@tensor_1/react 2.30.0 → 2.32.0

package/README.md

@@ -354,6 +354,52 @@ const icons: Record<EntityType, UixIcon> = { incident: SirenIcon, change: GitBra
 - **Accessibility:** decorative unless `label` is set. Never let an icon carry meaning alone; pair it with text.
 - **Bundle size:** each `<Name>Icon` is tree-shaken; one icon adds well under 3 KB minified. `<Icon name>` and `ICON_GLYPHS` load all of them.
 - **A glyph is missing?** Add its Lucide name to `scripts/icon-names.txt`, run `node scripts/generate-icons.mjs <lucide-react dir>` and release. Do not paste an SVG into a product.
+### SchedulingCalendar
+
+A month, week or agenda of UTC ranges in one explicit IANA zone (HAR-1347, HAR-1506). The calendar draws; the
+consumer owns every word, count and ranking.
+
+```tsx
+import { SchedulingCalendar, layoutMonthSpans, schedulingGridDays } from '@tensor_1/react';
+import { TriangleAlertIcon } from '@tensor_1/react/icons';
+
+// The item: one hue dimension (band), one state channel (status), markers with text.
+const entry = {
+  id: 'e1', title: 'Firewall rule update', start: '2026-10-06T08:00:00Z', end: '2026-10-06T09:00:00Z',
+  band: 'high',            // 'none' | 'low' | 'medium' | 'high' — only 'high' is filled
+  status: 'tentative',     // 'tentative' | 'committed' | 'live' | 'done' | 'dead' — line style, never a hue
+  markers: [{ id: 'm', label: 'Needs sign-off', emphasis: 'warning', icon: <TriangleAlertIcon /> }],
+  accessibleName: 'Firewall rule update, high, tentative, 6 October 10:00 to 11:00',
+};
+// A window: neutral, hatched, named, focusable. `global: false` never gets the global treatment.
+const hold = { id: 'w1', label: 'Quarter close', kindLabel: 'Hold', scopeLabel: 'Payroll services', pattern: 'cross',
+  start: '2026-10-04T22:00:00Z', end: '2026-10-09T22:00:00Z' };
+
+// Controlled month: the consumer ranks, cuts and counts; the calendar renders what it is given.
+const grid = schedulingGridDays('2026-10-07', 'month', 1);
+const spanLayout = layoutMonthSpans(spansInSalienceOrder, grid, { timeZone, weekStartsOn: 1 }); // lanes in the order given
+<SchedulingCalendar timeZone="Europe/Berlin" anchorDate="2026-10-07" showHeader={false}
+  entries={multiDayEntries} overlays={[hold]} spanLayout={spanLayout}
+  dayEntries={{ '2026-10-07': topThree }}                                        // already ranked and cut
+  days={{ '2026-10-07': { count: 50, overflowCount: 47, label: '50 items' } }}   // "+47 more", never entries.length
+  maxEntriesPerDay={3} onShowMore={(date) => openDay(date)}                      // a controlled day never expands in place
+  onSelectEntry={openItem} onSelectOverlay={openWindow} onSelectDate={openDayView}
+  legend={legendOfWhatIsOnScreen} legendCaption="Times in Europe/Berlin"
+  notice={truncated && <p>Showing the first 2,000 items.</p>} emptyNote="Nothing is scheduled this month." />
+```
+
+- **Drawn once.** An entry or window that covers several days is one bar per week row, in lanes above the chips
+  (`windowLaneCap`, `spanLaneCap`, default 2 each). Windows never take a chip slot. A row with more spans than lanes
+  shows "+N" and calls `onShowMore` with the first day that has a hidden span.
+- **Day membership is end-exclusive in `timeZone`**: 22:00–00:00 is on its start day only.
+- **Fixed geometry.** With `days` / `dayEntries` (or `maxEntriesPerDay` plus `onShowMore`) every cell keeps one
+  height: the head, the lane caps, the chip rows and the "+N" line. A chip reads `HH:MM title` (24 h, in the zone)
+  unless `renderEntry` replaces it.
+- **Colour.** Every calendar colour is named once at the top of `scheduling-calendar.css` (`--calendar-*`).
+- **Deprecated, still working in 2.x:** `entry.state` / `SchedulingEntryState`, `overlay.kind` /
+  `SchedulingOverlayKind` and the `previous` / `next` labels. An entry with `state` is no longer tinted: the two
+  problem states show a marker with the word for that state.
+
 ### SchedulingTimeline
 
 Lanes of bars on a time axis (HAR-1364; TENSOR's change day/week timeline, rollout Gantt rows and licence-renewal
@@ -377,3 +423,387 @@ markers). It pairs with `SchedulingCalendar`: same entry states, the same explic
 - **Keyboard:** one tab stop. ←/→ go to the previous or next bar in a lane, ↑/↓ to the nearest bar in the next lane, Home/End to the lane's ends, and Enter selects.
 - **Windows and markers:** `overlays` (`freeze`, `maintenance`, `blackout`; all lanes, or one with `laneId`), `markers` (a point in time) and `now` are drawn behind the bars and listed for screen readers.
 - Pure helpers are exported for tests and server code: `timelineTicks`, `placeSpan`, `layoutLane`, `shiftSpan`, `snapToStep`, `pixelsToMs`, `defaultTimelineStep`.
+
+### Calendar model (zoned days, hour slots, lanes)
+
+Pure functions for calendar geometry in one explicit IANA display zone (HAR-1504). They use only
+`Intl.DateTimeFormat`, never the process time zone, and never a fixed day length: DST days have 23 or 25
+hours. Every interval is half-open, `[start, end)`.
+
+```ts
+zonedDayBounds('2026-10-25', 'Europe/Berlin');   // { start: 2026-10-24T22:00Z, end: 2026-10-25T23:00Z } (25 h)
+zonedHourSlots('2026-10-25', 'Europe/Berlin');   // 25 slots; '02' twice, offsetLabel '+02:00' then '+01:00'
+zonedHourSlots('2026-03-29', 'Europe/Berlin');   // 23 slots; no '02'
+addZonedDays('2026-10-24T20:00Z', 1, 'Europe/Berlin');  // { instant: 2026-10-25T21:00Z, adjusted: null }
+addZonedDays('2026-03-28T01:30Z', 1, 'Europe/Berlin');  // 03:30 local, adjusted: 'gap_forward'
+zonedDaySpan('2026-10-10T22:00Z', '2026-10-11T22:00Z', 'Europe/Berlin'); // { start: '2026-10-11', end: '2026-10-12' }
+enumerateDateKeys({ start: '2026-10-11', end: '2026-10-12' });            // { dates: ['2026-10-11'], truncated: false }
+```
+
+- **Days:** `zonedDayBounds(dateKey, tz)` is the day's first instant and the next day's first instant, so the end of
+  one day is the start of the next. A day whose midnight is skipped starts at its first existing instant (01:00).
+- **Hour slots:** `zonedHourSlots(dateKey, tz)` gives one `{ instant, label, offsetLabel }` per real hour start.
+  `label` is the local hour (`'00'`–`'23'`); `offsetLabel` (`'+02:00'`) is set on both occurrences of a repeated
+  hour and is `null` otherwise.
+- **"+1 day":** `addZonedDays(instant, n, tz)` keeps the wall-clock time. A repeated wall time keeps the source's
+  offset; a skipped one moves forward once and returns `adjusted: 'gap_forward'`, so the caller can announce it.
+- **Day membership:** `zonedDaySpan(start, end, tz)` returns the days an entry touches as `[start, end)` date keys;
+  an entry ending at local 00:00 does not touch the next day. It throws a `RangeError` when `end` is not after
+  `start` and never swaps. `enumerateDateKeys(span, { limit })` lists them (default limit 370, `Infinity` for none)
+  and returns `truncated: true` instead of stopping silently.
+- **Lanes:** `packLanes(intervals, maxLanes, { order })` assigns first-fit lanes; overlapping intervals never share a
+  lane, touching ones may. Intervals that do not fit get `lane: null`, and each overlap cluster reports its
+  `laneCount` and `overflow`. `order: 'start'` (default) is greedy by start, then end, then id; `order: 'given'`
+  packs in input order, so a consumer's ranking decides who gets a lane.
+- **Top-N:** `rankOverflow(items, compare, n)` is a stable sort and cut: `{ visible, hidden }`. `hidden` counts only
+  what it was given; show the consumer's own total when it has one.
+- **Formatters:** `cachedDateTimeFormat(locale, options)` returns one shared `Intl.DateTimeFormat` per locale and
+  options shape. The model formats through it, so a 2,100-entry month builds at most a handful of formatters.
+- **Deprecated:** `zonedDateSpan` (end-inclusive, swaps inverted ends) and `enumerateDateSpan` (stops silently at
+  370) are unchanged in 2.x. Use `zonedDaySpan` and `enumerateDateKeys`.
+
+### FilterEditor (typed column filters)
+
+`FilterEditor` is the content of one column-filter popover with a typed value (HAR-1365; TENSOR's
+`table-filter-editor.tsx`, MOTUS's "+ filter"). `summarizeFilter` turns the applied value into the chip text.
+`FilterPopover` stays for the single-string case.
+
+```tsx
+const field: FilterField = { id: 'state', label: t('state'), kind: 'enum', options: states };
+<Popover anchor={chipRef} popover="manual">
+  <FilterEditor field={field} value={draft} onValueChange={setDraft} onApply={() => apply(field.id, draft)} onClear={() => clear(field.id)} />
+</Popover>
+<Chip onClick={edit} onRemove={remove}>{summarizeFilter(field, applied, { formatDate: formatDisplayDate })}</Chip>
+```
+
+| `kind` | Value | Editor |
+|---|---|---|
+| `enum` | `{ values: string[] }` | checkboxes; a diacritic-insensitive search above more than `searchThreshold` (8) options; Select all / Clear selection |
+| `text` | `{ operator, text }` | condition (`contains`, `not-contains`, `is`, `is-not`, `starts-with`) + text; Enter applies |
+| `number` | `{ operator, value, to? }` | condition (`eq`…`gte`, `between`) + value(s), optional `unit` |
+| `date-range` | `{ from?, to? }` | two date fields that bound each other |
+| `boolean` | `{ value?: boolean }` | Any / Yes / No (`trueLabel`, `falseLabel`) |
+| `reference` | `{ values: { value, label }[] }` | `onSearch(query)` → records, debounced (`searchDelay`), with loading, empty and error (retry) states; chosen records as removable chips |
+
+`isFilterEmpty`, `emptyFilterValue`, the operator lists and all words (`labels`) are exported, and the value is plain
+data for your own query string. Stale search results are ignored.
+
+**Presets (enum, HAR-1505).** `field.presets` names selections the product defines, e.g. a default scope. They
+render as toggle `Chip`s (`aria-pressed`) in a labelled group above the search box and options. Activating one
+replaces the selection with its `values`; the preset whose values equal the selection (as a set) is pressed, so
+ticking another option un-presses it. `summarizeFilter` then returns the preset's label (the `preset` summary
+label, default `'{label}'`; use `'{field}: {label}'` to keep the column name), and `matchFilterPreset(field, value)`
+returns the matching preset for your own use. The group's name is `labels.presets` (default "Presets").
+
+```tsx
+const state: FilterField = {
+  id: 'state', label: t('state'), kind: 'enum', options: states,
+  presets: [
+    { id: 'open', label: t('openWork'), values: ['new', 'open', 'pending'] },
+    { id: 'all', label: t('all'), values: states.map((s) => s.value) },
+  ],
+};
+```
+
+Every `FilterEditor` word can also come from `<UixLabelsProvider labels={{ filterEditor: { … } }}>`; an
+explicit `labels` prop still wins.
+### EntityPicker
+
+A form field that holds one record found by an async search (HAR-1366; TENSOR's `entity-picker.tsx` and its
+person, incident and CI pickers; MOTUS's author filter). Built on `SearchSuggest`.
+
+```tsx
+<Field label={t('assignee')} htmlFor="assignee" hint={t('assigneeHint')}>
+  <EntityPicker id="assignee" name="assignee_id" label={t('assignee')} value={assignee} onValueChange={setAssignee}
+    onSearch={(q) => api.people.search(q)} labels={{ none: t('choosePerson') }} />
+</Field>
+```
+
+- **Chosen:** the record shows in the field (title plus its last breadcrumb, or `renderValue`), with a × named "Clear {title}". Choosing the field again opens a fresh search; Escape with an empty query returns to the record.
+- **Searching:** debounced (`delay`, 250 ms) from `minQueryLength` (0) characters, with loading, empty and error states. **Retry is a list row**, so arrow keys reach it. Stale results are ignored. Focus returns to the field after a choice.
+- **Forms:** `name` posts the chosen id in a hidden input; `id` and the `Field` hint and error wire to the active control. `SearchSuggest` gains `inputId` and `inputDescribedBy` for the same purpose.
+
+### Lightbox
+
+A full-screen media viewer (HAR-1367; TENSOR's capture viewer, MOTUS's programme gallery and photo zoom).
+
+```tsx
+<Lightbox items={photos.map((p) => ({ src: p.url, alt: p.alt, caption: p.caption, width: p.w, height: p.h }))}
+  index={index} onIndexChange={setIndex} open={open} onClose={() => setOpen(false)} />
+```
+
+- **Moving:** previous/next buttons, ←/→, Home/End and a swipe on touch (`loop` wraps). An announced "{index} of {total}" counter and the caption sit under the media.
+- **Size:** "Show actual size" switches between fitted and natural size; the stage scrolls when zoomed.
+- **Video:** `kind: 'video'` renders a native player, which keeps its own arrow keys.
+- **Dialog:** native `<dialog>`. Focus starts on Close, Escape and a backdrop click close it, and focus returns to the opener. Every word is in `labels`.
+- **Image size:** pass `width` and `height` so an SVG or a slow image keeps its box.
+
+### FileUpload and Attachment
+
+`FileUpload` is a drop zone, file picker and upload list (HAR-984; TENSOR's attachment panel, MOTUS's photo intake). `Attachment` is a row for a file that is already stored (HAR-985).
+
+```tsx
+<FileUpload items={uploads} accept=".pdf,image/*" maxSize={20_000_000} maxFiles={10}
+  hint="PDF or photos, up to 20 MB"
+  onFilesAdded={(accepted) => accepted.forEach(startUpload)}
+  onRetry={retryUpload} onRemove={removeUpload} />
+
+<AttachmentList label={`Attachments (${files.length})`}>
+  {files.map((f) => (
+    <Attachment key={f.id} name={f.name} size={f.size} type={f.type} href={f.url} download
+      meta={`${f.addedBy} · ${f.addedAt}`} onRemove={() => confirmRemove(f)} />
+  ))}
+</AttachmentList>
+```
+
+- **The product uploads.** `onFilesAdded(accepted, rejected)` gets the files that passed `accept`, `maxSize` and `maxFiles` (counting `items`). Report progress, success and failure back through `items` (`status`, `progress`, `error`). Rejected files are listed in an alert, one sentence each.
+- **Keyboard:** "Choose files" is a real button, described by the `hint`. Dropping is an extra, not the only way in. `capture` opens the camera on phones.
+- **List:** each file shows its size and status. Uploads show a progress bar (indeterminate without `progress`), and failures show the reason and a Retry button. `previewUrl` shows a thumbnail, and `onAltChange` asks for alt text on images.
+- **Attachment:** the name is the link (`href`, `download`, `renderLink`). It has a quieter `meta` line, a `state` slot (e.g. a "Scanning" `StatusPill`), `actions`, `onRemove`, and `status` `loading` | `error` | `forbidden` (no link, and the reason shown). It's server-renderable.
+- Pure helpers: `formatFileSize`, `fileMatchesAccept`, `partitionFiles`, `fileKind`.
+
+### TextDiff
+
+A two-way diff of two texts (HAR-1368; TENSOR's knowledge-article version diff). `DiffViewer` stays the three-way configuration diff.
+
+```tsx
+<TextDiff before={v3.body} after={v4.body} beforeLabel={t('version', { n: 3 })} afterLabel={t('version', { n: 4 })}
+  label={t('bodyChanges')} context={3} />
+<TextDiff before={v3.title} after={v4.title} granularity="word" label={t('titleChanges')} />
+```
+
+- **Lines** (`granularity="line"`, the default): a Myers diff. Removed and added lines are paired with their closest counterpart, so a renumbered list still lines up, and only the changed words are marked inside a pair.
+- **Words** (`granularity="word"`): prose compared as one flow. Changed words across a space join into one change.
+- **Views:** `split` (the default) puts the versions side by side and stacks below about 36rem of container width. `unified` interleaves them.
+- **Not colour alone:** changes are `<del>` / `<ins>`, with a −/+ sign and a spoken "Removed:" / "Added:" (`labels`). Struck and underlined words mark changes inside a line.
+- **Long texts:** `context` keeps that many unchanged lines around each change. Longer runs fold behind "Show n unchanged lines", and focus moves to the first revealed line. Over `maxTokens` (20 000) a note replaces the diff. Past `maxEdits` (2 000) the changed middle shows as one replacement instead of stalling.
+- Pure model for tests and servers: `diffText`, `diffTokens`, `textDiffRows`, `tokenizeText`.
+
+### DashboardGrid
+
+The layout grid for dashboard widgets (HAR-1555; TENSOR's role dashboards). Pure layout: drag-and-drop, persistence and widget chrome stay in the product. Server-renderable.
+
+```tsx
+<DashboardGrid columns={{ base: 1, sm: 2, lg: 3 }} gap="md">
+  <DashboardGrid.Item><Stat label="Open incidents" value={42} /></DashboardGrid.Item>
+  <DashboardGrid.Item span={2}><Card title="Queue by team">…</Card></DashboardGrid.Item>
+  <DashboardGrid.Item span="full">
+    <Chart title="Resolved per hour" option={option} height="clamp(160px, 40cqi, 360px)" />
+  </DashboardGrid.Item>
+</DashboardGrid>
+```
+
+- **Columns follow the grid's own width**, not the viewport (a container query), so the same dashboard has fewer columns beside an open sidebar. Breakpoints: `sm` 36rem, `md` 48rem, `lg` 60rem, `xl` 80rem of grid width, sized for widgets of about 280–320 px (2 columns from 36rem, 3 from 60rem, 4 from 80rem). A breakpoint you leave out keeps the count of the next smaller one; a missing `base` is 1. Without `columns`: 1, 2 from `sm`, 3 from `lg`. Counts are 1–4.
+- **Spans:** `span={1}` (default), `span={2}` (clamps to the columns there are, so it is the whole row at one column), `span="full"` (`grid-column: 1 / -1`, the whole row at every width).
+- **Size-aware content:** each item is an inline-size container named `uix-dashboard-grid-item`. Give a Chart a height in `cqi` (a share of the item's width), or pass your own height per widget size; the Chart already redraws at the item's width. Use `@container uix-dashboard-grid-item (min-width: …)` for a card's own split layout. Widgets in one row share a height (the item's last child grows).
+- **`gap`:** `sm` (--uix-space-3), `md` (default, --uix-space-4), `lg` (--uix-space-6).
+- Refs reach the grid and item `<div>`s, and other props pass through. For an element you render yourself (a drag-and-drop library's sortable node, a server template), use `dashboardGridClassName(columns, gap)` and `dashboardGridItemClassName(span)`.
+- Plain HTML: `.uix-dashboard-grid` with `--cols-N` / `--{sm,md,lg,xl}-cols-N` and `--gap-sm|lg`, items `.uix-dashboard-grid__item` with `--span-2` / `--full`. Every direct child of the grid is a cell.
+
+### Select draws its own list
+
+`Select` (HAR-1572) no longer opens the browser's dropdown. It is the WAI-ARIA select-only combobox: a `<button role="combobox">` trigger and a UIx-drawn listbox in the top layer (a bottom sheet on phones). The props did not change, so existing call sites keep working:
+
+```tsx
+<Select id="status" name="status" value={status} onChange={(e) => setStatus(e.target.value)}>
+  <option value="" disabled hidden>Choose a status</option>
+  <optgroup label="Active">{active.map((s) => <option key={s.id} value={s.id}>{s.name}</option>)}</optgroup>
+</Select>
+<Select options={teams} value={team} onValueChange={(v) => setTeam(v as string)} searchable="auto" placeholder={t('team')} />
+<Select multiple name="labels" options={labels} defaultValue={['network']} />
+<Select loadOptions={(q, signal) => api.owners(q, { signal })} searchable options={[owner]} value={owner.value} />
+```
+
+- **Forms:** a visually hidden `<select data-uix-select-proxy>` holds `name`, `required`, `form`, `multiple` and the value. `ref` points at it, so `FormData`, `form.reset()`, autofill, react-hook-form `register` and `Controller` work as before. `onChange(e)` gets `e.target.value`, and a failed `required` focuses the trigger.
+- **Keyboard:** ↑ ↓ Home End PageUp PageDown and typing move (repeat one letter to cycle). Enter, Space, Tab and Alt+↑ choose. Escape closes and keeps the value. With `multiple`, Space toggles and Delete clears.
+- Plain Select for up to about 12 options, `searchable` for longer lists, `EntityPicker` or `SearchSuggest` for records.
+
+### Gaps from the TENSOR migration (2.32.0)
+
+Found on 2026-10-07/08 while TENSOR moved its hand-built UI onto 2.31.0. Everything is optional
+unless a line says **Behaviour change**.
+
+#### Anchored overlays stay inside the viewport
+
+A `Popover` / `useAnchoredPosition` panel that fits neither above nor below its anchor used to
+leave the viewport (a 384 px panel under a trigger in the middle of a 640 px phone screen got a
+negative `top`). It now slides over the anchor and stays inside the 8 px padding, after a scroll
+and after a resize as well. Once the anchor itself has left the viewport the panel follows it out.
+
+```tsx
+<Popover anchor={triggerRef} capHeight>…</Popover>          // taller than the screen: capped, scrolls inside
+useAnchoredPosition(anchorRef, panelRef, {
+  open,
+  capHeight: true,                 // max-height = viewport − 2 × padding (a smaller own max-height still applies)
+  onAnchorHidden: () => setOpen(false),   // what `Popover closeWhenAnchorHidden` is built on
+  shiftMainAxis: false,            // opt out: the 2.31.0 placement
+});
+computePosition(anchor, size, viewport).mainAxisRange   // [min, max] the top is kept in, or null
+```
+
+With CSS anchor positioning the browser moves a box with its anchor *after* resolving `top`, so
+no value can hold it at the viewport limit while the page scrolls. While a panel is held at the
+limit, or within 64 px of it, the hook writes fixed coordinates instead; they cannot drift.
+
+#### Menu: radio and checkbox items, attributes, Escape on the trigger
+
+```tsx
+<Menu trigger={<Button>Preset</Button>}>
+  <MenuItem id="manage" data-action-id="preset.manage" onSelect={manage}>Manage presets</MenuItem>
+  <MenuSeparator />
+  <MenuRadioGroup label="Dashboard preset" value={preset} onValueChange={setPreset}>
+    <MenuItemRadio value="mine">My queue</MenuItemRadio>
+    <MenuItemRadio value="team">Team</MenuItemRadio>
+  </MenuRadioGroup>
+  <MenuItemCheckbox checked={zebra} onCheckedChange={setZebra}>Alternating rows</MenuItemCheckbox>
+</Menu>
+```
+
+- `MenuItemRadio` / `MenuItemCheckbox` render `menuitemradio` / `menuitemcheckbox` with
+  `aria-checked` and a check column. The menu opens on the checked radio item.
+- A click or Enter follows `closeOnSelect` (radio: `true`, checkbox: `false`); Space changes the
+  state and leaves the menu open.
+- Every item kind forwards `id` and `data-*` to its own element.
+- Escape (and Tab) on the trigger closes a menu that has no item to focus (every item disabled).
+- The menu is capped to the viewport and scrolls.
+
+#### CollapsibleSection and Steps
+
+```tsx
+<CollapsibleSection title="Details" defaultOpen persistKey={`incident:${id}:details`} persistStorage="local">…</CollapsibleSection>
+<CollapsibleSection title="SLA" compact headingLevel={3} lazy openRequest={jumpToSla}>…</CollapsibleSection>
+```
+
+- `defaultOpen` is the starting state; with `persistKey`, what the person chose wins over it. A
+  passed `open` is the same starting state and no longer overrides the remembered state at
+  mount; it still applies when the parent changes it.
+- `persistStorage`: `'session'` (default) or `'local'`.
+- `openRequest` already set at mount is honoured (a deep link), and every request moves focus to
+  the summary. `undefined` and `0` mean "no request yet".
+- `compact`: a quiet row inside a card. `headingLevel`: the title is a real heading and the body a
+  `role="region"` named by it.
+
+```tsx
+<Steps progress={false} headingLevel={2} label="New change">
+  <Step title="What is changing" description="One sentence is enough."><Field …/></Step>
+  <Step title="When"><Field …/></Step>
+</Steps>
+```
+
+`progress={false}` is a numbered list of sections that are all on screen: no state is drawn or
+announced, and each step's children are its content, in a group named by the step title. Without
+it `Steps` is the progress indicator it was.
+
+Also: `DescriptionItem termProps` / `descriptionProps` (attributes for the `<dt>` / `<dd>`), and
+`closeLabel` is optional on `PromptDialog` and `ConfirmDialog`.
+
+#### Tabs: a name for the tablist
+
+```tsx
+<Tabs aria-label="Inbox filters" value={tab} onChange={setTab}>…</Tabs>
+<Tabs aria-labelledby="news-heading" overflow="scroll" …>…</Tabs>
+```
+
+`Tabs` passes HTML attributes to its `role="tablist"` element, in both overflow modes.
+
+#### Segmented: one tab stop, arrow keys, a radiogroup mode
+
+```tsx
+<Segmented aria-label="Row density" value={density} onChange={setDensity}>…</Segmented>
+<Segmented selection="radio" aria-labelledby="theme-label" value={theme} onChange={setTheme}>…</Segmented>
+```
+
+- **Behaviour change:** a `Segmented` is one tab stop (the selected option, or the first enabled
+  one). Arrow Right/Down and Left/Up move and select, wrapping; Home / End jump; Left and Right
+  swap in a right-to-left group. Before, every option was a tab stop and no key was handled.
+- `selection="radio"` renders `radiogroup` / `radio` / `aria-checked` instead of `group` /
+  `aria-pressed`, for a setting with exactly one value.
+
+#### useVirtualRows
+
+```tsx
+const v = useVirtualRows(rows, { rowHeight: 44, estimatedViewportHeight: 600, enabled: rows.length > 0 });
+```
+
+- `estimatedViewportHeight`: the height to assume until the scroller is measured (and whenever it
+  measures 0), so a 5,000-row table mounts with one window, not 5,000 rows.
+- When the row count shrinks under a large `scrollTop`, the window is clamped to the new count in
+  the same render: the spacer is never taller than the list.
+- `enabled: false` returns every row and no spacers. Rows are windowed when
+  `rows.length > threshold` (default 100).
+
+#### RuleBuilder for a flat AND-list
+
+```tsx
+<RuleBuilder value={rule} onChange={setRule} fields={fields} operators={operators}
+  conditionsOnly combinator="and" allowGroups={false} checks={{ emptyGroup: false }} labels={t.ruleBuilder} />
+<RuleBuilder … readOnly />              // the builder, every control disabled
+<RuleBuilder … readOnly="summary" />    // one sentence
+```
+
+- The built-in validation messages are labels (`issueEmptyGroup`, `issueNoActions`,
+  `issueMissingField`, …) and `checks` turns individual checks off.
+- `conditionsOnly`: no "Then" block; `actions` is then optional.
+- `combinator` fixes every group to one value (shown as text, never emits the other);
+  `hideCombinator` removes the control. `allowGroups={false}` hides "Add group".
+- **Behaviour change:** `readOnly` renders the builder with its controls disabled, not a sentence.
+  The sentence is `readOnly="summary"`, and its words are labels.
+- `UixLabelsProvider labels={{ ruleBuilder }}` translates every builder below it.
+
+#### Chip
+
+```tsx
+<Chip ref={chipRef} onClick={openEditor} onRemove={clear}
+  bodyProps={{ 'aria-haspopup': 'dialog', 'aria-expanded': open, 'aria-controls': editorId }}>Status: Open</Chip>
+<Chip href="/incidents" current renderLink={link}>Incidents</Chip>
+```
+
+- The × is named from `UixLabelsProvider` `chip.remove` (`'{label} entfernen'`); `removeLabel`
+  still wins.
+- 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.
+
+#### FileUpload and Attachment
+
+- A long unbroken file name no longer widens `FileUpload` past its container.
+- Both read `UixLabelsProvider` (`fileUpload`, `attachment`); a `labels` prop wins per word.
+- `sizeBase={1024}` counts in 1024s, `formatSize` takes the product's formatter, and
+  `formatFileSize(bytes, locale, { base: 1024, units })` does the same outside a component.
+
+#### Alert, Note, StatusPill, PromptDialog, Popover
+
+```tsx
+<Alert ref={errorRef} tone="info" title="…" actions={<Button size="xs" variant="ghost">Details</Button>} onDismiss={hide}>…</Alert>
+<StatusPill size="lg" tone="success" dot>Operational</StatusPill>
+<PromptDialog … multiline destructive error={serverError} />
+<Popover anchor={userRef} openOnHover>…</Popover>
+```
+
+- `Alert`: `onDismiss` + `dismissLabel` (`UixLabelsProvider` `alert.dismiss`), a trailing `actions`
+  slot, a forwarded ref, and a text column that wraps a long title at 320 px.
+- `Note tone={undefined}` and `tone="neutral"` are the default look.
+- `StatusPill size`: `'sm' | 'md' | 'lg'`.
+- `PromptDialog`: `multiline` (a textarea; Ctrl/⌘+Enter submits), `destructive` (a danger submit,
+  `role="alertdialog"`), an `error` slot, `role`. The field takes focus when the dialog opens.
+- `Popover openOnHover`: opens on pointer or focus on its anchor, stays while either is on the
+  anchor or the popover, closes after both left and on Escape.
+
+#### Spinner, Meter, Heartbeat
+
+```tsx
+<Spinner size="sm" label="Uploading" />
+<Meter tone="neutral" value={42} label="Option A, 42% of votes" />
+<LiveIndicator state="live">Live</LiveIndicator>   <Heartbeat state="danger" label="Connection lost" />
+```
+
+- `Spinner size="sm"` is 16 px.
+- `Meter tone="neutral"` (grey) and `tone="accent"` (brand) are fills for a proportion that is not
+  a status; both clear 3:1 against the track in light and dark, and no tone word is spoken.
+- `Heartbeat` is the pulsing dot (`live`, `idle`, `warning`, `danger`), decorative unless it has a
+  `label`; `LiveIndicator` adds the state in text. The ring stops under `prefers-reduced-motion`.
+
+#### ViewMenu
+
+The density options no longer break a label inside a word at phone width ("Großzügig"); options
+that do not fit one row wrap as whole options.

package/dist/attachment-labels.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The words of an `Attachment` row. In a module of its own, with no "use client": the
+ * server-renderable `Attachment` and its client parts both read it, and a server component can
+ * still import the defaults as plain values.
+ */
+interface AttachmentLabels {
+    /** Remove button. `{name}`. */
+    remove: string;
+    /** Download link name when `download` is set. `{name}`. */
+    download: string;
+    loading: string;
+    forbidden: string;
+}
+declare const DEFAULT_ATTACHMENT_LABELS: AttachmentLabels;
+
+export { type AttachmentLabels, DEFAULT_ATTACHMENT_LABELS };

package/dist/attachment-labels.js

@@ -0,0 +1,9 @@
+const DEFAULT_ATTACHMENT_LABELS = {
+  remove: "Remove {name}",
+  download: "Download {name}",
+  loading: "Loading\u2026",
+  forbidden: "You do not have access to this file."
+};
+export {
+  DEFAULT_ATTACHMENT_LABELS
+};

package/dist/calendar-model.d.ts

@@ -19,9 +19,149 @@ declare function startOfMonth(value: string): string;
 /** A weekday in `Date.getUTCDay()` numbering: 0 = Sunday … 6 = Saturday. */
 type CalendarWeekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
 declare function buildMonthGrid(month: string, weekStartsOn?: CalendarWeekday): CalendarDay[];
+/**
+ * A shared `Intl.DateTimeFormat` for `locale` and `options`. Formatters are expensive to
+ * build, so one instance is kept per locale and options shape (key order does not matter);
+ * the cache holds up to 64 shapes and drops the oldest past that.
+ */
+declare function cachedDateTimeFormat(locale: string | readonly string[] | undefined, options?: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
+/** The calendar date (`YYYY-MM-DD`) of an instant in `timeZone`. */
 declare function zonedDateKey(instant: string | Date, timeZone: string): string;
+/**
+ * The 24-hour wall-clock time (`HH:MM`) of an instant in `timeZone`. It reads the same
+ * cached formatter as the zone math, so it adds no `Intl.DateTimeFormat` instance.
+ */
+declare function zonedTimeOfDay(instant: string | number | Date, timeZone: string): string;
+interface ZonedDayBounds {
+    /** The first instant of the day in the zone (local 00:00, or the first existing time after a gap). */
+    start: Date;
+    /** The first instant of the next day: `end` of D equals `start` of D + 1. */
+    end: Date;
+}
+/**
+ * The half-open interval `[start, end)` of a calendar day in `timeZone`. DST days are 23 or
+ * 25 hours long; a day whose midnight does not exist starts at its first existing instant.
+ */
+declare function zonedDayBounds(dateKey: string, timeZone: string): ZonedDayBounds;
+interface ZonedHourSlot {
+    /** The real instant the local hour starts. */
+    instant: Date;
+    /** The local hour, two digits (`'00'` … `'23'`). */
+    label: string;
+    /**
+     * The UTC offset (`'+02:00'`) when this local hour occurs twice in the day (clocks went
+     * back), set on both occurrences; otherwise `null`.
+     */
+    offsetLabel: string | null;
+}
+/**
+ * One entry per real hour start in the day `[start, end)` in `timeZone`: 24 on most days,
+ * 23 when clocks go forward (no slot for the skipped hour) and 25 when they go back (the
+ * repeated hour twice, each with an `offsetLabel`).
+ */
+declare function zonedHourSlots(dateKey: string, timeZone: string): ZonedHourSlot[];
+interface ZonedDayShift {
+    instant: Date;
+    /** `'gap_forward'` when the target wall-clock time did not exist and moved forward past the gap. */
+    adjusted: 'gap_forward' | null;
+}
+/**
+ * Moves an instant by `days` calendar days in `timeZone`, keeping its wall-clock time
+ * ("+1 day" is the same local time on the next day, whether that day has 23, 24 or 25
+ * hours). A wall time that occurs twice keeps the source's offset when it can (else the
+ * earlier one). A wall time that does not exist moves forward by the gap, once, and the
+ * result says so (`adjusted: 'gap_forward'`).
+ */
+declare function addZonedDays(instant: string | Date, days: number, timeZone: string): ZonedDayShift;
+/**
+ * Calendar days `[start, end)` as date keys: `end` is the first day NOT covered.
+ * Produced by `zonedDaySpan`, read by `enumerateDateKeys`.
+ */
+interface ZonedDaySpan {
+    start: string;
+    end: string;
+}
+/**
+ * The calendar days an instant interval `[start, end)` touches in `timeZone`, end-exclusive:
+ * an entry ending exactly at local 00:00 occupies only the day before. Throws a `RangeError`
+ * when `end` is not after `start`; it never swaps the ends.
+ */
+declare function zonedDaySpan(start: string | Date, end: string | Date, timeZone: string): ZonedDaySpan;
+/**
+ * The date keys of a `ZonedDaySpan` (`[start, end)`), at most `limit` of them (default
+ * 370; `Infinity` for no limit). `truncated` is true when the span has more days than were
+ * returned, so a long span is never cut silently. Throws a `RangeError` on an inverted span.
+ */
+declare function enumerateDateKeys(span: ZonedDaySpan, options?: {
+    limit?: number;
+}): {
+    dates: string[];
+    truncated: boolean;
+};
+/**
+ * Inclusive date keys of an instant interval, with inverted ends swapped.
+ * @deprecated Use `zonedDaySpan`, which is end-exclusive (an entry ending at local 00:00
+ * does not paint the next day) and throws on an inverted interval instead of swapping.
+ * The behaviour here is unchanged in 2.x; changing it follows the contract-change process (E13).
+ */
 declare function zonedDateSpan(start: string, end: string, timeZone: string): ZonedDateSpan;
+/**
+ * Date keys of an inclusive span, stopping silently after `limit` (370).
+ * @deprecated Use `enumerateDateKeys`, which reads an end-exclusive `ZonedDaySpan` and
+ * reports `truncated` instead of stopping silently. The behaviour here is unchanged in 2.x (E13).
+ */
 declare function enumerateDateSpan(span: ZonedDateSpan, limit?: number): string[];
+interface LaneInterval {
+    id: string;
+    /** Half-open `[start, end)`: ISO string, epoch ms or Date. */
+    start: string | number | Date;
+    end: string | number | Date;
+}
+interface LanePlacement {
+    /** 0-based lane, or `null` when the interval did not fit in `maxLanes`. */
+    lane: number | null;
+    /** Index into `PackedLanes.clusters`. */
+    cluster: number;
+}
+interface LaneCluster {
+    /** Ids of one run of transitively overlapping intervals, by start, then end, then id. */
+    ids: string[];
+    /** Lanes the cluster uses (≤ `maxLanes`); a renderer divides the width by this. */
+    laneCount: number;
+    /** Intervals of the cluster that got no lane. */
+    overflow: number;
+}
+interface PackedLanes {
+    lanes: Record<string, LanePlacement>;
+    clusters: LaneCluster[];
+    /** Intervals that got no lane, over all clusters. */
+    overflow: number;
+}
+interface PackLanesOptions {
+    /**
+     * `'start'` (default): greedy first-fit by start, then end, then id, so the result does
+     * not depend on input order. `'given'`: first-fit in input order, so the consumer's
+     * ranking decides which intervals get a lane when there are not enough.
+     */
+    order?: 'start' | 'given';
+}
+/**
+ * Assigns half-open intervals to at most `maxLanes` lanes, first-fit. Two intervals that
+ * overlap never share a lane; two that only touch (`a.end === b.start`) may. Intervals
+ * that do not fit get `lane: null` and count towards their cluster's `overflow`. A
+ * zero-length interval occupies its start instant. Throws on `end < start` (it never
+ * swaps) and on a duplicate id.
+ */
+declare function packLanes(intervals: readonly LaneInterval[], maxLanes: number, options?: PackLanesOptions): PackedLanes;
+/**
+ * Sorts a copy of `items` with `compare` (stable) and cuts it after `n`. `hidden` is the
+ * number of items not shown, so it is a true total only when `items` is complete; a
+ * consumer that knows a larger total shows that instead.
+ */
+declare function rankOverflow<T>(items: readonly T[], compare: (a: T, b: T) => number, n: number): {
+    visible: T[];
+    hidden: number;
+};
 declare function selectRangeDate(current: DateRangeValue, date: string): DateRangeValue;
 declare function isDateInRange(date: string, value: DateRangeValue): boolean;
 declare function isDateUnavailable(date: string, options: {
@@ -30,4 +170,4 @@ declare function isDateUnavailable(date: string, options: {
     isDisabled?: (date: string) => boolean;
 }): boolean;
 
-export { type CalendarDay, type CalendarWeekday, type DateRangeValue, type ZonedDateSpan, addCalendarDays, addCalendarMonths, buildMonthGrid, enumerateDateSpan, isDateInRange, isDateUnavailable, selectRangeDate, startOfMonth, toDateKey, zonedDateKey, zonedDateSpan };
+export { type CalendarDay, type CalendarWeekday, type DateRangeValue, type LaneCluster, type LaneInterval, type LanePlacement, type PackLanesOptions, type PackedLanes, type ZonedDateSpan, type ZonedDayBounds, type ZonedDayShift, type ZonedDaySpan, type ZonedHourSlot, addCalendarDays, addCalendarMonths, addZonedDays, buildMonthGrid, cachedDateTimeFormat, enumerateDateKeys, enumerateDateSpan, isDateInRange, isDateUnavailable, packLanes, rankOverflow, selectRangeDate, startOfMonth, toDateKey, zonedDateKey, zonedDateSpan, zonedDayBounds, zonedDaySpan, zonedHourSlots, zonedTimeOfDay };