@abide/abide 0.28.0

package/src/lib/ui/dom/appendText.ts

@@ -0,0 +1,114 @@
+import { rawHtmlString } from '../../shared/html.ts'
+import { snippetPayload } from '../../shared/snippet.ts'
+import { effect } from '../effect.ts'
+import { claimChild } from '../runtime/claimChild.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+import { appendSnippet } from './appendSnippet.ts'
+
+const CLOSE = '/abide:html'
+
+/*
+A reactive `{expr}` interpolation under `parent`. A plain value is an escaped text
+node: created and appended (create), or the server-rendered text node claimed
+(hydrate) and bound. Adjacent SSR text merges into one node, so on hydrate the
+claimed node is split at the current value's length — deterministic, because
+`read()` returns the same value the server rendered.
+
+A value branded by `html\`…\`` (see abide/shared/html) inserts raw markup instead:
+its parsed nodes go between an anchor (create), or the server-rendered nodes
+between `<!--abide:html-->`/`<!--/abide:html-->` markers are adopted (hydrate), and
+a change re-parses and swaps. A binding is text or raw for its lifetime (decided by
+its first value), so plain text — the common case — stays a cheap single node.
+*/
+// @readme plumbing
+export function appendText(parent: Node, read: () => unknown, splitAlways = false): void {
+    /* A snippet call (`{row(args)}`) mounts its builder; a `html\`\`` value inserts
+       raw markup; everything else is escaped text — decided by the first value. */
+    if (typeof snippetPayload(read()) === 'function') {
+        appendSnippet(parent, read)
+        return
+    }
+    if (rawHtmlString(read()) !== undefined) {
+        appendRawHtml(parent, read)
+        return
+    }
+    const hydration = RENDER.hydration
+    if (hydration !== undefined) {
+        const node = claimChild(hydration, parent) as unknown as Text
+        const value = String(read())
+        /* Peel this binding's text off the merged SSR node. A non-final binding in a
+           run (`splitAlways`) splits even when it consumes the whole node, leaving an
+           empty node for the next binding — otherwise an interpolation that renders to
+           empty string (or whose followers do) has no node and the next claim grabs the
+           wrong sibling. The final binding keeps `<` so it doesn't leave a stray node a
+           following element would claim. */
+        if (
+            node !== null &&
+            (splitAlways ? value.length <= node.data.length : value.length < node.data.length)
+        ) {
+            node.splitText(value.length)
+        }
+        hydration.next.set(parent, node === null ? null : node.nextSibling)
+        effect(() => {
+            node.data = String(read())
+        })
+        return
+    }
+    const node = document.createTextNode('')
+    parent.appendChild(node)
+    effect(() => {
+        node.data = String(read())
+    })
+}
+
+/* Raw-markup interpolation: parse the branded string into nodes behind an anchor,
+   re-parsing on change; on hydrate adopt the server markup between its markers. */
+function appendRawHtml(parent: Node, read: () => unknown): void {
+    const hydration = RENDER.hydration
+    const markup = (): string => rawHtmlString(read()) ?? ''
+    const anchor = document.createTextNode('')
+    let nodes: Node[] = []
+
+    const set = (value: string): void => {
+        for (const node of nodes) {
+            parent.removeChild(node)
+        }
+        const holder = document.createElement('div')
+        holder.innerHTML = value
+        nodes = [...holder.childNodes]
+        for (const node of nodes) {
+            parent.insertBefore(node, anchor)
+        }
+    }
+
+    if (hydration !== undefined) {
+        const open = claimChild(hydration, parent)
+        let node: Node | null = open === null ? null : open.nextSibling
+        while (node !== null && !isComment(node, CLOSE)) {
+            nodes.push(node)
+            node = node.nextSibling
+        }
+        hydration.next.set(parent, node === null ? null : node.nextSibling)
+        parent.insertBefore(anchor, node)
+        let first = true
+        effect(() => {
+            const value = markup()
+            if (first) {
+                first = false // adopt the server markup as-is
+                return
+            }
+            set(value)
+        })
+        return
+    }
+
+    parent.appendChild(anchor)
+    effect(() => {
+        set(markup())
+    })
+}
+
+/* A comment node carrying exactly `data`. */
+function isComment(node: Node, data: string): boolean {
+    return (node as { data?: string }).data === data && node.childNodes.length === 0
+}

package/src/lib/ui/dom/applyResolved.ts

@@ -0,0 +1,72 @@
+import { RESUME } from '../runtime/RESUME.ts'
+
+/*
+Client consumer of an SSR stream fragment. Parses a streamed
+`<abide-resolve data-id="ID" data-resume="…">…</abide-resolve>` frame, registers
+its serialized value in the resume manifest (for later hydration), finds the
+matching `<!--abide:await:ID-->…<!--/abide:await:ID-->` boundary in `root`, removes
+the pending nodes between the markers, and inserts the resolved content in their
+place. The pending shell painted instantly; this swaps in each value as it
+arrives — completing the out-of-order streaming loop on the client.
+*/
+// @readme plumbing
+export function applyResolved(root: Element, frame: string): void {
+    const holder = document.createElement('div')
+    holder.innerHTML = frame
+    const resolved = holder.firstChild as Element | null
+    if (resolved === null || resolved.getAttribute === undefined) {
+        return
+    }
+    const id = resolved.getAttribute('data-id')
+    if (id === null) {
+        return
+    }
+    /* Record the resolved value so a later hydrate adopts this branch (no re-fetch). */
+    const resume = resolved.getAttribute('data-resume')
+    if (resume !== null) {
+        try {
+            RESUME[Number(id)] = JSON.parse(resume)
+        } catch {
+            /* malformed payload — leave unregistered, hydration re-runs the promise */
+        }
+    }
+    const open = `abide:await:${id}`
+    const close = `/abide:await:${id}`
+    const boundary = findBoundary(root, open)
+    if (boundary === undefined) {
+        return
+    }
+    const { parent, start } = boundary
+    /* Remove the pending nodes between the markers (exclusive of the markers). */
+    let node = start.nextSibling
+    while (node !== null && !isComment(node, close)) {
+        const next = node.nextSibling
+        parent.removeChild(node)
+        node = next
+    }
+    /* Insert resolved content after the open marker. */
+    let anchor = start.nextSibling
+    for (const child of [...resolved.childNodes]) {
+        parent.insertBefore(child, anchor)
+        anchor = child.nextSibling
+    }
+}
+
+/* A comment node carrying exactly `data`. */
+function isComment(node: Node, data: string): boolean {
+    return (node as { data?: string }).data === data && node.childNodes.length === 0
+}
+
+/* Depth-first search for the parent + open-marker comment of a boundary. */
+function findBoundary(node: Node, open: string): { parent: Node; start: Node } | undefined {
+    for (const child of [...node.childNodes]) {
+        if (isComment(child, open)) {
+            return { parent: node, start: child }
+        }
+        const nested = findBoundary(child, open)
+        if (nested !== undefined) {
+            return nested
+        }
+    }
+    return undefined
+}

package/src/lib/ui/dom/attach.ts

@@ -0,0 +1,20 @@
+import { OWNER } from '../runtime/OWNER.ts'
+import { toTeardown } from '../runtime/toTeardown.ts'
+import type { EffectResult } from '../runtime/types/EffectResult.ts'
+
+/*
+Runs an attachment against an element at build time and registers its optional
+teardown with the current ownership scope, so it detaches when the component
+disposes. The dual of `on`: where `on` owns a listener, `attach` owns whatever
+the attachment sets up. Node-lifetime, not reactive — for param reactivity put an
+`effect` inside the attachment and return its dispose. The attachment may be
+async; its teardown then runs once the promise settles. Runtime target for an
+`attach={…}` binding.
+*/
+// @readme plumbing
+export function attach(element: Element, attachment: (node: Element) => EffectResult): void {
+    const teardown = toTeardown(attachment(element))
+    if (teardown !== undefined && OWNER.current !== undefined) {
+        OWNER.current.push(teardown)
+    }
+}

package/src/lib/ui/dom/attr.ts

@@ -0,0 +1,19 @@
+import { effect } from '../effect.ts'
+
+/*
+Binds an element attribute to `read()`. A boolean true sets the bare attribute,
+and false/null/undefined removes it (the standard present/absent semantics);
+anything else is stringified. One effect per bound attribute, so only the
+changed attribute touches the DOM.
+*/
+// @readme plumbing
+export function attr(element: Element, name: string, read: () => unknown): void {
+    effect(() => {
+        const value = read()
+        if (value === false || value === null || value === undefined) {
+            element.removeAttribute(name)
+        } else {
+            element.setAttribute(name, value === true ? '' : String(value))
+        }
+    })
+}

package/src/lib/ui/dom/awaitBlock.ts

@@ -0,0 +1,224 @@
+import { effect } from '../effect.ts'
+import { claimChild } from '../runtime/claimChild.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+import { RESUME } from '../runtime/RESUME.ts'
+import { scope } from '../runtime/scope.ts'
+
+/*
+Async binding — the runtime for `<template await>`. Renders the pending branch,
+then swaps to the resolved branch (with the value) or the error branch on settle.
+Each branch is a RANGE of element roots, tracked as a node array so a multi-root
+branch inserts/removes as a unit.
+
+The read runs inside a abide-ui `effect`, so it's reactive: `abide/shared/cache`'s
+store subscribes the key it reads to this effect (createSubscriber is abide-ui-
+native), so `cache.invalidate()` of that key re-runs the block — pending, then the
+fresh value swaps in. A read that touches no reactive source runs exactly once.
+
+Hydration adopts in place, by precedence:
+  1. a streamed resume value (`RESUME[id]`) → adopt the resolved branch the stream
+     swapped in, no read (the promise never runs — a plain producer resume);
+  2. a warm-sync read (a non-thenable result) → adopt the SSR branch with it;
+  3. otherwise (genuinely pending) → discard the SSR boundary and run fresh.
+After the first (adopting) run, later invalidations swap content before an anchor
+parked just before the close marker.
+*/
+// @readme plumbing
+export function awaitBlock(
+    parent: Node,
+    id: number,
+    promiseThunk: () => unknown,
+    renderPending: ((parent: Node) => Node[]) | undefined,
+    renderThen: (parent: Node, value: unknown) => Node[],
+    /* Absent when the block has no catch branch — a rejection then surfaces (re-throws
+       to the unhandled-rejection path) instead of rendering an empty branch. */
+    renderCatch: ((parent: Node, error: unknown) => Node[]) | undefined,
+): void {
+    const hydration = RENDER.hydration
+    let active: { nodes: Node[]; dispose: () => void } | undefined
+    let anchor: Node | undefined
+    let first = true
+    /* Bumped each run so a prior run's in-flight promise can't clobber a newer one. */
+    let generation = 0
+
+    const detach = (): void => {
+        if (active !== undefined) {
+            active.dispose()
+            for (const node of active.nodes) {
+                parent.removeChild(node)
+            }
+            active = undefined
+        }
+    }
+
+    /* Replace the current content with a freshly-built range, before the anchor. */
+    const place = (build: (parent: Node) => Node[]): void => {
+        detach()
+        let nodes: Node[] = []
+        const dispose = scope(() => {
+            nodes = build(parent)
+        })
+        active = { nodes, dispose }
+        for (const node of nodes) {
+            parent.insertBefore(node, anchor ?? null)
+        }
+    }
+
+    /* Render a settled-or-pending result into the current generation. */
+    const render = (result: unknown): void => {
+        const gen = generation
+        if (!isThenable(result)) {
+            place((host) => renderThen(host, result)) // warm-sync → resolved now, no flash
+            return
+        }
+        if (renderPending !== undefined) {
+            place((host) => renderPending(host))
+        } else {
+            detach()
+        }
+        result.then(
+            (value) => {
+                if (gen === generation) {
+                    place((host) => renderThen(host, value))
+                }
+            },
+            (error) => {
+                if (gen !== generation) {
+                    return
+                }
+                /* No catch branch → surface the rejection instead of an empty branch. */
+                if (renderCatch === undefined) {
+                    throw error
+                }
+                place((host) => renderCatch(host, error))
+            },
+        )
+    }
+
+    /* Adopt an SSR-resolved branch in place (its roots claim the existing nodes),
+       then park an anchor just before the close marker for later swaps. */
+    const adopt = (open: Node | null, build: (parent: Node) => Node[]): void => {
+        const cursor = hydration as NonNullable<typeof hydration>
+        cursor.next.set(parent, open?.nextSibling ?? null)
+        let nodes: Node[] = []
+        const dispose = scope(() => {
+            nodes = build(parent)
+        })
+        const close = claimChild(cursor, parent)
+        cursor.next.set(parent, close?.nextSibling ?? null)
+        anchor = document.createTextNode('')
+        parent.insertBefore(anchor, close)
+        active = { nodes, dispose }
+    }
+
+    /* Discard the SSR boundary and (re)build the block from the live promise, fresh
+       (hydration off) — the recovery path when adoption can't use the server markup. */
+    const rebuildCold = (open: Node | null): void => {
+        detach()
+        discardBoundary(
+            parent,
+            open,
+            `/abide:await:${id}`,
+            hydration as NonNullable<typeof hydration>,
+        )
+        anchor = document.createTextNode('')
+        parent.appendChild(anchor)
+        const previous = RENDER.hydration
+        RENDER.hydration = undefined
+        try {
+            render(promiseThunk())
+        } finally {
+            RENDER.hydration = previous
+        }
+    }
+
+    /* The first run when hydrating: adopt by precedence (resume / warm-sync), else
+       discard the boundary and mount fresh. Adoption is guarded: a resume value that
+       didn't round-trip (e.g. a non-serializable Response) throws while building the
+       branch — fall back to the live promise, which reads the properly-reconstructed
+       warm cache (or re-fetches) instead of crashing hydration. */
+    const firstHydrate = (result: unknown): void => {
+        const cursor = hydration as NonNullable<typeof hydration>
+        const open = claimChild(cursor, parent)
+        const entry = RESUME[id]
+        if (entry !== undefined) {
+            let build: (host: Node) => Node[]
+            if (entry.ok) {
+                build = (host) => renderThen(host, entry.value)
+            } else if (renderCatch !== undefined) {
+                build = (host) => renderCatch(host, entry.error)
+            } else {
+                /* A resumed rejection with no catch branch surfaces (mirrors the cold
+                   path); in practice the server 500s such a block, so none resumes. */
+                throw entry.error
+            }
+            try {
+                adopt(open, build)
+            } catch {
+                rebuildCold(open)
+            }
+            return
+        }
+        if (!isThenable(result)) {
+            try {
+                adopt(open, (host) => renderThen(host, result))
+            } catch {
+                rebuildCold(open)
+            }
+            return
+        }
+        discardBoundary(parent, open, `/abide:await:${id}`, cursor)
+        anchor = document.createTextNode('')
+        parent.appendChild(anchor)
+        render(result)
+    }
+
+    effect(() => {
+        generation += 1
+        /* Read the promise EVERY run, including the first hydrate run, so the block
+           subscribes to its reactive source (a cache key). A cache-remote read is warm
+           on resume — it serves the snapshot without a network round-trip, so adoption
+           stays no-flash AND a later cache.invalidate re-runs the block. Without this
+           read a resume-adopted block has no deps and invalidate is a no-op. */
+        const result = promiseThunk()
+        if (first) {
+            first = false
+            if (hydration !== undefined) {
+                firstHydrate(result)
+                return
+            }
+            anchor = document.createTextNode('')
+            parent.appendChild(anchor)
+        }
+        render(result)
+    })
+}
+
+/* Whether a value is Promise-like (the cold path); a non-thenable is warm-sync. */
+function isThenable(value: unknown): value is Promise<unknown> {
+    return value !== null && typeof (value as { then?: unknown })?.then === 'function'
+}
+
+/* Remove the SSR boundary — open marker through close marker (inclusive) — and
+   park the hydration cursor on the node after it, so a fresh run replaces it
+   without duplicating the server's pending shell. */
+function discardBoundary(
+    parent: Node,
+    open: Node | null,
+    closeData: string,
+    hydration: NonNullable<(typeof RENDER)['hydration']>,
+): void {
+    let node = open
+    let after: Node | null = null
+    while (node !== null) {
+        const next = node.nextSibling
+        const isClose = (node as { data?: string }).data === closeData
+        parent.removeChild(node)
+        if (isClose) {
+            after = next
+            break
+        }
+        node = next
+    }
+    hydration.next.set(parent, after)
+}

package/src/lib/ui/dom/cloneStatic.ts

@@ -0,0 +1,52 @@
+import { claimChild } from '../runtime/claimChild.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+
+/*
+Parsed-once `<template>` per unique static-skeleton string, reused across every
+mount. A `<template>` (not a detached `<div>`) so table/select content parses by
+the real content model, exactly as the browser parsed the server markup.
+*/
+const TEMPLATES = new Map<string, HTMLTemplateElement>()
+
+function templateFor(html: string): HTMLTemplateElement {
+    let template = TEMPLATES.get(html)
+    if (template === undefined) {
+        template = document.createElement('template')
+        template.innerHTML = html
+        TEMPLATES.set(html, template)
+    }
+    return template
+}
+
+/*
+Appends a fully-static subtree (one or more top-level nodes) under `parent` — what
+the compiler emits in place of the imperative `openChild`/`setAttribute`/
+`appendStatic` chain when an element subtree carries no bindings, control flow, or
+listeners. The skeleton string is generated by the same rules as the SSR back-end,
+so it is byte-identical to the server markup.
+
+Create mode: clone the cached template once per mount — a single deep clone (native
+in the browser) instead of N create/append calls. Hydrate mode: nothing is built;
+the server already rendered this exact markup, so it only advances the parent's
+claim cursor past the run's top-level nodes (nothing inside binds, so none need
+claiming individually). The node count comes from the parsed template, which has
+the same top-level node count as the server markup.
+*/
+// @readme plumbing
+export function cloneStatic(parent: Node, html: string): void {
+    const template = templateFor(html)
+    const hydration = RENDER.hydration
+    if (hydration !== undefined) {
+        let node = claimChild(hydration, parent)
+        let remaining = template.content.childNodes.length
+        while (remaining > 0 && node !== null) {
+            node = node.nextSibling
+            remaining -= 1
+        }
+        hydration.next.set(parent, node)
+        return
+    }
+    for (const child of template.content.childNodes) {
+        parent.appendChild(child.cloneNode(true))
+    }
+}

package/src/lib/ui/dom/each.ts

@@ -0,0 +1,115 @@
+import { effect } from '../effect.ts'
+import { claimChild } from '../runtime/claimChild.ts'
+import { OWNER } from '../runtime/OWNER.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+import { scope } from '../runtime/scope.ts'
+import type { EachRow } from './types/EachRow.ts'
+
+/*
+Keyed list binding — the runtime for `<template each key=>`. Rows live in their own
+region, bounded by a trailing anchor so positioning is relative to the each itself,
+never `parent.firstChild` — a sibling before the each (e.g. a static nav link) must
+not be treated as the first row. An effect tracks `items()` and reconciles by key:
+a new key renders a row in its own ownership scope (so the row's bindings dispose
+when it leaves), and a departed key disposes and is removed. Keying by identity
+(not index) lets a row keep its node and inner effects across a reorder.
+
+Placement walks the desired list *backwards* from the trailing anchor, holding a
+cursor at the node each row should precede; a row already sitting there is left
+untouched, so a stable list does zero DOM moves and an append does exactly one —
+only out-of-place rows are re-inserted (`insertBefore` on an in-place node would
+otherwise remove-then-reinsert it, O(rows) moves per change). Departed rows are
+pruned *before* placement so their nodes can't shift the cursor's sibling checks.
+
+On hydrate the SSR rows are already in place and in order: claim each one where it
+sits (no reordering), park the anchor after them, and skip the first reconcile.
+*/
+// @readme plumbing
+export function each<T>(
+    parent: Node,
+    items: () => Iterable<T>,
+    keyOf: (item: T) => string,
+    render: (parent: Node, item: T) => Node,
+): void {
+    const rows = new Map<string, EachRow>()
+
+    /* Build one row in its own scope (render claims on hydrate, creates otherwise). */
+    const buildRow = (item: T): EachRow => {
+        let node: Node | undefined
+        const dispose = scope(() => {
+            node = render(parent, item)
+        })
+        return { node: node as Node, dispose }
+    }
+
+    const hydration = RENDER.hydration
+    let anchor: Node
+    /* When hydrating, the first effect run must NOT reconcile — the rows it would
+       build are already adopted in place below. */
+    let adopting = false
+    if (hydration !== undefined) {
+        for (const item of items()) {
+            rows.set(keyOf(item), buildRow(item)) // claims the SSR row where it sits
+        }
+        anchor = document.createTextNode('')
+        parent.insertBefore(anchor, claimChild(hydration, parent))
+        adopting = true
+    } else {
+        anchor = document.createTextNode('')
+        parent.appendChild(anchor)
+    }
+
+    effect(() => {
+        /* Read (subscribe) every run, including the adopting one. Materialize a
+           non-array iterable to an array so a generator yields fresh each run and the
+           list can be safely traversed once for placement, once for pruning. */
+        const source = items()
+        if (adopting) {
+            adopting = false // rows already adopted in document order; nothing to move
+            return
+        }
+        const list = Array.isArray(source) ? source : [...source]
+        const keys = list.map(keyOf)
+        const present = new Set(keys)
+        /* Prune departed rows first so their nodes don't sit between survivors and
+           throw off the in-place sibling checks below. */
+        for (const [key, row] of rows) {
+            if (!present.has(key)) {
+                row.dispose()
+                parent.removeChild(row.node)
+                rows.delete(key)
+            }
+        }
+        /* Walk backwards from the anchor: `cursor` is the node the current row must
+           precede. A row already there keeps its place; only an out-of-order (or
+           freshly built) row is moved. Placement never touches preceding siblings. */
+        let cursor: Node = anchor
+        for (let index = list.length - 1; index >= 0; index -= 1) {
+            const key = keys[index] as string
+            let row = rows.get(key)
+            if (row === undefined) {
+                row = buildRow(list[index] as T)
+                rows.set(key, row)
+            }
+            if (row.node.nextSibling !== cursor) {
+                parent.insertBefore(row.node, cursor)
+            }
+            cursor = row.node
+        }
+    })
+
+    /* Dispose every row still live when the enclosing scope tears down. The effect's
+       own disposer only unsubscribes it from `items()`; it never reaches the per-row
+       ownership scopes, which are pruned only on the departed-key path above. Without
+       this, a row whose binding subscribes to a longer-lived signal (a module store,
+       the cache, `page`) stays in that signal's observers after the list unmounts. The
+       host's DOM is cleared by `mount`, so disposal need not remove the nodes. */
+    if (OWNER.current !== undefined) {
+        OWNER.current.push(() => {
+            for (const row of rows.values()) {
+                row.dispose()
+            }
+            rows.clear()
+        })
+    }
+}