@statorjs/stator 1.0.0

package/src/client/runtime.ts

@@ -0,0 +1,246 @@
+/**
+ * stator client runtime.
+ *
+ * Responsibilities:
+ *   1. Attach delegated event listeners on document.body for a fixed set of
+ *      DOM event types. On fire, look for the nearest ancestor carrying
+ *      `data-event-<type>="..."` and POST the JSON descriptor to /__events.
+ *   2. Intercept form submissions: when the form has a `data-event-submit`
+ *      descriptor, follow the descriptor path; otherwise POST the form's
+ *      FormData to its `action` URL.
+ *   3. Apply patches in the response according to the wire protocol — see
+ *      WIRE.md. Two target kinds (slot, element) × three ops (text, html,
+ *      attr) currently implemented.
+ *   4. Apply directives (navigate, reload, etc.) after patches.
+ *   5. Dispatch `stator:*` CustomEvents on `window` at protocol edges so
+ *      inspectors and devtools can observe the traffic without monkey-
+ *      patching. See "Observability hooks" below for the contract.
+ */
+
+import { applyDirectives, applyPatches } from '../wire/apply.ts'
+import type { WireEnvelope } from '../wire/index.ts'
+import { clientId } from './client-id.ts'
+
+const EVENT_TYPES = ['click', 'submit', 'change', 'input'] as const
+
+/* ------------------------------------------------------------------ */
+/* Observability hooks                                                 */
+/* ------------------------------------------------------------------ */
+
+function emit(name: string, detail: unknown): void {
+  window.dispatchEvent(new CustomEvent(name, { detail }))
+}
+
+/* ------------------------------------------------------------------ */
+/* Event delegation + dispatch                                         */
+/* ------------------------------------------------------------------ */
+
+function init(): void {
+  for (const type of EVENT_TYPES) {
+    document.body.addEventListener(type, handleEvent)
+  }
+  initLiveChannel()
+}
+
+function initLiveChannel(): void {
+  const meta = document.querySelector('meta[name="stator-live"][content="true"]')
+  if (!meta) return
+
+  const routeKey = `GET ${location.pathname}${location.search}`
+  const url = `/__sse?route=${encodeURIComponent(routeKey)}&client=${encodeURIComponent(clientId)}`
+  const sse = new EventSource(url, { withCredentials: true })
+
+  let everOpened = false
+  sse.addEventListener('open', () => {
+    if (everOpened) {
+      // Reconnect — reload rather than risk stale state.
+      location.reload()
+      return
+    }
+    everOpened = true
+  })
+
+  sse.addEventListener('message', (e) => {
+    let data: WireEnvelope
+    try {
+      data = JSON.parse(e.data)
+    } catch (err) {
+      console.error('stator: malformed SSE message', err)
+      return
+    }
+    if (data.patches) {
+      emit('stator:patches-received', {
+        patches: data.patches,
+        source: 'sse',
+        timestamp: Date.now(),
+      })
+      applyPatches(data.patches)
+    }
+    if (data.directives && data.directives.length > 0) {
+      applyDirectives(data.directives)
+    }
+  })
+
+  sse.addEventListener('error', () => {
+    if (sse.readyState === EventSource.CLOSED) {
+      console.warn('stator: SSE permanently closed')
+    }
+  })
+}
+
+function handleEvent(e: Event): void {
+  const target = e.target as Element | null
+  if (!target) return
+
+  // Form submissions: prefer data-event-submit descriptor if present,
+  // otherwise intercept based on form's action attribute.
+  if (e.type === 'submit') {
+    const form = target.closest('form') as HTMLFormElement | null
+    if (form) {
+      const descriptorAttr = form.getAttribute('data-event-submit')
+      if (descriptorAttr) {
+        e.preventDefault()
+        let descriptor: { machine: string; event: { type: string } }
+        try {
+          descriptor = JSON.parse(descriptorAttr)
+        } catch {
+          console.error('stator: malformed event descriptor on form', form, descriptorAttr)
+          return
+        }
+        void dispatchEvent(descriptor)
+        return
+      }
+      // Opt-in interception via `data-stator-enhance`. Plain forms without
+      // the attribute submit normally — they may legitimately point at
+      // third-party endpoints, or want browser-default behavior for SEO,
+      // accessibility, or focus management. Auto-intercepting every form
+      // would silently change HTML semantics in ways the developer never
+      // asked for.
+      if (
+        form.hasAttribute('data-stator-enhance') &&
+        form.action &&
+        form.method.toLowerCase() === 'post'
+      ) {
+        e.preventDefault()
+        void submitForm(form)
+        return
+      }
+      // Fall through: nothing to intercept, browser default submit.
+      return
+    }
+  }
+
+  const attrName = `data-event-${e.type}`
+  const el = target.closest(`[${attrName}]`)
+  if (!el) return
+  const raw = el.getAttribute(attrName)
+  if (!raw) return
+
+  let descriptor: { machine: string; event: { type: string } }
+  try {
+    descriptor = JSON.parse(raw)
+  } catch {
+    console.error('stator: malformed event descriptor on', el, raw)
+    return
+  }
+
+  void dispatchEvent(descriptor)
+}
+
+async function dispatchEvent(descriptor: {
+  machine: string
+  event: { type: string }
+}): Promise<void> {
+  const routeKey = `GET ${location.pathname}${location.search}`
+
+  emit('stator:event-sent', {
+    machine: descriptor.machine,
+    event: descriptor.event,
+    routeKey,
+    timestamp: Date.now(),
+  })
+
+  const startedAt = performance.now()
+  let res: Response
+  try {
+    res = await fetch('/__events', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        'X-Stator-Route': routeKey,
+        'X-Stator-Client': clientId,
+      },
+      credentials: 'same-origin',
+      body: JSON.stringify(descriptor),
+    })
+  } catch (err) {
+    console.error('stator: network error during dispatch', err)
+    return
+  }
+  if (!res.ok) {
+    console.error('stator: event POST failed', res.status, await res.text())
+    return
+  }
+  await applyEnvelopeFromResponse(res, startedAt, 'post')
+}
+
+/**
+ * Submit a plain HTML form to its action URL with FormData. Signals
+ * `Accept: application/json` so the server returns the directives envelope
+ * even though the form looks like a normal browser submission.
+ */
+async function submitForm(form: HTMLFormElement): Promise<void> {
+  const formData = new FormData(form)
+  const startedAt = performance.now()
+  let res: Response
+  try {
+    res = await fetch(form.action, {
+      method: 'POST',
+      headers: { Accept: 'application/json' },
+      credentials: 'same-origin',
+      body: formData,
+    })
+  } catch (err) {
+    console.error('stator: network error during form submit', err)
+    return
+  }
+  if (!res.ok) {
+    console.error('stator: form submit failed', res.status, await res.text())
+    return
+  }
+  await applyEnvelopeFromResponse(res, startedAt, 'post')
+}
+
+async function applyEnvelopeFromResponse(
+  res: Response,
+  startedAt: number,
+  source: 'post' | 'sse',
+): Promise<void> {
+  let data: WireEnvelope
+  try {
+    data = await res.json()
+  } catch (err) {
+    console.error('stator: malformed response', err)
+    return
+  }
+  const durationMs = Math.round(performance.now() - startedAt)
+  if (data.patches) {
+    emit('stator:patches-received', {
+      patches: data.patches,
+      source,
+      durationMs,
+      timestamp: Date.now(),
+    })
+    applyPatches(data.patches)
+  }
+  if (data.directives && data.directives.length > 0) {
+    applyDirectives(data.directives)
+  }
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', init)
+} else {
+  init()
+}

package/src/client/use.ts

@@ -0,0 +1,119 @@
+import {
+  type AnyActor,
+  type AnyMachineDef,
+  createActor,
+  type MachineDef,
+  type Snapshot,
+} from '../engine/index.ts'
+
+const CLIENT_HELPERS = {
+  reads: new Proxy(
+    {},
+    {
+      get(_t, prop: string) {
+        throw new Error(`stator: client machines have no reads (accessed reads.${prop})`)
+      },
+    },
+  ),
+} as never
+
+/**
+ * The client-side reactive handle for a machine. Returned by `use()`, held as a
+ * class field (`qty = use(Qty)`). Exposes:
+ *   - each selector / context key as a live property (read through the actor's
+ *     current snapshot on every access — the client mirror of the server
+ *     instance proxy). This is what `bind:text={qty.count}` reads.
+ *   - `send(event)` to drive transitions.
+ *   - the underlying actor (non-enumerable) for the binding loop to subscribe.
+ */
+export interface ClientInstance {
+  send(event: { type: string; [k: string]: unknown } | string): void
+  /** @internal — the actor a binding subscribes to. */
+  readonly __actor: AnyActor
+}
+
+/** An actor plus an optional deferred seed thunk — evaluated at the element's
+ *  connect (when attributes are available), not at construction. */
+export interface CollectedActor {
+  actor: AnyActor
+  seedThunk?: () => Record<string, unknown>
+}
+
+/** Active collector: `use()` registers its actor here during element
+ *  construction, so `StatorElement` can start/seed/stop them on connect/disconnect.
+ *  A stack supports nested construction (rare, but correct). */
+const collectors: CollectedActor[][] = []
+
+export function pushCollector(): CollectedActor[] {
+  const bucket: CollectedActor[] = []
+  collectors.push(bucket)
+  return bucket
+}
+
+export function popCollector(): void {
+  collectors.pop()
+}
+
+/**
+ * Instantiate a client machine, owned by the constructing element. The optional
+ * seed sets initial context (the narrow hydration seed). A plain object is
+ * applied eagerly; a **thunk** `() => ({...})` is deferred to the element's
+ * connect — required when the seed reads `this.attrs`, since attributes aren't
+ * available at construction (the custom-element upgrade-timing rule).
+ */
+export function use(
+  def: MachineDef,
+  seed?: Record<string, unknown> | (() => Record<string, unknown>),
+): ClientInstance {
+  const eager = typeof seed === 'object' ? seed : undefined
+  const snapshot: Snapshot<object> | undefined = eager
+    ? {
+        value: [def.initial],
+        context: { ...(def.context as object), ...eager },
+      }
+    : undefined
+  const actor = createActor(def as AnyMachineDef, { snapshot })
+
+  // Register with the element under construction so its lifecycle owns the actor.
+  const bucket = collectors[collectors.length - 1]
+  if (bucket)
+    bucket.push({
+      actor,
+      seedThunk: typeof seed === 'function' ? seed : undefined,
+    })
+
+  const inst = Object.create(null) as Record<string | symbol, unknown>
+
+  // Selectors + context keys as live getters reading the current snapshot.
+  const selectorNames = Object.keys(def.selectors)
+  const contextNames = Object.keys(def.context as object)
+  for (const key of new Set([...selectorNames, ...contextNames])) {
+    Object.defineProperty(inst, key, {
+      enumerable: true,
+      get: () => {
+        const ctx = actor.getSnapshot().context
+        const sel = def.selectors[key]
+        // Client machines have no cross-machine reads; pass a stub so the
+        // shared SelectorMap signature holds.
+        return sel ? sel(ctx, CLIENT_HELPERS) : (ctx as Record<string, unknown>)[key]
+      },
+    })
+  }
+
+  Object.defineProperty(inst, 'send', {
+    enumerable: false,
+    value: (event: { type: string; [k: string]: unknown } | string) =>
+      actor.send(typeof event === 'string' ? ({ type: event } as never) : (event as never)),
+  })
+  Object.defineProperty(inst, '__actor', {
+    enumerable: false,
+    get: () => actor,
+  })
+
+  return inst as unknown as ClientInstance
+}
+
+/** Extract the actor from a `use()` instance (for the binding loop). */
+export function actorOf(inst: ClientInstance): AnyActor {
+  return inst.__actor
+}

package/src/compiler/client-emit.ts

@@ -0,0 +1,180 @@
+import ts from 'typescript'
+import type { ClientDirective, ClientElement } from './client-script.ts'
+import { CompileError } from './diagnostics.ts'
+
+/**
+ * Phase 3b stage 5 — emit the client entry module for a client component: the
+ * author's `<script>` (with auto-injected primitives) plus a generated subclass
+ * whose `setup()` wires the collected directives, then `defineElement`.
+ *
+ * Member references in template expressions (`qty.count`, `inc`) are class
+ * members, so they're rewritten to `this.<member>` inside the generated setup().
+ * A subclass — rather than AST surgery on the author's class — keeps the user
+ * class as written; the subclass overrides `setup()`.
+ */
+
+const PRIMITIVES =
+  "import { StatorElement, defineElement, use, machine, bind, effect, dispatch } from '@statorjs/stator/client'"
+
+export interface EmitClientInput {
+  /** The author's `<script>` source. */
+  script: string
+  element: ClientElement
+  directives: ClientDirective[]
+  /** All class member names (fields + methods) for `this.` rewriting. */
+  members: Set<string>
+}
+
+export function emitClientModule(input: EmitClientInput): string {
+  const { script, element, directives, members } = input
+  const impl = `__${element.className}Impl`
+
+  // Group directives by node marker (one querySelector per marked element).
+  const byMarker = new Map<string, ClientDirective[]>()
+  for (const d of directives) {
+    const list = byMarker.get(d.marker) ?? []
+    list.push(d)
+    byMarker.set(d.marker, list)
+  }
+
+  const lines: string[] = []
+  let i = 0
+  for (const [marker, group] of byMarker) {
+    const node = `n${i++}`
+    lines.push(`    const ${node} = this.querySelector('[data-b="${marker}"]')`)
+    lines.push(`    if (${node}) {`)
+    for (const d of group) lines.push(`      ${wireDirective(node, d, members)}`)
+    lines.push('    }')
+  }
+
+  return [
+    PRIMITIVES,
+    '',
+    stripClientPrimitiveImports(script).trim(),
+    '',
+    `class ${impl} extends ${element.className} {`,
+    '  setup() {',
+    ...lines,
+    '  }',
+    '}',
+    `defineElement(${impl}, ${JSON.stringify(element.tag)})`,
+    '',
+  ].join('\n')
+}
+
+function wireDirective(node: string, d: ClientDirective, members: Set<string>): string {
+  if (d.kind === 'on') {
+    const handler = emitHandler(d.expr, members)
+    return `${node}.addEventListener(${JSON.stringify(d.event)}, ${handler})`
+  }
+  // bind:
+  const target = d.target ?? 'text'
+  const thunk = `() => (${rewriteMembers(d.expr, members)})`
+  const deps = `[${d.deps.map((dep) => `this.${dep}`).join(', ')}]`
+
+  // value / checked are TWO-WAY: state→DOM (below) PLUS a DOM→state listener
+  // that `@set`s the bound context key. The expression must be a settable
+  // `<actor>.<key>` path (a derived selector can't be assigned).
+  if (target === 'value' || target === 'checked') {
+    const path = parseTwoWayPath(d.expr)
+    if (!path) {
+      throw new CompileError(
+        `stator: bind:${target}={${d.expr}} must bind to a settable context path ` +
+          `like \`actor.key\` (a derived value can't be two-way bound).`,
+      )
+    }
+    const writer = emitWriter(node, target)
+    const read = target === 'checked' ? `${node}.checked` : `${node}.value`
+    const guard = target === 'value' ? `if (e.isComposing) return; ` : ''
+    const setter =
+      `${node}.addEventListener(${JSON.stringify(target === 'value' ? 'input' : 'change')}, (e) => { ` +
+      `${guard}this.${path.actor}.send({ type: '@set', key: ${JSON.stringify(path.key)}, value: ${read} }) })`
+    return `this.track(bind(${deps}, ${thunk}, ${writer}));\n      ${setter}`
+  }
+
+  const writer = emitWriter(node, target)
+  return `this.track(bind(${deps}, ${thunk}, ${writer}))`
+}
+
+/** Parse a two-way bind expression `actor.key` into its parts; null if it isn't
+ *  a simple single-level member access (not assignable). */
+function parseTwoWayPath(expr: string): { actor: string; key: string } | null {
+  const m = expr.trim().match(/^([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)$/)
+  return m ? { actor: m[1]!, key: m[2]! } : null
+}
+
+/** on: handler — a bare method reference becomes `(e) => this.m(e)`; any other
+ *  expression is used directly (with member references rewritten). */
+function emitHandler(expr: string, members: Set<string>): string {
+  const t = expr.trim()
+  if (/^[A-Za-z_$][\w$]*$/.test(t) && members.has(t)) {
+    return `(e) => this.${t}(e)`
+  }
+  return rewriteMembers(expr, members)
+}
+
+function emitWriter(node: string, target: string): string {
+  switch (target) {
+    case 'text':
+      return `(v) => { ${node}.textContent = v == null ? '' : String(v) }`
+    case 'html':
+      return `(v) => { ${node}.innerHTML = v == null ? '' : String(v) }`
+    case 'value':
+      // Loop-break: only write when the DOM differs, so the echo from the user's
+      // own keystroke no-ops and the caret is preserved.
+      return `(v) => { const s = v == null ? '' : String(v); if (${node}.value !== s) ${node}.value = s }`
+    case 'disabled':
+    case 'hidden':
+    case 'checked':
+      return `(v) => { if (${node}.${target} !== !!v) ${node}.${target} = !!v }`
+    default:
+      // arbitrary attribute
+      return `(v) => { if (v == null || v === false) ${node}.removeAttribute(${JSON.stringify(target)}); else ${node}.setAttribute(${JSON.stringify(target)}, v === true ? '' : String(v)) }`
+  }
+}
+
+/** Remove any author import from `@statorjs/stator/client` — those primitives are
+ *  auto-injected (the `PRIMITIVES` line), so an author's habit-import would be a
+ *  duplicate binding. Server machine imports (for `dispatch`) are untouched. */
+function stripClientPrimitiveImports(script: string): string {
+  return script.replace(
+    /^\s*import\s+\{[^}]*\}\s+from\s+['"]@statorjs\/stator\/client['"]\s*;?\s*$/gm,
+    '',
+  )
+}
+
+/** Prefix class-member identifiers in an expression with `this.` (skipping the
+ *  property-name side of member access, so `qty.count` → `this.qty.count`). */
+export function rewriteMembers(expr: string, members: Set<string>): string {
+  const sf = ts.createSourceFile(
+    'e.ts',
+    `(${expr})`,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  )
+  const repls: Array<[start: number, end: number]> = []
+  const visit = (n: ts.Node): void => {
+    if (ts.isIdentifier(n)) {
+      const isPropName = n.parent && ts.isPropertyAccessExpression(n.parent) && n.parent.name === n
+      // skip shorthand/binding contexts where `this.` would be invalid
+      const isDeclName =
+        n.parent &&
+        (ts.isParameter(n.parent) || ts.isBindingElement(n.parent)) &&
+        n.parent.name === n
+      if (!isPropName && !isDeclName && members.has(n.text)) {
+        repls.push([n.getStart(sf), n.getEnd()])
+      }
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(sf)
+
+  // `(${expr})` adds a leading `(` (offset 1). Strip it back out by slicing.
+  let text = `(${expr})`
+  repls.sort((a, b) => b[0] - a[0])
+  for (const [start, end] of repls) {
+    text = `${text.slice(0, start)}this.${text.slice(start, end)}${text.slice(end)}`
+  }
+  return text.slice(1, -1) // remove the wrapping parens
+}