prime-ui-kit 0.9.3 → 0.11.0

package/src/components/input/examples/in-form.tsx

@@ -1,4 +1,4 @@
-/** Company details form: required fields checked on submit, neighbours keep their bottoms aligned — `required`, `error`, `reserveSupportRow`. */
+/** 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`. */
 import { Button, Input, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -15,10 +15,19 @@ function validate(form: FormData): Errors {
 
 export default function InputInFormExample() {
   const [errors, setErrors] = React.useState<Errors>({});
+  const [saved, setSaved] = React.useState(false);
 
   const submit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
-    setErrors(validate(new FormData(event.currentTarget)));
+    const next = validate(new FormData(event.currentTarget));
+    setErrors(next);
+    setSaved(Object.keys(next).length === 0);
+  };
+
+  /** Editing a field takes its error away and makes the form unsaved again. */
+  const edit = (field?: keyof Errors) => {
+    setSaved(false);
+    if (field) setErrors((current) => ({ ...current, [field]: undefined }));
   };
 
   return (
@@ -37,6 +46,7 @@ export default function InputInFormExample() {
             <Input.Wrapper>
               <Input.Field
                 name="name"
+                onValueChange={() => edit("name")}
                 defaultValue="ООО «Северный ветер»"
                 autoComplete="organization"
               />
@@ -45,27 +55,52 @@ export default function InputInFormExample() {
         </div>
         <Input.Root label="ИНН" required error={errors.inn} reserveSupportRow>
           <Input.Wrapper>
-            <Input.Field name="inn" defaultValue="78123" inputMode="numeric" />
+            <Input.Field
+              name="inn"
+              defaultValue="78123"
+              inputMode="numeric"
+              onValueChange={() => edit("inn")}
+            />
           </Input.Wrapper>
         </Input.Root>
         <Input.Root label="КПП" optional reserveSupportRow>
           <Input.Wrapper>
-            <Input.Field name="kpp" placeholder="9 цифр" inputMode="numeric" />
+            <Input.Field
+              name="kpp"
+              placeholder="9 цифр"
+              inputMode="numeric"
+              onValueChange={() => edit()}
+            />
           </Input.Wrapper>
         </Input.Root>
         <div className={styles.formWide}>
           <Input.Root label="Почта для счетов" hint="Сюда придут счета и акты">
             <Input.Wrapper>
-              <Input.Field name="email" type="email" placeholder="buh@company.ru" />
+              <Input.Field
+                name="email"
+                type="email"
+                placeholder="buh@company.ru"
+                onValueChange={() => edit()}
+              />
             </Input.Wrapper>
           </Input.Root>
         </div>
       </div>
       <div className={styles.formActions}>
-        <Button.Root variant="ghost" tone="neutral" type="reset" onClick={() => setErrors({})}>
+        <Button.Root
+          variant="ghost"
+          tone="neutral"
+          type="reset"
+          onClick={() => {
+            setErrors({});
+            setSaved(false);
+          }}
+        >
           Отменить
         </Button.Root>
-        <Button.Root type="submit">Сохранить</Button.Root>
+        <Button.Root type="submit" tone={saved ? "success" : "accent"}>
+          {saved ? "Сохранено" : "Сохранить"}
+        </Button.Root>
       </div>
     </form>
   );

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/input/examples/validation.tsx

@@ -1,9 +1,28 @@
-/** Required and optional markers, a hint, an error and a support row that does not shift — `required`, `optional`, `hint`, `error`, `reserveSupportRow`. */
+/** Live validation: an error shakes the field as it arrives, drops in and leaves as soon as the value is fixed; required and optional markers, a hint and a support row that does not shift — `required`, `optional`, `hint`, `error`, `reserveSupportRow`. */
 import { Button, Input } from "prime-ui-kit";
 import * as React from "react";
 
+const PROMO_CODES = ["SPRING25", "TEAM10"];
+
+/** The INN error, or nothing when the value is a valid INN. */
+function innError(value: string) {
+  if (value === "") return "Введите ИНН";
+  if (/\D/.test(value)) return "Только цифры, без пробелов и букв";
+  if (value.length !== 10 && value.length !== 12) return "ИНН состоит из 10 или 12 цифр";
+  return undefined;
+}
+
 export default function InputValidationExample() {
-  const [checked, setChecked] = React.useState(false);
+  const [inn, setInn] = React.useState("77010");
+  const [promo, setPromo] = React.useState("SPRING");
+  const [promoError, setPromoError] = React.useState<string>();
+
+  const applyPromo = () =>
+    setPromoError(
+      PROMO_CODES.includes(promo.trim().toUpperCase())
+        ? undefined
+        : "Промокод недействителен или истёк",
+    );
 
   return (
     <>
@@ -12,23 +31,29 @@ export default function InputValidationExample() {
           <Input.Field defaultValue="ООО «Северный ветер»" autoComplete="organization" />
         </Input.Wrapper>
       </Input.Root>
-      <Input.Root label="ИНН" required error="ИНН состоит из 10 или 12 цифр">
+      <Input.Root
+        label="ИНН"
+        required
+        hint="10 цифр для организации, 12 — для ИП"
+        error={innError(inn)}
+      >
         <Input.Wrapper>
-          <Input.Field defaultValue="77010" inputMode="numeric" />
+          <Input.Field value={inn} onValueChange={setInn} inputMode="numeric" />
         </Input.Wrapper>
       </Input.Root>
-      <Input.Root
-        label="Промокод"
-        optional
-        reserveSupportRow
-        error={checked ? "Промокод недействителен или истёк" : undefined}
-      >
+      <Input.Root label="Промокод" optional reserveSupportRow error={promoError}>
         <Input.Wrapper>
-          <Input.Field defaultValue="SPRING25" />
+          <Input.Field
+            value={promo}
+            onValueChange={(value) => {
+              setPromo(value);
+              setPromoError(undefined);
+            }}
+          />
         </Input.Wrapper>
       </Input.Root>
-      <Button.Root variant="soft" tone="neutral" onClick={() => setChecked((value) => !value)}>
-        {checked ? "Сбросить проверку" : "Проверить промокод"}
+      <Button.Root variant="soft" tone="neutral" onClick={applyPromo}>
+        Применить промокод
       </Button.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)

package/src/components/kanban/examples/cards.tsx

@@ -0,0 +1,152 @@
+/** 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`. */
+import { Avatar, Badge, Icon, Kanban, type PaletteColor, Thumbnail } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+type Person = { initials: string; name: string; color: PaletteColor };
+
+type Card =
+  | { kind: "note"; id: string; title: string; meta: string }
+  | {
+      kind: "ticket";
+      id: string;
+      title: string;
+      priority: { text: string; color: PaletteColor };
+      comments: number;
+      assignee: Person;
+    }
+  | {
+      kind: "design";
+      id: string;
+      title: string;
+      cover: string;
+      label: { text: string; color: PaletteColor };
+      attachments: number;
+      assignee: Person;
+    };
+
+const COLUMNS = [
+  { id: "todo", title: "К выполнению" },
+  { id: "progress", title: "В работе" },
+  { id: "review", title: "На проверке" },
+];
+
+const OLGA: Person = { initials: "ОБ", name: "Ольга Белова", color: "green" };
+const DENIS: Person = { initials: "ДК", name: "Денис Ким", color: "blue" };
+
+const CARDS: Card[] = [
+  {
+    kind: "design",
+    id: "DS-58",
+    title: "Новый экран оплаты счёта",
+    cover: "https://picsum.photos/seed/invoice-pay/480/270",
+    label: { text: "Дизайн", color: "pink" },
+    attachments: 6,
+    assignee: OLGA,
+  },
+  {
+    kind: "ticket",
+    id: "BUG-412",
+    title: "Счёт не уходит клиенту при пустом email",
+    priority: { text: "Высокий", color: "red" },
+    comments: 7,
+    assignee: DENIS,
+  },
+  { kind: "note", id: "N-12", title: "Собрать отзывы о новом тарифе", meta: "до 18 окт" },
+  {
+    kind: "ticket",
+    id: "PRJ-233",
+    title: "Импорт заказов из 1С",
+    priority: { text: "Средний", color: "yellow" },
+    comments: 2,
+    assignee: OLGA,
+  },
+  {
+    kind: "design",
+    id: "DS-61",
+    title: "Иконки статусов доставки",
+    cover: "https://picsum.photos/seed/delivery-icons/480/270",
+    label: { text: "Иконки", color: "purple" },
+    attachments: 12,
+    assignee: DENIS,
+  },
+  {
+    kind: "note",
+    id: "N-15",
+    title: "Согласовать договор с ООО «Вектор»",
+    meta: "юристы · 21 окт",
+  },
+];
+
+const PLACEMENT = {
+  todo: ["N-12", "PRJ-233"],
+  progress: ["DS-58", "BUG-412"],
+  review: ["DS-61", "N-15"],
+};
+
+export default function KanbanCardsExample() {
+  return (
+    <Kanban.Root
+      aria-label="Задачи продуктовой команды"
+      className={styles.board}
+      columns={COLUMNS}
+      items={CARDS}
+      getId={(card) => card.id}
+      getLabel={(card) => card.title}
+      defaultValue={PLACEMENT}
+      renderItem={(card) => {
+        if (card.kind === "note") {
+          return (
+            <Kanban.Item>
+              <Kanban.ItemTitle>{card.title}</Kanban.ItemTitle>
+              <Kanban.ItemDescription>{card.meta}</Kanban.ItemDescription>
+            </Kanban.Item>
+          );
+        }
+        if (card.kind === "ticket") {
+          return (
+            <Kanban.Item>
+              <Kanban.ItemHeader>
+                <span>{card.id}</span>
+                <Badge.Root color={card.priority.color}>{card.priority.text}</Badge.Root>
+              </Kanban.ItemHeader>
+              <Kanban.ItemTitle>{card.title}</Kanban.ItemTitle>
+              <Kanban.ItemFooter>
+                <Kanban.ItemCount>
+                  <Icon name="object.message" />
+                  {card.comments}
+                </Kanban.ItemCount>
+                <Avatar.Root size="s" color={card.assignee.color} aria-label={card.assignee.name}>
+                  <Avatar.Fallback>{card.assignee.initials}</Avatar.Fallback>
+                </Avatar.Root>
+              </Kanban.ItemFooter>
+            </Kanban.Item>
+          );
+        }
+        return (
+          <Kanban.Item>
+            <Thumbnail.Root fullWidth ratio="16:9">
+              <Thumbnail.Image src={card.cover} alt="" />
+              <Thumbnail.Fallback>
+                <Icon name="object.image" />
+              </Thumbnail.Fallback>
+            </Thumbnail.Root>
+            <Kanban.ItemTitle>{card.title}</Kanban.ItemTitle>
+            <Kanban.ItemBadges>
+              <Badge.Root color={card.label.color}>{card.label.text}</Badge.Root>
+            </Kanban.ItemBadges>
+            <Kanban.ItemFooter>
+              <Kanban.ItemCount>
+                <Icon name="object.document" />
+                {card.attachments}
+              </Kanban.ItemCount>
+              <Avatar.Root size="s" color={card.assignee.color} aria-label={card.assignee.name}>
+                <Avatar.Fallback>{card.assignee.initials}</Avatar.Fallback>
+              </Avatar.Root>
+            </Kanban.ItemFooter>
+          </Kanban.Item>
+        );
+      }}
+    />
+  );
+}