Initial Commit
This commit is contained in:
118
openspec/changes/enterprise-react-data-table/proposal.md
Normal file
118
openspec/changes/enterprise-react-data-table/proposal.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# OpenSpec Change: enterprise-react-data-table
|
||||
|
||||
- **Change ID**: enterprise-react-data-table
|
||||
- **Package**: `@suaveplan/react-data-table`
|
||||
- **Category**: react
|
||||
- **Target path**: `react/ui/react-data-table`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-data-table.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/react-data-table` on genesis from scratch at enterprise quality. A full-featured, headless-core data table for React: virtualized rows via `@suaveplan/react-virtual`, column sorting/filtering/pinning/resizing, row selection (single/multi), pagination (cursor + offset), column groups, expandable rows, inline editing, CSV/JSON export, and an `@suaveplan/error`-backed error boundary. The engine is decoupled from the render layer so server-side data sources (REST, SurrealDB, Drizzle) plug in through a typed `DataSource` adapter.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
Package does not exist on genesis — fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `DataTableError` base class |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `StorageLike` |
|
||||
| `@suaveplan/events` (`workspace:^`) | Column/sort/filter change events |
|
||||
| `@suaveplan/react-ui` (`workspace:^`) | Primitive UI (Button, Input, Checkbox, Popover, DropdownMenu) |
|
||||
| `@suaveplan/react-virtual` (`workspace:^`) | Row virtualization |
|
||||
| `@suaveplan/react-translate` (`workspace:^`) | i18n |
|
||||
| `@suaveplan/pagination` (`workspace:^`) | Cursor + offset pagination primitives |
|
||||
| `zod` (`catalog:forms`) | Column definition schemas |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Span on sort/filter/page |
|
||||
|
||||
---
|
||||
|
||||
## Preserved public API surface
|
||||
|
||||
```ts
|
||||
// Core
|
||||
DataTable<TRow>
|
||||
DataTableColumn<TRow>
|
||||
DataTableOptions<TRow>
|
||||
DataSource<TRow>
|
||||
useDataTable<TRow>(options: DataTableOptions<TRow>): DataTableState<TRow>
|
||||
|
||||
// Toolbar
|
||||
DataTableToolbar
|
||||
DataTableSearch
|
||||
DataTableColumnVisibility
|
||||
DataTableExport
|
||||
|
||||
// Pagination
|
||||
DataTablePagination
|
||||
|
||||
// Types
|
||||
SortDirection, FilterOperator, RowSelectionMode
|
||||
DataTableState<TRow>
|
||||
DataTableColumnDef<TRow>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **Virtualized rows** — delegates to `@suaveplan/react-virtual` `useVirtualList` for large datasets (>200 rows).
|
||||
2. **Column pinning** — left/right pin via `columnDef.pin: 'left' | 'right'`.
|
||||
3. **Inline editing** — `columnDef.editable` + `onCellEdit` callback + optimistic update pattern.
|
||||
4. **CSV/JSON export** — `DataTableExport` component; uses browser `Blob` + `URL.createObjectURL`.
|
||||
5. **OTel instrumentation** — spans on `sort`, `filter`, `page`, `export`.
|
||||
6. **Stories** — `default`, `large-dataset` (virtualized), `server-side`, `inline-edit`, `playground`.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
react/ui/react-data-table/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
core/
|
||||
use-data-table/
|
||||
use-data-table.ts + .types.ts + .md + .test.ts + index.ts
|
||||
data-source/
|
||||
data-source.ts + .types.ts + .md + .test.ts + index.ts
|
||||
components/
|
||||
data-table/
|
||||
data-table.tsx + .types.ts + .md + .test.tsx + .stories.tsx + index.ts
|
||||
data-table-toolbar/
|
||||
data-table-toolbar.tsx + .types.ts + .md + .test.tsx + .stories.tsx + index.ts
|
||||
data-table-pagination/
|
||||
data-table-pagination.tsx + .types.ts + .md + .test.tsx + .stories.tsx + index.ts
|
||||
data-table-column-header/
|
||||
data-table-column-header.tsx + .types.ts + .md + .test.tsx + index.ts
|
||||
data-table-export/
|
||||
data-table-export.ts + .md + .test.ts + index.ts
|
||||
utils/
|
||||
sorting.ts + .md + .test.ts
|
||||
filtering.ts + .md + .test.ts
|
||||
export.ts + .md + .test.ts
|
||||
tests/
|
||||
integration.test.tsx
|
||||
e2e/
|
||||
data-table.spec.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
Downstream: `react-admin-forms`, future admin-panel apps. Requires `@suaveplan/react-ui`, `@suaveplan/react-virtual`, `@suaveplan/pagination` on Verdaccio.
|
||||
112
openspec/changes/enterprise-react-data-table/tasks.md
Normal file
112
openspec/changes/enterprise-react-data-table/tasks.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user