suaveplan/openspec/changes/enterprise-react-dnd/tasks.md

Tasks: enterprise-react-dnd

Change ID: enterprise-react-dnd Package: @suaveplan/react-dnd Target path: react/ui/react-dnd Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/types

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory tree per proposal layout.
• Write package.json at 0.1.0 with "sideEffects": false, exports map.
• Dependencies: @suaveplan/error workspace:^, @suaveplan/types workspace:^, zod catalog:forms, @opentelemetry/api catalog:observability, tslib catalog:build.
• Write tsconfig.json, vitest.config.ts, scripts.

---

2. Error codes and types

• Define DndError extending SuaveplanError; codes: DND_CONTEXT_MISSING, DND_INVALID_DROP_TYPE.
• Define all public types: DragData, DragState, DropEvent, DraggableProps, DroppableProps, SortableListProps, DndContextValue, DndContextProps, DndBackend.

---

3. Backends

HTML5 backend

• Uses dragstart, drag, dragend, dragover, drop events.
• Write test (jsdom supports HTML5 drag — verify event handlers wired), md.

Pointer backend

• Uses pointerdown, pointermove, pointerup events; calculates offset for visual ghost.
• Write test, md.

Keyboard backend

• Arrow keys select item; Space/Enter confirms drop; Escape cancels.
• prevent-in-input guard: no action when event.target is INPUT, TEXTAREA, or [contenteditable].
• Write test (keyboard sequence), md.

---

4. DndContext and DndProvider

• DndProvider — accepts backend prop ('html5' | 'pointer' | 'keyboard', default 'html5'). Initialises selected backend, exposes context.
• useContextDnd — throws DndError(DND_CONTEXT_MISSING) outside provider.
• Tracks activeDrag: DragState | null; emits OTel dnd.drop span on successful drop with dnd.drag_type + dnd.droppable_id.
• Write test + md.

---

5. Draggable

• Wires backend drag-start/end; applies aria-grabbed="true/false"; accepts data: DragData, type: string, disabled props.
• Write test, stories (default, disabled, playground), md.

---

6. Droppable

• Accepts acceptTypes: string[]; filters drag data by type; fires onDrop(event: DropEvent); applies aria-dropeffect; isOver state for hover UI.
• Throws DndError(DND_INVALID_DROP_TYPE) if acceptTypes is empty array.
• Write test, stories (default, type-filtered, playground), md.

---

7. SortableList

• Generic SortableList<T> — renders items array, wires each as Draggable + Droppable; calls onReorder(newItems: T[]) on drop.
• Keyboard backend support: arrow keys move focus, Space confirms reorder.
• Write test, stories (default, keyboard-reorder, large-list), md.

---

8. E2E

• e2e/dnd.spec.ts — Playwright:
  • HTML5: drag item to droppable, verify onDrop called (intercept via page evaluate).
  • Keyboard: Tab to draggable, Space to grab, Arrow key to reorder, Space to drop.
  • Type filter: drag wrong-type item to droppable, verify drop rejected.

---

9. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/react-dnd — green.
• bunx turbo test:coverage --filter=@suaveplan/react-dnd — 100%.
• bun scripts/publish.ts --package @suaveplan/react-dnd.
• Archive change folder.