@nxgt/material 3.21.0 → 3.23.0

package/docs/guides/icon-motifs.md

@@ -16,7 +16,7 @@ Free works the same way.
 
 | You have | Serve | Use |
 | --- | --- | --- |
-| the Pro 7.3 pack | one sheet per style you draw, in `public/assets/icons/sprites/`: `duotone-thin.svg` (the default look), `duotone.svg`, `solid.svg`, `sharp-solid.svg`… A non-classic family is `<family>-<style>.svg` | the defaults |
+| the Pro 7.3 pack | one sheet per style you draw, in `public/assets/icons/sprites/`: the icon backgrounds' default mix needs `light.svg`, `thin.svg`, `sharp-regular.svg`, `sharp-light.svg` and `duotone-thin.svg`; `Icon`'s default look `duotone-thin.svg`; then `duotone.svg`, `solid.svg`, `sharp-solid.svg`… A non-classic family is `<family>-<style>.svg` | the defaults |
 | Font Awesome Free | `solid.svg`, `regular.svg` and `brands.svg` from `@fortawesome/fontawesome-free/sprites/`, copied to the same folder | `<IconSpritesProvider base="…" edition="free">` once at the root ([Free edition](#the-free-edition)) |
 
 The Free icons are CC BY 4.0: credit Font Awesome where you show them (the
@@ -54,23 +54,39 @@ import { Background } from '@nxgt/material/backgrounds';
   preset="icons"
   tone="mixed"
   icons="health" // a pack, or up to 48 names and { name, family?, type? }
-  iconStyle={['duotone-thin', 'duotone-light']} // one style, or a list of up to 8
-  iconMotif={{ layout: 'constellation', duotone: 'opacity' }}
+  iconStyle={[{ style: 'light', weight: 3 }, { style: 'duotone-thin' }]} // one style, a list of up to 8, or a weighted list
+  iconMotif={{ colors: 'one' }} // 'one', 'palette' or 'classic'
+  motif={{ icons: { ratio: 0.2 }, density: 'medium' }} // the share of icons among the shapes
 />;
 ```
 
-<img src="../previews/backgrounds-icons.webp" width="480" alt="The school pack of icons scattered over a faint wash, around a card">
+Since 3.22 this draws a **calm mix**: motif shapes and, in about one cell in
+five, an icon, all in one soft primary tint on an even grid over the whole
+frame (`preset="shapes"` with `motif.icons` draws the same). The [backgrounds
+guide](backgrounds.md#icons) lists the options.
+
+<img src="../previews/backgrounds-icons.webp" width="480" alt="The calm mix of shapes and a few school icons in one soft tint, in the open space below a dashboard">
 
 - **`icons`**: a pack name (`school`, `health`, `finance`, `travel`, `nature`,
   `tech`: lists of names, drawn in any style) or your own names and
   `{ name, family?, type? }` references. No `icons` draws the `school` pack.
-- **`iconStyle`**: one style (`'duotone-thin'`, `{ family: 'sharp', type: 'solid' }`)
-  or a list of up to 8. Each icon takes one style from the list by the seeded
-  pick, so a seed always draws the same picture. An icon's own `family` / `type`
-  always wins. Keep a list to styles that share your names.
-- **`iconMotif`**: `layout` (`scatter`, `grid`, `constellation`, `drift`),
-  `sizeRange`, `rotation`, `duotone` (`'opacity'`: the second layer is the same
-  tone at 0.4; `'tones'`: the next tone) and `secondaryOpacity`.
+- **`iconStyle`**: one style (`'duotone-thin'`, `{ family: 'sharp', type: 'solid' }`),
+  a list of up to 8, or a weighted list `[{ style, weight? }]`. Each icon takes
+  one style by the seeded pick, so a seed always draws the same picture. An
+  icon's own `family` / `type` always wins. Keep a list to styles that share
+  your names. The default is a weighted list (light 3, thin 3, sharp-regular 2,
+  sharp-light 2, duotone-thin 1): a weighted list is cut to the sprites your app
+  serves (`IconSpritesProvider`'s `servedStyles`, or the Free edition's
+  `regular` and `solid`), keeps the others' proportions, and draws Free
+  `regular` and `solid` when nothing is left.
+- **`iconMotif`**: `layout` (`even`, the default mix of shapes and icons;
+  `scatter`, `grid`, `constellation`, `drift`: icons only), `colors` (`'one'`,
+  `'palette'`, `'classic'`), `sizeRange`, `rotation`, `duotone` (`'opacity'`:
+  the second layer is the same tone at 0.4; `'tones'`: the next tone) and
+  `secondaryOpacity`.
+- **The look before 3.22** is icons only, scattered, in duotone thin and the
+  three tones at full strength:
+  `<Background preset="icons" iconStyle="duotone-thin" iconMotif={{ layout: 'scatter', colors: 'classic' }} />`.
 - `animated` drifts each icon a little; nothing moves under
   `prefers-reduced-motion`. Icons that cannot be drawn (an unknown pack or style,
   a bad name, more than 48) draw `scatter-icons`, with a console warning outside
@@ -192,7 +208,9 @@ Below it, in every `Icon` (so the app shell's menu, `AccountMenu`,
 every theme tile:
 
 - a style Free lacks is drawn from `solid.svg`: the default duotone, `thin`,
-  `light`, `sharp-*` and every other family. `regular` and `brands` stay;
+  `light`, `sharp-*` and every other family. `regular` and `brands` stay. An
+  icon background's weighted `iconStyle` (the default mix included) draws
+  `regular` and `solid` instead, since no Pro style is served;
 - a Pro-only name is renamed to its Free twin, the same one in every place
   (the table below, plus `chevrons-*` to `angles-*`, `badge-check` to
   `circle-check`, `loader` to `spinner`).

package/docs/guides/themes.md

@@ -54,14 +54,35 @@ export default defineTheme({
 - `Background`, `ActivityLayout` and every `NxgtTheme` zone read it: no props, and a prop you pass still wins.
   Serve the sprites (`/assets/icons/sprites/` or your `IconSpritesProvider base`) and import
   `@nxgt/material/backgrounds/icons.css` (or `backgrounds.css`); see [backgrounds](backgrounds.md#icons).
-- `extends` merges `iconMotif` and an `iconStyle` object key by key; `icons` and an `iconStyle` list or file name are
-  replaced whole. A derived theme that leaves them out inherits them.
-- `defineTheme` checks them when it is defined: `name` for an unknown pack, a bad icon name or style, `range` for the
-  rest (more than 48 icons, a layout, a size range).
+- `extends` merges `motif`, `iconMotif` and an `iconStyle` object key by key; `icons`, `motif.icons` and an `iconStyle`
+  list (weighted or not) or file name are replaced whole. A derived theme that leaves them out inherits them.
+- `defineTheme` checks them when it is defined: `name` for an unknown pack, a bad icon name or style or an unknown key,
+  `range` for the rest (more than 48 icons, a layout, a size range, a weight). 
+  A bad `motif` key or value is dropped, not thrown: `defineTheme` from `@nxgt/material/themes` warns for each one in development, the `@nxgt/material-core/theme/define` one only through its `{ warn }` option (4.0: an error; see [troubleshooting](../troubleshooting.md#definetheme-theme-x-backgroundmotif-unknown-key-spin-ignored)).
 - `ThemePicker` draws the theme's first four icons in its tile, from the same sprite base. A sprite that is not served
   draws nothing, and the tile keeps its wash.
 - The 14 shipped themes name no icons and are unchanged.
 
+### The calm backdrop's keys (3.22)
+
+`preset: 'icons'` is the calm mix by default; a theme tunes it with the same keys as the props:
+
+```ts
+background: {
+  preset: 'icons',
+  icons: 'school',
+  // a share each (default 1); a style the app does not serve is dropped, the rest keep their proportions
+  iconStyle: [{ style: 'light', weight: 3 }, { style: 'sharp-regular', weight: 2 }, { style: 'duotone-thin' }],
+  iconMotif: { layout: 'even', colors: 'one' },      // colors: 'one' | 'palette' | 'classic'
+  motif: { density: 'medium', icons: { ratio: 0.2 } }, // density: 'low' | 'medium' | 'high' | a count from 1 to 600
+}
+```
+
+`layout: 'even'` is the mix of shapes and icons; any other layout draws icons only. `motif.icons` is
+`{ pack?, style?, ratio }` and also works on `preset: 'shapes'`. The previous look is
+`iconStyle: 'duotone-thin', iconMotif: { layout: 'scatter', colors: 'classic' }`. Every key reaches the scene, and a
+prop on `Background` still wins. See [backgrounds](backgrounds.md#defaults-from-the-theme).
+
 ## Generate the files
 
 With Vite:

package/docs/guides/theming.md

@@ -1166,6 +1166,13 @@ Lavande tokens on `:root`.
   selector after the theme (`[data-nxgt-theme="ocean"] { --primary: … }`).
 - **Fonts.** The theme sets `font-family` on its own element; a font stack that
   is not installed falls back to the system face.
+- **Background.** A theme's `background` is read by `Background`, `ActivityLayout`
+  and `AuthCard`. Since 3.22 it takes the calm backdrop's keys: `iconMotif.layout:
+  'even'` and `colors: 'one' | 'palette' | 'classic'`, a weighted `iconStyle`
+  list, `motif.icons { pack, style, ratio }` and `motif.density` (`'low'`,
+  `'medium'`, `'high'` or a count). They are checked by `defineTheme`. A bad `motif` key or value is dropped, not thrown: `defineTheme` from `@nxgt/material/themes` warns for each one in development, the `@nxgt/material-core/theme/define` one only through its `{ warn }` option (4.0: an error; see [troubleshooting](../troubleshooting.md#definetheme-theme-x-backgroundmotif-unknown-key-spin-ignored)). See
+  [the calm backdrop in a theme](./backgrounds.md#the-calm-backdrop-in-a-theme)
+  and [Themes for your app](./themes.md#icon-motifs-in-a-theme).
 
 ### The provider and zones
 

package/docs/guides/vite-plugin.md

@@ -33,6 +33,7 @@ Every part is on by default and has an opt-out. It needs `vite` 5.2 or later (6,
 | `fonts.sans` | `'inter'` | Loads self-hosted Inter when `@fontsource-variable/inter` is installed (otherwise warns and keeps the system stack), in your root stylesheet, and sets `--font-sans`; `false` to keep the system stack and silence the warning. `fonts: false` turns both off |
 | `styles.check` | `true` | Fails `vite build` when the library's stylesheet is never imported (`@nxgt/material/styles.css`, or the compiled one through `@import "@nxgt/material";`), or `styles.css` is imported without the `@source` line Tailwind needs |
 | `themes` | off | Generates your themes' stylesheets and types and injects the boot script: see [Themes](#themes) |
+| `backdropSprite` | off | Builds the reduced backdrop sprite (one `<symbol>` per icon name and style, from your `@fortawesome/*` install) at build and serves it in dev; `packs` or `icons` is required, `true` is not accepted: see [The reduced backdrop sprite](#the-reduced-backdrop-sprite) |
 | `pdf` | on | pdfkit's standard fonts (`pdfkitStandardFonts()`): a no-op unless pdfkit goes through the bundle; and a dev-server route for the pdf.js worker (the `pdf.worker` row). `pdf: false` turns both off |
 | `pdf.bundle` | `false` | Also adds the renderer to `ssr.noExternal`, for a server whose runtime image has no `node_modules` (see [Rendering PDFs on a bundled server](#rendering-pdfs-on-a-bundled-server)) |
 | `pdf.worker` | `true` | Dev server only: answers `pdf.worker.min.mjs` in Vite's pre-bundle folder (`…/deps/`, any `cacheDir`, so Storybook and Vitest browser mode too) with the installed `@nxgt/material/dist/pdf.worker.min.mjs` (else `pdfjs-dist/build/…`). Vite 5 to 7 pre-bundle the library without the worker, so the readers' worker URL is a 404 there; Vite 8 needs no route, and `@nxgt/material-vue` none (it imports the worker with `?url`). `pdf: { worker: false }` drops it; then set `configurePdfReader({ workerSrc })` instead (see [the PDF reader guide](pdf-reader.md#bundlers)) |
@@ -159,6 +160,31 @@ message names the exact line to add.
 Opt out with `styles: false` (a Storybook build, for instance, may not import
 it).
 
+## The reduced backdrop sprite
+
+`backdropSprite` runs the same builder as the `nxgt-backdrop-sprite` command: one SVG sprite that holds only the icon
+packs' names in the chosen styles, read from the Font Awesome packages in your `node_modules`
+(`@fortawesome/fontawesome-pro`, else `@fortawesome/fontawesome-free`). There is no default pack: name the `packs` your backdrops draw, or an `icons` list; without either the plugin throws at startup (see [troubleshooting](../troubleshooting.md#backdropsprite-needs-the-icon-packs-your-backdrops-draw)).
+
+```ts
+nxgtMaterial({
+  backdropSprite: {
+    packs: ['health'],          // required (or icons): the icon packs whose names go in
+    icons: ['rocket'],          // names for your own `icons` list, alone or with packs
+    styles: ['light', 'thin'],  // default: the backdrop's styles that the install has, else regular and solid
+    base: '/sprites/',          // where it is served from (root-relative), default '/sprites/'
+    outFile: 'backdrop.svg',    // the file name under base, default 'backdrop.svg'
+    sources: ['node_modules/@fortawesome/fontawesome-pro'], // folders to read, default: the installed packages
+  },
+})
+```
+
+The build emits `dist/sprites/backdrop.svg` and the dev server answers `/sprites/backdrop.svg`; the plugin logs the
+`IconSpritesProvider` value (`backdropSprite={{ href, styles }}`) to use.
+The plugin's `base` is relative to the output folder; Vite's own `base` (`base: '/app/'`) prefixes the served and logged href, not the emitted file: the build still writes `dist/sprites/backdrop.svg`, the dev server answers `/app/sprites/backdrop.svg`, and the plugin logs `href: "/app/sprites/backdrop.svg"`. A plugin `base` that already starts with Vite's `base` has it stripped from the file name. A style you name that the install lacks fails
+the build. Use the plugin or the `nxgt-backdrop-sprite` command, not both: a `public/sprites/backdrop.svg` the command wrote is served before the plugin's route and shadows it. A Pro-only name built from a Free install is written under its Free twin and the build warns; set `edition="free"` on `IconSpritesProvider`. A sprite built from a Pro install is never committed or published. Restart the dev server after installing another Font Awesome package. See
+[the backgrounds guide](backgrounds.md#a-reduced-sprite-for-the-backdrop) for the runtime side.
+
 ## Rendering PDFs on a bundled server
 
 `pdf` is on by default and costs nothing for an app that never renders a PDF:

package/docs/roadmap.md

@@ -204,6 +204,12 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Later
 
+- **A strict theme `motif` (4.0)** — a theme background's `motif` with an
+  unknown key, a `layout` or `density` outside its list or a bad `icons` is
+  dropped in 3.22 (`@nxgt/material/themes`'s `defineTheme` warns for each one in
+  development; core's only through `{ warn }`); in 4.0 `defineTheme` throws
+  (`name` for a key, `range` for a value), as it does for the icon keys.
+
 - **More illustration sets** — finance, travel and tech scenes beside the
   health and education sets, each in its own subpath.
 - **More generic scenes** — further base scenes for `Illustration` beyond the

package/docs/troubleshooting.md

@@ -31,6 +31,10 @@ words in your error.
 - [A theme's colours do not show](#a-themes-colours-do-not-show)
 - [Math renders in the system fonts](#math-renders-in-the-system-fonts)
 - [`<Icon>` renders nothing](#icon-renders-nothing)
+- [`backdropSprite needs the icon packs your backdrops draw`](#backdropsprite-needs-the-icon-packs-your-backdrops-draw)
+- [Backdrop icons are blank with a reduced sprite](#backdrop-icons-are-blank-with-a-reduced-sprite)
+- [The `icons` backdrop looks different after 3.22](#the-icons-backdrop-looks-different-after-322)
+- [`defineTheme: Theme "x" background.motif: unknown key spin. Ignored.`](#definetheme-theme-x-backgroundmotif-unknown-key-spin-ignored)
 - [A background, an illustration or a theme tile draws no icons](#a-background-an-illustration-or-a-theme-tile-draws-no-icons)
 - [`Background: icons cannot be drawn (…); drawing "scatter-icons" instead.`](#background-icons-cannot-be-drawn--drawing-scatter-icons-instead)
 - [`IconRefError` from `IconSpritesProvider`](#iconreferror-from-iconspritesprovider)
@@ -352,6 +356,8 @@ words in your error.
 - [A `ServerTable` search shows older text, or a write is lost, over a slow router](#a-servertable-search-shows-older-text-or-a-write-is-lost-over-a-slow-router)
 - [`ListEmpty`'s title is now a heading](#listempty-title-is-now-a-heading)
 - [`ServerTable` keeps showing the empty page or the old rows after a failed fetch](#servertable-keeps-showing-the-empty-page-or-the-old-rows-after-a-failed-fetch)
+- [The focus falls to `<body>` after Previous / Next on a `ServerTable`](#the-focus-falls-to-body-after-previous--next-on-a-servertable)
+- [An empty gap under the `ServerTable` band while nothing is selected](#an-empty-gap-under-the-servertable-band-while-nothing-is-selected)
 - [The focus falls to the page after a `DataTable` bulk action](#the-focus-falls-to-the-page-after-a-datatable-bulk-action)
 - [A test's `getByText('No data available')` finds two elements after a change](#a-tests-getbytextno-data-available-finds-two-elements-after-a-change)
 - [`` [@nxgt/material] DataTable: `virtual` needs `maxHeight`; the rows are not virtualized. ``](#nxgtmaterial-datatable-virtual-needs-maxheight-the-rows-are-not-virtualized)
@@ -798,11 +804,50 @@ public/assets/icons/sprites/sharp-solid.svg ← <Icon name="atom" family="sharp"
 
 Serve one sheet per style you use, from your own Font Awesome Pro kit. With Font Awesome Free (`solid.svg`, `regular.svg`, `brands.svg`), set `edition="free"` on `IconSpritesProvider`: the library's own icons (the app shell menu, `AccountMenu`, pagination…) are duotone, and they then draw from `solid.svg`.
 
+### `backdropSprite needs the icon packs your backdrops draw`
+
+**When:** `nxgt-backdrop-sprite` exits with this message, or `vite` stops at startup with it, or `nxgtMaterial({ backdropSprite: {} })` throws it (`true` is a type error, and throws the same in plain JavaScript).
+**Why:** the reduced sprite holds only the icon names you ask for, and no pack is assumed: a default would ship names your backdrops may never draw, or miss the ones they do.
+**Fix:** name the packs your `Background` draws (`icons="health"`, or the default `school`), or the names of your own `icons` list:
+
+```sh
+npx nxgt-backdrop-sprite --pack health --pack school
+npx nxgt-backdrop-sprite --icon heart-pulse --icon stethoscope
+```
+
+```ts
+nxgtMaterial({ backdropSprite: { packs: ['health'] } }) // or { icons: ['heart-pulse'] }
+```
+
+### Backdrop icons are blank with a reduced sprite
+
+**When:** `IconSpritesProvider` has `backdropSprite`, and `Background preset="icons"` draws its shapes but no icons. The network tab shows a `404` (or an HTML page) for `/sprites/backdrop.svg`, or the file loads and the icons stay empty.
+**Why:** the sprite is missing, its `href` does not match where you serve it (a different `base` or `outFile`, a sub-path deployment), or it does not hold the symbol the backdrop asks for: a name from an `icons` list or pack you did not give the build, or a style you listed in `styles` that the sprite was not built with. A symbol is `<file>--<name>` (`thin--book-open`).
+**Fix:** run `npx nxgt-backdrop-sprite --pack health --out public/sprites/backdrop.svg --base /sprites/` (or add `nxgtMaterial({ backdropSprite: { packs: ['health'] } })`), serve the file at the `href` you give the provider, and give the build every pack (`--pack`) and name (`--icon`) your backdrops use. Open the file: `grep -c "<symbol" public/sprites/backdrop.svg`, and `grep 'id="thin--book-open"'`. `IconRefError` (`base`) from the provider means the `href` is not a root-relative `.svg` path. A build that fails with "no <style> sheet" or "No Font Awesome install" names a style or package the install lacks. Copy the printed `backdropSprite={{ href, styles }}` so the styles match the build; with the string form, set `servedStyles` to the styles the sprite holds. `edition="free"` with a sprite built from Pro styles only is blank too: the Free edition asks for `regular` and `solid` symbols, so build with `--style regular --style solid`. The opposite case: a sprite built from a Free install writes each Pro-only name (`backpack`, `chevrons-left`) under its Free twin's id (`school`, `angles-left`), and the command or the build warns "Pro-only names written under their Free twin"; the Pro edition then asks for the Pro name and draws nothing, so set `edition="free"` on `IconSpritesProvider`. A `public/sprites/backdrop.svg` written by the command also shadows the plugin's sprite: use one of the two. If `nxgt-backdrop-sprite` prints "@nxgt/material-core is not built", build or reinstall `@nxgt/material-core`.
+
+### The `icons` backdrop looks different after 3.22
+
+**When:** after upgrading to 3.22, `Background preset="icons"` (or a theme that names it) draws shapes among a few icons, in one soft tint, in several styles, and the glyphs stay clear of the cards, lists and text of the page.
+**Why:** that is the new default: motif shapes and about one icon in five on an even grid (`motif.icons.ratio` 0.2, `density` `medium`), `iconMotif.colors: 'one'`, a weighted `iconStyle` of five styles, and the drop rule (a glyph whose box meets a surface, a text or a control is dropped, not moved). No prop was removed. A style whose sprite the app does not serve is dropped; with none served the scene draws Free `regular` and `solid`, so a Free-only or half-served app needs `servedStyles` or `edition="free"` on `IconSpritesProvider`.
+**Fix:** to keep what you had, pass the three props below (in a theme, the same keys under `background`). To keep the new look and shrink the download, build the reduced sprite (`npx nxgt-backdrop-sprite --pack school`). For fewer or more glyphs, `motif={{ density: 'low' }}` or a number; for no icons, `motif={{ icons: { ratio: 0 } }}`.
+
+```tsx
+<Background preset="icons" iconStyle="duotone-thin" iconMotif={{ layout: 'scatter', colors: 'classic' }} />
+```
+
+See [the previous look](guides/backgrounds.md#the-look-before-322) and [the drop rule](guides/backgrounds.md#the-drop-rule).
+
+### `defineTheme: Theme "x" background.motif: unknown key spin. Ignored.`
+
+**When:** in development, `defineTheme` from `@nxgt/material/themes` logs a line such as `Theme "x" background.motif: unknown key spin. Ignored.`, `Theme "x" background.motif: density: low, default, medium, high or a count from 1 to 600. Ignored.`, `Theme "x" background.motif: layout: not scatter, even. Ignored.`, `Theme "x" background.motif: expected an object. Ignored.` or, for a bad `motif.icons`, the reason (`… background.motif.icons.ratio: a number from 0 to 1. Ignored.`), and the setting has no effect. Nothing throws, and nothing is logged in production.
+**Why:** since 3.22 a bad key or value under a theme background's `motif` (a misspelt key, a `layout` or `density` outside its list, a bad `motif.icons`) is dropped and the rest of the theme is kept; 4.0 makes it a `ThemeDefinitionError`. Core's `defineTheme` (`@nxgt/material-core/theme/define`) drops it silently unless you pass `{ warn }`.
+**Fix:** use a known key and a valid value: `motif: { density: 'medium', layout: 'even', icons: { ratio: 0.2 } }` (`density` is `low`, `default`, `medium`, `high` or a count from 1 to 600).
+
 ### A background, an illustration or a theme tile draws no icons
 
-**When:** `Background preset="icons"`, an `Illustration`, an `EmptyState` with an `illustration`, or a `ThemePicker` tile shows its wash or its plate and no icons. The network tab shows a `404` for `/assets/icons/sprites/duotone-thin.svg` (the default style), or for the sheet of the `iconStyle` you chose. No error is thrown.
-**Why:** these icons are `<use>` references to sprite sheets your app serves; the library ships none (the Font Awesome licence does not allow it). The default style is `duotone-thin`, so a Free-only app, which has `solid.svg`, `regular.svg` and `brands.svg`, draws nothing until it asks for a Free style. A name the sheet does not hold is blank too, such as `backpack` or `books`, which exist in Pro only. A theme tile with no icons keeps its wash: that is the intended fallback, not a bug.
-**Fix:** serve the sheet (or move the base with `IconSpritesProvider`). With only the Free sheets, say so: `<IconSpritesProvider base="/assets/icons/sprites/" edition="free">` draws every style Free lacks from `solid.svg` and the Pro-only names as their Free twin, so the app shell's menu, `AccountMenu` and the rest need nothing else (do not copy `solid.svg` to `duotone.svg`). Or choose a style you serve, and give Free names:
+**When:** `Background preset="icons"`, an `Illustration`, an `EmptyState` with an `illustration`, or a `ThemePicker` tile shows its wash or its plate and no icons. The network tab shows a `404` for the sheets of the default mix of `preset="icons"` (`light.svg`, `thin.svg`, `sharp-regular.svg`, `sharp-light.svg`, `duotone-thin.svg` under `/assets/icons/sprites/`; `Illustration` and `Icon` default to `duotone-thin.svg`), or for the sheet of the `iconStyle` you chose. No error is thrown.
+**Why:** these icons are `<use>` references to sprite sheets your app serves; the library ships none (the Font Awesome licence does not allow it). `Illustration` and `Icon` default to `duotone-thin`, and `preset="icons"` draws a weighted mix of five styles (it drops the ones `IconSpritesProvider`'s `servedStyles` does not list), so a Free-only app, which has `solid.svg`, `regular.svg` and `brands.svg`, draws nothing until it asks for a Free style. A name the sheet does not hold is blank too, such as `backpack` or `books`, which exist in Pro only. A theme tile with no icons keeps its wash: that is the intended fallback, not a bug.
+**Fix:** serve the sheet (or move the base with `IconSpritesProvider`, and list the sheets you serve in its `servedStyles`). With only the Free sheets, say so: `<IconSpritesProvider base="/assets/icons/sprites/" edition="free">` draws every style Free lacks from `solid.svg` and the Pro-only names as their Free twin, so the app shell's menu, `AccountMenu` and the rest need nothing else (do not copy `solid.svg` to `duotone.svg`). Or choose a style you serve, and give Free names:
 
 ```tsx
 // Free sprites copied to public/assets/icons/sprites/solid.svg
@@ -6459,6 +6504,23 @@ const columns = [{ accessorKey: 'name', header: NameHeader }];
 **Why:** `ServerTable` cannot tell a failed fetch from an empty answer: `error` was never passed, or it was passed and never cleared (`null`) when the next answer landed, so the failure stays on screen.
 **Fix:** pass `error` while the fetch has failed, with `onRetry`, and set it back to `null` as soon as the next answer lands. See [ServerTable](components/data-table-filter-and-lists.md#servertable).
 
+### The focus falls to `<body>` after Previous / Next on a `ServerTable`
+
+Versions before `reserveActions` landed swapped a page link for a disabled
+button while the next page loaded, which dropped the focus to `<body>`
+(always on a phone's tiles). Upgrade: the control now stays, `aria-disabled`,
+and the focus moves to its counterpart when one goes (Next on the last page).
+See [Focus while paging](components/data-table-filter-and-lists.md#focus-while-paging).
+A custom `linkComponent` must render an element that can take the focus (an
+`<a href>`).
+
+### An empty gap under the `ServerTable` band while nothing is selected
+
+Versions before `reserveActions` reserved the toolbar's 68px (`header-placeholder`) for the
+bulk actions. `ServerTable` now reserves nothing. On `DataTable` itself the
+default is still `reserveActions` `true`: pass `reserveActions={false}` to get
+the same.
+
 ### The focus falls to the page after a `DataTable` bulk action
 
 **When:** a bulk action clears the selection, its buttons unmount, and the next Tab starts from the top of the page.

package/lib/backgrounds/css-react/icons-quiet.css

@@ -4,7 +4,7 @@
 	 * band is `--background-quiet` wide (42%), then the icons fade back in over
 	 * 30%. `start` and `end` follow the reading direction. A mask, not a colour:
 	 * the text underneath keeps the wash's own contrast. */
-	[data-background="icons"] > [data-scene] > :is(.ic-q-start, .ic-q-end) {
+	[data-background] > [data-scene] > :is(.ic-q-start, .ic-q-end) {
 		--nxgt-quiet-to: to right;
 		-webkit-mask-image: linear-gradient(
 			var(--nxgt-quiet-to),
@@ -17,14 +17,14 @@
 			#000 calc(var(--background-quiet, 42%) + 30%)
 		);
 	}
-	[data-background="icons"] > [data-scene] > .ic-q-end,
-	[data-background="icons"] > [data-scene]:dir(rtl) > .ic-q-start {
+	[data-background] > [data-scene] > .ic-q-end,
+	[data-background] > [data-scene]:dir(rtl) > .ic-q-start {
 		--nxgt-quiet-to: to left;
 	}
-	[data-background="icons"] > [data-scene]:dir(rtl) > .ic-q-end {
+	[data-background] > [data-scene]:dir(rtl) > .ic-q-end {
 		--nxgt-quiet-to: to right;
 	}
-	[data-background="icons"] > [data-scene] > .ic-q-center {
+	[data-background] > [data-scene] > .ic-q-center {
 		-webkit-mask-image: linear-gradient(
 			to right,
 			#000 calc(50% - var(--background-quiet, 42%) / 2 - 30%),

package/lib/backgrounds/css-react/icons-tint.css

@@ -0,0 +1,98 @@
+/* The tint of the icons scene (`iconMotif.colors`, React only): a class on the
+ * scene root. `ic-c-one` (default) draws every glyph in the primary tone
+ * mixed toward transparent, a low contrast on any surface and a soft one in
+ * dark, never bright; `ic-c-palette` spreads primary, secondary and tertiary
+ * (`k1..k3`) at the same contrast; the rules out-rank icons.css's `.ic.k1..k3` tones; `ic-c-classic` has no rule here (icons.css
+ * gives the tones at full strength). The icons read `--fa-primary-color`
+ * (duotone and the sprites' paint) and `currentColor` (the flat styles), so the
+ * tint sets both. The motif shapes of the mix sit at 0.8 of the icons' tint. */
+@layer components {
+	[data-background] > [data-scene] > :is(.ic-c-one, .ic-c-palette) {
+		--ic-soft: 46%;
+	}
+	:is(.dark, [data-theme="dark"])
+		[data-background]
+		> [data-scene]
+		> :is(.ic-c-one, .ic-c-palette),
+	[data-background]:is(.dark, [data-theme="dark"])
+		> [data-scene]
+		> :is(.ic-c-one, .ic-c-palette) {
+		--ic-soft: 44%;
+	}
+
+	/* One tint. */
+	[data-background] > [data-scene] > .ic-c-one .ic:is(.k1, .k2, .k3) {
+		--ic-tint: color-mix(
+			in oklab,
+			var(--nxgt-bg-t1) var(--ic-soft),
+			transparent
+		);
+		--fa-primary-color: var(--ic-tint);
+		--fa-secondary-color: var(--ic-tint);
+		color: var(--ic-tint);
+	}
+	[data-background] > [data-scene] > .ic-c-one :is(.k1, .k2, .k3):not(.ic) {
+		color: color-mix(
+			in oklab,
+			var(--nxgt-bg-t1) calc(var(--ic-soft) * 0.8),
+			transparent
+		);
+	}
+	[data-background] > [data-scene] > .ic-c-one :is(.ic-ln, .ic-dt) {
+		stroke: color-mix(in oklab, var(--nxgt-bg-t1) var(--ic-soft), transparent);
+		fill: none;
+	}
+	[data-background] > [data-scene] > .ic-c-one .ic-dt {
+		fill: color-mix(in oklab, var(--nxgt-bg-t1) var(--ic-soft), transparent);
+		stroke: none;
+	}
+
+	/* Three tints, the same contrast. */
+	[data-background] > [data-scene] > .ic-c-palette .ic.k1 {
+		--ic-tint: color-mix(
+			in oklab,
+			var(--nxgt-bg-c1) var(--ic-soft),
+			transparent
+		);
+	}
+	[data-background] > [data-scene] > .ic-c-palette .ic.k2 {
+		--ic-tint: color-mix(
+			in oklab,
+			var(--nxgt-bg-c2) var(--ic-soft),
+			transparent
+		);
+	}
+	[data-background] > [data-scene] > .ic-c-palette .ic.k3 {
+		--ic-tint: color-mix(
+			in oklab,
+			var(--nxgt-bg-c3) var(--ic-soft),
+			transparent
+		);
+	}
+	[data-background] > [data-scene] > .ic-c-palette .ic:is(.k1, .k2, .k3) {
+		--fa-primary-color: var(--ic-tint);
+		--fa-secondary-color: var(--ic-tint);
+		color: var(--ic-tint);
+	}
+	[data-background] > [data-scene] > .ic-c-palette .k1:not(.ic) {
+		color: color-mix(
+			in oklab,
+			var(--nxgt-bg-c1) calc(var(--ic-soft) * 0.8),
+			transparent
+		);
+	}
+	[data-background] > [data-scene] > .ic-c-palette .k2:not(.ic) {
+		color: color-mix(
+			in oklab,
+			var(--nxgt-bg-c2) calc(var(--ic-soft) * 0.8),
+			transparent
+		);
+	}
+	[data-background] > [data-scene] > .ic-c-palette .k3:not(.ic) {
+		color: color-mix(
+			in oklab,
+			var(--nxgt-bg-c3) calc(var(--ic-soft) * 0.8),
+			transparent
+		);
+	}
+}