Type Definitions

type DesignNode = GroupNode | FrameNode | VectorNode | TextNode | DesignComponent

type SupportedDesignNodeType = 'GROUP' | 'FRAME' | 'VECTOR' | 'TEXT' | 'INSTANCE'

interface TextNode {
  /** Human-friendly node name shown in Figma */
  name: string
  
  /** Identifies the node as a text node */
  type: 'TEXT'
  
  /** Whether the node is visible in the current document */
  visible: boolean
  
  /** Raw text characters contained in the node */
  characters: string
}

interface GroupNode {
  /** Human-friendly node name shown in Figma */
  name: string
  
  /** Identifies the node as a group */
  type: 'GROUP'
  
  /** Whether the node is visible in the current document */
  visible: boolean
  
  /** Ordered child nodes within this container */
  children: DesignNode[]
}

interface FrameNode {
  /** Human-friendly node name shown in Figma */
  name: string
  
  /** Identifies the node as a frame */
  type: 'FRAME'
  
  /** Whether the node is visible in the current document */
  visible: boolean
  
  /** Ordered child nodes within this container */
  children: DesignNode[]
}

interface VectorNode {
  /** Human-friendly node name shown in Figma */
  name: string
  
  /** Identifies the node as a vector */
  type: 'VECTOR'
  
  /** Whether the node is visible in the current document */
  visible: boolean
  
  /** Fill styles applied to the vector */
  fills: Fill[]
}

interface DesignComponent<T extends object = Record<string, ComponentPropertyValue>> {
  /** Human-friendly node name shown in Figma */
  name: string
  
  /** Identifies the node as a component instance */
  type: 'INSTANCE'
  
  /** Whether the node is visible in the current document */
  visible: boolean
  
  /** Ordered child nodes within this container */
  children: DesignNode[]
  
  /** Component property map keyed by property name */
  properties: T
  
  /** Reference to the main component definition, if linked */
  mainComponent?: {
    /** ID of the main component this instance is linked to */
    id: string
    
    /** Name of the main component this instance is linked to */
    name: string
  } | null
}

type ComponentPropertyValue = string | number | boolean | DesignComponent

interface Variable {
  /** Variable name without the var(--...) wrapper */
  name: string
  
  /** Default value for the variable if defined */
  value: string
}

interface Fill {
  /** Hex color string or variable reference describing the fill color */
  color: string | Variable
}

interface DevComponent<T extends object = Record<string, unknown>> {
  /** Component tag or name to render */
  name: string
  
  /** Props that should be passed to the component */
  props: T
  
  /** Ordered child components or string literals */
  children: (DevComponent | string)[]
}

interface Plugin {
  /** Human-readable name displayed in the UI */
  name: string
  
  /** Map of code block identifiers to configuration */
  code: CodeOptions
}

type CodeOptions = Partial<Record<BuiltInCodeBlock, CodeBlockOptions>> & Record<string, CodeBlockOptions>

type BuiltInCodeBlock = 'css' | 'js'

type CodeBlockOptions = (TransformOptions & {
  /** The title of the code block (e.g., 'SCSS') */
  title?: string
}) | false

type TransformOptions = {
  /** The language for syntax highlighting */
  lang?: SupportedLang
  
  /** Transform the generated CSS code */
  transform?: (params: TransformParams) => string
  
  /** Transform CSS variable references */
  transformVariable?: (params: TransformVariableParams) => string
  
  /** Transform pixel values to desired units */
  transformPx?: (params: TransformPxParams) => string
  
  /** Transform design components to dev components */
  transformComponent?: (params: TransformComponentParams) => DevComponent | string
}

type SupportedLang =
  | 'text'
  | 'tsx'
  | 'jsx'
  | 'ts'
  | 'js'
  | 'vue'
  | 'html'
  | 'css'
  | 'sass'
  | 'scss'
  | 'less'
  | 'stylus'
  | 'json'

type NodeQuery = RequireAtLeastOne<QueryableProperties> | ((node: DesignNode) => boolean)

type QueryableProperties = {
  type?: SupportedDesignNodeType | SupportedDesignNodeType[] | RegExp
  name?: string | string[] | RegExp
  visible?: boolean
}

type QueryType = 'child' | 'children' | 'one' | 'all'

const RAW_TAG_NAME = '__tempad_raw__'