@nxgt/material-vue 0.42.0 → 0.43.0

package/docs/guides/vite-plugin.md

@@ -0,0 +1,194 @@
+# The Vite plugin: `nxgtMaterial()`
+
+One plugin for the build-time work `@nxgt/material-vue` asks of a Vite app: a strict
+Content Security Policy that needs no hand-written nonce, fonts that survive
+`font-src 'self'`, and a build that fails, with the exact fix, when the
+stylesheet is not wired.
+
+```ts
+// vite.config.ts
+import { nxgtMaterial } from '@nxgt/material-vue/vite';
+import vue from '@vitejs/plugin-vue';
+import tailwindcss from '@tailwindcss/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [vue(), tailwindcss(), ...nxgtMaterial()],
+});
+```
+
+`nxgtMaterial()` returns an array of plugins, hence the spread. Put it last in `plugins` and add no HTML minifier or rewriting plugin after it: a hash covers exact text, and anything that changes the inline scripts later invalidates it.
+
+Every part is on by default and has an opt-out. It needs `vite` 5.2 or later (6, 7, 8; on Vite 5, as under Nuxt 3, every check runs as for the client).
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `csp` | on, `mode: 'hash'` | Puts zod's jitless script in `index.html`, then writes the hash of every inline script and style of the built HTML to `nxgt-csp.json`; the header uses the script hashes. `csp: false` turns it all off |
+| `csp.mode` | `'hash'` | `'hash'`: no placeholder ever lands in the HTML. `'nonce'`: the HTML carries a placeholder your server replaces on every request |
+| `csp.placeholder` | `CSP_NONCE_PLACEHOLDER` | Nonce mode only: your own placeholder (or set Vite's `html.cspNonce`, which the plugin then reuses) |
+| `csp.zodJitless` | `true` | The inline script that switches zod's `new Function` probe off |
+| `csp.dev` | `true` | A `Content-Security-Policy-Report-Only` header on the dev server |
+| `csp.policy` | `{}` | `cspPolicy` options (`directives`, `hashes`) added to the dev and generated headers |
+| `fonts.katex` | `true` | Never inline a font as a `data:` URI (`cspAssetsInlineLimit`), composed with your own `build.assetsInlineLimit` |
+| `fonts.sans` | `'inter'` | Loads self-hosted Inter when `@fontsource-variable/inter` is installed (otherwise warns and keeps the system stack), in your root stylesheet, and sets `--font-sans`; `false` to keep the system stack and silence the warning. `fonts: false` turns both off |
+| `styles.check` | `true` | Fails `vite build` when the library's stylesheet is never imported (`@nxgt/material-vue/styles.css`, or the compiled one through `@import "@nxgt/material-vue";`) |
+| `pdf` | on | pdfkit's standard fonts (`pdfkitStandardFonts()`): a no-op unless pdfkit goes through the bundle. `pdf: false` turns it off |
+| `pdf.bundle` | `false` | Also adds the renderer to `ssr.noExternal`, for a server whose runtime image has no `node_modules` (see [Rendering PDFs on a bundled server](#rendering-pdfs-on-a-bundled-server)) |
+
+## The two CSP modes
+
+### Hash mode (default): safe on a static host
+
+The build computes the sha256 of every inline `<script>` and `<style>` of the
+built `index.html` (zod's jitless script, and anything of yours) and writes:
+
+- `dist/.vite/nxgt-csp.json`: `{ mode, scriptHashes, styleHashes, header }`;
+- a line in the build log with the ready-to-paste header.
+
+```
+Content-Security-Policy: default-src 'self'; script-src 'self' 'sha256-…'; style-src-elem 'self' 'unsafe-inline'; …
+```
+
+Scripts are allowed by hash only. `<style>` elements are allowed by
+`'unsafe-inline'`: the components create some at runtime (`ScrollArea` and
+`Select`, the modals' scroll lock, the rich text editor), which no build can
+hash, and a browser ignores `'unsafe-inline'` as soon as a hash or a nonce is
+in the same directive. So the header carries no style hash; `styleHashes` in
+the JSON is there for a stricter policy you write yourself (it would block
+those runtime `<style>` elements). An inline style runs no code; for a
+`style-src-elem` without `'unsafe-inline'`, use nonce mode.
+
+Send that header from your host (a `_headers` file, a CDN rule, the web
+server). The HTML holds no placeholder and no nonce, so nothing public can be
+mistaken for a secret. Rebuild, and the hashes follow the HTML. A hash covers
+exact text: an inline script a CDN or a tag manager rewrites no longer matches.
+
+### Nonce mode: for an app with a server
+
+```ts
+nxgtMaterial({ csp: { mode: 'nonce' } })
+```
+
+Vite's `html.cspNonce` is set to `NXGT_CSP_NONCE`, so every script, link and
+`meta` of `index.html` carries `nonce="NXGT_CSP_NONCE"`. **That value is
+public: never serve it as it is.** On every request, replace it:
+
+```ts
+import { applyCspNonce, cspPolicy, createCspNonce } from '@nxgt/material-vue/lib';
+
+const nonce = createCspNonce();
+const html = applyCspNonce(builtHtml, nonce);
+res.setHeader('Content-Security-Policy', cspPolicy({ nonce }).header);
+```
+
+`applyCspNonce` and `cspPolicy({ nonce })` throw when given the placeholder as
+the nonce. `nxgt-csp.json` still lists the header, with the placeholder in
+it, as a template to read, not to serve.
+
+Pick nonce mode when a server renders or serves your HTML and can run
+`applyCspNonce`; pick hash mode for a static host. Nonce mode is also the
+strict option for styles: `style-src-elem 'self' 'nonce-…'`, no
+`'unsafe-inline'`.
+
+## The dev server
+
+`csp.dev` sends `Content-Security-Policy-Report-Only` (hash mode: no nonce,
+and the hash of zod's jitless script when `csp.zodJitless` is on; nonce mode:
+the placeholder, as the dev HTML carries it) with `ws:` for HMR.
+Report-Only never blocks, so Vite's own inline scripts are reported and
+that is expected. Vite's dev `<style>` elements (your CSS, injected in dev
+only: `vite build` emits stylesheet files) are allowed by `'unsafe-inline'` in
+hash mode and carry the placeholder in nonce mode.
+
+## Fonts
+
+- **`fonts.katex`**: Vite inlines an asset under 4096 bytes as a `data:` URI,
+  and `font-src 'self'` blocks it (KaTeX's `KaTeX_Size3-Regular.woff2` is
+  3.6 KB). The plugin sets `build.assetsInlineLimit` so a font is always a
+  file. Your own function or number still applies to every other asset.
+- **`fonts.sans: 'inter'`**: in the stylesheet that imports
+  `@nxgt/material-vue/styles.css`, the plugin imports `@fontsource-variable/inter` first
+  and appends an unlayered `:root { --font-sans: "Inter Variable", … }` that
+  beats Tailwind's layered theme variable. Nothing is added when that
+  stylesheet (or a file it imports) already imports Inter or sets
+  `--font-sans` itself. A JavaScript `import '@fontsource-variable/inter'` is
+  not detected: pair it with `fonts: { sans: false }`. The package is an optional peer
+  and Inter loads only when your app has it installed:
+  `bun add @fontsource-variable/inter`. Without it the plugin warns once, in
+  dev and in `vite build`, keeps the system font stack and never fails the
+  build; `fonts: { sans: false }` turns Inter off and silences the warning.
+
+## The styles check
+
+`vite build` (client only; not under Vitest, not for `build.ssr`) fails when
+the library's stylesheet is imported by no stylesheet and no module. Either
+route passes: `@nxgt/material-vue/styles.css` (with Tailwind; it already
+scans the package, so Vue needs no `@source`), or the compiled stylesheet of
+an app without Tailwind, `@import "@nxgt/material-vue";` (the package's
+`style` condition, see [theming](theming.md#without-tailwind)). The error message names the
+exact `@import` line to add.
+
+Opt out with `styles: false` (a Storybook build, for instance, may not import
+it).
+
+## Rendering PDFs on a bundled server
+
+`pdf` is on by default and costs nothing for an app that never renders a PDF:
+the transform only touches modules whose id contains `pdfkit`. Add
+`pdf: { bundle: true }` to a Vite SSR server whose runtime image ships the
+bundle alone:
+
+```ts
+// vite.config.ts (an SSR server)
+export default defineConfig({
+  plugins: [...nxgtMaterial({ pdf: { bundle: true } })],
+});
+```
+
+`bundle: true` puts `@nxgt/material-vue`, `@nxgt/material-core`, `pdfkit`, `@react-pdf/*`
+and every dependency the renderer, pdfkit and core need at runtime (fontkit, yoga, png-js… read
+from your installed packages, so the list follows the renderer's releases) into
+`ssr.noExternal`, merged with your own array; `ssr.noExternal: true` is left as
+it is. What it does not touch is yours to bundle the way you bundle the rest of
+your server: `react` (the renderer's peer) and your app's other dependencies,
+for example `ssr: { noExternal: ['react'] }`. The library's own
+dependencies (a router, charts) are not walked, so a second copy never splits
+their contexts. Under Yarn PnP there is no `node_modules` to read: only the
+fixed names apply, and you list the renderer's dependencies yourself. Without `bundle`, the renderer
+stays external and loads pdfkit's fonts from `node_modules`, as designed. See
+[PDF documents](pdf.md#fonts-on-a-fully-inlined-server).
+
+## Nuxt
+
+The Nuxt module (`@nxgt/material-vue/nuxt`) calls `nxgtMaterial()` for you and
+maps its own options onto it. Under Nuxt:
+
+| Part | What the module does |
+| --- | --- |
+| `csp` | **Off.** Nuxt has no `index.html` for the plugin to hash or stamp, and a header on Vite's dev server never reaches the pages Nitro renders. The module sets no policy and sends no header: use `nuxt-security` for the CSP (its `nonce: true`, or its script hashes for prerendered pages) |
+| `csp.zodJitless` | Opt-in (`nxgtMaterial: { csp: { zodJitless: true } }`): the script goes into `app.head.script` with `tagPriority: 'critical'`. It is inline: `nuxt-security` with `nonce: true` stamps it, otherwise a strict `script-src` blocks it |
+| `fonts.katex` | On: a font is never inlined as a `data:` URI |
+| `fonts.sans: 'inter'` | Opt-in: `@fontsource-variable/inter` and the `--font-sans` override are put first in `nuxt.options.css`. A missing package warns once and keeps the system font; the build never fails |
+| `styles` | **Off** by default: Nuxt resolves `css` entries before Vite sees them. `styles: true` opts in |
+| `pdf` | Nitro owns it, not Vite: `pdf.bundle` adds `pdfkitStandardFonts()` to the Nitro Rollup config (`pdf.bundleStandardFonts` is its deprecated name), and the module always traces pdfkit's font files into `.output/server/node_modules` |
+
+Why hash mode is not used under Nuxt: a Nuxt app is server-rendered, so its
+HTML is built per request, not once at build time. A policy that lists hashes
+of a build-time `index.html` would describe a file that does not exist.
+
+## Other frameworks without an `index.html`
+
+Other SSR frameworks have no `index.html` to transform either: the CSP part
+finds nothing to hash, the build warns once (`no index.html in this build: the
+CSP part did nothing`) and the dev header only fits Vite's own server. On a
+server, send `cspPolicy({ nonce }).header` and `zodJitlessTag(nonce)` per
+request, or pass `csp: false`. The fonts part still works there, since it
+rewrites the stylesheet rather than the HTML.
+
+## Without the plugin
+
+Everything above has a manual route: [CSP guide](csp.md) (KaTeX, Inter, zod,
+SSR).
+
+Migrating an app that wrote its own CSP header, nonce, zod setting or PDF bundling:
+[Migrating to the Vite plugin](migrate-to-vite-plugin.md).

package/docs/roadmap.md

@@ -6,41 +6,15 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Now
 
-- **Empty and error states that look designed** — `EmptyState` and a new
-  `ErrorState` in three sizes (`default`, `compact`, `inline`), with in-house
-  inline SVG illustrations or a slot for your own. `ErrorState` is a
-  `role="alert"` with a Retry action and collapsible technical details. Every
-  built-in empty or error state uses them — the `DataTable` default (your
-  `#empty` slot and `empty` prop still replace it), `PdfReader`, `CommandEmpty`,
-  the gallery, the kanban board, chat and the partials. Ships in
-  `@nxgt/material-vue` 1.0, with the rest of the redesign.
+Nothing is in progress right now.
 
 ## Next
 
-- **One Vite plugin for the whole setup** — `nxgtMaterial()` from
-  `@nxgt/material-vue/vite` is the one call that wires the library
-  into a Vite app; it is implemented once in `@nxgt/material-core/vite`, and
-  `@nxgt/material/vite` is the same plugin.
-  Every option is on by default and each can be turned off or refined; the
-  helpers that exist today stay exported.
-  - `csp`: a nonce placeholder through `html.cspNonce` and
-    `applyCspNonce(html, nonce)` to fill it; zod's jitless mode set by an
-    inline nonced script in `index.html` (`ZOD_JITLESS_SCRIPT` for a server
-    that renders the page itself); and the recommended policy sent by the dev
-    server as Report-Only.
-  - `fonts`: the KaTeX fonts emitted as files, and `sans: 'inter'` for a
-    self-hosted Inter.
-  - `styles`: a build that fails with the exact fix when the stylesheet import
-    or the `@source` line is missing.
-  - `pdf`: pdfkit's standard fonts handled automatically when
-    `@react-pdf/renderer` is installed, and `bundle: true` (the Nuxt module's
-    `pdf.bundleStandardFonts` today) for a server that has no
-    `node_modules`.
-  - Nuxt: the Nuxt module takes the same options.
-  - On the server, `@nxgt/material-core` gains `createCspNonce()` (Web Crypto)
-    and `cspPolicy({ ... })`, which returns `{ directives, header }` as the
-    [Content Security Policy guide](guides/csp.md) describes; `NonceProvider`'s
-    `nonce` becomes optional on the client. Ships as minors.
+- **1.0: `EmptyState` is only about absence** — `variant` is removed, the
+  `generic`, `offline` and `maintenance` kinds leave `EmptyState` for
+  `ErrorState`, and `kind` defaults to `empty` (it is `generic` until then).
+  The upgrade is in
+  [Migrating from `variant`](components/feedback-and-status.md#migrating-from-variant).
 - **One media player, video and audio** — `MediaPlayer`, `MediaPlayerMini`,
   `useMediaPlayer` and `AudioPlayer`, built on the native `<video>` / `<audio>`.
   `StxPlayer` and `VideoPlayer` are removed in `@nxgt/material-vue` 1.0, with a
@@ -94,6 +68,15 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Later
 
+- **`PdfReader` can retry a failed load** — its empty and error blocks become
+  `EmptyState` and `ErrorState` (compact) with a Retry button and the error's
+  details, as in the React reader. Only on the owner's request:
+  softistx/nxgt-material#702.
+- **Vue /backgrounds: more presets and motifs** — the presets and motifs added
+  to React after the base (more gradients, geometric patterns, motif scenes)
+  reach `@nxgt/material-vue/backgrounds` on the owner's explicit ask. Until
+  then a preset id the Vue build lacks draws the gradient (and warns in
+  development). Tracked in softistx/nxgt-material#706.
 - **A CSP without `style-src-attr 'unsafe-inline'`** — the four form controls'
   hidden inputs no longer need it; the checked `Checkbox` indicator,
   `SelectValue`, the `RadioGroup` root, `Slider` and popper positioning still
@@ -167,6 +150,51 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **Empty and error states that look designed** — `EmptyState` with its
+  `kind` (`empty`, `search`, `not-found`, `unauthorized`) and a new
+  `ErrorState` (`generic`, `offline`, `maintenance`), each in two sizes
+  (`default`, `compact`), with in-house inline SVG illustrations or your own in
+  the `#illustration` slot. `ErrorState` is a `role="alert"` with a Retry
+  action and collapsible technical details. The `DataTable` default (your
+  `#empty` slot still replaces it, and `#empty-filtered` covers a filter that
+  hides every row), `CommandEmpty` and the built-in empty states that were
+  hand-rolled (notifications, gallery, quiz, sortable and transfer lists,
+  kanban, chat, charts, contacts, postal address, attributes, opening hours,
+  the player and the event calendar) use them. `variant` still works and is
+  deprecated. 0.43.0.
+  ([EmptyState](components/feedback-and-status.md#emptystate),
+  [ErrorState](components/feedback-and-status.md#errorstate))
+- **Background presets, the base** — `Background` from `@nxgt/material-vue/backgrounds`,
+  a superset of the one in `/components`: `preset` (`gradient` or `grain`),
+  `tone`, `intensity`, `animated` (drifts, and pauses while the page is hidden,
+  the background is off screen or the user prefers reduced motion), `grain`,
+  `seed` and `fill`. The SVG is built from plain data, so the server and the
+  client render the same markup and a strict CSP accepts it. The stylesheets
+  (`backgrounds.css`, `backgrounds/<preset>.css`) are opt-in. The grain's look
+  may still change.
+
+- **One Vite plugin for the whole setup** — `nxgtMaterial()` from
+  `@nxgt/material/vite` and `@nxgt/material-vue/vite` (one implementation in
+  `@nxgt/material-core/vite`) wires the library into a Vite app, each part on
+  by default and each switchable off; the helpers that existed before stay
+  exported ([Vite plugin guide](guides/vite-plugin.md), and the migration guide moves a hand-written setup over). You get:
+  - `csp`: `mode: 'hash'` (default) writes the sha256 of every inline script
+    and style to `dist/.vite/nxgt-csp.json` with the header, or `mode: 'nonce'`
+    leaves a placeholder for `applyCspNonce`; zod's jitless script; a
+    Report-Only header on the dev server. `createCspNonce()`, `cspPolicy()`
+    and `cspHash()` ship in `@nxgt/material-core/csp`.
+  - `fonts`: `katex` (fonts stay files) and `sans: 'inter'` (self-hosted Inter).
+  - `styles`: a build that fails with the exact fix when the stylesheet import
+    or React's `@source` line is missing.
+  - `pdf`: pdfkit's standard fonts handled by the same plugin, with
+    `bundle: true` for an SSR server with no `node_modules`. The Nuxt module
+    calls `nxgtMaterial()` with the same `fonts`, `styles` and `pdf` options
+    (`pdf.bundleStandardFonts` is deprecated for `pdf.bundle`) and adds zod's
+    jitless script to the head on request; its CSP stays `nuxt-security`'s.
+  - `NonceProvider`'s `nonce` is optional on the client (it reads the page's
+    nonce from its first render).
+  Shipped in 0.43.0.
+
 - **The app's brand, a header title and an account menu** — the app shell
   takes the app's `logo` and `name`: the logo alone in the collapsed rail,
   named by the app's name and shown as its tooltip, the logo and the name side