@nxgt/material-vue 0.26.1 → 0.27.0

package/dist/{use-heading-spy-VPuFj2Gt.js → use-heading-spy-BbEbAfPK.js}

@@ -1,34 +1,28 @@
-import { a as e } from "./i18n-provider-CaaZCmaR.js";
+import { a as e } from "./i18n-provider-DBusa725.js";
 import { c as t, d as n, f as r, l as i, n as a, u as o } from "./number.utils-Cy1z6qI7.js";
 import { computed as s, getCurrentInstance as c, onMounted as l, ref as u, toValue as d } from "vue";
 import { useIntersectionObserver as f, useMediaQuery as p, useSSRWidth as m, useStorage as h } from "@vueuse/core";
-//#region lib/composables/use-ssr-media-query.ts
-var g = 1024;
-function _(e) {
-	return c() ? p(e, { ssrWidth: m() ?? g }) : p(e);
-}
-//#endregion
-//#region lib/composables/use-mobile.ts
-var v = 768;
-function y() {
-	return _(`(max-width: ${v - 1}px)`);
-}
-//#endregion
 //#region lib/composables/resolve-theme.ts
-function b(e, t) {
+function g(e, t) {
 	let n = e === "light" || e === "dark" ? e : "system";
 	return {
 		theme: n === "system" ? t ? "dark" : "light" : n,
 		preference: n
 	};
 }
-function x(e) {
+function _(e) {
 	typeof document > "u" || (document.documentElement.classList.toggle("dark", e === "dark"), document.documentElement.style.colorScheme = e);
 }
 //#endregion
+//#region lib/composables/use-ssr-media-query.ts
+var v = 1024;
+function y(e) {
+	return c() ? p(e, { ssrWidth: m() ?? v }) : p(e);
+}
+//#endregion
 //#region lib/composables/use-theme.ts
-function S() {
-	let e = _("(prefers-color-scheme: dark)"), t = h("theme", null, void 0, { initOnMounted: !0 }), n = s(() => b(t.value, !!e.value));
+function b() {
+	let e = y("(prefers-color-scheme: dark)"), t = h("theme", null, void 0, { initOnMounted: !0 }), n = s(() => g(t.value, !!e.value));
 	return {
 		get theme() {
 			return n.value.theme;
@@ -37,11 +31,17 @@ function S() {
 			return n.value.preference;
 		},
 		updateTheme: (n) => {
-			n === "system" ? t.value = null : t.value = n, x(b(n === "system" ? void 0 : n, !!e.value).theme);
+			n === "system" ? t.value = null : t.value = n, _(g(n === "system" ? void 0 : n, !!e.value).theme);
 		}
 	};
 }
 //#endregion
+//#region lib/composables/use-mobile.ts
+var x = 768;
+function S() {
+	return y(`(max-width: ${x - 1}px)`);
+}
+//#endregion
 //#region ../../node_modules/date-fns/locale/fr/_lib/formatDistance.js
 var C = {
 	lessThanXSeconds: {
@@ -477,4 +477,4 @@ function z(e, t, n) {
 	});
 }
 //#endregion
-export { b as a, x as i, I as n, y as o, S as r, _ as s, z as t };
+export { y as a, b as i, I as n, _ as o, S as r, g as s, z as t };

package/dist/use-inert-others-CtGqZKR8.js

@@ -0,0 +1,22 @@
+import { nextTick as e, useTemplateRef as t, watch as n } from "vue";
+import { unrefElement as r } from "@vueuse/core";
+import { inertOthers as i } from "@nxgt/material-core/inert-others";
+//#region lib/components/ui/overlays/dialog/use-inert-others.ts
+function a(a, o) {
+	let s = typeof a == "string" ? t(a) : a;
+	n(o, (t, n, a) => {
+		if (!t || typeof document > "u") return;
+		let o, c = !1;
+		e(() => {
+			let e = r(s);
+			!c && e instanceof Element && (o = i(e));
+		}), a(() => {
+			c = !0, o?.();
+		});
+	}, {
+		immediate: !0,
+		flush: "post"
+	});
+}
+//#endregion
+export { a as t };

package/dist/{use-material-translation-CONqD9wJ.js → use-material-translation-BHtgyMz3.js}

@@ -1,6 +1,6 @@
-import "./stored-language-Bxhsx4iB.js";
-import { a as e } from "./i18n-provider-CaaZCmaR.js";
-import { i as t, r as n } from "./translator-CLI_7Crg.js";
+import "./stored-language-AJpwOMsA.js";
+import { a as e } from "./i18n-provider-DBusa725.js";
+import { i as t, r as n } from "./translator-D2_swsMz.js";
 //#region lib/i18n/translate-material.ts
 function r(e, r, i, a) {
 	if (e) for (let t of /* @__PURE__ */ new Set([e, e.split("-")[0]])) {

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

@@ -54,17 +54,71 @@ function save() {
 | `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` | `'default' \| 'xs' \| 'sm' \| 'lg' \| 'icon' \| 'icon-xs' \| 'icon-sm' \| 'icon-lg'` | — (36 px) | height; the `icon*` sizes are square |
-| `loading` | `boolean` | — | shows a spinner, sets `aria-busy` and disables the button |
+| `loading` | `boolean` | — | busy: a spinner, `aria-busy="true"` and `aria-disabled="true"`, and every click cancelled before your `@click` — 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 |
+| `lock-on-click` | `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` |
 | `spinner-variant` | `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` |
-| `as-child` / `as` | `boolean` / tag or component | `false` / `'button'` | styles its only child, or renders another element |
+| `as-child` / `as` | `boolean` / tag or component | `false` / `'button'` | styles its only child, or renders another element. With `as-child` the child keeps its own attributes (`class`, `style` and listeners merge) and its slot content; while `loading`, the spinner goes inside the child, `aria-busy` and `aria-disabled` land on it, and the child stays the same element, keeping its focus, ref and directives. A component child with no slot content shows only the spinner while busy |
 | `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | not `submit` by default — pass it inside a form |
 
-Unlike React, `loading` disables the button (it is not focusable while
-loading). The classes are exported as `buttonVariants` for styling your own
-element.
+The classes are exported as `buttonVariants` for styling your own element.
 
-**Storybook:** `Buttons & actions/Button` · **React:** `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 slot content; with
+`as-child`, put the label in a `<span>` inside the child element.
+
+```vue
+<template>
+  <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>
+</template>
+```
+
+**Submitting once.** Give a submit button `:loading="isSubmitting"` from
+`useForm`: vee-validate 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 pending flag after an `await` — the second click comes first: add
+`lock-on-click`.
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { Button, EmailFormField } from '@nxgt/material-vue/components';
+
+const { handleSubmit, isSubmitting } = useForm();
+const onSubmit = handleSubmit(async (values) => {
+  // …
+});
+</script>
+
+<template>
+  <form @submit="onSubmit">
+    <EmailFormField name="email" label="Email" />
+    <Button type="submit" :loading="isSubmitting">Sign in</Button>
+  </form>
+</template>
+```
+
+**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 `isSubmitting` itself.
+With `lock-on-click`, 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` · **React:** `Button`
 
 ---
 
@@ -204,7 +258,7 @@ function save(options?: { draft: boolean }) {
 | --- | --- | --- | --- |
 | `#menu` slot | — | — | the `DropdownMenu*` items shown by the chevron |
 | `menu-label` | `string` | `"More actions"` (translated) | the chevron's `aria-label` |
-| `variant`, `color`, `loading`, `disabled` | as `Button` | as `Button` | applied to both halves; `loading` also disables the chevron |
+| `variant`, `color`, `loading`, `disabled` | as `Button` | 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 and `@click` go to the main half.
 
@@ -216,7 +270,7 @@ Other `Button` props and `@click` go to the main half.
 
 ![ResponsiveButton](../previews/buttons-actions-responsivebutton.webp)
 
-Shows its label on desktop and collapses to icon-only on mobile.
+Shows its label from 768 px up and collapses to icon-only below. The collapse is a CSS media query, not a JS effect, so the server HTML is the same everywhere and nothing flashes.
 
 ```vue
 <script setup lang="ts">
@@ -235,10 +289,10 @@ import { Plus } from '@lucide/vue';
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `#icon` slot | — | — | always shown |
-| `expanded` | `boolean` | not mobile (`useIsMobile`) | forces the label on or off |
+| `expanded` | `boolean` | by width (`max-md` CSS) | forces the label on or off at every width |
 
-Every `Button` prop applies. Collapsed, the label stays in the button as
-screen-reader text, so it keeps its accessible name; an `aria-label` would
+Every `Button` prop applies. The label is always in the DOM, so the accessible
+name is the same at every width; collapsed, it is screen-reader text; an `aria-label` would
 replace that name, so pass one only when it should differ from the label.
 `expanded` is layout, not disclosure: the button has no `aria-expanded` of its
 own, so it is not announced as "collapsed". Used as a popover, drawer or menu
@@ -297,7 +351,7 @@ Needs `vue-router` installed on the app (`app.use(router)`).
 
 ![CopyButton](../previews/buttons-actions-copybutton.webp)
 
-Copies a value to the clipboard and briefly shows a check mark.
+Copies a value to the clipboard and briefly shows a check mark (or a cross when the clipboard refuses).
 
 ```vue
 <script setup lang="ts">
@@ -315,11 +369,12 @@ import { CopyButton } from '@nxgt/material-vue/components';
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `value` | `string \| (() => string)` | — (required) | what is copied; a function is read at click time |
-| `label` / `copied-label` | `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 |
+| `copied-label` / `failed-label` | `string` | `"Copied"` / `"Copy failed"` (translated) | announced in the status region (and shown in the tooltip) once the write succeeded or failed |
 | `#icon` slot | — | a copy icon | replaces the idle icon |
 | `variant`, `color` | as `IconButton` | `'ghost'`, `'default'` | the button style |
 
-The check mark stays for 1.5 s. `copyToClipboard(text)` is the same copy
+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). Its one root is a `span` with `display: contents` (no box) around the button and the status region, so `v-show`, `Transition` and `$el` work, and a class still goes to the button. The result stays for 1.5 s. `copyToClipboard(text)` is the same copy
 without a button.
 
 `CopyValue` shows the value in a monospace chip with the button beside it:
@@ -399,7 +454,7 @@ const emit = defineEmits<{ next: [] }>();
 | `label` | `string` | `"Load more"` (translated) | tooltip, `aria-label` and expanded label |
 | `#icon` slot | — | a rotate icon | replaces it |
 | `variant` | as `Button` | `'tonal'` | the style |
-| `loading` | `boolean` | — | spinner, button disabled |
+| `loading` | `boolean` | — | spinner, clicks ignored |
 
 Icon-only by default because it sits in a pagination bar next to other icon
 buttons.
@@ -522,7 +577,7 @@ on load.
 
 ![LanguageSwitcher](../previews/buttons-actions-languageswitcher.webp)
 
-Globe button with a menu of the `I18nProvider` languages.
+Globe button with a menu of the `I18nProvider` languages. Its menu is non-modal (see [DropdownMenu](overlays-and-menus.md#dropdownmenu)).
 
 ```vue
 <script setup lang="ts">

package/docs/components/data-display.md

@@ -399,7 +399,7 @@ const user = { name: 'Ada Lovelace', phone: '' };
 
 `label` and `value` (both `string`) are its only props; the default slot is
 rendered under the value. A falsy `value` renders nothing, so optional fields
-need no `v-if`.
+need no `v-if`. The label is a small muted caption above the value (not a title). `Description` takes one cell of the grid it is in; pass `class="col-start-full"` for a full-width row.
 
 **Storybook:** `Data display/Description` · **React:** `Description`
 
@@ -462,12 +462,23 @@ import { Icon, ListTile } from '@nxgt/material-vue/components';
 | `title` | `string` | — | first line |
 | `subtitle` | `string` | — | second, muted line |
 | `href` | `string` | — | renders an `<a>`; without it the row is a `<button>` |
+| `linkComponent` / `link-component` | `Component` | plain `<a>` | the link element, as in the app shell: a component that takes `href` and lets the other attributes fall through |
 | `selected` | `boolean` | `false` | highlighted row (`aria-current="page"` on a link) |
 | `size` | `'sm' \| 'md'` | `'md'` | `sm` is the dense navigation row |
 | `disabled` | `boolean` | — | disables the link or button |
 | `@click` | `(event: MouseEvent) => void` | — | fired by both shapes |
 | `#leading`, `#trailing` | slots | — | icons, avatars, actions |
 
+With a router, pass `link-component` so a click navigates on the client instead of reloading the page (`RouterLink` takes `to`, so wrap it in a component that takes `href`; `AppLink` below is the one defined in [A `ListTile` link reloads the whole page](../troubleshooting.md#a-listtile-link-reloads-the-whole-page)):
+
+```vue
+<ListTile title="Notifications" href="/settings/notifications" :link-component="AppLink" />
+```
+
+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 too).
+
 **Storybook:** `Data display/ListTile` · **React:** `ListTile`
 
 ---

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.
 
 ```vue
 <script setup lang="ts">
@@ -79,7 +79,9 @@ table enables, for typing your own column defs.
 | `#actions="{ table }"` / `actions` | slot / `(table) => VNode` | — | 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 shown | 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="{ filtered }"` | slot | icon and "No data available" | content of the empty row, spanning every visible column |
@@ -142,6 +144,72 @@ default, or the `#empty` slot, told whether rows exist but none matches the
 filters (`filtered`); content that renders nothing gets the default.
 `DataTableEmptyState` types the slot props.
 
+### Phones and narrow screens
+
+```vue
+<template>
+  <!-- The rows scroll inside 60% of the viewport; the page scrolls otherwise. -->
+  <DataTable
+    :data="invoices"
+    :columns="columns"
+    max-height="60vh"
+    scroll-label="Invoices"
+  />
+</template>
+```
+
+The table is as tall as its rows, and the page scrolls: there is no height
+cap unless you pass `max-height`, so a phone never gets a scroll inside the
+page's. The header row shows at every width (`:show-header="false"` hides
+it). With `max-height`, 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 `scroll-label`) 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:
+the `actions` prop or the `#actions` slot that render nothing (`null`,
+`false`, whitespace, a `v-if` left out) leave no empty `<fieldset>` behind.
+
+Selection actions do not move the rows. With `actions` or the `#actions`
+slot and the `select` column (`predefinedColumns().select`, id `select`),
+the toolbar's height is reserved — an empty, hidden placeholder
+(`[data-slot="header-placeholder"]`) while they 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.
+
+```vue
+<template>
+  <DataTable :data="people" :columns="[select, ...columns]">
+    <template #actions="{ table }">
+      <Button
+        v-if="table.getSelectedRowModel().rows.length > 0"
+        @click="handleDelete(table.getSelectedRowModel().rows)()"
+      >
+        Delete selected
+      </Button>
+    </template>
+  </DataTable>
+</template>
+```
+
+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
@@ -263,7 +331,16 @@ async function archive() {
   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 `v-model:sorting`: the headers show it, and
   `update:sorting` hands you the new `SortingState` to put in the URL.
   Filters work the same way: render them in `#actions` and keep their values
@@ -288,7 +365,10 @@ async function archive() {
   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.** The `#footer="{ table }"` slot or the `footer` prop
   (`(table) => VNode`) replaces the footer — `DataTableServerFooter` is the
@@ -297,7 +377,7 @@ async function archive() {
   page is fetched, 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

@@ -58,9 +58,33 @@ under `I18nProvider`), and so are `DateRangeField`'s; an `aria-label` on
 | `layout` | `'month-and-year' \| 'month-only' \| 'year-only'` | — | month / year selects in the heading instead of plain text |
 | `year-range` | `DateValue[]` | 100 years back, 10 ahead | the years in the year select |
 | `default-placeholder` | `DateValue` | today | the month shown first |
-| `locale` | `string` | `'en'` | month and weekday names |
+| `locale` | `string` | `I18nProvider` language, else `'en'` | month and weekday names, and the language of the day names |
 
 **Emits:** `update:modelValue` with `DateValue | DateValue[] | undefined`.
+
+**Day names.** Every day is named by its full date in the calendar's language
+(the `locale` prop, 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. 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 are named by their own dates, so a
+number alone matches no day. "Selected" comes from the `Calendar` itself, which
+renders the hidden hint; a calendar hand-built from the exported parts names its
+cells and buttons the same way but has no "Selected". `DateRangeField`'s
+calendar does the same:
+
+```ts
+await page.getByRole('gridcell', { name: 'Thursday, October 1, 2026', exact: true }).getByRole('button').click();
+```
+
+**Weekday row.** It follows the same language: "S", "M"… in English, "L",
+"M"… 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"), as in `@nxgt/material`; reka 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.
+
 No form wrapper — use `DateFormField`.
 **Storybook:** `Date & time/Calendar` · **React:** `Calendar`, `CalendarDayButton`
 

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

@@ -52,6 +52,8 @@ import { CircleAlert } from '@lucide/vue';
 
 The default slot is rendered under the description.
 
+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` · **React:** `Alert`
 
 ---
@@ -157,7 +159,8 @@ the content brings both.
 On open, `AlertDialogContent` focuses `AlertDialogCancel`, the least
 destructive action (its first control when there is no Cancel, the content
 when there is none); an `@open-auto-focus` that calls `event.preventDefault()`
-keeps focus where it was. After that opt-out the Cancel takes no focus until the next
+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)). After that opt-out the Cancel takes no focus until the next
 task: focus it from a `setTimeout`, not in the handler.
 
 **Emits:** `update:open` on `AlertDialog` — `boolean`.
@@ -239,7 +242,7 @@ function archive() {}
 | Prop (`ConfirmationDialog`) | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `#trigger` slot | — | — | becomes the dialog trigger (`as-child`, no extra button): pass one element, such as a `Button` |
-| `v-model:open` | `boolean` | uncontrolled | open state; without it the dialog keeps its own |
+| `v-model:open` | `boolean` | uncontrolled | open state: with `v-model:open`, or `:open` together with `@update:open`, the dialog shows exactly what `open` says; otherwise it keeps its own state (`:open` alone only opens it, `@update:open` alone only listens; an `open` that is still `undefined`, as `ref<boolean>()`, counts as not set and the dialog keeps its own state, so it still closes) |
 | `@confirm` | `(values?) => void` | — | emitted on confirm, with the form's parsed values when there is one; the dialog then closes |
 | `form-options` | `ConfirmationDialogFormOptions` (`{ schema, defaultValues? }`) | — | a form in the dialog, below the default slot — see below |
 | `color` | `IconButton` colour | `'warning'` | icon and both buttons |
@@ -247,6 +250,11 @@ function archive() {}
 | `#icon` slot | — | info icon, in a decorative `aria-hidden` badge | replaces the badge: keep yours decorative (`<IconButton as="span" aria-hidden="true">`), not a button that does nothing |
 | `confirm-text` / `cancel-text` | `string` | "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
+`@confirm` or `update:open`) or after an `await`. No `:key` per step is needed,
+and the reopened dialog's buttons take the click.
+
 `form-options` puts a form in the confirmation, as React's `formOptions`:
 `schema` is a Zod 4 schema (any Standard Schema, or a vee-validate typed
 schema), `defaultValues` its initial values, and the `#form` slot renders the
@@ -564,16 +572,83 @@ async function upload() {
 | --- | --- | --- | --- |
 | `title` / `description` | `string` | preset title for `success`, `error`, `loading` | toast text |
 | `icon` | a VNode (`toast`) · icon name (`toasts.*`) | preset icon | leading icon |
-| `action` | `{ label, onClick? }` or `(dismiss) => VNode` | a translated "Close" for `success`, `info`, `error` | trailing button |
-| `options` | vue-sonner `ExternalToast` | `duration: 5000` for presets, `Infinity` for `loading` | passed to Sonner (`id`, `duration`, `position`…) |
+| `action` | `{ label, onClick? }` or `(dismiss) => VNode` | 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` | vue-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
-vue-sonner's and takes its props (`position`, `expand`, `rich-colors`…);
-vue-sonner's stylesheet comes with this package's (`styles.css`, or the
-compiled stylesheet). `Toast` is the component each toast
-renders, and `sonnerToast` is vue-sonner's own `toast`, for anything the
-presets do not cover.
+replace each other; pass `options: { id }` to show both. `Toaster` wraps
+vue-sonner's and takes its props (`position`, `expand`, `rich-colors`…), all
+forwarded; mount the one from `@nxgt/material-vue/components`, not
+vue-sonner's own, or neither phone change below applies. vue-sonner's
+stylesheet comes with this package's (`styles.css`, or the compiled
+stylesheet). `Toast` is the component each toast renders, and `sonnerToast`
+is vue-sonner's own `toast`, for anything the presets do not cover.
+
+**Types:** `ToasterProps` (vue-sonner's), from `@nxgt/material-vue/components`.
+
+**On a phone** (under 600px wide, where vue-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 client's first render answer for a desktop (`bottom-right`, or for the
+width `provideSSRWidth()` gives), and a phone moves the toasts to the top once
+mounted. The phone offset is vue-sonner's `mobile-offset` (16px by default);
+raise its `top` when a sticky header must stay visible:
+`<Toaster :mobile-offset="{ top: 72 }" />`.
+
+```vue
+<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.
 
 **Storybook:** `Feedback & status/Toast` · **React:** `Toaster`, `toast`, `toasts`, `Toast` (`ToastAction` type)
 
@@ -640,7 +715,7 @@ import { HydrateLoading } from '@nxgt/material-vue/components';
 | --- | --- | --- | --- |
 | `#icon` slot | — | `<Spinner class="size-8" />` | replaces the spinner |
 | default slot | — | — | shown above the spinner |
-| `class` | `string` | — | the root fills the viewport (`size-lv`); override to box it |
+| `class` | `string` | — | the root fills the viewport (`w-lvw h-lvh`); override to box it |
 
 **Storybook:** `Feedback & status/HydrateLoading` · **React:** `HydrateLoading`
 

package/docs/components/form-fields.md

@@ -498,8 +498,8 @@ const code = ref('');
 | `length` | `number` | `6` | number of slots, split in two groups |
 | `v-model` | `string` | — | the digits typed so far |
 | `@complete` | `(value: string) => void` | — | once every slot is filled (from `vue-input-otp`) |
-| `error` | `boolean` | — | error colour on the slots |
-| `id` | `string` | from `useId()` | the input's id, which the label points to |
+| `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; it 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
 unlabelled primitives it is built from, for a hand-built layout:
@@ -527,10 +527,19 @@ const pin = ref('');
 </template>
 ```
 
+**On a phone.** The slots are 36 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:** `update:modelValue` with `string` (the digits typed so far).
 **Form wrapper:** `OtpFormField` — `name` inside a vee-validate form, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Form fields/OtpField` · **React:** `OtpField`, `OtpFormField`, `InputOTP` (same parts)
+**Storybook:** `Form fields/OtpField`, `Form fields/OtpField/Phone` · **React:** `OtpField`, `OtpFormField`, `InputOTP` (same parts)
 
 ---
 
@@ -818,7 +827,7 @@ a screen reader says "Notifications, switch, Email me when an order ships". An
 `aria-label` or `aria-labelledby` you pass wins, and an `aria-describedby` you
 pass is kept beside the row text. The `helper-text` (the validation message,
 under `SwitchFormField`) describes the switch too. With `required`, the label's
-asterisk is hidden from screen readers, so the name stays "Terms", not
+asterisk is drawn by CSS, so the name and the label text stay "Terms", not
 "Terms*". Without an `id` one is generated. The row is
 tinted while the switch is on, from `v-model` or, uncontrolled, from
 `default-value` and each toggle, and carries `data-checked="true"` /