@scalepad/ui 0.1.0

package/src/components/DataTable/DataTable.tsx

@@ -0,0 +1,1042 @@
+import {
+  memo,
+  useMemo,
+  useState,
+  type CSSProperties,
+  type MouseEvent as ReactMouseEvent,
+  type ReactNode,
+} from 'react';
+
+import {
+  flexRender,
+  type Header,
+  type Row,
+  type Table,
+} from '@tanstack/react-table';
+import { clsx } from 'clsx';
+import { Settings2 } from 'lucide-react';
+
+import {
+  Box,
+  Checkbox,
+  Flex,
+  Table as MantineTable,
+  Menu,
+} from '@mantine/core';
+
+import { tokens } from '../../theme/themeContract.css';
+import { EmptyState } from '../EmptyState';
+import { ErrorState } from '../ErrorState';
+import { IconButton } from '../IconButton';
+import { RowExpandToggle } from './RowExpandToggle';
+import {
+  InfiniteScrollTrigger,
+  type InfiniteScrollState,
+} from '../InfiniteScrollTrigger';
+import { SortableColumnHeader } from '../Table/SortableColumnHeader';
+import {
+  TableSkeletonRows,
+  type SkeletonColumnConfig,
+} from '../Table/TableSkeletonRows';
+import { TableCard } from '../TableCard';
+import { Text } from '../Typography';
+
+export interface DataTableColumnConfiguratorItem {
+  id: string;
+  label: string;
+  defaultVisible?: boolean;
+}
+
+export interface DataTableColumnConfigurator {
+  columns: DataTableColumnConfiguratorItem[];
+  buttonAriaLabel?: string;
+  menuLabel?: string;
+  onColumnToggle?: (columnId: string, isVisible: boolean) => void;
+}
+
+export interface DataTableProps<TData> {
+  /**
+   * TanStack Table instance from useServerTable
+   */
+  table: Table<TData>;
+  /**
+   * True ONLY on first load (no cached data) -> show skeleton
+   */
+  isInitialLoading: boolean;
+  /**
+   * True when data exists but refetching (sort/filter change) -> show subtle indicator
+   */
+  isRefetching: boolean;
+  /**
+   * True when query failed
+   */
+  isError: boolean;
+  /**
+   * Pagination state for InfiniteScrollTrigger
+   */
+  pagination: InfiniteScrollState;
+  /**
+   * Custom empty state component to render when no data
+   * Receives hasData boolean to determine if showing filtered empty vs no data
+   * If not provided, will use a default EmptyState component
+   */
+  emptyState?: ReactNode;
+  /**
+   * Custom error state component to render on query failure
+   * If not provided, will use a default ErrorState component
+   */
+  errorState?: ReactNode;
+  /**
+   * Callback when a row is clicked.
+   *
+   * The second argument is the underlying TanStack `Row<TData>` for callers
+   * that need access to row-model state (depth, canExpand, selection, etc.).
+   * Existing one-argument callers remain compatible.
+   *
+   * For group rows (`row.getCanExpand() === true`) this callback is NOT
+   * invoked by default — clicking a group row toggles expansion instead.
+   * See `disableRowClickForGroupRows` to make group-row body-clicks inert.
+   */
+  onRowClick?: (row: TData, tanstackRow: Row<TData>) => void;
+  /**
+   * Callback when hovering over a row (for prefetching)
+   */
+  onRowHover?: (row: TData) => void;
+  /**
+   * Custom class names for table rows
+   */
+  rowClassName?: string | ((row: TData) => string);
+  /**
+   * Row id that should render as active/highlighted.
+   */
+  activeRowId?: string;
+  /**
+   * Minimum width for horizontal scroll
+   * @default 800
+   */
+  minWidth?: number;
+  /**
+   * Whether to show a border around the table card
+   * @default true
+   */
+  withBorder?: boolean;
+  /**
+   * Number of skeleton rows to show during initial load
+   * @default 8
+   */
+  skeletonRowCount?: number;
+  /**
+   * Opacity when refetching (0-1)
+   * @default 0.6
+   */
+  refetchingOpacity?: number;
+  /**
+   * Loading message for infinite scroll
+   * @default "Loading more..."
+   */
+  infiniteScrollMessage?: string;
+  /**
+   * Message to show when all data has been loaded via infinite scroll
+   * Only shown if multiple pages were fetched.
+   * @default "All items loaded"
+   * @example "All apps loaded"
+   */
+  infiniteScrollEndMessage?: string;
+  /**
+   * Whether to show row selection checkboxes
+   * When true, renders a checkbox column and changes row click to toggle selection
+   * @default false
+   */
+  showRowSelection?: boolean;
+  /**
+   * Opt in to row expansion (tree rows). When true, `DataTable` assumes the
+   * consumer's table instance was built with `getSubRows` +
+   * `getExpandedRowModel()` and owns the `expanded` state. In auto mode this
+   * also injects a leading chevron column.
+   *
+   * @default false
+   */
+  enableRowExpansion?: boolean;
+  /**
+   * Optional custom renderer for group (expandable) rows. When provided and
+   * the row is a group (`row.getCanExpand() === true`), the row is rendered
+   * as a single `<td>` with `colSpan` covering every column — consumer fully
+   * owns the layout (chevron, label, aggregates, etc.). Pair with
+   * `RowGroupHeader` for the design-system default.
+   *
+   * Return `null`/`undefined` to fall back to per-column rendering for that
+   * specific row.
+   *
+   * When this prop is set, group rows ignore the selection checkbox cell
+   * and the auto-injected chevron cell — both are subsumed by the spanning
+   * TD. Leaf rows keep standard column-by-column rendering.
+   */
+  renderGroupRow?: (row: Row<TData>) => ReactNode;
+  /**
+   * Background color applied to the `<tr>` of custom-rendered group rows.
+   * Accepts any CSS color value (typically a design-system token value).
+   *
+   * @default tokens.color.background.subduedUltralight
+   */
+  groupRowBackground?: string;
+  /**
+   * How the expand/collapse chevron is rendered.
+   * - `"auto"` (default): `DataTable` prepends a dedicated chevron column.
+   * - `"custom"`: consumer composes `<RowExpandToggle row={row}>` inside one
+   *   of their own cells; no extra column is rendered.
+   *
+   * Only honored when `enableRowExpansion` is true.
+   * @default "auto"
+   */
+  renderExpandToggle?: 'auto' | 'custom';
+  /**
+   * When true, clicking a group row's body does nothing. The chevron button
+   * and (if present) the selection checkbox still work. Useful when the
+   * only meaningful interaction on a group row should be the explicit
+   * affordances.
+   * @default false
+   */
+  disableRowClickForGroupRows?: boolean;
+  /**
+   * Optional header content for the auto-injected chevron column.
+   * Ignored when `renderExpandToggle` is `"custom"`.
+   */
+  expandColumnHeader?: ReactNode;
+  /**
+   * Width (px) of the auto-injected chevron column.
+   * Ignored when `renderExpandToggle` is `"custom"`.
+   * @default 40
+   */
+  expandColumnWidth?: number;
+  /**
+   * Table layout algorithm
+   * - 'auto': Browser calculates column widths based on content (default)
+   * - 'fixed': Columns use exact widths from column definitions, content may truncate
+   * Use 'fixed' when you need precise column sizing with text truncation
+   * @default undefined (browser default is 'auto')
+   */
+  tableLayout?: 'auto' | 'fixed';
+  /**
+   * Optional column configurator menu.
+   * Lets consumers toggle visibility of selected columns.
+   */
+  columnConfigurator?: DataTableColumnConfigurator;
+}
+
+// Any element matching this selector is treated as an "interactive
+// descendant" — a click on it (or on one of its children) must not toggle
+// group-row expansion. This matters for rows rendered through
+// `renderGroupRow`, where consumers frequently embed buttons, links, inputs,
+// or other controls inside the row body.
+const INTERACTIVE_SELECTOR =
+  'button, a, input, textarea, select, label, [role="button"], [contenteditable=""], [contenteditable="true"]';
+
+function isClickFromInteractiveDescendant(
+  event: ReactMouseEvent<HTMLElement>,
+): boolean {
+  if (event.defaultPrevented) return true;
+  const target = event.target as Element | null;
+  if (!target || typeof target.closest !== 'function') return false;
+  const match = target.closest(INTERACTIVE_SELECTOR);
+  if (!match) return false;
+  // Only bail when the interactive element is inside this row, not an
+  // ancestor that happens to match (e.g. the surrounding page <main>).
+  return event.currentTarget.contains(match);
+}
+
+/**
+ * Resolve the aria-sort attribute from TanStack Table's sort state
+ */
+function getAriaSortValue(
+  sortState: false | 'asc' | 'desc',
+): 'ascending' | 'descending' | 'none' {
+  if (sortState === 'asc') return 'ascending';
+  if (sortState === 'desc') return 'descending';
+  return 'none';
+}
+
+/**
+ * Render a single header cell based on sort state and placeholder status
+ */
+function renderHeaderCell<TData>(header: Header<TData, unknown>) {
+  if (header.isPlaceholder) return null;
+
+  if (header.column.getCanSort()) {
+    // Resolve label: prefer string header, fall back to column ID
+    const label =
+      typeof header.column.columnDef.header === 'string'
+        ? header.column.columnDef.header
+        : header.column.id;
+
+    return (
+      <SortableColumnHeader
+        label={label}
+        sortProps={{
+          onClick: () => header.column.toggleSorting(),
+          'aria-sort': getAriaSortValue(header.column.getIsSorted()),
+        }}
+        align={header.column.columnDef.meta?.align}
+      />
+    );
+  }
+
+  return (
+    <Text variant="caption2.stronger">
+      {flexRender(header.column.columnDef.header, header.getContext())}
+    </Text>
+  );
+}
+
+// --- Memoized row component ---
+// Prevents re-rendering all rows when a single row's selection changes.
+// Custom comparison: rowData reference covers data identity; row reference covers
+// cell/handler freshness; callbacks and primitives are compared directly.
+
+interface DataTableRowProps<TData> {
+  row: Row<TData>;
+  rowData: TData;
+  isSelected: boolean;
+  showRowSelection: boolean;
+  isClickable: boolean;
+  onRowClick?: (row: TData, tanstackRow: Row<TData>) => void;
+  onRowHover?: (row: TData) => void;
+  rowClassName?: string | ((row: TData) => string);
+  activeRowId?: string;
+  showSyntheticActionsColumn?: boolean;
+  showExpandCell?: boolean;
+  disableRowClickForGroupRows?: boolean;
+  // Snapshotted expansion state read at the parent level. Passing these as
+  // primitives lets the memo comparator detect expand/collapse transitions —
+  // calling `prev.row.getIsExpanded()` inside the comparator always reads the
+  // live table state, so it can't distinguish between two consecutive renders.
+  isExpanded: boolean;
+  canExpand: boolean;
+  // Subtle background applied to group rows rendered through the standard
+  // per-column path (no `renderGroupRow`). Leaf rows always ignore this.
+  groupRowBackground: string;
+}
+
+function DataTableRowInner<TData>({
+  row,
+  rowData,
+  isSelected,
+  showRowSelection,
+  isClickable,
+  onRowClick,
+  onRowHover,
+  rowClassName,
+  activeRowId,
+  showSyntheticActionsColumn = false,
+  showExpandCell = false,
+  disableRowClickForGroupRows = false,
+  isExpanded,
+  canExpand,
+  groupRowBackground,
+}: DataTableRowProps<TData>) {
+  const rowClass =
+    typeof rowClassName === 'function' ? rowClassName(rowData) : rowClassName;
+  const isActive = row.id === activeRowId;
+  const isGroup = canExpand;
+  // Active/selected states always win over the group-row background so that
+  // hover/selection highlighting remains visible on group rows.
+  const rowBackgroundColor =
+    isSelected || isActive
+      ? tokens.color.background.primaryLight
+      : isGroup
+        ? groupRowBackground
+        : undefined;
+
+  const handleClick = (event: ReactMouseEvent<HTMLTableRowElement>) => {
+    // Group rows: body-click toggles expand (unless disabled). The chevron
+    // button and the selection checkbox stop propagation, so they still work
+    // independently — users get both affordances on a grouped + selectable
+    // table. Clicks that bubble up from an interactive descendant (e.g. a
+    // button or link inside a cell) must NOT toggle expansion.
+    if (isGroup) {
+      if (
+        !disableRowClickForGroupRows &&
+        !isClickFromInteractiveDescendant(event)
+      ) {
+        row.getToggleExpandedHandler()();
+      }
+      return;
+    }
+    // Leaf rows: selection wins over onRowClick when enabled (preserves
+    // existing behavior for flat tables).
+    if (showRowSelection) {
+      row.toggleSelected();
+      return;
+    }
+    if (onRowClick) {
+      onRowClick(rowData, row);
+    }
+  };
+
+  return (
+    <MantineTable.Tr
+      onClick={isClickable ? handleClick : undefined}
+      onMouseEnter={onRowHover ? () => onRowHover(rowData) : undefined}
+      className={clsx(rowClass)}
+      data-active={isActive ? 'true' : undefined}
+      data-expanded={isGroup ? (isExpanded ? 'true' : 'false') : undefined}
+      style={{
+        cursor: isClickable ? 'pointer' : undefined,
+        backgroundColor: rowBackgroundColor,
+      }}
+    >
+      {showRowSelection && (
+        <MantineTable.Td onClick={e => e.stopPropagation()}>
+          <Checkbox
+            checked={isSelected}
+            onChange={row.getToggleSelectedHandler()}
+            aria-label="Select row"
+          />
+        </MantineTable.Td>
+      )}
+      {showExpandCell && (
+        <MantineTable.Td onClick={e => e.stopPropagation()}>
+          <RowExpandToggle row={row} />
+        </MantineTable.Td>
+      )}
+      {row.getVisibleCells().map(cell => {
+        const meta = cell.column.columnDef.meta as
+          | { align?: string }
+          | undefined;
+        const isPinned = cell.column.getIsPinned();
+        const pinnedStyle: CSSProperties | undefined = isPinned
+          ? {
+              position: 'sticky',
+              left:
+                cell.column.getIsPinned() === 'left'
+                  ? cell.column.getStart()
+                  : undefined,
+              right:
+                cell.column.getIsPinned() === 'right'
+                  ? cell.column.getAfter()
+                  : undefined,
+              zIndex: 1,
+              background: rowBackgroundColor ?? tokens.color.background.default,
+              boxShadow:
+                cell.column.getIsPinned() === 'right'
+                  ? tokens.shadow.sm
+                  : undefined,
+            }
+          : undefined;
+        const cellStyle: CSSProperties = {
+          ...(meta?.align && {
+            textAlign: meta.align as CSSProperties['textAlign'],
+          }),
+          ...pinnedStyle,
+        };
+        return (
+          <MantineTable.Td key={cell.id} style={cellStyle}>
+            {flexRender(cell.column.columnDef.cell, cell.getContext())}
+          </MantineTable.Td>
+        );
+      })}
+      {showSyntheticActionsColumn && (
+        <MantineTable.Td
+          style={{
+            position: 'sticky',
+            right: 0,
+            zIndex: 1,
+            width: 48,
+            background: rowBackgroundColor ?? tokens.color.background.default,
+            boxShadow: tokens.shadow.sm,
+          }}
+        />
+      )}
+    </MantineTable.Tr>
+  );
+}
+
+const DataTableRow = memo(
+  DataTableRowInner,
+  (prev, next) =>
+    prev.row === next.row &&
+    prev.rowData === next.rowData &&
+    prev.isSelected === next.isSelected &&
+    prev.showRowSelection === next.showRowSelection &&
+    prev.isClickable === next.isClickable &&
+    prev.onRowClick === next.onRowClick &&
+    prev.onRowHover === next.onRowHover &&
+    prev.rowClassName === next.rowClassName &&
+    prev.activeRowId === next.activeRowId &&
+    prev.showSyntheticActionsColumn === next.showSyntheticActionsColumn &&
+    prev.showExpandCell === next.showExpandCell &&
+    prev.disableRowClickForGroupRows === next.disableRowClickForGroupRows &&
+    // Expansion state must be compared via snapshotted primitives, not
+    // `prev.row.getIsExpanded()`: TanStack caches the Row object across
+    // renders, and `getIsExpanded()` reads the live table state, so calling
+    // it on both `prev.row` and `next.row` (same reference) always returns
+    // the same value and would never invalidate the memo on expand/collapse.
+    prev.isExpanded === next.isExpanded &&
+    prev.canExpand === next.canExpand &&
+    prev.groupRowBackground === next.groupRowBackground,
+) as typeof DataTableRowInner;
+
+// --- Custom group-row renderer ---
+// Used when `renderGroupRow` is provided and the row is a group. Renders a
+// single <td colSpan> instead of the per-column layout, so the consumer can
+// emit a row that looks nothing like a leaf row (different fields,
+// background, aggregates, etc.).
+
+interface DataTableGroupRowProps<TData> {
+  row: Row<TData>;
+  content: ReactNode;
+  colSpan: number;
+  background: string;
+  disableRowClick: boolean;
+  // Snapshotted at parent level — see DataTableRow for why `row.getIsExpanded()`
+  // inside the memo comparator can't detect expand/collapse transitions.
+  isExpanded: boolean;
+}
+
+function DataTableGroupRowInner<TData>({
+  row,
+  content,
+  colSpan,
+  background,
+  disableRowClick,
+  isExpanded,
+}: DataTableGroupRowProps<TData>) {
+  // Custom-rendered group rows (`renderGroupRow`) often contain interactive
+  // descendants — buttons, links, inputs — that the consumer expects to
+  // behave independently. Swallow the row-level toggle when the original
+  // click originated from one of those controls so the control's own
+  // handler runs without also collapsing/expanding the group.
+  const handleClick = disableRowClick
+    ? undefined
+    : (event: ReactMouseEvent<HTMLTableRowElement>) => {
+        if (isClickFromInteractiveDescendant(event)) return;
+        row.getToggleExpandedHandler()();
+      };
+  return (
+    <MantineTable.Tr
+      onClick={handleClick}
+      data-expanded={isExpanded ? 'true' : 'false'}
+      style={{
+        cursor: handleClick ? 'pointer' : undefined,
+        backgroundColor: background,
+      }}
+    >
+      <MantineTable.Td
+        colSpan={colSpan}
+        style={{
+          backgroundColor: background,
+          padding: '0 16px',
+          height: 40,
+        }}
+      >
+        {content}
+      </MantineTable.Td>
+    </MantineTable.Tr>
+  );
+}
+
+const DataTableGroupRow = memo(
+  DataTableGroupRowInner,
+  (prev, next) =>
+    prev.row === next.row &&
+    prev.content === next.content &&
+    prev.colSpan === next.colSpan &&
+    prev.background === next.background &&
+    prev.disableRowClick === next.disableRowClick &&
+    prev.isExpanded === next.isExpanded,
+) as typeof DataTableGroupRowInner;
+
+/**
+ * DataTable component - renders a TanStack Table with automatic state handling
+ *
+ * Handles all loading/error/empty states automatically:
+ * - Initial load: Shows skeleton
+ * - Refetching: Shows table with opacity overlay
+ * - Error: Shows custom error state (or default ErrorState if not provided)
+ * - No data: Shows custom empty state (or default EmptyState if not provided)
+ * - Has data: Renders table from column definitions
+ *
+ * @example Basic usage
+ * ```tsx
+ * const { table, ...states } = useServerTable({ columns, queryOptions, filters });
+ *
+ * <DataTable
+ *   {...states}
+ *   table={table}
+ *   emptyState={
+ *     <TableEmptyState
+ *       entityName="apps"
+ *       noDataDescription="No apps found"
+ *       hasActiveFilters={hasActiveFilters}
+ *       onClearFilters={clearFilters}
+ *     />
+ *   }
+ *   onRowClick={(app) => openDrawer(app.id)}
+ * />
+ * ```
+ */
+export function DataTable<TData>({
+  table,
+  isInitialLoading,
+  isRefetching,
+  isError,
+  pagination,
+  emptyState,
+  errorState,
+  onRowClick,
+  onRowHover,
+  rowClassName,
+  activeRowId,
+  minWidth = 800,
+  withBorder = true,
+  skeletonRowCount = 8,
+  refetchingOpacity = 0.6,
+  infiniteScrollMessage = 'Loading more...',
+  infiniteScrollEndMessage,
+  showRowSelection = false,
+  enableRowExpansion = false,
+  renderExpandToggle = 'auto',
+  disableRowClickForGroupRows = false,
+  expandColumnHeader,
+  expandColumnWidth = 40,
+  renderGroupRow,
+  groupRowBackground,
+  tableLayout,
+  columnConfigurator,
+}: DataTableProps<TData>) {
+  const rows = table.getRowModel().rows;
+  const hasData = rows.length > 0;
+  const showExpandCell = enableRowExpansion && renderExpandToggle !== 'custom';
+  const resolvedGroupRowBackground =
+    groupRowBackground ?? tokens.color.background.subduedUltralight;
+
+  // Footer rendering is auto-detected: if any column has a `footer` defined,
+  // we emit a <tfoot>. This keeps the API surface small while covering the
+  // common "grand total" pattern.
+  const footerGroups = table.getFooterGroups();
+  const hasFooter = footerGroups.some(group =>
+    group.headers.some(
+      header => !header.isPlaceholder && header.column.columnDef.footer != null,
+    ),
+  );
+
+  if (
+    import.meta.env.DEV &&
+    enableRowExpansion &&
+    table.getState().expanded === undefined
+  ) {
+    // Warn once per render but only during development. In production we stay
+    // silent — expansion simply won't do anything useful, which is immediately
+    // visible to the integrator.
+    console.warn(
+      'DataTable: enableRowExpansion is true but the table instance has no expanded state. ' +
+        'Pass getExpandedRowModel() + state.expanded when constructing the table (e.g. via useServerTable with the tree option).',
+    );
+  }
+  const [isConfiguratorOpen, setIsConfiguratorOpen] = useState(false);
+  const configurableColumns = useMemo(
+    () =>
+      (columnConfigurator?.columns ?? []).filter(
+        ({ id }) => typeof table.getColumn(id)?.getIsVisible === 'function',
+      ),
+    [columnConfigurator?.columns, table],
+  );
+  const hasActionsColumn = useMemo(
+    () =>
+      table
+        .getHeaderGroups()
+        .some(group =>
+          group.headers.some(header => header.column.id === 'actions'),
+        ),
+    [table],
+  );
+  const shouldRenderSyntheticActionsColumn =
+    configurableColumns.length > 0 && !hasActionsColumn;
+
+  const handleToggleColumn = (columnId: string) => {
+    const column = table.getColumn(columnId);
+    if (!column) return;
+
+    const nextVisibility = !column.getIsVisible();
+    column.toggleVisibility(nextVisibility);
+    columnConfigurator?.onColumnToggle?.(columnId, nextVisibility);
+  };
+
+  const renderColumnConfiguratorMenu = () => (
+    <Menu
+      opened={isConfiguratorOpen}
+      onChange={setIsConfiguratorOpen}
+      withArrow
+      withinPortal
+      closeOnItemClick={false}
+    >
+      <Menu.Target>
+        <IconButton
+          variant="ghost"
+          size="xs"
+          aria-label={
+            columnConfigurator?.buttonAriaLabel ?? 'Configure table columns'
+          }
+        >
+          <Settings2 size={16} />
+        </IconButton>
+      </Menu.Target>
+      <Menu.Dropdown>
+        {columnConfigurator?.menuLabel && (
+          <Menu.Label>{columnConfigurator.menuLabel}</Menu.Label>
+        )}
+        {configurableColumns.map(column => {
+          const isVisible = table.getColumn(column.id)?.getIsVisible() ?? false;
+          return (
+            <Menu.Item
+              key={column.id}
+              onClick={() => handleToggleColumn(column.id)}
+            >
+              <Flex gap="xs" align="center">
+                <Checkbox checked={isVisible} readOnly tabIndex={-1} />
+                <Text variant="caption1">{column.label}</Text>
+              </Flex>
+            </Menu.Item>
+          );
+        })}
+      </Menu.Dropdown>
+    </Menu>
+  );
+
+  const renderContent = () => {
+    // Initial loading: show skeleton rows (no headers)
+    if (isInitialLoading) {
+      const firstHeaderGroup = table.getHeaderGroups()[0];
+      const skeletonColumns: SkeletonColumnConfig[] =
+        firstHeaderGroup?.headers.map(h => ({
+          width: Math.min(Math.round(h.getSize() * 0.65), 150),
+        })) ?? [{ width: 100 }];
+      return (
+        <TableCard withBorder={withBorder}>
+          <Box style={{ overflow: 'hidden', borderRadius: 'inherit' }}>
+            <MantineTable.ScrollContainer minWidth={minWidth}>
+              <MantineTable verticalSpacing="sm">
+                <MantineTable.Tbody>
+                  <TableSkeletonRows
+                    columns={skeletonColumns}
+                    rowCount={skeletonRowCount}
+                  />
+                </MantineTable.Tbody>
+              </MantineTable>
+            </MantineTable.ScrollContainer>
+          </Box>
+        </TableCard>
+      );
+    }
+
+    // Error: show error state
+    if (isError) {
+      return (
+        errorState ?? (
+          <ErrorState
+            title="Failed to load data"
+            description="An error occurred while fetching the data. Please try again."
+          />
+        )
+      );
+    }
+
+    // No data: show empty state
+    if (!hasData) {
+      return (
+        emptyState ?? (
+          <EmptyState
+            title="No data"
+            description="No records found to display."
+          />
+        )
+      );
+    }
+
+    // Has data: render table
+    return (
+      <Box
+        style={
+          isRefetching
+            ? {
+                opacity: refetchingOpacity,
+                pointerEvents: 'none',
+                transition: 'opacity 150ms',
+              }
+            : undefined
+        }
+      >
+        <TableCard withBorder={withBorder}>
+          <Box style={{ overflow: 'hidden', borderRadius: 'inherit' }}>
+            <MantineTable.ScrollContainer minWidth={minWidth}>
+              <MantineTable
+                highlightOnHover
+                verticalSpacing="sm"
+                layout={tableLayout}
+              >
+                {/* Table Headers */}
+                <MantineTable.Thead
+                  bg={tokens.color.background.subduedUltralight}
+                >
+                  {table.getHeaderGroups().map(headerGroup => (
+                    <MantineTable.Tr key={headerGroup.id}>
+                      {showRowSelection && (
+                        <MantineTable.Th w={40}>
+                          <Checkbox
+                            checked={table.getIsAllRowsSelected()}
+                            indeterminate={
+                              table.getIsSomeRowsSelected() &&
+                              !table.getIsAllRowsSelected()
+                            }
+                            onChange={table.getToggleAllRowsSelectedHandler()}
+                            aria-label="Select all rows"
+                          />
+                        </MantineTable.Th>
+                      )}
+                      {showExpandCell && (
+                        <MantineTable.Th w={expandColumnWidth}>
+                          {expandColumnHeader ?? null}
+                        </MantineTable.Th>
+                      )}
+                      {headerGroup.headers.map(header => {
+                        const isPinned = header.column.getIsPinned();
+                        const isConfiguratorHost =
+                          configurableColumns.length > 0 &&
+                          header.column.id === 'actions';
+                        const stickyConfiguratorStyle:
+                          | CSSProperties
+                          | undefined = isConfiguratorHost
+                          ? {
+                              position: 'sticky',
+                              right:
+                                isPinned === 'right'
+                                  ? header.column.getAfter()
+                                  : 0,
+                              zIndex: 3,
+                              background:
+                                tokens.color.background.subduedUltralight,
+                              boxShadow: tokens.shadow.sm,
+                            }
+                          : undefined;
+                        const pinnedStyle: CSSProperties | undefined = isPinned
+                          ? {
+                              position: 'sticky',
+                              left:
+                                header.column.getIsPinned() === 'left'
+                                  ? header.column.getStart()
+                                  : undefined,
+                              right:
+                                header.column.getIsPinned() === 'right'
+                                  ? header.column.getAfter()
+                                  : undefined,
+                              zIndex: 2,
+                              background:
+                                tokens.color.background.subduedUltralight,
+                              boxShadow:
+                                header.column.getIsPinned() === 'right'
+                                  ? tokens.shadow.sm
+                                  : undefined,
+                            }
+                          : undefined;
+                        const thStyle = stickyConfiguratorStyle ?? pinnedStyle;
+                        return (
+                          <MantineTable.Th
+                            key={header.id}
+                            w={header.getSize()}
+                            style={thStyle}
+                          >
+                            {isConfiguratorHost ? (
+                              <Flex justify="flex-end">
+                                {renderColumnConfiguratorMenu()}
+                              </Flex>
+                            ) : (
+                              renderHeaderCell(header)
+                            )}
+                          </MantineTable.Th>
+                        );
+                      })}
+                      {shouldRenderSyntheticActionsColumn && (
+                        <MantineTable.Th
+                          w={48}
+                          ta="right"
+                          style={{
+                            position: 'sticky',
+                            right: 0,
+                            zIndex: 3,
+                            background:
+                              tokens.color.background.subduedUltralight,
+                            boxShadow: tokens.shadow.sm,
+                          }}
+                        >
+                          <Flex justify="flex-end">
+                            {renderColumnConfiguratorMenu()}
+                          </Flex>
+                        </MantineTable.Th>
+                      )}
+                    </MantineTable.Tr>
+                  ))}
+                </MantineTable.Thead>
+
+                {/* Table Body */}
+                <MantineTable.Tbody>
+                  {rows.map(row => {
+                    // Snapshot expansion state here so the memoized row
+                    // components receive stable primitive props — see the
+                    // memo comparator comments on DataTableRow for why
+                    // calling `row.getIsExpanded()` inside the comparator
+                    // wouldn't detect transitions.
+                    const canExpand = row.getCanExpand();
+                    const isExpanded = row.getIsExpanded();
+                    const isGroupRow = canExpand;
+                    // Custom group row: render a single spanning TD. This
+                    // lets a group row look nothing like a leaf row (e.g.
+                    // different label, aggregates, background).
+                    if (isGroupRow && renderGroupRow) {
+                      const content = renderGroupRow(row);
+                      if (content != null) {
+                        const visibleCellCount = row.getVisibleCells().length;
+                        const colSpan =
+                          (showRowSelection ? 1 : 0) +
+                          (showExpandCell ? 1 : 0) +
+                          visibleCellCount +
+                          (shouldRenderSyntheticActionsColumn ? 1 : 0);
+                        return (
+                          <DataTableGroupRow
+                            key={row.id}
+                            row={row}
+                            content={content}
+                            colSpan={colSpan}
+                            background={resolvedGroupRowBackground}
+                            disableRowClick={disableRowClickForGroupRows}
+                            isExpanded={isExpanded}
+                          />
+                        );
+                      }
+                    }
+                    // Group rows are clickable whenever group-row clicking
+                    // isn't suppressed. Leaf rows keep the historical rule:
+                    // clickable when selection is on or when onRowClick is
+                    // provided.
+                    const isClickable = isGroupRow
+                      ? !disableRowClickForGroupRows
+                      : showRowSelection || !!onRowClick;
+                    return (
+                      <DataTableRow
+                        key={row.id}
+                        row={row}
+                        rowData={row.original}
+                        isSelected={showRowSelection && row.getIsSelected()}
+                        showRowSelection={showRowSelection}
+                        isClickable={isClickable}
+                        onRowClick={onRowClick}
+                        onRowHover={onRowHover}
+                        rowClassName={rowClassName}
+                        activeRowId={activeRowId}
+                        showSyntheticActionsColumn={
+                          shouldRenderSyntheticActionsColumn
+                        }
+                        showExpandCell={showExpandCell}
+                        disableRowClickForGroupRows={
+                          disableRowClickForGroupRows
+                        }
+                        isExpanded={isExpanded}
+                        canExpand={canExpand}
+                        groupRowBackground={resolvedGroupRowBackground}
+                      />
+                    );
+                  })}
+                </MantineTable.Tbody>
+
+                {/* Table Footer — emitted only when at least one column
+                    defines a `footer` template. Mirrors the header layout:
+                    leading selection/expand spacer cells, then per-column
+                    footer cells, then optional synthetic actions spacer. */}
+                {hasFooter && (
+                  <MantineTable.Tfoot
+                    bg={tokens.color.background.subduedUltralight}
+                  >
+                    {footerGroups.map(footerGroup => (
+                      <MantineTable.Tr key={footerGroup.id}>
+                        {showRowSelection && <MantineTable.Td />}
+                        {showExpandCell && <MantineTable.Td />}
+                        {footerGroup.headers.map(header => {
+                          const meta = header.column.columnDef.meta as
+                            | { align?: string }
+                            | undefined;
+                          const footerTemplate = header.column.columnDef.footer;
+                          const isPinned = header.column.getIsPinned();
+                          const pinnedStyle: CSSProperties | undefined =
+                            isPinned
+                              ? {
+                                  position: 'sticky',
+                                  left:
+                                    isPinned === 'left'
+                                      ? header.column.getStart()
+                                      : undefined,
+                                  right:
+                                    isPinned === 'right'
+                                      ? header.column.getAfter()
+                                      : undefined,
+                                  zIndex: 2,
+                                  background:
+                                    tokens.color.background.subduedUltralight,
+                                  boxShadow:
+                                    isPinned === 'right'
+                                      ? tokens.shadow.sm
+                                      : undefined,
+                                }
+                              : undefined;
+                          const cellStyle: CSSProperties = {
+                            ...(meta?.align && {
+                              textAlign:
+                                meta.align as CSSProperties['textAlign'],
+                            }),
+                            ...pinnedStyle,
+                          };
+                          return (
+                            <MantineTable.Td key={header.id} style={cellStyle}>
+                              {header.isPlaceholder || footerTemplate == null
+                                ? null
+                                : flexRender(
+                                    footerTemplate,
+                                    header.getContext(),
+                                  )}
+                            </MantineTable.Td>
+                          );
+                        })}
+                        {shouldRenderSyntheticActionsColumn && (
+                          <MantineTable.Td
+                            style={{
+                              position: 'sticky',
+                              right: 0,
+                              zIndex: 2,
+                              background:
+                                tokens.color.background.subduedUltralight,
+                              boxShadow: tokens.shadow.sm,
+                            }}
+                          />
+                        )}
+                      </MantineTable.Tr>
+                    ))}
+                  </MantineTable.Tfoot>
+                )}
+              </MantineTable>
+            </MantineTable.ScrollContainer>
+          </Box>
+        </TableCard>
+      </Box>
+    );
+  };
+
+  return (
+    <>
+      {renderContent()}
+      {hasData && (
+        <InfiniteScrollTrigger
+          {...pagination}
+          loadingMessage={infiniteScrollMessage}
+          endMessage={infiniteScrollEndMessage}
+        />
+      )}
+    </>
+  );
+}