@abide/abide 0.29.0 → 0.31.0

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

@@ -2,6 +2,7 @@ import { decodeHtmlEntities } from './decodeHtmlEntities.ts'
 import type { TemplateAttr } from './types/TemplateAttr.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 import type { TextPart } from './types/TextPart.ts'
+import { VOID_TAGS } from './VOID_TAGS.ts'
 
 /*
 A minimal compile-time parser for the abide template subset: elements, text with
@@ -19,23 +20,6 @@ text, never mistaken for a real style. Keeping it in the tree lets the front-end
 scope it to its sibling subtree (`analyzeComponent`); the node emits no DOM/markup.
 */
 
-const VOID_TAGS = new Set([
-    'area',
-    'base',
-    'br',
-    'col',
-    'embed',
-    'hr',
-    'img',
-    'input',
-    'link',
-    'meta',
-    'param',
-    'source',
-    'track',
-    'wbr',
-])
-
 /* A braced template expression with the absolute source offset of its first
    (post-trim) character, so the type-checking shadow can map a diagnostic back. */
 type Braced = { code: string; loc: number }
@@ -245,18 +229,29 @@ export function parseTemplate(source: string, baseOffset = 0): { nodes: Template
     return { nodes: roots }
 }
 
-/* Turns a component's attributes into props: a static value becomes a string
-   literal, an expression keeps its code (event/bind on components ignored). */
+/* Turns a component's attributes into props. A component has no directives —
+   every attribute is a prop under its written name, so `on*`/`bind:`/`attach`
+   round-trip to their original names (the kinds the tag-blind attribute parser
+   assigned) instead of being dropped. A static value becomes a string literal;
+   every other kind keeps its `code`, letting a prop hold any value, functions
+   included (e.g. an `onclick` callback). */
 function toProps(attrs: TemplateAttr[]): { name: string; code: string; loc?: number }[] {
-    const props: { name: string; code: string; loc?: number }[] = []
-    for (const attr of attrs) {
+    return attrs.map((attr) => {
         if (attr.kind === 'static') {
-            props.push({ name: attr.name, code: JSON.stringify(attr.value) })
-        } else if (attr.kind === 'expression') {
-            props.push({ name: attr.name, code: attr.code, loc: attr.loc })
+            return { name: attr.name, code: JSON.stringify(attr.value) }
         }
-    }
-    return props
+        /* Every non-static kind keeps its `code`/`loc`; only the prop name differs —
+           a directive (`event`/`bind`/`attach`) round-trips to its written name. */
+        const name =
+            attr.kind === 'event'
+                ? `on${attr.event}`
+                : attr.kind === 'bind'
+                  ? `bind:${attr.property}`
+                  : attr.kind === 'attach'
+                    ? 'attach'
+                    : attr.name
+        return { name, code: attr.code, loc: attr.loc }
+    })
 }
 
 /* The literal text of an attribute (a static value or an expression's code);

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

@@ -1,8 +1,9 @@
 import ts from 'typescript'
+import { REACTIVE_CALLEES } from './REACTIVE_CALLEES.ts'
 
 /*
 The signal binding names a `<script>` nested in a control-flow branch declares
-(`state`/`derived`/`prop`). The back-end adds them to the deref scope so both the
+(`state`/`linked`/`derived`/`prop`). The back-end adds them to the deref scope so both the
 script body and the branch's markup rewrite `{a}` → `a.value` — these stay PLAIN
 signals (local to the branch's render, owned by its scope, re-seeded from the
 in-scope data each mount), unlike the top-level component script which desugars to
@@ -18,7 +19,8 @@ export function nestedBindingNames(code: string): Set<string> {
         for (const declaration of statement.declarationList.declarations) {
             const callee = signalCallee(declaration)
             if (
-                (callee === 'state' || callee === 'derived' || callee === 'prop') &&
+                callee !== undefined &&
+                REACTIVE_CALLEES.has(callee) &&
                 ts.isIdentifier(declaration.name)
             ) {
                 names.add(declaration.name.text)

package/src/lib/ui/derived.ts

@@ -2,15 +2,26 @@ import { createComputedNode } from './runtime/createComputedNode.ts'
 import { OWNER } from './runtime/OWNER.ts'
 import { readNode } from './runtime/readNode.ts'
 import type { Derived } from './runtime/types/Derived.ts'
+import type { State } from './runtime/types/State.ts'
 import { unlinkDeps } from './runtime/unlinkDeps.ts'
 
 /*
-A read-only reactive cell computed from other cells — the abide replacement for
-`$derived`. Lazy: it recomputes on read only when a dependency has changed, and
-never serializes (it is re-derived from its inputs on resume). Read via `.value`.
+A reactive cell computed from other cells — the abide replacement for `$derived`.
+Lazy: it recomputes on read only when a dependency has changed, and never
+serializes (it is re-derived from its inputs on resume). Read via `.value`.
+
+With a `set`, it becomes a writable lens (Vue/Svelte's writable computed): the
+value still derives from upstream, but assigning `.value` runs `set`, whose job
+is to write *through* to the upstream sources. The write retriggers those
+sources, marking this computed dirty, so the next read recomputes — there is no
+local store, upstream stays the single source of truth. `set` is imperative
+(void): it writes an external target, unlike `state`/`linked`'s `transform`,
+which returns a value into their own store.
 */
 // @readme plumbing
-export function derived<T>(compute: () => T): Derived<T> {
+export function derived<T>(compute: () => T): Derived<T>
+export function derived<T>(compute: () => T, set: (next: T) => void): State<T>
+export function derived<T>(compute: () => T, set?: (next: T) => void): Derived<T> | State<T> {
     const node = createComputedNode(compute as () => unknown)
     /* Tear down with the enclosing scope, the way an effect does. A computed only
        unlinks from its sources when it re-runs (`runNode` re-tracking); one read
@@ -20,9 +31,19 @@ export function derived<T>(compute: () => T): Derived<T> {
     if (OWNER.current !== undefined) {
         OWNER.current.push(() => unlinkDeps(node))
     }
+    if (set === undefined) {
+        return {
+            get value(): T {
+                return readNode(node) as T
+            },
+        }
+    }
     return {
         get value(): T {
             return readNode(node) as T
         },
+        set value(next: T) {
+            set(next)
+        },
     }
 }

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

@@ -3,6 +3,7 @@ import { claimChild } from '../runtime/claimChild.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { RESUME } from '../runtime/RESUME.ts'
 import { scope } from '../runtime/scope.ts'
+import { discardBoundary } from './discardBoundary.ts'
 
 /*
 Async binding — the runtime for `<template await>`. Renders the pending branch,
@@ -198,27 +199,3 @@ export function awaitBlock(
 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/discardBoundary.ts

@@ -0,0 +1,27 @@
+import type { RENDER } from '../runtime/RENDER.ts'
+
+/* Remove an SSR boundary — open marker through close marker (inclusive) — and park
+   the hydration cursor on the node after it, returning that node. A fresh run then
+   replaces the boundary in place without duplicating the server's pending shell.
+   Shared by the await and try blocks (await ignores the return). */
+export function discardBoundary(
+    parent: Node,
+    open: Node | null,
+    closeData: string,
+    hydration: NonNullable<(typeof RENDER)['hydration']>,
+): Node | null {
+    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)
+    return after
+}

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

@@ -1,6 +1,7 @@
 import { claimChild } from '../runtime/claimChild.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
+import { discardBoundary } from './discardBoundary.ts'
 
 /*
 Synchronous error boundary — the runtime for `<template try>`. Builds the guarded
@@ -26,7 +27,12 @@ export function tryBlock(
     renderCatch?: (parent: Node, error: unknown) => Node[],
 ): void {
     /* Run a build under a fresh ownership scope; on throw, tear down the partial
-       effects/listeners it registered and rethrow so the caller can fall back. */
+       effects/listeners it registered and rethrow so the caller can fall back.
+       Deliberately not `scope()`: that returns a deferred disposer and leaks the
+       partial scope on throw (it only restores the owner), whereas an error boundary
+       must dispose eagerly when the guarded build throws and hand back the built
+       `Node[]` (not a disposer) on success — those nodes belong to the enclosing
+       scope. Different return type, different throw semantics; merging would be wrong. */
     const buildScoped = (build: () => Node[]): Node[] => {
         const previous = OWNER.current
         const disposers: Array<() => void> = []
@@ -85,28 +91,3 @@ export function tryBlock(
         parent.appendChild(node)
     }
 }
-
-/* Remove the SSR boundary — open marker through close marker (inclusive) — and
-   park the hydration cursor on the node after it, returning that node so a fresh
-   catch can be inserted in the boundary's place. */
-function discardBoundary(
-    parent: Node,
-    open: Node | null,
-    closeData: string,
-    hydration: NonNullable<(typeof RENDER)['hydration']>,
-): Node | null {
-    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)
-    return after
-}

package/src/lib/ui/installHotBridge.ts

@@ -21,6 +21,7 @@ import { switchBlock } from './dom/switchBlock.ts'
 import { tryBlock } from './dom/tryBlock.ts'
 import { when } from './dom/when.ts'
 import { effect } from './effect.ts'
+import { linked } from './linked.ts'
 import { enterRenderPass } from './runtime/enterRenderPass.ts'
 import { exitRenderPass } from './runtime/exitRenderPass.ts'
 import { hotReloadEnabled } from './runtime/hotReloadEnabled.ts'
@@ -44,6 +45,7 @@ export function installHotBridge(): void {
         snippet,
         doc,
         state,
+        linked,
         derived,
         effect,
         mount,

package/src/lib/ui/linked.ts

@@ -0,0 +1,34 @@
+import { createEffectNode } from './runtime/createEffectNode.ts'
+import type { State } from './runtime/types/State.ts'
+import { state } from './state.ts'
+
+/*
+A writable cell seeded reactively from upstream — the abide form of Angular's
+`linkedSignal`. Like `state` it owns a local value and can diverge from its
+source (an edit-form draft, a local working copy); unlike `state` the seed is a
+reactive thunk, so the cell reseeds whenever the thunk's dependencies change.
+Between reseeds it holds whatever was written to it, and edits never flow upstream
+(the seed reads, it does not write). The thunk is mandatory: it *is* the
+reactivity — a bare value can never reseed, which would just make this `state`.
+
+`transform` is the same coercion gate as on `state`, and it runs on *every* value
+entering the store — explicit `.value =` writes and reseeds alike — so the store
+never holds an un-coerced value (`return previous` rejects via the `Object.is`
+no-op). The seed is captured by reference: callers clone in the thunk
+(`linked(() => structuredClone(x))`) when they want isolation.
+*/
+// @readme plumbing
+export function linked<T>(seed: () => T, transform?: (next: T, previous: T) => T): State<T> {
+    /* The cell is a plain `state` — same store, same write path, so `transform` gates
+       reseeds and explicit writes identically. */
+    const cell = state<T>(undefined as T, transform)
+    /* Reactive reseed: the effect tracks the seed thunk and writes the cell when its
+       sources change. The cell is only written (its setter reads the store as a plain
+       field, never `readNode`), so it stays off the effect's dependency list — only
+       what `seed` reads can retrigger it. `createEffectNode` registers the disposer
+       with the enclosing scope. */
+    createEffectNode(() => {
+        cell.value = seed()
+    })
+    return cell
+}

package/src/lib/ui/router.ts

@@ -240,7 +240,7 @@ export function router(
                 }
                 /* Publish the active page so the `page` proxy resolves route/params/url. */
                 clientPage.value = {
-                    route: matched?.route ?? pathname,
+                    route: chainRoute,
                     params,
                     url:
                         typeof location === 'undefined'
@@ -264,12 +264,29 @@ export function router(
                 const hydrating =
                     first && pageView?.hydratable === true && pageView.hydrate !== undefined
                 first = false
-                const base = disposeFrom(divergence)
-                /* A fresh mount clears the torn-down DOM; hydration adopts it in place. */
-                if (!hydrating) {
-                    base.textContent = ''
+                /* The DOM mutation a navigation makes: tear the divergent chain down,
+                   clear its DOM (a fresh mount; hydration adopts in place), rebuild. */
+                const swap = (): void => {
+                    const base = disposeFrom(divergence)
+                    if (!hydrating) {
+                        base.textContent = ''
+                    }
+                    buildFrom(base, divergence, chainKeys, layoutViews, pageView, params, hydrating)
+                }
+                /* Wrap the swap in a View Transition where the browser supports it, so
+                   the page change cross-fades (and shared `view-transition-name` elements
+                   morph) — the synchronous swap is exactly the mutation the API snapshots
+                   around. Skipped while hydrating: the first paint adopts SSR DOM in place,
+                   not animate. CSS owns opting out (e.g. prefers-reduced-motion). */
+                if (
+                    !hydrating &&
+                    typeof document !== 'undefined' &&
+                    'startViewTransition' in document
+                ) {
+                    document.startViewTransition(swap)
+                } else {
+                    swap()
                 }
-                buildFrom(base, divergence, chainKeys, layoutViews, pageView, params, hydrating)
             })
         })
     })

package/src/lib/ui/state.ts

@@ -10,16 +10,23 @@ plain getter/setter over a signal node, so a read/write shows up as exactly that
 in a stack trace. The compiler's job (later) is only to auto-deref `{cell}` in
 templates and tag this declaration as a serializable manifest slot; the runtime
 needs no magic.
+
+`transform` is an optional coercion gate on the write path: every `.value =`
+runs it and stores what it returns, with `previous` for clamp-relative writes or
+rejection (`return previous` is an `Object.is` no-op). It is the local-truth
+mirror of `derived`'s write-through `set` — here the value lives in this cell, so
+the gate *returns* what to store rather than writing an external target. The
+construction `initial` is taken verbatim; the gate runs on writes only.
 */
 // @readme plumbing
-export function state<T>(initial: T): State<T> {
+export function state<T>(initial: T, transform?: (next: T, previous: T) => T): State<T> {
     const node = createSignalNode(initial)
     return {
         get value(): T {
             return readNode(node) as T
         },
         set value(next: T) {
-            writeNode(node, next)
+            writeNode(node, transform === undefined ? next : transform(next, node.value as T))
         },
     }
 }

package/template/src/ui/pages/page.abide

@@ -10,8 +10,8 @@ replayed on the client during hydration with no second fetch. A `then` *child*
 instead would stream the resolution in out of order.
 */
 import { cache } from '@abide/abide/shared/cache'
-import Layout from '../Layout.abide'
 import { getHello } from '$server/rpc/getHello.ts'
+import Layout from '../Layout.abide'
 </script>
 
 <Layout>