prime-ui-kit 0.10.0 → 0.11.0

package/src/components/input/COMPONENT.md

@@ -9,6 +9,8 @@
 - Any single-line value: name, e-mail, phone, search query, amount, URL, code.
 - Search fields with a leading icon and a clear button.
 - Values with a fixed prefix/suffix (`https://`, domain, `₽`, `%`).
+- Inline editing in a record card: each field saves itself (`onCommit`) on blur and Enter.
+- A value with actions beside it: copy, write, open a profile (`Input.CopyButton`, `Input.Action`); a password with a show toggle (`Input.RevealButton`).
 - As the reference field: Select, Datepicker, TagSelect and Textarea follow the same label / field / support-row contract.
 
 ## When not to use
@@ -32,10 +34,13 @@ Input.Root            label row, field body, support row; provides size / invali
    ├─ Input.Icon           decorative icon (start | end)
    ├─ Input.InlineAffix    muted text next to the value (start | end)
    ├─ Input.Field          native <input>
-   └─ Input.ClearButton    trailing clear action: a full-height segment at the end edge
+   ├─ Input.ClearButton    clear segment (kit-rendered)
+   ├─ Input.CopyButton     copy segment; the glyph morphs into a check (kit-rendered)
+   ├─ Input.RevealButton   show / hide a password segment, aria-pressed (kit-rendered)
+   └─ Input.Action         the consumer's named icon action with a tooltip (button or asChild link)
 Input.Counter         goes into Input.Root `counter` (support row, right side)
 ```
-The trailing side has a fixed CSS `order`, independent of JSX order: value · end inline affix · end icon · clear button · end affix. All `side="start"` slots share one order before the value, so among them the JSX order decides — write them as affix, icon, inline affix.
+The trailing side has a fixed CSS `order`, independent of JSX order: value · end inline affix · commit status (`onCommit`) · end icon · segments · end affix. The segments (`ClearButton`, `CopyButton`, `RevealButton`, `Action`) keep their JSX order among themselves and sit edge to edge, full field height, flush with the end edge. All `side="start"` slots share one order before the value, so among them the JSX order decides — write them as affix, icon, inline affix.
 
 ## API
 
@@ -57,8 +62,9 @@ The trailing side has a fixed CSS `order`, independent of JSX order: value · en
 | `counter` | `ReactNode` | — | Right side of the support row, usually `<Input.Counter />`. |
 | `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: a stepped `ProgressBar` (4 steps) under the field and the level word at the end of the support row — weak, easy, medium, hard (`labels.strengthWeak` … `strengthHard`), toned danger → warning → accent → success. Follows the value of `Input.Field`, controlled or not. For new-password fields. |
-| `getStrength` | `(value: string) => 0 \| 1 \| 2 \| 3 \| 4` | `getPasswordStrength` | Replaces the kit's estimate: every trait adds a point on its own, in any order — lowercase, uppercase, digits, symbols, 10+ and 14+ characters; 0–2 points weak, 3 easy, 4 medium, 5+ hard, and under 8 characters at most easy. Return 0 for empty, 1 weak … 4 hard. A hint for the person typing, not a security check. |
+| `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`. |
+| `getStrength` | `(value: string) => 0 \| 1 \| 2 \| 3 \| 4` | `getPasswordStrength` | Replaces the kit's estimate of `strength`. Return 0 for empty, 1 weak … 4 hard. A hint for the person typing, not a security check. |
+| `onCommit` | `(value: string) => void \| Promise<void>` | — | Inline save: fires with a changed value on blur and Enter; Escape reverts. Return a Promise: the field shows a spinner and stays editable; a rejection restores the value — show why through `error`. |
 | `labels` | `Partial<InputLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — (required) | Usually `Input.Wrapper`. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>` (field-root rule: `className`, `ref` and the rest → frame, `id` → control). |
@@ -68,11 +74,11 @@ The trailing side has a fixed CSS `order`, independent of JSX order: value · en
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | `Field` and the slots: `Icon`, `Affix`, `InlineAffix`, `ClearButton`. |
+| `children` | `ReactNode` | — (required) | `Field` and the slots: `Icon`, `Affix`, `InlineAffix`; the end segments `ClearButton`, `CopyButton`, `RevealButton`, `Action` in source order. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the `<div>`. |
 
 ### Input.Field
-`ref` → `HTMLInputElement`. The native `<input>`; `id`, `aria-invalid` and `aria-describedby` come from the root.
+`ref` → `HTMLInputElement`. The native `<input>`; `id`, `aria-invalid` and `aria-describedby` come from the root, `disabled` also from a disabled `Fieldset` around it.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -116,6 +122,31 @@ The trailing side has a fixed CSS `order`, independent of JSX order: value · en
 | `onClick` | `MouseEventHandler<HTMLButtonElement>` | — | Clear the value here. Afterwards focus returns to the input unless `event.preventDefault()` was called. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "children" \| "aria-label">` | — | The other button attributes. |
 
+### Input.CopyButton
+`ref` → `HTMLButtonElement`. Copies the field's value as a full-height segment at the end edge: the copy glyph morphs into a check, the name and tooltip switch to `labels.copied` (`labels.copyError` when the clipboard refuses), a polite live region repeats it.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `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
+`ref` → `HTMLButtonElement`. A full-height toggle segment that shows a `type="password"` field as text and back (`aria-pressed`, named by `labels.reveal`); the focus, caret and selection stay in the field.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "children" \| "aria-label" \| "aria-pressed">` | — | The other button attributes. |
+
+### Input.Action
+`ref` → `HTMLButtonElement` (the child with `asChild`). The consumer's icon action at the end edge («Позвонить», «Открыть профиль»): a full-height button segment named by `label`, with a tooltip and the touch hit area.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — (required) | Accessible name and tooltip («Позвонить», «Открыть профиль»). |
+| `asChild` | `boolean` | `false` | Renders the one child (an `<a href>`, a router link) with the segment's look; `disabled` becomes `aria-disabled`. |
+| `children` | `ReactNode` | — (required) | The glyph (`<Icon name>`), or with `asChild` the element that carries it. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" \| "children">` | — | `onClick`, `disabled` and the other button attributes. |
+
 ### Input.Counter
 `ref` → `HTMLSpanElement`. Character counter for the support row; shows `14/40` and announces `labels.counter`.
 
@@ -133,7 +164,7 @@ Input has no `variant` or `tone`: there is one field treatment (fill, no visible
 |---|---|---|---|
 | `xs` | 28 high, text 12/16, padX 8, radius 6, label 12/16, hint 12/16 | Dense table toolbars, inline filters | |
 | `s` | 32 high, text 13/20, padX 8, radius 8, label 12/16, hint 12/16 | Compact panels, side filters | |
-| `m` | 36 high, text 14/20, padX 12, radius 8, label 13/20, hint 12/16 | Regular forms and pages | yes |
+| `m` | 36 high, text 14/20, padX 12, radius 8, label 13/20, hint 12/16 | Regular forms and pages | yes (without `size`: the host's tier, else `m`) |
 | `l` | 40 high, text 16/24, padX 12, radius 10, label 14/20, hint 13/20 | Spacious forms, onboarding | |
 | `xl` | 48 high, text 16/24, padX 16, radius 12, label 14/20, hint 13/20 | Hero search, landing forms | |
 
@@ -167,13 +198,22 @@ Input has no `variant` or `tone`: there is one field treatment (fill, no visible
 | focus | keyboard focus on the input | wrapper gets the focus fill and an inset focus ring (`:has(input:focus-visible)`) |
 | no focus ring | `focusRing={false}` | `data-focus-ring="false"` on the wrapper |
 | invalid | `invalid` or non-empty `error` | `data-invalid="true"` on root and wrapper, `aria-invalid="true"` on the input, danger inset ring, danger focus ring; the control shakes once when an error arrives (`data-shake` on the frame) |
-| disabled | native `disabled` on `Input.Field` | disabled fill, disabled text and icons, `cursor: not-allowed`, clear button disabled look |
+| disabled | native `disabled` on `Input.Field`, or a disabled `Fieldset` around it | disabled fill, disabled text and icons, `cursor: not-allowed`, clear button disabled look |
 | read-only | native `readOnly` on `Input.Field` | no hover, default cursor |
 | reserved support row | `reserveSupportRow` | `data-reserve="true"` on the support row |
 | counter over limit | `current > max` | `data-invalid="true"` on `Input.Counter`; the current count rolls its digits to each new value |
 | strength | `strength` + the value of `Input.Field` | a stepped `ProgressBar` (4 cells, `aria-label` = `labels.strength`) under the field fills one cell after another, weak · easy · medium · hard, toned danger → warning → accent → success; the level word at the end of the support row flows in letter by letter and is announced (`aria-live`); the support row is reserved |
+| saving | `onCommit` returned a pending Promise | `aria-busy="true"` on the input; a `Spinner` at the end of the field (`data-commit="pending"`); the field stays editable and focusable, neighbours are untouched; a live region says `labels.saving` |
+| saved | the Promise resolved (or `onCommit` returned nothing) | the spinner cross-fades into a success check (`data-commit="saved"`) that fades out after a moment; the live region says `labels.saved` |
+| save refused | the Promise rejected | the committed value is put back (unless the person typed on), the status leaves; the owner shows why through `error` |
+| password shown | `Input.RevealButton` pressed | `aria-pressed="true"` on the button, `type="text"` on the input, the eye glyph switches to eye-off; caret and selection kept |
+| copied | `Input.CopyButton` pressed | the copy glyph cross-fades into a check, the button name becomes `labels.copied` (or `labels.copyError`) |
+
+Size: `data-size` on root and wrapper. Slots: `data-side="start" | "end"`. Segments: `data-field-action`.
+
+Inline save (`onCommit`): the value at focus is the committed one. Blur and Enter commit a changed value (an unchanged one never fires); Escape puts the committed value back through the field's own `onChange`, so a controlled owner receives it, and is consumed — it does not also close the drawer around the field. Return a Promise for a server save: pending shows a spinner, reject restores the value, resolve shows the check.
 
-Size: `data-size` on root and wrapper. Slots: `data-side="start" | "end"`.
+Strength estimate (`strength`, replaced by `getStrength`): every trait adds a point on its own, in any order — lowercase, uppercase, digits, symbols, 10+ and 14+ characters; 0–2 points weak, 3 easy, 4 medium, 5+ hard, and under 8 characters at most easy. The meter follows `Input.Field` controlled or not.
 
 Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontrolled: `defaultValue`. Both are native input props.
 
@@ -189,14 +229,19 @@ Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontro
 ### Keyboard
 | Key | Action |
 |---|---|
-| `Tab` | Focuses the field, then the clear button when it is shown. |
-| `Enter` · `Space` | On the clear button: clears the value and returns focus to the field. |
+| `Tab` | Focuses the field, then the segments at its end (clear, copy, reveal, actions). |
+| `Enter` · `Space` | On a segment: runs its action (the clear button returns focus to the field). |
+| `Enter` | With `onCommit`: saves a changed value; focus stays in the field. |
+| `Escape` | With `onCommit`: puts the committed value back. |
 
 ### ARIA
 - `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. "Сумма, ₽").
 - `Input.ClearButton` is a real button named by `labels.clear`, with `aria-controls` on the input.
+- `Input.Action` and `Input.CopyButton` are buttons (or a link with `asChild`) named by their label, with a tooltip; copying announces `labels.copied` through a polite live region.
+- `Input.RevealButton` is a toggle: a constant name `labels.reveal`, `aria-pressed` and `aria-controls` on the input; a pointer press keeps the focus in the field.
+- With `onCommit` the input carries `aria-busy="true"` while saving; a polite live region says `labels.saving`, then `labels.saved`.
 - `Input.Counter` shows `14/40` visually and announces `labels.counter` through `aria-live="polite"`.
 
 ### Labels
@@ -206,6 +251,12 @@ Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontro
 |---|---|---|
 | `optional` | `"необязательно"` | Marker after the label when `optional`. |
 | `clear` | `"Очистить"` | Accessible name of `Input.ClearButton`. |
+| `copy` | `"Копировать"` | Name and tooltip of the copy button. |
+| `copied` | `"Скопировано"` | Name, tooltip and announcement once the value is copied. |
+| `copyError` | `"Не удалось скопировать"` | Name, tooltip and announcement when the clipboard refuses. |
+| `reveal` | `"Показать пароль"` | Accessible name of `Input.RevealButton`;`aria-pressed` says whether the password is shown. |
+| `saving` | `"Сохранение"` | Announced while an `onCommit` save is pending. |
+| `saved` | `"Сохранено"` | Announced once an `onCommit` save succeeds. |
 | `counter` | `"{current} из {max} символов"` | Screen-reader text of `Input.Counter`; `{current}` and `{max}` are replaced. |
 | `strength` | `"Надёжность пароля"` | Accessible name of the `strength` meter and the spoken prefix of the level word. |
 | `strengthWeak` | `"Слабый"` | Level word for strength 1. |
@@ -223,7 +274,9 @@ Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontro
 | [with-icon.tsx](examples/with-icon.tsx) | A decorative icon at either end of the value — `Input.Icon`, `side`. |
 | [affixes.tsx](examples/affixes.tsx) | A fixed prefix and suffix flush with the edges and a unit next to the value — `Input.Affix`, `Input.InlineAffix`. |
 | [without-focus-ring.tsx](examples/without-focus-ring.tsx) | A single search field where the caret and the lighter fill show focus — `focusRing`. |
-| [password-strength.tsx](examples/password-strength.tsx) | A new password with a meter that fills step by step and names the level beside the hint — `strength`. |
+| [password-strength.tsx](examples/password-strength.tsx) | A new password with a show toggle and a meter that fills step by step and names the level beside the hint — `Input.RevealButton`, `strength`. |
+| [edge-actions.tsx](examples/edge-actions.tsx) | Actions at the field's end: a mail link with a tooltip beside copying the value, and a profile link on a read-only field — `Input.Action`, `Input.CopyButton`. |
+| [inline-edit.tsx](examples/inline-edit.tsx) | Record card fields that save on blur and Enter, revert on Escape and show the server's refusal — `onCommit`, `error`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the value: a clear button and a character counter follow it — `value`, `onValueChange`, `Input.ClearButton`, `Input.Counter`. |
 | [in-form.tsx](examples/in-form.tsx) | Company details form: required fields checked on submit, each error leaves as its field is fixed and a saved form turns the button green; neighbours keep their bottoms aligned — `required`, `error`, `reserveSupportRow`. |
 
@@ -235,7 +288,10 @@ Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontro
 - Rendering `Input.ClearButton` for an empty field → render it only when there is a value.
 - Setting `className` with a custom border or background on `Input.Wrapper` → the fill comes from the surface context; fields inside Card/Modal already switch.
 - `tone="danger"` / `error` as a boolean → use `invalid` or an `error` message.
+- A `Button` placed next to the field for «copy» or «call» → `Input.CopyButton` / `Input.Action` inside `Input.Wrapper`.
+- Hand-written blur / Enter / Escape handlers and a `disabled` field while saving → `onCommit` returning the save Promise; the field stays editable.
+- 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`), `Icon` (`Input.ClearButton`)
+- **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)
 - **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/edge-actions.tsx

@@ -0,0 +1,30 @@
+/** Actions at the field's end: a mail link with a tooltip beside copying the value, and a profile link on a read-only field — `Input.Action`, `Input.CopyButton`. */
+import { Icon, Input } from "prime-ui-kit";
+
+export default function InputEdgeActionsExample() {
+  return (
+    <>
+      <Input.Root label="Почта контакта">
+        <Input.Wrapper>
+          <Input.Field type="email" defaultValue="i.sokolova@severny-veter.ru" />
+          <Input.Action label="Написать письмо" asChild>
+            <a href="mailto:i.sokolova@severny-veter.ru">
+              <Icon name="field.email" />
+            </a>
+          </Input.Action>
+          <Input.CopyButton />
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root label="Ответственный">
+        <Input.Wrapper>
+          <Input.Field readOnly defaultValue="Анна Ковалёва" />
+          <Input.Action label="Открыть профиль" asChild>
+            <a href="#team-kovaleva">
+              <Icon name="object.user" />
+            </a>
+          </Input.Action>
+        </Input.Wrapper>
+      </Input.Root>
+    </>
+  );
+}

package/src/components/input/examples/inline-edit.tsx

@@ -0,0 +1,52 @@
+/** Record card fields that save on blur and Enter, revert on Escape and show the server's refusal — `onCommit`, `error`. */
+import { Input } from "prime-ui-kit";
+import * as React from "react";
+
+const SAVE_DELAY_MS = 900;
+
+/** Stands in for the API call: an empty value is refused like a server validation error. */
+function saveField(value: string) {
+  return new Promise<void>((resolve, reject) => {
+    window.setTimeout(() => {
+      if (value.trim() === "") reject(new Error("Поле не может быть пустым"));
+      else resolve();
+    }, SAVE_DELAY_MS);
+  });
+}
+
+export default function InputInlineEditExample() {
+  const [company, setCompany] = React.useState("ООО «Северный ветер»");
+  const [manager, setManager] = React.useState("Анна Ковалёва");
+  const [companyError, setCompanyError] = React.useState<string>();
+  const [managerError, setManagerError] = React.useState<string>();
+
+  const commitWith = (setError: (error: string | undefined) => void) => async (value: string) => {
+    setError(undefined);
+    try {
+      await saveField(value);
+    } catch (reason) {
+      setError(reason instanceof Error ? reason.message : "Не удалось сохранить");
+      throw reason;
+    }
+  };
+
+  return (
+    <>
+      <Input.Root
+        label="Компания"
+        hint="Сохраняется при выходе из поля и по Enter, Escape отменяет правку"
+        error={companyError}
+        onCommit={commitWith(setCompanyError)}
+      >
+        <Input.Wrapper>
+          <Input.Field value={company} onValueChange={setCompany} />
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root label="Ответственный" error={managerError} onCommit={commitWith(setManagerError)}>
+        <Input.Wrapper>
+          <Input.Field value={manager} onValueChange={setManager} />
+        </Input.Wrapper>
+      </Input.Root>
+    </>
+  );
+}

package/src/components/input/examples/password-strength.tsx

@@ -1,4 +1,4 @@
-/** A new password with a meter that fills step by step and names the level beside the hint — `strength`. */
+/** A new password with a show toggle and a meter that fills step by step and names the level beside the hint — `Input.RevealButton`, `strength`. */
 import { Input } from "prime-ui-kit";
 
 export default function InputPasswordStrengthExample() {
@@ -6,6 +6,7 @@ export default function InputPasswordStrengthExample() {
     <Input.Root label="Новый пароль" hint="Не короче 8 символов" strength>
       <Input.Wrapper>
         <Input.Field type="password" autoComplete="new-password" defaultValue="Graphite2026" />
+        <Input.RevealButton />
       </Input.Wrapper>
     </Input.Root>
   );

package/src/components/kanban/COMPONENT.md

@@ -15,58 +15,82 @@
 - One list to reorder, or items carried onto folders or assignees → use [Dnd](../dnd/COMPONENT.md) directly.
 - A linear process the user walks through once → use [Stepper](../stepper/COMPONENT.md).
 - A history of events → use [Timeline](../timeline/COMPONENT.md).
+- Work planned on dates, where duration and overlap matter → use [Gantt](../gantt/COMPONENT.md).
 
 ## Import
 ```tsx
-import { Kanban, type KanbanColumn, type KanbanMove, type KanbanValue } from "prime-ui-kit";
+import {
+  Kanban,
+  type KanbanColumn,
+  type KanbanColumnMove,
+  type KanbanMove,
+  type KanbanValue,
+} from "prime-ui-kit";
 ```
 
 ## Anatomy
 ```
-Kanban.Root                       board: horizontal strip of columns, its own Dnd.Root if none above
-└─ column (from `columns`)        `fill-muted` well (one ladder step off the board's surface); header + own vertical scroll
-   ├─ header                      title (h3) · count Badge · renderColumnActions(column)
-   └─ <ul> (Dnd.Sortable)         drop area; Skeleton cards while loading; EmptyPage when empty
-      └─ Kanban.Item              <li> card from renderItem(item)
-         ├─ Kanban.ItemTitle      title, up to three lines
-         ├─ Kanban.ItemDescription  muted meta line: id, due date
-         ├─ Kanban.ItemBadges     wrapping row of Badge
-         └─ Kanban.ItemFooter     row: Kanban.ItemCount … at the start, the assignee at the end
-            └─ Kanban.ItemCount   icon + number
+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`)   `fill-muted` well (one ladder step off the board's surface)
+      ├─ header                      title (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
+         └─ Kanban.Item              <li> card from renderItem(item)
+            ├─ Kanban.ItemHeader     optional top row over a faint hairline: key · priority (or a full-width Thumbnail cover)
+            ├─ Kanban.ItemTitle      title, up to three lines
+            ├─ Kanban.ItemDescription  muted meta line: id, due date
+            ├─ Kanban.ItemBadges     wrapping row of Badge
+            └─ Kanban.ItemFooter     row: Kanban.ItemCount … at the start, the assignee at the end
+               └─ Kanban.ItemCount   icon + number
 ```
-Columns and cards are application data (`columns`, `items`); the board state is where each card stands: `value` maps a column id to its card ids in order. A card in flight is drawn by Dnd as a lifted clone; the column under it opens a gap where it lands.
+Columns and cards are application data (`columns`, `items`); the board state is where each card stands: `value` maps a column id to its card ids in order, and `columnOrder` is the order of the columns. A card in flight is drawn by Dnd as a lifted clone; the column under it opens a gap where it lands.
 
 ## API
 
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Kanban.Root
-Generic `Kanban.Root<T>`; `ref` → `HTMLDivElement`. The board: a strip of columns that scrolls sideways inside itself, each column a labelled `<ul>` of cards under a header with the title, a count `Badge` and actions. Mounts its own `Dnd.Root` unless one is already above it. Sets `aria-busy` while loading, `data-loading`, `data-disabled`.
+Generic `Kanban.Root<T>`; `ref` → `HTMLDivElement`. The board: a strip of columns that scrolls sideways inside itself, each a labelled list of cards under a header. Mounts its own `Dnd.Root` unless one is above it. Give it a height.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `columns` | `readonly KanbanColumn[]` | — (required) | Columns in their order: `{ id, title, limit? }`; `limit` is a WIP limit — a full column refuses cards from other columns and its count turns orange (`count / limit`). |
+| `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. |
 | `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` | — | A card moved by pointer, touch or keyboard: the new placement, then `{ id, from, to, index }` to save. |
+| `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). |
+| `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`. |
 | `renderColumnActions` | `(column: KanbanColumn) => ReactNode` | — | Trailing actions of a column header (add a card, a menu); kit controls inside take the `s` tier. |
-| `canDrop` | `(id: string, columnId: string) => boolean` | — | A workflow rule: refuses card `id` in column `columnId`; the column turns `danger` before the release and a keyboard move is announced as refused. |
+| `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). |
+| `variant` | `"well" \| "plain"` | `"well"` | `well`: every column is a filled well with its cards inside. `plain`: no wells — a filled header plate and wider cards carry the column. |
 | `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; clicks on cards still work. |
+| `disabled` | `boolean` | `false` | Read-only board: no drag, no keyboard moves, no column grips; clicks on cards still work. |
 | `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. |
 
 ### Kanban.Item
-`ref` → `HTMLLIElement`. One card: an `<li>` two ladder steps lighter than its column (`control-selected`: white in light) with the raised shadow, lifted to the overlay shadow on hover; return it from `renderItem` (it takes its id from there). Draggable by the whole card, focusable, `aria-keyshortcuts` for Alt + arrows. Presses on buttons, fields and links inside never start a drag.
+`ref` → `HTMLLIElement`. One card; return it from `renderItem` (it takes its id from there). Dragged by the whole card and focusable; presses on buttons, fields and links inside never start a drag.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `disabled` | `boolean` | `false` | This card cannot be dragged or moved. |
-| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "id">` | — | `children` (the card parts), `className`, `onClick` and the other attributes; `onKeyDown` runs first, `preventDefault()` keeps the move from happening. |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "id">` | — | `children` (the card parts), `className`, `onClick` and the other attributes. |
+
+### 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.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### Kanban.ItemTitle · Kanban.ItemDescription
 `ref` → `HTMLSpanElement`. The card title (medium body text, up to three lines) and the muted meta line under it (id, due date; one line, tabular numbers).
@@ -98,13 +122,21 @@ Generic `Kanban.Root<T>`; `ref` → `HTMLDivElement`. The board: a strip of colu
 
 ## Variants
 
-The board has no visual variants: one look, fills over lines.
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `well` | every column is a filled well (`fill-muted`, radius `l`), cards inside it | the default board; columns must read as areas | yes |
+| `plain` | no wells: the column is its header — a filled plate (`fill-muted`, radius `l`) as wide as the cards — and its cards, which widen to almost the full column, so neighbouring columns stand closer | a lighter board on a page that already has its own surface | |
 
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `limit` (column) | count reads `count / limit`, orange when full; a full column refuses cards from others | a WIP limit per status | — |
-| `canDrop` | the column turns `danger` under a refused card; a keyboard move is announced as refused | workflow rules (a blocked ticket cannot be closed) | — |
+| `limit` (column) | count reads `count / limit`, orange when full; a full column refuses cards from others with the reason `labels.full` | a WIP limit per status | — |
+| `description` (column) | a muted caption line under the column title, one line with an ellipsis | the column's rule or meaning («Ответить в течение дня») | — |
+| `renderColumnMeta` | a caption line in tabular digits under the description | the stage's figures («2 сделки · 576 000 ₽») | — |
+| `color` (column) | the count Badge in the stage's hue (soft) | telling stages apart, matching their color elsewhere; the title still names the column | — |
+| `locked` (column) | a lock where the grip would be; the column holds its place, no column moves past it | system stages: the first «Новые», the last «Закрыто» | — |
+| `reorderableColumns` | a ghost grip at the end of every column header, after the actions; the column is carried by it | the user arranges the stages | `false` |
+| `canDrop` | the column turns `danger` under a refused card; a string reason is spoken and shown under the carried card; a keyboard move is announced as refused | workflow rules (a blocked ticket cannot be closed) | — |
 | `loading` | skeleton cards in the card geometry, no counts | the first load or a refresh | `false` |
 | `disabled` | cards do not drag, Alt + arrows do nothing | read-only boards, no permission | `false` |
 
@@ -113,20 +145,31 @@ The board has no visual variants: one look, fills over lines.
 |---|---|---|
 | 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 |
-| over a column | pointer over another column | the gap opens there; an empty column's well fades out |
-| refused | `limit` reached, `canDrop` returns `false` | `data-dnd-reject` on the `<ul>`: `danger-soft` fill |
+| 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 an 80 px well at the top; the whole column stays a drop area |
+| 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 |
 | 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 |
+| 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 |
+| 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 well 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). 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 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.
-- Column gap `--prime-space-3`, card gap `--prime-space-2`, card padding `--prime-space-3`, column radius `l`, card radius `m`.
+- `well`: column gap `--prime-space-3`, cards inset `--prime-space-2` from the column edge, column radius `l`. `plain`: column gap `--prime-space-3`, cards inset `--prime-space-1` (room for the focus ring). 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.
+- A faint inset hairline (`--prime-color-border-faint`, as in a dialog header) separates the header from the cards.
+- The header is a grid: the title, the count, the actions and the grip at the end on the first row; the description under the title on the second, the meta line under it (`--prime-space-1` above, caption, `text-secondary`).
+- A card is `--prime-color-control-selected` (two ladder steps off its column; white in light) on `--prime-shadow-raised`.
+- `Kanban.ItemHeader` is a muted caption row over a faint hairline (`--prime-color-border-faint`); a card without it starts with its title or a full-width `Thumbnail` cover.
 - Header actions get the `s` tier; inside a card, kit controls take the `m` host tier (a `Badge` is `s`). Pick a small `Avatar` (`size="s"`).
 
 ## Accessibility
@@ -136,15 +179,17 @@ Motion: the hover lift (shadow, the card rises above its neighbours) and the emp
 |---|---|
 | `Tab` | Moves through the cards, column by column. |
 | `Alt + ↑` · `Alt + ↓` | Moves the card one place inside its column. |
-| `Alt + ←` · `Alt + →` | Moves the card to the neighbouring column at the same row (or its end); focus follows it. The direction follows the writing direction (`dir="rtl"`: ← is the next 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
-- Every column is a `<ul>` labelled by its heading (`aria-labelledby`); cards are `<li>` with `aria-roledescription` and `aria-keyshortcuts`.
-- A live region (`role="status"`) announces grabbed, dropped, «position N of M», a move to another column and a refusal (`labels`).
+- 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`.
 - Touch: a drag starts after a hold; a finger that moves first scrolls the board.
 - 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`).
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -154,15 +199,23 @@ Motion: the hover lift (shadow, the card rises above its neighbours) and the emp
 | `count` | `"Карточек: {count}"` | Spoken name of the count badge. |
 | `countLimit` | `"Карточек: {count} из {limit}"` | Spoken name of the count badge of a column with a `limit`. |
 | `empty` | `"Нет карточек"` | Text of an empty column. |
-| `moved` | `"{label}: «{column}», позиция {position} из {total}"` | Live region: a card moved to another column with the keyboard. |
-| `refused` | `"{label}: колонка «{column}» не принимает карточку"` | Live region: the next column refused the card (full or `canDrop`). |
+| `emptyHint` | `"Перетащите сюда карточку"` | Hint under the empty-column text, while cards can be dropped (not on a `disabled` board). |
+| `full` | `"Колонка «{column}» заполнена ({limit})"` | Why a full column refuses a card: spoken, and shown under the carried card. |
+| `moveColumn` | `"Переместить колонку «{column}»"` | Name of the column grip (`reorderableColumns`). |
+| `column` | `"Колонка «{column}»"` | A column as the live region names it when it is carried or moved («Колонка «Демо»: позиция 2 из 4»). |
+| `moveFailed` | `"Не удалось переместить «{label}», карточка вернулась на место"` | Spoken when the `onValueChange` promise rejects; `{label}` is `getLabel(item)`. |
+| `columnMoveFailed` | `"Не удалось переместить колонку «{column}», она вернулась на место"` | Spoken when the `onColumnOrderChange` promise rejects. |
 
 ## Examples
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A release board: cards move within and between columns by drag, a touch hold or Alt + arrows; a card shows its meta line, labels, comments and assignee — `Kanban.Root`, `Kanban.Item`, `renderItem`, `renderColumnActions`. |
+| [variants.tsx](examples/variants.tsx) | The same release board in both looks: columns as filled wells, and bare columns where the header and wider cards carry each column — `variant`. |
 | [structure.tsx](examples/structure.tsx) | Cards take only the parts they need: a title alone, a meta line, labels, a footer with counts and an assignee — `Kanban.ItemTitle`, `Kanban.ItemDescription`, `Kanban.ItemBadges`, `Kanban.ItemFooter`, `Kanban.ItemCount`. |
-| [limits.tsx](examples/limits.tsx) | A support queue with a work-in-progress limit and a workflow rule: a full column and a blocked ticket are refused before the release, from the keyboard too — `limit`, `canDrop`. |
+| [cards.tsx](examples/cards.tsx) | Three kinds of cards on one board: a plain note, a ticket with a header row of key and priority, a design task with a cover — `Kanban.ItemHeader`, `Thumbnail`, `Kanban.ItemFooter`. |
+| [limits.tsx](examples/limits.tsx) | A support queue with a work-in-progress limit and a workflow rule: a full column and a blocked ticket are refused before the release with the reason under the card, from the keyboard too — `limit`, `canDrop`. |
+| [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 — `reorderableColumns`, `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`. |
 | [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 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. |
@@ -174,8 +227,13 @@ Motion: the hover lift (shadow, the card rises above its neighbours) and the emp
 - 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.
 - Styling a card from an ancestor (`.board .card`) → the flying clone is portalled to `<body>` and loses it; put the class on `Kanban.Item`.
+- Keeping the column order in `columns` and reordering that array → pass `columnOrder` / `onColumnOrderChange`; `columns` stays the data.
+- Putting a system stage back first after every move → `locked: true` on that column.
+- Stats squeezed into the column `title` → `renderColumnMeta`.
+- `canDrop` returning `false` for a rule a person cannot guess → return the reason as a string.
+- Applying a move in `onValueChange` and then undoing it yourself when the request fails → return the request's promise and apply `value` only after it succeeds; the board keeps the card in place meanwhile and glides it back on a rejection.
 - 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)
-- **See also:** [DataTable](../data-table/COMPONENT.md), [Card](../card/COMPONENT.md), [Avatar](../avatar/COMPONENT.md), [Timeline](../timeline/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)
+- **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)