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

// 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

Virtualized rows — delegates to @suaveplan/react-virtual useVirtualList for large datasets (>200 rows).
Column pinning — left/right pin via columnDef.pin: 'left' | 'right'.
Inline editing — columnDef.editable + onCellEdit callback + optimistic update pattern.
CSV/JSON export — DataTableExport component; uses browser Blob + URL.createObjectURL.
OTel instrumentation — spans on sort, filter, page, export.
Stories — default, large-dataset (virtualized), server-side, inline-edit, playground.

File layout

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.

3.9 KiB Raw Blame History