AI-native design editor. Open-source Figma alternative.
import {
behaviourArgs,
FLAGS,
isFlag,
type BehaviourArgs,
type Flag
} from '#dom-css/behaviours/args'
import { behaviourControls, booleanOf } from '#dom-css/behaviours/controls'
import { BUTTON_RESET } from '#dom-css/behaviours/reset'
import { allElements } from '#dom-css/behaviours/states/layers'
import { ownerVariants, restLayerOf, stateStyles } from '#dom-css/behaviours/states/model'
import { layerClassNames, propAttribute } from '#dom-css/behaviours/states/names'
import type { StateElement, StateStyles } from '#dom-css/behaviours/states/types'
import { camelCase } from 'es-toolkit/string'
import type { SceneGraph, SceneNode } from '@open-pencil/scene-graph'
import {
behaviourContract,
behaviourProperties,
layerPath,
readBehaviour,
textBinding,
type Behaviour
} from '@open-pencil/scene-graph/behaviours'
import { slotPropertyId } from '@open-pencil/scene-graph/slots'
import type { SceneGraphToDesignOptions } from '../projection'
import { claimName, identifierName } from '../storybook/names'
import {
blockRoot,
freePlacedParts,
inputLayers,
inputValue,
numberInput,
rangeModel,
textModel
} from './fields'
import {
groupItems,
GROUP_ITEMS,
isGroup,
type GroupKind,
type ItemBuilder,
type ItemKind
} from './groups'
import {
booleanProps,
slotProps,
textProps,
type BooleanProp,
type SlotProp,
type TextProp
} from './properties'
import {
referencedLayers,
type ComponentReference,
type ComponentReferences,
type IconReference,
type UsedLayer
} from './references'
import { activeTriggers, tabParts, type ChoiceModel, type RepeatedPart } from './repeats'
import { shaderLayers, type ShaderLayer } from './shaders'
import type { ComponentStyling } from './styling'
import { componentTree } from './tree'
/** Kinds generated as components so far; the rest keep static stories. */
export const GENERATED_KINDS = [
'button',
'switch',
'checkbox',
'toggle',
'collapsible',
'tabs',
'radioGroup',
'toggleGroup',
'accordion',
'slider',
'progress',
'numberField',
'textField',
'textarea'
] as const
/** What a generated component is: a control on its own, or a group's item. */
/**
* What a generated component is: a control on its own, a group's item, or `plain`, a component
* without a behaviour, which takes its properties as props and has no control of its own.
*/
export type GeneratedKind = (typeof GENERATED_KINDS)[number] | ItemKind | 'plain'
/** A variant property the component takes as a prop and sets on its root as `data-*`. */
export interface VariantProp {
/** The prop's identifier. */
name: string
/** The variant property it draws, which state styles name the condition after. */
property: string
options: string[]
default: string
}
/**
* What the control's root binds, which each framework writes in its own idiom: the two-way
* value (`v-model`, or Radix's `checked` and `onCheckedChange`), `disabled`, `invalid`, and a
* variant property the component sets as a `data-*` attribute from its prop.
*/
export type ComponentBinding =
| { type: 'model'; name: string }
| { type: 'disabled' }
/** `aria-invalid` and `data-invalid` while the `invalid` prop is on. */
| { type: 'invalid' }
/** A group's item: the value it stands for, which the group chooses among. */
| { type: 'value' }
| { type: 'prop'; prop: VariantProp; attribute: string }
/** A layer of the generated markup, before a framework picks its element or component. */
export interface ComponentElement {
type: 'element'
/** The behaviour part the layer draws, `root` for the control itself, or null. */
part: string | null
/** The element the design projects to, used when no library component draws the part. */
tag: string
/** The readable class the state styles select it by. */
className: string
/** Attributes the design sets, such as an image's `src` or its own `class`. */
attrs: Record<string, string>
/** On the root only. */
bindings: ComponentBinding[]
/** The boolean prop that shows the layer, which hides it while off. */
shownBy?: string
/** The slot prop whose content the layer shows in place of its own. */
slot?: string
/** The layer of the rest variant it draws, which code links back to. */
layerId?: string
/** The value a repeated part stands for, such as a tab trigger's tab. */
value?: string
/** A tab trigger that cannot be chosen. */
disabled?: boolean
/** The shader the layer fills with, which plays behind its content. */
shader?: ShaderLayer
children: ComponentNode[]
}
/** A number the component binds two ways, within its range, starting where the design does. */
export interface RangeModel {
min: number
max: number
step: number
default: number
}
/**
* Text a field binds two ways: the words it starts with, and the placeholder an empty field
* shows when the design draws one.
*/
export interface TextModel {
default: string
placeholder: string | null
}
export type ComponentNode =
| ComponentElement
| { type: 'text'; value: string }
/** The value of a text prop, drawn where the design binds a text layer to it. */
| { type: 'textProp'; name: string }
/** A field's input, drawn where the design binds its text layer to the field's text. */
| { type: 'input'; className: string; layerId?: string }
| ComponentReference
| IconReference
/**
* Whether a field's markup always draws its input, which then takes the caller's attributes. A
* field whose text is not bound yet has none, and an input inside a slot is replaced when the
* caller fills the slot; the root takes the attributes then.
*/
export function drawsInput(node: ComponentElement): boolean {
return node.children.some(
(child) =>
child.type === 'input' || (child.type === 'element' && !child.slot && drawsInput(child))
)
}
/** One component generated from a component set with a behaviour. */
export interface ComponentModel {
/** The component's identifier and file name. */
name: string
kind: GeneratedKind
styles: StateStyles
/** The markup every framework writes, with each layer's part and the root's bindings. */
tree: ComponentElement
/**
* The value the component binds two ways: a boolean such as `checked`, `pressed`, or `open`,
* or `value` when it chooses among `choice`, as tabs do.
*/
model: string | null
/** The options a string model takes and the one it starts on. */
choice: ChoiceModel | null
/** The range a number model takes, as a slider, progress bar, or number field has. */
range: RangeModel | null
/** The text a text field or textarea binds. */
text: TextModel | null
/** A group's item takes the `value` it stands for, which the group chooses among. */
valueProp: boolean
/** The component of a group's items, generated beside the group's own. */
item: ComponentModel | null
/** Whether the set draws a disabled state, so the component takes `disabled`. */
disabled: boolean
/** Whether the set draws an invalid state, so the component takes `invalid`. */
invalid: boolean
props: VariantProp[]
texts: TextProp[]
booleans: BooleanProp[]
slots: SlotProp[]
/** The variant properties that draw its booleans and states, which references set. */
args: BehaviourArgs
}
/** A generated component's files, and what its stories need to know about it. */
export interface GeneratedComponent {
/**
* The component's files. A file of JSX lists the layer each of its JSX elements draws, in the
* order they open, `null` for an element no layer drew, such as a shader's canvas.
*/
files: { path: string; content: string; layerIds?: (string | null)[] }[]
/** How stories import it: its path next to them, and whether it's a named export. */
entry: { path: string; named: boolean }
/** The prop a story sets the value with, if the component has one. */
valueArg: string | null
/** Whether that prop takes a list of the value, as Radix's slider does. */
valueList?: boolean
}
/** How a generator writes a component. */
export interface ComponentGeneratorOptions {
/** A stylesheet beside the component, by default, or Tailwind utilities in its markup. */
styling?: ComponentStyling
}
export type ComponentGenerator = (
component: ComponentModel,
options?: ComponentGeneratorOptions
) => Promise<GeneratedComponent>
/** Parts each kind renders as a native button, which the reset clears for the design. */
const BUTTON_PARTS: Record<GeneratedKind, readonly string[]> = {
button: ['root'],
switch: ['root'],
checkbox: ['root'],
toggle: ['root'],
collapsible: ['trigger'],
tabs: ['trigger'],
radioGroup: [],
toggleGroup: [],
accordion: [],
slider: [],
progress: [],
numberField: ['increment', 'decrement'],
textField: [],
textarea: [],
plain: [],
radioGroupItem: ['root'],
toggleGroupItem: ['root'],
accordionItem: ['trigger']
}
const isGenerated = (kind: Behaviour['kind']): kind is (typeof GENERATED_KINDS)[number] =>
(GENERATED_KINDS as readonly string[]).includes(kind)
/** What an owner generates as: a group's item when it is one, its own kind, or nothing. */
function generatedKind(kind: Behaviour['kind'], itemOf?: GroupKind): GeneratedKind | null {
if (itemOf) return GROUP_ITEMS[itemOf]
return isGenerated(kind) ? kind : null
}
/** Layer paths of the slot frames that draw each part, the same in every variant. */
function partPaths(graph: SceneGraph, set: SceneNode, behaviour: Behaviour): Map<string, string> {
const partOfSlot = new Map(Object.entries(behaviour.parts).map(([part, slot]) => [slot, part]))
const paths = new Map<string, string>()
const visit = (variant: SceneNode, node: SceneNode) => {
const part = partOfSlot.get(slotPropertyId(node) ?? '')
if (part) paths.set(layerPath(graph, variant.id, node.id), part)
for (const child of graph.getChildren(node.id)) visit(variant, child)
}
for (const variant of ownerVariants(graph, set))
for (const child of graph.getChildren(variant.id)) visit(variant, child)
return paths
}
/**
* The component a set with a behaviour generates, or `null` when its kind is not generated
* yet or its variants have no rest state to start from.
*/
export interface ComponentModelOptions extends Pick<SceneGraphToDesignOptions, 'vectorElement'> {
/**
* The other components generated alongside, which instances of them use rather than
* drawing their layers.
*/
references?: ComponentReferences
/** The component's identifier and file name; the owner's name by default. */
name?: string
/** A group's item component's name; the group's name with `Item` by default. */
itemName?: string
/** Generate the owner as the item of a group of this kind, which only lives in the group. */
itemOf?: GroupKind
}
/** Each layer's behaviour part: the root, and the slot frames that draw the others. */
function behaviourParts(
graph: SceneGraph,
set: SceneNode,
behaviour: Behaviour,
root: StateElement
): Map<StateElement, string> {
const paths = partPaths(graph, set, behaviour)
const contract = behaviourContract(behaviour.kind).parts
const parts = new Map<StateElement, string>([[root, 'root']])
for (const element of allElements(root)) {
const part = paths.get(element.key)
if (part && contract.some((item) => item.id === part)) parts.set(element, part)
}
return parts
}
/** Clears the native button look from the parts a kind renders as buttons. */
function resetButtons(
kind: GeneratedKind,
parts: ReadonlyMap<StateElement, string>,
repeated: ReadonlyMap<StateElement, RepeatedPart>
): void {
const all = [...parts, ...[...repeated].map(([element, item]) => [element, item.part] as const)]
for (const [element, part] of all)
if (BUTTON_PARTS[kind].includes(part)) element.base = { ...BUTTON_RESET, ...element.base }
}
/** The variant properties that are not values or states, as props set as `data-*`. */
function variantProps(
graph: SceneGraph,
set: SceneNode,
args: BehaviourArgs,
taken: Set<string>
): VariantProp[] {
const bound = new Set([...args.booleans.keys(), args.states?.property, args.filled?.property])
return behaviourProperties(graph, set)
.filter((definition) => definition.type === 'VARIANT' && !bound.has(definition.name))
.map((definition) => ({
name: claimName(camelCase(identifierName(definition.name, 'Prop')), taken),
property: definition.name,
options: definition.variantOptions ?? [],
default: definition.defaultValue
}))
}
/** What the root binds: its model, an item's value, `disabled`, `invalid`, and its variant props. */
function rootBindings(
model: string | null,
item: boolean,
flags: Flags,
props: readonly VariantProp[]
): ComponentBinding[] {
return [
...(model ? [{ type: 'model' as const, name: model }] : []),
...(item ? [{ type: 'value' as const }] : []),
...(flags.disabled ? [{ type: 'disabled' as const }] : []),
...(flags.invalid ? [{ type: 'invalid' as const }] : []),
...props.map((prop) => ({
type: 'prop' as const,
prop,
attribute: propAttribute(prop.property)
}))
]
}
/**
* A group's items, built as the group's item component; null for other owners and for a
* group's item itself.
*/
function itemsOf(
graph: SceneGraph,
behaviour: Behaviour,
variantIds: readonly string[],
parts: ReadonlyMap<StateElement, string>,
options: ComponentModelOptions,
build: (itemOf: GroupKind) => ItemBuilder
): ReturnType<typeof groupItems> {
if (options.itemOf || !isGroup(behaviour.kind)) return null
const itemsElement = [...parts].find(([, part]) => part === 'items')?.[0]
return groupItems(graph, variantIds, itemsElement, build(behaviour.kind))
}
/**
* The value the component binds two ways: `value` when it chooses among options or holds a
* number or text, its boolean such as `checked`, or none for a group's item, which its group
* chooses.
*/
function modelName(args: BehaviourArgs, item: boolean, valued: boolean): string | null {
if (valued) return 'value'
if (item) return null
return [...args.booleans.values()].find((arg) => !isFlag(arg.name))?.name ?? null
}
/**
* Kinds whose input is the control a person fills in, which `aria-invalid` marks; other
* controls are marked on their root.
*/
export const FIELD_KINDS: ReadonlySet<GeneratedKind> = new Set([
'textField',
'textarea',
'numberField'
])
/** Whether the set draws each flag, so the component takes it as a prop. */
type Flags = Record<Flag, boolean>
/** Which flags the set draws, as a boolean or an interaction state. */
const drawnFlags = (args: BehaviourArgs): Flags => {
const draws = (name: Flag) =>
[...args.booleans.values()].some((arg) => arg.name === name) ||
args.states?.[name] !== undefined
return { disabled: draws('disabled'), invalid: draws('invalid') }
}
/** The layers used rather than drawn: a group's items, then other generated components. */
function usedLayers(
graph: SceneGraph,
root: StateElement,
variantIds: readonly string[],
items: ReadonlyMap<StateElement, UsedLayer> | undefined,
references: ComponentReferences | undefined
): Map<StateElement, UsedLayer> {
const used = new Map(items)
if (references)
for (const [element, layer] of referencedLayers(graph, root, variantIds, references, used))
used.set(element, layer)
return used
}
/**
* Sizes the design gives include a layer's padding and border, which a component's own
* stylesheet has to say, since no page reset around it does. A root without a width hugs its
* content, as the design draws it.
*/
function borderBoxes(root: StateElement): void {
// A root the design sizes to its content hugs it, where a block would fill its container.
if (!Object.hasOwn(root.base, 'width')) root.base = { ...root.base, width: 'fit-content' }
for (const element of allElements(root)) {
const has = (property: string) => Object.hasOwn(element.base, property)
if ((has('width') || has('height')) && !has('box-sizing'))
element.base = { 'box-sizing': 'border-box', ...element.base }
}
}
/**
* A trigger that is a tab drawn disabled, by its disabled value or its disabled state, is a
* disabled trigger, which cannot be chosen, as preview runs it.
*/
function disableDrawnTabs(
graph: SceneGraph,
styles: StateStyles,
repeated: ReadonlyMap<StateElement, RepeatedPart>
): void {
for (const [element, item] of repeated) {
if (item.part !== 'trigger') continue
const layerId = restLayerOf(graph, styles, element)
const tab = layerId ? behaviourControls(graph, layerId).get('') : undefined
if (tab?.kind !== 'tab') continue
if (booleanOf(tab, 'disabled')?.designed || tab.states?.designedDisabled) item.disabled = true
}
}
/**
* Each layer's part, and tabs' triggers and panels, with the styles the generated parts need:
* native buttons cleared, the chosen tab's look, and moving parts free of their drawn place.
*/
function drawnParts(
graph: SceneGraph,
set: SceneNode,
behaviour: Behaviour | null,
kind: GeneratedKind,
root: StateElement
) {
// A component without a behaviour has no parts but its root.
const parts = behaviour
? behaviourParts(graph, set, behaviour, root)
: new Map<StateElement, string>([[root, 'root']])
const tabs = behaviour?.kind === 'tabs' ? tabParts(parts) : null
const repeated = tabs?.repeated ?? new Map<StateElement, RepeatedPart>()
activeTriggers(repeated)
resetButtons(kind, parts, repeated)
freePlacedParts(kind, parts)
blockRoot(kind, root)
borderBoxes(root)
return { parts, tabs, repeated }
}
/** The number or text the component holds, and the text property a field's input shows. */
function valueModels(
graph: SceneGraph,
set: SceneNode,
kind: GeneratedKind,
behaviour: Behaviour | null,
args: BehaviourArgs
): { range: RangeModel | null; text: TextModel | null; inputProperty: string | undefined } {
if (!behaviour) return { range: null, text: null, inputProperty: undefined }
const valueText = inputValue(kind)
const inputProperty = valueText && textBinding(behaviour, valueText)
const definition = behaviourProperties(graph, set).find((item) => item.id === inputProperty)
return {
range: rangeModel(kind, behaviour),
text: textModel(kind, definition, args),
inputProperty
}
}
export function componentModel(
graph: SceneGraph,
set: SceneNode,
options: ComponentModelOptions = {}
): ComponentModel | null {
const behaviour = readBehaviour(set)
// A component without a behaviour is plain: its properties are its props.
const kind = behaviour ? generatedKind(behaviour.kind, options.itemOf) : 'plain'
const styles = kind ? stateStyles(graph, set, options) : null
const args = behaviourArgs(graph, set) ?? { booleans: new Map() }
if (!kind || !styles) return null
const name = options.name ?? identifierName(set.name, 'Component')
const { parts, tabs, repeated } = drawnParts(graph, set, behaviour, kind, styles.root)
disableDrawnTabs(graph, styles, repeated)
// A group's items first, so its item component is used for them rather than a standalone one.
const variantIds = [styles.restId, ...ownerVariants(graph, set).map((variant) => variant.id)]
const items =
behaviour &&
itemsOf(
graph,
behaviour,
variantIds,
parts,
options,
(itemOf) => (owner) =>
componentModel(graph, owner, {
...options,
name: options.itemName ?? `${name}Item`,
itemName: undefined,
itemOf
})
)
const choice = tabs?.choice ?? items?.choice ?? null
const { range, text, inputProperty } = valueModels(graph, set, kind, behaviour, args)
const model = modelName(args, !!options.itemOf, !!(choice ?? range ?? text))
const taken = new Set([...(model ? [model] : []), ...FLAGS, 'value'])
const props = variantProps(graph, set, args, taken)
const flags = drawnFlags(args)
const used = usedLayers(graph, styles.root, variantIds, items?.used, options.references)
const elements = allElements(styles.root)
const texts = textProps(graph, set, elements, taken, inputProperty)
const input = inputLayers(texts.input)
numberInput(input, range)
const { booleans, shownBy } = booleanProps(graph, set, elements, taken)
const { slots, slotOf } = slotProps(graph, set, elements, taken, parts)
return {
name,
kind,
styles,
tree: componentTree(
styles.root,
{
parts,
classes: layerClassNames(styles),
texts: texts.bound,
used,
repeated,
input,
shownBy,
slotOf,
shaders: shaderLayers(graph, styles.restId, elements),
layerOf: (element) => restLayerOf(graph, styles, element)
},
rootBindings(model, !!options.itemOf, flags, props)
),
model,
choice,
range,
text,
valueProp: !!options.itemOf,
item: items?.item ?? null,
...flags,
props,
texts: texts.texts,
booleans,
slots,
args
}
}