Skip to content

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

12.0 KB
Raw Blame
import { uniq } from 'es-toolkit/array'
import { isEmptyObject } from 'es-toolkit/predicate'

import {
  TEXT_BINDABLE_FIELDS,
  type SceneGraph,
  type SceneNode,
  type TextBindableField,
  type Variable,
  type VariableType
} from '@open-pencil/scene-graph'
import { recordInstanceOverride } from '@open-pencil/scene-graph/instances'
import {
  effectBindableProperties,
  effectBindingField,
  effectBindingTarget,
  effectBindingVariableType,
  independentCornerChanges,
  paintBindingTarget
} from '@open-pencil/scene-graph/variables'

import type { FigmaEffect, FigmaEffectBindings } from '#core/figma-api/effects'
import type { FigmaPaint } from '#core/figma-api/paints'
import { reconcileVariableLayouts } from '#core/layout/variables'

import { variableAlias, type FigmaVariableAlias } from './values'

/**
 * The fields Figma's `setBoundVariable` takes, in the order its message lists them, with the
 * document field each one binds. Text style fields bind every character's style instead.
 */
const NODE_FIELDS = {
  height: 'height',
  width: 'width',
  characters: 'text',
  itemSpacing: 'itemSpacing',
  paddingLeft: 'paddingLeft',
  paddingRight: 'paddingRight',
  paddingTop: 'paddingTop',
  paddingBottom: 'paddingBottom',
  visible: 'visible',
  cornerRadius: 'cornerRadius',
  topLeftRadius: 'topLeftRadius',
  topRightRadius: 'topRightRadius',
  bottomLeftRadius: 'bottomLeftRadius',
  bottomRightRadius: 'bottomRightRadius',
  strokeWeight: 'strokeWeight',
  strokeTopWeight: 'borderTopWeight',
  strokeBottomWeight: 'borderBottomWeight',
  strokeLeftWeight: 'borderLeftWeight',
  strokeRightWeight: 'borderRightWeight',
  minWidth: 'minWidth',
  maxWidth: 'maxWidth',
  minHeight: 'minHeight',
  maxHeight: 'maxHeight',
  counterAxisSpacing: 'counterAxisSpacing',
  opacity: 'opacity',
  gridRowGap: 'gridRowGap',
  gridColumnGap: 'gridColumnGap'
} as const

export type FigmaBindableNodeField = keyof typeof NODE_FIELDS
export type FigmaBindableField = FigmaBindableNodeField | TextBindableField

const FIELD_NAMES = [...Object.keys(NODE_FIELDS), ...TEXT_BINDABLE_FIELDS]

const CORNER_FIELDS = [
  'topLeftRadius',
  'topRightRadius',
  'bottomLeftRadius',
  'bottomRightRadius'
] as const

/** Fields only an auto layout or grid container has; elsewhere Figma ignores the binding. */
const CONTAINER_FIELDS: ReadonlySet<string> = new Set([
  'itemSpacing',
  'paddingLeft',
  'paddingRight',
  'paddingTop',
  'paddingBottom',
  'counterAxisSpacing',
  'gridRowGap',
  'gridColumnGap'
])

const CONTAINER_TYPES: ReadonlySet<string> = new Set([
  'FRAME',
  'COMPONENT',
  'COMPONENT_SET',
  'INSTANCE'
])

/** The variable type each field takes from `setBoundVariable`, which is stricter than the panel. */
function fieldType(field: FigmaBindableField): VariableType {
  if (field === 'characters' || field === 'fontFamily' || field === 'fontStyle') return 'STRING'
  if (field === 'visible') return 'BOOLEAN'
  return 'FLOAT'
}

export function isTextBindableField(field: string): field is TextBindableField {
  return (TEXT_BINDABLE_FIELDS as readonly string[]).includes(field)
}

/** Figma's checks on a field name, in the order it makes them. */
export function assertBindableField(field: unknown): FigmaBindableField {
  if (field === 'fills' || field === 'strokes') {
    throw new Error(
      'in setBoundVariable: fills and strokes variable bindings must be set on paints directly'
    )
  }
  if (typeof field !== 'string' || !FIELD_NAMES.includes(field)) {
    throw new Error(
      'in setBoundVariable: Property "field" failed validation: Invalid option: expected one of ' +
        FIELD_NAMES.map((name) => `"${name}"`).join('|')
    )
  }
  return field as FigmaBindableField
}

/** The variable a `setBoundVariable` call names, by object or by id, checked against the field. */
export function bindingVariable(
  graph: SceneGraph,
  method: string,
  field: FigmaBindableField,
  variable: { readonly id: string } | string
): Variable {
  const id = typeof variable === 'string' ? variable : variable.id
  const found = graph.variables.get(id)
  if (!found) throw new Error(`in ${method}: Variable not found`)
  if (found.type !== fieldType(field)) {
    throw new Error(
      `in ${method}: variable of resolved type '${found.type}' cannot be bound to '${field}'`
    )
  }
  return found
}

/** Whether the layer has the field at all; Figma ignores a binding to one it lacks. */
export function hasBindableField(node: SceneNode, field: FigmaBindableField): boolean {
  if (field === 'characters' || isTextBindableField(field)) return node.type === 'TEXT'
  if (CONTAINER_FIELDS.has(field)) return CONTAINER_TYPES.has(node.type)
  return true
}

/** The document fields a Figma field binds: a uniform corner radius binds every corner. */
function documentFields(field: FigmaBindableNodeField): readonly string[] {
  return field === 'cornerRadius' ? CORNER_FIELDS : [NODE_FIELDS[field]]
}

const isCornerField = (field: string): boolean =>
  field === 'cornerRadius' || (CORNER_FIELDS as readonly string[]).includes(field)

/** Draws the layer corner by corner before a script binds or unbinds one, as Figma does. */
function separateCorners(graph: SceneGraph, node: SceneNode): void {
  const changes = independentCornerChanges(node)
  if (isEmptyObject(changes)) return
  graph.updateNode(node.id, changes)
  recordInstanceOverride(graph, node.id, Object.keys(changes))
}

/**
 * Binds or unbinds the document fields behind a Figma node field, then shows the variable's value
 * on the layer and lays out what it moves.
 */
export function setLayerBinding(
  graph: SceneGraph,
  node: SceneNode,
  field: FigmaBindableNodeField,
  variable: Variable | null
): void {
  // Figma keeps the corners' own bindings when a script unbinds the radius as a whole.
  if (field === 'cornerRadius' && !variable) return
  if (isCornerField(field)) separateCorners(graph, node)
  for (const name of documentFields(field)) {
    if (variable) graph.bindVariable(node.id, name, variable.id)
    else graph.unbindVariable(node.id, name)
  }
  reconcileVariableLayouts(graph, { subtrees: [node.id] })
}

/** Text style fields a text layer itself can hold a binding for. */
const LAYER_TEXT_FIELDS: ReadonlySet<TextBindableField> = new Set([
  'fontFamily',
  'fontSize',
  'letterSpacing',
  'lineHeight'
])

/**
 * Binds a text style field of text with no characters on the layer, as Figma keeps it for the
 * characters typed later. OpenPencil keeps only some of those fields on a layer.
 */
export function setEmptyTextBinding(
  graph: SceneGraph,
  node: SceneNode,
  field: TextBindableField,
  variable: Variable | null
): void {
  if (!LAYER_TEXT_FIELDS.has(field)) {
    throw new Error(
      `in setBoundVariable: OpenPencil binds ${field} only on text that has characters`
    )
  }
  if (variable) graph.bindVariable(node.id, field, variable.id)
  else graph.unbindVariable(node.id, field)
  reconcileVariableLayouts(graph, { subtrees: [node.id] })
}

const FIGMA_FIELD_BY_DOCUMENT_FIELD = new Map<string, string>(
  Object.entries(NODE_FIELDS)
    .filter(([figma]) => figma !== 'cornerRadius')
    .map(([figma, field]) => [field, figma])
)

/** The variable bound to each paint's colour, by paint index, for `fills` or `strokes`. */
export function paintBindings(node: SceneNode, key: 'fills' | 'strokes'): Map<number, string> {
  const bindings = new Map<number, string>()
  for (const [field, id] of Object.entries(node.boundVariables)) {
    const paint = paintBindingTarget(field)
    if (paint?.list === key) bindings.set(paint.index, id)
  }
  return bindings
}

/**
 * Binds each paint's colour to the variable its `boundVariables.color` names, as Figma does when
 * paints are set, and drops bindings of paints that no longer carry one.
 */
export function setPaintBindings(
  graph: SceneGraph,
  node: SceneNode,
  key: 'fills' | 'strokes',
  paints: readonly FigmaPaint[]
): void {
  const current = paintBindings(node, key)
  const wanted = new Map<number, string>()
  paints.forEach((paint, index) => {
    const id = 'boundVariables' in paint ? paint.boundVariables?.color?.id : undefined
    if (id && graph.variables.get(id)?.type === 'COLOR') wanted.set(index, id)
  })
  for (const index of current.keys()) {
    if (!wanted.has(index)) graph.unbindVariable(node.id, `${key}/${index}/color`)
  }
  for (const [index, id] of wanted) {
    if (current.get(index) !== id) graph.bindVariable(node.id, `${key}/${index}/color`, id)
  }
  if (current.size > 0 || wanted.size > 0) reconcileVariableLayouts(graph, { subtrees: [node.id] })
}

/** The variables each effect's properties are bound to, by effect index. */
export function effectBindings(node: SceneNode): Map<number, FigmaEffectBindings> {
  const bindings = new Map<number, FigmaEffectBindings>()
  for (const [field, id] of Object.entries(node.boundVariables)) {
    const target = effectBindingTarget(field)
    if (!target) continue
    const effect = bindings.get(target.index) ?? {}
    effect[target.property] = variableAlias(id)
    bindings.set(target.index, effect)
  }
  return bindings
}

/**
 * Binds each effect's properties to the variables its `boundVariables` names, as Figma does when
 * effects are set, and drops bindings the effects no longer carry. A reference to a missing
 * variable, one of the wrong type, or a property the effect lacks binds nothing.
 */
export function setEffectBindings(
  graph: SceneGraph,
  node: SceneNode,
  effects: readonly FigmaEffect[]
): void {
  const current = new Map(
    Object.entries(node.boundVariables).filter(([field]) => effectBindingTarget(field))
  )
  const wanted = new Map<string, string>()
  effects.forEach((effect, index) => {
    const bound: FigmaEffectBindings = effect.boundVariables ?? {}
    for (const property of effectBindableProperties(effect.type)) {
      const id = bound[property]?.id
      if (id && graph.variables.get(id)?.type === effectBindingVariableType(property))
        wanted.set(effectBindingField(index, property), id)
    }
  })
  for (const field of current.keys()) {
    if (!wanted.has(field)) graph.unbindVariable(node.id, field)
  }
  for (const [field, id] of wanted) {
    if (current.get(field) !== id) graph.bindVariable(node.id, field, id)
  }
  if (current.size > 0 || wanted.size > 0) reconcileVariableLayouts(graph, { subtrees: [node.id] })
}

/** Figma's order for a list of variables: by ID, each once. */
function byVariableId(ids: readonly string[]): FigmaVariableAlias[] {
  return uniq(ids)
    .sort((a, b) => a.localeCompare(b, 'en', { numeric: true }))
    .map(variableAlias)
}

type FigmaBoundVariables = Record<string, FigmaVariableAlias | FigmaVariableAlias[]>

/**
 * A layer's bindings as Figma's `boundVariables` reads them: a reference per node field, a list
 * per text style field and per bound paint, and one list of every variable its effects use.
 */
export function figmaBoundVariables(node: SceneNode): FigmaBoundVariables {
  const result: FigmaBoundVariables = {}
  for (const [field, id] of Object.entries(node.boundVariables)) {
    const name = FIGMA_FIELD_BY_DOCUMENT_FIELD.get(field)
    if (name) result[name] = variableAlias(id)
  }
  // Figma lists a uniform radius by its corners; a file can bind it as one field.
  const radius = node.boundVariables.cornerRadius
  if (radius) for (const corner of CORNER_FIELDS) result[corner] ??= variableAlias(radius)
  if (node.type === 'TEXT') {
    for (const field of TEXT_BINDABLE_FIELDS) {
      const ids = uniq([
        ...(node.boundVariables[field] ? [node.boundVariables[field]] : []),
        ...node.styleRuns.flatMap((run) => {
          const id = run.style.boundVariables?.[field]
          return id ? [id] : []
        })
      ])
      if (ids.length > 0) result[field] = ids.map(variableAlias)
    }
  }
  for (const key of ['fills', 'strokes'] as const) {
    const bindings = paintBindings(node, key)
    if (bindings.size === 0) continue
    result[key] = [...bindings.entries()]
      .sort(([a], [b]) => a - b)
      .map(([, id]) => variableAlias(id))
  }
  const effectIds = Object.entries(node.boundVariables)
    .filter(([field]) => effectBindingTarget(field))
    .map(([, id]) => id)
  if (effectIds.length > 0) result.effects = byVariableId(effectIds)
  return result
}