tachyon-dom 0.1.0

package/dist/runtime/html.d.ts

@@ -0,0 +1,8 @@
+declare const clientHtmlBrand: unique symbol;
+export type ClientHtml = {
+    readonly [clientHtmlBrand]: true;
+    toString(): string;
+};
+export declare const rawHtml: (value: string) => ClientHtml;
+export declare const isClientHtml: (value: unknown) => value is ClientHtml;
+export {};

package/dist/runtime/html.js

@@ -0,0 +1,6 @@
+const clientHtmlBrand = Symbol("tachyon.clientHtml");
+export const rawHtml = (value) => ({
+    [clientHtmlBrand]: true,
+    toString: () => value,
+});
+export const isClientHtml = (value) => Boolean(value && typeof value === "object" && value[clientHtmlBrand] === true);

package/dist/runtime/hydrate.d.ts

@@ -0,0 +1,68 @@
+import { type Result } from "../result.js";
+export type HydrationBoundaryError = {
+    message: string;
+};
+export type LocatedHydrationBoundary = {
+    id: string;
+    start: Comment;
+    end: Comment;
+    element: Element;
+};
+export type HydrationBoundaryDiagnostic = {
+    id: string;
+    type: "missing-start" | "missing-end" | "duplicate" | "missing-element";
+    message: string;
+};
+export type HydrationDiagnosticsHot = {
+    send: (event: string, payload: {
+        err: {
+            message: string;
+            stack?: string;
+        };
+    }) => void;
+};
+export type HydrationBoundaryHandle = {
+    hydrate: () => void;
+    hydrated: () => boolean;
+    element: () => Element;
+    dispose: () => void;
+};
+export type HydrationStrategy = "load" | "idle" | "visible" | "media" | "interaction";
+export type HydrationScheduleOptions = {
+    strategy: HydrationStrategy;
+    media?: string;
+    interaction?: keyof HTMLElementEventMap | string;
+    rootMargin?: string;
+    matchMedia?: (query: string) => MediaQueryList;
+};
+export type CompiledHydrationBoundary = {
+    id: string;
+    idKind?: "expression" | "static";
+    strategy?: HydrationStrategy;
+    media?: string;
+    interaction?: keyof HTMLElementEventMap | string;
+    rootMargin?: string;
+};
+export type ScheduleHydrationBoundariesOptions = {
+    resolveId?: (boundary: CompiledHydrationBoundary) => string | undefined;
+    onError?: (error: HydrationBoundaryError, boundary: CompiledHydrationBoundary) => void;
+    matchMedia?: (query: string) => MediaQueryList;
+};
+type HydrationCleanup = void | (() => void);
+type HydrationCommentIndex = {
+    starts: Map<string, Comment[]>;
+    ends: Map<string, Comment[]>;
+};
+export declare const locateHydrationBoundary: (root: ParentNode, id: string, index?: HydrationCommentIndex) => Result<LocatedHydrationBoundary, HydrationBoundaryError>;
+export declare const diagnoseHydrationBoundaries: (root: ParentNode, expectedIds: readonly string[]) => HydrationBoundaryDiagnostic[];
+export declare const reportHydrationDiagnostics: (root: ParentNode, expectedIds: readonly string[], options?: {
+    hot?: HydrationDiagnosticsHot;
+}) => HydrationBoundaryDiagnostic[];
+export declare const createHydrationBoundary: (root: ParentNode, id: string, bind: (element: Element) => HydrationCleanup, index?: HydrationCommentIndex) => Result<HydrationBoundaryHandle, HydrationBoundaryError>;
+export declare const serializeHydrationState: (id: string, state: unknown, options?: {
+    nonce?: string;
+}) => string;
+export declare const readHydrationState: <T>(root: ParentNode, id: string) => Result<T, HydrationBoundaryError>;
+export declare const scheduleHydration: (handle: HydrationBoundaryHandle, options?: HydrationScheduleOptions) => (() => void);
+export declare const scheduleHydrationBoundaries: (root: ParentNode, boundaries: readonly CompiledHydrationBoundary[], bind: (element: Element, boundary: CompiledHydrationBoundary) => HydrationCleanup, options?: ScheduleHydrationBoundariesOptions) => (() => void);
+export {};

package/dist/runtime/hydrate.js

@@ -0,0 +1,205 @@
+import { err, ok } from "../result.js";
+const escapeScriptJson = (value) => value.replaceAll("<", "\\u003c").replaceAll(">", "\\u003e");
+const escapeAttribute = (value) => value.replaceAll("&", "&amp;").replaceAll(`"`, "&quot;").replaceAll("<", "&lt;");
+const commentsIn = (root) => {
+    const ownerDocument = root instanceof Document ? root : (root.ownerDocument ?? document);
+    const walker = ownerDocument.createTreeWalker(root, NodeFilter.SHOW_COMMENT);
+    const comments = [];
+    let current = walker.nextNode();
+    while (current) {
+        if (current instanceof Comment) {
+            comments.push(current);
+        }
+        current = walker.nextNode();
+    }
+    return comments;
+};
+const hydrationCommentIndex = (root) => {
+    const starts = new Map();
+    const ends = new Map();
+    for (const comment of commentsIn(root)) {
+        if (!comment.data.startsWith("tachyon-hydrate:")) {
+            continue;
+        }
+        if (comment.data.endsWith(":start")) {
+            const id = comment.data.slice("tachyon-hydrate:".length, -":start".length);
+            starts.set(id, [...(starts.get(id) ?? []), comment]);
+        }
+        else if (comment.data.endsWith(":end")) {
+            const id = comment.data.slice("tachyon-hydrate:".length, -":end".length);
+            ends.set(id, [...(ends.get(id) ?? []), comment]);
+        }
+    }
+    return { starts, ends };
+};
+const nextElementBetween = (start, end) => {
+    let current = start.nextSibling;
+    while (current && current !== end) {
+        if (current instanceof Element) {
+            return current;
+        }
+        current = current.nextSibling;
+    }
+    return undefined;
+};
+export const locateHydrationBoundary = (root, id, index = hydrationCommentIndex(root)) => {
+    const start = index.starts.get(id)?.[0];
+    const end = index.ends.get(id)?.[0];
+    if (!start || !end) {
+        return err({ message: `Missing hydrate boundary markers for ${id}.` });
+    }
+    const element = nextElementBetween(start, end);
+    if (!element) {
+        return err({ message: `Missing hydrate boundary element for ${id}.` });
+    }
+    return ok({ id, start, end, element });
+};
+export const diagnoseHydrationBoundaries = (root, expectedIds) => {
+    const index = hydrationCommentIndex(root);
+    const diagnostics = [];
+    for (const id of expectedIds) {
+        const starts = index.starts.get(id) ?? [];
+        const ends = index.ends.get(id) ?? [];
+        if (starts.length === 0) {
+            diagnostics.push({ id, type: "missing-start", message: `Missing hydrate boundary start marker for ${id}.` });
+        }
+        if (ends.length === 0) {
+            diagnostics.push({ id, type: "missing-end", message: `Missing hydrate boundary end marker for ${id}.` });
+        }
+        if (starts.length > 1 || ends.length > 1) {
+            diagnostics.push({ id, type: "duplicate", message: `Duplicate hydrate boundary markers for ${id}.` });
+        }
+        if (starts.length === 1 && ends.length === 1 && !nextElementBetween(starts[0], ends[0])) {
+            diagnostics.push({ id, type: "missing-element", message: `Missing hydrate boundary element for ${id}.` });
+        }
+    }
+    return diagnostics;
+};
+export const reportHydrationDiagnostics = (root, expectedIds, options = {}) => {
+    const diagnostics = diagnoseHydrationBoundaries(root, expectedIds);
+    for (const diagnostic of diagnostics) {
+        options.hot?.send("vite:error", {
+            err: {
+                message: diagnostic.message,
+                stack: diagnostic.message,
+            },
+        });
+    }
+    return diagnostics;
+};
+export const createHydrationBoundary = (root, id, bind, index) => {
+    const located = locateHydrationBoundary(root, id, index);
+    if (!located.ok) {
+        return err(located.error);
+    }
+    let cleanup;
+    let isHydrated = false;
+    const hydrate = () => {
+        if (isHydrated) {
+            return;
+        }
+        cleanup = bind(located.value.element);
+        isHydrated = true;
+    };
+    return ok({
+        hydrate,
+        hydrated: () => isHydrated,
+        element: () => located.value.element,
+        dispose: () => {
+            if (typeof cleanup === "function") {
+                cleanup();
+            }
+            isHydrated = false;
+        },
+    });
+};
+export const serializeHydrationState = (id, state, options = {}) => {
+    const nonce = options.nonce ? ` nonce="${escapeAttribute(options.nonce)}"` : "";
+    return `<script type="application/json" data-tachyon-state="${escapeAttribute(id)}"${nonce}>${escapeScriptJson(JSON.stringify(state) ?? "null")}</script>`;
+};
+export const readHydrationState = (root, id) => {
+    const script = Array.from(root.querySelectorAll(`script[type="application/json"][data-tachyon-state]`)).find((candidate) => candidate.getAttribute("data-tachyon-state") === id);
+    if (!script) {
+        return err({ message: `Missing hydration state for ${id}.` });
+    }
+    try {
+        return ok(JSON.parse(script.textContent ?? "null"));
+    }
+    catch {
+        return err({ message: `Invalid hydration state for ${id}.` });
+    }
+};
+export const scheduleHydration = (handle, options = { strategy: "load" }) => {
+    if (options.strategy === "load") {
+        handle.hydrate();
+        return () => undefined;
+    }
+    if (options.strategy === "idle") {
+        const requestIdle = globalThis.requestIdleCallback ??
+            ((callback) => setTimeout(() => callback({ didTimeout: false, timeRemaining: () => 0 }), 0));
+        const cancelIdle = globalThis.cancelIdleCallback ?? clearTimeout;
+        const id = requestIdle(() => handle.hydrate());
+        return () => cancelIdle(id);
+    }
+    if (options.strategy === "media") {
+        const query = options.media;
+        if (!query) {
+            return () => undefined;
+        }
+        const matcher = options.matchMedia ?? globalThis.matchMedia;
+        const media = matcher(query);
+        const listener = () => {
+            if (media.matches) {
+                handle.hydrate();
+            }
+        };
+        media.addEventListener("change", listener);
+        listener();
+        return () => media.removeEventListener("change", listener);
+    }
+    if (options.strategy === "visible") {
+        const observer = new IntersectionObserver((entries) => {
+            if (entries.some((entry) => entry.isIntersecting)) {
+                handle.hydrate();
+                observer.disconnect();
+            }
+        }, options.rootMargin === undefined ? {} : { rootMargin: options.rootMargin });
+        observer.observe(handle.element());
+        return () => observer.disconnect();
+    }
+    const eventName = options.interaction ?? "click";
+    const listener = () => {
+        handle.hydrate();
+        document.removeEventListener(eventName, listener, true);
+    };
+    document.addEventListener(eventName, listener, true);
+    return () => document.removeEventListener(eventName, listener, true);
+};
+export const scheduleHydrationBoundaries = (root, boundaries, bind, options = {}) => {
+    const cleanups = [];
+    const index = hydrationCommentIndex(root);
+    for (const boundary of boundaries) {
+        const id = boundary.idKind === "expression" ? options.resolveId?.(boundary) : boundary.id;
+        if (!id) {
+            continue;
+        }
+        const handle = createHydrationBoundary(root, id, (element) => bind(element, boundary), index);
+        if (!handle.ok) {
+            options.onError?.(handle.error, boundary);
+            continue;
+        }
+        cleanups.push(scheduleHydration(handle.value, {
+            strategy: boundary.strategy ?? "load",
+            ...(boundary.media ? { media: boundary.media } : {}),
+            ...(boundary.interaction ? { interaction: boundary.interaction } : {}),
+            ...(boundary.rootMargin ? { rootMargin: boundary.rootMargin } : {}),
+            ...(options.matchMedia ? { matchMedia: options.matchMedia } : {}),
+        }));
+        cleanups.push(() => handle.value.dispose());
+    }
+    return () => {
+        for (const cleanup of cleanups.splice(0).reverse()) {
+            cleanup();
+        }
+    };
+};

package/dist/runtime/keyed-rows.d.ts

@@ -0,0 +1,61 @@
+/**
+ * keyed-rows: a high-performance keyed row list rendered directly into a `<tbody>`.
+ *
+ * The live DOM is the single source of truth. Unlike a virtual-DOM or shadow-array
+ * renderer, this primitive keeps no parallel `items[]` / `rowNodes[]` arrays, so:
+ *
+ * - memory stays close to the raw element cost (no bookkeeping arrays, no row pool),
+ * - `removeAt` / `swap` / `select` are O(1) DOM operations instead of array shifts,
+ * - `clear()` simply drops the subtree so it can be garbage collected immediately.
+ *
+ * Bulk creation binds a reusable multi-row chunk once and clones it, keeping the
+ * number of `cloneNode()` / `appendChild()` boundary crossings small and roughly
+ * constant regardless of row count. The body is detached during a full rebuild so
+ * the browser performs a single layout pass.
+ *
+ * This module intentionally has no imports: it is the hot path, and keeping it
+ * dependency-free keeps both its parse cost and its dev-server module graph minimal.
+ */
+export type KeyedRowsOptions<T> = {
+    /** Table body the rows live in. The DOM beneath it is the source of truth. */
+    tbody: HTMLTableSectionElement;
+    /** Single-row markup, e.g. `"<tr><td></td>...</tr>"`. Parsed once into a template. */
+    row: string;
+    /** Write an item's fields into a row before it is cloned into the table. */
+    bind: (row: HTMLTableRowElement, item: T, index: number) => void;
+    /** Class toggled on the selected row. Defaults to `"selected"`. */
+    selectedClass?: string;
+    /** Target number of DOM insertions per bulk build. Defaults to `50`. */
+    chunks?: number;
+};
+export type KeyedRows<T> = {
+    /** Replace every row from an array of items. */
+    replace: (items: readonly T[]) => void;
+    /** Append rows from an array of items. */
+    append: (items: readonly T[]) => void;
+    /** Replace every row, producing each item lazily (no intermediate array). */
+    replaceEach: (count: number, make: (index: number) => T) => void;
+    /** Append rows, producing each item lazily (no intermediate array). */
+    appendEach: (count: number, make: (index: number) => T) => void;
+    /** Run `patch` against every `stride`-th live row. */
+    update: (stride: number, patch: (row: HTMLTableRowElement, index: number) => void) => void;
+    /** Remove the row at `index`. */
+    removeAt: (index: number) => void;
+    /** Remove a specific row element. */
+    removeRow: (row: HTMLTableRowElement) => void;
+    /** Swap the rows at `a` and `b`, preserving element identity. */
+    swap: (a: number, b: number) => void;
+    /** Remove every row. */
+    clear: () => void;
+    /** Select the row at `index`. */
+    selectAt: (index: number) => void;
+    /** Select a specific row element, or pass `null` to clear the selection. */
+    selectRow: (row: HTMLTableRowElement | null) => void;
+    /** Index of the selected row, or `-1`. Recomputed from the live DOM. */
+    selectedIndex: () => number;
+    /** Number of rows currently in the body. */
+    length: () => number;
+    /** Row element at `index`, if any. */
+    rowAt: (index: number) => HTMLTableRowElement | undefined;
+};
+export declare const createKeyedRows: <T>(options: KeyedRowsOptions<T>) => KeyedRows<T>;

package/dist/runtime/keyed-rows.js

@@ -0,0 +1,192 @@
+/**
+ * keyed-rows: a high-performance keyed row list rendered directly into a `<tbody>`.
+ *
+ * The live DOM is the single source of truth. Unlike a virtual-DOM or shadow-array
+ * renderer, this primitive keeps no parallel `items[]` / `rowNodes[]` arrays, so:
+ *
+ * - memory stays close to the raw element cost (no bookkeeping arrays, no row pool),
+ * - `removeAt` / `swap` / `select` are O(1) DOM operations instead of array shifts,
+ * - `clear()` simply drops the subtree so it can be garbage collected immediately.
+ *
+ * Bulk creation binds a reusable multi-row chunk once and clones it, keeping the
+ * number of `cloneNode()` / `appendChild()` boundary crossings small and roughly
+ * constant regardless of row count. The body is detached during a full rebuild so
+ * the browser performs a single layout pass.
+ *
+ * This module intentionally has no imports: it is the hot path, and keeping it
+ * dependency-free keeps both its parse cost and its dev-server module graph minimal.
+ */
+const defaultChunks = 50;
+const positiveInteger = (name, value) => {
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+        throw new TypeError(`keyed-rows: \`${name}\` must be a positive finite integer.`);
+    }
+};
+export const createKeyedRows = (options) => {
+    const tbody = options.tbody;
+    const bind = options.bind;
+    const selectedClass = options.selectedClass ?? "selected";
+    const targetChunks = options.chunks ?? defaultChunks;
+    positiveInteger("chunks", targetChunks);
+    const single = document.createElement("template");
+    single.innerHTML = options.row;
+    const baseRow = single.content.firstElementChild;
+    if (!(baseRow instanceof HTMLTableRowElement)) {
+        throw new TypeError("keyed-rows: `row` markup must have a single <tr> root.");
+    }
+    // Reusable chunk of template rows; rebuilt only when the per-chunk size changes.
+    const chunk = document.createDocumentFragment();
+    let chunkRows = 0;
+    let selectedRow;
+    const ensureChunk = (rowsPerChunk) => {
+        if (chunkRows === rowsPerChunk) {
+            return;
+        }
+        chunk.replaceChildren();
+        for (let i = 0; i < rowsPerChunk; i++) {
+            chunk.appendChild(baseRow.cloneNode(true));
+        }
+        chunkRows = rowsPerChunk;
+    };
+    const build = (count, make, start) => {
+        if (count <= 0) {
+            return;
+        }
+        const perChunk = count < targetChunks ? count : Math.ceil(count / targetChunks);
+        ensureChunk(perChunk);
+        const templateRows = chunk.children;
+        let done = 0;
+        while (done < count) {
+            const size = Math.min(perChunk, count - done);
+            for (let local = 0; local < size; local++) {
+                const index = start + done + local;
+                bind(templateRows[local], make(index), index);
+            }
+            if (size === perChunk) {
+                tbody.appendChild(chunk.cloneNode(true));
+            }
+            else {
+                const partial = document.createDocumentFragment();
+                for (let local = 0; local < size; local++) {
+                    partial.appendChild(templateRows[local].cloneNode(true));
+                }
+                tbody.appendChild(partial);
+            }
+            done += size;
+        }
+    };
+    // Detach the body during a full rebuild so layout/paint happens once on reattach.
+    const rebuild = (count, make) => {
+        const parent = tbody.parentNode;
+        const nextSibling = tbody.nextSibling;
+        if (parent) {
+            parent.removeChild(tbody);
+        }
+        tbody.textContent = "";
+        selectedRow = undefined;
+        build(count, make, 0);
+        if (parent) {
+            parent.insertBefore(tbody, nextSibling);
+        }
+    };
+    const replace = (items) => rebuild(items.length, (index) => items[index]);
+    const replaceEach = (count, make) => {
+        positiveInteger("count", count);
+        rebuild(count, make);
+    };
+    const append = (items) => {
+        const start = tbody.childElementCount;
+        build(items.length, (index) => items[index - start], start);
+    };
+    const appendEach = (count, make) => {
+        positiveInteger("count", count);
+        build(count, make, tbody.childElementCount);
+    };
+    const update = (stride, patch) => {
+        positiveInteger("stride", stride);
+        const rows = tbody.children;
+        const total = rows.length;
+        for (let index = 0; index < total; index += stride) {
+            patch(rows[index], index);
+        }
+    };
+    const removeRow = (row) => {
+        if (row === selectedRow) {
+            selectedRow = undefined;
+        }
+        row.remove();
+    };
+    const removeAt = (index) => {
+        const row = tbody.children[index];
+        if (row) {
+            removeRow(row);
+        }
+    };
+    const swap = (a, b) => {
+        if (a === b) {
+            return;
+        }
+        const rows = tbody.children;
+        const rowA = rows[a];
+        const rowB = rows[b];
+        if (!rowA || !rowB) {
+            return;
+        }
+        const activeElement = tbody.ownerDocument.activeElement;
+        const restoreFocus = activeElement &&
+            activeElement !== tbody.ownerDocument.body &&
+            (rowA.contains(activeElement) || rowB.contains(activeElement)) &&
+            "focus" in activeElement
+            ? activeElement
+            : undefined;
+        const nextA = rowA.nextSibling;
+        if (nextA === rowB) {
+            tbody.insertBefore(rowB, rowA);
+            restoreFocus?.focus({ preventScroll: true });
+            return;
+        }
+        const nextB = rowB.nextSibling;
+        tbody.insertBefore(rowB, nextA);
+        tbody.insertBefore(rowA, nextB);
+        restoreFocus?.focus({ preventScroll: true });
+    };
+    const clear = () => {
+        selectedRow = undefined;
+        tbody.textContent = "";
+    };
+    const selectRow = (row) => {
+        if (selectedRow === row) {
+            return;
+        }
+        if (selectedRow) {
+            selectedRow.classList.remove(selectedClass);
+        }
+        selectedRow = row ?? undefined;
+        if (selectedRow) {
+            selectedRow.classList.add(selectedClass);
+        }
+    };
+    const selectAt = (index) => {
+        const row = tbody.children[index];
+        if (row) {
+            selectRow(row);
+        }
+    };
+    const selectedIndex = () => selectedRow && selectedRow.parentNode === tbody ? selectedRow.sectionRowIndex : -1;
+    return {
+        replace,
+        append,
+        replaceEach,
+        appendEach,
+        update,
+        removeAt,
+        removeRow,
+        swap,
+        clear,
+        selectAt,
+        selectRow,
+        selectedIndex,
+        length: () => tbody.childElementCount,
+        rowAt: (index) => tbody.children[index],
+    };
+};

package/dist/runtime/list.d.ts

@@ -0,0 +1,84 @@
+type ExpressionReader = (scope: Record<string, unknown>) => unknown;
+type ExpressionWriter = (scope: Record<string, unknown>, value: unknown) => void;
+type TextBinding = {
+    kind: "text";
+    path: number[];
+    expression: string;
+    read?: ExpressionReader;
+};
+type ClassBinding = {
+    kind: "class";
+    path: number[];
+    className: string;
+    expression: string;
+    read?: ExpressionReader;
+};
+type EventBinding = {
+    kind: "event";
+    path: number[];
+    eventName: string;
+    handler: string;
+    read?: ExpressionReader;
+};
+type AttributeBinding = {
+    kind: "attr";
+    path: number[];
+    name: string;
+    expression: string;
+    read?: ExpressionReader;
+};
+type StyleBinding = {
+    kind: "style";
+    path: number[];
+    name: string;
+    expression: string;
+    read?: ExpressionReader;
+};
+type RefBinding = {
+    kind: "ref";
+    path: number[];
+    expression: string;
+};
+type ModelBinding = {
+    kind: "model";
+    path: number[];
+    property: "value" | "checked";
+    expression: string;
+    read?: ExpressionReader;
+    write?: ExpressionWriter;
+};
+type NestedListBinding = {
+    kind: "list";
+    signature?: string;
+    path: number[];
+    each: string;
+    read?: ExpressionReader;
+    key: string;
+    keyRead?: ExpressionReader;
+    keyReadItem?: (item: unknown) => unknown;
+    itemName: string;
+    templateHtml: string;
+    bindings: Binding[];
+};
+type NestedConditionalBinding = {
+    kind: "if";
+    signature?: string;
+    path: number[];
+    test: string;
+    read?: ExpressionReader;
+    templateHtml: string;
+    bindings: Binding[];
+};
+type Binding = TextBinding | ClassBinding | EventBinding | AttributeBinding | StyleBinding | RefBinding | ModelBinding | NestedListBinding | NestedConditionalBinding;
+type KeyedListOptions = {
+    signature?: string;
+    key: string;
+    keyRead?: ExpressionReader;
+    keyReadItem?: (item: unknown) => unknown;
+    itemName: string;
+    scope?: Record<string, unknown>;
+    templateHtml: string;
+    bindings: Binding[];
+};
+export declare const mountKeyedList: (root: Element, path: readonly number[], items: readonly unknown[] | undefined, options: KeyedListOptions) => void;
+export {};