@fabio.caffarello/react-design-system 1.7.0 → 1.9.0

package/src/ui/organisms/Table/TableProvider.tsx

@@ -0,0 +1,429 @@
+'use client';
+
+import { useState, useMemo, useCallback } from 'react';
+import type { ReactNode } from 'react';
+import { TableContext, type TableContextValue, type PaginationMode } from './TableContext';
+import type { TableColumn } from './TableTypes';
+import type { FilterConfig, FilterValue } from './TableFilters/TableFilters';
+import type { TableAction } from './TableActions/TableActions';
+
+export interface TableProviderProps<T extends Record<string, unknown> = Record<string, unknown>> {
+  columns: TableColumn<T>[];
+  data: T[];
+  loading?: boolean;
+  
+  // Pagination
+  paginationMode?: PaginationMode;
+  page?: number; // controlled
+  pageSize?: number; // controlled
+  total?: number; // required for server mode
+  onPageChange?: (page: number) => void; // required for server mode
+  onPageSizeChange?: (size: number) => void;
+  defaultPageSize?: number;
+  pageSizeOptions?: number[];
+  
+  // Sorting
+  sortColumn?: string; // controlled
+  sortDirection?: 'asc' | 'desc'; // controlled
+  onSort?: (column: string, direction: 'asc' | 'desc') => void;
+  defaultSortColumn?: string;
+  defaultSortDirection?: 'asc' | 'desc';
+  
+  // Filters
+  filters?: FilterConfig[];
+  filterValues?: Record<string, FilterValue>; // controlled
+  onFilter?: (filters: Record<string, FilterValue>) => void;
+  initialFilterValues?: Record<string, FilterValue>;
+  
+  // Selection
+  selectable?: boolean;
+  selectedRows?: string[]; // controlled
+  onSelectionChange?: (selected: string[]) => void;
+  rowId?: (row: T) => string;
+  
+  // Actions
+  actions?: (row: T) => TableAction<T>[];
+  
+  // Empty state
+  emptyMessage?: string;
+  emptyStateTitle?: string;
+  emptyStateMessage?: string;
+  emptyStateIllustration?: ReactNode;
+  emptyStateAction?: ReactNode;
+  
+  // Callbacks
+  onRowClick?: (row: T) => void;
+  
+  // Column resizing
+  resizable?: boolean;
+  columnWidths?: Record<string, number>;
+  onColumnResize?: (columnKey: string, width: number) => void;
+  
+  // Virtual scrolling
+  virtualScrolling?: boolean;
+  virtualScrollingOptions?: {
+    itemHeight?: number;
+    containerHeight?: number;
+    overscan?: number;
+  };
+  
+  children: ReactNode;
+}
+
+/**
+ * TableProvider Component
+ * 
+ * Manages table state (pagination, sorting, filters, selection) and provides it via Context.
+ * Supports both client-side and server-side pagination with auto-detection.
+ */
+export function TableProvider<T extends Record<string, unknown> = Record<string, unknown>>({
+  columns,
+  data,
+  loading = false,
+  paginationMode: explicitMode,
+  page: controlledPage,
+  pageSize: controlledPageSize,
+  total: externalTotal,
+  onPageChange,
+  onPageSizeChange,
+  defaultPageSize = 10,
+  pageSizeOptions: _pageSizeOptions,
+  sortColumn: controlledSortColumn,
+  sortDirection: controlledSortDirection,
+  onSort,
+  defaultSortColumn,
+  defaultSortDirection = 'asc',
+  filters,
+  filterValues: controlledFilterValues,
+  onFilter,
+  initialFilterValues = {},
+  selectable = false,
+  selectedRows: controlledSelectedRows,
+  onSelectionChange,
+  rowId,
+  actions,
+  emptyMessage = "No data available",
+  emptyStateTitle,
+  emptyStateMessage,
+  emptyStateIllustration,
+  emptyStateAction,
+  onRowClick,
+  resizable = false,
+  columnWidths,
+  onColumnResize,
+  virtualScrolling,
+  virtualScrollingOptions: _virtualScrollingOptions,
+  children,
+}: TableProviderProps<T>) {
+  // Detect pagination mode
+  const paginationMode: PaginationMode = useMemo(() => {
+    if (explicitMode) return explicitMode;
+    
+    // Auto-detect: if total and onPageChange are provided, it's server-side
+    if (externalTotal !== undefined && onPageChange) {
+      return 'server';
+    }
+    
+    return 'client';
+  }, [explicitMode, externalTotal, onPageChange]);
+
+  // Pagination state
+  const isPaginationControlled = controlledPage !== undefined;
+  const [internalPage, setInternalPage] = useState(1);
+  const [internalPageSize, setInternalPageSize] = useState(defaultPageSize);
+  
+  const page = isPaginationControlled ? controlledPage! : internalPage;
+  const pageSize = controlledPageSize ?? internalPageSize;
+  
+  const total = useMemo(() => {
+    if (paginationMode === 'server') {
+      return externalTotal ?? 0;
+    }
+    return data.length;
+  }, [paginationMode, externalTotal, data.length]);
+  
+  const totalPages = useMemo(() => {
+    return Math.ceil(total / pageSize);
+  }, [total, pageSize]);
+
+  // Sorting state
+  const isSortingControlled = controlledSortColumn !== undefined;
+  const [internalSortColumn, setInternalSortColumn] = useState(defaultSortColumn || '');
+  const [internalSortDirection, setInternalSortDirection] = useState<'asc' | 'desc'>(defaultSortDirection);
+  
+  const sortColumn = isSortingControlled ? controlledSortColumn! : internalSortColumn;
+  const sortDirection = isSortingControlled ? (controlledSortDirection || 'asc') : internalSortDirection;
+
+  // Filter state
+  const isFilterControlled = controlledFilterValues !== undefined;
+  const [internalFilterValues, setInternalFilterValues] = useState<Record<string, unknown>>(initialFilterValues);
+  
+  const filterValues = isFilterControlled ? controlledFilterValues! : internalFilterValues;
+
+  // Selection state
+  const isSelectionControlled = controlledSelectedRows !== undefined;
+  const [internalSelectedRows, setInternalSelectedRows] = useState<string[]>([]);
+  
+  const selectedRows = isSelectionControlled ? controlledSelectedRows! : internalSelectedRows;
+
+  // Apply client-side filtering
+  const filteredData = useMemo(() => {
+    if (!filters || filters.length === 0) return data;
+    
+    return data.filter((row) => {
+      return filters.every((filter) => {
+        const value = filterValues[filter.key];
+        if (!value || value === '') return true;
+        
+        const rowValue = (row as unknown)[filter.key];
+        if (filter.type === 'text') {
+          return String(rowValue || '').toLowerCase().includes(String(value).toLowerCase());
+        }
+        return String(rowValue) === String(value);
+      });
+    });
+  }, [data, filters, filterValues]);
+
+  // Apply client-side sorting (only if not controlled externally)
+  const sortedData = useMemo(() => {
+    // If sorting is controlled externally (onSort provided), don't sort here
+    // The parent component should handle sorting on the server or before passing data
+    // However, we still apply sorting if sortColumn is set and no onSort callback
+    if (isSortingControlled && onSort) {
+      // When controlled, assume data is already sorted by parent
+      return filteredData;
+    }
+    
+    // Only apply internal sorting if sortColumn is set
+    if (!sortColumn) return filteredData;
+    
+    // Apply internal sorting
+    const sorted = [...filteredData];
+    sorted.sort((a, b) => {
+      const aValue = (a as unknown)[sortColumn];
+      const bValue = (b as unknown)[sortColumn];
+      const comparison = String(aValue || '').localeCompare(String(bValue || ''));
+      return sortDirection === 'asc' ? comparison : -comparison;
+    });
+    
+    return sorted;
+  }, [filteredData, sortColumn, sortDirection, onSort, isSortingControlled]);
+
+  // Apply client-side pagination
+  const paginatedData = useMemo(() => {
+    if (paginationMode === 'server') {
+      return sortedData; // Server already paginated
+    }
+    
+    const startIndex = (page - 1) * pageSize;
+    const endIndex = startIndex + pageSize;
+    return sortedData.slice(startIndex, endIndex);
+  }, [sortedData, paginationMode, page, pageSize]);
+
+  // Selection helpers
+  const getRowId = useCallback((row: T, index: number): string => {
+    if (rowId) {
+      return rowId(row);
+    }
+    return (row as unknown)?.id?.toString() || index.toString();
+  }, [rowId]);
+
+  const isAllSelected = useMemo(() => {
+    if (!selectable || paginatedData.length === 0) return false;
+    return paginatedData.every((row, index) => {
+      const id = getRowId(row, index);
+      return selectedRows.includes(id);
+    });
+  }, [selectable, paginatedData, selectedRows, getRowId]);
+
+  const isIndeterminate = useMemo(() => {
+    if (!selectable) return false;
+    const selectedCount = selectedRows.length;
+    return selectedCount > 0 && selectedCount < paginatedData.length;
+  }, [selectable, selectedRows.length, paginatedData.length]);
+
+  // Methods
+  const setPage = useCallback((newPage: number) => {
+    if (isPaginationControlled) {
+      onPageChange?.(newPage);
+    } else {
+      setInternalPage(newPage);
+    }
+  }, [isPaginationControlled, onPageChange]);
+
+  const setPageSize = useCallback((newSize: number) => {
+    if (onPageSizeChange) {
+      onPageSizeChange(newSize);
+    } else {
+      setInternalPageSize(newSize);
+    }
+    setPage(1); // Reset to first page
+  }, [onPageSizeChange, setPage]);
+
+  const setSorting = useCallback((column: string, direction: 'asc' | 'desc') => {
+    if (isSortingControlled) {
+      onSort?.(column, direction);
+    } else {
+      setInternalSortColumn(column);
+      setInternalSortDirection(direction);
+    }
+  }, [isSortingControlled, onSort]);
+
+  const setFilters = useCallback((newFilters: Record<string, FilterValue>) => {
+    if (isFilterControlled) {
+      onFilter?.(newFilters);
+    } else {
+      setInternalFilterValues(newFilters);
+    }
+    // Reset to first page when filters change
+    setPage(1);
+  }, [isFilterControlled, onFilter, setPage]);
+
+  const setSelection = useCallback((selected: string[]) => {
+    if (isSelectionControlled) {
+      onSelectionChange?.(selected);
+    } else {
+      setInternalSelectedRows(selected);
+    }
+  }, [isSelectionControlled, onSelectionChange]);
+
+  const toggleRowSelection = useCallback((rowId: string) => {
+    const newSelected = selectedRows.includes(rowId)
+      ? selectedRows.filter((id) => id !== rowId)
+      : [...selectedRows, rowId];
+    setSelection(newSelected);
+  }, [selectedRows, setSelection]);
+
+  const toggleSelectAll = useCallback(() => {
+    if (isAllSelected) {
+      setSelection([]);
+    } else {
+      const allIds = paginatedData.map((row, index) => getRowId(row, index));
+      setSelection(allIds);
+    }
+  }, [isAllSelected, paginatedData, getRowId, setSelection]);
+
+  // Column resizing state
+  const [internalColumnWidths, setInternalColumnWidths] = useState<Record<string, number>>({});
+  const isColumnWidthsControlled = columnWidths !== undefined;
+  const finalColumnWidths = isColumnWidthsControlled ? columnWidths! : internalColumnWidths;
+
+  const setColumnWidth = useCallback((columnKey: string, width: number) => {
+    if (isColumnWidthsControlled) {
+      onColumnResize?.(columnKey, width);
+    } else {
+      setInternalColumnWidths((prev) => ({
+        ...prev,
+        [columnKey]: width,
+      }));
+    }
+  }, [isColumnWidthsControlled, onColumnResize]);
+
+  // Use controlledColumnWidths from props if provided
+  const _controlledColumnWidths = columnWidths;
+
+  // Context value
+  const contextValue: TableContextValue<T> = useMemo(() => ({
+    columns,
+    data,
+    paginatedData,
+    loading,
+    paginationState: {
+      page,
+      pageSize,
+      total,
+      totalPages,
+    },
+    sortState: {
+      column: sortColumn,
+      direction: sortDirection,
+    },
+    filterState: {
+      values: filterValues,
+      config: filters || [],
+    },
+    selectionState: {
+      selectedRows,
+      isAllSelected,
+      isIndeterminate,
+    },
+    paginationMode,
+    selectable,
+    rowId,
+    actions,
+    resizable,
+    columnWidths: finalColumnWidths,
+    virtualScrolling,
+    emptyMessage,
+    emptyStateTitle,
+    emptyStateMessage,
+    emptyStateIllustration,
+    emptyStateAction,
+    setPage,
+    setPageSize,
+    setSorting,
+    setFilters,
+    setSelection,
+    toggleRowSelection,
+    toggleSelectAll,
+    getRowId,
+    setColumnWidth,
+    onPageChange,
+    onPageSizeChange,
+    onSort,
+    onFilter,
+    onSelectionChange,
+    onRowClick,
+    onColumnResize,
+  }), [
+    columns,
+    data,
+    paginatedData,
+    loading,
+    page,
+    pageSize,
+    total,
+    totalPages,
+    sortColumn,
+    sortDirection,
+    filterValues,
+    filters,
+    selectedRows,
+    isAllSelected,
+    isIndeterminate,
+    paginationMode,
+    selectable,
+    rowId,
+    actions,
+    emptyMessage,
+    emptyStateTitle,
+    emptyStateMessage,
+    emptyStateIllustration,
+    emptyStateAction,
+    setPage,
+    setPageSize,
+    setSorting,
+    setFilters,
+    setSelection,
+    toggleRowSelection,
+    toggleSelectAll,
+    getRowId,
+    setColumnWidth,
+    onPageChange,
+    onPageSizeChange,
+    onSort,
+    onFilter,
+    onSelectionChange,
+    onRowClick,
+    onColumnResize,
+    resizable,
+    columnWidths,
+    virtualScrolling,
+  ]);
+
+  return (
+    <TableContext.Provider value={contextValue}>
+      {children}
+    </TableContext.Provider>
+  );
+}

package/src/ui/organisms/Table/TableRow.tsx

@@ -0,0 +1,85 @@
+'use client';
+
+import type { HTMLAttributes } from 'react';
+import { useTableContext } from './TableContext';
+import { Checkbox } from '../../atoms';
+import TableCell from './TableCell';
+import TableActions from './TableActions';
+
+export interface TableRowProps<T extends Record<string, unknown> = Record<string, unknown>> extends Omit<HTMLAttributes<HTMLTableRowElement>, 'style'> {
+  row: T;
+  rowIndex: number;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+/**
+ * TableRow Component
+ * 
+ * Renders a table row (tr) with cells.
+ * Supports selection and row click.
+ * Must be used within a Table component.
+ */
+export default function TableRow<T extends Record<string, unknown> = Record<string, unknown>>({
+  row,
+  rowIndex,
+  className = '',
+  onClick,
+  style,
+  ...props
+}: TableRowProps<T>) {
+  const {
+    columns,
+    selectable,
+    selectionState,
+    toggleRowSelection,
+    getRowId,
+    actions,
+    onRowClick,
+  } = useTableContext<T>();
+
+  const id = getRowId(row, rowIndex);
+  const isSelected = selectionState.selectedRows.includes(id);
+
+  const handleClick = (e: React.MouseEvent<HTMLTableRowElement>) => {
+    if (onClick) {
+      onClick(e);
+    }
+    if (onRowClick) {
+      onRowClick(row);
+    }
+  };
+
+  return (
+    <tr
+      role="row"
+      aria-selected={selectable ? isSelected : undefined}
+      aria-rowindex={rowIndex + 1}
+      className={`hover:bg-gray-50 ${isSelected ? 'bg-indigo-50' : ''} ${className}`}
+      onClick={handleClick}
+      style={style}
+      {...props}
+    >
+      {selectable && (
+        <td className="px-6 py-4">
+          <Checkbox
+            checked={isSelected}
+            onChange={() => toggleRowSelection(id)}
+            aria-label={`Select row ${id}`}
+            className="my-0"
+          />
+        </td>
+      )}
+      
+      {columns.map((column) => (
+        <TableCell key={column.key} column={column} row={row} />
+      ))}
+      
+      {actions && (
+        <td className="px-6 py-4 text-right">
+          <TableActions row={row} />
+        </td>
+      )}
+    </tr>
+  );
+}

package/src/ui/organisms/Table/TableTypes.ts

@@ -0,0 +1,11 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+export interface TableColumn<T = Record<string, unknown>> {
+  key: keyof T | string;
+  label: string;
+  render?: (value: unknown, row: T) => ReactNode;
+  sortable?: boolean;
+  hiddenOnMobile?: boolean;
+}

package/src/ui/organisms/Table/index.ts

@@ -0,0 +1,55 @@
+// Main Table component
+export { default as Table } from './Table';
+export type { TableColumn } from './TableTypes';
+
+// Context
+export { TableContext, useTableContext, useTableContextOptional } from './TableContext';
+export type {
+  TableContextValue,
+  PaginationMode,
+  PaginationState,
+  SortState,
+  FilterState,
+  SelectionState,
+} from './TableContext';
+
+// Provider
+export { TableProvider } from './TableProvider';
+export type { TableProviderProps } from './TableProvider';
+
+// Compound Components
+export { default as TableHeader } from './TableHeader';
+export type { TableHeaderProps } from './TableHeader';
+
+export { default as TableHeaderRow } from './TableHeaderRow';
+export type { TableHeaderRowProps } from './TableHeaderRow';
+
+export { default as TableHeaderCell } from './TableHeaderCell';
+export type { TableHeaderCellProps } from './TableHeaderCell';
+
+export { default as TableBody } from './TableBody';
+export type { TableBodyProps } from './TableBody';
+
+export { default as TableRow } from './TableRow';
+export type { TableRowProps } from './TableRow';
+
+export { default as TableCell } from './TableCell';
+export type { TableCellProps } from './TableCell';
+
+export { default as TableFilters } from './TableFilters';
+export type { TableFiltersProps } from './TableFilters';
+
+export { default as TablePagination } from './TablePagination';
+export type { TablePaginationProps } from './TablePagination';
+
+export { default as TableEmptyState } from './TableEmptyState';
+export type { TableEmptyStateProps } from './TableEmptyState';
+
+export { default as TableActions } from './TableActions';
+export type { TableActionsProps } from './TableActions';
+
+// Hooks
+export { useVirtualScrolling } from './useVirtualScrolling';
+export { useColumnResizing } from './useColumnResizing';
+export type { UseVirtualScrollingOptions, VirtualScrollingResult } from './useVirtualScrolling';
+export type { UseColumnResizingOptions, UseColumnResizingResult } from './useColumnResizing';

package/src/ui/organisms/Table/useColumnResizing.ts

@@ -0,0 +1,134 @@
+'use client';
+
+import { useState, useCallback, useRef } from 'react';
+
+export interface ColumnWidth {
+  [key: string]: number;
+}
+
+export interface UseColumnResizingOptions {
+  defaultWidths?: ColumnWidth;
+  minWidth?: number;
+  maxWidth?: number;
+  resizable?: boolean;
+}
+
+export interface UseColumnResizingResult {
+  columnWidths: ColumnWidth;
+  setColumnWidth: (columnKey: string, width: number) => void;
+  resetColumnWidths: () => void;
+  isResizing: boolean;
+  resizingColumn: string | null;
+  startResize: (columnKey: string, startX: number, startWidth: number) => void;
+  handleResize: (currentX: number) => void;
+  endResize: () => void;
+}
+
+/**
+ * useColumnResizing Hook
+ * 
+ * Hook for managing column resizing in tables.
+ * 
+ * @example
+ * ```tsx
+ * const {
+ *   columnWidths,
+ *   setColumnWidth,
+ *   startResize,
+ *   handleResize,
+ *   endResize,
+ * } = useColumnResizing({
+ *   defaultWidths: { name: 200, email: 250 },
+ *   minWidth: 100,
+ * });
+ * ```
+ */
+export function useColumnResizing(
+  options: UseColumnResizingOptions = {}
+): UseColumnResizingResult {
+  const {
+    defaultWidths = {},
+    minWidth = 50,
+    maxWidth,
+    resizable = true,
+  } = options;
+
+  const [columnWidths, setColumnWidths] = useState<ColumnWidth>(defaultWidths);
+  const [isResizing, setIsResizing] = useState(false);
+  const [resizingColumn, setResizingColumn] = useState<string | null>(null);
+  const resizeStateRef = useRef<{ startX: number; startWidth: number } | null>(null);
+
+  const setColumnWidth = useCallback((columnKey: string, width: number) => {
+    const clampedWidth = Math.max(minWidth, maxWidth ? Math.min(width, maxWidth) : width);
+    setColumnWidths((prev) => ({
+      ...prev,
+      [columnKey]: clampedWidth,
+    }));
+  }, [minWidth, maxWidth]);
+
+  const resetColumnWidths = useCallback(() => {
+    setColumnWidths(defaultWidths);
+  }, [defaultWidths]);
+
+  const startResize = useCallback((columnKey: string, startX: number, startWidth: number) => {
+    if (!resizable) return;
+    setIsResizing(true);
+    setResizingColumn(columnKey);
+    resizeStateRef.current = { startX, startWidth };
+  }, [resizable]);
+
+  const handleResize = useCallback((currentX: number) => {
+    if (!isResizing || !resizingColumn || !resizeStateRef.current) return;
+    
+    const deltaX = currentX - resizeStateRef.current.startX;
+    const newWidth = resizeStateRef.current.startWidth + deltaX;
+    setColumnWidth(resizingColumn, newWidth);
+  }, [isResizing, resizingColumn, setColumnWidth]);
+
+  const endResize = useCallback(() => {
+    setIsResizing(false);
+    setResizingColumn(null);
+    resizeStateRef.current = null;
+  }, []);
+
+  // Handle mouse move and mouse up globally during resize
+  const handleMouseMoveRef = useRef<(e: MouseEvent) => void>();
+  const handleMouseUpRef = useRef<() => void>();
+
+  if (typeof window !== 'undefined') {
+    handleMouseMoveRef.current = (e: MouseEvent) => {
+      if (isResizing) {
+        handleResize(e.clientX);
+      }
+    };
+
+    handleMouseUpRef.current = () => {
+      if (isResizing) {
+        endResize();
+      }
+    };
+
+    if (isResizing) {
+      document.addEventListener('mousemove', handleMouseMoveRef.current);
+      document.addEventListener('mouseup', handleMouseUpRef.current);
+    } else {
+      if (handleMouseMoveRef.current) {
+        document.removeEventListener('mousemove', handleMouseMoveRef.current);
+      }
+      if (handleMouseUpRef.current) {
+        document.removeEventListener('mouseup', handleMouseUpRef.current);
+      }
+    }
+  }
+
+  return {
+    columnWidths,
+    setColumnWidth,
+    resetColumnWidths,
+    isResizing,
+    resizingColumn,
+    startResize,
+    handleResize,
+    endResize,
+  };
+}