@nxgt/material-vue 0.42.0 → 0.43.1

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).

package/docs/guides/csp.md

@@ -101,9 +101,30 @@ On the server, the nonce goes down through `provide`/`inject` only. On the
 client, `NonceProvider` also keeps it for the code that runs outside Vue
 (`claimCspNonce`, once mounted, so never on a server: one request's nonce
 never reaches another's). With nested providers, the innermost one mounted is
-the page's nonce, and it falls back to the outer one's when it unmounts. On
-the client, read the nonce the server wrote into the page and give the root
-the same prop:
+the page's nonce, and it falls back to the outer one's when it unmounts.
+
+On the client, `<NonceProvider>` with no `nonce` prop works: it falls back to
+the nonce the page carries (`getCspNonce()`: the `csp-nonce` meta tag, a
+`<script nonce>`, …), read in `setup`, so it is there from the first render (a
+`<style>` a child creates in its own `onMounted` carries it). A server has no
+page to read and keeps no nonce in a global: it passes the prop, the nonce the
+page carries, so the hydration pass renders what the server did. A server that
+renders without the prop leaves its `<style>` elements blocked: a browser
+checks the policy when it parses them, and a nonce set after hydration does
+not bring them back. A parent `ConfigProvider`'s nonce still wins over the
+page's, and the prop wins over both.
+
+```vue
+<NonceProvider><App /></NonceProvider>
+```
+
+"The page's nonce" here is what `getCspNonce()` returns: first a nonce a mounted
+provider has already claimed, else the `csp-nonce` meta tag or a nonced
+`<script>`/`<style>`. A provider whose own `nonce` goes from a value to
+`undefined` therefore keeps its earlier nonce.
+
+The server always passes the nonce itself. To hand the client the one the
+server wrote, read it from the page and give the root the same prop:
 
 ```ts
 // entry-client.ts
@@ -147,8 +168,8 @@ const Keyframes = () => h('style', { nonce: nonce.value }, props.css);
 
 `useCspNonce()` is a computed ref: `NonceProvider`'s nonce, else the nearest
 reka `ConfigProvider`'s, else `undefined`. It never reads the page in
-`setup`, so the server and the client render the same attribute and
-hydration does not mismatch. Code that runs once mounted (an imperative
+`setup` itself. A `NonceProvider` without a prop does, on the client, which
+is why a server-rendered app passes the prop to the provider on both sides. Code that runs once mounted (an imperative
 widget creating its own `<style>`) can call `getCspNonce()` instead.
 
 ## `<style>` elements the components inject
@@ -200,6 +221,8 @@ Not fixable by configuration yet, and still reported by a strict policy:
 
 ## zod and `'unsafe-eval'`
 
+> **With the Vite plugin** (`nxgtMaterial()` from `@nxgt/material-vue/vite`, the [Vite plugin guide](vite-plugin.md)) the KaTeX and zod steps below are done for you, and so is the Inter step once `@fontsource-variable/inter` is installed (without it the plugin warns and keeps the system font), and the build writes the CSP header (by hash, or with a nonce placeholder). What follows is the route without it.
+
 Building a `z.object()` makes zod probe `new Function` once, to choose
 between its compiled parser and its interpreter. Without `'unsafe-eval'` the
 browser reports a violation. The error is caught, so nothing breaks, but the
@@ -244,6 +267,8 @@ the stand-in is not seen through the factory's schema.
 
 ## KaTeX fonts
 
+> **With the Vite plugin** (`nxgtMaterial()` from `@nxgt/material-vue/vite`, the [Vite plugin guide](vite-plugin.md)) the KaTeX and zod steps below are done for you, and so is the Inter step once `@fontsource-variable/inter` is installed (without it the plugin warns and keeps the system font), and the build writes the CSP header (by hash, or with a nonce placeholder). What follows is the route without it.
+
 `Markdown` renders formulas with KaTeX, which needs its fonts
 (`KaTeX_*.woff2`). They are files on both routes, so `font-src 'self'` allows
 them, and a browser downloads a font only when a formula draws a glyph from
@@ -280,6 +305,8 @@ The library's CI fails when a stylesheet in `dist/` carries a `data:` font.
 
 ## Inter / the sans font
 
+> **With the Vite plugin** (`nxgtMaterial()` from `@nxgt/material-vue/vite`, the [Vite plugin guide](vite-plugin.md)) the KaTeX and zod steps below are done for you, and so is the Inter step once `@fontsource-variable/inter` is installed (without it the plugin warns and keeps the system font), and the build writes the CSP header (by hash, or with a nonce placeholder). What follows is the route without it.
+
 The library ships no web font. Its sans text uses the Tailwind token
 `--font-sans`, which the theme does not set, so it is Tailwind's system stack
 (`ui-sans-serif, system-ui, sans-serif`, then the emoji fonts). Many apps name
@@ -388,14 +415,29 @@ stamps Nuxt's scripts with it), so both render the same tree.
 
 On your own Vite SSR server, generate the nonce in the request handler, put it
 in the header and in every `<script>` and `<style>` you emit, and pass it to
-`NonceProvider` through your root component's props:
+`NonceProvider` through your root component's props. `createCspNonce()` and
+`cspPolicy({ nonce }).header` from `@nxgt/material-vue/lib` make both (they
+use `globalThis.crypto`, so the same code runs on Node, Bun, Deno and
+workers); add your own origins with the `directives` option. Never serve the
+build placeholder `CSP_NONCE_PLACEHOLDER` as a nonce: both helpers refuse it.
+A page that cannot have a per-request nonce (static hosting) allows its inline
+scripts by hash instead: `await cspHash(script)`, then
+`cspPolicy({ hashes: { script: [hash] } })`, whose
+`style-src-elem` is then `'self' 'unsafe-inline'`: the components create
+`<style>` elements at runtime, which have no hash, and a style hash would void
+`'unsafe-inline'` and block them. A nonce is the strict option for styles. For zod without `'unsafe-eval'`,
+put `zodJitlessTag(nonce)` first in the head.
 
 ```ts
 // entry-server.ts
 import { createSSRApp } from 'vue';
 import { renderToString } from 'vue/server-renderer';
+import { createCspNonce, cspPolicy } from '@nxgt/material-vue/lib';
 import App from './App.vue';
 
+// In the request handler:
+//   const nonce = createCspNonce();
+//   response.setHeader('Content-Security-Policy', cspPolicy({ nonce }).header);
 export function render(nonce: string) {
   return renderToString(createSSRApp(App, { nonce }));
 }

package/docs/guides/helpers.md

@@ -18,6 +18,7 @@ differences are listed under each table. React's `/hooks` is
 | --- | --- |
 | `cn(...classes)` | `clsx` + `tailwind-merge`: joins conditional classes, last Tailwind utility wins. |
 | `getCspNonce(doc?)`, `setCspNonce(nonce)` | The page's Content Security Policy nonce, from `@nxgt/material-core/csp-nonce`: `getCspNonce` reads what `setCspNonce` kept, else the `csp-nonce` meta tag, a `<script nonce>` or `<style nonce>`, else `__webpack_nonce__`; `undefined` on a server, where `setCspNonce` does nothing. See [CSP](csp.md#nonceprovider). |
+| `createCspNonce(bytes?)`, `cspPolicy({ nonce, dev, hashes, directives })`, `cspHash(source)`, `applyCspNonce(html, nonce)`, `CSP_NONCE_PLACEHOLDER`, `ZOD_JITLESS_SCRIPT`, `zodJitlessTag(nonce?)` | The server and build side of the CSP, from `@nxgt/material-core/csp` (no DOM; Node, Bun, Deno and workers): a nonce per request, the recommended policy as a `header`, the `'sha256-…'` source of an inline script, the nonce filled into built HTML, zod's jitless script. The public placeholder is refused as a nonce. See [CSP](csp.md#ssr). |
 | `printOnly(element, name?)`, `PRINT_ATTRIBUTE`, `PRINT_TARGET_ATTRIBUTE` | Opens the print dialog for one element of the page instead of the whole page (the marks are removed once printing is over), from `@nxgt/material-core/print-only`; the `@media print` rules are in the package's `styles.css`. See [printing](printing.md#printing-one-element-of-the-page). |
 | `clientOnly(component)` | Wraps a component so it renders nothing on the server and on the first client render, and mounts only after `onMounted`. Pair it with `defineAsyncComponent(() => import(…))`. See [SSR](ssr.md). |
 | `renderSlot(slot, context)`, `ContentSlot<T>` | Resolves a `ContentSlot`: a `VNode`, a string or number, or a `(context) => VNode \| string \| number`. |

package/docs/guides/i18n.md

@@ -310,7 +310,8 @@ names and text, which reka-ui left in English (`material.pagination.first`,
 step announces after its title, "Completed" or "Error"
 (`material.stepper.completed` / `error`, "Terminée" / "Erreur" in French);
 `CommandDialog`'s
-default title and description (`material.command.*`); the carousel's
+default title and description (`material.command.title` / `description`) and
+`CommandList`'s accessible name (`material.command.list`); the carousel's
 `aria-roledescription` (`material.carousel.roledescription` / `slide`); the
 filter's empty state and `+N more` chip (`material.filter.empty` / `more`) and
 the Yes/No, From, Until and Up to of its chips (`material.filter.value.*`;
@@ -455,6 +456,55 @@ reported with `console.warn`, one line per language:
 
 If you see that warning and did not mean it, move your key out of `material`.
 
+### Empty and error states
+
+`EmptyState` reads `material['empty-state'].<kind>.title` and `description` for
+its four kinds, and `ErrorState` reads `material['error-state'].<kind>.title`
+and `description` for its three. The other keys the two components and the
+places that use them read:
+
+| Key | English | French | Read by |
+| --- | --- | --- | --- |
+| `material.empty-state.empty.title` / `description` | No Data Found / There is nothing to display here at the moment. | Aucune donnée / Il n'y a rien à afficher pour le moment. | `EmptyState kind="empty"` |
+| `material.empty-state.search.title` / `description` | No results / Try a different query or clear the filters. | Aucun résultat / Essayez une autre recherche ou retirez les filtres. | `kind="search"` |
+| `material.empty-state.not-found.title` / `description` | Page Not Found / The page you are looking for doesn't exist or has been moved. | Page introuvable / La page que vous recherchez n'existe pas ou a été déplacée. | `kind="not-found"` |
+| `material.empty-state.unauthorized.title` / `description` | Access Denied / You don't have permission to view this content. | Accès refusé / Vous n'avez pas la permission de consulter ce contenu. | `kind="unauthorized"` |
+| `material.error-state.generic.title` / `description` | Something Went Wrong / An unexpected error occurred. Please try again later. | Une erreur est survenue / Une erreur inattendue s'est produite. Veuillez réessayer plus tard. | `ErrorState kind="generic"` |
+| `material.error-state.offline.title` / `description` | You are offline / Check your connection and try again. | Vous êtes hors ligne / Vérifiez votre connexion et réessayez. | `kind="offline"` |
+| `material.error-state.maintenance.title` / `description` | We'll be right back / The service is down for a short update. | On revient tout de suite / Le service est en courte mise à jour. | `kind="maintenance"` |
+| `material.error-state.retry` | Retry | Réessayer | `ErrorState`'s button |
+| `material.error-state.details` | Technical details | Détails techniques | the collapsible summary |
+| `material.error-state.details-name` / `details-message` / `details-cause` | Name / Message / Cause | Nom / Message / Cause | the rows inside it |
+| `material.table.labels.no-data` | No data available | Données non disponibles | `DataTable`'s default for a table with no data |
+| `material.table.labels.no-results` / `no-results-description` | No results / Try a different search or clear the filters. | Aucun résultat / Essayez une autre recherche ou retirez les filtres. | `DataTable`'s default when a filter hides every row, also announced by its status |
+| `material.command.empty` | No results | Aucun résultat | `CommandEmpty` with no children |
+| `material.pdf-reader.retry` | Retry | Réessayer | not read yet: the Vue `PdfReader` has no Retry button (React only for now, [#702](https://github.com/softistx/nxgt-material/issues/702)) |
+
+`material.empty-state.generic.*`, `offline.*` and `maintenance.*` still exist
+for the deprecated `variant`; `ErrorState` does not read them. An app that
+overrode those three for an `EmptyState` error variant copies its overrides to
+`material.error-state.<kind>.title` / `description`:
+
+```ts
+import { mergeResources, resources as materialResources } from '@nxgt/material-vue/i18n';
+
+const appResources = {
+  en: {
+    material: {
+      'error-state': {
+        offline: { title: 'No connection', description: 'Reconnect to continue.' },
+      },
+    },
+  },
+};
+
+export const merged = mergeResources(materialResources, appResources);
+```
+
+Text you pass (`title`, `description`, `retryLabel`) always wins over these keys.
+A `title` of your own drops the default description, so pass a `description`
+to keep a line under it.
+
 ## Zod messages
 
 ```ts

package/docs/guides/migrate-to-vite-plugin.md

@@ -0,0 +1,259 @@
+# Migrating to the Vite plugin
+
+This page is for an app that already sends a strict Content Security Policy
+(CSP) with `@nxgt/material-vue` by hand, and wants `nxgtMaterial()` to do that
+work. It is written as search → replace pairs, so a person or an upgrade agent
+can run each `grep`, change what it finds and check the result. Read the
+[Vite plugin guide](vite-plugin.md) first for what each option does.
+
+Nothing here is breaking: the old exports (`pdfkitStandardFonts`,
+`cspAssetsInlineLimit`, `createCspNonce`, `cspPolicy`, `applyCspNonce`) stay,
+and an app that changes nothing keeps working. Migrate pair by pair.
+
+## Step 0: add the plugin
+
+Search `vite.config.*` for `plugins:`. Add the plugin last, spread (it returns an
+array). Inter needs no install to build: without `@fontsource-variable/inter` the plugin warns once and keeps the system font (pair 4). Nuxt: skip to pair 8; the module calls the plugin for you.
+
+```ts
+// before
+plugins: [vue(), tailwindcss()],
+
+// after
+import { nxgtMaterial } from '@nxgt/material-vue/vite';
+
+plugins: [vue(), tailwindcss(), ...nxgtMaterial()],
+```
+
+```sh
+bun add @fontsource-variable/inter   # optional: to get Inter. Without it the plugin warns and keeps the system font;
+                                     # pass fonts: { sans: false } to keep it silently
+```
+
+**Verify**: `vite build` ends with a log line holding a ready
+`Content-Security-Policy` header, and `dist/.vite/nxgt-csp.json` exists.
+
+## The pairs
+
+| # | Search for | Replace with |
+| --- | --- | --- |
+| 1 | a hand-written static CSP header for a static host | [the generated header](#1-a-hand-written-static-csp-header) |
+| 2 | `randomBytes(16).toString('base64')` plus a hand-written header | [`csp: { mode: 'nonce' }` and the helpers](#2-a-server-nonce-setup) |
+| 3 | `build.assetsInlineLimit: cspAssetsInlineLimit` | [remove it](#3-assetsinlinelimit) |
+| 4 | `@import "@fontsource-variable/inter"` plus `--font-sans` in `@theme` | [remove it, or `fonts: { sans: false }`](#4-the-inter-import) |
+| 5 | a `zod-config.ts` with `z.config({ jitless: true })` | [remove it](#5-zod-configts) |
+| 6 | `pdfkitStandardFonts()` plus `ssr.noExternal: ['@nxgt/material-vue', …]` | [`pdf: { bundle: true }`](#6-pdf-on-a-bundled-server) (Vite SSR server; for Nuxt see pair 8) |
+| 7 | `<NonceProvider :nonce="getCspNonce()">` on the client | [`<NonceProvider>`](#7-nonceprovider-on-the-client) |
+| 8 | Nuxt: a hand-made CSP of your own | [stays with `nuxt-security`](#8-nuxt) |
+
+### 1. A hand-written static CSP header
+
+Search the host configuration (`_headers`, a CDN rule, `nginx.conf`, a
+`<meta http-equiv="Content-Security-Policy">`) for `script-src`. For a
+statically hosted SPA, the old route was a header you wrote yourself, often
+with `'unsafe-inline'` or `'unsafe-eval'` to make zod and Vite's inline code
+run.
+
+```
+# before (_headers)
+/*
+  Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; …
+
+# after: the header the build prints and writes to dist/.vite/nxgt-csp.json
+/*
+  Content-Security-Policy: default-src 'self'; script-src 'self' 'sha256-…'; style-src-elem 'self' 'unsafe-inline'; …
+```
+
+Copy `header` from `dist/.vite/nxgt-csp.json` (or from the build log) into the
+host's configuration. Rebuild, and recopy it: the hashes follow the HTML. To
+extend it (an API origin, say), use `nxgtMaterial({ csp: { policy: { directives: { 'connect-src': ["'self'", 'https://api.example.com'] } } } })`
+and recopy.
+
+**Verify**: open the deployed app with the console open: no `Refused to
+execute inline script` and no `unsafe-eval` report. `nxgt-csp.json` lists
+`scriptHashes` that cover the page's inline `<script>` elements.
+
+### 2. A server nonce setup
+
+Search `randomBytes(`, `crypto.randomUUID()` used as a nonce, `nonce-${`.
+If the app has a server that serves or renders its HTML, pick nonce mode and
+the library helpers (they use `globalThis.crypto`, so Node, Bun, Deno and
+workers alike).
+
+```ts
+// before (server)
+const nonce = randomBytes(16).toString('base64');
+res.setHeader('Content-Security-Policy', `default-src 'self'; script-src 'nonce-${nonce}' 'strict-dynamic'; …`);
+const html = template.replaceAll('__NONCE__', nonce);
+
+// vite.config.ts, after
+nxgtMaterial({ csp: { mode: 'nonce' } })
+
+// server, after
+import { applyCspNonce, createCspNonce, cspPolicy } from '@nxgt/material-vue/lib';
+
+const nonce = createCspNonce();
+const html = applyCspNonce(builtHtml, nonce);
+res.setHeader('Content-Security-Policy', cspPolicy({ nonce }).header);
+```
+
+The built HTML carries the public placeholder `NXGT_CSP_NONCE` (or the one you
+set with `csp.placeholder` / Vite's `html.cspNonce`, which the plugin reuses):
+**never serve it as it is**. `applyCspNonce` and `cspPolicy({ nonce })` throw
+when given the placeholder. The `header` in `nxgt-csp.json` is a template in
+this mode, not something to serve. Keep your own placeholder replacement only
+if you must: then set `csp.placeholder` to its token.
+
+**Verify**: `curl` a page twice: the `nonce="…"` values differ between
+requests, equal the nonce in the response header, and the string
+`NXGT_CSP_NONCE` appears nowhere in the response. No CSP violation in the
+console.
+
+### 3. `assetsInlineLimit`
+
+Search `cspAssetsInlineLimit` and `assetsInlineLimit` in `vite.config.*`. The
+plugin's `fonts.katex` (on by default) keeps every font out of `data:` URIs,
+and composes with a `build.assetsInlineLimit` of your own.
+
+```ts
+// before
+build: { assetsInlineLimit: cspAssetsInlineLimit },
+
+// after (delete the line; keep a limit of your own if you have one)
+```
+
+**Verify**: after `vite build`, `grep -l "data:font" dist/assets/*` finds
+nothing, and the KaTeX `.woff2` files are listed under `dist/assets/`.
+
+### 4. The Inter import
+
+Search the app stylesheet for `@fontsource-variable/inter` and `--font-sans`.
+The plugin imports Inter in the stylesheet that imports
+`@nxgt/material-vue/styles.css` and sets `--font-sans` unlayered, and it skips
+both when it finds your own, so the old lines are optional to remove. Inter needs
+`@fontsource-variable/inter` installed (`bun add @fontsource-variable/inter`):
+without it the plugin warns once and keeps the system font, and the build still
+succeeds. `fonts: { sans: false }` keeps the system font without the warning.
+
+```css
+/* before */
+@import "@fontsource-variable/inter";
+@theme { --font-sans: "Inter Variable", sans-serif; }
+
+/* after: delete both lines (the plugin adds them), or keep them
+   and write nxgtMaterial({ fonts: { sans: false } }) */
+```
+
+A JavaScript `import '@fontsource-variable/inter'` is not detected: keep it only
+with `fonts: { sans: false }`. If you use another font, also pass
+`fonts: { sans: false }`.
+
+**Verify**: the built CSS has `@font-face` rules for `Inter Variable` and
+`:root{--font-sans:…}`, the font files are same-origin, and no `font-src`
+violation shows in the console.
+
+### 5. `zod-config.ts`
+
+Search `z.config({ jitless: true })` and the `import './zod-config'` that
+precedes the app. Remove both: the plugin injects zod's jitless script
+(`ZOD_JITLESS_SCRIPT`) first in `index.html`, and hashes it (hash mode) or
+stamps it with the nonce (nonce mode).
+
+```ts
+// before
+import './zod-config'; // first
+import './app';
+
+// after
+import './app';
+```
+
+Keep the file in an app that renders HTML on its own server with no
+`index.html` (an SSR framework or Nuxt): there, put `zodJitlessTag(nonce)` first in
+the head instead (see [CSP: SSR](csp.md#ssr)).
+
+**Verify**: `grep -c "__zod_globalConfig" dist/index.html` prints at least `1`, the
+script has no `nonce` in hash mode, and the console shows no `unsafe-eval`
+report when a form mounts.
+
+### 6. PDF on a bundled server
+
+Search `pdfkitStandardFonts` and `noExternal` in `vite.config.*`. This is the
+pair for a Vite SSR server that renders `@nxgt/material-vue/pdf` and ships its
+bundle with no `node_modules`.
+
+```ts
+// before
+plugins: [pdfkitStandardFonts()],
+ssr: { noExternal: ['@nxgt/material-vue', '@nxgt/material-core'] },
+
+// after
+plugins: [...nxgtMaterial({ pdf: { bundle: true } })],
+```
+
+Keep an `ssr.noExternal` entry for what the plugin does not walk (your
+app's own dependencies). Your own array is merged, never replaced.
+
+**Verify**: `vite build` for the server, run the server from a folder with no
+`node_modules`, and request a PDF: no `ENOENT … .afm` error.
+
+### 7. `NonceProvider` on the client
+
+Search `getCspNonce()` next to `NonceProvider` in the client entry. On the
+client, a provider without a `nonce` prop reads the nonce the page carries in
+`setup`, from its first render: the one the server passed, so the hydration
+pass renders what the server did. The server keeps passing its request's
+nonce: it has no page to read.
+
+```vue
+<!-- before (client) -->
+<NonceProvider :nonce="getCspNonce()"><RouterView /></NonceProvider>
+
+<!-- after -->
+<NonceProvider><RouterView /></NonceProvider>
+```
+
+Leave the server render as it is. In hash mode there is no nonce at all:
+`<NonceProvider>` renders its children, and the `<style>` elements the
+components create are allowed by the header's `style-src-elem 'self'
+'unsafe-inline'`. Nonce mode is the strict option for styles.
+
+**Verify**: no hydration warning in the console, and a `Select` or a
+`ScrollArea` `<style>` carries the page's nonce in nonce mode.
+
+### 8. Nuxt
+
+The Nuxt module calls `nxgtMaterial()` for you with its own options, and keeps
+the CSP **off**: a Nuxt page is rendered per request, so there is no build-time
+`index.html` to hash or stamp. Pairs 1 and 2 do not apply: keep `nuxt-security`
+for the policy. What does apply:
+
+```ts
+// nuxt.config.ts, before
+export default defineNuxtConfig({
+  nxgtMaterial: { pdf: { bundleStandardFonts: true } },
+});
+
+// after
+export default defineNuxtConfig({
+  nxgtMaterial: { pdf: { bundle: true } },
+});
+```
+
+`pdf.bundleStandardFonts` still works and warns until you rename it. For zod
+(pair 5), keep the `z.config` file or set `nxgtMaterial: { csp: { zodJitless: true } }`,
+which puts the script in every head; `nuxt-security` with `nonce: true`
+stamps it.
+
+**Verify**: `nuxt build` prints no `bundleStandardFonts is deprecated` warning,
+and the server output renders a PDF without `node_modules`.
+
+## Checking the whole migration
+
+1. `vite build` succeeds and prints the header (hash mode), or `nxgt-csp.json`
+   exists (both modes).
+2. Serve the build with that header (or the nonce flow of pair 2).
+3. Open the app and exercise a form, a select and a modal. The console
+   shows no CSP violation.
+4. `git grep -n "zod-config\|cspAssetsInlineLimit\|fontsource-variable/inter"`
+   lists only what you kept on purpose.

package/docs/guides/pdf.md

@@ -281,20 +281,27 @@ artifact, `nitro: { noExternals: true }`), bundle the fonts in:
 // nuxt.config.ts
 export default defineNuxtConfig({
   modules: ['@nxgt/material-vue/nuxt'],
-  nxgtMaterial: { pdf: { bundleStandardFonts: true } },
+  nxgtMaterial: { pdf: { bundle: true } }, // was pdf.bundleStandardFonts
 });
 ```
 
 ```ts
 // vite.config.ts (a Vite SSR server without Nuxt)
-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 } })],
 });
 ```
 
+`pdf: { bundle: true }` adds the standard-fonts transform
+(`pdfkitStandardFonts()`, still exported on its own) and puts the library, core,
+the renderer, pdfkit and the renderer's runtime dependencies into
+`ssr.noExternal`, merged with your own (`react` and your app's own dependencies
+are yours to bundle). It replaces
+the hand-written `plugins: [pdfkitStandardFonts()]` plus `ssr.noExternal` pair
+([Vite plugin guide](vite-plugin.md#rendering-pdfs-on-a-bundled-server)).
+
 `@nxgt/material-core`, which the library's built code imports by name, is
 bundled with it: leave it out and the server fails at boot with
 [`Cannot find package '@nxgt/material-core'`](../troubleshooting.md#cannot-find-package-nxgtmaterial-core).

package/docs/guides/ssr.md

@@ -134,7 +134,7 @@ What to know in a Nuxt app:
 - **A PDF from `@nxgt/material-vue/pdf`** is imported where you use it, like
   the map. `usePdf` renders nothing on the server, and a Nitro route answers
   with `pdfResponse`; a server with no `node_modules` needs
-  `nxgtMaterial: { pdf: { bundleStandardFonts: true } }` ([PDF documents](pdf.md)).
+  `nxgtMaterial: { pdf: { bundle: true } }` ([PDF documents](pdf.md)).
 - **Your own browser-only component**: name it `*.client.vue` (Nuxt then
   leaves it out of the server bundle), or use `clientOnly` +
   `defineAsyncComponent` as in the next section. Wrapping a statically