@nxgt/material-vue 0.42.0 → 0.43.1

package/dist/use-background-activity-DdTBbNpX.js

@@ -0,0 +1,17 @@
+import { onBeforeUnmount as e, onMounted as t, ref as n, watch as r } from "vue";
+import { observeBackgroundActivity as i } from "@nxgt/material-core/backgrounds";
+//#region lib/composables/use-background-activity.ts
+function a(a, o) {
+	let s = n(!1), c, l = () => {
+		c?.(), c = void 0, s.value = !1;
+	}, u = () => {
+		l(), o() && a.value && (c = i(a.value, (e) => {
+			s.value = e;
+		}));
+	};
+	return t(() => {
+		u(), r(o, u);
+	}), e(l), s;
+}
+//#endregion
+export { a as t };

package/dist/{use-heading-spy-BIBHtUXN.js → use-heading-spy-jn8f2ioE.js}

@@ -1,29 +1,29 @@
-import { a as e } from "./i18n-provider-DmZSTBnp.js";
+import { a as e } from "./i18n-provider-tL27-a8y.js";
 import { c as t, d as n, l as r, n as i, s as a, u as o } from "./number.utils-C1eB3GDr.js";
 import { computed as s, getCurrentInstance as c, inject as l, onMounted as u, ref as d, shallowRef as f, toValue as p, watch as m } from "vue";
 import { injectConfigProviderContext as h } from "reka-ui";
 import { useIntersectionObserver as g, useMediaQuery as _, useSSRWidth as v, useStorage as y } from "@vueuse/core";
+//#region lib/composables/use-ssr-media-query.ts
+var b = 1024;
+function x(e) {
+	return c() ? _(e, { ssrWidth: v() ?? b }) : _(e);
+}
+//#endregion
 //#region lib/composables/resolve-theme.ts
-function b(e, t) {
+function S(e, t) {
 	let n = e === "light" || e === "dark" ? e : "system";
 	return {
 		theme: n === "system" ? t ? "dark" : "light" : n,
 		preference: n
 	};
 }
-function x(e) {
-	typeof document > "u" || (document.documentElement.classList.toggle("dark", e === "dark"), document.documentElement.style.colorScheme = e);
-}
-//#endregion
-//#region lib/composables/use-ssr-media-query.ts
-var S = 1024;
 function C(e) {
-	return c() ? _(e, { ssrWidth: v() ?? S }) : _(e);
+	typeof document > "u" || (document.documentElement.classList.toggle("dark", e === "dark"), document.documentElement.style.colorScheme = e);
 }
 //#endregion
 //#region lib/composables/use-theme.ts
 function w() {
-	let e = C("(prefers-color-scheme: dark)"), t = y("theme", null, void 0, { initOnMounted: !0 }), n = s(() => b(t.value, !!e.value));
+	let e = x("(prefers-color-scheme: dark)"), t = y("theme", null, void 0, { initOnMounted: !0 }), n = s(() => S(t.value, !!e.value));
 	return {
 		get theme() {
 			return n.value.theme;
@@ -32,7 +32,7 @@ function w() {
 			return n.value.preference;
 		},
 		updateTheme: (n) => {
-			n === "system" ? t.value = null : t.value = n, x(b(n === "system" ? void 0 : n, !!e.value).theme);
+			n === "system" ? t.value = null : t.value = n, C(S(n === "system" ? void 0 : n, !!e.value).theme);
 		}
 	};
 }
@@ -40,7 +40,7 @@ function w() {
 //#region lib/composables/use-mobile.ts
 var T = 768;
 function E() {
-	return C(`(max-width: ${T - 1}px)`);
+	return x(`(max-width: ${T - 1}px)`);
 }
 //#endregion
 //#region ../../node_modules/date-fns/locale/fr/_lib/formatDistance.js
@@ -495,4 +495,4 @@ function q(e, t, n) {
 	});
 }
 //#endregion
-export { V as a, w as c, b as d, W as i, C as l, U as n, B as o, H as r, E as s, q as t, x as u };
+export { V as a, w as c, x as d, W as i, C as l, U as n, B as o, H as r, E as s, q as t, S as u };

package/dist/{use-material-translation-COoBTGpB.js → use-material-translation-CHacJbhU.js}

@@ -1,6 +1,6 @@
-import "./stored-language-Wtcj2HsU.js";
-import { a as e } from "./i18n-provider-DmZSTBnp.js";
-import { i as t, r as n } from "./translator-D5Dp-dob.js";
+import "./stored-language-DVP9KzRu.js";
+import { a as e } from "./i18n-provider-tL27-a8y.js";
+import { i as t, r as n } from "./translator-Dpfm1mAC.js";
 //#region lib/i18n/translate-material.ts
 function r(e, r, i, a) {
 	if (e) for (let t of /* @__PURE__ */ new Set([e, e.split("-")[0]])) {

package/dist/{usecaseDiagram-POWQR4AR-Bi5we59l.js → usecaseDiagram-POWQR4AR-1f4iixDN.js}

@@ -12,7 +12,7 @@ import "./chunk-Z7XXMR3K-DdnrI6vA.js";
 import { t as ee } from "./chunk-XXDRQBXY-B9ckANit.js";
 import { t as te } from "./chunk-WEXAMYUT-DufdZ2tS.js";
 import "./chunk-UA2S7LBM-DN55-gzN.js";
-import { r as ne, t as re } from "./chunk-GNY47TPC-BByCj-tp.js";
+import { r as ne, t as re } from "./chunk-GNY47TPC-D4sl5ZSh.js";
 //#region ../../node_modules/chevrotain/node_modules/lodash-es/_freeGlobal.js
 var ie = typeof global == "object" && global && global.Object === Object && global, ae = typeof self == "object" && self && self.Object === Object && self, b = ie || ae || Function("return this")(), oe = b.Symbol, se = Object.prototype, ce = se.hasOwnProperty, le = se.toString, ue = oe ? oe.toStringTag : void 0;
 function de(e) {

package/dist/vite.js

@@ -1,2 +1,7 @@
-import { cspAssetsInlineLimit as e, pdfkitStandardFonts as t } from "@nxgt/material-core/vite";
-export { e as cspAssetsInlineLimit, t as pdfkitStandardFonts };
+import { CSP_NONCE_PLACEHOLDER as e, ZOD_JITLESS_SCRIPT as t, cspAssetsInlineLimit as n, nxgtMaterial as r, pdfkitStandardFonts as i } from "@nxgt/material-core/vite";
+//#region lib/vite/index.ts
+function a(e) {
+	return r(e, "@nxgt/material-vue");
+}
+//#endregion
+export { e as CSP_NONCE_PLACEHOLDER, t as ZOD_JITLESS_SCRIPT, n as cspAssetsInlineLimit, a as nxgtMaterial, i as pdfkitStandardFonts };

package/docs/README.md

@@ -14,8 +14,11 @@ detail: every option, the second example, and the traps.
 | [Printing](guides/printing.md) | You lay out a printable document (invoice, report) with the `Print*` components |
 | [PDF documents](guides/pdf.md) | You produce a PDF file from data with `@nxgt/material-vue/pdf`: in the browser (`usePdf`, `PdfDownloadButton`) or from a Nuxt server route (`pdfResponse`), fonts on an inlined server |
 | [Maps](guides/maps.md) | You render Leaflet maps or a location field with `@nxgt/material-vue/map` |
+| [Backgrounds](guides/backgrounds.md) | You want a gradient or patterned backdrop: tones, intensity, the opt-in `backgrounds.css`, custom colours, motion and CSP |
 | [SSR](guides/ssr.md) | Your app renders on a server — Nuxt or a Vite SSR server — and bundles this package |
 | [Content Security Policy](guides/csp.md) | Your app sends a strict CSP: the directives to use, the components that still inject a `<style>`, the zod and KaTeX settings, self-hosting a font, the per-request nonce |
+| [The Vite plugin](guides/vite-plugin.md) | You are adding `nxgtMaterial()` to `vite.config.ts`: the CSP by hash or nonce, fonts, the styles check, PDFs on a bundled server and the Nuxt module, and each option's opt-out |
+| [Migrating to the Vite plugin](guides/migrate-to-vite-plugin.md) | Your app has its own CSP header, nonce, `zod-config`, Inter import or PDF bundling, and you move it to `nxgtMaterial()`: search → replace pairs, each with how to verify |
 | [Helpers](guides/helpers.md) | You need a utility, composable, Pinia store factory or type from `/lib`, `/composables`, `/i18n`, `/models`, `/types` or `/dnd` |
 | [Troubleshooting](troubleshooting.md) | Something failed and you have an error message or a symptom |
 | [Roadmap](roadmap.md) | You want to know what is planned, what shipped, and what will not be done |

package/docs/components/buttons-and-actions.md

@@ -298,6 +298,8 @@ replace that name, so pass one only when it should differ from the label.
 own, so it is not announced as "collapsed". Used as a popover, drawer or menu
 trigger (`as-child`), it carries that trigger's `aria-expanded`.
 
+A `tooltip` always opens below 768 px or with `expanded={false}`. On a desktop width, or with `expanded`, one that repeats the visible label is not opened, and one that adds to it ("Create order (Ctrl+N)") still opens.
+
 **Storybook:** `Buttons & actions/ResponsiveButton` · **React:** `ResponsiveButton`
 
 ---

package/docs/components/data-table-filter-and-lists.md

@@ -80,7 +80,8 @@ table enables, for typing your own column defs.
 | `data` | `T[]` | — | rows; sorting, filtering and pagination run client-side |
 | `#expanded="{ row }"` / `renderExpandedRow` | slot / `(row) => VNode` | — | makes rows expandable; pair with the `expand` column |
 | `showViewOptions` | `boolean` | — | column visibility menu above the table |
-| `#actions="{ table }"` / `actions` | slot / `(table) => VNode` | — | toolbar content with access to the table (selected rows…) |
+| `#actions="{ table }"` / `actions` | slot / `(table) => VNode` | — | toolbar content with access to the table (selected rows…); disabled while `loading` |
+| `#filters="{ table }"` / `filters` | slot / `(table) => VNode` | — | a search or filter controls, on the toolbar's start side; unlike `actions` they stay enabled while `loading`, so a search typed during a reload keeps its focus and text |
 | `onLoadMore` / `isLoadingMore` | `() => void` / `boolean` | — | adds a "load more" button under the rows |
 | `options` | `{ showPage?: boolean; showSelected?: boolean }` | both shown | parts of the footer |
 | `showHeader` | `boolean` | shown | header row (column names, sorting, "Select all") at every width; `false` hides it |
@@ -89,10 +90,13 @@ table enables, for typing your own column defs.
 | `loading` | `boolean` | `false` | skeleton rows, or the current rows dimmed; `aria-busy`; controls disabled |
 | `loadingRows` | `number` | the page size | how many skeleton rows |
 | `density` | `'comfortable' \| 'compact'` | `'comfortable'` | `compact` tightens the cell padding, the row and header heights and the gap between rows, the selection column included; it is the table's `data-density` attribute, styled with classes (no inline style). The toolbar band and the empty state keep their size; the print variant is unchanged |
-| `#empty="{ filtered }"` | slot | icon and "No data available" | content of the empty row, spanning every visible column |
+| `#empty="{ filtered }"` | slot | a compact `EmptyState`: "No data available", or "No results" when filtered | content of the empty row, spanning every visible column |
+| `#empty-filtered` | slot | none (falls back to `#empty`, then the default) | content of the empty row when rows exist but the filters hide every one; wins over `#empty` then |
 | `manual` | `boolean` | `false` | `data` is one server page: no client filtering, sorting or paging; the footer is the server footer ([server-side data](#server-side-data)) |
 | `v-model:sorting` | `SortingState` | held inside | controlled sorting; `update:sorting` gets the new state |
 | `getRowId` | `(row, index) => string` | the index | the row's id, the key of the row selection |
+| `enableRowSelection` | `boolean \| (row) => boolean` | `true` | which rows can be selected (`row` is the data). A row that cannot has a disabled checkbox; "Select all" skips it and its checked and indeterminate states count only selectable rows. A locked row already in the selection can be cleared by its own box (and only cleared) |
+| `rowSelectionDisabledReason` | `(row) => string \| undefined` | — | why a row cannot be selected: its checkbox is `aria-disabled` but stays focusable, shows the reason in a tooltip on hover and focus, and has it as its `aria-describedby`; without a reason it is a plain `disabled` box |
 | `v-model:row-selection` | `RowSelectionState` | held inside | controlled selection, by id; may hold rows of other pages |
 | `pagination` | `{ totalCount?, offset?, previous?, next? }` | — | the server footer's range ("41–60 of 133") and Previous / Next: an href (a link) or a callback (a button) |
 | `#footer="{ table }"` / `footer` | slot / `false \| (table) => VNode` | the pagination | replaces the footer; `false` removes it |
@@ -141,13 +145,60 @@ arrives. Sorting (`DataTableColumnHeader`), the `select` column's "Select
 all", the toolbar's native controls (it
 is a disabled `<fieldset>`, so every input or button you render there, a
 filter or an export, is disabled
-too) and pagination are disabled meanwhile.
-
-When no row is left after filtering, the empty state is one `TableEmpty`
-cell spanning every visible column: today's icon and "No data available" by
-default, or the `#empty` slot, told whether rows exist but none matches the
-filters (`filtered`); content that renders nothing gets the default.
+too) and pagination are disabled meanwhile. The toolbar's `actions` are in that fieldset; a search or filter you want to keep typing in while the list reloads goes in `#filters` (or `filters`) instead, which sits beside it and stays enabled (its focus and text survive a reload).
+
+When no row is left, the empty state is one `TableEmpty` cell spanning every
+visible column. What it holds, first match wins:
+
+1. the `#empty-filtered` slot, when rows exist but the filters hide every one
+   (`filtered`);
+2. the `#empty` slot, told `{ filtered }`;
+3. the default, a compact `EmptyState`: "No data available"
+   (`material.table.labels.no-data`) for a table with no data, or, when
+   filtered, "No results" and "Try a different search or clear the filters."
+   (`material.table.labels.no-results`, `no-results-description`) announced by the table's
+   status.
+
+A slot that renders nothing falls through to the next step; there is no blank
+option, the default shows. When the filters hide every row, the table's hidden
+status announces "No results. Try a different search or clear the filters."
+whatever the visible content is. `#empty-filtered`
+is not used for a table with no data at all, nor with `manual` (server-side
+data): the table cannot tell a filtered page from an empty one there, so it
+reads `filtered` as `false`; branch on your own filter state in `#empty`.
 `DataTableEmptyState` types the slot props.
+`filtered` is computed from the core row model (`getCoreRowModel().rows.length > 0`), as in React.
+
+```vue
+<DataTable :data="people" :columns="columns">
+  <template #empty>No people yet.</template>
+  <template #empty-filtered>No person matches these filters.</template>
+</DataTable>
+```
+
+### Locked rows and a search that stays usable
+
+`enableRowSelection` leaves rows out of the selection, `rowSelectionDisabledReason` says why, and `#filters` keeps a search enabled while the list reloads (`#actions` is disabled meanwhile):
+
+```vue
+<DataTable
+  v-model:row-selection="selection"
+  :columns="columns"
+  :data="proposals"
+  :loading="isFetching"
+  :enable-row-selection="(proposal) => proposal.status !== 'applied'"
+  :row-selection-disabled-reason="() => 'Already applied'"
+>
+  <template #filters>
+    <SearchField v-model="q" label="Search" />
+  </template>
+  <template #actions="{ table }">
+    <Button>Apply to {{ table.getSelectedRowModel().rows.length }}</Button>
+  </template>
+</DataTable>
+```
+
+A locked row's checkbox is `aria-disabled` but focusable, so Tab reaches it and the tooltip says why; "Select all" skips it.
 
 ### Phones and narrow screens
 

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` |