aplance-ui 1.0.1

package/registry/components/ui/data-table/data-table.tsx

@@ -0,0 +1,1109 @@
+import {
+  flexRender,
+  getCoreRowModel,
+  getExpandedRowModel,
+  getGroupedRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  useReactTable,
+  type Column,
+  type ColumnPinningState,
+  type PaginationState as TanstackPaginationState,
+  type Updater,
+} from "@tanstack/react-table";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type DragEvent as ReactDragEvent,
+  type ReactNode,
+} from "react";
+import clsx from "clsx";
+import { FilterBar } from "./filter-bar";
+import { PaginationBar } from "./pagination-bar";
+import { Loader } from "../loader/loader";
+import type {
+  BodyCellProps,
+  BodyRowProps,
+  DataTableMeta,
+  DataTableProps,
+  HeaderActionButtonProps,
+  HeaderCellProps,
+} from "./types";
+import {
+  columnId,
+  formatAggregated,
+  getColumnStyle,
+  isLastPinned,
+  normalizeColumnPinningState,
+  reorderColumnOrder,
+  resolveUpdater,
+  SELECT_COLUMN_ID,
+} from "./utils";
+import s from "./data-table.module.css";
+import { Tooltip } from "../tooltip/tooltip";
+import {
+  IconArrowsUpDown,
+  IconArrowUp,
+  IconArrowDown,
+  IconChevronRight,
+  IconGripVertical,
+  IconStack2,
+  IconStack3,
+  IconPinnedOff,
+  IconArrowLeft,
+  IconArrowRight,
+} from "@tabler/icons-react";
+import { getScrollbarWidth } from "../../../lib/dom";
+import { Button } from "../button/button";
+
+const DEFAULT_PAGE_SIZE_OPTIONS = [10, 20, 50];
+const DEFAULT_PAGINATION = { pageIndex: 0, pageSize: 10 };
+// Stable refs for optional handlers. Inline `= () => {}` defaults allocate a
+// fresh function each render, invalidating any memo that depends on them
+// (notably `meta` below, which passes `onUpdateData` through tanstack).
+const NOOP_FILTER = () => {};
+const NOOP_PAGINATION = () => {};
+const NOOP_UPDATE = () => {};
+const POINTER_STYLE = { cursor: "pointer" } as const;
+const EMPTY_FILTER_VALUES: Record<string, string> = {};
+const ICON_SIZE = 15;
+const SORT_ICON_SIZE = 13;
+const ICON_STROKE = 1.6;
+const EMPTY_COLUMN_EXTRA_WIDTHS: Record<string, number> = {};
+// Grace period after `isLoading` flips false before committing to the empty
+// state. Eliminates the flash when consumers set isLoading=false a render
+// before populating rows, without making genuinely-empty results feel sluggish.
+const EMPTY_STATE_GRACE_MS = 150;
+
+export const DataTable = <TData extends { id: string }>({
+  data,
+  columns,
+  isLoading = false,
+  emptyMessage = "No results found.",
+
+  filters = [],
+  filterValues = EMPTY_FILTER_VALUES,
+  onFilterChange = NOOP_FILTER,
+
+  sorting,
+  onSortingChange,
+  manualSorting = false,
+
+  showPagination = true,
+  pagination = DEFAULT_PAGINATION,
+  onPaginationChange = NOOP_PAGINATION,
+  totalPages,
+  totalCount,
+  pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
+  showPageSizeSelect = true,
+  rowLabel = "row",
+
+  rowsSelectable = false,
+  rowSelection = {},
+  onRowSelectionChange,
+
+  editingRowId = null,
+  onUpdateData = NOOP_UPDATE,
+
+  enableColumnOrdering = false,
+  columnOrder,
+  onColumnOrderChange,
+  enableColumnResizing = false,
+  columnSizing,
+  onColumnSizingChange,
+  enableColumnPinning = false,
+  columnPinning,
+  onColumnPinningChange,
+  enableRowOrdering = false,
+  onRowOrderChange,
+  columnVisibility,
+  onColumnVisibilityChange,
+
+  enableGrouping = false,
+  grouping,
+  onGroupingChange,
+  expanded,
+  onExpandedChange,
+
+  defaultColumnPinning,
+
+  showVerticalBorders = false,
+
+  onRow,
+  paginationExtra,
+  className,
+}: DataTableProps<TData>) => {
+  // ── Table meta ──────────────────────────────────────────────────────────────
+  const meta: DataTableMeta<TData> = useMemo(
+    () => ({ editingRowId, updateData: onUpdateData }),
+    [editingRowId, onUpdateData],
+  );
+
+  const shouldPinSelectionColumn =
+    rowsSelectable &&
+    columns.some((columnDef) => columnId(columnDef) === SELECT_COLUMN_ID);
+
+  const resolvedControlledColumnPinning = useMemo(
+    () =>
+      columnPinning === undefined
+        ? undefined
+        : normalizeColumnPinningState(
+            columnPinning,
+            shouldPinSelectionColumn,
+            defaultColumnPinning,
+          ),
+    [columnPinning, shouldPinSelectionColumn, defaultColumnPinning],
+  );
+
+  const initialColumnPinning = useMemo(
+    () =>
+      enableColumnPinning && columnPinning === undefined
+        ? normalizeColumnPinningState(
+            undefined,
+            shouldPinSelectionColumn,
+            defaultColumnPinning,
+          )
+        : undefined,
+    [
+      enableColumnPinning,
+      columnPinning,
+      shouldPinSelectionColumn,
+      defaultColumnPinning,
+    ],
+  );
+
+  const handleColumnPinningChange = useCallback(
+    (updater: Updater<ColumnPinningState>) => {
+      if (!onColumnPinningChange) return;
+
+      onColumnPinningChange((prev) => {
+        const normalizedPrev =
+          normalizeColumnPinningState(
+            prev,
+            shouldPinSelectionColumn,
+            defaultColumnPinning,
+          ) ?? {};
+        const next = resolveUpdater(updater, normalizedPrev);
+
+        // Newly right-pinned columns are inserted on the inner edge (closer
+        // to the center) so the recently-pinned column visually slides in
+        // next to the body, leaving previously-pinned columns flush against
+        // the viewport edge.
+        const prevRight = normalizedPrev.right ?? [];
+        const nextRight = next.right ?? [];
+        const addedToRight = nextRight.filter((id) => !prevRight.includes(id));
+        const keptInRight = nextRight.filter((id) => prevRight.includes(id));
+
+        return (
+          normalizeColumnPinningState(
+            { left: next.left, right: [...addedToRight, ...keptInRight] },
+            shouldPinSelectionColumn,
+            defaultColumnPinning,
+          ) ?? {}
+        );
+      });
+    },
+    [onColumnPinningChange, shouldPinSelectionColumn, defaultColumnPinning],
+  );
+
+  // ── TanStack table instance ─────────────────────────────────────────────────
+  // Filtering is delegated to the consumer (see `useDataTable.filterFn`), so we
+  // don't wire any tanstack filter row-model here - rows arrive pre-filtered.
+  // eslint-disable-next-line react-hooks/incompatible-library -- TanStack Table relies on function-returning APIs by design.
+  const table = useReactTable<TData>({
+    data,
+    columns,
+    enableRowSelection: rowsSelectable,
+    enableColumnResizing,
+    enableColumnPinning,
+    enableGrouping,
+    columnResizeMode: "onChange",
+    state: {
+      sorting,
+      ...(showPagination && {
+        pagination: pagination as TanstackPaginationState,
+      }),
+      ...(rowsSelectable && { rowSelection }),
+      ...(enableColumnOrdering && columnOrder && { columnOrder }),
+      ...(enableColumnResizing && columnSizing && { columnSizing }),
+      ...(enableColumnPinning &&
+        resolvedControlledColumnPinning && {
+          columnPinning: resolvedControlledColumnPinning,
+        }),
+      ...(columnVisibility && { columnVisibility }),
+      ...(enableGrouping && grouping && { grouping }),
+      ...(enableGrouping && expanded !== undefined && { expanded }),
+    },
+    initialState: {
+      ...(enableColumnPinning &&
+        initialColumnPinning && {
+          columnPinning: initialColumnPinning,
+        }),
+    },
+    onSortingChange,
+    ...(showPagination && {
+      onPaginationChange: (updater) => {
+        const cur = pagination as TanstackPaginationState;
+        const next = typeof updater === "function" ? updater(cur) : updater;
+        onPaginationChange(next);
+      },
+    }),
+    ...(rowsSelectable && onRowSelectionChange && { onRowSelectionChange }),
+    ...(enableColumnOrdering && onColumnOrderChange && { onColumnOrderChange }),
+    ...(enableColumnResizing &&
+      onColumnSizingChange && { onColumnSizingChange }),
+    ...(enableColumnPinning &&
+      onColumnPinningChange && {
+        onColumnPinningChange: handleColumnPinningChange,
+      }),
+    ...(onColumnVisibilityChange && { onColumnVisibilityChange }),
+    ...(enableGrouping && onGroupingChange && { onGroupingChange }),
+    ...(enableGrouping && onExpandedChange && { onExpandedChange }),
+    getRowId: (row) => row.id,
+    getCoreRowModel: getCoreRowModel(),
+    ...(!manualSorting && { getSortedRowModel: getSortedRowModel() }),
+    ...(showPagination && {
+      getPaginationRowModel: getPaginationRowModel(),
+      pageCount: totalPages ?? -1,
+    }),
+    ...(enableGrouping && {
+      // Keep grouped columns in place so header controls stay spatially stable.
+      groupedColumnMode: false,
+      getGroupedRowModel: getGroupedRowModel(),
+      getExpandedRowModel: getExpandedRowModel(),
+    }),
+    manualSorting,
+    manualPagination: showPagination,
+    meta,
+  });
+
+  // ── Column drag-and-drop reorder (HTML5 native, no extra deps) ──────────────
+  const [draggedColumnId, setDraggedColumnId] = useState<string | null>(null);
+  const [dropTargetColumnId, setDropTargetColumnId] = useState<string | null>(
+    null,
+  );
+
+  const handleColumnDrop = useCallback(
+    (sourceId: string, targetId: string) => {
+      if (sourceId === targetId) return;
+      const targetCol = table.getColumn(targetId);
+      // Refuse drops onto fixed columns (e.g. the row-select column) so they
+      // stay anchored in their position.
+      if (targetCol && targetCol.getCanHide() === false) return;
+      const current =
+        columnOrder && columnOrder.length
+          ? columnOrder
+          : table.getAllLeafColumns().map((c) => c.id);
+      const next = reorderColumnOrder(current, sourceId, targetId);
+      table.setColumnOrder(next);
+    },
+    [columnOrder, table],
+  );
+
+  const handleDragEnd = useCallback(() => {
+    setDraggedColumnId(null);
+    setDropTargetColumnId(null);
+  }, []);
+
+  const [draggedRowId, setDraggedRowId] = useState<string | null>(null);
+  const [dropTargetRowId, setDropTargetRowId] = useState<string | null>(null);
+
+  const handleDragStartRow = useCallback((id: string) => {
+    setDraggedRowId(id);
+  }, []);
+
+  const handleDragOverRow = useCallback((id: string | null) => {
+    setDropTargetRowId(id);
+  }, []);
+
+  const handleDragEndRow = useCallback(() => {
+    setDraggedRowId(null);
+    setDropTargetRowId(null);
+  }, []);
+
+  const handleDropRow = useCallback(
+    (draggedId: string, targetId: string) => {
+      const draggedRow = table.getRow(draggedId);
+      const targetRow = table.getRow(targetId);
+      if (draggedRow && targetRow) {
+        onRowOrderChange?.(draggedRow.original, targetRow.original);
+      }
+    },
+    [onRowOrderChange, table],
+  );
+
+  // ── Sync header/body scrolling ──────────────────────────────────────────────
+  // The header lives in its own `overflow:hidden` container; we drive its
+  // scrollLeft from the body's scrollLeft on every scroll event so pinned
+  // columns stay perfectly aligned with their body counterparts.
+  const headerRef = useRef<HTMLDivElement>(null);
+  const bodyRef = useRef<HTMLDivElement>(null);
+  const rows = table.getRowModel().rows;
+  const headerCount = table.getFlatHeaders().length;
+  const totalWidth = table.getTotalSize();
+  const tableState = table.getState();
+  const tableColumnPinning = tableState.columnPinning;
+  const tableColumnSizing = tableState.columnSizing;
+  const tableColumnOrder = tableState.columnOrder;
+  const tableColumnVisibility = tableState.columnVisibility;
+  const tableGrouping = tableState.grouping;
+  const [bodyViewportWidth, setBodyViewportWidth] = useState(0);
+
+  const syncHeaderMetrics = useCallback(() => {
+    const body = bodyRef.current;
+    const header = headerRef.current;
+    if (!body || !header) return;
+
+    const scrollbarW = getScrollbarWidth();
+    const hasScroll = body.scrollHeight > body.clientHeight;
+    const paddingRight = hasScroll ? `${scrollbarW}px` : "0px";
+
+    header.style.paddingRight = paddingRight;
+    header.parentElement?.style.setProperty(
+      "--header-padding-right",
+      paddingRight,
+    );
+    header.parentElement?.setAttribute("data-has-scroll", hasScroll.toString());
+
+    // Re-sync horizontal scroll position after width changes so pinned
+    // columns stay perfectly aligned with their body counterparts.
+    header.scrollLeft = body.scrollLeft;
+    setBodyViewportWidth(body.clientWidth);
+  }, []);
+
+  useEffect(() => {
+    syncHeaderMetrics();
+  }, [
+    rows.length,
+    headerCount,
+    totalWidth,
+    tableColumnPinning,
+    tableColumnSizing,
+    tableColumnOrder,
+    tableColumnVisibility,
+    tableGrouping,
+    syncHeaderMetrics,
+  ]);
+
+  useEffect(() => {
+    const body = bodyRef.current;
+    if (!body) return;
+
+    const observer = new ResizeObserver(syncHeaderMetrics);
+    observer.observe(body);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [syncHeaderMetrics]);
+
+  useEffect(() => {
+    const body = bodyRef.current;
+    const header = headerRef.current;
+    if (!body || !header) return;
+
+    const syncFromBody = () => {
+      if (header.scrollLeft !== body.scrollLeft) {
+        header.scrollLeft = body.scrollLeft;
+      }
+    };
+
+    const syncFromHeader = () => {
+      if (body.scrollLeft !== header.scrollLeft) {
+        body.scrollLeft = header.scrollLeft;
+      }
+    };
+
+    body.addEventListener("scroll", syncFromBody, { passive: true });
+    header.addEventListener("scroll", syncFromHeader, { passive: true });
+
+    return () => {
+      body.removeEventListener("scroll", syncFromBody);
+      header.removeEventListener("scroll", syncFromHeader);
+    };
+  }, []);
+
+  // ── Derived UI state ────────────────────────────────────────────────────────
+  // Defer the empty state by a tick after a loading→idle transition so the
+  // loader doesn't flicker into "no results" for one paint before rows land.
+  // Genuinely empty results (no in-flight load) commit immediately on mount.
+  const isRowsEmpty = rows.length === 0;
+  const [showEmptyState, setShowEmptyState] = useState(
+    () => !isLoading && isRowsEmpty,
+  );
+  const wasLoadingRef = useRef(isLoading);
+
+  useEffect(() => {
+    const wasLoading = wasLoadingRef.current;
+    wasLoadingRef.current = isLoading;
+
+    if (isLoading || !isRowsEmpty) {
+      setShowEmptyState(false);
+      return;
+    }
+    if (wasLoading) {
+      const id = window.setTimeout(
+        () => setShowEmptyState(true),
+        EMPTY_STATE_GRACE_MS,
+      );
+      return () => window.clearTimeout(id);
+    }
+    setShowEmptyState(true);
+  }, [isLoading, isRowsEmpty]);
+
+  // Single tab-like discriminator drives the body - loader, empty, or content.
+  // While loading OR while bridging the loading→empty grace window, the
+  // loader stays visible to avoid the brief "no results" flash.
+  const view: "loader" | "empty" | "content" =
+    isLoading || (isRowsEmpty && !showEmptyState)
+      ? "loader"
+      : isRowsEmpty
+        ? "empty"
+        : "content";
+
+  const selectedCount = rowsSelectable
+    ? table.getSelectedRowModel().flatRows.length
+    : 0;
+  const headerGroups = table.getHeaderGroups();
+  const visibleLeafColumns = table.getVisibleLeafColumns();
+
+  const columnExtraWidths = useMemo<Record<string, number>>(() => {
+    const extraSpace = Math.max(0, bodyViewportWidth - totalWidth);
+    if (extraSpace <= 0) return EMPTY_COLUMN_EXTRA_WIDTHS;
+
+    // Never add responsive width onto pinned columns because tanstack computes
+    // sticky offsets from base sizes; changing pinned visual width would desync
+    // left/right offsets and reintroduce overlap.
+    const growColumns = visibleLeafColumns.filter(
+      (column) => !column.getIsPinned() && column.id !== SELECT_COLUMN_ID,
+    );
+    if (growColumns.length === 0) return EMPTY_COLUMN_EXTRA_WIDTHS;
+
+    const baseExtra = Math.floor(extraSpace / growColumns.length);
+    let remainder = extraSpace - baseExtra * growColumns.length;
+
+    const next: Record<string, number> = {};
+    for (const column of growColumns) {
+      const grow = baseExtra + (remainder > 0 ? 1 : 0);
+      if (grow > 0) {
+        next[column.id] = grow;
+      }
+      if (remainder > 0) {
+        remainder -= 1;
+      }
+    }
+
+    return next;
+  }, [bodyViewportWidth, totalWidth, visibleLeafColumns]);
+
+  // The table always fills its container while preserving configured widths as
+  // a minimum. Any extra viewport space is distributed across visible center
+  // columns, keeping pinned offsets stable and avoiding an empty right gutter.
+  const tableSizingStyle: CSSProperties = useMemo(
+    () => ({ width: "100%", minWidth: `${totalWidth}px` }),
+    [totalWidth],
+  );
+
+  const tableClass = clsx(
+    s.table,
+    showVerticalBorders && s.table_vertical_borders,
+  );
+
+  return (
+    <div className={clsx(s.root, className)}>
+      {/* Filter bar - fixed height, never scrolls */}
+      {filters.length > 0 && (
+        <FilterBar
+          fields={filters}
+          values={filterValues}
+          onChange={onFilterChange}
+        />
+      )}
+
+      {/* Content wrap - grows to fill remaining height.
+          table_shell fills it; pagination pins to the bottom via margin-top:auto */}
+      <div className={s.content_wrap}>
+        {/* Table: detached header pill + scrollable body */}
+        <div
+          className={clsx(
+            s.table_shell,
+            !showPagination && s.table_shell_no_pagination,
+          )}
+        >
+          {/* Pinned header pill - scroll synced to body via JS */}
+          <div className={s.table_header_container}>
+            <div className={s.table_header_wrap} ref={headerRef}>
+              <table className={tableClass} style={tableSizingStyle}>
+                <thead>
+                  {headerGroups.map((hg) => (
+                    <tr key={hg.id}>
+                      {hg.headers.map((header) => (
+                        <HeaderCell<TData>
+                          key={header.id}
+                          header={header}
+                          extraWidth={columnExtraWidths[header.column.id] ?? 0}
+                          enableColumnOrdering={enableColumnOrdering}
+                          enableColumnResizing={enableColumnResizing}
+                          enableColumnPinning={enableColumnPinning}
+                          enableGrouping={enableGrouping}
+                          draggedColumnId={draggedColumnId}
+                          dropTargetColumnId={dropTargetColumnId}
+                          onDragStartCol={setDraggedColumnId}
+                          onDragEndCol={handleDragEnd}
+                          onDragOverCol={setDropTargetColumnId}
+                          onDropCol={handleColumnDrop}
+                        />
+                      ))}
+                    </tr>
+                  ))}
+                </thead>
+              </table>
+            </div>
+            <div className={s.header_padding_mask} />
+          </div>
+
+          {/* Scrollable body - only this element scrolls. The body is a
+              single switch over `view`: at most one branch ever renders, the
+              other two are unmounted entirely. */}
+          <div
+            className={s.table_body_wrap}
+            style={{ pointerEvents: isLoading ? "none" : undefined }}
+            ref={bodyRef}
+          >
+            {view === "loader" && (
+              <table className={tableClass} style={tableSizingStyle}>
+                <tbody>
+                  {Array.from({ length: pagination?.pageSize || 10 }).map(
+                    (_, i) => (
+                      <tr key={`skeleton-${i}`}>
+                        {visibleLeafColumns.map((col) => {
+                          const isPinned = col.getIsPinned();
+                          const isLastPinnedCol = isPinned && isLastPinned(col);
+                          const isSelectColumn = col.id === SELECT_COLUMN_ID;
+                          const baseStyle = getColumnStyle(
+                            col,
+                            col.getSize(),
+                            columnExtraWidths[col.id] ?? 0,
+                          );
+
+                          return (
+                            <td
+                              key={col.id}
+                              className={clsx(
+                                isSelectColumn && s.col_select,
+                                isPinned === "left" && s.col_pinned_left,
+                                isPinned === "right" && s.col_pinned_right,
+                                isLastPinnedCol && s.col_pinned_last,
+                              )}
+                              style={baseStyle}
+                            >
+                              <div className={s.td_inner}>
+                                <Loader variant="skeleton" style={{height: "var(--spacing-9)"}}/>
+                              </div>
+                            </td>
+                          );
+                        })}
+                      </tr>
+                    ),
+                  )}
+                </tbody>
+              </table>
+            )}
+            {view === "empty" && (
+              <div className={s.state_overlay}>
+                <p className={s.empty_msg}>{emptyMessage}</p>
+              </div>
+            )}
+            {view === "content" && (
+              <table className={tableClass} style={tableSizingStyle}>
+                <tbody>
+                  {rows.map((row) => (
+                    <BodyRow<TData>
+                      key={row.id}
+                      row={row}
+                      editingRowId={editingRowId}
+                      onRow={onRow}
+                      enableGrouping={enableGrouping}
+                      columnExtraWidths={columnExtraWidths}
+                      enableRowOrdering={enableRowOrdering}
+                      draggedRowId={draggedRowId}
+                      dropTargetRowId={dropTargetRowId}
+                      onDragStartRow={handleDragStartRow}
+                      onDragOverRow={handleDragOverRow}
+                      onDragEndRow={handleDragEndRow}
+                      onDropRow={handleDropRow}
+                    />
+                  ))}
+                </tbody>
+              </table>
+            )}
+          </div>
+        </div>
+
+        {/* Pagination - margin-top:auto pins it to the bottom of content_wrap */}
+        {showPagination && (
+          <PaginationBar
+            table={table}
+            pagination={pagination}
+            onPaginationChange={onPaginationChange}
+            pageSizeOptions={pageSizeOptions}
+            showPageSizeSelect={showPageSizeSelect}
+            totalCount={totalCount}
+            rowLabel={rowLabel}
+            rowsSelectable={rowsSelectable}
+            selectedCount={selectedCount}
+            extra={paginationExtra}
+          />
+        )}
+      </div>
+    </div>
+  );
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// HeaderActionButton - local compact icon button for the table header.
+// Keeps the header tight (no library Button padding) without depending on the
+// Button component while still mirroring its hover/focus visuals.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const HeaderActionButton = ({
+  onClick,
+  ariaLabel,
+  ariaPressed,
+  active = false,
+  children,
+}: HeaderActionButtonProps) => {
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="sm"
+      layout="box"
+      className={s.icon_btn}
+      onClick={onClick}
+      aria-label={ariaLabel}
+      aria-pressed={ariaPressed}
+      draggable={false}
+      isActive={active}
+    >
+      {children}
+    </Button>
+  );
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// HeaderCell - one <th> with sort, group, pin, drag, and resize affordances.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const HeaderCell = <TData,>({
+  header,
+  extraWidth,
+  enableColumnOrdering,
+  enableColumnResizing,
+  enableColumnPinning,
+  enableGrouping,
+  draggedColumnId,
+  dropTargetColumnId,
+  onDragStartCol,
+  onDragEndCol,
+  onDragOverCol,
+  onDropCol,
+}: HeaderCellProps<TData>) => {
+  const column = header.column;
+  const colMeta = column.columnDef.meta;
+  const align = colMeta?.align ?? "left";
+  // Fixed columns (e.g. row-select) opt out of hide-ability AND of being a
+  // drag source / drop target so they stay anchored in their position.
+  const isFixed = column.getCanHide() === false;
+  const canDrag = enableColumnOrdering && !isFixed;
+  const canResize = enableColumnResizing && column.getCanResize();
+  const canPin = enableColumnPinning && column.getCanPin() && !isFixed;
+  const canGroup = enableGrouping && column.getCanGroup() && !isFixed;
+  const canSort = column.getCanSort();
+  const isPinned = column.getIsPinned();
+  const isLastPinnedCol = isPinned && isLastPinned(column);
+  const isBeingDragged = draggedColumnId === column.id;
+  const isDropTarget =
+    dropTargetColumnId === column.id &&
+    draggedColumnId !== column.id &&
+    !isFixed;
+  const isGrouped = enableGrouping && column.getIsGrouped();
+  const isSelectColumn = column.id === SELECT_COLUMN_ID;
+  const sortState = column.getIsSorted();
+  const hasHeaderActions = canSort || canGroup || canPin;
+  const sortTooltip =
+    sortState === "asc"
+      ? "Sort descending"
+      : sortState === "desc"
+        ? "Clear sorting"
+        : "Sort ascending";
+
+  const handleDragStart = (e: ReactDragEvent<HTMLTableCellElement>) => {
+    e.dataTransfer.effectAllowed = "move";
+    e.dataTransfer.setData("text/plain", column.id);
+    onDragStartCol(column.id);
+  };
+
+  const handleDragOver = (e: ReactDragEvent<HTMLTableCellElement>) => {
+    if (!draggedColumnId || draggedColumnId === column.id || isFixed) return;
+    e.preventDefault();
+    e.dataTransfer.dropEffect = "move";
+    if (dropTargetColumnId !== column.id) onDragOverCol(column.id);
+  };
+
+  const handleDragLeave = () => {
+    if (dropTargetColumnId === column.id) onDragOverCol(null);
+  };
+
+  const handleDrop = (e: ReactDragEvent<HTMLTableCellElement>) => {
+    e.preventDefault();
+    if (!draggedColumnId || isFixed) return;
+    onDropCol(draggedColumnId, column.id);
+    onDragEndCol();
+  };
+
+  const sortIcon = !sortState ? (
+    <IconArrowsUpDown size={SORT_ICON_SIZE} stroke={ICON_STROKE} />
+  ) : sortState === "asc" ? (
+    <IconArrowUp size={SORT_ICON_SIZE} stroke={ICON_STROKE} />
+  ) : (
+    <IconArrowDown size={SORT_ICON_SIZE} stroke={ICON_STROKE} />
+  );
+
+  return (
+    <th
+      colSpan={header.colSpan}
+      onDragOver={canDrag ? handleDragOver : undefined}
+      onDragLeave={canDrag ? handleDragLeave : undefined}
+      onDrop={canDrag ? handleDrop : undefined}
+      className={clsx(
+        colMeta?.headerClassName,
+        s[`align_${align}`],
+        isSelectColumn && s.col_select,
+        isPinned === "left" && s.col_pinned_left,
+        isPinned === "right" && s.col_pinned_right,
+        isLastPinnedCol && s.col_pinned_last,
+        isBeingDragged && s.col_dragging,
+        isDropTarget && s.col_drop_target,
+      )}
+      style={getColumnStyle(column, header.getSize(), extraWidth)}
+    >
+      {!header.isPlaceholder && (
+        <div className={s.th_inner}>
+          {canDrag && (
+            <span
+              className={s.drag_handle}
+              aria-hidden
+              draggable
+              onDragStart={handleDragStart}
+              onDragEnd={onDragEndCol}
+            >
+              <IconGripVertical size={ICON_SIZE} stroke={ICON_STROKE} />
+            </span>
+          )}
+          {isSelectColumn ? (
+            flexRender(column.columnDef.header, header.getContext())
+          ) : (
+            <span className={s.th_label}>
+              {flexRender(column.columnDef.header, header.getContext())}
+            </span>
+          )}
+          {hasHeaderActions && (
+            <span className={s.th_actions}>
+              {canSort && (
+                <Tooltip content={sortTooltip}>
+                  <HeaderActionButton
+                    onClick={column.getToggleSortingHandler()}
+                    ariaLabel={`Sort by ${column.id}`}
+                    ariaPressed={!!sortState}
+                    active={!!sortState}
+                  >
+                    {sortIcon}
+                  </HeaderActionButton>
+                </Tooltip>
+              )}
+              {canGroup && (
+                <Tooltip
+                  content={isGrouped ? "Ungroup column" : "Group by column"}
+                >
+                  <HeaderActionButton
+                    onClick={column.getToggleGroupingHandler()}
+                    ariaLabel={
+                      isGrouped ? "Ungroup column" : "Group by this column"
+                    }
+                    ariaPressed={isGrouped}
+                    active={isGrouped}
+                  >
+                    {isGrouped ? (
+                      <IconStack3 size={ICON_SIZE} stroke={ICON_STROKE} />
+                    ) : (
+                      <IconStack2 size={ICON_SIZE} stroke={ICON_STROKE} />
+                    )}
+                  </HeaderActionButton>
+                </Tooltip>
+              )}
+              {canPin && !isPinned && (
+                <>
+                  <Tooltip content="Pin left">
+                    <HeaderActionButton
+                      onClick={() => column.pin("left")}
+                      ariaLabel="Pin left"
+                    >
+                      <IconArrowLeft size={ICON_SIZE} stroke={ICON_STROKE} />
+                    </HeaderActionButton>
+                  </Tooltip>
+                  <Tooltip content="Pin right">
+                    <HeaderActionButton
+                      onClick={() => column.pin("right")}
+                      ariaLabel="Pin right"
+                    >
+                      <IconArrowRight size={ICON_SIZE} stroke={ICON_STROKE} />
+                    </HeaderActionButton>
+                  </Tooltip>
+                </>
+              )}
+              {canPin && isPinned && (
+                <Tooltip content="Unpin column">
+                  <HeaderActionButton
+                    onClick={() => column.pin(false)}
+                    ariaLabel="Unpin column"
+                    ariaPressed
+                    active
+                  >
+                    <IconPinnedOff size={ICON_SIZE} stroke={ICON_STROKE} />
+                  </HeaderActionButton>
+                </Tooltip>
+              )}
+            </span>
+          )}
+          {canResize && (
+            <span
+              role="separator"
+              aria-orientation="vertical"
+              className={clsx(
+                s.resize_handle,
+                column.getIsResizing() && s.resize_handle_active,
+              )}
+              onMouseDown={header.getResizeHandler()}
+              onTouchStart={header.getResizeHandler()}
+              onClick={(e) => e.stopPropagation()}
+              onDoubleClick={() => column.resetSize()}
+              draggable={false}
+            />
+          )}
+        </div>
+      )}
+    </th>
+  );
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// BodyRow - one <tr> + its visible cells.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const BodyRow = <TData extends { id: string }>({
+  row,
+  editingRowId,
+  onRow,
+  enableGrouping,
+  columnExtraWidths,
+  enableRowOrdering,
+  draggedRowId,
+  dropTargetRowId,
+  onDragStartRow,
+  onDragOverRow,
+  onDragEndRow,
+  onDropRow,
+}: BodyRowProps<TData>) => {
+  const isGroup = enableGrouping && row.getIsGrouped();
+  const visibleCells = row.getVisibleCells();
+  const groupSourceCell = isGroup
+    ? visibleCells.find((cell) => cell.getIsGrouped())
+    : undefined;
+  const groupAnchorCellId = isGroup
+    ? (visibleCells.find((cell) => cell.column.id !== SELECT_COLUMN_ID)?.id ??
+      groupSourceCell?.id ??
+      null)
+    : null;
+  const isEditingThisRow =
+    !isGroup && editingRowId !== null && row.original.id === editingRowId;
+
+  // Editing rows host inputs/selects; their clicks must not bubble to row click.
+  const handleRowClick =
+    !isGroup && !isEditingThisRow && onRow
+      ? () => onRow(row.original)
+      : undefined;
+
+  const canDrag = enableRowOrdering && !isGroup && !isEditingThisRow;
+  const isBeingDragged = draggedRowId === row.id;
+  const isDropTarget =
+    dropTargetRowId === row.id && draggedRowId !== row.id && !isGroup;
+
+  return (
+    <tr
+      draggable={canDrag}
+      onDragStart={(e) => {
+        if (!canDrag) return;
+        e.dataTransfer.effectAllowed = "move";
+        e.dataTransfer.setData("text/plain", row.id);
+        onDragStartRow?.(row.id);
+      }}
+      onDragOver={(e) => {
+        if (!canDrag || !draggedRowId || draggedRowId === row.id) return;
+        e.preventDefault();
+        e.dataTransfer.dropEffect = "move";
+        if (dropTargetRowId !== row.id) onDragOverRow?.(row.id);
+      }}
+      onDragLeave={() => {
+        if (!canDrag) return;
+        if (dropTargetRowId === row.id) onDragOverRow?.(null);
+      }}
+      onDragEnd={() => {
+        if (!canDrag) return;
+        onDragEndRow?.();
+      }}
+      onDrop={(e) => {
+        if (!canDrag) return;
+        e.preventDefault();
+        if (!draggedRowId || draggedRowId === row.id) return;
+        onDropRow?.(draggedRowId, row.id);
+        onDragEndRow?.();
+      }}
+      className={clsx(
+        row.getIsSelected() && s.row_selected,
+        isEditingThisRow && s.row_editing,
+        isGroup && s.row_group,
+        isBeingDragged && s.row_dragging,
+        isDropTarget && s.row_drop_target,
+      )}
+      onClick={handleRowClick}
+      style={handleRowClick ? POINTER_STYLE : undefined}
+    >
+      {visibleCells.map((cell) => (
+        <BodyCell<TData>
+          key={cell.id}
+          cell={cell}
+          extraWidth={columnExtraWidths[cell.column.id] ?? 0}
+          groupSourceCell={groupSourceCell}
+          isGroupAnchorCell={groupAnchorCellId === cell.id}
+        />
+      ))}
+    </tr>
+  );
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// BodyCell - one <td>. Routes to the right body for grouped/aggregated/normal
+// cells and applies meta-driven align + truncate + pin classes.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const BodyCell = <TData,>({
+  cell,
+  extraWidth,
+  groupSourceCell,
+  isGroupAnchorCell,
+}: BodyCellProps<TData>) => {
+  const column: Column<TData, unknown> = cell.column;
+  const colMeta = column.columnDef.meta;
+  const align = colMeta?.align ?? "left";
+  const truncate = colMeta?.truncate ?? true;
+  const isPinned = column.getIsPinned();
+  const isLastPinnedCol = isPinned && isLastPinned(column);
+  const isSelectColumn = column.id === SELECT_COLUMN_ID;
+  const groupedRenderCell =
+    groupSourceCell ?? (cell.getIsGrouped() ? cell : undefined);
+  const groupDepth = groupedRenderCell?.row.depth ?? 0;
+
+  let body: ReactNode;
+  if (groupedRenderCell && isGroupAnchorCell) {
+    const groupedColumn = groupedRenderCell.column;
+    body = (
+      <button
+        type="button"
+        className={s.group_toggle}
+        onClick={groupedRenderCell.row.getToggleExpandedHandler()}
+        aria-expanded={groupedRenderCell.row.getIsExpanded()}
+        aria-label={
+          groupedRenderCell.row.getIsExpanded()
+            ? "Collapse group"
+            : "Expand group"
+        }
+        style={
+          groupDepth > 0
+            ? { paddingInlineStart: `calc(${groupDepth} * var(--spacing-4))` }
+            : undefined
+        }
+      >
+        <IconChevronRight
+          size={ICON_SIZE}
+          stroke={ICON_STROKE}
+          className={clsx(
+            s.group_chevron,
+            groupedRenderCell.row.getIsExpanded() && s.group_chevron_open,
+          )}
+        />
+        <span className={s.group_value}>
+          {flexRender(
+            groupedColumn.columnDef.cell,
+            groupedRenderCell.getContext(),
+          )}
+        </span>
+        <span className={s.group_count}>
+          ({groupedRenderCell.row.subRows.length})
+        </span>
+      </button>
+    );
+  } else if (groupedRenderCell && groupedRenderCell.id === cell.id) {
+    body = null;
+  } else if (cell.getIsAggregated()) {
+    body = column.columnDef.aggregatedCell ? (
+      flexRender(column.columnDef.aggregatedCell, cell.getContext())
+    ) : column.columnDef.aggregationFn ? (
+      <span className={s.cell_aggregated}>
+        {formatAggregated(cell.getValue())}
+      </span>
+    ) : null;
+  } else if (cell.getIsPlaceholder()) {
+    body = null;
+  } else {
+    body = flexRender(column.columnDef.cell, cell.getContext());
+  }
+
+  // Group rows are full-width summary rows; sticky pinning makes no sense
+  // on them. We strip BOTH the pinned CSS classes AND the left/right inline
+  // offsets. Without this, td:focus-within (which sets position:relative)
+  // would combine with left:Xpx from getColumnStyle and physically shift
+  // the cell when the user clicks the group-toggle chevron.
+  const isGroupRow = !!groupedRenderCell;
+  const baseStyle = getColumnStyle(column, column.getSize(), extraWidth);
+  const cellStyle: CSSProperties = isGroupRow
+    ? {
+        width: baseStyle.width,
+        minWidth: baseStyle.minWidth,
+        maxWidth: baseStyle.maxWidth,
+      }
+    : baseStyle;
+
+  return (
+    <td
+      className={clsx(
+        colMeta?.cellClassName,
+        s[`align_${align}`],
+        isGroupAnchorCell && s.group_anchor_cell,
+        !isGroupRow && isSelectColumn && s.col_select,
+        !isGroupRow && isPinned === "left" && s.col_pinned_left,
+        !isGroupRow && isPinned === "right" && s.col_pinned_right,
+        !isGroupRow && isLastPinnedCol && s.col_pinned_last,
+      )}
+      style={cellStyle}
+    >
+      <div className={clsx(s.td_inner, !truncate && s.td_inner_no_truncate)}>
+        {body}
+      </div>
+    </td>
+  );
+};