@tensor_1/react 2.47.0 → 2.48.0

package/README.md

@@ -256,10 +256,39 @@ 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>
+```
+
 ### 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).
@@ -1166,3 +1195,443 @@ 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.
+- `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.

package/dist/{SchedulingCalendar-B6TakO2h.d.ts → SchedulingCalendar-WWyFL3Eo.d.ts}

@@ -2,6 +2,8 @@ import * as react from 'react';
 import { ReactNode } from 'react';
 import { CalendarWeekday } from './calendar-model.js';
 import { MoveProposal, MonthSpanLayout } from './scheduling-calendar-model.js';
+import { SchedulingSlotSelection } from './components/SchedulingResourceDay.js';
+import { SchedulingAvailabilityKind, SchedulingResource, SchedulingResourceSpan } from './scheduling-resource-model.js';
 
 interface TimeGridEntryContext {
     /** Whole text lines that fit in the item: 0 shows the markers only. */
@@ -236,6 +238,18 @@ interface SchedulingCalendarLabels {
     moveCancelled?: string;
     /** Announced when the time asked for does not exist that day. `{time}` is the time used instead. */
     gapForward?: string;
+    /** Names the resource day (HAR-983). `{date}` placeholder. */
+    resourceGrid?: string;
+    /** The words for the kinds of a resource span. */
+    availability?: Partial<Record<SchedulingAvailabilityKind, string>>;
+    /** Time of a resource that no span covers: no schedule, which is not free. */
+    noSchedule?: string;
+    /** A resource slot's or booking's accessible name. `{resource}`, `{start}`, `{end}`, `{kind}`, `{label}`. */
+    slotName?: string;
+    /** How to move in the resource day, read with it. */
+    resourceHint?: string;
+    /** The resource day with no resources. */
+    noResources?: string;
 }
 declare const DEFAULT_SCHEDULING_CALENDAR_LABELS: SchedulingCalendarLabels;
 interface SchedulingCalendarProps {
@@ -376,13 +390,48 @@ interface SchedulingCalendarProps {
     topLaneCap?: number;
     /** Lanes side by side in one day column of the time grid, at most. Fewer are used when the column is narrow. Default 4. */
     maxLanes?: number;
+    /**
+     * With `view="day"`, one column per resource (a practitioner, a room) instead of the time grid
+     * (HAR-983). Their stretches of the day come from `resourceSpans`; a time no span covers is
+     * shown as "no schedule", never as free.
+     */
+    resources?: SchedulingResource[];
+    /** The free, booked and off stretches of each resource, as the server composed them. */
+    resourceSpans?: SchedulingResourceSpan[];
+    /** Minutes per slot of the resource day: each free span is cut into bookable slots of this length. Default 15. */
+    slotMinutes?: number;
+    /** The first local time of the resource day's axis, `HH:MM`. Default `'07:00'`. */
+    dayStart?: string;
+    /** The local time the resource day's axis ends, `HH:MM`. Default `'19:00'`. */
+    dayEnd?: string;
+    /** Called by a click, Enter or Space on a free slot (its own start and end) or a booking. */
+    onSelectSlot?: (slot: SchedulingSlotSelection) => void;
+    /** Marks the slot or booking that holds this instant for this resource, e.g. while its popover is open. */
+    selectedSlot?: {
+        resourceId: string;
+        start: string;
+    };
+    /**
+     * `auto` (default): columns, and a list of one resource after another when the calendar is
+     * narrower than `resourceListBelow`. `columns` or `list` fixes one.
+     */
+    resourceLayout?: 'auto' | 'columns' | 'list';
+    /** The width in CSS pixels under which `auto` shows the list. Default 480. */
+    resourceListBelow?: number;
+    /**
+     * The first load shows skeletons; a refetch keeps what is on screen, dimmed and `aria-busy`
+     * (the resource day; the other views show `labels.loading` instead).
+     */
     loading?: boolean;
     error?: string;
     onRetry?: () => void;
     className?: string;
     labels?: Partial<SchedulingCalendarLabels>;
 }
-/** Month/week/agenda calendar for UTC ranges rendered in an explicit IANA time zone. */
-declare function SchedulingCalendar({ entries, anchorDate, timeZone, view: controlledView, onViewChange, onAnchorDateChange, onSelectEntry, overlays, onSelectOverlay, filter, renderEntry, locale, weekStartsOn, formatDate, formatInstant: formatInstantProp, maxEntriesPerDay, onShowMore, renderDayBadge, days: dayInfo, dayEntries, spanLayout, windowLaneCap, spanLaneCap, legend, legendCaption, showHeader, notice, emptyNote, onSelectDate, agendaGroups, agendaHeadingLevel, virtualizeAbove, monthDensity, timeGrid, now, canMove, step, onProposeMove, topLaneCrossMidnightMinutes, topLaneCap, maxLanes, loading, error, onRetry, className, labels: labelOverrides, }: SchedulingCalendarProps): react.JSX.Element;
+/**
+ * Month/week/day/agenda calendar for UTC ranges rendered in an explicit IANA time zone. With
+ * `resources`, the day view is one column per resource (HAR-983).
+ */
+declare function SchedulingCalendar({ entries, anchorDate, timeZone, view: controlledView, onViewChange, onAnchorDateChange, onSelectEntry, overlays, onSelectOverlay, filter, renderEntry, locale, weekStartsOn, formatDate, formatInstant: formatInstantProp, maxEntriesPerDay, onShowMore, renderDayBadge, days: dayInfo, dayEntries, spanLayout, windowLaneCap, spanLaneCap, legend, legendCaption, showHeader, notice, emptyNote, onSelectDate, agendaGroups, agendaHeadingLevel, virtualizeAbove, monthDensity, timeGrid, now, canMove, step, onProposeMove, topLaneCrossMidnightMinutes, topLaneCap, maxLanes, resources, resourceSpans, slotMinutes, dayStart, dayEnd, onSelectSlot, selectedSlot, resourceLayout, resourceListBelow, loading, error, onRetry, className, labels: labelOverrides, }: SchedulingCalendarProps): react.JSX.Element;
 
 export { DEFAULT_SCHEDULING_CALENDAR_LABELS as D, type SchedulingAgendaGroup as S, type TimeGridEntryContext as T, type SchedulingBand as a, SchedulingCalendar as b, type SchedulingCalendarDay as c, type SchedulingCalendarEntry as d, type SchedulingCalendarLabels as e, type SchedulingCalendarOverlay as f, type SchedulingCalendarProps as g, type SchedulingCalendarView as h, type SchedulingDatePart as i, type SchedulingEntryState as j, type SchedulingLegendItem as k, type SchedulingMarker as l, type SchedulingMarkerEmphasis as m, type SchedulingOverlayKind as n, type SchedulingOverlayPattern as o, type SchedulingStatus as p, SchedulingTimeGrid as q, type SchedulingTimeGridProps as r };

package/dist/announce.d.ts

@@ -0,0 +1,10 @@
+/** Create the polite region `announcePolite(…, from)` will use, ahead of its first message. */
+declare function ensureAnnouncer(from?: Element | null): void;
+/**
+ * Say `text` through a polite live region (`[data-uix-announcer]`): the page's, or the open
+ * dialog's when `from` is inside one. The region is cleared first and filled a moment later,
+ * so the same words twice are spoken twice; a newer message replaces one not yet spoken.
+ */
+declare function announcePolite(text: string, from?: Element | null): void;
+
+export { announcePolite, ensureAnnouncer };

package/dist/announce.js

@@ -0,0 +1,30 @@
+const timers = /* @__PURE__ */ new WeakMap();
+function ensureAnnouncer(from) {
+  liveRegion(from);
+}
+function liveRegion(from) {
+  if (typeof document === "undefined") return null;
+  const container = from?.closest("dialog") ?? document.body;
+  let region = container.querySelector(":scope > [data-uix-announcer]");
+  if (!region) {
+    region = document.createElement("div");
+    region.setAttribute("role", "status");
+    region.setAttribute("data-uix-announcer", "");
+    region.className = "uix-visually-hidden";
+    container.append(region);
+  }
+  return region;
+}
+function announcePolite(text, from) {
+  const el = liveRegion(from);
+  if (!el) return;
+  clearTimeout(timers.get(el));
+  el.textContent = "";
+  timers.set(el, setTimeout(() => {
+    el.textContent = text;
+  }, 0));
+}
+export {
+  announcePolite,
+  ensureAnnouncer
+};