bireactive 0.3.0 → 0.3.1

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/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

@@ -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, boxExpand, 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. */
@@ -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;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bireactive",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Bi-directional reactive programming.",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,18 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./automerge": {
+      "types": "./dist/automerge/index.d.ts",
+      "import": "./dist/automerge/index.js"
+    },
+    "./jsx-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "import": "./dist/jsx-runtime.js"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./dist/jsx-dev-runtime.d.ts",
+      "import": "./dist/jsx-dev-runtime.js"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -21,7 +33,9 @@
   ],
   "scripts": {
     "dev": "vite --host",
-    "site": "vite build && typedoc",
+    "site": "vite build && typedoc && vitepress build docs",
+    "docs": "typedoc && vitepress build docs",
+    "docs:dev": "typedoc && vitepress dev docs --port 5556",
     "preview": "vite preview",
     "prebuild": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json --resolve-full-paths",
@@ -38,6 +52,9 @@
     "postversion": "npm publish && git push --follow-tags"
   },
   "dependencies": {
+    "@automerge/automerge-repo": "^2.6.0-subduction.34",
+    "@automerge/automerge-repo-network-broadcastchannel": "^2.6.0-subduction.34",
+    "@automerge/automerge-repo-storage-indexeddb": "^2.6.0-subduction.34",
     "prism-esm": "^1.29.0-fix.6",
     "temml": "^0.13.3"
   },
@@ -54,9 +71,14 @@
     "reactive-framework-test-suite": "^0.0.2",
     "tsc-alias": "^1.8.17",
     "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.12.0",
+    "typedoc-vitepress-theme": "^1.1.3",
     "typescript": "^6.0.3",
     "vite": "^7.3.3",
     "vite-node": "^5.3.0",
+    "vite-plugin-top-level-await": "^1.6.0",
+    "vite-plugin-wasm": "^3.6.0",
+    "vitepress": "^1.6.4",
     "vitest": "^4.1.7"
   },
   "keywords": [