sygnal 5.4.0 → 6.0.0

package/dist/guide/drag-and-drop.md

@@ -0,0 +1,342 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Drag and Drop
+
+Sygnal has two tools for drag and drop:
+
+- **`sortable`**, a [behavior](./behaviors.md) that reorders a list in the component's state by mouse, pen, touch **and keyboard**, with screen-reader announcements. Use it for reordering: task lists, playlists, kanban columns (moves between lists included).
+- **`makeDragDriver()`**, a driver for native HTML5 drag and drop at the document level. Use it when the browser's drag-and-drop model is the point: dropping files from the desktop, dragging between components that don't share a host, arbitrary drop zones, or native drag images. HTML5 drag and drop has no keyboard or touch support of its own, so give those users another way (a menu, buttons).
+
+## Sortable lists
+
+`sortable({ from, item, handle })` reorders `state[from]`. The items are usually a Collection; each item's element carries its id in `data-id`, and the handle is a button inside it:
+
+```jsx live
+import { Collection, sortable } from 'sygnal'
+
+function Task({ state, context }) {
+  const { dragging, over, after, helpId } = context.sort
+  const id = String(state.id)
+  const cls = ['task', dragging === id && 'dragging', over === id && dragging !== id && (after ? 'drop-after' : 'drop-before')]
+  return (
+    <li className={cls.filter(Boolean).join(' ')} data-id={state.id}>
+      <button type="button" className="grip" aria-label={`Reorder ${state.title}`}
+        aria-describedby={helpId} aria-pressed={String(dragging === id)}>⠿</button>
+      <span className="title">{state.title}</span>
+    </li>
+  )
+}
+
+function TaskList({ state }) {
+  return (
+    <section>
+      <p id={state.sort.helpId} hidden>
+        Press Space or Enter to pick up a task, the arrow keys to move it, Space or Enter to drop it, and Escape to cancel.
+      </p>
+      <ul className="tasks"><Collection of={Task} from="tasks" /></ul>
+      <p className="announcer" role="status" aria-live="assertive">{state.sort.message}</p>
+    </section>
+  )
+}
+
+TaskList.initialState = {
+  tasks: [{ id: 1, title: 'Write spec' }, { id: 2, title: 'Build it' }, { id: 3, title: 'Ship' }],
+}
+TaskList.uses = { sort: sortable({ from: 'tasks', item: '.task', handle: '.grip' }) }
+TaskList.context = { sort: (state) => state.sort }
+TaskList.model = {
+  // one completed move: save the order
+  'sort.DROPPED': { HTTP: (state, move) => ({ url: '/api/tasks/order', method: 'PUT', json: { ids: state.tasks.map((t) => t.id), move } }) },
+}
+```
+
+```css live
+.grip { touch-action: none; user-select: none; cursor: grab; }
+.task.dragging { opacity: 0.5; }
+.task.drop-before { box-shadow: 0 -2px 0 royalblue; }
+.task.drop-after { box-shadow: 0 2px 0 royalblue; }
+```
+
+The behavior listens on the host's root element, so it hears the presses and keys that bubble out of the Collection items (which are isolated components): nothing is wired per item. The items read the drag state through [context](https://sygnal.js.org/guide/context/).
+
+The announcements in `state.sort.message` are English defaults ("Dropped Write tests at position 2 of 3.", "Reorder cancelled. Write tests is back at position 1 of 3."). When a spec gives its own wording, set it with the `messages` option: `sortable({ from: 'tasks', messages: { cancel: (label, n, m) => 'Cancelled. ' + label + ' is back at position ' + n + ' of ' + m + '.' } })`; the others keep their defaults.
+
+### Options
+
+| Option | Default | |
+|---|---|---|
+| `from` | (required) | The host state key of the list. An array of keys (`['todo', 'done']`) allows moves between lists; see [Several lists](#several-lists) |
+| `item` | `'[data-id]'` | Selector of each item's element |
+| `handle` | the item | Selector of the part that starts a drag and takes keyboard focus. Without one, the whole item does, and presses on buttons, links and fields inside it are left to them |
+| `attr` | `'data-id'` | The item element's attribute that holds its id |
+| `idField` | `'id'` | The id field of the list's entries (ids compare as strings) |
+| `axis` | `'y'` | `'y'`: ArrowUp / ArrowDown move, ArrowLeft / ArrowRight change lists; `'x'`: the other way round |
+| `threshold` | `4` | Pixels a pointer moves before a drag starts (a shorter press is a click) |
+| `label` | title, name, label or id | `(entry) => string`: the item's name in announcements |
+| `messages` | English | `{ lift, move, drop, cancel, stay }`, each `(label, position, count, extra) => string`. `extra`: for `lift`, true on a keyboard lift; for `move`, `drop` and `stay`, the list key when the item changed lists. `stay`: Escape after something else changed the list, so the item stays where it is |
+
+### State and actions
+
+`state.sort` (the key you chose in `uses`):
+
+| Field | |
+|---|---|
+| `dragging` | The id (a string) of the item being moved, or `null` |
+| `over`, `after` | Pointer drags: the id under the pointer, and whether the item lands after it (`true`) or before it |
+| `list` | Pointer drags: the list the item would land in (several lists) |
+| `mode` | `'pointer'`, `'keyboard'` or `null` |
+| `message` | The announcement to render in a live region: picked up, moved, dropped, cancelled |
+| `helpId` | A [`uid()`](./inputs.md#labels-and-ids-uid) id for the instructions element, unique to this host (two lists on a page get two ids); `null` until the first focus, press or key inside the host |
+
+`helpId` is set when the host is first used, not when it starts, so nothing is written into the state of a host that is never touched (a Collection item's state is its parent's data). A handle has its description by the time it is focused. The server renders no `helpId`, and neither does the client's first render, so hydration matches.
+
+`sort.DROPPED` fires once per completed move with `{ id, list, index, fromList, fromIndex }`: after a pointer drop, or a keyboard drop away from where the item started. The list in the state is already in its new order. Add a host entry for it to save the order. The other actions (`sort.PRESS`, `MOVE`, `UP`, `CANCEL`, `KEY`, `INIT`, `HELP`, `END`) are the behavior's own.
+
+### Keyboard
+
+| Key | |
+|---|---|
+| Space or Enter on a handle | Pick the item up (and announce the instructions) |
+| ArrowUp / ArrowDown (`axis: 'x'`: ArrowLeft / ArrowRight) | Move it one place; the list reorders as you go |
+| ArrowLeft / ArrowRight (`axis: 'x'`: ArrowUp / ArrowDown) | Move it to the previous / next list, at the same position |
+| Home / End | Move it to the start / end |
+| Space or Enter | Drop it |
+| Escape | Put it back where it started (unless something else changed the list meanwhile: see below) |
+| Tab | Drop it where it is; focus moves on |
+
+Focus stays on the moved item's handle after each step (an [`ELEMENT` command](./element-commands.md) through [`focusWithin`](./element-commands.md#focusing-inside-children-focuswithin), since the keyed Collection may move the focused element). If focus moves to another element while an item is lifted (a click elsewhere, a screen reader's own navigation) or a pointer is pressed anywhere, the item is dropped where it is, as Tab does; a press on a handle then starts a pointer drag at once. Losing focus to nothing (switching windows) keeps the item lifted. A held Space or Enter (the key's auto-repeat) doesn't drop and lift again.
+
+If the host is removed while an item is lifted (a route change, a parent hiding it), the drag is cancelled the same way, and no `sort.DROPPED` fires, so state that outlives the host (a parent's) isn't left half-moved. A pointer drag in progress is dropped too (the list hasn't changed yet).
+
+Cancelling (Escape, the host removed or made again) puts the list back only when nothing else has changed it since the last arrow key: the lists are then exactly the arrays the drag made, and the ones it lifted the item from come back as they were. When anything else changed them in the meantime (an entry edited, added or removed, the list replaced by new data, an undo or redo, another action reordering it, another tab's copy), the item stays where it is and the drag just ends: the behavior doesn't guess where the item belongs in a list that changed under it. Escape then announces that the item stays (`messages.stay`).
+
+The check is by identity, so a list that is made again on every step never matches, and cancelling it always leaves the item where it is: a host whose state comes through a lens that builds new arrays on each read (`get: s => s.tasks.map(...)` or a filter), or a host's own `sort.KEY` entry that returns a new array (normalising or re-sorting the list after each arrow key). Keep the lists the behavior sorts as stored arrays (a plain key or a lens that passes them through) for Escape to put them back. Undo is unaffected: a dropped drag is still one step.
+
+### Pointer and touch
+
+A press on a handle followed by a move past `threshold` starts a drag. While it moves, `over` and `after` say where the item would land, for a drop indicator; the list itself changes on release (a release over nothing, or outside the list, cancels). Escape cancels a pointer drag too. Mouse, pen and touch work the same way (Pointer Events, with document listeners only while a press is active).
+
+For touch, give the handle `touch-action: none`, or the browser scrolls the page instead (and cancels the drag). While a pointer is pressed the behavior blocks text selection and the browser's own drag of an image or link inside the item (`dragstart`); `user-select: none` on the handle also keeps a long press from selecting its text.
+
+### Several lists
+
+With `from: ['todo', 'done']`, items move between the lists. Mark each list's container with `data-list` and its key, so a pointer drop on an empty list lands in it:
+
+```jsx live
+import { Collection, sortable } from 'sygnal'
+
+function Card({ state }) {
+  return (
+    <li className="card" data-id={state.id}>
+      <button type="button" className="grip" aria-label={`Move ${state.title}`}>⠿</button> {state.title}
+    </li>
+  )
+}
+
+function Board({ state }) {
+  return (
+    <div className="board">
+      <ul className="lane" data-list="todo" aria-label="To do"><Collection of={Card} from="todo" /></ul>
+      <ul className="lane" data-list="done" aria-label="Done"><Collection of={Card} from="done" /></ul>
+      <p role="status" aria-live="assertive">{state.sort.message}</p>
+    </div>
+  )
+}
+
+Board.initialState = { todo: [{ id: 'a', title: 'Draft' }, { id: 'b', title: 'Review' }], done: [] }
+Board.uses = { sort: sortable({ from: ['todo', 'done'], item: '.card', handle: '.grip' }) }
+```
+
+Give an empty list some height, so there is something to drop on:
+
+```css live
+.board { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; }
+.board [role="status"] { grid-column: 1 / -1; }
+.lane { min-height: 3rem; border: 1px dashed currentColor; }
+```
+
+`sort.DROPPED`'s `fromList` and `list` say where the item came from and went. Over an item of the other list, the pointer's half of it decides: the upper half (the left half with `axis: 'x'`) lands before it, the lower half after it, so the end of a list is reached over its last item. Within the item's own list it lands before the hovered item when moving up and after it when moving down.
+
+### Accessibility
+
+- Make the handle a `<button type="button">` with a name (``aria-label={`Reorder ${title}`}``), or, without a handle, give the item `tabIndex={0}` and an `aria-label`.
+- Point the handles' `aria-describedby` at an instructions element with `id={state.sort.helpId}` (pass `helpId` to the items through context).
+- Render `state.sort.message` in a live region (`role="status"` / `aria-live`): it is how screen-reader users hear where the item is.
+- `sygnal-check` reports a handle that can't take focus or has no name, and a host without a live region ([SYG724](https://sygnal.js.org/reference/errors/#syg724)).
+
+### Nested sortables
+
+A sortable inside a sortable's item (sorted lanes, each with sorted cards) works: a press or key belongs to the innermost sortable whose items contain it, and a host's own root element is never one of its items. A host's items are the item elements below its root that aren't inside another of them, so the ids may repeat between the levels (lane `1` holding card `1`): the item under the pointer, the one a key is on and the handle that gets focus are always the host's own. Give each level its own handle.
+
+### Filtered and sorted lists
+
+`sortable` moves entries of the array in the state: the arrow keys swap the item with its neighbour in the array, the positions it announces count the array, and a pointer drop lands next to the entry it is dropped on. Render the list in that order. Under a Collection's `sort`, a move changes nothing you can see (the Collection sorts it back); under a `filter`, a keyboard step can pass entries that are hidden, and the positions count them. For a list that can be reordered, sort the array itself (once, for a starting order) instead of the Collection, and hide the handles while a filter hides entries. In development, [SYG435](https://sygnal.js.org/reference/errors/#syg435) warns when a list's items are shown in another order than the array's, or with entries hidden between them.
+
+### Undo and persist
+
+With the [`undo`](./undo.md) behavior on the same host, a drag is one undo step: `uses = { sort: sortable({ from: 'tasks' }), history: undo({ key: 'tasks' }) }` records the order from before the drag when the item is dropped, and a cancelled drag records nothing. The live keyboard moves aren't steps of their own, and the order of the two in `uses` doesn't matter.
+
+An action during a drag that changes the list too (an item added) is recorded with the drag so far, so the order from before the drag stays reachable; undo during a drag steps back over the drag so far, and redo during a drag records the order from before it (never a half-moved one). A drag cancelled after something else changed the list leaves the item where it is; if the order then differs from the one before the drag, that is one step, and nothing stays pending. With `track` naming none of `sort`'s actions, drags aren't recorded at all. `coalesceMs` joins quick drops only when `coalesce` names one of `sort`'s actions (`coalesce: ['sort.DROPPED']`).
+
+With several lists, record them together, so an undo after a move between lists puts both back:
+
+```jsx
+import { sortable, undo } from 'sygnal'
+
+Board.uses = {
+  sort: sortable({ from: ['todo', 'done'], item: '.card', handle: '.grip' }),
+  history: undo({ key: ['todo', 'done'] }),
+}
+```
+
+Each key is compared on its own, so a drag that moves an item to the other list and back, then drops it, records nothing. An undo restores only the keys the state had when the step was recorded (a key that was missing then is removed, not set to `undefined`); `key: []` throws.
+
+[`persist()`](./persistence.md) never saves or restores the root component's `state.sort` (it is UI state). A sortable on a sub-component or a Collection item keeps its slice in the data around it (`state.lanes[0].sort`), so a root `persist()` saves it with that data. Drag state that comes back this way, from another tab, or into a host made again (HMR) doesn't resume a drag: it is reset when the host starts or at the next press or key. Restored or synced drag state leaves the data as it is (only the drag that moved the item, in this page, knows its own lists: another tab's drag never moves anything here); a drag of this page (a host made again, a second host of the same slice) is cancelled by the rules above, so its lists come back when nothing else changed them.
+
+### Testing
+
+Keyboard moves are plain key events on the handle:
+
+```jsx
+import { renderComponent } from 'sygnal'
+import TaskList from './TaskList.jsx'
+
+it('moves a task down with the keyboard', async () => {
+  const t = renderComponent(TaskList)
+  await t.ready()
+  const key = (id, key) => t.simulateEvent('.grip', 'keydown', { key, within: `.task[data-id="${id}"]` })
+  key(2, ' ')
+  key(2, 'ArrowDown')
+  key(2, 'Enter')
+  await t.next((s) => s.sort.dragging === null)
+  expect(t.state.tasks.map((task) => task.id)).toEqual([1, 3, 2])
+  expect(t.actions.find((a) => a.type === 'sort.DROPPED').data).toMatchObject({ id: '2', index: 2, fromIndex: 1 })
+})
+```
+
+`t.commands('ELEMENT')` lists the focus commands; with `dom: 'real'` they run, and `document.activeElement` is the moved item's handle. Pointer drags are best tested in a real browser: a `pointerdown` on a handle, then `pointermove` / `pointerup` with `clientX` / `clientY` (the behavior finds the item under the pointer with `document.elementFromPoint`).
+
+### Diagnostics
+
+With `sygnal/diagnostics` loaded (the Vite plugin loads it in development): [SYG145](https://sygnal.js.org/reference/errors/#syg145) an item element without the id attribute, [SYG146](https://sygnal.js.org/reference/errors/#syg146) an `item` or `handle` selector that matches nothing at the first interaction, [SYG147](https://sygnal.js.org/reference/errors/#syg147) a `from` key that isn't an array in the host's state, [SYG435](https://sygnal.js.org/reference/errors/#syg435) a list shown in another order than its array's (a Collection's `sort` or `filter`). `sygnal-check` knows `sortable`'s options (a typo is [SYG127](https://sygnal.js.org/reference/errors/#syg127)) and reports [SYG724](https://sygnal.js.org/reference/errors/#syg724).
+
+## HTML5 drag and drop: makeDragDriver
+
+The drag-and-drop driver handles native HTML5 drag events at the document level, bypassing component isolation, so drag interactions work across deeply nested, isolated components. Reach for it for files dropped from the desktop, drags between components that don't share a host, or native drag images; for reordering a list, `sortable` above also covers touch and keyboard.
+
+### Setup
+
+Create the driver with `makeDragDriver()` and pass it to `run()`:
+
+```javascript
+import { run, makeDragDriver } from 'sygnal'
+import RootComponent from './RootComponent.jsx'
+
+run(RootComponent, { DND: makeDragDriver() })
+```
+
+### Registering Drag Categories
+
+Register drag categories from your model, typically in `BOOTSTRAP`. Each category describes a set of draggable elements and/or drop zones identified by CSS selectors:
+
+```jsx
+RootComponent.model = {
+  BOOTSTRAP: {
+    DND: () => ({
+      configs: [
+        { category: 'task', draggable: '.task-card' },
+        { category: 'lane', dropZone: '.lane-drop-zone', accepts: 'task' },
+      ],
+    }),
+  },
+}
+```
+
+#### Registration Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `category` | `string` | Required. Name for this group of drag elements |
+| `draggable` | `string` | CSS selector for elements that can be dragged |
+| `dropZone` | `string` | CSS selector for elements that accept drops |
+| `accepts` | `string` | Only accept drops from this dragging category. Omit to accept any |
+| `dragImage` | `string` | CSS selector for a custom drag preview. Resolved via `.closest()` from the draggable element |
+
+A single category can have both `draggable` and `dropZone` — for example, sortable lists where items are both dragged and dropped onto:
+
+```javascript
+const laneSort = {
+  category:  'lane-sort',
+  draggable: '.lane-drag-handle',
+  dropZone:  '.lane-header',
+  accepts:   'lane-sort',
+  dragImage: '.lane',
+}
+```
+
+### Listening to Drag Events
+
+Use the `DND` source in intent. It supports the same shorthand pattern as the DOM source:
+
+```jsx
+RootComponent.intent = ({ DND }) => ({
+  DRAG_START: DND.dragstart('task'),   // = DND.select('task').events('dragstart')
+  DROP:       DND.drop('lane'),        // = DND.select('lane').events('drop')
+  DRAG_END:   DND.dragend('task'),     // = DND.select('task').events('dragend')
+})
+```
+
+#### Event Payloads
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `dragstart` | `{ element, dataset }` | The dragged element and its `data-*` attributes |
+| `dragend` | `null` | Fires when the drag ends (drop or cancel) |
+| `drop` | `{ dropZone, insertBefore }` | The drop zone element, and the sibling element at the cursor position (for ordering) |
+| `dragover` | `null` | Fires continuously while dragging over a valid drop zone. `preventDefault()` is called automatically |
+
+### Handling Drops
+
+The `drop` event provides the drop zone element and an `insertBefore` reference for ordering. Use `dataset` attributes on your elements to identify items:
+
+```jsx
+// In the view, put identifying data on elements
+<div className="task-card" data={{ taskId: state.id }}>
+  {state.title}
+</div>
+
+// In the model, use the drop payload to move items
+RootComponent.model = {
+  DROP: (state, { dropZone, insertBefore }) => {
+    if (!state.dragging) return ABORT
+    const toLaneId = dropZone.dataset.laneId
+    const insertBeforeTaskId = insertBefore?.dataset.taskId ?? null
+    // moveTask: your own helper that returns the new lanes array
+    const lanes = moveTask(state.lanes, state.dragging.taskId, toLaneId, insertBeforeTaskId)
+    return { ...state, lanes, dragging: null }
+  },
+}
+```
+
+### Visual Feedback with Context
+
+Use context to communicate drag state down to child components for styling:
+
+```jsx
+RootComponent.context = {
+  draggingTaskId: state => state.dragging?.taskId ?? null,
+}
+
+// In a child component's view
+function TaskCard({ state, context }) {
+  const isDragging = context.draggingTaskId === state.id
+  return (
+    <div className={'task-card' + (isDragging ? ' dragging' : '')} data={{ taskId: state.id }}>
+      {state.title}
+    </div>
+  )
+}
+```
+
+### Complete Example
+
+See the [Kanban board example](https://github.com/tpresley/sygnal/tree/main/examples/kanban) for a full working implementation with task drag-and-drop between lanes, lane reordering with custom drag images, and visual drag feedback.

package/dist/guide/element-commands.md

@@ -0,0 +1,306 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Element Commands
+
+Some things the browser does are not state you render: which element has the focus, where the page is scrolled to, whether a `<dialog>` is open as a modal, whether a popover is showing. You change them by calling a method on the element (`input.focus()`, `dialog.showModal()`). In Sygnal, a model entry asks for that call with an **element command** on the built-in `ELEMENT` sink:
+
+```jsx
+Signup.model = {
+  SUBMIT: {
+    STATE: (state) => ({ ...state, errors: validate(state) }),
+    ELEMENT: (state) => (validate(state).email ? { focus: '.email' } : ABORT),
+  },
+  OPEN_HELP: { ELEMENT: { showModal: '.help' } },
+}
+```
+
+`ELEMENT` is built in: there is no driver to register, and it works in every component. The target is a CSS selector (`{ focus: '.email' }`), looked up in the view of the component that sent the command (see [Which element](#which-element)). A [control](https://sygnal.js.org/guide/controls/) works as a target too.
+
+## The command object
+
+A command is an object whose **first key is the method** and whose value is the target. The other keys are the method's options:
+
+```jsx
+Form.model = {
+  EDIT_EMAIL:   { ELEMENT: { focus: '.email' } },                          // email.focus({})
+  QUIET_FOCUS:  { ELEMENT: { focus: '.email', preventScroll: true } },     // email.focus({ preventScroll: true })
+  SHOW_LAST:    { ELEMENT: { scrollIntoView: '.row', block: 'nearest' } }, // row.scrollIntoView({ block: 'nearest' })
+  CLOSE_HELP:   { ELEMENT: { close: '.help', returnValue: 'done' } },      // dialog.close('done')
+}
+```
+
+The documented methods:
+
+| Method | Options | Element |
+|---|---|---|
+| `focus` | `preventScroll`, `focusVisible` | any focusable element |
+| `blur` | | any element |
+| `select` | | `<input>`, `<textarea>`: selects the text |
+| `click` | | any element (a programmatic click, e.g. to open a file input's picker) |
+| `scrollIntoView` | `block`, `inline`, `behavior` | any element |
+| `showModal` | | `<dialog>` |
+| `show` | | `<dialog>` (non-modal) |
+| `close` | `returnValue` (passed as the argument) | `<dialog>` |
+| `showPopover` | | an element with a `popover` attribute |
+| `hidePopover` | | an element with a `popover` attribute |
+| `togglePopover` | `force` | an element with a `popover` attribute |
+
+The options are passed to the method as one object, except for `close`, which gets `returnValue` as its argument. A popover is an element rendered with `attrs: { popover: 'auto' }` (or `'manual'`); its `toggle` event reaches intent as `DOM.toggle('.tip')`, with `newState` `'open'` or `'closed'`.
+
+The browser's declarative forms need no model: `<button popovertarget="tip">` toggles a popover and `<button commandfor="dlg" command="show-modal">` opens a dialog. JSX writes these as attributes, as it does `popovertargetaction`, `closedby`, `interestfor` and `anchor`, and an `aria-*` boolean as `"true"` / `"false"`.
+
+The value of the `ELEMENT` entry is a command, or a reducer that returns one: `(state, data) => command`. Return `ABORT` to send nothing. An **array** sends several commands, in order:
+
+```jsx
+Search.model = {
+  // put the cursor in the search box and select what is in it
+  EDIT_QUERY: { ELEMENT: [{ focus: '.query' }, { select: '.query' }] },
+}
+```
+
+Sygnal runs any method the element has, so other methods work too (`{ play: '.video' }`, `{ showPicker: '.date' }`, `{ requestSubmit: '.checkout' }`). The eleven above are the ones the types know; for TypeScript, add others to the `ElementCommandRegistry` interface:
+
+```ts
+// sygnal-commands.d.ts
+import 'sygnal'
+
+declare module 'sygnal' {
+  interface ElementCommandRegistry { play: {}; showPicker: {} }
+}
+```
+
+Methods that change the DOM Sygnal renders (`remove`, `append`, `setAttribute` and the like) are reported as [SYG641](https://sygnal.js.org/reference/errors/#syg641): the next render would undo them or trip over them. Change the state instead.
+
+## Which element
+
+The target is looked up in the view of the **component instance that sent the command**, the same scope its intent's `DOM` has. An element inside a child component is isolated from its parent, and each item of a [Collection](https://sygnal.js.org/guide/collections/) reaches only its own elements. To focus or scroll something a child renders, send the command from the child's own model. If more than one element matches, the first one gets the command.
+
+### Focusing inside children: `focusWithin`
+
+To focus an element a child renders (a field of a child form, the input of a Collection item the same action adds), use `focusWithin(selector)` as the target. It looks for `selector` anywhere under the sender's root element, children included, and focuses the first match with the command's options:
+
+```jsx live
+import { Collection, focusWithin } from 'sygnal'
+
+function Row({ state }) {
+  return (
+    <li data-id={state.id}>
+      <input className="title" aria-label="Title" value={state.title} />
+    </li>
+  )
+}
+Row.intent = ({ DOM }) => ({ TITLE: DOM.input('.title').value() })
+Row.model = { TITLE: (state, title) => ({ ...state, title }) }
+
+export function Checklist({ state }) {
+  return (
+    <div>
+      <button className="add">Add item</button>
+      <ul><Collection of={Row} from="rows" /></ul>
+    </div>
+  )
+}
+Checklist.initialState = { rows: [], next: 1 }
+Checklist.intent = ({ DOM }) => ({ ADD: DOM.click('.add') })
+Checklist.model = {
+  ADD: {
+    STATE: (state) => ({ ...state, rows: [...state.rows, { id: state.next, title: '' }], next: state.next + 1 }),
+    // the new row renders in the same patch, before the command runs
+    ELEMENT: (state) => ({ focus: focusWithin(`[data-id="${state.next}"] .title`) }),
+  },
+}
+```
+
+The reducer for `ELEMENT` sees the state before the action, so `state.next` is the new row's id. Prefer the child's own model when the child decides; `focusWithin` is for a parent that does (adding a row, submitting a form whose fields are child components). If nothing matches, nothing happens; `renderComponent()` reports [SYG640](https://sygnal.js.org/reference/errors/#syg640) when nothing in the view, children included, matches.
+
+## When it runs
+
+A command runs once the render that its action may cause is on the page, so it reaches an element that the same action renders (the error message under a field, a new row, a dialog that a state flag adds):
+
+- after the action, the command waits for the next patch of the DOM at which its target exists, and runs right after it;
+- if the action changes nothing that renders, it runs at the first check, 16 ms later;
+- while the target is missing, it keeps checking every 16 ms for about 1 s, then gives up ([SYG640](https://sygnal.js.org/reference/errors/#syg640) in development);
+- the pending commands of a component that is removed are dropped.
+
+During server rendering (`renderToString`) nothing runs: there are no elements to call.
+
+## Recipes
+
+### Focus the first invalid field
+
+After a failed submit, move the focus to the first field with an error. The `ELEMENT` entry runs after the errors have rendered, so it can focus a field the same action marked invalid:
+
+```jsx live
+import { ABORT } from 'sygnal'
+
+const validate = ({ name, email }) => ({
+  ...(name.trim() ? {} : { name: 'Enter your name' }),
+  ...(email.includes('@') ? {} : { email: 'Enter an email address' }),
+})
+
+export function Signup({ state }) {
+  return (
+    <form>
+      <label>Name <input className="name" value={state.name} /></label>
+      {state.errors.name && <p className="error">{state.errors.name}</p>}
+      <label>Email <input className="email" type="email" value={state.email} /></label>
+      {state.errors.email && <p className="error">{state.errors.email}</p>}
+      <button className="submit" type="button">Sign up</button>
+    </form>
+  )
+}
+
+Signup.initialState = { name: '', email: '', errors: {} }
+
+Signup.intent = ({ DOM }) => ({
+  NAME: DOM.input('.name').value(),
+  EMAIL: DOM.input('.email').value(),
+  SUBMIT: DOM.click('.submit'),
+})
+
+Signup.model = {
+  NAME: (state, name) => ({ ...state, name }),
+  EMAIL: (state, email) => ({ ...state, email }),
+  SUBMIT: {
+    STATE: (state) => ({ ...state, errors: validate(state) }),
+    // runs after the errors have rendered; the first invalid field gets the focus
+    ELEMENT: (state) => {
+      const errors = validate(state)
+      if (errors.name) return { focus: '.name' }
+      if (errors.email) return { focus: '.email' }
+      return ABORT
+    },
+  },
+}
+```
+
+### A native dialog
+
+`showModal` opens a `<dialog>` as a modal: the browser traps the focus inside it, dims the page and closes it on Escape. Its `close` event tells the component that it closed, whichever way it did:
+
+```jsx live
+export function Help({ state }) {
+  return (
+    <div>
+      <button className="open-help">Keyboard shortcuts</button>
+      <dialog className="help">
+        <h2>Keyboard shortcuts</h2>
+        <p>Press N for a new card.</p>
+        <button className="close-help">Close</button>
+      </dialog>
+      <p className="status">{state.status}</p>
+    </div>
+  )
+}
+
+Help.initialState = { status: 'Help is closed' }
+
+Help.intent = ({ DOM }) => ({
+  OPEN_HELP: DOM.click('.open-help'),
+  CLOSE_HELP: DOM.click('.close-help'),
+  // close doesn't bubble; Sygnal listens on the dialog itself (Escape closes it too)
+  HELP_CLOSED: DOM.close('.help'),
+})
+
+Help.model = {
+  OPEN_HELP: {
+    STATE: (state) => ({ ...state, status: 'Help is open' }),
+    ELEMENT: { showModal: '.help' },
+  },
+  CLOSE_HELP: { ELEMENT: { close: '.help', returnValue: 'done' } },
+  HELP_CLOSED: (state) => ({ ...state, status: 'Help is closed' }),
+}
+```
+
+The dialog's open state belongs to the browser here: the component keeps only a status it shows. `DOM.close('.help').map(e => e.target.returnValue)` gives the `returnValue` the dialog was closed with.
+
+### Scroll a new row into view
+
+A Collection item reaches only its own elements, so a new row scrolls itself into view, from its `BOOTSTRAP` (which runs once, when the item is created):
+
+```jsx live
+import { ABORT, Collection } from 'sygnal'
+
+function TaskRow({ state }) {
+  return <li className="row">{state.text}</li>
+}
+
+TaskRow.model = {
+  // only rows added by ADD scroll; the ones there at the start don't
+  BOOTSTRAP: { ELEMENT: (state) => (state.added ? { scrollIntoView: '.row', block: 'nearest' } : ABORT) },
+}
+
+export function TaskList() {
+  return (
+    <div className="task-list">
+      <button className="add-task">Add a task</button>
+      <ul>
+        <Collection of={TaskRow} from="tasks" />
+      </ul>
+    </div>
+  )
+}
+
+TaskList.initialState = { tasks: [{ id: 1, text: 'Water the plants' }] }
+
+TaskList.intent = ({ DOM }) => ({ ADD: DOM.click('.add-task') })
+
+TaskList.model = {
+  ADD: (state) => {
+    const id = state.tasks.length + 1
+    return { ...state, tasks: [...state.tasks, { id, text: `Task ${id}`, added: true }] }
+  },
+}
+```
+
+The list here scrolls inside a box of its own, so a new row has somewhere to scroll to:
+
+```css live
+.task-list ul { max-height: 6.5em; overflow-y: auto; margin-top: 0.5rem; }
+```
+
+In a [`<VirtualCollection>`](./virtual-collections.md#jumping-to-a-row) most rows aren't rendered, so the list jumps instead: its container takes `{ scrollToIndex: '.rows', index }` and `{ scrollToId: '.rows', id }`, sent by the component that renders it.
+
+## Testing
+
+[`renderComponent`](https://sygnal.js.org/integration/testing/) records every command the rendered tree sends. `t.commands('ELEMENT')` lists them in order, one entry per command (arrays flattened), as sent. With the mock DOM (the default) they are only recorded; with `dom: 'real'` they also run, so the test can check the focus or the dialog:
+
+```jsx
+// @vitest-environment jsdom
+import { it, expect, afterEach } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { Signup } from './Signup.jsx'
+
+let t
+afterEach(() => t?.dispose())
+
+it('asks for the focus on the first invalid field', async () => {
+  t = renderComponent(Signup)
+  await t.ready()
+  t.simulateEvent('.submit', 'click')
+  await t.next(s => !!s.errors.name)
+  await t.settle()
+  expect(t.commands('ELEMENT')).toEqual([{ focus: '.name' }])
+})
+
+it('moves the focus there (real DOM)', async () => {
+  t = renderComponent(Signup, { dom: 'real' })
+  await t.ready()
+  t.simulateEvent('.submit', 'click')
+  await t.next(s => !!s.errors.name)
+  await t.settle()
+  expect(document.activeElement).toBe(t.query('.name'))
+})
+```
+
+- The commands are recorded as the model sent them, so the test compares them with the same objects: `{ focus: '.name' }`.
+- jsdom has no `showModal`, `show`, `close`, popover methods or `scrollIntoView`. With `dom: 'real'`, `renderComponent` adds stand-ins: a dialog's `open` flips and `close` fires its `close` event, a popover's `toggle` event fires, and `scrollIntoView` does nothing. Check real scrolling and focus trapping in a browser.
+- The mock DOM reports SYG640 and SYG641 too, so `t.expectNoDiagnostics()` catches a command that missed its target.
+
+## Diagnostics
+
+| Code | When |
+|---|---|
+| [SYG640](https://sygnal.js.org/reference/errors/#syg640) (warning) | Nothing in the sending instance's view matched the target within about 1 s, or the command has no target. `sygnal-check` reports a literal command whose class the view never renders |
+| [SYG641](https://sygnal.js.org/reference/errors/#syg641) (error) | The element has no method of that name (a typo such as `fokus`, `showModal` on a `<div>`; for a [widget control](https://sygnal.js.org/guide/controls/#widget-controls-for-library-authors), its spec has no such command either), the value isn't a command object, or the method changes the DOM Sygnal renders. `sygnal-check` reports a misspelled documented method or spec command |
+
+Both come from the development checks (`sygnal/diagnostics`, loaded by the Vite plugin in dev) and from `sygnal-check`. In production a command that can't run does nothing.