@jmruthers/pace-core 0.5.193 → 0.6.2

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
@@ -75,7 +110,7 @@
  * - Configurable error reporting
  *
  * @dependencies
- * - React 18+ - Component lifecycle
+ * - React 19+ - Component lifecycle
  * - Performance monitoring utilities
  * - Tailwind CSS - Styling
  */
@@ -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);
     }
   }
 

package/src/components/ErrorBoundary/ErrorBoundaryContext.tsx

@@ -0,0 +1,129 @@
+/**
+ * @file Error Boundary Context
+ * @package @jmruthers/pace-core
+ * @module Components/ErrorBoundary
+ * @since 0.6.2
+ *
+ * Context provider for global error handler configuration in ErrorBoundary components.
+ * Allows applications to register a default error handler once, which is then used by
+ * all ErrorBoundary instances unless overridden.
+ *
+ * @example
+ * ```tsx
+ * // 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>
+ *
+ * // Usage - no onError needed, uses global handler
+ * <ErrorBoundary componentName="AppRoot">
+ *   <AppContent />
+ * </ErrorBoundary>
+ * ```
+ */
+
+import React, { createContext, useContext, ReactNode } from 'react';
+
+/**
+ * Type definition for the global error handler function
+ * @public
+ */
+export type GlobalErrorHandler = (
+  error: Error,
+  errorInfo: React.ErrorInfo,
+  errorId: string,
+  componentName: string
+) => void;
+
+/**
+ * Context value type for ErrorBoundary configuration
+ * @internal
+ */
+interface ErrorBoundaryContextType {
+  /** Global error handler that will be used by all ErrorBoundary instances */
+  defaultErrorHandler?: GlobalErrorHandler;
+}
+
+/**
+ * Context for ErrorBoundary global configuration
+ * @internal
+ */
+const ErrorBoundaryContext = createContext<ErrorBoundaryContextType | undefined>(undefined);
+
+/**
+ * Props for ErrorBoundaryProvider component
+ * @public
+ */
+export interface ErrorBoundaryProviderProps {
+  /** Children to wrap with the provider */
+  children: ReactNode;
+  /** Global error handler that will be used by all ErrorBoundary instances unless overridden */
+  defaultErrorHandler?: GlobalErrorHandler;
+}
+
+/**
+ * Provider component for ErrorBoundary global error handler configuration
+ * 
+ * Wrap your application with this provider to set a default error handler that will
+ * be used by all ErrorBoundary instances unless they provide their own onError prop.
+ * 
+ * @example
+ * ```tsx
+ * <ErrorBoundaryProvider
+ *   defaultErrorHandler={(error, errorInfo, errorId, componentName) => {
+ *     errorTracking.captureException(error, {
+ *       componentStack: errorInfo.componentStack,
+ *       errorBoundary: true,
+ *       errorId,
+ *       componentName,
+ *     });
+ *   }}
+ * >
+ *   <App />
+ * </ErrorBoundaryProvider>
+ * ```
+ * 
+ * @public
+ */
+/**
+ * Error boundary provider component.
+ * Provides global error handling configuration to child ErrorBoundary components.
+ * 
+ * @param props - Error boundary provider configuration
+ * @returns The error boundary provider
+ */
+export function ErrorBoundaryProvider({
+  children,
+  defaultErrorHandler,
+}: ErrorBoundaryProviderProps) {
+  const contextValue: ErrorBoundaryContextType = {
+    defaultErrorHandler,
+  };
+
+  return (
+    <ErrorBoundaryContext.Provider value={contextValue}>
+      {children}
+    </ErrorBoundaryContext.Provider>
+  );
+}
+
+/**
+ * Hook to access ErrorBoundary context
+ * @internal
+ */
+export function useErrorBoundaryContext(): ErrorBoundaryContextType | undefined {
+  return useContext(ErrorBoundaryContext);
+}
+

package/src/components/ErrorBoundary/index.ts

@@ -2,7 +2,32 @@
  * @file Error Boundary exports
  */
 
-export { ErrorBoundary } from './ErrorBoundary';
+// Re-export ErrorBoundary with automatic context support
+import { ErrorBoundary as ErrorBoundaryClass } from './ErrorBoundary';
+import { useErrorBoundaryContext } from './ErrorBoundaryContext';
+import React from 'react';
+import type { ErrorBoundaryProps } from './ErrorBoundary';
+
+// Export types and provider
 export type { ErrorBoundaryProps, ErrorBoundaryState } from './ErrorBoundary';
-import { ErrorBoundary } from './ErrorBoundary';
+export { ErrorBoundaryProvider } from './ErrorBoundaryContext';
+export type { ErrorBoundaryProviderProps, GlobalErrorHandler } from './ErrorBoundaryContext';
+
+/**
+ * ErrorBoundary component with automatic context support
+ * This wrapper automatically uses the global error handler from ErrorBoundaryProvider
+ * if no onError prop is provided.
+ */
+export const ErrorBoundary = React.forwardRef<
+  ErrorBoundaryClass,
+  Omit<ErrorBoundaryProps, '_globalErrorHandler'>
+>((props, ref) => {
+  const context = useErrorBoundaryContext();
+  const globalErrorHandler = context?.defaultErrorHandler;
+  
+  return React.createElement(ErrorBoundaryClass, { ...props, ref, _globalErrorHandler: globalErrorHandler });
+});
+
+ErrorBoundary.displayName = 'ErrorBoundary';
+
 export default ErrorBoundary;

package/src/components/EventSelector/EventSelector.tsx

@@ -80,7 +80,7 @@
  * - Button component - Retry functionality
  * - Alert component - Error display
  * - LoadingSpinner - Loading states
- * - React 18+ - Hooks and effects
+ * - React 19+ - Hooks and effects
  * - Tailwind CSS - Styling
  */
 
@@ -95,6 +95,9 @@ import { useEffect, useMemo, useRef } from 'react';
 import { cn } from '../../utils/core/cn';
 import { logger } from '../../utils/core/logger';
 
+/**
+ * Props for the EventSelector component.
+ */
 export interface EventSelectorProps {
   /** Placeholder text for the dropdown */
   placeholder?: string;

package/src/components/FileDisplay/FileDisplay.test.tsx

@@ -49,7 +49,7 @@ vi.mock('../../utils/storage/helpers', () => ({
 }));
 
 // Helper to render with UnifiedAuthProvider
-const renderWithUnifiedAuth = (ui: React.ReactElement) => {
+const renderWithUnifiedAuth = (ui: React.ReactElement<any>) => {
   return renderWithProviders(
     <UnifiedAuthProvider
       supabaseClient={supabase} 
@@ -64,7 +64,7 @@ const renderWithUnifiedAuth = (ui: React.ReactElement) => {
   );
 };
 
-const renderWithPublicContext = (ui: React.ReactElement, value: any = null) => {
+const renderWithPublicContext = (ui: React.ReactElement<any>, value: any = null) => {
   const Context = publicPageContextStore.value ?? React.createContext(null);
 
   return renderWithProviders(

package/src/components/FileDisplay/FileDisplay.tsx

@@ -192,10 +192,15 @@ function FileDisplayContent({
 
   const handleDeleteConfirm = async () => {
     setDeleteDialogOpen(false);
-    if (onDelete) {
-      await onDelete();
+    try {
+      if (onDelete) {
+        await onDelete();
+      }
+      setImageError(false);
+    } catch (error) {
+      // Error handling is delegated to onDelete callback
+      setImageError(false);
     }
-    setImageError(false);
   };
 
   const handleImageError = () => {
@@ -773,16 +778,10 @@ function FileDisplayAuthenticated({
 }: FileDisplayProps) {
   const { supabase } = useUnifiedAuth();
 
-  if (!supabase) {
-    return (
-      <figure className={className} title="Error">
-        <p className={getFallbackClasses(fallbackSize || 'md')}>
-          Supabase client not available in authenticated context
-        </p>
-      </figure>
-    );
-  }
+  // Consolidated state for displayOnly mode - must be before early return
+  const [displayOnlyFileReference, setDisplayOnlyFileReference] = useState<FileReference | null>(null);
 
+  // Call hooks before any early returns - hooks must handle null supabase gracefully
   const {
     fileUrl,
     fileReference,
@@ -797,20 +796,17 @@ function FileDisplayAuthenticated({
     record_id,
     organisation_id,
     category,
-    { supabase }
+    { supabase: supabase || null }
   );
-
-  // Consolidated state for displayOnly mode
-  const [displayOnlyFileReference, setDisplayOnlyFileReference] = useState<FileReference | null>(null);
   
   // Use fileUrls map if available, otherwise use useFileUrl hook
   const displayOnlyFileUrlFromMap = displayOnlyFileReference ? fileUrls.get(displayOnlyFileReference.id) : null;
   const displayOnlyFileUrlHook = useFileUrl(
     displayOnlyFileReference && !displayOnlyFileUrlFromMap ? displayOnlyFileReference : null,
     {
-      supabase,
+      supabase: supabase || null,
       organisation_id,
-      autoLoad: !displayOnlyFileUrlFromMap && !!displayOnlyFileReference
+      autoLoad: !displayOnlyFileUrlFromMap && !!displayOnlyFileReference && !!supabase
     }
   );
   const displayOnlyFileUrl = displayOnlyFileUrlFromMap || displayOnlyFileUrlHook.url;
@@ -831,6 +827,17 @@ function FileDisplayAuthenticated({
     }
   }, [displayOnly, category, fileReferences, fileUrls]);
 
+  // Early return check after all hooks are called
+  if (!supabase) {
+    return (
+      <figure className={className} title="Error">
+        <p className={getFallbackClasses(fallbackSize || 'md')}>
+          Supabase client not available in authenticated context
+        </p>
+      </figure>
+    );
+  }
+
   // Delete operation - implementation pending
   const handleDelete = async () => {
     // TODO: Implement delete via FileReferenceService when delete functionality is needed
@@ -906,6 +913,13 @@ function FileDisplayAuthenticated({
  * @param props.category - Optional category filter. When specified, only displays files matching this category and uses single file display variant.
  * @returns React element with file display
  */
+/**
+ * File display component.
+ * Renders files from the file reference system with support for previews, downloads, and public/private access.
+ * 
+ * @param props - File display configuration
+ * @returns The rendered file display
+ */
 export function FileDisplay({
   table_name,
   record_id,

package/src/components/FileUpload/FileUpload.tsx

@@ -15,6 +15,10 @@ import { getCurrentAppName } from '../../utils/app/appNameResolver';
 import { getAppId } from '../../utils/app/appIdResolver';
 import { assertAppId } from '../../types/core';
 
+/**
+ * Props for the FileUpload component.
+ * Configures file upload behavior including storage location, validation, and callbacks.
+ */
 export interface FileUploadProps {
   supabase: SupabaseClient;
   table_name: string;
@@ -71,6 +75,15 @@ export function FileUpload({
   onProgress,
   children
 }: FileUploadProps) {
+  // Validate pageContext early - required prop
+  if (!pageContext) {
+    const errorMsg = 'pageContext is required for FileUpload component. This is used for permission checks.';
+    if (import.meta.env.MODE === 'development') {
+      console.error('[FileUpload]', errorMsg);
+    }
+    throw new Error(errorMsg);
+  }
+
   const [isDragging, setIsDragging] = useState(false);
   const [uploadStates, setUploadStates] = useState<Map<string, FileUploadState>>(new Map());
   const [resolvedAppId, setResolvedAppId] = useState<string | null>(app_id || null);
@@ -286,6 +299,12 @@ export function FileUpload({
           throw new Error(errorMsg);
         }
 
+        // Validate pageContext before upload
+        if (!pageContext) {
+          const errorMsg = 'pageContext is required for file upload. This is used for permission checks.';
+          throw new Error(errorMsg);
+        }
+
         const result = await uploadFile({
           table_name,
           record_id,
@@ -294,7 +313,7 @@ export function FileUpload({
           app_id: resolvedAppId ? assertAppId(resolvedAppId) : assertAppId(''),
           category,
           folder,
-          pageContext,
+          pageContext: pageContext,
           event_id,
           is_public: isPublic
         }, file);
@@ -393,7 +412,7 @@ export function FileUpload({
         onUploadError?.(errorMessage, file);
       }
     }
-  }, [uploadFile, table_name, record_id, organisation_id, resolvedAppId, category, folder, isPublic, maxSize, onUploadSuccess, onUploadError, onProgress, validateFile, generatePreview, showPreview, appIdError]);
+  }, [uploadFile, table_name, record_id, organisation_id, resolvedAppId, category, folder, isPublic, maxSize, onUploadSuccess, onUploadError, onProgress, validateFile, generatePreview, showPreview, appIdError, pageContext]);
 
   const handleDragOver = useCallback((e: React.DragEvent) => {
     e.preventDefault();
@@ -475,6 +494,7 @@ export function FileUpload({
               className="hidden"
               disabled={isDisabled}
               data-testid="file-input"
+              aria-label={accept ? `Upload file${multiple ? 's' : ''} (${accept})` : `Upload file${multiple ? 's' : ''}`}
             />
             <div className="text-sec-600">
               {isResolvingAppId ? (

package/src/components/Footer/Footer.test.tsx

@@ -82,7 +82,7 @@ describe('Footer Component', () => {
     it('renders with children content', () => {
       renderWithProviders(
         <Footer>
-          <div data-testid="custom-content">Custom footer content</div>
+          <section data-testid="custom-content">Custom footer content</section>
         </Footer>
       );
       
@@ -163,7 +163,7 @@ describe('Footer Component', () => {
     it('renders content in proper semantic structure', () => {
       renderWithProviders(
         <Footer>
-          <div>Custom content</div>
+          <section>Custom content</section>
         </Footer>
       );
       
@@ -175,7 +175,7 @@ describe('Footer Component', () => {
     it('renders logo before children content', () => {
       renderWithProviders(
         <Footer logo="/logo.png">
-          <div data-testid="children">Children content</div>
+          <section data-testid="children">Children content</section>
         </Footer>
       );
       
@@ -189,7 +189,7 @@ describe('Footer Component', () => {
     it('renders copyright text after children content', () => {
       renderWithProviders(
         <Footer>
-          <div data-testid="children">Children content</div>
+          <section data-testid="children">Children content</section>
         </Footer>
       );
       
@@ -380,7 +380,7 @@ describe('Footer Component', () => {
           logo="/test-logo.png"
           copyright="Custom copyright text"
         >
-          <div>Test children</div>
+          <section>Test children</section>
         </Footer>
       );
       
@@ -398,27 +398,27 @@ describe('Footer Component', () => {
     it('works with complex children content', () => {
       renderWithProviders(
         <Footer>
-          <div className="grid grid-cols-1 md:grid-cols-3 gap-8 mb-8">
-            <div>
+          <section className="grid grid-cols-1 md:grid-cols-3 gap-8 mb-8">
+            <section>
               <h3 className="font-semibold mb-2">About Us</h3>
               <p className="text-sm text-muted-foreground">
                 We provide innovative solutions for modern businesses.
               </p>
-            </div>
-            <div>
+            </section>
+            <section>
               <h3 className="font-semibold mb-2">Contact</h3>
               <p className="text-sm text-muted-foreground">
                 Email: info@company.com
               </p>
-            </div>
-            <div>
+            </section>
+            <section>
               <h3 className="font-semibold mb-2">Follow Us</h3>
-              <div className="flex gap-2">
+              <nav className="flex gap-2">
                 <a href="#" className="text-muted-foreground hover:text-foreground">Twitter</a>
                 <a href="#" className="text-muted-foreground hover:text-foreground">LinkedIn</a>
-              </div>
-            </div>
-          </div>
+              </nav>
+            </section>
+          </section>
         </Footer>
       );
       
@@ -463,7 +463,7 @@ describe('Footer Component', () => {
           logo="/logo.png"
           className="custom-footer"
         >
-          <div data-testid="custom-content">Custom footer content</div>
+          <section data-testid="custom-content">Custom footer content</section>
         </Footer>
       );
       

package/src/components/Footer/Footer.tsx

@@ -47,28 +47,28 @@
  * 
  * // Footer with custom content
  * <Footer companyName="My Company">
- *   <div className="grid grid-cols-1 md:grid-cols-3 gap-8 mb-8">
- *     <div>
+ *   <section className="grid grid-cols-1 md:grid-cols-3 gap-8 mb-8">
+ *     <section>
  *       <h3 className="font-semibold mb-2">About Us</h3>
  *       <p className="text-sm text-muted-foreground">
  *         We provide innovative solutions for modern businesses.
  *       </p>
- *     </div>
- *     <div>
+ *     </section>
+ *     <section>
  *       <h3 className="font-semibold mb-2">Contact</h3>
  *       <p className="text-sm text-muted-foreground">
  *         Email: info@mycompany.com<br />
  *         Phone: (555) 123-4567
  *       </p>
- *     </div>
- *     <div>
+ *     </section>
+ *     <section>
  *       <h3 className="font-semibold mb-2">Follow Us</h3>
- *       <div className="flex gap-2">
+ *       <nav className="flex gap-2">
  *         <a href="#" className="text-muted-foreground hover:text-foreground">Twitter</a>
  *         <a href="#" className="text-muted-foreground hover:text-foreground">LinkedIn</a>
- *       </div>
- *     </div>
- *   </div>
+ *       </nav>
+ *     </section>
+ *   </section>
  * </Footer>
  * ```
  *
@@ -81,12 +81,15 @@
  * - Clear link identification
  *
  * @dependencies
- * - React 18+ - Component framework
+ * - React 19+ - Component framework
  * - Tailwind CSS - Styling
  */
 import React from 'react';
 import { cn } from '../../utils/core/cn';
 
+/**
+ * Props for the Footer component.
+ */
 export interface FooterProps {
   /**
    * Company or organization name
@@ -138,7 +141,7 @@ export interface FooterProps {
  * 
  * // With children
  * <Footer>
- *   <div>Custom footer content</div>
+ *   <section>Custom footer content</section>
  * </Footer>
  * 
  * // With logo and copyright