@nxgt/material 3.73.0 → 3.75.0

package/dist/{use-heading-spy-Bzj5mIUZ.js → use-heading-spy-B_Z4ArDh.js}

@@ -1,8 +1,8 @@
 import { t as e } from "./utils-BLfntITJ.js";
-import { a as t, c as n, d as r, i, n as a, r as o, t as s, u as c } from "./alert-dialog-A8K8zai1.js";
-import { a as l } from "./button-C8moFnIT.js";
-import { i as u } from "./translate-material-D1ndrd7a.js";
-import { t as d } from "./use-material-translation-C6H0B4kE.js";
+import { a as t, c as n, d as r, i, n as a, r as o, t as s, u as c } from "./alert-dialog-BfO_ri-N.js";
+import { a as l } from "./button-DgenqmpS.js";
+import { i as u } from "./translate-material-pVlPJ1v4.js";
+import { t as d } from "./use-material-translation-CIS2n3RB.js";
 import { _ as f, g as p, h as m, n as h, v as g, y as _ } from "./number.utils-BG_eEt5g.js";
 import { useCallback as v, useEffect as y, useMemo as b, useRef as x, useState as S } from "react";
 import { Fragment as C, jsx as w, jsxs as T } from "react/jsx-runtime";

package/dist/{use-material-translation-C6H0B4kE.js → use-material-translation-CIS2n3RB.js}

@@ -1,4 +1,4 @@
-import { i as e, t } from "./translate-material-D1ndrd7a.js";
+import { i as e, t } from "./translate-material-pVlPJ1v4.js";
 import { useCallback as n } from "react";
 //#region lib/i18n/use-material-translation.ts
 function r() {

package/dist/{use-return-focus-CkUX1HFl.js → use-return-focus-DNQtADAR.js}

@@ -1,6 +1,6 @@
 import { o as e, r as t } from "./dist-DVRQkaTK.js";
 import { a as n, c as r, i, l as a, o, r as s, s as c } from "./dist-lmHmz_bu.js";
-import { C as l, S as u, w as d } from "./spinner-C5Kb6MWu.js";
+import { C as l, S as u, w as d } from "./spinner-B2MubVWb.js";
 import { c as f, i as p, l as m, o as h, r as g, s as ee } from "./in-dialog-Vwkyp-M5.js";
 import { r as _ } from "./escape-owner-DpaP0lm1.js";
 import * as v from "react";

package/docs/components/data-display.md

@@ -13,6 +13,7 @@ from `@nxgt/material/components`.
 | <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 |
+| <img src="../previews/data-display-highlightedtext.webp" width="96" alt=""> | [HighlightedText](#highlightedtext) | A string with the words of a search query in a themed `<mark>` |
 | <img src="../previews/data-display-dayseparator.webp" width="96" alt=""> | [DaySeparator](#dayseparator) | "Today", "Yesterday" or the date between two hairlines |
 | <img src="../previews/data-display-periodcards.webp" width="96" alt=""> | [PeriodCards](#periodcards) | Consecutive date ranges (terms, sprints) as cards, with a current marker and an optional link per card |
 | <img src="../previews/data-display-chip.webp" width="96" alt=""> | [Chip](#chip) | Three looks and a dashed add pill, with slots, a selected state and a dismiss button |
@@ -147,6 +148,7 @@ import { SeatRing } from '@nxgt/material/components';
   seats={[
     { id: 'ada', label: 'Ada Example', status: { label: 'Ready', tone: 'success' }, badge: 'Host' },
     { id: 'bo', label: 'Bo Sample', status: { label: 'Away', tone: 'warning' } },
+    { id: 'cy', label: 'Cy Demo', out: true },
     { id: 'free', label: 'Free', empty: true },
   ]}
   highlightedId="ada"
@@ -159,7 +161,7 @@ import { SeatRing } from '@nxgt/material/components';
 
 | Prop | Type | Default | Notes |
 | --- | --- | --- | --- |
-| `seats` | `Seat[]` | required | `{ id, label, avatar?: { src?, fallback? }, status?: { label, tone? }, badge?, disabled?, empty? }`; clockwise from the top |
+| `seats` | `Seat[]` | required | `{ id, label, avatar?: { src?, fallback? }, status?: { label, tone? }, badge?, disabled?, out?, 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 |
@@ -183,6 +185,7 @@ no `style` attribute and a strict CSP is fine.
   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.
+- `out: true` marks an eliminated seat: it stays visible, dimmed, with the name struck through, the avatar greyed and the word "Out" (`material.seat-ring.out`, "Éliminé" in French) written in it, so the word is part of the seat's name (label, status, "Out", then the badge); it stays pickable unless `disabled`. An empty seat ignores it. Seat status words ("Eliminated") remain the app's own.
 - 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
@@ -228,6 +231,7 @@ import { Button, SecretCard } from '@nxgt/material/components';
 | `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)` |
+| `size` | `'default' \| 'sm'` | `'default'` | `sm` is the compact card for a phone: the faces lose their 6rem minimum height, the padding and gap tighten (`data-size`) |
 | `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 |
 
@@ -417,6 +421,35 @@ import { CountBadge, IconButton } from '@nxgt/material/components';
 
 ---
 
+## HighlightedText
+
+![HighlightedText](../previews/data-display-highlightedtext.webp)
+
+A string with the words of a search query in a themed `<mark>`. Case, accents and ligatures are folded (`œ` is `oe`, `æ` is `ae`, `ß` is `ss`), and a query word matches at the start of a word, as a search engine's normaliser does.
+
+```tsx
+import { HighlightedText, highlightRanges } from '@nxgt/material/components';
+
+<HighlightedText text="Œuvres d'été" query="oeuvre ete" />
+// <mark>Œuvre</mark>s d'<mark>été</mark>
+
+// For a table or a custom renderer: offsets into the original text.
+highlightRanges("Œuvres d'été", 'oeuvre ete'); // [[0, 5], [9, 12]]
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `text` | `string` | — | the string to show |
+| `query` | `string` | — | search words; a blank query marks nothing |
+| `locale` | `string` | runtime's | language for lowercasing |
+| span props | | | `className` and the other `span` props go to the wrapping `span` |
+
+`highlightRanges(text, query, locale?)` is pure and returns sorted, non-overlapping `[start, end)` offsets. The marks use theme tokens (readable in dark mode) and the system `Mark` colours in forced colours.
+
+**Storybook:** `Data display/HighlightedText`
+
+---
+
 ## DaySeparator
 
 ![DaySeparator](../previews/data-display-dayseparator.webp)
@@ -974,15 +1007,16 @@ A tile with an `href` ends with a discreet chevron after `trailing`: decorative
 | `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 |
+| `toggle` | `Switch` props | — | makes the tile a switch row (see below): the whole row toggles a Switch at its end; `href`, `onClick`, `actions`, `chips`, `content`, `chevron` and `linkComponent` are refused beside it by type |
 | `size` | `'sm' \| 'md'` | `'md'` | `sm` is the dense row (with `chips`, the record row, see below) |
 | `leading`, `trailing`, `subtitle` | `ReactNode` | — | slots; `trailing` sits inside the link, so it holds decoration only |
 | `actions` | `ReactNode` | — | buttons at the end of the tile, outside the link, vertically centred (`data-slot="item-actions"`) |
 | `chips` | `ReactNode` | — | tags after the text, in the compact record row (see below); inside the link, so decoration only; part of the row's accessible name, keep labels short |
+| `content` | `ReactNode` | — | full-width content under the title row, inside the tile's box and outside its link or button: it may hold inputs and buttons (an expected value beside an editable field), and its clicks do not reach `onClick`. Not available on a `toggle` row |
 | `variant` | `'tonal' \| 'divided'` | `'tonal'` | `divided`: flat rows with no tonal surface, a hover tint and the record-row layout; the hairline comes with `as="li"` |
 | `inset` | `boolean` | `false` | With `variant="divided"`: 16px of inline padding (M3's list-item inset) in place of 4px, for a list inside a `Card`; the hairlines on the `<li>` still run edge to edge. Ignored by `tonal` |
 | `as` | `'li'` | — | renders the tile inside a `<li>`, for a `<ul>` you own |
-| `disabled` | `boolean` | — | disables the link or button, and the `actions` with it |
+| `disabled` | `boolean` | — | disables the link or button, and the `actions` and `content` with it (both become inert) |
 
 With a router, pass `linkComponent` so a click navigates on the client instead of reloading the page (React Router's `Link` takes `to`, so wrap it):
 
@@ -999,7 +1033,27 @@ export function SettingsLink() {
 }
 ```
 
-A link tile's `trailing` sits inside its `<a>`, which cannot hold buttons. Put edit / remove / menu buttons in `actions`: they render outside the link, in the tile's box, while the link still covers the whole tile (a click on the text navigates, a click on a button does not) and hover and selected styles stay on the tile. Tab goes to the link, then to the buttons. A tile without `href` renders `actions` the same way. With `actions`, `className`, `style` and `data-*` go on the tile's box and every other prop (`aria-label`, `id`, handlers…) on the link or button; `actions={null}` (or `false`) is no actions. and the text of a link tile with actions cannot be selected (the link is stretched over the tile).
+A link tile's `trailing` sits inside its `<a>`, which cannot hold buttons. Put edit / remove / menu buttons in `actions`: they render outside the link, in the tile's box, while the link still covers the whole tile (a click on the text navigates, a click on a button does not) and hover and selected styles stay on the tile. Tab goes to the link, then to the buttons, then to the controls of `content`. A tile without `href` renders `actions` the same way. With `actions`, `className`, `style` and `data-*` go on the tile's box and every other prop (`aria-label`, `id`, handlers…) on the link or button; `actions={null}` (or `false`) is no actions. and the text of a link tile with actions cannot be selected (the link is stretched over the tile).
+
+**Content under the row.** `content` renders full-width under the title row, inside the tile's box and outside its link or button, so it may hold inputs and buttons (an expected value beside an editable field). Its clicks never reach the tile's `onClick`.
+
+```tsx
+<ul className="m-0 list-none p-0">
+  <ListTile
+    as="li"
+    variant="divided"
+    title="Item"
+    subtitle="SKU-1 · LOT-2"
+    actions={<IconButton label="Remove" onClick={remove}><Trash2 /></IconButton>}
+    content={
+      <label className="flex items-center justify-between gap-2">
+        Expected 12
+        <NumberField aria-label="Counted" value={counted} onChange={setCounted} />
+      </label>
+    }
+  />
+</ul>
+```
 
 ```tsx
 import { Pencil } from 'lucide-react';
@@ -1070,7 +1124,7 @@ function GuideList({ guides }: { guides: { to: string; title: string }[] }) {
 }
 ```
 
-**A switch row.** `toggle` takes a Switch's props (`checked`, `defaultChecked`, `onCheckedChange`, `name`, `thumbIcons`…). The tile is then a `<label>` for the switch, so a press anywhere on the row toggles it; the switch is the one tab stop (Space or Enter), named by `title` and described by `subtitle`, and `disabled` on the tile disables it. A switch row is neither a link nor a button: `href`, `onClick`, `actions` and `chevron` do not apply, and `trailing` sits before the switch.
+**A switch row.** `toggle` takes a Switch's props (`checked`, `defaultChecked`, `onCheckedChange`, `name`, `thumbIcons`…). The tile is then a `<label>` for the switch, so a press anywhere on the row toggles it; the switch is the one tab stop (Space or Enter), named by `title` and described by `subtitle`, and `disabled` on the tile disables it. A switch row is neither a link nor a button: `href`, `onClick`, `actions`, `content` and `chevron` do not apply, and `trailing` sits before the switch.
 
 ```tsx
 const [on, setOn] = useState(true);
@@ -1246,7 +1300,7 @@ yours, the component names no domain.
 | `kinds` | `Record<string, ChangeHistoryKindOverride>` | built-ins | `label`, `verb`, `icon` (`null` removes it), `tone` per kind; `creation` (default true for `created`) makes an entry list values only |
 | `variant` | `'rail' \| 'cards'` | `'rail'` | the look |
 | `groupBy` | `'day' \| 'none'` | `'day'` | a heading per day (sticky on the rail), or one list in the order given |
-| `collapseAfter` | `number` | `3` | an entry with more changes collapses behind "N fields changed" (a creation: "N fields set") and a preview of the names, as a button with `aria-expanded` |
+| `collapseAfter` | `number` | `3` | an entry with more changes collapses behind "N fields changed" (a creation: "N fields set") and a preview of the first three names, as a button with `aria-expanded`. The preview wraps instead of clipping with an ellipsis, and a screen reader hears the names behind the "+N" |
 | `filter` | `ReactNode` | — | a slot above the list, for a `Filter` bar |
 | `loading` | `boolean` | `false` | skeleton entries |
 | `hasMore` | `boolean` | — | shows the Load more button |

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

@@ -96,8 +96,8 @@ table enables, for typing your own column defs.
 | `data` | `T[]` | — | rows; sorting, filtering and pagination run client-side |
 | `layout` | `'table' \| 'cards' \| 'tiles' \| { phone, wide }` | `'table'` | `'cards'` lays the rows out as a list of cards, `'tiles'` as one column in a single surface ([Cards and tiles](../guides/cards-and-tiles.md)); both ignore `virtual`, `renderExpandedRow` and `showViewOptions` |
 | `cardDensity` | `'comfortable' \| 'compact'` | `'comfortable'` | `compact` fits cards of at least `--nxgt-cards-min` (15rem), up to four a row, with a tighter padding; `layout="cards"` only ([Cards and tiles](../guides/cards-and-tiles.md#columns)) |
-| `renderCard` | `(row, { Title, Row, selected, locked, reason }) => ReactNode` | — | a card's content, required with `layout="cards"`; `Title` is the card's one link and its name; `Row` (the compact record row) is also passed, laid out inside the card's own padding, with no height of its own |
-| `renderTile` | `(row, { Title, Row, selected, locked, reason }) => ReactNode` | — | a tile's content, required with `layout="tiles"`; same `Title` as a card, or `Row`, the compact record row (title, subtitle, chips, trailing facts; see the cards and tiles guide) |
+| `renderCard` | `(row, { Title, Actions, Row, selected, locked, reason }) => ReactNode` | — | a card's content, required with `layout="cards"`; `Title` is the card's one link and its name; `Actions` is the trailing action slot (outside the link, at least 44px); `Row` (the compact record row) is also passed, laid out inside the card's own padding, with no height of its own |
+| `renderTile` | `(row, { Title, Actions, Row, selected, locked, reason }) => ReactNode` | — | a tile's content, required with `layout="tiles"`; same `Title` as a card, or `Row`, the compact record row (title, subtitle, chips, trailing facts; see the cards and tiles guide) |
 | `renderExpandedRow` | `(row) => ReactNode` | — | makes rows expandable; pair with the `expand` column |
 | `showViewOptions` | `boolean` | — | column visibility menu above the table |
 | `actions` | `(table, controls) => ReactNode` | — | toolbar content with access to the table (selected rows…); disabled while `loading`. `controls.focusTable()` moves the focus to the table |
@@ -1018,7 +1018,7 @@ export default function Students() {
   table: [Cards and tiles](../guides/cards-and-tiles.md)).
 
 Its props are `ServerTableProps<T>`; `filter` is a `ServerTableFilter`,
-`empty` a `ServerTableEmpty`, and `bulkActions` gets a
+`empty` an optional `ServerTableEmpty`, and `bulkActions` gets a
 `ServerTableSelection`.
 
 | Prop | Type | Default | Effect |
@@ -1042,10 +1042,11 @@ Its props are `ServerTableProps<T>`; `filter` is a `ServerTableFilter`,
 | `loadMoreLabel` | `string` | "Load more" | with `footer="load-more"`: the button's label |
 | `hideOnSinglePage` | `boolean` | `false` | hides the footer's range and Previous / Next when the result is one page (no previous, no next), in the table, cards and tiles layouts; the count is still announced by the live region but no longer shown, so put it in `description` or keep the footer. With `bulkActions` the footer stays for "N rows selected", without its pager |
 | `bandActions` | `'stacked' \| 'inline'` | `'stacked'` | with `filter`, where `actions` sit below 768px: `'stacked'` gives them a row above the search; `'inline'` keeps them on the search's row (the search takes the room left), for a lone icon action such as a "+". An action wider than 3.5rem wraps under the search. From 768px both are the same. With a cards or tiles list on a phone, neither applies: [the two-row header](#the-phone-header-of-a-list-in-cards-or-tiles) puts the actions on its second row |
+| `surface` | `'card' \| 'none'` | `'card'` | the list's own surface: `'card'` a translucent background and 16px of padding (below 768px neither: the layout owns the page gutter and the tiles sit at it, so a `ServerTable` outside a layout that adds a gutter now sits flush with the screen edge below 768px and the caller wraps it in its own padding); `'none'` neither, for a `ServerTable` placed in a `Card`, a page section or any surface that already frames it, so the screen shows one surface, not a frame inside a frame (the tiles keep their own grouped border) |
 | `filterRef` | `Ref<ServerTableFilterHandle>` | — | with `filter`: `filterRef.current.focus()` focuses the Filter's first control, the search, else the first quick filter, "Add filter" or "Filters (N)" the width shows |
 | `sorting` | `createSorting(…)` | — | headers sorted from the URL; without it, no column is sortable (the server sorts, so pass `sorting` to let people sort), and the phone list bar shows only for selection |
 | `filters` | `tableFilters(model)` | — | without `filter`: "nothing matches" and its clear |
-| `empty` | `ServerTableEmpty`: `{ none, noMatch, clear?, headingLevel?, iconStyle? }` | — | the empty page: `none` and `noMatch` are a title or a `ListEmptyPage` (`{ title, description?, illustration?, action? }`); `headingLevel` (default 2) is the level of its title and of the error's; `iconStyle` styles the scenes (see below) |
+| `empty` | `ServerTableEmpty`: `{ none, noMatch, clear?, headingLevel?, iconStyle? }` | the `DataTable` default ("No data available", or "No results" when filtered) | the empty page. Leave it out when your page answers "nothing yet" and "nothing matches" itself and renders the table only when there are rows; the failure with Retry and the page past the last show either way. When given: `none` and `noMatch` are a title or a `ListEmptyPage` (`{ title, description?, illustration?, action? }`); `headingLevel` (default 2) is the level of its title and of the error's; `iconStyle` styles the scenes (see below) |
 | `error` | `ServerTableError \| null` | — | the fetch failed: the failure and a Retry replace the rows |
 | `onRetry` | `() => unknown` | — | the error's Retry; a returned promise keeps it loading |
 | `onClearFilters` | `() => void` | focus the table | without `filter`, after "clear" |
@@ -1054,7 +1055,17 @@ Its props are `ServerTableProps<T>`; `filter` is a `ServerTableFilter`,
 | `pageHref` | `(params) => string` | `` `?${params}` `` | Previous / Next hrefs |
 | `pagingNames` | `{ after?, trail? }` | `after`, `trail` | the cursor's params |
 | `resultsLabel` | `(count) => string` | "N results" | without `filter`: what the list's region says. The page past the last has its own words: `material.server-table.past-end`, `past-end-hint`, `first-page` and `past-end-status` |
-| `className` | `string` | — | on the list's surface |
+| `className` | `string` | — | on the list's surface (below 768px the list has no padding or background of its own) |
+
+A `ServerTable` in a `Card` shows one surface with `surface="none"`:
+
+```tsx
+<Card>
+  <CardContent>
+    <ServerTable {...props} surface="none" />
+  </CardContent>
+</Card>
+```
 
 ```tsx
 // A lone icon action stays on the search's row on a phone.
@@ -1936,8 +1947,13 @@ function Notifications({ items }: { items: Notification[] }) {
   the loader's own; see [A field's default](#a-fields-default)),
   `resultCount`, `loading`; every other prop of `Filter variant="bar"`
   (`quick`, `counts`, `previewCount`, `fieldProps`, `density`, `shortcuts`,
-  `searchApply`, `searchMinLength`, `errors`, `label`...) passes through. There is no `query`,
+  `searchApply`, `searchMinLength`, `searchAutoFocus`, `errors`, `label`...) passes through. There is no `query`,
   `defaultQuery` nor `onQueryChange`: the URL is the query.
+- **Focus on arrival.** `searchAutoFocus` puts focus in the search field when
+  the bar mounts (React's `autoFocus`, so it is right on the server too). Use it
+  on a search page reached with an empty query; leave it off on a list page,
+  where it would take focus from the page. `/` still focuses the field. `ServerTable`'s `filter` does not take
+  `searchAutoFocus`, on purpose: a list page should not steal focus.
 - **One write.** An edit writes the search, every `f=` and the aliased params,
   drops the `reset` ones and keeps the page's others (a tab, a sort).
   `onParamsChange` receives the next params for your router; the bar then

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

@@ -14,6 +14,8 @@ centre.
 | <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-unsaveddialog.webp" width="96" alt=""> | [UnsavedDialog](#unsaveddialog) | "Leave without saving?": a destructive confirm with Stay focused, used by the unsaved-changes guards |
 | <img src="../previews/feedback-status-stalenotice.webp" width="96" alt=""> | [StaleNotice](#stalenotice) | "This record changed": a warning that another write came first, with one Reload action and no overwrite |
+| | [Celebration](#celebration) | A one-shot confetti burst for a win or a reveal: plays once, never loops, theme colours, nothing under reduced motion |
+| | [Moment](#moment) | A full-screen one-off announcement (a player is eliminated, a role revealed): illustration, title, description and action, dismissed by Escape, a tap, its action or a timer |
 | <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-pageloadfailed.webp" width="96" alt=""> | [PageLoadFailed](#pageloadfailed) | An empty state for a page opened at a cursor that failed, with a link back to the start |
 | <img src="../previews/feedback-status-errorstate.webp" width="96" alt=""> | [ErrorState](#errorstate) | Failure block with Retry and technical details |
@@ -522,6 +524,69 @@ import { UnsavedDialog } from '@nxgt/material/components';
 
 ---
 
+## Celebration
+
+A one-shot confetti burst for a win or a reveal. It plays once when it mounts and again only when `trigger` changes. It never loops: the pieces fly out, fall and fade once, then are removed from the DOM. They are painted with theme tokens (`--primary`, `--secondary`, `--success`, `--info`, `--warning`), sit in a full-screen layer that ignores the pointer, and are `aria-hidden`. Under `prefers-reduced-motion` it renders nothing; it renders nothing on the server either.
+
+```tsx
+import { Celebration } from '@nxgt/material/components';
+
+{winner && <Celebration trigger={round} onComplete={() => startNextRound()} />}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `trigger` | `unknown` | — | plays the burst again when its value changes |
+| `pieces` | `number` | `48` | how many pieces fly out |
+| `duration` | `number` (ms) | `2400` | length of one burst |
+| `onComplete` | `() => void` | — | called once when a burst has ended |
+| `className` | `string` | — | on the full-screen layer |
+
+It is decorative: say what happened in text (a `Moment`, an alert). It pairs with `Moment` for a win screen.
+
+**Storybook:** `Feedback & status/Celebration` · **Vue:** not yet (#2272)
+
+---
+
+## Moment
+
+A transient full-screen announcement for a dramatic one-off event: a player is eliminated, a role is revealed. It is a modal dialog named by its `title` (and described by its `description`), so a screen reader announces it as it opens. Focus moves into it and goes back to the element that had it when it closes; the page behind is inert. Escape, a tap anywhere, the close button and the `action` dismiss it, and so does `duration`. It fades in and its picture pops in; under `prefers-reduced-motion` both stop. The surface is the tone's container with the foreground colour on it, so it holds AA in light and dark, and it fills a phone.
+
+```tsx
+import { Moment } from '@nxgt/material/components';
+import { Illustration } from '@nxgt/material/illustrations';
+
+<Moment
+  open={eliminated != null}
+  onOpenChange={(open) => !open && setEliminated(null)}
+  duration={6000}
+  tone="error"
+  illustration={<Illustration scene="error" />}
+  title={`${eliminated?.name} was eliminated`}
+  description="The village chose her. She was the seer."
+  action={<Button onClick={nextNight}>Next night</Button>}
+/>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `open` | `boolean` | — | shown or not (controlled) |
+| `onOpenChange` | `(open: boolean) => void` | — | called with `false` on every dismissal |
+| `duration` | `number` (ms) | — | dismisses by itself after this long; unset: stays until dismissed |
+| `illustration` | `ReactNode` | — | the picture (a scene, a pictogram, an icon); decorative, hidden from assistive technology |
+| `title` | `ReactNode` | — | what happened; the accessible name |
+| `description` | `ReactNode` | — | the line under it, in a `<p>` (phrasing content only) |
+| `action` | `ReactNode` | — | a button or link; its click dismisses after its own handler, unless that handler calls `event.preventDefault()` |
+| `tone` | `Tone` | `neutral` | the colour of the meaning: a named tone or one of your `AppTones` |
+| `closeLabel` | `string` | translated | name of the close button |
+| `className` | `string` | — | on the full-screen surface |
+
+A tap anywhere dismisses, so keep text a reader must act on out of a short `duration`. Without a `description` the dialog is described by the hint `material.moment.hint` ("Press Escape or tap to dismiss."), read by assistive technology only. The close button is named by `material.buttons.close`.
+
+**Storybook:** `Feedback & status/Moment` · **Vue:** not yet (#2248)
+
+---
+
 ## StaleNotice
 
 ![StaleNotice](../previews/feedback-status-stalenotice.webp)
@@ -855,6 +920,9 @@ import { CountdownTimer } from '@nxgt/material/components';
 // `criticalAt`); change (both tones) or hide the words:
 <CountdownTimer duration={300} warningText="Hurry up" />;
 <CountdownTimer duration={300} warningText={false} />;
+
+// The focal point of a screen:
+<CountdownTimer duration={300} size="lg" />;
 ```
 
 | Prop | Type | Default | Effect |
@@ -865,7 +933,7 @@ import { CountdownTimer } from '@nxgt/material/components';
 | `warningAt` / `criticalAt` | `number` | a quarter (≤ 60 s) / a tenth (≤ 10 s) | the seconds left when it turns amber / red |
 | `label` | `string` | `'Time remaining'` | its name |
 | `warningText` | `string \| false` | `'Little time left'` / `'Almost out of time'` | the words shown with a clock icon in the warning and critical tones, so low time is not told by colour alone; a string replaces both phrases; `false` hides them |
-| `size` | `'sm' \| 'md'` | `'md'` | 28 or 36 px high |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 28, 36 or 56 px high; `lg` is for a countdown that is the focal point of a screen (centred in a ring of seats, a full-screen exam) |
 
 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

package/docs/components/form-fields.md

@@ -381,8 +381,15 @@ that focuses the first refused row's text input: the row of the first
 built-in blank rule refused the list. An error on the list itself (too few
 rows, no row marked) focuses its first control. So `shouldFocusError`,
 `setFocus('choices')` and `setError('choices', …, { shouldFocus: true })` land
-on the refused row when there is an error, and on the first control otherwise;
-the form needs no `[aria-invalid="true"]` lookup.
+on the refused row when there is an error, and on the first control otherwise.
+A row path works too: `setFocus('choices.1.text')` and
+`setError('choices.1.text', …, { shouldFocus: true })` (a server's refusal)
+focus that row's text input. The form needs no `[aria-invalid="true"]` lookup.
+
+```tsx
+// After the server refused the second row:
+form.setError('choices.1.text', { message }, { shouldFocus: true });
+```
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -580,6 +587,13 @@ plain-text `label`, else from `aria-label`; with neither (a field named only
 through `aria-labelledby` included), the buttons keep the bare "Increase" /
 "Decrease".
 
+**Stepper tooltips.** Each +/− button shows its name in a tooltip on hover and
+on keyboard focus (`:focus-visible`). Focus that a script moves onto it, such
+as a `Sheet` or `Dialog` putting its initial focus on the first tabbable
+control, does not open the tooltip once the user has used the pointer (the browser does not treat that focus as `:focus-visible`), so it does not cover the field's label. The
+buttons stay in the tab order and keep their accessible names. `QuantityField`
+shares this (React only; the Vue steppers are unchanged, #2264).
+
 **Decimal separator.** After blur (and after +/−) the value is shown with the
 active language's separator, from `I18nProvider`: `1,5` in French, `1.5` in
 English (no grouping, so it stays editable). Typing accepts both: `1,5` and
@@ -663,7 +677,7 @@ Without a form library, `QuantityField` takes `value` and `onChange` (or
 `defaultValue`). The number is the one `NumberField` has: the language's
 decimal separator, `min`, `max` and `step` (clamped on blur), and steppers
 named after the field ("Increase Dose"). Both parts stay on one line on a
-phone: the number shrinks, the unit keeps a fixed 7rem.
+phone: the number shrinks, the unit is sized to its longest label (see Unit width below).
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -683,6 +697,11 @@ phone: the number shrinks, the unit keeps a fixed 7rem.
   is a textbox named after the label, the unit a combobox (or, with
   `allowCustomUnit`, a text input) named "Dose unit". The message describes
   the group, the number and the unit, and both are `aria-invalid` on an error.
+- **Unit width:** the unit part is sized to the longest label of `units`
+  (never under 7rem, never over 55% of the row, so the number keeps room at
+  360px). Beyond the cap the label is cut with an ellipsis and the full label
+  is the select's `title` (the `units` select only; a free unit typed past
+  the cap scrolls in its input). No inline style is used for it.
 - **Translations:** `material.quantity-field.unit` and `.unit-named` (English
   and French) name the unit part.
 

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

@@ -987,7 +987,7 @@ import { Background, Card } from '@nxgt/material/components';
 It fills the viewport; pass a `className` such as `h-96 w-full` to use it as a band.
 It is plain CSS from `styles.css`, with no inline `style`, and its colours lift
 in dark. `ActivityLayout` and `ThreadLayout` sit on it. The superset with `grain`,
-`seed`, `fill`, `motif` and the other presets (light, geometry and motif families) is `Background` from `/backgrounds`; see the [backgrounds guide](../guides/backgrounds.md). Light presets there: `mesh`, `aurora`, `spotlight`, `bokeh`, `rays`, `halo`, `plasma`, `glass`, `ripples`, `blobs`, `paper`, `linen`, `concrete`, `marble`, `grain`; geometry: `isometric`, `blueprint`, `dots`, `stripes`, `low-poly`, `topography`, `waves`, `hexagons`, `circuit`, `graph-paper`, `checker`, `diagonal-checker`, `chevrons`; motifs: `shapes`, `confetti-grid`, `constellation`, `halftone`, `truchet`, `floating`, `scatter-icons`, `school`, `night-sky`, `bubbles`, `leaves`, `science`, `music`, `travel`, `sport`, `moon`; sky: `eclipse`, `meteor-shower`, `ringed-planet`, `northern-lights`, or the `sky` prop to lay the moon or one of them over any preset.
+`seed`, `fill`, `motif` and the other presets (light, geometry and motif families) is `Background` from `/backgrounds`; see the [backgrounds guide](../guides/backgrounds.md). Light presets there: `mesh`, `aurora`, `spotlight`, `bokeh`, `rays`, `halo`, `plasma`, `glass`, `ripples`, `blobs`, `paper`, `linen`, `concrete`, `marble`, `grain`; geometry: `isometric`, `blueprint`, `dots`, `stripes`, `low-poly`, `topography`, `waves`, `hexagons`, `circuit`, `graph-paper`, `checker`, `diagonal-checker`, `chevrons`; motifs: `shapes`, `confetti-grid`, `constellation`, `halftone`, `truchet`, `floating`, `scatter-icons`, `school`, `night-sky`, `bubbles`, `leaves`, `science`, `music`, `travel`, `sport`, `moon`; sky: `eclipse`, `meteor-shower`, `ringed-planet`, `northern-lights`, `day-sky`, `dawn-sky`, or the `sky` prop to lay the moon or one of them over any preset.
 
 **Storybook:** `Navigation & layout/Background` · **Vue:** `Background`
 

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

@@ -641,7 +641,7 @@ in a desktop application.
 
 ![Command](../previews/overlays-menus-command.webp)
 
-Command palette with filtering, groups and shortcuts. `CommandDialog` shows it in a modal.
+Command palette with filtering, groups and shortcuts. `CommandDialog` shows it in a modal, with a visible close button (`showCloseButton`, on by default; `false` removes it) at the end of the input row: named "Close" (`material.buttons.close`) and 44px on a coarse pointer, since a phone has no Escape key.
 
 ```tsx
 import {
@@ -700,6 +700,7 @@ children and they replace that, as before.
 | `shouldFilter` (`Command`) | `boolean` | `true` | `false` when you filter the items yourself (server search) |
 | `title` / `description` (`CommandDialog`) | `string` | `"Command Palette"` / `"Search for a command to run..."` (translated) | the dialog's title and description, inside the dialog and visually hidden |
 | `mobilePresentation` (`CommandDialog`) | `'dialog' \| 'top' \| 'fullscreen'` | `'top'` | below 640 px: pinned under the top edge (so the input and the results stay above the on-screen keyboard), the whole screen, or the centred modal it was before |
+| `showCloseButton` (`CommandDialog`) | `boolean` | `true` | a visible close button at the end of the input row, named `material.buttons.close` and 44 px on a coarse pointer; `false` leaves Escape and the backdrop |
 | `commandProps` (`CommandDialog`) | `Pick<CommandProps, 'shouldFilter' \| 'value' \| 'onValueChange' \| 'loop' \| 'filter' \| 'label'>` | — | reaches the inner `Command`: `{ shouldFilter: false }` for a palette whose results come from a server (cmdk then does not hide them again by the typed text), `value` / `onValueChange` for the highlighted item, `label` for the input's accessible name. The input's sizing, the dialog's title and its focus stay as they are |
 | `open`, `onOpenChange` (`CommandDialog`) | as `Dialog` | — | every other prop goes to the `Dialog` |
 

package/docs/components/primitives.md

@@ -739,8 +739,8 @@ reached with the arrow keys. The list scrolls sideways when the tabs do not
 fit (its scrollbar hidden), which suits a phone or a narrow popover. While it
 overflows, each side with hidden tabs fades and gets a small scroll button
 ("Scroll tabs left" / "Scroll tabs right", from `material.tabs.*`; out of the
-tab order; on a touch screen 44px wide and as tall as the list, so it never covers content); the selected and the focused tab are
-scrolled into view, instantly under reduced motion. A list that fits has
+tab order; on a touch screen 44px wide and as tall as the list, so it never covers content). Under a button the list shows nothing (its edge mask is transparent there and fades in just beyond), so no label is ever cut by the button, even at 375px; the selected and the focused tab are
+scrolled into view clear of the button, instantly under reduced motion. A list that fits has
 neither, and neither is in the server markup. `segmented` does the same.
 
 **`segmented`** is a neutral pill track: the active tab sits on a raised

package/docs/components/rich-widgets.md

@@ -135,7 +135,7 @@ import {
 | `ChatActionProposal` `busy` / `disabled` | `boolean` | `false` | an answer is being sent (both disabled, Confirm spins) / a read-only viewer |
 | `ChatActionProposal` `deadline` | `Date \| string \| number` | — | "Respond by …" in a `<time>`, in the active language; `expired` says "Expired on" |
 | `ChatActionProposal` `failureCode` / `failureMessage` | `string` / `ReactNode` | — | a `failed` card's reason, in an `alert`, with the code |
-| `ChatToolActivity` `name` / `state` / `detail` | `ReactNode` / `'running' \| 'ok' \| 'failed'` / `ReactNode` | — / `'running'` | one compact row for a tool step in a `ChatMessageList`: the name in mono, Running (spinner), Done or Failed |
+| `ChatToolActivity` `name` / `nameText` / `state` / `detail` | `ReactNode` / `string` / `'running' \| 'ok' \| 'failed'` / `ReactNode` | — / — / `'running'` | one compact row for a tool step in a `ChatMessageList`: the name in mono, wrapped onto two lines at most with its full text in a `title` (`nameText` gives it when `name` is a node), then Running (spinner), Done or Failed |
 | `ChatThread` / `ChatMessageList` `layout` | `'bubbles' \| 'flat'` | `'bubbles'` | a messenger's bubbles, or a team chat's rows (name and time over each run) |
 | `ChatThread` / `ChatMessageList` `density` | `'comfortable' \| 'compact'` | `'comfortable'` | tighter bubbles, smaller avatars |
 | `ChatMessageList` `viewportProps` | `ComponentProps` of the viewport | `{ tabIndex: 0 }` | attributes of the scrolling element; it is a tab stop so the keyboard can scroll the transcript (`tabIndex: -1` opts out) |
@@ -148,8 +148,9 @@ import {
 | `ChatComposer` `onStop` | `() => void` | — | while `isLoading`, send becomes stop (an assistant answering) |
 | `ChatComposer` `sendOnEnter` | `boolean` | `true` | Enter sends and Shift+Enter breaks the line; `false`: Ctrl/⌘+Enter sends. Never while an IME composes |
 | `ChatComposer` `emojis` / `mentions` | `EmojiItem[]` / `MentionItem[]` | — | enables the emoji picker and the `@` list |
-| `ChatThreadHeader` | `title`, `subtitle`, `avatarSrc`, `status`, `actions`, `onBack` | — | the title bar; inside a `ChatInbox` it carries the back button on a narrow screen |
+| `ChatThreadHeader` | `title`, `subtitle`, `titleText`, `subtitleText`, `avatarSrc`, `status`, `actions`, `onBack` | — | the title bar; inside a `ChatInbox` it carries the back button on a narrow screen. The title is clamped to two lines and the subtitle truncated, each with its full text in a `title` attribute; `titleText` / `subtitleText` give that text when `title` / `subtitle` is a node |
 | `ChatConversationItem` `title` / `titleText` | `ReactNode` / `string` | — | the clipped title carries its full text in a `title` attribute when it is a string; `titleText` gives it when `title` is a node |
+| `ChatConversationItem` width | — | — | fills its container (`w-full`) and has no intrinsic width (`contain: inline-size`), so a long title never widens an auto-sized grid track and the timestamp stays whole; a shrink-to-fit parent (`w-fit`, `max-content`, an inline-flex wrapper, a popover sized to content) must give it a width |
 | `ChatConversationItem` `status` / `isTyping` | `StatusTone` / `boolean` | — | presence dot; "Typing…" instead of the preview |
 | `ChatInbox` `pane` / `defaultPane` | `'list' \| 'thread'` | `'list'` | which pane shows below the `@md` container width |
 | `ChatWidget` `open` / `defaultOpen` / `onOpenChange` | `boolean` | `false` | the floating launcher's panel (full screen below `sm`); `unreadCount` on the launcher, `side`, `strategy` |

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

@@ -846,7 +846,7 @@ export function Topics() {
 | `options` | `{ value; label; icon?; count?; description?; disabled?; disabledReason? }[]` | — | the chips, in one flow; `count`: see [option counts](#option-counts) |
 | `groups` | `{ label: string; options }[]` | — | titled sections instead of `options` (it wins when both are given): see [slot picker](#slot-picker-columns-groups-and-reasons) |
 | `columns` | `number \| { base?; sm?; md?; lg? }` | — | equal-width columns (1 to 12; one count per breakpoint, each holding to the next); Up and Down then move by row. Unset, the chips flow and wrap |
-| `showDisabledReason` | `boolean` | `true` | prints a disabled option's `disabledReason` under its chip; `false` leaves it to the tooltip and the accessible description |
+| `showDisabledReason` | `boolean` | `true` | prints a disabled option's `disabledReason` below the whole group ("Label: reason"), so the chip row keeps its wrapping; `false` leaves it to the tooltip and the accessible description |
 | `size` | `'default' \| 'sm' \| 'lg'` | `'default'` | the chip's size: 28px, 24px, or `lg`, a 44px box at every pointer (a coarse pointer already gets a 44px box at any size) |
 | `name` | `string` | — | put on every chip (`ChipGroupFormField` passes its field `name`), so `document.getElementsByName(name)` finds the group's chips in order |
 | `label`, `helperText`, `error`, `required`, `disabled`, `id` | | — | the question and its help or error text, the required mark, disabling every chip, the group's `id` |
@@ -894,7 +894,7 @@ export function Slots() {
 }
 ```
 
-- **Disabled reason.** The reason is a small muted line under the chip (not
+- **Disabled reason.** The reason is a small muted line below the whole group, as "Label: reason" (not
   only a tooltip), and the chip points to it with `aria-describedby`, so a
   screen reader says "09:30, Taken". The chip stays `aria-disabled`, not
   `disabled`: arrows still land on it and a press does nothing. The "up to N"
@@ -918,7 +918,7 @@ single mode), Home and End jump, and the arrows follow `dir="rtl"`; Space toggle
 mode; Enter does nothing, so it never submits a surrounding form. One chip holds
 the tab stop. A disabled option, or an unchosen one once `max` is reached, is
 `aria-disabled`: it stays focusable and an arrow stop, a press does nothing,
-and its `disabledReason` is printed under the chip (unless
+and its `disabledReason` is printed below the whole group, outside the chip row (unless
 `showDisabledReason={false}`, then its tooltip) and is its accessible description
 (as is `description`). The group's label shows the required mark when `required`; in
 multiple mode, where a `group` cannot carry `aria-required`, the group is

package/docs/getting-started.md

@@ -144,7 +144,7 @@ and need nothing.
 | `@nxgt/material/editor/viewer` | `RichTextViewer`: shows a saved document (HTML, JSON or Markdown) read-only. **Server-safe**: no editor instance, no `'use client'` ([RichTextViewer](components/rich-widgets.md#richtextviewer)) |
 | `@nxgt/material/editor/collab` | `collaboration()`: several people editing one `DocumentEditor` through a Yjs document and provider your app supplies. Needs `yjs` and `y-protocols` ([Collaboration](components/rich-widgets.md#collaboration)) |
 | `@nxgt/material/editor/pm` | The editor's own tiptap and ProseMirror classes (`Extension`, `Node`, `Plugin`, `PluginKey`, `TextSelection`, `ProseMirrorNode`, `Fragment`, `DecorationSet`, …) for a custom feature's extensions, so `instanceof` agrees with the editor. Shares the editor's code; **server-safe** ([A custom feature](components/rich-widgets.md#a-custom-feature)) |
-| `@nxgt/material/backgrounds` | Background presets: `Background` (a superset of the `/components` one: `preset` (50 ids, `AVAILABLE_BACKGROUND_PRESETS`), `tone`, `intensity`, `animated`, `grain`, `seed`, `fill`, `sky`, `motif` (`shapes`, `density`, `size`, `rotate`, `shapeFill`, `opacitySpread`) and, for `preset="icons"`, `icons`, `iconStyle` and `iconMotif`), and the types and tables re-exported from `@nxgt/material-core/backgrounds`. **Its own entry**, with an opt-in stylesheet ([backgrounds](guides/backgrounds.md)) |
+| `@nxgt/material/backgrounds` | Background presets: `Background` (a superset of the `/components` one: `preset` (52 ids, `AVAILABLE_BACKGROUND_PRESETS`), `tone`, `intensity`, `animated`, `grain`, `seed`, `fill`, `sky`, `motif` (`shapes`, `density`, `size`, `rotate`, `shapeFill`, `opacitySpread`) and, for `preset="icons"`, `icons`, `iconStyle` and `iconMotif`), and the types and tables re-exported from `@nxgt/material-core/backgrounds`. **Its own entry**, with an opt-in stylesheet ([backgrounds](guides/backgrounds.md)) |
 | `@nxgt/material/media-hls` | `hlsStreaming()`: the HLS adapter for `MediaPlayer`, `hls.js` loaded lazily ([streaming](guides/media-streaming.md)) |
 | `@nxgt/material/vite` | Build-time helper for consumers: `pdfkitStandardFonts()` ([printing](guides/printing.md#bundling-print-into-an-ssr-server)) |
 | `@nxgt/material/hooks` | `useTheme`, `useIsClient`, `useIsMobile`, `useLocalizedDate`, … ([helpers](guides/helpers.md#nxgtmaterialhooks)) |

package/docs/guides/app-shell.md

@@ -639,7 +639,7 @@ to know the theme on the server (a cookie, passed to `defaultTheme`).
 ## Use a background preset behind the shell
 
 The shell draws the gradient with three blurred blobs behind its frame. To use
-one of the 50 presets of `@nxgt/material/backgrounds` instead, pass it as
+one of the 52 presets of `@nxgt/material/backgrounds` instead, pass it as
 `backdrop` (behind the shell its shapes show only in empty space, see [Where the shapes go](#the-themes-background)):
 
 ```tsx