@statorjs/stator 1.0.0

package/src/wire/apply.ts

@@ -0,0 +1,103 @@
+/**
+ * Client-side appliers for the wire protocol — the one implementation of
+ * "given patches/directives, mutate the DOM". Used by both the page runtime
+ * (client/runtime.ts) and island dispatch (client/dispatch.ts), so the two
+ * paths can't drift.
+ *
+ * Observability: every applied patch/directive dispatches a `stator:*`
+ * CustomEvent on `window` (the inspector's contract), regardless of which
+ * path applied it.
+ */
+import type { Directive, Patch } from './index.ts'
+
+function emit(name: string, detail: unknown): void {
+  window.dispatchEvent(new CustomEvent(name, { detail }))
+}
+
+export function resolveTarget(target: { kind: 'slot' | 'element'; id: string }): Element | null {
+  if (target.kind === 'slot') {
+    return document.querySelector(`[data-slot="${target.id}"]`)
+  }
+  return document.querySelector(`[data-stator-id="${target.id}"]`)
+}
+
+export function applyPatches(patches: Patch[]): void {
+  for (const patch of patches) {
+    const element = resolveTarget(patch.target)
+    if (!element) {
+      // A missing target means this DOM diverged from server truth (stale
+      // non-live page, or client code removed server-owned nodes). Skipping
+      // is safe — arm/key-scoped slot ids guarantee a patch can't land on
+      // the wrong content — but the divergence is worth surfacing.
+      console.warn(
+        `stator: patch target ${patch.target.kind} "${patch.target.id}" not in DOM — skipped`,
+      )
+      continue
+    }
+    if (element) {
+      if (patch.op === 'text') element.textContent = patch.value
+      else if (patch.op === 'html') element.innerHTML = patch.value
+      else if (patch.op === 'attr') {
+        if (patch.value === null) element.removeAttribute(patch.name)
+        else element.setAttribute(patch.name, patch.value)
+      }
+      // Keyed-list ops address element children by index, sequentially: each
+      // op sees the DOM as left by the previous one (see wire/index.ts).
+      else if (patch.op === 'insert') {
+        const tpl = document.createElement('template')
+        tpl.innerHTML = patch.value
+        element.insertBefore(tpl.content, element.children[patch.index] ?? null)
+      } else if (patch.op === 'remove') {
+        element.children[patch.index]?.remove()
+      } else if (patch.op === 'move') {
+        const node = element.children[patch.from]
+        if (node) {
+          node.remove()
+          element.insertBefore(node, element.children[patch.to] ?? null)
+        }
+      }
+    }
+    emit('stator:patch-applied', { patch, element, timestamp: Date.now() })
+  }
+}
+
+export function applyDirectives(directives: Directive[]): void {
+  for (const directive of directives) {
+    emit('stator:directive-applied', { directive, timestamp: Date.now() })
+    switch (directive.type) {
+      case 'navigate':
+        location.href = directive.to
+        return // stop processing further directives; we're leaving
+      case 'reload':
+        location.reload()
+        return
+      case 'push-url':
+        history.pushState({}, '', directive.to)
+        break
+      case 'replace-url':
+        history.replaceState({}, '', directive.to)
+        break
+      case 'focus': {
+        const el = resolveTarget(directive.target)
+        if (el && 'focus' in el && typeof (el as HTMLElement).focus === 'function') {
+          ;(el as HTMLElement).focus()
+        }
+        break
+      }
+      case 'scroll': {
+        const el = resolveTarget(directive.target)
+        if (el && 'scrollIntoView' in el) {
+          ;(el as HTMLElement).scrollIntoView({
+            behavior: directive.behavior ?? 'auto',
+          })
+        }
+        break
+      }
+      case 'event':
+        emit(directive.name, directive.detail)
+        break
+      default:
+        console.error('stator: unknown directive type', directive)
+    }
+  }
+}

package/src/wire/index.ts

@@ -0,0 +1,67 @@
+/**
+ * The wire protocol — the single source of truth for every shape that crosses
+ * the server/client boundary. Documented in WIRE.md; produced by
+ * `server/recompute.ts` and the API-route envelope; consumed by the client
+ * runtime and island dispatch via `wire/apply.ts`.
+ *
+ * This module is types-only (no DOM, no server imports) so both sides can
+ * import it. Keep it that way: a new patch op or directive is added HERE and
+ * nowhere else — producers and appliers then fail to typecheck until they
+ * handle it.
+ */
+
+/** Slot positions (data-slot) vs element identities (data-stator-id) — the
+ *  two addressing dimensions, orthogonal to the op. */
+export type SlotTarget = { kind: 'slot'; id: string }
+export type ElementTarget = { kind: 'element'; id: string }
+export type PatchTarget = SlotTarget | ElementTarget
+
+/**
+ * Wire patch. Addressing is a discriminated `target` and the op describes
+ * what to do at that target.
+ *
+ * The keyed-list ops (`insert`/`remove`/`move`) address element children of a
+ * list slot **by index, sequentially**: each op's indices refer to the DOM
+ * state after every preceding op in the batch has been applied. The server
+ * emits them from a replay simulation, so a batch is deterministic.
+ *
+ * Reserved future ops (not yet emitted, documented for the wire spec):
+ *   - 'attr-add' / 'attr-remove' on element targets (per-class toggles)
+ *   - 'prop' on element targets (IDL property writes that have no attr)
+ */
+export type Patch =
+  | { target: SlotTarget; op: 'text'; value: string }
+  | { target: SlotTarget; op: 'html'; value: string }
+  /** `value: null` removes the attribute — boolean attributes (disabled,
+   *  checked, open, …) toggle by presence, so the wire must express absence. */
+  | { target: ElementTarget; op: 'attr'; name: string; value: string | null }
+  | { target: SlotTarget; op: 'insert'; index: number; value: string }
+  | { target: SlotTarget; op: 'remove'; index: number }
+  | { target: SlotTarget; op: 'move'; from: number; to: number }
+
+/** A client directive describing a side effect the client should perform
+ *  after applying patches. See the response-directives spec for the full list. */
+export type Directive =
+  | { type: 'navigate'; to: string }
+  | { type: 'reload' }
+  | { type: 'push-url'; to: string }
+  | { type: 'replace-url'; to: string }
+  | { type: 'focus'; target: { kind: 'slot' | 'element'; id: string } }
+  | {
+      type: 'scroll'
+      target: { kind: 'slot' | 'element'; id: string }
+      behavior?: 'smooth' | 'auto'
+    }
+  | { type: 'event'; name: string; detail?: unknown }
+
+/** The JSON envelope carried by `/__events` responses, API-route responses,
+ *  and SSE messages. */
+export interface WireEnvelope {
+  patches?: Patch[]
+  directives?: Directive[]
+  /** POST /__events only: whether the event committed a transition (any
+   *  machine touched). Distinguishes a guard-dropped event (HTTP 200, zero
+   *  patches, committed: false) from a committed one that happened to patch
+   *  nothing on this page. */
+  committed?: boolean
+}