@nxgt/material-vue 0.34.0 → 0.36.0

package/dist/{use-material-translation-CaHS6oZz.js → use-material-translation-DRB6oPdF.js}

@@ -1,6 +1,6 @@
-import "./stored-language-GDRdeYD8.js";
-import { a as e } from "./i18n-provider-CiVi05fs.js";
-import { i as t, r as n } from "./translator-BDFEmlcL.js";
+import "./stored-language-dtksFoGO.js";
+import { a as e } from "./i18n-provider-B2q6vp6H.js";
+import { i as t, r as n } from "./translator-DqiGrSH_.js";
 //#region lib/i18n/translate-material.ts
 function r(e, r, i, a) {
 	if (e) for (let t of /* @__PURE__ */ new Set([e, e.split("-")[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
 
@@ -171,8 +173,12 @@ Pill with leading, avatar and trailing slots, an active state and a dismiss butt
 
 ```vue
 <script setup lang="ts">
+import { ref } from 'vue';
 import { Avatar, AvatarFallback, Chip } from '@nxgt/material-vue/components';
 
+const chip = ref<InstanceType<typeof Chip>>();
+// chip.value?.focus()
+
 function remove(id: string) {
   console.log('remove', id);
 }
@@ -185,6 +191,9 @@ function remove(id: string) {
     </template>
   </Chip>
   <Chip label="Shipped" color="success" active />
+  <Chip label="Frontend" :dismiss-label="(label) => `Clear ${label} filter`" @dismiss="remove('fe')" />
+  <Chip label="+ Field" variant="dashed" :active="added" @click="add" />
+  <Chip ref="chip" label="Compact" size="sm" />
 </template>
 ```
 
@@ -192,12 +201,17 @@ function remove(id: string) {
 | --- | --- | --- | --- |
 | `label` | `string` | — | the text; the default slot replaces it |
 | `active` | `boolean` | — | filled appearance |
-| `variant` | Button `variant` | `'outlined'` | appearance when not active |
+| `variant` | Button `variant`, or `'dashed'` | `'outlined'` | appearance when not active; `dashed` is a muted dashed pill (a "+ Field" pill) that turns solid and normal once `active` |
+| `size` | `'default' \| 'sm'` | `'default'` | `sm` is a compact chip; the ✕ and every target stay at least 24px |
 | `color` | Button `color` | — | tone |
 | `disabled` | `boolean` | — | disables the chip and its ✕ |
-| `@dismiss` | `() => void` | — | a listener adds the ✕ button, named "Remove {label}" (`material.chip.dismiss-label`), `{label}` being the text the chip shows: the default slot's when given, else `label`; "Remove" when it shows none |
+| `@dismiss` | `() => void` | — | a listener adds the ✕ button, named "Remove {label}" (`material.chip.dismiss-label`), `{label}` being the text the chip shows: the default slot's when given, else `label`; "Remove" when it shows none; the ✕ is a 24px target |
+| `dismissLabel` | `string \| ((label: string) => string)` | — | names the ✕ instead of "Remove {label}": a string as is, or a function of the text the chip shows |
 | `@click` | `(event: MouseEvent) => void` | — | a listener makes the chip (or its body, when dismissible) a button |
 | `#leading`, `#avatar`, `#trailing` | slots | — | `#avatar` is shrunk to fit and replaces `#leading` |
+| exposed `el`, `focus(options?)` | `HTMLElement \| null`, `(options?: FocusOptions) => void` | — | the chip's body (the Button, the inner button, or the label span with `tabindex="-1"`) and a method focusing it: `chip.value?.focus()` |
+
+The dashed look's muted text meets 4.5:1 on the `background` and `card` surfaces, but not on `accent`.
 
 **Storybook:** `Data display/Chip` · **React:** `Chip`
 
@@ -923,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/data-table-filter-and-lists.md

@@ -356,7 +356,8 @@ async function archive() {
   in the URL; `manual` turns client filtering off.
 - **Selection** is `v-model:row-selection`, keyed by `getRowId`, so it
   survives a page change: ids of other pages stay in it, and the footer
-  counts them all ("3 rows selected", `material.table.pagination.selected`).
+  counts them all ("3 rows selected of 128", `material.table.pagination.rows-selected`; "Page n of m"
+  is hidden when the table has no rows).
   `#actions="{ table }"` reads it too (`table.store.state.rowSelection`). To
   keep it across a reload, put it in the URL or `sessionStorage`. Unbound,
   both models are held inside, as before. Bind both halves (`v-model`, or

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/selection-and-choice.md

@@ -144,6 +144,7 @@ const framework = ref('nuxt');
 | `placeholder` | `string` | `label` | the trigger's text while nothing is selected |
 | `required` | `boolean` | — | an asterisk after the label, and the select's `required`; the trigger is named by the label |
 | `label`, `helper-text`, `error`, `disabled` | | — | the field's text and state |
+| `ariaLabelledby` (`aria-labelledby` in a template) | `string` | — | the id of an element that names the trigger when `label` is absent; `label` wins when both are given |
 
 `#option` renders each option's content in the list (React's
 `renderOption`); it receives `{ option, index, selected }`. The trigger shows
@@ -166,7 +167,7 @@ the picked option's text.
 **Accessibility:** the trigger is named by `label`, described by the help or
 error text (`aria-describedby`) and marked `aria-invalid` on error, so
 `getByRole('combobox', { name: 'Framework' })` finds it and
-`toHaveAccessibleDescription(…)` / `toBeInvalid()` match.
+`toHaveAccessibleDescription(…)` / `toBeInvalid()` match. Without a `label`, `aria-labelledby` (`ariaLabelledby` in the script; the id of another element) names the trigger; when both are given, `label` wins.
 **Emits:** `update:modelValue` with `string`.
 **Form wrapper:** `SelectFormField` — `name` inside a vee-validate form, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).

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`