bireactive 0.2.0

package/dist/tex/motion.js

@@ -0,0 +1,290 @@
+// Motion combinators over tex shapes (`pluck`, `morph`, …).
+import { easeInOut, easeOut } from "../animation/index.js";
+import { effect, num } from "../core/index.js";
+import { Shape } from "../shapes/index.js";
+/** Pulse a part's `highlighted` signal for `dt` seconds. */
+export function* highlight(part, dt = 0.6) {
+    part.highlighted.value = true;
+    try {
+        yield dt;
+    }
+    finally {
+        part.highlighted.value = false;
+    }
+}
+/** Reveal an eq left-to-right via a clip-path sweep on the inner HTML
+ *  wrapper. (Animated clip-path on the outer `<g>` tears foreignObject
+ *  content in Chromium.) */
+export function* write(eq, dt = 0.6, ease = easeOut) {
+    const target = clipTarget(eq);
+    const progress = num(0);
+    const stop = effect(() => {
+        target.style.clipPath = `inset(0 ${(1 - progress.value) * 100}% 0 0)`;
+    });
+    try {
+        yield* progress.to(1, dt, ease);
+    }
+    finally {
+        target.style.clipPath = "";
+        stop();
+    }
+}
+/** Reverse of `write`; ends hidden (`opacity: 0`, clip-path cleared). */
+export function* writeOut(eq, dt = 0.4, ease = easeOut) {
+    const target = clipTarget(eq);
+    const progress = num(1);
+    const stop = effect(() => {
+        target.style.clipPath = `inset(0 ${(1 - progress.value) * 100}% 0 0)`;
+    });
+    try {
+        yield* progress.to(0, dt, ease);
+    }
+    finally {
+        stop();
+        eq.opacity.value = 0;
+        target.style.clipPath = "";
+    }
+}
+/** Inner HTML wrapper inside the foreignObject; falls back to `<g>`. */
+const clipTarget = (eq) => {
+    const fo = eq.intrinsic;
+    const wrapper = fo?.firstElementChild;
+    return wrapper instanceof HTMLElement ? wrapper : eq.el;
+};
+const findMathWrapper = (matchedEl) => {
+    let cur = matchedEl.parentElement;
+    while (cur && cur.tagName.toLowerCase() !== "math") {
+        cur = cur.parentElement;
+    }
+    if (!cur)
+        return null;
+    const wrapper = cur.parentElement;
+    return wrapper instanceof HTMLElement ? wrapper : null;
+};
+/** Part's matched-mrow position in parent-frame coords. */
+const partPose = (part) => {
+    const tr = part.host.translate.value;
+    const a = part.box.value;
+    return { x: tr.x + a.x, y: tr.y + a.y };
+};
+/** A Part lifted out of its TexShape into a free Shape. `translate` is
+ *  the matched mrow's TL in parent coords; `scale` pivots around it.
+ *  Zeroes the source's opacity until `dispose()`. */
+export class Plucked extends Shape {
+    source;
+    #sourcePrevOpacity;
+    constructor(source) {
+        const a = source.box.peek();
+        const local = { x: 0, y: 0, w: a.w, h: a.h };
+        super("foreignObject", () => local);
+        this.source = source;
+        this.#sourcePrevOpacity = source.opacity.peek();
+        source.opacity.value = 0;
+    }
+    dispose() {
+        this.source.opacity.value = this.#sourcePrevOpacity;
+        super.dispose();
+    }
+}
+/** Lift `part` out of its TexShape, mount under the same parent,
+ *  return the Plucked. Restore via `plucked.dispose()` or `unpluck`. */
+export function pluck(part) {
+    const liveEl = part.el;
+    const host = part.host;
+    if (!liveEl || !host.parent) {
+        throw new Error("pluck: TexShape isn't mounted yet — `s(eq)` it before plucking");
+    }
+    const wrapper = findMathWrapper(liveEl);
+    if (!wrapper)
+        throw new Error("pluck: cannot find <math> wrapper");
+    const boxLocal = part.box.value;
+    const pose = partPose(part);
+    // Deep-clone, then hide all but the matched mrow via `visibility`
+    // (not `display: none`, which would drop the preserved layout).
+    const clonedWrapper = wrapper.cloneNode(true);
+    const matchedClone = clonedWrapper.querySelector(`.bireactive-part-${part.name}`);
+    const mathClone = clonedWrapper.querySelector("math");
+    if (!matchedClone || !mathClone) {
+        throw new Error("pluck: cloned wrapper lost its matched mrow");
+    }
+    mathClone.style.visibility = "hidden";
+    matchedClone.style.visibility = "visible";
+    // Shift the mrow to local (0, 0); with `Plucked.box = (0,0,w,h)` this
+    // makes `plucked.translate` mean "matched mrow TL in parent coords".
+    clonedWrapper.style.transform = `translate(${-boxLocal.x}px, ${-boxLocal.y}px)`;
+    clonedWrapper.style.transformOrigin = "0 0";
+    const plucked = new Plucked(part);
+    const fo = plucked.intrinsic;
+    fo.setAttribute("x", "0");
+    fo.setAttribute("y", "0");
+    fo.setAttribute("width", String(Math.max(host.width.value + 32, 1)));
+    fo.setAttribute("height", String(Math.max(host.height.value + 16, 1)));
+    fo.style.overflow = "visible";
+    fo.style.pointerEvents = "none";
+    fo.appendChild(clonedWrapper);
+    plucked.translate.value = pose;
+    host.parent.add(plucked);
+    return plucked;
+}
+/** Animate `plucked` into `target`'s pose (or back to its source), then
+ *  dispose. Translates only; animate `scale` yourself to fit a target. */
+export function* unpluck(plucked, target, dt = 0.5, ease = easeInOut) {
+    const dest = target ?? plucked.source;
+    try {
+        yield* plucked.translate.to(partPose(dest), dt, ease);
+    }
+    finally {
+        plucked.dispose();
+    }
+}
+/** Animate `from` → `to`, matching Parts by marker identity (same
+ *  marker reference, or markers sharing a `group` root). Branches
+ *  by cardinality of each identity:
+ *
+ *    1↔1 same content → single rider, scaled to dest
+ *    1↔1 different    → dual rider, source fades out, dest fades in
+ *    1↔N              → N riders emerge from source, fan to dests
+ *    N↔1              → N riders converge to dest, fade out
+ *    N↔M              → pair by index; extras parent-crossfade
+ *
+ *  Unmatched parts cross-fade with the parent. Assumes both shapes
+ *  share a parent and have translate-only transforms. */
+export function* morph(from, to, dt = 0.6, ease = easeInOut) {
+    const parent = from.parent;
+    if (!parent || from.parent !== to.parent) {
+        if (to.opacity.peek() < 1)
+            to.opacity.value = 0;
+        yield [from.opacity.to(0, dt, ease), to.opacity.to(1, dt, ease)];
+        return;
+    }
+    // Hide `to` so riders supply visible content during the flight.
+    if (to.opacity.peek() !== 0)
+        to.opacity.value = 0;
+    const animators = [from.opacity.to(0, dt, ease), to.opacity.to(1, dt, ease)];
+    const cleanups = [];
+    const fromByRoot = groupByRoot(from.parts);
+    const toByRoot = groupByRoot(to.parts);
+    for (const root of new Set([...fromByRoot.keys(), ...toByRoot.keys()])) {
+        const fps = fromByRoot.get(root) ?? [];
+        const tps = toByRoot.get(root) ?? [];
+        if (fps.length === 0 || tps.length === 0)
+            continue;
+        if (fps.length === 1 && tps.length === 1) {
+            ride(fps[0], tps[0], dt, ease, animators, cleanups);
+        }
+        else if (fps.length === 1 && tps.length > 1) {
+            fanOut(fps[0], tps, dt, ease, animators, cleanups);
+        }
+        else if (fps.length > 1 && tps.length === 1) {
+            fanIn(fps, tps[0], dt, ease, animators, cleanups);
+        }
+        else {
+            // N↔M: pair by index; extras parent-crossfade.
+            const n = Math.min(fps.length, tps.length);
+            for (let i = 0; i < n; i++)
+                ride(fps[i], tps[i], dt, ease, animators, cleanups);
+        }
+    }
+    try {
+        yield animators;
+    }
+    finally {
+        for (const c of cleanups)
+            c();
+        from.opacity.value = 0;
+        to.opacity.value = 1;
+    }
+}
+/** Topmost marker in a `marker.group` chain — two markers share
+ *  identity for morph iff they share a root. */
+const groupRoot = (m) => {
+    let r = m;
+    while (r.group)
+        r = r.group;
+    return r;
+};
+const groupByRoot = (parts) => {
+    const out = new Map();
+    for (const p of parts) {
+        if (!p.el)
+            continue;
+        const a = p.box.value;
+        if (a.w === 0 || a.h === 0)
+            continue;
+        const r = groupRoot(p.marker);
+        const list = out.get(r);
+        if (list)
+            list.push(p);
+        else
+            out.set(r, [p]);
+    }
+    return out;
+};
+/** 1↔1 ride. Same content: single source clone, scaled to dest.
+ *  Different content: dual clone on the same trajectory, crossfade. */
+const ride = (p, q, dt, ease, animators, cleanups) => {
+    const pa = p.box.value;
+    const qa = q.box.value;
+    const destPose = partPose(q);
+    const sameContent = p.content.peek() === q.content.peek();
+    const src = pluck(p);
+    animators.push(src.translate.to(destPose, dt, ease), src.scale.to({ x: qa.w / pa.w, y: qa.h / pa.h }, dt, ease));
+    cleanups.push(() => src.dispose());
+    if (sameContent) {
+        // Source rider IS the right content; just hide q during flight.
+        const prevQ = q.opacity.peek();
+        q.opacity.value = 0;
+        cleanups.push(() => {
+            q.opacity.value = prevQ;
+        });
+    }
+    else {
+        // Dest rider starts at p's pose, scaled to p's footprint, faded
+        // out — then rides to q's pose at full size, fading in.
+        const dst = pluck(q);
+        dst.translate.value = partPose(p);
+        dst.scale.value = { x: pa.w / qa.w, y: pa.h / qa.h };
+        dst.opacity.value = 0;
+        animators.push(src.opacity.to(0, dt, ease), dst.translate.to(destPose, dt, ease), dst.scale.to({ x: 1, y: 1 }, dt, ease), dst.opacity.to(1, dt, ease));
+        cleanups.push(() => dst.dispose());
+    }
+};
+/** 1→N. Source rider fades out in place; N dest riders emerge from
+ *  source's pose and fan out to their respective slots. */
+const fanOut = (p, qs, dt, ease, animators, cleanups) => {
+    const pa = p.box.value;
+    const pPose = partPose(p);
+    const src = pluck(p);
+    animators.push(src.opacity.to(0, dt, ease));
+    cleanups.push(() => src.dispose());
+    for (const q of qs) {
+        const qa = q.box.value;
+        const dst = pluck(q);
+        dst.translate.value = pPose;
+        dst.scale.value = { x: pa.w / qa.w, y: pa.h / qa.h };
+        dst.opacity.value = 0;
+        animators.push(dst.translate.to(partPose(q), dt, ease), dst.scale.to({ x: 1, y: 1 }, dt, ease), dst.opacity.to(1, dt, ease));
+        cleanups.push(() => dst.dispose());
+    }
+};
+/** N→1. N source riders converge to dest's slot, fading out;
+ *  dest fades in there. */
+const fanIn = (ps, q, dt, ease, animators, cleanups) => {
+    const qa = q.box.value;
+    const qPose = partPose(q);
+    for (const p of ps) {
+        const pa = p.box.value;
+        const src = pluck(p);
+        animators.push(src.translate.to(qPose, dt, ease), src.scale.to({ x: qa.w / pa.w, y: qa.h / pa.h }, dt, ease), src.opacity.to(0, dt, ease));
+        cleanups.push(() => src.dispose());
+    }
+    // Dest rider fades in at q's pos so q is visible during the
+    // parent's partial crossfade.
+    const dst = pluck(q);
+    dst.opacity.value = 0;
+    animators.push(dst.opacity.to(1, dt, ease));
+    cleanups.push(() => dst.dispose());
+};
+// No part-level `swap`: to swap two parts visually, morph between two
+// equations holding them in opposite slots — `morph(tex`${a}${b}`,
+// tex`${b}${a}`)`. See md-tex-demo.

package/dist/tex/parts.d.ts

@@ -0,0 +1,65 @@
+import { type Box, Cell, type Val, type Writable } from "../core/index.js";
+import { type Marker } from "./marker.js";
+import type { TexShape } from "./tex.js";
+export type { Marker };
+export type PartContent = Val<string>;
+/** Named, addressable region of a TexShape (read-only, template-bound).
+ *  Reach into `part.box` for axes/cardinals. */
+export declare class Part<N extends string = string> {
+    #private;
+    readonly name: N;
+    readonly content: Cell<string>;
+    readonly marker: PartMarker;
+    readonly host: TexShape;
+    /** Background-tint highlight; written by `highlight()` and `bindParts()`. */
+    readonly highlighted: Writable<Cell<boolean>>;
+    readonly opacity: Writable<import("../core/index.js").Num>;
+    readonly box: Box;
+    el: HTMLElement | null;
+    constructor(name: N, content: Cell<string>, box: Box, marker: PartMarker, host: TexShape);
+    /** @internal Wire reactive state to `el`'s inline styles. */
+    bind(el: HTMLElement | null, highlightColor: string): void;
+    /** @internal */
+    dispose(): void;
+}
+/** Marker emitted by `part()` / `parts()`; valid inside `tex\`…\`` holes.
+ *  Group members share one inner `Marker` so they share identity. */
+export declare class PartMarker<N extends string = string> {
+    #private;
+    readonly name: N;
+    readonly group: PartMarker | null;
+    /** Per-instance color; `null` walks up the group chain. */
+    readonly color: Writable<Cell<string | null>>;
+    readonly content: Cell<string>;
+    constructor(name: N, source: PartContent, group?: PartMarker | null);
+    /** True when any rendering of this identity (prose/shape/anim) is active. */
+    get active(): Cell<boolean>;
+    /** Bind a local boolean signal to this marker's identity. */
+    bind(local: Writable<Cell<boolean>>): () => void;
+    /** Register in the global lookup under `id`. */
+    register(id: string): this;
+    /** One-off content override, same identity. */
+    with(content: PartContent): PartMarker<N>;
+    /** Expand into named child markers sharing this identity (1↔N morph). */
+    expand<T extends Record<string, PartContent>>(spec: T): {
+        readonly [K in keyof T & string]: PartMarker<K>;
+    };
+}
+export declare function part<N extends string>(name: N, content?: PartContent): PartMarker<N>;
+export declare function parts<T extends readonly (string | Record<string, PartContent>)[]>(...specs: T): MarkersFromSpecs<T>;
+type MarkersFromSpecs<T extends readonly (string | Record<string, PartContent>)[]> = {
+    readonly [K in NameOf<T[number]>]: PartMarker<K>;
+};
+type NameOf<S> = S extends string ? S : S extends Record<infer K, PartContent> ? K & string : never;
+/** Set the same color on N markers at once. */
+export declare function tint(color: string | null, ...markers: readonly {
+    color: Writable<Cell<string | null>>;
+}[]): void;
+/** Wire hover on each `Part.el` to its `Marker`; drive `highlighted`
+ *  from `active`. Unmatched names are silently skipped. */
+export declare function bindParts(eq: {
+    parts: Iterable<Part<string>>;
+}, markers: Partial<Record<string, Marker>>): () => void;
+export type PartList<Names extends string = string> = readonly Part[] & {
+    readonly [K in Names]: Part<K>;
+};

package/dist/tex/parts.js

@@ -0,0 +1,149 @@
+// Observable handles into a tex-rendered formula. Identity for morph
+// is by marker reference; `with`/`expand` share the root's identity.
+// Color cascades up the `group` chain via `effectiveColor`.
+import { Cell, cell, derive, effect, num, } from "../core/index.js";
+import { highlightTint, hover, marker, registerMarker } from "./marker.js";
+/** Walk the `marker.group` chain to first non-null color. */
+const effectiveColor = (m) => {
+    for (let cur = m; cur; cur = cur.group) {
+        const c = cur.color.value;
+        if (c !== null)
+            return c;
+    }
+    return null;
+};
+/** Named, addressable region of a TexShape (read-only, template-bound).
+ *  Reach into `part.box` for axes/cardinals. */
+export class Part {
+    name;
+    content;
+    marker;
+    host;
+    /** Background-tint highlight; written by `highlight()` and `bindParts()`. */
+    highlighted = cell(false);
+    opacity = num(1);
+    box;
+    el = null;
+    #disposers = [];
+    constructor(name, content, box, marker, host) {
+        this.name = name;
+        this.content = content;
+        this.marker = marker;
+        this.host = host;
+        this.box = box;
+    }
+    /** @internal Wire reactive state to `el`'s inline styles. */
+    bind(el, highlightColor) {
+        for (const d of this.#disposers)
+            d();
+        this.#disposers.length = 0;
+        this.el = el;
+        if (!el)
+            return;
+        this.#disposers.push(effect(() => {
+            if (this.highlighted.value) {
+                const color = effectiveColor(this.marker);
+                el.style.backgroundColor = color ? highlightTint(color) : highlightColor;
+            }
+            else {
+                el.style.backgroundColor = "transparent";
+            }
+        }), effect(() => {
+            el.style.opacity = String(this.opacity.value);
+        }), effect(() => {
+            el.style.color = effectiveColor(this.marker) ?? "";
+        }));
+    }
+    /** @internal */
+    dispose() {
+        for (const d of this.#disposers)
+            d();
+        this.#disposers.length = 0;
+        this.el = null;
+    }
+}
+/** Marker emitted by `part()` / `parts()`; valid inside `tex\`…\`` holes.
+ *  Group members share one inner `Marker` so they share identity. */
+export class PartMarker {
+    name;
+    group;
+    /** Per-instance color; `null` walks up the group chain. */
+    color = cell(null);
+    content;
+    /** Shared inner Marker; all group members alias the root's instance. */
+    #m;
+    constructor(name, source, group = null) {
+        this.name = name;
+        this.group = group;
+        this.content =
+            source instanceof Cell
+                ? source
+                : typeof source === "function"
+                    ? derive(source)
+                    : cell(source);
+        this.#m = group ? group.#m : marker();
+    }
+    /** True when any rendering of this identity (prose/shape/anim) is active. */
+    get active() {
+        return this.#m.active;
+    }
+    /** Bind a local boolean signal to this marker's identity. */
+    bind(local) {
+        return this.#m.bind(local);
+    }
+    /** Register in the global lookup under `id`. */
+    register(id) {
+        registerMarker(id, this);
+        return this;
+    }
+    /** One-off content override, same identity. */
+    with(content) {
+        return new PartMarker(this.name, content, this);
+    }
+    /** Expand into named child markers sharing this identity (1↔N morph). */
+    expand(spec) {
+        const out = {};
+        for (const k in spec)
+            out[k] = new PartMarker(k, spec[k], this);
+        return out;
+    }
+}
+export function part(name, content = name) {
+    return new PartMarker(name, content);
+}
+export function parts(...specs) {
+    const out = {};
+    for (const spec of specs) {
+        if (typeof spec === "string") {
+            out[spec] = new PartMarker(spec, spec);
+        }
+        else {
+            for (const k in spec)
+                out[k] = new PartMarker(k, spec[k]);
+        }
+    }
+    return out;
+}
+/** Set the same color on N markers at once. */
+export function tint(color, ...markers) {
+    for (const m of markers)
+        m.color.value = color;
+}
+/** Wire hover on each `Part.el` to its `Marker`; drive `highlighted`
+ *  from `active`. Unmatched names are silently skipped. */
+export function bindParts(eq, markers) {
+    const ds = [];
+    for (const p of eq.parts) {
+        const m = markers[p.name];
+        if (!m || !p.el)
+            continue;
+        ds.push(hover(p.el, m));
+        ds.push(effect(() => {
+            p.highlighted.value = m.active.value;
+        }));
+    }
+    return () => {
+        for (const d of ds)
+            d();
+    };
+}

package/dist/tex/tex.d.ts

@@ -0,0 +1,45 @@
+import { type Cell } from "../core/index.js";
+import { Shape, type ShapeOpts } from "../shapes/index.js";
+import { type PartList, PartMarker } from "./parts.js";
+/** A `tex\`…\`` interpolation slot. Strings splice verbatim; PartMarkers
+ *  wrap content in `\class{bireactive-part-N}{…}` to be re-found post-render. */
+export type TexInterp = string | PartMarker;
+export interface TexOpts extends ShapeOpts {
+    /** Font size in user units. Defaults to `tokens.fontSize`. */
+    size?: number;
+    /** Font family. Defaults to `tokens.mathFont`. */
+    font?: string;
+    /** Background tint applied while a part's `highlighted` signal is
+     *  true. Default: `tokens.tex.highlightColor`. */
+    highlightColor?: string;
+    /** "inline" (default) or "block" display style. Maps to Temml's
+     *  `displayMode` — bigger fractions, limits above/below, `\begin{…}`. */
+    display?: "inline" | "block";
+}
+/** Union of `PartMarker` names in an interpolation tuple (strings drop out). */
+export type NamesOf<V extends readonly TexInterp[]> = V extends readonly (infer U)[] ? U extends PartMarker<infer N> ? N : never : never;
+/** Render LaTeX → MathML via Temml (trust on, lenient errors). */
+export declare const renderToMathML: (source: string, opts?: {
+    displayMode?: boolean;
+}) => string;
+/** A LaTeX-rendered shape with addressable Parts. See `tex` (factory)
+ *  and `parts.ts` (Part / PartMarker). */
+export declare class TexShape<Names extends string = string> extends Shape {
+    readonly parts: PartList<Names>;
+    /** Width in local-frame user units (the rendered MathML bounding rect). */
+    readonly width: Cell<number>;
+    /** Height in local-frame user units. */
+    readonly height: Cell<number>;
+    constructor(strings: TemplateStringsArray | readonly string[], values: readonly TexInterp[], opts?: TexOpts);
+    /** Sugar: `eq.highlight("a")` → `eq.parts.a.highlighted.value = true`. */
+    highlight(name: Names, on?: boolean): void;
+}
+/** Render a LaTeX formula via Temml. Three forms:
+ *
+ *      tex`E = mc^2`                              // direct, default size
+ *      tex(28)`E = mc^2`                          // size-only shorthand
+ *      tex({ size: 28, display: "block" })`...`   // full options
+ *
+ *  Single-backslash LaTeX works directly (reads `strings.raw`). */
+export declare function tex<V extends readonly TexInterp[]>(strings: TemplateStringsArray, ...values: V): TexShape<NamesOf<V>>;
+export declare function tex(opts: TexOpts | number): <V extends readonly TexInterp[]>(strings: TemplateStringsArray, ...values: V) => TexShape<NamesOf<V>>;