figma.template.d.ts

// https://github.com/figma/code-connect/issues/261
// This type is generated by referencing https://www.figma.com/code-connect-docs/template-v2-api/

declare module "figma" {
  interface InstanceHandle {
    /**
     * Object containing all properties of the instance.
     */
    properties: Record<string, string | boolean | InstanceHandle>;
    /*
     * Gets a boolean property value.
     * Optional mapping object can transform the boolean value to any other type.
     */
    getBoolean(propName: string, options?: Record<string, any>): boolean | any;
    /*
     * Gets a string property value.
     */
    getString(propName: string): string;
    /*
     * Gets an enum property value with optional value mapping.
     * The options object maps enum values to desired output values.
     */
    getEnum(propName: string, options: Record<string, any>): any;
    /*
     * Gets an instance property value.
     * Returns the instance handle for the swapped instance.
     */
    getInstanceSwap(propName: string): InstanceHandle;
    /*
     * Gets a raw property value.
     */
    getPropertyValue(propName: string): string | boolean;
    /*
     * Renders the instance and returns both the rendered sections and metadata.
     */
    executeTemplate(): { example: ResultSection[]; metadata: Metadata };
    /*
     * Returns whether the instance has Code Connect.
     */
    hasCodeConnect(): boolean;
    /*
     * Returns the Code Connect ID of the instance, if it exists.
     */
    codeConnectId(): string | null;
    /*
     * Finds a text layer by name.
     * Optional selector options for path matching and traversal behavior.
     */
    findText(
      layerName: string,
      opts?: SelectorOptions
    ): TextHandle | ErrorHandle;
    /*
     * Finds an child instance layer by name.
     * Optional selector options for path matching and traversal behavior.
     */
    findInstance(
      layerName: string,
      opts?: SelectorOptions
    ): InstanceHandle | ErrorHandle;
    /*
     * Finds a child instance by its Code Connect ID.
     * Optional selector options for path matching and traversal behavior.
     */
    findConnectedInstance(
      codeConnectId: string,
      opts?: SelectorOptions
    ): InstanceHandle | ErrorHandle;
    /*
     * Finds all child instances that match the selector function.
     * Optional selector options for path matching and traversal behavior.
     */
    findConnectedInstances(
      selectorFn: (node: InstanceHandle) => boolean,
      opts?: SelectorOptions
    ): InstanceHandle[];
    /*
     * Finds all layers (instances or text) that match the selector function.
     * Optional selector options for path matching and traversal behavior.
     */
    findLayers(
      selectorFn: (node: InstanceHandle | TextHandle) => boolean,
      opts?: SelectorOptions
    ): (InstanceHandle | TextHandle)[];
  }

  interface TextHandle {
    /**
     * The text content of the text layer.
     */
    textContent: string;
  }

  /** Options for finding layers */
  interface SelectorOptions {
    /** List of parent layer names that matches the layer hierarchy */
    path?: string[];
    /** Whether to search through nested instances */
    traverseInstances?: boolean;
  }

  export interface Template {
    example: string;
    id?: string;
    metadata?: Metadata;
  }

  /** Metadata that can be included in template exports */
  interface Metadata {
    /**
     * Controls how nested instances are rendered in the Code Connect panel:
     * - true: The instance's code will be rendered inline within its parent
     * - false: The instance will be shown as a clickable pill that expands when clicked
     *
     * For example:
     * - Set to true for small components like icons that make sense inline
     * - Set to false for complex components that should be viewed separately
     */
    nestable?: boolean;

    /** Props which can be consumed in a parent instance */
    props?: Record<string, any>;
  }

  /**
   * Represents a section of code that will be rendered verbatim in the Code Connect panel
   */
  type CodeSection = {
    type: "CODE";
    code: string;
  };

  /**
   * Represents a child instance that will be rendered either inline or as a pill
   * depending on the nestable property
   */
  type InstanceSection = {
    type: "INSTANCE";
    /** The guid of the instance layer */
    guid: string;
    /** The guid of the backing component */
    symbolId: string;
  };

  /** Represents an error that will be displayed in the Code Connect panel */
  type ErrorSection = {
    type: "ERROR";
    message: string;
    errorObject?: ResultError;
  };

  /** The possible sections that can appear in the Code Connect panel */
  type ResultSection = CodeSection | InstanceSection | ErrorSection;

  /** Error when a property is not found */
  type PropertyNotFoundErrorObject = {
    type: "PROPERTY_NOT_FOUND";
    propertyName: string;
  };

  /** Error when a child layer is not found */
  type ChildLayerNotFoundErrorObject = {
    type: "CHILD_LAYER_NOT_FOUND";
    layerName: string;
  };

  /** Error when a property type doesn't match expected type */
  type PropertyTypeMismatchErrorObject = {
    type: "PROPERTY_TYPE_MISMATCH";
    propertyName: string;
    expectedType: string;
  };

  /** Error during template execution */
  type TemplateExecutionErrorObject = {
    type: "TEMPLATE_EXECUTION_ERROR";
  };

  /** All possible error types */
  type ResultError =
    | PropertyNotFoundErrorObject
    | PropertyTypeMismatchErrorObject
    | ChildLayerNotFoundErrorObject
    | TemplateExecutionErrorObject;

  export const selectedInstance: InstanceHandle;
  export const code: (codes: TemplateStringsArray, ...values: any[]) => string;
}