@nxgt/material 3.10.2 → 3.12.0

package/dist/lib/components/ui/display/entity-header/entity-stats.d.ts

@@ -0,0 +1,16 @@
+import { ReactNode } from 'react';
+import { Tone } from '../../tones.js';
+export type EntityStat = {
+    label: string;
+    value: ReactNode;
+    tone?: Tone;
+};
+/** A stat with no value (`null`, `undefined`, `false`, `''`) is dropped; `0` is a figure. */
+export declare const hasStatValue: (stat: EntityStat) => boolean;
+/**
+ * The figures of an EntityHeader (counts, a mean) as compact StatCard tiles in
+ * a row that wraps. A tile with a `tone` is tonal; without one it is outlined.
+ */
+export declare function EntityStats({ data }: {
+    data: EntityStat[];
+}): import("react").JSX.Element | null;

package/dist/lib/components/ui/display/entity-header/partials/entity-header-actions.d.ts

@@ -0,0 +1,6 @@
+import { ResponsiveButtonProps } from '../../../actions/responsive-button/responsive-button.js';
+/** The actions: buttons from props, or any node, at the end of the band; nothing when empty. */
+export declare function EntityHeaderActions({ actions, row, }: {
+    actions: ResponsiveButtonProps[] | React.ReactNode;
+    row: boolean;
+}): import("react").JSX.Element | null;

package/dist/lib/components/ui/display/entity-header/partials/entity-header-body.d.ts

@@ -0,0 +1,14 @@
+import { EntityStat } from '../entity-stats.js';
+/**
+ * The column beside the icon: the heading and the status on one line, the
+ * metadata and the stats under it.
+ */
+export declare function EntityHeaderBody({ title, status, metadata, stats, }: {
+    title?: React.ReactNode;
+    status?: React.ReactNode;
+    metadata: {
+        label: string;
+        value: React.ReactNode;
+    }[];
+    stats: EntityStat[];
+}): import("react").JSX.Element;

package/dist/lib/components/ui/display/entity-header/partials/entity-header-icon.d.ts

@@ -0,0 +1,6 @@
+import { IconButtonProps } from '../../../actions/icon-button/icon-button.js';
+/** The icon badge at the band's start; a round Avatar is its own badge. */
+export declare function EntityHeaderIcon({ icon, row, variant, color, }: {
+    icon: React.ReactNode;
+    row: boolean;
+} & Pick<IconButtonProps, 'variant' | 'color'>): import("react").JSX.Element;

package/dist/lib/components/ui/display/entity-header/partials/shown.d.ts

@@ -0,0 +1,2 @@
+/** Whether a node draws anything: not nil, `false` or an empty string. */
+export declare const shown: (node: React.ReactNode) => boolean;

package/dist/lib/components/ui/display/list-tile/list-tile.d.ts

@@ -16,6 +16,13 @@ export type ListTileProps = {
     selected?: boolean;
     size?: 'sm' | 'md';
     href?: string;
+    /**
+     * A discreet chevron after `trailing`, flipped in right-to-left, decorative
+     * (`aria-hidden`). On by default for a tile with an `href`, off otherwise
+     * (an `onClick` tile may select or act rather than navigate: pass `true`
+     * when it navigates). `false` opts a link out.
+     */
+    chevron?: boolean;
     /**
      * The link element of a tile with an `href`, with the app shell's contract
      * ({@link LinkComponent}: it takes `href`, spreads every other prop and
@@ -26,4 +33,4 @@ export type ListTileProps = {
     disabled?: boolean;
     onClick?: MouseEventHandler<HTMLButtonElement | HTMLAnchorElement>;
 } & Omit<HTMLAttributes<HTMLElement>, 'children' | 'title' | 'onClick'>;
-export declare function ListTile({ title, subtitle, leading, trailing, actions, className, selected, size, href, linkComponent, disabled, onClick, ...props }: ListTileProps): 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 | null | undefined;
+export declare function ListTile({ title, subtitle, leading, trailing, actions, className, selected, size, href, chevron, linkComponent, disabled, onClick, ...props }: ListTileProps): 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 | null | undefined;

package/dist/lib/components/ui/display/list-tile/partials/list-tile-body.d.ts

@@ -2,10 +2,11 @@ import { ReactNode } from 'react';
 type ListTileBodyProps = {
     leading?: ReactNode;
     trailing?: ReactNode;
+    chevron?: boolean;
     title: ReactNode;
     subtitle?: ReactNode;
     compact: boolean;
     selected?: boolean;
 };
-export declare function ListTileBody({ leading, trailing, title, subtitle, compact, selected, }: ListTileBodyProps): import("react").JSX.Element;
+export declare function ListTileBody({ leading, trailing, chevron, title, subtitle, compact, selected, }: ListTileBodyProps): import("react").JSX.Element;
 export {};

package/dist/lib/components/ui/display/stat-card/index.d.ts

@@ -1,4 +1,4 @@
 export type { StatDeltaTone } from './format-stat-delta.js';
 export { formatStatDelta } from './format-stat-delta.js';
-export type { StatCardProps, StatCardValueSize, StatCardVariant, } from './stat-card.js';
+export type { StatCardProps, StatCardSize, StatCardValueSize, StatCardVariant, } from './stat-card.js';
 export { StatCard } from './stat-card.js';

package/dist/lib/components/ui/display/stat-card/partials/stat-card-compact.d.ts

@@ -0,0 +1,12 @@
+import { StatCardClasses } from '../stat-card-classes.js';
+import { StatCardProps } from '../types.js';
+type Props = Pick<StatCardProps, 'label' | 'value' | 'icon' | 'loading'> & {
+    classes: StatCardClasses;
+};
+/**
+ * The inside of `StatCard size="sm"`: the icon chip, then the value over its
+ * label. The value comes first in the document, so assistive tech reads
+ * "22 Students"; the figures are tabular so a row of tiles does not jitter.
+ */
+export declare function StatCardCompact({ label, value, icon, loading, classes, }: Props): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/display/stat-card/stat-card-classes.d.ts

@@ -1,4 +1,4 @@
-import { StatCardProps, StatCardVariant } from './types.js';
+import { StatCardProps, StatCardSize, StatCardVariant } from './types.js';
 export type StatCardClasses = {
     /** `data-tone` of the root: the tone, or `neutral` on a tonal or filled card with none. */
     dataTone: StatCardProps['tone'] | 'neutral' | undefined;
@@ -13,7 +13,8 @@ export type StatCardClasses = {
     skeleton: string;
 };
 /** Every class a StatCard picks from its variant and tone; `className` is merged by the caller. */
-export declare function statCardClasses({ variant, tone, }: {
+export declare function statCardClasses({ variant, tone, size, }: {
     variant: StatCardVariant;
     tone: StatCardProps['tone'];
+    size?: StatCardSize;
 }): StatCardClasses;

package/dist/lib/components/ui/display/stat-card/stat-card.d.ts

@@ -1,3 +1,3 @@
 import { StatCardProps } from './types.js';
-export type { StatCardProps, StatCardValueSize, StatCardVariant, } from './types.js';
-export declare function StatCard({ label, value, hint, delta, deltaTone, icon, loading, tone, variant, valueSize, className, ...props }: StatCardProps): import("react").JSX.Element;
+export type { StatCardProps, StatCardSize, StatCardValueSize, StatCardVariant, } from './types.js';
+export declare function StatCard({ label, value, hint, delta, deltaTone, icon, loading, tone, variant, valueSize, size, className, ...props }: StatCardProps): import("react").JSX.Element;

package/dist/lib/components/ui/display/stat-card/types.d.ts

@@ -4,6 +4,7 @@ import { Tone } from '../../tones.js';
 import { StatDeltaTone } from './format-stat-delta.js';
 export type StatCardVariant = 'outlined' | 'tonal' | 'filled';
 export type StatCardValueSize = 'default' | 'display';
+export type StatCardSize = 'default' | 'sm';
 export type StatCardProps = Omit<ComponentProps<typeof Card>, 'children'> & {
     label: ReactNode;
     value?: ReactNode;
@@ -25,6 +26,14 @@ export type StatCardProps = Omit<ComponentProps<typeof Card>, 'children'> & {
      * `neutral` when there is no `tone`.
      */
     variant?: StatCardVariant;
+    /**
+     * `sm` is a compact tile for a band or a header, 40 to 56 px tall: the icon
+     * chip, then the value (tabular figures) over its label, in one row that
+     * hugs its content, so tiles sit side by side and wrap on a phone. It takes
+     * the same `tone` and `variant`; `hint`, `delta` and `valueSize` do not
+     * apply to it.
+     */
+    size?: StatCardSize;
     /** `display` draws the value larger (`headline-large`); `default` is `headline-small`. */
     valueSize?: StatCardValueSize;
 };

package/dist/lib/components/ui/feedback/alert/alert-variants.d.ts

@@ -0,0 +1,18 @@
+import { VariantProps } from 'class-variance-authority';
+/**
+ * Alert's look, in one place: Banner builds on the same variants, title and
+ * description classes, so the two cannot drift. The icon rules target the
+ * `alert-icon` slot only, so a Banner's dismiss button and action keep their
+ * own colours. Every class is written out in full: Tailwind cannot see one
+ * built from a template string.
+ */
+export declare const alertVariants: (props?: ({
+    variant?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "foreground" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export type AlertVariantProps = VariantProps<typeof alertVariants>;
+/** The text column: it may shrink below its content, so a long URL wraps. */
+export declare const ALERT_TEXT_CLASS = "flex min-w-0 flex-1 flex-col gap-1 break-words";
+/** The title's Typography variant and class. */
+export declare const ALERT_TITLE_VARIANT = "title-small";
+export declare const ALERT_TITLE_CLASS = "font-bold";
+export declare const ALERT_DESCRIPTION_CLASS = "text-muted-foreground";

package/dist/lib/components/ui/feedback/alert/alert.d.ts

@@ -1,12 +1,8 @@
-import { VariantProps } from 'class-variance-authority';
 import { ComponentProps, ReactNode } from 'react';
-declare const variants: (props?: ({
-    variant?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "foreground" | null | undefined;
-} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+import { AlertVariantProps } from './alert-variants.js';
 export type AlertProps = {
     icon?: ReactNode;
     title?: ReactNode;
     description?: ReactNode;
-} & Omit<ComponentProps<'div'>, 'title' | 'description'> & VariantProps<typeof variants>;
+} & Omit<ComponentProps<'div'>, 'title' | 'description'> & AlertVariantProps;
 export declare function Alert({ description, icon, title, className, variant, ...props }: AlertProps): import("react").JSX.Element;
-export {};

package/dist/lib/components/ui/feedback/typing-indicator/typing-indicator.d.ts

@@ -2,7 +2,7 @@ import { VariantProps } from 'class-variance-authority';
 import { ComponentProps } from 'react';
 declare const typingIndicatorVariants: (props?: ({
     variant?: "bubble" | "dots" | null | undefined;
-    size?: "sm" | "md" | null | undefined;
+    size?: "md" | "sm" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export type TypingIndicatorProps = ComponentProps<'div'> & VariantProps<typeof typingIndicatorVariants> & {
     /** Its accessible name, announced politely (`role="status"`). Default: "Typing". */

package/dist/lib/components/ui/fields/slider/split-slider-props.d.ts

@@ -45,13 +45,13 @@ export declare function splitSliderProps({ defaultValue, value, min, max, step,
         minStepsBetweenThumbs?: number;
         onValueCommit?(value: number[]): void;
         form?: string;
+        title?: string | undefined | undefined;
         content?: string | undefined | undefined;
         translate?: "yes" | "no" | undefined | undefined;
         color?: string | undefined | undefined;
         prefix?: string | undefined | undefined;
         slot?: string | undefined | undefined;
         style?: import('react').CSSProperties | undefined;
-        title?: string | undefined | undefined;
         children?: import('react').ReactNode;
         key?: import('react').Key | null | undefined;
         defaultChecked?: boolean | undefined | undefined;

package/dist/lib/components/ui/fields/slider/use-slider-control.d.ts

@@ -19,13 +19,13 @@ export declare function useSliderControl(props: SliderControlProps): {
         minStepsBetweenThumbs?: number;
         onValueCommit?(value: number[]): void;
         form?: string;
+        title?: string | undefined | undefined;
         content?: string | undefined | undefined;
         translate?: "yes" | "no" | undefined | undefined;
         color?: string | undefined | undefined;
         prefix?: string | undefined | undefined;
         slot?: string | undefined | undefined;
         style?: import('react').CSSProperties | undefined;
-        title?: string | undefined | undefined;
         children?: import('react').ReactNode;
         key?: import('react').Key | null | undefined;
         defaultChecked?: boolean | undefined | undefined;

package/dist/lib/components/ui/layout/app-shell/activity-column.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+import { ActivityLayoutProps } from './activity-layout.types.js';
+type ColumnProps = Pick<ActivityLayoutProps, 'items' | 'brand' | 'logo' | 'name' | 'context' | 'headerTitle' | 'breadcrumb' | 'breadcrumbRoot' | 'headerActions' | 'avatar' | 'linkComponent' | 'menuOpen' | 'onMenuOpenChange' | 'routeTransition' | 'backdrop'> & {
+    /** The element of the content region. */
+    as: 'main' | 'div';
+    contained: boolean;
+    /** Whether a backdrop is drawn, and whether it is the theme's. */
+    hasBackdrop: boolean;
+    themeBackdrop: boolean;
+    children?: ReactNode;
+};
+/**
+ * The content column of {@link ActivityLayout}: the backdrop layer behind, the
+ * app bar, the breadcrumb and the routed content region.
+ */
+export declare function ActivityColumn({ as, contained, hasBackdrop, themeBackdrop, items, brand, logo, name, context, headerTitle, breadcrumb, breadcrumbRoot, headerActions, avatar, linkComponent, menuOpen, onMenuOpenChange, routeTransition, backdrop, children, }: ColumnProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/layout/app-shell/activity-layout.d.ts

@@ -1,108 +1,5 @@
-import { ComponentProps, ReactNode } from 'react';
-import { AppBreadcrumbRoot } from './app-breadcrumb.js';
-import { RouteTransition } from './route-transition.js';
-import { AppLogo, AppShellLinkComponent, MenuItem } from './types.js';
-export type ActivityLayoutProps = {
-    items: MenuItem[];
-    /**
-     * The sidebar header, in the rail and in the phone's menu sheet: replaces
-     * `logo` and `name` entirely.
-     */
-    brand?: ReactNode;
-    /**
-     * The app's logo: an image URL, `{ src, alt }`, or a node. The collapsed
-     * rail shows it alone, the phone's menu sheet beside `name`.
-     */
-    logo?: AppLogo;
-    /**
-     * The app's name, already translated: the logo's accessible name and
-     * tooltip in the rail, shown beside it in the menu sheet.
-     */
-    name?: string;
-    /**
-     * A line at the top of the phone's menu sheet, above the brand: the
-     * current tenant's name. `name` stays the app's brand.
-     */
-    context?: ReactNode;
-    /**
-     * The header's leading title, the context the app is in (the active
-     * organisation's name): right after the phone's menu button, truncated
-     * with an ellipsis when long. Not a heading: the screen's `h1` is
-     * `ActivityContent`'s title, or the page's title in the bar (a route's
-     * `handle.title`), which it then sits beside.
-     */
-    headerTitle?: ReactNode;
-    /** The breadcrumb's first crumb, a text link in place of the home icon. */
-    breadcrumbRoot?: AppBreadcrumbRoot;
-    /** Passed to the header, before the avatar. */
-    headerActions?: ReactNode;
-    /** Passed to the header. An image URL, or a whole node. */
-    avatar?: ReactNode;
-    /**
-     * The link each menu entry renders, given its `href`. Defaults to React
-     * Router's `Link`; pass another for a different router.
-     */
-    linkComponent?: AppShellLinkComponent;
-    /**
-     * The element of the content region. `'main'` (the default) makes it the
-     * page's `<main>` landmark; pass `'div'` when your app renders its own
-     * `<main>` around or inside the shell — a page has only one.
-     */
-    contentAs?: 'main' | 'div';
-    /**
-     * Who scrolls. `'document'` (the default): the page grows with its content
-     * and the browser scrolls it, the header and the sidebar staying in view.
-     * `'container'`: the shell is exactly one screen high and the content
-     * region scrolls inside it — for a screen that manages its own height
-     * (a full-height map, a kanban board). The region then starts each new
-     * location at the top, and Back returns to where that page was left.
-     */
-    scroll?: 'document' | 'container';
-    /**
-     * Where the rail's entries sit. `'start'` (the default): right under the
-     * brand. `'center'`: vertically centred, as before.
-     */
-    align?: 'start' | 'center';
-    /**
-     * Controls the phone's menu sheet: open while true. It closes by itself
-     * when a link in it is followed or the location changes (the
-     * `onMenuOpenChange(false)` call tells you); leave it out to let the
-     * layout manage the sheet. Only a phone shows the sheet.
-     */
-    menuOpen?: boolean;
-    /** Asked for every change of the menu sheet: the button, Escape, a link, a new location. */
-    onMenuOpenChange?: (open: boolean) => void;
-    /**
-     * React's `<ViewTransition>` around the content region: on by default,
-     * `false` for none, or its props (default class `nxgt-route`). See the
-     * app shell guide, "Route transitions".
-     */
-    routeTransition?: RouteTransition;
-    /**
-     * An exception to the theme's background, which the layout draws by
-     * default: under Lavande, or under no theme, the built-in gradient and its
-     * three blobs; under another theme, that theme's `background`. A node
-     * replaces it for this screen: typically a `Background` preset from
-     * `@nxgt/material/backgrounds`. It fills the whole layout, sits under the
-     * sidebar, the header and the content, and is `inert`, `aria-hidden` and
-     * never takes a pointer. `false` draws no background at all, a plain page.
-     * The preset's stylesheet (`@nxgt/material/backgrounds.css`) is the app's to
-     * import. See the app shell guide, "Use a background preset behind the shell".
-     *
-     * @example
-     * ```tsx
-     * import { Background, MOTIF_SHAPES_ALL } from '@nxgt/material/backgrounds';
-     *
-     * <ActivityLayout
-     *   items={items}
-     *   backdrop={<Background preset="shapes" motif={{ shapes: MOTIF_SHAPES_ALL }} />}
-     * >
-     *   <Outlet />
-     * </ActivityLayout>
-     * ```
-     */
-    backdrop?: ReactNode | false;
-} & ComponentProps<'div'>;
+import { ActivityLayoutProps } from './activity-layout.types.js';
+export type { ActivityLayoutProps } from './activity-layout.types.js';
 /**
  * The application chrome: sidebar, header, breadcrumbs, and the routed content.
  *
@@ -118,4 +15,4 @@ export type ActivityLayoutProps = {
  * phone's toolbar (the bottom of the screen hidden). The bottom keeps clear
  * of a `MediaPlayerHost`'s docked bar (`--nxgt-media-dock`).
  */
-export declare function ActivityLayout({ items, brand, logo, name, context, headerTitle, breadcrumbRoot, headerActions, avatar, linkComponent, contentAs: Content, scroll, align, menuOpen, onMenuOpenChange, routeTransition, backdrop, children, className, ...props }: ActivityLayoutProps): import("react").JSX.Element;
+export declare function ActivityLayout({ items, brand, logo, name, context, headerTitle, breadcrumb, breadcrumbRoot, headerActions, avatar, linkComponent, contentAs: Content, scroll, align, menuOpen, onMenuOpenChange, routeTransition, backdrop, children, className, ...props }: ActivityLayoutProps): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/activity-layout.types.d.ts

@@ -0,0 +1,113 @@
+import { ComponentProps, ReactNode } from 'react';
+import { AppBreadcrumbRoot } from './app-breadcrumb.js';
+import { RouteTransition } from './route-transition.js';
+import { AppLogo, AppShellLinkComponent, MenuItem } from './types.js';
+export type ActivityLayoutProps = {
+    items: MenuItem[];
+    /**
+     * The sidebar header, in the rail and in the phone's menu sheet: replaces
+     * `logo` and `name` entirely.
+     */
+    brand?: ReactNode;
+    /**
+     * The app's logo: an image URL, `{ src, alt }`, or a node. The collapsed
+     * rail shows it alone, the phone's menu sheet beside `name`.
+     */
+    logo?: AppLogo;
+    /**
+     * The app's name, already translated: the logo's accessible name and
+     * tooltip in the rail, shown beside it in the menu sheet.
+     */
+    name?: string;
+    /**
+     * A line at the top of the phone's menu sheet, above the brand: the
+     * current tenant's name. `name` stays the app's brand.
+     */
+    context?: ReactNode;
+    /**
+     * The header's leading title, the context the app is in (the active
+     * organisation's name): right after the phone's menu button, truncated
+     * with an ellipsis when long. Not a heading: the screen's `h1` is
+     * `ActivityContent`'s title, or the page's title in the bar (a route's
+     * `handle.title`), which it then sits beside.
+     */
+    headerTitle?: ReactNode;
+    /**
+     * Whether the breadcrumb trail shows. `false` hides it, for an error page
+     * whose matched routes would show a misleading trail. The trail is also
+     * hidden when every matched `handle.breadcrumb` renders `null`.
+     *
+     * @default true
+     */
+    breadcrumb?: boolean;
+    /** The breadcrumb's first crumb, a text link in place of the home icon. */
+    breadcrumbRoot?: AppBreadcrumbRoot;
+    /** Passed to the header, before the avatar. */
+    headerActions?: ReactNode;
+    /** Passed to the header. An image URL, or a whole node. */
+    avatar?: ReactNode;
+    /**
+     * The link each menu entry renders, given its `href`. Defaults to React
+     * Router's `Link`; pass another for a different router.
+     */
+    linkComponent?: AppShellLinkComponent;
+    /**
+     * The element of the content region. `'main'` (the default) makes it the
+     * page's `<main>` landmark; pass `'div'` when your app renders its own
+     * `<main>` around or inside the shell — a page has only one.
+     */
+    contentAs?: 'main' | 'div';
+    /**
+     * Who scrolls. `'document'` (the default): the page grows with its content
+     * and the browser scrolls it, the header and the sidebar staying in view.
+     * `'container'`: the shell is exactly one screen high and the content
+     * region scrolls inside it — for a screen that manages its own height
+     * (a full-height map, a kanban board). The region then starts each new
+     * location at the top, and Back returns to where that page was left.
+     */
+    scroll?: 'document' | 'container';
+    /**
+     * Where the rail's entries sit. `'start'` (the default): right under the
+     * brand. `'center'`: vertically centred, as before.
+     */
+    align?: 'start' | 'center';
+    /**
+     * Controls the phone's menu sheet: open while true. It closes by itself
+     * when a link in it is followed or the location changes (the
+     * `onMenuOpenChange(false)` call tells you); leave it out to let the
+     * layout manage the sheet. Only a phone shows the sheet.
+     */
+    menuOpen?: boolean;
+    /** Asked for every change of the menu sheet: the button, Escape, a link, a new location. */
+    onMenuOpenChange?: (open: boolean) => void;
+    /**
+     * React's `<ViewTransition>` around the content region: on by default,
+     * `false` for none, or its props (default class `nxgt-route`). See the
+     * app shell guide, "Route transitions".
+     */
+    routeTransition?: RouteTransition;
+    /**
+     * An exception to the theme's background, which the layout draws by
+     * default: under Lavande, or under no theme, the built-in gradient and its
+     * three blobs; under another theme, that theme's `background`. A node
+     * replaces it for this screen: typically a `Background` preset from
+     * `@nxgt/material/backgrounds`. It fills the whole layout, sits under the
+     * sidebar, the header and the content, and is `inert`, `aria-hidden` and
+     * never takes a pointer. `false` draws no background at all, a plain page.
+     * The preset's stylesheet (`@nxgt/material/backgrounds.css`) is the app's to
+     * import. See the app shell guide, "Use a background preset behind the shell".
+     *
+     * @example
+     * ```tsx
+     * import { Background, MOTIF_SHAPES_ALL } from '@nxgt/material/backgrounds';
+     *
+     * <ActivityLayout
+     *   items={items}
+     *   backdrop={<Background preset="shapes" motif={{ shapes: MOTIF_SHAPES_ALL }} />}
+     * >
+     *   <Outlet />
+     * </ActivityLayout>
+     * ```
+     */
+    backdrop?: ReactNode | false;
+} & ComponentProps<'div'>;

package/dist/lib/components/ui/layout/app-shell/app-breadcrumb.d.ts

@@ -33,7 +33,8 @@ export type AppBreadcrumbProps = {
  *
  * A route opts in by exporting `handle = { breadcrumb: (match) => ... }`;
  * routes without one contribute nothing, so intermediate layouts stay out of
- * the trail. It starts with a home icon, or with `root`'s text link. Hidden on
+ * the trail, and so does a crumb that renders `null`; with none left the trail
+ * is hidden. It starts with a home icon, or with `root`'s text link. Hidden on
  * mobile, where there is no room for it.
  */
 export declare function AppBreadcrumb({ root, className, ...props }: AppBreadcrumbProps): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/app-sidebar-icon-item.d.ts

@@ -0,0 +1,13 @@
+import { AppShellLinkComponent, MenuItem } from './types.js';
+/**
+ * An entry with `display: 'icon'`: a round, icon-only link, drawn with
+ * `IconButton` (the Button family's look) in the expanded sidebar and the
+ * collapsed rail alike. The label is its tooltip and, visually hidden, its
+ * accessible name; the active one is tinted in primary and `aria-current`.
+ * On a coarse pointer the button itself is 44px.
+ */
+export declare function AppSidebarIconItem({ item, active, linkComponent: Link, }: {
+    item: MenuItem;
+    active: boolean;
+    linkComponent?: AppShellLinkComponent;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/app-sidebar-label-item.d.ts

@@ -0,0 +1,11 @@
+import { AppShellLinkComponent, MenuItem } from './types.js';
+/**
+ * The default entry: an icon and its label (any node, e.g. a `<Trans/>`),
+ * with its badge. The twin of {@link AppSidebarIconItem}, which draws an
+ * entry with `display: 'icon'`.
+ */
+export declare function AppSidebarLabelItem({ item, active, linkComponent, }: {
+    item: MenuItem;
+    active: boolean;
+    linkComponent?: AppShellLinkComponent;
+}): import("react").JSX.Element;

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

@@ -5,6 +5,12 @@ export interface Box {
     right: number;
     bottom: number;
 }
+/** The chrome above the content that no shape may touch. */
+export declare const BAND = "[data-slot=\"app-header\"], [data-slot=\"breadcrumb\"], [data-slot=\"activity-content-header\"], [data-slot=\"entity-header\"]";
+/** The content region: a route swaps the page directly under it. */
+export declare const REGION = "[data-slot=\"activity-content-region\"]";
+/** An element's box as a plain object. */
+export declare const box: (el: Element) => Box;
 /** The space a shape keeps from the layer's edges and from the header band, in pixels. */
 export declare const SHAPE_MARGIN = 8;
 /**

package/dist/lib/components/ui/layout/app-shell/observe-layout.d.ts

@@ -0,0 +1,11 @@
+/**
+ * What can change where the shapes may be, and nothing more: the layer's
+ * size and scene (a new theme or seed adds or removes elements; our own
+ * attributes do not count), the column's size, and the band elements (their
+ * size, and their parents' children: a route swaps the page under the
+ * content region, a header card comes and goes). The page's whole subtree is
+ * not watched for structure; its text and controls are, debounced on their
+ * own timer, and its inner scrollers and late fonts and images count too.
+ * `later` is the caller's debounce to a frame. Returns the cleanup.
+ */
+export declare function observeLayout(layer: Element, column: Element, later: () => void): () => void;

package/dist/lib/components/ui/layout/app-shell/shape-units.d.ts

@@ -0,0 +1,16 @@
+import { Box } from './keep-shapes-inside.js';
+/**
+ * What the backdrop shows or hides as one: a lone shape (`.mo > *`), or a
+ * compound body (`.pt.mg > .mo`: the moon, the planet, the eclipse), which is
+ * one unit made of all its parts, drawn with its halo (`.pt.mh`).
+ */
+export interface ShapeUnit {
+    /** The parts that carry `data-outside` (their `.mo > *` children). */
+    parts: Element[];
+    /** The elements that carry `data-hidden`: the shape itself, or the body group and its halo. */
+    hide: Element[];
+    /** The union box of the parts. */
+    box: Box;
+}
+/** The units of a scene, measured now. */
+export declare function shapeUnits(scene: Element): ShapeUnit[];

package/dist/lib/components/ui/layout/app-shell/shapes-clear-content.d.ts

@@ -0,0 +1,13 @@
+import { Box } from './keep-shapes-inside.js';
+/** The space a shape keeps from the text and controls of the page, in pixels. */
+export declare const CONTENT_MARGIN = 8;
+/** Most boxes kept from one page: past this the rest of a very long list is not collected, and a shape may be drawn over it. */
+export declare const MAX_CONTENT_BOXES = 6000;
+/** What a person reads or presses: a shape is never drawn over one of these. */
+export declare const CONTROLS = "input, textarea, select, button, a[href], img, canvas, video, [role=\"button\"], [role=\"textbox\"], [role=\"combobox\"], [role=\"checkbox\"], [role=\"switch\"], [role=\"tab\"], [role=\"slider\"], [contenteditable=\"true\"]";
+/**
+ * Whether a shape lies over (or within `margin` of) any occupied box of the
+ * content. The boxes are in the content's coordinates; `dx` and `dy` are the
+ * scroll offsets that bring them to the viewport.
+ */
+export declare function hitsContent(shape: Box, occupied: readonly Box[], dx: number, dy: number, margin?: number): boolean;

package/dist/lib/components/ui/layout/app-shell/types.d.ts

@@ -22,6 +22,16 @@ export type MenuItem = {
      * one out of the footer.
      */
     footer?: boolean;
+    /**
+     * How the entry is drawn. Unset: the icon and the label (a tile under the
+     * icon on the collapsed rail). `'icon'`: a round, icon-only button (the
+     * Button family's `IconButton`) in the expanded sidebar, the collapsed rail
+     * and the phone's menu sheet, with the `label` as its tooltip and its
+     * accessible name, `aria-current` when active and a 44px target on a
+     * coarse pointer. Meant for a `footer` entry such as "Settings". It draws
+     * no `badge`: the option is ignored on an icon entry.
+     */
+    display?: 'icon';
     /**
      * A badge on the entry (Material 3 navigation badge). `true`: a small dot.
      * A number: a count, shown as "99+" past 99. `0`, `false` or nothing: no

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

@@ -1,6 +1,20 @@
 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[];
+/**
+ * Keeps the discrete shapes of a preset (`.mo > *`: the motif and illustrated
+ * families) whole and clear of the chrome: after layout, and whenever the
+ * layer or its column resizes or its content changes (a new scene, a new
+ * route), a shape that crosses the layer's edge or the header band gets
+ * `data-outside` (activity-backdrop-shapes.css hides it). A compound body (the
+ * moon, a planet, an eclipse) counts as one shape, by the union of its parts. A floating scene
+ * (`data-animated`) keeps an extra margin for its drift. `data-checked` on the
+ * root lets the CSS show the scene, which stays hidden until the first pass so
+ * no cut shape flashes; where `ResizeObserver` or `Range#getClientRects` is
+ * missing, the scene is only marked checked. Presets without discrete shapes (waves, gradient) are
+ * only marked checked.
+ */
+export declare function keepInside(layer: HTMLElement, column: HTMLElement, scenes: () => Element[]): () => void;
 /** 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;
 /**