@nxgt/material-vue 0.26.1 → 0.28.0

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`
 
 ---
@@ -570,12 +584,12 @@ use `DataTable` on the [Data table, filter & lists](data-table-filter-and-lists.
 
 ![Tabs](../previews/primitives-tabs.webp)
 
-Tabs whose triggers can take an icon. `variant="line"` is the quieter pill style.
+Tabs whose triggers can take an icon, in two looks: `underline` (the default) and the `segmented` pill.
 
 ```vue
 <script setup lang="ts">
+import { Calendar, User } from '@lucide/vue';
 import {
-  Icon,
   Tabs,
   TabsContent,
   TabsList,
@@ -586,8 +600,11 @@ import {
 <template>
   <Tabs default-value="account" class="w-md">
     <TabsList>
-      <TabsTrigger value="account"><Icon name="user" />Account</TabsTrigger>
-      <TabsTrigger value="calendar"><Icon name="calendar" />Calendar</TabsTrigger>
+      <TabsTrigger value="account" :icon="User">Account</TabsTrigger>
+      <TabsTrigger value="calendar">
+        <template #icon><Calendar /></template>
+        Calendar
+      </TabsTrigger>
     </TabsList>
     <TabsContent value="account">Your profile.</TabsContent>
     <TabsContent value="calendar">Your events.</TabsContent>
@@ -595,36 +612,96 @@ import {
 </template>
 ```
 
-Parts: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`. An icon goes in the
-trigger's slot, before the label; there is no `icon` prop in Vue. By default
-(`variant="bar"`) the list is one muted pill with the active trigger raised.
-`variant="line"` is React's quieter style: a full-width, scrolling strip of
-light tabs, the active one on the background — `TabsList` and `TabsTrigger`
-read it from `Tabs`.
+Parts: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`. `TabsList` and
+`TabsTrigger` read the look from `Tabs`. A trigger's icon goes before its
+label, as `@nxgt/material`'s `icon`: pass a component to the `icon` prop, or
+fill the `#icon` slot. An icon written in the default slot still renders
+beside the label.
+
+**`underline`** (the default) lays the tabs over a border; the active one
+takes the primary colour, and a bar under it slides to the tab clicked or
+reached with the arrow keys. The list scrolls sideways when the tabs do not
+fit (its scrollbar hidden), which suits a phone or a narrow popover.
+
+**`segmented`** is a neutral pill track: the active tab sits on a raised
+surface that slides between tabs, and its label turns to the foreground
+colour and semibold — the state never rests on the surface alone. It suits a
+few short choices, such as a view switch.
+
+```vue
+<template>
+  <Tabs default-value="week" variant="segmented">
+    <TabsList>
+      <TabsTrigger value="day">Day</TabsTrigger>
+      <TabsTrigger value="week">Week</TabsTrigger>
+      <TabsTrigger value="month">Month</TabsTrigger>
+    </TabsList>
+    <TabsContent value="day">Today.</TabsContent>
+    <TabsContent value="week">This week.</TabsContent>
+    <TabsContent value="month">This month.</TabsContent>
+  </Tabs>
+</template>
+```
+
+`orientation="vertical"` lays the tabs in a column, the indicator on their
+left side; the arrow keys become Up and Down.
 
 ```vue
 <template>
-  <Tabs default-value="ts" variant="line">
+  <Tabs default-value="profile" orientation="vertical">
     <TabsList>
-      <TabsTrigger value="ts">TypeScript</TabsTrigger>
-      <TabsTrigger value="bash">Bash</TabsTrigger>
+      <TabsTrigger value="profile">Profile</TabsTrigger>
+      <TabsTrigger value="security">Security</TabsTrigger>
     </TabsList>
-    <TabsContent value="ts">const n = 1;</TabsContent>
-    <TabsContent value="bash">bun install</TabsContent>
+    <TabsContent value="profile">Your profile.</TabsContent>
+    <TabsContent value="security">Your sessions.</TabsContent>
   </Tabs>
 </template>
 ```
 
+The sliding indicator is reka's `TabsIndicator`, which renders once mounted:
+server HTML, and a page without JavaScript, show a static indicator under (or
+behind) the active tab instead, and hydrating swaps one for the other without
+a mismatch. The list then carries `data-indicator="ready"`. The focus ring is
+an outline in the primary colour inside the tab, so a scrolling list never
+clips it.
+
+With `TabsList asChild`, only the static indicator is drawn.
+
+`dir="rtl"` on `Tabs` (or reka's `ConfigProvider`) runs the tabs from the
+right: the indicator follows them, and the Left arrow key moves to the next
+tab. Under `prefers-reduced-motion: reduce` the indicator jumps to the active
+tab instead of sliding.
+
+**A tab with only an icon needs a name.** A screen reader announces a
+`TabsTrigger` by its text; with an icon and no label it is only "tab". Give it
+`aria-label`, and `title` for sighted users who hover it:
+
+```vue
+<TabsTrigger value="recent" :icon="Clock" aria-label="Recent" title="Recent" />
+```
+
+The emoji picker's group tabs are named this way, from
+`material.emoji.groups.*`.
+
+**The default look changed.** A `Tabs` with no `variant` used to render the
+`bar` look (one muted pill with the active trigger raised); it now renders
+`underline`. `variant="bar"` and `variant="line"` are deprecated aliases:
+`bar` renders as `underline`, `line` as `segmented`. Both still type-check and
+render; write `underline` or `segmented` instead.
+
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `variant` (`Tabs`) | `'bar' \| 'line'` | `'bar'` | the look of the list and its triggers |
+| `variant` (`Tabs`) | `'underline' \| 'segmented' \| 'bar' \| 'line'` | `'underline'` | the look; `bar` and `line` are deprecated aliases of `underline` and `segmented` |
 | `default-value` / `v-model` (`Tabs`) | `string \| number` | — | the selected tab, uncontrolled / controlled |
-| `orientation` (`Tabs`) | `'horizontal' \| 'vertical'` | `'horizontal'` | arrow-key direction |
+| `orientation` (`Tabs`) | `'horizontal' \| 'vertical'` | `'horizontal'` | a row or a column, and the arrow keys' direction |
+| `dir` (`Tabs`) | `'ltr' \| 'rtl'` | `'ltr'` | the reading direction: which way the tabs run and the arrow keys move |
 | `activation-mode` (`Tabs`) | `'automatic' \| 'manual'` | `'automatic'` | select on focus, or only on Enter / click |
 | `value` (`TabsTrigger`, `TabsContent`) | `string \| number` | — (required) | pairs a trigger with its panel |
+| `icon` (`TabsTrigger`) | `Component` | — | shown before the label; or the `#icon` slot |
 
 **Emits:** `update:modelValue` on `Tabs` — `string | number`.
-**Storybook:** `Primitives/Tabs` (story `Line`) · **React:** `Tabs` (same parts)
+**Storybook:** `Primitives/Tabs` (stories `Underline`, `Segmented`, `WithIcons`, `Scrolling`, `RightToLeft`, `Vertical`, `DeprecatedAliases`, `Hydrated`) · **React:** `Tabs` (same parts, the same variants)
 
 ---
 

package/docs/components/rich-widgets.md

@@ -272,6 +272,16 @@ const emojis: EmojiItem[] = [
 Parts: `EmojiPicker` (a button opening a popover), `EmojiList` (the searchable
 grid on its own, same `emojis` / `@select`), `expandEmojiShortcodes`.
 
+The category tabs are icon-only. Each is named from
+`material.emoji.groups.<group>` (for example `people_body`, `flags`): that name
+is its `aria-label` and `title`, in the provider's language (see
+[i18n](../guides/i18n.md)). An `EmojiItem` with no `group` falls under
+`general`; a `group` is lowercased, with ` & ` and spaces turned into `_`
+("Food & Drink" becomes `food_drink`). A group the bundles do not name gets
+its words, capitalised, as an English name (`hand_signs` becomes "Hand
+signs"), and an icon of its own is not provided: it shows the generic grid
+icon.
+
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `emojis` | `EmojiItem[]` | — (required) | the set offered; `group` drives the category tabs, `shortcodes` the search |

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"
@@ -402,10 +405,27 @@ and description and against the English ones, ignoring accents: in French,
 
 Some strings are still English in every language, among them the filter's
 validation messages, the camera's error messages, the editor's callout type
-names and default block content, and the names of the emoji picker's category
-tabs. File sizes (`2.0 KB`) and the filter chips' dates are not formatted for
+names and default block content. File sizes (`2.0 KB`) and the filter chips' dates are not formatted for
 the provider's language.
 
+The emoji picker's category tabs are icon-only; their name, read by screen
+readers and shown as a tooltip, comes from `material.emoji.groups.<group>`.
+Both languages ship `all`, `recent`, `general`, `people_body`, `components`,
+`animals_nature`, `food_drink`, `travel_places`, `activities`, `objects`,
+`symbols` and `flags`:
+
+```ts
+// English / French values of the shipped keys
+material.emoji.groups.people_body; // "People & body" / "Personnes et corps"
+material.emoji.groups.food_drink;  // "Food & drink" / "Nourriture et boissons"
+material.emoji.groups.flags;       // "Flags" / "Drapeaux"
+```
+
+A group your `EmojiItem`s name that is not in this list (`hand_signs`) reads
+as its words in English (`Hand signs`). As for every `material.*` key above,
+the components read their own bundle: your own translator sees a key you add,
+the tab does not.
+
 That override is visible only through **your** translator. The components
 translate through the package's own bundle, so defining
 `material.command.title` in your resources changes what

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