119 lines
3.9 KiB
Markdown
119 lines
3.9 KiB
Markdown
# 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.
|