@slowclap/rezi-core 0.1.0-fork.1

package/dist/constraints/graph.js

@@ -0,0 +1,359 @@
+/**
+ * packages/core/src/constraints/graph.ts — Constraint dependency graph builder.
+ *
+ * Why: Builds and validates expression dependencies before evaluation.
+ */
+import { isConstraintExpr } from "./expr.js";
+import { collectWidgetRefUsages, findUnknownFunctionName } from "./parser.js";
+const CONSTRAINT_PROPS = Object.freeze([
+    "width",
+    "height",
+    "minWidth",
+    "maxWidth",
+    "minHeight",
+    "maxHeight",
+    "flexBasis",
+    "display",
+]);
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+const EMPTY_KEYS = Object.freeze([]);
+function invalid(detail) {
+    return { ok: false, fatal: { code: "ZRUI_INVALID_CONSTRAINT", detail } };
+}
+function hashU32(hash, value) {
+    return Math.imul((hash ^ (value >>> 0)) >>> 0, FNV_PRIME) >>> 0;
+}
+function hashString(hash, value) {
+    let out = hashU32(hash, value.length);
+    for (let i = 0; i < value.length; i++) {
+        out = hashU32(out, value.charCodeAt(i));
+    }
+    return out;
+}
+function readWidgetId(node) {
+    const props = node.vnode.props;
+    const id = props?.id;
+    return typeof id === "string" && id.length > 0 ? id : null;
+}
+function makeNodeKey(instanceId, prop) {
+    return `${String(instanceId)}:${prop}`;
+}
+function makeInstancePropKey(instanceId, prop) {
+    return `${String(instanceId)}:${prop}`;
+}
+function addInstanceToIdIndex(index, id, instanceId) {
+    const group = index.get(id);
+    if (group === undefined) {
+        index.set(id, [instanceId]);
+        return;
+    }
+    group.push(instanceId);
+}
+function freezeIdIndex(index) {
+    const frozen = new Map();
+    for (const [id, instances] of index.entries()) {
+        frozen.set(id, Object.freeze(instances.slice()));
+    }
+    return frozen;
+}
+function maybeAddDisplayDependency(instanceId, currentNodeKey, deps, instancePropToNodeKey) {
+    const displayKey = instancePropToNodeKey.get(makeInstancePropKey(instanceId, "display"));
+    if (displayKey !== undefined && displayKey !== currentNodeKey)
+        deps.add(displayKey);
+}
+function refPropToConstraintProp(prop) {
+    switch (prop) {
+        case "w":
+            return "width";
+        case "h":
+            return "height";
+        case "min_w":
+            return "minWidth";
+        case "min_h":
+            return "minHeight";
+        default:
+            return "width";
+    }
+}
+function propLabel(prop) {
+    return prop;
+}
+function labelNode(node) {
+    const prop = propLabel(node.prop);
+    if (node.widgetId !== null)
+        return `#${node.widgetId}.${prop}`;
+    return `#${String(node.instanceId)}.${prop}`;
+}
+function findCyclePath(remaining, edges) {
+    const visitingStack = [];
+    const visitingIndex = new Map();
+    const visited = new Set();
+    const visit = (key) => {
+        visited.add(key);
+        visitingIndex.set(key, visitingStack.length);
+        visitingStack.push(key);
+        const deps = edges.get(key) ?? EMPTY_KEYS;
+        for (const dep of deps) {
+            if (!remaining.has(dep))
+                continue;
+            const loopIndex = visitingIndex.get(dep);
+            if (loopIndex !== undefined) {
+                const cycle = visitingStack.slice(loopIndex);
+                cycle.push(dep);
+                return cycle;
+            }
+            if (!visited.has(dep)) {
+                const nested = visit(dep);
+                if (nested !== null)
+                    return nested;
+            }
+        }
+        visitingStack.pop();
+        visitingIndex.delete(key);
+        return null;
+    };
+    for (const key of remaining) {
+        if (visited.has(key))
+            continue;
+        const cycle = visit(key);
+        if (cycle !== null)
+            return cycle;
+    }
+    return EMPTY_KEYS;
+}
+function computeFingerprint(nodes) {
+    let hash = FNV_OFFSET;
+    for (const node of nodes) {
+        hash = hashU32(hash, node.instanceId);
+        hash = hashString(hash, node.prop);
+        hash = hashString(hash, node.expr.source);
+    }
+    return hash >>> 0;
+}
+export function topologicalSort(graph) {
+    if (graph.nodes.length === 0) {
+        return { ok: true, value: Object.freeze([]) };
+    }
+    const inDegree = new Map();
+    const dependents = new Map();
+    for (const node of graph.nodes) {
+        const deps = graph.edges.get(node.key) ?? EMPTY_KEYS;
+        inDegree.set(node.key, deps.length);
+        for (const dep of deps) {
+            const list = dependents.get(dep);
+            if (list === undefined) {
+                dependents.set(dep, [node.key]);
+            }
+            else {
+                list.push(node.key);
+            }
+        }
+    }
+    const queue = [];
+    for (const node of graph.nodes) {
+        if ((inDegree.get(node.key) ?? 0) === 0)
+            queue.push(node.key);
+    }
+    const orderedKeys = [];
+    let head = 0;
+    while (head < queue.length) {
+        const key = queue[head];
+        head++;
+        if (key === undefined)
+            continue;
+        orderedKeys.push(key);
+        const nextNodes = dependents.get(key) ?? [];
+        for (const next of nextNodes) {
+            const nextDegree = (inDegree.get(next) ?? 0) - 1;
+            inDegree.set(next, nextDegree);
+            if (nextDegree === 0)
+                queue.push(next);
+        }
+    }
+    if (orderedKeys.length !== graph.nodes.length) {
+        const remaining = new Set();
+        for (const node of graph.nodes) {
+            if ((inDegree.get(node.key) ?? 0) > 0)
+                remaining.add(node.key);
+        }
+        const cycleKeys = findCyclePath(remaining, graph.edges);
+        const cycle = cycleKeys.map((key) => {
+            const node = graph.nodeByKey.get(key);
+            return node === undefined ? key : labelNode(node);
+        });
+        return {
+            ok: false,
+            fatal: {
+                code: "ZRUI_CIRCULAR_CONSTRAINT",
+                cycle: Object.freeze(cycle),
+            },
+        };
+    }
+    const order = [];
+    for (const key of orderedKeys) {
+        const node = graph.nodeByKey.get(key);
+        if (node !== undefined)
+            order.push(node);
+    }
+    return { ok: true, value: Object.freeze(order) };
+}
+export function buildConstraintGraph(root) {
+    const collected = [];
+    const idToInstancesMutable = new Map();
+    const siblingIdToInstancesByParentMutable = new Map();
+    const instanceIdToWidgetIdMutable = new Map();
+    let requiresCommitRelayout = false;
+    let hasDisplayConstraints = false;
+    const stack = [
+        { node: root, parent: null },
+    ];
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (frame === undefined)
+            break;
+        const { node, parent } = frame;
+        const widgetId = readWidgetId(node);
+        if (widgetId !== null) {
+            instanceIdToWidgetIdMutable.set(node.instanceId, widgetId);
+            addInstanceToIdIndex(idToInstancesMutable, widgetId, node.instanceId);
+            const siblingGroups = siblingIdToInstancesByParentMutable.get(parent);
+            if (siblingGroups === undefined) {
+                const nextSiblingGroups = new Map();
+                addInstanceToIdIndex(nextSiblingGroups, widgetId, node.instanceId);
+                siblingIdToInstancesByParentMutable.set(parent, nextSiblingGroups);
+            }
+            else {
+                addInstanceToIdIndex(siblingGroups, widgetId, node.instanceId);
+            }
+        }
+        const props = (node.vnode.props ?? {});
+        for (const prop of CONSTRAINT_PROPS) {
+            const candidate = props[prop];
+            if (!isConstraintExpr(candidate))
+                continue;
+            collected.push({
+                key: makeNodeKey(node.instanceId, prop),
+                instanceId: node.instanceId,
+                parentInstanceId: parent,
+                widgetId,
+                prop,
+                expr: candidate,
+            });
+        }
+        for (let i = node.children.length - 1; i >= 0; i--) {
+            const child = node.children[i];
+            if (child === undefined)
+                continue;
+            stack.push({ node: child, parent: node.instanceId });
+        }
+    }
+    const nodeByKey = new Map();
+    const instancePropToNodeKey = new Map();
+    for (const node of collected) {
+        nodeByKey.set(node.key, node);
+        instancePropToNodeKey.set(makeInstancePropKey(node.instanceId, node.prop), node.key);
+    }
+    const edgesMutable = new Map();
+    const requiredRuntimeInstanceIds = new Set();
+    const intrinsicRuntimeInstanceIds = new Set();
+    for (const node of collected) {
+        const unknownFunction = findUnknownFunctionName(node.expr.ast);
+        if (unknownFunction !== null) {
+            return invalid(`Unknown function "${unknownFunction}" in ${labelNode(node)} (${node.expr.source}). Hint: Check the constraint function allowlist (clamp/min/max/floor/ceil/round/abs/if/max_sibling/sum_sibling/steps), or prefer helper constraints for common patterns.`);
+        }
+        requiredRuntimeInstanceIds.add(node.instanceId);
+        if (node.prop === "display" || node.expr.hasIntrinsic || node.expr.hasSiblingAggregation) {
+            requiresCommitRelayout = true;
+            if (node.prop === "display")
+                hasDisplayConstraints = true;
+        }
+        if (node.expr.hasIntrinsic)
+            intrinsicRuntimeInstanceIds.add(node.instanceId);
+        const deps = new Set();
+        const usages = collectWidgetRefUsages(node.expr.ast);
+        for (const usage of usages) {
+            const instances = idToInstancesMutable.get(usage.id);
+            if (instances === undefined || instances.length === 0) {
+                return invalid(`Unknown widget reference "#${usage.id}.${usage.prop}" in ${labelNode(node)} (${node.expr.source}). Hint: Ensure the referenced id exists in the committed tree (and isn't conditionally omitted via show()/branching).`);
+            }
+            if (usage.viaAggregation) {
+                const siblingInstances = siblingIdToInstancesByParentMutable.get(node.parentInstanceId)?.get(usage.id) ?? [];
+                if (siblingInstances.length === 0) {
+                    return invalid(`Sibling aggregation "#${usage.id}.${usage.prop}" in ${labelNode(node)} (${node.expr.source}) has no matching sibling group. Hint: max_sibling()/sum_sibling() only see widgets with the same parent.`);
+                }
+                for (const instanceId of siblingInstances) {
+                    requiredRuntimeInstanceIds.add(instanceId);
+                    const depProp = refPropToConstraintProp(usage.prop);
+                    const depKey = instancePropToNodeKey.get(makeInstancePropKey(instanceId, depProp));
+                    if (depKey !== undefined)
+                        deps.add(depKey);
+                    else
+                        intrinsicRuntimeInstanceIds.add(instanceId);
+                    // Hidden nodes resolve sibling metric refs as zero, so depend on display first when present.
+                    maybeAddDisplayDependency(instanceId, node.key, deps, instancePropToNodeKey);
+                }
+                continue;
+            }
+            if (instances.length !== 1) {
+                return invalid(`Direct widget reference "#${usage.id}.${usage.prop}" in ${labelNode(node)} is ambiguous. Hint: Use max_sibling()/sum_sibling() (or the groupConstraints helpers) for shared IDs.`);
+            }
+            const instanceId = instances[0];
+            if (instanceId === undefined)
+                continue;
+            requiredRuntimeInstanceIds.add(instanceId);
+            const depProp = refPropToConstraintProp(usage.prop);
+            const depKey = instancePropToNodeKey.get(makeInstancePropKey(instanceId, depProp));
+            if (depKey !== undefined) {
+                deps.add(depKey);
+            }
+            else {
+                // Direct ref to an unconstrained metric falls back to baseline layout/intrinsic
+                // values and can change on commit even when layout-key props appear stable.
+                requiresCommitRelayout = true;
+                intrinsicRuntimeInstanceIds.add(instanceId);
+            }
+            // Hidden nodes resolve sibling metric refs as zero, so depend on display first when present.
+            maybeAddDisplayDependency(instanceId, node.key, deps, instancePropToNodeKey);
+        }
+        edgesMutable.set(node.key, Object.freeze([...deps]));
+    }
+    const nodes = Object.freeze(collected.slice());
+    const constrainedInstanceIds = new Set();
+    for (const node of nodes) {
+        constrainedInstanceIds.add(node.instanceId);
+    }
+    const idToInstances = new Map();
+    for (const [id, instances] of idToInstancesMutable.entries()) {
+        idToInstances.set(id, Object.freeze(instances.slice()));
+    }
+    const siblingIdToInstancesByParentId = new Map();
+    for (const [parentId, siblingGroups] of siblingIdToInstancesByParentMutable.entries()) {
+        siblingIdToInstancesByParentId.set(parentId, freezeIdIndex(siblingGroups));
+    }
+    const instanceIdToWidgetId = new Map(instanceIdToWidgetIdMutable.entries());
+    const edges = new Map(edgesMutable.entries());
+    const fingerprint = computeFingerprint(nodes);
+    const sorted = topologicalSort({ nodes, edges, nodeByKey });
+    if (!sorted.ok)
+        return sorted;
+    return {
+        ok: true,
+        value: {
+            nodes,
+            edges,
+            order: sorted.value,
+            fingerprint,
+            requiresCommitRelayout,
+            hasDisplayConstraints,
+            constrainedInstanceIds: Object.freeze(constrainedInstanceIds),
+            requiredRuntimeInstanceIds: Object.freeze(requiredRuntimeInstanceIds),
+            intrinsicRuntimeInstanceIds: Object.freeze(intrinsicRuntimeInstanceIds),
+            nodeByKey,
+            idToInstances,
+            siblingIdToInstancesByParentId,
+            instanceIdToWidgetId,
+        },
+    };
+}
+//# sourceMappingURL=graph.js.map

package/dist/constraints/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../src/constraints/graph.ts"],"names":[],"mappings":"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"}

package/dist/constraints/helpers.d.ts

@@ -0,0 +1,191 @@
+/**
+ * packages/core/src/constraints/helpers.ts — High-level constraint helpers.
+ *
+ * Why: Most app code should express layout intent without writing raw expression strings.
+ * These helpers compile to `expr("...")` using the existing DSL (same determinism/error rules).
+ *
+ * See: docs/rfc/002-constraint-helper-layer.md
+ */
+import type { ConstraintExpr } from "./types.js";
+export type ConstraintValue = number | ConstraintExpr;
+export type WidgetMetric = "width" | "height" | "minWidth" | "minHeight";
+export type SiblingAggregation = "none" | "max" | "sum";
+export type SpaceTerm = Readonly<{
+    id: string;
+    metric?: WidgetMetric;
+    aggregation?: SiblingAggregation;
+}>;
+export declare const visibilityConstraints: Readonly<{
+    /**
+     * Show when viewport width is at least `cols`.
+     *
+     * Returns a constraint expression suitable for `display: ...`.
+     */
+    viewportWidthAtLeast(cols: number): ConstraintExpr;
+    /** Show when viewport width is below `cols`. */
+    viewportWidthBelow(cols: number): ConstraintExpr;
+    /** Show when viewport height is at least `rows`. */
+    viewportHeightAtLeast(rows: number): ConstraintExpr;
+    /** Show when viewport height is below `rows`. */
+    viewportHeightBelow(rows: number): ConstraintExpr;
+    /**
+     * Show when the viewport is at least the given size.
+     *
+     * Use this when a region only makes sense above both a width and height threshold.
+     *
+     * Returns a constraint expression suitable for `display: ...`.
+     */
+    viewportAtLeast(options: Readonly<{
+        width?: number;
+        height?: number;
+    }>): ConstraintExpr;
+}>;
+export declare const conditionalConstraints: Readonly<{
+    /**
+     * Intent wrapper for `if(cond, then, else)`.
+     *
+     * Notes:
+     * - `cond > 0` is truthy (same as the underlying DSL).
+     * - `thenValue` / `elseValue` may be numbers or other constraints for composition.
+     */
+    ifThenElse(cond: ConstraintValue, thenValue: ConstraintValue, elseValue: ConstraintValue): ConstraintExpr;
+}>;
+export declare const widthConstraints: Readonly<{
+    /** `parent.w * ratio` (ratio is 0..1). */
+    percentOfParent(ratio: number): ConstraintExpr;
+    /** `viewport.w * ratio` (ratio is 0..1). */
+    percentOfViewport(ratio: number): ConstraintExpr;
+    /** `clamp(min, parent.w * ratio, max)` (ratio is 0..1). */
+    clampedPercentOfParent(options: Readonly<{
+        ratio: number;
+        min: number;
+        max: number;
+    }>): ConstraintExpr;
+    /** `clamp(min, viewport.w - minus, max)` */
+    clampedViewportMinus(options: Readonly<{
+        minus: number;
+        min: number;
+        max: number;
+    }>): ConstraintExpr;
+    /** `max(min, viewport.w * ratio)` (ratio is 0..1). */
+    minViewportPercent(options: Readonly<{
+        ratio: number;
+        min: number;
+    }>): ConstraintExpr;
+    /**
+     * Breakpoint steps by viewport width using the DSL `steps(...)` function.
+     *
+     * Semantics:
+     * `steps(viewport.w, 80: a, 120: b, 160: c)` yields:
+     * - `a` when `viewport.w < 80`
+     * - `b` when `viewport.w < 120`
+     * - `c` otherwise
+     *
+     * Notes:
+     * - Thresholds must be non-negative int32 and strictly increasing.
+     * - Values may be numbers or nested constraints for composition.
+     */
+    stepsByViewportWidth(options: Readonly<{
+        steps: readonly Readonly<{
+            below: number;
+            value: ConstraintValue;
+        }>[];
+    }>): ConstraintExpr;
+    /**
+     * Intrinsic-width-aware sizing with padding, clamped to a max bound.
+     *
+     * Common use: `width: clamp(min, intrinsic.w + pad, parent.w)`
+     */
+    clampedIntrinsicPlus(options: Readonly<{
+        pad: number;
+        min: number;
+        max?: number | "parent";
+    }>): ConstraintExpr;
+}>;
+export declare const heightConstraints: Readonly<{
+    /** `parent.h * ratio` (ratio is 0..1). */
+    percentOfParent(ratio: number): ConstraintExpr;
+    /** `viewport.h * ratio` (ratio is 0..1). */
+    percentOfViewport(ratio: number): ConstraintExpr;
+    /** `max(min, viewport.h * ratio)` (ratio is 0..1). */
+    minViewportPercent(options: Readonly<{
+        ratio: number;
+        min: number;
+    }>): ConstraintExpr;
+    /**
+     * Breakpoint steps by viewport height using the DSL `steps(...)` function.
+     *
+     * Thresholds must be non-negative int32 and strictly increasing.
+     */
+    stepsByViewportHeight(options: Readonly<{
+        steps: readonly Readonly<{
+            below: number;
+            value: ConstraintValue;
+        }>[];
+    }>): ConstraintExpr;
+    /** `clamp(min, parent.h * ratio, max)` (ratio is 0..1). */
+    clampedPercentOfParent(options: Readonly<{
+        ratio: number;
+        min: number;
+        max: number;
+    }>): ConstraintExpr;
+    /** `clamp(min, viewport.h * ratio, max)` (ratio is 0..1). */
+    clampedPercentOfViewport(options: Readonly<{
+        ratio: number;
+        min: number;
+        max: number;
+    }>): ConstraintExpr;
+    /** `clamp(min, viewport.h - minus, max)` */
+    clampedViewportMinus(options: Readonly<{
+        minus: number;
+        min: number;
+        max: number;
+    }>): ConstraintExpr;
+    /** `clamp(min, intrinsic.h + pad, parent.h)` (or a numeric max). */
+    clampedIntrinsicPlus(options: Readonly<{
+        pad: number;
+        min: number;
+        max?: number | "parent";
+    }>): ConstraintExpr;
+}>;
+export declare const groupConstraints: Readonly<{
+    /** `max_sibling(#id.w)` */
+    maxSiblingWidth(id: string): ConstraintExpr;
+    /** `max_sibling(#id.h)` */
+    maxSiblingHeight(id: string): ConstraintExpr;
+    /** `max_sibling(#id.min_w)` */
+    maxSiblingMinWidth(id: string): ConstraintExpr;
+    /** `max_sibling(#id.min_h)` */
+    maxSiblingMinHeight(id: string): ConstraintExpr;
+    /** `sum_sibling(#id.w)` */
+    sumSiblingWidth(id: string): ConstraintExpr;
+    /** `sum_sibling(#id.h)` */
+    sumSiblingHeight(id: string): ConstraintExpr;
+    /** `sum_sibling(#id.min_w)` */
+    sumSiblingMinWidth(id: string): ConstraintExpr;
+    /** `sum_sibling(#id.min_h)` */
+    sumSiblingMinHeight(id: string): ConstraintExpr;
+}>;
+export declare const spaceConstraints: Readonly<{
+    /**
+     * Remaining width inside the parent after subtracting other terms.
+     *
+     * Defaults to non-negative output (`max(0, ...)`) to avoid negative sizing surprises.
+     *
+     * Example:
+     * `spaceConstraints.remainingWidth({ subtract: [{ id: "sidebar" }, { id: "rail" }], minus: 1 })`
+     * => `max(0, parent.w - #sidebar.w - #rail.w - 1)`
+     */
+    remainingWidth(options: Readonly<{
+        subtract: readonly SpaceTerm[];
+        minus?: number;
+        clampMin?: number;
+    }>): ConstraintExpr;
+    /** Height variant of `remainingWidth(...)`. */
+    remainingHeight(options: Readonly<{
+        subtract: readonly SpaceTerm[];
+        minus?: number;
+        clampMin?: number;
+    }>): ConstraintExpr;
+}>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/constraints/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/constraints/helpers.ts"],"names":[],"mappings":"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"}