@nxgt/material-vue 0.41.0 → 0.43.0

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

@@ -11,7 +11,8 @@ centre. Everything is imported from `@nxgt/material-vue/components`.
 | <img src="../previews/feedback-status-alertdialog.webp" width="96" alt=""> | [AlertDialog](#alertdialog) | Parts for a blocking confirmation dialog |
 | <img src="../previews/feedback-status-confirmdialog.webp" width="96" alt=""> | [ConfirmDialog](#confirmdialog) | Confirm / cancel dialog, `ConfirmationDialog`, `CustomAlertDialog` |
 | <img src="../previews/feedback-status-customdialog.webp" width="96" alt=""> | [CustomDialog](#customdialog) | Ready-made dialog with trigger, icon, title, body and footer |
-| <img src="../previews/feedback-status-emptystate.webp" width="96" alt=""> | [EmptyState](#emptystate) | Icon, title, description and action, with presets |
+| <img src="../previews/feedback-status-emptystate.webp" width="96" alt=""> | [EmptyState](#emptystate) | Illustration, title, description and action, by kind (empty, search, not-found, unauthorized) |
+| <img src="../previews/feedback-status-errorstate.webp" width="96" alt=""> | [ErrorState](#errorstate) | Failure block with Retry and technical details |
 | <img src="../previews/feedback-status-progress.webp" width="96" alt=""> | [Progress](#progress) | Linear bar, circular ring and labelled progress field |
 | <img src="../previews/feedback-status-scrollprogress.webp" width="96" alt=""> | [ScrollProgress](#scrollprogress) | Hairline tracking the window or a scrollable element |
 | <img src="../previews/feedback-status-spinner.webp" width="96" alt=""> | [Spinner](#spinner) | Loading spinner in several styles and colours |
@@ -412,8 +413,7 @@ icon for that reason now needs an element such as a `Button` or `IconButton`.
 
 ![EmptyState](../previews/feedback-status-emptystate.webp)
 
-Icon in a tinted well, title, description and action; not-found,
-unauthorized, generic, empty, offline, search and maintenance presets.
+A calm absence: an illustration (an icon when `size="compact"`), title, description and action, for the `empty`, `search`, `not-found` and `unauthorized` kinds. Text is `text-foreground` and reads at 7:1. For something that failed, use an error state instead.
 
 ```vue
 <script setup lang="ts">
@@ -423,7 +423,7 @@ function clearFilters() {}
 </script>
 
 <template>
-  <EmptyState variant="search">
+  <EmptyState kind="search">
     <template #action>
       <Button variant="outlined" @click="clearFilters">Clear filters</Button>
     </template>
@@ -433,17 +433,88 @@ function clearFilters() {}
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `variant` | `'not-found' \| 'unauthorized' \| 'generic' \| 'empty' \| 'offline' \| 'search' \| 'maintenance'` | `'generic'` | preset icon, well colour, title and description |
-| `#icon` slot | — | the preset's | replaces the icon |
-| `title` / `description` | `string` (or `#title` / `#description`) | the preset's (translated) | replace the preset text; see below |
+| `kind` | `'empty' \| 'search' \| 'not-found' \| 'unauthorized'` | `'generic'` (legacy, until 1.0) | illustration, icon, title and description |
+| `size` | `'default' \| 'compact'` | `'default'` | `compact` swaps the illustration for a small icon and tightens the spacing |
+| `variant` | the four kinds, plus `'generic' \| 'offline' \| 'maintenance'` | — | **deprecated**, removed in 1.0: use `kind`; the error values render without `role="alert"` |
+| `#illustration` slot | — | the kind's | replaces the illustration |
+| `#icon` slot | — | the kind's | replaces the icon |
+| `title` / `description` | `string` (or `#title` / `#description`) | the kind's (translated) | replace the kind's text; see below |
 | `#action` slot | — | — | shown under the text |
 
-The preset's description is the companion of its title: with your own `title` and no `description`, no description is rendered. Pass `description` to keep a line under your own title. A `#title` slot counts as your own title; a `#description` slot always renders.
+The default description is the companion of its title: with your own `title` and no `description`, no description is rendered. Pass `description` to keep a line under your own title. A `#title` slot counts as your own title; a `#description` slot always renders.
+
+`EmptyState` cannot hide its media yet, unlike React's `illustration={false}` ([#711](https://github.com/softistx/nxgt-material/issues/711)); `ErrorState` can, with `:illustration="false"`.
+
+`<EmptyState />` with no `kind` or `variant` still renders the `generic` (error) copy until 1.0; pass `kind`.
+
+### Migrating from `variant`
+
+`variant` still works and is removed in 1.0. Until then:
+
+| Before | After |
+| --- | --- |
+| `variant="empty"`, `"search"`, `"not-found"`, `"unauthorized"` | `kind="…"` with the same value |
+| `variant="generic"`, `"offline"`, `"maintenance"` | `<ErrorState kind="…">`: it is a `role="alert"` block with Retry and technical details; an `EmptyState` error `variant` has no `role` |
+| no `variant` | pass `kind`: the default stays `generic` until 1.0, then becomes `empty` |
+| class overrides to shrink it (`min-h-0`, smaller padding) | `size="compact"`: a small icon, no minimum height |
+| `material.empty-state.generic\|offline\|maintenance.*` overrides | the same text under `material.error-state.<kind>.*` |
+
+```vue
+<!-- before -->
+<EmptyState variant="offline" />
+<EmptyState variant="search" class="min-h-0 py-6" />
+
+<!-- after -->
+<ErrorState kind="offline" @retry="refetch" />
+<EmptyState kind="search" size="compact" />
+```
+
+In 1.0, `variant` goes, the error kinds leave `EmptyState`, and `kind` defaults to `empty`. The DOM keeps `data-slot="empty-state"` and `data-variant`, and adds `data-kind` and `data-size`.
 
 **Storybook:** `Feedback & status/EmptyState` · **React:** `EmptyState`
 
 ---
 
+## ErrorState
+
+![ErrorState](../previews/feedback-status-errorstate.webp)
+
+Failure block with `role="alert"`, an illustration, an optional outlined Retry
+and collapsed technical details (name, message and causes, never the stack).
+Text reads at 7:1 in both themes.
+
+```vue
+<script setup lang="ts">
+import { ErrorState } from '@nxgt/material-vue/components';
+</script>
+
+<template>
+  <ErrorState kind="offline" :error="error" @retry="refetch" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `kind` | `'generic' \| 'offline' \| 'maintenance'` | `'generic'` | illustration, title and description (`material.error-state.<kind>.*`) |
+| `size` | `'default' \| 'compact'` | `'default'` | compact swaps the illustration for an icon |
+| `title` / `description` | `string` | the kind's (translated) | replace the text; a custom `title` drops the default description |
+| `illustration` | `boolean` | `true` | `:illustration="false"` hides the media |
+| `#illustration` / `#icon` slots | — | the built-in illustration | replace the media |
+| `#details` slot | — | the collapsed technical details | replaces them; React has no equivalent yet ([#712](https://github.com/softistx/nxgt-material/issues/712)) |
+| `error` | `unknown` | none | the thrown value; its name, message and `cause` chain go in the details |
+| `showDetails` | `boolean` | `true` when `error` is set | `false` hides the details |
+| `@retry` | `() => unknown` | none | shows an outlined **Retry** button; a returned promise keeps it loading until it settles |
+| `retrying` / `retryLabel` | `boolean` / `string` | derived / `Retry` | force the loading state; rename the button |
+| `action` | the `#action` slot | none | extra actions after Retry |
+
+The details are a native `<details>`: keyboard and server-render friendly.
+Copy keys: `material.error-state.{generic,offline,maintenance}.{title,description}`,
+`error-state.retry`, `error-state.details` and `error-state.details-name|message|cause`.
+
+**Storybook:** `Feedback & status/ErrorState` · **React:** `ErrorState`
+
+---
+
 ## Progress
 
 ![Progress](../previews/feedback-status-progress.webp)

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

@@ -624,6 +624,8 @@ Parts: `PdfReader` (`PdfViewer` is a deprecated alias), `PdfToolbar`, `PdfSideba
 `PdfThumbnailSidebar`, `PdfOutlineSidebar`, `PdfPageList`, and the
 `usePdfReader` composable for building your own layout.
 
+A failed load shows the reader's own error; the React reader adds a Retry button to it, which is React-only for now ([#702](https://github.com/softistx/nxgt-material/issues/702)).
+
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `file` | `PdfSource \| null` | — (required) | a URL (`string` or `URL`), a `File` or `Blob`, an `ArrayBuffer` or `Uint8Array`, or `{ url, httpHeaders?, withCredentials? }`; `null` shows the empty state |

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

@@ -8,6 +8,7 @@ documentation-site shell. Everything is imported from
 | | Component | What it does |
 | --- | --- | --- |
 | <img src="../previews/navigation-layout-appshell.webp" width="96" alt=""> | [ActivityLayout](#activitylayout) | App shell: sidebar, header, breadcrumbs, titled page |
+| <img src="../previews/navigation-layout-accountmenu.webp" width="96" alt=""> | [AccountMenu](#accountmenu) | The app bar's avatar menu: the account, the app's links, Sign out |
 | <img src="../previews/navigation-layout-authcard.webp" width="96" alt=""> | [AuthCard](#authcard) | Signed-out page frame: one `main`, a centred card, its title the `h1` |
 | <img src="../previews/navigation-layout-sidebar.webp" width="96" alt=""> | [Sidebar](#sidebar) | Collapsible navigation sidebar |
 | <img src="../previews/navigation-layout-topappbar.webp" width="96" alt=""> | [TopAppBar, BottomAppBar](#topappbar) | Top and bottom bars |
@@ -75,7 +76,9 @@ which work alone; `findActiveMenuItem`, `isMenuItemActive` and
 | `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 |
+| `logo` (or `#logo`), `name` | `AppLogo` (`string \| AppLogoImage`, `AppLogoImage` = `{ src, alt? }`), `string` | — | the app's logo alone in the collapsed rail, named by `name` (also its tooltip); logo and name side by side in the phone's menu sheet; `#logo` wins over `logo` |
+| `#brand` | slot | — | replaces the sidebar header, in the rail and the menu sheet; wins over `logo` and `name` |
+| `#header-title` | slot | — | the header's leading title (the context: an organisation's name), after the phone's menu button, truncated when long; when it is cut off, its full text is the `title` tooltip (#629) |
 | `#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 |
@@ -100,6 +103,58 @@ entry, and an icon-only one (no label) falls back to its `aria-label`.
 
 ---
 
+## AccountMenu
+
+![AccountMenu](../previews/navigation-layout-accountmenu.webp)
+
+The account menu of an app bar, for `ActivityLayout`'s `#avatar`: an avatar
+button named "Account menu, Ada Lovelace" (the picture, else the initials on
+`bg-primary`) that opens a menu aligned to its end, headed by the avatar, the
+name and a second line, then the app's links and a destructive Sign out.
+
+```vue
+<script setup lang="ts">
+import { AccountMenu, ActivityLayout } from '@nxgt/material-vue/components';
+</script>
+
+<template>
+  <ActivityLayout :items="items">
+    <template #header-title>{{ school.name }}</template>
+    <template #avatar>
+      <AccountMenu
+        :name="user.name"
+        :secondary="user.email"
+        :src="user.picture"
+        :items="[{ label: t('menu.profile'), url: '/profile', icon: 'user' }]"
+        :signing-out="pending"
+        @sign-out="signOut"
+      />
+    </template>
+    <RouterView />
+  </ActivityLayout>
+</template>
+```
+
+| Prop / event | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `name` | `string` | — | the trigger's name ("Account menu, {name}", `material.account-menu.trigger`), the menu's header, the initials |
+| `secondary` | `string` | — | a second line under the name, the e-mail say |
+| `src` | `string` | — | the avatar's picture; the initials until it loads, or without one |
+| `items` | `AccountMenuItem[]` | `[]` | `{ label: string; url: string; icon?: IconName }`: links between the header and Sign out; `label` already translated, `icon` a [Font Awesome](https://fontawesome.com/icons) symbol id of the duotone sprite (see [Icon](primitives.md#icon)) |
+| `linkComponent` | `Component` | `RouterLink` | the link each item renders, as in the app shell |
+| `@sign-out` | event | — | Sign out was chosen; the menu stays open, so `signing-out` shows |
+| `signOutLabel` | `string` | "Sign out" | `material.account-menu.sign-out` |
+| `signingOut` | `boolean` | `false` | Sign out is busy (`aria-busy`, a spinner) and ignores a second selection |
+
+Enter, Space or ArrowDown on the avatar opens the menu on its first item; the
+arrows move, Escape closes it and gives the focus back to the avatar. The
+items are real links (`<a href>`), named by their label. Its links need
+`vue-router`, as the shell's do.
+
+**Storybook:** `Navigation & layout/AccountMenu` · **React:** `AccountMenu` (prop `onSignOut`)
+
+---
+
 ## AuthCard
 
 ![AuthCard](../previews/navigation-layout-authcard.webp)
@@ -725,7 +780,7 @@ Parts: `Doc` (the shell), `DocPage` (header, content, see also and pager);
 the pieces it composes — `DocTopbar`, `DocSidebar`, `DocNav`, `DocArticle`,
 `DocToc`, `DocPager`, `DocSearch`, `DocSeeAlso`, `DocChildCards`,
 `DocProgress`, `DocSkipLink`, `DocHeader`, `DocCopyPage`, `DocCopyMarkdown`,
-`DocLink` — and `DocEmpty` for a 404.
+`DocLink` — and `DocEmpty` for a 404. `DocEmpty` is an `EmptyState` (`kind` defaults to `not-found`; `size` is `default` or `compact`): see [EmptyState](./feedback-and-status.md#emptystate).
 `useDoc` / `provideDoc` / `useDocContext` expose the state for a shell of
 your own, built from those parts:
 
@@ -823,9 +878,17 @@ import { Background, Card } from '@nxgt/material-vue/components';
 </template>
 ```
 
-No props but `class`. It fills the viewport; pass a `class` such as
-`h-96 w-full` to use it as a band. `ActivityLayout` and `ThreadLayout` sit on
-it.
+| Prop | Values | Default |
+| --- | --- | --- |
+| `preset` | `gradient` (the only preset on `/components`) | `gradient` |
+| `tone` | `primary`, `secondary`, `tertiary`, `neutral`, `success`, `warning`, `error`, `info`, `mixed` (primary, secondary and tertiary), `custom` (reads `--nxgt-bg-custom-1..3`) | `primary` |
+| `intensity` | `subtle`, `default`, `vivid` | `default` |
+| `animated` | drifts the blobs; paused while the page is hidden or the background is off screen, and never under reduced motion | `false` |
+
+It fills the viewport; pass a `class` such as `h-96 w-full` to use it as a band.
+It is plain CSS from `styles.css`, with no inline `style`, and its colours lift
+in dark. `ActivityLayout` and `ThreadLayout` sit on it. The superset with `grain`,
+`seed`, `fill` and the other presets is `Background` from `/backgrounds`; see the [backgrounds guide](../guides/backgrounds.md).
 
 **Storybook:** `Navigation & layout/Background` · **React:** `Background`
 

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

@@ -39,7 +39,16 @@ default) leave the page as it is.
 
 ![Dialog](../previews/overlays-menus-dialog.webp)
 
-Modal dialog parts with a close button.
+Modal dialog parts with a close button. An open `SelectField` list inside it has always taken the first Escape, as a layer of its own. So does an open `ComboboxField` or `Autocomplete` list: the second Escape closes the dialog. The same holds in a `Sheet`, a `Drawer`, an `AlertDialog` and a `Popover`.
+
+Your own `@escape-key-down` on the content receives the Escape that only closes an open list with `event.defaultPrevented === true`; a handler that asks "close without saving?" returns early on it:
+
+```vue
+<DialogContent @escape-key-down="(event) => {
+  if (event.defaultPrevented) return; // only an open list is closing
+  if (dirty) event.preventDefault(); // ask "close without saving?"
+}">
+```
 
 ```vue
 <script setup lang="ts">
@@ -198,6 +207,8 @@ Vue.
 
 Swipeable bottom or side drawer (Reka UI's drawer).
 
+An `Autocomplete` inside a Drawer keeps its list floating, stopped above the Drawer's footer, and a drag that starts on the list scrolls it instead of dragging the Drawer.
+
 ```vue
 <script setup lang="ts">
 import {
@@ -638,20 +649,26 @@ Parts: `Command`, `CommandDialog`, `CommandInput`, `CommandList`,
 `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandShortcut`,
 `CommandSeparator`.
 
+`CommandEmpty` shows when the search matches nothing. With no children it
+renders a compact `EmptyState` ("No results", `material.command.empty`); give it
+children and they replace that, as before.
+
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `value` (`CommandItem`) | `string` | — (required) | the item's value, emitted by `@select` and by `Command`'s `v-model` |
 | `checked` (`CommandItem`) | `boolean` | — | sets `aria-checked` and shows a checkbox indicator, for a multi-choice list; reka's `aria-selected` keeps meaning "selected value" (`multiple` is not used) |
 | `multiselectable` (`CommandList`) | `boolean` | — | sets `aria-multiselectable` on the list |
 | `@select` (`CommandItem`) | `(event) => void` | — | Enter or click on the item; `event.detail.value` is its `value` |
+| `aria-label` (`CommandList`) | `string` | `"Suggestions"` (translated, `material.command.list`) | the list's accessible name; your own `aria-label` replaces the default |
+| `decorative` (`CommandSeparator`) | `boolean` | `true` | the separator is purely visual (`role="none"`): a `role="separator"` is not allowed inside the listbox |
 | `heading` (`CommandGroup`) | `string` | — | the group's label |
 | `title` / `description` (`CommandDialog`) | `string` | `"Command Palette"` / `"Search for a command to run..."` (translated) | the dialog's title and description, visually hidden |
 | `v-model:open` (`CommandDialog`) | `boolean` | — | `CommandDialog` takes every `Dialog` prop |
 
 The filter matches the item's text, case- and accent-insensitive; there is no
 `shouldFilter` or `keywords` in Vue. `CommandDialog`'s default title and
-description are English, not translated — pass your own. It does not bind a
-keyboard shortcut: listen for ⌘K yourself (`useMagicKeys` from VueUse) and set
+description follow `I18nProvider` (`material.command.title` / `description`).
+It does not bind a keyboard shortcut: listen for ⌘K yourself (`useMagicKeys` from VueUse) and set
 `open`.
 
 **Storybook:** `Overlays & menus/Command` · **React:** `Command`, `CommandDialog` (same parts)

package/docs/components/primitives.md

@@ -193,7 +193,7 @@ import { Typography } from '@nxgt/material-vue/components';
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `variant` | `'huge-larger' \| 'huge-large' \| 'huge-medium' \| 'huge-small' \| 'headline-larger' \| 'headline-large' \| 'headline-medium' \| 'headline-small' \| 'title-large' \| 'title-medium' \| 'title-small' \| 'body-medium' \| 'body-small' \| 'caption' \| 'normal'` | `'normal'` | size and weight; `caption` is also muted |
-| `tone` | `'default' \| 'muted' \| 'primary' \| 'error'` | `'default'` | text colour: `muted` is `text-muted-foreground`, `primary` is `text-primary`, `error` is `text-error-text`; `default` inherits (a `class` colour still wins) |
+| `tone` | `'default' \| 'muted' \| 'primary' \| 'error'` | `'default'` | text colour: `muted` is `text-muted-foreground`, `primary` is `text-primary-text` (primary lightened in dark), `error` is `text-error-text`; `default` inherits (a `class` colour still wins) |
 | `as` | a tag name or a component | `'div'` | the element to render, keeping the variant, e.g. `as="h2"` or `as="span"` |
 | `asChild` | `boolean` | `false` | merge the classes onto the single child instead of rendering an element |
 
@@ -364,6 +364,8 @@ Takes every `<input>` attribute. `v-model` carries `string | number`;
 the error outline. For a labelled field with helper text and a form wrapper,
 use `TextField` on the [Form fields](form-fields.md) page.
 
+In an input group (`InputGroupInput`, `InputGroupField`) the fill tint follows the value: an empty field is not tinted, with or without a `placeholder` (one without renders a blank `placeholder=" "` so that CSS can tell). The bare `Input` and `Textarea` have no tint and get no placeholder.
+
 **Emits:** `update:modelValue` — `string | number`.
 **Storybook:** `Primitives/Input` · **React:** `Input`
 
@@ -461,7 +463,7 @@ import { Icon } from '@nxgt/material-vue/components';
 
 <template>
   <Icon name="bell" />
-  <Icon name="bell" type="solid" class="size-6 text-primary" aria-hidden="true" />
+  <Icon name="bell" type="solid" class="size-6 text-primary-text" aria-hidden="true" />
 </template>
 ```
 
@@ -901,7 +903,7 @@ defineProps<{ nonce?: string }>();
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `nonce` | `string` | `undefined` | the nonce of the page's `style-src-elem 'nonce-…'`; `undefined` or `''` inherits the nearest outer `NonceProvider`'s (or `ConfigProvider`'s) nonce (none at the root) |
+| `nonce` | `string` | `undefined` | the nonce of the page's `style-src-elem 'nonce-…'`; `undefined` or `''` inherits the nearest outer `NonceProvider`'s (or `ConfigProvider`'s) nonce, else, on the client from the first render (read in `setup`), the page's own (`csp-nonce` meta tag, …); a server has no page, so it passes the prop |
 
 `useCspNonce()` (`@nxgt/material-vue/composables`) reads it in a component of
 your own; `getCspNonce()` and `setCspNonce()` (`@nxgt/material-vue/lib`) read

package/docs/components/rich-widgets.md

@@ -238,7 +238,7 @@ props below, and `option` for anything else.
 | `height` | `string \| number` | `320` | the container's height; the chart fills it |
 | `loading` | `boolean` | `false` | a skeleton instead of the chart |
 | `empty` | `boolean` | when `data` is empty | force the empty state on or off |
-| `#emptyState` | slot | built-in empty state | what an empty chart shows |
+| `#emptyState` | slot | the built-in compact `EmptyState` | what an empty chart shows; a custom slot keeps its centring wrapper |
 | `colors` | `string[]` | from the `--chart-*` tokens | override the palette; any CSS colour, `oklch()` included (converted to `rgb()` for ECharts) |
 | `margin` | `ChartMargin` | — | plot padding |
 | `option` | `EChartsOption` | — | merged into the generated ECharts option |

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

@@ -234,6 +234,8 @@ options by label. Picking the selected option again clears it.
 
 Single or multiple (chips) autocomplete typed by its options, with free-solo values, accent-insensitive matching, a debounced server search and option slots.
 
+The input is a `combobox` (`aria-expanded`, `aria-controls`, `aria-activedescendant`) and the list a `listbox` of `option`s, as in `@nxgt/material`; the list opens on a click or on typing, not on focus alone. In tests, use `getByRole('combobox', { name })` and `getByRole('option', { name })`.
+
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue';
@@ -336,15 +338,23 @@ update them on `@query-change`, and pass `filter="none"` when the server
 already filtered.
 
 A disabled option (`disabled: true` on it, in `options` or in what `on-search`
-returns) is greyed out, carries `aria-disabled` and a native `disabled`, so Tab
-skips it, and is never picked, by click or by Enter (which picks the first
-enabled option), in `single` and `multiple` mode.
+returns) is greyed out, carries `aria-disabled` and a native `disabled`, so the arrow keys skip it, and is never picked, by click or by Enter (which picks the
+highlighted option, the first enabled one until the arrows move it), in `single` and `multiple` mode.
 
 **Accessibility.** A polite live region (`role="status"`) says "Loading…",
 then "3 results" or "No results" (or the failure) once the search answers or
 typing pauses — never on every keystroke. The list is `aria-busy` while
 loading. The strings are `material.autocomplete.loading`, `.results`,
-`.search-error` and `.min-query`. The keyboard works as before.
+`.search-error` and `.min-query`.
+
+**Keyboard.** The input keeps the focus and points at the highlighted option
+with `aria-activedescendant`. `ArrowDown` and `ArrowUp` open a closed list
+and move the highlight over the enabled options (wrapping at the ends); with
+an empty query `Home` and `End` jump to the first and last one. `Enter`
+picks the highlighted option (or adds the free-solo value when "Add …" stands
+for it) and, with the list closed, submits the form; hovering an option moves
+the highlight. `Escape` closes the list, and `Backspace` on an empty query removes
+the last chip. The options are not tab stops: Tab leaves the field.
 
 It is a generic component: `T` is inferred from `options`, and the slots —
 React's render props — receive it whole:

package/docs/getting-started.md

@@ -35,7 +35,7 @@ does not import that entry never has them in its tree.
 The tarball contains the built `dist/` (with KaTeX's fonts in
 `dist/fonts/katex/`, which the compiled stylesheet loads),
 `lib/styles.css`, the component
-stylesheets it imports (`lib/components/**/*.css`), `lib/map/map.css`, the
+stylesheets it imports (`lib/components/**/*.css`), `lib/map/map.css`, `lib/backgrounds/backgrounds.css`, `lib/backgrounds/css/*.css`, the
 Nuxt module (`lib/nuxt`, with the
 `lib/vite/index.ts` it imports), these docs and `CHANGELOG.md` (from the
 release after 0.25.1). There is no `postinstall` build step.
@@ -112,6 +112,18 @@ Your own components can use the same per-instance store factory
 (`defineLocalStore` and the status, filter and step-form stores) from
 `@nxgt/material-vue/lib`; see [helpers](guides/helpers.md#pinia-store-factories).
 
+## The Vite plugin
+
+In `vite.config.ts`, add the plugin after `tailwindcss()`:
+
+```ts
+import { nxgtMaterial } from '@nxgt/material-vue/vite';
+
+export default defineConfig({ plugins: [/* …, */ tailwindcss(), ...nxgtMaterial()] });
+```
+
+It sets up a strict Content Security Policy (the header is written to `dist/.vite/nxgt-csp.json`), keeps fonts out of `data:` URIs, loads Inter when `@fontsource-variable/inter` is installed and fails the build when the stylesheet above is not imported. Each part has an opt-out: [Vite plugin guide](guides/vite-plugin.md). On Nuxt, see the guide's note.
+
 ## Icons
 
 `Icon` renders a Font Awesome **sprite** referenced by a root-relative URL on
@@ -174,7 +186,9 @@ export default defineNuxtConfig({
     // prefix: 'Nxgt',   // <NxgtButton />
     // components: true, // auto-import components
     // imports: true,    // auto-import composables and i18n helpers
-    // pdf: { bundleStandardFonts: true }, // a server with no node_modules that renders /pdf
+    // pdf: { bundle: true }, // a server with no node_modules that renders /pdf
+    // fonts: { sans: 'inter' }, // self-hosted Inter (bun add @fontsource-variable/inter)
+    // csp: { zodJitless: true }, // zod's jitless script in every head (needs nuxt-security's nonce or hash)
   },
 });
 ```
@@ -184,7 +198,10 @@ export default defineNuxtConfig({
 | `prefix` | `string` | `''` | Prepended to every auto-imported component name |
 | `components` | `boolean` | `true` | Registers the components of `@nxgt/material-vue/components` for use without an import |
 | `imports` | `boolean` | `true` | Auto-imports the composables (`useTheme`, `useIsMobile`, `useIsClient`, `useLocalizedDate`, `useFormatters`, `useNumberFormatter`, `useSearchParam`, …) and `useMaterialTranslation`, `createTypedTranslation`, `useOptionalI18nContext` |
-| `pdf.bundleStandardFonts` | `boolean` | `false` | Adds `pdfkitStandardFonts()` to the Nitro build, for a server that renders with `@nxgt/material-vue/pdf` and runs without `node_modules` ([PDF documents](guides/pdf.md#fonts-on-a-fully-inlined-server)) |
+| `pdf.bundle` | `boolean` | `false` | Adds `pdfkitStandardFonts()` to the Nitro build, for a server that renders with `@nxgt/material-vue/pdf` and runs without `node_modules` ([PDF documents](guides/pdf.md#fonts-on-a-fully-inlined-server)). `pdf.bundleStandardFonts` is its deprecated name |
+| `fonts` | `boolean \| { katex?, sans? }` | `{ katex: true, sans: false }` | `katex`: a font is never inlined as a `data:` URI (`font-src 'self'`). `sans: 'inter'`: loads self-hosted Inter and sets `--font-sans` through `css` (a missing `@fontsource-variable/inter` warns once and keeps the system font). `false` turns both off |
+| `csp.zodJitless` | `boolean` | `false` | Puts zod's jitless inline script in every page's `<head>` (`tagPriority: 'critical'`). It is an inline script: a strict CSP needs `nuxt-security` with `nonce: true` (or its script hashes) to allow it. The module sets no CSP itself ([Vite plugin guide](guides/vite-plugin.md#nuxt)) |
+| `styles` | `boolean \| { check? }` | `false` | The `vite build` check that the stylesheet is imported, off by default under Nuxt because the module cannot see how `css` entries are resolved. `true` opts in |
 
 The module also:
 
@@ -223,6 +240,7 @@ export default defineConfig({
 | `@nxgt/material-vue` | Everything from `/components`, `/composables`, `/i18n`, `/lib`, `/models` and `/types` in one barrel, plus the compiled `style` condition (`dist/material-vue.css`, for apps without Tailwind) |
 | `@nxgt/material-vue/components` | UI components and `*FormField` wrappers ([components](components/README.md)) |
 | `@nxgt/material-vue/map` | Leaflet maps, markers, a location field. **Its own entry, not in the barrel above** ([maps](guides/maps.md)) |
+| `@nxgt/material-vue/backgrounds` | Background presets: `Background` (a superset of the `/components` one: `preset` `gradient` or `grain`, `tone`, `intensity`, `animated`, `grain`, `seed`, `fill`), and the types and tables re-exported from `@nxgt/material-core/backgrounds`; more presets are coming. **Its own entry**, with an opt-in stylesheet ([backgrounds](guides/backgrounds.md)) |
 | `@nxgt/material-vue/pdf` | PDF files from plain data: builders, `usePdf`, `PdfDownloadButton`, `pdfResponse`. **Its own entry, not in the barrel above** ([PDF documents](guides/pdf.md)) |
 | `@nxgt/material-vue/composables` | `useTheme`, `useIsClient`, `useIsMobile`, `useLocalizedDate`, `useSearchParam`, … ([helpers](guides/helpers.md#nxgtmaterial-vuecomposables)) |
 | `@nxgt/material-vue/dnd` | Drag-and-drop primitives ([helpers](guides/helpers.md#nxgtmaterial-vuednd)) |
@@ -232,6 +250,7 @@ export default defineConfig({
 | `@nxgt/material-vue/types` | Shared function types (`PromiseOr`, `FunctionOr`, …) |
 | `@nxgt/material-vue/styles.css` | Source Tailwind v4 tokens. **This** is the stylesheet a Tailwind app imports |
 | `@nxgt/material-vue/map.css` | Leaflet's stylesheet, for apps that use `/map`. Not part of `styles.css` |
+| `@nxgt/material-vue/backgrounds.css` | Every background preset's CSS, for apps that use `/backgrounds`; `@nxgt/material-vue/backgrounds/<preset>.css` loads one. Not part of `styles.css` |
 | `@nxgt/material-vue/nuxt` | The Nuxt module ([above](#nuxt)) |
 | `@nxgt/material-vue/vite` | `pdfkitStandardFonts()`, a Vite plugin for a server that inlines `/pdf` ([PDF documents](guides/pdf.md#fonts-on-a-fully-inlined-server)). Build-time code for `vite.config.ts` |
 

package/docs/guides/app-shell.md

@@ -17,10 +17,7 @@ const items: MenuItem[] = [
 </script>
 
 <template>
-  <ActivityLayout :items="items" avatar-src="/me.png">
-    <template #brand>
-      <strong>Acme</strong>
-    </template>
+  <ActivityLayout :items="items" logo="/logo.svg" name="Acme" avatar-src="/me.png">
     <RouterView />
   </ActivityLayout>
 </template>
@@ -179,7 +176,11 @@ partitionMenu(items);                              // { content, footer }
 | `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 |
+| `logo` | `string \| { src, alt? }` | an atom badge | The app's logo, an image URL: alone in the collapsed rail, beside `name` in the phone's menu sheet (see [The brand](#the-brand-logo-and-name)) |
+| `#logo` | slot | — | The logo as a node (an inline SVG), in place of `logo`; it wins when both are given |
+| `name` | `string` | — | The app's name, already translated: the logo's accessible name and tooltip in the rail, shown beside it in the sheet |
+| `#brand` | slot | — | Replaces the sidebar header entirely, in the rail and in the menu sheet; wins over `logo` and `name` |
+| `#header-title` | slot | — | The header's leading title: the context the app is in (the active organisation's name), right after the phone's menu button, truncated when long; when it is cut off, its full text is the `title` tooltip (#629) |
 | `#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 />` |
@@ -214,32 +215,26 @@ the slots.
 ```vue
 <script setup lang="ts">
 import {
+  AccountMenu,
   ActivityLayout,
-  Avatar,
-  AvatarFallback,
-  AvatarImage,
   LanguageSwitcher,
   type MenuItem,
   ThemeToggle,
 } from '@nxgt/material-vue/components';
 
-defineProps<{ items: MenuItem[]; user: { name: string; picture?: string } }>();
+defineProps<{ items: MenuItem[]; user: { name: string; email: string; picture?: string } }>();
+const emit = defineEmits<{ 'sign-out': [] }>();
 </script>
 
 <template>
-  <ActivityLayout :items="items">
-    <template #brand>
-      <img src="/logo.svg" alt="Acme" class="h-8" />
-    </template>
+  <ActivityLayout :items="items" logo="/logo.svg" name="Acme">
+    <template #header-title>Northwind school</template>
     <template #header-actions>
       <LanguageSwitcher />
       <ThemeToggle />
     </template>
     <template #avatar>
-      <Avatar>
-        <AvatarImage :src="user.picture ?? ''" :alt="user.name" />
-        <AvatarFallback>{{ user.name.slice(0, 2) }}</AvatarFallback>
-      </Avatar>
+      <AccountMenu :name="user.name" :secondary="user.email" :src="user.picture" @sign-out="emit('sign-out')" />
     </template>
     <RouterView />
   </ActivityLayout>
@@ -254,7 +249,92 @@ entry closes it — so does any route change, Back included — and focus goes t
 the page's `<main>`, unless the new screen already focused an element inside it
 (an error page's `h1`), which keeps it; 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.
+no tooltip: none opens over the first entry as focus moves in. It shows the
+app's `logo` and `name` (or `#brand`) above the entries, as the expanded
+sidebar does.
+
+### The app bar: a title, the actions, the account
+
+The header reads, from the start: the phone's menu button, `#header-title`
+(the context the app is in, the active school or organisation), then
+`#header-actions` (language, notifications) and `#avatar` at the end. The
+title takes the room left and ends in an ellipsis when it does not fit, so
+the avatar always stays on screen. It is not a heading: the screen's `h1` is
+`ActivityContent`'s title.
+
+`AccountMenu` is the `#avatar` most apps want: an avatar button named
+"Account menu, Ada Lovelace" (`material.account-menu.trigger`) that opens a
+menu aligned to its end, headed by the avatar, the name and `secondary`, then
+the app's `items` and a destructive Sign out
+(`material.account-menu.sign-out`). Choosing Sign out emits `sign-out` and
+keeps the menu open: pass `signing-out` while the request runs, and the item
+shows a spinner and ignores a second selection. Without `src`, or until it
+loads, the avatar shows the initials on `bg-primary`.
+
+```vue
+<AccountMenu
+  :name="user.name"
+  :secondary="user.email"
+  :src="user.picture"
+  :items="[
+    { label: t('menu.profile'), url: '/profile', icon: 'user' },
+    { label: t('menu.settings'), url: '/settings', icon: 'gear' },
+  ]"
+  :signing-out="pending"
+  @sign-out="signOut"
+/>
+```
+
+Each entry is an `AccountMenuItem`, exported with it:
+
+```ts
+type AccountMenuItem = {
+  label: string; // already translated
+  url: string; // rendered as a real link through `link-component`
+  icon?: IconName; // optional, decorative: the label names the entry
+};
+```
+
+`icon` is an `IconName`, a symbol id of the Font Awesome duotone sprite you serve (`user`, `gear`, `arrow-right-from-bracket`; browse the names at <https://fontawesome.com/icons>, and see [getting started](../getting-started.md#icons) for serving the sprite).
+
+### The brand: logo and name
+
+`logo` (or the `#logo` slot) and `name` put the app's brand in the sidebar
+header, in the shape each place has room for. `logo` is typed `AppLogo`
+(`string | AppLogoImage`, where `AppLogoImage` is `{ src: string; alt?: string }`
+and a string is the image URL), both exported from
+`@nxgt/material-vue/components`:
+
+- **The collapsed rail** (desktop, about 70 px wide) shows the **logo alone**.
+  `name` is its accessible name (an `<img alt>`, or `role="img"` with an
+  `aria-label` around the `#logo` node) and shows as a tooltip on hover, to
+  its right.
+- **The expanded sidebar and the phone's menu sheet** show the **logo and the
+  name side by side**. The name is on screen there, so the logo is decorative
+  (`alt=""` or `aria-hidden`), and no tooltip repeats it.
+
+```vue
+<ActivityLayout :items="items" logo="/logo.svg" :name="t('app.name')">…</ActivityLayout>
+<!-- An image with its own alt, used when there is no name: -->
+<ActivityLayout :items="items" :logo="{ src: '/logo.svg', alt: 'Acme' }">…</ActivityLayout>
+<!-- A node, an inline SVG for instance: -->
+<ActivityLayout :items="items" name="Acme">
+  <template #logo><AcmeMark class="size-8" /></template>
+  …
+</ActivityLayout>
+```
+
+Without a logo the header keeps its placeholder atom badge (named by `name`
+in the rail when there is one); fill `logo` in a real app. `#brand` is the
+full override: one node rendered as given, collapsed or expanded alike, in the
+rail and in the menu sheet. `AppSidebar` takes the same props and slots, and
+`AppHeader` takes them for its menu sheet.
+
+`#brand` is rendered twice, once in the rail and once in the menu sheet (the
+rail stays in the page on a phone, hidden): an `id` inside it appears twice
+while the sheet is open, so leave ids out of it. A link in `#brand` (a home
+link around the logo) is the sheet's first focusable element, so it takes
+the focus when the sheet opens.
 
 ## Landmarks, headings and scrolling
 
@@ -375,7 +455,7 @@ home included, is a `RouterLink`, so it goes through the router's base: under
 `AppSidebar`, `AppHeader` and `AppBreadcrumb` are exported for a layout of your
 own. `AppSidebar` and `AppHeader` take the same `items`; `AppSidebar` also
 takes `expanded` (`v-model:expanded`) and `with-toggle-icon`, and has the
-`#brand` slot; `AppHeader` takes `avatar-src` and `show-menu-icon` (default
+`#brand` slot, `logo`, `name` and `#logo`; `AppHeader` takes `avatar-src`, `logo`, `name` and `show-menu-icon` (default
 `true`), with `#actions`, `#avatar` and a default slot for the middle of the
 bar. The lower-level `Sidebar`, `TopAppBar`, `NavigationRail` and `Breadcrumb`
 primitives are on the