sygnal 6.6.0 → 7.0.0

package/dist/guide/accessibility.md

@@ -266,6 +266,8 @@ Star.model = { STAR: (state) => ({ ...state, starred: !state.starred }) }
 
 Use `aria-selected` for a tab, `aria-expanded` for a disclosure, `aria-checked` with `role="switch"`, and `aria-current="page"` for the current link. Native controls that carry their own state (a checkbox, `select`, `details`) aren't reported, and neither is a busy class (`{ saving: state.saving }`) that the click sets rather than toggles.
 
+A change announced another way isn't reported either: the element's text or `aria-label` follows a field of the class condition (a Copy button whose text becomes `{state.status === 'copied' ? 'Copied!' : 'Copy'}`), or it has `aria-live` or `role="status"` / `role="alert"`. `aria-pressed` is only for an on/off toggle; for any other change, let the text or label say it.
+
 ## ARIA values in JSX
 
 An `aria-*` attribute set to `true` renders `"true"`. Set to `false`, it renders `"false"` on the ARIA states that have a false value (`aria-expanded`, `aria-hidden`, `aria-pressed`, `aria-checked`, `aria-selected`, `aria-disabled`, `aria-invalid`, `aria-current`, `aria-haspopup`, `aria-busy`, `aria-modal`, `aria-required`, `aria-readonly`, `aria-multiline`, `aria-multiselectable`, `aria-atomic`, `aria-grabbed`); on any other `aria-*` (a label, an id reference, a number) `false` removes the attribute, so `aria-describedby={hasError && uid('error')}` doesn't announce "false". `null` and `undefined` remove it. Passed to a component, `role`, `for`, `tabindex` and `aria-*` are ordinary props: the component gets the value as written.

package/dist/guide/ai-chat.md

@@ -92,8 +92,8 @@ Chat.model = {
     STATE: (state) => (state.prompt.trim()
       ? { ...state, messages: [...state.messages, { role: 'user', content: state.prompt }], prompt: '', status: 'streaming', error: null }
       : ABORT),
-    // sinks see the state before the action: the conversation plus the prompt being sent
-    LLM: (state) => (state.prompt.trim() ? ask([...state.messages, { role: 'user', content: state.prompt }]) : ABORT),
+    // STATE has stored the new message; the prompt from before it decides whether to send
+    LLM: (state, data, next, { previousState }) => (previousState.prompt.trim() ? ask(state.messages) : ABORT),
   },
   STOP: {
     // keep the text that arrived; nothing arrives after the abort
@@ -114,7 +114,7 @@ Chat.model = {
 What the component does:
 
 - **The conversation is state.** `messages` holds the user's messages and the model's replies. Every request sends the whole conversation: models are stateless, so the history goes with each turn. A message you write yourself can be `{ role: 'user', content: text }`: the driver, `messageText()` and every transport accept that short form.
-- **`SEND` has two sinks.** `STATE` adds the user's message, `LLM` sends the request. Both see the state from before the action ([Model](https://sygnal.js.org/guide/model/#sinks-see-the-state-before-the-action)), so the `LLM` sink builds the message list with the prompt itself.
+- **`SEND` has two sinks.** `STATE` adds the user's message, `LLM` sends the request. STATE runs first, so the `LLM` sink sends the message list STATE just stored; STATE has cleared `prompt`, so the empty-submit guard reads `previousState.prompt` ([Model](https://sygnal.js.org/guide/model/#what-state-each-sink-sees)).
 - **`DELTA` shows the reply so far.** Its `text` is all the text received, not just the new piece, so the reducer only replaces `draft`.
 - **`DONE` gets the finished message** and appends it to the conversation as is.
 - **`STOP` aborts the request** by its key. Nothing arrives after an abort, not even `FAILED`.
@@ -388,7 +388,7 @@ Shopping.model = {
     STATE: (state) => (state.prompt.trim()
       ? { ...state, messages: [...state.messages, { role: 'user', content: state.prompt }], prompt: '', status: 'streaming', error: null }
       : ABORT),
-    LLM: (state) => (state.prompt.trim() ? ask([...state.messages, { role: 'user', content: state.prompt }]) : ABORT),
+    LLM: (state, data, next, { previousState }) => (previousState.prompt.trim() ? ask(state.messages) : ABORT),
   },
   DELTA: (state, { text }) => ({ ...state, draft: text }),
   // runs the call as it arrives; the model's input is unchecked, so check it
@@ -402,8 +402,8 @@ Shopping.model = {
       draft: '',
       status: toolCalls.length ? 'streaming' : 'ready',
     }),
-    // after tool calls, send the conversation again with their outputs
-    LLM: (state, { message, toolCalls }) => (toolCalls.length ? ask([...state.messages, answered(message, state.items)]) : ABORT),
+    // after tool calls, send the conversation again: STATE has added the answered message
+    LLM: (state, { toolCalls }) => (toolCalls.length ? ask(state.messages) : ABORT),
   },
   FAILED: (state, { error }) => ({ ...state, draft: '', status: 'ready', error: error.message }),
 }

package/dist/guide/behaviors.md

@@ -185,7 +185,7 @@ Two components can use the same behavior, and so can every item of a [Collection
 
 ### Options, the key, host state and timers
 
-Every model handler of a behavior gets the use's options and its key after the usual arguments: `(slice, data, next, props, options, key)`, and the intent gets `(sources, options, key)`. `props.state` is the host's whole state.
+Every model handler of a behavior gets the use's options and its key after the usual arguments: `(slice, data, next, props, options, key)`, and the intent gets `(sources, options, key)`. `props.state` is the host's whole state. As in a component, STATE runs first: an output handler gets the slice and `props.state` after it, and `props.previousState` is the host's state from before the action, so the slice from before it is `props.previousState[key]` ([Model](https://sygnal.js.org/guide/model/#what-state-each-sink-sees)).
 
 Two more parts are for behaviors that reach past their slice:
 

package/dist/guide/element-commands.md

@@ -68,6 +68,8 @@ declare module 'sygnal' {
 }
 ```
 
+A command built outside the model's return, in a variable or a helper, needs a type in TypeScript: in `const top = { scrollIntoView: '.page', block: 'start' }` the `block` widens to `string`, which isn't a `ScrollLogicalPosition`. Annotate it, `const top: ElementCommand = { … }` (or write `satisfies ElementCommand`); `ElementCommand` is exported from `sygnal`. A command written inside the return needs nothing.
+
 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
@@ -105,12 +107,12 @@ 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`) }),
+    ELEMENT: (state, data, next, { previousState }) => ({ focus: focusWithin(`[data-id="${previousState.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.
+STATE has already incremented `next` when `ELEMENT` runs, so the new row's id is `previousState.next`. 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
 

package/dist/guide/forms-reference.md

@@ -13,6 +13,7 @@ The details of the [`form` behavior](./forms.md). Start with the recipe on [Form
 | `errors` | Every current schema error by field name, shown or not |
 | `touched`, `server`, `remote`, `pending` | Blurred fields; [server errors](./forms.md#server-errors-and-failed-submits); [check](#async-checks) results; checks running |
 | `submitting`, `submitted`, `submitCount`, `queued`, `validating`, `validated` | Submit state: the request sent and not answered yet; `form.DONE` arrived (or a submit without a request was dispatched); attempts; a submit waits for a check or an async schema; an async schema runs; the schema has answered since the start or the last reset |
+| `progress`, `resets` | The submit request's last [progress](#file-fields) step (`{ phase, loaded, total, fraction }`, or `null`); how many times the form started over (`form.RESET`, `resetOnShow`), for keying a [file input](#file-fields) |
 | `fields`, `valid`, `dirty`, `error` | Calculated: per-field view data; no errors as of the schema's last answer (`false` before the first); values differ from `initial`; the form-level message |
 
 The options are on [Forms](./forms.md#options).
@@ -23,7 +24,7 @@ Named after the `uses` key (`form.CHANGE` for `uses = { form: … }`):
 
 | Action | Data |
 |---|---|
-| `form.CHANGE` | `{ name, value }`: from the form element's `input` events ([field types](./forms.md#field-types); a checkbox gives `checked`, and its `value` as `item`) |
+| `form.CHANGE` | `{ name, value }`: from the form element's `input` events ([field types](./forms.md#field-types); a checkbox gives `checked`, and its `value` as `item`; a [file input](#file-fields) its `File`) |
 | `form.SET` | `{ values }`: several fields at once, by field name (`{ name: 'Dana', 'addresses.7.city': 'Hilo' }`), as if the user had typed them: one validation, the fields count as changed, `touched` as for `form.CHANGE` (so errors show by the [`show`](./forms.md#options) rule), their server errors and check results cleared. Fields not named keep their values; a name that isn't a field is skipped ([SYG230](https://sygnal.js.org/reference/errors/#syg230) in development). For a fill from elsewhere: [an AI extraction](./recipes/ai-form-fill.md), a saved draft, an address lookup |
 | `form.BLUR` | The field name, from `focusout` |
 | `form.SUBMIT` | From the form element's `submit` (default prevented) |
@@ -31,10 +32,50 @@ Named after the `uses` key (`form.CHANGE` for `uses = { form: … }`):
 | `form.ERRORS` | Server errors: an error reply, a map or a list of issues |
 | `form.DONE` | The submit's request was saved: `initial` becomes `values`, `submitted` turns on ([a submit without a request](./forms.md#submit-without-a-request) needs none) |
 | `form.RESET` | Back to `initial`, or to the values given |
+| `form.PROGRESS` | A progress step of the submit's request, sent with `progress: 'form.PROGRESS'`: kept as `progress` until `form.DONE` or `form.ERRORS` ([file fields](#file-fields)) |
 | `form.VALIDATE` | Internal: the first validation when the host starts; with `resetOnShow`, the start over (also each time the form element appears again) |
 
 As for any behavior, a host model entry with the same name runs after the form's: `'form.DONE': (state) => ({ ...state, done: true })` shows a confirmation. Trigger an action from elsewhere with an intent action of that name, or `t.simulateAction('form.RESET')` in a test.
 
+## File fields
+
+A file input whose `name` is in `values` is a field like any other: its value is the `File` the user picked (an array of them with `multiple`, `null` when none), the schema validates it, its error shows on `fields.avatar.error`, and the submit's data carries it, so `request` sends it as [`multipart`](./http.md#upload-and-download-progress):
+
+```jsx
+import { form } from 'sygnal'
+import { z } from 'zod'
+
+const profileSchema = z.object({
+  name: z.string().min(1, 'Enter your name'),
+  avatar: z.file('Choose a photo').max(5_000_000, 'At most 5 MB').mime(['image/png', 'image/jpeg'], 'A PNG or JPEG photo'),
+})
+
+function Profile({ state }) {
+  const f = state.form.fields
+  const percent = Math.round((state.form.progress?.fraction ?? 0) * 100)
+  return (
+    <form>
+      <label>Name <input name="name" value={f.name.value} /></label>
+      <label>Photo <input type="file" name="avatar" accept="image/*" key={'avatar' + state.form.resets} /></label>
+      <p className="chosen">{f.avatar.value?.name}</p>
+      <p className="error">{f.avatar.error}</p>
+      {state.form.submitting && <progress max="100" value={percent} aria-label="Upload progress" />}
+      <button type="submit" disabled={state.form.submitting}>Save</button>
+    </form>
+  )
+}
+
+// the data has a File, so the form sends it as multipart, with progress in state.form.progress
+Profile.uses = { form: form(profileSchema, { values: { name: '', avatar: null }, request: { url: '/api/profile' } }) }
+```
+
+- **Progress**: the form's `request` asks for progress (`progress: 'form.PROGRESS'`; a `submit` entry's request can name it too), and the form keeps the latest step in `state.form.progress` (`{ phase, loaded, total, fraction }`) while it is submitting, and clears it on `form.DONE`, `form.ERRORS` and `form.RESET`.
+- **Don't bind `value`**: the browser doesn't let a page set a file input's file. So a reset can't clear it through state; instead the form counts its start overs in `state.form.resets`, and `key={'avatar' + state.form.resets}` makes a new, empty input after each one. For the same reason, show the chosen file's name yourself (`f.avatar.value?.name`): after a reset to saved values (`form.DONE` makes the saved values the start values) the value is still the file while the new input is empty.
+- **Validation** uses your schema's file checks: zod's `z.file()` (`.max()`, `.mime()`), valibot's `v.file()`, or `instanceof File` in a hand-written schema. Required means rejecting `null`.
+- **Tests** pick a file with `t.simulateEvent('[name="avatar"]', 'input', { target: { files: [new File(['…'], 'me.png')] } })`, submit, then `t.progress('HTTP', { loaded: 1, total: 2 }, 'form.PROGRESS')` and `t.respond('HTTP', reply, 'form.DONE')`.
+- A file input whose `name` isn't in `values` is left alone, as before 6.7, for an app that reads its files in its own intent.
+- A `File` can't be serialized, so `persist()` and server-rendered state don't carry file fields.
+
 ## Any Standard Schema
 
 `form()` takes any object with `~standard.validate`: zod (3.24 and later), valibot (1.0 and later), arktype, or one you write. A schema's issue paths become field names, and an issue without a path is a form-level message (`state.form.error`, shown after a submit):
@@ -263,11 +304,15 @@ Signup.model = {
 
 `form.DONE` marks the submit saved: `submitting` turns off, `submitted` on, and the saved values become `initial` (so `dirty` is `false` again).
 
-Whether a valid submit waits for `form.DONE` depends on the host's entry for the `submit` action, checked when the host starts:
+Whether a valid submit waits for `form.DONE` depends on how it is sent:
+
+- **With `request`**: the form sends it on its `http` sink and waits. `request` is an object or `(data, state) => request`, called with the schema's output and the host's state (as committed: the outputs' state since 7.0); `ABORT` or a falsy result sends nothing and leaves the submit pending, as below. The form adds `json: data` (or `multipart: data` when a top-level value is a `File`, `Blob` or an array of them; a file nested deeper isn't sent as a file) unless the request sets `json`, `multipart` or `body`, adds `progress: 'form.PROGRESS'` unless it sets `progress`, and always sets `ok: 'form.DONE'` and `error: 'form.ERRORS'`. With `submit` as well, that host action is dispatched too (to set state); its entry shouldn't send another request.
+
+Otherwise it depends on the host's entry for the `submit` action, checked when the host starts:
 
 - **With the `http` sink** (`SIGN_UP: { HTTP: … }`, or the sink the `http` option names, such as `http: 'API'`): `submitting` is `true` until `form.DONE` or `form.ERRORS`, and a submit meanwhile is dropped ([SYG232](https://sygnal.js.org/reference/errors/#syg232)). Even when the entry returns `ABORT` this time, the form waits.
 - **Anything else** (`STATE`, `PARENT`, `EVENTS`, `EFFECT`, `ROUTER`, a reducer function): no request, so the submit is done at once, as if `form.DONE` had arrived (no host `form.DONE` entry runs). An `EFFECT` that calls `next('form.DONE')` itself still works; the second `DONE` changes nothing. Work that answers later without the `http` sink (a promise in an `EFFECT`) gets no pending state: send it through a driver as a request instead.
-- **A host that unmounts** keeps its slice in the parent's state when it has a `state` prop. When it mounts again, the form clears `submitting`, `queued` and running checks (their replies went to the old host); the values, errors and `submitted` stay. `form.RESET` goes back to `initial`, or to the values it is given (`t.simulateAction('form.RESET', values)`, or an intent action `'form.RESET': DOM.click('.reset')`); it clears errors, touched fields and the submit count.
+- **A host that unmounts** keeps its slice in the parent's state when it has a `state` prop. When it mounts again, the form clears `submitting`, `queued` and running checks (their replies went to the old host); the values, errors and `submitted` stay. `form.RESET` goes back to `initial`, or to the values it is given (`t.simulateAction('form.RESET', values)`, or an intent action `'form.RESET': DOM.click('.reset')`: data that isn't a plain object, such as the click event, means `initial`); it clears errors, touched fields and the submit count.
 - **Starting over when shown** (`resetOnShow: true`): the form goes back to its start values, as a new form (`initial` too; touched fields, errors, server errors, checks and the submit state cleared), when its host starts (mounted again, a Switchable page made again for another `instance`) and each time its form element appears in the host's DOM after being absent (a Switchable page shown again: hidden pages stay alive and keep their state; a form rendered conditionally). Re-renders while the form is shown keep what the user typed. With the mock DOM (and in SSR) only the host's start counts. A `values` function gets the host's whole state and is called at each start over; without `resetOnShow`, once, when the host starts and the slice is still untouched. Before its first call (the first render of a page that reads its parent's state) the fields come from calling it with a blank state, every value read from it `''`.
 
 ## Without the behavior: the helpers
@@ -344,6 +389,47 @@ Signup.uses = {
 - A user's own submit is unchanged.
 - `formTool` comes from `sygnal/ai` so that an app using `form` without a tool doesn't carry the tool code. A plain object as `tool` does nothing but report [SYG245](https://sygnal.js.org/reference/errors/#syg245) in development.
 
+## TypeScript
+
+With a schema that declares its [Standard Schema](https://standardschema.dev) types (zod, valibot and arktype do), `form()` types the values from the schema's input and checks `values` against it. `UsesState<typeof uses>` gives the component's state the slice: `state.form.values.email` and `state.form.fields.email.value` are strings, and a top-level field name that isn't in the values is a type error (nested paths such as `` f[`addresses.${id}.city`] `` stay open). `FormOutput<typeof uses.form>` (or `SchemaOutput<typeof signupSchema>`) is the schema's output, the data of the host's submit action:
+
+```tsx
+import { form } from 'sygnal'
+import type { Component, UsesState, UsesActions, FormOutput } from 'sygnal'
+import { z } from 'zod'
+
+const signupSchema = z.object({
+  email: z.string().trim().email('Enter a valid email address'),
+  age: z.coerce.number().int().min(18, 'You must be 18 or older'),
+})
+
+const uses = {
+  form: form(signupSchema, { values: { email: '', age: '' }, submit: 'SIGN_UP' }),
+}
+
+type State = UsesState<typeof uses>
+type Actions = UsesActions<typeof uses> & { SIGN_UP: FormOutput<typeof uses.form> }
+
+const Signup: Component<State, {}, {}, Actions> = ({ state }) => {
+  const f = state.form.fields
+  return (
+    <form noValidate>
+      <label>Email <input name="email" value={f.email.value} aria-invalid={f.email.invalid} /></label>
+      <label>Age <input name="age" inputMode="numeric" value={f.age.value} aria-invalid={f.age.invalid} /></label>
+      <button type="submit" disabled={state.form.submitting}>Sign up</button>
+    </form>
+  )
+}
+
+Signup.uses = uses
+Signup.model = {
+  // values: { email: string; age: number }, the schema's output
+  SIGN_UP: { HTTP: (state, values) => ({ url: '/api/signup', method: 'POST', json: values, ok: 'form.DONE', error: 'form.ERRORS' }) },
+}
+```
+
+A schema without `types` (a hand-written one) types the values from `values` and the output as `any`. The reply actions are typed too: `form.ERRORS` takes an error reply, a map `{ name: message }` or a list of issues (`FormServerErrors`), and `form.RESET` the whole values (or nothing, for `initial`).
+
 ## Diagnostics
 
 With the dev checks on (the Vite plugin in dev, `renderComponent` in tests): [SYG230](https://sygnal.js.org/reference/errors/#syg230) a field inside the form whose name isn't in `values`, [SYG231](https://sygnal.js.org/reference/errors/#syg231) a schema that isn't a Standard Schema, [SYG232](https://sygnal.js.org/reference/errors/#syg232) a submit dropped while one is in progress (info), [SYG233](https://sygnal.js.org/reference/errors/#syg233) a value the schema strips from its output, [SYG234](https://sygnal.js.org/reference/errors/#syg234) a `submit` action the model doesn't have, [SYG235](https://sygnal.js.org/reference/errors/#syg235) a `check` for an unknown field, or a check request that sets `ok`/`error`/`latest`, [SYG236](https://sygnal.js.org/reference/errors/#syg236) array rows without an `id`, and [SYG237](https://sygnal.js.org/reference/errors/#syg237) two forms in one component on the same selector. `sygnal-check` knows `form`: an option typo is [SYG127](https://sygnal.js.org/reference/errors/#syg127), and fields inside the form element are not reported as uncontrolled ([SYG111](https://sygnal.js.org/reference/errors/#syg111)).

package/dist/guide/forms.md

@@ -69,7 +69,7 @@ function Signup({ state, uid }) {
 Signup.initialState = { accountId: null }
 
 Signup.uses = {
-  form: form(signupSchema, { values: { name: '', email: '', addresses: [{ id: 1, city: '' }] }, submit: 'SIGN_UP' }),
+  form: form(signupSchema, { values: { name: '', email: '', addresses: [{ id: 1, city: '' }] }, request: { url: '/api/signup' } }),
 }
 
 Signup.intent = ({ DOM }) => ({
@@ -78,7 +78,6 @@ Signup.intent = ({ DOM }) => ({
 })
 
 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 }),
 }
 ```
@@ -91,8 +90,8 @@ Signup.model = {
 - **`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.
+- **A valid submit** sends the `request` with the schema's output as its body: 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. The form adds `json: data` (`multipart` when a value is a [file](./forms-reference.md#file-fields)), `progress: 'form.PROGRESS'` and its reply actions `ok: 'form.DONE'`, `error: 'form.ERRORS'`. Other request fields (`method`, `headers`) are sent as written.
+- **Pending**: `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"`.
 
@@ -104,7 +103,7 @@ Reserve the height of the error lines in your CSS (`min-height`). A field's erro
 
 ## 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`.
+A submit that sends nothing (a wizard step's "Next", a dialog's "OK") names a host action with `submit` instead of `request`: 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`. (One with an `HTTP` sink is pending like a `request`.)
 
 ```jsx
 AccountStep.uses = { form: form(accountSchema, { values: { email: '', password: '' }, submit: 'NEXT' }) }
@@ -185,18 +184,19 @@ What `state.form.values[name]` gets from each kind of field, and how to bind it:
 | `<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` |
+| `<input type="file">` | Its `File` (`multiple`: an array), or `null` | Don't bind `value`: [file fields](./forms-reference.md#file-fields) |
 
 ## 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)) |
+| `request` | What a valid submit sends: `{ url, … }`, or `(data, state) => request` (an id from state) |
+| `submit` | Instead of `request`: 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; [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 |
+| `http` | The driver sink of the requests, default `'HTTP'` |
 | `resetOnShow` | `true`: start over each time the form is shown ([start empty on each visit](#start-empty-on-each-visit)) |
 | `tool` | Experimental: `formTool({ name, description, autosubmit? })` from `sygnal/ai` offers the form to the browser's agent ([WebMCP](./forms-reference.md#offer-the-form-to-the-browsers-agent)) |
 

package/dist/guide/http.md

@@ -45,7 +45,7 @@ Quote.intent = ({ DOM }) => ({
 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
+    HTTP:  (state, id) => ({ url: `/api/quotes/${id}`, ok: 'LOADED', error: 'FAILED', latest: true }),  // or state.id: STATE has stored it
   },
   REFRESH: {
     STATE: (state) => (state.id === null ? ABORT : { ...state, status: 'loading', error: '' }),
@@ -66,7 +66,7 @@ Click First, then Second before quote 1 arrives: with `latest: true` the first r
 
 ### 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`.
+STATE runs first, so the HTTP sink of `SHOW` sees the `id` STATE just stored; the action's data has it too. `REFRESH` doesn't change `id` and reads it from `state`. A request that needs a value STATE replaced (a cleared field, a guard on a flag STATE sets) reads it from the fourth argument's `previousState` ([Model](https://sygnal.js.org/guide/model/#what-state-each-sink-sees)). Sygnal 6.x gave every sink the state from before the action; see [Migrating to 7.0](./migrating-to-7.md).
 
 ## Only the Latest Response
 
@@ -123,10 +123,12 @@ A request is an object (or a URL string, for a plain GET with no reply actions):
 | `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 |
+| `method` | `'POST'` with `json`/`multipart`/`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` |
+| `multipart` | — | A `multipart/form-data` body written as data: `{ file: state.file, title: state.title }` ([uploads](#upload-and-download-progress)) |
 | `body` | — | Raw body (string, `FormData`, `Blob`, …) |
+| `progress` | — | Report upload and download progress: an action name (`'UPLOADING'`) or `true` for `HTTP.progress()` ([Upload and download progress](#upload-and-download-progress)) |
 | `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 |
@@ -143,6 +145,72 @@ Any other field is yours (an id, the query text): it isn't sent, and it comes ba
 
 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.
 
+## Upload and Download Progress
+
+Add `progress` to a request to hear how far it has got. With an action name, each step arrives as that action of the component that sent it, like `ok` and `error`:
+
+```js live-server
+export default {
+  'POST /api/files': ({ body }) => {
+    const file = body.get('file')
+    return { status: 201, json: { name: file.name, size: file.size }, delayMs: 300 }
+  },
+}
+```
+
+```jsx live title="Upload.jsx"
+import { ABORT } from 'sygnal'
+
+function Upload({ state }) {
+  const percent = Math.round(state.fraction * 100)
+  return (
+    <form className="upload">
+      <input type="file" className="file" aria-label="File to upload" />
+      <button type="button" className="sample">Use a 3 MB sample</button>
+      <button type="submit" disabled={!state.file || state.status === 'uploading'}>Upload</button>
+      <progress max="100" value={percent} aria-label="Upload progress">{percent}%</progress>
+      <p className="status" role="status">{state.message}</p>
+    </form>
+  )
+}
+Upload.initialState = { file: null, fraction: 0, status: 'idle', message: '' }
+Upload.intent = ({ DOM }) => ({
+  PICK:   DOM.select('.file').events('change').map((e) => e.target.files[0] ?? null),
+  SAMPLE: DOM.click('.sample'),
+  SEND:   DOM.select('.upload').events('submit', { preventDefault: true }),
+})
+const busy = (state) => !state.file || state.status === 'uploading'
+Upload.model = {
+  PICK:   (state, file) => ({ ...state, file, fraction: 0, status: 'idle', message: file ? file.name : '' }),
+  SAMPLE: (state) => ({ ...state, file: new File([new Uint8Array(3 * 1024 * 1024)], 'sample.bin'), fraction: 0, status: 'idle', message: 'sample.bin' }),
+  SEND: {
+    STATE: (state) => (busy(state) ? ABORT : { ...state, status: 'uploading', fraction: 0, message: 'Uploading…' }),
+    // STATE has already set status 'uploading': admit the upload by the state before this SEND
+    HTTP:  (state, data, next, { previousState }) => (busy(previousState) ? ABORT : { url: '/api/files', multipart: { file: state.file }, progress: 'UPLOADING', ok: 'UPLOADED', error: 'FAILED' }),
+  },
+  UPLOADING: (state, { phase, fraction }) => (phase === 'upload' ? { ...state, fraction } : ABORT),
+  UPLOADED:  (state, saved) => ({ ...state, status: 'done', fraction: 1, message: `Uploaded ${saved.name} (${saved.size} bytes).` }),
+  FAILED:    (state) => ({ ...state, status: 'failed', message: 'Upload failed.' }),
+}
+```
+
+- **Each step** is `{ phase, loaded, total, fraction, category, request }`. `phase` is `'upload'` while the body is sent, then `'download'` while the reply arrives (a GET reports only `'download'`). `total` and `fraction` (0 to 1) are `null` when the size isn't known, such as a download without a `Content-Length`.
+- **How often:** at most one step every 50 ms per phase, always including the first and the last (`fraction: 1`), so a fast connection doesn't render hundreds of times. A retry starts again at 0.
+- **`progress: true`** sends the steps to the source instead: `HTTP.progress('upload')` in the intent, filtered by category like `select()`.
+- **The file** comes from the input's `change` event (`e.target.files`) and is kept in state. `multipart` turns the request's parts into a `multipart/form-data` body, the encoding upload endpoints expect: a `File` or `Blob` is a file part, an array repeats the name (`files: [a, b]`), `null` and `undefined` are left out, an object is sent as JSON text and anything else as a string. The browser writes the `Content-Type` with its boundary, so one set in `headers` is dropped. In a test, `t.requests('HTTP')` shows the parts as you wrote them (`multipart.file.name`). An endpoint that takes the raw bytes needs no encoding: `body: state.file` (with `method: 'PUT'`). With the [`form` behavior](./forms.md), a file input is a field like any other, and `request: { url }` sends the submit as multipart with progress in `state.form.progress` ([file fields](./forms-reference.md#file-fields)).
+- **XMLHttpRequest:** a request with `progress` goes over `XMLHttpRequest`, because it is the only way to see upload progress in every browser (streamed `fetch` uploads work only in Chromium over HTTP/2). The reply is the same as with `fetch`: parsing, statuses, `latest`, `abort`, `timeoutMs` and `retry` all apply. Options `fetch` has and `XMLHttpRequest` doesn't (`init.keepalive`, `priority`, `cache`, `redirect`, `integrity`, `mode`) are ignored ([SYG636](https://sygnal.js.org/reference/errors/#syg636)), and the driver's `fetch` option isn't used: put auth in `headers`, which apply to both. `progress` does nothing on resources and `batch` requests. Where there is no `XMLHttpRequest` (Node, a service worker), the request is sent with `fetch` and reports no steps.
+
+In a test, `t.progress` sends a step of a pending request, which stays pending until `t.respond` or `t.fail`:
+
+```js
+t.simulateEvent('.sample', 'click')
+t.simulateEvent('.upload', 'submit')
+await t.progress('HTTP', { loaded: 50, total: 100 }, 'UPLOADING')   // phase: 'upload' for a request with a body
+expect(t.state.fraction).toBe(0.5)
+await t.respond('HTTP', { name: 'sample.bin', size: 3145728 }, 'UPLOADED')
+expect(t.state.status).toBe('done')
+```
+
 ## Driver Options
 
 ```javascript
@@ -156,6 +224,7 @@ makeFetchDriver({
   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)
+  XMLHttpRequest: MyXhr,                 // for progress requests (default: the global one)
 })
 ```
 
@@ -234,9 +303,10 @@ 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 }
+    HTTP:  (state, id, next, { previousState }) => {
+      const before = previousState.todos.find(t => t.id === id)   // rollback value
+      const updated = state.todos.find(t => t.id === id)
+      return { url: `/api/todos/${id}`, method: 'PATCH', json: { done: updated.done }, ok: 'SAVED', error: 'SAVE_FAILED', before }
     },
   },
   SAVED:       (state, saved) => ({ ...state, todos: state.todos.map(t => (t.id === saved.id ? saved : t)) }),
@@ -281,7 +351,7 @@ 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' }),
+    HTTP:  (state, data, next, { previousState }) => (previousState.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' }),