@nxgt/material 3.101.0 → 3.104.0

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
 
@@ -839,6 +840,61 @@ export function Topics() {
 }
 ```
 
+<a id="chipgroupfield-tones"></a>
+
+An option's `tone` colours its chip with the tones `Badge` takes (`primary`,
+`secondary`, `tertiary`, `success`, `info`, `warning`, `error`, `neutral`, and
+an app's own from `AppTones`), so a category filter can match the toned tiles
+below it. An unchosen chip shows a soft tint of the tone with the tone's text
+colour; a chosen chip shows the filled tone under its on-colour, both at AA
+contrast in light and dark. The leading check, `aria-checked`, the roving
+focus and the boundary of an unchosen chip are unchanged. No `tone` keeps the
+neutral chip.
+
+```tsx
+<ChipGroupField
+	label="Categories"
+	options={[
+		{ value: 'drinks', label: 'Drinks', icon: 'glass', tone: 'info' },
+		{ value: 'bakery', label: 'Bakery', tone: 'warning' },
+		{ value: 'other', label: 'Other' },
+	]}
+	value={value}
+	onValueChange={setValue}
+/>
+```
+
+`overflow="scroll"` keeps the chips on one line that scrolls sideways (touch,
+trackpad, the wheel; a focused chip scrolls into view), with a fade at each
+edge that hides more chips and no page scroll. The roving focus and the
+selection are the same. The default `overflow="wrap"` lets the chips flow onto
+several lines; `columns` and `groups` draw a grid and ignore `overflow`.
+
+`overflow="scroll"` for one sideways-scrolling line:
+
+```tsx
+import { ChipGroupField } from '@nxgt/material/components';
+import { useState } from 'react';
+
+const subjects = ['Algebra', 'Biology', 'Chemistry', 'Drama', 'Economics', 'French'].map(
+	(label) => ({ value: label.toLowerCase(), label }),
+);
+
+export function Subjects() {
+	const [value, setValue] = useState<string[]>([]);
+	return (
+		<ChipGroupField
+			label="Subjects"
+			type="multiple"
+			overflow="scroll"
+			options={subjects}
+			value={value}
+			onValueChange={setValue}
+		/>
+	);
+}
+```
+
 Balanced by default, and the unbalanced fill:
 
 ```tsx
@@ -857,7 +913,7 @@ const four = ['a', 'b', 'c', 'd'].map((value) => ({ value, title: value.toUpperC
 | `value` / `onValueChange` | `string \| null` or `string[]` | — | the chosen value, by `type` |
 | `deselectable` | `boolean` | `false` | `single` only: pressing the chosen chip clears it |
 | `max` / `min` | `number` | — | `multiple` only: `max` blocks the other chips once reached and speaks "{count} of {max} chosen"; `min` is a hint only |
-| `options` | `{ value; label; icon?; count?; description?; disabled?; disabledReason? }[]` | — | the chips, in one flow; `count`: see [option counts](#option-counts) |
+| `options` | `{ value; label; icon?; tone?; count?; description?; disabled?; disabledReason? }[]` | — | the chips, in one flow; `count`: see [option counts](#option-counts); `tone`: see [tones](#chipgroupfield-tones) |
 | `groups` | `{ label: string; options }[]` | — | titled sections instead of `options` (it wins when both are given): see [slot picker](#slot-picker-columns-groups-and-reasons) |
 | `columns` | `number \| { base?; sm?; md?; lg? }` | — | equal-width columns (1 to 12; one count per breakpoint, each holding to the next); Up and Down then move by row. Unset, the chips flow and wrap |
 | `showDisabledReason` | `boolean` | `true` | prints a disabled option's `disabledReason` below the whole group ("Label: reason"), so the chip row keeps its wrapping; `false` leaves it to the tooltip and the accessible description |
@@ -1020,6 +1076,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

@@ -265,6 +265,16 @@ focus. Below 30rem of list width the "Sort:" prefix is visually hidden (the name
 stays, and the button's accessible name is still "Sort: Name, Ascending").
 With no sortable column there is no control, and with neither a sortable column nor a `select` column there is no list bar.
 
+For a short list the band is noise: `showSort={false}` drops the button (on a
+phone too) and leaves every column sortable, so a
+`layout={{ phone: 'cards', wide: 'table' }}` keeps its header sorting on desktop.
+A list with a `select` column keeps its bar for "Select all". `DataTable` only:
+`ServerTable` does not pass it through.
+
+```tsx
+<DataTable layout="cards" showSort={false} renderCard={…} … />
+```
+
 ## Columns
 
 Tiles are always one column. For cards, the list's own width, not the window's, picks the columns: one, two from 36rem,
@@ -326,49 +336,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/csp.md

@@ -84,9 +84,10 @@ A virtual `DataTable` (`virtual`) adds no `style` attribute either: the
 server renders its first rows as plain rows, and the spacer rows' heights
 are custom properties written through `style.setProperty` after mount,
 which `style-src-attr` does not govern (`StrictCspVirtual` renders one under
-`style-src-attr 'none'`). Its scroll region's `maxHeight` is still an inline
-`style` on the server, one of #596's (a `maxHeightClassName` for
-`DataTable`, as `DataGrid` has, is [#800](https://github.com/softistx/nxgt-material/issues/800)).
+`style-src-attr 'none'`). Its scroll region's `maxHeight` is an inline
+`style` on the server, one of #596's: give `maxHeightClassName`
+(`maxHeightClassName="max-h-[28rem]"`, as `DataGrid` has) instead, and the
+region has no `style` attribute.
 
 A keyline `Carousel` (`multi-browse`, `hero`) renders no `style` attribute
 either: its first frame comes from container-query CSS, and the masks that

package/docs/guides/data-grid.md

@@ -1123,10 +1123,11 @@ A strict policy works with no `style-src-attr 'unsafe-inline'` for the grid:
   the CSSOM, which `style-src-attr` does not govern. A frozen column's drag
   rewrites `--dg-start-*` the same way.
 - A custom editor must follow the same rule: classes only.
-- `DataTable`'s own `maxHeight` (which a virtual `DataTable` needs) is an
-  inline `style={{ maxHeight }}` on its scroll region, so it is not covered
-  by this list; the grid takes a class instead. A `maxHeightClassName` on
-  `DataTable` is proposed in [#800](https://github.com/softistx/nxgt-material/issues/800).
+- `DataTable`'s own `maxHeight` is an inline `style={{ maxHeight }}` on its
+  scroll region, so it is not covered by this list; the grid takes a class
+  instead. A virtual `DataTable` under a strict CSP takes
+  `maxHeightClassName` (a class such as `max-h-[28rem]`, no inline style;
+  [#800](https://github.com/softistx/nxgt-material/issues/800)).
 
 The grid's popups (the select's list, the date's calendar, the menus) are
 library components and add nothing to the policy: see the

package/docs/guides/field-look-refined.md

@@ -41,7 +41,7 @@ import { TextField } from '@nxgt/material/components';
 | --- | --- |
 | `TextField` and the `*Field` text wrappers | `leading` / `trailing` icons and actions are muted with no well fill; a text unit (`"/ 20"`, a currency code) sits inline at the end in muted text. `CurrencyField` follows |
 | `NumberField`, `PercentField`, `CalculatorField` | one `role="group"` box; the value is end-aligned in tabular figures, the suffix hugs it, the Decrease and Increase buttons are a tinted round pair at the end (the `DurationField` look), no dividers |
-| `QuantityField`, `AgeField` | the value, the unit and the pair share one box; the unit is a chip that opens a menu |
+| `QuantityField`, `AgeField` | the value, the unit and the pair share one box; the unit is a chip that opens a menu (no chip without `units` or `allowCustomUnit`) |
 | `NumberField variant="score"` | a big value with its maximum, no box at rest; see [the form fields page](../components/form-fields.md#numberfield) |
 | Date, time and duration fields | the shared focus ring, a dashed hairline when read-only, the recessed surface when disabled |
 
@@ -49,7 +49,7 @@ import { TextField } from '@nxgt/material/components';
 
 - The `NumberField` order is the input, Decrease, Increase (it was Decrease,
   input, Increase). With a `CalculatorField`: input, Open calculator,
-  Decrease, Increase. A `QuantityField` is value, unit, Decrease, Increase.
+  Decrease, Increase. A `QuantityField` is value, unit (when it has one), Decrease, Increase.
 - The number box is a `group`. A test that queries an unnamed
   `getByRole('group')` now also matches it: name the one you mean.
 - A `QuantityField` unit is a button named "Unit: mg", not a `combobox`:

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

@@ -139,6 +139,7 @@ Vue: the Redux helpers are Pinia store factories: `defineLocalStore`
 | `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). |
@@ -260,6 +261,54 @@ export function ItemDialog({ item, onClose }: { item: Item | null; onClose: () =
 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),