sygnal 5.3.7 → 6.0.0

package/dist/guide/ui/select.md

@@ -0,0 +1,114 @@
+<!-- Generated from docs/src/content/docs/ui by scripts/copy-guides.mjs; online: https://sygnal.js.org/ui/ -->
+# Select
+
+`Select` is a custom select: a button that shows the chosen option and opens a listbox, following the [WAI-ARIA select-only combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/). Keyboard, focus and typeahead come from [Zag.js](https://zagjs.com)'s select machine, rendered with [`fromZag`](../adapters.md#zag-machines-fromzag). It is a [widget](../widgets.md) tag.
+
+A native `<select>` is smaller and works everywhere; use `Select` when the options need custom styling, or several values with checkmarks.
+
+```jsx live
+import { Select } from 'sygnal/ui/select'
+
+const SIZES = [
+  { value: 's', label: 'Small' },
+  { value: 'm', label: 'Medium' },
+  { value: 'l', label: 'Large', disabled: true },
+]
+
+function Order({ state }) {
+  return (
+    <form className="order">
+      <Select className="size" label="Size" items={SIZES} value={state.size} placeholder="Pick a size" name="size" />
+      <p>{state.size ? `Size: ${state.size}` : 'No size yet'}</p>
+    </form>
+  )
+}
+
+Order.initialState = { size: null }
+Order.intent = ({ DOM }) => ({
+  SIZE: DOM.select('.size').events('value-change').detail(),
+})
+Order.model = {
+  SIZE: (state, size) => ({ ...state, size }),
+}
+```
+
+The value is controlled: the select shows `state.size`, and `value-change` reports the user's choice. Leave `value` out (or use `defaultValue`) to let the select keep its own value.
+
+Install Zag's packages first: `npm install @zag-js/vanilla@~1.45.0 @zag-js/select@~1.45.0` (see [Menu](./menu.md#install)).
+
+## Props
+
+| Prop | | |
+|---|---|---|
+| `label` | | The visible label, linked to the trigger (its accessible name). Give every select one |
+| `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. Values are strings |
+| `value` | | Controlled: the value (an array with `multiple`); `null` for none |
+| `defaultValue` | | The start value when `value` is left out |
+| `placeholder` | | Shown while nothing is selected |
+| `multiple` | `false` | Several values; the list stays open while picking |
+| `name`, `form` | | The form field: a hidden native `<select>` carries the value in `FormData` |
+| `disabled`, `readOnly`, `required`, `invalid` | | |
+| `deselectable` | `false` | A click on the selected option clears it |
+| `closeOnSelect` | `true` | With `multiple`: `false` |
+| `loopFocus` | `false` | |
+| `positioning` | | Zag's positioning options: `{ placement: 'bottom-start', sameWidth: true }` |
+| `open` | | Controlled open state; follow `open-change` |
+
+## Events and commands
+
+| Event | Detail |
+|---|---|
+| `value-change` | The value (with `multiple`: the array of values); `null` when cleared |
+| `open-change` | `true` / `false` |
+
+Commands for `ELEMENT`: `open`, `close`, `clear`, and `focus` (the trigger): `CLEAR_SIZE: { ELEMENT: { clear: '.size' } }`.
+
+## Keyboard
+
+| Key | |
+|---|---|
+| Enter, Space, Down, Up | On the trigger: open the list |
+| A letter | On the trigger: select the next option starting with it; in the list: move to it |
+| Down / Up, Home / End | Move in the list; disabled options are skipped |
+| Enter | Select the highlighted option and close; the focus returns to the trigger |
+| Escape, Tab | Close |
+
+## Styling
+
+Zag's data attributes: `[data-scope="select"]` with `[data-part="root"]`, `"label"`, `"control"`, `"trigger"`, `"value-text"`, `"indicator"`, `"positioner"`, `"content"`, `"item"`, `"item-text"` and `"item-indicator"`. The trigger and content have `data-state`, options `data-highlighted`, `data-state="checked"` and `data-disabled`, and the value text `data-placeholder-shown` while empty. The item indicator (`✓`) is `hidden` on unselected options.
+
+```css live
+.size [data-part='trigger'] { min-width: 10rem; display: flex; justify-content: space-between; }
+.size [data-part='content'] { background: Canvas; border: 1px solid #ddd; }
+.size [data-part='item'] { padding: 4px 8px; }
+.size [data-part='item'][data-highlighted] { background: rgb(99 102 241 / 0.25); }
+.size [data-part='item'][data-disabled] { opacity: 0.5; }
+```
+
+## Positioning
+
+The listbox 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 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 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
+
+```jsx
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import Order from './Order.jsx'
+
+it('keeps the chosen size', async () => {
+  const t = renderComponent(Order)
+  await t.ready()
+  t.widget('.size').dispatch('value-change', 'm')
+  await t.next((state) => state.size === 'm')
+  expect(t.widget('.size').props.value).toBe('m')
+  t.dispose()
+})
+```
+
+For keyboard tests, see [Menu](./menu.md#testing).
+
+## Size
+
+Gzipped, in a small app: Select adds **33 KB** (mostly Zag's select machine, its positioning and `@zag-js/vanilla`). With Menu and Combobox, the three add 47 KB together.

package/dist/guide/ui/tabs.md

@@ -0,0 +1,161 @@
+<!-- Generated from docs/src/content/docs/ui by scripts/copy-guides.mjs; online: https://sygnal.js.org/ui/ -->
+# Tabs
+
+`tabs()` is a [behavior](../behaviors.md) that turns your own buttons and panels into tabs, following the [WAI-ARIA tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/). `tabsAttrs()` computes the attributes to spread on them: roles, ids that link each tab to its panel, `aria-selected`, the roving `tabindex` and `hidden` on the other panels.
+
+```jsx live
+import { tabs, tabsAttrs } from 'sygnal/ui'
+
+const SECTIONS = [
+  { id: 'general', label: 'General' },
+  { id: 'privacy', label: 'Privacy' },
+  { id: 'billing', label: 'Billing' },
+]
+
+function Settings({ state, uid }) {
+  const a = tabsAttrs(state.tabs, uid)
+  return (
+    <div className="settings">
+      <div className="tab-list" {...a.list} aria-label="Settings">
+        {SECTIONS.map((s) => <button className="tab" {...a.tab(s.id)}>{s.label}</button>)}
+      </div>
+      {SECTIONS.map((s) => (
+        <section className="tab-panel" {...a.panel(s.id)}>
+          <h2>{s.label}</h2>
+        </section>
+      ))}
+    </div>
+  )
+}
+
+Settings.uses = { tabs: tabs({ tab: '.tab', selected: 'general' }) }
+```
+
+`state.tabs.selected` is the selected tab's value. Render every panel: the ones not selected get `hidden`, and each tab's `aria-controls` points at its panel.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `tab` | (required) | The tabs: a selector or a [control](https://sygnal.js.org/guide/controls/) |
+| `selected` | | The tab selected at the start. Without it, the first tab rendered is selected |
+| `orientation` | `'horizontal'` | `'vertical'`: Up and Down move between the tabs instead of Left and Right |
+| `activation` | `'automatic'` | `'manual'`: the arrow keys only move the focus; Enter or Space selects |
+| `loop` | `true` | The arrow keys wrap from the last tab to the first |
+| `id` | the key in `uses` | The prefix of the ids |
+
+## Keyboard
+
+| Key | |
+|---|---|
+| Tab | Into the tab list, onto the selected tab; Tab again goes to its panel |
+| Right / Left (Down / Up when vertical) | The next or previous tab, wrapping; it is selected too, unless `activation: 'manual'` |
+| Home / End | The first or last tab |
+| Enter / Space | Selects the focused tab (a button click) |
+
+Disabled tabs (`disabled`) are skipped.
+
+## State, actions and attributes
+
+`state.tabs` is `{ id, selected, orientation }`. Actions: `tabs.SELECT` (a value; a click on a tab sends its own) and `tabs.MOVE` (a value: focus that tab, and select it unless manual). Select a tab from the model with `next('tabs.SELECT', 'billing')`, or from your intent with `'tabs.SELECT': DOM.click('.go-billing').mapTo('billing')`.
+
+`tabsAttrs(state.tabs, uid)` returns:
+
+| | Attributes |
+|---|---|
+| `list` | `role="tablist"`, `aria-orientation` |
+| `tab(value)` | `id`, `role="tab"`, `aria-selected`, `aria-controls`, `tabindex` (`0` on the selected tab, `-1` on the others), `type="button"`, `data-value`, `data-state` (`active` / `inactive`) |
+| `panel(value)` | `id`, `role="tabpanel"`, `aria-labelledby`, `tabindex="0"`, `hidden` unless selected, `data-state` |
+
+Values are compared as strings.
+
+`tabsAttrs(state.tabs, uid, values)` takes the tabs' values, in order, as an optional third argument (leave disabled tabs out). Pass it when the tabs can change: a `selected` value that isn't among them (its tab was removed) then shows the first tab selected, so there is always a tab to Tab into and a panel shown. Without it, the first tab rendered is selected only while nothing is.
+
+## Closable tabs
+
+When the user closes the selected tab, select a neighbour in the same reducer and move the focus to it (the close button that had the focus is gone):
+
+```jsx live
+import { ABORT } from 'sygnal'
+import { tabs, tabsAttrs } from 'sygnal/ui'
+
+function Editor({ state, uid }) {
+  const a = tabsAttrs(state.tabs, uid, state.files.map((f) => f.id))
+  return (
+    <div>
+      <div className="tab-list" {...a.list} aria-label="Open files">
+        {state.files.map((f) => (
+          <span className="tab-wrap">
+            <button className="tab" {...a.tab(f.id)}>{f.name}</button>
+            <button className="close" data-value={f.id} aria-label={'Close ' + f.name}>×</button>
+          </span>
+        ))}
+      </div>
+      {state.files.map((f) => <section className="tab-panel" {...a.panel(f.id)}>{f.text}</section>)}
+    </div>
+  )
+}
+
+Editor.uses = { tabs: tabs({ tab: '.tab' }) }
+Editor.initialState = {
+  files: [
+    { id: 'readme', name: 'README.md', text: 'About this project' },
+    { id: 'main', name: 'main.js', text: 'run(App)' },
+    { id: 'styles', name: 'styles.css', text: 'body { margin: 0 }' },
+  ],
+}
+
+Editor.intent = ({ DOM }) => ({ CLOSE: DOM.click('.close').data('value') })
+
+// the file after the closed one, or the one before it when it was the last
+const neighbour = (files, id) => {
+  const i = files.findIndex((f) => f.id === id), rest = files.filter((f) => f.id !== id)
+  return rest[Math.min(i, rest.length - 1)]
+}
+
+Editor.model = {
+  CLOSE: {
+    STATE: (state, id) => ({
+      ...state,
+      files: state.files.filter((f) => f.id !== id),
+      tabs: { ...state.tabs, selected: state.tabs.selected === id ? (neighbour(state.files, id)?.id ?? null) : state.tabs.selected },
+    }),
+    ELEMENT: (state, id) => {
+      const next = neighbour(state.files, id)
+      return next ? { focus: `.tab[data-value="${next.id}"]` } : ABORT
+    },
+  },
+}
+```
+
+(`ELEMENT` gets the state before the action, as every non-`STATE` entry does.)
+
+## Styling
+
+```css live
+.tab-list { display: flex; gap: 4px; border-bottom: 1px solid #ddd; }
+.tab[data-state='active'] { border-bottom: 2px solid currentColor; font-weight: 600; }
+.tab-panel:focus-visible { outline: 2px solid #2563eb; }
+```
+
+## Testing
+
+The arrow keys read the order of the tabs on the page, so test them with `dom: 'real'`. Clicks and `simulateAction` work on the mock DOM:
+
+```jsx
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import Settings from './Settings.jsx'
+
+it('selects a tab and shows its panel', async () => {
+  const t = renderComponent(Settings)
+  await t.ready()
+  t.simulateEvent('.tab', 'click', { data: { value: 'privacy' } })
+  await t.next((s) => s.tabs.selected === 'privacy')
+  expect(t.query('.tab[data-value="privacy"]').getAttribute('aria-selected')).toBe('true')
+  expect(t.actions.map((a) => a.type)).toEqual(['INITIALIZE', 'tabs.SELECT'])
+  t.dispose()
+})
+```
+
+The [UI parts overview](./overview.md#testing) shows a keyboard test with Testing Library.

package/dist/guide/ui/toaster.md

@@ -0,0 +1,152 @@
+<!-- Generated from docs/src/content/docs/ui by scripts/copy-guides.mjs; online: https://sygnal.js.org/ui/ -->
+# Toaster
+
+`<Toaster>` shows short notifications ("Saved", "Upload failed") that any component sends as an event. Render it once, near the root of the app:
+
+```jsx live
+// App.jsx
+import { Toaster } from 'sygnal/ui'
+import { Editor } from './Editor.jsx'
+
+export default function App({ state }) {
+  return (
+    <div className="app">
+      <h1>{state.title}</h1>
+      <Editor />
+      <Toaster />
+    </div>
+  )
+}
+
+App.initialState = { title: 'Notes' }
+```
+
+```js
+import { run, makeTimerDriver } from 'sygnal'
+import App from './App.jsx'
+
+run(App, { TIMER: makeTimerDriver() })
+```
+
+Then send a toast from anywhere, through the `EVENTS` bus:
+
+```jsx live-file=./Editor.jsx
+// Editor.jsx
+import { event } from 'sygnal'
+
+export function Editor({ state }) {
+  return (
+    <div className="editor">
+      <label>Note <textarea className="text" value={state.text} /></label>
+      <button className="save">Save</button>
+    </div>
+  )
+}
+
+Editor.initialState = { text: '' }
+Editor.isolatedState = true
+Editor.intent = ({ DOM }) => ({ TEXT: DOM.input('.text').value(), SAVE: DOM.click('.save') })
+Editor.model = {
+  TEXT: (state, text) => ({ ...state, text }),
+  SAVE: { EVENTS: event('TOAST', { text: 'Note saved', kind: 'success' }) },
+}
+```
+
+The timer driver dismisses toasts after their timeout. Without it, they stay until dismissed.
+
+## The TOAST event
+
+| Field | Default | |
+|---|---|---|
+| `text` | (required) | The message. `event('TOAST', 'Saved')` is short for `{ text: 'Saved' }` |
+| `kind` | `'info'` | `'info'`, `'success'`, `'warning'` or `'error'`. Errors are announced at once (`role="alert"`), the others politely (`role="status"`) |
+| `timeoutMs` | `5000` | ms until it dismisses itself; `0` keeps it until the user dismisses it |
+| `id` | `'t1'`, `'t2'`… | A toast sent with the `id` of a shown one replaces it in place and starts its timeout again. Ids compare as strings (`7` and `'7'` are the same toast); the automatic ones never equal an id of a shown toast |
+
+`event('TOAST_DISMISS', id)` removes the toast with that `id`; `event('TOAST_DISMISS')` removes all of them. With ids, a long task can report its progress in one toast:
+
+```jsx
+Upload.model = {
+  START: { EVENTS: event('TOAST', { id: 'upload', text: 'Uploading…', timeoutMs: 0 }) },
+  DONE: { EVENTS: event('TOAST', { id: 'upload', text: 'Upload complete', kind: 'success' }) },
+}
+```
+
+## Props
+
+| Prop | Default | |
+|---|---|---|
+| `label` | `'Notifications'` | The region's accessible name |
+| `dismissLabel` | `'Dismiss'` | The text of each toast's dismiss button; its accessible name is `Dismiss: <text>` |
+| `pauseOnHover` | `true` | The timeouts stop while the pointer or the keyboard focus is in the region, and start over when it leaves |
+| `transition` | `'toast'` | The [Transition](https://sygnal.js.org/advanced/transitions/) class prefix: `toast-enter-from`, `toast-leave-to`… |
+| `duration` | `200` | How long a dismissed toast stays for its leave animation, in ms |
+| `className` | | More classes on the region |
+
+## Markup and styling
+
+```html
+<div class="toaster-home">
+  <section class="toaster" aria-label="Notifications" popover="manual" data-paused>
+    <div class="toaster-status" role="status" aria-live="polite">
+      <div class="toaster-list">
+        <div class="toast" data-kind="success">
+          <span class="toast-text">Note saved</span>
+          <button class="toast-dismiss" aria-label="Dismiss: Note saved">Dismiss</button>
+        </div>
+      </div>
+    </div>
+    <div class="toaster-alert" role="alert"><div class="toaster-list"></div></div>
+  </section>
+</div>
+```
+
+The region is a popover, so the browser draws it in the top layer, centred and with a border. Place it in a corner and style the toasts:
+
+```css live
+.toaster { inset: auto 1rem 1rem auto; margin: 0; padding: 0; border: 0; background: none; overflow: visible; }
+.toast { display: flex; gap: 0.75rem; align-items: center; margin-top: 0.5rem; padding: 0.75rem 1rem;
+  border-radius: 6px; background: #1f2937; color: #fff; }
+.toast[data-kind='error'] { background: #b91c1c; }
+.toast-enter-active, .toast-leave-active { transition: opacity 200ms, transform 200ms; }
+.toast-enter-from, .toast-leave-to { opacity: 0; transform: translateY(0.5rem); }
+```
+
+## Above modal dialogs
+
+An open modal `<dialog>` makes the rest of the page inert: a toast outside it would be visible but couldn't be clicked or reached with Tab, and screen readers would skip it. While a modal dialog is open, the Toaster moves its region into that dialog, where it stays on top and usable, and back when the dialog closes or is removed. Toasts shown before the dialog opened move with it. Nothing is needed on your side; the region keeps its events, Collection items and timers wherever it is.
+
+It sees the modal dialogs of the page and of its own shadow root, so a Toaster inside a [custom element](../web-components.md) moves into that element's dialogs too.
+
+## Accessibility
+
+- The `role="status"` and `role="alert"` regions are always rendered, even when empty, so screen readers announce a toast when it is added.
+- Keep toasts short and don't put the only copy of important information in them: they go away. Use `timeoutMs: 0` for a message the user must act on.
+- The timeouts pause while the user hovers or tabs into the toasts ([WCAG 2.2.1](https://www.w3.org/WAI/WCAG22/Understanding/timing-adjustable)), and stay paused while either the pointer or the focus is still there.
+- Dismissing a toast with its focused Dismiss button moves the focus to the next toast's Dismiss button, or the previous one's, and after the last toast back to where it was before it entered the toasts.
+
+## Testing
+
+`renderComponent()` renders the Toaster with the rest of the app; the timeouts run on fake timers without a driver:
+
+```jsx
+import { it, expect, vi } from 'vitest'
+import { renderComponent } from 'sygnal'
+import App from './App.jsx'
+
+it('shows a toast when a note is saved, and removes it after 5 s', async () => {
+  vi.useFakeTimers()
+  const t = renderComponent(App)
+  await t.ready()
+  t.simulateEvent('.save', 'click')
+  await t.settle()
+  expect(t.query('.toast-text').textContent).toBe('Note saved')
+  expect(t.emitted.map((e) => e.type)).toContain('TOAST')
+
+  await vi.advanceTimersByTimeAsync(5000)
+  await t.settle()
+  expect(t.queryAll('.toast')).toHaveLength(0)
+  t.dispose()
+  vi.useRealTimers()
+})
+```

package/dist/guide/ui/tooltip.md

@@ -0,0 +1,103 @@
+<!-- Generated from docs/src/content/docs/ui by scripts/copy-guides.mjs; online: https://sygnal.js.org/ui/ -->
+# Tooltip
+
+`tooltip()` is a [behavior](../behaviors.md) that shows a short description of a control when the pointer rests on it or it gets the keyboard focus. The tip is a `popover="manual"` element, so it is drawn in the top layer, above dialogs and scrolling containers. CSS anchor positioning places it next to its trigger; there is no JavaScript positioning. The show and hide delays are [timers](../timers.md), so they are cancelled when the pointer leaves early and they run on fake timers in tests.
+
+```jsx live
+import { tooltip } from 'sygnal/ui'
+
+function Toolbar({ uid }) {
+  const anchor = '--' + uid('save')
+  return (
+    <div className="toolbar">
+      <button className="save" aria-describedby={uid('save-tip')} style={{ anchorName: anchor }}>Save</button>
+      <div className="tip" id={uid('save-tip')} role="tooltip" popover="manual" style={{ positionAnchor: anchor }}>
+        Save the draft (Ctrl+S)
+      </div>
+    </div>
+  )
+}
+
+Toolbar.uses = { saveTip: tooltip({ trigger: '.save', tip: '.tip' }) }
+```
+
+```js
+import { run, makeTimerDriver } from 'sygnal'
+import Toolbar from './Toolbar.jsx'
+
+run(Toolbar, { TIMER: makeTimerDriver() })
+```
+
+The delays need the timer driver in `run()`. Tests don't: [fake timers](../timers.md#testing) drive them.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `trigger` | (required) | The element it describes |
+| `tip` | (required) | The tooltip element: `role="tooltip"`, `popover="manual"` |
+| `showDelay` | `500` | ms the pointer or focus must stay before it shows |
+| `hideDelay` | `100` | ms before it hides after the pointer or focus leaves |
+
+## Behavior
+
+- Hovering or focusing the trigger shows the tip after `showDelay`; leaving before that never shows it.
+- Leaving hides it after `hideDelay`. Moving the pointer from the trigger onto the tip keeps it open, so the tip can be read and selected ([WCAG 1.4.13](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus)).
+- The pointer and the focus count apart: it hides once both have left, so the mouse moving away doesn't hide a tip the keyboard focus still shows.
+- Touch is left out: a tap focuses the trigger, which shows the tip as focus does.
+- Escape hides it at once, without moving the focus. (The behavior listens for it on the document only while the tip is shown or about to be.)
+
+`state.saveTip` is `{ open, pending, hover, focus }`: `pending` is `'show'` or `'hide'` while a delay runs; `hover` and `focus` say where the pointer and the focus are. The actions are `saveTip.ENTER` and `saveTip.LEAVE` (data: `'hover'` or `'focus'`), `saveTip.SHOW`, `saveTip.HIDE` (the timers), `saveTip.ESCAPE` and `saveTip.TOGGLED`. The timers are declared under the names `saveTip.show` and `saveTip.hide`, next to the component's own [`timers`](../timers.md).
+
+## Positioning
+
+The trigger gets an anchor name and the tip refers to it. The anchor name must be unique on the page, so build it from `uid()` in the view, as above. The rest is CSS:
+
+```css live
+.tip {
+  position-area: top;      /* above the trigger, centred */
+  position-try: flip-block; /* below it when there is no room above */
+  inset: auto;
+  margin: 0 0 6px;
+  padding: 4px 8px;
+  border: none;
+  border-radius: 4px;
+  background: #222;
+  color: #fff;
+  font-size: 0.875rem;
+}
+```
+
+`inset: auto` and `margin` replace the popover's default centring. Browsers without CSS anchor positioning need JavaScript positioning: see [Floating UI for older browsers](./overview.md#floating-ui-for-older-browsers).
+
+Safari 26 places the tip wrongly when the trigger is inside a `position: fixed` element (a fixed toolbar or header) and the page is scrolled: the tip moves up by the scroll distance. Triggers in the normal flow of the page are placed correctly. For triggers in a fixed bar, the Floating UI recipe works in every browser.
+
+## Accessibility
+
+- `aria-describedby` on the trigger points at the tip, so screen readers read the tip as the trigger's description. The trigger still needs its own name (its text or `aria-label`).
+- Keep the tip short and plain text; it can't take the focus. For anything interactive, use a [popover](./popover.md).
+- Don't rely on a tooltip for touch users: there is no hover, and a tap focuses the trigger only briefly.
+
+## Testing
+
+```jsx
+import { it, expect, vi } from 'vitest'
+import { renderComponent } from 'sygnal'
+import Toolbar from './Toolbar.jsx'
+
+it('shows the tip after the delay', async () => {
+  vi.useFakeTimers()
+  const t = renderComponent(Toolbar)
+  await t.ready()
+  t.simulateEvent('.save', 'pointerenter')
+  await t.next((s) => s.saveTip.pending === 'show')
+  expect(t.timers()).toEqual([{ name: 'saveTip.show', after: 500, action: 'saveTip.SHOW', component: 'Toolbar' }])
+
+  await vi.advanceTimersByTimeAsync(500)
+  await t.settle()
+  expect(t.commands('ELEMENT')).toEqual([{ showPopover: '.tip' }])
+  expect(t.actions.map((a) => a.type)).toEqual(['INITIALIZE', 'saveTip.ENTER', 'saveTip.SHOW'])
+  t.dispose()
+  vi.useRealTimers()
+})
+```