@rovula/ui 0.1.28 → 0.1.30

package/src/components/DataTable/DataTable.tsx

@@ -1,171 +1,2352 @@
 import {
+  Cell,
   ColumnDef,
   ColumnFiltersState,
-  OnChangeFn,
+  ColumnOrderState,
+  ColumnSizingInfoState,
+  ColumnSizingState,
+  ExpandedState,
+  Header,
+  PaginationState,
+  Row,
+  RowSelectionState,
+  RowData,
   SortingState,
+  Table as TanstackTable,
   VisibilityState,
   flexRender,
   getCoreRowModel,
+  getExpandedRowModel,
   getFilteredRowModel,
-  // getPaginationRowModel,
+  getPaginationRowModel,
   getSortedRowModel,
   useReactTable,
 } from "@tanstack/react-table";
-import React, { useEffect, useRef, useState } from "react";
+import React, {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import { useVirtualizer, type Virtualizer } from "@tanstack/react-virtual";
 
+// ---------------------------------------------------------------------------
+// Extend TanStack's ColumnMeta so every column definition can carry
+// `meta: { exactWidth: <number | string> }`.  When set the column is
+// rendered at exactly that width (width + minWidth + maxWidth all equal)
+// regardless of tableLayout mode, content width, or leftover table space.
+// Accepts a number (px) or any CSS length / calc() expression.
+//
+// `meta.align` — `text-left` / `text-center` / `text-right` on body cells and
+// on the header label wrapper (sort / ⋮ stay beside the label).
+// `meta.cellClassName` / `meta.headerCellClassName` — merged before the
+// table-level `cellClassName` / `headerCellClassName` props so callbacks can
+// override.
+//
+// `meta.colSpan` — merge this body cell with the next N-1 visible columns
+// (`<td colSpan={N}>`). Use `number` or `(row) => number` when only some rows
+// span (e.g. a footer "add" row). Skipped columns do not render their own `<td>`.
+// ---------------------------------------------------------------------------
+declare module "@tanstack/react-table" {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface ColumnMeta<TData extends RowData, TValue> {
+    exactWidth?: number | string;
+    align?: "left" | "center" | "right";
+    cellClassName?: string;
+    headerCellClassName?: string;
+    colSpan?: number | ((row: Row<TData>) => number);
+  }
+}
+
+/** TanStack Table types used by `DataTable` props — import from `@rovula/ui` to stay aligned with this package and `ColumnMeta` augmentation. */
+export type {
+  Cell,
+  ColumnDef,
+  ExpandedState,
+  Header,
+  PaginationState,
+  Row,
+  RowData,
+  RowSelectionState,
+  SortingState,
+  Table as TanstackTable,
+} from "@tanstack/react-table";
+
+export type {
+  EditableColumnDef,
+  EditDisplayMode,
+  EditTrigger,
+  DataTableEditingProps,
+} from "./DataTable.editing.types";
+
+function columnMetaAlignClass(
+  meta: { align?: "left" | "center" | "right" } | undefined,
+): string | undefined {
+  switch (meta?.align) {
+    case "center":
+      return "text-center";
+    case "right":
+      return "text-right";
+    case "left":
+      return "text-left";
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Walk visible body cells left-to-right; when a column defines `meta.colSpan`,
+ * emit one `<td>` spanning that many columns and skip the covered cells.
+ */
+function getVisibleCellsForRender<TData extends RowData>(
+  cells: Cell<TData, unknown>[],
+): { cell: Cell<TData, unknown>; colSpan: number }[] {
+  const out: { cell: Cell<TData, unknown>; colSpan: number }[] = [];
+  let i = 0;
+  while (i < cells.length) {
+    const cell = cells[i]!;
+    const meta = cell.column.columnDef.meta as
+      | { colSpan?: number | ((row: Row<TData>) => number) }
+      | undefined;
+    let want = 1;
+    if (meta?.colSpan != null) {
+      const raw =
+        typeof meta.colSpan === "function"
+          ? meta.colSpan(cell.row)
+          : meta.colSpan;
+      const n = Math.floor(Number(raw));
+      if (Number.isFinite(n) && n >= 1) want = n;
+    }
+    const maxSpan = cells.length - i;
+    const colSpan = Math.min(want, maxSpan);
+    out.push({ cell, colSpan: Math.max(1, colSpan) });
+    i += Math.max(1, colSpan);
+  }
+  return out;
+}
+
+function renderDataTableBodyCells<TData extends RowData>(opts: {
+  row: Row<TData>;
+  getSubRows?: (row: TData) => TData[] | undefined;
+  firstDataCellId: (row: Row<TData>) => string | undefined;
+  fixedColStyles: Map<string, React.CSSProperties> | null | undefined;
+  flexWidth: string | undefined;
+  lockPxExactWidth: boolean;
+  resizable: boolean;
+  tableLayout: "auto" | "fixed" | "equal";
+  resizableSlackGrowColId: string | null;
+  cellClassName?:
+    | string
+    | ((cell: Cell<TData, unknown>, row: Row<TData>) => string | undefined);
+  onCellClick?: (
+    cell: Cell<TData, unknown>,
+    row: Row<TData>,
+    event: React.MouseEvent,
+  ) => void;
+}): React.ReactNode {
+  const {
+    row,
+    getSubRows,
+    firstDataCellId,
+    fixedColStyles,
+    flexWidth,
+    lockPxExactWidth,
+    resizable,
+    tableLayout,
+    resizableSlackGrowColId,
+    cellClassName,
+    onCellClick,
+  } = opts;
+
+  return getVisibleCellsForRender(row.getVisibleCells()).map(
+    ({ cell, colSpan }) => {
+      const isFirstDataCell =
+        Boolean(getSubRows) && cell.id === firstDataCellId(row);
+      const usePixelResizeWidth =
+        resizable &&
+        tableLayout !== "equal" &&
+        !(
+          resizableSlackGrowColId != null &&
+          cell.column.id === resizableSlackGrowColId
+        );
+
+      return (
+        <TableCell
+          key={cell.id}
+          colSpan={colSpan > 1 ? colSpan : undefined}
+          style={resolveBodyCellWidthStyle(
+            cell.column.columnDef as ColumnDef<unknown, unknown>,
+            fixedColStyles?.get(cell.column.id),
+            flexWidth,
+            lockPxExactWidth,
+            usePixelResizeWidth ? cell.column.getSize() : undefined,
+          )}
+          className={cn(
+            columnMetaAlignClass(cell.column.columnDef.meta),
+            cell.column.columnDef.meta?.cellClassName,
+            typeof cellClassName === "function"
+              ? cellClassName(cell, row)
+              : cellClassName,
+          )}
+          onClick={
+            onCellClick
+              ? (e: React.MouseEvent) => onCellClick(cell, row, e)
+              : undefined
+          }
+        >
+          {isFirstDataCell ? (
+            <div
+              className="flex items-center gap-1"
+              style={{ paddingLeft: `${row.depth * 20}px` }}
+            >
+              {row.getCanExpand() ? (
+                <button
+                  type="button"
+                  onClick={row.getToggleExpandedHandler()}
+                  className="flex items-center justify-center size-5 rounded hover:bg-table-c-hover shrink-0 transition-colors"
+                  aria-label={row.getIsExpanded() ? "Collapse" : "Expand"}
+                >
+                  {row.getIsExpanded() ? (
+                    <ChevronDown className="size-4" />
+                  ) : (
+                    <ChevronRight className="size-4" />
+                  )}
+                </button>
+              ) : (
+                <span className="size-5 shrink-0" />
+              )}
+              {flexRender(cell.column.columnDef.cell, cell.getContext())}
+            </div>
+          ) : (
+            flexRender(cell.column.columnDef.cell, cell.getContext())
+          )}
+        </TableCell>
+      );
+    },
+  );
+}
+
+import * as Portal from "@radix-ui/react-portal";
 import {
-  ArrowDownIcon,
-  ArrowUpIcon,
-  ArrowsUpDownIcon,
-  ClipboardDocumentListIcon,
-} from "@heroicons/react/16/solid";
+  DndContext,
+  DragEndEvent,
+  KeyboardSensor,
+  PointerSensor,
+  closestCenter,
+  useSensor,
+  useSensors,
+} from "@dnd-kit/core";
+import {
+  restrictToVerticalAxis,
+  restrictToParentElement,
+} from "@dnd-kit/modifiers";
+import {
+  SortableContext,
+  arrayMove,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from "@dnd-kit/sortable";
+import { CSS } from "@dnd-kit/utilities";
+
+import {
+  ArrowDown,
+  ArrowUp,
+  ArrowUpDown,
+  ChevronDown,
+  ChevronRight,
+  ClipboardList,
+  Columns3,
+  EllipsisVertical,
+  Equal,
+  EyeOff,
+  Loader2,
+} from "lucide-react";
 
+import ActionButton from "@/components/ActionButton/ActionButton";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/DropdownMenu/DropdownMenu";
+import { Checkbox } from "../Checkbox/Checkbox";
+import { Switch } from "../Switch/Switch";
+import Button from "../Button/Button";
 import {
   Table,
   TableBody,
   TableCell,
   TableHead,
   TableHeader,
+  TablePagination,
+  TablePaginationProps,
   TableRow,
 } from "../Table/Table";
+import { cn } from "@/utils/cn";
+import type {
+  EditableColumnDef,
+  DataTableEditingProps,
+} from "./DataTable.editing.types";
+import {
+  EditContext,
+  useDataTableEditing,
+  resolveEditableColumns,
+  detectEditableColumnIds,
+} from "./DataTable.editing";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
 
-export interface DataTableProps<TData, TValue> {
-  columns: ColumnDef<TData, TValue>[];
+export type DataTablePaginationMode = "server" | "client" | "infinite";
+
+export interface DataTableProps<TData, TValue>
+  extends DataTableEditingProps<TData> {
+  columns: (ColumnDef<TData, TValue> | EditableColumnDef<TData, TValue>)[];
   data: TData[];
+
+  // --- Sorting ---
   manualSorting?: boolean;
   onSorting?: (sorting: SortingState) => void;
+
+  // --- Pagination ---
+  /**
+   * "client"   – DataTable manages page state internally with TanStack
+   * "server"   – caller controls page state; pass pageIndex/pageSize/totalCount
+   * "infinite" – no pagination bar; fetchMoreData enables infinite scroll
+   */
+  paginationMode?: DataTablePaginationMode;
+  /** Required for "server" mode */
+  totalCount?: number;
+  pageIndex?: number;
+  pageSize?: number;
+  onPaginationChange?: (state: PaginationState) => void;
+  pageSizeOptions?: number[];
+  /** Called when user scrolls near bottom (infinite mode). */
   fetchMoreData?: () => void;
+  /**
+   * Threshold in pixels from the bottom of the scroll container at which
+   * `fetchMoreData` is triggered. Defaults to 10px.
+   */
+  fetchMoreOffset?: number;
+  /**
+   * When `paginationMode` is `"infinite"`, shows a built-in footer row (spinner +
+   * label) and suppresses additional `fetchMoreData` calls until this is false again.
+   */
+  fetchingMore?: boolean;
+  /** Accessible label next to the spinner (default: "Loading more…"). */
+  fetchingMoreLabel?: string;
+  /**
+   * When there are no rows yet, shows a built-in loading state instead of the
+   * empty placeholder. Also suppresses `fetchMoreData` while true (infinite mode).
+   */
+  loading?: boolean;
+  /** Label for the initial-loading state (default: "Loading…"). */
+  loadingLabel?: string;
+
+  // --- Virtualization (experimental) ---
+  /**
+   * When true, DataTable will only render a vertical window of rows based on
+   * the scroll position of its internal scroll container. This is a basic
+   * fixed-row-height virtualizer intended for large but finite lists.
+   *
+   * Notes / limitations:
+   * - Only vertical row virtualization is supported.
+   * - Assumes approximately fixed row height; pass `virtualRowEstimate` to tune.
+   * - Works with selection, row actions, and basic infinite scroll, but more
+   *   complex combinations (tree rows, reorder, etc.) may have visual quirks.
+   */
+  virtualized?: boolean;
+  /**
+   * Estimated height in pixels for a single table row when `virtualized` is
+   * true. Used to compute how many rows fit in the viewport and the spacer
+   * heights above/below the rendered window.
+   * @default 40
+   */
+  virtualRowEstimate?: number;
+
+  /**
+   * Optional row id(s) to highlight visually. Highlighting is purely cosmetic
+   * and does not affect selection state.
+   */
+  highlightRowId?: string | string[];
+
+  /**
+   * When true and `highlightRowId` is set, moving the mouse pointer out of the
+   * scroll area will automatically scroll the first highlighted row back into
+   * view (centered).
+   */
+  scrollToHighlightOnMouseLeave?: boolean;
+
+  // --- Selection ---
+  selectable?: boolean;
+  onRowSelectionChange?: (rows: RowSelectionState) => void;
+
+  // --- Row actions ---
+  /** Render actions into the last fixed-width column. Receives the TanStack Row. */
+  rowActions?: (row: Row<TData>) => React.ReactNode;
+
+  // --- Row reorder ---
+  /**
+   * Enable drag-to-reorder rows. A grip handle column is prepended automatically.
+   * Requires each data item to have a unique `id` field (string | number)
+   * or supply `getRowId` to derive one.
+   */
+  reorderable?: boolean;
+  /** Return a unique string id for each row. Defaults to `(row) => row.id`. */
+  getRowId?: (row: TData) => string;
+  /** Called after the user drops a row into a new position. Receives the reordered data array. */
+  onRowReorder?: (data: TData[]) => void;
+  /**
+   * When `reorderable`, rows that return `true` are not draggable and are
+   * omitted from the sortable context (e.g. a pinned footer "add" row).
+   * Those rows are also kept **after** all sortable rows whenever column sort
+   * is applied (order among locked rows follows original `data` order).
+   */
+  isRowReorderLocked?: (row: Row<TData>) => boolean;
+
+  // --- Row & cell click ---
+  /** Fired when a body row is clicked. */
+  onRowClick?: (row: Row<TData>, event: React.MouseEvent) => void;
+  /** Fired when an individual body cell is clicked. */
+  onCellClick?: (
+    cell: Cell<TData, unknown>,
+    row: Row<TData>,
+    event: React.MouseEvent,
+  ) => void;
+
+  // --- Expandable rows ---
+  /** Return child rows to enable tree expansion */
+  getSubRows?: (row: TData) => TData[] | undefined;
+  /** Initial expanded state — `true` = all expanded, `{}` = all collapsed (uncontrolled) */
+  defaultExpanded?: ExpandedState | boolean;
+  /** Controlled expanded state — omit to let DataTable manage internally */
+  expanded?: ExpandedState;
+  onExpandedChange?: (expanded: ExpandedState) => void;
+
+  // --- Visual ---
+  /**
+   * Rounded frame + `border-table-c-border` around the scroll area and pagination
+   * (same token as primitive `Table` `bordered`). Set `false` when embedding in
+   * another bordered surface.
+   */
+  bordered?: boolean;
+  /**
+   * `"panel"` sets `data-surface="panel"` for table token overrides (modal /
+   * drawer). `"default"` leaves surface to ancestors.
+   */
+  surface?: "default" | "panel";
+  /** Alternate row background colours (RowA / RowB) */
+  striped?: boolean;
+  /** Add vertical column dividers */
+  divided?: boolean;
+  /** Return a className string to apply to a specific body row. */
+  rowClassName?:
+    | string
+    | ((row: Row<TData>, index: number) => string | undefined);
+  /** Return a className string to apply to a specific body cell. */
+  cellClassName?:
+    | string
+    | ((cell: Cell<TData, unknown>, row: Row<TData>) => string | undefined);
+  /** Return a className string to apply to a specific column header cell (`<th>`). */
+  headerCellClassName?:
+    | string
+    | ((header: Header<TData, unknown>) => string | undefined);
+  /** Additional className for the header section (`<thead>`). */
+  headerClassName?: string;
+  /** Additional className for the header row (`<tr>` inside `<thead>`). */
+  headerRowClassName?: string;
+  /**
+   * Controls when the sort indicator button is visible on sortable columns.
+   * - `"hover"` – shown only when hovering the column header (default)
+   * - `"always"` – always visible
+   */
+  sortIndicatorVisibility?: "always" | "hover";
+  /**
+   * CSS `table-layout` mode.
+   * - `"auto"` – browser sizes columns based on content (default)
+   * - `"fixed"` – non-`exactWidth` columns use their `size` as pixel widths;
+   *   the **last** visible non-exact column absorbs leftover width so the table
+   *   stays full-width. `meta.exactWidth` (px) columns stay locked.
+   * - `"equal"` – all visible columns without `meta.exactWidth` share the
+   *   remaining table width equally via
+   *   `calc((100% - <sum of exactWidth>px) / <flex column count>)`.
+   *   Columns with `meta.exactWidth` are still locked to their exact value.
+   *   With `resizable`, drag-to-resize is disabled for `equal` so widths stay
+   *   equal; `fixed`/`auto` keep column resize handles.
+   */
+  tableLayout?: "auto" | "fixed" | "equal";
+  /**
+   * Show a column menu (⋮) on each hideable column header: first a dropdown
+   * (“Hide … column”, “Manage columns”), then the full manage panel from the
+   * second action. Pass `true` or `ColumnManagementOptions` to tune features.
+   */
+  columnManagement?: boolean | ColumnManagementOptions;
+  /** Allow user to drag-resize column widths */
+  resizable?: boolean;
+  /**
+   * Global minimum column width in pixels when `resizable` is true.
+   * Individual columns can override with `minSize` in their column def.
+   * @default 60
+   */
+  columnMinSize?: number;
+  /**
+   * Global maximum column width in pixels when `resizable` is true.
+   * Individual columns can override with `maxSize` in their column def.
+   * @default Number.MAX_SAFE_INTEGER (no limit)
+   */
+  columnMaxSize?: number;
+
+  className?: string;
+  /**
+   * Sets `data-testid` on the root container and derives sub-ids for the
+   * table (`{testId}-table`), header (`{testId}-thead`), body (`{testId}-tbody`),
+   * rows (`{testId}-row-{rowId}`), and cells (`{testId}-cell-{rowId}-{colId}`).
+   */
+  testId?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Checkbox column builder
+// ---------------------------------------------------------------------------
+
+function buildCheckboxColumn<TData>(): ColumnDef<TData, unknown> {
+  return {
+    id: "__select__",
+    header: ({ table }) => (
+      <Checkbox
+        checked={
+          table.getIsSomeRowsSelected()
+            ? "indeterminate"
+            : table.getIsAllRowsSelected()
+        }
+        onCheckedChange={(v) => table.toggleAllRowsSelected(!!v)}
+        aria-label="Select all"
+      />
+    ),
+    cell: ({ row }) => (
+      <Checkbox
+        checked={row.getIsSelected()}
+        onCheckedChange={(v) => row.toggleSelected(!!v)}
+        aria-label="Select row"
+        disabled={!row.getCanSelect()}
+      />
+    ),
+    enableSorting: false,
+    enableHiding: false,
+    enableResizing: false,
+    size: 42,
+    maxSize: 42,
+    minSize: 42,
+    meta: { exactWidth: 42 },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Row-actions column builder
+// ---------------------------------------------------------------------------
+
+function buildActionsColumn<TData>(
+  render: (row: Row<TData>) => React.ReactNode,
+): ColumnDef<TData, unknown> {
+  return {
+    id: "__actions__",
+    header: () => null,
+    cell: ({ row }) => (
+      <div className="flex items-center justify-center gap-1">
+        {render(row)}
+      </div>
+    ),
+    enableSorting: false,
+    enableHiding: false,
+    enableResizing: false,
+    size: 80,
+    maxSize: 80,
+    minSize: 80,
+    meta: { exactWidth: 80 },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Row-reorder drag-handle column
+// ---------------------------------------------------------------------------
+
+function buildReorderColumn<TData>(): ColumnDef<TData, unknown> {
+  return {
+    id: "__reorder__",
+    header: () => null,
+    cell: ({ row }) => <RowDragHandle rowId={row.id} />,
+    enableSorting: false,
+    enableHiding: false,
+    enableResizing: false,
+    size: 54,
+    maxSize: 54,
+    minSize: 54,
+    meta: { exactWidth: 54 },
+  };
+}
+
+function RowDragHandle({ rowId }: { rowId: string }) {
+  const { attributes, listeners, setNodeRef, isDragging } = useSortable({
+    id: rowId,
+  });
+
+  return (
+    <ActionButton
+      ref={setNodeRef}
+      {...attributes}
+      {...listeners}
+      variant="icon"
+      size="sm"
+      active={isDragging}
+      className={cn(
+        "touch-none",
+        isDragging ? "cursor-grabbing" : "cursor-grab",
+      )}
+      aria-label="Drag to reorder"
+    >
+      <Equal className="!size-4" />
+    </ActionButton>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// SortableTableRow — wraps a <TableRow> with dnd-kit sortable transform
+// ---------------------------------------------------------------------------
+
+function SortableTableRow({
+  id,
+  children,
+  ...props
+}: { id: string } & React.ComponentProps<typeof TableRow>) {
+  const { transform, transition, isDragging, setNodeRef } = useSortable({
+    id,
+  });
+
+  const style: React.CSSProperties = {
+    transform: CSS.Transform.toString(
+      transform ? { ...transform, scaleX: 1, scaleY: 1 } : null,
+    ),
+    transition,
+    opacity: isDragging ? 0.5 : 1,
+    position: "relative",
+    zIndex: isDragging ? 50 : undefined,
+  };
+
+  return (
+    <TableRow ref={setNodeRef} style={style} {...props}>
+      {children}
+    </TableRow>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// ColumnManagementOptions
+// ---------------------------------------------------------------------------
+
+export interface ColumnManagementOptions {
+  /** Show drag-handle to reorder columns. @default true */
+  reorder?: boolean;
+  /** Show per-column visibility Switch. @default true */
+  visibility?: boolean;
+  /** Show "Hide all" button. @default true */
+  hideAll?: boolean;
+  /** Show "Show all" button. @default true */
+  showAll?: boolean;
+}
+
+const PINNED_START = ["__reorder__", "__select__"] as const;
+const PINNED_END = ["__actions__"] as const;
+
+/** Label for column-management menu (“Hide {name} column”). */
+function manageColumnHeaderLabel<TData>(
+  header: Header<TData, unknown>,
+): string {
+  const h = header.column.columnDef.header;
+  return typeof h === "string" ? h : header.column.id;
+}
+
+/**
+ * If a column carries `meta.exactWidth`, return CSS that locks the cell to
+ * exactly that width.  Accepts a number (px) or any CSS value / calc().
+ *
+ * Works in every `tableLayout` mode — `minWidth` + `maxWidth` constrain the
+ * cell even in `table-layout: auto` without requiring `table-fixed` on the
+ * table element.  `overflow: hidden` prevents content from pushing wider.
+ */
+function getExactWidthStyle(
+  colDef: ColumnDef<unknown, unknown>,
+  lock: boolean,
+): React.CSSProperties | undefined {
+  const w = (colDef.meta as { exactWidth?: number | string } | undefined)
+    ?.exactWidth;
+  if (w == null) return undefined;
+
+  // Only "lock" when the value is safely lockable (number or px string).
+  // For `calc()`, `%`, `rem`, etc. we apply only `width` even in fixed mode,
+  // otherwise the column becomes rigid in ways that surprise callers.
+  const lockable = exactWidthToPx(w) != null;
+  const shouldLock = lock && lockable;
+
+  // Lockable = number or "123px" — set all three to that fixed width.
+  // Do NOT use `calc(100% - ${w}px)` here: that means “fill minus w”, not “width = w”.
+  const locked = typeof w === "number" ? `${w}px` : (w as string).trim();
+
+  return shouldLock
+    ? {
+        width: locked,
+        minWidth: locked,
+        maxWidth: locked,
+        overflow: "hidden",
+        boxSizing: "border-box",
+      }
+    : {
+        width: w,
+      };
+}
+
+/**
+ * Convert `meta.exactWidth` to a numeric px value (only when possible).
+ * - `number` => px
+ * - `"123px"` => 123
+ * - other string formats => null (can't be summed at build time)
+ */
+function exactWidthToPx(
+  exactWidth: number | string | undefined,
+): number | null {
+  if (typeof exactWidth === "number") {
+    return Number.isFinite(exactWidth) ? exactWidth : null;
+  }
+  if (typeof exactWidth === "string") {
+    const m = exactWidth.trim().match(/^(-?\d*\.?\d+)\s*px$/i);
+    return m ? parseFloat(m[1]) : null;
+  }
+  return null;
+}
+
+/**
+ * Compute the auto-fill width for columns that do NOT have `exactWidth`.
+ * Formula: `calc((100% - <totalExactPx>px) / <flexCount>)`
+ *
+ * Only values convertible to numeric px participate in the subtraction.
+ */
+function useFlexColumnWidth<TData>(
+  table: TanstackTable<TData>,
+): string | undefined {
+  return React.useMemo(() => {
+    const visible = table.getVisibleLeafColumns();
+    let totalExactPx = 0;
+    let flexCount = 0;
+    for (const col of visible) {
+      const ew = (
+        col.columnDef.meta as { exactWidth?: number | string } | undefined
+      )?.exactWidth;
+      const asPx = exactWidthToPx(ew);
+      if (asPx != null) {
+        totalExactPx += asPx;
+      } else if (ew == null) {
+        flexCount += 1;
+      }
+    }
+    if (flexCount === 0) return undefined;
+    if (totalExactPx === 0) return undefined;
+    return `calc((100% - ${totalExactPx}px) / ${flexCount})`;
+  }, [table.getVisibleLeafColumns()]);
+}
+
+/**
+ * Resolve the inline style for a **header** cell (th).
+ *  - Has `exactWidth`  → locked width (min/max/overflow)
+ *  - `resizableWidth` (TanStack `getSize()`) → drag-resize width (`fixed`/`auto` only)
+ *  - flexWidth available → equal calc() (`equal` + `resizable` uses this, not getSize)
+ *  - Otherwise → fallback (e.g. fixed layout map or undefined)
+ */
+function resolveHeaderWidthStyle(
+  colDef: ColumnDef<unknown, unknown>,
+  flexWidth: string | undefined,
+  fallback: React.CSSProperties | undefined,
+  lockExactWidth: boolean,
+  resizableWidth?: number,
+): React.CSSProperties | undefined {
+  const exact = getExactWidthStyle(colDef, lockExactWidth);
+  if (exact) return exact;
+  if (resizableWidth != null) {
+    const colMax = colDef.maxSize;
+    return {
+      width: resizableWidth,
+      ...(colMax != null &&
+        colMax !== Number.MAX_SAFE_INTEGER && { maxWidth: colMax }),
+    };
+  }
+  if (flexWidth) return { width: flexWidth };
+  return fallback;
+}
+
+/**
+ * Resolve the inline style for a **body** cell (td).
+ *  - Has `exactWidth`  → locked width via min/maxWidth + overflow:hidden
+ *  - `resizableWidth` (TanStack column `getSize()`) → matches header when resizable
+ *  - fixedCellStyle available → "fixed" layout map
+ *  - flexWidth available → equal calc()
+ *  - Otherwise → undefined
+ */
+function resolveBodyCellWidthStyle(
+  colDef: ColumnDef<unknown, unknown>,
+  fixedCellStyle: React.CSSProperties | undefined,
+  flexWidth: string | undefined,
+  lockExactWidth: boolean,
+  resizableWidth?: number,
+): React.CSSProperties | undefined {
+  const exact = getExactWidthStyle(colDef, lockExactWidth);
+  if (exact) return exact;
+  if (resizableWidth != null) {
+    const colMax = colDef.maxSize;
+    return {
+      width: resizableWidth,
+      ...(colMax != null &&
+        colMax !== Number.MAX_SAFE_INTEGER && { maxWidth: colMax }),
+    };
+  }
+  if (fixedCellStyle) return fixedCellStyle;
+  if (flexWidth) return { width: flexWidth };
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// ManageColumnPanel — "Manage column" popover content (Figma DS node 9474:10149)
+// Each hideable column header renders its own ⋮ trigger.
+// anchorColumnId: the column whose ⋮ was clicked — its Switch is disabled so
+//   the user cannot hide it while the panel is open (prevents trigger unmount).
+// Drag is closed immediately on dragStart so the anchor never moves off-screen.
+// ---------------------------------------------------------------------------
+
+type LeafColumn<TData> = ReturnType<
+  TanstackTable<TData>["getAllLeafColumns"]
+>[number];
+
+function SortableColumnRow<TData>({
+  col,
+  label,
+  isLastVisible,
+  showReorder,
+  showVisibility,
+}: {
+  col: LeafColumn<TData>;
+  label: string;
+  isLastVisible: boolean;
+  showReorder: boolean;
+  showVisibility: boolean;
+}) {
+  const {
+    attributes,
+    listeners,
+    setNodeRef,
+    setActivatorNodeRef,
+    transform,
+    transition,
+    isDragging,
+  } = useSortable({ id: col.id });
+
+  const style: React.CSSProperties = {
+    transform: isDragging
+      ? `translateY(${transform?.y ?? 0}px)`
+      : CSS.Transform.toString(transform),
+    transition: isDragging ? undefined : transition,
+  };
+
+  return (
+    <div
+      ref={setNodeRef}
+      style={style}
+      className={cn(
+        "flex h-14 items-center gap-4 pl-6 pr-8 bg-modal-surface",
+        "relative select-none",
+        isDragging &&
+          "z-50 border border-primary-500/40 shadow-[0_8px_24px_-4px_rgba(0,0,0,0.24)] scale-[1.01]",
+      )}
+    >
+      {showReorder && (
+        <ActionButton
+          ref={setActivatorNodeRef}
+          {...attributes}
+          {...listeners}
+          variant="icon"
+          size="sm"
+          active={isDragging}
+          aria-label={`Drag to reorder ${label}`}
+          className={cn(
+            "shrink-0 touch-none",
+            isDragging ? "cursor-grabbing" : "cursor-grab",
+          )}
+        >
+          <Equal className="size-[14px]" />
+        </ActionButton>
+      )}
+      {showVisibility && (
+        <Switch
+          checked={col.getIsVisible()}
+          onCheckedChange={(v) => col.toggleVisibility(v)}
+          disabled={isLastVisible}
+        />
+      )}
+      <span
+        className={cn(
+          "flex-1 typography-subtitle4",
+          isDragging ? "text-text-contrast-max" : "text-text-g-contrast-high",
+        )}
+      >
+        {label}
+      </span>
+    </div>
+  );
+}
+
+function ManageColumnPanel<TData>({
+  table,
+  onClose,
+  maxListHeight = 400,
+  options = {},
+}: {
+  table: TanstackTable<TData>;
+  onClose: () => void;
+  maxListHeight?: number;
+  options?: ColumnManagementOptions;
+}) {
+  const {
+    reorder = true,
+    visibility = true,
+    hideAll = true,
+    showAll = true,
+  } = options;
+  const hideable = table.getAllLeafColumns().filter((col) => col.getCanHide());
+  const visibleCount = hideable.filter((col) => col.getIsVisible()).length;
+
+  const headerLabel = (col: LeafColumn<TData>) => {
+    const h = col.columnDef.header;
+    return typeof h === "string" ? h : col.id;
+  };
+
+  const sensors = useSensors(
+    useSensor(PointerSensor),
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+    }),
+  );
+
+  const handleDragEnd = (event: DragEndEvent) => {
+    const { active, over } = event;
+    if (!over || active.id === over.id) return;
+
+    const allColIds = table.getAllLeafColumns().map((c) => c.id);
+    const movable = allColIds.filter(
+      (id) =>
+        !(PINNED_START as readonly string[]).includes(id) &&
+        !(PINNED_END as readonly string[]).includes(id),
+    );
+
+    const oldIndex = movable.indexOf(active.id as string);
+    const newIndex = movable.indexOf(over.id as string);
+    if (oldIndex === -1 || newIndex === -1) return;
+
+    const fixedStart = allColIds.filter((id) =>
+      (PINNED_START as readonly string[]).includes(id),
+    );
+    const fixedEnd = allColIds.filter((id) =>
+      (PINNED_END as readonly string[]).includes(id),
+    );
+    table.setColumnOrder([
+      ...fixedStart,
+      ...arrayMove(movable, oldIndex, newIndex),
+      ...fixedEnd,
+    ]);
+  };
+
+  return (
+    <>
+      {/* Header */}
+      <div className="flex items-center gap-2 px-6 pt-4 pb-3 border-b border-modal-line">
+        <span className="flex-1 typography-subtitle3 text-text-contrast-max">
+          Manage column
+        </span>
+        {hideAll && (
+          <Button
+            variant="text"
+            color="secondary"
+            size="sm"
+            disabled={visibleCount <= 1}
+            onClick={() => {
+              const firstVisible =
+                hideable.find((col) => col.getIsVisible()) ?? hideable[0];
+              hideable.forEach((col) =>
+                col.toggleVisibility(col.id === firstVisible.id),
+              );
+            }}
+          >
+            Hide all
+          </Button>
+        )}
+        {showAll && (
+          <Button
+            variant="text"
+            color="primary"
+            size="sm"
+            onClick={() => table.toggleAllColumnsVisible(true)}
+          >
+            Show all
+          </Button>
+        )}
+        <Button variant="outline" color="primary" size="sm" onClick={onClose}>
+          Done
+        </Button>
+      </div>
+
+      {/* Column rows — drag-sortable, Y-axis only */}
+      <DndContext
+        sensors={sensors}
+        collisionDetection={closestCenter}
+        modifiers={[restrictToVerticalAxis, restrictToParentElement]}
+        onDragEnd={handleDragEnd}
+      >
+        <SortableContext
+          items={hideable.map((c) => c.id)}
+          strategy={verticalListSortingStrategy}
+        >
+          <div
+            className="overflow-y-auto ui-scrollbar"
+            style={{ maxHeight: maxListHeight }}
+          >
+            {hideable.map((col) => (
+              <SortableColumnRow
+                key={col.id}
+                col={col}
+                label={headerLabel(col)}
+                isLastVisible={col.getIsVisible() && visibleCount === 1}
+                showReorder={reorder}
+                showVisibility={visibility}
+              />
+            ))}
+          </div>
+        </SortableContext>
+      </DndContext>
+    </>
+  );
 }
 
+// ---------------------------------------------------------------------------
+// DataTable
+// ---------------------------------------------------------------------------
+
 export function DataTable<TData, TValue>({
   data,
   columns,
   manualSorting = false,
   onSorting,
+  paginationMode = "infinite",
+  totalCount,
+  pageIndex: controlledPageIndex,
+  pageSize: controlledPageSize,
+  onPaginationChange,
+  pageSizeOptions,
   fetchMoreData,
+  fetchMoreOffset,
+  fetchingMore = false,
+  fetchingMoreLabel = "Loading more…",
+  loading = false,
+  loadingLabel = "Loading…",
+  highlightRowId,
+  scrollToHighlightOnMouseLeave = false,
+  selectable = false,
+  onRowSelectionChange,
+  rowActions,
+  reorderable = false,
+  getRowId: getRowIdProp,
+  onRowReorder,
+  isRowReorderLocked,
+  onRowClick,
+  onCellClick,
+  getSubRows,
+  defaultExpanded,
+  expanded: controlledExpanded,
+  onExpandedChange,
+  bordered = true,
+  surface = "default",
+  striped = false,
+  divided = true,
+  rowClassName,
+  cellClassName,
+  headerCellClassName,
+  headerClassName,
+  headerRowClassName,
+  sortIndicatorVisibility = "hover",
+  tableLayout = "auto",
+  columnManagement: columnManagementProp = false,
+  resizable = false,
+  columnMinSize = 60,
+  columnMaxSize = Number.MAX_SAFE_INTEGER,
+  virtualized = false,
+  virtualRowEstimate,
+  className,
+  enableEditing = false,
+  editDisplayMode = "cell",
+  editTrigger = "click",
+  onCellCommit,
+  alwaysEditing,
+  enableCellTabTraversal,
+  editableColumnIds: editableColumnIdsProp,
+  testId,
 }: DataTableProps<TData, TValue>) {
-  const tableBodyRef = useRef<HTMLTableSectionElement>(null);
+  // scrollable container ref — lives on the wrapper div, not tbody
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const tableHeaderRef = useRef<HTMLTableSectionElement>(null);
+  const userInteractingRef = useRef(false);
+  /** Suppresses marking user scroll during highlight-driven `scrollTo` / `scrollIntoView`. */
+  const programmaticScrollLockRef = useRef(0);
+  const [stickyHeaderHeight, setStickyHeaderHeight] = useState(48);
+
+  const scheduleProgrammaticScrollEnd = useCallback(() => {
+    const el = scrollRef.current;
+    let settled = false;
+    const unlock = () => {
+      if (settled) return;
+      settled = true;
+      programmaticScrollLockRef.current = Math.max(
+        0,
+        programmaticScrollLockRef.current - 1,
+      );
+    };
+    el?.addEventListener("scrollend", unlock, { once: true });
+    window.setTimeout(unlock, 550);
+  }, []);
 
+  const virtualMeasureRowElement = useCallback(
+    (
+      element: HTMLTableRowElement,
+      entry: ResizeObserverEntry | undefined,
+      instance: Virtualizer<HTMLDivElement, HTMLTableRowElement>,
+    ) => {
+      const direction = instance.scrollDirection;
+      if (direction === "forward" || direction === null) {
+        const box = entry?.borderBoxSize?.[0];
+        if (box) {
+          return Math.round(box.blockSize);
+        }
+        return Math.round(element.getBoundingClientRect().height);
+      }
+      const raw = element.getAttribute("data-index");
+      const indexKey = raw != null ? Number.parseInt(raw, 10) : NaN;
+      const cache = (
+        instance as unknown as { measurementsCache?: { size: number }[] }
+      ).measurementsCache;
+      const cached =
+        Number.isFinite(indexKey) && cache?.[indexKey]
+          ? cache[indexKey]!.size
+          : undefined;
+      if (typeof cached === "number") {
+        return cached;
+      }
+      const box = entry?.borderBoxSize?.[0];
+      if (box) {
+        return Math.round(box.blockSize);
+      }
+      return Math.round(element.getBoundingClientRect().height);
+    },
+    [],
+  );
+
+  // Normalize columnManagement: boolean | options → boolean + options object
+  const columnManagement = !!columnManagementProp;
+  const columnManagementOptions: ColumnManagementOptions =
+    typeof columnManagementProp === "object" ? columnManagementProp : {};
+
+  // ---- state ----
   const [sorting, setSorting] = useState<SortingState>([]);
   const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
   const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({});
-  const [rowSelection, setRowSelection] = useState({});
+  const [columnOrder, setColumnOrder] = useState<ColumnOrderState>([]);
+  const [columnSizing, setColumnSizing] = useState<ColumnSizingState>({});
+  const [columnSizingInfo, setColumnSizingInfo] =
+    useState<ColumnSizingInfoState>({
+      startOffset: null,
+      startSize: null,
+      deltaOffset: null,
+      deltaPercentage: null,
+      isResizingColumn: false,
+      columnSizingStart: [],
+    });
+  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
+  const [internalExpanded, setInternalExpanded] = useState<ExpandedState>(
+    (defaultExpanded as ExpandedState) ?? {},
+  );
+  // Controlled: use prop directly every render; uncontrolled: use internal state
+  const isExpandedControlled = controlledExpanded !== undefined;
+  const expanded = isExpandedControlled ? controlledExpanded : internalExpanded;
 
-  const table = useReactTable({
-    data,
+  const [pagination, setPagination] = useState<PaginationState>({
+    pageIndex: controlledPageIndex ?? 0,
+    pageSize: controlledPageSize ?? 10,
+  });
+
+  // ---- column-management panel state (lifted here so hiding a column doesn't unmount it) ----
+  const [manageOpen, setManageOpen] = useState(false);
+  const [manageAnchorId, setManageAnchorId] = useState<string | null>(null);
+  const [columnManageMenuOpenId, setColumnManageMenuOpenId] = useState<
+    string | null
+  >(null);
+  const [managePanelPos, setManagePanelPos] = useState<{
+    top: number;
+    right: number;
+    maxListHeight: number;
+  }>({ top: 0, right: 0, maxListHeight: 400 });
+
+  const manageMenuTriggerRef = useRef<Map<string, HTMLButtonElement>>(
+    new Map(),
+  );
+
+  const openManagePanelAt = useCallback(
+    (colId: string, anchorRect: DOMRect) => {
+      const PANEL_W = 460;
+      const MARGIN = 8;
+      setColumnManageMenuOpenId(null);
+      const idealRight = window.innerWidth - anchorRect.right;
+      const right = Math.min(
+        Math.max(idealRight, MARGIN),
+        window.innerWidth - PANEL_W - MARGIN,
+      );
+      const top = anchorRect.bottom + MARGIN;
+      const maxListHeight = Math.max(80, window.innerHeight - top - 80);
+      setManagePanelPos({ top, right, maxListHeight });
+      setManageAnchorId(colId);
+      setManageOpen(true);
+    },
+    [],
+  );
+
+  // Close manage panel on Escape
+  useEffect(() => {
+    if (!manageOpen) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setManageOpen(false);
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [manageOpen]);
+
+  // Sync controlled pagination (server mode)
+  useEffect(() => {
+    if (paginationMode === "server") {
+      setPagination({
+        pageIndex: controlledPageIndex ?? 0,
+        pageSize: controlledPageSize ?? 10,
+      });
+    }
+  }, [paginationMode, controlledPageIndex, controlledPageSize]);
+
+  // ---- editing engine ----
+  const editableColIds = React.useMemo(
+    () =>
+      editableColumnIdsProp ??
+      (enableEditing
+        ? detectEditableColumnIds(columns as EditableColumnDef<TData>[])
+        : []),
+    [enableEditing, editableColumnIdsProp, columns],
+  );
+
+  const editingState = useDataTableEditing<TData>({
+    enabled: enableEditing,
+    editDisplayMode,
+    editTrigger,
+    editableColumnIds: editableColIds,
+  });
+
+  // ---- build final columns ----
+  const finalColumns = React.useMemo<ColumnDef<TData, unknown>[]>(() => {
+    let cols: ColumnDef<TData, unknown>[];
+    if (enableEditing) {
+      cols = resolveEditableColumns(columns as EditableColumnDef<TData>[], {
+        editing: editingState,
+        onCellCommit: onCellCommit as
+          | ((rowId: string, columnId: string, patch: Partial<TData>) => void)
+          | undefined,
+        alwaysEditing: alwaysEditing as
+          | ((row: Row<TData>) => boolean)
+          | undefined,
+        enableCellTabTraversal: enableCellTabTraversal ?? true,
+        editableColumnIds: editableColIds,
+      });
+    } else {
+      cols = [...(columns as ColumnDef<TData, unknown>[])];
+    }
+    if (reorderable) cols.unshift(buildReorderColumn<TData>());
+    if (selectable) cols.unshift(buildCheckboxColumn<TData>());
+    if (rowActions) cols.push(buildActionsColumn<TData>(rowActions));
+    return cols;
+  }, [
     columns,
+    selectable,
+    reorderable,
+    rowActions,
+    enableEditing,
+    editingState,
+    onCellCommit,
+    alwaysEditing,
+    enableCellTabTraversal,
+  ]);
+
+  // ---- table instance ----
+  const isPaginated =
+    paginationMode === "client" || paginationMode === "server";
+
+  const table = useReactTable<TData>({
+    data,
+    columns: finalColumns,
+    columnResizeMode: "onChange",
+    defaultColumn: {
+      minSize: columnMinSize,
+      maxSize: columnMaxSize,
+    },
+    ...(getRowIdProp
+      ? { getRowId: (row) => getRowIdProp(row) }
+      : { getRowId: (row) => (row as Record<string, unknown>).id as string }),
     manualSorting,
+    manualPagination: paginationMode === "server",
+    rowCount:
+      paginationMode === "server" ? totalCount ?? data.length : undefined,
+    getSubRows,
     onSortingChange: setSorting,
     onColumnFiltersChange: setColumnFilters,
+    onColumnVisibilityChange: setColumnVisibility,
+    onColumnOrderChange: setColumnOrder,
+    onColumnSizingChange: setColumnSizing,
+    onColumnSizingInfoChange: setColumnSizingInfo,
+    onRowSelectionChange: setRowSelection,
+    onExpandedChange: (updater) => {
+      const next = typeof updater === "function" ? updater(expanded) : updater;
+      if (!isExpandedControlled) setInternalExpanded(next);
+      onExpandedChange?.(next);
+    },
+    onPaginationChange: (updater) => {
+      const next =
+        typeof updater === "function" ? updater(pagination) : updater;
+      setPagination(next);
+      onPaginationChange?.(next);
+    },
     getCoreRowModel: getCoreRowModel(),
-    // getPaginationRowModel: getPaginationRowModel(),
     getSortedRowModel: getSortedRowModel(),
     getFilteredRowModel: getFilteredRowModel(),
-    onColumnVisibilityChange: setColumnVisibility,
-    onRowSelectionChange: setRowSelection,
+    getExpandedRowModel: getExpandedRowModel(),
+    ...(isPaginated ? { getPaginationRowModel: getPaginationRowModel() } : {}),
+    enableRowSelection: selectable,
+    enableColumnResizing: resizable,
     state: {
       sorting,
       columnFilters,
       columnVisibility,
+      columnOrder,
+      columnSizing,
+      columnSizingInfo,
       rowSelection,
-      // pagination: {
-      //   pageSize: 100,
-      //   pageIndex: 0,
-      // },
+      expanded,
+      ...(isPaginated ? { pagination } : {}),
     },
   });
 
+  /** Body row order: sortable rows follow header sort; locked rows stay at the bottom. */
+  const tableRowsForView = React.useMemo(() => {
+    const rows = table.getRowModel().rows;
+    if (!isRowReorderLocked) return rows;
+    const locked = rows.filter((r) => isRowReorderLocked(r));
+    const unlocked = rows.filter((r) => !isRowReorderLocked(r));
+    if (locked.length === 0) return rows;
+    const order = new Map(
+      data.map((row, index) => [
+        getRowIdProp
+          ? getRowIdProp(row)
+          : String((row as Record<string, unknown>).id),
+        index,
+      ]),
+    );
+    locked.sort((a, b) => (order.get(a.id) ?? 0) - (order.get(b.id) ?? 0));
+    return [...unlocked, ...locked];
+  }, [table.getRowModel().rows, isRowReorderLocked, data, getRowIdProp]);
+
+  // ---- side-effects ----
   useEffect(() => {
     onSorting?.(sorting);
   }, [sorting, onSorting]);
 
   useEffect(() => {
+    onRowSelectionChange?.(rowSelection);
+  }, [rowSelection, onRowSelectionChange]);
+
+  // Infinite scroll — listener on the wrapper div
+  useEffect(() => {
+    if (paginationMode !== "infinite") return;
+    const el = scrollRef.current;
+    if (!el) return;
     const handleScroll = () => {
-      if (tableBodyRef.current) {
-        const { scrollTop, scrollHeight, clientHeight } = tableBodyRef.current;
-        if (scrollTop + clientHeight >= scrollHeight - 10) {
-          fetchMoreData?.();
-        }
+      if (programmaticScrollLockRef.current > 0) return;
+      // Do not set userInteractingRef here: programmatic highlight scroll (often
+      // `behavior: "smooth"`) emits many scroll events after the programmatic
+      // lock unlocks, which would flip userInteracting and block the next follow.
+      // Pause is handled only via wheel / pointer when scrollToHighlightOnMouseLeave.
+      const { scrollTop, scrollHeight, clientHeight } = el;
+      if (fetchingMore || loading) return;
+      const offset = typeof fetchMoreOffset === "number" ? fetchMoreOffset : 10;
+      if (scrollTop + clientHeight >= scrollHeight - offset) {
+        fetchMoreData?.();
       }
     };
+    el.addEventListener("scroll", handleScroll);
+    return () => el.removeEventListener("scroll", handleScroll);
+  }, [paginationMode, fetchMoreData, fetchingMore, loading, fetchMoreOffset]);
 
-    const tableBodyElement = tableBodyRef.current;
-    if (tableBodyElement) {
-      tableBodyElement.addEventListener("scroll", handleScroll);
-    }
+  const isEmpty = tableRowsForView.length === 0;
+
+  // Virtualizer row offsets must match scroll coordinates: tbody starts below <thead>.
+  useLayoutEffect(() => {
+    if (!virtualized) return;
+    const el = tableHeaderRef.current;
+    if (!el) return;
+    const update = () => {
+      setStickyHeaderHeight(Math.round(el.getBoundingClientRect().height));
+    };
+    update();
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [virtualized]);
+
+  const scrollHighlightIntoViewRef = useRef<
+    (behavior?: ScrollBehavior) => void
+  >(() => {});
 
-    return () => {
-      if (tableBodyElement) {
-        tableBodyElement.removeEventListener("scroll", handleScroll);
+  const hadVirtualScrollSizeRef = useRef(false);
+
+  const rowVirtualizer = useVirtualizer({
+    count: virtualized ? tableRowsForView.length : 0,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => virtualRowEstimate ?? 40,
+    overscan: 4,
+    // Offsets must include sticky thead height so item.start matches document offsets inside the scrollport.
+    paddingStart: virtualized ? stickyHeaderHeight : 0,
+    scrollPaddingStart: 0,
+    measureElement: virtualMeasureRowElement,
+    onChange: () => {
+      if (!virtualized || !highlightRowId) return;
+      const h = scrollRef.current?.clientHeight ?? 0;
+      if (h < 1) {
+        hadVirtualScrollSizeRef.current = false;
+        return;
+      }
+      if (hadVirtualScrollSizeRef.current) return;
+      hadVirtualScrollSizeRef.current = true;
+      requestAnimationFrame(() => {
+        if (userInteractingRef.current) return;
+        scrollHighlightIntoViewRef.current("auto");
+      });
+    },
+  });
+
+  const scrollHighlightIntoView = useCallback(
+    (behavior: ScrollBehavior = "smooth") => {
+      if (!highlightRowId) return;
+      if (userInteractingRef.current) return;
+      const container = scrollRef.current;
+      if (!container) return;
+      const ids = Array.isArray(highlightRowId)
+        ? highlightRowId
+        : [highlightRowId];
+
+      // Virtualized: off-screen rows are not in the DOM, so querySelector fails.
+      // Drive scroll via the virtualizer so the target row mounts, then DOM path can fine-tune if needed.
+      if (virtualized) {
+        void rowVirtualizer.getTotalSize();
+        for (const id of ids) {
+          const idx = tableRowsForView.findIndex((r) => r.id === id);
+          if (idx !== -1) {
+            // `scrollToIndex({ align: "center" })` aligns item *start* to viewport center
+            // in TanStack Virtual; also thead was throwing off scroll coords — use
+            // paddingStart + explicit center of row in the scrollport.
+            const estimate = virtualRowEstimate ?? 40;
+            const startOffset = rowVirtualizer.getOffsetForIndex(idx, "start");
+            if (!startOffset) continue;
+            const [scrollTopAlignStart] = startOffset;
+            const vzWithCache = rowVirtualizer as unknown as {
+              measurementsCache?: { size: number }[];
+            };
+            const measured = vzWithCache.measurementsCache?.[idx]?.size;
+            const rowH = typeof measured === "number" ? measured : estimate;
+            const target =
+              scrollTopAlignStart + rowH / 2 - container.clientHeight / 2;
+            programmaticScrollLockRef.current += 1;
+            scheduleProgrammaticScrollEnd();
+            rowVirtualizer.scrollToOffset(Math.max(0, target), {
+              align: "start",
+              behavior: behavior === "smooth" ? "smooth" : "auto",
+            });
+            return;
+          }
+        }
+        return;
       }
+
+      for (const id of ids) {
+        const rowEl = container.querySelector<HTMLElement>(
+          `[data-row-id="${id}"]`,
+        );
+        if (rowEl) {
+          programmaticScrollLockRef.current += 1;
+          scheduleProgrammaticScrollEnd();
+          rowEl.scrollIntoView({ block: "center", behavior });
+          break;
+        }
+      }
+    },
+    [
+      highlightRowId,
+      tableRowsForView,
+      virtualized,
+      rowVirtualizer,
+      virtualRowEstimate,
+      stickyHeaderHeight,
+      scheduleProgrammaticScrollEnd,
+    ],
+  );
+
+  scrollHighlightIntoViewRef.current = scrollHighlightIntoView;
+
+  // Allow one onChange retry when the highlight target or virtualization toggles
+  // (e.g. scrollport height was 0 on first layout).
+  useLayoutEffect(() => {
+    hadVirtualScrollSizeRef.current = false;
+  }, [virtualized, highlightRowId]);
+
+  // Scroll to highlighted row(s) when the value changes (e.g. user picks one).
+  // When `scrollToHighlightOnMouseLeave` is set, auto-scroll is skipped while
+  // `userInteractingRef` is true (wheel / pointer on table only; not raw scroll).
+  useLayoutEffect(() => {
+    scrollHighlightIntoView("smooth");
+  }, [virtualized, scrollHighlightIntoView, highlightRowId]);
+
+  // ---- pagination bar props ----
+  const paginationBarProps: TablePaginationProps = {
+    pageIndex: pagination.pageIndex,
+    pageSize: pagination.pageSize,
+    totalCount:
+      paginationMode === "server"
+        ? totalCount ?? data.length
+        : table.getFilteredRowModel().rows.length,
+    pageSizeOptions,
+    onPageChange: (idx) =>
+      table.setPagination((prev) => ({ ...prev, pageIndex: idx })),
+    onPageSizeChange: (size) =>
+      table.setPagination({ pageIndex: 0, pageSize: size }),
+  };
+
+  const computedFlexWidth = useFlexColumnWidth(table);
+  const flexWidth = tableLayout === "equal" ? computedFlexWidth : undefined;
+
+  const fixedColStyles = React.useMemo<Map<
+    string,
+    React.CSSProperties
+  > | null>(() => {
+    if (tableLayout !== "fixed") return null;
+    const cols = table.getVisibleLeafColumns();
+
+    const isPxExactCol = (col: (typeof cols)[number]) => {
+      const ew = (
+        col.columnDef.meta as { exactWidth?: number | string } | undefined
+      )?.exactWidth;
+      return exactWidthToPx(ew) != null;
     };
-  }, [fetchMoreData]);
 
-  const isEmpty = table.getRowModel().rows?.length === 0;
+    // Full-width table + honour `size` as px: lock every non-exact column to
+    // its `size`, except the last “flex” column which absorbs leftover width
+    // (avoids `calc()` on every <col>/<th> — browsers often distribute badly).
+    const flexColIndices = cols
+      .map((c, i) => (!isPxExactCol(c) ? i : -1))
+      .filter((i) => i >= 0);
+    const growColIndex =
+      flexColIndices.length > 0
+        ? flexColIndices[flexColIndices.length - 1]
+        : -1;
+
+    const map = new Map<string, React.CSSProperties>();
+    cols.forEach((col, index) => {
+      if (isPxExactCol(col)) return;
+
+      if (index === growColIndex) {
+        // No entry → <col> has no width; cell styles omit width — column grows.
+        return;
+      }
+
+      const colSize = col.columnDef.size ?? col.getSize?.() ?? 150;
+      const px =
+        typeof colSize === "number"
+          ? colSize
+          : Number.isFinite(parseFloat(String(colSize)))
+          ? parseFloat(String(colSize))
+          : 150;
+
+      map.set(col.id, {
+        width: `${px}px`,
+        minWidth: `${px}px`,
+        maxWidth: `${px}px`,
+        overflow: "hidden",
+        boxSizing: "border-box" as const,
+      });
+    });
+
+    return map;
+  }, [tableLayout, table.getVisibleLeafColumns()]);
+
+  /**
+   * When `resizable` + `table-layout: fixed`, the table is often wider than
+   * `getTotalSize()` (`max(100%, …)`). Browsers then redistribute slack across
+   * *all* columns — even `<col>` + `th` locked to 42px can visually grow.
+   * Pick one non-exact column to absorb slack (empty `<col>`, no pixel width on
+   * cells) like the non-resizable `fixed` “grow” column. Not used for `equal`
+   * — there we leave non-exact `<col>`s empty and use `flexWidth` on cells only.
+   */
+  const resizableSlackGrowColId = React.useMemo(() => {
+    if (!resizable || tableLayout === "equal") return null;
+    const cols = table.getVisibleLeafColumns();
+    const flexIndices = cols
+      .map((c, i) => {
+        const ew = (
+          c.columnDef.meta as { exactWidth?: number | string } | undefined
+        )?.exactWidth;
+        return exactWidthToPx(ew) == null ? i : -1;
+      })
+      .filter((i) => i >= 0);
+    if (flexIndices.length === 0) return null;
+    return cols[flexIndices[flexIndices.length - 1]]?.id ?? null;
+  }, [resizable, tableLayout, table.getVisibleLeafColumns()]);
+
+  // Helper: find the first data cell (not checkbox/actions) for expand toggle
+  const firstDataCellId = (row: Row<TData>) =>
+    row
+      .getVisibleCells()
+      .find(
+        (c) =>
+          c.column.id !== "__select__" &&
+          c.column.id !== "__actions__" &&
+          c.column.id !== "__reorder__",
+      )?.id;
+
+  // ---- row reorder (drag-and-drop) ----
+  const rowReorderSensors = useSensors(
+    useSensor(PointerSensor),
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+    }),
+  );
+
+  const rowIds = React.useMemo(
+    () =>
+      tableRowsForView.filter((r) => !isRowReorderLocked?.(r)).map((r) => r.id),
+    [tableRowsForView, isRowReorderLocked],
+  );
+
+  const handleRowDragEnd = (event: DragEndEvent) => {
+    const { active, over } = event;
+    if (!over || active.id === over.id || !onRowReorder) return;
+
+    const oldIndex = data.findIndex(
+      (item) =>
+        (getRowIdProp
+          ? getRowIdProp(item)
+          : (item as Record<string, unknown>).id) === active.id,
+    );
+    const newIndex = data.findIndex(
+      (item) =>
+        (getRowIdProp
+          ? getRowIdProp(item)
+          : (item as Record<string, unknown>).id) === over.id,
+    );
+    if (oldIndex === -1 || newIndex === -1) return;
+
+    onRowReorder(arrayMove([...data], oldIndex, newIndex));
+  };
+
+  // `resizable` uses `table-layout: fixed`; without min/max on `meta.exactWidth`
+  // (e.g. __select__), those columns absorb extra table width even when inline
+  // `width: 42px` is set. Lock px-based exactWidth whenever fixed layout applies.
+  const lockPxExactWidth = tableLayout === "fixed" || resizable;
+
+  const showColumnMenuVisibility =
+    columnManagement && columnManagementOptions.visibility !== false;
+  const visibleHideableLeafCount = columnManagement
+    ? table
+        .getAllLeafColumns()
+        .filter((c) => c.getCanHide() && c.getIsVisible()).length
+    : 0;
+
+  // ---- render ----
+  const editContextValue = enableEditing ? editingState : null;
 
   return (
-    <div className="flex w-full h-full rounded-xl overflow-hidden border border-primary-10">
-      <Table className={isEmpty ? "h-full" : ""} rootRef={tableBodyRef}>
-        <TableHeader className="sticky top-0">
-          {table.getHeaderGroups().map((headerGroup) => (
-            <TableRow key={headerGroup.id} className="">
-              {headerGroup.headers.map((header, i) => {
-                return (
-                  <TableHead key={header.id}>
+    <EditContext.Provider value={editContextValue}>
+      <div
+        className={cn(
+          "flex flex-col w-full h-full min-h-0",
+          bordered && "overflow-hidden rounded-md border border-table-c-border",
+          !bordered && "overflow-hidden rounded-none",
+          className,
+        )}
+        data-surface={surface === "panel" ? "panel" : undefined}
+        data-testid={testId}
+      >
+        {/* Scrollable area: header sticks, body scrolls */}
+        <div
+          ref={scrollRef}
+          className={cn(
+            "relative min-h-0 overflow-auto",
+            "ui-scrollbar ui-scrollbar-x-m ui-scrollbar-y-s",
+            isPaginated ? "flex-1" : "h-full",
+          )}
+          onWheel={
+            scrollToHighlightOnMouseLeave
+              ? () => {
+                  userInteractingRef.current = true;
+                }
+              : undefined
+          }
+          onPointerDownCapture={
+            scrollToHighlightOnMouseLeave
+              ? () => {
+                  userInteractingRef.current = true;
+                }
+              : undefined
+          }
+          onMouseLeave={
+            scrollToHighlightOnMouseLeave
+              ? () => {
+                  userInteractingRef.current = false;
+                  scrollHighlightIntoView("smooth");
+                }
+              : undefined
+          }
+        >
+          <Table
+            scrollableWrapper={false}
+            className={cn(
+              (tableLayout === "fixed" ||
+                tableLayout === "equal" ||
+                resizable) &&
+                "table-fixed",
+              isEmpty && "h-full",
+            )}
+            style={
+              resizable
+                ? {
+                    // At least full scroll width, but grow when column sum exceeds it.
+                    width: `max(100%, ${table.getTotalSize()}px)`,
+                  }
+                : { width: "100%" }
+            }
+          >
+            {tableLayout === "fixed" && !resizable && (
+              <colgroup>
+                {table.getVisibleLeafColumns().map((col) => {
+                  const colDef = col.columnDef as ColumnDef<unknown, unknown>;
+                  const exact = getExactWidthStyle(colDef, lockPxExactWidth);
+                  const style = exact ?? fixedColStyles?.get(col.id);
+                  return <col key={col.id} style={style} />;
+                })}
+              </colgroup>
+            )}
+            {resizable && (
+              <colgroup>
+                {table.getVisibleLeafColumns().map((col) => {
+                  const colDef = col.columnDef as ColumnDef<unknown, unknown>;
+                  const exact = getExactWidthStyle(colDef, lockPxExactWidth);
+                  if (exact) return <col key={col.id} style={exact} />;
+                  // Equal: only lock exact cols; flex columns share via flexWidth on th/td.
+                  if (tableLayout === "equal") return <col key={col.id} />;
+                  if (
+                    resizableSlackGrowColId != null &&
+                    col.id === resizableSlackGrowColId
+                  ) {
+                    return <col key={col.id} />;
+                  }
+                  return <col key={col.id} style={{ width: col.getSize() }} />;
+                })}
+              </colgroup>
+            )}
+            {/* Sticky header */}
+            <TableHeader
+              ref={tableHeaderRef}
+              className={cn("sticky top-0 z-10", headerClassName)}
+              data-testid={testId ? `${testId}-thead` : undefined}
+            >
+              {table.getHeaderGroups().map((headerGroup) => (
+                <TableRow
+                  key={headerGroup.id}
+                  divided={false}
+                  colDivided={divided}
+                  className={cn("hover:bg-transparent", headerRowClassName)}
+                >
+                  {headerGroup.headers.map((header) => {
+                    const canSort = header.column.getCanSort();
+                    const isSorted = header.column.getIsSorted();
+                    const showManage =
+                      columnManagement && header.column.getCanHide();
+                    const canResize =
+                      resizable &&
+                      tableLayout !== "equal" &&
+                      header.column.getCanResize();
+                    const isResizing = header.column.getIsResizing();
+                    const fixedFallback =
+                      !resizable && fixedColStyles
+                        ? fixedColStyles.get(header.column.id)
+                        : undefined;
+
+                    const usePixelResizeWidth =
+                      resizable &&
+                      tableLayout !== "equal" &&
+                      !(
+                        resizableSlackGrowColId != null &&
+                        header.column.id === resizableSlackGrowColId
+                      );
+
+                    const headerStyle = resolveHeaderWidthStyle(
+                      header.column.columnDef as ColumnDef<unknown, unknown>,
+                      flexWidth,
+                      fixedFallback,
+                      lockPxExactWidth,
+                      usePixelResizeWidth ? header.getSize() : undefined,
+                    );
+
+                    return (
+                      <TableHead
+                        key={header.id}
+                        colSpan={header.colSpan}
+                        style={headerStyle}
+                        className={cn(
+                          "relative overflow-visible group/col whitespace-pre",
+                          isResizing && "select-none",
+                          header.column.columnDef.meta?.headerCellClassName,
+                          typeof headerCellClassName === "function"
+                            ? headerCellClassName(header)
+                            : headerCellClassName,
+                        )}
+                      >
+                        <div className="flex flex-row items-center gap-1 group/header">
+                          {/* Column label — flex-1 pushes sort + ⋮ to the right */}
+                          <span
+                            className={cn(
+                              "flex flex-1 flex-row items-center overflow-hidden",
+                              canSort && "cursor-pointer select-none",
+                              columnMetaAlignClass(
+                                header.column.columnDef.meta,
+                              ),
+                            )}
+                            onClick={header.column.getToggleSortingHandler()}
+                          >
+                            {header.isPlaceholder
+                              ? null
+                              : flexRender(
+                                  header.column.columnDef.header,
+                                  header.getContext(),
+                                )}
+                          </span>
+
+                          {/* Sort button — visible when sorted; shown on hover when unsorted */}
+                          {canSort && (
+                            <ActionButton
+                              variant="icon"
+                              size="xs"
+                              className={cn(
+                                "shrink-0 transition-opacity",
+                                isSorted
+                                  ? "opacity-100"
+                                  : sortIndicatorVisibility === "always"
+                                  ? "opacity-100"
+                                  : "opacity-0 group-hover/header:opacity-100",
+                              )}
+                              onClick={header.column.getToggleSortingHandler()}
+                              aria-label={
+                                isSorted === "asc"
+                                  ? "Sorted ascending — click to sort descending"
+                                  : isSorted === "desc"
+                                  ? "Sorted descending — click to clear sort"
+                                  : "Sort column"
+                              }
+                            >
+                              {isSorted === "asc" ? (
+                                <ArrowUp className="!size-4" />
+                              ) : isSorted === "desc" ? (
+                                <ArrowDown className="!size-4" />
+                              ) : (
+                                <ArrowUpDown className="!size-4 text-text-g-contrast-medium" />
+                              )}
+                            </ActionButton>
+                          )}
+
+                          {/* ⋮ column menu — hide column + open manage panel */}
+                          {showManage && (
+                            <DropdownMenu
+                              open={columnManageMenuOpenId === header.column.id}
+                              onOpenChange={(open) =>
+                                setColumnManageMenuOpenId(
+                                  open ? header.column.id : null,
+                                )
+                              }
+                              modal={false}
+                            >
+                              <DropdownMenuTrigger asChild>
+                                <ActionButton
+                                  variant="icon"
+                                  size="sm"
+                                  active={
+                                    (manageOpen &&
+                                      manageAnchorId === header.column.id) ||
+                                    columnManageMenuOpenId === header.column.id
+                                  }
+                                  aria-haspopup="menu"
+                                  aria-expanded={
+                                    columnManageMenuOpenId === header.column.id
+                                  }
+                                  aria-label="Column options"
+                                  className="shrink-0"
+                                  ref={(el) => {
+                                    if (el) {
+                                      manageMenuTriggerRef.current.set(
+                                        header.column.id,
+                                        el,
+                                      );
+                                    } else {
+                                      manageMenuTriggerRef.current.delete(
+                                        header.column.id,
+                                      );
+                                    }
+                                  }}
+                                  onClick={(e) => e.stopPropagation()}
+                                >
+                                  <EllipsisVertical className="!size-4" />
+                                </ActionButton>
+                              </DropdownMenuTrigger>
+                              <DropdownMenuContent
+                                align="end"
+                                sideOffset={4}
+                                className="min-w-[220px] py-1"
+                                onCloseAutoFocus={(e) => e.preventDefault()}
+                              >
+                                {showColumnMenuVisibility && (
+                                  <DropdownMenuItem
+                                    className="py-3"
+                                    disabled={
+                                      header.column.getIsVisible() &&
+                                      visibleHideableLeafCount <= 1
+                                    }
+                                    icon={
+                                      <EyeOff className="size-4" aria-hidden />
+                                    }
+                                    onSelect={() => {
+                                      header.column.toggleVisibility(false);
+                                    }}
+                                  >
+                                    Hide {manageColumnHeaderLabel(header)}{" "}
+                                    column
+                                  </DropdownMenuItem>
+                                )}
+                                <DropdownMenuItem
+                                  className="py-3"
+                                  icon={
+                                    <Columns3 className="size-4" aria-hidden />
+                                  }
+                                  onSelect={() => {
+                                    requestAnimationFrame(() => {
+                                      const el =
+                                        manageMenuTriggerRef.current.get(
+                                          header.column.id,
+                                        );
+                                      if (el) {
+                                        openManagePanelAt(
+                                          header.column.id,
+                                          el.getBoundingClientRect(),
+                                        );
+                                      }
+                                    });
+                                  }}
+                                >
+                                  Manage columns
+                                </DropdownMenuItem>
+                              </DropdownMenuContent>
+                            </DropdownMenu>
+                          )}
+                        </div>
+
+                        {/* Resize handle — draggable right edge */}
+                        {canResize && (
+                          <div
+                            onMouseDown={header.getResizeHandler(document)}
+                            onTouchStart={header.getResizeHandler(document)}
+                            onClick={(e) => e.stopPropagation()}
+                            className={cn(
+                              "absolute right-0 top-0 h-full w-[5px] z-10",
+                              "cursor-col-resize select-none touch-none",
+                              "flex items-center justify-center group/resize",
+                            )}
+                          >
+                            <div
+                              className={cn(
+                                "h-4/5 w-1.5 rounded-full transition-all duration-150",
+                                isResizing
+                                  ? "opacity-100 w-0.5 bg-primary-500"
+                                  : "opacity-0 bg-table-c-col-line group-hover/col:opacity-100 group-hover/resize:bg-primary-400",
+                              )}
+                            />
+                          </div>
+                        )}
+                      </TableHead>
+                    );
+                  })}
+                </TableRow>
+              ))}
+            </TableHeader>
+
+            {/*
+             * Body rendering rules:
+             *
+             * Striped (striped=true):
+             *   - TableBody CSS alternates bg-a / bg-b via nth-child on every <tr>
+             *   - Row borders suppressed (handled by alternating bg)
+             *
+             * Expandable tree, non-striped (getSubRows + striped=false):
+             *   - All rows: bg-table-bg-a (solid, no alternating)
+             *   - Every row has border-b separator
+             *
+             * Expandable tree, striped (getSubRows + striped=true):
+             *   - TableBody nth-child alternation applies across all rows (parents + children)
+             *   - Row borders suppressed
+             */}
+            <TableBody
+              striped={striped}
+              data-testid={testId ? `${testId}-tbody` : undefined}
+            >
+              {!isEmpty ? (
+                virtualized ? (
+                  (() => {
+                    const virtualItems = rowVirtualizer.getVirtualItems();
+                    if (!virtualItems.length) return null;
+                    // paddingStart models thead height in *scroll* coords; tbody spacers are only
+                    // for rows inside tbody — subtract it or the first row is pushed down twice.
+                    const top = Math.max(
+                      0,
+                      virtualItems[0]!.start - stickyHeaderHeight,
+                    );
+                    const bottom =
+                      rowVirtualizer.getTotalSize() -
+                      (virtualItems[virtualItems.length - 1]!.end ?? 0);
+
+                    return (
+                      <>
+                        {top > 0 && (
+                          <tr aria-hidden>
+                            <td
+                              colSpan={finalColumns.length}
+                              style={{ height: top }}
+                            />
+                          </tr>
+                        )}
+                        {virtualItems.map((item) => {
+                          const row = tableRowsForView[item.index]!;
+                          const isExpandable = Boolean(getSubRows);
+                          const rowBg =
+                            isExpandable && !striped
+                              ? "bg-table-bg-a"
+                              : undefined;
+                          const isHighlighted = Array.isArray(highlightRowId)
+                            ? highlightRowId.includes(row.id)
+                            : highlightRowId === row.id;
+                          const rowProps = {
+                            divided: isExpandable && !striped ? true : !striped,
+                            colDivided: divided,
+                            "data-state": row.getIsSelected()
+                              ? ("selected" as const)
+                              : undefined,
+                            "data-highlighted": isHighlighted
+                              ? "true"
+                              : undefined,
+                            className: cn(
+                              rowBg,
+                              onRowClick && "cursor-pointer",
+                              typeof rowClassName === "function"
+                                ? rowClassName(row, item.index)
+                                : rowClassName,
+                            ),
+                            onClick: onRowClick
+                              ? (e: React.MouseEvent<HTMLTableRowElement>) =>
+                                  onRowClick(row, e)
+                              : undefined,
+                          };
+
+                          return (
+                            <TableRow
+                              key={row.id}
+                              ref={rowVirtualizer.measureElement}
+                              data-index={item.index}
+                              data-row-id={row.id}
+                              {...rowProps}
+                            >
+                              {renderDataTableBodyCells({
+                                row,
+                                getSubRows,
+                                firstDataCellId,
+                                fixedColStyles,
+                                flexWidth,
+                                lockPxExactWidth,
+                                resizable,
+                                tableLayout,
+                                resizableSlackGrowColId,
+                                cellClassName,
+                                onCellClick,
+                              })}
+                            </TableRow>
+                          );
+                        })}
+                        {bottom > 0 && (
+                          <tr aria-hidden>
+                            <td
+                              colSpan={finalColumns.length}
+                              style={{ height: bottom }}
+                            />
+                          </tr>
+                        )}
+                      </>
+                    );
+                  })()
+                ) : reorderable ? (
+                  <DndContext
+                    sensors={rowReorderSensors}
+                    collisionDetection={closestCenter}
+                    modifiers={[restrictToVerticalAxis]}
+                    onDragEnd={handleRowDragEnd}
+                  >
+                    <SortableContext
+                      items={rowIds}
+                      strategy={verticalListSortingStrategy}
+                    >
+                      {tableRowsForView.map((row, rowIndex) => {
+                        const isExpandable = Boolean(getSubRows);
+                        const rowBg =
+                          isExpandable && !striped
+                            ? "bg-table-bg-a"
+                            : undefined;
+                        const locked = isRowReorderLocked?.(row);
+                        const isHighlighted = Array.isArray(highlightRowId)
+                          ? highlightRowId.includes(row.id)
+                          : highlightRowId === row.id;
+                        const rowProps = {
+                          divided: isExpandable && !striped ? true : !striped,
+                          colDivided: divided,
+                          "data-state": row.getIsSelected()
+                            ? ("selected" as const)
+                            : undefined,
+                          "data-highlighted": isHighlighted
+                            ? "true"
+                            : undefined,
+                          className: cn(
+                            rowBg,
+                            onRowClick && "cursor-pointer",
+                            typeof rowClassName === "function"
+                              ? rowClassName(row, rowIndex)
+                              : rowClassName,
+                          ),
+                          onClick: onRowClick
+                            ? (e: React.MouseEvent<HTMLTableRowElement>) =>
+                                onRowClick(row, e)
+                            : undefined,
+                        };
+
+                        const cells = renderDataTableBodyCells({
+                          row,
+                          getSubRows,
+                          firstDataCellId,
+                          fixedColStyles,
+                          flexWidth,
+                          lockPxExactWidth,
+                          resizable,
+                          tableLayout,
+                          resizableSlackGrowColId,
+                          cellClassName,
+                          onCellClick,
+                        });
+
+                        return locked ? (
+                          <TableRow
+                            key={row.id}
+                            data-row-id={row.id}
+                            {...rowProps}
+                          >
+                            {cells}
+                          </TableRow>
+                        ) : (
+                          <SortableTableRow
+                            key={row.id}
+                            id={row.id}
+                            data-row-id={row.id}
+                            {...rowProps}
+                          >
+                            {cells}
+                          </SortableTableRow>
+                        );
+                      })}
+                    </SortableContext>
+                  </DndContext>
+                ) : (
+                  tableRowsForView.map((row, rowIndex) => {
+                    const isExpandable = Boolean(getSubRows);
+
+                    // Non-striped expandable: solid bg-a on every row
+                    const rowBg =
+                      isExpandable && !striped ? "bg-table-bg-a" : undefined;
+                    const isHighlighted = Array.isArray(highlightRowId)
+                      ? highlightRowId.includes(row.id)
+                      : highlightRowId === row.id;
+
+                    return (
+                      <TableRow
+                        key={row.id}
+                        divided={isExpandable && !striped ? true : !striped}
+                        colDivided={divided}
+                        data-state={
+                          row.getIsSelected() ? "selected" : undefined
+                        }
+                        className={cn(
+                          rowBg,
+                          onRowClick && "cursor-pointer",
+                          typeof rowClassName === "function"
+                            ? rowClassName(row, rowIndex)
+                            : rowClassName,
+                        )}
+                        data-highlighted={isHighlighted ? "true" : undefined}
+                        onClick={
+                          onRowClick
+                            ? (e: React.MouseEvent) => onRowClick(row, e)
+                            : undefined
+                        }
+                        data-row-id={row.id}
+                      >
+                        {renderDataTableBodyCells({
+                          row,
+                          getSubRows,
+                          firstDataCellId,
+                          fixedColStyles,
+                          flexWidth,
+                          lockPxExactWidth,
+                          resizable,
+                          tableLayout,
+                          resizableSlackGrowColId,
+                          cellClassName,
+                          onCellClick,
+                        })}
+                      </TableRow>
+                    );
+                  })
+                )
+              ) : loading ? (
+                <TableRow
+                  className="h-full hover:bg-transparent"
+                  divided={false}
+                >
+                  <TableCell
+                    colSpan={finalColumns.length}
+                    className="typography-body1 text-text-g-contrast-medium text-center h-full min-h-[200px]"
+                  >
                     <div
-                      className="flex flex-row items-center cursor-pointer"
-                      onClick={header.column.getToggleSortingHandler()}
+                      className="flex flex-1 min-h-[200px] h-full flex-col items-center justify-center gap-3 py-16"
+                      role="status"
+                      aria-live="polite"
+                      aria-busy="true"
                     >
-                      {header.isPlaceholder
-                        ? null
-                        : flexRender(
-                            header.column.columnDef.header,
-                            header.getContext()
-                          )}
-                      {{
-                        asc: <ArrowUpIcon className="ml-3 h-4 w-4" />,
-                        desc: <ArrowDownIcon className="ml-3 h-4 w-4" />,
-                      }[header.column.getIsSorted() as string] ??
-                        (header.column.getCanSort() ? (
-                          <ArrowsUpDownIcon className="ml-3 h-4 w-4 text-text-g-contrast-high" />
-                        ) : null)}
+                      <Loader2
+                        className="size-8 shrink-0 animate-spin text-secondary-120"
+                        aria-hidden
+                      />
+                      {loadingLabel}
                     </div>
-                  </TableHead>
-                );
-              })}
-            </TableRow>
-          ))}
-        </TableHeader>
-        <TableBody className="overflow-y-scroll">
-          {!isEmpty ? (
-            table.getRowModel().rows.map((row) => (
-              <TableRow
-                key={row.id}
-                data-state={row.getIsSelected() && "selected"}
-                className=""
-              >
-                {row.getVisibleCells().map((cell) => (
-                  <TableCell key={cell.id}>
-                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
                   </TableCell>
-                ))}
-              </TableRow>
-            ))
-          ) : (
-            <TableRow className="h-full self-stretch">
-              <TableCell
-                colSpan={columns.length}
-                className="typography-body1 text-text-g-contrast-medium text-center h-full"
-              >
-                <div className="flex flex-1 h-full flex-col items-center justify-center gap-3">
-                  <ClipboardDocumentListIcon className="w-8 text-secondary-120" />
-                  There is no information yet.
-                </div>
-              </TableCell>
-            </TableRow>
-          )}
-        </TableBody>
-      </Table>
-    </div>
+                </TableRow>
+              ) : (
+                <TableRow
+                  className="h-full hover:bg-transparent"
+                  divided={false}
+                >
+                  <TableCell
+                    colSpan={finalColumns.length}
+                    className="typography-body1 text-text-g-contrast-medium text-center h-full"
+                  >
+                    <div className="flex flex-1 h-full flex-col items-center justify-center gap-3 py-16">
+                      <ClipboardList className="w-8 text-secondary-120" />
+                      There is no information yet.
+                    </div>
+                  </TableCell>
+                </TableRow>
+              )}
+            </TableBody>
+            {paginationMode === "infinite" &&
+              fetchingMore &&
+              !isEmpty &&
+              table.getVisibleLeafColumns().length > 0 && (
+                <tfoot className="[&_tr]:bg-table-c-row-bg">
+                  <TableRow
+                    divided={false}
+                    className="hover:!bg-table-c-row-bg border-t border-t-table-c-row-line"
+                  >
+                    <TableCell
+                      colSpan={table.getVisibleLeafColumns().length}
+                      className="py-3 text-center typography-body3 text-text-g-contrast-medium bg-inherit"
+                    >
+                      <span
+                        role="status"
+                        aria-live="polite"
+                        className="inline-flex items-center justify-center gap-2"
+                      >
+                        <Loader2
+                          className="size-4 shrink-0 animate-spin"
+                          aria-hidden
+                        />
+                        {fetchingMoreLabel}
+                      </span>
+                    </TableCell>
+                  </TableRow>
+                </tfoot>
+              )}
+          </Table>
+        </div>
+
+        {isPaginated && <TablePagination {...paginationBarProps} />}
+
+        {/* Manage-column panel — portal so it survives column hide/reorder */}
+        {columnManagement && manageOpen && (
+          <Portal.Root>
+            <div
+              className="fixed inset-0 z-40"
+              onClick={() => setManageOpen(false)}
+            />
+            <div
+              className="fixed z-50 w-[460px] rounded-lg bg-modal-surface shadow-[0px_12px_24px_-4px_rgba(0,0,0,0.12)] overflow-hidden"
+              style={{
+                top: managePanelPos.top,
+                right: managePanelPos.right,
+              }}
+              onClick={(e) => e.stopPropagation()}
+            >
+              <ManageColumnPanel
+                table={table}
+                onClose={() => setManageOpen(false)}
+                maxListHeight={managePanelPos.maxListHeight}
+                options={columnManagementOptions}
+              />
+            </div>
+          </Portal.Root>
+        )}
+      </div>
+    </EditContext.Provider>
   );
 }