@nxgt/material 3.88.1 → 3.91.0

package/dist/{use-heading-spy-kyOSe9rb.js → use-heading-spy-BcNK1qvq.js}

@@ -1,8 +1,8 @@
 import { t as e } from "./utils-BLfntITJ.js";
-import { a as t, c as n, d as r, i, n as a, r as o, t as s, u as c } from "./alert-dialog-CEGs7LMN.js";
-import { a as l } from "./button-DuTNpo28.js";
-import { i as u } from "./translate-material-BrYBBZ66.js";
-import { t as d } from "./use-material-translation-BdrItuwY.js";
+import { a as t, c as n, d as r, i, n as a, r as o, t as s, u as c } from "./alert-dialog-BFk4ye-3.js";
+import { a as l } from "./button-C5OEq9bi.js";
+import { i as u } from "./translate-material-BmpcP1p1.js";
+import { t as d } from "./use-material-translation-DoymV6IP.js";
 import { _ as f, g as p, h as m, t as h, v as g, y as _ } from "./date.utils-JTEIo3mM.js";
 import { useCallback as v, useEffect as y, useMemo as b, useRef as x, useState as S } from "react";
 import { Fragment as C, jsx as w, jsxs as T } from "react/jsx-runtime";

package/dist/{use-material-translation-BdrItuwY.js → use-material-translation-DoymV6IP.js}

@@ -1,4 +1,4 @@
-import { i as e, t } from "./translate-material-BrYBBZ66.js";
+import { i as e, t } from "./translate-material-BmpcP1p1.js";
 import { useCallback as n } from "react";
 //#region lib/i18n/use-material-translation.ts
 function r() {

package/dist/{use-return-focus-Cqzvj9R0.js → use-return-focus-CLEnhfka.js}

@@ -1,6 +1,6 @@
 import { o as e, r as t } from "./dist-DVRQkaTK.js";
 import { i as n, n as r, r as i, t as a } from "./dist-DWZXlCZR.js";
-import { C as o, S as s, x as c } from "./spinner-DcW21pN1.js";
+import { C as o, S as s, x as c } from "./spinner-JnLLiLIO.js";
 import { a as l, i as u, r as d } from "./dist-DHdUUM1w.js";
 import { c as f, i as p, l as m, o as h, r as g, s as ee } from "./in-dialog-D61Yeaol.js";
 import { r as te } from "./escape-owner-DpaP0lm1.js";

package/docs/components/README.md

@@ -46,11 +46,12 @@ Labelled inputs with a value, each with its form-library wrapper, and the compos
 
 ## [Date & time](date-and-time.md)
 
-Calendar, date, range, half-day range, time, duration, a month navigator, the now line. 9 entries.
+Calendar, date, range, half-day range, time, duration, age, a month navigator, the now line. 10 entries.
 
 [<img src="../previews/date-time-datefield.webp" height="72" alt="DateField">](date-and-time.md#datefield)
 [<img src="../previews/date-time-daterangefield.webp" height="72" alt="DateRangeField">](date-and-time.md#daterangefield)
 [<img src="../previews/date-time-timefield.webp" height="72" alt="TimeField">](date-and-time.md#timefield)
+[<img src="../previews/date-time-agefield.webp" height="72" alt="AgeField">](date-and-time.md#agefield)
 [<img src="../previews/date-time-durationfield.webp" height="72" alt="DurationField">](date-and-time.md#durationfield)
 [<img src="../previews/date-time-halfdayrangefield.webp" height="72" alt="HalfDayRangeField">](date-and-time.md#halfdayrangefield)
 [<img src="../previews/date-time-minimonth.webp" height="72" alt="MiniMonth">](date-and-time.md#minimonth)

package/docs/components/buttons-and-actions.md

@@ -939,7 +939,16 @@ In a page header with other actions, `collapse="phone"` keeps only the arrow bel
 </BackLink>
 ```
 
-**Storybook:** `Buttons & actions/BackLink` (`Default`, `LinkStyle`, `Rtl`, `CollapsedOnPhone`) · **Vue:** none yet
+At the top of a page, `flush` drops the start padding so the arrow lines up with the title and content under it, in left-to-right and right-to-left pages. It suits the `link` and `ghost` looks (no box); the hit area keeps the button's height. Without it the arrow is inset by the button's padding. Default `false`.
+
+```tsx
+<BackLink to="/items" variant="link" flush>
+	All items
+</BackLink>
+<h1>Item</h1>
+```
+
+**Storybook:** `Buttons & actions/BackLink` (`Default`, `LinkStyle`, `Flush`, `FlushRtl`, `Rtl`, `CollapsedOnPhone`) · **Vue:** none yet
 
 ---
 

package/docs/components/data-display.md

@@ -8,16 +8,18 @@ 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 |
+| — | [PersonCell](#personcell) | A decorative initials avatar before a truncating name, for the first column of a table or a card title |
 | <img src="../previews/data-display-seatring.webp" width="96" alt=""> | [SeatRing](#seatring) | Participants as seats around a circle or in a grid, optionally pickable |
 | <img src="../previews/data-display-secretcard.webp" width="96" alt=""> | [SecretCard](#secretcard) | A card whose secret is not rendered until it is revealed |
 | <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) | Status pill, 20 px, in seven tones, soft or outlined, with an optional decorative `icon` before the words |
+| <img src="../previews/data-display-badge.webp" width="96" alt=""> | [Badge](#badge) | Status pill, `sm` (20 px) or `md` (24 px), in seven tones, soft or outlined, with an optional decorative `icon` before the words |
 | <img src="../previews/data-display-countbadge.webp" width="96" alt=""> | [CountBadge](#countbadge) | Count in the corner of its children |
 | <img src="../previews/data-display-highlightedtext.webp" width="96" alt=""> | [HighlightedText](#highlightedtext) | A string with the words of a search query in a themed `<mark>` |
 | <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 |
 | <img src="../previews/data-display-chip.webp" width="96" alt=""> | [Chip](#chip) | Three looks and a dashed add pill, with slots, a selected state and a dismiss button |
 | <img src="../previews/data-display-statcard.webp" width="96" alt=""> | [StatCard](#statcard) | KPI tile with value, hint, icon and toned delta; `href` makes it one link |
+| | [ToneValue](#tonevalue) | A value in its tone's text colour after a shape (diamond, triangle, circle, square), so colour is never the only signal; the cells of a `meta.tone` column |
 | | [TotalsList](#totalslist) | Labelled figures in a `dl`, amounts right-aligned, a ruled grand-total row; the screen twin of `PrintTotals` |
 | <img src="../previews/data-display-metric-cards.webp" width="96" alt=""> | [Metric cards](#metric-cards) | Sixteen dashboard tiles |
 | <img src="../previews/data-display-card-presets.webp" width="96" alt=""> | [Card presets](#card-presets) | Twenty-seven ready-made cards |
@@ -368,7 +370,7 @@ and no lazy loading: give `src` the size you need.
 
 ![Badge](../previews/data-display-badge.webp)
 
-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.
+Status badge: a pill in two sizes (`sm`, 20 px with the `label-sm` text, by default; `md`, 24 px with `label-md`), 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';
@@ -377,20 +379,64 @@ import { Badge } from '@nxgt/material/components';
 <Badge variant="outlined" tone="error">Late</Badge>
 <Badge variant="success">New</Badge>
 <Badge variant="soft" tone="warning" icon="box-archive">Archived</Badge>
+<Badge size="md" variant="soft" tone="success">Paid</Badge>
 ```
 
-With an `icon`, a status reads as icon plus words, so colour is never the only signal. The icon is decorative (`aria-hidden`: the words name the status), 12 px, and takes the tone's text colour in `soft` and `outlined`; nothing changes without it.
+With an `icon`, a status reads as icon plus words, so colour is never the only signal. The icon is decorative (`aria-hidden`: the words name the status), 12 px (16 px at `md`), and takes the tone's text colour in `soft` and `outlined`; nothing changes without it.
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `icon` | `IconName \| ReactNode` | — | a decorative icon before the label: a string is a Font Awesome name (drawn solid), a node is rendered as given. Ignored with `asChild` |
 | `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 |
+| `size` | `'sm' \| 'md'` | `'sm'` | `sm` is 20 px with `label-sm` text and a 12 px icon; `md` is 24 px with `label-md` text and a 16 px icon, to read next to body text in a list or table row |
 | `asChild` | `boolean` | `false` | renders its child (a link) with the badge styles |
 
 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), `Data display/Badge/Icon` · **Vue:** `Badge` (without `soft` and `tone` yet)
+**Storybook:** `Data display/Badge` (Soft, SoftContrast, Sizes), `Data display/Badge/Icon` · **Vue:** `Badge` (without `soft` and `tone` yet, and without `size`: React-only until Vue parity, #2590)
+
+---
+
+## PersonCell
+
+An avatar before a name, for the first column of a table of people or the title of a card. The avatar is decorative (`aria-hidden`) and neutral by default; the name is the text a screen reader and a row link read. The name (and the optional description) truncate with an ellipsis (`min-w-0`) while their full text stays in the DOM, so it holds on a phone.
+
+In the first column of a table ([DataTable guide](./data-table-filter-and-lists.md)):
+
+```tsx
+import { createColumnHelper } from '@tanstack/react-table';
+import { PersonCell, type DataTableFeatures } from '@nxgt/material/components';
+
+const helper = createColumnHelper<DataTableFeatures, Person>();
+
+const columns = [
+  helper.accessor('name', {
+    header: 'Name',
+    cell: ({ getValue }) => <PersonCell name={getValue()} />,
+  }),
+];
+```
+
+As the title of a card, in its 32 px size:
+
+```tsx
+import { PersonCell } from '@nxgt/material/components';
+
+<PersonCell size="md" name="Ada Lovelace" description="Analyst" />
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `name` | `string` | — | the person's name, truncated when it does not fit |
+| `src` | `string` | — | a picture; the initials show until it loads or when it fails |
+| `initials` | `string` | derived from `name` | the letters shown without a picture (`'Ada Lovelace'` gives `AL`) |
+| `tone` | `Tone` | neutral | tone of the initials |
+| `description` | `string` | — | a muted, truncating line under the name |
+| `size` | `'sm' \| 'md'` | `'sm'` | `sm`: 24 px avatar, for a table row; `md`: 32 px, for a card or a list |
+| `className` | `string` | — | on the root, which is `flex min-w-0` |
+
+**Storybook:** `Data display/PersonCell` · Not in `@nxgt/material-vue` yet.
 
 ---
 
@@ -604,6 +650,26 @@ pass `disabled` with a `Spinner` in `leading`, or use a `Button`.
 
 ---
 
+## ToneValue
+
+A value in the text colour of its tone, after a small `aria-hidden` shape fixed per tone: a diamond for `error`, a triangle for `warning`, a circle for `success`, a square for any other tone, none for `neutral`. The tone survives forced colours, colour blindness and a black and white print. The cells of a [`meta.tone` column](data-table-filter-and-lists.md#cells-toned-by-their-value) of `DataTable`, `ServerTable` and `DataGrid` wear it; import it for a `renderCard` or any figure of your own.
+
+```tsx
+import { ToneValue } from '@nxgt/material/components';
+
+<ToneValue tone="error" label="Low">6.5</ToneValue>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `tone` | `Tone` | — | a named tone or one the app declared in `AppTones`; `undefined` renders the value in a plain span, with your `className` and props, and no mark |
+| `label` | `string` | — | words after the value for a screen reader, visually hidden; the mark is never read |
+| `children` | `ReactNode` | — | the value |
+
+**Storybook:** `Data display/ToneValue` · Not in `@nxgt/material-vue` yet (#2569).
+
+---
+
 ## TotalsList
 
 On-screen counterpart of `PrintTotals`: a `dl` of labelled figures, labels at the start, amounts right-aligned in tabular figures, one column at any width (a side rail, a phone). Rows have the shape of `PrintTotalRow` (`label`, `value`, `last`), so one array feeds the screen and its print.
@@ -990,9 +1056,19 @@ import { Badge, EntityHeader } from '@nxgt/material/components';
 | `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 `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) |
+| `surface` | `'card' \| 'none'` | `'card'` | `'none'` draws the header flat (no background, padding or shadow) for a header that sits directly on a page band or inside a surface of its own, so surfaces do not nest; the layout is unchanged |
 
 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".
 
+**Flat, on a page band.** `surface="none"` drops the header's own card; `className` still merges.
+
+```tsx
+<main className="bg-background">
+  <EntityHeader surface="none" title="John Doe" metadata={[{ label: 'Email', value: 'john.doe@example.com' }]} />
+  <Card>…</Card>
+</main>
+```
+
 **A control at the start.** `leading` takes a control, never `icon`: the icon badge is `aria-hidden`, which squashes a `Switcher` and makes axe report `aria-hidden-focus` (see [Troubleshooting](../troubleshooting.md#a-control-in-an-entityheaders-icon-is-hidden-from-assistive-tech-squashed-and-reports-aria-hidden-focus)).
 
 ```tsx

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

@@ -93,7 +93,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.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 |
+| `columns` | `ColumnDef<DataTableFeatures, T>[]` | — | `meta.className` styles a column's cells; `meta.cellClassName(value, row)` adds classes to a body cell from the value it shows (below); `meta.tone(value, row)` tones the cell ([below](#cells-toned-by-their-value)); `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)) |
@@ -135,6 +135,59 @@ table enables, for typing your own column defs.
 | `announceLoading` | `boolean` | `true` | `false` keeps the visually hidden "Loading data…" region silent, for a page whose own region tells the answer |
 | `announceEmpty` | `boolean` | `true` | `false` keeps the same region silent on an empty page (once the page empties after a change, it says "No results…" when filtered, "No data available" for an empty `manual` page; never on the first render), for a page whose own region tells it |
 
+### Cell classes from the value
+
+`meta.cellClassName(value, row)` returns classes for a body cell (or `undefined`), merged after `meta.className`. `DataTable` and `ServerTable` pass `cell.getValue()` and the row's original; `DataGrid` passes the value the cell shows now, so the class follows an edit, a save and an undo. The text is untouched and the header is not concerned.
+
+```tsx
+helper.accessor('balance', {
+	header: 'Balance',
+	meta: {
+		numeric: true,
+		cellClassName: (value) =>
+			typeof value === 'number' && value < 0 ? 'text-error-text' : undefined,
+	},
+});
+```
+
+### Cells toned by their value
+
+`meta.tone(value, row)` returns a tone (`'error'`, `'warning'`, `'success'`, any tone of the library or of your `AppTones`) or `undefined`. A toned cell gets `data-tone`, and its content is wrapped in [`ToneValue`](data-display.md#tonevalue): the value in the tone's text colour after a small shape (diamond for `error`, triangle for `warning`, circle for `success`, square for another tone, none for `neutral`), so the tone holds in dark, on a selected row and in forced colours, where the shapes tell the tones apart without colour. No tone, no mark: the value is plain. `DataTable` and `ServerTable` pass `cell.getValue()` and the row's original, and the default card of the `cards` and `tiles` layouts shows the first cell the same way; a `renderCard` imports `ToneValue`.
+
+`DataGrid` passes the value the cell shows now, so the tone follows an edit, a pending save, a refused save put back and an undo (and the mark appears at once on the focused cell). While a cell is edited its editor's ring stays the focus indicator, and a text kept as an error is not toned. On a phone the list summary and the row panel's read-only values wear `ToneValue` too.
+
+`toneBands` from `@nxgt/material/components` (also `@nxgt/material-core/cell-tone`) builds the function from bands on a number: `{ below: 8 }` is under 8, `{ from: 14 }` is 14 and over, the first band that holds wins, a gap between bands has no tone, and so has a value that is not a number. `max` divides the value first, so fractional bands serve any scale. The mark is `aria-hidden`; to have a screen reader say the band, give the bands a `label` and set `meta.toneLabel` (off by default).
+
+```tsx
+import { toneBands } from '@nxgt/material/components';
+
+const level = toneBands([
+	{ below: 8, tone: 'error', label: 'Low' },
+	{ below: 10, tone: 'warning', label: 'Borderline' },
+	{ from: 14, tone: 'success', label: 'High' },
+]);
+
+helper.accessor('score', {
+	header: 'Score',
+	meta: {
+		numeric: true,
+		tone: level,
+		toneLabel: level.label, // optional: "6.5 Low" for a screen reader
+	},
+});
+```
+
+A first column of people takes [`PersonCell`](./data-display.md#personcell) as its `cell`: a decorative avatar, then the name, which truncates on a phone.
+
+```tsx
+import { PersonCell } from '@nxgt/material/components';
+
+helper.accessor('name', {
+	header: 'Name',
+	cell: ({ getValue }) => <PersonCell name={getValue()} />,
+});
+```
+
 ### Loading and empty states
 
 ```tsx
@@ -1596,7 +1649,7 @@ props that matter:
 
 | Prop | Type | Default | Notes |
 | --- | --- | --- | --- |
-| `data`, `columns`, `getRowId` | `TData[]`, `ColumnDef[]`, `(row) => string` | — | Required. `meta.editor` makes a column editable: `'text'`, `'number'` (`number`, `codes`), `'select'` (`options`), `'date'` (`date`), `'checkbox'`, or [your own component](../guides/data-grid.md#a-custom-editor). `meta.parse`, `format`, `validate`, `schema`, `value` (computed), `aggregate`, `readOnly`, `locked`, `headerMenu`, `headerWrap` (two-line header titles; a cut title gets a tooltip), `frozen` and `className` (give a `w-*` width) are in [the guide](../guides/data-grid.md#columns-and-meta) |
+| `data`, `columns`, `getRowId` | `TData[]`, `ColumnDef[]`, `(row) => string` | — | Required. `meta.editor` makes a column editable: `'text'`, `'number'` (`number`, `codes`), `'select'` (`options`), `'date'` (`date`), `'checkbox'`, or [your own component](../guides/data-grid.md#a-custom-editor). `meta.parse`, `format`, `validate`, `schema`, `value` (computed), `aggregate`, `readOnly`, `locked`, `headerMenu`, `headerWrap` (two-line header titles; a cut title gets a tooltip), `frozen`, `className` (give a `w-*` width) and `cellClassName(value, row)` (classes from the value the cell shows now, so they follow an edit, a save and an undo), `tone(value, row)` and `toneLabel` (the same, for the cell's tone) are in [the guide](../guides/data-grid.md#columns-and-meta) |
 | `save` | `'batch' \| 'cell' \| 'row'` | `'batch'` | When `onSave` is called: on Save, 300 ms after each change, or when a row is left. `'row'` needs `getRowVersion`. In cell and row modes a call carries at most `maxEntriesPerSave` (200) entries |
 | `onSave` | `(entries, { signal }) => Promise<answer>` | — | `{ ok: true, versions }`, or `{ ok: false, refused }` with an `error` (and `revert: true` to put the cell back) or a `conflict` per entry. Pass `signal` to your `fetch` |
 | `getRowVersion`, `getCellVersion` | `(row) => version`, `(row, columnId) => version` | — | The version each value was read at; a mismatch on reload is a conflict ([versions](../guides/data-grid.md#versions-and-conflicts)) |
@@ -3093,7 +3146,7 @@ import { Avatar, ListPane, ListPaneItem } from '@nxgt/material/components';
 | `height` | `number \| string` | `20rem` | the body's height, capped at 65% of the viewport |
 | `over` | `boolean` | — | a drag is over the pane: a primary outline and tint |
 
-`ListPaneItem` takes `title`, `description`, `media`, `leading`, `badge`,
+`ListPaneItem` takes `title`, `titleLines` (`1` or `2`, default `1`; `2` clamps the title to two lines, the full text stays in the `title` attribute), `description`, `media`, `leading`, `badge`,
 `trailing`, `selected`, `focused` (a ring while its `group/listbox` parent has
 visible focus), `disabled`, `density` (`comfortable` or `compact`, one line),
 `appearance` (`plain` or `card`) and `lifted` (raised, as under a drag). It is

package/docs/components/date-and-time.md

@@ -1,6 +1,6 @@
 # Date & time
 
-Calendars and the fields that pick a day, a range, a time or a duration.
+Calendars and the fields that pick a day, a range, a time, a duration or an age.
 Every field comes with a React Hook Form wrapper (`DateFormField`…) that
 takes `control` and `name` — see the [forms guide](../guides/forms.md) for
 wiring, and [what each field emits](../guides/forms.md#what-each-field-emits)
@@ -19,6 +19,7 @@ each change and, where one is left, the prop that keeps the old behaviour.
 | <img src="../previews/date-time-daterangefield.webp" width="96" alt=""> | [DateRangeField](#daterangefield) | From / to range, typed or picked in a calendar (two months on a desktop, a bottom sheet on a phone) |
 | <img src="../previews/date-time-timefield.webp" width="96" alt=""> | [TimeField](#timefield) | A time typed in segments or picked in a `TimePicker` (a bottom sheet on a phone) |
 | <img src="../previews/date-time-timepicker.webp" width="96" alt=""> | [TimePicker](#timepicker) | Hour and minute tiles (or columns) with AM / PM |
+| <img src="../previews/date-time-agefield.webp" width="96" alt=""> | [AgeField](#agefield) | An age as a number and a unit (days, weeks, months, years), read aloud by locale: "2 months" |
 | <img src="../previews/date-time-durationfield.webp" width="96" alt=""> | [DurationField](#durationfield) | Hours and minutes as a total in minutes, typed on one line: "1 h 29 min" |
 | <img src="../previews/date-time-halfdayrangefield.webp" width="96" alt=""> | [HalfDayRangeField](#halfdayrangefield) | A range whose two ends are each a day plus morning or afternoon, ordered on the half |
 | <img src="../previews/date-time-minimonth.webp" width="96" alt=""> | [MiniMonth](#minimonth) | Compact month navigator with event dots and a keyboard date grid |
@@ -807,6 +808,57 @@ await user.click(within(screen.getByRole('listbox', { name: 'Minutes' })).getByR
 
 ---
 
+## AgeField
+
+![AgeField](../previews/date-time-agefield.webp)
+
+An age as one number and one unit, for what is scheduled by age (a dose due at
+2 months, a check at 11 years) or by interval. It is a `QuantityField` whose
+unit is day, week, month or year: one label, a number with its steppers, a unit
+picker, and one message under the pair.
+
+```tsx
+import { AgeField, type AgeValue } from '@nxgt/material/components';
+import { useState } from 'react';
+
+export function DueAt() {
+	const [age, setAge] = useState<AgeValue>({ value: 2, unit: 'month' });
+	return <AgeField label="Due at" units={['week', 'month', 'year']} value={age} onChange={setAge} />;
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `AgeValue` = `{ value: number \| null; unit: AgeUnit }` | `{ value: null, unit: <first unit> }` | the number (`null` while empty) and its unit |
+| `onChange` | `(value: AgeValue) => void` | — | fires on a number or a unit change |
+| `units` | `AgeUnit[]` (`'day' \| 'week' \| 'month' \| 'year'`) | all four | the units offered, in this order; the first is the unit of an empty field |
+| `min` / `max` | `number \| Partial<Record<AgeUnit, number>>` | `min` 0, no `max` | one bound for every unit, or one per unit (`max={{ month: 23, year: 120 }}`); the bound of the chosen unit applies |
+| `name` | `string` | — | a native form posts `${name}.value` and `${name}.unit` |
+| `required`, `disabled`, `error`, `helperText`, `hideSteppers` | | | as in `QuantityField` |
+| `ref` | `Ref<HTMLInputElement>` | — | reaches the number input (`AgeFormField` passes React Hook Form's `field.ref`) |
+
+**Read aloud.** The unit names are plural-aware and translated
+(`material.age-field.unit-day`, `unit-week`, `unit-month`, `unit-year`: "1 month",
+"2 months", « 2 mois »), and a polite status says the whole age when it changes
+(`material.age-field.reading`). `ageReading(t, 2, 'month')` gives the same text
+for your own use. The unit picker is named "Age unit" (`material.age-field.unit`).
+
+**In tests.** One `group` named by the label, a `spinbutton` for the number
+and a `combobox` named "Age unit":
+
+```ts
+await user.click(screen.getByRole('combobox', { name: 'Age unit' }));
+await user.click(await screen.findByRole('option', { name: 'years' }));
+```
+
+**Emits:** `{ value: number | null, unit: AgeUnit }`.
+**Form wrapper:** `AgeFormField` — `control` and `name`; an error on the field,
+on `<name>.value` or on `<name>.unit` shows as the one message. See
+[forms](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Date & time/AgeField` · **Vue:** none yet
+
+---
+
 ## DurationField
 
 ![DurationField](../previews/date-time-durationfield.webp)

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

@@ -660,7 +660,7 @@ The default description is the companion of its title: with your own `title` and
 
 ![PageLoadFailed](../previews/feedback-status-pageloadfailed.webp)
 
-An `EmptyState` for a list page opened at a cursor that failed to load (a stale link, a lost page): a title and a tonal "Back to the start" link. The link is rendered by the `LinkComponentProvider`'s component. For the next page of a list that is already shown, use [`LoadMoreFooter`](./buttons-and-actions.md#loadmorefooter), which keeps the rows.
+An `EmptyState` for a list page opened at a cursor that failed to load (a stale link, a lost page): a title and a tonal "Back to the start" link, with an optional filled Retry. The link is rendered by the `LinkComponentProvider`'s component. For the next page of a list that is already shown, use [`LoadMoreFooter`](./buttons-and-actions.md#loadmorefooter), which keeps the rows.
 
 ```tsx
 import { PageLoadFailed } from '@nxgt/material/components';
@@ -668,13 +668,22 @@ import { PageLoadFailed } from '@nxgt/material/components';
 <PageLoadFailed href="/orders" />;
 ```
 
+With a retry (the promise keeps Retry loading until it settles; the link turns ghost):
+
+```tsx
+<PageLoadFailed href="/orders" onRetry={() => refetch()} />;
+```
+
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `href` | `string` | — | where "Back to the start" goes: the list without its cursor |
 | `linkLabel` | `string` | `"Back to the start"` (translated) | the link's text |
+| `onRetry` | `() => unknown` | — | shows a filled Retry before the link (the link turns ghost); a returned promise keeps it loading until settled |
+| `retrying` | `boolean` | from the promise | forces Retry's loading state |
+| `retryLabel` | `ReactNode` | `"Retry"` (translated) | Retry's text |
 | `title` | `ReactNode` | `"This page could not be loaded"` (translated) | the title |
 
-It takes the other `EmptyState` props (`size`, `illustration`, `description`, `headingLevel`) except `action`. Texts are `material.load-more.page-failed-title` and `.back-to-start`.
+It takes the other `EmptyState` props (`size`, `illustration`, `description`, `headingLevel`) except `action`. Texts are `material.load-more.page-failed-title`, `material.load-more.back-to-start` and, for Retry, `material.error-state.retry`.
 
 **Storybook:** `Feedback & status/PageLoadFailed` · **Vue:** not yet (tracked as a `vue` issue)
 
@@ -1139,7 +1148,15 @@ of a [`MediaPlayerHost`](./media-and-files.md#mediaplayerhost)'s docked bar
 corner (`--nxgt-media-float`: a host's, or a `floatOnScroll` player's, with
 or without a host), so toasts never cover them. An
 `offset` or `mobileOffset` you pass replaces that default: add the variables
-yourself, e.g. `offset={{ bottom: 'calc(32px + var(--nxgt-media-dock, 0px) + var(--nxgt-media-float, 0px))' }}`.
+yourself, e.g. `offset={{ bottom: 'calc(32px + var(--nxgt-media-dock, 0px) + var(--nxgt-media-float, 0px) + var(--nxgt-sticky-bar, 0px))' }}`.
+
+**Above a `StickyActionBar`:** the bottom offsets, on a desktop and on a
+phone, also add the height of a mounted
+[`StickyActionBar`](./navigation-and-layout.md#stickyactionbar)
+(`--nxgt-sticky-bar`, 0 when none is mounted), so a toast never covers the
+bar's primary action. An `offset` or `mobileOffset` you pass drops that too:
+add `var(--nxgt-sticky-bar, 0px)` yourself, e.g.
+`offset={{ bottom: 'calc(32px + var(--nxgt-sticky-bar, 0px))' }}`.
 
 ```tsx
 <Toaster />                         // bottom-right on a desktop, top-center on a phone

package/docs/components/form-fields.md

@@ -573,7 +573,7 @@ export function Quantity() {
 | `min`, `max` | `number` | — | clamps typed and stepped values |
 | `step` | `number` | `1` | the +/− increment |
 | `hideSteppers` | `boolean` | `false` | hides the +/− buttons |
-| `suffix` | `ReactNode` | — | unit after the input |
+| `suffix` | `ReactNode` | — | unit shown inside the input box, at its end |
 | `aria-label` | `string` | — | names the input when it has no `label` (a part of a larger field) |
 | `aria-labelledby` | `string` | — | names the input by another element's id (a part of a larger field) |
 | `aria-describedby` | `string` | — | more ids describing the input, after its `helperText` (an error the larger field shows) |
@@ -1662,6 +1662,7 @@ import { Switch } from '@nxgt/material/components';
 | `helperText` | `ReactNode` | — | line under the row (or under the bare switch), with or without `placeholder`; `SwitchFormField` puts the validation message here |
 | `error` | `boolean` | — | error border on the row, error helper text, `aria-invalid` on the `switch` (a passed `aria-invalid` wins) |
 | `thumbIcons` | `boolean` | `false` | a 24px thumb in both states, a cross when off and a check when on |
+| `variant` | `'box' \| 'plain'` | `'box'` | `plain` draws a labelled switch with no border and no tint: the label beside the switch. No effect on a bare switch |
 | `className` | `string` | — | on the outermost element: the field, else the row, else the switch |
 
 ```tsx
@@ -1670,6 +1671,14 @@ import { Switch } from '@nxgt/material/components';
 
 `SwitchField`, `SwitchFormField` and `<Field type="switch">` take `thumbIcons` too.
 
+```tsx
+<SwitchFormField control={control} name="notify" label="Notify me" variant="plain" />
+```
+
+`SwitchField` and `<Field type="switch">` take `variant` too. `plain` keeps the
+row's layout, tap target and `<label for>`; an `error` still shows in the
+helper text and `aria-invalid`.
+
 The switch is a 52x32 track with a 2px outline when off and the accent fill when
 on; the thumb grows from 16px to 24px and carries a check, and a round state
 layer follows it. Everything is instant under reduced motion and uses system
@@ -1703,7 +1712,7 @@ libraries; neither name is deprecated, and both keep working.
 **Emits:** `boolean`.
 **Form wrapper:** `SwitchFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Form fields/Switch` · **Vue:** `Switch`, `SwitchField`, `SwitchFormField`
+**Storybook:** `Form fields/Switch` · **Vue:** `Switch`, `SwitchField`, `SwitchFormField` (no `variant` yet)
 
 ---
 

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

@@ -81,7 +81,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`, `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)), and `children` (read by `navigation="top"`, which opens them in a dropdown under a parent that is then only a trigger; by `navigation="two-level"`, which lists them in the panel beside the rail, one level deep; by the phone's menu sheet and the expanded sidebar, which nest them under the parent's own link), `group`, `bar`, `priority` for the navigation presets that read them (the drawer reads `group`, the bar `bar` and `priority`; the floating toolbar, not drawn yet, is the only preset still to read them) |
+| `items` | `MenuItem[]` | — | `label` (already translated), `url`, `icon`, `footer`, `display` (`'icon'`: a round icon-only button, the label as tooltip and name, in the rail and the expanded sidebar; the phone's menu sheet always shows icon and label; 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)), and `children` (read by `navigation="top"`, which opens them in a dropdown under a parent that is then only a trigger; by `navigation="two-level"`, which lists them in the panel beside the rail, one level deep; by the phone's menu sheet and the expanded sidebar, which nest them under the parent's own link, unless the entry sets `childrenIn: 'sidebar'`, which keeps them to the sidebar and the top dropdown), `childrenIn`, `group`, `bar`, `priority` for the navigation presets that read them (the drawer reads `group`, the bar `bar` and `priority`; the floating toolbar, not drawn yet, is the only preset still to read them) |
 | `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href`; see the [app shell guide](../guides/app-shell.md). Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 | `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)) |
@@ -104,7 +104,7 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 | `width` | `'full' \| 'form' \| 'reading'` | `'full'` | `ActivityContent`: caps the main column at 48rem (`'form'`) or 72ch (`'reading'`), the side panel right beside it |
 | `notice` | `ReactNode` | — | `ActivityContent`: a notice above the column and the side panel, at their width, taking its own height; first on a phone |
 | `aside`, `asideLabel` / `asideLabelledBy` | `ReactNode`, `string` | — | `ActivityContent`: a side panel, a named `complementary` landmark, beside the content from 1280px (CSS only), stacked below; sticky under the app bar |
-| `asideSide` / `asideWidth` / `asideFrom` / `asideSticky` / `asideStack` | `'start' \| 'end'` / `'sm' \| 'md' \| 'lg' \| string` / `'lg' \| 'xl' \| '2xl'` / `boolean` / `'before' \| 'after'` | `'end'` / `'md'` / `'xl'` / `true` / `'after'` | `ActivityContent`: the panel's side, width (16, 20, 24rem), breakpoint, stickiness and stacking order (see the [app shell guide](../guides/app-shell.md#a-side-panel-and-a-readable-width)) |
+| `asideSide` / `asideWidth` / `asideFrom` / `asideSticky` / `asideStack` | `'start' \| 'end'` / `'sm' \| 'md' \| 'lg' \| string` / `'lg' \| 'xl' \| '2xl'` / `boolean` / `'before' \| 'after'` | `'end'` / `'md'` / `'xl'` / `true` / `'after'` | `ActivityContent` (`asidePhone`: the panel stacks on a phone, or with `"toggle"` sits behind a Content / Preview switch, texts `asideMainLabel` / `asidePreviewLabel`; known limit: a save bar inside the content is hidden while the preview shows): the panel's side, width (16, 20, 24rem), breakpoint, stickiness and stacking order (see the [app shell guide](../guides/app-shell.md#a-side-panel-and-a-readable-width)) |
 | `navigation` | `ShellNavigation \| { phone?, tablet?, desktop?, hideOnScroll?, persistKey? }` | `{ phone: 'modal-drawer', tablet: 'rail', desktop: 'rail' }` | `ActivityLayout`: the navigation per window size (phone below 768px, tablet to 1279px, desktop from 1280px). Every `ShellNavigation` name is drawn: `'modal-drawer'`, `'rail'`, `'rail-expanded'`, `'drawer'`, `'sidebar'`, `'top'`, `'two-level'`, `'floating'`, `'bar'` and `'none'`. `hideOnScroll` (a field of this object, `false` by default) slides the `'floating'` toolbar away on scroll; no other preset reads it. `persistKey` (a field of this object) remembers the `'rail-expanded'` rail's, the `'sidebar'`'s and the `'two-level'` panel's state. A name alone (`navigation="sidebar"`, `"drawer"`, `"top"`, `"two-level"`) leaves a phone its default navigation; `{ phone: 'sidebar' }` draws it there. A phone never draws `'rail'` or `'rail-expanded'`: it keeps its menu sheet. `navigation="bar"` alone is phone-only (hidden from 768px, where the default rail shows; `{ tablet: 'bar' }` keeps it there). `'floating'` is drawn at every size, the phone included. See [`navigation` and `header`](../guides/app-shell.md#navigation-and-header) |
 | `navigationFab` | `ReactNode \| ({ expanded }) => ReactNode` | — | `ActivityLayout`: the screen's primary action, at the top of the `'rail-expanded'` rail (a `Fab`; the function form receives the rail's state). The other presets do not draw it |
 | `sidebarExpanded` / `defaultSidebarExpanded` / `onSidebarExpandedChange` | `boolean` / `boolean` / `(expanded: boolean) => void` | — / `false` / — | `ActivityLayout`: the `'sidebar'`'s expanded state (labels beside the icons; it starts collapsed), controlled or not; with `navigation.persistKey` the last choice is kept and read after hydration |
@@ -599,6 +599,11 @@ the page. It takes a `div`'s props.
   (`interactive-widget=resizes-content`) needs no lift, and none is applied.
   Pinch-zoom is not treated as a keyboard.
 - **Name.** With `aria-label` or `aria-labelledby` the bar is a `group`.
+- **Toasts clear it.** While mounted and sticky, the bar publishes its height as
+  `--nxgt-sticky-bar` on the document root and removes it on unmount; the
+  [`Toaster`](./feedback-and-status.md#toaster)'s bottom offsets add it. With
+  several bars the latest wins. From `md` the bar is inline, so a desktop
+  toast is lifted by the bar's height.
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |

package/docs/components/primitives.md

@@ -743,6 +743,12 @@ tab order; on a touch screen 44px wide and as tall as the list, so it never cove
 scrolled into view clear of the button, instantly under reduced motion. A list that fits has
 neither, and neither is in the server markup. `segmented` does the same.
 
+**No buttons: `scrollButtons="none"`** (on `TabsList` and `TabsNav`; the default is `"auto"`, as above). The list stays a plain row that scrolls by touch, wheel and keyboard, with no chevron buttons and no tab turned transparent. The cue stays: each side with hidden tabs still sets `data-overflow-left` / `data-overflow-right` and fades softly over 1.5rem, so a half-shown tab shows that more lies beyond it, and the selected or focused tab is still scrolled into view. The list carries `data-scroll-buttons="none"`.
+
+```tsx
+<TabsList scrollButtons="none">{/* … */}</TabsList>
+```
+
 **`segmented`** is a neutral pill track: the active tab sits on a raised
 surface that slides between tabs, and its label turns to the foreground
 colour and semibold — the state never rests on the surface alone. It suits a
@@ -876,6 +882,7 @@ See [the troubleshooting entry](../troubleshooting.md#usehref-may-be-used-only-i
 | `aria-label` | `TabsNav` | `string` | — (required) | names the navigation |
 | `value` | `TabsNav` | `string` | — | the current link's `value` |
 | `variant` | `TabsNav` | `'underline' \| 'segmented'` | `'underline'` | the look, as `Tabs` |
+| `scrollButtons` | `TabsNav`, `TabsList` | `'auto' \| 'none'` | `'auto'` | `'none'` leaves out the scroll buttons: a plain scrollable row with a soft edge fade |
 | `to` | `TabsNavLink` | `To` | — (required) | the route, as for `LinkButton` |
 | `value` | `TabsNavLink` | `string` | — | matched against the nav's `value` |
 | `current` | `TabsNavLink` | `boolean` | — | marks the link current or not, over `value` |

package/docs/components/selection-and-choice.md

@@ -26,7 +26,7 @@ value type each one writes. Everything is imported from
 | <img src="../previews/selection-choice-transferlist.webp" width="96" alt=""> | [TransferList](#transferlist) | Two-pane picker |
 | <img src="../previews/selection-choice-sortablelist.webp" width="96" alt=""> | [SortableList](#sortablelist) | Reorderable list of strings |
 | <img src="../previews/selection-choice-transferlist.webp" width="96" alt=""> | [TransferList](#transferlist) | Two-pane picker: search, counts, select-all, drag between panes |
-| <img src="../previews/selection-choice-sortablelist.webp" width="96" alt=""> | [SortableList](#sortablelist) | Reorderable list: drag or keyboard, announced |
+| <img src="../previews/selection-choice-sortablelist.webp" width="96" alt=""> | [SortableList](#sortablelist) | Reorderable list: drag or keyboard, announced; two-line labels, row menu |
 | <img src="../previews/selection-choice-treeselectfield.webp" width="96" alt=""> | [TreeSelectField](#treeselectfield) | Pick from a tree, single or multiple |
 | <img src="../previews/selection-choice-switcher.webp" width="96" alt=""> | [Switcher](#switcher) | Workspace, establishment or class switcher: menu, search, groups, links; `size="compact"` an icon-only round trigger for the app bar's `titleAfter` slot |
 
@@ -1182,6 +1182,8 @@ export function Ranking() {
 | `appearance` | `'cards' \| 'plain'` | `'cards'` | raised cards, or flat rows in one surface |
 | `density` | `'comfortable' \| 'compact'` | `'comfortable'` | `compact`: one-line rows |
 | `dragActivator` | `'row' \| 'handle'` | `'row'` | what starts a pointer drag: the whole row or only its grip |
+| `labelLines` | `1 \| 2` | `1` | lines a row's label may take before an ellipsis; `2` for long labels at phone width (the full text stays in the `title`). Ignored with `renderItem` |
+| `rowActions` | `(item) => SortableListRowAction[] \| undefined` | — | a "..." menu on each row, before the remove button, named "Actions for {label}" (44 px on touch); `SortableListRowAction` is `RowMenuItem`; `[]` or nothing means no menu. The trigger stays enabled on a `locked` row (edit or duplicate do not move it): return `[]` for a locked item to leave it out. On a touch pointer the trigger is 44 px, so a `compact` row grows to fit it; with a fine pointer it stays 36 px. Ignored with `renderItem` |
 
 `SortableListItem` also takes `avatar`, `badge` and `locked` (the row stays
 where it is: no grip, not draggable, not movable from the keyboard, not
@@ -1196,7 +1198,7 @@ await user.click(within(rows[0]).getByRole('button', { name: /^Move down/ }));
 ```
 
 **Emits:** `string[]`, in the new order.
-**Form wrapper:** `SortableListFormField` — `control` and `name` plus the same props, `hideLabel` included (the label's `required` asterisk is hidden with it; the asterisk only: a `list` takes no `aria-required`, so a required list is described by a visually hidden "This field is required."), see
+**Form wrapper:** `SortableListFormField` — `control` and `name` plus the same props, `hideLabel`, `labelLines` and `rowActions` included (the label's `required` asterisk is hidden with it; the asterisk only: a `list` takes no `aria-required`, so a required list is described by a visually hidden "This field is required."), see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
 **Storybook:** `Selection & choice/SortableList` · **Vue:** `SortableList`, `SortableListFormField`