@nxgt/material-vue 0.42.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

@@ -78,7 +78,7 @@ which work alone; `findActiveMenuItem`, `isMenuItemActive` and
 | `avatarSrc` | `string` | — | avatar image in the 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 |
+| `#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 |
@@ -780,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:
 
@@ -878,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

@@ -180,7 +180,7 @@ partitionMenu(items);                              // { content, footer }
 | `#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 |
+| `#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 />` |

package/docs/guides/backgrounds.md

@@ -0,0 +1,143 @@
+# Backgrounds
+
+`Background` is a backdrop that centres its content. The one in
+`@nxgt/material-vue/components` is the **gradient**: a tint with three blurred blobs, and
+it needs only `styles.css`. `@nxgt/material-vue/backgrounds` is the entry for the
+preset family and shares its tones, its intensities and its CSS with
+that gradient. There, `Background` is a superset of the `/components` one under
+the same name (same props, plus the preset ones); the other presets are being
+added slice by slice, so for now it draws the gradient and the grain.
+
+## Tone and intensity
+
+```vue
+<script setup lang="ts">
+import { Background } from '@nxgt/material-vue/components';
+</script>
+
+<template>
+  <Background tone="success" intensity="subtle" class="h-96 w-full">
+    ...
+  </Background>
+</template>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `tone` | `primary`, `secondary`, `tertiary`, `neutral`, `success`, `warning`, `error`, `info`, `mixed`, `custom` | `primary` |
+| `intensity` | `subtle`, `default`, `vivid` | `default` |
+| `preset` | `gradient` (the only one on `/components`; `/backgrounds` adds `grain`) | `gradient` |
+
+`mixed` draws from primary, secondary and tertiary; `custom` reads your own
+colours (see below).
+
+## The `/backgrounds` component
+
+`Background` from `@nxgt/material-vue/backgrounds` takes everything the `/components` one
+takes, and more. Import the stylesheet of the presets you use (below).
+
+```vue
+<script setup lang="ts">
+import { Background } from '@nxgt/material-vue/backgrounds';
+import '@nxgt/material-vue/backgrounds.css';
+</script>
+
+<template>
+  <Background preset="grain" tone="mixed" animated class="h-96 w-full">
+    ...
+  </Background>
+</template>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `preset` | `gradient`, `grain` (`SHIPPED_BACKGROUND_PRESETS`); any other id draws the gradient and warns outside production | `gradient` |
+| `tone`, `intensity` | as above | `primary`, `default` |
+| `animated` | `boolean`: drifts the layers, see Motion | `false` |
+| `grain` | `boolean`: film noise over the preset; needs `grain.css` | `false` |
+| `seed` | `number`: moves a seeded preset's geometry and the grain | `0` |
+| `fill` | `viewport` (the viewport's size) or `container` (its parent's size: the parent needs a definite height) | `viewport` |
+
+`BACKGROUND_PRESETS` is the planned table of all twenty presets, with their
+family and kind; `SHIPPED_BACKGROUND_PRESETS` is what `Background` draws today.
+
+The root states `preset`, `tone`, `intensity`, `animated`, `grain` and `fill` as
+`data-*` attributes (`data-animated` and `data-grain` are empty attributes), and
+`data-paused` while it is paused. Select on `data-preset` (`grain` for the grain
+preset), not on `data-background`. That one is the CSS key and stays
+`gradient` for it. The default slot is centred above the
+decoration.
+
+`grain` draws an SVG `feTurbulence` filter above the preset's layers, under
+your content; `intensity` scales its opacity. `preset="grain"` is the gradient
+with the grain on. The grain's look may still change. Its SVG is built from
+plain data by `@nxgt/material-core/backgrounds` (`buildGrain`), with no `style`
+attribute: ids come from `useId`, so the server and the client render the same
+markup, and nothing is random or measured.
+
+## Dark mode
+
+In dark the drawn colours are lifted to a lightness floor: the dark `--primary` is as dim as the light one, which made the
+gradient dull. The lift uses the relative colour syntax (Chrome 119, Safari 18,
+Firefox 128); older browsers get a `color-mix()` toward white.
+
+## Your own colours
+
+`tone="custom"` reads `--nxgt-bg-custom-1` to `--nxgt-bg-custom-3`, which you set in your
+own stylesheet. There is no colour prop, because one would write a `style`
+attribute.
+
+```css
+.brand-backdrop {
+  --nxgt-bg-custom-1: oklch(0.62 0.2 30);
+  --nxgt-bg-custom-2: oklch(0.7 0.15 80);
+  --nxgt-bg-custom-3: var(--primary);
+}
+```
+
+## Overriding the drawn colours
+
+The tone sets `--nxgt-bg-c1..c3`, the three colours the layers draw with. Set
+them on the element to pick your own. The element carries `data-background`, `data-tone` and `data-intensity`, which
+you can select on:
+
+```css
+[data-background][data-tone="primary"] {
+  --nxgt-bg-c1: oklch(0.62 0.2 30);
+  --nxgt-bg-c2: oklch(0.7 0.15 80);
+}
+```
+
+## Stylesheets
+
+`styles.css` carries the base, the gradient and the motion rules. Everything
+else is opt-in, because CSS cannot be tree-shaken. `animated` on the
+`/components` `Background` needs only `styles.css`; `grain` needs `grain.css` (or
+`backgrounds.css`) and renders nothing, with no error, without it:
+
+```css
+@import "@nxgt/material-vue/backgrounds.css";            /* every opt-in file */
+/* or just the one you use: */
+@import "@nxgt/material-vue/backgrounds/grain.css";      /* the grain overlay, over any preset */
+```
+
+The base, the gradient and the motion already come with `styles.css`: the
+`/components` `Background` needs none of `base.css`, `gradient.css` or
+`motion.css`. Only `grain.css` is extra.
+
+The CSS sits in `@layer components`: a utility such as `h-96 w-full` or
+`overflow-hidden` on the element beats it.
+
+## Motion, accessibility and CSP
+
+- Static by default. `animated` drifts the layers, and only under
+  `@media (prefers-reduced-motion: no-preference)`: with reduced motion it
+  never moves. It sets `data-paused`, which stops the animation, while the page
+  is hidden (another tab) or the background is off screen. The observers start
+  once mounted and only when `animated` is set, and are removed on unmount.
+  `animated` is on the `/components` `Background` too, with the same behaviour.
+- Every decorative layer is `aria-hidden="true"` and takes no pointer; under
+  `forced-colors: active` the layers are hidden. Put text on a `Card` when you
+  use `vivid`.
+- The markup carries no `style` attribute and no `<style>` element, so a
+  strict CSP needs nothing beyond the [baseline](csp.md).