@statorjs/stator 1.8.0 → 2.0.0

package/src/template/types.ts

@@ -1,15 +1,27 @@
-import type { AnyMachineDef, InstanceOf as SelectorsOf } from '../engine/index.ts'
+import type {
+  AnyMachineDef,
+  EventOf,
+  InstanceOf as SelectorsOf,
+  StateNameOf,
+} from '../engine/index.ts'
 import type { EventDescriptor } from '../server/render-context.ts'
 
 /**
  * The template-facing shape of a machine instance: the engine's selector view
  * (each selector as a property carrying its return type, callable if it returns
- * a function) plus the framework-provided `send` / `state` / `snapshot`.
+ * a function) plus the framework-provided `send` / `state` / `snapshot`. Both
+ * `state` (the state-name union) and `send` (the event union) are typed to the
+ * machine's own def, so `s.state === 'ready'` and `m.send({ type: 'SAVE', … })`
+ * autocomplete and a typo — in the name or the payload — is a compile error.
  */
-export type InstanceOf<TDef extends AnyMachineDef> = SelectorsOf<TDef> & InstanceCommon
+export type InstanceOf<TDef extends AnyMachineDef> = SelectorsOf<TDef> &
+  InstanceCommon<StateNameOf<TDef>, EventOf<TDef>>
 
-export interface InstanceCommon<TStateKey extends string = string> {
-  send(event: { type: string; [k: string]: unknown }): EventDescriptor | undefined
+export interface InstanceCommon<
+  TStateKey extends string = string,
+  TEvent = { type: string; [k: string]: unknown },
+> {
+  send(event: TEvent): EventDescriptor | undefined
   readonly state: TStateKey
   readonly snapshot: unknown
 }

package/src/wire/apply.ts

@@ -8,6 +8,7 @@
  * CustomEvent on `window` (the inspector's contract), regardless of which
  * path applied it.
  */
+import { setAttr } from './attr-value.ts'
 import type { Directive, Patch } from './index.ts'
 import {
   elementAt,
@@ -74,8 +75,7 @@ function applyPatch(
       return null
     }
     if (patch.op === 'text') element.textContent = patch.value
-    else if (patch.value === null) element.removeAttribute(patch.name)
-    else element.setAttribute(patch.name, patch.value)
+    else setAttr(element, patch.name, patch.value)
     return element
   }
 

package/src/wire/attr-value.ts

@@ -0,0 +1,55 @@
+import { isUrlAttribute, safeAttrUrl } from './safe-url.ts'
+
+/**
+ * THE attribute-value contract — one implementation for every tier that
+ * writes an attribute: static render (template/html.ts), the live diff
+ * (server/recompute.ts), the island writer codegen (compiler/client-emit.ts,
+ * via the client re-export), and the wire applier (wire/apply.ts).
+ *
+ * Boolean-absent semantics: `false`/`null`/`undefined` → `null`, meaning the
+ * attribute is ABSENT (`checked={expr}` must be able to render unchecked, and
+ * a static render must agree with what a live patch of the same attribute
+ * does). `true` → present-and-empty. Arrays join with no separator (matching
+ * text interpolation); everything else stringifies.
+ *
+ * History: this contract used to live in four drifting copies, and two of
+ * them disagreed in ways users hit — `checked={false}` rendered
+ * `checked="false"` on the static path, and array values patched as "a,b"
+ * but rendered as "ab". One implementation, so the seams can't disagree.
+ */
+export function attrValue(v: unknown): string | null {
+  if (v === false || v === null || v === undefined) return null
+  if (v === true) return ''
+  return stringifyAttr(v)
+}
+
+function stringifyAttr(v: unknown): string {
+  if (v == null) return ''
+  if (typeof v === 'string') return v
+  if (Array.isArray(v)) return v.map(stringifyAttr).join('')
+  return String(v)
+}
+
+/** The text-position value contract, shared by static render and text
+ *  patches: null/undefined → empty, arrays join with no separator (an
+ *  interpolated list of fragments/strings renders concatenated, not
+ *  comma-joined), everything else stringifies. */
+export function textValue(v: unknown): string {
+  return stringifyAttr(v)
+}
+
+/** Scheme guard for url-bearing attributes (href/src/…): strip a
+ *  javascript:/vbscript: value whether it arrives at first render or through
+ *  a later diff. `null` (attribute-absent) passes through. */
+export function sanitizeAttr(name: string, value: string): string
+export function sanitizeAttr(name: string, value: string | null): string | null
+export function sanitizeAttr(name: string, value: string | null): string | null {
+  if (value === null) return null
+  return isUrlAttribute(name) ? safeAttrUrl(value) : value
+}
+
+/** The DOM half of the contract: `null` removes, a string sets. */
+export function setAttr(el: Element, name: string, value: string | null): void {
+  if (value === null) el.removeAttribute(name)
+  else el.setAttribute(name, value)
+}

package/src/wire/island-markers.ts

@@ -0,0 +1,22 @@
+/**
+ * Island marker formats — the compiler↔island-runtime contract, in one place
+ * so codegen (compiler/lower.ts, compiler/client-emit.ts) and the runtime
+ * (client/bind.ts's bindSlot, the generated querySelector calls) can't drift.
+ *
+ * - ELEMENT markers: `data-b="b<N>"` on an element whose on:/bind:/read()
+ *   attribute wiring the island's setup() attaches. Every occurrence of a
+ *   marker is wired (a marked element inside a `.map()` repeats per row).
+ * - TEXT SLOT markers: an `<!--s<N>-->` comment where a client-machine
+ *   `read()` sat in text position; the runtime materializes one text node
+ *   after each occurrence. The comment's data IS the marker string.
+ */
+
+export const ISLAND_MARKER_ATTR = 'data-b'
+
+export const elementMarker = (i: number): string => `b${i}`
+
+export const slotMarker = (i: number): string => `s${i}`
+
+/** CSS selector for every occurrence of an element marker. */
+export const elementMarkerSelector = (marker: string): string =>
+  `[${ISLAND_MARKER_ATTR}="${marker}"]`