@jmruthers/pace-core 0.2.7 → 0.4.1

package/src/components/PaceAppLayout/PaceAppLayout.tsx

@@ -1,699 +0,0 @@
-/**
- * @file PACE App Layout Component
- * @package @jmruthers/pace-core
- * @module Components/PaceAppLayout
- * @since 0.1.0
- *
- * A comprehensive application layout component that provides a consistent
- * structure for all PACE suite applications with header, navigation, and footer.
- * 
- * NEW: Layout-level permission enforcement to ensure consuming apps can't
- * forget to implement permission checks on individual pages.
- *
- * Features:
- * - Consistent application layout structure
- * - Header with logo, navigation, and user menu
- * - Footer with copyright and links
- * - React Router integration with Outlet
- * - Unified authentication integration
- * - Navigation menu with configurable items
- * - User sign-out functionality
- * - Password change capability
- * - Responsive design
- * - Accessibility compliant
- * - Flexible content area
- * - Branding support
- * - Layout-level permission enforcement
- * - Automatic page permission validation
- * - Permission-based navigation filtering
- *
- * @example
- * ```tsx
- * // Basic app layout with React Router (RECOMMENDED)
- * <Router>
- *   <Routes>
- *     <Route path="/" element={<PaceAppLayout appName="My Application" />}>
- *       <Route index element={<HomePage />} />
- *       <Route path="dashboard" element={<DashboardPage />} />
- *       <Route path="settings" element={<SettingsPage />} />
- *     </Route>
- *   </Routes>
- * </Router>
- * 
- * // App layout with custom permission configuration
- * function MyApp() {
- *   return (
- *     <UnifiedAuthProvider supabaseClient={supabase} appName="My App">
- *       <Router>
- *         <Routes>
- *           <Route path="/" element={
- *             <PaceAppLayout 
- *               appName="My Application"
- *               enforcePermissions={true}
- *               defaultPermission="read"
- *               permissionFallback={<AccessDeniedPage />}
- *             />
- *           }>
- *             <Route index element={<HomePage />} />
- *             <Route path="events" element={<EventsPage />} />
- *             <Route path="reports" element={<ReportsPage />} />
- *             <Route path="admin" element={<AdminPage />} />
- *           </Route>
- *         </Routes>
- *       </Router>
- *     </UnifiedAuthProvider>
- *   );
- * }
- * 
- * ```
- *
- * @accessibility
- * - WCAG 2.1 AA compliant
- * - Proper semantic HTML structure
- * - Screen reader friendly navigation
- * - Keyboard navigation support
- * - Focus management
- * - High contrast support
- * - Clear content hierarchy
- * - Consistent navigation patterns
- *
- * @routing
- * - React Router v6 integration
- * - Nested route support
- * - Dynamic navigation handling
- * - Path-based navigation
- * - Route outlet rendering
- * - Permission-based route protection
- *
- * @dependencies
- * - React 18+ - Component framework
- * - React Router v6 - Routing
- * - UnifiedAuthProvider - Authentication
- * - usePermissionCache - Permission management
- * - Header component
- * - Footer component
- * - Button component
- * - NavigationMenu types
- * - Tailwind CSS - Styling
- */
-
-import React, { useState, useEffect, useMemo, useCallback } from 'react';
-import { Outlet, useNavigate, useLocation } from 'react-router-dom';
-import { useUnifiedAuth } from '../../providers/UnifiedAuthProvider';
-// Import RBAC functions directly so they can be mocked in tests
-import { isPermitted } from '../../rbac/api';
-import type { Permission } from '../../rbac/types';
-
-// Stable empty objects to prevent infinite loops
-const EMPTY_PAGE_ID_MAPPING = {};
-const EMPTY_ROUTE_PERMISSIONS = {};
-import { Button } from '../Button';
-import { Footer } from '../Footer';
-import { Header } from '../Header';
-import type { NavigationItem } from '../NavigationMenu/types';
-// Define Operation type locally since old RBAC types are removed
-type Operation = 'read' | 'create' | 'update' | 'delete' | 'manage';
-
-export interface PaceAppLayoutProps {
-  /** The name of the application to be displayed in the header. */
-  appName: string;
-  /** Optional navigation items for the header menu. If not provided, uses default navigation. */
-  navItems?: NavigationItem[];
-  /** Show/hide event selector in the header */
-  showEventSelector?: boolean;
-  /** Custom actions to display in the header (between event selector and user menu) */
-  headerActions?: React.ReactNode;
-  /** Custom logo component (overrides default logo) */
-  customLogo?: React.ReactNode;
-  /** 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 */
-  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;
-  /** Enable permission-based navigation filtering */
-  filterNavigationByPermissions?: boolean;
-  /** 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) */
-  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 */
-  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;
-}
-
-/**
- * A consistent layout component for all PACE suite applications that provides a standard
- * structure with header, main content area, and footer.
- * 
- * NEW: This component now includes layout-level permission enforcement to ensure
- * consuming apps can't forget to implement permission checks on individual pages.
- * 
- * This component is designed to work with React Router's nested routing pattern using
- * Outlet to render child routes. It provides integrated authentication, navigation,
- * and user management functionality.
- * 
- * Features:
- * - React Router v6 integration with nested routing
- * - Unified authentication integration
- * - Consistent header with navigation and user menu
- * - Flexible main content area with Outlet
- * - Footer with application branding
- * - User sign-out and password change functionality
- * - Responsive design and accessibility compliant
- * - Layout-level permission enforcement
- * - Permission-based navigation filtering
- * - Automatic page permission validation
- * 
- * @example
- * Basic React Router setup with permission enforcement (RECOMMENDED):
- * ```tsx
- * import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
- * import { UnifiedAuthProvider } from '@jmruthers/pace-core/providers';
- * import { PaceAppLayout, PaceLoginPage } from '@jmruthers/pace-core';
- * 
- * function App() {
- *   return (
- *     <UnifiedAuthProvider supabaseClient={supabase} appName="My App">
- *       <Router>
- *         <Routes>
- *           <Route path="/login" element={<PaceLoginPage appName="My App" />} />
- *           <Route path="/" element={
- *             <PaceAppLayout 
- *               appName="My Application"
- *               enforcePermissions={true}
- *               defaultPermission="read"
- *             />
- *           }>
- *             <Route index element={<HomePage />} />
- *             <Route path="dashboard" element={<DashboardPage />} />
- *             <Route path="meals" element={<MealsPage />} />
- *           </Route>
- *         </Routes>
- *       </Router>
- *     </UnifiedAuthProvider>
- *   );
- * }
- * ```
- * 
- * 
- * @example
- * Custom navigation items with permission filtering:
- * ```tsx
- * import { NavigationItem } from '@jmruthers/pace-core';
- * 
- * function App() {
- *   const customNavItems: NavigationItem[] = [
- *     { id: 'components', label: 'Components', href: '/components', icon: 'Component' },
- *     { id: 'styles', label: 'Styles', href: '/styles', icon: 'Palette' },
- *     { id: 'meals', label: 'Meals', href: '/meals', icon: 'UtensilsCrossed' }
- *   ];
- * 
- *   return (
- *     <Router>
- *       <Routes>
- *         <Route path="/" element={
- *           <PaceAppLayout 
- *             appName="My Custom App" 
- *             navItems={customNavItems}
- *             enforcePermissions={true}
- *             filterNavigationByPermissions={true}
- *             routePermissions={{
- *               '/components': 'read',
- *               '/styles': 'read',
- *               '/meals': 'read'
- *             }}
- *           />
- *         }>
- *           <Route path="components" element={<ComponentsPage />} />
- *           <Route path="styles" element={<StylesPage />} />
- *           <Route path="meals" element={<MealsPage />} />
- *         </Route>
- *       </Routes>
- *     </Router>
- *   );
- * }
- * ```
- * 
- * @example
- * Route-specific permissions with custom page IDs:
- * ```tsx
- * function AdminApp() {
- *   return (
- *     <Router>
- *       <Routes>
- *         <Route path="/" element={
- *           <PaceAppLayout 
- *             appName="Admin Panel"
- *             enforcePermissions={true}
- *             routePermissions={{
- *               '/dashboard': 'read',
- *               '/user-management': 'read',
- *               '/system-settings': 'update'
- *             }}
- *             pageIdMapping={{
- *               '/dashboard': 'dashboard',
- *               '/user-management': 'user-management',
- *               '/system-settings': 'system-admin'
- *             }}
- *             permissionFallback={<AccessDeniedPage />}
- *           />
- *         }>
- *           <Route path="dashboard" element={<DashboardPage />} />
- *           <Route path="user-management" element={<UserManagementPage />} />
- *           <Route path="system-settings" element={<SystemSettingsPage />} />
- *         </Route>
- *       </Routes>
- *     </Router>
- *   );
- * }
- * ```
- * 
- * @param props - Layout configuration including app name for branding and permission settings
- * @returns React element with complete application layout structure and permission enforcement
- * 
- * @since 0.1.0
- */
-export function PaceAppLayout({ 
-  appName, 
-  navItems, 
-  showEventSelector,
-  headerActions,
-  customLogo,
-  customUserMenu,
-  headerClassName,
-  showUserMenu = true,
-  enforcePermissions = false,
-  defaultPermission = 'read',
-  routePermissions = EMPTY_ROUTE_PERMISSIONS,
-  permissionFallback,
-  filterNavigationByPermissions = false,
-  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
-}: PaceAppLayoutProps) {
-  const { user, signOut, updatePassword } = useUnifiedAuth();
-  const navigate = useNavigate();
-  const location = useLocation();
-  // Use the new RBAC system for permission checking
-  const checkPermission = useCallback(async (permission: string, pageId?: string): Promise<boolean> => {
-    try {
-      // Use the imported RBAC API function
-      
-      if (!user?.id) return false;
-      
-      const scope = {
-        organisationId: user.user_metadata?.organisationId || user.app_metadata?.organisationId,
-        eventId: user.user_metadata?.eventId || user.app_metadata?.eventId,
-        appId: user.user_metadata?.appId || user.app_metadata?.appId,
-      };
-      
-      // Check if user is super admin first - super admins can access everything
-      // regardless of organisation context
-      const { isSuperAdmin } = await import('../../rbac/api');
-      const isSuper = await isSuperAdmin(user.id);
-      
-      if (isSuper) {
-        // Super admin bypass - allow access regardless of organisation context
-        return true;
-      }
-      
-      // For non-super admins, ensure we have at least organisationId for RBAC
-      if (!scope.organisationId) {
-        console.warn('No organisation context available for permission check, denying access');
-        return false;
-      }
-      
-      return await isPermitted({
-        userId: user.id,
-        scope,
-        permission: permission as Permission,
-        pageId
-      });
-    } catch (error) {
-      console.error('Permission check failed:', error);
-      // Let the error bubble up so it can be handled by the calling code
-      throw error;
-    }
-  }, [user?.id]);
-
-  // Permission enforcement state
-  const [hasPermission, setHasPermission] = useState<boolean | null>(null);
-  const [isCheckingPermission, setIsCheckingPermission] = useState(false);
-  const [permissionError, setPermissionError] = useState<Error | null>(null);
-
-  // 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]);
-
-  // 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
-  const currentPageId = useMemo(() => {
-    const currentPath = location.pathname;
-    return pageIdMapping[currentPath] || currentPath.slice(1) || 'home';
-  }, [location.pathname, pageIdMapping]);
-
-  // Check permission for current route
-  useEffect(() => {
-    if (!enforcePermissions) {
-      setHasPermission(true);
-      return;
-    }
-
-    let isMounted = true;
-
-    const checkRoutePermission = async () => {
-      if (!isMounted) return;
-      
-      setIsCheckingPermission(true);
-      setPermissionError(null);
-
-      try {
-        const hasAccess = await checkPermission(currentRoutePermission, currentPageId);
-        
-        if (!isMounted) return;
-        
-        setHasPermission(hasAccess);
-        
-        // NEW: Phase 1 - Enhanced Security Features
-        // Log page access attempt for audit
-        if (auditLog) {
-          console.log(`[PaceAppLayout] Page access attempt:`, {
-            pageName: currentPageId,
-            operation: currentRoutePermission,
-            userId: user?.id,
-            allowed: hasAccess,
-            strictMode,
-            timestamp: new Date().toISOString()
-          });
-        }
-        
-        // Handle strict mode violations
-        if (strictMode && !hasAccess) {
-          console.error(`[PaceAppLayout] STRICT MODE VIOLATION: User attempted to access protected page without permission`, {
-            pageName: currentPageId,
-            operation: currentRoutePermission,
-            userId: user?.id,
-            timestamp: new Date().toISOString()
-          });
-          
-          if (onStrictModeViolation) {
-            onStrictModeViolation(currentPageId, currentRoutePermission);
-          }
-        }
-        
-        // Handle page access denied callback
-        if (!hasAccess && onPageAccessDenied) {
-          onPageAccessDenied(currentPageId, currentRoutePermission);
-        }
-        
-      } catch (error) {
-        if (!isMounted) return;
-        
-        console.error(`[PaceAppLayout] Permission check failed for ${currentPageId}:`, error);
-        setPermissionError(error instanceof Error ? error : new Error('Permission check failed'));
-        setHasPermission(false);
-      } finally {
-        if (isMounted) {
-          setIsCheckingPermission(false);
-        }
-      }
-    };
-
-    checkRoutePermission();
-
-    return () => {
-      isMounted = false;
-    };
-  }, [enforcePermissions, currentRoutePermission, currentPageId, strictMode, user?.id]);
-
-  // Filter navigation items based on permissions
-  const [filteredMenuItems, setFilteredMenuItems] = useState<NavigationItem[]>(baseMenuItems);
-
-  useEffect(() => {
-    if (!filterNavigationByPermissions || !enforcePermissions) {
-      setFilteredMenuItems(baseMenuItems);
-      return;
-    }
-
-    let isMounted = true;
-
-    const filterItems = async () => {
-      const filtered = await Promise.all(
-        baseMenuItems.map(async (item) => {
-          if (!item.href) return { item, hasAccess: true };
-          
-          const pageId = pageIdMapping[item.href] || item.href.slice(1) || 'home';
-          const permission = routePermissions[item.href] || defaultPermission;
-          
-          try {
-            const hasAccess = await checkPermission(permission, pageId);
-            return { item, hasAccess };
-          } catch {
-            return { item, hasAccess: false };
-          }
-        })
-      );
-
-      if (!isMounted) return;
-
-      const accessibleItems = filtered
-        .filter(({ hasAccess }) => hasAccess)
-        .map(({ item }) => item);
-
-      setFilteredMenuItems(accessibleItems);
-    };
-
-    filterItems();
-
-    return () => {
-      isMounted = false;
-    };
-  }, [baseMenuItems, filterNavigationByPermissions, enforcePermissions, pageIdMapping, routePermissions, defaultPermission]);
-
-  // NEW: Phase 2 - Enhanced Routing Features
-  // Check route access for role-based routing
-  useEffect(() => {
-    if (!roleBasedRouting || routeConfig.length === 0) return;
-    
-    const currentPath = location.pathname;
-    const currentRoute = routeConfig.find(route => route.path === currentPath);
-    
-    if (!currentRoute) {
-      // Route not found in configuration
-      if (strictMode) {
-        console.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;
-    }
-    
-    // For now, allow all access - this will be enhanced with actual permission checking
-    const hasAccess = true; // This will be replaced with actual permission checking
-    
-    if (!hasAccess) {
-      // Handle route access denied
-      if (onRouteAccessDenied) {
-        onRouteAccessDenied(currentPath, 'Insufficient permissions');
-      }
-      
-      if (strictMode) {
-        console.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 });
-    }
-    
-    // Log route access attempt for audit
-    if (auditLog) {
-      console.log(`[PaceAppLayout] Route access attempt:`, {
-        route: currentPath,
-        userId: user?.id,
-        allowed: hasAccess,
-        permissions: currentRoute.permissions,
-        roles: currentRoute.roles,
-        accessLevel: currentRoute.accessLevel,
-        timestamp: new Date().toISOString()
-      });
-    }
-  }, [roleBasedRouting, routeConfig, location.pathname, strictMode, user?.id, fallbackRoute]);
-
-  const handleSignOut = async () => {
-    await signOut();
-  };
-
-  const handleChangePassword = async (newPassword: string) => {
-    // 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
-      console.error('Failed to change password:', result.error.message);
-    }
-    // The form will handle closing the modal on success
-    return result || { error: null };
-  };
-
-  // Show loading state while checking permissions
-  if (enforcePermissions && isCheckingPermission) {
-    return (
-      <div className="flex items-center justify-center min-h-screen">
-        <div className="text-center">
-          <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-sec-900 mx-auto mb-4"></div>
-          <p className="text-sec-600">Checking permissions...</p>
-        </div>
-      </div>
-    );
-  }
-
-  // Show permission error
-  if (enforcePermissions && permissionError) {
-    return (
-      <div className="flex items-center justify-center min-h-screen">
-        <div className="text-center">
-          <h2 className="text-xl font-semibold text-acc-600 mb-2">Permission Error</h2>
-          <p className="text-sec-600 mb-4">{permissionError.message}</p>
-          <Button onClick={() => navigate('/')}>Go Home</Button>
-        </div>
-      </div>
-    );
-  }
-
-  // Show permission fallback if user lacks permission
-  if (enforcePermissions && hasPermission === false) {
-    // NEW: Phase 1 - Use page permission fallback if available
-    if (enforcePagePermissions && pagePermissionFallback) {
-      return <>{pagePermissionFallback}</>;
-    }
-    
-    if (permissionFallback) {
-      return <>{permissionFallback}</>;
-    }
-    
-    return (
-      <div className="flex items-center justify-center min-h-screen">
-        <div className="text-center">
-          <h2 className="text-xl font-semibold text-acc-600 mb-2">Access Denied</h2>
-          <p className="text-sec-600 mb-4">
-            You don't have permission to access this page.
-          </p>
-          <Button onClick={() => navigate('/')}>Go Home</Button>
-        </div>
-      </div>
-    );
-  }
-
-  return (
-    <>
-      <Header
-        logo={customLogo || undefined}
-        logoUrl={!customLogo ? `/${appName.toLowerCase()}_logo_wide.svg` : undefined}
-        logoAlt={`${appName} Logo`}
-        navItems={filteredMenuItems}
-        actions={headerActions}
-        userMenu={customUserMenu}
-        user={user}
-        onSignOut={handleSignOut}
-        onChangePassword={handleChangePassword}
-        currentPath={window.location.pathname}
-        onNavigate={(item) => {
-          if (item.href) {
-            navigate(item.href);
-          }
-        }}
-        showEventSelector={showEventSelector}
-        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 />
-    </>
-  );
-}