@jmruthers/pace-core 0.5.76 → 0.5.77

package/docs/examples/navigation-menu-auth-fix.md

@@ -1,344 +0,0 @@
-# NavigationMenu Authentication Fix Example
-
-This example shows how to fix the NavigationMenu authentication context issue reported in the bug report.
-
-## Problem
-
-The consuming app was getting `permissions: undefined`, `roles: undefined`, `accessLevel: undefined` in console logs from the NavigationMenu component.
-
-## Root Cause
-
-The NavigationMenu component was not properly connected to the authentication context from `useUnifiedAuth`.
-
-## Solution
-
-### 1. Updated NavigationMenu Component
-
-The NavigationMenu component now properly uses the authentication context:
-
-```tsx
-// packages/core/src/components/NavigationMenu/NavigationMenu.tsx
-import { useUnifiedAuth } from "../../providers/UnifiedAuthProvider";
-
-export const NavigationMenu = React.forwardRef<HTMLDivElement, NavigationMenuProps>(({ 
-  items, 
-  filterByPermissions = true,
-  auditLog = true,
-  ...props 
-}, ref) => {
-  // Get authentication context
-  const authContext = React.useMemo(() => {
-    try {
-      return useUnifiedAuth();
-    } catch (error) {
-      console.warn('[NavigationMenu] useUnifiedAuth not available, running in unauthenticated mode');
-      return null;
-    }
-  }, []);
-
-  // Filter navigation items based on permissions
-  const filteredItems = React.useMemo(() => {
-    if (!filterByPermissions || !authContext) return items;
-    
-    return items.filter(item => {
-      // Check permissions if available
-      if (item.permissions && item.permissions.length > 0) {
-        const hasPermission = item.permissions.some(permission => 
-          authContext.hasPermission(permission)
-        );
-        if (!hasPermission) return false;
-      }
-      
-      // Check roles if available
-      if (item.roles && item.roles.length > 0) {
-        const hasRole = item.roles.some(role => 
-          authContext.hasRole(role)
-        );
-        if (!hasRole) return false;
-      }
-      
-      return true;
-    });
-  }, [items, filterByPermissions, authContext]);
-
-  // Log navigation access attempts for debugging
-  React.useEffect(() => {
-    if (auditLog && authContext) {
-      console.log('[NavigationMenu] Navigation access attempt:', {
-        itemId: 'navigation-menu',
-        label: 'Navigation Menu',
-        href: currentPath,
-        permissions: authContext.permissions,
-        roles: authContext.roles,
-        accessLevel: authContext.accessLevel,
-        timestamp: new Date().toISOString()
-      });
-    }
-  }, [auditLog, authContext, currentPath]);
-
-  // ... rest of component
-});
-```
-
-### 2. Updated NavigationItem Type
-
-Navigation items now support permission requirements:
-
-```typescript
-interface NavigationItem {
-  id: string;
-  label: string;
-  href?: string;
-  icon?: string;
-  children?: NavigationItem[];
-  isActive?: boolean;
-  permissions?: string[];
-  roles?: string[];
-  accessLevel?: string;
-  pageId?: string;
-  strictMode?: boolean;
-  meta?: {
-    title?: string;
-    description?: string;
-    hidden?: boolean;
-    order?: number;
-  };
-}
-```
-
-### 3. Correct App Structure
-
-The consuming app should use this structure:
-
-```tsx
-// App.tsx
-import React from 'react';
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
-import { 
-  UnifiedAuthProvider, 
-  OrganisationProvider, 
-  EventProvider,
-  PaceAppLayout 
-} from '@jmruthers/pace-core';
-import { supabase } from './integrations/supabase/client';
-import { AuthenticatedApp } from './AuthenticatedApp';
-
-function App() {
-  return (
-    <BrowserRouter>
-      <Routes>
-        <Route path="/*" element={
-          <UnifiedAuthProvider supabaseClient={supabase} appName="CAKE">
-            <OrganisationProvider>
-              <EventProvider>
-                <AuthenticatedApp />
-              </EventProvider>
-            </OrganisationProvider>
-          </UnifiedAuthProvider>
-        } />
-      </Routes>
-    </BrowserRouter>
-  );
-}
-
-export default App;
-```
-
-### 4. Updated AuthenticatedApp
-
-```tsx
-// AuthenticatedApp.tsx
-import React from 'react';
-import { Routes, Route } from 'react-router-dom';
-import { 
-  useUnifiedAuth, 
-  PaceAppLayout, 
-  NavigationItem, 
-  PaceLoginPage 
-} from "@jmruthers/pace-core";
-
-export function AuthenticatedApp() {
-  const { isAuthenticated, user, isLoading, accessLevel, roles } = useUnifiedAuth();
-
-  if (!isAuthenticated) {
-    return <PaceLoginPage appName="CAKE" />;
-  }
-
-  // Define navigation items with permission requirements
-  const navItems: NavigationItem[] = [
-    { 
-      id: 'meals', 
-      label: 'Meals', 
-      href: '/meals',
-      permissions: ['meals:read']
-    },
-    { 
-      id: 'dishes', 
-      label: 'Dishes', 
-      href: '/dishes',
-      permissions: ['dishes:read']
-    },
-    { 
-      id: 'items', 
-      label: 'Items', 
-      href: '/items',
-      permissions: ['items:read']
-    },
-    { 
-      id: 'diners', 
-      label: 'Diners', 
-      href: '/diners',
-      permissions: ['diners:read']
-    },
-    { 
-      id: 'menus', 
-      label: 'Menus', 
-      href: '/menus',
-      permissions: ['menus:read']
-    },
-    { 
-      id: 'distribution', 
-      label: 'Distribution', 
-      href: '/distribution',
-      permissions: ['distribution:read']
-    },
-    { 
-      id: 'suppliers', 
-      label: 'Suppliers', 
-      href: '/suppliers',
-      permissions: ['suppliers:read']
-    },
-  ];
-
-  return (
-    <PaceAppLayout 
-      key="main-layout"
-      appName="CAKE" 
-      navItems={navItems}
-      showEventSelector={true}
-    >
-      <Routes>
-        <Route index element={<div>Meals Page</div>} />
-        <Route path="meals" element={<div>Meals Page</div>} />
-        <Route path="dishes" element={<div>Dishes Page</div>} />
-        <Route path="items" element={<div>Items Page</div>} />
-        <Route path="diners" element={<div>Diners Page</div>} />
-        <Route path="menus" element={<div>Menus Page</div>} />
-        <Route path="distribution" element={<div>Distribution Page</div>} />
-        <Route path="suppliers" element={<div>Suppliers Page</div>} />
-        <Route path="*" element={<div>Not Found</div>} />
-      </Routes>
-    </PaceAppLayout>
-  );
-}
-```
-
-### 5. Alternative: Direct NavigationMenu Usage
-
-If you want to use NavigationMenu directly without PaceAppLayout:
-
-```tsx
-import { NavigationMenu } from '@jmruthers/pace-core';
-import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
-
-function CustomNavigation() {
-  const { hasPermission, hasRole } = useUnifiedAuth();
-
-  const navItems: NavigationItem[] = [
-    { 
-      id: 'meals', 
-      label: 'Meals', 
-      href: '/meals',
-      permissions: ['meals:read']
-    },
-    { 
-      id: 'admin', 
-      label: 'Admin Panel', 
-      href: '/admin',
-      roles: ['admin', 'super_admin']
-    }
-  ];
-
-  return (
-    <NavigationMenu 
-      items={navItems}
-      currentPath={location.pathname}
-      onNavigate={(item) => navigate(item.href)}
-      buttonText="Menu"
-      filterByPermissions={true}
-      auditLog={true}
-    />
-  );
-}
-```
-
-## Expected Results
-
-After implementing this fix:
-
-1. **Console logs will show proper authentication context**:
-   ```javascript
-   [NavigationMenu] Navigation access attempt: {
-     itemId: "navigation-menu",
-     label: "Navigation Menu",
-     href: "/meals",
-     permissions: { "meals:read": true, "dishes:read": true },
-     roles: ["user", "admin"],
-     accessLevel: "super",
-     timestamp: "2025-10-06T04:38:15.2012"
-   }
-   ```
-
-2. **Navigation items will be filtered based on permissions**:
-   - Items with `permissions: ['meals:read']` will only show if user has that permission
-   - Items with `roles: ['admin']` will only show if user has that role
-
-3. **No more "useUnifiedAuth not available" warnings**
-
-## Testing
-
-To test the fix:
-
-1. **Check console logs**: Should show proper authentication context
-2. **Test permission filtering**: Remove permissions from user and verify items are hidden
-3. **Test role filtering**: Change user roles and verify admin items show/hide
-4. **Test audit logging**: Enable `auditLog={true}` and verify logs are generated
-
-## Migration Guide
-
-If you're updating from the old NavigationMenu:
-
-1. **Add permission requirements to navigation items**:
-   ```tsx
-   // Old way
-   const navItems = [
-     { id: 'meals', label: 'Meals', href: '/meals' }
-   ];
-
-   // New way
-   const navItems = [
-     { id: 'meals', label: 'Meals', href: '/meals', permissions: ['meals:read'] }
-   ];
-   ```
-
-2. **Enable permission filtering**:
-   ```tsx
-   <NavigationMenu 
-     items={navItems}
-     filterByPermissions={true}
-     auditLog={true}
-   />
-   ```
-
-3. **Ensure proper provider hierarchy**:
-   ```tsx
-   <UnifiedAuthProvider>
-     <OrganisationProvider>
-       <EventProvider>
-         <NavigationMenu items={navItems} />
-       </EventProvider>
-     </OrganisationProvider>
-   </UnifiedAuthProvider>
-   ```
-
-This fix resolves the authentication context issue and provides proper permission-based navigation filtering.