@jmruthers/pace-core 0.6.10 → 0.6.12

package/src/components/PaceAppLayout/PaceAppLayout.tsx

@@ -97,109 +97,184 @@
  * - Tailwind CSS - Styling
  */
 
-import React, { useState, useEffect, useMemo } from 'react';
+import React, { useEffect } from 'react';
 import { Outlet, useNavigate, useLocation } from 'react-router-dom';
+import type { User } from '@supabase/supabase-js';
 import { useUnifiedAuth } from '../../providers/services/UnifiedAuthProvider';
 import { useOrganisations } from '../../hooks/useOrganisations';
-import { useEvents } from '../../hooks/useEvents';
+import { useOptionalEvents } from '../../hooks/useEvents';
 import { useEventTheme } from '../../hooks/useEventTheme';
-import type { Event } from '../../types/event';
-import { useCan } from '../../rbac/hooks/usePermissions';
-import { useResolvedScope } from '../../rbac/hooks/useResolvedScope';
 import { useRBAC } from '../../rbac/hooks/useRBAC';
-import { isSuperAdmin as checkSuperAdminApi } from '../../rbac/api';
 import { logger } from '../../utils/core/logger';
-import { EventContextRequiredError, OrganisationContextRequiredError, type Permission, type Scope } from '../../rbac/types';
-import { AccessDenied } from '../../rbac/components/AccessDenied';
-
-// Stable empty objects to prevent infinite loops
-const EMPTY_PAGE_ID_MAPPING = {};
-const EMPTY_ROUTE_PERMISSIONS = {};
-import { Button } from '../Button';
+import { useSuperAdminFallback } from './useSuperAdminFallback';
+import { useFilteredNavItems } from './useFilteredNavItems';
+import { useRoleBasedRouteAccess } from './useRoleBasedRouteAccess';
+import { usePaceAppLayoutConfig } from './usePaceAppLayoutConfig';
+import { usePaceAppLayoutPermissions } from './usePaceAppLayoutPermissions';
+import { usePaceAppLayoutGate } from './usePaceAppLayoutGate';
+import { usePaceAppLayoutScope } from './usePaceAppLayoutScope';
 import { Footer } from '../Footer';
 import { Header } from '../Header';
 import type { NavigationItem } from '../NavigationMenu/NavigationMenu';
-import { LoadingSpinner } from '../LoadingSpinner';
-// Define Operation type locally since old RBAC types are removed
+import { setupPrintDateTime } from '../../theming/runtime';
+
 type Operation = 'read' | 'create' | 'update' | 'delete' | 'manage';
+const EMPTY_PAGE_ID_MAPPING: Record<string, string> = {};
+const EMPTY_ROUTE_PERMISSIONS: Record<string, Operation> = {};
+
+/** Route config item for role-based routing. */
+export interface PaceAppLayoutRouteConfigItem {
+  path: string;
+  component: React.ComponentType;
+  permissions: string[];
+  roles?: string[];
+  accessLevel?: string;
+  pageId?: string;
+  strictMode?: boolean;
+  meta?: {
+    title?: string;
+    description?: string;
+    requiresAuth?: boolean;
+    hidden?: boolean;
+  };
+}
 
-/**
- * Props for the PaceAppLayout component.
- * Configures the application layout including navigation, header, and footer.
- */
-export interface PaceAppLayoutProps {
-  /** The name of the application to be displayed in the header. */
+/** Optional grouped permission options. When provided, overrides flat permission props. */
+export interface PaceAppLayoutPermissionConfig {
+  enforcePermissions?: boolean;
+  defaultPermission?: Operation;
+  routePermissions?: Record<string, Operation>;
+  pageIdMapping?: Record<string, string>;
+  permissionFallback?: React.ReactNode;
+  strictMode?: boolean;
+  enforcePagePermissions?: boolean;
+  pagePermissionFallback?: React.ReactNode;
+  auditLog?: boolean;
+  onPageAccessDenied?: (pageName: string, operation: string) => void;
+  onStrictModeViolation?: (pageName: string, operation: string) => void;
+}
+
+/** Optional grouped routing options. When provided, overrides flat routing props. */
+export interface PaceAppLayoutRoutingConfig {
+  roleBasedRouting?: boolean;
+  routeConfig?: PaceAppLayoutRouteConfigItem[];
+  fallbackRoute?: string;
+  onRouteAccessDenied?: (route: string, reason: string) => void;
+  onRouteStrictModeViolation?: (route: string, reason: string) => void;
+}
+
+/** Layout props for PaceAppLayout (ISP). */
+export interface PaceAppLayoutPropsLayout {
   appName: string;
-  /** Optional navigation items for the header menu. If not provided, uses default navigation. */
   navItems?: NavigationItem[];
-  /** Show/hide unified context selector (shows all accessible orgs and events) - default: true */
   showContextSelector?: boolean;
-  /** Show organisations in context selector - default: true */
   showOrganisations?: boolean;
-  /** Show events in context selector - default: true */
   showEvents?: boolean;
-  /** Custom actions to display in the header (between event selector and user menu) */
   headerActions?: React.ReactNode;
-  /** URL to navigate to when logo is clicked (defaults to '/dashboard') */
   logoHref?: string;
-  /** Custom user menu component (overrides default user menu) */
   customUserMenu?: React.ReactNode;
-  /** Custom className for the header */
   headerClassName?: string;
-  /** Show/hide user menu */
   showUserMenu?: boolean;
-  /** Enable layout-level permission enforcement */
+}
+
+/** Permission props for PaceAppLayout (ISP). */
+export interface PaceAppLayoutPropsPermission {
+  permissionConfig?: PaceAppLayoutPermissionConfig;
   enforcePermissions?: boolean;
-  /** Default permission to check for all routes (when enforcePermissions is true) */
   defaultPermission?: Operation;
-  /** Route-specific permissions mapping */
   routePermissions?: Record<string, Operation>;
-  /** Fallback component to show when user lacks permission */
   permissionFallback?: React.ReactNode;
-  /** Custom permission page ID mapping */
   pageIdMapping?: Record<string, string>;
-  
-  // NEW: Phase 1 - Enhanced Security Features
-  /** Enable strict mode to prevent bypassing permission checks (default: true) */
   strictMode?: boolean;
-  /** Enable page-level permission enforcement (default: false) */
   enforcePagePermissions?: boolean;
-  /** Default page permission fallback component */
   pagePermissionFallback?: React.ReactNode;
-  /** Enable audit logging for all permission checks (default: true) */
   auditLog?: boolean;
-  /** Callback when page access is denied */
   onPageAccessDenied?: (pageName: string, operation: string) => void;
-  /** Callback when strict mode violation occurs */
   onStrictModeViolation?: (pageName: string, operation: string) => void;
-  
-  // NEW: Phase 2 - Enhanced Routing Features
-  /** Enable role-based routing (default: false) */
+}
+
+/** Routing props for PaceAppLayout (ISP). */
+export interface PaceAppLayoutPropsRouting {
+  routingConfig?: PaceAppLayoutRoutingConfig;
   roleBasedRouting?: boolean;
-  /** Route configuration for role-based routing */
-  routeConfig?: Array<{
-    path: string;
-    component: React.ComponentType;
-    permissions: string[];
-    roles?: string[];
-    accessLevel?: string;
-    pageId?: string;
-    strictMode?: boolean;
-    meta?: {
-      title?: string;
-      description?: string;
-      requiresAuth?: boolean;
-      hidden?: boolean;
-    };
-  }>;
-  /** Fallback route for unauthorized access */
+  routeConfig?: PaceAppLayoutRouteConfigItem[];
   fallbackRoute?: string;
-  /** Callback when route access is denied */
   onRouteAccessDenied?: (route: string, reason: string) => void;
-  /** Callback when route strict mode violation occurs */
   onRouteStrictModeViolation?: (route: string, reason: string) => void;
 }
 
+/**
+ * Props for the PaceAppLayout component (ISP: composed from focused interfaces).
+ * Permission and routing options can be passed either as flat props or via permissionConfig / routingConfig.
+ */
+export type PaceAppLayoutProps = PaceAppLayoutPropsLayout
+  & PaceAppLayoutPropsPermission
+  & PaceAppLayoutPropsRouting;
+
+/** Renders the main layout structure (Header + main + Footer). Extracted to keep PaceAppLayout under max-lines. */
+function PaceAppLayoutContent({
+  appName,
+  logoHref,
+  filteredMenuItems,
+  headerActions,
+  customUserMenu,
+  user,
+  onSignOut,
+  onChangePassword,
+  headerClassName,
+  showContextSelector,
+  showOrganisations,
+  showEvents,
+  showUserMenu,
+  navigate,
+}: {
+  appName: string;
+  logoHref: string;
+  filteredMenuItems: NavigationItem[];
+  headerActions?: React.ReactNode;
+  customUserMenu?: React.ReactNode;
+  user: User | null | undefined;
+  onSignOut: () => Promise<void>;
+  onChangePassword: (newPassword: string, confirmPassword: string) => Promise<{ error?: { message: string; code?: string } }>;
+  headerClassName?: string;
+  showContextSelector: boolean;
+  showOrganisations: boolean;
+  showEvents: boolean;
+  showUserMenu: boolean;
+  navigate: (to: string) => void;
+}) {
+  return (
+    <>
+      <Header
+        logoUrl={`/${appName.toLowerCase()}_logo_wide.svg`}
+        logoAlt={`${appName} Logo`}
+        logoHref={logoHref}
+        navItems={filteredMenuItems}
+        actions={headerActions}
+        userMenu={customUserMenu}
+        user={user}
+        onSignOut={onSignOut}
+        onChangePassword={onChangePassword}
+        currentPath={window.location.pathname}
+        onNavigate={(item) => {
+          if (item.href) {
+            navigate(item.href);
+          }
+        }}
+        showContextSelector={showContextSelector}
+        showOrganisations={showOrganisations}
+        showEvents={showEvents}
+        showUserMenu={showUserMenu}
+        className={headerClassName || "sticky top-0 z-header w-full"}
+      />
+      <main className="px-4 w-full max-w-app-content-max mx-auto py-8">
+        <Outlet />
+      </main>
+      <Footer />
+    </>
+  );
+}
+
 /**
  * A consistent layout component for all PACE suite applications that provides a standard
  * structure with header, main content area, and footer.
@@ -348,9 +423,9 @@ export interface PaceAppLayoutProps {
  * 
  * @since 0.1.0
  */
-export function PaceAppLayout({ 
-  appName, 
-  navItems, 
+export function PaceAppLayout({
+  appName,
+  navItems,
   showContextSelector = true,
   showOrganisations = true,
   showEvents = true,
@@ -359,734 +434,183 @@ export function PaceAppLayout({
   customUserMenu,
   headerClassName,
   showUserMenu = true,
-  enforcePermissions = false,
-  defaultPermission = 'read',
-  routePermissions = EMPTY_ROUTE_PERMISSIONS,
-  permissionFallback,
-  pageIdMapping = EMPTY_PAGE_ID_MAPPING,
-  // NEW: Phase 1 - Enhanced Security Features
-  strictMode = true,
-  enforcePagePermissions = false,
-  pagePermissionFallback,
-  auditLog = true,
-  onPageAccessDenied,
-  onStrictModeViolation,
-  // NEW: Phase 2 - Enhanced Routing Features
-  roleBasedRouting = false,
-  routeConfig = [],
-  fallbackRoute = '/unauthorized',
-  onRouteAccessDenied,
-  onRouteStrictModeViolation
+  permissionConfig,
+  enforcePermissions: enforcePermissionsFlat = false,
+  defaultPermission: defaultPermissionFlat = 'read',
+  routePermissions: routePermissionsFlat = EMPTY_ROUTE_PERMISSIONS,
+  permissionFallback: permissionFallbackFlat,
+  pageIdMapping: pageIdMappingFlat = EMPTY_PAGE_ID_MAPPING,
+  strictMode: strictModeFlat = true,
+  enforcePagePermissions: enforcePagePermissionsFlat = false,
+  pagePermissionFallback: pagePermissionFallbackFlat,
+  auditLog: _auditLogFlat = true,
+  onPageAccessDenied: onPageAccessDeniedFlat,
+  onStrictModeViolation: onStrictModeViolationFlat,
+  routingConfig,
+  roleBasedRouting: roleBasedRoutingFlat = false,
+  routeConfig: routeConfigFlat = [],
+  fallbackRoute: fallbackRouteFlat = '/unauthorized',
+  onRouteAccessDenied: onRouteAccessDeniedFlat,
+  onRouteStrictModeViolation: onRouteStrictModeViolationFlat,
 }: PaceAppLayoutProps) {
-  const { user, signOut, updatePassword, supabase, appId: contextAppId, selectedOrganisationId } = useUnifiedAuth(); // Get appId from context (resolved on login)
-  const { 
-    selectedOrganisation, 
-    isContextReady: _isContextReady, 
-    hasValidOrganisationContext: _hasValidOrganisationContext,
-    ensureOrganisationContext: _ensureOrganisationContext,
-    isLoading: organisationLoading 
+  const config = usePaceAppLayoutConfig({
+    permissionConfig,
+    enforcePermissions: enforcePermissionsFlat,
+    defaultPermission: defaultPermissionFlat,
+    routePermissions: routePermissionsFlat,
+    permissionFallback: permissionFallbackFlat,
+    pageIdMapping: pageIdMappingFlat,
+    strictMode: strictModeFlat,
+    enforcePagePermissions: enforcePagePermissionsFlat,
+    pagePermissionFallback: pagePermissionFallbackFlat,
+    onPageAccessDenied: onPageAccessDeniedFlat,
+    onStrictModeViolation: onStrictModeViolationFlat,
+    routingConfig,
+    roleBasedRouting: roleBasedRoutingFlat,
+    routeConfig: routeConfigFlat,
+    fallbackRoute: fallbackRouteFlat,
+    onRouteAccessDenied: onRouteAccessDeniedFlat,
+    onRouteStrictModeViolation: onRouteStrictModeViolationFlat,
+  });
+
+  const { user, signOut, updatePassword, supabase, appId: contextAppId, selectedOrganisationId } = useUnifiedAuth();
+  const {
+    selectedOrganisation,
+    isLoading: organisationLoading,
   } = useOrganisations();
-  // Use useRBAC to get super admin status - it's more reliable than async check
-  // Note: isSuperAdmin might be false initially while loading, but that's OK - we'll allow rendering
-  // if organisation loading completes or if we're a super admin
   const { isSuperAdmin: isSuperAdminFromRBAC, isLoading: rbacLoading } = useRBAC();
+  const { isSuperAdminDirect, isCheckingSuperAdminDirect } = useSuperAdminFallback(user?.id, isSuperAdminFromRBAC);
 
-  // Also check super admin status directly as a fallback (for ADMIN/PORTAL apps)
-  // This allows super admins to proceed even if RBAC hasn't loaded yet
-  const [isSuperAdminDirect, setIsSuperAdminDirect] = useState<boolean>(false);
-  const [isCheckingSuperAdminDirect, setIsCheckingSuperAdminDirect] = useState<boolean>(false);
-
+  // Update --print-date-time when user prints (e.g. Ctrl+P) so printed pages show current date/time
   useEffect(() => {
-    const checkSuperAdminDirect = async () => {
-      if (!user?.id) {
-        setIsSuperAdminDirect(false);
-        setIsCheckingSuperAdminDirect(false);
-        return;
-      }
+    const teardown = setupPrintDateTime();
+    return teardown;
+  }, []);
 
-      // Only skip if RBAC already confirmed super admin
-      if (isSuperAdminFromRBAC) {
-        setIsCheckingSuperAdminDirect(false);
-        return;
-      }
-
-      setIsCheckingSuperAdminDirect(true);
-      try {
-        const superAdminStatus = await checkSuperAdminApi(user.id);
-        setIsSuperAdminDirect(superAdminStatus);
-      } catch (error) {
-        logger.error('PaceAppLayout', 'Error checking super admin status directly', { userId: user?.id, error });
-        setIsSuperAdminDirect(false);
-      } finally {
-        setIsCheckingSuperAdminDirect(false);
-      }
-    };
-
-    checkSuperAdminDirect();
-  }, [user?.id, isSuperAdminFromRBAC]);
-
-  // Use direct check if RBAC hasn't loaded yet, otherwise use RBAC result
   const isSuperAdmin = isSuperAdminFromRBAC || isSuperAdminDirect;
   const navigate = useNavigate();
   const location = useLocation();
-  
-  // Apply event theme colors automatically
+
   useEventTheme();
-  
-  // Get selected event (optional)
-  let selectedEvent: Event | null = null;
-  try {
-    const eventsContext = useEvents();
-    selectedEvent = eventsContext.selectedEvent;
-  } catch (_error) {
-    // Event provider not available - continue without event context
-  }
-  
-  // Resolve scope for permission checking
-  const { resolvedScope, isLoading: scopeLoading } = useResolvedScope({
-    supabase: supabase || null,
-    selectedOrganisationId: selectedOrganisation?.id || null,
-    selectedEventId: selectedEvent?.event_id || null,
-    selectedEventOrganisationId: selectedEvent?.organisation_id || null
+  const { selectedEvent } = useOptionalEvents();
+
+  const { scope, resolvedAppId, scopeLoading, baseMenuItems } = usePaceAppLayoutScope({
+    supabase,
+    selectedOrganisation,
+    selectedEvent,
+    contextAppId,
+    navItems,
   });
 
-  // Use appId from context (resolved immediately on login) or fallback to resolvedScope
-  // This ensures appId is available immediately without waiting for additional resolution
-  const resolvedAppId = contextAppId || resolvedScope?.appId;
-  
-  // Build scope from resolved values
-  // Preserve appId from resolvedScope or fallback to resolvedAppId
-  // CRITICAL: Always create a new scope object from primitive values to ensure stable reference
-  // This prevents useCan from re-checking permissions when resolvedScope changes reference but values are the same
-  const scopeOrgId = resolvedScope?.organisationId || selectedOrganisation?.id || '';
-  const scopeEventId = resolvedScope?.eventId || selectedEvent?.event_id || undefined;
-  const scopeAppId = resolvedScope?.appId || resolvedAppId || undefined;
-  
-  const scope = useMemo<Scope>(() => {
-    const newScope: Scope = {};
-    if (scopeOrgId) {
-      newScope.organisationId = scopeOrgId;
-    }
-    if (scopeEventId) {
-      newScope.eventId = scopeEventId;
-    }
-    if (scopeAppId) {
-      newScope.appId = scopeAppId;
-    }
-    return newScope;
-  }, [scopeOrgId, scopeEventId, scopeAppId]);
-
-  // Default navigation items if none provided
-  const defaultNavItems: NavigationItem[] = useMemo(() => [
-    { id: 'home', label: 'Home', href: '/', icon: 'Home' },
-    { id: 'dashboard', label: 'Dashboard', href: '/dashboard', icon: 'LayoutDashboard' },
-    { id: 'settings', label: 'Settings', href: '/settings', icon: 'Settings' },
-    { id: 'ui-showcase', label: 'UI Showcase', href: '/ui-showcase', icon: 'Component' },
-    { id: 'data-table-showcase', label: 'DataTable Showcase', href: '/data-table-showcase', icon: 'Table' },
-  ], []);
-
-  // Use provided navItems or fall back to default
-  const baseMenuItems = useMemo(() => navItems || defaultNavItems, [navItems, defaultNavItems]);
-
-  // Get current route permission requirements
-  const currentRoutePermission = useMemo(() => {
-    const currentPath = location.pathname;
-    return routePermissions[currentPath] || defaultPermission;
-  }, [location.pathname, routePermissions, defaultPermission]);
-
-  // Get current page ID for permission checking
-  // Extract base page name (first path segment) instead of full route path
-  // Example: /organisation/scouts-victoria -> "organisation"
-  const currentPageId = useMemo(() => {
-    const currentPath = location.pathname;
-    // Use pageIdMapping if provided (takes precedence)
-    if (pageIdMapping[currentPath]) {
-      return pageIdMapping[currentPath];
-    }
-    // Extract first path segment (base page name)
-    const pathSegments = currentPath.slice(1).split('/').filter(Boolean);
-    // Only return 'home' if there's actually a path segment, otherwise return empty string
-    // This prevents checking permissions for a non-existent "home" page when the index route is used
-    return pathSegments[0] || '';
-  }, [location.pathname, pageIdMapping]);
-
-  // Build permission string in format: operation:page.pageId
-  const currentPermission = useMemo<Permission>(() => {
-    // If enforcePermissions is false, don't check any permission (return empty string)
-    // If currentPageId is empty (index route with no path segments), don't check permissions
-    if (!enforcePermissions || !currentPageId) {
-      return '' as Permission;
-    }
-    const permissionString = `${currentRoutePermission}:page.${currentPageId}`;
-    return permissionString as Permission;
-  }, [enforcePermissions, currentRoutePermission, currentPageId]);
-
-  // Check super admin status before permission enforcement
-  // Removed duplicate super admin check - using useRBAC hook instead
-  // The useRBAC hook provides isSuperAdmin which is more reliable
-
-  // Use useCan hook for permission checking (standardized approach)
-  // Note: The database function already handles super admin bypass, but we check here
-  // as an additional safety layer to prevent unnecessary permission checks
-  // Pass appName to useCan so it can be passed to isPermitted for PORTAL/ADMIN special case
-  // Only check permissions if enforcePermissions is true and we have a valid permission string
-  const shouldCheckPermission = enforcePermissions && !!currentPermission && !!currentPageId;
-  // Pass super admin status to avoid duplicate check - use null if still checking, false/true if known
-  const superAdminStatus = isSuperAdminFromRBAC ? true : (isCheckingSuperAdminDirect ? null : isSuperAdminDirect);
-  const { can: canFromHook, isLoading: isCheckingPermission, error: permissionError } = useCan(
-    user?.id || '',
+  const permissions = usePaceAppLayoutPermissions({
+    config,
+    user,
     scope,
-    shouldCheckPermission ? currentPermission : ('' as Permission),
-    shouldCheckPermission ? currentPageId : '',
-    true, // useCache
-    superAdminStatus, // Pass super admin status to avoid duplicate check
-    appName // Pass appName for PORTAL/ADMIN special case
-  );
-
-  // Permission enforcement state - super admin bypasses all checks
-  // This ensures super admins never see permission errors even if useCan hasn't completed
-  // Use combined super admin check (RBAC + direct check)
-  const can = isSuperAdmin ? true : canFromHook;
-  const hasPermission = enforcePermissions ? can : true;
-  
-  // Check if the permission error is a context error (missing event/org context)
-  // Context errors should allow the page to render so it can show helpful messaging
-  // Real permission denials should still show "Access Denied"
-  const isContextError = useMemo(() => {
-    if (!permissionError) {
-      return false;
-    }
-    return (
-      permissionError instanceof EventContextRequiredError ||
-      permissionError instanceof OrganisationContextRequiredError ||
-      permissionError.name === 'EventContextRequiredError' ||
-      permissionError.name === 'OrganisationContextRequiredError'
-    );
-  }, [permissionError]);
-
-  // Handle permission check results with audit logging and callbacks
-  useEffect(() => {
-    if (!enforcePermissions) {
-      return;
-    }
-
-    // Only proceed when permission check is complete (not loading)
-    // Super admin status is checked via useRBAC hook (isSuperAdminFromRBAC)
-    // If RBAC is still loading, allow rendering to proceed (optimistic for super admins)
-    if (isCheckingPermission) {
-      return;
-    }
-
-    // NEW: Phase 1 - Enhanced Security Features
-    // Handle strict mode violations - skip for super admins
-    if (strictMode && !isSuperAdmin && !can) {
-      logger.error('PaceAppLayout', 'STRICT MODE VIOLATION: User attempted to access protected page without permission', {
-        pageName: currentPageId,
-        operation: currentRoutePermission,
-        userId: user?.id,
-        isSuperAdmin: isSuperAdmin,
-        timestamp: new Date().toISOString()
-      });
-      
-      if (onStrictModeViolation) {
-        onStrictModeViolation(currentPageId, currentRoutePermission);
-      }
-    }
-    
-    // Handle page access denied callback - skip for super admins
-    if (!isSuperAdmin && !can && onPageAccessDenied) {
-      onPageAccessDenied(currentPageId, currentRoutePermission);
-    }
-  }, [enforcePermissions, can, isCheckingPermission, isSuperAdmin, currentPageId, currentRoutePermission, user?.id, strictMode, auditLog, onPageAccessDenied, onStrictModeViolation]);
-
-  // Filter navigation items based on permissions
-  // Permission filtering is always enabled - users only see navigation items they have permission to access
-  const [filteredMenuItems, setFilteredMenuItems] = useState<NavigationItem[]>(baseMenuItems);
-
-  useEffect(() => {
-    let isMounted = true;
-
-    const filterItems = async () => {
-      // Wait for organisation context to be ready before filtering
-      // This prevents blocking navigation while context is loading
-      if (!user?.id) {
-        // User not loaded yet - show all items until context is ready
-        if (isMounted) {
-          setFilteredMenuItems(baseMenuItems);
-        }
-        return;
-      }
-
-      // Use the scope from context (includes selectedOrganisation and selectedEvent)
-      // This is critical for event-based apps where event context comes from EventService, not user metadata
-      const currentScope = scope;
-      
-      // Wait for scope to be fully resolved (including appId) before filtering
-      // This is important because getPermissionMap requires appId to fetch pages
-      // Check both resolvedScope.appId and resolvedAppId (fallback)
-      // appId is now resolved immediately on login in UnifiedAuthProvider, so it should be available
-      const _hasAppId = currentScope.appId || resolvedAppId;
-      
-      // OPTIMIZATION: Show items optimistically while permissions load
-      // This makes the menu appear immediately, then we filter when permissions are ready
-      const hasOrganisationContext = currentScope.organisationId;
-      const hasUser = !!user?.id;
-      
-      // Show navigation optimistically while waiting for context selection.
-      // Only hide navigation if user is not loaded.
-      // This prevents navigation from disappearing after initial render while waiting for context.
-      if (!hasUser) {
-        // User not loaded yet - show all items until user is ready
-        if (isMounted) {
-          setFilteredMenuItems(baseMenuItems);
-        }
-        return;
-      }
-
-      // If no organisation context yet, show items optimistically
-      // This allows users to see navigation while they select a context
-      // Only proceed with permission filtering once context is selected
-      if (!hasOrganisationContext) {
-        if (isMounted) {
-          // Show items optimistically when org selector is enabled, otherwise show all items
-          // This prevents navigation from disappearing while waiting for organisation selection
-          setFilteredMenuItems(baseMenuItems);
-        }
-        return;
-      }
-
-      // For super admins, show all items (they bypass permission checks)
-      // Gracefully handle RBAC not being initialized (e.g., in tests)
-      try {
-        const { isSuperAdmin: checkSuperAdminDynamic } = await import('../../rbac/api');
-        const isSuper = await checkSuperAdminDynamic(user.id);
-        
-        if (isSuper) {
-          // Super admins see all navigation items
-          if (isMounted) {
-            setFilteredMenuItems(baseMenuItems);
-          }
-          return;
-        }
-      } catch (error) {
-        // If RBAC is not initialized (e.g., in tests), continue with normal filtering
-        // This prevents errors from breaking navigation when RBAC isn't available
-        if (error && typeof error === 'object' && 'code' in error && error.code === 'RBAC_NOT_INITIALIZED') {
-          // RBAC not available - proceed with normal filtering without super admin check
-          // In this case, we'll filter items normally based on permissions
-        } else {
-          // Re-throw unexpected errors
-          throw error;
-        }
-      }
-
-      // Organisation context is ready - now filter items based on permissions
-      // OPTIMIZATION: Use batch permission map instead of individual checks to avoid rate limits
-      // This makes 1 call instead of N calls (where N = number of navigation items)
-      // OPTIMIZATION: Proceed even if appId is still resolving - permission checks work with organisationId
-      try {
-        const { getPermissionMap } = await import('../../rbac/api');
-        
-        // Build scope for permission check - use appId if available, but don't wait for it
-        // Permission checks will work with resource permissions even without appId
-        const permissionScope: Scope = {
-          organisationId: currentScope.organisationId,
-          eventId: currentScope.eventId,
-          appId: currentScope.appId || resolvedAppId || undefined // Use appId if available, but proceed without it
-        };
-        
-        const permissionMap = await getPermissionMap({
-          userId: user.id,
-          scope: permissionScope,
-        });
-
-        // Filter items using the permission map and scope type
-        // First, get scope types for all pages (batch if possible, or individual)
-        const { getPageScopeType } = await import('../../rbac/api');
-        const effectiveAppId = currentScope.appId || resolvedAppId;
-        const effectiveAppName = appName;
-        
-        // Determine current context type for scope filtering
-        const hasEventContext = !!currentScope.eventId;
-        const hasOrgContext = !!currentScope.organisationId;
-        
-        // Filter items using both permission map and scope type
-        const filtered = await Promise.all(
-          baseMenuItems.map(async (item) => {
-            if (!item.href) return { item, hasAccess: true, matchesScope: true, scopeCheckError: false };
-            
-            // Extract page ID from href: remove leading slash, fallback to 'dashboard' for root
-            // This matches database page names in rbac_app_pages
-            const pageId = pageIdMapping[item.href] || (item.href === '/' ? 'dashboard' : item.href.slice(1)) || 'dashboard';
-            const permission = routePermissions[item.href] || defaultPermission;
-            const fullPermission: Permission = permission.includes(':')
-              ? (permission as Permission)
-              : (pageId ? `${permission}:page.${pageId}` : permission) as Permission;
-            
-            // Check permission map (super admin check already handled in getPermissionMap)
-            const hasAccess = permissionMap['*'] === true || permissionMap[fullPermission] === true;
-            
-            // Check scope type compatibility
-            let matchesScope = true;
-            let scopeCheckError = false;
-            if (effectiveAppId || effectiveAppName) {
-              try {
-                const pageScopeType = await getPageScopeType(
-                  pageId,
-                  effectiveAppId,
-                  effectiveAppName
-                );
-                
-                // Filter based on current context:
-                // - If event is selected: show only 'event' or 'both' pages
-                // - If only org is selected: show only 'organisation' or 'both' pages
-                if (hasEventContext) {
-                  // Event context: show 'event' or 'both' pages only
-                  matchesScope = pageScopeType === 'event' || pageScopeType === 'both';
-                } else if (hasOrgContext) {
-                  // Organisation context only: show 'organisation' or 'both' pages only
-                  matchesScope = pageScopeType === 'organisation' || pageScopeType === 'both';
-                } else {
-                  // No context: show all pages (shouldn't happen, but safe fallback)
-                  matchesScope = true;
-                }
-              } catch (error) {
-                // If we can't get scope type, allow the page (graceful degradation)
-                // This prevents navigation from disappearing if there's a database issue
-                scopeCheckError = true;
-                logger.warn('PaceAppLayout', 'Failed to get page scope type for navigation filtering', {
-                  pageId,
-                  href: item.href,
-                  contextType: hasEventContext ? 'event' : (hasOrgContext ? 'organisation' : 'none'),
-                  error: error instanceof Error ? error.message : String(error),
-                  note: 'Allowing page to prevent navigation from disappearing - this may indicate missing scope_type in database'
-                });
-                matchesScope = true; // Default to allowing if we can't check
-              }
-            } else {
-              // No appId/appName available - can't check scope, allow the page
-              // This happens during initial load before app context is resolved
-              matchesScope = true;
-            }
-            
-            return { item, hasAccess, matchesScope, scopeCheckError };
-          })
-        );
-
-        if (!isMounted) return;
-
-        const accessibleItems = filtered
-          .filter(({ hasAccess, matchesScope }) => hasAccess && matchesScope)
-          .map(({ item }) => item);
-
-        // If all items were filtered out, check if it's due to scope filtering
-        // This can happen if:
-        // 1. All pages are scoped for the other context type (expected behavior)
-        // 2. Scope type lookup failed for all pages (should fallback to showing items with permissions)
-        if (accessibleItems.length === 0 && filtered.length > 0) {
-          const itemsWithPermissions = filtered.filter(({ hasAccess }) => hasAccess);
-          const itemsFilteredByScope = filtered.filter(({ hasAccess, matchesScope }) => hasAccess && !matchesScope);
-          const itemsWithScopeErrors = filtered.filter(({ hasAccess, scopeCheckError }) => hasAccess && scopeCheckError);
-          
-          // If scope checking failed for ALL items with permissions, fall back to showing them
-          // This prevents navigation from disappearing due to database/API issues
-          if (itemsWithPermissions.length > 0 && 
-              itemsWithScopeErrors.length === itemsWithPermissions.length) {
-            logger.warn('PaceAppLayout', 'Scope checking failed for all items - falling back to permission-only filtering', {
-              contextType: hasEventContext ? 'event' : (hasOrgContext ? 'organisation' : 'none'),
-              totalItems: baseMenuItems.length,
-              itemsWithPermissions: itemsWithPermissions.length,
-              scopeCheckErrorCount: itemsWithScopeErrors.length,
-              note: 'Showing items based on permissions only - scope filtering disabled due to errors. This may indicate database issues or missing scope_type values.'
-            });
-            
-            // Fall back to showing items that have permissions (ignore scope check)
-            const fallbackItems = filtered
-              .filter(({ hasAccess }) => hasAccess)
-              .map(({ item }) => item);
-            
-            if (isMounted && fallbackItems.length > 0) {
-              setFilteredMenuItems(fallbackItems);
-              return;
-            }
-          } else if (itemsWithPermissions.length > 0 && itemsFilteredByScope.length === itemsWithPermissions.length) {
-            // All items were filtered by scope (not errors) - this is expected if all pages are scoped for other context
-            logger.info('PaceAppLayout', 'All navigation items filtered out by scope type', {
-              contextType: hasEventContext ? 'event' : (hasOrgContext ? 'organisation' : 'none'),
-              totalItems: baseMenuItems.length,
-              itemsWithPermissions: itemsWithPermissions.length,
-              itemsFilteredByScope: itemsFilteredByScope.length,
-              note: 'All pages appear to be scoped for a different context type - this is expected behavior. Navigation will be empty until user selects the appropriate context.'
-            });
-          }
-        }
-
-        // SECURITY: Never show all items if permission check fails - this would be a security risk
-        // If all items are filtered out, it means the user doesn't have permission to see any navigation
-        // OR all pages are scoped for a different context type
-        // This is the correct behavior - better to show nothing than show unauthorized items
-        setFilteredMenuItems(accessibleItems);
-      } catch (error) {
-        // On error, fall back to showing all items (graceful degradation)
-        // This prevents navigation from being empty if permission checks fail
-        logger.error('PaceAppLayout', 'Failed to load permission map for navigation filtering', { userId: user?.id, error });
-        if (isMounted) {
-          setFilteredMenuItems(baseMenuItems);
-        }
-      }
-    };
-
-    filterItems();
+    appName,
+    isSuperAdminFromRBAC,
+    isSuperAdminDirect,
+    isCheckingSuperAdminDirect,
+    isSuperAdmin,
+  });
 
-    return () => {
-      isMounted = false;
-    };
-  }, [baseMenuItems, pageIdMapping, routePermissions, defaultPermission, can, user?.id, scope, scopeLoading, contextAppId, resolvedScope?.appId, resolvedAppId, selectedOrganisation?.id, selectedEvent?.event_id, appName]);
+  const filteredMenuItems = useFilteredNavItems({
+    baseMenuItems,
+    user,
+    scope,
+    routePermissions: config.routePermissions,
+    defaultPermission: config.defaultPermission,
+    pageIdMapping: config.pageIdMapping,
+    appName,
+    resolvedAppId,
+    scopeLoading,
+    contextAppId,
+    resolvedScopeAppId: resolvedAppId,
+    selectedOrganisationId: selectedOrganisation?.id,
+    selectedEventId: selectedEvent?.event_id ?? null,
+  });
 
-  // NEW: Phase 2 - Enhanced Routing Features
-  // Check route access for role-based routing
-  useEffect(() => {
-    if (!roleBasedRouting || routeConfig.length === 0) return;
-    
-    let isMounted = true;
-    
-    const checkRouteAccess = async () => {
-      const currentPath = location.pathname;
-      const currentRoute = routeConfig.find(route => route.path === currentPath);
-      
-      if (!currentRoute) {
-        // Route not found in configuration
-        if (strictMode) {
-          logger.error('PaceAppLayout', 'STRICT MODE VIOLATION: Route not found in configuration', {
-            route: currentPath,
-            userId: user?.id,
-            timestamp: new Date().toISOString()
-          });
-          
-          if (onRouteStrictModeViolation) {
-            onRouteStrictModeViolation(currentPath, 'Route not found in configuration');
-          }
-        }
-        return;
-      }
-      
-      // Check permissions using useCan hook result
-      let hasAccess = true; // Default to true if no permission requirements
-      
-      // Check page permissions
-      if (currentRoute.pageId && currentRoute.permissions && currentRoute.permissions.length > 0) {
-        // Use the permission check result from useCan hook
-        // For now, we'll use a simple check - in future we might need useMultiplePermissions here
-        try {
-          const { isPermittedCached } = await import('../../rbac/api');
-          const hasPagePermission = await isPermittedCached({
-            userId: user?.id || '',
-            scope,
-            permission: currentRoute.permissions[0] as Permission,
-            pageId: currentRoute.pageId,
-          });
-          if (!isMounted) return;
-          hasAccess = hasPagePermission;
-        } catch (error) {
-          logger.error('PaceAppLayout', 'Failed to check page permission', { route: currentPath, pageId: currentRoute.pageId, error });
-          if (!isMounted) return;
-          hasAccess = false;
-        }
-      }
-      
-      // If permission check passed or not required, check roles
-      if (hasAccess && currentRoute.roles && currentRoute.roles.length > 0 && user?.id) {
-        const { useUnifiedAuth } = await import('../../providers/services/UnifiedAuthProvider');
-        // Note: We're already in the component with authContext via useUnifiedAuth at top
-        // For this feature to work properly, we need the auth context
-        // This is a limitation of the current implementation
-        hasAccess = true; // Will be properly implemented when auth context is available in this effect
-      }
-      
-      if (!isMounted) return;
-      
-      if (!hasAccess) {
-        // Handle route access denied
-        if (onRouteAccessDenied) {
-          onRouteAccessDenied(currentPath, 'Insufficient permissions');
-        }
-        
-        if (strictMode) {
-          logger.error('PaceAppLayout', 'STRICT MODE VIOLATION: User attempted to access protected route without permission', {
-            route: currentPath,
-            userId: user?.id,
-            permissions: currentRoute.permissions,
-            roles: currentRoute.roles,
-            accessLevel: currentRoute.accessLevel,
-            timestamp: new Date().toISOString()
-          });
-          
-          if (onRouteStrictModeViolation) {
-            onRouteStrictModeViolation(currentPath, 'Insufficient permissions');
-          }
-        }
-        
-        // Redirect to fallback route
-        navigate(fallbackRoute, { replace: true });
-        return;
-      }
-    };
-    
-    checkRouteAccess();
-    
-    return () => {
-      isMounted = false;
-    };
-  }, [roleBasedRouting, routeConfig, location.pathname, strictMode, user?.id, fallbackRoute, scope, navigate, auditLog, onRouteAccessDenied, onRouteStrictModeViolation]);
+  useRoleBasedRouteAccess({
+    roleBasedRouting: config.roleBasedRouting,
+    routeConfig: config.routeConfig,
+    currentPath: location.pathname,
+    user,
+    scope,
+    strictMode: config.strictMode,
+    fallbackRoute: config.fallbackRoute,
+    navigate,
+    onRouteAccessDenied: config.onRouteAccessDenied,
+    onRouteStrictModeViolation: config.onRouteStrictModeViolation,
+  });
 
   const handleSignOut = async () => {
     try {
       await signOut();
     } catch (error) {
-      logger.error('PaceAppLayout', 'Failed to sign out', { error: error instanceof Error ? error.message : String(error) });
+      logger.error('PaceAppLayout', 'Failed to sign out', {
+        error: error instanceof Error ? error.message : String(error),
+      });
     }
   };
 
   const handleChangePassword = async (newPassword: string, _confirmPassword: string) => {
     try {
-      // The form component in UserMenu already checks for matching passwords
       const result = await updatePassword(newPassword);
-      if (result?.error) {
-        // The form will display the error message
+      if (!result.ok) {
         logger.error('PaceAppLayout', 'Failed to change password', { error: result.error.message });
-        // Convert AuthError to PasswordChangeFormError
-        return {
-          error: {
-            message: result.error.message,
-            code: result.error.name || 'PASSWORD_UPDATE_ERROR'
-          }
-        };
+        return { error: { message: result.error.message, code: result.error.code || 'PASSWORD_UPDATE_ERROR' } };
       }
-      // The form will handle closing the modal on success
       return {};
     } catch (error) {
-      logger.error('PaceAppLayout', 'Failed to change password', { error: error instanceof Error ? error.message : String(error) });
+      logger.error('PaceAppLayout', 'Failed to change password', {
+        error: error instanceof Error ? error.message : String(error),
+      });
       return {
         error: {
           message: error instanceof Error ? error.message : 'An unexpected error occurred',
-          code: 'PASSWORD_UPDATE_ERROR'
-        }
+          code: 'PASSWORD_UPDATE_ERROR',
+        },
       };
     }
   };
 
-  // CRITICAL: Wait for organisation context to be ready before proceeding
-  // The OrganisationService automatically selects an organisation when loading
-  // We just need to wait for isContextReady to be true
-  // No need to call ensureOrganisationContext() here - it will throw if no org is selected
-  // and the service handles selection automatically during loadUserOrganisations()
-
-  // Show loading state while organisation context is being set
-  // This is critical - we must wait for organisation context before allowing any data access
-  // BUT: Allow rendering to proceed if loading is complete, even if user has no organisations (valid state for profile pages)
-  // Only block if we're actively loading - once loading completes (success or error), allow rendering
-  // EXCEPTION: Super admins can proceed even during organisation loading (they can access all orgs)
-  // Use combined super admin check (RBAC + direct check) to allow super admins to proceed immediately
-  // IMPORTANT: If we're still checking super admin status, allow rendering to proceed (optimistic approach)
-  // This prevents blocking super admins while their status is being determined
-  // Also allow rendering if we already have a selectedOrganisationId (even if organisationLoading is still true)
-  // This prevents blank pages when organisation context is available but loading state hasn't cleared yet
-  if (user?.id && organisationLoading && !isSuperAdmin && !isCheckingSuperAdminDirect && !rbacLoading && !selectedOrganisationId) {
-    return (
-      <p className="grid place-items-center text-center size-full">
-        <LoadingSpinner
-          size="lg"/><br />
-        Loading organisation context...
-        </p>
-    );
-  }
-  
-  // Once loading is complete (whether success or error), allow rendering to proceed
-  // For users without organisations, allow access to profile pages (dashboard, member-profile, medical-profile, additional-contacts)
-  // These pages work with user context only and don't require organisation context
-  // The app can check hasValidOrganisationContext() to determine if org context is available for org-specific features
-
-  // Show loading state while checking permissions
-  // Keep loading active until permission check completes to prevent exposing protected content
-  // Super admin status is checked via useRBAC hook (isSuperAdminFromRBAC)
-  if (enforcePermissions && isCheckingPermission) {
-    return (
-      <p className="grid place-items-center text-center size-full">
-        <LoadingSpinner
-          size="lg"/><br />
-        Checking permissions...
-        </p>
-    );
-  }
+  const { gateContent } = usePaceAppLayoutGate({
+    user,
+    organisationLoading,
+    isSuperAdmin,
+    isCheckingSuperAdminDirect,
+    rbacLoading,
+    selectedOrganisationId,
+    enforcePermissions: config.enforcePermissions,
+    isCheckingPermission: permissions.isCheckingPermission,
+    permissionError: permissions.permissionError,
+    isContextError: permissions.isContextError,
+    hasPermission: permissions.hasPermission,
+    enforcePagePermissions: config.enforcePagePermissions,
+    pagePermissionFallback: config.pagePermissionFallback,
+    permissionFallback: config.permissionFallback,
+    onSignOut: handleSignOut,
+  });
 
-  // Show permission error (only after check is complete)
-  // Super admins bypass all permission checks, so don't show errors for them
-  // Context errors (missing event/org) should allow the page to render so it can show helpful messaging
-  // Real permission errors should still show "Access Denied"
-  if (enforcePermissions && permissionError && !isSuperAdmin && !isContextError) {
-    return (
-      <hgroup className="grid place-items-center text-center size-full">
-        <h2>Permission Error</h2>
-        <p>{permissionError.message}</p>
-        <Button onClick={() => navigate('/')}>Go Home</Button>
-      </hgroup>
-    );
-  }
-
-  // Show permission fallback if user lacks permission
-  // Only show this if super admin check is complete and user is not a super admin
-  // Skip if it's a context error (missing event/org) - allow page to render and show helpful messaging
-  if (enforcePermissions && hasPermission === false && !isCheckingSuperAdminDirect && !isSuperAdmin && !isContextError) {
-    // NEW: Phase 1 - Use page permission fallback if available
-    if (enforcePagePermissions && pagePermissionFallback) {
-      return <>{pagePermissionFallback}</>;
-    }
-    
-    if (permissionFallback) {
-      return <>{permissionFallback}</>;
-    }
-    
-    return (
-      <AccessDenied
-        message="You don't have permission to access this page."
-        onGoBack={() => navigate('/')}
-        onSignOut={async () => {
-            await handleSignOut();
-            navigate('/login');
-          }}
-        showSignOut={true}
-      />
-    );
+  if (gateContent !== null) {
+    return <>{gateContent}</>;
   }
 
   return (
-    <>
-      <Header
-        logoUrl={`/${appName.toLowerCase()}_logo_wide.svg`}
-        logoAlt={`${appName} Logo`}
-        logoHref={logoHref}
-        navItems={filteredMenuItems}
-        actions={headerActions}
-        userMenu={customUserMenu}
-        user={user}
-        onSignOut={handleSignOut}
-        onChangePassword={handleChangePassword}
-        currentPath={window.location.pathname}
-        onNavigate={(item) => {
-          if (item.href) {
-            navigate(item.href);
-          }
-        }}
-        showContextSelector={showContextSelector}
-        showOrganisations={showOrganisations}
-        showEvents={showEvents}
-        showUserMenu={showUserMenu}
-        className={headerClassName || "sticky top-0 z-[40] w-full"}
-      />
-      <main className="px-4 w-[min(var(--app-width),100%)] mx-auto py-8">
-        <Outlet />
-      </main>
-      <Footer />
-    </>
+    <PaceAppLayoutContent
+      appName={appName}
+      logoHref={logoHref}
+      filteredMenuItems={filteredMenuItems}
+      headerActions={headerActions}
+      customUserMenu={customUserMenu}
+      user={user}
+      onSignOut={handleSignOut}
+      onChangePassword={handleChangePassword}
+      headerClassName={headerClassName}
+      showContextSelector={showContextSelector}
+      showOrganisations={showOrganisations}
+      showEvents={showEvents}
+      showUserMenu={showUserMenu}
+      navigate={navigate}
+    />
   );
 }