Skip to content

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

12.6 KB
Raw Blame
import { effectiveFigmaRawNodeFields } from '#fig/source-metadata'
import { invert } from 'es-toolkit/object'

import type { GUID } from '@open-pencil/kiwi/fig'
import type { VariableConsumptionEntry } from '@open-pencil/kiwi/fig/codec'
import { guidToString, stringToGuid } from '@open-pencil/kiwi/fig/guid'
import type {
  SceneNode,
  SceneGraph,
  TextBindableField,
  TextBoundVariables
} from '@open-pencil/scene-graph'
import { boundNumberValue, isNumericVariableBindingField } from '@open-pencil/scene-graph/variables'

import { cloneRecord } from '../clone'
import { linearVariableExpression } from './expression'
import { mergeVariableModeMaps } from './maps'

export const VARIABLE_BINDING_FIELDS: Record<string, string> = {
  cornerRadius: 'CORNER_RADIUS',
  topLeftRadius: 'RECTANGLE_TOP_LEFT_CORNER_RADIUS',
  topRightRadius: 'RECTANGLE_TOP_RIGHT_CORNER_RADIUS',
  bottomLeftRadius: 'RECTANGLE_BOTTOM_LEFT_CORNER_RADIUS',
  bottomRightRadius: 'RECTANGLE_BOTTOM_RIGHT_CORNER_RADIUS',
  strokeWeight: 'STROKE_WEIGHT',
  borderTopWeight: 'BORDER_TOP_WEIGHT',
  borderBottomWeight: 'BORDER_BOTTOM_WEIGHT',
  borderLeftWeight: 'BORDER_LEFT_WEIGHT',
  borderRightWeight: 'BORDER_RIGHT_WEIGHT',
  itemSpacing: 'STACK_SPACING',
  paddingLeft: 'STACK_PADDING_LEFT',
  paddingTop: 'STACK_PADDING_TOP',
  paddingRight: 'STACK_PADDING_RIGHT',
  paddingBottom: 'STACK_PADDING_BOTTOM',
  counterAxisSpacing: 'STACK_COUNTER_SPACING',
  gridRowGap: 'GRID_ROW_GAP',
  gridColumnGap: 'GRID_COLUMN_GAP',
  text: 'TEXT_DATA',
  visible: 'VISIBLE',
  opacity: 'OPACITY',
  width: 'WIDTH',
  height: 'HEIGHT',
  minWidth: 'MIN_WIDTH',
  maxWidth: 'MAX_WIDTH',
  minHeight: 'MIN_HEIGHT',
  maxHeight: 'MAX_HEIGHT',
  x: 'X_POSITION',
  y: 'Y_POSITION',
  rotation: 'ROTATION',
  fontSize: 'FONT_SIZE',
  letterSpacing: 'LETTER_SPACING',
  lineHeight: 'LINE_HEIGHT',
  fontFamily: 'FONT_FAMILY'
}

export const VARIABLE_BINDING_FIELDS_INVERSE: Record<string, string> = Object.fromEntries(
  Object.entries(VARIABLE_BINDING_FIELDS).map(([field, kiwiField]) => [kiwiField, field])
)

export interface VariableConsumptionSource extends Record<string, unknown> {
  variableConsumptionMap?: { entries?: VariableConsumptionEntry[] }
  parameterConsumptionMap?: unknown
}

/** Modern parameter entries follow legacy entries and can explicitly clear them. */
/**
 * A bound opacity is authored as a percentage and stored as a unit fraction, so every
 * conversion between the two forms goes through this factor.
 */
const OPACITY_UNIT_PER_PERCENT = 0.01

/** Only an alias or an expression carries a variable reference worth resolving. */
export function referencesVariable(dataType: string | undefined): boolean {
  return dataType === 'ALIAS' || dataType === 'EXPRESSION'
}

export function variableConsumptionEntries(
  node: VariableConsumptionSource
): VariableConsumptionEntry[] {
  const parameters = node.parameterConsumptionMap as
    | { entries?: VariableConsumptionEntry[] }
    | undefined
  const fields = new Map<string, VariableConsumptionEntry>()
  const unkeyed: VariableConsumptionEntry[] = []
  for (const entry of [
    ...(node.variableConsumptionMap?.entries ?? []),
    ...(parameters?.entries ?? [])
  ]) {
    if (entry.variableField) fields.set(entry.variableField, entry)
    else unkeyed.push(entry)
  }
  return [...unkeyed, ...fields.values()]
}

export function mergeVariableConsumptionMaps(
  base: VariableConsumptionSource,
  patch: VariableConsumptionSource
): Record<string, unknown> {
  const incoming = variableConsumptionEntries(patch)
  if (incoming.length === 0) return {}
  const entries: VariableConsumptionEntry[] = []
  for (const entry of [...variableConsumptionEntries(base), ...incoming]) {
    const index = entry.variableField
      ? entries.findIndex((previous) => previous.variableField === entry.variableField)
      : -1
    if (index < 0) entries.push(cloneRecord(entry))
    else entries[index] = cloneRecord(entry)
  }
  // VariableDataMap carries nothing but its entries, so the merged list is the whole map.
  return { parameterConsumptionMap: { entries } }
}

export function claimedVariableMaps(
  layer: VariableConsumptionSource,
  claim: VariableConsumptionSource
): Record<string, unknown> {
  return { ...mergeVariableConsumptionMaps(layer, claim), ...mergeVariableModeMaps(layer, claim) }
}

export function variableBindingEntry(
  field: string,
  variableId: string | undefined,
  graph: SceneGraph,
  ids?: Map<string, GUID>,
  multiplier = 1,
  expression = false
): VariableConsumptionEntry | undefined {
  const variableField = VARIABLE_BINDING_FIELDS[field]
  if (!variableField) return undefined
  return consumptionEntry(variableField, variableId, graph, ids, multiplier, expression)
}

/** Kiwi's field for each text field a range of characters binds, where Kiwi has one. */
export const TEXT_RUN_BINDING_FIELDS = {
  fontFamily: 'FONT_FAMILY',
  fontStyle: 'FONT_STYLE',
  fontSize: 'FONT_SIZE',
  letterSpacing: 'LETTER_SPACING',
  lineHeight: 'LINE_HEIGHT',
  paragraphSpacing: 'PARAGRAPH_SPACING',
  paragraphIndent: 'PARAGRAPH_INDENT'
} as const satisfies Partial<Record<TextBindableField, string>>

const TEXT_RUN_BINDING_FIELDS_INVERSE: Partial<Record<string, TextBindableField>> =
  invert(TEXT_RUN_BINDING_FIELDS)

/** The entries a range of characters' bindings are written with, in its style override. */
export function textRunVariableEntries(
  bound: TextBoundVariables,
  graph: SceneGraph,
  ids?: Map<string, GUID>
): VariableConsumptionEntry[] {
  return Object.entries(bound).flatMap(([field, variableId]) => {
    const variableField = (TEXT_RUN_BINDING_FIELDS as Partial<Record<string, string>>)[field]
    if (!variableField || !variableId || !graph.variables.has(variableId)) return []
    return [consumptionEntry(variableField, variableId, graph, ids)]
  })
}

/** The text fields a style override binds, by variable ID. */
export function textRunVariableBindings(override: VariableConsumptionSource): TextBoundVariables {
  const bound: TextBoundVariables = {}
  for (const entry of variableConsumptionEntries(override)) {
    const field = entry.variableField && TEXT_RUN_BINDING_FIELDS_INVERSE[entry.variableField]
    const guid = field ? linearVariableExpression(entry.variableData)?.reference?.guid : undefined
    if (field && guid) bound[field] = guidToString(guid)
  }
  return bound
}

/**
 * How a record names a variable it uses, as Figma writes it: a library variable by its key,
 * even where the file holds a copy of it, and a local one by its record.
 */
export function variableAlias(
  graph: SceneGraph,
  variableId: string,
  ids?: ReadonlyMap<string, GUID>
): { guid: GUID } | { assetRef: { key: string; version?: string } } {
  const variable = graph.variables.get(variableId)
  if (variable?.key) {
    return {
      assetRef: { key: variable.key, ...(variable.version ? { version: variable.version } : {}) }
    }
  }
  return { guid: ids?.get(variableId) ?? stringToGuid(variableId) }
}

function consumptionEntry(
  variableField: string,
  variableId: string | undefined,
  graph: SceneGraph,
  ids?: Map<string, GUID>,
  multiplier = 1,
  expression = false
): VariableConsumptionEntry {
  if (!variableId) return { variableField }
  const variable = graph.variables.get(variableId)
  if (!variable) throw new Error(`Missing bound variable ${variableId}`)
  if (!Number.isFinite(multiplier)) throw new Error('Non-finite variable binding multiplier')
  const alias = {
    dataType: 'ALIAS',
    resolvedDataType: variable.type,
    value: { alias: variableAlias(graph, variableId, ids) }
  }
  // Figma's layer panel tests a variable bound to visibility with IS_TRUTHY, and writes a number
  // or boolean bound to text content as STRINGIFY.
  let conversion: 'IS_TRUTHY' | 'STRINGIFY' | undefined
  if (variableField === 'VISIBLE') conversion = 'IS_TRUTHY'
  else if (variableField === 'TEXT_DATA' && variable.type !== 'STRING') conversion = 'STRINGIFY'
  if (conversion) {
    return {
      variableField,
      variableData: {
        dataType: 'EXPRESSION',
        resolvedDataType: conversion === 'IS_TRUTHY' ? 'BOOLEAN' : 'STRING',
        value: {
          expressionValue: { expressionFunction: conversion, expressionArguments: [alias] }
        }
      }
    }
  }
  if (variable.type !== 'FLOAT' || (!expression && multiplier === 1))
    return { variableField, variableData: alias }
  return {
    variableField,
    variableData: {
      dataType: 'EXPRESSION',
      resolvedDataType: 'FLOAT',
      value: {
        expressionValue: {
          expressionFunction: 'MULTIPLY',
          expressionArguments: [
            { dataType: 'FLOAT', resolvedDataType: 'FLOAT', value: { floatValue: multiplier } },
            alias
          ]
        }
      }
    }
  }
}

function numericBindingUnit(field: string, distanceScale: number): number {
  if (field === 'opacity') return OPACITY_UNIT_PER_PERCENT
  if (field === 'rotation') return 1
  return distanceScale
}

export function overrideVariableBindingEntry(
  field: string,
  target: SceneNode,
  owner: SceneNode,
  graph: SceneGraph,
  ids?: Map<string, GUID>
): VariableConsumptionEntry | undefined {
  const units = numericBindingUnit(field, owner.componentScale)
  const multiplier =
    target.variableBindingScales[field] === undefined
      ? 1
      : target.variableBindingScales[field] / units
  return variableBindingEntry(field, target.boundVariables[field], graph, ids, multiplier)
}

export function exportedVariableConsumptionEntries(
  node: SceneNode,
  graph: SceneGraph,
  ids?: Map<string, GUID>
): VariableConsumptionEntry[] {
  const fields = new Set(Object.keys(node.boundVariables))
  for (const entry of variableConsumptionEntries(effectiveFigmaRawNodeFields(node))) {
    if (!referencesVariable(entry.variableData?.dataType)) continue
    const field = entry.variableField && VARIABLE_BINDING_FIELDS_INVERSE[entry.variableField]
    if (field) fields.add(field)
  }
  return [...fields].flatMap((field) => {
    const multiplier =
      (node.variableBindingScales[field] ?? 1) /
      (field === 'opacity' ? OPACITY_UNIT_PER_PERCENT : 1)
    const entry = variableBindingEntry(
      field,
      node.boundVariables[field],
      graph,
      ids,
      multiplier,
      node.type === 'INSTANCE' && node.componentScale !== 1
    )
    return entry ? [entry] : []
  })
}

export interface ResolvedVariableConsumption {
  field: string
  variableId: string
  multiplier: number
}

export function resolveVariableConsumptionEntry(
  entry: VariableConsumptionEntry
): ResolvedVariableConsumption | undefined {
  const field = entry.variableField
    ? VARIABLE_BINDING_FIELDS_INVERSE[entry.variableField]
    : undefined
  if (!field) return undefined
  const expression = linearVariableExpression(entry.variableData)
  if (entry.variableData?.value?.expressionValue && !expression?.reference)
    throw new Error('Variable expression must contain one alias')
  const guid = expression?.reference?.guid
  return guid
    ? { field, variableId: guidToString(guid), multiplier: expression.multiplier }
    : undefined
}

export function sourceVariableBindingScales(
  source: VariableConsumptionSource
): Record<string, number> {
  const scales: Record<string, number> = {}
  for (const entry of variableConsumptionEntries(source)) {
    const binding = resolveVariableConsumptionEntry(entry)
    if (binding && isNumericVariableBindingField(binding.field)) {
      scales[binding.field] =
        binding.multiplier * (binding.field === 'opacity' ? OPACITY_UNIT_PER_PERCENT : 1)
    }
  }
  return scales
}

/** Omit identity conversions: most unscaled scopes need only percentage opacity units. */
export function numericVariableAssignmentScales(layoutScale = 1): Record<string, number> {
  if (layoutScale === 1) return {}
  return Object.fromEntries(
    Object.entries(numericVariableBindingScales(VARIABLE_BINDING_FIELDS, layoutScale)).filter(
      ([, scale]) => scale !== 1
    )
  )
}

/** Translate Figma numeric bindings into persistent scene-unit conversions. */
export function numericVariableBindingScales(
  bindings: Record<string, string>,
  layoutScale: number,
  declarationScales: Partial<Record<string, number>> = {}
): Record<string, number> {
  const scales: Record<string, number> = {}
  for (const field of Object.keys(bindings)) {
    if (!isNumericVariableBindingField(field)) continue
    scales[field] = declarationScales[field] ?? numericBindingUnit(field, layoutScale)
  }
  return scales
}

export function resolvedNumericBindingUpdate(
  field: string,
  value: number
): Partial<SceneNode> | undefined {
  if (field === 'opacity')
    return { opacity: Math.max(0, Math.min(1, value * OPACITY_UNIT_PER_PERCENT)) }
  return isNumericVariableBindingField(field)
    ? { [field]: boundNumberValue(field, value) }
    : undefined
}