@abide/abide 0.30.0 → 0.31.1

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'

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>