@nxgt/material-core 0.12.0 → 0.13.1

package/docs/troubleshooting.md

@@ -22,6 +22,23 @@ file) is an example — search for the words around it.
 - [`Could not read <url>: HTTP <status>` (`FilePreviewHttpError`)](#could-not-read-url-http-status-filepreviewhttperror)
 - [`Refused to preview a URL with an unsafe scheme` (`FilePreviewUnsafeUrlError`)](#refused-to-preview-a-url-with-an-unsafe-scheme-filepreviewunsafeurlerror)
 
+**Backgrounds**
+
+- [`Background: preset "<id>" is not available yet; drawing "gradient".`](#background-preset-id-is-not-available-yet-drawing-gradient)
+- [`Unsafe background scene at <path>: <reason>`](#unsafe-background-scene-at-path-reason)
+- [`Unsafe background scene at <path>: url(#<id>) points to no element of the scene`](#unsafe-background-scene-at-path-urlid-points-to-no-element-of-the-scene)
+
+**Content Security Policy**
+
+- [`[nxgt-material] html.cspNonce is set, but the CSP is in hash mode (the default): set nxgtMaterial({ csp: { mode: 'nonce' } }) or drop html.cspNonce.`](#nxgt-material-htmlcspnonce-is-set-but-the-csp-is-in-hash-mode-the-default-set-nxgtmaterial-csp--mode-nonce---or-drop-htmlcspnonce)
+- [`Invalid CSP nonce: only A-Z, a-z, 0-9, "+", "/", "_", "=" and "-" are allowed, got …`](#invalid-csp-nonce-only-a-z-a-z-0-9---_--and---are-allowed-got-)
+- [`The CSP nonce is the build placeholder "NXGT_CSP_NONCE", which is public: …`](#the-csp-nonce-is-the-build-placeholder-nxgt_csp_nonce-which-is-public-)
+- [`Invalid CSP hash "…": expected 'sha256-…', 'sha384-…' or 'sha512-…'`](#invalid-csp-hash--expected-sha256--sha384--or-sha512-)
+- [`Invalid CSP directive name "…": only a-z and "-" are allowed.` and `Invalid CSP source "…" in "…": …`](#invalid-csp-directive-name--only-a-z-and---are-allowed)
+- [`A CSP nonce needs at least 16 random bytes (128 bits), got …`](#a-csp-nonce-needs-at-least-16-random-bytes-128-bits-got-)
+- [`applyCspNonce: the HTML holds no "NXGT_CSP_NONCE" placeholder, so no nonce was applied. …`](#applycspnonce-the-html-holds-no-nxgt_csp_nonce-placeholder-so-no-nonce-was-applied-)
+- [`nxgtMaterial()` fails the build](#nxgtmaterial-fails-the-build)
+
 **Build**
 
 - [`… still references '#standard-fonts/' after the transform — …`](#-still-references-standard-fonts-after-the-transform--)
@@ -157,6 +174,53 @@ safePreviewUrl('javascript:alert(1)'); // null
 const file = safePreviewUrl(url) ?? new Blob([text], { type: 'text/yaml' });
 ```
 
+## Backgrounds
+
+How the engine is used is in the [Backgrounds page](backgrounds.md).
+
+### `Background: preset "<id>" is not available yet; drawing "gradient".`
+
+`resolveShippedPreset` got an id that is not in `SHIPPED_BACKGROUND_PRESETS`: a
+preset that is planned (it is in `BACKGROUND_PRESETS`) but not built yet, or a
+typo from JavaScript. It returns `'gradient'` and prints this once per id,
+except when `NODE_ENV` is `production`. Use a shipped preset:
+
+```ts
+import { SHIPPED_BACKGROUND_PRESETS } from '@nxgt/material-core/backgrounds';
+
+console.log(SHIPPED_BACKGROUND_PRESETS); // ['gradient', 'grain']
+```
+
+### `Unsafe background scene at <path>: <reason>`
+
+`assertSafeScene` found a node a strict CSP could not accept. `<path>` is the
+tags from the root to the node (`svg>defs>filter`). `<reason>` is one of: a tag
+or attribute that is not allowed (`style`, `on*` and `href` never are), a
+number that is not finite, an attribute with markup, an escape or a control
+character, an id or class with unusual characters, an id without the
+`<idPrefix>-` prefix or used twice, a URL in a value, or a `url()` that is not
+a local id. Fix the builder to emit only `SCENE_TAGS` and `SCENE_ATTRIBUTES`:
+
+```ts
+import { assertSafeScene, el, svgIdPrefix } from '@nxgt/material-core/backgrounds';
+
+const prefix = svgIdPrefix('bg');
+assertSafeScene(el('svg', { viewBox: '0 0 10 10' }, []), prefix);
+```
+
+### `Unsafe background scene at <path>: url(#<id>) points to no element of the scene`
+
+A `fill`, `filter`, `mask` or similar attribute references `url(#id)`, but no
+element of the same scene has that `id`. Give the element the id (with the
+`idPrefix`), or drop the reference:
+
+```ts
+// `prefix` is the one from svgIdPrefix, as above
+const id = `${prefix}-fade`;
+el('linearGradient', { id }, []);
+el('rect', { fill: `url(#${id})` }, []);
+```
+
 ## Build
 
 ### `… still references '#standard-fonts/' after the transform — …`
@@ -168,9 +232,10 @@ rather than the server at its first request. Pin the previous
 
 ### `Cannot find module '#standard-fonts/Helvetica' from '…'`
 
-A server bundle that contains pdfkit, run without `node_modules`. Add
-`pdfkitStandardFonts()` to that build (see the README's `/vite` section), or
-keep the library external so pdfkit loads from `node_modules`.
+A server bundle that contains pdfkit, run without `node_modules`. Build it
+with `nxgtMaterial({ pdf: { bundle: true } })` (or add `pdfkitStandardFonts()`;
+see the README's `/vite` section), or keep the library external so pdfkit
+loads from `node_modules`.
 
 ### `Cannot find module '…/pdfkit/js/standard-fonts/Helvetica.cjs'`
 
@@ -233,3 +298,109 @@ import { withNxgtPrint } from '@nxgt/material/next';
 
 export default withNxgtPrint({ output: 'standalone' });
 ```
+
+## Content Security Policy
+
+### `[nxgt-material] html.cspNonce is set, but the CSP is in hash mode (the default): set nxgtMaterial({ csp: { mode: 'nonce' } }) or drop html.cspNonce.`
+
+Thrown by `nxgtMaterial()` (`/vite`) in its default hash mode when the Vite config sets `html.cspNonce`. Drop it, or use `nxgtMaterial({ csp: { mode: 'nonce' } })`, where the plugin sets it. The libraries' [troubleshooting pages](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/troubleshooting.md#nxgt-material-htmlcspnonce-is-set-but-the-csp-is-in-hash-mode-the-default-set-nxgtmaterial-csp--mode-nonce---or-drop-htmlcspnonce) ([Vue](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/troubleshooting.md#nxgt-material-htmlcspnonce-is-set-but-the-csp-is-in-hash-mode-the-default-set-nxgtmaterial-csp--mode-nonce---or-drop-htmlcspnonce)) cover the plugin's other messages.
+
+### `Invalid CSP nonce: only A-Z, a-z, 0-9, "+", "/", "_", "=" and "-" are allowed, got …`
+
+Thrown by `applyCspNonce`, `cspPolicy` and `zodJitlessTag` (`/csp`). The
+nonce holds a character outside the base64 alphabet (a quote, `<`, a space,
+an empty string): written into `nonce="…"` or `'nonce-…'` it would break out
+of the attribute or the header.
+
+Generate it with `createCspNonce()`, or pass the value your framework made
+unchanged (a base64 string):
+
+```ts
+import { createCspNonce, cspPolicy } from '@nxgt/material-core/csp';
+
+const nonce = createCspNonce();
+const { header } = cspPolicy({ nonce });
+```
+
+### `The CSP nonce is the build placeholder "NXGT_CSP_NONCE", which is public: …`
+
+Thrown by `applyCspNonce` and `cspPolicy` when the nonce you pass is
+`CSP_NONCE_PLACEHOLDER`. That string is written in the built HTML to be
+replaced per request; a policy that trusts it trusts anything that can read
+your page, so it is refused.
+
+Replace the placeholder with a fresh nonce for each request, and send the
+same nonce in the header:
+
+```ts
+import { applyCspNonce, createCspNonce, cspPolicy } from '@nxgt/material-core/csp';
+
+const nonce = createCspNonce();
+const page = applyCspNonce(builtHtml, nonce);
+const { header } = cspPolicy({ nonce });
+```
+
+On static hosting, where no request can carry its own nonce, allow the inline
+scripts by hash instead: `cspPolicy({ hashes: { script: [await cspHash(code)] } })`.
+Its `style-src-elem` is then `'self' 'unsafe-inline'`, for the `<style>`
+elements the libraries create at runtime; a nonce is the strict option for
+styles.
+
+### `Invalid CSP hash "…": expected 'sha256-…', 'sha384-…' or 'sha512-…'`
+
+Thrown by `cspPolicy` for an entry of `hashes.script` or `hashes.style` that
+is not a hash source (a nonce, a keyword, a malformed or non-base64 digest).
+Build the entries with `cspHash`:
+
+```ts
+const hash = await cspHash(inlineScriptText);
+cspPolicy({ hashes: { script: [hash] } });
+```
+
+### `Invalid CSP directive name "…": only a-z and "-" are allowed.`
+
+Also `Invalid CSP source "…" in "…": a source holds no ";", ",", whitespace or control character.`
+Thrown by `cspPolicy` for a key or a source of its `directives` option that
+could end the directive and start another (`"a; script-src *"`). One entry of
+the array is one source: split a list into several entries.
+
+```ts
+cspPolicy({ directives: { 'connect-src': ['https://api.example.com', 'wss://live.example.com'] } });
+```
+
+### `A CSP nonce needs at least 16 random bytes (128 bits), got …`
+
+Thrown by `createCspNonce(bytes)` for fewer than 16 bytes, which a guesser
+could try. Call it with no argument (16 bytes) or a larger count.
+
+### `applyCspNonce: the HTML holds no "NXGT_CSP_NONCE" placeholder, so no nonce was applied. …`
+
+Thrown by `applyCspNonce(html, nonce, placeholder?)` when `html` does not
+contain the placeholder. Served as it is, the page's scripts would carry no
+nonce and the policy would block them. Two causes:
+
+- the HTML comes from a hash-mode build (the default of `nxgtMaterial()`),
+  which writes no placeholder: build with
+  `nxgtMaterial({ csp: { mode: 'nonce' } })`, or serve the hash-mode header
+  from `dist/.vite/nxgt-csp.json` without calling `applyCspNonce`;
+- the build set its own `csp.placeholder` (or `html.cspNonce`): pass the same
+  string as the third argument.
+
+```ts
+const page = applyCspNonce(builtHtml, nonce, 'MY_PLACEHOLDER');
+```
+
+### `nxgtMaterial()` fails the build
+
+**When:** `vite build` stops with a message that starts `[nxgt-material]`
+(`stylesheet is never imported`, `Tailwind is not told to scan the package`,
+`@fontsource-variable/inter is not installed`).
+**Why:** `nxgtMaterial()` checks at build time what the library needs, and
+fails with the exact fix when a part is missing. The messages are printed by
+the libraries' plugin: their wording is in the libraries' troubleshooting pages
+([`@nxgt/material`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/troubleshooting.md#content-security-policy), [`@nxgt/material-vue`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/troubleshooting.md#content-security-policy)).
+**Fix:** apply the fix the message prints, or turn the check off:
+
+```ts
+nxgtMaterial({ styles: false, fonts: { sans: false } }, '@nxgt/material');
+```

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@nxgt/material-core",
-	"version": "0.12.0",
-	"description": "The framework-free core of @nxgt/material and @nxgt/material-vue: the PDF document model and its react-pdf renderer, print formatters, PDF file helpers, the PDF viewer's pure modules, the currency digits, the file-size formatter, the field-blur layers, a field's first focusable control, a repeatable row group's focus and announcement rules, the aria-describedby joiner, the inert background of a modal layer, Escape forwarded while an overlay closes, the Toaster's touch-hover guard and its focus hand-back, the page's Content Security Policy nonce, an object built on first use, the zod issue messages, the date range presets, the debounce, accent-insensitive text matching and the race-free async search behind Autocomplete and SearchField, the submit guard, the code error map, an avatar's initials, the two-factor helpers (a grouped TOTP secret, the recovery codes' file, a text download), printing one element of the page, the file preview's kind detection and text reader, the pdfkit fonts Vite plugin, a CSP-safe Vite assetsInlineLimit and the Node-only pdfkit fonts resolution for Next.js and Nuxt builds",
+	"version": "0.13.1",
+	"description": "The framework-free core of @nxgt/material and @nxgt/material-vue: the PDF document model and its react-pdf renderer, print formatters, PDF file helpers, the PDF viewer's pure modules, the currency digits, the file-size formatter, the field-blur layers, a field's first focusable control, a repeatable row group's focus and announcement rules, the aria-describedby joiner, the inert background of a modal layer, Escape forwarded while an overlay closes and kept for a field's open list, the Toaster's touch-hover guard and its focus hand-back, the page's Content Security Policy nonce, the server and build side of the CSP (a nonce per request, the policy header, hashes, zod's jitless script), an object built on first use, the zod issue messages, the date range presets, the debounce, accent-insensitive text matching and the race-free async search behind Autocomplete and SearchField, the submit guard, the code error map, an avatar's initials, the two-factor helpers (a grouped TOTP secret, the recovery codes' file, a text download), the empty and error states' kinds, copy keys, error details and illustration geometry, printing one element of the page, the file preview's kind detection and text reader, the background presets' engine (a seeded generator, scattering, motif shapes, a safe SVG scene format, the activity observer), the pdfkit fonts Vite plugin, the nxgtMaterial() Vite plugin (a strict CSP by hash or nonce, fonts, a styles check), a CSP-safe Vite assetsInlineLimit and the Node-only pdfkit fonts resolution for Next.js and Nuxt builds",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -188,6 +188,11 @@
 			"import": "./dist/lib/text-match.js",
 			"default": "./dist/lib/text-match.js"
 		},
+		"./drawer-room": {
+			"types": "./dist/lib/drawer-room.d.ts",
+			"import": "./dist/lib/drawer-room.js",
+			"default": "./dist/lib/drawer-room.js"
+		},
 		"./async-search": {
 			"types": "./dist/lib/async-search.d.ts",
 			"import": "./dist/lib/async-search.js",
@@ -228,15 +233,31 @@
 			"import": "./dist/vite/index.js",
 			"default": "./dist/vite/index.js"
 		},
+		"./states": {
+			"types": "./dist/states/index.d.ts",
+			"import": "./dist/states/index.js",
+			"default": "./dist/states/index.js"
+		},
+		"./backgrounds": {
+			"types": "./dist/backgrounds/index.d.ts",
+			"import": "./dist/backgrounds/index.js",
+			"default": "./dist/backgrounds/index.js"
+		},
 		"./pdfkit-fonts": {
 			"types": "./dist/pdfkit-fonts/index.d.ts",
 			"import": "./dist/pdfkit-fonts/index.js",
 			"default": "./dist/pdfkit-fonts/index.js"
 		},
+		"./csp": {
+			"types": "./dist/csp/index.d.ts",
+			"import": "./dist/csp/index.js",
+			"default": "./dist/csp/index.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"sideEffects": false,
 	"keywords": [
+		"backgrounds",
 		"pdf",
 		"react-pdf",
 		"print",
@@ -296,20 +317,25 @@
 			"src/lib/initials.ts",
 			"src/lib/text-match.ts",
 			"src/lib/async-search.ts",
+			"src/lib/drawer-room.ts",
 			"src/lib/submit-guard.ts",
 			"src/lib/code-errors.ts",
 			"src/lib/two-factor.ts",
 			"src/lib/print-only.ts",
 			"src/file-preview/index.ts",
 			"src/pdf-viewer/index.ts",
+			"src/backgrounds/index.ts",
 			"src/vite/index.ts",
-			"src/pdfkit-fonts/index.ts"
+			"src/states/index.ts",
+			"src/pdfkit-fonts/index.ts",
+			"src/csp/index.ts"
 		]
 	},
 	"dependencies": {
 		"intl-messageformat": "^11.2.14"
 	},
 	"devDependencies": {
+		"@fontsource-variable/inter": "^5",
 		"@nxgt/material-testing": "0.0.0",
 		"@react-pdf/renderer": "^4.9.0",
 		"@types/bun": "^1.4.2",
@@ -320,11 +346,15 @@
 		"vitest": "^4.1.10"
 	},
 	"peerDependencies": {
+		"@fontsource-variable/inter": ">=5",
 		"@react-pdf/renderer": "^4.9.0",
 		"react": "^18.2.0 || ^19.0.0",
-		"vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+		"vite": "^5.2.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
 	},
 	"peerDependenciesMeta": {
+		"@fontsource-variable/inter": {
+			"optional": true
+		},
 		"@react-pdf/renderer": {
 			"optional": true
 		},