@mihcm/ui 0.14.1

package/src/DataTable.tsx

@@ -0,0 +1,989 @@
+'use client';
+
+/**
+ * DataTable (web variant — React DOM).
+ *
+ * Full-featured data table powered by TanStack Table v8 and rendered
+ * with the design system's Table primitives. Supports sorting,
+ * filtering, pagination, row selection, column visibility,
+ * expandable rows, column resizing, column/row pinning, grouping,
+ * and faceted filtering — all toggled via boolean props.
+ *
+ * Wiki: docs/components/DataTable.md
+ */
+import {
+  Fragment,
+  useState,
+  useMemo,
+  useCallback,
+  useEffect,
+  useRef,
+  type ReactNode,
+} from 'react';
+import {
+  useReactTable,
+  getCoreRowModel,
+  getSortedRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  getExpandedRowModel,
+  getGroupedRowModel,
+  getFacetedRowModel,
+  getFacetedMinMaxValues,
+  getFacetedUniqueValues,
+  flexRender,
+  createColumnHelper,
+  type ColumnDef,
+  type SortingState,
+  type ColumnFiltersState,
+  type VisibilityState,
+  type ExpandedState,
+  type RowSelectionState,
+  type ColumnPinningState,
+  type RowPinningState,
+  type GroupingState,
+  type Row,
+  type Column,
+  type Header,
+  type HeaderContext,
+  type Table as TanStackTable,
+} from '@tanstack/react-table';
+import { useVirtualizer } from '@tanstack/react-virtual';
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableRow,
+  TableHead,
+  TableCell,
+  type TableHeaderTone,
+  type TableVariant,
+} from './Table.js';
+import { Input } from './Input.js';
+import { Button } from './Button.js';
+import { Checkbox } from './Checkbox.js';
+import { Select, SelectTrigger, SelectContent, SelectItem } from './Select.js';
+import { cn } from './internal/cn.js';
+
+/* ── Re-export for consumer convenience ───────────────────────────── */
+
+export { createColumnHelper };
+export type { ColumnDef, Row, RowSelectionState, TableVariant };
+
+/* ── DataTableColumnHeader ────────────────────────────────────────── */
+
+interface DataTableColumnHeaderProps<TData, TValue> {
+  column: Column<TData, TValue>;
+  title: string;
+  className?: string;
+}
+
+export function DataTableColumnHeader<TData, TValue>({
+  column,
+  title,
+  className,
+}: DataTableColumnHeaderProps<TData, TValue>) {
+  if (!column.getCanSort()) {
+    return <span className={className}>{title}</span>;
+  }
+
+  const sorted = column.getIsSorted();
+
+  return (
+    <button
+      type="button"
+      className={cn(
+        'inline-flex items-center gap-1 -ml-1 px-1 py-0.5 rounded-md',
+        'hover:bg-muted transition-colors duration-150',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        className,
+      )}
+      onClick={column.getToggleSortingHandler()}
+      aria-label={`Sort by ${title}`}
+    >
+      {title}
+      <span className="inline-flex flex-col" aria-hidden>
+        <svg
+          viewBox="0 0 8 4"
+          className={cn(
+            'h-1.5 w-2 transition-transform duration-200',
+            sorted === 'asc' ? 'text-foreground' : 'text-muted-foreground/40',
+          )}
+          fill="currentColor"
+        >
+          <path d="M4 0L8 4H0z" />
+        </svg>
+        <svg
+          viewBox="0 0 8 4"
+          className={cn(
+            'h-1.5 w-2 transition-transform duration-200',
+            sorted === 'desc' ? 'text-foreground' : 'text-muted-foreground/40',
+          )}
+          fill="currentColor"
+        >
+          <path d="M4 4L0 0h8z" />
+        </svg>
+      </span>
+    </button>
+  );
+}
+
+/* ── Column visibility dropdown ───────────────────────────────────── */
+
+function ColumnVisibilityDropdown<TData>({
+  table,
+}: {
+  table: TanStackTable<TData>;
+}) {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    function handleClick(e: MouseEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    }
+    document.addEventListener('mousedown', handleClick);
+    return () => document.removeEventListener('mousedown', handleClick);
+  }, [open]);
+
+  return (
+    <div ref={ref} className="relative">
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={() => setOpen(!open)}
+        aria-expanded={open}
+        aria-haspopup="true"
+      >
+        <svg
+          aria-hidden
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={2}
+          className="h-4 w-4"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M10.5 6h9.75M10.5 6a1.5 1.5 0 11-3 0m3 0a1.5 1.5 0 10-3 0M3.75 6H7.5m3 12h9.75m-9.75 0a1.5 1.5 0 01-3 0m3 0a1.5 1.5 0 00-3 0m-3.75 0H7.5m9-6h3.75m-3.75 0a1.5 1.5 0 01-3 0m3 0a1.5 1.5 0 00-3 0m-9.75 0h9.75"
+          />
+        </svg>
+        Columns
+      </Button>
+      {open && (
+        <div className="absolute right-0 top-full z-50 mt-1 min-w-[10rem] rounded-lg border border-border bg-card p-1 shadow-md">
+          {table.getAllLeafColumns().map((column) => {
+            if (column.id === 'select' || column.id === 'expand') return null;
+            return (
+              <label
+                key={column.id}
+                className="flex cursor-pointer items-center gap-2 rounded-md px-2 py-1.5 text-sm hover:bg-muted transition-colors duration-150"
+              >
+                <Checkbox
+                  size="sm"
+                  checked={column.getIsVisible()}
+                  onCheckedChange={(v) => column.toggleVisibility(!!v)}
+                />
+                <span className="capitalize">
+                  {typeof column.columnDef.header === 'string'
+                    ? column.columnDef.header
+                    : column.id}
+                </span>
+              </label>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/* ── Column filter input ──────────────────────────────────────────── */
+
+function ColumnFilterInput<TData>({
+  column,
+  faceted,
+}: {
+  column: Column<TData, unknown>;
+  faceted: boolean;
+}) {
+  const columnFilterValue = column.getFilterValue();
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  /* Close faceted dropdown on outside click */
+  useEffect(() => {
+    if (!open) return;
+    function handleClick(e: MouseEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    }
+    document.addEventListener('mousedown', handleClick);
+    return () => document.removeEventListener('mousedown', handleClick);
+  }, [open]);
+
+  /* Faceted: number column → min/max range */
+  if (faceted) {
+    const facetedMinMax = column.getFacetedMinMaxValues?.();
+    const isNumberColumn =
+      facetedMinMax !== undefined &&
+      facetedMinMax[0] !== undefined &&
+      typeof facetedMinMax[0] === 'number';
+
+    if (isNumberColumn) {
+      const [min, max] = facetedMinMax as [number, number];
+      const currentRange = (columnFilterValue as [number, number] | undefined) ?? [
+        undefined,
+        undefined,
+      ];
+      return (
+        <div className="grid min-w-[10rem] grid-cols-2 gap-1">
+          <Input
+            type="number"
+            value={currentRange[0] ?? ''}
+            onChange={(e) => {
+              const val = e.target.value ? Number(e.target.value) : undefined;
+              column.setFilterValue((old: [number, number] | undefined) => [
+                val,
+                old?.[1],
+              ]);
+            }}
+            placeholder={`Min (${min})`}
+            className="h-8 min-w-0 bg-background px-2 text-xs shadow-mi-input"
+          />
+          <Input
+            type="number"
+            value={currentRange[1] ?? ''}
+            onChange={(e) => {
+              const val = e.target.value ? Number(e.target.value) : undefined;
+              column.setFilterValue((old: [number, number] | undefined) => [
+                old?.[0],
+                val,
+              ]);
+            }}
+            placeholder={`Max (${max})`}
+            className="h-8 min-w-0 bg-background px-2 text-xs shadow-mi-input"
+          />
+        </div>
+      );
+    }
+
+    /* Faceted: string column → unique values list */
+    const uniqueValues = column.getFacetedUniqueValues?.();
+    if (uniqueValues && uniqueValues.size > 0) {
+      const sortedValues = Array.from(uniqueValues.keys())
+        .filter((v): v is string => typeof v === 'string')
+        .sort();
+      return (
+        <div ref={ref} className="relative">
+          <Input
+            type="text"
+            value={(columnFilterValue as string) ?? ''}
+            onChange={(e) => column.setFilterValue(e.target.value || undefined)}
+            onFocus={() => setOpen(true)}
+            placeholder="Filter..."
+            className="h-8 min-w-[8rem] bg-background px-2 text-xs shadow-mi-input"
+          />
+          {open && sortedValues.length > 0 && (
+            <div className="absolute left-0 top-full z-50 mt-1 max-h-40 min-w-full overflow-y-auto rounded-md border border-border bg-card p-1 shadow-mi-modal">
+              {sortedValues.map((val) => (
+                <button
+                  key={val}
+                  type="button"
+                  className="block w-full rounded px-2 py-1 text-left text-xs hover:bg-muted transition-colors duration-150"
+                  onClick={() => {
+                    column.setFilterValue(val);
+                    setOpen(false);
+                  }}
+                >
+                  {val}{' '}
+                  <span className="text-muted-foreground">
+                    ({uniqueValues.get(val)})
+                  </span>
+                </button>
+              ))}
+            </div>
+          )}
+        </div>
+      );
+    }
+  }
+
+  /* Default: simple text input */
+  return (
+    <Input
+      type="text"
+      value={(columnFilterValue as string) ?? ''}
+      onChange={(e) => column.setFilterValue(e.target.value || undefined)}
+      placeholder="Filter..."
+      className="h-8 min-w-[8rem] bg-background px-2 text-xs shadow-mi-input"
+    />
+  );
+}
+
+/* ── DataTable ────────────────────────────────────────────────────── */
+
+export interface DataTableProps<TData, TValue> {
+  columns: ColumnDef<TData, TValue>[];
+  data: TData[];
+  /** Show a global search input above the table. */
+  searchable?: boolean;
+  /** Placeholder for the search input. */
+  searchPlaceholder?: string;
+  /** Enable column header click-to-sort. @default true */
+  sortable?: boolean;
+  /** Show pagination controls below the table. */
+  paginated?: boolean;
+  /** Rows per page when `paginated` is true. @default 10 */
+  pageSize?: number;
+  /** Options for the rows-per-page selector. @default [5, 10, 20, 50] */
+  pageSizeOptions?: number[];
+  /** Add a selection checkbox column. */
+  selectable?: boolean;
+  /** Show a column-visibility toggle dropdown. */
+  columnVisibility?: boolean;
+  /** Enable expandable rows. */
+  expandable?: boolean;
+  /** Row-level guard for expand. */
+  getRowCanExpand?: (row: Row<TData>) => boolean;
+  /** Content rendered when a row is expanded. */
+  renderSubComponent?: (props: { row: Row<TData> }) => ReactNode;
+  /** Called whenever row selection changes. */
+  onRowSelectionChange?: (selection: RowSelectionState) => void;
+  /** Enable per-column filter inputs below each header. */
+  columnFilterable?: boolean;
+  /** Allow shift+click to sort by multiple columns. */
+  multiSort?: boolean;
+  /** Allow columns to be resized by dragging the header edge. */
+  resizable?: boolean;
+  /** Enable column pinning. Provide pinned column IDs via `pinnedColumns`. */
+  columnPinnable?: boolean;
+  /** Column IDs to pin left/right. Only used when `columnPinnable` is true. */
+  pinnedColumns?: { left?: string[]; right?: string[] };
+  /** Enable row pinning. Provide pinned row IDs via `pinnedRows`. */
+  rowPinnable?: boolean;
+  /** Row IDs to pin top/bottom. Only used when `rowPinnable` is true. */
+  pinnedRows?: { top?: string[]; bottom?: string[] };
+  /** Enable row grouping by column. */
+  groupable?: boolean;
+  /** Enable faceted filtering (unique value lists, min/max ranges). Requires `columnFilterable`. */
+  faceted?: boolean;
+  /** Visual style variant for the table. @default 'default' */
+  variant?: TableVariant;
+  /** Semantic header color. */
+  headerTone?: TableHeaderTone;
+  /** ClassName applied to every header cell. */
+  headerClassName?: string;
+  /** Enable a minimum width table layout for wide/large datasets. */
+  wide?: boolean;
+  /** Render large row sets through TanStack Virtual inside a fixed-height scroll area. */
+  virtualized?: boolean;
+  /** Scroll container height when `virtualized` is true. */
+  virtualHeight?: number;
+  /** Estimated row height for TanStack Virtual. */
+  estimateRowHeight?: number;
+  /** Extra rows rendered before/after the viewport. */
+  virtualOverscan?: number;
+  /** Additional className on the root wrapper. */
+  className?: string;
+  /** Message shown when no rows match. @default 'No results.' */
+  emptyMessage?: string;
+}
+
+export function DataTable<TData, TValue>({
+  columns: userColumns,
+  data,
+  searchable = false,
+  searchPlaceholder = 'Search...',
+  sortable = true,
+  paginated = false,
+  pageSize: initialPageSize = 10,
+  pageSizeOptions = [5, 10, 20, 50],
+  selectable = false,
+  columnVisibility: showColumnVisibility = false,
+  expandable = false,
+  getRowCanExpand,
+  renderSubComponent,
+  onRowSelectionChange,
+  columnFilterable = false,
+  multiSort = false,
+  resizable = false,
+  columnPinnable = false,
+  pinnedColumns,
+  rowPinnable = false,
+  pinnedRows,
+  groupable = false,
+  faceted = false,
+  variant = 'default',
+  headerTone = 'default',
+  headerClassName,
+  wide = false,
+  virtualized = false,
+  virtualHeight = 520,
+  estimateRowHeight = 56,
+  virtualOverscan = 8,
+  className,
+  emptyMessage = 'No results.',
+}: DataTableProps<TData, TValue>) {
+  /* ── State ──────────────────────────────────────────────────────── */
+  const [sorting, setSorting] = useState<SortingState>([]);
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
+  const [globalFilter, setGlobalFilter] = useState('');
+  const [visibility, setVisibility] = useState<VisibilityState>({});
+  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
+  const [expanded, setExpanded] = useState<ExpandedState>({});
+  const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: initialPageSize });
+  const [grouping, setGrouping] = useState<GroupingState>([]);
+  const [columnPinning, setColumnPinning] = useState<ColumnPinningState>(
+    pinnedColumns ?? {},
+  );
+  const [rowPinning, setRowPinning] = useState<RowPinningState>(
+    pinnedRows ?? {},
+  );
+  const tableScrollRef = useRef<HTMLDivElement>(null);
+
+  /* ── Sync controlled pinning props ─────────────────────────────── */
+  useEffect(() => {
+    if (columnPinnable && pinnedColumns !== undefined) {
+      setColumnPinning(pinnedColumns);
+    }
+  }, [columnPinnable, pinnedColumns]);
+
+  useEffect(() => {
+    if (rowPinnable && pinnedRows !== undefined) {
+      setRowPinning(pinnedRows);
+    }
+  }, [rowPinnable, pinnedRows]);
+
+  /* ── Notify parent of selection changes ─────────────────────────── */
+  useEffect(() => {
+    onRowSelectionChange?.(rowSelection);
+  }, [rowSelection, onRowSelectionChange]);
+
+  /* ── Compose columns (selection + expand + user) ────────────────── */
+  const columns = useMemo(() => {
+    const cols: ColumnDef<TData, unknown>[] = [];
+
+    if (selectable) {
+      cols.push({
+        id: 'select',
+        header: ({ table }: HeaderContext<TData, unknown>) => (
+          <Checkbox
+            checked={
+              table.getIsAllPageRowsSelected()
+                ? true
+                : table.getIsSomePageRowsSelected()
+                  ? 'indeterminate'
+                  : false
+            }
+            onCheckedChange={(v) => table.toggleAllPageRowsSelected(!!v)}
+            aria-label="Select all"
+          />
+        ),
+        cell: ({ row }) => (
+          <Checkbox
+            checked={row.getIsSelected()}
+            onCheckedChange={(v) => row.toggleSelected(!!v)}
+            aria-label="Select row"
+          />
+        ),
+        enableSorting: false,
+        enableHiding: false,
+        enableColumnFilter: false,
+        enableGrouping: false,
+      });
+    }
+
+    if (expandable) {
+      cols.push({
+        id: 'expand',
+        header: () => null,
+        cell: ({ row }) =>
+          row.getCanExpand() ? (
+            <button
+              type="button"
+              onClick={row.getToggleExpandedHandler()}
+              aria-label={row.getIsExpanded() ? 'Collapse row' : 'Expand row'}
+              className="p-1 rounded-md hover:bg-muted transition-colors duration-150 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              <svg
+                aria-hidden
+                viewBox="0 0 16 16"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth={2}
+                className={cn(
+                  'h-4 w-4 transition-transform duration-200',
+                  row.getIsExpanded() && 'rotate-90',
+                )}
+              >
+                <path strokeLinecap="round" strokeLinejoin="round" d="M6 4l4 4-4 4" />
+              </svg>
+            </button>
+          ) : null,
+        enableSorting: false,
+        enableHiding: false,
+        enableColumnFilter: false,
+        enableGrouping: false,
+      });
+    }
+
+    cols.push(...(userColumns as ColumnDef<TData, unknown>[]));
+    return cols;
+  }, [userColumns, selectable, expandable]);
+
+  /* ── Table instance ─────────────────────────────────────────────── */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const table = useReactTable<TData>({
+    data,
+    columns,
+    state: {
+      sorting,
+      columnFilters,
+      globalFilter,
+      columnVisibility: visibility,
+      rowSelection,
+      expanded,
+      pagination,
+      ...(groupable ? { grouping } : {}),
+      ...(columnPinnable ? { columnPinning } : {}),
+      ...(rowPinnable ? { rowPinning } : {}),
+    },
+    enableSorting: sortable,
+    ...(multiSort ? { enableMultiSort: true } : {}),
+    ...(resizable
+      ? { enableColumnResizing: true, columnResizeMode: 'onChange' as const }
+      : {}),
+    autoResetPageIndex: false,
+    onSortingChange: setSorting,
+    onColumnFiltersChange: setColumnFilters,
+    onGlobalFilterChange: setGlobalFilter,
+    onColumnVisibilityChange: setVisibility,
+    onRowSelectionChange: setRowSelection,
+    onExpandedChange: setExpanded,
+    onPaginationChange: setPagination,
+    ...(groupable ? { onGroupingChange: setGrouping } : {}),
+    ...(columnPinnable ? { onColumnPinningChange: setColumnPinning } : {}),
+    ...(rowPinnable ? { onRowPinningChange: setRowPinning } : {}),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getRowCanExpand: (getRowCanExpand as any) ?? (() => expandable),
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+    getExpandedRowModel: getExpandedRowModel(),
+    ...(groupable ? { getGroupedRowModel: getGroupedRowModel() } : {}),
+    ...(faceted
+      ? {
+          getFacetedRowModel: getFacetedRowModel(),
+          getFacetedMinMaxValues: getFacetedMinMaxValues(),
+          getFacetedUniqueValues: getFacetedUniqueValues(),
+        }
+      : {}),
+  });
+
+  /* ── Pagination helpers ─────────────────────────────────────────── */
+  const pageIndex = table.getState().pagination.pageIndex;
+  const pageCount = table.getPageCount();
+  const regularRows = table.getRowModel().rows;
+  const rowVirtualizer = useVirtualizer({
+    count: regularRows.length,
+    getScrollElement: () => tableScrollRef.current,
+    estimateSize: () => estimateRowHeight,
+    overscan: virtualOverscan,
+    enabled: virtualized,
+  });
+  const virtualRows = virtualized ? rowVirtualizer.getVirtualItems() : [];
+  const topVirtualPadding = virtualized && virtualRows.length > 0 ? virtualRows[0]?.start ?? 0 : 0;
+  const bottomVirtualPadding =
+    virtualized && virtualRows.length > 0
+      ? rowVirtualizer.getTotalSize() - (virtualRows.at(-1)?.end ?? 0)
+      : 0;
+  const rowsToRender = virtualized
+    ? virtualRows.map((virtualRow) => regularRows[virtualRow.index]).filter((row): row is Row<TData> => Boolean(row))
+    : regularRows;
+
+  /* ── Pinning style helper ──────────────────────────────────────── */
+  const getPinningStyles = useCallback(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (header: Header<any, unknown>): React.CSSProperties => {
+      if (!columnPinnable) return {};
+      const isPinned = header.column.getIsPinned();
+      if (!isPinned) return {};
+      return {
+        position: 'sticky',
+        left: isPinned === 'left' ? `${header.getStart('left')}px` : undefined,
+        right: isPinned === 'right' ? `${header.getStart('right')}px` : undefined,
+        zIndex: 1,
+        backgroundColor: 'var(--color-card, #fff)',
+      };
+    },
+    [columnPinnable],
+  );
+
+  const getCellPinningStyles = useCallback(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (cell: { column: Column<any, unknown> }): React.CSSProperties => {
+      if (!columnPinnable) return {};
+      const isPinned = cell.column.getIsPinned();
+      if (!isPinned) return {};
+      return {
+        position: 'sticky',
+        left: isPinned === 'left' ? `${cell.column.getStart('left')}px` : undefined,
+        right: isPinned === 'right' ? `${cell.column.getStart('right')}px` : undefined,
+        zIndex: 1,
+        backgroundColor: 'var(--color-card, #fff)',
+      };
+    },
+    [columnPinnable],
+  );
+
+  /* ── Render ─────────────────────────────────────────────────────── */
+  return (
+    <div className={cn('w-full space-y-4', className)}>
+      {/* Toolbar */}
+      {(searchable || showColumnVisibility) && (
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+          {searchable && (
+            <Input
+              placeholder={searchPlaceholder}
+              value={globalFilter}
+              onChange={(e) => setGlobalFilter(e.target.value)}
+              className="w-full bg-background shadow-mi-input sm:max-w-sm"
+              size="sm"
+              leadingIcon={
+                <svg
+                  aria-hidden
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth={2}
+                  className="h-4 w-4"
+                >
+                  <circle cx="11" cy="11" r="8" />
+                  <path strokeLinecap="round" d="m21 21-4.35-4.35" />
+                </svg>
+              }
+            />
+          )}
+          {showColumnVisibility && (
+            <div className="sm:ml-auto">
+              <ColumnVisibilityDropdown table={table} />
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Table */}
+      <div
+        ref={tableScrollRef}
+        className={cn(
+        'overflow-x-auto overflow-y-visible rounded-xl bg-card',
+        virtualized && 'overflow-y-auto',
+        (variant === 'bordered' || variant === 'card') && 'border border-border shadow-mi-card',
+      )}
+        style={virtualized ? { maxHeight: virtualHeight } : undefined}
+      >
+        <Table
+          variant={variant}
+          headerTone={headerTone}
+          className={cn((wide || columnFilterable || resizable) && 'min-w-[960px]')}
+          {...(resizable ? { style: { width: table.getCenterTotalSize() } } : {})}
+        >
+          <TableHeader>
+            {table.getHeaderGroups().map((headerGroup) => (
+              <Fragment key={headerGroup.id}>
+                <TableRow>
+                  {headerGroup.headers.map((header) => (
+                    <TableHead
+                      key={header.id}
+                      colSpan={header.colSpan}
+                      style={{
+                        width: resizable ? header.getSize() : (header.getSize() !== 150 ? header.getSize() : undefined),
+                        ...getPinningStyles(header),
+                      }}
+                      className={cn(
+                        'h-12 whitespace-nowrap px-3 py-2 align-middle',
+                        resizable && 'relative',
+                        (header.column.id === 'select' || header.column.id === 'expand') && 'w-12 min-w-12',
+                        headerClassName,
+                      )}
+                    >
+                      {header.isPlaceholder ? null : (
+                        <div className="flex min-w-0 items-center gap-1">
+                          {groupable && header.column.getCanGroup() && (
+                            <button
+                              type="button"
+                              onClick={header.column.getToggleGroupingHandler()}
+                              className={cn(
+                                'rounded p-0.5 hover:bg-muted transition-colors duration-150',
+                                'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                              )}
+                              aria-label={
+                                header.column.getIsGrouped()
+                                  ? `Ungroup by ${header.column.id}`
+                                  : `Group by ${header.column.id}`
+                              }
+                              title={
+                                header.column.getIsGrouped()
+                                  ? `Ungroup by ${header.column.id}`
+                                  : `Group by ${header.column.id}`
+                              }
+                            >
+                              <svg
+                                aria-hidden
+                                viewBox="0 0 16 16"
+                                fill="none"
+                                stroke="currentColor"
+                                strokeWidth={1.5}
+                                className={cn(
+                                  'h-3.5 w-3.5',
+                                  header.column.getIsGrouped()
+                                    ? 'text-foreground'
+                                    : 'text-muted-foreground/50',
+                                )}
+                              >
+                                <path
+                                  strokeLinecap="round"
+                                  strokeLinejoin="round"
+                                  d="M2 4h12M2 8h8M2 12h4"
+                                />
+                              </svg>
+                            </button>
+                          )}
+
+                          {flexRender(header.column.columnDef.header, header.getContext())}
+                        </div>
+                      )}
+
+                      {resizable && (
+                        <div
+                          onMouseDown={header.getResizeHandler()}
+                          onTouchStart={header.getResizeHandler()}
+                          onDoubleClick={() => header.column.resetSize()}
+                          role="separator"
+                          aria-orientation="vertical"
+                          className={cn(
+                            'absolute right-0 top-0 h-full w-1 cursor-col-resize select-none touch-none',
+                            'hover:bg-primary/50 transition-colors duration-150',
+                            header.column.getIsResizing() && 'bg-primary',
+                          )}
+                        />
+                      )}
+                    </TableHead>
+                  ))}
+                </TableRow>
+                {columnFilterable && (
+                  <TableRow className="bg-muted/30 hover:bg-muted/30">
+                    {headerGroup.headers.map((header) => (
+                      <TableHead
+                        key={`${header.id}-filter`}
+                        colSpan={header.colSpan}
+                        style={{
+                          width: resizable ? header.getSize() : (header.getSize() !== 150 ? header.getSize() : undefined),
+                          ...getPinningStyles(header),
+                        }}
+                        className={cn(
+                          'h-12 border-t border-border px-3 py-2 align-middle',
+                          (header.column.id === 'select' || header.column.id === 'expand') && 'w-12 min-w-12',
+                        )}
+                      >
+                        {!header.isPlaceholder && header.column.getCanFilter() ? (
+                          <ColumnFilterInput
+                            column={header.column}
+                            faceted={faceted}
+                          />
+                        ) : null}
+                      </TableHead>
+                    ))}
+                  </TableRow>
+                )}
+              </Fragment>
+            ))}
+          </TableHeader>
+          <TableBody>
+            {/* Pinned top rows */}
+            {rowPinnable &&
+              table.getTopRows().map((row) => (
+                <Fragment key={row.id}>
+                  <TableRow
+                    data-state={row.getIsSelected() ? 'selected' : undefined}
+                    className="bg-muted/30"
+                  >
+                    {row.getVisibleCells().map((cell) => (
+                      <TableCell key={cell.id} style={getCellPinningStyles(cell)}>
+                        {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                      </TableCell>
+                    ))}
+                  </TableRow>
+                </Fragment>
+              ))}
+
+            {/* Regular rows */}
+            {regularRows.length ? (
+              <>
+                {topVirtualPadding > 0 ? (
+                  <TableRow aria-hidden>
+                    <TableCell colSpan={columns.length} style={{ height: topVirtualPadding, padding: 0 }} />
+                  </TableRow>
+                ) : null}
+                {rowsToRender.map((row) => (
+                <Fragment key={row.id}>
+                  <TableRow
+                    data-state={row.getIsSelected() ? 'selected' : undefined}
+                  >
+                    {row.getVisibleCells().map((cell) => (
+                      <TableCell key={cell.id} style={getCellPinningStyles(cell)}>
+                        {/* Grouped cell rendering */}
+                        {groupable && cell.getIsGrouped() ? (
+                          <button
+                            type="button"
+                            onClick={row.getToggleExpandedHandler()}
+                            className="inline-flex items-center gap-1 font-medium"
+                          >
+                            <svg
+                              aria-hidden
+                              viewBox="0 0 16 16"
+                              fill="none"
+                              stroke="currentColor"
+                              strokeWidth={2}
+                              className={cn(
+                                'h-3.5 w-3.5 transition-transform duration-200',
+                                row.getIsExpanded() && 'rotate-90',
+                              )}
+                            >
+                              <path strokeLinecap="round" strokeLinejoin="round" d="M6 4l4 4-4 4" />
+                            </svg>
+                            {flexRender(cell.column.columnDef.cell, cell.getContext())}{' '}
+                            <span className="text-muted-foreground text-xs">
+                              ({row.subRows.length})
+                            </span>
+                          </button>
+                        ) : groupable && cell.getIsAggregated() ? (
+                          flexRender(
+                            cell.column.columnDef.aggregatedCell ?? cell.column.columnDef.cell,
+                            cell.getContext(),
+                          )
+                        ) : groupable && cell.getIsPlaceholder() ? null : (
+                          flexRender(cell.column.columnDef.cell, cell.getContext())
+                        )}
+                      </TableCell>
+                    ))}
+                  </TableRow>
+                  {row.getIsExpanded() && renderSubComponent && !row.subRows.length && (
+                    <TableRow key={`${row.id}-expanded`}>
+                      <TableCell
+                        colSpan={row.getVisibleCells().length}
+                        className="p-0"
+                      >
+                        {renderSubComponent({ row: row as Row<TData> })}
+                      </TableCell>
+                    </TableRow>
+                  )}
+                </Fragment>
+                ))}
+                {bottomVirtualPadding > 0 ? (
+                  <TableRow aria-hidden>
+                    <TableCell colSpan={columns.length} style={{ height: bottomVirtualPadding, padding: 0 }} />
+                  </TableRow>
+                ) : null}
+              </>
+            ) : (
+              <TableRow>
+                <TableCell
+                  colSpan={columns.length}
+                  className="h-24 text-center text-muted-foreground"
+                >
+                  {emptyMessage}
+                </TableCell>
+              </TableRow>
+            )}
+
+            {/* Pinned bottom rows */}
+            {rowPinnable &&
+              table.getBottomRows().map((row) => (
+                <Fragment key={row.id}>
+                  <TableRow
+                    data-state={row.getIsSelected() ? 'selected' : undefined}
+                    className="bg-muted/30"
+                  >
+                    {row.getVisibleCells().map((cell) => (
+                      <TableCell key={cell.id} style={getCellPinningStyles(cell)}>
+                        {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                      </TableCell>
+                    ))}
+                  </TableRow>
+                </Fragment>
+              ))}
+          </TableBody>
+        </Table>
+      </div>
+
+      {/* Pagination */}
+      {paginated && (
+        <div className="flex flex-col gap-3 text-sm sm:flex-row sm:items-center sm:justify-between">
+          {/* Selection count (left) */}
+          <div className="text-muted-foreground">
+            {selectable && (
+              <span>
+                {table.getFilteredSelectedRowModel().rows.length} of{' '}
+                {table.getFilteredRowModel().rows.length} row(s) selected
+              </span>
+            )}
+          </div>
+
+          {/* Page size + nav (right) */}
+          <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:gap-4">
+            {/* Rows per page */}
+            <div className="flex items-center gap-2">
+              <span className="text-muted-foreground whitespace-nowrap">Rows per page</span>
+              <Select
+                value={String(table.getState().pagination.pageSize)}
+                onValueChange={(v) => table.setPageSize(Number(v))}
+              >
+                <SelectTrigger className="h-7 w-[70px] text-sm" />
+                <SelectContent>
+                  {pageSizeOptions.map((size) => (
+                    <SelectItem key={size} value={String(size)}>
+                      {size}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </div>
+
+            {/* Page indicator */}
+            <span className="text-muted-foreground whitespace-nowrap">
+              Page {pageIndex + 1} of {pageCount || 1}
+            </span>
+
+            {/* Navigation */}
+            <div className="flex items-center gap-1">
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => table.previousPage()}
+                disabled={!table.getCanPreviousPage()}
+              >
+                Previous
+              </Button>
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => table.nextPage()}
+                disabled={!table.getCanNextPage()}
+              >
+                Next
+              </Button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}