@nxgt/material-vue 0.26.1 → 0.27.0

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

package/docs/components/primitives.md

@@ -163,7 +163,9 @@ import {
 
 Parts: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`,
 `CardContent`, `CardFooter` — each a styled `<div>` taking `class` and the
-element's attributes. `CardAction` sits top-right of the header.
+element's attributes, except `CardTitle`, a heading: an `h3` by default,
+another level or a `div` with `as` (`<CardTitle as="h2">`), so
+`getByRole('heading', { name })` finds it. `CardAction` sits top-right of the header.
 
 **Storybook:** `Primitives/Card` · **React:** `Card` (same parts)
 
@@ -246,12 +248,24 @@ import { Input, Label } from '@nxgt/material-vue/components';
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `with-asterisk` | `boolean` | — | appends a red `*`, hidden from screen readers: mark the field itself `required` (or `aria-required`), which every field of this library does for you |
+| `with-asterisk` | `boolean` | — | draws a red `*` with CSS after the label, so it is in neither the label's text nor its accessible name (`getByLabel('Email', { exact: true })` and `getByLabelText` match "Email"): mark the field itself `required` (or `aria-required`), which every field of this library does for you |
 | `for` | `string` | — | the control it labels; clicking the label focuses it |
 
 Fields on the [Form fields](form-fields.md) page render it for you through
 their `label` prop.
 
+To restyle the mark, target `[data-slot="label-text"][data-required]::after`:
+`background-color` sets its colour (default `var(--color-error)`), `width` and
+`height` its size. It stays visible in forced-colors mode and in print.
+
+```css
+[data-slot="label-text"][data-required]::after {
+	background-color: #b45309;
+	width: 0.75em;
+	height: 0.75em;
+}
+```
+
 **Storybook:** `Primitives/Label` · **React:** `Label`
 
 ---

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

@@ -31,6 +31,8 @@ value type each one writes. Everything is imported from
 ![Select](../previews/selection-choice-select.webp)
 
 Select primitives with groups, labels and scroll buttons, plus a styled native `<select>`.
+Its list is modal: while it is open the rest of the page is `inert` (a
+`Select` in a `Dialog` makes the dialog inert too, until the list closes).
 
 ```vue
 <script setup lang="ts">
@@ -140,7 +142,7 @@ const framework = ref('nuxt');
 | `options` | `{ value: string; label: string }[]` | — | required; the items |
 | `v-model` | `string` | `''` | the selected `value`; `''` for nothing selected |
 | `placeholder` | `string` | `label` | the trigger's text while nothing is selected |
-| `required` | `boolean` | — | an asterisk after the label, and the select's `required` |
+| `required` | `boolean` | — | an asterisk after the label, and the select's `required`; the trigger is named by the label |
 | `label`, `helper-text`, `error`, `disabled` | | — | the field's text and state |
 
 `#option` renders each option's content in the list (React's
@@ -161,6 +163,10 @@ the picked option's text.
 
 `SelectFormField` passes the slot through.
 
+**Accessibility:** the trigger is named by `label`, described by the help or
+error text (`aria-describedby`) and marked `aria-invalid` on error, so
+`getByRole('combobox', { name: 'Framework' })` finds it and
+`toHaveAccessibleDescription(…)` / `toBeInvalid()` match.
 **Emits:** `update:modelValue` with `string`.
 **Form wrapper:** `SelectFormField` — `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).
@@ -571,6 +577,11 @@ const picked = ref<string[]>([]);
 | `options` | `{ value: string; label: string }[]` | — | required; the chips |
 | `label`, `helper-text`, `error`, `disabled` | | — | the field's text and state |
 
+**Accessibility:** the chips are toggle buttons in a `role="group"` named by
+`label` and described by the help text: a chosen chip is
+`aria-pressed="true"` (never `aria-selected`), in `single` mode too.
+Query `getByRole('group', { name: 'Topics' })`, then
+`getByRole('button', { name: 'Design' })`; there is no `option` role.
 **Emits:** `update:modelValue` with `string[]`. `SelectChipFormField` stores
 `string[]` in both modes (React stores `string | null` in `single` mode).
 **Form wrapper:** `SelectChipFormField` — `name` inside a vee-validate form, see

package/docs/getting-started.md

@@ -21,7 +21,7 @@ the **required peers**. The app must resolve a single copy of each, otherwise
 | `vue-router` | `^4.5 \|\| ^5` | the app shell, `LinkButton`, `useSearchParam`, `useNavigationHandler` |
 | `vee-validate` | `^4.15` | every `*FormField` wrapper and the built-in forms ([forms](guides/forms.md)) |
 | `@tanstack/vue-table` | `^9` | `DataTable` |
-| `@vueuse/core` | `^13 \|\| ^14` | `useTheme`, `useIsMobile`, `ScrollProgress`, `CopyButton`, prop forwarding in primitives |
+| `@vueuse/core` | `^13 \|\| ^14` | `useTheme`, `useIsMobile`, `ScrollProgress`, prop forwarding in primitives |
 
 **Optional peers** are only needed by the entry that uses them. An app that
 does not import that entry never has them in its tree.
@@ -350,7 +350,7 @@ touched, and validated, when focus leaves it, so a required field shows its
 error as the user moves past it rather than only on submit
 ([details](troubleshooting.md#metatouched-stays-false-after-leaving-a-field)).
 An `AlertDialogContent` whose `@open-auto-focus` calls `event.preventDefault()`
-now keeps focus where it was, as the other modals do
+now keeps focus off its Cancel, as the other modals do
 ([details](troubleshooting.md#an-alertdialog-focuses-its-cancel-although-open-auto-focus-prevented-it)).
 A `DrawerContent` hands focus back, on close, to the element that opened it,
 where it used to fall to `<body>`

package/docs/guides/app-shell.md

@@ -66,7 +66,7 @@ and `definePageMeta({ breadcrumb: 'Invoices' })` in each page.
 
 <a id="it-needs-a-data-router"></a>
 
-The sidebar navigates with `useRouter().push()`, and the sidebar and
+The sidebar entries are `RouterLink`s, and the sidebar and
 `AppBreadcrumb` read `useRoute()`. Install vue-router before mount
 (`app.use(router)`, see [getting started](../getting-started.md#pinia-and-router));
 without it the shell cannot render. Any history works: `createWebHistory`,
@@ -175,12 +175,39 @@ partitionMenu(items);                              // { content, footer }
 | --- | --- | --- | --- |
 | `items` | `MenuItem[]` | — (required) | Sidebar entries, and the mobile menu sheet |
 | `avatar-src` | `string` | — | End of the header: the image URL of an `Avatar` |
-| `class` | `string` | — | Classes for the inner layout box |
+| `link-component` | `AppShellLinkComponent` (a `Component`) | `RouterLink` | The link each menu entry renders, given `href` (see below) |
+| `content-as` | `'main' \| 'div'` | `'main'` | The content region's element: the page's `<main>` landmark, or a `div` when your app renders its own `<main>` |
+| `scroll` | `'document' \| 'container'` | `'document'` | Who scrolls: the page (header and sidebar sticky), or the content region inside a shell one screen high |
+| `class` | `string` | — | Classes for the outer element (`[data-slot=activity-layout]`), which takes the other attributes too |
 | `#brand` | slot | an atom icon | Replaces the sidebar header: a logo, a product name. Always fill it; the default is a placeholder |
 | `#header-actions` | slot | — | In the header, before the avatar: notifications, help, `LanguageSwitcher`, `ThemeToggle` |
 | `#avatar` | slot | the `avatar-src` image | Replaces the avatar entirely |
 | default | slot | — | The routed content, usually `<RouterView />` |
 
+Each menu entry is a real link, `<a href="/invoices">`, so it works before
+hydration on a server-rendered page, opens in a new tab on middle-click, and
+is announced as a link, named by its label alone ("Identities": the icon beside
+it is decorative); the current page's entry carries `aria-current="page"`.
+By default it is a `RouterLink` (client-side navigation, no reload), so
+`link-component` is only needed for another router or a custom link: pass it a
+component that takes `href` and renders a single root element with its default slot. Vue falls the rest of the
+attributes (`class`, `aria-current`, the tooltip's handlers, `data-state`)
+through to that root, so the root must be one element, not a fragment, and must
+take them: do not set `inheritAttrs: false` without binding `$attrs` yourself.
+A link that forwards only a `DataTable`'s link props is not enough here.
+
+The prop's type is exported as `AppShellLinkComponent` (any `Component`):
+
+```ts
+import type { AppShellLinkComponent } from '@nxgt/material-vue/components';
+import { defineComponent, h } from 'vue';
+
+export const MyLink: AppShellLinkComponent = defineComponent({
+  props: { href: { type: String, required: true } },
+  setup: (props, { slots }) => () => h('a', { href: props.href }, slots.default?.()),
+});
+```
+
 The shell holds no session: read the user wherever your app keeps it and fill
 the slots.
 
@@ -219,10 +246,56 @@ defineProps<{ items: MenuItem[]; user: { name: string; picture?: string } }>();
 </template>
 ```
 
-The layout fills the viewport (it sits on `Background`, which is
-`100lvw × 100lvh`). On screens below 768 px the sidebar is hidden and the
-header shows a menu button that opens the same entries in a sheet.
-Breadcrumbs are hidden there.
+On screens below 768 px the sidebar is hidden and the header shows a menu
+button ("Open menu") that opens the same entries in a sheet. Breadcrumbs are
+hidden there. The sheet is a dialog named "Navigation"
+(`material.app-shell.navigation`) with a visible "Close" button. Following an
+entry closes it — so does any route change, Back included — and focus goes to
+the page's `<main>`; closed with Escape, the close button or the overlay,
+focus returns to the menu button. Its entries show their labels, so they have
+no tooltip: none opens over the first entry as focus moves in.
+
+## Landmarks, headings and scrolling
+
+- **One `<main>`.** The content region is the page's `<main>` landmark
+  (`getByRole('main')`). If your app already renders a `<main>` around the
+  shell, pass `content-as="div"`: a page has only one.
+- **The screen's title is the `h1`.** `ActivityContent`'s `title` is a heading,
+  level 1 by default (`title-as`); the shell itself renders no heading, so a
+  screen's title is the page's top one. A `CardTitle` is an `h3` (its `as`
+  changes the level).
+- **The document scrolls.** The shell sits on `Background` but is `100%` wide
+  and at least `100dvh` high, so it never adds a scrollbar's width of
+  horizontal scroll and its bottom is never under a phone's toolbar. The page
+  grows with the screen and the browser scrolls it; the header and the
+  desktop sidebar are sticky. `scroll="container"` is the opt-in for a screen
+  that manages its own height (a full-height map, a board): the shell is then
+  exactly `100dvh` high and the content region scrolls inside it.
+- **A new screen starts at the top.** With the document scrolling, the
+  router's `scrollBehavior` handles positions as for any page. With
+  `scroll="container"` the content region outlives navigations, and
+  `scrollBehavior` only knows the window, so the shell does it for that box: a
+  new path opens at the top, and Back or Forward returns to where that entry
+  was left (kept per history entry — `history.state.position`, or the
+  `fullPath` with a memory history — for the session). A change of query or
+  hash only (a filter, a tab, an `#anchor`) keeps the position.
+
+```vue
+<script setup lang="ts">
+import { ActivityLayout, type MenuItem } from '@nxgt/material-vue/components';
+
+defineProps<{ items: MenuItem[] }>();
+</script>
+
+<template>
+  <!-- The app renders its own <main>, and the board below needs a fixed height. -->
+  <main>
+    <ActivityLayout :items="items" content-as="div" scroll="container">
+      <RouterView />
+    </ActivityLayout>
+  </main>
+</template>
+```
 
 ## `ActivityContent`
 
@@ -231,6 +304,7 @@ Breadcrumbs are hidden there.
 | `title` | `string` | — | Header card title |
 | `subtitle` | `string` | — | Under the title |
 | `hide-header` | `boolean` | `false` | No header card |
+| `title-as` | `'h1'` … `'h6'` \| `'div'` | `'h1'` | The title's element: the screen's heading, `'h2'` under a heading of yours, `'div'` for none |
 | `#actions` | slot | — | Right side of the header card: buttons |
 | `#header` | slot | — | Replaces the header card entirely |
 | default | slot | — | The screen's content |
@@ -250,6 +324,9 @@ import { ActivityContent, Button } from '@nxgt/material-vue/components';
 </template>
 ```
 
+The header card wraps: on a narrow screen the actions go under the title
+instead of squeezing it, and a long title wraps.
+
 ## Breadcrumbs
 
 `AppBreadcrumb` (rendered by `ActivityLayout`) starts with a home icon linking
@@ -302,3 +379,22 @@ takes `expanded` (`v-model:expanded`) and `with-toggle-icon`, and has the
 bar. The lower-level `Sidebar`, `TopAppBar`, `NavigationRail` and `Breadcrumb`
 primitives are on the
 [navigation & layout](../components/navigation-and-layout.md) page.
+
+`AppHeader` and `AppSidebar` also work without Vue Router, given a
+`link-component` of your own (the default, `RouterLink`, needs one). Without a
+router no entry is marked active, and the header's menu sheet closes only when
+an entry is followed rather than on every route change. `AppBreadcrumb` is
+built from the route and needs Vue Router.
+
+```vue
+<script setup lang="ts">
+import { AppHeader, type MenuItem } from '@nxgt/material-vue/components';
+import PlainLink from './plain-link.vue'; // renders <a :href="href"><slot /></a>
+
+defineProps<{ items: MenuItem[] }>();
+</script>
+
+<template>
+  <AppHeader :items="items" :link-component="PlainLink" />
+</template>
+```

package/docs/guides/forms.md

@@ -52,7 +52,7 @@ What a wrapper does for you, through `useField(() => props.name)`:
 | `error` | `true` when the field has an error message, or is touched and invalid (the red border) |
 | `helperText` | the field's error message, or your own `helperText` when there is none |
 | `name` | the `name` you passed, also used as the native `name` |
-| `id` | passed through; `RadioGroupField` and `CheckboxGroup` generate one when absent, and a group's option *i* is `` `${id}-${i}` `` |
+| `id` | passed through; when absent, every field generates one (`useId`), never the field `name`, so two forms on one page sharing a field name keep their labels apart; a group's option *i* is `` `${id}-${i}` `` |
 | everything else | your props, passed through unchanged (`label`, `disabled`, `options`, …) |
 
 `RadioGroupFormField` and `CheckboxGroupFormField` need nothing more for a
@@ -201,8 +201,17 @@ const onSubmit = handleSubmit((values) => props.onSave(values));
   validates, and calls `fn` only when the form is valid. `isSubmitting` stays
   `true` until the promise `fn` returns settles.
 - `Button` defaults to `type="button"`: the submit button needs
-  `type="submit"`. `loading` shows a spinner and disables it; pass it
-  `isSubmitting`.
+  `type="submit"`. With `:loading="isSubmitting"` it is busy (`aria-busy`,
+  `aria-disabled`, a spinner) from the first click until the promise settles,
+  and cancels every click meanwhile — a double click, or Enter pressed twice
+  in a field, submits once. It stays focusable. For a `loading` that turns
+  true only after an `await`, add `lock-on-click`
+  ([Button](../components/buttons-and-actions.md#button)). The guard sees
+  clicks, Space and Enter on the button, and Enter in a field when it is the
+  form's first submit button; `form.requestSubmit()` and `form.submit()` fire
+  no click, so a submit your code starts (an OTP step that submits on its
+  last digit, a shortcut) checks `isSubmitting` itself. A `lock-on-click`
+  whose `loading` never turns true releases after one second.
 - Initial values must have the type the field emits. See
   [What each field emits](#what-each-field-emits).
 
@@ -273,8 +282,9 @@ Then, for these schemas:
 
 | Input | English | French |
 | --- | --- | --- |
-| `email: 'nope'` for `z.email()` | `Invalid email address.` | `adresse e-mail invalide.` |
-| `name: 'ab'` for `z.string().min(3)` | `This value is too small: it must be at least 3 characters.` | `Cette valeur est trop petite : elle doit être au minimum 3 caractères.` |
+| `email: 'nope'` for `z.email()` | `Invalid email address.` | `Adresse e-mail invalide.` |
+| `name: 'ab'` for `z.string().min(3)` | `Must contain at least 3 characters.` | `Doit contenir au moins 3 caractères.` |
+| `bio` too long for `z.string().max(80)` | `Must contain at most 80 characters.` | `Doit contenir au plus 80 caractères.` |
 | a missing key, or `null` / `''` / `0` given to a schema of another type (`seats: null` for `z.number()`) | `This field is required.` | `Ce champ est requis.` |
 
 A message set on the schema wins over the error map, so override one field
@@ -313,6 +323,13 @@ How it picks the language, and what that implies:
 - The message is computed when validation runs. An error already on screen
   keeps its language after a switch until the field is validated again
   (`validate()` from `useForm` re-runs it).
+- A string length reads as a length (`Must contain at most 80 characters.`);
+  a number or a list keeps the size wording (`This value is too large: it
+  must be at most 2 items.`). The strings are `material.zod.too_big_string_*`
+  and `material.zod.too_small_string_*` (`inclusive` / `exclusive`): an app
+  that overrode `too_big_inclusive` for strings overrides these now.
+- A format message that opens with its noun (`Invalid email address.`,
+  `Adresse e-mail invalide.`) starts with a capital letter in every language.
 - `invalid_type` with an empty input (`undefined`, `null`, `''`, `0`,
   `false`) says `This field is required.`; with any other input it says
   what was expected (`z.number()` given `'x'` gives
@@ -576,6 +593,42 @@ props, and `Field` does neither.
 barrel cannot render it. Use `LocationFormField` from
 `@nxgt/material-vue/map`.
 
+## Focusing the first invalid field
+
+vee-validate never moves focus: a failed `handleSubmit` reports
+`{ errors }` to its second callback and that is all (React Hook Form's
+`shouldFocusError` has no equivalent). Every `*FormField` marks the element it
+renders with `data-field-name="<name>"`, and two helpers from
+`@nxgt/material-vue/lib` use it to focus the first control a user can reach in
+a field, whatever its shape (an input, a select trigger, the first chip, a
+file picker's button, the first of two date inputs):
+
+```vue
+<script setup lang="ts">
+import { focusField, focusFirstInvalid } from '@nxgt/material-vue/lib';
+import { useForm } from 'vee-validate';
+
+const { handleSubmit, setFieldError } = useForm<Values>();
+
+// A failed submit: the first field, in page order, that has an error.
+const onSubmit = handleSubmit(save, ({ errors }) => focusFirstInvalid(errors));
+
+// A server error on one field:
+function reject() {
+  setFieldError('email', 'Already used');
+  focusField('email');
+}
+</script>
+```
+
+- `focusFirstInvalid(errors, scope?)` takes the first field in **page order**
+  whose name is in `errors`, not the first key of `errors`. Pass the form
+  element as `scope` on a page with several forms.
+- `focusField(name, scope?)` focuses one field. Both return whether a control
+  took focus: a field that is not mounted (a closed tab) cannot.
+- A field of your own that wants the same calls `useFieldBlur` (it stamps the
+  `name` prop) or sets `data-field-name` itself.
+
 ## Server errors
 
 Map an API's field errors onto the form with `setErrors` (or `setFieldError`

package/docs/guides/helpers.md

@@ -41,6 +41,7 @@ differences are listed under each table. React's `/hooks` is
 | `STYLES_UTILS.cssSize(value)` | `240` → `'240px'`, a string unchanged, `undefined` for empty. Vue does not add `px` to a numeric inline style the way React does. |
 | `searchParams(request)`, `searchParam(request, key)` | Reads the query string of a Fetch `Request` (a server handler, an edge function). |
 | `isExternalHref(href)` | True for `http(s):`, protocol-relative `//` and `mailto:`: open in a new tab, not in-app. |
+| `focusFirstInvalid(errors, scope?)`, `focusField(name, scope?)` | Focus the first control a user can reach in the first field, in page order, that has an error in `errors` (vee-validate's `onInvalid` `{ errors }`), or in the field `name`; each `*FormField` marks its element with its name for them. `scope` limits the lookup to one form; both return whether a control took focus. See [forms](forms.md#focusing-the-first-invalid-field). |
 | `buildFieldOptions(values, { valueKey, label })` | Maps records to `{ value, label }` options; `valueKey` and a string `label` are paths (`'owner.name'`), or `label` is a function. |
 | `zodLocaleError(options?)` | Zod v4 `customError` that translates issues through `material.zod.*`: `z.config({ customError: zodLocaleError() })`. Options `storageKey`, `language`, `translate` (type `ZodLocaleErrorOptions`): see [below](#zodlocaleerror-limits). |
 | `parsedType(data)` | Runtime type name used for Zod's `{received}` placeholder. |
@@ -56,7 +57,7 @@ defineProps<{
 </script>
 
 <template>
-  <tr :class="cn('border-b', order.late && 'text-error')">
+  <tr :class="cn('border-b', order.late && 'text-error-text')">
     <td>
       <template v-for="(part, i) in splitMatch(order.ref, query)" :key="i">
         <mark v-if="part.match">{{ part.text }}</mark>

package/docs/guides/i18n.md

@@ -278,10 +278,13 @@ previous and next buttons, `DateRangeField`'s included (`material.calendar.*`),
 checkboxes, the filter's presets and `Min`/`Max` fields, the `variant="4"` spinner's label,
 `ScrollToTop`, the network upload field's `Retry`/`Remove`, the map's
 `You are here` and zoom buttons, and the close button of dialogs, sheets and
-`DialogFooter`. The other icon-only buttons are named from it too: the
+`DialogFooter`. `CopyButton` reads `material.copy.copy`, `copied` and `failed` ("Copy", "Copied",
+"Copy failed"). The other icon-only buttons are named from it too: the
 `Sidebar` toggle (`material.sidebar.toggle`), the data table's row expander
 (`material.table.labels.toggle-row`), its loading status, "Loading data…" /
-"Chargement des données…" (`material.table.loading`), a `Chip`'s remove button, which the
+"Chargement des données…" (`material.table.loading`), its scroll region,
+"Scrollable table" / "Tableau défilant"
+(`material.table.labels.scroll-region`, or the `scroll-label` prop), a `Chip`'s remove button, which the
 `Autocomplete` chips use ("Remove {label}", `material.chip.dismiss-label`),
 the `LocationPreview` trigger (`material.map.preview` / `preview-named`),
 `DurationField`'s inputs, "Hours" and "Minutes"

package/docs/guides/ssr.md

@@ -275,7 +275,7 @@ export default defineNuxtPlugin((nuxtApp) => {
 | `getActivePinia()` was called but there was no active Pinia | a widget rendered on the server before Pinia was installed | `app.use(createPinia())` in the server entry too; in Nuxt the module does it |
 | Text flips language right after load | no `initial-language` | Pass the request's language ([i18n](i18n.md#server-rendering)) |
 | Hydration mismatch around an icon | an `<svg><title>` in your markup | `role="img"` + `aria-label` |
-| Hydration mismatch on a phone around a `ResponsiveButton`, the app shell or a `DataTable`, or on a dark screen around a code block, 0.21.0 or earlier | the server answered "desktop, light", the phone's first render its own screen | upgrade ([troubleshooting](../troubleshooting.md#hydration-completed-but-contains-mismatches)) |
+| Hydration mismatch on a phone around the app shell or a `DataTable`, or on a dark screen around a code block, 0.21.0 or earlier | the server answered "desktop, light", the phone's first render its own screen | upgrade ([troubleshooting](../troubleshooting.md#hydration-completed-but-contains-mismatches)) |
 | Hydration mismatch on a page with a `TimeField`, 0.21.0 or earlier | the server rendered the phone (dialog) trigger, a desktop client the popover one | upgrade ([troubleshooting](../troubleshooting.md#hydration-completed-but-contains-mismatches)) |
 
 More entries, with the full message and fix, are in