@nxgt/material 3.45.0 → 3.46.0

package/docs/components/data-display.md

@@ -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
 
@@ -1375,6 +1377,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 +1529,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/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

package/docs/guides/two-factor.md

@@ -0,0 +1,78 @@
+# Two-step verification
+
+A one-time code is asked for at five moments of an account's life: signing in,
+confirming a sensitive action ("step-up"), turning an authenticator app on,
+making new recovery codes and turning it off. The components below draw all of
+them. They are **driven by props**: your server, session or store says what
+happened (`attemptsLeft`, `error`, `locked`, `pending`), and the components
+keep only the typed value, the focus and the submit guard. Nothing is fetched
+inside them.
+
+| Moment | Component | Page |
+| --- | --- | --- |
+| The code field and its states (wrong, expired, busy, locked, resent) | `VerificationCode` | [Form fields](../components/form-fields.md#verificationcode) |
+| Sign-in's second step | `AuthCard` holding a `VerificationCode` | [Navigation and layout](../components/navigation-and-layout.md#authcard) |
+| "Confirm it's you" before a sensitive action | `StepUpDialog` | [Feedback and status](../components/feedback-and-status.md#stepupdialog) |
+| Turning an authenticator app on | `EnrolmentCard` (over `EnrolmentSecret`) | [Data display](../components/data-display.md#enrolmentcard) |
+| Recovery codes: how many are left, a new set | `RecoveryCodesStatus`, then `RecoveryCodes` | [Data display](../components/data-display.md#recoverycodesstatus) |
+| A notice with a way out ("Continue", "Retry") | `Alert` with `actions` | [Feedback and status](../components/feedback-and-status.md#alert) |
+| The page-wide lock | `VerificationLockProvider`, `useVerificationLock` | [Form fields](../components/form-fields.md#verificationcode) |
+
+## Wire it once
+
+Put one `VerificationLockProvider` around the screens that ask for a code. An
+authenticator or recovery code that is `locked`, or has `attemptsLeft: 0`,
+locks every such field under the provider until the page is loaded again: a
+remount, a step change or closing the dialog does not lift it. An e-mailed
+code is never held by it. Without a provider the lock covers the document.
+
+Then map your answer to props, in one place:
+
+```tsx
+import { VerificationCode } from '@nxgt/material/components';
+
+<VerificationCode
+	via="secondFactor" // or 'email'
+	attemptsLeft={answer?.attemptsLeft}
+	error={answer?.error} // 'invalid' | 'expired' | 'failed' | 'throttled' | a node
+	retryAfter={answer?.retryAfter} // seconds, with 'throttled'
+	locked={answer?.locked}
+	pending={pending}
+	onSubmit={(code, { kind }) => send(code, kind)} // 'code' | 'recovery'
+	onResend={via === 'email' ? sendAgain : undefined}
+/>;
+```
+
+The framework-free part (`createVerificationLock`, `normalizeRecoveryCode`) is
+in `@nxgt/material-core/two-factor`.
+
+## Replacing what an app wrote itself
+
+| An app's own | Replace with | Notes |
+| --- | --- | --- |
+| A "confirm it's you" dialog with a state machine (asking, failed, code, expired, confirmed) | `StepUpDialog` | Keep your state; map it to `via`, `requestError`, `error`, `attemptsLeft`, `pending`, `confirming`. Leave `via` out while the code is requested. The replay of the blocked action stays yours |
+| A code input with a "use a recovery code" switch, in a sign-in step, an activation or a turn-off | `VerificationCode` (`allowRecovery` by default for `via="secondFactor"`; `destructive` for turning off) | The recovery code is trimmed and cut at 40; `kind` tells you which it is |
+| A card with the QR code, the key, a sessions note and a first code | `EnrolmentCard` | `sessionsNotice` is a default, your wording or `false`; `status` is a line over the field |
+| A card with the codes left and a "new codes" action | `RecoveryCodesStatus`, then the existing `RecoveryCodes` for the new set | `remaining` is `null` when not known; `requireCode={false}` is a plain button |
+| A "this is required" notice with a link | `Alert` with `actions` (a `LinkButton`) | The wording stays yours |
+| A "3 tries left" or "locked" message the app kept in its own state | `attemptsLeft` and `locked` | A wrong code empties and focuses the field; no tries left locks an app code and expires an e-mailed one |
+| A hand-made lock that survives a remount or a closed dialog | `VerificationLockProvider` | `useVerificationLock()` reads it from the rest of the app |
+| Cancel buttons drawn `outlined` or `ghost` | nothing: they are tonal | `cancelVariant` on `StepUpDialog` and `EnrolmentCard` restores another look |
+
+What stays in the app: every request, the mapping of a server error to the
+props above, where the challenge is kept, the replay of the action a step-up
+unblocked, the leave guard around the new recovery codes, and all wording
+(`labels`, or your translations under `material.*`).
+
+## On a phone and for assistive technology
+
+Every control has a 44 px target on a coarse pointer, the slots shrink to fit
+320 px, and the dialog's footer stays one row (`DialogFooter`'s
+`stackOnPhone={false}`). A refusal after a submit is the field's accessible description (the focus goes
+there); one polite live region announces what the focus does not read, such
+as a new code; the lock is a `role="alert"` that takes the focus when the
+form's own answer locked it, and describes the disabled field. The code field
+is `autocomplete="one-time-code"`. In a test, find it with
+`getByRole('textbox', { name: 'Code' })`.
+
+React only for now; the Vue twin is a `vue` issue.

package/docs/roadmap.md

@@ -330,6 +330,22 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **Two-step verification** — the pieces every app rebuilt for a one-time
+  code. `VerificationCode` is the form (app or e-mailed code, "Use a recovery
+  code", resend, wrong with the tries left, expired, busy, locked, throttled
+  with `retryAfter`: Resend waits, and waits again if it is answered throttled
+  again), and
+  `VerificationLockProvider` keeps a locked app code locked page-wide.
+  `StepUpDialog` is "Confirm it's you"; `EnrolmentCard` turns an authenticator
+  app on; `RecoveryCodesStatus` shows the codes left and makes a new set.
+  `Alert` takes `actions` and `DialogFooter` `stackOnPhone`; the new Cancel
+  buttons are tonal and take `cancelVariant`. The framework-free part is in
+  `@nxgt/material-core/two-factor`. React only for now; the Vue port is a
+  `vue` issue.
+  [Two-step verification guide](guides/two-factor.md) ·
+  [VerificationCode](components/form-fields.md#verificationcode) ·
+  [StepUpDialog](components/feedback-and-status.md#stepupdialog) ·
+  [EnrolmentCard](components/data-display.md#enrolmentcard)
 - **One filter model: defaults, a scope, a refusal, `FilterBar`** — a filter
   field says what an absent value means and what role it plays, so a list can
   start narrowed and a page can keep a value the user never clears.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "3.45.0",
+	"version": "3.46.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -362,7 +362,7 @@
 		"docs:previews": "rm -rf node_modules/.cache/nxgt-preview-free/missing && NXGT_PREVIEW_FREE=1 vitest run --project previews && bun .storybook/preview-free-report.ts"
 	},
 	"dependencies": {
-		"@nxgt/material-core": "^0.40.0",
+		"@nxgt/material-core": "^0.41.0",
 		"@base-ui/react": "^1.6.0",
 		"@dnd-kit/core": "^6.3.1",
 		"@dnd-kit/sortable": "^10.0.0",