@vtex/faststore 0.0.5 → 0.0.6

package/dist/docs/field.md

@@ -0,0 +1,317 @@
+# Field
+
+**Category:** layout
+**Purpose:** Composable anatomy for a form field — label, input, description, error, and validity feedback — that behaves standalone or binds to a react-hook-form field through a context contract.
+
+---
+
+## When to use
+
+- Any form field: a shipping-address line, a profile field, a checkout opt-in, a standalone search box.
+- Inside a bound Control (a matter component that seeds `FieldBinding` from an entity's data) when the
+  anatomy needs to be reordered, restyled, or have a part omitted, without a new component.
+- As the closed anatomy it already is today — `Field.Root` + `Field.Label` + `Field.Control` (+
+  `Field.Description` / `Field.Error`) with no binding above it — for any field a matter renders itself.
+
+## When NOT to use
+
+- A boolean field's control — use `Field.Checkbox` (drives the shipped `Checkbox` particle), not
+  `Field.Control` (renders a native `<input>`).
+- A field whose value is picked from a list — out of scope here; `FieldSelect` (in the select particle) is the bound
+  part for that, and the contract's `options` member is reserved for it.
+- A submit action or a whole fieldset's write — those are `FormSubmit`/the fieldset tasks, not this
+  particle.
+
+---
+
+## Composition
+
+`Field.Root` is the anatomy's entry point. The five other shipped parts, plus the new `Field.Checkbox`,
+are children (directly or nested) of it — none of them require `Field.Root` at the type level, but every
+shipped composition places them there for the label/control/error ARIA wiring Base UI owns.
+
+```
+Field.Root                    (providesContext: 'field')
+├── Field.Label                (requiresContext: 'field')
+├── Field.Control               (requiresContext: 'field')
+├── Field.Description           (requiresContext: 'field')
+├── Field.Error                 (requiresContext: 'field')
+├── Field.Validity              (requiresContext: 'field'; render-prop, reads Base UI's validity state)
+└── Field.Checkbox              (requiresContext: 'field'; new — wraps Checkbox.Root)
+```
+
+`providesContext`/`requiresContext` are the compiler's static check for a *schema-authored* composition —
+they say "some ancestor must provide `field`", not "`FieldBinding` is that ancestor". At runtime,
+`FieldBinding` is the only thing that ever supplies the context; `Field.Root` provides the *contract*
+value for its compiler declaration but pushes no React context of its own.
+
+Child order reflects authored order — an author reorders `Field.Label` and `Field.Control`, or places an
+icon between them, and the DOM follows. No part receives the field name as a prop; whatever an author
+composes inside a bound Control edits that Control's field, and there is no way to spell a different one.
+
+### The field contract (`FieldBinding` / `useField`)
+
+`FieldBinding` is a **code-level export, never catalogued** — it carries no DOM of its own and never
+appears in a schema. A bound Control (shipped per-entity by later tasks, e.g. a shipping-address street
+field) renders it internally, seeded from the entity's data:
+
+```tsx
+<FieldBinding name="shippingAddress.street" label="Street" defaultValue={address.street}>
+  <Field.Root>
+    <Field.Label />
+    <Field.Control />
+    <Field.Error />
+  </Field.Root>
+</FieldBinding>
+```
+
+Every part below a `FieldBinding` reads the contract via `useField()` and, when a react-hook-form
+`FormProvider` is also present, renders its **bound** behaviour (reads/writes through react-hook-form).
+With no contract, or a contract but no `FormProvider`, every part renders its plain, unbound behaviour —
+identical to a `Field.Root` composed with no binding at all. `useField()` returns `null` rather than
+throwing when no contract is present, because eight particles and four matters render `Field` parts with
+no contract today.
+
+The contract carries **no live value** — only `name` and static facts (`label`, `placeholder`,
+`defaultValue`, `rule`, `options`, and the input semantics). It never changes while the shopper types, so
+typing re-renders only the part subscribed to that value through react-hook-form, not every part under the
+binding.
+
+`defaultValue` is not adopted once and forgotten: the bound part re-seeds the field whenever it re-renders
+with a `defaultValue` that differs from the one already applied, provided react-hook-form reports the field
+clean. A field the shopper has typed into is left alone — a changed `defaultValue` reaching a dirty field is
+skipped, not queued, so it is picked up on a later render once the field becomes clean again.
+
+A bound part narrows the contract's `defaultValue` to its own value type before registering it —
+`useBoundField`'s `shape.normalise` (`TEXT_FIELD_VALUE` coerces a non-string to `''`, `BOOLEAN_FIELD_VALUE`
+runs it through `Boolean(...)`) — and that same narrowed value is also the dirty baseline react-hook-form
+compares against, never the raw seed.
+
+### The fieldset seam (`useFieldsetField` / `useFieldsetFieldNames` / `useNoAncestorFieldset`)
+
+`useFieldsetField(namespace, key)` always returns `${namespace}.${key}`, and registers that full name with
+the enclosing fieldset registry for as long as the caller is mounted. With no registry above the caller,
+that registration is a no-op — it returns the joined name and throws nothing. With a registry above that
+declares a **different** namespace, the call **throws during render** instead of registering: the message
+names both the registry's own namespace and the full name the call was refused under, so it is the control
+that asked for the wrong namespace whose render fails first. That throw is uncaught — nothing in this
+repository installs an `ErrorBoundary` — so it unwinds the whole render past the fieldset: a sibling
+composed after the offending control never reaches its own render either, and the subtree comes back
+blank. Naming the offender in the message is what tells a reader which control to fix; it does not confine
+the failure to that control alone. A bound Control calls it to tell its fieldset which field name it
+mounted, so the fieldset can later submit exactly the fields on screen.
+
+A fieldset builds the registry it provides in one of two ways. `useFieldsetFieldNames(namespace)` is the
+built-in path: it returns `{ registry, getFieldNames }`. `registry.registerFieldName` refcounts per name —
+two callers of one name, however each arrived, collapse to one entry that is released only once the last
+holder releases, and the release function it hands back is at-most-once (calling it again after the first
+call does nothing). `getFieldNames()` lists every name currently held, in first-registration order. The
+registry object is memoised on `namespace`, so a fieldset that re-points at a different namespace hands out
+a new registry object, and every control still mounted re-registers under the new namespace in the same
+commit.
+
+The other way to build a registry is providing `FieldsetFieldContext` directly with a hand-written
+`{ namespace, registerFieldName }` object — the context is exported for exactly that, and nothing requires
+going through the hook. A control that calls `useFieldsetField` gets the namespace throw either way, since
+that check reads `registry.namespace` and lives in `useFieldsetField` itself, never in `registerFieldName` —
+so the namespace check is never lost for a normal control; only a caller that bypasses `useFieldsetField`
+and reaches `registerFieldName` directly escapes it, on either kind of registry. Refcounting for that same
+direct caller depends on which registry it reached: on one built by `useFieldsetFieldNames`, it is
+refcounted exactly like a caller that arrived through `useFieldsetField` — two callers of one name collapse
+to one entry either way (see above). On a hand-written registry, it gets whatever that particular
+`registerFieldName` implementation wrote, which may not refcount at all. The structural type,
+`{ namespace: string; registerFieldName: (name: string) => () => void }`, does not enforce either property
+at the type level — but the contract's own documentation requires both, as provider obligations:
+refcounting, and that the returned function releases at most once.
+
+Every fieldset also calls `useNoAncestorFieldset(componentName)` once, a one-line guard that throws during
+render when it finds an ancestor fieldset already providing field registration for the subtree — fieldsets
+compose as siblings under one `FormRoot`, never nested. `ShippingAddressFieldset`, `ClientProfileFieldset`
+and `ClientPreferencesFieldset` all provide their registry via `useFieldsetFieldNames` today.
+
+---
+
+## Components
+
+### Field.Root
+
+Form field container that connects a label, input, and validation messages via ARIA. Declares
+`providesContext: 'field'`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `disabled` | boolean | `false` | Explicit prop always wins over the contract's `disabled`. |
+| `invalid` | boolean | — | Explicit prop always wins over the value react-hook-form derives when bound. |
+| `name` | string | — | Explicit prop always wins over the contract's `name` when bound. |
+
+Bound behaviour: passes the contract's `name` to Base UI's `name`; derives `invalid` from
+react-hook-form's field state and passes it as a prop. `dirty`/`touched` are three-state: while
+react-hook-form has not registered (mounted) the contract's name, both are `undefined`, so Base UI's own
+internal tracking still drives `data-dirty`/`data-touched` for a control it never registers — a raw Base
+UI control placed directly under the bound `Field.Root`, rather than through a `Field.*` adapter. Once
+react-hook-form registers the name, its own dirty/touched state for that name always wins instead, in
+both directions, so `data-dirty`/`data-touched` come off the rendered element as soon as react-hook-form
+reports the field clean/untouched again — this applies identically to `dirty` and `touched`.
+
+### Field.Label
+
+Accessible label, associated with `Field.Control`'s input via ARIA. No props beyond `className`/`children`.
+
+Bound behaviour: a **childless** `Field.Label` renders the contract's `label`; with children, the children
+win.
+
+### Field.Control
+
+Renders a native `<input>` directly — it *is* the input, not a wrapper. No props beyond native input
+attributes.
+
+Bound behaviour: registers with react-hook-form using the contract's `name`, `rule` (as `rules`), and
+`defaultValue`; wires `value`, `onChange`, `onBlur`, and `ref` from the resulting controller field. An
+explicit `placeholder`, `disabled`, `readOnly`, `autoComplete`, or `inputMode` prop wins over the
+contract's; `aria-required` is set when the field resolves to required.
+
+Requiredness resolves in `useBoundField`, the one hook every bound control passes through, as
+`required = baselineRequired || authorRaise` and nothing else. The fieldset's `rule.required` is the
+baseline; a control may raise a field to required and never lower one. Read-only is deliberately not
+a term: a field that is read-only and required stays required, and an unsatisfiable form is the
+declared baseline's fault. The one resolved value drives the announcement, the validation and the
+error copy together, so they cannot disagree — including a blank check beside `required`, because
+`required` alone treats a space-filled string as present.
+
+### Field.Description
+
+Helper text, linked to the control via `aria-describedby`. No props beyond `className`/`children`.
+Unchanged whether bound or not — the contract carries no description text.
+
+### Field.Error
+
+Validation error message, linked to the control via `aria-describedby`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `match` | `boolean \| keyof ValidityState` | — | Unbound path only (see below). |
+
+Unbound behaviour: `match` keeps Base UI's documented meaning — `true` always shows the error; a
+`ValidityState` key shows it only when that native flag is set; omitted, it falls back to Base UI's own
+native-validity default.
+
+Bound behaviour: renders `children ?? <the react-hook-form error's message>` for the contract's name, and
+renders nothing when there is no error. `match` is not read on this path — visibility is driven by
+react-hook-form's error, not by native constraint validation (which the shipped `Field.Control` never
+opts into: there is no real `required` HTML attribute, only `aria-required`).
+
+### Field.Validity
+
+Render-prop slot for custom messages derived from Base UI's own validity state.
+
+**Bound behaviour is not transparent.** `Field.Root` only feeds Base UI's `invalid` flag from
+react-hook-form; that flips `validity.valid` to `false`, so `data-invalid` and a bound `Field.Error` both
+react correctly. It does **not** feed `.error`/`.errors` — those come from Base UI's own internal
+`validityData`, which Base UI writes only from its own commit cycle (native constraint validation, or its
+`validate` prop, run on change, on blur, or via an imperative `actionsRef.validate()`). A field with no
+native HTML constraint and no `validate` prop — every shipped bound `Field.Control` — never triggers that
+cycle. A required field left empty and submitted renders `valid: false` with `error: ''`:
+
+```tsx
+<Field.Validity>{(validity) => (validity.validity.valid ? null : <span>{validity.error}</span>)}</Field.Validity>
+// Invalid after submit, but `validity.error` is '' — renders an empty <span>, not the rule's message.
+```
+
+Use `Field.Error` for a bound field's error text — it reads react-hook-form's error directly instead of
+Base UI's own validity data. `Field.Validity` stays useful for `.validity.valid`/`.filled`/`.focused`, and
+for a control that also carries a real native HTML constraint.
+
+### Field.Checkbox
+
+New bound part: an adapter over the shipped `Checkbox` particle, not a change to it. Reads the field
+contract, binds through `useBoundField`, and drives `Checkbox.Root`.
+
+| Prop | Type | Notes |
+|------|------|-------|
+| `className` | string | Forwarded to `Checkbox.Root`. |
+| `children` | ReactNode | Forwarded to `Checkbox.Root` — compose `Checkbox.Indicator` here for the visual check mark. `Field.Checkbox` renders no default indicator. |
+
+Bound behaviour: renders `Checkbox.Root` with `checked={Boolean(field.value)}`,
+`onCheckedChange={field.onChange}`, `onBlur={field.onBlur}` and `ref={field.ref}` — so react-hook-form
+hears the checkbox's blur (a form running `mode: 'onBlur'`/`'onTouched'` treats it like every other
+field) and can move focus to it after a failed submit — seeded from the contract's `defaultValue`/`rule`,
+plus `disabled` from the contract. It also renders `data-fs-field-checkbox=""` on the same host element
+as `Checkbox.Root`'s own `data-fs-checkbox-root=""`, so a brand can target the bound checkbox without
+touching the generic one. Unbound behaviour: renders `Checkbox.Root` with `children` and `className`
+only. `Checkbox.Root` itself gains no `requiresContext` from this pairing — every standalone checkbox
+stays placeable anywhere — but its prop set opened to Base UI's own span props, so `ref`, `onBlur` and
+any `data-*` attribute reach the rendered host element through a rest spread.
+
+---
+
+## Canonical schema example
+
+`FieldBinding` and the two hooks are never catalogued, so a **bound** composition can only be authored in
+code — a matter's Control renders `FieldBinding` internally. A schema can only author the **unbound**
+anatomy, which is the same shape that ships on `main` today:
+
+```json
+{
+  "email-field": {
+    "type": "FieldRoot",
+    "style": ["flex", "flex-col", "gap-1"],
+    "children": ["email-label", "email-control", "email-description"]
+  },
+  "email-label": { "type": "FieldLabel", "props": { "children": "Email address" } },
+  "email-control": { "type": "FieldControl", "props": { "type": "email", "placeholder": "you@example.com" } },
+  "email-description": { "type": "FieldDescription", "props": { "children": "We'll never share your email with anyone." } }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Passing the field name as a prop to a part.** No part accepts one. The only way to name a field is a
+  `FieldBinding` above it — whatever an author composes inside a bound Control edits that Control's field.
+- **Expecting the field contract to carry the live value.** It never does, by design (Decision 1 of the
+  spec that added binding) — read the value through react-hook-form (`getValues`, `useWatch`), not
+  through `useField()`. Do not call `useController` yourself to get at it: it is only ever called once
+  per bound part, inside `useBoundField`, and a second call site for the same name would register a
+  duplicate binding.
+- **Nesting a bound Control inside another bound Control.** Unsupported; nothing enforces it today.
+- **Using `Field.Control` for a boolean field.** It renders a native `<input>`; use `Field.Checkbox`, which
+  drives `Checkbox.Root`.
+- **Passing an unstable `rule` or `options` object to a Control.** The contract memoises on these values —
+  a churning identity costs re-renders (every subscriber below the binding re-renders), never correctness.
+- **Expecting `Field.Error`'s `match` prop to do anything on a bound composition.** It is read only on the
+  unbound path; a bound `Field.Error`'s visibility is driven by react-hook-form's error for the contract's
+  name.
+
+---
+
+## Styling
+
+Every part renders its own `data-fs-*` hook and accepts `className`; none ships default styling.
+`Field.Checkbox` additionally renders `data-fs-field-checkbox=""` on the same host element as
+`Checkbox.Root`'s own `data-fs-checkbox-root=""`, so a brand can target the bound checkbox without touching
+the generic one.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `FieldRoot` | Stacks label/control/description/error | `flex flex-col gap-1` |
+| `FieldLabel` | Label typography | `text-sm font-medium text-gray-700` |
+| `FieldControl` | The input box; target `data-invalid:` for the error state | `border border-gray-300 rounded-md px-3 py-2 text-sm data-invalid:border-red-400` |
+| `FieldDescription` | Helper text, quieter than the label | `text-xs text-gray-500` |
+| `FieldError` | Error text, typically red | `text-xs text-red-500` |
+
+---
+
+## Related
+
+- [[checkbox]] — the generic particle `Field.Checkbox` adapts. `Checkbox.Root` itself stays placeable
+  standalone, outside any form; it gains no form-specific requirement from this pairing.
+- [[fieldset]] — the visual fieldset/legend particle. Unrelated to the write-boundary fieldset that
+  provides `useFieldsetField`'s registry — `ShippingAddressFieldset`, `ClientProfileFieldset` and
+  `ClientPreferencesFieldset`, documented above.
+- [[document-field]], [[phone-field]] — field-shaped composites that read the field contract themselves
+  (through `useField()`/`useFormContext()`) rather than through a `Field.*` adapter, because they own
+  masking, progressive formatting and their own validators that an adapter has no way to reach past.
+- [[email-field]], [[password-field]], [[number-field]], [[postal-code-field]], [[access-code-field]] —
+  particles that already compose `Field.Root` and its parts with their own closed anatomy; still
+  unaffected by the field contract until their own tasks convert them.

package/dist/docs/form.md

@@ -0,0 +1,307 @@
+# Form
+
+**Category:** action
+**Purpose:** The composable form boundary — one `<form>`, one react-hook-form instance, and a registry of the fieldsets mounted inside it — so a single submit can validate and persist every entity a shopper changed in one press.
+
+---
+
+## When to use
+
+- Any composition where a submit needs to persist more than one entity behind one button — a
+  checkout step with a name, a phone and a delivery address, for example.
+- As the outermost boundary for a fieldset (a shipping-address fieldset, a profile fieldset —
+  shipped by later tasks) — a fieldset does nothing outside a `FormRoot`, because it has nowhere to
+  register.
+- Wherever `FormSubmit`, `FormEnterSubmit`, `FormError`, `FormClear` or `FormReset` are needed — all
+  five require the context only `FormRoot` provides, and can be placed anywhere inside it, not only as
+  its direct children.
+
+## When NOT to use
+
+- A single, self-contained write with its own explicit button and no reason to ever compose with
+  another entity — nothing in the catalog takes this shape today; every write-capable matter either
+  registers a fieldset with `FormRoot` or writes on change, with no component of its own `<form>`.
+- A boolean or list field's own anatomy — that is `Field.Root`/`Field.Checkbox`/`Field.Select` (see
+  [[field]]), composed *inside* the fieldset a `FormRoot` wraps, not a `Form` part itself.
+- A visual `<fieldset>`/`<legend>` grouping with no write behaviour — that is `Fieldset.Root`/
+  `Fieldset.Legend` (see [[fieldset]]), an unrelated, purely presentational particle sharing the word
+  "fieldset" by coincidence.
+
+---
+
+## Composition
+
+```
+FormRoot                      (providesContext: 'form')
+├── FormSubmit                 (requiresContext: 'form')
+├── FormEnterSubmit            (requiresContext: 'form')
+├── FormError                  (requiresContext: 'form')
+├── FormClear                  (requiresContext: 'form')
+├── FormReset                  (requiresContext: 'form')
+└── a fieldset                 (a later task — registers itself with FormRoot)
+    └── a bound Control        (shipped by the field contract — see [[field]])
+```
+
+`FormSubmit`, `FormEnterSubmit`, `FormError`, `FormClear` and `FormReset` are siblings of each other and
+of whatever fieldset(s) `FormRoot` wraps — none of them needs to be adjacent to the others, or to the
+fieldset, in the tree. Child order under `FormRoot` reflects visual order: where an author places
+`FormSubmit`/`FormEnterSubmit` relative to the fields is where the button renders.
+
+`providesContext`/`requiresContext` are the compiler's static check for a schema-authored page — every
+one of the five parts fails the build with a `context-constraint-violation` diagnostic if no `FormRoot`
+is an ancestor. At runtime, each part's own hook (`useFormRegistry`) throws the same failure as a
+defence for JSX composed outside the compiler (Storybook, tests, manual code).
+
+`FormRoot` knows fieldsets, never fields: it reaches a field name only through a fieldset
+registration's `getFieldNames()`, never by reading `Field.*` parts or the field contract directly. A
+fieldset is a code-level concept (round 1's `FieldsetFieldContext`/`useFieldsetField` seam, plus the
+`FieldsetRegistration` contract this task ships) — it is not itself catalogued or schema-authorable,
+the same way `FieldBinding` is not.
+
+### The registry contract (`FieldsetRegistration` / `useFormRegistry`)
+
+A fieldset registers itself once, for as long as it is mounted. Its `label` is the kebab-case rendering of
+its own `namespace` (`shippingAddress` → `shipping-address`) — a machine identifier, never shopper copy;
+see *FormError* below for the one place it surfaces:
+
+```tsx
+const { registerFieldset } = useFormRegistry();
+
+useEffect(
+  () =>
+    registerFieldset({
+      namespace: 'shippingAddress',
+      label: 'shipping-address',
+      getFieldNames: () => ['shippingAddress.street', 'shippingAddress.city'],
+      toPayload: (values) => ({ street: values.street, city: values.city }),
+      dispatch: (payload) => actions.shippingAddress.update(payload),
+    }),
+  [registerFieldset],
+);
+```
+
+`FormRoot` calls `dispatch` for a fieldset only when one of the fields it currently has mounted is dirty —
+"dirty" means "the shopper touched a field here", not "differs from the seed" (see *Common
+mistakes*). `FormRoot` destructures `dirtyFields` from `formState` during render, which is what
+subscribes it, and walks each mounted field's dot-path through that object. Reading dirtiness inside the submit callback
+instead would subscribe nothing, leaving the gate dependent on whichever composed part happened to
+open a subscription of its own. Registrations dispatch in the order they were first inserted, one at a time; a
+later registration under the same namespace replaces the earlier one in place rather than moving it —
+this is how the same fieldset survives its own effect cleaning up and re-running.
+
+`registerFieldset` throws when the namespace collides with one a *different*, still-mounted fieldset
+already holds, and when it is a prefix or a descendant of one already registered (`profile` alongside
+`profile.address`). Two fieldsets sharing a namespace would silently collapse into one, leaving the
+displaced fieldset mounted, editable and permanently unwritable while submit still reports success; a
+nested namespace would make the parent dispatch on the child's edits and marshal the child's values
+into the parent's payload. Both are unusable by construction, so `FormRoot` fails fast at registration
+rather than degrading silently.
+
+### Implicit submission
+
+By default, `FormRoot` cancels HTML implicit submission for its own text-entry inputs: pressing Enter
+in a field does nothing, because a stray Enter mid-address would commit a write the shopper has not
+finished composing. Whether Enter submits is chosen by composition, not by a prop: mount `FormSubmit`
+to keep that cancelling default, or `FormEnterSubmit` to allow it — there is no `submitOnEnter` prop
+and no schema entry for the behaviour on either part.
+
+The allowance is form-scoped, not fieldset-scoped: a `FormEnterSubmit` placed inside one fieldset of a
+multi-fieldset `FormRoot` allows Enter to submit from *any* text-entry input of that `FormRoot`, not
+only the fieldset it happens to sit in — `FormRoot` knows fieldsets, never fields, so there is no
+narrower rule and no path to one. Two mounted `FormEnterSubmit`s compose (unmounting one leaves the
+allowance the other still holds in place), and both `FormSubmit` and `FormEnterSubmit` can be mounted
+together, in which case Enter still submits exactly once.
+
+Enter that commits an IME candidate — the keystroke a Japanese, Chinese or Korean shopper uses to
+choose a word, not to submit — is cancelled either way, allowance or not. Choosing a word must never
+send a half-finished form.
+
+An author-supplied `onKeyDown` on `FormRoot` runs first, unconditionally, before either behaviour: it
+can cancel Enter on a form that otherwise allows it, but it cannot force Enter to submit on a form that
+cancels it, because the built-in guard's own `preventDefault()` runs after the author's handler.
+
+---
+
+## Components
+
+### FormRoot
+
+The only `<form>` in a composition. Renders `noValidate`, wires
+`onSubmit={handleSubmit(onValid, onInvalid)}`, and provides both react-hook-form's context and the
+fieldset registry to every descendant. Declares no `actions` — every write stays declared by the
+fieldset that owns it.
+
+No props beyond the native `<form>` attributes (`onSubmit` is owned internally and cannot be passed).
+
+### FormSubmit
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | Rendered when there are no `children`. Falls through to the message catalog (`fs/form.submit`) when unset. |
+| `children` | ReactNode | — | Wins over `label` when present. |
+
+Text resolves `children ?? label ?? formatMessage({ id: 'fs/form.submit' })` — there is no hard-coded
+English default. An author who wants copy other than the catalog's own must set `label` or `children`
+explicitly.
+
+A `type="submit"` `Button`, disabled while `formState.isSubmitting`. Pressing it validates every
+registered field first; only once every field is valid does it skip untouched fieldsets, dispatch the
+dirty ones in registration order, and collect what failed. Pressing Enter in a text input does *not*
+submit — see *Implicit submission* above and `FormEnterSubmit` below for a form where it does.
+
+### FormEnterSubmit
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | Rendered when there are no `children`. Falls through to the message catalog (`fs/form.submit`) when unset. |
+| `children` | ReactNode | — | Wins over `label` when present. |
+
+Renders the same button as `FormSubmit`, sharing its text resolution (the same `fs/form.submit` id —
+there is no separate id for the Enter variant, since both parts render the same word) and its
+`data-fs-form-submit`/`data-fs-form-submit-pending` hooks — there is no separate styling hook for this
+part. While mounted, it additionally allows Enter to
+submit the enclosing `FormRoot` from any of its text-entry inputs (see *Implicit submission* above for
+the form-wide blast radius and the IME carve-out).
+
+### FormError
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `fallbackMessage` | string | `'Something went wrong. Please try again.'` | Shown for a fieldset whose write threw rather than resolving `userErrors`. |
+
+Renders nothing when the last submit produced no failures. Otherwise, one group per failing fieldset,
+carrying `data-fs-form-error-item={label}` — a styling/selector hook, never rendered as text. The visible
+text inside each group is each failing `userError`'s own `message`, or `fallbackMessage` when the dispatch
+rejected or never settled.
+
+### FormClear
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | Rendered when there are no `children`. Falls through to the message catalog (`fs/form.clear`) when unset. |
+| `children` | ReactNode | — | Wins over `label` when present. |
+
+A `type="button"` `Button` that empties every field registered by every fieldset inside the enclosing
+`FormRoot` — not only the fieldset nearest to it in the tree. Each bound part registers how its own
+field is cleared, to its own empty value (`false` for a boolean field, `''` otherwise), and marks dirty
+only the fields whose value actually changed: a field already empty stays clean. A registered name with
+no bound part currently mounted is left alone. The following submit dispatches a write for every
+fieldset that had something to clear, and nothing for one where clearing was a no-op. There is no prop
+to scope it to one fieldset; place it only where clearing the whole form is the intended action.
+
+### FormReset
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | Rendered when there are no `children`. Falls through to the message catalog (`fs/form.reset`) when unset. |
+| `children` | ReactNode | — | Wins over `label` when present. |
+
+A `type="button"` `Button` that returns every registered field name to react-hook-form's baseline for
+that name, and clears its dirty/touched state. Before a fieldset's first successful write, that
+baseline is whatever the field's own seed resolves to; it becomes "what was last written" only after a
+successful submit.
+
+---
+
+## Canonical schema example
+
+`FormSubmit`, `FormEnterSubmit`, `FormError`, `FormClear` and `FormReset` are schema-authorable; a
+fieldset is not (it is a code-level composition today, the same way a bound `Field.Control` is). A
+schema can author the form's boundary and its actions around wherever a fieldset renders itself:
+
+```json
+{
+  "checkout-step": {
+    "type": "FormRoot",
+    "style": ["flex", "flex-col", "gap-4"],
+    "children": ["shipping-address-fieldset", "step-error", "step-submit"]
+  },
+  "step-error": { "type": "FormError" },
+  "step-submit": { "type": "FormSubmit", "props": { "label": "Save and continue" } }
+}
+```
+
+`shipping-address-fieldset` is a matter component (shipped by a later task) that renders its own
+fields and calls `registerFieldset` internally — it is placed in the schema like any other
+component, but nothing about its internals is schema-authorable.
+
+---
+
+## Common mistakes
+
+- **Expecting a submit with nothing touched to dispatch anything.** It does not — `FormSubmit`'s skip
+  gate is per-fieldset `dirtyFields`, which the RFC and this doc both call "touched", not "changed".
+  Typing a value and then typing the original seed back still leaves that fieldset dirty and dispatches
+  a request that changes nothing.
+- **Reading `formState.isDirty` to decide whether to submit.** Whole-form `isDirty` is `true` from the
+  moment any field is seeded and never reliably returns to `false` under this design — `FormRoot` never
+  reads it, and neither should a composition built on top of it.
+- **Expecting `FormReset` to mean "clear the form".** That is `FormClear`. `FormReset` returns fields to
+  a baseline; before any successful write, that baseline is whatever the field's own seed resolves to, so
+  Reset reverts to the original value rather than emptying it — the two look the same only when a seed
+  happens to be empty. They diverge for good the moment something has been saved, when the baseline
+  becomes what was last written.
+- **Placing `FormClear` expecting it to clear only the nearest fieldset.** It has no scoping prop by
+  design (Decision, engineer-approved): pressing it empties every field of every fieldset registered
+  anywhere in the enclosing `FormRoot`, and the following submit dispatches a write for each one. Place
+  it only where clearing the whole form is genuinely the intended action.
+- **Nesting a second `FormRoot` inside the first.** Unsupported; nothing enforces it today, and two
+  `useForm()` instances would not share state. Compose fieldsets as siblings under one `FormRoot`
+  instead.
+- **Confusing this with `Fieldset.Root`/`Fieldset.Legend`.** Those are a purely visual `<fieldset>`
+  wrapper (see [[fieldset]]) with no write behaviour and no relationship to the registry this particle
+  defines.
+- **Giving `FormRoot` an `actions` selector.** It declares none by design (Decision 1) — a write always
+  belongs to the fieldset that dispatches it, so `catalog.json` can still say which component performs
+  it.
+- **Reaching for a `submitOnEnter` prop.** There is none, on either part, by design: whether Enter
+  submits is chosen by composing `FormSubmit` or `FormEnterSubmit`, never by a flag.
+- **Placing `FormEnterSubmit` inside one fieldset and expecting the allowance to stay scoped to it.**
+  It does not — the allowance is form-wide, because `FormRoot` knows fieldsets, never fields. Enter in
+  *any* text-entry input of that `FormRoot` submits, not only the ones in the fieldset the part sits in.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `FormRoot` | The `<form>` element — typically stacks its fieldsets and actions | `flex flex-col gap-6` |
+| `FormSubmit` | The primary action button; target `data-fs-form-submit-pending` for the in-flight state | `bg-blue-600 text-white rounded-md px-4 py-2 data-fs-form-submit-pending:opacity-60` |
+| `FormError` | The failure summary; carries `role="alert"` | `text-sm text-red-600 space-y-2` |
+| `FormClear` | A secondary action, typically quieter than Submit | `text-sm text-gray-500 underline` |
+| `FormReset` | A secondary action, typically quieter than Submit | `text-sm text-gray-500 underline` |
+
+```json
+{
+  "checkout-step": {
+    "type": "FormRoot",
+    "style": ["flex", "flex-col", "gap-6"],
+    "children": ["shipping-address-fieldset", "step-error", "step-actions"]
+  },
+  "step-error": { "type": "FormError", "style": ["text-sm", "text-red-600", "space-y-2"] },
+  "step-actions": {
+    "type": "Container",
+    "style": ["flex", "gap-2"],
+    "children": ["step-reset", "step-submit"]
+  },
+  "step-reset": { "type": "FormReset", "style": ["text-sm", "text-gray-500", "underline"] },
+  "step-submit": {
+    "type": "FormSubmit",
+    "props": { "label": "Save and continue" },
+    "style": ["bg-blue-600", "text-white", "rounded-md", "px-4", "py-2"]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[field]] — the field anatomy and the field contract a bound Control renders inside a fieldset; also
+  documents the fieldset *field-name* seam (`useFieldsetField`), the sibling scope to this particle's
+  *fieldset* registry.
+- [[fieldset]] — the unrelated, purely visual `<fieldset>`/`<legend>` particle. Shares a name with the
+  write-boundary "fieldset" concept this doc uses, but has no code relationship to it.
+- [[button]] — the particle every `Form` action wraps (`Button` with `type="submit"` or `type="button"`,
+  plus this particle's own `data-fs-form-*` hooks).

package/dist/docs/identity-edit.md

@@ -10,9 +10,9 @@ rather than a shared mechanism: the two differ in exactly the parts that are dom
 starts on the summary and needs an explicit cancel; that one derives its starting state from whether an
 address exists and closes itself with no cancel at all.
 
-The mode is owned here, not authored in a page (ADR-0006). `ClientProfileForm` announces nothing and never
-learns whether anything collapses around it, which is what lets the same form sit in a section, in a wizard
-step, or on a page of its own.
+The mode is owned here, not authored in a page (ADR-0006). The composed `FormRoot`/`ClientProfileFieldset`
+pair announces nothing and never learns whether anything collapses around it, which is what lets the same
+form sit in a section, in a wizard step, or on a page of its own.
 
 ## Why no mode name reaches the schema
 
@@ -51,8 +51,8 @@ resolution error rather than a silently dead branch that blanks the section.
 - Starts on the summary. Unlike the delivery section, nothing about the profile data decides this: the
   summary is always the right first thing to show a shopper who has one.
 - The mode moves only on this section's own buttons, `EditButton` and `CancelButton`. Saving the form does
-  not close the section, which is what keeps `ClientProfileForm`'s confirmation on screen long enough to
-  read.
+  not close the section, so the form's own fields and controls stay on screen after a save rather than
+  being replaced by the summary.
 - **Self-contained.** It observes nothing outside itself and reports nothing: no other section opens or
   closes as a result of anything happening here. Whether finishing a form should collapse the section that
   holds it is a sequencing question, deliberately left to the flow-of-steps RFC (#611) rather than
@@ -68,7 +68,7 @@ IdentityEditController
 │  └─ IdentitySummaryView   → IdentityEditButton
 └─ IdentitySummaryRoot
    ├─ IdentitySummaryView   → IdentitySummarySelectedSummary
-   └─ IdentityEditForm      → ClientProfileFormRoot + IdentityEditCancelButton
+   └─ IdentityEditForm      → FormRoot(ClientProfileFieldset) + IdentityEditCancelButton
 ```
 
 ## Accessibility