@nxgt/material 3.8.0 → 3.9.0

package/docs/guides/illustrations.md

@@ -0,0 +1,172 @@
+# Illustrations
+
+`@nxgt/material/illustrations` draws the **state illustrations**: a hero icon
+on a Material 3 Expressive plate, two to four satellite icons around it, a
+dashed ring and a few sparkles. There are twelve scenes: `empty`, `no-results`,
+`not-found`, `error`, `offline`, `success`, `welcome`, `forbidden`,
+`maintenance`, `invitation`, `sign-in` and `empty-inbox`, and two domain sets of
+ten more each, health and education, in their own entries ([health](#scene-sets-the-health-scenes) and [education](#scene-sets-the-education-scenes)). The icons are
+[Font Awesome](https://fontawesome.com) sprites **your app serves** (see
+[Icons](../getting-started.md#icons)): the package ships no icon artwork, so it
+works with the sprites your licence covers. The [icon motifs guide](icon-motifs.md) shows them next to the icon backgrounds, the sky and the themes, and lists the suggested names that are Pro only, with Free neighbours.
+
+Colours are the theme's tones, light and dark, painted by classes in
+`styles.css` (no inline `style`, so a strict CSP is satisfied). The server and
+the browser render the same markup.
+
+## Draw one
+
+```tsx
+import { Illustration } from '@nxgt/material/illustrations';
+
+<Illustration scene="empty" size="lg" title="An empty inbox" />
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `scene` | `IllustrationScene`, or an id of `scenes` | required | which scene (`ILLUSTRATION_SCENES` lists the twelve) |
+| `scenes` | a `SceneTable` | the twelve | a domain's set, such as `HEALTH_SCENES` or `EDUCATION_SCENES`: `scene` is then one of its ids (or register it with `IllustrationDefaults` `sets`). Pass a stable reference (a module constant), not a table built in render. A table of your own uses `SceneRow` and `SceneTable` from `@nxgt/material-core/illustrations` |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 120, 190 or 280 px wide, 4:3, never wider than its container |
+| `title` | `string` | none | the accessible name: the picture becomes `role="img"` with an `aria-label`. Without it the illustration is decorative and hidden from assistive technology. It is never a `<title>` element |
+| `animated` | `boolean` | `false` | the satellites drift and the sparkles twinkle, slowly. Nothing moves under `prefers-reduced-motion` |
+| `hero` | `string \| IconRef` | the scene's | the main icon, a name (`'graduation-cap'`) or `{ name, family?, type? }` |
+| `satellites` | `(string \| IconRef)[]` | the scene's | up to four icons around the hero |
+| `style` | the DOM `style` of the wrapper, as on any `div`; the look of the icons is `iconStyle` | none | the library's own markup holds no `style` attribute |
+| `iconStyle` | a style, or a list of up to eight | `'duotone-thin'` | the icon style: `{ family, type }` or the sprite's file name (`'sharp-duotone-light'`, `'solid'`). Given a list, each icon takes one by a seeded pick. An `IconRef` with its own `family` or `type` wins |
+| `tone` | `'primary' \| 'secondary' \| 'tertiary' \| 'error' \| 'warning' \| 'success'` | the scene's | the colour of the plate and the hero |
+| `duotone` | `'opacity' \| 'tones'` | `'opacity'` | duotone styles: the second layer is the same tone, fainter, or another tone |
+
+The rest of the props go to the wrapping `div` (`data-slot="illustration"`,
+with `data-scene`, `data-size` and `data-animated`). A bad icon name or style
+never crashes the page: outside production it warns once in the console, and
+the scene's built-in art is drawn instead.
+
+The sprites are read from `/assets/icons/sprites/`, or from the base of the
+nearest `IconSpritesProvider`. An icon whose name the sprite does not hold is
+blank: keep to names every style you use has (the suggested ones are the
+`SUGGESTED_ICONS` table, hero first).
+
+The plate's shape loads on demand: the illustration is a disc until it
+arrives, in a box of the same size, so the page does not move. A streaming
+server render includes the plate; `renderToString` sends the disc and the
+browser draws the plate once the chunk has loaded.
+
+## Use them in the states
+
+`EmptyState`, `ErrorState` and the `DataTable` empty row draw today's built-in
+art unless you ask:
+
+```tsx
+import { EmptyState } from '@nxgt/material/components';
+
+<EmptyState kind="search" illustration />          {/* the kind's scene */}
+<EmptyState kind="empty" illustration="welcome" />  {/* a scene by name */}
+```
+
+`illustration` takes a scene id or `true` (the kind's scene: `empty`,
+`search` is `no-results`, `not-found`, `offline`, `generic` is `error`,
+`unauthorized` is `forbidden`, `maintenance`) as well as a
+node or `false`. A scene is drawn at `md` in the default size and at `sm` in a
+`compact` one; the `inline` row keeps its icon well. A string that is not a
+scene id is a node, as before (so a string equal to a scene id, such as
+`"error"`, now draws the scene). The scene engine loads only when a scene is
+drawn: a state that keeps the built-in art costs nothing more.
+
+A table's empty row takes `emptyIllustration`, a scene id (both states) or
+`true` (`empty`, and `no-results` when filtered). It dresses the default empty
+state only, never your own `empty` or `emptyFiltered`.
+
+## Scene sets: the health scenes
+
+`@nxgt/material/illustrations/health` holds ten scenes for a health app:
+`patient-record`, `consultation`, `appointment`, `lab-sample`, `prescription`,
+`vaccination`, `hospitalisation`, `emergency`, `no-patients` and `lab-results`.
+Register the set once, below your `IllustrationDefaults`, and its ids work
+everywhere a scene id does:
+
+```tsx
+import { Illustration, IllustrationDefaults } from '@nxgt/material/illustrations';
+import { HEALTH_SCENES } from '@nxgt/material/illustrations/health';
+import { DataTable, EmptyState, ErrorState } from '@nxgt/material/components';
+
+<IllustrationDefaults sets={[HEALTH_SCENES]}>
+  <Illustration scene="patient-record" title="Patient record" />
+  <EmptyState illustration="no-patients" title="No patients yet" />
+  <ErrorState kind="generic" illustration="emergency" />
+  <DataTable data={rows} columns={columns} emptyIllustration="no-patients" />
+</IllustrationDefaults>
+```
+
+`sets` takes any number of `SceneTable`s. A base id wins over a set's id, and
+a `scenes` prop on one `Illustration` (`<Illustration scene="no-patients"
+scenes={HEALTH_SCENES} />`) wins over the provider, so a single scene needs no
+provider. The ids are typed: importing the health entry adds them to `SceneId`
+(module augmentation of `IllustrationSceneRegistry`; `RegisteredScene` is the union of the imported sets' ids), so `scene="no-patients"`
+type-checks in an app that imports it and `scene="bogus"` does not. An id that no
+registered set holds draws the built-in art and warns once outside production;
+in a state, a string that is not a registered id is a node, as before (so the
+set must be registered for the string shorthand). An app that never imports the
+subpath does not carry the table. A table of your own is a `SceneTable`
+(`SceneRow` from `@nxgt/material-core/illustrations`), passed through `sets` or
+`scenes`; its ids are not in `SceneId`, so type them with the `scenes` prop. `HEALTH_SUGGESTED_ICONS` (like `SUGGESTED_ICONS`) lists the icon names the set draws, hero first.
+
+## Scene sets: the education scenes
+
+`@nxgt/material/illustrations/education` holds ten scenes for a school app:
+`classroom`, `homework`, `exam-grades`, `timetable`, `attendance`,
+`enrolment`, `library`, `graduation`, `no-students` and `report-card`. It works
+exactly like the health set above, and the two register side by side:
+
+```tsx
+import { Illustration, IllustrationDefaults } from '@nxgt/material/illustrations';
+import { EDUCATION_SCENES } from '@nxgt/material/illustrations/education';
+import { HEALTH_SCENES } from '@nxgt/material/illustrations/health';
+import { EmptyState } from '@nxgt/material/components';
+
+<IllustrationDefaults sets={[EDUCATION_SCENES, HEALTH_SCENES]}>
+  <Illustration scene="classroom" title="Classroom" />
+  <EmptyState illustration="no-students" title="No students yet" />
+</IllustrationDefaults>
+```
+
+Importing the entry adds the ids to `SceneId`; `EDUCATION_SUGGESTED_ICONS` lists
+the icon names the set draws, hero first. Some of them (`backpack`,
+`clipboard-list-check`, `books`, `file-chart-column`) are Font Awesome Pro
+icons: serve a Pro sprite, or pass `icons` with Free neighbours.
+
+## Turn them on for an app
+
+`IllustrationDefaults` opts a subtree in: every default-size `EmptyState` and
+`ErrorState` below it draws its scene, without a prop on each.
+
+```tsx
+import { IllustrationDefaults } from '@nxgt/material/illustrations';
+
+<IllustrationDefaults icons="suggested" iconStyle="duotone-light">
+  <App />
+</IllustrationDefaults>
+```
+
+| Prop | Effect |
+| --- | --- |
+| `icons` | `'suggested'`: every state draws its scene with the suggested icons. A table `{ empty: { hero, satellites }, … }`: those scenes are drawn with those icons (a field you leave out keeps the suggested one), the others keep the built-in art. Without `icons` only `iconStyle` is set |
+| `iconStyle` | the icon style of every `Illustration` below; a prop on one wins |
+| `sets` | scene sets to register (`[HEALTH_SCENES, EDUCATION_SCENES]`): their ids work in `Illustration`, a state's `illustration` and `emptyIllustration`; `icons` may name them too |
+
+An `illustration` prop always wins over the provider (`false` hides the
+media), and `icon` too: a state given an `icon` keeps its well. Without the
+provider nothing changes for an app: the default art is exactly what it was.
+Mount the provider and `IconSpritesProvider` where your sprites are known,
+typically at the root.
+
+## Styling
+
+The look is the `ill-*` classes of `styles.css`: `ill-<tone>` on the root,
+`ill-plate`, `ill-ring`, `ill-hero`, `ill-sat` and `ill-spark`. Override them
+after the stylesheet, or set `--primary-text`, `--secondary-text` and
+`--tertiary-text` (the tone colours are read from the `--<tone>-text` tokens,
+light and dark). The core builder (`@nxgt/material-core/illustrations`,
+[reference](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/illustrations.md))
+has the scene as data, for a server that draws its own markup.
+
+**Storybook:** `Feedback & status/Illustration`

package/docs/guides/themes.md

@@ -27,6 +27,41 @@ A module exports its themes as the default export (one theme or an array) or as
 named exports. The seeds, `extends`, `tones`, `fonts`, `radius` and `tokens` are
 documented in [`@nxgt/material-core`'s themes page](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/theme.md).
 
+## Icon motifs in a theme
+
+A theme can name an icon motif, so the whole app is dressed in the pack that
+fits it, with no prop anywhere:
+
+```ts
+// src/themes/sante.ts
+import { defineTheme, menthe } from '@nxgt/material/themes';
+
+export default defineTheme({
+  name: 'sante',
+  label: 'Santé',
+  extends: menthe,
+  background: {
+    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 up to 8
+    iconMotif: { layout: 'constellation', duotone: 'opacity' },
+    sky: 'northern-lights', // optional: the moon or a celestial preset over the icons
+  },
+});
+```
+
+- `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).
+- `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.
+
 ## Generate the files
 
 With Vite:

package/docs/guides/theming.md

@@ -1180,7 +1180,7 @@ import { ThemePicker } from '@nxgt/material/theme-picker';
 <ThemePicker layout="list" showBackground={false} />;
 ```
 
-The tiles' stylesheet is opt-in (about 3.3 KB gzipped), so an app that does not
+The tiles' stylesheet is opt-in (about 3.8 KB gzipped; a theme's icon motif shows in its tile, see [Icon motifs in a theme](themes.md#icon-motifs-in-a-theme)), so an app that does not
 use the picker does not ship it; `styles.css` does not carry it.
 
 Pass `themes` to choose among fewer or to add an app theme, `value` and