@tensor_1/react 2.47.0 → 2.49.0

package/README.md

@@ -192,7 +192,7 @@ Rules the component cannot enforce for you:
 - **Dimming is not a signal.** `dimmedNodeIds` must be accompanied by text that says what is dimmed and why.
 - **Localise everything.** Every visible and announced string comes from `labels`; the English defaults live in `DEFAULT_RELATIONSHIP_GRAPH_LABELS`.
 
-**Map controls (`controls`, `initialView`).** The default `controls="full"` is the labelled toolbar above the map. `controls="compact"` is the map convention: an icon cluster in the map's bottom-right corner (zoom in, zoom out, fit, reset, full screen, each with a tooltip) and the zoom level beside it; drag pans, Ctrl/⌘ + wheel or a pinch zooms around the pointer, and a plain wheel keeps scrolling the page and briefly says how to zoom. The map itself takes keyboard focus: arrow keys pan (on an item they still move between items), `+` and `−` zoom, `0` resets and Escape leaves full screen. Full screen covers the page (the page behind does not scroll) and there a plain wheel zooms. `controls="none"` draws nothing; drag, pinch and Ctrl/⌘ + wheel still work. `initialView="fit"` opens with every item in view (down to the 40 % minimum) instead of the 75 % readability floor, and Reset returns to it.
+**Map controls (`controls`, `initialView`).** The default `controls="full"` is the labelled toolbar above the map. `controls="compact"` is the map convention: an icon cluster in the map's bottom-right corner (zoom in, zoom out, fit, reset, full screen, each with a tooltip) and the zoom level beside it; drag pans, Ctrl/⌘ + wheel or a pinch zooms around the pointer, and a plain wheel keeps scrolling the page and briefly says how to zoom. The map itself takes keyboard focus: arrow keys pan (on an item they still move between items), `+` and `−` zoom, `0` resets and Escape leaves full screen. Full screen covers the page (the page behind does not scroll) and there a plain wheel zooms. `controls="none"` draws nothing; drag, pinch and Ctrl/⌘ + wheel still work. `initialView="fit"` opens with every item in view (down to the 40 % minimum) instead of the 75 % readability floor, and Reset returns to it. With `controls="compact"` the hint, the zoom level and the cluster sit in a band along the map's bottom edge; the map ends at the band, and fit, the first view and Reset leave its height free.
 
 ```tsx
 <RelationshipGraph layout="layered" controls="compact" initialView="fit" height="clamp(24rem, 62vh, 44rem)" … />
@@ -256,10 +256,102 @@ const showSpinner = useDelayedPending(upload.isPending);
 {showSpinner && <Spinner size="sm" label={t('uploading')} />}
 ```
 
+### What changed: highlight, count, optimistic values (motion standard §2.5, §2.6, §2.8)
+
+- **`ChangeHighlight value={…}`** (or `useChangeHighlight(value)` on your own element, or
+  `.uix-changed` on plain markup) tints the element when `value` changes after mount and fades
+  the tint; never on the first render; a second change restarts it. `as="tr"` tints the row's
+  cells; `variant="ring"` rings something with a colour of its own (a status pill, a star).
+  Under reduced motion or forced colours it is a steady outline for the same time. Give it
+  words: `announce="Status changed to Resolved by A. Novak"` speaks through a polite region
+  (inside the open dialog when there is one). `flashChanged(el)` and `announcePolite(text)`
+  are the same pieces for changes that do not flow through a React value.
+- **`Count value={n}`** for a badge or stat value: one 4 px tick in the change's direction with
+  a fade, tabular figures, `format` for "99+". Never a loop, never a count-up.
+- **`useOptimisticValue(serverValue, commit, { onRollback })`** only for reversible, personal
+  actions (star, pin, reaction, mark read, display preference, own saved-view order). It shows
+  the change at once; if `commit` rejects, the last confirmed value comes back, `rollbacks`
+  counts up (flash it with `ChangeHighlight value={rollbacks}`) and `onRollback` lets you say
+  what was restored. State transitions, assignment, approvals and priority stay pessimistic.
+
+```tsx
+<ChangeHighlight as="tr" value={row.updatedAt} announce={t('rowUpdated', { id: row.id, actor })}>…</ChangeHighlight>
+<Td><ChangeHighlight value={row.status} variant="ring"><StatusPill tone={tone}>{label}</StatusPill></ChangeHighlight></Td>
+<span className="uix-navitem__badge"><Count value={unread} format={(n) => (n > 99 ? '99+' : String(n))} /></span>
+
+const star = useOptimisticValue(view.starred, (next) => api.star(view.id, next), { onRollback: () => toast.error(t('starNotSaved')) });
+<ChangeHighlight value={star.rollbacks} variant="ring" announce={star.rollback ? t('starRestored') : undefined}>
+  <StarButton pinned={star.value} label={view.name} onToggle={(next) => star.set(next)} />
+</ChangeHighlight>
+```
+
+### Lists that move, the success outcome, sliding indicators (motion standard §2.5, §2.8)
+
+- **`MotionList`** (`items`, `getKey`, `renderItem`, `as`): a new item rises 8 px and fades in;
+  a removed item stays in place (hidden from assistive tech, `inert`), fades out, and only then
+  leaves, so the items below glide up; a re-sort glides (FLIP, transform only). Nothing moves on
+  the first render. Focus stays on a moved item and goes to the next item when the focused one
+  leaves; focus outside the list is never pulled in. `renderItem` must pass unknown props to its
+  element (`<li>`, or a `Tr` with `as="tbody"`).
+- **`useDeferredReorder(items, getKey)`**: never re-sort under the pointer. While a mouse is over
+  the list or keyboard focus is inside it, a new order waits (content still updates, new rows go
+  to the end); `held` says so; the order applies when they leave. Spread `listProps` on the list.
+- **`SuccessState`** in `States`: the outcome of a rare journey (a request submitted): a mark
+  that draws once, the title (focused on mount for `page` and `full-page`), `reference`,
+  `next` (what happens next), `action`. Reduced motion shows the mark at once.
+- **Tabs, Segmented**: the line underline, the pill and the lifted segment slide to the chosen
+  option on a click (160 ms); a keyboard change and reduced motion jump. Server HTML, forced
+  colours and Segmented's link mode keep each option's own mark. `useSlidingIndicator` is the
+  hook behind it.
+- **CollapsibleSection** opening fades the body in and settles it 4 px (on `::details-content`,
+  where supported); an already open section, a keyboard open and closing are instant.
+
+```tsx
+const queue = useDeferredReorder(rows, (row) => row.id);
+<MotionList {...queue.listProps} as="tbody" items={queue.items} getKey={(row) => row.id}
+  renderItem={(row) => <Tr>…</Tr>} />
+
+<SuccessState title={t('requestSubmitted')} reference={<>{req.number} <CopyButton … /></>}
+  next={[t('confirmationSent'), t('agentPicksUp')]} action={<ButtonLink href={`/requests/${req.id}`}>{t('viewRequest')}</ButtonLink>} />
+```
+
+### Drag affordances (motion standard §2.8)
+
+One set of drag states for every draggable thing (`drag.css`), as attributes so any element can
+carry them: `[data-uix-drag="lifted"]` (picked up by the pointer: a little larger, a deeper
+shadow), `[data-uix-drag="grabbed"]` (picked up from the keyboard: a dashed ring, no motion),
+`[data-uix-drop-target]` (the zone it would land in), `.uix-drop-line` (the gap it would drop
+into) and `[data-uix-settle]` (the landing). Reduced motion keeps the states and drops the scale
+and the landing.
+
+- **SortableList** and **DashboardCanvas** lift and settle on their own.
+- **Kanban**: `KanbanCard dragging`, `KanbanColumn dropTarget`, `<KanbanDropLine />` at the gap;
+  call `settleDrop(cardElement)` once the card is in its new place.
+- **`useKeyboardGrab({ id, label, onMove, onDrop, onCancel, labels })`** for a draggable thing you
+  build: Space or Enter picks the focused item up, the arrows call `onMove(direction)` (return
+  what to say, e.g. "Position 3 of 8"), Space or Enter drops, Escape or leaving puts it back;
+  every step is said politely. Spread `itemProps` (it includes a `ref`) on the focusable item; the
+  picked-up state follows `id`, so an item moved into another list stays picked up and focused.
+  Words: `labels` or `UixLabelsProvider` `keyboardGrab`. The kit's lists have their own paths.
+
+```tsx
+<KanbanColumn title={t('doing')} dropTarget={drag?.column === 'doing'}>
+  {cards.map((card, i) => <Fragment key={card.id}>
+    {drag?.column === 'doing' && drag.index === i && <KanbanDropLine />}
+    <KanbanCard title={card.title} dragging={drag?.id === card.id} onMove={…} />
+  </Fragment>)}
+  {drag?.column === 'doing' && drag.index >= cards.length && <KanbanDropLine />}
+</KanbanColumn>
+
+// your own draggable list: the picked-up state follows the id, across lists too
+const grab = useKeyboardGrab({ id: item.id, label: item.title, onMove: (dir) => move(item.id, dir), onCancel: restore });
+<li tabIndex={0} {...grab.itemProps}>{item.title}</li>
+```
+
 ### Scrolling tabs, toned stat tiles and copying
 
 - **`Tabs overflow="scroll"`** keeps a long tab row on one line that scrolls sideways. The selected tab is always scrolled into view, and edge buttons appear only on the side that has hidden tabs. The buttons are pointer-only: keyboard users move with Arrow, Home and End. Combine it with `TabPanel keepMounted` on a record page with many sections.
-- **`Stat tone`** (`warning`, `danger`) draws a toned outline and value; the label stays muted, so the tone never replaces words. `size="compact"` fits dense fact bands.
+- **`Stat tone`** (`warning`, `danger`) colours the value and leads it with a dot of that tone; the border stays neutral and the label muted, so the tone never replaces words (a toned outline before 2.48). `size="compact"` fits dense fact bands.
 - **`Stat onActivate`** makes the whole tile a button that opens an editor (`aria-haspopup="dialog"`). Pass `activateLabel` (e.g. "change") so the name reads "Priority: P1, change", and `expanded` while the editor is open. The ref points at the button, for anchoring a popover.
 - **`Stat pending`** is for a tile whose action is still running (a save, a state change). The button gets `aria-busy="true"` and `aria-disabled="true"`, is dimmed with a progress cursor, and calls neither `onActivate` nor your `onClick` / `onKeyDown` until `pending` is false again. It is never natively `disabled`, so it keeps focus and a screen reader can still read it. Only a tile with `onActivate` has the state; a read-only tile and a link tile ignore the prop.
 - **Tiles in one row line up.** A grid or flex row stretches its tiles to the tallest one. Read-only, button and link tiles all start their label and value at the same offset from the top edge, whatever the height (before 2.38.0 a button tile centred its rows).
@@ -1012,6 +1104,9 @@ const v = useVirtualRows(rows, { rowHeight: 44, estimatedViewportHeight: 600, en
 - The ref is the body (the button, link or span that carries the chip's action), also on a
   removable chip; `bodyProps` puts attributes there.
 - `current` on a link chip: `aria-current="page"` and the filled look.
+- `onClick` gets the click event, so a chip can be a `Menu` trigger:
+  `<Menu trigger={<Chip variant="add" icon={<PlusIcon />}>Filter</Chip>}>…</Menu>`. A handler that takes no
+  argument still works.
 
 #### FileUpload and Attachment
 
@@ -1166,3 +1261,446 @@ mask; an avatar with a dot no longer clips it.
   `entityPicker`. `SearchSuggest` has the two slots these use: `idle` and `note`.
 - `CommandPalette` announces its result count through `UixLabelsProvider` `commandPalette`
   (`resultsOne`, `resultsMany`, `{count}`) or a `resultsLabel(count)` prop; English is unchanged.
+
+### Codes, contacts and paper (batch 5)
+
+#### QrCode
+
+`QrCode` draws `value` as a scannable SVG QR code with the standard four-module quiet zone.
+Name it for where it leads (`label`), pick `errorCorrection` (`M` by default; `Q` or `H` for a
+poster that may be creased or partly covered) and a `size`: CSS pixels, or a length such as
+`'32mm'` on paper. Keep at least 2 px per module on a screen and 0.4 mm per module on paper.
+The symbol is ink on paper in light, dark, print and forced colours, because scanners read dark
+on light. The encoder is the kit's own (`encodeQr`, `qrPath`), with no runtime dependency.
+
+```tsx
+<QrCode value={campaignUrl} label={t('qrOpensCampaign')} errorCorrection="Q" size="40mm" />
+```
+
+#### CodeDisplay
+
+`CodeDisplay` shows a one-time code large enough to read across a counter: monospace groups
+(`groupSize`, or the code's own spaces and hyphens), a visible `label`, and a screen-reader
+spelling character by character (`spell` for a spelling alphabet or to tell O from 0).
+`expiresAt` adds a countdown that is never a live region: a screen reader hears "{time} left"
+once at `warnBefore` seconds (60) and "expired" once, and `onExpire` runs once. An expired code
+is struck through and says so in words; `copyable` adds a `CopyButton` while the code is live.
+The product makes the code and enforces its expiry.
+
+```tsx
+<CodeDisplay code={pairing.code} label={t('pairingCode')} expiresAt={pairing.expiresAt} copyable onExpire={refresh} />
+```
+
+#### ContactCard
+
+`ContactCard` renders `.uix-contact` in a card (`bare` for a peek, a popover or a card body that
+already has padding): avatar, `name` (a quiet link with `href` / `renderLink`), `role`, the
+`email` and `phone` as selectable text, and Email / Call as `mailto:` / `tel:` `ButtonLink`s
+named for the person ("Email Amra Hadžić"), then your own `actions` and `stats`.
+`state="purged"` (the person's data was erased) shows a neutral placeholder and nothing that
+reaches anyone, even when stale props still carry an address; `state="unavailable"` keeps the
+name and says the details are unavailable. Words: `labels` or `UixLabelsProvider` `contactCard`.
+
+```tsx
+<ContactCard name={p.name} role={p.role} avatar={<Avatar size="lg" src={p.photo} alt="" />} email={p.email} phone={p.phone}
+  state={p.erasedAt ? 'purged' : 'active'} href={`/people/${p.id}`} renderLink={(props) => <Link {...props} />} />
+```
+
+#### EventRow slots
+
+`EventRow` takes `weekday`, `year` and `time` in its date tile (the tile widens to its longest
+line), `dateTime` to make the tile a `<time>` with a machine-readable date, and `media` for a
+thumbnail at the row's end: an `<img>` drawn 4:3 and cropped to fill, moved under the text on a
+phone. Without them the markup is unchanged.
+
+```tsx
+<EventRow weekday="Wed" month="Oct" day="22" year="2026" time="18:00" dateTime="2026-10-22T18:00+02:00"
+  title={<Link href="/program/42">Book launch</Link>} meta="National library" media={<img src={cover} alt="" />} />
+```
+
+#### PrintLayout
+
+`PrintLayout` is a print document frame for the browser's own print (`window.print()`): `size`
+`A4` (default) or `A5`, `orientation`, a `header` and a `footer` that repeat on every printed page
+(it renders a layout `<table>`: Chromium repeats a real `<thead>` / `<tfoot>`, not a CSS table of
+divs), "page / pages" in the bottom-right margin (`pageNumbers`), and ink-on-paper tokens for
+everything inside, also as a paper preview on screen in the dark theme. While it is on the page,
+printing shows only the documents (`isolate`, default): the app shell, toolbars and toasts are
+left out and scroll boxes cannot cut the document. `singlePage` keeps a poster or a one-page
+readout in one piece; when its content does not fit, the preview is outlined and
+`onOverflowChange(true)` is called. `PrintSignature` is a signature line with place and date and
+an optional stamp box (never split across pages); `PrintPageBreak` starts a new page. Utilities:
+`.uix-print-keep`, `.uix-print-hide`, `.uix-print-only`.
+
+```tsx
+<PrintLayout header={<PracticeHeader />} footer={<DoctorFooter />}>
+  <h1>{t('findings')}</h1>
+  <DescriptionList items={patient} />
+  <PrintSignature placeAndDate={placeAndDate} name={doctor} stamp />
+</PrintLayout>
+```
+
+#### QrScanner
+
+`QrScanner` is a camera viewfinder for a decoder you supply: `decode(frame)` gets
+`{ imageData, video }` (frames at most `maxFrameSize` px on the long side, every `interval` ms)
+and returns the text it read; the kit ships no decoder and makes no network request.
+`onResult(value)` is called once per new text (the same text again within `repeatAfter` ms is
+not repeated), and a status message says it once. Before the browser's prompt the scanner shows
+your `explainer` and a start button (with `autoStart`, a camera the browser already allows starts
+at once); after a refusal it says how to allow the camera again; it says so when the browser has
+no camera API, no camera is found, or the camera sends no picture. `manualEntry` is rendered in
+every state. A hint appears after `hintAfter` ms of frames without a code; a torch toggle appears
+when the camera has one. The camera stops on Stop, on unmount and while the page is hidden.
+
+```tsx
+<QrScanner decode={({ imageData }) => wasmDecoder.read(imageData)} onResult={redeem}
+  explainer={<p>{t('cameraWhy')}</p>} manualEntry={<VoucherCodeField />} />
+```
+
+A scan trail (what was read, what the product did with it, what to do next) is the product's:
+keep `onResult` and `onStatusChange` in state and show the last few as a `Timeline` under the
+scanner, newest first, with the outcome in words ("Not changed: already lent").
+
+#### SchedulingCalendar: the day by resource
+
+`view="day"` with `resources` draws one column per resource (a practitioner, a room) on a slot
+axis in `timeZone`: `resourceSpans` are the free, booked and off stretches the server composed;
+a free span is cut into bookable slots of `slotMinutes` (15), a booking and time off stay whole,
+and a time no span covers is hatched "no schedule" (never free; nothing is inferred). `dayStart`
+/ `dayEnd` set the axis (07:00–19:00). `onSelectSlot` gets `{ resourceId, start, end, kind, span }`
+for a click, Enter or Space on a slot or a booking; `selectedSlot` marks one. The view is one tab
+stop: arrows move between slots and resources, Home / End to a column's ends. The gutter and the
+heads stay in view while the grid scrolls. `loading` shows skeletons on the first load and dims
+what is on screen on a refetch. Below `resourceListBelow` (480 px of its own width) the day is a
+list, one resource after another (`resourceLayout` fixes either).
+
+```tsx
+<SchedulingCalendar view="day" anchorDate={day} timeZone={tenantZone} entries={[]}
+  resources={practitioners} resourceSpans={spans} slotMinutes={15} dayStart="07:30" dayEnd="17:00"
+  onSelectSlot={openSlotPopover} selectedSlot={open && { resourceId: open.resourceId, start: open.start }} loading={isFetching} />
+```
+
+#### RelationshipGraph: gaps on the map
+
+For a map of what is expected and what is there (TENSOR's K3 gaps): an edge takes
+`variant: 'dashed'` (an expected relation that is missing), a `tone` and a `description` that
+both nodes say to a screen reader ("covers, from Control K3.2 (expected, missing)"); a node takes
+a `tone`; a legend item takes the same `tone`, a `shape` (`edge` or `node`) and a `variant`, so
+it matches what it explains. Say a tone's meaning in words too (`description`, the node's text).
+`revealId` scrolls a node into view without moving focus (a table row beside the map), and with
+reduced motion it jumps. Without `rootId` no node gets the root border (`markRoot` forces it
+either way). `controls="none"` hides the toolbar in the radial layout as well. Edge labels that
+would overlap in a dense column are moved apart, or left out when they would drift too far (the
+relationship stays in the nodes' descriptions and the list). An edge across more than one column
+is a solid "skip" edge in a channel under the columns it crosses, no longer dashed or flagged as a
+cycle; `LayeredEdgeKind` gains `skip` and `back`.
+
+`RelationshipGraph layout="layered"` was measured at CMDB topology sizes (HAR-1387; 300 and 600
+items): no items overlap; a column that takes many forward edges says their common relation once
+in its header and only edges that differ keep a label; a busy node fans out along one bus; a
+node's description names five relationships and points to the list, whose rows list at most eight
+neighbours until "Show all N" (`connectedHeading`, `showAllRelations`, `showFewerRelations`,
+`moreRelations`); a pan or a zoom only moves the stage, so dragging stays at the display's frame
+rate. A force layout was not needed.
+
+### Form fields (HAR-1812, HAR-1799, …)
+
+#### CheckboxGroup
+
+```tsx
+<CheckboxGroup label={t('tags')} hint={t('tagsHint')} error={errors.tags} columns={3} required>
+  {tags.map((tag) => (
+    <Checkbox key={tag.id} name="tags" value={tag.id} label={tag.name}
+      checked={chosen.includes(tag.id)} onChange={() => toggle(tag.id)} />
+  ))}
+</CheckboxGroup>
+```
+
+The checkbox counterpart of `<RadioGroup label>`: a `<fieldset>` whose `<legend>` names the group,
+so it is announced with each box, and the field's message slot below (`hint`, or `error` with
+`role="alert"`, tied to the group with `aria-describedby`). `columns` is a ceiling: no column is
+narrower than 10rem, so a phone gets one. `disabled` disables every box; `required` draws the
+marker (which boxes must be ticked is your rule).
+
+#### PasswordInput and OtpInput
+
+```tsx
+<Field label={t('password')} error={errors.password}>
+  <PasswordInput name="password" autoComplete="current-password" />
+</Field>
+<Field label={t('code')} hint={t('codeHint')} error={errors.code}>
+  <OtpInput name="code" length={6} groupSize={3} onComplete={(code) => verify(code)} />
+</Field>
+```
+
+`PasswordInput` is an `Input type="password"` with a reveal toggle inside its end: a button with
+`aria-pressed` whose name stays "Show password" (`labels.show`, or `UixLabelsProvider`
+`passwordInput`). A pointer press keeps the caret in the field; Tab reaches the toggle. When the
+form submits, a revealed password is hidden first, so the browser still offers to save it.
+`revealed` / `defaultRevealed` / `onRevealedChange`, `size`, and every `Input` prop pass through.
+
+`OtpInput` is ONE input (`inputMode="numeric"`, `autoComplete="one-time-code"`, `pattern`;
+no `maxLength`, so an autofilled "ABCD-EFGH" is cleaned before it is cut) drawn as `length` cells, so the phone's code autofill, password managers and screen
+readers see one field. Typing or pasting "123 456" keeps the characters; `onComplete(code)` runs
+once each time the code fills. `mode="alphanumeric"` takes letters (upper-cased); `groupSize`
+draws a gap; `aria-invalid` (from `Field error`) turns the cells red.
+
+`InputGroup` gains `trailingAction`: a real control inside the field's end (class
+`uix-input-group__action`, square, the field's height less 4 px a side), which both use.
+
+#### TimePicker
+
+```tsx
+<Field label={t('opensAt')} hint={t('businessHours')}>
+  <TimePicker name="opens" value={opens} onValueChange={setOpens} locale={locale} minuteStep={30} min="08:00" max="18:00" />
+</Field>
+```
+
+A time of day beside `DatePicker`; the value is `HH:mm` (what `<input type="time">` holds) or
+`null`. The field shows the locale's clock (14:30 in `de`, 2:30 PM in `en-US`; `hour12` overrides)
+and reads a typed time on Enter or blur: `1430`, `14.30`, `9`, `2:30 pm`. ArrowUp / ArrowDown step
+the part under the caret (the hour, or the minutes to the next `minuteStep`), PageUp / PageDown the
+hour, Alt+ArrowDown opens the list. The clock button lists the times at `minuteStep` between `min`
+and `max`; the list takes focus on the chosen time, Enter picks, Escape closes and focus goes back
+to the field. Text that is not a time, or one before `min` / after `max`, marks the field invalid and
+says why. `name` submits `HH:mm` through a hidden input. Words: `labels` or `UixLabelsProvider`
+`timePicker`. `DateTimePicker` now uses it for its time (no native `type="time"` is left);
+`minuteStep` defaults to 15 there and only steps the keys and the list, any typed minute is kept.
+
+#### Date fields without call-site workarounds (HAR-2432)
+
+```tsx
+<UixLabelsProvider labels={{
+  dateFormat: { locale: 'de', formatDate: toDDMMYYYY, parseDate: fromDDMMYYYY, placeholder: 'TT.MM.JJJJ' },
+  dateRangePicker: { label: t('chooseRange'), invalidMessage: t('rangeInvalid') },
+}}>
+```
+
+- `dateFormat` sets `locale`, `formatDate`, `parseDate` and `placeholder` for every `DatePicker`,
+  `DateTimePicker`, `DateRangePicker` (and the `locale` of `TimePicker`) below the provider; a prop
+  on one field still wins.
+- `FilterPopover type="date"` renders the kit `DatePicker`; the value stays `YYYY-MM-DD` (`''` for
+  none).
+- `DateRangePickerLabels` has `label` and `invalidMessage`, so no English default is left outside
+  the labels group; the props still win.
+- `DateTimePicker` names its time from the label's accessible text (an `aria-hidden` "*" is left
+  out) and follows the label when its text changes after mount.
+
+#### Combobox at parity with Select (HAR-1588)
+
+```tsx
+<span id="cat-label" className="uix-field__label">{t('category')}</span>
+<Combobox aria-labelledby="cat-label" label={t('category')} emptyLabel={t('noMatch')} value={category} onValueChange={setCategory}
+  options={[{ label: t('hardware'), options: hardware }, { label: t('software'), options: software }, other]} />
+```
+
+The list is a top-layer popover placed with `useAnchoredPosition` (like `Select`), so a Drawer, a
+Popover or an `overflow: hidden` cell never clips it. ↑ ↓ PageUp PageDown move (Home End too while
+an option is active), disabled options are skipped and the list does not wrap; Enter chooses;
+Escape closes it and puts the chosen option's text back, as leaving the field does. `options` take
+groups (`{ label, options, disabled }`, rendered as `role="group"`); the no-match row is outside the
+listbox; the chosen option has a check mark. New: `aria-labelledby` (replaces `label` as the name),
+`aria-describedby`, `aria-invalid` and `inputId` land on the input; `placement`;
+`filterComboboxItems`.
+
+#### TagInput
+
+```tsx
+<Field label={t('labels')} hint={t('labelsHint')}>
+  <TagInput name="labels" value={labels} onValueChange={setLabels} suggestions={known} maxTags={10}
+    validate={(tag) => (tag.length > 40 ? t('tooLong') : null)} />
+</Field>
+```
+
+Type and press Enter or a comma to add a chip; a paste of "a, b, c" adds three. A duplicate (ignoring
+case and accents), a `validate` refusal or one past `maxTags` keeps the text and says why under the
+field. Suggestions (those not added yet) open in a top-layer list once the person types or presses
+ArrowDown; Enter adds the active one. Backspace in the empty field reaches the last chip; ArrowLeft /
+ArrowRight move between chips and back; Backspace or Delete removes the focused chip and focus stays
+with the tags; the field is the only tab stop. Each change is announced politely. Inside `Field` the
+text input gets the label, hint and error; `name` submits one value per tag. Words: `labels` or
+`UixLabelsProvider` `tagInput`.
+
+#### SearchSuggest freeText (HAR-2465)
+
+```tsx
+<label className="uix-field__label" htmlFor="maker">{t('manufacturer')}</label>
+<SearchSuggest freeText inputId="maker" name="manufacturer" label={t('manufacturer')}
+  value={maker} onValueChange={setMaker} options={spellings} loading={loading} />
+```
+
+A text field with suggestions: the value is the text. Enter keeps what was typed and never submits
+the surrounding form (also while `loading`); no row is picked unless the person moves to it
+(ArrowDown / ArrowUp, then Enter) or clicks it, and then its title replaces the text through
+`onValueChange`, again without submitting. Blur, Tab and Escape keep the text (a second Escape does
+not clear it). No magnifier is drawn. `onSelect` is optional. Without `freeText` the search mode is
+unchanged. Decision: `Docs/adr/0004-search-suggest-free-text.md`.
+
+#### EntityPicker and SearchSuggest gaps (HAR-1834)
+
+- A failure Retry cannot fix: reject `onSearch` with `{ retryable: false, message? }`, or pass
+  `isRetryable(error)`. The list shows the message (or `labels.forbidden`) and no Retry row.
+- `SearchSuggest` takes `disabled` and `invalid`; `EntityPicker` forwards them, so an empty disabled
+  picker cannot be typed in and an empty required one with an error is announced invalid.
+- Clear starts a new search: the old query and rows are gone and the field has focus.
+- A visible label names the field: with a `<label for>` (a `Field`) or `aria-labelledby`
+  (`EntityPicker`) / `inputLabelledBy` (`SearchSuggest`), no `aria-label` overrides it.
+- While the next query loads the last rows stay in view (`aria-busy` at once), and the spinner waits
+  300 ms (`useDelayedPending`), so a fast answer shows none; Enter during a search picks nothing and
+  submits nothing.
+### Calm status colour, the app shell and display preferences (2.48)
+
+#### StatusPill treatments, Stat sentiment, quiet Alert (HAR-1563)
+
+```tsx
+<StatusPill tone="danger" treatment="dot">Breached</StatusPill>       // a table cell
+<StatusPill tone="progress">In progress</StatusPill>                  // the record's header (soft, the default)
+<StatusPill tone="warning" treatment="outline">Due in 2h</StatusPill> // a flag among other chrome
+<Stat label="Breached SLAs" value={7} trend={{ direction: 'up', label: '2', sentiment: 'negative' }} />
+```
+
+- `StatusPill treatment`: `'soft'` (default, the tinted wash; `'filled'` is its old name and still works), `'dot'`
+  (no fill, a neutral label, the tone only in the dot: for tables) and `'outline'` (a neutral hairline, a hushed
+  label and the dot; only `critical` keeps a toned border). `dot` and `outline` always draw the dot. **Changed:**
+  `outline` used to colour the label and a 40 % border in the tone's hue.
+- `StatusPill tone="progress"`: in flight, the same blue as `info`.
+- `Stat trend.sentiment`: `'positive'` (green), `'negative'` (red) or `'neutral'` (grey, the default). **Changed:** the
+  chip used to be green for `up` and red for `down`, so a rise in breached SLAs showed green. Pass the sentiment the
+  change has for your metric.
+- `Stat tone`: the border stays neutral and a dot leads the toned value (**changed:** the border was toned).
+- `Alert`: the borders are a 24 % hairline of the tone (**changed:** 30 to 40 %); the warning icon is the text
+  role, at least 3:1 on its tint in both themes.
+
+#### A Stat link tile looks like a link at rest (HAR-1803)
+
+A tablet has no hover, so a tile that leads somewhere has to show it before it is touched. A link tile
+(`href`) draws a trailing chevron (`ChevronRightIcon`) in its label row; a tile that opens a dialog or menu
+keeps its down chevron; an in-place action tile (`onActivate` with `haspopup={false}`, class
+`.uix-stat--action`) underlines its value with a dotted line. All three are shapes, so they read without
+colour and in forced-colours mode, and none depends on hover. A plain figure tile is unchanged. The
+hover tint of interactive tiles now applies only where the device can hover (`@media (hover: hover)`).
+
+```tsx
+<Stat label={t('overdue')} value={4} href="/loans?overdue" renderLink={toRoute} />  // › at rest
+```
+
+#### Inset: a well inside a card body (HAR-1818)
+
+```tsx
+<Card title={t('current')}>
+  <Inset role="group" aria-label={t('headerPreview')}><BrandBar brand={brand} /></Inset>
+  <Inset padding="sm"><code>{css}</code></Inset>
+</Card>
+```
+
+`Inset` (`.uix-inset`) frames a preview or a specimen inside a card body: a hairline border, the md radius,
+the subtle background and `--uix-space-4` padding (`padding="sm"`: `--uix-space-3`). Use it instead of a `Card`
+in a `Card`, which brings a second shadow, card padding and card semantics. `tone="surface"` is for a well on
+a panel that is already subtle. It lays out nothing; give it a `role="group"` and a name when the preview needs
+one.
+
+#### Icons, not text glyphs (HAR-1576)
+
+Toast, Pagination, MetricInput, SavedViewMenu and Steps draw the icon set (`XIcon`, the chevrons, `PlusIcon`
+/ `MinusIcon`, `StarIcon`) where they drew `× ‹ › « + − ★ !`. The table sort arrows and the `Select` trigger's
+chevron are the icon set's glyphs through a CSS mask in `currentColor`, so they follow the theme; plain CSS gets
+the same through `.uix-glyph`:
+
+```html
+<span class="uix-glyph uix-glyph--chevron-down" aria-hidden="true"></span>
+```
+
+`node packages/react/scripts/glyph-icons.mjs` is the guard (it runs in `npm test`): a glyph as the whole content
+of a button, a link or an icon slot, or in a CSS `content:`, fails with its file and line. Text that only looks
+like an icon (a Kbd legend, a diff sign) goes in `glyph-icons.allow.json` with a reason.
+
+#### The staff shell: full viewport and the type presets (HAR-1815)
+
+```tsx
+<AppShell layout="viewport" sidebar={<StaffNav />}>
+  <PageHeader size="display" eyebrow={t('today')} title={t('overview')} subtitle={t('overviewLead')} actions={actions} />
+</AppShell>
+<DetailPage variant="staff" back={{ href: '/loans', label: t('allLoans') }} title={loan.code} metrics={metrics}>
+  <Card><SectionHead size="compact" as="h3" title={t('copies')} /><Table>…<CellSub tabular>{copy.inventory}</CellSub>…</Table></Card>
+</DetailPage>
+```
+
+- `AppShell layout="viewport"`: no frame, `100dvh`, no top-bar row (a `topbar` sits at the top of the main
+  column), staff padding (`space-7 space-6 space-6`, `space-8` at the sides from 80rem), and below 40rem one
+  column with the sidebar hidden. `layout="frame"` is the default and the old look.
+- `PageHeader size="display"`: 40 px heading-font title, bold hushed eyebrow, body-size hushed subtitle (42rem),
+  actions on the bottom line.
+- `DetailPage variant="staff"`: h2 / 1.15 title, un-underlined hushed back link, eyebrow metric labels over
+  regular tabular h3 values.
+- `SectionHead size="compact"` (15 px / 1.3 / 600) and `as="h3"`; `CellSub tabular`.
+
+#### Sidebar actions and search, AccountMenu, the rail hotkey and the phone nav tier (HAR-1371)
+
+```tsx
+const [nav, setNav] = useState<ShellNav>('full');
+<AppShell layout="viewport" navHotkey="[" navTierStorageKey="staff-nav" onNavChange={setNav} phoneNav="drawer"
+  sidebar={(
+    <Sidebar brand={brand} nav={nav === 'rail' ? 'rail' : 'full'}
+      actions={<><ModeToggle /><Menu trigger={<Button icon size="sm" variant="ghost" aria-label={t('tools')}><EllipsisIcon /></Button>}>…</Menu></>}
+      search={{ label: t('search'), shortcut: ['Mod', 'K'], onActivate: openPalette }}
+      footer={<AccountMenu collapsed={nav === 'rail'} user={{ name, sub: email, status: 'online' }} items={<>
+        <MenuItem href="/profile">{t('profile')}</MenuItem>
+        <MenuItem onSelect={signOut} tone="danger">{t('signOut')}</MenuItem>
+      </>} />}>
+      {navItems}
+    </Sidebar>
+  )}>
+  {page}
+</AppShell>
+```
+
+- `Sidebar actions` sit beside the brand (hidden in the rail); `search` is a row that opens your search and shows
+  its keys (it does not bind them: your command palette listens); `footer` is pinned to the bottom.
+- Key caps are for a keyboard: on a touch phone or tablet (`(hover: none) and (pointer: coarse)`) the kit draws
+  none, in the search row, Menu and CommandPalette rows, Tooltips, SearchSuggest and a Button's hint. What a
+  screen reader hears is unchanged (`aria-keyshortcuts`, the spoken keys and descriptions stay).
+- `AccountMenu`: avatar (photo, your node, or initials), name and a second line as a `Menu` trigger;
+  `collapsed` in the rail.
+- `navHotkey` switches full ↔ rail instantly, never while typing; `navTierStorageKey` remembers the tier before
+  the first paint and reports it through `onNavChange`.
+- `phoneNav="drawer"`: at 40rem and under, a menu button opens the sidebar in a start-side `Drawer`.
+
+#### Display preferences: theme, contrast, text size, motion, density (HAR-1372)
+
+```tsx
+// app/layout.tsx: before the stylesheets, so nothing flashes. The script sets attributes on <html>
+// before React hydrates, so <html> needs suppressHydrationWarning; under a Content-Security-Policy
+// give the inline script your per-request nonce (or allow its hash).
+<html lang="bs" suppressHydrationWarning>
+  <head>
+    <script nonce={nonce} dangerouslySetInnerHTML={{ __html: displayPreferencesScript('staff-display') }} />
+  </head>
+  <body>{children}</body>
+</html>
+
+// a settings page, or a dialog from AccountMenu
+<DisplayPreferences storageKey="staff-display" />
+// the header
+<ThemeSwitcher storageKey="staff-display" display="icons" />
+// your own control
+const { preferences, setPreference, resolvedTheme } = useDisplayPreferences({ storageKey: 'staff-display' });
+```
+
+The tokens read five attributes on `<html>`: `data-theme` (light / dark), `data-contrast="more"`,
+`data-text-scale="sm|lg|xl"`, `data-motion="reduce"` and `data-density="compact|comfortable"`. A choice applies
+at once (transitions are suspended for that frame), is stored, and `system` follows the OS. The head script and the
+hook read the same key and the same defaults; pass both the same. `useReducedMotion` honours `data-motion`.
+
+#### StatRow: a row of tiles that reflows
+
+```tsx
+<StatRow>{facts.map((f) => <Stat key={f.id} size="compact" {...f} />)}</StatRow>
+<StatRow className="uix-stat-row--hero">{kpis}</StatRow>  // 12rem tiles for 34 px values
+```
+
+`StatRow` (`.uix-stat-row`) puts as many tiles side by side as fit at 8.5rem each (12rem with
+`.uix-stat-row--hero`, or as soon as a hero tile is in the row; `minTileWidth` / `--stat-row-min` to
+choose), all the same height, down to one per row on a phone. A fixed column count squeezed six tiles
+into 320 px until their labels broke letter by letter. Labels now wrap at a space and break inside a
+word only when that word alone is wider than the tile.