@statorjs/stator 1.0.0

package/src/template/conditional.ts

@@ -0,0 +1,166 @@
+import {
+  allocSlotId,
+  type ErasedSelector,
+  keyToken,
+  popListScope,
+  type RenderState,
+  registerBinding,
+  requireCurrentRenderState,
+  type SlotId,
+  unregisterBindingsForScope,
+} from '../server/render-context.ts'
+import { isReadResult, type ReadResult } from './read.ts'
+import { type HtmlFragment, isHtmlFragment } from './types.ts'
+
+/**
+ * A conditional fragment. Same wire shape as EachResult — a position-marker
+ * span whose innerHTML is swapped on key change. When inactive, the span has
+ * no inner content, so the conditional body's DOM is genuinely absent (not
+ * hidden via CSS).
+ */
+export interface BranchResult {
+  readonly __isBranchResult: true
+  readonly html: string
+  readonly slotId: SlotId
+}
+
+export function isBranchResult(v: unknown): v is BranchResult {
+  return (
+    typeof v === 'object' && v !== null && (v as Record<string, unknown>).__isBranchResult === true
+  )
+}
+
+/**
+ * Render the body for a branch result. Mirrors renderListBody: clears any
+ * existing descendant bindings under this slot, pushes a child scope, and
+ * runs the renderer. Returns the inner HTML (empty when renderer is null).
+ *
+ * Descendant slot ids are scoped by the ARM (`s2:btrue:s0`,
+ * `s2:bconfirmed:s0`) — the branch analogue of keyed rows' key scoping. Two
+ * arms of one branch never share slot ids, so a patch computed for one arm
+ * can never land inside the other's DOM (the stale-page hazard: a non-live
+ * page showing arm A while the server diffs arm B must skip, not miswrite).
+ */
+export function renderBranchBody(
+  state: RenderState,
+  slotId: SlotId,
+  armKey: unknown,
+  renderer: (() => HtmlFragment) | null,
+): string {
+  unregisterBindingsForScope(state, slotId)
+  if (!renderer) return ''
+  state.scopeStack.push({ prefix: `${slotId}:b${keyToken(String(armKey))}`, counter: 0 })
+  try {
+    const fragment = renderer()
+    if (!isHtmlFragment(fragment)) {
+      throw new Error('stator: when()/match() renderer must return an html`...` result')
+    }
+    return fragment.html
+  } finally {
+    popListScope(state)
+  }
+}
+
+/**
+ * Render `fn()` when `cond` is truthy; otherwise render nothing. Re-renders
+ * only when the truthiness of `cond` flips — toggling between two truthy
+ * values does not cause a swap.
+ */
+export function when<T>(cond: T | ReadResult<T>, fn: () => HtmlFragment): BranchResult {
+  const state = requireCurrentRenderState()
+
+  let value: T
+  let slotId: SlotId
+  let machineName: string | null = null
+  let selector: ErasedSelector | null = null
+
+  if (isReadResult(cond)) {
+    value = cond.value as T
+    slotId = cond.slotId
+    machineName = cond.machineName
+    selector = cond.selector
+  } else {
+    value = cond
+    slotId = allocSlotId(state)
+  }
+
+  const keyFn = (v: unknown): boolean => !!v
+  const renderFn = (v: unknown): (() => HtmlFragment) | null => (v ? fn : null)
+
+  const activeKey = keyFn(value)
+  const innerHtml = renderBranchBody(state, slotId, activeKey, renderFn(value))
+
+  if (machineName && selector) {
+    registerBinding(state, {
+      slotId,
+      machineName,
+      selector,
+      lastValue: value,
+      kind: 'branch',
+      branchKeyFn: keyFn,
+      branchRenderFn: renderFn,
+      lastBranchKey: activeKey,
+    })
+  }
+
+  // `display: contents` so the wrapper span doesn't break the surrounding
+  // element's layout (grid/flex) — see each.ts for the same rationale.
+  const html = `<span data-slot="${slotId}" data-branch="true" style="display:contents">${innerHtml}</span>`
+  return { __isBranchResult: true, html, slotId }
+}
+
+/**
+ * Render the body for the matching case key, or nothing if no case matches.
+ * Re-renders only when the key changes — toggling other context fields
+ * doesn't cause a swap.
+ *
+ * Type-safe when `key` is a `ReadResult<TKey extends string>`: cases must be
+ * keyed by the same literal union.
+ */
+export function match<TKey extends string>(
+  key: TKey | ReadResult<TKey>,
+  cases: Partial<Record<TKey, () => HtmlFragment>>,
+): BranchResult {
+  const state = requireCurrentRenderState()
+
+  let value: TKey
+  let slotId: SlotId
+  let machineName: string | null = null
+  let selector: ErasedSelector | null = null
+
+  if (isReadResult(key)) {
+    value = key.value as TKey
+    slotId = key.slotId
+    machineName = key.machineName
+    selector = key.selector
+  } else {
+    value = key
+    slotId = allocSlotId(state)
+  }
+
+  const keyFn = (v: unknown): unknown => v
+  const renderFn = (v: unknown): (() => HtmlFragment) | null => {
+    const fn = (cases as Record<string, (() => HtmlFragment) | undefined>)[String(v)]
+    return fn ?? null
+  }
+
+  const innerHtml = renderBranchBody(state, slotId, keyFn(value), renderFn(value))
+
+  if (machineName && selector) {
+    registerBinding(state, {
+      slotId,
+      machineName,
+      selector,
+      lastValue: value,
+      kind: 'branch',
+      branchKeyFn: keyFn,
+      branchRenderFn: renderFn,
+      lastBranchKey: keyFn(value),
+    })
+  }
+
+  // `display: contents` so the wrapper span doesn't break the surrounding
+  // element's layout (grid/flex) — see each.ts for the same rationale.
+  const html = `<span data-slot="${slotId}" data-branch="true" style="display:contents">${innerHtml}</span>`
+  return { __isBranchResult: true, html, slotId }
+}

package/src/template/directives/core.ts

@@ -0,0 +1,58 @@
+import type { ElementId } from '../../server/render-context.ts'
+
+export interface DirectiveContext<TArg> {
+  /** The synthetic id of the element this directive is attached to. */
+  elementId: ElementId
+  /** The modifier portion of the directive, e.g. 'click' in `on('click', ...)`. */
+  modifier: string
+  /** The argument passed to the directive, e.g. the handler function. */
+  arg: TArg
+  /** Adds an attribute to the element (e.g. `data-event-click="..."`). */
+  addAttribute(name: string, value: string): void
+  /**
+   * Records a cleanup function. Unused server-side in the POC; reserved
+   * for V1 directives that bind server-side timers / SSE.
+   */
+  registerCleanup(fn: () => void): void
+}
+
+export interface DirectiveDefinition<TArg> {
+  name: string
+  apply(ctx: DirectiveContext<TArg>): void
+}
+
+export interface Directive<TArg> extends DirectiveDefinition<TArg> {
+  readonly __isStatorDirective: true
+}
+
+export function defineDirective<TArg>(def: DirectiveDefinition<TArg>): Directive<TArg> {
+  return { ...def, __isStatorDirective: true }
+}
+
+export interface DirectiveInvocation<TArg = unknown> {
+  readonly __isStatorDirectiveInvocation: true
+  directive: Directive<TArg>
+  modifier: string
+  arg: TArg
+}
+
+export function isDirectiveInvocation(v: unknown): v is DirectiveInvocation {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    (v as Record<string, unknown>).__isStatorDirectiveInvocation === true
+  )
+}
+
+export function invoke<TArg>(
+  directive: Directive<TArg>,
+  modifier: string,
+  arg: TArg,
+): DirectiveInvocation<TArg> {
+  return {
+    __isStatorDirectiveInvocation: true,
+    directive,
+    modifier,
+    arg,
+  }
+}

package/src/template/directives/list-attr.ts

@@ -0,0 +1,183 @@
+import {
+  allocSlotId,
+  type RenderState,
+  registerBinding,
+  requireCurrentRenderState,
+} from '../../server/render-context.ts'
+import { isReadResult, type ReadResult } from '../read.ts'
+import { type DirectiveInvocation, defineDirective, invoke } from './core.ts'
+
+/**
+ * Shared shape for compound-attribute directives (`class:list`, `style:list`).
+ * Each directive owns an entire attribute. Conditional reads appear *inside*
+ * the spec, never alongside literal text — that rule is enforced by html.ts.
+ *
+ * The directive registers one attr binding per unique machine appearing in
+ * the spec; each binding's selector recomposes the full attribute value, so
+ * any machine event that affects the spec emits exactly one patch for the
+ * attribute (and the value always includes every static entry).
+ */
+
+type ConditionalEntry<TValue> = TValue | ReadResult<TValue>
+
+/** Recursive shape accepted by class:list. */
+export type ClassListSpec =
+  | string
+  | false
+  | null
+  | undefined
+  | ReadResult<string | boolean | null | undefined>
+  | Record<string, ConditionalEntry<boolean | null | undefined>>
+  | ClassListSpec[]
+
+/** Recursive shape accepted by style:list. */
+export type StyleListSpec =
+  | string
+  | false
+  | null
+  | undefined
+  | ReadResult<string | null | undefined>
+  | Record<string, ConditionalEntry<string | number | null | undefined>>
+  | StyleListSpec[]
+
+function evalRead<T>(value: ConditionalEntry<T>): T {
+  return isReadResult(value) ? (value.selector(value.instance) as T) : value
+}
+
+function collectMachines(spec: unknown, out: Set<string>): void {
+  if (spec == null || spec === false) return
+  if (typeof spec === 'string') return
+  if (isReadResult(spec)) {
+    out.add(spec.machineName)
+    return
+  }
+  if (Array.isArray(spec)) {
+    for (const item of spec) collectMachines(item, out)
+    return
+  }
+  if (typeof spec === 'object') {
+    for (const v of Object.values(spec)) {
+      if (isReadResult(v)) out.add(v.machineName)
+    }
+  }
+}
+
+function composeClass(spec: ClassListSpec): string {
+  const parts: string[] = []
+  walkClass(spec, parts)
+  return parts.join(' ')
+}
+
+function walkClass(spec: ClassListSpec, out: string[]): void {
+  if (spec == null || spec === false) return
+  if (typeof spec === 'string') {
+    if (spec.length > 0) out.push(spec)
+    return
+  }
+  if (isReadResult(spec)) {
+    const v = spec.selector(spec.instance)
+    if (typeof v === 'string' && v.length > 0) out.push(v)
+    return
+  }
+  if (Array.isArray(spec)) {
+    for (const item of spec) walkClass(item, out)
+    return
+  }
+  if (typeof spec === 'object') {
+    for (const [name, cond] of Object.entries(spec)) {
+      const truthy = evalRead(cond)
+      if (truthy) out.push(name)
+    }
+  }
+}
+
+function composeStyle(spec: StyleListSpec): string {
+  const decls: string[] = []
+  walkStyle(spec, decls)
+  return decls.join('; ')
+}
+
+function walkStyle(spec: StyleListSpec, out: string[]): void {
+  if (spec == null || spec === false) return
+  if (typeof spec === 'string') {
+    const trimmed = spec.trim()
+    if (trimmed.length > 0) out.push(trimmed.replace(/;\s*$/, ''))
+    return
+  }
+  if (isReadResult(spec)) {
+    const v = spec.selector(spec.instance)
+    if (typeof v === 'string' && v.trim().length > 0) {
+      out.push(v.trim().replace(/;\s*$/, ''))
+    }
+    return
+  }
+  if (Array.isArray(spec)) {
+    for (const item of spec) walkStyle(item, out)
+    return
+  }
+  if (typeof spec === 'object') {
+    for (const [prop, raw] of Object.entries(spec)) {
+      const value = evalRead(raw)
+      if (value == null || value === '') continue
+      out.push(`${prop}: ${value}`)
+    }
+  }
+}
+
+/**
+ * Register one attr-binding per unique machine the spec depends on. Each
+ * binding's selector ignores its arg and recomputes the entire attribute
+ * by re-walking the spec — every ReadResult inside re-evaluates its
+ * `.selector(.instance)`, returning fresh state.
+ */
+function bindListAttr<TSpec>(
+  state: RenderState,
+  spec: TSpec,
+  attrName: string,
+  elementId: string,
+  compose: (spec: TSpec) => string,
+): string {
+  const machines = new Set<string>()
+  collectMachines(spec, machines)
+
+  const initial = compose(spec)
+  for (const machineName of machines) {
+    const slotId = allocSlotId(state)
+    registerBinding(state, {
+      slotId,
+      machineName,
+      selector: () => compose(spec),
+      lastValue: initial,
+      kind: 'attr',
+      attrName,
+      parentId: elementId,
+    })
+  }
+  return initial
+}
+
+const classListDirective = defineDirective<ClassListSpec>({
+  name: 'class:list',
+  apply({ elementId, arg, addAttribute }) {
+    const state = requireCurrentRenderState()
+    const initial = bindListAttr(state, arg, 'class', elementId, composeClass)
+    addAttribute('class', initial)
+  },
+})
+
+const styleListDirective = defineDirective<StyleListSpec>({
+  name: 'style:list',
+  apply({ elementId, arg, addAttribute }) {
+    const state = requireCurrentRenderState()
+    const initial = bindListAttr(state, arg, 'style', elementId, composeStyle)
+    addAttribute('style', initial)
+  },
+})
+
+export function classList(spec: ClassListSpec): DirectiveInvocation<ClassListSpec> {
+  return invoke(classListDirective, '', spec)
+}
+
+export function styleList(spec: StyleListSpec): DirectiveInvocation<StyleListSpec> {
+  return invoke(styleListDirective, '', spec)
+}

package/src/template/directives/on.ts

@@ -0,0 +1,22 @@
+import { type EventDescriptor, isEventDescriptor } from '../../server/render-context.ts'
+import { type DirectiveInvocation, defineDirective, invoke } from './core.ts'
+
+type Handler = () => EventDescriptor | undefined
+
+const onDirective = defineDirective<Handler>({
+  name: 'on',
+  apply({ modifier, arg, addAttribute }) {
+    const result = arg()
+    if (!isEventDescriptor(result)) {
+      throw new Error(
+        `stator: on('${modifier}', ...) handler must be exactly one machine.send(...) call. ` +
+          `Multi-statement handlers and arbitrary side effects are not supported in the POC.`,
+      )
+    }
+    addAttribute(`data-event-${modifier}`, JSON.stringify(result))
+  },
+})
+
+export function on(modifier: string, handler: Handler): DirectiveInvocation<Handler> {
+  return invoke(onDirective, modifier, handler)
+}