Initial Commit

openspec/changes/enterprise-react-data-table/proposal.md

@@ -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.