@k8ordo/form 0.1.1 → 1.1.0

package/docs/GUIDE.md

@@ -11,14 +11,10 @@ fallbacks.
 ## zod, or zod/mini
 
 The conversion is taken from zod's shared core, so a schema written with either
-entry works. `zod/mini` is the same validator with a much smaller surface — if
-the schema module is also imported somewhere on the client, that is the one to
-reach for.
-
-```
-zod        63 kB gzipped
-zod/mini   10 kB gzipped
-```
+entry works. `zod/mini` is the same validator with a much smaller surface —
+bundled for the browser, the `talkSchema` below comes to about a quarter of the
+size — so if the schema module is also imported somewhere on the client, that
+is the one to reach for.
 
 Nothing in this package notices which one you chose. Note that under this
 design the schema is imported only by server code — the Server Component that
@@ -29,7 +25,8 @@ the client imports the schema module anyway.
 ## The shape of it
 
 ```
-server    formFields(schema)  →  { title: { input, messages }, … }   plain data
+server    formFields(schema)  →  { fields: { title: { input, messages, secret }, … },
+                                   arrays, rules, dropped }   plain data
             ↓ props (zod does not cross)
 client    useForm(fields, state)  →  attributes to spread, message to show
             ↓ submit
@@ -38,12 +35,15 @@ server    parseForm(schema, formData)  →  typed data, or per-field errors
 
 `formFields` runs on the server — in a Server Component or at module scope. Its
 result is JSON, so it crosses the RSC boundary as props and zod never enters the
-client bundle.
+client bundle. The messages are read when it runs — zod's, and a rule's
+[function message](#a-message-that-follows-the-request) — and module scope runs
+once, before any request: when a message follows the request (its locale, say,
+with `@k8ordo/i18n`), call `formFields` during the render instead.
 
 ## Writing a form
 
 ```ts
-// schema.ts
+// src/lib/schema.ts
 export const talkSchema = z.object({
   title: z.string().min(1).max(120),
   eventUrl: z.url(),
@@ -56,8 +56,39 @@ an unchecked checkbox arrives as a missing key, a repeated name arrives as
 several entries, everything is a string — and `z.coerce` handles `'42'` → `42`.
 That way the schema keeps describing what it actually validates.
 
+Because every submitted value is a string, a plain `z.number()` could not accept
+any submission at all; `formFields` refuses it instead of deriving a form that
+always fails. An empty numeric control is not 0 either — it submits nothing, so
+`z.coerce.number()` is required and `z.coerce.number().optional()` is not. That
+makes an untouched field a type error, which is where its wording comes from:
+
+```ts
+z.coerce.number('数値を入力してください');
+```
+
+Depending on the zod version, that wording also replaces the default message of
+every other check on the field that has none of its own (4.5.4 does this, 4.4.3
+does not), so give `.int()` or `.min()` theirs.
+
+Each leaf derives the control that submits what it validates:
+
+| Schema                                           | `input`                                                                                                |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `z.string()`                                     | `type="text"`                                                                                          |
+| `z.email()` / `z.url()`                          | `type="email"` / `type="url"`                                                                          |
+| `z.iso.date()` / `z.iso.time()`                  | `type="date"` / `type="time"`                                                                          |
+| `z.iso.datetime({ local: true })`                | `type="datetime-local"`                                                                                |
+| `z.coerce.number()`                              | `type="number"`; `step` from `.multipleOf()`, else `1` after `.int()` and `any` otherwise              |
+| `z.boolean()`, `z.literal(true)`                 | `type="checkbox"`                                                                                      |
+| `z.stringbool()`                                 | `type="checkbox"` with a `value` ([Checkboxes that submit a string](#checkboxes-that-submit-a-string)) |
+| `z.file()`                                       | `type="file"`                                                                                          |
+| a password ([below](#what-it-guarantees))        | `type="password"`                                                                                      |
+| `z.enum([…])`                                    | no `type`: spread it onto a `<select>`, not a radio ([Radio groups](#radio-groups))                    |
+| `z.array(z.enum([…]))`                           | no `type`: one checkbox per option ([Checkbox groups](#checkbox-groups))                               |
+| anything else (`z.uuid()`, `z.coerce.date()`, …) | `type="text"`                                                                                          |
+
 ```tsx
-// page.tsx — Server Component
+// src/routes/talks/new/page.tsx — Server Component
 const talkFields = formFields(talkSchema); // module scope: derived once
 
 export default function Page() {
@@ -69,7 +100,7 @@ export default function Page() {
 report travel together.
 
 ```tsx
-// talk-form.tsx
+// src/components/talk-form.tsx
 'use client';
 
 export const TalkForm = ({ action, fields }: TalkFormProps) => {
@@ -87,76 +118,180 @@ export const TalkForm = ({ action, fields }: TalkFormProps) => {
 ```
 
 `form.props` attaches to the `<form>` and nowhere else. There is no per-field
-registration to forget.
+registration to forget. Its `onSubmit` checks the form
+([below](#what-it-guarantees)) — an `onSubmit` of your own written after the
+spread replaces it, so call `form.props.onSubmit(event)` from yours — and it
+also hears the form being reset — by a reset
+button, by `form.reset()`, or by React itself after every form action, whatever
+it returned — and forgets what it knew about the old values: the messages,
+which server errors were still current, the rows that were added, and
+`isDirty`.
+
+A form with no action behind it — a GET filter, say — calls `useForm(fields)`
+and leaves the state out. It is still checked on submit, so a filter that
+breaks its schema never reaches the URL.
 
 ```ts
-// actions.ts
+// src/lib/actions.ts
 'use server';
 
+import { href } from '@k8ordo/framework';
+import { redirect } from '@k8ordo/framework/server';
+
 export async function createTalk(_prev: FormState, formData: FormData) {
   const parsed = parseForm(talkSchema, formData);
   if (!parsed.success) return parsed.state;
 
   await insertTalk(parsed.data); // typed
-  redirect('/talks');
+  redirect(href('/talks'));
 }
 ```
 
+When a new state arrives, focus moves to the first failure on the page, so the
+failure is announced where it happened. That is the first failed field in
+document order — not the first key of `state.errors`, which follows the schema
+— or a message no field owns, when it comes before every failed field: the
+form-level message below, or an array's own
+([Nested objects and repeated rows](#nested-objects-and-repeated-rows)). A
+server error stays on its field until the person edits that field, and a
+message the browser raises takes precedence over it. Responses are told apart
+by their content plus `state.token`, which `parseForm` sets on every parse — a
+state built by hand needs a fresh `token` too, or a second identical failure
+reads as the same response, and focus does not move.
+
+An issue with no path — a `.refine()` on the whole schema that names no
+`path` — lands in `state.formError`, not on a field. No control can take focus
+for it, so `form.formError` hands over the message and the props for the
+element that shows it — an `id` and `tabIndex={-1}`, which lets the script
+focus it without adding it to the Tab order. Without them the message is drawn
+but never focused, and a screen reader says nothing about it. Put it above the
+fields, the way an error summary is placed: it then takes focus even when
+fields failed too, the person hears what went wrong with the submission as a
+whole first, and Tab moves on through the fields.
+
+```tsx
+<form {...form.props} action={formAction}>
+  {form.formError.message !== undefined && (
+    <p {...form.formError.props}>{form.formError.message}</p>
+  )}
+  {/* … */}
+</form>
+```
+
+Focus carries the message rather than a live region because focus moves on
+every response: a live region already holding the same text announces nothing
+when the same failure comes back.
+
 ## What it guarantees
 
 **The wording cannot drift.** Client messages are obtained by running the
 schema against a probe value, so the text shown next to the input is the text
-zod itself produces. A custom `min(1, '…')` reaches both sides.
+zod itself produces. A custom `min(1, '…')` reaches both sides. The one
+exception is a range message from `@k8ordo/ui`'s `NumberField` (see
+[Working with @k8ordo/ui](#working-with-k8ordoui)).
 
 **`required` means the same thing on both sides.** JSON Schema's `required`
 means "the key is present", but a form always submits something for every
-control — an empty text field as `''`, an unchecked checkbox as `false` once
-parsed. The attribute is emitted only when the schema rejects that empty
-submission, so the two sides always agree: a plain `z.boolean()` checkbox is
-not required, while `z.literal(true, '…')` — a consent box — is, and shows
-zod's own wording.
-
-**Nothing is dropped in silence.** Checks HTML cannot express — `refine`,
-cross-field rules, an exclusive bound on a float, a regex whose flags or
-anchoring the `pattern` attribute would silently reinterpret, a
-`z.iso.datetime()` no `datetime-local` control can ever satisfy — are returned
-in `dropped`. They still run on the server; you are told they do not run on
-the client. Outside production `formFields` also logs the list once per schema
-with `console.warn`, so it is seen without anyone remembering to read it.
+control. What that is depends on the control: `''` for a text field, `false` for
+an unchecked checkbox, and nothing at all for a number, a `z.coerce.bigint()`, a
+file, a choice, or an unchecked `z.stringbool()` box — an empty numeric field is
+not 0 (nor 0n), an unfilled file
+input is not the zero-byte file the browser sends, and neither a radio group
+with nothing selected nor a `<select>` left on a `value=""` placeholder has
+chosen anything. The attribute is emitted only when the schema rejects that
+empty submission, and `parseForm` hands the schema exactly what the derivation
+probed, so the two sides always agree: a plain `z.boolean()` checkbox is not
+required, while `z.literal(true, '…')` — a consent box — is, and shows zod's own
+wording; `z.enum([…])` is required, while `z.enum([…]).optional()` can be left
+on its placeholder.
+
+**Checks the client skips are reported.** What HTML cannot express — a
+`refine` on the schema as a whole, cross-field rules, an exclusive bound on a
+float, a regex whose flags or anchoring the `pattern` attribute would silently
+reinterpret, several regexes on one string (the attribute holds one), a regex on
+a control that ignores `pattern` such as `type="date"`, a `.mime()` that
+`accept` only suggests to the file picker, a `z.iso.datetime()` no
+`datetime-local` control can ever satisfy,
+a leaf whose constraints could not be read at all because a `.transform()` or a
+`z.custom()` left nothing to read — are returned in `dropped`. They still run
+on the server; you are told they do not run on the client. Outside production
+`formFields` also logs the list once per schema with `console.warn`, so it is
+seen without anyone remembering to read it. One kind is not reported yet: a
+`refine` on a single field, a nested object, or a row (see
+[What it does not do yet](#what-it-does-not-do-yet)).
+
+**The control follows the format, whatever is stacked on it.** `z.email()`
+derives `type="email"` and `z.iso.date()` `type="date"`, and a check added on
+top — `.regex()`, `.startsWith()`, `.lowercase()` — does not turn either into a
+text input. The check itself becomes the `pattern` when it is the only regex
+the browser would have to run (`z.url().lowercase()`), and is listed in
+`dropped` otherwise (`z.email().regex(…)`, whose format already carries one).
 
 **A schema this package cannot express fails at derive time.** `z.record`,
 tuples, a repeat nested inside a repeat, nullable objects, keys containing
 `.` or brackets — `formFields` throws with the reason, instead of deriving a
-form that would silently misparse what the person typed.
+form that would silently misparse what the person typed. So does a leaf no
+control could ever satisfy, because every value arrives as a string:
+`z.number()` (use `z.coerce.number()`), `z.literal(1)`, `z.date()`,
+`z.bigint()`. So does a checkbox that could never submit `false`:
+`z.stringbool().default(true)`, since an unchecked box submits nothing and the
+default reads nothing as `true`. A form that can never validate, or that
+silently discards what the person did, is a mistake to report, not a check to
+drop. A schema that coerces reads strings and is kept, so
+`z.coerce.date()` and `z.coerce.bigint()` derive as text inputs.
 
 **A missing name is loud.** If the schema has a field that never arrived in the
 FormData, `parseForm` throws instead of reporting it as a validation failure.
 Forgetting to spread `input` is a wiring mistake, not something the person
-filling in the form did. The one exception is an enum field: a radio group
-with nothing selected submits no entry at all — a state the person can reach —
-so it comes back as that field's validation error instead.
-
-**Native validation survives without JavaScript.** `noValidate` is applied
-from JavaScript on mount, never rendered into the markup. With scripts
-disabled or not yet loaded, the browser's own checks stay on; once the hook is
-live, it takes over the message path and the server stays the arbiter.
-
-**Secrets are never echoed.** `parseForm` returns the submitted values so a
-retry without JavaScript keeps the input. Fields marked as passwords are
-excluded automatically, and typed as `password` in the markup:
+filling in the form did. The exceptions are the controls that submit no entry
+at all when left alone — a state the person can reach: a radio group with
+nothing selected reaches the schema as no value, the same as a `<select>` on
+its placeholder (a validation error unless the enum accepts `undefined`), an
+unchecked checkbox as `false` (or, under `z.stringbool()`, as no value), and a
+checkbox group with nothing checked as `[]`. A forgotten spread on one of those is not caught either.
+
+**A failing submission stops in the browser, with JavaScript or without.**
+`noValidate` is applied from JavaScript on mount, never rendered into the
+markup, so with scripts disabled or not yet loaded the browser's own checks
+stay on. Once the hook is live it runs the same check on every submit, in
+zod's wording: every field, the ones nobody touched included, and the
+cross-field [rules](#checks-html-has-no-attribute-for). A failure stops the submission, shows each failed field's message, and
+moves focus to the first failed field on the page. When that field is one the
+hook has no message for — a control outside the schema, say a `required`
+consent box the server never reads — the browser reports it with its own
+bubble (`reportValidity()`), as it would without the hook. A submit button marked
+`formNoValidate` skips the check, as it skips the browser's. The server stays
+the arbiter: what passes still goes to it, and the checks in `dropped` run
+there alone.
+
+**A retry keeps what was submitted.** `parseForm` returns the submitted
+values, and they render as the controls' defaults, which is also what React's
+reset after the action restores. A `<select>` — `multiple` too — is no
+exception, although React applies a select's `defaultValue` only when it
+mounts: `useForm` writes each response's echo into the options'
+`defaultSelected` itself, so the select needs no `key` to remount it.
+
+**Secrets are never echoed.** Fields marked as passwords are left out of
+those values automatically, and typed as `password` in the markup:
 
 ```ts
 z.string().min(8).meta({ input: 'password' }); // zod
+z.string().check(z.minLength(8), z.meta({ input: 'password' })); // zod/mini
 globalRegistry.add(password, { input: 'password' }); // zod or zod/mini
 ```
 
-`.meta()` is shorthand for the registry and is not available on `zod/mini`;
-the registry route works with either.
+`.meta()` is shorthand for the registry, and `zod/mini` has no such method —
+pass `z.meta()` to `.check()` there. The registry route works with either.
 
 **`isDirty` costs one boolean.** `form.isDirty` compares each control — text,
 checkbox, `<select>`, a `HiddenValue` — with the value it was rendered with,
 read straight from the DOM; adding or removing a row counts too. It flips at
-most twice, so it never becomes a per-keystroke re-render.
+most twice, so it never becomes a per-keystroke re-render. A reset — React's
+own after every form action included — is read from the DOM once it is
+through, so it takes the flag back to `false` for everything the browser
+restores. A `HiddenValue` is not among those: its value is the caller's
+state, which React writes straight back, so a form holding an edited one
+stays dirty until that state is reset too.
 
 ## Nested objects and repeated rows
 
@@ -200,6 +335,26 @@ buttons disappear at exactly the bounds the server enforces. For an array of
 scalars (`z.array(z.string())`) the item has a single unnamed field:
 `row.field()`.
 
+`items.error` is the server's message about the array itself — too few or too
+many rows for its `.min()` / `.max()` — which no row's field carries, so no
+control can take focus for it. Like `form.formError`, it comes with the props
+for the element that shows it: `items.errorProps`, an `id` and
+`tabIndex={-1}`. Without them a submit that failed only on the array moves
+focus nowhere, and a screen reader says nothing about it. Put it above the
+rows: it then takes focus even when a row failed too, and Tab moves on into
+the rows. Below them, the first failed row takes focus instead.
+
+```tsx
+<form {...form.props} action={formAction}>
+  {items.error !== undefined && <p {...items.errorProps}>{items.error}</p>}
+  {items.rows.map((row) => (
+    <div key={row.key}>{/* … */}</div>
+  ))}
+</form>
+```
+
+`row.index` is the row's current position.
+
 `parseForm` reports how many rows arrived in `state.rows`, so a retry without
 JavaScript rebuilds the same number of rows. Row counts are read from the
 submitted names but never trusted beyond the schema's `.max()` (or a hard
@@ -207,7 +362,56 @@ ceiling), so a forged index cannot make the server allocate.
 
 A nested object behind `.optional()` / `.default()` keeps its fields — the
 wrapper is peeled the same way on both sides. A repeat nested inside a repeat
-has no unambiguous name; it is a compile error and a derive-time throw.
+has no unambiguous name; the types let it through, but `formFields` and
+`parseForm` throw on it.
+
+## Radio groups
+
+Do not spread an enum's `input` onto a hand-written radio: once `state`
+carries `values`, `input` holds the echoed choice as `defaultValue`, which
+collides with each radio's own `value` and restores no selection. Take `name`
+and `required` from it and restore the choice per option (`@k8ordo/ui`'s
+`Radio` and `RadioCard` take the spread instead — see
+[Working with @k8ordo/ui](#working-with-k8ordoui)):
+
+```tsx
+const plan = form.field('plan');
+
+<input
+  defaultChecked={state.values?.plan === option}
+  name={plan.input.name}
+  required={plan.input.required}
+  type="radio"
+  value={option}
+/>;
+```
+
+## Checkboxes that submit a string
+
+`z.boolean()` reads a checkbox as checked or not, whatever it submits.
+`z.stringbool()` reads what it submits: its `value` when checked, and nothing
+when not. `input.value` is the schema's own spelling of `true` — `"true"`, or
+the first of `truthy` when one is given — so the box submits a string the
+schema reads back, never the browser's default `on`.
+
+That is the shape a boolean takes in a GET filter form derived from an
+`@k8ordo/state` url schema, where a boolean has to be `z.stringbool()`: the
+box submits the same string `update()` writes for `true`, so the URL the form
+lands on and the one state writes agree. An unchecked box submits nothing,
+which reaches the schema as `undefined`: `.default(false)` or `.optional()`
+accepts it, and a bare `z.stringbool()` makes the box `required`.
+`.default(true)` is refused at derive time — nothing would read as `true`, so
+unchecking the box could never submit `false`.
+
+Only these fields carry `value` in their type. `formFields` names their paths
+in the third type argument of `FormFields` (`FormFields<FieldPath, ArrayPath,
+StringCheckboxPath>`), and `field()` types `input` as `StringCheckboxInput` for
+them and as `FieldInput`, with no `value`, for every other field — so the other
+fields spread onto a component that takes `value` only when it is controlled.
+A `FormFields` type written by hand can leave the third argument out: it still
+takes the derived fields, and the box still submits its `value`, but
+`input.value` no longer compiles. The same holds for a box inside repeated
+rows, which `row.field()` never types with `value`.
 
 ## Checkbox groups
 
@@ -221,7 +425,15 @@ const tags = form.field('tags');
 
 {
   ['a', 'b', 'c'].map((option) => (
-    <input key={option} type="checkbox" value={option} {...tags.input} />
+    <input
+      defaultChecked={
+        Array.isArray(state.values?.tags) && state.values.tags.includes(option)
+      }
+      key={option}
+      name={tags.input.name}
+      type="checkbox"
+      value={option}
+    />
   ));
 }
 ```
@@ -230,17 +442,29 @@ const tags = form.field('tags');
 `[]`, never a wiring error. The `.min(2)` cannot become an HTML attribute (on
 a group, `required` would mean "check every box"), so it is reported in
 `dropped`; declare `minChecked('tags', 2, '…')` to run the same bound in the
-browser. On a no-JS retry the group echoes as an array, so restoring is:
+browser. After a submission `state.values.tags` holds what was checked as an
+array — `['a']` for one box, `[]` for none — and `tags.input` carries only the
+`name`, so each box restores itself from that array.
 
-```tsx
-defaultChecked={Array.isArray(state.values?.tags) && state.values.tags.includes(option)}
-```
+## Files
+
+`z.file()` derives `type="file"`, and `.mime([…])` becomes `accept`. `accept`
+only decides what the file picker offers first — the person can still pick any
+file, and the browser never checks the type — so the check runs on the server
+and is listed in `dropped`. An unfilled file input still submits — an unnamed,
+zero-byte File, which `z.file()` would otherwise accept as a real upload — so it
+reaches the schema as nothing entered and `required` keeps meaning what it says.
+
+Size bounds (`.min()` / `.max()` on a file) are byte counts, and no HTML
+attribute carries them: they run on the server and are reported in `dropped`.
+A file is never echoed into `state.values`, because no browser lets a value be
+put back into a file control.
 
 ## Paths are checked at compile time
 
-`formFields` derives the set of valid paths from the schema type, so a typo is
-a build error rather than something you find by clicking. Rules are typed
-against the same paths.
+`formFields` derives the set of valid paths from the schema type, so a typo in
+`form.field()` or `form.array()` is a build error rather than something you
+find by clicking. Rules are typed against the same paths.
 
 ```tsx
 form.field('titel'); // error: not a field in the schema
@@ -250,6 +474,9 @@ form.array('tags'); // error: a checkbox group is a field
 defineForm(schema, [sameAs('confrim', 'password', '…')]); // error: typo
 ```
 
+A row's `row.field(key)` is the exception: the key is a plain string, and a
+typo in it throws when the row renders.
+
 ## Checks HTML has no attribute for
 
 Password confirmation, "tick at least two", "required only when rejected" —
@@ -274,18 +501,52 @@ implementation to drift from the first.
 
 On the client a breach is applied with `setCustomValidity`, so it is
 indistinguishable from a built-in check — `:user-invalid` matches and the
-message arrives through the same path as every other one.
+message arrives through the same path as every other one. When several rules
+break the same field, both sides show the one declared first.
+
+Available: `sameAs(field, other, message)`, `minChecked(field, min, message)`,
+and `requiredWhen(field, when, equals, message)` —
+`requiredWhen('reason', 'status', 'rejected', '…')` requires `reason` while
+`status` is `'rejected'`. Anything else stays a `.refine()` and runs on the
+server only. A `refine` on the schema as a whole is listed in `dropped`; one on
+a single field, a nested object, or a row is not yet.
+
+### A message that follows the request
+
+`message` takes a function as well as a string, the way zod takes
+`{ error: () => … }`: it is called when the rule is reported, not where the
+rule is declared. `formFields` calls it as it derives the fields — the client
+cannot run a function sent from the server, so the rules cross already
+worded — and `parseForm` calls it when the rule breaks. A definition at module
+scope therefore reports in whichever locale is current in the request that
+reads it:
+
+```ts
+// src/lib/signup-form.ts
+import { mismatch, pickAtLeast } from '../messages/signup'; // @k8ordo/i18n
 
-Available: `sameAs`, `minChecked`, `requiredWhen`. Anything else stays a
-`.refine()`, runs on the server, and is listed in `dropped`.
+export const signup = defineForm(schema, [
+  sameAs('confirm', 'password', mismatch),
+  minChecked('topics', 2, () => pickAtLeast(2)),
+]);
+```
+
+Call `formFields` during the render for this, the same as for zod's function
+messages.
 
 ## Asking the server about one field
 
 Whether a name is already taken is something only the server knows. `useAsyncCheck`
 runs on blur, keeps the newest answer when replies arrive out of order, and
 applies the result with `setCustomValidity` — so the answer shows up through the
-same path as every other message. A blur that leaves the value unchanged does
-not ask again, and emptying the field clears the last answer with it.
+same path as every other message. Leaving the field while it still holds the
+value the last answer was about does not ask again — a blur while a check is
+still in flight does — and emptying the field and leaving it clears the last
+answer.
+
+`check` receives the field's value and resolves to the message to show, or to
+`undefined` when the value is fine. A rejected promise applies no verdict
+either way; the server still checks the submission.
 
 ```tsx
 const slug = form.field('slug');
@@ -308,22 +569,32 @@ into React state and pushing it back out at submit:
 <HiddenValue name="body" value={body} />
 ```
 
-This is all `Controller` does in react-hook-form, and it is the one place that
-binding silently breaks there. Here the value is in the form, so it submits
-whether or not anything else works. `HiddenValue` is a component rather than a
-props helper because React updates a controlled value without any DOM event —
-the component announces each change with one, so cross-field rules and
+The value is an ordinary form entry, so it goes out with the rest of the
+FormData and needs no submit-time code. `HiddenValue` is a component rather
+than a props helper because React updates a controlled value without any DOM
+event — the component announces each change with one, so cross-field rules and
 `isDirty` hear it like any keystroke.
 
 ## Multi-step forms
 
 Keep every step mounted and hide the ones you are not on. The values stay in
-the DOM, so moving between steps costs nothing and losing a step is impossible:
+the DOM, so moving between steps costs nothing and losing a step is impossible.
+Hide steps only once hydrated — a step hidden in the server's HTML is out of
+reach without JavaScript — and, once hydrated, render the submit button only on
+the last step: Enter in a text field can click the form's first submit button
+even when it is hidden, which would send the whole form from an earlier step.
 
 ```tsx
-<div hidden={step !== 1} ref={stepOne}>
+const subscribe = () => () => {};
+const hydrated = useSyncExternalStore(subscribe, () => true, () => false);
+
+<fieldset hidden={hydrated && step !== 0} ref={stepOne}>
   {/* … */}
-</div>
+</fieldset>
+<fieldset hidden={hydrated && step !== 1}>
+  {/* … */}
+  {(!hydrated || step === 1) && <button type="submit">送信</button>}
+</fieldset>
 ```
 
 Validate one step before advancing by checking only the controls inside that
@@ -336,19 +607,45 @@ const stepIsValid = [
 ].every((control) => (control as HTMLInputElement).checkValidity());
 ```
 
+After a failed submit, `useForm` moves focus to the first failed field on the
+page, but a control inside a hidden step cannot take focus. When a new state
+arrives, switch during render to the earliest step holding a key of
+`state.errors`, so the field is visible by the time focus moves. The check on
+submit covers the hidden steps too, and stops the submission for a failure
+there without being able to show it — checking each step before advancing is
+what keeps the earlier steps from failing at the end.
+
 Without JavaScript this degrades to one long form that submits in a single
 request — which is the correct behaviour, not a broken one.
 
 ## What it does not do yet
 
+- Several files in one control. `z.array(z.file())` derives repeated
+  single-file rows rather than one `multiple` input, and `parseForm` reads one
+  file per name.
+- Constraints that sit behind a `.transform()`, or a `.pipe()` whose output
+  JSON Schema cannot describe. The schema no longer says what the control
+  submits, so the field derives as a bare text input and is listed in
+  `dropped`; every check still runs on the server.
+- A `z.custom()` that rejects the strings a text control submits. Nothing about
+  it is readable, so it cannot be refused at derive time the way `z.date()` is
+  — it derives as a text input, is listed in `dropped`, and fails on the server.
+- Reporting a `.refine()` / `.superRefine()` on a single field, on a nested
+  object, or on a row. Of `.refine()` / `.superRefine()` checks, `dropped`
+  counts only the ones on the schema as a whole; the others run on the server
+  without a word on the client.
+- Rules on fields inside repeated rows. Rule field names are typed against the
+  schema's field paths, and a row's fields are not among them.
 - Input masking. Rewriting `el.value` on input works with the DOM as the source
   of truth, but managing the caret is a separate problem from wiring a form.
 
 ## Working with @k8ordo/ui
 
-`@k8ordo/form` does not depend on `@k8ordo/ui`. Attributes go to the input;
-`FormControl` gets only what it uses, and generates the `id` and `aria-*`
-links itself.
+`@k8ordo/form` does not depend on `@k8ordo/ui`; the fields in `@k8ordo/ui`
+take what `formFields` derives as it is. Spread `input` onto the field after
+`FormControl`'s props. `FormControl` gets only what it uses — the label, the
+error, `invalid`, `required` — and generates the `id` and `aria-*` links
+itself.
 
 ```tsx
 const title = form.field('title');
@@ -361,3 +658,104 @@ const title = form.field('title');
   renderInput={(props) => <TextField {...props} {...title.input} />}
 />;
 ```
+
+Nothing in `input` has to be taken out first: `TextField` renders the date and
+time types as well as the text ones, `PasswordInput` keeps its show/hide toggle
+under a spread `type`, `Textarea` drops the `type` a `<textarea>` does not
+have, and `NumberField` and `Slider` take string bounds, `step="any"`, and the
+echoed `defaultValue`, which is a string whichever field it belongs to.
+Uncontrolled fields keep their value in the DOM, so a reset — React's after
+each action included — restores the echo, `isDirty` reads them, and a value a
+component changes in code — a stepper, a chosen option, a removed file —
+arrives as an `input` event, the way typing does.
+
+| Schema                                            | Component                                            | What to pass besides `{...props} {...input}`              |
+| ------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------- |
+| `z.string()`, `z.email()`, `z.url()`, `z.iso.*()` | `TextField`, `Textarea`                              | —                                                         |
+| a password                                        | `PasswordInput`                                      | —                                                         |
+| `z.coerce.number()`                               | `NumberField`, `Slider`                              | —                                                         |
+| `z.enum([…])`                                     | `Select`, `Radio`, `RadioCard`                       | `options`; `labelAs="legend"` on `FormControl` for radios |
+| `z.boolean()`, `z.literal(true)`                  | `Checkbox`, `Switch`                                 | `label`, and no `{...props}`: they need no `FormControl`  |
+| `z.array(z.enum([…]))`                            | `CheckboxGroup.Root`, `CheckboxCard`, `Autocomplete` | `defaultValue` from `state.values`                        |
+| `z.file()`                                        | `FileField.Root`                                     | a `FileField.Trigger` and `FileField.ItemList`            |
+
+**Radios take the spread.** The advice under [Radio groups](#radio-groups) is
+about a hand-written `<input type="radio">`. `Radio` and `RadioCard` read an
+enum's `input` the other way round: `defaultValue` is the selected option and
+`required` reaches every radio.
+
+**A `z.stringbool()` box is the exception.** A spread `value` does not reach
+`Checkbox`'s input, so a `z.stringbool()` box drawn with it submits the
+browser's `on` — which the default `z.stringbool()` reads as `true`, but a
+custom `truthy`, and the URL state writes, do not share. Render a plain
+`<input {...field.input} />` there.
+
+**A `Select` needs a placeholder for `required` to mean anything.** Put
+`{ value: '', label: '…' }` first in `options`; a `<select>` without an empty
+option always has a choice selected.
+
+**A checkbox group echoes as an array.** `input` carries only the `name`, so
+pass what was checked back as `defaultValue`:
+
+```tsx
+const tags = form.field('tags');
+const checked = state.values?.tags;
+
+<FormControl
+  errorText={tags.error}
+  invalid={tags.invalid}
+  label="タグ"
+  labelAs="legend"
+  renderInput={(props) => (
+    <CheckboxCard
+      {...props}
+      {...tags.input}
+      defaultValue={Array.isArray(checked) ? checked : []}
+      options={options}
+    />
+  )}
+/>;
+```
+
+`minChecked` reaches `Autocomplete` as well as the checkboxes: it submits
+through a hidden `<select multiple>` that is present even with nothing
+selected, so the rule has an element to mark, and focus sent to it after a
+failure goes on to the text input.
+
+**`NumberField` checks its own range.** It renders `type="text"` so it can
+format and step the value, and the browser does not check `min` and `max` on
+a text input. `NumberField` reports an out-of-range value with
+`setCustomValidity` instead, which `useForm` shows like any other message —
+but in `@k8ordo/ui`'s wording (`numberFieldRangeUnderflow` /
+`numberFieldRangeOverflow`), not zod's, the one place the client's text is not
+zod's own. Leaving the field clamps the value into range, so the message shows
+only while typing. `.int()` and `.multipleOf()` set the precision the field
+rounds to; a plain `z.coerce.number()` derives `step="any"`, which is not
+rounded. Without JavaScript nothing checks the range before the server does;
+a `TextField` given the derived `type="number"` keeps the browser's own
+check, and its wording.
+
+**A `Textarea` has no `pattern`.** A regex on a field drawn as a `Textarea`
+reaches the markup, but a `<textarea>` ignores it: the check runs on the server
+only, and `dropped` cannot list it, since the derivation does not know which
+element renders the field.
+
+**`FileField`** submits what `FileField.ItemList` shows: removing a file there
+removes it from the input, and a reset empties the list with it.
+
+The form-level message fits `Alert`, which passes `id` and `tabIndex` through
+to its element. Its `role="alert"` means a screen reader may read the message
+twice — once when it appears, once when focus lands on it — the same trade an
+error summary with an alert role makes.
+
+```tsx
+{
+  form.formError.message !== undefined && (
+    <Alert
+      {...form.formError.props}
+      message={form.formError.message}
+      tone="error"
+    />
+  );
+}
+```