@nxgt/material 3.51.0 → 3.53.0

package/dist/{use-heading-spy-C9-A2md2.js → use-heading-spy-CP63sAcS.js}

@@ -1,4 +1,4 @@
-import { r as e } from "./i18n-provider-Ang2f31m.js";
+import { r as e } from "./i18n-provider-DlVPS58N.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, useState as d } from "react";
 import { busySettler as f, busySettler as p, createSubmitGuard as m, createSubmitGuard as h } from "@nxgt/material-core/submit-guard";

package/dist/use-material-translation-nNF8fUXz.js

@@ -0,0 +1,14 @@
+import { r as e } from "./i18n-provider-DlVPS58N.js";
+import { t } from "./translate-material-q-JNxP1m.js";
+import { useCallback as n } from "react";
+//#region lib/i18n/use-material-translation.ts
+function r() {
+	let r = e(), i = r?.language, a = r?.resources;
+	return {
+		t: n((e, n, r) => t(i, e, n, r, a), [i, a]),
+		language: i,
+		hasProvider: !!r
+	};
+}
+//#endregion
+export { r as t };

package/dist/use-shape-morph-DXdy2X5g.js

@@ -0,0 +1,35 @@
+import { useLayoutEffect as e, useRef as t } from "react";
+import { morph as n, morphAt as r, toSvgPath as i } from "@nxgt/material-core/shapes";
+//#region lib/components/ui/display/shape/use-shape-morph.ts
+var a = .8, o = 14, s = o * Math.sqrt(1 - a * a);
+function c(e) {
+	let t = e / 1e3;
+	return 1 - Math.exp(-.8 * o * t) * (Math.cos(s * t) + a * o / s * Math.sin(s * t));
+}
+var l = () => typeof window.matchMedia == "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+function u(a, o, s) {
+	let u = t(o);
+	e(() => {
+		let e = a.current, t = u.current;
+		if (!e || t === o || !s || l()) {
+			e && t !== o && e.setAttribute("d", i(o)), u.current = o;
+			return;
+		}
+		let d = n(t, o), f = i(o), p = 0, m = performance.now(), h = (t) => {
+			let n = t - m;
+			if (n >= 520) {
+				u.current = o, e.setAttribute("d", f);
+				return;
+			}
+			let a = r(d, c(n));
+			u.current = a, e.setAttribute("d", i(a)), p = requestAnimationFrame(h);
+		};
+		return e.setAttribute("d", i(d.from)), p = requestAnimationFrame(h), () => cancelAnimationFrame(p);
+	}, [
+		a,
+		o,
+		s
+	]);
+}
+//#endregion
+export { u as n, c as t };

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

@@ -1138,9 +1138,38 @@ keyboard focus of the title button, only while it is clipped (Escape dismisses
 it; moving the pointer across the line does not). Without `action` the DOM is as
 before. Nothing is added for a Vue port yet (React first).
 
+#### A link title, several actions and a footer
+
+For a tile whose title goes to a page (a hospital bed, a room), pass
+`titleLink`: an element (a router `<Link to=... />`, an `<a href=...>`) that
+receives the title as its children. It is stretched over the card exactly like
+the title button and named after the title, the status and the meta. The root
+stays a plain `div`, and `onClick`, `active` and `role` are not read. `action`
+takes several controls (two menus in a fragment); `footer` (`tile` only) is a
+last row for secondary links, such as the occupant or a device, above the
+stretched link and outside its accessible name. Nothing nests, so
+`nested-interactive` stays clean; keep each footer target 44px (`min-h-11`);
+the footer wraps inside the tile at 360px.
+
+```tsx
+<ActionCard
+	variant="tile"
+	title="Bed 12A"
+	titleLink={<Link to="/beds/12a" />}
+	status={<Badge variant="soft" tone="warning">Occupied</Badge>}
+	action={<><StatusMenu /><StayMenu /></>}
+	footer={<Link to="/patients/9">DOE Jane</Link>}
+/>;
+```
+
+| Prop | Type | Effect |
+| --- | --- | --- |
+| `titleLink` | `ReactElement` | the title becomes this link (its `className` is kept); the card is one link tab stop, then the actions, then the footer links |
+| `footer` | `ReactNode` | `tile` only; secondary links under the status and meta |
+
 The root is `data-slot="action-card"` (it was the `Card` primitive's `data-slot="card"`): style it with `className`, not through `Card` classes or a `[data-slot=card]` selector.
 
-A whole board built on it, with sections and an occupancy table, is the `Guides/Recipes/Status board` recipe. **Storybook:** `Buttons & actions/ActionCard`, `Buttons & actions/ActionCard/Look`, `Buttons & actions/ActionCard/Tile`, `Buttons & actions/ActionCard/Checks` · **Vue:** `ActionCard`, with the earlier look and no button role yet (#1195)
+A whole board built on it, with sections (each its own h2 and free count) and, with `linked`, link titles and an occupant footer, and an occupancy table, is the `Guides/Recipes/Status board` recipe. **Storybook:** `Buttons & actions/ActionCard`, `Buttons & actions/ActionCard/Look`, `Buttons & actions/ActionCard/Tile`, `Buttons & actions/ActionCard/Link tile`, `Buttons & actions/ActionCard/Checks` · **Vue:** `ActionCard`, with the earlier look and no button role yet (#1195)
 
 ---
 

package/docs/components/data-display.md

@@ -642,7 +642,7 @@ import { Description } from '@nxgt/material/components';
 </div>
 ```
 
-`label` and `value` are its main props; the rest go to the `div`. A `value` of `null`, `undefined`, `false` or `''` renders nothing (`0` is shown), so optional fields need no guard. Inside a `variant="panels"` list a `Description` must sit in a `DescriptionList.Group`; otherwise it renders its stand-alone markup. The label is a small
+`label` and `value` are its main props; the rest go to the `div`. A `value` of `null`, `undefined`, `false` or `''` with no `lines` and no `children` renders nothing (`0` is shown), so optional fields need no guard. `children` alone are the value (`<Description label="Note">text</Description>`); after a `value` they follow it. Inside a `variant="panels"` list a `Description` must sit in a `DescriptionList.Group`; otherwise it renders its stand-alone markup. The label is a small
 muted caption above the value (not a title). `Description` takes one cell of
 the grid it is in; pass `className="col-start-full"` for a full-width row. It takes `lines` anywhere; inside a [`DescriptionList`](#descriptionlist) also `span` and `labelPosition`.
 
@@ -686,7 +686,7 @@ row) or a number of columns (used once that many fit; at most `maxColumns`, and
 field uses dense packing: the fields after it fill the cells before it, so they
 may be drawn above it while the DOM and reading order stay the source order.
 Put the full-width field where that reads fine, or last. A multi-line value
-(an address) takes `lines={[…]}` or `children`, never a string to split. Entries of `lines` that are `null`, `false` or `""` are skipped, and a `Description` whose `lines` are all empty and that has no `value` renders nothing.
+(an address) takes `lines={[…]}` or `children`, never a string to split. Entries of `lines` that are `null`, `false` or `""` are skipped, and a `Description` whose `lines` are all empty and that has no `value` or `children` renders nothing.
 
 ```tsx
 <DescriptionList variant="panels">
@@ -1087,7 +1087,7 @@ yours, the component names no domain.
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `entries` | `ChangeHistoryEntry[]` | — | `id`, `kind`, `at` (`Date`, string or number), `author` (`name`, `src`), `changes` (`ChangeHistoryChange[]`: `field`, `before`, `after`, `redacted`) |
+| `entries` | `ChangeHistoryEntry[]` | — | `id`, `kind`, `at` (`Date`, string or number), `author` (`name`, `src`), `changes` (optional, `ChangeHistoryChange[]`: `field`, `before`, `after`, `redacted`; left out or `[]`, the entry shows its sentence, author and time with no change list) |
 | `kinds` | `Record<string, ChangeHistoryKindOverride>` | built-ins | `label`, `verb`, `icon` (`null` removes it), `tone` per kind; `creation` (default true for `created`) makes an entry list values only |
 | `variant` | `'rail' \| 'cards'` | `'rail'` | the look |
 | `groupBy` | `'day' \| 'none'` | `'day'` | a heading per day (sticky on the rail), or one list in the order given |

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

@@ -95,8 +95,8 @@ table enables, for typing your own column defs.
 | `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)) |
-| `renderCard` | `(row, { Title, selected, locked, reason }) => ReactNode` | — | a card's content, required with `layout="cards"`; `Title` is the card's one link and its name |
-| `renderTile` | `(row, { Title, selected, locked, reason }) => ReactNode` | — | a tile's content, required with `layout="tiles"`; same `Title` as a card |
+| `renderCard` | `(row, { Title, Row, selected, locked, reason }) => ReactNode` | — | a card's content, required with `layout="cards"`; `Title` is the card's one link and its name; `Row` (the compact record row) is also passed, laid out inside the card's own padding, with no height of its own |
+| `renderTile` | `(row, { Title, Row, selected, locked, reason }) => ReactNode` | — | a tile's content, required with `layout="tiles"`; same `Title` as a card, or `Row`, the compact record row (title, subtitle, chips, trailing facts; see the cards and tiles guide) |
 | `renderExpandedRow` | `(row) => ReactNode` | — | makes rows expandable; pair with the `expand` column |
 | `showViewOptions` | `boolean` | — | column visibility menu above the table |
 | `actions` | `(table, controls) => ReactNode` | — | toolbar content with access to the table (selected rows…); disabled while `loading`. `controls.focusTable()` moves the focus to the table |

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

@@ -85,6 +85,7 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 | `titleAs` | `'h1'` … `'h6'` \| `'div'` | `'h1'` | `ActivityContent`: the title's heading level |
 | `inset` | `boolean` | `false` | `ActivityContent`: pads the content 1rem on each side. Off, it lines up with the app bar and the cards |
 | `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)) |
 | `align` | `'start' \| 'center'` | `'start'` | `ActivityLayout`, `AppSidebar`: the collapsed rail's entries sit right under the brand, or `'center'` for centred in the height below it |

package/docs/components/primitives.md

@@ -735,7 +735,7 @@ reached with the arrow keys. The list scrolls sideways when the tabs do not
 fit (its scrollbar hidden), which suits a phone or a narrow popover. While it
 overflows, each side with hidden tabs fades and gets a small scroll button
 ("Scroll tabs left" / "Scroll tabs right", from `material.tabs.*`; out of the
-tab order, 44px on a touch screen); the selected and the focused tab are
+tab order; on a touch screen 44px wide and as tall as the list, so it never covers content); the selected and the focused tab are
 scrolled into view, instantly under reduced motion. A list that fits has
 neither, and neither is in the server markup. `segmented` does the same.
 

package/docs/components/rich-widgets.md

@@ -382,7 +382,8 @@ import { LineChart } from '@nxgt/material/charts';
 ```
 
 A line chart can be read against a reference: `bands` shade a range of the
-value axis (a normal range), `thresholds` draw labelled lines and `pointTone`
+value axis (a normal range, constant or stepping along x with a row field or
+function), `thresholds` draw labelled lines and `pointTone`
 rings the values that need a word, which the tooltip, the summary and the
 "View data" table repeat
 ([guide](../guides/charts.md#reading-values-against-a-reference)).

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

@@ -1294,6 +1294,25 @@ const RouterLink: AppShellLinkComponent = ({ href, ...props }) => <Link to={href
 />;
 ```
 
+### Compact trigger for an app bar
+
+In the app bar's `titleAfter` slot the title already names the chosen record, so the full trigger repeats it. `size="compact"` renders an icon-only round button instead (32px, a 44x44 box on a coarse pointer). It is named by the label and the chosen option (`Project: Quarterly plan`, read to screen readers), the tooltip shows the option, and the panel (menu, popover or sheet) and the keyboard are unchanged. `size="default"` is the full trigger. Compact works with both variants; to compact only below `md`, pick the size with your own breakpoint hook (`size={isNarrow ? 'compact' : 'default'}`).
+
+```tsx
+export const handle = {
+	title: 'Quarterly plan',
+	titleAfter: (
+		<Switcher
+			size="compact"
+			label="Project"
+			value="a"
+			options={projects}
+			getHref={(item) => `/projects/${item.id}`}
+		/>
+	),
+};
+```
+
 ### Expressive
 
 `variant="expressive"` is a pill that opens a larger panel (always with a search). `recent` lists up to 3 option ids shown as tiles above the groups while nothing is typed; `badge` draws a soft badge after the title. On a phone the sheet is full height with a close button.
@@ -1328,6 +1347,7 @@ To put a Switcher at the start of a page header, pass it as [EntityHeader](data-
 | `onValueChange` | `(value: string) => void` | — | |
 | `label` | `ReactNode` | — | what is switched: names the trigger, the panel and the list |
 | `variant` | `'default' \| 'expressive'` | `'default'` | tile trigger and menu, or pill and large panel |
+| `size` | `'default' \| 'compact'` | `'default'` | full trigger, or an icon-only round button for the app bar's `titleAfter` slot |
 | `searchable` | `boolean` | from 8 options (always, expressive) | the search field of the panel; `true` also replaces the menu with the panel |
 | `recent` | `string[]` | — | up to 3 option ids shown as tiles (expressive) |
 | `getHref` | `(item) => string \| undefined` | — | link mode; falls back to `item.href` |

package/docs/guides/app-shell.md

@@ -925,6 +925,7 @@ export function BoardShell({ items }: { items: MenuItem[] }) {
 | `titleAs` | `'h1'` … `'h6'` \| `'div'` | `'h1'` | The title's element: the screen's heading, `'h2'` under a heading of yours, `'div'` for none |
 | `inset` | `boolean` | `false` | Pads the content 1rem on each side. Off, it lines up with the app bar and the cards |
 | `width` | `'full'` \| `'form'` \| `'reading'` | `'full'` | Caps the main column: `'form'` 48rem, `'reading'` 72ch. The header card keeps the full width |
+| `notice` | `ReactNode` | — | A notice (an `Alert`, a `Banner`) above the main column and the side panel, as wide as the two together; it follows the header card and stacks first on a phone |
 | `aside` | `ReactNode` | — | A side panel: beside the content from `asideFrom`, stacked below it |
 | `asideLabel` / `asideLabelledBy` | `string` | — | The panel's accessible name (`aria-label`), or the id of a heading inside it (`aria-labelledby`). One of them is needed |
 | `asideSide` | `'start'` \| `'end'` | `'end'` | Which side of the content the panel sits on, wide |
@@ -973,6 +974,20 @@ decides the layout.
 </ActivityContent>
 ```
 
+```tsx
+import { ActivityContent, Alert } from '@nxgt/material/components';
+
+<ActivityContent
+  title="New visit"
+  width="form"
+  notice={<Alert variant="warning" title="Confirm your address" />}
+  aside={<DuplicateHints />}
+  asideLabel="Possible duplicates"
+>
+  <VisitForm />
+</ActivityContent>
+```
+
 - **Landmark.** The panel is an `<aside>`, a `complementary` landmark: name it
   with `asideLabel`, or with `asideLabelledBy` (the id of its heading). Its
   content is the panel's own; give it one `h2` when it has a heading.
@@ -987,6 +1002,13 @@ decides the layout.
   the main column and the pair stays start-aligned: at 1920px the panel is 1rem
   from the fields, not at the window's far edge. The header card above keeps
   the full width. `width` also works without a panel.
+- **A notice above both.** `notice` renders an `Alert` or a `Banner` right
+  under the header card, across the main column and the panel (with
+  `width="form"`, exactly their width), and it takes its own height in the
+  layout, so a page that centres its content needs no guessed offset. On a
+  phone it comes first, then the column, then the panel (`asideStack`
+  unchanged). Without `notice` the layout is unchanged. It works without a
+  panel too.
 - **The breakpoint is the window's.** `asideFrom` follows the viewport, not the
   content column, which the sidebar and the gutters narrow a little: pick `'lg'`
   for a panel on a smaller window, `'2xl'` to keep it stacked on all but the

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

@@ -48,6 +48,41 @@ only the surface and the content differ. Let the text and the meta wrap
 `renderTile` replaces `renderCard` there (`renderCard` is not read, and the
 reverse), and `item.Title` is rendered once per tile.
 
+### A compact record row in a tile
+
+For a list of records (a name, a note, a few tags), `item.Row` lays the tile
+out as the dense row of `ListTile` (`size="sm"` with `chips`), so you do not
+hand-lay two lines. The tile keeps its checkbox, its link and its states; the
+title is the one link and keeps the heading level you give it with `as`.
+
+```tsx
+<ServerTable
+  layout={{ phone: 'tiles', wide: 'table' }}
+  getRowHref={(person) => `/people/${person.id}`}
+  renderTile={(person, { Row }) => (
+    <Row
+      as="h2"
+      title={person.name}
+      subtitle={person.role}
+      chips={<Chip size="sm" label={person.status} />}
+      trailing={<span>{person.room}</span>}
+    />
+  )}
+  // ...
+/>;
+```
+
+`Row` takes `title`, `as` (`h2`, `h3`, `h4` or `span`, default `span`),
+`subtitle`, `chips`, `trailing`, `leading` and `chevron`. It replaces
+`Title`: render one or the other, once. The row measures its own width: the
+subtitle sits on the title's line from 28rem and the chips after the text from
+36rem, and below that they stack under the title. A one-line row is 36px tall
+under a mouse and 44px on a coarse pointer, against 72px for a free tile.
+`chips` and `trailing` are decoration, never buttons; a link or button row
+(`getRowHref` or `onRowClick`) gets a decorative chevron (`chevron={false}`
+removes it). `renderCard` is handed `Row` too: the same row inside the card's
+own padding and border, with no height of its own.
+
 ## One layout on a phone, another from 768px
 
 `layout` also takes `{ phone, wide }`: the layout below 768px and the one from
@@ -94,13 +129,14 @@ only the title is interactive.
 On a coarse pointer the title link also keeps a 44px box of its own, clear of
 the row-select checkbox, however short the title.
 
-`item` also carries `selected`, `locked` and `reason` (a row `enableRowSelection`
-leaves out, and `rowSelectionDisabledReason`'s answer).
+`item` also carries `Row` (the compact record row above), `selected`,
+`locked` and `reason` (a row `enableRowSelection` leaves out, and
+`rowSelectionDisabledReason`'s answer).
 
 The types, from `@nxgt/material/components`: `DataTableItem` (the `item`
 argument), `DataTableLayout` (`'table' | 'cards' | 'tiles'`),
-`DataTableResponsiveLayout` (`{ phone, wide }`), `DataTableLayoutProp` (what
-`layout` takes: either) and `DataTableItemTitleElement` (`Title`'s `as`).
+`DataTableItemRowProps` (`Row`'s props), `DataTableResponsiveLayout`
+(`{ phone, wide }`), `DataTableLayoutProp` (what `layout` takes: either) and `DataTableItemTitleElement` (`Title`'s `as`).
 
 ## In a `ServerTable`
 

package/docs/guides/charts.md

@@ -240,11 +240,39 @@ const toneOf = (point: ChartPoint) =>
 
 | Prop | Effect |
 | --- | --- |
-| `bands` | `{ from, to, label, tone? }[]`: a wash across the plot behind the lines, with its `label` inside it at the left. `from` and `to` may come in either order. |
-| `thresholds` | `{ value, label, tone?, dash? }[]`: a horizontal line behind the series with its `label` above it at the right end; dashed unless `dash: false`. |
+| `bands` | `{ from, to, label, tone? }[]`: a wash across the plot behind the lines, with its `label` inside it at the left. `from` and `to` may come in either order, and are a number, a row field or a function of the row (a stepped band; typed `ChartRowValue`). |
+| `thresholds` | `{ value, label, tone?, dash? }[]` (`value`: a number, a row field or a function of the row): a horizontal line behind the series with its `label` above it at the right end; dashed unless `dash: false`. |
 | `pointTone` | `(point: ChartPoint, series: ChartSeries) => Tone \| undefined`: the tone of one value. It is given the point `onPointClick` gets, so `point.index` is the row of the full `data` even when the chart is zoomed. |
 | `toneLabels` | `{ [tone]: word }`: the word of each tone, in your language and domain. Unset, the library's neutral word ("Error", translated by `material.charts.tone.*`); an app tone you declared falls back to its own name. |
 
+**A band or a line that changes along x.** When each row carries its own
+range (a normal range copied with a measurement, which changes with an age
+band or a catalogue edit), give `from` and `to` as the name of a row field, or
+as a function of the row; a threshold's `value` takes the same. The band then
+steps along x: each row owns the stretch up to the midpoint to its neighbours,
+rows with the same range merge into one block, and a row that gives no number
+leaves a gap. A number keeps the constant band, and so does a field or function
+that gives every row the same range.
+
+```tsx
+// rows: { day: 'Day 1', reading: 48, low: 40, high: 60, limit: 70 }
+<LineChart
+  title="Daily readings"
+  data={rows}
+  x="day"
+  series={[{ key: 'reading', label: 'Reading' }]}
+  bands={[{ from: 'low', to: 'high', label: 'Normal range', tone: 'success' }]}
+  thresholds={[{ value: (row) => row.limit as number, label: 'Upper limit', tone: 'error' }]}
+/>
+```
+
+The text names every range with the x labels it covers, in the summary and
+under "View data" (`Normal range: 40 to 60 (Day 1 to Day 6), 45 to 70 (Day 7 to
+Day 12)`), and the count of values outside a band uses each row's own range
+(a row with no range is not counted). The axis grows to the whole span, a
+label is drawn once, in the widest stretch (a threshold's at the end of the
+last one), and over a `zoom` window the blocks follow the window's rows.
+
 **The value axis holds them.** Unless `yAxis.min` and `yAxis.max` pin it, the
 axis grows to include every band end and threshold, so none is out of view.
 With a pinned axis a band is clipped to the plot and a threshold outside it is

package/docs/guides/data-grid.md

@@ -15,6 +15,7 @@ import { DataGrid, type DataGridHandle } from '@nxgt/material/components';
 ## Contents
 
 - [Columns and `meta`](#columns-and-meta)
+- [One column, several kinds of row](#one-column-several-kinds-of-row)
 - [Locked and read-only rows](#locked-and-read-only-rows)
 - [Saving](#saving)
 - [Versions and conflicts](#versions-and-conflicts)
@@ -42,9 +43,10 @@ Columns are DataTable's TanStack v9 column definitions. A column with no
 | `frozen` | Keeps a leading column at the inline start while the rest scrolls |
 | `lockPosition` | `'start'` or `'end'`: the column keeps its edge when columns are reordered ([columns](#columns-resize-hide-and-reorder)) |
 | `editor` | `'text'`, `'number'`, `'select'`, `'date'`, `'checkbox'`, or your own component ([custom editor](#a-custom-editor)) |
-| `number` | `{ min, max, decimals }` for the number editor; `min` and `max` may be functions of the row. A value outside them, or with too many decimals, is an error: it is never rounded or clamped |
+| `rowEditor(row)` | The built-in editor (`'text'`, `'number'`, `'select'`, `'date'`, `'checkbox'`) a row's cell has, for a column that mixes kinds ([one column, several kinds of row](#one-column-several-kinds-of-row)). It wins over `editor` |
+| `number` | `{ min, max, decimals }` for the number editor; `min`, `max` and `decimals` may be functions of the row. A value outside them, or with too many decimals, is an error: it is never rounded or clamped |
 | `codes` | Symbolic values the number editor also takes ("abs", "exempt"), with the label each language shows and the aliases it accepts |
-| `options` | The select editor's `{ value, label }` list. The cell shows and copies the label; a typed or pasted text matches a label or a value, in any case and without accents |
+| `options` | The select editor's `{ value, label }` list, or a function of the row returning it. The cell shows and copies the label; a typed or pasted text matches a label or a value, in any case and without accents |
 | `date` | `{ min, max }` as ISO dates (`'2026-09-01'`). The value is an ISO date, shown and read in the page's locale |
 | `parse(text, ctx)` | Text to value, replacing the editor's own: `{ value }` or `{ error }`. `ctx` has `lang`, `locale` and `row`. `{ value: null }` clears the cell, whatever the column's value type |
 | `format(value, ctx)` | Value to text, shown in the cell and in the editor |
@@ -129,6 +131,44 @@ answered by then refuses the paste with the same message. Set `checkTimeout` to
 <DataGrid checkTimeout={5000} /* … */ />
 ```
 
+## One column, several kinds of row
+
+A result-entry sheet has one « Result » column whose rows differ: a quantity
+(a number, held to that row's own min, max and decimals), a coded value (a
+pick among that row's own options) and a free text. Give the column
+`rowEditor`, and let `number` and `options` read the row:
+
+```tsx
+type Result = {
+  id: string;
+  kind: 'quantity' | 'coded' | 'text';
+  value: number | string | null;
+  min?: number;
+  max?: number;
+  decimals?: number;
+  options?: { value: string; label: string }[];
+};
+
+helper.accessor('value', {
+  id: 'result',
+  header: 'Result',
+  meta: {
+    rowEditor: (row) =>
+      row.kind === 'quantity' ? 'number' : row.kind === 'coded' ? 'select' : 'text',
+    number: { min: (r) => r.min ?? 0, max: (r) => r.max ?? 0, decimals: (r) => r.decimals ?? 0 },
+    options: (row) => row.options ?? [],
+  },
+});
+```
+
+Everything reads the column for the row: typing and the editors, a pasted or
+filled text, Delete, undo, copy, the phone's row panel and the conflict
+panel. `rowEditor` returns a built-in name only; a custom component stays
+`editor`'s. The column's `className`, `format`, `parse`, `validate` and
+`schema` stay column-wide. A column with `rowEditor` copies on fill and never
+continues a series, and its totals use the `decimals` given as a number. A row
+that must not be edited at all is `readOnly` or `locked` as usual.
+
 ## Locked and read-only rows
 
 `rowReadOnly(row)` and `rowLocked(row)` return `false`, `true` or

package/docs/guides/forms.md

@@ -783,6 +783,41 @@ form.setFocus('email'); // or without an error
 - If focus does not move, see
   [`setError(…, { shouldFocus: true })` does nothing](../troubleshooting.md#seterror--shouldfocus-true--or-a-failed-submit-does-not-focus-the-field).
 
+## A form that is quick to fill
+
+`useFastForm` and `useFocusOnRefusal` (`@nxgt/material/components`) are the
+two habits of a record form, in one place. `useFastForm(props, first, active?)`
+is `useForm` with `mode: 'onTouched'` (an error shows once the user leaves the
+field, then follows each change; a `mode` in `props` wins) that also focuses
+the `first` field when the form opens, so typing starts at once. It waits a
+frame and retries for about half a second, so a dialog's focus trap has
+settled; it stops as soon as the focus moved. `active` (default `true`) is for
+a hook that stays mounted while its dialog is closed: it focuses each time
+`active` turns true.
+
+`useFocusOnRefusal<T>(message, busy)` returns a ref for the submit control: once
+a refusal shows (`message` set) and nothing is running (`busy` false), the
+control takes the focus back, so it never falls to the page after the button
+was disabled during the request.
+
+```tsx
+import { Button, TextFormField, useFastForm, useFocusOnRefusal } from '@nxgt/material/components';
+
+export function SignUp({ refusal, busy, save }: Props) {
+  const form = useFastForm<{ email: string }>({ defaultValues: { email: '' } }, 'email');
+  const submit = useFocusOnRefusal<HTMLButtonElement>(refusal, busy);
+  return (
+    <form onSubmit={form.handleSubmit(save)}>
+      <TextFormField control={form.control} name="email" label="Email" />
+      <Button ref={submit} type="submit" loading={busy}>Sign up</Button>
+    </form>
+  );
+}
+```
+
+Storybook: `Guides/Forms/useFastForm`. If the focus does not move, see
+[`useFastForm` does not focus the first field](../troubleshooting.md#usefastform-does-not-focus-the-first-field).
+
 ## Server errors
 
 Map an API's field errors onto the form with `setError`, and put anything that

package/docs/guides/helpers.md

@@ -265,7 +265,7 @@ flag. Storybook: `Guides/Hooks/useSubmitOnce`.
 | `formatMessage(message, language, values?, { onError }?)` | Formats one ICU message (`{name}`, plurals, selects) in any BCP 47 `language` with the translator's engine, for a message that is not in a bundle (a server-side catalogue). Cached per message; one that does not format is logged and returned unformatted, or passed to `onError` as a `FormatMessageError` (reason, key, source) without logging. |
 | `createTypedTranslation(translate)` | Turns a translator into a typed `useTranslation()` hook. |
 | `translate`, `useMaterialTranslation()` | Translator / hook bound to the package's own `material.*` keys. `useMaterialTranslation().t(key, fallback)` returns `fallback` without a provider. |
-| `translateMaterial(language, key, fallback, values?)` | The same as `useMaterialTranslation().t`, with the language passed as a value: no provider, no hook. For a PDF `footer` function or a server. `'fr-CA'` reads `fr`; an unknown language formats `fallback`. |
+| `translateMaterial(language, key, fallback, values?, resources?)` | The same as `useMaterialTranslation().t`, with the language passed as a value: no provider, no hook. `resources` is your merged bundle (stable object), read before the base one. For a PDF `footer` function or a server. `'fr-CA'` reads `fr`; an unknown language formats `fallback`. |
 | `getLanguage()` | Language read from `localStorage`, else `FALLBACK_LANGUAGE`. |
 | `LANGUAGE_KEY`, `FALLBACK_LANGUAGE`, `SUPPORTED_LANGUAGES` | Storage key (`'language'`), fallback (`'en'`) and supported languages (`en`, `fr`). |
 

package/docs/guides/i18n.md

@@ -63,6 +63,7 @@ function translateMaterial(
   key: MaterialLocaleKey,
   fallback: string,
   values?: TranslationContext,
+  resources?: ResourceBundle, // your merged bundle, a stable object (module scope)
 ): string;
 ```
 
@@ -189,6 +190,7 @@ if (failure) {
 | `initialLanguage` | `Language` | — | Used as-is for the first render when supported, and `localStorage` is not read. Set it in SSR. See [below](#server-rendering) |
 | `storageKey` | `string` | `'language'` | `localStorage` key the choice is read from and written to |
 | `supportedLanguages` | `Language[]` | `['en', 'fr']` | What `changeLanguage` accepts and `LanguageSwitcher` lists |
+| `resources` | `ResourceBundle` | — | Your `mergeResources(...)` result: the components read their `material.*` words from it before the base bundle. Pass a stable object (module scope) |
 | `onLanguageChange` | `(language) => void` | — | Called after a successful change: save it to a cookie, a profile, analytics |
 
 `changeLanguage` with an unsupported value logs
@@ -208,7 +210,8 @@ const context = useOptionalI18nContext(); // null outside the provider
 third language is not in the type today, so adding one to
 `supportedLanguages` takes a cast. The runtime accepts it: your translator
 uses your strings for it, and the components fall back to their English copy,
-formatted.
+formatted. A third language you define under `material.*` and give through
+`resources` now reaches the components.
 
 ```tsx
 const LANGUAGES = ['en', 'fr', 'de'] as Language[];
@@ -498,8 +501,8 @@ material.emoji.groups.flags;       // "Flags" / "Drapeaux"
 
 A group your `EmojiItem`s name that is not in this list (`hand_signs`) reads
 as its words in English (`Hand signs`). As for every `material.*` key above,
-the components read their own bundle: your own translator sees a key you add,
-the tab does not.
+your own translator sees a key you add; the components see it too once you hand
+them the merged resources (see "Overriding a component's words" below).
 
 ```tsx
 // Under <I18nProvider defaultLanguage="fr">
@@ -509,11 +512,34 @@ the tab does not.
 <Spinner variant="4" />     // role="img" aria-label="Chargement..."
 ```
 
-That override is visible only through **your** translator. The components
-translate through the package's own bundle, so defining
-`material.command.title` in your resources changes what
-`t('material.command.title')` returns in your code, but not the title
-`CommandDialog` renders.
+### Overriding a component's words
+
+Give the provider the merged resources and every component translates through
+them, so an override under `material.*` changes what it renders:
+
+```tsx
+import { mergeResources, resources as materialResources } from '@nxgt/material/i18n';
+
+const resources = mergeResources(materialResources, {
+  en: { material: { 'recovery-codes-status': { title: 'Backup codes' } } },
+});
+
+<I18nProvider defaultLanguage="en" resources={resources}>
+  <RecoveryCodesStatus remaining={3} onRegenerate={regenerate} /> {/* title: "Backup codes" */}
+</I18nProvider>
+```
+
+Without `resources`, the components read the package's own bundle: an override
+is visible only through **your** translator, and defining `material.command.title`
+does not change the title `CommandDialog` renders. Pass a stable object
+(module scope), not one built in a render. A component's `labels` prop still
+wins over both. Outside a component, `translateMaterial` takes the merged
+resources as a fifth argument and `zodLocaleError` takes `translate`. Toasts
+follow `resources` too: `toast()`, its presets and the close label run outside
+React, so the mounted `I18nProvider` hands them its `resources` and language
+(with several providers, the last one mounted wins). They follow that
+provider's language as well as its resources, which can differ from the
+language of an inner subtree.
 
 Each time `mergeResources` runs outside production, overlapping leaves are
 reported, one line per language:

package/docs/guides/two-factor.md

@@ -62,7 +62,8 @@ in `@nxgt/material-core/two-factor`.
 What stays in the app: every request, the mapping of a server error to the
 props above, where the challenge is kept, the replay of the action a step-up
 unblocked, the leave guard around the new recovery codes, and all wording
-(`labels`, or your translations under `material.*`).
+(`labels`, or your translations under `material.*`, given to
+`I18nProvider` as `resources`, see [i18n](i18n.md#overriding-a-components-words)).
 
 ## On a phone and for assistive technology