|
| 1 | +/** |
| 2 | + * Type definitions for the `figma` module available in Code Connect template files |
| 3 | + * (.figma.ts). |
| 4 | + * Usage: add to your tsconfig.json: |
| 5 | + * { "compilerOptions": { "types": ["@figma/code-connect/figma-types"] } } |
| 6 | + */ |
| 7 | +// Declare require() for the 'figma' module so that template files can use |
| 8 | +// `const figma = require('figma')` without needing @types/node installed. |
| 9 | +declare function require(module: 'figma'): typeof import('figma') |
| 10 | +declare function require(module: string): any |
| 11 | +declare module 'figma' { |
| 12 | + export type CodeSection = { type: 'CODE'; code: string; nestedImports?: string[] } |
| 13 | + export type InstanceSection = { |
| 14 | + type: 'INSTANCE' |
| 15 | + guid: string |
| 16 | + symbolId: string |
| 17 | + resultSections?: ResultSection[] |
| 18 | + nestedImports?: string[] |
| 19 | + } |
| 20 | + export type SlotSection = { type: 'SLOT'; guid?: string; propertyName: string } |
| 21 | + export type ErrorSection = { type: 'ERROR'; message: string; errorObject?: unknown } |
| 22 | + export type ResultSection = CodeSection | InstanceSection | SlotSection | ErrorSection |
| 23 | + |
| 24 | + export interface TemplateStringResult { |
| 25 | + sections: ResultSection[] |
| 26 | + language: string |
| 27 | + type: 'SECTIONS' |
| 28 | + } |
| 29 | + |
| 30 | + export interface SelectorOptions { |
| 31 | + path?: string[] |
| 32 | + traverseInstances?: boolean |
| 33 | + } |
| 34 | + |
| 35 | + type ObjectValue = Record<string, FCCValue> |
| 36 | + |
| 37 | + export type FCCValue = |
| 38 | + | string |
| 39 | + | number |
| 40 | + | boolean |
| 41 | + | undefined |
| 42 | + | { $value: string; $type: 'jsx-element' } |
| 43 | + | { $value: string; $type: 'function' } |
| 44 | + | { $value: string; $type: 'identifier' } |
| 45 | + | { $value: ObjectValue; $type: 'object' } |
| 46 | + | { $value: string; $type: 'template-string' } |
| 47 | + | { $value: string; $type: 'react-component' } |
| 48 | + | { $value: FCCValue[]; $type: 'array' } |
| 49 | + |
| 50 | + export interface TextHandle { |
| 51 | + readonly type: 'TEXT' |
| 52 | + readonly name: string |
| 53 | + __render__(): string |
| 54 | + } |
| 55 | + |
| 56 | + export interface TemplateMetadata { |
| 57 | + nestable?: boolean |
| 58 | + props?: Record<string, unknown> |
| 59 | + __props: Record<string, unknown> |
| 60 | + [key: string]: unknown |
| 61 | + } |
| 62 | + |
| 63 | + export interface ErrorHandle { |
| 64 | + readonly type: 'ERROR' |
| 65 | + __render__(): ResultSection[] |
| 66 | + executeTemplate(): { |
| 67 | + example: ResultSection[] |
| 68 | + metadata?: TemplateMetadata |
| 69 | + } |
| 70 | + } |
| 71 | + |
| 72 | + export interface InstanceHandle { |
| 73 | + readonly type: 'INSTANCE' |
| 74 | + readonly symbolId: string |
| 75 | + readonly name: string |
| 76 | + readonly children: (InstanceHandle | TextHandle | ErrorHandle)[] |
| 77 | + readonly properties: Record<string, { value: string | boolean }> |
| 78 | + readonly path?: string[] |
| 79 | + readonly slots?: Record<string, { guid: string }> |
| 80 | + |
| 81 | + codeConnectId(): string | null |
| 82 | + |
| 83 | + __find__(name: string): InstanceHandle | ErrorHandle | null |
| 84 | + __findChildWithCriteria__(criteria: { |
| 85 | + type: 'INSTANCE' | 'TEXT' |
| 86 | + name: string |
| 87 | + }): InstanceHandle | TextHandle | ErrorHandle | null |
| 88 | + __getPropertyValue__(name: string): string | boolean | ErrorHandle |
| 89 | + __render__(): ResultSection[] |
| 90 | + __getProps__(): ResultSection[] | Record<string, unknown> | undefined |
| 91 | + __renderWithFn__( |
| 92 | + renderFn: (props: Record<string, unknown>) => TemplateStringResult, |
| 93 | + ): ResultSection[] | ErrorHandle | undefined |
| 94 | + |
| 95 | + getString(propName: string): string |
| 96 | + getBoolean(propName: string): boolean |
| 97 | + getBoolean<O extends Record<string, unknown>>( |
| 98 | + propName: string, |
| 99 | + options: O, |
| 100 | + ): EnumOptionsValues<O> |
| 101 | + getEnum<O extends Record<string, unknown>>( |
| 102 | + propName: string, |
| 103 | + options: O, |
| 104 | + ): EnumOptionsValues<O> | undefined |
| 105 | + getInstanceSwap(propName: string): InstanceHandle | undefined |
| 106 | + getSlot(propName: string): ResultSection[] | undefined |
| 107 | + hasCodeConnect(): boolean |
| 108 | + getPropertyValue(name: string): string | boolean | ErrorHandle |
| 109 | + findInstance(layerName: string, opts?: SelectorOptions): InstanceHandle | ErrorHandle |
| 110 | + findText(layerName: string, opts?: SelectorOptions): TextHandle | ErrorHandle |
| 111 | + findConnectedInstance( |
| 112 | + codeConnectId: string, |
| 113 | + opts?: SelectorOptions, |
| 114 | + ): InstanceHandle | ErrorHandle | null |
| 115 | + findConnectedInstances( |
| 116 | + selectorFn: (node: InstanceHandle) => boolean, |
| 117 | + opts?: SelectorOptions, |
| 118 | + ): (InstanceHandle | ErrorHandle)[] |
| 119 | + findLayers( |
| 120 | + selectorFn: (node: InstanceHandle) => boolean, |
| 121 | + opts?: SelectorOptions, |
| 122 | + ): (InstanceHandle | TextHandle | ErrorHandle)[] |
| 123 | + executeTemplate(): { |
| 124 | + example: ResultSection[] |
| 125 | + metadata?: TemplateMetadata |
| 126 | + } |
| 127 | + } |
| 128 | + |
| 129 | + export type LayerHandle = InstanceHandle | TextHandle | ErrorHandle |
| 130 | + |
| 131 | + export type EnumOptionsValues<O extends Record<string, unknown>> = O[keyof O] |
| 132 | + |
| 133 | + export interface FigmaProperties { |
| 134 | + string(propName: string): string |
| 135 | + boolean(propName: string): boolean |
| 136 | + boolean<O extends Record<string, unknown>>(propName: string, options: O): EnumOptionsValues<O> |
| 137 | + enum<O extends Record<string, unknown>>( |
| 138 | + propName: string, |
| 139 | + options: O, |
| 140 | + ): EnumOptionsValues<O> | undefined |
| 141 | + // In error cases the implementation may return string (from TextHandle.__render__) |
| 142 | + instance(propName: string): ResultSection[] | string | undefined |
| 143 | + __instance__( |
| 144 | + propName: string, |
| 145 | + ): InstanceHandle | TextHandle | ErrorHandle | ResultSection[] | undefined |
| 146 | + slot(propName: string): ResultSection[] | undefined |
| 147 | + children(layerNames: string[]): ResultSection[] |
| 148 | + } |
| 149 | + |
| 150 | + export type TemplateLiteral = ( |
| 151 | + strings: TemplateStringsArray, |
| 152 | + ...values: unknown[] |
| 153 | + ) => TemplateStringResult |
| 154 | + |
| 155 | + export interface Figma { |
| 156 | + /** The currently selected component instance */ |
| 157 | + readonly selectedInstance: InstanceHandle & { readonly __properties__: FigmaProperties } |
| 158 | + /** Alias for selectedInstance */ |
| 159 | + readonly currentLayer: InstanceHandle & { readonly __properties__: FigmaProperties } |
| 160 | + /** Access component properties via the properties API */ |
| 161 | + readonly properties: FigmaProperties |
| 162 | + |
| 163 | + /** Template literal tag for custom/plaintext code */ |
| 164 | + code: TemplateLiteral |
| 165 | + /** Template literal tag for JSX/TSX code */ |
| 166 | + tsx: TemplateLiteral |
| 167 | + /** Template literal tag for HTML code */ |
| 168 | + html: TemplateLiteral |
| 169 | + /** Template literal tag for Swift code */ |
| 170 | + swift: TemplateLiteral |
| 171 | + /** Template literal tag for Kotlin/Compose code */ |
| 172 | + kotlin: TemplateLiteral |
| 173 | + |
| 174 | + /** Return a raw value (not rendered as a template string) */ |
| 175 | + value(raw: unknown, preview?: unknown): { type: string; value: unknown; preview: unknown } |
| 176 | + |
| 177 | + helpers: { |
| 178 | + react: { |
| 179 | + renderProp(name: string, prop: FCCValue | ResultSection[]): TemplateStringResult | string |
| 180 | + renderChildren( |
| 181 | + prop: FCCValue | ResultSection[], |
| 182 | + ): ResultSection[] | string | number | boolean | TemplateStringResult |
| 183 | + renderPropValue( |
| 184 | + prop: FCCValue | ResultSection[], |
| 185 | + ): string | number | boolean | ResultSection[] |
| 186 | + stringifyObject(obj: unknown): string |
| 187 | + jsxElement(value: string): { $value: string; $type: 'jsx-element' } |
| 188 | + function(value: string): { $value: string; $type: 'function' } |
| 189 | + identifier(value: string): { $value: string; $type: 'identifier' } |
| 190 | + object(value: ObjectValue): { $value: ObjectValue; $type: 'object' } |
| 191 | + templateString(value: string): { $value: string; $type: 'template-string' } |
| 192 | + reactComponent(value: string): { $value: string; $type: 'react-component' } |
| 193 | + array(value: FCCValue[]): { $value: FCCValue[]; $type: 'array' } |
| 194 | + isReactComponentArray(prop: unknown): boolean |
| 195 | + } |
| 196 | + swift: { |
| 197 | + renderChildren(children: ResultSection[], prefix: string): ResultSection[] |
| 198 | + } |
| 199 | + kotlin: { |
| 200 | + renderChildren(children: ResultSection[], prefix: string): ResultSection[] |
| 201 | + } |
| 202 | + } |
| 203 | + } |
| 204 | + |
| 205 | + const figma: Figma |
| 206 | + export = figma |
| 207 | +} |
0 commit comments