sygnal 5.3.7 → 6.0.0

package/dist/guide/forms.md

@@ -0,0 +1,250 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Forms
+
+A form with validation is one [behavior](./behaviors.md): `form(schema, options)` in the component's `uses`. It keeps the values, errors and touched fields in `state.form`, validates with any [Standard Schema](https://standardschema.dev) validator (zod, valibot, arktype, or your own object), and handles the submit. Sygnal has no validator dependency.
+
+This page is the recipe and what you need around it. The [Forms reference](./forms-reference.md) has the full slice and action tables, async checks (is this email taken?), two forms in one component, rows as components, resetting, the helpers for a form without the behavior, and `processForm()`. Controlled inputs, `uid()` and `autoFocus` are on [Inputs, Labels and Focus](./inputs.md).
+
+## The recipe
+
+In this demo, a stand-in server answers the request: `taken@example.com` is already registered, any other address gets an account.
+
+```js live-server
+let nextId = 1
+
+export default {
+  'POST /api/signup': ({ json }) => json.email === 'taken@example.com'
+    ? { status: 422, json: { errors: { email: 'Already registered' } } }
+    : { status: 201, json: { id: nextId++ } },
+}
+```
+
+Validation, a list of rows the user adds and removes, the submit to the server, the pending button, and the server's errors:
+
+```jsx live
+import { form } from 'sygnal'
+import { z } from 'zod'
+
+const signupSchema = z.object({
+  name: z.string().trim().min(1, 'Enter your name'),
+  email: z.string().trim().toLowerCase().email('Enter a valid email address'),
+  addresses: z.array(z.object({ city: z.string().trim().min(1, 'Enter a city') })).min(1, 'Add at least one address'),
+})
+
+function Signup({ state, uid }) {
+  const f = state.form.fields
+  const rows = state.form.values.addresses
+  return (
+    <form className="signup" noValidate>
+      <label for={uid('name')}>Name</label>
+      <input id={uid('name')} name="name" value={f.name.value} aria-invalid={f.name.invalid} aria-describedby={uid('name-error')} />
+      <p id={uid('name-error')}>{f.name.error}</p>
+
+      <label for={uid('email')}>Email</label>
+      <input id={uid('email')} name="email" type="email" value={f.email.value} aria-invalid={f.email.invalid} aria-describedby={uid('email-error')} />
+      <p id={uid('email-error')}>{f.email.error}</p>
+
+      {rows.map((row, i) => {
+        const city = f[`addresses.${row.id}.city`]
+        return (
+          <fieldset className="address">
+            <legend>Address {i + 1}</legend>
+            <label for={uid(`city-${row.id}`)}>City</label>
+            <input id={uid(`city-${row.id}`)} name={city.name} value={city.value} aria-invalid={city.invalid} aria-describedby={uid(`city-${row.id}-error`)} />
+            <p id={uid(`city-${row.id}-error`)}>{city.error}</p>
+            <button type="button" className="remove" data-id={row.id} disabled={rows.length === 1}>Remove</button>
+          </fieldset>
+        )
+      })}
+      <p>{f.addresses.error}</p>
+      <button type="button" className="add">Add address</button>
+
+      <p role="alert">{state.form.error}</p>
+      <button type="submit" disabled={state.form.submitting}>{state.form.submitting ? 'Signing up…' : 'Sign up'}</button>
+      <p className="done">{state.accountId ? `Account ${state.accountId} created.` : ''}</p>
+    </form>
+  )
+}
+
+Signup.initialState = { accountId: null }
+
+Signup.uses = {
+  form: form(signupSchema, { values: { name: '', email: '', addresses: [{ id: 1, city: '' }] }, submit: 'SIGN_UP' }),
+}
+
+Signup.intent = ({ DOM }) => ({
+  'form.ADD': DOM.click('.add').mapTo({ field: 'addresses', value: { city: '' } }),
+  'form.REMOVE': DOM.click('.remove').map((e) => ({ field: 'addresses', id: e.target.dataset.id })),
+})
+
+Signup.model = {
+  SIGN_UP: { HTTP: (state, values) => ({ url: '/api/signup', method: 'POST', json: values, ok: 'form.DONE', error: 'form.ERRORS' }) },
+  'form.DONE': (state, account) => ({ ...state, accountId: account.id }),
+}
+```
+
+`main.js` runs it with `run(Signup, { HTTP: makeFetchDriver() })`. There is no intent per field: the two intent entries are the row buttons.
+
+## What the form does
+
+- **Fields are matched by `name`.** The behavior listens for `input`, `focusout` and `submit` on the form element (option `form`, default `'form'`), so every field inside it whose `name` is a path in `values` is controlled: `value={f.email.value}` stays in sync as the user types. Array rows are named by their `id`: `addresses.7.city`.
+- **`state.form.fields[name]`** is what the view needs for each field: `value`, `error` (the message to show, `''` for none), `invalid` (`!!error`, for `aria-invalid`), `touched`, `dirty` and `pending` (an [async check](./forms-reference.md#async-checks) is running), plus `name`.
+- **When errors show**: every change is validated, but a field's schema error shows once the field has lost focus (`show: 'blur'`, the default), or while typing (`show: 'input'`), or only after a submit (`show: 'submit'`). After the first submit every error shows, and each follows the typing. Server errors show at once.
+- **An invalid submit** shows every error, focuses the first invalid field in page order (rows included) and sends nothing.
+- **A valid submit** dispatches the `submit` action (`SIGN_UP`) with the schema's output: the trimmed, transformed values (`email` lower-cased here; the rows without their `id`, because `z.object` strips keys it doesn't declare), not the raw ones. Your model entry for it sends the request, with `ok: 'form.DONE'` and `error: 'form.ERRORS'` as its reply actions.
+- **Pending**: when the submit entry sends a request (an `HTTP` sink), `state.form.submitting` is `true` from the valid submit until `form.DONE` or `form.ERRORS` arrives. Use it for the button's text and `disabled`. A second submit meanwhile is dropped, so a double click sends once.
+- **`form.DONE`** marks the submit saved: `submitting` turns off, `submitted` on, and the saved values become the new start values (`dirty` is `false` again). A host model entry with the same name runs after the form's and gets the reply body: `'form.DONE': (state, account) => …` above shows the new account's id.
+- **Labels and errors**: each field has a label and its error text is linked with `aria-describedby`, with ids from [`uid()`](./inputs.md#labels-and-ids-uid) (a row's ids include its `id`, so they stay unique), so the form passes the [accessibility checks](./accessibility.md). `aria-invalid={f.email.invalid}` renders `"true"` or `"false"`.
+
+Reserve the height of the error lines in your CSS (`min-height`). A field's error appears when it loses focus, which happens on the mouse*down* of a click elsewhere: if the new line pushes the button down before the mouse*up*, the click is lost.
+
+```css live
+.signup p { min-height: 1.5em; }
+```
+
+## Submit without a request
+
+A submit that sends nothing (a wizard step's "Next", a dialog's "OK") is an entry with `STATE`, `PARENT` or `EVENTS` and no `HTTP`. It is done at once: `submitting` stays `false`, `submitted` turns on, and you send no `form.DONE`.
+
+```jsx
+AccountStep.uses = { form: form(accountSchema, { values: { email: '', password: '' }, submit: 'NEXT' }) }
+AccountStep.model = {
+  NEXT: { PARENT: (state, values) => ({ type: 'NEXT', email: values.email }) },
+}
+```
+
+**Wizards**: each step is a child with a `state` prop (`<AccountStep state="account" />`); the parent switches steps on its `PARENT` message. The step's `form` slice lives in the parent's state, so after "Back" the step mounts with its values kept (and `submitting` off, even if it unmounted mid-request). Make "Next" a `type="submit"` button inside the `<form>`; in a test, simulate `'submit'` on the form (the mock DOM doesn't turn a click into a submit).
+
+## Start empty on each visit
+
+The values live in state, so they survive a visit (a [Switchable](https://sygnal.js.org/guide/switchable/) page shares its parent's state and stays alive while hidden). For a form that starts empty each time it is shown, set `resetOnShow: true`; a start value from state goes in a `values` function:
+
+```jsx
+NewExpensePage.uses = {
+  form: form(expenseSchema, {
+    values: (state) => ({ ...EMPTY, category: state.settings.defaultCategory }),
+    submit: 'SAVE',
+    resetOnShow: true,
+  }),
+}
+```
+
+Typing while it is shown is kept; a wizard step leaves it off. [The rule](./forms-reference.md#saving-and-resetting).
+
+## Server errors and failed submits
+
+The server has the last word. With `error: 'form.ERRORS'` on the request, a failed reply goes to the form, which turns `submitting` off, puts the reply's errors on their fields, shows them at once and focuses the first one in page order. A `422` reply's body can be either shape:
+
+```json
+{ "errors": { "password": "Too common", "addresses.1.city": "Unknown city" } }
+```
+
+```json
+{ "errors": [{ "path": ["addresses", 0, "city"], "message": "Unknown city" }, { "path": ["email"], "message": "Already registered" }] }
+```
+
+- A map from field name to a message (or a list of messages: the first shows), or a list of `{ path, message }` issues. In an issue path, a number is the row's position in the array the server got, and it becomes that row's `id` (`addresses.0.city` names the first row's city, whatever its `id`). In a map, a name is a field name, so rows go by `id`.
+- `form.ERRORS` also accepts the map or the list itself (`t.simulateAction('form.ERRORS', { email: 'Taken' })`).
+- A message for a name that isn't a field (`{ "message": "Down for maintenance" }`) becomes the form-level `state.form.error`. A reply with no message at all (a `500` with an empty body, a network error) shows `"Request failed (500)"` there, or `"Request failed"` without a status. The recipe renders it in `<p role="alert">`.
+- Editing a field clears its server error, and the form-level one.
+
+For your own text on failures other than a `422`, add a host entry: it runs after the form's and gets the [error reply](./http.md) `{ error, status, body, request }` (`status` is `undefined` for a network error):
+
+```js
+Checkout.model = {
+  'form.SUBMIT': (state) => ({ ...state, failed: false }),
+  'form.ERRORS': (state, reply) => ({ ...state, failed: reply.status !== 422 }),
+}
+// view: <p role="alert">{state.failed ? 'Could not place the order. Try again.' : ''}</p>
+```
+
+## Field arrays
+
+Rows of an array of objects are named by their `id`, not their position, so a row's errors, touched state and focus stay with it when another row is removed. Render the rows inline with `.map()`, as in the recipe:
+
+- **Names**: `name={f[`addresses.${row.id}.city`].name}`. Each row needs an `id` in the start values ([SYG236](https://sygnal.js.org/reference/errors/#syg236)).
+- **Add**: `form.ADD` with `{ field, value }` appends `{ id, ...value }` with the next free id: `'form.ADD': DOM.click('.add').mapTo({ field: 'addresses', value: { city: '' } })`.
+- **Remove**: `form.REMOVE` with `{ field, id }` removes that row (the id can be the string from `data-id`): `'form.REMOVE': DOM.click('.remove').map((e) => ({ field: 'addresses', id: e.target.dataset.id }))`.
+- **Numbering**: the row's position is the map's index (`Address {i + 1}`); it renumbers after a remove, while the row's `id`, name and ids stay.
+- **The array itself is a field** (`f.addresses`), for an array-level error such as "Add at least one address" (`z.array(…).min(1, …)`).
+
+No child component is needed for a row. When a row is big enough to be a component of its own, see [rows as components](./forms-reference.md#rows-as-components).
+
+## Field types
+
+What `state.form.values[name]` gets from each kind of field, and how to bind it:
+
+| Field | Value | Bind |
+|---|---|---|
+| `<input>` (text, email, password, search, tel, url), `<textarea>` | The text | `value={f.email.value}` |
+| `<input type="number">`, `range`, `date`, `time` | The text as the browser gives it (`'42'`, `'2026-10-05'`; `''` when empty) | `value={f.age.value}`; convert in the schema: `z.coerce.number()`, `v.pipe(v.string(), v.transform(Number), v.number())` |
+| `<input type="radio">` (same `name`) | The checked radio's `value` | `checked={f.size.value === 'm'}` |
+| `<input type="checkbox">` on a boolean | `checked` | `checked={f.agree.value}` |
+| Checkboxes sharing a `name` on an array | The array of the checked boxes' `value`s (checking adds it, unchecking removes it) | `values: { tags: [] }`, `<input type="checkbox" name="tags" value="news" checked={f.tags.value.includes('news')} />` |
+| `<select>` | The selected option's `value` | `value={f.country.value}` |
+| `<select multiple>` | The array of selected `value`s | `selected={f.colors.value.includes('red')}` on each `<option>` |
+| A form-associated custom element (`<wa-input>`, `<wa-select>`) | Its `value` | `value={f.nick.value}` |
+| A form-associated custom checkbox or switch (`<wa-checkbox>`, `<wa-switch>`: a hyphenated tag with a boolean `checked`) | `checked` (as a group on an array, like checkboxes) | `checked={f.news.value}` |
+| `<input type="file">` | Not handled: the form ignores it | Leave `value` unbound; read `e.target.files` in your own intent and keep the files out of `values` |
+
+## Options
+
+| Option | |
+|---|---|
+| `values` | The start values (or a function of the host's state). Field names are paths in it: `email`, `address.city`, and `addresses.7.city` for the row with `id` 7 |
+| `submit` | The host action a valid submit dispatches with the schema's output ([SYG234](https://sygnal.js.org/reference/errors/#syg234) when the model has no such entry). An entry with an `HTTP` sink keeps the submit pending until its reply; any other is done at once ([submit without a request](#submit-without-a-request)) |
+| `show` | `'blur'` (default), `'input'` or `'submit'`: when a schema error shows |
+| `form` | The form element's selector, default `'form'`. Give each form its own when a component has two: `form: '.login'` and `form: '.news'` ([two forms](./forms-reference.md#two-forms-in-one-component), [SYG237](https://sygnal.js.org/reference/errors/#syg237)) |
+| `check` | [Async checks](./forms-reference.md#async-checks) by field name |
+| `http` | The driver sink of the requests, default `'HTTP'`: the checks' requests go to it, and a submit entry with this sink waits for its reply |
+| `resetOnShow` | `true`: start over each time the form is shown ([start empty on each visit](#start-empty-on-each-visit)) |
+
+The form's actions are named after the `uses` key (`form.ADD` for `uses = { form: … }`): `form.CHANGE`, `form.BLUR`, `form.SUBMIT`, `form.ADD`, `form.REMOVE`, `form.ERRORS`, `form.DONE` and `form.RESET` ([the actions](./forms-reference.md#the-actions)). A host model entry with one of those names runs after the form's, on the full state; trigger one from elsewhere with an intent action of that name, or `t.simulateAction('form.RESET')` in a test. Don't name `submit` after one ([SYG234](https://sygnal.js.org/reference/errors/#syg234)).
+
+## Testing
+
+Simulate events on the fields by `name`, answer the requests, and read `t.state.form`:
+
+```jsx
+import { renderComponent } from 'sygnal'
+import { it, expect } from 'vitest'
+import Signup from './Signup.jsx'
+
+it('validates, adds a row, posts the cleaned values and shows the server errors', async () => {
+  const t = renderComponent(Signup, { strict: true })
+  await t.ready()
+  t.simulateEvent('[name="email"]', 'input', { value: 'nope' })
+  t.simulateEvent('[name="email"]', 'focusout')
+  await t.settle()
+  expect(t.state.form.fields.email.error).toBe('Enter a valid email address')
+
+  t.simulateEvent('[name="name"]', 'input', { value: ' Ada ' })
+  t.simulateEvent('[name="email"]', 'input', { value: 'Ada@Example.com' })
+  t.simulateEvent('[name="addresses.1.city"]', 'input', { value: 'London' })
+  t.simulateEvent('.add', 'click')
+  t.simulateEvent('[name="addresses.2.city"]', 'input', { value: 'Paris' })
+  t.simulateEvent('.signup', 'submit')
+  await t.settle()
+  expect(t.state.form.submitting).toBe(true)
+  expect(t.requests('HTTP').at(-1)).toMatchObject({ url: '/api/signup', json: { name: 'Ada', email: 'ada@example.com', addresses: [{ city: 'London' }, { city: 'Paris' }] } })
+
+  await t.fail('HTTP', { status: 422, body: { errors: [{ path: ['addresses', 1, 'city'], message: 'Unknown city' }] } })
+  expect(t.state.form.fields['addresses.2.city'].error).toBe('Unknown city')
+  expect(t.state.form.submitting).toBe(false)
+  t.expectNoDiagnostics()
+})
+```
+
+- `simulateEvent` takes a CSS selector (`'[name="email"]'`, `'.remove[data-id="2"]'`), never an element from `t.query()`.
+- `await t.respond('HTTP', body)` and `await t.fail('HTTP', { status, body })` answer the newest request the component has sent (check `t.requests('HTTP')` first) and resolve once the reply is reduced and rendered: read `t.state` right after them. `t.next(pred)` would wait for a further state and time out.
+- `t.state.form.fields[name]` is what the view shows; `t.query('[name="email"]').getAttribute('aria-invalid')` checks the markup.
+- The focus on a failed submit is an [element command](./element-commands.md): `t.commands('ELEMENT').at(-1).focus.within` is the selector of the invalid fields on the default mock DOM; with `renderComponent(Signup, { dom: 'real' })` the field is focused (`document.activeElement`).
+
+## More
+
+On the [Forms reference](./forms-reference.md):
+
+- [the slice](./forms-reference.md#the-slice) (`values`, `initial`, `errors`, `touched`, `server`, `submitCount`, `queued`, `validating`, `valid`, `dirty`…) and [the actions](./forms-reference.md#the-actions) with their data;
+- [any Standard Schema](./forms-reference.md#any-standard-schema): a hand-written schema, async schemas;
+- [async checks](./forms-reference.md#async-checks) on blur, [two forms in one component](./forms-reference.md#two-forms-in-one-component), [rows as components](./forms-reference.md#rows-as-components), [saving and resetting](./forms-reference.md#saving-and-resetting);
+- [the helpers](./forms-reference.md#without-the-behavior-the-helpers) for a form without the behavior, the [diagnostics](./forms-reference.md#diagnostics), and [`processForm()`](./forms-reference.md#processform) for a form without validation.

package/dist/guide/http.md

@@ -0,0 +1,299 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# HTTP
+
+For HTTP, use the built-in fetch driver instead of calling `fetch` in a component. Register it once in `main.js`:
+
+```javascript
+import { run, makeFetchDriver } from 'sygnal'
+import App from './App.jsx'
+
+run(App, { HTTP: makeFetchDriver() })
+```
+
+A model entry sends a request to the `HTTP` sink and names the actions that receive the reply: `ok` for a 2xx response, `error` for everything else. The intent has no line for the reply.
+
+In this demo, a stand-in server answers: quote 1 slowly, and quote 2 with a 404.
+
+```js live-server
+const quotes = { 1: { id: 1, text: 'Start where you are.' } }
+
+export default {
+  'GET /api/quotes/:id': ({ params }) => (quotes[params.id]
+    ? { json: quotes[params.id], delayMs: 1500 }
+    : { status: 404, json: { message: 'No such quote' }, delayMs: 400 }),
+}
+```
+
+```jsx live
+import { ABORT } from 'sygnal'
+
+function Quote({ state }) {
+  return (
+    <div className="quote">
+      <button className="pick" data={{ id: 1 }}>First</button>
+      <button className="pick" data={{ id: 2 }}>Second</button>
+      <button className="refresh">Refresh</button>
+      <p className="text">{state.status === 'loading' ? 'Loading…' : state.error || state.quote?.text}</p>
+    </div>
+  )
+}
+Quote.initialState = { id: null, status: 'idle', quote: null, error: '' }
+Quote.intent = ({ DOM }) => ({
+  SHOW:    DOM.click('.pick').data('id', Number),
+  REFRESH: DOM.click('.refresh'),
+})
+Quote.model = {
+  SHOW: {
+    STATE: (state, id) => ({ ...state, id, status: 'loading', error: '' }),
+    HTTP:  (state, id) => ({ url: `/api/quotes/${id}`, ok: 'LOADED', error: 'FAILED', latest: true }),  // id from data: state.id is still the old one here
+  },
+  REFRESH: {
+    STATE: (state) => (state.id === null ? ABORT : { ...state, status: 'loading', error: '' }),
+    HTTP:  (state) => (state.id === null ? ABORT : { url: `/api/quotes/${state.id}`, ok: 'LOADED', error: 'FAILED', latest: true }),
+  },
+  LOADED: (state, quote) => ({ ...state, status: 'done', quote }),     // the parsed body
+  FAILED: (state, { status }) => ({ ...state, status: 'error', error: status === 404 ? 'No such quote.' : 'Could not load the quote.' }),
+}
+```
+
+Click First, then Second before quote 1 arrives: with `latest: true` the first request is aborted (see [Only the Latest Response](#only-the-latest-response)), and the 404 goes to `FAILED`.
+
+- The **`ok` action** gets the parsed body: JSON when the response says so, otherwise text (see `parse` below).
+- The **`error` action** gets `{ error, status, body, request }`. For a non-2xx response, `status` and the parsed `body` are set and `error.message` reads like `'HTTP 404 Not Found: /api/quotes/9'`. For a network error, a body that doesn't parse, a timeout (`error.name === 'TimeoutError'`) or no `fetch`, `status` is `undefined`. `request` is the request as the model sent it.
+- The reply goes to **exactly the component instance that sent the request**. Two `<Quote>` components, or every item of a Collection, can use the same action names without seeing each other's replies, and need no request ids.
+- If the instance is removed (a Collection item deleted, a page left), its requests are aborted and nothing arrives.
+- A name with no model entry is reported as [SYG112](https://sygnal.js.org/reference/errors/#syg112), with the closest model key. A request with a `then` or `catch` key is not sent ([SYG610](https://sygnal.js.org/reference/errors/#syg610)): use `ok` and `error`.
+
+### Build the request from (state, data)
+
+Every sink of one action sees the state from **before** that action ([Model](https://sygnal.js.org/guide/model/#sinks-see-the-state-before-the-action)). In `SHOW` above, `STATE` sets `id`, but the `HTTP` sink still sees the previous `state.id`, so it builds the URL from `data`. `REFRESH` doesn't change `id`, so it can read it from `state`.
+
+## Only the Latest Response
+
+Responses arrive in the order the server answers, not the order the requests were sent. With `latest: true`, sending a request aborts this instance's earlier requests **with the same key** that are still in flight, and their replies never arrive. The abort happens when the newer request is sent: a reply that lands before that still arrives. For example, with a debounce in front of the request, an older reply that comes back while the user is still typing (the newer request isn't sent yet) is delivered, so a reducer that must ignore it needs its own check, such as comparing the reply with the current input. The key is the `ok` action (else the `error` action), or an explicit `key`. A search box needs no request ids and no stale checks. In this demo, a stand-in server searches a few book titles, taking most of a second:
+
+```js live-server
+const books = ['Dune', 'Dune Messiah', 'Children of Dune', 'Foundation', 'Solaris']
+
+export default {
+  'GET /api/search': ({ query }) => {
+    const q = query.q.toLowerCase()
+    const results = books.filter(b => b.toLowerCase().includes(q)).map(title => ({ title }))
+    return { json: { results }, delayMs: 900 }
+  },
+}
+```
+
+```jsx live
+import { ABORT, debounce } from 'sygnal'
+
+function Search({ state }) {
+  return <div><input className="q" aria-label="Search" value={state.query} /><p className="status">{state.status}</p><ul>{state.results.map(r => <li>{r.title}</li>)}</ul></div>
+}
+Search.initialState = { query: '', status: '', results: [] }
+Search.intent = ({ DOM }) => ({
+  TYPE:   DOM.input('.q').value(),
+  SEARCH: DOM.input('.q').value().compose(debounce(300)).filter(q => q !== ''),
+})
+Search.model = {
+  TYPE: {
+    STATE: (state, query) => (query === '' ? { ...state, query, status: '', results: [] } : { ...state, query }),
+    HTTP:  (state, query) => (query === '' ? { abort: 'RESULTS' } : ABORT),     // clearing cancels the request in flight
+  },
+  SEARCH: {
+    STATE: (state) => ({ ...state, status: 'Searching…' }),
+    HTTP:  (state, q) => ({ url: '/api/search', query: { q }, ok: 'RESULTS', error: 'FAILED', latest: true }),
+  },
+  RESULTS: (state, body) => ({ ...state, status: '', results: body.results }),
+  FAILED:  (state, { status }) => ({ ...state, status: status === 404 ? 'Not found.' : 'Search failed.', results: [] }),
+}
+```
+
+- **Cancel without sending**: `{ abort: 'RESULTS' }` aborts this instance's requests in flight whose key is `'RESULTS'`; `{ abort: true, key: 'search' }` does the same for an explicit key. Nothing is delivered for a cancelled request.
+- **`key`** groups requests with different reply actions, or splits one action into separate groups: `` { url: `/api/items/${id}`, ok: 'ITEM', key: `item-${id}`, latest: true } `` keeps one request per item in flight.
+- `makeFetchDriver({ latest: true })` makes every request latest-only (a request can still say `latest: false`). Prefer `latest: true` on the request: tests see it too.
+
+## Requests
+
+A request is an object (or a URL string, for a plain GET with no reply actions):
+
+| Field | Default | Meaning |
+|---|---|---|
+| `url` | (required) | The URL, prefixed with the driver's `baseUrl` |
+| `ok` | — | Action that receives the parsed body of a 2xx response |
+| `error` | — | Action that receives `{ error, status, body, request }` |
+| `key` | the `ok` action, else `error` | The group for `latest` and `abort` |
+| `method` | `'POST'` with `json`/`body`, else `'GET'` | HTTP method |
+| `query` | — | Object appended as a query string, before any `#fragment`: `{ q: 'dune' }` → `?q=dune` (URL-encoded; `null`/`undefined` values skipped; an array repeats the key: `{ tag: ['a', 'b'] }` → `?tag=a&tag=b`) |
+| `json` | — | Body sent as `JSON.stringify(json)` with `Content-Type: application/json` |
+| `body` | — | Raw body (string, `FormData`, `Blob`, …) |
+| `headers` | — | Object or `Headers`, merged over the driver's `headers` case-insensitively (sent with lowercase names) |
+| `latest` | driver's `latest` (false) | Abort this instance's requests with the same key still in flight |
+| `timeoutMs` | driver's `timeoutMs` (none) | Fail with a `TimeoutError` after this many ms |
+| `parse` | `'auto'` | How the body becomes the `ok` data: `'auto'` (JSON when the content-type says JSON, otherwise text; 204 → `null`), `'json'`, `'text'`, `'response'` (the `Response` itself), or a function `res => value` |
+| `init` | driver's `init` | Other `fetch()` options: `{ credentials: 'include', mode, cache, redirect, referrer, referrerPolicy, integrity, keepalive, priority }` |
+| `cache`, `staleTime` | — | Answer from the driver's cache (GET/HEAD only): see [Resources and Caching](./resources.md#the-query-cache) |
+| `tags`, `invalidates` | — | Tags for [invalidation](./resources.md#invalidation); `invalidates: ['quotes']` refreshes the tagged reads after a 2xx reply |
+| `updates` | — | After a 2xx reply, write it into this component's resources (and their cache entries): `updates: 'item'`, or `{ items: (list, reply) => newList }` ([Writing a reply into the cache](./resources.md#writing-a-reply-into-the-cache)) |
+| `retry` | driver's `retry` for GET/HEAD (0) | Retry network errors, 408, 429 and 5xx: a count or `{ count, delayMs, maxDelayMs, jitter }` ([Retries](./resources.md#retries)) |
+| `validate` | — | A Standard Schema the body must pass ([Validation](./resources.md#validation)) |
+
+Any other field is yours (an id, the query text): it isn't sent, and it comes back on the failure's `request`. A sink that returns `ABORT`, `null` or `undefined` sends nothing.
+
+A request that names only `ok` sends its failures to `HTTP.errors()` (logged when nothing listens), and one that names only `error` sends its successes to `HTTP.select()`. Name both.
+
+## Driver Options
+
+```javascript
+makeFetchDriver({
+  baseUrl: '/api',                       // prefix for every url
+  headers: { Authorization: `Bearer ${token}` },
+  init: { credentials: 'include' },      // fetch() options for every request
+  latest: false,                         // default for every request
+  timeoutMs: 10000,                      // default for every request (default: none)
+  parse: 'auto',                         // default for every request
+  fetch: myFetch,                        // default: globalThis.fetch, read at each request
+  cache: queryCache(),                   // the query cache (default: none), see Resources and Caching
+  retry: 2,                              // default for GET/HEAD requests (default: 0)
+})
+```
+
+- Disposing the app (or a hot reload) aborts every request in flight; nothing is delivered after.
+- Server rendering (`renderToString`, Vike, Astro) runs views only, so no request is made on the server; drivers run on the client. Server data for the first render comes from Vike's [`+data`](https://sygnal.js.org/integration/vike/) or [`hydrateState`](./ssr.md), and resources can be rendered from a seeded query cache ([Server rendering](./resources.md#server-rendering)).
+
+## Testing Without a Driver
+
+`renderComponent` needs no driver for `HTTP`. The requests the component sends are recorded, and the source is a fake that replies like the real driver. Answer a request with `t.respond` or fail it with `t.fail`, and `await` the call:
+
+```js
+import { it, expect, afterEach } from 'vitest'
+import { renderComponent } from 'sygnal'
+import Quote from './Quote.jsx'
+
+let t
+afterEach(() => t?.dispose())
+
+it('shows the picked quote, then a missing one', async () => {
+  t = renderComponent(Quote, { strict: true })
+  t.simulateEvent('.pick[data-id="2"]', 'click')
+  await t.respond('HTTP', { text: 'Two' }, 'LOADED')   // resolves once LOADED is reduced and rendered
+  expect(t.requests('HTTP')[0].url).toBe('/api/quotes/2')
+  expect(t.html()).toContain('Two')
+
+  t.simulateEvent('.refresh', 'click')
+  await t.fail('HTTP', 404)                           // an HTTP status, an Error, or a message
+  expect(t.state.error).toBe('No such quote.')
+  t.expectNoDiagnostics()
+})
+```
+
+- The third argument picks the request: an action, key or category name (`'LOADED'`), a partial request (`{ url: '/api/quotes/2' }`), or a predicate. Without it, the newest pending request is answered.
+- A request that was superseded by `latest: true` or aborted is no longer pending, and answering it **throws at the call**: `expect(() => t.respond('HTTP', [], { query: { q: 'du' } })).toThrow()` asserts that a stale request can't land. (A call made while earlier input is still queued, such as a debounced search, waits up to 1 s for its request instead.)
+- `t.requests('HTTP')` lists the requests sent; `t.sinkValues('HTTP')` also has the `{ abort }` commands.
+
+The [Testing guide](https://sygnal.js.org/integration/testing/#answering-requests-respond-and-fail) has the full matching rules. In a running app, a sink with no driver is reported as [SYG609](https://sygnal.js.org/reference/errors/#syg609) (with the dev diagnostics on).
+
+## Reads That Follow State: resources
+
+For data a component shows, declare it instead of loading it in the model: `` Quote.resources = { quote: (state) => state.id && `/api/quotes/${state.id}` } `` fetches whenever the request changes and writes `state.quote = { status, data, error, refreshing }`. [Resources and Caching](./resources.md) covers refetching, the opt-in cache, invalidation, retries and validation.
+
+## Requests Without Reply Actions: select() and errors()
+
+A request without `ok`/`error` has no reply actions: its reply goes to the `HTTP` source, read in the intent with `HTTP.select(category)` (`{ category, value, status, request }`) and `HTTP.errors(category)` (`{ error, category, request, status, body }`). Use it to compose replies as streams, or for replies that a component other than the sender handles. Reading your own request back this way is the [alternative form](https://sygnal.js.org/advanced/alternative-forms/#selecterrors-round-trip) of reply actions, flagged in strict mode as [SYG508](https://sygnal.js.org/reference/errors/#syg508).
+
+## Recipes
+
+### Optimistic update with rollback
+
+Change the state at once and send the write in the same action. Put the previous value on the request as your own field: fields the driver doesn't know aren't sent, and they come back on the failure's `request`, so the `error` action can restore it. In this demo, a stand-in server saves the first todo and refuses the second:
+
+```js live-server
+const todos = { 1: { id: 1, title: 'Write', done: false } }   // no todo 2: a 500
+
+export default {
+  'PATCH /api/todos/:id': ({ params, json }) => {
+    const todo = todos[params.id]
+    if (!todo) return { status: 500, json: { message: 'Disk full' }, delayMs: 1000 }
+    return { json: Object.assign(todo, json), delayMs: 1000 }
+  },
+}
+```
+
+```jsx live
+function Todos({ state }) {
+  return (
+    <div>
+      <ul>{state.todos.map(t => <li className={t.done ? 'todo done' : 'todo'}><button className="toggle" data-id={String(t.id)}>{t.done ? '✓ ' : ''}{t.title}</button></li>)}</ul>
+      <p className="error">{state.error}</p>
+    </div>
+  )
+}
+Todos.initialState = { todos: [{ id: 1, title: 'Write', done: false }, { id: 2, title: 'Ship', done: false }], error: '' }
+Todos.intent = ({ DOM }) => ({ TOGGLE: DOM.click('.toggle').data('id', Number) })
+Todos.model = {
+  TOGGLE: {
+    STATE: (state, id) => ({ ...state, error: '', todos: state.todos.map(t => (t.id === id ? { ...t, done: !t.done } : t)) }),
+    HTTP:  (state, id) => {
+      const before = state.todos.find(t => t.id === id)   // the state before this action
+      return { url: `/api/todos/${id}`, method: 'PATCH', json: { done: !before.done }, ok: 'SAVED', error: 'SAVE_FAILED', before }
+    },
+  },
+  SAVED:       (state, saved) => ({ ...state, todos: state.todos.map(t => (t.id === saved.id ? saved : t)) }),
+  SAVE_FAILED: (state, { request }) => ({   // request is the request as sent, with your own fields
+    ...state,
+    error: 'Could not save.',
+    todos: state.todos.map(t => (t.id === request.before.id ? request.before : t)),
+  }),
+}
+```
+
+`SAVED` replaces the item with the server's version. In a test, `await t.fail('HTTP', 500)` and check that the item is back.
+
+### Save status
+
+A write's status is ordinary state: set it when the request is sent and in the reply actions. Ignoring a second click while saving keeps one request in flight. In this demo, a stand-in server rejects an empty name:
+
+```js live-server
+export default {
+  'PUT /api/profile': ({ json }) => (json.name.trim() === ''
+    ? { status: 422, json: { name: 'Required' }, delayMs: 800 }
+    : { json, delayMs: 800 }),
+}
+```
+
+```jsx live
+import { ABORT } from 'sygnal'
+
+function Profile({ state }) {
+  const label = { idle: '', saving: 'Saving…', saved: 'Saved.', failed: 'Could not save.' }[state.save]
+  return (
+    <form>
+      <input className="name" aria-label="Name" value={state.name} />
+      <button className="save" disabled={state.save === 'saving'}>Save</button>
+      <p className="save-status">{label}</p>
+    </form>
+  )
+}
+Profile.initialState = { name: '', save: 'idle' }   // 'idle' | 'saving' | 'saved' | 'failed'
+Profile.intent = ({ DOM }) => ({ NAME: DOM.input('.name').value(), SAVE: DOM.click('.save') })
+Profile.model = {
+  NAME: (state, name) => ({ ...state, name, save: 'idle' }),
+  SAVE: {
+    STATE: (state) => (state.save === 'saving' ? ABORT : { ...state, save: 'saving' }),
+    HTTP:  (state) => (state.save === 'saving' ? ABORT : { url: '/api/profile', method: 'PUT', json: { name: state.name }, ok: 'SAVED', error: 'SAVE_FAILED' }),
+  },
+  SAVED:       (state) => ({ ...state, save: 'saved' }),
+  SAVE_FAILED: (state) => ({ ...state, save: 'failed' }),
+}
+```
+
+To refresh the reads a save changed, add `invalidates: ['profile']` to the request ([Invalidation](./resources.md#invalidation)). To show the saved record at once, add `updates: 'profile'` when the profile is a resource ([Writing a reply into the cache](./resources.md#writing-a-reply-into-the-cache)).
+
+For reads, see the [pagination and infinite list recipes](./resources.md#recipes).
+
+## Related
+
+- [Resources and Caching](./resources.md): declarative reads, the query cache, invalidation, retries, validation
+- [Sockets](https://sygnal.js.org/guide/sockets/): WebSocket and server-sent events with `makeSocketDriver()`
+- [Custom Drivers](https://sygnal.js.org/guide/custom-drivers/): `driverFromAsync()` for any promise-returning function, and hand-written drivers
+- [Server Functions](https://sygnal.js.org/integration/server-functions/): calling Telefunc functions through a driver with reply actions