@nxgt/material 3.45.0 → 3.47.0

package/docs/guides/i18n.md

@@ -334,7 +334,10 @@ names of its −/+ buttons, "Increase hours" / "Decrease hours" /
 "Increase minutes" / "Decrease minutes"
 (`material['duration-field']['increase-hours']` and the three others); the status a
 `Stepper` step announces after its title, "Completed" or "Error"
-(`material.stepper.completed` / `error`, "Terminée" / "Erreur" in French); and
+(`material.stepper.completed` / `error`, "Terminée" / "Erreur" in French); the
+Stepper's phone header (`material.stepper.step-of`, `back`, `next`, `optional`,
+`attention`, `failed`) and the Timeline's day-heading count (`material.timeline.events`; its
+"Today" and "Yesterday" are `DaySeparator`'s); and
 the pagination buttons' names and text: `PaginationPrevious` /
 `PaginationNext`'s "Previous" / "Next" (`material.pagination.previous` /
 `next`), `PaginationFirst` / `PaginationLast`'s "First" / "Last"

package/docs/guides/ssr.md

@@ -167,8 +167,10 @@ State the server cannot know must be resolved the same way on both sides:
 | Language | no `localStorage`: `defaultLanguage` | Resolve it from the request and pass `initialLanguage` to `I18nProvider`. See [i18n](i18n.md#server-rendering) |
 | Theme | no preference: light | An inline boot script in `<head>`, and `suppressHydrationWarning` on `<html>`. See [theming](theming.md#no-flash-on-load-a-boot-script) |
 | `formatAmount`, `formatDate` | the server's locale and time zone, unless you pass them | Use `useFormatters({ timeZone })`, which follows the `I18nProvider` language, or pass `locale` and `timeZone` (`createFormatters` binds them). A date-only `YYYY-MM-DD` is the same everywhere. See [printing](printing.md#formatamount-and-formatdate) |
-| Screen width, `prefers-color-scheme` (`useIsMobile`, `useTheme`, `AppHeader`, `DataTable`, `TimeField`, `Stepper`, `PaneLayout`, `ListDetailsLayout`, the code blocks, …) | no screen: a desktop, light | Nothing: a hydrating client renders the same, then switches on a phone or a dark screen |
+| Screen width, `prefers-color-scheme` (`useIsMobile`, `useTheme`, `AppHeader`, `DataTable`, `TimeField`, `PaneLayout`, `ListDetailsLayout`, the code blocks, …) | no screen: a desktop, light | Nothing: a hydrating client renders the same, then switches on a phone or a dark screen |
 | An attribute's `DATETIME` / `TIME` instant (`AttributesSummary`, `AttributesEditor`), the opening hours' first day of the week | the server's time zone and Intl data differ from the browser's | Nothing: the instant is written in UTC and the week starts on the language's first day until mount, then the viewer's zone and the locale's week info take over, so hydration matches |
+| `Stepper` layout, `Timeline` sides | CSS breakpoints and a container query, no screen width in JavaScript | Nothing: server and client markup are the same |
+| `Timeline` `grouped` | the server's time zone and clock differ from the browser's | Pass `timeZone` and `now` to group on the server too; without them the day headings appear after mount (the items do not remount) |
 | Step form (`createStepFormSlice`) | no `localStorage`: step 0 | Nothing with `useSliceReducer`: a hydrating client renders step 0, then resumes. A slice in a Redux store: see [forms](forms.md#a-multi-step-form) |
 | Zod messages | no `localStorage`: English | Pass the request's language, `zodLocaleError({ language })`, where the server formats messages. See [forms](forms.md#validation-messages) |
 

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,36 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **Stepper and Timeline, expressive** — both have a new look by default, with
+  the same props. `Stepper` shows the current step as a cookie, a completed one
+  as a circle with a check and a failed one in the error container, joined by
+  thick tracks that fill with a spring; below `sm` a header card ("Step 3 of
+  5", a segmented bar, Back and Next with `onChange`) replaces the steps, and
+  the layout no longer depends on JavaScript, so the server and the client
+  match. `Step` gains `optional` and `content`. `Timeline` has shaped markers
+  by tone, cards for items with `children`, alternating sides in a wide
+  container (`layout="rail"` for one rail) and `grouped` day headings (`DaySeparator`, level
+  set with `headingLevel`), with
+  `timeZone` and `now` to group on the server. React only for now; the Vue
+  twin is a `vue` issue.
+  [Stepper](components/navigation-and-layout.md#stepper) ·
+  [Timeline](components/data-display.md#timeline)
+- **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/lib/styles.css

@@ -157,3 +157,11 @@
 	bottom: -0.1875rem;
 	transform: rotate(-45deg) scale(0.75);
 }
+
+/* A state change on a Stepper's shape: a small spring-in (no motion under
+ * prefers-reduced-motion: the catalogue's reduced-motion rule ends it). */
+@keyframes nxgt-pop {
+	from {
+		transform: scale(0.55);
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "3.45.0",
+	"version": "3.47.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",