@dashforge/tw 0.6.0-beta → 0.8.0-beta

package/src/components/DataGrid/DataGrid.tsx

@@ -0,0 +1,1199 @@
+import {
+  useMemo,
+  type ReactNode,
+  type MouseEvent,
+  type PointerEvent as RPointerEvent,
+} from 'react';
+import { cn } from '../../utils/cn.js';
+import { useAccessState } from '../../hooks/useAccessState.js';
+import { Skeleton } from '../Skeleton/Skeleton.js';
+import { Pagination } from '../Pagination/Pagination.js';
+import { dataGridVariants } from './dataGrid.variants.js';
+import { useControllableState } from '../_shared/data/useControllableState.js';
+import { useDebouncedValue } from '../_shared/data/useDebouncedValue.js';
+import { useTableSearch } from '../_shared/data/useTableSearch.js';
+import { useTableFilter } from '../_shared/data/useTableFilter.js';
+import { useTableSort, cycleSortFor } from '../_shared/data/useTableSort.js';
+import { useTableSelection } from '../_shared/data/useTableSelection.js';
+import { getNestedValue } from '../_shared/data/getNestedValue.js';
+import { useVirtualizer } from '../_shared/data/useVirtualizer.js';
+import {
+  useColumnAutoDetect,
+  resolveAlign,
+  resolveMonospace,
+  resolveTabularNums,
+} from '../_shared/data/useColumnAutoDetect.js';
+import type {
+  TableColumn,
+  TableColumnInferredType,
+  TableFilterType,
+  TableSortModel,
+  TableFilterModel,
+  TableLabels,
+} from '../Table/table.types.js';
+import type { DataGridProps } from './dataGrid.types.js';
+import { ColumnFilterTrigger } from './filters/ColumnFilters.js';
+import { ColumnVisibilityTrigger } from './visibility/ColumnVisibilityDialog.js';
+import { useColumnResize } from './resize/useColumnResize.js';
+import {
+  useColumnReorder,
+  type ColumnReorderHandlers,
+} from './reorder/useColumnReorder.js';
+
+const DEFAULT_LABELS: Required<TableLabels> = {
+  searchPlaceholder: 'Search...',
+  noData: 'No data',
+  loading: 'Loading…',
+  ariaSortNone: 'Not sorted. Click to sort ascending.',
+  ariaSortAscending: 'Sorted ascending. Click to sort descending.',
+  ariaSortDescending: 'Sorted descending. Click to clear sort.',
+  ariaSelectRow: 'Select row',
+  ariaSelectAllRows: 'Select all rows',
+  ariaExpandRow: 'Expand row',
+  ariaCollapseRow: 'Collapse row',
+  selectedCount: '{count} selected',
+  clearSelection: 'Clear selection',
+  filterColumn: 'Filter',
+  filterApply: 'Apply',
+  filterClear: 'Clear',
+  filterMin: 'Min',
+  filterMax: 'Max',
+  filterFrom: 'From',
+  filterTo: 'To',
+  filterAll: 'All',
+  filterTrue: 'True',
+  filterFalse: 'False',
+  density: 'Density',
+  densityCompact: 'Compact',
+  densityComfortable: 'Comfortable',
+  densitySpacious: 'Spacious',
+  columnsButton: 'Columns',
+  columnsTitle: 'Manage columns',
+  columnsDescription:
+    'Show or hide columns. Required columns cannot be toggled.',
+  columnsShowAll: 'Show all',
+  columnsHideAll: 'Hide all',
+  columnsDone: 'Done',
+};
+
+/**
+ * Dashforge TW `<DataGrid>` — virtualized data table.
+ *
+ * Companion to `<Table>` for large data sets (~500+ rows up to
+ * millions via virtualization). Same column model, sort/search/
+ * filter/selection logic (shared via `_shared/data/` helpers) —
+ * differs in render path: only the visible window of rows is mounted
+ * in DOM, with spacer `<tr>` above and below to preserve scrollbar
+ * size.
+ *
+ * Virtualization: hand-rolled (`useVirtualizer`) using
+ * `IntersectionObserver` + scroll-event + `requestAnimationFrame`
+ * debounce + `ResizeObserver`. Zero new runtime deps.
+ *
+ * Server-side mode (4 independent opt-in flags):
+ *  - `serverSideSort` — emits `onSortChange` but does NOT sort locally
+ *  - `serverSideFilter` — emits `onFilterChange` but does NOT filter
+ *  - `serverSideSearch` — emits `onSearchQueryChange` (debounced)
+ *  - `serverSidePagination` — `totalCount` prop sizes the virtual
+ *    scrollbar; `rows` is the page slice from the server
+ *
+ * Selection at scale: `selectAllScope`:
+ *  - `'allLoaded'` (default) — header checkbox toggles all rows in
+ *    `rows` prop
+ *  - `'visible'` — toggles only the current viewport window
+ */
+export function DataGrid<T extends object>(props: DataGridProps<T>) {
+  const {
+    rows,
+    cols,
+    getRowId,
+    totalCount: totalCountProp,
+
+    rowHeight,
+    overscan = 5,
+    height,
+
+    sortModel: sortModelProp,
+    onSortChange,
+    defaultSortModel,
+    serverSideSort = false,
+
+    enableSearch = false,
+    searchQuery: searchQueryProp,
+    onSearchQueryChange,
+    searchPlaceholder,
+    searchDebounceMs = 200,
+    serverSideSearch = false,
+
+    filterModel: filterModelProp,
+    onFilterChange,
+    serverSideFilter = false,
+
+    hiddenColumns: hiddenColumnsProp,
+    onHiddenColumnsChange,
+    enableColumnVisibility = true,
+
+    columnWidths: columnWidthsProp,
+    onColumnWidthsChange,
+    enableColumnResize = true,
+
+    columnOrder: columnOrderProp,
+    onColumnOrderChange,
+    enableColumnReorder = true,
+
+    rowSelection = 'none',
+    selectedRowIds: selectedRowIdsProp,
+    onSelectionChange,
+    bulkActions,
+    selectAllScope = 'allLoaded',
+
+    pagination,
+    serverSidePagination = false,
+
+    rowActions,
+
+    loading = false,
+    loadingRowCount = 8,
+    emptyState,
+
+    stickyHeader = true,
+    caption,
+    showCaption = false,
+
+    access: gridAccess,
+
+    labels: labelsProp,
+
+    variant,
+    size,
+    density,
+
+    sx,
+    slotProps,
+  } = props;
+
+  const labels = { ...DEFAULT_LABELS, ...labelsProp };
+  const gridAccessState = useAccessState(gridAccess);
+
+  // ───── Controllable state ─────
+
+  const [sortModel, setSortModel] = useControllableState<TableSortModel>({
+    controlledValue: sortModelProp,
+    defaultValue: defaultSortModel ?? [],
+    onChange: onSortChange,
+  });
+  const [searchQuery, setSearchQuery] = useControllableState<string>({
+    controlledValue: searchQueryProp,
+    defaultValue: '',
+    onChange: onSearchQueryChange,
+  });
+  // filterModel: in v1-bis the per-column header UI commits filter
+  // items to this controllable state. Consumer can lift it via
+  // filterModelProp + onFilterChange to drive server-side filtering.
+  const [filterModel, setFilterModel] = useControllableState<TableFilterModel>({
+    controlledValue: filterModelProp,
+    defaultValue: [],
+    onChange: onFilterChange,
+  });
+  const [selectedRowIds, setSelectedRowIds] = useControllableState<string[]>({
+    controlledValue: selectedRowIdsProp,
+    defaultValue: [],
+    onChange: onSelectionChange,
+  });
+
+  // ───── Column visibility ─────
+  // Seed default hidden set from `defaultHidden` flag on columns.
+  // Memoized to avoid the seed shifting on every render — the
+  // controllable state keeps internal state stable thereafter.
+  const defaultHiddenColumns = useMemo(
+    () =>
+      cols
+        .filter((c) => c.defaultHidden === true)
+        .map((c) => c.field as string),
+    [cols],
+  );
+  const [hiddenColumns, setHiddenColumns] = useControllableState<string[]>({
+    controlledValue: hiddenColumnsProp,
+    defaultValue: defaultHiddenColumns,
+    onChange: onHiddenColumnsChange,
+  });
+
+  // ───── Column widths (resize state) ─────
+  // Seed from any `col.width` declared statically. Internal state is
+  // applied only when the user actually starts dragging; until then
+  // we fall back to the static width from the column def.
+  const defaultColumnWidths = useMemo(() => {
+    const map: Record<string, number> = {};
+    for (const c of cols) {
+      if (typeof c.width === 'number') {
+        map[c.field as string] = c.width;
+      }
+    }
+    return map;
+  }, [cols]);
+  const [columnWidths, setColumnWidths] = useControllableState<
+    Record<string, number>
+  >({
+    controlledValue: columnWidthsProp,
+    defaultValue: defaultColumnWidths,
+    onChange: onColumnWidthsChange,
+  });
+  const { startResize } = useColumnResize({
+    widths: columnWidths,
+    onChange: setColumnWidths,
+  });
+
+  // ───── Column order (reorder state) ─────
+  const defaultColumnOrder = useMemo(
+    () => cols.map((c) => c.field as string),
+    [cols],
+  );
+  const [columnOrder, setColumnOrder] = useControllableState<string[]>({
+    controlledValue: columnOrderProp,
+    defaultValue: defaultColumnOrder,
+    onChange: onColumnOrderChange,
+  });
+  const reorderHandlers = useColumnReorder({
+    order: columnOrder,
+    onChange: setColumnOrder,
+  });
+
+  // Apply the active order to the columns list. Cols not in the
+  // order array (e.g. newly-added columns at runtime) are appended
+  // in their original position from `cols`.
+  const orderedCols = useMemo(() => {
+    if (!columnOrder || columnOrder.length === 0) return cols;
+    const byField = new Map(
+      cols.map((c) => [c.field as string, c] as const),
+    );
+    const seen = new Set<string>();
+    const result: typeof cols = [];
+    for (const field of columnOrder) {
+      const c = byField.get(field);
+      if (c) {
+        result.push(c);
+        seen.add(field);
+      }
+    }
+    for (const c of cols) {
+      if (!seen.has(c.field as string)) result.push(c);
+    }
+    return result;
+  }, [cols, columnOrder]);
+
+  // ───── RBAC + visibility + reorder: derive final column list ─────
+  //  - `access.onUnauthorized === 'hide'` removes a column entirely.
+  //  - `hiddenColumns` is the user-toggled hidden set from the
+  //    column-visibility dialog.
+  //  - `orderedCols` is the user-reordered version of `cols`.
+  // NOTE: filtering happens on `orderedCols` so the active order is
+  // preserved through visibility changes.
+  const visibleCols = useMemo(
+    () =>
+      orderedCols.filter((col) => {
+        if (col.access && col.access.onUnauthorized === 'hide') return false;
+        if (hiddenColumns.includes(col.field as string)) return false;
+        return true;
+      }),
+    [orderedCols, hiddenColumns],
+  );
+
+  // ───── Smart-default column types ─────
+  const columnTypes = useColumnAutoDetect(rows, visibleCols);
+
+  // ───── Pipeline: search → filter → sort (skip when server-side) ─────
+  //
+  // Each pipeline hook is ALWAYS called (React hooks rules). The
+  // server-side flags decide whether to use the local-computed result
+  // or pass the upstream rows through unchanged. The hooks are
+  // `useMemo`-based internally so they're cheap when their inputs
+  // are unchanged.
+
+  const debouncedSearchQuery = useDebouncedValue(searchQuery, searchDebounceMs);
+  const localSearched = useTableSearch(rows, visibleCols, debouncedSearchQuery);
+  const searchedRows = serverSideSearch ? rows : localSearched;
+
+  const localFiltered = useTableFilter(searchedRows, filterModel);
+  const filteredRows = serverSideFilter ? searchedRows : localFiltered;
+
+  const localSorted = useTableSort(filteredRows, visibleCols, sortModel);
+  const sortedRows = serverSideSort ? filteredRows : localSorted;
+
+  // ───── Virtualization ─────
+
+  // Effective row count for the virtual scrollbar:
+  // - Client-side: actual sorted rows count
+  // - Server-side pagination: caller-provided totalCount
+  const effectiveTotalCount = serverSidePagination
+    ? totalCountProp ?? sortedRows.length
+    : sortedRows.length;
+
+  const initialViewportHeight = height ? parseInt(height, 10) || 400 : 400;
+  const { scrollRef, window: vWindow } = useVirtualizer({
+    totalCount: effectiveTotalCount,
+    rowHeight,
+    overscan,
+    initialViewportHeight,
+  });
+
+  // The rows actually mounted in DOM.
+  const renderedRows = useMemo(() => {
+    if (serverSidePagination) {
+      // In server-side pagination, `rows` IS the page slice; we
+      // render all of it (virtualization within the page is still
+      // useful for very large page sizes).
+      return rows.slice(vWindow.startIndex, vWindow.endIndex + 1);
+    }
+    return sortedRows.slice(vWindow.startIndex, vWindow.endIndex + 1);
+  }, [serverSidePagination, rows, sortedRows, vWindow.startIndex, vWindow.endIndex]);
+
+  // ───── Selection helpers ─────
+
+  // For `selectAllScope='visible'`, the select-all scope is the
+  // current window. For `'allLoaded'`, it's the whole sorted set.
+  const selectAllPool = useMemo(() => {
+    if (selectAllScope === 'visible') {
+      return renderedRows.map((row, idx) =>
+        getRowId(row, vWindow.startIndex + idx),
+      );
+    }
+    return sortedRows.map((row, idx) => getRowId(row, idx));
+  }, [selectAllScope, renderedRows, sortedRows, getRowId, vWindow.startIndex]);
+
+  const selection = useTableSelection(rowSelection, selectedRowIds, setSelectedRowIds);
+
+  const selectedRows = useMemo(
+    () => sortedRows.filter((row, idx) => selection.isSelected(getRowId(row, idx))),
+    [sortedRows, selection, getRowId],
+  );
+
+  // ───── Variant recipe ─────
+  const v = dataGridVariants({ variant, size, density });
+
+  // ───── Render ─────
+
+  if (!gridAccessState.visible) return null;
+
+  const isInteractive = !gridAccessState.disabled;
+  const showSelectionColumn = rowSelection !== 'none';
+  const showRowActionsColumn = rowActions != null;
+
+  const totalColumnCount =
+    visibleCols.length +
+    (showSelectionColumn ? 1 : 0) +
+    (showRowActionsColumn ? 1 : 0);
+
+  return (
+    <div
+      className={cn(v.root(), sx, slotProps?.root?.className)}
+      data-disabled={!isInteractive ? 'true' : undefined}
+    >
+      {/* ───── Toolbar ───── */}
+      {(enableSearch || enableColumnVisibility) && (
+        <div className={cn(v.toolbar(), slotProps?.toolbar?.className)}>
+          {enableSearch && (
+            <label className={cn(v.search(), slotProps?.search?.className)}>
+              <span className="sr-only">{labels.searchPlaceholder}</span>
+              <SearchIcon className="ml-2 shrink-0 text-neutral-500" />
+              <input
+                type="text"
+                value={searchQuery}
+                onChange={(e) => setSearchQuery(e.target.value)}
+                placeholder={searchPlaceholder ?? labels.searchPlaceholder}
+                disabled={!isInteractive}
+                className={cn(
+                  'flex-1 bg-transparent border-0 outline-none',
+                  'px-2 py-1.5',
+                  'placeholder:text-neutral-400',
+                  'disabled:opacity-50 disabled:cursor-not-allowed',
+                )}
+              />
+            </label>
+          )}
+          {enableColumnVisibility && (
+            <ColumnVisibilityTrigger
+              cols={cols.filter(
+                (c) =>
+                  // RBAC-hidden columns are never offered in the dialog.
+                  !c.access || c.access.onUnauthorized !== 'hide',
+              )}
+              hiddenColumns={hiddenColumns}
+              onChange={setHiddenColumns}
+              disabled={!isInteractive}
+              labels={{
+                columnsButton: labels.columnsButton,
+                columnsTitle: labels.columnsTitle,
+                columnsDescription: labels.columnsDescription,
+                columnsShowAll: labels.columnsShowAll,
+                columnsHideAll: labels.columnsHideAll,
+                columnsDone: labels.columnsDone,
+              }}
+            />
+          )}
+        </div>
+      )}
+
+      {/* ───── Scroll wrapper (bounded height — required for virt) ───── */}
+      <div
+        ref={scrollRef}
+        className={cn(v.scroll(), slotProps?.scroll?.className)}
+        style={height ? { height, maxHeight: height } : undefined}
+      >
+        <table className={cn(v.table(), slotProps?.table?.className)}>
+          {caption != null && (
+            <caption className={cn(!showCaption && 'sr-only', 'py-2 text-sm text-neutral-500')}>
+              {caption}
+            </caption>
+          )}
+
+          <thead
+            className={cn(
+              stickyHeader ? v.thead() : 'bg-neutral-50',
+              slotProps?.thead?.className,
+            )}
+          >
+            <tr className={cn(v.headerRow(), slotProps?.headerRow?.className)}>
+              {showSelectionColumn && (
+                <th
+                  scope="col"
+                  className={cn(
+                    v.headerCell(),
+                    v.selectionCell(),
+                    v.stickyLeftHeaderCell(),
+                    slotProps?.headerCell?.className,
+                    slotProps?.selectionCell?.className,
+                  )}
+                >
+                  {rowSelection === 'multiple' && (
+                    <input
+                      type="checkbox"
+                      aria-label={labels.ariaSelectAllRows}
+                      checked={selection.isAllSelected(selectAllPool)}
+                      ref={(el) => {
+                        if (el)
+                          el.indeterminate = selection.isIndeterminate(selectAllPool);
+                      }}
+                      onChange={() => selection.toggleAll(selectAllPool)}
+                      disabled={!isInteractive}
+                      className="cursor-pointer"
+                    />
+                  )}
+                </th>
+              )}
+
+              {visibleCols.map((col) => (
+                <HeaderCell
+                  key={col.field as string}
+                  col={col}
+                  sortModel={sortModel}
+                  onSortClick={(e) =>
+                    handleSortClick(col, e, sortModel, setSortModel)
+                  }
+                  inferredType={columnTypes.get(col.field as string)}
+                  filterModel={filterModel}
+                  onFilterChange={setFilterModel}
+                  effectiveWidth={resolveColumnWidth(col, columnWidths)}
+                  resizable={
+                    enableColumnResize && col.resizable !== false
+                  }
+                  startResize={startResize}
+                  reorderable={
+                    enableColumnReorder && col.reorderable !== false
+                  }
+                  reorderHandlers={reorderHandlers}
+                  labels={labels}
+                  className={cn(
+                    v.headerCell(),
+                    col.sticky === 'left' && v.stickyLeftHeaderCell(),
+                    col.sticky === 'right' && v.stickyRightHeaderCell(),
+                    slotProps?.headerCell?.className,
+                  )}
+                  buttonClassName={v.headerCellButton()}
+                  disabled={!isInteractive}
+                />
+              ))}
+
+              {showRowActionsColumn && (
+                <th
+                  scope="col"
+                  aria-hidden="true"
+                  className={cn(
+                    v.headerCell(),
+                    'w-12',
+                    slotProps?.headerCell?.className,
+                  )}
+                />
+              )}
+            </tr>
+          </thead>
+
+          <tbody className={cn(v.tbody(), slotProps?.tbody?.className)}>
+            {loading
+              ? renderLoadingRows({
+                  count: loadingRowCount,
+                  visibleCols,
+                  showSelectionColumn,
+                  showRowActionsColumn,
+                  rowHeight,
+                  rowClass: cn(v.row(), slotProps?.row?.className),
+                  cellClass: cn(v.cell(), slotProps?.cell?.className),
+                })
+              : sortedRows.length === 0
+                ? renderEmptyState({
+                    totalColumnCount,
+                    emptyState,
+                    fallback: labels.noData,
+                    cellClass: cn(
+                      v.cell(),
+                      v.emptyState(),
+                      slotProps?.emptyState?.className,
+                    ),
+                  })
+                : renderVirtualizedBody({
+                    vWindow,
+                    rowHeight,
+                    renderedRows,
+                    visibleCols,
+                    columnTypes,
+                    columnWidths,
+                    selection,
+                    rowSelection,
+                    showSelectionColumn,
+                    showRowActionsColumn,
+                    rowActions,
+                    getRowId,
+                    isInteractive,
+                    labels,
+                    serverSidePagination,
+                    classes: {
+                      row: cn(v.row(), slotProps?.row?.className),
+                      cell: cn(v.cell(), slotProps?.cell?.className),
+                      selectionCell: cn(
+                        v.cell(),
+                        v.selectionCell(),
+                        v.stickyLeftCell(),
+                        slotProps?.cell?.className,
+                        slotProps?.selectionCell?.className,
+                      ),
+                      stickyLeftCell: v.stickyLeftCell(),
+                      stickyRightCell: v.stickyRightCell(),
+                      rowActionsCell: cn(
+                        v.cell(),
+                        v.rowActionsCell(),
+                        slotProps?.cell?.className,
+                        slotProps?.rowActionsCell?.className,
+                      ),
+                    },
+                  })}
+          </tbody>
+        </table>
+      </div>
+
+      {/* ───── Bulk action footer ───── */}
+      {bulkActions && selectedRows.length > 0 && (
+        <div
+          className={cn(v.bulkActionFooter(), slotProps?.bulkActionFooter?.className)}
+          role="region"
+          aria-label={labels.selectedCount.replace(
+            '{count}',
+            String(selectedRows.length),
+          )}
+        >
+          <span className="text-sm text-neutral-700">
+            {labels.selectedCount.replace('{count}', String(selectedRows.length))}
+          </span>
+          <div className="flex items-center gap-2">
+            {bulkActions(selectedRows)}
+            <button
+              type="button"
+              onClick={selection.clearSelection}
+              className={cn(
+                'text-sm text-neutral-500 hover:text-neutral-900',
+                'underline-offset-2 hover:underline',
+                'focus:outline-none focus-visible:underline',
+              )}
+            >
+              {labels.clearSelection}
+            </button>
+          </div>
+        </div>
+      )}
+
+      {/* ───── Optional pagination footer ───── */}
+      {pagination && (
+        <div className={cn(v.paginationFooter(), slotProps?.pagination?.className)}>
+          <Pagination
+            page={pagination.page}
+            pageSize={pagination.pageSize}
+            totalCount={totalCountProp ?? sortedRows.length}
+            onPageChange={pagination.onPageChange}
+            onPageSizeChange={pagination.onPageSizeChange}
+            pageSizeOptions={pagination.pageSizeOptions}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ───── Header cell ─────
+
+function HeaderCell<T extends object>(props: {
+  col: TableColumn<T>;
+  sortModel: TableSortModel;
+  onSortClick: (e: MouseEvent<HTMLButtonElement>) => void;
+  inferredType: string | undefined;
+  filterModel: TableFilterModel;
+  onFilterChange: (model: TableFilterModel) => void;
+  effectiveWidth: number | undefined;
+  resizable: boolean;
+  startResize: (
+    field: string,
+    startWidth: number,
+    clampMin: number,
+    clampMax: number,
+  ) => (e: RPointerEvent<HTMLElement>) => void;
+  reorderable: boolean;
+  reorderHandlers: ColumnReorderHandlers;
+  labels: Required<TableLabels>;
+  className: string;
+  buttonClassName: string;
+  disabled: boolean;
+}) {
+  const {
+    col,
+    sortModel,
+    onSortClick,
+    inferredType,
+    filterModel,
+    onFilterChange,
+    effectiveWidth,
+    resizable,
+    startResize,
+    reorderable,
+    reorderHandlers,
+    labels,
+    className,
+    buttonClassName,
+    disabled,
+  } = props;
+
+  const align = resolveAlign(col, inferredType as never);
+  const alignClass =
+    align === 'right' ? 'text-right' : align === 'center' ? 'text-center' : 'text-left';
+
+  const sortEntry = sortModel.find((s) => s.field === col.field);
+  const ariaSort: 'ascending' | 'descending' | 'none' =
+    sortEntry?.direction === 'asc'
+      ? 'ascending'
+      : sortEntry?.direction === 'desc'
+        ? 'descending'
+        : 'none';
+
+  const headerContent =
+    typeof col.header === 'function' ? col.header() : col.header;
+
+  const cellStyle = {
+    width: effectiveWidth != null ? `${effectiveWidth}px` : undefined,
+    minWidth: col.minWidth != null ? `${col.minWidth}px` : undefined,
+    flex: effectiveWidth != null ? undefined : col.flex,
+    position: resizable || reorderable ? ('relative' as const) : undefined,
+  };
+
+  // Drop indicator for reorder: a 2px vertical bar at the LEFT or
+  // RIGHT edge of this th when it's the active drop target.
+  const dropTarget = reorderHandlers.dropTarget;
+  const dropIndicatorClass =
+    dropTarget != null && dropTarget.field === (col.field as string)
+      ? dropTarget.side === 'left'
+        ? 'before:absolute before:top-0 before:bottom-0 before:left-0 before:w-0.5 before:bg-primary-500'
+        : 'after:absolute after:top-0 after:bottom-0 after:right-0 after:w-0.5 after:bg-primary-500'
+      : '';
+
+  const isDragging = reorderHandlers.draggingField === (col.field as string);
+
+  // Drag attributes only attach when reorderable; we DO NOT make the
+  // entire th `draggable` if it isn't — keeps the keyboard focus
+  // behavior unchanged.
+  const dragAttrs = reorderable
+    ? {
+        draggable: true,
+        onDragStart: reorderHandlers.dragStart(col.field as string),
+        onDragOver: reorderHandlers.dragOver(col.field as string),
+        onDrop: reorderHandlers.drop(col.field as string),
+        onDragEnd: reorderHandlers.dragEnd,
+      }
+    : {};
+
+  const resizeHandle = resizable ? (
+    <span
+      role="separator"
+      aria-orientation="vertical"
+      aria-label={`Resize ${typeof col.header === 'string' ? col.header : col.field}`}
+      onPointerDown={(e) => {
+        const handle = e.currentTarget;
+        const th = handle.parentElement as HTMLElement | null;
+        const startWidth =
+          effectiveWidth ?? th?.getBoundingClientRect().width ?? 120;
+        const min = col.minWidth ?? 40;
+        const max = col.maxWidth ?? 1200;
+        startResize(col.field as string, startWidth, min, max)(e);
+      }}
+      className={cn(
+        'absolute top-0 bottom-0 right-0 w-1.5',
+        'cursor-col-resize select-none touch-none',
+        'hover:bg-primary-300 active:bg-primary-400',
+        'transition-colors motion-reduce:transition-none',
+      )}
+    />
+  ) : null;
+
+  const filterType = col.filterable
+    ? resolveFilterType(col, inferredType as TableColumnInferredType | undefined)
+    : null;
+
+  const filterTrigger =
+    col.filterable && filterType ? (
+      <ColumnFilterTrigger
+        field={col.field as string}
+        filterType={filterType}
+        filterModel={filterModel}
+        onFilterChange={onFilterChange}
+        disabled={disabled}
+        labels={{
+          filterColumn: labels.filterColumn,
+          filterApply: labels.filterApply,
+          filterClear: labels.filterClear,
+          filterMin: labels.filterMin,
+          filterMax: labels.filterMax,
+          filterFrom: labels.filterFrom,
+          filterTo: labels.filterTo,
+          filterAll: labels.filterAll,
+          filterTrue: labels.filterTrue,
+          filterFalse: labels.filterFalse,
+        }}
+      />
+    ) : null;
+
+  // Layout strategy:
+  //  - sortable only → sort button is the cell content
+  //  - filterable only → header text + filter trigger in a flex row
+  //  - both → sort button + filter trigger in a flex row
+  //  - neither → plain header text
+  const wrapperJustify =
+    align === 'right'
+      ? 'justify-end'
+      : align === 'center'
+        ? 'justify-center'
+        : 'justify-start';
+
+  if (col.sortable) {
+    const sortButton = (
+      <button
+        type="button"
+        onClick={onSortClick}
+        disabled={disabled}
+        aria-label={
+          ariaSort === 'ascending'
+            ? labels.ariaSortAscending
+            : ariaSort === 'descending'
+              ? labels.ariaSortDescending
+              : labels.ariaSortNone
+        }
+        className={cn(
+          buttonClassName,
+          align === 'right' && 'flex-row-reverse',
+          'disabled:cursor-not-allowed disabled:opacity-50',
+        )}
+      >
+        <span>{headerContent}</span>
+        <SortIcon direction={sortEntry?.direction} />
+      </button>
+    );
+    return (
+      <th
+        scope="col"
+        aria-sort={ariaSort}
+        className={cn(
+          className,
+          alignClass,
+          dropIndicatorClass,
+          isDragging && 'opacity-50',
+        )}
+        style={cellStyle}
+        {...dragAttrs}
+      >
+        {filterTrigger ? (
+          <div className={cn('flex items-center gap-1', wrapperJustify)}>
+            {sortButton}
+            {filterTrigger}
+          </div>
+        ) : (
+          sortButton
+        )}
+        {resizeHandle}
+      </th>
+    );
+  }
+
+  return (
+    <th
+      scope="col"
+      className={cn(
+        className,
+        alignClass,
+        dropIndicatorClass,
+        isDragging && 'opacity-50',
+      )}
+      style={cellStyle}
+      {...dragAttrs}
+    >
+      {filterTrigger ? (
+        <div className={cn('flex items-center gap-1', wrapperJustify)}>
+          <span>{headerContent}</span>
+          {filterTrigger}
+        </div>
+      ) : (
+        headerContent
+      )}
+      {resizeHandle}
+    </th>
+  );
+}
+
+/**
+ * Resolve the effective width (px) for a column. User-driven resize
+ * (`columnWidths[field]`) wins over the static `col.width`. Returns
+ * `undefined` if neither source has a width set — the consumer falls
+ * back to the column's `flex` value or browser auto-layout.
+ */
+function resolveColumnWidth<T extends object>(
+  col: TableColumn<T>,
+  columnWidths: Record<string, number>,
+): number | undefined {
+  const resized = columnWidths[col.field as string];
+  if (resized != null) return resized;
+  return col.width;
+}
+
+/**
+ * Resolve the filter UI type for a column. Explicit `col.filterType`
+ * wins; otherwise we map the auto-detected primitive type:
+ *  - `number` → number range
+ *  - `boolean` → true/false/all select
+ *  - `date` → date range
+ *  - anything else (string / unknown) → text contains
+ */
+function resolveFilterType<T extends object>(
+  col: TableColumn<T>,
+  inferred: TableColumnInferredType | undefined,
+): TableFilterType {
+  if (col.filterType) return col.filterType;
+  switch (inferred) {
+    case 'number':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'date':
+      return 'date';
+    default:
+      return 'text';
+  }
+}
+
+// ───── Virtualized body ─────
+
+function renderVirtualizedBody<T extends object>(args: {
+  vWindow: { startIndex: number; endIndex: number; paddingTop: number; paddingBottom: number };
+  rowHeight: number;
+  renderedRows: T[];
+  visibleCols: TableColumn<T>[];
+  columnTypes: Map<string, string>;
+  columnWidths: Record<string, number>;
+  selection: ReturnType<typeof useTableSelection>;
+  rowSelection: 'none' | 'single' | 'multiple';
+  showSelectionColumn: boolean;
+  showRowActionsColumn: boolean;
+  rowActions: ((row: T) => ReactNode) | undefined;
+  getRowId: (row: T, index: number) => string;
+  isInteractive: boolean;
+  labels: Required<TableLabels>;
+  serverSidePagination: boolean;
+  classes: {
+    row: string;
+    cell: string;
+    selectionCell: string;
+    stickyLeftCell: string;
+    stickyRightCell: string;
+    rowActionsCell: string;
+  };
+}): ReactNode {
+  const {
+    vWindow,
+    renderedRows,
+    visibleCols,
+    columnTypes,
+    columnWidths,
+    selection,
+    rowSelection,
+    showSelectionColumn,
+    showRowActionsColumn,
+    rowActions,
+    getRowId,
+    isInteractive,
+    labels,
+    classes,
+  } = args;
+
+  return (
+    <>
+      {vWindow.paddingTop > 0 && (
+        <tr aria-hidden="true" style={{ height: vWindow.paddingTop }} />
+      )}
+      {renderedRows.map((row, localIdx) => {
+        const absoluteIdx = vWindow.startIndex + localIdx;
+        const rowId = getRowId(row, absoluteIdx);
+        const isSelected = selection.isSelected(rowId);
+        return (
+          <tr
+            key={rowId}
+            data-selected={isSelected ? 'true' : 'false'}
+            aria-selected={rowSelection !== 'none' ? isSelected : undefined}
+            className={classes.row}
+          >
+            {showSelectionColumn && (
+              <td className={classes.selectionCell}>
+                <input
+                  type="checkbox"
+                  aria-label={labels.ariaSelectRow}
+                  checked={isSelected}
+                  onChange={() => selection.toggleRow(rowId)}
+                  disabled={!isInteractive}
+                  className="cursor-pointer"
+                />
+              </td>
+            )}
+            {visibleCols.map((col) => (
+              <DataCell
+                key={col.field as string}
+                col={col}
+                row={row}
+                rowIndex={absoluteIdx}
+                isSelected={isSelected}
+                inferredType={columnTypes.get(col.field as string)}
+                effectiveWidth={resolveColumnWidth(col, columnWidths)}
+                cellClass={classes.cell}
+                stickyLeftClass={classes.stickyLeftCell}
+                stickyRightClass={classes.stickyRightCell}
+              />
+            ))}
+            {showRowActionsColumn && rowActions && (
+              <td className={classes.rowActionsCell}>{rowActions(row)}</td>
+            )}
+          </tr>
+        );
+      })}
+      {vWindow.paddingBottom > 0 && (
+        <tr aria-hidden="true" style={{ height: vWindow.paddingBottom }} />
+      )}
+    </>
+  );
+}
+
+// ───── Data cell ─────
+
+function DataCell<T extends object>(props: {
+  col: TableColumn<T>;
+  row: T;
+  rowIndex: number;
+  isSelected: boolean;
+  inferredType: string | undefined;
+  effectiveWidth: number | undefined;
+  cellClass: string;
+  stickyLeftClass: string;
+  stickyRightClass: string;
+}) {
+  const {
+    col,
+    row,
+    rowIndex,
+    isSelected,
+    inferredType,
+    effectiveWidth,
+    cellClass,
+    stickyLeftClass,
+    stickyRightClass,
+  } = props;
+  const value = getNestedValue(row, col.field as string);
+  const align = resolveAlign(col, inferredType as never);
+  const tabularNums = resolveTabularNums(col, inferredType as never);
+  const monospace = resolveMonospace(col);
+  const alignClass =
+    align === 'right' ? 'text-right' : align === 'center' ? 'text-center' : 'text-left';
+
+  const columnAccessState = col.access
+    ? {
+        hidden: col.access.onUnauthorized === 'hide',
+        disabled: col.access.onUnauthorized === 'disable',
+        readonly: col.access.onUnauthorized === 'readonly',
+      }
+    : null;
+
+  const content = col.cellRenderer
+    ? col.cellRenderer({
+        row,
+        value,
+        rowIndex,
+        isSelected,
+        isExpanded: false, // DataGrid v1 doesn't support expansion (defer)
+        access: columnAccessState,
+      })
+    : renderDefaultCell(value);
+
+  return (
+    <td
+      className={cn(
+        cellClass,
+        alignClass,
+        tabularNums && 'tabular-nums',
+        monospace && 'font-mono',
+        col.sticky === 'left' && stickyLeftClass,
+        col.sticky === 'right' && stickyRightClass,
+      )}
+      style={{
+        width: effectiveWidth != null ? `${effectiveWidth}px` : undefined,
+        minWidth: col.minWidth != null ? `${col.minWidth}px` : undefined,
+      }}
+    >
+      {content}
+    </td>
+  );
+}
+
+// ───── Helpers ─────
+
+function renderDefaultCell(value: unknown): ReactNode {
+  if (value == null) return null;
+  if (typeof value === 'boolean') return value ? '✓' : '✗';
+  if (value instanceof Date) return value.toISOString().slice(0, 10);
+  if (typeof value === 'object') return JSON.stringify(value);
+  return value as ReactNode;
+}
+
+function handleSortClick<T extends object>(
+  col: TableColumn<T>,
+  event: MouseEvent<HTMLButtonElement>,
+  current: TableSortModel,
+  setSortModel: (
+    next: TableSortModel | ((prev: TableSortModel) => TableSortModel),
+  ) => void,
+) {
+  if (!col.sortable) return;
+  const multi = event.shiftKey;
+  setSortModel((prev) => cycleSortFor(prev, col.field as string, multi));
+}
+
+function renderLoadingRows<T extends object>(args: {
+  count: number;
+  visibleCols: TableColumn<T>[];
+  showSelectionColumn: boolean;
+  showRowActionsColumn: boolean;
+  rowHeight: number;
+  rowClass: string;
+  cellClass: string;
+}): ReactNode {
+  const {
+    count,
+    visibleCols,
+    showSelectionColumn,
+    showRowActionsColumn,
+    rowHeight,
+    rowClass,
+    cellClass,
+  } = args;
+  return Array.from({ length: count }).map((_, i) => (
+    <tr
+      key={`loading-${i}`}
+      className={rowClass}
+      aria-busy="true"
+      style={{ height: rowHeight }}
+    >
+      {showSelectionColumn && (
+        <td className={cellClass}>
+          <Skeleton variant="rectangle" width="16px" height="16px" />
+        </td>
+      )}
+      {visibleCols.map((col) => (
+        <td key={col.field as string} className={cellClass}>
+          <Skeleton variant="text" width="80%" />
+        </td>
+      ))}
+      {showRowActionsColumn && (
+        <td className={cellClass}>
+          <Skeleton variant="rectangle" width="24px" height="24px" />
+        </td>
+      )}
+    </tr>
+  ));
+}
+
+function renderEmptyState(args: {
+  totalColumnCount: number;
+  emptyState: ReactNode;
+  fallback: string;
+  cellClass: string;
+}): ReactNode {
+  return (
+    <tr>
+      <td colSpan={args.totalColumnCount} className={args.cellClass}>
+        {args.emptyState ?? args.fallback}
+      </td>
+    </tr>
+  );
+}
+
+// ───── Icons ─────
+
+function SortIcon(props: { direction?: 'asc' | 'desc' }) {
+  return (
+    <svg
+      width="0.75em"
+      height="0.75em"
+      viewBox="0 0 16 16"
+      fill="currentColor"
+      aria-hidden="true"
+      className="shrink-0 opacity-60 group-hover:opacity-100"
+    >
+      {props.direction === 'asc' ? (
+        <path d="M8 4l4 6H4z" />
+      ) : props.direction === 'desc' ? (
+        <path d="M8 12L4 6h8z" />
+      ) : (
+        <>
+          <path d="M8 3l3 4H5z" opacity="0.5" />
+          <path d="M8 13l-3-4h6z" opacity="0.5" />
+        </>
+      )}
+    </svg>
+  );
+}
+
+function SearchIcon(props: { className?: string }) {
+  return (
+    <svg
+      width="0.875em"
+      height="0.875em"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      className={props.className}
+    >
+      <circle cx="7" cy="7" r="4.5" />
+      <path d="M11 11l3 3" />
+    </svg>
+  );
+}