@nxgt/material 3.68.0 → 3.71.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

@@ -19,6 +19,7 @@ for the value type each one writes. Everything is imported from
 | <img src="../previews/form-fields-passwordfield.webp" width="96" alt=""> | [PasswordField](#passwordfield) | Show / hide toggle and a strength meter |
 | <img src="../previews/form-fields-numberfield.webp" width="96" alt=""> | [NumberField](#numberfield) | `number \| null` with clamping and +/− buttons |
 | <img src="../previews/form-fields-percentfield.webp" width="96" alt=""> | [PercentField](#percentfield) | `NumberField` with a `%` suffix |
+| <img src="../previews/form-fields-quantityfield.webp" width="96" alt=""> | [QuantityField](#quantityfield) | One labelled field holding an amount and its unit |
 | <img src="../previews/form-fields-currencyfield.webp" width="96" alt=""> | [CurrencyField](#currencyfield) | Locale-formatted amount with a currency suffix |
 | <img src="../previews/form-fields-phonefield.webp" width="96" alt=""> | [PhoneField](#phonefield) | International number, emits E.164 |
 | <img src="../previews/form-fields-urlfield.webp" width="96" alt=""> | [UrlField](#urlfield) | Validates on blur, open and copy buttons |
@@ -610,6 +611,79 @@ ratio (`0.15`).
 
 ---
 
+## QuantityField
+
+![QuantityField](../previews/form-fields-quantityfield.webp)
+
+One labelled field holding an amount and its unit ("2 capsule", "500 mg"): a
+[`NumberField`](#numberfield)'s number beside a unit picker, under one label
+and one error message. The value is `{ value: number | null, unit: string }`.
+`QuantityFormField` wires it to react-hook-form.
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { Button, QuantityFormField } from '@nxgt/material/components';
+import type { QuantityValue } from '@nxgt/material/components';
+
+type Values = { dose: QuantityValue };
+
+function DoseForm() {
+  const { control, handleSubmit } = useForm<Values>({
+    defaultValues: { dose: { value: null, unit: '' } },
+  });
+  return (
+    <form onSubmit={handleSubmit((values) => console.log(values.dose))}>
+      <QuantityFormField
+        control={control}
+        name="dose"
+        label="Dose"
+        min={0}
+        step={0.5}
+        units={[
+          { value: 'mg', label: 'mg' },
+          { value: 'ml', label: 'mL' },
+        ]}
+      />
+      <Button type="submit">Save</Button>
+    </form>
+  );
+}
+```
+
+Without a form library, `QuantityField` takes `value` and `onChange` (or
+`defaultValue`). The number is the one `NumberField` has: the language's
+decimal separator, `min`, `max` and `step` (clamped on blur), and steppers
+named after the field ("Increase Dose"). Both parts stay on one line on a
+phone: the number shrinks, the unit keeps a fixed 7rem.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `control`, `name` | `Control<T>`, `Path<T>` | — | the form and its `{ value, unit }` (`QuantityFormField`) |
+| `value`, `defaultValue`, `onChange` | `QuantityValue`, `(value) => void` | empty | the amount and its unit; `onChange` gets both on each change |
+| `label` | `ReactNode` | none | the one label; it names the group |
+| `units` | `{ value, label }[]` | none | the units offered |
+| `allowCustomUnit` | `boolean` | `false` | the unit is typed in a text input and `units` are suggestions; otherwise it is picked from `units` |
+| `min`, `max`, `step`, `hideSteppers` | | `step` 1 | as `NumberField` |
+| `unitLabel`, `unitPlaceholder` | `string` | "<label> unit" | the unit part's accessible name and its placeholder |
+| `helperText`, `error` | `ReactNode`, `boolean` | none | the one message under the pair; in a form, an error on `name`, `name.value` or `name.unit` shows there |
+| `className`, `aria-label` | `string` | none | `className` goes on the group; `aria-label` names it when `label` is not plain text |
+| `name`, `onBlur` | | none | `QuantityField` only (the form field takes them from the form): `name` names the parts `<name>.value` and `<name>.unit`; `onBlur` fires when the number input loses focus |
+| `required`, `disabled`, `placeholder`, `id`, `ref` | | | `placeholder`, `id` and `ref` reach the number input (React Hook Form's `field.ref` focuses it on an error) |
+
+- **Semantics:** a `<fieldset>` (role `group`) named by the label; the number
+  is a textbox named after the label, the unit a combobox (or, with
+  `allowCustomUnit`, a text input) named "Dose unit". The message describes
+  the group, the number and the unit, and both are `aria-invalid` on an error.
+- **Translations:** `material.quantity-field.unit` and `.unit-named` (English
+  and French) name the unit part.
+
+**Emits:** `{ value: number | null, unit: string }`.
+**Form wrapper:** `QuantityFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/QuantityField` · **Vue:** none yet (#2106)
+
+---
+
 ## CurrencyField
 
 ![CurrencyField](../previews/form-fields-currencyfield.webp)
@@ -665,9 +739,19 @@ export function Mobile() {
 | `value` / `defaultValue` | `string \| null` | `null` | an E.164 number (`+33612345678`) |
 | `onChange` | `(value: string \| null) => void` | — | `null` until the typed number is possible for the country |
 | `defaultCountry` | `string` (ISO 3166-1) | `'FR'` | the country used when the value has no `+` prefix |
-
-**Emits:** E.164 `string`, or `null` while the number is incomplete.
-**Form wrapper:** `PhoneFormField` — `control` and `name`, see
+| `onValidityChange` | `(incomplete: boolean) => void` | — | `true` while the draft is not empty but not yet a possible number (`onChange` gives `null` for it, as for an empty field); `false` once it is complete or empty. Fires before the matching `onChange`; not called while the field has never been incomplete |
+
+**Emits:** E.164 `string`, or `null` while the number is empty or incomplete.
+Outside a form, tell the two apart with `onValidityChange` (or
+`isIncompletePhone(draft, iso)`).
+**Form wrapper:** `PhoneFormField` — `control` and `name`; an empty field is
+`null`, and a half-typed number is a field error « Incomplete number »
+(`material.phone-field.incomplete`, « Numéro incomplet » in French) that blocks
+the submit, so a stored number is never cleared silently. `PhoneFormField` takes `rules`: your own `rules.validate` (a function or an
+object of them) runs beside the incomplete check, as its `custom` key for a
+function. A `rules.required` is checked first by React Hook Form, so a half-typed
+number reads as the required message there. A form `reset()` to `null` does not clear a half-typed draft (the
+value did not change), so an incomplete draft stays an error until it is edited. See
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
 **Storybook:** `Form fields/PhoneField` (and `/Field look`) · **Vue:** `PhoneField`, `PhoneFormField`
 
@@ -1870,6 +1954,16 @@ Parts: `PostalAddress` (the card), `PostalAddressDialog` (the edit form).
 | `onEdit` | `() => void` | — | shows the edit button |
 | `disabled` | `boolean` | — | hides it |
 
+**One line and country codes:** `formatPostalAddress(address, { language?, separator? })`
+returns the address as one line for a read view, `"12 rue du Lac, 74000 Annecy, France"`:
+street, city line, then the country named in `language` (default `'en'`, as
+`postalAddressCountryName`). The city line puts the postal code before the city
+(FR, BE, CH, DE and any other country) or after the city and region (GB, US, CA,
+IE, AU, NZ, IN: `"London SW1A 2AA"`). Empty parts are skipped; `separator`
+defaults to `', '`. `ISO_COUNTRY_CODES` (the 249 ISO 3166-1 alpha-2 codes) and
+`isCountryCode(code)` (a guard to `string`, upper case only) are exported from
+`@nxgt/material/components` too.
+
 `PostalAddressFormField` and `PostalAddressDialog` take `cancelVariant` (the
 dialog's Cancel button, a `Button` `variant`, default `'tonal'`; `'outlined'`
 restores the earlier look).

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

@@ -65,9 +65,10 @@ function Attachments() {
 <NetworkUploadField
   mode="single"
   label="Contract"
-  onUpload={async (file, onProgress) => {
+  onUpload={async (file, onProgress, signal) => {
+    const res = await fetch('/api/files', { method: 'POST', body: file, signal });
     onProgress?.(100);
-    return `https://files.example.com/${file.name}`;
+    return (await res.json()).url;
   }}
 />;
 ```
@@ -75,8 +76,8 @@ function Attachments() {
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `mode` | `'single' \| 'multiple'` | — (required) | `value` is a `string` or a `string[]` |
-| `onUpload` | `(file, onProgress?) => Promise<string>` | — | `NetworkUploadField` only; the resolved string becomes the value |
-| `getPresignedUrl` | `(file) => Promise<{ uploadUrl, publicUrl, headers? }>` | — | `S3UploadField` only; PUTs the file to `uploadUrl`, stores `publicUrl` |
+| `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 |
 | `maxSize` | `number` (bytes) | — | larger files are rejected before upload |
 | `maxFiles` | `number` | — | `mode="multiple"` only; the drop zone is disabled once reached |
@@ -95,9 +96,51 @@ description instead, so the error is still said: with `error` and that
 group, so to set files in a test, reach the input through it:
 `getByRole('group', { name: 'Contract' }).locator('input[type=file]')`.
 
+### Presigned POST
+
+A backend that signs a POST policy (so the bucket enforces content type and
+size) returns `{ method: 'POST', url, fields, value }`. The field sends
+`multipart/form-data` with `fields` in their order and the file appended last
+under the name `file`, then stores `value` (the key). The same target works for `S3UploadFormField`,
+`ImageS3Field`, `ImageS3FormField`, `FileListS3Field` and `FileListS3FormField`;
+the PUT shape stays valid. Progress, retry, cancel and errors behave as for a PUT.
+
+```tsx
+<S3UploadFormField
+  control={control}
+  name="file"
+  label="Contract"
+  getPresignedUrl={async (file) => {
+    const { url, fields, key } = await api.presignPost({ name: file.name, contentType: file.type });
+    return { method: 'POST', url, fields, value: key }; // fields exactly as signed
+  }}
+/>
+```
+
+A refused policy (`403`, or `400 EntityTooLarge`) reaches `onError(file, error)`
+and the field's error state; when S3 answers with its XML error, the message
+carries the code. The S3 helpers reject with an `UploadError` (`kind`:
+`status` | `network` | `aborted`, plus `status` and `code`), and the field words
+it in the active language from `material.upload.error-status`,
+`error-status-code`, `error-network` and `error-aborted` (`Échec de l'envoi
+(statut 400, EntityTooLarge)` in French). `error.message` stays English, for
+logs. An error thrown by your own `onUpload` or `getPresignedUrl` is not an
+`UploadError`: its `message` is shown as is, so translate it yourself. A stored
+`value` that is a key needs `resolveUrl` to preview it.
+
+The bucket must allow the browser to POST from your origin:
+
+```json
+[{ "AllowedOrigins": ["https://app.example.com"], "AllowedMethods": ["POST"], "AllowedHeaders": ["*"] }]
+```
+
+If the app sends a `Content-Security-Policy`, add the bucket host to
+`connect-src` (uploads use `XMLHttpRequest`), for example
+`connect-src 'self' https://my-bucket.s3.eu-west-1.amazonaws.com`.
+
 **Form wrapper:** `S3UploadFormField`, `NetworkUploadFormField` — `control` and `name`, see
 [forms](../guides/forms.md).
-**Storybook:** `Media & files/S3UploadField`, `Media & files/NetworkUploadField` · **Vue:** `S3UploadField`, `NetworkUploadField`, `S3UploadFormField`, `NetworkUploadFormField`
+**Storybook:** `Media & files/S3UploadField`, `Media & files/NetworkUploadField` · **Vue:** `S3UploadField`, `NetworkUploadField`, `S3UploadFormField`, `NetworkUploadFormField` (PUT only, #2095)
 
 ---
 
@@ -199,7 +242,9 @@ function Attachments() {
 ```
 
 Parts: `FileList` (display only), `FileListField` (uploads through `onUpload`),
-`FileListS3Field` (uploads through `getPresignedUrl`, like `S3UploadField`).
+`FileListS3Field` (uploads through `getPresignedUrl`, like `S3UploadField`;
+with a POST target the value is `value`, a key, so pass `resolveUrl` to preview
+saved images).
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
@@ -224,7 +269,7 @@ dropzone as well read the error twice, and the group still says it once
 `maxFiles` hides the dropzone. The dropzone is outlined through `data-invalid`.
 
 **Form wrapper:** `FileListFormField`, `FileListS3FormField` — see [forms](../guides/forms.md).
-**Storybook:** `Media & files/FileList`, `Media & files/FileListField` · **Vue:** `FileList`, `FileListField`, `FileListS3Field`, `FileListFormField`, `FileListS3FormField`
+**Storybook:** `Media & files/FileList`, `Media & files/FileListField` · **Vue:** `FileList`, `FileListField`, `FileListS3Field`, `FileListFormField`, `FileListS3FormField` (S3 variants PUT only, #2095)
 
 ---
 
@@ -364,7 +409,8 @@ function Avatar() {
 ```
 
 Parts: `ImageField` (uploads through `onUpload`), `ImageS3Field` (through
-`getPresignedUrl`).
+`getPresignedUrl`; with a POST target the value is `value`, a key, so pass
+`resolveUrl` to preview saved images).
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
@@ -389,7 +435,7 @@ with no message of its own, by a visually hidden "This value is not valid."
 (`material.zod.default`, translated), and outlined through `data-invalid`.
 
 **Form wrapper:** `ImageFormField`, `ImageS3FormField` — see [forms](../guides/forms.md).
-**Storybook:** `Media & files/ImageField` · **Vue:** `ImageField`, `ImageS3Field`, `ImageFormField`, `ImageS3FormField`
+**Storybook:** `Media & files/ImageField` · **Vue:** `ImageField`, `ImageS3Field`, `ImageFormField`, `ImageS3FormField` (S3 variants PUT only, #2095)
 
 ---
 

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)