aplance-ui 1.5.1 → 1.6.0

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

@@ -1,1238 +1,1285 @@
-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,
-  useLayoutEffect,
-  useMemo,
-  useRef,
-  useState,
-  type CSSProperties,
-  type DragEvent as ReactDragEvent,
-  type MouseEvent as ReactMouseEvent,
-  type ReactNode,
-} from "react";
-import clsx from "clsx";
-import { Filters } from "./filters";
-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, 100];
-const DEFAULT_PAGINATION = { pageIndex: 0, pageSize: 20 };
-// 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;
-// Controls a row can hold. A click on one is that control's, not the row's.
-const ROW_CONTROLS =
-  'a, button, input, select, textarea, label, summary, [contenteditable]:not([contenteditable="false"]), [role="button"], [role="link"], [role="menuitem"], [role="checkbox"], [role="radio"], [role="switch"], [role="option"], [role="tab"]';
-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;
-
-const MIN_SKELETON_ROWS = 1;
-const useIsomorphicLayoutEffect =
-  typeof window === "undefined" ? useEffect : useLayoutEffect;
-
-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,
-  getRowCanSelect,
-  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,
-  paginationLabel,
-  className,
-}: DataTableProps<TData>) => {
-  // Collapse the filter row into a button + modal once it no longer fits inline.
-
-  // ── 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 ? (getRowCanSelect ?? true) : false,
-    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 bodyTableRef = useRef<HTMLTableElement>(null);
-  const skeletonRowRef = useRef<HTMLTableRowElement>(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 bodyViewportWidthRef = useRef(0);
-  // Body wrap height tracked separately so the loading skeleton can render
-  // exactly the count of rows that fits the visible body. Avoids the
-  // "skeleton overflows + body wrap scrolls" feel during cold load.
-  const [bodyViewportHeight, setBodyViewportHeight] = useState(0);
-  const bodyViewportHeightRef = useRef(0);
-  const [skeletonRowHeight, setSkeletonRowHeight] = useState(0);
-  const skeletonRowHeightRef = useRef(0);
-
-  const commitBodyViewportWidth = useCallback((nextWidth: number) => {
-    if (bodyViewportWidthRef.current === nextWidth) return;
-    bodyViewportWidthRef.current = nextWidth;
-    setBodyViewportWidth(nextWidth);
-  }, []);
-
-  const commitBodyViewportHeight = useCallback((nextHeight: number) => {
-    if (bodyViewportHeightRef.current === nextHeight) return;
-    bodyViewportHeightRef.current = nextHeight;
-    setBodyViewportHeight(nextHeight);
-  }, []);
-
-  const commitSkeletonRowHeight = useCallback((nextHeight: number) => {
-    if (nextHeight <= 0 || skeletonRowHeightRef.current === nextHeight) return;
-    skeletonRowHeightRef.current = nextHeight;
-    setSkeletonRowHeight(nextHeight);
-  }, []);
-
-  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());
-    // Mirror onto the body wrap so CSS can release the reserved scrollbar gutter
-    // when there's no vertical overflow (no blank strip on a few-row table).
-    body.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;
-    commitBodyViewportWidth(body.clientWidth);
-    commitBodyViewportHeight(body.clientHeight);
-  }, [commitBodyViewportWidth, commitBodyViewportHeight]);
-
-  useIsomorphicLayoutEffect(() => {
-    syncHeaderMetrics();
-  }, [
-    rows.length,
-    headerCount,
-    totalWidth,
-    tableColumnPinning,
-    tableColumnSizing,
-    tableColumnOrder,
-    tableColumnVisibility,
-    tableGrouping,
-    syncHeaderMetrics,
-  ]);
-
-  useIsomorphicLayoutEffect(() => {
-    const body = bodyRef.current;
-    if (!body) return;
-    if (typeof ResizeObserver === "undefined") return;
-
-    const observer = new ResizeObserver(syncHeaderMetrics);
-    observer.observe(body);
-    if (bodyTableRef.current) observer.observe(bodyTableRef.current);
-
-    return () => {
-      observer.disconnect();
-    };
-  }, [syncHeaderMetrics, rows.length, isLoading]);
-
-  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-to-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);
-
-  // wasLoadingRef is intentionally omitted from the dep array: it's a ref used
-  // to track the previous value of isLoading across renders without triggering
-  // re-runs. React guarantees ref objects are stable across the component lifetime.
-  useEffect(() => {
-    const wasLoading = wasLoadingRef.current;
-    wasLoadingRef.current = isLoading;
-
-    if (isLoading || !isRowsEmpty) {
-      setShowEmptyState(false);
-      return;
-    }
-    if (!wasLoading) {
-      setShowEmptyState(true);
-      return;
-    }
-    const id = window.setTimeout(
-      () => setShowEmptyState(true),
-      EMPTY_STATE_GRACE_MS,
-    );
-    return () => window.clearTimeout(id);
-  }, [isLoading, isRowsEmpty]);
-
-  // Single tab-like discriminator drives the body - loader, empty, or content.
-  // While loading OR while bridging the loading-to-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";
-
-  useIsomorphicLayoutEffect(() => {
-    if (view !== "loader") return;
-    const row = skeletonRowRef.current;
-    if (!row) return;
-
-    const measureRow = () => {
-      commitSkeletonRowHeight(Math.ceil(row.getBoundingClientRect().height));
-    };
-
-    measureRow();
-    if (typeof ResizeObserver === "undefined") return;
-
-    const observer = new ResizeObserver(measureRow);
-    observer.observe(row);
-
-    return () => {
-      observer.disconnect();
-    };
-  }, [commitSkeletonRowHeight, view]);
-
-  const selectedCount = rowsSelectable
-    ? table.getSelectedRowModel().flatRows.length
-    : 0;
-  const headerGroups = table.getHeaderGroups();
-  const visibleLeafColumns = table.getVisibleLeafColumns();
-
-  const skeletonRowCount =
-    bodyViewportHeight > 0 && skeletonRowHeight > 0
-      ? Math.max(
-          MIN_SKELETON_ROWS,
-          Math.floor(bodyViewportHeight / skeletonRowHeight),
-        )
-      : MIN_SKELETON_ROWS;
-
-  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]);
-
-  const tableWidth = Math.max(totalWidth, bodyViewportWidth);
-
-  // Columns that fit the body never scroll it sideways. The body's width is
-  // read from clientWidth, which rounds to the nearest pixel, so on a
-  // fractional layout (page zoom, display scaling) the table can overhang the
-  // body by under a pixel. Left to `overflow-x: auto`, that sliver shows a
-  // horizontal scrollbar, which shortens the body, flips its scrollbar gutter
-  // and starts another resize.
-  const columnsFit = bodyViewportWidth > 0 && totalWidth <= bodyViewportWidth;
-
-  // Match the table element width to the measured column widths. This keeps
-  // header, body, and skeleton rows on the same sizing contract during resize.
-  const tableSizingStyle: CSSProperties = useMemo(
-    () => ({ width: `${tableWidth}px`, minWidth: `${totalWidth}px` }),
-    [tableWidth, totalWidth],
-  );
-
-  const bodySkeletonStyle: CSSProperties = {
-    height: "var(--spacing-9)",
-  };
-
-  const selectSkeletonStyle: CSSProperties = {
-    width: "var(--data-table-selection-control-size, var(--spacing-9))",
-    height: "var(--data-table-selection-control-size, var(--spacing-9))",
-  };
-
-  const tableClass = clsx(
-    s.table,
-    showVerticalBorders && s.table_vertical_borders,
-  );
-
-  return (
-    <div className={clsx(s.root, className)}>
-      {/* Filters - inline row on desktop; a "Filters" button + modal once the
-          row no longer fits (so phones aren't buried under stacked fields). */}
-      {filters.length > 0 && (
-        <Filters
-          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 }}
-            data-fits={columnsFit}
-            ref={bodyRef}
-          >
-            {view === "loader" && (
-              <table className={tableClass} style={tableSizingStyle}>
-                <tbody>
-                  {Array.from({ length: skeletonRowCount }).map(
-                    (_, rowIndex) => (
-                      <tr
-                        key={`skeleton-${rowIndex}`}
-                        ref={rowIndex === 0 ? skeletonRowRef : undefined}
-                      >
-                        {visibleLeafColumns.map((column) => {
-                          const isPinned = column.getIsPinned();
-                          const isLastPinnedCol =
-                            isPinned && isLastPinned(column);
-                          const isSelectColumn = column.id === SELECT_COLUMN_ID;
-
-                          return (
-                            <td
-                              key={column.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={getColumnStyle(
-                                column,
-                                column.getSize(),
-                                columnExtraWidths[column.id] ?? 0,
-                              )}
-                            >
-                              <div className={s.td_inner}>
-                                <Loader
-                                  variant="skeleton"
-                                  className={
-                                    isSelectColumn
-                                      ? s.loading_select_skeleton
-                                      : undefined
-                                  }
-                                  style={
-                                    isSelectColumn
-                                      ? selectSkeletonStyle
-                                      : bodySkeletonStyle
-                                  }
-                                />
-                              </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}
-                ref={bodyTableRef}
-              >
-                <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}
-            isLoading={view === "loader"}
-            totalCount={totalCount}
-            rowLabel={rowLabel}
-            rowsSelectable={rowsSelectable}
-            selectedCount={selectedCount}
-            label={paginationLabel}
-            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.
-  // Only a click on the row itself opens it: not one on a control inside it
-  // (a link, a copy button), nor one that reaches it through a portal (a row's
-  // action menu), which React bubbles here from outside the row.
-  const handleRowClick =
-    !isGroup && !isEditingThisRow && onRow
-      ? (event: ReactMouseEvent<HTMLTableRowElement>) => {
-          const target = event.target as Element;
-          if (!event.currentTarget.contains(target)) return;
-          const control = target.closest(ROW_CONTROLS);
-          if (control && event.currentTarget.contains(control)) return;
-          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>
-  );
-};
+import {
+  FlexRender,
+  useTable,
+  type ColumnPinningState,
+  type RowData,
+  type Updater,
+} from "@tanstack/react-table";
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type DragEvent as ReactDragEvent,
+  type MouseEvent as ReactMouseEvent,
+  type ReactNode,
+} from "react";
+import clsx from "clsx";
+import { Filters } from "./filters";
+import { PaginationBar } from "./pagination-bar";
+import { Loader } from "../loader/loader";
+import type {
+  BodyCellProps,
+  BodyRowProps,
+  DataTableFeatures,
+  DataTableMeta,
+  DataTableProps,
+  FooterCellProps,
+  HeaderActionButtonProps,
+  HeaderCellProps,
+} from "./types";
+import {
+  columnId,
+  dataTableFeatures,
+  formatAggregated,
+  getColumnStyle,
+  growColumnWidths,
+  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, 100];
+const DEFAULT_PAGINATION = { pageIndex: 0, pageSize: 20 };
+// 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;
+// Controls a row can hold. A click on one is that control's, not the row's.
+const ROW_CONTROLS =
+  'a, button, input, select, textarea, label, summary, [contenteditable]:not([contenteditable="false"]), [role="button"], [role="link"], [role="menuitem"], [role="checkbox"], [role="radio"], [role="switch"], [role="option"], [role="tab"]';
+const EMPTY_FILTER_VALUES: Record<string, string> = {};
+const ICON_SIZE = 15;
+const SORT_ICON_SIZE = 13;
+const ICON_STROKE = 1.6;
+// 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;
+
+const MIN_SKELETON_ROWS = 1;
+const useIsomorphicLayoutEffect =
+  typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+/**
+ * A group row's aggregate for a column without its own `aggregatedCell`.
+ * Module-level so the table's `defaultColumn` stays one reference: a new one
+ * each render would rebuild every column. The context is typed on the two
+ * fields it reads, so it fits every table's rows despite tanstack's invariant
+ * row type.
+ */
+const DEFAULT_COLUMN = {
+  aggregatedCell: ({
+    column,
+    getValue,
+  }: {
+    column: { columnDef: { aggregationFn?: unknown } };
+    getValue: () => unknown;
+  }) => {
+    const text = formatAggregated(getValue(), column.columnDef.aggregationFn);
+    return text === null ? null : (
+      <span className={s.cell_aggregated}>{text}</span>
+    );
+  },
+};
+
+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,
+  manualPagination = true,
+  totalPages,
+  totalCount,
+  pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
+  showPageSizeSelect = true,
+  rowLabel = "row",
+
+  rowsSelectable = false,
+  getRowCanSelect,
+  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,
+  paginationLabel,
+  className,
+}: DataTableProps<TData>) => {
+  // Collapse the filter row into a button + modal once it no longer fits inline.
+
+  // ── Table meta ──────────────────────────────────────────────────────────────
+  const meta: DataTableMeta = 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],
+  );
+
+  // Uncontrolled pinning starts from the default pins.
+  const initialColumnPinning = useMemo(
+    () =>
+      enableColumnPinning && columnPinning === undefined
+        ? normalizeColumnPinningState(
+            {
+              start: defaultColumnPinning?.start ?? [],
+              end: defaultColumnPinning?.end ?? [],
+            },
+            shouldPinSelectionColumn,
+            defaultColumnPinning,
+          )
+        : undefined,
+    [
+      enableColumnPinning,
+      columnPinning,
+      shouldPinSelectionColumn,
+      defaultColumnPinning,
+    ],
+  );
+
+  const handleColumnPinningChange = useCallback(
+    (updater: Updater<ColumnPinningState>) => {
+      if (!onColumnPinningChange) return;
+
+      onColumnPinningChange((prev) => {
+        const normalizedPrev = normalizeColumnPinningState(
+          prev,
+          shouldPinSelectionColumn,
+          defaultColumnPinning,
+        ) ?? { start: [], end: [] };
+        const next = resolveUpdater(updater, normalizedPrev);
+
+        // Newly end-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 addedToEnd = next.end.filter(
+          (id) => !normalizedPrev.end.includes(id),
+        );
+        const keptInEnd = next.end.filter((id) =>
+          normalizedPrev.end.includes(id),
+        );
+
+        return (
+          normalizeColumnPinningState(
+            { start: next.start, end: [...addedToEnd, ...keptInEnd] },
+            shouldPinSelectionColumn,
+            defaultColumnPinning,
+          ) ?? { start: [], end: [] }
+        );
+      });
+    },
+    [onColumnPinningChange, shouldPinSelectionColumn, defaultColumnPinning],
+  );
+
+  // ── TanStack table instance ─────────────────────────────────────────────────
+  // Filtering is delegated to the consumer (see `useDataTable.filterFn`), so
+  // `dataTableFeatures` registers no filtering - rows arrive pre-filtered.
+  const table = useTable<DataTableFeatures, TData>({
+    features: dataTableFeatures,
+    data,
+    columns,
+    defaultColumn: DEFAULT_COLUMN,
+    enableRowSelection: rowsSelectable ? (getRowCanSelect ?? true) : false,
+    enableColumnResizing,
+    enableColumnPinning,
+    enableGrouping,
+    columnResizeMode: "onChange",
+    state: {
+      sorting,
+      ...(showPagination && { pagination }),
+      ...(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) =>
+        onPaginationChange(resolveUpdater(updater, pagination)),
+    }),
+    ...(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,
+    // A page at a time: the table counts pages from what it is told - the page
+    // count, else the row count, else unknown (-1, which keeps "next" open).
+    // Every row: it pages them itself. Without pagination, nothing is paged.
+    manualPagination: !showPagination || manualPagination,
+    ...(showPagination &&
+      manualPagination && {
+        pageCount: totalPages ?? (totalCount === undefined ? -1 : undefined),
+        rowCount: totalCount,
+      }),
+    // The page and the open groups are the user's: an edit, a refetch, or a
+    // new grouping must not send them back to page one or close every group.
+    autoResetPageIndex: false,
+    autoResetExpanded: false,
+    // Keep grouped columns in place so header controls stay spatially stable.
+    groupedColumnMode: false,
+    manualSorting,
+    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 bodyTableRef = useRef<HTMLTableElement>(null);
+  const skeletonRowRef = useRef<HTMLTableRowElement>(null);
+  const rows = table.getRowModel().rows;
+  const headerCount = table.getFlatHeaders().length;
+  const totalWidth = table.getTotalSize();
+  const {
+    columnPinning: tableColumnPinning,
+    columnSizing: tableColumnSizing,
+    columnOrder: tableColumnOrder,
+    columnVisibility: tableColumnVisibility,
+    grouping: tableGrouping,
+  } = table.state;
+  const [bodyViewportWidth, setBodyViewportWidth] = useState(0);
+  const bodyViewportWidthRef = useRef(0);
+  // Body wrap height tracked separately so the loading skeleton can render
+  // exactly the count of rows that fits the visible body. Avoids the
+  // "skeleton overflows + body wrap scrolls" feel during cold load.
+  const [bodyViewportHeight, setBodyViewportHeight] = useState(0);
+  const bodyViewportHeightRef = useRef(0);
+  const [skeletonRowHeight, setSkeletonRowHeight] = useState(0);
+  const skeletonRowHeightRef = useRef(0);
+
+  const commitBodyViewportWidth = useCallback((nextWidth: number) => {
+    if (bodyViewportWidthRef.current === nextWidth) return;
+    bodyViewportWidthRef.current = nextWidth;
+    setBodyViewportWidth(nextWidth);
+  }, []);
+
+  const commitBodyViewportHeight = useCallback((nextHeight: number) => {
+    if (bodyViewportHeightRef.current === nextHeight) return;
+    bodyViewportHeightRef.current = nextHeight;
+    setBodyViewportHeight(nextHeight);
+  }, []);
+
+  const commitSkeletonRowHeight = useCallback((nextHeight: number) => {
+    if (nextHeight <= 0 || skeletonRowHeightRef.current === nextHeight) return;
+    skeletonRowHeightRef.current = nextHeight;
+    setSkeletonRowHeight(nextHeight);
+  }, []);
+
+  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());
+    // Mirror onto the body wrap so CSS can release the reserved scrollbar gutter
+    // when there's no vertical overflow (no blank strip on a few-row table).
+    body.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;
+    commitBodyViewportWidth(body.clientWidth);
+    commitBodyViewportHeight(body.clientHeight);
+  }, [commitBodyViewportWidth, commitBodyViewportHeight]);
+
+  useIsomorphicLayoutEffect(() => {
+    syncHeaderMetrics();
+  }, [
+    rows.length,
+    headerCount,
+    totalWidth,
+    tableColumnPinning,
+    tableColumnSizing,
+    tableColumnOrder,
+    tableColumnVisibility,
+    tableGrouping,
+    syncHeaderMetrics,
+  ]);
+
+  useIsomorphicLayoutEffect(() => {
+    const body = bodyRef.current;
+    if (!body) return;
+    if (typeof ResizeObserver === "undefined") return;
+
+    const observer = new ResizeObserver(syncHeaderMetrics);
+    observer.observe(body);
+    if (bodyTableRef.current) observer.observe(bodyTableRef.current);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [syncHeaderMetrics, rows.length, isLoading]);
+
+  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-to-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);
+
+  // wasLoadingRef is intentionally omitted from the dep array: it's a ref used
+  // to track the previous value of isLoading across renders without triggering
+  // re-runs. React guarantees ref objects are stable across the component lifetime.
+  useEffect(() => {
+    const wasLoading = wasLoadingRef.current;
+    wasLoadingRef.current = isLoading;
+
+    if (isLoading || !isRowsEmpty) {
+      setShowEmptyState(false);
+      return;
+    }
+    if (!wasLoading) {
+      setShowEmptyState(true);
+      return;
+    }
+    const id = window.setTimeout(
+      () => setShowEmptyState(true),
+      EMPTY_STATE_GRACE_MS,
+    );
+    return () => window.clearTimeout(id);
+  }, [isLoading, isRowsEmpty]);
+
+  // Single tab-like discriminator drives the body - loader, empty, or content.
+  // While loading OR while bridging the loading-to-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";
+
+  useIsomorphicLayoutEffect(() => {
+    if (view !== "loader") return;
+    const row = skeletonRowRef.current;
+    if (!row) return;
+
+    const measureRow = () => {
+      commitSkeletonRowHeight(Math.ceil(row.getBoundingClientRect().height));
+    };
+
+    measureRow();
+    if (typeof ResizeObserver === "undefined") return;
+
+    const observer = new ResizeObserver(measureRow);
+    observer.observe(row);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [commitSkeletonRowHeight, view]);
+
+  const selectedCount = rowsSelectable
+    ? table.getSelectedRowModel().flatRows.length
+    : 0;
+  const headerGroups = table.getHeaderGroups();
+  const visibleLeafColumns = table.getVisibleLeafColumns();
+  // The rows of footers columns define, e.g. a total from
+  // `column.getAggregationValue()`; none when no column has a footer.
+  const footerGroups = table
+    .getFooterGroups()
+    .filter((group) =>
+      group.headers.some(
+        (header) =>
+          !header.isPlaceholder && header.column.columnDef.footer !== undefined,
+      ),
+    );
+
+  const skeletonRowCount =
+    bodyViewportHeight > 0 && skeletonRowHeight > 0
+      ? Math.max(
+          MIN_SKELETON_ROWS,
+          Math.floor(bodyViewportHeight / skeletonRowHeight),
+        )
+      : MIN_SKELETON_ROWS;
+
+  const columnExtraWidths = growColumnWidths(
+    visibleLeafColumns,
+    bodyViewportWidth - totalWidth,
+  );
+
+  const tableWidth = Math.max(totalWidth, bodyViewportWidth);
+
+  // Columns that fit the body never scroll it sideways. The body's width is
+  // read from clientWidth, which rounds to the nearest pixel, so on a
+  // fractional layout (page zoom, display scaling) the table can overhang the
+  // body by under a pixel. Left to `overflow-x: auto`, that sliver shows a
+  // horizontal scrollbar, which shortens the body, flips its scrollbar gutter
+  // and starts another resize.
+  const columnsFit = bodyViewportWidth > 0 && totalWidth <= bodyViewportWidth;
+
+  // Match the table element width to the measured column widths. This keeps
+  // header, body, and skeleton rows on the same sizing contract during resize.
+  const tableSizingStyle: CSSProperties = {
+    width: `${tableWidth}px`,
+    minWidth: `${totalWidth}px`,
+  };
+
+  const bodySkeletonStyle: CSSProperties = {
+    height: "var(--spacing-9)",
+  };
+
+  const selectSkeletonStyle: CSSProperties = {
+    width: "var(--data-table-selection-control-size, var(--spacing-9))",
+    height: "var(--data-table-selection-control-size, var(--spacing-9))",
+  };
+
+  const tableClass = clsx(
+    s.table,
+    showVerticalBorders && s.table_vertical_borders,
+  );
+
+  return (
+    <div className={clsx(s.root, className)}>
+      {/* Filters - inline row on desktop; a "Filters" button + modal once the
+          row no longer fits (so phones aren't buried under stacked fields). */}
+      {filters.length > 0 && (
+        <Filters
+          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 }}
+            data-fits={columnsFit}
+            ref={bodyRef}
+          >
+            {view === "loader" && (
+              <table className={tableClass} style={tableSizingStyle}>
+                <tbody>
+                  {Array.from({ length: skeletonRowCount }).map(
+                    (_, rowIndex) => (
+                      <tr
+                        key={`skeleton-${rowIndex}`}
+                        ref={rowIndex === 0 ? skeletonRowRef : undefined}
+                      >
+                        {visibleLeafColumns.map((column) => {
+                          const isPinned = column.getIsPinned();
+                          const isLastPinnedCol =
+                            isPinned && isLastPinned(column);
+                          const isSelectColumn = column.id === SELECT_COLUMN_ID;
+
+                          return (
+                            <td
+                              key={column.id}
+                              className={clsx(
+                                isSelectColumn && s.col_select,
+                                isPinned === "start" && s.col_pinned_start,
+                                isPinned === "end" && s.col_pinned_end,
+                                isLastPinnedCol && s.col_pinned_last,
+                              )}
+                              style={getColumnStyle(
+                                column,
+                                column.getSize(),
+                                columnExtraWidths[column.id] ?? 0,
+                              )}
+                            >
+                              <div className={s.td_inner}>
+                                <Loader
+                                  variant="skeleton"
+                                  className={
+                                    isSelectColumn
+                                      ? s.loading_select_skeleton
+                                      : undefined
+                                  }
+                                  style={
+                                    isSelectColumn
+                                      ? selectSkeletonStyle
+                                      : bodySkeletonStyle
+                                  }
+                                />
+                              </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}
+                ref={bodyTableRef}
+              >
+                <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>
+                {footerGroups.length > 0 && (
+                  <tfoot>
+                    {footerGroups.map((group) => (
+                      <tr key={group.id}>
+                        {group.headers.map((header) => (
+                          <FooterCell<TData>
+                            key={header.id}
+                            header={header}
+                            extraWidth={
+                              columnExtraWidths[header.column.id] ?? 0
+                            }
+                          />
+                        ))}
+                      </tr>
+                    ))}
+                  </tfoot>
+                )}
+              </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}
+            isLoading={view === "loader"}
+            totalCount={totalCount}
+            rowLabel={rowLabel}
+            rowsSelectable={rowsSelectable}
+            selectedCount={selectedCount}
+            label={paginationLabel}
+            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 extends RowData>({
+  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 === "start" && s.col_pinned_start,
+        isPinned === "end" && s.col_pinned_end,
+        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 header={header} />
+          ) : (
+            <span className={s.th_label}>
+              <FlexRender header={header} />
+            </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("start")}
+                      ariaLabel="Pin left"
+                    >
+                      <IconArrowLeft size={ICON_SIZE} stroke={ICON_STROKE} />
+                    </HeaderActionButton>
+                  </Tooltip>
+                  <Tooltip content="Pin right">
+                    <HeaderActionButton
+                      onClick={() => column.pin("end")}
+                      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>
+  );
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FooterCell - one footer <td>, sized and pinned like the column's body cells.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const FooterCell = <TData extends RowData>({
+  header,
+  extraWidth,
+}: FooterCellProps<TData>) => {
+  const column = header.column;
+  const isPinned = column.getIsPinned();
+  return (
+    <td
+      colSpan={header.colSpan}
+      className={clsx(
+        s[`align_${column.columnDef.meta?.align ?? "left"}`],
+        column.id === SELECT_COLUMN_ID && s.col_select,
+        isPinned === "start" && s.col_pinned_start,
+        isPinned === "end" && s.col_pinned_end,
+        isPinned && isLastPinned(column) && s.col_pinned_last,
+      )}
+      style={getColumnStyle(column, header.getSize(), extraWidth)}
+    >
+      <div className={s.td_inner}>
+        {header.isPlaceholder ? null : <FlexRender footer={header} />}
+      </div>
+    </td>
+  );
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 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.
+  // Only a click on the row itself opens it: not one on a control inside it
+  // (a link, a copy button), nor one that reaches it through a portal (a row's
+  // action menu), which React bubbles here from outside the row.
+  const handleRowClick =
+    !isGroup && !isEditingThisRow && onRow
+      ? (event: ReactMouseEvent<HTMLTableRowElement>) => {
+          const target = event.target as Element;
+          if (!event.currentTarget.contains(target)) return;
+          const control = target.closest(ROW_CONTROLS);
+          if (control && event.currentTarget.contains(control)) return;
+          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>. The group row's anchor cell hosts the expand toggle and
+// the grouped value; every other cell renders through `FlexRender`, which
+// picks the aggregated, placeholder, or normal body. Applies meta-driven
+// align + truncate + pin classes.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const BodyCell = <TData extends RowData>({
+  cell,
+  extraWidth,
+  groupSourceCell,
+  isGroupAnchorCell,
+}: BodyCellProps<TData>) => {
+  const column = 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) {
+    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 cell={groupedRenderCell} />
+        </span>
+        <span className={s.group_count}>
+          ({groupedRenderCell.row.subRows.length})
+        </span>
+      </button>
+    );
+  } else if (groupedRenderCell && !cell.getIsAggregated()) {
+    // A group row shows its toggle and its aggregates only. Any other column
+    // (the grouped one, or one with nothing to aggregate, like text under
+    // `auto`) stays empty instead of calling its `cell` with no row value.
+    body = null;
+  } else {
+    body = <FlexRender cell={cell} />;
+  }
+
+  // Group rows are full-width summary rows; sticky pinning makes no sense
+  // on them. We strip BOTH the pinned CSS classes AND the inline sticky
+  // offsets. Without this, td:focus-within (which sets position:relative)
+  // would combine with the offset 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 === "start" && s.col_pinned_start,
+        !isGroupRow && isPinned === "end" && s.col_pinned_end,
+        !isGroupRow && isLastPinnedCol && s.col_pinned_last,
+      )}
+      style={cellStyle}
+    >
+      <div className={clsx(s.td_inner, !truncate && s.td_inner_no_truncate)}>
+        {body}
+      </div>
+    </td>
+  );
+};