@jmruthers/pace-core 0.6.1 → 0.6.3

package/src/hooks/useFileDisplay.ts

@@ -34,7 +34,7 @@
  * ```
  */
 
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useEffect, useCallback, useRef } from 'react';
 import type { SupabaseClient } from '@supabase/supabase-js';
 import { FileReference, FileCategory } from '../types/file-reference';
 import { getPublicUrl, getSignedUrl, generateFileUrlsBatch } from '../utils/storage/helpers';
@@ -71,6 +71,10 @@ function cleanupCache() {
   }
 }
 
+/**
+ * Return value of the useFileDisplay hook.
+ * Provides file URLs, references, loading state, error, and refetch function.
+ */
 export interface UseFileDisplayReturn {
   /** Single file URL if category is provided and file found, null otherwise */
   fileUrl: string | null;
@@ -134,14 +138,25 @@ export function useFileDisplay(
   const [isLoading, setIsLoading] = useState<boolean>(false);
   const [error, setError] = useState<Error | null>(null);
 
+  // Ref to track if component is mounted and effect is active
+  // This prevents state updates from stale async operations
+  const isMountedRef = useRef(true);
+
+  // Helper to safely set state only if component is still mounted
+  const safeSetState = <T,>(setter: (value: T) => void, value: T) => {
+    if (isMountedRef.current) {
+      setter(value);
+    }
+  };
+
   const fetchFiles = useCallback(async (): Promise<void> => {
     if (!table_name || !record_id || !supabase) {
-      setFileUrl(null);
-      setFileReference(null);
-      setFileReferences([]);
-      setFileUrls(new Map());
-      setFileCount(0);
-      setIsLoading(false);
+      safeSetState(setFileUrl, null);
+      safeSetState(setFileReference, null);
+      safeSetState(setFileReferences, []);
+      safeSetState(setFileUrls, new Map());
+      safeSetState(setFileCount, 0);
+      safeSetState(setIsLoading, false);
       return;
     }
 
@@ -173,13 +188,13 @@ export function useFileDisplay(
               expiresIn: 3600
             });
             const regeneratedUrl = signedUrlResult?.url || null;
-            setFileUrl(regeneratedUrl);
-            setFileReference(cachedData.fileReference);
-            setFileReferences(cachedData.fileReferences || []);
-            setFileUrls(cachedData.fileUrls || new Map());
-            setFileCount(cachedData.fileCount || 0);
-            setIsLoading(false);
-            setError(null);
+            safeSetState(setFileUrl, regeneratedUrl);
+            safeSetState(setFileReference, cachedData.fileReference);
+            safeSetState(setFileReferences, cachedData.fileReferences || []);
+            safeSetState(setFileUrls, cachedData.fileUrls || new Map());
+            safeSetState(setFileCount, cachedData.fileCount || 0);
+            safeSetState(setIsLoading, false);
+            safeSetState(setError, null);
             return;
           } catch (err) {
             // If signed URL regeneration fails, fall through to normal fetch
@@ -188,20 +203,20 @@ export function useFileDisplay(
         }
         
         // Normal cache hit for public files or files with URLs
-        setFileUrl(cachedData.fileUrl || null);
-        setFileReference(cachedData.fileReference || null);
-        setFileReferences(cachedData.fileReferences || []);
-        setFileUrls(cachedData.fileUrls || new Map());
-        setFileCount(cachedData.fileCount || 0);
-        setIsLoading(false);
-        setError(null);
+        safeSetState(setFileUrl, cachedData.fileUrl || null);
+        safeSetState(setFileReference, cachedData.fileReference || null);
+        safeSetState(setFileReferences, cachedData.fileReferences || []);
+        safeSetState(setFileUrls, cachedData.fileUrls || new Map());
+        safeSetState(setFileCount, cachedData.fileCount || 0);
+        safeSetState(setIsLoading, false);
+        safeSetState(setError, null);
         return;
       }
     }
 
     try {
-      setIsLoading(true);
-      setError(null);
+      safeSetState(setIsLoading, true);
+      safeSetState(setError, null);
 
       const service = createFileReferenceService(supabase);
       let files: FileReference[] = [];
@@ -481,11 +496,11 @@ export function useFileDisplay(
       }
 
       if (files.length === 0) {
-        setFileUrl(null);
-        setFileReference(null);
-        setFileReferences([]);
-        setFileUrls(new Map());
-        setFileCount(0);
+        safeSetState(setFileUrl, null);
+        safeSetState(setFileReference, null);
+        safeSetState(setFileReferences, []);
+        safeSetState(setFileUrls, new Map());
+        safeSetState(setFileCount, 0);
         
         // Cache empty result
         if (enableCache) {
@@ -499,14 +514,14 @@ export function useFileDisplay(
         return;
       }
 
-      setFileReferences(files);
-      setFileCount(files.length);
+      safeSetState(setFileReferences, files);
+      safeSetState(setFileCount, files.length);
 
       if (category && files.length > 0) {
         // Single file mode - get first file
         const firstFile = files[0];
         // Removed verbose debug logs - only log on errors
-        setFileReference(firstFile);
+        safeSetState(setFileReference, firstFile);
         
         // Generate URL based on file visibility
         let url: string | null = null;
@@ -529,7 +544,7 @@ export function useFileDisplay(
             });
           }
         }
-        setFileUrl(url);
+        safeSetState(setFileUrl, url);
       } else {
         // Multiple files mode - generate URLs for all files in batch
         const urlMap = await generateFileUrlsBatch(supabase, files, {
@@ -538,9 +553,9 @@ export function useFileDisplay(
               userId: organisation_id ? undefined : record_id,
               expiresIn: 3600
             });
-        setFileUrls(urlMap);
-        setFileReference(null);
-        setFileUrl(null);
+        safeSetState(setFileUrls, urlMap);
+        safeSetState(setFileReference, null);
+        safeSetState(setFileUrl, null);
       }
 
       // Cache the result
@@ -584,30 +599,46 @@ export function useFileDisplay(
     } catch (err) {
       logger.error('useFileDisplay', 'Error fetching files:', err);
       const error = err instanceof Error ? err : new Error('Unknown error occurred');
-      setError(error);
-      setFileUrl(null);
-      setFileReference(null);
-      setFileReferences([]);
-      setFileUrls(new Map());
-      setFileCount(0);
+      safeSetState(setError, error);
+      safeSetState(setFileUrl, null);
+      safeSetState(setFileReference, null);
+      safeSetState(setFileReferences, []);
+      safeSetState(setFileUrls, new Map());
+      safeSetState(setFileCount, 0);
     } finally {
-      setIsLoading(false);
+      safeSetState(setIsLoading, false);
     }
   }, [table_name, record_id, organisation_id, category, supabase, cacheTtl, enableCache]);
 
   // Fetch files when parameters change
   useEffect(() => {
+    // Mark as mounted when effect runs
+    isMountedRef.current = true;
+
     if (table_name && record_id && supabase) {
-      fetchFiles();
+      // Call fetchFiles - it will check isMountedRef before setting state
+      fetchFiles().catch((err) => {
+        // Only set error if component is still mounted
+        if (isMountedRef.current) {
+          safeSetState(setError, err instanceof Error ? err : new Error('Unknown error'));
+        }
+      });
     } else {
-      setFileUrl(null);
-      setFileReference(null);
-      setFileReferences([]);
-      setFileUrls(new Map());
-      setFileCount(0);
-      setIsLoading(false);
-      setError(null);
+      // Only update state if component is still mounted
+      safeSetState(setFileUrl, null);
+      safeSetState(setFileReference, null);
+      safeSetState(setFileReferences, []);
+      safeSetState(setFileUrls, new Map());
+      safeSetState(setFileCount, 0);
+      safeSetState(setIsLoading, false);
+      safeSetState(setError, null);
     }
+
+    // Cleanup: mark as unmounted when dependencies change or component unmounts
+    // This prevents state updates from stale requests
+    return () => {
+      isMountedRef.current = false;
+    };
     // fetchFiles is memoized; we only need to re-run when parameters change
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [table_name, record_id, organisation_id, supabase]);

package/src/hooks/useFileReference.ts

@@ -59,6 +59,13 @@ const urlRefreshManager = {
   }
 };
 
+/**
+ * Hook for managing file references.
+ * Provides file upload, retrieval, and URL generation functionality.
+ * 
+ * @param supabase - Supabase client instance
+ * @returns File reference service with upload, get, and URL methods
+ */
 export function useFileReference(supabase: SupabaseClient) {
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -385,13 +392,18 @@ export function useFileReferenceById(
     }
 
     const loadUrl = async () => {
-      const service = createFileReferenceService(supabase);
-      const url = await service.getFileUrl(
-        fileReference.table_name,
-        fileReference.record_id,
-        organisationId
-      );
-      setFileUrl(url);
+      try {
+        const service = createFileReferenceService(supabase);
+        const url = await service.getFileUrl(
+          fileReference.table_name,
+          fileReference.record_id,
+          organisationId
+        );
+        setFileUrl(url);
+      } catch (error) {
+        // Silently fail - component will handle missing URL
+        setFileUrl(null);
+      }
     };
 
     loadUrl();
@@ -478,6 +490,9 @@ export type UseFileReferenceOptions = {
   organisation_id: string;
 };
 
+/**
+ * Return value of the useFileReference hook.
+ */
 export type UseFileReferenceReturn = {
   isLoading: boolean;
   error: string | null;
@@ -492,6 +507,9 @@ export type UseFileReferenceReturn = {
   clearError: () => void;
 };
 
+/**
+ * Return value of the useFileReferenceForRecord hook.
+ */
 export type UseFileReferenceForRecordReturn = {
   isLoading: boolean;
   error: string | null;

package/src/hooks/useFileUrl.ts

@@ -15,11 +15,14 @@ import { createLogger } from '../utils/core/logger';
 
 const log = createLogger('useFileUrl');
 
+/**
+ * Options for the useFileUrl hook.
+ */
 export interface UseFileUrlOptions {
   /** Organisation ID for signed URL generation */
   organisation_id: string | undefined;
   /** Supabase client instance */
-  supabase: SupabaseClient;
+  supabase: SupabaseClient | null;
   /** Whether to auto-load URLs on mount */
   autoLoad?: boolean;
 }
@@ -63,6 +66,13 @@ export function useFileUrl(
       return;
     }
 
+    if (!supabase) {
+      setUrl(null);
+      setIsLoading(false);
+      setError(new Error('Supabase client is required for URL generation'));
+      return;
+    }
+
     // Skip if already loading or URL already exists for this file
     if (isLoading || (url && fileReferenceIdRef.current === fileReference.id)) {
       return;

package/src/hooks/useFocusManagement.ts

@@ -1,6 +1,9 @@
 
 import { useRef, useCallback, useEffect } from 'react';
 
+/**
+ * Options for the useFocusManagement hook.
+ */
 export interface FocusManagementOptions {
   trapFocus?: boolean;
   autoFocus?: boolean;
@@ -10,6 +13,10 @@ export interface FocusManagementOptions {
   onFocusLast?: () => void;
 }
 
+/**
+ * Return value of the useFocusManagement hook.
+ * Provides focus management utilities for accessible components.
+ */
 export interface FocusManagementReturn {
   containerRef: React.RefObject<HTMLDivElement | null>;
   focusRef: React.RefObject<HTMLElement | null>;
@@ -22,6 +29,13 @@ export interface FocusManagementReturn {
   handleEscape: (callback: () => void) => () => void;
 }
 
+/**
+ * Hook for managing focus in accessible components.
+ * Provides focus trapping, restoration, and navigation utilities.
+ * 
+ * @param options - Focus management configuration
+ * @returns Focus management utilities and refs
+ */
 export function useFocusManagement(options: FocusManagementOptions = {}): FocusManagementReturn {
   const { 
     trapFocus = false, 

package/src/hooks/useFocusTrap.ts

@@ -1,6 +1,9 @@
 
 import { useRef, useEffect, useCallback } from 'react';
 
+/**
+ * Options for the useFocusTrap hook.
+ */
 export interface FocusTrapOptions {
   /** Whether the focus trap is active */
   isActive?: boolean;

package/src/hooks/useInactivityTracker.ts

@@ -55,6 +55,9 @@
 import { useState, useEffect, useCallback, useRef } from 'react';
 import { logger } from '../utils/core/logger';
 
+/**
+ * Options for the useInactivityTracker hook.
+ */
 export interface UseInactivityTrackerOptions {
   /** Timeout in milliseconds before user is considered idle (default: 30 minutes) */
   idleTimeoutMs?: number;

package/src/hooks/useKeyboardShortcuts.ts

@@ -1,5 +1,9 @@
 import { useEffect, useCallback } from 'react';
 
+/**
+ * Keyboard shortcut definition.
+ * Defines a key combination and its handler function.
+ */
 export interface KeyboardShortcut {
   /** Key combination (e.g., 'Escape', 'Enter', 'ArrowDown', 'ctrl+s') */
   key: string;

package/src/hooks/useOrganisationPermissions.ts

@@ -50,6 +50,10 @@ import { useOrganisations } from './useOrganisations';
 import { useOrganisationSecurity } from './useOrganisationSecurity';
 import type { OrganisationRole, OrganisationPermission } from '../types/organisation';
 
+/**
+ * Return value of the useOrganisationPermissions hook.
+ * Provides organisation-specific permissions and role information.
+ */
 export interface UseOrganisationPermissionsReturn {
   /** User's role in the organisation */
   userRole: OrganisationRole | 'no_access';

package/src/hooks/useOrganisationSecurity.ts

@@ -16,6 +16,10 @@ import type { OrganisationSecurityError, SuperAdminContext } from '../types/orga
 import type { Permission } from '../rbac/types';
 import { logger } from '../utils/core/logger';
 
+/**
+ * Organisation security hook interface.
+ * Provides security utilities for organisation access validation and super admin functionality.
+ */
 export interface OrganisationSecurityHook {
   // Super admin context
   superAdminContext: SuperAdminContext;

package/src/hooks/usePerformanceMonitor.ts

@@ -5,6 +5,10 @@ import { createLogger } from '../utils/core/logger';
 
 const log = createLogger('usePerformanceMonitor');
 
+/**
+ * Performance metrics interface.
+ * Represents performance measurement data for components or operations.
+ */
 export interface PerformanceMetrics {
   renderTime: number;
   componentName: string;

package/src/hooks/usePermissionCache.ts

@@ -103,6 +103,13 @@ const DEFAULT_CONFIG: CacheConfig = {
   enableAuditTrail: true
 };
 
+/**
+ * Hook for centralized permission caching.
+ * Provides intelligent caching with automatic invalidation for permission checks.
+ * 
+ * @param config - Optional cache configuration
+ * @returns Permission cache utilities including check functions and debug info
+ */
 export function usePermissionCache(config: Partial<CacheConfig> = {}) {
   const mergedConfig = useMemo(() => ({ ...DEFAULT_CONFIG, ...config }), [config]);
   

package/src/hooks/useQueryCache.ts

@@ -127,6 +127,13 @@ export interface UseQueryCacheReturn {
  * );
  * ```
  */
+/**
+ * Hook for in-memory query result caching.
+ * Provides caching for frequently accessed data to eliminate duplicate queries.
+ * 
+ * @param supabase - Optional Supabase client instance
+ * @returns Query cache utilities including get, invalidate, and clear functions
+ */
 export function useQueryCache(supabase?: SupabaseClient<Database>): UseQueryCacheReturn {
   const getCachedQuery = useCallback(async <T,>(
     table: string,
@@ -218,7 +225,11 @@ export function useQueryCache(supabase?: SupabaseClient<Database>): UseQueryCach
 /**
  * Pre-configured cache helpers for common queries
  */
-export const queryCacheHelpers = {
+export const queryCacheHelpers: {
+  pacePersonByUserId: <T>(supabase: SupabaseClient<Database>, userId: string, fetchFn: () => Promise<T>) => Promise<T>;
+  paceMemberByPersonId: <T>(supabase: SupabaseClient<Database>, personId: string, fetchFn: () => Promise<T>) => Promise<T>;
+  rbacAppPagesByAppId: <T>(supabase: SupabaseClient<Database>, appId: string, fetchFn: () => Promise<T>) => Promise<T>;
+} = {
   /**
    * Cache core_person queries by user_id
    * TTL: 5 minutes

package/src/hooks/useSessionRestoration.ts

@@ -18,6 +18,10 @@ const log = createLogger('useSessionRestoration');
 
 const SESSION_RESTORATION_TIMEOUT_MS = 5000;
 
+/**
+ * Return value of the useSessionRestoration hook.
+ * Extends SessionRestorationState with timeout information.
+ */
 export interface UseSessionRestorationResult extends SessionRestorationState {
   /** Indicates whether the restoration process exceeded the timeout window */
   hasTimedOut: boolean;

package/src/hooks/useStorage.ts

@@ -27,6 +27,10 @@ export interface UseStorageOptions {
   orgId: string;
 }
 
+/**
+ * Return value of the useStorage hook.
+ * Provides storage operations including upload, URL generation, file management, and listing.
+ */
 export interface UseStorageReturn {
   // Upload
   uploadFile: (file: File, options?: Partial<StorageUploadOptions>) => Promise<StorageUploadResult>;

package/src/hooks/useToast.ts

@@ -71,7 +71,7 @@ const listeners: Array<(state: State) => void> = []
 /**
  * Reset the toast state and clear all timeouts
  */
-export function reset() {
+export function reset(): void {
   memoryState = { toasts: [] }
   toastTimeouts.forEach((timeout) => clearTimeout(timeout))
   toastTimeouts.clear()

package/src/index.ts

@@ -224,16 +224,16 @@ export { ProtectedRoute } from './components/ProtectedRoute/ProtectedRoute';
 export type { ProtectedRouteProps } from './components/ProtectedRoute/ProtectedRoute';
 
 // UTILITY COMPONENTS
-export { ErrorBoundary } from './components/ErrorBoundary/ErrorBoundary';
+export { ErrorBoundary, ErrorBoundaryProvider } from './components/ErrorBoundary';
+export type { ErrorBoundaryProps, ErrorBoundaryState, ErrorBoundaryProviderProps, GlobalErrorHandler } from './components/ErrorBoundary';
 export { LoadingSpinner } from './components/LoadingSpinner/LoadingSpinner';
 export { SessionRestorationLoader } from './components/SessionRestorationLoader/SessionRestorationLoader';
 export type { SessionRestorationLoaderProps } from './components/SessionRestorationLoader/SessionRestorationLoader';
 
-// EVENT MANAGEMENT
-export { EventSelector } from './components/EventSelector/EventSelector';
-
-// ORGANISATION MANAGEMENT
-export { OrganisationSelector } from './components/OrganisationSelector/OrganisationSelector';
+// CONTEXT SELECTION
+// Unified context selector (shows all accessible orgs and events)
+export { ContextSelector } from './components/ContextSelector/ContextSelector';
+export type { ContextSelectorProps } from './components/ContextSelector/ContextSelector';
 export { useOrganisationPermissions } from './hooks/useOrganisationPermissions';
 export { useOrganisationSecurity } from './hooks/useOrganisationSecurity';
 export { createSecureDataAccess } from './utils/security/secureDataAccess';