sygnal 5.4.0 → 6.0.0

package/src/ui/tabs.ts

@@ -0,0 +1,82 @@
+/*
+ * PLAN-5 2-U (S-4): Tabs, a behavior that wires the host's own markup (WAI-ARIA APG tabs).
+ *
+ *   Settings.uses = { tabs: tabs({ tab: '.tab', selected: 'general' }) }
+ *   const a = tabsAttrs(state.tabs, uid)
+ *   <div {...a.list} aria-label="Settings">
+ *     <button className="tab" {...a.tab('general')}>General</button> …
+ *   </div>
+ *   <section {...a.panel('general')}>…</section> …
+ *
+ * The host renders the tabs and panels; `tabsAttrs` gives each its attributes from the slice:
+ * roles, ids (from `uid`, so every instance has its own), aria-selected / aria-controls /
+ * aria-labelledby, the roving tabindex, `hidden` on the other panels, and the hooks
+ * `data-value` / `data-state` ('active' | 'inactive'). A click on a tab selects it; the arrow
+ * keys move the focus between the tabs (and select, unless `activation: 'manual'`), Home / End
+ * go to the first / last; disabled tabs are skipped.
+ *
+ * Options: `tab` (required: the tabs' selector), `selected` (the start; none: the first tab
+ * rendered), `orientation` ('horizontal' | 'vertical': which arrow keys), `activation`
+ * ('automatic' | 'manual'), `loop` (true), `id` (the ids' prefix; default: the key in `uses`).
+ * State: { id, selected, orientation }. Actions: SELECT (a value, or a click), MOVE (a value:
+ * focus it, and select it unless manual).
+ * G-397: `tabsAttrs(slice, uid, values)` with the tabs' values shows the first one selected when
+ * `selected` isn't among them (a removed tab); a host that removes tabs re-selects a neighbour
+ * and moves the focus to it in its own reducer (the guide's closable tabs).
+ */
+import {ABORT, defineBehavior} from '../index'
+import {idsOf, keyNav, keyed, lit} from './shared'
+
+const base = /*#__PURE__*/ defineBehavior({
+  initialState: {id: null as null | string, selected: null as null | string, orientation: 'horizontal'},
+  intent: ({DOM}: any, {tab, orientation, loop}: any) => {
+    const v = orientation == 'vertical'
+    return {
+      SELECT: DOM.click(tab).data('value'),
+      MOVE: keyNav(DOM, tab, [v ? 'ArrowDown' : 'ArrowRight'], [v ? 'ArrowUp' : 'ArrowLeft'], loop),
+    }
+  },
+  model: {
+    SELECT: (s: any, v: any) => (v == null || String(v) === s.selected ? ABORT : {...s, selected: String(v)}),
+    MOVE: {
+      STATE: (s: any, v: string, _n: any, _p: any, o: any) => (o.activation == 'manual' || v === s.selected ? ABORT : {...s, selected: v}),
+      ELEMENT: (_s: any, v: string, _n: any, _p: any, o: any) => ({focus: o.tab + '[data-value=' + lit(v) + ']'}),
+    },
+  },
+})
+
+/** Tabs as a behavior over the host's markup: `uses = { tabs: tabs({ tab: '.tab', selected: 'general' }) }`; render with `tabsAttrs`. */
+export const tabs = (options: any = {}): any =>
+  keyed(base({...options, ...(options.selected != null && {selected: String(options.selected)})}))
+
+/**
+ * The attributes of a tab set, from its slice: `list` (the tablist), `tab(value)` and
+ * `panel(value)`. Spread them on the host's elements: `<button className="tab" {...a.tab('general')}>`.
+ * `values` (optional): the tabs' values in order (leave disabled ones out). With it, a `selected`
+ * that isn't one of them (its tab was removed) shows the first one selected (G-397); without it,
+ * the first tab rendered is selected only while nothing is.
+ */
+export const tabsAttrs = (s: any, uid: any, values?: any[]): any => {
+  const id = idsOf(s, uid, 'tabs'), state = (b: boolean) => (b ? 'active' : 'inactive')
+  const vs = values && values.map(String)
+  let first: any = vs?.[0], sel = s?.selected == null ? null : String(s.selected)
+  if (vs && sel != null && !vs.includes(sel)) sel = null
+  // no selection (or a removed one): the first value, or the first tab (or panel) rendered
+  const on = (v: any) => {
+    v = String(v)
+    if (sel != null) return v === sel
+    first ??= v
+    return v === first
+  }
+  return {
+    list: {role: 'tablist', 'aria-orientation': s?.orientation || 'horizontal'},
+    tab: (v: any) => {
+      const b = on(v)
+      return {type: 'button', id: id('tab', v), role: 'tab', 'aria-selected': b, 'aria-controls': id('panel', v), tabindex: b ? '0' : '-1', 'data-value': String(v), 'data-state': state(b)}
+    },
+    panel: (v: any) => {
+      const b = on(v)
+      return {id: id('panel', v), role: 'tabpanel', 'aria-labelledby': id('tab', v), tabindex: '0', hidden: !b, 'data-state': state(b)}
+    },
+  }
+}

package/src/ui/toaster.ts

@@ -0,0 +1,198 @@
+/*
+ * PLAN-5 2-U (T-1, D198, from spike 0-S4): the Toaster component.
+ *
+ *   anywhere:  SAVE: { EVENTS: event('TOAST', { text: 'Saved', kind: 'success' }) }
+ *   once:      <Toaster />            (main.js: run(App, { TIMER: makeTimerDriver() }))
+ *
+ * - TOAST adds { id, text, kind ('info' | 'success' | 'warning' | 'error'; default 'info'),
+ *   timeoutMs (default 5000; 0 = until dismissed) }. A string is the text. A TOAST with the `id`
+ *   of a shown toast replaces it in place and restarts its timer ('Saving…' → 'Saved').
+ *   TOAST_DISMISS removes the toast with that id (no id: all of them). G-398: ids compare as
+ *   strings (the Collection's keys); an automatic id is 't<n>', never one a shown toast has.
+ * - Each toast is a Collection item: its `timers` static auto-dismisses it (GS-7; fake-timer
+ *   testable), its Dismiss button removes it, Transition animates it (`transition` names the
+ *   classes, `duration` is how long a leaving toast stays: the leave animation's length).
+ * - Two persistent live regions: role="status" (polite) for every kind but errors, role="alert"
+ *   for errors. They are rendered while empty, so a toast added later is announced.
+ * - While the pointer or the focus is in the region, the timers stop (and start over when both
+ *   have left; G-399: `hover` and `focus` are tracked apart): `pauseOnHover={false}` turns this
+ *   off. A focused Dismiss button moves the focus to the next toast's (else the previous one's,
+ *   else where the focus came from) before its toast goes; a focused element removed any other
+ *   way gets a focusout sent (Chromium sends none), so the region never stays paused.
+ * - The region is a `popover="manual"` element (top layer, above the page), re-parented into the
+ *   topmost open modal <dialog> while one is open and back when it closes or is removed (a
+ *   MutationObserver in the region's hooks, D198): outside the modal it would be drawn but inert
+ *   (spike 0-S4). `__sygnalHome` keeps its events in this component (G-356). The region is the
+ *   only child of a wrapper (`.toaster-home`), so the moved element has no siblings to patch.
+ *   G-404: the dialogs of the region's own root (a shadow root) are looked at and observed too.
+ *   G-426: the focus is that root's activeElement (in a shadow root the document's is the host).
+ *
+ * Class hooks: .toaster-home, .toaster (+ `className`), .toaster-status, .toaster-alert,
+ * .toaster-list, .toast, .toast-text, .toast-dismiss. Data attributes: data-kind on .toast,
+ * data-paused on .toaster.
+ */
+import {ABORT, Collection, Transition, createElement as h, xs} from '../index'
+
+// ── the region's placement (D198) ────────────────────────────────────
+// the open modal dialogs, in the order they became modal (the last one is on top)
+const order: any[] = []
+const modal = (d: any) => { try { return d.matches(':modal') } catch (_) { return false } }
+// G-404: the dialogs of the document and of the region's own root (a shadow root: sygnal/element)
+const topModal = (root: any) => {
+  const all = [...document.querySelectorAll('dialog')]
+  if (root !== document && root?.querySelectorAll) all.push(...root.querySelectorAll('dialog'))
+  const open = all.filter(modal)
+  for (let i = order.length; i--;) if (!open.includes(order[i])) order.splice(i, 1)
+  for (const d of open) if (!order.includes(d)) order.push(d)
+  return order[order.length - 1]
+}
+const show = (el: any) => { try { el.matches(':popover-open') || el.showPopover() } catch (_) {} }
+// the element with the focus in `el`'s root
+const act = (el: any) => (el.getRootNode?.() || document).activeElement
+// G-428: a focusout that leaves `t`: not to an element inside it, and with no relatedTarget not
+// while the focus is still inside (the window lost the focus: it comes back to the same element)
+const left = (t: any, e: any) => !(t && t.contains?.(e.relatedTarget || act(t)))
+// a toast on its way out (its Transition's leave classes)
+const leaving = (b: any) => /-leave-/.test(b.closest?.('.toast')?.className || '')
+
+const placement = {
+  insert: (v: any) => {
+    const el = v.elm, home = el.parentNode, root = el.getRootNode?.() || document
+    el.__sygnalHome = home
+    show(el)
+    // G-399: the focus in the region, and where it came from (where it goes back to). G-432: a
+    // focus from nowhere (the region's own refocus after a move, the browser's after a modal
+    // closed, the window focused again) keeps the last element it came from. G-458: but not one
+    // a press in the region gave: the user comes back from nowhere after a click on the page took
+    // the focus, and a mouse Dismiss would focus (and scroll to) an element left long ago. (A focus
+    // that comes back from another element names that one; a focus that left to a modal comes
+    // back from nowhere when it closes and keeps it: G-432)
+    // G-499: the press is its time, and counts for a focus within a second (a press released
+    // outside, a right-click or a touch scroll gets no focusin or click to clear it); a cancelled
+    // one (the browser took it for a scroll) at once
+    el.addEventListener('pointerdown', (e: any) => { el._p = e.timeStamp })
+    el.addEventListener('pointercancel', () => { el._p = 0 })
+    el.addEventListener('focusin', (e: any) => {
+      if (!el.contains(e.relatedTarget)) { el._f = 1; el._from = e.relatedTarget || (el._p && e.timeStamp - el._p < 1e3 ? null : el._from) }
+      el._p = 0
+    })
+    el.addEventListener('focusout', (e: any) => { if (left(el, e)) el._f = 0 })
+    // a Dismiss button with the focus (keyboard; a click that focused it): the focus moves to the
+    // next toast's Dismiss button, else the previous one's, else back where it came from, before
+    // the button goes (a removed focused element gets no focusout in Chromium)
+    el.addEventListener('click', (e: any) => {
+      el._p = 0
+      const b = e.target?.closest?.('.toast-dismiss')
+      // G-426: the root's activeElement (in a shadow root, the document's is the host)
+      if (!b || !b.contains(act(el))) return
+      const bs = [...el.querySelectorAll('.toast-dismiss')].filter((x: any) => x === b || !leaving(x)), i = bs.indexOf(b)
+      const to: any = bs[i + 1] || bs[i - 1] || (el._from?.isConnected && !el.contains(el._from) && el._from)
+      to ? to.focus() : b.blur()
+    })
+    if (typeof MutationObserver == 'undefined') return
+    const place = () => {
+      const to = topModal(root) || home
+      if (el.parentNode !== to) {
+        // a move blurs a focused Dismiss button: give the focus back
+        const a = act(el), f: any = el.contains(a) && a
+        to.appendChild(el)
+        f && f.focus()
+      }
+      // a moved popover is closed: show it again (on top of the dialog it is in)
+      show(el)
+    }
+    // `open` flips on showModal / close; a dialog removed while open takes the region with it
+    const mo = el._mo = new MutationObserver((rs) => {
+      // G-399: the focused element was removed (a toast dismissed some other way): no focusout
+      // in Chromium, so the region would stay paused; send one
+      if (el._f && !el.contains(act(el))) { el._f = 0; el.dispatchEvent(new FocusEvent('focusout', {bubbles: true})) }
+      if (home.isConnected && (!el.isConnected || (el.parentNode !== home && !modal(el.parentNode)) || rs.some((r) => r.type == 'attributes'))) place()
+    })
+    const opts = {subtree: true, childList: true, attributes: true, attributeFilter: ['open']}
+    mo.observe(document.body, opts)
+    // G-404: a region in a shadow root sees that root's dialogs open and close too
+    if (root !== document && root.nodeType == 11) mo.observe(root, opts)
+    place()
+  },
+  // removed with its wrapper while in a dialog: take it out of the dialog too
+  destroy: (v: any) => {
+    const el = v.elm
+    el._mo?.disconnect()
+    el.parentNode !== el.__sygnalHome && el.remove()
+  },
+}
+
+// ── one toast ──────────────────────────────────────────────────────
+// (statics through a /*#__PURE__*/ Object.assign, so every bundler drops an unused Toaster; a
+// componentName, so diagnostics and DevTools name them in minified builds too)
+const ToastItem = /*#__PURE__*/ Object.assign(function ToastItem({state, dismissLabel, transition, duration}: any) {
+  return h(Transition, {name: transition, duration},
+    h('div', {className: 'toast', 'data-kind': state.kind},
+      h('span', {className: 'toast-text'}, state.text),
+      h('button', {type: 'button', className: 'toast-dismiss', 'aria-label': dismissLabel + ': ' + state.text}, dismissLabel)))
+}, {
+  componentName: 'ToastItem',
+  intent: ({DOM}: any) => ({DISMISS: DOM.click('.toast-dismiss')}),
+  // a replaced toast (rev) gets a new timer name, so its timer starts over
+  timers: (s: any) => ({['expire' + (s?.rev || '')]: s?.timeoutMs > 0 && !s.paused && {after: s.timeoutMs, action: 'EXPIRE'}}),
+  model: {DISMISS: () => undefined, EXPIRE: () => undefined},
+})
+
+// ── the toaster ──────────────────────────────────────────────────────
+const polite = (t: any) => t.kind != 'error'
+const urgent = (t: any) => t.kind == 'error'
+// entering or leaving the region (not moving between its children)
+const crossing = (e: any) => !e.ownerTarget?.contains?.(e.relatedTarget)
+const paused = (s: any, p: boolean) => ({...s, paused: p, toasts: s.toasts.map((t: any) => ({...t, paused: p}))})
+// the pointer or the focus came in or left: paused while either is in (unless pauseOnHover={false})
+const pause = (s: any, k: string, on: boolean, p: any) => {
+  if (s[k] === on) return ABORT
+  const n = {...s, [k]: on}, z = p.pauseOnHover !== false && !!(n.hover || n.focus)
+  return z === s.paused ? n : paused(n, z)
+}
+// ids compare as strings (the Collection's keys do: 7 and '7' are one toast)
+const same = (a: any, b: any) => '' + a === '' + b
+
+/** Renders the toasts that `event('TOAST', { text, kind, timeoutMs })` sends from anywhere. Render it once: `<Toaster />`. */
+export const Toaster = /*#__PURE__*/ Object.assign(function Toaster({state, label = 'Notifications', dismissLabel = 'Dismiss', transition = 'toast', duration = 200, className}: any) {
+  const list = (filter: any) => h('div', {className: 'toaster-list'}, h(Collection, {of: ToastItem, from: 'toasts', filter, dismissLabel, transition, duration}))
+  return h('div', {className: 'toaster-home'},
+    h('section', {
+      className: className ? 'toaster ' + className : 'toaster', 'aria-label': label, attrs: {popover: 'manual'},
+      'data-paused': state.paused ? '' : undefined, hook: placement,
+    },
+    h('div', {className: 'toaster-status', role: 'status', 'aria-live': 'polite'}, list(polite)),
+    h('div', {className: 'toaster-alert', role: 'alert'}, list(urgent))))
+}, {
+  componentName: 'Toaster',
+  isolatedState: true,
+  initialState: {toasts: [] as any[], next: 1, paused: false, hover: false, focus: false},
+  intent: ({EVENTS, DOM}: any) => ({
+    TOAST: EVENTS.select('TOAST'),
+    DISMISS: EVENTS.select('TOAST_DISMISS'),
+    // G-399: the pointer and the focus apart (the timers stop while either is in the region)
+    HOVER: xs.merge(DOM.pointerover('.toaster').filter(crossing).mapTo(true), DOM.pointerout('.toaster').filter(crossing).mapTo(false)),
+    FOCUS: xs.merge(DOM.focusin('.toaster').filter(crossing).mapTo(true), DOM.focusout('.toaster').filter((e: any) => left(e.ownerTarget, e)).mapTo(false)),
+  }),
+  model: {
+    TOAST: (s: any, d: any) => {
+      const t = typeof d == 'string' ? {text: d} : d || {}
+      // G-398: an automatic id is 't<n>', one no shown toast has (a user's 2 or '2' never meets it)
+      const i = t.id == null ? -1 : s.toasts.findIndex((x: any) => same(x.id, t.id))
+      let n = s.next, id = t.id
+      if (id == null) { while (s.toasts.some((x: any) => same(x.id, 't' + n))) n++; id = 't' + n++ }
+      const toast = {...t, id, kind: t.kind || 'info', timeoutMs: t.timeoutMs ?? 5000, paused: s.paused, rev: i < 0 ? 0 : s.toasts[i].rev + 1}
+      return {
+        ...s,
+        next: n,
+        toasts: i < 0 ? [...s.toasts, toast] : s.toasts.map((x: any, j: number) => (j == i ? toast : x)),
+      }
+    },
+    DISMISS: (s: any, id: any) => {
+      const toasts = id == null ? [] : s.toasts.filter((x: any) => !same(x.id, id))
+      return toasts.length == s.toasts.length ? ABORT : {...s, toasts}
+    },
+    HOVER: (s: any, on: boolean, _n: any, p: any) => pause(s, 'hover', on, p),
+    FOCUS: (s: any, on: boolean, _n: any, p: any) => pause(s, 'focus', on, p),
+  },
+})

package/src/ui/tooltip.ts

@@ -0,0 +1,70 @@
+/*
+ * PLAN-5 2-U (S-3, from spike 0-S3): Tooltip, a manual popover placed by CSS anchor positioning,
+ * shown on hover / focus after a delay and hidden after a delay (D197 `timers`).
+ *
+ *   Toolbar.uses = { saveTip: tooltip({ trigger: '.save', tip: '.save-tip' }) }
+ *
+ * The host renders the trigger with aria-describedby (the tip's id) and `anchor-name`, and the
+ * tip with role="tooltip", popover="manual", `position-anchor` and `position-area` (styles; see
+ * the guide). No JavaScript positioning.
+ *
+ * Options: `trigger`, `tip` (required), `showDelay` (500 ms), `hideDelay` (100 ms).
+ * State: { open, pending: null | 'show' | 'hide', hover, focus }. Actions: ENTER / LEAVE (data
+ * 'hover' | 'focus': the pointer on the trigger or the tip (it stays open while hovered, WCAG
+ * 1.4.13), or the focus on the trigger), SHOW / HIDE (the timers), ESCAPE (hides it at once),
+ * TOGGLED. Timers (joined to the host's `timers`): '<key>.show' / '<key>.hide'; one whose state
+ * goes away is cancelled, so leaving before the delay never shows the tip. Needs
+ * makeTimerDriver() (tests: fake timers).
+ * G-403: the pointer and the focus are tracked apart (it hides once both have left: a mouse
+ * leaving doesn't hide a tip the keyboard focus still shows); touch pointer events are ignored
+ * (a tap focuses the trigger instead); the document keydown listener for Escape is there only
+ * while the tip is shown or about to be, so a page of tooltips has at most the open one's.
+ */
+import {ABORT, defineBehavior, dropRepeats, xs} from '../index'
+
+const mouse = (e: any) => e?.pointerType != 'touch'
+const which = (k: any) => (k == 'focus' ? 'focus' : 'hover')
+
+const base = /*#__PURE__*/ defineBehavior({
+  initialState: {open: false, pending: null as null | string, hover: false, focus: false},
+  timers: (s: any, o: any) => ({
+    show: s?.pending == 'show' && {after: o.showDelay ?? 500, action: 'SHOW'},
+    hide: s?.pending == 'hide' && {after: o.hideDelay ?? 100, action: 'HIDE'},
+  }),
+  intent: ({DOM, STATE}: any, {trigger, tip}: any) => ({
+    ENTER: xs.merge(xs.merge(DOM.pointerenter(trigger), DOM.pointerenter(tip)).filter(mouse).mapTo('hover'), DOM.focus(trigger).mapTo('focus')),
+    LEAVE: xs.merge(xs.merge(DOM.pointerleave(trigger), DOM.pointerleave(tip)).filter(mouse).mapTo('hover'), DOM.blur(trigger).mapTo('focus')),
+    ESCAPE: (STATE ? STATE.stream.map((s: any) => !!(s?.open || s?.pending)).compose(dropRepeats()) : xs.of(true))
+      .map((on: boolean) => (on ? DOM.keydown('document').key().filter((k: string) => k == 'Escape') : xs.never()))
+      .flatten(),
+    TOGGLED: DOM.toggle(tip).map((e: any) => e.newState == 'open'),
+  }),
+  model: {
+    ENTER: (s: any, k: any) => {
+      const n = {...s, [which(k)]: true}, pending = s.open ? null : 'show'
+      return s[which(k)] && s.pending == pending ? ABORT : {...n, pending}
+    },
+    LEAVE: (s: any, k: any) => {
+      const n = {...s, [which(k)]: false}
+      // still hovered or focused: as it was
+      const pending = n.hover || n.focus ? s.pending : s.open ? 'hide' : null
+      return !s[which(k)] && s.pending == pending ? ABORT : {...n, pending}
+    },
+    SHOW: {
+      STATE: (s: any) => ({...s, pending: null}),
+      ELEMENT: (s: any, _d: any, _n: any, _p: any, o: any) => (s.open ? ABORT : {showPopover: o.tip}),
+    },
+    HIDE: {
+      STATE: (s: any) => ({...s, pending: null}),
+      ELEMENT: (s: any, _d: any, _n: any, _p: any, o: any) => (s.open ? {hidePopover: o.tip} : ABORT),
+    },
+    ESCAPE: {
+      STATE: (s: any) => (s.open || s.pending ? {...s, pending: null} : ABORT),
+      ELEMENT: (s: any, _d: any, _n: any, _p: any, o: any) => (s.open ? {hidePopover: o.tip} : ABORT),
+    },
+    TOGGLED: (s: any, open: boolean) => (s.open == open ? ABORT : {...s, open}),
+  },
+})
+
+/** A tooltip as a behavior: `uses = { tip: tooltip({ trigger: '.save', tip: '.save-tip', showDelay: 500 }) }`. */
+export const tooltip = (options: any = {}): any => base({...options, open: false, pending: null, hover: false, focus: false})

package/src/ui/zag/combobox.ts

@@ -0,0 +1,115 @@
+/*
+ * PLAN-5 2-Z (U-1): Combobox, a Zag combobox machine (WAI-ARIA editable combobox with a listbox
+ * popup) as a widget tag.
+ *
+ *   <Combobox className="city" label="City" items={CITIES} value={state.city} placeholder="Type a city" />
+ *   intent: CITY: DOM.select('.city').events('value-change').detail()   // 'Paris'
+ *
+ * Renders a label, the input (role="combobox", aria-autocomplete="list", aria-activedescendant
+ * on the highlighted option), a trigger button, and the listbox in a positioner. The items are
+ * filtered as the user types: by default the labels that contain the text (case-insensitive);
+ * `filter={(item, text) => boolean}` replaces the test, `filter={false}` leaves it to the app (it
+ * passes the `items` to show, from `input-change`). The filter text resets when the list closes.
+ * Keyboard is Zag's: ArrowDown / ArrowUp open and move, Enter selects, Escape closes, Home / End
+ * in the input move the caret. Styling hooks: `data-scope="combobox"` + `data-part` (root, label,
+ * control, input, trigger, positioner, content, item, item-text, item-indicator), `data-state`,
+ * `data-highlighted`.
+ *
+ * Forms (G-411): with `name`, hidden inputs submit the value (one per value when `multiple`);
+ * the visible input, which shows the label, has no name. `form` goes on the hidden inputs (G-434).
+ * With `allowCustomValue` (single), the selected value is submitted unless the user typed since
+ * the last selection; then the typed text (an item's exact label submits that item's value; G-435,
+ * G-468).
+ *
+ * Props: `label`, `items` (strings or { value, label?, disabled? }), `value` (controlled: a
+ * string, an array when `multiple`, null for none), `defaultValue`, `placeholder`, `filter`, and
+ * Zag's combobox props (`multiple`, `name`, `form`, `disabled`, `readOnly`, `required`,
+ * `invalid`, `allowCustomValue`, `openOnClick`, `inputBehavior`, `selectionBehavior`,
+ * `closeOnSelect`, `loopFocus`, `positioning`, `open`, `id`). Events: `value-change` (the value,
+ * or the values when multiple), `input-change` (the text the user typed), `open-change` (boolean).
+ * Commands: `open`, `close`, `clear`, `focus` (the input).
+ */
+import * as combobox from '@zag-js/combobox'
+import {fromZag} from '../../zag'
+import {createElement as h} from '../../index'
+import {NAMING, arr, collectionOf, named, norm, options, valueOut} from './shared'
+
+const shown = (all: any[], f: any, q: string) => {
+  if (f === false || !q) return all
+  const l = q.toLowerCase()
+  return all.filter((i) => (typeof f == 'function' ? f(i, q) : String(i.label).toLowerCase().includes(l)))
+}
+
+// the filter text: what the user typed; '' when the list closes
+const setText = (x: any, q: string) => { if (x.q !== q) x.q = q, x.refresh() }
+
+// G-411: forms get the value, not the label the input shows: the visible input has no name; one
+// hidden input per value (a single combobox: one, '' when empty) carries `name`.
+// G-435 / G-468: a single combobox with `allowCustomValue` submits the selected value unless the
+// user typed since the last selection (`x.t`: set by input-change, cleared by a selection, a value
+// change or a new controlled value that isn't empty: G-494); then the value of an item whose label the text is, else the
+// text itself. So `selectionBehavior` 'preserve' / 'clear', items relabelled after a pick and a
+// `defaultValue` before the items load all submit the value.
+const submitted = (api: any, x: any): string => {
+  const v = api.value[0] ?? ''
+  if (!x.custom || !x.t) return v
+  const q = api.inputValue
+  return x.items.find((i: any) => i.label === q)?.value ?? q
+}
+const hidden = (api: any, p: any, x: any) => {
+  if (p.name == null) return null
+  const vs = x.multiple ? api.value : [submitted(api, x)]
+  // G-434: `form` as an attribute (HTMLInputElement.form is a read-only property)
+  const attrs = p.form == null ? undefined : {form: p.form}
+  return vs.map((value: string, i: number) => h('input', {key: 'h' + i, type: 'hidden', name: p.name, attrs, disabled: !!p.disabled, value}))
+}
+
+export const Combobox: any = /*#__PURE__*/ fromZag(combobox, (api: any, p: any, x: any) => {
+  const input = named(api.getInputProps(), p, 1)
+  delete input.attrs.name
+  delete input.attrs.form
+  return h('div', api.getRootProps(),
+    p.label != null && h('label', api.getLabelProps(), p.label),
+    h('div', api.getControlProps(),
+      h('input', {...input, placeholder: p.placeholder}),
+      h('button', api.getTriggerProps(), '▾')),
+    h('div', api.getPositionerProps(), h('div', named(api.getContentProps(), p), options(h, api))),
+    hidden(api, p, x))
+}, {
+  name: 'Combobox',
+  $own: 1,
+  ownProps: [...NAMING, 'name'],
+  props: ({items, label, placeholder, value, defaultValue, filter, 'aria-label': _l, 'aria-labelledby': _b, 'aria-describedby': _d, ...p}: any, x: any) => {
+    x.multiple = !!p.multiple
+    x.custom = !!p.allowCustomValue
+    x.items = norm(items)
+    // G-468: a new controlled value ends the typing. G-494: not an empty one (an app that clears
+    // its value on input-change: the typed text is still what is submitted)
+    const v = arr(value), k = v && JSON.stringify(v)
+    if (k !== x.v) x.v = k, v?.length && (x.t = 0)
+    return {
+      ...p,
+      collection: collectionOf(combobox, shown(x.items, filter, x.q || '')),
+      value: v,
+      defaultValue: arr(defaultValue),
+      // typing only (not the label a selection writes): the filter text, and input-change
+      // G-414: the app's own callbacks (p.onInputValueChange / p.onOpenChange) run first
+      onInputValueChange: (d: any) => { p.onInputValueChange?.(d); if (d.reason == 'input-change') x.t = 1, setText(x, d.inputValue), x.dispatch('input-change', d.inputValue) },
+      onSelect: (d: any) => { x.t = 0; p.onSelect?.(d) },
+      onValueChange: (d: any) => { x.t = 0; p.onValueChange?.(d) },
+      onOpenChange: (d: any) => { p.onOpenChange?.(d); d.open || setText(x, '') },
+    }
+  },
+  events: {
+    'value-change': ['onValueChange', valueOut],
+    'input-change': null,
+    'open-change': ['onOpenChange', (d: any) => d.open],
+  },
+  commands: {
+    open: (api: any) => api.setOpen(true),
+    close: (api: any) => api.setOpen(false),
+    clear: (api: any) => api.clearValue(),
+    focus: (api: any) => api.focus(),
+  },
+  fallback: (p: any, hh: any) => hh('div', null, p.label != null && hh('label', null, p.label), hh('input', {placeholder: p.placeholder, disabled: true})),
+})

package/src/ui/zag/menu.ts

@@ -0,0 +1,40 @@
+/*
+ * PLAN-5 2-Z (U-1): Menu, a Zag menu machine (WAI-ARIA menu button) as a widget tag.
+ *
+ *   <Menu className="actions" label="Actions" items={[{ value: 'edit', label: 'Edit' }, { value: 'delete', label: 'Delete', disabled: true }]} />
+ *   intent: PICK: DOM.select('.actions').events('select').detail()     // 'edit'
+ *   model:  OPEN_ACTIONS: { ELEMENT: { open: '.actions' } }
+ *
+ * Renders a trigger button (its text: `label`) and the menu (role="menu", items role="menuitem")
+ * in a positioner. Keyboard, focus and typeahead are Zag's: Enter / Space / ArrowDown open it on
+ * the first item (ArrowUp on the last), the arrows move, Home / End, typing jumps to an item,
+ * Enter / click selects and closes, Escape / Tab / a click outside closes; the focus returns to
+ * the trigger. Styling hooks: Zag's `data-scope="menu"` + `data-part` (trigger, positioner,
+ * content, item, separator), `data-state`, `data-highlighted`, `data-disabled`.
+ *
+ * Props: `label`, `items` (strings, or { value, label?, disabled? }, or { separator: true }), and
+ * Zag's menu props (`open` controlled, `defaultOpen`, `closeOnSelect`, `loopFocus`, `typeahead`,
+ * `positioning`, `dir`, `id`). Events: `select` (the item's value), `open-change` (boolean).
+ * Commands: `open`, `close`.
+ */
+import * as menu from '@zag-js/menu'
+import {fromZag} from '../../zag'
+import {createElement as h} from '../../index'
+import {NAMING, named, norm} from './shared'
+
+export const Menu: any = /*#__PURE__*/ fromZag(menu, (api: any, p: any) => [
+  h('button', named(api.getTriggerProps(), {...p, label: 1}, 1), p.label),
+  h('div', api.getPositionerProps(),
+    h('div', api.getContentProps(),
+      norm(p.items).map((i: any) => (i.separator
+        ? h('hr', api.getSeparatorProps())
+        : h('div', {key: i.value, ...api.getItemProps({value: i.value, disabled: !!i.disabled})}, i.label))))),
+], {
+  name: 'Menu',
+  $own: 1,
+  ownProps: NAMING,
+  props: ({items, label, 'aria-label': _l, 'aria-labelledby': _b, 'aria-describedby': _d, ...p}: any) => p,
+  events: {select: ['onSelect', (d: any) => d.value], 'open-change': ['onOpenChange', (d: any) => d.open]},
+  commands: {open: (api: any) => api.setOpen(true), close: (api: any) => api.setOpen(false)},
+  fallback: (p: any, hh: any) => hh('button', {type: 'button', 'aria-haspopup': 'menu', 'aria-expanded': false}, p.label),
+})

package/src/ui/zag/select.ts

@@ -0,0 +1,54 @@
+/*
+ * PLAN-5 2-Z (U-1): Select, a Zag select machine (WAI-ARIA select-only combobox + listbox) as a
+ * widget tag.
+ *
+ *   <Select className="size" label="Size" items={['S', 'M', 'L']} value={state.size} placeholder="Pick a size" name="size" />
+ *   intent: SIZE: DOM.select('.size').events('value-change').detail()   // 'M' (multiple: ['M', 'L'])
+ *
+ * Renders a label, a trigger button (role="combobox", named by the label) showing the selected
+ * label or the placeholder, the listbox (items role="option", aria-selected, a ✓ indicator Zag
+ * hides when unselected) in a positioner, and a hidden native <select> for forms (`name`).
+ * Keyboard and typeahead are Zag's. Styling hooks: `data-scope="select"` + `data-part` (root,
+ * label, control, trigger, value-text, indicator, positioner, content, item, item-text,
+ * item-indicator), `data-state`, `data-highlighted`, `data-placeholder-shown`.
+ *
+ * Props: `label`, `items` (strings or { value, label?, disabled? }), `value` (controlled: a
+ * string, or an array when `multiple`; null for none), `defaultValue`, `placeholder`, and Zag's
+ * select props (`multiple`, `name`, `form`, `disabled`, `required`, `readOnly`, `invalid`,
+ * `deselectable`, `closeOnSelect`, `loopFocus`, `positioning`, `open`, `id`). Events:
+ * `value-change` (the value, or the values when multiple), `open-change` (boolean).
+ * Commands: `open`, `close`, `clear`, `focus` (the trigger).
+ */
+import * as select from '@zag-js/select'
+import {fromZag} from '../../zag'
+import {createElement as h} from '../../index'
+import {NAMING, arr, collectionOf, named, norm, options, valueOut} from './shared'
+
+export const Select: any = /*#__PURE__*/ fromZag(select, (api: any, p: any, x: any) => {
+  const hidden = api.getHiddenSelectProps(), v = api.value
+  // multiple: the options' selected props carry the value (a select's value prop is one string)
+  if (x.multiple) delete hidden.props.value
+  if (p.label == null) delete hidden.attrs['aria-labelledby']
+  return h('div', api.getRootProps(),
+    p.label != null && h('label', api.getLabelProps(), p.label),
+    h('div', api.getControlProps(),
+      h('button', named(api.getTriggerProps(), p, 1),
+        h('span', api.getValueTextProps(), api.valueAsString || p.placeholder || ''),
+        h('span', api.getIndicatorProps(), '▾'))),
+    h('div', api.getPositionerProps(), h('div', named(api.getContentProps(), p), options(h, api))),
+    h('select', hidden,
+      h('option', {value: ''}),
+      x.items.map((i: any) => h('option', {key: i.value, value: i.value, selected: v.includes(i.value)}, i.label))))
+}, {
+  name: 'Select',
+  $own: 1,
+  ownProps: [...NAMING, 'name'],
+  props: ({items, label, placeholder, value, defaultValue, 'aria-label': _l, 'aria-labelledby': _b, 'aria-describedby': _d, ...p}: any, x: any) => {
+    x.items = norm(items)
+    x.multiple = !!p.multiple
+    return {...p, collection: collectionOf(select, x.items), value: arr(value), defaultValue: arr(defaultValue)}
+  },
+  events: {'value-change': ['onValueChange', valueOut], 'open-change': ['onOpenChange', (d: any) => d.open]},
+  commands: {open: (api: any) => api.setOpen(true), close: (api: any) => api.setOpen(false), clear: (api: any) => api.clearValue(), focus: (api: any) => api.focus()},
+  fallback: (p: any, hh: any) => hh('div', null, p.label != null && hh('label', null, p.label), hh('button', {type: 'button', disabled: true}, p.placeholder || '')),
+})

package/src/ui/zag/shared.ts

@@ -0,0 +1,43 @@
+/*
+ * PLAN-5 2-Z: helpers the Zag-based parts (Menu, Select, Combobox) share. '../../zag' becomes the
+ * external 'sygnal/zag' and '../../index' the external 'sygnal' in the 'sygnal/ui/menu', 'sygnal/ui/select' and 'sygnal/ui/combobox' builds.
+ */
+
+/** G-413: the naming props a part applies to its control (not the host) */
+export const NAMING = ['aria-label', 'aria-labelledby', 'aria-describedby']
+
+/**
+ * A control's (or listbox's) Zag props named from the part's props: without a label element, no
+ * aria-labelledby to it; the props' aria-label / aria-labelledby (/ aria-describedby) win
+ */
+export const named = (bag: any, p: any, describe?: any) => {
+  const a = bag.attrs
+  if (p.label == null) delete a['aria-labelledby']
+  for (const k of NAMING) if (p[k] != null && (describe || k != 'aria-describedby')) a[k] = p[k]
+  if (p['aria-labelledby'] != null) delete a['aria-label']
+  return bag
+}
+
+/** An item as the parts take it: a string, or { value, label?, disabled? } (Menu also { separator: true }) */
+export const norm = (items: any): any[] =>
+  (items || []).map((i: any) => (i && typeof i == 'object'
+    ? {...i, value: String(i.value ?? ''), label: i.label ?? String(i.value ?? '')}
+    : {value: String(i), label: String(i)}))
+
+/** A Select / Combobox value prop as Zag's string[] (undefined: uncontrolled; null or '': none) */
+export const arr = (v: any): any =>
+  v === undefined ? undefined : v == null || v === '' ? [] : Array.isArray(v) ? v.map(String) : [String(v)]
+
+/** The listbox collection options for Zag's collection() */
+export const collectionOf = (z: any, items: any[]) =>
+  z.collection({items, itemToValue: (i: any) => i.value, itemToString: (i: any) => i.label, isItemDisabled: (i: any) => !!i.disabled})
+
+/** value-change's detail: the value (single) or the values (multiple) */
+export const valueOut = (d: any, x: any) => (x.multiple ? d.value : d.value[0] ?? null)
+
+/** Item rows of a listbox (Select, Combobox): text + a ✓ indicator Zag hides when unselected */
+export const options = (h: any, api: any) =>
+  api.collection.items.map((item: any) =>
+    h('div', {key: item.value, ...api.getItemProps({item})},
+      h('span', api.getItemTextProps({item}), item.label),
+      h('span', api.getItemIndicatorProps({item}), '✓')))

package/src/ui-combobox.d.ts

@@ -0,0 +1,20 @@
+// 'sygnal/ui/combobox' (PLAN-5 U-1, D202/D203/D211): Combobox on Zag.js's combobox machine.
+// Needs @zag-js/vanilla and @zag-js/combobox (optional peer dependencies, ~1.45.0).
+import type { Widget } from 'sygnal'
+import type { ZagInstance } from 'sygnal/zag'
+import type { UiItem, UiPositioning, ListboxProps } from './ui-zag-types'
+export type { UiItem, UiPositioning, ListboxProps } from './ui-zag-types'
+
+export interface ComboboxProps extends ListboxProps {
+  /** The items shown for the typed text: default, labels containing it (case-insensitive); false: none (the app filters `items` from `input-change`) */
+  filter?: false | ((item: { value: string; label: string; disabled?: boolean }, text: string) => boolean)
+  allowCustomValue?: boolean
+  openOnClick?: boolean
+  inputBehavior?: 'autohighlight' | 'autocomplete' | 'none'
+  selectionBehavior?: 'clear' | 'replace' | 'preserve'
+}
+/**
+ * An editable combobox (Zag combobox). Events: `value-change`, `input-change` (the typed text),
+ * `open-change`. Commands: `open`, `close`, `clear`, `focus`.
+ */
+export const Combobox: Widget<ComboboxProps, ZagInstance, 'value-change' | 'input-change' | 'open-change'>

package/src/ui-combobox.ts

@@ -0,0 +1,6 @@
+// 'sygnal/ui/combobox' (PLAN-5 U-1, D202/D203/D211): Combobox, a widget tag on Zag.js's combobox machine
+// (fromZag). A subpath per part (D211), so an app that uses Combobox installs only @zag-js/vanilla and
+// @zag-js/combobox (optional peer dependencies, ~1.45.0), and 'sygnal/ui' (the native parts) never
+// needs Zag. Rollup turns '../../zag' into the external 'sygnal/zag' (fromZag ships once when an
+// app uses several parts) and '../../index' into 'sygnal'.
+export {Combobox} from './ui/zag/combobox'