@optilogic/core 1.0.0-beta.1 → 1.0.0-beta.11

package/src/components/data-table.tsx

@@ -0,0 +1,735 @@
+/**
+ * DataTable Component
+ *
+ * A data-driven table that sits between the simple Table primitives and the
+ * full DataGrid. Supports opt-in sorting, search, pagination, row selection,
+ * and pinned rows -- all composed from existing core primitives.
+ */
+
+import * as React from "react";
+import {
+  ArrowUp,
+  ArrowDown,
+  ArrowUpDown,
+  Search,
+  ChevronsLeft,
+  ChevronLeft,
+  ChevronRight,
+  ChevronsRight,
+} from "lucide-react";
+
+import { cn } from "../utils/cn";
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption,
+} from "./table";
+import { Button } from "./button";
+import { Input } from "./input";
+import { Checkbox } from "./checkbox";
+import {
+  Select,
+  SelectTrigger,
+  SelectContent,
+  SelectItem,
+  SelectValue,
+} from "./select";
+import { LoadingSpinner } from "./loading-spinner";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Column definition for the DataTable.
+ */
+export interface DataTableColumn<T> {
+  /** Unique key identifying this column */
+  key: string;
+  /** Header label (string or ReactNode) */
+  header: string | React.ReactNode;
+  /**
+   * Custom cell renderer. When omitted the table renders
+   * `String(accessor(row))` or `String(row[key])`.
+   */
+  cell?: (row: T, rowIndex: number) => React.ReactNode;
+  /** Accessor function to pull the raw value from a row (used for sorting & default rendering) */
+  accessor?: (row: T) => string | number | boolean | null | undefined;
+  /** Whether this column is sortable (default false) */
+  sortable?: boolean;
+  /** Custom sort comparator. Receives two rows, return negative / 0 / positive. */
+  sortFn?: (a: T, b: T) => number;
+  /** Text alignment */
+  align?: "left" | "center" | "right";
+  /** Extra class name applied to every `<td>` in this column */
+  className?: string;
+  /** Extra class name applied to the `<th>` for this column */
+  headerClassName?: string;
+  /** Tailwind width class or inline width, e.g. "w-[100px]" */
+  width?: string;
+}
+
+/** Sort descriptor */
+export interface DataTableSort {
+  /** Column key */
+  key: string;
+  /** Direction */
+  direction: "asc" | "desc";
+}
+
+/**
+ * Props for the DataTable component.
+ */
+export interface DataTableProps<T> {
+  // ── Data ─────────────────────────────────────────────────────────────────
+  /** Array of row data */
+  data: T[];
+  /** Column definitions */
+  columns: DataTableColumn<T>[];
+  /** Return a stable unique key for each row */
+  getRowKey: (row: T, index: number) => string;
+
+  // ── Sorting ──────────────────────────────────────────────────────────────
+  /** Default sort (uncontrolled) */
+  defaultSort?: DataTableSort;
+  /** Controlled sort */
+  sort?: DataTableSort | null;
+  /** Called when sort changes (controlled) */
+  onSortChange?: (sort: DataTableSort | null) => void;
+
+  // ── Search ───────────────────────────────────────────────────────────────
+  /**
+   * Enable the search bar. Pass `true` for defaults or a config object.
+   * Search is always controlled by the consumer via `searchValue` /
+   * `onSearchChange`, or managed internally when omitted.
+   */
+  searchable?: boolean;
+  /** Placeholder text for the search input */
+  searchPlaceholder?: string;
+  /** Controlled search value */
+  searchValue?: string;
+  /** Called when the search value changes */
+  onSearchChange?: (value: string) => void;
+  /** Custom search predicate. When omitted, a case-insensitive substring
+   *  match across all columns (using accessor / row[key]) is used. */
+  searchFn?: (row: T, query: string) => boolean;
+
+  // ── Pagination ───────────────────────────────────────────────────────────
+  /** Pass a number to enable pagination with that default page size */
+  pageSize?: number;
+  /** Options shown in the rows-per-page selector */
+  pageSizeOptions?: number[];
+  /** Controlled current page (0-indexed) */
+  currentPage?: number;
+  /** Called when page changes */
+  onPageChange?: (page: number) => void;
+  /** Called when page size changes */
+  onPageSizeChange?: (size: number) => void;
+
+  // ── Selection ────────────────────────────────────────────────────────────
+  /** Enable selection mode: "checkbox" adds a checkbox column, "highlight" selects on row click */
+  selectable?: "checkbox" | "highlight";
+  /** Currently selected row keys */
+  selectedRows?: string[];
+  /** Called when selection changes */
+  onSelectedRowsChange?: (keys: string[]) => void;
+
+  // ── Row interactions ─────────────────────────────────────────────────────
+  /** Called when a row is clicked (independent of selection) */
+  onRowClick?: (row: T, index: number) => void;
+  /** Dynamic row class name */
+  rowClassName?: (row: T, index: number) => string;
+
+  // ── Pinned rows ──────────────────────────────────────────────────────────
+  /** Row keys that should be pinned to the top */
+  pinnedRows?: string[];
+
+  // ── Slots ────────────────────────────────────────────────────────────────
+  /** Custom toolbar rendered between search bar and table */
+  toolbar?: React.ReactNode;
+  /** Custom empty state */
+  emptyState?: React.ReactNode;
+  /** Table caption */
+  caption?: string;
+
+  // ── Loading ──────────────────────────────────────────────────────────────
+  /** Show loading state */
+  loading?: boolean;
+
+  // ── Styling ──────────────────────────────────────────────────────────────
+  /** Class name for the outermost wrapper */
+  className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getCellRawValue<T>(row: T, col: DataTableColumn<T>): string | number | boolean | null | undefined {
+  if (col.accessor) return col.accessor(row);
+  return (row as Record<string, unknown>)[col.key] as string | number | boolean | null | undefined;
+}
+
+function defaultSearch<T>(row: T, query: string, columns: DataTableColumn<T>[]): boolean {
+  const lowerQuery = query.toLowerCase();
+  return columns.some((col) => {
+    const val = getCellRawValue(row, col);
+    if (val == null) return false;
+    return String(val).toLowerCase().includes(lowerQuery);
+  });
+}
+
+function defaultSortComparator<T>(
+  a: T,
+  b: T,
+  col: DataTableColumn<T>,
+  direction: "asc" | "desc",
+): number {
+  if (col.sortFn) {
+    const result = col.sortFn(a, b);
+    return direction === "asc" ? result : -result;
+  }
+  const aVal = getCellRawValue(a, col);
+  const bVal = getCellRawValue(b, col);
+  const aStr = aVal == null ? "" : String(aVal);
+  const bStr = bVal == null ? "" : String(bVal);
+
+  // Try numeric comparison first
+  const aNum = Number(aStr);
+  const bNum = Number(bStr);
+  if (!isNaN(aNum) && !isNaN(bNum) && aStr !== "" && bStr !== "") {
+    return direction === "asc" ? aNum - bNum : bNum - aNum;
+  }
+
+  const cmp = aStr.localeCompare(bStr);
+  return direction === "asc" ? cmp : -cmp;
+}
+
+// ---------------------------------------------------------------------------
+// DataTable
+// ---------------------------------------------------------------------------
+
+export function DataTable<T>({
+  data,
+  columns,
+  getRowKey,
+
+  // Sorting
+  defaultSort,
+  sort: controlledSort,
+  onSortChange,
+
+  // Search
+  searchable = false,
+  searchPlaceholder = "Search...",
+  searchValue: controlledSearchValue,
+  onSearchChange,
+  searchFn,
+
+  // Pagination
+  pageSize: defaultPageSize,
+  pageSizeOptions = [10, 15, 25, 50, 100],
+  currentPage: controlledPage,
+  onPageChange,
+  onPageSizeChange,
+
+  // Selection
+  selectable,
+  selectedRows: controlledSelectedRows,
+  onSelectedRowsChange,
+
+  // Row interaction
+  onRowClick,
+  rowClassName,
+
+  // Pinned rows
+  pinnedRows = [],
+
+  // Slots
+  toolbar,
+  emptyState,
+  caption,
+
+  // Loading
+  loading = false,
+
+  // Styling
+  className,
+}: DataTableProps<T>) {
+  // ── Internal state (uncontrolled defaults) ───────────────────────────────
+
+  const [internalSort, setInternalSort] = React.useState<DataTableSort | null>(
+    defaultSort ?? null,
+  );
+  const [internalSearchValue, setInternalSearchValue] = React.useState("");
+  const [internalPage, setInternalPage] = React.useState(0);
+  const [internalPageSize, setInternalPageSize] = React.useState(
+    defaultPageSize ?? 10,
+  );
+  const [internalSelectedRows, setInternalSelectedRows] = React.useState<string[]>([]);
+
+  // Resolve controlled vs uncontrolled
+  const sort = controlledSort !== undefined ? controlledSort : internalSort;
+  const searchQuery =
+    controlledSearchValue !== undefined ? controlledSearchValue : internalSearchValue;
+  const page = controlledPage !== undefined ? controlledPage : internalPage;
+  const pageSize = defaultPageSize != null ? (internalPageSize ?? defaultPageSize) : undefined;
+  const selectedRowKeys =
+    controlledSelectedRows !== undefined ? controlledSelectedRows : internalSelectedRows;
+
+  const handleSortChange = React.useCallback(
+    (next: DataTableSort | null) => {
+      if (onSortChange) onSortChange(next);
+      else setInternalSort(next);
+    },
+    [onSortChange],
+  );
+
+  const handleSearchChange = React.useCallback(
+    (value: string) => {
+      if (onSearchChange) onSearchChange(value);
+      else setInternalSearchValue(value);
+      // Reset to first page on search
+      if (onPageChange) onPageChange(0);
+      else setInternalPage(0);
+    },
+    [onSearchChange, onPageChange],
+  );
+
+  const handlePageChange = React.useCallback(
+    (p: number) => {
+      if (onPageChange) onPageChange(p);
+      else setInternalPage(p);
+    },
+    [onPageChange],
+  );
+
+  const handlePageSizeChange = React.useCallback(
+    (size: number) => {
+      if (onPageSizeChange) onPageSizeChange(size);
+      else setInternalPageSize(size);
+      // Reset to first page
+      if (onPageChange) onPageChange(0);
+      else setInternalPage(0);
+    },
+    [onPageSizeChange, onPageChange],
+  );
+
+  const handleSelectionChange = React.useCallback(
+    (keys: string[]) => {
+      if (onSelectedRowsChange) onSelectedRowsChange(keys);
+      else setInternalSelectedRows(keys);
+    },
+    [onSelectedRowsChange],
+  );
+
+  // ── Header sort click ────────────────────────────────────────────────────
+
+  const handleHeaderClick = React.useCallback(
+    (colKey: string) => {
+      if (sort?.key === colKey) {
+        if (sort.direction === "asc") {
+          handleSortChange({ key: colKey, direction: "desc" });
+        } else {
+          handleSortChange(null);
+        }
+      } else {
+        handleSortChange({ key: colKey, direction: "asc" });
+      }
+    },
+    [sort, handleSortChange],
+  );
+
+  // ── Data pipeline: search → sort → split pinned / unpinned → paginate ──
+
+  // 1. Search
+  const searchedData = React.useMemo(() => {
+    if (!searchable || !searchQuery) return data;
+    if (searchFn) return data.filter((row) => searchFn(row, searchQuery));
+    return data.filter((row) => defaultSearch(row, searchQuery, columns));
+  }, [data, searchable, searchQuery, searchFn, columns]);
+
+  // 2. Sort
+  const sortedData = React.useMemo(() => {
+    if (!sort) return searchedData;
+    const col = columns.find((c) => c.key === sort.key);
+    if (!col) return searchedData;
+    return [...searchedData].sort((a, b) =>
+      defaultSortComparator(a, b, col, sort.direction),
+    );
+  }, [searchedData, sort, columns]);
+
+  // 3. Split pinned vs unpinned
+  const pinnedSet = React.useMemo(() => new Set(pinnedRows), [pinnedRows]);
+
+  const { pinnedData, unpinnedData } = React.useMemo(() => {
+    if (pinnedSet.size === 0) return { pinnedData: [] as T[], unpinnedData: sortedData };
+    const pinned: T[] = [];
+    const unpinned: T[] = [];
+    // Collect pinned rows from the full dataset in pinnedRows order
+    const dataByKey = new Map<string, T>();
+    data.forEach((row, i) => {
+      dataByKey.set(getRowKey(row, i), row);
+    });
+    pinnedRows.forEach((key) => {
+      const row = dataByKey.get(key);
+      if (row) pinned.push(row);
+    });
+    // Unpinned: from sorted/searched data, excluding pinned keys
+    sortedData.forEach((row, i) => {
+      const key = getRowKey(row, i);
+      // Need original index from data for stable keys
+      if (!pinnedSet.has(key)) unpinned.push(row);
+    });
+    return { pinnedData: pinned, unpinnedData: unpinned };
+  }, [sortedData, pinnedSet, pinnedRows, data, getRowKey]);
+
+  // 4. Pagination (applied to unpinned data only)
+  const totalUnpinned = unpinnedData.length;
+  const totalPages = pageSize ? Math.max(1, Math.ceil(totalUnpinned / pageSize)) : 1;
+  const paginatedData = React.useMemo(() => {
+    if (!pageSize) return unpinnedData;
+    const start = page * pageSize;
+    return unpinnedData.slice(start, start + pageSize);
+  }, [unpinnedData, pageSize, page]);
+
+  // All visible rows (pinned + current page of unpinned)
+  const visibleRows = React.useMemo(
+    () => [...pinnedData, ...paginatedData],
+    [pinnedData, paginatedData],
+  );
+
+  // Total items count (for display in pagination)
+  const totalItems = searchedData.length;
+
+  // ── Selection helpers ────────────────────────────────────────────────────
+
+  const visibleKeys = React.useMemo(
+    () => visibleRows.map((row, i) => getRowKey(row, i)),
+    [visibleRows, getRowKey],
+  );
+
+  const allVisibleSelected =
+    visibleKeys.length > 0 && visibleKeys.every((k) => selectedRowKeys.includes(k));
+  const someVisibleSelected =
+    !allVisibleSelected && visibleKeys.some((k) => selectedRowKeys.includes(k));
+
+  const toggleRowSelection = React.useCallback(
+    (key: string) => {
+      const isSelected = selectedRowKeys.includes(key);
+      const next = isSelected
+        ? selectedRowKeys.filter((k) => k !== key)
+        : [...selectedRowKeys, key];
+      handleSelectionChange(next);
+    },
+    [selectedRowKeys, handleSelectionChange],
+  );
+
+  const toggleAllVisible = React.useCallback(() => {
+    if (allVisibleSelected) {
+      // Deselect all visible
+      const visibleSet = new Set(visibleKeys);
+      handleSelectionChange(selectedRowKeys.filter((k) => !visibleSet.has(k)));
+    } else {
+      // Select all visible
+      const merged = new Set([...selectedRowKeys, ...visibleKeys]);
+      handleSelectionChange(Array.from(merged));
+    }
+  }, [allVisibleSelected, visibleKeys, selectedRowKeys, handleSelectionChange]);
+
+  // ── Row click handler ────────────────────────────────────────────────────
+
+  const handleRowClick = React.useCallback(
+    (row: T, index: number, key: string) => {
+      if (selectable === "highlight") {
+        toggleRowSelection(key);
+      }
+      onRowClick?.(row, index);
+    },
+    [selectable, toggleRowSelection, onRowClick],
+  );
+
+  // ── Render helpers ───────────────────────────────────────────────────────
+
+  const renderCellContent = (row: T, col: DataTableColumn<T>, rowIndex: number) => {
+    if (col.cell) return col.cell(row, rowIndex);
+    const val = getCellRawValue(row, col);
+    if (val == null) return <span className="text-muted-foreground italic">--</span>;
+    return String(val);
+  };
+
+  const alignClass = (align?: "left" | "center" | "right") => {
+    if (align === "center") return "text-center";
+    if (align === "right") return "text-right";
+    return "text-left";
+  };
+
+  // ── Loading state ────────────────────────────────────────────────────────
+
+  if (loading) {
+    return (
+      <div className={cn("flex items-center justify-center py-16", className)}>
+        <LoadingSpinner label="Loading" showDots />
+      </div>
+    );
+  }
+
+  // ── Render ───────────────────────────────────────────────────────────────
+
+  const showSearch = searchable;
+  const showPagination = pageSize != null;
+  const showCheckboxColumn = selectable === "checkbox";
+
+  return (
+    <div className={cn("flex flex-col w-full", className)}>
+      {/* Toolbar area: search + custom toolbar */}
+      {(showSearch || toolbar) && (
+        <div className="flex items-center gap-3 pb-4">
+          {showSearch && (
+            <div className="relative flex-1 max-w-sm">
+              <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+              <Input
+                type="text"
+                placeholder={searchPlaceholder}
+                value={searchQuery}
+                onChange={(e) => handleSearchChange(e.target.value)}
+                className="pl-9"
+              />
+            </div>
+          )}
+          {toolbar && <div className="flex items-center gap-2">{toolbar}</div>}
+        </div>
+      )}
+
+      {/* Table */}
+      <Table>
+        {caption && <TableCaption>{caption}</TableCaption>}
+
+        <TableHeader>
+          <TableRow>
+            {showCheckboxColumn && (
+              <TableHead className="w-[40px]">
+                <Checkbox
+                  checked={allVisibleSelected ? true : someVisibleSelected ? "indeterminate" : false}
+                  onCheckedChange={() => toggleAllVisible()}
+                  aria-label="Select all"
+                />
+              </TableHead>
+            )}
+            {columns.map((col) => {
+              const isSorted = sort?.key === col.key;
+              const sortDir = isSorted ? sort!.direction : null;
+
+              return (
+                <TableHead
+                  key={col.key}
+                  className={cn(
+                    col.width,
+                    col.headerClassName,
+                    alignClass(col.align),
+                    col.sortable && "cursor-pointer select-none",
+                  )}
+                  onClick={col.sortable ? () => handleHeaderClick(col.key) : undefined}
+                >
+                  <div
+                    className={cn(
+                      "flex items-center gap-1",
+                      col.align === "center" && "justify-center",
+                      col.align === "right" && "justify-end",
+                    )}
+                  >
+                    <span>{col.header}</span>
+                    {col.sortable && (
+                      <span className="inline-flex ml-1">
+                        {sortDir === "asc" ? (
+                          <ArrowUp className="h-3.5 w-3.5" />
+                        ) : sortDir === "desc" ? (
+                          <ArrowDown className="h-3.5 w-3.5" />
+                        ) : (
+                          <ArrowUpDown className="h-3.5 w-3.5 opacity-40" />
+                        )}
+                      </span>
+                    )}
+                  </div>
+                </TableHead>
+              );
+            })}
+          </TableRow>
+        </TableHeader>
+
+        {/* Pinned rows */}
+        {pinnedData.length > 0 && (
+          <TableBody className="bg-muted/30 border-b-2 border-border">
+            {pinnedData.map((row, i) => {
+              const key = getRowKey(row, i);
+              const isSelected = selectedRowKeys.includes(key);
+              return (
+                <TableRow
+                  key={key}
+                  data-state={isSelected ? "selected" : undefined}
+                  className={cn(
+                    (onRowClick || selectable === "highlight") && "cursor-pointer",
+                    rowClassName?.(row, i),
+                  )}
+                  onClick={() => handleRowClick(row, i, key)}
+                >
+                  {showCheckboxColumn && (
+                    <TableCell className="w-[40px]">
+                      <Checkbox
+                        checked={isSelected}
+                        onCheckedChange={() => toggleRowSelection(key)}
+                        onClick={(e) => e.stopPropagation()}
+                        aria-label="Select row"
+                      />
+                    </TableCell>
+                  )}
+                  {columns.map((col) => (
+                    <TableCell
+                      key={col.key}
+                      className={cn(alignClass(col.align), col.className)}
+                    >
+                      {renderCellContent(row, col, i)}
+                    </TableCell>
+                  ))}
+                </TableRow>
+              );
+            })}
+          </TableBody>
+        )}
+
+        {/* Main body */}
+        <TableBody>
+          {paginatedData.length === 0 && pinnedData.length === 0 ? (
+            <TableRow>
+              <TableCell
+                colSpan={columns.length + (showCheckboxColumn ? 1 : 0)}
+                className="h-24 text-center"
+              >
+                {emptyState ?? (
+                  <span className="text-muted-foreground">No results.</span>
+                )}
+              </TableCell>
+            </TableRow>
+          ) : (
+            paginatedData.map((row, i) => {
+              // Compute a stable key – need original data index for getRowKey
+              const globalIndex = pageSize ? page * pageSize + i : i;
+              const key = getRowKey(row, globalIndex);
+              const isSelected = selectedRowKeys.includes(key);
+              return (
+                <TableRow
+                  key={key}
+                  data-state={isSelected ? "selected" : undefined}
+                  className={cn(
+                    (onRowClick || selectable === "highlight") && "cursor-pointer",
+                    rowClassName?.(row, globalIndex),
+                  )}
+                  onClick={() => handleRowClick(row, globalIndex, key)}
+                >
+                  {showCheckboxColumn && (
+                    <TableCell className="w-[40px]">
+                      <Checkbox
+                        checked={isSelected}
+                        onCheckedChange={() => toggleRowSelection(key)}
+                        onClick={(e) => e.stopPropagation()}
+                        aria-label="Select row"
+                      />
+                    </TableCell>
+                  )}
+                  {columns.map((col) => (
+                    <TableCell
+                      key={col.key}
+                      className={cn(alignClass(col.align), col.className)}
+                    >
+                      {renderCellContent(row, col, globalIndex)}
+                    </TableCell>
+                  ))}
+                </TableRow>
+              );
+            })
+          )}
+        </TableBody>
+      </Table>
+
+      {/* Pagination footer */}
+      {showPagination && (
+        <div className="flex items-center justify-between pt-4">
+          <div className="flex items-center gap-2">
+            <span className="text-sm text-muted-foreground">Rows per page</span>
+            <Select
+              value={String(pageSize)}
+              onValueChange={(val) => handlePageSizeChange(Number(val))}
+            >
+              <SelectTrigger className="h-8 w-[70px]">
+                <SelectValue placeholder={String(pageSize)} />
+              </SelectTrigger>
+              <SelectContent>
+                {pageSizeOptions.map((opt) => (
+                  <SelectItem key={opt} value={String(opt)}>
+                    {opt}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+
+          <div className="flex items-center gap-4">
+            <span className="text-sm text-muted-foreground">
+              Page {page + 1} of {totalPages}
+              {` (${totalItems} total)`}
+            </span>
+
+            <div className="flex items-center gap-1">
+              <Button
+                variant="ghost"
+                size="icon"
+                className="h-8 w-8"
+                onClick={() => handlePageChange(0)}
+                disabled={page === 0}
+                aria-label="First page"
+              >
+                <ChevronsLeft className="h-4 w-4" />
+              </Button>
+              <Button
+                variant="ghost"
+                size="icon"
+                className="h-8 w-8"
+                onClick={() => handlePageChange(page - 1)}
+                disabled={page === 0}
+                aria-label="Previous page"
+              >
+                <ChevronLeft className="h-4 w-4" />
+              </Button>
+              <Button
+                variant="ghost"
+                size="icon"
+                className="h-8 w-8"
+                onClick={() => handlePageChange(page + 1)}
+                disabled={page >= totalPages - 1}
+                aria-label="Next page"
+              >
+                <ChevronRight className="h-4 w-4" />
+              </Button>
+              <Button
+                variant="ghost"
+                size="icon"
+                className="h-8 w-8"
+                onClick={() => handlePageChange(totalPages - 1)}
+                disabled={page >= totalPages - 1}
+                aria-label="Last page"
+              >
+                <ChevronsRight className="h-4 w-4" />
+              </Button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+DataTable.displayName = "DataTable";