suaveplan/openspec/changes/enterprise-react-data-table/tasks.md

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.