@nxgt/material 3.8.1 → 3.9.0

package/dist/lib/backgrounds/background/partials/use-icons-scene.d.ts

@@ -0,0 +1,22 @@
+import { BackgroundPreset, IconMotifOptions, IconStyleInput } from '@nxgt/material-core/backgrounds';
+import { IconsInput } from '@nxgt/material-core/icons';
+import { IconsSceneProps } from './icons-scene.js';
+type IconsSceneInput = {
+    icons: IconsInput | undefined;
+    iconStyle: IconStyleInput | undefined;
+    iconMotif: IconMotifOptions | undefined;
+    seed: number;
+    animated: boolean;
+};
+/**
+ * The `icons` preset's props for its lazy scene, and the preset to draw. The
+ * `icons` the builder cannot draw (an unknown pack, a name that is not one,
+ * more than 48, an unknown style) draw `scatter-icons`, with a warning outside
+ * production. Only core's `/icons` references are read here. The props are
+ * keyed on strings, so a new object with the same values is the same scene.
+ */
+export declare function useIconsScene(resolved: BackgroundPreset, { icons, iconStyle, iconMotif, seed, animated }: IconsSceneInput): {
+    preset: BackgroundPreset;
+    iconsScene: IconsSceneProps | undefined;
+};
+export {};

package/dist/lib/backgrounds/background/types.d.ts

@@ -1,4 +1,5 @@
-import { BackgroundIntensity, BackgroundTone, MoonOptions, MotifOptions } from '@nxgt/material-core/backgrounds';
+import { BackgroundIntensity, BackgroundTone, IconMotifOptions, IconStyleInput, MoonOptions, MotifOptions, SkyPreset } from '@nxgt/material-core/backgrounds';
+import { IconsInput } from '@nxgt/material-core/icons';
 import { ComponentProps } from 'react';
 import { AvailableBackgroundPreset } from './available.js';
 export interface BackgroundProps extends ComponentProps<'div'> {
@@ -25,12 +26,37 @@ export interface BackgroundProps extends ComponentProps<'div'> {
      * `halftone`, `truchet`, `floating` and `scatter-icons`, each the options
      * it uses. A new object with the same values is the same scene. */
     motif?: MotifOptions;
-    /** What the `moon` preset draws beside `motif`'s `size` and `density`:
+    /** What the `moon` preset, the celestial presets and a `sky` draw beside `motif`'s `size` and `density`:
      * `position` (the moon's centre as fractions of the container, default
      * `{ x: 0.8, y: 0.2 }`), `phase` (the crescent's thickness, 0.3 fat to 0.8
      * thin, default `0.78`) and `halo` (its radius in moons, default `2.6`).
      * A new object with the same values is the same scene. */
     moon?: MoonOptions;
+    /** A sky drawn over the preset, before the grain: `'moon'` or `'eclipse'`,
+     * `'meteor-shower'`, `'ringed-planet'`, `'northern-lights'`. It reads the same
+     * `motif` (`size`, `density`) but not `moon` (those options stay with the
+     * preset): its body sits at its own default place, moved to the other side
+     * when the preset's moon or celestial body would be within a fifth of the
+     * width, and its stars follow `seed + 1`. Its ids are apart from the preset's. Its builder loads on demand, so it fills in after the first
+     * paint. Needs `@nxgt/material/backgrounds/celestial.css` (in `backgrounds.css`). */
+    sky?: SkyPreset;
+    /** The `icons` preset: a pack's name (`'school'`, `'health'`, `'finance'`,
+     * `'travel'`, `'nature'`, `'tech'`) or up to 48 icon names and
+     * `{ name, family?, type? }` references. Default: the `school` pack. The
+     * sprites are files your app serves (see `IconSpritesProvider`). A value the
+     * builder cannot draw draws `scatter-icons`, with a warning outside
+     * production. */
+    icons?: IconsInput;
+    /** The `icons` preset: the family and style of the icons that name none, one
+     * (`{ family?, type? }` or a sprite file's name such as `'sharp-light'`) or a
+     * list of at most 8, each icon taking one with the seed. Default: duotone
+     * thin. Keep a list to styles that share the names you use. */
+    iconStyle?: IconStyleInput;
+    /** The `icons` preset: `layout` (`'scatter'`, `'grid'`, `'constellation'`,
+     * `'drift'`), `sizeRange`, `rotation`, `duotone` (`'opacity'` or `'tones'`),
+     * `secondaryOpacity` and `calm`. A new object with the same values is the
+     * same scene. */
+    iconMotif?: IconMotifOptions;
     /** `'viewport'` is the viewport's size (as in `/components`);
      * `'container'` fills its parent, which needs a definite height. A
      * `className` overrides either. */

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

@@ -9,6 +9,6 @@
  * name (same props, plus every preset's), with the types and the engine's
  * tables re-exported from `@nxgt/material-core/backgrounds` by name.
  */
-export { BACKGROUND_INTENSITIES, BACKGROUND_PRESETS, BACKGROUND_TONES, type BackgroundIntensity, type BackgroundPreset, type BackgroundTone, MOTIF_SHAPES, MOTIF_SHAPES_ALL, type MoonOptions, type MotifDensity, type MotifOptions, type MotifShape, type MotifSize, type OpacitySpread, type PresetInfo, SHIPPED_BACKGROUND_PRESETS, type ShapeFill, type ShippedBackgroundPreset, } from '@nxgt/material-core/backgrounds';
+export { BACKGROUND_INTENSITIES, BACKGROUND_PRESETS, BACKGROUND_TONES, type BackgroundIntensity, type BackgroundPreset, type BackgroundTone, type CelestialPreset, type IconLayout, type IconMotifOptions, type IconStyleInput, type IconStyleRef, type IconsInput, MOTIF_SHAPES, MOTIF_SHAPES_ALL, type MoonOptions, type MotifDensity, type MotifOptions, type MotifShape, type MotifSize, type OpacitySpread, type PresetInfo, SHIPPED_BACKGROUND_PRESETS, type ShapeFill, type ShippedBackgroundPreset, type SkyPreset, } from '@nxgt/material-core/backgrounds';
 export { Background, type BackgroundProps } from './background/index.js';
 export { AVAILABLE_BACKGROUND_PRESETS, type AvailableBackgroundPreset, } from './background/available.js';

package/dist/lib/components/ui/collections/data-table/empty-types.d.ts

@@ -0,0 +1,20 @@
+import { SceneId } from '../../feedback/state-frame/scene-registry.js';
+import { DataTableEmpty } from './partials/data-table-empty-row.js';
+/** The props of `DataTable` that say what an empty table shows. */
+export interface DataTableEmptyProps {
+    /** Shown, spanning every visible column, when the table has no row to show.
+     * A function is told whether rows exist but none matches the filters.
+     * Without it (or when it renders nothing) the default is a compact
+     * `EmptyState`. Precedence: `emptyFiltered` when filtered, else `empty`,
+     * else the default. */
+    empty?: DataTableEmpty;
+    /** Shown instead of `empty` when the table is filtered: rows exist but the
+     * filters hide every one of them, or `filtered` says so. A function is
+     * told `{ filtered: true }`. Renders nothing: `empty`, then the default. */
+    emptyFiltered?: DataTableEmpty;
+    /** Draws the default empty state with an icon illustration
+     * (`@nxgt/material/illustrations`): a scene id (`'empty'`, `'no-results'`…,
+     * for both states) or `true` (`'empty'`, and `'no-results'` when filtered).
+     * Not used for your own `empty` or `emptyFiltered`. */
+    emptyIllustration?: SceneId | true;
+}

package/dist/lib/components/ui/collections/data-table/layout-types.d.ts

@@ -32,3 +32,15 @@ export type DataTableItem = {
     /** Why it cannot (`rowSelectionDisabledReason`), when it is locked. */
     reason?: string;
 };
+/** `DataTable`'s `virtual`: `true`, or the virtualizer's sizes. */
+export type DataTableVirtual = boolean | {
+    /** A row's height before it is measured, in pixels, without the gap between rows. Default 36, a comfortable row. */
+    estimateSize?: number;
+    /** Rows rendered past each edge of the visible ones. Default 8. */
+    overscan?: number;
+    /** Rows the server (and the first client render) show, before the
+     * table virtualizes. Default 50. */
+    ssrRows?: number;
+};
+/** How tight a `DataTable`'s rows are. */
+export type DataTableDensity = 'comfortable' | 'compact';

package/dist/lib/components/ui/collections/data-table/partials/data-table-body.d.ts

@@ -1,4 +1,5 @@
 import { Table as ReactTable, RowData } from '@tanstack/react-table';
+import { SceneId } from '../../../feedback/state-frame/scene-registry.js';
 import { DataTableFeatures } from '../features.js';
 import { DataTableVirtualOptions } from '../virtual-option.js';
 import { DataTableEmpty } from './data-table-empty-row.js';
@@ -11,6 +12,7 @@ interface DataTableBodyProps<TData extends RowData> extends Omit<DataTableRowPro
     loadingRows?: number;
     empty?: DataTableEmpty;
     emptyFiltered?: DataTableEmpty;
+    emptyIllustration?: SceneId | true;
     /** The empty state is "nothing matches" (`emptyFiltered`). */
     filtered: boolean;
     /** The rows virtualized (`DataTable`'s resolved `virtual`). */
@@ -21,5 +23,5 @@ interface DataTableBodyProps<TData extends RowData> extends Omit<DataTableRowPro
 /** `DataTable`'s rows (`DataTableRow`, or `DataTableVirtualRows` with
  * `virtual`); skeleton rows while loading with no row to show; or the empty
  * state. */
-export declare function DataTableBody<TData extends RowData>({ table, renderExpandedRow, getRowHref, onRowClick, linkComponent, loading, loadingRows, empty, emptyFiltered, filtered, virtual, headerRows, }: DataTableBodyProps<TData>): import("react").JSX.Element;
+export declare function DataTableBody<TData extends RowData>({ table, renderExpandedRow, getRowHref, onRowClick, linkComponent, loading, loadingRows, empty, emptyFiltered, emptyIllustration, filtered, virtual, headerRows, }: DataTableBodyProps<TData>): import("react").JSX.Element;
 export {};

package/dist/lib/components/ui/collections/data-table/partials/data-table-empty-row.d.ts

@@ -1,4 +1,5 @@
 import { ReactNode } from 'react';
+import { SceneId } from '../../../feedback/state-frame/scene-registry.js';
 /** What `DataTable`'s `empty` render function is told: `filtered` is `true`
  * when there is data but no row matches the column filters, or when the
  * table's `filtered` prop says so. */
@@ -12,9 +13,10 @@ export type DataTableEmpty = ReactNode | ((state: DataTableEmptyState) => ReactN
  * table's hidden status when filtered). Content that renders nothing falls
  * through to the next. Shared by the table's empty row and the cards' empty
  * block. */
-export declare function DataTableEmptyContent({ empty, emptyFiltered, filtered, }: {
+export declare function DataTableEmptyContent({ empty, emptyFiltered, emptyIllustration, filtered, }: {
     empty?: DataTableEmpty;
     emptyFiltered?: DataTableEmpty;
+    emptyIllustration?: SceneId | true;
     filtered: boolean;
 }): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element;
 /** `DataTable`'s "nothing here" row: one `TableEmpty` cell spanning every
@@ -26,9 +28,10 @@ export declare function DataTableEmptyContent({ empty, emptyFiltered, filtered,
  * box takes 4px off each side and sticks 4px in, or a wide empty state would
  * stick out of the region by the container's padding. It carries
  * `data-filtered` when filtered. */
-export declare function DataTableEmptyRow({ columnCount, empty, emptyFiltered, filtered, }: {
+export declare function DataTableEmptyRow({ columnCount, empty, emptyFiltered, emptyIllustration, filtered, }: {
     columnCount: number;
     empty?: DataTableEmpty;
     emptyFiltered?: DataTableEmpty;
+    emptyIllustration?: SceneId | true;
     filtered: boolean;
 }): import("react").JSX.Element;

package/dist/lib/components/ui/collections/data-table/partials/layouts/data-table-items-empty.d.ts

@@ -4,8 +4,8 @@ import { DataTableProps } from '../../types.js';
 /** The cards' (and tiles') empty state, in the list's place and outside any
  * `<ul>`: the `empty` / `emptyFiltered` content, which is also the focus
  * target of an empty page (a bulk action that emptied it). */
-export declare function DataTableItemsEmpty<TData extends RowData>({ listRef, focusable, filtered, empty, emptyFiltered, }: {
+export declare function DataTableItemsEmpty<TData extends RowData>({ listRef, focusable, filtered, empty, emptyFiltered, emptyIllustration, }: {
     listRef: Ref<HTMLElement>;
     focusable: boolean;
     filtered: boolean;
-} & Pick<DataTableProps<TData>, 'empty' | 'emptyFiltered'>): import("react").JSX.Element;
+} & Pick<DataTableProps<TData>, 'empty' | 'emptyFiltered' | 'emptyIllustration'>): import("react").JSX.Element;

package/dist/lib/components/ui/collections/data-table/types.d.ts

@@ -1,30 +1,18 @@
 import { ColumnDef, Row, RowData, RowSelectionState, SortingState } from '@tanstack/react-table';
 import { KeyboardEvent, MouseEvent, ReactNode, Ref } from 'react';
+import { DataTableEmptyProps } from './empty-types.js';
 import { DataTableFeatures } from './features.js';
-import { DataTableItem, DataTableLayoutProp } from './layout-types.js';
-import { DataTableEmpty } from './partials/data-table-empty-row.js';
+import { DataTableDensity, DataTableItem, DataTableLayoutProp, DataTableVirtual } from './layout-types.js';
 import { DataTableLinkComponent, DataTableServerPagination } from './server-pagination.js';
 import { DataTableSlot, DataTableTable } from './slots.js';
-export type { DataTableItem, DataTableItemTitleElement, DataTableLayout, DataTableLayoutProp, DataTableResponsiveLayout, } from './layout-types.js';
+export type { DataTableDensity, DataTableItem, DataTableItemTitleElement, DataTableLayout, DataTableLayoutProp, DataTableResponsiveLayout, DataTableVirtual, } from './layout-types.js';
 export type { DataTableLinkComponent, DataTableLinkProps, DataTablePageTarget, DataTableServerPagination, } from './server-pagination.js';
 export type { DataTableControls, DataTableSlot, DataTableTable, } from './slots.js';
 export type DataTableOptions = {
     showPage?: boolean;
     showSelected?: boolean;
 };
-/** `DataTable`'s `virtual`: `true`, or the virtualizer's sizes. */
-export type DataTableVirtual = boolean | {
-    /** A row's height before it is measured, in pixels, without the gap between rows. Default 36, a comfortable row. */
-    estimateSize?: number;
-    /** Rows rendered past each edge of the visible ones. Default 8. */
-    overscan?: number;
-    /** Rows the server (and the first client render) show, before the
-     * table virtualizes. Default 50. */
-    ssrRows?: number;
-};
-/** How tight a `DataTable`'s rows are. */
-export type DataTableDensity = 'comfortable' | 'compact';
-export interface DataTableProps<TData extends RowData> {
+export interface DataTableProps<TData extends RowData> extends DataTableEmptyProps {
     columns: ColumnDef<DataTableFeatures, TData, any>[];
     data: TData[];
     className?: string;
@@ -75,16 +63,6 @@ export interface DataTableProps<TData extends RowData> {
     loading?: boolean;
     /** How many skeleton rows `loading` shows. Default: the page size. */
     loadingRows?: number;
-    /** Shown, spanning every visible column, when the table has no row to show.
-     * A function is told whether rows exist but none matches the filters.
-     * Without it (or when it renders nothing) the default is a compact
-     * `EmptyState`. Precedence: `emptyFiltered` when filtered, else `empty`,
-     * else the default. */
-    empty?: DataTableEmpty;
-    /** Shown instead of `empty` when the table is filtered: rows exist but the
-     * filters hide every one of them, or `filtered` says so. A function is
-     * told `{ filtered: true }`. Renders nothing: `empty`, then the default. */
-    emptyFiltered?: DataTableEmpty;
     /** Whether the rows are filtered, overriding what the table sees (data,
      * but no row left by the column filters). For server-side data (`manual`),
      * which cannot tell: `true` when the page's query has a search or a

package/dist/lib/components/ui/feedback/empty-state/empty-state.d.ts

@@ -1,13 +1,18 @@
 import { EmptyStateKind } from '@nxgt/material-core/states';
 import { ComponentProps, ReactNode } from 'react';
-import { StateFrameSize, StateHeadingLevel } from '../state-frame/state-frame.js';
+import { StateFrameSize, StateHeadingLevel, StateIllustrationProp } from '../state-frame/state-frame.js';
 export type { EmptyStateKind } from '@nxgt/material-core/states';
 export interface EmptyStateProps extends Omit<ComponentProps<'div'>, 'title'> {
     /** What is absent: `empty` (nothing yet, the default), `search`, `not-found`, `unauthorized`. The error kinds are `ErrorState`'s. */
     kind?: EmptyStateKind;
     size?: StateFrameSize;
-    /** Replaces the built-in illustration or icon; `false` shows no media. */
-    illustration?: ReactNode | false;
+    /**
+     * Replaces the built-in illustration or icon; `false` shows no media. A
+     * scene id (`'empty'`, `'no-results'`, `'not-found'`, `'error'`, `'offline'`,
+     * `'success'`, `'welcome'`) or `true` (the kind's scene) draws an icon
+     * illustration, see `@nxgt/material/illustrations`.
+     */
+    illustration?: StateIllustrationProp;
     icon?: ReactNode;
     title?: ReactNode;
     /** Makes the title a heading of this level; see `StateFrame`. */

package/dist/lib/components/ui/feedback/error-state/error-state.d.ts

@@ -1,7 +1,7 @@
 import { ErrorDetail, ErrorStateKind } from '@nxgt/material-core/states';
 import { ComponentProps, ReactNode } from 'react';
 import { ContentSlot } from '../../../../lib/ui.utils.js';
-import { StateHeadingLevel } from '../state-frame/state-frame.js';
+import { StateHeadingLevel, StateIllustrationProp } from '../state-frame/state-frame.js';
 export type ErrorStateProps = Omit<ComponentProps<'div'>, 'title'> & {
     /** Which failure this is; the default title and description follow it. */
     kind?: ErrorStateKind;
@@ -10,8 +10,8 @@ export type ErrorStateProps = Omit<ComponentProps<'div'>, 'title'> & {
     /** Makes the title a heading of this level; see `StateFrame`. */
     headingLevel?: StateHeadingLevel;
     description?: ReactNode;
-    /** Replaces the built-in media; `false` shows none. */
-    illustration?: ReactNode | false;
+    /** Replaces the built-in media; `false` shows none; a scene id or `true` draws an icon illustration (`@nxgt/material/illustrations`). */
+    illustration?: StateIllustrationProp;
     icon?: ReactNode;
     /** The thrown value: its name, message and causes go in the details. */
     error?: unknown;

package/dist/lib/components/ui/feedback/state-frame/illustration-defaults.d.ts

@@ -0,0 +1,46 @@
+import { IconRef, IconStyleInput } from '@nxgt/material-core/icons';
+import { IllustrationScene, SceneTable } from '@nxgt/material-core/illustrations';
+import { ReactNode } from 'react';
+/** The icons a scene is drawn with: the hero, then the satellites (up to four). */
+export type IllustrationIcons = {
+    hero?: IconRef | string;
+    satellites?: readonly (IconRef | string)[];
+};
+export type IllustrationDefaultsValue = {
+    /**
+     * `'suggested'`: every state draws its scene with the suggested icons
+     * (`SUGGESTED_ICONS`). A table: those scenes are drawn with these icons
+     * and the others keep today's art. It may also name the scenes of a domain
+     * set (`HEALTH_SCENES`, `EDUCATION_SCENES`) by their ids.
+     */
+    icons?: 'suggested' | (Partial<Record<IllustrationScene, IllustrationIcons>> & Readonly<Record<string, IllustrationIcons | undefined>>);
+    /** The icon style of every illustration below (`duotone-thin`): `{ family?, type? }`, a sprite file's name, or a list of them. */
+    iconStyle?: IconStyleInput;
+    /**
+     * Scene sets to register, such as `[HEALTH_SCENES]` of
+     * `@nxgt/material/illustrations/health` or `[EDUCATION_SCENES]` of
+     * `…/education`: their ids then work everywhere a
+     * scene id does (`Illustration scene`, a state's `illustration`,
+     * `emptyIllustration`). A `scenes` prop on one `Illustration` wins; a base
+     * id wins over a set's.
+     */
+    sets?: readonly SceneTable[];
+};
+export type IllustrationDefaultsProps = IllustrationDefaultsValue & {
+    children?: ReactNode;
+};
+/**
+ * Opts a subtree into the icon illustrations: `EmptyState` and `ErrorState`
+ * of the default size then draw the scene of their kind (when `icons` names
+ * it) instead of the built-in art, and every `Illustration` takes the
+ * `iconStyle`. Without it nothing changes. The sprites come from
+ * `IconSpritesProvider` (or `/assets/icons/sprites/`). This module holds no
+ * drawing code: the engine loads only where a scene is drawn.
+ */
+export declare function IllustrationDefaults({ icons, iconStyle, sets, children, }: IllustrationDefaultsProps): import("react").JSX.Element;
+/** The nearest `IllustrationDefaults`, or `null`. */
+export declare function useIllustrationDefaults(): IllustrationDefaultsValue | null;
+/** The icons the provider gives a scene: `{}` for `'suggested'`, `undefined` when it does not name it. */
+export declare function defaultIconsFor(defaults: IllustrationDefaultsValue | null, scene: string): IllustrationIcons | undefined;
+/** The registered set that holds `scene`, or `undefined` (a base id, or an id no set has). */
+export declare function setOf(defaults: IllustrationDefaultsValue | null, scene: string): SceneTable | undefined;

package/dist/lib/components/ui/feedback/state-frame/scene-registry.d.ts

@@ -0,0 +1,14 @@
+import { IllustrationScene } from '@nxgt/material-core/illustrations';
+/**
+ * The ids of the scene sets an app registers (`IllustrationDefaults` `sets`),
+ * so they type-check as a scene id. A set's subpath adds its ids by module
+ * augmentation when it is imported (`@nxgt/material/illustrations/health`
+ * adds the health ids): `{ health: HealthScene }`. Empty until then, so the
+ * base ids stay strict.
+ */
+export interface IllustrationSceneRegistry {
+}
+/** The ids of every imported set. */
+export type RegisteredScene = IllustrationSceneRegistry[keyof IllustrationSceneRegistry];
+/** A scene id: a base scene, or one of an imported set (draw it under an `IllustrationDefaults` that has the set in `sets`). */
+export type SceneId = IllustrationScene | RegisteredScene;

package/dist/lib/components/ui/feedback/state-frame/state-frame.d.ts

@@ -1,5 +1,6 @@
 import { StateKind } from '@nxgt/material-core/states';
 import { ComponentProps, ReactNode } from 'react';
+import { SceneId } from './scene-registry.js';
 /**
  * `default`: a page or a panel. `compact`: a card. `inline`: a row in a
  * list of options, the icon well beside the text, the action at the end.
@@ -8,11 +9,18 @@ export type StateFrameSize = 'default' | 'compact' | 'inline';
 /** A title's heading level, as `FacetGroup`'s `headingLevel` (no `h1`: the
  * page's own heading is that). */
 export type StateHeadingLevel = 2 | 3 | 4 | 5 | 6;
+/**
+ * What replaces a state's built-in media: any node, `false` for none, a scene
+ * id (`'empty'`, `'no-results'`…) or `true` to draw the kind's scene with the
+ * icon illustrations of `@nxgt/material/illustrations`. A scene is drawn at
+ * the default and compact sizes; the inline row keeps its icon well.
+ */
+export type StateIllustrationProp = ReactNode | SceneId;
 export type StateFrameProps = Omit<ComponentProps<'div'>, 'title'> & {
     kind: StateKind;
     size?: StateFrameSize;
-    /** Replaces the built-in media; `false` shows no media at all. */
-    illustration?: ReactNode | false;
+    /** Replaces the built-in media; `false` shows no media at all; a scene id or `true` draws an icon illustration. */
+    illustration?: StateIllustrationProp;
     /** Shown in the icon well when there is no `illustration`. */
     icon?: ReactNode;
     title?: ReactNode;

package/dist/lib/components/ui/feedback/state-frame/state-scene-illustration.d.ts

@@ -0,0 +1,5 @@
+import { SceneId } from './scene-registry.js';
+export declare function StateSceneIllustration({ scene, size, }: {
+    scene: SceneId;
+    size: 'sm' | 'md';
+}): import("react").JSX.Element;

package/dist/lib/components/ui/feedback/state-frame/state-scenes.d.ts

@@ -0,0 +1,15 @@
+import { IllustrationScene, SceneTable } from '@nxgt/material-core/illustrations';
+import { StateKind } from '@nxgt/material-core/states';
+import { SceneId } from './scene-registry.js';
+/**
+ * The scenes of `@nxgt/material-core/illustrations`, as ids: written out so
+ * `StateFrame` can tell a scene id from a node without loading the engine
+ * (a test holds this list to core's `ILLUSTRATION_SCENES`).
+ */
+export declare const SCENE_IDS: readonly IllustrationScene[];
+/** The scene a state kind is drawn with. */
+export declare const SCENE_OF_KIND: Record<StateKind, IllustrationScene>;
+/** Whether `value` is the id of a scene (a string a `ReactNode` could also be): a base scene, or an id of one of the registered `sets`. */
+export declare function isSceneId(value: unknown, sets?: readonly SceneTable[]): value is SceneId;
+/** The kind whose built-in art stands in for a scene that cannot be drawn (`success` and `welcome` have no kind: the empty art). */
+export declare const KIND_OF_SCENE: Record<IllustrationScene, StateKind>;

package/dist/lib/components/ui/layout/app-shell/use-keep-shapes-inside.d.ts

@@ -1,3 +1,6 @@
+import { Box } from './keep-shapes-inside.js';
+/** The band's strips: a sticky one (the app bar) is measured where it rests, above the first strip that scrolls. */
+export declare function bandBoxes(column: Element, layer: Box): Box[];
 /** A callback ref for the theme's `Background`, a child of the backdrop layer (it is loaded lazily, so it mounts after this hook). */
 export declare function useKeepShapesInside(): (el: HTMLElement | null) => void;
 /**

package/dist/lib/components/ui/primitives/icon/icon-sprites.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+export type IconSpritesProviderProps = {
+    /**
+     * Where the sprite files are served from: a root-relative path on your own
+     * origin, such as `/static/icons/`. Throws `IconRefError` (`base`) for a URL,
+     * a `//host` path, a `..` or a `:`.
+     */
+    base: string;
+    children?: ReactNode;
+};
+/**
+ * Tells every `Icon` below it where the sprite files live, when they are not
+ * at `/assets/icons/sprites/`. Without it the default base is used.
+ */
+export declare function IconSpritesProvider({ base, children, }: IconSpritesProviderProps): import("react").JSX.Element;
+/** The sprite base of the nearest `IconSpritesProvider`, or `/assets/icons/sprites/`. It does not throw outside a provider: an `Icon` works without one. */
+export declare function useSpriteBase(): string;

package/dist/lib/components/ui/primitives/icon/index.d.ts

@@ -1 +1,2 @@
 export * from './icon.js';
+export * from './icon-sprites.js';

package/dist/lib/illustrations/illustration.d.ts

@@ -0,0 +1,38 @@
+import { SceneTable } from '@nxgt/material-core/illustrations';
+import { ComponentProps, ReactElement } from 'react';
+import { SceneId } from '../components/ui/feedback/state-frame/scene-registry.js';
+import { IllustrationOverrides } from './use-illustration.js';
+export type IllustrationSize = 'sm' | 'md' | 'lg';
+export type IllustrationProps<T extends SceneTable | undefined = undefined> = Omit<ComponentProps<'div'>, 'title'> & IllustrationOverrides & {
+    /** Which scene: one of `ILLUSTRATION_SCENES` (`empty`, `no-results`, `not-found`, `error`, `offline`, `success`, `welcome`, `forbidden`, `maintenance`, `invitation`, `sign-in`, `empty-inbox`), or an id of `scenes`, or of a set an `IllustrationDefaults` above registers (`sets`). */
+    scene: T extends SceneTable ? keyof T & string : SceneId;
+    /** A domain's set of scenes, such as `HEALTH_SCENES` of `@nxgt/material/illustrations/health` or `EDUCATION_SCENES` of `…/education`: `scene` is then one of its ids. */
+    scenes?: T;
+    /** The width: `sm` 120px, `md` 190px (default), `lg` 280px; the box keeps a 4:3 shape and never wider than its container. */
+    size?: IllustrationSize;
+    /**
+     * What the picture says, as its accessible name (`role="img"` with an
+     * `aria-label`, never a `<title>`). Without it the illustration is
+     * decorative and hidden from assistive technology.
+     */
+    title?: string;
+    /** The satellites drift and the sparkles twinkle, slowly. Off by default and under reduced motion. */
+    animated?: boolean;
+};
+/**
+ * A state illustration: a hero icon on a Material 3 Expressive plate with
+ * satellites and sparkles, drawn from the Font Awesome sprites your app serves
+ * (`IconSpritesProvider` says where; `/assets/icons/sprites/` otherwise).
+ * Colours are the theme's tones, light and dark; the markup holds no `style`
+ * attribute. The server and the client render the same markup: the plate is
+ * a disc until its shapes have loaded. `hero`, `satellites`, `iconStyle`, `tone` and
+ * `duotone` override the scene (and the `IllustrationDefaults` above). An icon
+ * name or a style that is not valid does not crash the page: outside
+ * production it warns once, and the built-in art of the scene's kind is drawn.
+ */
+export declare function Illustration<T extends SceneTable>(props: IllustrationProps<T> & {
+    scenes: T;
+}): ReactElement;
+export declare function Illustration(props: IllustrationProps<undefined> & {
+    scenes?: undefined;
+}): ReactElement;

package/dist/lib/illustrations/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * State illustrations: `@nxgt/material/illustrations`. `Illustration` draws
+ * one of twelve scenes (a hero icon on a plate with satellites) from the Font
+ * Awesome sprites your app serves; `IllustrationDefaults` opts a subtree's
+ * `EmptyState` and `ErrorState` into them. The scenes are
+ * `@nxgt/material-core/illustrations`, re-exported by name.
+ */
+export { type IconStyleInput, type IconStyleRef, ILLUSTRATION_SCENES, type IllustrationScene, type IllustrationSpec, type IllustrationTone, type SceneRow, type SceneTable, SUGGESTED_ICONS, } from '@nxgt/material-core/illustrations';
+export { IllustrationDefaults, type IllustrationDefaultsProps, type IllustrationDefaultsValue, type IllustrationIcons, } from '../components/ui/feedback/state-frame/illustration-defaults.js';
+export type { IllustrationSceneRegistry, RegisteredScene, SceneId, } from '../components/ui/feedback/state-frame/scene-registry.js';
+export { Illustration, type IllustrationProps, type IllustrationSize, } from './illustration.js';

package/dist/lib/illustrations/plated-illustration.d.ts

@@ -0,0 +1,11 @@
+import { IllustrationSpec } from '@nxgt/material-core/illustrations';
+/**
+ * The illustration with its plate drawn. Its own module so the shapes engine
+ * (`@nxgt/material-core/illustrations/plates`) loads on demand:
+ * `Illustration` shows the disc until this has arrived.
+ */
+export default function PlatedIllustration({ spec, idPrefix, base, }: {
+    spec: IllustrationSpec;
+    idPrefix: string;
+    base: string;
+}): import("react").JSX.Element;

package/dist/lib/illustrations/use-illustration.d.ts

@@ -0,0 +1,22 @@
+import { IconRef } from '@nxgt/material-core/icons';
+import { IllustrationSpec, SceneTable } from '@nxgt/material-core/illustrations';
+export type IllustrationOverrides = {
+    hero?: IconRef | string;
+    satellites?: readonly (IconRef | string)[];
+    iconStyle?: IllustrationSpec['iconStyle'];
+    tone?: IllustrationSpec['tone'];
+    duotone?: IllustrationSpec['duotone'];
+};
+/**
+ * A scene's spec, with the provider's icons and iconStyle under the props', the
+ * sprite base and an id prefix that is the same on the server and the client.
+ * Built from a stable key, so a re-render with equal props is the same spec.
+ */
+export declare function useIllustration(scene: string, overrides: IllustrationOverrides, given?: SceneTable): {
+    built: {
+        spec: IllustrationSpec;
+        flat: import('@nxgt/material-core/backgrounds').SceneNode;
+    } | null;
+    idPrefix: string;
+    base: string;
+};

package/dist/lib/illustrations-education/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The education illustrations: `@nxgt/material/illustrations/education`. A set
+ * of ten scenes (a classroom, homework, exam grades, a timetable, attendance,
+ * an enrolment, a library, a graduation, no students, a report card). Register
+ * the set once, then every scene id works:
+ * `<IllustrationDefaults sets={[EDUCATION_SCENES]}>` and
+ * `<Illustration scene="classroom" />` (or `scenes={EDUCATION_SCENES}` on one).
+ * Importing this subpath also adds the ids to `SceneId`. Only an app that
+ * imports it carries the table.
+ */
+export { EDUCATION_SCENE_IDS, EDUCATION_SCENES, EDUCATION_SUGGESTED_ICONS, type EducationScene, } from '@nxgt/material-core/illustrations/education';
+declare module '../components/ui/feedback/state-frame/scene-registry.js' {
+    interface IllustrationSceneRegistry {
+        education: import('@nxgt/material-core/illustrations/education').EducationScene;
+    }
+}

package/dist/lib/illustrations-health/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The health illustrations: `@nxgt/material/illustrations/health`. A set of
+ * ten scenes (a patient's record, a consultation, an appointment, a lab
+ * sample, a prescription, a vaccination, a hospital stay, an emergency, no
+ * patients, lab results). Register the set once, then every scene id works:
+ * `<IllustrationDefaults sets={[HEALTH_SCENES]}>` and
+ * `<Illustration scene="patient-record" />` (or `scenes={HEALTH_SCENES}` on
+ * one). Importing this subpath also adds the ids to `SceneId`. Only an app
+ * that imports it carries the table.
+ */
+export { HEALTH_SCENE_IDS, HEALTH_SCENES, HEALTH_SUGGESTED_ICONS, type HealthScene, } from '@nxgt/material-core/illustrations/health';
+declare module '../components/ui/feedback/state-frame/scene-registry.js' {
+    interface IllustrationSceneRegistry {
+        health: import('@nxgt/material-core/illustrations/health').HealthScene;
+    }
+}

package/dist/lib/theme-picker/partials/mini-background.d.ts

@@ -4,6 +4,9 @@ import { ThemeBackground } from '@nxgt/material-core/theme/define';
  * texture of its preset (rings, grid, lines, dots). Drawn by CSS from the
  * enclosing zone's tokens, so it is the theme's own colours with no engine
  * and no inline style. `false` is a theme with no background: a plain surface.
+ * The `icons` preset adds its first four icons, each a `<use>` of the sprite
+ * your app serves (`IconSpritesProvider`): a sprite that is not there draws
+ * nothing, and the wash stays.
  */
 export declare function MiniBackground({ background, }: {
     background: ThemeBackground | false;

package/dist/lib/theme-picker/partials/tile-icons.d.ts

@@ -0,0 +1,9 @@
+import { ThemeBackground } from '@nxgt/material-core/theme/define';
+/**
+ * The `href`s of the first icons an `icons` background names, for the picker's
+ * tile. It uses only core's `/icons` references (never the scene builder) and
+ * draws none when the names or styles are not valid (as the scene would not
+ * draw them either): the tile keeps its plain wash.
+ * With a list of styles the icons take them in turn, so the tile shows the mix.
+ */
+export declare function tileIcons(background: ThemeBackground, base: string): string[];