@thangnqdev/ui 0.2.0 → 0.2.2

package/src/data-display/DataTablePro.tsx

@@ -1,534 +1,534 @@
-import React, { useState, useMemo, forwardRef, useEffect, useRef } from 'react';
-import {
-  ChevronUp,
-  ChevronDown,
-  ChevronsUpDown,
-  Search,
-  Download,
-  Trash2,
-  ChevronLeft,
-  ChevronRight,
-  Filter,
-  Loader2,
-} from 'lucide-react';
-import { cn } from '../utils/cn';
-import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from './Table';
-import { Button } from '../buttons/Button';
-import { Checkbox } from '../forms/Checkbox';
-
-export interface SortRule {
-  key: string;
-  direction: 'asc' | 'desc';
-}
-
-export interface ColumnDef<TData, TValue = any> {
-  key: string;
-  header: string | React.ReactNode;
-  accessor?: (row: TData) => TValue;
-  render?: (row: TData, index: number, value: TValue) => React.ReactNode;
-  sortable?: boolean;
-  sortComparator?: (a: TData, b: TData) => number;
-  width?: string;
-}
-
-export interface DataTableProProps<TData extends Record<string, any>> {
-  data: TData[];
-  columns: ColumnDef<TData>[];
-  keyExtractor: (row: TData) => string;
-  searchable?: boolean;
-  searchPlaceholder?: string;
-  selectable?: boolean;
-  selectedKeys?: string[];
-  defaultSelectedKeys?: string[];
-  onSelectionChange?: (selectedKeys: string[]) => void;
-  pageSize?: number;
-  pageSizeOptions?: number[];
-  title?: string;
-  description?: string;
-  actions?: React.ReactNode;
-  className?: string;
-  loading?: boolean;
-
-  // Sorting
-  multiSort?: boolean;
-  sorting?: SortRule[] | null;
-  defaultSorting?: SortRule[];
-  onSortingChange?: (sorting: SortRule[]) => void;
-
-  // Server-side / Manual controls
-  manualPagination?: boolean;
-  manualSorting?: boolean;
-  manualFiltering?: boolean;
-  pageIndex?: number;
-  pageCount?: number;
-  totalCount?: number;
-  onPaginationChange?: (page: number, pageSize: number) => void;
-  searchQuery?: string;
-  onSearchChange?: (query: string) => void;
-  onSelectAllDataset?: () => void;
-  emptyText?: string;
-}
-
-export function DataTablePro<TData extends Record<string, any>>({
-  data,
-  columns,
-  keyExtractor,
-  searchable = true,
-  searchPlaceholder = 'Search all records...',
-  selectable = true,
-  selectedKeys: controlledSelectedKeys,
-  defaultSelectedKeys = [],
-  onSelectionChange,
-  pageSize: initialPageSize = 10,
-  pageSizeOptions = [5, 10, 25, 50],
-  title,
-  description,
-  actions,
-  className,
-  loading = false,
-
-  // Multi-column sorting
-  multiSort = true,
-  sorting: controlledSorting,
-  defaultSorting = [],
-  onSortingChange,
-
-  // Server-side / manual mode props
-  manualPagination = false,
-  manualSorting = false,
-  manualFiltering = false,
-  pageIndex: controlledPageIndex,
-  pageCount: controlledPageCount,
-  totalCount: controlledTotalCount,
-  onPaginationChange,
-  searchQuery: controlledSearchQuery,
-  onSearchChange,
-  onSelectAllDataset,
-  emptyText = 'No matching records found.',
-}: DataTableProProps<TData>) {
-  // 1. Search state
-  const [internalSearch, setInternalSearch] = useState('');
-  const search = controlledSearchQuery !== undefined ? controlledSearchQuery : internalSearch;
-
-  // 2. Multi-column sorting state
-  const [internalSorting, setInternalSorting] = useState<SortRule[]>(defaultSorting);
-  const currentSorting = controlledSorting !== undefined ? controlledSorting ?? [] : internalSorting;
-
-  // 3. Pagination state
-  const [internalCurrentPage, setInternalCurrentPage] = useState(1);
-  const currentPage = controlledPageIndex !== undefined ? controlledPageIndex : internalCurrentPage;
-
-  const [internalPageSize, setInternalPageSize] = useState(initialPageSize);
-  const pageSize = internalPageSize;
-
-  // 4. Selection state
-  const [internalSelectedKeys, setInternalSelectedKeys] = useState<string[]>(defaultSelectedKeys);
-  const isSelectedControlled = controlledSelectedKeys !== undefined;
-  const selectedKeys = isSelectedControlled ? controlledSelectedKeys : internalSelectedKeys;
-
-  const handleSelectionUpdate = (nextKeys: string[]) => {
-    if (!isSelectedControlled) {
-      setInternalSelectedKeys(nextKeys);
-    }
-    onSelectionChange?.(nextKeys);
-  };
-
-  // Search filtering (Client-side when not manual)
-  const filteredData = useMemo(() => {
-    if (manualFiltering || !search.trim()) return data;
-    const q = search.toLowerCase();
-
-    return data.filter((row) => {
-      return columns.some((col) => {
-        const val = col.accessor ? col.accessor(row) : row[col.key];
-        if (val === null || val === undefined) return false;
-        return String(val).toLowerCase().includes(q);
-      });
-    });
-  }, [data, search, columns, manualFiltering]);
-
-  // True Multi-Column Sorting (Client-side when not manual)
-  const sortedData = useMemo(() => {
-    if (manualSorting || currentSorting.length === 0) return filteredData;
-
-    return [...filteredData].sort((a, b) => {
-      for (const { key, direction } of currentSorting) {
-        const col = columns.find((c) => c.key === key);
-        let comp = 0;
-
-        if (col?.sortComparator) {
-          comp = col.sortComparator(a, b);
-        } else {
-          const valA = col?.accessor ? col.accessor(a) : a[key];
-          const valB = col?.accessor ? col.accessor(b) : b[key];
-
-          if (valA === valB) continue;
-          if (valA === null || valA === undefined) return 1;
-          if (valB === null || valB === undefined) return -1;
-
-          comp = valA < valB ? -1 : 1;
-        }
-
-        if (comp !== 0) {
-          return direction === 'asc' ? comp : -comp;
-        }
-      }
-      return 0;
-    });
-  }, [filteredData, currentSorting, columns, manualSorting]);
-
-  // Pagination calculations
-  const totalItems = controlledTotalCount !== undefined ? controlledTotalCount : sortedData.length;
-  const totalPages = controlledPageCount !== undefined
-    ? Math.max(1, controlledPageCount)
-    : Math.max(1, Math.ceil(totalItems / pageSize));
-
-  // Reset/clamp page if out of range on client-side filter
-  useEffect(() => {
-    if (!manualPagination && currentPage > totalPages && totalPages > 0) {
-      setInternalCurrentPage(totalPages);
-      onPaginationChange?.(totalPages, pageSize);
-    }
-  }, [totalPages, currentPage, manualPagination, pageSize, onPaginationChange]);
-
-  const paginatedData = useMemo(() => {
-    if (manualPagination) return data;
-    const start = (currentPage - 1) * pageSize;
-    return sortedData.slice(start, start + pageSize);
-  }, [data, sortedData, currentPage, pageSize, manualPagination]);
-
-  // Sorting handler supporting Shift+Click for multi-sort
-  const handleSort = (key: string, e?: React.MouseEvent) => {
-    const isShift = e?.shiftKey || false;
-    let nextSorting: SortRule[] = [...currentSorting];
-    const existingIdx = nextSorting.findIndex((s) => s.key === key);
-
-    if (isShift && multiSort) {
-      if (existingIdx >= 0) {
-        if (nextSorting[existingIdx].direction === 'asc') {
-          nextSorting[existingIdx] = { key, direction: 'desc' };
-        } else {
-          nextSorting.splice(existingIdx, 1);
-        }
-      } else {
-        nextSorting.push({ key, direction: 'asc' });
-      }
-    } else {
-      if (existingIdx >= 0 && nextSorting.length === 1) {
-        if (nextSorting[0].direction === 'asc') {
-          nextSorting = [{ key, direction: 'desc' }];
-        } else {
-          nextSorting = [];
-        }
-      } else {
-        nextSorting = [{ key, direction: 'asc' }];
-      }
-    }
-
-    if (controlledSorting === undefined) {
-      setInternalSorting(nextSorting);
-    }
-    onSortingChange?.(nextSorting);
-  };
-
-  const handlePageChange = (newPage: number) => {
-    const clamped = Math.max(1, Math.min(totalPages, newPage));
-    if (controlledPageIndex === undefined) {
-      setInternalCurrentPage(clamped);
-    }
-    onPaginationChange?.(clamped, pageSize);
-  };
-
-  const handlePageSizeChange = (newSize: number) => {
-    setInternalPageSize(newSize);
-    if (controlledPageIndex === undefined) {
-      setInternalCurrentPage(1);
-    }
-    onPaginationChange?.(1, newSize);
-  };
-
-  const handleSearchChange = (query: string) => {
-    if (controlledSearchQuery === undefined) {
-      setInternalSearch(query);
-      if (controlledPageIndex === undefined) {
-        setInternalCurrentPage(1);
-      }
-    }
-    onSearchChange?.(query);
-  };
-
-  // Cross-page selection logic
-  const currentPageKeys = useMemo(() => paginatedData.map(keyExtractor), [paginatedData, keyExtractor]);
-  const isAllCurrentPageSelected =
-    currentPageKeys.length > 0 && currentPageKeys.every((k) => selectedKeys.includes(k));
-  const isSomeCurrentPageSelected =
-    currentPageKeys.some((k) => selectedKeys.includes(k)) && !isAllCurrentPageSelected;
-
-  const toggleSelectAllCurrentPage = () => {
-    if (isAllCurrentPageSelected) {
-      const next = selectedKeys.filter((k) => !currentPageKeys.includes(k));
-      handleSelectionUpdate(next);
-    } else {
-      const combined = Array.from(new Set([...selectedKeys, ...currentPageKeys]));
-      handleSelectionUpdate(combined);
-    }
-  };
-
-  const toggleSelectRow = (key: string) => {
-    const next = selectedKeys.includes(key)
-      ? selectedKeys.filter((k) => k !== key)
-      : [...selectedKeys, key];
-    handleSelectionUpdate(next);
-  };
-
-  const canSelectAllDataset = !manualPagination || typeof onSelectAllDataset === 'function';
-
-  const selectAllDataset = () => {
-    if (manualPagination) {
-      onSelectAllDataset?.();
-      return;
-    }
-    const allKeys = sortedData.map(keyExtractor);
-    handleSelectionUpdate(allKeys);
-  };
-
-  const clearSelection = () => {
-    handleSelectionUpdate([]);
-  };
-
-  const exportCSV = () => {
-    const exportRows = manualPagination ? data : sortedData;
-    const headers = columns.map((c) => (typeof c.header === 'string' ? c.header : c.key));
-    const rows = exportRows.map((row) =>
-      columns.map((c) => {
-        const val = c.accessor ? c.accessor(row) : row[c.key];
-        return `"${String(val ?? '').replace(/"/g, '""')}"`;
-      }).join(',')
-    );
-    const csvContent = 'data:text/csv;charset=utf-8,' + [headers.join(','), ...rows].join('\n');
-    const encodedUri = encodeURI(csvContent);
-    const link = document.createElement('a');
-    link.setAttribute('href', encodedUri);
-    link.setAttribute('download', `export_${Date.now()}.csv`);
-    document.body.appendChild(link);
-    link.click();
-    document.body.removeChild(link);
-  };
-
-  return (
-    <div className={cn('w-full space-y-4', className)}>
-      {/* Header Toolbar */}
-      <div className="flex flex-col sm:flex-row sm:items-center justify-between gap-4">
-        {(title || description) && (
-          <div>
-            {title && <h3 className="text-base font-bold tracking-tight text-[var(--ui-text-primary)]">{title}</h3>}
-            {description && <p className="text-xs text-[var(--ui-text-muted)]">{description}</p>}
-          </div>
-        )}
-
-        <div className="flex flex-wrap items-center gap-2.5">
-          {searchable && (
-            <div className="relative w-full sm:w-64">
-              <Search className="absolute left-3 w-3.5 h-3.5 text-[var(--ui-text-muted)] pointer-events-none" />
-              <input
-                type="text"
-                placeholder={searchPlaceholder}
-                value={search}
-                onChange={(e) => handleSearchChange(e.target.value)}
-                className="w-full h-8 pl-8 pr-3 text-xs rounded-xl bg-[var(--ui-bg-surface)] border border-[var(--ui-border-default)] hover:border-[var(--ui-border-strong)] focus:outline-none focus:ring-2 focus:ring-[var(--ui-primary)]/40 text-[var(--ui-text-primary)] placeholder:text-[var(--ui-text-muted)] transition-all shadow-inner"
-              />
-            </div>
-          )}
-
-          <Button size="xs" variant="outline" leftIcon={<Download className="w-3 h-3" />} onClick={exportCSV}>
-            Export CSV
-          </Button>
-
-          {actions}
-        </div>
-      </div>
-
-      {/* Bulk selection banner */}
-      {selectedKeys.length > 0 && (
-        <div className="px-4 py-2 rounded-xl bg-[var(--ui-primary)]/15 border border-[var(--ui-primary)]/30 flex flex-wrap items-center justify-between gap-2 animate-in fade-in duration-200">
-          <div className="flex items-center gap-2 text-xs font-semibold text-[var(--ui-primary)]">
-            <span>Selected {selectedKeys.length} records</span>
-            {canSelectAllDataset && selectedKeys.length < totalItems && (
-              <button
-                type="button"
-                onClick={selectAllDataset}
-                className="underline hover:text-[var(--ui-primary)]/80 cursor-pointer font-bold ml-1"
-              >
-                Select all {totalItems} records
-              </button>
-            )}
-          </div>
-          <Button
-            size="xs"
-            variant="ghost"
-            className="text-xs text-rose-500 hover:text-rose-600 hover:bg-rose-500/10"
-            onClick={clearSelection}
-          >
-            Clear Selection
-          </Button>
-        </div>
-      )}
-
-      {/* Table Container */}
-      <div className="relative w-full overflow-x-auto rounded-2xl border border-[var(--ui-border-default)] bg-[var(--ui-bg-surface)] shadow-sm">
-        {loading && (
-          <div className="absolute inset-0 z-20 bg-[var(--ui-bg-surface)]/60 backdrop-blur-xs flex items-center justify-center">
-            <Loader2 className="w-6 h-6 animate-spin text-[var(--ui-primary)]" />
-          </div>
-        )}
-
-        <Table>
-          <TableHeader>
-            <TableRow>
-              {selectable && (
-                <TableHead className="w-10 px-4">
-                  <Checkbox
-                    checked={isAllCurrentPageSelected}
-                    indeterminate={isSomeCurrentPageSelected}
-                    onCheckedChange={toggleSelectAllCurrentPage}
-                    aria-label="Select all on page"
-                  />
-                </TableHead>
-              )}
-
-              {columns.map((col) => {
-                const sortIndex = currentSorting.findIndex((s) => s.key === col.key);
-                const sortRule = sortIndex >= 0 ? currentSorting[sortIndex] : null;
-
-                return (
-                  <TableHead
-                    key={col.key}
-                    style={{ width: col.width }}
-                    onClick={(e) => col.sortable !== false && handleSort(col.key, e)}
-                    className={cn(
-                      col.sortable !== false &&
-                        'cursor-pointer select-none hover:text-[var(--ui-text-primary)] transition-colors'
-                    )}
-                  >
-                    <div className="flex items-center gap-1.5">
-                      <span>{col.header}</span>
-                      {col.sortable !== false && (
-                        <div className="flex items-center gap-0.5 text-[var(--ui-text-muted)]">
-                          {sortRule ? (
-                            sortRule.direction === 'asc' ? (
-                              <ChevronUp className="w-3.5 h-3.5 text-[var(--ui-primary)] font-bold" />
-                            ) : (
-                              <ChevronDown className="w-3.5 h-3.5 text-[var(--ui-primary)] font-bold" />
-                            )
-                          ) : (
-                            <ChevronsUpDown className="w-3 h-3 opacity-40" />
-                          )}
-                          {currentSorting.length > 1 && sortIndex >= 0 && (
-                            <span className="text-[10px] font-mono font-bold text-[var(--ui-primary)]">
-                              {sortIndex + 1}
-                            </span>
-                          )}
-                        </div>
-                      )}
-                    </div>
-                  </TableHead>
-                );
-              })}
-            </TableRow>
-          </TableHeader>
-
-          <TableBody>
-            {paginatedData.length === 0 ? (
-              <TableRow>
-                <TableCell
-                  colSpan={columns.length + (selectable ? 1 : 0)}
-                  className="h-32 text-center text-xs text-[var(--ui-text-muted)]"
-                >
-                  {emptyText}
-                </TableCell>
-              </TableRow>
-            ) : (
-              paginatedData.map((row, rowIdx) => {
-                const key = keyExtractor(row);
-                const isSelected = selectedKeys.includes(key);
-
-                return (
-                  <TableRow
-                    key={key}
-                    data-state={isSelected ? 'selected' : undefined}
-                    className={cn(isSelected && 'bg-[var(--ui-primary)]/10')}
-                  >
-                    {selectable && (
-                      <TableCell className="w-10 px-4">
-                        <Checkbox
-                          checked={isSelected}
-                          onCheckedChange={() => toggleSelectRow(key)}
-                          aria-label={`Select row ${key}`}
-                        />
-                      </TableCell>
-                    )}
-
-                    {columns.map((col) => {
-                      const val = col.accessor ? col.accessor(row) : row[col.key];
-                      const cellContent = col.render ? col.render(row, rowIdx, val) : val;
-
-                      return <TableCell key={col.key}>{cellContent}</TableCell>;
-                    })}
-                  </TableRow>
-                );
-              })
-            )}
-          </TableBody>
-        </Table>
-      </div>
-
-      {/* Pagination Footer */}
-      <div className="flex flex-col sm:flex-row sm:items-center justify-between gap-3 px-1 text-xs text-[var(--ui-text-muted)] font-mono">
-        <div className="flex items-center gap-2">
-          <span>Rows per page:</span>
-          <select
-            value={pageSize}
-            onChange={(e) => handlePageSizeChange(Number(e.target.value))}
-            className="px-2 py-1 rounded-lg bg-[var(--ui-bg-surface)] border border-[var(--ui-border-default)] text-[var(--ui-text-primary)] font-mono text-xs focus:outline-none"
-          >
-            {pageSizeOptions.map((opt) => (
-              <option key={opt} value={opt}>
-                {opt}
-              </option>
-            ))}
-          </select>
-          <span className="text-[var(--ui-text-muted)]">
-            Showing {totalItems === 0 ? 0 : Math.min((currentPage - 1) * pageSize + 1, totalItems)}–
-            {Math.min(currentPage * pageSize, totalItems)} of {totalItems}
-          </span>
-        </div>
-
-        <div className="flex items-center gap-1.5">
-          <Button
-            size="xs"
-            variant="outline"
-            disabled={currentPage <= 1 || loading}
-            onClick={() => handlePageChange(currentPage - 1)}
-            aria-label="Previous page"
-          >
-            <ChevronLeft className="w-3.5 h-3.5" />
-          </Button>
-
-          <span className="px-2 font-bold text-[var(--ui-text-primary)]">
-            {currentPage} / {totalPages}
-          </span>
-
-          <Button
-            size="xs"
-            variant="outline"
-            disabled={currentPage >= totalPages || loading}
-            onClick={() => handlePageChange(currentPage + 1)}
-            aria-label="Next page"
-          >
-            <ChevronRight className="w-3.5 h-3.5" />
-          </Button>
-        </div>
-      </div>
-    </div>
-  );
-}
+import React, { useState, useMemo, forwardRef, useEffect, useRef } from 'react';
+import {
+  ChevronUp,
+  ChevronDown,
+  ChevronsUpDown,
+  Search,
+  Download,
+  Trash2,
+  ChevronLeft,
+  ChevronRight,
+  Filter,
+  Loader2,
+} from 'lucide-react';
+import { cn } from '../utils/cn';
+import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from './Table';
+import { Button } from '../buttons/Button';
+import { Checkbox } from '../forms/Checkbox';
+
+export interface SortRule {
+  key: string;
+  direction: 'asc' | 'desc';
+}
+
+export interface ColumnDef<TData, TValue = any> {
+  key: string;
+  header: string | React.ReactNode;
+  accessor?: (row: TData) => TValue;
+  render?: (row: TData, index: number, value: TValue) => React.ReactNode;
+  sortable?: boolean;
+  sortComparator?: (a: TData, b: TData) => number;
+  width?: string;
+}
+
+export interface DataTableProProps<TData extends Record<string, any>> {
+  data: TData[];
+  columns: ColumnDef<TData>[];
+  keyExtractor: (row: TData) => string;
+  searchable?: boolean;
+  searchPlaceholder?: string;
+  selectable?: boolean;
+  selectedKeys?: string[];
+  defaultSelectedKeys?: string[];
+  onSelectionChange?: (selectedKeys: string[]) => void;
+  pageSize?: number;
+  pageSizeOptions?: number[];
+  title?: string;
+  description?: string;
+  actions?: React.ReactNode;
+  className?: string;
+  loading?: boolean;
+
+  // Sorting
+  multiSort?: boolean;
+  sorting?: SortRule[] | null;
+  defaultSorting?: SortRule[];
+  onSortingChange?: (sorting: SortRule[]) => void;
+
+  // Server-side / Manual controls
+  manualPagination?: boolean;
+  manualSorting?: boolean;
+  manualFiltering?: boolean;
+  pageIndex?: number;
+  pageCount?: number;
+  totalCount?: number;
+  onPaginationChange?: (page: number, pageSize: number) => void;
+  searchQuery?: string;
+  onSearchChange?: (query: string) => void;
+  onSelectAllDataset?: () => void;
+  emptyText?: string;
+}
+
+export function DataTablePro<TData extends Record<string, any>>({
+  data,
+  columns,
+  keyExtractor,
+  searchable = true,
+  searchPlaceholder = 'Search all records...',
+  selectable = true,
+  selectedKeys: controlledSelectedKeys,
+  defaultSelectedKeys = [],
+  onSelectionChange,
+  pageSize: initialPageSize = 10,
+  pageSizeOptions = [5, 10, 25, 50],
+  title,
+  description,
+  actions,
+  className,
+  loading = false,
+
+  // Multi-column sorting
+  multiSort = true,
+  sorting: controlledSorting,
+  defaultSorting = [],
+  onSortingChange,
+
+  // Server-side / manual mode props
+  manualPagination = false,
+  manualSorting = false,
+  manualFiltering = false,
+  pageIndex: controlledPageIndex,
+  pageCount: controlledPageCount,
+  totalCount: controlledTotalCount,
+  onPaginationChange,
+  searchQuery: controlledSearchQuery,
+  onSearchChange,
+  onSelectAllDataset,
+  emptyText = 'No matching records found.',
+}: DataTableProProps<TData>) {
+  // 1. Search state
+  const [internalSearch, setInternalSearch] = useState('');
+  const search = controlledSearchQuery !== undefined ? controlledSearchQuery : internalSearch;
+
+  // 2. Multi-column sorting state
+  const [internalSorting, setInternalSorting] = useState<SortRule[]>(defaultSorting);
+  const currentSorting = controlledSorting !== undefined ? controlledSorting ?? [] : internalSorting;
+
+  // 3. Pagination state
+  const [internalCurrentPage, setInternalCurrentPage] = useState(1);
+  const currentPage = controlledPageIndex !== undefined ? controlledPageIndex : internalCurrentPage;
+
+  const [internalPageSize, setInternalPageSize] = useState(initialPageSize);
+  const pageSize = internalPageSize;
+
+  // 4. Selection state
+  const [internalSelectedKeys, setInternalSelectedKeys] = useState<string[]>(defaultSelectedKeys);
+  const isSelectedControlled = controlledSelectedKeys !== undefined;
+  const selectedKeys = isSelectedControlled ? controlledSelectedKeys : internalSelectedKeys;
+
+  const handleSelectionUpdate = (nextKeys: string[]) => {
+    if (!isSelectedControlled) {
+      setInternalSelectedKeys(nextKeys);
+    }
+    onSelectionChange?.(nextKeys);
+  };
+
+  // Search filtering (Client-side when not manual)
+  const filteredData = useMemo(() => {
+    if (manualFiltering || !search.trim()) return data;
+    const q = search.toLowerCase();
+
+    return data.filter((row) => {
+      return columns.some((col) => {
+        const val = col.accessor ? col.accessor(row) : row[col.key];
+        if (val === null || val === undefined) return false;
+        return String(val).toLowerCase().includes(q);
+      });
+    });
+  }, [data, search, columns, manualFiltering]);
+
+  // True Multi-Column Sorting (Client-side when not manual)
+  const sortedData = useMemo(() => {
+    if (manualSorting || currentSorting.length === 0) return filteredData;
+
+    return [...filteredData].sort((a, b) => {
+      for (const { key, direction } of currentSorting) {
+        const col = columns.find((c) => c.key === key);
+        let comp = 0;
+
+        if (col?.sortComparator) {
+          comp = col.sortComparator(a, b);
+        } else {
+          const valA = col?.accessor ? col.accessor(a) : a[key];
+          const valB = col?.accessor ? col.accessor(b) : b[key];
+
+          if (valA === valB) continue;
+          if (valA === null || valA === undefined) return 1;
+          if (valB === null || valB === undefined) return -1;
+
+          comp = valA < valB ? -1 : 1;
+        }
+
+        if (comp !== 0) {
+          return direction === 'asc' ? comp : -comp;
+        }
+      }
+      return 0;
+    });
+  }, [filteredData, currentSorting, columns, manualSorting]);
+
+  // Pagination calculations
+  const totalItems = controlledTotalCount !== undefined ? controlledTotalCount : sortedData.length;
+  const totalPages = controlledPageCount !== undefined
+    ? Math.max(1, controlledPageCount)
+    : Math.max(1, Math.ceil(totalItems / pageSize));
+
+  // Reset/clamp page if out of range on client-side filter
+  useEffect(() => {
+    if (!manualPagination && currentPage > totalPages && totalPages > 0) {
+      setInternalCurrentPage(totalPages);
+      onPaginationChange?.(totalPages, pageSize);
+    }
+  }, [totalPages, currentPage, manualPagination, pageSize, onPaginationChange]);
+
+  const paginatedData = useMemo(() => {
+    if (manualPagination) return data;
+    const start = (currentPage - 1) * pageSize;
+    return sortedData.slice(start, start + pageSize);
+  }, [data, sortedData, currentPage, pageSize, manualPagination]);
+
+  // Sorting handler supporting Shift+Click for multi-sort
+  const handleSort = (key: string, e?: React.MouseEvent) => {
+    const isShift = e?.shiftKey || false;
+    let nextSorting: SortRule[] = [...currentSorting];
+    const existingIdx = nextSorting.findIndex((s) => s.key === key);
+
+    if (isShift && multiSort) {
+      if (existingIdx >= 0) {
+        if (nextSorting[existingIdx].direction === 'asc') {
+          nextSorting[existingIdx] = { key, direction: 'desc' };
+        } else {
+          nextSorting.splice(existingIdx, 1);
+        }
+      } else {
+        nextSorting.push({ key, direction: 'asc' });
+      }
+    } else {
+      if (existingIdx >= 0 && nextSorting.length === 1) {
+        if (nextSorting[0].direction === 'asc') {
+          nextSorting = [{ key, direction: 'desc' }];
+        } else {
+          nextSorting = [];
+        }
+      } else {
+        nextSorting = [{ key, direction: 'asc' }];
+      }
+    }
+
+    if (controlledSorting === undefined) {
+      setInternalSorting(nextSorting);
+    }
+    onSortingChange?.(nextSorting);
+  };
+
+  const handlePageChange = (newPage: number) => {
+    const clamped = Math.max(1, Math.min(totalPages, newPage));
+    if (controlledPageIndex === undefined) {
+      setInternalCurrentPage(clamped);
+    }
+    onPaginationChange?.(clamped, pageSize);
+  };
+
+  const handlePageSizeChange = (newSize: number) => {
+    setInternalPageSize(newSize);
+    if (controlledPageIndex === undefined) {
+      setInternalCurrentPage(1);
+    }
+    onPaginationChange?.(1, newSize);
+  };
+
+  const handleSearchChange = (query: string) => {
+    if (controlledSearchQuery === undefined) {
+      setInternalSearch(query);
+      if (controlledPageIndex === undefined) {
+        setInternalCurrentPage(1);
+      }
+    }
+    onSearchChange?.(query);
+  };
+
+  // Cross-page selection logic
+  const currentPageKeys = useMemo(() => paginatedData.map(keyExtractor), [paginatedData, keyExtractor]);
+  const isAllCurrentPageSelected =
+    currentPageKeys.length > 0 && currentPageKeys.every((k) => selectedKeys.includes(k));
+  const isSomeCurrentPageSelected =
+    currentPageKeys.some((k) => selectedKeys.includes(k)) && !isAllCurrentPageSelected;
+
+  const toggleSelectAllCurrentPage = () => {
+    if (isAllCurrentPageSelected) {
+      const next = selectedKeys.filter((k) => !currentPageKeys.includes(k));
+      handleSelectionUpdate(next);
+    } else {
+      const combined = Array.from(new Set([...selectedKeys, ...currentPageKeys]));
+      handleSelectionUpdate(combined);
+    }
+  };
+
+  const toggleSelectRow = (key: string) => {
+    const next = selectedKeys.includes(key)
+      ? selectedKeys.filter((k) => k !== key)
+      : [...selectedKeys, key];
+    handleSelectionUpdate(next);
+  };
+
+  const canSelectAllDataset = !manualPagination || typeof onSelectAllDataset === 'function';
+
+  const selectAllDataset = () => {
+    if (manualPagination) {
+      onSelectAllDataset?.();
+      return;
+    }
+    const allKeys = sortedData.map(keyExtractor);
+    handleSelectionUpdate(allKeys);
+  };
+
+  const clearSelection = () => {
+    handleSelectionUpdate([]);
+  };
+
+  const exportCSV = () => {
+    const exportRows = manualPagination ? data : sortedData;
+    const headers = columns.map((c) => (typeof c.header === 'string' ? c.header : c.key));
+    const rows = exportRows.map((row) =>
+      columns.map((c) => {
+        const val = c.accessor ? c.accessor(row) : row[c.key];
+        return `"${String(val ?? '').replace(/"/g, '""')}"`;
+      }).join(',')
+    );
+    const csvContent = 'data:text/csv;charset=utf-8,' + [headers.join(','), ...rows].join('\n');
+    const encodedUri = encodeURI(csvContent);
+    const link = document.createElement('a');
+    link.setAttribute('href', encodedUri);
+    link.setAttribute('download', `export_${Date.now()}.csv`);
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+  };
+
+  return (
+    <div className={cn('w-full space-y-4', className)}>
+      {/* Header Toolbar */}
+      <div className="flex flex-col sm:flex-row sm:items-center justify-between gap-4">
+        {(title || description) && (
+          <div>
+            {title && <h3 className="text-base font-bold tracking-tight text-[var(--ui-text-primary)]">{title}</h3>}
+            {description && <p className="text-xs text-[var(--ui-text-muted)]">{description}</p>}
+          </div>
+        )}
+
+        <div className="flex flex-wrap items-center gap-2.5">
+          {searchable && (
+            <div className="relative w-full sm:w-64">
+              <Search className="absolute left-3 w-3.5 h-3.5 text-[var(--ui-text-muted)] pointer-events-none" />
+              <input
+                type="text"
+                placeholder={searchPlaceholder}
+                value={search}
+                onChange={(e) => handleSearchChange(e.target.value)}
+                className="w-full h-8 pl-8 pr-3 text-xs rounded-xl bg-[var(--ui-bg-surface)] border border-[var(--ui-border-default)] hover:border-[var(--ui-border-strong)] focus:outline-none focus:ring-2 focus:ring-[var(--ui-primary)]/40 text-[var(--ui-text-primary)] placeholder:text-[var(--ui-text-muted)] transition-all shadow-inner"
+              />
+            </div>
+          )}
+
+          <Button size="xs" variant="outline" leftIcon={<Download className="w-3 h-3" />} onClick={exportCSV}>
+            Export CSV
+          </Button>
+
+          {actions}
+        </div>
+      </div>
+
+      {/* Bulk selection banner */}
+      {selectedKeys.length > 0 && (
+        <div className="px-4 py-2 rounded-xl bg-[var(--ui-primary)]/15 border border-[var(--ui-primary)]/30 flex flex-wrap items-center justify-between gap-2 animate-in fade-in duration-200">
+          <div className="flex items-center gap-2 text-xs font-semibold text-[var(--ui-primary)]">
+            <span>Selected {selectedKeys.length} records</span>
+            {canSelectAllDataset && selectedKeys.length < totalItems && (
+              <button
+                type="button"
+                onClick={selectAllDataset}
+                className="underline hover:text-[var(--ui-primary)]/80 cursor-pointer font-bold ml-1"
+              >
+                Select all {totalItems} records
+              </button>
+            )}
+          </div>
+          <Button
+            size="xs"
+            variant="ghost"
+            className="text-xs text-rose-500 hover:text-rose-600 hover:bg-rose-500/10"
+            onClick={clearSelection}
+          >
+            Clear Selection
+          </Button>
+        </div>
+      )}
+
+      {/* Table Container */}
+      <div className="relative w-full overflow-x-auto rounded-2xl border border-[var(--ui-border-default)] bg-[var(--ui-bg-surface)] shadow-sm">
+        {loading && (
+          <div className="absolute inset-0 z-20 bg-[var(--ui-bg-surface)]/60 backdrop-blur-xs flex items-center justify-center">
+            <Loader2 className="w-6 h-6 animate-spin text-[var(--ui-primary)]" />
+          </div>
+        )}
+
+        <Table>
+          <TableHeader>
+            <TableRow>
+              {selectable && (
+                <TableHead className="w-10 px-4">
+                  <Checkbox
+                    checked={isAllCurrentPageSelected}
+                    indeterminate={isSomeCurrentPageSelected}
+                    onCheckedChange={toggleSelectAllCurrentPage}
+                    aria-label="Select all on page"
+                  />
+                </TableHead>
+              )}
+
+              {columns.map((col) => {
+                const sortIndex = currentSorting.findIndex((s) => s.key === col.key);
+                const sortRule = sortIndex >= 0 ? currentSorting[sortIndex] : null;
+
+                return (
+                  <TableHead
+                    key={col.key}
+                    style={{ width: col.width }}
+                    onClick={(e) => col.sortable !== false && handleSort(col.key, e)}
+                    className={cn(
+                      col.sortable !== false &&
+                        'cursor-pointer select-none hover:text-[var(--ui-text-primary)] transition-colors'
+                    )}
+                  >
+                    <div className="flex items-center gap-1.5">
+                      <span>{col.header}</span>
+                      {col.sortable !== false && (
+                        <div className="flex items-center gap-0.5 text-[var(--ui-text-muted)]">
+                          {sortRule ? (
+                            sortRule.direction === 'asc' ? (
+                              <ChevronUp className="w-3.5 h-3.5 text-[var(--ui-primary)] font-bold" />
+                            ) : (
+                              <ChevronDown className="w-3.5 h-3.5 text-[var(--ui-primary)] font-bold" />
+                            )
+                          ) : (
+                            <ChevronsUpDown className="w-3 h-3 opacity-40" />
+                          )}
+                          {currentSorting.length > 1 && sortIndex >= 0 && (
+                            <span className="text-[10px] font-mono font-bold text-[var(--ui-primary)]">
+                              {sortIndex + 1}
+                            </span>
+                          )}
+                        </div>
+                      )}
+                    </div>
+                  </TableHead>
+                );
+              })}
+            </TableRow>
+          </TableHeader>
+
+          <TableBody>
+            {paginatedData.length === 0 ? (
+              <TableRow>
+                <TableCell
+                  colSpan={columns.length + (selectable ? 1 : 0)}
+                  className="h-32 text-center text-xs text-[var(--ui-text-muted)]"
+                >
+                  {emptyText}
+                </TableCell>
+              </TableRow>
+            ) : (
+              paginatedData.map((row, rowIdx) => {
+                const key = keyExtractor(row);
+                const isSelected = selectedKeys.includes(key);
+
+                return (
+                  <TableRow
+                    key={key}
+                    data-state={isSelected ? 'selected' : undefined}
+                    className={cn(isSelected && 'bg-[var(--ui-primary)]/10')}
+                  >
+                    {selectable && (
+                      <TableCell className="w-10 px-4">
+                        <Checkbox
+                          checked={isSelected}
+                          onCheckedChange={() => toggleSelectRow(key)}
+                          aria-label={`Select row ${key}`}
+                        />
+                      </TableCell>
+                    )}
+
+                    {columns.map((col) => {
+                      const val = col.accessor ? col.accessor(row) : row[col.key];
+                      const cellContent = col.render ? col.render(row, rowIdx, val) : val;
+
+                      return <TableCell key={col.key}>{cellContent}</TableCell>;
+                    })}
+                  </TableRow>
+                );
+              })
+            )}
+          </TableBody>
+        </Table>
+      </div>
+
+      {/* Pagination Footer */}
+      <div className="flex flex-col sm:flex-row sm:items-center justify-between gap-3 px-1 text-xs text-[var(--ui-text-muted)] font-mono">
+        <div className="flex items-center gap-2">
+          <span>Rows per page:</span>
+          <select
+            value={pageSize}
+            onChange={(e) => handlePageSizeChange(Number(e.target.value))}
+            className="px-2 py-1 rounded-lg bg-[var(--ui-bg-surface)] border border-[var(--ui-border-default)] text-[var(--ui-text-primary)] font-mono text-xs focus:outline-none"
+          >
+            {pageSizeOptions.map((opt) => (
+              <option key={opt} value={opt}>
+                {opt}
+              </option>
+            ))}
+          </select>
+          <span className="text-[var(--ui-text-muted)]">
+            Showing {totalItems === 0 ? 0 : Math.min((currentPage - 1) * pageSize + 1, totalItems)}–
+            {Math.min(currentPage * pageSize, totalItems)} of {totalItems}
+          </span>
+        </div>
+
+        <div className="flex items-center gap-1.5">
+          <Button
+            size="xs"
+            variant="outline"
+            disabled={currentPage <= 1 || loading}
+            onClick={() => handlePageChange(currentPage - 1)}
+            aria-label="Previous page"
+          >
+            <ChevronLeft className="w-3.5 h-3.5" />
+          </Button>
+
+          <span className="px-2 font-bold text-[var(--ui-text-primary)]">
+            {currentPage} / {totalPages}
+          </span>
+
+          <Button
+            size="xs"
+            variant="outline"
+            disabled={currentPage >= totalPages || loading}
+            onClick={() => handlePageChange(currentPage + 1)}
+            aria-label="Next page"
+          >
+            <ChevronRight className="w-3.5 h-3.5" />
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}