sygnal 5.3.7 → 6.0.0

package/src/extra/widget.ts

@@ -0,0 +1,201 @@
+/**
+ * PLAN-5 W-1 (D189/D190/D196): `defineWidget`, a framework-agnostic third-party widget (a date
+ * picker, a chart, an editor) as a JSX tag (canonical) that also works as a control spec.
+ *
+ *   const DatePicker = defineWidget({
+ *     tag: 'input',
+ *     mount: (el, props, dispatch) => flatpickr(el, { defaultDate: props.value, onChange: ([d]) => dispatch('pick', d) }),
+ *     update: (fp, props) => fp.setDate(props.value, false),
+ *     unmount: (fp) => fp.destroy(),
+ *     events: ['pick'],
+ *     commands: { open: (fp) => fp.open() },
+ *   })
+ *   // view:   <label>Due <DatePicker className="due" value={state.due} /></label>
+ *   // intent: DUE: DOM.select('.due').events('pick').detail()
+ *   // model:  OPEN_DUE: { ELEMENT: { open: '.due' } }
+ *   // alt:    const { Due } = controls({ Due: DatePicker }); DOM.select(Due).events('pick'), { open: Due }
+ *
+ * 0 B in the core when unused: everything is in this module, and the marker handler is registered
+ * by the first defineWidget() call, not on import.
+ * - The tag is a function carrying the pragma's control render hook (`__sygnalControl`, CT-1), so
+ *   `<DatePicker …/>` never becomes a component. It is also a control spec object (D101/D116:
+ *   `kind`, `vnode(props, children, h)`, `commands`), so `controls({ Due: DatePicker })` works.
+ * - `vnode()` returns a `widget` marker; the owner's reconcile walk rewrites it through the marker
+ *   registry (`pres.widget`, given the marker's path) into the host vnode, with the owner instance
+ *   at hand (onError). The host has no children (opaque to snabbdom) and carries the newest props
+ *   in `data.wp`; its hooks read the vnode they are given, so `update` always gets the props of
+ *   the render being patched (no closure over mount-time props). Each host has its own hook
+ *   object: the widget's, then a `ref`'s (the host element), then a `<Transition>`'s (G-363).
+ * - 1-R (G-360): the host's key names the widget and the instance (its key in the parent, or its
+ *   place when unkeyed), so snabbdom never patches a host into another vnode (a plain element of
+ *   the same tag, another widget, the error fallback) or the reverse: the host is destroyed and
+ *   the widget unmounts.
+ * - The record `{ w (the tag), p (props), i (instance), e (dispatch) }` lives on the host element
+ *   as the non-enumerable `__sw` (D200: short, the core reads it), so the instance survives re-renders and keyed moves
+ *   (snabbdom moves the element). Mount runs on insert, or on the first patch of an element that
+ *   has none (SSR hydration). `update` runs when the props change (shallow; an object host prop
+ *   such as `style` one level deep, G-362); without `update`, a change remounts (G-367: a mount
+ *   that throws then is SYG660 and leaves no record). `unmount` on destroy (a removed Portal
+ *   destroys its content too, G-359).
+ * - `className` goes to the host as class-module tokens (G-364): a change toggles only those, not
+ *   the classes the library added (flatpickr's `flatpickr-input`).
+ * - `dispatch(name, detail)` (mount's third parameter) dispatches a bubbling CustomEvent on the
+ *   host: the intent reads it like any DOM event (`.detail()`); isolation (Collection items)
+ *   applies as for any element.
+ * - Commands: D102's `spec.commands[name](hostElement, options)` resolves the instance from the
+ *   host. For selector targets each command whose name the element doesn't already have is also
+ *   a method of the host (D190); a declared command whose name is a native method (`focus`,
+ *   `close`) is found by the core through `__sw` and wins over the native one, with the
+ *   options object (D196, D200).
+ * - A widget tag is not a selector: `DOM.select(DatePicker)` matches nothing (SYG143 in dev).
+ * - G-413: `ownProps` names props that stay off the host although they'd go there (a part that
+ *   puts `aria-label` on its own control).
+ * - G-409: mount's fourth parameter `error(e)` reports a later failure the widget caught itself
+ *   (fromZag's machine-driven redraws): handled as a throwing `update` (SYG661 + fallback; G-580:
+ *   the dev message says the widget reported it through error(e)).
+ * - A `mount`/`update` that throws (SYG660/661): reported to the app's onError with phase
+ *   'widget' (D105), and the owner's next render shows its `onError` fallback in that instance's
+ *   place (G-361: per instance; a render with other props tries again, and the failure is
+ *   forgotten when the fallback leaves the page). `unmount` (SYG662): reported, nothing to replace.
+ * - Inside `<Portal>`: the Portal's children are rewritten here too (Portal children are not
+ *   walked by the core), so a widget works in a portal.
+ * - SSR (extra/ssr.ts): the host, with `fallback` inside it; the client patch replaces it with
+ *   the keyed host and mounts.
+ *
+ * Dev text lives in the 'sygnal/diagnostics' entry (checks/widgets.ts), reached through the core
+ * bridge as `widget(code, widgetTag, owner, extra)`: SYG140 (dispatch of an undeclared event),
+ * SYG143, SYG144 (a declared event the host fires natively), SYG660–662. Without the entry, a
+ * thrown mount/update/unmount is logged as `[Sygnal SYG66x]` with the error.
+ */
+import {pres} from '../core/registry'
+import {chainHooks} from '../pragma/index'
+
+const W = '__sw'
+
+// props that also go to the host element (every prop but key goes to the widget; ref is the host's)
+const HOST = /^(id|class(Name)?|style|title|name|placeholder|role|tab[iI]ndex|hidden|lang|dir|attrs)$|^(aria|data)-/
+
+/** the dev entry's reporter (checks/widgets.ts); returns the diagnostic when one was reported
+ * (r: G-580, a 661 the widget reported through error(e), not a throwing update) */
+const dev = (code: number, w: any, o?: any, x?: any, r?: any): any => (globalThis as any).__SYGNAL_DIAGNOSTICS__?.widget?.(code, w, o, x, r)
+
+let ids = 0
+
+// shallow; G-362: an object host prop (style, attrs, a class map) compares one level deep, so a
+// new object with the same entries is no change (snabbdom patches the host from it anyway)
+const same = (a: any, b: any, d?: any): any => {
+  const k = Object.keys(a)
+  return k.length == Object.keys(b).length && k.every(x => a[x] === b[x] ||
+    !d && HOST.test(x) && typeof a[x] == 'object' && typeof b[x] == 'object' && a[x] && b[x] && same(a[x], b[x], 1))
+}
+
+// k: the host's key, the failure's place; [error, the props of the fallback's last render]; r:
+// reported through error(e)
+function fail(o: any, w: any, k: any, code: number, e: any, r?: any) {
+  e = e instanceof Error ? e : Error(e)
+  dev(code, w, o, e, r) || console.error(`[Sygnal SYG${code}]`, e)
+  o.app.appError(o, e, 'widget')
+  if (code < 662 && !o.disposed) (o.$wf ||= new Map()).set(k, [e]), o.refresh()
+}
+
+function mount(v: any) {
+  const el = v.elm, {ww: w, wp: p, wo: o} = v.data
+  const d = (n: string, detail?: any) => { dev(140, w, o, n); el.dispatchEvent(new CustomEvent(n, {detail, bubbles: true})) }
+  let i: any
+  dev(144, w, o, el)
+  // G-409: mount's fourth parameter reports a later failure (an adapter's own redraw): SYG661,
+  // the owner's onError fallback in this instance's place, as for a throwing update (G-580: the
+  // dev text says error(e) reported it)
+  const err = (x: any) => { el[W] && fail(o, w, v.key, 661, x, 1) }
+  try { i = w.def.mount(el, p, d, err) } catch (x) { return fail(o, w, v.key, 660, x) }
+  Object.defineProperty(el, W, {value: {w, p, i, e: d}, configurable: true})
+  // the tag form's commands: a host method for each one the element doesn't have (D190)
+  for (const m in w.def.commands) m in el || (el[m] = (x: any) => el[W]?.w.commands[m]?.(el, x))
+}
+
+function destroy(v: any) {
+  const el = v.elm, s = el[W]
+  if (s) {
+    delete el[W]
+    try { s.w.def.unmount?.(s.i, el) } catch (x) { fail(v.data.wo, s.w, v.key, 662, x) }
+  }
+}
+
+const hooks: any = {
+  insert: mount,
+  postpatch(_: any, v: any) {
+    const el = v.elm, p = v.data.wp, s = el[W]
+    // SSR hydration (the element was patched in place, never inserted): mount now
+    if (!s) return mount(v)
+    const u = s.w.def.update
+    if (same(s.p, p)) return
+    // G-367: without update, a change remounts
+    if (!u) return destroy(v), mount(v)
+    try { u(s.i, p, el); s.p = p } catch (x) { fail(v.data.wo, s.w, v.key, 661, x) }
+  },
+  destroy,
+}
+
+/** the host vnode for a widget marker (client: the hooks, the owner and the key k; SSR adds the fallback) */
+function host(n: any, o?: any, k?: any): any {
+  const {ww: w, wp: p, h, attrs, r} = n.data, def = w.def, hp: any = {ref: r}
+  for (const x in p) if ((HOST.test(x) || def.hostProps?.includes(x)) && !def.ownProps?.includes(x)) hp[x] = p[x]
+  if (hp.className) hp.class = [hp.class, hp.className], delete hp.className
+  const v = h(def.tag || 'div', hp), d = v.data
+  if (attrs) d.attrs = {...d.attrs, ...attrs}
+  if (o) {
+    v.key = k
+    d.ww = w; d.wp = p; d.wo = o; v.children = undefined
+    // a hook object per host: a ref's hooks (from h), the widget's, then a Transition's (marker)
+    chainHooks(d, hooks)
+    n.data.hook && chainHooks(d, n.data.hook)
+  }
+  return v
+}
+
+/** pres.widget: the host, or the owner's fallback where this instance failed */
+function rewrite(n: any, o: any, path: string): any {
+  const w = n.data.ww, p = n.data.wp, wf = o.$wf
+  // the instance: the widget and its key, or its place when unkeyed
+  const k = 'w' + w.$i + (n.key == null ? path : '#' + n.key)
+  let f = wf?.get(k)
+  // a render with other props than the fallback's last one tries again
+  if (f && f[1] && !same(f[1], p)) wf.delete(k), f = 0
+  if (!f) return host(n, o, k)
+  f[1] = p
+  const def = o.def, x = n.data.h('div', {attrs: {'data-sygnal-error': def.name}})
+  let r: any = x
+  try { r = def.onError?.(f[0], {componentName: def.name}) || x } catch (_) {}
+  // its own key; the failure is forgotten when it leaves the page (a reopened panel tries again)
+  chainHooks((r = {...r, key: k + '!', data: {...r.data}}).data, {destroy: () => wf.delete(k)})
+  return r
+}
+
+/** widget markers among a Portal's children (the core doesn't walk them) */
+const inPortal = (c: any[], o: any, x: string): any[] =>
+  c.map((n, i) => n?.sel == 'widget' ? rewrite(n, o, x + '.' + i) : n?.children ? {...n, children: inPortal(n.children, o, x + '.' + i)} : n)
+
+export function defineWidget(def: any): any {
+  pres.widget ||= rewrite
+  const p: any = pres.portal
+  if (p && !p.$w) ((pres.portal = (n: any, o: any, x: string) => p({...n, children: inPortal(n.children || [], o, x)}, o, x)) as any).$w = 1
+  const w: any = () => {}, commands: any = {}
+  // D200: any name, `close` and `togglePopover` too (the core passes a widget command the options)
+  for (const m in def.commands) commands[m] = (el: any, o: any) => el[W] && def.commands[m](el[W].i, o || {}, el)
+  return Object.assign(w, {
+    kind: 'widget',
+    def,
+    $i: ++ids,
+    events: def.events || [],
+    commands,
+    // D101/D116: the control spec's vnode(props, children, h): one (marker) element vnode; also
+    // the tag form's pragma render hook (no data-control stamp)
+    vnode: w.__sygnalControl = (props: any, _: any, h: any) => {
+      const {key, ref, ...p} = props || {}
+      return {sel: 'widget', data: {ww: w, wp: p, h, r: ref}, children: undefined, text: undefined, key}
+    },
+    $ssr: host,
+    // D190/D199: a widget tag is not a selector (SYG143 in dev): select its className or a control
+    toString: () => (dev(143, w), ':not(*)'),
+  })
+}

package/src/extra/xstreamExtras.ts

@@ -0,0 +1,269 @@
+/**
+ * ESM ports of xstream's `concat`, `debounce`, `throttle`, `delay`, `dropRepeats` and
+ * `sampleCombine` extras (xstream, MIT, André Staltz), behaviour-identical.
+ *
+ * Why not import 'xstream/extra/*': those modules are CommonJS with `exports.default`. Under
+ * Vite/Vitest the default import resolves to the function, but in the rollup CJS build and in
+ * native Node ESM it resolves to the module object `{ default: fn }`, so the re-exports from
+ * 'sygnal' were not callable there (and neither were sygnal's own internal uses). ESM classes
+ * are also tree-shaken when an app does not use them. See also ./flatten.ts.
+ */
+import {Stream} from 'xstream'
+
+// ---------------------------------------------------------------- concat
+
+class ConcatProducer {
+  type = 'concat'
+  out: any = null
+  i = 0
+  constructor(public streams: any[]) {}
+  _start(out: any) { this.out = out; this.streams[this.i]._add(this) }
+  _stop() {
+    const streams = this.streams
+    if (this.i < streams.length) streams[this.i]._remove(this)
+    this.i = 0
+    this.out = null
+  }
+  _n(t: any) { const u = this.out; if (u) u._n(t) }
+  _e(err: any) { const u = this.out; if (u) u._e(err) }
+  _c() {
+    const u = this.out
+    if (!u) return
+    const streams = this.streams
+    streams[this.i]._remove(this)
+    if (++this.i < streams.length) streams[this.i]._add(this)
+    else u._c()
+  }
+}
+
+/** Emits everything from the first stream, then (once it completes) the second, and so on. */
+export function concat<T>(...streams: Stream<T>[]): Stream<T> {
+  return new Stream<T>(new ConcatProducer(streams) as any)
+}
+
+// ---------------------------------------------------------------- debounce
+
+const NO_VALUE = {}
+
+class DebounceOperator {
+  type = 'debounce'
+  out: any = null
+  id: any = null
+  t: any = NO_VALUE
+  constructor(public dt: number, public ins: any) {}
+  _start(out: any) { this.out = out; this.ins._add(this) }
+  _stop() { this.ins._remove(this); this.out = null; this.clearInterval() }
+  clearInterval() {
+    const id = this.id
+    if (id !== null) clearInterval(id)
+    this.id = null
+  }
+  _n(t: any) {
+    const u = this.out
+    if (!u) return
+    this.clearInterval()
+    this.t = t
+    this.id = setInterval(() => {
+      this.clearInterval()
+      u._n(t)
+      this.t = NO_VALUE
+    }, this.dt)
+  }
+  _e(err: any) {
+    const u = this.out
+    if (!u) return
+    this.clearInterval()
+    u._e(err)
+  }
+  _c() {
+    const u = this.out
+    if (!u) return
+    this.clearInterval()
+    if (this.t != NO_VALUE) u._n(this.t)
+    this.t = NO_VALUE
+    u._c()
+  }
+}
+
+/** Emits a value only after `period` ms have passed without another value. */
+export function debounce(period: number): <T>(ins: Stream<T>) => Stream<T> {
+  return function debounceOperator<T>(ins: Stream<T>): Stream<T> {
+    return new Stream<T>(new DebounceOperator(period, ins) as any)
+  }
+}
+
+// ---------------------------------------------------------------- throttle
+
+class ThrottleOperator {
+  type = 'throttle'
+  out: any = null
+  id: any = null
+  constructor(public dt: number, public ins: any) {}
+  _start(out: any) { this.out = out; this.ins._add(this) }
+  _stop() { this.ins._remove(this); this.out = null; this.id = null }
+  clearInterval() {
+    const id = this.id
+    if (id !== null) clearInterval(id)
+    this.id = null
+  }
+  _n(t: any) {
+    const u = this.out
+    if (!u) return
+    if (this.id) return
+    u._n(t)
+    this.id = setInterval(() => { this.clearInterval() }, this.dt)
+  }
+  _e(err: any) {
+    const u = this.out
+    if (!u) return
+    this.clearInterval()
+    u._e(err)
+  }
+  _c() {
+    const u = this.out
+    if (!u) return
+    this.clearInterval()
+    u._c()
+  }
+}
+
+/** Emits a value, then ignores further values for `period` ms. */
+export function throttle(period: number): <T>(ins: Stream<T>) => Stream<T> {
+  return function throttleOperator<T>(ins: Stream<T>): Stream<T> {
+    return new Stream<T>(new ThrottleOperator(period, ins) as any)
+  }
+}
+
+// ---------------------------------------------------------------- delay
+
+class DelayOperator {
+  type = 'delay'
+  out: any = null
+  constructor(public dt: number, public ins: any) {}
+  _start(out: any) { this.out = out; this.ins._add(this) }
+  _stop() { this.ins._remove(this); this.out = null }
+  _n(t: any) {
+    const u = this.out
+    if (!u) return
+    const id = setInterval(() => { u._n(t); clearInterval(id) }, this.dt)
+  }
+  _e(err: any) {
+    const u = this.out
+    if (!u) return
+    const id = setInterval(() => { u._e(err); clearInterval(id) }, this.dt)
+  }
+  _c() {
+    const u = this.out
+    if (!u) return
+    const id = setInterval(() => { u._c(); clearInterval(id) }, this.dt)
+  }
+}
+
+/** Delays every event (values, error, completion) by `period` ms. */
+export function delay(period: number): <T>(ins: Stream<T>) => Stream<T> {
+  return function delayOperator<T>(ins: Stream<T>): Stream<T> {
+    return new Stream<T>(new DelayOperator(period, ins) as any)
+  }
+}
+
+// ---------------------------------------------------------------- dropRepeats
+
+const EMPTY = {}
+
+class DropRepeatsOperator {
+  type = 'dropRepeats'
+  out: any = null
+  v: any = EMPTY
+  isEq: (x: any, y: any) => boolean
+  constructor(public ins: any, fn?: (x: any, y: any) => boolean) {
+    this.isEq = fn ? fn : (x: any, y: any) => x === y
+  }
+  _start(out: any) { this.out = out; this.ins._add(this) }
+  _stop() { this.ins._remove(this); this.out = null; this.v = EMPTY }
+  _n(t: any) {
+    const u = this.out
+    if (!u) return
+    const v = this.v
+    if (v !== EMPTY && this.isEq(t, v)) return
+    this.v = t
+    u._n(t)
+  }
+  _e(err: any) { const u = this.out; if (u) u._e(err) }
+  _c() { const u = this.out; if (u) u._c() }
+}
+
+/** Drops consecutive duplicates (`===`, or the given equality function). */
+export function dropRepeats<T>(isEqual?: (x: T, y: T) => boolean): (ins: Stream<T>) => Stream<T> {
+  return function dropRepeatsOperator(ins: Stream<T>): Stream<T> {
+    return new Stream<T>(new DropRepeatsOperator(ins, isEqual as any) as any)
+  }
+}
+
+// ---------------------------------------------------------------- sampleCombine
+
+const NO = {}
+
+class SampleCombineListener {
+  constructor(public i: number, public p: SampleCombineOperator) { p.ils[i] = this }
+  _n(t: any) {
+    const p = this.p
+    if (p.out === NO) return
+    p.up(t, this.i)
+  }
+  _e(err: any) { this.p._e(err) }
+  _c() { this.p.down(this.i, this) }
+}
+
+class SampleCombineOperator {
+  type = 'sampleCombine'
+  out: any = NO
+  ils: any[] = []
+  Nn = 0
+  vals: any[] = []
+  constructor(public ins: any, public others: any[]) {}
+  _start(out: any) {
+    this.out = out
+    const s = this.others
+    const n = this.Nn = s.length
+    const vals = this.vals = new Array(n)
+    for (let i = 0; i < n; i++) {
+      vals[i] = NO
+      s[i]._add(new SampleCombineListener(i, this))
+    }
+    this.ins._add(this)
+  }
+  _stop() {
+    const s = this.others
+    const n = s.length
+    const ils = this.ils
+    this.ins._remove(this)
+    for (let i = 0; i < n; i++) s[i]._remove(ils[i])
+    this.out = NO
+    this.vals = []
+    this.ils = []
+  }
+  _n(t: any) {
+    const out = this.out
+    if (out === NO) return
+    if (this.Nn > 0) return
+    out._n([t, ...this.vals])
+  }
+  _e(err: any) { const out = this.out; if (out !== NO) out._e(err) }
+  _c() { const out = this.out; if (out !== NO) out._c() }
+  up(t: any, i: number) {
+    const v = this.vals[i]
+    if (this.Nn > 0 && v === NO) this.Nn--
+    this.vals[i] = t
+  }
+  down(i: number, l: any) { this.others[i]._remove(l) }
+}
+
+/**
+ * Operator: whenever the source emits, emits `[source, latest(a), latest(b), ...]`
+ * (only once every other stream has emitted at least once).
+ */
+export function sampleCombine(...streams: Stream<any>[]): (sampler: Stream<any>) => Stream<any[]> {
+  return function sampleCombineOperator(sampler: Stream<any>): Stream<any[]> {
+    return new Stream<any[]>(new SampleCombineOperator(sampler, streams) as any)
+  }
+}