prime-ui-kit 0.7.13 → 0.9.1

package/src/components/divider/COMPONENT.md

@@ -1,102 +1,113 @@
 # Divider
 
-## Canonical
+**Category:** layout
+**Kind:** primitive
 
-- **What:** `Divider.Root` draws a horizontal or vertical separator (pseudo-element lines) with optional **children** (label, icon + text). Nested controls inherit **`size`** via **`ControlSizeProvider`**.
-- **Defaults:** `orientation="horizontal"`, `variant="default"`, `size="m"`. **`align`** defaults to **`start`** for **`variant="text"`**, otherwise **`center`**.
-- **Import:** `import { Divider } from "prime-ui-kit"`.
+> A hairline separator inside one surface, horizontal or vertical, with or without a label.
 
+## When to use
+- Separate rows of a list or groups inside one panel, menu or card.
+- An «или» between two alternative actions (sign in / get a link by email).
+- A section heading drawn on a line (`align="start"`).
+- A vertical break between groups of buttons in a toolbar row.
+
+## When not to use
+- To separate cards or panels from each other → use fill and spacing ([Card](../card/COMPONENT.md), [PageContent](../page-content/COMPONENT.md) sections), never a line.
+- Separators inside a dropdown menu → `Dropdown.Separator` ([Dropdown](../dropdown/COMPONENT.md)).
+- Row lines of a table → [DataTable](../data-table/COMPONENT.md) draws them itself.
+
+## Import
 ```tsx
 import { Divider } from "prime-ui-kit";
-
-export function Example() {
-  return <Divider.Root />;
-}
 ```
 
-## Extended
-
-### About
-
-`Divider` is a non-interactive visual separator: a line built from `::before` / `::after`, optionally wrapping a label or icon. **`Icon`** inside **`children`** does not use its own size classes — glyph size follows **`--prime-divider-icon`** from the root **`data-size`**.
-
-**When to use**
-
-- Separate blocks in a form, card, or settings column without an extra bordered panel.
-- Full-width rows in a list-like shell (`examples/list-separators.tsx`).
-- Section-style labels inline with the line (`variant="text"`) — see `examples/section-breaks.tsx`.
-- Between flex children in a column when rhythm comes from the parent **`gap`** (`variant="line-spacing"`) — see `examples/line-spacing-column.tsx`.
-- A vertical bar between toolbar actions (`orientation="vertical"`); parent row should **`align-items: stretch`** so the line gets height.
-
-**When not to use**
-
-- As the only semantic boundary for document structure — use real headings / **`section`** (and **`hr`** when a thematic break is appropriate).
-- For switchable or collapsible grouping — use [Tabs](../tabs/COMPONENT.md) or [Accordion](../accordion/COMPONENT.md).
-- **`orientation="vertical"`** in a row with no definite height — the vertical line needs stretch from the parent.
-- Purely decorative repetition next to text that already states structure — hide from AT (**`role="presentation"`**, **`aria-hidden`**) per **Rules**.
-
-### Composition
-
-- Single public part: **`Divider.Root`** — optional **`children`** render in an inner **`span`** (**`styles.content`**).
-- Place **`Divider.Root`** in document order where the break should appear; no required child structure beyond optional slot content.
-
-### Examples (source)
-
-| Scenario | File |
-|----------|------|
-| Section breaks (`variant="text"`) | [`examples/section-breaks.tsx`](examples/section-breaks.tsx) |
-| Splits inside one card | [`examples/card-splits.tsx`](examples/card-splits.tsx) |
-| List row separators | [`examples/list-separators.tsx`](examples/list-separators.tsx) |
-| Inset copy in a stack, full-bleed rules | [`examples/inset-stack.tsx`](examples/inset-stack.tsx) |
-| `line-spacing` + vertical toolbar | [`examples/line-spacing-column.tsx`](examples/line-spacing-column.tsx) |
-
-Shared layout tokens for the examples: [`examples/divider-examples.module.css`](examples/divider-examples.module.css).
-
-Playground snippets (same demos as `playground/sections/DividerSection.tsx`):
-
-- **`variants.tsx`** — empty horizontal line; **`default`** with centered label; **`variant="text"`**; **`line-spacing`** between rows in a column; **`orientation="vertical"`** between toolbar-style buttons; full-width line between list rows (**`size="s"`**).
-- **`sizes.tsx`** — **`variant="text"`** at **`size`** **`s`**, **`m`**, and **`xl`** (three steps to compare label scale and spacing).
-- **`composition.tsx`** — **`Icon`** + label inside **`variant="text"`** **`size="m"`**; second divider at **`size="xl"`** with icon + label.
-
-### Rules
-
-- **Non-interactive:** no disabled/loading/focus states; behavior is plain **`div`** semantics unless you set **`role`** / **`aria-*`**.
-- **`variant="default"`** — full-width line; optional centered label unless **`align`** overrides.
-- **`variant="text"`** — uppercase section label styling; **`align`** defaults to **`start`**.
-- **`variant="line-spacing"`** — **`flex: 0 0 auto`** so it does not act as a flex grow spacer; spacing is the parent’s **`gap`**.
-- **Semantics:** default **`role="separator"`**; for **`orientation="vertical"`**, **`aria-orientation="vertical"`** is set automatically.
-- **Decoration:** redundant lines → **`role="presentation"`** (or **`none`**) and **`aria-hidden`** (see list example).
-- **Sizing:** match adjacent controls with the same **`size`** prop; do not patch stroke width with ad hoc pixels.
-
-### API
-
-#### Divider.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| orientation | `"horizontal"` \| `"vertical"` | `"horizontal"` | No | Line direction. |
-| align | `"start"` \| `"center"` \| `"end"` | `center` for `default` / `line-spacing`; `start` for `text` | No | Balance of `::before` / `::after` stubs around content. |
-| variant | `"default"` \| `"line-spacing"` \| `"text"` | `"default"` | No | Visual mode and flex participation. |
-| size | `"s"` \| `"m"` \| `"l"` \| `"xl"` | `"m"` | No | Gap, label type, icon scale, **`ControlSizeProvider`** value. |
-| children | `React.ReactNode` | — | No | Label, icon + text, or omit for a solid line. |
-| className | `string` | — | No | Extra class on the root. |
-| role | `string` | `"separator"` | No | Override for decorative separators. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | `aria-*`, `data-*`, etc. |
-
-### Related
-
-- [Typography](../typography/COMPONENT.md)
-- [Button](../button/COMPONENT.md)
-- [Link button](../link-button/COMPONENT.md)
-- [Tabs](../tabs/COMPONENT.md)
-- [Accordion](../accordion/COMPONENT.md)
-
-## LLM note
+## Anatomy
+```
+Divider          <div role="separator">; the line is drawn by ::before / ::after
+└─ label         children (text, Icon) between the two line halves
+```
 
-- One export shape: **`Divider.Root`** only; no subcomponents.
-- **`variant` × `align` defaults:** `text` → **`align` `start`**; else **`center`** (explicit **`align`** always wins).
-- **`line-spacing`:** use only when the parent flex column uses **`gap`** for vertical rhythm; divider must not be relied on for layout height.
-- **Vertical:** requires ancestor **`align-items: stretch`** (or explicit height) so `::before`/`::after` flex segments fill the row.
-- **Children:** toggles inner **`span`** and **`ControlSizeProvider`**; **`Icon`** ignores its own **`size`** when inside divider content.
-- **a11y:** default **`separator`** is announced; for decorative list lines between items, mirror **`examples/list-separators.tsx`**: **`ul`/`li`**, separator **`li`** with **`aria-hidden`**, **`Divider.Root`** with **`role="presentation"`**.
-- **Playground alignment:** `variants.tsx` is one frame (empty line, `default` label, `text`, `line-spacing` column, vertical toolbar, list-row separator); `sizes.tsx` is `text` at **s / m / xl**; `composition.tsx` is icon + text at **m** and **xl**.
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Divider
+`ref` → `HTMLDivElement`. A `role="separator"` hairline in `border-subtle`; children become its label.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | `vertical` stretches to the height of its flex row and sets `aria-orientation`. |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | Position of the label on the line; `start` reads as a section heading. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the label: type, gap and icon size. Match the content around the divider. |
+| `children` | `ReactNode` | — | Label: text, an `Icon`, or both. Omit for a plain line. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` (`"presentation"` for a purely visual line), `aria-label` and the other div attributes. |
+
+## Variants
+No `variant`, `tone` or `color`: one hairline in `border-subtle`, label in `text-muted`, weight 500.
+
+### align
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `start` | label flush left, line to the right | a section heading on a line | |
+| `center` | line — label — line | «или», a date in a feed | yes |
+| `end` | line to the left, label flush right | an end marker | |
+
+### orientation
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `horizontal` | full-width line | between rows and blocks | yes |
+| `vertical` | line as tall as its flex row | between toolbar groups | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` · `s` | label 12/16, caption tracking | dense menus, `s` content | |
+| `m` | label 13/20, icon 16 | regular content | yes |
+| `l` · `xl` | label 14/20 · 16/24, icon 20 | large panels | |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| plain line | no children | `:empty`, one line |
+| labelled | children | two line halves, each at least `--prime-space-6` long |
+| orientation / align / size | props | `data-orientation`, `data-align`, `data-size`, `aria-orientation` when vertical |
+
+## Layout & spacing
+- No margins: the parent's `gap` sets the rhythm around the line.
+- Horizontal: `width: 100%` in its flex column. Vertical: `align-self: stretch` in a flex row.
+- Label gap and icon size follow the tier (`--prime-control-<size>-gap`, `-icon`).
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- `role="separator"`; vertical sets `aria-orientation="vertical"`.
+- A purely visual line between rows that are separate anyway → `role="presentation"`.
+- The label is read as the separator's text; an icon-only divider needs `aria-label`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Hairlines between the rows of a settings list. |
+| [sizes.tsx](examples/sizes.tsx) | The label at every tier, matching the content around it — `size`. |
+| [with-icon.tsx](examples/with-icon.tsx) | An icon before the label and an icon alone on the line; the divider sizes it. |
+| [align.tsx](examples/align.tsx) | The label at the start, the center or the end of the line; `start` heads a section — `align`. |
+| [vertical.tsx](examples/vertical.tsx) | A vertical line between groups of toolbar buttons — `orientation`. |
+| [or-separator.tsx](examples/or-separator.tsx) | An "or" line between two ways to sign in. |
+
+## Mistakes
+- Margins on the divider → spacing via the parent `gap`.
+- Lines between cards → separate cards by fill and spacing.
+- `<Icon size="l" />` inside the label → leave the size to the divider.
+- A vertical divider in a block container (no height) → place it in a flex row.
+
+## Related
+- **Built from:** —
+- **See also:** [Dropdown](../dropdown/COMPONENT.md), [Card](../card/COMPONENT.md), [PageContent](../page-content/COMPONENT.md)

package/src/components/divider/examples/align.tsx

@@ -0,0 +1,14 @@
+/** The label at the start, the center or the end of the line; `start` heads a section — `align`. */
+import { Divider } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DividerAlignExample() {
+  return (
+    <div className={styles.column}>
+      <Divider align="start">Уведомления</Divider>
+      <Divider>Сегодня</Divider>
+      <Divider align="end">Конец истории</Divider>
+    </div>
+  );
+}

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

@@ -0,0 +1,30 @@
+/* Layout of the Divider scenarios: semantic tokens only. */
+
+/* A column as wide as a short form: the lines need room to read as lines. */
+.column {
+  display: grid;
+  gap: var(--prime-space-3);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+/* vertical.tsx: the row stretches the vertical line to the buttons' height. */
+.toolbar {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-2);
+}
+
+/* overview.tsx */
+.list {
+  display: flex;
+  flex-direction: column;
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+.listRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-4);
+  padding-block: var(--prime-space-3);
+}

package/src/components/divider/examples/or-separator.tsx

@@ -0,0 +1,19 @@
+/** An "or" line between two ways to sign in. */
+import { Button, Divider, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DividerOrSeparatorExample() {
+  return (
+    <div className={styles.column}>
+      <Button.Root fullWidth>Войти</Button.Root>
+      <Divider>или</Divider>
+      <Button.Root variant="outline" tone="neutral" fullWidth>
+        <Button.Icon>
+          <Icon name="field.email" />
+        </Button.Icon>
+        Получить ссылку на почту
+      </Button.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,30 @@
+/** Hairlines between the rows of a settings list. */
+import { Divider, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const ROWS = [
+  { label: "Пароль", value: "Изменён 12 дней назад" },
+  { label: "Двухфакторный вход", value: "Включён" },
+  { label: "Активные сессии", value: "3 устройства" },
+];
+
+export default function DividerOverviewExample() {
+  return (
+    <div className={styles.list}>
+      {ROWS.map((row, index) => (
+        <div key={row.label}>
+          {index > 0 ? <Divider /> : null}
+          <div className={styles.listRow}>
+            <Typography as="span" variant="body-m">
+              {row.label}
+            </Typography>
+            <Typography as="span" variant="body-m" tone="secondary">
+              {row.value}
+            </Typography>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,19 @@
+/** The label at every tier, matching the content around it — `size`. */
+import { Divider, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function DividerSizesExample() {
+  return (
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Divider size={size}>Раздел</Divider>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/divider/examples/vertical.tsx

@@ -0,0 +1,21 @@
+/** A vertical line between groups of toolbar buttons — `orientation`. */
+import { Button, Divider } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DividerVerticalExample() {
+  return (
+    <div className={styles.toolbar}>
+      <Button.Root variant="ghost" tone="neutral">
+        Вырезать
+      </Button.Root>
+      <Button.Root variant="ghost" tone="neutral">
+        Копировать
+      </Button.Root>
+      <Divider orientation="vertical" />
+      <Button.Root variant="ghost" tone="danger">
+        Удалить
+      </Button.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,26 @@
+/** An icon before the label and an icon alone on the line; the divider sizes it. */
+import { Divider, Icon, Typography } from "prime-ui-kit";
+
+export default function DividerWithIconExample() {
+  return (
+    <div>
+      <div>
+        <Divider>
+          <Icon name="status.locked" />
+          Безопасность
+        </Divider>
+        <Typography as="span" variant="caption" tone="muted">
+          иконка и подпись
+        </Typography>
+      </div>
+      <div>
+        <Divider aria-label="Безопасность">
+          <Icon name="status.locked" />
+        </Divider>
+        <Typography as="span" variant="caption" tone="muted">
+          только иконка
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/dnd/COMPONENT.md

@@ -0,0 +1,197 @@
+# Dnd
+
+**Category:** layout
+**Kind:** composite
+
+> Pointer-driven drag and drop: reorderable lists, draggable items and drop zones on one shared session, with a lifted clone, a gap where the item lands, auto-scroll, touch support and a keyboard path.
+
+## When to use
+- Reordering a list, a row of chips or a set of settings by hand (`Dnd.Sortable`).
+- Moving an item between lists to an exact position: a board of columns (several `Dnd.Sortable` with one `kind`).
+- Moving an item onto a target with no inner order: a folder, an assignee (`Dnd.Draggable` + `Dnd.DropZone`).
+
+## When not to use
+- Picking files from the computer → use [FileUpload](../file-upload/COMPONENT.md) (native file drop).
+- An order that is a plain setting with few options → a [Select](../select/COMPONENT.md) or [SegmentedControl](../segmented-control/COMPONENT.md) is faster.
+- Dragging values (a slider thumb, a color square) → use [Slider](../slider/COMPONENT.md) or [ColorPicker](../color-picker/COMPONENT.md).
+- Reordering table rows or a virtualized list → not covered: the engine measures the DOM, so only mounted items take part.
+
+## Import
+```tsx
+import { Dnd, moveBefore } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Dnd.Root                         session owner: overlay (portal), live region, labels — mount once
+├─ Dnd.Sortable                  list container and drop target; renders items in the drawn order
+│  └─ Dnd.SortableItem           one item (li in ul/ol, div otherwise); the gap is drawn before it
+│     └─ Dnd.Handle              optional grip: a ghost icon-only Button (with `handle` on the list)
+├─ Dnd.Draggable                 an item to carry elsewhere; stays in place, faded, until the drop
+└─ Dnd.DropZone                  a box that takes dropped items
+```
+A drag in flight is drawn by `Dnd.Root` as a clone of the lifted element above every layer, following the pointer. The page gets `data-dnd-active="mouse | touch | pen"` on `<html>` for the length of the gesture.
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Dnd.Root
+No ref, no DOM of its own besides the portalled overlay and a visually hidden live region. Owns the one drag session the app shares — mount it once above every screen that drags. Without a root the parts render but do not drag.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `labels` | `Partial<DndLabels>` | — | Built-in strings, see Labels. |
+| `children` | `ReactNode` | — | The app or the screen that drags. |
+
+### Dnd.Sortable
+Generic `Dnd.Sortable<T>`; `ref` → `HTMLElement`. Renders `<div>`, `<ul>` or `<ol>` and registers itself as the drop target; draws the gap and the optimistic order. Sets `data-axis` and `data-dragging`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `readonly T[]` | — (required) | Items in their current order. |
+| `getId` | `(item: T) => string` | — (required) | Stable unique id; must match `Dnd.SortableItem id`. |
+| `getLabel` | `(item: T) => string` | `the id` | Spoken by the live region. |
+| `onReorder` | `(id: string, beforeId: string \| null) => DndReorderResult \| Promise<DndReorderResult>` | — (required) | The item `id` lands in front of `beforeId` (`null` = last); with connected lists `id` may come from another list. Apply it with `moveBefore`; return `{ ok: false }` (or reject) to roll the drawn order back. |
+| `renderItem` | `(item: T, index: number) => ReactNode` | — (required) | Returns a `Dnd.SortableItem`. |
+| `axis` | `"x" \| "y"` | `"y"` | A column or a single row; wrapping grids are not supported. |
+| `handle` | `boolean` | `false` | Only `Dnd.Handle` starts a drag; the rest of the item stays free for clicks and text selection. |
+| `disabled` | `boolean` | `false` | No drag, no keyboard reorder. |
+| `kind` | `string` | `unique per list` | Lists sharing a `kind` exchange items (a board). |
+| `canDrop` | `(id: string) => boolean` | — | Refuses an item by id; the list gets `data-dnd-reject` and turns `danger` before the release. |
+| `as` | `"div" \| "ul" \| "ol"` | `"div"` | Root element; `ul` / `ol` render items as `li`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "children">` | — | `className` (the list layout), `aria-label` (the name of the list) and the other attributes of the list element. |
+
+### Dnd.SortableItem
+`ref` → `HTMLElement`. `<li>` inside `ul` / `ol`, `<div>` otherwise; throws outside `Dnd.Sortable`. Sets `data-lifted`, `data-dnd-item`, `aria-roledescription`, `aria-keyshortcuts` and `tabIndex={0}` (not with `handle`). Presses on buttons, fields, links and `[data-dnd-ignore]` inside never start a drag.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `id` | `string` | — (required) | The item id (same as `getId`). |
+| `disabled` | `boolean` | `false` | This item cannot be dragged or moved. |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "id">` | — | `className` (the row look: fill, radius, padding) and the other attributes; `onPointerDown` / `onKeyDown` run first, `preventDefault()` keeps the drag from starting. |
+
+### Dnd.Handle
+`ref` → `HTMLButtonElement`. The grip: a ghost icon-only `xs` Button with the `action.drag` icon; a press always starts the drag, Alt+arrows on it reorder its item.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `aria-label` | `string` | `labels.handle` | Accessible name. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "children">` | — | `className`, `disabled` and the other button attributes. |
+
+### Dnd.Draggable
+Generic `Dnd.Draggable<TData>`; `ref` → `HTMLElement`. Renders the `as` element; stays in place at reduced opacity (`data-dragging`) while carried. Has no keyboard path of its own: offer a button or a menu for the same move.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `kind` | `string` | — (required) | What it is; zones accept by kind. |
+| `id` | `string` | — (required) | Unique within its kind. |
+| `data` | `TData` | — | Payload handed to the zone's `onDrop`. |
+| `label` | `string` | `the id` | Spoken by the live region. |
+| `disabled` | `boolean` | `false` | Not draggable. |
+| `handle` | `boolean` | `false` | Only a `Dnd.Handle` inside starts the drag. |
+| `as` | `"div" \| "li" \| "span" \| "article" \| "section"` | `"div"` | Element. |
+| `onDragStart` | `(item, point, origin) => void` | — | Fired once the press became a drag. |
+| `onDragEnd` | `(item, outcome: "drop" \| "release" \| "cancel") => void` | — | Always fired at the end. |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "id">` | — | `className` and the other attributes. |
+
+### Dnd.DropZone
+Generic `Dnd.DropZone<TData>`; `ref` → `HTMLElement`. Renders the `as` element; state is mirrored by `data-dnd-over`, `data-dnd-reject`, `data-dnd-flash`. Where zones overlap, the innermost wins.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `accepts` | `string \| readonly string[] \| ((item: DragItem) => boolean)` | — (required) | Kinds it takes, or a predicate. |
+| `onDrop` | `(item: DragItem<TData>) => void` | — (required) | An accepted item landed. |
+| `canDrop` | `(item: DragItem<TData>) => boolean` | — | Refuses an item; the zone turns `danger` before the release. |
+| `onEnter · onLeave` | `(item) => void · () => void` | — | An accepted item came over / left. |
+| `flashOnDrop` | `boolean` | `false` | Flashes the zone after a drop. |
+| `disabled` | `boolean` | `false` | Not a target. |
+| `as` | `"div" \| "section" \| "li" \| "ul" \| "ol" \| "span"` | `"div"` | Element. |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "onDrop">` | — | `className` (the zone's own look) and the other attributes. |
+
+### moveBefore
+`moveBefore(items, id, beforeId, getId)` returns `items` with `id` moved in front of `beforeId` (`null` = last): the body of every `onReorder`.
+
+## Variants
+
+### axis (Dnd.Sortable)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `y` | a column; the gap opens above or below neighbours | lists, settings, menus | yes |
+| `x` | one row of items; the gap opens left or right | chips, tabs, tag strips | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `handle` | only the grip starts a drag; the row keeps its controls | rows with buttons, switches, text | `false` |
+| `kind` shared | lists exchange items at an exact position | boards | unique per list |
+| `flashOnDrop` | the zone flashes `accent-soft` after a drop | the eye must follow where the item went | `false` |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| idle | — | items show `cursor: grab` |
+| carried | a drag | the clone follows the pointer, lifted on `--prime-shadow-modal`, scale 1.02; a sortable source leaves the layout (`data-lifted`) and a dashed accent gap of its size and radius fades in; neighbours glide aside; a `Dnd.Draggable` stays at 0.4 opacity (`data-dragging`) |
+| over a zone | pointer over an accepting zone | `data-dnd-over`: `accent-soft` fill, dashed accent outline |
+| refused | `canDrop` returns `false` | `data-dnd-reject`: `danger-soft` fill; the clone gets a dashed `danger` outline |
+| dropped | release | the clone glides to the item's new place and is swapped for the real element; `data-dnd-flash` with `flashOnDrop` |
+| cancelled | Escape, a system-cancelled pointer | the clone flies back, nothing changes |
+| disabled | `disabled` | `data-disabled`, no `aria-roledescription` |
+
+All motion is on the tokens (lift `fast`, glide and landing `base`, flash `slow`, `standard` easing; `data-dnd-flash` clears when the flash animation ends); under `prefers-reduced-motion` the lift, the gap fade, the glide and the flash are off.
+
+## Layout & spacing
+- The list gap is `--prime-space-2`; override it with `className`.
+- The look of a row is the consumer's: give `Dnd.SortableItem` / `Dnd.Draggable` a fill, a radius and padding on its own class — the clone is portalled to `<body>`, ancestor selectors do not reach it.
+- A scrollable ancestor under the pointer auto-scrolls within 64 px of its edge (a `ScrollContainer` strip works).
+- Keep a zone's height stable between states; it only changes fill and outline.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves to the list items (with `handle`, to the grips). |
+| `Alt + ↑` · `Alt + ↓` | Moves the item one place (`axis="x"`: Alt + ← / →). |
+| `Escape` | Cancels a drag in flight. |
+
+### ARIA
+- A live region (`role="status"`, `aria-live="polite"`) announces grabbed, dropped, returned, cancelled and «position N of M» from `labels`.
+- Every draggable item has `aria-roledescription` and `aria-keyshortcuts`; the clone is `aria-hidden`.
+- Touch: a drag starts after a hold; a finger that moves first scrolls the page.
+- `Dnd.Draggable` has no keyboard path of its own — offer a button or a menu for the same move.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `handle` | `"Перетащить"` | Name of `Dnd.Handle`. |
+| `roleDescription` | `"перетаскиваемый элемент"` | `aria-roledescription` of every draggable item. |
+| `grabbed` | `"{label}: взят"` | Live region: picked up. |
+| `dropped` | `"{label}: перемещён"` | Live region: dropped on a target. |
+| `returned` | `"{label}: возвращён на место"` | Live region: released over nothing. |
+| `cancelled` | `"{label}: перемещение отменено"` | Live region: cancelled (Escape, interruption). |
+| `moved` | `"{label}: позиция {position} из {total}"` | Live region: moved with the keyboard. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Project tasks reordered by dragging the whole row; one root above, the move applied with a helper — `Dnd.Root`, `Dnd.Sortable`, `onReorder`, `moveBefore`. |
+| [handle.tsx](examples/handle.tsx) | Notification channels with switches: only the grip starts a drag, and the async save can roll the order back — `handle`, `Dnd.Handle`, `onReorder`. |
+| [board.tsx](examples/board.tsx) | A ticket board: columns share one kind, so a ticket lands in another column at an exact position, and a full column refuses it before the release — `kind`, `canDrop`, `onReorder`. |
+| [drop-zones.tsx](examples/drop-zones.tsx) | Documents carried onto folders: a zone takes items by kind, a locked folder refuses before the release, the target flashes where the file landed — `Dnd.Draggable`, `Dnd.DropZone`, `canDrop`, `flashOnDrop`. |
+| [narrow.tsx](examples/narrow.tsx) | A row of status filters in a 320 px strip: tags reorder sideways and the strip scrolls when a tag is held near its edge — `axis`. |
+
+## Mistakes
+- No `Dnd.Root` above the screen → nothing drags. Mount it once at the app root.
+- A `Dnd.SortableItem` `id` that differs from `getId(item)` → the item never moves.
+- Rendering items yourself instead of through `renderItem` → the list cannot draw the gap or the optimistic order.
+- Using `index` as the id → ids must survive a reorder.
+- Styling a row from an ancestor selector (`.list .row`) → the flying clone loses it.
+- Starting a drag from a button inside a row without `handle` → presses on controls are theirs; use `Dnd.Handle`.
+- A drag-only move with no alternative → add a button or a menu for the same action.
+
+## Related
+- **Built from:** [Button](../button/COMPONENT.md)
+- **See also:** [FileUpload](../file-upload/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [Card](../card/COMPONENT.md)

package/src/components/dnd/examples/board.tsx

@@ -0,0 +1,83 @@
+/** A ticket board: columns share one kind, so a ticket lands in another column at an exact position, and a full column refuses it before the release — `kind`, `canDrop`, `onReorder`. */
+import { Badge, Dnd, moveBefore, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Status = "todo" | "doing" | "done";
+type Ticket = { id: string; title: string; status: Status };
+
+const COLUMNS: { status: Status; title: string }[] = [
+  { status: "todo", title: "К выполнению" },
+  { status: "doing", title: "В работе" },
+  { status: "done", title: "Готово" },
+];
+
+const WIP_LIMIT = 3;
+
+const TICKETS: Ticket[] = [
+  { id: "t1", title: "Починить загрузку аватара", status: "todo" },
+  { id: "t2", title: "Тёмная тема для таблиц", status: "todo" },
+  { id: "t3", title: "Экспорт отчёта в CSV", status: "doing" },
+  { id: "t4", title: "Обновить онбординг", status: "done" },
+  { id: "t5", title: "Фильтры в списке заказов", status: "doing" },
+];
+
+export default function DndBoardExample() {
+  const [tickets, setTickets] = React.useState(TICKETS);
+
+  // The ticket changes column and lands in front of `beforeId` (`null` = at the end).
+  const place = (id: string, status: Status, beforeId: string | null) =>
+    setTickets((current) =>
+      moveBefore(
+        current.map((ticket) => (ticket.id === id ? { ...ticket, status } : ticket)),
+        id,
+        beforeId,
+        (ticket) => ticket.id,
+      ),
+    );
+
+  return (
+    <Dnd.Root>
+      <div className={styles.board}>
+        {COLUMNS.map((column) => {
+          const inColumn = tickets.filter((ticket) => ticket.status === column.status);
+          return (
+            <section key={column.status} className={styles.column} aria-label={column.title}>
+              <div className={styles.columnHeader}>
+                <Typography as="h4" variant="title-s">
+                  {column.title}
+                </Typography>
+                <Badge.Root>{inColumn.length}</Badge.Root>
+              </div>
+              <Dnd.Sortable
+                kind="ticket"
+                aria-label={`Тикеты: ${column.title}`}
+                className={styles.cards}
+                items={inColumn}
+                getId={(ticket) => ticket.id}
+                getLabel={(ticket) => ticket.title}
+                canDrop={(id) =>
+                  column.status !== "doing" ||
+                  inColumn.length < WIP_LIMIT ||
+                  inColumn.some((ticket) => ticket.id === id)
+                }
+                onReorder={(id, beforeId) => place(id, column.status, beforeId)}
+                renderItem={(ticket) => (
+                  <Dnd.SortableItem id={ticket.id} className={styles.ticket}>
+                    <Typography as="span" variant="body-m">
+                      {ticket.title}
+                    </Typography>
+                    <Typography as="span" variant="caption" tone="muted">
+                      {ticket.id.toUpperCase()}
+                    </Typography>
+                  </Dnd.SortableItem>
+                )}
+              />
+            </section>
+          );
+        })}
+      </div>
+    </Dnd.Root>
+  );
+}