@nxgt/material-vue 0.35.0 → 0.37.0

package/docs/components/README.md

@@ -26,7 +26,7 @@ Anything you press that is not a field: buttons, link buttons, copy, load more,
 
 ## [Form fields](form-fields.md)
 
-Labelled inputs with a value, each with its form-library wrapper, and the composite values (attributes, contacts, address, opening hours). 24 entries.
+Labelled inputs with a value, each with its form-library wrapper, and the composite values (attributes, contacts, address, opening hours), and the titled sections a long form is laid out in. 25 entries.
 
 [<img src="../previews/form-fields-textfield.webp" height="72" alt="TextField">](form-fields.md#textfield)
 [<img src="../previews/form-fields-phonefield.webp" height="72" alt="PhoneField">](form-fields.md#phonefield)
@@ -53,7 +53,7 @@ Picking among options: select, combobox, autocomplete, checkbox, radio, card and
 
 ## [Data display](data-display.md)
 
-Read-only presentation: avatar, badge, chip, stat and metric cards, card presets, list tile, timeline, code, markdown, terminal, API docs blocks, QR and barcode. 24 entries.
+Read-only presentation: avatar, badge, chip, stat and metric cards, card presets, list tile, timeline, code, markdown, terminal, API docs blocks, QR and barcode, two-step verification (enrolment secret, recovery codes). 26 entries.
 
 [<img src="../previews/data-display-avatar.webp" height="72" alt="Avatar">](data-display.md#avatar)
 [<img src="../previews/data-display-statcard.webp" height="72" alt="StatCard">](data-display.md#statcard)
@@ -71,7 +71,7 @@ Collections you query: data table, filter, pagination, tree, drag and drop. 6 en
 
 ## [Navigation & layout](navigation-and-layout.md)
 
-Where a page sits and how you move: app shell, sidebar, app bars, breadcrumb, page layouts, grid, resizable, skip link, pager, TOC, steppers, hero, doc site shell. 17 entries.
+Where a page sits and how you move: app shell, sidebar, app bars, breadcrumb, page layouts, grid, resizable, skip link, pager, TOC, steppers, hero, doc site shell, signed-out page frame. 18 entries.
 
 [<img src="../previews/navigation-layout-appshell.webp" height="72" alt="ActivityLayout">](navigation-and-layout.md#activitylayout)
 [<img src="../previews/navigation-layout-sidebar.webp" height="72" alt="Sidebar">](navigation-and-layout.md#sidebar)

package/docs/components/data-display.md

@@ -30,6 +30,8 @@ from `@nxgt/material-vue/components`.
 | <img src="../previews/data-display-paramtable.webp" width="96" alt=""> | [ParamTable](#paramtable) | Name / type / default / description table |
 | <img src="../previews/data-display-qrcode.webp" width="96" alt=""> | [QRCode](#qrcode) | QR code on a padded tile |
 | <img src="../previews/data-display-barecode.webp" width="96" alt=""> | [Barecode](#barecode) | 1D barcode |
+| <img src="../previews/data-display-enrolmentsecret.webp" width="96" alt=""> | [EnrolmentSecret](#enrolmentsecret) | A TOTP enrolment: QR code, app link, the key grouped by four |
+| <img src="../previews/data-display-recoverycodes.webp" width="96" alt=""> | [RecoveryCodes](#recoverycodes) | One-time recovery codes: copy, download, print, confirm |
 
 ## Avatar
 
@@ -935,3 +937,113 @@ The other props (`lineColor`, `background`, `margin`, `fontSize`, …) are
 JsBarcode's options.
 
 **Storybook:** `Data display/Barecode` · **React:** `Barecode`
+
+---
+
+## EnrolmentSecret
+
+![EnrolmentSecret](../previews/data-display-enrolmentsecret.webp)
+
+A TOTP enrolment (two-step verification): the QR code of the `otpauth://` URI, the URI as a link — a phone cannot scan its own screen, and an authenticator app on it opens the link — and the secret in groups of four, to type or copy.
+
+```vue
+<script setup lang="ts">
+import { EnrolmentSecret } from '@nxgt/material-vue/components';
+</script>
+
+<template>
+  <EnrolmentSecret
+    uri="otpauth://totp/Acme:ada%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=Acme"
+    secret="JBSWY3DPEHPK3PXP"
+  />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `uri` | `string` | — | the QR code's content and the link's `href`; the link renders only when it starts with `otpauth:` |
+| `secret` | `string` | — | shown as `JBSW Y3DP EHPK 3PXP`; the copy button copies it without spaces |
+| `showQrCode` | `boolean` | `true` | `false`: the link and the key alone |
+| `qrSize` | `number` | `192` | the QR code's size in pixels (it shrinks to fit a narrower box) |
+| `qrLabel`, `openAppLabel`, `manualLabel`, `secretLabel`, `copyLabel`, `copiedLabel` | `string` | translated | the QR code's name, the link, the line before the key, the key's group name, the copy button's name, what it announces |
+
+The QR code sits beside the rest once the component is 28rem wide (a
+container query), above it on a phone. The key is a `<code>` in a
+`fieldset` named "Setup key" (a group may be named, a `code` element may
+not) beside a `CopyButton`, which announces "Key copied" in a polite status
+region; it wraps at the group boundaries, never past the card's edge.
+`groupSecret(secret, size?)` (from `@nxgt/material-core/two-factor`) is
+re-exported for a layout of your own.
+
+**Storybook:** `Data display/EnrolmentSecret` · **React:** `EnrolmentSecret`
+
+---
+
+## RecoveryCodes
+
+![RecoveryCodes](../previews/data-display-recoverycodes.webp)
+
+One-time recovery codes, shown once: read as a list, copied, downloaded as a text file, printed (the card alone), and an "I have saved these codes" confirmation before "Done".
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useRouter } from 'vue-router';
+import { RecoveryCodes } from '@nxgt/material-vue/components';
+
+const props = defineProps<{ codes: string[]; email: string }>();
+const router = useRouter();
+const saved = ref(false);
+</script>
+
+<template>
+  <RecoveryCodes
+    v-model:saved="saved"
+    :codes="props.codes"
+    description="Use one of them to sign in if you lose your phone."
+    :file-heading="`Recovery codes for ${props.email}`"
+    @done="router.push('/settings/security')"
+  />
+</template>
+```
+
+| Prop / slot | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `codes` | `readonly string[]` | — | an ordered list named "Recovery codes" |
+| `title` / `#title`, `titleAs` | `string`, `'h2' \| 'h3' \| 'h4'` | "Recovery codes", `'h2'` | the card's heading |
+| `description` / `#description` | `string` / slot | — | a line under it |
+| `warning` / `#warning` | `string \| false` / slot | "Each code works once…" | an `Alert` above the codes, not printed; `false` hides it |
+| `focusTitle` | `boolean` | `true` | the heading takes the focus once shown: the codes replaced what the user acted on |
+| `fileName`, `fileHeading`, `fileNote` | `string` | `"recovery-codes.txt"`, the title, the warning | the downloaded file and its first two lines |
+| `onDone` (`@done`) | `() => void` | — | shows "Done", which calls it once the confirmation is ticked |
+| `v-model:saved` | `boolean` | uncontrolled | the confirmation |
+| `labels` | `Partial<RecoveryCodesLabels>` | translated | `list`, `copy`, `copied`, `copyFailed`, `download`, `print`, `saved`, `savedRequired`, `done` |
+
+- **Copy** puts the codes on the clipboard one per line; "Codes copied" (or
+  "Copy failed") is announced by the component's own polite status region,
+  so it needs no `Toaster`.
+- **Download** saves `recoveryCodesText(codes, { heading, note })` with
+  `downloadText` (both re-exported from `@nxgt/material-core/two-factor`).
+- **Print** prints the card and nothing else, with no inline style and no new
+  window: `printOnly` (`@nxgt/material-vue/lib`) marks `<html data-nxgt-print>` and the card
+  while the dialog is open, and the rules in `styles.css` hide the rest of the page in
+  print. The buttons, the confirmation and the warning are not printed.
+- **Done** before the box is ticked moves the focus to the box, marks it
+  `aria-invalid` and says "Tick the box once your codes are safe" under it.
+  "Done" is shown only when `@done` (the `onDone` prop) is bound.
+
+Leaving the page before the codes are saved is the app's to guard, with its
+router: refuse the navigation while `saved` is false, and ask the browser
+too:
+
+```ts
+import { onBeforeRouteLeave } from 'vue-router';
+import { useEventListener } from '@vueuse/core';
+
+onBeforeRouteLeave(() => saved.value || window.confirm('Leave without saving your codes?'));
+useEventListener(window, 'beforeunload', (event) => {
+  if (!saved.value) event.preventDefault();
+});
+```
+
+**Storybook:** `Data display/RecoveryCodes` · **React:** `RecoveryCodes` (`saved` / `onSavedChange`, `onDone`; props for the slots)

package/docs/components/feedback-and-status.md

@@ -173,6 +173,8 @@ keeps focus off the Cancel, on the content: the page behind an alert dialog is
 task: focus it from a `setTimeout`, not in the handler.
 
 **Emits:** `update:open` on `AlertDialog` — `boolean`.
+`AlertDialogContent` is capped to the viewport height and scrolls inside itself, like `DialogContent` ([Dialog](overlays-and-menus.md#dialog)).
+
 **Storybook:** `Feedback & status/AlertDialog` · **React:** `AlertDialog` (same parts)
 
 ---

package/docs/components/form-fields.md

@@ -11,6 +11,7 @@ value type each one writes. Everything is imported from
 | | Component | What it does |
 | --- | --- | --- |
 | <img src="../previews/form-fields-field.webp" width="96" alt=""> | [Field](#field) | Renders the field matching a config `type` |
+| <img src="../previews/form-fields-formsection.webp" width="96" alt=""> | [FormSection](#formsection) | Titled section of a form, one column on a phone |
 | <img src="../previews/form-fields-textfield.webp" width="96" alt=""> | [TextField](#textfield) | Labelled input with adornments and helper text |
 | <img src="../previews/form-fields-textareafield.webp" width="96" alt=""> | [TextareaField](#textareafield) | Labelled textarea with row sizing and a counter |
 | <img src="../previews/form-fields-emailfield.webp" width="96" alt=""> | [EmailField](#emailfield) | Validates on blur, `mailto:` button |
@@ -90,6 +91,86 @@ with `useField` as above (the error message is then yours to pass as
 
 ---
 
+## FormSection
+
+![FormSection](../previews/form-fields-formsection.webp)
+
+A titled section of a form: a heading (an `h2` by default), an optional
+description and actions, then its fields in the form grid's columns; one
+column on a phone.
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import {
+  Button,
+  EmailFormField,
+  FormSection,
+  SwitchFormField,
+  TextFormField,
+} from '@nxgt/material-vue/components';
+
+const { handleSubmit } = useForm({
+  initialValues: { firstName: '', email: '', contact: '', digest: false },
+});
+const onSubmit = handleSubmit((values) => console.log(values));
+</script>
+
+<template>
+  <form class="form-grid-layout" @submit="onSubmit">
+    <div data-slot="form-fields">
+      <FormSection title="Profile">
+        <TextFormField name="firstName" label="First name" />
+        <EmailFormField name="email" label="Email" />
+      </FormSection>
+      <FormSection
+        title="Emergency contact"
+        description="Who we call when you cannot be reached."
+      >
+        <template #actions>
+          <Button variant="outlined" size="sm">Add another</Button>
+        </template>
+        <TextFormField name="contact" label="Name" />
+      </FormSection>
+      <FormSection title="Notifications">
+        <SwitchFormField name="digest" label="Digest" placeholder="Email me a weekly digest" />
+      </FormSection>
+    </div>
+    <div data-slot="form-actions">
+      <Button type="submit">Save</Button>
+    </div>
+  </form>
+</template>
+```
+
+| Prop / slot | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `title` / `#title` | `string` / slot | — | the section's heading, which names the group; the slot wins over the prop |
+| `title-as` | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'h2'` | the heading level: `'h3'` when the form already sits under an `h2` |
+| `description` / `#description` | `string` / slot | — | a muted line under the title; the group's accessible description |
+| `#actions` | slot | — | controls beside the title, wrapping under it on a phone |
+| `separated` | `boolean` | `true` | a rule above the section when it follows another `FormSection` |
+| default slot | slot | — | the section's fields |
+
+The section is a `role="group"` named by its heading (`aria-labelledby`) and
+described by its description (`aria-describedby`), so a screen reader
+announces "Profile, group" on entering it, and a test finds it with
+`getByRole('group', { name: 'Profile' })`. It is not a `<fieldset>`: a
+fieldset would be one cell of the form's grid, and its fields would not take
+the grid's columns. Inside `.form-grid-layout`'s `[data-slot="form-fields"]`
+it spans the whole row and lays its fields out in the same columns the form
+grid uses, by the section's own width (it is a container query container, so
+it works outside a form grid too). The form grid's wide-field rules still
+apply inside it: a switch, a textarea, chips, files and the rich text editor
+take a row of their own. The rule between sections is a top border drawn on
+each section that follows another; the first has none. The heading is small,
+semibold, uppercase and muted, set apart from the fields' labels, and reads
+4.5:1 in both themes.
+
+**Storybook:** `Form fields/FormSection` · **React:** `FormSection`
+
+---
+
 ## TextField
 
 ![TextField](../previews/form-fields-textfield.webp)

package/docs/components/navigation-and-layout.md

@@ -8,6 +8,7 @@ documentation-site shell. Everything is imported from
 | | Component | What it does |
 | --- | --- | --- |
 | <img src="../previews/navigation-layout-appshell.webp" width="96" alt=""> | [ActivityLayout](#activitylayout) | App shell: sidebar, header, breadcrumbs, titled page |
+| <img src="../previews/navigation-layout-authcard.webp" width="96" alt=""> | [AuthCard](#authcard) | Signed-out page frame: one `main`, a centred card, its title the `h1` |
 | <img src="../previews/navigation-layout-sidebar.webp" width="96" alt=""> | [Sidebar](#sidebar) | Collapsible navigation sidebar |
 | <img src="../previews/navigation-layout-topappbar.webp" width="96" alt=""> | [TopAppBar, BottomAppBar](#topappbar) | Top and bottom bars |
 | <img src="../previews/navigation-layout-breadcrumb.webp" width="96" alt=""> | [Breadcrumb](#breadcrumb) | Breadcrumb primitives |
@@ -98,6 +99,69 @@ pass, collapsed or expanded.
 
 ---
 
+## AuthCard
+
+![AuthCard](../previews/navigation-layout-authcard.webp)
+
+The frame of a signed-out page (sign in, sign up, a reset link): one `main`, a centred card whose title is the page's `h1`, a row above it for the brand and a toolbar, padded clear of a phone's notch and home bar.
+
+```vue
+<script setup lang="ts">
+import {
+  AuthCard,
+  Button,
+  EmailField,
+  LanguageSwitcher,
+  PasswordField,
+} from '@nxgt/material-vue/components';
+
+defineProps<{ expired?: boolean }>();
+const signIn = () => {};
+</script>
+
+<template>
+  <AuthCard
+    title="Sign in"
+    description="Welcome back."
+    :notice="expired ? 'This link has expired.' : undefined"
+    notice-tone="error"
+  >
+    <template #brand><img src="/logo.svg" alt="Acme" height="24" /></template>
+    <template #toolbar><LanguageSwitcher /></template>
+    <template #footer><a href="/terms">Terms</a></template>
+    <form class="flex flex-col gap-4" @submit.prevent="signIn">
+      <EmailField label="Email" name="email" autocomplete="email" />
+      <PasswordField label="Password" name="password" autocomplete="current-password" />
+      <Button type="submit">Sign in</Button>
+    </form>
+  </AuthCard>
+</template>
+```
+
+| Prop / slot | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `title` / `#title` | `string` / slot | — | the page's `h1`, in the card's title |
+| `description` / `#description` | `string` / slot | — | a line under the title |
+| `notice` / `#notice` | `string` / slot | — | an `Alert` above the form: an expired link, a signed-out message |
+| `noticeTone` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | its colour; `'error'` is `role="alert"`, the others `role="status"` |
+| `focusTitle` | `boolean` | `false` | the `h1` takes the focus once shown (`useFocusOnMount`): for an end state that replaced the form ("Check your inbox") |
+| `#brand`, `#toolbar` | slots | — | the row above the card, left and right; it renders only when one is given |
+| `#banner` | slot | — | above that row (an update notice) |
+| `#footer` | slot | — | under the card |
+
+A non-error notice goes into a `role="status"` region that is always
+rendered (zero height while empty), so a screen reader announces a notice
+that appears later; an error is a `role="alert"` inserted when it shows.
+
+The `main` has `tabindex="-1"`: never reached by Tab, but what replaced a
+control the user acted on (a dismissed banner) can hand it the focus. Its
+padding is `max(1rem, env(safe-area-inset-*))` on each side, as classes: no
+inline style. Other attributes reach the `main`.
+
+**Storybook:** `Navigation & layout/AuthCard` · **React:** `AuthCard` (props `brand`, `toolbar`, `banner`, `footer` for the slots)
+
+---
+
 ## Sidebar
 
 ![Sidebar](../previews/navigation-layout-sidebar.webp)

package/docs/components/overlays-and-menus.md

@@ -96,6 +96,21 @@ overlay, for a dialog taller than the screen).
 Unlike React, `DialogContent` renders the X by itself (turn it off with
 `:show-close-button="false"`), and `DialogTrigger` is not `as-child` by default.
 
+`DialogContent` and `AlertDialogContent` are capped at `100dvh - 2rem` (`100vh`
+where `dvh` is unsupported) and scroll inside themselves, so a long body never
+pushes the title off-screen on a phone. The built-in X scrolls with the content. On
+browsers with `dvh` support, your own `max-h-*` through `class` wins over the
+cap. To remove the cap and the scroll, pass `class="max-h-none overflow-visible"`:
+
+```vue
+<DialogContent class="max-h-none overflow-visible">
+```
+
+Content wider than the dialog now scrolls horizontally or is clipped
+(`overflow-visible` restores the old behaviour). `DialogScrollContent` is for a
+dialog that should grow taller than the screen and scroll inside the overlay
+instead of capping; it does not pin the header or footer.
+
 On open, `DialogContent` moves focus into the dialog: to its first control
 (the built-in X when there is nothing before it), or to the content itself
 when it has none. An `@open-auto-focus` that calls `event.preventDefault()`
@@ -165,6 +180,9 @@ Parts: `Sheet`, `SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetTitle`,
 | `side` (`SheetContent`) | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | the edge it slides from; left / right are ¾ wide, capped at 384 px |
 | `default-open` / `v-model:open`, `modal` (`Sheet`) | as `Dialog` | — | a sheet is a Reka dialog |
 
+`SheetContent` scrolls inside itself, and a top or bottom sheet is capped at
+`100dvh`. Override the cap with `max-h-*` through `class`.
+
 `SheetContent` always renders a top-right X, named "Close"
 (`material.buttons.close`, translated); there is no `withCloseButton` prop in
 Vue.

package/docs/components/selection-and-choice.md

@@ -263,19 +263,19 @@ const picked = ref<string[]>(['nuxt']);
 | --- | --- | --- | --- |
 | `mode` | `'single' \| 'multiple'` | `'single'` | decides the `v-model` type |
 | `v-model` | `string \| string[] \| null` | `null` | per `mode` |
-| `options` | `T[]`, `T extends { value: string; label: string }` | `[]` | the items, typed by your own option type; with `on-search`, the list before a search and the selected options' labels |
+| `options` | `T[]`, `T extends { value: string; label: string; disabled?: boolean }` | `[]` | the items (`disabled` on one: listed, announced as disabled, never picked), typed by your own option type; with `on-search`, the list before a search and the selected options' labels |
 | `get-option-value` | `(option: T) => string` | `option.value` | the value an option stands for |
 | `get-option-label` | `(option: T) => string` | `option.label` | the text it shows and is searched by |
 | `filter` | `'accent-insensitive' \| 'none' \| (option: T, query: string) => boolean` | `'accent-insensitive'`, `'none'` with `on-search` | how the list is filtered as the user types: label or value, ignoring case and accents (`e` finds "École") in the provider's language; `'none'` shows `options` as given; a function gets the trimmed query, never an empty one |
 | `free-solo` | `boolean` | `false` | accept a typed value that is not an option ("Add …") |
 | `free-solo-label` | `(query: string) => string` | `Add "{query}"`, translated | the free-solo button's text |
 | `@search` (prop `on-search`) | `(query: string, { signal }: { signal: AbortSignal }) => Promise<T[]>` | — | server search: called once typing pauses; its results become the list. Each search aborts the previous one, and a response that lands after a newer one is dropped |
-| `@search-error` | `(error: unknown) => void` | — | `on-search` rejected (an abort is not a rejection) |
+| `@search-error` | `(error: unknown) => void` | — | `on-search` rejected (an abort is not a rejection); pass the reason back as `search-error` |
 | `min-query-length` | `number` | `1` | `on-search` waits for this many characters; below it the list says "Type at least N characters to search." |
 | `debounce-ms` | `number` | `250` | the pause before `on-search` and `@query-change` run |
 | `@query-change` | `(query: string) => void` | — | the typed text once typing pauses — fetch `options` yourself here |
 | `loading` | `boolean` | — | with `@query-change`: "Loading…" in the list, `aria-busy` on it, announced |
-| `search-error` | `string` | — | with `@query-change`: shown and announced in place of the options |
+| `search-error` | `string` | — | shown and announced in place of the options; with `on-search` it replaces the generic "The search failed. Try again." |
 | `empty` | `string` | "No option found." | text when nothing matches |
 | `required` | `boolean` | — | the asterisk, and `aria-required` on the input, which the label names |
 | `error` | `boolean` | — | red border on the box, error helper text, `aria-invalid` on the input |
@@ -321,7 +321,10 @@ const person = ref<string | null>(null);
 With `on-search`, `min-query-length` defaults to 1, `debounce-ms` to 250 and `filter` to `'none'`
 (the server filters). A rejected search shows and announces "The search
 failed. Try again." by itself and hands the error to `@search-error`; an abort is
-never an error. Type your search with `AutocompleteSearch<T>` (its second
+never an error. To say why instead (the API's own refusal, "the service is
+unreachable"), keep the reason in your state from `@search-error` and pass it as
+`search-error`: it takes precedence over the generic text, in the list and in the
+live region. Type your search with `AutocompleteSearch<T>` (its second
 argument is `AutocompleteSearchContext`, `{ signal }`); `AutocompleteFilter<T>`
 and `AutocompleteSearchProps<T>` are exported from `@nxgt/material-vue/components` too.
 `filterAutocompleteOptions(options, query, locale?)`, exported beside the
@@ -332,6 +335,11 @@ To fetch it yourself instead, keep `options` and `loading` in your state,
 update them on `@query-change`, and pass `filter="none"` when the server
 already filtered.
 
+A disabled option (`disabled: true` on it, in `options` or in what `on-search`
+returns) is greyed out, carries `aria-disabled` and a native `disabled`, so Tab
+skips it, and is never picked, by click or by Enter (which picks the first
+enabled option), in `single` and `multiple` mode.
+
 **Accessibility.** A polite live region (`role="status"`) says "Loading…",
 then "3 results" or "No results" (or the failure) once the search answers or
 typing pauses — never on every keystroke. The list is `aria-busy` while

package/docs/guides/forms.md

@@ -259,6 +259,40 @@ 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.
 
+## A long form in sections
+
+A long form reads better in titled sections. Lay it out in the form grid
+(`.form-grid-layout`, its fields in `[data-slot="form-fields"]`, its buttons
+in `[data-slot="form-actions"]`) and put each group of fields in a
+[`FormSection`](../components/form-fields.md#formsection):
+
+```vue
+<template>
+  <form class="form-grid-layout" @submit="onSubmit">
+    <div data-slot="form-fields">
+      <FormSection title="Profile">
+        <TextFormField name="firstName" label="First name" />
+        <TextFormField name="lastName" label="Last name" />
+      </FormSection>
+      <FormSection title="Notifications" description="You can change these at any time.">
+        <SwitchFormField name="digest" label="Digest" placeholder="Email me a weekly digest" />
+      </FormSection>
+    </div>
+    <div data-slot="form-actions">
+      <Button type="submit" :loading="isSubmitting">Save</Button>
+    </div>
+  </form>
+</template>
+```
+
+- Each section's title is an `h2` (pass `title-as="h3"` when the form sits
+  under an `h2` of your own), so a screen reader moves from section to
+  section, and each section is a group named by its title.
+- The sections take a whole row of the grid and lay their fields out in the
+  grid's columns, one column on a phone; switches, textareas, chips and file
+  fields still take a row of their own. A rule separates each section from the
+  one before it (`:separated="false"` drops it).
+
 ## Validation messages
 
 `zodLocaleError()` from `@nxgt/material-vue/lib` is a Zod v4 error map that
@@ -337,6 +371,92 @@ How it picks the language, and what that implies:
   with no string of its own (a map, a set) gets
   `This value has the wrong type.`
 
+### Wording errors by code
+
+`zodLocaleError` words zod's own issues; a rule of your own — a name already
+taken, a code the API sends back — has words only your app knows.
+`useCodeResolver(schema, options?)` (`@nxgt/material-vue/components`)
+returns a vee-validate typed schema that words both in the page's language:
+a refinement carrying a code in `params.code` reads as your translator's
+words for that code, every other issue as `zodLocaleError`'s. The language
+is `I18nProvider`'s (or the `language` option: a value, ref or getter).
+
+It is a `ComputedRef<TypedSchema>`: pass it as it is to
+`useForm({ validationSchema })`, which accepts a ref and, when it changes,
+re-validates the fields already validated — so a language switch re-words
+the errors on screen.
+
+```ts
+// i18n.ts — the app's translator, over the package's bundle
+import { createTranslator, mergeResources, resources } from '@nxgt/material-vue/i18n';
+
+export const appResources = mergeResources(resources, {
+  en: { errors: { taken: 'This name is already taken.', tooShort: 'At least {min} characters.' } },
+  fr: { errors: { taken: 'Ce nom est déjà pris.', tooShort: 'Au moins {min} caractères.' } },
+});
+export const translate = createTranslator<string>(appResources);
+```
+
+```vue
+<!-- sign-up-form.vue -->
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { z } from 'zod';
+import { Button, TextFormField, useCodeResolver } from '@nxgt/material-vue/components';
+import { translate } from './i18n';
+
+const props = defineProps<{ save: (values: z.output<typeof schema>) => Promise<void> }>();
+
+const TAKEN = ['admin', 'root'];
+
+const schema = z.object({
+  // Worded by material's zod messages: "Invalid email address."
+  email: z.email(),
+  username: z
+    .string()
+    .refine((name) => name.length >= 3, { params: { code: 'errors.tooShort', min: 3 } })
+    .refine((name) => !TAKEN.includes(name), { params: { code: 'errors.taken' } }),
+});
+
+const validationSchema = useCodeResolver(schema, { translate });
+const { handleSubmit } = useForm({
+  validationSchema,
+  initialValues: { email: '', username: '' },
+});
+const onSubmit = handleSubmit((values) => props.save(values));
+</script>
+
+<template>
+  <form novalidate @submit="onSubmit">
+    <TextFormField name="email" label="Email" />
+    <TextFormField name="username" label="Username" />
+    <Button type="submit">Sign up</Button>
+  </form>
+</template>
+```
+
+- **The codes.** `translate(code, params, language)`: `params` is the
+  refinement's whole `params`, so `{ code, min: 3 }` fills `{min}`. A key
+  your translator returns verbatim (what `createTranslator` does with a key
+  it lacks) has no words: the issue falls back to `zodLocaleError`.
+- **The rest.** The same `translate` is handed to `zodLocaleError`, so your
+  `material.zod.*` overrides apply. Without `translate`, every issue is
+  worded by the package's own messages.
+- **Another code.** `codeOf` picks the code an issue carries. Its default is
+  `defaultCodeOf` (a custom issue's `params.code`); to word every empty
+  required field by one code of yours, use `isEmptyRequired` (both, and
+  the type `CodeIssue`, are exported beside `useCodeResolver` from
+  `@nxgt/material-vue/components`, and from `@nxgt/material-core/code-errors`):
+  `codeOf: (issue) => (isEmptyRequired(issue) ? 'errors.required' : defaultCodeOf(issue))`.
+- Issues map to vee-validate's errors by field path as `FormScope` maps a
+  Standard Schema's (`contacts[0].value`).
+- Outside a composable, `createCodeErrorMap({ translate, codeOf?, fallback })`
+  (also exported beside `useCodeResolver`) is the error map itself, for
+  `schema.safeParse(values, { error })`.
+
+Storybook: `Guides/Forms/useCodeResolver`. React: the same name in
+`@nxgt/material/components`, returning a react-hook-form resolver.
+
 ## What each field emits
 
 The value a wrapper writes into the form, read from each field's

package/docs/guides/helpers.md

@@ -18,6 +18,7 @@ differences are listed under each table. React's `/hooks` is
 | --- | --- |
 | `cn(...classes)` | `clsx` + `tailwind-merge`: joins conditional classes, last Tailwind utility wins. |
 | `getCspNonce(doc?)`, `setCspNonce(nonce)` | The page's Content Security Policy nonce, from `@nxgt/material-core/csp-nonce`: `getCspNonce` reads what `setCspNonce` kept, else the `csp-nonce` meta tag, a `<script nonce>` or `<style nonce>`, else `__webpack_nonce__`; `undefined` on a server, where `setCspNonce` does nothing. See [CSP](csp.md#nonceprovider). |
+| `printOnly(element, name?)`, `PRINT_ATTRIBUTE`, `PRINT_TARGET_ATTRIBUTE` | Opens the print dialog for one element of the page instead of the whole page (the marks are removed once printing is over), from `@nxgt/material-core/print-only`; the `@media print` rules are in the package's `styles.css`. See [printing](printing.md#printing-one-element-of-the-page). |
 | `clientOnly(component)` | Wraps a component so it renders nothing on the server and on the first client render, and mounts only after `onMounted`. Pair it with `defineAsyncComponent(() => import(…))`. See [SSR](ssr.md). |
 | `renderSlot(slot, context)`, `ContentSlot<T>` | Resolves a `ContentSlot`: a `VNode`, a string or number, or a `(context) => VNode \| string \| number`. |
 | `formatAmount(value, currency?, { locale?, fractionDigits? })`, `formatDate(value, { locale?, timeZone?, dateStyle?, timeStyle? })` | An amount in its currency's own decimals (two without a currency) and a medium date, in the runtime's locale unless you pass one; a date-only `YYYY-MM-DD` keeps its day in every time zone; `'—'` when empty. Also on `/components`. See [printing](printing.md#formatamount-and-formatdate). |
@@ -207,6 +208,9 @@ they are auto-imported.
 | `useSearchParam(name)` | `ComputedRef<string \| null>` of one query parameter (`vue-router`; the first one when repeated). |
 | `useNavigationHandler(to, { replace? })`, `useNavigationHandlers(routes)` | Click handlers that push or replace a route (`vue-router`). |
 | `useAllowedTransitions(status, transitions, configs)` | Status-machine actions (icon, colour, label, dialog copy) allowed from the current status. Plain array, computed once per call. |
+| `useFocusOnMount<T>(focus?)` | A `ShallowRef` to bind with `ref="…"`: its element takes focus once mounted, and again whenever `focus` (a value, ref or getter; `true` by default) turns true. Nothing runs on a server. See [below](#usefocusonmount). |
+| `useSubmitOnce(busy?)` | One submit in flight: wraps a submit handler so a double click or a second Enter is dropped until the request ends (the handler's promise, or `busy` — a ref or getter — back to false). See [below](#usesubmitonce). |
+| `createSubmitGuard()`, `busySettler(guard)` | The framework-free guard behind `useSubmitOnce` (`@nxgt/material-core/submit-guard`): `{ once(run, { settleSync? }), settle(run?), pendingRun() }`, and the function that settles it from a busy flag. |
 
 ```vue
 <script setup lang="ts">
@@ -246,6 +250,87 @@ it follows changes **inside** the array you passed, not a new array. When the
 list is a prop the parent replaces, write the `computed` over `props.x`
 yourself, as above.
 
+### `useFocusOnMount`
+
+When what the user acted on is replaced — a wizard's next step, an end state
+such as "Message sent" — the button that had focus is gone, and focus falls
+back to the top of the page. Bind the ref to the new content's heading: it
+takes focus once mounted, a screen reader reads it, and Tab goes on from
+there. A heading is not focusable by itself: give it `tabindex="-1"` (a
+button, a link or a field needs nothing).
+
+```vue
+<script setup lang="ts">
+import { useFocusOnMount } from '@nxgt/material-vue/composables';
+
+defineProps<{ email: string }>();
+const title = useFocusOnMount<HTMLHeadingElement>();
+</script>
+
+<template>
+  <section aria-labelledby="sent-title">
+    <h2 id="sent-title" ref="title" tabindex="-1">Message sent</h2>
+    <p>We replied to {{ email }}.</p>
+  </section>
+</template>
+```
+
+`useFocusOnMount(() => open.value)` focuses again whenever `open` turns true
+(after the DOM update), for content that stays mounted and is only shown.
+Storybook: `Guides/Hooks/useFocusOnMount`.
+
+### `useSubmitOnce`
+
+A disabled or `loading` button only stops clicks once it has rendered, and
+never stops Enter in a field: a fast double click, or Enter twice, posts the
+form twice — and a second request can abort the first mid-call. The
+composable returns a wrapper that lets one call through until the request
+ends; a dropped call's event has its default prevented, so it never falls
+back to the browser's own submission.
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { Button, TextFormField } from '@nxgt/material-vue/components';
+import { useSubmitOnce } from '@nxgt/material-vue/composables';
+
+type Values = { email: string };
+const props = defineProps<{ save: (values: Values) => Promise<void> }>();
+
+const { handleSubmit, isSubmitting } = useForm<Values>({ initialValues: { email: '' } });
+const submitOnce = useSubmitOnce();
+// handleSubmit(fn) returns a function whose call returns a promise: the
+// guard opens again when `save` ends.
+const onSubmit = submitOnce(handleSubmit((values) => props.save(values)));
+</script>
+
+<template>
+  <form @submit="onSubmit">
+    <TextFormField name="email" label="Email" />
+    <Button type="submit" :loading="isSubmitting">Subscribe</Button>
+  </form>
+</template>
+```
+
+**Return the request's promise, or pass `busy`.** The guard opens again:
+
+- when the handler's promise ends, fulfilled or rejected (a rejection still
+  reaches the caller);
+- with `busy` passed (a ref or a getter: `useSubmitOnce(() => pending.value)`),
+  once it was true and is false again. It settles the submit that was on its
+  way when `busy` rose, never a newer one, and a handler that returns no
+  promise waits for it;
+- without `busy`, as soon as a handler returns something that is not a
+  promise: one that returned early (`if (!valid) return;`) or did its work
+  synchronously does not lock the form.
+
+Outside a component, `createSubmitGuard()` from
+`@nxgt/material-core/submit-guard` (also re-exported here) is the same guard:
+`once(run)` wraps a handler, `settle()` opens it by hand, and
+`busySettler(guard)` returns the function to call with each value of a busy
+flag. Storybook:
+`Guides/Hooks/useSubmitOnce`.
+
 <a id="nxgtmateriali18n"></a>
 
 ## `@nxgt/material-vue/i18n`