@abide/abide 0.38.1 → 0.40.0

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

@@ -1,9 +1,12 @@
 /*
-Source text for the `$esc` / `$attr` / `$text` / `$snip` helpers injected into
-every SSR render body. `$esc` escapes the five HTML-significant characters. `$attr`
+Source text for the `$esc` / `$attr` / `$spread` / `$text` / `$snip` helpers injected
+into every SSR render body. `$esc` escapes the five HTML-significant characters. `$attr`
 renders a dynamic `{expr}` attribute with the same present/absent semantics the
 client `attr` binding uses: false/null/undefined drops it, true emits the bare
-attribute, anything else emits `name="escaped"`. `$snip` brands a snippet's
+attribute, anything else emits `name="escaped"`. `$spread` renders a `{...obj}`
+element spread — each key as an attribute via `$attr`, skipping functions (event
+handlers, wired client-side by `spreadAttrs`) and any key in the `skip` list (a key the
+element names explicitly, which wins over the spread) — mirroring that client runtime. `$snip` brands a snippet's
 rendered string. `$text` is what `{expr}` interpolations push: a snippet call's
 value is emitted raw between `<!--abide:snippet-->` markers (the client runs its
 builder there to claim the nodes); a `html\`…\`` value raw between `<!--abide:html-->`
@@ -16,6 +19,13 @@ export const SSR_ESCAPE =
     "({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '\"': '&quot;', \"'\": '&#39;' })[c]);\n" +
     'const $attr = (n, v) => (v === false || v === null || v === undefined) ? "" ' +
     ': v === true ? (" " + n) : (" " + n + \'="\' + $esc(v) + \'"\');\n' +
+    'const $spread = (o, skip) => { let s = ""; for (const k in o) { ' +
+    'if (skip && skip.indexOf(k) >= 0) continue; ' +
+    /* Skip keys that aren't valid attribute names: $attr emits the name verbatim, so a
+       runtime-controlled key with whitespace/quotes/`>`/`=`/`/` would inject markup. The
+       client's setAttribute throws on these, so dropping them matches that behaviour. */
+    'if (/[\\s"\'>\\/=]/.test(k)) continue; ' +
+    'const v = o[k]; if (typeof v !== "function") s += $attr(k, v); } return s; };\n' +
     "const $RAW = Symbol.for('abide.rawHtml');\n" +
     "const $SNIP = Symbol.for('abide.snippet');\n" +
     'const $snip = (s) => ({ [$SNIP]: s });\n' +

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

@@ -32,6 +32,11 @@ export const UI_RUNTIME_IMPORTS: { name: string; specifier: string }[] = [
     { name: 'mountSlot', specifier: 'ui/dom/mountSlot' },
     { name: 'outlet', specifier: 'ui/dom/outlet' },
     { name: 'mountChild', specifier: 'ui/dom/mountChild' },
+    { name: 'mergeProps', specifier: 'ui/dom/mergeProps' },
+    { name: 'spreadProps', specifier: 'ui/dom/spreadProps' },
+    { name: 'restProps', specifier: 'ui/dom/restProps' },
+    { name: 'spreadAttrs', specifier: 'ui/dom/spreadAttrs' },
+    { name: 'readCall', specifier: 'ui/dom/readCall' },
     { name: 'hydrate', specifier: 'ui/dom/hydrate' },
     { name: 'escapeKey', specifier: 'ui/runtime/escapeKey' },
     { name: 'nextBlockId', specifier: 'ui/runtime/nextBlockId' },

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

@@ -9,7 +9,10 @@ Wraps a component into a complete ES module with two entry points:
 
   - default `component(host, $props)` — mounts the client build, returns the
     disposer (`import Counter from './Counter.abide'; const stop = Counter(host)`);
-  - `render($props)` — server-renders to `{ html, state, awaits }` for SSR.
+  - `render($props, $ctx)` — async, server-renders to `{ html, state, awaits, resume }`
+    for SSR. `$ctx` is the request-local block-id counter, threaded so a child's
+    `await`/`try` ids share the page's depth-first numbering; omitted at the top level
+    (a fresh counter defaults in).
 
 `render` is also attached to the default export (`component.render`) so a parent
 can server-render a child it imported by its default name. Both entry points share
@@ -76,7 +79,7 @@ export function hydrateInto(host, $props) {
     return hydrate(host, build, $props)
 }
 
-export function render($props) {
+export function render($props, $ctx) {
 ${ssrBody}
 }
 

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

@@ -16,10 +16,24 @@ front-end, then the SSR back-end, and returns `{ html, state, awaits }`:
 Effects are stripped — they are client lifecycle and emit no HTML, so the server
 render is a snapshot of the markup before any effect runs.
 
-Runs with `doc`/`state`/`computed`/`effect`/`nextBlockId`/`enterRenderPass`/
-`exitRenderPass` in scope and defines `model`. The body is bracketed by a render
-pass so the outermost render resets the block-id counter and an inlined child
-render continues it — keeping await/try ids unique and aligned with the client.
+Defines `model` with `doc`/`state`/`computed`/`effect` in scope. The block-id counter is
+the request-local `$ctx` (threaded into child renders), not a module global — a blocking
+`await` block awaits its promise at its structural position and renders inline, so ids
+allocate depth-first like the client; render yields at that `await`, and a shared global
+counter would interleave across concurrent requests. `$ctx` defaults to a fresh counter
+when a caller (a test, a top-level render) omits it.
+
+The body is wrapped in an ASYNC IIFE (returns `Promise<SsrRender>`) ONLY when it contains
+an inline `await` — a blocking `{#await … then}` block, a child-component render, a `<slot>`
+read (its `$children` builder is async), or a top-level `await` in the author script. A
+purely synchronous / streaming-await / try-only component returns `SsrRender` directly. The
+framework always `await`s `render()`, so production is uniform either way; the sync return
+keeps static pages off the microtask queue and leaves the bulk of the SSR tests synchronous.
+
+The reactive scope brackets the body; it is entered synchronously before any inline `await`,
+so `const model = scope()` resolves correctly, and `model` is captured for the rest of the
+render (its reads are object-method calls, not scope lookups, so they stay correct across
+the awaits).
 
 `analyzed` is a lazy default: a direct caller (tests) omits it and the front-end
 runs here, but `compileModule` shares one analysis across both back-ends.
@@ -31,15 +45,24 @@ export function compileSSR(
     analyzed: AnalyzedComponent = analyzeComponent(source, scopeSeed),
 ): string {
     const { script, stateNames, derivedNames, computedNames, nodes } = analyzed
+    const lowered = stripEffects(script)
     const ssr = generateSSR(nodes, stateNames, derivedNames, computedNames, isLayout)
     /* No `<style>` in the markup — the scoped CSS is bundled into the entry stylesheet
        the shell links (see `abideUiPlugin`), so SSR output is styled by that sheet. The
        elements still carry their `data-a-…` scopes via `generateSSR`. */
     /* `typeof model` guards a component with no reactive state (a pure-async or
        static component declares no `model`); its snapshot is then empty. */
-    return (
-        `enterRenderPass();\nconst $scope = enterScope();\ntry {\n${stripEffects(script)}\n${SSR_ESCAPE}\nconst $out = [];\nconst $awaits = [];\n${ssr}` +
-        `return { html: $out.join(''), state: (typeof model !== 'undefined' ? model.snapshot() : {}), awaits: $awaits };\n` +
-        `} finally { exitScope($scope); exitRenderPass(); }`
-    )
+    const body =
+        `const $scope = enterScope();\ntry {\n${lowered}\n${SSR_ESCAPE}\nconst $out = [];\nconst $awaits = [];\nconst $resume = {};\n${ssr}` +
+        `return { html: $out.join(''), state: (typeof model !== 'undefined' ? model.snapshot() : {}), awaits: $awaits, resume: $resume };\n` +
+        `} finally { exitScope($scope); }`
+    /* An inline `await` — a blocking await block, a child render, a slot read, or a
+       top-level `await` in the author script — forces an async wrapper. Match `await` as a
+       standalone token (operator), so a no-space form (`await(x)`, `await[i]`, `` await`t` ``)
+       is caught where a `.includes('await ')` substring scan would miss it and emit a bare
+       top-level `await` in a non-async function (a SyntaxError). `(?!:)` excludes the
+       `<!--abide:await:N-->` boundary-marker strings; `\b` excludes `$awaits`. A false
+       positive (the token in author text) only costs a needless async wrapper, never a crash. */
+    const needsAsync = /\bawait\b(?!:)/.test(`${lowered}${ssr}`)
+    return `var $ctx = $ctx || { next: 0 };\n${needsAsync ? `return (async () => {\n${body}\n})();` : body}`
 }

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

@@ -357,9 +357,17 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                    unterminated (a script ending in a call with no trailing semicolon,
                    e.g. `effect(() => …)`) merges across the newline into `effect(…)(…)`
                    — a spurious "not callable" on the author's last statement. */
-                builder.raw(
-                    `;((__prop: Parameters<typeof ${node.name}>[0][${JSON.stringify(prop.name)}]) => {})(`,
-                )
+                if (prop.spread) {
+                    /* A `{...expr}` spread contributes a SUBSET of the props (required ones
+                       may come from another spread/explicit prop), so check it against
+                       `Partial<Props>` — every key it does carry must match the child's
+                       declared type, without demanding completeness. */
+                    builder.raw(`;((__spread: Partial<Parameters<typeof ${node.name}>[0]>) => {})(`)
+                } else {
+                    builder.raw(
+                        `;((__prop: Parameters<typeof ${node.name}>[0][${JSON.stringify(prop.name)}]) => {})(`,
+                    )
+                }
                 builder.expr(prop.code, prop.loc)
                 builder.raw(');\n')
             }
@@ -373,19 +381,26 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                narrowing — emitting it inside the `if` block (as a plain child) instead
                gave it the positive narrowing, so a literal-union compare read as a
                "no overlap" and a typeof-narrowed branch saw the wrong member. */
-            const elseChild = node.children.find(
-                (child): child is Extract<TemplateNode, { kind: 'case' }> =>
-                    child.kind === 'case' && child.match === undefined,
+            const branches = node.children.filter(
+                (child): child is Extract<TemplateNode, { kind: 'case' }> => child.kind === 'case',
             )
-            const thenChildren = node.children.filter((child) => child !== elseChild)
+            const thenChildren = node.children.filter((child) => child.kind !== 'case')
             builder.raw('if ')
             builder.expr(node.condition, node.loc)
             builder.raw(' {\n')
             emitNodes(thenChildren, builder)
             builder.raw('}')
-            if (elseChild !== undefined) {
-                builder.raw(' else {\n')
-                emitNodes(elseChild.children, builder)
+            /* `elseif` → a real `else if` so its body inherits the prior conditions' negative
+               narrowing plus its own positive; `else` → the trailing block. */
+            for (const branch of branches) {
+                if (branch.condition !== undefined) {
+                    builder.raw(' else if ')
+                    builder.expr(branch.condition, branch.loc)
+                    builder.raw(' {\n')
+                } else {
+                    builder.raw(' else {\n')
+                }
+                emitNodes(branch.children, builder)
                 builder.raw('}')
             }
             builder.raw('\n')

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

@@ -0,0 +1,53 @@
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/* The authored props of a child-component node (each attribute lowered to a prop;
+   a `spread` entry carries no `name`). */
+type ComponentProps = Extract<TemplateNode, { kind: 'component' }>['props']
+
+/*
+The props-bag source expression a child mount/render receives, shared by the build
+and SSR back-ends so their last-wins layering stays byte-identical — the invariant
+SSR/client prop congruence rests on. No spread → the plain object literal of named
+value thunks (+ the trailing slot). With a `{...expr}` spread → a `mergeProps` of
+ordered layers — explicit-prop runs, `spreadProps(expr)` spreads, the slot —
+resolved last-wins per key, so source order decides overrides (like JSX).
+`lowerExpression` is the caller's expression lowering; `slotPart` is its `$children`
+layer (a host-taking builder for the client, a string-returning thunk for SSR) or
+undefined when the component has no slotted children.
+*/
+export function composeProps(
+    props: ComponentProps,
+    lowerExpression: (code: string) => string,
+    slotPart: string | undefined,
+): string {
+    const propThunk = (prop: { name: string; code: string }): string =>
+        `${JSON.stringify(prop.name)}: () => (${lowerExpression(prop.code)})`
+    if (!props.some((prop) => prop.spread)) {
+        const parts = props.map(propThunk)
+        if (slotPart !== undefined) {
+            parts.push(slotPart)
+        }
+        return `{ ${parts.join(', ')} }`
+    }
+    const layers: string[] = []
+    let run: string[] = []
+    const flushRun = (): void => {
+        if (run.length > 0) {
+            layers.push(`{ ${run.join(', ')} }`)
+            run = []
+        }
+    }
+    for (const prop of props) {
+        if (prop.spread) {
+            flushRun()
+            layers.push(`spreadProps(() => (${lowerExpression(prop.code)}))`)
+        } else {
+            run.push(propThunk(prop))
+        }
+    }
+    flushRun()
+    if (slotPart !== undefined) {
+        layers.push(`{ ${slotPart} }`)
+    }
+    return `mergeProps([${layers.join(', ')}])`
+}

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

@@ -60,6 +60,9 @@ export function desugarSignals(scriptBody: string): {
     const stateNames = new Set<string>()
     const derivedNames = new Set<string>()
     const computedNames = new Set<string>()
+    /* A `props()` destructure must be lowered even when it declares no reactive binding
+       (a rest-only `const { ...rest } = props()`), so track its presence on its own. */
+    let hasPropsDestructure = false
     for (const statement of source.statements) {
         if (!ts.isVariableStatement(statement)) {
             continue
@@ -67,14 +70,16 @@ export function desugarSignals(scriptBody: string): {
         for (const declaration of statement.declarationList.declarations) {
             const callee = signalCallee(declaration)
             if (callee === 'props') {
-                /* `const {…} = props()` — each destructured binding is a read-only
-                   computed over the parent thunk, read as `name()`. */
+                /* `const {…, ...rest} = props()` — each named binding is a read-only computed
+                   over the parent thunk (read as `name()`); a `...rest` binding stays a plain
+                   const (a `restProps` bag), so it joins no reactive set. */
                 if (!ts.isObjectBindingPattern(declaration.name)) {
                     throw new Error(
                         'abide: `props()` must be destructured — `const { a, b } = props()`',
                     )
                 }
-                for (const binding of propsBindings(declaration)) {
+                hasPropsDestructure = true
+                for (const binding of propsDestructure(declaration).bindings) {
                     computedNames.add(binding.local)
                 }
                 continue
@@ -98,7 +103,12 @@ export function desugarSignals(scriptBody: string): {
             }
         }
     }
-    if (stateNames.size === 0 && derivedNames.size === 0 && computedNames.size === 0) {
+    if (
+        stateNames.size === 0 &&
+        derivedNames.size === 0 &&
+        computedNames.size === 0 &&
+        !hasPropsDestructure
+    ) {
         return { code: scriptBody, stateNames, derivedNames, computedNames }
     }
 
@@ -249,23 +259,34 @@ function signalCallee(declaration: ts.VariableDeclaration): string | undefined {
    the optional `= default` expression (the fallback when the prop is absent). */
 type PropsBinding = { local: string; key: string; initializer: ts.Expression | undefined }
 
-/* The bindings of a `const {…} = props()` pattern. Rest (`...rest`) and nested
-   destructuring have no single prop key, so they throw a legible compile error. */
-function propsBindings(declaration: ts.VariableDeclaration): PropsBinding[] {
+/* The destructure of a `const {…, ...rest} = props()` pattern — its named bindings
+   plus an optional rest binding (the unconsumed props, gathered by `restProps`).
+   Nested destructuring has no single prop key, so it throws a legible compile error. */
+function propsDestructure(declaration: ts.VariableDeclaration): {
+    bindings: PropsBinding[]
+    rest: string | undefined
+} {
     const pattern = declaration.name as ts.ObjectBindingPattern
-    return pattern.elements.map((element) => {
+    const bindings: PropsBinding[] = []
+    let rest: string | undefined
+    for (const element of pattern.elements) {
         if (element.dotDotDotToken !== undefined) {
-            throw new Error('abide: `...rest` in `props()` destructuring is not supported')
+            if (!ts.isIdentifier(element.name)) {
+                throw new Error('abide: `...rest` in `props()` must bind a plain name')
+            }
+            rest = element.name.text
+            continue
         }
         if (!ts.isIdentifier(element.name)) {
             throw new Error('abide: nested destructuring in `props()` is not supported')
         }
-        return {
+        bindings.push({
             local: element.name.text,
             key: propsBindingKey(element),
             initializer: element.initializer,
-        }
-    })
+        })
+    }
+    return { bindings, rest }
 }
 
 /* The parent prop key a binding element reads — its rename source (`name: alias` →
@@ -285,10 +306,11 @@ function propsBindingKey(element: ts.BindingElement): string {
     throw new Error('abide: computed prop keys in `props()` destructuring are not supported')
 }
 
-/* If `statement` is a `const {…} = props()` destructure, returns one reactive
-   computed per binding — `scope().derive("name", () => $props["key"]?.() ?? default)`
-   — read as `name()`; otherwise undefined. The `?? default` applies the binding's
-   `= default` fallback when the prop is absent. */
+/* If `statement` is a `const {…, ...rest} = props()` destructure, returns one reactive
+   computed per named binding — `scope().derive("name", () => $props["key"]?.() ?? default)`,
+   read as `name()` — plus a `const rest = restProps($props, [consumed])` line for a rest
+   binding; otherwise undefined. The `?? default` applies the binding's `= default` fallback
+   when the prop is absent. */
 function propsDestructureLines(
     statement: ts.Statement,
     printer: ts.Printer,
@@ -302,7 +324,8 @@ function propsDestructureLines(
         if (signalCallee(declaration) !== 'props' || !ts.isObjectBindingPattern(declaration.name)) {
             return undefined
         }
-        for (const { local, key, initializer } of propsBindings(declaration)) {
+        const { bindings, rest } = propsDestructure(declaration)
+        for (const { local, key, initializer } of bindings) {
             const fallback =
                 initializer === undefined
                     ? ''
@@ -311,6 +334,11 @@ function propsDestructureLines(
                 `const ${local} = scope().derive(${JSON.stringify(local)}, () => $props[${JSON.stringify(key)}]?.()${fallback})`,
             )
         }
+        /* The rest bag gathers every prop not named above (and not `$children`). */
+        if (rest !== undefined) {
+            const consumed = bindings.map((binding) => binding.key)
+            lines.push(`const ${rest} = restProps($props, ${JSON.stringify(consumed)})`)
+        }
     }
     return lines
 }