@nxgt/material-core 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @nxgt/material-core
 
+## 0.13.0
+
+### Minor Changes
+
+- [#640](https://github.com/softistx/nxgt-material/pull/640) [`f39e0b7`](https://github.com/softistx/nxgt-material/commit/f39e0b7321c6e753896f48119f354bd316cdd909) Thanks [@SteveGT96](https://github.com/SteveGT96)! - New `@nxgt/material-core/backgrounds` subpath: the engine behind the coming background presets, framework-free and with no DOM at import. It holds the types (`BackgroundPreset`, `BackgroundTone`, `BackgroundIntensity`, `MotifOptions`, `SceneNode`...), the `BACKGROUND_PRESETS` table, a seeded generator (`mulberry32`), `valueNoise2`, `scatter`, the motif shapes (`motifShape`, `place`, `MOTIF_SHAPES`, `MOTIF_DEFAULTS`), a plain SVG scene format with `assertSafeScene` (no `style`, `on*`, `href` or external URL, so it is safe under a strict Content Security Policy), `svgIdPrefix` for ids inside `url(#...)`, and `observeBackgroundActivity`, which pauses an animation when the page is hidden, the element is off screen or the user prefers reduced motion.
+
+- [#690](https://github.com/softistx/nxgt-material/pull/690) [`9b656e8`](https://github.com/softistx/nxgt-material/commit/9b656e80aef7afb299151e9772c7271c0e3fa377) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `@nxgt/material-core/backgrounds` gets its first scene builder: `buildGrain` (also `buildBackgroundScene('grain', ...)`), a film-noise overlay drawn by an `feTurbulence` filter on one rect, safe under `assertSafeScene`, with ids from the `idPrefix` and the `seed` moving the noise. It also exports `SHIPPED_BACKGROUND_PRESETS`, the `ShippedBackgroundPreset` type (`'gradient' | 'grain'`, widened as presets land) and `resolveShippedPreset`, which falls back to `'gradient'` with a one-time warning outside production.
+
+- [#642](https://github.com/softistx/nxgt-material/pull/642) [`2087342`](https://github.com/softistx/nxgt-material/commit/2087342f0b5cd3d987ff0903c0e90e5889c629d4) Thanks [@SteveGT96](https://github.com/SteveGT96)! - New subpath `@nxgt/material-core/csp`, the server and build side of the Content Security Policy (it reads no DOM, so it runs on Node, Bun, Deno, workers and browsers; `/csp-nonce` stays the browser's side). `createCspNonce()` makes a per-request nonce; `cspPolicy({ nonce, dev, hashes, directives })` returns the recommended policy as directives and a `header` (without a nonce, `style-src-elem 'self' 'unsafe-inline'` for the `<style>` elements the libraries create at runtime, unless `hashes.style` is given); `cspHash(source)` gives the `'sha256-…'` source of an inline script or style; `applyCspNonce(html, nonce)` fills the `CSP_NONCE_PLACEHOLDER` a build leaves; `ZOD_JITLESS_SCRIPT` and `zodJitlessTag(nonce)` switch zod's `new Function` probe off from an inline script. `cspPolicy` and `applyCspNonce` throw when given the public placeholder as the nonce, and `applyCspNonce` throws when the HTML holds no placeholder (a hash-mode build, or a custom placeholder not passed as its third argument).
+
+- [#649](https://github.com/softistx/nxgt-material/pull/649) [`0fd651b`](https://github.com/softistx/nxgt-material/commit/0fd651b98403966aee8ecd4059048eabbe8c91f6) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Add `@nxgt/material-core/drawer-room`: `drawerRoom(element, top)`, the height an open floating list may take under `top` inside a Drawer without covering its footer (`null` outside a Drawer). `Autocomplete` uses it in both libraries ([#582](https://github.com/softistx/nxgt-material/issues/582)).
+
+- [#687](https://github.com/softistx/nxgt-material/pull/687) [`970cf63`](https://github.com/softistx/nxgt-material/commit/970cf63a763be215c4d27cca58a5698d915d6f46) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `nxgtMaterial()` in `@nxgt/material-core/vite` takes a `pdf` option. It is on by default and adds `pdfkitStandardFonts()` (a no-op unless pdfkit goes through the bundle). `pdf: { bundle: true }` also adds the library, `@nxgt/material-core`, `pdfkit`, `@react-pdf/*` and every package the renderer, pdfkit and core need at runtime (their transitive dependencies, read from your installed packages) to `ssr.noExternal` (merged with yours; `noExternal: true` is left alone), for an SSR server whose runtime image has no `node_modules`. `pdf: false` turns it off.
+
+- [#651](https://github.com/softistx/nxgt-material/pull/651) [`0da112a`](https://github.com/softistx/nxgt-material/commit/0da112a9353e4bf369a58a8ef62e5ff3b9238f6a) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `@nxgt/material-core/vite` gains `nxgtMaterial(options, library?)`, one Vite plugin for the build-time work of a strict Content Security Policy. Default `csp.mode: 'hash'`: zod's jitless script is injected into `index.html`, the sha256 of every inline script and style is written to `dist/.vite/nxgt-csp.json` (`scriptHashes`, `styleHashes`, `header`) and the header logged at the end of the build: scripts by hash, `style-src-elem 'self' 'unsafe-inline'` with no style hash (the components create `<style>` elements at runtime, and a hash would void `'unsafe-inline'`; nonce mode is the strict option for styles), and no placeholder ever lands in the HTML. `csp: { mode: 'nonce' }` opts into Vite's `html.cspNonce` placeholder for a server that calls `applyCspNonce` per request. It also keeps fonts out of `data:` URIs (composing your `build.assetsInlineLimit`), loads self-hosted Inter and sets `--font-sans` only when the optional peer `@fontsource-variable/inter` is installed (otherwise one warning, in dev and in build, and the system font stays; the build never fails), sends a Report-Only header on the dev server (in hash mode it carries the jitless script's hash), and, given a library name, fails `vite build` with the exact line to add when the stylesheet is missing (neither `styles.css` nor the compiled stylesheet through `@import "<library>";`) or the React `@source` is (`styles.css` only). On Vite 5, which has no build environments, every check runs as for the client. `/vite` now reads stylesheets and installed `package.json` files with `node:fs/promises`, `node:fs` and `node:path` (build-time code, like `/pdfkit-fonts`); it also re-exports `CSP_NONCE_PLACEHOLDER` and `ZOD_JITLESS_SCRIPT`.
+
+- [#639](https://github.com/softistx/nxgt-material/pull/639) [`009f7af`](https://github.com/softistx/nxgt-material/commit/009f7afaf99d44cdc960f9666cdb546fd4fc13f7) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `@nxgt/material-core/states`: the kinds of `EmptyState` and `ErrorState` (`EMPTY_STATE_KINDS`, `ERROR_STATE_KINDS`, `resolveEmptyStateKind`, `isErrorKind`), their i18n keys and English fallbacks (`stateCopy`, `STATE_ACTION_KEYS`), `describeError` (an error's name, message and cause chain, never its stack) and the geometry of the illustrations (`STATE_ILLUSTRATIONS`, `STATE_ACCENT`, `STATE_ICON`).
+  
+  `@nxgt/material` and `@nxgt/material-vue` ship new i18n keys in `en` and `fr`, for the components that follow: `material.error-state.*` (`generic`, `offline` and `maintenance` with a title and a description, `retry`, `details`, `details-name`, `details-message`, `details-cause`), `material.table.labels.no-results` and `no-results-description`, `material.command.empty` and `material.pdf-reader.retry`.
+
+- [#647](https://github.com/softistx/nxgt-material/pull/647) [`0f88cbd`](https://github.com/softistx/nxgt-material/commit/0f88cbdd0ee2045901d568df2eb769196acaf73b) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Escape closes only an open `ComboboxField`, `Combobox` or `Autocomplete` list inside a `Dialog`, `Sheet`, `Drawer`, `AlertDialog` or `Popover`; a second Escape closes the layer ([#631](https://github.com/softistx/nxgt-material/issues/631)). Before, the first Escape closed the whole layer. A `Select` list has always taken the first Escape, as a layer of its own, and is unchanged. The layer's own `onEscapeKeyDown` (`@escape-key-down`) now sees `defaultPrevented` true for an Escape that only closes a list. `@nxgt/material-core/escape-forward` gains `keepListEscape(event)` for your own overlay.
+
+- [#679](https://github.com/softistx/nxgt-material/pull/679) [`c17e6c2`](https://github.com/softistx/nxgt-material/commit/c17e6c235e471990a3315c03a463bfd0c3d0b3e8) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `PdfReader`: a scroll with no input the reader hears (find in page, a screen reader's cursor, setting `scrollTop`) that lands just after the opening page's pin corrects the view is reported once the scroll spy's hold ends, and the pin lets go; before, the page number stayed on the opening page and the next correction scrolled back to it. Fixes [#677](https://github.com/softistx/nxgt-material/issues/677). `@nxgt/material-core/pdf-viewer`'s `createScrollSpy` takes an options object as its fourth argument, `{ idleMs?, readerPosition? }` (a bare number is still `idleMs`): two frames after a hold ends, a scroll it held is measured once when `readerPosition` says the view is no longer where the reader put it; input in the page area during a hold measures a scroll it held. `pageInView(scroller, pages)`, the page most on screen, is exported.
+
+### Patch Changes
+
+- [#708](https://github.com/softistx/nxgt-material/pull/708) [`4c5658b`](https://github.com/softistx/nxgt-material/commit/4c5658bba08aac0d5b0224683f9374a1411296ba) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Docs: the getting-started `/backgrounds` rows describe what ships, the roadmaps list the base as shipped and the remaining presets as next, and the troubleshooting pages explain the development warning for a preset that is not available yet, a grain that looks bare without `backgrounds.css`, and (in core) `assertSafeScene`'s errors.
+
+- [#691](https://github.com/softistx/nxgt-material/pull/691) [`8feb417`](https://github.com/softistx/nxgt-material/commit/8feb41728fc4d4f9ce3ad4be7c78fd4ddd7b5b67) Thanks [@SteveGT96](https://github.com/SteveGT96)! - The README links the libraries' new "Migrating to the Vite plugin" guide, which moves a hand-written CSP, zod, font and PDF setup to `nxgtMaterial()`.
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -6,20 +6,20 @@ The framework-free core that [`@nxgt/material`](https://www.npmjs.com/package/@n
 the print formatters, the PDF file helpers, the PDF viewer's framework-free
 half (page geometry, scroll spy, text search), the currency field's decimals,
 the file-size formatter, the slider's tick marks, the emoji list's groups,
-the date range presets, a debounce, accent-insensitive text matching and a race-free async search (`/debounce`, `/text-match`, `/async-search`), the file preview's kind detection, the fields' blur
+the date range presets, a debounce, accent-insensitive text matching and a race-free async search (`/debounce`, `/text-match`, `/async-search`), the room an open list has above a Drawer's footer (`/drawer-room`), the file preview's kind detection, the fields' blur
 rule, a field's first reachable control (`/focus-control`) and its `aria-describedby`
 (`/described-by`), where the focus goes in a repeatable row group
 (`/repeatable-group`), the page behind a modal layer made inert
-(`/inert-others`), Escape pressed while an overlay closes
-(`/escape-forward`), the Toaster's guard against a tap's emulated hover
+(`/inert-others`), Escape pressed while an overlay closes or in a field whose
+list is open (`/escape-forward`), the Toaster's guard against a tap's emulated hover
 (`/touch-hover`), the focus a toast's action hands back (`/toast-focus`), a
 table row's activation, the zod error map's issue messages
 (`/zod-issue-messages`), a zod error map that words an issue by its code
-(`/code-errors`), the page's Content Security Policy nonce (`/csp-nonce`), an
+(`/code-errors`), the page's Content Security Policy nonce (`/csp-nonce`), the server and build side of the CSP (`/csp`), an
 object built on its first use (`/lazy-object`), one submit in flight
 (`/submit-guard`), the two-step verification helpers (`/two-factor`: a TOTP
 secret grouped to be typed, the recovery codes' text file, a text download),
-printing one element of the page (`/print-only`), the Vite plugin that
+the empty and error states' kinds, copy keys, error details and illustrations (`/states`), printing one element of the page (`/print-only`), the engine behind the background presets (`/backgrounds`), the Vite plugin that
 bundles pdfkit's standard fonts and a `build.assetsInlineLimit` that keeps
 fonts out of `data:` URIs, and the Node-only resolution of those fonts that
 the Next.js helper and the Nuxt module run at build time.
@@ -30,7 +30,7 @@ re-export what they always exported, at the same subpaths:
 from here, and so do their `PdfReader`, `CurrencyField`, form fields (their
 focus, blur, `aria-describedby` and zod messages), file list and upload
 field (`formatFileSize`), modal layers (the inert page behind, Escape while
-closing), `Toaster`, `DataTable` rows, `@nxgt/material/next` and
+closing, Escape in a field whose list is open), `Toaster`, `DataTable` rows, `@nxgt/material/next` and
 `@nxgt/material-vue/nuxt`. Import it directly when you want the model or a
 formatter without a UI library, or one of these helpers in a component of
 your own.
@@ -60,13 +60,15 @@ files are plain ES modules and also load in Node without a bundler.
 | Optional peer | Needed by |
 | --- | --- |
 | `react`, `@react-pdf/renderer@^4.9` | `@nxgt/material-core/pdf/render` and `/pdf` — rendering a document |
-| `vite@^6 \|\| ^7 \|\| ^8` | `@nxgt/material-core/vite` — its declarations name Vite's `Plugin` type (types only); the plugin itself runs in your Vite config |
+| `vite@^5.2 \|\| ^6 \|\| ^7 \|\| ^8` | `@nxgt/material-core/vite` — its declarations name Vite's `Plugin` type (types only); the plugin itself runs in your Vite config |
+| `@fontsource-variable/inter@>=5` | `@nxgt/material-core/vite` — `nxgtMaterial()` loads Inter only when it is installed, else warns and keeps the system font; `fonts: { sans: false }` silences the warning |
 
 Every other subpath imports none of them, and is safe to import on a server
-with no DOM. One subpath is **Node only**: `/pdfkit-fonts` imports `node:module`
-and `node:path`, for a framework's config at build time — never import it
-from code a browser bundle can reach. No other subpath imports a `node:`
-built-in.
+with no DOM. Two subpaths are **Node only**: `/pdfkit-fonts` imports `node:module`
+and `node:path`, and `/vite` imports `node:fs/promises`, `node:fs` and `node:path`
+(the styles check reads stylesheets from disk; `pdf: { bundle: true }` reads installed `package.json` files), both for a framework's or a
+Vite config at build time — never import them from code a browser bundle
+can reach. No other subpath imports a `node:` built-in.
 
 ## Subpaths
 
@@ -85,14 +87,15 @@ built-in.
 | `/pdf-source` | `PdfSource` and its helpers (`toPdfjsSource`, `pdfSourceKey`, …) |
 | `/pdf-file-name` | `resolvePdfFileName`, `DEFAULT_PDF_FILE_NAME` |
 | `/pdf-download` | `downloadPdfFile`, `printPdfFile` — in a browser |
-| `/pdf-viewer` | The PDF viewer's pure half: page geometry and fit (`readerFitScale`, `placeholderSize`, `rotatedSize`, `PdfPageSize`, `FitMode`), page sizes (`readPageSizes`, `createPageSizesLoader`), the scroll spy (`createScrollSpy`, `revealHit`, `scrollIntoArea`), the opening page's pin (`pinToPage`, whose optional `onRelease` runs once when it lets go, and `pinHolds`, whether the view is still where it puts the page), text search (`pageTextFromItems`, `findTextMatches`, `searchDocument`), `escapeHtml`, `mapPdfOutline` |
+| `/pdf-viewer` | The PDF viewer's pure half: page geometry and fit (`readerFitScale`, `placeholderSize`, `rotatedSize`, `PdfPageSize`, `FitMode`), page sizes (`readPageSizes`, `createPageSizesLoader`), the scroll spy (`createScrollSpy` and its `ScrollSpyOptions`, `pageInView`, `revealHit`, `scrollIntoArea`), the opening page's pin (`pinToPage`, whose optional `onRelease` runs once when it lets go, and `pinHolds`, whether the view is still where it puts the page), text search (`pageTextFromItems`, `findTextMatches`, `searchDocument`), `escapeHtml`, `mapPdfOutline` |
 | `/currency-digits` | `currencyFractionDigits` — the decimals `CurrencyField` shows |
 | `/field-blur-layers` | `layerOf`, `openerOf`, `FieldLayers` — whose overlay a layer of the page is, for a field's blur |
 | `/focus-control` | `firstControl`, `focusHandle`, `FocusHandle` — the first control of a field a user can reach, and a stand-in element that focuses it for a form library |
 | `/repeatable-group` | `focusAfterRemove`, `focusAfterMove`, `focusRowTarget`, `rowMoveTarget`, `canAddRow`, `canRemoveRow`, `RowFocusTarget`, `RowMoveDirection`, `RowAnnouncement`, `ROW_SLOT`, `ROW_FIELDS_SLOT`, `ADD_ATTRIBUTE` — where the focus goes after a row of a `RepeatableGroup` is added, removed or moved, and what its live region says |
-| `/escape-forward` | `forwardEscape` — Escape pressed while an overlay closes, pressed again for the overlay below once it has gone |
+| `/escape-forward` | `forwardEscape`, `keepListEscape` — Escape pressed while an overlay closes, pressed again for the overlay below once it has gone; Escape pressed in a field whose list is open, kept from closing the overlay around it |
 | `/described-by` | `describedBy` — an `aria-describedby` value from the caller's ids and a field's help and error ids |
 | `/inert-others` | `inertOthers`, `INERT_MARKER` — the rest of the page `inert` behind a modal layer, live regions kept, nested layers counted |
+| `/backgrounds` | `buildBackgroundScene`, `buildGrain`, `assertSafeScene`, `svgIdPrefix`, `observeBackgroundActivity`, `mulberry32`, `valueNoise2`, `scatter`, `motifShape`, `place`, `BACKGROUND_PRESETS`, `SHIPPED_BACKGROUND_PRESETS`, `resolveShippedPreset`, `BACKGROUND_TONES`, `MOTIF_SHAPES`, `MOTIF_DEFAULTS` and the types `BackgroundPreset`, `ShippedBackgroundPreset`, `BackgroundTone`, `BackgroundIntensity`, `MotifOptions`, `SceneNode`, `PresetInfo` — the engine behind the libraries' background presets: a seeded generator, scattering, motif shapes, a plain SVG scene format with its safety check, ids for `url(#…)`, and the observer that pauses an animation |
 | `/touch-hover` | `ignoreTouchHover`, `TOASTER_PHONE_QUERY`, `TOASTER_PHONE_POSITION` — keeps a tap from hovering an element, so a toast a finger touched does not stay paused; where the `Toaster` puts toasts on a phone |
 | `/toast-focus` | `focusOrigin`, `handFocusBack`, `trackToasterOrigin`, `TOASTER_SELECTOR` — where the focus was before it entered a toast, and handing it back there before the toast's action runs, so a dialog the action opens keeps the focus |
 | `/zod-issue-messages` | `sizeMessage`, `invalidFormatMessage`, `IssueText` — the translated text of a zod `too_big` / `too_small` and `invalid_format` issue |
@@ -102,17 +105,20 @@ built-in.
 | `/emoji-groups` | `groupKey`, `groupEmojis`, `searchEmojis`, `groupName`, `GROUP_NAMES` and the type `EmojiItem` — how the emoji list groups, searches and names its emojis |
 | `/date-range` | `DATE_RANGE_PRESET_IDS`, `presetRange`, `resolvePresetRange`, `isSameDayRange`, `isRangeDisabled`, `withTimeOf`, `endOfDayTime`, `clampRangeEnd`, `keepRangeTimes` and the types `DayRange`, `PartialDayRange`, `DateRangePreset`, `DateRangePresetId`, `DateRangePresetOption`, `DateRangeRules` — `DateRangeField`'s presets and times |
 | `/csp-nonce` | `getCspNonce`, `setCspNonce`, `claimCspNonce(nonce, depth)`, `createNoncedStyle`, and `getNonce` / `setNonce` (the `get-nonce` API) — the page's Content Security Policy nonce, for a `<style>` created at runtime; browser only |
+| `/csp` | `createCspNonce`, `cspPolicy`, `cspHash`, `applyCspNonce`, `CSP_NONCE_PLACEHOLDER`, `ZOD_JITLESS_SCRIPT`, `zodJitlessTag` and the types `CspPolicyOptions`, `CspDirectives` — the Content Security Policy for a server or a build: a nonce per request, the recommended header, hashes of inline code, zod's jitless switch; no DOM |
 | `/lazy-object` | `lazyObject`, `buildOnce` — a value built on its first use rather than when its module loads: the libraries' zod schemas |
 | `/debounce` | `debounce`, the type `Debounced` — a function called once calls pause, with `cancel` and `flush` (`SearchField`'s `debounceMs`) |
 | `/initials` | `initials` — an avatar's initials from a name, `'Ada Lovelace'` → `'AL'` (`AccountMenu`) |
 | `/text-match` | `foldText`, `matchesText` — case- and accent-insensitive matching (`'e'` finds "École"), lowercased for a locale |
 | `/async-search` | `createAsyncSearch`, `searchAnnouncement`, `DEFAULT_SEARCH_DEBOUNCE_MS`, `DEFAULT_MIN_QUERY_LENGTH` and the types `AsyncSearch`, `AsyncSearchConfig`, `AsyncSearchState`, `AsyncSearchStatus`, `SearchFn`, `SearchContext`, `SearchAnnouncement` — `Autocomplete`'s server search: debounced, each run aborting the last, a stale response dropped |
+| `/drawer-room` | `drawerRoom(element, top)` — the height in px an open floating list may take under `top` inside a Drawer without covering its footer (at least 80, an 8px gap kept); `null` outside a Drawer (`Autocomplete`) |
 | `/submit-guard` | `createSubmitGuard`, `busySettler` and the types `SubmitGuard`, `SubmitOnceOptions` — one submit in flight until its request ends, behind both libraries' `useSubmitOnce` |
 | `/code-errors` | `createCodeErrorMap`, `defaultCodeOf`, `isEmptyRequired` and the types `CodeErrorMap`, `CodeErrorMapOptions`, `CodeIssue` — a zod 4 error map that words an issue by the code it carries (a refinement's `params.code`), behind both libraries' `useCodeResolver` |
 | `/two-factor` | `groupSecret`, `recoveryCodesText`, `downloadText` and the types `RecoveryCodesTextOptions`, `DownloadTextOptions` — a TOTP secret in groups of four, the recovery codes as a text file, and saving a text file, behind both libraries' `EnrolmentSecret` and `RecoveryCodes` |
 | `/print-only` | `printOnly`, `PRINT_ATTRIBUTE`, `PRINT_TARGET_ATTRIBUTE` — printing one element of the page with no inline style, behind `RecoveryCodes`' Print button; re-exported by both libraries' `/lib` |
 | `/file-preview` | `fileKind`, `describeFile`, `safePreviewUrl`, `readTextPreview`, `FilePreviewHttpError`, `FilePreviewUnsafeUrlError`, `TEXT_PREVIEW_MAX_BYTES`, `fileExtension`, `fileNameFromUrl`, `dataUrlType`, `kindOfMimeType`, `normaliseMimeType`, `isTextFileKind`, `TEXT_FILE_KINDS` and the types `FileKind`, `FileKindInput`, `DescribedFile`, `FilePreviewSource`, `TextPreview` — `FilePreview`'s kind detection, URL allow-list and text reader |
-| `/vite` | `pdfkitStandardFonts()`, `cspAssetsInlineLimit` — see below |
+| `/states` | `EMPTY_STATE_KINDS`, `ERROR_STATE_KINDS`, `resolveEmptyStateKind`, `isErrorKind`, `stateCopy`, `STATE_ACTION_KEYS`, `describeError`, `STATE_ILLUSTRATIONS`, `STATE_ACCENT`, `STATE_ICON` and the types `EmptyStateKind`, `ErrorStateKind`, `StateKind`, `LegacyEmptyStateVariant`, `StateFamily`, `StateCopy`, `ErrorDetail`, `StateIllustration`, `IllustrationShape`, `IllustrationTone`, `StateAccent`, `StateIconName` — the kinds, copy keys, error details and illustrations behind `EmptyState` and `ErrorState` |
+| `/vite` | `nxgtMaterial()`, `pdfkitStandardFonts()`, `cspAssetsInlineLimit`, `CSP_NONCE_PLACEHOLDER`, `ZOD_JITLESS_SCRIPT` and the types `NxgtMaterialOptions`, `NxgtMaterialCspOptions`, `NxgtMaterialLibrary` — see below |
 | `/pdfkit-fonts` | **Node only.** `pdfkitStandardFontDirs`, `pdfkitStandardFontFiles`, `PDFKIT_STANDARD_FONTS`, the types `PdfkitStandardFont` and `PdfkitFontsWarn` — where the app's pdfkit keeps its standard fonts, for a server tracer |
 
 ## Usage
@@ -328,13 +334,30 @@ server). `pinHolds(node)` tells whether the view still shows `node` where the
 pin puts it: at the top, or as near as the area can scroll at its end. A
 scroll that leaves it elsewhere came from find in page, a screen reader's
 cursor or your own `scrollTop`, none of which the pin hears: treat it as the
-user's.
+user's. Such a scroll can land within the hold a correction starts, which
+ignores it: give `createScrollSpy` the option `readerPosition`, which says
+whether the view is still where the reader put it, and the spy measures once,
+two frames after release (past a resize's correction), when a held scroll
+left it elsewhere. Its fourth argument is `{ idleMs?, readerPosition? }`; a
+bare number is still `idleMs`. Not covered: a second correction within the
+same hold puts the view back where the reader put it, and that scroll is lost.
 
 ```ts
-import { pinHolds, pinToPage } from '@nxgt/material-core/pdf-viewer';
+import {
+  createScrollSpy,
+  pinHolds,
+  pinToPage,
+} from '@nxgt/material-core/pdf-viewer';
 
-// pages: Map<number, HTMLElement>; spy: from createScrollSpy
+// pages: Map<number, HTMLElement>
 let pinned = true;
+const spy = createScrollSpy(
+  () => area, // the reader's page area
+  () => pages,
+  onScroll,
+  // still where the reader put it
+  { readerPosition: () => !pinned || pinHolds(pages.get(3)) },
+);
 const unpin = pinToPage(
   () => pages.get(3), // the page's element, looked up again on each correction
   () => spy.hold(), // the corrections are not the user's scrolling
@@ -348,6 +371,14 @@ function onScroll(page: number) {
 }
 ```
 
+`pageInView(area, pages)` is the spy's own measure, on demand: the page most
+on screen, the last one in view once the area is scrolled to its end, or `null` when
+no page is in view.
+
+```ts
+const page = pageInView(area, pages); // 3
+```
+
 ### A currency's decimals: `/currency-digits`
 
 ```ts
@@ -482,6 +513,25 @@ what a combobox's polite live region says: the failure, else "loading",
 else the count once the query has settled — `null` while the user is still
 typing.
 
+### An open list above a Drawer's footer: `/drawer-room`
+
+`drawerRoom(element, top)` looks for the `[data-slot="drawer-content"]` around
+`element` and answers how many pixels a floating list that starts at `top`
+(a viewport coordinate) may take before it reaches the Drawer's
+`[data-slot="drawer-footer"]`, or the Drawer's bottom edge without a footer,
+or the window's. It keeps an 8px gap and never answers less than 80, so the
+list stays usable. Outside a Drawer it answers `null`: the list keeps its own
+height.
+
+```ts
+import { drawerRoom } from '@nxgt/material-core/drawer-room';
+
+const room = drawerRoom(field, field.getBoundingClientRect().bottom + 6);
+list.style.maxHeight = room == null ? '' : `${room}px`;
+```
+
+Measure again when the field or the Drawer resizes or scrolls.
+
 ### One submit in flight: `/submit-guard`
 
 `createSubmitGuard()` returns `{ once, settle, pendingRun }`. `once(run)` wraps a
@@ -709,6 +759,54 @@ document.head.append(style);
   [`get-nonce`](https://www.npmjs.com/package/get-nonce)'s names, so a
   bundler alias can point that package here.
 
+### The CSP for a server or a build: `/csp`
+
+`/csp-nonce` reads the nonce in a browser; `/csp` is for the code that
+chooses it: an SSR request handler, a build script, a Vite plugin. It uses
+only `globalThis.crypto`, `btoa` and strings, so it runs on Node, Bun, Deno,
+workers and browsers, and keeps no state.
+
+```ts
+import {
+  applyCspNonce,
+  createCspNonce,
+  cspHash,
+  cspPolicy,
+  zodJitlessTag,
+} from '@nxgt/material-core/csp';
+
+// Per request (SSR): a fresh nonce, the header, the nonce in the HTML.
+const nonce = createCspNonce(); // 16 random bytes, base64
+const { header } = cspPolicy({ nonce }); // the policy of the CSP guide
+response.setHeader('Content-Security-Policy', header);
+const html = `<head>${zodJitlessTag(nonce)}…</head>`; // zod without new Function
+
+// A build that left CSP_NONCE_PLACEHOLDER in the HTML fills it per request:
+const page = applyCspNonce(builtHtml, nonce);
+
+// Static hosting has no per-request nonce: allow inline code by its hash.
+const hash = await cspHash("console.log('hi')"); // "'sha256-…'"
+cspPolicy({ hashes: { script: [hash] } }); // script-src 'self' 'sha256-…'
+```
+
+- `cspPolicy({ nonce?, dev?, hashes?, directives? })` returns
+  `{ directives, header }`. Without a nonce there is no `'strict-dynamic'`:
+  scripts fall back to `'self'` (and their hashes), style elements to
+  `'self' 'unsafe-inline'`, since the libraries create `<style>` elements at
+  runtime that no build can hash (a `hashes.style` entry replaces
+  `'unsafe-inline'`, which a browser ignores beside a hash); `dev` adds `ws:` and
+  `wss:` to `connect-src`; `directives` is merged per directive (sources are
+  appended), and a directive set to `null` or `[]` is dropped.
+- `applyCspNonce(html, nonce, placeholder?)` replaces every placeholder and
+  throws on a nonce outside base64 (`"`, `<`, a space would break out of the
+  attribute), and when `html` holds no placeholder (a hash-mode build, or a
+  custom placeholder not passed as the third argument).
+- **Never serve `CSP_NONCE_PLACEHOLDER` as a nonce**: it is public, so it
+  voids the policy. `applyCspNonce` and `cspPolicy` throw when given it.
+- `ZOD_JITLESS_SCRIPT` is `(globalThis.__zod_globalConfig??={}).jitless=true;`
+  (zod 4.4 and later), for a page whose policy has no `'unsafe-eval'`.
+  Each library tests it against the zod it runs on.
+
 ### Built on first use: `/lazy-object`
 
 `buildOnce(build)` returns a function that calls `build` on its first call
@@ -788,6 +886,45 @@ const { text, truncated } = await readTextPreview('/logs/today.log', {
 });
 ```
 
+### The kinds of an empty or failed screen: `/states`
+
+The framework-free half of `EmptyState` and `ErrorState`. Four **empty kinds**
+(`empty`, `search`, `not-found`, `unauthorized`) are an absence; three **error
+kinds** (`generic`, `offline`, `maintenance`) are something that failed.
+`resolveEmptyStateKind({ kind, variant })` picks `kind`, else the legacy
+`variant`, else `'generic'` (the default `EmptyState` has always had).
+`stateCopy(kind, family)` gives the i18n keys and the English fallbacks:
+`material.empty-state.<kind>.*` for the empty kinds, and for `EmptyState`
+given a legacy error `variant`; `material.error-state.<kind>.*` for the error
+kinds of `ErrorState` (`family` is `'empty-state'` or `'error-state'`).
+`STATE_ILLUSTRATIONS` is each kind's SVG geometry as data (shapes with a
+`tone`, no colour and no style); the libraries paint it with classes on theme
+tokens, so it is CSP-safe. `STATE_ACCENT` and `STATE_ICON` name each kind's
+accent and its lucide icon (kebab-case).
+
+`describeError(error, { maxDepth })` is what an `ErrorState` may show of a
+thrown value: `{ name, message }` for the error then each `cause` (3 entries
+by default), for an `Error`, a `{ message }` object, a string or a primitive,
+stopping at a cycle. It **never reads `.stack`**: a stack names files and
+paths. [More in docs/states.md](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/states.md).
+
+```ts
+import {
+	describeError,
+	resolveEmptyStateKind,
+	stateCopy,
+} from '@nxgt/material-core/states';
+
+resolveEmptyStateKind({}); // 'generic' — the legacy default
+resolveEmptyStateKind({ kind: 'search', variant: 'offline' }); // 'search'
+
+stateCopy('offline', 'error-state').titleKey; // 'material.error-state.offline.title'
+stateCopy('offline', 'empty-state').title; // 'You are offline'
+
+describeError(new Error('Could not save', { cause: new TypeError('Failed to fetch') }));
+// [{ name: 'Error', message: 'Could not save' }, { name: 'TypeError', message: 'Failed to fetch' }]
+```
+
 ### A field's blur across overlays: `/field-blur-layers`
 
 A field whose popover, listbox or dialog renders into `<body>` must not count
@@ -866,7 +1003,7 @@ const said: RowAnnouncement = { kind: 'removed', index: index + 1 };
 status.textContent = said.kind === 'removed' ? `Removed period ${said.index}` : '';
 ```
 
-### Escape while an overlay closes: `/escape-forward`
+### Escape while an overlay closes or a list is open: `/escape-forward`
 
 Radix's and reka's dismissable layers give Escape to the highest layer only,
 and a dialog's layer leaves their stack when its content unmounts, not when
@@ -892,6 +1029,35 @@ function onEscapeKeyDown(event: KeyboardEvent) {
 }
 ```
 
+`keepListEscape(event)` is the other half: Escape pressed in a field whose
+list is open belongs to the list. A Base UI combobox (`ComboboxField`,
+`Combobox`) closes its list from a handler on its input, but a Radix or reka
+overlay listens on the document first and closes itself with the list: the
+dialog, sheet, drawer or popover around the field vanished on the first
+Escape. Called from the content's escape handler, before the caller's own,
+`keepListEscape` prevents the default when the event's target is an open
+list's input, and returns whether it did; the list still closes, and the
+second Escape closes the overlay. The caller's handler then sees
+`event.defaultPrevented` true for an Escape that only closes a list. The
+target is read from the event's composed path and tested by `nodeType`, so a
+field in an iframe or a shadow root counts. The input counts as open when it
+is a `role="combobox"` with `aria-expanded="true"` whose `aria-controls`
+list sits in a `[data-slot="combobox-content"]` popup (a command palette's
+input is not), or when it carries `data-list-open="true"` (the Vue
+`Autocomplete`'s textbox).
+
+```ts
+import { forwardEscape, keepListEscape } from '@nxgt/material-core/escape-forward';
+
+const dialog = document.querySelector<HTMLElement>('[role="dialog"]');
+
+function onEscapeKeyDown(event: KeyboardEvent) {
+  keepListEscape(event); // an open list takes this Escape
+  if (event.defaultPrevented) return; // the dialog stays open
+  forwardEscape(dialog, event);
+}
+```
+
 ### A field's `aria-describedby`: `/described-by`
 
 `describedBy(own, ...ids)` joins the ids a field's control is described by:
@@ -1031,22 +1197,99 @@ row.addEventListener('click', (event) => {
 });
 ```
 
+### Background presets: `/backgrounds`
+
+The engine under the libraries' background presets, with the grain built so far; the other presets follow.
+A background is a **scene**: a plain tree `{ tag, attrs, children }` of SVG
+elements that each library renders with `createElement` or `h` — never as an
+HTML string. `assertSafeScene` throws for a `style`, an `on*` handler, an
+`href`, a URL, or a `url(…)` that is not the id of an element in the same
+scene, so a scene can never need `style-src-attr 'unsafe-inline'`. Everything
+is **seeded**: the same `seed` gives the same scene on the server and in the
+browser (no `Math.random`, nothing measured).
+
+```ts
+import {
+	assertSafeScene,
+	mulberry32,
+	motifShape,
+	observeBackgroundActivity,
+	place,
+	scatter,
+	svgIdPrefix,
+} from '@nxgt/material-core/backgrounds';
+
+const rand = mulberry32(42);
+const dots = scatter(rand, [60, 40, 24, 12]).map((p) =>
+	place({ x: p.x, y: p.y, className: 'k1', opacity: 0.6 }, motifShape('ring', p.s, false)),
+);
+const scene = { tag: 'svg', attrs: { viewBox: '0 0 1600 1000' }, children: dots } as const;
+assertSafeScene(scene, svgIdPrefix(':r1:')); // throws if anything is unsafe
+
+// pause an animation when the page is hidden, the element is off screen or
+// the user prefers reduced motion; call it from an effect, once mounted
+const stop = observeBackgroundActivity(element, (paused) => {
+	element.toggleAttribute('data-paused', paused);
+});
+stop();
+```
+
+`svgIdPrefix(useId())` makes a generated id safe inside `url(#…)`
+(`':r1:'` becomes `'bg-r1'`). `BACKGROUND_PRESETS` is the table of the 20
+preset ids with their family, how each is drawn and whether `seed` changes
+it. `buildBackgroundScene(preset, { idPrefix, seed })` returns the scene of a
+preset, or `null` for a CSS-only one or one with no builder yet (only `grain` has one so far).
+`SHIPPED_BACKGROUND_PRESETS` (`gradient`, `grain`) is what the libraries draw today, and
+`resolveShippedPreset(id)` returns `id` when it ships, else `'gradient'`, with a one-time
+warning outside production. See
+[Backgrounds](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/backgrounds.md).
+
+### One plugin: `nxgtMaterial()` (`/vite`)
+
+```ts
+// vite.config.ts
+import { nxgtMaterial } from '@nxgt/material-core/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [...nxgtMaterial({ csp: { mode: 'hash' } })] });
+```
+
+It sets up a strict Content Security Policy (zod's jitless script, then the
+sha256 of every inline script and style of `index.html` written to
+`dist/.vite/nxgt-csp.json` with a ready header that uses the script hashes, or `csp: { mode: 'nonce' }`
+for a placeholder your server fills with `applyCspNonce`), keeps fonts out of
+`data:` URIs, and, when called with a library name (the libraries'
+`/vite` do it), loads Inter (when `@fontsource-variable/inter` is installed; otherwise it warns and keeps the system font) and fails the build when the library's stylesheet
+is not wired (neither `styles.css` nor the compiled stylesheet,
+`@import "<library>";`). The libraries' [Vite plugin guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/vite-plugin.md)
+has every option, and the [migration guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/migrate-to-vite-plugin.md)
+moves a hand-written setup over. It reads stylesheets and the renderer's
+`package.json` files from disk (`node:fs`, `node:fs/promises`, `node:path`), so
+`/vite` is build-time code like `/pdfkit-fonts`.
+
 ### Bundling pdfkit's fonts: `/vite`
 
 An SSR server bundled into a single file with no `node_modules` needs
-pdfkit's standard fonts inlined, or it throws on every request:
+pdfkit's standard fonts inlined, or it throws on every request. With a
+library name (the libraries' `/vite` pass it), `nxgtMaterial()` does both
+halves:
 
 ```ts
 // vite.config.ts
-import { pdfkitStandardFonts } from '@nxgt/material-core/vite';
+import { nxgtMaterial } from '@nxgt/material-core/vite';
 import { defineConfig } from 'vite';
 
-export default defineConfig({ plugins: [pdfkitStandardFonts()] });
+export default defineConfig({
+  plugins: [...nxgtMaterial({ pdf: { bundle: true } }, '@nxgt/material')],
+});
 ```
 
-`@nxgt/material/vite` and `@nxgt/material-vue/vite` export the same
-function. The doc comment on `pdfkitStandardFonts` explains when you need it
-and when keeping the library external is the lighter answer.
+`pdf` is on by default (`pdfkitStandardFonts()`, a no-op unless pdfkit goes
+through the bundle); `pdf: { bundle: true }` also puts the library, core,
+`pdfkit`, `@react-pdf/*` and the renderer's runtime dependencies into
+`ssr.noExternal` (`react` and your own dependencies stay yours to bundle). `@nxgt/material/vite` and
+`@nxgt/material-vue/vite` export `pdfkitStandardFonts` on its own too; its doc
+comment explains when keeping the library external is the lighter answer.
 
 ### Fonts under a strict CSP: `cspAssetsInlineLimit` (`/vite`)
 
@@ -1121,6 +1364,7 @@ Every message, with its cause, is in [troubleshooting](https://cdn.jsdelivr.net/
 ## Documentation
 
 - [docs/README.md](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/README.md) — every page, and when to read it
+- [States](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/states.md) — the kinds, copy keys, `describeError` and illustrations of `EmptyState` and `ErrorState`
 - [Troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/troubleshooting.md) — every error message, and its fix
 - [Roadmap](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/roadmap.md) — what is next
 

package/dist/backgrounds/activity.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tells `onChange` whether an animated background should be paused: the page
+ * is hidden, the element is off screen, or the user prefers reduced motion.
+ * Calls `onChange` once with the current state, then on each change only.
+ * Returns the function that removes every listener and observer.
+ *
+ * Reads the DOM when called, never at import: call it from an effect or
+ * `onMounted`, and only when the background is `animated`.
+ */
+export declare function observeBackgroundActivity(el: Element, onChange: (paused: boolean) => void): () => void;
+//# sourceMappingURL=activity.d.ts.map

package/dist/backgrounds/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../src/backgrounds/activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACxC,EAAE,EAAE,OAAO,EACX,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GACjC,MAAM,IAAI,CAiCZ"}

package/dist/backgrounds/build.d.ts

@@ -0,0 +1,9 @@
+import type { BackgroundPreset, SceneNode, SceneOptions } from './types';
+/**
+ * The SVG scene of a preset, or `null` when it has none (the CSS-only
+ * presets, and a preset whose builder is not there yet). The same `seed`
+ * always gives the same scene. The scene is checked with `assertSafeScene`
+ * before it is returned.
+ */
+export declare function buildBackgroundScene(preset: BackgroundPreset, opts: SceneOptions): SceneNode | null;
+//# sourceMappingURL=build.d.ts.map

package/dist/backgrounds/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/backgrounds/build.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,gBAAgB,EAEhB,SAAS,EACT,YAAY,EACZ,MAAM,SAAS,CAAC;AAWjB;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,YAAY,GAChB,SAAS,GAAG,IAAI,CAIlB"}

package/dist/backgrounds/id-prefix.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Turns a framework's generated id (React's `useId` gives `:r1:` or `«r1»`,
+ * Vue's `v-0`) into a prefix that is safe inside `url(#…)` and as an `id`:
+ * only `A-Z a-z 0-9 _ -`, and a letter first. Ids in a scene are
+ * `<prefix>-<name>`.
+ */
+export declare function svgIdPrefix(raw: string): string;
+//# sourceMappingURL=id-prefix.d.ts.map

package/dist/backgrounds/id-prefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-prefix.d.ts","sourceRoot":"","sources":["../../src/backgrounds/id-prefix.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG/C"}

package/dist/backgrounds/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@nxgt/material-core/backgrounds` — the engine behind the background
+ * presets: types, the preset table, a seeded random generator, noise,
+ * scattering, the motif primitives, the scene format and its safety check,
+ * ids for `url(#…)`, and the activity observer that pauses an animation.
+ * Framework-free; the libraries render a scene with `createElement` / `h`.
+ */
+export { observeBackgroundActivity } from './activity';
+export { buildBackgroundScene } from './build';
+export { svgIdPrefix } from './id-prefix';
+export { valueNoise2 } from './noise';
+export { BACKGROUND_PRESETS, resolveShippedPreset, SHIPPED_BACKGROUND_PRESETS, } from './presets';
+export { buildGrain } from './presets/grain';
+export { MOTIF_DEFAULTS, MOTIF_SHAPES, motifShape, type PlaceOptions, place, } from './primitives';
+export { mulberry32, pick, round1 } from './rng';
+export { type ScatterOptions, type ScatterPoint, scatter, } from './scatter';
+export { assertSafeScene, el, SCENE_ATTRIBUTES, SCENE_TAGS, } from './scene';
+export { BACKGROUND_INTENSITIES, BACKGROUND_TONES } from './tones';
+export type { BackgroundIntensity, BackgroundPreset, BackgroundTone, MotifDensity, MotifOptions, MotifShape, MotifSize, OpacitySpread, PresetInfo, SceneBuilder, SceneNode, SceneOptions, SceneTag, ShapeFill, ShippedBackgroundPreset, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/backgrounds/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backgrounds/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EACN,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,GAC1B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACN,cAAc,EACd,YAAY,EACZ,UAAU,EACV,KAAK,YAAY,EACjB,KAAK,GACL,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,OAAO,GACP,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,eAAe,EACf,EAAE,EACF,gBAAgB,EAChB,UAAU,GACV,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACnE,YAAY,EACX,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,SAAS,EACT,aAAa,EACb,UAAU,EACV,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,uBAAuB,GACvB,MAAM,SAAS,CAAC"}