@nxgt/material 3.100.1 → 3.103.0

package/docs/README.md

@@ -11,6 +11,7 @@ detail: every option, the second example, and the traps.
 | [Themes for your app](guides/themes.md) | You define your own themes: `defineTheme` modules, the Vite plugin's `themes` option, the `nxgt-theme` command and its CI check, the tone warnings |
 | [Barcodes and label sheets](guides/barcode.md) | You draw a Code 128 or Data Matrix code and print a sheet of labels with `@nxgt/material/barcode`: `Barcode`, `LabelSheet` and `Label`, label size, columns, rows, gaps and a start offset, dark mode, print and accessibility |
 | [Calculator](guides/calculator.md) | You add an exact-decimal calculator with `@nxgt/material/calculator` (and `CalculatorField` with `@nxgt/material/calculator-field`): `Calculator`, the keyboard, the tape and memory, copy and paste, what is stored, feedback, sizing and accessibility |
+| [Keypad](guides/keypad.md) | You add a numeric keypad outside the calculator with `@nxgt/material/keypad`: quantity, price, percentage and cash-tendered entry, decimal or minor-unit digits, calculation keys, field bindings (`useKeypadNumber`, `useKeypadQuantity`), the cash variant with change and bill shortcuts, the keyboard and accessibility |
 | [Charts](guides/charts.md) | You draw charts with `@nxgt/material/charts`: each chart, the shared props, reference bands, thresholds and point tones, zoom and phone scroll, the keyboard, accessibility, theming the `--chart-1..5` tokens, and moving off the Nivo charts, removed in 3.0 |
 | [Cards and tiles](guides/cards-and-tiles.md) | You want a `DataTable` as a list of cards or tiles: `layout`, `renderCard`, `renderTile`, the card's one link, selection, the sort control, columns by the list's width |
 | [EventCalendar](guides/event-calendar.md) | You mark periods with `spans`, label days and weeks with `dayBadges` and `weekBadges`, colour events with `tone`, cancel them with `status`, or make them read-only with `readOnlyEvents` |

package/docs/components/README.md

@@ -65,6 +65,7 @@ Picking among options: select, combobox, autocomplete, checkbox, radio, card and
 [<img src="../previews/selection-choice-autocomplete.webp" height="72" alt="Autocomplete">](selection-and-choice.md#autocomplete)
 [<img src="../previews/selection-choice-choicecardgroup.webp" height="72" alt="ChoiceCardGroup">](selection-and-choice.md#choicecardgroup)
 [<img src="../previews/selection-choice-transferlist.webp" height="72" alt="TransferList">](selection-and-choice.md#transferlist)
+[<img src="../previews/selection-choice-statusmenu.webp" height="72" alt="StatusMenu">](selection-and-choice.md#statusmenu)
 
 ## [Data display](data-display.md)
 

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

@@ -1199,7 +1199,7 @@ import { Banknote, CreditCard } from 'lucide-react';
 | `title`, `description`, `icon` | `ReactNode` | — | the content |
 | `status` | `ReactNode` | — | a line under the title; a string or number becomes a soft `Badge`, a node is shown as given |
 | `meta` | `ReactNode` | — | a secondary line, one line with an ellipsis |
-| `action` | `ReactNode` | — | a trailing control outside the press surface, see [tile](#actioncard-tile); `title` is then required, a `role` moves to the title button; the card's `disabled` does not reach it, disable its control too |
+| `action` | `ReactNode` | — | a trailing control outside the press surface, see [tile](#actioncard-tile); `title` is then required, a `role` moves to the title button; the card's `disabled` does not reach it, disable its control too; in a `tile` it wraps under a narrow title |
 
 A card with `active`, `onClick`, `disabled` or your own `role` is `role="button"` (unless you set another): it takes the Tab stop, and
 Enter and Space press it. `active` sets `aria-pressed`; pass your own `role`
@@ -1218,7 +1218,39 @@ For a card choice bound to a form value, see `ChoiceCardGroup` on
 `variant="tile"` is a compact grid cell for boards: no minimum width (it fills
 its grid track), the title and the `action` on the first row, then `status`,
 `description` and `meta`, and no indicator unless `withIndicator`. `status` and
-`meta` work on every variant.
+`meta` work on every variant. The `action` wraps under a narrow title instead of
+overflowing the tile.
+
+A status that changes in place is a [`StatusMenu`](selection-and-choice.md#statusmenu)
+in `action`: the chip shows the status (so the card needs no `status` badge) and
+opens the choices, in a bottom sheet on a phone. Its button is named "Status of
+Unit 21: Free". The chip is 6 to 10rem wide (a long status word is wider). A tile
+with an `action` is a wrapping line: the title may shrink to 4.5rem
+(`--ac-title-min`), and an action that does not fit beside it drops under the
+title, so a chip fits in a two-per-row `xs` grid on a 360px phone and an icon
+button such as `RowMenu` stays beside the title. A wrapped action starts at the tile's line start (under the icon when the tile
+has one), not under the title text.
+
+```tsx
+import { ActionCard, StatusMenu } from '@nxgt/material/components';
+
+<ActionCard
+	variant="tile"
+	title="Unit 21"
+	meta="Zone B, second floor"
+	onClick={() => openDetail(unit.id)}
+	action={
+		<StatusMenu
+			label="Unit 21"
+			value={unit.status}
+			choices={statuses}
+			onSelect={(next) => saveStatus(unit.id, next)} // a promise keeps the old status with a spinner
+		/>
+	}
+/>;
+```
+
+A compact icon-button action, with a `status` badge, uses `RowMenu`:
 
 ```tsx
 import {

package/docs/components/data-display.md

@@ -1652,7 +1652,7 @@ The colour shows as a thin accent bar inset from the chip's edges (never a borde
 
 ![CodeBlock](../previews/data-display-codeblock.webp)
 
-Highlighted code with line numbers and copy, a collapsible JSON tree, and tabbed samples (`Tabs`, underlined).
+Highlighted code (or plain text) with line numbers and copy, a collapsible JSON tree, and tabbed samples (`Tabs`, underlined).
 
 <img src="../previews/data-display-codegroup.webp" height="96" alt="CodeGroup">
 <img src="../previews/data-display-jsonviewer.webp" height="96" alt="JsonViewer">
@@ -1661,6 +1661,7 @@ Highlighted code with line numbers and copy, a collapsible JSON tree, and tabbed
 import { CodeBlock, CodeGroup, JsonViewer } from '@nxgt/material/components';
 
 <CodeBlock code={source} language="typescript" filename="greet.ts" highlightLines={[2]} />
+<CodeBlock code={dnsRecord} language="text" label={false} />
 <CodeGroup tabs={[
   { label: 'bun', language: 'bash', code: 'bun add @nxgt/material' },
   { label: 'npm', language: 'bash', code: 'npm i @nxgt/material' },
@@ -1671,6 +1672,8 @@ import { CodeBlock, CodeGroup, JsonViewer } from '@nxgt/material/components';
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `scheme` | `'dark' \| 'light'` | follows the theme | forces the palette (all three) |
+| `language` | `string` | `typescript` | `CodeBlock`: one of 16 ids or aliases, or `text` (also `plaintext`, `plain`, `txt`) to show the code as is, labelled "Text". An unknown id still falls back to `typescript` |
+| `label` | `ReactNode \| false` | the language's name | `CodeBlock`: replaces the language label; `false` hides it |
 | `showLineNumbers` | `boolean` | `true` | `CodeBlock`, `CodeGroup` |
 | `highlightLines` | `number[]` | — | `CodeBlock`: marked lines |
 | `maxHeight` | `number \| string` | — | `CodeBlock`, `JsonViewer`: scrolls past it |

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

@@ -250,6 +250,8 @@ function DeleteProject({ onDelete }: { onDelete: () => Promise<void> }) {
 | `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 |
+| `confirmPhrase` | `string` | — | asks the user to type this text before Confirm enables, for a deletion worth a second thought. A field labelled by the translated `material.confirm-dialog.type-phrase` ("Type {phrase} to confirm", the phrase in code style) takes the focus on open instead of Cancel and starts empty each time the dialog opens. Paste is allowed; Enter in the field confirms only once it matches. It combines with `confirmDisabled` (both must allow). Empty or unset: no field |
+| `confirmPhraseMatch` | `'exact' \| 'trim' \| 'trim-case-insensitive'` | `'exact'` | how the typed text is compared: character for character, ignoring spaces around it, or ignoring those and the letter case |
 | `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 |
 
@@ -269,6 +271,38 @@ function DeleteProject({ onDelete }: { onDelete: () => Promise<void> }) {
 />
 ```
 
+**Type the value to confirm.** For a deletion that should not happen by habit (a domain, a mailbox), ask for the name:
+
+```tsx
+<ConfirmDialog
+  open={open}
+  onOpenChange={setOpen}
+  variant="destructive"
+  title="Delete example.com?"
+  description="Its mailboxes are deleted with it."
+  confirmLabel="Delete"
+  confirmPhrase="example.com"
+  confirmPhraseMatch="trim-case-insensitive"
+  onConfirm={remove}
+/>
+```
+
+`ConfirmDialog` has no form; `ConfirmationDialog` (with `formOptions`) does not take `confirmPhrase`. The Vue twin does not have it yet.
+
+**The text stays while the dialog fades out.** A confirm is usually driven by a nullable subject, and closing clears it: `open={item !== null}`. `ConfirmDialog` keeps the `title`, `description`, `details`, button labels and `variant` of its last open render until it has closed, so the title does not read "Delete ?" during the exit animation. Nothing to add in the app:
+
+```tsx
+<ConfirmDialog
+  open={item !== null}
+  onOpenChange={(o) => !o && setItem(null)}
+  title={`Delete ${item?.name ?? ''}?`}
+  description="This cannot be undone."
+  onConfirm={remove}
+/>
+```
+
+For a dialog you build yourself (`Dialog`, `CustomDialog`, `ConfirmationDialog` children), read the subject through [`useLatched`](../guides/helpers.md#uselatched).
+
 **`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

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

@@ -22,6 +22,7 @@ documentation-site shell. Everything is imported from
 | <img src="../previews/navigation-layout-dashboardgrid.webp" width="96" alt=""> | [DashboardGrid, DashboardTile](#dashboardgrid) | Tiles with spans that the user rearranges in an edit mode, by drag or keyboard; the order is the app's |
 | <img src="../previews/navigation-layout-editorlayout.webp" width="96" alt=""> | [EditorLayout](#editorlayout) | The editor page: toolbar, canvas that scrolls alone, properties at the end (a bottom sheet on a phone), optional outline at the start |
 | <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-panelcard.webp" width="96" alt=""> | [PanelCard](#panelcard) | Titled card for a side panel: heading, description, header actions |
 | <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 |
@@ -1197,6 +1198,33 @@ props, so `className` adds to it.
 
 **Storybook:** `Navigation & layout/SectionColumns` · **Vue:** later ([#1614](https://github.com/softistx/nxgt-material/issues/1614))
 
+## PanelCard
+
+A titled card for the side of a page (an `ActivityContent` aside) or its sections: a heading, an optional one-line description and header actions over the content. It replaces the `Card` + `CardHeader` + `CardTitle as="h2"` + `CardDescription` + `CardContent` wrapper apps wrote themselves.
+
+```tsx
+import { PanelCard } from '@nxgt/material/components';
+
+<PanelCard
+  title="Recent activity"
+  description="The last five changes to this record."
+  actions={<Button size="sm" variant="outlined">Refresh</Button>}
+>
+  …
+</PanelCard>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` | required | The heading, and the accessible name of the card |
+| `description` | `ReactNode` | none | One line under the title |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` | The title's heading level; use `3` inside a section that already has an `h2` |
+| `actions` | `ReactNode` | none | A slot at the end of the title row (a button, a `RowMenu`) |
+
+The card is a `role="region"` labelled by its title, so `getByRole('region', { name })` finds it. Children are the card's content (`CardContent`); with none, the card is its header only. It takes the `div`'s props, so `className` adds to it.
+
+**Storybook:** `Navigation & layout/PanelCard` · **Vue:** later, [#2866](https://github.com/softistx/nxgt-material/issues/2866)
+
 ---
 
 ## RecordPage

package/docs/components/rich-widgets.md

@@ -13,6 +13,7 @@ the app owns the data.
 | <img src="../previews/rich-widgets-drawing.webp" width="96" alt=""> | [Drawing](#drawing) | Vector drawing from a scene of plain data or JSX primitives: theme colours, accessible, focusable nodes, strict-CSP safe |
 | <img src="../previews/rich-widgets-barcode.webp" width="96" alt=""> | [Barcode](#barcode) | Code 128 and Data Matrix as accessible SVG, themed and dark-aware, black on white in print, with `LabelSheet` for a printed sheet of labels |
 | <img src="../previews/rich-widgets-calculator.webp" width="96" alt=""> | [Calculator](#calculator) | Exact decimal calculator (Standard, Scientific, a point of sale, Financial, Conversion and Programmer) with the usual precedence, a shaped keypad, tape, memory, keyboard, copy and paste, and a number field whose button opens it (`CalculatorField`, in `@nxgt/material/calculator-field`), in its own entry; variants other than Standard load on demand |
+| <img src="../previews/rich-widgets-keypad.webp" width="96" alt=""> | [Keypad](#keypad) | A touch and keyboard numeric keypad for a quantity, a price, a percentage or a cash tender with change (`@nxgt/material/keypad`), decimal or minor-unit entry, field bindings, in its own entry, styled by `calculator.css` |
 | <img src="../previews/rich-widgets-emojipicker.webp" width="96" alt=""> | [EmojiPicker](#emojipicker) | Shared emoji picker and list |
 | <img src="../previews/rich-widgets-mentionlist.webp" width="96" alt=""> | [MentionList](#mentionlist) | `@` mention list with local search |
 | <img src="../previews/rich-widgets-documenteditor.webp" width="96" alt=""> | [DocumentEditor](#documenteditor) | Rich text editor for long-form writing, built on a headless core |
@@ -1012,6 +1013,33 @@ import { CalculatorField, CalculatorFormField } from '@nxgt/material/calculator-
 
 See the [calculator guide](../guides/calculator.md).
 
+## Keypad
+
+A numeric keypad from `@nxgt/material/keypad`, usable outside the Calculator:
+quantity, price, percentage and cash-tendered entry. The value is a canonical
+decimal string and the arithmetic is the calculator's exact engine. Digits go in
+as typed (`entry="decimal"`) or like a till (`entry="minor"`, `1 2 5` is `1.25`);
+`operations` adds calculation keys; `min` and `max` hold the value; the keyboard
+works when focus is in the keypad (`keyboard="global"` for a till). Its own entry,
+server-safe, styled by `@nxgt/material/calculator.css` (import it after
+`styles.css`; there is no keypad stylesheet).
+
+```tsx
+import { Keypad, useKeypadNumber } from '@nxgt/material/keypad';
+
+<Keypad value={qty} onValueChange={setQty} onCommit={(value) => addLine(value)} />
+const binding = useKeypadNumber({ value: qty, onChange: setQty, min: 1 });
+<Keypad binding={binding} />
+<Keypad variant="cash" total="17.35" denominations={[5, 10, 20, 50]} currency="EUR" onTender={pay} />
+```
+
+`useKeypadNumber` binds it to a `NumberField`, `PercentField` or `CurrencyField`
+(also with `minorUnits`), `useKeypadQuantity` to a `QuantityField`; the bound
+keypad hides its own display unless `operations` are offered. The `cash` variant shows the total, the change or
+the amount still due, bill shortcuts from `denominations`, and reports
+`onTender(tendered, settlement)`; your app owns the charge. See the
+[keypad guide](../guides/keypad.md).
+
 ## EmojiPicker
 
 ![EmojiPicker](../previews/rich-widgets-emojipicker.webp)

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

@@ -29,6 +29,7 @@ value type each one writes. Everything is imported from
 | <img src="../previews/selection-choice-sortablelist.webp" width="96" alt=""> | [SortableList](#sortablelist) | Reorderable list: drag or keyboard, announced; two-line labels, row menu |
 | <img src="../previews/selection-choice-treeselectfield.webp" width="96" alt=""> | [TreeSelectField](#treeselectfield) | Pick from a tree, single or multiple |
 | <img src="../previews/selection-choice-switcher.webp" width="96" alt=""> | [Switcher](#switcher) | Workspace, establishment or class switcher: menu, search, groups, links; `size="compact"` an icon-only round trigger for the app bar's `titleAfter` slot |
+| <img src="../previews/selection-choice-statusmenu.webp" width="96" alt=""> | [StatusMenu](#statusmenu) | A record's status as a soft chip that opens a menu (a bottom sheet on a phone) of statuses: transitions, locked, busy, read-only; `StatusMenuFormField` for forms |
 
 ## Select
 
@@ -1020,6 +1021,125 @@ on a touch screen.
 
 ---
 
+## StatusMenu
+
+![StatusMenu](../previews/selection-choice-statusmenu.webp)
+
+A record's status (a ticket, an order, a patient, a device) as a chip that
+changes it in one tap: a soft Badge pill (the tone's container, the tone's
+icon, the words, a chevron) that opens a menu of radio items. The held status
+is checked and inert. The button is named "Status of Ticket 42: Open", and
+`onSelect` never runs for the held status, for a blocked one, or when locked or
+busy.
+
+- `transitions` greys the statuses it does not reach, each saying why. A
+  terminal status needs `done: []`; unlike `useAllowedTransitions`, a missing
+  key allows every move.
+- `locked` picks nothing and shows its `reason` as a tooltip and as the menu's
+  first line.
+- `busy` keeps the old status and swaps the chevron for a spinner. A returned
+  promise does the same until it settles; a rejection is announced and sent to
+  `onError`.
+- `confirm` on a choice asks first, in a dialog.
+- `readOnly` draws a plain label, no button.
+
+On a phone (under 768px) the statuses open in a bottom sheet of 44px rows
+instead of the menu; a status that cannot be picked says why in its own row
+(touch has no tooltip). `presentation` is `'auto'` (default), `'menu'` or
+`'sheet'`.
+
+```tsx
+import { StatusMenu, type StatusChoice } from '@nxgt/material/components';
+
+const statuses: StatusChoice<'todo' | 'progress' | 'done'>[] = [
+  { value: 'todo', label: 'To do', tone: 'neutral', icon: 'circle' },
+  { value: 'progress', label: 'In progress', tone: 'info', icon: 'circle-half-stroke' },
+  { value: 'done', label: 'Done', tone: 'success', icon: 'circle-check' },
+];
+
+<StatusMenu
+  label="Ticket 42"
+  value={status}
+  choices={statuses}
+  transitions={{ done: ['progress'] }}
+  presentation="auto" // 'menu' | 'sheet' to force one
+  onSelect={(next) => setStatus(next)}
+/>;
+```
+
+Saving through a server, with a status that asks first:
+
+```tsx
+const statuses: StatusChoice<'open' | 'cancelled'>[] = [
+  { value: 'open', label: 'Open', tone: 'info' },
+  {
+    value: 'cancelled',
+    label: 'Cancelled',
+    tone: 'error',
+    confirm: { title: 'Cancel this ticket?', confirmLabel: 'Cancel ticket', destructive: true },
+  },
+];
+
+<StatusMenu
+  label="Ticket 42"
+  value={status}
+  choices={statuses}
+  onSelect={async (next) => {
+    await saveStatus(ticketId, next); // pending until it settles; a throw is announced
+    setStatus(next);
+  }}
+  onError={(error) => toast.error(String(error))}
+/>;
+```
+
+`confirm` defaults: `confirmLabel` "Confirm", `destructive` `false`, `description`
+"Change the status to {label}?" (`material.status-menu.confirm-default`). The menu
+marks such a choice "Asks first" (`material.status-menu.confirms`). A confirmed
+save shows its progress in the dialog (busy buttons, a failure kept in it), not on the chip.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `label` | `string` | — | what the status belongs to; names the button "Status of {label}: {status}" |
+| `value` / `choices` | `V` / `readonly StatusChoice<V>[]` | — | the held status, and every status: `value`, `label`, `tone`, `icon`, `description`, `disabled`, `disabledReason`, `confirm` (`title`, `description`, `confirmLabel`, `destructive`: a `ConfirmDialog` runs `onSelect` on confirm, a failure stays in the dialog and reaches `onError`) |
+| `onSelect` | `(next, prev) => void \| Promise<void>` | — | a different status was picked; a returned promise keeps the chip pending (menu closed, focus on the chip, spinner, `aria-busy`, old status shown) until it settles |
+| `onError` | `(error) => void` | — | the promise rejected (or threw): the failure is announced and the old status stays |
+| `transitions` | `Partial<Record<V, readonly V[]>>` | — | the statuses reachable from each status (no key: every move; a terminal status is `[]`) |
+| `unavailable` | `'disabled' \| 'hidden'` | `'disabled'` | an unreachable status is greyed with "Not available from {status}", or dropped |
+| `locked` / `reason` | `boolean` / `string` | — | nothing can be picked; `reason` is the tooltip, the button's description and the menu's first line |
+| `busy` | `boolean` | `false` | `aria-busy` and `aria-disabled`, a spinner, the old status kept, the menu does not open |
+| `readOnly` | `boolean` | `false` | a plain label |
+| `size` | `'sm' \| 'md'` | `'md'` | chip height |
+| `presentation` | `'auto' \| 'menu' \| 'sheet'` | `'auto'` | a dropdown menu, a bottom sheet of 44px rows, or the sheet under 768px |
+| `open` / `onOpenChange` | `boolean` / `(open) => void` | — | controlled menu |
+| `triggerProps` / `className` | | | on the button / on the menu |
+
+Texts come from `material.status-menu.*` (English and French). The rules
+(which statuses can be picked, and why not) are `@nxgt/material-core/status-menu`.
+
+**Form wrapper:** `StatusMenuFormField` takes `control`, `name`, `rules` and the
+StatusMenu props except `value` (the form holds it). A pick runs
+`onSelect` first; the form takes the new status once `onSelect` resolves (a
+promise keeps the pending state and the old status, and a rejection keeps the old
+value). `field.onBlur` fires when focus leaves the chip and its menu or sheet. An
+empty value (`''`) matches no choice, so the chip shows an empty value: give an
+initial status. The error message (or `helperText`) is written under the chip and linked to
+it with `aria-describedby` and `aria-invalid`, a refused submit focuses the chip,
+and `disabled` (or the form's) locks it.
+
+```tsx
+<StatusMenuFormField
+  control={form.control}
+  name="status"
+  label="Ticket 42"
+  choices={statuses}
+  rules={{ required: 'Pick a status.' }}
+/>
+```
+
+**Storybook:** `Selection & choice/StatusMenu` (and `/In a form`) · **Vue:** React only for now (#2816)
+
+---
+
 ## OptionTile
 
 ![OptionTile](../previews/selection-choice-optiontile.webp)

package/docs/guides/calculator.md

@@ -123,7 +123,7 @@ numbers: `sqrt(-1)` is "Undefined result".
 />
 ```
 
-The props below are read only by this variant (`currency` is shared). A point of sale till for a counter, on `@nxgt/material-core/calculator/pos`; the
+The props below are read only by this variant (`currency` is shared). A point of sale till for a counter, on `@nxgt/material-core/calculator/pos` (the engine; apps import `@nxgt/material/calculator`). The
 tab is named "Point of sale". The keys type an amount the way a till does:
 `1`, `2`, `5` is `1.25`, `00` adds two zeros, backspace drops the last digit,
 `C` clears it. `+` adds it to the ticket. `×` types a quantity first (`2.50 ×

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

@@ -326,49 +326,46 @@ grid of compact cells you read at a glance and change in place. Use
 [`ActionCard variant="tile"`](../components/buttons-and-actions.md#actioncard-tile)
 in a `ResponsiveGrid minItem="xs"`, one grid per section under its own `h2`:
 
-- **`status`** is a soft `Badge` with its word and an icon, so a status is
-  never told by colour alone.
+- **`action`** is a [`StatusMenu`](../components/selection-and-choice.md#statusmenu)
+  chip: it shows the status as a word, an icon and a tone (never colour alone),
+  so the tile needs no `status` badge, and it changes the status in place (a
+  bottom sheet on a phone). Its button is named "Status of {name}: {status}".
+  The title is the one button (it opens the detail), so the card and its chip
+  are two tab stops and nothing nests. When the tile is too narrow for the title
+  and the chip side by side (two per row at 360px), the chip wraps under the
+  title.
 - **`meta`** is one line, the occupant only while occupied; a long one is
   clipped and shown in full in a tooltip.
-- **`action`** is a `RowMenu` with a `DropdownMenuRadioGroup` of statuses,
-  named "Change status of {name}". The title is the one button (it opens the
-  detail), so the card and its menu are two tab stops and nothing nests.
 
 ```tsx
-import {
-	ActionCard,
-	Badge,
-	DropdownMenuRadioGroup,
-	DropdownMenuRadioItem,
-	ResponsiveGrid,
-	RowMenu,
-} from '@nxgt/material/components';
+import { ActionCard, ResponsiveGrid, StatusMenu } from '@nxgt/material/components';
+
+const choices = [
+	{ value: 'free', label: 'Free', tone: 'success', icon: 'check' },
+	{ value: 'occupied', label: 'Occupied', tone: 'warning', icon: 'user' },
+	{ value: 'out', label: 'Out of service', tone: 'error', icon: 'ban' },
+];
 
 <ResponsiveGrid minItem="xs">
 	<ActionCard
 		variant="tile"
 		title="Bed A1"
-		status={<Badge variant="soft" tone="warning" icon="user">Occupied</Badge>}
 		meta="Amara Diallo"
 		onClick={() => openDetail('a1')}
 		action={
-			<RowMenu
+			<StatusMenu
 				label="Bed A1"
-				triggerProps={{ 'aria-label': 'Change status of Bed A1' }}
-			>
-				<DropdownMenuRadioGroup value={status} onValueChange={setStatus}>
-					<DropdownMenuRadioItem value="free">Free</DropdownMenuRadioItem>
-					<DropdownMenuRadioItem value="occupied">Occupied</DropdownMenuRadioItem>
-					<DropdownMenuRadioItem value="cleaning">Cleaning</DropdownMenuRadioItem>
-				</DropdownMenuRadioGroup>
-			</RowMenu>
+				value={status}
+				choices={choices}
+				onSelect={setStatus}
+			/>
 		}
 	/>
 </ResponsiveGrid>;
 ```
 
 `title` is required with `action`: it is the card's button, named after the
-title, the status and the meta line.
+title and the meta line.
 
 For the figures of the whole board, put a `StatCardGroup` above a `DataTable`
 with one row per section, one numeric column per status (they add up to the

package/docs/guides/forms.md

@@ -537,6 +537,7 @@ or fails validation.
 | `Checkbox` · `CheckboxFormField` | `boolean` | `false` (see [Traps](#traps)) |
 | `CheckboxGroup` · `CheckboxGroupFormField` | `string[]` | `[]` |
 | `RadioGroup` · `RadioGroupFormField` | `string` | `''` |
+| `StatusMenu` · `StatusMenuFormField` | `string`: the picked `choices` value | `''` matches no choice, so the chip shows an empty value: give an initial status |
 | `CheckCardField` · `CheckCardFormField` | `boolean`: `true` for the first card, `false` for the second | `false` |
 | `ChipGroupField` · `ChipGroupFormField` | `type="single"` (default): `string \| null`. `type="multiple"`: `string[]` | `null` / `[]` |
 | `ChoiceCardGroup` · `ChoiceCardGroupFormField` | same as `ChipGroupField` | `null` / `[]` |

package/docs/guides/helpers.md

@@ -138,6 +138,8 @@ Vue: the Redux helpers are Pinia store factories: `defineLocalStore`
 | `useAllowedTransitions(status, transitions, configs)` | Status-machine actions (icon, colour, label, dialog copy) allowed from the current status. |
 | `useFocusOnMount<T>(focus = true)` | A ref whose element takes focus once mounted, and again whenever `focus` turns true: the heading of what replaced the content the user acted on. See [below](#usefocusonmount). |
 | `useScrollAway(ref?, { threshold? })` | True while the reader scrolls down (by `threshold`, 24 px, since the scroll last turned); false scrolling up, at the top or at the end. Folds an extended `Fab`. Without `ref`, the window; false on the server. See [Fab](../components/buttons-and-actions.md#fab). |
+| `useLatched(value)`, `useLatchedWhileClosed(open, value)` | The last value that was not `null` / `undefined`, and the value from the last open render while `open` is false: keep a dialog's text while it fades out after the app cleared its subject. `ConfirmDialog` does it itself. See [below](#uselatched). |
+| `useBarcodeScanner({ onScan, enabled?, acceptIn?, maxGap?, minLength?, onKey? })`, `createScanner()`, `attachBarcodeScanner(target, options)` | Hears a keyboard-wedge barcode reader anywhere on the page: a run of keys each within `maxGap` ms (50), at least `minLength` (4) long, closed by Enter, reaches `onScan(code)`; slower or shorter runs are typing. `createScanner` is the framework-free detector (`@nxgt/material-core/barcode-scanner`, also re-exported by `@nxgt/material/hooks`). See [below](#usebarcodescanner). |
 | `useCountdown(duration, { paused?, onExpire?, key? })` | Seconds left of `duration` (the clock `CountdownTimer` draws), for a button or a message that waits: ticks on the client only, `duration` on the server and first render. A new `duration` **or a new `key`** starts over, so the same `retryAfter` twice restarts it. See [below](#usecountdown). |
 | `useSubmitOnce(busy?)` | One submit in flight: wraps a submit handler so a double click or a second Enter is dropped until the request ends (the handler's promise, or `busy` back to false). See [below](#usesubmitonce). |
 | `useDrafts<T>(storageKey, { serialize?, parse?, storage? })`, `clearDrafts(storageKey, storage?)` | Unsent values kept by key in `sessionStorage`: `{ get, set, drop, clear, keys, loaded }`. Read after the first render (no hydration mismatch), storage errors swallowed, `drop(key)` once saved; `clearDrafts` empties a store key without a hook (sign-out). See [below](#usedrafts). |
@@ -231,6 +233,82 @@ render, with no flash. Where `matchMedia` does not exist (jsdom) the hook
 answers `serverValue` and never subscribes. When CSS alone can do it
 (`hidden xl:block`), prefer CSS: it has no flash at all.
 
+### `useLatched`
+
+A dialog driven by a nullable subject loses the subject the instant it closes,
+while its exit animation still plays. Read the subject through `useLatched` and
+the last one stays on screen until the dialog has gone. [`ConfirmDialog`](../components/feedback-and-status.md#confirmdialog)
+does this for its own props; use the hook for a `Dialog`, `CustomDialog` or
+`ConfirmationDialog` of your own.
+
+```tsx
+import { Dialog, DialogContent, DialogTitle } from '@nxgt/material/components';
+import { useLatched } from '@nxgt/material/hooks';
+
+export function ItemDialog({ item, onClose }: { item: Item | null; onClose: () => void }) {
+  const shown = useLatched(item); // still the last item while the dialog fades out
+  return (
+    <Dialog open={item !== null} onOpenChange={(o) => !o && onClose()}>
+      <DialogContent>
+        <DialogTitle>{shown?.name}</DialogTitle>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+`useLatchedWhileClosed(open, value)` is the same for a value built from several
+things: it returns `value` while `open`, and the value of the last open render
+once `open` is false.
+
+### `useBarcodeScanner`
+
+A USB or Bluetooth barcode reader is a keyboard: it types the whole code in a
+few milliseconds a key and ends with Enter. The hook tells that run from a
+person typing by timing alone, with one capture-phase `keydown` listener on
+the document, for a till, a stock count or a check-in screen. It does not draw
+barcodes: that is [`Barecode`](../components/data-display.md#barecode).
+
+```tsx
+import { useState } from 'react';
+import { useBarcodeScanner } from '@nxgt/material/hooks';
+
+export function Till({ add }: { add: (code: string) => void }) {
+  const [query, setQuery] = useState('');
+  useBarcodeScanner({ onScan: add, acceptIn: '[data-till-search]' });
+  return (
+    <input
+      data-till-search=""
+      aria-label="Search an item"
+      value={query}
+      onChange={(event) => setQuery(event.target.value)}
+    />
+  );
+}
+```
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `onScan` | required | called with the code when a scan ends; the Enter that closed it is swallowed (`preventDefault`, `stopPropagation`) |
+| `enabled` | `true` | while `false` nothing is listened to and nothing is swallowed |
+| `acceptIn` | none | a CSS selector of the form fields a scan is also accepted in (the search field); every other `input`, `textarea`, `select` and editable element is typed in. Outside form fields a scan is always accepted. In an accepted field the scan's characters are already typed in when Enter arrives: `onScan` clears the field itself |
+| `maxGap` | `50` | the longest pause between two keys of one scan, in ms |
+| `minLength` | `4` | the shortest code taken for a scan |
+| `onKey` | none | `(event, { result, pending })` for each key the scanner looked at: a screen with its own shortcuts skips them while `pending.length > 1`, since those keys are a scan's |
+
+Ctrl, Meta and Alt chords and key repeat are ignored. `onScan` and `onKey` are
+read from a ref, so a new function each render never re-binds the listener.
+The hook does nothing on the server. A reader that types slower than 50 ms a
+key (some Bluetooth modes) needs a larger `maxGap`.
+
+Outside React, `createScanner({ maxGap?, minLength? })` from
+`@nxgt/material-core/barcode-scanner` (or `@nxgt/material/hooks`, which re-exports it) is the pure detector:
+`feed(key, time)` answers `{ kind: 'pass' }`, `{ kind: 'buffering' }` or
+`{ kind: 'scan', code }`; `reset()` and `pending` complete it. The timing is
+the caller's (`event.timeStamp`), so it is tested without a clock.
+`attachBarcodeScanner(target, options)` is the DOM binding without React and
+returns what removes the listener.
+
 ### `useCountdown`
 
 The clock behind [`CountdownTimer`](../components/feedback-and-status.md#countdowntimer),