@jmruthers/pace-core 0.6.1 → 0.6.3

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);
     }
   }
 

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/FileDisplay/FileDisplay.tsx

@@ -125,7 +125,7 @@ interface FileDisplayContentProps {
   showMetadata?: boolean;
 }
 
-function FileDisplayContent({
+const FileDisplayContent = React.memo(function FileDisplayContent({
   isLoading,
   error,
   fileUrl,
@@ -156,6 +156,29 @@ function FileDisplayContent({
   const [internalFileUrls, setInternalFileUrls] = useState<Map<string, string>>(new Map(fileUrls));
   const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
   const fileReferencesRef = useRef<FileReference[]>([]);
+  const imgRef = useRef<HTMLImageElement | null>(null);
+  const currentSrcRef = useRef<string | null>(null);
+  const isImageLoadingRef = useRef(false);
+
+  // Stabilize fileUrl to prevent unnecessary image reloads
+  // This prevents NS_BINDING_ABORTED errors when the component re-renders
+  const stableFileUrl = useMemo(() => fileUrl, [fileUrl]);
+
+  // Track when image starts loading to prevent cancellation
+  const handleImageLoadStart = useCallback(() => {
+    isImageLoadingRef.current = true;
+    if (stableFileUrl) {
+      currentSrcRef.current = stableFileUrl;
+    }
+  }, [stableFileUrl]);
+
+  // Track when image finishes loading
+  const handleImageLoad = useCallback(() => {
+    isImageLoadingRef.current = false;
+    if (stableFileUrl) {
+      currentSrcRef.current = stableFileUrl;
+    }
+  }, [stableFileUrl]);
 
   // Compute fallback text
   const computedFallbackText = useMemo(() => {
@@ -192,10 +215,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 = () => {
@@ -323,7 +351,7 @@ function FileDisplayContent({
       }
       
       // Show loading skeleton if URL is not available yet
-      if (!fileUrl) {
+      if (!stableFileUrl) {
         return (
           <figure className={className || "max-w-full h-48"} title="Loading">
             <p className={fallbackClasses}>
@@ -336,10 +364,15 @@ function FileDisplayContent({
       return (
         <figure className={className || ""}>
           <img
-            src={fileUrl}
+            ref={imgRef}
+            key={fileReference.id}
+            src={stableFileUrl || undefined}
             alt={fileReference.file_metadata.fileName || 'File'}
             className={imgClassName || "object-cover size-full"}
             onError={handleImageError}
+            onLoadStart={handleImageLoadStart}
+            onLoad={handleImageLoad}
+            loading="lazy"
           />
         </figure>
       );
@@ -347,14 +380,14 @@ function FileDisplayContent({
     
     // Document link display when displayOnly is true and file is not an image
     // Render non-image files as clickable links that open in a new tab
-    if (displayOnly && !isImage && fileUrl && fileReference && !showDelete) {
+    if (displayOnly && !isImage && stableFileUrl && fileReference && !showDelete) {
       const fileName = fileReference.file_metadata?.fileName || 'Document';
       const ariaLabel = `Open ${fileName} in new tab`;
       
       return (
         <figure className={className}>
           <a
-            href={fileUrl}
+            href={stableFileUrl || undefined}
             target="_blank"
             rel="noopener noreferrer"
             aria-label={ariaLabel}
@@ -380,7 +413,7 @@ function FileDisplayContent({
     
     // Standard single file display with wrapper
     // For displayOnly mode, if fallback is enabled and there's no URL or image error, show fallback instead of folder icon
-    if (displayOnly && showFallback && (!fileUrl || imageError || !isImage)) {
+    if (displayOnly && showFallback && (!stableFileUrl || imageError || !isImage)) {
       return (
         <figure className={className} title={fileReference.file_metadata.fileName || 'File'}>
           <p className={fallbackClasses}>
@@ -392,13 +425,15 @@ function FileDisplayContent({
     
     return (
       <figure className={`relative ${className}`}>
-        {isImage && fileUrl && !imageError ? (
+        {isImage && stableFileUrl && !imageError ? (
           <>
             <img
-              src={fileUrl}
+              key={fileReference.id}
+              src={stableFileUrl}
               alt={fileReference.file_metadata.fileName || 'File'}
               className={imgClassName || "object-cover size-full"}
               onError={handleImageError}
+              loading="lazy"
             />
             {showDelete && (
               <>
@@ -536,10 +571,12 @@ function FileDisplayContent({
           <figure key={fileRef.id} className="flex items-center space-x-3 p-3 bg-sec-50 rounded-lg border border-sec-200">
             {isImage && fileUrl ? (
               <img
-                src={fileUrl}
+                key={fileRef.id}
+                src={fileUrl || undefined}
                 alt={fileRef.file_metadata.fileName || 'File'}
                 className={imgClassName || "object-cover size-full"}
                 onError={handleImageError}
+                loading="lazy"
               />
             ) : (
               <span className="text-2xl">
@@ -591,7 +628,7 @@ function FileDisplayContent({
       {children}
     </figure>
   );
-}
+});
 
 /**
  * Internal component for public page context
@@ -773,16 +810,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 +828,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 +859,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 +945,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>
       );