@abide/abide 0.33.1 → 0.34.0

package/src/lib/ui/types/Scope.ts

@@ -0,0 +1,57 @@
+import type { computed } from '../computed.ts'
+import type { linked } from '../linked.ts'
+import type { Cell } from '../runtime/types/Cell.ts'
+import type { Patch } from '../runtime/types/Patch.ts'
+import type { state } from '../state.ts'
+import type { SyncTransport } from './SyncTransport.ts'
+
+/*
+A lexical scope: the unit that owns a region's reactive data, its lifetime, and
+the capabilities applied to it. Its data surface MIRRORS `Doc` (read/replace/add/
+remove/cell/derive/apply/snapshot) so the compiler can target a scope as a
+component's data binding directly. It nests (`child`/`root`), and carries the
+capability surface as methods so a scope is a passable value:
+`<Child parentScope={scope} />`.
+
+Capabilities route where the scope's changes go: `record()` to an undo journal,
+`persist()` to durable storage, `broadcast()` to peers — declared once, then
+`undo`/`redo` act on a recorded scope. `id` is the scope's identity for the
+boundary-crossing capabilities — `persist()` defaults its key to it. `scope()` is
+the ONLY public entry; everything else is a method reached through it (the
+`history`/`persist`/`sync` helpers it composes are internal).
+*/
+export type Scope = {
+    readonly id: string
+    readonly parent: Scope | undefined
+    /* data — mirrors Doc */
+    read: <T>(path: string) => T
+    replace: (path: string, value: unknown) => void
+    add: (path: string, value: unknown) => void
+    remove: (path: string) => void
+    apply: (patch: Patch) => void
+    cell: <T>(path: string) => Cell<T>
+    derive: <T>(path: string, compute: () => T) => () => T
+    snapshot: () => unknown
+    /* the `.value`-cell signal forms, reachable only through a scope (the standalone
+       `state`/`linked`/`computed` are no longer exported): a writable `state(x, transform)`
+       gate, a reseeding `linked`, and the read-only `computed(compute)`. A writable
+       computed does not exist — that write is expressed at the binding (`bind:value={{
+       get, set }}`). The serializable computed doc slot is `derive` above. */
+    state: typeof state
+    linked: typeof linked
+    computed: typeof computed
+    /* tree */
+    child: (initial?: unknown) => Scope
+    root: () => Scope
+    /* capabilities — enable where the scope's changes go */
+    record: (options?: { limit?: number }) => void
+    persist: (key?: string) => void
+    broadcast: (transport: SyncTransport) => void
+    /* undo/redo — act on a recorded scope */
+    undo: () => void
+    redo: () => void
+    canUndo: () => boolean
+    canRedo: () => boolean
+    /* lifetime */
+    dispose: () => void
+}

package/src/lib/ui/types/SyncTransport.ts

@@ -0,0 +1,13 @@
+import type { Patch } from '../runtime/types/Patch.ts'
+
+/*
+The bidirectional channel `sync` rides: `send` publishes a local patch to peers,
+`subscribe` delivers patches from peers (returning an unsubscribe). Deliberately
+minimal and patch-shaped — an app adapts it to a `socket` (publish ⇒ `send`, the
+socket's frames ⇒ `subscribe`), and a test adapts it to an in-memory hub. A patch
+is already the serializable wire unit, so nothing else is needed.
+*/
+export type SyncTransport = {
+    send: (patch: Patch) => void
+    subscribe: (onPatch: (patch: Patch) => void) => () => void
+}

package/src/preload.ts

@@ -1,4 +1,4 @@
-// @readme plumbing
+// @documentation plumbing
 import { plugin } from 'bun'
 import { abideResolverPlugin } from './abideResolverPlugin.ts'
 import { abideUiPlugin } from './lib/ui/compile/abideUiPlugin.ts'

package/src/lib/shared/toScopeSet.ts

@@ -1,4 +0,0 @@
-/* Normalizes a scope option (one tag or many) to a Set for O(1) membership. */
-export function toScopeSet(scope: string | string[]): Set<string> {
-    return new Set(typeof scope === 'string' ? [scope] : scope)
-}

package/src/lib/ui/derived.ts

@@ -1,49 +0,0 @@
-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 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, 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
-       once and then abandoned never re-runs, so absent this it would sit in its
-       source signals' subscriber lists forever — re-marked dirty on every write to
-       them — for the source's lifetime. Outside a scope it owns its own life (no-op). */
-    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/doc.ts

@@ -1,15 +0,0 @@
-import { createDoc } from './runtime/createDoc.ts'
-import type { Doc } from './runtime/types/Doc.ts'
-
-/*
-Creates a reactive document: a single immutable, serializable tree addressed by
-path, where every change is a patch. `doc.read(path)` is path-granular reactive
-read; `doc.replace/add/remove` emit patches that wake only the readers whose
-paths the change touched. This is the substrate the whole framework stands on —
-deep reactivity, resumability, undo, and sync all reduce to "a patch over a
-path", so they share one mechanism instead of being bolted on.
-*/
-// @readme plumbing
-export function doc(initial: unknown = {}): Doc {
-    return createDoc(initial)
-}