[Swift] Support nested/compound property mappings (parity with React)

[jackthmp]

Summary

React Code Connect supports nesting property helpers inside each other — figma.boolean wrapping figma.instance, figma.enum wrapping figma.enum, etc. This enables conditional rendering and compound property mappings. Swift Code Connect has no equivalent for any of these patterns, making it impossible to express common real-world component APIs.

Use Case 1: Conditionally omitting an optional instance

In React, you can conditionally include or omit an instance property (docs):

props: {
  icon: figma.boolean("Has Icon", {
    true: figma.instance("Icon"),
    false: undefined, // omitted from snippet
  }),
}

In Swift, @FigmaInstance with an optional type renders an empty value when no instance is selected, producing invalid code:

struct MyButton_CodeConnect: FigmaConnect {
  @FigmaInstance("Icon") var icon: Icon?

  var body: some View {
    MyButton("Submit", icon: icon) { }
  }
}

When no icon is selected:

MyButton("Submit", icon: ) { }
//                  ^^^^^ empty — not valid code

Expected: The parameter should either be omitted entirely (MyButton("Submit") { }) or render as nil.

This was discussed for React in #71 and #86, where figma.boolean wrapping was the solution.

Use Case 2: Combining multiple Figma properties into one code value

In React, you can nest figma.enum inside figma.enum to map combinations of Figma properties to a single code value (docs):

props: {
  type: figma.enum("Type", {
    "Secondary": figma.enum("Theme", {
      "Light": "secondary",
      "Dark": "secondary-dark",
    }),
    "Tertiary": figma.enum("Theme", {
      "Light": "tertiary",
      "Dark": "tertiary-dark",
    }),
  }),
}

In Swift, @FigmaEnum mappings are flat — each maps a single Figma property independently. There's no way to express "when Type=Secondary AND Theme=Dark, use .secondary(variation: .dark)":

// Forced to ignore Theme entirely:
@FigmaEnum("Type", mapping: [
  "Secondary": CookbookButton.Style.secondary(),
  "Tertiary": CookbookButton.Style.tertiary(),
])
var type: CookbookButton.Style = .primary()

Attempted Workaround: Variant-specific structs

The docs describe variant for mapping one Figma component to different code components (e.g. PrimaryButton vs DangerButton). We attempted using multiple FigmaConnect structs with the same component type but different variant restrictions to work around both use cases above.

This does not work — Figma only ever displays one of the snippets, regardless of which variant is active. The variant property appears to only function when each struct declares a different component type, as shown in the docs.

Proposal

Support nested/compound property mappings in Swift, bringing parity with React's composable helpers.

For optional instances (Use Case 1)

Option A: Automatically omit the parameter when a @FigmaInstance with an optional type resolves to nothing — consistent with how falsy props are omitted in React.

Option B: Add hideDefault to @FigmaInstance, consistent with the existing @FigmaEnum API:

@FigmaInstance("Icon", hideDefault: true) var icon: Icon?

Option C: Allow @FigmaBoolean to wrap @FigmaInstance:

@FigmaBoolean("Has Icon", mapping: [
  true: FigmaInstance("Icon"),
  false: nil,
])
var icon: Icon?

For compound property mappings (Use Case 2)

Allow nesting @FigmaEnum (or similar) inside @FigmaEnum mapping values:

@FigmaEnum("Type", mapping: [
  "Secondary": FigmaEnum("Theme", mapping: [
    "Light": CookbookButton.Style.secondary(),
    "Dark": CookbookButton.Style.secondary(variation: .dark),
  ]),
  "Tertiary": FigmaEnum("Theme", mapping: [
    "Light": CookbookButton.Style.tertiary(),
    "Dark": CookbookButton.Style.tertiary(variation: .dark),
  ]),
])
var type: CookbookButton.Style = .primary()

Environment

• Code Connect version: 1.4.1
• Platform: Swift (SwiftUI)

[slees-figma]

Hey @jackthmp, thanks for the detailed report. These are indeed known gaps in the Swift parser that make it impossible to achieve some representations of Swift code as you've pointed out.

Sharing in case this is of interest - we're working on a framework-agnostic setup for Code Connect, which while not written in Swift, allows much greater flexibility to represent any code, and could address your desired outputs today. Docs: https://developers.figma.com/docs/code-connect/no-parser/

Some examples of how this might look:

Conditionally omitting an optional instance:

  // url=https://www.figma.com/...
  // component=MyButton
  const figma = require('figma')
  const instance = figma.selectedInstance

  const label = instance.getString('Label')
  const hasIcon = instance.getBoolean('Has Icon')
  const iconHandle = hasIcon ? instance.getInstanceSwap('Icon') : null
  const iconSnippet = iconHandle ? iconHandle.executeTemplate().example : null

  export default {
    example: figma.code`MyButton("${label}"${iconSnippet ? figma.code`, icon: ${iconSnippet}` : ''}) { }`,
    imports: [],
    id: 'my-button',
  }

Compound property mappings:

  // url=https://www.figma.com/...
  // component=MyButton
  const figma = require('figma')
  const instance = figma.selectedInstance

  const type = instance.getPropertyValue('Type')
  const theme = instance.getPropertyValue('Theme')

  // Freely combine any Figma properties into a single code value
  const variant =
    type === 'Secondary' && theme === 'Dark'  ? '.secondary(variation: .dark)'  :
    type === 'Secondary' && theme === 'Light' ? '.secondary(variation: .light)' :
    '.primary'

  export default {
    example: figma.swift`MyButton(variant: ${variant})`,
    imports: [],
    id: 'my-button',
  }

Re. variants, as the template approach allows writing arbitrary code, there isn't a need anymore to use variants / variant restrictions (which have always been a workaround for not being able to use conditional code)