@nxgt/material 3.103.0 → 3.105.0

package/dist/{use-heading-spy-CO3_AtY9.js → use-heading-spy-FIZlf9qj.js}

@@ -1,9 +1,9 @@
 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-NFyAiSqc.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-CK_47jfm.js";
 import { t as l } from "./label-DR-zZyGQ.js";
-import { a as u } from "./button-Be7GZzF9.js";
-import { i as d } from "./translate-material-Du0j0t97.js";
-import { t as f } from "./use-material-translation-uNc1FyC8.js";
+import { a as u } from "./button-YfEMZbRO.js";
+import { i as d } from "./translate-material-s_lxIV43.js";
+import { t as f } from "./use-material-translation-xNzbSVgS.js";
 import { _ as p, g as m, h, t as g, v as _, y as v } from "./date.utils-JTEIo3mM.js";
 import { t as y } from "./input-CC2joTjB.js";
 import { useCallback as b, useEffect as x, useId as S, useMemo as C, useRef as w, useState as T } from "react";

package/dist/{use-material-translation-uNc1FyC8.js → use-material-translation-xNzbSVgS.js}

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

package/dist/{use-return-focus-AfLRrUm-.js → use-return-focus-CW9KkDkp.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-Cg0y_E_K.js";
+import { C as o, S as s, x as c } from "./spinner-CEVomQ5K.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/README.md

@@ -22,7 +22,7 @@ detail: every option, the second example, and the traps.
 | [Layouts](guides/layouts.md) | You are choosing a navigation preset, an app bar variant or a page layout, and want one working example of each |
 | [Animations](guides/animations.md) | You animate with `animate-*` classes: setup next to `tw-animate-css`, every animation with its defaults, the modifiers, stagger, text splitting, scroll-driven animation, appear/disappear, reduced motion, recipes and browser support |
 | [Theming](guides/theming.md) | You want to change colours or radius, use a shipped theme (`@nxgt/material/themes/<name>.css`) or a themed zone, add dark mode without a flash, use tones (the `data-tone` channel and app tones), or use the compiled CSS without Tailwind |
-| [Printing](guides/printing.md) | You render PDF documents with `@nxgt/material/print`, turn them into a download, a new tab or a server response, write them as plain data, or bundle them into an SSR server |
+| [Printing](guides/printing.md) | You render PDF documents with `@nxgt/material/print`, turn them into a download, a new tab or a server response, write them as plain data, bundle them into an SSR server, or export a list as CSV with `toCsv` and `csvResponse` |
 | [PDF reader](guides/pdf-reader.md) | You render PDFs with `@nxgt/material/pdf-reader`: the pdf.js assets and worker, `configurePdfReader`, server rendering, the Content-Security-Policy and moving from the classic reader (removed in 3.0) |
 | [Media players](guides/media.md) | You play video or audio: embedded, audio cards, playlists, chapters and transcript, sound across pages with `MediaPlayerHost`, the lightbox, CSP and keyboard |
 | [Streaming (HLS)](guides/media-streaming.md) | You play `.m3u8` streams in `MediaPlayer` with `@nxgt/material/media-hls` |

package/docs/components/README.md

@@ -34,6 +34,7 @@ Anything you press that is not a field: buttons, split buttons, floating action
 [<img src="../previews/buttons-actions-toolbar.webp" height="72" alt="Toolbar">](buttons-and-actions.md#toolbar)
 [<img src="../previews/buttons-actions-iconbutton.webp" height="72" alt="IconButton">](buttons-and-actions.md#iconbutton)
 [<img src="../previews/buttons-actions-actioncard.webp" height="72" alt="ActionCard">](buttons-and-actions.md#actioncard)
+[<img src="../previews/buttons-actions-producttile.webp" height="72" alt="ProductTile">](buttons-and-actions.md#producttile)
 
 ## [Form fields](form-fields.md)
 

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

@@ -24,6 +24,7 @@ and language switches. Everything is imported from `@nxgt/material/components`.
 | <img src="../previews/buttons-actions-scrolltotop.webp" width="96" alt=""> | [ScrollToTop](#scrolltotop) | Appears past a scroll threshold |
 | <img src="../previews/buttons-actions-scrolltolatestbutton.webp" width="96" alt=""> | [ScrollToLatestButton](#scrolltolatestbutton) | "Jump to latest" over a scroll box, counting what arrived |
 | <img src="../previews/buttons-actions-actioncard.webp" width="96" alt=""> | [ActionCard](#actioncard) | Clickable card, a button (`aria-pressed`) when it chooses or reacts, with an active indicator; `status`, `meta`, a trailing `action` and a `tile` variant |
+| <img src="../previews/buttons-actions-producttile.webp" width="96" alt=""> | [ProductTile](#producttile) | Large tap tile for a till or kiosk catalogue: picture or icon, name, price, stock state |
 | <img src="../previews/buttons-actions-themetoggle.webp" width="96" alt=""> | [ThemeToggle](#themetoggle) | Light / dark / system switch |
 | <img src="../previews/buttons-actions-languageswitcher.webp" width="96" alt=""> | [LanguageSwitcher](#languageswitcher) | Menu of the `I18nProvider` languages |
 
@@ -1335,6 +1336,52 @@ A whole board built on it, with sections (each its own h2 and free count) and, w
 
 ---
 
+## ProductTile
+
+![ProductTile](../previews/buttons-actions-producttile.webp)
+
+A large, even tap tile for a point-of-sale or kiosk catalogue: a picture (or a toned shape with an icon), the item's name, a prominent price and a stock state on its own line. `ActionCard` has no media or price slot; this is the tile for a catalogue.
+
+```tsx
+import { Badge, ProductTile, ResponsiveGrid } from '@nxgt/material/components';
+
+<ResponsiveGrid minItem="9rem" gap="md">
+	<ProductTile
+		title="Orange juice 1 L"
+		price="1,500"
+		icon="bottle-water"
+		selected={basket.has(id)}
+		onClick={() => add(id)}
+	/>
+	<ProductTile
+		title="Free-range eggs, tray of thirty"
+		price="4,800"
+		image="/eggs.jpg"
+		disabled
+		status={<Badge variant="soft" tone="error">Out of stock</Badge>}
+	/>
+</ResponsiveGrid>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` | required | The name, up to two lines |
+| `price` | `ReactNode` | none | Large and tabular (`tabular-nums`), at the foot of the tile; format it with the app's locale |
+| `status` | `ReactNode` | none | The stock state, on its own line under the price (a `Badge`) |
+| `image` | `string` | none | The photo's URL (a square one fits best), in a tinted 4:3 well, lazy loaded, with an empty `alt` (the title names the tile). If it fails to load, the toned `icon` shape takes its place |
+| `imageFit` | `'contain' \| 'cover'` | `contain` | `contain` for a cut-out PNG or a packshot on white, `cover` for a full-bleed photo |
+| `icon`, `tone`, `shape` | `IconName`, `Tone`, `ShapeName` | `primary`, `squircle` | Without an `image` (or when it fails), a toned shape with this icon, in the same 4:3 well, so tiles with and without a photo share one height |
+| `media` | `ReactNode` | none | Your own media in place of the box; replaces `image` and `icon` |
+| `selected` | `boolean` | `false` | `aria-pressed`, a tint and a bar at the start (the item is in the basket) |
+| `disabled` | `boolean` | `false` | Dimmed and not tappable; its text, status included, is still read |
+| `asChild` | `boolean` | `false` | Render inside the one child (a router `Link`): `<ProductTile asChild title="…"><Link to="…" /></ProductTile>`. `selected` is then `aria-current`, `disabled` is `aria-disabled`, `tabIndex={-1}` and a cancelled click, so a link leaves the Tab order and Enter does not follow it; `onClick` is not called |
+
+The tile is one `button` named by its text: `getByRole('button', { name: /Orange juice.*1,500/ })`. It is a hairline card, at least 44 px high under a coarse pointer, and fills its grid cell (`h-full`): the name takes two lines and the status line is always reserved, so tiles of a row share one height. `minItem="9rem"` gives two columns at 360 px. It has a pressed state, a focus ring and a dark mode. It takes the `button`'s props, so `className` adds to it.
+
+**Storybook:** `Buttons & actions/ProductTile` · **Vue:** later
+
+---
+
 ## ThemeToggle
 
 ![ThemeToggle](../previews/buttons-actions-themetoggle.webp)

package/docs/components/data-display.md

@@ -601,7 +601,7 @@ text colour, 4.5:1 or more on the page and in a card; the `outlined` hairline
 and the `tag` dot still read `--chip-tone`, not the tone channel); `tag`
 a smaller tag led by a colour dot; `dashed` a muted "add" pill. 28px tall,
 24px with `size="sm"`, 44px with `size="lg"`. Selected (`active`, or `aria-pressed` on a toggle
-chip) takes a primary tint and a primary edge, and a pressed toggle with
+chip) takes a primary tint and a primary edge (a pressed toggle chip with a `color` shows the filled tone under its on-colour instead), and a pressed toggle with
 nothing leading draws a check. An unselected neutral toggle chip keeps a
 boundary of at least 3:1 against the page and the card. The label is truncated as one piece; the ✕
 and `trailing` stay whole.
@@ -631,7 +631,7 @@ import { Avatar, Chip } from '@nxgt/material/components';
 | `active` | `boolean` | — | selected: primary tint and edge |
 | `aria-pressed` | `boolean` | — | a toggle chip: selected while pressed, with a check when nothing leads |
 | `size` | `'default' \| 'sm' \| 'lg'` | `'default'` | 28px, 24px, or `lg`, a 44px box at every pointer (the touch target); every target stays at least 24px |
-| `color` | `'default' \| 'primary' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'error'` | neutral | tone: the edge (outlined), the fill and label (tonal, `filled`: a status look) or the dot and tint (tag). A `tag` without `color` (or with `default`) draws no dot |
+| `color` | `'default'` or any `Tone` (the eight named tones, or one declared in `AppTones`) | neutral | tone: the edge (outlined), the fill and label (tonal, `filled`: a status look) or the dot and tint (tag). A `tag` without `color` (or with `default`) draws no dot |
 | `onDismiss` | `() => void` | — | adds the ✕ button, named "Remove {label}" (`material.chip.dismiss-label`), `{label}` being the text `label` shows, a node's included; "Remove" when it shows none; the ✕ is drawn 18px (16px small) in its own 24x24 box (44x44 on a coarse pointer) |
 | `dismissLabel` | `string \| ((label: string) => string)` | — | names the ✕ instead of "Remove {label}": a string as is, or a function of the text the chip shows |
 | `onClick` | `MouseEventHandler` | — | makes the chip (or its body, when dismissible) a button; without it the chip is a `<span>` |

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

@@ -107,9 +107,11 @@ table enables, for typing your own column defs.
 | `onLoadMore` / `isLoadingMore` | `() => void` / `boolean` | — | adds a "load more" button under the rows |
 | `options` | `{ showPage?: boolean; showSelected?: boolean }` | both `true` | parts of the footer |
 | `showHeader` | `boolean` | shown | header row (column names, sorting, "Select all") at every width; `false` hides it |
+| `showSort` | `boolean` | shown | `false` drops the sort control of the `cards` and `tiles` list bar (on a phone too); columns stay sortable and a `table` keeps its header sorting ([Cards and tiles](../guides/cards-and-tiles.md#sorting)) |
 | `maxHeight` | `number \| string` | none | caps the table's height (`400`, `'60vh'`); the rows scroll inside it |
+| `maxHeightClassName` | class | none | the same cap as a Tailwind class (`'max-h-[28rem]'`), with no inline `style` on the scroll region, server included; wins over `maxHeight` |
 | `scrollLabel` | `string` | "Scrollable table" | the name of the scroll region the table becomes while it overflows |
-| `virtual` | `boolean \| { estimateSize?, overscan?, ssrRows? }` | off | renders only the rows in view, for long lists; needs `maxHeight`. Client mode shows every filtered and sorted row with no paging and no pagination footer; `manual` virtualizes the rows given. Defaults: `estimateSize` 36 (px, a comfortable row without the gap between rows), `overscan` 8, `ssrRows` 50. `renderExpandedRow` is ignored while it is on ([long lists](#long-lists)) |
+| `virtual` | `boolean \| { estimateSize?, overscan?, ssrRows? }` | off | renders only the rows in view, for long lists; needs `maxHeight` or `maxHeightClassName`. Client mode shows every filtered and sorted row with no paging and no pagination footer; `manual` virtualizes the rows given. Defaults: `estimateSize` 36 (px, a comfortable row without the gap between rows), `overscan` 8, `ssrRows` 50. `renderExpandedRow` is ignored while it is on ([long lists](#long-lists)) |
 | `loading` | `boolean` | `false` | skeleton rows, or the current rows dimmed; `aria-busy`; controls disabled |
 | `loadingRows` | `number` | the page size | how many skeleton rows |
 | `density` | `'comfortable' \| 'compact'` | `'comfortable'` | `compact` tightens the cell padding, the row and header heights and the gap between rows, the selection column included; it is the table's `data-density` attribute, styled with classes (no inline style). The toolbar band and the empty state keep their size; the print variant is unchanged |
@@ -527,12 +529,22 @@ Rows stay rows on a phone unless you ask for `layout="cards"`, `layout="tiles"`
   virtual
   maxHeight="70vh"
 />
+
+// Under a strict CSP (`style-src-attr 'none'`): a class, no inline style.
+<DataTable
+  data={people}
+  columns={columns}
+  getRowId={(person) => person.id}
+  virtual
+  maxHeightClassName="max-h-[28rem]"
+/>
 ```
 
 `virtual` renders only the rows in view and a few around them (`overscan`),
 between two `aria-hidden` spacer rows that stand for the rest. It needs
-`maxHeight`, since the rows scroll inside the table: without it, `virtual`
-is off and a development warning says so. In client mode every filtered and
+`maxHeight` or `maxHeightClassName`, since the rows scroll inside the table
+(the virtualizer measures the scroll region, so the class needs no number):
+without either, `virtual` is off and a development warning says so. In client mode every filtered and
 sorted row is in one scrolling list: no paging and no pagination footer
 (`onLoadMore` still shows its button). In `manual` mode the rows given are
 virtualized as they are, with the server footer.
@@ -556,8 +568,9 @@ virtualized as they are, with the server footer.
   takes over after mount. The spacers' heights are custom properties
   (`--vr-before`, `--vr-after`) written on the `<tbody>` through CSSOM, which
   `style-src-attr` does not govern: the rows add no `style` attribute to the
-  server markup. The scroll region's own `maxHeight` is still an inline
-  `style` there ([csp.md](../guides/csp.md)).
+  server markup. The scroll region's `maxHeight` is an inline
+  `style` there; pass `maxHeightClassName` instead and it has none
+  ([csp.md](../guides/csp.md)).
 
 `@nxgt/material-vue`'s `DataTable` has no `virtual` yet.
 
@@ -1070,7 +1083,7 @@ export default function Students() {
   and its "Clear search and filters" button
   (`onParamsChange(withoutFilters(params))`, then `onClearFilters`, or the
   table, or the list of cards or tiles, takes the focus). Your search box and switches stay outside.
-- **Passed through** to `DataTable`: `columns`, `maxHeight`, `scrollLabel`,
+- **Passed through** to `DataTable`: `columns`, `maxHeight`, `maxHeightClassName`, `scrollLabel`,
   `showViewOptions`, `renderExpandedRow`, `options`, `loading`,
   `loadingRows`, `getRowHref`, `onRowClick`, `linkComponent`, `density`,
   `layout`, `enableRowSelection`, `rowSelectionDisabledReason`,

package/docs/components/form-fields.md

@@ -27,6 +27,7 @@ order and roles) and the tokens that tune it.
 | <img src="../previews/form-fields-numberfield.webp" width="96" alt=""> | [NumberField](#numberfield) | `number \| null` with clamping and +/− buttons |
 | <img src="../previews/form-fields-percentfield.webp" width="96" alt=""> | [PercentField](#percentfield) | `NumberField` with a `%` suffix |
 | <img src="../previews/form-fields-quantityfield.webp" width="96" alt=""> | [QuantityField](#quantityfield) | One labelled field holding an amount and its unit |
+| <img src="../previews/form-fields-quantitystepper.webp" width="96" alt=""> | [QuantityStepper](#quantitystepper) | Inline −/value/+ control for a cart or ticket line |
 | <img src="../previews/form-fields-currencyfield.webp" width="96" alt=""> | [CurrencyField](#currencyfield) | Locale-formatted amount with a currency suffix |
 | <img src="../previews/form-fields-phonefield.webp" width="96" alt=""> | [PhoneField](#phonefield) | International number, emits E.164 |
 | <img src="../previews/form-fields-urlfield.webp" width="96" alt=""> | [UrlField](#urlfield) | Validates on blur, open and copy buttons |
@@ -802,7 +803,7 @@ phone: the chip truncates before the value does (see The unit chip below).
 | `control`, `name` | `Control<T>`, `Path<T>` | — | the form and its `{ value, unit }` (`QuantityFormField`) |
 | `value`, `defaultValue`, `onChange` | `QuantityValue`, `(value) => void` | empty | the amount and its unit; `onChange` gets both on each change |
 | `label` | `ReactNode` | none | the one label; it names the group |
-| `units` | `{ value, label }[]` | none | the units offered |
+| `units` | `{ value, label }[]` | none | the units offered; without `units` and `allowCustomUnit` there is no unit to pick, so no chip is drawn (a plain count) |
 | `allowCustomUnit` | `boolean` | `false` | the unit menu gets a "Search or type a unit" input and a "Use “x”" item, so a unit outside `units` can be typed; otherwise it is a plain listbox of `units` |
 | `min`, `max`, `step`, `hideSteppers` | | `step` 1 | as `NumberField` |
 | `unitLabel`, `unitPlaceholder` | `string` | "<label> unit" | `unitLabel` names the unit part (the menu's name; the chip reads "<unitLabel>: mg"); `unitPlaceholder` shows while no unit is chosen |
@@ -812,15 +813,16 @@ phone: the chip truncates before the value does (see The unit chip below).
 | `required`, `disabled`, `placeholder`, `id`, `ref` | | | `required` applies to the number only; to require a unit, validate `unit` in the form schema. `placeholder`, `id` and `ref` reach the number input (React Hook Form's `field.ref` focuses it on an error) |
 
 - **Semantics:** a `<fieldset>` (role `group`) named by the label; the number
-  is a textbox named after the label, the unit chip a button named "Unit: mg"
-  (`aria-expanded`; it opens a popover), the menu a listbox named
-  "Dose unit". The message describes the group, the number and the chip, and
-  the number is `aria-invalid` on an error.
-- **Keyboard:** Tab goes value, unit chip, Decrease, Increase. Enter, Space or
+  is a textbox named after the label, the unit chip (when drawn) a button
+  named "Unit: mg" (`aria-expanded`; it opens a popover), the menu a listbox
+  named "Dose unit". The message describes the group, the number and the chip,
+  and the number is `aria-invalid` on an error. Without a chip there is no
+  unit button or listbox.
+- **Keyboard:** Tab goes value, unit chip (when drawn), Decrease, Increase. Enter, Space or
   ArrowDown on the chip opens the menu (focus lands on the list, or on the
   search with `allowCustomUnit`); the arrows move, Enter picks, Esc closes and
   returns focus to the chip.
-- **The unit chip:** one focus ring for the whole box, whichever part has
+- **The unit chip** (drawn only with `units` or `allowCustomUnit`; a plain `<QuantityField label="Count" />` has none, and Tab goes value, Decrease, Increase): one focus ring for the whole box, whichever part has
   focus. The chip is capped at 52% of the box and truncates a long label with
   an ellipsis (the full label is its `title`); the value keeps room for about
   4 digits at 360px. A coarse pointer gets 44px targets. Disabled, the chip
@@ -836,6 +838,57 @@ phone: the chip truncates before the value does (see The unit chip below).
 
 ---
 
+## QuantityStepper
+
+![QuantityStepper](../previews/form-fields-quantitystepper.webp)
+
+A compact inline −/value/+ control for a cart or ticket line, where a
+[`NumberField`](#numberfield) or [`QuantityField`](#quantityfield) (a labelled
+box) is too heavy. It has no label and no border: a `group` named by your
+`aria-label` ("Quantity of Orange juice") holding a minus button, the value and
+a plus button. It is an uncontrolled or controlled number, not a form field.
+
+```tsx
+import { QuantityStepper } from '@nxgt/material/components';
+import { useState } from 'react';
+
+export function Line() {
+  const [qty, setQty] = useState(2);
+  return (
+    <QuantityStepper
+      aria-label="Quantity of Orange juice"
+      value={qty}
+      onValueChange={setQty}
+      min={1}
+      max={20}
+      onRemove={() => removeLine()}
+    />
+  );
+}
+```
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `aria-label` | `string` | required | Names the group and the value; the buttons are "Decrease …", "Increase …" and "Remove …" followed by it |
+| `value` / `defaultValue` | `number` | `min` | Controlled / uncontrolled value |
+| `onValueChange` | `(value: number) => void` | none | Called with the new value, always within `min` and `max` |
+| `min`, `max` | `number` | `0`, none | The limits; the minus (or plus) button is `aria-disabled` at its limit |
+| `step` | `number` | `1` | What a button or an arrow key adds; Page Up/Down use ten steps, Home/End jump to `min`/`max` |
+| `size` | `'sm' \| 'md'` | `'md'` | 32px or 36px buttons; both are 44px under a coarse pointer |
+| `editable` | `boolean` | `false` | The value is a text input: committed on Enter or blur (clamped; text that is not a number is dropped), Escape cancels; only Up/Down and Page Up/Down step it, Left/Right/Home/End move the caret |
+| `onRemove` | `() => void` | none | At `min`, the minus button becomes a trash button named "Remove …" that calls this instead of stepping |
+| `disabled` | `boolean` | `false` | Disables every control |
+
+The value is a `spinbutton` (`aria-valuenow`, `aria-valuemin`, `aria-valuemax`)
+in tabular figures, so the row does not shift as digits change. The stepper is
+inline (`inline-flex`): put it in a `ListTile`'s `trailing` or `content`. The
+text is translated through `material.number-field.*` and
+`material.quantity-stepper.remove`.
+
+**Storybook:** `Form fields/QuantityStepper` · **Vue:** later
+
+---
+
 ## CurrencyField
 
 ![CurrencyField](../previews/form-fields-currencyfield.webp)

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

@@ -82,7 +82,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, 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`, `defaultExpanded` (the expanded sidebar folds the entry's children from a chevron button, open at first when `true`, folded when `false`; unset, they are always listed), `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`, `defaultExpanded` (the expanded sidebar folds the entry's children from a chevron button, open at first when `true`, folded when `false`; unset, they are always listed), `persistKey` (remembers a collapsible group's fold state in this browser: a string key, or `true` to derive it from `navigation.persistKey` and the `url`), `badgeWhen` (`'collapsed'`: a collapsible group's own `badge` shows only while it is folded), `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)) |
@@ -670,7 +670,7 @@ import { ListDetailsLayout, PaneLayout, ThreadLayout } from '@nxgt/material/comp
   </ListDetailsLayout.Details>
 </ListDetailsLayout>
 
-<PaneLayout defaultOpen paneSide="right">
+<PaneLayout defaultOpen="desktop" paneSide="right">
   <PaneLayout.Content>
     <PaneLayout.Trigger>Folders</PaneLayout.Trigger>
     {messages}
@@ -716,10 +716,25 @@ takes over. A page rendered only in the browser starts on the real layout.
   container and the flex row moves to an inner `data-slot="pane-layout-body"`.
 - `paneWidth`: `'sm'` (16rem), `'md'` (20rem, default) or `'lg'` (24rem) for
   the inline pane; no style attribute, so it holds under a strict CSP.
+- `defaultOpen`: `true` / `false` for every viewport, `'desktop'` (open wide,
+  shut on a phone) or `{ desktop, phone }` (a missing key is shut). The state
+  follows the viewport until the user opens or closes the pane, so a cart that
+  starts open on desktop never opens its sheet over a phone, with no effect
+  and no flash: the server renders the desktop value and the inline pane is
+  hidden by CSS on a phone. With `phone="stack"` the pane has no overlay to
+  hide, so a stacked pane that is open on desktop only shows for one frame
+  before closing on a phone.
+- `paneSide`: `'left'` (default) or `'right'`. The pane takes its side with a
+  CSS `order`, never by reversing the row, so the DOM and tab order are the
+  ones you write: put `PaneLayout.Content` first and the pane after it and
+  Tab reaches the content first, whichever side the pane is on.
+  Before this change a right pane written after the content sat on the left; check
+  screens that relied on it.
 - With `phone` or `breakpoint` set, the inline pane is an `<aside>` named by
   `sheetTitle` (default `Side Panel`), a landmark; the historical markup is a
   `div`. `usePaneLayout()` and the function children also get `phone`,
   `breakpoint` and `paneWidth`.
+
 `ThreadLayout` is a centred column over the app
 [background](#background) on the page ground (`bg-ground`, so a `bg-card` card stands apart) for focused flows (sign-in, onboarding), with no
 app bar. `width`, `stepperPlacement` and a sticky `footer` make it a centred form or a wizard with a side rail (see "A centred form or a wizard" below).
@@ -736,7 +751,8 @@ app bar. `width`, `stepperPlacement` and a sticky `footer` make it a centred for
 | `history` / `historyParam` | `'push' \| 'replace'` / `string` | — / `'view'` | `ListDetailsLayout`: keep the view in the URL (`?view=details`), through React Router |
 | `listWidth` / `resizable` / `onListWidthChange` | `number` / `boolean` / `(width) => void` | `320` / `false` | `ListDetailsLayout`: the list pane's width in px; `resizable` adds a keyboard and pointer separator, 240 to 480 px |
 | `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 |
+| `open` / `onOpenChange` | `boolean` | `false` | `PaneLayout`: pane shown |
+| `defaultOpen` | `boolean \| 'desktop' \| { desktop?, phone? }` | `false` | `PaneLayout`: initial pane state per viewport |
 | `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 |
 | `header` | `ReactNode` | — | `ThreadLayout`: above the column |
@@ -1223,6 +1239,8 @@ import { PanelCard } from '@nxgt/material/components';
 
 The card is a `role="region"` labelled by its title, so `getByRole('region', { name })` finds it. Children are the card's content (`CardContent`); with none, the card is its header only. It takes the `div`'s props, so `className` adds to it.
 
+The title is set in the card-title step (`title-sm` emphasized) whatever its heading level, one step below an `ActivityContent` page title (`title-md` emphasized), so an aside never outranks the page. The level only sets the document outline, not the size.
+
 **Storybook:** `Navigation & layout/PanelCard` · **Vue:** later, [#2866](https://github.com/softistx/nxgt-material/issues/2866)
 
 ---

package/docs/components/primitives.md

@@ -83,7 +83,7 @@ opens at once.
 
 ![Collapsible](../previews/primitives-collapsible.webp)
 
-A single show / hide region and its trigger. The content springs open to its height and folds away (clipped only while it moves, so a focus ring inside is never cut). Give `CollapsibleTrigger` a `variant` for a styled trigger with a turning chevron: `tonal`, a pill that squares its corners while open, or `text`.
+A single show / hide region and its trigger. The content springs open to its height and folds away (clipped only while it moves, so a focus ring inside is never cut). Give `CollapsibleTrigger` a `variant` for a styled trigger with a turning chevron: `tonal`, a pill that squares its corners while open, or `text`. Add `flush` to a `text` trigger to drop its inline padding and take the parent's font, so a section disclosure inside `<Typography as="h3">` lines up with the headings around it.
 
 ```tsx
 import {
@@ -110,6 +110,33 @@ import {
 </Collapsible>;
 ```
 
+A flush trigger inside a heading, aligned with the headings around it:
+
+```tsx
+import {
+	Collapsible,
+	CollapsibleContent,
+	CollapsibleTrigger,
+	Typography,
+} from '@nxgt/material/components';
+
+<div className="flex w-80 flex-col gap-3">
+	<Typography as="h3" variant="title-sm" emphasized>
+		Question
+	</Typography>
+	<Collapsible>
+		<Typography as="h3" variant="title-sm" emphasized>
+			<CollapsibleTrigger variant="text" flush>
+				Details
+			</CollapsibleTrigger>
+		</Typography>
+		<CollapsibleContent className="text-muted-foreground text-sm">
+			Hidden text that opens under the heading.
+		</CollapsibleContent>
+	</Collapsible>
+</div>;
+```
+
 Parts: `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent`.
 
 | Prop | Type | Default | Effect |
@@ -117,6 +144,7 @@ Parts: `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent`.
 | `defaultOpen` / `open` | `boolean` | `false` | whether the content shows, uncontrolled / controlled |
 | `onOpenChange` | `(open: boolean) => void` | — | called when the trigger toggles it |
 | `disabled` | `boolean` | `false` | the trigger does nothing |
+| `flush` (`CollapsibleTrigger`) | `boolean` | `false` | with `variant="text"`, no inline padding and the parent's font: the label starts at the left edge and can sit in a heading; ignored on other variants |
 | `variant` (`CollapsibleTrigger`) | `'tonal' \| 'text'` | — | a styled trigger with a chevron; unset, it is unstyled as before (with `asChild`, the child takes the look and brings its own icon) |
 
 To keep the former instant toggle, pass `className="animate-none"` to
@@ -705,7 +733,7 @@ For sorting, paging and selection use `DataTable` on the
 
 ![Tabs](../previews/primitives-tabs.webp)
 
-Tabs whose triggers can take an icon, in two looks: `underline` (the default) and the `segmented` pill.
+Tabs whose triggers can take an icon, in two looks: `underline` (the default) and the `segmented` pill. `<TabsList fullWidth>` on a `segmented` list fills its container and shares the width between the tabs in equal parts (a payment-method switch); `underline` ignores it.
 
 ```tsx
 import {
@@ -767,6 +795,19 @@ few short choices, such as a view switch.
 </Tabs>
 ```
 
+**`fullWidth`** on a `segmented` `TabsList` makes the track fill its container,
+the tabs sharing the width in equal parts, whatever their labels. It suits a
+two-way switch such as a payment method.
+
+```tsx
+<Tabs defaultValue="cash" variant="segmented">
+	<TabsList fullWidth aria-label="Payment method">
+		<TabsTrigger value="cash">Cash</TabsTrigger>
+		<TabsTrigger value="card">Card</TabsTrigger>
+	</TabsList>
+</Tabs>
+```
+
 `orientation="vertical"` lays the tabs in a column, the indicator on their
 left side; the arrow keys become Up and Down.
 
@@ -825,6 +866,7 @@ as `segmented`. Both still type-check and render; write `underline` or
 | `variant` (`Tabs`) | `'underline' \| 'segmented' \| 'bar' \| 'line'` | `'underline'` | the look; `bar` and `line` are deprecated aliases of `underline` and `segmented` |
 | `defaultValue` / `value` (`Tabs`) | `string` | — | the selected tab, uncontrolled / controlled |
 | `onValueChange` (`Tabs`) | `(value: string) => void` | — | called when a trigger is selected |
+| `fullWidth` (`TabsList`) | `boolean` | `false` | `segmented` only: the track fills its container and the tabs share the width in equal parts; `underline` ignores it |
 | `orientation` (`Tabs`) | `'horizontal' \| 'vertical'` | `'horizontal'` | a row or a column, and the arrow keys' direction |
 | `dir` (`Tabs`) | `'ltr' \| 'rtl'` | `'ltr'` | the reading direction: which way the tabs run and the arrow keys move |
 | `icon` (`TabsTrigger`) | `ReactNode` | — | shown before the label |

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

@@ -840,6 +840,61 @@ export function Topics() {
 }
 ```
 
+<a id="chipgroupfield-tones"></a>
+
+An option's `tone` colours its chip with the tones `Badge` takes (`primary`,
+`secondary`, `tertiary`, `success`, `info`, `warning`, `error`, `neutral`, and
+an app's own from `AppTones`), so a category filter can match the toned tiles
+below it. An unchosen chip shows a soft tint of the tone with the tone's text
+colour; a chosen chip shows the filled tone under its on-colour, both at AA
+contrast in light and dark. The leading check, `aria-checked`, the roving
+focus and the boundary of an unchosen chip are unchanged. No `tone` keeps the
+neutral chip.
+
+```tsx
+<ChipGroupField
+	label="Categories"
+	options={[
+		{ value: 'drinks', label: 'Drinks', icon: 'glass', tone: 'info' },
+		{ value: 'bakery', label: 'Bakery', tone: 'warning' },
+		{ value: 'other', label: 'Other' },
+	]}
+	value={value}
+	onValueChange={setValue}
+/>
+```
+
+`overflow="scroll"` keeps the chips on one line that scrolls sideways (touch,
+trackpad, the wheel; a focused chip scrolls into view), with a fade at each
+edge that hides more chips and no page scroll. The roving focus and the
+selection are the same. The default `overflow="wrap"` lets the chips flow onto
+several lines; `columns` and `groups` draw a grid and ignore `overflow`.
+
+`overflow="scroll"` for one sideways-scrolling line:
+
+```tsx
+import { ChipGroupField } from '@nxgt/material/components';
+import { useState } from 'react';
+
+const subjects = ['Algebra', 'Biology', 'Chemistry', 'Drama', 'Economics', 'French'].map(
+	(label) => ({ value: label.toLowerCase(), label }),
+);
+
+export function Subjects() {
+	const [value, setValue] = useState<string[]>([]);
+	return (
+		<ChipGroupField
+			label="Subjects"
+			type="multiple"
+			overflow="scroll"
+			options={subjects}
+			value={value}
+			onValueChange={setValue}
+		/>
+	);
+}
+```
+
 Balanced by default, and the unbalanced fill:
 
 ```tsx
@@ -858,7 +913,7 @@ const four = ['a', 'b', 'c', 'd'].map((value) => ({ value, title: value.toUpperC
 | `value` / `onValueChange` | `string \| null` or `string[]` | — | the chosen value, by `type` |
 | `deselectable` | `boolean` | `false` | `single` only: pressing the chosen chip clears it |
 | `max` / `min` | `number` | — | `multiple` only: `max` blocks the other chips once reached and speaks "{count} of {max} chosen"; `min` is a hint only |
-| `options` | `{ value; label; icon?; count?; description?; disabled?; disabledReason? }[]` | — | the chips, in one flow; `count`: see [option counts](#option-counts) |
+| `options` | `{ value; label; icon?; tone?; count?; description?; disabled?; disabledReason? }[]` | — | the chips, in one flow; `count`: see [option counts](#option-counts); `tone`: see [tones](#chipgroupfield-tones) |
 | `groups` | `{ label: string; options }[]` | — | titled sections instead of `options` (it wins when both are given): see [slot picker](#slot-picker-columns-groups-and-reasons) |
 | `columns` | `number \| { base?; sm?; md?; lg? }` | — | equal-width columns (1 to 12; one count per breakpoint, each holding to the next); Up and Down then move by row. Unset, the chips flow and wrap |
 | `showDisabledReason` | `boolean` | `true` | prints a disabled option's `disabledReason` below the whole group ("Label: reason"), so the chip row keeps its wrapping; `false` leaves it to the tooltip and the accessible description |

package/docs/guides/app-shell.md

@@ -129,6 +129,8 @@ type MenuItem = {
 `badge` marks an entry that has something new (the Material 3 navigation
 badge):
 
+(A collapsible sidebar group can show its own `badge` only while folded: see `badgeWhen` with `defaultExpanded`, below.)
+
 ```tsx
 const items: MenuItem[] = [
   { label: 'Home', url: '/', icon: 'house', badge: true },            // a dot
@@ -418,8 +420,26 @@ its `url`, with its badge, for a parent page that already lists them. Unset
 chevron button after the entry (named "Collapse the group" / "Expand the group",
 `material.navigation.group-collapse` and `group-expand`) shows and hides them,
 `true` opening them at first and `false` folding them (a folded group still opens at first when the current page is one of its children). It is ignored with `display: 'icon'`. Unset, they are always
-listed, as before. The entry stays a link to its `url`; the state is local (not
-remembered), and the phone's menu sheet and the other presets ignore it.
+listed, as before. The entry stays a link to its `url`, and the phone's menu sheet and the other presets ignore it.
+
+By default the fold state is local and resets on reload. `persistKey` remembers it
+in this browser: a string is the storage key, `true` derives the key from
+`navigation.persistKey` and the entry's `url` (nothing is saved without that key).
+Like the sidebar's own collapse, the saved choice is read after hydration, so a
+server render and the first client render both follow `defaultExpanded`; a saved
+choice wins over the "current page is a child" opening. `badgeWhen: 'collapsed'`
+draws the parent's `badge` only while the group is folded, so its children's own
+badges are not signalled twice (default `'always'`).
+
+```tsx
+{
+  label: 'Groups', url: '/groups', icon: 'users', badge: true,
+  children: [{ label: 'Item A', url: '/a', badge: 2 }],
+  defaultExpanded: true,
+  persistKey: true,        // under navigation.persistKey + '/groups'
+  badgeWhen: 'collapsed',  // the dot shows only while folded
+}
+```
 
 ```tsx
 {

package/docs/guides/cards-and-tiles.md

@@ -265,6 +265,16 @@ focus. Below 30rem of list width the "Sort:" prefix is visually hidden (the name
 stays, and the button's accessible name is still "Sort: Name, Ascending").
 With no sortable column there is no control, and with neither a sortable column nor a `select` column there is no list bar.
 
+For a short list the band is noise: `showSort={false}` drops the button (on a
+phone too) and leaves every column sortable, so a
+`layout={{ phone: 'cards', wide: 'table' }}` keeps its header sorting on desktop.
+A list with a `select` column keeps its bar for "Select all". `DataTable` only:
+`ServerTable` does not pass it through.
+
+```tsx
+<DataTable layout="cards" showSort={false} renderCard={…} … />
+```
+
 ## Columns
 
 Tiles are always one column. For cards, the list's own width, not the window's, picks the columns: one, two from 36rem,

package/docs/guides/csp.md

@@ -84,9 +84,10 @@ A virtual `DataTable` (`virtual`) adds no `style` attribute either: the
 server renders its first rows as plain rows, and the spacer rows' heights
 are custom properties written through `style.setProperty` after mount,
 which `style-src-attr` does not govern (`StrictCspVirtual` renders one under
-`style-src-attr 'none'`). Its scroll region's `maxHeight` is still an inline
-`style` on the server, one of #596's (a `maxHeightClassName` for
-`DataTable`, as `DataGrid` has, is [#800](https://github.com/softistx/nxgt-material/issues/800)).
+`style-src-attr 'none'`). Its scroll region's `maxHeight` is an inline
+`style` on the server, one of #596's: give `maxHeightClassName`
+(`maxHeightClassName="max-h-[28rem]"`, as `DataGrid` has) instead, and the
+region has no `style` attribute.
 
 A keyline `Carousel` (`multi-browse`, `hero`) renders no `style` attribute
 either: its first frame comes from container-query CSS, and the masks that

package/docs/guides/data-grid.md

@@ -1123,10 +1123,11 @@ A strict policy works with no `style-src-attr 'unsafe-inline'` for the grid:
   the CSSOM, which `style-src-attr` does not govern. A frozen column's drag
   rewrites `--dg-start-*` the same way.
 - A custom editor must follow the same rule: classes only.
-- `DataTable`'s own `maxHeight` (which a virtual `DataTable` needs) is an
-  inline `style={{ maxHeight }}` on its scroll region, so it is not covered
-  by this list; the grid takes a class instead. A `maxHeightClassName` on
-  `DataTable` is proposed in [#800](https://github.com/softistx/nxgt-material/issues/800).
+- `DataTable`'s own `maxHeight` is an inline `style={{ maxHeight }}` on its
+  scroll region, so it is not covered by this list; the grid takes a class
+  instead. A virtual `DataTable` under a strict CSP takes
+  `maxHeightClassName` (a class such as `max-h-[28rem]`, no inline style;
+  [#800](https://github.com/softistx/nxgt-material/issues/800)).
 
 The grid's popups (the select's list, the date's calendar, the menus) are
 library components and add nothing to the policy: see the