@abide/abide 0.31.1 → 0.32.1

package/src/lib/ui/dom/types/EachRow.ts

@@ -1,3 +1,10 @@
-/* A live row in a keyed list: its top node (for placement/removal) and the
-   disposer for the bindings created in its ownership scope. */
-export type EachRow = { node: Node; dispose: () => void }
+/* A live row in a keyed list: a content RANGE bounded by two comment markers (so a
+   row holds any content, not just one node), plus the disposer for the bindings
+   created in its ownership scope. `pending` holds a freshly built row's nodes in a
+   fragment until first placement inserts them. */
+export type EachRow = {
+    start: Node
+    end: Node
+    dispose: () => void
+    pending?: DocumentFragment
+}

package/src/lib/ui/dom/types/SwitchCase.ts

@@ -1,6 +1,7 @@
 /* One branch of a `switch`: `match` returns the value this case selects on
-   (undefined = the default branch); `render` builds the branch's element roots. */
+   (undefined = the default branch); `render` builds the branch's content into the
+   parent (the block tracks it as a range between markers). */
 export type SwitchCase = {
     match: (() => unknown) | undefined
-    render: (parent: Node) => Node[]
+    render: (parent: Node) => void
 }

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

@@ -1,51 +1,51 @@
 import { effect } from '../effect.ts'
-import { claimChild } from '../runtime/claimChild.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { clearBetween } from './clearBetween.ts'
+import { fillBefore } from './fillBefore.ts'
+import { openMarker } from './openMarker.ts'
 
 /*
-Conditional binding — the runtime for `<template if>` (with optional `else`). An
-effect tracks `condition()` and mounts the matching branch (`render` truthy,
-`renderElse` falsy), anchored for placement; only a truthy↔falsy flip swaps. A
-branch is a RANGE of element roots (one or more), tracked as a node array so a
-multi-root branch inserts/removes as a unit.
+Conditional binding — the runtime for `<template if>` (with optional `else`). The
+branch's content lives in a RANGE bounded by two comment markers, so a branch may
+hold anything — elements, components, text, nested control-flow, snippets — not
+just element roots. An effect tracks `condition()` and swaps the range's content
+on a truthy↔falsy flip (`render` truthy, `renderElse` falsy); an unchanged
+condition is a no-op.
 
-On hydrate it adopts the branch the server rendered: it runs the matching render
-in place (its roots claim the existing nodes), then inserts an anchor after them
-for future toggles. The effect's first run sees the same branch and is a no-op;
-later toggles (after hydration ends) build fresh.
+On hydrate it adopts the server-rendered range: claim the start marker, run the
+matching render in place (its content claims the existing nodes), then claim the
+end marker. The effect's first run sees the same branch and is a no-op; later
+toggles clear the range and build fresh into a fragment.
 */
 // @readme plumbing
 export function when(
     parent: Node,
     condition: () => unknown,
-    render: (parent: Node) => Node[],
-    renderElse?: (parent: Node) => Node[],
+    render: (parent: Node) => void,
+    renderElse?: (parent: Node) => void,
 ): void {
     const hydration = RENDER.hydration
-    let active: { nodes: Node[]; dispose: () => void } | undefined
-    let activeBranch: 'then' | 'else' | undefined
-    let anchor: Node
-
-    const build = (chosen: (parent: Node) => Node[]): { nodes: Node[]; dispose: () => void } => {
-        let nodes: Node[] = []
-        const dispose = scope(() => {
-            nodes = chosen(parent)
-        })
-        return { nodes, dispose }
-    }
+    const chosenFor = (branch: 'then' | 'else') => (branch === 'then' ? render : renderElse)
+    let dispose: (() => void) | undefined
+    let activeBranch: 'then' | 'else'
+    let end: Comment
 
+    const start = openMarker(parent, '[')
     if (hydration !== undefined) {
         activeBranch = condition() ? 'then' : 'else'
-        const chosen = activeBranch === 'then' ? render : renderElse
+        const chosen = chosenFor(activeBranch)
         if (chosen !== undefined) {
-            active = build(chosen) // roots claim the SSR nodes in place
+            dispose = scope(() => chosen(parent)) // content claims the SSR nodes in place
         }
-        anchor = document.createTextNode('')
-        parent.insertBefore(anchor, claimChild(hydration, parent))
+        end = openMarker(parent, ']')
     } else {
-        anchor = document.createTextNode('')
-        parent.appendChild(anchor)
+        end = openMarker(parent, ']')
+        activeBranch = condition() ? 'then' : 'else'
+        const chosen = chosenFor(activeBranch)
+        if (chosen !== undefined) {
+            dispose = fillBefore(end, chosen)
+        }
     }
 
     effect(() => {
@@ -53,21 +53,12 @@ export function when(
         if (branch === activeBranch) {
             return
         }
-        if (active !== undefined) {
-            active.dispose()
-            for (const node of active.nodes) {
-                parent.removeChild(node)
-            }
-            active = undefined
-        }
+        clearBetween(start, end, dispose)
+        dispose = undefined
         activeBranch = branch
-        const chosen = branch === 'then' ? render : renderElse
-        if (chosen === undefined) {
-            return
-        }
-        active = build(chosen)
-        for (const node of active.nodes) {
-            parent.insertBefore(node, anchor)
+        const chosen = chosenFor(branch)
+        if (chosen !== undefined) {
+            dispose = fillBefore(end, chosen)
         }
     })
 }

package/src/lib/ui/installHotBridge.ts

@@ -16,7 +16,6 @@ import { mount } from './dom/mount.ts'
 import { mountChild } from './dom/mountChild.ts'
 import { on } from './dom/on.ts'
 import { openChild } from './dom/openChild.ts'
-import { openRoot } from './dom/openRoot.ts'
 import { switchBlock } from './dom/switchBlock.ts'
 import { tryBlock } from './dom/tryBlock.ts'
 import { when } from './dom/when.ts'
@@ -50,7 +49,6 @@ export function installHotBridge(): void {
         effect,
         mount,
         openChild,
-        openRoot,
         appendText,
         appendSnippet,
         appendStatic,

package/src/lib/ui/renderToStream.ts

@@ -5,10 +5,11 @@ import type { SsrAwait, SsrRender } from './runtime/types/SsrRender.ts'
 Out-of-order SSR streaming. Yields the pending shell first (so the browser paints
 immediately), then one resolved fragment per await block as its promise settles —
 in completion order, not source order, so a slow read never blocks a fast one.
-Each resolved fragment is a `<abide-resolve data-id="ID" data-resume="…">…</abide-resolve>`
-that `applyResolved` swaps into the matching `<!--abide:await:ID-->` boundary; the
-`data-resume` payload is the JSON-serialized value, registered for hydration so an
-`await` block adopts the resolved branch on resume instead of re-running.
+Each resolved fragment is a `<abide-resolve data-id="ID"><script type="application/json">
+…</script>…</abide-resolve>` that `applyResolved` swaps into the matching
+`<!--abide:await:ID-->` boundary; the leading script holds the JSON-serialized value,
+registered for hydration so an `await` block adopts the resolved branch on resume
+instead of re-running.
 
 This is the await-block-streams half of the cache rule: a top-level `await` in the
 script would have blocked the shell (inlined), but an await *block* flushes its
@@ -46,7 +47,9 @@ export async function* renderToStream(render: () => SsrRender): AsyncGenerator<s
         const resolved = await Promise.race(inflight.values())
         inflight.delete(resolved.id)
         const resume = encodeResume(resolved.resume)
-        yield `<abide-resolve data-id="${resolved.id}" data-resume="${resume}">${resolved.html}</abide-resolve>`
+        yield `<abide-resolve data-id="${resolved.id}">` +
+            `<script type="application/json">${resume}</script>` +
+            `${resolved.html}</abide-resolve>`
     }
 }
 
@@ -94,11 +97,11 @@ function settle(block: SsrAwait): Promise<Settled> {
     )
 }
 
-/* JSON for an HTML double-quoted attribute: escape `"` and `&` (and `<` for safety
-   inside markup). `applyResolved`/the inline swap script decode it via the DOM. */
+/* JSON for a `<script type="application/json">` data block: script content is raw
+   text, so only `<` needs neutralizing (emitted as a unicode escape) to keep a
+   literal `</script>` from closing the block early — quotes stay raw. Far cheaper
+   than attribute escaping (no full-string `"`/`&` passes) and JSON.parse decodes it
+   back. `applyResolved`/the inline swap script read it via `.textContent`. */
 function encodeResume(resume: ResumeEntry): string {
-    return JSON.stringify(resume)
-        .replace(/&/g, '&amp;')
-        .replace(/"/g, '&quot;')
-        .replace(/</g, '&lt;')
+    return JSON.stringify(resume).replace(/</g, '\\u003c')
 }

package/src/lib/ui/state.ts

@@ -18,15 +18,24 @@ mirror of `derived`'s write-through `set` — here the value lives in this cell,
 the gate *returns* what to store rather than writing an external target. The
 construction `initial` is taken verbatim; the gate runs on writes only.
 */
+/* No-arg form for an undefined initial with a declared type: `state<Foo>()` is
+   `State<Foo | undefined>`. Without it `state<Foo>(undefined)` is an arity/assign
+   error and `state(undefined)` infers `T = undefined` (every `.value` access then
+   narrows to `never`). */
 // @readme plumbing
-export function state<T>(initial: T, transform?: (next: T, previous: T) => T): State<T> {
+export function state<T>(): State<T | undefined>
+export function state<T>(initial: T, transform?: (next: T, previous: T) => T): State<T>
+export function state<T>(
+    initial?: T,
+    transform?: (next: T, previous: T) => T,
+): State<T | undefined> {
     const node = createSignalNode(initial)
     return {
-        get value(): T {
-            return readNode(node) as T
+        get value(): T | undefined {
+            return readNode(node) as T | undefined
         },
-        set value(next: T) {
-            writeNode(node, transform === undefined ? next : transform(next, node.value as T))
+        set value(next: T | undefined) {
+            writeNode(node, transform === undefined ? next : transform(next as T, node.value as T))
         },
     }
 }

package/src/lib/ui/compile/branchElements.ts

@@ -1,50 +0,0 @@
-import type { TemplateNode } from './types/TemplateNode.ts'
-
-/*
-The element roots of a control-flow branch (`if`/`else`/`switch case`/`await
-then|catch`). A branch may hold one or MORE top-level elements — each becomes a
-root the block tracks as a range. Whitespace-only text between/around them is
-dropped (so SSR and the client build agree on the node set, keeping hydration
-aligned). Any other top-level content — meaningful text, a component, or a nested
-control-flow `<template>` — must be wrapped in an element; it throws a clear error
-rather than silently dropping (full fragment roots are a separate feature).
-
-Both back-ends call this, so the server HTML and the client build contain exactly
-the same roots in the same order.
-*/
-type ElementNode = Extract<TemplateNode, { kind: 'element' }>
-
-export function branchElements(
-    children: TemplateNode[],
-    context: string,
-    allowEmpty = false,
-): ElementNode[] {
-    const elements: ElementNode[] = []
-    for (const child of children) {
-        if (child.kind === 'element') {
-            elements.push(child)
-            continue
-        }
-        /* Whitespace-only text is layout noise between roots — drop it. */
-        if (child.kind === 'text' && isWhitespaceOnly(child)) {
-            continue
-        }
-        /* A scoped `<script>` is emitted as code by the back-end, not a root; a
-           `<style>` is bundled CSS (its scope already stamped on the roots). */
-        if (child.kind === 'script' || child.kind === 'style') {
-            continue
-        }
-        throw new Error(
-            `[abide] ${context} content must be element(s); wrap text / components / nested <template> in an element`,
-        )
-    }
-    if (elements.length === 0 && !allowEmpty) {
-        throw new Error(`[abide] ${context} must contain at least one element`)
-    }
-    return elements
-}
-
-/* A text node whose parts are all whitespace literals (no interpolation). */
-function isWhitespaceOnly(node: Extract<TemplateNode, { kind: 'text' }>): boolean {
-    return node.parts.every((part) => part.kind === 'static' && part.value.trim() === '')
-}

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

@@ -1,20 +0,0 @@
-import { claimChild } from '../runtime/claimChild.ts'
-import { RENDER } from '../runtime/RENDER.ts'
-
-/*
-Opens the root element of a control-flow branch/row, which the block inserts
-itself. In create mode it returns a detached element (the block does the
-insert); in hydrate mode it claims the existing server-rendered root from the
-parent's claim pointer (in place — the block adopts it). The compiler emits this
-for `each`/`if`/`switch`/`await` branch roots so adoption and creation share code.
-*/
-// @readme plumbing
-export function openRoot(parent: Node, tag: string): Element {
-    const hydration = RENDER.hydration
-    if (hydration !== undefined) {
-        const current = claimChild(hydration, parent)
-        hydration.next.set(parent, current === null ? null : current.nextSibling)
-        return current as unknown as Element
-    }
-    return document.createElement(tag)
-}