Skip to content

AI-native design editor. Open-source Figma alternative.

10.3 KB
Raw Blame
import { compact, groupBy, isEqual, pick, uniq } from 'es-toolkit'

import type {
  ComponentPropertyDefinition,
  ComponentPropertyReference,
  SceneGraph,
  SceneNode
} from '@open-pencil/scene-graph'
import {
  componentPropertyDefinitions,
  createComponentPropertyId,
  exposableInstances,
  instanceExposureIssue
} from '@open-pencil/scene-graph/components'

import { isLayerRef, type LayerRef } from '../refs'

const PROPERTY_SYMBOL = Symbol.for('open-pencil.component-property')

/**
 * A component property, by its name in the component that holds it. Where it is placed picks
 * its type: `text` on a text layer makes a TEXT property, `visible` a BOOLEAN one, and `of` on an
 * instance an INSTANCE_SWAP one, whose default is the component that `of` names: by name, ID,
 * or the `ref()` that marks it.
 */
export interface ComponentProperty<
  T extends string | boolean | LayerRef = string | boolean | LayerRef
> {
  readonly [PROPERTY_SYMBOL]: true
  readonly name: string
  readonly defaultValue: T
}

export function isComponentProperty(value: unknown): value is ComponentProperty {
  return typeof value === 'object' && value !== null && PROPERTY_SYMBOL in value
}

/**
 * Bind a field to a property of the component it is drawn in, created on first use: on the
 * component set, for a variant, as Figma keeps them, or else on the component.
 */
export function property<T extends string | boolean | LayerRef>(
  name: string,
  defaultValue: T
): ComponentProperty<T> {
  return Object.freeze({ [PROPERTY_SYMBOL]: true as const, name, defaultValue })
}

/** The prop each property type binds, and the field it binds there. */
const BOUND_PROPS = {
  text: { type: 'TEXT', field: 'TEXT', node: 'TEXT' },
  visible: { type: 'BOOLEAN', field: 'VISIBLE', node: undefined },
  of: { type: 'INSTANCE_SWAP', field: 'INSTANCE_SWAP', node: 'INSTANCE' }
} as const satisfies Record<
  string,
  {
    type: ComponentPropertyDefinition['type']
    field: ComponentPropertyReference['field']
    node: SceneNode['type'] | undefined
  }
>

/** The component, or the set it is a variant of, that holds properties for layers under `parentId`. */
function propertyOwner(graph: SceneGraph, parentId: string): SceneNode {
  let node = graph.getNode(parentId)
  while (node) {
    if (node.type === 'INSTANCE') throw new Error('property() cannot be used inside an instance')
    if (node.type === 'COMPONENT_SET') return node
    if (node.type === 'COMPONENT') {
      const set = node.parentId ? graph.getNode(node.parentId) : undefined
      return set?.type === 'COMPONENT_SET' ? set : node
    }
    node = node.parentId ? graph.getNode(node.parentId) : undefined
  }
  throw new Error('property() must be inside a <Component> or <ComponentSet>')
}

/** The ID of the property with this name on `owner`, added if it has none. */
function ensureDefinition(
  graph: SceneGraph,
  owner: SceneNode,
  name: string,
  type: ComponentPropertyDefinition['type'],
  defaultValue: string,
  added: string[] | undefined
): string {
  const existing = owner.componentPropertyDefinitions.find((item) => item.name === name)
  if (existing) {
    if (existing.type !== type)
      throw new Error(`Component property ${name} is ${existing.type}, not ${type}`)
    if (existing.defaultValue !== defaultValue)
      throw new Error(
        `Component property ${name} has two defaults: ${existing.defaultValue} and ${defaultValue}`
      )
    return existing.id
  }
  const id = createComponentPropertyId()
  added?.push(id)
  graph.updateNode(owner.id, {
    componentPropertyDefinitions: [
      ...owner.componentPropertyDefinitions,
      { id, name, type, defaultValue }
    ]
  })
  return id
}

export interface BoundProperties {
  /** The props, with each property in place of its default. */
  props: Record<string, unknown>
  references: ComponentPropertyReference[]
}

/**
 * Bind the fields a layer's props place a `property()` in, creating the properties on its
 * component; `componentId` gives the ID a swap's default component has, and `added` takes the
 * IDs of the properties it creates.
 */
export function bindProperties(
  graph: SceneGraph,
  source: Record<string, unknown>,
  type: SceneNode['type'],
  parentId: string,
  componentId: ComponentLookup,
  added?: string[]
): BoundProperties {
  if (source.properties !== undefined && type !== 'INSTANCE')
    throw new Error('Only instances accept properties; bind a field to property() instead')
  const props = { ...source }
  const references: ComponentPropertyReference[] = []
  for (const [key, value] of Object.entries(source)) {
    if (!isComponentProperty(value)) continue
    if (!Object.hasOwn(BOUND_PROPS, key))
      throw new Error(`property() binds text, visible, or of, not ${key}`)
    const bound = BOUND_PROPS[key as keyof typeof BOUND_PROPS]
    if (bound.node && bound.node !== type)
      throw new Error(
        `property() in ${key} needs ${bound.node === 'TEXT' ? '<Text>' : '<Instance>'}`
      )
    const expected = bound.type === 'BOOLEAN' ? 'boolean' : 'string'
    const swapRef = bound.type === 'INSTANCE_SWAP' && isLayerRef(value.defaultValue)
    if (!swapRef && typeof value.defaultValue !== expected)
      throw new Error(`Component property ${value.name} in ${key} takes a ${expected} default`)
    let defaultValue = isLayerRef(value.defaultValue) ? '' : String(value.defaultValue)
    if (bound.type === 'INSTANCE_SWAP') {
      const id = componentId(isLayerRef(value.defaultValue) ? value.defaultValue : defaultValue)
      if (!id) throw new Error(`<Instance> component not found: ${defaultValue || 'ref()'}`)
      defaultValue = id
    }
    const owner = propertyOwner(graph, parentId)
    const propertyId = ensureDefinition(graph, owner, value.name, bound.type, defaultValue, added)
    references.push({ propertyId, field: bound.field })
    props[key] = value.defaultValue
  }
  return { props, references }
}

/** Match the nearest component scope, including definitions inherited from its set. */
export function componentPropertyScope(
  graph: SceneGraph,
  parentId: string
): readonly ComponentPropertyDefinition[] | undefined {
  let parent = graph.getNode(parentId)
  while (parent) {
    if (parent.type === 'INSTANCE') return componentPropertyDefinitions(graph, parent)
    if (parent.type === 'COMPONENT_SET') return parent.componentPropertyDefinitions
    if (parent.type === 'COMPONENT') {
      const set = parent.parentId ? graph.getNode(parent.parentId) : undefined
      return set?.type === 'COMPONENT_SET'
        ? [...set.componentPropertyDefinitions, ...parent.componentPropertyDefinitions]
        : parent.componentPropertyDefinitions
    }
    parent = parent.parentId ? graph.getNode(parent.parentId) : undefined
  }
  return undefined
}

/** Whether a variant has every value `wanted` names, by variant property. */
export function hasVariantValues(variant: SceneNode, wanted: Record<string, string>): boolean {
  return isEqual(pick(variant.componentPropertyValues, Object.keys(wanted)), wanted)
}

/** The ID of the component a name, ID, or `ref()` names, as `<Instance of>` finds it. */
export type ComponentLookup = (reference: string | LayerRef) => string | undefined

/** Mark an instance in a component's layers as exposed, under Figma's rules for exposing one. */
export function exposeInstance(graph: SceneGraph, instance: SceneNode): void {
  const issue = instanceExposureIssue(graph, instance)
  if (issue === 'not-in-component') throw new Error('exposed needs an <Instance> in a component')
  if (issue === 'not-primary')
    throw new Error('exposed needs an <Instance> in a component, not inside another instance')
  if (issue === 'nothing-to-expose')
    throw new Error(`${instance.name} has no properties or exposed instances to expose`)
  graph.updateNode(instance.id, { isExposedInstance: true })
}

/** The names an instance of `component` takes: its properties' and its exposed instances'. */
export function componentPropNames(graph: SceneGraph, component: SceneNode): string[] {
  return [
    ...(componentPropertyScope(graph, component.id) ?? []).map((definition) => definition.name),
    ...exposableInstances(graph, component.id)
      .filter((node) => node.isExposedInstance)
      .map((node) => node.name)
  ]
}

function parseVariantValues(name: string): Record<string, string> {
  const entries = compact(name.split(',').map((part) => part.trim()))
  const values: Record<string, string> = {}
  for (const entry of entries) {
    const [key = '', ...rest] = entry.split('=')
    const property = key.trim()
    const value = rest.join('=').trim()
    if (property && value) values[property] = value
  }
  return values
}

/** Variant properties a component set takes from its variants' names, such as `State=On`. */
export function inferComponentSetProperties(graph: SceneGraph, componentSetId: string): void {
  const componentSet = graph.getNode(componentSetId)
  if (componentSet?.type !== 'COMPONENT_SET') return
  const existingDefinitions = componentSet.componentPropertyDefinitions

  const variants = graph
    .getChildren(componentSetId)
    .filter((node) => node.type === 'COMPONENT')
    .map((variant) => ({ id: variant.id, values: parseVariantValues(variant.name) }))
  const defined = new Set(
    existingDefinitions
      .filter((definition) => definition.type === 'VARIANT')
      .map((definition) => definition.name)
  )
  // Each property's values in the order the variants first use them.
  const options = groupBy(
    variants.flatMap(({ values }) => Object.entries(values)),
    ([name]) => name
  )
  for (const name of Object.keys(options)) {
    const other = existingDefinitions.find(
      (definition) => definition.name === name && definition.type !== 'VARIANT'
    )
    if (other)
      throw new Error(
        `Variant property ${name} of ${componentSet.name} has the name of its ${other.type} property`
      )
  }
  const definitions: ComponentPropertyDefinition[] = Object.entries(options)
    .filter(([name]) => !defined.has(name))
    .map(([name, entries]) => {
      const variantOptions = uniq(entries.map(([, value]) => value))
      return {
        id: createComponentPropertyId(),
        name,
        type: 'VARIANT',
        defaultValue: variantOptions[0] ?? '',
        variantOptions
      }
    })

  for (const { id, values } of variants) graph.updateNode(id, { componentPropertyValues: values })
  graph.updateNode(componentSetId, {
    componentPropertyDefinitions: [...existingDefinitions, ...definitions]
  })
}