@jmruthers/pace-core 0.2.4

package/src/hooks/useDataTablePerformance.ts

@@ -0,0 +1,387 @@
+/**
+ * @file DataTable Performance Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/DataTablePerformance
+ * @since 0.3.0
+ */
+
+import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
+import type { 
+  DataRecord,
+  PaginationMode,
+  PerformanceConfig,
+  ServerSideConfig,
+  ServerSideParams,
+  ServerSideResponse,
+  ChunkingConfig,
+  SearchIndexConfig,
+} from '../components/DataTable/types';
+import {
+  determinePaginationMode,
+  getOptimalPageSizeOptions,
+  DataChunkManager,
+  SearchIndex,
+  debounce,
+  VisibilityTracker
+} from '../components/DataTable/utils/performanceUtils';
+import {
+  ErrorRecoveryManager,
+  DataTableError,
+  DataTableErrorType,
+  safeExecute,
+  MemoryMonitor,
+  CircuitBreaker,
+  DEFAULT_FALLBACK_CONFIG,
+  type FallbackConfig
+} from '../components/DataTable/utils/errorHandling';
+
+export interface UseDataTablePerformanceOptions<TData extends DataRecord> {
+  data: TData[];
+  performance?: PerformanceConfig;
+  serverSide?: ServerSideConfig<TData>;
+  chunking?: ChunkingConfig;
+  searchIndex?: SearchIndexConfig;
+  // Enhanced error handling options
+  fallbackConfig?: FallbackConfig;
+  onError?: (error: DataTableError) => void;
+  enableErrorRecovery?: boolean;
+}
+
+export interface UseDataTablePerformanceReturn<TData extends DataRecord> {
+  // Performance state
+  paginationMode: PaginationMode;
+  isVirtualized: boolean;
+  pageSizeOptions: number[];
+  
+  // Data management
+  processedData: TData[];
+  totalCount: number;
+  isLoading: boolean;
+  
+  // Search functionality
+  searchQuery: string;
+  setSearchQuery: (query: string) => void;
+  searchResults: number[];
+  
+  // Server-side functionality
+  fetchServerData: (params: ServerSideParams) => Promise<void>;
+  serverData: ServerSideResponse<TData> | null;
+  
+  // Performance monitoring
+  memoryUsage: number;
+  
+  // Error handling and recovery
+  errorState: {
+    hasErrors: boolean;
+    errorCount: number;
+    lastError: DataTableError | null;
+    fallbacksActive: string[];
+  };
+  retryLastOperation: () => Promise<void>;
+  clearErrors: () => void;
+  
+  // Cleanup
+  cleanup: () => void;
+}
+
+/**
+ * Hook for managing DataTable performance optimizations
+ */
+export function useDataTablePerformance<TData extends DataRecord>({
+  data,
+  performance = {},
+  serverSide,
+  chunking,
+  searchIndex,
+  fallbackConfig = DEFAULT_FALLBACK_CONFIG,
+  onError,
+  enableErrorRecovery = true
+}: UseDataTablePerformanceOptions<TData>): UseDataTablePerformanceReturn<TData> {
+  // ============================================================================
+  // STATE MANAGEMENT
+  // ============================================================================
+  
+  const [isLoading, setIsLoading] = useState(false);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [searchResults, setSearchResults] = useState<number[]>([]);
+  const [serverData, setServerData] = useState<ServerSideResponse<TData> | null>(null);
+  const [memoryUsage, setMemoryUsage] = useState(0);
+  
+  // Error handling state
+  const [errorState, setErrorState] = useState({
+    hasErrors: false,
+    errorCount: 0,
+    lastError: null as DataTableError | null,
+    fallbacksActive: [] as string[],
+  });
+  const [lastFailedOperation, setLastFailedOperation] = useState<(() => Promise<any>) | null>(null);
+
+  // ============================================================================
+  // REFS AND MANAGERS
+  // ============================================================================
+  
+  const chunkManagerRef = useRef<DataChunkManager<TData> | null>(null);
+  const searchIndexRef = useRef<SearchIndex<TData> | null>(null);
+  const visibilityTrackerRef = useRef<VisibilityTracker | null>(null);
+  
+  // Error handling managers
+  const errorRecoveryManagerRef = useRef<ErrorRecoveryManager>(new ErrorRecoveryManager(fallbackConfig));
+  const memoryMonitorRef = useRef<MemoryMonitor | null>(null);
+  const circuitBreakerRef = useRef<CircuitBreaker>(new CircuitBreaker());
+
+  // ============================================================================
+  // COMPUTED VALUES
+  // ============================================================================
+  
+  const paginationMode = useMemo(() => {
+    if (serverSide) return 'server';
+    return determinePaginationMode(data?.length || 0, performance.serverSideThreshold);
+  }, [data?.length, performance.serverSideThreshold, serverSide]);
+
+  // Virtualization is now handled internally by UnifiedTableBody
+  const isVirtualized = false;
+
+  const pageSizeOptions = useMemo(() => {
+    return getOptimalPageSizeOptions(paginationMode, data?.length || 0);
+  }, [paginationMode, data?.length]);
+
+  // ============================================================================
+  // DATA PROCESSING
+  // ============================================================================
+  
+  const processedData = useMemo(() => {
+    if (serverSide && serverData) {
+      return serverData.data;
+    }
+
+    let filteredData = data;
+    
+    // Apply search filtering - ensure we don't exclude zero values
+    if (searchQuery && searchResults.length > 0) {
+      filteredData = searchResults.map(index => data[index]);
+    }
+
+    // Important: Ensure we don't accidentally filter out rows with zero values
+    // This was causing "no data" issues when rows contained zero values in numeric columns
+    // The filtering should be explicit, not implicit based on falsy values
+
+    return filteredData;
+  }, [data, serverData, searchQuery, searchResults, serverSide]);
+
+  const totalCount = useMemo(() => {
+    if (serverSide && serverData) {
+      return serverData.totalCount;
+    }
+    return processedData?.length || 0;
+  }, [serverData, processedData?.length, serverSide]);
+
+  // ============================================================================
+  // CHUNK MANAGEMENT
+  // ============================================================================
+  
+  useEffect(() => {
+    if (chunking && !chunkManagerRef.current) {
+      chunkManagerRef.current = new DataChunkManager<TData>(chunking);
+    }
+  }, [chunking]);
+
+  // ============================================================================
+  // SEARCH INDEX MANAGEMENT
+  // ============================================================================
+  
+  useEffect(() => {
+    if (searchIndex && !searchIndexRef.current) {
+      searchIndexRef.current = new SearchIndex<TData>(searchIndex);
+    }
+
+    if (searchIndexRef.current && data.length > 0) {
+      searchIndexRef.current.buildIndex(data);
+    }
+  }, [searchIndex, data]);
+
+  // Debounced search function
+  const debouncedSearch = useCallback(
+    debounce((query: string) => {
+      if (!searchIndexRef.current) return;
+      
+      if (!query.trim()) {
+        setSearchResults([]);
+        return;
+      }
+
+      const results = searchIndexRef.current.search(query);
+      setSearchResults(results);
+    }, performance.debounceSearch ?? 300),
+    [performance.debounceSearch]
+  );
+
+  // Handle search query changes
+  useEffect(() => {
+    debouncedSearch(searchQuery);
+  }, [searchQuery, debouncedSearch]);
+
+  // ============================================================================
+  // SERVER-SIDE DATA FETCHING
+  // ============================================================================
+  
+  const fetchServerData = useCallback(async (params: ServerSideParams) => {
+    if (!serverSide) return;
+
+    setIsLoading(true);
+    try {
+      const response = await serverSide.fetchData(params);
+      setServerData(response);
+    } catch (error) {
+      console.error('Failed to fetch server data:', error);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [serverSide]);
+
+  // ============================================================================
+  // PERFORMANCE MONITORING
+  // ============================================================================
+  
+  useEffect(() => {
+    if (!visibilityTrackerRef.current) {
+      visibilityTrackerRef.current = new VisibilityTracker();
+    }
+
+    const tracker = visibilityTrackerRef.current;
+    const unsubscribe = tracker.onVisibilityChange((visibleCount) => {
+      // Performance monitoring removed
+    });
+
+    return unsubscribe;
+  }, [totalCount, isVirtualized, paginationMode]);
+
+  // Update memory usage
+  useEffect(() => {
+    const updateMemoryUsage = () => {
+      let usage = 0;
+      
+      if (chunkManagerRef.current) {
+        usage += chunkManagerRef.current.getMemoryUsage();
+      }
+      
+      // Add general memory estimation
+      usage += (JSON.stringify(processedData || []).length) / (1024 * 1024);
+      
+      setMemoryUsage(usage);
+    };
+
+    updateMemoryUsage();
+    
+    // Only set up interval in non-test environments to prevent memory leaks during testing
+    const interval = typeof process !== 'undefined' && process.env.NODE_ENV !== 'test' 
+      ? setInterval(updateMemoryUsage, 5000) 
+      : null;
+    
+    return () => {
+      if (interval) {
+        clearInterval(interval);
+      }
+    };
+  }, [processedData]);
+
+  // ============================================================================
+  // ERROR HANDLING FUNCTIONS
+  // ============================================================================
+  
+  const handleError = useCallback(async (error: DataTableError, operation?: () => Promise<any>) => {
+    if (enableErrorRecovery) {
+      try {
+        const recovery = await errorRecoveryManagerRef.current.handleError(error);
+        setErrorState(prev => ({
+          hasErrors: true,
+          errorCount: prev.errorCount + 1,
+          lastError: error,
+          fallbacksActive: [...prev.fallbacksActive, error.type],
+        }));
+        
+        if (operation) {
+          setLastFailedOperation(() => operation);
+        }
+        
+        onError?.(error);
+        return recovery;
+      } catch (recoveryError) {
+        console.error('Error recovery failed:', recoveryError);
+      }
+    }
+    throw error;
+  }, [enableErrorRecovery, onError]);
+
+  const retryLastOperation = useCallback(async () => {
+    if (lastFailedOperation) {
+      try {
+        await lastFailedOperation();
+        setLastFailedOperation(null);
+        setErrorState(prev => ({ ...prev, hasErrors: false }));
+      } catch (error) {
+        console.error('Retry failed:', error);
+      }
+    }
+  }, [lastFailedOperation]);
+
+  const clearErrors = useCallback(() => {
+    setErrorState({
+      hasErrors: false,
+      errorCount: 0,
+      lastError: null,
+      fallbacksActive: [],
+    });
+    setLastFailedOperation(null);
+    errorRecoveryManagerRef.current.clearErrorLog();
+  }, []);
+
+  // ============================================================================
+  // CLEANUP
+  // ============================================================================
+  
+  const cleanup = useCallback(() => {
+    chunkManagerRef.current?.clear();
+    visibilityTrackerRef.current?.destroy();
+    memoryMonitorRef.current?.stopMonitoring();
+  }, []);
+
+  useEffect(() => {
+    return cleanup;
+  }, [cleanup]);
+
+  // ============================================================================
+  // RETURN VALUES
+  // ============================================================================
+  
+  return {
+    // Performance state
+    paginationMode,
+    isVirtualized,
+    pageSizeOptions,
+    
+    // Data management
+    processedData,
+    totalCount,
+    isLoading,
+    
+    // Search functionality
+    searchQuery,
+    setSearchQuery,
+    searchResults,
+    
+    // Server-side functionality
+    fetchServerData,
+    serverData,
+    
+    // Performance monitoring
+    memoryUsage,
+    
+    // Error handling and recovery
+    errorState,
+    retryLastOperation,
+    clearErrors,
+    
+    // Cleanup
+    cleanup
+  };
+} 

package/src/hooks/useDataTableState.ts

@@ -0,0 +1,110 @@
+/**
+ * @file useDataTableState Hook
+ * @description Hook for managing DataTable state
+ */
+
+import { useState, useCallback, useMemo } from 'react';
+import type { SortingState, ColumnFiltersState, ExpandedState } from '@tanstack/react-table';
+
+export interface DataTableState {
+  sorting: SortingState;
+  columnFilters: ColumnFiltersState;
+  expanded: ExpandedState;
+  pageSize: number;
+  pageIndex: number;
+  selectedRows: string[];
+}
+
+export interface DataTableActions {
+  setSorting: (sorting: SortingState) => void;
+  setColumnFilters: (filters: ColumnFiltersState) => void;
+  setExpanded: (expanded: ExpandedState) => void;
+  setPageSize: (size: number) => void;
+  setPageIndex: (index: number) => void;
+  setSelectedRows: (rows: string[]) => void;
+  resetState: () => void;
+}
+
+export interface DataTableComputed {
+  paginatedData: any[];
+  totalPages: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+}
+
+export interface UseDataTableStateOptions {
+  initialPageSize?: number;
+  data: any[];
+}
+
+/**
+ * Hook for managing DataTable state
+ * @param options Configuration options
+ * @returns Object containing state, actions, and computed values
+ */
+export function useDataTableState(options: UseDataTableStateOptions) {
+  const { initialPageSize = 10, data } = options;
+
+  // State
+  const [sorting, setSorting] = useState<SortingState>([]);
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
+  const [expanded, setExpanded] = useState<ExpandedState>({});
+  const [pageSize, setPageSize] = useState(initialPageSize);
+  const [pageIndex, setPageIndex] = useState(0);
+  const [selectedRows, setSelectedRows] = useState<string[]>([]);
+
+  // Actions
+  const resetState = useCallback(() => {
+    setSorting([]);
+    setColumnFilters([]);
+    setExpanded({});
+    setPageSize(initialPageSize);
+    setPageIndex(0);
+    setSelectedRows([]);
+  }, [initialPageSize]);
+
+  // Computed values
+  const paginatedData = useMemo(() => {
+    const start = pageIndex * pageSize;
+    const end = start + pageSize;
+    return data.slice(start, end);
+  }, [data, pageIndex, pageSize]);
+
+  const totalPages = useMemo(() => {
+    return Math.ceil(data.length / pageSize);
+  }, [data.length, pageSize]);
+
+  const hasNextPage = useMemo(() => {
+    return pageIndex < totalPages - 1;
+  }, [pageIndex, totalPages]);
+
+  const hasPreviousPage = useMemo(() => {
+    return pageIndex > 0;
+  }, [pageIndex]);
+
+  return {
+    state: {
+      sorting,
+      columnFilters,
+      expanded,
+      pageSize,
+      pageIndex,
+      selectedRows
+    },
+    actions: {
+      setSorting,
+      setColumnFilters,
+      setExpanded,
+      setPageSize,
+      setPageIndex,
+      setSelectedRows,
+      resetState
+    },
+    computed: {
+      paginatedData,
+      totalPages,
+      hasNextPage,
+      hasPreviousPage
+    }
+  };
+}

package/src/hooks/useDebounce.ts

@@ -0,0 +1,18 @@
+
+import { useState, useEffect } from 'react';
+
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => {
+      clearTimeout(handler);
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+}

package/src/hooks/useFocusManagement.ts

@@ -0,0 +1,161 @@
+
+import { useRef, useCallback, useEffect } from 'react';
+
+export interface FocusManagementOptions {
+  trapFocus?: boolean;
+  autoFocus?: boolean;
+  restoreFocus?: boolean;
+  onEscape?: () => void;
+  onFocusFirst?: () => void;
+  onFocusLast?: () => void;
+}
+
+export interface FocusManagementReturn {
+  containerRef: React.RefObject<HTMLDivElement>;
+  focusRef: React.RefObject<HTMLElement>;
+  setFocus: (element: HTMLElement | null) => void;
+  focusFirst: () => void;
+  focusLast: () => void;
+  trapFocus: () => void;
+  releaseFocus: () => void;
+  getFocusableElements: () => HTMLElement[];
+  handleEscape: (callback: () => void) => () => void;
+}
+
+export function useFocusManagement(options: FocusManagementOptions = {}): FocusManagementReturn {
+  const { 
+    trapFocus = false, 
+    autoFocus = false, 
+    restoreFocus = false,
+    onEscape,
+    onFocusFirst,
+    onFocusLast 
+  } = options;
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const focusRef = useRef<HTMLElement | null>(null);
+  const previousFocusRef = useRef<HTMLElement | null>(null);
+  const trapFocusActiveRef = useRef<boolean>(false);
+
+  const setFocus = useCallback((element: HTMLElement | null) => {
+    focusRef.current = element;
+    element?.focus();
+  }, []);
+
+  const getFocusableElements = useCallback((): HTMLElement[] => {
+    if (!containerRef.current) return [];
+
+    return Array.from(
+      containerRef.current.querySelectorAll<HTMLElement>(
+        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+      )
+    ).filter((el) => !el.hasAttribute('disabled') && !el.hasAttribute('hidden'));
+  }, []);
+
+  const focusFirst = useCallback(() => {
+    const elements = getFocusableElements();
+    if (elements.length > 0) {
+      setFocus(elements[0]);
+      onFocusFirst?.();
+    }
+  }, [getFocusableElements, setFocus, onFocusFirst]);
+
+  const focusLast = useCallback(() => {
+    const elements = getFocusableElements();
+    if (elements.length > 0) {
+      setFocus(elements[elements.length - 1]);
+      onFocusLast?.();
+    }
+  }, [getFocusableElements, setFocus, onFocusLast]);
+
+  const trapFocusMethod = useCallback(() => {
+    trapFocusActiveRef.current = true;
+  }, []);
+
+  const releaseFocus = useCallback(() => {
+    trapFocusActiveRef.current = false;
+  }, []);
+
+  const handleEscape = useCallback((callback: () => void) => {
+    return () => {
+      const handleKeyDown = (event: KeyboardEvent) => {
+        if (event.key === 'Escape') {
+          callback();
+        }
+      };
+
+      document.addEventListener('keydown', handleKeyDown);
+      return () => document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, []);
+
+  // Handle focus trap
+  useEffect(() => {
+    if (!trapFocus || !containerRef.current) return;
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape' && onEscape) {
+        onEscape();
+        return;
+      }
+
+      if (event.key !== 'Tab') return;
+
+      const elements = getFocusableElements();
+      if (elements.length === 0) return;
+
+      const firstElement = elements[0];
+      const lastElement = elements[elements.length - 1];
+
+      if (event.shiftKey) {
+        if (document.activeElement === firstElement) {
+          event.preventDefault();
+          lastElement.focus();
+        }
+      } else {
+        if (document.activeElement === lastElement) {
+          event.preventDefault();
+          firstElement.focus();
+        }
+      }
+    };
+
+    const current = containerRef.current;
+    current.addEventListener('keydown', handleKeyDown);
+    return () => {
+      current?.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [trapFocus, onEscape, getFocusableElements]);
+
+  // Handle auto focus
+  useEffect(() => {
+    if (autoFocus) {
+      focusFirst();
+    }
+  }, [autoFocus, focusFirst]);
+
+  // Handle focus restoration
+  useEffect(() => {
+    if (!restoreFocus) return;
+
+    previousFocusRef.current = document.activeElement as HTMLElement;
+
+    return () => {
+      if (previousFocusRef.current) {
+        previousFocusRef.current.focus();
+      }
+    };
+  }, [restoreFocus]);
+
+  return {
+    containerRef,
+    focusRef,
+    setFocus,
+    focusFirst,
+    focusLast,
+    trapFocus: trapFocusMethod,
+    releaseFocus,
+    getFocusableElements,
+    handleEscape,
+  };
+}