@nxgt/material 3.12.0 → 3.13.0

package/dist/{use-heading-spy-DXo6IOX9.js → use-heading-spy-DETdqnB6.js}

@@ -1,4 +1,4 @@
-import { r as e } from "./i18n-provider-C6HhBw34.js";
+import { r as e } from "./i18n-provider-GV4Ukoe2.js";
 import { _ as t, g as n, h as r, n as i, v as a, y as o } from "./number.utils-BG_eEt5g.js";
 import { useCallback as s, useEffect as c, useMemo as l, useRef as u } from "react";
 //#region ../../node_modules/date-fns/locale/fr/_lib/formatDistance.js

package/dist/{use-material-translation-B3V_bz-5.js → use-material-translation-DGeVp-qP.js}

@@ -1,5 +1,5 @@
-import { r as e } from "./i18n-provider-C6HhBw34.js";
-import { t } from "./translate-material-Bd_KgfB8.js";
+import { r as e } from "./i18n-provider-GV4Ukoe2.js";
+import { t } from "./translate-material-C0aOnHpZ.js";
 import { useCallback as n } from "react";
 //#region lib/i18n/use-material-translation.ts
 function r() {

package/docs/components/data-display.md

@@ -66,6 +66,12 @@ The hairline's strength is `--avatar-ring-share`, the share of the tone's text c
 :root { --avatar-ring-share: 80%; }
 ```
 
+**Initials scale with the size.** The fallback's text is 40 % of the avatar's diameter (never under 10 px), whatever the size class (`size-6` to `size-16` and beyond): two letters keep clear of the edge at 32 px and grow on a larger avatar. The colours are the tone's, so the text stays 4.5:1. The avatar is a size container (`container-type: inline-size`) and the share is `--avatar-text-share` (a unitless number, `40` by default):
+
+```css
+:root { --avatar-text-share: 36; }
+```
+
 A fallback you restyle with `className` keeps the hairline: pass `shadow-none` (or a `tone`) for a filled look, for instance `<AvatarFallback className="bg-primary text-primary-foreground shadow-none">`. A toneless `AvatarFallback` inside `<AvatarBase tone="success">` inherits the root's tone. `AvatarFallback` needs an `Avatar` or `AvatarBase` ancestor (or its own `tone`) to be coloured: on its own it renders transparent, with no hairline.
 
 A shaped avatar:
@@ -83,7 +89,7 @@ The fallback with no `tone` is neutral: the neutral tone's container (it was the
 <Avatar shape="cookie-9" fallback="MK" tone="maths" /> {/* a tone the app declared in AppTones */}
 ```
 
-**Storybook:** `Data display/Avatar` (`Shapes`, `ShapedFallbacks`), `Data display/Avatar/Tones` · **Vue:** `Avatar` (`status`, `status-pulse`), `AvatarImage`, `AvatarFallback`
+**Storybook:** `Data display/Avatar` (`Shapes`, `ShapedFallbacks`), `Data display/Avatar/Initials` (`InitialsScale`), `Data display/Avatar/Tones` · **Vue:** `Avatar` (`status`, `status-pulse`), `AvatarImage`, `AvatarFallback`
 
 ---
 
@@ -439,7 +445,7 @@ import { StatCard } from '@nxgt/material/components';
 <StatCard tone="success" variant="tonal" valueSize="display" label="Revenue" value="€48,200" delta={12.4} icon={<CreditCard />} />
 ```
 
-**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.
+**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; for an even layout use `StatCardGroup`.
 
 ```tsx
 <div className="flex flex-wrap gap-2">
@@ -448,11 +454,24 @@ import { StatCard } from '@nxgt/material/components';
 </div>
 ```
 
+**`StatCardGroup`: an even grid of compact tiles.** Four hugging tiles leave an orphan at 360 px. Wrap the `size="sm"` tiles in a `StatCardGroup`: while the group is narrower than `md` (28 rem, its own width, not the window's) the tiles are two equal columns, 2×2 for four (an odd last tile takes the whole row); from there they are one row of tiles that hug their content, wrapping if they must. It takes the props of a `div`; the root is `data-slot="stat-card-group"` and `StatCardGroupProps` is exported. `EntityHeader`'s `stats` use it.
+
+```tsx
+import { StatCard, StatCardGroup } from '@nxgt/material/components';
+
+<StatCardGroup>
+  <StatCard size="sm" variant="tonal" tone="primary" label="Students" value={22} />
+  <StatCard size="sm" variant="tonal" tone="tertiary" label="Classes" value={6} />
+  <StatCard size="sm" label="Mean" value="12.4" />
+  <StatCard size="sm" label="Absent" value={0} />
+</StatCardGroup>
+```
+
 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).
 
-**Storybook:** `Data display/StatCard`, `Data display/StatCard/Tones` · **Vue:** `StatCard`
+**Storybook:** `Data display/StatCard/Group` (`GroupOnPhone`, `GroupOnDesktop`), `Data display/StatCard/Tones` · **Vue:** `StatCard` (`StatCardGroup` is React only for now)
 
 ---
 
@@ -630,15 +649,16 @@ import { Badge, EntityHeader } from '@nxgt/material/components';
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `title` | `ReactNode` | — | the `h1`; optional: without it no heading is rendered (see below) |
+| `title` | `ReactNode` | — | the heading (an `h1` unless `headingLevel` says otherwise); optional: without it no heading is rendered (see below) |
+| `headingLevel` | `1 \| 2 \| 3` | `1` | the title's heading level: pass `2` or `3` when the page already has its `h1` (a list title beside a detail header); the look does not change |
 | `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) |
+| `stats` | `EntityStat[]` | `[]` | figures (counts, a mean) as compact `size="sm"` [StatCard](#statcard) tiles in a `StatCardGroup` (2×2 on a phone, a wrapping row beside) 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.
+**Stats.** Figures (counts, a mean) go in `stats`, shown as compact [StatCard](#statcard) tiles (`size="sm"`) in a `StatCardGroup` (2×2 on a phone, a row that wraps beside) 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
@@ -667,6 +687,12 @@ import { Badge, EntityHeader } from '@nxgt/material/components';
 
 The root is a plain `div` in every case, never a landmark, so there is no accessible name to supply.
 
+**A page that has its `h1` already.** A detail header beside a list titled "Team" is not the page's title: `headingLevel={2}` keeps one `h1` and an outline in order.
+
+```tsx
+<EntityHeader headingLevel={2} title="Ada Lovelace" metadata={[{ label: 'Role', value: 'Analyst' }]} />
+```
+
 Without a `title` the band is one row at every width: the icon inline before the status and metadata, the content taking the space, the actions at the end of the row or, when they do not fit, wrapped below and still at the end. An `Avatar` as `icon` is drawn without the badge around it.
 
 With a title, in a narrow container (under `@sm`) the order is title, metadata, `children`, then the actions; from `@sm` the actions sit beside the title, yet they come after the `children` in the DOM and so in focus order.
@@ -695,7 +721,8 @@ A tile with an `href` ends with a discreet chevron after `trailing`: decorative
 | `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 |
+| `selected` | `boolean` | `false` | the current row: drawn selected; a link gets `aria-current="page"` (your own `aria-current` replaces it), a button `aria-pressed` |
+| `toggle` | `Switch` props | — | makes the tile a switch row (see below): the whole row toggles a Switch at its end; `href`, `onClick`, `actions`, `chevron` and `linkComponent` are refused beside it by type |
 | `size` | `'sm' \| 'md'` | `'md'` | `sm` is the dense navigation row |
 | `leading`, `trailing`, `subtitle` | `ReactNode` | — | slots; `trailing` sits inside the link, so it holds decoration only |
 | `actions` | `ReactNode` | — | buttons at the end of the tile, outside the link, vertically centred (`data-slot="item-actions"`) |
@@ -735,11 +762,36 @@ export function SettingsRow() {
 }
 ```
 
+**A selected link, for list-detail navigation.** Give `selected` from the router's location: the open row is a link (a shareable URL), `aria-current="page"` and drawn selected. Pass `aria-current="true"` when the selection is not a page.
+
+```tsx
+import { useLocation } from 'react-router';
+
+function GuideList({ guides }: { guides: { to: string; title: string }[] }) {
+  const { pathname } = useLocation();
+  return (
+    <nav aria-label="Guides">
+      {guides.map((guide) => (
+        <ListTile key={guide.to} title={guide.title} href={guide.to} linkComponent={RouterLink} selected={pathname === guide.to} />
+      ))}
+    </nav>
+  );
+}
+```
+
+**A switch row.** `toggle` takes a Switch's props (`checked`, `defaultChecked`, `onCheckedChange`, `name`, `thumbIcons`…). The tile is then a `<label>` for the switch, so a press anywhere on the row toggles it; the switch is the one tab stop (Space or Enter), named by `title` and described by `subtitle`, and `disabled` on the tile disables it. A switch row is neither a link nor a button: `href`, `onClick`, `actions` and `chevron` do not apply, and `trailing` sits before the switch.
+
+```tsx
+const [on, setOn] = useState(true);
+
+<ListTile title="Notifications" subtitle="Email and push" toggle={{ checked: on, onCheckedChange: setOn }} />
+```
+
 See also [A `ListTile` link reloads the whole page](../troubleshooting.md#a-listtile-link-reloads-the-whole-page). A disabled tile never renders the link component: it is a plain `<a>` without `href`, with `aria-disabled="true"`.
 
 The root carries `data-slot="item-detail"` (a tile that is a button or a plain row too).
 
-**Storybook:** `Data display/ListTile` · **Vue:** `ListTile`
+**Storybook:** `Data display/ListTile`, `Data display/ListTile links`, `Data display/ListTile current` · **Vue:** `ListTile`
 
 ---
 

package/docs/components/data-table-filter-and-lists.md

@@ -87,7 +87,7 @@ table enables, for typing your own column defs.
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `columns` | `ColumnDef<DataTableFeatures, T>[]` | — | `meta.className` styles a column's cells; `meta.label` names the column in the cards sort menu |
+| `columns` | `ColumnDef<DataTableFeatures, T>[]` | — | `meta.className` styles a column's cells; `meta.numeric` sets a column of figures flush to the end in tabular digits (`text-end tabular-nums`, header and cells), so decimals line up; `meta.label` names the column in the cards sort menu |
 | `data` | `T[]` | — | rows; sorting, filtering and pagination run client-side |
 | `layout` | `'table' \| 'cards' \| 'tiles' \| { phone, wide }` | `'table'` | `'cards'` lays the rows out as a list of cards, `'tiles'` as one column in a single surface ([Cards and tiles](../guides/cards-and-tiles.md)); both ignore `virtual`, `renderExpandedRow` and `showViewOptions` |
 | `cardDensity` | `'comfortable' \| 'compact'` | `'comfortable'` | `compact` fits cards of at least `--nxgt-cards-min` (15rem), up to four a row, with a tighter padding; `layout="cards"` only ([Cards and tiles](../guides/cards-and-tiles.md#columns)) |

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

@@ -38,22 +38,40 @@ import { CircleAlert } from 'lucide-react';
 
 <Alert
   variant="warning"
-  icon={<CircleAlert />}
   title="Check the address"
   description="The postcode does not match the city."
 />
 ```
 
+An Alert shows its tone's icon by default, the same one a [Banner](#banner)
+shows (an `info` circle for `primary`, `secondary`, `foreground` and `info`, a
+check, a triangle, an alert circle). Pass `icon={<CircleAlert />}` to use
+your own, or `icon={null}` for none. Before 3.13 an Alert had no icon unless
+you passed one, so an Alert without `icon` now gains one: add `icon={null}` to
+keep the old look.
+
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `variant` | `'primary' \| 'secondary' \| 'success' \| 'info' \| 'warning' \| 'error' \| 'foreground'` | `'primary'` | left border, tint and icon colour |
-| `icon` | `ReactNode` | — | shown before the text; no default icon |
+| `icon` | `ReactNode` | the tone's icon | shown before the text; `null` (or `false`) shows none, any node replaces the tone's icon |
 | `title` | `ReactNode` | — | bold first line |
 | `description` | `ReactNode` | — | muted body text |
 
 The root carries `data-slot="alert"`, the title `data-slot="alert-title"` and the description `data-slot="alert-description"`, for tests and selectors.
 
-**Storybook:** `Feedback & status/Alert` · **Vue:** `Alert`
+**In a form grid.** Inside `.form-grid-layout`'s `[data-slot="form-fields"]` or a [FormSection](form-fields.md#formsection)'s fields, an `Alert` or a `Banner` placed directly in the grid takes the whole row (`col-span-full w-full`) without any class from you; a utility class of your own on it still wins.
+
+```tsx
+<form className="form-grid-layout">
+  <div data-slot="form-fields">
+    <Alert variant="warning" title="Check the address" />
+    <TextField label="Street" />
+    <TextField label="City" />
+  </div>
+</form>
+```
+
+**Storybook:** `Feedback & status/Alert/Tone icon` (`ToneIcon`), `Feedback & status/Alert/In a form grid` (`InFormGrid`) · **Vue:** `Alert` (the default icon and the form-grid row are React only for now)
 
 ---
 
@@ -85,7 +103,7 @@ import { Banner, Button } from '@nxgt/material/components';
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `tone` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | colours and the default icon |
-| `icon` | `ReactNode` | the tone's icon | replaces the default icon; `false` shows none |
+| `icon` | `ReactNode` | the tone's icon | replaces the default icon; `false` shows none. The default icons are Alert's (one shared map) |
 | `action` | `ReactNode` | — | rendered at the end of the banner; under `sm` it drops below the text, in line with it; there a `ghost` or `link` button (a `LinkButton` too, any size) that is the action itself, not wrapped in another element, is pulled back by its own padding, so its label (or leading icon) starts at the text's edge |
 | `onDismiss` | `() => void` | — | shows a close button; the banner does not hide itself |
 

package/docs/components/form-fields.md

@@ -144,6 +144,7 @@ export function SettingsForm({ onSave }: { onSave: (values: Values) => void }) {
 | `titleAs` | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'h2'` | the heading level: `'h3'` when the form already sits under an `h2` |
 | `description` | `ReactNode` | — | a muted line under the title; the group's accessible description |
 | `actions` | `ReactNode` | — | controls beside the title, wrapping under it on a phone |
+| `variant` | `'label' \| 'heading'` | `'label'` | `label` is the small uppercase muted title; `heading` puts the title on the type scale (`title-md` emphasized) and the description in `body-md`, muted |
 | `separated` | `boolean` | `true` | a rule above the section when it follows another `FormSection` |
 
 The section is a `role="group"` named by its heading (`aria-labelledby`) and
@@ -157,11 +158,21 @@ grid uses, by the section's own width (it is a container query container, so
 it works outside a form grid too). The form grid's wide-field rules still
 apply inside it: a switch, a textarea, chips, files and the rich text editor
 take a row of their own. The rule between sections is a top border drawn on
-each section that follows another; the first has none. The heading is small,
+each section that follows another; the first has none. The default heading is small,
 semibold, uppercase and muted, set apart from the fields' labels, and reads
-4.5:1 in both themes.
+4.5:1 in both themes. `variant="heading"` is the section title the design
+rules ask for: `title-md` emphasized in the text colour over a `body-md`
+muted description (both 4.5:1 or more); the root carries `data-variant`. An
+`Alert` or a `Banner` placed directly in the section's fields takes the whole
+row.
 
-**Storybook:** `Form fields/FormSection` · **Vue:** `FormSection`
+```tsx
+<FormSection variant="heading" title="Profile" description="How you appear to other members.">
+  <TextFormField control={control} name="firstName" label="First name" />
+</FormSection>
+```
+
+**Storybook:** `Form fields/FormSection/Heading variant` (`HeadingVariant`) · **Vue:** `FormSection` (no `variant` yet)
 
 ---
 

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

@@ -361,12 +361,11 @@ List / details that collapses to one view on mobile, a side pane that becomes a
 <img src="../previews/navigation-layout-threadlayout.webp" height="96" alt="ThreadLayout">
 
 ```tsx
-import { ListDetailsLayout, ListDetailsTrigger, PaneLayout, ThreadLayout } from '@nxgt/material/components';
+import { ListDetailsLayout, PaneLayout, ThreadLayout } from '@nxgt/material/components';
 
 <ListDetailsLayout activeView={view} onActiveViewChange={setView}>
   <ListDetailsLayout.List>{conversations}</ListDetailsLayout.List>
-  <ListDetailsLayout.Details>
-    <ListDetailsTrigger view="list">Back</ListDetailsTrigger>
+  <ListDetailsLayout.Details back>
     {thread}
   </ListDetailsLayout.Details>
 </ListDetailsLayout>
@@ -397,6 +396,8 @@ app bar.
 | --- | --- | --- | --- |
 | `activeView` / `defaultActiveView` / `onActiveViewChange` | `'list' \| 'details'` | `'list'` | `ListDetailsLayout`: which view a phone shows |
 | `listPosition` | `'left' \| 'right'` | `'left'` | `ListDetailsLayout` |
+| `breakpoint` | `'viewport' \| 'container'` | `'viewport'` | `ListDetailsLayout`: what the 648 px phone layout follows, the window or the layout's own width |
+| `back` | `boolean \| ReactNode` | — | `ListDetailsLayout.Details`: a bar with the way back to the list, on a phone only; `true` is the translated "Back to the list" (`material['list-details'].back`), a node is its label |
 | `open` / `defaultOpen` / `onOpenChange` | `boolean` | `false` | `PaneLayout`: pane shown |
 | `paneSide` | `'left' \| 'right'` | `'left'` | `PaneLayout` |
 | `sheetTitle` | `string` | "Side Panel" (translated, `material['pane-layout']['sheet-title']`) | `PaneLayout.Pane`: screen-reader title of the sheet on phones |
@@ -404,6 +405,10 @@ app bar.
 
 `useListDetails()` and `usePaneLayout()` read the state from inside.
 
+**The way back on a phone.** With `back` on `ListDetailsLayout.Details` the details open under a bar with a labelled back button (`ListDetailsLayout.Back`, also usable in your own header; it renders nothing on a wide screen or when the list shows). On a phone the layout also moves the focus: to the details when a row opens them, then back to that row when the way back is taken, also when `activeView` is controlled by the screen (a URL-driven list and detail). A wide screen shows both panes, with no bar and no focus moves. Leave `back` out and `ListDetailsTrigger view="list"` still works as before.
+
+**Sizing.** The layout fills the box it is in: `h-full` and, in a flex column, `flex-1 min-h-0`, so a header above it and the layout under it share the height with no `h-dvh`. `breakpoint="container"` makes the single-view layout follow the layout's own width (a dialog, a column of a split view) rather than the window; the first render is the wide one, as on a server.
+
 **Storybook:** `Navigation & layout/ListDetailsLayout`, `Navigation & layout/PaneLayout`, `Navigation & layout/ThreadLayout` · **Vue:** `ListDetailsLayout`, `PaneLayout`, `ThreadLayout`
 
 ---

package/docs/guides/backgrounds.md

@@ -55,7 +55,7 @@ import '@nxgt/material/backgrounds.css';
 | `sky` | `'moon'`, `'eclipse'`, `'meteor-shower'`, `'ringed-planet'` or `'northern-lights'`: a second scene drawn over any preset, before the grain; see [Celestial presets and the sky overlay](#celestial-presets-and-the-sky-overlay) | none |
 | `icons` | for `preset="icons"`: a pack name (`school`, `health`, `finance`, `travel`, `nature`, `tech`) or up to 48 icon names and `{ name, family?, type? }` references; see [Icons](#icons) | the `school` pack |
 | `iconStyle` | for `preset="icons"`: one style (`{ family?, type? }` or a sprite name such as `'sharp-light'`) or a list of at most 8, one drawn per icon | duotone thin |
-| `iconMotif` | for `preset="icons"`: `layout` (`scatter`, `grid`, `constellation`, `drift`), `sizeRange`, `rotation`, `duotone` (`opacity` or `tones`), `secondaryOpacity` (0.4 or, with `tones`, 0.85 unless set), `calm` | `{ layout: 'scatter', duotone: 'opacity', calm: true }` (`secondaryOpacity` unset: 0.4, or 0.85 with `tones`) |
+| `iconMotif` | for `preset="icons"`: `layout` (`scatter`, `grid`, `constellation`, `drift`), `sizeRange`, `rotation`, `duotone` (`opacity` or `tones`), `secondaryOpacity` (0.4 or, with `tones`, 0.85 unless set), `calm`, `quiet` (`start`, `end`, `center`: a band the icons fade out of) | `{ layout: 'scatter', duotone: 'opacity', calm: true }` (`secondaryOpacity` unset: 0.4, or 0.85 with `tones`) |
 | `fill` | `viewport` (the viewport's size) or `container` (its parent's size: the parent needs a definite height) | `viewport` |
 
 
@@ -357,7 +357,40 @@ import { Background } from '@nxgt/material/backgrounds';
 - `animated` drifts each icon a few pixels on `translate` (never under `prefers-reduced-motion`, paused while hidden).
 - In an `ActivityLayout` the keep-inside pass hides an icon that would cross the layer's edge or the header band.
 - A theme can name the preset with `background: { preset: 'icons', icons, iconStyle, iconMotif, sky }`; the props win. The theme picker draws the first four icons in the theme's tile ([themes](themes.md#icon-motifs-in-a-theme)).
-- CSS: `backgrounds/icons.css` (or `backgrounds.css`). React only: `@nxgt/material-vue` does not draw it.
+- CSS: `backgrounds/icons.css` (or `backgrounds.css`). Both pull in `backgrounds/icons-quiet.css`, the mask behind `iconMotif.quiet`, which can also be imported alone. React only: `@nxgt/material-vue` does not draw it.
+
+### Keeping text clear of the icons: `quiet`
+
+A greeting band, a hero or a card header often puts text on the motif. `calm`
+only thins the icons in the middle of the frame; `iconMotif.quiet` clears a
+**band** of it: the icons fade out over `start`, `end` or the `center`, so the
+text sits on the wash alone.
+
+```tsx
+<Background preset="icons" icons="school" iconMotif={{ quiet: 'start' }} className="h-48 rounded-2xl">
+	<div className="absolute inset-y-0 start-0 flex w-[42%] flex-col justify-center ps-6">
+		<h2>Good morning, Ada</h2>
+		<p>Three classes today, the first at 9:00.</p>
+	</div>
+</Background>
+```
+
+- `'start'` and `'end'` follow the reading direction (the left, then the right,
+  in a left-to-right page; swapped in a right-to-left one). `'center'` keeps the
+  middle clear, for a centred title.
+- It is a CSS mask on the scene, so it holds at every width and with every
+  `layout`; the icons are the same ones (the seed and the layout are unchanged),
+  only hidden. No inline style: it is a class on the scene (`ic-q-start`,
+  `ic-q-end`, `ic-q-center`) and a rule of the preset's stylesheet.
+- The band is `--background-quiet` wide, **42%** by default, then the icons fade
+  back in over 30% more. Set it with a class: `className="[--background-quiet:60%]"`.
+  Keep your text inside the band's width, and widen the band on a phone, where
+  the text takes more of the line.
+- Contrast: under the mask the text sits on the surface and the wash (at most
+  15% of a tone), never on an icon. The `Backgrounds/Icons/Quiet band` story
+  measures the title and the muted line at 4.5:1 against the surface and each
+  tone of the wash, light and dark.
+- A theme sets it too: `background: { preset: 'icons', iconMotif: { quiet: 'end' } }`.
 
 ## Dark mode
 

package/docs/guides/drawing.md

@@ -220,10 +220,25 @@ A `Drawing` takes `title` **or** `decorative`; the type refuses neither.
 ```tsx
 <Drawing scene={chart} title="Sales by month, rising" />      {/* role="img" aria-label */}
 <Drawing scene={flourish} decorative />                        {/* aria-hidden */}
+<Drawing
+  scene={chart}
+  title="Sales by month, rising"
+  description="January 12, February 18, March 25, April 31."
+/>                                                              {/* role="img", aria-label, <desc>, aria-describedby */}
 ```
 
+The `<desc>`'s id is the drawing's own id prefix plus `-desc`, so two drawings on
+a page never share one. `toSVG` takes the same `description` (with a `title`; it
+throws on a `decorative` drawing): `toSVG(scene, { title, description })` writes the
+`<desc id="…-desc">` and the root's `aria-describedby`, escaped, in the file or
+e-mail too.
+
 - The name is an `aria-label`, never a `<title>` element: React 19 would hoist a
   `<title>` into the document's head.
+- A long description, such as a chart's data, is the `description` prop, next to
+  the `title` (it needs one: a decorative drawing is hidden). It is written as a
+  `<desc>` inside the `<svg>`, which the root names in `aria-describedby`, so a
+  screen reader reads the name, the role, then the description.
 - A drawing with an interactive node is `role="group"`, because an image cannot
   hold focusable children; a decorative one cannot hold an interactive node and
   throws `A decorative drawing has an interactive node: give the Drawing a title instead`.

package/docs/guides/printing.md

@@ -121,6 +121,8 @@ import { PrintDocument, PrintHeader } from '@nxgt/material/print';
 | `producer` | `creator` | The software that wrote the PDF. |
 | `language` | the `I18nProvider` around the document, then `'en'` | The built-in strings ("Page 2 of 5") and the PDF's language. |
 | `locale`, `timeZone` | `language`, the runtime's | How the data blocks format amounts and dates. |
+| `theme` | — | `{ fonts: { sans, serif, mono }, colors }`: the page's font family, which every block inherits. Pass a family you embedded with [`registerPdfFont`](#embedding-a-font-and-archiving) to ship the font in the file. |
+| `conformance` | — | A PDF/A level (`'PDF/A-2b'`, …) the file claims. Needs every font embedded; see [Embedding a font](#embedding-a-font-and-archiving). |
 
 Nothing but `children` is required: `<PrintDocument>{…}</PrintDocument>` is an
 A4 page with the margins the blocks were designed for.
@@ -366,7 +368,8 @@ TypeScript checks every `key` against `T`.
 | `label` | `string` | — | Required. The header text, and the label in a [`PrintKeyValue`](#printkeyvalue-one-record-as-label-and-value-pairs) |
 | `width` | `number \| '<n>%'` | — | A fixed width in points (`40`) or a share of the table (`'25%'`) |
 | `flex` | `number` | `1` | Share of the width the fixed columns leave. Ignored when `width` is set |
-| `align` | `'left' \| 'center' \| 'right'` | `'right'` for `amount`, `number` and `percent`, else `'left'` | Header and cells |
+| `align` | `'left' \| 'center' \| 'right'` | `'right'` for `amount`, `number`, `percent` and `numeric: true` columns, else `'left'` | Header and cells |
+| `numeric` | `boolean` | `true` for `amount`, `number` and `percent`, else `false` | A column of figures: its cells print with [tabular digits](#tabular-figures) and flush right. Set it on a column whose `format` is a function; `numeric: false` drops the tabular digits of an `amount` column but keeps it flush right (give `align: 'left'` to move it) |
 | `format` | `'amount' \| 'date' \| 'number' \| 'percent' \| (value, row) => string` | none | How the value prints (below) |
 | `currency` | `string \| (row: T) => string \| null \| undefined` | the table's `currency` | ISO 4217 code for `format: 'amount'`, for the column or per row |
 | `total` | `'sum' \| (rows: T[]) => number \| string \| null` | none | A figure in the totals row: the sum of the column, or your own |
@@ -553,7 +556,7 @@ function resolvePrintTable<T>(
   rows: T[],
   options?: { currency?: string; totalLabel?: string },
 ): {
-  columns: { id: string; label: string; align: 'left' | 'center' | 'right'; width?: number | `${number}%`; flex?: number }[];
+  columns: { id: string; label: string; align: 'left' | 'center' | 'right'; width?: number | `${number}%`; flex?: number; numeric?: boolean }[];
   rows: PrintValue[][];
   footer: PrintValue[][]; // one totals row, or none
   empty: boolean;
@@ -976,6 +979,8 @@ type PdfDocument = {
   version: 1;
   meta?: { title?: string; author?: string; subject?: string; keywords?: string; creator?: string; producer?: string };
   language?: string; // the built-in strings ('en', 'fr') and the PDF's language; 'en' by default
+  outline?: boolean; // the bookmarks panel: one entry per heading; off by default
+  conformance?: 'PDF/A-1' | 'PDF/A-1b' | 'PDF/A-2' | 'PDF/A-2b' | 'PDF/A-3' | 'PDF/A-3b'; // needs embedded fonts
   locale?: string;   // how amounts, dates and numbers print; `language` by default
   timeZone?: string;
   theme?: { colors?: Partial<Record<PdfThemeColor, string>>; fonts?: Partial<Record<'sans' | 'serif' | 'mono', string>> };
@@ -1332,6 +1337,112 @@ Rendering a model throws, before any page is drawn, on:
 | `[pdf] Unknown node type "chart".` | A `type` this version does not know: a typo in hand-written JSON, or a document from a newer version |
 | `[pdf] Unsupported document version 2: this version renders version 1.` | `version` is not `1` |
 
+## Accessible, archival and consistent PDFs
+
+What a PDF built here is, and is not, for assistive technology and archives.
+
+### What is written, and what is not tagged
+
+`@react-pdf/renderer` (4.9) draws text and boxes; it never writes the
+structure tree a *tagged* PDF needs (the `Marked` flag, `StructTreeRoot`,
+marked content for headings, tables and figures). pdfkit, underneath, can tag,
+but react-pdf does not call it, so **no document made here is a tagged PDF,
+and none claims to be PDF/UA**. A screen reader reads the text in the
+document's order (the order you wrote the nodes), with no heading or table
+semantics. What *is* written:
+
+| What | How | Where a reader sees it |
+| --- | --- | --- |
+| Language | `language` on the document (or `<PrintDocument language>`) | The reader's speech language, and the file's `/Lang` |
+| Title, author, subject, keywords | `meta`, or the `PrintDocument` props | The window title (shown instead of the file name), the document properties |
+| Outline (bookmarks) | `outline: true` on a [model document](#documents-as-data): each `heading` is an entry, a level 2 under the level 1 before it, a level 3 under the level 2 | The bookmarks panel, with a jump to the heading's page |
+| Reading order | The order of the nodes, header then body | The text selection, copy and screen-reader order |
+| PDF/A marker | `conformance: 'PDF/A-2b'` with an embedded font | The archive validators' first check (this is not a validation: run a PDF/A validator on what you keep) |
+
+Text in an image or a drawing is not text: put what it says in the page
+next to it. The model's `image` node has no `alt`: there is nowhere in an
+untagged PDF to write it. The outline lists the headings of the page bodies,
+not of a repeated `header` or `footer`.
+
+```ts
+import { heading, page, pdfDocument, text } from '@nxgt/material/print';
+
+pdfDocument({
+  language: 'fr',
+  meta: { title: 'Facture INV-42' }, // shown as the window title
+  outline: true,                     // the bookmarks panel
+  pages: [page({ body: [heading('Facture'), heading('Lignes', 2), text('…')] })],
+});
+```
+
+### Embedding a font and archiving
+
+pdfkit's standard fonts (Helvetica, Times-Roman, Courier) are **not embedded**
+in the file: a viewer draws its own Helvetica, so the glyph widths, the euro
+sign and the narrow no-break space of French amounts can differ, and PDF/A
+refuses the file. To ship the font, register one family once and name it in
+the theme (`registerPdfFont` is a thin call to react-pdf's `Font.register`):
+
+```ts
+import { pdfDocument, registerPdfFont } from '@nxgt/material/print';
+import regular from '@fontsource/inter/files/inter-latin-400-normal.woff?url';
+import bold from '@fontsource/inter/files/inter-latin-700-normal.woff?url';
+
+const sans = registerPdfFont({ family: 'Inter', regular, bold }); // once per process
+pdfDocument({
+  theme: { fonts: { sans } },   // or <PrintDocument theme={{ fonts: { sans } }}>
+  conformance: 'PDF/A-2b',      // optional: the archive marker
+  pages,
+});
+```
+
+The same two options on the component:
+
+```tsx
+<PrintDocument theme={{ fonts: { sans } }} conformance="PDF/A-2b" title="Invoice 2026-001">
+  {/* pages */}
+</PrintDocument>
+```
+
+- **Give static files** (TTF, OTF or WOFF), one per style: `regular`, `bold`,
+  `italic`, `boldItalic`. A variable font (`inter-latin-wght-normal.woff2`)
+  has one weight in a PDF, so its bold looks regular, and its bold subset can
+  fail.
+- The file embeds the glyphs it uses (a subset), so a family adds tens of
+  kilobytes to a document, not its whole size. The library does **not** bundle
+  a font: the size of `@nxgt/material` and `@nxgt/material-core` stays as it
+  is, and the choice (and its licence) is yours. `@fontsource/inter` (OFL) is a
+  static, free option.
+- A source is a URL or a path react-pdf can fetch where it renders: a file
+  path on a server, a URL (or a bundler's `?url` import) in the browser.
+- On a server bundle, the registered font is read at render time; nothing
+  needs `pdfkitStandardFonts()` for it.
+- Register before the first render; registering the same family again adds
+  its faces.
+
+### Tabular figures
+
+Figures that should line up (an invoice's amounts, a report card's marks) need
+digits of one width. The standard fonts' digits already are; a proportional
+font such as Inter has them as the OpenType `tnum` feature. A `numeric`
+column, an `amount`, `number` or `percent` column of a `dataTable` or a
+`PrintDataTable`, the values of `totals` and a `metric` turn it on, and a
+`style: { tabularNums: true }` does it on any `text`:
+
+```ts
+table({
+  columns: [{ label: 'Item', flex: 3 }, { label: 'Qty', numeric: true, width: 50 }],
+  rows: [['Design', 12], ['Review', 140]],
+});
+text('1 234,50', { style: { tabularNums: true } });
+```
+
+A font without the feature (the standard ones, Liberation Sans) draws the same
+as before. On screen, a `DataTable` column takes `meta: { numeric: true }`
+(flush to the end, `tabular-nums`; see
+[DataTable](../components/data-table-filter-and-lists.md)), and a `DataGrid`'s
+cells are `tabular-nums` already.
+
 ## Why it is a separate entry
 
 `@react-pdf/renderer` depends on `pdfkit`, and pdfkit loads its fourteen

package/docs/roadmap.md

@@ -168,8 +168,9 @@ version they shipped in, and planned entries may name the major they target.
   accessibility (PDF/UA), archival (PDF/A-3) and electronic invoicing (Factur-X,
   EN 16931). It also brings the items below.
 - **Your brand on the page** — a print theme whose defaults follow the screen
-  theme, and your own font files registered in one call (the library bundles
-  no fonts).
+  theme, and your own font files registered in one call (the font half ships:
+  `registerPdfFont` and `theme.fonts` on the current renderer; the library
+  bundles no fonts).
 - **QR codes, barcodes and charts in a PDF** — pass the value or the chart
   options and get vector output, no data URL to prepare.
 - **Rich text and Markdown in a PDF** — the rich-text editor's content and
@@ -178,7 +179,8 @@ version they shipped in, and planned entries may name the major they target.
   renders it itself, refreshing a moment after its data stops changing.
 - **Test helpers for generated PDFs** — read a generated PDF's text, page count
   and metadata in a unit test, without a browser.
-- **Archive-ready PDFs** — PDF/A-3 output through one option, for invoices and
+- **Archive-ready PDFs** — PDF/A-3 output through one option (the PDF/A-1/2/3
+  marker ships already through `conformance` on the current renderer), for invoices and
   records that must be kept.
 - **Electronic invoices (Factur-X)** — an invoice PDF that carries its
   machine-readable data (EN 16931), built on archive-ready PDFs and the

package/docs/troubleshooting.md

@@ -3384,6 +3384,51 @@ renders.
 **Fix:** build the document with `pdfDocument()` or `definePdfDocument()`,
 which stamp `version: 1`, rather than by hand.
 
+### A PDF accessibility checker says the PDF is not tagged
+
+**When:** a checker (Acrobat's accessibility check, PAC, veraPDF with the PDF/UA profile) reports "document is not tagged" or "no structure tree" on a PDF made with `@nxgt/material/print`.
+**Why:** `@react-pdf/renderer` 4.9 writes no structure tree, so no PDF made here is a tagged PDF, and none claims PDF/UA. This is the renderer's limit, not a missing option. What the library does write is the language, the title (shown as the window title), the outline and the reading order of the nodes.
+**Fix:** set what can be set, and say the rest in the page: `language` and `meta.title` on the document, `outline: true` for a long one, text beside a drawing or an image. If a tagged PDF is a requirement, offer an accessible HTML version of the same data. See [what is written, and what is not tagged](guides/printing.md#what-is-written-and-what-is-not-tagged).
+
+```ts
+pdfDocument({ language: 'fr', meta: { title: 'Facture INV-42' }, outline: true, pages });
+```
+
+### The PDF's font is substituted, or a PDF/A validator rejects the file
+
+**When:** a viewer shows a different Helvetica than the one you designed with (other widths, a missing euro sign, or the narrow no-break space of French thousands drawn as a wrong glyph), or a PDF/A validator reports "font not embedded".
+**Why:** the default fonts (Helvetica, Times-Roman, Courier) are pdfkit's standard fonts: the file names them and the viewer draws its own.
+**Fix:** embed a family with `registerPdfFont` and name it in the theme; see [Embedding a font and archiving](guides/printing.md#embedding-a-font-and-archiving).
+
+```ts
+const sans = registerPdfFont({ family: 'Inter', regular: interRegular, bold: interBold });
+pdfDocument({ theme: { fonts: { sans } }, conformance: 'PDF/A-2b', pages });
+```
+
+### An embedded font has no bold
+
+**When:** `registerPdfFont` was given a variable font (`inter-latin-wght-normal.woff2`): bold text looks regular, and in some builds rendering fails while writing the font.
+**Why:** react-pdf draws a variable font at its default instance, so bold has nothing to switch to (a bold request on a variable woff2 also failed in our tests).
+**Fix:** give one static file per style (`@fontsource/inter` ships `inter-latin-400-normal.woff` and `inter-latin-700-normal.woff`).
+
+### A `Drawing` `description` is never read
+
+**When:** a `Drawing` with `description` writes no `<desc>`, or a screen reader says only the name.
+**Why:** a description is read after the name, so it needs a `title`; a `decorative` drawing is hidden from assistive technology, and the type refuses `description` on it. `toSVG` takes the same `description` option and throws without a `title` or with `decorative`, so an exported file or an e-mail carries it too.
+**Fix:** give the drawing a `title`, and keep the title short and the description long (`toSVG(scene, { title, description })` does the same for a file):
+
+```tsx
+<Drawing scene={chart} title="Sales by month" description="January 12, February 18, March 25: rising." />
+```
+
+### `iconMotif.quiet` changes nothing
+
+A theme that defines `iconMotif.quiet` with a value other than `start`, `end` or `center` is rejected by `defineTheme`; see the core troubleshooting.
+
+**When:** text over `<Background preset="icons">` still sits on icons although `iconMotif={{ quiet: 'start' }}` is set.
+**Why:** `quiet` is a CSS mask the `icons` preset's stylesheet draws: another preset ignores it, the band is `--background-quiet` wide (42% by default) and fades back in over 30% more, and on a phone the text can be wider than the band.
+**Fix:** use `preset="icons"`, import `@nxgt/material/backgrounds.css`, and widen the band: `className="[--background-quiet:60%]"`. See [Keeping text clear of the icons](guides/backgrounds.md#keeping-text-clear-of-the-icons-quiet).
+
 ### `'invoice' is of type 'unknown'` in a `definePdfDocument` template
 
 **When:** compiling a template whose data parameter has no type,