@nxgt/material 3.54.0 → 3.56.0

package/docs/components/data-display.md

@@ -8,6 +8,8 @@ from `@nxgt/material/components`.
 | --- | --- | --- |
 | <img src="../previews/data-display-avatar.webp" width="96" alt=""> | [Avatar](#avatar) | Image with a fallback and an optional online / offline dot |
 | <img src="../previews/data-display-avatargroup.webp" width="96" alt=""> | [AvatarGroup](#avatargroup) | Overlapping avatars with a `+N` overflow |
+| <img src="../previews/data-display-seatring.webp" width="96" alt=""> | [SeatRing](#seatring) | Participants as seats around a circle or in a grid, optionally pickable |
+| <img src="../previews/data-display-secretcard.webp" width="96" alt=""> | [SecretCard](#secretcard) | A card whose secret is not rendered until it is revealed |
 | <img src="../previews/data-display-shape.webp" width="96" alt=""> | [Shape](#shape) | Material 3 Expressive's shapes as a backdrop, an icon container or a mask for a photo |
 | <img src="../previews/data-display-badge.webp" width="96" alt=""> | [Badge](#badge) | Status pill, 20 px, in seven tones, soft or outlined, with an optional decorative `icon` before the words |
 | <img src="../previews/data-display-countbadge.webp" width="96" alt=""> | [CountBadge](#countbadge) | Count in the corner of its children |
@@ -27,6 +29,7 @@ from `@nxgt/material/components`.
 | <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-votetally.webp" width="96" alt=""> | [VoteTally](#votetally) | A live ranked tally of a vote, with counts, shares and voters |
 | <img src="../previews/data-display-eventchip.webp" width="96" alt=""> | [EventChip](#eventchip) | Calendar event pill, soft, solid or outlined |
 | <img src="../previews/data-display-codeblock.webp" width="96" alt=""> | [CodeBlock](#codeblock) | Code, JSON tree and tabbed samples |
 | <img src="../previews/data-display-markdown.webp" width="96" alt=""> | [Markdown](#markdown) | GFM with math and mermaid |
@@ -127,6 +130,144 @@ array (`people.map(...)`); a single wrapper component or fragment counts as one.
 
 ---
 
+## SeatRing
+
+![SeatRing](../previews/data-display-seatring.webp)
+
+Participants as seats: around a circle when there is room, in a grid on a
+phone. A seating plan, a round-table meeting, a party-game lobby. Each seat has
+an avatar, a name, a status written in words and a badge; with `selectionMode`
+it is a listbox to pick one or several seats from.
+
+```tsx
+import { SeatRing } from '@nxgt/material/components';
+
+<SeatRing
+  aria-label="Players"
+  seats={[
+    { id: 'ada', label: 'Ada Example', status: { label: 'Ready', tone: 'success' }, badge: 'Host' },
+    { id: 'bo', label: 'Bo Sample', status: { label: 'Away', tone: 'warning' } },
+    { id: 'free', label: 'Free', empty: true },
+  ]}
+  highlightedId="ada"
+  centerSlot={<p>Round 2</p>}
+  selectionMode="single"
+  value={target}
+  onValueChange={setTarget}
+/>
+```
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `seats` | `Seat[]` | required | `{ id, label, avatar?: { src?, fallback? }, status?: { label, tone? }, badge?, disabled?, empty? }`; clockwise from the top |
+| `layout` | `'ring' \| 'grid'` | `'ring'` | `ring` falls back to the grid in a narrow box and past the seat limit (10 seats) |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | seat width 4.75, 6 or 8rem; ring from a box of 32, 38 or 46rem; at most 10 seats on the circle |
+| `selectionMode` | `'none' \| 'single' \| 'multiple'` | `'none'` | `none`: a list; otherwise a listbox |
+| `value`, `defaultValue`, `onValueChange` | `string \| null` (single), `string[]` (multiple) | — | controlled or not |
+| `highlightedId` | `string` | — | emphasised seat (whose turn it is); `aria-current="true"` on it, in a list and in a listbox |
+| `renderAvatar`, `renderStatus`, `renderBadge` | `(seat) => ReactNode` | — | replace the default avatar, status line or badge |
+| `renderEmptySeat` | `(seat) => ReactNode` | dashed circle and "Empty seat" | content of an empty seat |
+| `centerSlot` | `ReactNode` | — | middle of the ring (a timer, a title); above the seats in the grid |
+| `aria-label` / `aria-labelledby` | `string` | — | names the list or the listbox: always give one |
+
+The layout follows the component's own width (a container query), not the
+window, so it also collapses in a narrow column or a dialog. The grid is two columns
+at 30rem or less and auto-fill above it, with a 44px minimum seat height. The circle is CSS only, so server markup has
+no `style` attribute and a strict CSP is fine.
+
+**Accessibility**
+
+- Not selectable: a `list` of `listitem`s. Selectable: a `listbox` of `option`s
+  (`aria-multiselectable` in `multiple`).
+- A roving tab stop sits on the chosen seat, else the first taken one. Arrow
+  keys, Home and End move the focus (an empty seat is skipped); Space or Enter
+  picks, and pressing the chosen seat again clears it.
+- A seat is named by its label and its status text, never by colour alone.
+- In a listbox, empty and `disabled` seats are `aria-disabled`, and a disabled
+  seat can be reached but not picked (in a list, `disabled` only dims the seat).
+- Put no button in a selectable seat: interactive content (an "Invite" action
+  in `renderEmptySeat`) belongs to a non-selectable ring.
+- Seat changes are not animated beyond a colour fade, which stops under
+  `prefers-reduced-motion`.
+
+**Storybook:** `Data display/SeatRing` · **Vue:** not yet (#1931)
+
+---
+
+## SecretCard
+
+![SecretCard](../previews/data-display-secretcard.webp)
+
+A card that holds a secret and shows it only after a deliberate tap or click: a
+private role in a party game, a one-time code, a recovery key, a card to turn
+over. It is hidden by default, can be hidden again, and can hide itself after a
+delay. The secret (`back`) is **not rendered** while hidden, so it is not in the
+markup, not read by a screen reader and not copied; it is not merely covered by CSS.
+
+```tsx
+import { Button, SecretCard } from '@nxgt/material/components';
+
+<SecretCard
+  title="Your role"
+  description="Look alone, then hide it."
+  back={<p>Night watch</p>}
+  autoHideMs={8000}
+  actions={<Button variant="outlined">Next player</Button>}
+/>
+```
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` | required | the name, always shown (a heading, `h3`) |
+| `back` | `ReactNode` | required | the secret, rendered only while revealed |
+| `description` | `ReactNode` | - | a hint, shown only while hidden |
+| `front` | `ReactNode` | neutral pattern | the hidden face; put no secret in it |
+| `icon` | `ReactNode` | - | decorative, before the title |
+| `tone` | `Tone` | - | `data-tone`: a named tone or an app's |
+| `actions` | `ReactNode` | - | buttons beside the reveal button |
+| `revealed` + `onRevealedChange` | `boolean` + `(revealed) => void` | - | controlled |
+| `defaultRevealed`, `onRevealedChange` | `boolean`, `(revealed) => void` | `false` | uncontrolled; never together with `revealed` |
+| `autoHideMs` | `number` | - | hides again after this long shown; also calls `onRevealedChange(false)` |
+| `disabled` | `boolean` | `false` | the card cannot be revealed; a revealed card can always be hidden |
+| `labels` | `Partial<{ reveal, revealed, hidden }>` | `material.secret-card.*` | the button's name ("Show secret") and the announcements |
+
+Controlled, with your own words:
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<SecretCard
+  title="Recovery key"
+  back={<code>K7QF-92LM</code>}
+  revealed={open}
+  onRevealedChange={setOpen}
+  labels={{ reveal: 'Show the key', revealed: 'Key shown', hidden: 'Key hidden' }}
+/>
+```
+
+**Accessibility**
+
+- The reveal is a real `button`, a disclosure: one name ("Show secret"; the
+  icon changes) and `aria-expanded` for the state, with `aria-controls` on the
+  face. Only a click, a tap, Enter or Space reveals: no hover, so a scroll
+  never reveals it.
+- A click is carried by `aria-expanded`, so nothing is announced for it. A
+  change a click does not explain (`autoHideMs`, the parent) is said through a
+  polite live region ("Secret revealed", "Secret hidden"). The message never
+  holds the secret, and nothing is said on the first render.
+- When the face that held focus is swapped (a focusable `back` on auto-hide, a
+  focusable `front` on reveal), focus moves to the reveal button.
+- `disabled` stops a reveal only: a revealed card can always be hidden.
+- The flip runs only after a change (not on first render or hydration) and
+  without `prefers-reduced-motion`; with it the face changes at once.
+- The card is full width up to 28rem, the button is at least 44px high, and
+  the layout follows `dir` (RTL) and dark mode.
+- Keep `front` and `description` free of the secret: they are always in the page.
+
+**Storybook:** `Data display/SecretCard` · **Vue:** not yet (#1938)
+
+---
+
 ## Shape
 
 ![Shape](../previews/data-display-shape.webp)
@@ -352,7 +493,7 @@ import { Link } from 'react-router';
 | `items` | `PeriodCardItem[]` | — | `id`, `title`, `start`, `end` (`Date`, ISO string or timestamp, read as local days; `'2026-09-01'` is that day, not UTC), and optionally `state`, `description`, `badges`, `footer`, `href` |
 | `today` | `DayInput \| false` | now | the day that tells the current period, by calendar day, both ends included; `false` turns the detection off |
 | `state` (per item) | `'past' \| 'current' \| 'upcoming'` | from `today` | an explicit state wins over the dates |
-| `linkComponent` | `LinkComponent` | `<a>` | the title's link, as the app shell's |
+| `linkComponent` | `LinkComponent` | `<a>` | the title's link, as the app shell's. Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 | `emptyState` | `ReactNode` | — | shown instead of the list when `items` is empty |
 | `headingLevel` | `2 \| 3 \| 4` | `3` | the level of each card's heading |
 | `dateFormat` | `Intl.DateTimeFormatOptions` | day, short month, year | how the range reads, through `formatRange` |
@@ -817,7 +958,7 @@ A tile with an `href` ends with a discreet chevron after `trailing`: decorative
 | --- | --- | --- | --- |
 | `href` | `string` | — | renders an `<a>`, with a chevron by default |
 | `chevron` | `boolean` | `true` with an `href`, else `false` | the decorative chevron after `trailing` |
-| `linkComponent` | `AppShellLinkComponent` | plain `<a>` | the link element, as in the app shell: takes `href`, spreads every other prop, forwards `ref` |
+| `linkComponent` | `AppShellLinkComponent` | plain `<a>` | the link element, as in the app shell: takes `href`, spreads every other prop, forwards `ref`. Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 | `onClick` | `MouseEventHandler` | — | renders a `<button>` |
 | `selected` | `boolean` | `false` | the current row: drawn selected; a link gets `aria-current="page"` (your own `aria-current` replaces it), a button `aria-pressed` |
 | `toggle` | `Switch` props | — | makes the tile a switch row (see below): the whole row toggles a Switch at its end; `href`, `onClick`, `actions`, `chips`, `chevron` and `linkComponent` are refused beside it by type |
@@ -1166,6 +1307,75 @@ the same way; pass the app's zone from the server so every screen agrees.
 
 ---
 
+## VoteTally
+
+![VoteTally](../previews/data-display-votetally.webp)
+
+A live ranked tally of a vote: a poll, a decision in a meeting, an election, a
+party-game ballot. One row per option with its count and share written as text
+("Ada Example, 3 votes, 60%"), a bar beneath, and who voted for it. The leader,
+a tie and the viewer's own vote are marked in words. Counts can change while
+the page is open.
+
+```tsx
+import { VoteTally } from '@nxgt/material/components';
+
+<VoteTally
+  aria-label="Best day"
+  options={[
+    { id: 'mon', label: 'Monday', count: 5, voters: [{ id: 'ada', label: 'Ada Example' }] },
+    { id: 'tue', label: 'Tuesday', count: 2 },
+  ]}
+  selectedId="tue"
+  abstainCount={1}
+/>
+```
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `options` | `VoteOption[]` | required | `{ id, label, count, voters?: { id, label, avatar? }[], avatar? }` |
+| `total` | `number` | sum of counts | base of the shares; abstentions are never in it. `0` or less falls back to the sum. A `total` below the sum caps each share at 100 |
+| `sort` | `'count' \| 'none'` | `'count'` | highest first; equal counts keep their order and share a rank |
+| `selectedId` | `string` | — | the viewer's vote: "Your vote" badge and the primary fill |
+| `showLeader` | `boolean` | `true` | "Leader" on a single top option, "Tie" on each of several; no arbitrary leader. Off: no mark, no emphasis, and the status says the votes cast instead of who leads |
+| `showVoters` | `'none' \| 'avatars' \| 'names'` | `'avatars'` | avatars, or a line of names |
+| `maxVoters` | `number` | `5` | voters shown before "+N"; names mode ends with "+N more" |
+| `abstainCount` | `number` | — | shown under the bars ("2 abstentions") and added to the announcement |
+| `animated` | `boolean` | `true` | the bar's width eases when a count changes (only the width), never under `prefers-reduced-motion` |
+| `emptyLabel` | `ReactNode` | "No votes yet" | shown while no option has a vote, rows (if any) stay beneath it |
+| `announceDelay` | `number` | `1000` | ms a change waits before it is announced |
+| `renderOption`, `renderVoters` | `(row) => ReactNode` | — | replace a row's label cell or voters; `row` has `option`, `rank`, `percent`, `leader`, `tied`, `selected` |
+| `header`, `footer` | `ReactNode` | — | above and below the rows |
+| `aria-label` / `aria-labelledby` | `string` | — | names the list: always give one |
+| `className`, other `div` props | — | — | go to the root `div` |
+
+**Shares.** Percentages are whole numbers. When `total` is the sum of the
+counts they add up to 100 (largest remainder: 1, 1 and 1 vote read 34%, 33%,
+33%). With a larger `total` (voters still to come) each share is rounded on its
+own, so they add up to less.
+
+**Accessibility**
+
+- A `list` of `listitem`s. Each row's text is real: the label, then
+  "3 votes" and "60%". The bars are `aria-hidden`.
+- Leader, tie and "Your vote" are words in badges, never colour alone.
+- A visually hidden polite status says where the vote stands ("Monday leads
+  with 5 votes", "Tie between Ada and Bo, 3 votes each"), and any
+  abstentions, once changes stop for
+  `announceDelay`. It never says the page as loaded, and a burst of updates is
+  one announcement.
+- Voters are a named group (`Voters for Monday`) of avatars each named by the
+  voter, or a line of names.
+- One column at any width: on a phone the count wraps under the label, long
+  labels wrap, and a bar keeps its own line so changing counts do not move rows.
+  It mirrors in right-to-left, and the bars follow the theme in dark mode.
+- Bar widths are SVG attributes, so server markup has no `style` attribute and
+  a strict CSP is fine.
+
+**Storybook:** `Data display/VoteTally` · **Vue:** not yet (#1940)
+
+---
+
 ## EventChip
 
 ![EventChip](../previews/data-display-eventchip.webp)

package/docs/components/data-table-filter-and-lists.md

@@ -125,7 +125,7 @@ table enables, for typing your own column defs.
 | `footer` | `false \| (table) => ReactNode` | the pagination | replaces the footer, or removes it |
 | `getRowHref` | `(row) => string \| undefined` | — | the first data cell links to the row's page; a click elsewhere on the row follows it |
 | `onRowClick` | `(row, event) => void` | — | a click on the row (not on a control); alone (without `getRowHref`), it makes the row focusable and Enter calls it |
-| `linkComponent` | `ComponentType<{ href, className?, children?, rel?, 'aria-label'?, onClick? }>` | `<a>` | the link for `getRowHref` and the page links: wrap your router's. It must forward `className` and `ref` (the past-end page's "Back to the first page" is a `Button asChild` over it) |
+| `linkComponent` | `ComponentType<{ href, className?, children?, rel?, 'aria-label'?, onClick? }>` | `<a>` | the link for `getRowHref` and the page links: wrap your router's. It must forward `className` and `ref` (the past-end page's "Back to the first page" is a `Button asChild` over it). Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 | `reserveActions` | `boolean` | `true` | with `actions` and a `select` column: keep the toolbar's 68px band while nothing is selected, so the bar does not push the rows down; `false` keeps none and the bar arrives on the first selection (`ServerTable` passes `false`) |
 | `focusable` | `boolean` | `true` with `actions`, else `false` | the `<table>` (or the list of cards or tiles) takes the focus by script (`tabindex="-1"`, never a tab stop): where the focus goes once the control that had it is gone. When the selection is cleared and the focused control went with it (a bulk action's button), the table takes the focus instead of the page's body ([focus after a bulk action](#focus-after-a-bulk-action)); `false` turns both off |
 | `tableRef` | `Ref<HTMLTableElement>` | — | the `<table>`, to focus it yourself (with `focusable`); `controls.focusTable()` does the same from a toolbar slot. It stays `null` while the layout is a list (`cards`, `tiles`, or the phone side of `{ phone, wide }`): use `focusRef` |
@@ -1258,7 +1258,7 @@ import { ListEmpty } from '@nxgt/material/components';
 | `clear` | `string` | "Clear search and filters" | the way out's label (`material.list-empty.clear`) |
 | `onClear` | `() => void` | — | the way out is a button |
 | `clearHref` | `string` | — | the way out is a link (without `onClear`) |
-| `linkComponent` | `DataTableLinkComponent` | `<a>` | the link for `clearHref` (a router's); it must forward `className` and `ref`, since the button is `asChild` over it |
+| `linkComponent` | `DataTableLinkComponent` | `<a>` | the link for `clearHref` (a router's); it must forward `className` and `ref`, since the button is `asChild` over it. Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 | `headingLevel` | `2`–`6` | `2` | the title is a heading of this level, so the page keeps a landmark when the list empties; the look does not change |
 | `busy` | `boolean` | `false` | the next answer is loading: the page stays, marked `data-busy` (no `aria-busy`: the element has no role) |
 
@@ -1314,7 +1314,7 @@ A list that fits one page shows "1–5 of 5" by default. `hideOnSinglePage` rend
 | `hideOnSinglePage` | `boolean` | `false` | renders nothing when there is no previous and no next page; the range is then not shown, so tell the count elsewhere (a heading, a status line) or keep the footer |
 | `live` | `boolean` | `true` | `false` renders the range as plain text instead of a polite live region |
 | `disabled` | `boolean` | `false` | makes Previous and Next inert while the feed loads |
-| `linkComponent` | `DataTableLinkComponent` | `<a>` | your router's link; it must forward `className` and `ref` |
+| `linkComponent` | `DataTableLinkComponent` | `<a>` | your router's link; it must forward `className` and `ref`. Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 
 **Storybook:** `Data table, filter & lists/PageFooter`
 

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

@@ -760,7 +760,9 @@ import { CountdownTimer } from '@nxgt/material/components';
 It ticks on the client only: the server renders the full time. The clock is a
 `role="timer"`; a polite live region speaks only when a threshold is crossed
 ("1:00 left") and when the time is up, never every second. `formatClock` and
-`countdownTone` are exported too.
+`countdownTone` are exported too, and so is the clock itself as the
+[`useCountdown`](../guides/helpers.md#usecountdown) hook (`@nxgt/material/hooks`),
+for a button that waits without a ring.
 
 **Storybook:** `Feedback & status/CountdownTimer` · **Vue:** React only for now (#890)
 
@@ -1210,7 +1212,7 @@ function invite(answer: (id: string, yes: boolean) => void): NotificationItem {
 | `footer` | `ReactNode` | — | under the list: "View all", settings… |
 | `fullScreenOnMobile` | `boolean` | `true` | a phone gets a full-screen sheet instead of the popover |
 | `toastOnArrival` | `boolean` | `false` | shows a toast for each new item (needs a `Toaster`) |
-| `linkComponent` | `LinkComponent` | native `<a>` | renders each row's `href` through your router's link, so a click navigates without a page load: `linkComponent={({ href, ...p }) => <Link to={href} {...p} />}` (spread every prop, as for `AppShell`) |
+| `linkComponent` | `LinkComponent` | native `<a>` | renders each row's `href` through your router's link, so a click navigates without a page load: `linkComponent={({ href, ...p }) => <Link to={href} {...p} />}` (spread every prop, as for `AppShell`). Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 | `error` / `onRetry` | `ReactNode \| boolean` / `() => unknown` | — | the feed could not be read: the list is replaced by an error line (`true` for the default words, a node for your own message) and, with `onRetry`, a Retry button (a returned promise keeps it loading). The empty state is not shown; counts still come from `items` / `count` |
 
 A row is interactive only when a click does something: it has an `href`, or
@@ -1284,7 +1286,7 @@ import { NotificationRow } from '@nxgt/material/components';
 | `createdAt` / `now` | `Date \| string \| number` | — | the time, counted from `now` (the clock when unset) |
 | `unread` | `boolean` | `false` | tint, bold, dot and edge |
 | `href` / `onOpen` | — | — | the row as a link or a button |
-| `linkComponent` | `LinkComponent` | native `<a>` | renders the `href` link through your router's link (`Notifications` passes its own down) |
+| `linkComponent` | `LinkComponent` | native `<a>` | renders the `href` link through your router's link (`Notifications` passes its own down). Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 | `onMarkRead` / `onDismiss` | `() => void` | — | the quick actions (mark read only while unread) |
 | `actions` | `NotificationAction[]` | — | inline buttons; the first is filled, the rest tonal (`emphasis` overrides) |
 | `density` | `'comfortable' \| 'compact'` | `'comfortable'` | spacing, avatar size, one-line description |

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

@@ -66,7 +66,7 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `items` | `MenuItem[]` | — | `label` (already translated), `url`, `icon`, `footer`, `display` (`'icon'`: a round icon-only button, the label as tooltip and name; see the [app shell guide](../guides/app-shell.md)), `badge` (`true` a dot, a number a count up to "99+"), `badgeLabel` (see [Badges](../guides/app-shell.md#badges)) |
-| `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href`; see the [app shell guide](../guides/app-shell.md) |
+| `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href`; see the [app shell guide](../guides/app-shell.md). Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 | `logo`, `name` | `AppLogo` (`ReactNode \| string \| AppLogoImage`, `AppLogoImage` = `{ src, alt? }`), `string` | — | the app's logo alone in the collapsed rail, named by `name` (also its tooltip); logo and name side by side in the phone's menu sheet |
 | `context` | `ReactNode` | — | a line at the top of the phone's menu sheet, above the brand: the current tenant's name; `name` stays the app's brand; `AppHeader` and `AppSidebar` take it too (see the [app shell guide](../guides/app-shell.md#the-brand-logo-and-name)) |
 | `brand` | `ReactNode` | — | replaces the sidebar header, in the rail and the menu sheet; wins over `logo` and `name` |
@@ -148,7 +148,7 @@ import { AccountMenu, ActivityLayout } from '@nxgt/material/components';
 | `secondary` | `ReactNode` | — | a second line under the name, the e-mail say |
 | `src` | `string` | — | the avatar's picture; the initials until it loads, or without one |
 | `items` | `AccountMenuItem[]` | `[]` | `{ label: ReactNode; url: string; icon?: IconName }`: links between the header and Sign out; `label` already translated, `icon` a [Font Awesome](https://fontawesome.com/icons) symbol id of the duotone sprite (see [Icon](primitives.md#icon)) |
-| `linkComponent` | `AppShellLinkComponent` | React Router `Link` | the link each item renders, as in the app shell |
+| `linkComponent` | `AppShellLinkComponent` | React Router `Link` | the link each item renders, as in the app shell. Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 | `onSignOut` | `() => void` | — | Sign out was chosen; the menu stays open, so `signingOut` shows |
 | `signOutLabel` | `ReactNode` | "Sign out" | `material.account-menu.sign-out` |
 | `signingOut` | `boolean` | `false` | Sign out is busy (`aria-busy`, a spinner) and ignores a second selection |
@@ -588,7 +588,7 @@ import { Pager } from '@nxgt/material/components';
 | `previous`, `next` | `{ title; href; description? }` | — | either may be omitted |
 | `shortcuts` | `boolean` | `false` | shows `[` / `]` key hints (the `Doc` shell handles the keys) |
 | `previousLabel`, `nextLabel` | `string` | translated | small labels |
-| `linkComponent` | `ComponentType<{ href; className?; children? }>` | `<a>` | your router's link |
+| `linkComponent` | `ComponentType<{ href; className?; children? }>` | `<a>` | your router's link. Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 
 External `href`s open in a new tab.
 
@@ -617,7 +617,7 @@ import { SeeAlso } from '@nxgt/material/components';
 | --- | --- | --- | --- |
 | `items` | `{ id?; title; href }[]` | — | external links get the outbound icon |
 | `label` | `string` | translated "See also" | heading |
-| `linkComponent` | `ComponentType<{ href; className?; children? }>` | `<a>` | your router's link |
+| `linkComponent` | `ComponentType<{ href; className?; children? }>` | `<a>` | your router's link. Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 
 **Storybook:** `Navigation & layout/SeeAlso` · **Vue:** `SeeAlso`
 

package/docs/components/primitives.md

@@ -28,6 +28,7 @@ other pages are built from these.
 | <img src="../previews/primitives-togglegroup.webp" width="96" alt=""> | [ToggleGroup](#togglegroup) | Connected, segmented or separate toggle group |
 | | [Activity](#activity) | React `<Activity>` switched by a boolean |
 | | [NonceProvider](#nonceprovider) | Gives the page's CSP nonce to every component below |
+| | [LinkComponentProvider](#linkcomponentprovider) | Sets, once, the link component of every component that renders a link |
 
 ## Accordion
 
@@ -960,6 +961,67 @@ import { Activity } from '@nxgt/material/components';
 
 **Storybook:** — · **Vue:** `Activity`
 
+## LinkComponentProvider
+
+No preview: it draws nothing of its own, it hands the app's link component down.
+
+Sets once the link the components below render their links with: `LinkButton`
+(with `IconLinkButton` and `ResponsiveLinkButton`), the sidebar and app shell,
+`AccountMenu`, `Pager`, `SeeAlso`, `Toc`, `PeriodCards`, `NotificationRow`,
+`Doc` (which then skips its `onNavigate`, as for its own `linkComponent`),
+`ListTile`, `DataTable`, `ServerTable`, `PageFooter`, `ListEmpty`, `Switcher`,
+`Notifications`, `Breadcrumb` and `Pagination` links, `LinkCard` (internal addresses only; an external one stays a
+plain `<a>`) and `QuestionNavigator`'s link variant.
+
+Not wired, by design: `ActionCard`'s `titleLink` and `Markdown`'s links are
+elements or content you supply, `SkipLink` and `PaginationBar` are in-page
+(`#`) anchors, `ContactLinks` renders `mailto:` and `tel:` links, and the
+`FileList` and `FilePreview` download links, `EnrolmentSecret`'s `otpauth:`
+link and the editor's action card (`target="_blank"`) are not navigation. A component's own `linkComponent` prop still wins. Without the provider
+and without the prop, each keeps its own default, so nothing changes until you
+render it.
+
+```tsx
+import {
+	LinkComponentProvider,
+	type LinkComponentProps,
+} from '@nxgt/material/components';
+import { Link } from 'react-router';
+
+// Spread every prop onto the element; a function component receives `ref`
+// as a prop in React 19, so spreading forwards it.
+const RouterLink = ({ href, ...props }: LinkComponentProps) => (
+	<Link to={href} {...props} />
+);
+
+<LinkComponentProvider component={RouterLink}>
+	<App />
+</LinkComponentProvider>;
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `component` | `LinkComponent` | — | the default link: `ComponentType<LinkComponentProps>`, where `LinkComponentProps` is the anchor's props plus a required `href` |
+
+`LinkComponent` and `LinkComponentProps` are exported from
+`@nxgt/material/components`, and `useLinkComponent(own?)` returns the link a
+component of your own should render (`own`, else the provider's, else
+`undefined`). `LinkButton` and its siblings take a router `to`: with a link
+component they hand it over as `href`, with `target` and `download`;
+`replace`, `state`, `reloadDocument` and `preventScrollReset` belong to React
+Router's `Link` and are not passed. They also take `linkComponent` themselves.
+
+```tsx
+import { useLinkComponent } from '@nxgt/material/components';
+
+function MyCrumb({ href, children }: { href: string; children: string }) {
+	const Link = useLinkComponent() ?? 'a';
+	return <Link href={href}>{children}</Link>;
+}
+```
+
+**Storybook:** — · **Vue:** —
+
 ## NonceProvider
 
 No preview: it draws nothing of its own, it hands the page's Content Security

package/docs/components/rich-widgets.md

@@ -2412,7 +2412,58 @@ French bundle — see [i18n](../guides/i18n.md).
 | `onComplete` | `(result: QuizResult) => void` | — | `{ correct, total, percent, answers, timedOut }`, once per results screen |
 | `onAnswersChange` / `onIndexChange` | callbacks | — | follow progress |
 | `QuestionCard` `revealed` | `boolean` | `false` | marks right / wrong and shows the verdict and `explanation` |
+| `QuestionCard` `verdict` | `'correct' \| 'incorrect' \| 'pending'` | — | the server's verdict, shown as given (word and icon, never colour alone); reveals the card. `question.correct` is optional and only highlights the right choices. Without it, `revealed` compares in the browser as before |
+| `QuestionCard` `points` / `feedback` | `{ awarded, possible }` / `string` | — | points earned and a grader's remark, in the verdict banner (with `verdict`) |
+| `Question` `media` | `{ src, alt?, kind?, type?, name? }` | — | an image (default), audio (`kind: 'audio'` or `type: 'audio/*'`, an `AudioPlayer`) or a document link (any other `type`, a `FilePreview`); `name` (else `alt`) is the text alternative |
 | `QuestionCard` `value` / `onValueChange` | `QuestionAnswer` | — | controlled answer |
 | `QuestionCard` `variant` / `density` / `showShortcuts` / `number` / `showFeedback` | — | `'card'`, `'comfortable'`, `false`, —, `true` | framed or plain, spacing, key badges, "Question 2", the verdict banner |
 
+A server-graded answer, shown as given (no comparison in the browser):
+
+```tsx
+<QuestionCard
+  question={{ id: 'q1', kind: 'text', prompt: 'Explain X' }}
+  value="my answer"
+  verdict="incorrect" // or 'correct' | 'pending'
+  points={{ awarded: 2, possible: 3 }}
+  feedback="Good, but cite a source"
+/>
+```
+
 **Storybook:** `Rich widgets/Quiz`, `Rich widgets/QuestionCard` · **Vue:** `Quiz`, `QuestionCard` (the modes, results, number kind and shortcuts are React only for now, #890)
+
+### QuestionNavigator
+
+The numbered questions of a quiz or exam player: jump to one, see the current
+one and which are answered or flagged. Import it from
+`@nxgt/material/widgets/education`.
+
+```tsx
+<QuestionNavigator
+  count={20}
+  current={3}
+  answered={[1, 2]} // or a Set
+  flagged={[2]}
+  onSelect={(n) => go(n)}
+/>
+// URL-driven player: <QuestionNavigator count={20} current={3} getHref={(n) => `/quiz/${n}`} />
+```
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `count` | `number` | — | how many questions |
+| `current` | `number` | — | the current question, **from 1**; gets `aria-current="step"` |
+| `answered` / `flagged` | `number[] \| Set<number>` | — | question numbers, from 1 |
+| `onSelect` | `(n: number) => void` | — | each number is a button |
+| `getHref` | `(n: number) => string` | — | each number is a link; wins over `onSelect`. With neither, the numbers are plain marks |
+| `label` | `string` | `"Questions"` | the navigation's name |
+
+Each target is at least 44 x 44 px. Answered shows a check and flagged a flag,
+and both are named in the accessible label ("Question 2, answered, flagged,
+current"), never by colour alone. With many questions it is **one row that
+scrolls sideways and keeps the current number in view** (rather than a wrapping
+grid): its height stays constant at 20 or 100 questions on a 360px phone, so it
+can sit above the question without pushing it down. Labels live under
+`material.question-navigator.*` (`label`, `item`, `answered`, `unanswered`, `flagged`, `current`).
+
+**Storybook:** `Rich widgets/QuestionNavigator` · **Vue:** not yet (React first, #1948)

package/docs/components/selection-and-choice.md

@@ -1351,7 +1351,7 @@ To put a Switcher at the start of a page header, pass it as [EntityHeader](data-
 | `searchable` | `boolean` | from 8 options (always, expressive) | the search field of the panel; `true` also replaces the menu with the panel |
 | `recent` | `string[]` | — | up to 3 option ids shown as tiles (expressive) |
 | `getHref` | `(item) => string \| undefined` | — | link mode; falls back to `item.href` |
-| `linkComponent` | `LinkComponent` | `<a>` | your router's link: takes `href`, spreads every prop, forwards `ref` |
+| `linkComponent` | `LinkComponent` | `<a>` | your router's link: takes `href`, spreads every prop, forwards `ref`. Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 | `footer` | `{ label?, onSelect?, href? }` | — | a "Manage…" button (a link with `href`) at the end of the panel; `label` defaults to `material.switcher.manage` |
 | `emptyLabel` | `ReactNode` | `material.switcher.empty` | shown when the search matches nothing |
 | `sheet` | `boolean` | on a phone | `true` always opens a sheet, `false` never |

package/docs/guides/app-shell.md

@@ -198,7 +198,7 @@ partitionMenu(items);                              // { content, footer }
 | `context` | `ReactNode` | — | A line at the top of the phone's menu sheet, above the brand: the current tenant's name, already translated (see [The brand](#the-brand-logo-and-name)). `name` stays the app's brand; the collapsed rail shows no context |
 | `brand` | `ReactNode` | — | Replaces the sidebar header entirely, in the rail and in the menu sheet; wins over `logo` and `name` |
 | `avatar` | `ReactNode` | — | End of the header. A `string` is used as the image URL of an `Avatar`; anything else is rendered as-is |
-| `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href` (see below) |
+| `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href` (see below). Defaults to the [`LinkComponentProvider`](../components/primitives.md#linkcomponentprovider)'s link when one is set. |
 | `headerTitle` | `ReactNode` | — | The header's leading title: the context the app is in (the active organisation's name), right after the phone's menu button, truncated when long; when it is cut off, its full text is the `title` tooltip (#629) |
 | `titleAfter` | `ReactNode` | — | A node right after the page's title in the app bar, outside its `h1` (a record's `Switcher`); wins over a route's `handle.titleAfter` (see [A slot after the title](#a-slot-after-the-title)) |
 | `headerContext` | `ReactNode` | — | A small muted context line (the tenant's name) after the page's title and its slot, from `md` up: outside the `h1`, truncated, its full text the tooltip once cut off. Not shown on a phone, where the menu sheet's `context` carries it (see [A context line](#a-context-line-after-the-title)) |
@@ -231,7 +231,7 @@ hydration on a server-rendered page, opens in a new tab on middle-click, and
 is announced as a link, named by its label alone ("Identities": the icon beside
 it is decorative); the current page's entry carries `aria-current="page"`.
 By default it is a React Router `Link` (client-side navigation, the router's
-`basename`), so leaving `linkComponent` out never reloads the page. Pass it only
+`basename`), so leaving `linkComponent` out never reloads the page; a [`LinkComponentProvider`](../components/primitives.md#linkcomponentprovider) above the shell sets another default once. Pass it only
 for another router or a custom link: a component taking
 `href`. It must spread **every other prop it receives** onto the element it
 renders (`className`, `aria-current`, the tooltip's handlers, `data-state`) and

package/docs/guides/helpers.md

@@ -137,6 +137,7 @@ Vue: the Redux helpers are Pinia store factories: `defineLocalStore`
 | `useAllowedTransitions(status, transitions, configs)` | Status-machine actions (icon, colour, label, dialog copy) allowed from the current status. |
 | `useFocusOnMount<T>(focus = true)` | A ref whose element takes focus once mounted, and again whenever `focus` turns true: the heading of what replaced the content the user acted on. See [below](#usefocusonmount). |
 | `useScrollAway(ref?, { threshold? })` | True while the reader scrolls down (by `threshold`, 24 px, since the scroll last turned); false scrolling up, at the top or at the end. Folds an extended `Fab`. Without `ref`, the window; false on the server. See [Fab](../components/buttons-and-actions.md#fab). |
+| `useCountdown(duration, { paused?, onExpire?, key? })` | Seconds left of `duration` (the clock `CountdownTimer` draws), for a button or a message that waits: ticks on the client only, `duration` on the server and first render. A new `duration` **or a new `key`** starts over, so the same `retryAfter` twice restarts it. See [below](#usecountdown). |
 | `useSubmitOnce(busy?)` | One submit in flight: wraps a submit handler so a double click or a second Enter is dropped until the request ends (the handler's promise, or `busy` back to false). See [below](#usesubmitonce). |
 | `createSubmitGuard()`, `busySettler(guard)` | The framework-free guard behind `useSubmitOnce` (`@nxgt/material-core/submit-guard`): `{ once(run, { settleSync? }), settle(run?), pendingRun() }`, and the function that settles it from a busy flag. |
 
@@ -204,6 +205,45 @@ export function Sent({ email }: { email: string }) {
 `useFocusOnMount(open)` focuses again whenever `open` turns true, for content
 that stays mounted and is only shown. Storybook: `Guides/Hooks/useFocusOnMount`.
 
+### `useCountdown`
+
+The clock behind [`CountdownTimer`](../components/feedback-and-status.md#countdowntimer),
+without the ring: the seconds left, for a submit button that stays disabled
+while a rate limit (a 429 `retryAfter`) runs out.
+
+```tsx
+import { useState } from 'react';
+import { Button } from '@nxgt/material/components';
+import { useCountdown } from '@nxgt/material/hooks';
+
+export function SignInButton({ signIn }: { signIn: () => Promise<{ retryAfter?: number }> }) {
+  const [wait, setWait] = useState({ seconds: 0, refusals: 0 });
+  const left = useCountdown(wait.seconds, { key: wait.refusals });
+  return (
+    <Button
+      disabled={left > 0}
+      onClick={async () => {
+        const { retryAfter } = await signIn();
+        if (retryAfter) setWait((w) => ({ seconds: retryAfter, refusals: w.refusals + 1 }));
+      }}
+    >
+      {left > 0 ? `Try again in ${Math.ceil(left)} s` : 'Sign in'}
+    </Button>
+  );
+}
+```
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `paused` | `false` | holds the clock where it is; it carries on from there |
+| `onExpire` | none | called once, when it reaches zero |
+| `key` | none (`string \| number`) | a new value starts the clock over from `duration`, even for the same duration: without it, a second refusal that answers `retryAfter: 30` again would not restart anything |
+
+It returns a number of seconds, fractional (it ticks every 250 ms): use
+`Math.ceil` to show it, `formatClock` (from `@nxgt/material/components`) for
+`m:ss`. The options type is exported as `UseCountdownOptions`. A `duration` of `0` is
+already expired and never calls `onExpire`.
+
 ### `useSubmitOnce`
 
 A disabled or `loading` button only stops clicks once it has rendered, and

package/lib/components/components.css

@@ -134,6 +134,14 @@
 @import "./ui/display/period-cards/period-cards.css";
 @import "./ui/layout/sidebar/sidebar-tokens.css";
 @import "./ui/display/avatar/avatar.css";
+/* SeatRing: seats as a grid or on a circle by its own width. */
+@import "./ui/display/seat-ring/seat-ring.css";
+@import "./ui/display/seat-ring/seat-ring-index.css";
+@import "./ui/display/seat-ring/seat-ring-ring.css";
+/* VoteTally: ranked bars with counts, shares and voters. */
+@import "./ui/display/vote-tally/vote-tally.css";
+/* SecretCard: a face that is not rendered until it is revealed. */
+@import "./ui/display/secret-card/secret-card.css";
 /* Alert and Banner span the row in the form grids (#1497). */
 @import "./ui/feedback/alert/alert.css";
 @import "./ui/display/stat-card/stat-card.css";