@nxgt/material 3.45.0 → 3.47.0

package/docs/components/data-display.md

@@ -24,7 +24,7 @@ from `@nxgt/material/components`.
 | <img src="../previews/data-display-entityheader.webp" width="96" alt=""> | [EntityHeader](#entityheader) | Page header with status, metadata and actions |
 | <img src="../previews/data-display-listtile.webp" width="96" alt=""> | [ListTile](#listtile) | Row with leading / trailing slots, row actions, chips and a divided variant |
 | <img src="../previews/data-display-accordioncard.webp" width="96" alt=""> | [AccordionCard](#accordioncard) | Accordion rendered from `items` |
-| <img src="../previews/data-display-timeline.webp" width="96" alt=""> | [Timeline](#timeline) | Vertical event timeline with relative times |
+| <img src="../previews/data-display-timeline.webp" width="96" alt=""> | [Timeline](#timeline) | Vertical event timeline: shaped markers, cards, alternating sides, day groups (`DaySeparator` headings, words from `material.day-separator.*`), relative times; `layout="auto"` needs a parent with a definite width (`rail` in a `w-fit` parent) |
 | <img src="../previews/data-display-changehistory.webp" width="96" alt=""> | [ChangeHistory](#changehistory) | History of the changes made to anything, as a rail or as cards |
 | <img src="../previews/data-display-zonedtime.webp" width="96" alt=""> | [ZonedTime](#zonedtime) | A moment written in a given time zone, identical on the server and the client |
 | <img src="../previews/data-display-eventchip.webp" width="96" alt=""> | [EventChip](#eventchip) | Calendar event pill, soft, solid or outlined |
@@ -36,8 +36,10 @@ 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-enrolmentcard.webp" width="96" alt=""> | [EnrolmentCard](#enrolmentcard) | Turning on an authenticator app: the key, a notice and the first code to check, driven by props |
 | <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 |
+| <img src="../previews/data-display-recoverycodesstatus.webp" width="96" alt=""> | [RecoveryCodesStatus](#recoverycodesstatus) | How many recovery codes are left, and a new set behind a code |
 
 ## Avatar
 
@@ -963,7 +965,12 @@ import { AccordionCard } from '@nxgt/material/components';
 
 ![Timeline](../previews/data-display-timeline.webp)
 
-Vertical event timeline with toned icons and relative times.
+Vertical event timeline with toned markers and relative times. Each marker is
+44px and takes a shape by tone (circle, squircle, cookie, clover, diamond,
+burst) in the tone's container colour; an item with `children` is a rounded
+card with a subtle tone bar. Once the timeline's own container is 48rem wide
+(a container query, not the viewport) the two sides alternate; narrower, it is
+a single rail. `grouped` opens each day with a `DaySeparator` heading.
 
 ```tsx
 import { Package, Pencil } from 'lucide-react';
@@ -982,11 +989,45 @@ Parts: `Timeline`, `TimelineItem` (one row, for your own list),
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `items` | `TimelineItemData[]` | — | `title`, `description`, `timestamp`, `icon` or `avatar`, `tone`, `children` |
+| `items` | `TimelineItemData[]` | — | `title`, `description`, `timestamp`, `icon` or `avatar`, `tone`, `children` (rendered as a card) |
+| `grouped` | `boolean` | `false` | a heading per day ("Today", "Yesterday", a weekday or a date: a `DaySeparator`, real `<h3>`, with a `<time dateTime>` and its count); items keep the order given |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | the level of the day headings |
+| `layout` | `'auto' \| 'rail'` | `'auto'` | `'auto'` alternates sides in a wide container (it measures its own container: its parent needs a definite width, see below); `'rail'` never does |
+| `timeZone` | `string` | — | the zone the days are cut in |
+| `now` | `Date` | — | the reference instant for "Today" and "Yesterday" |
 | `loading` | `boolean` | `false` | skeleton rows |
 | `empty` | `ReactNode` | "No activity yet" | shown when `items` is empty |
 
-**Storybook:** `Data display/Timeline` · **Vue:** `Timeline`, `TimelineItem`, `RelativeTime` (without `now`, `tooltip`, `focusable` and `ref`, React only)
+```tsx
+// Grouped on the server too: fix the zone and the reference instant.
+<Timeline items={items} grouped timeZone="UTC" now={new Date('2026-03-15T12:00:00Z')} aria-label="Order history" />
+
+// One rail, never alternating sides.
+<Timeline items={items} layout="rail" aria-label="Order history" />
+```
+
+**Server rendering.** Without both `timeZone` and `now`, `grouped` renders no
+day headings on the server and on the first client render, and adds them once
+mounted (and logs a development warning once). With both, the headings render
+on the server too. The list is one flat `<ol>`: each heading sits inside the first `<li>` of
+its day, ahead of the item's content (a list may only hold `<li>`s, so a
+standalone heading row fails axe), never around the items, so an item keeps its
+parent, its key and its state when they appear (a counter inside an item is not reset).
+**Width.** `layout="auto"` is a container query on the Timeline itself, so its
+parent needs a definite width (a block, a grid cell, a fixed width). In a
+shrink-to-fit parent (`w-fit`, an inline flex item) it collapses to 0 wide:
+use `layout="rail"` there, which sets no container. In right-to-left the wide
+layout mirrors, time labels included. `now` also fixes the relative times
+("5 minutes ago") of the items. **Accessibility:** the list keeps its
+`aria-label`, markers are decorative, each day heading is a real heading whose
+count reads as "N events", and every item of a day has `aria-describedby`
+pointing to that heading (a nested list labelled by it would put the items
+under a new parent). **Migrating:** the new look is the default; pass
+`layout="rail"` for a single rail. Children now render as a card, not as text
+under the title. New key: `material.timeline.events`; the day words come from
+`material.day-separator.today` and `yesterday`.
+
+**Storybook:** `Data display/Timeline` · **Vue:** `Timeline`, `TimelineItem`, `RelativeTime` (without `now`, `tooltip`, `focusable` and `ref`, React only); the redesign and `grouped`, `layout`, `timeZone`, `now` are React only for now (#1810)
 
 ---
 
@@ -1375,6 +1416,56 @@ not that span.
 
 ---
 
+## EnrolmentCard
+
+![EnrolmentCard](../previews/data-display-enrolmentcard.webp)
+
+Turning on an authenticator app, in one card: the [EnrolmentSecret](#enrolmentsecret) (QR code, app link, the key) on a tinted surface, a notice that the other devices are signed out, and the first code to prove the app works, with "Activate" and a tonal Cancel. It is **driven by props**, like the [VerificationCode](form-fields.md#verificationcode) it holds: `attemptsLeft`, `locked`, `error` and `pending` are your answer to the last code, `onSubmit` your call. It fetches nothing.
+
+```tsx
+import { EnrolmentCard, VerificationLockProvider } from '@nxgt/material/components';
+
+<VerificationLockProvider>
+  <EnrolmentCard
+    uri={enrolment.uri}
+    secret={enrolment.secret}
+    onSubmit={(code) => activate(code)} // the code is an app's code
+    onCancel={() => navigate('/settings/security')}
+    error={answer.error}
+    attemptsLeft={answer.attemptsLeft}
+    locked={answer.locked}
+    pending={activating}
+  />
+</VerificationLockProvider>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `uri`, `secret` | `string` | — | passed to `EnrolmentSecret` |
+| `onSubmit` | `(code, { kind }) => unknown` | — | called with the six digits; return a promise to hold a second submit |
+| `onCancel` | `() => void` | — | draws a Cancel beside Activate; left out, no Cancel |
+| `cancelVariant` | `ButtonVariant` | `'tonal'` | the Cancel button's variant; `'outlined'` or `'ghost'` restores an earlier look |
+| `attemptsLeft`, `locked`, `error`, `pending` | as `VerificationCode` | — | the answer to the last code: a wrong code empties the field and focuses it with the tries left; no tries left, or `locked`, locks the form and the page-wide lock. `error="throttled"` shows the general wait line only (no Resend, no `retryAfter` here). |
+| `title`, `titleAs`, `description` | `ReactNode`, `'h2'…`, `ReactNode \| false` | built-in, `'h2'` | the heading ("Set up your authenticator app"), its level, and the line under it |
+| `focusTitle` | `boolean` | `true` | the title takes the focus once mounted |
+| `length` | `number` | `6` | the slots in the code field, as `VerificationCode` |
+| `sessionsNotice` | `ReactNode \| false` | "Turning this on signs you out on your other devices." | the notice that the other devices are (or were) signed out; pass the after-the-fact wording once they were, `false` for none |
+| `status` | `ReactNode` | — | a notice line over the field ("Your session is confirmed. Type the next code.") |
+| `secretProps` | `Partial<EnrolmentSecretProps>` | — | the QR size, labels and copy icon |
+| `submitLabel`, `labels`, `icons` | — | "Activate" | the button, every string (`title`, `description`, `activate`, `cancel`, `sessionsNotice`, and those of `VerificationCode`), the locked alert's icon |
+
+There is no recovery-code switch: no recovery code exists yet. The card reads
+the lock of the nearest `VerificationLockProvider` (or the document's), so a
+lock set by another code form disables its field and leaves Cancel usable.
+
+**In a test**, find the field by `getByRole('textbox', { name: 'Code' })`, the
+button by `getByRole('button', { name: 'Activate' })` and the lock by
+`getByRole('alert')`.
+
+**Storybook:** `Data display/EnrolmentCard`, `…/Shared lock`, `Guides/Accessibility/Touch targets/Verification code` · **Vue:** not yet
+
+---
+
 ## EnrolmentSecret
 
 ![EnrolmentSecret](../previews/data-display-enrolmentsecret.webp)
@@ -1477,3 +1568,41 @@ useEffect(() => {
 ```
 
 **Storybook:** `Data display/RecoveryCodes` · **Vue:** `RecoveryCodes` (`v-model:saved`, `@done`, `@copy`; slots `title`, `description`, `warning`, `copy-icon`, `download-icon`, `print-icon`)
+
+---
+
+## RecoveryCodesStatus
+
+![RecoveryCodesStatus](../previews/data-display-recoverycodesstatus.webp)
+
+Where an account stands on its recovery codes: how many are left, a warning when none is, and the way to make a new set. It is **driven by props**; show the new codes with [RecoveryCodes](#recoverycodes) once `onRegenerate` succeeds.
+
+```tsx
+import { RecoveryCodesStatus, VerificationLockProvider } from '@nxgt/material/components';
+
+<VerificationLockProvider>
+  <RecoveryCodesStatus
+    remaining={account.recoveryCodesLeft}
+    onRegenerate={(code, options) => regenerate(code, options?.kind)}
+    error={answer.error}
+    attemptsLeft={answer.attemptsLeft}
+    locked={answer.locked}
+    pending={regenerating}
+  />
+</VerificationLockProvider>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `remaining` | `number \| null` | — | the count, an ICU plural ("6 recovery codes left"); `0` turns it red and adds a warning; `null` or left out shows no count |
+| `onRegenerate` | `(code?, { kind }?) => unknown` | — | with `requireCode`, called with the code and its kind (`'code'` or `'recovery'`); without it, called with no argument |
+| `requireCode` | `boolean` | `true` | `true`: a `VerificationCode` whose button is "New codes"; `false`: a plain button |
+| `allowRecovery` | `boolean` | `true` | offers "Use a recovery code" in the form |
+| `length` | `number` | `6` | the slots in the code field, as `VerificationCode` |
+| `attemptsLeft`, `locked`, `error`, `pending` | as `VerificationCode` | — | the answer to the last code; the same locked state. `error="throttled"` shows the general wait line only (no Resend, no `retryAfter` here) |
+| `title`, `titleAs`, `description` | `ReactNode`, `'h2'…`, `ReactNode \| false` | built-in, `'h2'` | the heading ("Recovery codes"), its level, the line under it |
+| `labels`, `icons` | partial objects | built-in | `title`, `description`, `remaining` (`(count) => string`), `noneLeft`, `noneLeftHint`, `newCodes`, `newCodesHint`, and those of `VerificationCode` |
+
+It reads the page-wide lock like [EnrolmentCard](#enrolmentcard) does. With `requireCode={false}` there is no code form, so `error` and `attemptsLeft` are not shown: the plain button follows `pending`, and is disabled by `locked` and by the page-wide lock; then the lock's text (the message of the answer that locked, or "Too many wrong codes. Try again later.") shows above it as a muted line that describes the button.
+
+**Storybook:** `Data display/RecoveryCodesStatus`, `Data display/EnrolmentCard/Shared lock` · **Vue:** not yet

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

@@ -11,6 +11,7 @@ centre.
 | <img src="../previews/feedback-status-alertdialog.webp" width="96" alt=""> | [AlertDialog](#alertdialog) | Parts for a blocking confirmation dialog |
 | <img src="../previews/feedback-status-confirmdialog.webp" width="96" alt=""> | [ConfirmDialog](#confirmdialog) | Confirm / cancel dialog, `ConfirmationDialog`, `CustomAlertDialog` |
 | <img src="../previews/feedback-status-customdialog.webp" width="96" alt=""> | [CustomDialog](#customdialog) | Ready-made dialog with trigger, icon, title, body and footer |
+| <img src="../previews/feedback-status-stepupdialog.webp" width="96" alt=""> | [StepUpDialog](#stepupdialog) | "Confirm it's you": a dialog that asks for a one-time code, driven by props |
 | <img src="../previews/feedback-status-emptystate.webp" width="96" alt=""> | [EmptyState](#emptystate) | Illustration, title, description and action, by kind (empty, search, not-found, unauthorized) |
 | <img src="../previews/feedback-status-errorstate.webp" width="96" alt=""> | [ErrorState](#errorstate) | Failure block with Retry and technical details |
 | <img src="../previews/feedback-status-progress.webp" width="96" alt=""> | [Progress](#progress) | Material 3 Expressive linear bar, circular ring and labelled progress field, flat or wavy |
@@ -56,9 +57,25 @@ keep the old look.
 | `icon` | `ReactNode` | the tone's icon | shown before the text; `null` (or `false`) shows none, any node replaces the tone's icon |
 | `title` | `ReactNode` | — | bold first line |
 | `description` | `ReactNode` | — | muted body text |
+| `actions` | `ReactNode` | — | buttons or links under the text, wrapping on a narrow screen (`data-slot="alert-actions"`); a `Button` or `LinkButton` keeps its 44 px target on a coarse pointer |
 
 The root carries `data-slot="alert"`, the title `data-slot="alert-title"` and the description `data-slot="alert-description"`, for tests and selectors.
 
+**Actions.** Give an Alert a way out with `actions`, such as a link to the next step:
+
+```tsx
+<Alert
+  variant="warning"
+  title="A second step is required"
+  description="Turn on two-step sign-in to continue."
+  actions={
+    <Button asChild size="sm">
+      <a href="/settings/security">Continue</a>
+    </Button>
+  }
+/>
+```
+
 **In a form grid.** Inside `.form-grid-layout`'s `[data-slot="form-fields"]` or a [FormSection](form-fields.md#formsection)'s fields, an `Alert` or a `Banner` placed directly in the grid takes the whole row (`col-span-full w-full`) without any class from you; a utility class of your own on it still wins.
 
 ```tsx
@@ -71,7 +88,7 @@ The root carries `data-slot="alert"`, the title `data-slot="alert-title"` and th
 </form>
 ```
 
-**Storybook:** `Feedback & status/Alert/Tone icon` (`ToneIcon`), `Feedback & status/Alert/In a form grid` (`InFormGrid`) · **Vue:** `Alert` (the default icon and the form-grid row are React only for now)
+**Storybook:** `Feedback & status/Alert/Tone icon` (`ToneIcon`), `Feedback & status/Alert/In a form grid` (`InFormGrid`), `Feedback & status/Alert` (`WithActions`) · **Vue:** `Alert` (the default icon and the form-grid row are React only for now)
 
 ---
 
@@ -336,6 +353,101 @@ import { Atom } from 'lucide-react';
 
 ---
 
+## StepUpDialog
+
+![StepUpDialog](../previews/feedback-status-stepupdialog.webp)
+
+"Confirm it's you": a dialog that asks for a one-time code before the app goes
+on with a sensitive action. It is **presentational and props-driven**, built on
+`Dialog` and `VerificationCode`: it holds no state machine and fetches nothing,
+so you wire the model of your own (a session, a store, a loader) to its props.
+
+```tsx
+import { StepUpDialog, VerificationLockProvider } from '@nxgt/material/components';
+
+type Step = {
+	open: boolean;
+	via?: 'email' | 'secondFactor';
+	address?: string;
+	requestError?: string;
+	attemptsLeft?: number;
+	error?: 'invalid' | 'expired' | 'failed' | 'throttled';
+	retryAfter?: number;
+	pending: boolean;
+	resent: boolean;
+	accepted: boolean;
+};
+
+export function ConfirmItsYou({
+	step,
+	close,
+	check,
+	sendAgain,
+}: {
+	step: Step;
+	close: () => void;
+	check: (code: string, kind: 'code' | 'recovery') => Promise<void>;
+	sendAgain: () => Promise<void>;
+}) {
+	return (
+		<VerificationLockProvider>
+			<StepUpDialog
+				open={step.open}
+				onCancel={close}
+				via={step.via} // left out while the code is being requested
+				destination={step.address}
+				requestError={step.requestError}
+				attemptsLeft={step.attemptsLeft}
+				error={step.error}
+				retryAfter={step.retryAfter}
+				pending={step.pending}
+				onSubmit={(code, { kind }) => check(code, kind)}
+				onResend={sendAgain}
+				resent={step.resent}
+				confirming={step.accepted}
+			/>
+		</VerificationLockProvider>
+	);
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `open`, `onCancel` | `boolean`, `() => void` | — | Escape, a click outside and Cancel call `onCancel`, except while `confirming`; you close the dialog |
+| `cancelVariant` | `ButtonVariant` | `'tonal'` | the Cancel button's variant; `'outlined'` or `'ghost'` restores an earlier look |
+| `via` | `'email' \| 'secondFactor'` | — | how the code was issued; left out, the code is still being requested: no field, a status line. Changing it starts the form again (typed value, recovery switch) |
+| `destination` | `ReactNode` | — | where an e-mailed code went; named in the description |
+| `requestError` | `ReactNode` | — | the request for a code failed: an alert in place of the field |
+| `attemptsLeft`, `locked`, `error`, `retryAfter`, `pending` | as `VerificationCode` | — | the answer to the last code (`error="throttled"` with `retryAfter` seconds disables "Resend the code" for that long and never locks; the footer is unchanged). No tries left: an e-mailed code reads "expired, ask for a new code"; an app or recovery code shows the locked alert and writes the page-wide lock |
+| `length`, `allowRecovery` | `number`, `boolean` | `6`, per `via` | the slots in the code field, and "Use a recovery code" (on for `via="secondFactor"`), passed to the `VerificationCode` |
+| `onSubmit`, `onResend`, `resent` | as `VerificationCode` | — | your calls; "Resend the code" sits alone on its own line |
+| `confirming`, `confirmedLabel` | `boolean`, `ReactNode` | — | the code was accepted and you re-run the action: the field goes, a status line shows, Cancel is disabled and Escape does nothing until you close it |
+| `title`, `description` | `ReactNode` | built-in | the title ("Confirm it's you") and the line under it, which follows `via` |
+| `labels`, `icons` | partial objects | built-in | every string of the dialog (`title`, `description`, `descriptionApp`, `descriptionEmail`, `descriptionEmailTo`, `requesting`, `cancel`, `confirmed`) and of `VerificationCode` (`incomplete`, `incompleteRecovery` among them) |
+
+Confirm is a footer button that submits the form. Pressed with too few digits
+(or an empty recovery code) it focuses the field and says "Enter all 6 digits."
+instead of calling `onSubmit`.
+
+**Focus.** The title takes the focus on open and whenever the field goes away
+(a code being requested, a code accepted); the field takes it after a refusal;
+on close it goes back to the button that opened the dialog. A locked code
+leaves Cancel usable.
+
+**On a phone** the footer stays one row, Cancel on the left and Confirm on the
+right: `DialogFooter` takes `stackOnPhone={false}` (`true` by default, the
+buttons stacked full width). Every control keeps a 44 px target on a coarse
+pointer.
+
+**In a test**, find the field by `getByRole('textbox', { name: 'Code' })`, the
+dialog by `getByRole('dialog', { name: "Confirm it's you" })` and the lock by
+`getByRole('alert')`.
+
+**Storybook:** `Feedback & status/StepUpDialog`, `…/Locks`, `…/Throttled`, `…/Layout`, `Guides/Accessibility/Touch targets/Step-up dialog` ·
+**Vue:** not yet
+
+---
+
 ## EmptyState
 
 ![EmptyState](../previews/feedback-status-emptystate.webp)

package/docs/components/form-fields.md

@@ -24,6 +24,7 @@ for the value type each one writes. Everything is imported from
 | <img src="../previews/form-fields-searchfield.webp" width="96" alt=""> | [SearchField](#searchfield) | Clear button, spinner, debounced value |
 | <img src="../previews/form-fields-colorfield.webp" width="96" alt=""> | [ColorField](#colorfield) | Hex input with a picker |
 | <img src="../previews/form-fields-otpfield.webp" width="96" alt=""> | [OtpField](#otpfield) | One-time code input |
+| <img src="../previews/form-fields-verificationcode.webp" width="96" alt=""> | [VerificationCode](#verificationcode) | The form that checks a one-time code, with a page-wide lock |
 | <img src="../previews/form-fields-inputgroupfield.webp" width="96" alt=""> | [InputGroupField](#inputgroupfield) | Labelled `InputGroup` with addons |
 | <img src="../previews/form-fields-localizedtextfields.webp" width="96" alt=""> | [LocalizedTextFields](#localizedtextfields) | One text in several languages, with defaults and a reset |
 | <img src="../previews/form-fields-inlineedit.webp" width="96" alt=""> | [InlineEdit](#inlineedit) | Click-to-edit text |
@@ -742,6 +743,168 @@ carries `data-invalid`, not `aria-invalid`.
 
 ---
 
+## VerificationCode
+
+![VerificationCode](../previews/form-fields-verificationcode.webp)
+
+A `<form>` that asks for a one-time code, **presentational and controlled**: it
+keeps the typed value, the app or recovery switch, the focus and the submit
+guard, and shows the answer you give it. It fetches nothing and holds no state
+machine; your state (a session, a store, a loader) says what happened, and
+`onSubmit` and `onResend` are yours. Every string is a label.
+
+The slots are tinted boxes inside a hairline ring that holds 3:1 against the
+card in light and dark, with a dot while empty, a dash between the halves, 20px
+semibold tabular digits, and a soft caret and a 2px primary ring on the active
+one (the caret stands still under `prefers-reduced-motion`). A wrong code tints
+the slots and digits and shows its message with an icon; a full code is tinted with
+the primary colour (the slots pop in once, only where motion is welcome); a locked form is
+muted, with a "Locked" pill in the label row (`labels.lockedBadge`) and the lock
+message under the slots. The recovery code's input shares the same fill and ring.
+
+```tsx
+import { VerificationCode, VerificationLockProvider } from '@nxgt/material/components';
+
+export function SecondStep({ answer, pending, send }: Props) {
+	return (
+		<VerificationLockProvider>
+			<VerificationCode
+				via="secondFactor"
+				attemptsLeft={answer?.attemptsLeft}
+				error={answer?.error}
+				pending={pending}
+				onSubmit={(code, { kind }) => send(code, kind)}
+			/>
+		</VerificationLockProvider>
+	);
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `via` | `'email' \| 'secondFactor'` | — | how the code was issued: sent to the person, or from an authenticator app |
+| `attemptsLeft` | `number` | — | the tries left, said under a wrong code; at `0` see below |
+| `error` | `'invalid' \| 'expired' \| 'failed' \| 'throttled' \| ReactNode` | — | the last refusal; a node is shown as a wrong code's message. `'throttled'` is not a refusal of the code: see below. Leave it out when a new code is typed or accepted |
+| `retryAfter` | `number` | — | with `error="throttled"`, the seconds to wait before asking for a new code |
+| `locked` | `boolean` | — | locks this form, and the page-wide lock, for an app or recovery code; ignored for an e-mailed code, which is never locked unless a recovery code is typed in its form |
+| `pending` | `boolean` | — | a request is in flight: field disabled, Confirm busy, a second press dropped |
+| `onSubmit` | `(code, { kind: 'code' \| 'recovery' }) => unknown` | — | the code as typed (a recovery code is trimmed and cut at 40) and what it is (`'code'` is the issued code, from an app or an e-mail). Return a promise to hold a second submit |
+| `onResend`, `resent` | `() => unknown`, `boolean` | — | "Resend the code" alone on its own line (an e-mailed code), "New code" / "Try again" once a code expired; `resent` says a new code was sent |
+| `allowRecovery` | `boolean` | `via === 'secondFactor'` | "Use a recovery code", which swaps the field for a text field and back |
+| `length` | `number` | `6` | slots in the code field |
+| `id` | `string` | generated | the form's id; the buttons of `actions="none"` point at it with `form={id}`. Other `<form>` props pass through |
+| `actions` | `'inline' \| 'none'` | `'inline'` | `'none'` leaves the buttons to you; point them at the form with `form={id}` |
+| `submitLabel`, `secondaryAction` | `ReactNode` | "Confirm" | the button, and what sits beside it (Cancel), which stays usable when locked |
+| `destructive` | `boolean` | — | the button is red (turning protection off) |
+| `status` | `ReactNode` | — | a notice line over the field |
+| `labels`, `icons` | partial objects | built-in | every string (`triesLeft`, `incomplete`, `throttledMinutes` and `throttledSeconds` are `(count) => string`; `incompleteRecovery` is the empty recovery code's message); the locked alert's icon |
+
+Submitting too few digits (the inline Confirm, which stays enabled until the
+form is locked, Enter, or a Confirm button of your own pointed at the form)
+does not call `onSubmit`: it focuses the field and says "Enter all 6 digits."
+(an empty recovery code, "Enter your recovery code."), announced once.
+
+A wrong code empties the field and focuses it once your answer arrives, and
+says "Wrong code." with the tries left (an ICU plural). `expired` and `failed`
+say their message. One polite live region announces what the focus does not
+read: "A new code was sent.", and a refusal you set without a submit. A refusal
+that follows a submit sends the focus to the field, which is described by the
+message, so the live region leaves it out rather than say it twice. A rejected
+`onSubmit` is swallowed: map the failure to `error="failed"`.
+
+**Throttled.** `error="throttled"` says too many new codes were asked for.
+It is not a refusal of the code: the field stays usable, nothing locks (for an
+app or recovery code, `locked` or `attemptsLeft: 0` still does and overrides
+it; an e-mailed code never locks), no try is counted, and an entry switch does
+not clear it. It speaks before "expired": an e-mailed code with no tries left
+that is throttled when "New code" is pressed says the wait, not "This code has
+expired.", and the button keeps the "New code" label. The line stays until you
+clear `error` (the end of the wait only re-enables Resend). With `retryAfter` (seconds) the line reads "Wait 2
+min before asking for a new code." (minutes rounded up, "Wait 45 s…" under a
+minute; on an authenticator or recovery code, `via="secondFactor"`, "Wait 2 min
+before trying again.") and "Resend the code" is disabled, described by that line, until the
+wait elapsed, counted from when the answer arrived: one timer, no countdown,
+so the text does not tick. A new `retryAfter` starts the clock again, and so does a
+resend that settles while `error` is still `"throttled"`, even with the same
+`retryAfter`. Resend
+is disabled once the client has hydrated, not in the server HTML. Without `retryAfter` the line is general ("Too many
+requests. Wait a moment and try again.") and Resend stays on. `EnrolmentCard` and `RecoveryCodesStatus` take `error="throttled"` too, with no Resend and no
+`retryAfter`: they show that general line only.
+It is announced once by the polite live region; when it answers a press of
+Resend, the focus goes to the field (the pressed button is now disabled), which
+is described by the line, and the live region leaves it out. The words are
+`labels.throttled`, `throttledMinutes(n)` and `throttledSeconds(n)` (`throttledMinutesApp(n)` and `throttledSecondsApp(n)` for `via="secondFactor"`). On the
+server nothing waits and no timer runs.
+
+**With no tries left** (`attemptsLeft === 0`) the form reads the answer by what
+the code was: an e-mailed code shows "expired, ask for a new code" (nothing is
+held against it), and an app or recovery code shows the locked alert, because
+that lock belongs to the account, so it also writes the page-wide lock below.
+What is typed decides what is held: an e-mailed form in recovery mode is held
+like an app's. Switching the entry clears the held decision of the answer you
+gave for the other kind of code: a stale `attemptsLeft: 0` for the e-mailed
+code does not lock the recovery field, only a refused recovery code does, and
+a lock already written stays written. The stale answer is released once a
+changed answer arrives, or a submit made since the switch ends with `pending`
+down, so raise `pending` in the same tick as your `onSubmit` (or return its
+promise); an `error` node rebuilt on each render reads as a changed answer. The locked message disables the field and Confirm and describes
+them (`aria-describedby`); it takes the focus after a submit that locked it.
+One lock is one alert: only the first form to show it has `role="alert"`, and
+the other forms under the same lock show the same words as a plain element.
+With no provider every form whose own answer locked it is an alert (the server
+and the hydrated page must agree), and the forms the document lock holds are
+plain elements.
+
+**Wiring your state.** Map the answer your session or API gives to the props;
+nothing else is needed:
+
+```tsx
+type Answer = {
+	via: 'email' | 'secondFactor';
+	attemptsLeft?: number;
+	error?: 'invalid' | 'expired' | 'failed' | 'throttled';
+	retryAfter?: number; // seconds, with 'throttled'
+};
+
+function CodeStep({ answer, pending, send, sendAgain }: StepProps<Answer>) {
+	return (
+		<VerificationCode
+			via={answer.via}
+			attemptsLeft={answer.attemptsLeft}
+			error={answer.error}
+			retryAfter={answer.retryAfter}
+			pending={pending}
+			onSubmit={(code, { kind }) => send({ code, recovery: kind === 'recovery' })}
+			onResend={answer.via === 'email' ? sendAgain : undefined}
+		/>
+	);
+}
+```
+
+**The lock.** An app or recovery code that is `locked`, or has no tries left,
+writes a page-wide lock: every app or recovery field under the same
+`VerificationLockProvider` stays locked until the page is loaded again, whether
+it remounts, the step changes or a dialog closes. Without a provider the lock
+covers the whole document. A code sent by e-mail is never held by it, unless a recovery code is typed in its form.
+`useVerificationLock()` returns `{ locked, message, lock(message?) }` for the
+rest of your app; on the server it is always unlocked, so hydration cannot
+mismatch. `createVerificationLock` and `normalizeRecoveryCode` are in
+`@nxgt/material-core/two-factor`.
+
+For a layout of your own use `useVerificationLabels`.
+
+**On a phone** the buttons stay on one row, the slots shrink to fit 320 px, and
+every control keeps a 44 px target on a coarse pointer.
+
+**In a test**, find the field by `getByRole('textbox', { name: 'Code' })`, the
+refusal as the field's accessible description (`toHaveAccessibleDescription`; the `status` region carries only what the focus does not read: after a click on Confirm it stays empty), and the lock by `getByRole('alert')` (one per lock).
+
+**Storybook:** `Form fields/VerificationCode`, `…/States`, `…/Lock`, `…/Lock scope`, `…/Answers`, `…/Failures`, `…/Recovery switch`, `…/Throttled`, `…/Throttled expired`, `…/Entry switch`, `…/Layout`, `…/Refined`, `…/Refined checks`,
+`Navigation & layout/AuthCard/Second factor` · **Vue:** not yet (the framework-free
+part is `@nxgt/material-core/two-factor`)
+
+---
+
 ## InputGroupField
 
 ![InputGroupField](../previews/form-fields-inputgroupfield.webp)

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

@@ -21,7 +21,7 @@ documentation-site shell. Everything is imported from
 | <img src="../previews/navigation-layout-pager.webp" width="96" alt=""> | [Pager](#pager) | Previous / next cards |
 | <img src="../previews/navigation-layout-seealso.webp" width="96" alt=""> | [SeeAlso](#seealso) | Related links |
 | <img src="../previews/navigation-layout-toc.webp" width="96" alt=""> | [Toc](#toc) | On-this-page outline |
-| <img src="../previews/navigation-layout-stepper.webp" width="96" alt=""> | [Stepper](#stepper) | Clickable steps with progress |
+| <img src="../previews/navigation-layout-stepper.webp" width="96" alt=""> | [Stepper](#stepper) | Clickable steps with progress: shaped indicators, optional steps, a phone header |
 | <img src="../previews/navigation-layout-steps.webp" width="96" alt=""> | [Steps](#steps) | Numbered editorial steps |
 | <img src="../previews/navigation-layout-hero.webp" width="96" alt=""> | [Hero](#hero) | Landing band |
 | <img src="../previews/navigation-layout-doc.webp" width="96" alt=""> | [Doc](#doc) | Documentation site shell |
@@ -657,23 +657,41 @@ const items: TocItem[] = [
 
 ![Stepper](../previews/navigation-layout-stepper.webp)
 
-Clickable horizontal or vertical steps with status and progress; compact on mobile.
+Clickable horizontal or vertical steps with status and progress. The look is
+expressive: the current step is a cookie, a completed one a filled circle with
+a check, an upcoming one a muted outlined circle and a failed one a cookie in
+the error container, joined by thick pill tracks that fill with the spatial
+spring (no motion under `prefers-reduced-motion`). Below `sm` a header card
+replaces the steps.
 
 ```tsx
 import { CreditCard, Truck, User } from 'lucide-react';
-import { Stepper, TooltipProvider } from '@nxgt/material/components';
+import { Stepper } from '@nxgt/material/components';
+
+<Stepper
+  active={active}
+  onChange={setActive}
+  steps={[
+    { icon: <User />, title: 'Account', description: 'Your profile details.' },
+    { icon: <Truck />, title: 'Shipping', status: 'completed' },
+    { icon: <CreditCard />, title: 'Payment' },
+  ]}
+/>
+```
 
-<TooltipProvider>
-  <Stepper
-    active={active}
-    onChange={setActive}
-    steps={[
-      { icon: <User />, title: 'Account', description: 'Your profile details.' },
-      { icon: <Truck />, title: 'Shipping', status: 'completed' },
-      { icon: <CreditCard />, title: 'Payment' },
-    ]}
-  />
-</TooltipProvider>
+An optional step with a card under it, and Back / Next in the phone header
+(they call `onChange(active ± 1)`):
+
+```tsx
+<Stepper
+  active={active}
+  onChange={setActive}
+  steps={[
+    { title: 'Account' },
+    { title: 'Address', optional: true, content: <p>Skip this if you pick up in store.</p> },
+    { title: 'Payment' },
+  ]}
+/>
 ```
 
 Parts: `Stepper`, `StepperIndicator` (the progress bar alone: `current`,
@@ -681,10 +699,10 @@ Parts: `Stepper`, `StepperIndicator` (the progress bar alone: `current`,
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `steps` | `{ icon?; title; description?; status? }[]` | — | `status`: `'completed' \| 'error' \| 'upcoming'`, else derived from `active` |
-| `active` | `number` | `0` | current step; its `description` shows under the bar |
+| `steps` | `{ icon?; title; description?; status?; optional?; content? }[]` | — | `status`: `'completed' \| 'error' \| 'upcoming'`, else derived from `active`. `optional` adds "· Optional" to the label; `content` is a tinted card shown under the current step |
+| `active` | `number` | `0` | current step; its `description` shows under the steps (in the header card on a phone) |
 | `onChange` | `(index: number) => void` | — | makes steps clickable |
-| `orientation` | `'horizontal' \| 'vertical' \| 'responsive'` | `'horizontal'` | `'vertical'`: a column from `md`, phones get the compact bar. `'responsive'`: every step in a column below `sm` (640px), a row from `sm` |
+| `orientation` | `'horizontal' \| 'vertical' \| 'responsive'` | `'horizontal'` | `'vertical'`: a column from `sm` (640px), phones get the header card. `'responsive'`: every step in a column below `sm` (640px), a row from `sm` |
 | `renderStepLabel` | `(step, index) => ReactNode` | — | replaces the "Step n" caption |
 | `name` | `string` | — | the stepper's `data-pw` (`stepper` without it), and the prefix of each step's: `<name>-step-N` instead of `step-N` |
 
@@ -692,12 +710,37 @@ Each step is an `<li>` with `data-pw="step-N"` (`<name>-step-N` with `name`),
 N counted from 0, for tests to select; the current step's button carries
 `aria-current="step"`, and a completed or failed step is announced as such.
 
-A server renders the desktop layout (every step), as does a hydrating client;
-a phone switches to the compact bar right after hydrating (with
-`orientation="responsive"`, to the column of every step). A page rendered
-only in the browser starts on the real layout.
-
-**Storybook:** `Navigation & layout/Stepper` · **Vue:** `Stepper`
+Below `sm` a header card shows "Step 3 of 5", the title, the description and a
+segmented progress bar (one segment per step, toned by state); with `onChange`
+it also has Back and Next buttons, which stay focusable but inactive (`aria-disabled`) at the ends. Titles clamp to two
+lines. The info tooltip on the current step is gone: read the description
+under the steps.
+
+**Server rendering.** The layout is chosen by CSS breakpoints, not by the
+screen width in JavaScript, so the server and the client render the same
+markup and nothing switches after hydration. Both layouts are in the markup
+and the unused one is hidden; ids stay unique.
+
+**Accessibility.** The steps are a list, the current step's button carries
+`aria-current="step"`, a completed or failed step is announced as such, and
+steps are focusable when `onChange` is given. The header's progress bar is
+decorative: the "Step n of N" text carries the meaning. The live header
+announces a failed current step and the number of failed steps; Back and Next
+use `aria-disabled` and stay focusable at the ends.
+
+**Migrating.** The new look is the default and the props are unchanged;
+`optional` and `content` are additive. Update any test that selected the old
+info button on the current step. New `material.stepper.*` keys: `step-of`,
+`back`, `next`, `optional`, `attention`, `failed`. The `attention` text ("Needs attention") is shown under the title of a failed step, as a visual cue only: the announced status stays "Error".
+
+Migration notes:
+
+- `data-orientation` now repeats the `orientation` prop; a `responsive` Stepper no longer reports `vertical` or `horizontal` by width.
+- Below 640px the horizontal step list is hidden and the header card replaces it.
+- `horizontal` and `vertical` switch at `sm` (640px), not `md` (768px).
+- `Stepper` no longer renders `StepperIndicator` (still exported).
+
+**Storybook:** `Navigation & layout/Stepper` · **Vue:** `Stepper`, with the earlier look: the redesign, `optional` and `content` are React only for now (#1810)
 
 ---
 

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

@@ -139,7 +139,9 @@ utilities: a class you pass wins. The flat look of 2.x before it is
 `className="rounded-lg border bg-background shadow-lg"` on `DialogContent`
 (and `className="bg-black/50"` on a `DialogOverlay` of your own).
 `DialogFooter` stacks its actions full width on a phone, the main one at the
-bottom. With `prefers-reduced-motion`, nothing moves: it appears and goes.
+bottom. `stackOnPhone={false}` keeps one row instead, the first
+action on the left and the last on the right, for two short actions such as
+Cancel and Confirm. With `prefers-reduced-motion`, nothing moves: it appears and goes.
 
 `DialogContent` and `AlertDialogContent` are capped at `100dvh - 2rem` (`100vh`
 where `dvh` is unsupported) and scroll inside themselves, so a long body never