# Tasks: enterprise-react-data-table

**Change ID**: enterprise-react-data-table
**Package**: `@suaveplan/react-data-table`
**Target path**: `react/ui/react-data-table`
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/react-ui`, `@suaveplan/react-virtual`, `@suaveplan/react-translate`, `@suaveplan/pagination`

---

## 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, correct deps/devDeps.
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library-browser.json`.
- [ ] Write `vitest.config.ts` using `createTestConfig()`.
- [ ] Add scripts: `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check`.

---

## 2. Types and error codes

- [ ] Define `DataTableError` extending `SuaveplanError` from `@suaveplan/error`; error codes: `DATA_TABLE_FETCH_FAILED`, `DATA_TABLE_EXPORT_FAILED`, `DATA_TABLE_INVALID_COLUMN`.
- [ ] Write types file: `DataTableColumn<TRow>`, `DataTableOptions<TRow>`, `DataTableState<TRow>`, `DataTableColumnDef<TRow>`, `DataSource<TRow>`, `SortDirection`, `FilterOperator`, `RowSelectionMode`, `PinDirection`.
- [ ] Write Zod `DataTableColumnDefSchema` for runtime column-def validation.

---

## 3. Core — `useDataTable` hook

- [ ] Implement `useDataTable<TRow>(options)`:
  - Internal state: `data: TRow[]`, `sortBy`, `sortDir`, `filters`, `page`, `pageSize`, `selectedRows`, `columnVisibility`, `columnPinning`.
  - Exposes: `rows`, `totalRows`, `sort(col, dir)`, `filter(col, op, val)`, `clearFilters()`, `setPage(n)`, `setPageSize(n)`, `toggleRow(id)`, `selectAll()`, `clearSelection()`, `toggleColumn(id)`, `pinColumn(id, side)`.
  - Calls `options.dataSource.fetch(params)` on any state change; wraps in `DataTableError` with code `DATA_TABLE_FETCH_FAILED` on throw.
  - Emits OTel span `data_table.sort` / `data_table.filter` / `data_table.page` via `@opentelemetry/api`.
- [ ] Write `use-data-table.test.ts`: sort, filter, page, selection, column visibility — all branches. `{ timeout: 30000 }` on async tests.
- [ ] Write `use-data-table.md`.

---

## 4. Core — `DataSource`

- [ ] Define `DataSource<TRow>` interface: `fetch(params: FetchParams): Promise<{ rows: TRow[]; total: number }>`.
- [ ] Implement `MemoryDataSource<TRow>` — in-memory sort/filter/page over a static array. Used in tests and stories.
- [ ] Write `data-source.test.ts`: fetch with sort, filter, page combinations.
- [ ] Write `data-source.md`.

---

## 5. Components

### DataTable

- [ ] Implement `DataTable<TRow>` — renders `<table>` (or virtual list when `rows > 200`) with column headers, cells, selection checkboxes, pinned columns (CSS sticky), expandable rows, inline editing cells.
- [ ] Integration with `@suaveplan/react-virtual` `useVirtualList` for rows > 200.
- [ ] Write test, stories (default, large-dataset virtualized, server-side, inline-edit, playground), md.

### DataTableToolbar

- [ ] Implement search input, column-visibility toggle (Popover from `@suaveplan/react-ui`), filter chips, export button.
- [ ] Write test, stories, md.

### DataTablePagination

- [ ] Cursor + offset pagination UI using `@suaveplan/pagination` types.
- [ ] Write test, stories, md.

### DataTableColumnHeader

- [ ] Sortable/filterable column header with pin toggle.
- [ ] Write test, md.

### DataTableExport

- [ ] `exportToCsv(rows, columns)` and `exportToJson(rows)` — produce `Blob`, trigger download. Wraps in `DataTableError(DATA_TABLE_EXPORT_FAILED)` on failure.
- [ ] Write `data-table-export.test.ts`.
- [ ] Write `export.md`.

---

## 6. Utils

- [ ] `sorting.ts` — `sortRows(rows, col, dir, accessor)`: stable sort. Write `sorting.test.ts`, `sorting.md`.
- [ ] `filtering.ts` — `filterRows(rows, filters)`: supports `eq`, `neq`, `contains`, `startsWith`, `gt`, `lt`, `gte`, `lte`. Write `filtering.test.ts`, `filtering.md`.

---

## 7. Integration and E2E

- [ ] `tests/integration.test.tsx` — full `DataTable` with `MemoryDataSource`: sort, filter, page, select, export CSV.
- [ ] `e2e/data-table.spec.ts` — Playwright: render table, click column header to sort, type in search, paginate, export CSV file download.

---

## 8. Docs

- [ ] All co-located `.md` files (≥200 words, simple + advanced examples, API reference).
- [ ] Root `README.md`: purpose, install, quick-start with `MemoryDataSource`, table of exports, links to co-located docs.

---

## 9. Verify and publish

- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-data-table` — green.
- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-data-table` — 100%.
- [ ] `bun scripts/publish.ts --package @suaveplan/react-data-table`.
- [ ] Archive change folder.