187 lines
6.0 KiB
Markdown
187 lines
6.0 KiB
Markdown
# OpenSpec Change: enterprise-browser-react-kanban
|
|
|
|
- **Change ID**: enterprise-browser-react-kanban
|
|
- **Package**: `@suaveplan/react-kanban`
|
|
- **Category**: browser
|
|
- **Target path**: `browser/react/react-kanban`
|
|
- **Status**: IN PROGRESS
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-kanban.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/react-kanban` on the genesis branch at enterprise quality. The package provides a headless `useKanban` hook with pure helpers (`findCardColumn`, `isColumnAtWipLimit`, `moveCardInBoard`, `moveColumnInBoard`, `validateMove`), plus reference `Board`, `Column`, `Card` components with Storybook stories. Genesis fixes the broken export map (missing `./core/column/column` and `./core/card/card` source files), splits the over-cap `board.ts` (320 lines) and `board.test.ts` (541 lines), adds Zod schemas for board state, OTel metrics, keyboard-drag support, and axe-core clean stories. No `react-dom` in runtime deps.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Fresh build — does not exist on genesis yet.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | `WIP_LIMIT_EXCEEDED`, `INVALID_MOVE`, `CARD_NOT_FOUND` |
|
|
| `@suaveplan/logger` (`workspace:^`) | Structured logging |
|
|
| `@suaveplan/schema-registry` (`workspace:^`) | Board / card schema registration |
|
|
| `zod` (`catalog:forms`) | Board, column, card Zod schemas |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Move / WIP-violation metrics |
|
|
| `tslib` (`catalog:build`) | Runtime helpers |
|
|
|
|
Dev: `vitest`, `@vitest/coverage-istanbul`, `happy-dom`, `@testing-library/react`, `@suaveplan/testing`, `@suaveplan/testing-dom`.
|
|
|
|
No `react-dom` in runtime `dependencies` — peer only.
|
|
|
|
---
|
|
|
|
## Preserved public API surface
|
|
|
|
```ts
|
|
// Hook
|
|
function useKanban(config: KanbanConfig): [KanbanState, KanbanActions]
|
|
|
|
// Pure helpers
|
|
function findCardColumn(board: KanbanBoard, cardId: string): KanbanColumn | null
|
|
function isColumnAtWipLimit(column: KanbanColumn): boolean
|
|
function moveCardInBoard(board: KanbanBoard, source: DragSource, dest: DropTarget): KanbanBoard
|
|
function moveColumnInBoard(board: KanbanBoard, fromIdx: number, toIdx: number): KanbanBoard
|
|
function validateMove(board: KanbanBoard, source: DragSource, dest: DropTarget): MoveResult
|
|
|
|
// Reference components (new)
|
|
function Board(props: BoardProps): JSX.Element
|
|
function Column(props: ColumnProps): JSX.Element
|
|
function Card(props: CardProps): JSX.Element
|
|
|
|
// Types
|
|
interface KanbanBoard { columns: KanbanColumn[] }
|
|
interface KanbanColumn { id: string; title: string; wipLimit?: number; cards: KanbanCard[] }
|
|
interface KanbanCard<T = unknown> { id: string; title: string; data?: T }
|
|
interface KanbanConfig { board: KanbanBoard; onMove?(src: DragSource, dst: DropTarget): void; enforceWipLimits?: boolean }
|
|
interface KanbanState { board: KanbanBoard; dragging: DragSource | null }
|
|
interface KanbanActions { moveCard(src: DragSource, dst: DropTarget): MoveResult; moveColumn(from: number, to: number): void }
|
|
```
|
|
|
|
Subpath exports: `"."`, `"./core/board/board"`, `"./core/column/column"`, `"./core/card/card"`, `"./utils/drag-drop"`, `"./components/board"`.
|
|
|
|
---
|
|
|
|
## New additions for genesis
|
|
|
|
### 1. Implement the missing `Column` and `Card` modules
|
|
|
|
Main-branch exported `./core/column/column` and `./core/card/card` from `package.json` but had no source files. Genesis ships `src/core/column/column.ts` and `src/core/card/card.ts` with typed interfaces, helpers, and tests.
|
|
|
|
### 2. Split `board.ts` and `board.test.ts`
|
|
|
|
`board.ts` (320 lines) → `board.ts` + `moves.ts` + `wip.ts` + `swimlanes.ts`, each ≤ 300 lines. `board.test.ts` (541 lines) → split by responsibility: `board.test.ts`, `moves.test.ts`, `wip.test.ts`, each ≤ 500 lines.
|
|
|
|
### 3. Reference `Board`, `Column`, `Card` components + stories
|
|
|
|
`src/components/` — reference visual components built on `useKanban`. Stories: default, playground, WIP-limit enforcement, swimlane grouping.
|
|
|
|
### 4. Keyboard-drag support
|
|
|
|
Arrow-key move (card left/right/up/down) wired in `useKanban`; reference components respect it. Axe-core clean.
|
|
|
|
### 5. Zod schemas
|
|
|
|
`KanbanBoardSchema`, `KanbanColumnSchema`, `KanbanCardSchema` registered in `@suaveplan/schema-registry`.
|
|
|
|
### 6. OTel metrics
|
|
|
|
Counter `kanban.move_total{success}`, counter `kanban.wip_violation_total`, histogram `kanban.move_latency_ms`.
|
|
|
|
### 7. Error codes
|
|
|
|
`WIP_LIMIT_EXCEEDED`, `INVALID_MOVE`, `CARD_NOT_FOUND`.
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
browser/react/react-kanban/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
core/
|
|
board/
|
|
board.ts (useKanban hook, ≤300 lines)
|
|
board.test.ts
|
|
board.md
|
|
moves.ts (move helpers)
|
|
moves.test.ts
|
|
wip.ts (WIP-limit enforcement)
|
|
wip.test.ts
|
|
swimlanes.ts (swimlane grouping)
|
|
swimlanes.test.ts
|
|
index.ts
|
|
column/
|
|
column.ts
|
|
column.test.ts
|
|
column.md
|
|
column.types.ts
|
|
index.ts
|
|
card/
|
|
card.ts
|
|
card.test.ts
|
|
card.md
|
|
card.types.ts
|
|
index.ts
|
|
components/
|
|
board/
|
|
board.tsx
|
|
board.stories.tsx
|
|
board.test.tsx
|
|
board.md
|
|
index.ts
|
|
column/
|
|
column.tsx
|
|
column.stories.tsx
|
|
column.test.tsx
|
|
column.md
|
|
index.ts
|
|
card/
|
|
card.tsx
|
|
card.stories.tsx
|
|
card.test.tsx
|
|
card.md
|
|
index.ts
|
|
utils/
|
|
drag-drop/
|
|
drag-drop.ts
|
|
drag-drop.test.ts
|
|
drag-drop.md
|
|
index.ts
|
|
schema/
|
|
board-schema/
|
|
board-schema.ts
|
|
board-schema.md
|
|
index.ts
|
|
types/
|
|
common.ts
|
|
common.md
|
|
constants/
|
|
index.ts
|
|
tests/
|
|
integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
**Downstream**: any Suaveplan browser app with a kanban board.
|
|
|
|
**Breaking changes**: None — new components and modules are additive. `board.ts` split is internal.
|
|
|
|
**Prerequisites**: `@suaveplan/error`, `@suaveplan/schema-registry` on Verdaccio.
|