Initial Commit
This commit is contained in:
85
openspec/changes/enterprise-react-dnd/proposal.md
Normal file
85
openspec/changes/enterprise-react-dnd/proposal.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# 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
|
||||
```
|
||||
98
openspec/changes/enterprise-react-dnd/tasks.md
Normal file
98
openspec/changes/enterprise-react-dnd/tasks.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user