@jmruthers/pace-core 0.5.185 → 0.5.186

package/src/components/ProtectedRoute/ProtectedRoute.tsx

@@ -68,7 +68,7 @@
  * - LoadingSpinner - Loading state UI
  */
 
-import React, { useMemo } from 'react';
+import React, { useMemo, useEffect, useRef, useState } from 'react';
 import { Navigate, Outlet } from 'react-router-dom';
 import { useUnifiedAuth } from '../../providers/services/UnifiedAuthProvider';
 import { useSessionRestoration } from '../../hooks/useSessionRestoration';
@@ -77,6 +77,7 @@ import { LoadingSpinner } from '../LoadingSpinner/LoadingSpinner';
 import { SessionRestorationLoader } from '../SessionRestorationLoader';
 import { Alert, AlertDescription, AlertTitle } from '../Alert/Alert';
 import { logger } from '../../utils/core/logger';
+import { usePreventTabReload } from '../../hooks/usePreventTabReload';
 
 export interface ProtectedRouteProps {
   /**
@@ -148,6 +149,96 @@ export function ProtectedRoute({
   
   const sessionRestoration = useSessionRestoration();
 
+  // Prevent full page reloads when switching tabs (handles bfcache and visibility changes)
+  usePreventTabReload({ enabled: true, gracePeriodMs: 2000 });
+
+  // Track if user was previously authenticated to prevent redirects during session refresh
+  const wasAuthenticatedRef = useRef(false);
+  const [shouldRedirect, setShouldRedirect] = useState(false);
+  const tabJustBecameVisibleRef = useRef(false);
+  
+  // Track authentication state to detect when user was previously logged in
+  useEffect(() => {
+    if (isAuthenticated) {
+      wasAuthenticatedRef.current = true;
+      setShouldRedirect(false);
+      tabJustBecameVisibleRef.current = false; // Clear visibility flag when authenticated
+    }
+  }, [isAuthenticated]);
+
+  // Handle tab visibility changes - prevent immediate redirects when tab becomes visible
+  // This prevents the page from refreshing when switching back to the tab
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+
+    let timeoutId: ReturnType<typeof setTimeout> | null = null;
+    let wasHidden = document.hidden;
+
+    const handleVisibilityChange = () => {
+      const isNowVisible = !document.hidden;
+      
+      // When tab becomes visible, immediately prevent redirects and give session refresh time
+      if (isNowVisible && wasHidden) {
+        // Tab just became visible - immediately prevent redirects
+        if (!isAuthenticated && wasAuthenticatedRef.current) {
+          tabJustBecameVisibleRef.current = true;
+          setShouldRedirect(false); // Immediately clear redirect flag
+          
+          // Clear any existing timeout
+          if (timeoutId) {
+            clearTimeout(timeoutId);
+          }
+          
+          // Wait a bit to see if session refresh completes
+          timeoutId = setTimeout(() => {
+            // Only allow redirect if still not authenticated after delay
+            tabJustBecameVisibleRef.current = false;
+            // Use a function to get the latest state
+            setShouldRedirect((prev) => {
+              // Only set to true if we're still not authenticated
+              // This will be checked again in the render logic
+              return prev;
+            });
+          }, 2000); // 2 second grace period for session refresh
+        }
+      } else if (!isNowVisible) {
+        // Tab became hidden - clear the visibility flag
+        tabJustBecameVisibleRef.current = false;
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = null;
+        }
+      }
+      
+      wasHidden = !isNowVisible;
+    };
+
+    // Check initial state - if tab is visible and user appears logged out, give grace period
+    if (!document.hidden && !isAuthenticated && wasAuthenticatedRef.current) {
+      tabJustBecameVisibleRef.current = true;
+      setShouldRedirect(false);
+      timeoutId = setTimeout(() => {
+        tabJustBecameVisibleRef.current = false;
+      }, 2000);
+    }
+
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+    return () => {
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    };
+  }, [isAuthenticated]);
+
+  // Reset redirect flag when authenticated
+  useEffect(() => {
+    if (isAuthenticated) {
+      setShouldRedirect(false);
+      tabJustBecameVisibleRef.current = false;
+    }
+  }, [isAuthenticated]);
+
   const isRestoringSession = useMemo(() => {
     return sessionRestoration.isRestoring &&
       !sessionRestoration.restorationComplete &&
@@ -182,13 +273,55 @@ export function ProtectedRoute({
   }
 
   // Redirect to login if not authenticated
+  // Priority order:
+  // 1. If session restoration has timed out or errored → redirect immediately (even if loading)
+  // 2. If user was never authenticated → redirect immediately (even if loading)
+  // 3. If tab just became visible → show loading (prevent redirect during grace period)
+  // 4. If we've confirmed they should redirect (after visibility change grace period) → redirect
+  // 5. Otherwise, if loading → show loading spinner (session might be refreshing)
+  // 6. Otherwise → redirect (user is not authenticated and not loading)
   if (!isAuthenticated) {
+    // Session restoration timeout/error always redirects immediately
     if (sessionRestoration.hasTimedOut || sessionRestoration.restorationError) {
       logger.warn('ProtectedRoute', 'Session restoration failed, redirecting to login', {
         timedOut: sessionRestoration.hasTimedOut,
         error: sessionRestoration.restorationError?.message
       });
+      return <Navigate to={loginPath} replace />;
+    }
+
+    // User was never authenticated → redirect immediately
+    if (!wasAuthenticatedRef.current) {
+      return <Navigate to={loginPath} replace />;
+    }
+
+    // Tab just became visible - show loading to prevent redirect during grace period
+    // Also check document visibility state directly as a fallback
+    const isTabVisible = typeof document !== 'undefined' && !document.hidden;
+    if (tabJustBecameVisibleRef.current || (isTabVisible && wasAuthenticatedRef.current && isLoading)) {
+      return loadingFallback || (
+        <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '100vh' }}>
+          <LoadingSpinner />
+        </div>
+      );
     }
+
+    // We've confirmed redirect after grace period → redirect
+    if (shouldRedirect) {
+      return <Navigate to={loginPath} replace />;
+    }
+
+    // User was authenticated before but now appears logged out
+    // Show loading state while we wait for session refresh (unless we're not loading)
+    if (isLoading) {
+      return loadingFallback || (
+        <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '100vh' }}>
+          <LoadingSpinner />
+        </div>
+      );
+    }
+
+    // Not loading and not authenticated → redirect
     return <Navigate to={loginPath} replace />;
   }
 

package/src/hooks/index.ts

@@ -64,6 +64,9 @@ export type { UseStorageOptions, UseStorageReturn } from './useStorage';
 // === PUBLIC DATA ACCESS HOOKS ===
 export * from './public';
 
+// === PAGE LIFECYCLE HOOKS ===
+export { usePreventTabReload } from './usePreventTabReload';
+export type { UsePreventTabReloadOptions } from './usePreventTabReload';
 
 // RBAC Hooks - Use @jmruthers/pace-core/rbac instead
 // Note: RBAC functionality has been moved to the dedicated RBAC module

package/src/hooks/useFileReference.test.ts

@@ -67,6 +67,7 @@ const mockFileUploadOptions = {
   organisation_id: 'test-org-123',
   app_id: 'test-app-123',
   category: FileCategory.GENERAL_DOCUMENTS,
+  folder: 'documents',
   pageContext: 'configuration',
   is_public: false
 };

package/src/hooks/usePreventTabReload.ts

@@ -0,0 +1,106 @@
+/**
+ * @file usePreventTabReload Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks
+ * @since 0.6.0
+ *
+ * Prevents full page reloads when switching browser tabs.
+ * Handles browser back-forward cache (bfcache) restoration and tab visibility changes.
+ */
+
+import { useEffect, useRef } from 'react';
+
+export interface UsePreventTabReloadOptions {
+  /**
+   * Whether to enable the prevention logic
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Grace period in milliseconds to wait after tab becomes visible
+   * before allowing any potential reloads
+   * @default 2000
+   */
+  gracePeriodMs?: number;
+}
+
+/**
+ * Hook to prevent full page reloads when switching browser tabs.
+ * 
+ * This hook handles:
+ * - Browser back-forward cache (bfcache) restoration
+ * - Tab visibility changes
+ * - Prevents unwanted page reloads when returning to a tab
+ * 
+ * @param options - Configuration options
+ * 
+ * @example
+ * ```tsx
+ * import { usePreventTabReload } from '@jmruthers/pace-core';
+ * 
+ * function MyComponent() {
+ *   usePreventTabReload();
+ *   // Component code...
+ * }
+ * ```
+ */
+export function usePreventTabReload(options: UsePreventTabReloadOptions = {}): void {
+  const { enabled = true, gracePeriodMs = 2000 } = options;
+  const isRestoringFromCacheRef = useRef(false);
+  const gracePeriodTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return;
+
+    // Handle pageshow event - detects when page is restored from bfcache
+    const handlePageShow = (event: PageTransitionEvent) => {
+      // If page was restored from bfcache, prevent any reload behavior
+      if (event.persisted) {
+        isRestoringFromCacheRef.current = true;
+        
+        // Clear any existing timeout
+        if (gracePeriodTimeoutRef.current) {
+          clearTimeout(gracePeriodTimeoutRef.current);
+        }
+        
+        // Set grace period to prevent reloads
+        gracePeriodTimeoutRef.current = setTimeout(() => {
+          isRestoringFromCacheRef.current = false;
+        }, gracePeriodMs);
+      }
+    };
+
+    // Handle visibility changes - when tab becomes visible
+    const handleVisibilityChange = () => {
+      if (!document.hidden) {
+        // Tab just became visible - set flag to prevent reloads
+        isRestoringFromCacheRef.current = true;
+        
+        // Clear any existing timeout
+        if (gracePeriodTimeoutRef.current) {
+          clearTimeout(gracePeriodTimeoutRef.current);
+        }
+        
+        // Set grace period
+        gracePeriodTimeoutRef.current = setTimeout(() => {
+          isRestoringFromCacheRef.current = false;
+        }, gracePeriodMs);
+      }
+    };
+
+    // Add event listeners
+    window.addEventListener('pageshow', handlePageShow);
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+
+    return () => {
+      window.removeEventListener('pageshow', handlePageShow);
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+      
+      if (gracePeriodTimeoutRef.current) {
+        clearTimeout(gracePeriodTimeoutRef.current);
+      }
+    };
+  }, [enabled, gracePeriodMs]);
+}
+

package/src/hooks/useSecureDataAccess.ts

@@ -219,7 +219,7 @@ export function useSecureDataAccess(): SecureDataAccessReturn {
       'cake_meal', 'cake_mealtype', 'pace_person', 'pace_member',
       // SECURITY: Phase 3A additions - medical and personal data
       'medi_profile', 'medi_condition', 'medi_diet', 'medi_action_plan', 'medi_profile_versions',
-      'pace_consent', 'pace_contact', 'pace_id_documents', 'pace_qualifications',
+      'pace_consent', 'pace_contact', 'pace_identification', 'pace_identification_type', 'pace_qualification',
       'form_responses', 'form_response_values', 'forms',
       // SECURITY: Phase 3B additions - remaining critical tables
       'invoice', 'line_item', 'credit_balance', 'payment_method',
@@ -379,7 +379,7 @@ export function useSecureDataAccess(): SecureDataAccessReturn {
       'cake_meal', 'cake_mealtype', 'pace_person', 'pace_member',
       // SECURITY: Phase 3A additions - medical and personal data
       'medi_profile', 'medi_condition', 'medi_diet', 'medi_action_plan', 'medi_profile_versions',
-      'pace_consent', 'pace_contact', 'pace_id_documents', 'pace_qualifications',
+      'pace_consent', 'pace_contact', 'pace_identification', 'pace_identification_type', 'pace_qualification',
       'form_responses', 'form_response_values', 'forms',
       // SECURITY: Phase 3B additions - remaining critical tables
       'invoice', 'line_item', 'credit_balance', 'payment_method',