import { DesignDocument, DesignElement, DesignNode, DesignStyleDeclaration, DesignText } from "./types.js"; import { COMPONENT_STYLINGS, ComponentStyling, ExportHTMLBundle, ExportHTMLBundleOptions, ExportHTMLFile, SceneGraphToDesignOptions, VectorElementRenderer, WebFontFaceAsset, WebFontFaceRequest, WebFontFaceResolver, exportHTMLBundle, sceneGraphToDesignDocument, sceneNodeToDesignDocument, sceneNodesToDesignDocument, serializeHTML, serializeNode } from "./styling.js"; import { ThemeNamespace } from "twirlwind"; import { Behaviour } from "@open-pencil/scene-graph/behaviours"; import { CSSStyleSheetLike } from "@acemir/cssom"; import { ComponentPropertyDefinition, SceneGraph, SceneNode, TokenUnit, Variable, VariableCollection, VariableCollectionMode } from "@open-pencil/scene-graph"; //#region src/export/tailwind-jsx.d.ts /** Engine services the projection takes, such as drawing vector layers as SVG. */ type ProjectionServices = Pick; /** Print a design document as Tailwind JSX, one top-level element per block. */ declare function designDocumentToTailwindJSX(document: DesignDocument): string; /** Tailwind JSX for scene nodes, separated by blank lines. */ declare function sceneNodesToTailwindJSX(graph: SceneGraph, nodeIds: string[], options?: ProjectionServices): string; /** Tailwind JSX with the layer behind each element, in the order elements open. */ interface TailwindJSXWithLayers { code: string; /** One entry per JSX element in pre-order; `null` for an element no layer produced. */ layerIds: Array; } declare function sceneNodesToTailwindJSXWithLayers(graph: SceneGraph, nodeIds: string[], { vectorElement }?: ProjectionServices): TailwindJSXWithLayers; //#endregion //#region src/behaviours/args.d.ts /** A variant property a boolean value draws, as the component's boolean prop. */ interface BooleanArg { /** * The prop's name, as Reka and Radix call it: `checked`, `pressed`, `open`, `disabled`; or * `invalid`, which code marks with `aria-invalid`. */ name: string; on: string; off: string; } /** The props a component with a behaviour has, read from the variant properties that draw it. */ interface BehaviourArgs { /** Boolean props by the name of the variant property that draws them. */ booleans: Map; /** * The variant property that draws interaction states. States follow the pointer and focus, * so they are not props; `rest` is the value shown without one, and `disabled` and `invalid` * the values the `disabled` and `invalid` props show, if the set draws them. */ states?: { property: string; rest: string; disabled?: string; invalid?: string; }; /** * The variant property that draws a field with text, which the field shows while its input * has text rather than taking as a prop. */ filled?: { property: string; on: string; off: string; }; } /** * The props of a component set with a behaviour. Only variant properties become props here, * since each variant is drawn; a boolean value becomes a boolean prop when its property offers * exactly its on and off values. */ declare function behaviourArgs(graph: SceneGraph, set: SceneNode): BehaviourArgs | null; //#endregion //#region src/behaviours/states/types.d.ts /** * What must hold on a control's root for a variant to show. Reka and Radix set `data-state` * and `data-disabled` themselves; the browser sets the interactions; a generated component * sets `data-invalid` from its `invalid` prop, and `data-*` from its props for every other * variant property. */ type StateCondition = { type: 'state'; value: string; } | { type: 'disabled'; } | /** `enabled` when the property that draws invalid draws disabled too, which wins over it. */ { type: 'invalid'; enabled?: boolean; } | { type: 'interaction'; state: 'hover' | 'pressed' | 'focus'; /** When focus lands on a layer inside the control, such as a field's input. */ within?: boolean; /** * When the property that draws the interaction draws invalid too: one value shows at a * time, and an invalid control keeps its invalid look under the pointer and in focus. */ valid?: boolean; } | /** A field whose input holds text. */ { type: 'filled'; } | { type: 'prop'; name: string; value: string; }; /** What a variant changes on a layer, and the conditions that show that variant. */ interface StateRule { conditions: StateCondition[]; /** * The layer the conditions test when it is not the control's root, such as a tab trigger * that Reka and Radix mark active itself: the layer the rule styles, or one around it. */ on?: StateElement; /** The part of the layer the rule styles: an input's placeholder, or a number input's spinner. */ pseudo?: 'placeholder' | '-webkit-inner-spin-button'; style: DesignStyleDeclaration; } /** A layer of the merged markup: its rest style and what each other variant changes. */ interface StateElement { type: 'element'; /** The layer path below the variant, with the text when variants label a layer differently. */ key: string; /** What the layer draws other than its own box, such as an instance or an icon (`layerKind`). */ kind: string | undefined; /** The layer's name, for class names. */ name: string; tagName: string; attrs: Record; base: DesignStyleDeclaration; rules: StateRule[]; /** The shader the layer fills with at rest, as the projection keeps it. */ shader?: DesignElement['shader']; children: StateNode[]; } type StateNode = StateElement | DesignText; interface StateStyles { /** The set's name, for the root's class name. */ name: string; /** The variant drawing the rest state, which the merged tree starts from. */ restId: string; root: StateElement; } //#endregion //#region src/export/components/model.d.ts /** A generated component's files, and what its stories need to know about it. */ 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. */ interface ComponentGeneratorOptions { /** A stylesheet beside the component, by default, or Tailwind utilities in its markup. */ styling?: ComponentStyling; } //#endregion //#region src/export/components/layers.d.ts /** The frameworks a layer can be generated as a component for. */ declare const LAYER_COMPONENT_FRAMEWORKS: readonly ["vue", "react"]; type LayerComponentFramework = (typeof LAYER_COMPONENT_FRAMEWORKS)[number]; /** A layer as a component: its name and the files that make it up. */ interface LayerComponent { name: string; layerId: string; files: GeneratedComponent['files']; } /** * Each layer as a Vue or React component, as the Storybook export generates a component set's: * a component set with its variants as props and its behaviour's parts, and any other layer as * a plain component of the elements it draws. Names stay distinct across the layers. */ declare function layerComponents(graph: SceneGraph, layerIds: readonly string[], framework: LayerComponentFramework, options?: Pick & ComponentGeneratorOptions): Promise; /** Layers as HTML and the stylesheet that styles it, and the images it points at. */ interface LayerMarkup { html: string; /** The layer each element of `html` draws, in the order they open, `null` for none. */ layerIds: (string | null)[]; css: string; images: ExportHTMLFile[]; } /** * Layers as indented HTML with a readable class per layer and one stylesheet, as the generated * components draw them, or with Tailwind utilities in place of the classes and no stylesheet. * Images are files under `assetBasePath` rather than inlined. */ declare function layerMarkup(graph: SceneGraph, layerIds: readonly string[], options?: Pick & ComponentGeneratorOptions & { assetBasePath?: string; }): Promise; //#endregion //#region src/tokens/conditions.d.ts /** What a feature is tested against: a keyword such as `dark`, or a length such as `640px`. */ type FeatureValue = { type: 'keyword'; name: string; } | { type: 'dimension'; value: number; unit: string; }; /** An at-rule that tests one feature: `@media (prefers-color-scheme: dark)`. */ interface FeatureCondition { rule: 'media' | 'container'; /** `prefers-color-scheme`, lowercase. */ feature: string; value: FeatureValue; } /** * Reads a condition with css-tree, so spacing, case and comments do not change what it tests, and * only what CSS calls whitespace separates its parts. Undefined for anything but one `@media` or * unnamed `@container` rule testing one feature: a selector, `@media screen`, or * `@media (a: b) and (c: d)`. */ declare function parseFeatureCondition(css: string): FeatureCondition | undefined; /** The condition as the stylesheet writes it: `@media (max-width: 640px)`. */ declare function featureConditionCSS({ rule, feature, value }: FeatureCondition): string; //#endregion //#region src/tokens/validate.d.ts type Parse = (cssText: string) => CSSStyleSheetLike; /** * Token strings come from documents, so each one is parsed in place before it is written. A value * or condition that closes its rule early parses to a different number of rules and fails. */ declare function createTokenValidator(parse: Parse): { declaration: (name: string, value: string) => boolean; /** * A custom property name without its `--`: one word to the CSS value tokenizer, which splits * on spaces, colons, commas and slashes, and one declaration to the parser. It starts with a * letter, digit or underscore, so `--` is never doubled into `----`. */ name(name: string): boolean; /** A selector, or a `@media`, `@supports` or `@container` prelude, that wraps exactly one rule. */ condition(condition: string): boolean; }; type TokenValidator = ReturnType; //#endregion //#region src/tokens/expression.d.ts /** * What a piece of a CSS value is. A finished `var(--name)` is one `reference`; while it is typed * it reads as a `function`, a `paren` and a `property`, the custom property name. */ type CSSValueTokenKind = 'reference' | 'property' | 'function' | 'paren' | 'number' | 'operator' | 'separator' | 'string' | 'keyword'; interface CSSValueToken { kind: CSSValueTokenKind; text: string; from: number; to: number; } /** * The tokens of one CSS value, such as `clamp(1rem, 4vw, var(--space-md))`, in order and with * their source ranges. Reading tolerates half-typed values: an unclosed function still gives * its name and its `(`. */ declare function cssValueTokens(source: string): CSSValueToken[]; /** The custom property a token names, in `var(--name)` or as a bare `--name`. */ declare function cssTokenProperty(token: CSSValueToken): string | undefined; type CSSExpressionProblem = { kind: 'unclosed'; } | { kind: 'syntax'; } | { kind: 'negated-reference'; property: string; } | { kind: 'unknown-token'; name: string; } | { kind: 'invalid'; property: string; }; /** * Why a CSS expression cannot stand in for a token, if it cannot. The token validator checks it * is one declaration; then it must name only tokens that exist and suit the token's unit, which * `supports` checks where a browser can type values. A value holding `var()` passes that last * check until it is used, so only its names are checked. */ declare function cssExpressionProblem(css: string, unit: TokenUnit, tokens: ReadonlySet, validator: TokenValidator, supports?: (property: string, value: string) => boolean): CSSExpressionProblem | undefined; //#endregion //#region src/tokens/names.d.ts /** Every variable, collection by collection, in each collection's own order. */ declare function collectionVariables(source: Pick): Variable[]; /** * Lowercase words joined by `-`, keeping digits on their word, as Tailwind keys do: `Text/2xl` * is `text-2xl`, `Heading/H1` is `heading-h1`, `brandPrimary` is `brand-primary`. es-toolkit's * `kebabCase` splits digits off (`text-2-xl`), which no design system writes. */ declare function tokenSlug(text: string): string; /** The Tailwind namespace a token belongs to, from its type, its scopes, then its leading name segment. */ declare function variableNamespace(variable: Variable): ThemeNamespace | undefined; /** * The custom property a code snippet names, without `--`: `var(--brand)`, `var(--brand, red)` * and `--brand` all name `brand`. A snippet that is anything else, such as a Tailwind class, * names none. */ declare function parseCSSName(snippet: string | undefined): string | undefined; /** The name `codeSyntax.WEB` gives the token, if it gives one. */ declare function explicitCSSName(variable: Variable): string | undefined; /** * `Gray/50` as COLOR is `color-gray-50`; `Space/small` is `spacing-small`. A group the next segment * repeats is said once, so `Gap/gap-1` is `gap-1`, as kits that mirror Tailwind classes name them. Two tokens can derive * the same name, so stylesheet output takes names from `variableCSSNames`, which makes them unique. */ declare function deriveCSSName(variable: Variable): string; /** * Document-wide custom property names, without `--`. The first token whose `WEB` snippet claims * a name keeps it; later claimants, which Figma files do contain, and derived names that collide * take a derived name with a numeric suffix, in iteration order. */ declare function variableCSSNames(variables: Iterable): Map; /** The `WEB` snippet that names a token in Figma's Dev Mode and here. */ declare function cssNameCodeSyntax(name: string): string; //#endregion //#region src/tokens/stylesheet.d.ts type TokenStylesheetFormat = 'css' | 'tailwind'; type TokenStylesheetIssue = { message: string; variableId?: string; collectionId?: string; modeId?: string; }; type TokenStylesheetOptions = { format: TokenStylesheetFormat; /** Write only these tokens. Names still come from every token, so aliases outside resolve. */ include?: (variable: Variable) => boolean; }; type TokenStylesheet = { css: string; issues: TokenStylesheetIssue[]; }; type TokenSource = Pick; /** The attribute a collection's manual modes are switched by, unless it names its own. */ declare function defaultModeAttributeName(collection: VariableCollection): string; /** The attribute that puts an element in a mode with no condition of its own: `data-theme`. */ declare function modeAttribute(collection: VariableCollection, mode: VariableCollectionMode): { name: string; value: string; }; /** The scope a mode applies in when it names none: `[data-theme="dark"]` for Theme / Dark. */ declare function defaultModeCondition(collection: VariableCollection, mode: VariableCollectionMode): string; /** * Variables as a stylesheet of custom properties. The default mode of every collection is the * base set, in `:root` or, for Tailwind, in `@theme` when the token has a Tailwind namespace; * every other mode overrides the values that differ, under its condition. Aliases stay `var()` * references, and number formulas `calc()` over them; both are declared again in each mode that * changes what they point to. */ declare function buildTokenStylesheet(source: TokenSource, { format, include }: TokenStylesheetOptions, validate: TokenValidator): TokenStylesheet; /** * Browsers check token strings with their own CSS parser. Elsewhere, in the CLI and MCP, the CSS * object model package loads on first use; its browser build exports nothing, so it is never * the browser path. */ declare function loadTokenValidator(): Promise; declare function tokenStylesheet(source: TokenSource, options: TokenStylesheetOptions): Promise; //#endregion //#region src/tokens/values.d.ts /** * A property that takes values in each token unit, where a browser checks or computes a CSS * expression written for the token: `scale` takes any plain number, `width` any length. */ declare const TOKEN_UNIT_PROPERTY: Record; /** * The unit a FLOAT token is written in. An explicit unit wins; opacity and font weights are * unitless; every other number is a pixel length, which is what the canvas draws. */ declare function variableUnit(variable: Variable): TokenUnit; /** A stored number written in its unit: 24 as `rem` is `1.5rem`, 150 as `ms` is `150ms`. */ declare function tokenNumberToCSS(value: number, unit: TokenUnit): string; //#endregion //#region src/behaviours/controls.d.ts /** A boolean value of a control and the property that draws it. */ interface BooleanModel { definition: ComponentPropertyDefinition; on?: string; off?: string; /** The value as the document's instance draws it. */ designed: boolean; } /** The variant property that draws a control's interaction states. */ interface StatesModel { name: string; values: NonNullable; /** The value the instance shows at rest. */ rest: string | undefined; /** Whether the document's instance is drawn disabled. */ designedDisabled: boolean; /** Whether the document's instance is drawn invalid. */ designedInvalid: boolean; } /** An instance with a behaviour below a root layer: its values, states, and bound layers. */ interface ControlModel { /** The instance's layer path below the root. */ path: string; kind: Behaviour['kind']; behaviour: Behaviour; booleans: Record; states: StatesModel | null; /** Each bound part's slot frame, by part id, as a layer path below the root. */ parts: Record; /** Each bound text value's text layer, by value id, as a layer path below the root. */ texts: Record; /** The children of the items slot that are controls themselves, in order. */ items: ControlModel[]; /** * Layers the control decides to show, which the design may hide: tab panels, or a * collapsible's content, as layer paths below the root. */ reveal: string[]; /** For tabs, each panel's layer path, in order. */ panels: string[]; /** For tabs, each trigger's layer path, in order. */ triggers: string[]; } /** * The controls below a root layer, by layer path, outermost first. Items of a group are listed * both in the group's `items` and on their own, since each keeps its own state. Preview runs * them as live islands; export generates components from them. */ declare function behaviourControls(graph: SceneGraph, rootId: string): Map; /** A control's boolean value, if the behaviour binds it. */ declare function booleanOf(control: ControlModel, valueId: string): BooleanModel | undefined; //#endregion //#region src/behaviours/reset.d.ts /** * Element styles a native `