@nxgt/material-vue 0.21.0 → 0.23.0

package/docs/guides/forms.md

@@ -0,0 +1,960 @@
+# Forms
+
+This page shows how the fields in `@nxgt/material-vue` are wired into a form
+with vee-validate 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.
+
+`vee-validate` (`^4.15`) is a required peer. Zod v4 is a dependency of the
+package; add it to your own app too, since your schemas import it:
+
+```bash
+bun add vee-validate zod
+```
+
+Do not add `@vee-validate/zod`: its current release is written for Zod 3 and
+throws on a Zod 4 union error. A ten-line adapter replaces it, see
+[The schema adapter](#the-schema-adapter).
+
+## The pair
+
+Every field ships twice, in the same barrel:
+
+- a **standalone field** (`TextField`) that you bind yourself with `v-model`;
+- a **form wrapper** (`TextFormField`) that takes a `name` and reads
+  everything else from the vee-validate form around it.
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { ref } from 'vue';
+import { TextField, TextFormField } from '@nxgt/material-vue/components';
+
+// Standalone: you own the state. TextField emits `string | number`.
+const name = ref<string | number>('');
+
+// Inside a form: the wrapper reads and writes the form value called `fullName`.
+useForm({ initialValues: { fullName: '' } });
+</script>
+
+<template>
+  <TextField v-model="name" label="Name" />
+  <TextFormField name="fullName" label="Name" />
+</template>
+```
+
+What a wrapper does for you, through `useField(() => props.name)`:
+
+| Field prop | Set to |
+| --- | --- |
+| `v-model` | the form value at `name`, written back as the type in [What each field emits](#what-each-field-emits) |
+| `error` | `true` when the field has an error message, or is touched and invalid (the red border) |
+| `helperText` | the field's error message, or your own `helperText` when there is none |
+| `name` | the `name` you passed, also used as the native `name` |
+| `id` | passed through; `RadioGroupField` and `CheckboxGroup` generate one when absent, and a group's option *i* is `` `${id}-${i}` `` |
+| everything else | your props, passed through unchanged (`label`, `disabled`, `options`, …) |
+
+`RadioGroupFormField` and `CheckboxGroupFormField` need nothing more for a
+screen reader: the field names its `radiogroup` / `group` by the `label`
+(`` `${id}-label` ``) and describes it by the helper or error text
+(`` `${id}-helper` ``), so the question and the error are announced with the
+group. A checkbox `group` in error with no message yet is also described by a
+hidden "This value is not valid.", inside your `helper-text`.
+
+Every wrapper has the same shape: `name`, plus the field's own props minus the
+ones the wrapper sets.
+
+```ts
+import type { TextFieldProps } from '@nxgt/material-vue/components';
+
+type TextFormFieldProps = { name: string } & Omit<TextFieldProps, 'modelValue' | 'error' | 'name'>;
+```
+
+A wrapper finds its form through Vue's provide / inject: it must be rendered
+**inside the component that calls `useForm`** (or one of its descendants).
+There is no `control` to pass. The form validates a field each time its value
+changes, and every field is marked touched on submit.
+
+### Touched on blur
+
+Every wrapper also marks its field **touched when focus leaves it**, and
+validates it then, as vee-validate's own `<Field>` does by default
+(`validateOnBlur: true`). So `meta.touched` flips as the user moves on, and
+an empty required field shows its message without being typed in.
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { TextFormField } from '@nxgt/material-vue/components';
+
+// A Zod schema works the same: see "The schema adapter" below
+useForm({
+  initialValues: { name: '' },
+  validationSchema: { name: (value: string) => Boolean(value) || 'Required' },
+});
+</script>
+
+<template>
+  <!-- Tab into the field, then out: "Required" appears, and meta.touched is true -->
+  <TextFormField name="name" label="Name" />
+</template>
+```
+
+"Leaving" is one rule for every shape of field:
+
+| The field | Touched when |
+| --- | --- |
+| one input (`TextFormField`, `NumberFormField`, `SwitchFormField`, …) | its input loses focus, as a native `blur` |
+| several controls (`DateRangeFormField`, `SliderFormField` with two thumbs, `OtpFormField`, `PhoneFormField`, `TransferListFormField`, …) | focus leaves all of them; moving between them is not leaving |
+| a picker (`SelectFormField`, `DateFormField`, `TimeFormField`, `ComboboxFormField`, `CountryFormField`, …) | 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-vue/map`) | focus leaves its buttons and the dialog they open |
+| an upload (`UploadFormField`, `NetworkUploadFormField`, `ImageFormField`, `FileListFormField` and their S3 variants) | focus leaves the drop zone and its buttons. Choosing a file in the browser's own dialog is not leaving |
+| `RichTextEditorFormField` | focus leaves the editor and its toolbar |
+| `FilterFormField` | the filter is applied (or on every change, with `live-update`) — 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 on `<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.
+
+Nothing else about validation timing changed: a value change still validates,
+and `handleSubmit` still marks every field touched. A global
+`configure({ validateOnBlur: false })` is not read by the wrappers (vee-validate
+does not expose its config); they always validate on blur.
+
+To show a field's error only once it has been touched, read the flag with
+vee-validate's `useIsFieldTouched`:
+
+```ts
+import { useIsFieldTouched } from 'vee-validate';
+
+const nameTouched = useIsFieldTouched('name');
+```
+
+## A complete form
+
+A schema, the adapter, typed initial values, three kinds of field and a
+submit button that shows progress:
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { z } from 'zod';
+import {
+  Button,
+  NumberFormField,
+  SelectFormField,
+  TextFormField,
+} from '@nxgt/material-vue/components';
+import { toTypedSchema } from './to-typed-schema';
+
+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 Values = z.output<typeof schema>; // seats: number
+
+const props = defineProps<{ onSave: (values: Values) => Promise<void> }>();
+
+const plans = [
+  { value: 'starter', label: 'Starter' },
+  { value: 'team', label: 'Team' },
+  { value: 'enterprise', label: 'Enterprise' },
+];
+
+const { handleSubmit, isSubmitting } = useForm({
+  validationSchema: toTypedSchema(schema),
+  initialValues: { email: '', seats: 1, plan: 'team' },
+});
+
+// `values` is the schema's output; the promise keeps `isSubmitting` true.
+const onSubmit = handleSubmit((values) => props.onSave(values));
+</script>
+
+<template>
+  <form class="grid gap-4" @submit="onSubmit">
+    <TextFormField name="email" label="Email" type="email" required />
+    <NumberFormField name="seats" label="Seats" :min="1" :max="50" />
+    <SelectFormField name="plan" label="Plan" :options="plans" />
+    <Button type="submit" :loading="isSubmitting">Subscribe</Button>
+  </form>
+</template>
+```
+
+- **Two types, on purpose.** The form holds the schema's *input* type while
+  the user types (`seats` is `null` once the input is cleared); `handleSubmit`
+  receives its *output* (`seats: number`), transforms applied. The
+  `nullable().pipe(…)` makes the input type match what `NumberFormField`
+  emits, and a cleared field fails with "This field is required.".
+- `handleSubmit(fn)` returns the submit listener: it calls `preventDefault()`,
+  validates, and calls `fn` only when the form is valid. `isSubmitting` stays
+  `true` until the promise `fn` returns settles.
+- `Button` defaults to `type="button"`: the submit button needs
+  `type="submit"`. `loading` shows a spinner and disables it; pass it
+  `isSubmitting`.
+- Initial values must have the type the field emits. See
+  [What each field emits](#what-each-field-emits).
+
+### The schema adapter
+
+vee-validate 4 takes a *typed schema*: an object with a `parse` method that
+returns the parsed value or the errors by field path. Put this file in your
+app once and pass every Zod schema through it:
+
+```ts
+// to-typed-schema.ts
+import type { TypedSchema, TypedSchemaError } from 'vee-validate';
+import type { z } from 'zod';
+
+/** A Zod 4 schema as a vee-validate typed schema: input type in, output type out. */
+export function toTypedSchema<S extends z.ZodType>(
+  schema: S,
+): TypedSchema<z.input<S>, z.output<S>> {
+  return {
+    __type: 'VVTypedSchema',
+    async parse(values) {
+      const result = await schema.safeParseAsync(values);
+      if (result.success) return { value: result.data, errors: [] };
+
+      const errors = new Map<string, TypedSchemaError>();
+      for (const issue of result.error.issues) {
+        // ['contacts', 0, 'value'] -> 'contacts[0].value', vee-validate's path syntax
+        const path = issue.path
+          .map((key, index) =>
+            typeof key === 'number' ? `[${key}]` : index === 0 ? String(key) : `.${String(key)}`,
+          )
+          .join('');
+        const entry = errors.get(path) ?? { path: path || undefined, errors: [] };
+        entry.errors.push(issue.message);
+        errors.set(path, entry);
+      }
+      return { errors: [...errors.values()] };
+    },
+  };
+}
+```
+
+`useForm({ validationSchema: toTypedSchema(schema) })` then infers the form
+values from `z.input` and the submitted values from `z.output`. The package's
+own built-in forms (the attribute editor, for one) use the same shape
+internally.
+
+## Validation messages
+
+`zodLocaleError()` from `@nxgt/material-vue/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:
+
+```ts
+// main.ts
+import { z } from 'zod';
+import { zodLocaleError } from '@nxgt/material-vue/lib';
+
+z.config({ customError: zodLocaleError() });
+```
+
+It is safe on a server: where there is no `localStorage`, or it cannot be
+read, it writes English. In Nuxt, a plugin (`plugins/zod-messages.ts`, inside
+`defineNuxtPlugin(() => { … })`) installs it on both sides; pass `language`
+to use the request's language on the server (see below).
+
+Then, for these schemas:
+
+| Input | English | French |
+| --- | --- | --- |
+| `email: 'nope'` for `z.email()` | `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, or `null` / `''` / `0` given to a schema of another type (`seats: null` for `z.number()`) | `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 state.
+- Three options line it up with your i18n: `storageKey` (the `storage-key`
+  you gave `I18nProvider`), `language` (a language, or a function returning
+  one, used instead of storage: the request's language on a server) and
+  `translate` (your merged translator, so your `material.zod.*` overrides
+  apply). See [i18n](i18n.md#zod-messages):
+
+  ```ts
+  import { z } from 'zod';
+  import { zodLocaleError } from '@nxgt/material-vue/lib';
+  import { translate } from './i18n'; // createTranslator(mergeResources(...))
+
+  z.config({ customError: zodLocaleError({ storageKey: 'lang', translate }) });
+  ```
+
+- 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
+  (`validate()` from `useForm` re-runs it).
+- `invalid_type` with an empty input (`undefined`, `null`, `''`, `0`,
+  `false`) says `This field is required.`; with any other input it says
+  what was expected (`z.number()` given `'x'` gives
+  `This value must be a number.`, `Un nombre est attendu.` in French). A type
+  with no string of its own (a map, a set) gets
+  `This value has the wrong type.`
+
+## What each field emits
+
+The value a wrapper writes into the form, read from each field's
+`update:modelValue` in the source. **Initial 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 initial value |
+| --- | --- | --- |
+| `TextField` · `TextFormField` | `string`. With `type="number"`: `number`, and `''` when cleared (Vue's `v-model` number cast) | `''` |
+| `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. `currency` (default `'EUR'`) is display | `null` |
+| `PhoneField` · `PhoneFormField` | E.164 `string` (`'+33612345678'`), or `null` while the number is not yet a possible one. `default-country` is `'FR'` | `null` |
+| `UrlField` · `UrlFormField` | `string` (as typed) | `''` |
+| `SearchField` · `SearchFormField` | `string`, on every keystroke. `debounce-ms` (default `0`) delays only the `value-change` event | `''` |
+| `ColorField` · `ColorFormField` | `string` (hex, `'#1e293b'`), written when a valid colour is committed | `''` |
+| `OtpField` · `OtpFormField` | `string` of up to `length` (default 6) characters | `''` |
+| `InputGroupField` · `InputGroupFormField` | `string` | `''` |
+| `InlineEdit` | `string`, written on save only. No form wrapper: bind it with `useField` | `''` |
+| `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` |
+| `SliderField` · `SliderFormField` | `number` when the value is a number; `number[]` when it is an array (a range) | `0` / `[20, 80]` |
+| `SwitchField` · `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 }` | `[]` |
+| `AttributeValuesFormFieldSet` | `Record<string, any>`: `{ [attribute.name]: value }` for the `attributes` you pass | `{}` |
+
+### Date & time
+
+| Field · wrapper | Form value | Empty initial value |
+| --- | --- | --- |
+| `DateField` · `DateFormField` | `Date \| undefined` (not an ISO string) | `undefined` |
+| `DateRangeField` · `DateRangeFormField` | `DateRange \| undefined`: `{ from?: Date; to?: Date }` | `undefined` |
+| `TimeField` · `TimeFormField` | `Date \| undefined`. There is no string mode: format it yourself on submit | `undefined` |
+| `DurationField` · `DurationFormField` | `number \| null`: total minutes (hours × 60 + minutes) | `null` |
+
+### Selection & choice
+
+| Field · wrapper | Form value | Empty initial value |
+| --- | --- | --- |
+| `SelectField` · `SelectFormField` | `string` (an option `value`) | `''` |
+| `ComboboxField` · `ComboboxFormField` | `string \| null`; picking the selected option again clears it | `null` |
+| `Autocomplete` · `AutocompleteFormField` | `mode="single"` (default): `string \| null`. `mode="multiple"`: `string[]` | `null` / `[]` |
+| `Checkbox` | `boolean` (`'indeterminate'` / `null` for the third state). No form wrapper: use `SwitchFormField`, or bind it with `useField` | `false` |
+| `CheckboxGroup` · `CheckboxGroupFormField` | `string[]` | `[]` |
+| `RadioGroupField` · `RadioGroupFormField` | `string` | `''` |
+| `CheckCardField` · `CheckCardFormField` | `boolean`: `true` for the first card, `false` for the second | `false` |
+| `SelectCardField` · `SelectCardFormField` | `string[]` in both modes. `mode="single"` (default) holds `[]` or `[value]` | `[]` |
+| `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 initial value |
+| --- | --- | --- |
+| `NetworkUploadField` · `NetworkUploadFormField` | `mode="single"`: the `string` your `on-upload` resolved (a URL or a key), or `undefined` after removal. `mode="multiple"`: `string[]` | `undefined` / `[]` |
+| `S3UploadField` · `S3UploadFormField` | as above; the value is `publicUrl` from `get-presigned-url` | `undefined` / `[]` |
+| `ImageField`, `ImageS3Field` · `ImageFormField`, `ImageS3FormField` | `string \| undefined` (the uploaded URL) | `undefined` |
+| `FileListField`, `FileListS3Field` · `FileListFormField`, `FileListS3FormField` | `string[]` | `[]` |
+| `UploadField` · `UploadFormField` | a `File`, or `File[]` with `multiple`. Nothing is uploaded | `undefined` / `[]` |
+| `RichTextEditor` · `RichTextEditorFormField` | `string`: the editor's HTML | `''` |
+| `LocationField` · `LocationFormField` (from `@nxgt/material-vue/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-vue/lib`,
+for example).
+
+Not in `@nxgt/material-vue`: `FilesFormField` (use `NetworkUploadFormField`
+or `FileListFormField`) and `CheckboxFormField` / `InlineEditFormField` (see
+the rows above).
+
+## 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, with a postal
+address beside it: the value shape, initial values, and a schema.
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { z } from 'zod';
+import {
+  Button,
+  type Contact,
+  ContactsFormField,
+  ContactType,
+  type PostalAddressFieldValue,
+  PostalAddressFormField,
+} from '@nxgt/material-vue/components';
+import { toTypedSchema } from './to-typed-schema';
+
+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(),
+    region: z.string().nullish(),
+    postalCode: z.string().nullish(),
+    country: z.string().nullish(),
+  }),
+});
+
+type Values = { contacts: Contact[]; address: PostalAddressFieldValue };
+
+const emit = defineEmits<{ save: [values: Values] }>();
+
+const { handleSubmit } = useForm({
+  validationSchema: toTypedSchema(schema),
+  initialValues: {
+    contacts: [{ type: ContactType.Email, value: 'sales@example.com', label: 'Sales' }],
+    address: { locality: 'Lyon', country: 'FR' },
+  },
+});
+
+const onSubmit = handleSubmit((values) => emit('save', values));
+</script>
+
+<template>
+  <form class="grid gap-4" @submit="onSubmit">
+    <ContactsFormField name="contacts" label="Contacts" />
+    <PostalAddressFormField name="address" label="Address" />
+    <Button type="submit">Save</Button>
+  </form>
+</template>
+```
+
+| Wrapper | Value | Notes |
+| --- | --- | --- |
+| `ContactsFormField` | `Contact[]` | Add, edit and delete go through `ContactDialog`. `ContactType` is `EMAIL`, `FAX`, `MOBILE`, `PHONE`, `WEBSITE` |
+| `OpeningHoursFormField` | `OpeningHour[]` | `show-add-all-days` 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; a `value` prop, when passed, is shown instead of the form value; `helper-text` shows when there is no error. It follows `resetForm()` and `setFieldValue()` |
+
+- **The array's own error is shown under the field.** `ContactsFormField`,
+  `OpeningHoursFormField`, `PostalAddressFormField` and
+  `AttributesFormField` display the error at `name` (where a Zod `.min(1)` on
+  the array lands). An error on one item (`contacts[0].value`) is not shown by
+  the wrapper; the item's dialog validates its own fields.
+- `AttributeValuesFormFieldSet` is the other half of the attribute editor:
+  given `attributes`, it renders one input per attribute and writes
+  `{ [attribute.name]: value }` to its `name`. Its starting values come from
+  its `default-values` prop, not from the form.
+
+## Config-driven forms
+
+`Field` 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.
+There is no config-driven *form* wrapper in `@nxgt/material-vue`: register
+each config with the form through `defineField`, and let `v-model` fall
+through to the rendered field.
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { reactive } from 'vue';
+import { Button, Field, type FieldConfig } from '@nxgt/material-vue/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', min: 0 } },
+  { name: 'public', config: { type: 'switch', label: 'Public' } },
+  {
+    name: 'tier',
+    config: {
+      type: 'select',
+      label: 'Tier',
+      options: [
+        { value: 'free', label: 'Free' },
+        { value: 'pro', label: 'Pro' },
+      ],
+    },
+  },
+];
+
+const emit = defineEmits<{ save: [values: Settings] }>();
+
+const { defineField, errors, handleSubmit } = useForm<Settings>({
+  initialValues: { title: '', retries: 3, public: false, tier: null },
+});
+
+// One model per config, registered with the form. `reactive` unwraps the refs,
+// so `v-model="models[name]"` writes into the form.
+const models = reactive(
+  Object.fromEntries(fields.map(({ name }) => [name, defineField(name)[0]])),
+);
+
+const onSubmit = handleSubmit((values) => emit('save', values));
+</script>
+
+<template>
+  <form class="grid gap-4" @submit="onSubmit">
+    <Field
+      v-for="{ name, config } in fields"
+      :key="name"
+      v-model="models[name]"
+      :config="config"
+      v-bind="errors[name] ? { error: true, helperText: errors[name] } : {}"
+    />
+    <Button type="submit">Save</Button>
+  </form>
+</template>
+```
+
+`FieldConfig` is a union over `type`: each member takes the props of the
+field it renders. `v-model`, `error` and `helperText` are not `Field` props;
+they fall through to the rendered field, and override the config's own
+`helperText` while there is an error (hence the conditional `v-bind`). With
+`strictTemplates` on, `vue-tsc` flags that `v-model` as an unknown prop.
+
+| `type` | Renders | Form value |
+| --- | --- | --- |
+| `text`, `textarea` | `TextField`, `TextareaField` | `string` |
+| `number` | `NumberField` | `number \| null` |
+| `select`, `multi-select`, `autocomplete` | `Autocomplete` (`single`, `multiple`, or your `mode`) | `string \| null` / `string[]` |
+| `chips-single`, `chips-multiple` | `SelectChipField` | `string[]` |
+| `radio-group`, `checkbox-group` | `RadioGroupField`, `CheckboxGroup` | `string` / `string[]` |
+| `switch` | `SwitchField` | `boolean` |
+| `date`, `date-range`, `time` | `DateField`, `DateRangeField`, `TimeField` | `Date` / `DateRange` / `Date` |
+| `slider` | `SliderField` | `number` (or `number[]` for a range) |
+| `image` | `ImageField` | `string \| undefined` |
+| `upload` | `UploadField` | `File`, or `File[]` with `multiple` |
+| `network-upload` | `NetworkUploadField` | what `on-upload` 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 show the error for you and type-check each field's
+props, and `Field` does neither.
+
+`location` is listed in `FieldType` but is not a `FieldConfig` member and
+`Field` has no renderer for it: the map lives on its own entry, so the main
+barrel cannot render it. Use `LocationFormField` from
+`@nxgt/material-vue/map`.
+
+## Server errors
+
+Map an API's field errors onto the form with `setErrors` (or `setFieldError`
+for one field), and keep an error that belongs to no field in your own state,
+shown in an `Alert`:
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { ref } from 'vue';
+import { Alert, Button, PasswordFormField, TextFormField } from '@nxgt/material-vue/components';
+
+type Values = { email: string; password: string };
+type ApiError = { message: string; fields?: Partial<Record<keyof Values, string>> };
+
+const { handleSubmit, isSubmitting } = useForm<Values>({
+  initialValues: { email: '', password: '' },
+});
+const serverError = ref<string | null>(null);
+
+const onSubmit = handleSubmit(async (values, { setErrors }) => {
+  serverError.value = null;
+  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;
+  if (error.fields) setErrors(error.fields);
+  else serverError.value = error.message;
+});
+</script>
+
+<template>
+  <form class="grid gap-4" @submit="onSubmit">
+    <Alert v-if="serverError" variant="error" title="Could not sign in" :description="serverError" />
+    <TextFormField name="email" label="Email" />
+    <PasswordFormField name="password" label="Password" />
+    <Button type="submit" :loading="isSubmitting">Sign in</Button>
+  </form>
+</template>
+```
+
+- `setErrors` and `setFieldError` are on the second argument of the
+  `handleSubmit` callback, and on the object `useForm` returns. A field error
+  set this way shows under the field like a schema error, and is replaced the
+  next time that field is validated (its next change).
+- The form-level message is yours: clear it at the start of the next submit,
+  as above.
+- `Alert` `variant` is one of `primary` (default), `secondary`, `error`,
+  `success`, `info`, `warning`, `foreground`.
+
+## Dialogs and steps
+
+### A form in a dialog
+
+Put the form inside `Dialog` / `DialogContent`, in the component that calls
+`useForm`: the dialog content is teleported, but the wrappers still find the
+form, because injection follows the component tree. Close the dialog from the
+submit handler.
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { ref } from 'vue';
+import { z } from 'zod';
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+  TextFormField,
+} from '@nxgt/material-vue/components';
+import { toTypedSchema } from './to-typed-schema';
+
+const emit = defineEmits<{ delete: [] }>();
+const open = ref(false);
+
+const { handleSubmit, meta, resetForm } = useForm({
+  validationSchema: toTypedSchema(z.object({ project: z.literal('my-project') })),
+  initialValues: { project: '' },
+});
+
+const onSubmit = handleSubmit(() => {
+  emit('delete');
+  open.value = false;
+  resetForm();
+});
+</script>
+
+<template>
+  <Dialog v-model:open="open">
+    <DialogTrigger as-child>
+      <Button color="error">Delete project</Button>
+    </DialogTrigger>
+    <DialogContent>
+      <form class="grid gap-4" @submit="onSubmit">
+        <DialogHeader>
+          <DialogTitle>Delete project</DialogTitle>
+          <DialogDescription>Type "my-project" to confirm.</DialogDescription>
+        </DialogHeader>
+        <TextFormField name="project" label="Project name" />
+        <DialogFooter>
+          <Button type="submit" color="error" :disabled="!meta.valid">Delete</Button>
+        </DialogFooter>
+      </form>
+    </DialogContent>
+  </Dialog>
+</template>
+```
+
+- `meta.valid` keeps the button disabled until the schema passes; the form
+  runs a silent validation when it mounts, so it starts disabled.
+- `ConfirmationDialog` has no form of its own in `@nxgt/material-vue`: it
+  renders its default slot above Cancel / Confirm and emits `confirm`, then
+  closes. Use it for a plain confirmation, and the pattern above when the
+  user has to type something.
+- `ConfirmDialog` (controlled: `open` is required) awaits its `@confirm`
+  handler: while the promise is pending both buttons are disabled and the
+  confirm button reads "Processing..." (`material.confirm-dialog.processing`);
+  it closes on success and, on a throw or a rejection, stays open showing the
+  error's message (or `material.confirm-dialog.failed`). Its `loading` prop
+  disables both buttons too, for work you track yourself.
+
+### A multi-step form
+
+`defineStepFormStore` from `@nxgt/material-vue/lib` holds the current `step`
+and the values collected so far, in a Pinia store (Pinia must be installed).
+Each step is its own component with its own small `useForm`:
+
+```ts
+// signup.ts
+import { defineStepFormStore } from '@nxgt/material-vue/lib';
+
+export type Signup = { email: string; company: string };
+
+export const useSignupWizard = defineStepFormStore<Signup>('signup-wizard');
+```
+
+```vue
+<!-- EmailStep.vue -->
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { Button, TextFormField } from '@nxgt/material-vue/components';
+import type { Signup } from './signup';
+
+const props = defineProps<{ email?: string }>();
+const emit = defineEmits<{ next: [values: Pick<Signup, 'email'>] }>();
+
+const { handleSubmit } = useForm({ initialValues: { email: props.email ?? '' } });
+const onSubmit = handleSubmit((values) => emit('next', values));
+</script>
+
+<template>
+  <form class="grid gap-4" @submit="onSubmit">
+    <TextFormField name="email" label="Email" />
+    <Button type="submit">Next</Button>
+  </form>
+</template>
+```
+
+```vue
+<!-- CompanyStep.vue -->
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { Button, TextFormField } from '@nxgt/material-vue/components';
+import type { Signup } from './signup';
+
+const props = defineProps<{ company?: string }>();
+const emit = defineEmits<{ back: []; next: [values: Pick<Signup, 'company'>] }>();
+
+const { handleSubmit } = useForm({ initialValues: { company: props.company ?? '' } });
+const onSubmit = handleSubmit((values) => emit('next', values));
+</script>
+
+<template>
+  <form class="grid gap-4" @submit="onSubmit">
+    <TextFormField name="company" label="Company" />
+    <div class="flex gap-2">
+      <Button variant="outlined" @click="emit('back')">Back</Button>
+      <Button type="submit">Finish</Button>
+    </div>
+  </form>
+</template>
+```
+
+```vue
+<!-- SignupWizard.vue -->
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Stepper } from '@nxgt/material-vue/components';
+import CompanyStep from './CompanyStep.vue';
+import EmailStep from './EmailStep.vue';
+import { type Signup, useSignupWizard } from './signup';
+
+const emit = defineEmits<{ done: [values: Signup] }>();
+
+// One store per component instance: two wizards on a page do not share state.
+const wizard = useSignupWizard();
+const values = computed(() => wizard.values as Partial<Signup>);
+
+function next(part: Partial<Signup>) {
+  wizard.updateFormValues(part);
+  wizard.updateStep((step: number) => step + 1);
+}
+
+function finish(part: Pick<Signup, 'company'>) {
+  emit('done', { ...values.value, ...part } as Signup);
+  wizard.reset();
+}
+</script>
+
+<template>
+  <div class="grid gap-6">
+    <Stepper :active="wizard.step" :steps="[{ title: 'Account' }, { title: 'Company' }]" />
+    <EmailStep v-if="wizard.step === 0" :email="values.email" @next="next" />
+    <CompanyStep
+      v-else
+      :company="values.company"
+      @back="wizard.updateStep((step: number) => step - 1)"
+      @next="finish"
+    />
+  </div>
+</template>
+```
+
+```ts
+type StepFormState<T> = { isDirty: boolean; step: number; values: Partial<T> };
+
+defineStepFormStore<T>(name, initialValues?: Partial<T>, extraActions?);
+// returns useStore(initialState?) -> store with state + updateStep(FunctionOr<number>),
+// updateFormValues(FunctionOr<Partial<T>>), reset()
+```
+
+- Call the returned `useSignupWizard()` inside `setup`: each call gets its own
+  store id, so the state is per wizard, not global. The store is typed `any`;
+  narrow `values` as above.
+- `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 `name`, and a new store reads it back: 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 and resumes at the stored step once
+  mounted, so hydration matches with no `clientOnly`; a page rendered only in
+  the browser, or a store made outside a component, reads the stored step
+  straight away.
+- One `useForm` per step component, not one for the whole wizard: a field
+  that unmounts removes its value from the form (see [Traps](#traps)).
+
+## 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`.
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import {
+  FilterFormField,
+  type FilterSchema,
+  type FilterValues,
+} from '@nxgt/material-vue/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' },
+      ],
+    },
+  ],
+};
+
+useForm<{ filters: FilterValues }>({ initialValues: { filters: {} } });
+</script>
+
+<template>
+  <FilterFormField name="filters" :schema="schema" variant="popover" />
+</template>
+```
+
+The form value follows every change in the panel, with empty entries removed;
+applying the panel (or any change, with `live-update`) also marks the field
+touched. 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 a form above it.** A `*FormField` finds its form by
+injection. Rendered by a parent or a sibling of the component that calls
+`useForm`, it gets no form and keeps a value of its own that is never
+submitted, with no error. Call `useForm` in the component whose template (or
+a descendant) renders the wrappers. Two `useForm` calls in one component: the
+wrappers see the last one.
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { TextFormField } from '@nxgt/material-vue/components';
+
+useForm({ initialValues: { email: '' } });
+</script>
+
+<template>
+  <TextFormField name="email" label="Email" />
+</template>
+```
+
+**`Button` does not submit by default.** It renders `type="button"`, so a
+form whose button has no `type` never calls `handleSubmit`.
+
+```vue
+<Button type="submit">Save</Button>
+```
+
+**The initial 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 `resetForm()`.
+
+```ts
+resetForm({ values: { ...invoice, issuedAt: new Date(invoice.issuedAt) } });
+```
+
+**A field that unmounts takes its value with it.** vee-validate removes the
+value of a field when its component unmounts (a `v-if`, a tab, a step), so it
+is missing from what `handleSubmit` receives. Give each step its own form, as
+in [A multi-step form](#a-multi-step-form), or keep the values:
+
+```ts
+useForm({ keepValuesOnUnmount: true });
+```
+
+**A `disabled` wrapper is still submitted.** The wrappers pass `disabled` to
+the input only; vee-validate does not know, and the value is in the submitted
+values. Leave it out yourself when it must not be sent.
+
+**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 single-mode card or chip field holds an array.** `SelectCardFormField`
+and `SelectChipFormField` write `[]` or `[value]` even with `mode="single"`.
+Type the schema as an array:
+
+```ts
+z.object({ plan: z.array(z.string()).length(1, { error: 'Pick a plan' }) });
+```
+
+**A field re-mounted on every render loses its state.** 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, and
+the form drops the value (see above). Use stable keys.
+
+**Server-side Zod messages are English.** `z.config` is global to the
+process, and a server has no `localStorage`, so `zodLocaleError()` writes
+English there (in 0.21.0 and earlier it threw
+`ReferenceError: localStorage is not defined`). Pass
+`zodLocaleError({ language: () => requestLanguage() })` where the server
+knows the request's language. See [Validation messages](#validation-messages).