@nxgt/material 2.13.0 → 2.14.0

package/docs/components/primitives.md

@@ -27,6 +27,7 @@ other pages are built from these.
 | <img src="../previews/primitives-toggle.webp" width="96" alt=""> | [Toggle](#toggle) | Pressable on / off button |
 | <img src="../previews/primitives-togglegroup.webp" width="96" alt=""> | [ToggleGroup](#togglegroup) | Single or multiple toggle group |
 | | [Activity](#activity) | React `<Activity>` switched by a boolean |
+| | [NonceProvider](#nonceprovider) | Gives the page's CSP nonce to every component below |
 
 ## Accordion
 
@@ -773,3 +774,33 @@ import { Activity } from '@nxgt/material/components';
 | `visible` | `boolean` | `false` | `true` renders with `mode="visible"`; `false` hides the subtree and keeps its state |
 
 **Storybook:** — · **Vue:** `Activity`
+
+## NonceProvider
+
+No preview: it draws nothing of its own, it hands the page's Content Security
+Policy nonce down.
+
+Gives this request's CSP nonce to every component below it: the `<style>`
+elements of `ScrollArea` and `Select`, the stylesheet tiptap injects for
+`RichTextEditor`, and, on the client, the scroll lock of every modal. Render it once, at the root, on the server and on
+the client, with the same nonce.
+
+```tsx
+import { NonceProvider } from '@nxgt/material/components';
+
+<NonceProvider nonce={nonce}>
+	<App />
+</NonceProvider>;
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `nonce` | `string \| undefined` | — | the nonce of the page's `style-src-elem 'nonce-…'`; `undefined` or `''` inherits the nearest outer `NonceProvider`'s nonce (none at the root) |
+
+`useCspNonce()` (`@nxgt/material/hooks`) reads it in a component of your own;
+`getCspNonce()` and `setCspNonce()` (`@nxgt/material/lib`) read and keep the
+page's nonce outside React. The server entry, the client entry and what each
+component needs are in the [Content Security Policy
+guide](../guides/csp.md#nonceprovider).
+
+**Storybook:** `Primitives/NonceProvider` · **Vue:** `NonceProvider`

package/docs/getting-started.md

@@ -30,7 +30,9 @@ does not import that entry never has them in its tree.
 | `@nxgt/material/print` | `bun add @react-pdf/renderer@^4.9 react-pdf-tailwind` ([printing](guides/printing.md)) |
 | `@nxgt/material/map` | `bun add leaflet react-leaflet @react-leaflet/core @adamscybot/react-leaflet-component-marker react-geolocated` ([maps](guides/maps.md)) |
 
-The tarball contains the built `dist/`, `lib/styles.css`, the component
+The tarball contains the built `dist/` (with KaTeX's fonts in
+`dist/fonts/katex/`, which the compiled stylesheet loads),
+`lib/styles.css`, the component
 stylesheets it imports (`lib/components/**/*.css`), `lib/map/map.css`,
 these docs and `CHANGELOG.md` (from the release after 2.6.1). There is no
 `postinstall` build step.
@@ -45,6 +47,8 @@ In the app's root stylesheet, in this order:
 @source "../node_modules/@nxgt/material/";
 ```
 
+Toaster, Drawer and InputOTP take their CSS from this stylesheet: without it they render unstyled.
+
 - **`styles.css` is source, not compiled CSS.** It holds the Tailwind v4
   `@theme` layer (colours, `--radius`, the `dark` variant, base styles), so it
   runs through *your* Tailwind build. Nothing injects it: import it

package/docs/guides/csp.md

@@ -0,0 +1,408 @@
+# Content Security Policy
+
+This page is for an app that serves a strict Content Security Policy (CSP) and
+wants `@nxgt/material` to run under it: the directives to send, the few
+places the library still needs a relaxation (and which components cause it),
+and the settings that quiet the console. Nothing here is needed on a page
+without a CSP.
+
+## Start from this policy
+
+```http
+Content-Security-Policy:
+  default-src 'self';
+  script-src 'nonce-{NONCE}' 'strict-dynamic';
+  style-src-elem 'self' 'nonce-{NONCE}';
+  style-src-attr 'unsafe-inline';
+  font-src 'self';
+  img-src 'self' data: blob:;
+  worker-src 'self';
+  connect-src 'self';
+  object-src 'none';
+  base-uri 'self'
+```
+
+| Directive | Why |
+| --- | --- |
+| `script-src 'nonce-X' 'strict-dynamic'` | Your entry script carries the nonce; the chunks it loads are trusted through `strict-dynamic`. The library needs no `'unsafe-eval'` once the zod setting below is applied |
+| `style-src-elem 'self' 'nonce-X'` | Your stylesheet and the `<style>` elements that carry the nonce. No component needs `'unsafe-inline'` here, apart from the [known gaps](#known-gaps): see [the `<style>` elements the components inject](#style-elements-the-components-inject) |
+| `style-src-attr 'unsafe-inline'` | The `style="…"` attributes in the server-rendered HTML and those set through `setAttribute('style', …)`. CSP blocks only these two; `el.style.x = …` and `style.setProperty` are not blocked. An attribute cannot carry a nonce, so this is the only way to allow it. It does not allow `<style>` elements or scripts |
+| `font-src 'self'` | The library ships no web font (host Inter yourself: [Inter / the sans font](#inter--the-sans-font)), and KaTeX's fonts are files, never `data:` URIs: see [KaTeX fonts](#katex-fonts) for the one Vite setting the Tailwind route needs |
+| `img-src 'self' data: blob:` | `data:` for the cropper's output, a captured `Camera` photo, a `Markdown` mermaid diagram and the PDF viewer's annotation icons (SVG `data:` images; the icons the components draw are inline `<svg>` elements and need none); `blob:` for previews of a file the user picked. Drop what you do not use |
+| `worker-src 'self'` | The pdf.js worker of `PdfReader` is a same-origin file your bundler emits (Monaco: see below) |
+| `connect-src 'self'` | `PdfReader` fetches the PDF from its `url`: add that origin when it is not yours |
+
+Components outside this table need nothing more. Measured per component:
+
+| Component | Extra directive | Status |
+| --- | --- | --- |
+| `PdfReader`, `PdfSidebar`, `PdfPageList`, `PdfThumbnailSidebar` | `worker-src 'self'` (the worker is a bundled asset), `connect-src` for the PDF's origin | worker URL read from the code; fonts: see [gaps](#known-gaps) |
+| `CodeEditor`, `CodeDiff` (Monaco) | `@monaco-editor/react` loads Monaco from `https://cdn.jsdelivr.net/npm/monaco-editor@…/min/vs` by default: that host in `style-src-elem` (Monaco's CSS) and `font-src` (its icon font), plus `worker-src blob:` | not yet verified in a browser. Safe default: allow `https://cdn.jsdelivr.net` in `script-src`, `style-src-elem` and `font-src`, and `worker-src blob:`; or stay on `'self'` by [serving Monaco yourself](#monaco-on-self) |
+| `Markdown` with a `mermaid` block | mermaid is imported lazily and runs with `securityLevel: 'strict'` | whether mermaid needs `'unsafe-eval'` is not yet verified. Safe default: keep `'unsafe-eval'` out and report any violation you see; its SVG carries a `<style>` element, see [gaps](#known-gaps) |
+| `Camera` | none: `getUserMedia` is not governed by CSP; the captured photo is a `data:` image | `media-src` for the live preview is not yet verified. Safe default: `media-src 'self' blob:` (a `srcObject` stream usually needs nothing) |
+
+### Monaco on `'self'`
+
+Copy Monaco's `min/vs` folder to your public files (for example `/monaco/vs`)
+and point the loader at it, before the first editor mounts:
+
+```ts
+import { loader } from '@monaco-editor/react';
+
+loader.config({ paths: { vs: '/monaco/vs' } });
+```
+
+### Packages the app imports itself
+
+`zod` and `@monaco-editor/react` are dependencies of the library, and
+neither is bundled: the library imports them at runtime. A strict package
+manager (pnpm) does not let the app import a package it does not list, so
+install what you import: `bun add zod @monaco-editor/react`. Keep your zod
+inside `^4.4.3` (zod 4.4 or later shares its configuration through
+`globalThis`) and the app and the library share one copy.
+
+## NonceProvider
+
+Render `NonceProvider` once, at the root, with this request's nonce, on the
+server and on the client. Every component below it takes the nonce: the
+`<style>` elements of `ScrollArea` and `Select`, the stylesheet tiptap
+injects for `RichTextEditor` (its `injectNonce` option, unless you pass your
+own), and, on the client, the scroll lock of every modal.
+
+```tsx
+// app.tsx
+import { NonceProvider } from '@nxgt/material';
+import type { ReactNode } from 'react';
+
+export function App({ nonce, children }: { nonce?: string; children: ReactNode }) {
+  return <NonceProvider nonce={nonce}>{children}</NonceProvider>;
+}
+```
+
+On the server, the nonce goes down through React context only. On the
+client, `NonceProvider` also keeps it for the code that runs outside React
+(`claimCspNonce`, in an insertion effect, 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. The server entry is under [SSR](#ssr). On the
+client, read the nonce the server wrote into the page and render the same
+tree:
+
+```tsx
+// entry.client.tsx
+import { getCspNonce } from '@nxgt/material';
+import { hydrateRoot } from 'react-dom/client';
+import { App } from './app';
+import { Routes } from './routes';
+
+hydrateRoot(document, <App nonce={getCspNonce()}><Routes /></App>);
+```
+
+`getCspNonce()` reads, in order: the value given to `setCspNonce`,
+`<meta property="csp-nonce" nonce="…">` (what Vite's `html.cspNonce` writes)
+or `<meta name="csp-nonce" content="…">`, the first `<script nonce>` or
+`<style nonce>` of the page, then `__webpack_nonce__`. A browser hides a
+`nonce` attribute's value once the page is parsed; `getCspNonce()` reads the
+`nonce` property, which keeps it.
+
+A component of your own that renders a `<style>` takes the nonce with
+`useCspNonce()`:
+
+```tsx
+import { useCspNonce } from '@nxgt/material/hooks';
+
+export function Keyframes({ css }: { css: string }) {
+  return <style nonce={useCspNonce()}>{css}</style>;
+}
+```
+
+`useCspNonce()` returns the provider's nonce, or `undefined` outside one. It
+never reads the page while rendering, so the server and the client render the
+same attribute and hydration does not mismatch. Code that runs in an effect
+(an imperative widget creating its own `<style>`) can call `getCspNonce()`
+instead.
+
+## `<style>` elements the components inject
+
+`style-src-elem 'self' 'nonce-X'` is enough for every component below: your
+stylesheet carries the CSS the dependencies used to inject, and under a
+`NonceProvider` the few `<style>` elements left carry the nonce. No route
+needs `'unsafe-inline'` in `style-src-elem` for them; mermaid and pdf.js's
+font fallback are the [known gaps](#known-gaps).
+
+| Component | What it needs | How |
+| --- | --- | --- |
+| `Toaster` (sonner), `Drawer` (vaul), `InputOTP` (input-otp) | nothing | their CSS is in the stylesheet you import (`styles.css`, or `dist/material.css`); the library build removes the `<style>` they would inject |
+| `ImageCropper` (react-easy-crop) | nothing | its CSS is in the stylesheet; it renders with `disableAutomaticStylesInjection` |
+| `Spinner` (variant `4`), `PdfReader` (search highlights, night mode) | nothing | their rules are in the stylesheet (`spinner.css`, `pdf-viewer.css`) |
+| `ScrollArea`, `Select` (Radix) | the nonce | Radix renders a `<style>` element with `NonceProvider`'s nonce: wrap the app in [`NonceProvider`](#nonceprovider) |
+| `RichTextEditor` (tiptap) | the nonce | tiptap, on mount, with `NonceProvider`'s nonce as `injectNonce` |
+| `Dialog`, `AlertDialog`, `Sheet`, `ConfirmationDialog`, … (Radix scroll lock) | the nonce | react-style-singleton, when a modal opens: see below |
+
+Your app must import the library's stylesheet for the first three rows, as
+the [README](../../README.md) already asks: `@import
+"@nxgt/material/styles.css"` in a Tailwind app, or `dist/material.css`. An
+app that imports only the JavaScript renders toasts and drawers unstyled.
+
+The library's CI checks this on every build: it fails when the built
+JavaScript creates a `<style>`, or calls `insertRule`, `Function` or `eval`,
+outside a short list, each entry with its reason (the scroll lock, tiptap,
+the gaps below). It then imports every built entry and fails if importing
+calls `Function`: a schema built at import would. A story renders a
+`Toaster` with a toast, an open `Drawer` and `Dialog`, an `InputOTP`,
+`Spinner` and `ImageCropper` under this policy and counts the violations:
+none. Another adds `script-src 'self' 'nonce-X'`, no `'unsafe-eval'`, calls
+`z.config({ jitless: true })`, then renders `AttributeForm`, submits it and
+parses with `openingHoursSchema()`: no `script-src` violation.
+
+### Allowed by the check, nothing for you to do
+
+Code that stays in the build and the CSP never sees, or only in a case the
+library avoids:
+
+| Where | What it is | Why it is no violation |
+| --- | --- | --- |
+| `Resizable` (react-resizable-panels) | `insertRule` | on a constructed stylesheet (`adoptedStyleSheets`), which CSP does not govern |
+| `ImageCropper` (react-easy-crop) | `createElement('style')` | the branch is skipped: `disableAutomaticStylesInjection` is passed |
+| Nivo charts (react-virtualized-auto-sizer) | `<style>` of a resize detector | only in a browser without `ResizeObserver`, which no supported browser is |
+| `PdfReader` (pdf.js) | the `isEvalSupported` probe, `new Function("")` | unreachable: `PdfReader` passes `isEvalSupported: false`. If you call `pdfjs.getDocument` yourself, pass it too |
+| lodash (a dependency of some chart code) | `Function("return this")()` | only when neither `global` nor `self` exists: never in a browser |
+| `InputOTP` (input-otp) | a `<style>` inside `<noscript>` | rendered only with scripts off, where no CSP report is sent |
+
+### The scroll lock of modals
+
+Radix locks the page scroll with `react-style-singleton`, which adds a
+`<style>` to `<head>` when a modal opens and takes its nonce from
+`get-nonce`. The library bundles it pointed at its own nonce store
+(`@nxgt/material-core/csp-nonce`), so it reads what `NonceProvider` keeps,
+else what `getCspNonce()` finds in the page (the meta tag, a
+`<script nonce>`). Nothing else to set: the `__webpack_nonce__` assignment
+earlier versions of this guide asked for is no longer needed.
+
+A page without a `NonceProvider` (one that renders no `ScrollArea`, `Select`
+or `RichTextEditor`) needs nothing either, as long as the server writes the
+nonce into the page (the meta tag, or its `<script nonce>`): the scroll lock
+reads it through `getCspNonce()`. Call `setCspNonce(nonce)` on the client only
+when the page carries it nowhere. `setCspNonce` does nothing on a server (no
+`document`), so a request's nonce never lands in a module global there: see
+[SSR](#ssr).
+
+### Known gaps
+
+Not fixable by configuration yet, and still reported by a strict policy:
+
+- the `<style>` element inside mermaid's SVG, and the one cytoscape adds to
+  `<head>` for mermaid's mindmap and architecture diagrams;
+- the font fallback of pdf.js, when a PDF font is not embedded;
+- this repository's Storybook, or an app that imports react-use's barrel
+  itself on a dev server: react-use served as one module, whose `useCss`
+  makes nano-css create three `<style>` elements at import. Our `dist`
+  bundles the hooks it uses and never imports react-use or nano-css, so
+  an app that only uses `@nxgt/material` does not report it.
+
+## zod and `'unsafe-eval'`
+
+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
+report is sent. Switch zod to its interpreter **before the first schema is
+built**, in a module the app imports first:
+
+```ts
+// zod-config.ts
+import { z } from 'zod';
+
+z.config({ jitless: true });
+```
+
+```ts
+// entry.client.tsx
+import './zod-config'; // first
+import './app';
+```
+
+The library builds no schema while it loads, so that is all it takes:
+
+- **zod is not bundled.** `@nxgt/material` imports the zod your app has (a
+  dependency, `^4.4.3`), so your `z.config` is the one its schemas see. zod
+  4.4 or later shares its configuration through `globalThis`, so a
+  second copy of zod 4 that a package manager nested still sees it; that is
+  why the range is `^4.4.3`.
+- **Its schemas are factories**, built on the first call and the same schema
+  after: `openingHoursSchema()`, and the attribute form's, which
+  `AttributeForm` builds when it renders. A component that validates builds
+  its schema when it first renders, never at import.
+
+| Deprecated constant (removed in 3.0) | Use |
+| --- | --- |
+| `OpeningHoursSchema` | `openingHoursSchema()` |
+
+The deprecated constants still work: each is built on its first use and
+behaves as the schema its factory returns (`.parse`, `.safeParse`, `.shape`,
+`.extend`, `instanceof z.ZodObject`). It is not the same object, so do not
+compare it with `===` or register it: a `.meta()` or `registry.add()` on
+the stand-in is not seen through the factory's schema.
+
+## KaTeX fonts
+
+`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
+it: a page with no math downloads none.
+
+- **Compiled route** (`dist/material.css`): the `@font-face` rules point at
+  `dist/fonts/katex/*.woff2`, shipped beside the stylesheet, through a
+  relative `url()`. A bundler emits them as files of your build; an app that
+  serves `dist/` as it is must serve `dist/fonts/` with it. Copy only the
+  stylesheet and math falls back to the system fonts
+  ([troubleshooting](../troubleshooting.md#math-renders-in-the-system-fonts)).
+  Earlier versions inlined the 60 fonts as `data:` URIs (1.4 MB of the
+  stylesheet), and `font-src` needed `data:`.
+- **Tailwind route** (`@import "@nxgt/material/styles.css"`): your bundler emits
+  KaTeX's fonts as files, but Vite inlines any asset under
+  `assetsInlineLimit` (4096 bytes) as a `data:` URI, and
+  `KaTeX_Size3-Regular.woff2` is 3.6 KB, so it is inlined and `font-src 'self'`
+  blocks it. Never inline fonts, with `cspAssetsInlineLimit` from
+  `@nxgt/material/vite` (the same helper as [Inter](#inter--the-sans-font)):
+
+  ```ts
+  // vite.config.ts
+  import { cspAssetsInlineLimit } from '@nxgt/material/vite';
+  import { defineConfig } from 'vite';
+
+  export default defineConfig({ build: { assetsInlineLimit: cspAssetsInlineLimit } });
+  ```
+
+  It returns `false` for a font and leaves every other asset to Vite's
+  default. (`assetsInlineLimit: 0` also works, and inlines nothing at all.)
+  The compiled route through Vite needs the same setting, for the same file.
+
+The library's CI fails when a stylesheet in `dist/` carries a `data:` font.
+
+## Inter / the sans font
+
+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
+Inter there and load it from Google Fonts or rsms.me; both are blocked by
+`font-src 'self'` and `style-src-elem 'self' 'nonce-X'`, because the page then
+asks for another origin's stylesheet and fonts. Host Inter yourself instead:
+
+```sh
+bun add @fontsource-variable/inter
+```
+
+```css
+/* the app's root stylesheet */
+@import "tailwindcss";
+@import "@nxgt/material/styles.css";
+@import "@fontsource-variable/inter";
+@source "../node_modules/@nxgt/material/";
+
+@theme {
+  --font-sans: "Inter Variable", ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+(`@fontsource-variable/inter` is the variable font, family `Inter Variable`.
+For fixed weights install `@fontsource/inter` instead, import
+`@fontsource/inter/400.css` and the weights you use, and name the family
+`"Inter"`.) A JavaScript entry works as well: `import '@fontsource-variable/inter';`.
+
+Set it in the root `@theme`, like the colours: `@theme` entries are resolved
+on the root, so a value set on an inner element does not change what the
+rest of the page inherits. See [theming](theming.md#fonts).
+
+- **Under the policy.** The package's stylesheet is bundled into yours (no
+  second origin, so `style-src-elem 'self'` holds) and its `@font-face` rules
+  point at `.woff2` files that your bundler emits into the build. They load
+  from your own origin, so `font-src 'self'` allows them. A browser downloads
+  only the subsets a page draws: Latin first, the other scripts on demand.
+- **Vite and `assetsInlineLimit`.** Vite inlines an asset under 4096 bytes as
+  a `data:` URI, which `font-src 'self'` blocks. Fontsource's files are
+  larger, so they are emitted as files without any setting. A small subset
+  file can still fall under the limit, and the KaTeX route needs it anyway:
+  keep the one setting that never inlines a font, `cspAssetsInlineLimit`
+  from `@nxgt/material/vite`:
+
+  ```ts
+  // vite.config.ts
+  import { cspAssetsInlineLimit } from '@nxgt/material/vite';
+  import { defineConfig } from 'vite';
+
+  export default defineConfig({ build: { assetsInlineLimit: cspAssetsInlineLimit } });
+  ```
+
+  ([KaTeX fonts](#katex-fonts) uses the same setting.)
+- **If Inter is not loaded.** Nothing breaks and no violation is reported: the
+  browser skips `"Inter Variable"`, which names no installed font, and draws
+  the next entry of the stack, the system sans. Only the look changes. This is
+  also what you get when you keep the token at its default.
+- **Troubleshooting.** A request to `fonts.googleapis.com` or
+  `fonts.gstatic.com` is not ours: see
+  [the font refused for another host](../troubleshooting.md#refused-to-load-the-font-httpsfontsgstaticcom-because-it-violates-the-following-content-security-policy-directive-font-src-self).
+
+## SSR
+
+Generate the nonce **per request**, put it in the header and hand it to the
+renderer. React's stream takes it as an option, and stamps the scripts it
+emits:
+
+```tsx
+// entry.server.tsx
+import { randomBytes } from 'node:crypto';
+import { NonceProvider } from '@nxgt/material';
+import { renderToPipeableStream } from 'react-dom/server';
+import { PassThrough } from 'node:stream';
+import type { ReactNode } from 'react';
+
+export function render(app: ReactNode, respond: (html: PassThrough, csp: string) => void) {
+  const nonce = randomBytes(16).toString('base64');
+  const csp = [
+    `script-src 'nonce-${nonce}' 'strict-dynamic'`,
+    `style-src-elem 'self' 'nonce-${nonce}'`,
+    `style-src-attr 'unsafe-inline'`,
+    `font-src 'self'`,
+  ].join('; ');
+
+  const body = new PassThrough();
+  const { pipe } = renderToPipeableStream(<NonceProvider nonce={nonce}>{app}</NonceProvider>, {
+    nonce,
+    onShellReady() {
+      respond(body, csp);
+      pipe(body);
+    },
+  });
+}
+```
+
+The stream stamps its own scripts with `nonce`; `NonceProvider` hands the same
+value to the components. Also give the nonce to your `<script>` and
+inline-style tags (`<Scripts nonce>` in React Router) and to a
+`meta[name="csp-nonce"]` tag, which `getCspNonce()` reads on the client.
+
+**Never keep the nonce in a module-level variable on the server.** Two
+requests handled at once would overwrite each other, and one page would carry
+the other's nonce. Pass it down the request: as an argument, through
+`NonceProvider` (React context) or `AsyncLocalStorage`. `setCspNonce` is a
+no-op there for that reason.
+
+See also the [SSR guide](ssr.md).
+
+## Status
+
+Nothing is left to ship for the policy. What was done:
+
+- the CSS the dependencies injected at runtime (`Toaster`, `Drawer`,
+  `InputOTP`, `ImageCropper`) and the `<style>` of `Spinner` and `PdfReader`
+  are in the stylesheet;
+- the few `<style>` elements left carry the nonce (`NonceProvider`);
+- KaTeX's fonts ship as files, so `font-src 'self'` needs no `data:`, and
+  Inter is documented as a self-hosted font;
+- zod is an external dependency whose schemas are built on first use (see
+  above).
+
+What remains are the [known gaps](#known-gaps) and the rows marked "not yet
+verified" in the tables above; each is waiting on a dependency, not on this
+library. Progress is on the [roadmap](../roadmap.md). A report you cannot match
+to an entry is in [troubleshooting](../troubleshooting.md#content-security-policy).

package/docs/guides/helpers.md

@@ -14,6 +14,7 @@ differences are listed under each table.
 | --- | --- |
 | `cn(...classes)` | `clsx` + `tailwind-merge`: joins conditional classes, last Tailwind utility wins. |
 | `clientOnly(Component)` | Wraps a component so it renders nothing on the server and mounts only on the client. See [SSR](ssr.md). |
+| `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). |
 | `renderSlot(slot, context)` | Resolves a `ContentSlot`: a `ReactNode` or a `(context) => ReactNode`. |
 | `DATE_UTILS` | `format(iso, 'PP', locale?)` (`'-'` when empty), `parseFromTimestring('HH:mm')`, `parseFromISOString`, `formatDateRangeFilter`. |
 | `formatDateRangeFilter(range)` | Turns a day-picker range into `{ from, to }` ISO strings at start / end of day; `undefined` when empty. |
@@ -119,6 +120,7 @@ Vue: the Redux helpers are Pinia store factories: `defineLocalStore`
 | `useTheme()` | `{ theme, preference, updateTheme }`: light / dark / system, stored in `localStorage`, applied as the `dark` class. See [theming](theming.md#usetheme). |
 | `resolveTheme(stored, prefersDark)`, `applyResolvedTheme(theme)` | The pure theme logic behind `useTheme`, for a boot script. |
 | `useIsClient()` | `false` on the server and first render, `true` after mount: a hydration guard. |
+| `useCspNonce()` | The nonce of the nearest `NonceProvider`, for a `<style>` of your own (`<style nonce={useCspNonce()}>`); `undefined` outside one, on the server and on the client alike. See [CSP](csp.md#nonceprovider). |
 | `useIsMobile()` | `true` below 768 px (`ResponsiveButton` no longer uses it: it collapses with CSS). `false` on the server and while hydrating, so SSR HTML is the desktop layout; a phone switches right after. |
 | `useHeadingSpy(ids, onActive, options?)` | IntersectionObserver over heading ids; reports the topmost visible one. |
 | `useLocalizedDate()` | `{ language, locale, format }`: `DATE_UTILS.format` bound to the `I18nProvider` language (`en` without a provider). |

package/docs/guides/theming.md

@@ -68,6 +68,27 @@ Some colours are derived rather than tokens of their own:
 `bg-primary-container`, `bg-secondary-container`, `bg-accent-container`,
 `bg-error-container`. They follow the token they are computed from.
 
+## Fonts
+
+The library ships no font. Text uses Tailwind's `--font-sans`, which the theme
+does not set, so the default is the system sans stack
+(`ui-sans-serif, system-ui, sans-serif`, then the emoji fonts); there is
+nothing to download. To use Inter, self-host it and set the token in the root
+`@theme`:
+
+```css
+@import "@fontsource-variable/inter";
+
+@theme {
+  --font-sans: "Inter Variable", ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+If Inter is not loaded, the browser draws the next font of the stack. Loading it
+from Google Fonts or rsms.me is blocked by a strict CSP: the install, the
+bundler settings and the policy are in
+[Inter / the sans font](csp.md#inter--the-sans-font).
+
 ## Overriding tokens
 
 Redefine the variables **after** the import, for light and dark separately:
@@ -374,6 +395,12 @@ other bundlers that support package `exports` in CSS. The file is not exported
 under a path of its own, so `import '@nxgt/material/dist/material.css'` does
 not resolve.
 
+The compiled stylesheet loads KaTeX's fonts (`Markdown` maths) from
+`dist/fonts/katex/`, beside it: your bundler emits them as files (Vite inlines the 3.6 KB `KaTeX_Size3` font unless `assetsInlineLimit` is set: see the CSP guide's KaTeX fonts section), and a
+browser fetches one only when a formula needs it. Serving `dist/material.css`
+without `dist/fonts/` makes math fall back to the system fonts
+([troubleshooting](../troubleshooting.md#math-renders-in-the-system-fonts)).
+
 Tokens can be overridden the same way, after the import. What you cannot do
 without Tailwind is use the token utilities (`bg-primary`…) in your own
 markup beyond those the library already uses.

package/docs/roadmap.md

@@ -6,6 +6,21 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Now
 
+- **A strict Content Security Policy** — a page that sends `script-src` with
+  a nonce and no `'unsafe-eval'`, and `style-src-elem` with a nonce and no
+  `'unsafe-inline'`, runs every component with no violation report: a
+  `NonceProvider` forwards the nonce to each component, the CSS the
+  dependencies inject moves into the stylesheet, zod becomes external with
+  schemas built lazily, and the KaTeX fonts ship as files. Done so far:
+  KaTeX's fonts are files beside the compiled stylesheet instead of 1.4 MB of
+  `data:` URIs inside it, so `font-src 'self'` needs no `data:`;
+  `NonceProvider` takes the nonce to `ScrollArea`, `Select`,
+  `RichTextEditor` and the scroll lock of modals; `Toaster`, `Drawer`,
+  `InputOTP`, `ImageCropper`, `Spinner` and `PdfReader` inject no `<style>`,
+  their CSS is in the stylesheet; zod is no longer bundled and no schema is
+  built at import, so the app's `z.config({ jitless: true })` keeps zod from
+  probing `new Function`. Today the
+  [Content Security Policy guide](guides/csp.md) lists what is left to relax.
 - **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
@@ -84,7 +99,8 @@ version they shipped in, and planned entries may name the major they target.
   `ConfirmationDialog` and the attribute editors, so an app without
   react-hook-form never installs it. `ContactItem` and `OpeningHoursItem`,
   deprecated in 2.x, are removed then: use `ContactsFormField` and
-  `OpeningHoursFormField`.
+  `OpeningHoursFormField`. So is the `OpeningHoursSchema` constant: call
+  `openingHoursSchema()`.
   The `Switch` row's misspelt `data-filed` attribute goes too: select
   `[data-checked="true"]` instead. `DateField` / `DateRangeField` stop
   accepting a day rule as `disabled`: pass it as `disabledDays`.