@nxgt/material-vue 0.26.1 → 0.28.0

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`
 
 ---
@@ -620,7 +631,7 @@ function openEvent() {
 
 ![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.
 
 ```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"` /

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

@@ -751,6 +751,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. `StxPlayer` mounts on the client only.
 
+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` · **React:** `StxPlayer` (same parts)
 
 ---

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

@@ -72,11 +72,14 @@ which work alone; `findActiveMenuItem`, `isMenuItemActive` and
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `items` | `MenuItem[]` | — | `label` (already translated), `url`, `icon` (a Font Awesome name), `footer` |
+| `linkComponent` | `Component` | `RouterLink` | The link each menu entry renders, given `href`; pass it as `link-component` (see the [app shell guide](../guides/app-shell.md)) |
 | `avatarSrc` | `string` | — | avatar image in the header |
 | `#brand` | slot | — | sidebar header |
 | `#header-actions`, `#avatar` | slots | — | header, before the avatar; `#avatar` replaces it |
 | `title`, `subtitle`, `#actions` | `string`, `string`, slot | — | `ActivityContent`'s header card |
 | `#header` / `hideHeader` | slot / `boolean` | — / `false` | `ActivityContent`: replace or drop the header card |
+| `contentAs` / `scroll` | `'main' \| 'div'` / `'document' \| 'container'` | `'main'` / `'document'` | the content region is the page's `<main>`; the document scrolls (see the [app shell guide](../guides/app-shell.md#landmarks-headings-and-scrolling)) |
+| `titleAs` | `'h1'` … `'h6'` \| `'div'` | `'h1'` | `ActivityContent`: the title's heading level |
 
 The active entry is the longest match across the whole menu, segment-aware.
 `AppBreadcrumb` reads `meta.breadcrumb` (a string, or a function of the
@@ -86,6 +89,11 @@ to the router's root, so a history base is kept; a crumb with params links to
 its path with them filled in) and the current page is text with
 `aria-current="page"`.
 
+`AppSidebar` gives each entry its label as a tooltip **only while it is
+collapsed**: expanded (and in the phone menu sheet) the label is on screen
+and no tooltip opens. A `SidebarMenuItem` of your own shows the `tooltip` you
+pass, collapsed or expanded.
+
 **Storybook:** `Navigation & layout/AppShell` · **React:** `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb`
 
 ---
@@ -135,9 +143,19 @@ const expanded = ref(false);
 ```
 
 Parts: `Sidebar`, `SidebarHeader`, `SidebarContent`, `SidebarFooter`,
-`SidebarMenuLabel` (`#actions` slot), `SidebarMenuItem` (a button: `#icon`
+`SidebarMenuLabel` (`#actions` slot), `SidebarMenuItem` (a button, or a link with `href` and `link-component`: `#icon`
 slot, `active`, `tooltip`, `@click`).
 
+A `SidebarMenuItem` stays a `<button>` without `href`. With `href` it renders a
+real link, a plain `<a>` unless you pass `link-component` (given the `href`):
+
+```vue
+<SidebarMenuItem href="/inbox" :link-component="MyLink">
+  <template #icon><Icon name="inbox" /></template>
+  Inbox
+</SidebarMenuItem>
+```
+
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `v-model:expanded` | `boolean` | `false` | labels beside the icons; collapsed shows icons with tooltips |

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

@@ -9,6 +9,19 @@ uncontrolled. Dialogs that exist to confirm something live on
 [Feedback & status](feedback-and-status.md). Everything is imported from
 `@nxgt/material-vue/components`.
 
+**The page behind a modal layer is inert.** While a `Dialog`, `Sheet`,
+`Drawer`, `AlertDialog` or `CommandDialog` is open — and a `Select` list, a
+`ContextMenu`, or a `DropdownMenu` or `Popover` given `modal` — everything else
+on the page is `inert` as well as `aria-hidden`: its controls leave the tab
+order and the accessibility tree, so a keyboard or screen-reader user stays in
+the layer and axe's `aria-hidden-focus` passes. Live regions stay reachable:
+a toast shown over a dialog is announced, and its action can be used. Layers
+stack: a `Select` open in a `Dialog` makes the dialog inert too, until it
+closes. Focus left on the page when the layer opens (an `@open-auto-focus`
+that prevents the default and focuses nothing) goes to the layer's content.
+Non-modal layers (`:modal="false"`, and `DropdownMenu` and `Popover` by
+default) leave the page as it is.
+
 | | Component | What it does |
 | --- | --- | --- |
 | <img src="../previews/overlays-menus-dialog.webp" width="96" alt=""> | [Dialog](#dialog) | Modal dialog with a close button |
@@ -74,7 +87,7 @@ overlay, for a dialog taller than the screen).
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `default-open` / `v-model:open` (`Dialog`) | `boolean` | `false` | open state, uncontrolled / controlled |
-| `modal` (`Dialog`) | `boolean` | `true` | `false` drops the backdrop and lets the page stay interactive |
+| `modal` (`Dialog`) | `boolean` | `true` | `false` drops the backdrop and lets the page stay interactive; `true` makes the page behind `inert` while it is open |
 | `as-child` (`DialogTrigger`) | `boolean` | `false` | the trigger is its child — pass it with a `Button`, or the trigger renders its own `<button>` around it |
 | `show-close-button` (`DialogContent`) | `boolean` | `true` | the top-right X, named "Close" (`material.buttons.close`, translated) |
 | `show-close-button` (`DialogFooter`) | `boolean` | `false` | adds an outlined "Close" button (`material.buttons.close`, translated) |
@@ -86,7 +99,10 @@ Unlike React, `DialogContent` renders the X by itself (turn it off with
 On open, `DialogContent` moves focus into the dialog: to its first control
 (the built-in X when there is nothing before it), or to the content itself
 when it has none. An `@open-auto-focus` that calls `event.preventDefault()`
-keeps focus where it was. `SheetContent`, `DrawerContent` and
+keeps focus off that control: a modal dialog then focuses its content, as the
+page behind it is inert, and a non-modal one leaves focus where it was
+([details](../troubleshooting.md#focus-moves-into-a-dialog-although-open-auto-focus-prevented-it)).
+`SheetContent`, `DrawerContent` and
 `AlertDialogContent` do the same; an alert dialog focuses its
 `AlertDialogCancel`.
 
@@ -371,7 +387,7 @@ shows.
 
 ![DropdownMenu](../previews/overlays-menus-dropdownmenu.webp)
 
-Menu with checkbox and radio items, submenus, shortcuts and a destructive item.
+Menu with checkbox and radio items, submenus, shortcuts and a destructive item. It is non-modal by default: Reka's modal menu marks the rest of the page `aria-hidden` while its buttons and links stay focusable, which accessibility audits (axe `aria-hidden-focus`) report; a non-modal menu hides nothing and still closes on Escape, an outside click or Tab. Pass `modal` for a modal one: the page behind it is then `inert` too, so its controls leave the tab order and axe passes.
 
 ```vue
 <script setup lang="ts">
@@ -421,7 +437,7 @@ Parts: `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`,
 | `variant` (`DropdownMenuItem`) | `'default' \| 'error'` | `'default'` | error colour for a destructive item; `'destructive'` is a deprecated alias of `'error'`; both render `data-variant="error"`, so style or test with `[data-variant=error]` |
 | `inset` (item, label, sub-trigger) | `boolean` | — | indents to line up with checkbox and radio items |
 | `@select` (`DropdownMenuItem`) | `(event: Event) => void` | — | the item's action; `event.preventDefault()` keeps the menu open |
-| `default-open` / `v-model:open`, `modal` (`DropdownMenu`) | `boolean` | —, `true` | open state; a modal menu blocks the page behind it |
+| `default-open` / `v-model:open`, `modal` (`DropdownMenu`) | `boolean` | —, `false` | open state; `modal` brings back the scroll lock, swallowed outside clicks and an `aria-hidden`, `inert` page behind the menu |
 | `to` (`DropdownMenuContent`) | `string \| HTMLElement` | `'body'` | where the menu is teleported; for a menu opened in fullscreen, pass the fullscreen element, read when the menu opens (see [troubleshooting](../troubleshooting.md#a-dropdownmenu-opened-in-fullscreen-does-not-show)) |
 
 Vue's `DropdownMenuItem` has no `active` prop. CSS or a test that selected