prime-ui-kit 0.10.0 → 0.11.1

package/src/components/dnd/COMPONENT.md

@@ -7,14 +7,17 @@
 
 ## 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`).
+- Reordering tiles in a wrapping grid: photos, covers (`axis="grid"`).
+- Moving an item between lists to an exact position: a board of columns (several `Dnd.Sortable` with one `kind`; Alt + ← / → moves across from the keyboard).
+- A list with a pinned first row or a system item that must hold its place (`locked`).
+- Reordering the rows of a table of your own (`as="tbody"`; a group's heading row in `header`). For records in a [DataTable](../data-table/COMPONENT.md) use its `onReorder`.
 - 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.
+- Reordering a virtualized list → not covered: the engine measures the DOM, so only mounted items take part.
 
 ## Import
 ```tsx
@@ -25,12 +28,15 @@ import { Dnd, moveBefore } from "prime-ui-kit";
 ```
 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)
+│  ├─ header                     optional content before the items that never moves (a group's heading row)
+│  ├─ 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); a lock in a `locked` item
+│  ├─ empty                      the `empty` content while the list has no items
+│  └─ children                   optional content after the items that never moves (an add tile)
 ├─ 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.
+A drag in flight is drawn by `Dnd.Root` as a clone of the lifted element above every layer, following the pointer; an item without a fill of its own flies on the fill of the surface it was lifted from (`--prime-color-layer-current`). A refusal with a reason shows the reason in a chip under the clone. The page gets `data-dnd-active="mouse | touch | pen"` on `<html>` for the length of the gesture.
 
 ## API
 
@@ -45,34 +51,38 @@ No ref, no DOM of its own besides the portalled overlay and a visually hidden li
 | `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`.
+Generic `Dnd.Sortable<T>`; `ref` → `HTMLElement`. The list and its drop target: renders the items through `renderItem` and 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. |
+| `onReorder` | `(id: string, beforeId: string \| null) => void \| Promise<void>` | — (required) | Item `id` lands in front of `beforeId` (`null` = last); in linked lists `id` may come from another list. Apply it with `moveBefore`; return a promise to save on a server (a rejection moves the item back). |
+| `renderItem` | `(item: T, index: number) => ReactNode` | — (required) | Returns a `Dnd.SortableItem`. During a drag `index` is the place the item will have on release, so a shown position follows the gap. |
+| `children` | `ReactNode` | — | Content after the items that never moves and takes no drop position: an add tile at the end of a grid. Inside `ul` / `ol` it must be `li`. |
+| `axis` | `"x" \| "y" \| "grid"` | `"y"` | A column, a single row, or a wrapping grid (`display: grid`; the host sets the tracks and the cells' size, the gap takes a cell). Keyboard: Alt + ↑ / ↓ in a column, Alt + ← / → in a row and a grid. |
 | `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`. |
+| `kind` | `string` | `unique per list` | Lists sharing a `kind` exchange items (a board): by pointer at an exact position, by keyboard with Alt + the arrows across the axis. Name each list: the name is spoken on a move. |
+| `canDrop` | `(id: string) => boolean \| string` | — | Refuses an item by id: `false`, or a string that says why (spoken and shown under the carried copy). The list turns `danger` before the release. |
+| `empty` | `ReactNode` | — | Shown while the list has no items; fades out when a gap opens in the list, so the gap takes its place. |
+| `as` | `"div" \| "ul" \| "ol" \| "tbody"` | `"div"` | Root element; `ul` / `ol` render items as `li`, `tbody` as table rows `tr`. |
+| `header` | `ReactNode` | — | Content in front of the items that never moves and takes no drop position: the heading row of a group in a `tbody`. |
 | `…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.
+`ref` → `HTMLElement`. `<li>` inside `ul` / `ol`, `<tr>` inside `tbody`, `<div>` otherwise; throws outside `Dnd.Sortable`. One item of the list; presses on buttons, fields and links 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. |
+| `disabled` | `boolean` | `false` | This item cannot be dragged or moved (others may still move past it). |
+| `locked` | `boolean` | `false` | Holds its place: it does not move and nothing is put where it would shift it. Its `Dnd.Handle` turns into a lock. A pinned first row, a system column. |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "id">` | — | `className` (the row look: fill, radius, padding), `aria-labelledby` / `aria-describedby` (the visible title and description) and the other attributes. |
 
 ### 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.
+`ref` → `HTMLButtonElement`. The grip: a ghost icon-only `xs` Button; a press always starts the drag, Alt + arrows on it move its item. In a `locked` item it is a lock instead.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -80,7 +90,7 @@ Generic `Dnd.Sortable<T>`; `ref` → `HTMLElement`. Renders `<div>`, `<ul>` or `
 | `…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.
+Generic `Dnd.Draggable<TData>`; `ref` → `HTMLElement`. An item carried onto a `Dnd.DropZone`; stays in place, faded, while carried. Has no keyboard path: offer a button or a menu for the same move.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -102,7 +112,7 @@ Generic `Dnd.DropZone<TData>`; `ref` → `HTMLElement`. Renders the `as` element
 |---|---|---|---|
 | `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. |
+| `canDrop` | `(item: DragItem<TData>) => boolean \| string` | — | Refuses an item: `false`, or a string that says why (spoken, and shown under the carried copy); 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. |
@@ -119,12 +129,23 @@ Generic `Dnd.DropZone<TData>`; `ref` → `HTMLElement`. Renders the `as` element
 |---|---|---|---|
 | `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 | |
+| `grid` | a wrapping grid in reading order; the gap is a cell | photo galleries, tiles | |
+
+### as (Dnd.Sortable)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `div` | a flex column / row / grid of `div` items | most lists | yes |
+| `ul` · `ol` | the same with `li` items | a list that reads as one to assistive tech | |
+| `tbody` | table rows (`tr` items) in the table's own layout; the gap is a row across every column; the row flies inside a one-row copy of its table at its column widths | rows of a table (`axis="y"`) | |
 
 ### 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 |
+| `kind` shared | lists exchange items at an exact position; Alt + ← / → moves across | boards | unique per list |
+| `locked` (item) | a lock where the grip would be; the item holds its place, nothing moves past it | a pinned first row, a system column | `false` |
+| `empty` | a line of the list's own while it is empty; a gap opening takes its place | columns, lists that may run out | — |
+| `canDrop` → string | the refusal says why: live region and a chip under the clone | workflow rules a person must understand | — |
 | `flashOnDrop` | the zone flashes `accent-soft` after a drop | the eye must follow where the item went | `false` |
 
 ## States
@@ -133,16 +154,43 @@ Generic `Dnd.DropZone<TData>`; `ref` → `HTMLElement`. Renders the `as` element
 | 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 |
+| refused | `canDrop` returns `false` or a string | `data-dnd-reject`: `danger-soft` fill; the clone gets a dashed `danger` outline; a string is spoken once and shown in the tooltip's inverse chip under the clone (it fades in, `fast`) |
+| locked | `locked` on an item | `data-locked`; no `aria-roledescription` or shortcuts; `Dnd.Handle` is a lock; the gap never stands where it would shift the item, a keyboard step past it does not happen, and an item from another list takes the nearest free place after it |
+| empty | `empty` and no items | `data-dnd-empty` element in the list (an `li` with `role="presentation"` in `ul` / `ol`, a `div` otherwise); out of the flow and faded (`fast`) once a gap opens in the list |
 | 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`; the clone sets down into the look the item will have in place — its resting shadow, or under the mouse its hover look: the item gets `data-dnd-hover` until the pointer leaves it or presses, so a host styles its hover lift on `:is(:hover, [data-dnd-hover])` and the card never dips to flat and lifts again |
 | cancelled | Escape, a system-cancelled pointer | the clone flies back, nothing changes |
+| saving | `onReorder` returned a pending promise (a drop or a keyboard move) | the item stays drawn in its new place until the promise settles; apply the new order before resolving; a rejection glides it back over `base` |
+| moved from the keyboard | Alt + an arrow | the items glide to their new places over `base`, like during a drag |
 | 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.
+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, the flash, the reason chip and the empty fade are off.
+
+An item's own `onPointerDown` / `onKeyDown` run before the kit's: `preventDefault()` in them keeps the drag from starting. Presses on buttons, fields, links and `[data-dnd-ignore]` inside an item never start a drag. The browser's own drag of an image or a link inside an item or a `Dnd.Draggable` is stopped in the capture phase, so `onDragStart` on `Dnd.Draggable` is the kit's event.
+
+**Host attributes — the styling contract.** Style a host on these, never on the kit's classes:
+
+| Attribute | On | Means |
+|---|---|---|
+| `data-dnd-active="mouse \| touch \| pen"` | `<html>` | a drag is in flight (hide hover-only actions, stop snapping) |
+| `data-dnd-item`, `data-dnd-kind` | every draggable | its id and kind |
+| `data-lifted` | a sortable item | it is carried: out of the layout, the gap stands for it |
+| `data-dragging` | a `Dnd.Draggable` / a sortable list | it is carried (the source fades) / an item of the list is in the air |
+| `data-locked`, `data-disabled`, `data-handle` | an item | `locked`, `disabled`, the list has `handle` |
+| `data-dnd-hover` | an item that just landed under the mouse | style its hover on `:is(:hover, [data-dnd-hover])` |
+| `data-dnd-landing` | an item | hidden while the clone lands on it |
+| `data-axis` | a `Dnd.Sortable` | `x`, `y` or `grid` (a host widens its rule with it: `.gallery[data-axis]`) |
+| `data-dnd-over`, `data-dnd-reject` | a list or a zone | an accepted item is over it / the spot refuses it |
+| `data-dnd-flash` | a `Dnd.DropZone` | flashing after a drop (`flashOnDrop`) |
+| `data-dnd-gap`, `data-dnd-ghost` | the gap / a leaving gap's out-of-flow copy, fading out mid-drag | count cells without them (`:not([data-dnd-ghost])`) |
+| `data-dnd-empty` | the `empty` element | the list is empty |
+| `data-dnd-mirror` | a part the host marks | kept in step on the carried copy (a shown position from `renderItem`'s `index`; rolling digits roll) |
+| `data-dnd-ignore`, `data-dnd-handle` | a part the host marks | a press here never drags / always drags |
 
 ## 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.
+- The list gap is `--prime-space-2`; override it with `className` (widen the rule with `[data-axis]` so it wins: `.gallery[data-axis] { gap: … }`).
+- A grid (`axis="grid"`) is `display: grid`: the host sets the tracks (`grid-template-columns`) and the cells' size; the gap takes a cell, and a carried item resizes to the cell it would land in.
+- The reason chip stands `--prime-tooltip-offset` under the carried copy, start-aligned, at most `--prime-tooltip-max-width` wide.
+- 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 table row is the exception: it flies inside empty copies (`display: contents`) of its ancestors up to the nearest surface (`data-depth`), so the table's own cell styles still apply.
 - 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.
 
@@ -152,12 +200,16 @@ All motion is on the tokens (lift `fast`, glide and landing `base`, flash `slow`
 | Key | Action |
 |---|---|
 | `Tab` | Moves to the list items (with `handle`, to the grips). |
-| `Alt + ↑` · `Alt + ↓` | Moves the item one place (`axis="x"`: Alt + ← / →). |
+| `Alt + ↑` · `Alt + ↓` | Moves the item one place (`axis="x"` and `"grid"`: Alt + ← / → in the writing direction). |
+| `Alt + ←` · `Alt + →` | In lists sharing a `kind`: moves the item to the same row of the neighbouring list (`axis="x"`: Alt + ↑ / ↓); focus follows. |
 | `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`.
+- A live region (`role="status"`, `aria-live="polite"`) announces grabbed, dropped, returned, cancelled, «position N of M», a move to another list by its name and a refusal with its reason, from `labels`.
+- Every draggable item has `aria-roledescription` and `aria-keyshortcuts` (with the across keys in linked lists) and is in the tab order (`tabIndex={0}`); with `handle` the grip takes focus instead. The clone is `aria-hidden`.
+- In lists sharing a `kind`, Alt + the across arrows move the item to the same row of the neighbouring list in document order; focus follows the item.
+- Name an item by what it shows: `aria-labelledby` on its visible title and `aria-describedby` on its description. An `aria-label` on the item replaces its content for assistive tech — use it only when the item shows no text (a photo tile). Name every linked list (`aria-label` or `aria-labelledby` on its heading): that name is spoken when an item moves into it.
+- A `locked` item has no role description or shortcuts; its `Dnd.Handle` is a lock: a `<span role="img">` named `labels.locked` with the `status.locked` icon at the grip's size (no ref).
 - 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.
 
@@ -167,20 +219,26 @@ All motion is on the tokens (lift `fast`, glide and landing `base`, flash `slow`
 | Key | Default | Used for |
 |---|---|---|
 | `handle` | `"Перетащить"` | Name of `Dnd.Handle`. |
+| `locked` | `"Закреплено"` | Name of the lock a `Dnd.Handle` shows in a `locked` item. |
 | `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. |
+| `movedTo` | `"{label}: «{list}», позиция {position} из {total}"` | Live region: moved to a linked list with the keyboard; `{list}` is its accessible name. |
+| `refused` | `"{label}: «{list}» не принимает элемент"` | Live region: a linked list refused a keyboard move (`canDrop` answered `false`). |
+| `refusedReason` | `"{label}: {reason}"` | Live region: a target refused the item and said why (`canDrop` answered a string). |
 
 ## 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`. |
+| [grid.tsx](examples/grid.tsx) | Product photos in a wrapping grid: a photo carried across rows lands in reading order, the gap takes a cell, Alt + ← / → steps it one place — `axis`. |
+| [locked.tsx](examples/locked.tsx) | Sections of a workspace menu: the home section is pinned first with a lock in place of its grip, the rest reorder around nothing past it; each row is named by its visible title — `locked`, `handle`, `aria-labelledby`. |
+| [board.tsx](examples/board.tsx) | A ticket board: columns share one kind, so a ticket lands in another column at an exact position or moves there with Alt + ← / →, an empty column says so, and a full column refuses it before the release with the reason under the ticket — `kind`, `canDrop`, `empty`, `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 and says why under the carried file, 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
@@ -191,7 +249,12 @@ All motion is on the tokens (lift `fast`, glide and landing `base`, flash `slow`
 - 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.
+- `aria-label` on an item that shows a title and a description → it hides them; point `aria-labelledby` / `aria-describedby` at them.
+- `draggable={false}` on every image inside an item → not needed: the kit stops the browser's own drag inside its items.
+- A pinned row kept first by re-sorting the array after every move → `locked` on its item.
+- An empty-list message rendered next to the list → pass it as `empty`: the gap takes its place while an item is over the list.
+- `canDrop` returning `false` where the rule is not obvious → return the reason as a string.
 
 ## Related
-- **Built from:** [Button](../button/COMPONENT.md)
-- **See also:** [FileUpload](../file-upload/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [Card](../card/COMPONENT.md)
+- **Built from:** [Button](../button/COMPONENT.md), `Icon` (`action.drag` for the grip, `status.locked` for a locked item's lock)
+- **See also:** [Kanban](../kanban/COMPONENT.md), [DataTable](../data-table/COMPONENT.md) (`onReorder`), [FileUpload](../file-upload/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [Card](../card/COMPONENT.md)

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

@@ -1,4 +1,4 @@
-/** 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`. */
+/** A ticket board: columns share one kind, so a ticket lands in another column at an exact position or moves there with Alt + ← / →, an empty column says so, and a full column refuses it before the release with the reason under the ticket — `kind`, `canDrop`, `empty`, `onReorder`. */
 import { Badge, Dnd, moveBefore, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -19,7 +19,6 @@ 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" },
 ];
 
@@ -42,25 +41,34 @@ export default function DndBoardExample() {
       <div className={styles.board}>
         {COLUMNS.map((column) => {
           const inColumn = tickets.filter((ticket) => ticket.status === column.status);
+          const headingId = `board-${column.status}`;
           return (
-            <section key={column.status} className={styles.column} aria-label={column.title}>
+            <section key={column.status} className={styles.column}>
               <div className={styles.columnHeader}>
-                <Typography as="h4" variant="title-s">
+                <Typography as="h4" variant="title-s" id={headingId}>
                   {column.title}
                 </Typography>
                 <Badge.Root>{inColumn.length}</Badge.Root>
               </div>
               <Dnd.Sortable
                 kind="ticket"
-                aria-label={`Тикеты: ${column.title}`}
+                // Named by the visible heading: the live region says «В работе» on a move.
+                aria-labelledby={headingId}
                 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)
+                  column.status === "doing" &&
+                  inColumn.length >= WIP_LIMIT &&
+                  !inColumn.some((ticket) => ticket.id === id)
+                    ? `В работе уже ${WIP_LIMIT} тикета`
+                    : true
+                }
+                empty={
+                  <Typography as="p" variant="body-s" tone="muted" className={styles.empty}>
+                    Нет тикетов
+                  </Typography>
                 }
                 onReorder={(id, beforeId) => place(id, column.status, beforeId)}
                 renderItem={(ticket) => (

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

@@ -1,4 +1,4 @@
-/** 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`. */
+/** Documents carried onto folders: a zone takes items by kind, a locked folder refuses before the release and says why under the carried file, 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";
 
@@ -54,7 +54,7 @@ export default function DndDropZonesExample() {
             accepts="document"
             flashOnDrop
             className={styles.column}
-            canDrop={() => !folder.locked}
+            canDrop={() => (folder.locked ? "Архив только для чтения" : true)}
             onDrop={(item) =>
               setDocuments((current) =>
                 current.map((doc) => (doc.id === item.id ? { ...doc, folder: folder.id } : doc)),

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

@@ -71,6 +71,29 @@
   min-height: calc(var(--prime-space-24) * 1.5);
 }
 
+/* grid.tsx: the host sets the tracks of a wrapping grid; the gap takes a cell. */
+.gallery[data-axis] {
+  grid-template-columns: repeat(auto-fill, minmax(calc(var(--prime-space-24) * 1.25), 1fr));
+  gap: var(--prime-space-3);
+  width: 100%;
+  max-width: calc(var(--prime-space-24) * 6);
+}
+
+/* A tile is its photo: the item takes the thumbnail's radius, so the gap and the ring match it. */
+.tile {
+  display: flex;
+  border-radius: var(--prime-thumbnail-m-radius);
+}
+
+/* An empty column's line: a dashed «put it here» slot, like the gap that replaces it. */
+.empty {
+  margin: 0;
+  padding: var(--prime-space-4);
+  border: var(--prime-border-width) dashed var(--prime-color-fill-strong);
+  border-radius: var(--prime-radius-m);
+  text-align: center;
+}
+
 /* 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));

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

@@ -0,0 +1,48 @@
+/** Product photos in a wrapping grid: a photo carried across rows lands in reading order, the gap takes a cell, Alt + ← / → steps it one place — `axis`. */
+import { Dnd, Icon, moveBefore, Thumbnail } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Photo = { id: string; title: string };
+
+const PHOTOS: Photo[] = [
+  { id: "chair-front", title: "Кресло спереди" },
+  { id: "chair-side", title: "Кресло сбоку" },
+  { id: "chair-back", title: "Кресло сзади" },
+  { id: "chair-detail", title: "Подлокотник" },
+  { id: "chair-base", title: "Крестовина" },
+  { id: "chair-box", title: "Упаковка" },
+  { id: "chair-room", title: "В интерьере" },
+];
+
+export default function DndGridExample() {
+  const [photos, setPhotos] = React.useState(PHOTOS);
+
+  return (
+    <Dnd.Root>
+      <Dnd.Sortable
+        as="ul"
+        axis="grid"
+        aria-label="Фото товара по порядку"
+        className={styles.gallery}
+        items={photos}
+        getId={(photo) => photo.id}
+        getLabel={(photo) => photo.title}
+        onReorder={(id, beforeId) =>
+          setPhotos((current) => moveBefore(current, id, beforeId, (photo) => photo.id))
+        }
+        renderItem={(photo) => (
+          <Dnd.SortableItem id={photo.id} className={styles.tile} aria-label={photo.title}>
+            <Thumbnail.Root fullWidth ratio="1:1">
+              <Thumbnail.Image src={`https://picsum.photos/seed/${photo.id}/320/320`} />
+              <Thumbnail.Fallback>
+                <Icon name="object.image" />
+              </Thumbnail.Fallback>
+            </Thumbnail.Root>
+          </Dnd.SortableItem>
+        )}
+      />
+    </Dnd.Root>
+  );
+}

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

@@ -9,7 +9,7 @@ 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: "slack", title: "Slack", enabled: false },
   { id: "sms", title: "SMS", enabled: false },
 ];
 
@@ -27,7 +27,12 @@ export default function DndHandleExample() {
         getId={(channel) => channel.id}
         getLabel={(channel) => channel.title}
         onReorder={async (id, beforeId) => {
-          await new Promise((resolve) => setTimeout(resolve, 300));
+          await new Promise((resolve) => setTimeout(resolve, 600));
+          // The server refuses to put a switched-off channel first: the row glides back.
+          const moved = channels.find((channel) => channel.id === id);
+          if (moved && !moved.enabled && beforeId === channels[0]?.id) {
+            throw new Error("Выключенный канал не может быть первым");
+          }
           setChannels((current) => moveBefore(current, id, beforeId, (channel) => channel.id));
         }}
         renderItem={(channel) => (

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

@@ -0,0 +1,57 @@
+/** Sections of a workspace menu: the home section is pinned first with a lock in place of its grip, the rest reorder around nothing past it; each row is named by its visible title — `locked`, `handle`, `aria-labelledby`. */
+import { Dnd, moveBefore, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Section = { id: string; title: string; description: string; pinned?: boolean };
+
+const SECTIONS: Section[] = [
+  { id: "home", title: "Главная", description: "Всегда первая в меню", pinned: true },
+  { id: "orders", title: "Заказы", description: "Новые и в работе" },
+  { id: "invoices", title: "Счета", description: "Выставленные и оплаченные" },
+  { id: "clients", title: "Клиенты", description: "Компании и контакты" },
+  { id: "reports", title: "Отчёты", description: "Продажи и склад" },
+];
+
+export default function DndLockedExample() {
+  const [sections, setSections] = React.useState(SECTIONS);
+  const uid = React.useId();
+
+  return (
+    <Dnd.Root>
+      <Dnd.Sortable
+        as="ul"
+        handle
+        aria-label="Порядок разделов меню"
+        className={styles.list}
+        items={sections}
+        getId={(section) => section.id}
+        getLabel={(section) => section.title}
+        onReorder={(id, beforeId) =>
+          setSections((current) => moveBefore(current, id, beforeId, (section) => section.id))
+        }
+        renderItem={(section) => (
+          <Dnd.SortableItem
+            id={section.id}
+            locked={section.pinned ?? false}
+            className={styles.handleRow}
+            // Named and described by what it shows: `aria-label` here would hide the row's text.
+            aria-labelledby={`${uid}-${section.id}`}
+            aria-describedby={`${uid}-${section.id}-note`}
+          >
+            <Dnd.Handle aria-label={`Переместить раздел «${section.title}»`} />
+            <span className={styles.rowText}>
+              <Typography as="span" variant="body-m" id={`${uid}-${section.id}`}>
+                {section.title}
+              </Typography>
+              <Typography as="span" variant="caption" tone="muted" id={`${uid}-${section.id}-note`}>
+                {section.description}
+              </Typography>
+            </span>
+          </Dnd.SortableItem>
+        )}
+      />
+    </Dnd.Root>
+  );
+}

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

@@ -18,7 +18,7 @@ export default function DndNarrowExample() {
 
   return (
     <Dnd.Root>
-      <ScrollContainer axis="horizontal" fade className={styles.strip}>
+      <ScrollContainer axis="horizontal" className={styles.strip}>
         <Dnd.Sortable
           axis="x"
           as="ul"