bireactive 0.2.4 → 0.3.1

package/dist/shapes/drag-behaviors.js

@@ -0,0 +1,102 @@
+// drag-behaviors.ts — Dragology-style drag *modifiers* layered over the
+// scene graph. The model-driven cores (`closest`, `between`, `whenFar`)
+// live in `core/lenses/snap.ts`; these wire them to pointer input and the
+// animation clock.
+//
+// The key idea, and the answer to "drag-and-drop complicates state": the
+// floating offset and the spring-settle are TRANSIENT drag state, held in
+// the animator, never written to the model. The model only ever sees the
+// committed drop.
+import { spring } from "../animation/index.js";
+import { cell, derive, effect, Vec, vec, } from "../core/index.js";
+import { drag } from "./interaction.js";
+/** Dragology's `withFloating`: while held, `pos` follows the pointer
+ *  directly (via the robust `drag` wiring — grab offset, touch, capture);
+ *  on release it springs to `home` (the resolved target, e.g. a `closest`
+ *  snap position or a layout slot). `pos` is the caller-owned display cell
+ *  the shape renders from.
+ *
+ *      const pos = vec(home.peek());
+ *      const dot = s(circle(pos, 10));
+ *      const { anim } = floating(dot, pos, home);
+ *      this.anim.start(anim);
+ *
+ *  While dragging, the settle spring is frozen (rate 0) so it never fights
+ *  the pointer; on release it re-engages and eases `pos` home. */
+export function floating(shape, pos, home, opts = {}) {
+    const dragging = cell(false);
+    const dispose = drag(shape, pos, dragging);
+    const anim = spring(pos, home, {
+        omega: opts.omega ?? 24,
+        zeta: opts.zeta ?? 0.9,
+        ...opts,
+        // Never completes (re-engages every release) and yields to the pointer
+        // while held.
+        precision: 0,
+        rate: () => (dragging.value ? 0 : (opts.rate?.() ?? 1)),
+    });
+    return { dragging, anim, dispose };
+}
+// ── drag lifecycle ──────────────────────────────────────────────────
+// The `was`-flag edge and z-raise every demo hand-rolls, factored out, plus a
+// model-driven driver that ties a `Drag<M>` spec (drag-spec.ts) to the
+// grab→preview→commit lifecycle — the spec is built once per grab (like
+// Dragology's `dragologyOnDrag`), so candidate states are enumerated then.
+/** Run `grab`/`drop` on the rising/falling edge of `active`. */
+export function onGesture(active, edges) {
+    let was = false;
+    return effect(() => {
+        const now = active.value;
+        if (now && !was)
+            edges.grab?.();
+        else if (!now && was)
+            edges.drop?.();
+        was = now;
+    });
+}
+/** Re-append shapes to raise them above siblings (z-order). */
+export function raise(...shapes) {
+    for (const s of shapes)
+        s.el.parentElement?.appendChild(s.el);
+}
+/** Bind a committed `model` cell to a `Drag<M>` spec built at grab time. Owns
+ *  the transient drag state (which element, the free pointer, the live preview)
+ *  and commits the spec's drop on release — the demo only renders `preview`/`at`. */
+export function dragModel(model, spec) {
+    const active = cell(null);
+    const pointer = vec(0, 0);
+    const live = cell(null);
+    const preview = derive(() => {
+        const s = live.value;
+        return s ? s.preview.value : model.value;
+    });
+    const at = Vec.derive(() => {
+        const s = live.value;
+        return s ? s.at.value : pointer.value;
+    });
+    const grip = (handle, id, seed, onGrab) => {
+        const dragging = cell(false);
+        const offDown = handle.on("pointerdown", () => {
+            pointer.value = seed();
+            active.value = id;
+            live.value = spec(id, pointer);
+            onGrab?.();
+        });
+        const offDrag = drag(handle, pointer, dragging);
+        const offEdge = onGesture(dragging, {
+            drop: () => {
+                const s = live.peek();
+                if (s)
+                    model.value = s.drop.peek();
+                active.value = null;
+                live.value = null;
+            },
+        });
+        return () => {
+            offDown();
+            offDrag();
+            offEdge();
+        };
+    };
+    return { active, pointer, preview, at, grip };
+}

package/dist/shapes/drag-spec.d.ts

@@ -0,0 +1,52 @@
+import { type Read } from "../core/index.js";
+type V = {
+    x: number;
+    y: number;
+};
+/** A drag behavior: Dragology's `DragBehavior`, reactive and parametric in the
+ *  MODEL `M` (positions are just `M = Vec`). */
+export interface Drag<M> {
+    /** Model rendered this frame (non-dragged elements reflow toward this). */
+    preview: Read<M>;
+    /** Model committed on release. */
+    drop: Read<M>;
+    /** Where the dragged handle sits this frame (the renderer floats it here). */
+    at: Read<V>;
+    /** Residual |pointer − achievable|; combinators arbitrate on this. */
+    gap: Read<number>;
+}
+/** `d.fixed`: a single reachable model; `locate` reads where the dragged handle
+ *  lands in it (a layout cell, or a pure layout fn). */
+declare function fixed<M>(pointer: Read<V>, state: M, locate: (m: M) => V): Drag<M>;
+/** `d.vary`: a continuous family; `place` is the BACKWARD map pointer→model (a
+ *  lens / `argminVec`, not numerical search), `gap` the residual off the family. */
+declare function vary<M>(pointer: Read<V>, place: (p: V) => M, locate: (m: M) => V): Drag<M>;
+/** `d.closest`: the behavior with the smallest `gap` (discrete snapping and
+ *  continuous tracks both pick with it). */
+declare function closest<M>(bs: readonly Drag<M>[]): Drag<M>;
+/** `d.between`: free motion in the candidates' convex hull; preview is their
+ *  barycentric blend (`mix` any `Lerp`/`Linear` model). Unlike `closest` it does
+ *  NOT snap — it rests at the blend, so `drop` is the previewed mix. */
+declare function between<M>(pointer: Read<V>, bs: readonly Drag<M>[], mix: (ms: readonly M[], ws: readonly number[]) => M): Drag<M>;
+/** `d.whenFar`: use `near` unless its gap exceeds `radius`, then `far` (snap
+ *  into a port, else float free). */
+declare function whenFar<M>(near: Drag<M>, far: Drag<M>, radius: number): Drag<M>;
+/** `d.withFloating`: the dragged handle follows the pointer while the rest
+ *  reflow (they already do — `preview` is reactive); just an `at` override. */
+declare function withFloating<M>(pointer: Read<V>, b: Drag<M>): Drag<M>;
+/** `d.onDrop`: transform the committed model (create/destroy, snap-to-grid),
+ *  the escape hatch beyond repositional drags. */
+declare function onDrop<M>(b: Drag<M>, f: (m: M) => M): Drag<M>;
+/** The drag-behavior DSL (Dragology's `d.`): primitives `fixed`/`vary`,
+ *  combinators `closest`/`between`/`whenFar`, modifiers `withFloating`/`onDrop`.
+ *  Build a `Drag<M>` once at grab; the renderer reads `preview`/`at`/`drop`. */
+export declare const d: {
+    readonly fixed: typeof fixed;
+    readonly vary: typeof vary;
+    readonly closest: typeof closest;
+    readonly between: typeof between;
+    readonly whenFar: typeof whenFar;
+    readonly withFloating: typeof withFloating;
+    readonly onDrop: typeof onDrop;
+};
+export {};

package/dist/shapes/drag-spec.js

@@ -0,0 +1,112 @@
+// drag-spec.ts — the general drag algebra (Dragology's `d.` DSL), model-driven.
+//
+// Dragology's closed object isn't "snap"; it's a behavior
+//
+//     DragBehavior = (pointer) → { preview, dropState, gap }
+//
+// — the whole previewed MODEL this frame, the model to commit on release, and
+// the residual the combinators arbitrate on. Snapping is one primitive of it.
+//
+// Reactive form: the result is cells already tracking a shared pointer, so
+// nothing recomputes per frame by hand. And the deep bit — "drawing knows
+// state→drawing, computing knows drawing→state" (a lens) — is FREE here:
+// Dragology synthesizes drawing→state by speculative rendering (render every
+// candidate, extract positions; quadratic), whereas bireactive already has it
+// as the backward lens, so `vary` is a lens write and `preview` is a reactive
+// previewed model (springs interpolate it — no view-diffing, no re-render).
+//
+// Exposed as `d` to mirror the paper. It builds on core's pointer math
+// (`hullWeights` for `between`, `nearestIndex`'s sticky selection mirrored in
+// `closest`). Renderer contract: render non-dragged elements from `preview`,
+// the dragged one at `at`, and commit `drop` on release.
+import { derive, hullWeights } from "../core/index.js";
+const dist = (a, b) => Math.hypot(a.x - b.x, a.y - b.y);
+/** `d.fixed`: a single reachable model; `locate` reads where the dragged handle
+ *  lands in it (a layout cell, or a pure layout fn). */
+function fixed(pointer, state, locate) {
+    const s = derive(() => state);
+    const at = derive(() => locate(state));
+    return { preview: s, drop: s, at, gap: derive(() => dist(pointer.value, at.value)) };
+}
+/** `d.vary`: a continuous family; `place` is the BACKWARD map pointer→model (a
+ *  lens / `argminVec`, not numerical search), `gap` the residual off the family. */
+function vary(pointer, place, locate) {
+    const preview = derive(() => place(pointer.value));
+    const at = derive(() => locate(preview.value));
+    return { preview, drop: preview, at, gap: derive(() => dist(pointer.value, at.value)) };
+}
+/** `d.closest`: the behavior with the smallest `gap` (discrete snapping and
+ *  continuous tracks both pick with it). */
+function closest(bs) {
+    const idx = derive(() => {
+        let best = 0;
+        let bg = Number.POSITIVE_INFINITY;
+        for (let i = 0; i < bs.length; i++) {
+            const g = bs[i].gap.value;
+            if (g < bg) {
+                bg = g;
+                best = i;
+            }
+        }
+        return best;
+    });
+    return {
+        preview: derive(() => bs[idx.value].preview.value),
+        drop: derive(() => bs[idx.value].drop.value),
+        at: derive(() => bs[idx.value].at.value),
+        gap: derive(() => bs[idx.value].gap.value),
+    };
+}
+/** `d.between`: free motion in the candidates' convex hull; preview is their
+ *  barycentric blend (`mix` any `Lerp`/`Linear` model). Unlike `closest` it does
+ *  NOT snap — it rests at the blend, so `drop` is the previewed mix. */
+function between(pointer, bs, mix) {
+    const ws = derive(() => hullWeights(pointer.value, bs.map(b => b.at.value)));
+    const at = derive(() => {
+        const w = ws.value;
+        let x = 0;
+        let y = 0;
+        bs.forEach((b, i) => {
+            const a = b.at.value;
+            x += w[i] * a.x;
+            y += w[i] * a.y;
+        });
+        return { x, y };
+    });
+    const blend = derive(() => mix(bs.map(b => b.preview.value), ws.value));
+    return { preview: blend, drop: blend, at, gap: derive(() => dist(pointer.value, at.value)) };
+}
+/** `d.whenFar`: use `near` unless its gap exceeds `radius`, then `far` (snap
+ *  into a port, else float free). */
+function whenFar(near, far, radius) {
+    const pickFar = derive(() => near.gap.value > radius);
+    const sel = (f) => derive(() => f(pickFar.value ? far : near).value);
+    return {
+        preview: sel(b => b.preview),
+        drop: sel(b => b.drop),
+        at: sel(b => b.at),
+        gap: sel(b => b.gap),
+    };
+}
+/** `d.withFloating`: the dragged handle follows the pointer while the rest
+ *  reflow (they already do — `preview` is reactive); just an `at` override. */
+function withFloating(pointer, b) {
+    return { preview: b.preview, drop: b.drop, gap: b.gap, at: pointer };
+}
+/** `d.onDrop`: transform the committed model (create/destroy, snap-to-grid),
+ *  the escape hatch beyond repositional drags. */
+function onDrop(b, f) {
+    return { preview: b.preview, at: b.at, gap: b.gap, drop: derive(() => f(b.drop.value)) };
+}
+/** The drag-behavior DSL (Dragology's `d.`): primitives `fixed`/`vary`,
+ *  combinators `closest`/`between`/`whenFar`, modifiers `withFloating`/`onDrop`.
+ *  Build a `Drag<M>` once at grab; the renderer reads `preview`/`at`/`drop`. */
+export const d = {
+    fixed,
+    vary,
+    closest,
+    between,
+    whenFar,
+    withFloating,
+    onDrop,
+};

package/dist/shapes/handle.js

@@ -1,5 +1,5 @@
 // handle.* — writable derived shapes (draggable circles wired to a Vec).
-import { cell, mean, polar as polarLens, Vec, } from "../core/index.js";
+import { cell, mean, polar as polarLens, SKIP, Vec, } from "../core/index.js";
 import { Circle } from "./circle.js";
 import { drag } from "./interaction.js";
 const COLOR = "var(--bireactive-handle, #2563eb)";
@@ -51,7 +51,7 @@ const scaleHandle = (shape, radius = 40, opts) => {
     // Reads center and scale; writes only scale.
     const pos = Vec.lens([shape.center, shape.scale], vals => ({ x: vals[0].x + radius * vals[1].x, y: vals[0].y }), (target, vals) => {
         const k = Math.max(0.05, Math.abs(target.x - vals[0].x) / radius);
-        return [undefined, { x: k, y: k }];
+        return [SKIP, { x: k, y: k }];
     });
     return handleFn(pos, { cursor: "ew-resize", ...opts });
 };

package/dist/shapes/index.d.ts

@@ -7,11 +7,13 @@ export { type ArrowOpts, arrow, connect, ensureArrowMarker } from "./connect.js"
 export { Curve, type CurveOpts, type CurveSegment, curve, ellipse } from "./curve.js";
 export { dashedPath } from "./dashed.js";
 export { debug } from "./debug.js";
+export { type DragModel, dragModel, type FloatingOpts, type FloatingResult, floating, onGesture, raise, } from "./drag-behaviors.js";
+export { type Drag, d } from "./drag-spec.js";
 export { group } from "./group.js";
 export { type HandleOpts, handle } from "./handle.js";
 export { cursor, drag, draggable, dragRotate, dragWithState, hoverSignal } from "./interaction.js";
 export { Label, type LabelOpts, label } from "./label.js";
-export { type ArrangeOpts, arrange, expand, grid, split } from "./layout.js";
+export { type ArrangeOpts, arrange, expand, grid, split, type TreeStack, type TreeStackBox, type TreeStackOpts, treeStack, } from "./layout.js";
 export { Line, type LineOpts, line } from "./line.js";
 export { type ForEachOptions, forEach } from "./list.js";
 export { type Mount, mount } from "./mount.js";

package/dist/shapes/index.js

@@ -7,11 +7,13 @@ export { arrow, connect, ensureArrowMarker } from "./connect.js";
 export { Curve, curve, ellipse } from "./curve.js";
 export { dashedPath } from "./dashed.js";
 export { debug } from "./debug.js";
+export { dragModel, floating, onGesture, raise, } from "./drag-behaviors.js";
+export { d } from "./drag-spec.js";
 export { group } from "./group.js";
 export { handle } from "./handle.js";
 export { cursor, drag, draggable, dragRotate, dragWithState, hoverSignal } from "./interaction.js";
 export { Label, label } from "./label.js";
-export { arrange, expand, grid, split } from "./layout.js";
+export { arrange, expand, grid, split, treeStack, } from "./layout.js";
 export { Line, line } from "./line.js";
 export { forEach } from "./list.js";
 export { mount } from "./mount.js";

package/dist/shapes/interaction.d.ts

@@ -19,9 +19,8 @@ export declare function draggable(handle: AnyShape, onDrag: (local: Inner<Vec>)
  *  `shape.translate`. Grab offset is captured on pointerdown; optional
  *  `dragging` reports active state. Defaults `cursor` to `"grab"`. */
 export declare function drag(shape: AnyShape, target: Writable<Vec>, dragging?: Writable<Cell<boolean>>): () => void;
-/** Wrap a `drag(shape, target)` call and return a local `dragging`
- *  Cell<boolean>. Sugar for "give me a drag handle that exposes its
- *  own state." */
+/** Wrap a `drag(shape, target)` call and return a local `dragging` `Cell<boolean>`.
+ *  Sugar for "give me a drag handle that exposes its own state." */
 export declare function dragWithState(shape: AnyShape, target: Writable<Vec>): {
     dragging: Cell<boolean>;
     dispose: () => void;

package/dist/shapes/interaction.js

@@ -63,43 +63,51 @@ export function cursor(shape, init) {
  *  `onState(active)` callback fires `true` on pointerdown and `false`
  *  on pointerup/cancel — `Handle` uses it to drive `.dragging`. */
 export function draggable(handle, onDrag, onState) {
-    let dragging = false;
     let pointerId = -1;
     let unblock = null;
     ownTouchGesture(handle);
-    const offs = [];
-    offs.push(handle.on("pointerdown", e => {
-        const pe = e;
-        dragging = true;
-        pointerId = pe.pointerId;
-        handle.el.setPointerCapture(pointerId);
-        unblock = blockPageScroll();
-        onState?.(true);
-        onDrag(handle.toLocal(pe));
-    }));
-    offs.push(handle.on("pointermove", e => {
-        if (!dragging)
+    const onMove = (e) => {
+        if (pointerId === -1 || e.pointerId !== pointerId)
             return;
         onDrag(handle.toLocal(e));
-    }));
-    const stop = () => {
-        if (dragging && pointerId !== -1) {
-            try {
-                handle.el.releasePointerCapture(pointerId);
-            }
-            catch {
-                /* ok */
-            }
+    };
+    const stop = (e) => {
+        if (pointerId === -1 || (e && e.pointerId !== pointerId))
+            return;
+        try {
+            handle.el.releasePointerCapture(pointerId);
+        }
+        catch {
+            /* ok */
         }
-        dragging = false;
         pointerId = -1;
+        window.removeEventListener("pointermove", onMove);
+        window.removeEventListener("pointerup", stop);
+        window.removeEventListener("pointercancel", stop);
         unblock?.();
         unblock = null;
         onState?.(false);
     };
-    offs.push(handle.on("pointerup", stop));
-    offs.push(handle.on("pointercancel", stop));
-    return () => offs.forEach(d => d());
+    const offDown = handle.on("pointerdown", e => {
+        const pe = e;
+        pointerId = pe.pointerId;
+        try {
+            handle.el.setPointerCapture(pointerId);
+        }
+        catch {
+            /* ok */
+        }
+        unblock = blockPageScroll();
+        window.addEventListener("pointermove", onMove);
+        window.addEventListener("pointerup", stop);
+        window.addEventListener("pointercancel", stop);
+        onState?.(true);
+        onDrag(handle.toLocal(pe));
+    });
+    return () => {
+        offDown();
+        stop();
+    };
 }
 /** Bind pointer drag on `shape` directly to a writable `Vec` (no handle dot);
  *  returns a disposer. `target` is in the SVG-root frame and coords are read
@@ -114,47 +122,60 @@ export function drag(shape, target, dragging) {
     let dy = 0;
     let pointerId = -1;
     let unblock = null;
-    const offs = [];
-    offs.push(shape.on("pointerdown", e => {
+    // Moves/ups are tracked on `window`, not the shape: pointer capture alone
+    // drops the gesture when the element is re-parented (z-raising) or the
+    // pointer outruns the shape, so a window listener is the reliable path.
+    const onMove = (e) => {
+        if (pointerId === -1 || e.pointerId !== pointerId)
+            return;
+        const world = shape.toWorld(e);
+        target.value = { x: world.x - dx, y: world.y - dy };
+    };
+    const stop = (e) => {
+        if (pointerId === -1 || (e && e.pointerId !== pointerId))
+            return;
+        try {
+            shape.el.releasePointerCapture(pointerId);
+        }
+        catch {
+            /* ok */
+        }
+        pointerId = -1;
+        window.removeEventListener("pointermove", onMove);
+        window.removeEventListener("pointerup", stop);
+        window.removeEventListener("pointercancel", stop);
+        unblock?.();
+        unblock = null;
+        if (dragging)
+            dragging.value = false;
+    };
+    const offDown = shape.on("pointerdown", e => {
         const pe = e;
         pointerId = pe.pointerId;
-        shape.el.setPointerCapture(pointerId);
+        try {
+            shape.el.setPointerCapture(pointerId);
+        }
+        catch {
+            /* ok */
+        }
         unblock = blockPageScroll();
         const world = shape.toWorld(pe);
         const v = target.value;
         dx = world.x - v.x;
         dy = world.y - v.y;
+        window.addEventListener("pointermove", onMove);
+        window.addEventListener("pointerup", stop);
+        window.addEventListener("pointercancel", stop);
         if (dragging)
             dragging.value = true;
-    }));
-    offs.push(shape.on("pointermove", e => {
-        if (pointerId === -1)
-            return;
-        const world = shape.toWorld(e);
-        target.value = { x: world.x - dx, y: world.y - dy };
-    }));
-    const stop = () => {
-        if (pointerId !== -1) {
-            try {
-                shape.el.releasePointerCapture(pointerId);
-            }
-            catch {
-                /* ok */
-            }
-            pointerId = -1;
-        }
-        unblock?.();
-        unblock = null;
-        if (dragging)
-            dragging.value = false;
+    });
+    return () => {
+        offDown();
+        stop();
     };
-    offs.push(shape.on("pointerup", stop));
-    offs.push(shape.on("pointercancel", stop));
-    return () => offs.forEach(d => d());
 }
-/** Wrap a `drag(shape, target)` call and return a local `dragging`
- *  Cell<boolean>. Sugar for "give me a drag handle that exposes its
- *  own state." */
+/** Wrap a `drag(shape, target)` call and return a local `dragging` `Cell<boolean>`.
+ *  Sugar for "give me a drag handle that exposes its own state." */
 export function dragWithState(shape, target) {
     const dragging = cell(false);
     const dispose = drag(shape, target, dragging);

package/dist/shapes/label.js

@@ -14,7 +14,7 @@ export class Label extends Shape {
             : typeof content === "function"
                 ? derive(content)
                 : cell(content);
-        const sizeSig = Num.from(opts.size ?? tokens.fontSize);
+        const sizeSig = Num.coerce(opts.size ?? tokens.fontSize);
         const a = opts.align ?? { x: 0.5, y: 0.5 };
         super("text", () => {
             const text = flattenText(contentSig.value);
@@ -34,6 +34,12 @@ export class Label extends Shape {
         this.attr("dominant-baseline", yAttr(a.y));
         if (opts.bold)
             this.attr("font-weight", 700);
+        // Labels are decorative: never select on drag, never steal a pointer from
+        // the shape underneath (so text over a draggable doesn't break its grab).
+        const style = this.intrinsic.style;
+        style.userSelect = "none";
+        style.setProperty("-webkit-user-select", "none");
+        style.pointerEvents = "none";
         this.effect(() => {
             this.intrinsic.innerHTML = renderContent(contentSig.value);
         });

package/dist/shapes/layout.d.ts

@@ -1,4 +1,4 @@
-import { Box, type Val } from "../core/index.js";
+import { Box, type Read, type Val } from "../core/index.js";
 import type { Shape } from "./shape.js";
 export interface ArrangeOpts {
     /** Spacing between adjacent bounding boxes. Default 0. */
@@ -27,3 +27,49 @@ export declare function split(source: Box, axis: "x" | "y", parts: number | numb
 export declare function grid(source: Box, rows: number, cols: number, opts?: {
     gap?: Val<number>;
 }): Box[][];
+export interface TreeStackBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface TreeStackOpts<Id> {
+    /** Top-level node ids, in order (read inside a derive; cell reads track). */
+    roots: () => readonly Id[];
+    /** A container's children, in order (read inside a derive). */
+    kids: (id: Id) => readonly Id[];
+    /** Containers stack their `kids`; non-containers are sized by `leaf`. */
+    container: (id: Id) => boolean;
+    /** Intrinsic size of a non-container node. */
+    leaf: (id: Id) => {
+        w: number;
+        h: number;
+    };
+    /** Top-left of a root node. */
+    origin: (id: Id) => {
+        x: number;
+        y: number;
+    };
+    /** Space reserved above a container's children (a title bar). Default 0. */
+    header?: number;
+    /** Inset around a container's children. Default 0. */
+    pad?: number;
+    /** Space between adjacent children. Default 0. */
+    gap?: number;
+    /** Minimum container width. Default 0. */
+    minWidth?: number;
+    /** Height of an empty container. Default `header + 2·pad`. */
+    emptyHeight?: number;
+}
+export interface TreeStack<Id> {
+    /** Reactive placement of every reachable node. */
+    readonly boxes: Read<Map<Id, TreeStackBox>>;
+    /** A node's box as a reactive `Box` (zero box when absent). */
+    box(id: Id): Box;
+}
+/** Intrinsic ("hug-contents") layout of a tree as nested vertical stacks:
+ *  each container's size is the bottom-up sum of its children, each child is
+ *  placed top-down from its container. Unlike `row`/`col` (which fit items
+ *  into a fixed container), the containers grow to fit. Pure function of the
+ *  inputs, so feeding it a *previewed* tree yields a previewed layout. */
+export declare function treeStack<Id>(opts: TreeStackOpts<Id>): TreeStack<Id>;

package/dist/shapes/layout.js

@@ -1,5 +1,5 @@
 // Spatial composition primitives.
-import { Box, BoxMath, reader, transformBox } from "../core/index.js";
+import { Box, boxExpand, derive, reader, transformBox, } from "../core/index.js";
 /** Lay out `shapes` in a row/column. First stays put; the rest bind
  *  their `translate` reactively to sit `gap` past the previous.
  *  Reflows on size or anchor change. */
@@ -40,7 +40,7 @@ export function arrange(shapes, axis, opts = {}) {
 /** Inflate a Box on each side by `by`. */
 export function expand(b, by) {
     const byFn = reader(by);
-    return Box.derive(() => BoxMath.expand(b.value, byFn()));
+    return Box.derive(() => boxExpand(b.value, byFn()));
 }
 /** Split a Box along an axis into N reactive sub-Boxes.
  *
@@ -72,3 +72,61 @@ export function split(source, axis, parts, opts = {}) {
 export function grid(source, rows, cols, opts = {}) {
     return split(source, "y", rows, opts).map(row => split(row, "x", cols, opts));
 }
+/** Intrinsic ("hug-contents") layout of a tree as nested vertical stacks:
+ *  each container's size is the bottom-up sum of its children, each child is
+ *  placed top-down from its container. Unlike `row`/`col` (which fit items
+ *  into a fixed container), the containers grow to fit. Pure function of the
+ *  inputs, so feeding it a *previewed* tree yields a previewed layout. */
+export function treeStack(opts) {
+    const header = opts.header ?? 0;
+    const pad = opts.pad ?? 0;
+    const gap = opts.gap ?? 0;
+    const minW = opts.minWidth ?? 0;
+    const emptyH = opts.emptyHeight ?? header + 2 * pad;
+    const measure = (id) => {
+        if (!opts.container(id))
+            return opts.leaf(id);
+        const ks = opts.kids(id);
+        if (ks.length === 0)
+            return { w: minW, h: emptyH };
+        let maxw = 0;
+        let h = header + pad;
+        for (const c of ks) {
+            const m = measure(c);
+            maxw = Math.max(maxw, m.w);
+            h += m.h + gap;
+        }
+        return { w: Math.max(minW, maxw + 2 * pad), h: h + pad - gap };
+    };
+    const place = (id, x, y, out) => {
+        const m = measure(id);
+        out.set(id, { x, y, w: m.w, h: m.h });
+        if (opts.container(id)) {
+            let cy = y + header + pad;
+            for (const c of opts.kids(id)) {
+                place(c, x + pad, cy, out);
+                cy += measure(c).h + gap;
+            }
+        }
+    };
+    const boxes = derive(() => {
+        const out = new Map();
+        for (const r of opts.roots()) {
+            const o = opts.origin(r);
+            place(r, o.x, o.y, out);
+        }
+        return out;
+    });
+    const cache = new Map();
+    return {
+        boxes,
+        box(id) {
+            let b = cache.get(id);
+            if (!b) {
+                b = Box.derive(() => boxes.value.get(id) ?? { x: 0, y: 0, w: 0, h: 0 });
+                cache.set(id, b);
+            }
+            return b;
+        },
+    };
+}