@nxgt/material-vue 0.42.0 → 0.43.0

package/docs/troubleshooting.md

@@ -17,15 +17,19 @@ words in your error.
 **Styles & assets**
 
 - [Components render unstyled, with no error](#components-render-unstyled-with-no-error)
+- [A link is blue and underlined on hover and focus](#a-link-of-mine-or-of-a-component-is-blue-and-underlined-on-hover-and-focus)
 - [Math renders in the system fonts](#math-renders-in-the-system-fonts)
 - [`<Icon>` renders nothing](#icon-renders-nothing)
 - [An accessibility audit reports low contrast on a badge, a button, a toast or a menu entry](#an-accessibility-audit-reports-low-contrast-on-a-badge-a-button-a-toast-or-a-menu-entry)
 - [`ARIA hidden element must not be focusable or contain focusable elements`](#aria-hidden-element-must-not-be-focusable-or-contain-focusable-elements)
 - [An accessibility audit reports low contrast on a tonal or outlined button, a selected list tile or a hovered badge link](#an-accessibility-audit-reports-low-contrast-on-a-tonal-or-outlined-button-a-selected-list-tile-or-a-hovered-badge-link)
 - [An accessibility audit reports low contrast on error text in the dark theme](#an-accessibility-audit-reports-low-contrast-on-error-text-in-the-dark-theme)
+- [An accessibility audit reports low contrast on primary text in the dark theme](#an-accessibility-audit-reports-low-contrast-on-primary-text-in-the-dark-theme)
 - [Dialogs, toasts or buttons no longer animate](#dialogs-toasts-or-buttons-no-longer-animate)
 - [A Content-Security-Policy reports a `data:` image on every form with a required field](#a-content-security-policy-reports-a-data-image-on-every-form-with-a-required-field)
 - [A Button's label overflows a card on a phone](#a-buttons-label-overflows-a-card-on-a-phone)
+- [A ResponsiveButton no longer shows its tooltip next to its visible label](#a-responsivebutton-no-longer-shows-its-tooltip-next-to-its-visible-label)
+- [An input now has `placeholder=" "` in the DOM](#an-input-now-has-placeholder--in-the-dom)
 - [A dialog or sheet scrolls, or clips a child, after upgrading](#a-dialog-or-sheet-scrolls-or-clips-a-child-after-upgrading)
 - [A form's fields no longer scroll in their own box after upgrading](#a-forms-fields-no-longer-scroll-in-their-own-box-after-upgrading)
 - [axe reports `target-size` on a control under a form's sticky actions](#axe-reports-target-size-on-a-control-under-a-forms-sticky-actions)
@@ -39,6 +43,8 @@ words in your error.
 - [A test no longer finds a date or time picker by the `button` role, or a slider thumb by the exact name `Minimum`](#a-test-no-longer-finds-a-date-or-time-picker-by-the-button-role-or-a-slider-thumb-by-the-exact-name-minimum)
 - [An end-to-end test no longer finds a required field by a name ending in `*`](#an-end-to-end-test-no-longer-finds-a-required-field-by-a-name-ending-in-)
 - [A test no longer finds `aria-invalid` on an upload field's group or drop zone](#a-test-no-longer-finds-aria-invalid-on-an-upload-fields-group-or-drop-zone)
+- [An `Autocomplete` test no longer finds a `textbox` or `button`, or the list no longer opens on focus](#an-autocomplete-test-no-longer-finds-a-textbox-or-button-or-the-list-no-longer-opens-on-focus)
+- [Enter in an `Autocomplete` submits the form instead of picking](#enter-in-an-autocomplete-submits-the-form-instead-of-picking)
 - [A test no longer finds `aria-invalid` on a `Switch` row or an `Autocomplete` box](#a-test-no-longer-finds-aria-invalid-on-a-switch-row-or-an-autocomplete-box)
 - [An `Autocomplete` lists more options than before, or "ecole" finds "École"](#an-autocomplete-lists-more-options-than-before-or-ecole-finds-école)
 - [`@query-change` runs more often after upgrading](#query-change-runs-more-often-after-upgrading)
@@ -63,6 +69,8 @@ words in your error.
 
 **Feedback**
 
+- [An `EmptyState` shows "Something Went Wrong"](#an-emptystate-shows-something-went-wrong)
+- [An `EmptyState` with an error `variant` is not announced, or `ErrorState` ignores my `empty-state` overrides](#an-emptystate-with-an-error-variant-is-not-announced-or-errorstate-ignores-my-empty-state-overrides)
 - [A toast with an action never goes away](#a-toast-with-an-action-never-goes-away)
 - [A toast covers the form's button on a phone](#a-toast-covers-the-forms-button-on-a-phone)
 - [A toast never goes away after a tap](#a-toast-never-goes-away-after-a-tap)
@@ -122,6 +130,8 @@ words in your error.
 - [`Cannot find module '#standard-fonts/Helvetica'`](#cannot-find-module-standard-fontshelvetica)
 - [`Cannot find module '…/pdfkit/js/standard-fonts/Helvetica.cjs'`](#cannot-find-module-pdfkitjsstandard-fontshelveticacjs)
 - [`still references '#standard-fonts/' after the transform`](#still-references-standard-fonts-after-the-transform)
+- [`[nxgt-material] pdf.bundleStandardFonts is deprecated: use pdf.bundle.`](#nxgt-material-pdfbundlestandardfonts-is-deprecated-use-pdfbundle)
+- [`[nxgt-material] @fontsource-variable/inter is not installed: keeping the system font. Install it to use Inter (bun add @fontsource-variable/inter), or drop fonts: { sans: 'inter' }.`](#nxgt-material-fontsource-variableinter-is-not-installed-keeping-the-system-font-install-it-to-use-inter-bun-add-fontsource-variableinter-or-drop-fonts--sans-inter-)
 - [`renderToStream is a Node specific API` / `renderToBuffer is a Node specific API`](#rendertostream-is-a-node-specific-api--rendertobuffer-is-a-node-specific-api)
 - [PDF rendering fails on an edge runtime](#pdf-rendering-fails-on-an-edge-runtime)
 - [`[pdf] No renderer for the custom node`](#pdf-no-renderer-for-the-custom-node)
@@ -190,6 +200,7 @@ words in your error.
 - [A `DataTable` shows its header row on a phone](#a-datatable-shows-its-header-row-on-a-phone)
 - [A test's `getByRole('region')` finds more than one region](#a-tests-getbyroleregion-finds-more-than-one-region)
 - [A `DataTable` toolbar is gone](#a-datatable-toolbar-is-gone)
+- [A search in the `DataTable` toolbar loses focus while the list reloads](#a-search-in-the-datatable-toolbar-loses-focus-while-the-list-reloads)
 - [axe reports `target-size` on a `DataTable`'s "Select all"](#axe-reports-target-size-on-a-datatables-select-all)
 - [A French test no longer finds the sort menu's "Asc" or "Desc"](#a-french-test-no-longer-finds-the-sort-menus-asc-or-desc)
 
@@ -220,8 +231,19 @@ words in your error.
 - [`FilePreview` shows a file card with a Download link for a PDF](#filepreview-shows-a-file-card-with-a-download-link-for-a-pdf)
 - [`FilePreview` says "This file could not be previewed."](#filepreview-says-this-file-could-not-be-previewed)
 
+**Backgrounds**
+
+- [`Background: preset "<id>" is not available yet; drawing "gradient".`](#background-preset-id-is-not-available-yet-drawing-gradient)
+- [A grain or preset `Background` looks bare, with no error](#a-grain-or-preset-background-looks-bare-with-no-error)
+
 **Content Security Policy**
 
+- [`[nxgt-material] html.cspNonce is set, but the CSP is in hash mode (the default): set nxgtMaterial({ csp: { mode: 'nonce' } }) or drop html.cspNonce.`](#nxgt-material-htmlcspnonce-is-set-but-the-csp-is-in-hash-mode-the-default-set-nxgtmaterial-csp--mode-nonce---or-drop-htmlcspnonce)
+- [`Invalid CSP nonce: only A-Z, a-z, 0-9, "+", "/", "_", "=" and "-" are allowed, got …`](#invalid-csp-nonce-only-a-z-a-z-0-9---_--and---are-allowed-got-)
+- [`The CSP nonce is the build placeholder "NXGT_CSP_NONCE", which is public: generate one per request with createCspNonce().`](#the-csp-nonce-is-the-build-placeholder-nxgt_csp_nonce-which-is-public-generate-one-per-request-with-createcspnonce)
+- [`[nxgt-material] no index.html in this build: the CSP part did nothing. On a server, send cspPolicy({ nonce }).header and zodJitlessTag(nonce) per request, or pass csp: false.`](#nxgt-material-no-indexhtml-in-this-build-the-csp-part-did-nothing-on-a-server-send-csppolicy-nonce-header-and-zodjitlesstagnonce-per-request-or-pass-csp-false)
+- [`[nxgt-material] @nxgt/material-vue's stylesheet is never imported`](#nxgt-material-nxgtmaterial-vues-stylesheet-is-never-imported)
+- [`[nxgt-material] @fontsource-variable/inter is not installed`](#nxgt-material-fontsource-variableinter-is-not-installed)
 - [`Refused to apply inline style because it violates the following Content Security Policy directive`](#refused-to-apply-inline-style-because-it-violates-the-following-content-security-policy-directive)
 - [`Refused to load the font 'data:font/woff2…' because it violates the following Content Security Policy directive: "font-src 'self'"`](#refused-to-load-the-font-datafontwoff2-because-it-violates-the-following-content-security-policy-directive-font-src-self)
 - [`Refused to load the font 'https://fonts.gstatic.com/…' because it violates the following Content Security Policy directive: "font-src 'self'"`](#refused-to-load-the-font-httpsfontsgstaticcom-because-it-violates-the-following-content-security-policy-directive-font-src-self)
@@ -604,6 +626,38 @@ const files = page.getByRole('group', { name: 'Attachments' });
 await expect(files).toHaveAccessibleDescription('Add at least one file.');
 ```
 
+### An `Autocomplete` test no longer finds a `textbox` or `button`, or the list no longer opens on focus
+
+**When:** after upgrading, `getByRole('textbox')` finds no `Autocomplete` input,
+`getByRole('button', { name: 'Paris' })` finds no option, or focusing the input
+(a dialog that focuses its first field) no longer opens the list.
+**Why:** the `Autocomplete` follows the ARIA 1.2 combobox pattern, as in
+`@nxgt/material`: the input is a `combobox` (`aria-expanded`, `aria-controls`,
+`aria-activedescendant`), the list a `listbox` of `option`s. The list opens on a
+click or on typing, no longer on focus.
+**Fix:** query by the new roles and open the list with a click:
+
+```ts
+const input = page.getByRole('combobox', { name: 'Country' });
+await input.click();
+await page.getByRole('option', { name: 'France' }).click();
+```
+
+### Enter in an `Autocomplete` submits the form instead of picking
+
+**When:** after upgrading, pressing Enter in an `Autocomplete` whose list is
+shut submits the surrounding form, where it used to pick the first option.
+**Why:** a shut list shows nothing to pick, so Enter keeps its form meaning.
+The list opens on a click, on typing or on ArrowDown, and Enter then picks the
+highlighted option (the first enabled one until the arrow keys move it).
+**Fix:** open the list first in your test or flow:
+
+```ts
+const input = page.getByRole('combobox', { name: 'Country' });
+await input.press('ArrowDown');
+await input.press('Enter');
+```
+
 ### A test no longer finds `aria-invalid` on a `Switch` row or an `Autocomplete` box
 
 **When:** after upgrading to 0.22.0, `[aria-invalid]` on the bordered row of a
@@ -1224,6 +1278,29 @@ on a section) changes nothing: `@theme` resolves `--color-error-text` on the
 root. Below the root, set `--color-error-text` (and `--color-error` for fills)
 on that element, or put the override on the root.
 
+### An accessibility audit reports low contrast on primary text in the dark theme
+
+**When:** `Typography tone="primary"`, a link, an icon or a label of your own in
+the brand colour fails 4.5:1 (text) or 3:1 (icon) in the dark theme, about 2:1
+on the page; the catalogue's own primary text passes.
+**Why:** it is drawn with `text-primary`, the fill colour. The brand colour is
+dark so that near-white text reads on it, which makes it too dark to read as
+text on the dark surfaces. Primary text has its own token, `--primary-text`:
+the same colour in light, `--primary` mixed 60 % with white in dark.
+**Fix:** draw primary text with `text-primary-text`; keep `text-primary` for
+fills, borders and rings:
+
+```vue
+// before
+<a class="text-primary underline" href="/docs">Docs</a>
+// after
+<a class="text-primary-text underline" href="/docs">Docs</a>
+```
+
+An app that overrides `--primary` under `:root` and `.dark, [data-theme="dark"]`
+gets `--primary-text` for free; set `--primary-text` after it to choose another
+colour. On an element below the root, set `--color-primary-text`.
+
 ### Dialogs, toasts or buttons no longer animate
 
 **When:** a transition or an animation of a catalogue component does not run
@@ -1313,6 +1390,21 @@ actions where they are, make them static:
 An app's own fixed bottom bar or floating action button now sits under the
 sticky actions (`z-index: 10`): give it a z-index above 10 (`class="z-20"`).
 
+### A link of mine, or of a component, is blue and underlined on hover and focus
+
+**When:** an `<a>` you render, or one a component renders, takes the info
+colour, an underline and an info tint on hover and focus that you did not
+ask for.
+**Why:** `styles.css` styles every `<a>` as a link in running text. The
+components' own links opt out; an anchor of yours that has its own look
+(a card, a menu entry, a button-like link) does not unless you say so.
+**Fix:** add the `nxgt-plain-link` class to the anchor; it then inherits its
+text colour and gets no underline or tint. See [Links](guides/theming.md#links).
+
+```vue
+<a href="/pricing" class="nxgt-plain-link flex items-center gap-2 p-2">Pricing</a>
+```
+
 ### axe reports `target-size` on a control under a form's sticky actions
 
 **When:** since the form's actions stick to the bottom (see above), axe's
@@ -1333,8 +1425,38 @@ await page.addStyleTag({
 await expectAccessible(page);
 ```
 
+### A ResponsiveButton no longer shows its tooltip next to its visible label
+
+**When:** a `ResponsiveButton` with a `tooltip` on a desktop width (768 px and up, or `expanded`), where the tooltip used to appear beside the label.
+**Why:** the tooltip repeated the label, so it is not opened any more (it is not merely hidden: an open one would still set `aria-describedby` and take the first Escape inside a dialog). It still opens when it says something the label does not, such as `Create order (Ctrl+N)`, and always when the button is collapsed to its icon (below 768 px, or `expanded` false).
+**Fix:** nothing, if the tooltip repeats the label. To keep one on a wide screen, give it text that adds to the label.
+
+### An input now has `placeholder=" "` in the DOM
+
+**When:** a test selects `input:not([placeholder])` or compares an `InputGroupInput` or `InputGroupField` that has no `placeholder` with an attribute-less snapshot.
+**Why:** the "filled" tint relies on `:placeholder-shown`, which only matches a field that has a placeholder. A text field without one (or with `placeholder=""`) now renders a blank `placeholder=" "`, so an empty field is not tinted as if it held a value. It draws nothing and is not announced.
+**Fix:** select by role and accessible name (`getByRole('textbox', { name: ... })`) rather than by the missing attribute, and update the snapshot.
+
 ## Feedback
 
+### An `EmptyState` shows "Something Went Wrong"
+
+**When:** `<EmptyState />` renders the title "Something Went Wrong" (or "Une erreur est survenue") and an error illustration, for a list, a table or a page that is simply empty.
+**Why:** with neither `kind` nor `variant`, `EmptyState` keeps its old default, `generic`, until 1.0, when it becomes `kind="empty"`.
+**Fix:** pass `kind` (`empty`, `search`, `not-found` or `unauthorized`). When something did fail, use `ErrorState` instead (see [Feedback & status](components/feedback-and-status.md#errorstate)):
+
+```vue
+<EmptyState kind="empty" />
+<!-- a failure, with a Retry button -->
+<ErrorState kind="generic" :error="error" @retry="refetch" />
+```
+
+### An `EmptyState` with an error `variant` is not announced, or `ErrorState` ignores my `empty-state` overrides
+
+**When:** an `EmptyState variant="generic"`, `"offline"` or `"maintenance"` is no longer found by `getByRole('alert')`, or the text you set under `material.empty-state.generic|offline|maintenance` does not appear in an `ErrorState`.
+**Why:** `variant` is deprecated and removed in 1.0. Its error values render the error illustration without `role="alert"`; `ErrorState` is the `role="alert"` block, and it reads its own keys, `material.error-state.<kind>.title` and `description`.
+**Fix:** replace `<EmptyState variant="offline" />` with `<ErrorState kind="offline" />`, and copy your overrides to `material.error-state.<kind>.*` (see [the i18n guide](guides/i18n.md#empty-and-error-states)).
+
 ### A toast with an action never goes away
 
 **When:** a test, or a user, waits for a toast to disappear by itself, and one
@@ -2266,7 +2388,7 @@ appears when the renderer is inlined.
 // nuxt.config.ts
 export default defineNuxtConfig({
   modules: ['@nxgt/material-vue/nuxt'],
-  nxgtMaterial: { pdf: { bundleStandardFonts: true } },
+  nxgtMaterial: { pdf: { bundle: true } },
 });
 ```
 
@@ -2275,11 +2397,10 @@ In a Vite SSR server:
 ```ts
 // vite.config.ts
 import { defineConfig } from 'vite';
-import { pdfkitStandardFonts } from '@nxgt/material-vue/vite';
+import { nxgtMaterial } from '@nxgt/material-vue/vite';
 
 export default defineConfig({
-  plugins: [pdfkitStandardFonts()],
-  ssr: { noExternal: ['@nxgt/material-vue', '@nxgt/material-core'] },
+  plugins: [...nxgtMaterial({ pdf: { bundle: true } })],
 });
 ```
 
@@ -2327,9 +2448,9 @@ export default defineNitroConfig({
 
 With `nitro.externals` set to a boolean, the module leaves Nitro's trace
 alone: add the `traceInclude` above yourself (as an `externals` object), or
-inline the server and use `bundleStandardFonts`. A server built with
+inline the server and use `pdf.bundle`. A server built with
 `noExternals` has no `node_modules` to trace into: use
-`bundleStandardFonts` instead ([above](#cannot-find-module-standard-fontshelvetica)).
+`pdf.bundle` instead ([above](#cannot-find-module-standard-fontshelvetica)).
 The module resolves them with `pdfkitStandardFontFiles(rootDir, warn)` from
 `@nxgt/material-core/pdfkit-fonts` (Node-only); a Nitro config can call it
 too, with `@nxgt/material-core` installed as a direct dependency, in place
@@ -2338,10 +2459,27 @@ When the module cannot resolve pdfkit's fonts although `@react-pdf/renderer`
 is installed, `nuxi build` prints one `pdf fonts:` warning naming everything
 that failed.
 
+### `[nxgt-material] pdf.bundleStandardFonts is deprecated: use pdf.bundle.`
+
+**When:** at `nuxi build` or `nuxi dev`, as a warning, with the old option.
+**Why:** the Nuxt module now takes the same `pdf` option as `nxgtMaterial()`.
+**Fix:** rename it; nothing else changes.
+
+```ts
+nxgtMaterial: { pdf: { bundle: true } }, // was pdf: { bundleStandardFonts: true }
+```
+
+### `[nxgt-material] @fontsource-variable/inter is not installed: keeping the system font. Install it to use Inter (bun add @fontsource-variable/inter), or drop fonts: { sans: 'inter' }.`
+
+**When:** at `nuxi build` or `nuxi dev`, after setting `nxgtMaterial: { fonts: { sans: 'inter' } }`. A warning, once; the build succeeds and the page keeps the system font.
+**Why:** the module loads Inter through `css`, and the package is an optional peer.
+**Fix:** `bun add @fontsource-variable/inter` to use Inter, or drop the option.
+In a plain Vite app the same package gives [a different message](#nxgt-material-fontsource-variableinter-is-not-installed).
+
 ### `still references '#standard-fonts/' after the transform`
 
 **When:** at build, from the `nxgt-material:pdfkit-standard-fonts` plugin
-(added by `pdfkitStandardFonts()` or the Nuxt `pdf.bundleStandardFonts`
+(added by `nxgtMaterial()`, `pdfkitStandardFonts()` or the Nuxt `pdf.bundle`
 option).
 **Why:** a pdfkit release changed how it loads its standard fonts, and the
 plugin could not rewrite every call. It fails the build on purpose, rather
@@ -3036,6 +3174,7 @@ await page.getByRole('button', { name: /^(Close|Fermer)$/ }).click();
 | `breadcrumb` (the `nav`'s name), `More` | `Fil d'Ariane`, `Plus` | `breadcrumb.label`, `breadcrumb.more` |
 | `Breadcrumb` (`DocHeader`) | `Fil d'Ariane` | `doc.breadcrumb` |
 | `Command Palette`, `Search for a command to run...` (`CommandDialog`) | `Palette de commandes`, `Recherchez une commande à exécuter...` | `command.title`, `command.description` |
+| `Suggestions` (`CommandList`'s name) | `Commandes suggérées` | `command.list` |
 | `carousel`, `slide` (`aria-roledescription`) | `carrousel`, `diapositive` | `carousel.roledescription`, `carousel.slide` |
 | `No filters available`, `+2 more` | `Aucun filtre disponible`, `+2 de plus` | `filter.empty`, `filter.more` |
 | `Yes` / `No`, `From 5`, `Until …`, `Up to 9` (filter chips) | `Oui` / `Non`, `À partir de 5`, `Jusqu'au …`, `Jusqu'à 9` | `filter.value.*` |
@@ -3596,6 +3735,19 @@ page.getByRole('region', { name: 'Invoices' });
 **Why:** the toolbar is rendered only when it has content (yours, or `show-view-options`): an empty `<fieldset>` is a nameless group to a screen reader.
 **Fix:** look for what the toolbar holds (a filter by its label, the view options by "View"), not for the `fieldset` itself. A component of yours that renders nothing still counts as content: render it conditionally instead.
 
+### A search in the `DataTable` toolbar loses focus while the list reloads
+
+**When:** a search or filter input is rendered by `actions` or the `#actions` slot, and the list reloads (`loading` turns `true`) while you type: the input loses focus and the keystrokes stop.
+**Why:** the `actions` band is a `<fieldset disabled={loading}>`, so every native control in it is disabled while the table loads, and a disabled input cannot keep the focus.
+**Fix:** move the search to the `#filters` slot (or `filters`), which sits beside that fieldset and stays enabled; keep only the actions that act on rows in `#actions`.
+
+```vue
+<DataTable :loading="isFetching">
+  <template #filters><SearchField v-model="q" /></template>
+  <template #actions="{ table }">...</template>
+</DataTable>
+```
+
 ### axe reports `target-size` on a `DataTable`'s "Select all"
 
 **When:** axe (WCAG 2.5.8) flags the header row's "Select all" checkbox (`thead [data-slot="checkbox-field"]`) when the column after the `select` column is a sortable `DataTableColumnHeader`, mostly on a phone, where the columns are narrowest. The rows' checkboxes pass.
@@ -4032,10 +4184,102 @@ beginning is shown, with "Showing the first … of this file." below.
 
 ---
 
+## Backgrounds
+
+How the presets work is in the [Backgrounds guide](guides/backgrounds.md).
+
+### `Background: preset "<id>" is not available yet; drawing "gradient".`
+
+**When:** in development (not when `NODE_ENV` is `production`), the first time a `Background` from `@nxgt/material-vue/backgrounds` gets a `preset` that does not ship yet, or a typo from JavaScript. It is printed once per id.
+**Why:** `BACKGROUND_PRESETS` lists the planned presets; only the ones in `SHIPPED_BACKGROUND_PRESETS` are drawn today. Any other id draws the gradient.
+**Fix:** use a shipped preset:
+
+```ts
+import { SHIPPED_BACKGROUND_PRESETS } from '@nxgt/material-vue/backgrounds';
+
+console.log(SHIPPED_BACKGROUND_PRESETS); // ['gradient', 'grain']
+```
+
+### A grain or preset `Background` looks bare, with no error
+
+**When:** `grain` or `preset="grain"` shows no film noise, or a `Background` from `/backgrounds` has only the plain gradient.
+**Why:** the presets' CSS is opt-in and not part of `styles.css`; without it the grain overlay is not shown, and nothing is reported.
+**Fix:** import the stylesheet of the presets you use, once:
+
+```ts
+import '@nxgt/material-vue/backgrounds.css'; // every preset
+// or one file: '@nxgt/material-vue/backgrounds/grain.css'
+```
+
+---
+
 ## Content Security Policy
 
 How to set up the policy is in the [Content Security Policy guide](guides/csp.md).
 
+### `[nxgt-material] html.cspNonce is set, but the CSP is in hash mode (the default): set nxgtMaterial({ csp: { mode: 'nonce' } }) or drop html.cspNonce.`
+
+**When:** `vite build` or `vite` with `nxgtMaterial()` in its default hash mode, while your config sets Vite's `html.cspNonce`.
+
+**Why:** hash mode writes no nonce into the HTML; a `html.cspNonce` would put a fixed value there that the plugin's header does not match.
+
+**Fix:** drop `html.cspNonce`, or choose nonce mode, where the plugin sets it for you:
+
+```ts
+nxgtMaterial({ csp: { mode: 'nonce' } })
+```
+
+### `Invalid CSP nonce: only A-Z, a-z, 0-9, "+", "/", "_", "=" and "-" are allowed, got …`
+
+**When:** `nxgtMaterial({ csp: { mode: 'nonce' } })` with a `csp.placeholder` (or an `html.cspNonce`) that is empty or holds a character outside the base64 alphabet, such as a quote or a space.
+
+**Fix:** leave `csp.placeholder` out (the default is `NXGT_CSP_NONCE`), or use only letters, digits, `+`, `/`, `_`, `-` and `=`.
+
+### `The CSP nonce is the build placeholder "NXGT_CSP_NONCE", which is public: generate one per request with createCspNonce().`
+
+**When:** a server hands `applyCspNonce` or `cspPolicy` the nonce the build left in the HTML (`NXGT_CSP_NONCE`, or your `csp.placeholder`) instead of a fresh one.
+
+**Why:** the placeholder is written in the built HTML, so anyone can read it; a policy that trusts it trusts anything.
+
+**Fix:** generate a nonce per request and use the same one in the page and in the header:
+
+```ts
+import { applyCspNonce, createCspNonce, cspPolicy } from '@nxgt/material-vue/lib';
+
+const nonce = createCspNonce();
+const page = applyCspNonce(builtHtml, nonce);
+const { header } = cspPolicy({ nonce });
+```
+
+The server helpers' other messages (`Invalid CSP hash`, `Invalid CSP directive name` and `Invalid CSP source`, `A CSP nonce needs at least 16 random bytes`, `applyCspNonce: the HTML holds no "NXGT_CSP_NONCE" placeholder`) are in `@nxgt/material-core`'s [troubleshooting page](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/troubleshooting.md#content-security-policy).
+
+### `[nxgt-material] no index.html in this build: the CSP part did nothing. On a server, send cspPolicy({ nonce }).header and zodJitlessTag(nonce) per request, or pass csp: false.`
+
+**When:** a client `vite build` that emits no `index.html` (Nuxt, a library build, an SSR framework's client build). It is a warning, printed once, not an error.
+
+**Why:** the CSP part hashes the inline scripts of the built HTML, or leaves a nonce placeholder in it. With no HTML there is nothing to do. The fonts part still works.
+
+**Fix:** on a server, send `cspPolicy({ nonce }).header` and put `zodJitlessTag(nonce)` in the head of every response (both from `@nxgt/material-vue/lib`), or silence the warning with `nxgtMaterial({ csp: false })`.
+
+### `[nxgt-material] @nxgt/material-vue's stylesheet is never imported`
+
+**When:** `vite build` with `nxgtMaterial()` finds no stylesheet or module that imports `@nxgt/material-vue/styles.css`, and no stylesheet that imports the compiled one (`@import "@nxgt/material-vue";`); every component would render unstyled.
+
+**Fix:** add the line the message prints to your main stylesheet, after Tailwind's own import:
+
+```css
+@import "@nxgt/material-vue/styles.css";
+```
+
+or import `@nxgt/material-vue/styles.css` from your entry. An app without Tailwind imports the compiled stylesheet instead, `@import "@nxgt/material-vue";`, which the check accepts too. A build that has no use for the stylesheet (a Storybook build, say) opts out with `nxgtMaterial({ styles: false })`.
+
+### `[nxgt-material] @fontsource-variable/inter is not installed`
+
+**When:** `nxgtMaterial()` loads Inter only when the optional peer is installed, and it is not. A warning, once, in `vite dev` and in `vite build`; the build still succeeds and the page keeps the system font stack.
+In Nuxt the module reports [another message](#nxgt-material-fontsource-variableinter-is-not-installed-keeping-the-system-font-install-it-to-use-inter-bun-add-fontsource-variableinter-or-drop-fonts--sans-inter-).
+
+**Fix:** `bun add @fontsource-variable/inter` to use Inter, or keep the system font and silence the warning with `nxgtMaterial({ fonts: { sans: false } })`.
+
 ### `Refused to apply inline style because it violates the following Content Security Policy directive`
 
 **When:** a component mounts, or a modal opens, on a page that sends

package/lib/backgrounds/backgrounds.css

@@ -0,0 +1,8 @@
+/* Every background preset's CSS, opt-in: `import "@nxgt/material/backgrounds.css"`
+ * (the same file in @nxgt/material-vue). Not part of styles.css, which carries
+ * only the base, the gradient and the motion `Background` (from /components)
+ * needs. One preset alone: `@nxgt/material/backgrounds/<preset>.css`. */
+@import "./css/base.css";
+@import "./css/gradient.css";
+@import "./css/grain.css";
+@import "./css/motion.css";

package/lib/backgrounds/css/base.css

@@ -0,0 +1,169 @@
+/* Background presets, the base: the frame, the tone and intensity variables,
+ * the dark lift, the paused state and forced colours. Plain CSS keyed on
+ * `data-background`, which `Background` sets itself, after the caller's
+ * props, so a wrapper's own `data-slot` (ThreadLayout, ActivityLayout) cannot
+ * unhook it. No Tailwind classes and no inline `style`, so a strict CSP
+ * blocks nothing. Shared byte for byte by @nxgt/material and
+ * @nxgt/material-vue (scripts/shared-paths.ts).
+ *
+ * Everything sits in `@layer components`: a utility the app puts on the
+ * element (`h-96 w-full`, `overflow-hidden`) is in a later layer and wins.
+ *
+ * Tones become `--nxgt-bg-t1..t3` (the tokens a tone draws from) and the
+ * drawn colours `--nxgt-bg-c1..c3`; an app may override the latter on the
+ * element. 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. An app
+ * sets `--nxgt-bg-custom-1..3` in its own CSS for `tone="custom"`. */
+@layer components {
+	[data-background] {
+		--nxgt-bg-floor: 0.64;
+		--nxgt-bg-k: 1;
+		--nxgt-bg-blob: 1;
+		--nxgt-bg-t1: var(--primary);
+		--nxgt-bg-t2: var(--secondary);
+		--nxgt-bg-t3: var(--primary);
+		--nxgt-bg-c1: var(--nxgt-bg-t1);
+		--nxgt-bg-c2: var(--nxgt-bg-t2);
+		--nxgt-bg-c3: var(--nxgt-bg-t3);
+		position: relative;
+		display: flex;
+		flex-direction: column;
+		width: 100lvw;
+		height: 100lvh;
+	}
+
+	/* `fill="container"`: the size of the parent, not of the viewport. */
+	[data-background][data-fill="container"] {
+		width: 100%;
+		height: 100%;
+	}
+
+	[data-background][data-tone="secondary"] {
+		--nxgt-bg-t1: var(--secondary);
+		--nxgt-bg-t2: var(--primary);
+		--nxgt-bg-t3: var(--secondary);
+	}
+	[data-background][data-tone="tertiary"] {
+		--nxgt-bg-t1: var(--tertiary);
+		--nxgt-bg-t2: var(--primary);
+		--nxgt-bg-t3: var(--tertiary);
+	}
+	[data-background][data-tone="neutral"] {
+		--nxgt-bg-t1: var(--muted-foreground);
+		--nxgt-bg-t2: var(--foreground);
+		--nxgt-bg-t3: var(--muted-foreground);
+	}
+	[data-background][data-tone="success"] {
+		--nxgt-bg-t1: var(--success);
+		--nxgt-bg-t2: var(--info);
+		--nxgt-bg-t3: var(--success);
+	}
+	[data-background][data-tone="warning"] {
+		--nxgt-bg-t1: var(--warning);
+		--nxgt-bg-t2: var(--error);
+		--nxgt-bg-t3: var(--warning);
+	}
+	[data-background][data-tone="error"] {
+		--nxgt-bg-t1: var(--error);
+		--nxgt-bg-t2: var(--warning);
+		--nxgt-bg-t3: var(--error);
+	}
+	[data-background][data-tone="info"] {
+		--nxgt-bg-t1: var(--info);
+		--nxgt-bg-t2: var(--primary);
+		--nxgt-bg-t3: var(--info);
+	}
+	[data-background][data-tone="mixed"] {
+		--nxgt-bg-t1: var(--primary);
+		--nxgt-bg-t2: var(--secondary);
+		--nxgt-bg-t3: var(--tertiary);
+	}
+	[data-background][data-tone="custom"] {
+		--nxgt-bg-t1: var(--nxgt-bg-custom-1, var(--primary));
+		--nxgt-bg-t2: var(--nxgt-bg-custom-2, var(--secondary));
+		--nxgt-bg-t3: var(--nxgt-bg-custom-3, var(--primary));
+	}
+
+	/* Intensity: `--nxgt-bg-k` scales the frame's tint, `--nxgt-bg-blob` the blobs'
+	 * opacity. The default is 1 and 1, today's look. */
+	[data-background][data-intensity="subtle"] {
+		--nxgt-bg-k: 0.5;
+		--nxgt-bg-blob: 0.6;
+	}
+	[data-background][data-intensity="vivid"] {
+		--nxgt-bg-k: 1.6;
+	}
+
+	/* Dark: lift the drawn colours. The fallback mixes with white; the
+	 * relative colour syntax (Chrome 119, Safari 18, Firefox 128) replaces it
+	 * where it is supported. */
+	:is(.dark, [data-theme="dark"]) [data-background],
+	[data-background]:is(.dark, [data-theme="dark"]) {
+		--nxgt-bg-c1: color-mix(in oklab, var(--nxgt-bg-t1) 70%, white);
+		--nxgt-bg-c2: color-mix(in oklab, var(--nxgt-bg-t2) 70%, white);
+		--nxgt-bg-c3: color-mix(in oklab, var(--nxgt-bg-t3) 70%, white);
+	}
+	@supports (color: oklch(from red max(l, 0.5) c h)) {
+		:is(.dark, [data-theme="dark"]) [data-background],
+		[data-background]:is(.dark, [data-theme="dark"]) {
+			--nxgt-bg-c1: oklch(
+				from var(--nxgt-bg-t1) max(l, var(--nxgt-bg-floor)) c h
+			);
+			--nxgt-bg-c2: oklch(
+				from var(--nxgt-bg-t2) max(l, var(--nxgt-bg-floor)) c h
+			);
+			--nxgt-bg-c3: oklch(
+				from var(--nxgt-bg-t3) max(l, var(--nxgt-bg-floor)) c h
+			);
+		}
+	}
+
+	/* The decorative layers never take a pointer; the content keeps its own. */
+	[data-background] > [aria-hidden="true"] {
+		pointer-events: none;
+	}
+
+	/* An SVG scene (`data-scene`) and an overlay (`data-overlay`, the grain)
+	 * fill the frame, under the content. The SVG slices to cover it. An
+	 * overlay stays hidden until its own stylesheet shows it (grain.css), so
+	 * without that file it paints nothing. */
+	[data-background] > [data-overlay] {
+		display: none;
+	}
+	[data-background] > :is([data-scene], [data-overlay]) {
+		position: absolute;
+		inset: 0;
+	}
+	[data-background] > :is([data-scene], [data-overlay]) > svg {
+		display: block;
+		width: 100%;
+		height: 100%;
+	}
+
+	[data-background] > [data-slot="background-content"] {
+		display: flex;
+		flex: 1 1 0%;
+		width: 100%;
+		height: 100%;
+		z-index: 5;
+		align-items: center;
+		justify-content: center;
+	}
+
+	/* Paused (hidden page or off screen): the motion rules' `animation`
+	 * shorthands read `--nxgt-bg-play`, so this one declaration stops the
+	 * decoration whatever the specificity. The content does not read it: an
+	 * app's own animations under `background-content` keep running. */
+	[data-background][data-paused] {
+		--nxgt-bg-play: paused;
+	}
+
+	@media (forced-colors: active) {
+		[data-background] {
+			background-image: none;
+		}
+		[data-background] > [aria-hidden="true"] {
+			display: none;
+		}
+	}
+}

package/lib/backgrounds/css/gradient.css

@@ -0,0 +1,53 @@
+/* The `gradient` preset: the frame's tint and three blurred blobs, what
+ * `Background` always looked like (a primary tint from 5% to 20%, blobs
+ * going primary to secondary), now drawn from the tone's colours so it lifts
+ * in dark. The layers are `aria-hidden` divs, see base.css. */
+@layer components {
+	[data-background="gradient"] {
+		background-image: linear-gradient(
+			to right in oklab,
+			color-mix(
+				in oklab,
+				var(--nxgt-bg-c1) calc(5% * var(--nxgt-bg-k)),
+				transparent
+			),
+			color-mix(
+				in oklab,
+				var(--nxgt-bg-c1) calc(20% * var(--nxgt-bg-k)),
+				transparent
+			)
+		);
+	}
+
+	[data-background="gradient"] > [data-layer] {
+		position: absolute;
+		aspect-ratio: 1 / 1;
+		border-radius: 9999px;
+		filter: blur(64px);
+		opacity: var(--nxgt-bg-blob);
+		background-image: linear-gradient(
+			to right in oklab,
+			var(--nxgt-bg-c1),
+			var(--nxgt-bg-c2)
+		);
+	}
+	[data-background="gradient"] > [data-layer="blob-1"] {
+		bottom: 33.333333%;
+		width: 8rem;
+	}
+	[data-background="gradient"] > [data-layer="blob-2"] {
+		right: 0;
+		bottom: 0;
+		width: 8rem;
+		max-width: 28rem;
+	}
+	[data-background="gradient"] > [data-layer="blob-3"] {
+		right: 50%;
+		width: 10rem;
+		background-image: linear-gradient(
+			to right in oklab,
+			color-mix(in oklab, var(--nxgt-bg-c1) 60%, transparent),
+			color-mix(in oklab, var(--nxgt-bg-c2) 60%, transparent)
+		);
+	}
+}

package/lib/backgrounds/css/grain.css

@@ -0,0 +1,19 @@
+/* The grain: film noise over any preset. `Background` draws it as an
+ * `aria-hidden` SVG (an `feTurbulence` filter) with `data-overlay="grain"`
+ * when `grain` is set, or for `preset="grain"`, which is the gradient plus
+ * this overlay. It sits above the preset's layers and under the content; the
+ * intensity scales its opacity. Plain CSS, no inline `style`. The look may
+ * still change. */
+@layer components {
+	[data-background][data-grain] > [data-overlay="grain"] {
+		display: block;
+		opacity: calc(0.16 * var(--nxgt-bg-k));
+		mix-blend-mode: soft-light;
+	}
+
+	@media (forced-colors: active) {
+		[data-background][data-grain] > [data-overlay="grain"] {
+			display: none;
+		}
+	}
+}