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