@typecad/ui 0.1.0-alpha.1

package/dist/ui-engine/keyframes.js

@@ -0,0 +1,39 @@
+import { resolveColor } from "./color.js";
+import { clampInt16, cssOpacityToPercent, cssPx, KEYFRAME_PROP_BG, KEYFRAME_PROP_FG, KEYFRAME_PROP_OPACITY, KEYFRAME_PROP_SIZE, KEYFRAME_PROP_TRANSFORM, parseTransform, } from "./model.js";
+export function buildKeyframeSets(rawKeyframes, colorFormat) {
+    return rawKeyframes.map((ks) => ({
+        name: ks.name,
+        stops: ks.stops.map((stop) => {
+            let props = 0;
+            if (stop.background)
+                props |= KEYFRAME_PROP_BG;
+            if (stop.color)
+                props |= KEYFRAME_PROP_FG;
+            if (stop.opacity)
+                props |= KEYFRAME_PROP_OPACITY;
+            if (stop.transform || stop.left || stop.top)
+                props |= KEYFRAME_PROP_TRANSFORM;
+            if (stop.width || stop.height)
+                props |= KEYFRAME_PROP_SIZE;
+            const transform = parseTransform(stop.transform);
+            const x = transform.x + cssPx(stop.left);
+            const y = transform.y + cssPx(stop.top);
+            return {
+                percent: stop.percent,
+                props,
+                bg: stop.background ? resolveColor(stop.background, colorFormat) : 0,
+                fg: stop.color ? resolveColor(stop.color, colorFormat) : 0,
+                opacity: stop.opacity ? cssOpacityToPercent(stop.opacity) : 100,
+                transformOffsetX: clampInt16(x),
+                transformOffsetY: clampInt16(y),
+                translatePctX: clampInt16(transform.pctX),
+                translatePctY: clampInt16(transform.pctY),
+                scaleX: transform.scaleX,
+                scaleY: transform.scaleY,
+                rotateDeg: clampInt16(transform.rotateDeg),
+                width: stop.width ? Math.max(0, Math.min(32767, cssPx(stop.width))) : 0,
+                height: stop.height ? Math.max(0, Math.min(32767, cssPx(stop.height))) : 0,
+            };
+        }),
+    }));
+}

package/dist/ui-engine/layout-engine.d.ts

@@ -0,0 +1,35 @@
+import { StyledNode } from "./style-resolver.js";
+import type { UIFontAssetModel } from "./font-assets.js";
+export interface Box {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface IntrinsicSize {
+    w: number;
+    h: number;
+}
+export interface LayoutEngine {
+    /** Engine id, used to select on the `display` style property. */
+    readonly id: "block" | "flex" | "grid";
+    /**
+     * Arrange a styled tree into a flat list of boxes (pre-order, root first).
+     * measureFn provides intrinsic sizes (e.g. text dimensions from the font).
+     */
+    arrange(root: StyledNode, viewport: Box, measureFn: (node: StyledNode, availableWidth?: number) => IntrinsicSize): Box[];
+}
+/** Static display:none predicate shared by layout engines and lowering. */
+export declare function isDisplayNone(node: StyledNode): boolean;
+/** Parse CSS aspect-ratio values: "16 / 9", "1/1", or "1.777". */
+export declare function parseAspectRatio(value: string | undefined): number | undefined;
+/** Measure a node's intrinsic size. Accounts for the Adafruit GFX font metrics
+ *  and the text size the draw dispatch will use. When `fontAssets` is provided,
+ *  text widths use the real per-glyph advances of any matching custom
+ *  @font-face (the runtime draws at those advances); otherwise they fall back
+ *  to the 6*ts default-font advance. */
+export declare function measure(node: StyledNode, availableWidth?: number, fontAssets?: UIFontAssetModel[]): IntrinsicSize;
+/** Bind a set of font assets to measure(), returning a measureFn the layout
+ *  engines accept. Text nodes using a custom @font-face then measure at the
+ *  font's real glyph advances; nodes on the default font are unaffected. */
+export declare function measureWithFonts(fontAssets: UIFontAssetModel[]): (node: StyledNode, availableWidth?: number) => IntrinsicSize;

package/dist/ui-engine/layout-engine.js

@@ -0,0 +1,203 @@
+// ---------------------------------------------------------------------------
+// Layout engine — pluggable, staged layout.
+//
+//   style tree  →  measure pass  →  arrange pass (engine)  →  computed boxes
+//
+// v1 ships BlockLayoutEngine only. The LayoutEngine interface + measure()
+// are built so that FlexLayoutEngine (v2) is a pure addition: no rewrite of
+// measure, the style tree, the node representation, or the draw layer.
+//
+// measure() is general (returns intrinsic {w,h}) even though block layout
+// only needs it for text — flex reuses it for flex-basis:content.
+// ---------------------------------------------------------------------------
+import { layoutText } from "./text-layout.js";
+import { layoutRuns } from "./rich-layout.js";
+import { assetTextWidth } from "./font-assets.js";
+/** Static display:none predicate shared by layout engines and lowering. */
+export function isDisplayNone(node) {
+    return node.style.display?.trim().toLowerCase() === "none";
+}
+/** Parse CSS aspect-ratio values: "16 / 9", "1/1", or "1.777". */
+export function parseAspectRatio(value) {
+    const raw = value?.trim().toLowerCase();
+    if (!raw || raw === "auto")
+        return undefined;
+    const parts = raw.split("/").map((part) => part.trim()).filter(Boolean);
+    if (parts.length === 1) {
+        const ratio = parseFloat(parts[0]);
+        return Number.isFinite(ratio) && ratio > 0 ? ratio : undefined;
+    }
+    if (parts.length === 2) {
+        const width = parseFloat(parts[0]);
+        const height = parseFloat(parts[1]);
+        if (Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0) {
+            return width / height;
+        }
+    }
+    return undefined;
+}
+// The Adafruit GFX default font: 5×7 pixel glyphs, 6px advance width per char.
+// At setTextSize(N), advance = 6×N, height = 8×N (7 glyph + 1 descender line).
+// The draw dispatch in the runtime header uses setTextSize(2).
+const GFX_TEXT_SIZE = 2;
+const GFX_ADVANCE_PER_CHAR = 6 * GFX_TEXT_SIZE; // 12px at size 2
+const GFX_CHAR_HEIGHT = 8 * GFX_TEXT_SIZE; // 16px at size 2
+/** Compute the GFX text size from a node's CSS font-size.
+ *  Mirrors the logic in model.ts textSizeOf(). font-weight does NOT inflate
+ *  the bucket (matching web behavior); see model.ts:textSizeOf for rationale. */
+function gfxTextSizeOf(node) {
+    let size = GFX_TEXT_SIZE;
+    if (node.style.fontSize) {
+        const px = parseInt(node.style.fontSize, 10);
+        if (!isNaN(px)) {
+            if (px <= 12)
+                size = 1;
+            else if (px <= 20)
+                size = 2;
+            else if (px <= 28)
+                size = 3;
+            else
+                size = 4;
+        }
+    }
+    return size;
+}
+function letterSpacingOf(node) {
+    if (!node.style.letterSpacing)
+        return 0;
+    const px = parseInt(node.style.letterSpacing, 10);
+    return Number.isFinite(px) ? px : 0;
+}
+function lineHeightOf(node, charH) {
+    const raw = node.style.lineHeight?.trim();
+    if (!raw || raw === "normal")
+        return charH;
+    if (raw.endsWith("%")) {
+        const pct = parseFloat(raw);
+        return Number.isFinite(pct) ? Math.max(1, Math.round(charH * pct / 100)) : charH;
+    }
+    if (/^-?\d*\.?\d+$/.test(raw)) {
+        const n = parseFloat(raw);
+        return Number.isFinite(n) ? Math.max(1, Math.round(charH * n)) : charH;
+    }
+    const px = parseInt(raw, 10);
+    return Number.isFinite(px) && px > 0 ? px : charH;
+}
+function applyTextTransform(text, node) {
+    const value = text ?? "";
+    switch (node.style.textTransform) {
+        case "uppercase": return value.toUpperCase();
+        case "lowercase": return value.toLowerCase();
+        case "capitalize": return value.replace(/\b\w/g, (c) => c.toUpperCase());
+        default: return value;
+    }
+}
+function textWidthOf(text, advance) {
+    let w = 0;
+    for (const _ch of text)
+        w += advance;
+    return w;
+}
+/** Measure a node's intrinsic size. Accounts for the Adafruit GFX font metrics
+ *  and the text size the draw dispatch will use. When `fontAssets` is provided,
+ *  text widths use the real per-glyph advances of any matching custom
+ *  @font-face (the runtime draws at those advances); otherwise they fall back
+ *  to the 6*ts default-font advance. */
+export function measure(node, availableWidth, fontAssets = []) {
+    // Rich-text (inline runs): size the node from its multi-run layout. Each run
+    // is measured at its own font/size advance (per-run style), and the laid-out
+    // width/height drive the node's box. This keeps flex sizing in sync with the
+    // precomputed runLines the lowering bakes (and the runtime draws).
+    if (node.runs && node.runs.length > 0) {
+        const layoutInput = node.runs.map(r => {
+            const rs = { ...node.style, ...r.style };
+            const rTs = gfxTextSizeOf({ ...node, style: rs });
+            const rAdvance = 6 * rTs + letterSpacingOf({ ...node, style: rs });
+            return {
+                text: applyTextTransform(r.text, { ...node, style: rs }),
+                hardBreak: r.hardBreak,
+                measureText: (s) => assetTextWidth(s, rs, fontAssets) ?? textWidthOf(s, rAdvance),
+                height: 8 * rTs,
+                ascent: 7 * rTs,
+            };
+        });
+        const layout = layoutRuns(layoutInput, { maxWidth: availableWidth, whiteSpace: node.style.whiteSpace });
+        return { w: layout.width, h: layout.height };
+    }
+    // Per-node text size (from font-size + font-weight CSS).
+    const ts = gfxTextSizeOf(node);
+    const advance = 6 * ts + letterSpacingOf(node);
+    const charH = 8 * ts;
+    // For interpolation text (e.g. "taps: {count}"), strip the braces so layout
+    // measures "taps: count" — closer to the resolved runtime width than the
+    // literal "{count}". The braces are an authoring delimiter, not rendered.
+    const stripInterp = (value) => node.hasInterpolation ? (value ?? "").replace(/[{}]/g, "") : (value ?? "");
+    // Width of a string using the asset font's real advances when the node has
+    // one, else the 6*ts default-font advance. This keeps the measured box width
+    // in sync with what the runtime actually draws (avoids overflow/clipping).
+    const widthOf = (value) => assetTextWidth(stripInterp(value), node.style, fontAssets) ?? textWidthOf(stripInterp(value), advance);
+    if (node.tag === "text" || node.tag === "button" || node.tag === "select") {
+        if (node.tag === "select") {
+            // Size to the longest option, not the full comma-separated text
+            const options = node.options && node.options.length > 0
+                ? node.options.map((option) => option.text)
+                : (node.text ?? "").split(",").map(s => s.trim()).filter(Boolean);
+            const longest = options.length > 0 ? options.reduce((a, b) => a.length >= b.length ? a : b) : "";
+            return { w: widthOf(applyTextTransform(longest, node)), h: lineHeightOf(node, charH) };
+        }
+        const text = applyTextTransform(stripInterp(node.text), node);
+        const layout = layoutText(text, {
+            maxWidth: availableWidth,
+            whiteSpace: node.style.whiteSpace,
+            lineHeight: lineHeightOf(node, charH),
+            measureText: widthOf,
+        });
+        return { w: layout.width, h: layout.height };
+    }
+    if (node.tag === "check" || node.tag === "radio") {
+        // Checkbox/radio: 16px indicator + 6px gap + label text
+        const text = applyTextTransform(stripInterp(node.text), node);
+        const labelMaxWidth = availableWidth !== undefined ? Math.max(0, availableWidth - 22) : undefined;
+        const layout = layoutText(text, {
+            maxWidth: labelMaxWidth,
+            whiteSpace: node.style.whiteSpace,
+            lineHeight: lineHeightOf(node, charH),
+            measureText: widthOf,
+        });
+        return { w: 16 + 6 + layout.width, h: Math.max(layout.height, 16) };
+    }
+    if (node.tag === "progress") {
+        // Progress bar: default 200px wide, 12px tall
+        return { w: 200, h: 12 };
+    }
+    if (node.tag === "range") {
+        // Slider: default 200px wide, 20px tall (roomy track for touch)
+        return { w: 200, h: 20 };
+    }
+    if (node.tag === "input") {
+        // Input field: sized to the placeholder or a default width, 20px tall.
+        const text = node.placeholder ?? "";
+        const textW = text.length > 0 ? text.length * GFX_ADVANCE_PER_CHAR : 120;
+        return { w: Math.max(textW + 16, 120), h: 20 };
+    }
+    if (node.tag === "img") {
+        return { w: node.imgWidth ?? 32, h: node.imgHeight ?? 32 };
+    }
+    if (node.tag === "canvas") {
+        // Canvas intrinsic size = its width/height attributes. Without this the
+        // layout collapsed the node to 0x0 (no intrinsic size), so ui.drawCanvas
+        // content drew into a 2x2 sliver and was invisible.
+        return { w: node.canvasW ?? 0, h: node.canvasH ?? 0 };
+    }
+    if (node.tag === "list") {
+        return { w: 0, h: 100 }; // lists default to 100px tall, expand via flex
+    }
+    // Containers have no intrinsic size in block layout — they fill available.
+    return { w: 0, h: 0 };
+}
+/** Bind a set of font assets to measure(), returning a measureFn the layout
+ *  engines accept. Text nodes using a custom @font-face then measure at the
+ *  font's real glyph advances; nodes on the default font are unaffected. */
+export function measureWithFonts(fontAssets) {
+    return (node, availableWidth) => measure(node, availableWidth, fontAssets);
+}

package/dist/ui-engine/model.d.ts

@@ -0,0 +1,239 @@
+import type { DisplayProfile } from "@typecad/cuttlefish/api/shared";
+import type { UIFontAssetModel } from "./font-assets.js";
+import type { UIImageAsset } from "./image-assets.js";
+import { type Box } from "./layout-engine.js";
+import type { StyledNode } from "./style-resolver.js";
+export { easeCurveLerpK, TIMING_EASE, TIMING_EASE_IN, TIMING_EASE_IN_OUT, TIMING_EASE_OUT, TIMING_LINEAR, timingFunctionCode, } from "./easing.js";
+export type UINodeKindModel = "fill" | "text" | "button" | "check" | "radio" | "progress" | "range" | "input" | "img" | "list" | "canvas";
+export type UIPropertyModel = "background" | "color" | "text" | "visible" | "borderColor";
+export interface UINodeModel {
+    index: number;
+    tag: string;
+    id?: string;
+    classes: string[];
+    box: Box;
+    bg: number;
+    fg: number;
+    kind: UINodeKindModel;
+    text?: string;
+    placeholder?: string;
+    valueAttr?: string;
+    name?: string;
+    checked?: boolean;
+    textBuffer: string;
+    hasTextBinding: boolean;
+    hasBg: boolean;
+    textAlign: 0 | 1 | 2;
+    textSize: number;
+    lineHeight: number;
+    letterSpacing: number;
+    fontAntialias: boolean;
+    fontFace: number;
+    borderColor: number;
+    borderStyle: 0 | 1 | 2;
+    borderWidth: number;
+    /** Per-side border widths. When all four equal borderWidth, the runtime draws
+     *  the uniform rect outline; when any differs, it draws per-side lines. */
+    borderTopWidth: number;
+    borderRightWidth: number;
+    borderBottomWidth: number;
+    borderLeftWidth: number;
+    borderRadius: number;
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    gradientEnabled: number;
+    gradientColor1: number;
+    gradientColor2: number;
+    outlineColor: number;
+    outlineStyle: 0 | 1 | 2;
+    outlineWidth: number;
+    zIndex: number;
+    transformOffsetX: number;
+    transformOffsetY: number;
+    rotateDeg: number;
+    pressedOffsetX: number;
+    pressedOffsetY: number;
+    shadowCount: number;
+    shadowOffsetX: number[];
+    shadowOffsetY: number[];
+    shadowBlur: number[];
+    shadowColor: number[];
+    shadowAlpha: number[];
+    shadowInset: boolean[];
+    textShadowCount: number;
+    textShadowOffsetX: number;
+    textShadowOffsetY: number;
+    textShadowBlur: number;
+    textShadowColor: number;
+    textShadowAlpha: number;
+    underline: number;
+    textOverflow: boolean;
+    nowrap: boolean;
+    whiteSpaceMode: 0 | 1 | 2 | 3;
+    visible: boolean;
+    opacity: number;
+    clearColor: number;
+    lastTextWidth: number;
+    lastTextHeight: number;
+    dirty: boolean;
+    value: number;
+    options?: Array<{
+        value: string;
+        text: string;
+    }>;
+    scrollable: boolean;
+    scrollY: number;
+    contentHeight: number;
+    /** Elastic excursion past a scroll boundary (0 in-bounds; +top, -bottom). */
+    overscrollPx: number;
+    /** True while a bounce-back / edge-snap settle animation is running. */
+    settling: boolean;
+    /** scrollY captured at the last container repaint (Mode B shift delta). */
+    lastPaintedScrollY: number;
+    rangeMin: number;
+    rangeMax: number;
+    /** For <input>: max character length (0 = use UI_TEXT_BUF). */
+    maxlen: number;
+    /** For <input>: text or number keyboard. */
+    inputType?: "text" | "number";
+    /** For <input>: custom keyboard template id. */
+    keyboard?: string;
+    parentIndex: number;
+    subtreeEnd: number;
+    screenId: number;
+    imgDataId: number;
+    objectFit: 0 | 1 | 2 | 3 | 4;
+    listItemHeight: number;
+    /** Children are produced by callbacks (virtualized), not static nodes. Set for <list>. */
+    virtualized: boolean;
+    /** Canvas buffer width in pixels (for kind "canvas"). */
+    canvasW: number;
+    /** Canvas buffer height in pixels (for kind "canvas"). */
+    canvasH: number;
+    /** Rich-text runs. Present only for text nodes with mixed inline content;
+     *  absent for plain single-string text nodes. When present, the runs are the
+     *  node's content and `text` is empty. */
+    runs?: UITextRunModel[];
+    /** Precomputed wrapped-line geometry for rich-text runs (struct-of-arrays).
+     *  The parallel arrays are indexed together; segment i is
+     *  (segRun[i], segText[i], segX[i], segW[i], segLine[i]). Baked at lower time
+     *  because runs are static-content only (no runtime re-flow). */
+    runLines?: RunLines;
+}
+/** One rich-text run in lowered form: a piece of styled inline text with all
+ *  style fields pre-resolved to their runtime representations. */
+export interface UITextRunModel {
+    text: string;
+    /** Resolved RGB565/mono foreground color. */
+    fg: number;
+    /** GFX text size 1-4 (from run font-size + font-weight). */
+    textSize: number;
+    /** Font asset id (0 = classic GFX bitmap font). */
+    fontFace: number;
+    /** text-decoration: 0=none, 1=underline, 2=line-through, 3=both. */
+    underline: number;
+    /** Letter spacing in px. */
+    letterSpacing: number;
+    /** Resolved screen index for an <a href> run, or -1 if not a link. */
+    linkTarget: number;
+}
+/** Precomputed wrapped-line geometry for a rich-text node, as parallel arrays
+ *  (mirrors how the C++ runtime emits them). Segment arrays are indexed
+ *  together; each segment belongs to the line given by its segLine entry. */
+export interface RunLines {
+    segRun: number[];
+    segText: string[];
+    segX: number[];
+    segW: number[];
+    segLine: number[];
+    lineY: number[];
+    lineH: number[];
+    lineBaseline: number[];
+    lineW: number[];
+}
+export interface UITransitionModel {
+    node: number;
+    prop: "background" | "color";
+    durationMs: number;
+    pressedTarget: number;
+    baseTarget: number;
+    elapsed: number;
+    prevValue: number;
+    targetValue: number;
+    active: boolean;
+}
+export interface KeyframeStopModel {
+    percent: number;
+    props: number;
+    bg: number;
+    fg: number;
+    opacity: number;
+    transformOffsetX: number;
+    transformOffsetY: number;
+    translatePctX: number;
+    translatePctY: number;
+    scaleX: number;
+    scaleY: number;
+    rotateDeg: number;
+    width: number;
+    height: number;
+}
+export declare const KEYFRAME_PROP_BG = 1;
+export declare const KEYFRAME_PROP_FG = 2;
+export declare const KEYFRAME_PROP_OPACITY = 4;
+export declare const KEYFRAME_PROP_TRANSFORM = 8;
+export declare const KEYFRAME_PROP_SIZE = 16;
+export interface KeyframeSetModel {
+    name: string;
+    stops: KeyframeStopModel[];
+}
+export interface AnimationModel {
+    node: number;
+    keyframeSet: number;
+    durationMs: number;
+    delayMs: number;
+    iterations: number;
+    baseWidth: number;
+    baseHeight: number;
+    originX: number;
+    originY: number;
+    timingFunction: number;
+}
+export interface UIProgram {
+    width: number;
+    height: number;
+    colorFormat: "rgb565" | "rgb666" | "rgb888" | "mono";
+    display?: DisplayProfile;
+    fontAssets: UIFontAssetModel[];
+    imageAssets: UIImageAsset[];
+    nodes: UINodeModel[];
+    transitions: UITransitionModel[];
+    keyframeSets: KeyframeSetModel[];
+    animations: AnimationModel[];
+}
+type ColorFormat = "rgb565" | "rgb666" | "rgb888" | "mono";
+export declare function cssPx(value: string | undefined): number;
+export declare function clampInt8(n: number): number;
+export declare function clampInt16(n: number): number;
+export interface ParsedTransform {
+    x: number;
+    y: number;
+    pctX: number;
+    pctY: number;
+    scaleX: number;
+    scaleY: number;
+    rotateDeg: number;
+}
+export declare function parseTransform(transform: string | undefined): ParsedTransform;
+export declare function transformOffset(transform: string | undefined): {
+    x: number;
+    y: number;
+};
+export declare function transformOriginPercent(value: string | undefined): {
+    x: number;
+    y: number;
+};
+export declare function cssOpacityToPercent(value: string | undefined): number;
+export declare function lowerUIToModel(root: StyledNode, boxes: Box[], colorFormat: ColorFormat, display?: DisplayProfile, fontAssets?: UIFontAssetModel[], allScreens?: StyledNode[], imageAssetIds?: Map<string, number>, keyframeSets?: KeyframeSetModel[], imageAssets?: UIImageAsset[]): UIProgram;