# OpenSpec Change: enterprise-react-dnd

- **Change ID**: enterprise-react-dnd
- **Package**: `@suaveplan/react-dnd`
- **Category**: react
- **Target path**: `react/ui/react-dnd`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-dnd.md`

---

## Summary

Deliver `@suaveplan/react-dnd` on genesis from scratch at enterprise quality. A drag-and-drop kit for React with `DndProvider`/`DndContext`, `Draggable`, `Droppable`, and `SortableList`. Genesis upgrades from HTML5-only to a multi-backend architecture supporting HTML5, pointer events, and keyboard navigation; adds `@suaveplan/error`-backed errors, OTel span events, full Playwright E2E, and 100% coverage.

---

## Current-state audit (genesis)

Package does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `DndError` |
| `@suaveplan/types` (`workspace:^`) | Shared option types |
| `zod` (`catalog:forms`) | Config schemas |
| `@opentelemetry/api` (`catalog:observability`) | `dnd.drop` span |

External: `tslib catalog:build`. React 18 peer.

---

## Preserved public API surface

```ts
DndContext, DndProvider
Draggable           — aria-grabbed, draggable via HTML5/pointer/keyboard
Droppable           — type-filtered, aria-dropeffect, hover state
SortableList<T>     — auto-reorder wiring

// Types
DndContextProps, DndContextValue, DragData, DraggableProps,
DragState, DropEvent, DroppableProps, SortableListProps
```

---

## New additions for genesis

1. **Multi-backend**: HTML5 (default), pointer events (touch/stylus), keyboard (arrow keys + space/enter). Backend selected via `DndProvider` `backend` prop.
2. **`DndError`** — codes: `DND_CONTEXT_MISSING`, `DND_INVALID_DROP_TYPE`.
3. **`prevent-in-input` guard** — keyboard backend ignores keydown when a text input or contenteditable has focus.
4. **OTel `dnd.drop` span** — attributes: `dnd.drag_type`, `dnd.droppable_id`.
5. **Playwright E2E** — HTML5 drag, pointer-event drag, keyboard reorder.
6. **Stories** — `DndProvider` with `Draggable`+`Droppable` default, `SortableList` default, keyboard variant, playground.

---

## File layout

```text
react/ui/react-dnd/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    dnd-context/ (tsx + types + md + test + index)
    draggable/ (tsx + types + md + test + stories + index)
    droppable/ (tsx + types + md + test + stories + index)
    sortable-list/ (tsx + types + md + test + stories + index)
    backends/
      html5-backend/ (ts + md + test + index)
      pointer-backend/ (ts + md + test + index)
      keyboard-backend/ (ts + md + test + index)
    types/
      react-dnd.types.ts
  e2e/
    dnd.spec.ts
```