prime-ui-kit 0.9.1 → 0.9.2

package/src/components/dropdown/COMPONENT.md

@@ -35,6 +35,7 @@ Dropdown.Root                     state and dismiss policy (no DOM)
     │   └── Dropdown.Item         <button role="menuitem">
     │       ├── Dropdown.ItemIcon       leading glyph (aria-hidden)
     │       └── Dropdown.ItemShortcut   Kbd at the end
+    ├── Dropdown.CheckboxItem     <button role="menuitemcheckbox">: label + check mark at the end while checked; stays open
     └── Dropdown.Item
 ```
 
@@ -62,7 +63,7 @@ No DOM: clones the single child, merges `ref` and `onClick` (toggles), sets `ari
 | `children` | `ReactElement` | — (required) | One element, usually a Button. |
 
 ### Dropdown.Content
-`ref` → `HTMLDivElement`. Portal + `role="menu"` on the floating surface (a ScrollContainer), named by the trigger; renders while open and during its exit animation. Focus moves to the first item; Tab closes the menu and returns focus to the trigger.
+`ref` → `HTMLDivElement`. Portal + `role="menu"` on the floating surface (a ScrollContainer), named by the trigger; renders while open and during its exit animation. Focus moves to the first item; Tab closes the menu and returns focus to the trigger. Below 640px of viewport the menu is a bottom sheet: a scrim, a grab handle, swipe down to close (with `closeOnOutsideClick`), page scroll locked.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -82,6 +83,17 @@ No DOM: clones the single child, merges `ref` and `onClick` (toggles), sets `ari
 | `tone` | `"neutral" \| "danger"` | `"neutral"` | `danger`: destructive action — danger text, icon and hover fill. |
 | `children` | `ReactNode` | — | `Dropdown.ItemIcon`, the label, `Dropdown.ItemShortcut`. |
 
+### Dropdown.CheckboxItem
+`ref` → `HTMLButtonElement`. A `<button role="menuitemcheckbox">` with `aria-checked`: the label (and an `ItemIcon`) on the left like any item, an accent check mark at the end while checked and nothing while not; a click, Enter or Space toggles it and the menu stays open. + native button props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `checked` | `boolean` | — | Checked state (controlled). |
+| `defaultChecked` | `boolean` | `false` | Initial state (uncontrolled). |
+| `onCheckedChange` | `(checked: boolean) => void` | — | Called with the new state. |
+| `disabled` | `boolean` | `false` | Muted, `aria-disabled`, skipped by the arrow keys, does not toggle. |
+| `children` | `ReactNode` | — | The label (optionally after a `Dropdown.ItemIcon`). |
+
 ### Dropdown.ItemIcon · Dropdown.ItemShortcut
 `ref` → `HTMLSpanElement` / `HTMLElement` (the `<kbd>`). An `aria-hidden` `<span>` holding the leading glyph at the menu icon size (a kit `Icon` follows it) / a `Kbd` one tier below the menu, pushed to the end of the item — a hint, not a handler. + native props.
 
@@ -145,9 +157,10 @@ The panel is the shared floating surface: `bg-raised`, `--prime-panel-radius` (1
 | open / closed | `open` / `defaultOpen` / `onOpenChange` | `data-state` on the menu (closed while the exit animation plays) and on the trigger, `aria-expanded` on the trigger |
 | side | `side` and the room next to the trigger | `data-side` (resolved) |
 | size | `size` on Content | `data-size` |
-| item hover / focus | pointer, arrow keys | subtle fill (danger-soft for `danger`), no movement |
+| item hover / focus | a hovering pointer, arrow keys | subtle fill (danger-soft for `danger`), no movement; a tap leaves no hover fill |
 | item disabled | `disabled` | `aria-disabled="true"`, `data-disabled="true"` |
 | item tone | `tone` | `data-tone` |
+| sheet | viewport below 640px | a scrim and a full-width bottom sheet with an `aria-hidden` grab handle around the menu; the sheet carries `data-state`, the menu keeps its role and ref; page scroll locked; a swipe down from the handle closes it (with `closeOnOutsideClick`) |
 
 ## Layout & spacing
 - Width is `max-content` between `--prime-panel-min-width` and twice that; items never wrap.
@@ -160,14 +173,14 @@ The panel is the shared floating surface: `bg-raised`, `--prime-panel-radius` (1
 ### Keyboard
 | Key | Action |
 |---|---|
-| `Enter` · `Space` | On the trigger opens the menu (focus on the first item); on an item runs it and returns focus to the trigger. |
+| `Enter` · `Space` | On the trigger opens the menu (focus on the first item); on an item runs it and returns focus to the trigger; on a checkbox item toggles it and the menu stays open. |
 | `ArrowDown` · `ArrowUp` | Move focus to the next / previous enabled item, wrapping. |
 | `Home` · `End` | First / last enabled item. |
 | `Escape` | Closes the menu (`closeOnEscape`); focus returns to the trigger. |
 | `Tab` · `Shift+Tab` | Closes the menu; focus returns to the trigger (Tab then goes on to the next stop). |
 
 ### ARIA
-- The menu is `role="menu"` named by the trigger; items are `role="menuitem"`, disabled ones `aria-disabled`.
+- The menu is `role="menu"` named by the trigger; items are `role="menuitem"`, checkbox items `role="menuitemcheckbox"` with `aria-checked`, disabled ones `aria-disabled`.
 - The trigger gets `aria-haspopup="menu"`, `aria-expanded` and `aria-controls`.
 - `Dropdown.Group` is `role="group"` named by its `label`.
 - `Dropdown.ItemIcon` is hidden from screen readers; a key hint is text only — the app handles the shortcut.
@@ -187,6 +200,7 @@ No `labels`.
 | [placement.tsx](examples/placement.tsx) | Every side and alignment relative to the trigger; near the viewport edge the menu flips and shifts — `side`, `align`. |
 | [states.tsx](examples/states.tsx) | A regular, a disabled and a destructive item; arrow keys skip the disabled one — `disabled`, `tone`. |
 | [match-trigger-width.tsx](examples/match-trigger-width.tsx) | Under a full-width button the menu is at least as wide as the trigger — `matchTriggerWidth`. |
+| [checkbox-items.tsx](examples/checkbox-items.tsx) | A column chooser: toggles in the menu keep it open, the key column cannot be hidden — `Dropdown.CheckboxItem`, `checked`, `onCheckedChange`. |
 | [long-list.tsx](examples/long-list.tsx) | More projects than fit: the grouped list scrolls inside the panel, capped by the room next to the trigger — `Dropdown.Group`. |
 | [dismiss.tsx](examples/dismiss.tsx) | An onboarding step keeps the menu open on an outside press and on Escape until an item is picked — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the open state and opens the menu from another button; the picked step updates the trigger — `open`, `onOpenChange`. |
@@ -199,5 +213,5 @@ No `labels`.
 - A destructive item without `tone="danger"`, or in the middle of the list → mark it and put it last.
 
 ## Related
-- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (the menu), [Kbd](../kbd/COMPONENT.md) (`ItemShortcut`), [Divider](../divider/COMPONENT.md) (`Separator`)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (the menu), [Kbd](../kbd/COMPONENT.md) (`ItemShortcut`), [Divider](../divider/COMPONENT.md) (`Separator`), Icon (`action.check` of `CheckboxItem`)
 - **See also:** [Select](../select/COMPONENT.md), [CommandMenu](../command-menu/COMPONENT.md), [Popover](../popover/COMPONENT.md), [Button](../button/COMPONENT.md)

package/src/components/dropdown/examples/checkbox-items.tsx

@@ -0,0 +1,48 @@
+/** A column chooser: toggles in the menu keep it open, the key column cannot be hidden — `Dropdown.CheckboxItem`, `checked`, `onCheckedChange`. */
+import { Button, Dropdown, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+const COLUMNS = [
+  { id: "number", label: "Номер", locked: true },
+  { id: "client", label: "Клиент", locked: false },
+  { id: "status", label: "Статус", locked: false },
+  { id: "amount", label: "Сумма", locked: false },
+  { id: "due", label: "Срок оплаты", locked: false },
+];
+
+export default function DropdownCheckboxItemsExample() {
+  const [hidden, setHidden] = React.useState<string[]>(["due"]);
+  const shown = COLUMNS.length - hidden.length;
+
+  const toggle = (id: string, visible: boolean) =>
+    setHidden((list) => (visible ? list.filter((item) => item !== id) : [...list, id]));
+
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          <Button.Icon>
+            <Icon name="action.settings" />
+          </Button.Icon>
+          Колонки: {shown} из {COLUMNS.length}
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Group label="Показывать">
+          {COLUMNS.map((column) => (
+            <Dropdown.CheckboxItem
+              key={column.id}
+              checked={!hidden.includes(column.id)}
+              disabled={column.locked}
+              onCheckedChange={(visible) => toggle(column.id, visible)}
+            >
+              {column.label}
+            </Dropdown.CheckboxItem>
+          ))}
+        </Dropdown.Group>
+        <Dropdown.Separator />
+        <Dropdown.Item onSelect={() => setHidden([])}>Показать все</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/src/components/empty-page/COMPONENT.md

@@ -1,6 +1,6 @@
 # EmptyPage
 
-**Category:** feedback
+**Category:** status
 **Kind:** composite
 
 > Empty state of a page, a block or a menu: icon, title, explanation and an action.

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-faint` well; 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>` on the raised fill (`bg-raised`) with the card shadow; 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 gets a `fill-subtle` wash (`@media (hover: hover)` only) |
+| 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 wash and the empty well fade on opacity (`fast`, `standard`); 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>
+      )}
+    />
+  );
+}