@nxgt/material 3.70.0 → 3.72.0

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

@@ -16,6 +16,7 @@ either can be used alone.
 | <img src="../previews/data-table-filter-lists-datatable.webp" width="96" alt=""> | [DataTable](#datatable) | TanStack Table v9 with sorting, selection, expansion and pagination, client-side or one server page at a time |
 | <img src="../previews/data-table-filter-lists-servertable.webp" width="96" alt=""> | [ServerTable](#servertable) | A server-mode `DataTable` driven by the URL, with the Filter in its top band (a title and a description, or neither): sort, cursor paging, the empty page with a scene, an action and removable chips, one count announced |
 | <img src="../previews/data-table-filter-lists-rowmenu.webp" width="96" alt=""> | [RowMenu](#rowmenu) | A row's "..." button named after its row ("Actions for Ada"), its menu aligned to the end with the destructive item last, a loading state while an action runs, `rowMenuColumn` to drop both in a table, and `useRowMenuFocus` to hand the focus back to a row's button after an action |
+| <img src="../previews/data-table-filter-lists-recordactionsmenu.webp" width="96" alt=""> | [RecordActionsMenu](#recordactionsmenu) | A record's archive, restore and delete menu over `RowMenu`: Archive runs at once with an Undo toast that stays until dismissed, Restore runs at once, Delete permanently asks first and keeps a refusal in its dialog; `archivePolicy="confirm"` asks before archiving, `consequence` notes what an action entails, `successAction` adds a toast action, and an `ActionRefusal` (`isActionRefusal`) carries a refusal's details and action |
 | <img src="../previews/data-table-filter-lists-listempty.webp" width="96" alt=""> | [ListEmpty](#listempty) | A list's empty page: nothing yet, with a scene and an action, or nothing matches and the way out |
 | <img src="../previews/data-table-filter-lists-pagefooter.webp" width="96" alt=""> | [PageFooter](#pagefooter) | The page footer of a feed that is not a table (cards, a news feed) under a FilterBar: the range and Previous / Next as links from the URL's cursor trail, `pageControls="icon"`; no `totalCount` for a feed with no total (no range, Previous / Next only); `hideOnSinglePage` hides it on a single page |
 | <img src="../previews/data-table-filter-lists-datagrid.webp" width="96" alt=""> | [DataGrid](#datagrid) | An editable grid: spreadsheet keys, paste, a fill handle with series, undo, totals, saving with versions and conflicts (lazy ones fetch theirs on "Keep mine"), `onRefuse` for a refused paste or fill, row selection (`enableRowSelection`), and resizable, hideable and reorderable columns (`columnControls`, `columnLayout`, `DataGridColumnsMenu`) |
@@ -1042,7 +1043,7 @@ Its props are `ServerTableProps<T>`; `filter` is a `ServerTableFilter`,
 | `hideOnSinglePage` | `boolean` | `false` | hides the footer's range and Previous / Next when the result is one page (no previous, no next), in the table, cards and tiles layouts; the count is still announced by the live region but no longer shown, so put it in `description` or keep the footer. With `bulkActions` the footer stays for "N rows selected", without its pager |
 | `bandActions` | `'stacked' \| 'inline'` | `'stacked'` | with `filter`, where `actions` sit below 768px: `'stacked'` gives them a row above the search; `'inline'` keeps them on the search's row (the search takes the room left), for a lone icon action such as a "+". An action wider than 3.5rem wraps under the search. From 768px both are the same. With a cards or tiles list on a phone, neither applies: [the two-row header](#the-phone-header-of-a-list-in-cards-or-tiles) puts the actions on its second row |
 | `filterRef` | `Ref<ServerTableFilterHandle>` | — | with `filter`: `filterRef.current.focus()` focuses the Filter's first control, the search, else the first quick filter, "Add filter" or "Filters (N)" the width shows |
-| `sorting` | `createSorting(…)` | — | headers sorted from the URL |
+| `sorting` | `createSorting(…)` | — | headers sorted from the URL; without it, no column is sortable (the server sorts, so pass `sorting` to let people sort), and the phone list bar shows only for selection |
 | `filters` | `tableFilters(model)` | — | without `filter`: "nothing matches" and its clear |
 | `empty` | `ServerTableEmpty`: `{ none, noMatch, clear?, headingLevel?, iconStyle? }` | — | the empty page: `none` and `noMatch` are a title or a `ListEmptyPage` (`{ title, description?, illustration?, action? }`); `headingLevel` (default 2) is the level of its title and of the error's; `iconStyle` styles the scenes (see below) |
 | `error` | `ServerTableError \| null` | — | the fetch failed: the failure and a Retry replace the rows |
@@ -1071,6 +1072,11 @@ not three:
    "Select all on this page"); at the end, the sort menu, "Filters (N)" and
    the page's `actions`.
 
+On a phone (below 768px) the "Select all" text shortens with an ellipsis (the box keeps its
+full name) rather than run under the sort, "Filters (N)" or the actions. When
+the end group is too wide to leave the start 6rem, it wraps to a line of its
+own under "Select all", in the same order.
+
 While rows are selected, row 2 becomes the selection bar: "N rows selected"
 (`material.table.pagination.selected`) and "Clear selection" take the label's
 place, and the `bulkActions` take the place of the sort, "Filters (N)" and the
@@ -1092,8 +1098,8 @@ Filters sheet are the same. A list that cannot be selected has no checkbox
 without `actions`, `variant: 'facets'` and every width from 768px are
 unchanged, and `bandActions` has no effect while the second row is there.
 
-The row is narrow, so it compacts to the band's width, never wrapping to a
-third row: below 30rem the sort shows its icon and arrow (its name, "Sort: Name,
+The row is narrow, so it compacts to the band's width: when the end group is
+still too wide it wraps under "Select all" (a third line, see above). Below 30rem the sort shows its icon and arrow (its name, "Sort: Name,
 Ascending", is unchanged); "Filters (N)" keeps its icon and count (and its
 name) while rows are selected, and on a band narrower than 19rem; the count
 may take two lines. A button of `actions` that has an icon (a lucide glyph or
@@ -1195,10 +1201,16 @@ const columns = [
 
 `rowMenuColumn` returns a column for `DataTable` and `ServerTable`: a header
 that is visually hidden but named "Actions" (`material.row-menu.column`), a cell
-per row, no sorting and no hiding. Build the columns once (outside the render,
-or in a `useMemo`), and keep a dialog's state in the page, not in the cell: a
+per row, no sorting and no hiding. A row whose `items(row)` is empty (or whose
+`items` option is absent) and whose `menu(row)` returns nothing (`null`,
+`undefined` or `false`, as in `cond && <X />`) renders an empty cell, with no
+button, and the column keeps its width. A fragment counts as content, even an
+empty one. Build the columns once (outside the render, or in a `useMemo`), and
+keep a dialog's state in the page, not in the cell: a
 cell that remounts would lose it.
 
+When any item has an icon, the items without one are inset by the icon's width, so the labels line up.
+
 For a menu of your own, compose the parts: `RowMenuTrigger` forwards its props
 and `ref`, so it is the child of a `DropdownMenuTrigger asChild`.
 
@@ -1303,6 +1315,106 @@ a table re-render that remounts the button.
 
 **Storybook:** `Data table, filter & lists/RowMenu`, `Guides/Accessibility/Touch targets/Row menu` · **Vue:** not yet (tracked as a `vue` issue)
 
+
+---
+
+## RecordActionsMenu
+
+![RecordActionsMenu](../previews/data-table-filter-lists-recordactionsmenu.webp)
+
+A record's archive, restore and delete menu, built over [RowMenu](#rowmenu): the same
+button ("Actions for {name}", 44px on touch), the same focus return, and the
+record's actions after any of your own.
+
+- **Archive** (a record that is not archived) runs at once and shows a toast, "{name} archived", with an **Undo** action. Each archive leaves a toast until it is dismissed (WCAG 2.2.1: no timeout to race). Undo restores; a successful Undo calls `onDone('restore')` and shows no second toast; a failure of it is shown in a toast.
+- **Restore** (an archived record) runs at once.
+- **Delete permanently** (an archived record only) comes after a separator, in the error colour, and **always asks**: a `ConfirmDialog` with `lockOnRefusal`. A refusal stays in the dialog and locks the confirm button; Cancel stays.
+- **`archivePolicy="confirm"`** makes Archive ask first, in a `ConfirmDialog` (default tone) whose note is the `consequence`; its success toast is plain, with no Undo. A refusal then stays in that dialog, as delete's does (not locked: Cancel and a retry stay possible).
+- **`consequence`** is a note of what the action entails, shown under the dialog's description (delete, and archive under `'confirm'`). One node for every action, or a map per intent: `{ delete: 'Its files are deleted too.' }`.
+- **`successAction`** adds an action to the success toast, per intent (`archive`, `restore`): `{ archive: { label: 'View archive', href: '/archive' } }`, or `onAction` for a client-side navigation. A toast has one button, so beside Undo the action is a link in the toast's text.
+- **`ActionRefusal`**: reject `send` with `new ActionRefusal(message, { action, details? })` to carry a refusal with an action (`{ label, href }` or `{ label, onAction }`). The delete dialog (and the confirm-archive one) shows the message, the details and the action, as any [ConfirmDialog](feedback-and-status.md#confirmdialog) does by default; a link or handler closes the dialog. An archive or restore refusal shows the action as the toast's button. A plain `Error` keeps showing its message only. The class, `isActionRefusal` and `RecordAction` belong to `ConfirmDialog`'s section.
+- A refused archive or restore shows the error's message in a toast.
+- Undo goes through the same flight as Archive and Restore: the menu's trigger is busy meanwhile and the menu cannot start another action until it is over. An Undo clicked while another action runs waits for it, then runs only if the record is archived by then (a failed archive or a successful restore leaves nothing to undo; the hook decides from what settled, not from a re-render); a second click on the same Undo does nothing.
+- When any item of the menu has an icon, the ones without (your own `items`) are inset so the labels line up.
+- The whole menu renders nothing when `can` leaves no action and you gave no item of your own.
+
+```tsx
+import { RecordActionsMenu } from '@nxgt/material/components';
+
+<RecordActionsMenu
+  name={project.title}
+  archived={project.archivedAt != null}
+  can={(intent) => permissions.has(`project:${intent}`)}
+  send={(intent) => api.projects.act(project.id, intent)}
+  onDone={(intent) => intent === 'delete' && navigate('/projects')}
+  items={[{ label: 'Edit', onSelect: () => navigate(`${project.id}/edit`) }]}
+/>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `name` | `string` | — | the record's name: the button's name ("Actions for {name}"), the toasts' and the dialog's text |
+| `archived` | `boolean` | — | `true` offers Restore, then Delete permanently; `false` offers Archive |
+| `send` | `(intent: 'archive' \| 'restore' \| 'delete') => Promise<unknown>` | — | does the action. A rejection's message is shown in a toast (archive, restore) or in the dialog (delete) |
+| `can` | `(intent) => boolean` | everything | the actions refused are left out |
+| `onDone` | `(intent) => void` | — | after a success, an Undo's restore included (`'restore'`): refresh a list, or leave a deleted record's route |
+| `items` | `RowMenuItem[]` | — | items of your own, before the record's actions |
+| `children` | `ReactNode` | — | menu content of your own (submenus, groups), above `items` |
+| `messages` | `RecordActionsMessages` | translated | wording overrides (camelCase keys; the i18n keys are kebab-case), `{name}` replaced by the record's name: `archive`, `restore`, `delete`, `archived`, `restored`, `undo`, `failed`, `archiveTitle`, `archiveDescription`, `archiveConfirm`, `deleteTitle`, `deleteDescription`, `deleteConfirm` |
+| `archivePolicy` | `'undo' \| 'confirm'` | `'undo'` | `'undo'` archives at once with an Undo toast; `'confirm'` asks in a dialog first, with no Undo |
+| `consequence` | `ReactNode \| Partial<Record<ConsequenceIntent, ReactNode>>` | — | the dialog's note of what the action entails (delete, and archive under `'confirm'`) |
+| `successAction` | `{ archive?: RecordAction; restore?: RecordAction }` | — | an action on the success toast; `RecordAction` is `{ label, href?, onAction? }`: `onAction` wins when both are given, and `href` is a full page load (use `onAction` for client-side navigation) |
+| `refusal` | `(ctx: ConfirmRefusalContext) => ReactNode` | — | replaces `ConfirmDialog`'s default refusal (the message, plus an `ActionRefusal`'s details and action) in both dialogs, delete and archive (`'confirm'`); `ctx.cause` is what `send` rejected with. Toasts are not affected |
+| `rowId`, `triggerProps`, `className` | as `RowMenu` | — | passed to the `RowMenu` |
+
+```tsx
+import { ActionRefusal, RecordActionsMenu } from '@nxgt/material/components';
+
+<RecordActionsMenu
+  name={project.title}
+  archived={project.archivedAt != null}
+  archivePolicy="confirm"
+  consequence={{ archive: 'Open tasks stay assigned.', delete: 'Its files are deleted too.' }}
+  successAction={{ restore: { label: 'Open project', onAction: () => navigate(project.id) } }}
+  send={async (intent) => {
+    const blockers = await api.projects.act(project.id, intent);
+    if (blockers) {
+      throw new ActionRefusal(`Still used by ${blockers.count} invoices`, {
+        details: 'Remove them first.',
+        action: { label: 'View the invoices', href: `/invoices?project=${project.id}` },
+      });
+    }
+  }}
+/>
+```
+
+Types: `RecordActionsMenuProps`, `RecordIntent` (`'archive' | 'restore' | 'delete'`), `ConsequenceIntent` (`'archive' | 'delete'`, the intents with a dialog), `ArchivePolicy`, `RecordSuccessActions`, `RecordConsequence`, `RecordActionsMessages` and `UseRecordActionsOptions`, all exported (`RecordAction`, `ActionRefusal` and `isActionRefusal` come with [ConfirmDialog](feedback-and-status.md#confirmdialog)). A throw from `onDone` is logged with `console.error`; it does not hide the toast nor count as a refusal. A second archive or restore while one is pending is ignored; an Undo waits for it.
+
+The default words are the `material.record-actions.*` keys (`archive`, `restore`,
+`delete`, `archived`, `restored`, `undo`, `failed`, `archive-title`, `archive-description`,
+`archive-confirm`, `delete-title`, `delete-description`, `delete-confirm`). `useRecordActions` holds the logic if you
+need to build the menu from other parts. The archive toast is shown by `toasts`,
+so mount a `Toaster`.
+
+### useRecordActions
+
+The menu's logic, for a menu built from other parts. It takes `UseRecordActionsOptions` (`name`, `archived`, `send`, and optionally `can`, `onDone`, `messages`, `archivePolicy`, `successAction`) and returns:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `intents` | `RecordIntent[]` | the actions offered, `can` applied |
+| `running` | `'archive' \| 'restore' \| null` | the action in flight (an Undo counts as `'restore'`) |
+| `run(intent)` | `(intent: 'archive' \| 'restore') => Promise<void>` | runs it and shows the toasts (Undo included) |
+| `runUndo()` | `() => Promise<void>` | the archive toast's Undo: queued behind a pending action, then restores through the same flight, so `running` is set meanwhile |
+| `confirmingDelete`, `setConfirmingDelete` | `boolean`, setter | the delete dialog's open state |
+| `confirmingArchive`, `setConfirmingArchive` | `boolean`, setter | the archive dialog's open state (`archivePolicy="confirm"`) |
+| `chooseArchive()` | `() => void` | what choosing Archive does: opens the dialog under `'confirm'`, else runs at once |
+| `archiveConfirmed()` | `() => Promise<void>` | the archive dialog's `onConfirm`: sends `archive`, throws a refusal |
+| `deleteConfirmed()` | `() => Promise<void>` | the delete dialog's `onConfirm`: sends `delete`, throws a refusal |
+| `text` | strings | the words: `archive`, `restore`, `delete`, `archiveTitle`, `archiveDescription`, `archiveConfirm`, `deleteTitle`, `deleteDescription`, `deleteConfirm` |
+
+**Storybook:** `Data table, filter & lists/RecordActionsMenu` (`Overview`, `Archive Then Undo`, `Archived Record`, `Delete Refused Stays Locked`, `Delete Confirmed`, `Iconless Item Aligned`) and `…/RecordActionsMenu/Confirm and refusals` (`Archive With Confirm`, `Archive Cancel Returns Focus`, `Note Is Described`, `Delete Refused With Action`, `Archive Refused With Handler`, the `Refusal Override` pair, the refused-toast pair, `Success Action On Toast`) · **Vue:** not yet (#2092)
+
 ---
 
 ## ListEmpty

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

@@ -9,10 +9,11 @@ centre.
 | <img src="../previews/feedback-status-alert.webp" width="96" alt=""> | [Alert](#alert) | Callout with icon, title and description in seven tones |
 | <img src="../previews/feedback-status-banner.webp" width="96" alt=""> | [Banner](#banner) | Dismissible banner with an action, in the look of Alert |
 | <img src="../previews/feedback-status-alertdialog.webp" width="96" alt=""> | [AlertDialog](#alertdialog) | Parts for a blocking confirmation dialog |
-| <img src="../previews/feedback-status-confirmdialog.webp" width="96" alt=""> | [ConfirmDialog](#confirmdialog) | Confirm / cancel dialog, `ConfirmationDialog`, `CustomAlertDialog` |
+| <img src="../previews/feedback-status-confirmdialog.webp" width="96" alt=""> | [ConfirmDialog](#confirmdialog) | Confirm / cancel dialog, `ConfirmationDialog`, `CustomAlertDialog`; `ActionRefusal` (`isActionRefusal`) carries a refusal's details and action |
 | <img src="../previews/feedback-status-customdialog.webp" width="96" alt=""> | [CustomDialog](#customdialog) | Ready-made dialog with trigger, icon, title, body and footer |
 | <img src="../previews/feedback-status-stepupdialog.webp" width="96" alt=""> | [StepUpDialog](#stepupdialog) | "Confirm it's you": a dialog that asks for a one-time code, driven by props |
 | <img src="../previews/feedback-status-unsaveddialog.webp" width="96" alt=""> | [UnsavedDialog](#unsaveddialog) | "Leave without saving?": a destructive confirm with Stay focused, used by the unsaved-changes guards |
+| <img src="../previews/feedback-status-stalenotice.webp" width="96" alt=""> | [StaleNotice](#stalenotice) | "This record changed": a warning that another write came first, with one Reload action and no overwrite |
 | <img src="../previews/feedback-status-emptystate.webp" width="96" alt=""> | [EmptyState](#emptystate) | Illustration, title, description and action, by kind (empty, search, not-found, unauthorized) |
 | <img src="../previews/feedback-status-pageloadfailed.webp" width="96" alt=""> | [PageLoadFailed](#pageloadfailed) | An empty state for a page opened at a cursor that failed, with a link back to the start |
 | <img src="../previews/feedback-status-errorstate.webp" width="96" alt=""> | [ErrorState](#errorstate) | Failure block with Retry and technical details |
@@ -239,14 +240,44 @@ function DeleteProject({ onDelete }: { onDelete: () => Promise<void> }) {
 | --- | --- | --- | --- |
 | `open` / `onOpenChange` | `boolean` / `(open: boolean) => void` | required | controlled only |
 | `onConfirm` | `() => void \| Promise<void>` | required | awaited with the dialog open and both buttons disabled; closes on success; on a throw or rejection the dialog stays open and shows the error's message, or the translated `material.confirm-dialog.failed` ("The action failed.") when it has none |
+| `title` / `description` | `string` / `ReactNode` | required | a string `description` renders in a paragraph; any other node (several `<p>`, a list, a link) renders in a `div`, so a consent notice of several paragraphs is valid HTML; both name the dialog (`aria-describedby`) |
 | `variant` | `'default' \| 'destructive'` | `'default'` | `destructive` paints the confirm button `error` |
 | `loading` | `boolean` | `false` | disables both buttons and shows the translated `material.confirm-dialog.processing` label, as a pending `onConfirm` does |
 | `confirmDisabled` | `boolean` | `false` | disables the confirm button, for example while an error of yours stands |
 | `lockOnRefusal` | `boolean` | `false` | once `onConfirm` has refused (thrown), the confirm button stays disabled while its error shows, so a retry that cannot succeed is not invited; Cancel stays enabled. The error clears when the dialog closes |
+| `details` | `ReactNode` | — | a note under the description, read with it by assistive technology, for what else is affected or cannot be undone |
+| `refusal` | `(refusal: ConfirmRefusalContext) => ReactNode` | the message; an `ActionRefusal`'s details and action too | renders the refusal inside the error alert (still `role="alert"`, a `div`) instead of the default, so it can carry a link. Receives `{ message, cause, close }`: `message` is the thrown error's message or the translated `material.confirm-dialog.failed` text, `cause` is what `onConfirm` threw, `close()` closes the dialog |
 | `confirmLabel` / `cancelLabel` | `string` | "Confirm" / "Cancel", translated (`material.confirm-dialog.confirm` / `.cancel`) | button text |
 | `cancelVariant` | `ButtonVariant` | `'tonal'` | the Cancel button's variant; `'outlined'` restores the earlier look |
 | `onCloseAutoFocus` | `(event: Event) => void` | — | called as the dialog closes, before the focus goes back; `event.preventDefault()` places it yourself, e.g. `ctx.focusTrigger()` of a `ServerTable` bulk action whose button a redraw replaced |
 
+```tsx
+<ConfirmDialog
+  open={open}
+  onOpenChange={setOpen}
+  title="Delete item"
+  description="This cannot be undone."
+  details="Its attachments are deleted with it."
+  onConfirm={remove}
+  refusal={({ message, close }) => (
+    <>
+      {message}. <a href="/usage" onClick={close}>See what still uses it</a>
+    </>
+  )}
+/>
+```
+
+**`ActionRefusal`** is the refusal that carries an action. Throw `new ActionRefusal(message, { action, details? })` from `onConfirm`, with `action` `{ label, href }` (a link, a full page load) or `{ label, onAction }` (a handler, for client-side navigation; it wins when both are given) and `details` a note. The alert then shows the message, the details and the action, and the action closes the dialog; any other error shows its message only. `isActionRefusal(error)` is the guard (it also accepts a copy from another install of the package), and `RecordAction` is the action's type. `RecordActionsMenu` reuses all of this.
+
+```tsx
+throw new ActionRefusal('Still used by 3 invoices', {
+  details: 'Remove them first.',
+  action: { label: 'View the invoices', href: '/invoices' },
+});
+```
+
+The `details` note is part of the dialog's accessible description (`aria-describedby`), with the `description`. While `onConfirm` runs, the buttons are disabled and the focus stays on the dialog, not on the page behind it.
+
 On a phone (below 640 px) the footer stacks. A `destructive` dialog puts Cancel first and the destructive action last; a default one keeps the action on top.
 
 `ConfirmDialog` opens with its Cancel focused, so Enter cancels. On closing
@@ -312,7 +343,7 @@ built on `AlertDialog`, so it does not close on an outside click. Put
 `AlertDialogCancel` / `AlertDialogAction` in its `footer`.
 
 **Storybook:** `Feedback & status/ConfirmDialog`, `Feedback & status/ConfirmationDialog`,
-`Feedback & status/CustomAlertDialog` · **Vue:** `ConfirmDialog`, `ConfirmationDialog` (`form-options` + `#form` slot for `renderForm`), `CustomAlertDialog`
+`Feedback & status/CustomAlertDialog` · **Vue:** `ConfirmDialog` (no `details` / `refusal` yet), `ConfirmationDialog` (`form-options` + `#form` slot for `renderForm`), `CustomAlertDialog`
 
 ---
 
@@ -491,6 +522,31 @@ import { UnsavedDialog } from '@nxgt/material/components';
 
 ---
 
+## StaleNotice
+
+![StaleNotice](../previews/feedback-status-stalenotice.webp)
+
+Another write came first (a `stale-version` refusal on a versioned record). Keep what was typed, show this warning `Alert`, and let the user read the record again. It takes the focus and scrolls itself into view (`block: "center"`) when it mounts, and it has no "overwrite" action. Built on `Alert` and `Button`; see [Server errors](../guides/forms.md#a-save-refused-because-another-write-came-first).
+
+```tsx
+import { StaleNotice } from '@nxgt/material/components';
+
+{stale && <StaleNotice onReload={revalidate} busy={state === 'loading'} />}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `onReload` | `() => void` | — | runs on "Reload the record" |
+| `busy` | `boolean` | `false` | the button shows as loading |
+| `message` | `string` | translated | replaces the description |
+| `className` | `string` | — | on the wrapper that takes the focus |
+
+The title, description and button come from `material.stale-notice.*`.
+
+**Storybook:** `Feedback & status/StaleNotice` · **Vue:** not yet (`vue` issue #2159)
+
+---
+
 ## EmptyState
 
 ![EmptyState](../previews/feedback-status-emptystate.webp)

package/docs/components/form-fields.md

@@ -1700,6 +1700,37 @@ import { AttributesFormField } from '@nxgt/material/components';
 <AttributesFormField control={control} name="attributes" label="Attributes" />
 ```
 
+**`AttributeValuesFormFieldSet`** renders one input per attribute and writes
+`{ [attribute.name]: value }` to the form at `name`:
+
+```tsx
+import { AttributeValuesFormFieldSet, FormSection } from '@nxgt/material/components';
+
+const form = useForm({ defaultValues: { attributes: { color: '#2563eb', size: 'M' } } });
+
+<FormSection title="Attributes">
+  <AttributeValuesFormFieldSet
+    control={form.control}
+    name="attributes"
+    label="Attributes"
+    hideLabel
+    attributes={[
+      { name: 'color', label: 'Colour', type: 'COLOR' },
+      { name: 'size', label: 'Size', type: 'SELECT', options: ['S', 'M', 'L'] },
+    ]}
+  />
+</FormSection>
+```
+
+| Prop | |
+| --- | --- |
+| `attributes` | the attributes to fill, one input each |
+| `control`, `name` | the form and the path of the object it writes |
+| `label` | the fieldset's accessible name (required) |
+| `hideLabel` | default `false`. `true` keeps `label` as the name but draws nothing, for a `FormSection` that already has the title |
+| `defaultValues` | optional fallback, used only while the form value at `name` is empty: `undefined`, `null` or an object with no keys (`{}`). Any other value in the form wins |
+| `className` | on the `<fieldset>` |
+
 **The inline editor** is one row per attribute: a grip, the type's icon, the
 label with `name · Type` under it, the unit as a badge and the default value
 (a Yes or No, a colour swatch, a number with its unit). A row opens to its
@@ -1811,7 +1842,10 @@ const schema = z.object({ attributes: attributesListSchema() });
 
 **Emits:** `Attribute[]`; the inline editor writes a date as `yyyy-MM-dd`, a
 date-time as an ISO instant and a time as `HH:mm`. `AttributeValuesFormFieldSet`
-writes an object keyed by attribute `name`; `AttributeValuesForm` reads a bare
+writes an object keyed by attribute `name`, reads the form's value at `name`
+(`defaultValues` is only the fallback while it holds nothing), fills the row
+width, and takes `hideLabel` to keep `label` as the fieldset's accessible name
+without drawing the heading; `AttributeValuesForm` reads a bare
 `yyyy-MM-dd` default as that local day.
 **Form wrapper:** `AttributesFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair), [what each field emits](../guides/forms.md#what-each-field-emits)
@@ -1863,6 +1897,32 @@ The editor checks the shape of a value, not that the line exists. Below 640px
 each contact is a summary row; tapping it opens a bottom sheet with the same
 fields and actions, and closing it with an empty value drops the contact.
 
+**Limit the types, hide the star.** A backend that stores only some types, or
+no primary flag, says so on `ContactsFormField` and `ContactsEditor` (`primary` is inline only):
+
+```tsx
+<ContactsFormField
+  control={control}
+  name="contacts"
+  label="Contacts"
+  types={['EMAIL', 'PHONE', 'FAX', 'WEBSITE']}
+  primary={false}
+/>
+```
+
+`types` (an array of `ContactTypeName`, i.e. `'EMAIL' | 'PHONE' | …` or the
+`ContactType` values; every type by default) limits the "Add" chips and the
+type select; list at least one type, since an empty `types={[]}` is not
+supported. The chips keep the library's order (phone, mobile, email,
+website, fax); the select follows the order given. With `editing="dialog"`,
+`types` limits the dialog's type select (`ContactDialog` takes it too, and a
+new contact starts with the first type); `primary` has no effect there, since
+the dialog has no star. A contact
+already in the value with another type is kept and shown, and its own type
+stays in its select, so nothing is changed silently. `primary={false}` (`true`
+by default) hides the star and the primary marks; a `primary` flag already in
+the value is left untouched.
+
 `variant="cards"` is the Expressive variant: each contact is its own tinted
 card with a round tile for the primary one. The fields keep the library's
 field radius in both. `variant` is on `ContactsFormField`, `ContactsEditor`
@@ -1895,9 +1955,9 @@ only, and a value that fails its check is shown without a link.
 | `empty` | `ReactNode` | "No contacts" | shown when there is nothing to list; `null` renders nothing |
 
 `ContactsEditor` takes `value`, `onValueChange`, `label`, `headingLevel` (`3`
-by default; the type headings sit one below it), `variant` and `disabled`. A
+by default; the type headings sit one below it), `variant`, `types`, `primary` and `disabled`. A
 wrong format is said once the field was left, a duplicate at once. `ContactsFormField` takes `editing` (`'inline' \| 'dialog'`,
-default `'inline'`), `variant` (inline only) and `cancelVariant` (dialog only,
+default `'inline'`), `variant` (inline only), `types`, `primary` (inline only) and `cancelVariant` (dialog only,
 the Cancel button's `Button` variant, default `'tonal'`; `'outlined'` restores
 the earlier look). `Contacts` takes `data`, `onAdd`, `onEdit` and `disabled`.
 

package/docs/components/media-and-files.md

@@ -78,12 +78,15 @@ function Attachments() {
 | `mode` | `'single' \| 'multiple'` | — (required) | `value` is a `string` or a `string[]` |
 | `onUpload` | `(file, onProgress?, signal?) => Promise<string>` | — | `NetworkUploadField` only; the resolved string becomes the value. Removing an uploading row or unmounting the field aborts `signal`: pass it to your request, or the upload still completes (its value is dropped). An abort after the request completed cannot unsend it: the value is dropped and `onRemove` is not called. The S3 fields abort their request themselves and reject with an `UploadError` of kind `aborted` (named `AbortError`, no longer a `DOMException`) |
 | `getPresignedUrl` | `(file) => Promise<PresignedUploadTarget>` | — | `S3UploadField` only; `{ uploadUrl, publicUrl, headers? }` PUTs the file and stores `publicUrl`; `{ method: 'POST', url, fields, value }` posts a form and stores `value` (see [presigned POST](#presigned-post)) |
-| `accept` | `string` | — | file input `accept`, also shown under the drop zone |
+| `accept` | `string` | — | file input `accept`; the drop zone's hint shows it as short names (`image/jpeg,image/png` reads `JPEG, PNG`, `.pdf` reads `PDF`, `image/*` reads `Images`; unknown entries stay as given) |
+| `acceptLabel` | `string` | — | replaces those names in the hint (`"Photos only"`); `""` hides the type part. |
 | `maxSize` | `number` (bytes) | — | larger files are rejected before upload |
 | `maxFiles` | `number` | — | `mode="multiple"` only; the drop zone is disabled once reached |
 | `onRemove` | `(value) => void \| Promise<void>` | — | called when a committed file is removed (delete it server-side here) |
 | `resolveUrl` | `(value) => string \| null \| undefined` | — | turns a stored key into an `<img src>` so saved images preview |
 
+The drop zone's hint wraps in a narrow dialog instead of being clipped.
+
 The field is a `group` named by its `label`. The drop zone is a `button`, which
 may not carry `aria-invalid`: with `error` it is described by `helperText`, or
 without one by a visually hidden "This value is not valid."

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

@@ -17,6 +17,7 @@ documentation-site shell. Everything is imported from
 | <img src="../previews/navigation-layout-listdetailslayout.webp" width="96" alt=""> | [ListDetailsLayout, PaneLayout, ThreadLayout](#listdetailslayout) | Page layouts that adapt to phones |
 | <img src="../previews/navigation-layout-responsivegrid.webp" width="96" alt=""> | [ResponsiveGrid](#responsivegrid) | Container-query grid, 1 to 5 columns, or `auto-fill` columns by a minimum tile width (`minItem`) |
 | <img src="../previews/navigation-layout-sectioncolumns.webp" width="96" alt=""> | [SectionColumns](#sectioncolumns) | Short page sections side by side from a viewport breakpoint, stacked below it |
+| <img src="../previews/navigation-layout-recordpage.webp" width="96" alt=""> | [RecordPage, RecordDetails](#recordpage) | The page of one record: header card, content, facts as a side panel from `xl` |
 | <img src="../previews/navigation-layout-resizable.webp" width="96" alt=""> | [ResizableGroup](#resizablegroup) | Resizable panels |
 | <img src="../previews/navigation-layout-skiplink.webp" width="96" alt=""> | [SkipLink](#skiplink) | Skip-to-content link |
 | <img src="../previews/navigation-layout-pager.webp" width="96" alt=""> | [Pager](#pager) | Previous / next cards |
@@ -574,6 +575,63 @@ props, so `className` adds to it.
 
 ---
 
+## RecordPage
+
+![RecordPage](../previews/navigation-layout-recordpage.webp)
+
+The page of one record (an item, a place, a person): a header card, the content, and the record's facts as a side panel from `xl` that stacks after the content, or before it, below. `RecordDetails` is the facts card that goes in the panel.
+
+```tsx
+import { Badge, Button, Card, CardContent, Description, RecordDetails, RecordPage } from '@nxgt/material/components';
+
+<RecordPage
+  title="Torque wrench 3/8"
+  actions={<Button>Edit</Button>}
+  details={
+    <RecordDetails
+      title="Details"
+      status={<Badge>Active</Badge>}
+      created={{ label: 'Added on', at: item.createdAt }}
+      updated={{ label: 'Updated on', at: item.updatedAt }}
+      timeZone="Europe/Paris"
+    >
+      <Description label="Code">TW-3804</Description>
+      <Description label="Category">Hand tools</Description>
+    </RecordDetails>
+  }
+  detailsLabel="Item details"
+  detailsStack="after"
+>
+  <Card><CardContent>…</CardContent></Card>
+</RecordPage>
+```
+
+`RecordPage` is [`ActivityContent`](#activitylayout) with the side panel's props renamed, so `title`, `subtitle`, `actions`, `header`, `notice`, `width`, `inset` and `titleAs` work as there. It adds no data, state or request.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `details` | `ReactNode` | — | The facts, usually a `RecordDetails`. No panel without it |
+| `detailsLabel` | `string` | — | The panel's accessible name: it is a `complementary` landmark. Or `detailsLabelledBy`, the id of a heading inside it |
+| `detailsStack` | `'before' \| 'after'` | `'after'` | Where the panel goes below `asideFrom` |
+| `detailsClassName` | `string` | — | Classes for the panel |
+| `asideFrom`, `asideWidth`, `asideSticky` | as on `ActivityContent` | `xl`, `md`, `true` | The breakpoint, the panel's width and the sticky offset |
+
+`RecordDetails` props:
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `title`, `titleAs` | `ReactNode`, heading | —, `'h2'` | The card's heading (under the page's `h1`) |
+| `status` | `ReactNode` | — | Beside the title: a `Badge` or `StatusIndicator` |
+| `created`, `updated` | `{ label: string; at: Date \| string \| number }` | — | The two segments of the muted meta line; each « label date » stays on one line |
+| `timeZone` | IANA zone | `'UTC'` | The zone the dates are written in, the same on a server and in a browser. Dates have no seconds and no zone suffix |
+| `maxColumns` | `1`-`6` | `4` | The most columns of the facts: the panel's own width gives one, a stacked and wide panel up to this |
+
+The facts are a [`DescriptionList`](data-display.md#descriptionlist), so the columns follow the card's width, not the window's.
+
+**Storybook:** `Navigation & layout/RecordPage` · **Vue:** later ([#2127](https://github.com/softistx/nxgt-material/issues/2127))
+
+---
+
 ## ResizableGroup
 
 ![ResizableGroup](../previews/navigation-layout-resizable.webp)

package/docs/components/overlays-and-menus.md

@@ -61,10 +61,27 @@ Your own `onEscapeKeyDown` on the content receives the Escape that only closes a
 >
 ```
 
+**A long dialog scrolls its body, not the whole box.** Wrap the fields in `DialogBody` (a direct child of `DialogContent`, between `DialogHeader` and `DialogFooter`): the content becomes a clipped column, the header and the footer stay in view, and only the body scrolls. A hairline shows on the edge where content is hidden beneath the header or the footer. It works the same as a bottom sheet or full screen on a phone, with the safe-area padding kept under the footer. A dialog without `DialogBody` is unchanged and scrolls as a whole. Give the body an `aria-label` (or `aria-labelledby`) to make it a named region; `className` sets its inner layout (`grid gap-3`). It sets `data-overflow-start` and `data-overflow-end` while content is hidden above or below. `DialogScrollContent`, `Sheet`, `Drawer` and `AlertDialog` do not take it yet.
+
+```tsx
+<DialogContent>
+	<DialogHeader>
+		<DialogTitle>New item</DialogTitle>
+	</DialogHeader>
+	<DialogBody aria-label="Item fields" className="grid gap-3">
+		{/* twelve fields */}
+	</DialogBody>
+	<DialogFooter>
+		<Button>Save</Button>
+	</DialogFooter>
+</DialogContent>
+```
+
 ```tsx
 import {
 	Button,
 	Dialog,
+	DialogBody,
 	DialogClose,
 	DialogContent,
 	DialogDescription,
@@ -94,7 +111,8 @@ import {
 ```
 
 Parts: `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`,
-`DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogClose`, plus
+`DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogBody` (the part
+that scrolls alone), `DialogClose`, plus
 `DialogOverlay` and `DialogPortal`, and `DialogScrollContent`: a content for
 a dialog taller than the screen, which sits in a scrolling overlay with a
 margin instead of being clipped, and renders its own close button. It takes
@@ -132,6 +150,7 @@ export function Terms() {
 | `variant`, `color` (`DialogClose`) | as `IconButton` | `'ghost'` | a top-right X button, named "Close" (`material.buttons.close`, translated) while it shows only the icon; text children or an `aria-label` name it instead, and icon-only children leave it unnamed; children replace the X |
 | `size` (`DialogContent`) | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | its width from 640 px up: 384, 512, 672, 896 px, or the screen less 2rem a side |
 | `mobilePresentation` (`DialogContent`) | `'dialog' \| 'bottom-sheet' \| 'top' \| 'fullscreen'` | `'dialog'` | below 640 px: a centred dialog, a sheet that springs up from the bottom edge (rounded top corners), a dialog pinned under the top edge, or the whole screen |
+| `className`, `aria-label` / `aria-labelledby`, `onScroll`, `ref` (`DialogBody`) | `ComponentProps<'div'>` | — | the scroll region: `className` lays out its content (`grid gap-3`); an `aria-label` or `aria-labelledby` makes it a `region` with that name; `onScroll` and `ref` are called after its own overflow flags update. It sets `data-overflow-start` / `data-overflow-end` while content is hidden above / below, and bleeds by `--dialog-px` (1.5rem) so a `DialogContent` with its own padding sets both: `p-4 [--dialog-px:1rem]` |
 | `scrim` (`DialogContent`, `SheetContent`, `DrawerContent`) | `'dim' \| 'blur'` | `'dim'` | the scrim behind; `blur` also blurs the page a little |
 
 The look lives in the stylesheet (`nxgt-dialog`, `nxgt-scrim`), under the

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` |

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