@nxgt/material 2.16.0 → 2.17.0

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

@@ -62,6 +62,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 +106,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**
 
@@ -1105,6 +1108,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 +1865,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

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.17.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",