@tmorrow/cre8-wc 2.0.7 → 2.0.8

package/a2ui/stream/pointer.ts

@@ -0,0 +1,147 @@
+/**
+ * Two addressing schemes, kept in one file because they are easy to confuse.
+ *
+ * **Spec paths** (`$.slots.footer[0].children[2]`) address nodes in the
+ * component tree. This grammar is not invented here — it is what the one-shot
+ * renderer already puts in `EmittedEvent.path`, which is why streaming can reuse
+ * it as node identity.
+ *
+ * **JSON Pointers** (`/user/name`) address values in the surface data model,
+ * per RFC 6901.
+ */
+
+export type PathSegment =
+  | { kind: 'children'; index: number }
+  | { kind: 'slot'; name: string; index: number };
+
+const SEGMENT_RE = /^\.(?:children\[(\d+)\]|slots\.([A-Za-z_][\w-]*)\[(\d+)\])/;
+
+/** Parse `$.slots.footer[0]` into segments. Throws on malformed input. */
+export function parsePath(path: string): PathSegment[] {
+  if (typeof path !== 'string' || path.length === 0) {
+    throw new Error(`path: must be a non-empty string, got ${JSON.stringify(path)}`);
+  }
+  if (path[0] !== '$') {
+    throw new Error(`path "${path}": must start with "$"`);
+  }
+  const segments: PathSegment[] = [];
+  let rest = path.slice(1);
+  while (rest.length > 0) {
+    const m = SEGMENT_RE.exec(rest);
+    if (!m) {
+      throw new Error(
+        `path "${path}": cannot parse at "${rest}" — expected ".children[N]" or ".slots.NAME[N]"`
+      );
+    }
+    if (m[1] !== undefined) {
+      segments.push({ kind: 'children', index: Number(m[1]) });
+    } else {
+      segments.push({ kind: 'slot', name: m[2], index: Number(m[3]) });
+    }
+    rest = rest.slice(m[0].length);
+  }
+  return segments;
+}
+
+export function formatPath(segments: PathSegment[]): string {
+  let out = '$';
+  for (const seg of segments) {
+    out += seg.kind === 'children' ? `.children[${seg.index}]` : `.slots.${seg.name}[${seg.index}]`;
+  }
+  return out;
+}
+
+/** `$.children[0]` + `{children,2}` → `$.children[0].children[2]`. */
+export function childPath(parentPath: string, slot: string | null, index: number): string {
+  return slot === null || slot === undefined
+    ? `${parentPath}.children[${index}]`
+    : `${parentPath}.slots.${slot}[${index}]`;
+}
+
+// ─── RFC 6901 JSON Pointer ──────────────────────────────────────────────────
+
+function unescapeToken(token: string): string {
+  return token.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+
+export function parsePointer(pointer: string): string[] {
+  if (pointer === '' || pointer === '/') return [];
+  if (pointer[0] !== '/') {
+    throw new Error(`pointer "${pointer}": must be empty or start with "/"`);
+  }
+  return pointer.slice(1).split('/').map(unescapeToken);
+}
+
+export function pointerGet(root: unknown, pointer: string): unknown {
+  let cur: unknown = root;
+  for (const token of parsePointer(pointer)) {
+    if (cur === null || cur === undefined) return undefined;
+    if (Array.isArray(cur)) {
+      const i = Number(token);
+      if (!Number.isInteger(i)) return undefined;
+      cur = cur[i];
+    } else if (typeof cur === 'object') {
+      cur = (cur as Record<string, unknown>)[token];
+    } else {
+      return undefined;
+    }
+  }
+  return cur;
+}
+
+/**
+ * Write `value` at `pointer`, creating intermediate containers as needed. An
+ * array is created when the next token looks like an index, an object otherwise.
+ * Mutates and returns `root` — except for the whole-document pointer `""`,
+ * where the caller must use the returned value.
+ */
+export function pointerSet(root: Record<string, unknown>, pointer: string, value: unknown): unknown {
+  const tokens = parsePointer(pointer);
+  if (tokens.length === 0) return value;
+
+  let cur: unknown = root;
+  for (let i = 0; i < tokens.length - 1; i++) {
+    const token = tokens[i];
+    const container = cur as Record<string, unknown> | unknown[];
+    const existing = Array.isArray(container)
+      ? (container as unknown[])[Number(token)]
+      : (container as Record<string, unknown>)[token];
+
+    if (existing === undefined || existing === null || typeof existing !== 'object') {
+      const next: unknown = /^\d+$/.test(tokens[i + 1]) ? [] : {};
+      if (Array.isArray(container)) (container as unknown[])[Number(token)] = next;
+      else (container as Record<string, unknown>)[token] = next;
+      cur = next;
+    } else {
+      cur = existing;
+    }
+  }
+
+  const last = tokens[tokens.length - 1];
+  if (Array.isArray(cur)) {
+    if (last === '-') (cur as unknown[]).push(value);
+    else (cur as unknown[])[Number(last)] = value;
+  } else {
+    (cur as Record<string, unknown>)[last] = value;
+  }
+  return root;
+}
+
+export function pointerRemove(root: Record<string, unknown>, pointer: string): void {
+  const tokens = parsePointer(pointer);
+  if (tokens.length === 0) {
+    for (const key of Object.keys(root)) delete root[key];
+    return;
+  }
+  let cur: unknown = root;
+  for (let i = 0; i < tokens.length - 1; i++) {
+    if (cur === null || typeof cur !== 'object') return;
+    cur = Array.isArray(cur)
+      ? (cur as unknown[])[Number(tokens[i])]
+      : (cur as Record<string, unknown>)[tokens[i]];
+  }
+  if (cur === null || typeof cur !== 'object') return;
+  const last = tokens[tokens.length - 1];
+  if (Array.isArray(cur)) (cur as unknown[]).splice(Number(last), 1);
+  else delete (cur as Record<string, unknown>)[last];
+}

package/a2ui/stream/renderer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * SurfaceRenderer — mirrors a SurfaceModel into live DOM, incrementally.
+ *
+ * The model is the source of truth; a `SurfaceChange` is only an invalidation
+ * hint, so the renderer always re-reads current state rather than trusting a
+ * diff it was handed. Elements are keyed by spec-node *object identity* (a
+ * WeakMap), not by path — paths shift when a sibling is inserted, and an element
+ * that keeps its identity keeps its internal state, its focus, and its
+ * animations.
+ */
+import type { ComponentSpec, EmittedEvent } from '../types.js';
+import type { ApplyResult, SurfaceModel } from './model.js';
+import type { SurfaceChange, SurfaceMessage } from './types.js';
+export interface SurfaceRendererOptions {
+    root: HTMLElement;
+    doc?: Document;
+    onEvent?: (evt: EmittedEvent) => void;
+}
+export declare class SurfaceRenderer {
+    readonly model: SurfaceModel;
+    private readonly rootEl;
+    private readonly doc;
+    private readonly onEvent?;
+    private readonly elements;
+    private readonly book;
+    constructor(model: SurfaceModel, options: SurfaceRendererOptions);
+    /** Apply a message to the model, then mirror the resulting changes to DOM. */
+    apply(message: SurfaceMessage): ApplyResult;
+    reconcile(changes: SurfaceChange[]): void;
+    /** Full (re)render of the surface root. */
+    mount(): void;
+    /** The element currently rendering the node at `path`, if it exists. */
+    elementAt(path: string): HTMLElement | undefined;
+    private elementFor;
+    private applyProps;
+    private applyEvents;
+    private makeListener;
+    private reconcileContainer;
+    /**
+     * Rebuild the container's DOM child list in place. `children` first, then each
+     * named slot in declaration order — DOM order inside a slotted host does not
+     * affect layout, but a stable order keeps the reconcile a no-op when nothing
+     * moved.
+     */
+    private reconcileChildren;
+    private nodeFor;
+    /** Re-resolve bound props across the whole tree after a data-model change. */
+    private refreshProps;
+}
+/** Locate a node in the tree by object identity, returning its current path. */
+export declare function findPath(root: ComponentSpec | null, target: ComponentSpec, path?: string): string | null;

package/a2ui/stream/renderer.js

@@ -0,0 +1,282 @@
+/**
+ * SurfaceRenderer — mirrors a SurfaceModel into live DOM, incrementally.
+ *
+ * The model is the source of truth; a `SurfaceChange` is only an invalidation
+ * hint, so the renderer always re-reads current state rather than trusting a
+ * diff it was handed. Elements are keyed by spec-node *object identity* (a
+ * WeakMap), not by path — paths shift when a sibling is inserted, and an element
+ * that keeps its identity keeps its internal state, its focus, and its
+ * animations.
+ */
+import { applyProp } from '../renderer.js';
+import { resolveNode } from './model.js';
+export class SurfaceRenderer {
+    model;
+    rootEl;
+    doc;
+    onEvent;
+    elements = new WeakMap();
+    book = new WeakMap();
+    constructor(model, options) {
+        this.model = model;
+        this.rootEl = options.root;
+        this.doc = options.doc ?? options.root.ownerDocument ?? document;
+        this.onEvent = options.onEvent;
+    }
+    /** Apply a message to the model, then mirror the resulting changes to DOM. */
+    apply(message) {
+        let result;
+        try {
+            result = this.model.apply(message);
+        }
+        catch (error) {
+            // A rolled-back patch restored the tree from a copy, so every node object
+            // this renderer knows about is now a stranger. Remount before rethrowing.
+            if (error?.rolledBack)
+                this.mount();
+            throw error;
+        }
+        this.reconcile(result.changes);
+        return result;
+    }
+    reconcile(changes) {
+        for (const change of changes) {
+            switch (change.kind) {
+                case 'root':
+                    this.mount();
+                    break;
+                case 'data':
+                    if (this.model.root)
+                        this.refreshProps(this.model.root);
+                    break;
+                case 'content':
+                case 'text':
+                    this.reconcileContainer(change.path);
+                    break;
+                case 'props': {
+                    const node = this.model.nodeAt(change.path);
+                    if (typeof node !== 'string')
+                        this.applyProps(node);
+                    break;
+                }
+                case 'events': {
+                    const node = this.model.nodeAt(change.path);
+                    if (typeof node !== 'string')
+                        this.applyEvents(node);
+                    break;
+                }
+            }
+        }
+    }
+    /** Full (re)render of the surface root. */
+    mount() {
+        const root = this.model.root;
+        if (!root) {
+            this.rootEl.replaceChildren();
+            return;
+        }
+        const el = this.elementFor(root);
+        this.reconcileChildren(root, el);
+        if (this.rootEl.firstChild !== el || this.rootEl.childNodes.length !== 1) {
+            this.rootEl.replaceChildren(el);
+        }
+    }
+    /** The element currently rendering the node at `path`, if it exists. */
+    elementAt(path) {
+        const node = this.model.nodeAt(path);
+        return typeof node === 'string' ? undefined : this.elements.get(node);
+    }
+    // ─── internals ────────────────────────────────────────────────────────────
+    elementFor(node) {
+        const existing = this.elements.get(node);
+        if (existing)
+            return existing;
+        const el = this.doc.createElement(node.component);
+        this.elements.set(node, el);
+        this.book.set(el, { props: new Set(), events: new Map(), texts: new Map() });
+        this.applyProps(node);
+        this.applyEvents(node);
+        this.reconcileChildren(node, el);
+        return el;
+    }
+    applyProps(node) {
+        const el = this.elements.get(node);
+        if (!el)
+            return;
+        const bk = this.book.get(el);
+        const defs = this.model.catalog.components.get(node.component)?.properties?.props?.properties ?? {};
+        const resolved = resolveNode(node, this.model.data);
+        const next = resolved.props ?? {};
+        for (const key of bk.props) {
+            if (!(key in next)) {
+                el.removeAttribute(key);
+                try {
+                    delete el[key];
+                }
+                catch {
+                    /* a component may define the property non-configurable; leaving it is fine */
+                }
+            }
+        }
+        bk.props = new Set(Object.keys(next));
+        for (const [key, value] of Object.entries(next)) {
+            applyProp(el, key, value, defs[key]);
+        }
+    }
+    applyEvents(node) {
+        const el = this.elements.get(node);
+        if (!el)
+            return;
+        const bk = this.book.get(el);
+        for (const [name, listener] of bk.events)
+            el.removeEventListener(name, listener);
+        bk.events.clear();
+        if (!node.events || !this.onEvent)
+            return;
+        for (const [eventName, binding] of Object.entries(node.events)) {
+            const listener = this.makeListener(node, eventName, binding);
+            el.addEventListener(eventName, listener);
+            bk.events.set(eventName, listener);
+        }
+    }
+    makeListener(node, eventName, binding) {
+        const handler = typeof binding === 'string' ? binding : binding.handler;
+        const stop = typeof binding === 'object' && binding.stopPropagation === true;
+        const prevent = typeof binding === 'object' && binding.preventDefault === true;
+        return (nativeEvent) => {
+            if (stop)
+                nativeEvent.stopPropagation();
+            if (prevent)
+                nativeEvent.preventDefault();
+            this.onEvent?.({
+                component: node.component,
+                // Resolved at fire time: an insert above this node moves its path.
+                path: findPath(this.model.root, node) ?? '$',
+                event: eventName,
+                handler,
+                detail: 'detail' in nativeEvent ? nativeEvent.detail : undefined,
+                nativeEvent,
+            });
+        };
+    }
+    reconcileContainer(path) {
+        const node = this.model.nodeAt(path);
+        if (typeof node === 'string')
+            return;
+        const el = this.elements.get(node);
+        if (!el)
+            return;
+        this.reconcileChildren(node, el);
+    }
+    /**
+     * Rebuild the container's DOM child list in place. `children` first, then each
+     * named slot in declaration order — DOM order inside a slotted host does not
+     * affect layout, but a stable order keeps the reconcile a no-op when nothing
+     * moved.
+     */
+    reconcileChildren(node, el) {
+        const bk = this.book.get(el);
+        const desired = [];
+        const liveTextKeys = new Set();
+        const push = (child, slot, index) => {
+            if (typeof child === 'string')
+                liveTextKeys.add(textKey(slot, index));
+            desired.push(this.nodeFor(child, slot, index, bk));
+        };
+        (node.children ?? []).forEach((child, i) => push(child, null, i));
+        if (node.slots) {
+            for (const [slotName, list] of Object.entries(node.slots)) {
+                list.forEach((child, i) => push(child, slotName, i));
+            }
+        }
+        for (const key of [...bk.texts.keys()]) {
+            if (!liveTextKeys.has(key))
+                bk.texts.delete(key);
+        }
+        for (let i = 0; i < desired.length; i++) {
+            const current = el.childNodes[i];
+            if (current === desired[i])
+                continue;
+            el.insertBefore(desired[i], current ?? null);
+        }
+        while (el.childNodes.length > desired.length) {
+            el.removeChild(el.childNodes[el.childNodes.length - 1]);
+        }
+    }
+    nodeFor(child, slot, index, bk) {
+        if (typeof child === 'string') {
+            const key = textKey(slot, index);
+            const bare = slot === null || slot === 'default';
+            const cached = bk.texts.get(key);
+            if (cached && (bare ? cached.nodeType === 3 : cached.nodeType === 1)) {
+                if (cached.textContent !== child)
+                    cached.textContent = child;
+                return cached;
+            }
+            let created;
+            if (bare) {
+                created = this.doc.createTextNode(child);
+            }
+            else {
+                created = this.doc.createElement('span');
+                created.setAttribute('slot', slot);
+                created.textContent = child;
+            }
+            bk.texts.set(key, created);
+            return created;
+        }
+        const el = this.elementFor(child);
+        if (slot !== null && slot !== 'default')
+            el.setAttribute('slot', slot);
+        else
+            el.removeAttribute('slot');
+        return el;
+    }
+    /** Re-resolve bound props across the whole tree after a data-model change. */
+    refreshProps(node) {
+        this.applyProps(node);
+        for (const child of node.children ?? []) {
+            if (typeof child !== 'string')
+                this.refreshProps(child);
+        }
+        if (node.slots) {
+            for (const list of Object.values(node.slots)) {
+                for (const child of list)
+                    if (typeof child !== 'string')
+                        this.refreshProps(child);
+            }
+        }
+    }
+}
+function textKey(slot, index) {
+    return `${slot ?? ''}#${index}`;
+}
+/** Locate a node in the tree by object identity, returning its current path. */
+export function findPath(root, target, path = '$') {
+    if (!root)
+        return null;
+    if (root === target)
+        return path;
+    const children = root.children ?? [];
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        if (typeof child === 'string')
+            continue;
+        const found = findPath(child, target, `${path}.children[${i}]`);
+        if (found)
+            return found;
+    }
+    if (root.slots) {
+        for (const [slotName, list] of Object.entries(root.slots)) {
+            for (let i = 0; i < list.length; i++) {
+                const child = list[i];
+                if (typeof child === 'string')
+                    continue;
+                const found = findPath(child, target, `${path}.slots.${slotName}[${i}]`);
+                if (found)
+                    return found;
+            }
+        }
+    }
+    return null;
+}