@jmruthers/pace-core 0.2.6 → 0.4.1

package/src/components/NavigationMenu/NavigationMenu.tsx

@@ -1,698 +0,0 @@
-/**
- * @file Unified Navigation Menu Component
- * @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 18+ - Component framework and hooks
- * - Lucide React - Icon components
- * - Radix UI - Dropdown menu primitives
- * - React Router (optional) - For navigation handling
- * - Tailwind CSS - Styling system
- */
-
-import * as React from "react";
-import { Menu, ChevronDown } from "lucide-react";
-import { cn } from "../../utils/cn";
-import { NavigationMenuProps, NavigationItem } from "./types";
-import { Button } from "../Button";
-import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "../Select";
-import { useUnifiedAuth } from "../../providers/UnifiedAuthProvider";
-import { AccessLevel } from "../../types/unified";
-
-/**
- * Unified NavigationMenu component that supports both dropdown and hierarchical navigation modes.
- * 
- * A flexible navigation menu component with support for icons, current page highlighting,
- * keyboard navigation, and nested menu items.
- * 
- * 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 (Enter, Space, Escape)
- * - 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 with permission requirements
- *   const navItems = [
- *     { 
- *       id: 'dashboard', 
- *       label: 'Dashboard', 
- *       href: '/dashboard', 
- *       icon: 'LayoutDashboard',
- *       permissions: ['dashboard:read']
- *     },
- *     { 
- *       id: 'meals', 
- *       label: 'Meals', 
- *       href: '/meals', 
- *       icon: 'UtensilsCrossed',
- *       permissions: ['meals:read']
- *     },
- *     { 
- *       id: 'admin', 
- *       label: 'Admin Panel', 
- *       href: '/admin', 
- *       icon: 'Shield',
- *       roles: ['admin', 'super_admin']
- *     },
- *     { 
- *       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"
- *       filterByPermissions={true}
- *       auditLog={true}
- *     />
- *   );
- * }
- * ```
- * 
- * @example
- * Custom navigation with external links and actions:
- * ```tsx
- * 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}
- *     />
- *   );
- * }
- * ```
- * 
- * @param props - NavigationMenu component props including items, mode, navigation handlers, and styling options
- * @returns React element with navigation menu functionality
- * 
- * @since 0.1.0
- */
-export const NavigationMenu = React.forwardRef<
-  HTMLDivElement,
-  NavigationMenuProps
->(({ 
-  items, 
-  mode = 'dropdown',
-  currentPath, 
-  onNavigate, 
-  className, 
-  disabled = false,
-  buttonText = "Menu",
-  showIcons = true,
-  navigationLabel = "Main navigation",
-  // NEW: Phase 2 - Enhanced Security Features
-  strictMode = true,
-  auditLog = true,
-  onNavigationAccessDenied,
-  onStrictModeViolation,
-  filterByPermissions = true,
-  ...props 
-}, ref) => {
-  const [expandedItems, setExpandedItems] = React.useState<Set<string>>(new Set());
-  const buttonRef = React.useRef<HTMLButtonElement>(null);
-
-  // Get authentication context
-  let authContext = null;
-  try {
-    authContext = useUnifiedAuth();
-  } catch (error) {
-    // NavigationMenu is being used outside of UnifiedAuthProvider
-    console.warn('[NavigationMenu] useUnifiedAuth not available, running in unauthenticated mode');
-  }
-
-  // NEW: Phase 2 - Enhanced Security Features
-  // Filter navigation items based on permissions
-  const filteredItems = React.useMemo(() => {
-    if (!filterByPermissions || !authContext) return items || [];
-    
-    return (items || []).filter(item => {
-      // Check if item should be hidden
-      if (item.meta?.hidden) return false;
-      
-      // Check permissions if available
-      if (item.permissions && item.permissions.length > 0) {
-        const hasPermission = item.permissions.some(permission => {
-          // Only check string permissions, ignore invalid types
-          if (typeof permission !== 'string') return true;
-          return authContext.hasPermission(permission);
-        });
-        if (!hasPermission) return false;
-      }
-      
-      // Check roles if available
-      if (item.roles && item.roles.length > 0) {
-        const hasRole = item.roles.some(role => {
-          // Only check string roles, ignore invalid types
-          if (typeof role !== 'string') return true;
-          return authContext.hasRole(role);
-        });
-        if (!hasRole) return false;
-      }
-      
-      // Check access level if available
-      if (item.accessLevel) {
-        // Only check string access levels, ignore invalid types
-        if (typeof item.accessLevel === 'string') {
-          // Convert string to AccessLevel enum
-          const accessLevel = item.accessLevel as AccessLevel;
-          const hasAccessLevel = authContext.hasAccessLevel(accessLevel);
-          if (!hasAccessLevel) 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]);
-
-
-  // Handle keyboard navigation for hierarchical mode
-  const handleHierarchicalKeyDown = (event: React.KeyboardEvent, item: NavigationItem) => {
-    switch (event.key) {
-      case 'Enter':
-      case ' ':
-        event.preventDefault();
-        if (item.children && item.children.length > 0) {
-          toggleExpanded(item.id);
-        } else if (item.href) {
-          onNavigate?.(item);
-        }
-        break;
-      case 'Escape':
-        if (expandedItems.has(item.id)) {
-          toggleExpanded(item.id);
-        }
-        break;
-    }
-  };
-
-  // Toggle expanded state for hierarchical items
-  const toggleExpanded = (itemId: string) => {
-    const newExpanded = new Set(expandedItems);
-    if (newExpanded.has(itemId)) {
-      newExpanded.delete(itemId);
-    } else {
-      newExpanded.add(itemId);
-    }
-    setExpandedItems(newExpanded);
-  };
-
-  // Handle navigation item click
-  const handleItemClick = (item: NavigationItem) => {
-    // NEW: Phase 2 - Enhanced Security Features
-    // Log navigation access attempt for audit
-    if (auditLog) {
-      console.log(`[NavigationMenu] Navigation access attempt:`, {
-        itemId: item.id,
-        label: item.label,
-        href: item.href,
-        permissions: item.permissions,
-        roles: item.roles,
-        accessLevel: item.accessLevel,
-        timestamp: new Date().toISOString()
-      });
-    }
-    
-    // Check if user has permission to access this navigation item
-    // For now, allow all access - this will be enhanced with actual permission checking
-    const hasPermission = true; // This will be replaced with actual permission checking
-    
-    if (!hasPermission) {
-      // Handle access denied
-      if (onNavigationAccessDenied) {
-        onNavigationAccessDenied(item.id, 'Insufficient permissions');
-      }
-      
-      if (strictMode) {
-        console.error(`[NavigationMenu] STRICT MODE VIOLATION: User attempted to access protected navigation item without permission`, {
-          itemId: item.id,
-          label: item.label,
-          href: item.href,
-          permissions: item.permissions,
-          roles: item.roles,
-          accessLevel: item.accessLevel,
-          timestamp: new Date().toISOString()
-        });
-        
-        if (onStrictModeViolation) {
-          onStrictModeViolation(item.id, 'Insufficient permissions');
-        }
-      }
-      
-      return; // Don't navigate if access is denied
-    }
-    
-    if (onNavigate) {
-      onNavigate(item);
-    } else if (item.href) {
-      // Default navigation behavior
-      window.location.href = item.href;
-    }
-  };
-
-  // Check if item is currently active
-  const isActiveItem = (item: NavigationItem): boolean => {
-    if (item.isActive !== undefined) return item.isActive;
-    if (currentPath === item.href) return true;
-    if (item.children && item.children.length > 0) {
-      return item.children.some(child => isActiveItem(child));
-    }
-    return false;
-  };
-
-  // Handle navigation item selection
-  const handleNavigationSelect = (itemId: string) => {
-    const item = filteredItems.find(i => i.id === itemId);
-    if (item) {
-      handleItemClick(item);
-    }
-  };
-
-  // 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 ? (
-          <div>
-            <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>
-            )}
-          </div>
-        ) : (
-          <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 (
-      <Select 
-        onValueChange={handleNavigationSelect}
-        className={className}
-        data-testid="navigation-menu-root"
-      >
-        <SelectTrigger 
-          ref={buttonRef}
-          disabled={disabled} 
-          aria-label={buttonText}
-          data-testid="navigation-menu-trigger"
-        >
-          <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>
-            );
-          })}
-        </SelectContent>
-      </Select>
-    );
-  }
-
-  // Hierarchical mode
-  return (
-    <nav 
-      ref={ref}
-      className={className}
-      aria-label={navigationLabel}
-      {...props}
-    >
-      <ul role="menubar">
-        {filteredItems.map(item => (
-          <React.Fragment key={item.id}>
-            {renderHierarchicalItem(item, 0)}
-          </React.Fragment>
-        ))}
-      </ul>
-    </nav>
-  );
-});
-
-NavigationMenu.displayName = "NavigationMenu";