@nxgt/material 2.7.1 → 2.9.0

package/dist/{vennDiagram-UO4OBE2U-CO0yFCI8.js → vennDiagram-UO4OBE2U-BpgP__1T.js}

@@ -1,8 +1,8 @@
-import { t as e } from "./src-C9kQSo6K.js";
-import { i as t } from "./chunk-ZIGJFQKS-C3xUAXJq.js";
+import { t as e } from "./src-CsLQInsN.js";
+import { i as t } from "./chunk-ZIGJFQKS-9VXArDKF.js";
 import { n } from "./chunk-Y2CYZVJY-BAad7w_K.js";
-import { H as r, U as i, a, b as o, c as s, f as c, it as l, nt as u, q as d, rt as f, tt as p, v as m, w as h, y as g } from "./chunk-O7XYJQB3-A66QSOPA.js";
-import { t as _ } from "./chunk-6AEJRKK7-3YWRP4aV.js";
+import { H as r, U as i, a, b as o, c as s, f as c, it as l, nt as u, q as d, rt as f, tt as p, v as m, w as h, y as g } from "./chunk-O7XYJQB3-BChweQ_V.js";
+import { t as _ } from "./chunk-6AEJRKK7-BLBlw8ui.js";
 import { t as v } from "./rough.esm-Cvc79rxE.js";
 //#region ../../node_modules/khroma/dist/methods/transparentize.js
 var y = (e, t) => f(e, "a", -t), b = 1e-10;

package/dist/{wardleyDiagram-VNRHLVJA-QkwghAYo.js → wardleyDiagram-VNRHLVJA-CYqKMb2f.js}

@@ -1,9 +1,9 @@
-import { n as e } from "./src-C9kQSo6K.js";
-import { i as t } from "./chunk-ZIGJFQKS-C3xUAXJq.js";
+import { n as e } from "./src-CsLQInsN.js";
+import { i as t } from "./chunk-ZIGJFQKS-9VXArDKF.js";
 import { n } from "./mermaid-parser.core-BXD_TD1T.js";
 import { n as r } from "./chunk-Y2CYZVJY-BAad7w_K.js";
-import { D as i, H as a, U as o, a as s, b as c, c as l, q as u, v as d, w as f, x as p, y as m } from "./chunk-O7XYJQB3-A66QSOPA.js";
-import { t as h } from "./chunk-6AEJRKK7-3YWRP4aV.js";
+import { D as i, H as a, U as o, a as s, b as c, c as l, q as u, v as d, w as f, x as p, y as m } from "./chunk-O7XYJQB3-BChweQ_V.js";
+import { t as h } from "./chunk-6AEJRKK7-BLBlw8ui.js";
 import { t as g } from "./chunk-JWPE2WC7-BGVSGRTC.js";
 //#region ../../node_modules/mermaid/dist/chunks/mermaid.core/wardleyDiagram-VNRHLVJA.mjs
 var _ = /* @__PURE__ */ r((e, t) => {

package/dist/{xychartDiagram-PMCCYNJV-B2aZlrno.js → xychartDiagram-PMCCYNJV-b-Quuxoi.js}

@@ -1,11 +1,11 @@
-import { at as e, rt as t, st as n } from "./components-DrStgM4J.js";
-import { n as r } from "./src-C9kQSo6K.js";
-import { i } from "./chunk-ZIGJFQKS-C3xUAXJq.js";
+import { at as e, rt as t, st as n } from "./components-km60bAdr.js";
+import { n as r } from "./src-CsLQInsN.js";
+import { i } from "./chunk-ZIGJFQKS-9VXArDKF.js";
 import { n as a } from "./chunk-Y2CYZVJY-BAad7w_K.js";
-import { D as o, H as s, U as c, a as l, b as u, c as d, f, q as p, v as m, w as h, y as g, z as _ } from "./chunk-O7XYJQB3-A66QSOPA.js";
-import { t as v } from "./chunk-6AEJRKK7-3YWRP4aV.js";
-import "./chunk-742MDFTN-Cs1qGiTK.js";
-import { t as y } from "./chunk-MBY4JIJT-C3RQP_Nk.js";
+import { D as o, H as s, U as c, a as l, b as u, c as d, f, q as p, v as m, w as h, y as g, z as _ } from "./chunk-O7XYJQB3-BChweQ_V.js";
+import { t as v } from "./chunk-6AEJRKK7-BLBlw8ui.js";
+import "./chunk-742MDFTN-CsUjFyzK.js";
+import { t as y } from "./chunk-MBY4JIJT-BFIqOe-8.js";
 //#region ../../node_modules/mermaid/dist/chunks/mermaid.core/xychartDiagram-PMCCYNJV.mjs
 var b = (function() {
 	var e = /* @__PURE__ */ a(function(e, t, n, r) {

package/docs/components/buttons-and-actions.md

@@ -50,15 +50,63 @@ import { Mail } from 'lucide-react';
 | `variant` | `'filled' \| 'tonal' \| 'outlined' \| 'ghost' \| 'link'` | `'filled'` | the style |
 | `color` | `'primary' \| 'secondary' \| 'success' \| 'info' \| 'warning' \| 'error' \| 'default'` | `'primary'` | the colour; `default` is the foreground colour |
 | `size` | `'xs' \| 'sm' \| 'default' \| 'lg' \| 'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'` | — | height: 24, 32, 36 and 40 px; the `icon*` sizes are square, for a button holding only an icon (give it an `aria-label`). Unset, the button keeps its content's height, as before sizes existed |
-| `loading` | `boolean` | — | shows a spinner and swallows clicks (the button stays focusable) |
+| `loading` | `boolean` | — | busy: a spinner, `aria-busy="true"` and `aria-disabled="true"`, and every click cancelled — a submit button submits neither on a click nor on Enter in a field. It stays focusable (no native `disabled`), so focus is not lost |
+| `lockOnClick` | `boolean` | — | a click makes the button busy at once, until `loading` has turned true and back (or for one second when it never does): for a `loading` that turns true only after an `await` |
 | `spinnerVariant` | `SpinnerProps['variant']` | `'2'` | which spinner `loading` shows |
+| `wrap` | `boolean` | — | the label breaks onto as many lines as it needs, centred, instead of being cut with “…”: the button grows taller, never shorter than its `size`. Ignored by the `icon*` sizes |
 | `tooltip` | `string` | — | wraps the button in a `Tooltip` |
 | `asChild` | `boolean` | `false` | styles its only child instead of rendering a `<button>` |
 | `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | not `submit` by default — pass it inside a form |
 
 The classes are exported as `buttonVariants` for styling your own element.
 
-**Storybook:** `Buttons & actions/Button` · **Vue:** `Button`
+**On a phone.** A button is never wider than its container, and keeps its
+content's width in a column: a label too
+long for it (a card on a phone) is cut with “…” on one line, and its
+accessible name — and a `title` you give it — keep the whole text. Give a
+label that must be read in full `wrap`, or a width of your own (`w-full`).
+The text is put in a `<span data-slot="button-label">` (one per run of
+text) that shrinks and ends in the ellipsis; it needs the text to be the button's own child; with `asChild`,
+put the label in a `<span>` inside the child element.
+
+```tsx
+<Button title="Continue to the payment details">Continue to the payment details</Button>;
+<Button wrap>Continue to the payment details and confirm the order</Button>;
+```
+
+**Submitting once.** Give a submit button `loading={formState.isSubmitting}`:
+React Hook Form sets it as `handleSubmit` starts, so the button is busy from
+the first click and a double click, or Enter pressed twice, submits once.
+When `loading` comes from something that turns true later — a mutation's
+`isPending` after an async resolver — the second click comes first: add
+`lockOnClick`.
+
+```tsx
+<form onSubmit={handleSubmit(onSubmit)}>
+	<EmailFormField control={control} name="email" label="Email" />
+	<Button type="submit" loading={formState.isSubmitting}>
+		Sign in
+	</Button>
+</form>;
+
+<Button type="submit" loading={mutation.isPending} lockOnClick>
+	Sign in
+</Button>;
+```
+
+**What the guard covers.** Clicks on this button, Space and Enter on it,
+and Enter in a field when it is the form's first submit button (the default
+one, which the browser clicks). `form.requestSubmit()` and `form.submit()`
+fire no click, so a submit your code starts — an OTP step that submits on its
+last digit, a keyboard shortcut — must check `formState.isSubmitting` itself.
+With `lockOnClick`, a `loading` that never turns true releases the lock after
+one second.
+
+A test finds a busy button by its state, not by `disabled`:
+`expect(button).toHaveAttribute('aria-busy', 'true')` (`toBeDisabled()` is
+false: it is still focusable).
+
+**Storybook:** `Buttons & actions/Button` (`Submits Once`, `Lock On Click`), `Buttons & actions/Button/Phone` · **Vue:** `Button`
 
 ---
 
@@ -179,7 +227,7 @@ import {
 | --- | --- | --- | --- |
 | `menu` | `ReactNode` | — (required) | the `DropdownMenu*` items shown by the chevron |
 | `menuLabel` | `string` | `"More actions"` (translated) | the chevron's `aria-label` |
-| `variant`, `color`, `loading`, `disabled` | as `Button` | — | applied to both halves; `loading` also disables the chevron |
+| `variant`, `color`, `loading`, `disabled` | as `Button` | — | `variant`, `color` and `disabled` apply to both halves; `loading` makes the main half busy (spinner, clicks ignored, still focusable) and disables the chevron (native `disabled`) |
 
 Other `Button` props (`onClick`, `type`…) go to the main half.
 
@@ -191,7 +239,7 @@ Other `Button` props (`onClick`, `type`…) go to the main half.
 
 ![ResponsiveButton](../previews/buttons-actions-responsivebutton.webp)
 
-Shows its label on desktop and collapses to icon-only on mobile, keeping the label for screen readers.
+Shows its label from 768 px up and collapses to icon-only below, keeping the label for screen readers. The collapse is a CSS media query, not a JS effect, so the server HTML is the same everywhere and nothing flashes.
 
 ```tsx
 import { ResponsiveButton } from '@nxgt/material/components';
@@ -203,9 +251,10 @@ import { Plus } from 'lucide-react';
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `icon` | `ReactNode` | — (required) | always shown |
-| `expanded` | `boolean` | not mobile (`useIsMobile`) | shows the label, or keeps it as screen-reader text only |
+| `expanded` | `boolean` | by width (`max-md` CSS) | `true` or `false` forces the label shown, or kept as screen-reader text only, at every width |
 
-Every `Button` prop applies. Collapsed, the label is still in the button as
+Every `Button` prop applies. The label is always in the DOM, so the accessible
+name is the same at every width; collapsed, it is
 `sr-only` text, so the icon-only button keeps its accessible name; no
 `aria-label` is needed. `expanded` is layout, not disclosure: the button has
 no `aria-expanded` of its own, so it is not announced as "collapsed". Wrapped
@@ -263,7 +312,7 @@ Needs a `react-router` router above it.
 
 ![CopyButton](../previews/buttons-actions-copybutton.webp)
 
-Copies a value to the clipboard and briefly shows a check mark. `CopyValue` displays the value next to the button.
+Copies a value to the clipboard and briefly shows a check mark (or a cross when the clipboard refuses). `CopyValue` displays the value next to the button.
 
 ```tsx
 import { CopyButton, CopyValue } from '@nxgt/material/components';
@@ -277,12 +326,13 @@ import { CopyButton, CopyValue } from '@nxgt/material/components';
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `value` | `string \| (() => string)` | — (required) | what is copied; a function is read at click time |
-| `label` / `copiedLabel` | `string` | `"Copy"` / `"Copied"` (translated) | tooltip and `aria-label`, before and after |
+| `label` | `string` | `"Copy"` (translated) | the button's accessible name; it never changes after a click |
+| `copiedLabel` / `failedLabel` | `string` | `"Copied"` / `"Copy failed"` (translated) | announced in the status region (and shown in the tooltip) once the write succeeded or failed |
 | `icon` | `ReactNode` | a copy icon | replaces the idle icon |
 | `variant`, `color` | as `IconButton` | `'ghost'`, `'default'` | the button style |
 | `display` (`CopyValue`) | `ReactNode` | `value` | what is shown, when it differs from what is copied |
 
-The check mark stays for 1.5 s.
+The write is awaited: "Copied" appears only once the clipboard accepted the text, and a refusal (no permission, an insecure page, no Clipboard API) shows "Copy failed" instead. The outcome is announced through a visually hidden `role="status"` (polite) region rendered next to the button, not by renaming the button: `getByRole('button', { name: 'Copy' })` keeps matching, and a test reads the outcome with `within(button.parentElement!).getByRole('status')` (a bare `getByRole('status')` is ambiguous: every `CopyButton` renders a `status` region, and so do `Banner`, `DataTable` and the skeletons). The result stays for 1.5 s.
 
 **Storybook:** `Buttons & actions/CopyButton` · **Vue:** `CopyButton`, `CopyValue`
 
@@ -446,6 +496,6 @@ import { I18nProvider } from '@nxgt/material/i18n';
 | --- | --- | --- | --- |
 | `languages` | `Language[]` | the provider's `supportedLanguages` | which languages the menu lists |
 
-Disabled when no `I18nProvider` is mounted. See the [i18n guide](../guides/i18n.md).
+Its menu is non-modal (see [DropdownMenu](overlays-and-menus.md#dropdownmenu)). Disabled when no `I18nProvider` is mounted. See the [i18n guide](../guides/i18n.md).
 
 **Storybook:** `Buttons & actions/LanguageSwitcher` · **Vue:** `LanguageSwitcher`

package/docs/components/data-display.md

@@ -308,7 +308,9 @@ import { Description } from '@nxgt/material/components';
 ```
 
 `label` and `value` are its only props; the rest go to the `div`. A falsy
-`value` renders nothing, so optional fields need no guard.
+`value` renders nothing, so optional fields need no guard. The label is a small
+muted caption above the value (not a title). `Description` takes one cell of
+the grid it is in; pass `className="col-start-full"` for a full-width row.
 
 **Storybook:** `Data display/Description` · **Vue:** `Description`
 
@@ -358,12 +360,32 @@ import { ListTile } from '@nxgt/material/components';
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `href` | `string` | — | renders an `<a>` |
+| `linkComponent` | `AppShellLinkComponent` | plain `<a>` | the link element, as in the app shell: takes `href`, spreads every other prop, forwards `ref` |
 | `onClick` | `MouseEventHandler` | — | renders a `<button>` |
 | `selected` | `boolean` | `false` | highlighted row |
 | `size` | `'sm' \| 'md'` | `'md'` | `sm` is the dense navigation row |
 | `leading`, `trailing`, `subtitle` | `ReactNode` | — | slots |
 | `disabled` | `boolean` | — | disables the link or button |
 
+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):
+
+```tsx
+import { Link } from 'react-router';
+import type { AppShellLinkComponent } from '@nxgt/material/components';
+import { ListTile } from '@nxgt/material/components';
+
+// Hoisted: one component, not a new one on every render.
+const RouterLink: AppShellLinkComponent = ({ href, ...props }) => <Link to={href} {...props} />;
+
+export function SettingsLink() {
+  return <ListTile title="Notifications" href="/settings/notifications" linkComponent={RouterLink} />;
+}
+```
+
+See also [A `ListTile` link reloads the whole page](../troubleshooting.md#a-listtile-link-reloads-the-whole-page). A disabled tile never renders the link component: it is a plain `<a>` without `href`, with `aria-disabled="true"`.
+
+The root carries `data-slot="item-detail"` (a tile that is a button or a plain row too).
+
 **Storybook:** `Data display/ListTile` · **Vue:** `ListTile`
 
 ---
@@ -457,7 +479,7 @@ import { EventChip } from '@nxgt/material/components';
 
 ![CodeBlock](../previews/data-display-codeblock.webp)
 
-Highlighted code with line numbers and copy, a Monaco diff, a collapsible JSON tree, and tabbed samples (`Tabs variant="line"`).
+Highlighted code with line numbers and copy, a Monaco diff, a collapsible JSON tree, and tabbed samples (`Tabs`, underlined).
 
 <img src="../previews/data-display-codegroup.webp" height="96" alt="CodeGroup">
 <img src="../previews/data-display-jsonviewer.webp" height="96" alt="JsonViewer">

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

@@ -23,7 +23,7 @@ each other, so either can be used alone.
 
 ![DataTable](../previews/data-table-filter-lists-datatable.webp)
 
-TanStack Table v9 with sorting, filtering, selection, expandable rows, pagination or load-more, column visibility, skeleton rows while loading and your own empty state — or one server page at a time, with controlled sorting and selection, cursor Previous / Next links and row links.
+TanStack Table v9 with sorting, filtering, selection, expandable rows, pagination or load-more, column visibility, skeleton rows while loading and your own empty state — or one server page at a time, with controlled sorting and selection, cursor Previous / Next links and row links. On a phone it keeps its header row and scrolls sideways in a keyboard-reachable region; the page does not.
 
 ```tsx
 import {
@@ -72,14 +72,16 @@ table enables, for typing your own column defs.
 | `actions` | `(table) => ReactNode` | — | toolbar content with access to the table (selected rows…) |
 | `onLoadMore` / `isLoadingMore` | `() => void` / `boolean` | — | adds a "load more" button under the rows |
 | `options` | `{ showPage?: boolean; showSelected?: boolean }` | both `true` | parts of the footer |
-| `showHeader` | `boolean` | hidden on mobile | header row |
+| `showHeader` | `boolean` | shown | header row (column names, sorting, "Select all") at every width; `false` hides it |
+| `maxHeight` | `number \| string` | none | caps the table's height (`400`, `'60vh'`); the rows scroll inside it |
+| `scrollLabel` | `string` | "Scrollable table" | the name of the scroll region the table becomes while it overflows |
 | `loading` | `boolean` | `false` | skeleton rows, or the current rows dimmed; `aria-busy`; controls disabled |
 | `loadingRows` | `number` | the page size | how many skeleton rows |
 | `empty` | `ReactNode \| ({ filtered }) => ReactNode` | icon and "No data available" | content of the empty row, spanning every visible column |
 | `manual` | `boolean` | `false` | `data` is one server page: no client filtering, sorting or paging; the footer is the server footer ([server-side data](#server-side-data)) |
-| `sorting` / `onSortingChange` | `SortingState` / `(sorting) => void` | held inside | controlled sorting; the callback gets the new state, not an updater |
+| `sorting` / `onSortingChange` | `SortingState` / `(sorting) => void` | held inside | controlled sorting; the callback gets the new state, not an updater, and is not called for an update that resolves to the current value |
 | `getRowId` | `(row, index) => string` | the index | the row's id, the key of `rowSelection` |
-| `rowSelection` / `onRowSelectionChange` | `RowSelectionState` / `(selection) => void` | held inside | controlled selection, by id; may hold rows of other pages |
+| `rowSelection` / `onRowSelectionChange` | `RowSelectionState` / `(selection) => void` | held inside | controlled selection, by id; may hold rows of other pages; the callback is not called for an update that resolves to the current value |
 | `pagination` | `{ totalCount?, offset?, previous?, next? }` | — | the server footer's range ("41–60 of 133") and Previous / Next: an href (a link) or a callback (a button) |
 | `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 |
@@ -138,6 +140,69 @@ default, or your own content, told whether rows exist but none matches the
 filters (`filtered`); content that renders nothing gets the default.
 `DataTableEmpty` and `DataTableEmptyState` type the prop and its argument.
 
+### Phones and narrow screens
+
+```tsx
+// The rows scroll inside 60% of the viewport; the page scrolls otherwise.
+<DataTable
+  data={invoices}
+  columns={columns}
+  maxHeight="60vh"
+  scrollLabel="Invoices"
+/>
+```
+
+The table is as tall as its rows, and the page scrolls: there is no height
+cap unless you pass `maxHeight`, so a phone never gets a scroll inside the
+page's. The header row shows at every width (`showHeader` `false` hides it).
+With `maxHeight`, the rows scroll under the header row, which stays in view
+on an opaque background.
+
+When the columns are wider than the table, the table scrolls sideways in
+one box (`[data-slot="table-wrapper"]`), and the page does not. While it
+overflows, that box is a `region` named "Scrollable table"
+(`material.table.labels.scroll-region`, or `scrollLabel`) with
+`tabindex="0"`, so a keyboard user can reach it and scroll it with the arrow
+keys, and an edge fades on each side where columns are hidden
+(`data-scroll-start` / `data-scroll-end` on its parent,
+`[data-slot="table-scroll"]`). It is not a region while it fits, nor on the
+server; once focused, it stays a tab stop until focus leaves, even if it
+stops overflowing. The empty state is centred in the part of the table you
+can see (the box's measured width, `--table-visible-width`), not across its
+whole scroll width. The table needs no width from its parent: inside a
+content-sized one (`w-fit`, `inline-flex`, an `auto` grid track, a popover)
+it is as wide as its columns.
+
+The `select` column's checkboxes keep their 16px box, with a 24px target
+around it (WCAG 2.5.8). The toolbar renders only when it has content:
+`actions` that render nothing (`null`, `false`, whitespace, an empty
+fragment) leave no empty `<fieldset>` behind.
+
+Selection actions do not move the rows. With `actions` and the `select`
+column (`predefinedColumns().select`, id `select`), the toolbar's height is
+reserved — an empty, hidden placeholder
+(`[data-slot="header-placeholder"]`) while `actions` render nothing, the
+same minimum height once they do — so the "Delete selected" that appears on
+the first selection does not push the tapped row down. The reserved height
+is one row of default-size buttons (`h-9`); taller or wrapping actions still
+grow the toolbar.
+
+```tsx
+<DataTable
+  data={people}
+  columns={[select, ...columns]}
+  actions={(table) =>
+    table.getSelectedRowModel().rows.length > 0 && (
+      <Button onClick={handleDelete(table.getSelectedRowModel().rows)}>
+        Delete selected
+      </Button>
+    )
+  }
+/>
+```
+
+Rows stay rows on a phone; a card layout is not built in.
+
 ### Server-side data
 
 When the server filters, sorts and pages, hand the table **one page** and
@@ -249,12 +314,22 @@ export default function Students() {
   index of the page's first row) make the range: "41–60 of 133"
   (`material.table.pagination.range`), "41–60" without a total, "133 rows"
   without an offset. Cursor paging knows the offset from the trail's length
-  times the page size; leave it out if pages can be short.
+  times the page size; leave it out if pages can be short. The range is a
+  polite live region (`role="status"`, `aria-atomic="true"`, named "Rows
+  shown" by `material.table.pagination.range-label`) that is in the DOM from
+  the first render whenever `pagination` is given, so a screen reader
+  announces "41–60 of 133" when the page changes. With neither `offset` nor
+  `totalCount` the region is empty, and is kept in the DOM so a later change
+  is still announced. The table already has a visually hidden status for
+  "Loading data…" (and the page may have a toast region), so a test finds the
+  range with `getByRole('status', { name: 'Rows shown' })`, not a bare
+  `getByRole('status')`.
 - **Sorting** is controlled: the headers show `sorting`, and
   `onSortingChange` receives the new `SortingState` (not TanStack's updater)
-  for you to put in the URL. Filters work the same way: render them in
-  `actions` and keep their values in the URL; `manual` turns client
-  filtering off.
+  for you to put in the URL (neither it nor `onRowSelectionChange` is called
+  for an update that resolves to the current value). Filters work the same
+  way: render them in `actions` and keep their values in the URL; `manual`
+  turns client filtering off.
 - **Selection** is keyed by `getRowId`, so it survives a page change: ids
   of other pages stay in `rowSelection`, and the footer counts them all
   ("3 rows selected", `material.table.pagination.selected`). `actions(table)`
@@ -271,7 +346,10 @@ export default function Students() {
   navigation (opening a sheet). Alone, it makes the row focusable and Enter
   calls it; with `getRowHref`, the link stays the keyboard target, and
   calling `event.preventDefault()` in it stops a mouse click from following
-  the link. A focusable row has no role of its own: for anything a screen
+  the link. The row itself is never a second control: with `getRowHref` it
+  has no role, no `tabindex` and no `aria-label`, and the one link is named
+  by the cell's text, so `getByRole('link', { name: 'Ada', exact: true })`
+  is unique. A focusable row has no role of its own: for anything a screen
   reader user must reach, prefer `getRowHref` or a button in a cell.
 - **Your own footer.** `footer={(table) => …}` replaces the footer —
   `<DataTableServerFooter table={table} pagination={…} />` is the default
@@ -280,7 +358,7 @@ export default function Students() {
   navigation is pending, and the current rows stay in place, dimmed.
 
 The server footer's strings are `material.table.pagination.*`
-(`previous`, `next`, `label`, `range`, `range-open`, `total`, `selected`),
+(`previous`, `next`, `label`, `range`, `range-open`, `range-label`, `total`, `selected`),
 in English and French.
 
 For the TanStack API itself (column helpers, features, row models), see

package/docs/components/date-and-time.md

@@ -46,6 +46,30 @@ month label opens the year view.
 | `startMonth`, `endMonth` | `Date` | — | navigation bounds |
 | `captionLayout` | `'label' \| 'dropdown' \| …` | `'label'` | caption as text or month / year dropdowns |
 | `showOutsideDays` | `boolean` | `true` | days of the adjacent months |
+| `locale` | `Locale` (react-day-picker) | `I18nProvider` language, else `en` | month and weekday names, the heading, and the language of the day names |
+
+**Day names.** Every day is named by its full date in the calendar's language
+(`locale`, else the active `I18nProvider` language, else English): "Thursday,
+October 1, 2026", "jeudi 1 octobre 2026". The name is on the button and, for
+Testing Library, on the `gridcell` around it; "Today" and "selected" are not in
+it. The chosen day has `aria-selected="true"` on its cell and its button is
+described by "Selected" (`material.calendar.selected`, translated); today has
+`aria-current="date"` on both. The days of the neighbouring months
+(`showOutsideDays`) are named by their own dates, so a number alone matches no
+day. "Selected" comes from the `Root` of the default `Calendar`: replacing
+`components.Root` drops it. Pass `labels={{ labelDayButton }}` to override the
+name on both:
+
+```ts
+await page.getByRole('gridcell', { name: 'Thursday, October 1, 2026', exact: true }).getByRole('button').click();
+```
+
+**Weekday row.** It follows the same language: "Su", "Mo"… in English, "lu",
+"ma"… under a French `I18nProvider`, with the week starting on the locale's
+first day (Monday in French). Each header is labelled by its full weekday
+("lundi"); react-day-picker hides the row from assistive tech
+(`<thead aria-hidden>`), since every day's name already carries its weekday.
+It reads at 4.5:1 or more on the popover in the light and the dark theme.
 
 **Storybook:** `Date & time/Calendar` · **Vue:** `Calendar` (Reka parts)
 

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

@@ -45,6 +45,8 @@ import { CircleAlert } from 'lucide-react';
 | `title` | `ReactNode` | — | bold first line |
 | `description` | `ReactNode` | — | muted body text |
 
+The root carries `data-slot="alert"`, the title `data-slot="alert-title"` and the description `data-slot="alert-description"`, for tests and selectors.
+
 **Storybook:** `Feedback & status/Alert` · **Vue:** `Alert`
 
 ---
@@ -129,7 +131,9 @@ to `outlined`). Radix props (`open`, `defaultOpen`, `onOpenChange`) go on
 On open, `AlertDialogContent` focuses `AlertDialogCancel`, the least
 destructive action (its first control when there is no Cancel, the content
 when there is none); an `onOpenAutoFocus` that calls `event.preventDefault()`
-keeps focus where it was.
+keeps focus off the Cancel, on the content: the page behind an alert dialog is
+`inert` while it is open
+([Overlays & menus](overlays-and-menus.md)).
 It hands focus back on close as `DialogContent` does: to
 the element that had it when it opened (the button of yours that opened a
 controlled `AlertDialog`, too), unless focus already went elsewhere or your
@@ -219,6 +223,13 @@ const schema = z.object({ reason: z.string().min(3) });
 | `iconProps` | `IconButtonProps` | — | the badge's `variant`, `color`, `className` |
 | `confirmText` / `cancelText` | `ReactNode` | "Confirm" / "Cancel", translated (`material.confirm-dialog.confirm` / `.cancel`) | button text |
 
+**Several steps, one dialog.** Confirm closes it; to show the next step, change
+its `title` (and `description`) and set `open` back to `true`, at once (from
+`onConfirm` or `onOpenChange`) or after an `await`. No `key` per step is needed:
+the reopened overlay stays under the content, even while the previous one is
+still fading out, so the dialog's buttons take the click. The same holds for
+`ConfirmDialog`, `Dialog`, `AlertDialog` and `Sheet`.
+
 ![CustomAlertDialog](../previews/feedback-status-customalertdialog.webp)
 
 `CustomAlertDialog` is the alert-dialog twin of [CustomDialog](#customdialog):
@@ -415,15 +426,81 @@ toasts.dismiss(id);
 | --- | --- | --- | --- |
 | `title` / `description` | `ReactNode` | preset title for `success`, `error`, `loading` | toast text |
 | `icon` | `ReactNode` (`toast`) · icon name (`toasts.custom`) | preset icon | leading icon |
-| `action` | `ToastAction`: `{ label, onClick? }` or `(dismiss) => ReactNode` | a translated “Close” for `success`, `info`, `error` | trailing button: `onClick`, then the toast closes; or what the function renders, given `dismiss` |
-| `options` | Sonner `ExternalToast` | `duration: 5000` for presets, `Infinity` for `loading` | passed to Sonner (`id`, `duration`, `position`…) |
+| `action` | `ToastAction`: `{ label, onClick? }` or `(dismiss) => ReactNode` | a translated “Close” for `success`, `info`, `error`; a preset keeps the caller's own | trailing button: `onClick`, then the toast closes; or what the function renders, given `dismiss`. Brings the X button and a persistent toast, see below |
+| `dismissLabel` | `string` | the translated “Close” when an `action` is given | accessible name of the X icon button beside the action; `''` hides it |
+| `role` | `'status' \| 'alert'` | none (`toasts.error`: `'alert'`) | live-region role. Toasts are already announced politely by the `Toaster`'s region; `alert` interrupts, and may be read twice by some screen readers |
+| `options` | Sonner `ExternalToast` | `duration: 5000` for presets, `Infinity` for `loading` and for any toast with your own `action` (a preset's fallback "Close" still times out at 5000) unless a `duration` is passed | passed to Sonner (`id`, `duration`, `position`…) |
 
 The toast id defaults to the title, so two toasts with the same title
-replace each other; pass `options: { id }` to show both. `Toaster` is Sonner's
-and takes its props (`position`, `expand`, `richColors`…). `Toast` is the
-component each toast renders, for use with `sonnerToast.custom`.
+replace each other; pass `options: { id }` to show both. `Toaster` wraps
+Sonner's and takes its props (`position`, `expand`, `richColors`…), all
+forwarded; mount the one from `@nxgt/material/components`, not Sonner's own,
+or neither phone change below applies. `Toast` is the component each toast
+renders, for use with `sonnerToast.custom`.
+
+**Types:** `ToastAction`, `ToastProps`, `ToastMethodProps`, `ToasterProps`.
+
+**On a phone** (under 600px wide, where Sonner lays toasts out across the
+screen), a `Toaster` with no `position` shows its toasts at the top
+(`top-center`): across the bottom they covered what a form keeps there, its
+submit button first. A `position` you pass applies on every screen. The server
+and the hydrating client render the desktop default (`bottom-right`), and a
+phone moves the toasts to the top once hydrated. The phone offset is Sonner's
+`mobileOffset` (16px by default); raise its `top` when a sticky header must
+stay visible: `<Toaster mobileOffset={{ top: 72 }} />`.
+
+```tsx
+<Toaster />                         // bottom-right on a desktop, top-center on a phone
+<Toaster position="bottom-center" /> // bottom-center everywhere
+```
+
+**An action keeps the toast open.** `toast()` itself does it, so a preset and a
+direct call behave alike: any toast with an `action` is persistent by default
+(`options.duration: Infinity`, WCAG 2.2.1: a timed toast can vanish before a
+keyboard or screen-reader user reaches its button) unless you pass
+`options.duration`, and shows a small close (X) icon button beside the action,
+named by `material.toast.buttons.close` ("Close" / "Fermer") unless you pass
+your own `dismissLabel` (`''` hides it). The presets keep the `action` you pass
+(`toasts.info({ description: 'A new version is available', action: { label:
+'Reload', onClick } })`); without an `action`, the preset's text "Close" button
+is unchanged, on a timed toast. Sonner pauses its timer while a mouse hovers a
+toast, while a finger is down on it and while the page is hidden, but not on
+keyboard focus, which is why the default is persistent. A tap does not hover:
+the mouse a browser emulates after a tap (which never leaves until the next tap
+elsewhere) is ignored, so a tapped toast still goes after its duration. On a
+touch screen a tap no longer fans out a stack of two or more toasts either: pass
+`expand` to keep the stack open. Sonner does not close a toast on Escape (it
+only collapses the stack); this `Toast` does when focus is inside it, with or
+without an action. The close button is reached with Tab. **Focus after a
+dismiss:** the dismissed toast leaves the page with the focused control in it,
+so focus falls back to `document.body`; move it yourself (`onClick`, or after
+`toasts.dismiss()`) when the flow needs it elsewhere.
+
+**Announced to screen readers:** `Toaster` renders a polite live region
+(`<section aria-live="polite">`) that is in the page before the first toast,
+so every toast inserted into it is read out. A toast therefore has no `role`
+of its own: one on each toast would nest a second live region. `toasts.error`
+is `role="alert"` (assertive), so a failure interrupts; pass `role` to
+`toast()` or to a preset to choose another (a caller's wins). Mount `Toaster`
+once, early, and not conditionally after the first toast. A `Toast` rendered
+outside a `Toaster` is not in a live region: give it its own.
+
+**In tests:** find a toast by its text within the region, and an error toast
+by role. A `status` or `alert` takes no name from its content, so read the
+message with `toHaveTextContent`.
+
+```ts
+const alert = await screen.findByRole('alert'); // toasts.error
+expect(alert).toHaveTextContent('Save failed');
+const saved = await screen.findByText('Item saved'); // toasts.success / info
+expect(saved.closest('section[aria-live="polite"]')).not.toBeNull();
+```
+
+Wait with `findBy*` or `waitFor`, never a fixed delay. A toast stays in the
+DOM until it is dismissed or times out (a toast with an action never times
+out), so queries in one test file can see the previous
+test's toasts: call `toasts.dismiss()` first.
 
-**Types:** `ToastAction`, `ToastProps`, `ToastMethodProps`.
 **Storybook:** `Feedback & status/Toast` · **Vue:** `Toaster`, `toast`, `toasts`, `Toast` (`ToastAction` type)
 
 ---
@@ -475,7 +552,7 @@ import { HydrateLoading } from '@nxgt/material/components';
 | --- | --- | --- | --- |
 | `loadingIcon` | `ReactNode` | `<Spinner className="size-8" />` | replaces the spinner (`lodadingIcon`, the old misspelling, is a deprecated alias) |
 | `children` | `ReactNode` | — | shown above the spinner |
-| `className` | `string` | — | the root fills the viewport (`size-lv`); override to box it |
+| `className` | `string` | — | the root fills the viewport (`w-lvw h-lvh`); override to box it |
 
 **Storybook:** `Feedback & status/HydrateLoading` · **Vue:** `HydrateLoading`
 

package/docs/components/form-fields.md

@@ -348,7 +348,7 @@ import { SearchField } from '@nxgt/material/components';
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `onValueChange` | `(value: string) => void` | — | the text, debounced when `debounceMs` is set |
+| `onValueChange` | `(value: string) => void` | — | the text, debounced when `debounceMs` is set; the latest `onValueChange` is called when the delay ends, so an inline arrow is safe |
 | `debounceMs` | `number` | `0` | delay before `onValueChange`; `0` calls it on every key |
 | `loading` | `boolean` | `false` | spinner in place of the clear button |
 | `onChange` | native handler | — | still fires on every key, undebounced |
@@ -410,8 +410,8 @@ export function Code() {
 | `length` | `number` | `6` | number of slots, split in two groups |
 | `value` / `onChange` | `string` / `(value: string) => void` | — | from `input-otp` |
 | `onComplete` | `(value: string) => void` | — | once every slot is filled |
-| `error` | `boolean` | — | error colour on the slots |
-| `id` | `string` | from `useId()` | the input's id, which the label points to; the generated one is the same on the server and the client |
+| `error` | `boolean` | — | error colour on the slots (`data-invalid` on each); `aria-invalid` goes on the input only, the one element a screen reader reads |
+| `id` | `string` | from `useId()` | the input's id, which the label points to; the generated one is the same on the server and the client, and differs per field — `OtpFormField` too (not the field `name`), so two code forms on one page each keep their name |
 
 `InputOTP`, `InputOTPGroup`, `InputOTPSlot` and `InputOTPSeparator` are the
 parts `OtpField` is built from (`input-otp`), for a layout of your own — no
@@ -444,10 +444,19 @@ export function Pin() {
 `index` it shows; `InputOTPSeparator` is a `separator` with a dash, or your
 children.
 
+**On a phone.** The slots are 44 px squares that shrink with a narrow
+field, kept square: six fit a 320 px-wide card, each above the 24 px
+target of WCAG 2.5.8, and the gaps between them narrow under the `sm`
+breakpoint. A slot you build yourself with `InputOTPSlot` does the same.
+
+**In a test**, find the code by its input — `getByLabelText('Enter OTP')` —
+and an error by `toHaveAttribute('aria-invalid', 'true')` on it; a slot
+carries `data-invalid`, not `aria-invalid`.
+
 **Emits:** `string` (the digits typed so far).
 **Form wrapper:** `OtpFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Form fields/OtpField` · **Vue:** `OtpField`, `OtpFormField`, `InputOTP` (same parts)
+**Storybook:** `Form fields/OtpField`, `Form fields/OtpField/Phone` · **Vue:** `OtpField`, `OtpFormField`, `InputOTP` (same parts)
 
 ---
 
@@ -693,7 +702,7 @@ switch, Email me when an order ships" and `getByRole('switch', { name:
 wins. The `helperText` (the validation message, under `SwitchFormField`)
 describes the switch too, and an `aria-describedby` you pass is kept beside
 these. With `required`, the switch has `aria-required` and the label's asterisk
-is hidden from screen readers, so the name stays "Terms", not "Terms*".
+is drawn by CSS, so the name and the label text stay "Terms", not "Terms*".
 Without an `id` one is generated, under `SwitchFormField` too (it used to be
 the field's `name`, which two forms on one page shared). The row is tinted
 while the switch is on, from `checked` or, uncontrolled, from `defaultChecked` and each toggle, and carries

package/docs/components/media-and-files.md

@@ -689,6 +689,13 @@ Playback uses the browser's `<video>` / `<audio>`: a format the browser cannot
 decode (H.264 MP4 in a Chromium build without proprietary codecs) shows the
 player's error state with a Retry button. The preview is the audio story.
 
+The speed and captions menus are radio groups: each entry is a
+`menuitemradio` and the chosen one `aria-checked="true"` (captions: "Off" or
+one track's `label`). `c` toggles the captions; turned on before a language
+was chosen, they show the current track's first caption track, which the menu
+then checks. In a test, pick one with
+`getByRole('menuitemradio', { name: 'English' })`.
+
 **Storybook:** `Media & files/StxPlayer` · **Vue:** `StxPlayer` (same parts)
 
 ---