prime-ui-kit 0.15.0 → 0.17.0

package/src/components/hint/COMPONENT.md

@@ -6,7 +6,7 @@
 > Help text or a validation error under a field.
 
 ## When to use
-- Under a custom control without `hint` / `error` props, or a hand-built field, where you wire the ids yourself: format rules, limits, where the value comes from.
+- Under a control without `hint` / `error` props (an embedded `Datepicker.Panel`, a custom control), where you wire the ids yourself: format rules, limits, where the value comes from.
 - As the error message of such a control (`invalid`), in the same slot as the hint.
 
 ## When not to use
@@ -31,17 +31,22 @@ Hint.Root      <p> with the text
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Hint.Root
-`ref` → `HTMLParagraphElement`. A `<p>` with the support text; provides its tier to nested icons. + native `<p>` props (`id`, `role`, `className`, …).
+`ref` → `HTMLParagraphElement`. A `<p>` with the support text; provides its tier to nested icons.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the paired field: 12/16 for xs–m, 13/20 for l and xl. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the paired field: 12/16 for xs–m, 13/20 for l and xl. Without it the tier of its host, else `m`. |
 | `invalid` | `boolean` | `false` | Error styling: danger text that drops in (fade + 4 px from above). |
-| `disabled` | `boolean` | `false` | Disabled text color, next to a disabled control. |
+| `disabled` | `boolean` | `false` | Disabled text color, next to a disabled control. A disabled `Fieldset` around the hint sets it too. |
 | `children` | `ReactNode` | — | Text, optionally with `Hint.Icon` first. |
+| `…rest` | `HTMLAttributes<HTMLParagraphElement>` | — | `children`, `id`, `aria-live`, `className` and the other paragraph attributes. |
 
 ### Hint.Icon
-`ref` → `HTMLSpanElement`. An `aria-hidden` `<span>` holding a glyph: 14 px for xs–m, 16 px for l and xl, centred on the first line. + native `<span>` props.
+`ref` → `HTMLSpanElement`. An `aria-hidden` `<span>` holding a glyph: 14 px for xs–m, 16 px for l and xl, centred on the first line.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (the glyph), `className` and the other span attributes. |
 
 ## Variants
 Hint has no `variant` or `tone`; its states are flags.
@@ -63,29 +68,33 @@ The hint is always smaller than the field text; use the field's size.
 | `invalid` | Danger text, drops in | Validation error | `false` |
 | `disabled` | Disabled text | Under a disabled control | `false` |
 
-**Combinations** — one element switches between the hint text and the error text with `invalid` (no layout jump); add `role="alert"` to an error shown after a user action. `invalid` and `disabled` together make no sense. There is no success state: use neutral text, or a [Banner](../banner/COMPONENT.md) for a result.
+**Combinations** — one element switches between the hint text and the error text with `invalid` (no layout jump); a standalone hint that changes after an action stays mounted with `aria-live="polite"` (inside a field the frame does it). `invalid` and `disabled` together make no sense. There is no success state: use neutral text, or a [Banner](../banner/COMPONENT.md) for a result.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
 | error | `invalid` | `data-invalid="true"`; the message drops in over `fast` (fade + `--prime-space-1` from above, no shake, no layout shift) and the color eases from the hint color |
-| disabled | `disabled` | `data-disabled="true"` |
-| size | `size` | `data-size` |
+| disabled | `disabled`, or a disabled `Fieldset` around it | `data-disabled="true"` |
+| size | `size`, else the host tier | `data-size` |
 
 Hint is not interactive: hover and focus belong to the field.
 
 ## Layout & spacing
-- Field → hint: the tier `hint-gap` (`--prime-control-<size>-hint-gap`), set by the field layout, not by Hint.
+- Field → hint: the tier `--field-hint-gap`, set by the field layout, not by Hint. The text and the icon size come from the field tier (`--field-hint-size`, `--field-hint-lh`, `--field-hint-icon`).
 - Icon → text gap: `--prime-space-1`. Long text wraps (`overflow-wrap: anywhere`).
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 No keyboard interaction.
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - Give the hint an `id` and put it into the control's `aria-describedby` so screen readers read it with the field.
-- Add `role="alert"` to an error that appears after a user action.
+- Inside a field the frame announces an error that arrives: its support slot is a polite live region. A standalone Hint whose text changes after an action stays mounted with `aria-live="polite"`.
 - `Hint.Icon` is decorative; the text carries the meaning.
 
 ### Labels
@@ -96,17 +105,18 @@ No `labels`.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | Help text under a hand-built field, linked to its input by `id` and `aria-describedby`. |
-| [sizes.tsx](examples/sizes.tsx) | Every size tier, matching the field above: 12/16 for xs–m, 13/20 for l and xl — `size`. |
+| [overview.tsx](examples/overview.tsx) | Help text under a calendar that has no hint of its own, linked to it through `id` and `aria-describedby` — `id`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier, one per field tier: 12/16 for xs–m, 13/20 for l and xl — `size`. |
 | [states.tsx](examples/states.tsx) | Default help text next to an error and a hint under a disabled control — `invalid`, `disabled`. |
 | [with-icon.tsx](examples/with-icon.tsx) | A leading icon centred on the first line, in the default and the error state — `Hint.Icon`. |
-| [hint-or-error.tsx](examples/hint-or-error.tsx) | After a check the error replaces the hint in the same element, without a layout jump, and is announced — `invalid`, `role`. |
+| [hint-or-error.tsx](examples/hint-or-error.tsx) | After a check the error replaces the hint in the same element, without a layout jump, and a polite region reads it — `invalid`, `aria-live`. |
 
 ## Mistakes
 - `<Hint.Root>` under an Input → use `hint` / `error` on `Input.Root`; it links the ids itself.
 - A separate hint and error element at the same time → one element; the error replaces the hint.
 - Hint without `id` + `aria-describedby` → the screen reader does not connect it to the field.
-- Hint size different from the field size → use the same `size`.
+- Hint size different from the field size → use the same `size`, or none inside a sized host.
+- `role="alert"` on a field error → none; the field frame announces it, a standalone hint takes `aria-live="polite"`.
 
 ## Related
 - **Built from:** —

package/src/components/hint/examples/examples.module.css

@@ -1,12 +1,21 @@
 /* Layout of the Hint scenarios: semantic tokens only. */
 
-/* overview.tsx, hint-or-error.tsx: label → control → support row with the m-tier gaps. */
+/* hint-or-error.tsx: control → support row at the m-tier hint gap. */
 .field {
   display: grid;
   justify-items: start;
   gap: var(--prime-control-m-hint-gap);
 }
 
+/* overview.tsx: the same pair in a 320 px column — an embedded calendar measures its container
+   for its month, so the column gives it one. */
+.calendarField {
+  display: grid;
+  justify-items: start;
+  gap: var(--prime-control-m-hint-gap);
+  width: min(100%, calc(var(--prime-space-20) * 4));
+}
+
 .actions {
   display: flex;
   flex-wrap: wrap;

package/src/components/hint/examples/hint-or-error.tsx

@@ -1,4 +1,4 @@
-/** After a check the error replaces the hint in the same element, without a layout jump, and is announced — `invalid`, `role`. */
+/** After a check the error replaces the hint in the same element, without a layout jump, and a polite region reads it — `invalid`, `aria-live`. */
 import { Button, Hint } from "prime-ui-kit";
 import * as React from "react";
 
@@ -17,7 +17,7 @@ export default function HintHintOrErrorExample() {
           Сбросить
         </Button.Root>
       </div>
-      <Hint.Root invalid={invalid} role={invalid ? "alert" : undefined}>
+      <Hint.Root invalid={invalid} aria-live="polite">
         {invalid
           ? "Заполните название перед публикацией."
           : "Черновик можно сохранить без названия."}

package/src/components/hint/examples/overview.tsx

@@ -1,22 +1,21 @@
-/** Help text under a hand-built field, linked to its input by `id` and `aria-describedby`. */
-import { Hint, Input, Label } from "prime-ui-kit";
+/** Help text under a calendar that has no hint of its own, linked to it through `id` and `aria-describedby` — `id`. */
+import { Datepicker, Hint } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 export default function HintOverviewExample() {
-  const inputId = React.useId();
   const hintId = React.useId();
 
   return (
-    <div className={styles.field}>
-      <Label.Root htmlFor={inputId}>ИНН компании</Label.Root>
-      <Input.Root id={inputId}>
-        <Input.Wrapper>
-          <Input.Field inputMode="numeric" defaultValue="7707083893" aria-describedby={hintId} />
-        </Input.Wrapper>
-      </Input.Root>
-      <Hint.Root id={hintId}>10 цифр для юрлица, 12 — для ИП.</Hint.Root>
+    <div className={styles.calendarField}>
+      <Datepicker.Panel
+        mode="single"
+        role="group"
+        aria-label="Дата отгрузки"
+        aria-describedby={hintId}
+      />
+      <Hint.Root id={hintId}>Склад отгружает по будням, заказ собирают за два дня.</Hint.Root>
     </div>
   );
 }

package/src/components/hint/examples/sizes.tsx

@@ -1,4 +1,4 @@
-/** Every size tier, matching the field above: 12/16 for xs–m, 13/20 for l and xl — `size`. */
+/** Every size tier, one per field tier: 12/16 for xs–m, 13/20 for l and xl — `size`. */
 import { Hint, Typography } from "prime-ui-kit";
 
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;

package/src/components/input/COMPONENT.md

@@ -51,7 +51,7 @@ The trailing side has a fixed CSS `order`, independent of JSX order: value · en
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier for height, padding, radius, text, label and hint. Without it the field takes the tier of its host (LoginForm, Popover, a panel with a size), else `m`. Also provided to nested controls via the control-size context. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier for height, padding, radius, text, label and hint. Without it the field takes the tier of its host (LoginForm, Popover, a panel with a size), else `m`. Also provided to nested controls via the control-size context. |
 | `label` | `ReactNode` | — | Label above the field, rendered as `<label htmlFor>`. Without it, give `Input.Field` an `aria-label`. |
 | `required` | `boolean` | `false` | Red `*` after the label (`aria-hidden`) and native `required` on `Input.Field`. |
 | `optional` | `boolean` | `false` | Muted marker right after the label text (`labels.optional`). |
@@ -59,7 +59,7 @@ The trailing side has a fixed CSS `order`, independent of JSX order: value · en
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger inset ring on the field, `aria-invalid` on the input. A non-empty `error` implies it. |
 | `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring on `Input.Wrapper` (`data-focus-ring="false"`); focus, keyboard, ARIA and the invalid ring stay. |
-| `counter` | `ReactNode` | — | Right side of the support row, usually `<Input.Counter />`. |
+| `counter` | `ReactNode` | — | Right side of the support row, usually `<Input.Counter current max />`. |
 | `reserveSupportRow` | `boolean` | `false` | Always render the support row (min height = hint line height), so an appearing error does not shift the layout. |
 | `id` | `string` | — | Id of the `<input>` (auto-generated when omitted); hint id is `<id>-hint`, error id is `<id>-error`. |
 | `strength` | `boolean` | `false` | A password strength meter for new-password fields: a stepped `ProgressBar` under the field and the level word (weak … hard) in the support row. Follows the value of `Input.Field`. |
@@ -127,7 +127,7 @@ The trailing side has a fixed CSS `order`, independent of JSX order: value · en
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` | `string` | `the field's value` | Text to copy instead of the field's current value. |
+| `value` | `string` | the field's value | Text to copy instead of the field's current value. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "children" \| "aria-label">` | — | `onClick`, `disabled` and the other button attributes. |
 
 ### Input.RevealButton
@@ -179,7 +179,7 @@ Input has no `variant` or `tone`: there is one field treatment (fill, no visible
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `focusRing={false}` | No focus ring; the field still switches to the focus fill, caret visible | A single search field where focus is obvious | `true` |
+| `focusRing` | `false`: no focus ring; the field still switches to the focus fill, caret visible | A single search field where focus is obvious | `true` |
 | `reserveSupportRow` | Empty support row of hint height under the field | Fields validated on the fly; neighbouring fields in one grid row | `false` |
 | `required` / `optional` | Red `*` / muted «необязательно» after the label | Mark the minority: required when most are optional, optional when most are required | `false` |
 
@@ -219,7 +219,7 @@ Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontro
 
 ## Layout & spacing
 - Label → field gap: tier `label-gap` (`--prime-space-1` on xs/s, `--prime-space-2` on m–xl). Field → support row: `--prime-space-1`.
-- Field → field in a form: `--prime-space-5` (20); group → actions: `--prime-space-8` (32).
+- Fields of a form stack in a label-less [Fieldset](../fieldset/COMPONENT.md) (20 apart); the form around the groups spaces them from its actions (32).
 - `Input.Root` is `width: 100%` and `min-width: 0`; there is no `fullWidth` prop — the width comes from the parent (grid column, flex item, capped wrapper).
 - Use `reserveSupportRow` on fields that share a grid row so their bottoms stay aligned when only one shows an error.
 - The value truncates with an ellipsis before icons and affixes; the field height never changes.
@@ -227,6 +227,8 @@ Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontro
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Focuses the field, then the segments at its end (clear, copy, reveal, actions). |
@@ -235,6 +237,8 @@ Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontro
 | `Escape` | With `onCommit`: puts the committed value back. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `label` renders a `<label htmlFor>` bound to the input. Without `label`, set `aria-label` on `Input.Field`. A placeholder never replaces the label.
 - Hint and error are linked through `aria-describedby`; the error replaces the hint and sets `aria-invalid="true"`.
 - `Input.Icon`, `Input.Affix`, `Input.InlineAffix` are `aria-hidden`: put the meaning in the label (e.g. "Сумма, ₽").
@@ -293,5 +297,5 @@ Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontro
 - Returning `false` from `onCommit` to refuse → reject the Promise (throw) and set `error`.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Tooltip](../tooltip/COMPONENT.md) (`Input.Action`, `Input.CopyButton`), [Spinner](../spinner/COMPONENT.md) (`onCommit`), [ProgressBar](../progress-bar/COMPONENT.md) (`strength`), `Icon` (segments)
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Tooltip](../tooltip/COMPONENT.md) (`Input.Action`, `Input.CopyButton`), [Spinner](../spinner/COMPONENT.md) (`onCommit`), [ProgressBar](../progress-bar/COMPONENT.md) (`strength`), `Icon` (segments), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Textarea](../textarea/COMPONENT.md), [Select](../select/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md) — fields with the same contract

package/src/components/input/examples/affixes.tsx

@@ -4,14 +4,14 @@ import { Input } from "prime-ui-kit";
 export default function InputAffixesExample() {
   return (
     <>
-      <Input.Root label="Адрес магазина" hint="Адрес: https://moy-magazin.shop.ru">
+      <Input.Root label="Адрес магазина" hint="Латиница, цифры и дефис">
         <Input.Wrapper>
           <Input.Affix side="start">https://</Input.Affix>
           <Input.Field placeholder="moy-magazin" />
           <Input.Affix side="end">.shop.ru</Input.Affix>
         </Input.Wrapper>
       </Input.Root>
-      <Input.Root label="Сумма платежа, ₽">
+      <Input.Root label="Сумма платежа">
         <Input.Wrapper>
           <Input.Field placeholder="0,00" inputMode="decimal" />
           <Input.InlineAffix side="end">₽</Input.InlineAffix>

package/src/components/input/examples/examples.module.css

@@ -5,7 +5,7 @@
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-8);
-  width: min(100%, var(--prime-modal-width-m));
+  width: min(100%, var(--prime-layout-form-width-m));
 }
 
 .formFields {

package/src/components/input/examples/sizes.tsx

@@ -7,11 +7,15 @@ export default function InputSizesExample() {
   return (
     <>
       {SIZES.map((size) => (
-        <Input.Root key={size} size={size} label={size} hint="Пришлём ссылку для входа">
-          <Input.Wrapper>
-            <Input.Field type="email" placeholder="name@company.ru" />
-          </Input.Wrapper>
-        </Input.Root>
+        <div key={size}>
+          <div>
+            <Input.Root size={size} label={size} hint="Пришлём ссылку для входа">
+              <Input.Wrapper>
+                <Input.Field type="email" placeholder="name@company.ru" />
+              </Input.Wrapper>
+            </Input.Root>
+          </div>
+        </div>
       ))}
     </>
   );

package/src/components/input/examples/states.tsx

@@ -4,29 +4,45 @@ import { Icon, Input } from "prime-ui-kit";
 export default function InputStatesExample() {
   return (
     <>
-      <Input.Root label="default">
-        <Input.Wrapper>
-          <Input.Field placeholder="Например, Москва" />
-        </Input.Wrapper>
-      </Input.Root>
-      <Input.Root label="disabled">
-        <Input.Wrapper>
-          <Input.Field defaultValue="Екатеринбург" disabled />
-        </Input.Wrapper>
-      </Input.Root>
-      <Input.Root label="readOnly">
-        <Input.Wrapper>
-          <Input.Field defaultValue="ID 4821-0093" readOnly />
-          <Input.Icon side="end">
-            <Icon name="status.locked" tone="secondary" />
-          </Input.Icon>
-        </Input.Wrapper>
-      </Input.Root>
-      <Input.Root label="invalid" invalid>
-        <Input.Wrapper>
-          <Input.Field type="tel" defaultValue="+7 900 12" />
-        </Input.Wrapper>
-      </Input.Root>
+      <div>
+        <div>
+          <Input.Root label="default">
+            <Input.Wrapper>
+              <Input.Field placeholder="Например, Москва" />
+            </Input.Wrapper>
+          </Input.Root>
+        </div>
+      </div>
+      <div>
+        <div>
+          <Input.Root label="disabled">
+            <Input.Wrapper>
+              <Input.Field defaultValue="Екатеринбург" disabled />
+            </Input.Wrapper>
+          </Input.Root>
+        </div>
+      </div>
+      <div>
+        <div>
+          <Input.Root label="readOnly">
+            <Input.Wrapper>
+              <Input.Field defaultValue="ID 4821-0093" readOnly />
+              <Input.Icon side="end">
+                <Icon name="status.locked" tone="secondary" />
+              </Input.Icon>
+            </Input.Wrapper>
+          </Input.Root>
+        </div>
+      </div>
+      <div>
+        <div>
+          <Input.Root label="invalid" invalid>
+            <Input.Wrapper>
+              <Input.Field type="tel" defaultValue="+7 900 12" />
+            </Input.Wrapper>
+          </Input.Root>
+        </div>
+      </div>
     </>
   );
 }

package/src/components/input/examples/with-icon.tsx

@@ -4,22 +4,30 @@ import { Icon, Input } from "prime-ui-kit";
 export default function InputWithIconExample() {
   return (
     <>
-      <Input.Root label="Поиск по каталогу">
-        <Input.Wrapper>
-          <Input.Icon side="start">
-            <Icon name="action.search" tone="secondary" />
-          </Input.Icon>
-          <Input.Field type="search" placeholder="Название или артикул" />
-        </Input.Wrapper>
-      </Input.Root>
-      <Input.Root label="Номер договора">
-        <Input.Wrapper>
-          <Input.Field defaultValue="Д-2026/0147" readOnly />
-          <Input.Icon side="end">
-            <Icon name="status.locked" tone="secondary" />
-          </Input.Icon>
-        </Input.Wrapper>
-      </Input.Root>
+      <div>
+        <div>
+          <Input.Root label="Поиск по каталогу">
+            <Input.Wrapper>
+              <Input.Icon side="start">
+                <Icon name="action.search" tone="secondary" />
+              </Input.Icon>
+              <Input.Field type="search" placeholder="Название или артикул" />
+            </Input.Wrapper>
+          </Input.Root>
+        </div>
+      </div>
+      <div>
+        <div>
+          <Input.Root label="Номер договора">
+            <Input.Wrapper>
+              <Input.Field defaultValue="Д-2026/0147" readOnly />
+              <Input.Icon side="end">
+                <Icon name="status.locked" tone="secondary" />
+              </Input.Icon>
+            </Input.Wrapper>
+          </Input.Root>
+        </div>
+      </div>
     </>
   );
 }

package/src/components/kanban/COMPONENT.md

@@ -33,7 +33,7 @@ import {
 Kanban.Root                          board: horizontal strip of columns, its own Dnd.Root if none above
 └─ <ul> (Dnd.Sortable, axis x)       the columns in `columnOrder`
    └─ <li> column (from `columns`)   no well with a header plate (`plain`) or a header line (`line`), or a `fill-muted` well (`well`)
-      ├─ header                      title (h3) · count Badge (the stage color) · renderColumnActions(column) · [grip Dnd.Handle, a lock when `locked`]
+      ├─ header                      title (`columnTitleAs`, h3) · count Badge (the stage color) · renderColumnActions(column) · [grip Dnd.Handle, a lock when `locked`]
       │  ├─ description              muted line under the title (`column.description`)
       │  └─ meta                     the stage's figures (`renderColumnMeta(column)`)
       └─ <ul> (Dnd.Sortable)         own vertical scroll; Skeleton cards while loading; EmptyPage (Dnd `empty`) when empty
@@ -59,23 +59,24 @@ Generic `Kanban.Root<T>`; `ref` → `HTMLDivElement`. The board: a strip of colu
 | `columns` | `readonly KanbanColumn[]` | — (required) | Every column: `{ id, title, description?, color?, limit?, locked? }`, drawn in `columnOrder`. `color` is a `PaletteColor` for the count badge, `limit` a WIP limit, `locked` keeps a system stage in place. |
 | `items` | `readonly T[]` | — (required) | Every card the board can show; `value` decides where each one stands. |
 | `getId` | `(item: T) => string` | — (required) | Stable unique id of a card, the one used in `value`. |
-| `getLabel` | `(item: T) => string` | `the id` | Spoken by the live region. |
+| `getLabel` | `(item: T) => string` | the `id` | Spoken by the live region. |
 | `value` | `KanbanValue` | — | Card ids per column (controlled): `{ [columnId]: id[] }`. Ids missing from `items` are skipped. |
 | `defaultValue` | `KanbanValue` | `{}` | Initial card ids per column (uncontrolled). |
 | `onValueChange` | `(value: KanbanValue, move: KanbanMove) => void \| Promise<void>` | — | A card moved: the new placement, then `{ id, from, to, index }` to save. Return the save's promise: the card waits busy in its new place; a rejection glides it back. |
 | `reorderableColumns` | `boolean` | `false` | A grip (`Dnd.Handle`) at the end of every column header moves the column by pointer, touch hold and Alt + ← / →; the cards travel with it. |
 | `columnOrder` | `readonly string[]` | — | Column ids in their order (controlled). Columns it does not name follow in `columns` order. |
-| `defaultColumnOrder` | `readonly string[]` | `the order of `columns`` | Initial column ids in their order (uncontrolled). |
+| `defaultColumnOrder` | `readonly string[]` | the order of `columns` | Initial column ids in their order (uncontrolled). |
 | `onColumnOrderChange` | `(order: readonly string[], move: KanbanColumnMove) => void \| Promise<void>` | — | A column moved: the new order, then `{ id, index }` to save. Return the save's promise: the column waits busy in its new place; a rejection glides it back. |
 | `renderItem` | `(item: T) => ReactNode` | — (required) | Renders one card; return a `Kanban.Item`. |
 | `getItemHref` | `(item: T) => string` | — | The card is a link: a real `<a>` named by `getLabel` covers it and is its tab stop — a click, ⌘/Ctrl-click, a middle click, a new tab. A press on it still drags the card; a drag never follows it. |
-| `onItemClick` | `(item: T, event: KanbanItemClickEvent) => void` | — | Opens a card in place (a Drawer): a click, Enter or Space; never from a control inside it or after a drag. With `getItemHref` it gets plain clicks: `event.preventDefault()` routes in the app. |
+| `onItemOpen` | `(item: T, event: KanbanItemOpenEvent) => void` | — | Opens a card in place (a Drawer): a click, Enter or Space; never from a control inside it or after a drag. With `getItemHref` it gets plain clicks: `event.preventDefault()` routes in the app. |
+| `columnTitleAs` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of the column titles in the page outline; the look does not change. |
 | `renderColumnActions` | `(column: KanbanColumn) => ReactNode` | — | Trailing actions of a column header (add a card, a menu); kit controls inside take the `s` tier. |
-| `renderColumnMeta` | `(column: KanbanColumn) => ReactNode` | — | The meta line under a column's title and description: the stage's figures («12 сделок · 4,8 млн ₽»). |
-| `canDrop` | `(id: string, columnId: string) => boolean \| string` | — | A workflow rule: refuses card `id` in column `columnId` — `false`, or a string that says why (spoken and shown under the carried card). |
+| `renderColumnMeta` | `(column: KanbanColumn) => ReactNode` | — | The meta line under a column's title and description: the stage's figures («12 сделок · 4,8 млн ₽»). Like `description`, it describes the column's list. |
+| `canDrop` | `(id: string, columnId: string) => boolean \| string` | — | A workflow rule: refuses card `id` in column `columnId` — `false`, or a string that says why (spoken and shown under the carried card). The column turns `danger` before the release. |
 | `variant` | `"plain" \| "line" \| "well"` | `"plain"` | No wells: `plain` — a filled header plate over the cards, `line` — a bare header over a faint line; cards stand on the host. `well`: every column is a filled well holding its cards (bounded queues). |
 | `loading` | `boolean` | `false` | Columns show skeleton cards in the card geometry; the cards cross-fade in when it turns off. |
-| `disabled` | `boolean` | `false` | Read-only board: no drag, no keyboard moves, no column grips; `onItemClick` and `getItemHref` still open cards. |
+| `disabled` | `boolean` | `false` | Read-only board: no drag, no keyboard moves, no column grips; `onItemOpen` and `getItemHref` still open cards. |
 | `labels` | `Partial<KanbanLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue">` | — | `className` (the board height), `aria-label` and the other div attributes. |
 
@@ -85,7 +86,7 @@ Generic `Kanban.Root<T>`; `ref` → `HTMLDivElement`. The board: a strip of colu
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `disabled` | `boolean` | `false` | This card cannot be dragged or moved. |
-| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "id">` | — | `children` (the card parts), `className` and the other attributes; `onClick` / `onKeyDown` run before `onItemClick` opens the card — `preventDefault()` keeps it closed. |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "id">` | — | `children` (the card parts), `className` and the other attributes; `onClick` / `onKeyDown` run before `onItemOpen` opens the card — `preventDefault()` keeps it closed. |
 
 ### Kanban.ItemHeader
 `ref` → `HTMLDivElement`. Optional top row of a card: the key or project at the start, the last child (a priority `Badge`, an assignee) at the end.
@@ -149,26 +150,26 @@ Do not wrap a `plain` board's columns in your own boxes, and do not put a `well`
 | State | Driven by | DOM |
 |---|---|---|
 | idle | — | cards show `cursor: grab`; under a mouse the card lifts to `--prime-shadow-overlay` (`@media (hover: hover)` only) — no wash: a wash is one ladder step, the column's own color |
-| carried | a drag | Dnd: the clone lifts on `--prime-shadow-modal`, a dashed accent gap opens where the card lands, cards glide aside |
+| carried | a drag | Dnd: the clone lifts on Dnd's carry shadow, a dashed accent gap opens where the card lands, cards glide aside |
 | column carried | a drag by the column grip | the same for the whole column: its clone lifts with its cards, a column-sized gap opens in the strip, the columns glide aside |
 | over a column | pointer over another column | the gap opens there; an empty column's slot fades out |
 | refused | `limit` reached, `canDrop` returns `false` or a reason | `data-dnd-reject` on the `<ul>`: `danger-soft` fill; the reason in a chip under the carried card |
 | locked column | `locked` | `data-locked` on the column; the grip is a lock named «Закреплено» |
 | full | count ≥ `limit` | `data-full` on the column, orange count `count / limit` |
-| empty | no cards | a compact `EmptyPage` in a dashed drop slot at the top (`fill-strong` dashed line, no fill): «Нет карточек» and the hint «Перетащите сюда карточку» (not on a `disabled` board); the whole column stays a drop area |
+| empty | no cards | a compact `EmptyPage` in Dnd's dashed drop slot at the top (`fill-strong` dashed line, no fill): «Нет карточек» and the hint «Перетащите сюда карточку»; a `disabled` board shows the text alone; the whole column stays a drop area |
 | loading | `loading` | `aria-busy` and `data-loading` on the root; `Skeleton` cards; `Crossfade` swaps them for the cards |
 | disabled | `disabled` / `Kanban.Item disabled` | `data-disabled` on the root / card; no `aria-roledescription`, no shortcuts, no column grips |
-| saving | `onValueChange` / `onColumnOrderChange` returned a pending promise | the card (column) stays in its new place with `aria-busy` and `data-pending`; a card's content quiets to 0.6 under a centred `Spinner`, a column's heading quiets and a spinner stands in for its grip; it does not move again until the answer |
-| opens | `onItemClick` / `getItemHref` | `data-clickable` (in place) or `data-link` (a link over the card, its focus ring drawn on the card); a card that opens lifts on hover on a read-only board too |
+| saving | `onValueChange` / `onColumnOrderChange` returned a pending promise | the card (column) stays in its new place with `aria-busy` and `data-pending`; a card's content quiets to 0.6 under a centred `Spinner`, a column's heading quiets and its grip is busy (Dnd); it does not move again until the answer |
+| opens | `onItemOpen` / `getItemHref` | `data-clickable` (in place) or `data-link` (a link over the card, its focus ring drawn on the card); a card that opens lifts on hover on a read-only board too |
 | refused save | the promise rejected | the card glides back to its old column and place (every card it pushed aside glides too), a column glides back in the strip; `labels.moveFailed` / `labels.columnMoveFailed` is announced |
 
-Motion: the hover lift (shadow, the card rises above its neighbours) and the empty slot fade (`fast`, `standard`); a card dropped under the mouse lands straight into its hover lift (`data-dnd-hover`); the swap from skeletons is `Crossfade`; drag motion is Dnd's (lift, gap, glide, landing); a saving card or column quiets (`fast`, both ways) and its spinner enters (`enterMotion`); a refused save glides back (`base`), never jumps. Under `prefers-reduced-motion` all of it is off.
+Motion: the hover lift (shadow, the card rises above its neighbours) and the empty slot fade (`fast`, `standard`); a card dropped under the mouse lands straight into its hover lift (`data-dnd-hover`); the swap from skeletons is `Crossfade`; drag motion is Dnd's (lift, gap, glide, landing); a saving card or column quiets (`fast`, both ways) and its spinner fades in by itself; a refused save glides back (`base`, the list's FLIP glide), never jumps. Under `prefers-reduced-motion` all of it is off.
 
 A card's own `onKeyDown` runs before the board's: `preventDefault()` in it keeps the move from happening. A controlled owner applies the new `value` (or `columnOrder`) once the request succeeds — in the promise chain, before the returned promise resolves — never before the answer.
 
 ## Layout & spacing
 - Give the root a height (`className`): columns span it and every column body scrolls on its own; without one the columns take the height of the tallest.
-- The board is a size container. From 40rem of its own width columns keep a fixed 18rem; below it a column takes 85% of the board and snaps (`scroll-snap-type: x mandatory`), so the next column peeks. Snapping is off while a drag auto-scrolls the strip.
+- The board is a size container. From 40rem of its own width columns keep a fixed 18rem; below it a column takes 85% of the board, so the next column peeks. The strip snaps to the start of a column (ScrollContainer `snap="mandatory"`); snapping is off while a drag carries a card.
 - The strip scrolls sideways inside the board, never the page. Cards sit at the top of their column; the drop area runs to the bottom of the column, so a card can be released anywhere in it.
 - `plain` / `line`: column gap `--prime-space-3`, cards inset `--prime-space-1` (room for the focus ring); a card sets `data-depth` one above the board's host and paints `--prime-color-layer-current`, so it keeps its color in flight too. `well`: column gap `--prime-space-3`, cards inset `--prime-space-2` from the column edge, column radius `l`. Card gap `--prime-space-2`, card padding `--prime-space-3`, card radius `m`.
 - The column title is `title-m`; the header is at least a control `m` tall, its text starts where the card text does.
@@ -181,23 +182,28 @@ A card's own `onKeyDown` runs before the board's: `preventDefault()` in it keeps
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves through the cards, column by column. |
-| `Enter` · `Space` | Opens the focused card (`onItemClick`) or follows its link (`getItemHref`). |
+| `Enter` · `Space` | Opens the focused card (`onItemOpen`) or follows its link (`getItemHref`). |
 | `Alt + ↑` · `Alt + ↓` | Moves the card one place inside its column. |
 | `Alt + ←` · `Alt + →` | On a card: moves it to the neighbouring column at the same row (or its end). On a column grip: moves the column one place. Focus follows. The direction follows the writing direction (`dir="rtl"`: ← goes forward). |
 | `Escape` | Cancels a drag in flight. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - Every column is a `<ul>` labelled by its heading (`aria-labelledby`) and described by its description and meta (`aria-describedby`); cards are `<li>` with `aria-roledescription` and `aria-keyshortcuts`. The columns are Dnd lists of one kind: Alt + ← / → across them is Dnd's.
 - The column grip is a button named «Переместить колонку «…»» with `aria-keyshortcuts`; a keyboard column move is announced with its position («Колонка «…»: позиция 2 из 4», `labels.column`). A locked column has a lock named «Закреплено» instead.
 - A live region (`role="status"`) announces grabbed, dropped, «position N of M», a move to another column by its title and a refusal with its reason (`labels`, Dnd's labels).
 - The count is spoken as text («Карточек: 3 из 5»), not only by colour; a full column also reads `count / limit`.
-- With `getItemHref` a real `<a>` named by `getLabel` covers the card and is its tab stop: a click, ⌘/Ctrl-click, a middle click and «open in new tab» work anywhere on the card, Space follows it like Enter, Alt + arrows move the card from it and a press on it drags the card; the release of a drag never follows it. Controls inside the card stand above the link. With `onItemClick` alone the card opens by a click, Enter or Space; a control inside the card never opens it, and a card that opens stays a tab stop on a `disabled` board.
+- With `getItemHref` a real `<a>` named by `getLabel` covers the card and is its tab stop: a click, ⌘/Ctrl-click, a middle click and «open in new tab» work anywhere on the card, Space follows it like Enter, Alt + arrows move the card from it and a press on it drags the card; the release of a drag never follows it. Controls inside the card stand above the link. With `onItemOpen` alone the card opens by a click, Enter or Space; a control inside the card never opens it, and a card that opens stays a tab stop on a `disabled` board.
 - Touch: a drag starts after a hold; a finger that moves first scrolls the board.
+- A board named by `aria-label` or `aria-labelledby` is a `group` with that name; an unnamed one has no role.
 - While loading the root has `aria-busy`; skeletons are hidden from assistive tech.
-- While a move is saved the card or column has `aria-busy` (its spinner is hidden from assistive tech); a refused save is announced (`labels.moveFailed`, `labels.columnMoveFailed`).
+- While a move is saved the card or column has `aria-busy` (its spinner is hidden from assistive tech, a column's busy grip says so itself); a refused save is announced (`labels.moveFailed`, `labels.columnMoveFailed`).
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -224,19 +230,19 @@ A card's own `onKeyDown` runs before the board's: `preventDefault()` in it keeps
 | [limits.tsx](examples/limits.tsx) | A support queue with a work-in-progress limit and a workflow rule, its columns drawn as wells so each reads as a bounded queue: a full column and a blocked ticket are refused before the release with the reason under the card, from the keyboard too — `limit`, `canDrop`, `variant`. |
 | [columns.tsx](examples/columns.tsx) | A sales pipeline whose stages move by the grip in their header while the first and the last stay locked; each stage carries its color on the count, a rule and its figures under the title, and is edited in a popover; the page keeps the order — `reorderableColumns`, `columnOrder`, `onColumnOrderChange`, `locked`, `color`, `description`, `renderColumnMeta`, `renderColumnActions`. |
 | [saving.tsx](examples/saving.tsx) | Every move is saved on the server: the card waits busy in its new place, and an invoice the server refuses to close glides back to its column — `onValueChange`. |
-| [item-link.tsx](examples/item-link.tsx) | Tickets that open: each card is a link to its page, so ⌘-click or a middle click opens a new tab, a plain click, Enter or Space opens it in place, and a drag only moves it — `getItemHref`, `onItemClick`. |
-| [states.tsx](examples/states.tsx) | Loading draws skeleton cards in the card geometry and cross-fades the cards in; an empty column keeps its drop area; a closed order stays in place while the rest move; a read-only board drags nothing — `loading`, `disabled`. |
+| [item-link.tsx](examples/item-link.tsx) | Tickets that open: each card is a link to its page, so ⌘-click or a middle click opens a new tab, a plain click, Enter or Space opens it in place, and a drag only moves it — `getItemHref`, `onItemOpen`. |
+| [states.tsx](examples/states.tsx) | Loading draws skeleton cards in the card geometry; an empty column keeps its drop area and a closed order stays in place while the rest move; a read-only board drags nothing — `loading`, `disabled`. |
 | [controlled.tsx](examples/controlled.tsx) | The placement lives in the parent: every move arrives with its source, target and position to save, and a button resets the board — `value`, `onValueChange`. |
-| [narrow.tsx](examples/narrow.tsx) | On a phone-width screen a column takes 85% of the board and snaps into place, so the next one peeks; the strip scrolls inside the board, never the page. |
-| [screen.tsx](examples/screen.tsx) | A sales pipeline as a work screen: the title with the open deals and their sum, search, filter, the board / list switch and the one primary action in the app header, a full-height Kanban of deals by stage with totals, moves saved on the server that can be refused, and the deal in a Drawer — `value`, `onValueChange`, `renderColumnMeta`, `onItemClick`. |
+| [narrow.tsx](examples/narrow.tsx) | On a phone-width screen a column takes 85% of the board and snaps into place, so the next one peeks; the strip scrolls inside the board, never the page — `Kanban.Root`, `columns`. |
+| [screen.tsx](examples/screen.tsx) | A sales pipeline as a work screen: the title with the open deals and their sum, search, filter, the board / list switch and the one primary action in its top bar, a full-height Kanban of deals by stage with totals, moves saved on the server that can be refused, and the deal in a Drawer — `value`, `onValueChange`, `renderColumnMeta`, `onItemOpen`. |
 
 ## Mistakes
 - Returning something other than `Kanban.Item` from `renderItem` → the card does not drag and Alt + arrows do nothing.
 - Using the array index as the card id → ids must survive a move.
 - Keeping the status only on the item and no `value` → the board draws nothing; build `defaultValue` (or `value`) from your data: `{ [status]: ids }`.
 - No height on the root inside a fixed region → the page scrolls instead of the column.
-- A hover-only action on a card → touch has no hover; put the action in the card or open the card on click (`onItemClick`).
-- `onClick` / `onKeyDown` on `Kanban.Item` to open a card → `onItemClick` (click, Enter, Space, never after a drag) or `getItemHref` for a page of its own.
+- A hover-only action on a card → touch has no hover; put the action in the card or open the card on click (`onItemOpen`).
+- `onClick` / `onKeyDown` on `Kanban.Item` to open a card → `onItemOpen` (click, Enter, Space, never after a drag) or `getItemHref` for a page of its own.
 - `getItemHref` without `getLabel` → the link is named by the card id; pass a human name.
 - Drawing your own box (a Card, a filled `div`) around each column, or around a `well` board → pick the `variant`: `plain` or `line` for one level of nesting, `well` when columns must read as bounded queues.
 - Styling a card from an ancestor (`.board .card`) → the flying clone is portalled to `<body>` and loses it; put the class on `Kanban.Item`.
@@ -248,5 +254,5 @@ A card's own `onKeyDown` runs before the board's: `preventDefault()` in it keeps
 - Drag as the only way to change a status → keep a status field or a menu in the card details too.
 
 ## Related
-- **Built from:** [Dnd](../dnd/COMPONENT.md), [Badge](../badge/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md), [Crossfade](../crossfade/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Spinner](../spinner/COMPONENT.md)
+- **Built from:** [Dnd](../dnd/COMPONENT.md), [Badge](../badge/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md), [Crossfade](../crossfade/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [DataTable](../data-table/COMPONENT.md), [Card](../card/COMPONENT.md), [Avatar](../avatar/COMPONENT.md), [Thumbnail](../thumbnail/COMPONENT.md), [Timeline](../timeline/COMPONENT.md), [Gantt](../gantt/COMPONENT.md)