@nxgt/material-vue 0.42.0 → 0.43.0

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

package/docs/guides/theming.md

@@ -40,6 +40,10 @@ build:
   and `[data-theme="dark"]`;
 - a `@theme` block that maps each token to a Tailwind colour, so `bg-primary`,
   `text-error-foreground`, `border-border` are real utilities;
+- the **background presets' base, gradient and motion CSS** (`lib/backgrounds/css/`),
+  which `Background` from `/components` draws with: plain CSS keyed on
+  `data-background`, in `@layer components`, so a utility on the element wins.
+  The other presets are opt-in ([backgrounds](backgrounds.md));
 - a `dark` custom variant, base styles (scrollbars, borders, selection, body
   colours), and a few utilities: `center`, `size-lv`, `col-start-full`,
   `h-fill`, `w-fill`, `size-fill`.
@@ -51,10 +55,12 @@ build:
 | `--background`, `--foreground` | `bg-background`, `text-foreground` | page and text |
 | `--primary`, `--primary-foreground` | `bg-primary`, `text-primary-foreground` | filled buttons, active states, focus |
 | `--secondary`, `--secondary-foreground` | `bg-secondary`, … | the secondary colour |
+| `--tertiary`, `--tertiary-foreground` | `bg-tertiary`, `text-tertiary`, `bg-tertiary-container`, … | the tertiary colour (strix violet) |
 | `--muted`, `--muted-foreground` | `bg-muted`, `text-muted-foreground` | quiet surfaces, hints, placeholders |
 | `--track`, `--track-fill` | `bg-track`, `bg-track-fill`, `border-track-fill` | the empty part of a slider or meter, the drawer handle; the slider range and thumb |
 | `--accent`, `--accent-foreground` | `bg-accent`, … | hover surfaces |
 | `--error`, `--success`, `--info`, `--warning` (+ `-foreground`) | `bg-error`, `text-success`, … | the status colours of `Button`, `Alert`, `Badge`, toasts |
+| `--primary-text` | `text-primary-text` | primary drawn as text or an icon on a page, card or popover surface: `Typography tone="primary"`, links, the `Alert` primary icon, selected labels. Equal to `--primary` in light; in dark, `--primary` mixed 60 % with white (`color-mix(in oklab, var(--primary) 40%, white)`), well over 4.5:1 on `--background` and `--card` |
 | `--error-text` | `text-error-text` | error drawn as text: field messages, `HelperText` in its error state, form and dialog errors, `variant="error"` menu items |
 | `--destructive` | `bg-destructive`, `text-destructive` | deprecated alias of `--error`: the light theme sets it to `var(--error)`, the dark theme keeps its own value; use `--error` |
 | `--card`, `--popover`, `--tooltip` (+ `-foreground`) | `bg-card`, `bg-popover`, `bg-tooltip` | surfaces |
@@ -130,6 +136,26 @@ import { Button } from '@nxgt/material-vue/components';
 </template>
 ```
 
+## Links
+
+`styles.css` styles every bare `<a>` as a link in running text: the info
+colour, an underline on hover and focus, an info tint behind it. Links the
+components render with a look of their own (`Toc`, `SeeAlso`, `Pager`,
+`LinkCard`, `ListTile`, the doc shell's links, `BreadcrumbLink`, `SkipLink`,
+the sidebar entries) opt out of it. Do the same for an anchor of yours that
+has its own look, such as a card, a menu entry or a button-like link: add the
+`nxgt-plain-link` class.
+
+```vue
+<a href="/pricing" class="nxgt-plain-link flex items-center gap-2 rounded p-2 hover:bg-muted">
+  Pricing
+</a>
+```
+
+The class only removes the prose style (colour, underline, tint, pointer);
+the anchor then inherits its text colour like any other element, so style
+the rest yourself. Without the class the anchor keeps the prose style.
+
 ## Contrast and reduced motion
 
 **Contrast.** The shipped light palette keeps the text of every filled status
@@ -139,7 +165,10 @@ colour at 4.5:1 or more (WCAG 1.4.3): `--secondary` 5.7:1, `--success` 5.6:1,
 `--background`, 4.8:1 on its own 15 % `tonal` tint.
 
 The dark theme keeps brighter values, read as text on the dark surfaces: the
-dark `--secondary` (`oklch(0.66 0.1135 245.65)`) is 6.5:1 on `--background`
+dark `--tertiary` (`oklch(0.7 0.15 310.75)`) is 7.0:1 on `--background` and
+6.3:1 on `--card`, with a dark `--tertiary-foreground` that keeps 7.0:1 on
+a filled tertiary surface (light: 7.6:1 under near-white). The dark
+`--secondary` (`oklch(0.66 0.1135 245.65)`) is 6.5:1 on `--background`
 and 5.8:1 on `--card` (a `tonal` secondary `Button` 5.4:1 and 4.6:1). Under
 near-white text those brights are too light, so every filled surface built on
 them is tinted in the dark theme: a filled `secondary` `Button`, `IconButton`
@@ -162,12 +191,12 @@ their text and icon in one tone per colour, read on `--background`, on
 the light theme `primary`, `secondary`, `info` and `success` use the token
 itself (5.8, 4.8, 4.9 and 4.7:1 at their lowest) and `warning` and `error` the
 token mixed with 15 % black (6.4 and 5.4:1). In the dark theme `primary` is
-mixed with 60 % white (8.1:1 on `--card`: the token itself is a dark indigo,
+mixed with 60 % white, the `--primary-text` token (8.1:1 on `--card`: the token itself is a dark indigo,
 2.2:1), `success` and `warning` with 15 % white (5.0 and 6.3:1), `error` with
 30 % white (5.9:1), and `secondary` and `info` use the token (4.6 and 5.3:1).
 The tones are mixed from the tokens (`color-mix(in oklab, var(--color-error)
 85%, black)`), so an override of a token moves its tone with it; a text colour
-of your own on one of those buttons (`class="text-primary"`) replaces the tone
+of your own on one of those buttons (`class="text-primary-text"`) replaces the tone
 and is yours to check.
 
 A `Badge` used as a link (`as-child` around an `<a>`) darkens on hover like a filled
@@ -230,12 +259,31 @@ and `.dark, [data-theme="dark"]` moves it, but setting `--error-text` or
 `--color-error-text` (and `--color-error` for fills) on that element, or put
 the override on the root.
 
+**Primary text has a token of its own**, `--primary-text` (`text-primary-text`),
+for the same reason: the brand colour is a dark fill (it keeps near-white text
+readable on a button) and reads at only about 2:1 as text on the dark surfaces.
+The light value is `var(--primary)`; the dark one is
+`color-mix(in oklab, var(--primary) 40%, white)` (primary mixed 60 % with
+white, the recipe of the tonal `Button` labels). `Typography tone="primary"`,
+the `Alert` primary icon, links, selected labels and the other primary text of
+the catalogue use it.
+
+- **`text-primary-text`** for primary written as text, or an icon beside that
+  text, on a page, card or popover surface.
+- **`text-primary`** (with `bg-primary`, `border-primary`, `ring-primary`) for
+  fills, borders and rings. Text on a primary fill is `text-primary-foreground`.
+
+Like `--error-text`, it is computed where it is declared, on the root: an
+override of `--primary` under `:root` and `.dark, [data-theme="dark"]` moves it
+(override `--primary-text` itself after it to pick another dark colour); below
+the root, set `--color-primary-text` on the element.
+
 Storybook's `Guides/Theming/Contrast` measures all of this in both themes:
 the surfaces' text, the error text (`HelperText` and a field's message on
 `--background` and `--card`), the `Alert`s and the `Timeline`, `Button` and
 `IconButton` in every variant and colour, and a `Badge` link in every colour,
 at rest, hovered, focused and pressed, the tracks and the tabs;
-`Data display/ListTile` measures the selected tile, `Data table, filter & lists/DataTable/On a card` the header, the cells, the links and the selected rows on a page and on a `Card` (also right-to-left), and `Feedback & status/Alert/Tones contrast` the warning, error and success alerts there. Run them against your own
+`Data display/ListTile` measures the selected tile, `Data table, filter & lists/DataTable/On a card` the header, the cells, the links and the selected rows on a page and on a `Card` (also right-to-left), and `Feedback & status/Alert/Tones contrast` every alert tone there, and `Primitives/Typography/Tones contrast` the text tones (primary included). Run them against your own
 tokens after an override.
 
 **Tabs.** An `underline` tab's active label is `--primary` in the light