@nxgt/material 3.11.0 → 3.12.1

package/dist/{use-chat-composer-Bt2ULsv6.js → use-chat-composer-B0_STpQN.js}

@@ -6912,7 +6912,7 @@ function ov({ className: e, side: t = "bottom", sideOffset: r, align: i = "start
 function sv({ className: e, ...t }) {
 	return /* @__PURE__ */ G(Zg, {
 		"data-slot": "combobox-list",
-		className: n("grid gap-0.5 max-h-[min(calc(--spacing(96)---spacing(9)),calc(var(--available-height)---spacing(9)))] scroll-py-1 overflow-y-auto p-1 data-empty:p-0", e),
+		className: n("grid auto-rows-max gap-0.5 max-h-[min(calc(--spacing(96)---spacing(9)),calc(var(--available-height)---spacing(9)))] scroll-py-1 overflow-y-auto p-1 data-empty:p-0", e),
 		...t
 	});
 }

package/docs/components/data-display.md

@@ -9,7 +9,7 @@ from `@nxgt/material/components`.
 | <img src="../previews/data-display-avatar.webp" width="96" alt=""> | [Avatar](#avatar) | Image with a fallback and an optional online / offline dot |
 | <img src="../previews/data-display-avatargroup.webp" width="96" alt=""> | [AvatarGroup](#avatargroup) | Overlapping avatars with a `+N` overflow |
 | <img src="../previews/data-display-shape.webp" width="96" alt=""> | [Shape](#shape) | Material 3 Expressive's shapes as a backdrop, an icon container or a mask for a photo |
-| <img src="../previews/data-display-badge.webp" width="96" alt=""> | [Badge](#badge) | Pill label in seven tones |
+| <img src="../previews/data-display-badge.webp" width="96" alt=""> | [Badge](#badge) | Status pill, 20 px, in seven tones, soft or outlined |
 | <img src="../previews/data-display-countbadge.webp" width="96" alt=""> | [CountBadge](#countbadge) | Count in the corner of its children |
 | <img src="../previews/data-display-dayseparator.webp" width="96" alt=""> | [DaySeparator](#dayseparator) | "Today", "Yesterday" or the date between two hairlines |
 | <img src="../previews/data-display-periodcards.webp" width="96" alt=""> | [PeriodCards](#periodcards) | Consecutive date ranges (terms, sprints) as cards, with a current marker and an optional link per card |
@@ -210,20 +210,25 @@ and no lazy loading: give `src` the size you need.
 
 ![Badge](../previews/data-display-badge.webp)
 
-Pill label: default, secondary, error, success, info, warning, outlined.
+Status badge: a 20 px pill with the `label-sm` text, compact padding and no hover or pointer affordance. Use `soft` (a tonal fill from the tone tokens) for a state; `outlined` is a thin 1 px line at 40 % of the tone. Every tone stays at 4.5:1 or more in the light and dark themes and follows the theme presets.
 
 ```tsx
 import { Badge } from '@nxgt/material/components';
 
-<Badge variant="success">Paid</Badge>
+<Badge variant="soft" tone="success">Paid</Badge>
+<Badge variant="outlined" tone="error">Late</Badge>
+<Badge variant="success">New</Badge>
 ```
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `variant` | `'default' \| 'secondary' \| 'error' \| 'success' \| 'info' \| 'warning' \| 'outlined'` | `'default'` | tone |
+| `variant` | `'default' \| 'secondary' \| 'error' \| 'success' \| 'info' \| 'warning' \| 'soft' \| 'outlined'` | `'default'` | the filled tones, `soft` (recommended for a state) or `outlined` |
+| `tone` | the eight named tones, or a tone of your own declared in `AppTones` | `'neutral'` | the colour of a `soft` or `outlined` badge; ignored by the filled variants |
 | `asChild` | `boolean` | `false` | renders its child (a link) with the badge styles |
 
-**Storybook:** `Data display/Badge` · **Vue:** `Badge`
+A `Badge` link (`asChild`) no longer fades on hover: a badge is a status, not a button. Put a `Chip` or a `Button` where the user acts.
+
+**Storybook:** `Data display/Badge` (Soft, SoftContrast) · **Vue:** `Badge` (without `soft` and `tone` yet)
 
 ---
 
@@ -428,12 +433,22 @@ import { StatCard } from '@nxgt/material/components';
 | `tone` | the eight named tones, or a tone of your own declared in `AppTones` | — | the value is drawn in the tone's text colour and the icon sits on a chip of its container. Without one the card is as before |
 | `variant` | `'outlined' \| 'tonal' \| 'filled'` | `'outlined'` | `tonal` paints the card with the tone's container and a fine outline in its text colour (3:1 against the page); `filled` paints it with the tone and draws everything on it in the on-colour. Both use `neutral` when there is no `tone`. Every text is 4.5:1 or more. In a [calm zone](../guides/theming.md#calm-zone), a `tonal` or `filled` card is the card's own surface with the tone's ring, and its icon chip a ring |
 | `valueSize` | `'default' \| 'display'` | `'default'` | `display` draws the value larger (`headline-large`) |
+| `size` | `'default' \| 'sm'` | `'default'` | `sm` is a compact tile for a band or a header (see below); it ignores `hint`, `delta` and `valueSize` |
 
 ```tsx
 <StatCard tone="success" variant="tonal" valueSize="display" label="Revenue" value="€48,200" delta={12.4} icon={<CreditCard />} />
 ```
 
-Parts: the root carries `data-slot="stat-card"`, `data-variant` and, when a tone applies, `data-tone` (the tone, or `neutral` on a `tonal` or `filled` card without one); the icon wrapper carries `data-slot="stat-card-icon"`. The types `StatCardProps`, `StatCardVariant` and `StatCardValueSize` are exported.
+**Compact tile (`size="sm"`).** For figures in a header band: a tile 40 to 56 px tall that hugs its content, the optional icon chip, then the value (tabular figures) over its label. It takes the same `tone` and `variant` (`tonal`, `outlined`, `filled`); `hint`, `delta` and `valueSize` are ignored (nothing is drawn for them, and `loading` shows a skeleton in place of the value only). Tiles in a `flex flex-wrap gap-2` row sit side by side and wrap on a phone.
+
+```tsx
+<div className="flex flex-wrap gap-2">
+  <StatCard size="sm" variant="tonal" tone="primary" label="Students" value={22} />
+  <StatCard size="sm" variant="tonal" tone="tertiary" label="Classes" value={6} />
+</div>
+```
+
+Parts: the root carries `data-slot="stat-card"`, `data-variant` and, when a tone applies, `data-tone` (the tone, or `neutral` on a `tonal` or `filled` card without one); the icon wrapper carries `data-slot="stat-card-icon"`. The compact tile adds `data-size="sm"`. The types `StatCardProps`, `StatCardVariant`, `StatCardValueSize` and `StatCardSize` are exported.
 
 In `filled`, the delta and its trend arrow take the on-colour too (the arrow and the sign still say up or down). The outline's share is `--stat-card-ring-share` (`68%`, or `--nxgt-tone-ring-share` for every ring); it draws the tonal card's border, the filled card's edge in a calm zone and the hairline round the icon chip. Known limit: the dark theme's primary `filled` card has an edge of about 2.3:1 on a `Card` and 2.5:1 on the page (its text is 7:1); a `tonal` card avoids it. See [App tones](../guides/theming.md#app-tones-on-shape-fab-avatar-statcard-and-the-metric-cards).
 
@@ -618,10 +633,24 @@ import { Badge, EntityHeader } from '@nxgt/material/components';
 | `title` | `ReactNode` | — | the `h1`; optional: without it no heading is rendered (see below) |
 | `icon`, `status` | `ReactNode` | — | before and after the title; `icon` is decoration, shown in an `aria-hidden` badge, so put nothing meaningful or focusable there |
 | `metadata` | `{ label: string; value: ReactNode }[]` | `[]` | facts under the title, a description list: a muted label beside its value, no colon; a link in a value is drawn in the primary text colour (`text-primary-text`), not the prose link's info blue, and `nxgt-plain-link` still opts out |
+| `stats` | `EntityStat[]` | `[]` | figures (counts, a mean) as compact `size="sm"` [StatCard](#statcard) tiles in a wrapping row under the metadata; a `tone` paints a tile, `0` is a figure, an empty value drops the tile (see Stats below) |
 | `actions` | `ResponsiveButtonProps[] \| ReactNode` | `[]` | an array becomes responsive buttons (icon-only on phones) |
 
 The root carries `data-slot="entity-header"`; the metadata is a `dl` with `data-slot="entity-metadata"` (a muted `dt` label beside its `dd` value, no colon), and the actions sit in `data-slot="entity-header-actions"` (absent when there are none). Inside an EntityHeader that replaces the old `summary-data` slot and its `Label:` text, so update a selector or a test that read "Label: value".
 
+**Stats.** Figures (counts, a mean) go in `stats`, shown as compact [StatCard](#statcard) tiles (`size="sm"`) in a wrapping row under the metadata; facts (dates, names) stay in `metadata`. A `tone` paints a tile (tonal), none leaves it outlined; `0` is a figure, an empty value drops the tile. The row is `data-slot="entity-stats"`, and the type `EntityStat` is exported.
+
+```tsx
+<EntityHeader
+  title="Class 6A"
+  metadata={[{ label: 'Year', value: '2026-2027' }]}
+  stats={[
+    { label: 'Students', value: 24, tone: 'primary' },
+    { label: 'Coefficient', value: 2 },
+  ]}
+/>
+```
+
 `title` is optional. A record page whose `h1` is the app bar's title (`handle.title`, `AppShellHandle.title`, see the [app shell guide](../guides/app-shell.md#the-pages-title-in-the-app-bar)) uses EntityHeader without it, so the page keeps a single heading:
 
 ```tsx
@@ -653,15 +682,17 @@ With a title, in a narrow container (under `@sm`) the order is title, metadata,
 Row with leading / trailing slots, title and subtitle; becomes a link or button when interactive. `size="sm"` is the dense row.
 
 ```tsx
-import { ChevronRight } from 'lucide-react';
 import { ListTile } from '@nxgt/material/components';
 
-<ListTile title="Notifications" subtitle="Email and push" trailing={<ChevronRight />} href="/settings/notifications" />
+<ListTile title="Notifications" subtitle="Email and push" href="/settings/notifications" />
 ```
 
+A tile with an `href` ends with a discreet chevron after `trailing`: decorative (`aria-hidden`, so the link's name stays its text) and flipped in right-to-left. `chevron={false}` opts out; `chevron` on a button tile (an `onClick` that navigates) opts in.
+
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `href` | `string` | — | renders an `<a>` |
+| `href` | `string` | — | renders an `<a>`, with a chevron by default |
+| `chevron` | `boolean` | `true` with an `href`, else `false` | the decorative chevron after `trailing` |
 | `linkComponent` | `AppShellLinkComponent` | plain `<a>` | the link element, as in the app shell: takes `href`, spreads every other prop, forwards `ref` |
 | `onClick` | `MouseEventHandler` | — | renders a `<button>` |
 | `selected` | `boolean` | `false` | highlighted row |

package/docs/components/feedback-and-status.md

@@ -7,7 +7,7 @@ centre.
 | | Component | What it does |
 | --- | --- | --- |
 | <img src="../previews/feedback-status-alert.webp" width="96" alt=""> | [Alert](#alert) | Callout with icon, title and description in seven tones |
-| <img src="../previews/feedback-status-banner.webp" width="96" alt=""> | [Banner](#banner) | Dismissible banner with an action |
+| <img src="../previews/feedback-status-banner.webp" width="96" alt=""> | [Banner](#banner) | Dismissible banner with an action, in the look of Alert |
 | <img src="../previews/feedback-status-alertdialog.webp" width="96" alt=""> | [AlertDialog](#alertdialog) | Parts for a blocking confirmation dialog |
 | <img src="../previews/feedback-status-confirmdialog.webp" width="96" alt=""> | [ConfirmDialog](#confirmdialog) | Confirm / cancel dialog, `ConfirmationDialog`, `CustomAlertDialog` |
 | <img src="../previews/feedback-status-customdialog.webp" width="96" alt=""> | [CustomDialog](#customdialog) | Ready-made dialog with trigger, icon, title, body and footer |
@@ -63,6 +63,13 @@ The root carries `data-slot="alert"`, the title `data-slot="alert-title"` and th
 
 Dismissible info / success / warning / error banner with an action.
 
+A Banner looks like an [Alert](#alert): the same light tone surface, start
+accent bar, tone-coloured icon, title and description typography and padding.
+They are built on one shared variants module, so they cannot drift. What a
+Banner adds is its role: page level (full width), an `action` and a dismiss
+button. Before 3.12 it was a solid tinted fill with a full tone border and
+rounded corners.
+
 ```tsx
 import { Banner, Button } from '@nxgt/material/components';
 
@@ -754,6 +761,10 @@ longer than the toast (a URL) breaks at its edge instead of pushing the
 action out. With a long message and an action, the action and the X go under
 the text; the icon stays 40px and never squeezes the text.
 
+In a collapsed stack only the front toast's action and X are reachable; the
+ones behind it appear when the stack opens on hover or when focus is inside
+the toaster.
+
 The toast id defaults to the title, so two toasts with the same title
 replace each other; pass `options: { id }` to show both. `Toaster` wraps
 Sonner's and takes its props (`position`, `expand`, `richColors`…), all

package/docs/components/navigation-and-layout.md

@@ -7,7 +7,7 @@ documentation-site shell. Everything is imported from
 
 | | Component | What it does |
 | --- | --- | --- |
-| <img src="../previews/navigation-layout-appshell.webp" width="96" alt=""> | [ActivityLayout](#activitylayout) | App shell: sidebar, header, breadcrumbs, titled page; a route's `handle.title` is the page's `h1` in the app bar (it labels `main`; `usePageTitleFocus()` focuses it after a navigation), `breadcrumbRoot` a text root crumb, `context` the tenant line atop the phone's menu sheet; `menuOpen` / `onMenuOpenChange` control the phone's menu sheet, which closes itself on a followed link or any location change |
+| <img src="../previews/navigation-layout-appshell.webp" width="96" alt=""> | [ActivityLayout](#activitylayout) | App shell: sidebar, header, breadcrumbs, titled page; a route's `handle.title` is the page's `h1` in the app bar (it labels `main`; `usePageTitleFocus()` focuses it after a navigation), `breadcrumbRoot` a text root crumb, `breadcrumb={false}` no trail, `context` the tenant line atop the phone's menu sheet; `menuOpen` / `onMenuOpenChange` control the phone's menu sheet, which closes itself on a followed link or any location change |
 | <img src="../previews/navigation-layout-accountmenu.webp" width="96" alt=""> | [AccountMenu](#accountmenu) | The app bar's avatar menu: the account, the app's links, Sign out |
 | <img src="../previews/navigation-layout-authcard.webp" width="96" alt=""> | [AuthCard](#authcard) | Signed-out page frame: one `main`, a centred card, its title the `h1` |
 | <img src="../previews/navigation-layout-sidebar.webp" width="96" alt=""> | [Sidebar](#sidebar) | Collapsible navigation sidebar |
@@ -64,7 +64,7 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `items` | `MenuItem[]` | — | `label` (already translated), `url`, `icon`, `footer`, `badge` (`true` a dot, a number a count up to "99+"), `badgeLabel` (see [Badges](../guides/app-shell.md#badges)) |
+| `items` | `MenuItem[]` | — | `label` (already translated), `url`, `icon`, `footer`, `display` (`'icon'`: a round icon-only button, the label as tooltip and name; see the [app shell guide](../guides/app-shell.md)), `badge` (`true` a dot, a number a count up to "99+"), `badgeLabel` (see [Badges](../guides/app-shell.md#badges)) |
 | `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href`; see the [app shell guide](../guides/app-shell.md) |
 | `logo`, `name` | `AppLogo` (`ReactNode \| string \| AppLogoImage`, `AppLogoImage` = `{ src, alt? }`), `string` | — | the app's logo alone in the collapsed rail, named by `name` (also its tooltip); logo and name side by side in the phone's menu sheet |
 | `context` | `ReactNode` | — | 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; `AppHeader` and `AppSidebar` take it too (see the [app shell guide](../guides/app-shell.md#the-brand-logo-and-name)) |
@@ -72,6 +72,7 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 | `avatar` | `ReactNode` | — | an image URL or a node, in the header |
 | `headerTitle` | `ReactNode` | — | the header's leading title (the context: an organisation's name), after the phone's menu button, truncated when long; when it is cut off, its full text is the `title` tooltip (#629) |
 | `handle.title` | `ReactNode \| (match: UIMatch) => ReactNode` | — | on a route: the page's title in the app bar, its one `h1`, in the first server HTML; `ActivityContent` leaves its own title out while it is set (see the [app shell guide](../guides/app-shell.md#the-pages-title-in-the-app-bar)) |
+| `breadcrumb` | `boolean` | `true` | `false` hides the breadcrumb trail (an error page); it is also hidden when every matched `handle.breadcrumb` renders `null`; see the [app shell guide](../guides/app-shell.md#breadcrumbs) |
 | `breadcrumbRoot` | `{ label: ReactNode; to: string }` | — | the breadcrumb's first crumb, a text link in place of the home icon (`AppBreadcrumb`'s `root`); see the [app shell guide](../guides/app-shell.md#breadcrumbs) |
 | `headerActions` | `ReactNode` | — | header, before the avatar |
 | `title`, `subtitle`, `actions` | `ReactNode` | — | `ActivityContent`'s header card; `title` is left out while a route's `handle.title` puts the page's title in the app bar |

package/docs/guides/app-shell.md

@@ -82,6 +82,7 @@ type MenuItem = {
   url: string;
   icon: IconName;     // a symbol of the duotone sprite, see Getting started › Icons
   footer?: boolean;   // pin to the sidebar footer
+  display?: 'icon';   // a round, icon-only button; see below
   badge?: number | boolean | ReactNode; // see Badges
   badgeLabel?: string; // the badge's text in the link's name, already translated
 };
@@ -103,6 +104,22 @@ type MenuItem = {
 
 - **`footer: true` pins an entry to the footer.** Being last in the list does
   not: appending an entry never moves another one out of the footer.
+- **`display: 'icon'` draws the entry as a round, icon-only button.** Meant
+  for the footer's "Settings": in the collapsed rail, the expanded sidebar and
+  the phone's menu sheet alike, it is an `IconButton` (the Button family's
+  look, ghost, tonal when it is the active entry) with the label as its
+  tooltip and, visually hidden, its accessible name, `aria-current="page"`
+  when active, and a 44px target on a coarse pointer. The entries without it
+  keep their icon and label. An icon entry draws no `badge`.
+
+  ```tsx
+  { label: t('menu.settings'), url: '/settings', icon: 'gear', footer: true, display: 'icon' }
+  ```
+
+- The active entry's icon and label are in primary on the rail: a darker
+  primary in light (85 % of its lightness, so the label reads 4.5:1 on its
+  pill for every theme preset) and a lavender of its hue in dark; see
+  [the sidebar tokens](./theming.md).
 - The icons are drawn with `Icon type="duotone"`, so the duotone sprite must
   be served ([getting started](../getting-started.md#icons)).
 
@@ -183,6 +200,7 @@ partitionMenu(items);                              // { content, footer }
 | `avatar` | `ReactNode` | — | End of the header. A `string` is used as the image URL of an `Avatar`; anything else is rendered as-is |
 | `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href` (see below) |
 | `headerTitle` | `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 when long; when it is cut off, its full text is the `title` tooltip (#629) |
+| `breadcrumb` | `boolean` | `true` | `false` hides the breadcrumb trail, for an error page whose matched routes would show a misleading one (see [Breadcrumbs](#breadcrumbs)) |
 | `breadcrumbRoot` | `AppBreadcrumbRoot` (`{ label: ReactNode; to: string }`) | — | The breadcrumb's first crumb, in place of the home icon: a text link to `to` (see [Breadcrumbs](#breadcrumbs)) |
 | `headerActions` | `ReactNode` | — | In the header, before the avatar: notifications, help, `ThemeToggle` |
 | `children` | `ReactNode` | — | The routed content, usually `<Outlet />` |
@@ -498,11 +516,23 @@ or an `NxgtTheme` zone around it; see [Themes](./theming.md#the-provider-and-zon
 | `backdrop={<Background … />}` | that node, for this screen |
 | `backdrop={false}` | no background and no blobs: a plain page (`data-plain` on the root) |
 
-The theme's shapes (the motif and illustrated presets) stay whole: a shape that
-would cross the layer's edge, or reach the app bar, the breadcrumb, the header
-card or an `EntityHeader`, is not drawn, and nothing shows until that first
-check has run. Full-width textures such as `waves` and the gradient are not
-shapes and are not filtered. A `Background` passed as `backdrop` is kept whole the same way; any other node is left as it is.
+**Where the shapes go.** The theme's shapes (the motif and illustrated presets)
+are drawn whole or not at all, and only in empty space. A shape that would cross the layer's edge,
+or reach the app bar, the breadcrumb, the header card or an `EntityHeader`, is
+not drawn (a permanent exclusion). A shape that lies over (or within 8px of) the page's text or
+controls (inputs, buttons, links, images, and every line of text) is hidden: it
+fades out in 150ms (none under `prefers-reduced-motion`) and fades back once
+the content moves away, for instance when the page scrolls or a list changes.
+Shapes are hidden, never moved. The check reads the content when it changes or
+resizes and keeps the boxes, so a scroll only shifts them (one `requestAnimationFrame`-throttled
+pass, well under a millisecond on a typical page; text past the first 6000 boxes is not collected, so a shape may be drawn over it). A moon, a planet or an eclipse counts as one shape: it is hidden whole, with its halo. Limits: a sticky element is measured where it is laid out, not where it sticks, and a late font or image, or an inner scroller, triggers a new check a moment later. Nothing shows until the first
+check has run, so no shape flashes over the content. On a phone, where the
+content fills the width, the shapes you see are the ones in the empty part of
+the page, usually below the content. Full-width textures such as `waves` and the
+gradient are not shapes and are not filtered. A `Background` passed as
+`backdrop` follows the same rule; any other node is left as it is. The layer is
+below the content in z-order (`-z-10` in the column's own stacking context), so
+a dialog, a sheet or a sticky header is always above it.
 
 `backdrop={false}` used to draw the built-in gradient, as if it were left out;
 it now removes it. To keep the gradient, leave `backdrop` out. A theme's
@@ -522,7 +552,7 @@ to know the theme on the server (a cookie, passed to `defaultTheme`).
 
 The shell draws the gradient with three blurred blobs behind its frame. To use
 one of the 50 presets of `@nxgt/material/backgrounds` instead, pass it as
-`backdrop`:
+`backdrop` (behind the shell its shapes show only in empty space, see [Where the shapes go](#the-themes-background)):
 
 ```tsx
 import { Outlet } from 'react-router';
@@ -559,7 +589,7 @@ export function Shell({ items }: { items: MenuItem[] }) {
   `scroll="container"` alike.
 - **The chrome is lightly translucent and frosted.** Under a `backdrop`, the
   app bar, the breadcrumb (a pill as wide as its crumbs) and the tabs strip
-  show a shape faintly through their fill, over a 6px blur that keeps it from
+  show the backdrop faintly through their fill, over a 6px blur that keeps it from
   competing with a text. The lists and tables (band and rows), the segmented
   `ToggleGroup`, the list bar, the phone tiles and the cards stay opaque, so no
   shape runs behind a row. The sidebar is frosted too (87%), but the layer is
@@ -797,7 +827,21 @@ to the router's root, then adds one crumb per matched route that has a
 the trail. The last crumb is text (`aria-current="page"`); the others are
 links, each inside its `<li>`. The home icon is itself the link, named "Home"
 (`material.app-shell.home`, translated): `getByRole('link', { name: 'Home' })`.
-The trail is hidden when no route has a breadcrumb.
+The trail is hidden when no route has a breadcrumb. A crumb whose
+`handle.breadcrumb` returns `null` (or `undefined`, `false`) is left out with
+its separator, as `handle.title` accepts `null`, so the trail is hidden too
+when every matched route returns `null`.
+
+An error page rendered by `ActivityLayout` still matches the failed route, so
+it would show its trail ("Home > Section" on a 404). Pass `breadcrumb={false}`
+to render the layout without the trail:
+
+```tsx
+// the root route's errorElement
+<ActivityLayout items={items} breadcrumb={false}>
+  <ActivityContent title="Page not found" />
+</ActivityLayout>
+```
 
 A multi-tenant app whose root is the current tenant passes `breadcrumbRoot`
 (`AppBreadcrumb`'s `root`) to replace the home icon with a text link,

package/docs/guides/backgrounds.md

@@ -181,6 +181,8 @@ of path data; `low-poly` is about 20 KB (210 nodes); `circuit` about 9 KB (90 no
 
 <img src="../previews/backgrounds-motifs.webp" width="480" alt="The shapes preset behind a card">
 
+**Behind an `ActivityLayout`** a preset's discrete shapes are hidden wherever they would lie over the page's text or controls, and fade back when the content moves away (see [Where the shapes go](./app-shell.md#the-themes-background)). A `Background` used on its own, on a page you lay out, draws all its shapes.
+
 `shapes`, `confetti-grid`, `constellation`, `halftone`, `truchet`, `floating` and `scatter-icons` draw seeded, deterministic geometry from
 the tone's three colours: the same `seed` gives the same composition on the server and in the
 browser, and a new `seed` redraws it.

package/docs/guides/theming.md

@@ -578,15 +578,16 @@ rail and menu sheet) is drawn with three tokens, in light and in dark:
 | --- | --- | --- | --- |
 | `--sidebar-active` | `bg-sidebar-active` | primary at 15 % | primary at 30 % |
 | `--sidebar-active-hover` | `bg-sidebar-active-hover` | primary at 20 % | primary at 35 % |
-| `--sidebar-active-foreground` | `text-sidebar-active-foreground` | `--primary` | `oklch(from var(--primary) 0.72 0.15 h)`, 6.3:1 or more on the pill |
+| `--sidebar-active-foreground` | `text-sidebar-active-foreground` | `oklch(from var(--primary) calc(l * 0.85) c h)`, 4.5:1 or more on the pill for every theme preset | `oklch(from var(--primary) 0.72 0.15 h)`, 6.3:1 or more on the pill |
 
 The pill is the icon's (collapsed rail) or the whole row (expanded), a pill in the collapsed rail and, in the expanded row, an `--nxgt-item-radius` (6px) shape that carries the 3px start bar every chosen row has, drawn in `--sidebar-active-foreground` (a `Highlight` bar in forced colours); the
 foreground is the label and the icon, whose duotone layers both follow it (in
 dark too: the icon of `AppSidebar` is the lifted lavender like its label). The
 label is read on the pill (expanded) or on the sidebar (collapsed rail); the
 icon, on the pill. In browsers without relative colour syntax (before Chrome
-119, Safari 18, Firefox 128) the dark foreground falls back to `--primary`
-itself, as the dark lift needs `oklch(from …)`.
+119, Safari 18, Firefox 128) the foreground falls back to `--primary`
+itself in light and dark, as both the light darkening and the dark lift need
+`oklch(from …)`.
 
 The defaults are derived where the entry is drawn, from the `--primary` it
 sits under, so a `--primary` set on a wrapper recolours the rail inside it.

package/docs/roadmap.md

@@ -308,6 +308,24 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **Display polish** — `Badge` is a status badge: a 20 px pill with the
+  `label-sm` text and no hover, a `soft` variant (the tone's container under
+  the tone's text, 4.5:1) and a `tone` prop for `soft` and `outlined`, taking
+  your own tones too; `CountBadge` keeps its own size. `ListTile` with an
+  `href` ends with a discreet chevron (`chevron={false}` opts out). `StatCard`
+  gets a compact `size="sm"` tile and `EntityHeader` a `stats` prop that shows
+  figures as these tiles. `Banner` takes `Alert`'s look. A footer `MenuItem`
+  can be `display: 'icon'`, a round icon-only button with a tooltip, 44 px on
+  a touch screen; the rail's active label is drawn in a darker primary so it
+  reads 4.5:1 on every theme preset. `breadcrumb={false}` hides the trail, and
+  so does a trail whose crumbs all render `null` (#1475). `Combobox` rows are
+  touch-sized on a touch screen (#1474). The backdrop's shapes are hidden while
+  they lie over the page's text or controls, never moved (#1478). Nothing
+  changes in core. React only; the
+  Vue port is a `vue` issue. Ships in 3.12.0.
+  ([Data display](components/data-display.md),
+  [App shell](guides/app-shell.md))
+
 - **Buttons and the type scale in Material 3 Expressive** — `Typography` takes
   the Material 3 scale (`display`, `headline`, `title`, `body`, `label`, each
   `lg`, `md` and `sm`, plus `emphasized`) as Tailwind tokens: `text-title-md`

package/docs/troubleshooting.md

@@ -109,6 +109,7 @@ words in your error.
 
 **Navigation**
 
+- [A `ListTile` link shows two chevrons](#a-listtile-link-shows-two-chevrons)
 - [A `ListTile` link reloads the whole page](#a-listtile-link-reloads-the-whole-page)
 - [After a link in the phone menu, the focus goes to `<main>`, not to the page's title](#after-a-link-in-the-phone-menu-the-focus-goes-to-main-not-to-the-pages-title)
 - [The phone menu needs two Escapes to close, or a tooltip shows over it](#the-phone-menu-needs-two-escapes-to-close-or-a-tooltip-shows-over-it)
@@ -979,8 +980,9 @@ your token against the page at 4.5:1:
 <Button variant="tonal" color="error">Delete</Button>
 ```
 
-A `Badge` link of your own with a hover fade such as `[a&]:hover:bg-error/90`
-in its `className` puts the fade back: darken instead, as in
+A `Badge` no longer changes on hover; a hover fade of your own such as
+`[a&]:hover:bg-error/90` in its `className` puts the fade back: darken
+instead, as in
 `[a&]:hover:bg-[color-mix(in_oklab,var(--color-error)_90%,black)]` (with
 your badge's colour in place of `error`). A
 subtitle colour of your own on a selected `ListTile` must reach 4.5:1 on
@@ -1974,6 +1976,19 @@ tree.
 
 ## Navigation
 
+### A `ListTile` link shows two chevrons
+
+**When:** a `ListTile` with an `href` and a `trailing={<ChevronRight />}` of
+your own draws a second chevron since the tile adds one.
+**Why:** a link tile ends with a decorative chevron by default.
+**Fix:** drop your own, or keep it and pass `chevron={false}`:
+
+```tsx
+<ListTile title="Notifications" href="/settings/notifications" />
+// or, with your own icon
+<ListTile title="Notifications" href="/settings/notifications" chevron={false} trailing={<MyArrow />} />
+```
+
 ### A `ListTile` link reloads the whole page
 
 **When:** a `ListTile` with an `href` is clicked inside a router app: the

package/lib/components/components.css

@@ -55,6 +55,7 @@
 /* ActivityLayout: the route transition (cross-fade, none under reduced motion). */
 @import "./ui/layout/app-shell/route-transition.css";
 @import "./ui/layout/app-shell/activity-backdrop.css";
+@import "./ui/layout/app-shell/activity-backdrop-shapes.css";
 /* DataTable cards and tiles: the item shell (hairline, tint, start bar, columns by the list's width). */
 @import "./ui/collections/data-table/data-table-items.css";
 @import "./ui/collections/data-table/data-table-items-compact.css";

package/lib/components/ui/feedback/toast/toast-expressive.css

@@ -107,6 +107,23 @@
 		gap: 8px;
 		margin-inline-start: auto;
 	}
+	/* A stacked toast behind the front one (`data-expanded="false"`,
+	 * `data-front="false"`) sits under it, scaled and offset by a few pixels:
+	 * its buttons are covered, so a tap lands on the front toast, and a covered,
+	 * scaled close button fails axe's `target-size` (#1480). Its buttons are
+	 * hidden until the stack opens (sonner opens it on hover, not on focus) or
+	 * focus is inside the toaster, so a Tab from the front toast still reaches
+	 * them. Sonner's own `opacity: 0` for these does not apply to our unstyled
+	 * (`data-styled="false"`) toasts. */
+	[data-sonner-toast][data-expanded="false"][data-front="false"]
+	.nxgt-toast-buttons {
+		visibility: hidden;
+	}
+	[data-sonner-toaster]:focus-within
+		[data-sonner-toast][data-expanded="false"][data-front="false"]
+		.nxgt-toast-buttons {
+		visibility: visible;
+	}
 	.nxgt-toast-title {
 		color: var(--toast-fg);
 	}

package/lib/components/ui/layout/app-shell/activity-backdrop-shapes.css

@@ -0,0 +1,49 @@
+/* Which shapes of the backdrop show (observe-layout.ts, watch-content.ts).
+ * Plain CSS in `@layer components`, beside activity-backdrop.css. */
+@layer components {
+	/* The theme's backdrop keeps its shapes whole (keep-shapes-inside.ts):
+	 * the scene waits for the first pass, then a shape that would cross the
+	 * layer's edge or reach the header band is hidden, never cut. */
+	[data-keep-inside]:not([data-checked]) .mo,
+	[data-slot="activity-layout-backdrop"]
+		[data-background]:not([data-checked])
+		.mo {
+		visibility: hidden;
+	}
+	[data-keep-inside] .mo > [data-outside],
+	[data-slot="activity-layout-backdrop"]
+		[data-background]
+		.mo
+		> [data-outside] {
+		visibility: hidden;
+	}
+
+	/* A shape over the page's text or controls fades out and comes back once
+	 * clear (watch-content.ts): it is hidden, never moved. A compound body (the
+	 * moon, the planet, the eclipse: `.pt.mg`) is hidden whole, with its halo
+	 * (`.pt.mh`). The scene stays invisible until the first check, so nothing
+	 * flashes over the content. */
+	[data-keep-inside] .mo > *,
+	[data-keep-inside] .pt,
+	[data-slot="activity-layout-backdrop"] [data-background] .mo > *,
+	[data-slot="activity-layout-backdrop"] [data-background] .pt {
+		transition: opacity 150ms ease;
+	}
+	/* Important: a preset sets its own opacity on a body (`.md`, the dark
+	 * moon's, a celestial body's); in a layer, `!important` beats every normal
+	 * declaration of those. The 150 ms transition still runs. */
+	[data-keep-inside] .mo > [data-hidden],
+	[data-keep-inside] .pt[data-hidden],
+	[data-slot="activity-layout-backdrop"] [data-background] .mo > [data-hidden],
+	[data-slot="activity-layout-backdrop"] [data-background] .pt[data-hidden] {
+		opacity: 0 !important;
+	}
+	@media (prefers-reduced-motion: reduce) {
+		[data-keep-inside] .mo > *,
+		[data-keep-inside] .pt,
+		[data-slot="activity-layout-backdrop"] [data-background] .mo > *,
+		[data-slot="activity-layout-backdrop"] [data-background] .pt {
+			transition: none;
+		}
+	}
+}

package/lib/components/ui/layout/app-shell/activity-backdrop.css

@@ -77,23 +77,6 @@
 		display: none;
 	}
 
-	/* The theme's backdrop keeps its shapes whole (use-keep-shapes-inside.ts):
-	 * the scene waits for the first pass, then a shape that would cross the
-	 * layer's edge or reach the header band is hidden, never cut. */
-	[data-keep-inside]:not([data-checked]) .mo,
-	[data-slot="activity-layout-backdrop"]
-		[data-background]:not([data-checked])
-		.mo {
-		visibility: hidden;
-	}
-	[data-keep-inside] .mo > [data-outside],
-	[data-slot="activity-layout-backdrop"]
-		[data-background]
-		.mo
-		> [data-outside] {
-		visibility: hidden;
-	}
-
 	/* A preset fills the layer: the layer's size, not `100lvw x 100lvh`, which
 	 * counts the scrollbar and a phone's toolbar. */
 	[data-slot="activity-layout-backdrop"] > [data-background] {

package/lib/components/ui/layout/sidebar/sidebar-tokens.css

@@ -3,13 +3,18 @@
 :root {
 	/* The active entry of the sidebar and the navigation rail: its tint, the
 	 * tint hovered, the start bar (the label's colour), and the icon and label drawn on it. Translucent primary
-	 * (these shares, 15 % and 20 % hovered); the label is primary itself. The
+	 * (these shares, 15 % and 20 % hovered); the label is primary at 85 % of its lightness in light (a lavender of its hue in dark). The
 	 * utilities (`bg-sidebar-active`...) derive them on the element, so they
 	 * follow a `--primary` set below :root. To theme the rail set
 	 * `--sidebar-active`, `--sidebar-active-hover` and
 	 * `--sidebar-active-foreground` (all three, or the first two and the
 	 * foreground); the derived colours are not declared here, on purpose. */
 	--nxgt-sidebar-active-share: 15%;
+	/* Light: primary itself reads 4.5:1 on the page but not on its own 15 % pill
+	 * for every preset (corail 3.7:1), so the label is primary darkened to 85 %
+	 * of its lightness (4.99:1 on the worst preset, hovered). The preset spec
+	 * (sidebar-active-contrast.test.ts) reads this number back. */
+	--nxgt-sidebar-active-l: calc(l * 0.85);
 	/* The height of the app bar and of the rail's header from `md` up, so the
 	 * rail's logo and the bar's title share one centre line. Phones keep the
 	 * bar alone at this height; the menu sheet's header is unconstrained. */
@@ -24,7 +29,7 @@
 	/* The dark theme's primary is too dark to read on its surfaces (2.5:1), so
 	 * the rail's label is a saturated lavender of its hue (5.3:1: lightness
 	 * 0.72, chroma 0.15) on a denser pill (30 %, 35 % hovered). Light keeps the
-	 * lightness and chroma of primary (the `l` and `c` fallbacks). */
+	 * chroma of primary and 85 % of its lightness. */
 	--nxgt-sidebar-active-share: 30%;
 	--nxgt-sidebar-active-hover-share: 35%;
 	--nxgt-sidebar-active-l: 0.72;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "3.11.0",
+	"version": "3.12.1",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -465,6 +465,7 @@
 		"@vitejs/plugin-react": "6.0.4",
 		"@vitest/browser-playwright": "4.1.10",
 		"ajv": "^8.20.0",
+		"axe-core": "4.12.1",
 		"globals": "^17.7.0",
 		"hls.js": "^1.7.3",
 		"leaflet": "^1.9.4",