AI-native design editor. Open-source Figma alternative.
import type {
Effect as PluginEffect,
VariableBindableEffectField
} from '@figma/plugin-typings/plugin-api-standalone'
import type { Effect, SceneGraph, VariableType } from '@open-pencil/scene-graph'
import {
EFFECT_BINDING_PROPERTIES,
effectBindableProperties,
effectBindingVariableType,
type EffectBindingProperty
} from '@open-pencil/scene-graph/variables'
import { boundEffectCopy, type FigmaEffect } from '#core/figma-api/effects'
import { FIGMA_DEFAULT_VALUES, variableAlias, type FigmaVariableAlias } from './values'
import { FigmaVariable, FigmaVariableCollection, assertVariableName } from './variable'
export { FigmaVariable, FigmaVariableCollection, writeVariableValue } from './variable'
export type { FigmaComposedColor, FigmaVariableAlias, FigmaVariableValue } from './values'
export {
figmaBoundVariables,
paintBindings,
setLayerBinding,
effectBindings,
setEffectBindings,
setPaintBindings,
type FigmaBindableField
} from './bindings'
/** Figma's variable types, including the motion types OpenPencil does not model. */
const FIGMA_TYPES = ['BOOLEAN', 'COLOR', 'FLOAT', 'STRING', 'EASING', 'TIMING'] as const
export type FigmaVariableResolvedType = (typeof FIGMA_TYPES)[number]
function assertType(method: string, type: unknown): FigmaVariableResolvedType {
if (!(FIGMA_TYPES as readonly unknown[]).includes(type)) {
throw new Error(
`in ${method}: Property "resolvedType" failed validation: Invalid option: expected one of ` +
FIGMA_TYPES.map((name) => `"${name}"`).join('|')
)
}
return type as FigmaVariableResolvedType
}
function isModelledType(type: FigmaVariableResolvedType): type is VariableType {
return Object.hasOwn(FIGMA_DEFAULT_VALUES, type)
}
/** A solid paint as `setBoundVariableForPaint` takes and returns it. */
type FigmaSolidPaint = {
readonly type: string
readonly boundVariables?: { color?: FigmaVariableAlias }
}
/** `figma.variables`: the document's variables and collections, as Figma's plugin API has them. */
export class FigmaVariablesAPI {
readonly #graph: SceneGraph
constructor(graph: SceneGraph) {
this.#graph = graph
}
getVariableById(id: string): FigmaVariable | null {
return this.#graph.variables.has(id) ? new FigmaVariable(this.#graph, id) : null
}
async getVariableByIdAsync(id: string): Promise<FigmaVariable | null> {
return this.getVariableById(id)
}
getVariableCollectionById(id: string): FigmaVariableCollection | null {
return this.#graph.variableCollections.has(id)
? new FigmaVariableCollection(this.#graph, id)
: null
}
async getVariableCollectionByIdAsync(id: string): Promise<FigmaVariableCollection | null> {
return this.getVariableCollectionById(id)
}
getLocalVariables(type?: FigmaVariableResolvedType): FigmaVariable[] {
const wanted = type === undefined ? undefined : assertType('getLocalVariables', type)
return [...this.#graph.variables.values()]
.filter((variable) => wanted === undefined || variable.type === wanted)
.map((variable) => new FigmaVariable(this.#graph, variable.id))
}
async getLocalVariablesAsync(type?: FigmaVariableResolvedType): Promise<FigmaVariable[]> {
return this.getLocalVariables(type)
}
getLocalVariableCollections(): FigmaVariableCollection[] {
return [...this.#graph.variableCollections.keys()].map(
(id) => new FigmaVariableCollection(this.#graph, id)
)
}
async getLocalVariableCollectionsAsync(): Promise<FigmaVariableCollection[]> {
return this.getLocalVariableCollections()
}
/** A variable in `collection` whose every mode starts at Figma's default for its type. */
createVariable(
name: string,
collection: { readonly id: string } | string,
resolvedType: FigmaVariableResolvedType
): FigmaVariable {
const type = assertType('createVariable', resolvedType)
if (!isModelledType(type))
throw new Error(`in createVariable: OpenPencil does not support ${type} variables`)
const collectionId = typeof collection === 'string' ? collection : collection.id
if (!this.#graph.variableCollections.has(collectionId)) {
throw new Error('in createVariable: Could not find variable collection')
}
assertVariableName(this.#graph, 'createVariable', name, collectionId)
const variable = this.#graph.createVariable(
name,
type,
collectionId,
structuredClone(FIGMA_DEFAULT_VALUES[type])
)
return new FigmaVariable(this.#graph, variable.id)
}
createVariableCollection(name: string): FigmaVariableCollection {
return new FigmaVariableCollection(this.#graph, this.#graph.createCollection(name).id)
}
createVariableAlias(variable: { readonly id: string }): FigmaVariableAlias {
return variableAlias(variable.id)
}
async createVariableAliasByIdAsync(variableId: string): Promise<FigmaVariableAlias> {
if (!this.#graph.variables.has(variableId)) {
throw new Error('in createVariableAliasByIdAsync: Variable not found')
}
return variableAlias(variableId)
}
/**
* A copy of `paint` whose colour is bound to `variable`, or unbound for `null`; it binds when the
* paint is set on a layer. Colour is the one paint field Figma binds.
*/
setBoundVariableForPaint<T extends FigmaSolidPaint>(
paint: T,
_field: 'color',
variable: { readonly id: string } | null
): T & { boundVariables: { color?: FigmaVariableAlias } } {
const { color: _previous, ...others } = paint.boundVariables ?? {}
if (variable === null) return { ...structuredClone(paint), boundVariables: others }
if (this.#graph.variables.get(variable.id)?.type !== 'COLOR') {
throw new Error('in setBoundVariableForPaint: can only bind color variables to color')
}
return {
...structuredClone(paint),
boundVariables: { ...others, color: variableAlias(variable.id) }
}
}
/**
* A copy of `effect` with one property bound to `variable`; it binds when the effect is set on a
* layer. As in Figma, the copy's values are not resolved yet, a shadow's spread reads 0, and
* `null` unbinds every property of the effect, not only `field`.
*/
setBoundVariableForEffect(
effect: PluginEffect,
field: VariableBindableEffectField,
variable: { readonly id: string } | null
): FigmaEffect {
return boundEffectCopy('setBoundVariableForEffect', effect, (modelled) => {
const property = assertEffectField(modelled.type, field)
if (variable === null) return {}
if (typeof variable !== 'object') {
throw new TypeError(`in setBoundVariableForEffect: Expected node, got ${typeof variable}`)
}
const type = effectBindingVariableType(property)
if (this.#graph.variables.get(variable.id)?.type !== type) {
throw new Error(
`in setBoundVariableForEffect: can only bind ${type.toLowerCase()} variables to ${property}`
)
}
return { ...modelled.boundVariables, [property]: variableAlias(variable.id) }
})
}
}
/** Figma's check of the property `setBoundVariableForEffect` binds, which a blur limits to radius. */
function assertEffectField(type: Effect['type'], field: unknown): EffectBindingProperty {
const properties = effectBindableProperties(type)
const found = properties.find((property) => property === field)
if (found) return found
const expected =
properties.length === 1
? `Invalid input: expected "${properties[0]}"`
: `Invalid option: expected one of ${EFFECT_BINDING_PROPERTIES.map((name) => `"${name}"`).join('|')}`
throw new Error(`in setBoundVariableForEffect: Property "field" failed validation: ${expected}`)
}