@nxgt/material 3.7.5 → 3.8.0

package/dist/{use-heading-spy-ByOQNnFZ.js → use-heading-spy-DXo6IOX9.js}

@@ -1,77 +1,8 @@
-import { n as e } from "./stored-language-Bb7yX5uE.js";
-import { r as t } from "./i18n-provider-C6SBK_nO.js";
-import { t as n } from "./use-ssr-media-query-C6M5m8sf.js";
-import { _ as r, g as i, h as a, n as o, v as s, y as c } from "./number.utils-BG_eEt5g.js";
-import { useCallback as l, useEffect as u, useMemo as d, useRef as f, useState as p, useSyncExternalStore as m } from "react";
-//#region lib/hooks/resolve-theme.ts
-function h(e, t) {
-	let n = e === "light" || e === "dark" ? e : "system";
-	return {
-		theme: n === "system" ? t ? "dark" : "light" : n,
-		preference: n
-	};
-}
-function g(e) {
-	typeof document > "u" || (document.documentElement.classList.toggle("dark", e === "dark"), document.documentElement.style.colorScheme = e);
-}
-//#endregion
-//#region lib/hooks/use-is-client.ts
-function _() {
-	let [e, t] = p(!1);
-	return u(() => {
-		t(!0);
-	}, []), e;
-}
-//#endregion
-//#region lib/hooks/theme-store.ts
-var v = "theme", y = /* @__PURE__ */ new Set(), b;
-function x() {
-	let t = e(v);
-	if (t == null) return b;
-	try {
-		let e = JSON.parse(t);
-		return typeof e == "string" ? e : void 0;
-	} catch {
-		return t;
-	}
-}
-function S() {
-	for (let e of y) e();
-}
-function C(e) {
-	(e.key === v || e.key === null) && S();
-}
-var w = {
-	subscribe(e) {
-		return y.add(e), y.size === 1 && typeof window < "u" && window.addEventListener("storage", C), () => {
-			y.delete(e), y.size === 0 && typeof window < "u" && window.removeEventListener("storage", C);
-		};
-	},
-	getSnapshot: x,
-	getServerSnapshot: () => void 0,
-	set(e) {
-		b = e === "system" ? void 0 : e;
-		try {
-			e === "system" ? globalThis.localStorage?.removeItem(v) : globalThis.localStorage?.setItem(v, JSON.stringify(e));
-		} catch {}
-		S();
-	}
-};
-//#endregion
-//#region lib/hooks/use-theme.ts
-function T() {
-	let e = n("(prefers-color-scheme: dark)", !1), { theme: t, preference: r } = h(m(w.subscribe, w.getSnapshot, w.getServerSnapshot), e);
-	return {
-		theme: t,
-		preference: r,
-		updateTheme: l((t) => {
-			w.set(t), g(h(t === "system" ? void 0 : t, e).theme);
-		}, [e])
-	};
-}
-//#endregion
+import { r as e } from "./i18n-provider-C6HhBw34.js";
+import { _ as t, g as n, h as r, n as i, v as a, y as o } from "./number.utils-BG_eEt5g.js";
+import { useCallback as s, useEffect as c, useMemo as l, useRef as u } from "react";
 //#region ../../node_modules/date-fns/locale/fr/_lib/formatDistance.js
-var E = {
+var d = {
 	lessThanXSeconds: {
 		one: "moins d’une seconde",
 		other: "moins de {{count}} secondes"
@@ -133,11 +64,11 @@ var E = {
 		one: "presqu’un an",
 		other: "presque {{count}} ans"
 	}
-}, D = (e, t, n) => {
-	let r, i = E[e];
+}, f = (e, t, n) => {
+	let r, i = d[e];
 	return r = typeof i == "string" ? i : t === 1 ? i.one : i.other.replace("{{count}}", String(t)), n?.addSuffix ? n.comparison && n.comparison > 0 ? "dans " + r : "il y a " + r : r;
-}, O = {
-	date: c({
+}, p = {
+	date: o({
 		formats: {
 			full: "EEEE d MMMM y",
 			long: "d MMMM y",
@@ -146,7 +77,7 @@ var E = {
 		},
 		defaultWidth: "full"
 	}),
-	time: c({
+	time: o({
 		formats: {
 			full: "HH:mm:ss zzzz",
 			long: "HH:mm:ss z",
@@ -155,7 +86,7 @@ var E = {
 		},
 		defaultWidth: "full"
 	}),
-	dateTime: c({
+	dateTime: o({
 		formats: {
 			full: "{{date}} 'à' {{time}}",
 			long: "{{date}} 'à' {{time}}",
@@ -164,18 +95,18 @@ var E = {
 		},
 		defaultWidth: "full"
 	})
-}, k = {
+}, m = {
 	lastWeek: "eeee 'dernier à' p",
 	yesterday: "'hier à' p",
 	today: "'aujourd’hui à' p",
 	tomorrow: "'demain à' p'",
 	nextWeek: "eeee 'prochain à' p",
 	other: "P"
-}, A = (e, t, n, r) => k[e], j = {
+}, h = (e, t, n, r) => m[e], g = {
 	narrow: ["av. J.-C", "ap. J.-C"],
 	abbreviated: ["av. J.-C", "ap. J.-C"],
 	wide: ["avant Jésus-Christ", "après Jésus-Christ"]
-}, M = {
+}, _ = {
 	narrow: [
 		"T1",
 		"T2",
@@ -194,7 +125,7 @@ var E = {
 		"3ème trimestre",
 		"4ème trimestre"
 	]
-}, N = {
+}, v = {
 	narrow: [
 		"J",
 		"F",
@@ -237,7 +168,7 @@ var E = {
 		"novembre",
 		"décembre"
 	]
-}, P = {
+}, y = {
 	narrow: [
 		"D",
 		"L",
@@ -274,7 +205,7 @@ var E = {
 		"vendredi",
 		"samedi"
 	]
-}, F = {
+}, b = {
 	narrow: {
 		am: "AM",
 		pm: "PM",
@@ -305,7 +236,7 @@ var E = {
 		evening: "du soir",
 		night: "du matin"
 	}
-}, I = (e, t) => {
+}, x = (e, t) => {
 	let n = Number(e), r = t?.unit;
 	if (n === 0) return "0";
 	let i = [
@@ -316,48 +247,48 @@ var E = {
 		"second"
 	], a;
 	return a = n === 1 ? r && i.includes(r) ? "ère" : "er" : "ème", n + a;
-}, L = ["MMM", "MMMM"], R = {
-	en: a,
+}, S = ["MMM", "MMMM"], C = {
+	en: r,
 	fr: {
 		code: "fr",
-		formatDistance: D,
-		formatLong: O,
-		formatRelative: A,
+		formatDistance: f,
+		formatLong: p,
+		formatRelative: h,
 		localize: {
-			preprocessor: (e, t) => e.getDate() === 1 || !t.some((e) => e.isToken && L.includes(e.value)) ? t : t.map((e) => e.isToken && e.value === "do" ? {
+			preprocessor: (e, t) => e.getDate() === 1 || !t.some((e) => e.isToken && S.includes(e.value)) ? t : t.map((e) => e.isToken && e.value === "do" ? {
 				isToken: !0,
 				value: "d"
 			} : e),
-			ordinalNumber: I,
-			era: s({
-				values: j,
+			ordinalNumber: x,
+			era: a({
+				values: g,
 				defaultWidth: "wide"
 			}),
-			quarter: s({
-				values: M,
+			quarter: a({
+				values: _,
 				defaultWidth: "wide",
 				argumentCallback: (e) => e - 1
 			}),
-			month: s({
-				values: N,
+			month: a({
+				values: v,
 				defaultWidth: "wide"
 			}),
-			day: s({
-				values: P,
+			day: a({
+				values: y,
 				defaultWidth: "wide"
 			}),
-			dayPeriod: s({
-				values: F,
+			dayPeriod: a({
+				values: b,
 				defaultWidth: "wide"
 			})
 		},
 		match: {
-			ordinalNumber: i({
+			ordinalNumber: n({
 				matchPattern: /^(\d+)(ième|ère|ème|er|e)?/i,
 				parsePattern: /\d+/i,
 				valueCallback: (e) => parseInt(e)
 			}),
-			era: r({
+			era: t({
 				matchPatterns: {
 					narrow: /^(av\.J\.C|ap\.J\.C|ap\.J\.-C)/i,
 					abbreviated: /^(av\.J\.-C|av\.J-C|apr\.J\.-C|apr\.J-C|ap\.J-C)/i,
@@ -367,7 +298,7 @@ var E = {
 				parsePatterns: { any: [/^av/i, /^ap/i] },
 				defaultParseWidth: "any"
 			}),
-			quarter: r({
+			quarter: t({
 				matchPatterns: {
 					narrow: /^T?[1234]/i,
 					abbreviated: /^[1234](er|ème|e)? trim\.?/i,
@@ -383,7 +314,7 @@ var E = {
 				defaultParseWidth: "any",
 				valueCallback: (e) => e + 1
 			}),
-			month: r({
+			month: t({
 				matchPatterns: {
 					narrow: /^[jfmasond]/i,
 					abbreviated: /^(janv|févr|mars|avr|mai|juin|juill|juil|août|sept|oct|nov|déc)\.?/i,
@@ -422,7 +353,7 @@ var E = {
 				},
 				defaultParseWidth: "any"
 			}),
-			day: r({
+			day: t({
 				matchPatterns: {
 					narrow: /^[lmjvsd]/i,
 					short: /^(di|lu|ma|me|je|ve|sa)/i,
@@ -452,7 +383,7 @@ var E = {
 				},
 				defaultParseWidth: "any"
 			}),
-			dayPeriod: r({
+			dayPeriod: t({
 				matchPatterns: {
 					narrow: /^(a|p|minuit|midi|mat\.?|ap\.?m\.?|soir|nuit)/i,
 					any: /^([ap]\.?\s?m\.?|du matin|de l'après[-\s]midi|du soir|de la nuit)/i
@@ -477,28 +408,28 @@ var E = {
 		}
 	}
 };
-function z() {
-	let e = t()?.language ?? "en", n = d(() => R[e] ?? a, [e]);
+function w() {
+	let t = e()?.language ?? "en", n = l(() => C[t] ?? r, [t]);
 	return {
-		language: e,
+		language: t,
 		locale: n,
-		format: l((e, t) => o.format(e, t, n), [n])
+		format: s((e, t) => i.format(e, t, n), [n])
 	};
 }
 //#endregion
 //#region lib/hooks/use-focus-on-mount.ts
-function B(e = !0) {
-	let t = f(null);
-	return u(() => {
+function T(e = !0) {
+	let t = u(null);
+	return c(() => {
 		e && t.current?.focus();
 	}, [e]), t;
 }
 //#endregion
 //#region lib/hooks/use-heading-spy.ts
-var V = "0px 0px -65% 0px", H = [0, 1];
-function U(e, t, n) {
-	let r = n?.rootMargin ?? V, i = n?.threshold ?? H;
-	u(() => {
+var E = "0px 0px -65% 0px", D = [0, 1];
+function O(e, t, n) {
+	let r = n?.rootMargin ?? E, i = n?.threshold ?? D;
+	c(() => {
 		if (e.length === 0) return;
 		let n = e.map((e) => document.getElementById(e)).filter((e) => e != null);
 		if (n.length === 0) return;
@@ -519,4 +450,4 @@ function U(e, t, n) {
 	]);
 }
 //#endregion
-export { _ as a, T as i, B as n, g as o, z as r, h as s, U as t };
+export { T as n, w as r, O as t };

package/dist/{use-material-translation-hLQzOjF0.js → use-material-translation-DkxcLbLM.js}

@@ -1,5 +1,5 @@
-import { r as e } from "./i18n-provider-C6SBK_nO.js";
-import { t } from "./translate-material-Bsjc4Tow.js";
+import { r as e } from "./i18n-provider-C6HhBw34.js";
+import { t } from "./translate-material-CGZljjp1.js";
 import { useCallback as n } from "react";
 //#region lib/i18n/use-material-translation.ts
 function r() {

package/dist/use-slice-reducer-BGkeGtML.js

@@ -0,0 +1,42 @@
+import { useEffect as e, useMemo as t, useReducer as n, useState as r, useSyncExternalStore as i } from "react";
+//#region lib/lib/redux/bind-slice-actions.ts
+function a(e, t) {
+	let n = {};
+	for (let r of Object.keys(e)) {
+		let i = e[r];
+		n[r] = (...e) => t(i(...e));
+	}
+	return n;
+}
+//#endregion
+//#region lib/lib/redux/slice-server-state.ts
+var o = /* @__PURE__ */ new WeakMap();
+function s(e, t) {
+	o.set(e, t);
+}
+function c(e) {
+	return o.get(e);
+}
+//#endregion
+//#region lib/lib/redux/use-slice-reducer.ts
+function l(e, t) {
+	return t ? {
+		...e,
+		...t
+	} : e;
+}
+var u = "nxgt/useSliceReducer/restore", d = () => () => {}, f = () => !1;
+function p(e) {
+	return (t, n) => n.type === u ? n.payload : e(t, n);
+}
+function m(o, s) {
+	let m = c(o), h = i(d, f, () => m !== void 0), [g] = r(h), [_, v] = n(t(() => p(o.reducer), [o.reducer]), s, (e) => l(h && m ? m() : o.getInitialState(), e));
+	return e(() => {
+		g && v({
+			type: u,
+			payload: l(o.getInitialState(), s)
+		});
+	}, []), [_, t(() => a(o.actions, v), [o.actions])];
+}
+//#endregion
+export { a as i, m as n, s as r, l as t };

package/dist/use-theme-Cd-aiDJo.js

@@ -0,0 +1,31 @@
+import { t as e } from "./use-ssr-media-query-C6M5m8sf.js";
+import { i as t, n, o as r, r as i, s as a, t as o } from "./theme-store-CSl51uNH.js";
+import { a as s } from "./theme-context-BagPvRcz.js";
+import { useCallback as c, useEffect as l, useState as u, useSyncExternalStore as d } from "react";
+import { PRESET_SCHEMES as f } from "@nxgt/material-core/theme/boot";
+//#region lib/hooks/use-is-client.ts
+function p() {
+	let [e, t] = u(!1);
+	return l(() => {
+		t(!0);
+	}, []), e;
+}
+//#endregion
+//#region lib/hooks/use-theme.ts
+var m = new Map(Object.entries(f));
+function h(l = {}) {
+	let u = s(), f = d(o.subscribe, o.getSnapshot, o.getServerSnapshot), p = u?.name ?? a(f, void 0, i), h = l.defaultMode ?? (u ? u.defaultMode : m.get(p)) ?? "system", g = e("(prefers-color-scheme: dark)", !1), { theme: _, preference: v } = r(d(n.subscribe, n.getSnapshot, n.getServerSnapshot), g, h);
+	return {
+		theme: _,
+		preference: v,
+		updateTheme: c((e) => {
+			n.set(e, h), t(r(e, g, h).theme);
+		}, [g, h]),
+		themeName: p,
+		setThemeName: c((e) => {
+			o.set(e);
+		}, [])
+	};
+}
+//#endregion
+export { p as n, h as t };

package/docs/README.md

@@ -8,6 +8,7 @@ detail: every option, the second example, and the traps.
 | [Getting started](getting-started.md) | You are installing the package, wiring its styles and icons, or upgrading to a new release |
 | [Components](components/README.md) | You are looking for a component — one preview per category, then one page per category |
 | [Forms](guides/forms.md) | You are building a form: the field / `*FormField` pair, React Hook Form + Zod, what each field emits, server errors, multi-step forms |
+| [Themes for your app](guides/themes.md) | You define your own themes: `defineTheme` modules, the Vite plugin's `themes` option, the `nxgt-theme` command and its CI check, the tone warnings |
 | [Charts](guides/charts.md) | You draw charts with `@nxgt/material/charts`: each chart, the shared props, zoom and phone scroll, the keyboard, accessibility, theming the `--chart-1..5` tokens, and moving off the Nivo charts, removed in 3.0 |
 | [Cards and tiles](guides/cards-and-tiles.md) | You want a `DataTable` as a list of cards or tiles: `layout`, `renderCard`, `renderTile`, the card's one link, selection, the sort control, columns by the list's width |
 | [DataGrid](guides/data-grid.md) | You are building an editable grid: columns and editors, save modes and conflicts, resizing, hiding and reordering columns, paste, fill and series, undo, totals, long lists, phones, custom editors, CSP |
@@ -15,7 +16,7 @@ detail: every option, the second example, and the traps.
 | [i18n](guides/i18n.md) | You want the components in French, your own strings typed, or translated Zod messages |
 | [App shell](guides/app-shell.md) | You are mounting the sidebar, header and breadcrumbs (`ActivityLayout`) around your routes |
 | [Animations](guides/animations.md) | You animate with `animate-*` classes: setup next to `tw-animate-css`, every animation with its defaults, the modifiers, stagger, text splitting, scroll-driven animation, appear/disappear, reduced motion, recipes and browser support |
-| [Theming](guides/theming.md) | You want to change colours or radius, add dark mode without a flash, use tones (the `data-tone` channel and app tones), or use the compiled CSS without Tailwind |
+| [Theming](guides/theming.md) | You want to change colours or radius, use a shipped theme (`@nxgt/material/themes/<name>.css`) or a themed zone, add dark mode without a flash, use tones (the `data-tone` channel and app tones), or use the compiled CSS without Tailwind |
 | [Printing](guides/printing.md) | You render PDF documents with `@nxgt/material/print`, turn them into a download, a new tab or a server response, write them as plain data, or bundle them into an SSR server |
 | [PDF reader](guides/pdf-reader.md) | You render PDFs with `@nxgt/material/pdf-reader`: the pdf.js assets and worker, `configurePdfReader`, server rendering, the Content-Security-Policy and moving from the classic reader (removed in 3.0) |
 | [Media players](guides/media.md) | You play video or audio: embedded, audio cards, playlists, chapters and transcript, sound across pages with `MediaPlayerHost`, the lightbox, CSP and keyboard |

package/docs/components/foundations.md

@@ -6,6 +6,7 @@ The full guide, with every animation's defaults, recipes and browser support, is
 
 | | Component | What it does |
 | --- | --- | --- |
+| <img src="../previews/foundations-themes-themepicker.webp" width="96" alt=""> | [ThemePicker](#themepicker) | A radiogroup of theme tiles with a mini preview and the light / dark / system control |
 | | [Animations](#animations) | Tailwind 4 animation classes and modifiers, pure CSS: entrances and exits, attention seekers, loops and ambient motion, stagger, text reveals, scroll-driven animation, appear and disappear |
 
 ## Animations
@@ -157,3 +158,41 @@ out with no JavaScript: `@starting-style` for the way in, `allow-discrete` so
 - Reduced motion: a 150ms fade, no movement or scale.
 
 The Storybook page *Foundations / Animations* shows every class with controls.
+
+## ThemePicker
+
+![ThemePicker](../previews/foundations-themes-themepicker.webp)
+
+A radiogroup of tiles, one per theme. Each tile is a zone of its own theme, so its
+three swatches (primary, secondary, tertiary) and its mini background (the theme's
+tone and preset's texture, drawn by CSS) are that theme's colours in the page's
+mode. The light / dark / system control sits beneath. The arrow keys move the
+choice; the selected tile is tinted, with a start bar and its name in primary text.
+
+```tsx
+import { ThemePicker } from '@nxgt/material/theme-picker';
+import { NxgtThemeProvider } from '@nxgt/material/themes';
+
+<NxgtThemeProvider>
+  <ThemePicker />
+</NxgtThemeProvider>;
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `themes` | `readonly Theme[]` | the provider's, else the presets | the tiles; add your own `defineTheme` results (give the same list to `NxgtThemeProvider`, which resolves the stored name) |
+| `value` / `onValueChange` | `ThemeName` / `(name) => void` | the current theme | controlled: the choice is not stored; uncontrolled: it is stored (`setThemeName`) |
+| `showMode` | `boolean` | `true` | the light / dark / system control |
+| `showBackground` | `boolean` | `true` | the mini background in each tile |
+| `layout` | `'grid' \| 'list'` | `'grid'` | `'list'` for a menu or a narrow sheet; the grid goes from 2 to 4 columns with its width |
+
+A tile's name is the theme's `label` in the current language (a string, or one per
+locale; the capitalised name when there is none). The group is named by
+`material.theme-picker.label` and the mode control by `material.theme-picker.mode`; the mode control is `ThemeToggle`, whose Light, Dark and System names keep their own keys.
+It writes no inline style, so a strict CSP needs nothing. Its tiles are styled by
+an opt-in stylesheet, `@import "@nxgt/material/theme-picker.css";` after
+`styles.css` (about 3.3 KB gzipped, not part of `styles.css`, so an app without
+the picker pays nothing); the app also imports each theme's stylesheet
+(`@nxgt/material/themes/<name>.css`), as for any theme.
+
+**Storybook:** `Foundations/Themes/ThemePicker` · **Vue:** none

package/docs/components/navigation-and-layout.md

@@ -24,7 +24,7 @@ documentation-site shell. Everything is imported from
 | <img src="../previews/navigation-layout-steps.webp" width="96" alt=""> | [Steps](#steps) | Numbered editorial steps |
 | <img src="../previews/navigation-layout-hero.webp" width="96" alt=""> | [Hero](#hero) | Landing band |
 | <img src="../previews/navigation-layout-doc.webp" width="96" alt=""> | [Doc](#doc) | Documentation site shell |
-| <img src="../previews/navigation-layout-background.webp" width="96" alt=""> | [Background](#background) | Gradient backdrop with colour blobs |
+| <img src="../previews/navigation-layout-background.webp" width="96" alt=""> | [Background](#background) | Gradient backdrop with colour blobs; the `/backgrounds` one takes its unset props from the nearest theme |
 | | [NavigationRail](#navigationrail) | Placeholder, no props yet |
 
 ## ActivityLayout
@@ -81,7 +81,7 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 | `titleAs` | `'h1'` … `'h6'` \| `'div'` | `'h1'` | `ActivityContent`: the title's heading level |
 | `inset` | `boolean` | `false` | `ActivityContent`: pads the content 1rem on each side. Off, it lines up with the app bar and the cards |
 | `align` | `'start' \| 'center'` | `'start'` | `ActivityLayout`, `AppSidebar`: the collapsed rail's entries sit right under the brand, or `'center'` for centred in the height below it |
-| `backdrop` | `ReactNode` | — | `ActivityLayout`: a decorative background behind the frame, in place of the gradient and its blobs: a `Background` preset from `@nxgt/material/backgrounds`. Rendered in an `inert`, `aria-hidden` layer as wide as the content column and one viewport high, fixed in the viewport while the content scrolls; the chrome (app bar, breadcrumb, tabs strip) is lightly translucent and frosted over it (80%, 87% for the sidebar, breadcrumb and tabs strip, 92% and no blur under `prefers-reduced-transparency` or without `backdrop-filter`), and the lists, tables and cards stay opaque; `--nxgt-backdrop-chrome` sets the chrome's fill and `--nxgt-backdrop-surface` the lists'. See [Use a background preset behind the shell](../guides/app-shell.md#use-a-background-preset-behind-the-shell) |
+| `backdrop` | `ReactNode \| false` | — | `ActivityLayout`: an exception to the theme's background (drawn by default; Lavande's is the built-in gradient and blobs); `false` draws a plain page. A node is a decorative background behind the frame: a `Background` preset from `@nxgt/material/backgrounds`. Rendered in an `inert`, `aria-hidden` layer as wide as the content column and one viewport high, fixed in the viewport while the content scrolls; the chrome (app bar, breadcrumb, tabs strip) is lightly translucent and frosted over it (80%, 87% for the sidebar, breadcrumb and tabs strip, 92% and no blur under `prefers-reduced-transparency` or without `backdrop-filter`), and the lists, tables and cards stay opaque; `--nxgt-backdrop-chrome` sets the chrome's fill and `--nxgt-backdrop-surface` the lists'. See [Use a background preset behind the shell](../guides/app-shell.md#use-a-background-preset-behind-the-shell) |
 | `routeTransition` | `boolean \| Omit<ViewTransitionProps, 'children' \| 'ref'>` | `true` | `ActivityLayout`: React's `<ViewTransition>` around the content region, so a navigation cross-fades it. `false` renders none (your app has its own boundary); an object passes `default` / `update` classes, `name`, callbacks through. See [Route transitions](../guides/app-shell.md#route-transitions) |
 
 The active entry is the longest match across the whole menu, segment-aware.
@@ -742,7 +742,7 @@ import { Background, Card } from '@nxgt/material/components';
 It fills the viewport; pass a `className` such as `h-96 w-full` to use it as a band.
 It is plain CSS from `styles.css`, with no inline `style`, and its colours lift
 in dark. `ActivityLayout` and `ThreadLayout` sit on it. The superset with `grain`,
-`seed`, `fill`, `motif` and the other presets (light, geometry and motif families) is `Background` from `/backgrounds`; see the [backgrounds guide](../guides/backgrounds.md). Light presets there: `mesh`, `aurora`, `spotlight`, `bokeh`, `rays`, `halo`, `plasma`, `glass`, `ripples`, `blobs`, `paper`, `linen`, `concrete`, `marble`, `grain`; geometry: `isometric`, `blueprint`, `dots`, `stripes`, `low-poly`, `topography`, `waves`, `hexagons`, `circuit`, `graph-paper`, `checker`, `diagonal-checker`, `chevrons`; motifs: `shapes`, `confetti-grid`, `constellation`, `halftone`, `truchet`, `floating`, `scatter-icons`, `school`, `night-sky`, `bubbles`, `leaves`, `science`, `music`, `travel`, `sport`.
+`seed`, `fill`, `motif` and the other presets (light, geometry and motif families) is `Background` from `/backgrounds`; see the [backgrounds guide](../guides/backgrounds.md). Light presets there: `mesh`, `aurora`, `spotlight`, `bokeh`, `rays`, `halo`, `plasma`, `glass`, `ripples`, `blobs`, `paper`, `linen`, `concrete`, `marble`, `grain`; geometry: `isometric`, `blueprint`, `dots`, `stripes`, `low-poly`, `topography`, `waves`, `hexagons`, `circuit`, `graph-paper`, `checker`, `diagonal-checker`, `chevrons`; motifs: `shapes`, `confetti-grid`, `constellation`, `halftone`, `truchet`, `floating`, `scatter-icons`, `school`, `night-sky`, `bubbles`, `leaves`, `science`, `music`, `travel`, `sport`, `moon`.
 
 **Storybook:** `Navigation & layout/Background` · **Vue:** `Background`
 

package/docs/getting-started.md

@@ -139,7 +139,7 @@ and need nothing.
 | `@nxgt/material/editor/viewer` | `RichTextViewer`: shows a saved document (HTML, JSON or Markdown) read-only. **Server-safe**: no editor instance, no `'use client'` ([RichTextViewer](components/rich-widgets.md#richtextviewer)) |
 | `@nxgt/material/editor/collab` | `collaboration()`: several people editing one `DocumentEditor` through a Yjs document and provider your app supplies. Needs `yjs` and `y-protocols` ([Collaboration](components/rich-widgets.md#collaboration)) |
 | `@nxgt/material/editor/pm` | The editor's own tiptap and ProseMirror classes (`Extension`, `Node`, `Plugin`, `PluginKey`, `TextSelection`, `ProseMirrorNode`, `Fragment`, `DecorationSet`, …) for a custom feature's extensions, so `instanceof` agrees with the editor. Shares the editor's code; **server-safe** ([A custom feature](components/rich-widgets.md#a-custom-feature)) |
-| `@nxgt/material/backgrounds` | Background presets: `Background` (a superset of the `/components` one: `preset` (44 ids, `AVAILABLE_BACKGROUND_PRESETS`), `tone`, `intensity`, `animated`, `grain`, `seed`, `fill` and `motif` (`shapes`, `density`, `size`, `rotate`, `shapeFill`, `opacitySpread`)), and the types and tables re-exported from `@nxgt/material-core/backgrounds`. **Its own entry**, with an opt-in stylesheet ([backgrounds](guides/backgrounds.md)) |
+| `@nxgt/material/backgrounds` | Background presets: `Background` (a superset of the `/components` one: `preset` (45 ids, `AVAILABLE_BACKGROUND_PRESETS`), `tone`, `intensity`, `animated`, `grain`, `seed`, `fill` and `motif` (`shapes`, `density`, `size`, `rotate`, `shapeFill`, `opacitySpread`)), and the types and tables re-exported from `@nxgt/material-core/backgrounds`. **Its own entry**, with an opt-in stylesheet ([backgrounds](guides/backgrounds.md)) |
 | `@nxgt/material/media-hls` | `hlsStreaming()`: the HLS adapter for `MediaPlayer`, `hls.js` loaded lazily ([streaming](guides/media-streaming.md)) |
 | `@nxgt/material/vite` | Build-time helper for consumers: `pdfkitStandardFonts()` ([printing](guides/printing.md#bundling-print-into-an-ssr-server)) |
 | `@nxgt/material/hooks` | `useTheme`, `useIsClient`, `useIsMobile`, `useLocalizedDate`, … ([helpers](guides/helpers.md#nxgtmaterialhooks)) |

package/docs/guides/app-shell.md

@@ -191,7 +191,7 @@ partitionMenu(items);                              // { content, footer }
 | `align` | `'start' \| 'center'` | `'start'` | Where the collapsed rail's entries sit: right under the brand, or centred in the height below it |
 | `menuOpen` | `boolean` | — | Controls the phone's menu sheet: open while `true`. Leave it out and the layout manages the sheet. Only a phone shows the sheet |
 | `onMenuOpenChange` | `(open: boolean) => void` | — | Called for every change of the sheet: the menu button, Escape, the close button, a followed link, a new location |
-| `backdrop` | `ReactNode` | — | A decorative background drawn behind the frame in place of the built-in gradient and blobs: usually a `Background` preset from `@nxgt/material/backgrounds` (see [Use a background preset behind the shell](#use-a-background-preset-behind-the-shell)) |
+| `backdrop` | `ReactNode \| false` | — | An exception to the theme's background, which the layout draws by default (Lavande's: the built-in gradient and blobs). A node replaces it for this screen: usually a `Background` preset from `@nxgt/material/backgrounds` (see [Use a background preset behind the shell](#use-a-background-preset-behind-the-shell)); `false` draws no background, a plain page |
 
 On a page with `viewport-fit=cover` (an installed PWA drawing under a
 notch and the home indicator), the shell pads clear of
@@ -484,10 +484,44 @@ while the sheet is open, so leave ids out of it. A link in `brand` (a home
 link around the logo) is the sheet's first focusable element, so it takes
 the focus when the sheet opens.
 
+## The theme's background
+
+`ActivityLayout` draws the background of the nearest theme (`NxgtThemeProvider`
+or an `NxgtTheme` zone around it; see [Themes](./theming.md#the-provider-and-zones)).
+`backdrop` is the exception:
+
+| Case | What is drawn |
+| --- | --- |
+| no theme, or Lavande (a `gradient` background in the `primary` tone, default intensity) | the built-in gradient and its three blobs; the markup is what it was, plus `data-slot="activity-content-header"` on the content header card |
+| any other theme background | that background in the backdrop layer, with the frosted chrome described below (`@nxgt/material/backgrounds.css` is yours to import) |
+| a theme with `background: false` | no background |
+| `backdrop={<Background … />}` | that node, for this screen |
+| `backdrop={false}` | no background and no blobs: a plain page (`data-plain` on the root) |
+
+The theme's shapes (the motif and illustrated presets) stay whole: a shape that
+would cross the layer's edge, or reach the app bar, the breadcrumb, the header
+card or an `EntityHeader`, is not drawn, and nothing shows until that first
+check has run. Full-width textures such as `waves` and the gradient are not
+shapes and are not filtered. A `Background` passed as `backdrop` is kept whole the same way; any other node is left as it is.
+
+`backdrop={false}` used to draw the built-in gradient, as if it were left out;
+it now removes it. To keep the gradient, leave `backdrop` out. A theme's
+background is loaded on demand (the scene engine, about 21 KB gzipped, is
+not part of `@nxgt/material/components`): a streaming server render sends it in
+the same response, `renderToString` fills the layer once the chunk has loaded.
+
+**Server render and a stored theme.** The server does not know the stored theme
+name: it renders `defaultTheme` (Lavande by default). A visitor whose stored theme
+is another one gets that theme's colours at once from the boot script, but the
+theme's backdrop (its background, shapes and the frosted chrome) appears only after
+hydration, once the stored name has been read. The first paint shows the default
+backdrop, or none. An app that must show the right backdrop in the first HTML has
+to know the theme on the server (a cookie, passed to `defaultTheme`).
+
 ## Use a background preset behind the shell
 
 The shell draws the gradient with three blurred blobs behind its frame. To use
-one of the 44 presets of `@nxgt/material/backgrounds` instead, pass it as
+one of the 45 presets of `@nxgt/material/backgrounds` instead, pass it as
 `backdrop`:
 
 ```tsx
@@ -508,10 +542,11 @@ export function Shell({ items }: { items: MenuItem[] }) {
 }
 ```
 
-- **It replaces the gradient.** While `backdrop` is given the layout's root
-  carries `data-backdrop`, and the built-in gradient (its tint and three blobs) is not drawn (plain
-  CSS, no inline `style`). Without it the markup and the look are what they
-  were; `null`, `undefined` and `false` count as none.
+- **It replaces the gradient.** While a `backdrop` node is given the layout's
+  root carries `data-backdrop`, and the built-in gradient (its tint and three
+  blobs) is not drawn (plain CSS, no inline `style`). Without it the look is
+  what it was (and the markup, bar the `activity-content-header` slot on the header card); `null` and `undefined` count as none, and `false`
+  is not none: it draws a plain page (see [The theme's background](#the-themes-background)).
 - **It sits behind the content column.** The node is wrapped in a layer
   (`[data-slot="activity-layout-backdrop"]`) that spans the column's width beside the
   sidebar, under the app bar, the breadcrumb and the content. The layer is `inert`, `aria-hidden="true"`