sygnal 5.4.0 → 6.0.0

package/dist/guide/ssr.md

@@ -0,0 +1,255 @@
+<!-- Generated from docs/src/content/docs/integration by scripts/copy-guides.mjs; online: https://sygnal.js.org/integration/ -->
+# Server-Side Rendering
+
+`renderToString()` renders a Sygnal component to an HTML string without a browser DOM. Use it for server-rendered pages, static site generation, or any environment where you need HTML output from your components.
+
+```ts
+import { renderToString } from 'sygnal'
+
+const html = renderToString(App, { state: { count: 0 } })
+// → '<div class="counter" data-sygnal-ssr=""><h1>Count: 0</h1><button>+</button></div>'
+```
+
+The root element carries an empty `data-sygnal-ssr` attribute. It marks the markup as Sygnal's server HTML, so the client can tell it from other content in the mount point (a [persisted](./persistence.md#server-rendering-hydrate) app restores its saved state after the first render instead of before it). The first client render removes it.
+
+## Basic Usage
+
+Pass a component function and optional state:
+
+```jsx
+function Greeting({ state }) {
+  return <div className="greeting">Hello, {state.name}!</div>
+}
+
+Greeting.initialState = { name: 'World' }
+
+// Uses component's initialState
+renderToString(Greeting)
+// → '<div class="greeting" data-sygnal-ssr="">Hello, World!</div>'
+
+// Override state
+renderToString(Greeting, { state: { name: 'Alice' } })
+// → '<div class="greeting" data-sygnal-ssr="">Hello, Alice!</div>'
+```
+
+## Sub-Components
+
+Sub-components are rendered recursively. State lensing works the same as in the browser — pass `state="propName"` to scope child state:
+
+```jsx
+function App({ state }) {
+  return (
+    <div>
+      <Header state="header" />
+      <Content state="content" />
+    </div>
+  )
+}
+
+App.initialState = {
+  header: { title: 'My App' },
+  content: { body: 'Welcome' },
+}
+
+renderToString(App)
+// Renders both Header and Content with their scoped state
+```
+
+## Collections
+
+Collections render each item from the state array:
+
+```jsx
+function TodoItem({ state }) {
+  return <li>{state.text}</li>
+}
+
+function TodoList({ state }) {
+  return (
+    <ul>
+      <Collection of={TodoItem} from="items" />
+    </ul>
+  )
+}
+
+TodoList.initialState = {
+  items: [
+    { id: 1, text: 'Buy milk' },
+    { id: 2, text: 'Write docs' },
+  ],
+}
+
+renderToString(TodoList)
+// → '<ul data-sygnal-ssr=""><div><li>Buy milk</li><li>Write docs</li></div></ul>'
+```
+
+## Context
+
+Component context is computed from state and propagated to descendants:
+
+```jsx
+function App({ state, context }) {
+  return <div className={`theme-${context.theme}`}>{state.label}</div>
+}
+
+App.initialState = { label: 'Hello', darkMode: true }
+App.context = { theme: (state) => state.darkMode ? 'dark' : 'light' }
+
+renderToString(App)
+// → '<div class="theme-dark" data-sygnal-ssr="">Hello</div>'
+```
+
+## Error Boundaries
+
+Error boundaries work during SSR. Components with `onError` render fallback content; those without render an empty `<div data-sygnal-error>`:
+
+```jsx
+function Fragile({ state }) {
+  throw new Error('Oops')
+}
+
+Fragile.onError = (err, { componentName }) => (
+  <div className="error">Something went wrong in {componentName}</div>
+)
+
+renderToString(Fragile)
+// → '<div class="error" data-sygnal-ssr="">Something went wrong in Fragile</div>'
+```
+
+To report these errors, pass the [app-level error hook](./error-boundaries.md#app-level-error-hook): `renderToString(App, { onError })`. It is called with the phase `'view'`, after the boundary picked the fallback.
+
+## Special Components
+
+| Component | SSR Behavior |
+|-----------|-------------|
+| **Portal** | Children rendered inline (no target container on server) |
+| **Transition** | Unwrapped to child element (no animation) |
+| **Suspense** | Always renders children (not fallback) |
+| **Slot** | Unwrapped to children |
+| **Collection** | Items rendered from state array |
+| **Switchable** | Active component rendered based on state |
+
+## Client Hydration
+
+Embed serialized state in a `<script>` tag for client-side rehydration:
+
+```jsx
+const html = renderToString(App, {
+  state: { count: 5 },
+  hydrateState: true,
+})
+// Appends: <script>window.__SYGNAL_STATE__={"count":5}</script>
+```
+
+Use a custom variable name:
+
+```jsx
+renderToString(App, {
+  state: { count: 5 },
+  hydrateState: '__MY_APP_STATE__',
+})
+// Appends: <script>window.__MY_APP_STATE__={"count":5}</script>
+```
+
+:::caution[Multiple apps on one page]
+If you render more than one Sygnal app on the same page, use unique variable names to avoid collisions:
+
+```jsx
+renderToString(Header, { state: headerState, hydrateState: '__HEADER_STATE__' })
+renderToString(Sidebar, { state: sidebarState, hydrateState: '__SIDEBAR_STATE__' })
+```
+
+`hydrateState: true` writes to `window.__SYGNAL_STATE__`, which is fine for single-app pages but will collide if used twice. This does not apply to Astro — each island hydrates independently through Astro's own mechanism.
+:::
+
+On the client, read the embedded state to hydrate:
+
+```jsx
+import { run } from 'sygnal'
+
+const initialState = window.__SYGNAL_STATE__ || App.initialState
+
+run(App, '#app', { initialState })
+```
+
+### What the first client render keeps
+
+`run()` doesn't clear the mount point. Its first render patches the server's markup in place and **adopts** each element that matches what the client renders at the same position (the same tag; keyed children such as component roots and `Collection` items match by key). An adopted element stays the same DOM node, so everything the user did before the app started is kept: the focus, text typed into an uncontrolled field, a checked box, the scroll position. The same applies to [Astro islands](https://sygnal.js.org/integration/astro/) and [Vike pages](https://sygnal.js.org/integration/vike/), which both hydrate this way.
+
+| Server markup | First client render |
+|---|---|
+| An element the client renders with the same tag | Adopted: the same node. Its attributes become the client's: the ones the client also renders keep the server's value (nothing is written again, so an `iframe` or `img` doesn't reload), and attributes the client doesn't render are removed |
+| `class` and `id` | Kept when the client's are the same, changed or removed when they aren't |
+| `style` | Written again from the client's `style`: a declaration only the server wrote goes |
+| `data-*` | Kept when the client renders them (as `data-*` props or in `attrs`), removed when it doesn't; `data-sygnal-ssr` (the root's marker) goes |
+| `open` on a `<details>` or `<dialog>` the client renders without `open` | Kept: the user may have opened it before start-up. When the client renders `open` (`open={isOpen}`, also `false`), its value wins. A conditional spread (`{...(isOpen && { open: true })}`) renders no `open` at all when closed, so a server `open` stays: write `open={isOpen}` to control it |
+| A text node | Kept, its text set to the client's. Text next to text in the client's view (`Hello, {name}!`: three text nodes) is one text node in the server's HTML: it is split where the client's first text ends, when it starts with that text, so the elements after it are still adopted |
+| A `<textarea>`'s text (`renderToString` writes its `value` as text) | The text node goes; the field keeps its value (the server's text, or what the user typed) |
+| A component that returns a fragment (`<>…</>`), or a `false` / `null` child (`{cond && <X />}`) | A fragment's elements are adopted one by one, as its parent's own children; a `false` / `null` child takes no element: the elements after them are still adopted. Later renders update, add, remove and move them as on a client-only page |
+| Whitespace and comments where the client renders no text (a page template's indentation) | Removed |
+| An element with another tag, or text where the client renders an element | Replaced in place by the client's element; the elements around it are still adopted |
+| An element whose vnode has an `insert` hook: a `<Transition>`'s child (its enter runs), a `<VirtualCollection>` row (measured when inserted), the `<Toaster>` region, a `lazy()` placeholder, an element with your own `hook={{ insert }}` (also with a `postpatch`, a `ref` or `autoFocus`) | Made again in place, as a fresh render makes it: its `insert` runs |
+| An element with a `create` or `init` hook (a `thunk`) | Made again in place; its hooks run |
+| An element whose hyperscript selector has a class or id (`h('p.card')`; JSX never makes one), and a `<Portal>`'s placeholder | Made again in place (patching never changes a selector's class or id) |
+| An element with a `ref`, `autoFocus`, a widget, a `<VirtualCollection>` container, or your own hook without `insert` | Adopted: `ref` points at the server's element, `autoFocus` focuses it, a widget mounts on it. A hook's `postpatch` runs |
+| A `<Portal>`'s content (the server renders it inline) | Replaced by the Portal's placeholder; the content renders in the target |
+| A custom element that builds its own light DOM (children the client doesn't render), already upgraded before start-up | Adopted, but those children are removed (they aren't the client's) and its `connectedCallback` doesn't run again. Wrap such an element in [`<ClientOnly>`](https://sygnal.js.org/integration/vike/#clientonly) (`sygnal/vike/ClientOnly`) so the client makes it |
+| The mount point's own attributes (`<div id="app" class="shell" data-theme="dark">`) | Kept: they aren't the app's (when the app's root element is the mount point itself, its props are written over them) |
+
+Form fields follow the usual rule for [controlled fields](./inputs.md#controlled-inputs): a field with a `value` (or `checked`) prop shows the state, so the client's value replaces what the user typed or picked before start-up (an `input`, a `textarea` and a `select` alike); a field without one keeps it.
+
+When the server's markup differs from what the client renders (other state, a mismatched template), the page ends up as a fresh client render would make it. This also holds when the mount point holds something else before start-up (a loading spinner): it is patched into the app. The exceptions are the user's changes listed above: an uncontrolled field's value, an `open` the client doesn't render.
+
+## Stable ids: uid
+
+[`uid()`](./inputs.md#labels-and-ids-uid) ids come from each component's position in the tree, not from a counter, so `renderToString` and the client produce the same ids and hydration keeps the server's `for` / `id` pairs. Both start from the root `u`. When a page has more than one app, give each its own root, and the same one on both sides:
+
+```jsx
+// server
+const html = renderToString(Signup, { uid: 'signup' })
+
+// client, hydrating that markup
+run(Signup, {}, { mountPoint: '#signup', uid: 'signup' })
+```
+
+The ids then start with `signup-` (`signup-email`). In [Astro](https://sygnal.js.org/integration/astro/#props), pass a `uid` prop to the island; in [Vike](https://sygnal.js.org/integration/vike/), the Page, Layouts and Wrappers get matching ids on both sides without any option.
+
+## Astro Integration
+
+The Astro server renderer uses `renderToString` internally. When using the Sygnal Astro integration, SSR happens automatically:
+
+```astro
+---
+import Counter from '../components/Counter.jsx'
+---
+<Counter client:load />
+```
+
+## API
+
+```typescript
+function renderToString(
+  component: ComponentFunction,
+  options?: RenderToStringOptions
+): string
+```
+
+### RenderToStringOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `state` | `any` | Component's `.initialState` | State for the root component |
+| `props` | `Record<string, any>` | `{}` | Props to pass to the component |
+| `context` | `Record<string, any>` | `{}` | Parent context to merge with |
+| `hydrateState` | `boolean \| string` | — | Embed state in `<script>` tag |
+| `head` | `any[]` | — | Receives each rendered component's `head` static ([HEAD driver](https://sygnal.js.org/guide/head/)) |
+| `cache` | `QueryCache` | — | A seeded `queryCache()`: `resources` found in it render as `'success'` with their data, others as `'loading'` ([Server rendering](./resources.md#server-rendering)) |
+| `onError` | `(error, info) => void` | — | [App-level error hook](./error-boundaries.md#app-level-error-hook), called with the phase `'view'` |
+| `uid` | `string` | `'u'` | The root of the [`uid()`](#stable-ids-uid) ids; use the same value as `run()`'s `uid` on the client |
+
+## Limitations
+
+- **Intent and Model are skipped** — SSR is render-only. Event handlers, streams, and state reducers don't run on the server.
+- **No requests** — drivers don't run, so `resources` render as `'loading'` unless the `cache` option has them; seed it in a loader with `cache.set(request, data)` and send `cache.dehydrate()` to the client ([Server rendering](./resources.md#server-rendering)).
+- **Refs are not populated** — No DOM exists, so `createRef()` objects remain `{ current: null }`.
+- **Lazy components** — `lazy()` wrappers render their loading placeholder. For SSR, import components directly instead.

package/dist/guide/timers.md

@@ -0,0 +1,178 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Timers
+
+A component declares the timers it needs as a function of its state, and gets each tick as one of its own actions. There is no `setInterval` to start or clear: while `state.running` is true the tick runs, and when it turns false the timer stops.
+
+```jsx
+Stopwatch.timers = (state) => ({
+  tick: state.running && { every: 100, action: 'TICK' },
+})
+```
+
+## Setup
+
+Timers are run by `makeTimerDriver()`, which you register when you start the app:
+
+```jsx
+import { run, makeTimerDriver } from 'sygnal'
+import App from './App.jsx'
+
+run(App, { TIMER: makeTimerDriver() })
+```
+
+The key is yours to choose (`TIMER` by convention): Sygnal finds the driver by the `timers` static it takes, not by its name. One driver serves every component of the app. A component that declares `timers` in an app without the driver gets [SYG643](https://sygnal.js.org/reference/errors/#syg643) in development, since nothing would ever fire.
+
+## The timers static
+
+`timers` takes the state (with its calculated fields) and returns an object of named timers. Each value is a timer spec, or a falsy value for "not now":
+
+```jsx
+Game.timers = (state) => ({
+  tick: state.running && { every: 100, action: 'TICK' },
+  done: state.armed && { after: 5000, action: 'EXPIRE' },
+  frame: state.animating && { frame: 'FRAME' },
+})
+```
+
+| Spec | Runs | Action data |
+|---|---|---|
+| `{ every: ms, action }` | Every `ms` milliseconds (a positive number) | `{ n, t }`: the tick number from 1, and `Date.now()` |
+| `{ after: ms, action }` | Once, `ms` milliseconds (0 or more) after it is declared | `{ t }`: `Date.now()` |
+| `{ frame: 'ACTION' }` | Every animation frame (`requestAnimationFrame`; every 16 ms where there is none) | `{ t, dt }`: `Date.now()`, and the milliseconds since the previous frame (0 on the first) |
+
+Any spec can add `background: true` (see [hidden pages](#hidden-pages)). The action is one of the component's own actions: it goes to the instance that declared the timer, and every sink of its model entry runs, as for an intent action.
+
+Sygnal compares the result with the previous one, name by name, whenever the state changes:
+
+- a new name starts its timer;
+- a name that is gone, or now falsy, stops its timer;
+- a spec that changed (another interval, another action) restarts its timer;
+- a spec that is the same as before keeps running, even though the function returned a new object.
+
+So `timers` is a description, not a command: return what should be running now. An `after` timer fires once; it doesn't fire again while the same spec stays declared. Make it falsy (and then declared again) to arm it once more.
+
+### Ticks don't drift
+
+An `every` timer schedules each tick from the moment it started, not from the previous tick: tick `n` is due at start + n × `every`. A late tick doesn't push the later ones back, so 1,000 ticks of 100 ms end 100 s after the start. Use the `t` in the data (or `Date.now()` in the intent) for elapsed time rather than counting ticks.
+
+When a tick comes very late (a browser throttles timers in a background tab), the missed ticks are not delivered one by one: they are coalesced into the next one, and `n` jumps over them.
+
+## A stopwatch
+
+The stopwatch keeps the clock time it started at and adds up the finished runs, so it is exact however late a tick comes. The tick only moves `now`, which the view reads. It stops when the stopwatch pauses, resets or is removed:
+
+```jsx live
+const pad = (n) => String(n).padStart(2, '0')
+const format = (ms) => {
+  const tenths = Math.floor(ms / 100)
+  return `${pad(Math.floor(tenths / 600))}:${pad(Math.floor(tenths / 10) % 60)}.${tenths % 10}`
+}
+
+// the running time at clock time `at`: the finished runs plus the current one
+const elapsed = (state, at) => state.done + (state.status === 'running' ? at - state.since : 0)
+
+export function Stopwatch({ state }) {
+  const label = { idle: 'Start', running: 'Pause', paused: 'Resume' }[state.status]
+  return (
+    <section className="stopwatch">
+      <p className="time">{format(elapsed(state, state.now))}</p>
+      <button className="toggle">{label}</button>
+      <button className="lap" disabled={state.status !== 'running'}>Lap</button>
+      <button className="reset" disabled={state.status !== 'paused'}>Reset</button>
+      <ol className="laps">
+        {state.laps.map((lap, i) => <li>{`Lap ${i + 1}: ${format(lap)}`}</li>)}
+      </ol>
+    </section>
+  )
+}
+
+const INITIAL = { status: 'idle', done: 0, since: 0, now: 0, lapStart: 0, laps: [] }
+
+Stopwatch.initialState = INITIAL
+// a tick every 100 ms while running; stopped when it pauses, resets or unmounts
+Stopwatch.timers = (state) => ({ tick: state.status === 'running' && { every: 100, action: 'TICK' } })
+Stopwatch.intent = ({ DOM }) => ({
+  TOGGLE: DOM.click('.toggle').map(() => Date.now()),
+  LAP: DOM.click('.lap').map(() => Date.now()),
+  RESET: DOM.click('.reset'),
+})
+Stopwatch.model = {
+  TOGGLE: (state, at) => state.status === 'running'
+    ? { ...state, status: 'paused', done: elapsed(state, at), now: at }
+    : { ...state, status: 'running', since: at, now: at },
+  TICK: (state, { t }) => ({ ...state, now: t }),
+  LAP: (state, at) => {
+    const total = elapsed(state, at)
+    return { ...state, now: at, laps: [...state.laps, total - state.lapStart], lapStart: total }
+  },
+  RESET: () => INITIAL,
+}
+```
+
+## Hidden pages
+
+A component on a hidden [Switchable](https://sygnal.js.org/guide/switchable/) page keeps its state, but its timers stop while the page is hidden. When the page is shown again they start from scratch: an `every` timer counts from 1 again, and an `after` timer waits its whole delay. A timer that should go on in the background says so:
+
+```jsx
+Inbox.timers = () => ({
+  // keeps checking for new mail while another page is shown
+  poll: { every: 30000, action: 'CHECK_MAIL', background: true },
+})
+```
+
+When a component is removed, its timers stop; when the app is disposed, all of them do.
+
+## Server rendering
+
+Drivers don't run during `renderToString`, so no timer starts on the server. The view renders the initial state, and the timers start in the browser after hydration.
+
+## Testing
+
+`renderComponent` runs the real timer driver for you (no `drivers` option needed), on whatever clock the test uses. With Vitest's fake timers, `vi.advanceTimersByTimeAsync(ms)` moves time forward and the timers fire as they would. `t.timers()` lists the timers running now, each as its spec plus `name`, `action` and `component`:
+
+```jsx
+// @vitest-environment jsdom
+import { it, expect, afterEach, vi } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { Stopwatch } from './Stopwatch.jsx'
+
+let t
+afterEach(() => {
+  t?.dispose()
+  vi.useRealTimers()
+})
+
+it('ticks while running and stops when paused', async () => {
+  vi.useFakeTimers()
+  t = renderComponent(Stopwatch)
+  await t.ready()
+  expect(t.timers()).toEqual([])
+
+  t.simulateEvent('.toggle', 'click')
+  await t.next(s => s.status === 'running')
+  expect(t.timers()).toEqual([{ name: 'tick', every: 100, action: 'TICK', component: 'Stopwatch' }])
+
+  await vi.advanceTimersByTimeAsync(1000)
+  expect(t.state.now - t.state.since).toBe(1000)
+
+  t.simulateEvent('.toggle', 'click')
+  await t.next(s => s.status === 'paused')
+  expect(t.timers()).toEqual([])
+})
+```
+
+- The fake is registered as the `TIMER` sink (`timerSink: 'CLOCK'` gives it another name, when a test needs `TIMER` for something else). If the test passes its own `makeTimerDriver()` in `drivers`, the fake stands down, so no timer runs twice; `t.timers()` then lists nothing, and throws when that driver is under the fake's name.
+- `t.actions` lists each tick with its data (`t.actions.filter(a => a.type === 'TICK')`), so a test can check the `{ n, t }` values.
+- `vi.getTimerCount()` is 0 after `t.dispose()`: removing a component stops its timers.
+- A `frame` timer uses `requestAnimationFrame` when the environment has one, and a 16 ms timeout otherwise (as in jsdom), so fake timers drive it too.
+
+See [Fake timers](https://sygnal.js.org/integration/testing/#fake-timers) for how the waits (`next()`, `settle()`) behave on a fake clock.
+
+## Diagnostics
+
+| Code | When |
+|---|---|
+| [SYG422](https://sygnal.js.org/reference/errors/#syg422) (error) | A spec the driver can't run: a zero or negative `every`, a negative `after`, no `action`, a `frame` that isn't an action name. That timer is not started; the others are |
+| [SYG643](https://sygnal.js.org/reference/errors/#syg643) (warning) | The component declares `timers`, but no `makeTimerDriver()` is registered. `sygnal-check` reports it too when it can read the app's `run()` call |
+
+To stop a timer, return a falsy value for it, not an invalid spec.

package/dist/guide/ui/accordion.md

@@ -0,0 +1,93 @@
+<!-- Generated from docs/src/content/docs/ui by scripts/copy-guides.mjs; online: https://sygnal.js.org/ui/ -->
+# Accordion
+
+`accordion()` is a [behavior](../behaviors.md) for a list of headers that each show and hide a panel, following the [WAI-ARIA accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/). You render the header buttons and the panels; `accordionAttrs()` gives them `aria-expanded`, the ids that link each button to its panel, and `hidden` on the closed panels.
+
+```jsx live
+import { accordion, accordionAttrs } from 'sygnal/ui'
+
+const FAQ = [
+  { id: 'shipping', question: 'How long does shipping take?', answer: 'Two to four working days.' },
+  { id: 'returns', question: 'Can I return an item?', answer: 'Within 30 days, unused.' },
+]
+
+function Faq({ state, uid }) {
+  const a = accordionAttrs(state.faq, uid)
+  return (
+    <div className="faq">
+      {FAQ.map((item) => (
+        <div className="faq-item">
+          <h3><button className="faq-question" {...a.trigger(item.id)}>{item.question}</button></h3>
+          <div className="faq-answer" {...a.panel(item.id)}><p>{item.answer}</p></div>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+Faq.uses = { faq: accordion({ trigger: '.faq-question' }) }
+```
+
+Wrap each button in a heading of the level that fits the page, so the headers are in the page outline.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `trigger` | (required) | The header buttons: a selector or a [control](https://sygnal.js.org/guide/controls/) |
+| `multiple` | `false` | Several panels open at once; without it, opening one closes the others |
+| `collapsible` | `true` | `false`: the last open panel can't be closed (its button gets `aria-disabled`) |
+| `expanded` | `[]` | The panels open at the start: a value or an array |
+| `loop` | `true` | Down on the last header goes to the first |
+| `id` | the key in `uses` | The prefix of the ids |
+
+## Keyboard
+
+| Key | |
+|---|---|
+| Enter / Space | Opens or closes the focused header's panel |
+| Down / Up | The next or previous header |
+| Home / End | The first or last header |
+| Tab | The next focusable element, through the open panels |
+
+## State, actions and attributes
+
+`state.faq` is `{ id, expanded, collapsible }`: `expanded` lists the open panels' values. Actions: `faq.TOGGLE`, `faq.EXPAND` and `faq.COLLAPSE` take a value (a click on a header toggles its own), `faq.MOVE` focuses a header. Open a panel from your model with `next('faq.EXPAND', 'returns')`.
+
+`accordionAttrs(state.faq, uid)` returns:
+
+| | Attributes |
+|---|---|
+| `trigger(value)` | `id`, `aria-expanded`, `aria-controls`, `aria-disabled` (only on the open panel that can't close), `type="button"`, `data-value`, `data-state` (`open` / `closed`) |
+| `panel(value)` | `id`, `role="region"`, `aria-labelledby`, `hidden` unless open, `data-state` |
+
+## Styling
+
+```css live
+.faq-question { width: 100%; text-align: start; }
+.faq-question[data-state='open']::after { content: '−'; }
+.faq-question[data-state='closed']::after { content: '+'; }
+```
+
+## Testing
+
+```jsx
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import Faq from './Faq.jsx'
+
+it('opens one answer at a time', async () => {
+  const t = renderComponent(Faq)
+  await t.ready()
+  t.simulateEvent('.faq-question', 'click', { data: { value: 'shipping' } })
+  await t.next((s) => s.faq.expanded.includes('shipping'))
+  t.simulateAction('faq.TOGGLE', 'returns')
+  await t.next((s) => s.faq.expanded.includes('returns'))
+  expect(t.state.faq.expanded).toEqual(['returns'])
+  expect(t.query('.faq-question[data-value="returns"]').getAttribute('aria-expanded')).toBe('true')
+  expect(t.actions.map((a) => a.type)).toEqual(['INITIALIZE', 'faq.TOGGLE', 'faq.TOGGLE'])
+  t.dispose()
+})
+```
+
+The arrow keys read the order of the headers on the page: test them with `dom: 'real'`.

package/dist/guide/ui/combobox.md

@@ -0,0 +1,144 @@
+<!-- Generated from docs/src/content/docs/ui by scripts/copy-guides.mjs; online: https://sygnal.js.org/ui/ -->
+# Combobox
+
+`Combobox` is a text input with a list of suggestions that narrows as the user types, following the [WAI-ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). Keyboard handling and the active option come from [Zag.js](https://zagjs.com)'s combobox machine, rendered with [`fromZag`](../adapters.md#zag-machines-fromzag). It is a [widget](../widgets.md) tag.
+
+```jsx live
+import { Combobox } from 'sygnal/ui/combobox'
+
+const CITIES = ['Amsterdam', 'Berlin', 'Lisbon', 'London', 'Paris', 'Prague']
+
+function Trip({ state }) {
+  return (
+    <div className="trip">
+      <Combobox className="city" label="City" items={CITIES} value={state.city} placeholder="Type a city" />
+      <p>{state.city ? `Going to ${state.city}` : ''}</p>
+    </div>
+  )
+}
+
+Trip.initialState = { city: null }
+Trip.intent = ({ DOM }) => ({
+  CITY: DOM.select('.city').events('value-change').detail(),
+})
+Trip.model = {
+  CITY: (state, city) => ({ ...state, city }),
+}
+```
+
+Typing `lo` leaves London in the list; Down and Enter pick it, the input shows "London", and `value-change` sends `'London'`.
+
+Install Zag's packages first: `npm install @zag-js/vanilla@~1.45.0 @zag-js/combobox@~1.45.0` (see [Menu](./menu.md#install)).
+
+## Filtering
+
+By default the list shows the items whose label contains the text, ignoring case. The filter text resets when the list closes, so the next open shows every item.
+
+- `filter={(item, text) => item.label.toLowerCase().startsWith(text.toLowerCase())}` replaces the test.
+- `filter={false}` turns it off: the app passes the items to show, from the `input-change` event. Use it for server-side search (with [`makeFetchDriver`](../http.md)). In this demo, a stand-in server searches a few names:
+
+```js live-server
+const names = ['Ada Lovelace', 'Alan Turing', 'Grace Hopper', 'Barbara Liskov', 'Donald Knuth']
+const users = names.map((name, i) => ({ id: String(i + 1), name }))
+
+export default {
+  'GET /api/users': ({ query }) => {
+    const q = (query.q ?? '').toLowerCase()
+    return { json: users.filter((u) => u.name.toLowerCase().includes(q)), delayMs: 400 }
+  },
+}
+```
+
+```jsx live live-height=240
+import { Combobox } from 'sygnal/ui/combobox'
+
+function Search({ state }) {
+  return <Combobox className="user" label="User" items={state.matches} filter={false} placeholder="Search users" />
+}
+
+Search.initialState = { matches: [] }
+Search.intent = ({ DOM }) => ({
+  QUERY: DOM.select('.user').events('input-change').detail(),
+})
+Search.model = {
+  QUERY: { HTTP: (state, q) => ({ url: '/api/users', query: { q }, ok: 'MATCHES', error: 'FAILED', latest: true }) },
+  MATCHES: (state, users) => ({ ...state, matches: users.map((u) => ({ value: u.id, label: u.name })) }),
+  FAILED: (state) => ({ ...state, matches: [] }),
+}
+```
+
+## Props
+
+| Prop | | |
+|---|---|---|
+| `label` | | The visible label, linked to the input (its accessible name). Give every combobox one |
+| `aria-label`, `aria-labelledby`, `aria-describedby` | | Name or describe the input when there is no visible `label` (or in addition to it); they go on the input, not the host |
+| `items` | (required) | Strings, or `{ value, label, disabled }` objects |
+| `value` | | Controlled: the value (an array with `multiple`); `null` for none |
+| `defaultValue` | | The start value when `value` is left out |
+| `placeholder` | | The input's placeholder |
+| `filter` | contains | A function `(item, text) => boolean`, or `false` |
+| `allowCustomValue` | `false` | Keep text that matches no item when the input loses focus. With `name` (single), the form submits the selected item's value, or, when the user typed since the last selection, the typed text (text equal to an item's label submits the item's value). A new controlled `value` ends the typing, except an empty one (an app that clears its value on `input-change`) |
+| `openOnClick` | `false` | Open the list when the input is clicked |
+| `inputBehavior` | `'none'` | `'autohighlight'` highlights the first match; `'autocomplete'` also completes the text |
+| `selectionBehavior` | `'replace'` | What the input shows after a pick: `'replace'` (the label), `'clear'`, or `'preserve'` (the typed text). With `multiple`: `'clear'` |
+| `closeOnSelect` | `true` | With `multiple`: `false` |
+| `loopFocus` | `true` | The arrow keys wrap |
+| `name` | | The form field: hidden inputs submit the value (one per value with `multiple`), not the label the input shows. `form` (a form's id) goes on those hidden inputs |
+| `multiple`, `form`, `disabled`, `readOnly`, `required`, `invalid`, `positioning`, `open` | | As in Zag's combobox |
+
+## Events and commands
+
+| Event | Detail |
+|---|---|
+| `value-change` | The value (with `multiple`: the array); `null` when cleared |
+| `input-change` | The text the user typed (not the label a pick writes) |
+| `open-change` | `true` / `false` |
+
+Commands for `ELEMENT`: `open`, `close`, `clear`, and `focus` (the input).
+
+## Keyboard
+
+| Key | |
+|---|---|
+| Typing | Filters the list and opens it |
+| Down / Up | Open the list; move the active option (`aria-activedescendant`, the focus stays in the input) |
+| Enter | Pick the active option |
+| Escape | Close the list |
+| Home / End | Move the caret in the input |
+
+## Styling
+
+Zag's data attributes: `[data-scope="combobox"]` with `[data-part="root"]`, `"label"`, `"control"`, `"input"`, `"trigger"`, `"positioner"`, `"content"`, `"item"`, `"item-text"` and `"item-indicator"`; `data-state`, `data-highlighted` and `data-disabled` as for [Select](./select.md#styling).
+
+```css live
+.city { max-width: 16rem; }
+.city [data-part='content'] { background: Canvas; border: 1px solid #ddd; }
+.city [data-part='item'][data-highlighted] { background: rgb(99 102 241 / 0.25); }
+```
+
+## Positioning
+
+The listbox renders inside the widget's host, next to the input, and Zag positions it with `position: absolute` (the `--x` / `--y` variables on the positioner). Inside a container that clips its content (`overflow: hidden` or `auto`: a card, a scrolling panel, a table cell), the open listbox is cut off at the container's edge. Pass `positioning={{ strategy: 'fixed' }}` there: the positioner is then placed relative to the viewport and escapes the clipping (it still follows the input when the page scrolls; an ancestor with a `transform`, `filter` or `contain` still clips it). Other options go in the same object: `positioning={{ placement: 'bottom-end', gutter: 4, strategy: 'fixed' }}`.
+
+## Testing
+
+```jsx
+import { it } from 'vitest'
+import { renderComponent } from 'sygnal'
+import Trip from './Trip.jsx'
+
+it('keeps the picked city', async () => {
+  const t = renderComponent(Trip)
+  await t.ready()
+  t.widget('.city').dispatch('value-change', 'Paris')
+  await t.next((state) => state.city === 'Paris')
+  t.dispose()
+})
+```
+
+Typing and filtering need a DOM: see [Menu](./menu.md#testing).
+
+## Size
+
+Gzipped, in a small app: Combobox adds **34 KB** (mostly Zag's combobox machine, its positioning and `@zag-js/vanilla`). With Menu and Select, the three add 47 KB together.