@nxgt/material 2.0.1 → 2.2.0

package/docs/guides/forms.md

@@ -0,0 +1,841 @@
+# Forms
+
+This page shows how the fields in `@nxgt/material` are wired into a form with
+React Hook Form and Zod. It covers the value each field emits, how validation
+messages are translated, server errors, dialogs and multi-step forms. Each
+field's own props live on its [component page](../components/README.md); this
+page shows the wiring once.
+
+`react-hook-form` is a required peer. The examples also use Zod v4 and its
+resolver, which your app installs itself:
+
+```bash
+bun add zod @hookform/resolvers
+```
+
+## The pair
+
+Every field ships twice, in the same barrel:
+
+- a **standalone field** (`TextField`) that you control yourself with
+  `value` / `onChange`;
+- a **form wrapper** (`TextFormField`) that takes `control` and `name` and
+  reads everything else from React Hook Form.
+
+```tsx
+import { type ChangeEvent, useState } from 'react';
+import { useForm } from 'react-hook-form';
+import { TextField, TextFormField } from '@nxgt/material/components';
+
+// Standalone: you own the state.
+export function StandaloneName() {
+  const [name, setName] = useState('');
+  return (
+    <TextField
+      label="Name"
+      value={name}
+      onChange={(event: ChangeEvent<HTMLInputElement>) => setName(event.target.value)}
+    />
+  );
+}
+
+// Inside a form: the wrapper owns the wiring.
+export function FormName() {
+  const { control } = useForm({ defaultValues: { name: '' } });
+  return <TextFormField control={control} name="name" label="Name" />;
+}
+```
+
+What a wrapper does for you, from the field state of `name`:
+
+| Field prop | Set to |
+| --- | --- |
+| `value` | the form value (`''` / `null` / `[]` when it is `undefined`, depending on the field) |
+| `onChange` / `onValueChange` | `field.onChange`, converted to the type in [What each field emits](#what-each-field-emits) |
+| `onBlur` | `field.onBlur`, called when focus leaves the whole field, so `mode: 'onBlur'` and touched state work (see [Touched on blur](#touched-on-blur)) |
+| `error` | `fieldState.invalid` (the red border) |
+| `helperText` | `fieldState.error?.message`, or your own `helperText` when there is no error |
+| `disabled` | your own `disabled`, or `field.disabled` from React Hook Form |
+| `name` | the field `name` |
+| `id` | yours when you pass one. Otherwise the text-like wrappers (text, number, date…) use the field `name`, so two forms on one page sharing a field name get the same `id`: pass your own. `SwitchFormField`, `CheckboxFormField`, `SliderFormField`, `RadioGroupFormField` and `CheckboxGroupFormField` generate one instead; a group's option *i* is `` `${id}-${i}` `` |
+| `aria-labelledby` / `aria-describedby` | on `RadioGroupFormField` and `CheckboxGroupFormField`, the `radiogroup` / `group` is named by its `label` (`` `${id}-label` ``) and described by the helper or error text (`` `${id}-helper` ``), so a screen reader announces the question and the error with the group. The `radiogroup` also gets `aria-invalid`; the checkbox `group` does not (ARIA forbids it there), its error is its description — for an error with no message, a hidden "This value is not valid." inside your `helperText`. Your own `aria-label` / `aria-labelledby` wins; your `aria-describedby` ids are kept, first |
+
+Every wrapper has the same shape: the React Hook Form half and the field's own
+props, minus the ones the wrapper sets.
+
+```ts
+import type { UseControllerProps } from 'react-hook-form';
+import type { TextFieldProps } from '@nxgt/material/components';
+
+type TextFormFieldProps<T extends Record<string, any>> =
+  Pick<UseControllerProps<T>, 'control' | 'name'> & Omit<TextFieldProps, 'name'>;
+```
+
+A wrapper renders a React Hook Form `Controller`, so it needs the `control` of
+the form it belongs to. Passing `control` explicitly is what makes it work:
+there is no `FormProvider` lookup.
+
+### Touched on blur
+
+Every wrapper calls React Hook Form's `field.onBlur` **when focus leaves the
+field**, as a native `blur` does for one `<input>`. So `touchedFields` flips
+as the user moves on, and a form whose `mode` validates on blur (`'onBlur'`,
+`'onTouched'`, `'all'`) shows an empty required field's message without it
+being typed in.
+
+```tsx
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+import { SelectFormField } from '@nxgt/material/components';
+
+const schema = z.object({ plan: z.string().min(1, { error: 'Required' }) });
+
+export function PlanForm() {
+  const { control, formState } = useForm({
+    mode: 'onTouched', // validate on the first blur, then on each change
+    resolver: zodResolver(schema),
+    defaultValues: { plan: '' },
+  });
+  // Tab into the select, then out: "Required" appears, and
+  // formState.touchedFields.plan is true.
+  return (
+    <SelectFormField
+      control={control}
+      name="plan"
+      label="Plan"
+      options={[{ value: 'pro', label: 'Pro' }]}
+    />
+  );
+}
+```
+
+"Leaving" is one rule for every shape of field:
+
+| The field | Touched when |
+| --- | --- |
+| one input (`TextFormField`, `EmailFormField`, `TextareaFormField`, `SwitchFormField`, `CheckboxFormField`, …) | its input loses focus, as a native `blur` |
+| several controls (`PasswordFormField` and its eye button, `NumberFormField` and its steppers, `PhoneFormField`, `OtpFormField`, `SliderFormField` with two thumbs, `DurationFormField`, `RatingFormField`, `RadioGroupFormField`, `CheckboxGroupFormField`, `SelectChipFormField`, `SelectCardFormField`, `SortableListFormField`, `TransferListFormField`, `InlineEditFormField`, `AttributeValuesFormFieldSet`, …) | focus leaves all of them; moving between them is not leaving |
+| a picker (`SelectFormField`, `ComboboxFormField`, `AutocompleteFormField`, `CountryFormField`, `TimezoneFormField`, `ColorFormField`, `DateFormField`, `DateRangeFormField`, `TimeFormField`, …) | focus leaves the trigger **and** the popover it opened. Opening the popover, or picking in it, is not leaving; closing it hands focus back to the trigger, and the next Tab or click elsewhere is |
+| a dialog editor (`PostalAddressFormField`, `ContactsFormField`, `OpeningHoursFormField`, `AttributesFormField`, and `LocationFormField` from `@nxgt/material/map`) | focus leaves its buttons and the dialog they open. Closing the dialog hands focus back to the button that opened it |
+| an upload (`UploadFormField`, `NetworkUploadFormField`, `S3UploadFormField`, `ImageFormField`, `ImageS3FormField`, `FileListFormField`, `FileListS3FormField`) | focus leaves the drop zone and its buttons. Choosing a file in the browser's own dialog is not leaving |
+| `RichTextEditorFormField`, `CodeEditorFormField` | focus leaves the editor and its toolbar |
+| `FormField` (config-driven) | the rule of the field its `type` renders |
+| `FilterFormField` | the filter is applied (or on every change, with `liveUpdate`) — not on blur |
+
+"Opened" means named by one of the field's controls as the popup it controls
+(`aria-controls`, as a select trigger does) — a control inside one of the
+field's own overlays counts as the field's, so the list of a select in the
+field's dialog is still the field — or mounted under `<body>` after
+focus entered the field and named by no other control. Focus reaching a layer
+that was already there (a non-modal side panel, a banner) is leaving, and so
+is focus that goes nowhere, a click on a blank part of the page. So is focus
+going straight into **another** field's overlay: pressing the mouse on the
+next `SelectFormField` opens its list, which takes focus from this field
+without the trigger ever having it — this field is touched then, not when
+that list closes. Switching to another window is not leaving.
+
+This only makes the blur reach React Hook Form. **When the form validates is
+still its `mode`**: with the default `mode: 'onSubmit'`, leaving a field marks
+it touched and validates nothing until the first submit (then
+`reValidateMode` applies).
+
+To show a field's error only once it has been touched, read the flag with
+`getFieldState`, or `useFormState` in a child component:
+
+```ts
+const { control, formState, getFieldState } = useForm(/* … */);
+const { isTouched, error } = getFieldState('plan', formState);
+```
+
+A field of your own, wrapped in a `Controller`, gets the same behaviour by
+passing `field.onBlur` to the control that loses focus:
+
+```tsx
+<Controller
+  control={control}
+  name="nickname"
+  render={({ field }) => (
+    <input value={field.value} onChange={field.onChange} onBlur={field.onBlur} />
+  )}
+/>
+```
+
+## A complete form
+
+A schema, a resolver, typed default values, three kinds of field and a submit
+button that shows progress:
+
+```tsx
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+import {
+  Button,
+  NumberFormField,
+  SelectFormField,
+  TextFormField,
+} from '@nxgt/material/components';
+
+const schema = z.object({
+  email: z.email(),
+  // A cleared NumberField emits null: accept it as input, reject it on output.
+  seats: z.number().nullable().pipe(z.number().int().min(1).max(50)),
+  plan: z.enum(['starter', 'team', 'enterprise']),
+});
+
+type Draft = z.input<typeof schema>; // seats: number | null
+type Values = z.output<typeof schema>; // seats: number
+
+const plans = [
+  { value: 'starter', label: 'Starter' },
+  { value: 'team', label: 'Team' },
+  { value: 'enterprise', label: 'Enterprise' },
+];
+
+export function SubscribeForm({
+  onSave,
+}: {
+  onSave: (values: Values) => Promise<void>;
+}) {
+  const form = useForm<Draft, unknown, Values>({
+    resolver: zodResolver(schema),
+    defaultValues: { email: '', seats: 1, plan: 'team' },
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit(onSave)} className="grid gap-4">
+      <TextFormField control={form.control} name="email" label="Email" type="email" required />
+      <NumberFormField control={form.control} name="seats" label="Seats" min={1} max={50} />
+      <SelectFormField control={form.control} name="plan" label="Plan" options={plans} />
+      <Button type="submit" loading={form.formState.isSubmitting}>
+        Subscribe
+      </Button>
+    </form>
+  );
+}
+```
+
+- **Two types, on purpose.** `Draft` is what the fields hold while the user
+  types (`seats` is `null` once the input is cleared); `Values` is what the
+  schema guarantees on submit. `useForm<Draft, unknown, Values>` gives
+  `handleSubmit` the parsed `Values`. The `nullable().pipe(…)` makes the
+  schema's input type match what `NumberFormField` emits, and a cleared field
+  fails with "This field is required.".
+- `Button` defaults to `type="button"`: the submit button needs
+  `type="submit"`. `loading` shows a spinner and ignores clicks while the
+  promise returned by `onSave` is pending.
+- Default values must have the type the field emits. See
+  [What each field emits](#what-each-field-emits).
+
+## Validation messages
+
+`zodLocaleError()` from `@nxgt/material/lib` is a Zod v4 error map that
+writes messages in the user's language (`en` or `fr`), from the package's own
+`material.zod.*` strings. Install it once, before any schema is parsed, in your
+app's entry. It is safe on a server, where it writes English unless you pass
+`zodLocaleError({ language })` with the request's language:
+
+```ts
+import { z } from 'zod';
+import { zodLocaleError } from '@nxgt/material/lib';
+
+z.config({ customError: zodLocaleError() });
+```
+
+Then, for the schema of [A complete form](#a-complete-form):
+
+| Input | English | French |
+| --- | --- | --- |
+| `email: 'nope'` | `Invalid email address.` | `adresse e-mail invalide.` |
+| `name: 'ab'` for `z.string().min(3)` | `This value is too small: it must be at least 3 characters.` | `Cette valeur est trop petite : elle doit être au minimum 3 caractères.` |
+| a missing key (`undefined`) | `This field is required.` | `Ce champ est requis.` |
+
+A message set on the schema wins over the error map, so override one field
+where the generic text is not good enough:
+
+```ts
+import { z } from 'zod';
+
+const schema = z.object({
+  name: z.string().min(1, { error: 'Tell us your name' }),
+  project: z.literal('my-project', { error: 'Type the project name exactly' }),
+});
+```
+
+How it picks the language, and what that implies:
+
+- By default it reads `localStorage.language`, the key `I18nProvider` writes
+  by default. `'fr'` gives French; anything else gives English. It does not
+  read the provider's React state.
+- Options, all optional: `storageKey` (pass the provider's own if you changed
+  it), `language` (a language or a function returning one, used instead of
+  storage), and `translate` (your app's translator, so the `material.zod.*`
+  strings you merged with `mergeResources` apply). See
+  [i18n](i18n.md#zod-messages).
+- It works **without** `I18nProvider`: it formats from the package's own
+  bundle, in English when nothing is stored.
+- The message is computed when validation runs. An error already on screen
+  keeps its language after a switch until the field is validated again
+  (`form.trigger()` re-runs it).
+- It is safe on a server: with no `localStorage` (or when reading it throws)
+  it writes English, unless you pass `language`.
+- `invalid_type` says what was expected (`z.number()` given a string says
+  `This value must be a number.`); a type with no string of its own says
+  `This value has the wrong type.`
+
+## What each field emits
+
+The value a wrapper writes into the form, read from each field's `onChange`
+/ `onValueChange` in the source. **Default values must have this type**: a
+`Date` field given an ISO string, or a number field given `'3'`, renders wrong
+or fails validation.
+
+### Form fields
+
+| Field · wrapper | Form value | Empty default |
+| --- | --- | --- |
+| `TextField` · `TextFormField` | `string`. With `type="number"`: `number \| null` | `''` |
+| `TextareaField` · `TextareaFormField` | `string` | `''` |
+| `EmailField` · `EmailFormField` | `string` (as typed; the field shows its own "Enter a valid email" hint on blur) | `''` |
+| `PasswordField` · `PasswordFormField` | `string` | `''` |
+| `NumberField` · `NumberFormField` | `number \| null`. `null` when cleared; clamped to `min` / `max` on blur | `null` |
+| `PercentField` · `PercentFormField` | `number \| null`, `min` 0, `max` 100, `step` 1 by default | `null` |
+| `CurrencyField` · `CurrencyFormField` | `number \| null`, the amount only, not rounded. `currency` (default `'EUR'`) and `fractionDigits` (the currency's own decimals by default) are display | `null` |
+| `PhoneField` · `PhoneFormField` | E.164 `string` (`'+33612345678'`), or `null` while the number is not yet a possible one. `defaultCountry` is `'FR'` | `null` |
+| `UrlField` · `UrlFormField` | `string` (as typed) | `''` |
+| `SearchField` · `SearchFormField` | `string`, after `debounceMs` (default `0`) | `''` |
+| `ColorField` · `ColorFormField` | `string` (hex, `'#1e293b'`) | `''` |
+| `OtpField` · `OtpFormField` | `string` of up to `length` (default 6) characters | `''` |
+| `InputGroupField` · `InputGroupFormField` | `string`. With `type="number"`: `number \| null` | `''` |
+| `InlineEdit` · `InlineEditFormField` | `string`, written on save only | `''` |
+| `CountryField` · `CountryFormField` | `mode="single"` (default): ISO code `string \| null` (`'FR'`). `mode="multiple"`: `string[]` | `null` / `[]` |
+| `TimezoneField` · `TimezoneFormField` | IANA `string \| null` (`'Europe/Paris'`) | `null` |
+| `RatingField` · `RatingFormField` | `number`, `0` for no rating | `0` |
+| `Slider` · `SliderFormField` | `number` when the default is a number; `number[]` when the default is an array (a range) | `0` / `[20, 80]` |
+| `Switch` · `SwitchFormField` | `boolean` | `false` |
+| `AttributesField` · `AttributesFormField` | `Attribute[]` | `[]` |
+| `ContactsFormField` | `Contact[]`: `{ type: ContactType; value: string; label?: string \| null }` | `[]` |
+| `PostalAddressFormField` | `PostalAddressFieldValue`: `{ street?, locality?, region?, postalCode?, country? }`; `{}` after delete | `{}` |
+| `OpeningHoursFormField` | `OpeningHour[]`: `{ dayOfWeek: 0–6; openTime?: 'HH:mm'; closeTime?: 'HH:mm'; isClosed?: boolean }` | `[]` |
+
+### Date & time
+
+| Field · wrapper | Form value | Empty default |
+| --- | --- | --- |
+| `DateField` · `DateFormField` | `Date \| undefined` (not an ISO string) | `undefined` |
+| `DateRangeField` · `DateRangeFormField` | `DateRange \| undefined`: `{ from: Date \| undefined; to?: Date }` | `undefined` |
+| `TimeField` · `TimeFormField` | `Date \| undefined`. With `asString`: `'HH:mm'`. While empty it shows its `placeholder` | `undefined` / `''` |
+| `DurationField` · `DurationFormField` | `number \| null`: total minutes (hours × 60 + minutes) | `null` |
+
+### Selection & choice
+
+| Field · wrapper | Form value | Empty default |
+| --- | --- | --- |
+| `SelectField` · `SelectFormField` | `string` (an option `value`) | `''` |
+| `ComboboxField` · `ComboboxFormField` | `string \| null` | `null` |
+| `Autocomplete` · `AutocompleteFormField` | `mode="single"`: `string \| null`. `mode="multiple"`: `string[]` | `null` / `[]` |
+| `Checkbox` · `CheckboxFormField` | `boolean` | `false` (see [Traps](#traps)) |
+| `CheckboxGroup` · `CheckboxGroupFormField` | `string[]` | `[]` |
+| `RadioGroup` · `RadioGroupFormField` | `string` | `''` |
+| `CheckCardField` · `CheckCardFormField` | `boolean`: `true` for the first card, `false` for the second | `false` |
+| `SelectCardField` · `SelectCardFormField` | `mode="single"` (default): `string \| null`. `mode="multiple"`: `string[]`. The standalone field always emits `string[]` | `''` / `[]` |
+| `SelectChipField` · `SelectChipFormField` | same as `SelectCardField` | `''` / `[]` |
+| `TransferList` · `TransferListFormField` | `string[]`: the selected `value`s, in order | `[]` |
+| `SortableList` · `SortableListFormField` | `string[]`: the `value`s, in the user's order | `[]` |
+
+### Media & files
+
+| Field · wrapper | Form value | Empty default |
+| --- | --- | --- |
+| `NetworkUploadField` · `NetworkUploadFormField` | `mode="single"`: the `string` your `onUpload` resolved (a URL or a key), or `null` after removal. `mode="multiple"`: `string[]` | `undefined` / `[]` |
+| `S3UploadField` · `S3UploadFormField` | as above; the value is `publicUrl` from `getPresignedUrl` | `undefined` / `[]` |
+| `ImageField`, `ImageS3Field` · `ImageFormField`, `ImageS3FormField` | `string \| null` (the uploaded URL) | `undefined` |
+| `FileListField`, `FileListS3Field` · `FileListFormField`, `FileListS3FormField` | `string[]` | `[]` |
+| `FilesFormField` | `mode="single"`: `string \| null`. `mode="multiple"`: `string[]` (typed or picked URLs) | `null` / `[]` |
+| `UploadField` · `UploadFormField` | a `File`, or `File[]` with `multiple`. Nothing is uploaded | `undefined` / `[]` |
+| `LocationField` · `LocationFormField` (from `@nxgt/material/map`) | `[lat, lng]`, rounded to 7 decimals | `null` |
+
+An upload field emits a **string** because it uploads as soon as a file is
+dropped: the form holds where the file went, never the file. `UploadFormField`
+is the exception. It holds the `File`, and your submit handler sends it (with
+`convertToFormData` from `@nxgt/material/lib`, for example).
+
+## Composite values
+
+A composite field edits a structured value through its own dialog. The form
+holds the whole value. Here is `ContactsFormField` end to end: its value
+shape, a default, and a schema.
+
+```tsx
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+import {
+  Button,
+  type Contact,
+  ContactsFormField,
+  ContactType,
+  type PostalAddressFieldValue,
+  PostalAddressFormField,
+} from '@nxgt/material/components';
+
+const schema = z.object({
+  contacts: z
+    .array(
+      z.object({
+        type: z.enum(ContactType),
+        value: z.string().min(1),
+        label: z.string().nullish(),
+      }),
+    )
+    .min(1, { error: 'Add at least one contact' }),
+  address: z.object({
+    street: z.string().nullish(),
+    locality: z.string().nullish(),
+    postalCode: z.string().nullish(),
+    country: z.string().nullish(),
+  }),
+});
+
+type Values = { contacts: Contact[]; address: PostalAddressFieldValue };
+
+export function SupplierForm({ onSave }: { onSave: (values: Values) => void }) {
+  const form = useForm<Values>({
+    resolver: zodResolver(schema),
+    defaultValues: {
+      contacts: [{ type: ContactType.Email, value: 'sales@example.com', label: 'Sales' }],
+      address: { locality: 'Lyon', country: 'FR' },
+    },
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit(onSave)} className="grid gap-4">
+      <ContactsFormField control={form.control} name="contacts" label="Contacts" />
+      <PostalAddressFormField control={form.control} name="address" label="Address" />
+      <Button type="submit">Save</Button>
+    </form>
+  );
+}
+```
+
+| Wrapper | Value | Notes |
+| --- | --- | --- |
+| `ContactsFormField` | `Contact[]` | Add, edit and delete go through `ContactDialog`. `ContactType` is `EMAIL`, `FAX`, `MOBILE`, `PHONE`, `WEBSITE` |
+| `OpeningHoursFormField` | `OpeningHour[]` | `showAddAllDays` adds Monday–Friday 09:00–17:00 and a closed weekend in one click |
+| `PostalAddressFormField` | `PostalAddressFieldValue` | Deleting the address writes `{}`, not `null` |
+| `AttributesFormField` | `Attribute[]` | A typed attribute editor. Its `label` prop is required |
+
+- **The array's own error is shown under the field.** `ContactsFormField`,
+  `OpeningHoursFormField` and `AttributesFormField` display
+  `errors.<name>.message` (where a Zod `.min(1)` on the array lands) and
+  `errors.<name>.root` (where a `useFieldArray` rule lands). Errors of one
+  item are shown in its dialog.
+- `AttributesFormField` follows the form value: `form.reset()` and
+  `form.setValue()` replace the list it shows.
+- `AttributeValuesFormFieldSet` is the other half: given `attributes`, it
+  renders one input per attribute and writes `{ [attribute.name]: value }` to
+  its `name`.
+
+## Config-driven forms
+
+`FormField` renders the field that matches a config `type`, which is useful
+when the form comes from data (a CMS, a settings schema) rather than from
+code.
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { Button, type FieldConfig, FormField } from '@nxgt/material/components';
+
+type Settings = { title: string; retries: number | null; public: boolean; tier: string | null };
+
+const fields: { name: keyof Settings; config: FieldConfig }[] = [
+  { name: 'title', config: { type: 'text', label: 'Title' } },
+  { name: 'retries', config: { type: 'number', label: 'Retries' } },
+  { name: 'public', config: { type: 'switch', label: 'Public' } },
+  {
+    name: 'tier',
+    config: {
+      type: 'select',
+      label: 'Tier',
+      mode: 'single',
+      value: '',
+      options: [
+        { value: 'free', label: 'Free' },
+        { value: 'pro', label: 'Pro' },
+      ],
+    },
+  },
+];
+
+export function SettingsForm({ onSave }: { onSave: (values: Settings) => void }) {
+  const { control, handleSubmit } = useForm<Settings>({
+    defaultValues: { title: '', retries: 3, public: false, tier: null },
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSave)} className="grid gap-4">
+      {fields.map(({ name, config }) => (
+        <FormField key={name} control={control} name={name} config={config} />
+      ))}
+      <Button type="submit">Save</Button>
+    </form>
+  );
+}
+```
+
+`FieldConfig` is a union over `type`: each member takes the props of the field
+it renders. For a `select`, that is `Autocomplete`, which requires `mode` and
+`value` in the type even though `FormField` supplies the value.
+
+| `type` | Renders | Form value |
+| --- | --- | --- |
+| `text`, `textarea` | `TextField`, `TextareaField` | `string` |
+| `number` | `TextField type="number"` | `number \| null` |
+| `select`, `multi-select`, `autocomplete` | `Autocomplete` | `string \| null` / `string[]` |
+| `chips-single`, `chips-multiple` | `SelectChipField` | `string \| null` / `string[]` |
+| `radio-group`, `checkbox-group` | `RadioGroup`, `CheckboxGroup` | `string` / `string[]` |
+| `switch` | `Switch` | `boolean` |
+| `date`, `date-range`, `time` | `DateField`, `DateRangeField`, `TimeField` | `Date` / `DateRange` / `Date` |
+| `slider` | `Slider` | `number` |
+| `image` | `ImageField` | `string \| null` |
+| `upload` | `UploadFormField` | `File`, or `File[]` with `multiple` |
+| `network-upload` | `NetworkUploadFormField` | what `onUpload` resolved: `string` / `string[]` |
+| `otp` | `OtpField` | `string` |
+| `check-card`, `select-card` | `CheckCardField`, `SelectCardField` | `boolean` / `string[]` |
+| `rich-text-editor`, `code-editor` | `RichTextEditor`, `CodeEditor` | as the editor emits |
+
+Reach for it when the list of fields is data. Write the wrappers by hand when
+the form is code: they type-check each field's props against its `name`, and
+`FormField` does not. A config's `helperText` shows until the field has an
+error message to show in its place, and `useForm({ disabled })` disables every
+config field, as it does the other wrappers.
+
+`location` is listed in `FieldType` but has no config and renders
+"Unsupported field type: location": the map is browser-only and lives on its
+own entry, so the main barrel cannot render it. Use `LocationFormField` from
+`@nxgt/material/map`.
+
+`Field` is the same renderer without React Hook Form: `<Field config={…} />`,
+where the config carries `value` and `onChange` / `onValueChange` itself.
+
+## Server errors
+
+Map an API's field errors onto the form with `setError`, and put anything that
+belongs to no field under `root`, shown in an `Alert`:
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { Alert, Button, PasswordFormField, TextFormField } from '@nxgt/material/components';
+
+type Values = { email: string; password: string };
+type ApiError = { message: string; fields?: Partial<Record<keyof Values, string>> };
+
+export function SignInForm() {
+  const form = useForm<Values>({ defaultValues: { email: '', password: '' } });
+  const rootError = form.formState.errors.root?.server?.message;
+
+  const onSubmit = form.handleSubmit(async (values) => {
+    const response = await fetch('/api/sessions', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(values),
+    });
+    if (response.ok) return;
+
+    const error = (await response.json()) as ApiError;
+    for (const [name, message] of Object.entries(error.fields ?? {})) {
+      form.setError(name as keyof Values, { type: 'server', message }, { shouldFocus: true });
+    }
+    if (!error.fields) form.setError('root.server', { type: 'server', message: error.message });
+  });
+
+  return (
+    <form onSubmit={onSubmit} className="grid gap-4">
+      {rootError && <Alert variant="error" title="Could not sign in" description={rootError} />}
+      <TextFormField control={form.control} name="email" label="Email" />
+      <PasswordFormField control={form.control} name="password" label="Password" />
+      <Button type="submit" loading={form.formState.isSubmitting}>
+        Sign in
+      </Button>
+    </form>
+  );
+}
+```
+
+- A field error set this way shows under the field like a schema error, and
+  is cleared when the field is validated again.
+- `root.*` errors are **not** cleared by editing a field. They are cleared at
+  the next `handleSubmit`, or explicitly with `form.clearErrors('root')`.
+- `Alert` `variant` is one of `primary`, `secondary`, `error`, `success`,
+  `info`, `warning`, `foreground`.
+
+## Dialogs and steps
+
+### A form in a dialog
+
+`ConfirmationDialog` holds a small Zod form of its own: pass `formOptions`,
+and the confirm button stays disabled until the form is valid. Confirming
+runs the schema first, and `onConfirm` receives its parsed output, so a
+`.trim()` or `.transform()` is applied.
+
+```tsx
+import { z } from 'zod';
+import { Button, ConfirmationDialog, TextFormField } from '@nxgt/material/components';
+
+const schema = z.object({ project: z.literal('my-project') });
+
+export function DeleteProject({ onDelete }: { onDelete: () => void }) {
+  return (
+    <ConfirmationDialog
+      title="Delete project"
+      description='Type "my-project" to confirm.'
+      trigger={<Button color="error">Delete project</Button>}
+      confirmText="Delete"
+      color="error"
+      variant="tonal"
+      onConfirm={() => onDelete()}
+      formOptions={{
+        schema,
+        renderForm: ({ control }) => (
+          <TextFormField control={control} name="project" label="Project name" />
+        ),
+      }}
+    />
+  );
+}
+```
+
+- The dialog closes as soon as `onConfirm` returns; it does not wait for a
+  promise. For an async action, use `ConfirmDialog`: it stays open while
+  `onConfirm` runs, closes on success and shows the error when it throws.
+- It works with a `trigger` (uncontrolled; `onOpenChange` only observes) or
+  controlled, with `open` and `onOpenChange` from the parent.
+
+For a larger form, put your own `useForm` inside `Dialog` / `DialogContent`
+and close the dialog from the submit handler.
+
+### A multi-step form
+
+`createStepFormSlice` from `@nxgt/material/lib` holds the current `step` and
+the values collected so far. Each step is its own small form. Run the slice as
+local component state with `useSliceReducer`:
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { Button, Stepper, TextFormField } from '@nxgt/material/components';
+import { createStepFormSlice, useSliceReducer } from '@nxgt/material/lib';
+
+type Signup = { email: string; company: string };
+
+const signupSlice = createStepFormSlice<Signup>({ name: 'signup-wizard' });
+
+function EmailStep({ email, onNext }: { email?: string; onNext: (v: Pick<Signup, 'email'>) => void }) {
+  const { control, handleSubmit } = useForm({ defaultValues: { email: email ?? '' } });
+  return (
+    <form onSubmit={handleSubmit(onNext)} className="grid gap-4">
+      <TextFormField control={control} name="email" label="Email" />
+      <Button type="submit">Next</Button>
+    </form>
+  );
+}
+
+function CompanyStep({ company, onBack, onNext }: {
+  company?: string;
+  onBack: () => void;
+  onNext: (v: Pick<Signup, 'company'>) => void;
+}) {
+  const { control, handleSubmit } = useForm({ defaultValues: { company: company ?? '' } });
+  return (
+    <form onSubmit={handleSubmit(onNext)} className="grid gap-4">
+      <TextFormField control={control} name="company" label="Company" />
+      <div className="flex gap-2">
+        <Button type="button" variant="outlined" onClick={onBack}>Back</Button>
+        <Button type="submit">Finish</Button>
+      </div>
+    </form>
+  );
+}
+
+export function SignupWizard({ onDone }: { onDone: (values: Signup) => void }) {
+  const [state, { updateStep, updateFormValues, reset }] = useSliceReducer(signupSlice);
+  // The slice's state type widens `values` to `{}`; narrow it back.
+  const values = state.values as Partial<Signup>;
+  const step = state.step;
+
+  return (
+    <div className="grid gap-6">
+      <Stepper active={step} steps={[{ title: 'Account' }, { title: 'Company' }]} />
+      {step === 0 && (
+        <EmailStep
+          email={values.email}
+          onNext={(v) => {
+            updateFormValues(v);
+            updateStep((s) => s + 1);
+          }}
+        />
+      )}
+      {step === 1 && (
+        <CompanyStep
+          company={values.company}
+          onBack={() => updateStep((s) => s - 1)}
+          onNext={(v) => {
+            onDone({ ...values, ...v } as Signup);
+            reset();
+          }}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+```ts
+type StepFormState<T> = { isDirty: boolean; step: number; values: Partial<T> };
+
+createStepFormSlice<T>({ name, initialState?: Partial<T>, reducers?, selectors? });
+// actions: updateStep(FunctionOr<number>), updateFormValues(FunctionOr<Partial<T>>), reset()
+```
+
+- `updateFormValues` **merges** into `values`, so each step only sends its own
+  fields. `values` is `Partial<T>`: read it as possibly incomplete until the
+  last step.
+- `updateStep` writes the whole state, values included, to `localStorage`
+  under the slice `name`, and the slice's initial state reads it back (when
+  `useSliceReducer` mounts or a store is created): after a reload the wizard
+  resumes at the stored step with the stored values. `reset()` clears it. Two
+  wizards with the same `name` share that entry, so give each its own. It is
+  stored in clear text: keep passwords and secrets out of a step form's values.
+- Nothing is read on a server, so an SSR page renders step 0. A client
+  hydrating that page renders step 0 too, then resumes at the stored step once
+  mounted, so hydration matches with no `clientOnly`; a page rendered only in
+  the browser shows the stored step from its first render. That is
+  `useSliceReducer`'s doing.
+- The same slice works in a Redux store (`configureStore({ reducer: {
+  signup: signupSlice.reducer } })`) when the steps live on different routes.
+  A store created in the browser reads the storage when it is created, so in
+  an SSR app preload the server's state and resume after hydrating:
+
+  ```tsx
+  import { configureStore } from '@reduxjs/toolkit';
+  import { useEffect } from 'react';
+  import { useDispatch } from 'react-redux';
+  import { safeGetItem } from '@nxgt/material/lib';
+
+  const store = configureStore({
+    reducer: { signup: signupSlice.reducer },
+    // What the server rendered: step 0, no values.
+    preloadedState: { signup: { isDirty: false, step: 0, values: {} } },
+  });
+
+  function ResumeSignup() {
+    const dispatch = useDispatch();
+    useEffect(() => {
+      const stored = safeGetItem<{ step?: unknown; values?: object } | null>(
+        'signup-wizard',
+        null,
+      );
+      if (typeof stored?.step !== 'number' || !stored.values) return;
+      dispatch(signupSlice.actions.updateFormValues(stored.values));
+      dispatch(signupSlice.actions.updateStep(stored.step));
+    }, [dispatch]);
+    return null;
+  }
+
+  // Inside <Provider store={store}>, beside the wizard: <ResumeSignup />
+  ```
+
+## Filters are forms too
+
+`FilterFormField` puts a schema-driven filter panel (inline, dialog, sheet,
+drawer or popover) into a form as one value: `FilterValues`, a record keyed by
+field `id`.
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { FilterFormField, type FilterSchema, type FilterValues } from '@nxgt/material/components';
+
+const schema: FilterSchema = {
+  fields: [
+    { id: 'q', type: 'text', label: 'Search' },
+    {
+      id: 'status',
+      type: 'checkbox-group',
+      label: 'Status',
+      options: [
+        { value: 'open', label: 'Open' },
+        { value: 'closed', label: 'Closed' },
+      ],
+    },
+  ],
+};
+
+export function ReportFilters() {
+  const { control } = useForm<{ filters: FilterValues }>({ defaultValues: { filters: {} } });
+  return <FilterFormField control={control} name="filters" schema={schema} variant="popover" />;
+}
+```
+
+The filter types, presets, persistence and the standalone `Filter` are on the
+[Data table, filter & lists](../components/data-table-filter-and-lists.md)
+page. The type for one field of the schema is exported as
+`FilterFieldSchema`, because `FilterField` is the component.
+
+## Traps
+
+**A wrapper needs the `control` of its own form.** Wrappers do not read a
+`FormProvider`. Pass `control` from the `useForm` that owns the field; a
+`control` from another form writes into that other form.
+
+```tsx
+<TextFormField control={form.control} name="email" label="Email" />
+```
+
+**`Button` does not submit by default.** It renders `type="button"`, so a
+form whose button has no `type` never calls `handleSubmit`.
+
+```tsx
+<Button type="submit">Save</Button>
+```
+
+**The default value must have the emitted type.** A `DateFormField` given
+`'2026-01-31'` or a `NumberFormField` given `'3'` does not render the value,
+or fails the schema on submit. Convert API data before `reset()`.
+
+```ts
+form.reset({ ...invoice, issuedAt: new Date(invoice.issuedAt) });
+```
+
+**A checkbox with no default is indeterminate.** `CheckboxFormField` renders
+`undefined` as the indeterminate state (and writes `null` for it).
+
+```ts
+useForm({ defaultValues: { terms: false } });
+```
+
+**A field disabled through React Hook Form is left out of the submitted
+values.** React Hook Form removes the fields it considers disabled (for
+example, fields registered while `useForm({ disabled: true })`) from the values
+`handleSubmit` passes you. A wrapper that honours a `disabled` *prop* only
+disables the input; React Hook Form does not know, and the value is still
+submitted. For a read-only value that must be sent, use that prop, or
+`readOnly` where the field has one.
+
+**An empty text field is `''`, not missing.** `z.string()` accepts `''`, so
+"required" never fires for a cleared input. Add `.min(1, …)`:
+
+```ts
+z.object({ name: z.string().min(1, { error: 'Required' }) });
+```
+
+**A field re-mounted on every render loses its state.** Declaring a component
+inside another component's body, or a `key` that changes on each render
+(`key={Math.random()}`), mounts a new field every time: focus, the
+`PhoneField` draft and the `NumberField` text are lost as you type. Declare
+step and field components at module level, as in
+[A multi-step form](#a-multi-step-form), and use stable keys.
+
+**Zod messages on a server are English.** `zodLocaleError()` reads the
+language from `localStorage`, which a server does not have. Pass
+`zodLocaleError({ language })` where you know the request's language. See
+[Validation messages](#validation-messages).