bireactive 0.2.1 → 0.2.3

package/README.md

@@ -1,8 +1,8 @@
 # bi-reactive
 
-Reactive programming where edges can go both ways. Write to an input and
-everything derived from it updates; write the *derived* value and the input
-adjusts to match. Forward and backward propagation are handled by the engine, with the same set of caveats as regular reactive programming.
+[npm](https://www.npmjs.com/package/bireactive) · [GitHub](https://github.com/OrionReed/bireactive) · [site](https://orionreed.github.io/bireactive/) · [API](https://orionreed.github.io/bireactive/api/)
+
+A signals-like bidirectional reactive programming system where edges can go both ways. Forward and backward propagation are handled by the engine, with the same set of caveats as regular reactive programming.
 
 ## Install
 

package/dist/coll.d.ts

@@ -0,0 +1,74 @@
+import { type Cell, type Read, type Writable } from "./core/index.js";
+/** Accessor for an element's writable field cell. Forward reads `.value`;
+ *  the backward pass writes it. */
+export type Field<E, V> = (e: E) => Writable<Cell<V>>;
+/** A forward test over an element's fields, optionally assertable —
+ *  `assert(e)` makes the test pass by writing fields. */
+export interface FieldPred<E> {
+    (e: E): boolean;
+    assert?: (e: E) => void;
+}
+export interface Group<K, E> {
+    key: K;
+    items: readonly E[];
+}
+export interface GroupOpts<E, K> {
+    /** Fixed key order; seeds empty buckets and pins column order. */
+    order?: readonly K[];
+    /** Order field within each group; enables `move(e, key, index)`. */
+    sort?: Field<E, number>;
+}
+/** `field === value`, assertable by writing the field. */
+export declare function is<E, V>(field: Field<E, V>, value: V): FieldPred<E>;
+/** Conjunction; asserts every clause. */
+export declare function allPass<E>(...preds: readonly FieldPred<E>[]): FieldPred<E>;
+/** Read-only projection with chainable structural lenses. */
+export declare class View<E> {
+    protected readonly list: Read<readonly E[]>;
+    readonly key: (e: E) => unknown;
+    protected readonly parent: View<E> | null;
+    protected constructor(list: Read<readonly E[]>, key: (e: E) => unknown, parent: View<E> | null);
+    /** Current members; tracked when read in an effect/derive. */
+    get items(): readonly E[];
+    /** The source collection at the head of the chain. */
+    get root(): Coll<E>;
+    /** Make `e` appear in this view: satisfy own constraint, recursively up. */
+    assertContains(e: E): void;
+    protected assertSelf(_e: E): void;
+    filter(pred: FieldPred<E>): View<E>;
+    sortBy(field: Field<E, number>): SortView<E>;
+    groupBy<K>(field: Field<E, K>, opts?: GroupOpts<E, K>): GroupView<K, E>;
+    map<F>(f: (e: E) => F): Read<readonly F[]>;
+    /** Remove `e` from the source. */
+    remove(e: E): void;
+}
+/** A writable source collection. */
+export declare class Coll<E> extends View<E> {
+    #private;
+    constructor(items: readonly E[], key: (e: E) => unknown);
+    assertContains(e: E): void;
+    insert(e: E, at?: number): void;
+    removeFromSource(e: E): void;
+}
+/** Sorted view. `move` writes the order field between the drop neighbours. */
+export declare class SortView<E> extends View<E> {
+    #private;
+    constructor(parent: View<E>, field: Field<E, number>);
+    move(e: E, to: number): void;
+}
+/** Grouped view. `move`/`insert` write the group field (and, with a `sort`
+ *  field, the order field). Backward composition runs the parent chain. */
+export declare class GroupView<K, E> {
+    #private;
+    readonly groups: Read<readonly Group<K, E>[]>;
+    constructor(parent: View<E>, field: Field<E, K>, opts?: GroupOpts<E, K>);
+    get value(): readonly Group<K, E>[];
+    map<F>(f: (g: Group<K, E>) => F): Read<readonly F[]>;
+    /** Place `e` in group `toKey` at `index`. Inserts it into the source if
+     *  it isn't there yet, asserts every upstream filter, then writes the
+     *  group key and order field — all in one batch. */
+    move(e: E, toKey: K, index?: number): void;
+    insert(e: E, toKey: K, index?: number): void;
+    remove(e: E): void;
+}
+export declare function coll<E>(items: readonly E[], key: (e: E) => unknown): Coll<E>;

package/dist/coll.js

@@ -0,0 +1,208 @@
+// coll.ts — a keyed, ordered, *bidirectional* collection.
+//
+// The structural sibling of `tree.ts`. A `Coll<E>` holds stable element
+// handles (records of cells), and each projection — `filter` / `sortBy` /
+// `groupBy` — is a WRITABLE structural lens. You edit the *view* and the
+// backward pass writes the elements' own fields:
+//
+//   sortBy(rank)  → move(e, i)        writes `rank`   (position is a field)
+//   groupBy(key)  → move(e, k, i)     writes `key`    (membership is a field)
+//   filter(pred)  → insert/assert     writes whatever pred demands
+//
+// Because position / group / visibility are the elements' own writable
+// cells, these lenses are COMPLEMENT-FREE — the "complement" lives in the
+// field cells, not the lens (contrast `Seq<T>`, where order is imposed and
+// must be remembered). One `move`/`insert` composes the backward passes up
+// the chain in a single `batch`: drop into a filtered + grouped + sorted
+// view and the filter's predicate, the group key, and the rank all get set
+// at once.
+//
+// Two change classes, mirroring the engine's two levels:
+//   • value change   — a field cell changes; forward derivations re-flow.
+//   • structural edit — insert/remove/move; a discrete batched transition.
+// No lens edges are built at runtime, so acyclicity holds as ever.
+import { batch, cell, derive } from "./core/index.js";
+/** `field === value`, assertable by writing the field. */
+export function is(field, value) {
+    const p = ((e) => field(e).value === value);
+    p.assert = (e) => {
+        field(e).value = value;
+    };
+    return p;
+}
+/** Conjunction; asserts every clause. */
+export function allPass(...preds) {
+    const p = ((e) => preds.every(q => q(e)));
+    p.assert = (e) => {
+        for (const q of preds)
+            q.assert?.(e);
+    };
+    return p;
+}
+/** Read-only projection with chainable structural lenses. */
+export class View {
+    list;
+    key;
+    parent;
+    constructor(list, key, parent) {
+        this.list = list;
+        this.key = key;
+        this.parent = parent;
+    }
+    /** Current members; tracked when read in an effect/derive. */
+    get items() {
+        return this.list.value;
+    }
+    /** The source collection at the head of the chain. */
+    get root() {
+        let v = this;
+        while (v.parent)
+            v = v.parent;
+        return v;
+    }
+    /** Make `e` appear in this view: satisfy own constraint, recursively up. */
+    assertContains(e) {
+        this.parent?.assertContains(e);
+        this.assertSelf(e);
+    }
+    assertSelf(_e) { }
+    filter(pred) {
+        return new FilterView(this, pred);
+    }
+    sortBy(field) {
+        return new SortView(this, field);
+    }
+    groupBy(field, opts) {
+        return new GroupView(this, field, opts);
+    }
+    map(f) {
+        return derive(() => this.list.value.map(f));
+    }
+    /** Remove `e` from the source. */
+    remove(e) {
+        this.root.removeFromSource(e);
+    }
+}
+/** A writable source collection. */
+export class Coll extends View {
+    #src;
+    constructor(items, key) {
+        const src = cell(items);
+        super(src, key, null);
+        this.#src = src;
+    }
+    assertContains(e) {
+        if (!this.#src.value.includes(e))
+            this.insert(e);
+    }
+    insert(e, at) {
+        const arr = [...this.#src.value];
+        if (at == null)
+            arr.push(e);
+        else
+            arr.splice(at, 0, e);
+        this.#src.value = arr;
+    }
+    removeFromSource(e) {
+        this.#src.value = this.#src.value.filter(x => x !== e);
+    }
+}
+class FilterView extends View {
+    #pred;
+    constructor(parent, pred) {
+        super(derive(() => parent.items.filter(pred)), parent.key, parent);
+        this.#pred = pred;
+    }
+    assertSelf(e) {
+        this.#pred.assert?.(e);
+    }
+}
+/** Sorted view. `move` writes the order field between the drop neighbours. */
+export class SortView extends View {
+    #field;
+    constructor(parent, field) {
+        super(derive(() => [...parent.items].sort((a, b) => field(a).value - field(b).value)), parent.key, parent);
+        this.#field = field;
+    }
+    move(e, to) {
+        const others = this.items.filter(x => x !== e);
+        batch(() => {
+            this.assertContains(e);
+            this.#field(e).value = between(rankAt(others, this.#field, to - 1), rankAt(others, this.#field, to));
+        });
+    }
+}
+/** Grouped view. `move`/`insert` write the group field (and, with a `sort`
+ *  field, the order field). Backward composition runs the parent chain. */
+export class GroupView {
+    groups;
+    #parent;
+    #field;
+    #order;
+    #sort;
+    constructor(parent, field, opts = {}) {
+        this.#parent = parent;
+        this.#field = field;
+        this.#order = opts.order ?? [];
+        this.#sort = opts.sort;
+        this.groups = derive(() => {
+            const sort = this.#sort;
+            const items = sort ? [...parent.items].sort((a, b) => sort(a).value - sort(b).value) : parent.items;
+            return groupItems(items, e => field(e).value, this.#order);
+        });
+    }
+    get value() {
+        return this.groups.value;
+    }
+    map(f) {
+        return derive(() => this.value.map(f));
+    }
+    /** Place `e` in group `toKey` at `index`. Inserts it into the source if
+     *  it isn't there yet, asserts every upstream filter, then writes the
+     *  group key and order field — all in one batch. */
+    move(e, toKey, index) {
+        const target = (this.value.find(g => Object.is(g.key, toKey))?.items ?? []).filter(x => x !== e);
+        const sort = this.#sort;
+        batch(() => {
+            this.#parent.assertContains(e);
+            this.#field(e).value = toKey;
+            if (sort && index != null)
+                sort(e).value = between(rankAt(target, sort, index - 1), rankAt(target, sort, index));
+        });
+    }
+    insert(e, toKey, index) {
+        this.move(e, toKey, index);
+    }
+    remove(e) {
+        this.#parent.remove(e);
+    }
+}
+function groupItems(items, keyOf, order) {
+    const buckets = new Map();
+    for (const k of order)
+        buckets.set(k, []);
+    for (const e of items) {
+        const k = keyOf(e);
+        const arr = buckets.get(k);
+        if (arr)
+            arr.push(e);
+        else
+            buckets.set(k, [e]);
+    }
+    return [...buckets].map(([key, items]) => ({ key, items }));
+}
+function rankAt(arr, field, i) {
+    return i >= 0 && i < arr.length ? field(arr[i]).value : undefined;
+}
+function between(a, b) {
+    if (a != null && b != null)
+        return (a + b) / 2;
+    if (a != null)
+        return a + 1;
+    if (b != null)
+        return b - 1;
+    return 0;
+}
+export function coll(items, key) {
+    return new Coll(items, key);
+}

package/dist/core/values/num.d.ts

@@ -25,6 +25,12 @@ export declare class Num extends Cell<V> {
     /** Affine `v ↦ k·v + off`. Invertible iff k ≠ 0; readability alias
      *  for `.scale(k).add(off)`. */
     affine(k: Val<number>, off: Val<number>): this;
+    /** `sin(this)` (radians). Forward lands in [−1, 1]; the inverse is
+     *  multi-valued, so a write clamps to that domain and returns the
+     *  pre-image nearest the current source — the drag stays on its branch. */
+    sin(): this;
+    /** `exp(this)` — bijection on the reals; inverse is the natural log. */
+    exp(): this;
     /** Lossy clamping lens to `[lo, hi]`. PutGet only (a write outside
      *  the range reads back clamped, not as written). */
     clamp(lo: Val<V>, hi: Val<V>): this;

package/dist/core/values/num.js

@@ -11,6 +11,11 @@ export const scale = (a, k) => a * k;
 export const lerp = (a, b, t) => a + (b - a) * t;
 export const metric = (a, b) => Math.abs(a - b);
 export const equals = (a, b) => a === b;
+const TAU = 2 * Math.PI;
+/** Representative of `x + 2πk` nearest `s` (shortest-arc branch pick). */
+const nearestTo = (s, x) => x + TAU * Math.round((s - x) / TAU);
+/** Clamp to the sin/cos domain `[-1, 1]`. */
+const unit = (t) => (t < -1 ? -1 : t > 1 ? 1 : t);
 const linearImpl = { add, sub, scale };
 const packImpl = {
     dim: 1,
@@ -49,6 +54,21 @@ export class Num extends Cell {
         const of = reader(off);
         return this.lens(v => v * kf() + of(), n => (n - of()) / kf());
     }
+    /** `sin(this)` (radians). Forward lands in [−1, 1]; the inverse is
+     *  multi-valued, so a write clamps to that domain and returns the
+     *  pre-image nearest the current source — the drag stays on its branch. */
+    sin() {
+        return this.lens(v => Math.sin(v), (target, s) => {
+            const p = Math.asin(unit(target));
+            const a = nearestTo(s, p);
+            const b = nearestTo(s, Math.PI - p);
+            return Math.abs(a - s) <= Math.abs(b - s) ? a : b;
+        });
+    }
+    /** `exp(this)` — bijection on the reals; inverse is the natural log. */
+    exp() {
+        return this.lens(v => Math.exp(v), n => Math.log(n));
+    }
     /** Lossy clamping lens to `[lo, hi]`. PutGet only (a write outside
      *  the range reads back clamped, not as written). */
     clamp(lo, hi) {

package/dist/core/values/tri.d.ts

@@ -17,13 +17,15 @@ export declare class Tri extends Cell<V> {
     constructor(v?: V);
     /** Kleene negation. Involution; fixed at `"mixed"`. */
     not(): this;
-    /** Aggregate over N writable Bools. Read: all-true → `true`,
-     *  all-false → `false`, disagreement → `"mixed"`. Write: `true` /
-     *  `false` broadcast to every parent; `"mixed"` is a no-op. */
-    static allOf(parents: readonly Bool[]): Writable<Tri>;
-    /** Dual of `allOf` (Kleene OR): any-true → `true`, all-false →
-     *  `false`, else `"mixed"`. Same broadcast write policy. */
-    static anyOf(parents: readonly Bool[]): Writable<Tri>;
+    /** Aggregate over N writable `Bool` / `Tri` children. Read: all-true →
+     *  `true`, all-false → `false`, any disagreement (or any child already
+     *  `"mixed"`) → `"mixed"`. Write: `true` / `false` broadcast to every
+     *  child, recursing through nested aggregates; `"mixed"` is a no-op. */
+    static allOf(parents: readonly (Bool | Tri)[]): Writable<Tri>;
+    /** Dual of `allOf` (Kleene OR) over `Bool` / `Tri` children: any-true →
+     *  `true`, all-false → `false`, else (or any child `"mixed"`) →
+     *  `"mixed"`. Same broadcast write policy. */
+    static anyOf(parents: readonly (Bool | Tri)[]): Writable<Tri>;
 }
 /** Writable `Tri`. Strict factory: `Tri.value | Writable<Tri>` in,
  *  `Writable<Tri>` out. Default initial value is `"mixed"`. */

package/dist/core/values/tri.js

@@ -3,12 +3,6 @@
 // `Tri.value ∈ { true, false, "mixed" }` — Bool plus an unknown state
 // fixed under negation. Strong-Kleene AND/OR follow the partial-info
 // reading (`mixed AND false` → `false`, `mixed AND true` → `mixed`).
-//
-// Headline use: aggregate N booleans via `Tri.allOf` / `Tri.anyOf`
-// (all-agree → that value, disagreement → `"mixed"`). Writing the
-// aggregate broadcasts to every parent ("select all" / "deselect all");
-// writing `"mixed"` is a no-op. Morally `Maybe<Bool>` — the basis for
-// mixed-state checkbox trees and "loading" predicate states.
 import { Cell } from "../cell.js";
 const equals = (a, b) => a === b;
 /** Kleene negation: `true` / `false` swap, `"mixed"` is fixed. */
@@ -40,14 +34,17 @@ export class Tri extends Cell {
     not() {
         return this.lens(not, not);
     }
-    /** Aggregate over N writable Bools. Read: all-true → `true`,
-     *  all-false → `false`, disagreement → `"mixed"`. Write: `true` /
-     *  `false` broadcast to every parent; `"mixed"` is a no-op. */
+    /** Aggregate over N writable `Bool` / `Tri` children. Read: all-true →
+     *  `true`, all-false → `false`, any disagreement (or any child already
+     *  `"mixed"`) → `"mixed"`. Write: `true` / `false` broadcast to every
+     *  child, recursing through nested aggregates; `"mixed"` is a no-op. */
     static allOf(parents) {
         return Tri.lens(parents, (vs) => {
             let anyT = false;
             let anyF = false;
             for (const v of vs) {
+                if (v === "mixed")
+                    return "mixed";
                 if (v)
                     anyT = true;
                 else
@@ -62,13 +59,16 @@ export class Tri extends Cell {
             return parents.map(() => target);
         });
     }
-    /** Dual of `allOf` (Kleene OR): any-true → `true`, all-false →
-     *  `false`, else `"mixed"`. Same broadcast write policy. */
+    /** Dual of `allOf` (Kleene OR) over `Bool` / `Tri` children: any-true →
+     *  `true`, all-false → `false`, else (or any child `"mixed"`) →
+     *  `"mixed"`. Same broadcast write policy. */
     static anyOf(parents) {
         return Tri.lens(parents, (vs) => {
             let anyT = false;
             let anyF = false;
             for (const v of vs) {
+                if (v === "mixed")
+                    return "mixed";
                 if (v)
                     anyT = true;
                 else

package/dist/core/values/vec.d.ts

@@ -14,6 +14,8 @@ export declare const metric: (a: V, b: V) => number;
 export declare const equals: (a: V, b: V) => boolean;
 export declare const normalize: (v: V) => V;
 export declare const perp: (v: V) => V;
+export declare const rotateAbout: (v: V, p: V, dθ: number) => V;
+export declare const scaleAbout: (v: V, p: V, k: number) => V;
 /** Tangent point on the circle (radius `r`, centre `c`) from external
  *  point `p`. `side: -1` picks the CCW tangent from `pc`, `+1` the CW
  *  (y-down screen coords flip the visual sense). Returns `c` if `p` is
@@ -32,7 +34,12 @@ export declare class Vec extends Cell<V> {
     constructor(v?: V);
     add(b: Val<V>): this;
     sub(b: Val<V>): this;
-    scale(k: Val<number>): this;
+    /** Uniform scale by `k` about `pivot` (default origin). Inverse scales
+     *  by `1/k`; exact bijection for `k ≠ 0`. */
+    scale(k: Val<number>, pivot?: Val<V>): this;
+    /** Rotate by `angle` (radians) about `pivot` (default origin). Inverse
+     *  rotates by `−angle`; exact bijection. */
+    rotate(angle: Val<number>, pivot?: Val<V>): this;
     offset(dx: Val<number>, dy: Val<number>): this;
     up(n: Val<number>): this;
     down(n: Val<number>): this;

package/dist/core/values/vec.js

@@ -20,6 +20,18 @@ export const normalize = (v) => {
     return m === 0 ? { x: 0, y: 0 } : { x: v.x / m, y: v.y / m };
 };
 export const perp = (v) => ({ x: v.y, y: -v.x });
+export const rotateAbout = (v, p, dθ) => {
+    const cos = Math.cos(dθ);
+    const sin = Math.sin(dθ);
+    const dx = v.x - p.x;
+    const dy = v.y - p.y;
+    return { x: p.x + cos * dx - sin * dy, y: p.y + sin * dx + cos * dy };
+};
+export const scaleAbout = (v, p, k) => ({
+    x: p.x + k * (v.x - p.x),
+    y: p.y + k * (v.y - p.y),
+});
+const ORIGIN = { x: 0, y: 0 };
 /** Tangent point on the circle (radius `r`, centre `c`) from external
  *  point `p`. `side: -1` picks the CCW tangent from `pc`, `+1` the CW
  *  (y-down screen coords flip the visual sense). Returns `c` if `p` is
@@ -49,19 +61,7 @@ const packImpl = {
     },
     write: (a, o) => ({ x: a[o], y: a[o + 1] }),
 };
-const pivotalImpl = {
-    rotateAbout: (v, p, dθ) => {
-        const cos = Math.cos(dθ);
-        const sin = Math.sin(dθ);
-        const dx = v.x - p.x;
-        const dy = v.y - p.y;
-        return { x: p.x + cos * dx - sin * dy, y: p.y + sin * dx + cos * dy };
-    },
-    scaleAbout: (v, p, k) => ({
-        x: p.x + k * (v.x - p.x),
-        y: p.y + k * (v.y - p.y),
-    }),
-};
+const pivotalImpl = { rotateAbout, scaleAbout };
 export class Vec extends Cell {
     static traits = {
         linear: linearImpl,
@@ -94,16 +94,26 @@ export class Vec extends Cell {
             return { x: n.x + o.x, y: n.y + o.y };
         });
     }
-    scale(k) {
+    /** Uniform scale by `k` about `pivot` (default origin). Inverse scales
+     *  by `1/k`; exact bijection for `k ≠ 0`. */
+    scale(k, pivot) {
         const kf = reader(k);
+        const pf = pivot === undefined ? undefined : reader(pivot);
         return this.lens(v => {
             const k = kf();
-            return { x: v.x * k, y: v.y * k };
+            return pf ? scaleAbout(v, pf(), k) : { x: v.x * k, y: v.y * k };
         }, n => {
             const k = kf();
-            return { x: n.x / k, y: n.y / k };
+            return pf ? scaleAbout(n, pf(), 1 / k) : { x: n.x / k, y: n.y / k };
         });
     }
+    /** Rotate by `angle` (radians) about `pivot` (default origin). Inverse
+     *  rotates by `−angle`; exact bijection. */
+    rotate(angle, pivot = ORIGIN) {
+        const af = reader(angle);
+        const pf = reader(pivot);
+        return this.lens(v => rotateAbout(v, pf(), af()), n => rotateAbout(n, pf(), -af()));
+    }
     offset(dx, dy) {
         const xf = reader(dx);
         const yf = reader(dy);

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./animation/index.js";
 export * from "./assert/index.js";
 export { type CodeOpts, CodeShape, code, codeStyles, type Token, tokenize } from "./code/index.js";
+export * from "./coll.js";
 export * from "./core/index.js";
 export * from "./ext/index.js";
 export * from "./shapes/index.js";

package/dist/index.js

@@ -3,6 +3,7 @@ export * from "./assert/index.js";
 // `code` and `tex` both export `Part`; re-export `code`'s other symbols
 // explicitly so the wildcard below lets `tex`'s `Part` win.
 export { CodeShape, code, codeStyles, tokenize } from "./code/index.js";
+export * from "./coll.js";
 export * from "./core/index.js";
 export * from "./ext/index.js";
 export * from "./shapes/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bireactive",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Bi-directional reactive programming.",
   "type": "module",
   "main": "./src/index.ts",
@@ -31,7 +31,7 @@
   ],
   "scripts": {
     "dev": "vite --host",
-    "site": "vite-node site/build.ts && vite build && vite-node site/build.ts",
+    "site": "vite-node site/build.ts && vite build && vite-node site/build.ts && typedoc",
     "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",
@@ -63,6 +63,7 @@
     "mitata": "^1.0.34",
     "reactive-framework-test-suite": "^0.0.2",
     "tsc-alias": "^1.8.17",
+    "typedoc": "^0.28.19",
     "typescript": "^6.0.3",
     "vite": "^7.3.3",
     "vite-node": "^5.3.0",