sygnal 5.4.0 → 6.0.0

package/src/extra/timers.ts

@@ -0,0 +1,95 @@
+import {makeReplies} from './replies';
+
+/*
+ * makeTimerDriver() (PLAN-4 GS-7, D114): timers declared per component instance from state,
+ * answered with reply actions (./replies.ts). Registered: `run(App, { TIMER: makeTimerDriver() })`.
+ * The core has no timer code (0 B): it sends a component's `timers` static to the source marked
+ * `__sygnalStatic: 'timers'` (initStatics), stamped with the sender (`__emitterId`).
+ *
+ * - Declaration: `C.timers = (state) => ({ [name]: spec | falsy })`, spec one of
+ *   `{ every: ms, action }`, `{ after: ms, action }`, `{ frame: 'ACTION' }`, each with an
+ *   optional `background: true`.
+ * - Diffed per (sender, name), comparing specs structurally: a new name starts, a removed or
+ *   falsy one stops, a changed spec restarts (an equal one keeps running).
+ * - `every`: drift-free; tick n is due at start + n * every (each delay is computed from the
+ *   start, not chained). A late tick (a throttled background tab) coalesces the missed ones:
+ *   n jumps. Data `{ n, t }`: the tick number from 1, `t` = Date.now().
+ * - `after`: fires once, data `{ t }`. It doesn't fire again while the same spec stays declared.
+ * - `frame`: every animation frame (requestAnimationFrame; setTimeout 16 ms without it), data
+ *   `{ t, dt }`: Date.now() and the ms since the previous frame (0 on the first).
+ * - A hidden Switchable page's timers stop unless `background: true` (the core sends only those
+ *   while hidden) and start again from scratch when it is shown.
+ * - A disposed instance's timers stop; app dispose stops all. SSR runs no drivers: no timers.
+ * - An invalid spec (non-positive `every`, negative `after`, no action) doesn't start; the dev
+ *   entry reports SYG422 through the `timerSpec` diagnostics hook.
+ */
+
+const g: any = globalThis;
+const now = () => Date.now();
+
+const valid = (s: any) => s.frame
+  ? typeof s.frame == 'string'
+  : typeof s.action == 'string' && !!s.action && (s.every == null ? s.after >= 0 : s.after == null && s.every > 0) && (s.every || s.after) < 1 / 0;
+
+// starts one timer; `e` (its entry) gets `d` once an `after` has fired. Returns the stop function.
+// The next tick / frame is scheduled before the action is sent, so an action that stops (or
+// changes) the timer clears the pending one.
+const start = (s: any, send: (type: string, data: any) => void, e: any): (() => void) => {
+  let id: any, n = 0, last: any;
+  const t0 = now(), every = s.every, raf = s.frame && g.requestAnimationFrame;
+  const later = (ms: number) => id = raf ? requestAnimationFrame(tick) : setTimeout(tick, ms);
+  // a frame's `ts` is requestAnimationFrame's timestamp (the fallback passes none: the clock)
+  const tick = (ts = now()) => {
+    const t = now();
+    if (s.frame) {
+      later(16);
+      send(s.frame, {t, dt: last == null ? 0 : ts - last});
+      last = ts;
+    } else if (every) {
+      n = Math.max(n + 1, Math.floor((t - t0) / every));
+      later(t0 + (n + 1) * every - t);
+      send(s.action, {n, t});
+    } else {
+      e.d = 1;
+      send(s.action, {t});
+    }
+  };
+  later(s.frame ? 16 : every || s.after);
+  return () => raf ? cancelAnimationFrame(id) : clearTimeout(id);
+};
+
+/**
+ * The driver over `runners` (sender → { c: component name, on: { [name]: entry } }, an entry
+ * being { k: the spec's JSON, s: the spec, x: stop, ok: started, d: an `after` that fired }).
+ * The testing fake passes its own map to list the active timers (t.timers).
+ */
+export const timerDriver = (runners: Map<any, any>) => (sink$: any) => {
+  const update = (id: any, d: any, c?: any) => {
+    let r = runners.get(id);
+    if (!r) runners.set(id, r = {c, on: {}});
+    const on = r.on;
+    for (const n in on) if (on[n].k != JSON.stringify(d?.[n])) on[n].x(), delete on[n];
+    for (const n in d) {
+      const s = d[n];
+      if (!s || on[n]) continue;
+      const e: any = on[n] = {k: JSON.stringify(s), s, x: () => {}};
+      if (e.ok = valid(s)) e.x = start(s, (type, data) => reply(id, type, data), e);
+      else g.__SYGNAL_DIAGNOSTICS__?.timerSpec?.(n, s, c);
+    }
+    if (!d) runners.delete(id);
+  };
+  const stopAll = () => runners.forEach((_, id) => update(id, 0));
+  const {replies, reply} = makeReplies(id => update(id, 0));
+  sink$.addListener({
+    next: (v: any) => { if (v && v.__emitterId !== undefined && 'timers' in v) update(v.__emitterId, v.timers, v.__emitterName); },
+    error: () => {},
+    complete: stopAll,
+  });
+  return {...replies, __sygnalStatic: 'timers', dispose: stopAll};
+};
+
+/**
+ * Timers declared by components (`C.timers = (state) => ({ tick: state.running && { every: 100,
+ * action: 'TICK' } })`), delivered as their own actions: `run(App, { TIMER: makeTimerDriver() })`.
+ */
+export const makeTimerDriver = () => timerDriver(new Map());

package/src/extra/undo.ts

@@ -0,0 +1,261 @@
+/*
+ * PLAN-4 GS-8: undo / redo.
+ *
+ *   Editor.model = undoable({ TYPE: ..., LOAD: ... }, { key: 'doc', coalesceMs: 500, resetOn: ['LOAD'] })
+ *     → state.history = { past, future }; adds UNDO and REDO (the host's intent triggers them)
+ *   Editor.uses = { history: undo({ key: 'doc', undo: UndoButton, redo: RedoButton }) }
+ *     → the same as a behavior: state.history also has canUndo / canRedo, the actions are
+ *       'history.UNDO' / 'history.REDO', and the controls trigger them
+ *
+ * Every STATE reducer (function entries, `STATE` of object entries, 'ACTION | STATE' keys) is
+ * wrapped: when its result has a different state[key], the old state[key] is pushed onto
+ * `past` (at most `limit`, default 100) and `future` is cleared. With `track`, only those
+ * actions are recorded; built-in actions (INITIALIZE ...) only when tracked. A change by the
+ * same action within `coalesceMs` of the previous one joins that step (typing). With
+ * `coalesce` (4-G1, D143) only the listed actions join (`coalesceMs` then defaults to 500);
+ * every other action is always its own step (two quick clicks on Larger are two). `resetOn`
+ * actions clear the history and are not recorded. Snapshots are references: reducers must
+ * return new objects (they do in Sygnal). A model's own UNDO / REDO entry runs after the
+ * built-in one (as a host entry for a behavior action does, D123).
+ *
+ * Gestures (3-H G-447): another behavior in the host's `uses` that declares `undoStep` (its
+ * actions that complete a step: sortable's DROPPED) makes its other actions gesture steps. Their
+ * changes aren't recorded; `history.base` holds the value from before the gesture until the
+ * completing action records it as one entry. Works in either `uses` order (undo first: the
+ * behavior's actions get host entries that run after them). undo() as a behavior only:
+ * undoable() can't see `uses`. 3-L: a recorded action, UNDO or REDO during a gesture first
+ * records the value from before it (G-473: it stays reachable); a gesture step that brings the
+ * value back to where the gesture started (a cancel) leaves nothing pending, nor does a gesture
+ * action after the value was changed outside the gesture (G-475 / G-479). `track` / `coalesce`
+ * naming any of a gesture behavior's actions apply to its steps; `resetOn` naming one of them
+ * resets the history at that action (G-477). 3-O: an untracked gesture is like an untracked
+ * action, its changes are never recorded, nor pending (G-506); drops join only when `coalesce`
+ * names a gesture action (G-507); REDO mid-gesture records the value from before the gesture in
+ * place of the current one, as a recorded action does (G-508); "back where it started" compares
+ * arrays and plain objects shallowly (G-509). 3-U: with `key: [...]` every comparison is key by key
+ * (G-529 / G-530), a key the state didn't have stays out on UNDO / REDO, and `key: []` throws (G-531).
+ *
+ * SYG226 (dev, warn): a `track` / `resetOn` / `coalesce` name with no model entry (nor an action
+ * of a behavior in the host's `uses`).
+ */
+import { defineBehavior } from './behaviors'
+import { ABORT, isAbort } from '../shared'
+
+const BUILT_IN = /^(BOOTSTRAP|INITIALIZE|DISPOSE|READY|RESOURCE)$/
+// the last recorded change of a history, keyed by its `past` array (which a behavior's calculated
+// fields keep while they copy the history object): [action, time] (coalescing; never in state)
+const last = new WeakMap<object, [string, number]>()
+const reported = new WeakSet<object>()
+
+export interface UndoOptions { key: string | string[], limit?: number, track?: string[], coalesce?: string[], coalesceMs?: number, resetOn?: string[] }
+
+const actionOf = (a: string) => a.split('|')[0].trim()
+
+// 3-U G-531: `key: []` keeps nothing (a definition error, in every build)
+const keyed = (o: UndoOptions) => {
+  if (Array.isArray(o?.key) && !o.key.length) throw new Error("undo: `key: []` names no state key; use key: 'name' or key: ['a', 'b']")
+}
+
+// SYG226: report through the diagnostics core when it is enabled (dev); nothing in production
+const check = (model: any, o: UndoOptions, component?: any, skip?: any) => {
+  const known = new Set(Object.keys(model || {}).map(actionOf))
+  for (const a of [...(o.track || []), ...(o.resetOn || []), ...(o.coalesce || [])]) {
+    const i = a.indexOf('.'), m = i > 0 && skip?.[a.slice(0, i)]?.model
+    // a behavior's action (G-477: one it doesn't have is reported)
+    if (known.has(a) || m && a.slice(i + 1) in m) continue
+    try {
+      (globalThis as any).__SYGNAL_DIAGNOSTICS__?.report('SYG226', {
+        severity: 'warn', component, data: {action: a},
+        message: `undo ${o.track?.includes(a) ? 'track' : o.resetOn?.includes(a) ? 'resetOn' : 'coalesce'} names '${a}', which has no model entry`,
+        fix: `Use the name of a model entry, or add '${a}' to the model`,
+      })
+    } catch (e) { queueMicrotask(() => { throw e }) }
+  }
+}
+
+// a history without the pending gesture base
+const settled = (h: any) => { const {base: _, ...o} = h; return o }
+// the same value (a gesture step that put everything back: a cancel): arrays and plain objects
+// compare their entries by identity (G-509), anything else is itself
+const plain = (x: any) => Array.isArray(x) ? 1 : x && typeof x == 'object' && Object.getPrototypeOf(x) === Object.prototype ? 2 : 0
+const same1 = (a: any, b: any) => {
+  const k = a !== b && plain(a) && plain(a) == plain(b) && Object.keys(a)
+  return a === b || !!k && k.length == Object.keys(b).length && k.every(i => i in b && a[i] === b[i])
+}
+
+const wrap = (model: any, o: UndoOptions, hk: string, ns: string, S = 'STATE', g: any = {}): any => {
+  const {key, limit = 100, track, coalesce, coalesceMs = coalesce ? 500 : 0, resetOn = []} = o, keys = typeof key == 'string' ? null : key
+  const out: any = {}
+  const hist = (s: any) => s?.[hk] || {past: [], future: []}
+  // the value undo keeps: state[key], or (3-P G-515: `key: ['todo', 'done']`) an object of those
+  // keys the state has; values compare key by key (3-U G-529 / G-530: no shared identity, no cache).
+  // 3-W G-536: a key the state lacks and one it has as `undefined` differ for an array key (a key
+  // that appears or goes is a change); for a string key both are the value `undefined`. Primitive
+  // state (before the first object) has none of the keys
+  const val = (s: any) => {
+    if (!keys) return s?.[key as string]
+    const v: any = {}
+    for (const k of keys) if (s && typeof s == 'object' && k in s) v[k] = s[k]
+    return v
+  }
+  const by = (a: any, b: any, f: any) => !!a && !!b && keys!.every(k => k in a == k in b && f(a[k], b[k]))
+  const eq = (a: any, b: any) => keys ? a === b || by(a, b, (x: any, y: any) => x === y) : a === b
+  const same = (a: any, b: any) => keys ? by(a, b, same1) : same1(a, b)
+  // G-531: a key the snapshot didn't have is left out (not set to undefined); G-536: so is a string
+  // key whose snapshot is undefined
+  const set = (s: any, v: any) => {
+    const r = keys ? {...s, ...v} : {...s, [key as string]: v}
+    for (const k of keys || [key as string]) if (keys ? !(k in v) : v === undefined) delete r[k]
+    return r
+  }
+  // one more entry in `past` (`join`: the change joins the last one)
+  const rec = (r: any, h: any, v: any, name: string, joins: any) => {
+    const at = Date.now(), prev = last.get(h.past)
+    const join = joins && prev && prev[0] == name && at - prev[1] < coalesceMs && h.past.length
+    const nh = {...settled(h), past: join ? h.past : [...h.past, v].slice(-limit), future: []}
+    last.set(nh.past, [name, at])
+    return {...r, [hk]: nh}
+  }
+  // 3-H G-447: a gesture's actions (`g`: another behavior's actions, 1 a step, 2 the one that
+  // completes it, its `undoStep`). A step's change isn't recorded: `base` keeps [the value before
+  // the gesture's first step, the value after its last]; the completing action records that
+  // first value as one entry. A gesture that ends without it (cancelled) records nothing. The
+  // pre-action state comes from the handler's props (`state`): as the host entry after the
+  // behavior's (undo before it in `uses`), the reducer gets the behavior's result. `all`: the
+  // gesture behavior's actions (G-477: `track` / `coalesce` naming any of them cover its steps);
+  // `n` its key in `uses`, `end` its internal `undoEnd(slice)`: true when the slice an action
+  // left ended the gesture without completing it (3-P G-510: sortable's Escape, unmount, reset)
+  const gw = (f: any, [kind, all, n, end]: any, name: string) => {
+    const has = (l?: string[]) => !!l && all.some((x: string) => l.includes(x))
+    // G-507: drops join only when `coalesce` names the gesture (two separate drags are two steps)
+    const tracked = !track || has(track), joins = coalesceMs > 0 && has(coalesce), reset = resetOn.includes(name)
+    return (s: any, ...x: any[]) => {
+      const r0 = f ? f(s, ...x) : s, r = isAbort(r0) ? s : r0, pre = x[2]?.state || s, none = f ? r0 : ABORT
+      if (!r || typeof r != 'object' || !pre) return none
+      const h = hist(r), b = h.base, v = val(r), p = val(pre)
+      // G-477: resetOn names this gesture action
+      if (reset) return h.past.length || h.future.length || b ? {...r, [hk]: {...settled(h), past: [], future: []}} : none
+      // G-506: an untracked gesture is an untracked change: nothing recorded, nothing pending
+      if (!tracked) return none
+      // the base holds while the value is the one the gesture's last step left (G-475: else it
+      // was changed outside the gesture, e.g. restored, and the base is stale)
+      const on = b && eq(b[1], p) && b, stop = kind == 1 && end?.(r[n])
+      if (kind == 1 && !stop) {
+        if (eq(v, p)) return b && !on ? {...r, [hk]: settled(h)} : none
+        const b0 = on ? on[0] : p
+        // back where the gesture started (Escape, an item moved back): nothing pending (G-479);
+        // the base is this behavior's (G-514: a step joins another's pending base and takes it)
+        return {...r, [hk]: same(b0, v) ? settled(h) : {...h, base: [b0, v, n]}}
+      }
+      // G-514: only the behavior that opened the base completes it
+      if (b && b[2] != null && b[2] !== n || !b && !stop) return none
+      // G-510: ended without completing: what it leaves (the item where it is, or a restore after
+      // the value changed) is one step from the value before the gesture, unless it is that value
+      if (stop) {
+        const b0 = on ? on[0] : p
+        return same(b0, v) ? b ? {...r, [hk]: settled(h)} : none : rec(r, h, b0, name, 0)
+      }
+      return !on || eq(b[0], v) ? {...r, [hk]: settled(h)} : rec(r, h, b[0], name, joins)
+    }
+  }
+  // G-473: a pending gesture's base, recorded before another change: the value from before the
+  // gesture stays reachable (its steps join that change's entry)
+  const before = (h: any, v: any) => { const b = h.base; return b && eq(b[1], v) && !eq(b[0], v) ? [b[0]] : null }
+  for (const a in g) if (!(a in model)) out[a] = {[S]: gw(null, g[a], a)}
+  for (const a in model) {
+    const e = model[a], [name, sink] = a.split('|').map(x => x.trim())
+    if (g[a]) {
+      const f = typeof e == 'function' ? e : e?.[S]
+      out[a] = typeof e == 'function' ? gw(e, g[a], a) : {...e, [S]: gw(typeof f == 'function' ? f : null, g[a], a)}
+      continue
+    }
+    const reset = resetOn.includes(name), joins = coalesceMs > 0 && (!coalesce || coalesce.includes(name))
+    const f0 = sink ? (sink == S ? e : null) : typeof e == 'function' ? e : e?.[S]
+    // a constant STATE value isn't a reducer: the entry is left alone (G-214)
+    if (f0 != null && typeof f0 != 'function') { out[a] = e; continue }
+    const f = f0
+    // an entry without a STATE reducer is left alone, except a resetOn object entry (gets one)
+    if (!(f || reset && !sink) || !(reset || (track ? track.includes(name) : !BUILT_IN.test(name)))) { out[a] = e; continue }
+    const w = (s: any, ...x: any[]) => {
+      const r = f ? f(s, ...x) : s, h = hist(s)
+      if (!r || typeof r != 'object' || isAbort(r)) return r
+      if (reset) return h.past.length || h.future.length || h.base ? {...r, [hk]: {...settled(h), past: [], future: []}} : r
+      const v = val(s)
+      if (r === s || eq(val(r), v)) return r
+      const b0 = before(h, v)
+      return rec(r, h, b0 ? b0[0] : v, name, !b0 && joins)
+    }
+    out[a] = sink || typeof e == 'function' ? w : {...e, [S]: w}
+  }
+  // mid-gesture, the value from before the gesture stands in for the current one: UNDO goes back
+  // to it (G-473: the drag so far is the step undone), REDO records it (G-508: the drag so far
+  // joins the redone step, as with a recorded action; at most `limit`)
+  const step = (u: boolean) => (s: any) => {
+    const h = hist(s), v = val(s), b = before(h, v), {past, future} = h
+    if (!(u ? b || past.length : future.length)) return ABORT
+    return {...set(s, u ? b ? b[0] : past[past.length - 1] : future[0]), [hk]: {...settled(h),
+      past: u ? b ? past : past.slice(0, -1) : [...past, b ? b[0] : v].slice(-limit),
+      future: u ? [v, ...future] : future.slice(1)}}
+  }
+  const add = (a: string, f: any) => {
+    const own = out[ns + a]
+    if (!own) return out[ns + a] = f
+    const g = typeof own == 'function' ? own : own[S]
+    // the model's own entry runs after the built-in step (its ABORT keeps the step)
+    const both = typeof g != 'function' ? f : (s: any, ...x: any[]) => {
+      const r = f(s, ...x), q = g(isAbort(r) ? s : r, ...x)
+      return isAbort(q) ? r : q
+    }
+    out[ns + a] = typeof own == 'function' ? both : {...own, [S]: both}
+  }
+  add('UNDO', step(true))
+  add('REDO', step(false))
+  return out
+}
+
+/**
+ * Wraps a model's STATE reducers so `state[key]` gets undo / redo (GS-8): `state.history =
+ * { past, future }`, plus UNDO and REDO entries for the intent to trigger. Options: `key` (the
+ * state key to snapshot), `limit` (100), `track` (only these actions), `coalesceMs` (join rapid
+ * changes by one action), `coalesce` (only these actions join; default window 500 ms), `resetOn`
+ * (actions that clear the history). Returns a new model.
+ */
+export const undoable = (model: any, options: UndoOptions): any => {
+  keyed(options)
+  check(model, options)
+  return wrap(model, options, 'history', '')
+}
+
+/**
+ * undoable() as a behavior (GS-8 + GS-1): `uses = { history: undo({ key: 'doc', undo: Undo,
+ * redo: Redo }) }` gives `state.history = { past, future, canUndo, canRedo }` and the actions
+ * 'history.UNDO' / 'history.REDO' (the `undo` / `redo` controls trigger them; so can a host
+ * intent action of that name). The other options are undoable()'s; `track` and `resetOn` name
+ * the host's actions.
+ */
+export const undo = (options: UndoOptions & { undo?: any, redo?: any }): any => {
+  keyed(options)
+  const b = defineBehavior({
+    initialState: {past: [], future: []},
+    intent: ({DOM}: any, {undo, redo}: any) => ({
+      ...(undo && {UNDO: DOM.click(undo)}),
+      ...(redo && {REDO: DOM.click(redo)}),
+    }),
+    // placeholders (no change): they make the actions behavior-owned; the full-state UNDO / REDO
+    // that wrap() adds for 'key.UNDO' runs after them, as a host entry would (D123)
+    model: {UNDO: () => ABORT, REDO: () => ABORT},
+    calculated: {canUndo: (h: any) => h.past.length > 0, canRedo: (h: any) => h.future.length > 0},
+  })(options), merge = b.merge
+  b.merge = (c: any, k: string) => {
+    const u = c.view?.uses, g: any = {}
+    if (!reported.has(b)) reported.add(b), check(c.model, options, c, u)
+    // the gestures of the host's other behaviors (sortable's drag: one step per drop), in either `uses` order
+    for (const n in u) {
+      const s = u[n]?.undoStep, all = Object.keys(u[n]?.model || {}).map(a => n + '.' + a)
+      if (s) for (const a in u[n].model) g[n + '.' + a] = [s.includes(a) ? 2 : 1, all, n, u[n].undoEnd]
+    }
+    c.model = wrap(c.model || {}, options, k, k + '.', c.stateSourceName, g)
+    merge(c, k)
+  }
+  return b
+}

package/src/extra/viewTransitions.ts

@@ -0,0 +1,38 @@
+import type {Stream} from 'xstream';
+import type {VNode} from '../cycle/dom/snabbdom';
+import {makeDOMDriver, DOMDriverOptions} from '../cycle/dom/makeDOMDriver';
+import {viewTransition$} from '../cycle/dom/viewTransition';
+
+/**
+ * PLAN-4 GS-12 (D129): a DOM driver that can patch inside `document.startViewTransition()`.
+ * It is `makeDOMDriver(mountPoint, options)`, as run()'s own DOM driver, plus the hook: the patch caused by an action listed in a component's
+ * `viewTransitions` static (`Board.viewTransitions = ['MOVE']`, `App.viewTransitions = ['ROUTE']`)
+ * runs as a View Transition. Opt-in, so the hook costs nothing in apps that don't import it.
+ *
+ *     run(App, { DOM: makeViewTransitionDOMDriver('#root') })
+ */
+export function makeViewTransitionDOMDriver(mountPoint: string | Element | DocumentFragment = '#root', options: DOMDriverOptions = {}) {
+  const inner: any = makeDOMDriver(mountPoint, options);
+  return (vnode$: Stream<VNode>, name?: string) => {
+    let source: any;
+    // the flags live on the driver's IsolateModule (the core sets `vt` there; it is per app),
+    // which exists once the inner driver has run: read lazily, at the first vnode
+    source = inner(viewTransition$(vnode$, () => source?._isolateModule), name);
+    const im = source._isolateModule;
+    // SYG645 (dev): this app's DOM driver can do View Transitions
+    im.vtDriver = 1;
+    // a request is consumed by the next vnode (viewTransition$ resets it), however late: a render
+    // may take long. It expires when the page has been idle for 100 ms without one, since a listed
+    // action whose new state renders the same view (the first ROUTE reply, say) sends no vnode and
+    // must not animate a later, unrelated patch. A slow render keeps the main thread busy, so the
+    // expiry timer then runs late: it is re-armed instead (late by more than 30 ms = busy)
+    let on = 0, t: any;
+    const expire = (due: number): any => t = setTimeout(() => Date.now() - due > 30 ? expire(Date.now() + 100) : on = 0, 100);
+    Object.defineProperty(im, 'vt', {
+      configurable: true,
+      get: () => on,
+      set: (v: any) => { clearTimeout(t); (on = v ? 1 : 0) && expire(Date.now() + 100); },
+    });
+    return source;
+  };
+}