@nxgt/material 3.8.1 → 3.9.0

package/docs/roadmap.md

@@ -190,6 +190,14 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Later
 
+- **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
+  twelve it draws today (`forbidden`, `maintenance`, `invitation`, `sign-in`
+  and `empty-inbox` are among them), added on demand.
+- **A Vue twin of icon backgrounds and illustrations** — see the `vue`
+  issue (#1422).
+
 - **Retire `tw-animate-css` in a future major** — the overlays (dialogs,
   sheets, menus, popovers, toasts) still animate with its `animate-in`,
   `fade-in` and `zoom-in`. They would move to the animation API
@@ -287,6 +295,20 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **Icon backgrounds, celestial presets and illustrations** — `Background
+  preset="icons"` draws a pattern of icons from the packs, `iconStyle` taking
+  one style or a list and `iconMotif` choosing the layout.
+  `IconSpritesProvider` serves the Font Awesome sprites from your own base (the
+  package ships none). Four celestial presets (`eclipse`, `meteor-shower`,
+  `ringed-planet`, `northern-lights`) and a `sky` overlay join the
+  backgrounds. `Illustration` draws 12 base scenes, and the health and
+  education sets (10 scenes each) come from their own subpaths,
+  `@nxgt/material/illustrations/health` and
+  `@nxgt/material/illustrations/education`; `IllustrationDefaults` sets the
+  look once for a subtree. A theme can name an icon motif, and the theme
+  picker's tile shows it. The teal preset's success hue is fixed (#1411).
+  React only. 3.9.0. ([Icon motifs](guides/icon-motifs.md))
+
 - **Themes** (in the next prerelease) — 14 ready-made themes (Lavande, the
   default, then Océan, Forêt, Ambre, Ardoise, Corail, Menthe, Prune, Sable,
   Slate, Pink, Bleu mono, Blue moon and Teal) as stylesheets,

package/docs/troubleshooting.md

@@ -31,6 +31,9 @@ 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)
+- [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)
 - [An accessibility audit reports low contrast on a badge, a button, a toast or a menu entry](#an-accessibility-audit-reports-low-contrast-on-a-badge-a-button-a-toast-or-a-menu-entry)
 - [`ARIA hidden element must not be focusable or contain focusable elements`](#aria-hidden-element-must-not-be-focusable-or-contain-focusable-elements)
 - [An accessibility audit reports low contrast on a tonal or outlined button, a selected list tile or a hovered badge link](#an-accessibility-audit-reports-low-contrast-on-a-tonal-or-outlined-button-a-selected-list-tile-or-a-hovered-badge-link)
@@ -418,6 +421,10 @@ words in your error.
 - [`Refused to load the font 'https://fonts.gstatic.com/…' because it violates the following Content Security Policy directive: "font-src 'self'"`](#refused-to-load-the-font-httpsfontsgstaticcom-because-it-violates-the-following-content-security-policy-directive-font-src-self)
 - [`Refused to evaluate a string as JavaScript because 'unsafe-eval' is not an allowed source of script`](#refused-to-evaluate-a-string-as-javascript-because-unsafe-eval-is-not-an-allowed-source-of-script)
 
+**Illustrations**
+
+- [`Illustration: … Drawing the built-in art instead.`](#illustration--drawing-the-built-in-art-instead)
+
 - [Reporting a bug](#reporting-a-bug)
 
 ---
@@ -767,7 +774,7 @@ shows a `404` for `/assets/icons/sprites/<style>.svg`.
 **Why:** `Icon` references a sprite sheet at a root-relative URL on your own
 origin. This package does not ship the Font Awesome Pro sheets, because the
 licence does not allow redistributing them. A missing sheet renders nothing,
-with no fallback.
+with no fallback. If you moved the sheets, wrap the app in `IconSpritesProvider` so `Icon` reads the new base.
 **Fix:**
 
 ```text
@@ -778,6 +785,44 @@ 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.
 
+### 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`), or choose a style you serve, and give Free names where you have only Free:
+
+```tsx
+// Free sprites copied to public/assets/icons/sprites/solid.svg
+<Background preset="icons" icons="health" iconStyle="solid" />
+<Illustration scene="empty" iconStyle="solid" hero="box-open" />
+<IllustrationDefaults iconStyle="solid" sets={[EDUCATION_SCENES]}>
+  <EmptyState illustration="no-students" title="No students yet" />
+</IllustrationDefaults>
+```
+
+The Pro-only suggested names and their Free neighbours are in the [icon motifs guide](guides/icon-motifs.md#free-fallbacks-for-pro-only-names).
+
+### `Background: icons cannot be drawn (…); drawing "scatter-icons" instead.`
+
+**When:** a development-only `console.warn`, once, from `<Background preset="icons">` (or a theme that names the preset). The background shows stroked glyphs (stars, sparkles, squiggles) instead of your icons.
+**Why:** the builder refused the input: an unknown pack name (`icons="medical"`), a name that is not a Font Awesome name (`'Graduation Cap'`), more than 48 icons, an `iconStyle` list of more than 8, or a family and style Font Awesome 7.3.1 does not draw. The page does not break; production builds draw the fallback silently.
+**Fix:** use one of the six packs, names in the form `graduation-cap`, at most 48 icons, and a style from the icon-motifs guide:
+
+```tsx
+<Background preset="icons" icons="health" />            {/* a pack */}
+<Background preset="icons" icons={['rocket', 'star']} /> {/* or names */}
+```
+
+### `IconRefError` from `IconSpritesProvider`
+
+**When:** rendering `<IconSpritesProvider base="…">` throws `IconRefError` with code `base`.
+**Why:** the base is a URL, a `//host` path, or holds `..` or `:`. Sprites are only loaded from your own origin.
+**Fix:** pass a root-relative path, and serve the sheets there:
+
+```tsx
+<IconSpritesProvider base="/static/icons/">{children}</IconSpritesProvider>
+```
+
 ### The light and dark neutrals turned violet after upgrading to 3.6
 
 **When:** after `@nxgt/material` 3.6, the page, cards, borders and muted text
@@ -6810,13 +6855,13 @@ How the presets work is in the [Backgrounds guide](guides/backgrounds.md).
 ### `Background: preset "<id>" is not available in this library yet; drawing "gradient".`
 
 **When:** in development (not when `NODE_ENV` is `production`), the first time a `Background` from `@nxgt/material/backgrounds` gets a `preset` that this library does not draw yet, or a typo from JavaScript. It is printed once per id.
-**Why:** `BACKGROUND_PRESETS` lists the 45 presets; this library draws the ones in `AVAILABLE_BACKGROUND_PRESETS`. Any other id draws the gradient.
+**Why:** `BACKGROUND_PRESETS` lists the 50 presets; this library draws all of them, the ones in `AVAILABLE_BACKGROUND_PRESETS`. Any other id (a typo from JavaScript) draws the gradient.
 **Fix:** use an available preset:
 
 ```ts
 import { AVAILABLE_BACKGROUND_PRESETS } from '@nxgt/material/backgrounds';
 
-console.log(AVAILABLE_BACKGROUND_PRESETS); // all 45 ids: 'gradient', 'grain', 'mesh', 'aurora', …, 'sport', 'moon'
+console.log(AVAILABLE_BACKGROUND_PRESETS); // the 50 ids it draws: 'gradient', 'grain', 'mesh', 'aurora', …, 'moon', 'eclipse', …, 'northern-lights', 'icons'
 ```
 
 ### A preset `Background` looks bare, with no error
@@ -6828,7 +6873,8 @@ console.log(AVAILABLE_BACKGROUND_PRESETS); // all 45 ids: 'gradient', 'grain', '
 ```ts
 import '@nxgt/material/backgrounds.css'; // every preset
 // or one file: '@nxgt/material/backgrounds/<preset>.css'
-// (floating and scatter-icons also need drift.css, which their file imports)
+// (floating and scatter-icons also need drift.css, which their file imports;
+// the four celestial presets and the `sky` prop share backgrounds/celestial.css)
 ```
 
 ### My gradient colour override stopped working
@@ -7156,6 +7202,25 @@ import { z } from 'zod';
 z.config({ jitless: true });
 ```
 
+## Illustrations
+
+### `Illustration: … Drawing the built-in art instead.`
+
+**When:** a development-only `console.warn`, once per message, from an `Illustration` (or an `EmptyState` / `ErrorState` with `illustration`) that cannot be built. The page does not break: the built-in art of the scene's kind is drawn, and production builds do it silently.
+**Why:** the scene id is in no table (`"patient-record" is not a scene of the table`), an icon name is not valid, or the style is not one Font Awesome 7.3.1 draws. A domain id such as `patient-record` (health) or `classroom` (education) is only a scene when its set is registered; in an `EmptyState`, `illustration="no-patients"` or `"no-students"` is otherwise drawn as text.
+**Fix:** register the set once for the subtree, or pass it to the one `Illustration`; and take `iconStyle` from the 37 sprite file names (a bad name is a type error):
+
+```tsx
+import { EDUCATION_SCENES } from '@nxgt/material/illustrations/education';
+import { HEALTH_SCENES } from '@nxgt/material/illustrations/health';
+
+<IllustrationDefaults sets={[HEALTH_SCENES, EDUCATION_SCENES]}>
+  <EmptyState illustration="no-patients" />
+</IllustrationDefaults>;
+
+<Illustration scene="patient-record" scenes={HEALTH_SCENES} iconStyle="duotone-light" />;
+```
+
 ---
 
 ## Reporting a bug

package/lib/backgrounds/backgrounds.css

@@ -51,6 +51,10 @@
 @import "./css-react/sport.css";
 /* the moon (React only) */
 @import "./css-react/moon.css";
+/* the celestial presets and the sky overlay (React only) */
+@import "./css-react/celestial.css";
+/* icons (React only) */
+@import "./css-react/icons.css";
 /* motifs */
 @import "./css/motifs.css";
 @import "./css/shapes.css";