@jmruthers/pace-core 0.2.4

package/src/components/DataTable/hooks/useColumnOrderPersistence.ts

@@ -0,0 +1,95 @@
+import { useState, useEffect, useCallback } from 'react';
+
+interface UseColumnOrderPersistenceProps {
+  tableId?: string;
+  defaultOrder?: string[];
+  enablePersistence?: boolean;
+}
+
+export function useColumnOrderPersistence({
+  tableId,
+  defaultOrder = [],
+  enablePersistence = false,
+}: UseColumnOrderPersistenceProps) {
+  const [columnOrder, setColumnOrder] = useState<string[]>(defaultOrder);
+  const [isLoaded, setIsLoaded] = useState(false);
+
+  // Generate a unique key for this table
+  const storageKey = tableId ? `datatable-column-order-${tableId}` : 'datatable-column-order';
+
+  // Load column order from localStorage on mount
+  useEffect(() => {
+    if (!enablePersistence || !tableId) {
+      setIsLoaded(true);
+      return;
+    }
+
+    try {
+      const savedOrder = localStorage.getItem(storageKey);
+      if (savedOrder) {
+        const parsedOrder = JSON.parse(savedOrder);
+        if (Array.isArray(parsedOrder)) {
+          setColumnOrder(parsedOrder);
+        }
+      }
+    } catch (error) {
+      console.warn('Failed to load column order from localStorage:', error);
+    } finally {
+      setIsLoaded(true);
+    }
+  }, [enablePersistence, tableId, storageKey]);
+
+  // Save column order to localStorage
+  const saveColumnOrder = useCallback((newOrder: string[]) => {
+    if (!enablePersistence || !tableId) return;
+
+    try {
+      localStorage.setItem(storageKey, JSON.stringify(newOrder));
+    } catch (error) {
+      console.warn('Failed to save column order to localStorage:', error);
+    }
+  }, [enablePersistence, tableId, storageKey]);
+
+  // Update column order and save to localStorage
+  const updateColumnOrder = useCallback((newOrder: string[]) => {
+    setColumnOrder(newOrder);
+    saveColumnOrder(newOrder);
+  }, [saveColumnOrder]);
+
+  // Reset to default order
+  const resetColumnOrder = useCallback(() => {
+    setColumnOrder(defaultOrder);
+    if (enablePersistence && tableId) {
+      try {
+        localStorage.removeItem(storageKey);
+      } catch (error) {
+        console.warn('Failed to remove column order from localStorage:', error);
+      }
+    }
+  }, [defaultOrder, enablePersistence, tableId, storageKey]);
+
+  // Clear all saved preferences
+  const clearAllPreferences = useCallback(() => {
+    if (!enablePersistence) return;
+
+    try {
+      // Remove all datatable preferences
+      const keys = Object.keys(localStorage);
+      keys.forEach(key => {
+        if (key.startsWith('datatable-')) {
+          localStorage.removeItem(key);
+        }
+      });
+    } catch (error) {
+      console.warn('Failed to clear datatable preferences:', error);
+    }
+  }, [enablePersistence]);
+
+  return {
+    columnOrder,
+    isLoaded,
+    updateColumnOrder,
+    resetColumnOrder,
+    clearAllPreferences,
+  };
+}

package/src/components/DataTable/hooks/useColumnReordering.ts

@@ -0,0 +1,110 @@
+import { useState, useCallback, useMemo, useEffect } from 'react';
+import type { Column } from '@tanstack/react-table';
+
+interface UseColumnReorderingProps<TData> {
+  columns: Column<TData, unknown>[];
+  onColumnOrderChange?: (columnOrder: string[]) => void;
+  enableReordering?: boolean;
+  enablePersistence?: boolean;
+  tableId?: string;
+  savedColumnOrder?: string[];
+  onColumnOrderUpdate?: (columnOrder: string[]) => void;
+}
+
+export function useColumnReordering<TData>({
+  columns,
+  onColumnOrderChange,
+  enableReordering = false,
+  enablePersistence = false,
+  tableId,
+  savedColumnOrder,
+  onColumnOrderUpdate,
+}: UseColumnReorderingProps<TData>) {
+  const [columnOrder, setColumnOrder] = useState<string[]>(() => {
+    // Use saved order if available, otherwise use default column order
+    if (enablePersistence && savedColumnOrder && savedColumnOrder.length > 0) {
+      return savedColumnOrder;
+    }
+    return columns.map(col => col.id);
+  });
+
+  // Update column order when columns change
+  useMemo(() => {
+    if (enableReordering) {
+      const newOrder = columns.map(col => col.id);
+      setColumnOrder(prevOrder => {
+        // Only update if the order has actually changed
+        if (JSON.stringify(prevOrder) !== JSON.stringify(newOrder)) {
+          return newOrder;
+        }
+        return prevOrder;
+      });
+    }
+  }, [columns, enableReordering]);
+
+  const moveColumn = useCallback((fromIndex: number, toIndex: number) => {
+    if (!enableReordering) return;
+    
+    const newOrder = [...columnOrder];
+    const [movedColumn] = newOrder.splice(fromIndex, 1);
+    newOrder.splice(toIndex, 0, movedColumn);
+    
+    setColumnOrder(newOrder);
+    onColumnOrderChange?.(newOrder);
+    onColumnOrderUpdate?.(newOrder);
+  }, [columnOrder, onColumnOrderChange, onColumnOrderUpdate, enableReordering]);
+
+  const moveColumnLeft = useCallback((columnId: string) => {
+    if (!enableReordering) return;
+    
+    const currentIndex = columnOrder.indexOf(columnId);
+    if (currentIndex > 0) {
+      moveColumn(currentIndex, currentIndex - 1);
+    }
+  }, [columnOrder, moveColumn, enableReordering]);
+
+  const moveColumnRight = useCallback((columnId: string) => {
+    if (!enableReordering) return;
+    
+    const currentIndex = columnOrder.indexOf(columnId);
+    if (currentIndex < columnOrder.length - 1) {
+      moveColumn(currentIndex, currentIndex + 1);
+    }
+  }, [columnOrder, moveColumn, enableReordering]);
+
+  const canMoveLeft = useCallback((columnId: string) => {
+    return enableReordering && columnOrder.indexOf(columnId) > 0;
+  }, [columnOrder, enableReordering]);
+
+  const canMoveRight = useCallback((columnId: string) => {
+    return enableReordering && columnOrder.indexOf(columnId) < columnOrder.length - 1;
+  }, [columnOrder, enableReordering]);
+
+  const reorderColumns = useCallback((newOrder: string[]) => {
+    if (!enableReordering) return;
+    
+    setColumnOrder(newOrder);
+    onColumnOrderChange?.(newOrder);
+    onColumnOrderUpdate?.(newOrder);
+  }, [onColumnOrderChange, onColumnOrderUpdate, enableReordering]);
+
+  // Get columns in the current order
+  const orderedColumns = useMemo(() => {
+    if (!enableReordering) return columns;
+    
+    return columnOrder
+      .map(id => columns.find(col => col.id === id))
+      .filter(Boolean) as Column<TData, unknown>[];
+  }, [columns, columnOrder, enableReordering]);
+
+  return {
+    columnOrder,
+    orderedColumns,
+    moveColumn,
+    moveColumnLeft,
+    moveColumnRight,
+    canMoveLeft,
+    canMoveRight,
+    reorderColumns,
+  };
+}

package/src/components/DataTable/hooks/useDataTableState.ts

@@ -0,0 +1,325 @@
+/**
+ * @file DataTable State Management Hook
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Hooks
+ * @since 0.4.0
+ * 
+ * Centralized state management for DataTable using useReducer pattern.
+ * This replaces the scattered useState calls with a single, predictable state management system.
+ */
+
+import { useReducer, useCallback, useMemo } from 'react';
+import type { 
+  SortingState, 
+  ColumnFiltersState, 
+  VisibilityState, 
+  GroupingState, 
+  ExpandedState,
+  PaginationState 
+} from '@tanstack/react-table';
+import type { DataRecord } from '../types';
+
+// ============================================================================
+// STATE INTERFACE
+// ============================================================================
+
+export interface DataTableState<TData extends DataRecord> {
+  // Table state
+  sorting: SortingState;
+  columnFilters: ColumnFiltersState;
+  columnVisibility: VisibilityState;
+  grouping: GroupingState;
+  expanded: ExpandedState;
+  pagination: PaginationState;
+  columnOrder: string[];
+  
+  // Row operations
+  rowSelection: Record<string, boolean>;
+  
+  // Editing state
+  isCreating: boolean;
+  creationData: Record<string, any>;
+  editingRowId: string | null;
+  editingData: Record<string, any>;
+  
+  // UI state
+  showImportModal: boolean;
+  showFilterRow: boolean;
+  
+  // Search state
+  searchQuery: string;
+}
+
+// ============================================================================
+// ACTION TYPES
+// ============================================================================
+
+export type DataTableAction<TData extends DataRecord> =
+  | { type: 'SET_SORTING'; payload: SortingState }
+  | { type: 'SET_COLUMN_FILTERS'; payload: ColumnFiltersState }
+  | { type: 'SET_COLUMN_VISIBILITY'; payload: VisibilityState }
+  | { type: 'SET_GROUPING'; payload: GroupingState }
+  | { type: 'SET_EXPANDED'; payload: ExpandedState }
+  | { type: 'SET_PAGINATION'; payload: PaginationState }
+  | { type: 'SET_COLUMN_ORDER'; payload: string[] }
+  | { type: 'SET_ROW_SELECTION'; payload: Record<string, boolean> }
+  | { type: 'TOGGLE_ROW_SELECTION'; payload: { rowId: string; selected: boolean } }
+  | { type: 'CLEAR_ROW_SELECTION' }
+  | { type: 'SET_CREATING'; payload: boolean }
+  | { type: 'SET_CREATION_DATA'; payload: Record<string, any> }
+  | { type: 'CLEAR_CREATION_DATA' }
+  | { type: 'SET_EDITING_ROW'; payload: { rowId: string | null; data: Record<string, any> } }
+  | { type: 'CLEAR_EDITING' }
+  | { type: 'SET_IMPORT_MODAL'; payload: boolean }
+  | { type: 'SET_FILTER_ROW'; payload: boolean }
+  | { type: 'SET_SEARCH_QUERY'; payload: string }
+  | { type: 'RESET_STATE' }
+  | { type: 'INITIALIZE_STATE'; payload: Partial<DataTableState<TData>> };
+
+// ============================================================================
+// REDUCER
+// ============================================================================
+
+export function dataTableReducer<TData extends DataRecord>(
+  state: DataTableState<TData>,
+  action: DataTableAction<TData>
+): DataTableState<TData> {
+  switch (action.type) {
+    case 'SET_SORTING':
+      return { ...state, sorting: action.payload };
+    
+    case 'SET_COLUMN_FILTERS':
+      return { ...state, columnFilters: action.payload };
+    
+    case 'SET_COLUMN_VISIBILITY':
+      return { ...state, columnVisibility: action.payload };
+    
+    case 'SET_GROUPING':
+      return { ...state, grouping: action.payload };
+    
+    case 'SET_EXPANDED':
+      return { ...state, expanded: action.payload };
+    
+    case 'SET_PAGINATION':
+      return { ...state, pagination: action.payload };
+    
+    case 'SET_COLUMN_ORDER':
+      return { ...state, columnOrder: action.payload };
+    
+    case 'SET_ROW_SELECTION':
+      return { ...state, rowSelection: action.payload };
+    
+    case 'TOGGLE_ROW_SELECTION':
+      return {
+        ...state,
+        rowSelection: {
+          ...state.rowSelection,
+          [action.payload.rowId]: action.payload.selected
+        }
+      };
+    
+    case 'CLEAR_ROW_SELECTION':
+      return { ...state, rowSelection: {} };
+    
+    case 'SET_CREATING':
+      return { ...state, isCreating: action.payload };
+    
+    case 'SET_CREATION_DATA':
+      return { ...state, creationData: action.payload };
+    
+    case 'CLEAR_CREATION_DATA':
+      return { ...state, creationData: {} };
+    
+    case 'SET_EDITING_ROW':
+      return {
+        ...state,
+        editingRowId: action.payload.rowId,
+        editingData: action.payload.data
+      };
+    
+    case 'CLEAR_EDITING':
+      return { ...state, editingRowId: null, editingData: {} };
+    
+    case 'SET_IMPORT_MODAL':
+      return { ...state, showImportModal: action.payload };
+    
+    case 'SET_FILTER_ROW':
+      return { ...state, showFilterRow: action.payload };
+    
+    case 'SET_SEARCH_QUERY':
+      return { ...state, searchQuery: action.payload };
+    
+    case 'RESET_STATE':
+      return createInitialState<TData>();
+    
+    case 'INITIALIZE_STATE':
+      return { ...state, ...action.payload };
+    
+    default:
+      return state;
+  }
+}
+
+// ============================================================================
+// INITIAL STATE
+// ============================================================================
+
+export function createInitialState<TData extends DataRecord>(
+  initialPageSize: number = 10,
+  columnIds: string[] = []
+): DataTableState<TData> {
+  return {
+    sorting: [],
+    columnFilters: [],
+    columnVisibility: {},
+    grouping: [],
+    expanded: {},
+    pagination: {
+      pageIndex: 0,
+      pageSize: initialPageSize
+    },
+    columnOrder: columnIds,
+    rowSelection: {},
+    isCreating: false,
+    creationData: {},
+    editingRowId: null,
+    editingData: {},
+    showImportModal: false,
+    showFilterRow: false,
+    searchQuery: ''
+  };
+}
+
+// ============================================================================
+// HOOK
+// ============================================================================
+
+export interface UseDataTableStateOptions<TData extends DataRecord> {
+  initialPageSize?: number;
+  columnIds?: string[];
+  initialRowSelection?: Record<string, boolean>;
+  onRowSelectionChange?: (selection: Record<string, boolean>) => void;
+}
+
+export function useDataTableState<TData extends DataRecord>({
+  initialPageSize = 10,
+  columnIds = [],
+  initialRowSelection = {},
+  onRowSelectionChange
+}: UseDataTableStateOptions<TData> = {}) {
+  
+  const initialState = useMemo(() => 
+    createInitialState<TData>(initialPageSize, columnIds),
+    [initialPageSize, columnIds]
+  );
+
+  const [state, dispatch] = useReducer(dataTableReducer<TData>, {
+    ...initialState,
+    rowSelection: initialRowSelection
+  });
+
+  // ============================================================================
+  // ACTION CREATORS
+  // ============================================================================
+
+  const actions = useMemo(() => ({
+    setSorting: (sorting: SortingState) => 
+      dispatch({ type: 'SET_SORTING', payload: sorting }),
+    
+    setColumnFilters: (filters: ColumnFiltersState) => 
+      dispatch({ type: 'SET_COLUMN_FILTERS', payload: filters }),
+    
+    setColumnVisibility: (visibility: VisibilityState) => 
+      dispatch({ type: 'SET_COLUMN_VISIBILITY', payload: visibility }),
+    
+    setGrouping: (grouping: GroupingState) => 
+      dispatch({ type: 'SET_GROUPING', payload: grouping }),
+    
+    setExpanded: (expanded: ExpandedState) => 
+      dispatch({ type: 'SET_EXPANDED', payload: expanded }),
+    
+    setPagination: (pagination: PaginationState) => 
+      dispatch({ type: 'SET_PAGINATION', payload: pagination }),
+    
+    setColumnOrder: (order: string[]) => 
+      dispatch({ type: 'SET_COLUMN_ORDER', payload: order }),
+    
+    setRowSelection: (selection: Record<string, boolean> | ((old: Record<string, boolean>) => Record<string, boolean>)) => {
+      const newSelection = typeof selection === 'function' ? selection(state.rowSelection) : selection;
+      dispatch({ type: 'SET_ROW_SELECTION', payload: newSelection });
+      onRowSelectionChange?.(newSelection);
+    },
+    
+    toggleRowSelection: (rowId: string, selected: boolean) => {
+      dispatch({ type: 'TOGGLE_ROW_SELECTION', payload: { rowId, selected } });
+      const newSelection = { ...state.rowSelection, [rowId]: selected };
+      onRowSelectionChange?.(newSelection);
+    },
+    
+    clearRowSelection: () => {
+      dispatch({ type: 'CLEAR_ROW_SELECTION' });
+      onRowSelectionChange?.({});
+    },
+    
+    setCreating: (isCreating: boolean) => 
+      dispatch({ type: 'SET_CREATING', payload: isCreating }),
+    
+    setCreationData: (data: Record<string, any>) => 
+      dispatch({ type: 'SET_CREATION_DATA', payload: data }),
+    
+    clearCreationData: () => 
+      dispatch({ type: 'CLEAR_CREATION_DATA' }),
+    
+    setEditingRow: (rowId: string | null, data: Record<string, any>) => 
+      dispatch({ type: 'SET_EDITING_ROW', payload: { rowId, data } }),
+    
+    clearEditing: () => 
+      dispatch({ type: 'CLEAR_EDITING' }),
+    
+    setImportModal: (show: boolean) => 
+      dispatch({ type: 'SET_IMPORT_MODAL', payload: show }),
+    
+    setFilterRow: (show: boolean) => 
+      dispatch({ type: 'SET_FILTER_ROW', payload: show }),
+    
+    setSearchQuery: (query: string) => 
+      dispatch({ type: 'SET_SEARCH_QUERY', payload: query }),
+    
+    resetState: () => 
+      dispatch({ type: 'RESET_STATE' }),
+    
+    initializeState: (partialState: Partial<DataTableState<TData>>) => 
+      dispatch({ type: 'INITIALIZE_STATE', payload: partialState })
+  }), [state.rowSelection, onRowSelectionChange]);
+
+  // ============================================================================
+  // COMPUTED VALUES
+  // ============================================================================
+
+  const computed = useMemo(() => ({
+    hasSelection: Object.values(state.rowSelection).some(Boolean),
+    selectedRowIds: Object.entries(state.rowSelection)
+      .filter(([_, selected]) => selected)
+      .map(([rowId, _]) => rowId),
+    isEditing: state.editingRowId !== null,
+    isCreating: state.isCreating,
+    hasFilters: state.columnFilters.length > 0 || state.searchQuery !== '',
+    canClearFilters: state.columnFilters.length > 0 || state.searchQuery !== ''
+  }), [state]);
+
+  // ============================================================================
+  // CLEAR FILTERS
+  // ============================================================================
+
+  const clearFilters = useCallback(() => {
+    dispatch({ type: 'SET_COLUMN_FILTERS', payload: [] });
+    dispatch({ type: 'SET_SEARCH_QUERY', payload: '' });
+  }, []);
+
+  return {
+    state,
+    actions,
+    computed,
+    clearFilters
+  };
+}

package/src/components/DataTable/hooks/useHierarchicalState.ts

@@ -0,0 +1,174 @@
+/**
+ * @file Hierarchical State Management Hook
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Hooks/useHierarchicalState
+ * @since 0.4.35
+ */
+
+import { useState, useCallback, useMemo, useEffect } from 'react';
+import type { HierarchicalDataRow, HierarchicalConfig } from '../types';
+
+/**
+ * Hook for managing hierarchical expand/collapse state
+ * 
+ * Provides state management for hierarchical rows with support for:
+ * - Individual row expansion/collapse
+ * - Bulk expand/collapse operations
+ * - Default expanded state configuration
+ * - Parent/child relationship tracking
+ */
+export function useHierarchicalState<TData extends HierarchicalDataRow>(
+  data: TData[],
+  config?: HierarchicalConfig
+) {
+  // Initialize expanded state based on defaultExpanded config
+  const getInitialExpandedState = useCallback((): Set<string> => {
+    if (!config?.defaultExpanded) {
+      return new Set();
+    }
+
+    if (config.defaultExpanded === true) {
+      // All parent rows expanded
+      return new Set(data.filter(row => row.isParent).map(row => row.id));
+    }
+
+    if (Array.isArray(config.defaultExpanded)) {
+      // Specific rows expanded
+      return new Set(config.defaultExpanded);
+    }
+
+    // All collapsed
+    return new Set();
+  }, [data, config?.defaultExpanded]);
+
+  const [expandedRows, setExpandedRows] = useState<Set<string>>(getInitialExpandedState);
+
+  // Reset expanded state when data changes
+  useEffect(() => {
+    setExpandedRows(getInitialExpandedState());
+  }, [getInitialExpandedState]);
+
+  // Get parent-child relationships
+  const parentChildMap = useMemo(() => {
+    const map = new Map<string, TData[]>();
+    
+    if (Array.isArray(data)) {
+      data.forEach(row => {
+        if (row.isParent) {
+          map.set(row.id, []);
+        } else if (row.parentId) {
+          const children = map.get(row.parentId) || [];
+          children.push(row);
+          map.set(row.parentId, children);
+        }
+      });
+    }
+
+    return map;
+  }, [data]);
+
+  // Get visible rows (parent rows + expanded children)
+  const visibleRows = useMemo(() => {
+    const visible: TData[] = [];
+    
+    if (Array.isArray(data)) {
+      data.forEach(row => {
+        if (row.isParent) {
+          visible.push(row);
+          
+          // Add children if parent is expanded
+          if (expandedRows.has(row.id)) {
+            const children = parentChildMap.get(row.id) || [];
+            visible.push(...children);
+          }
+        }
+      });
+    }
+
+    return visible;
+  }, [data, expandedRows, parentChildMap]);
+
+  // Toggle single row expansion
+  const toggleRow = useCallback((rowId: string) => {
+    setExpandedRows(prev => {
+      const newSet = new Set(prev);
+      if (newSet.has(rowId)) {
+        newSet.delete(rowId);
+      } else {
+        newSet.add(rowId);
+      }
+      
+      // Notify parent component
+      if (config?.onExpandedChange) {
+        config.onExpandedChange(Array.from(newSet));
+      }
+      
+      return newSet;
+    });
+  }, [config]);
+
+  // Expand all parent rows
+  const expandAll = useCallback(() => {
+    const parentIds = data.filter(row => row.isParent).map(row => row.id);
+    setExpandedRows(new Set(parentIds));
+    
+    if (config?.onExpandedChange) {
+      config.onExpandedChange(parentIds);
+    }
+  }, [data, config]);
+
+  // Collapse all rows
+  const collapseAll = useCallback(() => {
+    setExpandedRows(new Set());
+    
+    if (config?.onExpandedChange) {
+      config.onExpandedChange([]);
+    }
+  }, [config]);
+
+  // Check if row is expanded
+  const isExpanded = useCallback((rowId: string) => {
+    return expandedRows.has(rowId);
+  }, [expandedRows]);
+
+  // Check if row has children
+  const hasChildren = useCallback((rowId: string) => {
+    return parentChildMap.has(rowId) && (parentChildMap.get(rowId)?.length || 0) > 0;
+  }, [parentChildMap]);
+
+  // Get children count for a parent row
+  const getChildrenCount = useCallback((rowId: string) => {
+    return parentChildMap.get(rowId)?.length || 0;
+  }, [parentChildMap]);
+
+  // Get all expanded row IDs
+  const getExpandedIds = useCallback(() => {
+    return Array.from(expandedRows);
+  }, [expandedRows]);
+
+  // Set expanded state from external source
+  const setExpandedIds = useCallback((ids: string[]) => {
+    setExpandedRows(new Set(ids));
+  }, []);
+
+  return {
+    // State
+    expandedRows,
+    visibleRows,
+    
+    // Actions
+    toggleRow,
+    expandAll,
+    collapseAll,
+    setExpandedIds,
+    
+    // Getters
+    isExpanded,
+    hasChildren,
+    getChildrenCount,
+    getExpandedIds,
+    
+    // Utilities
+    parentChildMap,
+  };
+}