@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/components/NavigationMenu/NavigationMenu.tsx

@@ -3,201 +3,18 @@
  * @package @jmruthers/pace-core
  * @module Navigation
  * @since 0.1.0
- * 
- * A flexible navigation menu component that supports both dropdown and hierarchical modes.
- * 
- * Features:
- * - Dropdown mode: Menu button that opens a dropdown list
- * - Hierarchical mode: Expandable tree navigation with nested items
- * - Icon support for navigation items
- * - Current page highlighting
- * - Keyboard navigation support
- * - Accessible design with proper ARIA attributes
- * - Click outside to close (dropdown mode)
- * - Recursive rendering for nested items (hierarchical mode)
- * 
- * @example
- * Basic dropdown navigation (most common use case):
- * ```tsx
- * import { NavigationMenu } from '@jmruthers/pace-core';
- * import { useNavigate, useLocation } from 'react-router-dom';
- * 
- * function AppNavigation() {
- *   const navigate = useNavigate();
- *   const location = useLocation();
- * 
- *   const navItems = [
- *     { id: 'home', label: 'Home', href: '/', icon: 'Home' },
- *     { id: 'dashboard', label: 'Dashboard', href: '/dashboard', icon: 'LayoutDashboard' },
- *     { id: 'reports', label: 'Reports', href: '/reports', icon: 'FileText' },
- *     { id: 'settings', label: 'Settings', href: '/settings', icon: 'Settings' }
- *   ];
- * 
- *   return (
- *     <NavigationMenu 
- *       items={navItems}
- *       mode="dropdown"
- *       currentPath={location.pathname}
- *       onNavigate={(item) => navigate(item.href)}
- *       buttonText="Main Menu"
- *       showIcons={true}
- *     />
- *   );
- * }
- * 
- * @example
- * Hierarchical navigation with nested items:
- * ```tsx
- * import { NavigationMenu } from '@jmruthers/pace-core';
- * 
- * function SidebarNavigation() {
- *   const hierarchicalItems = [
- *     { 
- *       id: 'user-management', 
- *       label: 'User Management',
- *       icon: 'Users',
- *       children: [
- *         { id: 'users-list', label: 'All Users', href: '/users' },
- *         { id: 'users-create', label: 'Create User', href: '/users/create' },
- *         { id: 'user-roles', label: 'User Roles', href: '/users/roles' }
- *       ]
- *     },
- *     { 
- *       id: 'reports', 
- *       label: 'Reports',
- *       icon: 'BarChart',
- *       children: [
- *         { id: 'sales-reports', label: 'Sales Reports', href: '/reports/sales' },
- *         { id: 'user-reports', label: 'User Reports', href: '/reports/users' }
- *       ]
- *     },
- *     { id: 'settings', label: 'Settings', href: '/settings', icon: 'Settings' }
- *   ];
- * 
- *   return (
- *     <NavigationMenu 
- *       items={hierarchicalItems}
- *       mode="hierarchical"
- *       currentPath={window.location.pathname}
- *       onNavigate={(item) => {
- *         if (item.href) {
- *           window.location.href = item.href;
- *         }
- *       }}
- *       className="w-64 bg-sec-50 p-4"
- *     />
- *   );
- * }
- * ```
- * 
- * @example
- * Integration with React Router and authentication:
- * ```tsx
- * import { NavigationMenu } from '@jmruthers/pace-core';
- * import { useNavigate, useLocation } from 'react-router-dom';
- * import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
- * 
- * function AuthenticatedNavigation() {
- *   const navigate = useNavigate();
- *   const location = useLocation();
- *   const { hasRole, hasPermission } = useUnifiedAuth();
- * 
- *   // Build navigation items based on user permissions
- *   const navItems = [
- *     { id: 'dashboard', label: 'Dashboard', href: '/dashboard', icon: 'LayoutDashboard' },
- *     ...(hasPermission('meals:read') ? [
- *       { id: 'meals', label: 'Meals', href: '/meals', icon: 'UtensilsCrossed' }
- *     ] : []),
- *     ...(hasRole('admin') ? [
- *       { id: 'admin', label: 'Admin Panel', href: '/admin', icon: 'Shield' }
- *     ] : []),
- *     { id: 'profile', label: 'Profile', href: '/profile', icon: 'User' }
- *   ];
- * 
- *   return (
- *     <NavigationMenu 
- *       items={navItems}
- *       mode="dropdown"
- *       currentPath={location.pathname}
- *       onNavigate={(item) => navigate(item.href)}
- *       buttonText="Navigation"
- *       navigationLabel="Main application navigation"
- *     />
- *   );
- * }
- * ```
- * 
- * @example
- * ```tsx
- * // Custom navigation with external links and actions
- * import { NavigationMenu } from '@jmruthers/pace-core';
- * 
- * function CustomNavigation() {
- *   const handleNavigation = (item) => {
- *     if (item.id === 'logout') {
- *       // Handle logout action
- *       handleLogout();
- *     } else if (item.href?.startsWith('http')) {
- *       // Handle external links
- *       window.open(item.href, '_blank');
- *     } else if (item.href) {
- *       // Handle internal navigation
- *       navigate(item.href);
- *     }
- *   };
- * 
- *   const navItems = [
- *     { id: 'home', label: 'Home', href: '/', icon: 'Home' },
- *     { id: 'help', label: 'Help Center', href: 'https://help.example.com', icon: 'HelpCircle' },
- *     { id: 'logout', label: 'Sign Out', icon: 'LogOut' } // No href for actions
- *   ];
- * 
- *   return (
- *     <NavigationMenu 
- *       items={navItems}
- *       mode="dropdown"
- *       onNavigate={handleNavigation}
- *       buttonText="Menu"
- *       disabled={false}
- *     />
- *   );
- * }
- * ```
- * 
- * @accessibility
- * - WCAG 2.1 AA compliant navigation structure
- * - Proper ARIA attributes for screen readers
- * - Keyboard navigation with Enter, Space, and Escape keys
- * - Focus management for dropdown menus
- * - Semantic HTML structure with nav, menu, and menuitem roles
- * - Clear visual indicators for active/current page
- * 
- * @performance
- * - Lightweight component with minimal re-renders
- * - Efficient click outside detection
- * - Optimized keyboard event handling
- * - Memory cleanup for event listeners
- * 
- * @styling
- * - Uses Tailwind CSS for consistent styling
- * - Supports custom className for additional styling
- * - Responsive design considerations
- * 
- * @dependencies
- * - React 19+ - Component framework and hooks
- * - Lucide React - Icon components
- * - Radix UI - Dropdown menu primitives
- * - React Router (optional) - For navigation handling
- * - Tailwind CSS - Styling system
+ *
+ * Navigation menu with dropdown and hierarchical modes. Items are filtered by RBAC
+ * (permissions, roles, access level, page permission). See JSDoc on NavigationMenu below.
  */
 
 import * as React from "react";
-import { ChevronDown } from "lucide-react";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "../Select";
 import { logger } from "../../utils/core/logger";
+import { resolveNavigationAccess } from "./navigationPermissionHelper";
 import { useNavigationFiltering } from "./useNavigationFiltering";
+import { HierarchicalNavItem } from "./HierarchicalNavItem";
 import type { NavigationItem, NavigationMenuProps } from "./types";
-import type { Permission } from "../../rbac/types";
 
 /**
  * Unified NavigationMenu component that supports both dropdown and hierarchical navigation modes.
@@ -341,7 +158,6 @@ import type { Permission } from "../../rbac/types";
  *       onNavigate={(item) => navigate(item.href)}
  *       buttonText="Navigation"
  *       navigationLabel="Main application navigation"
- *       // Permission filtering is always enabled - no prop needed
  *       auditLog={true}
  *     />
  *   );
@@ -352,29 +168,27 @@ import type { Permission } from "../../rbac/types";
  * Custom navigation with external links and actions:
  * ```tsx
  * import { NavigationMenu } from '@jmruthers/pace-core';
- * 
+ * import type { NavigationItem } from '@jmruthers/pace-core';
+ *
  * function CustomNavigation() {
- *   const handleNavigation = (item) => {
+ *   const handleNavigation = (item: NavigationItem) => {
  *     if (item.id === 'logout') {
- *       // Handle logout action
  *       handleLogout();
  *     } else if (item.href?.startsWith('http')) {
- *       // Handle external links
  *       window.open(item.href, '_blank');
  *     } else if (item.href) {
- *       // Handle internal navigation
  *       navigate(item.href);
  *     }
  *   };
- * 
+ *
  *   const navItems = [
  *     { id: 'home', label: 'Home', href: '/', icon: 'Home' },
  *     { id: 'help', label: 'Help Center', href: 'https://help.example.com', icon: 'HelpCircle' },
- *     { id: 'logout', label: 'Sign Out', icon: 'LogOut' } // No href for actions
+ *     { id: 'logout', label: 'Sign Out', icon: 'LogOut' }
  *   ];
- * 
+ *
  *   return (
- *     <NavigationMenu 
+ *     <NavigationMenu
  *       items={navItems}
  *       mode="dropdown"
  *       onNavigate={handleNavigation}
@@ -384,7 +198,7 @@ import type { Permission } from "../../rbac/types";
  *   );
  * }
  * ```
- * 
+ *
  * @param props - NavigationMenu component props including items, mode, navigation handlers, and styling options
  * @returns React element with navigation menu functionality
  * 
@@ -429,8 +243,8 @@ export const NavigationMenu = React.forwardRef<
         event.preventDefault();
         if (item.children && item.children.length > 0) {
           toggleExpanded(item.id);
-        } else if (item.href) {
-          onNavigate?.(item);
+        } else {
+          handleItemClick(item);
         }
         break;
       case 'Escape':
@@ -452,17 +266,12 @@ export const NavigationMenu = React.forwardRef<
     setExpandedItems(newExpanded);
   };
 
-  // Handle navigation item click
   const handleItemClick = (item: NavigationItem) => {
-    // NEW: Phase 2 - Enhanced Security Features
-    // Log navigation access attempt for audit (minimal logging)
     if (auditLog) {
-      // Navigation access attempt logged
+      logger.debug('NavigationMenu', 'Navigation access attempt', { itemId: item.id, label: item.label });
     }
-    
-    // Check if user has permission to access this navigation item
+
     if (!authContext) {
-      // No auth context - allow access (for unauthenticated scenarios)
       if (onNavigate) {
         onNavigate(item);
       } else if (item.href) {
@@ -470,86 +279,32 @@ export const NavigationMenu = React.forwardRef<
       }
       return;
     }
-    
-    // Check if item should be visible (already filtered)
-    // If item is in filteredItems, it has already passed permission checks in PaceAppLayout
-    const isItemVisible = filteredItems.some(filtered => filtered.id === item.id);
-    
-    // If item is not visible, it was filtered out - don't allow navigation
-    if (!isItemVisible) {
-      logger.warn('NavigationMenu', 'Navigation attempt to filtered item blocked', {
-        itemId: item.id,
-        label: item.label,
-        href: item.href
-      });
-      return;
-    }
-    
-    // Check permissions if the item requires them using RBAC hooks
-    // Only check if item has explicit permission requirements AND we have permission checking capability
-    let hasPermission = true; // Default to true if no permission requirements
-    
-    // Only check permissions if:
-    // 1. Item has explicit permission requirements
-    // 2. We have RBAC context
-    // 3. We have hasAnyPermission function AND permission map is loaded (not empty)
-    if (item.permissions && item.permissions.length > 0 && rbacContext && hasAnyPermission && permissionMap && Object.keys(permissionMap).length > 0) {
-      // Convert string permissions to Permission type and check
-      const permissions = item.permissions
-        .filter((p): p is string => typeof p === 'string')
-        .map(p => p as Permission);
-      
-      if (permissions.length > 0) {
-        hasPermission = hasAnyPermission(permissions);
-      }
-    }
-    
-    // If permission check failed, try role-based access
-    if (!hasPermission && rbacContext) {
-      // Check roles if permissions check failed or item has role requirements
-      if (item.roles && item.roles.length > 0) {
-        hasPermission = item.roles.some(role => {
-          if (typeof role !== 'string') return true;
-          
-          // Map role strings to RBAC role checks (same logic as filtering)
-          switch (role.toLowerCase()) {
-            case 'super_admin':
-            case 'super admin':
-              return rbacContext.isSuperAdmin;
-            case 'org_admin':
-            case 'org admin':
-            case 'admin':
-              return rbacContext.isOrgAdmin || rbacContext.isSuperAdmin;
-            case 'event_admin':
-            case 'event admin':
-              return rbacContext.isEventAdmin || rbacContext.isSuperAdmin;
-            default:
-              // For other roles, check against organisationRole or eventAppRole
-              return (
-                rbacContext.organisationRole === role ||
-                rbacContext.eventAppRole === role ||
-                rbacContext.isSuperAdmin
-              );
-          }
+
+    const { allowed } = resolveNavigationAccess({
+      item,
+      authContext,
+      rbacContext,
+      filteredItems,
+      permissionMap,
+      hasAnyPermission: hasAnyPermission ?? null,
+    });
+
+    if (!allowed) {
+      const isInFilteredTree = (list: NavigationItem[], targetId: string): boolean =>
+        list.some(
+          (f) => f.id === targetId || (f.children != null && isInFilteredTree(f.children, targetId))
+        );
+      const isItemVisible = isInFilteredTree(filteredItems, item.id);
+      if (!isItemVisible) {
+        logger.warn("NavigationMenu", "Navigation attempt to filtered item blocked", {
+          itemId: item.id,
+          label: item.label,
+          href: item.href,
         });
       }
-    }
-    
-    // If permission map is empty but item is in filteredItems, trust PaceAppLayout's filtering
-    // This handles the case where NavigationMenu's usePermissions returns empty map
-    // but PaceAppLayout already filtered items correctly
-    if (!hasPermission && (!permissionMap || Object.keys(permissionMap).length === 0) && isItemVisible) {
-      // Permission map is empty but item passed filtering - trust PaceAppLayout
-      // Permission map empty but item passed filtering - trusting PaceAppLayout (removed verbose logging)
-      hasPermission = true;
-    }
-    
-    if (!hasPermission) {
-      // Handle access denied
       if (onNavigationAccessDenied) {
         onNavigationAccessDenied(item);
       }
-      
       if (strictMode) {
         logger.error('NavigationMenu', 'STRICT MODE VIOLATION: User attempted to access protected navigation item without permission', {
           itemId: item.id,
@@ -560,19 +315,16 @@ export const NavigationMenu = React.forwardRef<
           accessLevel: item.accessLevel,
           timestamp: new Date().toISOString()
         });
-        
         if (onStrictModeViolation) {
           onStrictModeViolation(item, 'Insufficient permissions');
         }
       }
-      
-      return; // Don't navigate if access is denied
+      return;
     }
-    
+
     if (onNavigate) {
       onNavigate(item);
     } else if (item.href) {
-      // Default navigation behavior
       window.location.href = item.href;
     }
   };
@@ -586,7 +338,6 @@ export const NavigationMenu = React.forwardRef<
     return false;
   };
 
-  // Handle navigation item selection
   const handleNavigationSelect = (itemId: string) => {
     const item = filteredItems.find(i => i.id === itemId);
     if (item) {
@@ -594,61 +345,6 @@ export const NavigationMenu = React.forwardRef<
     }
   };
 
-  // Render hierarchical navigation item
-  const renderHierarchicalItem = (item: NavigationItem, level: number = 0) => {
-    const hasChildren = item.children && item.children.length > 0;
-    const isExpanded = expandedItems.has(item.id);
-    const itemIsActive = isActiveItem(item);
-
-    return (
-      <li role="none">
-        {hasChildren ? (
-          <>
-            <button
-              onClick={() => toggleExpanded(item.id)}
-              onKeyDown={(e) => handleHierarchicalKeyDown(e, item)}
-              aria-expanded={isExpanded}
-              aria-controls={`submenu-${item.id}`}
-              aria-current={itemIsActive ? "page" : undefined}
-            >
-              <span>{item.label}</span>
-              <ChevronDown aria-hidden="true" />
-            </button>
-            
-            {isExpanded && item.children && (
-              <ul
-                id={`submenu-${item.id}`}
-                role="menu"
-                aria-label={`${item.label} submenu`}
-              >
-                {item.children.map(child => (
-                  <React.Fragment key={child.id}>
-                    {renderHierarchicalItem(child, level + 1)}
-                  </React.Fragment>
-                ))}
-              </ul>
-            )}
-          </>
-        ) : (
-          <a
-            href={item.href || '#'}
-            onClick={(e) => {
-              if (onNavigate && item.href) {
-                e.preventDefault();
-                onNavigate(item);
-              }
-            }}
-            onKeyDown={(e) => handleHierarchicalKeyDown(e, item)}
-            role="menuitem"
-            aria-current={itemIsActive ? "page" : undefined}
-          >
-            {item.label}
-          </a>
-        )}
-      </li>
-    );
-  };
-
   // Render based on mode
   if (mode === 'dropdown') {
     return (
@@ -666,36 +362,40 @@ export const NavigationMenu = React.forwardRef<
           <SelectValue placeholder={buttonText} />
         </SelectTrigger>
         <SelectContent>
-          {filteredItems.map((item) => {
-            const _isActive = isActiveItem(item);
-            return (
-              <SelectItem
-                key={item.id}
-                value={item.id}
-                disabled={!item.href}
-                data-testid={`navigation-menu-item-${item.id}`}
-              >
-                {item.label}
-              </SelectItem>
-            );
-          })}
+          {filteredItems.map((item) => (
+            <SelectItem
+              key={item.id}
+              value={item.id}
+              disabled={!item.href}
+              data-testid={`navigation-menu-item-${item.id}`}
+            >
+              {item.label}
+            </SelectItem>
+          ))}
         </SelectContent>
       </Select>
     );
   }
 
-  // Hierarchical mode
   return (
-    <nav 
+    <nav
       ref={ref}
       className={className}
       aria-label={navigationLabel}
       {...props}
     >
       <ul role="menubar">
-        {filteredItems.map(item => (
+        {filteredItems.map((item) => (
           <React.Fragment key={item.id}>
-            {renderHierarchicalItem(item, 0)}
+            <HierarchicalNavItem
+              item={item}
+              level={0}
+              expandedIds={expandedItems}
+              onToggle={toggleExpanded}
+              onItemClick={handleItemClick}
+              onKeyDown={handleHierarchicalKeyDown}
+              isActiveItem={isActiveItem}
+            />
           </React.Fragment>
         ))}
       </ul>

package/src/components/NavigationMenu/index.ts

@@ -7,4 +7,9 @@
  */
 
 export { NavigationMenu } from './NavigationMenu';
-export type { NavigationMenuProps, NavigationItem, NavigationMode } from './NavigationMenu';
+export type {
+  NavigationMenuProps,
+  NavigationItem,
+  NavigationItemMeta,
+  NavigationMode,
+} from './NavigationMenu';