@jmruthers/pace-core 0.6.1 → 0.6.2

package/src/components/DataTable/utils/debugTools.ts

@@ -14,9 +14,9 @@ import type {
 import { createLogger } from '../../../utils/core/logger';
 
 /**
- * Debug levels for controlling verbosity
+ * Debug levels for controlling verbosity (internal use only)
  */
-export enum DebugLevel {
+enum DebugLevel {
   NONE = 0,
   ERROR = 1,
   WARN = 2,
@@ -26,9 +26,9 @@ export enum DebugLevel {
 }
 
 /**
- * Performance debug configuration
+ * Performance debug configuration (internal use only)
  */
-export interface DebugConfig {
+interface DebugConfig {
   enabled: boolean;
   level: DebugLevel;
   logToConsole: boolean;
@@ -41,9 +41,9 @@ export interface DebugConfig {
 }
 
 /**
- * Default debug configuration
+ * Default debug configuration (internal use only)
  */
-export const DEFAULT_DEBUG_CONFIG: DebugConfig = {
+const DEFAULT_DEBUG_CONFIG: DebugConfig = {
   enabled: import.meta.env.MODE === 'development',
   level: DebugLevel.INFO,
   logToConsole: true,
@@ -56,9 +56,9 @@ export const DEFAULT_DEBUG_CONFIG: DebugConfig = {
 };
 
 /**
- * Debug log entry interface
+ * Debug log entry interface (internal use only)
  */
-export interface DebugLogEntry {
+interface DebugLogEntry {
   timestamp: number;
   level: DebugLevel;
   category: string;
@@ -70,9 +70,9 @@ export interface DebugLogEntry {
 }
 
 /**
- * Performance timeline entry
+ * Performance timeline entry (internal use only)
  */
-export interface PerformanceTimelineEntry {
+interface PerformanceTimelineEntry {
   id: string;
   operation: string;
   startTime: number;
@@ -83,9 +83,9 @@ export interface PerformanceTimelineEntry {
 }
 
 /**
- * Memory snapshot
+ * Memory snapshot (internal use only)
  */
-export interface MemorySnapshot {
+interface MemorySnapshot {
   timestamp: number;
   heapUsed: number;
   heapTotal: number;
@@ -94,9 +94,9 @@ export interface MemorySnapshot {
 }
 
 /**
- * Render performance data
+ * Render performance data (internal use only)
  */
-export interface RenderPerformanceData {
+interface RenderPerformanceData {
   componentName: string;
   renderCount: number;
   totalRenderTime: number;
@@ -106,9 +106,9 @@ export interface RenderPerformanceData {
 }
 
 /**
- * Advanced DataTable debugger
+ * Advanced DataTable debugger (internal use only)
  */
-export class DataTableDebugger {
+class DataTableDebugger {
   private config: DebugConfig
   private logger = createLogger('DataTableDebugger');
   private logEntries: DebugLogEntry[] = [];
@@ -469,104 +469,9 @@ export class DataTableDebugger {
 }
 
 /**
- * Global debugger instance
+ * Global debugger instance (internal use only)
  */
-export const dataTableDebugger = new DataTableDebugger();
-
-/**
- * Performance profiler decorator
- */
-export function profile(operation: string) {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
-    const originalMethod = descriptor.value;
-
-    descriptor.value = async function (this: unknown, ...args: unknown[]) {
-      const operationId = `${target.constructor.name}.${propertyKey}_${Date.now()}`;
-      
-      dataTableDebugger.startOperation(operationId, operation, {
-        className: target.constructor.name,
-        methodName: propertyKey,
-        args: args.length,
-      });
-
-      try {
-        const result = await originalMethod.apply(this, args);
-        dataTableDebugger.endOperation(operationId, { success: true });
-        return result;
-      } catch (error) {
-        dataTableDebugger.endOperation(operationId, { success: false, error: error instanceof Error ? error.message : String(error) });
-        dataTableDebugger.log(DebugLevel.ERROR, 'Performance', `Operation failed: ${operation}`, error);
-        throw error;
-      }
-    };
-
-    return descriptor;
-  };
-}
-
-/**
- * Memory monitoring utility
- */
-export class MemoryMonitor {
-  private debuggerInstance: DataTableDebugger;
-  private intervalId: NodeJS.Timeout | null = null;
-
-  constructor(debuggerInstance: DataTableDebugger = dataTableDebugger) {
-    this.debuggerInstance = debuggerInstance;
-  }
-
-  start(interval: number = 5000): void {
-    this.stop(); // Stop any existing monitoring
-    
-    this.intervalId = setInterval(() => {
-      this.debuggerInstance.takeMemorySnapshot('periodic');
-    }, interval);
-  }
-
-  stop(): void {
-    if (this.intervalId) {
-      clearInterval(this.intervalId);
-      this.intervalId = null;
-    }
-  }
-}
-
-/**
- * Performance monitoring React hook
- */
-export function usePerformanceDebugger(componentName: string) {
-  const startTime = React.useRef<number>(0);
-
-  React.useEffect(() => {
-    startTime.current = performance.now();
-    
-    return () => {
-      const renderTime = performance.now() - startTime.current;
-      dataTableDebugger.trackRender(componentName, renderTime);
-    };
-  });
-
-  const trackOperation = React.useCallback((operation: string, fn: () => unknown) => {
-    const operationId = `${componentName}_${operation}_${Date.now()}`;
-    dataTableDebugger.startOperation(operationId, operation);
-    
-    try {
-      const result = fn();
-      dataTableDebugger.endOperation(operationId);
-      return result;
-    } catch (error) {
-      dataTableDebugger.endOperation(operationId, { error: error instanceof Error ? error.message : String(error) });
-      throw error;
-    }
-  }, [componentName]);
-
-  return {
-    trackOperation,
-    log: (level: DebugLevel, message: string, data?: unknown) => 
-      dataTableDebugger.log(level, componentName, message, data),
-  };
-}
+const dataTableDebugger = new DataTableDebugger();
 
 /**
  * Development tools integration

package/src/components/DataTable/utils/errorHandling.ts

@@ -23,6 +23,10 @@ export enum DataTableErrorType {
   MEMORY = 'memory'
 }
 
+/**
+ * Custom error class for DataTable operations.
+ * Provides error type and recoverability information.
+ */
 export class DataTableError extends Error {
   constructor(
     message: string,
@@ -34,6 +38,10 @@ export class DataTableError extends Error {
   }
 }
 
+/**
+ * Error recovery manager for DataTable.
+ * Handles error recovery strategies and error logging.
+ */
 export class ErrorRecoveryManager {
   constructor(private config: FallbackConfig) {}
   
@@ -46,6 +54,10 @@ export class ErrorRecoveryManager {
   }
 }
 
+/**
+ * Memory monitor for DataTable.
+ * Tracks memory usage and provides warnings when thresholds are exceeded.
+ */
 export class MemoryMonitor {
   constructor(private threshold: number = 100) {}
   

package/src/components/DataTable/utils/exportUtils.ts

@@ -333,6 +333,15 @@ export async function exportToCSVWithTableRows(
  * - Triggers browser download
  * - Throws error if export fails
  */
+/**
+ * Exports DataTable data to CSV format.
+ * Handles column mapping, data formatting, and browser download.
+ * 
+ * @template TData - The type of data records in the table
+ * @param data - Array of data records to export
+ * @param columns - Column definitions for export
+ * @param filename - Name of the CSV file to download
+ */
 export function exportToCSV<TData extends DataRecord>(
   data: TData[],
   columns: ExportColumn[],

package/src/components/DataTable/utils/flexibleImport.ts

@@ -11,10 +11,18 @@
 import { createLogger } from '../../../utils/core/logger';
 import type { CellValue } from '../types';
 
+/**
+ * Column mapping interface for CSV import.
+ * Maps target field names to possible CSV column names.
+ */
 export interface ColumnMapping {
   [targetField: string]: string[];
 }
 
+/**
+ * Options for flexible CSV import.
+ * Configures column mapping, date parsing, validation, and other import settings.
+ */
 export interface ImportOptions {
   columnMappings?: ColumnMapping;
   dateFormats?: readonly string[];
@@ -160,6 +168,10 @@ export interface ImportError {
   message: string;
 }
 
+/**
+ * Import warning interface.
+ * Represents warnings encountered during CSV import.
+ */
 export interface ImportWarning {
   row: number;
   field: string;
@@ -609,54 +621,6 @@ export const commonMappings = {
   }
 };
 
-/**
- * Helper function to create import options with predefined date format sets
- */
-export function createImportOptions(options: Partial<ImportOptions> = {}): ImportOptions {
-  return {
-    dateFormats: DATE_FORMAT_SETS.ALL,
-    strictDateParsing: false,
-    ...options,
-  };
-}
-
-/**
- * Helper function to create import options for specific regions
- */
-export function createRegionalImportOptions(region: 'US' | 'EUROPEAN' | 'ISO' | 'NATURAL' | 'ALL', options: Partial<ImportOptions> = {}): ImportOptions {
-  return {
-    dateFormats: DATE_FORMAT_SETS[region],
-    strictDateParsing: false,
-    ...options,
-  };
-}
-
-/**
- * Helper function to test if a string can be parsed as a date
- */
-export function testDateParsing(dateStr: string, formats?: string[]): { success: boolean; parsedDate?: Date; matchedFormat?: string } {
-  if (!dateStr || typeof dateStr !== 'string') {
-    return { success: false };
-  }
-  
-  const testFormats = formats || DATE_FORMAT_SETS.ALL;
-  
-  for (const format of testFormats) {
-    // This is a simplified version of the parseDateWithFormat function
-    // In a real implementation, you'd want to reuse the actual parsing logic
-    try {
-      const date = new Date(dateStr);
-      if (!isNaN(date.getTime())) {
-        return { success: true, parsedDate: date, matchedFormat: 'native' };
-      }
-    } catch (error) {
-      // Continue to next format
-    }
-  }
-  
-  return { success: false };
-}
-
 /**
  * Helper function to get suggested date formats based on sample data
  */

package/src/components/DataTable/utils/paginationUtils.ts

@@ -121,6 +121,14 @@ export interface PaginationBinding {
  * });
  * ```
  */
+/**
+ * Creates a unified pagination binding that works across all pagination modes.
+ * Provides consistent pagination state and actions regardless of client/server/hybrid mode.
+ * 
+ * @template TData - The type of data records in the table
+ * @param config - Pagination binding configuration
+ * @returns Unified pagination state and actions
+ */
 export function getPaginationBinding<TData extends DataRecord>(
   config: PaginationBindingConfig<TData>
 ): PaginationBinding {

package/src/components/DataTable/utils/performanceUtils.ts

@@ -17,7 +17,7 @@ import type {
 // ============================================================================
 
 /**
- * Determines the optimal pagination mode based on dataset size
+ * Determines the optimal pagination mode based on dataset size.
  * 
  * IMPORTANT: This function NEVER returns 'server' mode - it only returns 'client' or 'hybrid'.
  * Server mode should ONLY be used when serverSide config is explicitly provided.
@@ -26,6 +26,10 @@ import type {
  * 
  * For large datasets (>10k rows), returns 'hybrid' which still uses client-side pagination
  * but with optimizations. If true server-side pagination is needed, serverSide config must be provided.
+ * 
+ * @param dataLength - Number of rows in the dataset
+ * @param serverSideThreshold - Threshold for switching to hybrid mode (default: 10000)
+ * @returns Optimal pagination mode ('client' or 'hybrid')
  */
 export function determinePaginationMode(
   dataLength: number,

package/src/components/Dialog/Dialog.tsx

@@ -43,10 +43,10 @@
  *     </DialogHeader>
  *     <DialogBody>
  *       <section className="space-y-4">
- *         <div className="grid grid-cols-4 items-center gap-4">
+ *         <fieldset className="grid grid-cols-4 items-center gap-4">
  *           <Label htmlFor="name" className="text-right">Name</Label>
  *           <Input id="name" defaultValue="John Doe" className="col-span-3" />
- *         </div>
+ *         </fieldset>
  *       </section>
  *     </DialogBody>
  *     <DialogFooter>

package/src/components/ErrorBoundary/ErrorBoundary.test.tsx

@@ -8,7 +8,8 @@ import React from 'react';
 import { screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { ErrorBoundary } from './ErrorBoundary';
+import { ErrorBoundary } from './index';
+import { ErrorBoundaryProvider } from './ErrorBoundaryContext';
 import { renderWithProviders } from '../../__tests__/helpers/test-utils';
 
 // Mock the performance budget monitor
@@ -778,4 +779,182 @@ describe('ErrorBoundary Component', () => {
     }
     vi.clearAllMocks();
   });
+
+  describe('Global Error Handler', () => {
+    it('uses global error handler when no onError prop is provided', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const globalErrorHandler = vi.fn();
+      
+      renderWithProviders(
+        <ErrorBoundaryProvider defaultErrorHandler={globalErrorHandler}>
+          <ErrorBoundary componentName="TestComponent">
+            <ThrowingComponent />
+          </ErrorBoundary>
+        </ErrorBoundaryProvider>
+      );
+      
+      await waitFor(() => {
+        expect(globalErrorHandler).toHaveBeenCalledTimes(1);
+        expect(globalErrorHandler).toHaveBeenCalledWith(
+          expect.any(Error),
+          expect.any(Object), // errorInfo
+          expect.any(String),  // errorId
+          'TestComponent'      // componentName
+        );
+      }, { interval: 10 });
+      
+      consoleSpy.mockRestore();
+    });
+
+    it('uses global error handler with default component name when componentName not provided', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const globalErrorHandler = vi.fn();
+      
+      renderWithProviders(
+        <ErrorBoundaryProvider defaultErrorHandler={globalErrorHandler}>
+          <ErrorBoundary>
+            <ThrowingComponent />
+          </ErrorBoundary>
+        </ErrorBoundaryProvider>
+      );
+      
+      await waitFor(() => {
+        expect(globalErrorHandler).toHaveBeenCalledTimes(1);
+        expect(globalErrorHandler).toHaveBeenCalledWith(
+          expect.any(Error),
+          expect.any(Object), // errorInfo
+          expect.any(String),  // errorId
+          'Unknown Component'  // componentName (default)
+        );
+      }, { interval: 10 });
+      
+      consoleSpy.mockRestore();
+    });
+
+    it('prefers onError prop over global error handler', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const globalErrorHandler = vi.fn();
+      const localErrorHandler = vi.fn();
+      
+      renderWithProviders(
+        <ErrorBoundaryProvider defaultErrorHandler={globalErrorHandler}>
+          <ErrorBoundary 
+            componentName="TestComponent"
+            onError={localErrorHandler}
+          >
+            <ThrowingComponent />
+          </ErrorBoundary>
+        </ErrorBoundaryProvider>
+      );
+      
+      await waitFor(() => {
+        expect(localErrorHandler).toHaveBeenCalledTimes(1);
+        expect(globalErrorHandler).not.toHaveBeenCalled();
+      }, { interval: 10 });
+      
+      consoleSpy.mockRestore();
+    });
+
+    it('does not call global handler when ErrorBoundary is not wrapped in provider', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const globalErrorHandler = vi.fn();
+      
+      // Render without provider
+      renderWithProviders(
+        <ErrorBoundary componentName="TestComponent">
+          <ThrowingComponent />
+        </ErrorBoundary>
+      );
+      
+      await waitFor(() => {
+        expect(screen.getByText('Error in TestComponent')).toBeInTheDocument();
+      }, { interval: 10 });
+      
+      // Global handler should not be called since there's no provider
+      expect(globalErrorHandler).not.toHaveBeenCalled();
+      
+      consoleSpy.mockRestore();
+    });
+
+    it('works with nested ErrorBoundary providers (inner provider overrides outer)', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const outerErrorHandler = vi.fn();
+      const innerErrorHandler = vi.fn();
+      
+      renderWithProviders(
+        <ErrorBoundaryProvider defaultErrorHandler={outerErrorHandler}>
+          <ErrorBoundary componentName="Outer">
+            <ErrorBoundaryProvider defaultErrorHandler={innerErrorHandler}>
+              <ErrorBoundary componentName="Inner">
+                <ThrowingComponent />
+              </ErrorBoundary>
+            </ErrorBoundaryProvider>
+          </ErrorBoundary>
+        </ErrorBoundaryProvider>
+      );
+      
+      await waitFor(() => {
+        expect(innerErrorHandler).toHaveBeenCalledTimes(1);
+        expect(innerErrorHandler).toHaveBeenCalledWith(
+          expect.any(Error),
+          expect.any(Object),
+          expect.any(String),
+          'Inner'
+        );
+        // Outer handler should not be called for inner boundary
+        expect(outerErrorHandler).not.toHaveBeenCalled();
+      }, { interval: 10 });
+      
+      consoleSpy.mockRestore();
+    });
+
+    it('allows ErrorBoundaryProvider without defaultErrorHandler (no-op)', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      
+      renderWithProviders(
+        <ErrorBoundaryProvider>
+          <ErrorBoundary componentName="TestComponent">
+            <ThrowingComponent />
+          </ErrorBoundary>
+        </ErrorBoundaryProvider>
+      );
+      
+      await waitFor(() => {
+        expect(screen.getByText('Error in TestComponent')).toBeInTheDocument();
+      }, { interval: 10 });
+      
+      // Should render error UI without calling any handler
+      expect(screen.getByText('Error in TestComponent')).toBeInTheDocument();
+      
+      consoleSpy.mockRestore();
+    });
+
+    it('passes correct error information to global handler', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const globalErrorHandler = vi.fn();
+      const testError = new Error('Custom test error');
+      
+      renderWithProviders(
+        <ErrorBoundaryProvider defaultErrorHandler={globalErrorHandler}>
+          <ErrorBoundary componentName="TestComponent">
+            <ThrowingComponent errorMessage="Custom test error" />
+          </ErrorBoundary>
+        </ErrorBoundaryProvider>
+      );
+      
+      await waitFor(() => {
+        expect(globalErrorHandler).toHaveBeenCalledTimes(1);
+        const callArgs = globalErrorHandler.mock.calls[0];
+        expect(callArgs[0]).toBeInstanceOf(Error);
+        expect(callArgs[0].message).toBe('Custom test error');
+        expect(callArgs[1]).toBeDefined(); // errorInfo
+        expect(callArgs[1].componentStack).toBeDefined();
+        expect(typeof callArgs[2]).toBe('string'); // errorId
+        expect(callArgs[2]).toMatch(/^error_/); // errorId format
+        expect(callArgs[3]).toBe('TestComponent'); // componentName
+      }, { interval: 10 });
+      
+      consoleSpy.mockRestore();
+    });
+  });
 });

package/src/components/ErrorBoundary/ErrorBoundary.tsx

@@ -25,10 +25,35 @@
  *   <MyComponent />
  * </ErrorBoundary>
  * 
+ * // Using global error handler (recommended for applications)
+ * import { ErrorBoundaryProvider, ErrorBoundary } from '@jmruthers/pace-core';
+ * 
+ * // Setup once in main.tsx
+ * <ErrorBoundaryProvider
+ *   defaultErrorHandler={(error, errorInfo, errorId, componentName) => {
+ *     if (import.meta.env.DEV) {
+ *       console.error(`[${componentName}] ErrorBoundary caught error:`, error, errorInfo);
+ *     }
+ *     errorTracking.captureException(error, {
+ *       componentStack: errorInfo.componentStack,
+ *       errorBoundary: true,
+ *       errorId,
+ *       componentName,
+ *     });
+ *   }}
+ * >
+ *   <App />
+ * </ErrorBoundaryProvider>
+ * 
+ * // Then use ErrorBoundary without onError prop - uses global handler
+ * <ErrorBoundary componentName="AppRoot">
+ *   <AppContent />
+ * </ErrorBoundary>
+ * 
  * // Error boundary with custom fallback
  * <ErrorBoundary
  *   componentName="UserProfile"
- *   fallback={<div>Something went wrong loading the profile.</div>}
+ *   fallback={<section>Something went wrong loading the profile.</section>}
  *   onError={(error, errorInfo, errorId) => {
  *     console.log('Error caught:', errorId, error);
  *   }}
@@ -58,6 +83,16 @@
  *   </ErrorBoundary>
  *   <Footer />
  * </ErrorBoundary>
+ * 
+ * // Per-instance onError overrides global handler
+ * <ErrorBoundary 
+ *   componentName="SpecialCase"
+ *   onError={(error, errorInfo, errorId) => {
+ *     // Custom handling for this specific case - global handler won't be called
+ *   }}
+ * >
+ *   <SpecialComponent />
+ * </ErrorBoundary>
  * ```
  *
  * @accessibility
@@ -120,6 +155,8 @@ export interface ErrorBoundaryProps {
   enableRetry?: boolean;
   /** Whether to enable error reporting */
   enableReporting?: boolean;
+  /** Internal: Global error handler from context (not part of public API) */
+  _globalErrorHandler?: (error: Error, errorInfo: React.ErrorInfo, errorId: string, componentName: string) => void;
 }
 
 /**
@@ -162,15 +199,16 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
   componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
     const { componentName = 'Unknown Component', onError, enableReporting = true } = this.props;
     const errorId = this.state.errorId!;
+    const componentNameForHandler = componentName || 'Unknown Component';
     
     this.setState({ errorInfo });
     
     // Enhanced logging with component name and error ID
-    logger.error('ErrorBoundary', `[${componentName}] Caught error ${errorId}:`, error, errorInfo);
+    logger.error('ErrorBoundary', `[${componentNameForHandler}] Caught error ${errorId}:`, error, errorInfo);
     
     // Performance monitoring - track error occurrence
     performanceBudgetMonitor.measure('ERROR_BOUNDARY_TRIGGER', 1, {
-      componentName,
+      componentName: componentNameForHandler,
       errorId,
       errorMessage: error.message,
       stack: error.stack?.substring(0, 200), // Truncated stack trace
@@ -178,12 +216,14 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
 
     // Report error if enabled
     if (enableReporting) {
-      this.reportError(errorId, componentName);
+      this.reportError(errorId, componentNameForHandler);
     }
     
-    // Call custom error handler if provided
+    // Call error handler: prefer prop onError, fall back to global handler from props
     if (onError) {
       onError(error, errorInfo, errorId);
+    } else if (this.props._globalErrorHandler) {
+      this.props._globalErrorHandler(error, errorInfo, errorId, componentNameForHandler);
     }
   }