@nxgt/material 2.16.0 → 2.17.0

package/dist/{use-heading-spy-C1KA3PrF.js → use-heading-spy-XkSExwoT.js}

@@ -1,24 +1,24 @@
-import { n as e } from "./stored-language-DPqzxRmf.js";
-import { r as t } from "./i18n-provider-C3SlA4J0.js";
+import { n as e } from "./stored-language-BKoohv2_.js";
+import { r as t } from "./i18n-provider-Dv9ZSmgO.js";
 import { _ as n, g as r, h as i, n as a, v as o, y as s } from "./number.utils-BiBN2hWJ.js";
-import { createContext as c, useCallback as l, useContext as u, useEffect as d, useMemo as f, useSyncExternalStore as p } from "react";
+import { createContext as c, useCallback as l, useContext as u, useEffect as d, useMemo as f, useRef as p, useSyncExternalStore as m } from "react";
 //#region lib/hooks/resolve-theme.ts
-function m(e, t) {
+function h(e, t) {
 	let n = e === "light" || e === "dark" ? e : "system";
 	return {
 		theme: n === "system" ? t ? "dark" : "light" : n,
 		preference: n
 	};
 }
-function h(e) {
+function g(e) {
 	typeof document > "u" || (document.documentElement.classList.toggle("dark", e === "dark"), document.documentElement.style.colorScheme = e);
 }
 //#endregion
 //#region lib/hooks/theme-store.ts
-var g = "theme", _ = /* @__PURE__ */ new Set(), v;
-function y() {
-	let t = e(g);
-	if (t == null) return v;
+var _ = "theme", v = /* @__PURE__ */ new Set(), y;
+function b() {
+	let t = e(_);
+	if (t == null) return y;
 	try {
 		let e = JSON.parse(t);
 		return typeof e == "string" ? e : void 0;
@@ -26,63 +26,63 @@ function y() {
 		return t;
 	}
 }
-function b() {
-	for (let e of _) e();
+function x() {
+	for (let e of v) e();
 }
-function x(e) {
-	(e.key === g || e.key === null) && b();
+function S(e) {
+	(e.key === _ || e.key === null) && x();
 }
-var S = {
+var C = {
 	subscribe(e) {
-		return _.add(e), _.size === 1 && typeof window < "u" && window.addEventListener("storage", x), () => {
-			_.delete(e), _.size === 0 && typeof window < "u" && window.removeEventListener("storage", x);
+		return v.add(e), v.size === 1 && typeof window < "u" && window.addEventListener("storage", S), () => {
+			v.delete(e), v.size === 0 && typeof window < "u" && window.removeEventListener("storage", S);
 		};
 	},
-	getSnapshot: y,
+	getSnapshot: b,
 	getServerSnapshot: () => void 0,
 	set(e) {
-		v = e === "system" ? void 0 : e;
+		y = e === "system" ? void 0 : e;
 		try {
-			e === "system" ? globalThis.localStorage?.removeItem(g) : globalThis.localStorage?.setItem(g, JSON.stringify(e));
+			e === "system" ? globalThis.localStorage?.removeItem(_) : globalThis.localStorage?.setItem(_, JSON.stringify(e));
 		} catch {}
-		b();
+		x();
 	}
 };
 //#endregion
 //#region lib/hooks/use-ssr-media-query.ts
-function C(e, t) {
-	return p(l((t) => {
+function w(e, t) {
+	return m(l((t) => {
 		let n = window.matchMedia(e);
 		return n.addEventListener("change", t), () => n.removeEventListener("change", t);
 	}, [e]), () => window.matchMedia(e).matches, () => t);
 }
 //#endregion
 //#region lib/hooks/use-theme.ts
-function w() {
-	let e = C("(prefers-color-scheme: dark)", !1), { theme: t, preference: n } = m(p(S.subscribe, S.getSnapshot, S.getServerSnapshot), e);
+function T() {
+	let e = w("(prefers-color-scheme: dark)", !1), { theme: t, preference: n } = h(m(C.subscribe, C.getSnapshot, C.getServerSnapshot), e);
 	return {
 		theme: t,
 		preference: n,
 		updateTheme: l((t) => {
-			S.set(t), h(m(t === "system" ? void 0 : t, e).theme);
+			C.set(t), g(h(t === "system" ? void 0 : t, e).theme);
 		}, [e])
 	};
 }
 //#endregion
 //#region lib/hooks/use-csp-nonce.ts
-var T = c(void 0), E = c(0);
-function D() {
-	return u(T);
+var E = c(void 0), D = c(0);
+function O() {
+	return u(E);
 }
 //#endregion
 //#region lib/hooks/use-mobile.ts
-var O = 768;
-function k() {
-	return C(`(max-width: ${O - 1}px)`, !1);
+var k = 768;
+function A() {
+	return w(`(max-width: ${k - 1}px)`, !1);
 }
 //#endregion
 //#region ../../node_modules/date-fns/locale/fr/_lib/formatDistance.js
-var A = {
+var j = {
 	lessThanXSeconds: {
 		one: "moins d’une seconde",
 		other: "moins de {{count}} secondes"
@@ -144,10 +144,10 @@ var A = {
 		one: "presqu’un an",
 		other: "presque {{count}} ans"
 	}
-}, j = (e, t, n) => {
-	let r, i = A[e];
+}, M = (e, t, n) => {
+	let r, i = j[e];
 	return r = typeof i == "string" ? i : t === 1 ? i.one : i.other.replace("{{count}}", String(t)), n?.addSuffix ? n.comparison && n.comparison > 0 ? "dans " + r : "il y a " + r : r;
-}, M = {
+}, N = {
 	date: s({
 		formats: {
 			full: "EEEE d MMMM y",
@@ -175,18 +175,18 @@ var A = {
 		},
 		defaultWidth: "full"
 	})
-}, N = {
+}, P = {
 	lastWeek: "eeee 'dernier à' p",
 	yesterday: "'hier à' p",
 	today: "'aujourd’hui à' p",
 	tomorrow: "'demain à' p'",
 	nextWeek: "eeee 'prochain à' p",
 	other: "P"
-}, P = (e, t, n, r) => N[e], F = {
+}, F = (e, t, n, r) => P[e], I = {
 	narrow: ["av. J.-C", "ap. J.-C"],
 	abbreviated: ["av. J.-C", "ap. J.-C"],
 	wide: ["avant Jésus-Christ", "après Jésus-Christ"]
-}, I = {
+}, L = {
 	narrow: [
 		"T1",
 		"T2",
@@ -205,7 +205,7 @@ var A = {
 		"3ème trimestre",
 		"4ème trimestre"
 	]
-}, L = {
+}, R = {
 	narrow: [
 		"J",
 		"F",
@@ -248,7 +248,7 @@ var A = {
 		"novembre",
 		"décembre"
 	]
-}, R = {
+}, z = {
 	narrow: [
 		"D",
 		"L",
@@ -285,7 +285,7 @@ var A = {
 		"vendredi",
 		"samedi"
 	]
-}, z = {
+}, B = {
 	narrow: {
 		am: "AM",
 		pm: "PM",
@@ -316,7 +316,7 @@ var A = {
 		evening: "du soir",
 		night: "du matin"
 	}
-}, B = (e, t) => {
+}, V = (e, t) => {
 	let n = Number(e), r = t?.unit;
 	if (n === 0) return "0";
 	let i = [
@@ -327,38 +327,38 @@ var A = {
 		"second"
 	], a;
 	return a = n === 1 ? r && i.includes(r) ? "ère" : "er" : "ème", n + a;
-}, V = ["MMM", "MMMM"], H = {
+}, H = ["MMM", "MMMM"], U = {
 	en: i,
 	fr: {
 		code: "fr",
-		formatDistance: j,
-		formatLong: M,
-		formatRelative: P,
+		formatDistance: M,
+		formatLong: N,
+		formatRelative: F,
 		localize: {
-			preprocessor: (e, t) => e.getDate() === 1 || !t.some((e) => e.isToken && V.includes(e.value)) ? t : t.map((e) => e.isToken && e.value === "do" ? {
+			preprocessor: (e, t) => e.getDate() === 1 || !t.some((e) => e.isToken && H.includes(e.value)) ? t : t.map((e) => e.isToken && e.value === "do" ? {
 				isToken: !0,
 				value: "d"
 			} : e),
-			ordinalNumber: B,
+			ordinalNumber: V,
 			era: o({
-				values: F,
+				values: I,
 				defaultWidth: "wide"
 			}),
 			quarter: o({
-				values: I,
+				values: L,
 				defaultWidth: "wide",
 				argumentCallback: (e) => e - 1
 			}),
 			month: o({
-				values: L,
+				values: R,
 				defaultWidth: "wide"
 			}),
 			day: o({
-				values: R,
+				values: z,
 				defaultWidth: "wide"
 			}),
 			dayPeriod: o({
-				values: z,
+				values: B,
 				defaultWidth: "wide"
 			})
 		},
@@ -488,8 +488,8 @@ var A = {
 		}
 	}
 };
-function U() {
-	let e = t()?.language ?? "en", n = f(() => H[e] ?? i, [e]);
+function W() {
+	let e = t()?.language ?? "en", n = f(() => U[e] ?? i, [e]);
 	return {
 		language: e,
 		locale: n,
@@ -497,10 +497,18 @@ function U() {
 	};
 }
 //#endregion
+//#region lib/hooks/use-focus-on-mount.ts
+function G(e = !0) {
+	let t = p(null);
+	return d(() => {
+		e && t.current?.focus();
+	}, [e]), t;
+}
+//#endregion
 //#region lib/hooks/use-heading-spy.ts
-var W = "0px 0px -65% 0px", G = [0, 1];
-function K(e, t, n) {
-	let r = n?.rootMargin ?? W, i = n?.threshold ?? G;
+var K = "0px 0px -65% 0px", q = [0, 1];
+function J(e, t, n) {
+	let r = n?.rootMargin ?? K, i = n?.threshold ?? q;
 	d(() => {
 		if (e.length === 0) return;
 		let n = e.map((e) => document.getElementById(e)).filter((e) => e != null);
@@ -522,4 +530,4 @@ function K(e, t, n) {
 	]);
 }
 //#endregion
-export { E as a, C as c, T as i, h as l, U as n, D as o, k as r, w as s, K as t, m as u };
+export { E as a, T as c, h as d, A as i, w as l, G as n, D as o, W as r, O as s, J as t, g as u };

package/dist/{use-material-translation-DMa4Xrnd.js → use-material-translation-Cndoq_iK.js}

@@ -1,5 +1,5 @@
-import { r as e } from "./i18n-provider-C3SlA4J0.js";
-import { t } from "./translate-material-CqB-j9WD.js";
+import { r as e } from "./i18n-provider-Dv9ZSmgO.js";
+import { t } from "./translate-material-CCJg3yfc.js";
 import { useCallback as n } from "react";
 //#region lib/i18n/use-material-translation.ts
 function r() {

package/dist/{usecaseDiagram-POWQR4AR-FMjCkoxs.js → usecaseDiagram-POWQR4AR-CPOCe5We.js}

@@ -8,11 +8,11 @@ import "./chunk-7PRAP22T-0C6_H8Li.js";
 import { a as g, i as _, o as v, r as y } from "./chunk-J5ZVWO5B-DmRRmhon.js";
 import "./chunk-7INBJB4K-k-I67NSP.js";
 import "./chunk-5DYCD2WN-Cd1zazNp.js";
-import "./chunk-Z7XXMR3K-BSXPgLtN.js";
+import "./chunk-Z7XXMR3K-C8MhuVIi.js";
 import { t as ee } from "./chunk-XXDRQBXY-dKXxu_aj.js";
 import { t as te } from "./chunk-WEXAMYUT-CbFOhEve.js";
 import "./chunk-UA2S7LBM-ChuksCDg.js";
-import { r as ne, t as re } from "./chunk-GNY47TPC-BZdgq2LF.js";
+import { r as ne, t as re } from "./chunk-GNY47TPC-DdqgSBxM.js";
 //#region ../../node_modules/chevrotain/node_modules/lodash-es/_freeGlobal.js
 var ie = typeof global == "object" && global && global.Object === Object && global, ae = typeof self == "object" && self && self.Object === Object && self, b = ie || ae || Function("return this")(), oe = b.Symbol, se = Object.prototype, ce = se.hasOwnProperty, le = se.toString, ue = oe ? oe.toStringTag : void 0;
 function de(e) {

package/dist/{xychartDiagram-PMCCYNJV-B76HOkCh.js → xychartDiagram-PMCCYNJV-Cleaihn8.js}

@@ -1,4 +1,4 @@
-import { at as e, rt as t, st as n } from "./components-Bkdm6jn6.js";
+import { at as e, rt as t, st as n } from "./components-CIYQrI45.js";
 import { n as r } from "./src-CsLQInsN.js";
 import { i } from "./chunk-ZIGJFQKS-9VXArDKF.js";
 import { n as a } from "./chunk-Y2CYZVJY-BAad7w_K.js";

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/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
 
@@ -703,3 +705,102 @@ The props are those of `react-barcode`. The barcode sits in an
 not that span.
 
 **Storybook:** `Data display/Barecode` · **Vue:** `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.
+
+```tsx
+import { EnrolmentSecret } from '@nxgt/material/components';
+
+<EnrolmentSecret
+  uri="otpauth://totp/Acme:ada%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=Acme"
+  secret="JBSWY3DPEHPK3PXP"
+/>
+```
+
+| 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` · **Vue:** `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".
+
+```tsx
+import { RecoveryCodes } from '@nxgt/material/components';
+
+<RecoveryCodes
+  codes={codes}
+  description="Use one of them to sign in if you lose your phone."
+  fileHeading={`Recovery codes for ${email}`}
+  saved={saved}
+  onSavedChange={setSaved}
+  onDone={() => navigate('/settings/security')}
+/>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `codes` | `readonly string[]` | — | an ordered list named "Recovery codes" |
+| `title`, `titleAs` | `ReactNode`, `'h2' \| 'h3' \| 'h4'` | "Recovery codes", `'h2'` | the card's heading |
+| `description` | `ReactNode` | — | a line under it |
+| `warning` | `ReactNode \| false` | "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` | `() => void` | — | shows "Done", which calls it once the confirmation is ticked |
+| `saved` / `onSavedChange` | `boolean` / `(saved) => void` | 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/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.
+
+Leaving the page before the codes are saved is the app's to guard, with its
+router: block the navigation while `saved` is false, and ask the browser
+too:
+
+```tsx
+const [saved, setSaved] = useState(false);
+useBlocker(() => !saved); // React Router: confirm, then blocker.proceed()
+useEffect(() => {
+  if (saved) return;
+  const ask = (event: BeforeUnloadEvent) => event.preventDefault();
+  window.addEventListener('beforeunload', ask);
+  return () => window.removeEventListener('beforeunload', ask);
+}, [saved]);
+
+<RecoveryCodes codes={codes} saved={saved} onSavedChange={setSaved} onDone={done} />
+```
+
+**Storybook:** `Data display/RecoveryCodes` · **Vue:** `RecoveryCodes` (`v-model:saved`, `@done`; slots `title`, `description`, `warning`)

package/docs/components/form-fields.md

@@ -10,6 +10,7 @@ for the 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 |
@@ -85,6 +86,83 @@ config: the map is browser-only and lives on `@nxgt/material/map`, so use
 
 ---
 
+## 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.
+
+```tsx
+import { useForm } from 'react-hook-form';
+import {
+  Button,
+  EmailFormField,
+  FormSection,
+  SwitchFormField,
+  TextFormField,
+} from '@nxgt/material/components';
+
+type Values = { firstName: string; email: string; contact: string; digest: boolean };
+
+export function SettingsForm({ onSave }: { onSave: (values: Values) => void }) {
+  const { control, handleSubmit } = useForm<Values>({
+    defaultValues: { firstName: '', email: '', contact: '', digest: false },
+  });
+  return (
+    <form className="form-grid-layout" onSubmit={handleSubmit(onSave)}>
+      <div data-slot="form-fields">
+        <FormSection title="Profile">
+          <TextFormField control={control} name="firstName" label="First name" />
+          <EmailFormField control={control} name="email" label="Email" />
+        </FormSection>
+        <FormSection
+          title="Emergency contact"
+          description="Who we call when you cannot be reached."
+          actions={<Button variant="outlined" size="sm">Add another</Button>}
+        >
+          <TextFormField control={control} name="contact" label="Name" />
+        </FormSection>
+        <FormSection title="Notifications">
+          <SwitchFormField control={control} name="digest" label="Digest" placeholder="Email me a weekly digest" />
+        </FormSection>
+      </div>
+      <div data-slot="form-actions">
+        <Button type="submit">Save</Button>
+      </div>
+    </form>
+  );
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` | — | the section's heading, which names the group |
+| `titleAs` | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'h2'` | the heading level: `'h3'` when the form already sits under an `h2` |
+| `description` | `ReactNode` | — | a muted line under the title; the group's accessible description |
+| `actions` | `ReactNode` | — | controls beside the title, wrapping under it on a phone |
+| `separated` | `boolean` | `true` | a rule above the section when it follows another `FormSection` |
+
+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` · **Vue:** `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 |
@@ -81,6 +82,56 @@ the [app shell guide](../guides/app-shell.md#breadcrumbs)).
 
 ---
 
+## 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.
+
+```tsx
+import { AuthCard, Button, EmailField, LanguageSwitcher, PasswordField } from '@nxgt/material/components';
+
+<AuthCard
+  title="Sign in"
+  description="Welcome back."
+  notice={expired ? 'This link has expired.' : undefined}
+  noticeTone="error"
+  brand={<img src="/logo.svg" alt="Acme" height={24} />}
+  toolbar={<LanguageSwitcher />}
+  footer={<a href="/terms">Terms</a>}
+>
+  <form className="flex flex-col gap-4" onSubmit={signIn}>
+    <EmailField label="Email" name="email" autoComplete="email" />
+    <PasswordField label="Password" name="password" autoComplete="current-password" />
+    <Button type="submit">Sign in</Button>
+  </form>
+</AuthCard>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` | — | the page's `h1`, in the card's title |
+| `description` | `ReactNode` | — | a line under the title |
+| `notice` | `ReactNode` | — | 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` | `ReactNode` | — | the row above the card, left and right; it renders only when one is given |
+| `banner` | `ReactNode` | — | above that row (an update notice) |
+| `footer` | `ReactNode` | — | 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 props reach the `main`.
+
+**Storybook:** `Navigation & layout/AuthCard` · **Vue:** `AuthCard` (slots `title`, `description`, `notice`, `brand`, `toolbar`, `banner`, `footer`)
+
+---
+
 ## Sidebar
 
 ![Sidebar](../previews/navigation-layout-sidebar.webp)