113 lines
5.3 KiB
Markdown
113 lines
5.3 KiB
Markdown
# 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.
|