@nxgt/material 3.68.0 → 3.71.0

package/docs/components/rich-widgets.md

@@ -83,8 +83,8 @@ function Conversation({ messages }: { messages: Message[] }) {
 Parts: `ChatInbox` (`list`, `thread`, `listHeader`, `pane`), `ChatConversationItem`,
 `ChatThread`, `ChatThreadHeader`, `ChatMessageList`, `ChatMessage`,
 `ChatMessageSeparator`, `ChatReplyQuote`, `ChatReactionGroup`, `ChatComposer`,
-`ChatComposerAttachments`, `ChatComposerAttachmentChip`, `ChatMarkdown`,
-`ChatTypingIndicator`, `ChatWidget`, `chatGroupPosition`, `ChatLayoutContext`,
+`ChatComposerAttachments`, `ChatComposerAttachmentChip`, `ChatMarkdown`, `Markdown` documents `math`, `mermaid` and the untrusted-input guarantees (data-display.md#markdown).
+`ChatTypingIndicator`, `ChatActionProposal`, `ChatToolActivity`, `ChatWidget`, `chatGroupPosition`, `ChatLayoutContext`,
 `useChatComposerAttachments`. Built on [TypingIndicator](feedback-and-status.md#typingindicator),
 [DaySeparator](data-display.md#dayseparator) and
 [ScrollToLatestButton](buttons-and-actions.md#scrolltolatestbutton).
@@ -94,6 +94,30 @@ Parts: `ChatInbox` (`list`, `thread`, `listHeader`, `pane`), `ChatConversationIt
 [<img src="../previews/rich-widgets-chat-composer.webp" height="96" alt="ChatComposer">](#chat-kit)
 [<img src="../previews/rich-widgets-chat-widget.webp" height="96" alt="ChatWidget">](#chat-kit)
 [<img src="../previews/rich-widgets-chat-advanced.webp" height="96" alt="ChatComposer with mentions">](#chat-kit)
+[<img src="../previews/rich-widgets-chat-action-proposal.webp" height="96" alt="ChatActionProposal">](#chat-kit)
+
+An assistant's proposed action and its tool steps, inside a list:
+
+```tsx
+import {
+	ChatActionProposal,
+	ChatMessageList,
+	ChatToolActivity,
+} from '@nxgt/material/components';
+
+<ChatMessageList>
+	<ChatToolActivity name="find_absences" state="ok" />
+	<ChatActionProposal
+		title="Mark 12 absences as justified"
+		summary="Class 5B, 3 to 7 November."
+		deadline="2026-11-02T16:00:00Z"
+		status={status} // 'pending' until answered
+		busy={sending}
+		onConfirm={confirm}
+		onReject={reject}
+	/>
+</ChatMessageList>;
+```
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
@@ -105,8 +129,16 @@ Parts: `ChatInbox` (`list`, `thread`, `listHeader`, `pane`), `ChatConversationIt
 | `ChatMessage` `onReply` / `onReact` / `onDelete` / `menuItems` | callbacks / `ReactNode` | — | the toolbar shown on hover or focus (a tap on touch): react, reply, copy, and a "more" menu |
 | `ChatMessage` `reactions` / `onReactionToggle` | `ChatReaction[]` | — | the reaction pills under the bubble |
 | `ChatMessage` `isStreaming` / `copyable` | `boolean` | `false` / `true` | streaming caret; Copy in the toolbar |
+| `ChatActionProposal` `title` / `summary` / `toolLabel` / `children` | `ReactNode` | — | a card for an action the assistant proposes: what, its effect, the tool behind it (a slot) and extra detail |
+| `ChatActionProposal` `status` | `'pending' \| 'running' \| 'confirmed' \| 'failed' \| 'rejected' \| 'expired'` | `'pending'` | a toned badge with its icon and words (colour is never the only signal); only `pending` shows the buttons; leaving `pending` moves the focus to the status |
+| `ChatActionProposal` `onConfirm` / `onReject` | `() => void` | — | the Confirm (filled) and Reject (tonal) buttons; `confirmLabel` / `rejectLabel` reword them; `actions` replaces both |
+| `ChatActionProposal` `busy` / `disabled` | `boolean` | `false` | an answer is being sent (both disabled, Confirm spins) / a read-only viewer |
+| `ChatActionProposal` `deadline` | `Date \| string \| number` | — | "Respond by …" in a `<time>`, in the active language; `expired` says "Expired on" |
+| `ChatActionProposal` `failureCode` / `failureMessage` | `string` / `ReactNode` | — | a `failed` card's reason, in an `alert`, with the code |
+| `ChatToolActivity` `name` / `state` / `detail` | `ReactNode` / `'running' \| 'ok' \| 'failed'` / `ReactNode` | — / `'running'` | one compact row for a tool step in a `ChatMessageList`: the name in mono, Running (spinner), Done or Failed |
 | `ChatThread` / `ChatMessageList` `layout` | `'bubbles' \| 'flat'` | `'bubbles'` | a messenger's bubbles, or a team chat's rows (name and time over each run) |
 | `ChatThread` / `ChatMessageList` `density` | `'comfortable' \| 'compact'` | `'comfortable'` | tighter bubbles, smaller avatars |
+| `ChatMessageList` `viewportProps` | `ComponentProps` of the viewport | `{ tabIndex: 0 }` | attributes of the scrolling element; it is a tab stop so the keyboard can scroll the transcript (`tabIndex: -1` opts out) |
 | `ChatThread` `surface` | `'plain' \| 'card'` | `'plain'` | fills its parent, or draws a rounded bordered card |
 | `ChatThread` `composerProps` | `ChatComposerProps` | — | renders a `ChatComposer` under the list |
 | `ChatMessageList` `isTyping` / `typingAvatar` | `boolean` / `ReactNode` | `false` | a typing bubble at the end of the list |
@@ -117,6 +149,7 @@ Parts: `ChatInbox` (`list`, `thread`, `listHeader`, `pane`), `ChatConversationIt
 | `ChatComposer` `sendOnEnter` | `boolean` | `true` | Enter sends and Shift+Enter breaks the line; `false`: Ctrl/⌘+Enter sends. Never while an IME composes |
 | `ChatComposer` `emojis` / `mentions` | `EmojiItem[]` / `MentionItem[]` | — | enables the emoji picker and the `@` list |
 | `ChatThreadHeader` | `title`, `subtitle`, `avatarSrc`, `status`, `actions`, `onBack` | — | the title bar; inside a `ChatInbox` it carries the back button on a narrow screen |
+| `ChatConversationItem` `title` / `titleText` | `ReactNode` / `string` | — | the clipped title carries its full text in a `title` attribute when it is a string; `titleText` gives it when `title` is a node |
 | `ChatConversationItem` `status` / `isTyping` | `StatusTone` / `boolean` | — | presence dot; "Typing…" instead of the preview |
 | `ChatInbox` `pane` / `defaultPane` | `'list' \| 'thread'` | `'list'` | which pane shows below the `@md` container width |
 | `ChatWidget` `open` / `defaultOpen` / `onOpenChange` | `boolean` | `false` | the floating launcher's panel (full screen below `sm`); `unreadCount` on the launcher, `side`, `strategy` |
@@ -2457,9 +2490,10 @@ French bundle — see [i18n](../guides/i18n.md).
 | `QuestionCard` `renderCode` | `(field: QuestionCodeField) => ReactNode` | — | the code field of a `code` question; `field` is `{ value, onChange, label, labelledBy, describedBy, language, maxLength, readOnly, disabled }`. Keeps Monaco out of the card's bundle |
 | `Question` `description` | `string` | — | `open`, `code`: a persistent helper line under the answer field ("A person will mark this answer"), linked to it by `aria-describedby` and passed to `renderCode` as `field.describedBy`; always shown, unlike `hint` (a reveal button). Its id is `${promptId}-description` |
 | `QuestionCard` `promptId` | `string` | generated | the id of the prompt text: point a wrapping section's `aria-labelledby` at it (and `aria-describedby` at `${promptId}-description`) |
+| `QuestionCard` `preview` | `boolean` | `false` | an author's preview, `<QuestionCard question={q} preview />`: forces `revealed` and `readOnly`, drops `onValueChange`, and shows the marks (the `question.correct` options marked, the expected text or number filled in) and the `explanation`, with no verdict banner. `verdict` and `showFeedback` are always ignored in a preview; `value` is ignored when the question has a `correct` — an `open` or `code` question has none, so pass its reference answer as `value`. Not for a learner's attempt |
 | `QuestionCard` `readOnly` / `busy` | `boolean` | `false` | `readOnly`: an answer already submitted, shown without the revealed marks; `busy`: read-only and `aria-busy` while it is saved; every kind honours both |
 | new strings | `material.education.kind-open`, `kind-code`, `code-placeholder` | — | English fallbacks and a French bundle |
-| `QuestionCard` `variant` / `density` / `showShortcuts` / `number` / `showFeedback` | — | `'card'`, `'comfortable'`, `false`, —, `true` | framed or plain, spacing, key badges, "Question 2", the verdict banner |
+| `QuestionCard` `variant` / `density` / `showShortcuts` / `number` / `showFeedback` | — | `'card'`, `'comfortable'`, `false`, —, `true` | framed or plain, spacing, key badges, "Question 2", the verdict banner (for a card with marks and no banner, use `preview`) |
 
 An open answer and a code answer, with the code editor from its own subpath
 (it is client-only, so load it lazily in an SSR app):

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

@@ -417,7 +417,7 @@ disabled with the field; Backspace in the empty input removes the last one.
 | `getOptionValue`, `getOptionLabel` | `(option: T) => string` | `.value`, `.label` | for other option shapes |
 | `getOptionLeading` | `(option: T) => ReactNode` | — | an avatar (or a flag) before the label, in the list and in the chip; `renderOption` replaces the whole row |
 | `filter` | `'accent-insensitive' \| 'none' \| (option: T, query: string) => boolean` | `'accent-insensitive'`, `'none'` with `onSearch` | how the list is filtered as the user types: label or value, ignoring case and accents (`e` finds "École") in the provider's language; `'none'` shows `options` as given; a function gets the trimmed query, never an empty one |
-| `freeSolo` | `boolean` | — | accept a typed value that is not an option |
+| `freeSolo` | `boolean` | — | accept a typed value that is not an option; Enter adds it |
 | `onSearch` | `(query: string, { signal }: { signal: AbortSignal }) => Promise<T[]>` | — | server search: called once typing pauses; its results become the list. Each search aborts the previous one, and a response that lands after a newer one is dropped |
 | `onSearchError` | `(error: unknown) => void` | — | `onSearch` rejected (an abort is not a rejection) |
 | `minQueryLength` | `number` | `1` | `onSearch` waits for this many characters; below it the list says "Type at least N characters to search." |
@@ -433,6 +433,12 @@ disabled with the field; Backspace in the empty input removes the last one.
 | `disabled` | `boolean` | — | disables the input and each chip's remove button |
 | `error` | `boolean` | — | error border on the chips box, error helper text, `aria-invalid` on the input |
 
+Enter in a form: it acts on the list and does not submit the form while it has
+something to do (WAI-ARIA combobox practice). It picks the highlighted option;
+with `freeSolo` and no option highlighted it adds the typed text; with the list
+open it is only default-prevented. On a closed list with nothing typed it
+submits, as a plain input does.
+
 An avatar in the rows and the chips:
 `getOptionLeading={(person) => <Avatar src={person.photo} alt="" />}`; see
 [the field look](../guides/field-look-2-x.md#autocomplete-and-the-chips-box).
@@ -471,8 +477,9 @@ text, as a `Select` shows it, and keeps the search:
   gets the label back on leave: the value can only be replaced by another pick.
 - The option's `getOptionLeading` (or `renderSelectedLeading`) avatar shows
   before the text while it is picked.
-- `freeSolo` still adds through its "Add" button; text left in the input and
-  not added is dropped on leave, as any other typed text.
+- `freeSolo` adds through its "Add" button, or with Enter when no option is
+  highlighted; text left in the input and not added is dropped on leave, as
+  any other typed text.
 - Keep the selected option in `options` (as with `onSearch` and chips): a value
   with no matching option has no label, so the input stays empty.
 - The input is the combobox: `aria-expanded` follows the list,

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

@@ -146,7 +146,9 @@ sort control writes it), the cursor paging in the footer, `bulkActions` and the
 selection kept across pages, the empty and error pages. An empty page has no
 list bar over it, and the focus a bulk action's `clear()` hands back goes to the
 list. The sort control names its columns as in a `DataTable`: set `meta.label`
-on a column whose header is a render function (see [Sort](#sort)).
+on a column whose header is a render function (see [Sort](#sort)). Without
+`sorting`, no column is sortable (the server sorts, so pass `sorting` to let people
+sort), and the phone list bar shows only for selection.
 
 ```tsx
 import { ServerTable } from '@nxgt/material/components';
@@ -341,7 +343,7 @@ the `Guides/Recipes/Status board` story, and the Claude Code plugin's
 
 ## Troubleshooting
 
-**The sort control is missing, or an option reads like the column id.** The control needs a column that can be sorted (an accessor, `enableSorting` not `false`); an option is the column's `meta.label`, else a string `header`. Set `meta.label`.
+**The sort control is missing, or an option reads like the column id.** The control needs a column that can be sorted (an accessor, `enableSorting` not `false`); an option is the column's `meta.label`, else a string `header`. Set `meta.label`. On a `ServerTable` the control is also missing when `sorting` is not passed: no column is sortable without it. Pass `sorting` (the server sorts).
 
 **The phone shows the table for a moment.** `{ phone, wide }` renders `wide` on
 the server and for the first client render, so that hydration matches; a phone

package/docs/guides/csp.md

@@ -28,7 +28,7 @@ Content-Security-Policy:
 | `style-src-elem 'self' 'nonce-X'` | Your stylesheet and the `<style>` elements that carry the nonce. No component needs `'unsafe-inline'` here, apart from the [known gaps](#known-gaps): see [the `<style>` elements the components inject](#style-elements-the-components-inject) |
 | `style-src-attr 'unsafe-inline'` | The `style="…"` attributes in the server-rendered HTML and those set through `setAttribute('style', …)`. CSP blocks only these two; `el.style.x = …` and `style.setProperty` are not blocked. An attribute cannot carry a nonce, so this is the only way to allow it. It does not allow `<style>` elements or scripts |
 | `font-src 'self'` | The library ships no web font (host Inter yourself: [Inter / the sans font](#inter--the-sans-font)), and KaTeX's fonts are files, never `data:` URIs: see [KaTeX fonts](#katex-fonts) for the one Vite setting the Tailwind route needs |
-| `img-src 'self' data: blob:` | `data:` for the cropper's output, a captured `Camera` photo, a `Markdown` mermaid diagram and the PDF reader's annotation icons (SVG `data:` images; the icons the components draw are inline `<svg>` elements and need none); `blob:` for previews of a file the user picked. Drop what you do not use |
+| `img-src 'self' data: blob:` | `data:` for the cropper's output, a captured `Camera` photo, and the PDF reader's annotation icons (SVG `data:` images; the icons the components draw are inline `<svg>` elements and need none); `blob:` for previews of a file the user picked and for a `Markdown` mermaid diagram (an SVG image from a `blob:` URL). Drop what you do not use |
 | `worker-src 'self'` | The pdf.js worker of `PdfReader`: the build ships it as a file, `dist/pdf.worker.min.mjs`, referenced relative to the module that loads it, so `'self'` is enough with no setting and no `data:`. `configurePdfReader({ workerSrc })` overrides it ([PDF reader guide](pdf-reader.md#content-security-policy)). Monaco: see below |
 | `connect-src 'self'` | `PdfReader` fetches the PDF from its `url` and its pdf.js assets from `assetsUrl`: add those origins when they are not yours |
 
@@ -38,7 +38,7 @@ Components outside this table need nothing more. Measured per component:
 | --- | --- | --- |
 | `PdfReader` | `worker-src 'self'` (the worker is a file of the package), `connect-src` for the PDF's and the assets' origins, and `script-src 'wasm-unsafe-eval'` for the JPEG 2000 and ICC WebAssembly decoders (without it: a JavaScript fallback for JPEG 2000, device colours for ICC profiles) | worker checked in the same Playwright run (Vite production build under `worker-src 'self'`), the rest read from pdf.js's code: [PDF reader guide](pdf-reader.md#content-security-policy) |
 | `CodeEditor`, `CodeDiff` (Monaco) | `@monaco-editor/react` loads Monaco from `https://cdn.jsdelivr.net/npm/monaco-editor@…/min/vs` by default: that host in `style-src-elem` (Monaco's CSS) and `font-src` (its icon font), plus `worker-src blob:` | not yet verified in a browser. Safe default: allow `https://cdn.jsdelivr.net` in `script-src`, `style-src-elem` and `font-src`, and `worker-src blob:`; or stay on `'self'` by [serving Monaco yourself](#monaco-on-self) |
-| `Markdown` with a `mermaid` block | mermaid is imported lazily and runs with `securityLevel: 'strict'` | whether mermaid needs `'unsafe-eval'` is not yet verified. Safe default: keep `'unsafe-eval'` out and report any violation you see; its SVG carries a `<style>` element, see [gaps](#known-gaps) |
+| `Markdown` (maths, mermaid, code) | nothing beyond the policy above, in a client render | checked in Chromium under that policy with `style-src-attr 'none'`, no `img-src data:` and no `'unsafe-eval'`: [Markdown under a strict CSP](#markdown-katex-mermaid-and-code-under-a-strict-csp) |
 | `RichTextViewer` (`@nxgt/material/editor/viewer`) | none, but it emits `style` attributes: a text colour, a highlight, a text alignment or a table cell's background in the saved document becomes an inline `style` (only allow-listed properties with plain values survive), so a page that shows such a document needs `style-src-attr 'unsafe-inline'`. A document with none sends no style | measured by reading the renderers; a strict `style-src-attr 'none'` page shows the document without those colours |
 | `Camera` | none: `getUserMedia` is not governed by CSP; the captured photo is a `data:` image | `media-src` for the live preview is not yet verified. Safe default: `media-src 'self' blob:` (a `srcObject` stream usually needs nothing) |
 | `MediaPlayer` with `hlsStreaming()` | `connect-src` and `media-src blob:` for the stream; `worker-src blob:` only with `config: { enableWorker: true }` (the adapter defaults to no worker) | see the [streaming guide](media-streaming.md#content-security-policy) |
@@ -201,8 +201,8 @@ instead.
 `style-src-elem 'self' 'nonce-X'` is enough for every component below: your
 stylesheet carries the CSS the dependencies used to inject, and under a
 `NonceProvider` the few `<style>` elements left carry the nonce. No route
-needs `'unsafe-inline'` in `style-src-elem` for them; mermaid and pdf.js's
-font fallback are the [known gaps](#known-gaps).
+needs `'unsafe-inline'` in `style-src-elem` for them; the mindmap diagrams of
+mermaid and pdf.js's font fallback are the [known gaps](#known-gaps).
 
 | Component | What it needs | How |
 | --- | --- | --- |
@@ -261,12 +261,50 @@ when the page carries it nowhere. `setCspNonce` does nothing on a server (no
 `document`), so a request's nonce never lands in a module global there: see
 [SSR](#ssr).
 
+### Markdown (KaTeX, mermaid and code) under a strict CSP
+
+The full `Markdown` (and `ChatMarkdown`) needs no relaxed directive: no
+`'unsafe-inline'`, no `'unsafe-eval'`, no `style-src-attr`, no `img-src data:`.
+Only `img-src blob:` (already in the policy above) for the diagrams. The
+`Data display/Markdown > StrictCsp` story plays maths, two flowcharts (one with
+an `<img>` in a label, removed before the render, since mermaid would load it in the page) and a code block in a document served
+`script-src 'self' 'nonce-X'` (no `'unsafe-eval'`),
+`style-src-elem 'self' 'nonce-X'`, `style-src-attr 'none'`,
+`img-src 'self' blob:` and `font-src 'self'`, and expects not one violation.
+What the app does: wrap the app in [`NonceProvider`](#nonceprovider) (or let
+the page carry the nonce in its meta tag).
+
+- **Code blocks**: the scheme's colours are classes of the stylesheet
+  (`data-scheme`), and `maxHeight` is a custom property written through the
+  CSSOM in a layout effect (a server-rendered block is full height until
+  hydration).
+- **KaTeX**: on a client render React writes its styles through the CSSOM.
+  Its fonts are files ([KaTeX fonts](#katex-fonts)).
+- **Mermaid**: the diagram stays an image, now from a `blob:` URL (revoked when
+  the diagram goes), so the SVG's own `<style>` and `style` attributes live in
+  the image and the page needs neither `data:` nor `style-src-attr` for them.
+  While a diagram renders, mermaid builds it in a temporary element of the
+  page and sanitises it with DOMPurify, which a strict policy reports. For
+  that render only, and only for the elements of that diagram, a short-lived
+  scope gives mermaid's `<style>` the nonce, writes its `style` attributes
+  through the CSSOM and parks the `style` attributes of the string DOMPurify
+  parses (patches of `Document.prototype.createElement`,
+  `Element.prototype.setAttribute` and `DOMParser.prototype.parseFromString`;
+  each is a pass-through once the last render ends and is restored only if
+  no other script patched it since). Unrelated calls, such as an editor
+  parsing HTML, are left alone.
+- **Left**: a page whose HTML the server renders with math carries KaTeX's
+  `style="…"` attributes in the markup, which `style-src-attr 'none'` blocks
+  (the formula loses its spacing until `style-src-attr 'unsafe-inline'`, or a
+  client-only render of the `Markdown`). Mermaid's mindmap and architecture
+  diagrams add a `<style>` to `<head>` ([known gaps](#known-gaps)).
+
 ### Known gaps
 
 Not fixable by configuration yet, and still reported by a strict policy:
 
-- the `<style>` element inside mermaid's SVG, and the one cytoscape adds to
-  `<head>` for mermaid's mindmap and architecture diagrams;
+- the `<style>` element cytoscape adds to `<head>` for mermaid's mindmap and
+  architecture diagrams (flowcharts, sequences and the like add none);
 - the font fallback of pdf.js, when a PDF font is not embedded;
 - this repository's Storybook, or an app that imports react-use's barrel
   itself on a dev server: react-use served as one module, whose `useCss`

package/docs/guides/forms.md

@@ -115,7 +115,7 @@ export function PlanForm() {
 | The field | Touched when |
 | --- | --- |
 | one input (`TextFormField`, `EmailFormField`, `TextareaFormField`, `SwitchFormField`, `CheckboxFormField`, …) | its input loses focus, as a native `blur` |
-| several controls (`OpeningHoursFormField`, inline by default: focus leaves the week editor and its phone sheet; `ContactsFormField`, inline by default: focus leaves the rows and the phone sheet; `AttributesFormField`, inline by default: focus leaves the rows, their open fields and the phone sheet; `PasswordFormField` and its eye button, `NumberFormField` and its steppers, `PhoneFormField`, `OtpFormField`, `SliderFormField` with two thumbs, `DurationFormField`, `RatingFormField`, `RadioGroupFormField`, `CheckboxGroupFormField`, `ChipGroupFormField`, `ChoiceCardGroupFormField`, `SortableListFormField`, `TransferListFormField`, `InlineEditFormField`, `LocalizedTextFormField`, `AttributeValuesFormFieldSet`, …) | focus leaves all of them; moving between them is not leaving |
+| several controls (`OpeningHoursFormField`, inline by default: focus leaves the week editor and its phone sheet; `ContactsFormField`, inline by default: focus leaves the rows and the phone sheet; `AttributesFormField`, inline by default: focus leaves the rows, their open fields and the phone sheet; `PasswordFormField` and its eye button, `NumberFormField` and its steppers, `QuantityFormField`, `PhoneFormField`, `OtpFormField`, `SliderFormField` with two thumbs, `DurationFormField`, `RatingFormField`, `RadioGroupFormField`, `CheckboxGroupFormField`, `ChipGroupFormField`, `ChoiceCardGroupFormField`, `SortableListFormField`, `TransferListFormField`, `InlineEditFormField`, `LocalizedTextFormField`, `AttributeValuesFormFieldSet`, …) | focus leaves all of them; moving between them is not leaving |
 | a picker (`SelectFormField`, `ComboboxFormField`, `AutocompleteFormField`, `TreeSelectFormField`, `CountryFormField`, `TimezoneFormField`, `ColorFormField`, `DateFormField`, `DateRangeFormField`, `TimeFormField`, …) | focus leaves the trigger **and** the popover it opened. Opening the popover, or picking in it, is not leaving; closing it hands focus back to the trigger, and the next Tab or click elsewhere is. A typed `DateFormField`, `DateRangeFormField` or `TimeFormField` is one trigger: moving between its segments (both ends of a range) and its buttons is not leaving |
 | a dialog editor (`PostalAddressFormField`, `ContactsFormField` with `editing="dialog"`, `OpeningHoursFormField` with `editing="dialog"`, `AttributesFormField` with `editing="dialog"`, and `LocationFormField` from `@nxgt/material/map`) | focus leaves its buttons and the dialog they open. Closing the dialog hands focus back to the button that opened it |
 | an upload (`UploadFormField`, `NetworkUploadFormField`, `S3UploadFormField`, `ImageFormField`, `ImageS3FormField`, `FileListFormField`, `FileListS3FormField`) | focus leaves the drop zone and its buttons. Choosing a file in the browser's own dialog is not leaving |
@@ -485,8 +485,9 @@ or fails validation.
 | `PasswordField` · `PasswordFormField` | `string` | `''` |
 | `NumberField` · `NumberFormField` | `number \| null`. `null` when cleared; clamped to `min` / `max` on blur | `null` |
 | `PercentField` · `PercentFormField` | `number \| null`, `min` 0, `max` 100, `step` 1 by default | `null` |
+| `QuantityField` · `QuantityFormField` | `{ value: number \| null, unit: string }`. An error on the field, `.value` or `.unit` shows as one message under the pair | `{ value: null, unit: '' }` |
 | `CurrencyField` · `CurrencyFormField` | `number \| null`, the amount only, not rounded. `currency` (default `'EUR'`) and `fractionDigits` (the currency's own decimals by default) are display | `null` |
-| `PhoneField` · `PhoneFormField` | E.164 `string` (`'+33612345678'`), or `null` while the number is not yet a possible one. `defaultCountry` is `'FR'` | `null` |
+| `PhoneField` · `PhoneFormField` | E.164 `string` (`'+33612345678'`), or `null` when empty. `PhoneFormField` reports a non-empty number that is not yet possible as the field error `material.phone-field.incomplete`; `PhoneField` signals it with `onValidityChange`. `defaultCountry` is `'FR'` | `null` |
 | `UrlField` · `UrlFormField` | `string` (as typed) | `''` |
 | `SearchField` · `SearchFormField` | `string`, after `debounceMs` (default `0`) | `''` |
 | `ColorField` · `ColorFormField` | `string` (hex, `'#1e293b'`) | `''` |
@@ -535,7 +536,7 @@ or fails validation.
 | Field · wrapper | Form value | Empty default |
 | --- | --- | --- |
 | `NetworkUploadField` · `NetworkUploadFormField` | `mode="single"`: the `string` your `onUpload` resolved (a URL or a key), or `null` after removal. `mode="multiple"`: `string[]` | `undefined` / `[]` |
-| `S3UploadField` · `S3UploadFormField` | as above; the value is `publicUrl` from `getPresignedUrl` | `undefined` / `[]` |
+| `S3UploadField` · `S3UploadFormField` | as above; the value is `publicUrl` (PUT) or `value` (POST) from `getPresignedUrl` | `undefined` / `[]` |
 | `ImageField`, `ImageS3Field` · `ImageFormField`, `ImageS3FormField` | `string \| null` (the uploaded URL) | `undefined` |
 | `FileListField`, `FileListS3Field` · `FileListFormField`, `FileListS3FormField` | `string[]` | `[]` |
 | `FilesFormField` | `mode="single"`: `string \| null`. `mode="multiple"`: `string[]` (typed or picked URLs) | `null` / `[]` |
@@ -785,8 +786,9 @@ form.setFocus('email'); // or without an error
 
 ## 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?)`
+`useFastForm`, `useFocusOnRefusal` and `useServerFieldErrors`
+(`@nxgt/material/components`) are the three habits of a record form, in one
+place; the first two are below, the third under [Server errors](#server-errors). `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
@@ -820,8 +822,24 @@ Storybook: `Guides/Forms/useFastForm`. If the focus does not move, see
 
 ## Server errors
 
-Map an API's field errors onto the form with `setError`, and put anything that
-belongs to no field under `root`, shown in an `Alert`:
+`useServerFieldErrors(form, fieldErrors)` (`@nxgt/material/components`) puts an
+action's `{ path: message }` field errors on the form, each under its field
+with `type: 'server'`, and focuses the first. It runs when the `fieldErrors`
+object changes, so pass the answer's own object (one per answer) and
+`undefined` while a request runs or when the answer is not a refusal; entries
+with an empty message are skipped, and the keys must be names of the form's
+fields.
+
+```tsx
+import { useFastForm, useServerFieldErrors } from '@nxgt/material/components';
+
+const form = useFastForm<Values>({ defaultValues }, 'email');
+useServerFieldErrors(form, actionData?.fieldErrors); // { email: 'Already used' }
+```
+
+It pairs with `useFastForm` and `useFocusOnRefusal` above. To write the same
+mapping by hand, or to put anything that belongs to no field under `root`,
+shown in an `Alert`, use `setError`:
 
 ```tsx
 import { useForm } from 'react-hook-form';
@@ -869,6 +887,36 @@ export function SignInForm() {
 - `Alert` `variant` is one of `primary`, `secondary`, `error`, `success`,
   `info`, `warning`, `foreground`.
 
+### A save refused because another write came first
+
+When the API refuses a versioned save (`stale-version`), keep the form as it is
+and show a `StaleNotice` above it. It takes the focus and scrolls into view on
+mount, and its one action reads the record again. There is no overwrite.
+
+```tsx
+import type { FormEventHandler } from 'react';
+import type { UseFormReturn } from 'react-hook-form';
+import { Button, StaleNotice, TextFormField } from '@nxgt/material/components';
+
+type Props = {
+  form: UseFormReturn<{ title: string }>;
+  stale: boolean; // the save was refused with `stale-version`
+  reload: () => void; // read the record again
+  reloading: boolean;
+  onSubmit: FormEventHandler<HTMLFormElement>;
+};
+
+function EditNote({ form, stale, reload, reloading, onSubmit }: Props) {
+  return (
+    <form onSubmit={onSubmit} className="grid gap-4">
+      {stale && <StaleNotice onReload={reload} busy={reloading} />}
+      <TextFormField control={form.control} name="title" label="Title" />
+      <Button type="submit">Save</Button>
+    </form>
+  );
+}
+```
+
 ## Dialogs and steps
 
 ### A form in a dialog

package/docs/guides/i18n.md

@@ -236,7 +236,7 @@ the camera's button, toggle and image (`material.camera.capture`, `captured`,
 barcode accessible names, the calendar's navigation tooltips
 (`material.calendar.*`), the data table's selection checkboxes, the filter's
 presets and `Min`/`Max` fields, the `variant="4"` spinner's label,
-`ScrollToTop`, the network upload field's `Retry`/`Remove`, the map's
+`ScrollToTop`, the network upload field's `Retry` and `Remove {name}`, the map's
 `You are here` and zoom buttons, and the icon-only close button of
 `DialogClose`, `DrawerClose`, `SheetClose` and `SheetContent`'s
 `withCloseButton`. A range `Slider`'s readout inputs read
@@ -320,9 +320,9 @@ those words as an optional third argument); the `aria-label` of `Breadcrumb`
 and `Pagination` and the breadcrumb ellipsis's "More"
 (`material.breadcrumb.*`, `material.pagination.label`), and `DocHeader`'s
 breadcrumb (`material.doc.breadcrumb`); `MessageCard`'s "Unread"
-(`material.cards.unread`); the network upload field's "Replace {name}", "Upload
+(`material.cards.unread`); the network upload field's "Replace {name}", "Remove {name}", "Upload
 failed", its type, size and count errors (`material.upload.replace-named`,
-`failed`, `invalid-type`, `too-large`, `max-files`; an error keeps the language
+`remove-named`, `failed`, `invalid-type`, `too-large`, `max-files`; an error keeps the language
 it was raised in) and the drop zone's "Max {size}" and "Up to {count} files"
 (`material.upload.dropzone.max-size` / `max-files`); the editor's
 placeholder, which follows a language change without rebuilding the editor,
@@ -485,8 +485,9 @@ and description and against the English ones, ignoring accents: in French,
 
 Some strings are still English in every language, among them the filter's
 validation messages, the camera's error messages, the editor's callout type
-names and default block content. File sizes (`2 KB`) and the filter chips' dates are not formatted for
-the provider's language.
+names and default block content. The filter chips' dates, and file sizes outside the upload field (`2 KB`),
+are not formatted for the provider's language; the upload field writes its
+size in it (`10,4 ko`).
 
 The emoji picker's category tabs are icon-only; their name, read by screen
 readers and shown as a tooltip, comes from `material.emoji.groups.<group>`.

package/docs/guides/printing.md

@@ -1013,7 +1013,7 @@ it:
 | `heading` | `heading(text, level?)` | A title, level `1`, `2` or `3` |
 | `text` | `text(content, { variant?, style? })` | A paragraph: a string, or runs `{ text, bold?, italic?, color?, href? }`; `variant` is `'body'`, `'muted'`, `'caption'` or `'label'` |
 | `stack` / `row` | `stack(children, { gap?, style?, keepTogether? })`, `row(children, { gap?, align?, justify?, style? })` | Children one under the other, or side by side |
-| `section` | `section(title, children, { keepTogether? })` | A titled block, as `PrintSection`; `keepTogether` as on a `stack` |
+| `section` | `section(title, children, { keepTogether? })` | A titled block, as `PrintSection`; `keepTogether` as on a `stack`; a block taller than a page breaks normally, see [Keeping a block on one page](#keeping-a-block-on-one-page) |
 | `table` | `table({ columns, rows, footer?, labelTotals?, striped?, repeatHeader?, keepRowsWhole?, emptyText?, hideWhenEmpty? })`, or `dataTable(columns, rows, options?)` from [column definitions](#tables-from-column-definitions-datatable-and-keyvalueof) | A table of `PrintValue`s, as `PrintDataTable`; a row or a cell may carry a `style`, see [Row and cell styles](#row-and-cell-styles-in-a-table); with `labelTotals`, an empty first cell of a `footer` row reads "Total" in the document's language |
 | `keyValue` | `keyValue(items, { columns?, keepEmpty? })`, or `keyValueOf(fields, data, options?)` from column definitions | Label and value pairs, as `PrintKeyValue` |
 | `totals` | `totals(rows)` | Label and value rows; `emphasis` makes one bold |
@@ -1140,12 +1140,22 @@ section(group.title, rows, { keepTogether: true });
 stack([heading('Result'), table(result)], { keepTogether: true });
 ```
 
-Use it on a block you know is shorter than a page. react-pdf cannot split a
-block that opted out of wrapping: a block taller than the page area is not
-broken, it overflows the page and is cut off at the edge (react-pdf logs
-"can't wrap between pages and it's bigger than available page height").
-Leave `keepTogether` off for a block that may grow past a page, and use
-`keepRowsWhole` and `repeatHeader` on a long table instead.
+A block taller than a page breaks normally. react-pdf cannot split a block
+that opted out of wrapping (it overflows and is cut off at the edge), and
+cannot measure ahead, so for a document as data `renderPdfBuffer`,
+`renderPdfBlob`, `renderPdfStream`, `downloadPdf`, `openPdf` and `pdfResponse`
+first render each `keepTogether` block alone, on a page like the one it sits
+on, and drop the option of those that need more than one page. A block that
+fits keeps it, so its output does not change; a document with no
+`keepTogether` pays for no extra pass. The measure is made at the page's
+width: a block inside a `row` is measured with that row, but a parent's padding or narrower style is not applied.
+
+This holds for a document as data only. `<PrintSection keepTogether>` in a
+`PrintDocument` element, and a document you render yourself with
+`renderPdfElement`, are not measured: use `keepTogether` there on a block
+shorter than a page, or call `resolveKeepTogether(doc)` from
+`@nxgt/material-core/pdf/render` first and render its result. For a long
+table, `keepRowsWhole` and `repeatHeader` keep the rows apart from each other.
 
 ### Row and cell styles in a table
 

package/docs/roadmap.md

@@ -6,6 +6,8 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Now
 
+- **Calculator** — `@nxgt/material/calculator` adds `Calculator`, in six variants (Standard, Scientific, point of sale, Financial, Unit conversion, Programmer) chosen by `variant` or by its own switcher, and `CalculatorField` / `CalculatorFormField`, a number field whose button opens it in a popover, or a bottom sheet on a phone. Every variant shows the whole expression above the result, honours operator precedence and computes in exact decimals (0.1 + 0.2 = 0.3) without `eval`, so a strict CSP holds. A history tape (persisted, with an opt-out), memory keys, the physical keyboard, copy and paste, locale formatting and screen-reader announcements come with each; haptic and sound feedback are opt-in. Point of sale charges through `onCharge(total)`; currency rates come from the app. React only for now; the Vue port is tracked in [#2100](https://github.com/softistx/nxgt-material/issues/2100). Tracked in [#2101](https://github.com/softistx/nxgt-material/issues/2101).
+
 - **Barcodes and label sheets** — `@nxgt/material/barcode` draws Code 128
   and Data Matrix as accessible SVG (themed, dark-aware, black on white in
   print) and lays labels out on a sheet to print: label size, columns, rows,
@@ -15,6 +17,10 @@ version they shipped in, and planned entries may name the major they target.
 - **Toast texts follow app translations** — the toast presets read the
   app's `I18nProvider` `resources`, so an override under `material.*`
   changes their wording ([#1855](https://github.com/softistx/nxgt-material/issues/1855)).
+- **A record page layout** — `RecordPage` and `RecordDetails` lay out one
+  record: a header card, the content, and its facts as a side panel from `xl`
+  that stacks after or before the content, with a created / updated line
+  ([#1689](https://github.com/softistx/nxgt-material/issues/1689)).
 - **A decision bar for phone pages** — `StickyActionBar` holds a long page's
   main decision at the bottom of a phone, above the keyboard and clear of the
   safe areas, and inline from `md`
@@ -157,6 +163,8 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Next
 
+- **Layouts: adaptive navigation, headers and page layouts** — `ActivityLayout` takes `navigation` (a bottom bar, a rail with a FAB, standard and modal drawers, a collapsible sidebar, a top navigation with dropdowns, two-level navigation or a floating toolbar, chosen for phone, tablet and desktop) and `header` (small, center-aligned, medium and large collapsing on scroll, a search bar with full-screen search on a phone, sticky tabs, hide on scroll); each piece is also exported. Page layouts grow with it: an inspector pane and URL state for `ListDetailsLayout`, phone modes for `PaneLayout`, spans and masonry for `ResponsiveGrid`, tabs for `Kanban` on a phone, and new settings, dashboard (rearranging tiles), editor and landing layouts, each with a screen recipe. Everything is opt-in; the shell's default is unchanged. Tracked in [#2103](https://github.com/softistx/nxgt-material/issues/2103).
+
 - **FilterBar "Add a filter" stays on its row** — the button no longer wraps
   alone onto a second row on a desktop screen ([#1752](https://github.com/softistx/nxgt-material/issues/1752)).
 
@@ -241,11 +249,13 @@ version they shipped in, and planned entries may name the major they target.
   slot; the bar's `views` slot is planned with it. They are meant to replace
   the legacy `FilterPresets`. Tracked in [#1876](https://github.com/softistx/nxgt-material/issues/1876).
 
-- **RecordActionsMenu** — one menu for a record's lifecycle: archive with an Undo toast (or confirm first with `archivePolicy="confirm"`), restore, and delete that always confirms and shows the backend's refusal, with `ConfirmDialog` gaining `details` and `refusal` slots.
 - **Cursor trail cap** — `ServerTable` and `PageFooter` keep cursor URLs short: the trail is encoded once and capped by `maxTrail` (20 by default) with an exact page count, and `totalCount` becomes optional for APIs that do not count.
 
 ## Later
 
+- **One `onUpload` options object (next major)** — the upload fields'
+  `onUpload(file, onProgress?, signal?)` becomes `onUpload(file, { onProgress,
+  signal })`, like the editor's upload context.
 - **A strict theme `motif` (4.0)** — a theme background's `motif` with an
   unknown key, a `layout` or `density` outside its list or a bad `icons` is
   dropped in 3.22 (`@nxgt/material/themes`'s `defineTheme` warns for each one in
@@ -361,6 +371,9 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **RecordActionsMenu (next minor)** — one menu for a record's lifecycle: archive with an Undo toast (or confirm first with `archivePolicy="confirm"`), restore, and delete that always confirms and shows the backend's refusal, with `ConfirmDialog` gaining `details` and `refusal` slots.
+- **Assistant approval card (next minor)** — `ChatActionProposal` shows an action an assistant proposes, with its status, deadline and Confirm / Reject, and `ChatToolActivity` is a compact row for a tool step in a chat thread ([#2134](https://github.com/softistx/nxgt-material/issues/2134)).
+
 - **Link navigation (3.66.0)** — `TabsNav` and `SegmentedNav` render route tabs and segmented navigation as a `nav` of links with `aria-current="page"`, looking like Tabs and the segmented ToggleGroup, plus `useTabParam`, `skipTabChange` and `tabIds` to keep the current tab in the URL. Tracked in [#2029](https://github.com/softistx/nxgt-material/issues/2029).
 
 - **Smaller, easier-to-read components (3.58.0)** — the library's own source