prime-ui-kit 0.9.1 → 0.9.3

package/src/components/kanban/COMPONENT.md

@@ -0,0 +1,181 @@
+# Kanban
+
+**Category:** data-display
+**Kind:** composite
+
+> A board of status columns: cards reorder within a column and move between columns by pointer, touch hold and keyboard, with announcements, WIP limits, loading and empty states and a layout that scrolls inside itself at any width.
+
+## When to use
+- Work items that flow through statuses and are moved by hand: tasks, tickets, orders, invoices, deals.
+- A team needs to see the load of every status at once (counts, WIP limits).
+- The status change is the main action on the screen, and its order inside a status matters.
+
+## When not to use
+- Records with many attributes to compare, sort or filter → use [DataTable](../data-table/COMPONENT.md).
+- 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).
+
+## Import
+```tsx
+import { Kanban, type KanbanColumn, 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
+```
+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.
+
+## 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`.
+
+| 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`). |
+| `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. |
+| `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. |
+| `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. |
+| `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.
+
+| 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. |
+
+### 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).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+
+### Kanban.ItemBadges
+`ref` → `HTMLDivElement`. A wrapping row of `Badge`s: labels, priority.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### Kanban.ItemFooter
+`ref` → `HTMLDivElement`. The bottom row: `Kanban.ItemCount`s at the start; the last child, unless a count, sits at the end (the assignee `Avatar`).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### Kanban.ItemCount
+`ref` → `HTMLSpanElement`. A small muted counter with a 14 px icon: comments, attachments, subtasks.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+
+## Variants
+
+The board has no visual variants: one look, fills over lines.
+
+### 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) | — |
+| `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` |
+
+## States
+| 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 |
+| 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 |
+| 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 |
+| 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 |
+
+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.
+
+## 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`.
+- 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
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `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). |
+| `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`).
+- 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.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `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`). |
+
+## 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`. |
+| [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`. |
+| [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. |
+
+## 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.
+- Styling a card from an ancestor (`.board .card`) → the flying clone is portalled to `<body>` and loses it; put the class on `Kanban.Item`.
+- 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)

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

@@ -0,0 +1,78 @@
+/** 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`. */
+import { Button, Kanban, type KanbanMove, type KanbanValue, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Invoice = { id: string; client: string; amount: string };
+
+const COLUMNS = [
+  { id: "draft", title: "Черновики" },
+  { id: "sent", title: "Отправлены" },
+  { id: "paid", title: "Оплачены" },
+];
+
+const INVOICES: Invoice[] = [
+  { id: "INV-2041", client: "ООО «Север»", amount: "48 300 ₽" },
+  { id: "INV-2042", client: "АО «Гранит»", amount: "212 000 ₽" },
+  { id: "INV-2038", client: "ИП Лебедев", amount: "7 950 ₽" },
+  { id: "INV-2035", client: "ООО «Вектор»", amount: "95 400 ₽" },
+];
+
+const INITIAL: KanbanValue = {
+  draft: ["INV-2041", "INV-2042"],
+  sent: ["INV-2038"],
+  paid: ["INV-2035"],
+};
+
+const TITLES = new Map(COLUMNS.map((column) => [column.id, column.title]));
+
+export default function KanbanControlledExample() {
+  const [placement, setPlacement] = React.useState(INITIAL);
+  const [lastMove, setLastMove] = React.useState<KanbanMove | null>(null);
+
+  return (
+    <div className={styles.stage}>
+      <div className={styles.toolbar}>
+        <Typography as="span" variant="body-s" tone="muted" aria-live="polite">
+          {lastMove
+            ? `${lastMove.id}: ${TITLES.get(lastMove.from)} → ${TITLES.get(lastMove.to)}, позиция ${lastMove.index + 1}`
+            : "Перенесите счёт — изменение уйдёт на сервер"}
+        </Typography>
+        <div className={styles.spacer} />
+        <Button.Root
+          variant="ghost"
+          tone="neutral"
+          disabled={placement === INITIAL}
+          onClick={() => {
+            setPlacement(INITIAL);
+            setLastMove(null);
+          }}
+        >
+          Сбросить
+        </Button.Root>
+      </div>
+      <Kanban.Root
+        aria-label="Счета за октябрь"
+        className={styles.board}
+        columns={COLUMNS}
+        items={INVOICES}
+        getId={(invoice) => invoice.id}
+        getLabel={(invoice) => invoice.id}
+        value={placement}
+        onValueChange={(next, move) => {
+          setPlacement(next);
+          setLastMove(move);
+        }}
+        renderItem={(invoice) => (
+          <Kanban.Item>
+            <Kanban.ItemTitle>{invoice.client}</Kanban.ItemTitle>
+            <Kanban.ItemDescription>
+              {invoice.id} · {invoice.amount}
+            </Kanban.ItemDescription>
+          </Kanban.Item>
+        )}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,31 @@
+/* Layout of the Kanban scenarios: semantic tokens only. */
+
+/* A board gets its height from the page region it fills; tall columns scroll inside it. */
+.board {
+  block-size: calc(var(--prime-space-24) * 5);
+}
+
+/* A board that stands below its own toolbar. */
+.stage {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-3);
+  inline-size: 100%;
+}
+
+.toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-3);
+}
+
+.spacer {
+  flex: 1;
+}
+
+/* A phone-width screen. */
+.phone {
+  inline-size: min(100%, calc(var(--prime-space-20) * 4.5));
+  block-size: calc(var(--prime-space-24) * 5);
+}

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

@@ -0,0 +1,58 @@
+/** 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`. */
+import { Badge, Kanban } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+type Ticket = { id: string; title: string; client: string; blocked?: boolean };
+
+const COLUMNS = [
+  { id: "new", title: "Новые" },
+  { id: "progress", title: "В работе", limit: 3 },
+  { id: "solved", title: "Решены" },
+];
+
+const TICKETS: Ticket[] = [
+  { id: "SUP-1042", title: "Не приходит письмо со счётом", client: "ООО «Север»" },
+  { id: "SUP-1045", title: "Ошибка оплаты картой", client: "ИП Лебедев", blocked: true },
+  { id: "SUP-1038", title: "Сменить владельца аккаунта", client: "ООО «Вектор»" },
+  { id: "SUP-1036", title: "Дубли в отчёте по заказам", client: "АО «Гранит»" },
+  { id: "SUP-1031", title: "Нет доступа к API-ключам", client: "ООО «Логистик»" },
+  { id: "SUP-1027", title: "Перенести проект в другую команду", client: "ООО «Север»" },
+];
+
+const BLOCKED = new Set(TICKETS.filter((ticket) => ticket.blocked).map((ticket) => ticket.id));
+
+const PLACEMENT = {
+  new: ["SUP-1042", "SUP-1045"],
+  progress: ["SUP-1038", "SUP-1036", "SUP-1031"],
+  solved: ["SUP-1027"],
+};
+
+export default function KanbanLimitsExample() {
+  return (
+    <Kanban.Root
+      aria-label="Очередь поддержки"
+      className={styles.board}
+      columns={COLUMNS}
+      items={TICKETS}
+      getId={(ticket) => ticket.id}
+      getLabel={(ticket) => ticket.title}
+      defaultValue={PLACEMENT}
+      // A ticket waiting on the client cannot be closed.
+      canDrop={(id, columnId) => columnId !== "solved" || !BLOCKED.has(id)}
+      renderItem={(ticket) => (
+        <Kanban.Item>
+          <Kanban.ItemTitle>{ticket.title}</Kanban.ItemTitle>
+          <Kanban.ItemDescription>
+            {ticket.id} · {ticket.client}
+          </Kanban.ItemDescription>
+          {ticket.blocked ? (
+            <Kanban.ItemBadges>
+              <Badge.Root color="orange">Ждёт клиента</Badge.Root>
+            </Kanban.ItemBadges>
+          ) : null}
+        </Kanban.Item>
+      )}
+    />
+  );
+}

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

@@ -0,0 +1,76 @@
+/** 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. */
+import { Avatar, Kanban } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+type Task = { id: string; title: string; due: string; initials: string; name: string };
+
+const COLUMNS = [
+  { id: "todo", title: "К выполнению" },
+  { id: "progress", title: "В работе" },
+  { id: "done", title: "Готово" },
+];
+
+const TASKS: Task[] = [
+  {
+    id: "PRJ-301",
+    title: "Подготовить отчёт по продажам",
+    due: "до 14 окт",
+    initials: "АК",
+    name: "Анна Котова",
+  },
+  {
+    id: "PRJ-305",
+    title: "Созвон с ООО «Вектор»",
+    due: "до 9 окт",
+    initials: "ИС",
+    name: "Илья Смирнов",
+  },
+  {
+    id: "PRJ-297",
+    title: "Обновить прайс-лист",
+    due: "до 11 окт",
+    initials: "МВ",
+    name: "Мария Волкова",
+  },
+  {
+    id: "PRJ-290",
+    title: "Закрыть акты за сентябрь",
+    due: "2 окт",
+    initials: "АК",
+    name: "Анна Котова",
+  },
+];
+
+const PLACEMENT = {
+  todo: ["PRJ-301", "PRJ-305"],
+  progress: ["PRJ-297"],
+  done: ["PRJ-290"],
+};
+
+export default function KanbanNarrowExample() {
+  return (
+    <Kanban.Root
+      aria-label="Мои задачи"
+      className={styles.phone}
+      columns={COLUMNS}
+      items={TASKS}
+      getId={(task) => task.id}
+      getLabel={(task) => task.title}
+      defaultValue={PLACEMENT}
+      renderItem={(task) => (
+        <Kanban.Item>
+          <Kanban.ItemTitle>{task.title}</Kanban.ItemTitle>
+          <Kanban.ItemFooter>
+            <Kanban.ItemDescription>
+              {task.id} · {task.due}
+            </Kanban.ItemDescription>
+            <Avatar.Root size="s" aria-label={task.name}>
+              <Avatar.Fallback>{task.initials}</Avatar.Fallback>
+            </Avatar.Root>
+          </Kanban.ItemFooter>
+        </Kanban.Item>
+      )}
+    />
+  );
+}

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

@@ -0,0 +1,130 @@
+/** 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`. */
+import { Avatar, Badge, Button, Icon, Kanban, type PaletteColor } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+type Task = {
+  id: string;
+  title: string;
+  due: string;
+  labels: { text: string; color: PaletteColor }[];
+  comments: number;
+  assignee: { initials: string; name: string; color: PaletteColor };
+};
+
+const COLUMNS = [
+  { id: "backlog", title: "Бэклог" },
+  { id: "progress", title: "В работе" },
+  { id: "review", title: "На проверке" },
+  { id: "done", title: "Готово" },
+];
+
+const ANNA = { initials: "АК", name: "Анна Котова", color: "purple" } as const;
+const ILYA = { initials: "ИС", name: "Илья Смирнов", color: "teal" } as const;
+const MARIA = { initials: "МВ", name: "Мария Волкова", color: "orange" } as const;
+
+const TASKS: Task[] = [
+  {
+    id: "PRJ-214",
+    title: "Экспорт счетов в CSV для бухгалтерии",
+    due: "14 окт",
+    labels: [{ text: "Биллинг", color: "blue" }],
+    comments: 3,
+    assignee: ANNA,
+  },
+  {
+    id: "PRJ-221",
+    title: "Фильтр заказов по складу",
+    due: "17 окт",
+    labels: [{ text: "Заказы", color: "green" }],
+    comments: 0,
+    assignee: ILYA,
+  },
+  {
+    id: "PRJ-198",
+    title: "Повторная отправка приглашений в команду",
+    due: "10 окт",
+    labels: [
+      { text: "Команда", color: "purple" },
+      { text: "Срочно", color: "red" },
+    ],
+    comments: 5,
+    assignee: MARIA,
+  },
+  {
+    id: "PRJ-205",
+    title: "Тёмная тема для отчётов",
+    due: "12 окт",
+    labels: [{ text: "Дизайн", color: "pink" }],
+    comments: 2,
+    assignee: ANNA,
+  },
+  {
+    id: "PRJ-187",
+    title: "Лимиты API для партнёров",
+    due: "9 окт",
+    labels: [{ text: "API", color: "sky" }],
+    comments: 8,
+    assignee: ILYA,
+  },
+  {
+    id: "PRJ-176",
+    title: "Онбординг нового проекта",
+    due: "3 окт",
+    labels: [{ text: "Проекты", color: "yellow" }],
+    comments: 1,
+    assignee: MARIA,
+  },
+];
+
+const PLACEMENT = {
+  backlog: ["PRJ-214", "PRJ-221"],
+  progress: ["PRJ-198", "PRJ-205"],
+  review: ["PRJ-187"],
+  done: ["PRJ-176"],
+};
+
+export default function KanbanOverviewExample() {
+  return (
+    <Kanban.Root
+      aria-label="Задачи релиза 2.4"
+      className={styles.board}
+      columns={COLUMNS}
+      items={TASKS}
+      getId={(task) => task.id}
+      getLabel={(task) => task.title}
+      defaultValue={PLACEMENT}
+      renderColumnActions={(column) => (
+        <Button.Root variant="ghost" tone="neutral" aria-label={`Добавить в «${column.title}»`}>
+          <Button.Icon>
+            <Icon name="action.add" />
+          </Button.Icon>
+        </Button.Root>
+      )}
+      renderItem={(task) => (
+        <Kanban.Item>
+          <Kanban.ItemTitle>{task.title}</Kanban.ItemTitle>
+          <Kanban.ItemDescription>
+            {task.id} · до {task.due}
+          </Kanban.ItemDescription>
+          <Kanban.ItemBadges>
+            {task.labels.map((label) => (
+              <Badge.Root key={label.text} color={label.color}>
+                {label.text}
+              </Badge.Root>
+            ))}
+          </Kanban.ItemBadges>
+          <Kanban.ItemFooter>
+            <Kanban.ItemCount>
+              <Icon name="object.message" />
+              {task.comments}
+            </Kanban.ItemCount>
+            <Avatar.Root size="s" color={task.assignee.color} aria-label={task.assignee.name}>
+              <Avatar.Fallback>{task.assignee.initials}</Avatar.Fallback>
+            </Avatar.Root>
+          </Kanban.ItemFooter>
+        </Kanban.Item>
+      )}
+    />
+  );
+}

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

@@ -0,0 +1,75 @@
+/** 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`. */
+import { Button, Icon, Kanban, Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Order = { id: string; title: string; total: string };
+
+const COLUMNS = [
+  { id: "new", title: "Новые" },
+  { id: "packing", title: "Сборка" },
+  { id: "shipped", title: "Отгружены" },
+];
+
+const ORDERS: Order[] = [
+  { id: "ORD-5531", title: "ООО «Север» · 12 позиций", total: "48 300 ₽" },
+  { id: "ORD-5529", title: "ИП Лебедев · 3 позиции", total: "7 950 ₽" },
+  { id: "ORD-5524", title: "АО «Гранит» · 40 позиций", total: "212 000 ₽" },
+];
+
+const PLACEMENT = { new: ["ORD-5531", "ORD-5529"], packing: [], shipped: ["ORD-5524"] };
+
+const LOAD_MS = 1200;
+
+export default function KanbanStatesExample() {
+  const [loading, setLoading] = React.useState(true);
+  const [readOnly, setReadOnly] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!loading) return;
+    const timer = window.setTimeout(() => setLoading(false), LOAD_MS);
+    return () => window.clearTimeout(timer);
+  }, [loading]);
+
+  return (
+    <div className={styles.stage}>
+      <div className={styles.toolbar}>
+        <Switch.Root checked={readOnly} onCheckedChange={setReadOnly}>
+          <Switch.Label>Только просмотр</Switch.Label>
+        </Switch.Root>
+        <div className={styles.spacer} />
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          loading={loading}
+          onClick={() => setLoading(true)}
+        >
+          <Button.Icon>
+            <Icon name="action.refresh" />
+          </Button.Icon>
+          Обновить
+        </Button.Root>
+      </div>
+      <Kanban.Root
+        aria-label="Заказы склада"
+        className={styles.board}
+        columns={COLUMNS}
+        items={ORDERS}
+        getId={(order) => order.id}
+        getLabel={(order) => order.id}
+        defaultValue={PLACEMENT}
+        loading={loading}
+        disabled={readOnly}
+        renderItem={(order) => (
+          <Kanban.Item>
+            <Kanban.ItemTitle>{order.id}</Kanban.ItemTitle>
+            <Kanban.ItemDescription>
+              {order.title} · {order.total}
+            </Kanban.ItemDescription>
+          </Kanban.Item>
+        )}
+      />
+    </div>
+  );
+}