Table Components & Providers
Relevant source files
The following files were used as context for generating this wiki page:
The Table Components and Providers module constitutes the primary UI layer of the Better Tables ecosystem. It integrates core state management logic with React components to provide high-performance, type-safe data grids. The architecture relies on a specialized provider pattern to synchronize state across complex features such as relationship filtering, inline editing, and virtualization.
This system bridges the gap between the @better-tables/core logic and the visual representation, utilizing Shadcn-style primitives for rendering. It handles the orchestration of data fetching, URL state synchronization, and user interactions within a unified React context.
Sources: packages/ui/src/components/table/table.tsx, packages/ui/src/components/table/table-providers.tsx, README.md:197-210
Architecture Overview
The UI layer is structured around the BetterTable component, which serves as the entry point. It utilizes a provider-based architecture to manage state across deeply nested child components like headers, filter bars, and editable cells.
The diagram shows the hierarchical flow from the main component through state providers to specialized UI sub-sections.
Sources: packages/ui/src/components/table/table.tsx:690-750, packages/ui/src/components/table/table-providers.tsx:20-50
Table Components
BetterTable Component
The BetterTable component is the flagship UI component. It accepts a table definition and data source, coordinating features like sorting, pagination, and selection through a declarative features prop.
| Prop | Type | Description |
|---|---|---|
table | TableDefinition | The core table definition containing columns and logic. |
data | TData[] | The array of data objects to render. |
features | TableFeatures | Toggle object for filtering, sorting, pagination, etc. |
onCellEdit | Function | Callback for handling inline cell edits. |
virtualized | boolean | Enables high-performance row virtualization. |
Sources: packages/ui/src/components/table/table.tsx:80-160, packages/core/src/types/table.ts:130-170
Inline Editing UI
Inline editing is handled via the EditableCell wrapper. It mounts type-aware editors (text, number, date, option) based on the column definition's .editable() configuration.
The sequence diagram illustrates the lifecycle of a cell edit from user interaction to adapter persistence.
Sources: packages/ui/src/hooks/use-editable-cells.ts:10-60, packages/ui/src/components/table/table.tsx:301-315
State Providers & Hooks
TableProvider
The TableProvider (found in table-providers.tsx) wraps the table UI to expose core managers. It ensures that components like the FilterBar can access and modify the same state as the main TableBody.
Key functionalities provided:
- State Synchronization: Maps core
TableStateManagerevents to React state updates. - Context Access: Provides hooks like
useTableContextfor sub-components to accessFilterManagerandSortingManager. - Relationship Resolution: Handles the mapping of dot-path IDs to visible columns.
Sources: packages/ui/src/components/table/table-providers.tsx:40-110, packages/ui/src/hooks/use-table-data.ts:20-45
useTableData Hook
This hook manages the lifecycle of data fetching. It handles the fetchData request to the adapter, including parameter serialization and loading states.
// packages/ui/src/hooks/use-table-data.ts:84-90
export function useTableData<TData = unknown>({
adapter,
filters = EMPTY_FILTERS,
pagination,
params = EMPTY_PARAMS,
enabled = true,
}: UseTableDataOptions<TData>): UseTableDataResult<TData>
The hook uses stable defaults (EMPTY_FILTERS, EMPTY_PARAMS) to prevent infinite refetch loops caused by inline object literals.
Sources: packages/ui/src/hooks/use-table-data.ts:84-110, plans/034-usetabledata-loop-and-date-render.md:35-50
Implementation Details
Feature Gating
The UI uses a feature gating matrix to determine if a specific capability (like inline editing) should be active for a given column or row.
Formatting Logic
The table components use a centralized getFormatterForType utility to render data. This utility is responsible for coercing raw values (like ISO strings from an HTTP adapter) into formatted date strings or badges.
Sources: packages/ui/src/components/table/table.tsx:309, packages/core/src/types/table.ts:320-350
Summary
The Table Components & Providers module provides the reactive glue between @better-tables/core and the user interface. By utilizing a provider-based architecture, it enables features like automatic relationship filtering and optimistic inline editing while maintaining high performance through virtualization and stable hook dependencies.