sygnal 5.3.7 → 6.0.0

package/dist/guide/ui/dialog.md

@@ -0,0 +1,124 @@
+<!-- Generated from docs/src/content/docs/ui by scripts/copy-guides.mjs; online: https://sygnal.js.org/ui/ -->
+# Dialog
+
+`dialog()` is a [behavior](../behaviors.md) for a native `<dialog>`. It opens the dialog with `showModal()`, so the browser does the hard parts: it traps the focus inside the dialog, makes the rest of the page inert, closes it on Escape and returns the focus when it closes. The behavior keeps `open` and `returnValue` in state, whichever way the dialog closed.
+
+```jsx live
+import { dialog } from 'sygnal/ui'
+
+function Profile({ state, uid }) {
+  return (
+    <div>
+      <button className="edit-profile">Edit profile</button>
+      <dialog className="profile" aria-labelledby={uid('title')}>
+        <h2 id={uid('title')}>Edit profile</h2>
+        <label>Name <input className="name" value={state.name} /></label>
+        <button className="save">Save</button>
+        <button className="cancel">Cancel</button>
+      </dialog>
+      <p>{state.profile.returnValue === 'saved' ? 'Profile saved' : ''}</p>
+    </div>
+  )
+}
+
+Profile.initialState = { name: '' }
+Profile.uses = { profile: dialog({ dialog: '.profile', trigger: '.edit-profile', close: '.cancel' }) }
+Profile.intent = ({ DOM }) => ({
+  NAME: DOM.input('.name').value(),
+  SAVE: DOM.click('.save'),
+})
+Profile.model = {
+  NAME: (state, name) => ({ ...state, name }),
+  SAVE: { ELEMENT: { close: '.profile', returnValue: 'saved' } },
+}
+```
+
+A click on `.edit-profile` opens the dialog and a click on `.cancel` closes it. Save closes it from the model with a return value, through the built-in [`ELEMENT` sink](../element-commands.md).
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `dialog` | (required) | The `<dialog>` element: a selector or a [control](https://sygnal.js.org/guide/controls/). It must match only this behavior's dialog: a selector that also matches a dialog nested in it (`dialog`, a shared class) gets that dialog's events too |
+| `trigger` | | Its clicks open the dialog |
+| `close` | | Its clicks close the dialog, with the return value `''` |
+| `modal` | `true` | `false` opens it with `show()`: not modal, the page stays usable |
+| `cancelable` | `true` | `false` keeps Escape from closing it: the `cancel` event is prevented, and opening it sets `closedby="none"` (Chromium closes a dialog on a second Escape otherwise; the attribute goes again when it closes). `CANCEL` still runs on each Escape. In a browser without `closedby`, a second Escape can still close it; the `CLOSED` action tells you |
+| `returnFocus` | `true` | When the dialog closes and the focus was lost, focus the element that opened it (the clicked trigger, when several match `trigger`), else the trigger. A selector names another element; `false` leaves the focus to the browser |
+
+The browser returns the focus to the element that had it before the dialog opened. Safari doesn't focus a button when it is clicked, so after a mouse click the focus would go back to the page itself; `returnFocus` focuses the trigger instead. It does nothing when the browser already moved the focus somewhere. It works for a dialog the host renders only while it is open, too.
+
+## State and actions
+
+`state.profile` is `{ open, returnValue }`.
+
+| Action | Data | |
+|---|---|---|
+| `profile.OPEN` | | Opens the dialog (no change when it is open) |
+| `profile.CLOSE` | the return value | Closes it with that return value |
+| `profile.CLOSED` | the return value | The dialog closed, whichever way: sets `open: false` and `returnValue` |
+| `profile.TOGGLED` | `true` / `false` | The dialog's `toggle` event: a dialog opened without the model (for example with `commandfor`) sets `open: true` |
+| `profile.CANCEL` | the event | Escape was pressed (the dialog closes next, unless `cancelable: false`). The `cancel` event; with `cancelable: false`, the Escape `keydown` in the dialog (`closedby="none"` stops the `cancel` event) |
+| `profile.SYNC` | `false` | The dialog left the page while open (a page change, a conditional render), or OPEN's `showModal()` threw (a disconnected dialog, a popover open on it): sets `open: false`, as no close event comes (your `close` listeners don't run for a dialog that never opened) |
+
+`OPEN` and `CLOSE` check the dialog itself before they act: `showModal()` only on a closed dialog, `close()` only on an open one. A dialog removed while open opens again when it is back.
+
+React to a close in your own model with an entry for the namespaced action. It runs after the behavior's, on the full state:
+
+```jsx
+Profile.model = {
+  'profile.CLOSED': (state, returnValue) => (returnValue === 'saved' ? { ...state, savedName: state.name } : state),
+}
+```
+
+Open the dialog from another place with an intent action of the same name, `'profile.OPEN': DOM.click('.avatar')`, or from a model entry that sends `{ showModal: '.profile' }` to `ELEMENT`.
+
+## Accessibility
+
+- Name the dialog: `aria-labelledby` pointing at its heading, as above, or `aria-label`.
+- Put a close button inside. Escape closes a modal dialog, but not everyone has a keyboard.
+- The dialog element has `role="dialog"`; a modal one is also `aria-modal` to assistive technology.
+- A form inside the dialog with `method="dialog"` closes it on submit, with the submit button's `value` as the return value; `CLOSED` sees it.
+
+## Styling
+
+```css
+.profile { border: none; border-radius: 8px; padding: 1.5rem; }
+.profile::backdrop { background: rgb(0 0 0 / 0.4); }
+.profile[open] { animation: fade-in 150ms ease-out; }
+```
+
+## Testing
+
+The mock DOM records the `showModal` and `close` commands without running them, so simulate the dialog's `close` event as the browser sends it:
+
+```jsx
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import Profile from './Profile.jsx'
+
+it('opens the dialog and keeps the return value', async () => {
+  const t = renderComponent(Profile)
+  await t.ready()
+  t.simulateEvent('.edit-profile', 'click')
+  await t.next((s) => s.profile.open)
+  expect(t.commands('ELEMENT')).toEqual([{ showModal: '.profile' }])
+
+  t.simulateEvent('.save', 'click')
+  await t.settle()
+  expect(t.commands('ELEMENT').at(-1)).toEqual({ close: '.profile', returnValue: 'saved' })
+
+  t.simulateEvent('.profile', 'close', { target: { returnValue: 'saved' } })
+  await t.next((s) => !s.profile.open)
+  expect(t.state.profile.returnValue).toBe('saved')
+  expect(t.actions.map((a) => [a.type, a.cause])).toEqual([
+    ['INITIALIZE', 'built-in'],
+    ['profile.OPEN', 'behavior'],
+    ['SAVE', 'intent'],
+    ['profile.CLOSED', 'behavior'],
+  ])
+  t.dispose()
+})
+```
+
+With `dom: 'real'`, the commands run on the jsdom elements; focus trapping and the backdrop need a real browser.

package/dist/guide/ui/disclosure.md

@@ -0,0 +1,60 @@
+<!-- Generated from docs/src/content/docs/ui by scripts/copy-guides.mjs; online: https://sygnal.js.org/ui/ -->
+# Disclosure
+
+`disclosure()` is a [behavior](../behaviors.md) for a button that shows and hides one section of content, following the [WAI-ARIA disclosure pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/). `disclosureAttrs()` gives the button `aria-expanded` and `aria-controls`, and the section its `id` and `hidden`.
+
+```jsx live
+import { disclosure, disclosureAttrs } from 'sygnal/ui'
+
+function Order({ state, uid }) {
+  const a = disclosureAttrs(state.details, uid)
+  return (
+    <article className="order">
+      <h2>Order {state.number}</h2>
+      <button className="details-toggle" {...a.trigger}>{state.details.open ? 'Hide details' : 'Show details'}</button>
+      <div className="details" {...a.panel}>
+        <p>Shipped to {state.address}</p>
+      </div>
+    </article>
+  )
+}
+
+Order.initialState = { number: 1042, address: '1 Main St' }
+Order.uses = { details: disclosure({ trigger: '.details-toggle' }) }
+```
+
+For a plain show-and-hide section with no state in the model, the native `<details>` and `<summary>` elements need no code at all. Use the behavior when the model needs to know or set whether the section is open.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `trigger` | (required) | The button: a selector or a [control](https://sygnal.js.org/guide/controls/) |
+| `open` | `false` | Open at the start |
+| `id` | the key in `uses` | The prefix of the ids |
+
+## State, actions and attributes
+
+`state.details` is `{ id, open }`. Actions: `details.TOGGLE` (a click on the button), `details.OPEN` and `details.CLOSE` (no change when it already is).
+
+`disclosureAttrs(state.details, uid)` returns `trigger` (`aria-expanded`, `aria-controls`, `type="button"`, `data-state`) and `panel` (`id`, `hidden` unless open, `data-state`: `open` / `closed`).
+
+## Testing
+
+```jsx
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import Order from './Order.jsx'
+
+it('shows and hides the details', async () => {
+  const t = renderComponent(Order)
+  await t.ready()
+  expect(t.query('.details').hidden).toBe(true)
+  t.simulateEvent('.details-toggle', 'click')
+  await t.next((s) => s.details.open)
+  expect(t.query('.details-toggle').getAttribute('aria-expanded')).toBe('true')
+  expect(t.query('.details').hidden).toBe(false)
+  expect(t.actions.map((a) => a.type)).toEqual(['INITIALIZE', 'details.TOGGLE'])
+  t.dispose()
+})
+```

package/dist/guide/ui/menu.md

@@ -0,0 +1,125 @@
+<!-- Generated from docs/src/content/docs/ui by scripts/copy-guides.mjs; online: https://sygnal.js.org/ui/ -->
+# Menu
+
+`Menu` is a menu button: a trigger that opens a list of actions, following the [WAI-ARIA menu button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/). The keyboard handling, focus management and typeahead come from [Zag.js](https://zagjs.com)'s menu machine; Sygnal renders it with [`fromZag`](../adapters.md#zag-machines-fromzag). It is a [widget](../widgets.md) tag: render it with a class, and read its events in the intent like any element's.
+
+```jsx live
+import { Menu } from 'sygnal/ui/menu'
+
+const ACTIONS = [
+  { value: 'rename', label: 'Rename' },
+  { value: 'duplicate', label: 'Duplicate' },
+  { separator: true },
+  { value: 'delete', label: 'Delete' },
+]
+
+function Card({ state }) {
+  return (
+    <div className="card">
+      <h3>{state.title}</h3>
+      <Menu className="card-actions" label="Actions" items={ACTIONS} />
+      <p>{state.last ? `Last action: ${state.last}` : ''}</p>
+    </div>
+  )
+}
+
+Card.initialState = { title: 'Groceries', last: '' }
+Card.intent = ({ DOM }) => ({
+  ACTION: DOM.select('.card-actions').events('select').detail(),
+})
+Card.model = {
+  ACTION: (state, last) => ({ ...state, last }),
+}
+```
+
+`DOM.select('.card-actions').events('select').detail()` gives the value of the item the user picked (`'rename'`). The menu closes and the focus goes back to the trigger.
+
+## Install
+
+Each Zag-based part has a subpath of its own (`sygnal/ui/menu`, `sygnal/ui/select`, `sygnal/ui/combobox`), so `sygnal/ui` (Dialog, Popover, Tabs…) never needs Zag, and a part needs only Zag's runtime and its own machine. They are optional peer dependencies of `sygnal`; install them in one version:
+
+```bash
+npm install @zag-js/vanilla@~1.45.0 @zag-js/menu@~1.45.0       # Menu (sygnal/ui/menu)
+npm install @zag-js/vanilla@~1.45.0 @zag-js/select@~1.45.0     # Select (sygnal/ui/select)
+npm install @zag-js/vanilla@~1.45.0 @zag-js/combobox@~1.45.0   # Combobox (sygnal/ui/combobox)
+```
+
+Without them, `sygnal/vite` stops with [SYG666](https://sygnal.js.org/reference/errors/#syg666), which names the missing packages.
+
+## Props
+
+| Prop | | |
+|---|---|---|
+| `label` | (required) | The trigger's text: its accessible name |
+| `aria-label`, `aria-labelledby`, `aria-describedby` | | Name or describe the trigger when there is no visible `label` (or in addition to it); they go on the trigger, not the host |
+| `items` | (required) | Strings, or `{ value, label, disabled }` objects; `{ separator: true }` draws a separator |
+| `open` | | Controlled open state; follow the `open-change` event |
+| `defaultOpen` | `false` | |
+| `closeOnSelect` | `true` | `false` keeps the menu open after a pick |
+| `loopFocus` | `false` | The arrow keys wrap from the last item to the first |
+| `typeahead` | `true` | Typing a letter moves to the next item starting with it |
+| `positioning` | | Zag's positioning options: `{ placement: 'bottom-end', gutter: 4 }` |
+| `dir` | `'ltr'` | |
+
+`className`, `id`, `style` and `aria-*` / `data-*` props go on the host `<div>`.
+
+## Events and commands
+
+| Event | Detail |
+|---|---|
+| `select` | The value of the item picked |
+| `open-change` | `true` when it opens, `false` when it closes |
+
+Open or close it from the model with an [element command](../element-commands.md) on its class: `OPEN_ACTIONS: { ELEMENT: { open: '.card-actions' } }`, or `{ close: '.card-actions' }`.
+
+## Keyboard
+
+| Key | |
+|---|---|
+| Enter, Space, Down | On the trigger: open the menu on the first item (Up: on the last) |
+| Down / Up | The next / previous item; disabled items are skipped |
+| Home / End | The first / last item |
+| A letter | The next item that starts with it |
+| Enter, Space | Pick the highlighted item and close |
+| Escape, Tab | Close; Escape returns the focus to the trigger |
+
+A click outside closes it too.
+
+## Styling
+
+The parts carry Zag's data attributes: `[data-scope="menu"]` with `[data-part="trigger"]`, `"positioner"`, `"content"`, `"item"` and `"separator"`; the content and trigger have `data-state="open" | "closed"`, an item `data-highlighted` and `data-disabled`. The content is `hidden` while closed, and the positioner places it with `position` and CSS variables (`--x`, `--y`).
+
+```css live
+.card-actions [data-part='content'] { background: Canvas; border: 1px solid #ddd; border-radius: 6px; padding: 4px; }
+.card-actions [data-part='item'] { padding: 4px 8px; border-radius: 4px; cursor: default; }
+.card-actions [data-part='item'][data-highlighted] { background: rgb(99 102 241 / 0.25); }
+.card-actions [data-part='item'][data-disabled] { opacity: 0.5; }
+```
+
+## Positioning
+
+The menu renders inside the widget's host, next to the trigger, 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 menu 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 trigger 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
+
+In the default mock DOM the menu renders its host only; `t.widget('.card-actions')` gives its props and dispatches its events:
+
+```jsx
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import Card from './Card.jsx'
+
+it('records the picked action', async () => {
+  const t = renderComponent(Card)
+  await t.ready()
+  t.widget('.card-actions').dispatch('select', 'rename')
+  await t.next((state) => state.last === 'rename')
+  t.dispose()
+})
+```
+
+To test the keyboard and focus, render it with `dom: 'real'` in jsdom (`renderComponent` adds the `ResizeObserver`, `CSS.escape` and `Element.prototype.scrollTo` that Zag needs and jsdom lacks, for the test's lifetime) or in a real browser. Sygnal's browser suite runs all three Zag parts in Chromium, Firefox and WebKit.
+
+## Size
+
+Gzipped, in a small app: Menu adds **33 KB** (Zag's menu machine, its positioning and `@zag-js/vanilla` make up almost all of it; `fromZag` is about 2 KB). Menu, Select and Combobox together add 47 KB, because they share most of Zag. For a simple list of links or buttons, a [Popover](./popover.md) costs a fraction of that.

package/dist/guide/ui/overview.md

@@ -0,0 +1,166 @@
+<!-- Generated from docs/src/content/docs/ui by scripts/copy-guides.mjs; online: https://sygnal.js.org/ui/ -->
+# UI Parts
+
+`sygnal/ui` is a set of headless UI parts. Each part wires up what the browser already does well (`<dialog>`, the Popover API, CSS anchor positioning) and adds the state, keyboard handling and ARIA attributes it leaves out. The parts are unstyled: you write the markup and the CSS, and they give you class hooks and data attributes to style.
+
+```jsx
+import { dialog, tabs, tabsAttrs, Toaster } from 'sygnal/ui'
+```
+
+| Part | What it is | Built on |
+|---|---|---|
+| [Dialog](./dialog.md) | A behavior for `uses` | `<dialog>`, `showModal()` |
+| [Popover](./popover.md) | A behavior for `uses` | The Popover API (`popover`, `popovertarget`) |
+| [Tooltip](./tooltip.md) | A behavior for `uses` | A manual popover placed by CSS anchor positioning, with show and hide delays |
+| [Tabs](./tabs.md) | A behavior + `tabsAttrs` | Your buttons and panels; roving focus |
+| [Accordion](./accordion.md) | A behavior + `accordionAttrs` | Your buttons and panels |
+| [Disclosure](./disclosure.md) | A behavior + `disclosureAttrs` | Your button and panel |
+| [Toaster](./toaster.md) | A component | `popover="manual"`, Collection, Transition, timers |
+| [Menu](./menu.md) | A widget tag, from `sygnal/ui/menu` | Zag.js's menu machine ([`fromZag`](../adapters.md#zag-machines-fromzag)) |
+| [Select](./select.md) | A widget tag, from `sygnal/ui/select` | Zag.js's select machine |
+| [Combobox](./combobox.md) | A widget tag, from `sygnal/ui/combobox` | Zag.js's combobox machine |
+
+Menu, Select and Combobox need keyboard and focus handling that the browser doesn't give: they run [Zag.js](https://zagjs.com) state machines, each in a subpath of its own (`sygnal/ui/menu`, `sygnal/ui/select`, `sygnal/ui/combobox`). Zag is an optional peer dependency: a part needs `@zag-js/vanilla` and its own machine (`npm install @zag-js/vanilla@~1.45.0 @zag-js/menu@~1.45.0` for Menu), and `sygnal/ui` never needs it. They are [widget](../widgets.md) tags: `<Menu className="actions" label="Actions" items={ITEMS} />`, read with `DOM.select('.actions').events('select').detail()`.
+
+## How the parts work
+
+Six parts are [behaviors](../behaviors.md): you list them in a component's `uses` under a state key, and they add a slice of state and namespaced actions to it. The component renders its own markup with the classes the behavior's options name:
+
+```jsx
+import { dialog } from 'sygnal/ui'
+
+function Settings({ state, uid }) {
+  return (
+    <div>
+      <button className="open-settings">Settings</button>
+      <dialog className="settings" aria-labelledby={uid('title')}>
+        <h2 id={uid('title')}>Settings</h2>
+        <button className="close-settings">Close</button>
+      </dialog>
+      <p>{state.settings.open ? 'Editing settings' : ''}</p>
+    </div>
+  )
+}
+
+Settings.uses = { settings: dialog({ dialog: '.settings', trigger: '.open-settings', close: '.close-settings' }) }
+```
+
+`state.settings` is `{ open, returnValue }`, and the actions are `settings.OPEN`, `settings.CLOSE` and so on. Your own intent and model can trigger them and react to them, as with any behavior: an intent action `'settings.OPEN': DOM.click('.edit')` adds a trigger, and a model entry `'settings.CLOSED': (state) => …` runs after the behavior's.
+
+Tabs, Accordion and Disclosure have no markup of their own either. A helper gives you the attributes to spread on your elements, computed from the slice: roles, ARIA states, ids that link the buttons and panels, and the roving `tabindex`. It takes the view's `uid`, so each instance of the component gets its own ids:
+
+```jsx
+const a = tabsAttrs(state.tabs, uid)
+// <div {...a.list} aria-label="Settings"> <button className="tab" {...a.tab('general')}>General</button> …
+```
+
+The Toaster renders its own markup, so it is a component: render `<Toaster />` once and send `event('TOAST', { text })` from any component.
+
+## Styling
+
+Style the parts with your own classes, the ones you pass in the options. The parts add these data attributes:
+
+| Attribute | On | Values |
+|---|---|---|
+| `data-state` | tabs and tab panels | `active`, `inactive` |
+| `data-state` | accordion and disclosure buttons and panels | `open`, `closed` |
+| `data-value` | tabs, accordion buttons | the value you passed |
+| `data-kind` | each toast | `info`, `success`, `warning`, `error` |
+| `data-paused` | the toast region | present while paused |
+
+The browser also exposes the open state: `dialog[open]`, `:modal`, `:popover-open`, `dialog::backdrop` and `[popover]::backdrop`.
+
+## Browser support
+
+The parts target current evergreen browsers: Chromium (Chrome, Edge), Firefox and Safari. They rely on `<dialog>`, the Popover API (including `popovertarget` and `toggle` events), the `:modal` pseudo-class and, for the Tooltip, CSS anchor positioning (`anchor-name`, `position-anchor`, `position-area`). Sygnal's browser suite runs every part in Chromium, Firefox and WebKit.
+
+The package has no JavaScript positioning fallback. To support a browser without CSS anchor positioning, position the tooltip with [Floating UI](#floating-ui-for-older-browsers) instead.
+
+### Floating UI for older browsers
+
+[Floating UI](https://floating-ui.com/) computes a position in JavaScript. Give the tip a [ref](https://sygnal.js.org/advanced/refs/) and run its `autoUpdate` while the tooltip is open, from an `EFFECT` on the behavior's `TOGGLED` action:
+
+```jsx live
+import { createRef } from 'sygnal'
+import { tooltip } from 'sygnal/ui'
+import { computePosition, autoUpdate, offset, flip, shift } from '@floating-ui/dom'
+
+const trigger = createRef()
+const tip = createRef()
+let stop = null
+
+function Toolbar({ uid }) {
+  return (
+    <div>
+      <button className="save" ref={trigger} aria-describedby={uid('tip')}>Save</button>
+      <div className="tip" ref={tip} id={uid('tip')} role="tooltip" popover="manual">Save the draft</div>
+    </div>
+  )
+}
+
+Toolbar.uses = { tip: tooltip({ trigger: '.save', tip: '.tip' }) }
+Toolbar.model = {
+  'tip.TOGGLED': {
+    EFFECT: (state, open) => {
+      stop?.()
+      stop = open ? autoUpdate(trigger.current, tip.current, () =>
+        computePosition(trigger.current, tip.current, { placement: 'top', strategy: 'fixed', middleware: [offset(6), flip(), shift()] })
+          .then(({ x, y }) => Object.assign(tip.current.style, { left: `${x}px`, top: `${y}px` }))) : null
+    },
+  },
+}
+```
+
+```css live
+.tip { position: fixed; margin: 0; inset: auto; }
+```
+
+A module-level ref is shared by every instance; for a component rendered more than once, keep the refs in a `Map` keyed by an id.
+
+## Size
+
+`sygnal/ui` is a separate entry. An app that doesn't import it ships none of it, and each part is tree-shaken on its own. The first behavior an app uses also brings in `defineBehavior` (about 1 KB gzipped). Measured in a small app, gzipped:
+
+| Part | Adds |
+|---|---|
+| Dialog | 0.4 KB + `defineBehavior` |
+| Popover | 0.2 KB + `defineBehavior` |
+| Tooltip | 0.3 KB + `defineBehavior` + `makeTimerDriver` (0.6 KB) |
+| Tabs, Accordion | about 1 KB each + `defineBehavior` |
+| Disclosure | 0.3 KB + `defineBehavior` |
+| Toaster | 1.1 KB + `makeTimerDriver` |
+| Menu (`sygnal/ui/menu`) | 33 KB, Zag included |
+| Select (`sygnal/ui/select`) | 33 KB, Zag included |
+| Combobox (`sygnal/ui/combobox`) | 34 KB, Zag included |
+| Menu + Select + Combobox | 47 KB (they share Zag's runtime and positioning) |
+
+## Testing
+
+`renderComponent()` tests the parts like any component. The default mock DOM records `ELEMENT` commands (`showModal`, `focus`) without running them, so a test simulates the browser's events (`close`, `toggle`) itself. The tooltip delays and toast timeouts run on [fake timers](https://sygnal.js.org/integration/testing/). Keyboard navigation in Tabs and Accordion reads the order of the elements on the page, so test it with `dom: 'real'`.
+
+```jsx
+// @vitest-environment jsdom
+import { it, expect } from 'vitest'
+import { within } from '@testing-library/dom'
+import userEvent from '@testing-library/user-event'
+import { renderComponent } from 'sygnal'
+import Settings from './Settings.jsx'
+
+it('moves between the tabs with the arrow keys', async () => {
+  const t = renderComponent(Settings, { dom: 'real' })
+  await t.ready()
+  const screen = within(t.container)
+  const user = userEvent.setup()
+
+  await user.click(screen.getByRole('tab', { name: 'General' }))
+  await user.keyboard('{ArrowRight}')
+  await t.waitForState((s) => s.tabs.selected === 'privacy')
+
+  expect(screen.getByRole('tab', { name: 'Privacy', selected: true })).toBeTruthy()
+  expect(screen.getByRole('tabpanel', { name: 'Privacy' })).toBeTruthy()
+  expect(t.actions.map((a) => a.type)).toContain('tabs.MOVE')
+  t.dispose()
+})
+```
+
+The [browser suite](https://github.com/tpresley/sygnal/tree/main/browser-tests) runs the parts in real engines, for what a DOM emulation doesn't have: the top layer, focus trapping, light dismiss and anchor positioning.

package/dist/guide/ui/popover.md

@@ -0,0 +1,101 @@
+<!-- Generated from docs/src/content/docs/ui by scripts/copy-guides.mjs; online: https://sygnal.js.org/ui/ -->
+# Popover
+
+`popover()` is a [behavior](../behaviors.md) for an element with the HTML `popover` attribute. The browser shows it in the top layer, above everything else, and a button with `popovertarget` opens and closes it with no code at all. The browser also closes it when the user clicks outside or presses Escape (light dismiss), sets `aria-expanded` on the button and returns the focus to it. The behavior keeps `open` in state and lets the model open and close the popover.
+
+```jsx live
+import { popover } from 'sygnal/ui'
+
+function Filters({ state, uid }) {
+  return (
+    <div>
+      <button className="filters-button" popovertarget={uid('filters')}>Filters</button>
+      <div className="filters" id={uid('filters')} popover="auto" aria-label="Filters">
+        <label><input type="checkbox" className="only-open" checked={state.onlyOpen} /> Only open tasks</label>
+        <button className="filters-done">Done</button>
+      </div>
+      <p>{state.filters.open ? 'Choosing filters…' : ''}</p>
+    </div>
+  )
+}
+
+Filters.initialState = { onlyOpen: false }
+Filters.uses = { filters: popover({ popover: '.filters', close: '.filters-done' }) }
+Filters.intent = ({ DOM }) => ({ ONLY_OPEN: DOM.change('.only-open').checked() })
+Filters.model = { ONLY_OPEN: (state, onlyOpen) => ({ ...state, onlyOpen }) }
+```
+
+`popovertarget` takes the popover's `id`; `uid()` keeps it unique when the component is rendered more than once.
+
+## Options
+
+| Option | | |
+|---|---|---|
+| `popover` | (required) | The popover element: a selector or a [control](https://sygnal.js.org/guide/controls/) |
+| `close` | | A button inside: its clicks close the popover |
+
+There is no `trigger` option: open it with a `popovertarget` button. A button that toggled an `auto` popover through the model would open it again right after closing it, because the press outside the popover light-dismisses it first; the browser exempts `popovertarget` buttons from that.
+
+## State and actions
+
+`state.filters` is `{ open }`. It follows the popover's `toggle` event, whatever opened or closed it.
+
+| Action | Data | |
+|---|---|---|
+| `filters.OPEN` | | Shows the popover (`showPopover`) |
+| `filters.CLOSE` | | Hides it (`hidePopover`) |
+| `filters.TOGGLE` | | Toggles it (`togglePopover`) |
+| `filters.TOGGLED` | `true` / `false` | The `toggle` event: sets `open` |
+| `filters.SYNC` | `false` | The popover left the page while open (a page change, a conditional render): sets `open: false`, as no `toggle` event comes |
+
+`OPEN` and `CLOSE` check the popover itself (`:popover-open`), not `state.filters.open`, which follows the `toggle` event a moment later: `OPEN` then `CLOSE` in one go leaves it closed, and `showPopover()` is never called on an open popover.
+
+Open it from somewhere else, for example a keyboard shortcut, with an intent action of the same name: `'filters.OPEN': DOM.keydown('document').filter((e) => e.key === 'f' && e.altKey)`.
+
+## `auto` or `manual`
+
+- `popover="auto"` (or just `popover`): light dismiss, and opening one closes the other `auto` popovers that aren't its ancestors. Menus, pickers and filter panels.
+- `popover="manual"`: only your code and its `popovertarget` button close it. Use it for something that stays open, such as a [tooltip](./tooltip.md) or [toasts](./toaster.md).
+
+A popover inside a modal [dialog](./dialog.md) works: it opens above the dialog, the first Escape closes the popover and the second the dialog.
+
+## Accessibility
+
+- Name the popover (`aria-label` or `aria-labelledby`) when it is a region of controls, as above.
+- `popovertarget` gives the button `aria-expanded` and links it to the popover for assistive technology. The browser returns the focus to the button when the popover closes with the focus inside it.
+- For a menu with arrow-key navigation, use a menu part, not a bare popover.
+
+## Styling
+
+Browsers center a popover in the viewport by default. To place it next to its button, use [CSS anchor positioning](./tooltip.md#positioning):
+
+```css live
+.filters-button { anchor-name: --filters; }
+.filters { position-anchor: --filters; position-area: bottom span-right; margin: 4px 0 0; inset: auto; }
+.filters:popover-open { animation: fade-in 120ms ease-out; }
+```
+
+For a component rendered more than once, give each instance its own anchor name, from `uid()` in a `style` prop, as the tooltip does.
+
+## Testing
+
+The mock DOM doesn't open popovers, so simulate the `toggle` event as the browser sends it:
+
+```jsx
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import Filters from './Filters.jsx'
+
+it('follows the popover and closes it from the Done button', async () => {
+  const t = renderComponent(Filters)
+  await t.ready()
+  t.simulateEvent('.filters', 'toggle', { newState: 'open', oldState: 'closed' })
+  await t.next((s) => s.filters.open)
+
+  t.simulateEvent('.filters-done', 'click')
+  await t.settle()
+  expect(t.commands('ELEMENT')).toEqual([{ hidePopover: '.filters' }])
+  expect(t.actions.map((a) => a.type)).toEqual(['INITIALIZE', 'filters.TOGGLED', 'filters.CLOSE'])
+  t.dispose()
+})
+```