FRD-032: Resource Table

Field	Value
Owner	David Holmes
Status	Draft
Last Updated	2026-05-26
Target Release	v2.0.0
Type	Widget
Size	M
Priority	P1 — SaaS Widget

Document Summary

Build a generic Resource Table widget that provides CRUD table UX with sort, filter, paginate, bulk-select, search, and standardized empty/loading/error states. It builds on the DataGrid primitive and generalizes the patterns demonstrated by people-table.tsx and billing-history-table.tsx into a reusable, consumer-configurable widget.

Introduction

Overview

The design system has DataGrid as a powerful table primitive and two specialized table widgets (PeopleTable, BillingHistoryTable). However, every new CRUD resource list (projects, environments, deployments, documents) requires teams to re-compose DataGrid with search, filters, bulk actions, and state handling. A generic ResourceTable widget would provide this composition out of the box, configured via props rather than rebuilt from scratch.

Goals

Provide a ResourceTable widget composing DataGrid with ListToolbar, search, filter presets, bulk actions, and state handling.
Support consumer-defined column configurations using the existing DataGridColumn type.
Provide built-in search integration that filters across all searchable columns.
Handle loading (skeleton rows), empty (configurable message + CTA), and error (message + retry) states.
Support row-level actions via a configurable actions column.
Ship with Storybook stories demonstrating diverse resource types and unit tests.

Non-Goals

Server-side pagination/filtering (widget operates on client-side data; server-side is a consumer responsibility via callbacks).
Inline row editing (covered by InlineEdit in FRD-028).
Tree/hierarchical table display.

Scope

In Scope

Item	Description
ResourceTable widget	Composed DataGrid with toolbar, search, filters, bulk actions, pagination, and state handling.
Column configuration	Consumer passes `DataGridColumn[]` to define columns, including custom cell renderers.
Search integration	Built-in search that filters across columns marked as `searchable`.
Filter presets	Consumer-defined filter presets rendered as toolbar filter chips or a filter popover.
Bulk actions	Checkbox column with bulk action buttons (e.g., “Delete selected”, “Export selected”).
Row actions	Per-row action dropdown (consumer provides action definitions).
State handling	Loading skeleton, empty state with CTA, error state with retry.
Pagination	Built-in pagination with configurable page sizes.
Stories and tests	Storybook stories for various resource types; unit tests for search, filter, bulk selection.

Out of Scope

Item	Reason
Server-side pagination	Consumer manages via `onPageChange` callback and provides paginated data.
Inline editing	Separate FRD (FRD-028 InlineEdit).
Column reordering / drag-to-resize	DataGrid primitive concern; future enhancement.
Virtualized rows	DataGrid handles virtualization internally for large datasets.

Users and Pain Points

User	Pain Point
SaaS developers	Rebuild DataGrid + toolbar + search + filters + pagination for every new resource type.
Product designers	Inconsistent table patterns across different resource pages.
QA teams	Each custom table implementation has different state handling bugs.
End users	Inconsistent search, filter, and pagination UX across different resource lists.

Definitions

Term	Definition
Resource	Any CRUD entity displayed in a table: users, projects, deployments, keys, invoices, etc.
Bulk action	An action applied to all currently selected rows (e.g., delete, export, archive).
Row action	An action specific to a single row, rendered in an actions column dropdown.
Filter preset	A named, pre-configured filter (e.g., “Active only”, “Created this week”) rendered as a toolbar chip.
Searchable column	A column whose accessor value is included in the full-text search.

Current State

DataGrid (src/components/ui/data-grid.tsx): Full-featured table with sorting, filtering, pagination, row selection via TanStack Table. Accepts ColumnDef[], data, sorting/filter/pagination state.
ListToolbar (src/components/ui/list-toolbar.tsx): Toolbar with search input, filter buttons, and action buttons. Used above DataGrid.
PeopleTable (src/components/widgets/people-table.tsx): Specialized DataGrid for team members with avatar, name, email, role, status columns.
BillingHistoryTable (src/components/patterns/billing-history-table.tsx): Specialized DataGrid for invoices.
StatusCard: Used for empty/error states.
No generic ResourceTable widget exists.

Proposed Solution

Build src/components/widgets/resource-table.tsx as a composed widget that wraps DataGrid, ListToolbar, and state handling into a single configurable component.

Architecture

ResourceTable
├── ListToolbar (search + filter chips + bulk action buttons)
├── DataGrid (columns + data + sort + paginate + select)
│   ├── Consumer-defined columns
│   └── Optional actions column (auto-appended)
├── Pagination (page controls + page size selector)
└── State overlays (loading skeleton / empty card / error card)

Configuration Model

Instead of rebuilding columns for every resource, consumers pass:

columns — standard DataGridColumn[] with optional searchable: boolean flag.
data — array of resource objects.
rowActions — optional array of action definitions { label, icon, onClick, variant } rendered in per-row dropdown.
bulkActions — optional array of bulk action definitions rendered in toolbar when rows are selected.
filterPresets — optional named filters rendered as toolbar chips.
emptyState / errorState — configurable content for empty and error displays.

State Handling

The widget reads loading, error, and data.length to determine which view to render:

loading === true → Skeleton rows (shape-matched to column count).
error is defined → StatusCard with error message and retry button.
data.length === 0 && !loading → Empty state card with configurable CTA.

Requirements

Requirement Priorities

Must Have: Column configuration, search, sort, paginate, empty/loading/error states.
Should Have: Bulk select + bulk actions, row actions dropdown, filter presets.
Could Have: Column visibility toggle, CSV export built-in, saved filter presets.

Functional Requirements

ID	Requirement	Priority
FR-01	Widget accepts `columns`, `data`, and renders a DataGrid with sorting enabled on all columns.	Must
FR-02	Built-in search input filters rows across all columns marked `searchable: true`.	Must
FR-03	Pagination controls with configurable page sizes (default [10, 25, 50]).	Must
FR-04	Loading state renders skeleton rows matching the column count and configured page size.	Must
FR-05	Empty state renders a configurable StatusCard with title, description, and optional CTA button.	Must
FR-06	Error state renders a StatusCard with error message and retry button.	Must
FR-07	`rowActions` prop auto-appends an actions column with a dropdown menu per row.	Should
FR-08	`bulkActions` prop enables checkbox column; selected rows reveal bulk action buttons in the toolbar.	Should
FR-09	`filterPresets` prop renders filter chips in the toolbar; clicking a chip applies the filter.	Should
FR-10	`onRowClick` callback fires when a row is clicked (for navigation to detail view).	Should
FR-11	Widget exposes `ref` to the outer container and `tableRef` to the TanStack Table instance for advanced control.	Could

Non-Functional Requirements

ID	Requirement	Target
NFR-01	Renders 100 rows with 8 columns in < 50ms.	Measured via React Profiler.
NFR-02	Bundle size	< 5 KB gzipped (excluding shared DataGrid deps).
NFR-03	Search debounce	200ms debounce on search input to avoid excessive filtering.
NFR-04	Dark mode	Full token-based dark mode support.
NFR-05	Responsive	Column hiding on narrow viewports via responsive column config.

API/Interface Requirements

interface ResourceTableColumn<T> extends DataGridColumn<T> {
  searchable?: boolean;
}

interface RowAction<T> {
  label: string;
  icon?: ReactNode;
  onClick: (row: T) => void;
  variant?: "default" | "destructive";
  disabled?: boolean | ((row: T) => boolean);
}

interface BulkAction<T> {
  label: string;
  icon?: ReactNode;
  onClick: (selectedRows: T[]) => void;
  variant?: "default" | "destructive";
}

interface FilterPreset {
  id: string;
  label: string;
  filter: (row: any) => boolean;
}

interface ResourceTableProps<T extends { id: string }> {
  columns: ResourceTableColumn<T>[];
  data: T[];
  loading?: boolean;
  error?: string;
  onRetry?: () => void;
  rowActions?: RowAction<T>[];
  bulkActions?: BulkAction<T>[];
  filterPresets?: FilterPreset[];
  onRowClick?: (row: T) => void;
  pageSizes?: number[];              // default [10, 25, 50]
  defaultPageSize?: number;          // default 10
  searchPlaceholder?: string;
  emptyTitle?: string;
  emptyDescription?: string;
  emptyAction?: { label: string; onClick: () => void };
  className?: string;
}

Accessibility Requirements

ID	Requirement
A11Y-01	DataGrid uses `role="grid"` with proper `role="row"` and `role="gridcell"` semantics.
A11Y-02	Row action dropdown is keyboard accessible; opens on Enter/Space, navigates with arrows.
A11Y-03	Bulk action buttons announce the number of selected rows via `aria-label`.
A11Y-04	Search input has `aria-label` and clears on Escape.
A11Y-05	Pagination controls announce current page and total pages.
A11Y-06	All components pass axe-core automated checks with zero violations.

Content and Documentation Requirements

ID	Requirement
DOC-01	Storybook docs page with usage guidelines, prop table, and interactive examples.
DOC-02	Recipe showing ResourceTable configured for 3+ different resource types (users, projects, invoices).
DOC-03	Migration guide for teams using raw DataGrid + ListToolbar composition.

Dependencies

Dependency	Type	Risk
`src/components/ui/data-grid.tsx`	Internal	Low — core table primitive.
`src/components/ui/list-toolbar.tsx`	Internal	Low — toolbar with search and filters.
`src/components/ui/pagination.tsx`	Internal	Low — page controls.
`src/components/ui/status-card.tsx`	Internal	Low — empty/error states.
`src/components/ui/skeleton.tsx`	Internal	Low — loading states.
`@tanstack/react-table`	Existing	Low — already used by DataGrid.

Risks and Tradeoffs

Risk	Likelihood	Impact	Mitigation
Widget is too opinionated; teams need more customization	Medium	Medium	Expose `tableRef` for advanced TanStack Table control; keep props composable.
Search performance degrades with large datasets	Low	Medium	200ms debounce; document that server-side search is preferred for 1000+ rows.
Generic typing makes TypeScript inference complex	Medium	Low	Use constrained generic `T extends { id: string }`; provide concrete examples.

Open Questions

#	Question	Owner	Status
OQ-01	Should ResourceTable support server-side pagination via `onPageChange` callback?	David Holmes	Open
OQ-02	Should column visibility toggles be built in or deferred?	David Holmes	Open
OQ-03	Should the widget support “infinite scroll” as an alternative to pagination?	David Holmes	Open

Acceptance Criteria

#	Criterion
AC-01	Widget renders a table with consumer-defined columns, sorting, and pagination.
AC-02	Search input filters rows across searchable columns with 200ms debounce.
AC-03	Loading state shows skeleton rows; empty state shows configurable card with CTA; error state shows retry.
AC-04	Row actions render in a per-row dropdown menu.
AC-05	Bulk selection enables bulk action buttons in the toolbar.
AC-06	All components pass axe-core checks with zero violations.
AC-07	Storybook stories demonstrate 3+ resource types (users, projects, invoices).
AC-08	Unit tests cover search, sort, pagination, bulk selection, and state transitions.
AC-09	`pnpm typecheck` and `pnpm vitest run --project unit` pass with zero errors.

LLM Handoff Instructions

When implementing this FRD:

Create src/components/widgets/resource-table.tsx. Study people-table.tsx and billing-history-table.tsx for the composition pattern.
Use DataGrid as the core table. Pass columns, data, sorting, pagination, and selection props through.
Compose ListToolbar above the DataGrid. Wire the search input to DataGrid’s global filter. Render filter preset chips and bulk action buttons conditionally.
Auto-append actions column: If rowActions is provided, append a final column with a DropdownMenu containing the action items.
State handling: Check loading, error, data.length in order. Render skeleton/error/empty as appropriate. Empty state is gated on !loading && data.length === 0.
Generic typing: ResourceTable<T extends { id: string }> — the id constraint is needed for row selection keys.
Stories in src/components/widgets/resource-table.stories.tsx. Create stories for: Default (users), ProjectsExample, InvoicesExample, Loading, Empty, Error, BulkActions, WithFilters.
Tests in src/components/widgets/resource-table.test.tsx.

Key files:

src/components/ui/data-grid.tsx — table primitive API.
src/components/ui/list-toolbar.tsx — toolbar API.
src/components/widgets/people-table.tsx — composition pattern reference.

Decision Log

Date	Decision	Rationale
2026-05-26	Client-side data model; no built-in server-side pagination.	Widget stays simple; server-side pagination is a consumer concern using `onPageChange` callback.
2026-05-26	Require `id: string` on all resource objects.	Needed for row selection, keying, and action targeting.
2026-05-26	Auto-append actions column rather than requiring consumers to define it.	Reduces boilerplate for the most common pattern.

Document History

Version	Date	Author	Changes
0.1	2026-05-26	David Holmes	Initial draft.