prime-ui-kit 0.9.0 → 0.9.2

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:** interaction
+**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 and glides with the items as the landing spot moves; entering a connected list, it fades out in the list it left and in where it opens; crossing empty space (the gutter between lists) leaves the gap in the last list that takes the item; 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 over a target, or over empty space while a list holds the gap | 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>
+  );
+}

package/src/components/dnd/examples/drop-zones.tsx

@@ -0,0 +1,82 @@
+/** 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`. */
+import { Badge, Dnd, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Folder = "inbox" | "contracts" | "archive";
+type Paper = { id: string; title: string; folder: Folder };
+
+const FOLDERS: { id: Folder; title: string; locked?: boolean }[] = [
+  { id: "contracts", title: "Договоры" },
+  { id: "archive", title: "Архив (закрыт для записи)", locked: true },
+];
+
+const DOCUMENTS: Paper[] = [
+  { id: "d1", title: "Договор поставки № 14", folder: "inbox" },
+  { id: "d2", title: "Акт сверки за квартал", folder: "inbox" },
+  { id: "d3", title: "Счёт на оплату", folder: "inbox" },
+];
+
+export default function DndDropZonesExample() {
+  const [documents, setDocuments] = React.useState(DOCUMENTS);
+  const inFolder = (folder: Folder) => documents.filter((doc) => doc.folder === folder);
+
+  return (
+    <Dnd.Root>
+      <div className={styles.board}>
+        <section className={styles.column} aria-label="Входящие">
+          <div className={styles.columnHeader}>
+            <Typography as="h4" variant="title-s">
+              Входящие
+            </Typography>
+            <Badge.Root>{inFolder("inbox").length}</Badge.Root>
+          </div>
+          {inFolder("inbox").map((doc) => (
+            <Dnd.Draggable
+              key={doc.id}
+              kind="document"
+              id={doc.id}
+              label={doc.title}
+              className={styles.ticket}
+            >
+              <Typography as="span" variant="body-m">
+                {doc.title}
+              </Typography>
+            </Dnd.Draggable>
+          ))}
+        </section>
+        {FOLDERS.map((folder) => (
+          <Dnd.DropZone
+            key={folder.id}
+            as="section"
+            aria-label={folder.title}
+            accepts="document"
+            flashOnDrop
+            className={styles.column}
+            canDrop={() => !folder.locked}
+            onDrop={(item) =>
+              setDocuments((current) =>
+                current.map((doc) => (doc.id === item.id ? { ...doc, folder: folder.id } : doc)),
+              )
+            }
+          >
+            <div className={styles.columnHeader}>
+              <Typography as="h4" variant="title-s">
+                {folder.title}
+              </Typography>
+              <Badge.Root>{inFolder(folder.id).length}</Badge.Root>
+            </div>
+            {inFolder(folder.id).map((doc) => (
+              <div key={doc.id} className={styles.ticket}>
+                <Typography as="span" variant="body-m">
+                  {doc.title}
+                </Typography>
+              </div>
+            ))}
+          </Dnd.DropZone>
+        ))}
+      </div>
+    </Dnd.Root>
+  );
+}

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

@@ -0,0 +1,89 @@
+/* Layout of the Dnd scenarios: semantic tokens only. */
+
+.list {
+  width: 100%;
+  max-width: calc(var(--prime-space-24) * 4);
+}
+
+/* A row is a fill on the page, no outline: the fill reads as "a thing you can hold". */
+.row,
+.handleRow {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-3);
+  min-width: 0;
+  padding: var(--prime-space-3) var(--prime-space-4);
+  border-radius: var(--prime-radius-m);
+  background: var(--prime-color-card-bg);
+  box-shadow: var(--prime-card-shadow);
+}
+
+/* The grip sits closer to the edge: it is a square button with its own inner room. */
+.handleRow {
+  padding-inline-start: var(--prime-space-2);
+}
+
+.rowText {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.board {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, calc(var(--prime-space-24) * 2)), 1fr));
+  gap: var(--prime-space-4);
+  width: 100%;
+  min-width: 0;
+}
+
+.column {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-2);
+  min-height: calc(var(--prime-space-24) * 2);
+  padding: var(--prime-space-3);
+  border-radius: var(--prime-radius-l);
+  background: var(--prime-color-bg-sunken);
+}
+
+.columnHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: var(--prime-space-1) var(--prime-space-2);
+}
+
+.ticket {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-1);
+  padding: var(--prime-space-3) var(--prime-space-4);
+  border-radius: var(--prime-radius-m);
+  background: var(--prime-color-bg-surface);
+  box-shadow: var(--prime-shadow-raised);
+}
+
+/* The sortable area of a column fills it, so an empty column is still a drop target. */
+.cards {
+  flex: 1;
+  min-height: calc(var(--prime-space-24) * 1.5);
+}
+
+/* 320 px strip; the padding keeps room for the focus ring of the first and last tag. */
+.strip {
+  width: min(100%, calc(var(--prime-space-20) * 4));
+  padding: var(--prime-space-1);
+}
+
+.chips {
+  gap: var(--prime-space-2);
+  width: max-content;
+}
+
+/* The item takes the badge's own shape, so the gap and the focus ring match it. */
+.chip {
+  display: inline-flex;
+  border-radius: var(--prime-badge-m-radius);
+}

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

@@ -0,0 +1,53 @@
+/** Notification channels with switches: only the grip starts a drag, and the async save can roll the order back — `handle`, `Dnd.Handle`, `onReorder`. */
+import { Dnd, moveBefore, Switch, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Channel = { id: string; title: string; enabled: boolean };
+
+const CHANNELS: Channel[] = [
+  { id: "email", title: "Почта", enabled: true },
+  { id: "push", title: "Push-уведомления", enabled: true },
+  { id: "telegram", title: "Telegram", enabled: false },
+  { id: "sms", title: "SMS", enabled: false },
+];
+
+export default function DndHandleExample() {
+  const [channels, setChannels] = React.useState(CHANNELS);
+
+  return (
+    <Dnd.Root>
+      <Dnd.Sortable
+        as="ul"
+        handle
+        aria-label="Каналы по приоритету"
+        className={styles.list}
+        items={channels}
+        getId={(channel) => channel.id}
+        getLabel={(channel) => channel.title}
+        onReorder={async (id, beforeId) => {
+          await new Promise((resolve) => setTimeout(resolve, 300));
+          setChannels((current) => moveBefore(current, id, beforeId, (channel) => channel.id));
+        }}
+        renderItem={(channel) => (
+          <Dnd.SortableItem id={channel.id} className={styles.handleRow}>
+            <Dnd.Handle />
+            <Typography as="span" variant="body-m" className={styles.rowText}>
+              {channel.title}
+            </Typography>
+            <Switch.Root
+              aria-label={channel.title}
+              checked={channel.enabled}
+              onCheckedChange={(enabled) =>
+                setChannels((current) =>
+                  current.map((item) => (item.id === channel.id ? { ...item, enabled } : item)),
+                )
+              }
+            />
+          </Dnd.SortableItem>
+        )}
+      />
+    </Dnd.Root>
+  );
+}

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

@@ -0,0 +1,42 @@
+/** 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`. */
+import { Badge, Dnd, moveBefore, ScrollContainer } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const FILTERS = [
+  { id: "all", title: "Все заказы" },
+  { id: "new", title: "Новые" },
+  { id: "paid", title: "Оплаченные" },
+  { id: "shipping", title: "В доставке" },
+  { id: "done", title: "Доставленные" },
+  { id: "refund", title: "Возвраты" },
+];
+
+export default function DndNarrowExample() {
+  const [filters, setFilters] = React.useState(FILTERS);
+
+  return (
+    <Dnd.Root>
+      <ScrollContainer axis="horizontal" fade className={styles.strip}>
+        <Dnd.Sortable
+          axis="x"
+          as="ul"
+          aria-label="Порядок фильтров"
+          className={styles.chips}
+          items={filters}
+          getId={(filter) => filter.id}
+          getLabel={(filter) => filter.title}
+          onReorder={(id, beforeId) =>
+            setFilters((current) => moveBefore(current, id, beforeId, (filter) => filter.id))
+          }
+          renderItem={(filter) => (
+            <Dnd.SortableItem id={filter.id} className={styles.chip}>
+              <Badge.Root>{filter.title}</Badge.Root>
+            </Dnd.SortableItem>
+          )}
+        />
+      </ScrollContainer>
+    </Dnd.Root>
+  );
+}

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

@@ -0,0 +1,45 @@
+/** Project tasks reordered by dragging the whole row; one root above, the move applied with a helper — `Dnd.Root`, `Dnd.Sortable`, `onReorder`, `moveBefore`. */
+import { Dnd, moveBefore, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const TASKS = [
+  { id: "brief", title: "Согласовать бриф", due: "Сегодня" },
+  { id: "design", title: "Макеты главной страницы", due: "Завтра" },
+  { id: "build", title: "Вёрстка и интеграция", due: "Через 3 дня" },
+  { id: "review", title: "Ревью и правки", due: "Через неделю" },
+  { id: "launch", title: "Запуск", due: "Через 2 недели" },
+];
+
+export default function DndOverviewExample() {
+  const [tasks, setTasks] = React.useState(TASKS);
+
+  return (
+    <Dnd.Root>
+      <Dnd.Sortable
+        as="ul"
+        aria-label="Задачи проекта"
+        className={styles.list}
+        items={tasks}
+        getId={(task) => task.id}
+        getLabel={(task) => task.title}
+        onReorder={(id, beforeId) =>
+          setTasks((current) => moveBefore(current, id, beforeId, (task) => task.id))
+        }
+        renderItem={(task) => (
+          <Dnd.SortableItem id={task.id} className={styles.row}>
+            <span className={styles.rowText}>
+              <Typography as="span" variant="body-m" truncate>
+                {task.title}
+              </Typography>
+              <Typography as="span" variant="caption" tone="muted">
+                {task.due}
+              </Typography>
+            </span>
+          </Dnd.SortableItem>
+        )}
+      />
+    </Dnd.Root>
+  );
+}