@nxgt/material 2.7.1 → 2.9.0

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

@@ -59,11 +59,14 @@ which work alone.
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `items` | `MenuItem[]` | — | `label` (already translated), `url`, `icon`, `footer` |
+| `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href`; see the [app shell guide](../guides/app-shell.md) |
 | `brand` | `ReactNode` | — | sidebar header |
 | `avatar` | `ReactNode` | — | an image URL or a node, in the header |
 | `headerActions` | `ReactNode` | — | header, before the avatar |
 | `title`, `subtitle`, `actions` | `ReactNode` | — | `ActivityContent`'s header card |
 | `header` / `hideHeader` | `ReactNode` / `boolean` | — | `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 `handle.breadcrumb` from `useMatches()`, so the shell
@@ -110,12 +113,27 @@ import {
 ```
 
 Parts: `Sidebar`, `SidebarHeader`, `SidebarContent`, `SidebarFooter`,
-`SidebarMenuLabel` (`actions` slot), `SidebarMenuItem` (a button: `icon`,
+`SidebarMenuLabel` (`actions` slot), `SidebarMenuItem` (a button, or a link with `href` and `linkComponent`: `icon`,
 `active`, `tooltip`).
 
+A `SidebarMenuItem` stays a `<button>` without `href`. With `href` it renders a
+real link, a plain `<a>` unless you pass `linkComponent` (given the `href`):
+
+```tsx
+<SidebarMenuItem href="/inbox" linkComponent={MyLink} icon={<Inbox />}>Inbox</SidebarMenuItem>
+```
+
+An entry's tooltip is its label, shown by default **only while the
+`Sidebar` is collapsed**: expanded, the label is on screen and no tooltip
+opens. A `tooltip` you pass is always shown, collapsed or expanded:
+
+```tsx
+<SidebarMenuItem icon={<Inbox />} tooltip="3 unread">Inbox</SidebarMenuItem>
+```
+
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `expanded` | `boolean` | `false` | labels beside the icons; collapsed shows icons with tooltips |
+| `expanded` | `boolean` | `false` | labels beside the icons; collapsed shows icons with their labels as tooltips |
 | `onExpandedChange` | `(expanded: boolean) => void` | — | called by the toggle |
 | `withToggleIcon` | `boolean` | `false` | built-in expand / collapse button, shown on hover or while focus is inside the sidebar, named "Toggle sidebar" (`material.sidebar.toggle`) with `aria-expanded` |
 
@@ -573,7 +591,7 @@ import { Background, Card } from '@nxgt/material/components';
 </Background>
 ```
 
-No props of its own. It fills the viewport (`size-lv`); pass a `className`
+No props of its own. It fills the viewport (`w-lvw h-lvh`); pass a `className`
 such as `h-96 w-full` to use it as a band. `ActivityLayout` and
 `ThreadLayout` sit on it.
 

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

@@ -8,6 +8,19 @@ command palette) with this library's styling, and render into a portal on
 [Feedback & status](feedback-and-status.md). Everything is imported from
 `@nxgt/material/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 `onOpenAutoFocus`
+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 an icon close button |
@@ -92,7 +105,7 @@ export function Terms() {
 | --- | --- | --- | --- |
 | `defaultOpen` / `open` (`Dialog`) | `boolean` | `false` | open state, uncontrolled / controlled |
 | `onOpenChange` (`Dialog`) | `(open: boolean) => void` | — | called on trigger, Escape, outside click and close |
-| `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 |
 | `asChild` (`DialogTrigger`) | `boolean` | **`true`** | the trigger is its child — pass one element, usually a `Button` |
 | `variant`, `color` (`DialogClose`) | as `IconButton` | `'ghost'` | a top-right X button, named "Close" (`material.buttons.close`, translated) while it shows only the icon; text children or an `aria-label` name it instead, and icon-only children leave it unnamed; children replace the X |
 
@@ -100,8 +113,9 @@ export function Terms() {
 It ignores outside clicks that land on an open `Combobox` list, so a combobox
 inside a dialog works. On open it moves focus into the dialog: to its first
 control, or to the content itself when it has none. An `onOpenAutoFocus` of
-yours that calls `event.preventDefault()` keeps focus where it was (then focus
-what you want yourself).
+yours that calls `event.preventDefault()` keeps focus off that control (then
+focus what you want yourself): a modal dialog then focuses its content, as the
+page behind it is inert, and a non-modal one leaves focus where it was.
 On close it hands focus back to the element that had it when the dialog
 opened — its `DialogTrigger`, or the button of yours that set `open` on a
 controlled `Dialog` — if that element is still on the page and focus has not
@@ -368,7 +382,7 @@ the fullscreen element shows.
 
 ![DropdownMenu](../previews/overlays-menus-dropdownmenu.webp)
 
-Menu with checkbox and radio items, submenus, shortcuts and an error item.
+Menu with checkbox and radio items, submenus, shortcuts and an error item. It is non-modal by default: Radix'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 or an outside click (Tab stays in the menu). Pass `modal` for a modal one: the page behind it is then `inert` too, so its controls leave the tab order and axe passes.
 
 ```tsx
 import {
@@ -408,11 +422,12 @@ Parts: `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`,
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
+| `modal` (`DropdownMenu`) | `boolean` | `false` | `true` brings back Radix's modal menu: scroll lock, outside clicks swallowed, the rest of the page `aria-hidden` and `inert` |
 | `variant` (`DropdownMenuItem`) | `'default' \| 'error'` | `'default'` | error colour for a destructive item |
-| `active` (`DropdownMenuItem`) | `boolean` | — | highlights the current item (filled primary) |
+| `active` (`DropdownMenuItem`) | `boolean` | — | highlights the current item (filled primary) and sets `data-active` on it; style or select it with `data-[active]:` or `[data-active]` |
 | `inset` (item, label, sub-trigger) | `boolean` | — | indents to line up with checkbox and radio items |
 | `onSelect` (`DropdownMenuItem`) | `(event: Event) => void` | — | the item's action; `event.preventDefault()` keeps the menu open |
-| `defaultOpen` / `open`, `modal` (`DropdownMenu`) | `boolean` | —, `true` | open state; a modal menu blocks the page behind it |
+| `defaultOpen` / `open` (`DropdownMenu`) | `boolean` | — | open state; see `modal` above for the page behind the menu |
 | `container` (`DropdownMenuContent`) | `Element \| DocumentFragment \| null` | `document.body` | where the menu is portalled; for a menu opened in fullscreen, pass `document.fullscreenElement`, read when the menu opens (see [troubleshooting](../troubleshooting.md#a-dropdownmenu-opened-in-fullscreen-does-not-show)) |
 
 **Storybook:** `Overlays & menus/DropdownMenu` · **Vue:** `DropdownMenu` (same parts)

package/docs/components/primitives.md

@@ -147,7 +147,9 @@ import {
 ```
 
 Parts: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`,
-`CardContent`, `CardFooter` — each a styled `<div>` taking its element's props.
+`CardContent`, `CardFooter` — each a styled `<div>` taking its element's props,
+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` · **Vue:** `Card` (same parts)
@@ -224,12 +226,24 @@ import { Input, Label } from '@nxgt/material/components';
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `withAsterisk` | `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 |
+| `withAsterisk` | `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 |
 | `htmlFor` | `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` · **Vue:** `Label`
 
 ---
@@ -559,7 +573,7 @@ For sorting, paging and selection use `DataTable` on the
 
 ![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.
 
 ```tsx
 import {
@@ -584,16 +598,91 @@ import {
 </Tabs>;
 ```
 
-Parts: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`.
+Parts: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`. `TabsList` and
+`TabsTrigger` read the look from `Tabs`.
+
+**`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.
+
+```tsx
+<Tabs defaultValue="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>
+```
+
+`orientation="vertical"` lays the tabs in a column, the indicator on their
+left side; the arrow keys become Up and Down.
+
+```tsx
+<Tabs defaultValue="profile" orientation="vertical">
+	<TabsList>
+		<TabsTrigger value="profile">Profile</TabsTrigger>
+		<TabsTrigger value="security">Security</TabsTrigger>
+	</TabsList>
+	<TabsContent value="profile">Your profile.</TabsContent>
+	<TabsContent value="security">Your sessions.</TabsContent>
+</Tabs>
+```
+
+The sliding indicator is measured once the page runs: 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 changing
+the markup. 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` the list is your child element and the sliding
+indicator is placed inside it, measured against it, so the child must render
+its children directly: a component child that wraps them in an inner element
+hides the indicator.
+
+`dir="rtl"` on `Tabs` (or Radix's `DirectionProvider`) 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:
+
+```tsx
+<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
+boxed `bar` look (a primary ring around the active tab, a smaller label under
+its icon on the phone); 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'` | full-width bar of equal triggers, or the quieter line style |
+| `variant` (`Tabs`) | `'underline' \| 'segmented' \| 'bar' \| 'line'` | `'underline'` | the look; `bar` and `line` are deprecated aliases of `underline` and `segmented` |
 | `defaultValue` / `value` (`Tabs`) | `string` | — | the selected tab, uncontrolled / controlled |
 | `onValueChange` (`Tabs`) | `(value: string) => void` | — | called when a trigger is selected |
-| `icon` (`TabsTrigger`) | `ReactNode` | — | shown before the label (above it on the phone in `bar`) |
+| `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 |
+| `icon` (`TabsTrigger`) | `ReactNode` | — | shown before the label |
 
-**Storybook:** `Primitives/Tabs` · **Vue:** `Tabs` (same parts, `variant="line"`)
+**Storybook:** `Primitives/Tabs` (stories `Underline`, `Segmented`, `WithIcons`, `Scrolling`, `RightToLeft`, `Vertical`, `DeprecatedAliases`, `Hydrated`) · **Vue:** `Tabs` (same parts, the same variants, `icon` prop or `#icon` slot)
 
 ---
 

package/docs/components/rich-widgets.md

@@ -244,6 +244,16 @@ const EMOJIS: EmojiItem[] = [
 Parts: `EmojiPicker` (a button opening a popover), `EmojiList` (the searchable
 grid on its own, same `emojis` / `onSelect`), `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[]` | — | the set offered; `group` drives the category tabs, `shortcodes` the search |

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

@@ -30,7 +30,9 @@ value type each one writes. Everything is imported from
 
 ![Select](../previews/selection-choice-select.webp)
 
-Select primitives with groups, labels and scroll buttons.
+Select primitives with groups, labels and scroll buttons. 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).
 
 ```tsx
 import {
@@ -132,9 +134,13 @@ export function Framework() {
 | `onValueChange` | `(value: string) => void` | — | Radix Select's |
 | `renderOption` | `(option: SelectOption) => ReactNode` | — | custom item content |
 | `placeholder` | `ReactNode` | `label` | the trigger's text while nothing is selected |
-| `required` | `boolean` | — | an asterisk after the label, and Radix Select's `required` |
+| `required` | `boolean` | — | an asterisk after the label, and Radix Select's `required`; the trigger is named by the label |
 | `label`, `helperText`, `error` | | — | the field's text and state |
 
+**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:** `string`.
 **Form wrapper:** `SelectFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
@@ -530,6 +536,11 @@ export function Topics() {
 | `onValueChange` | `(value: string[]) => void` | — | |
 | `options` | `{ value, label, icon? }[]` | — | the chips |
 
+**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:** `string[]`. `SelectChipFormField` stores `string | null` in
 `single` mode (`null` once the choice is cleared; `''` and `null` both show
 nothing selected) and `string[]` in `multiple`. Options are matched by

package/docs/getting-started.md

@@ -20,7 +20,7 @@ hooks throw ("Invalid hook call") and design tokens come from two builds.
 | `react-hook-form` | `^7` | every `*FormField` wrapper ([forms](guides/forms.md)) |
 | `react-redux`, `@reduxjs/toolkit` | `^9`, `^2` | `DataTable`, filter, gallery, kanban, player, the slice helpers in `/lib` |
 | `@tanstack/react-table` | `^9` | `DataTable` |
-| `react-use` | `^17` | `useTheme`, `useIsMobile`, `ScrollProgress` (`useScroll` / `useWindowScroll`), `CopyButton` (`useCopyToClipboard`), other hooks |
+| `react-use` | `^17` | `useTheme`, `useIsMobile`, `ScrollProgress` (`useScroll` / `useWindowScroll`), other hooks |
 
 **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.
@@ -255,7 +255,9 @@ A `ConfirmationDialog` given `open` follows it, and closes only through
 open (an alert dialog to its Cancel), and hand it back on close. A test that
 types or presses a key right after opening one now acts inside it
 ([details](troubleshooting.md#keys-typed-right-after-opening-a-dialog-sheet-or-drawer-land-inside-it)).
-To keep focus where it was, prevent the default:
+To keep focus off the first control, prevent the default (on a modal it
+lands on the content, as the page behind is inert;
+[details](troubleshooting.md#focus-moves-into-a-dialog-although-onopenautofocus-prevented-it)):
 
 ```tsx
 <DialogContent onOpenAutoFocus={(event) => event.preventDefault()}>{/* … */}</DialogContent>

package/docs/guides/app-shell.md

@@ -51,8 +51,8 @@ wraps. Each leaf route renders `ActivityContent`.
 `useMatches()`. That hook only works under a **data router**:
 `createBrowserRouter` / `createMemoryRouter` + `RouterProvider`, or a
 framework-mode app. Under `<BrowserRouter>` or `<MemoryRouter>` it throws
-`useMatches must be used within a data router.`. The sidebar and header also
-navigate with `react-router`, so the shell cannot render outside a router.
+`useMatches must be used within a data router.`. The sidebar entries are React Router `Link`s too, so the shell cannot render
+outside a router.
 
 In a test or a story:
 
@@ -142,10 +142,36 @@ partitionMenu(items);                              // { content, footer }
 | `items` | `MenuItem[]` | — | Sidebar entries, and the mobile menu sheet |
 | `brand` | `ReactNode` | — | Replaces the sidebar header: a logo, a product name |
 | `avatar` | `ReactNode` | — | End of the header. A `string` is used as the image URL of an `Avatar`; anything else is rendered as-is |
+| `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href` (see below) |
 | `headerActions` | `ReactNode` | — | In the header, before the avatar: notifications, help, `ThemeToggle` |
 | `children` | `ReactNode` | — | The routed content, usually `<Outlet />` |
+| `contentAs` | `'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 |
+
+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 React Router `Link` (client-side navigation, the router's
+`basename`), so leaving `linkComponent` out never reloads the page. Pass it only
+for another router or a custom link: a component taking
+`href`. It must spread **every other prop it receives** onto the element it
+renders (`className`, `aria-current`, the tooltip's handlers, `data-state`) and
+forward `ref`: the styling, the tooltip and the current-page mark arrive that
+way. A link that forwards only a `DataTable`'s `DataTableLinkProps` is not
+enough here.
 
-The rest of `div` props (`className`, `id`…) go to the outer container.
+```tsx
+import { Link } from 'react-router';
+import type { AppShellLinkComponent } from '@nxgt/material/components';
+
+// Spread everything but `href`; `ref` is a prop in React 19.
+const MyLink: AppShellLinkComponent = ({ href, ...props }) => <Link to={href} {...props} />;
+// <ActivityLayout items={items} linkComponent={MyLink}>…</ActivityLayout>
+```
+
+`className` and the rest of the `div` props (`id`, `data-*`…) go to the outer
+element, `[data-slot=activity-layout]`.
 `avatar` and `headerActions` are props because the shell holds no session:
 read the user wherever your app keeps it and pass the node.
 
@@ -180,7 +206,54 @@ export function Shell({ items, user }: { items: MenuItem[]; user: { name: string
 ```
 
 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.
+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 change of location, 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 `contentAs="div"`: a page has only one.
+- **The screen's title is the `h1`.** `ActivityContent`'s `title` is a heading,
+  level 1 by default (`titleAs`); 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 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, React
+  Router's `<ScrollRestoration />` handles positions as for any page. With
+  `scroll="container"` the content region outlives navigations, and
+  `ScrollRestoration` only knows the window, so the shell does it for that
+  box: a new pathname opens at the top, and Back or Forward (a `POP`) returns
+  to where that entry was left (kept per `location.key`, for the session). A
+  change of query or hash only (a filter, a tab, an `#anchor`) keeps the
+  position.
+
+```tsx
+import { Outlet } from 'react-router';
+import { ActivityLayout, type MenuItem } from '@nxgt/material/components';
+
+// The app renders its own <main>, and the board below needs a fixed height.
+export function BoardShell({ items }: { items: MenuItem[] }) {
+  return (
+    <main>
+      <ActivityLayout items={items} contentAs="div" scroll="container">
+        <Outlet />
+      </ActivityLayout>
+    </main>
+  );
+}
+```
 
 ## `ActivityContent`
 
@@ -191,6 +264,7 @@ button that opens the same entries in a sheet. Breadcrumbs are hidden there.
 | `actions` | `ReactNode` | — | Right side of the header card: buttons |
 | `header` | `ReactNode` | — | Replaces the header card entirely |
 | `hideHeader` | `boolean` | `false` | No header card |
+| `titleAs` | `'h1'` … `'h6'` \| `'div'` | `'h1'` | The title's element: the screen's heading, `'h2'` under a heading of yours, `'div'` for none |
 
 ```tsx
 import { ActivityContent, Button } from '@nxgt/material/components';
@@ -208,6 +282,9 @@ export function InvoicesPage() {
 }
 ```
 
+The header card wraps: on a narrow screen the actions go under the title
+instead of squeezing it, and a long title wraps rather than scrolling.
+
 ## Breadcrumbs
 
 `AppBreadcrumb` (rendered by `ActivityLayout`) starts with a home icon linking
@@ -272,3 +349,19 @@ own. They take the same `items`; `AppHeader` takes `actions`, `avatar` and
 `showMenuIcon` (default `true`). The lower-level `Sidebar`, `TopAppBar` and
 `Breadcrumb` primitives are on the
 [navigation & layout](../components/navigation-and-layout.md) page.
+
+`AppHeader` needs a React Router context even on its own: its menu sheet reads
+the location (`useLocation`) to close when it changes, and outside a router
+that hook throws. Render it under your `RouterProvider` — or, in a test, inside
+a `MemoryRouter`:
+
+```tsx
+import { MemoryRouter } from 'react-router';
+import { AppHeader } from '@nxgt/material/components';
+
+render(
+  <MemoryRouter>
+    <AppHeader items={items} />
+  </MemoryRouter>,
+);
+```

package/docs/guides/forms.md

@@ -57,7 +57,7 @@ What a wrapper does for you, from the field state of `name`:
 | `helperText` | `fieldState.error?.message`, or your own `helperText` when there is no error |
 | `disabled` | your own `disabled`, or `field.disabled` from React Hook Form |
 | `name` | the field `name` |
-| `id` | yours when you pass one. Otherwise the text-like wrappers (text, number, date…) use the field `name`, so two forms on one page sharing a field name get the same `id`: pass your own. `SwitchFormField`, `CheckboxFormField`, `SliderFormField`, `RadioGroupFormField` and `CheckboxGroupFormField` generate one instead; a group's option *i* is `` `${id}-${i}` `` |
+| `id` | yours when you pass one. Otherwise every wrapper generates one (`useId`), never the field `name`, so two forms on one page sharing a field name (a sign-in and a sign-up form) keep their labels apart; a group's option *i* is `` `${id}-${i}` `` |
 | `aria-labelledby` / `aria-describedby` | on `RadioGroupFormField` and `CheckboxGroupFormField`, the `radiogroup` / `group` is named by its `label` (`` `${id}-label` ``) and described by the helper or error text (`` `${id}-helper` ``), so a screen reader announces the question and the error with the group. The `radiogroup` also gets `aria-invalid`; the checkbox `group` does not (ARIA forbids it there), its error is its description — for an error with no message, a hidden "This value is not valid." inside your `helperText`. Your own `aria-label` / `aria-labelledby` wins; your `aria-describedby` ids are kept, first |
 
 Every wrapper has the same shape: the React Hook Form half and the field's own
@@ -223,8 +223,18 @@ export function SubscribeForm({
   schema's input type match what `NumberFormField` emits, and a cleared field
   fails with "This field is required.".
 - `Button` defaults to `type="button"`: the submit button needs
-  `type="submit"`. `loading` shows a spinner and ignores clicks while the
-  promise returned by `onSave` is pending.
+  `type="submit"`. With `loading={form.formState.isSubmitting}` it is busy
+  (`aria-busy`, `aria-disabled`, a spinner) from the first click until the
+  promise returned by `onSave` 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` (a
+  mutation's `isPending`), add `lockOnClick`
+  ([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 `formState.isSubmitting` itself. A
+  `lockOnClick` whose `loading` never turns true releases after one second.
 - Default values must have the type the field emits. See
   [What each field emits](#what-each-field-emits).
 
@@ -247,8 +257,9 @@ Then, for the schema of [A complete form](#a-complete-form):
 
 | Input | English | French |
 | --- | --- | --- |
-| `email: 'nope'` | `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'` | `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 (`undefined`) | `This field is required.` | `Ce champ est requis.` |
 
 A message set on the schema wins over the error map, so override one field
@@ -280,6 +291,13 @@ How it picks the language, and what that implies:
   (`form.trigger()` re-runs it).
 - It is safe on a server: with no `localStorage` (or when reading it throws)
   it writes English, unless you pass `language`.
+- 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` says what was expected (`z.number()` given a string says
   `This value must be a number.`); a type with no string of its own says
   `This value has the wrong type.`
@@ -520,6 +538,37 @@ own entry, so the main barrel cannot render it. Use `LocationFormField` from
 `Field` is the same renderer without React Hook Form: `<Field config={…} />`,
 where the config carries `value` and `onChange` / `onValueChange` itself.
 
+## Focusing the first invalid field
+
+React Hook Form moves focus to the first invalid field on a failed
+`handleSubmit` (`shouldFocusError`, on by default), and to the field you name
+in `setError(name, error, { shouldFocus: true })` or `setFocus(name)`. It does
+that by calling `focus()` on the `ref` the field registered, which every
+`*FormField` (and the config-driven `FormField`) hands over: an input takes
+it directly; a field made of several controls (a select, a group of chips, a
+date range, an upload, a dialog editor) hands over a handle that focuses the
+first control a user can reach in it.
+
+```tsx
+const form = useForm<Values>({ resolver: zodResolver(schema) });
+
+// A failed submit focuses the first invalid field, nothing to wire:
+<form onSubmit={form.handleSubmit(save)}>…</form>
+
+// A server error on one field:
+form.setError('email', { type: 'server', message: 'Already used' }, { shouldFocus: true });
+form.setFocus('email'); // or without an error
+```
+
+- Only a **mounted** field takes focus: React Hook Form skips one in a closed
+  tab or a collapsed section, so open it before calling `setError`.
+- `FilterFormField` is the exception: it holds criteria, not a value that can
+  be invalid.
+- A field of your own passes `field.ref` to its control:
+  `<input {...field} />` (`{...field}` carries `ref`).
+- If focus does not move, see
+  [`setError(…, { shouldFocus: true })` does nothing](../troubleshooting.md#seterror--shouldfocus-true--or-a-failed-submit-does-not-focus-the-field).
+
 ## Server errors
 
 Map an API's field errors onto the form with `setError`, and put anything that

package/docs/guides/helpers.md

@@ -45,7 +45,7 @@ import { cn, DATE_UTILS, formatNumber, searchParam, splitMatch } from '@nxgt/mat
 
 export function OrderRow({ order, query }: { order: { ref: string; total: number; createdAt: string; late: boolean }; query: string }) {
   return (
-    <tr className={cn('border-b', order.late && 'text-error')}>
+    <tr className={cn('border-b', order.late && 'text-error-text')}>
       <td>
         {splitMatch(order.ref, query).map((part, i) =>
           part.match ? <mark key={i}>{part.text}</mark> : <span key={i}>{part.text}</span>,
@@ -119,7 +119,7 @@ Vue: the Redux helpers are Pinia store factories: `defineLocalStore`
 | `useTheme()` | `{ theme, preference, updateTheme }`: light / dark / system, stored in `localStorage`, applied as the `dark` class. See [theming](theming.md#usetheme). |
 | `resolveTheme(stored, prefersDark)`, `applyResolvedTheme(theme)` | The pure theme logic behind `useTheme`, for a boot script. |
 | `useIsClient()` | `false` on the server and first render, `true` after mount: a hydration guard. |
-| `useIsMobile()` | `true` below 768 px. `false` on the server and while hydrating, so SSR HTML is the desktop layout; a phone switches right after. |
+| `useIsMobile()` | `true` below 768 px (`ResponsiveButton` no longer uses it: it collapses with CSS). `false` on the server and while hydrating, so SSR HTML is the desktop layout; a phone switches right after. |
 | `useHeadingSpy(ids, onActive, options?)` | IntersectionObserver over heading ids; reports the topmost visible one. |
 | `useLocalizedDate()` | `{ language, locale, format }`: `DATE_UTILS.format` bound to the `I18nProvider` language (`en` without a provider). |
 | `useNumberFormatter()` | `{ formatNumber, formatCurrency }`: `Intl.NumberFormat` with the options you pass, bound to the `I18nProvider` language (`en-US` without a provider). For what `formatAmount` does not cover: percentages, units, compact notation. |

package/docs/guides/i18n.md

@@ -206,10 +206,13 @@ presets and `Min`/`Max` fields, the `variant="4"` spinner's label,
 `withCloseButton`. A range `Slider`'s readout inputs read
 `material.slider.minimum` / `maximum` ("Minimum", "Maximum"), and a
 single value's input, when nothing names the slider, `material.slider.value`
-("Value", "Valeur"). The other icon-only buttons are named from it too: the
+("Value", "Valeur"). `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 — `Chip`,
+"Chargement des données…" (`material.table.loading`), its scroll region,
+"Scrollable table" / "Tableau défilant"
+(`material.table.labels.scroll-region`, or the `scrollLabel` prop), a chip's remove button — `Chip`,
 `ComboboxChip` and the `Autocomplete` chips, "Remove {label}"
 (`material.chip.dismiss-label`) — the `LocationPreview` trigger
 (`material.map.preview` / `preview-named`), and the delete button of the
@@ -324,10 +327,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.
+
 ```tsx
 // Under <I18nProvider defaultLanguage="fr">
 <CarouselNext />            // screen reader: "Diapositive suivante"