bireactive 0.2.0

package/dist/core/values/template.js

@@ -0,0 +1,148 @@
+// template.ts — bidirectional text templates: typed slots ⇄ rendered string.
+//
+// A template is `lit₀ slot₀ lit₁ slot₁ … litₙ` — a multi-parent `Str.lens`
+// over the slot cells. Forward RENDERS (interleave literals with each
+// slot's formatted value); backward PARSES (split the edited string on the
+// literal delimiters, decode each segment, write the changed slots back).
+// Slots-as-source: the typed cells are canonical and the string is one
+// view, so the same slots can drive several renderings at once (edit any,
+// all stay in sync) — the thing `Str`'s views can't do.
+//
+// Each slot carries a `Codec<T>` (string ⇄ T). That codec is the textual
+// dual of the `pack` trait: `pack : factor :: codec : template` — both
+// serialize a value class into a medium (Float64Array vs string) so one
+// generic lens (LSQ-solve vs parse/print) works over any class that
+// supplies it. Kept local here rather than as a `TraitDict` entry; it can
+// graduate to a trait once a second consumer wants it.
+//
+// Parse is rejection-tolerant: a segment that fails its codec (typing
+// "banana" into a number slot) yields `undefined`, the engine's GetPut
+// stop prunes the no-op, and that slot stays put. A missing delimiter
+// rejects the whole edit. Adjacent slots with no literal between them are
+// ambiguous to split — avoid empty inter-slot literals.
+import { num } from "./num.js";
+import { Str, str } from "./str.js";
+/** Identity codec for string slots. */
+export const strCodec = {
+    format: v => v,
+    parse: s => s,
+};
+/** Numeric codec; `int` rounds on both read and write. Rejects non-finite. */
+export const numCodec = (int = false) => ({
+    format: v => (int ? String(Math.round(v)) : String(v)),
+    parse: s => {
+        const t = s.trim();
+        if (t === "")
+            return undefined;
+        const n = Number(t);
+        if (!Number.isFinite(n))
+            return undefined;
+        return int ? Math.round(n) : n;
+    },
+});
+/** Enumerated string codec: accepts only members of `options`. */
+export const enumCodec = (options) => ({
+    format: v => v,
+    parse: s => (options.includes(s) ? s : undefined),
+});
+/** Slot constructors that infer the codec from the cell's value class. */
+export const slot = {
+    str: (cell, name = "") => ({ name, cell, codec: strCodec }),
+    num: (cell, name = "") => ({ name, cell, codec: numCodec() }),
+    int: (cell, name = "") => ({ name, cell, codec: numCodec(true) }),
+    pick: (cell, options, name = "") => ({
+        name,
+        cell,
+        codec: enumCodec(options),
+    }),
+};
+const render = (literals, slots, vals) => {
+    let out = literals[0] ?? "";
+    for (let i = 0; i < slots.length; i++) {
+        out += slots[i].codec.format(vals[i]);
+        out += literals[i + 1] ?? "";
+    }
+    return out;
+};
+const parse = (literals, slots, edited) => {
+    const k = slots.length;
+    const reject = () => new Array(k).fill(undefined);
+    const updates = reject();
+    const lit0 = literals[0] ?? "";
+    if (!edited.startsWith(lit0))
+        return updates;
+    let pos = lit0.length;
+    for (let i = 0; i < k; i++) {
+        const delim = literals[i + 1] ?? "";
+        let segEnd;
+        if (delim === "") {
+            // Last segment runs to the end; an empty interior literal means two
+            // adjacent slots — unsplittable, so this slot takes the empty span.
+            segEnd = i === k - 1 ? edited.length : pos;
+        }
+        else {
+            const idx = edited.indexOf(delim, pos);
+            if (idx < 0)
+                return reject();
+            segEnd = idx;
+        }
+        const v = slots[i].codec.parse(edited.slice(pos, segEnd));
+        if (v !== undefined)
+            updates[i] = v;
+        pos = segEnd + delim.length;
+    }
+    return updates;
+};
+/** Core builder: `literals.length === slots.length + 1`. Returns the
+ *  rendered text as a `Writable<Str>` that parses back into the slots. */
+export function template(literals, slots) {
+    if (slots.length === 0)
+        return str(literals.join(""));
+    const cells = slots.map(s => s.cell);
+    // Heterogeneous, dynamic-length parents don't fit the static N-tuple
+    // overload; bind a flat signature at the boundary. `.bind(Str)` keeps the
+    // static `this` (the lens reads it as the constructor).
+    const lensN = Str.lens.bind(Str);
+    return lensN(cells, vals => render(literals, slots, vals), edited => parse(literals, slots, edited));
+}
+/** Tagged template; interpolate `slot.*` holes. Bring your own cells:
+ *
+ *      tpl`Hello ${slot.str(name)}, ×${slot.int(count)}` */
+export function tpl(strings, ...slots) {
+    return template([...strings], slots);
+}
+/** Parse a `:name` pattern against a kind schema, owning fresh slot cells.
+ *  Returns the rendered URL `text` and the typed `params` cells; edit
+ *  either side and the other stays in sync.
+ *
+ *      const { text, params } = route("/users/:id/posts/:slug",
+ *        { id: "int", slug: "str" }); */
+export function route(pattern, schema) {
+    const literals = [];
+    const slots = [];
+    const params = {};
+    const re = /:([A-Za-z_][A-Za-z0-9_]*)/g;
+    let last = 0;
+    let m = re.exec(pattern);
+    while (m !== null) {
+        literals.push(pattern.slice(last, m.index));
+        const name = m[1];
+        const kind = schema[name];
+        if (!kind)
+            throw new Error(`route: ":${name}" has no schema entry`);
+        if (kind === "str") {
+            const c = str("");
+            params[name] = c;
+            slots.push(slot.str(c, name));
+        }
+        else {
+            const c = num(0);
+            params[name] = c;
+            slots.push(kind === "int" ? slot.int(c, name) : slot.num(c, name));
+        }
+        last = m.index + m[0].length;
+        m = re.exec(pattern);
+    }
+    literals.push(pattern.slice(last));
+    return { text: template(literals, slots), params: params };
+}

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

@@ -0,0 +1,49 @@
+import type { Easing } from "../../animation/index.js";
+import { type Tween } from "../anim.js";
+import { Cell, type Inner, type Val, type Writable } from "../signal.js";
+import type { Linear } from "../traits.js";
+import { Num } from "./num.js";
+import { Vec } from "./vec.js";
+type V = {
+    translate: Inner<Vec>;
+    scale: Inner<Vec>;
+    origin: Inner<Vec>;
+    rotate: number;
+    opacity: number;
+};
+export declare const DEFAULT: V;
+export declare const add: (a: V, b: V) => V;
+export declare const sub: (a: V, b: V) => V;
+export declare const scale: (a: V, k: number) => V;
+export declare const lerp: (a: V, b: V, t: number) => V;
+export declare const equals: (a: V, b: V) => boolean;
+export declare const metric: (a: V, b: V) => number;
+export declare class Transform extends Cell<V> {
+    static traits: {
+        linear: Linear<V>;
+        lerp: (a: V, b: V, t: number) => V;
+        metric: (a: V, b: V) => number;
+        equals: (a: V, b: V) => boolean;
+    };
+    readonly _t: typeof Transform.traits;
+    /** Scalar `scale` is the `.scale` Vec field lens, not an eager method;
+     *  scalar-multiply via `Transform.lens(...)` or field writes. */
+    constructor(v?: V);
+    add(b: Val<V>): this;
+    sub(b: Val<V>): this;
+    lerp(b: Val<V>, t: Val<number>): Transform;
+    get translate(): this extends import("../index.js").WritableBrand ? Writable<Vec> : Vec;
+    get scale(): this extends import("../index.js").WritableBrand ? Writable<Vec> : Vec;
+    get origin(): this extends import("../index.js").WritableBrand ? Writable<Vec> : Vec;
+    get rotate(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
+    get opacity(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
+    /** Tween-builder, implied by the lerp trait. */
+    to(this: Writable<Transform>, target: V, dur: Val<number>, ease?: Easing): Tween<V>;
+}
+export type TransformInit = {
+    [K in keyof V]?: V[K];
+};
+/** Seed a `Writable<Transform>` from literal values. For reactive
+ *  sources, use `Transform.lens(...)` or field-write composition. */
+export declare function transform(init?: TransformInit): Writable<Transform>;
+export {};

package/dist/core/values/transform.js

@@ -0,0 +1,115 @@
+// transform.ts — reactive 2D transform.
+//
+// Invertibles (`add`, `sub`) return `: this` and ride on
+// `Cell#lens(fwd, bwd)`; chained calls compose into a lens chain.
+// Field-lens getters use `field()`, so writability propagates through
+// nested chains
+// (`Transform.translate.x.value = 5` works on writable receivers).
+import { tween } from "../anim.js";
+import { Cell, reader, readNow } from "../signal.js";
+import { field } from "../writable.js";
+import { Num } from "./num.js";
+import { Vec, add as vAdd, equals as vEquals, lerp as vLerp, metric as vMetric, scale as vScale, sub as vSub, } from "./vec.js";
+export const DEFAULT = {
+    translate: { x: 0, y: 0 },
+    scale: { x: 1, y: 1 },
+    origin: { x: 0, y: 0 },
+    rotate: 0,
+    opacity: 1,
+};
+export const add = (a, b) => ({
+    translate: vAdd(a.translate, b.translate),
+    scale: vAdd(a.scale, b.scale),
+    origin: vAdd(a.origin, b.origin),
+    rotate: a.rotate + b.rotate,
+    opacity: a.opacity + b.opacity,
+});
+export const sub = (a, b) => ({
+    translate: vSub(a.translate, b.translate),
+    scale: vSub(a.scale, b.scale),
+    origin: vSub(a.origin, b.origin),
+    rotate: a.rotate - b.rotate,
+    opacity: a.opacity - b.opacity,
+});
+export const scale = (a, k) => ({
+    translate: vScale(a.translate, k),
+    scale: vScale(a.scale, k),
+    origin: vScale(a.origin, k),
+    rotate: a.rotate * k,
+    opacity: a.opacity * k,
+});
+export const lerp = (a, b, t) => ({
+    translate: vLerp(a.translate, b.translate, t),
+    scale: vLerp(a.scale, b.scale, t),
+    origin: vLerp(a.origin, b.origin, t),
+    rotate: a.rotate + (b.rotate - a.rotate) * t,
+    opacity: a.opacity + (b.opacity - a.opacity) * t,
+});
+export const equals = (a, b) => a === b ||
+    (vEquals(a.translate, b.translate) &&
+        vEquals(a.scale, b.scale) &&
+        vEquals(a.origin, b.origin) &&
+        a.rotate === b.rotate &&
+        a.opacity === b.opacity);
+export const metric = (a, b) => vMetric(a.translate, b.translate) +
+    vMetric(a.scale, b.scale) +
+    vMetric(a.origin, b.origin) +
+    Math.abs(a.rotate - b.rotate) +
+    Math.abs(a.opacity - b.opacity);
+const linearImpl = { add, sub, scale };
+export class Transform extends Cell {
+    static traits = { linear: linearImpl, lerp, metric, equals };
+    /** Scalar `scale` is the `.scale` Vec field lens, not an eager method;
+     *  scalar-multiply via `Transform.lens(...)` or field writes. */
+    constructor(v = DEFAULT) {
+        super(v, { equals });
+    }
+    add(b) {
+        const bf = reader(b);
+        return this.lens(v => add(v, bf()), n => sub(n, bf()));
+    }
+    sub(b) {
+        const bf = reader(b);
+        return this.lens(v => sub(v, bf()), n => add(n, bf()));
+    }
+    lerp(b, t) {
+        return Transform.derive(() => lerp(this.value, readNow(b), readNow(t)));
+    }
+    get translate() {
+        return field(this, "translate", Vec);
+    }
+    get scale() {
+        return field(this, "scale", Vec);
+    }
+    get origin() {
+        return field(this, "origin", Vec);
+    }
+    get rotate() {
+        return field(this, "rotate", Num);
+    }
+    get opacity() {
+        return field(this, "opacity", Num);
+    }
+    /** Tween-builder, implied by the lerp trait. */
+    to(target, dur, ease) {
+        return tween(this, target, dur, ease);
+    }
+}
+/** Seed a `Writable<Transform>` from literal values. For reactive
+ *  sources, use `Transform.lens(...)` or field-write composition. */
+export function transform(init) {
+    const tr = new Transform();
+    if (init) {
+        if (init.translate !== undefined)
+            tr.translate.value = init.translate;
+        if (init.scale !== undefined)
+            tr.scale.value = init.scale;
+        if (init.origin !== undefined)
+            tr.origin.value = init.origin;
+        if (init.rotate !== undefined)
+            tr.rotate.value = init.rotate;
+        if (init.opacity !== undefined)
+            tr.opacity.value = init.opacity;
+    }
+    return tr;
+}

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

@@ -0,0 +1,31 @@
+import { Cell, type Init, type Writable } from "../signal.js";
+import type { Bool } from "./bool.js";
+type V = boolean | "mixed";
+/** Kleene negation: `true` / `false` swap, `"mixed"` is fixed. */
+export declare const not: (a: V) => V;
+/** Kleene AND: a known `false` dominates; otherwise mixed unless both
+ *  are known and true. */
+export declare const and: (a: V, b: V) => V;
+/** Kleene OR: a known `true` dominates; otherwise mixed unless both
+ *  are known and false. */
+export declare const or: (a: V, b: V) => V;
+export declare class Tri extends Cell<V> {
+    static traits: {
+        equals: (a: V, b: V) => boolean;
+    };
+    readonly _t: typeof Tri.traits;
+    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>;
+}
+/** Writable `Tri`. Strict factory: `Tri.value | Writable<Tri>` in,
+ *  `Writable<Tri>` out. Default initial value is `"mixed"`. */
+export declare function tri(v?: Init<Tri>): Writable<Tri>;
+export {};

package/dist/core/values/tri.js

@@ -0,0 +1,95 @@
+// tri.ts — three-valued logical type (Kleene logic).
+//
+// `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 "../signal.js";
+const equals = (a, b) => a === b;
+/** Kleene negation: `true` / `false` swap, `"mixed"` is fixed. */
+export const not = (a) => (a === "mixed" ? "mixed" : !a);
+/** Kleene AND: a known `false` dominates; otherwise mixed unless both
+ *  are known and true. */
+export const and = (a, b) => {
+    if (a === false || b === false)
+        return false;
+    if (a === true && b === true)
+        return true;
+    return "mixed";
+};
+/** Kleene OR: a known `true` dominates; otherwise mixed unless both
+ *  are known and false. */
+export const or = (a, b) => {
+    if (a === true || b === true)
+        return true;
+    if (a === false && b === false)
+        return false;
+    return "mixed";
+};
+export class Tri extends Cell {
+    static traits = { equals };
+    constructor(v = "mixed") {
+        super(v, { equals });
+    }
+    /** Kleene negation. Involution; fixed at `"mixed"`. */
+    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. */
+    static allOf(parents) {
+        return Tri.lens(parents, (vs) => {
+            let anyT = false;
+            let anyF = false;
+            for (const v of vs) {
+                if (v)
+                    anyT = true;
+                else
+                    anyF = true;
+                if (anyT && anyF)
+                    return "mixed";
+            }
+            return anyT;
+        }, (target, _vs) => {
+            if (target === "mixed")
+                return parents.map(() => undefined);
+            return parents.map(() => target);
+        });
+    }
+    /** Dual of `allOf` (Kleene OR): any-true → `true`, all-false →
+     *  `false`, else `"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)
+                    anyT = true;
+                else
+                    anyF = true;
+            }
+            if (anyT && !anyF)
+                return true;
+            if (!anyT && anyF)
+                return false;
+            return "mixed";
+        }, (target, _vs) => {
+            if (target === "mixed")
+                return parents.map(() => undefined);
+            return parents.map(() => target);
+        });
+    }
+}
+/** Writable `Tri`. Strict factory: `Tri.value | Writable<Tri>` in,
+ *  `Writable<Tri>` out. Default initial value is `"mixed"`. */
+export function tri(v = "mixed") {
+    if (v instanceof Tri)
+        return v;
+    return new Tri(v);
+}

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

@@ -0,0 +1,72 @@
+import type { Easing } from "../../animation/index.js";
+import { type Tween } from "../anim.js";
+import { Cell, type Init, type Val, type Writable } from "../signal.js";
+import type { Linear, Pack, Pivotal } from "../traits.js";
+import { Num } from "./num.js";
+type V = {
+    x: number;
+    y: number;
+};
+export declare const add: (a: V, b: V) => V;
+export declare const sub: (a: V, b: V) => V;
+export declare const scale: (a: V, k: number) => V;
+export declare const lerp: (a: V, b: V, t: number) => V;
+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;
+/** 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
+ *  inside or on the circle. */
+export declare function tangentPoint(p: V, c: V, r: number, side?: 1 | -1): V;
+export declare class Vec extends Cell<V> {
+    static traits: {
+        linear: Linear<V>;
+        lerp: (a: V, b: V, t: number) => V;
+        metric: (a: V, b: V) => number;
+        equals: (a: V, b: V) => boolean;
+        pack: Pack<V>;
+        pivotal: Pivotal<V>;
+    };
+    readonly _t: typeof Vec.traits;
+    constructor(v?: V);
+    add(b: Val<V>): this;
+    sub(b: Val<V>): this;
+    scale(k: Val<number>): this;
+    offset(dx: Val<number>, dy: Val<number>): this;
+    up(n: Val<number>): this;
+    down(n: Val<number>): this;
+    left(n: Val<number>): this;
+    right(n: Val<number>): this;
+    normalize(): Vec;
+    perp(): Vec;
+    lerp(b: Val<V>, t: Val<number>): Vec;
+    distance(other: Val<V>): Num;
+    get x(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
+    get y(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
+    get magnitude(): Num;
+    /** Tween-builder; `this: Writable<Vec>` gates the call to writable
+     *  receivers. */
+    to(this: Writable<Vec>, target: V, dur: Val<number>, ease?: Easing): Tween<V>;
+}
+/** Writable `Vec` at `(x, y)`. Each axis is a literal `number` (lifted
+ *  to a fresh seed) or an existing `Writable<Num>` (identity passthrough).
+ *  RO sources are rejected at the type level — use `Vec.derive(...)` for
+ *  reactive RO tracking, or `cell.value` to snapshot. Lock an axis with
+ *  `Num.pin(c)`: `vec(slider, Num.pin(100))`. */
+export declare function vec(x?: Init<Num>, y?: Init<Num>): Writable<Vec>;
+/** Policy for `polar`'s inverse — which inputs absorb a write:
+ *
+ *  - `rotate`    — c fixed; write r and a to land on target.
+ *  - `translate` — r and a fixed; shift c by Δ.
+ *  - `radial`    — c and a fixed; project the drag onto the ray.
+ *  - `circular`  — c and r fixed; project the drag onto the circle. */
+export type PolarPolicy = "rotate" | "translate" | "radial" | "circular";
+/** Vec at polar offset from `center`: `center + (r·cos a, r·sin a)`.
+ *  Bidirectional; each input is a literal (lifted to a fresh seed) or an
+ *  existing writable cell. RO inputs are rejected at the type level.
+ *  `policy` selects which inputs absorb writes; lock one with
+ *  `Num.pin(c)`: `polar(c, Num.pin(100), a)`. */
+export declare function polar(center: Init<Vec>, r: Init<Num>, a: Init<Num>, policy?: PolarPolicy): Writable<Vec>;
+export {};