formstand 0.12.0 → 0.14.0

package/README.md

@@ -4,13 +4,14 @@
 
 Zod-schema-first form state for React 19, backed by zustand.
 
-**[Documentation](https://scrumrot.github.io/formstand/)** · **[Live playground](https://scrumrot.github.io/formstand/examples/)** · **[API reference](https://scrumrot.github.io/formstand/api/)**
+**[Documentation](https://scrumrot.github.io/formstand/documentation/)** · **[Live playground](https://scrumrot.github.io/formstand/examples/)** · **[CLI](https://scrumrot.github.io/formstand/documentation/cli/)** · **[API reference](https://scrumrot.github.io/formstand/documentation/api/)**
 
-- **Typed paths** — `useField(form, "users.0.email")` infers the value type from the schema.
-- **Per-field subscriptions** — fields re-render only when their own slice changes.
-- **Sync and async validation** — with race-handling for async refines.
-- **Field arrays** with stable IDs that survive reorders.
-- **Bound input components** for the common cases.
+- **Typed paths**: `useField(form, "users.0.email")` infers the value type from the schema. Writes are typed too, so a typo'd path is a compile error.
+- **Per-field subscriptions**: fields re-render only when their own slice changes, and validation parses one field's subschema per keystroke instead of the whole form.
+- **Two error channels**: validation owns one, your app owns the other, so a background pass cannot wipe a server message.
+- **Field arrays** with stable IDs that survive reorders, inserts, and removes.
+- **Bound input components** with the accessibility wiring already done.
+- **A generator**: [`formstand-cli`](https://scrumrot.github.io/formstand/documentation/cli/) writes the whole component from your schema, for six UI kits.
 
 ## Install
 
@@ -24,12 +25,7 @@ Peer-dep ranges: `zod ^4.2`, `zustand ^5.0`, `react ^19.0`.
 
 ```tsx
 import { z } from "zod";
-import {
-  TextField,
-  NumberField,
-  useForm,
-  useIsSubmitting,
-} from "formstand";
+import { TextField, NumberField, useForm, useIsSubmitting } from "formstand";
 
 const schema = z.object({
   name: z.string().min(2, "min 2 chars"),
@@ -44,11 +40,7 @@ const SignUpForm = () => {
   const submitting = useIsSubmitting(form);
 
   return (
-    <form
-      onSubmit={form.handleSubmit((data) => {
-        console.log("submit", data);
-      })}
-    >
+    <form onSubmit={form.handleSubmit((data) => console.log("submit", data))}>
       <TextField form={form} path="name" label="Name" />
       <NumberField form={form} path="age" label="Age" />
       <button type="submit" disabled={submitting}>
@@ -59,382 +51,94 @@ const SignUpForm = () => {
 };
 ```
 
-## Core API
+`handleSubmit` calls `preventDefault` for you and only runs your handler with parsed,
+`z.output`-typed data. The bound components render the label, wire the accessibility
+attributes, and show the field's error.
 
-### `createForm(schema, options)`
-
-Creates a form instance. React users typically use `useForm` instead, which wraps this.
-
-```ts
-const form = createForm(schema, {
-  initialValues,
-  mode: "onBlur",          // "onChange" | "onBlur" | "onSubmit"
-  reValidateMode: "onChange", // mode used after the first submit attempt
-  validateOnMount: false,  // run a validation pass at creation (see below)
-});
-```
-
-### `Form<TSchema>` methods
-
-| Method | Notes |
-|---|---|
-| `getState()` / `subscribe(listener)` | the underlying zustand store |
-| `setValue(path, value)` | updates one field. Dirtiness is derived, not stored: a field reads as dirty while its value differs structurally from `initialValues` at that path (arrays/plain objects compare deep, Dates by timestamp, `Object.is` otherwise) |
-| `setValues(next)` | replace the entire values object; server errors release only where a value slice actually changed |
-| `setTouched(path, touched?)` | marks a path touched |
-| `setError(path, errors)` / `setErrors(map)` / `clearErrors(path?)` | the app-owned **server error channel** (`state.serverErrors`) — validation never touches it; `setError` accepts a single string or an array; `clearErrors(path)` clears both channels at the path and its descendants (`clearErrors("")` clears just the root entry; `clearErrors()` clears everything); `setErrors` replaces the whole server channel |
-| `setMode` / `setReValidateMode` | switch modes at runtime |
-| `reset(nextInitial?, options?)` | reset to initial; optional partial overrides (shallow-merged for record roots, replaced wholesale otherwise) and `{ keepErrors, keepTouched, keepSubmitCount }` (no `keepDirty` — dirtiness derives from values vs initial, and reset makes them equal) |
-| `resetField(path)` | reset one field to its initial value, clearing its (and descendants') error/touched state (dirtiness clears by definition — the value now equals initial); a path with no initial counterpart (an appended array row) keeps its value and only clears field state |
-| `adoptValues(values)` | mid-session rebase: replaces `values` + `initialValues` and clears `errors` and in-flight validation flags (`isValidating`/`isValidatingForm` — the rebase disowns in-flight passes), but **preserves** interaction state (`touched`, `submitCount`, `isSubmitting`, `mode`). Use `reset()` for a full wipe |
-| `updateState(updater)` | atomic multi-field patch; `errors` is derived from `schemaErrors`/`serverErrors`, so patch the channels — the patch type omits `errors` entirely, and a plain-JS `errors` patch is warned about and ignored |
-| `validate()` / `validateField(path)` / `validateFields(paths)` | sync validation; on an async schema all three transparently start the async pass instead and return `{ kind: "pending", promise }` |
-| `validateAsync()` / `validateFieldAsync(path)` / `validateFieldsAsync(paths)` | async; supports `async .refine` |
-| `submit(onValid, onInvalid?, { force? })` → `Promise<SubmitResult>` | full submit flow; resolves `{ kind: "valid", data }`, `{ kind: "invalid", errors }` (errored fields are also marked touched), `{ kind: "skipped" }` when another submit is in flight, or `{ kind: "error", error }` when `onValid` throws/rejects — submit resolves instead of rejecting, so `handleSubmit` never produces an unhandled rejection from an `onValid` throw |
-| `handleSubmit(onValid, onInvalid?)(event?)` | event handler wrapper that calls `preventDefault` |
-| `getField(path)` | typed one-shot value read |
-| `getFieldState(path)` | typed one-shot read of a field's full slice (value/error/touched/dirty/isValidating) |
-| `watchField` / `watchValue` / `watchValues` | subscriptions; see below |
-| `diff()` / `dirtyFields()` | PATCH-style helpers, derived by comparing `values` against `initialValues`: minimal divergent paths (objects recurse to the changed leaves; arrays report their base path). Reverting a field drops it |
-| `snapshot()` / `restore(snap)` | full state capture/restore for undo/rollback |
-| `arrayPush` / `arrayRemove` / `arrayInsert` / `arrayMove` / `arraySwap` | array ops with meta-key re-keying (errors/touched/server verdicts follow their rows); dirtiness is derived, so push + remove reads clean again |
-
-### Validation modes
-
-- `mode: "onBlur"` (default): validate on blur and on submit.
-- `mode: "onChange"`: validate on every change and on submit (not on blur).
-- `mode: "onSubmit"`: validate only on submit.
-- `mode: "onTouched"`: validate on blur always; on change only once the field has been touched.
-- `mode: "all"`: validate on every change and blur.
-- `reValidateMode` (default `"onChange"`) kicks in once `submitCount > 0`.
-
-For schemas with `async .refine`, sync `validate()` / `validateField()` / `validateFields()` don't throw: they detect the async requirement, start the async pass themselves, and hand you the in-flight work as `{ kind: "pending", promise }` (never a bare truthy `Promise` — a boolean gate can't silently pass). The requirement is also remembered per scope, so later sync calls skip straight to the async pass instead of re-paying a doomed sync parse per keystroke. If the *field being validated* is itself sync, `validateField` still settles synchronously even when other fields carry async refines — field validation parses just that field's subschema when it can (see below).
-
-## React hooks
-
-### `useForm(schema, options)`
-
-Lazy-creates a `Form<TSchema>` and holds it for the component's lifetime. Stable reference across renders.
-
-### `useField(form, path, options?)`
-
-Subscribes to one field's slice (value/error/touched/dirty/isValidating) and returns helpers:
-
-```ts
-const name = useField(form, "name");
-name.value;      // typed via FieldPath
-name.error;      // readonly string[] | undefined
-name.touched;
-name.dirty;
-name.isValidating;
-name.setValue(v);
-name.setTouched();
-name.setError("taken");  // or ["taken", "reserved"]
-name.clearError();
-name.validate();
-name.validateAsync();
-name.onBlur();
-```
-
-Options:
-
-```ts
-useField(form, "username", { debounceMs: 300 }); // debounces validation
-```
-
-Path can also be a selector:
-
-```ts
-useField(form, (state) => `users.${state.values.selectedIdx}.email`);
-```
-
-### `useFieldArray(form, path)`
-
-Array operations + stable IDs for React keys:
-
-```ts
-const users = useFieldArray<UserItem>(form, "users");
-users.fields.map((f, i) => (
-  <UserRow key={f.id} item={f.value} index={i} />
-));
-users.push({...});
-users.remove(i);
-users.move(from, to);
-users.swap(a, b);
-users.insert(i, item);
-users.error;   // array-level error (e.g. min(1))
-```
-
-`fields` IDs are shared per `(form, path)` — every hook on the same array sees
-the same ids. Array ops (hook-issued or imperative `form.arrayMove` etc.)
-record their exact index mapping and id derivation replays it, so even rows
-with equal values keep the right ids through ops; whole-array writes
-(`setValue`, `restore`) reconcile by item identity with a positional fallback,
-so editing a field keeps its row's `id` (the row updates instead of
-remounting). A genuinely new item gets a fresh `id`.
-
-### `useFormSelector(form, selector)` / `useFormSelectorShallow(form, selector)`
-
-Selector-style subscription. Use `useFormSelectorShallow` for selectors that return objects/arrays.
-
-> Formerly `useFormState` / `useFormStateShallow` — renamed because React DOM
-> ships its own (deprecated) `useFormState` and auto-imports regularly grabbed
-> the wrong one. The old names were removed in 0.4.0.
-
-### `useFormError(form)`
-
-Shortcut for the root-level error (errors at the `""` key from a schema-level `.refine`).
-
-### Flag hooks
-
-```ts
-useIsDirty(form);       // any field dirty
-useIsValid(form);       // no errors currently in the error map
-useIsSubmitting(form);
-useSubmitCount(form);
-```
-
-> **`useIsValid` reflects the error map, not a fresh validation.** It returns
-> `true` when no errors are currently recorded — covering both schema errors and
-> server errors set via `setError`. But the error map is empty until validation
-> runs, so a never-validated form reads as valid even if its initial values
-> would fail the schema. If you gate a submit button on `!useIsValid(form)`,
-> pass `validateOnMount: true` to `useForm`/`createForm` so the initial values
-> are checked up front. (`submit`/`handleSubmit` always re-validate regardless,
-> so an invalid form can't actually be submitted either way.) `validateOnMount`
-> surfaces errors for untouched fields immediately — gate error display on
-> `touched` if you don't want them shown before interaction.
-
-### Bound input components
-
-```tsx
-<TextField form={form} path="email" label="Email" type="email" />
-<NumberField form={form} path="age" label="Age" />
-<CheckboxField form={form} path="agree" label="I agree" />
-<SelectField form={form} path="theme" label="Theme" placeholder="Pick a theme"
-  options={[{ value: "light", label: "Light" }, { value: "dark", label: "Dark" }]} />
-```
-
-All bound components ship with accessibility wiring: `name={path}` (autofill,
-password managers, native form posts), `aria-invalid` while errored,
-`aria-describedby` pointing at the error message, and the error rendered with
-`role="alert"` so it's announced when it appears. Each also accepts a `ref`
-to the underlying `<input>`/`<select>`.
-
-`SelectField` stays controlled while the field value is `undefined` by rendering
-a disabled empty option (with your `placeholder` text, if given), so the blank
-state is visible instead of the browser silently showing the first option.
-
-`NumberField` renders a `type="text"` input with `inputMode="decimal"` and keeps
-the raw text while you type, so partial entries (`-`, `1.`, `1e`) survive instead
-of being coerced away by a controlled `<input type="number">`. Each keystroke
-that parses to a **finite** number is pushed to the form (whitespace counts as
-empty → `undefined`; `Infinity` is rejected), and the display snaps to the
-canonical value on blur. If something else writes the field while you're typing
-(`reset`, `adoptValues`, another component), the external value wins and the
-input updates immediately.
-
-Or roll your own with the prop helpers:
+Prefer your own markup? Every binding is also a plain function over a `useField` result:
 
 ```tsx
 <input {...textInputProps(useField(form, "name"))} />
-<input {...checkboxProps(useField(form, "agree"))} />
-<select {...selectProps(useField(form, "theme"))}>...</select>
-```
-
-`numberInputProps` is also exported as a stateless `<input type="number">` binding
-(native stepper + `step`), at the cost of the intermediate-entry behaviour above:
-
-```tsx
-<input {...numberInputProps(useField(form, "age"))} type="number" step="1" />
-```
-
-### Focus management
-
-`focusFirstError(errors, root?)` focuses the first control (in DOM order) whose
-`name` matches an errored path — the bound components set `name={path}` so this
-works out of the box. Wire it into the invalid-submit handler:
-
-```tsx
-<form onSubmit={form.handleSubmit(onValid, (errors) => focusFirstError(errors))}>
-```
-
-On a page with several forms, pass the form element (e.g. via a ref) as `root`
-so the search stays inside your form — without it the whole document is
-scanned, and a root-`""` error's first-control fallback refuses to guess
-between forms (it returns `false` when the document holds more than one
-`<form>`):
-
-```tsx
-<form ref={formRef} onSubmit={form.handleSubmit(onValid, (errors) => focusFirstError(errors, formRef.current ?? undefined))}>
-```
-
-It returns `true` only when a control actually received focus — disabled or
-hidden controls, controls inside a closed `<dialog>`, and controls that refuse
-focus (e.g. `display: none`) are passed over for the next match.
-
-For custom focus logic, every bound component also takes a `ref` to its input.
-
-## Sharing a form across components
-
-`useForm(schema, options)` creates a form bound to the calling component's lifetime. Calling `useForm` twice — even with the same schema — gives you **two independent forms with two independent stores**. The hook uses `useState(() => createForm(...))` under the hood, and `useState` is per-component-instance.
-
-To share one form between components, use one of these patterns:
-
-### 1. Lift the form up and pass it down as a prop
-
-```tsx
-const Parent = () => {
-  const form = useForm(schema, { initialValues });
-  return (
-    <>
-      <NameField form={form} />
-      <EmailField form={form} />
-    </>
-  );
-};
-```
-
-Each child takes `form: FieldFormApi` (or the typed `Form<typeof schema>`) and calls `useField(form, "...")` on it. Works for small trees; gets noisy if the tree is deep.
-
-### 2. `createFormContext` — no prop drilling, full typing
-
-```tsx
-import { createFormContext } from "formstand";
-
-const { Provider, useFormContext } = createFormContext<typeof schema>();
-
-const Parent = () => {
-  const form = useForm(schema, { initialValues });
-  return (
-    <Provider form={form}>
-      <NameField />
-      <EmailField />
-    </Provider>
-  );
-};
-
-// In NameField.tsx — no form prop:
-const NameField = () => {
-  const form = useFormContext();          // typed Form<typeof schema>
-  const name = useField(form, "name");
-  return <input {...textInputProps(name)} />;
-};
 ```
 
-The factory pattern (one `createFormContext` per form shape) preserves the schema's type information through the context. Children can `useField` directly without losing path inference.
+## Or generate the whole thing
 
-### 3. Module-scope `createForm` (rare)
+[`formstand-cli`](https://scrumrot.github.io/formstand/documentation/cli/) writes the
+component from a schema you already have. It is a dev dependency that produces plain
+code and adds nothing to your bundle.
 
-```ts
-// formStore.ts
-export const profileForm = createForm(schema, { initialValues });
-```
-
-Import and use anywhere. The form lives for the lifetime of the module — useful for single-instance "app-wide" forms (e.g., a global filter bar), bad for forms that should reset between page mounts.
-
-## Common pitfalls
-
-- **Object-returning selectors must use `useFormSelectorShallow`.** `useFormSelector(form, (s) => ({ values: s.values, errors: s.errors }))` returns a fresh object on every call; React's `useSyncExternalStore` will detect snapshot churn and bail with *"Maximum update depth exceeded"*. Use `useFormSelectorShallow` instead — it caches by shallow equality.
-- **Synchronous `validate` / `validateField` return `pending` on async schemas.** They start the async pass for you and return `{ kind: "pending", promise }` — check `result.kind` (or use the `*Async` variants directly) rather than assuming `valid`/`invalid`.
-- **`form.submit()` short-circuits when one is already in flight** — it resolves `{ kind: "skipped" }`. Pass `{ force: true }` as the third argument to bypass.
-- **`z.coerce.*` collapses typed paths.** Form values are typed as `z.input<Schema>`, and in zod v4 the input of `z.coerce.number()` is `unknown` — so `FieldPath`/`FieldValue` can't see through it and path inference degrades for those fields. Prefer keeping the field's input type honest (e.g. `z.string()` in the schema and parse in a `.transform`/`.pipe`, or use `NumberField`, which parses text to `number` for you) over `z.coerce`.
-- **The imperative write surface is typed.** `form.setValue("naem", "x")` and `form.setValue("age", "thirty")` are compile errors, as are `setTouched`/`setError`/`clearErrors`/`validateField(s)`/array ops with bad paths. Dynamic array paths still typecheck (`` `users.${i}.email` `` with `i: number` matches the template-literal path type); for a fully runtime-built string, cast: `form.setValue(path as FieldPath<z.input<typeof schema>>, value as never)`.
-
-## Path semantics
-
-Paths are dot-separated (`"users.0.email"`). How a segment is interpreted is
-decided by the **existing container**: arrays take numeric segments as indices,
-plain objects take any segment as a string key — so a `z.record` keyed `"0"`
-reads and writes the record key instead of silently becoming an array. Only
-when the container doesn't exist yet does the segment type pick what's created
-(numeric → array, otherwise object). Three limitations: keys containing `.`
-are not addressable; array writes beyond index 100 000 are refused (a typo'd
-index must not allocate gigabytes); and the typed `FieldPath` union stops at
-9 segments by default — the runtime walks any depth, and `createForm`'s
-type-level `pathDepth` option widens the union per form (a deliberate
-compile-time trade; see the [typed paths guide](https://scrumrot.github.io/formstand/guide/typed-paths)).
-
-## Subscriptions (non-React)
-
-```ts
-form.subscribe((state, prev) => { ... });                  // fires on every state change
-form.watchValues((values, prev) => { ... });               // only on values changes
-form.watchValue("users.0.email", (next, prev) => { ... }); // single path's value
-form.watchField("users.0.email", (snapshot) => { ... });   // value + error + touched + dirty + isValidating
-```
-
-All return an unsubscribe function.
-
-## Async validation
-
-```ts
-const schema = z.object({
-  username: z.string().refine(
-    async (v) => !(await isTaken(v)),
-    { message: "taken" },
-  ),
-});
-```
-
-- `form.submit` uses `safeParseAsync` internally, so async refines work transparently.
-- `form.validateFieldAsync(path)` parses **just that field's subschema** when the path is reachable through refinement-free objects/arrays — so an async username check doesn't fire when you validate an unrelated field. When a traversed level carries a refinement (cross-field rules), it falls back to a full-form parse and scopes the written errors to the path and its descendants.
-- `validateField("address")` also **sets and clears errors for descendant paths** (`address.city`, …), not just the exact key.
-- Per-path **sequence numbers** ensure stale "username was taken" results don't overwrite a newer "ok" result.
-- A **values-reference guard** drops the write if `values` mutated during the await (so `reset`/`adoptValues`/`setValue` during an in-flight validate doesn't corrupt the error map).
-
-For UI, prefer `useField(form, path, { debounceMs: 300 })` to throttle network traffic.
-
-## Server-side errors
-
-```ts
-form.handleSubmit(async (data) => {
-  const res = await api.create(data);
-  if (!res.ok) {
-    for (const err of res.errors) {
-      // setError's path is typed; a server-provided string needs a cast
-      form.setError(err.field as FieldPath<z.input<typeof schema>>, [err.message]);
-    }
-  }
-});
-```
-
-Errors live in two channels. `schemaErrors` is owned by validation: every pass rebuilds it (full passes wholesale, field-scoped passes splice their scope). `serverErrors` is owned by you: `setError`/`setErrors` write it and validation never reads or writes it — which is the entire preservation story. A background `validateAsync()` can't wipe a "username taken" message because it physically can't touch that channel; there are no marks or bookkeeping to get wrong. The `errors` map every hook reads is derived from both on each write: the schema's message wins at a key, server entries show where the schema is silent. The merge is order-independent — `setError` on a key the schema currently rejects stores the verdict (visible in `state.serverErrors`) behind the schema message, and if the schema later clears at that key without the value changing, the stored verdict resurfaces, since the value it judged is unchanged.
-
-A server error is released when:
-
-- the value on its spine changes (`setValue`/`resetField`/array op on the path, a descendant, or an ancestor — editing `address.street` releases a verdict on `address`; array ops release verdicts on the array itself while row-level entries follow their rows through re-indexing),
-- a `setValues` bulk write changes its value slice (entries on untouched fields survive),
-- a field-scoped validation (`validateField`/`validateFieldAsync`/`validateFields`) targets its path (`validateField("")` counts as a full pass and leaves the server channel alone, like `validate()`), or
-- you call `clearErrors` / `reset` / `adoptValues`.
-
-Note `submit` still proceeds when the schema is valid even if server errors are present (the server gets to re-judge); they simply remain in the merged map, so `useIsValid` stays `false` until the user edits the field.
-
-## Field arrays with nested arrays
-
-Both work — `arrayPush("users.0.tags", tag)` mutates the inner array; outer reorders correctly re-key meta for all nested paths. Inner row ids live per `(form, path)` and reconcile by value when the outer index re-seats a different item at the path — pass a `key` from the outer `fields` so each row's whole subtree moves with its item.
-
-## Optimistic UI
-
-```ts
-form.handleSubmit(async (data) => {
-  const snap = form.snapshot();
-  form.adoptValues(data); // optimistic: data becomes the new baseline
-  try {
-    const saved = await api.save(data);
-    form.adoptValues(saved); // confirm with server response
-  } catch (e) {
-    form.restore(snap); // rollback
-  }
-});
-```
+```bash
+npm install -D formstand-cli
+npx formstand-gen src/profileSchema.ts --ui mui --sections panel --columns 2 --out src/ProfileForm.tsx
+```
+
+You get typed `initialValues`, a bound control per field, sections for nested objects,
+`useFieldArray` blocks with add and remove buttons, and a wired submit. Point it at a
+TypeScript type instead (`--type Profile`) and it generates the zod schema too. `--ui`
+targets plain formstand components, Material UI 5 through 9, shadcn/ui, Chakra 3,
+Mantine 9, or Ant Design 6.
+
+Try it without installing anything in the
+[Schema builder](https://scrumrot.github.io/formstand/examples/#/schema-builder), which
+runs the real emitters in your browser.
+
+## How it works
+
+Your zod schema is the single source of truth. It defines the value types, the set of
+addressable paths, and the validation rules, and `useForm` builds a form whose entire
+state lives in one plain zustand store. Hooks subscribe to slices of that store, so a
+field re-renders only when its own slice changes. Because the store is ordinary zustand,
+everything works outside React too: read it, subscribe to it, or drive it imperatively.
+
+Errors live in two channels that cannot clobber each other. Validation owns
+`schemaErrors` and rebuilds it on every pass; your `setError` calls own `serverErrors`
+and validation never touches them. The map your UI reads is derived from both. That is
+why a background `validateAsync()` cannot wipe a "username already taken" message, and
+why the server verdict is released automatically when the user edits that field, with no
+`clearErrors` bookkeeping in your change handlers.
+
+Anything that can be derived is. Dirtiness is computed by comparing values against
+initial values rather than tracked as you write, so it cannot drift out of sync,
+`arrayPush` followed by `arrayRemove` reads clean again, and `diff()` gives you a
+PATCH-ready payload of exactly what changed.
+
+## The API, at a glance
+
+| Area | What's there | Docs |
+| --- | --- | --- |
+| Form instance | `createForm`, `setValue`/`setValues`, `reset`/`resetField`/`adoptValues`, `submit`/`handleSubmit`, `diff`/`dirtyFields`, `snapshot`/`restore`, array ops | [createForm & Form](https://scrumrot.github.io/formstand/documentation/api/) |
+| Hooks | `useForm`, `useField`, `useFieldArray`, `useVariantField`, `useFormSelector`, `useFormValues`, the flag hooks, `createFormContext`, `createFormHooks` | [Hooks](https://scrumrot.github.io/formstand/documentation/api/hooks) |
+| Components | `TextField`, `NumberField`, `DateField`, `CheckboxField`, `SelectField`, the prop builders, `useNumberInput`, `focusField`/`focusFirstError` | [Components & bindings](https://scrumrot.github.io/formstand/documentation/api/components) |
+| Validation | five modes plus `reValidateMode`, field-scoped passes, async refines with race handling, per-field `debounceMs` | [Validation](https://scrumrot.github.io/formstand/documentation/validation) |
+| Utilities | `parsePath`/`getAtPath`/`setAtPath`, `validateSync`/`validateAsync`, `persistForm`, and the full type list | [Utilities & types](https://scrumrot.github.io/formstand/documentation/api/utilities) |
+
+Coming from react-hook-form? The
+[migration guide](https://scrumrot.github.io/formstand/documentation/migrating-from-react-hook-form)
+maps `register`, `watch`, `setError`, `setFocus`, and `useFieldArray` onto their
+counterparts, and is honest about what has none.
+
+## Things that catch people out
+
+- **Object-returning selectors need `useFormSelectorShallow`.** A selector returning a
+  fresh object every call makes React bail with *"Maximum update depth exceeded"*.
+- **`useIsValid` reflects the error map, not a fresh parse.** A never-validated form
+  reads as valid. Pass `validateOnMount: true` if you gate a submit button on it.
+- **Sync `validate`/`validateField` return `{ kind: "pending" }` on async schemas.**
+  They start the async pass for you, so check `result.kind` rather than assuming.
+- **`z.coerce.*` collapses typed paths**, because in zod v4 its input type is `unknown`.
+  Keep the input type honest and parse in a `.transform`/`.pipe`, or use `NumberField`.
+- **Explicit type arguments are a compile error** on a schema-typed form. The value type
+  infers from the path; `useField<Values>(form, "email")` fails on purpose, with a
+  message telling you to drop it.
+
+Each of these is covered properly in the
+[documentation](https://scrumrot.github.io/formstand/documentation/).
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) — note the repo has three
-independent npm roots (`.`, `examples/`, `cli/`), and the root test suite
-needs `examples/` installed. Where the project is headed lives in
-[ROADMAP.md](./ROADMAP.md).
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Note the repo has three independent npm roots
+(`.`, `examples/`, `cli/`), and the root test suite needs `examples/` installed. Where
+the project is headed lives in [ROADMAP.md](./ROADMAP.md).
 
 ## License