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