@nxgt/material 3.52.0 → 3.53.0

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

@@ -1,4 +1,4 @@
-import { r as e } from "./i18n-provider-BFNrM0Qu.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-ByM3gD9R.js → use-material-translation-nNF8fUXz.js}

@@ -1,5 +1,5 @@
-import { r as e } from "./i18n-provider-BFNrM0Qu.js";
-import { t } from "./translate-material-BPl8TQLg.js";
+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() {

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-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/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/i18n.md

@@ -534,8 +534,12 @@ is visible only through **your** translator, and defining `material.command.titl
 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`; the
-toast presets and the toast close label still read the package's bundle.
+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: