bireactive 0.2.2 → 0.2.3

package/README.md

@@ -1,6 +1,6 @@
 # bi-reactive
 
-[npm](https://www.npmjs.com/package/bireactive) · [GitHub](https://github.com/OrionReed/bireactive) · [site](https://orionreed.github.io/bireactive/)
+[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.
 

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/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.2",
+  "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",