@figma/code-connect 1.4.8 → 1.4.9

package/figma-types-no-require.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Type definitions for the `figma` module available in Code Connect template files
+ * (.figma.ts) — variant WITHOUT the global `require('figma')` shim.
+ *
+ * Use this instead of `@figma/code-connect/figma-types` if your project has
+ * @types/node installed. The default entry declares a global `require`, which
+ * overrides Node's `NodeRequire` type and breaks `require.resolve` (and similar)
+ * elsewhere in your project. This variant omits that declaration so the figma
+ * types can be added to your main tsconfig.json without a conflict. It types the
+ * recommended `import figma from 'figma'` syntax; `require('figma')` is typed by
+ * @types/node's own `require`.
+ *   { "compilerOptions": { "types": ["@figma/code-connect/figma-types-no-require"] } }
+ */
+declare module 'figma' {
+  export type CodeSection = { type: 'CODE'; code: string; nestedImports?: string[] }
+  export type InstanceSection = {
+    type: 'INSTANCE'
+    guid: string
+    symbolId: string
+    resultSections?: ResultSection[]
+    nestedImports?: string[]
+  }
+  export type SlotSection = { type: 'SLOT'; guid?: string; propertyName: string }
+  export type ErrorSection = { type: 'ERROR'; message: string; errorObject?: unknown }
+  export type ResultSection = CodeSection | InstanceSection | SlotSection | ErrorSection
+
+  export interface TemplateStringResult {
+    sections: ResultSection[]
+    language: string
+    type: 'SECTIONS'
+  }
+
+  export interface SelectorOptions {
+    path?: string[]
+    traverseInstances?: boolean
+  }
+
+  export type SlotResult = ResultSection[] & {
+    /** Connected instances directly in the slot (shallow). */
+    readonly connectedInstances: InstanceHandle[]
+  }
+
+  type ObjectValue = Record<string, FCCValue>
+
+  export type FCCValue =
+    | string
+    | number
+    | boolean
+    | undefined
+    | { $value: string; $type: 'jsx-element' }
+    | { $value: string; $type: 'function' }
+    | { $value: string; $type: 'identifier' }
+    | { $value: ObjectValue; $type: 'object' }
+    | { $value: string; $type: 'template-string' }
+    | { $value: string; $type: 'react-component' }
+    | { $value: FCCValue[]; $type: 'array' }
+
+  export interface TextHandle {
+    readonly type: 'TEXT'
+    readonly name: string
+    readonly textContent: string
+    readonly __containingSlotName__?: string
+    __render__(): string
+  }
+
+  export interface TemplateMetadata {
+    nestable?: boolean
+    props?: Record<string, unknown>
+    __props: Record<string, unknown>
+    [key: string]: unknown
+  }
+
+  export interface ErrorHandle {
+    readonly type: 'ERROR'
+    readonly __containingSlotName__?: string
+    __render__(): ResultSection[]
+    executeTemplate(): {
+      example: ResultSection[]
+      metadata?: TemplateMetadata
+    }
+  }
+
+  export interface InstanceHandle {
+    readonly type: 'INSTANCE'
+    readonly symbolId: string
+    readonly name: string
+    readonly children: (InstanceHandle | TextHandle | ErrorHandle)[]
+    readonly properties: Record<string, { value: string | boolean }>
+    readonly path?: string[]
+    readonly slots?: Record<string, { guid: string }>
+    /** Internal: the property name of the slot this node is content of, if any. */
+    readonly __containingSlotName__?: string
+
+    codeConnectId(): string | null
+
+    __find__(name: string): InstanceHandle | ErrorHandle | null
+    __findChildWithCriteria__(criteria: {
+      type: 'INSTANCE' | 'TEXT'
+      name: string
+    }): InstanceHandle | TextHandle | ErrorHandle | null
+    __getPropertyValue__(name: string): string | boolean | ErrorHandle
+    __render__(): ResultSection[]
+    __getProps__(): ResultSection[] | Record<string, unknown> | undefined
+    __renderWithFn__(
+      renderFn: (props: Record<string, unknown>) => TemplateStringResult,
+    ): ResultSection[] | ErrorHandle | undefined
+
+    getString(propName: string): string
+    getBoolean(propName: string): boolean
+    getBoolean<O extends Record<string, unknown>>(
+      propName: string,
+      options: O,
+    ): EnumOptionsValues<O>
+    getEnum<O extends Record<string, unknown>>(
+      propName: string,
+      options: O,
+    ): EnumOptionsValues<O> | undefined
+    getInstanceSwap(propName: string): InstanceHandle | ErrorHandle | undefined
+    getSlot(propName: string): SlotResult | undefined
+    hasCodeConnect(): boolean
+    getPropertyValue(name: string): string | boolean | ErrorHandle
+    findInstance(layerName: string, opts?: SelectorOptions): InstanceHandle | ErrorHandle
+    findText(layerName: string, opts?: SelectorOptions): TextHandle | ErrorHandle
+    findConnectedInstance(
+      codeConnectId: string,
+      opts?: SelectorOptions,
+    ): InstanceHandle | ErrorHandle | null
+    findConnectedInstances(
+      selectorFn: (node: InstanceHandle) => boolean,
+      opts?: SelectorOptions,
+    ): (InstanceHandle | ErrorHandle)[]
+    findLayers(
+      selectorFn: (node: InstanceHandle | TextHandle) => boolean,
+      opts?: SelectorOptions,
+    ): (InstanceHandle | TextHandle | ErrorHandle)[]
+    executeTemplate(): {
+      example: ResultSection[]
+      metadata?: TemplateMetadata
+    }
+  }
+
+  export type LayerHandle = InstanceHandle | TextHandle | ErrorHandle
+
+  export type EnumOptionsValues<O extends Record<string, unknown>> = O[keyof O]
+
+  export interface FigmaProperties {
+    string(propName: string): string
+    boolean(propName: string): boolean
+    boolean<O extends Record<string, unknown>>(propName: string, options: O): EnumOptionsValues<O>
+    enum<O extends Record<string, unknown>>(
+      propName: string,
+      options: O,
+    ): EnumOptionsValues<O> | undefined
+    // In error cases the implementation may return string (from TextHandle.__render__)
+    instance(propName: string): ResultSection[] | string | undefined
+    __instance__(
+      propName: string,
+    ): InstanceHandle | TextHandle | ErrorHandle | ResultSection[] | undefined
+    slot(propName: string): SlotResult | undefined
+    children(layerNames: string[]): ResultSection[]
+  }
+
+  export type TemplateLiteral = (
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ) => TemplateStringResult
+
+  export interface Figma {
+    /** Per-entry data from a .figma.batch.json file. Available in batch templates. */
+    readonly batch: Record<string, any>
+
+    /** The currently selected component instance */
+    readonly selectedInstance: InstanceHandle & { readonly __properties__: FigmaProperties }
+    /** Alias for selectedInstance */
+    readonly currentLayer: InstanceHandle & { readonly __properties__: FigmaProperties }
+    /** Access component properties via the properties API */
+    readonly properties: FigmaProperties
+
+    /** Template literal tag for custom/plaintext code */
+    code: TemplateLiteral
+    /** Template literal tag for JSX/TSX code */
+    tsx: TemplateLiteral
+    /** Template literal tag for HTML code */
+    html: TemplateLiteral
+    /** Template literal tag for Swift code */
+    swift: TemplateLiteral
+    /** Template literal tag for Kotlin/Compose code */
+    kotlin: TemplateLiteral
+
+    /** Return a raw value (not rendered as a template string) */
+    value(raw: unknown, preview?: unknown): { type: string; value: unknown; preview: unknown }
+
+    helpers: {
+      react: {
+        renderProp(name: string, prop: FCCValue | ResultSection[]): TemplateStringResult | string
+        renderChildren(
+          prop: FCCValue | ResultSection[],
+        ): ResultSection[] | string | number | boolean | TemplateStringResult
+        renderPropValue(
+          prop: FCCValue | ResultSection[],
+        ): string | number | boolean | ResultSection[]
+        stringifyObject(obj: unknown): string
+        jsxElement(value: string): { $value: string; $type: 'jsx-element' }
+        function(value: string): { $value: string; $type: 'function' }
+        identifier(value: string): { $value: string; $type: 'identifier' }
+        object(value: ObjectValue): { $value: ObjectValue; $type: 'object' }
+        templateString(value: string): { $value: string; $type: 'template-string' }
+        reactComponent(value: string): { $value: string; $type: 'react-component' }
+        array(value: FCCValue[]): { $value: FCCValue[]; $type: 'array' }
+        isReactComponentArray(prop: unknown): boolean
+      }
+      swift: {
+        renderChildren(
+          children: ResultSection[] | string | undefined,
+          prefix: string,
+        ): ResultSection[]
+      }
+      kotlin: {
+        renderChildren(
+          children: ResultSection[] | string | undefined,
+          prefix: string,
+        ): ResultSection[]
+      }
+    }
+  }
+
+  const figma: Figma
+  export = figma
+}

package/figma-types.d.ts

@@ -32,6 +32,11 @@ declare module 'figma' {
     traverseInstances?: boolean
   }
 
+  export type SlotResult = ResultSection[] & {
+    /** Connected instances directly in the slot (shallow). */
+    readonly connectedInstances: InstanceHandle[]
+  }
+
   type ObjectValue = Record<string, FCCValue>
 
   export type FCCValue =
@@ -51,6 +56,7 @@ declare module 'figma' {
     readonly type: 'TEXT'
     readonly name: string
     readonly textContent: string
+    readonly __containingSlotName__?: string
     __render__(): string
   }
 
@@ -63,6 +69,7 @@ declare module 'figma' {
 
   export interface ErrorHandle {
     readonly type: 'ERROR'
+    readonly __containingSlotName__?: string
     __render__(): ResultSection[]
     executeTemplate(): {
       example: ResultSection[]
@@ -78,6 +85,8 @@ declare module 'figma' {
     readonly properties: Record<string, { value: string | boolean }>
     readonly path?: string[]
     readonly slots?: Record<string, { guid: string }>
+    /** Internal: the property name of the slot this node is content of, if any. */
+    readonly __containingSlotName__?: string
 
     codeConnectId(): string | null
 
@@ -104,7 +113,7 @@ declare module 'figma' {
       options: O,
     ): EnumOptionsValues<O> | undefined
     getInstanceSwap(propName: string): InstanceHandle | ErrorHandle | undefined
-    getSlot(propName: string): ResultSection[] | undefined
+    getSlot(propName: string): SlotResult | undefined
     hasCodeConnect(): boolean
     getPropertyValue(name: string): string | boolean | ErrorHandle
     findInstance(layerName: string, opts?: SelectorOptions): InstanceHandle | ErrorHandle
@@ -144,7 +153,7 @@ declare module 'figma' {
     __instance__(
       propName: string,
     ): InstanceHandle | TextHandle | ErrorHandle | ResultSection[] | undefined
-    slot(propName: string): ResultSection[] | undefined
+    slot(propName: string): SlotResult | undefined
     children(layerNames: string[]): ResultSection[]
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figma/code-connect",
-  "version": "1.4.8",
+  "version": "1.4.9",
   "description": "A tool for connecting your design system components in code with your design system in Figma",
   "keywords": [],
   "author": "Figma",
@@ -25,6 +25,9 @@
     },
     "./figma-types": {
       "types": "./figma-types.d.ts"
+    },
+    "./figma-types-no-require": {
+      "types": "./figma-types-no-require.d.ts"
     }
   },
   "repository": {
@@ -37,7 +40,8 @@
   },
   "files": [
     "dist/**/*",
-    "figma-types.d.ts"
+    "figma-types.d.ts",
+    "figma-types-no-require.d.ts"
   ],
   "engines": {
     "node": ">=18"
@@ -83,7 +87,7 @@
     "@types/jest": "^29.5.13",
     "@types/jsdom": "^21.1.7",
     "@types/lodash": "4.17.20",
-    "@types/node": "22.17.2",
+    "@types/node": "22.19.21",
     "@types/prettier": "2.7.3",
     "@types/prompts": "^2.4.9",
     "@types/react": "18.3.27",