@nxgt/material 2.16.0 → 2.18.0

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

@@ -287,7 +287,7 @@ Parts: `Autocomplete`, `AutocompleteChips` (the chips row it uses in
 | `mode` | `'single' \| 'multiple'` | — | required; decides the `value` type |
 | `value` | `string` / `string[]` | — | required, per `mode` |
 | `onValueChange` | `(value?: string \| null) => void` / `(value?: string[] \| null) => void` | — | per `mode` |
-| `options` | `T[]` (`{ value, label }` by default) | `[]` | the items; with `onSearch`, the list before a search and the selected options' labels |
+| `options` | `T[]` (`{ value, label, disabled? }` by default) | `[]` | the items (`disabled` on one: listed, announced as disabled, never picked); with `onSearch`, the list before a search and the selected options' labels |
 | `getOptionValue`, `getOptionLabel` | `(option: T) => string` | `.value`, `.label` | for other option shapes |
 | `filter` | `'accent-insensitive' \| 'none' \| (option: T, query: string) => boolean` | `'accent-insensitive'`, `'none'` with `onSearch` | 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 |
 | `freeSolo` | `boolean` | — | accept a typed value that is not an option |
@@ -297,7 +297,7 @@ Parts: `Autocomplete`, `AutocompleteChips` (the chips row it uses in
 | `debounceMs` | `number` | `250` | the pause before `onSearch` and `onQueryChange` run |
 | `onQueryChange` | `(query: string) => void` | — | the query once typing pauses — fetch `options` yourself here |
 | `loading` | `boolean` | — | with `onQueryChange`: "Loading…" in the list, `aria-busy` on the listbox, announced |
-| `searchError` | `ReactNode` | — | with `onQueryChange`: shown and announced in place of the options |
+| `searchError` | `ReactNode` | — | shown and announced in place of the options; with `onSearch` it replaces the generic "The search failed. Try again." |
 | `empty` | `ReactNode` | "No option found." | text when nothing matches |
 | `actions` | `ReactNode \| ((query: string) => ReactNode)` | — | buttons at the end of the list ("Create …") |
 | `required` | `boolean` | — | the asterisk, and `aria-required` on the `combobox` input, which the label names |
@@ -346,7 +346,10 @@ export function PersonField() {
 With `onSearch`, `minQueryLength` defaults to 1, `debounceMs` 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 `onSearchError`; 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 `onSearchError` and pass it as
+`searchError`: 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/components` too.
 
@@ -354,6 +357,11 @@ To fetch it yourself instead, keep `options` and `loading` in your state,
 update them from `onQueryChange`, and pass `filter="none"` when the server
 already filtered.
 
+A disabled option (`disabled: true` on it, in `options` or in what `onSearch`
+returns) is greyed out, carries `aria-disabled`, and is never picked, by click
+or by Enter, in `single` and `multiple` mode. As in the combobox pattern, the
+arrow keys still reach it so that it is announced; Enter on it does nothing.
+
 **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 listbox is `aria-busy` while

package/docs/guides/forms.md

@@ -238,6 +238,38 @@ export function SubscribeForm({
 - Default values must have the type the field emits. See
   [What each field emits](#what-each-field-emits).
 
+## 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):
+
+```tsx
+<form className="form-grid-layout" onSubmit={form.handleSubmit(onSave)}>
+  <div data-slot="form-fields">
+    <FormSection title="Profile">
+      <TextFormField control={form.control} name="firstName" label="First name" />
+      <TextFormField control={form.control} name="lastName" label="Last name" />
+    </FormSection>
+    <FormSection title="Notifications" description="You can change these at any time.">
+      <SwitchFormField control={form.control} name="digest" label="Digest" placeholder="Email me a weekly digest" />
+    </FormSection>
+  </div>
+  <div data-slot="form-actions">
+    <Button type="submit" loading={form.formState.isSubmitting}>Save</Button>
+  </div>
+</form>
+```
+
+- Each section's title is an `h2` (pass `titleAs="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/lib` is a Zod v4 error map that
@@ -302,6 +334,85 @@ How it picks the language, and what that implies:
   `This value must be a number.`); a type with no string of its own says
   `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/components`) is a
+react-hook-form resolver 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); the resolver is made once per
+schema and language.
+
+```tsx
+// i18n.ts — the app's translator, over the package's bundle
+import { createTranslator, mergeResources, resources } from '@nxgt/material/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);
+```
+
+```tsx
+// sign-up-form.tsx
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+import { Button, TextFormField, useCodeResolver } from '@nxgt/material/components';
+import { translate } from './i18n';
+
+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' } }),
+});
+
+export function SignUpForm({ save }: { save: (values: z.output<typeof schema>) => Promise<void> }) {
+  const resolver = useCodeResolver(schema, { translate });
+  const { control, handleSubmit } = useForm({ resolver, defaultValues: { email: '', username: '' } });
+  return (
+    <form noValidate onSubmit={handleSubmit(save)}>
+      <TextFormField control={control} name="email" label="Email" />
+      <TextFormField control={control} name="username" label="Username" />
+      <Button type="submit">Sign up</Button>
+    </form>
+  );
+}
+```
+
+- **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/components`, and from `@nxgt/material-core/code-errors`):
+  `codeOf: (issue) => (isEmptyRequired(issue) ? 'errors.required' : defaultCodeOf(issue))`.
+- **Stable options.** Pass `translate` and `codeOf` from module scope: a new
+  function each render makes a new resolver.
+- **After a language switch** an error already on screen keeps its words
+  until the field is validated again: call `trigger()` when the language
+  changes and the form was submitted (see
+  [troubleshooting](../troubleshooting.md#errors-keep-their-old-words-after-a-language-switch)).
+- Outside a hook, `createCodeErrorMap({ translate, codeOf?, fallback })` (also
+  exported beside `useCodeResolver`) is the error map itself, for
+  `schema.safeParse(values, { error })`.
+
+Storybook: `Guides/Forms/useCodeResolver`. Vue: the same name in
+`@nxgt/material-vue/components`, returning a `validationSchema` for vee-validate.
+
 ## What each field emits
 
 The value a wrapper writes into the form, read from each field's `onChange`

package/docs/guides/helpers.md

@@ -15,6 +15,7 @@ differences are listed under each table.
 | `cn(...classes)` | `clsx` + `tailwind-merge`: joins conditional classes, last Tailwind utility wins. |
 | `clientOnly(Component)` | Wraps a component so it renders nothing on the server and mounts only on the client. See [SSR](ssr.md). |
 | `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). |
 | `renderSlot(slot, context)` | Resolves a `ContentSlot`: a `ReactNode` or a `(context) => ReactNode`. |
 | `DATE_UTILS` | `format(iso, 'PP', locale?)` (`'-'` when empty), `parseFromTimestring('HH:mm')`, `parseFromISOString`, `formatDateRangeFilter`. |
 | `formatDateRangeFilter(range)` | Turns a day-picker range into `{ from, to }` ISO strings at start / end of day; `undefined` when empty. |
@@ -131,6 +132,9 @@ Vue: the Redux helpers are Pinia store factories: `defineLocalStore`
 | `useSearchParam(name)` | One query-string value from the router (`react-router`). |
 | `useNavigationHandler(to, options?)`, `useNavigationHandlers(routes)` | Stable click handlers that navigate (`react-router`). |
 | `useAllowedTransitions(status, transitions, configs)` | Status-machine actions (icon, colour, label, dialog copy) allowed from the current status. |
+| `useFocusOnMount<T>(focus = true)` | A ref whose element takes focus once mounted, and again whenever `focus` turns true: the heading of what replaced the content the user acted on. 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` 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. |
 
 ```tsx
 import { useState } from 'react';
@@ -168,6 +172,83 @@ the component, or with `useCallback`) when the list is long.
 
 Vue: `@nxgt/material-vue/composables`, same names.
 
+### `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. Put the ref on 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).
+
+```tsx
+import { useFocusOnMount } from '@nxgt/material/hooks';
+
+export function Sent({ email }: { email: string }) {
+  const title = useFocusOnMount<HTMLHeadingElement>();
+  return (
+    <section aria-labelledby="sent-title">
+      <h2 id="sent-title" ref={title} tabIndex={-1}>
+        Message sent
+      </h2>
+      <p>We replied to {email}.</p>
+    </section>
+  );
+}
+```
+
+`useFocusOnMount(open)` focuses again whenever `open` turns true, 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 hook
+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.
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { Button, TextFormField } from '@nxgt/material/components';
+import { useSubmitOnce } from '@nxgt/material/hooks';
+
+type Values = { email: string };
+
+export function NewsletterForm({ save }: { save: (values: Values) => Promise<void> }) {
+  const { control, handleSubmit, formState } = useForm<Values>({ defaultValues: { email: '' } });
+  const submitOnce = useSubmitOnce();
+  return (
+    // handleSubmit returns a promise: the guard opens again when `save` ends.
+    <form onSubmit={submitOnce(handleSubmit(save))}>
+      <TextFormField control={control} name="email" label="Email" />
+      <Button type="submit" loading={formState.isSubmitting}>
+        Subscribe
+      </Button>
+    </form>
+  );
+}
+```
+
+**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 router's form submission, followed by its navigation
+  state: `useSubmitOnce(navigation.state !== 'idle')`), 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 React, `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`.
+
 ## `@nxgt/material/i18n`
 
 | Export | What it does |

package/docs/guides/i18n.md

@@ -299,6 +299,19 @@ fichier.") when it cannot show it, `material.file-preview.download`
 "Seuls les premiers {size} de ce fichier sont affichés.") under a text cut
 by the size cap; the text or Markdown it shows scrolls in a region named by
 `material.file-preview.content` ("Contents of {name}", "Contenu de {name}").
+`EnrolmentSecret` reads `material.enrolment-secret.qr-label` ("QR code to
+scan with your authenticator app"), `open-app` ("Open in your authenticator
+app", "Ouvrir dans votre application d'authentification"), `manual` ("Or
+type this key in the app:"), `secret-label` ("Setup key", "Clé de
+configuration"), `copy` ("Copy the key") and `copied` ("Key copied", "Clé
+copiée"); each has a prop that overrides it. `RecoveryCodes` reads
+`material.recovery-codes.title` and `list` ("Recovery codes", "Codes de
+récupération"), `warning` ("Each code works once. Keep them somewhere safe:
+they are shown only now."), `copy`, `copied` and `copy-failed` ("Copy codes",
+"Codes copied", "Copy failed"), `download`, `print`, `saved` ("I have saved
+these codes", "J'ai enregistré ces codes"), `saved-required` ("Tick the box
+once your codes are safe") and `done`; `title`, `warning` and `labels`
+override them. `AuthCard` has no copy of its own.
 `material.carousel.roledescription` /
 `slide` and `material.attributes.buttons.add-option` are there for
 `@nxgt/material-vue`'s carousel and attribute options, so the bundles hold
@@ -407,6 +420,10 @@ z.config({
 
 Examples and per-field overrides are in [forms](forms.md#validation-messages).
 
+Your own rules' messages — a refinement carrying an error code in
+`params.code` — are worded by your translator, in the provider's language,
+with `useCodeResolver`: see [forms](forms.md#wording-errors-by-code).
+
 ## Server rendering
 
 On the server there is no `localStorage`, so without help the server renders

package/docs/guides/printing.md

@@ -1397,3 +1397,30 @@ Under pnpm the glob is
 `pdfkitStandardFonts()` is a Vite plugin and does not apply to Next.js.
 
 More on what a server bundle evaluates in [SSR](ssr.md).
+
+## Printing one element of the page
+
+`RecoveryCodes`' "Print" button prints its card and nothing else, with
+`window.print()`, no inline style and no new window. The same helper prints
+any element of yours: `printOnly(element, name?)` from
+`@nxgt/material/lib` marks `<html data-nxgt-print="<name>">` and
+the element (`data-nxgt-print-target`), opens the print dialog, and removes
+both once printing is over (on `afterprint`, or as soon as `print()` returns
+where it blocks). The rules that hide the rest of the page are in the
+package's `styles.css` (`print-only.css`), under `@media print`: everything but the element,
+what holds it and what it holds is taken out of the flow, and the element
+starts at the top left of the first sheet.
+
+```tsx
+import { printOnly } from '@nxgt/material/lib';
+
+const stop = printOnly(document.getElementById('ticket') as HTMLElement, 'ticket');
+// When the element unmounts before the dialog closed (a browser whose
+// print() returns at once and never fires afterprint):
+stop();
+```
+
+Hide the controls inside the element with Tailwind's `print:hidden`. If the
+rest of the page still prints, an `!important` print rule of the app's wins
+over the package's: see
+[troubleshooting](../troubleshooting.md#recoverycodes-print-button-prints-the-whole-page).

package/docs/roadmap.md

@@ -157,6 +157,21 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **Signed-out pages and two-step verification** — `AuthCard`, the frame of a
+  sign-in page (one `main`, the card's title its `h1`, a status or alert
+  notice, safe-area padding); `EnrolmentSecret`, a TOTP enrolment's QR code,
+  app link and key grouped by four; `RecoveryCodes`, one-time codes to copy,
+  download or print alone, with an "I have saved these codes" confirmation
+  (`saved` / `onSavedChange`) an app's router guard can follow. 2.17.0.
+- **Focus after a change, one submit at a time, errors worded by code** —
+  `useFocusOnMount` focuses the heading of what replaced the content the user
+  acted on; `useSubmitOnce` drops a double click or a second Enter until the
+  request ends; `useCodeResolver` words a zod schema's errors in the page's
+  language, a refinement's `params.code` in the app's own words. 2.17.0.
+- **Long forms in titled sections** — `FormSection`: a heading (an `h2`, or
+  the level `titleAs` names), a description and actions, its fields in the form
+  grid's columns and one column on a phone, a rule between sections, and a
+  group a screen reader announces by its title. 2.17.0.
 - **A strict Content Security Policy** — a page that sends `script-src` with a
   nonce and no `'unsafe-eval'`, and `style-src-elem` with a nonce and no
   `'unsafe-inline'`, runs every component with no violation report:

package/docs/troubleshooting.md

@@ -27,6 +27,7 @@ words in your error.
 - [Dialogs, toasts or buttons no longer animate](#dialogs-toasts-or-buttons-no-longer-animate)
 - [A Content-Security-Policy reports a `data:` image on every form with a required field](#a-content-security-policy-reports-a-data-image-on-every-form-with-a-required-field)
 - [A Button's label overflows a card on a phone](#a-buttons-label-overflows-a-card-on-a-phone)
+- [A dialog or sheet scrolls, or clips a child, after upgrading](#a-dialog-or-sheet-scrolls-or-clips-a-child-after-upgrading)
 
 **Feedback**
 
@@ -62,6 +63,7 @@ words in your error.
 
 **Printing**
 
+- [`RecoveryCodes`' Print button prints the whole page](#recoverycodes-print-button-prints-the-whole-page)
 - [`Cannot find module '#standard-fonts/Helvetica'`](#cannot-find-module-standard-fontshelvetica)
 - [`still references '#standard-fonts/' after the transform`](#still-references-standard-fonts-after-the-transform)
 - [`TypeError: (0 , t.createContext) is not a function` in a Next.js route handler](#typeerror-0--tcreatecontext-is-not-a-function-in-a-nextjs-route-handler)
@@ -105,6 +107,8 @@ words in your error.
 - [A test asserting the old Zod string length text fails](#a-test-asserting-the-old-zod-string-length-text-fails)
 - [A calendar's weekday row is in English on a French page](#a-calendars-weekday-row-is-in-english-on-a-french-page)
 - [An accessibility audit reports low contrast on a calendar's weekday row or its days](#an-accessibility-audit-reports-low-contrast-on-a-calendars-weekday-row-or-its-days)
+- [Errors keep their old words after a language switch](#errors-keep-their-old-words-after-a-language-switch)
+- [`useCodeResolver` re-validates or resets the form on every render](#usecoderesolver-re-validates-or-resets-the-form-on-every-render)
 
 **Runtime**
 
@@ -148,6 +152,8 @@ words in your error.
 - [An `Autocomplete` lists more options than before, or "ecole" finds "École"](#an-autocomplete-lists-more-options-than-before-or-ecole-finds-école)
 - [`onQueryChange` runs more often after upgrading](#onquerychange-runs-more-often-after-upgrading)
 - [An older search's results replace the newer ones in an `Autocomplete`](#an-older-searchs-results-replace-the-newer-ones-in-an-autocomplete)
+- [An `Autocomplete` option does nothing on click or Enter](#an-autocomplete-option-does-nothing-on-click-or-enter)
+- ["The search failed. Try again." no longer shows in an `Autocomplete`](#the-search-failed-try-again-no-longer-shows-in-an-autocomplete)
 - [A test no longer finds `aria-invalid` on an `OtpField` slot](#a-test-no-longer-finds-aria-invalid-on-an-otpfield-slot)
 - [A test no longer finds the breadcrumb's home button](#a-test-no-longer-finds-the-breadcrumbs-home-button)
 - [A test no longer finds a sidebar entry by the `button` role](#a-test-no-longer-finds-a-sidebar-entry-by-the-button-role)
@@ -613,6 +619,27 @@ your own through `className`. With `asChild`, put the label in a `<span>`:
 </Button>
 ```
 
+### A dialog or sheet scrolls, or clips a child, after upgrading
+
+**When:** after upgrading, a tall `DialogContent`, `AlertDialogContent` or
+`SheetContent` shows a scrollbar, or a child that stuck out of it (a popover, a
+focus ring, a wide table) is clipped.
+**Why:** these contents are now capped to the viewport (`max-h-[calc(100dvh-2rem)]`,
+`100vh` where `dvh` is unsupported; a top or bottom sheet is capped at `100dvh`)
+and carry `overflow-y-auto`, so a long body scrolls inside them instead of
+leaving the title off-screen. Setting `overflow-y` makes `overflow-x` clip or
+scroll too.
+**Fix:** to keep the old behaviour on one dialog, remove the cap and the scroll
+with `className="max-h-none overflow-visible"`; to change the cap, pass your own
+`max-h-*` (it wins on browsers with `dvh` support):
+
+```tsx
+<DialogContent className="max-h-none overflow-visible">
+```
+
+For a dialog that should grow taller than the screen and scroll inside the
+overlay instead of capping, use `DialogScrollContent`.
+
 ## Feedback
 
 ### A toast with an action never goes away
@@ -1105,6 +1132,29 @@ dependencies: `--external @nxgt/material --external @nxgt/material-core`.
 
 ## Printing
 
+### `RecoveryCodes`' Print button prints the whole page
+
+**When:** "Print" on `RecoveryCodes` prints the rest of the page with the
+codes, or the codes away from the top of the sheet.
+**Why:** the button only marks the page (`<html data-nxgt-print>`) and the
+card (`data-nxgt-print-target`); hiding the rest is a `@media print` rule in
+the package's stylesheet (`print-only.css`). A page that does not load
+`@nxgt/material/styles.css` (or `dist/material.css`) has no such rule, and an app's own
+print rule that is `!important` (or a `position` on an ancestor set with
+`!important`) wins over it.
+**Fix:** load the stylesheet the setup guide names, and keep your print
+rules off the marked page:
+
+```css
+/* your app's print rules, everywhere but while one element is printed */
+@media print {
+  html:not([data-nxgt-print]) .page-header { position: static !important; }
+}
+```
+
+To print an element of your own the same way, call `printOnly(element)`
+from `@nxgt/material/lib`; the same rules apply to it.
+
 ### `Cannot find module '#standard-fonts/Helvetica'`
 
 **When:** a built SSR server answers nothing on every route, `/health`
@@ -1839,6 +1889,52 @@ react-day-picker hides the weekday row from assistive tech
 (`<thead aria-hidden>`); in a test, find a day by its full date instead
 (`getByRole('gridcell', { name: 'jeudi 1 octobre 2026' })`).
 
+### Errors keep their old words after a language switch
+
+**When:** a form validated with `useCodeResolver` shows an error, the user
+switches the language, and the error stays in the old one (a code's words
+or a zod message alike).
+**Why:** the resolver follows the new language, but react-hook-form keeps
+the message it computed until the field is validated again.
+**Fix:** validate again when the language changes, once the form was
+submitted:
+
+```tsx
+const resolver = useCodeResolver(schema, { translate });
+const { trigger, formState } = useForm({ resolver });
+const { isSubmitted } = formState;
+useEffect(() => {
+  if (isSubmitted) trigger();
+}, [resolver, isSubmitted, trigger]); // a new resolver is a new language
+```
+
+Storybook: `Guides/Forms/useCodeResolver`. See
+[forms](guides/forms.md#wording-errors-by-code).
+
+### `useCodeResolver` re-validates or resets the form on every render
+
+**When:** `translate` or `codeOf` is written inline in the component
+(`useCodeResolver(schema, { codeOf: (issue) => … })`), or the schema is built
+in the component body.
+**Why:** the resolver is memoised on the schema, the language, `translate`
+and `codeOf`: a new function or schema each render makes a new resolver
+each render.
+**Fix:** define the schema, the translator and `codeOf` at module scope (or
+with `useMemo` / `useCallback` when they depend on props):
+
+```tsx
+import { type CodeIssue, defaultCodeOf, isEmptyRequired, useCodeResolver } from '@nxgt/material/components';
+
+const schema = z.object({ username: z.string().min(3) });
+const codeOf = (issue: CodeIssue) =>
+  isEmptyRequired(issue) ? 'errors.required' : defaultCodeOf(issue);
+
+export function SignUpForm() {
+  const resolver = useCodeResolver(schema, { translate, codeOf });
+  // …
+}
+```
+
 ## Runtime
 
 ### A test asserting the old Zod string length text fails
@@ -2837,6 +2933,51 @@ an older query, even from an API that ignores the signal:
 />
 ```
 
+### An `Autocomplete` option does nothing on click or Enter
+
+**When:** one option of an `Autocomplete` is greyed out and clicking it, or
+pressing Enter on it, changes nothing, with no error.
+**Why:** that option has `disabled: true` (in the local `options` or in what
+`onSearch` returns). It is listed and announced with `aria-disabled`, and never
+picked, in `single` and `multiple` mode; the arrow keys still reach a disabled option so that it is announced, but Enter does not pick it.
+**Fix:** drop `disabled` from the option, or build it only for the options that
+may be chosen:
+
+```tsx
+<Autocomplete
+	mode="single"
+	value={value}
+	onValueChange={setValue}
+	options={[
+		{ value: 'a', label: 'Alpha', disabled: true }, // listed, never picked
+		{ value: 'b', label: 'Beta' },
+	]}
+/>
+```
+
+### "The search failed. Try again." no longer shows in an `Autocomplete`
+
+**When:** after upgrading, an `Autocomplete` whose `onSearch` rejects shows
+your own text, or nothing generic, where it used to say "The search failed. Try
+again."
+**Why:** `searchError` now takes precedence over the generic text with `onSearch`
+too, in the list and in the live announcement. The generic text only shows
+while `searchError` is unset.
+**Fix:** nothing, if the reason is what you want. To get the generic text back,
+leave `searchError` unset or empty; to show a reason, keep it from `onSearchError` and pass it
+back:
+
+```tsx
+<Autocomplete
+	mode="single"
+	value={value}
+	onValueChange={setValue}
+	onSearch={search}
+	onSearchError={() => setReason('Directory unreachable')}
+	searchError={reason}
+/>
+```
+
 ### A test no longer finds `aria-invalid` on an `OtpField` slot
 
 **When:** `[data-slot="input-otp-slot"][aria-invalid]` (or

package/lib/components/components.css

@@ -29,6 +29,7 @@
 @import "./ui/layout/app-bar/bottom-app-bar.css";
 @import "./ui/primitives/label/label.css";
 @import "./ui/feedback/toast/toast.css";
+@import "./print-only.css";
 @import "./ui/fields/contacts/contact-item.css";
 @import "./ui/fields/opening-hours/opening-hours-item.css";
 @import "./ui/fields/attributes/attribute-form/attribute-form.css";

package/lib/components/print-only.css

@@ -0,0 +1,44 @@
+/* Printing one element of the page (`printOnly`, from `/lib` or
+ * @nxgt/material-core/print-only; RecoveryCodes' Print button): while
+ * <html data-nxgt-print> is set, print media shows the element marked
+ * data-nxgt-print-target and nothing else. No inline style: only these rules,
+ * the same in @nxgt/material and @nxgt/material-vue.
+ *
+ * Everything that neither is, holds nor sits inside the target is taken out
+ * of the flow, so the page prints no blank sheets after it; where :has() is
+ * not supported, that rule is dropped and `visibility` alone hides the rest.
+ * The target's ancestors stop positioning it, so it starts at the top left of
+ * the first page. Unlayered, these rules beat the components' Tailwind
+ * utilities (layered) with no `!important`. */
+@media print {
+	html[data-nxgt-print]
+		body
+		*:not(
+			[data-nxgt-print-target],
+			[data-nxgt-print-target] *,
+			:has([data-nxgt-print-target])
+		) {
+		display: none;
+	}
+
+	html[data-nxgt-print] body * {
+		visibility: hidden;
+	}
+
+	html[data-nxgt-print] :has([data-nxgt-print-target]) {
+		position: static;
+		transform: none;
+	}
+
+	html[data-nxgt-print] [data-nxgt-print-target],
+	html[data-nxgt-print] [data-nxgt-print-target] * {
+		visibility: visible;
+	}
+
+	html[data-nxgt-print] [data-nxgt-print-target] {
+		position: absolute;
+		inset: 0 0 auto 0;
+		margin: 0;
+		box-shadow: none;
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "2.16.0",
+	"version": "2.18.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -119,7 +119,7 @@
 		"docs:previews": "vitest run --project previews"
 	},
 	"dependencies": {
-		"@nxgt/material-core": "^0.9.1",
+		"@nxgt/material-core": "^0.10.0",
 		"@base-ui/react": "^1.6.0",
 		"@dnd-kit/core": "^6.3.1",
 		"@dnd-kit/sortable": "^10.0.0",