@stcn52/pro 0.0.0-stage → 0.2.1

package/docs/components.md

@@ -0,0 +1,1706 @@
+# Component reference
+
+Every component below ships from `@stcn52/pro`. Props are the ones exported from
+`src/`, states are the ones actually styled, and the keyboard column is what the
+implementation handles — not an intention.
+
+Conventions used throughout:
+
+- **Controlled by default where it matters.** Anything with a selection
+  (`Nav`, `Tree`, `Segment`, `Select`, `DataTable`, `DetailSheet`) takes a value
+  and an `onChange`; the host owns the state and the URL.
+- **Refs are forwarded** on every form control (`Button`, `Input`, `Select`,
+  `Checkbox`, `Switch`), so a page can `searchRef.current?.focus()` — that is how
+  `⌘K` works.
+- **One focus ring.** Defined once in `base.css` as `:focus-visible` with
+  `outline: 2px solid var(--accent)`; components never invent their own.
+- **Tokens only.** No component hard-codes a colour, radius or duration.
+
+---
+
+## 1. Actions
+
+### `Button`
+
+`variant: 'primary' | 'default' | 'text' | 'danger'` · `size: 'sm' | 'md' | 'lg'` ·
+`icon?` / `iconAfter?` (`IconName`) · `block?` · `loading?` · ref forwarded.
+
+- `loading` renders an inline spinner **and** sets `disabled` + `aria-busy`, so
+  the label width never jumps.
+- Icon-only (no children) adds `pro-btn--icon-only` for a square hit area.
+- States: hover, pressed (0.5px sink), focus-visible, disabled, loading.
+
+### `ActionButton`
+
+`icon` (required) · `label` (required) · `size` · `active?` · `tone?: 'default' | 'accent'`.
+
+The bare icon button used by the chrome, toolbars and rows. `label` becomes both
+`aria-label` and `title`; `active` sets `aria-pressed` and the accent tint. If you
+pass `children` it becomes a pill-shaped button with an icon.
+
+### `SplitButton`
+
+`label` · `onPrimary` · `menuLabel` · `menuItems?` · `menuOpen?` / `onToggleMenu?`.
+
+The product's "New ▾" control. The caret owns its own `Popover` + `Menu`
+anchored to itself, so a host only supplies the items; pass `menuOpen` +
+`onToggleMenu` to control it instead.
+
+---
+
+## 2. Forms
+
+### `Input` / `Textarea` / `SearchInput`
+
+`size?: 'md' | 'lg'` · `invalid?` · ref forwarded. `invalid` sets
+`aria-invalid` and the red border; `SearchInput` adds a leading magnifier and a
+`suffix` slot (used for the `⌘K` hint), and forwards a ref.
+
+### `Field`
+
+`label?` · `required?` · `hint?` · `error?` · `htmlFor?`.
+
+Wraps any control: generates an `id` with `useId` when none is given, wires
+`label[for]`, renders the required asterisk, and shows `error` (with an icon,
+`role="alert"`) **instead of** the hint. The rule the pages follow: pass an error
+only after the first blur or a submit attempt, and clear it the moment the value
+becomes valid.
+
+### `Select` / `MultiSelect`
+
+`value: string | null` · `options: { value, label, icon?, color?, disabled? }[]` ·
+`onChange` · `placeholder?` · `size?` · `invalid?` · `disabled?`.
+
+- Trigger shows `pro-select-trigger--placeholder` when nothing is chosen; the
+  caret rotates with `aria-expanded`.
+- Options can be rich (a `StatusTag`, a colour dot), which is how the status
+  pickers render.
+- Opening from the keyboard puts focus on the first item; choosing one closes
+  the layer by requesting `onOpenChange(false)`.
+- `MultiSelect` takes `values: string[]` and an optional `label` before the count badge.
+- `searchable` defaults to false for Select and true for MultiSelect. `searchValue`
+  controls the query; `onSearch` reports typing and a nonempty query reset on close.
+  `searchPlaceholder` customizes the search field. Arrows enter enabled choices;
+  MultiSelect also supports arrow navigation between checkboxes.
+- Default filtering reads text from rich label children. Supply `searchText` for
+  opaque custom labels, or `filterOption(query, option)` for a custom predicate.
+  `filterOption={false}` leaves filtering to a remote host. Optional `filterSort`
+  sorts within each group without changing the supplied options.
+- A controlled query stays host-owned; update `searchValue` in response to
+  `onSearch`. Search is ignored when `searchable={false}`.
+
+- `virtual` opts into fixed-height windowing. `listHeight` defaults to 256 and
+  `itemHeight` to 36. Match `itemHeight` to your custom row geometry. Arrows,
+  Home/End and typeahead navigate the complete result set; a focused row remains
+  mounted during wheel scrolling. Use `virtual={false}` to render all options.
+- `MultiSelect` supports `mode="tags"`: Enter or a checkbox commits a trimmed
+  custom value. Created tags remain selectable and clearable through `values`.
+  `tokenSeparators={[',', ';']}` commits complete tokens from typing/paste and
+  leaves the trailing fragment in the search field. In multiple mode, tokens
+  resolve existing values/label text only. IME text is committed after composition.
+- `maxCount` limits distinct values in MultiSelect, including values absent from
+  the current options. At the limit, new choices are disabled, selected choices
+  remain removable, and excess batch tokens are ignored. Disabled selections
+  remain locked. Tags mode always displays the search field.
+
+- Both controls forward a native button ref and attributes, accept controlled
+  `open` / `onOpenChange` or `defaultOpen`, and keep search intact when a host
+  refuses to close. Queries reset only after the popup actually closes.
+- Groups use `{ key?, label, options, disabled? }`; their disabled flag applies
+  to every child. Values remain unique strings. Group headers count toward
+  virtual geometry but not option positions or keyboard selection.
+- `labelInValue` changes single values to `{ value, label? } | null` and multiple
+  values to arrays of those objects. Selected labels survive remote option
+  replacement; unknown values display their supplied label or literal value.
+  `defaultValue` / `defaultValues` enable uncontrolled selection.
+- Single `allowClear` adds a separate accessible clear button and emits `null`;
+  its callback therefore accepts `string | null`. Without it, the existing
+  string-only callback contract is unchanged. MultiSelect keeps its default
+  Clear footer and in multiple mode preserves values absent from current options; explicit
+  `allowClear={true}` also clears unknown values and `allowClear={false}` hides
+  it. Tags mode also clears created tags by default. Disabled selections stay locked.
+- `optionRender(option, { index })` customizes presentation without replacing
+  native option keyboard/disabled semantics; keep interactive controls outside
+  the rendered option. `labelRender` customizes the single selected label;
+  MultiSelect `tagRender({ value, label, disabled, closable, onClose })` renders
+  accessible removable tags beside the trigger without nested buttons.
+- `loading`, `error` and `notFoundContent` present host-owned async state;
+  requests, cancellation and option updates remain the host's responsibility.
+  Existing options remain usable while loading.
+- Klun retains separate Select/MultiSelect, string keys, native button refs and
+  dialog/menu or checkbox semantics. AntD's numeric values, combobox imperative
+  handle, popup internals and full prop naming are not drop-in compatible.
+
+### `Checkbox` / `Switch`
+
+`Checkbox`: `label?` · `indeterminate?` · `compact?`. The indeterminate flag is
+applied to the DOM node in an effect (React has no prop for it); the box is
+`.pro-checkbox__box` so the focus ring can sit on the visual square.
+`Switch`: `label` (required) · `size?: 'sm' | 'md'`; renders `role="switch"` and a
+36×20 track (20×16 in `sm`).
+
+---
+
+## 3. Overlays
+
+### `Dialog`
+
+`open` · `onClose` · `title` · `tools?` · `footer?` · `size?: 'sm'|'md'|'lg'|'xl'` ·
+`dismissable?` · `bodyClassName?`.
+
+Portalled to `<body>`; locks body scroll; **traps Tab** (wraps at both ends);
+`Esc` and scrim click only close when `dismissable` (false while a form is
+dirty); focuses the first control on open and **restores focus to the opener** on
+close.
+
+### `Popover`
+
+`anchor: HTMLElement | null` · `open` · `onClose` · `placement?` · `matchAnchorWidth?` ·
+`dismissOnOutsideClick?` · `autoFocus?`.
+
+A single floating layer: measured against the anchor, flipped when the preferred
+side has no room, clamped to the viewport, re-measured on scroll/resize. Hides
+itself with `visibility` until it has coordinates (so it never flashes at 0,0),
+focuses its first control when opened from the keyboard, and returns focus to the
+anchor when Escape closes it. Provides `usePopoverClose()` so nested menus can
+dismiss it.
+
+### `Menu`
+
+`items: { id, label, icon?, hint?, danger?, disabled?, checked?, onSelect? }[]` ·
+`searchable?` · `onSelect?`.
+
+`role="menu"` with `menuitem` / `menuitemradio` (the latter when `checked` is
+defined). Keyboard: **↑ ↓** move, **Home/End** jump, a printable character runs
+typeahead, **Enter/Space** activate (native button), and choosing an item closes
+the surrounding popover. `hint` is the right-aligned shortcut/count slot.
+
+### `ContextMenu`
+
+`items` · `onOpen?` · render-prop `children({ onContextMenu })` · `aria-label`.
+
+Opens at the **pointer** (not the element rect), flipped and clamped to an 8px
+viewport margin, portalled to `body` so `overflow: hidden` never clips it.
+Dividers, disabled and danger items; `role="menu"` with roving focus, ↑↓,
+Home/End and typeahead. The **Menu key** and **Shift+F10** open it on the focused
+trigger; Escape closes and returns focus to the element that was right-clicked;
+the native menu is suppressed only while a non-empty menu shows. `useContextMenu(items)`
+is the imperative form — `openAt(x, y, context)` → `onSelect(context)`.
+
+A press inside a **stacked** layer (`.pro-popover`, `.pro-portal`,
+`[role=listbox]`, `[role=menu]`) does not dismiss the parent — without that guard
+a `Select` inside a `Popover` could never be used with a mouse.
+
+### `Tooltip`
+
+`label` · `delay = 400` · `placement?: 'top' | 'bottom'`.
+
+Shows on hover after the delay and **immediately on focus**; hides on blur,
+Escape and any scroll. Portalled, `role="tooltip"`, non-interactive.
+
+### `Menu` submenus and dividers
+
+An item may carry `items` — it then renders a caret, `aria-haspopup="menu"` /
+`aria-expanded`, and opens those entries beside its own row while the parent menu
+stays open (choosing in the child closes the whole tree). `ArrowRight` opens it,
+`ArrowLeft` closes it and returns the focus to the row. A `divider: true` item
+renders the hairline between groups that `ContextMenuItem` already had.
+
+### `Toast` — `ToastProvider` + `useToast()`
+
+```ts
+useToast().push(tone, message, options?)   // returns the id, so the host can dismiss it early
+useToast().dismiss(id)
+```
+
+- **tone** `'info' | 'success' | 'warning' | 'error'` — the hairline and the glyph
+  carry it (`warning` is the product's amber; the sprite has no warning mark, so
+  it reuses the filled disc, and `icon` overrides the glyph outright).
+- **options** `{ duration?, title?, action?, variant?, closeable?, icon? }`. The
+  third argument also still takes a bare number, which is the duration.
+  `duration: 0` keeps a toast until it is dismissed; `title` prints a bold line
+  with the message as the description under it; `action: { label, onClick }` adds
+  one inline command (Undo, View, Retry) and does **not** dismiss anything itself.
+- **placement** on the provider: `top-left | top-center | top-right | bottom-left |
+bottom-center | bottom-right`. The stack grows away from the pinned edge and the
+  toast animates in from it. The default, `top-center`, is where the product
+  raises its messages.
+- **variant** `'surface'` (the white card, default) or `'filled'` (the message on
+  the tone's own colour; amber keeps dark ink because white on `--amber-500` is
+  illegible).
+- **`max`** caps the stack; the oldest toast leaves first.
+
+One live region (`aria-live="polite"`) exists **before** any content arrives;
+each toast has a dismiss button (unless `closeable: false`) and **pausing on
+hover** (the timer is cleared on `mouseenter`, restarted at 1.5s on
+`mouseleave`). Outside a provider `useToast` degrades to `console.info`, so the
+library never crashes a host.
+
+---
+
+## 4. Display
+
+| Component                          | Props that matter                                            | Notes                                                                                                                                                                                                                                                                                                                             |
+| ---------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Icon`                             | `name`, `size`, `label?`, `style?`                           | 146 glyphs taken verbatim from the product's sprite. `size` sets `font-size` (the SVG is 1em). `label` → `role="img"`; otherwise `aria-hidden`. An unknown name warns and renders an empty box instead of throwing.                                                                                                               |
+| `Tag`                              | `variant: solid \| soft \| outline`, `color`, `icon`, `pill` | `StatusTag` maps 12 status words onto the measured palette; `LevelTag` renders the L0–L4 badge; `CountTag` the counted badge.                                                                                                                                                                                                     |
+| `Avatar`                           | `name`, `src`, `size: xs \| sm \| md \| lg`, `title`         | Initials + a deterministic colour hashed from the name, so the same person is always the same colour. `AvatarStack` overlaps up to `max` and shows `+N`; `AvatarPlaceholder` is the dashed "not set" ring.                                                                                                                        |
+| `Card`                             | `title?`, `extra?`, `flush?`                                 | Section shell. `KeyValue` renders label/value rows; `Progress` takes 0–1 (clamped) with a tone and `aria-valuenow`; `Metric` is the label/value/delta/trend/icon tile.                                                                                                                                                            |
+| `BarChart` / `Donut` / `Sparkline` | `data[]`, sizing props                                       | No chart dependency: bars are flex heights, the donut is a `conic-gradient` with a punched hole and a legend, the sparkline is an SVG polyline.                                                                                                                                                                                   |
+| `Crumbs`                           | `items: { id, label, onClick? }[]`                           | Marks the last item `aria-current="page"`.                                                                                                                                                                                                                                                                                        |
+| `Divider`                          | `orientation`                                                | Horizontal / vertical hairline on the divider token.                                                                                                                                                                                                                                                                              |
+| `States`                           | see below                                                    | `EmptyState` (`variant: empty \| error \| offline`, `title`, `hint`, `action`, `compact`) always renders **title + explanation + action**; `ErrorState` answers what/why/what-now and offers a retry; `EmptyArt` is the product's `</null>` illustration; `Skeleton`, `TableSkeleton`, `LoadingBlock`, `InlineSpinner`, `Banner`. |
+
+---
+
+## 5. Navigation
+
+| Component            | Props                                                                                                      | Behaviour                                                                                                                                                                                                                                           |
+| -------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Nav`                | `items`, `value`, `onChange`, `overflowItems?`                                                             | The product tab strip. The 2px ink bar is **measured from the live DOM** (and re-measured with a `ResizeObserver`) so variable-width and CJK labels stay centred. **← →** move the selection and focus; extra destinations fold into a "More" menu. |
+| `Tree` / `TreeGroup` | `nodes`, `value`, `onSelect`, `defaultExpanded`                                                            | Accessible tree outline with optional controlled state, checks, lazy loading, virtual scrolling, and reorder callbacks.                                                                                                                             |
+| `Sidebar`            | `title`, `operations?`, `footer?`, `defaultWidth = 260`, `minWidth`, `maxWidth`, `collapsed?`              | The category column, **resizable** by dragging the gutter (pointer capture) or with ← → on the handle, which exposes `role="separator"` + `aria-value*`.                                                                                            |
+| `Segment` / `Chip`   | `options`/`pressed`, `onChange`                                                                            | Compact view switchers and filter pills; both use `aria-pressed`.                                                                                                                                                                                   |
+| `Pagination`         | `page`, `pageSize`, `total`, `onPageChange`, `onPageSizeChange?`, `pageSizeOptions?`, `left?`, `children?` | A windowed page list with an ellipsis, a page-size menu, and a "Go to" field (digits only, commits on Enter, clamped). Prev/next disable at the bounds.                                                                                             |
+
+---
+
+## 6. `DataTable<T>` — the grid everything sits on
+
+```tsx
+<DataTable
+  columns={columns} rows={rows} rowKey={rowKey}
+  status="ready"                     // loading | error | ready
+  sort={sort} onSortChange={setSort}
+  selectable selectedKeys onSelectedKeysChange
+  groupBy={(row) => row.status}      // grouped <tbody> blocks, foldable
+  expandedGroups={open} onExpandedGroupsChange={setOpen}   // or uncontrolled
+  showIndex rowActions onRowClick
+  emptyState={…} errorState={…} loadingRows={8} loadingColumns={[…]}
+  ariaLabel="All ideas"
+/>
+```
+
+- **Five states are structural**: `loading` renders skeleton rows at the real row
+  height, `error`/`empty` render the supplied nodes in an overlay, `ready` with
+  rows renders the grid, and any column can carry edge content.
+- Column definition: `{ id, header, width?, align?, sortable?, fixed?, render(row, index), className? }`.
+  `fixed: 'left' | 'right'` pins a column while the grid scrolls sideways; the
+  component measures the offsets from the numeric `width`s of the columns pinned
+  before it, and the outer column of each pinned run carries the edge shadow. A
+  non-numeric width still pins, it just cannot be offset. The checkbox and actions
+  columns join their edge **only when a data column is frozen** — an unfrozen grid
+  has no frozen edge, and pinning them anyway left a shadow and an opaque
+  background with nothing to mark.
+- **The selection bar covers the header row.** While rows are selected the table
+  renders `SelectionBar` over the header (50px, full width, white), so the columns
+  never move: the box centres in the pick column, the count starts at the first
+  data column, and the covered header is `inert` — its select-all is not rendered
+  twice. Cancel clears the selection.
+- A **selected row** wears `--surface-table-row-selected` — the head's neutral tone,
+  not the accent: the product's grid keeps the accent for the checkbox, so a
+  selected row still reads as a row. Everything else keeps `--surface-selected`.
+- **Commands can live inside a cell**: `Column.actions` (`[{ id, icon, label,
+onSelect }]`) renders boxes over the cell's right edge, revealed by the pointer
+  being on that cell, each with its tooltip. The row's own commands (`rowActions`)
+  are a different layer and sit at the row's **end** — the actions cell is
+  zero-width and must stay out of the positioning chain, or the overlay anchors to
+  the scrollport instead of the row.
+- The pointer is **two levels**: the row under it takes the light wash (the pick
+  cell's gutter with it) and the cell under it the accent tint — the row reads as a
+  row, the cell as the target.
+- The pick cell's **checkbox** appears when that cell is pointed at (or the row is
+  selected, holds the cursor, or a bulk selection is running) — never because the
+  pointer happens to be somewhere else in the row.
+- The bar is exactly the header row's height (`--table-head-height`, shared with
+  `thead th`): it stands in for that row, so it must not be taller than it.
+- The pick column is the grid's **gutter**: it wears the header's tone
+  (`--surface-table-head`) on every row, while a hovered or selected row keeps its
+  own colour there too.
+- **The grid is drawn as a grid**: every column carries a hairline on its right, so
+  the columns are divided as well as the rows. The filler and the structural cells
+  (pick, row actions, header tools) draw no trailing edge — they are not columns.
+- **The grid behaves like a spreadsheet.** `cursor` turns the keyboard cursor into
+  a **cell**: ← → walk the columns, ↑ ↓ the rows, Home/End jump to the ends of a
+  row, Enter opens the record, Space toggles its selection; focus follows the
+  cursor through a roving tabindex (one tab stop for the whole grid). Hovering
+  lights up the cell under the pointer, never the row.
+- **Selection needs a writer.** The 44px pick column keeps its row number whenever
+  `selectable` is on, but the checkbox (and the select-all box) only renders when
+  `onSelectedKeysChange` is given — a control that cannot write is worse than no
+  control. A column that declares `sortable` is disabled with a title when the
+  host passed no `onSortChange`.
+- The pick cell is the product's: the row number at rest, the checkbox on hover,
+  on a selected row, while a bulk selection is active, and on the **cursor row**
+  (the keyboard's hover — the number steps aside only when a checkbox exists).
+- **The column menu** (`onColumnCommand`): each data column's header grows the
+  product's ⋯ (on hover or focus) with Sort by (a submenu: Ascending / Descending
+  / Clear sort, the active one checked when the column is sorted), Move left,
+  Move right (disabled at the ends), Insert left, Insert right, Freeze or Unfreeze
+  and Remove this column. The library reports a `ColumnCommand` and changes
+  nothing: the host rewrites its `columns` and hands the array back, exactly like
+  `sort` / `onSortChange`.
+- **The bulk bar is built here**, not in a page. `bulk` supplies the data and the
+  write for the product's commands; the component owns the bar, the submenus, the
+  round-robin spread, the confirmation and the dialog:
+
+  ```tsx
+  bulk={{
+    statuses:    { options, apply(keys, value) },
+    baselines:   { options, apply(keys, id) },      // "Move in baseline"
+    schedules:   { options, apply(keys, id) },      // "Schedule"
+    distribute:  { people, apply(key, person) },    // round-robin, one write per row
+    properties:  { fields, initialValues?, title?, apply(keys, values) },
+  }}
+  ```
+
+  The order is the product's — Update status, Move in baseline, Schedule,
+  Distribute workitems, Edit properties — then anything `bulkActions(keys)` adds,
+  then the workbench's More (export / delete) and Cancel. Only the capabilities the
+  host supplied appear. Items sharing a `group` fold into one submenu (named after
+  the group, icon from `groupIcon`); an item with no group stays a button of its
+  own, keeping its label, icon and handler.
+
+- **Frozen columns belong to the view.** `ListView.frozen` is the list of column
+  ids pinned to the left edge (the product's "frozen columns"), kept next to
+  `sort` and `group` because it is part of the view: `ListWorkbench` applies
+  `fixed: 'left'` to those columns and answers the column menu's Freeze /
+  Unfreeze itself, while Move / Insert / Remove rewrite the host's `columns` array
+  and leave through `onColumnCommand`. The demo freezes `id`, which is how the
+  product's grid opens: the checkbox column and the ID scroll together and the
+  rest goes under them. Host-defined `column.fixed` remains host-owned: Unfreeze
+  forwards to `onColumnCommand`, and the host updates `columns` to remove it.
+  Without that callback the workbench locally unpins the column for this session.
+  Selected export requires every selected record to be present in `rows`; missing
+  records produce an error rather than an incomplete file.
+- **The keyboard cursor is the cell.** `cursor` makes the body one tab stop whose
+  unit is the **cell** — ← → walk the columns, ↑ ↓ the rows, Home / End jump to
+  the ends of the row, Enter opens the record, Space toggles its row's selection
+  when the host can write one, a pointer click parks the cursor on the cell it
+  landed in, and focus rides with the cursor through a roving tabindex. The
+  cursor is clamped when the rows shrink under it, and it follows the columns too,
+  so removing one cannot leave it pointing at a cell that is gone.
+  `ListWorkbench` turns it on, which is what the product's grid does; without it
+  every row that has an `onRowClick` is its own tab stop.
+- **A widget inside a cell keeps its own keys.** The row's key listener sits on
+  the `<tr>`, so everything pressed inside a cell bubbles to it; the grid answers
+  only when the key is not the widget's (`src/components/table/keyboard.ts`). A
+  rename field takes its space and keeps its caret, an in-cell editor walks its
+  own text, and a `Column.actions` box answers Enter itself instead of opening the
+  record. The rule is a list of roles — `input`, `button`, `a[href]`,
+  `[contenteditable]`, the combobox / listbox / textbox roles — so a host's own
+  editor inside a cell gets the same treatment without having to remember
+  `stopPropagation`.
+- **The frozen geometry is shared.** The pinned offsets, the edge shadow and the
+  skeleton rows all read the same measured offsets
+  (`src/components/table/geometry.ts`), so a loading grid does not jump sideways
+  when the data lands, and the row cursor stays put.
+- **Density** `'default'` (45px rows, the measured grid) or `'compact'` (36px
+  rows and header, `--text-sm` cells). Compact also reserves the actions column —
+  a 36px row has no room for the floating command overlay — which is what
+  `.pro-table__cell--actions` right-aligns.
+- **Groups fold** from their own header (`aria-expanded`), uncontrolled and open
+  by default, or controlled through `expandedGroups` / `onExpandedGroupsChange`.
+  String/number results are wrapped in a truncating span automatically, so a
+  value like `SLC-T1` never wraps and the row keeps its measured 52px pitch.
+- Sorting is three-state (`asc → desc → none`) and sets `aria-sort`; the header
+  is a real `<button>`.
+- Row checkboxes are a **hover affordance** (hidden until hover/selection/focus);
+  the select-all header checkbox supports `indeterminate`.
+- Rows are keyboard-activatable when `onRowClick` is given (`Enter`/`Space`) and
+  announce via a live region.
+
+---
+
+## 7. Ship surface
+
+| Component                                | Props                                                                                                                                                                                            | Behaviour                                                                                                                                                                                                                                                                                                                             |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AppRail`                                | `items`, `footerItems?`, `activeId?`                                                                                                                                                             | The 60px product switcher; the active item gets the lighter band and `aria-current="page"`.                                                                                                                                                                                                                                           |
+| `AppHeader` / `ProductHeader`            | `search`, `searchRef`, `actions`, `tabs`, `activeTab`, `onTabChange`, `overflowTabs`, `starred`, `onToggleStar`, `products?`, `onSelectProduct?`, `onCollapseSidebar?`, `sidebarCollapsed?`      | Products level vs workbench level. `searchRef` is what `⌘K` focuses; `search.onSubmit` fires on Enter; the product name opens a switcher when `products` is given; the outdent control reports its pressed state.                                                                                                                     |
+| `HeaderActions`                          | `onCreate?`, `onHelp?`, `onNotifications?`, `unread?`, `user`                                                                                                                                    | The `+`, `?`, bell (with a dot badge) and avatar cluster; the avatar's click receives the event so the host can anchor a menu to it.                                                                                                                                                                                                  |
+| `BrandMark`                              | `size?`                                                                                                                                                                                          | The four-dot product mark, drawn inline so the brand colour stays under our control.                                                                                                                                                                                                                                                  |
+| `ListHeader`                             | `title`, `titleIcon?`, `actions?`                                                                                                                                                                | The 48px strip above a grid.                                                                                                                                                                                                                                                                                                          |
+| `ListToolbar`                            | `search`, `count?`, `fields?`, `rules?`, `onRulesChange?`, `sortFields?`, `sort?`, `onSortChange?`, `groupFields?`, `group?`, `onGroupChange?`, `onToggleExpand?`, `expanded?`, `extraControls?` | Search, then Filter / Sort / Group / More, with the count pinned right and active filters rendered as removable chips. Opening the filter builder on a blank slate seeds one condition, as the product does.                                                                                                                          |
+| `FilterPanel` / `FilterChip`             | `fields`, `rules`, `onRulesChange`                                                                                                                                                               | Field / condition / value rows with add, clear-all and apply.                                                                                                                                                                                                                                                                         |
+| `DetailSheet`                            | `kind`, `code`, `title`, `tools?`, `properties?`, `tabs`, `activeTab`, `onTabChange`, `aside`, `composer?`, `onClose`                                                                            | The entity panel that covers everything right of the rail: identity bar, title, property strip, tabs, main column, metadata rail. `DetailSection` is a collapsible rail group, `DetailField` a labelled row, `Feed` a comment/activity timeline, `FeedFilter` its chip bar, `CommentComposer` the composer with a mention affordance. |
+| `TypeBadge`                              | `kind` (11 entity kinds)                                                                                                                                                                         | The coloured square in front of every entity title. `TitleCell` = badge + truncating title with a completed strikethrough; `ProductCell` = module icon + name + lock; `StarButton`, `QuickStart`, `TableBanner`, `SelectionBar` fill out the chrome.                                                                                  |
+| `BoardView` / `RoadmapView` / `DocSplit` | `columns` / `periods`+`lanes` / `tree`+children                                                                                                                                                  | Kanban columns, the quarter timeline grid, and the document tree + body split.                                                                                                                                                                                                                                                        |
+
+---
+
+## 8. Extracted composites (third pass)
+
+These nine components were store-coupled inside the demo site and are now pure and
+controlled, so any host can drive them. Their store wiring lives in the demo's
+`src/app/adapters/*`.
+
+| Component             | Controlled props                                                      | Behaviour kept                                                                                                                                          |
+| --------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CommentThread`       | `comments`, `currentUser`, `onAdd`, `onUpdate`, `onRemove`, `onReact` | replies nest, inline edit with an "edited" marker, delete confirmation naming the comment, emoji reactions with `aria-pressed`, `@mention` highlighting |
+| `AttachmentUpload`    | `files`, `onUpload`, `onRemove`, `maxSizeMb`                          | drag-and-drop + picker, per-file progress that completes, oversize refused before reading, attached rows with preview and unlink                        |
+| `LinkPicker`          | `targets`, `selected`, `candidates`, `onLink`, `onUnlink`             | dialog with a target segment, search, already-linked rows disabled, current links grouped with unlink                                                   |
+| `FilePreview`         | `file`, `open`, `onClose`                                             | md/txt/csv document view, csv table, image frame, unsupported-type state, zoom, real download                                                           |
+| `TransitionsTimeline` | `entries`, `statuses`, `currentStatus`                                | newest-first rail, flow strip, `old → new` chips, status-coloured dots, real empty state                                                                |
+| `EntityDialog`        | `fields`, `initialValues`, `onSubmit`                                 | two-column sheet, blur-then-validate, reset on `open` only (typing never wiped), drag/scroll guard                                                      |
+| `ShareDialog`         | `value`, `onChange`, `onSave`, `onCopy`                               | visibility, copyable link, expiry menu, scheduled export with validation                                                                                |
+| `ReportCanvas`        | `widgets`, `onChange`, `loading`                                      | drag reorder, 4/6/12 width, keyboard ▲▼, remove confirmation, empty state, live-region announcements                                                    |
+| `RoadmapEditor`       | `lanes`, `periods`, `bars`, `onChange`                                | drag between quarters, ←/→ moves, inline rename, recolour, zoom, weekend toggle, bounded weekend maths                                                  |
+
+## 9. Extracted in the fourth pass
+
+Lifted out of the demo site once its own copies had drifted into four variants of
+the same thing. Everything below is pure: the store, the router and the demo's
+seed data stay in the host.
+
+| Component         | Props that matter                                                                                                                                                      | Behaviour kept                                                                                                                                                                                                                                                                                                             |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DetailBlock`     | `title?`, `actions?`, `children`, `className`                                                                                                                          | The content block a detail sheet is written with — heading row plus optional right-aligned actions — so a page never reaches for `pro-detail-block__*` itself.                                                                                                                                                             |
+| `DetailTool`      | `icon?`, `label?`, `children`, `onClick`                                                                                                                               | The compact tool in the identity bar ("Attachments", "Links", "Export"). With only `label` it is icon-only and the label becomes its accessible name; tooltips stay with the host.                                                                                                                                         |
+| `EditableText`    | `title`, `text`, `onSave`, `rows`, `label`, `editSeed`, `paragraphs`, `note`, `readOnly`, `editing`/`draft` (controlled or not)                                        | Read view, editor and Cancel/Save row in one place: uncontrolled by default so two blocks on a sheet never share state, liftable when a host owns the state machine, and a blank draft re-commits the current text rather than blanking a record.                                                                          |
+| `EntityPicker<T>` | `rows`, `rowKey`, `value`, `onChange`, `onConfirm`, `linked`, `variant` (`list` \| `table`), `scopes`, `search`, `fields`/`rules`/`sortFields`, `hint`, `confirmLabel` | "Select ideas" in both shapes the product uses: the compact tick list (a plan picking what it scores) and the workbench table with a scope tree (a roadmap picking from the whole product). `linked` is what turns ticks into `N to link · M to unlink`, and the dialog is only dismissable when nothing would be written. |
+| `ScatterPlot`     | `points: { id, label, x, y, name?, render? }[]`, `xLabel`, `yLabel`, `title`, `extra`, `onSelect?`, `emptyState`, `height`                                             | The Plan matrix: percentage-positioned points with computed ticks, so a point can never fall outside the frame. No chart dependency; points are `role="img"` with the value in their accessible name unless `onSelect` makes them buttons.                                                                                 |
+| `ProjectWizard`   | `types`, `members`, `owner`, `existingKeys?`, `belongsToOptions?`, `categoryOptions?`, `onSubmit(draft)`, `onClose`                                                    | The three-step `New project` modal: the type preview pane, the type cards with arrow-key roving focus, blur-then-validate details, the member step with its own roster dialog, and the discard guard.                                                                                                                      |
+
+| `AccountMenu` | `user: { name, email? }`, `items`, `label?` | The account popover body: identity row, then the menu. The host keeps the anchor and the popover. |
+| `ShortcutsDialog` | `open`, `onClose`, `shortcuts: { keys, label }[]`, `title?` | The keyboard help sheet — `<kbd>` on the left, the action on the right. |
+| `QuickStartDialog` | `open`, `onClose`, `steps`, `checked`, `onToggle`, `onGo?`, `onReset?`, `intro?` | The getting-started checklist: progress bar, one tickable row per step, and a "go" action for the steps that lead somewhere. |
+
+Alongside them: `VoteCount`, `QuickStart` grew `done` / `total` for the checklist
+counter, `Tag` grew `tone="accent"` and `size="sm"` for the quarter chip, and
+`primaryComponents` / `componentLine` moved in with the wizard.
+
+## 10. Hooks and helpers
+
+| Export                                                                                          | Use                                                                                                     |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `useToast()`                                                                                    | Push a toast from anywhere under `ToastProvider`.                                                       |
+| `useControllableState({ value, defaultValue, onChange })`                                       | The pattern behind every controlled/uncontrolled component.                                             |
+| `usePopoverClose()`                                                                             | Lets a menu close the popover that hosts it.                                                            |
+| `useAnchorRef()` · `useSelectAnchor()`                                                          | Keep a trigger element in state so an anchored layer can measure it.                                    |
+| `formatListTime`                                                                                | `Today 15:44` / `Yesterday 09:12` / `Tuesday 09:12` / `Mar 3` — the product's relative list timestamps. |
+| `formatDateTime` · `formatDay` · `formatNumber` · `formatCount` · `formatCompact` · `pluralize` | All through `Intl`; nothing is hand-formatted.                                                          |
+| `cx` · `statusColor` · `avatarColor` · `initials` · `nextRuleId`                                | Class joining, status→token mapping, deterministic avatar colours, initials, filter-rule ids.           |
+
+## 11. Inline editors, the assistant and the newer surfaces
+
+The components added after the fourth pass, in the order a host meets them.
+
+| Component                                         | Props that matter                                                                                                                                                                                                 | Behaviour                                                                                                                                                                                                                                                                                                             |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PeoplePicker`                                    | `tabs`, `value`, `onPick`, `searchPlaceholder`, `emptyHint`, `onClose`                                                                                                                                            | The inline assignee editor the grid opens on a cell: the person already assigned starts the cursor (or `Unassigned`), type to filter, ↑↓ walk the rows, Enter picks. Returns `null` for the `Unassigned` row.                                                                                                         |
+| `QuickSelect`                                     | `options`, `value`, `onPick`, `placeholder`, `allowClear`, `renderOption`, `onClose`                                                                                                                              | The enum cell editor: the field is the control, the list is portalled, typeahead jumps to an option, Escape closes, and `allowClear` adds the row that empties the field.                                                                                                                                             |
+| `QuickText`                                       | `value`, `onCommit`, `display`, `trigger`, `maxLength`, `onClose`                                                                                                                                                 | The inline rename editor. `trigger` is `click` or `dblclick`; `display` is normally the very node the column already draws, so opening the editor changes nothing but the input. An unchanged value never commits.                                                                                                    |
+| `useListCursor` / `useSelectAnchor`               | `count` / —                                                                                                                                                                                                       | The two shared pieces behind those editors: the cursor arithmetic that keeps ↑↓ inside a shrinking list, and the anchor ref a portalled list measures against.                                                                                                                                                        |
+| `ContextMenuList` / `useContextMenu`              | `items`, `quick`, `aria-label` / `items`                                                                                                                                                                          | The menu the right-click layer renders, and its imperative form (`openAt(x, y, context)`) for a host that owns the gesture itself.                                                                                                                                                                                    |
+| `IconAvatar`                                      | `icon`, `label?`, `tone`, `size`                                                                                                                                                                                  | The avatar shell carrying a glyph instead of initials — a row whose leading mark identifies a kind of record. Decorative unless `label` is given.                                                                                                                                                                     |
+| `RichTextToolbar`                                 | —                                                                                                                                                                                                                 | The inert rich-text strip that sits above a description textarea (the editor itself is out of scope).                                                                                                                                                                                                                 |
+| `AiPanel` / `PingMark`                            | `open`, `messages`, `onSubmit`, `pending`, `suggestions`, `quickChips`, `onClose`                                                                                                                                 | The assistant side panel: a `role="dialog"` whose transcript is one `role="log"`, a composer that submits on Enter, suggestion cards and quick chips that fill the composer. It never invents a reply — the host owns the transcript and the thinking state.                                                          |
+| `SidebarCollapseProvider` / `useSidebarCollapsed` | `collapsed`                                                                                                                                                                                                       | Collapsing a sidebar is a shell decision, so a shell wraps its page tree once and every `Sidebar` inside follows; a `collapsed` prop on one sidebar still wins.                                                                                                                                                       |
+| `ListWorkbench<T>`                                | `rows`, `columns`, `view` + `onViewChange`, `selection`, `title`/`noun`, `status`, `searchText`, `matches`, `compare`, `views`, `boardView`, `enumFields`/`textFields`/`assigneeField`, `bulkActions`, `onDelete` | The whole list screen in one component: header, toolbar (search / filter / sort / group / view switch), the five states, inline cell editors, selection with its bulk bar, pagination and the row commands. Everything it cannot decide alone — how to search, filter, compare, open, export — arrives as a callback. |
+| `DEFAULT_SHARING`                                 | —                                                                                                                                                                                                                 | The value a report's sharing starts from (`ReportSharing`): visibility, link, expiry, schedule, hour, recipients, format.                                                                                                                                                                                             |
+
+## Additional common components
+
+### `Radio` / `RadioGroup`
+
+`Radio` forwards its input ref and native input attributes, with a `label` slot.
+`RadioGroup` takes string-valued `options`, `value` / `defaultValue`, `onChange`,
+`name`, `disabled`, `required`, and `orientation`. An `aria-label` is required.
+Same-name native radios provide arrow-key selection, Space activation and form submission.
+Each group gets a unique name when omitted.
+
+### `Tabs`
+
+`items: { key, label, children, disabled? }[]`, `activeKey` / `defaultActiveKey`,
+`onChange`, `keepMounted`, and a required `aria-label`. Left/Right wrap past disabled
+tabs; Home/End select the first/last enabled tab. One tab is in the Tab sequence.
+Linked tab panels retain their content when `keepMounted` is true; otherwise inactive
+content unmounts. A removed or disabled active key displays the first enabled tab.
+
+### `Collapse`
+
+`items: { key, label, children, disabled? }[]`, `activeKeys` / `defaultActiveKeys`,
+`onChange`, and `accordion`. Native buttons respond to Enter/Space and expose
+`aria-expanded` / `aria-controls`. Accordion opens at most one panel. Hidden content
+remains mounted to preserve input state.
+
+### `Badge`
+
+`count`, `overflowCount` (99), `showZero`, `dot`, `label`, and optional `children`.
+Counts above the limit display `99+` while retaining the full accessible count.
+Zero is hidden by default; negative and non-finite counts are hidden. Children
+receive an attached badge. Supply a descriptive `label` for dots.
+
+Reference: [Ant Design component library](https://github.com/ant-design/ant-design).
+These are independent token-based implementations, not drop-in antd replacements.
+
+### `Slider`
+
+Native single-thumb `input[type="range"]`, with forwarded ref and input attributes.
+`min` (0), `max` (100), `step` (1), native `value` / `defaultValue`, `disabled`,
+`name`, and `onChange(event)` work like `Input`. Supply a visible `Field` label or
+`aria-label`. Arrow keys, Home/End, rounding, bounds and form submission are native
+browser behaviour. No custom multi-thumb range or tooltip is provided.
+
+### `Steps`
+
+`items: { key, title, description?, disabled? }[]`, zero-based `current`,
+`status: 'process' | 'error'`, `orientation`, optional `onChange(index)`, and a required
+`aria-label`. An ordered list exposes the current step with `aria-current="step"`
+and names each step's status. Passing `current={items.length}` marks all complete;
+out-of-range indices are clamped. With `onChange`, native buttons allow Enter/Space
+activation and respect disabled steps; the host controls progression and validation.
+
+### `Alert`
+
+`message`, `description`, `type: 'info' | 'success' | 'warning' | 'error'`, `showIcon`,
+`action`, `closable`, `closeLabel`, `open` / `defaultOpen`, `onOpenChange`, `onClose`.
+Persistent inline feedback with `role="alert"` for errors and `role="status"` otherwise.
+Closing uses a labelled native button, supports Enter/Space, and reports visibility
+changes. For temporary notifications use `useToast`; for table strips use `Banner`.
+
+References: [Slider](https://ant.design/components/slider/),
+[Steps](https://ant.design/components/steps/), [Alert](https://ant.design/components/alert/).
+
+### `CheckboxGroup`
+
+`options: { value, label, disabled? }[]`, string-array `value` / `defaultValue`,
+`onChange`, `name`, `disabled`, `orientation`, and required `aria-label`.
+Reuses `Checkbox`; Tab reaches enabled choices and Space toggles them.
+Native same-name checkbox inputs submit multiple form values. Selection is
+preserved when options change; the host owns removal of obsolete selections.
+
+### `PasswordInput`
+
+Reuses `Input` and forwards its ref, value, native input attributes, `size`, and
+`invalid`. Visibility uses `visible` / `defaultVisible` (false), `onVisibleChange`,
+`showLabel` / `hideLabel`. A labelled toggle supports Enter/Space and exposes
+`aria-pressed`; pointer toggles keep focus in the field. `disabled` disables both
+controls. Works with `Field`; supply the appropriate password `autoComplete` value.
+
+### `Rate`
+
+Whole-star rating from 0 to 5. `value` / `defaultValue`, `onChange(number)`,
+`disabled`, `readOnly`, `allowClear` (true), `clearLabel`, `name`, and required
+`aria-label`. Reuses native `RadioGroup` for arrow navigation and Space selection.
+The clear button resets to zero. Read-only mode exposes a labelled image without
+interactive controls. Non-finite values display zero; others round and clamp.
+Half-star input and hover previews are not implemented.
+
+References: [Checkbox](https://ant.design/components/checkbox/),
+[Input](https://ant.design/components/input/), [Rate](https://ant.design/components/rate/).
+
+### `Cascader`
+
+Hierarchical leaf selection with `options: { value, label, disabled?, children? }[]`,
+string-array `value` / `defaultValue`, `onChange`, `searchable`, `allowClear`,
+`disabled`, `invalid`, and required `aria-label`. Values are the complete path.
+Reuses `Popover` and `Menu`: Up/Down, Home/End and typeahead walk each level; Right
+opens a child menu, Left returns, Enter chooses and Escape closes. Search matches
+full leaf paths; disabled ancestors also disable descendants. Closing returns focus
+to the trigger. Rich labels use their text for full-path search.
+
+`multiple` changes value/defaultValue/onChange to arrays of complete string paths.
+Parent/child checks share Tree's conduction engine; `showCheckedStrategy` is
+`'SHOW_PARENT'` by default or `'SHOW_CHILD'` for leaf paths. Disabled ancestors
+block descendants; `disableCheckbox` blocks that node's check conduction while
+children remain independently checkable. Search toggles retain checks outside
+results. Unknown selected paths survive changes; selected labels survive remote
+options replacement, including leaf values displayed through parent compaction.
+Multi clear preserves disabled/checkbox-disabled paths.
+
+`changeOnSelect` allows intermediate single paths: pointer selection keeps the
+hierarchy open, while keyboard selection or a leaf requests closing.
+`loadData(selectedOptions)` resolves child options or lets the host update options
+and resolve void. Set `isLeaf={false}` on unloaded branches. Loads deduplicate,
+show loading, offer Retry on failure, and reject stale source/loader replacements
+or late unmounted results. Returned children are validated against the full
+hierarchy before display. Keep source objects immutable and loader callbacks stable;
+changing their identity invalidates pending requests and loaded metadata.
+
+`fieldNames` maps value/label/children; string values are required and unique per
+complete path. Cyclic input, malformed children and duplicate paths are rejected.
+`displayRender(labels, selectedOptions)` and `optionRender(option)` customize
+presentation. `filterOption(query, selectedOptions)`, searchValue/onSearch and
+notFoundContent support host search. `open`/`defaultOpen`/`onOpenChange` keep popup
+ownership explicit; a refused close does not erase its query. loading presents
+host-owned async state; requests remain the host's responsibility. Native button
+attributes and ref support Form and focus.
+
+Klun keeps the original single Menu/submenu UI and string paths. Multiple,
+intermediate and lazy hierarchy use existing Tree semantics rather than copying
+AntD's column UI or private combobox handle. It does not alias numeric/null values,
+hover expansion, Panel, semantic styles or every AntD prop. Menu closeOnSelect can
+be disabled when a composite control owns closing, keeping single radio semantics.
+
+### `Transfer`
+
+`items: { key, label, disabled? }[]`, `targetKeys` / `defaultTargetKeys`, `onChange`,
+`titles`, `searchable`, `disabled`, `status`, `emptyState` / `errorState`, and required
+`aria-label`. Two checkbox lists support Tab/Space and labelled move buttons. Search
+and select-all affect visible enabled rows; moves preserve unknown and disabled
+target keys. A live region reports selected counts. Compact viewports stack the lists.
+
+`selectedKeys` / `defaultSelectedKeys` control the checked rows independently of
+`targetKeys`; `onSelectChange(leftKeys, rightKeys)` reports both partitions.
+`onChange(targetKeys, direction, moveKeys)` reports only known enabled rows that
+actually move, with `right` meaning add to targets and `left` meaning remove.
+Existing single-argument callbacks remain assignable. A controlled host can refuse
+both target and check changes; each displayed state stays supplied by the host.
+
+`pagination` enables independent pages per side, default size 10;
+`pagination={{ pageSize, showSizeChanger?, pageSizeOptions? }}` sets a controlled
+size when supplied. Search resets that side to page 1 and reduced totals clamp the
+visible page. Checks survive page/search changes; select-all touches only enabled
+rows on the displayed page. `filterOption(query, item, direction)` and
+`onSearch(direction, query)` support host filtering. Rich labels use their text by
+default, or `searchText` for opaque content; `render(item)` changes row presentation.
+
+A render-function child receives `direction`, `disabled`, `dataSource`,
+`filteredItems`, `selectedKeys`, `onItemSelect` and `onItemSelectAll`; custom lists
+own paging, as in AntD. Selection callbacks reject disabled, unknown and wrong-side
+keys, including saved callbacks after the component becomes disabled/loading.
+Bulk selection accepts true/false or `'replace'`; replace preserves disabled checks
+and checks on the opposite side. `showSelectAll={false}` hides the checkbox header;
+`footer(listProps)` adds per-side content. Native div attributes and refs are forwarded.
+
+Klun keeps `items`, string keys, textual titles and ready/loading/error status;
+it does not alias AntD's `dataSource`, numeric keys, oneWay or semantic style APIs.
+
+### `DatePicker` / `DateRangePicker`
+
+ISO calendar dates (`YYYY-MM-DD`) avoid implicit time-zone conversions. `DatePicker`
+forwards an input ref, `name`, `id`, and `required`; accepts `value` / `defaultValue`,
+`onChange(string)`, `min`, `max`, `disabledDate`, `locale`, `disabled`, `invalid`, and
+required `aria-label`. Native date entry and a themed calendar share the same bounds.
+Custom disabled dates also fail native form validity when provided by the host.
+
+The calendar offers month/year selection, previous/next month, Today and Clear.
+Left/Right move a day, Up/Down a week, Home/End within the week and PageUp/PageDown
+a month (clamping the day for shorter months). Enter/Space chooses; unavailable
+days can be inspected with keyboard focus but cannot be selected. Escape closes
+and restores trigger focus. Locale controls calendar names; the browser localizes
+native input display. Invalid host dates are marked invalid and never normalized
+into a different date. Calendar values use years 0001 through 9999.
+
+`DateRangePicker` accepts a `[start, end]` tuple, optional `names`, and shared date
+constraints. Each endpoint bounds the other; partial ranges are allowed, reversed
+ranges fail native validation. Time and multi-date selection are separate needs
+and are not included in this date-only contract.
+
+### MultiSelect corrections
+
+The trigger opens a labelled dialog containing a checkbox group. Choices expose
+actual checkbox semantics; disabled items cannot be toggled or cleared. Clear
+removes enabled selections present in this options page and preserves locked or
+unknown keys. The panel closes when the whole control becomes disabled.
+
+References: [Cascader](https://ant.design/components/cascader/),
+[Transfer](https://ant.design/components/transfer/),
+[DatePicker](https://ant.design/components/date-picker/).
+
+### DataTable: paging, filtering and row details
+
+`pagination` reuses `Pagination` and stays controlled. By default the table derives
+`total` from supplied rows and slices locally. Set `mode: 'remote'` for server-paged
+rows; the host then supplies the total and fetches on `onPageChange`. Invalid or
+out-of-range page values are clamped for display. Row numbers and render indexes
+are relative to the current page.
+
+A column `sorter(a, b)` enables local sorting without mutating `rows`. Columns with
+only `sortable` retain the existing host-managed sorting contract. `defaultSort`
+and `defaultFilters` initialize uncontrolled state; `sort` and `filters` make it
+controlled. A column's `filters` supplies named choices, and `onFilter(values, row)`
+implements its local predicate. Without a predicate the host handles the filter
+callback. The pipeline is filter → sort → page, and filter changes request page 1.
+For remote data omit local predicates/comparators and perform them on the server.
+
+`isRowSelectable` disables selection per row. Select-all touches only eligible
+rows on the current page, preserving locked and off-page keys. Selection remains
+host-managed through `selectedKeys`/`onSelectedKeysChange`.
+
+`expandedRowRender` supplies detail content, including a nested table when needed.
+`rowExpandable` excludes individual rows. Expansion is uncontrolled by default;
+use `defaultExpandedRowKeys`, or control it with `expandedRowKeys` and
+`onExpandedRowKeysChange`.
+
+Columns support `hidden`, `ellipsis: false` for wrapping (disables fixed-height virtual scrolling), and `onCell` for native
+cell attributes. Use `rowSpan`/`colSpan` and a zero span on covered cells. Keep
+`onCell` pure: layout and cursor navigation both read it. Cursor navigation skips
+omitted cells and follows visible grouped rows in their rendered order.
+
+`title`, `footer`, `rowClassName`, `summary` (native rows inside `tfoot`),
+`showHeader`, `stickyHeader` and `scroll: { x, y }` cover layout customization.
+The default empty and error states provide feedback even without custom content.
+Interactive controls within cells keep their own click and keyboard behavior.
+
+### Tree and DirectoryTree — full hierarchy interactions
+
+Both accept existing `nodes: { id, label, children }[]` or `treeData:
+{ key, title, children }[]`. `fieldNames` maps custom data fields. Keys must be
+unique across the entire tree; duplicate keys and cycles are rejected. Numeric
+treeData keys normalize to strings, including keys used by state and `scrollTo`.
+
+| Capability         | Props and behavior                                                                                                                                                                                                                                          |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Expansion          | `expandedKeys` / `defaultExpandedKeys` (`defaultExpanded` remains compatible), `defaultExpandAll`, `defaultExpandParent`, `autoExpandParent`, `onExpand`                                                                                                    |
+| Selection          | `selectedKeys` / `defaultSelectedKeys`, `multiple`, `selectable`, `onSelectionChange(keys, info)`; legacy `value` / `onSelect(node)` remain unchanged                                                                                                       |
+| Checks             | `checkable`, `checkedKeys` / `defaultCheckedKeys`, `onCheck`; hierarchical checks report full checked keys plus half-checked keys in info                                                                                                                   |
+| Strict checks      | `checkStrictly` disables parent/child conduction and accepts/reports `{ checked, halfChecked }`                                                                                                                                                             |
+| Node boundaries    | `disabled`, `disableCheckbox`, `checkable: false`, `selectable: false`; disabled check nodes stop conduction without disabling descendants independently                                                                                                    |
+| Async branches     | `loadData(node)` resolves children or updates host data and resolves void; `isLeaf`, `loadedKeys`, `defaultLoadedKeys`, `onLoad`, `onLoadError`; requests deduplicate, retry after failure and reject stale replacements                                    |
+| Search             | `searchValue` highlights labels and reveals ancestors; `filterTreeNode` highlights predicate matches without removing nodes; `titleRender` owns custom content                                                                                              |
+| Appearance         | `showLine` (including custom leaf icons), `showIcon`, `icon`, `switcherIcon`, `switcherLoadingIcon`, `blockNode`, `indent`, CSS `motion`, semantic `classNames` / `styles`, node `className` / `style`                                                      |
+| Dragging           | `draggable` boolean, predicate or icon/config object; `movable`, `allowDrop`, `onMove`, all drag lifecycle callbacks and `onDrop`; cycles and disabled targets are refused; hovering a closed branch opens it                                               |
+| Virtual rows       | `height`, `itemHeight`, `virtual`; fixed-height windowing retains an active descendant for accessibility; set `virtual={false}` for the complete DOM                                                                                                        |
+| Imperative control | `ref: TreeRef` exposes `nativeElement`, `focus()` and `scrollTo({ key, align, offset })`; nested keys reveal their ancestors, controlled expansion must be accepted by the host                                                                             |
+| Directory behavior | `DirectoryTree` defaults to click expansion and folder/file icons; `expandAction` also supports `doubleClick` and `false`; Ctrl/Meta toggles and Shift ranges merge the last ordinary/Ctrl selection; directory selection stays independent of expandAction |
+| Commands           | `nodeActions`, `nodeContextMenu`, `onRightClick`, `onDoubleClick`; visible command equivalents must accompany right-click menus                                                                                                                             |
+
+Keyboard: Up/Down walk visible nodes; Right opens or enters a branch; Left closes
+or goes to its parent; Home/End jump; typing searches visible labels; `*` opens
+sibling branches; Enter selects; Space checks (or selects without checks).
+RTL mirrors Left/Right navigation and Alt nesting/lifting. IME keys do not
+change tree state. Ctrl/Meta+Space supports additive directory selection, Shift+navigation extends
+ranges, and Alt+arrows reorder/nest/lift through the same move validation used
+by pointer dragging. Embedded controls retain their own keys. Disabled nodes
+remain discoverable by navigation while refusing changes.
+
+Keep host data immutable and retain node identities while an async request is
+in flight. A newly replaced node invalidates the old request/cache. When using
+controlled `loadedKeys`, update them from `onLoad` and clear replaced nodes yourself.
+Use a node’s `ariaLabel` when its rich title needs an explicit accessible name. Newly loaded children inherit
+checked ancestor state in hierarchical mode. Default values are initialization
+values; changing them later does not overwrite user state.
+
+Virtualization uses a fixed `itemHeight` and truncates labels to one line, as
+Ant Design's virtual Tree does. CSS transitions respect reduced motion; `motion`
+is a boolean here, not Ant Design's private rc-motion configuration. This is
+capability alignment with existing Klun APIs, not a drop-in `antd` import.
+
+DirectoryTree caches the selection from the last plain/Ctrl/Meta pick, merging
+Shift ranges with that base; a later Shift pick shrinks only its previous range.
+Ctrl/Meta wins when held together with Shift. A plain directory pick replaces the
+selection even with `expandAction={false}`, and Directory selection info reports
+`selected: true`, including Ctrl deselection, matching AntD DirectoryTree.
+Regular Tree keeps its existing additive multiple selection independently of
+click expansion. Boolean `showLine={{ showLeafIcon: true }}` renders the default
+file icon; false keeps only the connector, and functions receive node state.
+
+Native dragging resolves upper-half gaps through the previous visible node,
+inside expanded branches and horizontal nesting/lifting of last descendants,
+mirrored in RTL. `allowDrop.dropPosition` remains relative (-1/0/1).
+**Migration:** `onDrop.dropPosition` now matches AntD's target sibling index plus
+relative direction; use `onDrop.relativeDropPosition` for the previous relative
+meaning. `onMove` keeps before/after/inside. Unknown targets, cycles, disabled
+boundaries, no-op moves and explicit leaves reject invalid drops. The host owns
+reordering. Numeric treeData keys (including 0) intentionally normalize to string
+state/callback/ref keys; 1 and '1' collide and are rejected. Nonfinite numeric
+keys are invalid. This avoids changing existing TreeSelect/route string APIs.
+
+## Global configuration and Form foundation
+
+`ConfigProvider` inherits `locale`, `direction` and `disabled` from its parent.
+Omitted options inherit; explicit `disabled={false}` overrides the provider.
+`useProConfig()` reads configuration and `useComponentDisabled(disabled)` resolves
+the disabled fallback for custom controls. Core input controls, Button,
+ActionButton, Select/MultiSelect, radio/checkbox groups, DatePicker, Cascader,
+Transfer, Rate and Tree consume it. Portalled Dialog, Popover, Tooltip and Toast
+retain provider language and direction. This provides native text direction;
+full mirroring of every physical CSS offset and Ship business control is not
+implemented. Locale currently supplies Form messages and DatePicker date labels;
+other existing English copy is unchanged.
+
+`Form` / `FormItem` use `NamePath`: a string or number is a literal key; an array
+of string/number segments describes a nested object/array path. `user.name`
+remains a literal key; `['user', 'name']` accesses the nested value. Numeric array
+indexes are nonnegative integers below 100,000; string numeric keys remain object
+keys. Records/arrays are copied at store boundaries; reserved prototype keys,
+cycles and structures deeper than 100 levels are rejected before writing.
+Other object types must remain immutable.
+
+`initialValues` initializes the instance and is the reset baseline; changing
+that prop does not overwrite edits. Unmounted fields preserve values but clear
+errors and pending validation. `setFieldsValue` merges records recursively and
+replaces arrays; `setFieldValue` changes one exact path. Partial updates retain
+unmodified sibling metadata. Reset can target a subtree and remounts affected
+controls/lists, including multiple resets in one React batch. Dependencies and
+externally controlled field metadata are not implemented yet.
+
+```tsx
+const [form] = useForm();
+
+<Form form={form} initialValues={{ name: '', subscribed: true }} onFinish={save}>
+  <FormItem name="name" label="Name" required rules={[{ min: 2, message: 'Too short' }]}>
+    <Input />
+  </FormItem>
+  <FormItem name="subscribed" valuePropName="checked">
+    <Checkbox label="Receive updates" />
+  </FormItem>
+  <Button type="submit">Save</Button>
+</Form>;
+```
+
+Rules support required, whitespace, min/max (numeric value or string/array
+length), regular expressions and synchronous/asynchronous `validator(value,
+values)`. Validators return a message or throw/reject an Error to fail. Omitted
+messages use provider locale. `validateTrigger` defaults to `onBlur`; use
+`onChange` when desired. `onFinish` runs only for valid, current values; repeated
+submissions are suppressed while pending. `onFinishFailed` receives validation
+failures; `onSubmitError` receives rejected submissions, which also show a retry
+message without clearing values. Stale edits, reset, superseded validation and
+unmount prevent old results from becoming current errors.
+
+`useForm()` returns `[form]`. The instance exposes `getFieldValue`,
+`getFieldsValue`, `setFieldValue`, `setFieldsValue`, `getFieldError`,
+`isFieldTouched`, `isFieldValidating`, `resetFields`, `validateFields`,
+`scrollToField` and `submit`. Programmatic setters do not emit `onValuesChange`.
+`useFormInstance()` reads the enclosing instance; `useWatch(name, form?)`
+subscribes to one field. Do not attach one instance to multiple Forms at once.
+
+FormItem binds one child control and preserves its change/blur handlers. Native
+inputs use `value`; Checkbox/Switch use `valuePropName="checked"`. For array
+controls provide `emptyValue={[]}`; MultiSelect additionally needs
+`valuePropName="values"`, while DateRangePicker needs `emptyValue={['', '']}`.
+`getValueFromEvent` adapts custom callback arguments. Custom controls must forward
+the supplied id, aria attributes and blur callback to their actual control;
+groups should supply their own `aria-label`. Errors use a live alert and are
+linked to supporting controls with `aria-describedby`.
+
+### Dynamic Form lists
+
+`FormList` and `Form.List` are the same component; `Form.Item` aliases `FormItem`,
+and `Form.useForm`, `Form.useFormInstance`, `Form.useWatch` alias the named hooks.
+List callbacks receive `{ name: index, key: stableIdentity }[]`, operations
+`add(value?, index?)`, `remove(index | indexes)` and `move(from, to)`, plus
+`{ errors }`. Child field/list names are relative to their enclosing list.
+Imperative instance methods and `useWatch` always use absolute paths.
+
+```tsx
+<Form initialValues={{ people: [{ name: 'Ada' }] }} onFinish={save}>
+  <Form.List name="people" rules={[{ required: true, message: 'Add a person' }]}>
+    {(fields, operations, meta) => (
+      <>
+        {fields.map((field) => (
+          <div key={field.key}>
+            <Form.Item name={[field.name, 'name']} label="Name" required>
+              <Input />
+            </Form.Item>
+            <Button onClick={() => operations.remove(field.name)}>Remove</Button>
+          </div>
+        ))}
+        <Button onClick={() => operations.add({ name: '' })}>Add person</Button>
+        {meta.errors.map((error) => (
+          <p key={error} role="alert">
+            {error}
+          </p>
+        ))}
+      </>
+    )}
+  </Form.List>
+  <Button type="submit">Save</Button>
+</Form>
+```
+
+Always use `field.key` as React key and `field.name` in field paths. Moves and
+insertions preserve the existing rows' identities. Structural list changes
+clear descendant validation/touched metadata and invalidate pending validators
+so errors cannot attach to the wrong row. List rules validate after operations;
+child rules validate through blur/change/submit. `meta.errors` is rendered by the
+host. Provider/Form disabled state prevents list operations. Arrays initialize
+from Form `initialValues`; list-level `initialValue` is not supported.
+
+`validateFields(names?)` validates each selected path and its registered
+descendants; pass `{ recursive: false }` as its second argument for exact fields.
+Validation errors preserve string names for legacy fields and array paths for
+nested/list fields. Programmatic array replacements preserve keys by index;
+reset remounts rows. Dynamic lists support nesting and multiple operations in
+one event. There is no automatic dependency-validation engine in this batch.
+
+### Form dependencies
+
+`FormItem.dependencies` takes absolute form `NamePath[]`, including the complete
+list prefix and index (e.g. `dependencies={[["users", 0, "password"]]}`). A user
+change revalidates dependent fields that have been touched or previously
+validated; pristine fields do not immediately display errors. Transitive
+relationships are traversed once per field, including cyclic dependencies.
+Validators receive a snapshot of all current values, and superseded async
+results cannot overwrite newer validation results.
+
+As in the reference AntD contract, programmatic `setFieldValue`/`setFieldsValue`
+writes do not trigger dependency validation. Use `validateFields` explicitly
+when required, and `useWatch` for conditional content. `shouldUpdate` and
+render-function FormItem children remain unsupported.
+
+### P1 pagination and display contracts
+
+Pagination accepts controlled `page`/`pageSize` or `defaultPage` (1) /
+`defaultPageSize` (20). Existing `onPageChange`/`onPageSizeChange` callbacks remain;
+`onChange(page, pageSize)` combines them. Size changes reset to page 1.
+`showSizeChanger`, `showQuickJumper` (true), `hideOnSinglePage`, `showTotal(total,
+range)` and provider-aware `disabled` configure the footer. Displayed page/range
+are clamped to valid finite totals and sizes. DataTable pagination retains its
+required controlled page/pageSize/onPageChange contract.
+
+Segment adds defaultValue, per-option/provider disabled state and vertical
+orientation. Arrow/Home/End keys move focus and select enabled options; horizontal
+arrows follow the provider's direction. Existing group/pressed-button semantics
+are retained rather than exposing AntD radio-style markup.
+
+Avatar accepts native span attributes/ref, children/icon fallback, numeric size,
+circle/square shape and gap-based text scaling measured with ResizeObserver.
+Images support srcSet (including srcSet-only), crossOrigin and loading; failure
+falls back unless onError returns false, and changing src/srcSet retries.
+The wrapper owns the accessible name; its image is decorative. Unicode initials
+preserve graphemes with Intl.Segmenter (older engines use code points).
+AvatarStack applies size/shape to every member and +N, and exposes hidden names
+in the overflow label/title. IconAvatar supports numeric size/native span ref;
+AvatarPlaceholder forwards native button attributes/ref and provider disabled.
+Klun retains deterministic name colors, xs/sm/md/lg dimensions and people/max
+stack data. AntD responsive breakpoint sizes, ReactNode src, Group children
+context/popover and semantic style maps are not part of this contract.
+
+Tag supports closable/onClose (preventDefault cancels removal), closeLabel,
+checkable/checked/defaultChecked/onChange and disabled. Check and close use
+separate native buttons so both interactions remain reachable by keyboard.
+Color remains a CSS color; existing Klun variants and icons are preserved.
+
+Card adds loading, cover, actions, bordered and hoverable; extra renders even
+without a title. Loading hides pending children and announces status. Progress
+maps nonfinite values to zero. Divider adds children/titlePlacement and dashed
+rails with logical start/end alignment. These APIs preserve Klun's existing
+geometry. Card now exposes Grid/Meta composition; semantic-style APIs remain outside the contract.
+
+### P1 menu and navigation contracts
+
+Menu retains action-menu defaults. Set `selectable` for selectedKeys /
+defaultSelectedKeys / onSelectedKeysChange; `multiple` uses checkbox semantics
+and keeps the menu open while toggling. Existing item.checked and onSelect(id)
+remain available. openKeys / defaultOpenKeys / onOpenChange control expansion;
+vertical/horizontal modes use popup submenus, inline mode displays nested rows.
+Single leaf selection closes standalone popup submenus and the surrounding
+Popover. Controlled state changes are requested through callbacks. Item IDs
+must be unique throughout a hierarchy. Rich label children are searchable;
+opaque labels can provide searchText. Arrow keys, Home/End, typeahead and disabled
+choices work across supported modes; directions follow ConfigProvider.
+
+Independent Menu/Select instances do not inherit the selection or expansion of
+a containing menu. Only internal recursive submenus share that state. Klun's
+item.id and onSelect(id) contracts remain distinct from AntD key/event objects;
+AntD hover delays, horizontal overflow and inlineCollapsed are not supplied.
+
+Nav stays route-controlled and adds provider-aware disabled, RTL arrows and
+Home/End. Arbitrary IDs are matched as data, without CSS selector interpolation.
+Sidebar adds controlled width/onWidthChange; finite min/max bounds apply to both
+rendered dimensions and resizing, with RTL pointer/keyboard arithmetic and a
+logical content-edge gutter. Collapsed sidebars are inert and hidden from the
+accessibility tree. Existing mobile hiding and shell collapse provider remain.
+
+ContextMenu and ContextMenuList consume disabled defaults (explicit false wins).
+Disabled requests cannot open or persist an imperative menu; disabled parents
+hide and lock submenus. Context menu portals retain dir/lang, and submenu
+placement/navigation respects RTL. Pointer-bound menus remain separate from
+AntD Dropdown, keeping the existing openAt/row context and icon-strip contracts.
+
+### P1 general feedback
+
+`Empty` adds the general Empty entry alongside `EmptyState`: custom image nodes
+or image URLs, description (null/false hides it), children as actions and localized
+English/Chinese defaults. `Spin` supports controlled spinning, cancellable delay,
+custom indicator, description, three sizes and fullscreen; busy child content is
+inert until loading finishes. `Skeleton` preserves the original single block API
+and adds title/avatar/paragraph placeholders, static animation and loading=false
+content. `Result` supports success/error/info/warning and 403/404/500, custom icon,
+title, subtitle, actions and detail content; static results are not live alerts.
+
+These entries reuse Klun tokens and existing feedback primitives. AntD's semantic
+classNames/styles API, global indicator setter and Spin auto-percent animation
+are not exposed. Existing Progress retains the 0–1 value contract in Card.
+
+### P1 Slider and Rate
+
+`Slider` preserves native single-value `onChange(event)` and adds a discriminated
+`range` mode with `[start,end]` value/defaultValue/onChange, distinct form names,
+non-crossing handles, dynamic accessible bounds, step normalization, marks,
+vertical layout, native title tooltips and onChangeComplete. The forwarded ref
+points to the first native input. Tooltips use the browser title UI, not a popup;
+AntD's editable multi-handle range, draggable whole track and null-step marks-only
+selection are not exposed.
+
+`Rate` adds count, allowHalf, hover preview/onHoverChange, per-star tooltips and
+custom characters. Native same-name radios keep form submission and arrow keys;
+readonly values expose one accessible rating name. Clear remains an explicit
+button. Half-star labels expose each 0.5 choice so keyboard and pointer interaction
+share the same discrete values.
+
+### P1 general Progress
+
+`Progress` keeps value in 0–1 and adds percent in 0–100 (value takes precedence),
+line/circle/dashboard, active/success/exception styling, segmented steps, bounded
+success overlays, custom colors/format/ARIA naming, size/stroke controls and
+logical dashboard gap placement in RTL. showInfo controls formatted percentages;
+showValue remains the existing line label option. SVG rings use local paths;
+AntD gradient objects, arbitrary semantic styles and percentage-position variants
+are not part of this API.
+
+### P1 Tabs, Collapse and Steps
+
+`Tabs` adds top/bottom/start/end placement, RTL and vertical keyboard navigation,
+provider disabled, card/editable-card, add/remove requests and focus recovery after
+closing either active or inactive tabs. Hosts own edited items via onEdit(action,
+key). Dynamic removal repairs uncontrolled selection without resurrecting stale
+keys. keepMounted preserves the previous API; item forceRender and destroyOnHidden
+control content lifecycle. forceRender takes precedence over destroyOnHidden,
+as in the underlying rc-motion stable hidden branch. Overflow uses native scrolling.
+
+`Collapse` adds provider disabled, Up/Down/Home/End header focus, independent extra
+actions, borderless/ghost and keepMounted=false teardown; accordion ignores keys
+for removed items. Extra actions are separate controls outside the toggle button.
+`Steps` adds item status/icon/subTitle, initial numbering and current/onChange
+absolute step offsets, localized status, provider disabled and direction keys that
+move focus without changing the step until activation. Horizontal responsive
+stacking remains the existing CSS behavior.
+
+AntD animated panel motion, tabs automatic overflow menu/custom tab-bar rendering,
+Steps panel/dot types and semantic styling are separate remaining differences.
+
+### P1 input and action enhancements
+
+Input preserves the native input ref and event contract. It adds `sm`, prefix/suffix,
+`allowClear`, `showCount` (UTF-16 length, optional formatter), warning/error status and
+outlined/filled/borderless/underlined variants. Clearing emits the native input event
+and restores focus; read-only/disabled fields hide the clear button. Runtime feature
+changes preserve the input node and uncontrolled value. Native form reset updates counts.
+PasswordInput inherits these props. Textarea retains its existing native API.
+
+Button adds dashed/link variants, round/circle shape, ghost and danger combinations.
+ActionButton and Switch support loading (busy and disabled). Switch supports checked /
+unchecked text and Left=off / Right=on keyboard operation; its native checkbox events,
+form value and ref remain intact. RadioGroup and CheckboxGroup options accept native
+id/title/required/style/change handlers; checkbox changes report registered values in
+option order. Group values remain strings to preserve the existing typed API. AntD
+semantic styles, delayed loading, numeric group values and boolean Switch value aliases
+are not provided by these native-control APIs.
+
+### P1 inline feedback enhancements
+
+Badge adds rich counts, status/text, custom color, small size, logical attached offsets,
+null/false title suppression and native span attributes/ref. Numeric overflow keeps the
+full accessible description; invalid numeric counts are hidden. The original explicit
+`dot` remains visible at zero. Processing uses a reduced-motion-aware pulse. AntD Ribbon
+and animated rolling digits remain compatibility gaps.
+
+Alert adds a `title` alias (preferred over message), warning banner, filled variant,
+custom decorative icon, native div attributes/ref and configurable close button. Close
+handlers may preventDefault; inherited disabled can be explicitly overridden. Controlled
+hosts retain ownership of visibility. afterClose runs after actual removal, once, with no
+exit animation. Existing showIcon=true and open/defaultOpen contracts remain unchanged.
+AntD semantic style callbacks and animated exit are not implemented.
+
+### `InputNumber`
+
+Numeric `value/defaultValue` and `onChange(number | null)` integrate with Form; native
+input ref/attributes, affixes, status and variants come from Input. Invalid/incomplete
+editing drafts stay visible while focused, and valid in-range edits update the value.
+Blur aligns range/precision and restores the host's controlled value. External values
+update focused drafts. Step controls and Up/Down support Shift×10, disabled/read-only,
+precision, formatter/parser and onStep. Uses JavaScript numbers (small IEEE-754 artifacts
+are rounded without truncating large precise values); AntD stringMode/high-precision arithmetic and press-and-hold are gaps.
+`formatter` receives userTyping/input to preserve caret-friendly drafts. Composition
+commits once at its end, with modified/IME navigation protected; finite stepping rejects
+unrepresentable results and bound no-ops without calling onStep. Step controls use locale.
+Host formatter/parser exceptions remain host-owned; no stringMode or arbitrary precision.
+
+### `AutoComplete`
+
+Editable string value, options `{value,label?,disabled?,searchText?}`, filtering/custom
+filter, onSearch/onSelect, controlled open, clear and native ref. Combobox focus stays
+in the input; Up/Down skip disabled options, active choices scroll into view, Enter
+selects, Escape closes. IME composition avoids premature search/selection. Empty options
+never render a popup. Uses the existing Popover with autofocus disabled; grouped options,
+virtual suggestions and arbitrary custom input children remain compatibility gaps.
+Selecting the existing value still calls onSelect but not onChange/onSearch. Disabled or
+read-only drops uncontrolled popup state; explicit controlled open remains host-owned.
+Modified and key229 navigation is ignored. Native input form/reset semantics are retained.
+
+### `TreeSelect`
+
+Tree data uses `{value: string,title,children?,disabled?,disableCheckbox?,selectable?,isLeaf?}`.
+Single values are string/null; multiple or treeCheckable values are string arrays. Change
+receives values and labels. Reuses Tree expansion, lazy loading, checks, search and virtual
+scrolling via treeProps; lazy node identities and selected labels survive parent renders.
+Checkbox mode selects via checkboxes and returns Tree's full checked keys; AntD strategy
+constants / labelInValue / numeric values are compatibility gaps. Native trigger ref,
+ARIA, hidden named form values, clear, controlled open and Form blur validation are supported.
+Node identities remain nonempty strings as required by Tree (null clears). Repeated identical selection does not
+notify onChange. Locale covers placeholder/search/clear; explicit disabled=false reaches
+both search and Tree under a disabled provider. Disabling drops uncontrolled popup state.
+Search clears on actual close; rejected controlled close requests retain the search.
+
+### `TimePicker`
+
+Native local-clock input: string HH:mm / HH:mm:ss (empty clears), min/max, second-based
+step, native ref/attributes, Input affixes/variants/clear, Form and ConfigProvider. DisabledTime
+marks unavailable values invalid without discarding drafts, with a localized validity
+message. Native min/max supports overnight ranges; repeated same-value changes do not
+notify. Values remain local clock strings and explicit disabled=false is supported. No Date or timezone conversion.
+The native picker provides localized interaction; AntD Dayjs, custom time columns, range
+picker, 12-hour formatting and disabled unit callbacks are not provided by this entry.
+
+### General information display
+
+`Breadcrumb` complements Crumbs with native links, configurable separators, disabled
+items, custom rendering and current-page semantics. `Descriptions` complements KeyValue
+with responsive columns (xs→xxxl), horizontal/vertical layout, borders, header/extra and
+bounded spans; overflow spans truncate to the current row, and the final cell fills it.
+Breadcrumb labels follow locale, a null per-item separator hides it; host itemRender owns
+its own interaction/disabled behavior. Descriptions preserves zero labels and values.
+Both forward native attributes/ref. Legacy Crumbs and KeyValue APIs remain intact.
+
+`Statistic` complements Metric with string-preserving digit grouping, configurable
+separators/precision, prefix/suffix, formatter, loading and value style. Precision truncates
+and pads decimals as in AntD's Number.tsx; fractional-only strings gain a leading zero,
+empty string displays zero, punctuation-only strings remain raw; it does not round or convert big integer strings.
+Timer/countdown and semantic style callbacks remain compatibility gaps.
+
+`Typography.Text/Title/Paragraph/Link` provide native text/heading/link semantics, emphasis,
+code/keyboard/mark/delete, CSS multi-line ellipsis with controlled expansion, copying and
+editing. Clipboard errors expose retry and invoke onError; async copy stays busy. Editing
+accepts empty strings, supports Enter-save/Escape-cancel and restores focus; disabled
+configuration blocks actions. Copy/edit labels follow locale, and copy requires
+the native Clipboard API. Measurement-based suffix ellipsis, autosizing editor, semantic
+styling and HTML clipboard formats remain gaps. Link uses safe defaults for target=_blank.
+
+### Layout / Grid / Flex / Space / Splitter
+
+Layout 提供 Header/Footer/Content/Sider；Sider 支持受控/默认折叠、零宽、响应式断点、触发器和折叠原因回调。Sider仅实际折叠状态变化通知onCollapse，onBreakpoint仍报告初始/变化断点；支持locale与显式disabled=false、有限非负数字width。Sider xxxl保持AntD1840阈值，Grid xxxl保留原库1920，不强改已有断点。Row/Col 使用 24 栅格、逻辑方向 gutter/offset/push/pull、响应式尺寸/排列；Grid.useBreakpoint 返回断点状态。Flex 使用原生 CSS flex，有限非负数字gap；Col数字flex/order防止NaN/Infinity；Space 支持间距、分隔及 Compact 输入/按钮连接。
+
+Splitter.Panel 提供数字像素或百分比 size/defaultSize/min/max，受控尺寸、指针/方向键/Home/End 调整、折叠恢复、保留或销毁隐藏内容。回调返回像素尺寸，宿主控制 size 时必须写回才能持久更新；尺寸计算扣除每个 8px 分隔条。整组受控尺寸按可用空间比例归一化，部分受控面板保持固定尺寸。未提供 size 的面板内部管理调整结果。拖动结束/取消/lost capture只提交当前pointer draft一次，非当前pointer不终止；axis/RTL/extent/disabled/panel身份变化使旧draft失效，修饰键/IME不resize；不可满足pair min/max时保留当前分配而不制造越界。复杂对象 collapsible、拖动预览延迟、多panel穿透resize、dragger doubleclick、AntD semantic 样式入口仍未提供。
+
+### Dropdown / Popconfirm
+
+Dropdown 使用原生 Button 触发器（children 是按钮内容，ref 指向按钮），menu 接收现有 MenuProps。支持 open/defaultOpen/onOpenChange、方向键打开、嵌套菜单、禁用、选择关闭及现有 Placement 定位。IME/key229/修饰键不打开；外部loading阻止内置交互，禁用/loading丢弃非受控开关但保留host受控open，重复相同开关不通知。多选菜单遵循 Menu 保留打开的规则。未复制 AntD 的任意子元素克隆、hover/contextMenu 触发、Dropdown.Button 或 popupRender 扩展。
+
+Popconfirm 同样使用原生 Button 触发器，title 是字符串可访问名称，description 支持 ReactNode。onConfirm 可以异步，false 保留打开，拒绝会显示重试提示并通知 onError；等待期间阻止重复、取消和外部关闭。onCancel 表示取消按钮操作。受控 open 必须由宿主写回，禁用/关闭/卸载使旧请求结果失效。使用现有 Popover 的焦点恢复和上下文；文本可通过 okText/cancelText 自定义，locale提供确认/取消/失败重试默认，0 description和button内容不丢失。外部loading隐藏内置操作；禁用丢弃非受控popup且使pending generation失效，受控open仍由host拥有。未实现参考的任意子元素触发、函数 title/description、箭头和完整 semantic 样式。
+
+### Drawer
+
+Drawer 复用 Dialog 的模态栈、焦点循环/恢复、滚动锁及配置上下文。open 由宿主管理；placement 支持 top/right/bottom/left 物理边缘，RTL 不交换指定边缘。width/height 接收像素数字或 CSS 长度并限制到视口；默认 378px，非法非有限数字回退378，负数归0。title/tools/footer/bodyClassName/style 使用 Dialog 协议，keyboard/maskClosable/closable 独立控制关闭方式；dismissable 仍作为前两项默认值。关闭时销毁内容，原 DetailSheet 业务组件保持独立。参考的 push、resizable、destroyOnHidden=false、动画结束回调、非模态/自定义挂载与 semantic 样式尚未提供。
+
+### Image
+
+Image 使用真实原生 img，alt 必填，ref 指向图片；src/fallback/placeholder 处理加载及失败，原生 img 属性透传。preview=false 关闭预览，配置对象支持 open/defaultOpen/onOpenChange/src；预览使用 Dialog，提供缩放、旋转、重置和焦点恢复。disabled 消费配置，取消 onClick 默认行为可阻止打开。className/style 作用于包裹容器，width/height 作用于 img。
+
+预览/工具/关闭沿用locale；禁用丢弃非受控预览，受控open仍由host持有。旋转按360度归一化，0 placeholder可见。
+
+Image.PreviewGroup 使用显式 items（src/alt）列表，支持 current/defaultCurrent/onChange、受控开关和前后导航；重复打开当前图片不重复通知onChange；子 Image 的 src 匹配列表时打开分组，否则打开独立预览。未实现参考的自动子图片注册、拖动/滚轮/翻转、下载、自定义动作、进度/semantic 样式；业务 FilePreview 仍仅展示附件元数据，不代替此真实图片组件。
+
+### Upload
+
+Upload 的 originFileObj 是实际 File，ref 指向原生 file input，children 是按钮内容。默认无传输，只保留手动列表；指定 action 后发送 POST multipart（name/data/headers/withCredentials），或 customRequest 获得实际 file 和 progress/success/error 回调，可返回 abort。成功 response 是 XHR 原始文本，由宿主解析。
+
+beforeUpload 支持异步，false 保留手动项，Upload.LIST_IGNORE 忽略，File/Blob 转换实际字节；失败（包括falsy拒绝原因）保留 error 项。accept 在选择和拖放时都检查，multiple/maxCount 控制数量，maxCount=1 替换并取消旧请求。fileList/defaultFileList/onChange 提供受控/默认列表，onRemove false 或拒绝保留文件；删除/卸载后旧回调不再更新；异步移除结束检查最新列表，已移除项不重复通知。异步预处理完成后使用最新传输配置/maxCount/回调；禁用期间不开始新请求，已开始的请求仍由移除/卸载取消。中文locale覆盖列表与控件；显式disabled=false传给内置按钮。列表只展示文本/进度/错误和删除，不自动渲染不可信文件链接。beforeUpload 是客户端检查，服务端仍需验证文件。目录、粘贴、缩略图列表、自动重试、任意 trigger 克隆、动态 action/data、完整 semantic 样式仍为参考扩展差距；AttachmentUpload 业务元数据契约保持独立。
+
+### App / message / notification
+
+App 内包含独立 ToastProvider 栈，message 默认顶部居中，notification 默认右上，配置支持 placement/max，嵌套 App 按字段继承父配置但各自持有独立栈；max=0 抑制展示；默认右上通知在窄屏移至右下以避免与顶部 message 重叠。放在 ConfigProvider 内即可继承 direction/locale。App.useApp() 返回最近 App 的绑定 API；根导出的 message/notification 调用最后注册且仍挂载的 App，没有宿主时抛出明确错误，不创建丢失上下文的独立根。
+
+message.open({content,type,key,duration,onClose})、notification.open({message,description,type,key,duration,onClose}) notification 返回可用于 destroy 的字符串 key；message 返回可调用关闭且可 await 的句柄（key 属性可用于 destroy），提供 info/success/warning/error/loading，loading 默认持续至关闭。duration 继续使用 Klun 的毫秒契约，0 为持久；destroy() 删除本栈全部，destroy(key) 删除指定项。同 key 更新替换原内容并重置计时，注册的 onClose 在最终移除时各执行一次；封顶删除和卸载清理计时器。已关闭句柄再次调用不会删除后来复用相同 key 的消息；批量移除先清理旧项，再执行全部回调，回调抛错仍结清所有等待者并保留新消息计时，随后向宿主抛出首个错误。悬停或键盘焦点暂停正数计时，离开后沿用原有 1500ms 宽限；持久项不会因悬停而关闭。现有 useToast.push/dismiss 保持兼容，新增 key/onClose 和无参数 dismiss。
+
+参考的独立 useMessage/useNotification contextHolder、自定义静态根/config、可堆叠折叠/进度条、App DOM wrapper/modal API 和任意挂载点有意不提供；静态 API 推荐只在单根 App 中使用，多根/嵌套场景使用 App.useApp 绑定准确上下文。
+
+### Form 条件项与字段生命周期
+
+无 name 的 Form.Item 可接收 `(form) => ReactNode`，shouldUpdate=true 默认监听值变化，比较函数接收前后值快照；单独 dependencies 时只跟随指定路径变化。noStyle 支持无名输出或命名控件的 display:contents 包装。命名项仍要求单个可绑定控制元素。
+
+Form/Item preserve 默认 true，Item 可覆盖 Form。preserve=false 实际卸载后恢复 Form initialValues，无初始值则删除路径；列表子字段没有单字段初始值，且清理保护列表重排/移位、StrictMode 重注册、父列表整体卸载和宿主最新写值。卸载清理在微任务中发生，读取最终值时等待提交后的微任务。字段错误与请求元数据同时清理。scrollToField 支持 focus/block/behavior，保持原默认聚焦；focusField 只定位可见、可用控制，不聚焦隐藏输入或禁用字段集。
+
+validateTrigger 支持 onChange/onBlur、事件数组及 false；false 关闭自动校验，显式 validateFields/submit 仍校验。保持 Klun 默认 onBlur，已出现错误的字段在修改时自动复验（false 除外）。scrollToFirstError 支持 false 或 focus/block/behavior，保持 Klun 默认 true；AntD 默认不自动滚动，这一差异用于兼容既有调用。
+
+### Calendar / Timeline
+
+Calendar 是独立月/年日历，value/defaultValue 使用 YYYY-MM-DD ISO 字符串，与 DatePicker 共用校验与日期运算；mode/defaultMode 为 month/year，fullscreen=false 为紧凑单元格。onChange 只在日期变化时触发，onSelect 额外给出 date/month/year/customize 来源；onPanelChange 在面板年月或模式改变时通知。validRange 是含端点有效范围，disabledDate 与 ConfigProvider.disabled 组合限制选择。cellRender 追加内容，fullCellRender 替换内容；headerRender 接收 value/type/onChange/onTypeChange，自定义操作仍受范围/禁用限制。网格方向键/Home/End/PageUp/PageDown 支持跨月聚焦和 RTL。时间、周编号和 Dayjs 类型不属于这一入口，保留 Klun 日期字符串契约。
+
+Timeline 使用语义 ol/li，items 支持 key/title/content/icon/color/loading/placement，以及 AntD 的 label/children/dot 别名。pending 追加加载项，reverse 复制后反转，不改宿主数组；orientation 为 vertical/horizontal，mode 为 start/end/alternate（left/right 兼容逻辑别名）。空数据输出空列表，具体空状态由宿主组合 Empty；水平列表在窄屏内部滚动，颜色和布局随主题/方向变化。业务 TransitionsTimeline 仍负责活动含义与时间格式，不混入通用数据模型。
+
+### List / Listy / Masonry
+
+List 泛型 dataSource/renderItem/rowKey 配合现有 Pagination（Klun 的 page/pageSize 命名）、受控/非受控页码和容量；数据缩短会夹到有效页。header/footer/loadMore、bordered/split/size/itemLayout、grid 响应式列数与 gutter、loading 和 emptyText 可组合。List.Item 支持 actions/extra，List.Item.Meta（也导出 ListItem/ListItemMeta）支持 avatar/title/description；原生 li 保留，不产生嵌套列表项。children 分页忽略 null/false，与总数采用同一集合。
+
+Listy 为独立泛型长列表，items/rowKey/itemRender、group.key/title、sticky、height 和 virtual。无有效 height 时使用正常流；virtual=true 使用固定 itemHeight（默认44，分组标题也同高），只渲染可见区及3行缓冲，并保留完整滚动高度与 aria-posinset/setsize。变高内容请使用普通 Listy 或 Masonry，不承诺 rc-listy 动态测量行高。ref.nativeElement 和 scrollTo(number / {top,left} / {key,align,offset} / {groupKey,align,offset}) 支持定位；align 为 top/bottom/auto。分组保持首次出现的分组顺序，itemRender 的 index 保留原数据索引；可访问序号按最终分组顺序。
+
+Masonry items 的 key/data/children/height/column 与 itemRender 配合；columns 支持断点对象，gutter 支持数字或 [横向,纵向]。使用原生 ResizeObserver 测实际单元高度，依次放入最短列；column 可固定列且夹到有效范围，改变高度/列数/内容自动重算。DOM 顺序保持数据顺序，RTL 使用逻辑位置。onLayoutChange 通知 key/column 分配变化，不复制 AntD motion/fresh 动画或语义样式注入。旧浏览器无 ResizeObserver 时仅挂载/属性更新时测量；宿主需要动态媒体尺寸更新应提供原生 ResizeObserver 支持。
+
+### Affix / Anchor / FloatButton / BackTop
+
+Affix 在 window 或 target() 返回的滚动容器边缘固定同一个子 DOM，offsetTop 默认0、offsetBottom 可选；占位保留测量高度，滚动/resize/原生 ResizeObserver 重算位置，onChange 仅通知固定状态变化。ref.nativeElement/updatePosition 可主动更新；无目标解除固定，卸载移除监听和动画帧。使用 CSS fixed，宿主须避免会改变 fixed 包含块的 transformed 祖先；不引入复制节点或门户导致表单/焦点重新挂载。
+
+Anchor 是 nav/原生链接，items 支持 key/href/title/children/target/disabled，提供纵横方向、affix、offsetTop/targetOffset/bounds、getContainer、getCurrentAnchor、onChange/onClick 和 replace。字面 ID 使用 getElementById/decodeURIComponent；只拦截同页普通主键点击，Ctrl/Meta/外部 target 保持浏览器行为，preventDefault 可取消。href 只接受 HTTP/HTTPS/mailto/tel 或相对地址，不执行脚本协议。消费 ConfigProvider disabled/locale，滚动检测活动章节。更换容器时更新 getContainer 函数身份，以重新绑定监听；不复制弃用 Anchor.Link 或 semantic 样式。
+
+FloatButton 保留 Button 原生属性、ref、variant 和原生 type，扩展 icon/content（description 别名）/shape/tooltip/badge；icon-only 需 aria-label 或文字 tooltip。FloatButton.Group（也导出 FloatButtonGroup）支持常驻组与 click/hover、open/defaultOpen/onOpenChange，禁用原生字段集阻止所有按钮；Escape 关闭后恢复内部焦点，鼠标离开但键盘仍在组内时保留，随后失焦关闭。逻辑角落位置可通过 style 覆盖；不重复实现链接按钮协议或语义样式注入。
+
+AntD 6.6.5 独立 BackTop 已弃用并推荐 FloatButton.BackTop；Klun 同时提供这两个入口并复用同一实现。target 接受 Window/Document/HTMLElement，visibilityHeight 默认400、showProgress 显示0–100滚动进度；behavior 默认 smooth，系统减少动画时自动 auto。onClick.preventDefault 可取消滚动，target 不存在时隐藏，监听在卸载时移除。沿用浏览器平滑滚动，不提供毫秒 duration 动画引擎。
+
+## Mentions
+
+Native textarea ref; string value/defaultValue/onChange integrates with Form. options accepts value/label/disabled;
+prefix supports one or multiple nonempty tokens, split defaults to space. Searches the last prefix before the collapsed caret,
+filters case-insensitively by value (filterOption=false for remote search), invokes onSearch(query,prefix), and inserts onSelect.
+IME delays suggestions until composition ends. Up/Down skips disabled options and scrolls the active option into view;
+Enter inserts without submitting a form, Escape closes, and Tab retains normal navigation. onKeyDown may cancel default handling.
+Loading and notFoundContent represent pending/empty results. Mentions.getMentions parses completed prefix tokens.
+Controlled refusal leaves the original text and focus unchanged after the selection event. Disable/readOnly suppress editing suggestions.
+
+Compared with AntD 6.6.5 and @rc-component/mentions 1.12.0: textarea anchored Popover rather than mirrored caret geometry;
+no deprecated Option children, semantic styles, popup container or auto-size wrapper. The replacement reuses matching trailing text
+and adds split boundaries without deleting unrelated trailing characters. Multiple-character split is supported.
+
+## ColorPicker
+
+Native Button ref; string/null or gradient stop array controlled/default values, onChange(value), onChangeComplete(value), controlled open/defaultOpen/onOpenChange.
+Solid colors and each gradient stop accept #RGB/#RGBA/#RRGGBB/#RRGGBBAA, comma RGB/RGBA (including percentages), HSB/HSBA with percentage saturation/brightness,
+and transparent. Invalid/out-of-range input is rejected before callbacks or swatch CSS; unsupported external values display an empty swatch.
+HEX/RGB/HSB format switching changes presentation; native color input and keyboard-operable hue/saturation/brightness/opacity ranges edit values.
+HSB stays internal for grayscale/black so changing opacity or restoring saturation retains hue. disabledAlpha forces opacity on user edits.
+Completion fires on typed commit, presets, clear, range release/navigation or native picker blur. allowClear emits null and onClear.
+Presets label/colors/defaultOpen, showText, panelRender and resolved global disabled settings are supported.
+
+Compared with AntD 6.6.5 and @rc-component/color-picker 3.1.1: strings replace AggregationColor objects;
+uses native color selection and accessible channel ranges rather than a custom 2D drag plane. Gradient values use {color,percent}[]; native stop selection/add/remove/position editing supports at least two stops, validates CSS, sorts only the preview and preserves input order. mode selects available single/gradient modes; controlled values determine the current mode. No custom stop drag plane, hover trigger, semantic styles or popup mounting.
+
+## Carousel
+
+Single-visible-slide carousel; current/initialSlide/onChange, beforeChange/afterChange, ref nativeElement/goTo/next/prev.
+Finite/infinite bounds, arrow/dot navigation, horizontal/vertical/RTL keyboard, optional native pointer swipe,
+fade/scrollx entrance effects and logical dot placement. Inactive slides stay mounted but hidden and unfocusable.
+Autoplay pauses on pointer hover, focus, document hiding or reduced motion; a Play/Pause control is always available.
+Changing speed during navigation does not discard the completion event; unmount or later navigation cancels superseded timers.
+Compared with fixed AntD/react-slick: no clone track, multi-slide/slick settings, internal slider or legacy autoplay imperative API;
+CSS entry transitions replace outgoing track animation. initialSlide is the uncontrolled seed, current controls later changes.
+
+## Tour
+
+Target-aware modal tour reuses Dialog's stack, keyboard trapping, Escape, focus restoration and scroll lock;
+Dialog now accepts maskStyle/maskContent for custom visual masks. steps title/description/cover/target/placement/mask,
+current/defaultCurrent/onChange, open/defaultOpen/onOpenChange, onClose(current)/onFinish.
+Default open is true when steps exist (reference behavior). Target is scrolled into view, followed on scroll/resize,
+and highlighted through an SVG mask; missing targets center the panel. Gap, mask color, primary border,
+custom indicators/actions and cancellable next/previous button props are supported. Resolved disabled=false overrides provider disable.
+Compared with @rc-component/tour: target interactions remain blocked during this modal flow;
+no nonmodal focus behavior, animation placeholder, arbitrary popup mounting or semantic styles. Positions use viewport bounds.
+
+## QRCode
+
+Uses the exact reference @rc-component/qrcode 2.0.0 encoder, rather than decorative modules. SVG default/canvas,
+UTF-8 strings or segment arrays, errorLevel L/M/Q/H, boostLevel, four-module quiet margin,
+size/color/bgColor, embedded icon/imageSettings, bordered, active/loading/expired/scanned and refresh/custom status controls.
+Native wrapper ref. Empty values have a visible state; excessive payloads show an alert rather than crashing callers;
+valid value changes recover an encoding failure. Keep high contrast and quiet margins for scanning.
+The exact encoding package is a build-time dependency bundled into the artifact with its MIT notices; public types do not reference it. jsqr is a development-only independent decoder used by tests.
+SVG default intentionally differs from AntD canvas default, with no semantic style injection or QR internals exposed.
+
+## Watermark
+
+Native repeated DOM tiles support text/multiple styled lines, native image/failure fallback, font, rotation,
+width/height, gap/offset and zIndex; ResizeObserver follows content dimensions. Text and controls remain usable.
+Native root ref. MutationObserver reattaches the same removed overlay or tile and restores altered overlay styles,
+then invokes onRemove. Normal React dimension/content/style updates do not count as tampering.
+Compared with AntD: DOM marks replace raster canvas caching, image requests use native browser loading,
+no inherited watermark context; tamper repair is visual deterrence, never access control.
+Very dense surfaces are limited to 4096 tiles; use larger tile/gap values for large scroll documents.
+
+## BorderBeam
+
+A layout wrapper with native root ref adds pointer-transparent SVG perimeter segments, independent of child DOM refs.
+Responsive measurement, count (1..32), duration seconds, pixel size/lineWidth/outset and validated solid/gradient colors.
+Native SVG gradient stops use finite bounded percentages. Reduced motion keeps stationary segments.
+Compared with AntD: wrapper layout and top-left uniform corner radius replace child-host injection and nonuniform corner geometry;
+SVG dash motion replaces CSS offset-path and tail coloring. Numeric dimensions avoid CSS-unit measurement dependencies.
+
+### DataTable: hierarchy, header groups and virtual windows
+
+`columns` accepts `ColumnDefinition<T>`: either an existing `Column<T>` or a
+`ColumnGroup<T>` with `id`, `header`, `children`, `hidden` and `className`. Hidden
+branches disappear; native colSpan/rowSpan reflect the visible leaves. Numeric
+leaf widths also size grouped headers through colgroup. Group headers pin only
+when all their leaves share the same fixed edge. Duplicate column IDs are rejected.
+
+`getChildren(row)` opts into hierarchy; root records are filtered, sorted and
+paged before expanded descendants are flattened. Sorting and filters apply at
+all levels, with a failed parent filter excluding its branch. Original records
+remain unchanged. Use the existing expansion keys/callback, `rowExpandable` and
+`indentSize` (20px default). Duplicate or empty row keys, including cycles, are
+rejected. Row indexes refer to the visible flattened page. `groupBy` groups that
+visible page; `expandedRowRender` can coexist with tree expansion.
+
+`sortPriority` enables additive multi-sort (higher numbers first). `sorts`,
+`defaultSorts` and `onSortsChange` expose the array; each header cycles asc → desc →
+removed. Existing controlled `sort` stays single-sort unless the array API is
+explicitly used. `onSortChange` retains its nullable single-state payload.
+`onChange(change)` reports sort/filter/paginate once, including proposed filters,
+sorts, pagination and processed **root records before pagination** in
+`currentDataSource`. Controlled rejection does not suppress proposed events.
+`summary(rows)` now receives that pre-pagination root scope, matching AntD's
+summary scope; render native rows/cells inside the supplied tfoot.
+
+`selectionMode="single"` renders same-name native radios without select-all or a
+bulk selection bar; a pick replaces the selected keys and disabled rows cannot
+be picked. Multiple selection retains its existing page selection contract.
+
+`virtual` enables a fixed-height native table window, or use
+`{ rowHeight, overscan }` (45px/36px according to density, three overscan rows by
+default). `scroll.y` supplies viewport height, otherwise 300px. Rich cells are
+clipped to this pitch; choose a sufficient height. Tree expansion, grouped
+headers, fixed columns and cursor navigation work within the window. The active
+row stays mounted outside the window until focus leaves, preserving editors and
+keyboard navigation. Non-finite dimensions fall back to valid defaults. Grouped
+bodies, detail expansion and any `onCell` use full rendering, preserving merged
+cell geometry. This is an intentional difference from AntD's measured virtual
+rows and merged-span repair. Arbitrary variable-height virtual content and its
+internal rc-table ref are not exposed. Klun keeps string keys, rows/rowKey,
+getChildren and its existing native table semantics.
+
+### DatePicker / DateRangePicker: periods, local time and typed formats
+
+The existing ISO string/native input ref contract is retained. `picker` is date,
+week, month, quarter or year; emitted period values use the ISO Monday, first day
+of the month/quarter, or January 1. Native week input uses ISO week years (for
+example 2021-01-01 displays 2020-W53). Period bounds compare their period starts,
+so a mid-month min/max does not discard the entire boundary month. `disabledDate`
+receives the candidate ISO day/period and `{ type }`.
+
+`showTime` (date mode only) emits local `YYYY-MM-DDTHH:mm[:ss]` without timezone
+conversion. Use `{ defaultValue: '09:00', step: 1 }` to supply the initial clock
+and expose seconds. `min`/`max` accept local datetimes; a plain-date maximum ends
+at 23:59:59. `disabledTime(value)` rejects the complete local datetime. Date
+availability is independent of clock availability: select the day, then adjust
+its clock. `needConfirm` defaults to true with time, false otherwise. Calendar
+choices remain provisional until Apply when enabled; Escape/reopen cancels the
+proposal. Native entry and preset commits are immediate. `onOk` reports Apply.
+
+`multiple` changes value/defaultValue/onChange to `string[]`, toggles dates or
+periods, sorts and deduplicates the proposal, keeps the panel open, and renders
+controlled removable tags. Time is excluded from this mode. With needConfirm,
+panel selections are staged until Apply. The ref points to the entry input;
+`name` submits a hidden JSON array and required validation reads committed dates.
+An explicit disabled=false also enables nested month/time controls under a
+disabled ConfigProvider. readOnly blocks both entry and panel edits.
+
+`presets` contain a ReactNode label and ISO value or lazy function, evaluated on
+click and checked against constraints. `open/defaultOpen/onOpenChange` control
+the popup; rejected closing retains the panel. `format` accepts strict token
+strings YYYY/MM/DD/HH/mm/ss/Q with literal separators, or an explicit
+`{ format(value), parse(text) }` pair. Invalid typed drafts do not emit and fail
+native validity; blur restores the committed display. Display format changes do
+not change ISO values. Locale affects panel labels and native controls; token
+parsing is explicit and locale-independent.
+
+DateRangePicker keeps editable partial tuples and never silently swaps endpoints.
+Shared date/time bounds constrain both endpoints, including same-day clocks.
+Its disabledDate/disabledTime receive `{ from, range: 'start' | 'end' }`; preset
+pairs are strictly checked, normalized to the picker period, then atomically
+validated and committed. Range open is 'start', 'end' or null, with only one
+panel open at once. Range presets use tuple values/lazy functions.
+
+These are Klun ISO values and native refs, rather than AntD Dayjs objects and
+picker handles. Year/quarter panels and strict formats cover the documented
+contract; decade drilldown, masked editing, arbitrary Dayjs tokens/locale parsing,
+millisecond/12-hour column panels and measured rc-picker internals are not exposed.
+
+### ConfigProvider: inherited themes and portalled controls
+
+`theme="light" | "dark"` chooses a subtree theme; omission inherits the nearest
+provider, or the document theme when no provider selects one. `tokens` merges Klun
+CSS custom properties (`--accent`, `--fg`, etc.) with the parent. Undefined options
+and token values inherit, and explicit component `disabled={false}` enables a
+control inside a disabled provider. Dialog, Popover, Tooltip, Toast, ContextMenu,
+fullscreen Spin and AiPanel carry language/direction/theme/tokens into their body
+portals. Native browser controls retain the browser's own formatting and UI.
+
+Pagination consumes Chinese/English text and mirrors navigation arrows. Select,
+MultiSelect and Cascader localize built-in entry/search/loading labels while
+preserving caller-provided content; DatePicker localizes calendar actions.
+DataTable consumes configuration for selection/sort/filter/paging and live status;
+its fixed left/right column runs mirror to leading/trailing edges in RTL, including
+loading rows. Host-rendered cell actions remain owned by the host. Text spacing,
+borders and edge affordances use logical CSS; chart coordinates and centered
+transforms retain physical geometry.
+
+This configuration uses Klun CSS tokens, not AntD's CSS-in-JS token algorithms or
+AntD component configuration objects. It does not claim compatibility with AntD
+`theme.algorithm`, `prefixCls`, `getPopupContainer` or arbitrary locale objects.
+
+### Menu and ContextMenu: complete navigation contract
+
+Menu supports controlled/default selectedKeys and openKeys, single/multiple
+selection, vertical/horizontal/inline modes, nested items, disabled branches and
+per-item callbacks. A standalone root has one Tab entry; commands use programmatic
+focus, arrow keys/Home/End/typeahead, and native Enter/Space activation. Inline
+navigation walks expanded descendants. Popup Escape/backward closes only the
+focused level and restores its trigger, including RTL and deeper nesting. Selecting
+a leaf dismisses the tree unless closeOnSelect=false (the default for multiple).
+When the focused command disappears or becomes disabled, focus moves to the first
+available command without stealing focus from an external control.
+
+ContextMenu supports pointer/ContextMenu-key/Shift+F10 opening, typed context passed
+to commands, icon strips, nested menus and host cancellation through preventDefault
+in onOpen or the trigger handler. Internal menu scrolling preserves the menu;
+page scroll dismisses the pointer anchor. Long menus are bounded and scroll within
+the viewport, submenus flip to available space, and Escape/backward restores one
+level at a time. Omitted configuration inherits through all portal levels.
+
+Klun uses string ids/items and command callbacks instead of AntD key/domEvent/
+keyPath info objects. Root menus remain visible components; a host owns overall
+opening via Popover/Dropdown. Search is a Klun level filter, not an AntD API.
+AntD Menu.Item/ItemGroup/children syntax, inlineCollapsed, overflow collection,
+hover-delay configuration and CSS-in-JS semantic customization are not replicated.
+ContextMenu is the Klun command surface corresponding to AntD Dropdown's
+contextMenu trigger; its hook/list APIs and quick strip remain Klun-specific.
+
+### Pagination: state and boundary behavior
+
+`page`/`pageSize` are controlled when supplied, otherwise defaultPage/defaultPageSize
+initialize internal state. User changes notify onPageChange/onPageSizeChange and
+onChange with the proposed pair even if a controlled host refuses the update.
+Clicking the active page is a no-op; empty results show a disabled page 1 and do
+not notify. showTotal receives the normalized total and inclusive visible range
+(`[0, 0]` for empty results). Numeric boundaries are finite integer values capped
+at Number.MAX_SAFE_INTEGER; invalid pageSize falls back to 20, negative total to 0.
+
+A shrinking total clamps the displayed page without a synthetic event. If results
+return, the originally requested page returns until the user changes it, matching
+the reference state model. Klun preserves its existing page-size contract: selecting
+a size resets the proposed page to 1 (AntD preserves/clamps the current page).
+Choices deduplicate and reject non-positive or unsafe integer values. The uncontrolled
+size menu discards open state when disabled/hidden. The numeric quick jumper commits
+on Enter, clamps to the available range, discards its draft on blur and leaves IME
+Enter untouched. hideOnSinglePage, showQuickJumper/showSizeChanger and host slots
+remain independent. Chinese/English labels and RTL arrows inherit configuration;
+the existing footer layout wraps for narrow viewports.
+
+The API keeps page/onPageChange rather than AntD current/onShowSizeChange. It does
+not add AntD simple mode, prev/next/jump itemRender or arbitrary native prop forwarding.
+
+### Card: composition and narrow content
+
+Card retains its section/flush API and forwards native attributes/style/ref.
+size="small", type="inner" and variant (taking precedence over bordered) select
+compact/inner/borderless layouts. Loading hides the pending body and localizes
+its status label, while cover/actions remain available. Card.Grid/Card.Meta are
+also exported as CardGrid/CardMeta, with native div attributes/ref. Grid defaults
+to three columns and one column below 480px; host width styles override defaults.
+Titles, metadata and action slots wrap inside their available width. Existing
+Tabs can be composed in extra/body rather than adding Card tabList aliases.
+Klun does not implement AntD prefixCls/semantic style maps or its breakpoint grid
+system inside Card; use the library Grid for custom responsive columns.
+
+### Tag and Divider: native composition
+
+Tag forwards native span attributes/ref and lets host style override its CSS
+color. icon accepts existing Icon names or ReactNode. Close stops propagation
+before onClose; preventDefault retains the tag and the check state. Check/close
+use separate native buttons, so Enter/Space and disabled semantics work without
+nested controls. checked is controlled; defaultChecked initializes local state.
+Close labels consume locale; disabled=false overrides provider disabled. Long
+labels truncate inside the available width while preserving their full accessible
+text (supply title for a pointer tooltip). Klun retains CSS color/variants and
+pressed-button semantics rather than AntD preset color maps/CheckableTag aliases.
+
+Divider forwards native div attributes/style/ref. orientation remains
+horizontal/vertical; titlePlacement start/center/end follows inherited direction.
+variant solid/dashed/dotted takes precedence over the legacy dashed flag. Host
+style controls spacing; captions wrap on narrow screens, and vertical captions
+are ignored. Klun keeps logical placement and existing margin geometry rather
+than AntD physical left/right aliases, semantic style maps or responsive sizes.
+
+### Segment: focus and dynamic data
+
+Segment retains string-valued options and group/pressed-button semantics. There
+is one tab stop among enabled options. Horizontal arrows follow provider RTL;
+vertical arrows use Up/Down; Home/End skip disabled options. Re-selecting the
+current value sends no change. Missing selected values remain host-owned, with
+a first-enabled keyboard entry; removing/disabling the focused option restores
+owned focus without stealing external focus. IME and canceled native key events
+are ignored. Empty/all-disabled groups have a focusable root. Native div
+attributes/ref/style, ReactNode icon/label and block layout are supported; label
+content must be noninteractive. Chip forwards native button/ref and consumes
+global disabled with explicit overrides. Default View labels consume locale.
+Klun keeps its string values/button markup rather than AntD radio/name form
+submission, primitive/number option shorthand, size/shape or semantic aliases.
+
+### Nav / Sidebar: host-owned navigation and shell state
+
+Nav keeps route value/onChange controlled; current clicks send no change.
+Arrow/Home/End navigation starts from the focused destination even when the host
+refuses a route change. More and portaled menus keep their own keyboard behavior;
+disabling Nav/removing overflow discards pending open state. Item context commands
+inherit item/Nav disabled, including explicit false under disabled provider.
+Rich-label command names use their text. Missing routes do not auto-commit;
+removing/disabling a focused destination restores owned focus. Ink tracks both
+strip and destination resizes. Nav native attributes/style/ref are forwarded;
+internal built-in labels consume locale. It is page navigation (aria-current),
+not a Tabs tabpanel controller or an automatic horizontal overflow collector.
+
+Sidebar forwards aside attributes/style/ref; shell provider collapse can be
+explicitly overridden. Collapsed content stays mounted but inert/aria-hidden.
+Configured finite min/max bounds constrain pointer and keyboard proposals;
+controlled hosts may refuse them. Only primary-pointer drags resize; lost
+capture/cancel ends a drag. RTL reverses drag/arrow direction; Home/End reach
+bounds, composing/modified keys are ignored. Categories/resize labels consume
+locale. Existing CSS hides Sidebar at <=1024px; shell owns the external collapse
+control/focus and mobile navigation. Nested Menu provides navigation expansion.
+Klun retains 300px default and zero-width collapse instead of AntD Sider's
+breakpoint callbacks, built-in trigger/80px rail, theme and collapsed state aliases.
+
+### States and general feedback: mapping and boundaries
+
+EmptyState is the illustrated empty/offline explanation; ErrorState is the
+existing alert with optional host-owned retry; Empty is the general image/
+description/action entry; Result displays status/exception outcomes without
+an automatic live alert. LoadingBlock/InlineSpinner/Spin announce loading;
+Skeleton/TableSkeleton are decorative. Default state/retry/loading/progress
+names consume locale; explicit host content is preserved. Empty/Spin/Result
+forward native div refs and attributes. Spin delay changes restart the wait,
+cancel/unmount clear timers, nested content becomes inert only while shown, and
+fullscreen uses the configured body portal. It is a loading overlay, not a
+modal focus trap or a replacement for host request cancellation.
+
+Primitive Skeleton defaults to 12px height and sanitizes nonfinite geometry;
+compound placeholders retain avatar/title/paragraph/loading/active behavior.
+Skeleton/TableSkeleton rows and Progress visual steps cap at 1000 to prevent
+unbounded DOM allocation; use virtual data lists/continuous progress above that.
+Progress retains the 0–1 value contract (precedence over percent), line/circle/
+dashboard, bounded success, RTL logical gap placement, explicit formatting and
+accessible values. format returning null hides info, and label=0 stays visible.
+Step gaps shrink to fit narrow containers. State descriptions/actions wrap;
+table placeholders scroll locally. Existing Klun art/status geometry remains.
+AntD semantic style maps, compound Skeleton element aliases, Spin percent=auto/
+global indicator and gradient/array Progress colors remain intentional differences.
+
+### Icon: names, fallback and meaning
+
+Icon resolves only own glyph definitions; prototype-like names safely use the
+same empty box as unknown names and warn. The fallback preserves a supplied
+label/aria-label. Decorative icons remain aria-hidden; meaningful spans use
+role=img and their SVG stays nonfocusable/hidden. Native span attributes/ref and
+host styles are forwarded. Numeric sizes include zero, negative values clamp to
+zero and nonfinite values use CSS defaults; CSS dimensions remain supported.
+Klun retains the PingCode glyph catalog rather than importing AntD icon exports,
+two-tone colors, icon-font scripts or component/viewBox aliases. Use a real Button
+or ActionButton for interactive actions rather than relying on an icon alone.
+
+### Charts: finite data, empty states and descriptions
+
+AntD core has no equivalent chart family; Klun preserves its bar, CSS donut,
+SVG trend and positioned score/effort matrix, composing the existing Card/Avatar.
+Bars/donuts treat negative or nonfinite amounts as zero; zero bars have no height.
+Donut totals scale before summing so very large finite data retains proportions;
+empty/zero distributions use a neutral rail. Sparkline preserves finite signed
+values, scales before measuring its range, uses zero for nonfinite samples and
+shows a dot for one sample. Invalid/nonpositive dimensions use defaults.
+Scatter drops nonfinite coordinates and clamps negative score/effort positions
+to its nonnegative origin; math axes stay physical in RTL. Empty charts have
+localized feedback; explicit emptyState and accessible names are retained.
+Bar/Sparkline provide data descriptions; Donut keeps its data name (or description
+when a host name is supplied); points expose coordinate descriptions and consume
+provider disabled, with explicit overrides. Duplicate category names are allowed;
+point IDs remain unique host keys. Rings retain aspect ratio and legends wrap,
+long labels truncate, and chart overflow stays local on narrow screens. These
+are lightweight displays, not Ant Design Charts axis/tooltip/zoom replacements.
+
+### SelectionBar batch contract
+
+SelectionBar composes Checkbox/Menu/Popover; AntD 6.6.5 core has no matching bulk strip. The reference is `table/hooks/useSelection.tsx` for selection ownership and Menu/Popover for command interaction. Preserve the Klun table-header-height overlay (`--table-head-height`, currently 44px) and use `overlay={false}` for a wrapping board strip. Excess overlay commands scroll locally.
+
+Counts are finite nonnegative integers; zero selections disable commands, while Cancel and select-all remain available. `disabled` consumes ConfigProvider with explicit false overriding it; each action's disabled remains authoritative. Default count, Cancel, More and select-all labels consume locale. Only the count has live status semantics; interactive commands remain exposed in a labelled group.
+
+`loading` locks selection and all commands for host-owned work. Commands returning a Promise are automatically locked, expose aria-busy and prevent repeat clicks until settlement. Throws/rejections retain the selection, show a retryable error and invoke `onError`; the next command clears the error. Menus close when disabled/loading or removed and do not reopen after unlock. Focus owned by an inline command or its menu trigger is preserved across pending work; unrelated external focus is left alone.
+
+`BulkActions.apply` accepts void or Promise<void>. Standard status/baseline/schedule and round-robin commands notify and clear only after success. Round-robin waits for every started write, including rejected writes; empty people disable distribution. Hosts own request cancellation, authorization, stale selection reconciliation, error details and transactional rollback for partially successful distribution. Extra/More commands retain host-owned notifications and clearing. No AntD semantic style/prefixCls API or server mutation layer is introduced.
+
+### Inline editor contracts
+
+PeoplePicker/QuickSelect are Klun cell controls composed from Select-style listbox/search behavior, Avatar, Tag and Popover; compare AntD 6.6.5 `components/select/index.tsx` and `@rc-component/select@1.10.1` `Select.js`/`OptionList.js`. QuickText maps to `components/typography/Editable.tsx` while retaining a single-line cell input, untrimmed commit values and the 220ms click/double-click distinction. No new runtime dependency or AntD API aliases are introduced.
+
+All three consume ConfigProvider disabled with explicit false override and preserve host-owned controlled values, including unknown choices. Default text consumes locale; custom labels stay intact. QuickSelect and QuickText additionally support readOnly. ListWorkbench forwards the field configurations: TextField disabled/readOnly/validate(row,next)/onError(row,error), EnumField disabled/readOnly, and AssigneeField disabled/loading/error/onRetry. Workbench assignee triggers honor the same resolved disabled state as their picker.
+
+QuickText offers a keyboard entry even without an interactive display node. Enter/F2/Space opens, Enter/blur commits once, Escape cancels; IME and modified commit keys do not save/cancel. `validate(next)` returns an accessible error and keeps the draft; synchronous write failures show retry feedback and call onError. Successful keyboard completion restores its own display focus, external blur retains external focus. Empty nonnullable drafts and unchanged writes keep the existing behavior; invalid maxLength is ignored, finite nonnegative lengths use native UTF-16 counting. Mid-edit external values do not replace the draft; disabling/readOnly cancels without a write. QuickText validation/commit are synchronous; hosts manage async writes and reconciliation.
+
+QuickSelect skips disabled options for keyboard/pointer picks, suppresses unchanged writes, retains typed search on keyboard opening, scrolls the active option and keeps combobox focus. Unknown values remain visible. Clear is a separate command row, so a real `\u0000clear` value is safe; clearing still returns the existing empty-string API. There is no pending multi-value confirmation mode: a pick commits immediately and Escape/outside dismisses without a write. Hosts keep option values unique and provide immutable lists.
+
+PeoplePicker supports disabled people/sources, fallback when a tab disappears, RTL tab navigation and real row focus for Arrow/Home/End. Unknown assigned IDs remain unselected, and `__unassigned__` can be a real ID. Loading and error are host-owned; cached rows are protected during them, onRetry requests a host retry, and async results recover owned removed/disabled focus without moving external focus. It is a single-select picker; Unassigned returns null, unchanged picks close without redundant writes. Requests, authorization, caching and cancellation belong to the host.
+
+### AiPanel interaction contract
+
+AntD 6.6.5 core has no AI panel; map its layer to `components/modal/Modal.tsx` and `@rc-component/dialog@1.10.0` `Dialog/index.js`, and compose a native multiline input. AiPanel and Dialog now share the existing focus/scroll stack with ordered modal z-index, topmost-only Escape, hidden/inert focus filtering and opener restoration. Callback changes do not refocus the composer. Preserve the Klun floating panel/brand geometry, with viewport-bounded width/height, logical RTL placement and reduced-motion styling.
+
+`onSubmit(text)` receives trimmed plain text and may return void or Promise<void>. Host pending or a returned Promise locks sending, suggestions/chips/history/attachment; the composer stays readable while pending. Throws/rejections keep the draft, show a local error and call onError. `error` and `onRetry` also support host-owned failures; retry uses the host callback when present, otherwise resubmits the retained draft. Successful submission clears the draft; stale completions after close/reopen/unmount cannot modify the new session. Close remains available while pending; hosts own aborting requests.
+
+Enter sends, Shift+Enter inserts a newline, IME/modified keys do not submit or dismiss. Default greeting/control/status text consumes locale, disabled consumes ConfigProvider with explicit false override, and existing portal theme/tokens remain intact. Body scrolling follows new or streamed text only while the reader remains near the end. The log exposes only host-supplied plain-text messages; pending/error feedback remains separately announced. History/attachment invoke host callbacks and are unavailable when no callback exists. No model, network, upload, Markdown execution, transcript persistence or automatic assistant reply is introduced; host controls messages, request cancellation and business authorization.
+
+Typography interaction alignment: editor composition, key229, modified and repeated keys
+cannot submit/cancel. Finishing restores only owned focus; external focus and child updates
+are preserved. Controls follow locale; native textarea draft/Shift+Enter and synchronous
+host save callbacks retain the existing contract. Async copy text stops before clipboard
+write after unmount/disable, serializes one attempt and reports failure with retry. Once a
+native clipboard write has begun, it cannot be canceled. CSS ellipsis remains line-clamp
+without AntD text measurement/suffix/tooltip algorithms; no typography autosize/onBlur-save,
+copy fallback API or Promise-based edit validation is added. Title runtime levels stay1–5.
+
+### Ship chrome 与阅读/编辑组合契约
+
+这些业务模块没有 AntD 核心库的一对一组件，按组合行为对照固定 6.6.5 的 Layout/Menu/Tabs/Input/Typography/Empty/Modal/Progress，并复用本库已验收的 Nav、Menu、Popover、Input、Dialog、Checkbox 和 Progress；不引入业务路由、存储或请求依赖。
+
+| 模块          | 已支持能力                                                                                                                | 有意保留的边界                                                                           |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Rail          | 受控 activeId、主/底部按钮、aria-current、中文导航名、provider 禁用及 item.disabled 显式覆盖                              | 路由由 onClick 宿主实现；不模拟 Menu 的选择模型                                          |
+| Header        | 受控 search/tabs、搜索 ref、产品切换、账户/通知/Ping/收藏/sidebar 操作、IME/修饰/重复 Enter 保护，禁用和中文名称          | actions 是宿主 ReactNode；快捷键全局注册和通知加载由宿主实现                             |
+| Toolbar       | 受控搜索/rules/sort/group、builder/菜单/可移除chip、零值、空schema安全、切字段重置operator、动态禁用关闭popup             | operators/freeText 是宿主声明；不执行查询/校验业务筛选语义，不提供异步加载API            |
+| Bits          | 有限size/未知类型fallback、title F2或双击编辑、IME保护/trim/空值保留/恢复焦点、收藏/快捷入口/提示条、provider 禁用        | title同步onEdit，空标题不提交；统计数据/权限和富suffix由宿主提供                         |
+| Views         | Board/quarter Roadmap/DocSplit 受控阅读数据、中文空状态、内部滚动/移动布局；零period不生成非法CSS，无动作卡片不占tab位置  | 无看板拖放/卡片提交/请求；RoadmapView按顺序周期分配，不替代有日期的 RoadmapEditor        |
+| ShellSurfaces | AccountMenu复用Menu；Shortcuts/QuickStart复用Dialog；受控checked/toggle/go/reset、实际checkbox下一值、中文labels、0 intro | 身份、快捷键注册、权限/导航/持久化由host提供；没有请求的空状态是实际空列表               |
+| DetailBlock   | 可省略/零标题actions、原生section/h3；DetailTool原生按钮provider禁用                                                      | host自定义actions自行处理禁用/权限                                                       |
+| EditableText  | text/editSeed、受控/默认editing与draft、readOnly/disabled显式覆盖、中文save/cancel、editor及触发器焦点、paragraph/note    | 同步onSave；空draft重提交原文兼容防误删，Promise提交/失败/授权由host封装，不假报异步成功 |
+
+窄屏 Header/Toolbar换行，Board/Roadmap横向滚动限定在本身，DocSplit上下排布；保留既有主题tokens与API。组合验收示例见 Ship/Alignment/Chrome，回归见 ShipChromeAlignment.test.tsx。
+
+### Ship 详情、评论与附件组合契约
+
+对照固定 AntD 6.6.5 ActionButton 的异步提交锁、Input/TextArea、Modal、Upload 和 Timeline/Steps 的组合行为，业务模块继续采用本库组件，不冒充 AntD 的业务扩展。
+
+| 模块                          | 行为                                                                                                                                                                                          | 保留差异                                                                                                                 |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| DetailSheet / CommentComposer | 受控详情/分区/字段/过滤，零内容；provider 禁用、中文操作名称；IME 安全发送，Promise 待定锁，失败保留草稿并提示，false 不清空，成功仅清空提交时草稿；关闭/禁用隔离旧结果，恢复本组件拥有的焦点 | Pin 暂无宿主回调而禁用；加粗/代码是展示工具；附件、引用、授权和业务请求由宿主实现                                        |
+| CommentThread                 | 受控评论/回复/编辑/删除/反应；Promise 提交防重复，失败保留草稿并可重试；确认删除，剪贴板结果提示；孤儿和循环父链有限遍历，RTL 缩进                                                            | 评论 ID 必须唯一；实体切换由宿主重新挂载；无虚拟列表或自动网络请求，部分宿主文本/时间格式保留原文                        |
+| AttachmentUpload              | 文件选择/拖入、读取前大小限制、真实 FileReader 读取、有限进度、读取后最新回调；Promise 失败提示，计时器/reader 卸载清理；provider 禁用，预览/删除确认/复制真实结果                            | onUpload 仍收到 name/size 元数据，不传送或保存文件字节；读取与进度不是服务器上传。需要真实传输时使用 Upload 或宿主传输层 |
+| LinkPicker                    | 受控关系、按类型候选/搜索/已关联状态，候选移除后禁止提交，类型失效重置，provider 禁用也保护自定义 opener，卸载关联确认                                                                        | onLink/onUnlink 为同步宿主提交；候选加载、错误和业务授权由宿主管理；不凭空查询远端实体                                   |
+| FilePreview                   | 受控元数据预览，按文件身份重置缩放，RTL 缩放原点；下载生成与当前展示一致的示意内容，CSV 防公式并正确转义，URL 延后释放                                                                        | 没有原始文件字节/鉴权地址，预览和下载明确为示意，不表示原始附件下载成功；下载提示仅表示交给浏览器                        |
+| TransitionsTimeline           | 受控活动/当前状态/工作流标签、空状态、本地化和 RTL；排除空/重复状态，安全处理状态 ID                                                                                                          | 只读展示，保留既有状态词汇和摘要识别规则；不执行工作流、不持久化、不替代通用 Timeline                                    |
+
+验收示例 Ship/Alignment/Detail；回归 ShipDetailAlignment.test.tsx。无需新增依赖。
+
+### Ship 实体与分享弹窗契约
+
+对照固定 AntD6.6.5 Modal/ActionButton、Form（实际 form1.8.6）以及本库 Dialog、Field、Select、DataTable、Tree、Menu；复用宿主受控协议，不创建请求或权限系统。
+
+| 模块         | 已支持行为                                                                                                                                                                                                  | 边界                                                                                                                                                                                             |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| EntityDialog | 字段/侧栏/初始值、blur 与提交必填校验、唯一 label ID、零计数、prototype 字段安全；打开捕获基线，不因 inline fields 改变清空草稿；关闭重开重置；Promise 提交锁/失败提示/retry/继续创建；禁用与关闭隔离旧结果 | 不再人工延时；宿主 onSubmit 负责真实提交，工具节点由宿主管理；附件/工单尚无 host callback 的按钮明确禁用；无富文本、远端字段校验、通用 Form 实例                                                 |
+| EntityPicker | list/table、scope/search/filter/sort、受控选择与差异计数、去重，保留跨页 ID；provider 禁用不能被非零 counts 覆盖；Promise confirm 锁/错误/retry，原标签缺失时 ID 提供 accessible name                       | rows 和分页候选由 host 提供；本身不因当前页缺少 ID 删除选择；成功是否关闭由 onConfirm 宿主决定，toolbar 需要 search 配置；无服务端查询/授权                                                      |
+| ShareDialog  | 打开/报表切换重置草稿，分享范围/expiry/schedule/hour/recipients/format；定时发送必须有效非空收件人且 hour 为6–20整数；Promise save/copy 锁和失败重试，旧会话结果忽略，复制成功才 Copied                     | link 必须来自 host，空 link 不伪造示例地址；onCopy 缺失或空 link 禁用复制；保留 onChange→onSave 顺序，onChange 收到尝试值，持久化失败时 host 负责回滚外部状态；UI 不执行后台导出或授予实际访问权 |
+
+中文 RTL、空链接及失败重试故事见 Ship/Alignment/Entity，回归 ShipEntityAlignment.test.tsx；选项值是既有英文枚举，宿主业务文本不自动翻译。
+
+### Ship 画布、路线图、工作台与项目向导契约
+
+没有 AntD 核心库对应的业务编辑器。按固定6.6.5 Card/Layout、Table/InternalTable 与实际 table1.11.1、Timeline/Steps 与实际 steps1.2.3、Form 与实际 form1.8.6、Modal/ActionButton，以及本库的已验收组合行为审查。
+
+| 模块          | 已支持行为                                                                                                                                                                                                                                                                                                                                                                                                                             | 有意保留的边界                                                                                                                                                                                                                                                                                                       |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ReportCanvas  | 受控 widgets、5种内置主体、宿主 dataset/renderBody/actions、12列宽度、按钮与自身拖动排序、删除确认/新增/公告；provider禁用/loading保护自定义 opener和写事件；自身handle与active drag ID验证，禁用旧drag失效；IME安全新增、unique label ID、非法span回退6，窄屏全宽卡片                                                                                                                                                                 | 无持久化/请求、跨画布拖放、布局碰撞算法；缺少有效 chartTypes 时回退现有五类。自定义 body/controls由host管理；onChange同步，host失败状态由host展示，未假报服务器保存                                                                                                                                                  |
+| RoadmapEditor | 受控 lane/period/bar、rename/recolour/move/add/delete、按钮路径/自身drag、状态公告、weekends/zoom/fit；每个period独立year，quarter参数整数/日期范围保护及year0正确；空lane/period禁止创建、动态候选校验；provider禁用/RTL箭头/IME、unique IDs                                                                                                                                                                                          | quarter/month是既有显示粒度，不生成真实月级日期跨度；未知lane过滤，host IDs/periods须唯一；onChange/onRename同步，不运行排程或持久化。时间线横向滚动在本身；只提供已声明颜色，不创建存储                                                                                                                             |
+| ListWorkbench | 受控 view/selection，过滤/排序/分组/table/board/paging/列设置、行与批量菜单、表格inline editors；同tick patches合并、最新callback、卸载/identity/禁用取消旧patch、finite page/size、原型字段安全；board也遵守loading/error/empty；Promise create/edit/bulk-properties/import/delete与真实clipboard结果，失败保留选择/草稿并提示，等待期间新选择保留；CSV引号/转义/多行/CRLF/BOM解析，拒绝坏header/列数/引号，导出公式保护与延迟URL释放 | 全量客户端rows过滤分页，无服务端查询/授权/路由/持久化；CSV仅平坦primitive，host自定义onExport负责自身内容安全；import读取完成用最新callback，卸载不启动写，已开始host请求不能自动撤销；onChange类view/inline协议保持同步，其他bulk能力沿SelectionBar协议；identity变化重置本地会话，entity切换host须正确设置identity |
+| ProjectWizard | 三步type/details/members、radio键盘/RTL/IME保护、step focus/公告、脏草稿退出确认、唯一field IDs；挂载捕获baseline不被inline defaults清空；empty catalogue与name256/key15/enum/candidate校验；owner包含且不可移除、成员去重、过期roster选择拒绝；Promise提交锁/error/retry/禁用与卸载旧结果隔离                                                                                                                                         | open由host通过mount/unmount管理，每次重开需重新挂载，owner/initialdefaults为会话配置；member协议仍name，重名唯一性由host负责；onSubmit成功的关闭由host决定；无创建网络、邀请、身份或真正权限授予                                                                                                                     |
+
+中文 RTL及loading/error/empty/disabled示例见 Ship/Alignment/Workbench；部分既有领域枚举、菜单、提示和统计说明仍为英文，宿主内容不自动翻译。回归 ShipWorkbenchAlignment.test.tsx。画布和路线图文案只声明应用更改，不再虚构 browser/localStorage 保存。