dnd-manager 1.2.0 → 1.3.0

package/README.md

@@ -1,18 +1,24 @@
 # dnd-manager
 
-Simple, performant, and data-driven Drag-and-Drop library for vanilla JS, compatible with any
-framework, and designed for developers who want full control over drag-and-drop UX without being
-locked into specific component patterns or opinionated libraries.
+Lightweight, data-driven drag-and-drop for vanilla JS and any framework. Full control over UX
+without opinionated component patterns.
 
-This document provides practical examples of using the library in both vanilla JavaScript and React
-applications.
+**Live demo:** [itsjavi.com/dnd-manager](https://itsjavi.com/dnd-manager) · **Source:**
+[demo/](demo/) in this repo · **LLM-optimized docs:** [llms.md](llms.md)
+
+---
 
 ## Table of Contents
 
-1. [Installation](#installation)
-2. [Clone Preview Helper](#clone-preview-helper)
-3. [Vanilla JavaScript Example](#vanilla-javascript-example)
-4. [React Example](#react-example)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Clone preview helper](#clone-preview-helper)
+- [Vanilla JS](#vanilla-js)
+- [React](#react)
+- [Multiple managers](#multiple-managers)
+- [Dynamic drag ability](#dynamic-drag-ability)
+- [Keyboard](#keyboard)
+- [API overview](#api-overview)
 
 ---
 
@@ -20,834 +26,350 @@ applications.
 
 ```bash
 pnpm add dnd-manager
-```
-
-Or with npm/yarn:
-
-```bash
-npm install dnd-manager
-yarn add dnd-manager
+# or: npm install dnd-manager
 ```
 
 ---
 
-## Clone Preview Helper
+## Quick start
 
-Use `new DragPreviewController()` to get a clone of the dragged element that follows the cursor with
-`position: fixed`, `pointer-events: none`, and transform-based movement.
+1. Mark draggable/droppable elements with `data-kind` (e.g. `data-kind="cell"`).
+2. Add position data (e.g. `data-row`, `data-col` for a grid).
+3. Create a `DragDropManager` with callbacks that read position/data and handle drag/drop.
 
 ```typescript
-import {
-  DragPreviewController,
-  DragDropManager,
-  type DragDropCallbacks,
-  type PointerPosition,
-} from 'dnd-manager'
-
-type Item = { index: number }
-type Position = { index: number }
-
-const preview = new DragPreviewController({
-  zIndex: 9999,
-  opacity: 0.95,
-  className: 'drop-shadow-xl',
-})
+import { DragDropManager, type DragDropCallbacks } from 'dnd-manager'
+
+type Item = { id: string; name: string }
+type Position = { row: number; col: number }
 
 const callbacks: DragDropCallbacks<Item, Position> = {
-  getItemPosition: (element) => {
-    const raw = element.dataset.index
-    if (!raw) return null
-    const index = Number.parseInt(raw, 10)
-    return Number.isFinite(index) ? { index } : null
+  getItemPosition: (el) => {
+    const row = el.dataset.row,
+      col = el.dataset.col
+    return row != null && col != null ? { row: +row, col: +col } : null
   },
-
-  getItemData: (_element, pos) => ({ index: pos.index }),
-
-  onDragStart: (element) => {
-    preview.startFromElement(element)
+  getItemData: (el, pos) => ({ id: el.dataset.itemId ?? '', name: el.dataset.name ?? '' }),
+  onDrop: (from, to, item) => {
+    /* swap/update DOM or state */
   },
-
-  onDragMove: (pos: PointerPosition) => {
-    preview.moveToPointer(pos)
-  },
-
-  onDragEnd: () => {
-    preview.stop()
+  onDragEnd: (result) => {
+    /* result or null; cleanup preview etc. */
   },
 }
 
 const manager = new DragDropManager<Item, Position>(
-  '#container',
-  {
-    draggableKind: 'ITEM',
-    droppableKind: 'ITEM',
-  },
+  document.querySelector('#container'),
+  { draggableKind: 'cell', droppableKind: 'cell' },
   callbacks,
 )
 
-// Important cleanup for unmount/page teardown.
-function cleanup() {
-  preview.destroy()
-  manager.destroy()
-}
+// On teardown:
+manager.destroy()
 ```
 
-This helper uses the clone-in-`document.body` pattern to avoid drift in scrolled containers and
-keeps cursor tracking smooth via transform updates.
+Elements with `data-empty` are not draggable. Use `onDragStart` / `onDragMove` to show a preview;
+use `onDragEnd(result)` for cleanup and optional reordering (see below).
 
 ---
 
-## Vanilla JavaScript Example
+## Clone preview helper
 
-This example creates a draggable grid with cells that can be reordered. Clicking a cell logs its
-data to the console, and dragging shows a preview element following the cursor.
+`DragPreviewController` gives a clone of the dragged element that follows the cursor
+(`position: fixed`, `pointer-events: none`). Reduces drift in scrolled containers.
 
-**HTML:**
+The clone is a picture of the source: it drops `id`, `name`, `data-kind` and the drag attributes
+(`data-dragging`, `data-hovered`, `data-drop-invalid`), so placeholder styles such as
+`[data-dragging] { opacity: .4 }` don't hit it, and it is `inert`. Style it with
+`[data-drag-preview]`. Appended to `document.body`, it loses descendant selectors (`.box .slot`) and
+custom properties inherited from the source's ancestors; copy what it needs with
+`copyComputedStyles` (e.g. `['--slot-bg']`), or render your own preview from `onDragStart` /
+`onDragMove` / `onDragEnd`.
 
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Vanilla JS DragDrop Grid</title>
-    <style>
-      body {
-        margin: 0;
-        padding: 20px;
-        font-family:
-          system-ui,
-          -apple-system,
-          sans-serif;
-        background: #f9fafb;
-      }
-
-      .grid {
-        display: grid;
-        grid-template-columns: repeat(3, 120px);
-        gap: 8px;
-        padding: 20px;
-      }
-
-      .cell {
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        font-weight: 600;
-        border-radius: 8px;
-        padding: 20px;
-        min-height: 80px;
-        transition:
-          transform 0.2s,
-          opacity 0.2s,
-          box-shadow 0.2s;
-        user-select: none;
-        touch-action: none;
-      }
-
-      .cell:not([data-empty]) {
-        color: white;
-        cursor: grab;
-      }
-
-      .cell[data-empty] {
-        background: #f3f4f6;
-        border: 2px dashed #d1d5db;
-      }
-
-      /* Dragging states */
-      .cell[data-dragging='true'] {
-        opacity: 0.4;
-        cursor: grabbing !important;
-      }
-
-      .cell[data-hovered='true'] {
-        transform: scale(1.05);
-        box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.5);
-      }
-
-      /* Drag preview */
-      #drag-preview {
-        position: fixed;
-        pointer-events: none;
-        z-index: 9999;
-        opacity: 0;
-        transform: translate(-50%, -50%);
-        transition: opacity 0.2s;
-        padding: 20px;
-        border-radius: 8px;
-        color: white;
-        font-weight: 600;
-        box-shadow: 0 10px 25px rgba(0, 0, 0, 0.3);
-      }
-    </style>
-  </head>
-  <body>
-    <h1>Vanilla JS Drag & Drop Grid</h1>
-    <p>Drag cells to reorder, click to log to console</p>
-
-    <div id="grid-container" class="grid">
-      <!-- Row 0 -->
-      <div
-        class="cell"
-        data-kind="cell"
-        data-row="0"
-        data-col="0"
-        data-item-id="1"
-        data-name="Item 1"
-        style="background: #ef4444"
-      >
-        Item 1
-      </div>
-      <div
-        class="cell"
-        data-kind="cell"
-        data-row="0"
-        data-col="1"
-        data-item-id="2"
-        data-name="Item 2"
-        style="background: #3b82f6"
-      >
-        Item 2
-      </div>
-      <div
-        class="cell"
-        data-kind="cell"
-        data-row="0"
-        data-col="2"
-        data-item-id="3"
-        data-name="Item 3"
-        style="background: #10b981"
-      >
-        Item 3
-      </div>
-
-      <!-- Row 1 -->
-      <div
-        class="cell"
-        data-kind="cell"
-        data-row="1"
-        data-col="0"
-        data-item-id="4"
-        data-name="Item 4"
-        style="background: #f59e0b"
-      >
-        Item 4
-      </div>
-      <div class="cell" data-kind="cell" data-row="1" data-col="1" data-empty></div>
-      <div
-        class="cell"
-        data-kind="cell"
-        data-row="1"
-        data-col="2"
-        data-item-id="5"
-        data-name="Item 5"
-        style="background: #8b5cf6"
-      >
-        Item 5
-      </div>
-
-      <!-- Row 2 -->
-      <div
-        class="cell"
-        data-kind="cell"
-        data-row="2"
-        data-col="0"
-        data-item-id="6"
-        data-name="Item 6"
-        style="background: #ec4899"
-      >
-        Item 6
-      </div>
-      <div
-        class="cell"
-        data-kind="cell"
-        data-row="2"
-        data-col="1"
-        data-item-id="7"
-        data-name="Item 7"
-        style="background: #14b8a6"
-      >
-        Item 7
-      </div>
-      <div class="cell" data-kind="cell" data-row="2" data-col="2" data-empty></div>
-    </div>
-
-    <!-- Drag preview element -->
-    <div id="drag-preview"></div>
-
-    <script type="module" src="./app.ts"></script>
-  </body>
-</html>
+```typescript
+import { DragPreviewController, DragDropManager, type DragDropCallbacks } from 'dnd-manager'
+
+const preview = new DragPreviewController({ zIndex: 9999, opacity: 0.95 })
+
+const callbacks: DragDropCallbacks<Item, Position> = {
+  getItemPosition: (el) => ({ index: Number(el.dataset.index) }),
+  getItemData: (el, pos) => ({ index: pos.index }),
+  onDragStart: (element) => preview.startFromElement(element),
+  onDragMove: (pos) => preview.moveToPointer(pos),
+  onDragEnd: () => preview.stop(),
+}
+
+const manager = new DragDropManager(
+  container,
+  { draggableKind: 'ITEM', droppableKind: 'ITEM' },
+  callbacks,
+)
+
+// Cleanup:
+preview.destroy()
+manager.destroy()
 ```
 
-**TypeScript (app.ts):**
+---
 
-```typescript
-import { DragDropManager, type DragDropCallbacks } from 'dnd-manager'
+## Vanilla JS
 
-// Types
-type GridItem = {
-  id: string
-  name: string
-  color: string
-}
+Use a container of elements with `data-kind`, `data-row`, `data-col`, and item fields
+(`data-item-id`, `data-name`, etc.). In callbacks:
 
-type GridPosition = {
-  row: number
-  col: number
-}
+- **getItemPosition** — parse position from data attributes.
+- **getItemData** — return item payload (e.g. id, name, color).
+- **onDragStart** — show preview (e.g. copy size/style to a fixed preview element).
+- **onDragMove** — update preview position (`left`/`top` or transform).
+- **onDrop** — swap/update DOM (or state) using source/target positions and `sourceItem`.
+- **onDragEnd(result)** — `result` is `{ sourcePosition, targetPosition, sourceItem }` on valid
+  drop, or `null` when cancelled. Use for cleanup (hide preview) and optionally do reordering here
+  instead of in `onDrop`.
+- **onClick** — handle click (e.g. log or select).
 
-// Initialize
-function initDragDropGrid(): void {
-  const container = document.getElementById('grid-container')
-  const preview = document.getElementById('drag-preview')
+Full grid markup and CSS are in the [demo app](demo/) (see `GridDemo` and styles). Minimal markup
+pattern:
 
-  if (!container || !preview) return
+```html
+<div id="grid-container">
+  <div class="cell" data-kind="cell" data-row="0" data-col="0" data-item-id="1" data-name="Item 1">
+    Item 1
+  </div>
+  <!-- ... more cells; use data-empty on empty slots -->
+</div>
+<div id="drag-preview"></div>
+```
 
-  // Setup DragDropManager callbacks
-  const callbacks: DragDropCallbacks<GridItem, GridPosition> = {
-    getItemPosition: (element, kind) => {
-      const row = element.dataset.row
-      const col = element.dataset.col
-      if (row === undefined || col === undefined) return null
-
-      return {
-        row: parseInt(row, 10),
-        col: parseInt(col, 10),
-      }
-    },
-
-    getItemData: (element, position) => {
-      const itemId = element.dataset.itemId
-      const name = element.dataset.name
-      const color = element.style.background
-
-      if (!itemId || !name || !color) return null
-
-      return {
-        id: itemId,
-        name: name,
-        color: color,
-      }
-    },
-
-    onDragStart: (element, position, item) => {
-      console.log('🚀 Drag started:', item)
-
-      // Copy element dimensions and styles to preview
-      const rect = element.getBoundingClientRect()
-      preview.textContent = item.name
-      preview.style.background = item.color
-      preview.style.width = `${rect.width}px`
-      preview.style.height = `${rect.height}px`
-      preview.style.opacity = '0.9'
-    },
-
-    onDragMove: (pos, hoveredElement) => {
-      // Update preview position
-      preview.style.left = `${pos.x}px`
-      preview.style.top = `${pos.y}px`
-    },
-
-    onDrop: (sourcePos, targetPos, sourceItem) => {
-      console.log('📦 Dropped:', {
-        from: sourcePos,
-        to: targetPos,
-        item: sourceItem,
-      })
-
-      // Get source and target elements
-      const sourceElement = container.querySelector(
-        `[data-row="${sourcePos.row}"][data-col="${sourcePos.col}"]`,
-      ) as HTMLElement
-      const targetElement = container.querySelector(
-        `[data-row="${targetPos.row}"][data-col="${targetPos.col}"]`,
-      ) as HTMLElement
-
-      if (!sourceElement || !targetElement) return
-
-      // Swap element contents and data attributes
-      const tempContent = sourceElement.innerHTML
-      const tempId = sourceElement.dataset.itemId
-      const tempName = sourceElement.dataset.name
-      const tempColor = sourceElement.style.background
-      const tempEmpty = sourceElement.dataset.empty
-
-      // Update source with target data
-      sourceElement.innerHTML = targetElement.innerHTML
-      sourceElement.dataset.itemId = targetElement.dataset.itemId || ''
-      sourceElement.dataset.name = targetElement.dataset.name || ''
-      sourceElement.style.background = targetElement.style.background
-      if (targetElement.dataset.empty !== undefined) {
-        sourceElement.dataset.empty = ''
-      } else {
-        delete sourceElement.dataset.empty
-      }
-
-      // Update target with source data
-      targetElement.innerHTML = tempContent
-      targetElement.dataset.itemId = tempId || ''
-      targetElement.dataset.name = tempName || ''
-      targetElement.style.background = tempColor
-      if (tempEmpty !== undefined) {
-        targetElement.dataset.empty = ''
-      } else {
-        delete targetElement.dataset.empty
-      }
-    },
-
-    onDragEnd: () => {
-      // Hide preview
-      preview.style.opacity = '0'
-    },
-
-    onClick: (element, position) => {
-      const itemId = element.dataset.itemId
-      const name = element.dataset.name
-      const color = element.style.background
-
-      if (itemId && name) {
-        console.log('👆 Clicked:', { id: itemId, name, color })
-      }
-    },
-  }
+### Reordering in `onDragEnd`
 
-  // Create DragDropManager instance
-  const dragDropManager = new DragDropManager<GridItem, GridPosition>(
-    container,
-    {
-      draggableKind: 'cell',
-      droppableKind: 'cell',
-      dragThreshold: 10,
-      clickThreshold: 10,
-      scrollThreshold: 100,
-      scrollSpeed: 10,
-      cancelOnEscape: true,
-      cancelOnPointerLeave: true,
-    },
-    callbacks,
-  )
+You can do all post-drag work in `onDragEnd` so cleanup and DOM/state updates stay in one place:
 
-  // Cleanup on page unload
-  window.addEventListener('beforeunload', () => {
-    dragDropManager.destroy()
-  })
+```typescript
+onDragEnd: (result) => {
+  if (result === null) return
+  const { sourcePosition, targetPosition, sourceItem } = result
+  // Update DOM or state (e.g. swap elements), then cleanup
+  swapElements(container, sourcePosition, targetPosition, sourceItem)
+  preview.style.opacity = '0'
 }
-
-// Start when DOM is ready
-document.addEventListener('DOMContentLoaded', initDragDropGrid)
 ```
 
 ---
 
-## React Example
+## React
 
-This example shows the same draggable grid implemented as a React component with TypeScript.
+Create the manager inside `useEffect` and clean up on unmount. Use state for grid data and preview;
+update state in `onDrop` (or `onDragEnd`). Keep `getItemData` reading from current state so the
+manager always has up-to-date item data.
 
 ```typescript
-import { useEffect, useRef, useState } from 'react'
-import { DragDropManager, type DragDropCallbacks } from 'dnd-manager'
+useEffect(() => {
+  if (!containerRef.current) return
+  const callbacks: DragDropCallbacks<GridItem, GridPosition> = {
+    getItemPosition: (el) => ({ row: +el.dataset.row!, col: +el.dataset.col! }),
+    getItemData: (_, pos) => gridData[pos.row][pos.col],
+    onDragStart: (el, _, item) => setDragPreview({ item, rect: el.getBoundingClientRect() }),
+    onDragMove: (pos) => setDragPreview((p) => (p ? { ...p, position: pos } : p)),
+    onDrop: (from, to, item) => setGridData((prev) => swap(prev, from, to, item)),
+    onDragEnd: () => setDragPreview(null),
+  }
+  const manager = new DragDropManager(
+    containerRef,
+    { draggableKind: 'cell', droppableKind: 'cell' },
+    callbacks,
+  )
+  return () => manager.destroy()
+}, [gridData])
+```
 
-// Types
-type GridItem = {
-  id: string
-  name: string
-  color: string
-}
+Render cells with `data-kind`, `data-row`, `data-col`, and item attributes; render a fixed-position
+preview from `dragPreview`. Full component and CSS: [demo app](demo/).
 
-type GridPosition = {
-  row: number
-  col: number
-}
+---
 
-// Initial data
-const INITIAL_DATA: (GridItem | null)[][] = [
-  [
-    { id: '1', name: 'Item 1', color: '#ef4444' },
-    { id: '2', name: 'Item 2', color: '#3b82f6' },
-    { id: '3', name: 'Item 3', color: '#10b981' },
-  ],
-  [
-    { id: '4', name: 'Item 4', color: '#f59e0b' },
-    null,
-    { id: '5', name: 'Item 5', color: '#8b5cf6' },
-  ],
-  [
-    { id: '6', name: 'Item 6', color: '#ec4899' },
-    { id: '7', name: 'Item 7', color: '#14b8a6' },
-    null,
-  ],
-]
-
-// Cell component
-type CellProps = {
-  item: GridItem | null
-  row: number
-  col: number
-} & React.ComponentProps<'div'>
-
-function GridCell({ item, row, col, ...props }: CellProps) {
-  if (item) {
-    return (
-      <div
-        data-kind="cell"
-        data-row={row}
-        data-col={col}
-        data-item-id={item.id}
-        className="grid-cell grid-cell--filled"
-        style={{
-          background: item.color,
-        }}
-        {...props}
-      >
-        {item.name}
-      </div>
-    )
-  }
+## Multiple managers
 
-  return (
-    <div
-      data-kind="cell"
-      data-row={row}
-      data-col={col}
-      data-empty="true"
-      className="grid-cell grid-cell--empty"
-      {...props}
-    />
-  )
-}
+Use two (or more) `DragDropManager` instances with **compatible `data-kind`** and a **shared
+callbacks** object. Ensure positions identify items globally (e.g. `{ containerId, itemId }`) so
+`onDrop` / `onDragEnd` can update both containers or shared state.
 
-// Drag preview component
-type DragPreviewProps = {
-  item: GridItem | null
-  position: { x: number; y: number } | null
-  width?: number
-  height?: number
-}
+`onDrop` runs on the manager where the drag **started**. `onDragEnd(result)` runs for every drag;
+`result` is the drop payload or `null`.
 
-function DragPreview({ item, position, width, height }: DragPreviewProps) {
-  if (!item || !position) return null
-
-  return (
-    <div
-      className="drag-preview"
-      style={{
-        left: position.x,
-        top: position.y,
-        background: item.color,
-        width: width ? `${width}px` : undefined,
-        height: height ? `${height}px` : undefined,
-      }}
-    >
-      {item.name}
-    </div>
-  )
+```typescript
+const callbacks: DragDropCallbacks<Item, Position> = {
+  getItemPosition: (el) => ({
+    containerId: el.closest('[data-container]')?.dataset.container as 'left' | 'right',
+    itemId: el.dataset.id!,
+  }),
+  getItemData: (el) => ({ id: el.dataset.id!, label: el.dataset.label! }),
+  onDrop: (sourcePos, targetPos, sourceItem) => {
+    // Update DOM or state for both source and target containers
+  },
 }
 
-// Main component
-export function DraggableGrid() {
-  const containerRef = useRef<HTMLDivElement>(null)
-  const [gridData, setGridData] = useState<(GridItem | null)[][]>(INITIAL_DATA)
-  const [dragPreview, setDragPreview] = useState<{
-    item: GridItem | null
-    position: { x: number; y: number } | null
-    width?: number
-    height?: number
-  }>({ item: null, position: null })
-
-  useEffect(() => {
-    if (!containerRef.current) return
-
-    // Setup callbacks
-    const callbacks: DragDropCallbacks<GridItem, GridPosition> = {
-      getItemPosition: (element, kind) => {
-        const row = element.dataset.row
-        const col = element.dataset.col
-        if (row === undefined || col === undefined) return null
-
-        return {
-          row: parseInt(row, 10),
-          col: parseInt(col, 10),
-        }
-      },
-
-      getItemData: (element, position) => {
-        return gridData[position.row][position.col]
-      },
-
-      onDragStart: (element, position, item) => {
-        console.log('🚀 Drag started:', item)
-
-        // Store element dimensions for preview
-        const rect = element.getBoundingClientRect()
-        setDragPreview({
-          item,
-          position: null,
-          width: rect.width,
-          height: rect.height,
-        })
-      },
-
-      onDragMove: (pos, hoveredElement) => {
-        setDragPreview((prev) => ({
-          ...prev,
-          position: pos,
-        }))
-      },
-
-      onDrop: (sourcePos, targetPos, sourceItem) => {
-        console.log('📦 Dropped:', {
-          from: sourcePos,
-          to: targetPos,
-          item: sourceItem,
-        })
-
-        // Swap items
-        setGridData((prevData) => {
-          const newData = prevData.map((row) => [...row])
-          const targetItem = newData[targetPos.row][targetPos.col]
-          newData[targetPos.row][targetPos.col] = sourceItem
-          newData[sourcePos.row][sourcePos.col] = targetItem
-          return newData
-        })
-      },
-
-      onDragEnd: () => {
-        setDragPreview({ item: null, position: null, width: undefined, height: undefined })
-      },
-
-      onClick: (element, position) => {
-        const item = gridData[position.row][position.col]
-        if (item) {
-          console.log('👆 Clicked:', item)
-        }
-      },
-    }
-
-    // Create manager
-    const manager = new DragDropManager<GridItem, GridPosition>(
-      containerRef,
-      {
-        draggableKind: 'cell',
-        droppableKind: 'cell',
-        dragThreshold: 10,
-        clickThreshold: 10,
-        scrollThreshold: 100,
-        scrollSpeed: 10,
-        cancelOnEscape: true,
-        cancelOnPointerLeave: true,
-      },
-      callbacks,
-    )
-
-    // Cleanup
-    return () => {
-      manager.destroy()
-    }
-  }, [gridData])
-
-  return (
-    <div className="draggable-grid-container">
-      <h1>React Drag & Drop Grid</h1>
-      <p>Drag cells to reorder, click to log to console</p>
-
-      <div ref={containerRef} className="grid">
-        {gridData.map((row, rowIndex) =>
-          row.map((item, colIndex) => (
-            <GridCell key={`${rowIndex}-${colIndex}`} item={item} row={rowIndex} col={colIndex} />
-          )),
-        )}
-      </div>
-
-      <DragPreview
-        item={dragPreview.item}
-        position={dragPreview.position}
-        width={dragPreview.width}
-        height={dragPreview.height}
-      />
-    </div>
-  )
-}
+const leftManager = new DragDropManager(
+  leftEl,
+  { draggableKind: 'cell', droppableKind: 'cell' },
+  callbacks,
+)
+const rightManager = new DragDropManager(
+  rightEl,
+  { draggableKind: 'cell', droppableKind: 'cell' },
+  callbacks,
+)
+// Cleanup: destroy both
 ```
 
-**CSS (Tailwind or plain CSS):**
+Drops land on any matching droppable in the page by default (`dropScope: 'document'`). For
+independent widgets that share kinds but must not exchange items, set `dropScope: 'container'`.
+Managers may also nest: a press inside an inner manager's container belongs to the inner manager
+only.
 
-```css
-/* Container */
-.draggable-grid-container {
-  padding: 20px;
-  font-family:
-    system-ui,
-    -apple-system,
-    sans-serif;
-}
+---
 
-/* Grid */
-.grid {
-  display: grid;
-  grid-template-columns: repeat(3, 120px);
-  gap: 8px;
-  padding: 20px;
-}
+## Dynamic drag ability
 
-/* Grid cells */
-.grid-cell {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-weight: 600;
-  border-radius: 8px;
-  transition:
-    transform 0.2s,
-    opacity 0.2s,
-    box-shadow 0.2s;
-  user-select: none;
-  touch-action: none;
-}
+Control whether an item can be dragged (e.g. by permissions or locked state) **without
+reinitializing** the manager.
 
-.grid-cell--filled {
-  padding: 20px;
-  color: white;
-  cursor: grab;
-  min-height: 80px;
-}
+- **`canDrag(element, position)`** — optional callback; called on every pointer down. Return `true`
+  to allow drag, `false` to block.
+- Keep the **callbacks object stable** and either:
+  - **Mutate** `callbacks.canDrag` when permissions/state change (vanilla), or
+  - Have **`canDrag` read from a ref or store** you update (e.g. in React) so the same manager
+    instance always sees current state.
 
-.grid-cell--empty {
-  background: #f3f4f6;
-  border: 2px dashed #d1d5db;
-  min-height: 80px;
-}
+**Vanilla:** update `canDrag` when state changes:
 
-/* Dragging state */
-.grid-cell[data-dragging='true'] {
-  opacity: 0.4;
-  cursor: grabbing !important;
+```typescript
+const callbacks = { getItemPosition, getItemData, canDrag: () => true }
+function setCanDrag(fn: (el: HTMLElement, pos: Position) => boolean) {
+  callbacks.canDrag = fn
 }
+setCanDrag((el, pos) => !getItemData(el, pos)?.locked && userCanEdit)
+const manager = new DragDropManager(container, config, callbacks)
+```
 
-/* Hover state */
-.grid-cell[data-hovered='true'] {
-  transform: scale(1.05);
-  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.5);
-}
+**React:** use a ref that always holds latest state; `canDrag` reads from it so the manager doesn’t
+need to be recreated when state changes.
 
-/* Drag preview */
-.drag-preview {
-  position: fixed;
-  pointer-events: none;
-  z-index: 9999;
-  transform: translate(-50%, -50%);
-  padding: 20px;
-  border-radius: 8px;
-  color: white;
-  font-weight: 600;
-  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.3);
-  opacity: 0.9;
-}
-```
+---
 
-**With Tailwind CSS:**
+## Keyboard
 
-```typescript
-// Update cell component to use Tailwind classes
-function GridCell({ item, row, col, ...props }: CellProps) {
-  if (item) {
-    return (
-      <div
-        data-kind="cell"
-        data-row={row}
-        data-col={col}
-        data-item-id={item.id}
-        className="flex items-center justify-center p-5 rounded-lg cursor-grab
-                   font-semibold text-white transition-all duration-200
-                   data-[dragging=true]:opacity-40 data-[dragging=true]:cursor-grabbing
-                   data-[hovered=true]:scale-105 data-[hovered=true]:ring-4
-                   data-[hovered=true]:ring-blue-500/50"
-        style={{ background: item.color }}
-        {...props}
-      >
-        {item.name}
-      </div>
-    )
-  }
+`keyboard: true` adds pick-and-place for keyboard users. Draggables must be focusable (a `<button>`,
+or `tabindex="0"`).
 
-  return (
-    <div
-      data-kind="cell"
-      data-row={row}
-      data-col={col}
-      data-empty="true"
-      className="bg-gray-100 border-2 border-dashed border-gray-300 rounded-lg min-h-[80px]"
-      {...props}
-    />
-  )
-}
+| Key             | Effect                                                                                 |
+| --------------- | -------------------------------------------------------------------------------------- |
+| Space / Enter   | On a focused draggable: pick it up. During the drag: drop on the target.               |
+| Arrow keys      | Move the target to the nearest droppable in that direction, scrolled into view.        |
+| Escape          | Cancel (also with `cancelOnEscape: false`; the key goes no further, e.g. to a dialog). |
+| Tab, focus loss | Cancel.                                                                                |
 
-// Drag preview with Tailwind
-function DragPreview({ item, position, width, height }: DragPreviewProps) {
-  if (!item || !position) return null
-
-  return (
-    <div
-      className="fixed pointer-events-none z-[9999] -translate-x-1/2 -translate-y-1/2
-                 p-5 rounded-lg text-white font-semibold shadow-2xl opacity-90"
-      style={{
-        left: position.x,
-        top: position.y,
-        background: item.color,
-        width: width ? `${width}px` : undefined,
-        height: height ? `${height}px` : undefined,
-      }}
-    >
-      {item.name}
-    </div>
-  )
-}
-```
+The same callbacks and attributes apply: `onDragStart`, `data-dragging` on the source,
+`data-hovered` / `data-drop-invalid` on the target, `onDragMove(targetCenter, target)` per move,
+`onDrop` and `onDragEnd`. A drop on a target `canDrop` rejects is ignored (the drag goes on). Focus
+stays on the source throughout; after a drop that moves the item, focus its new element in
+`onDragEnd`. `getState().input` tells a `'keyboard'` drag from a `'pointer'` one.
 
----
+Screen readers need words: announce from the callbacks into a live region, and describe the keys.
 
-## Covered Features
-
-### Both Examples Include:
-
-1. **Grid Layout** - 3x3 grid with draggable cells
-2. **Click Detection** - Logs item data to console on click
-3. **Drag Preview** - Visual feedback following cursor during drag, matching original element size
-4. **Swap Behavior** - Items swap positions on drop
-5. **Empty Cells** - Non-draggable placeholder cells
-6. **Visual Feedback** - Opacity changes, hover states, and scaling
-7. **TypeScript Types** - Full type safety with generics
-
-### DragDropManager Features Used:
-
-- `data-empty` convention - Elements with `data-empty` are automatically treated as non-draggable
-- `getItemPosition` - Extracts grid coordinates from data attributes
-- `getItemData` - Retrieves item data from grid state
-- `onDragStart` - Shows preview and updates source appearance
-  - Uses `getBoundingClientRect()` to copy element dimensions to preview
-- `onDragMove` - Updates preview position in real-time
-- `onDrop` - Swaps items and updates state
-- `onDragEnd` - Hides preview
-- `onClick` - Handles click/tap events
-
-### Configuration:
-
-- `draggableKind` / `droppableKind` - Accept `string` or `string[]` to match one or many kinds. Each
-  element should still expose a single `data-kind` value.
-- `dragThreshold: 10` - Prevents accidental drags
-- `clickThreshold: 10` - Distinguishes clicks from drags
-- `scrollThreshold: 100` - Auto-scroll near viewport edges
-- `scrollSpeed: 10` - Smooth scroll speed
-- `cancelOnEscape: true` - Cancels active drag when Escape is pressed
-- `cancelOnPointerLeave: true` - Cancels active drag if pointer leaves the window
+```typescript
+const live = document.querySelector('#dnd-status')! // <div id="dnd-status" aria-live="assertive">
 
----
+new DragDropManager(
+  grid,
+  { draggableKind: 'slot', droppableKind: 'slot', keyboard: true },
+  {
+    getItemPosition,
+    getItemData,
+    onDragStart: (_el, _pos, item) => (live.textContent = `Picked up ${item.name}.`),
+    onDragMove: (_pos, target) => (live.textContent = target?.getAttribute('aria-label') ?? ''),
+    onDragEnd: (result) => (live.textContent = result ? 'Dropped.' : 'Cancelled.'),
+  },
+)
+```
 
-## Notes
+---
 
-- **Performance**: The manager uses `requestAnimationFrame` for smooth updates at 60fps
-- **Mobile-Friendly**: Uses pointer events which work with touch, mouse, and pen
-- **Accessibility**: Uses data attributes that don't interfere with screen readers
-- **React Integration**: Manager is created in `useEffect` with proper cleanup
-- **State Management**: React example uses `useState` to trigger re-renders after drops
+## API overview
+
+### Callbacks
+
+| Callback                                              | Purpose                                                                                                                                                                              |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `getItemPosition(element, kind)`                      | Return position object from DOM (e.g. `{ row, col }`) or `null`.                                                                                                                     |
+| `getItemData(element, position)`                      | Return item data for the element at `position`.                                                                                                                                      |
+| `canDrag(element, position)`                          | Optional. Return `false` to block drag on this pointer down.                                                                                                                         |
+| `canDrop(sourcePosition, targetPosition, sourceItem)` | Optional. Return `false` to reject the droppable under the pointer (checked every frame and at the drop): it gets `data-drop-invalid`, and a drop there ends with `onDragEnd(null)`. |
+| `onDragStart(element, position, item)`                | Show preview, update source appearance.                                                                                                                                              |
+| `onDragMove(pointerPosition, hoveredElement)`         | Update preview position.                                                                                                                                                             |
+| `onDrop(sourcePosition, targetPosition, sourceItem)`  | Called when dropped on valid target; update DOM/state.                                                                                                                               |
+| `onDragEnd(result)`                                   | Always called when drag ends. `result` = `{ sourcePosition, targetPosition, sourceItem }` or `null`. Use for cleanup and optional reordering.                                        |
+| `onClick(element, position)`                          | Click/tap on draggable element.                                                                                                                                                      |
+
+### Manager config
+
+| Option                            | Description                                                                                              |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `draggableKind` / `droppableKind` | String or string[] to match `data-kind`.                                                                 |
+| `dragThreshold`                   | Pixels before drag starts (default 10).                                                                  |
+| `dragDelay`                       | Long press: ms to hold before the drag starts (default 0). A number, or per type: `{ touch: 250 }`.      |
+| `dragDelayTolerance`              | Pixels a press may move during `dragDelay` before it is released to the browser (default 5).             |
+| `clickThreshold`                  | Max movement to still count as click (default 10).                                                       |
+| `scrollThreshold`                 | Distance from a scroll container's or the viewport's edge to start auto-scroll (default 100).            |
+| `scrollSpeed`                     | Auto-scroll speed in px per frame (default 10, `0` disables it).                                         |
+| `cancelOnEscape`                  | Cancel drag on Escape (default true).                                                                    |
+| `cancelOnPointerLeave`            | Cancel when pointer leaves window (default true).                                                        |
+| `dropScope`                       | `'document'` (default): drop on matching droppables anywhere; `'container'`: only inside this container. |
+| `keyboard`                        | Keyboard pick-and-place (default false); see [Keyboard](#keyboard).                                      |
+| `focusOnPress`                    | A press focuses the draggable, as a click would (default false); see below.                              |
+
+### Conventions
+
+- **`data-kind`** — identifies draggable/droppable type; must match config.
+- **`data-empty`** — elements with this attribute are not draggable.
+- **Buttons** — only the main button of the primary pointer starts a drag; right-click (context
+  menus), middle-click and extra touches are left to the browser.
+- **`data-dragging`** — set to `"true"` on the source element during drag; removed on end/cancel.
+- **`data-hovered`** — set to `"true"` on the hovered droppable; removed when pointer leaves or drag
+  ends.
+- **`data-drop-invalid`** — set to `"true"` instead of `data-hovered` on a hovered droppable that
+  `canDrop` rejects (e.g. a full party, a locked box); style it as "not allowed".
+- **Preview** — implement in `onDragStart` / `onDragMove` / `onDragEnd`, or use
+  `DragPreviewController`.
+
+### Notes
+
+- Uses `requestAnimationFrame` for 60fps updates; pointer events work with touch, mouse, and pen.
+- **Focus.** By default a press on a draggable is cancelled (`preventDefault` on `pointerdown`),
+  which keeps the browser from selecting text or dragging an `<img>` or link natively, but also
+  keeps focus where it was. `focusOnPress: true` lets the press through and cancels `selectstart`
+  and `dragstart` while it is held instead: the draggable gets focus like a clicked button (no focus
+  ring for a mouse, per `:focus-visible`), so focus styles, keyboard follow-ups and a virtual list
+  that keeps its focused row rendered work with mouse drags too.
+- **Touch.** Once a touch press becomes a drag, the manager keeps the browser from panning and from
+  opening a long-press context menu, so the drag is not cancelled. It does so with a non-passive
+  `touchmove` listener on the container, in place before any touch starts (iOS Safari ignores one
+  added later), so touch scrolls that start inside the container wait for that small handler. A drag
+  also survives its source leaving the DOM mid-drag (a virtualized list unmounting the row), whose
+  touch and pointer events keep going to the detached element. Checked in Chromium and iOS Safari.
+  Without a delay, a swipe that starts on a draggable drags rather than scrolls. For lists that must
+  also scroll by touch, use a long press: `dragDelay: { touch: 250 }` — a quick swipe scrolls,
+  holding still for 250ms picks the item up. On iOS also add
+  `-webkit-touch-callout: none; user-select: none` to draggables.
+- Auto-scroll scrolls the closest scroll container under the pointer (`overflow: auto | scroll`)
+  that can still scroll toward the edge the pointer is near, nested ones first, and otherwise the
+  window. It keeps scrolling while the pointer rests in the edge zone, and re-checks the hovered
+  droppable after each step. A container's zone is at most a quarter of its size.
+- The native `click` the browser fires after the release that ends a drag (on the source element,
+  which holds pointer capture) is swallowed, so a draggable `<button>` or link is not activated by a
+  drop. A press that never became a drag clicks as usual.
+- While a press is held the manager follows `pointermove` on the whole window, so dragging out of
+  the container works even if the source element leaves the DOM mid-drag (a virtualized list
+  unmounting its row), which ends pointer capture. Re-render the source's state from your own data
+  (`onDragStart` / `onDragEnd`) if the row can come back as a new element.
+- React: create manager in `useEffect`, depend on grid state if `getItemData` uses it, and destroy
+  on cleanup.