mtrl 0.3.6 → 0.3.8

package/src/components/menu/features/controller.ts

@@ -1,6 +1,9 @@
 // src/components/menu/features/controller.ts
 
 import { MenuConfig, MenuContent, MenuItem, MenuDivider, MenuEvent, MenuSelectEvent } from '../types';
+import { createPositioner } from './position';
+
+let ignoreNextDocumentClick = false;
 
 /**
  * Adds controller functionality to the menu component
@@ -9,7 +12,7 @@ import { MenuConfig, MenuContent, MenuItem, MenuDivider, MenuEvent, MenuSelectEv
  * @param config - Menu configuration
  * @returns Component enhancer with menu controller functionality
  */
-export const withController = (config: MenuConfig) => component => {
+const withController = (config: MenuConfig) => component => {
   if (!component.element) {
     console.warn('Cannot initialize menu controller: missing element');
     return component;
@@ -19,18 +22,30 @@ export const withController = (config: MenuConfig) => component => {
   const state = {
     visible: config.visible || false,
     items: config.items || [],
-    placement: config.placement,
-    activeSubmenu: null,
-    activeSubmenuItem: null,
+    position: config.position,
+    selectedItemId: null as string | null,
+    activeSubmenu: null as HTMLElement,
+    activeSubmenuItem: null as HTMLElement,
     activeItemIndex: -1,
+    submenuLevel: 0, // Track nesting level of submenus
+    activeSubmenus: [] as Array<{
+      element: HTMLElement, 
+      menuItem: HTMLElement, 
+      level: number,
+      isOpening: boolean // Track if submenu is in opening transition
+    }>,
     submenuTimer: null,
     hoverIntent: {
       timer: null,
       activeItem: null
     },
-    component
+    component,
+    keyboardNavActive: false // Track if keyboard navigation is active
   };
 
+  // Create positioner
+  const positioner = createPositioner(component, config);
+
   // Create event helpers
   const eventHelpers = {
     triggerEvent(eventName: string, data: any = {}, originalEvent?: Event) {
@@ -51,6 +66,12 @@ export const withController = (config: MenuConfig) => component => {
    * Gets the anchor element from config
    */
   const getAnchorElement = (): HTMLElement => {
+    // First try to get the resolved anchor from the anchor feature
+    if (component.anchor && typeof component.anchor.getAnchor === 'function') {
+      return component.anchor.getAnchor();
+    }
+
+    // Fall back to config anchor for initial positioning
     const { anchor } = config;
     
     if (typeof anchor === 'string') {
@@ -62,7 +83,13 @@ export const withController = (config: MenuConfig) => component => {
       return element as HTMLElement;
     }
     
-    return anchor;
+    // Handle component with element property
+    if (typeof anchor === 'object' && anchor !== null && 'element' in anchor) {
+      return anchor.element;
+    }
+    
+    // Handle direct HTML element
+    return anchor as HTMLElement;
   };
 
   /**
@@ -74,7 +101,7 @@ export const withController = (config: MenuConfig) => component => {
     
     itemElement.className = itemClass;
     itemElement.setAttribute('role', 'menuitem');
-    itemElement.setAttribute('tabindex', '-1');
+    itemElement.setAttribute('tabindex', '-1'); // Set to -1 by default, will update when needed
     itemElement.setAttribute('data-id', item.id);
     itemElement.setAttribute('data-index', index.toString());
     
@@ -85,6 +112,14 @@ export const withController = (config: MenuConfig) => component => {
       itemElement.setAttribute('aria-disabled', 'false');
     }
     
+    if (state.selectedItemId && item.id === state.selectedItemId) {
+      itemElement.classList.add(`${itemClass}--selected`);
+      itemElement.setAttribute('aria-selected', 'true');
+    } else {
+      itemElement.setAttribute('aria-selected', 'false');
+    }
+
+
     if (item.hasSubmenu) {
       itemElement.classList.add(`${itemClass}--submenu`);
       itemElement.setAttribute('aria-haspopup', 'true');
@@ -121,8 +156,23 @@ export const withController = (config: MenuConfig) => component => {
     
     // Add event listeners
     if (!item.disabled) {
+      // Mouse events
       itemElement.addEventListener('click', (e) => handleItemClick(e, item, index));
       
+      // Focus and blur events for proper focus styling
+      itemElement.addEventListener('focus', () => {
+        state.activeItemIndex = index;
+        state.keyboardNavActive = true;
+      });
+      
+      // Additional keyboard event handler for accessibility
+      itemElement.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          handleItemClick(e, item, index);
+        }
+      });
+      
       if (item.hasSubmenu && config.openSubmenuOnHover) {
         itemElement.addEventListener('mouseenter', () => handleSubmenuHover(item, index, itemElement));
         itemElement.addEventListener('mouseleave', handleSubmenuLeave);
@@ -170,128 +220,6 @@ export const withController = (config: MenuConfig) => component => {
     component.element.appendChild(menuList);
   };
 
-  /**
-   * Positions the menu relative to its anchor
-   */
-  const positionMenu = (): void => {
-    const anchor = getAnchorElement();
-    if (!anchor) return;
-    
-    const menuElement = component.element;
-    const anchorRect = anchor.getBoundingClientRect();
-    const { placement } = state;
-    const offset = config.offset || 8;
-    
-    // Reset styles for measurement
-    menuElement.style.top = '0';
-    menuElement.style.left = '0';
-    menuElement.style.right = 'auto';
-    menuElement.style.bottom = 'auto';
-    menuElement.style.maxHeight = config.maxHeight || '';
-    
-    // Take measurements
-    const menuRect = menuElement.getBoundingClientRect();
-    const viewportWidth = window.innerWidth;
-    const viewportHeight = window.innerHeight;
-    
-    // Calculate position based on placement
-    let top = 0;
-    let left = 0;
-    
-    switch (placement) {
-      case 'top-start':
-        top = anchorRect.top - menuRect.height - offset;
-        left = anchorRect.left;
-        break;
-      case 'top':
-        top = anchorRect.top - menuRect.height - offset;
-        left = anchorRect.left + (anchorRect.width / 2) - (menuRect.width / 2);
-        break;
-      case 'top-end':
-        top = anchorRect.top - menuRect.height - offset;
-        left = anchorRect.right - menuRect.width;
-        break;
-      case 'right-start':
-        top = anchorRect.top;
-        left = anchorRect.right + offset;
-        break;
-      case 'right':
-        top = anchorRect.top + (anchorRect.height / 2) - (menuRect.height / 2);
-        left = anchorRect.right + offset;
-        break;
-      case 'right-end':
-        top = anchorRect.bottom - menuRect.height;
-        left = anchorRect.right + offset;
-        break;
-      case 'bottom-start':
-        top = anchorRect.bottom + offset;
-        left = anchorRect.left;
-        break;
-      case 'bottom':
-        top = anchorRect.bottom + offset;
-        left = anchorRect.left + (anchorRect.width / 2) - (menuRect.width / 2);
-        break;
-      case 'bottom-end':
-        top = anchorRect.bottom + offset;
-        left = anchorRect.right - menuRect.width;
-        break;
-      case 'left-start':
-        top = anchorRect.top;
-        left = anchorRect.left - menuRect.width - offset;
-        break;
-      case 'left':
-        top = anchorRect.top + (anchorRect.height / 2) - (menuRect.height / 2);
-        left = anchorRect.left - menuRect.width - offset;
-        break;
-      case 'left-end':
-        top = anchorRect.bottom - menuRect.height;
-        left = anchorRect.left - menuRect.width - offset;
-        break;
-    }
-    
-    // Auto-flip if needed to stay in viewport
-    if (config.autoFlip) {
-      // Flip vertically if needed
-      if (top < 0) {
-        if (placement.startsWith('top')) {
-          top = anchorRect.bottom + offset;
-        }
-      } else if (top + menuRect.height > viewportHeight) {
-        if (placement.startsWith('bottom')) {
-          top = anchorRect.top - menuRect.height - offset;
-        }
-      }
-      
-      // Flip horizontally if needed
-      if (left < 0) {
-        if (placement.startsWith('left')) {
-          left = anchorRect.right + offset;
-        } else if (placement.includes('start')) {
-          left = 0;
-        }
-      } else if (left + menuRect.width > viewportWidth) {
-        if (placement.startsWith('right')) {
-          left = anchorRect.left - menuRect.width - offset;
-        } else if (placement.includes('end')) {
-          left = viewportWidth - menuRect.width;
-        }
-      }
-    }
-    
-    // Apply position
-    menuElement.style.top = `${top}px`;
-    menuElement.style.left = `${left}px`;
-    
-    // Ensure it's in viewport
-    const updatedRect = menuElement.getBoundingClientRect();
-    if (updatedRect.top < 0) {
-      menuElement.style.top = '0';
-    }
-    if (updatedRect.left < 0) {
-      menuElement.style.left = '0';
-    }
-  };
-
   /**
    * Clean up hover intent timer
    */
@@ -303,6 +231,56 @@ export const withController = (config: MenuConfig) => component => {
     }
   };
 
+  /**
+   * Sets focus appropriately based on interaction type
+   * For keyboard interactions, focuses the first item
+   * For mouse interactions, makes the menu container focusable but doesn't auto-focus
+   * 
+   * @param {'keyboard'|'mouse'} interactionType - Type of interaction that opened the menu
+   */
+  const handleFocus = (interactionType: 'keyboard' | 'mouse'): void => {
+    // Reset active item index
+    state.activeItemIndex = -1;
+    
+    if (interactionType === 'keyboard') {
+      // Find all focusable items
+      const items = Array.from(
+        component.element.querySelectorAll(`.${component.getClass('menu-item')}:not(.${component.getClass('menu-item--disabled')})`)
+      ) as HTMLElement[];
+      
+      if (items.length > 0) {
+        // Set all items to tabindex -1 except the first one
+        items.forEach((item, index) => {
+          item.setAttribute('tabindex', index === 0 ? '0' : '-1');
+        });
+        
+        // Focus the first item for keyboard navigation
+        items[0].focus();
+        state.activeItemIndex = 0;
+        state.keyboardNavActive = true;
+      } else {
+        // If no items, focus the menu itself
+        component.element.setAttribute('tabindex', '0');
+        component.element.focus();
+      }
+    } else {
+      // For mouse interaction, make the menu focusable but don't auto-focus
+      component.element.setAttribute('tabindex', '-1');
+      
+      // Still set up the tabindex correctly for potential keyboard navigation
+      const items = Array.from(
+        component.element.querySelectorAll(`.${component.getClass('menu-item')}:not(.${component.getClass('menu-item--disabled')})`)
+      ) as HTMLElement[];
+      
+      if (items.length > 0) {
+        // Set all items to tabindex -1 except the first one
+        items.forEach((item, index) => {
+          item.setAttribute('tabindex', index === 0 ? '0' : '-1');
+        });
+      }
+    }
+  };
+
   /**
    * Handles click on a menu item
    */
@@ -337,15 +315,31 @@ export const withController = (config: MenuConfig) => component => {
   const handleSubmenuClick = (item: MenuItem, index: number, itemElement: HTMLElement, viaKeyboard = false): void => {
     if (!item.submenu || !item.hasSubmenu) return;
     
+    // Check if the submenu is already open
     const isOpen = itemElement.getAttribute('aria-expanded') === 'true';
     
+    // Find if any submenu is currently in opening transition
+    const anySubmenuTransitioning = state.activeSubmenus.some(s => s.isOpening);
+    
+    // Completely ignore clicks during any submenu transition
+    if (anySubmenuTransitioning) {
+      return;
+    }
+    
     if (isOpen) {
-      // Close submenu
-      closeSubmenu();
-    } else {
-      // Close any open submenu
-      closeSubmenu();
+      // Close submenu - only if fully open
+      // Find the closest submenu level
+      const currentLevel = parseInt(
+        itemElement.closest(`.${component.getClass('menu--submenu')}`)?.getAttribute('data-level') || '0',
+        10
+      );
       
+      // Close this level + 1 and deeper
+      closeSubmenuAtLevel(currentLevel + 1);
+      
+      // Reset expanded state
+      itemElement.setAttribute('aria-expanded', 'false');
+    } else {
       // Open new submenu
       openSubmenu(item, index, itemElement, viaKeyboard);
     }
@@ -357,6 +351,9 @@ export const withController = (config: MenuConfig) => component => {
   const handleSubmenuHover = (item: MenuItem, index: number, itemElement: HTMLElement): void => {
     if (!config.openSubmenuOnHover || !item.hasSubmenu) return;
     
+    // If keyboard navigation is active, don't open submenu on hover
+    if (state.keyboardNavActive) return;
+    
     // Clear any existing timers
     clearHoverIntent();
     clearSubmenuTimer();
@@ -368,7 +365,6 @@ export const withController = (config: MenuConfig) => component => {
       if (isCurrentlyHovered) {
         // Only close and reopen if this is a different submenu item
         if (state.activeSubmenuItem !== itemElement) {
-          closeSubmenu();
           openSubmenu(item, index, itemElement);
         }
       }
@@ -380,6 +376,9 @@ export const withController = (config: MenuConfig) => component => {
    * Handles mouse leave from submenu
    */
   const handleSubmenuLeave = (e: MouseEvent): void => {
+    // If keyboard navigation is active, don't close submenu on mouse leave
+    if (state.keyboardNavActive) return;
+    
     // Clear hover intent
     clearHoverIntent();
     
@@ -397,7 +396,7 @@ export const withController = (config: MenuConfig) => component => {
         const overMenuItem = menuItemElement.matches(':hover');
         
         if (!overSubmenu && !overMenuItem) {
-          closeSubmenu();
+          closeSubmenuAtLevel(state.submenuLevel);
         }
       }
       
@@ -406,22 +405,45 @@ export const withController = (config: MenuConfig) => component => {
   };
 
   /**
-   * Opens a submenu
+   * Opens a submenu with proper animation and positioning
    */
   const openSubmenu = (item: MenuItem, index: number, itemElement: HTMLElement, viaKeyboard = false): void => {
     if (!item.submenu || !item.hasSubmenu) return;
     
-    // Close any existing submenu
-    closeSubmenu();
+    // If opened via keyboard, update the keyboard navigation state
+    if (viaKeyboard) {
+      state.keyboardNavActive = true;
+    }
+    
+    // Get current level of the submenu we're opening
+    const currentLevel = itemElement.closest(`.${component.getClass('menu--submenu')}`) 
+      ? parseInt(itemElement.closest(`.${component.getClass('menu--submenu')}`).getAttribute('data-level') || '0', 10) + 1
+      : 1;
+
+    // Close any deeper level submenus first, preserving the current level
+    closeSubmenuAtLevel(currentLevel);
+    
+    // Check if this submenu is already in opening state - if so, do nothing
+    const existingSubmenuIndex = state.activeSubmenus.findIndex(
+      s => s.menuItem === itemElement && s.isOpening
+    );
+    if (existingSubmenuIndex >= 0) {
+      return; // Already opening this submenu, don't restart the process
+    }
     
     // Set expanded state
     itemElement.setAttribute('aria-expanded', 'true');
     
-    // Create submenu element
+    // Create submenu element with proper classes and attributes
     const submenuElement = document.createElement('div');
     submenuElement.className = `${component.getClass('menu')} ${component.getClass('menu--submenu')}`;
     submenuElement.setAttribute('role', 'menu');
     submenuElement.setAttribute('tabindex', '-1');
+    submenuElement.setAttribute('data-level', currentLevel.toString());
+    submenuElement.setAttribute('data-parent-item', item.id);
+    
+    // Increase z-index for each level of submenu
+    submenuElement.style.zIndex = `${1000 + (currentLevel * 10)}`;
     
     // Create submenu list
     const submenuList = document.createElement('ul');
@@ -442,58 +464,169 @@ export const withController = (config: MenuConfig) => component => {
     });
     
     submenuElement.appendChild(submenuList);
+    
+    // Add to DOM to enable measurement and transitions
     document.body.appendChild(submenuElement);
     
+    // Position the submenu using our positioner with the current nesting level
+    positioner.positionSubmenu(submenuElement, itemElement, currentLevel);
+    
     // Setup keyboard navigation for submenu
     submenuElement.addEventListener('keydown', handleMenuKeydown);
     
     // Add mouseenter event to prevent closing
     submenuElement.addEventListener('mouseenter', () => {
-      clearSubmenuTimer();
+      if (!state.keyboardNavActive) {
+        clearSubmenuTimer();
+      }
     });
     
     // Add mouseleave event to handle closing
     submenuElement.addEventListener('mouseleave', (e) => {
-      handleSubmenuLeave(e);
+      if (!state.keyboardNavActive) {
+        handleSubmenuLeave(e);
+      }
     });
     
-    // Position the submenu next to its parent item
-    const itemRect = itemElement.getBoundingClientRect();
-    
-    // Default position is to the right
-    submenuElement.style.top = `${itemRect.top}px`;
-    submenuElement.style.left = `${itemRect.right + 8}px`;
-    
-    // Check if submenu would be outside viewport and adjust if needed
-    const submenuRect = submenuElement.getBoundingClientRect();
-    const viewportWidth = window.innerWidth;
+    // Setup submenu event handlers for nested submenus
+    const setupNestedSubmenuHandlers = (parent: HTMLElement) => {
+      const submenuItems = parent.querySelectorAll(`.${component.getClass('menu-item--submenu')}`) as NodeListOf<HTMLElement>;
+      
+      submenuItems.forEach((menuItem) => {
+        const itemIndex = parseInt(menuItem.getAttribute('data-index'), 10);
+        const menuItemData = item.submenu[itemIndex] as MenuItem;
+        
+        if (menuItemData && menuItemData.hasSubmenu) {
+          // Add hover handler for nested submenus
+          if (config.openSubmenuOnHover) {
+            menuItem.addEventListener('mouseenter', () => {
+              handleNestedSubmenuHover(menuItemData, itemIndex, menuItem);
+            });
+            menuItem.addEventListener('mouseleave', handleSubmenuLeave);
+          }
+          
+          // Add click handler for nested submenus
+          menuItem.addEventListener('click', (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            handleNestedSubmenuClick(menuItemData, itemIndex, menuItem, false);
+          });
+        }
+      });
+    };
     
-    if (submenuRect.right > viewportWidth) {
-      // Position to the left instead
-      submenuElement.style.left = 'auto';
-      submenuElement.style.right = `${window.innerWidth - itemRect.left + 8}px`;
-    }
+    // Setup handlers for any nested submenus
+    setupNestedSubmenuHandlers(submenuElement);
     
-    // Add to state
+    // Update state with active submenu
     state.activeSubmenu = submenuElement;
     state.activeSubmenuItem = itemElement;
     
-    // Add submenu events
+    // Add to active submenus array to maintain hierarchy
+    state.activeSubmenus.push({
+      element: submenuElement, 
+      menuItem: itemElement, 
+      level: currentLevel,
+      isOpening: true // Mark as in opening transition
+    });
+    
+    // Update submenu level
+    state.submenuLevel = currentLevel;
+    
+    // Add document events for this submenu
     document.addEventListener('click', handleDocumentClickForSubmenu);
-    window.addEventListener('resize', handleWindowResizeForSubmenu);
-    window.addEventListener('scroll', handleWindowScrollForSubmenu);
+    window.addEventListener('resize', handleWindowResizeForSubmenu, { passive: true });
+    window.addEventListener('scroll', handleWindowScrollForSubmenu, { passive: true });
     
-    // Make visible
-    setTimeout(() => {
+    // Make visible with animation
+    requestAnimationFrame(() => {
       submenuElement.classList.add(`${component.getClass('menu--visible')}`);
       
+      // Wait for transition to complete before marking as fully opened
+      // This should match your CSS transition duration
+      setTimeout(() => {
+        // Find this submenu in the active submenus array and update its state
+        const index = state.activeSubmenus.findIndex(s => s.element === submenuElement);
+        if (index !== -1) {
+          state.activeSubmenus[index].isOpening = false;
+        }
+      }, 300); // Adjust to match your transition duration
+      
       // If opened via keyboard, focus the first item in the submenu
       if (viaKeyboard && submenuItems.length > 0) {
+        submenuItems[0].setAttribute('tabindex', '0');
+        
+        // Set other items to -1
+        for (let i = 1; i < submenuItems.length; i++) {
+          submenuItems[i].setAttribute('tabindex', '-1');
+        }
+        
+        // Focus with a short delay to allow animation to start
         setTimeout(() => {
           submenuItems[0].focus();
         }, 50);
       }
-    }, 10);
+    });
+  };
+
+  /**
+   * Handles hover on a nested submenu item
+   */
+  const handleNestedSubmenuHover = (item: MenuItem, index: number, itemElement: HTMLElement): void => {
+    if (!config.openSubmenuOnHover || !item.hasSubmenu || state.keyboardNavActive) return;
+    
+    // Clear any existing timers
+    clearHoverIntent();
+    clearSubmenuTimer();
+    
+    // Set hover intent with a slightly longer delay for nested menus
+    state.hoverIntent.activeItem = itemElement;
+    state.hoverIntent.timer = setTimeout(() => {
+      const isCurrentlyHovered = itemElement.matches(':hover');
+      if (isCurrentlyHovered) {
+        // Find the closest submenu level of this item
+        const currentLevel = parseInt(
+          itemElement.closest(`.${component.getClass('menu--submenu')}`)?.getAttribute('data-level') || '1',
+          10
+        );
+        
+        // Open the nested submenu (will handle closing deeper levels properly)
+        handleNestedSubmenuClick(item, index, itemElement, false);
+      }
+      state.hoverIntent.timer = null;
+    }, 120); // Slightly longer delay for nested submenus
+  };
+
+  /**
+   * Handles click on a nested submenu item
+   */
+  const handleNestedSubmenuClick = (item: MenuItem, index: number, itemElement: HTMLElement, viaKeyboard = false): void => {
+    if (!item.submenu || !item.hasSubmenu) return;
+    
+    // Check if the submenu is already open
+    const isOpen = itemElement.getAttribute('aria-expanded') === 'true';
+    
+    // Find if any submenu is currently in opening transition
+    const anySubmenuTransitioning = state.activeSubmenus.some(s => s.isOpening);
+    
+    // Completely ignore clicks during any submenu transition
+    if (anySubmenuTransitioning) {
+      return;
+    }
+    
+    if (isOpen) {
+      // Find the closest submenu level
+      const currentLevel = parseInt(
+        itemElement.closest(`.${component.getClass('menu--submenu')}`)?.getAttribute('data-level') || '1',
+        10
+      );
+      
+      // Close submenus at and deeper than the next level
+      closeSubmenuAtLevel(currentLevel + 1);
+    } else {
+      // Open the nested submenu
+      openSubmenu(item, index, itemElement, viaKeyboard);
+    }
   };
 
   /**
@@ -507,36 +640,94 @@ export const withController = (config: MenuConfig) => component => {
   };
 
   /**
-   * Closes any open submenu
+   * Closes submenus at or deeper than the specified level
+   * @param level - The level to start closing from
    */
-  const closeSubmenu = (): void => {
-    // Clear timers
+  const closeSubmenuAtLevel = (level: number): void => {
+    // Clear any hover intent or submenu timers
     clearHoverIntent();
     clearSubmenuTimer();
     
-    if (!state.activeSubmenu) return;
+    // Find submenus at or deeper than the specified level
+    const submenusCopy = [...state.activeSubmenus];
+    const submenuIndicesToRemove = [];
     
-    // Remove expanded state from all items
-    if (state.activeSubmenuItem) {
-      state.activeSubmenuItem.setAttribute('aria-expanded', 'false');
+    // Identify which submenus to remove, working from deepest level first
+    for (let i = submenusCopy.length - 1; i >= 0; i--) {
+      if (submenusCopy[i].level >= level) {
+        const submenuToClose = submenusCopy[i];
+        
+        // Set aria-expanded attribute to false on the parent menu item
+        if (submenuToClose.menuItem) {
+          submenuToClose.menuItem.setAttribute('aria-expanded', 'false');
+        }
+        
+        // Hide with animation
+        submenuToClose.element.classList.remove(`${component.getClass('menu--visible')}`);
+        
+        // Schedule for removal
+        setTimeout(() => {
+          if (submenuToClose.element.parentNode) {
+            submenuToClose.element.parentNode.removeChild(submenuToClose.element);
+          }
+        }, 200);
+        
+        // Mark for removal from state
+        submenuIndicesToRemove.push(i);
+      }
     }
     
-    // Remove submenu element with animation
-    state.activeSubmenu.classList.remove(`${component.getClass('menu--visible')}`);
+    // Remove the closed submenus from state
+    submenuIndicesToRemove.forEach(index => {
+      state.activeSubmenus.splice(index, 1);
+    });
+    
+    // Update active submenu references based on what's left
+    if (state.activeSubmenus.length > 0) {
+      const deepestRemaining = state.activeSubmenus[state.activeSubmenus.length - 1];
+      state.activeSubmenu = deepestRemaining.element;
+      state.activeSubmenuItem = deepestRemaining.menuItem;
+      state.submenuLevel = deepestRemaining.level;
+    } else {
+      state.activeSubmenu = null;
+      state.activeSubmenuItem = null;
+      state.submenuLevel = 0;
+    }
+  };
+
+  /**
+   * Closes all submenus
+   */
+  const closeSubmenu = (): void => {
+    // Clear timers
+    clearHoverIntent();
+    clearSubmenuTimer();
     
-    // Store reference for cleanup
-    const submenuToRemove = state.activeSubmenu;
+    if (state.activeSubmenus.length === 0) return;
     
-    // Remove after animation
-    setTimeout(() => {
-      if (submenuToRemove && submenuToRemove.parentNode) {
-        submenuToRemove.parentNode.removeChild(submenuToRemove);
+    // Close all active submenus
+    [...state.activeSubmenus].forEach(submenu => {
+      // Remove expanded state from parent item
+      if (submenu.menuItem) {
+        submenu.menuItem.setAttribute('aria-expanded', 'false');
       }
-    }, 200);
+      
+      // Remove submenu element with animation
+      submenu.element.classList.remove(`${component.getClass('menu--visible')}`);
+      
+      // Remove after animation
+      setTimeout(() => {
+        if (submenu.element.parentNode) {
+          submenu.element.parentNode.removeChild(submenu.element);
+        }
+      }, 200);
+    });
     
     // Clear state
     state.activeSubmenu = null;
     state.activeSubmenuItem = null;
+    state.activeSubmenus = [];
+    state.submenuLevel = 0;
     
     // Remove document events
     document.removeEventListener('click', handleDocumentClickForSubmenu);
@@ -567,56 +758,96 @@ export const withController = (config: MenuConfig) => component => {
    * Handles window resize for submenu
    */
   const handleWindowResizeForSubmenu = (): void => {
-    // Reposition or close submenu on resize
-    closeSubmenu();
+    // Reposition open submenu on resize
+    if (state.activeSubmenu && state.activeSubmenuItem) {
+      positioner.positionSubmenu(state.activeSubmenu, state.activeSubmenuItem, state.submenuLevel);
+    }
   };
 
   /**
    * Handles window scroll for submenu
+   * Repositions the submenu to stay attached to its parent during scrolling
    */
   const handleWindowScrollForSubmenu = (): void => {
-    // Reposition or close submenu on scroll
-    closeSubmenu();
+    // Use requestAnimationFrame to optimize scroll performance
+    window.requestAnimationFrame(() => {
+      // Only reposition if we have an active submenu
+      if (state.activeSubmenu && state.activeSubmenuItem) {
+        positioner.positionSubmenu(state.activeSubmenu, state.activeSubmenuItem, state.submenuLevel);
+      }
+    });
   };
 
   /**
    * Opens the menu
+   * @param {Event} [event] - Optional event that triggered the open
+   * @param {'mouse'|'keyboard'} [interactionType='mouse'] - Type of interaction that triggered the open
    */
-  /**
-   * Opens the menu
-   */
-  const openMenu = (event?: Event): void => {
+  const openMenu = (event?: Event, interactionType: 'mouse' | 'keyboard' = 'mouse'): void => {
     if (state.visible) return;
     
+    // Set keyboard navigation state based on interaction type
+    state.keyboardNavActive = interactionType === 'keyboard';
+    
     // Update state
     state.visible = true;
     
-    // Add the menu to the DOM if it's not already there
+    // First, remove any existing document click listener
+    document.removeEventListener('click', handleDocumentClick);
+    
+    // Step 1: Add the menu to the DOM if it's not already there with initial hidden state
     if (!component.element.parentNode) {
+      // Apply explicit initial styling to ensure it doesn't flash
+      component.element.classList.remove(`${component.getClass('menu--visible')}`);
+      component.element.setAttribute('aria-hidden', 'true');
+      component.element.style.transform = 'scaleY(0)';
+      component.element.style.opacity = '0';
+      
+      // Add to DOM
       document.body.appendChild(component.element);
     }
     
-    // Set attributes
-    component.element.setAttribute('aria-hidden', 'false');
-    component.element.classList.add(`${component.getClass('menu--visible')}`);
-    
-    // Position
-    positionMenu();
+    // Step 2: Position the menu (will be invisible)
+    const anchorElement = getAnchorElement();
+    if (anchorElement) {
+      positioner.positionMenu(anchorElement);
+    }
     
-    // Focus first item
+    // Step 3: Use a small delay to ensure DOM operations are complete
     setTimeout(() => {
-      focusFirstItem();
-    }, 100);
-    
-    // Add document events
-    if (config.closeOnClickOutside) {
-      document.addEventListener('click', handleDocumentClick);
-    }
-    if (config.closeOnEscape) {
-      document.addEventListener('keydown', handleDocumentKeydown);
-    }
-    window.addEventListener('resize', handleWindowResize);
-    window.addEventListener('scroll', handleWindowScroll);
+      // Set attributes for accessibility
+      component.element.setAttribute('aria-hidden', 'false');
+      
+      // Remove the inline styles we added
+      component.element.style.transform = '';
+      component.element.style.opacity = '';
+      
+      // Force a reflow before adding the visible class
+      void component.element.getBoundingClientRect();
+      
+      // Add visible class to start the CSS transition
+      component.element.classList.add(`${component.getClass('menu--visible')}`);
+      
+      // Step 4: Focus based on interaction type (after animation starts)
+      setTimeout(() => {
+        handleFocus(interactionType);
+      }, 100);
+      
+      // Add the document click handler on the next event loop 
+      // after the current click is fully processed
+      setTimeout(() => {
+        if (config.closeOnClickOutside && state.visible) {
+          document.addEventListener('click', handleDocumentClick);
+        }
+        
+        // Add other document events normally
+        if (config.closeOnEscape) {
+          document.addEventListener('keydown', handleDocumentKeydown);
+        }
+        window.addEventListener('resize', handleWindowResize, { passive: true });
+        window.addEventListener('scroll', handleWindowScroll, { passive: true });
+      }, 0);
+    }, 20); // Short delay for browser to process
     
     // Trigger event
     eventHelpers.triggerEvent('open', {}, event);
@@ -624,10 +855,22 @@ export const withController = (config: MenuConfig) => component => {
 
   /**
    * Closes the menu
+   * @param {Event} [event] - Optional event that triggered the close
+   * @param {boolean} [restoreFocus=true] - Whether to restore focus to the anchor element
+   * @param {boolean} [skipAnimation=false] - Whether to skip animation (for focus changes)
    */
-  const closeMenu = (event?: Event): void => {
+  const closeMenu = (event?: Event, restoreFocus: boolean = true, skipAnimation: boolean = false): void => {
     if (!state.visible) return;
     
+    // Check if we're in a tab navigation - if so, don't restore focus
+    const isTabNavigation = document.body.hasAttribute('data-menu-tab-navigation');
+    if (isTabNavigation) {
+      restoreFocus = false;
+    }
+    
+    // Reset keyboard navigation state on close
+    state.keyboardNavActive = false;
+    
     // Close any open submenu first
     closeSubmenu();
     
@@ -638,38 +881,99 @@ export const withController = (config: MenuConfig) => component => {
     component.element.setAttribute('aria-hidden', 'true');
     component.element.classList.remove(`${component.getClass('menu--visible')}`);
     
+    // Store anchor reference before potentially removing the menu
+    const anchorElement = getAnchorElement();
+    
     // Remove document events
     document.removeEventListener('click', handleDocumentClick);
     document.removeEventListener('keydown', handleDocumentKeydown);
     window.removeEventListener('resize', handleWindowResize);
     window.removeEventListener('scroll', handleWindowScroll);
     
-    // Trigger event
-    eventHelpers.triggerEvent('close', {}, event);
+    // Trigger event with added data
+    eventHelpers.triggerEvent('close', {
+      isFocusRelated: event instanceof FocusEvent,
+      shouldRestoreFocus: restoreFocus,
+      isTabNavigation: isTabNavigation || event?.key === 'Tab'
+    }, event);
     
-    // Remove from DOM after animation completes
+    // Determine animation duration - for tab navigation we want to close immediately
+    const animationDuration = skipAnimation ? 0 : 300;
+    
+    // Remove from DOM after animation completes (or immediately if skipAnimation)
     setTimeout(() => {
       if (component.element.parentNode && !state.visible) {
         component.element.parentNode.removeChild(component.element);
+        
+        // Only restore focus if explicitly requested AND not in tab navigation
+        if (restoreFocus && anchorElement && !isTabNavigation && event?.type !== 'click') {
+          // Additional check to make sure we're not in an ongoing tab navigation
+          if (!document.body.hasAttribute('data-menu-tab-navigation')) {
+            requestAnimationFrame(() => {
+              anchorElement.focus();
+            });
+          }
+        }
       }
-    }, 300); // Match the animation duration in CSS
+    }, animationDuration);
   };
 
   /**
    * Toggles the menu
    */
-  const toggleMenu = (event?: Event): void => {
+  const toggleMenu = (event?: Event, interactionType: 'mouse' | 'keyboard' = 'mouse'): void => {
     if (state.visible) {
       closeMenu(event);
     } else {
-      openMenu(event);
+      // Determine interaction type from event
+      if (event) {
+        if (event instanceof KeyboardEvent) {
+          interactionType = 'keyboard';
+        } else if (event instanceof MouseEvent) {
+          interactionType = 'mouse';
+        }
+      }
+      openMenu(event, interactionType);
     }
   };
 
+  /**
+   * Updates the selected state of menu items
+   * @param itemId - The ID of the item to mark as selected, or null to clear selection
+   */
+  const updateSelectedState = (itemId: string | null): void => {
+    if (!component.element) return;
+    
+    // Get all menu items
+    const menuItems = component.element.querySelectorAll(`.${component.getClass('menu-item')}`) as NodeListOf<HTMLElement>;
+    
+    // Update selected state for each item
+    menuItems.forEach(item => {
+      const currentItemId = item.getAttribute('data-id');
+      
+      if (currentItemId === itemId) {
+        item.classList.add(`${component.getClass('menu-item--selected')}`);
+        item.setAttribute('aria-selected', 'true');
+      } else {
+        item.classList.remove(`${component.getClass('menu-item--selected')}`);
+        item.setAttribute('aria-selected', 'false');
+      }
+    });
+    
+    // Also update state
+    state.selectedItemId = itemId;
+  };
+
   /**
    * Handles document click
    */
   const handleDocumentClick = (e: MouseEvent): void => {
+    // If we should ignore this click (happens right after opening), reset the flag and return
+    if (ignoreNextDocumentClick) {
+      ignoreNextDocumentClick = false;
+      return;
+    }
+    
     // Don't close if clicked inside menu
     if (component.element.contains(e.target as Node)) {
       return;
@@ -690,7 +994,8 @@ export const withController = (config: MenuConfig) => component => {
    */
   const handleDocumentKeydown = (e: KeyboardEvent): void => {
     if (e.key === 'Escape') {
-      closeMenu(e);
+      // When closing with Escape, always restore focus
+      closeMenu(e, true);
     }
   };
 
@@ -699,37 +1004,42 @@ export const withController = (config: MenuConfig) => component => {
    */
   const handleWindowResize = (): void => {
     if (state.visible) {
-      positionMenu();
+      const anchorElement = getAnchorElement();
+      if (anchorElement) {
+        positioner.positionMenu(anchorElement);
+      }
     }
   };
 
   /**
    * Handles window scroll
+   * Repositions the menu to stay attached to its anchor during scrolling
    */
   const handleWindowScroll = (): void => {
     if (state.visible) {
-      positionMenu();
+      // Use requestAnimationFrame to optimize scroll performance
+      window.requestAnimationFrame(() => {
+        // Reposition the main menu to stay attached to anchor when scrolling
+        const anchorElement = getAnchorElement();
+        if (anchorElement) {
+          positioner.positionMenu(anchorElement);
+        }
+        
+        // Also reposition any open submenu relative to its parent menu item
+        if (state.activeSubmenu && state.activeSubmenuItem) {
+          positioner.positionSubmenu(state.activeSubmenu, state.activeSubmenuItem, state.submenuLevel);
+        }
+      });
     }
   };
 
-  /**
-   * Sets focus to the menu itself, but doesn't auto-select the first item
-   * This improves usability by not having an item automatically selected
-   */
-  const focusFirstItem = (): void => {
-    // Instead of focusing the first item directly, focus the menu container
-    // which will still allow keyboard navigation to work
-    component.element.setAttribute('tabindex', '0');
-    component.element.focus();
-    
-    // Reset active item index
-    state.activeItemIndex = -1;
-  };
-
   /**
    * Handles keydown events on the menu or submenu
    */
   const handleMenuKeydown = (e: KeyboardEvent): void => {
+    // Set keyboard navigation active flag
+    state.keyboardNavActive = true;
+    
     // Determine if this event is from the main menu or a submenu
     const isSubmenu = state.activeSubmenu && state.activeSubmenu.contains(e.target as Node);
     
@@ -750,17 +1060,28 @@ export const withController = (config: MenuConfig) => component => {
       focusedItemIndex = items.indexOf(focusedElement);
     }
     
+    // Function to update tabindex and focus a specific item
+    const focusItem = (index: number) => {
+      // Set all items to tabindex -1
+      items.forEach(item => item.setAttribute('tabindex', '-1'));
+      
+      // Set the target item to tabindex 0 and focus it
+      items[index].setAttribute('tabindex', '0');
+      items[index].focus();
+    };
+    
     switch (e.key) {
       case 'ArrowDown':
       case 'Down':
         e.preventDefault();
         // If no item is active, select the first one
         if (focusedItemIndex < 0) {
-          items[0].focus();
+          focusItem(0);
         } else if (focusedItemIndex < items.length - 1) {
-          items[focusedItemIndex + 1].focus();
+          focusItem(focusedItemIndex + 1);
         } else {
-          items[0].focus();
+          // Wrap to first item
+          focusItem(0);
         }
         break;
         
@@ -769,22 +1090,23 @@ export const withController = (config: MenuConfig) => component => {
         e.preventDefault();
         // If no item is active, select the last one
         if (focusedItemIndex < 0) {
-          items[items.length - 1].focus();
+          focusItem(items.length - 1);
         } else if (focusedItemIndex > 0) {
-          items[focusedItemIndex - 1].focus();
+          focusItem(focusedItemIndex - 1);
         } else {
-          items[items.length - 1].focus();
+          // Wrap to last item
+          focusItem(items.length - 1);
         }
         break;
         
       case 'Home':
         e.preventDefault();
-        items[0].focus();
+        focusItem(0);
         break;
         
       case 'End':
         e.preventDefault();
-        items[items.length - 1].focus();
+        focusItem(items.length - 1);
         break;
         
       case 'Enter':
@@ -803,7 +1125,20 @@ export const withController = (config: MenuConfig) => component => {
         if (isSubmenu) {
           // In a submenu, right arrow opens nested submenus
           if (focusedItemIndex >= 0 && items[focusedItemIndex].classList.contains(`${component.getClass('menu-item--submenu')}`)) {
-            items[focusedItemIndex].click();
+            // Simulate click but specifying it's via keyboard
+            const itemElement = items[focusedItemIndex];
+            const itemIndex = parseInt(itemElement.getAttribute('data-index'), 10);
+            
+            // Get the parent submenu to find the correct data
+            const parentMenu = itemElement.closest(`.${component.getClass('menu--submenu')}`);
+            const parentItemId = parentMenu?.getAttribute('data-parent-item');
+            
+            // Find the parent item in the items array to get its submenu
+            const parentItem = findItemById(parentItemId);
+            if (parentItem && parentItem.submenu) {
+              const itemData = parentItem.submenu[itemIndex] as MenuItem;
+              handleNestedSubmenuClick(itemData, itemIndex, itemElement, true);
+            }
           }
         } else {
           // In main menu, right arrow opens a submenu
@@ -828,9 +1163,21 @@ export const withController = (config: MenuConfig) => component => {
           if (state.activeSubmenuItem) {
             // Store the reference to the parent item before closing the submenu
             const parentItem = state.activeSubmenuItem;
-            closeSubmenu();
+            
+            // Get the current level
+            const currentLevel = parseInt(
+              menuElement.getAttribute('data-level') || '1',
+              10
+            );
+            
+            // Close this level of submenu
+            closeSubmenuAtLevel(currentLevel);
+            
             // Focus the parent item after closing
-            parentItem.focus();
+            if (parentItem) {
+              parentItem.setAttribute('tabindex', '0');
+              parentItem.focus();
+            }
           } else {
             closeSubmenu();
           }
@@ -844,27 +1191,116 @@ export const withController = (config: MenuConfig) => component => {
           if (state.activeSubmenuItem) {
             // Store the reference to the parent item before closing the submenu
             const parentItem = state.activeSubmenuItem;
-            closeSubmenu();
+            
+            // Get the current level
+            const currentLevel = parseInt(
+              menuElement.getAttribute('data-level') || '1',
+              10
+            );
+            
+            // Close this level of submenu
+            closeSubmenuAtLevel(currentLevel);
+            
             // Focus the parent item after closing
-            parentItem.focus();
+            if (parentItem) {
+              parentItem.setAttribute('tabindex', '0');
+              parentItem.focus();
+            }
           } else {
             closeSubmenu();
           }
         } else {
-          // In main menu, Escape closes the entire menu
-          closeMenu(e);
+          // In main menu, Escape closes the entire menu and restores focus to anchor
+          closeMenu(e, true);
         }
         break;
         
       case 'Tab':
-        // Close the menu when tabbing out
-        if (!isSubmenu) {
-          closeMenu();
+        // Modified Tab handling - we want to close the menu and move focus to the next focusable element
+        e.preventDefault(); // Prevent default tab behavior
+        
+        // Find the focusable elements before closing the menu
+        const focusableElements = getFocusableElements();
+        const anchorElement = getAnchorElement();
+        const anchorIndex = anchorElement ? focusableElements.indexOf(anchorElement) : -1;
+        
+        // Calculate the next element to focus
+        let nextElementIndex = -1;
+        if (anchorIndex >= 0) {
+          nextElementIndex = e.shiftKey ? 
+            // For Shift+Tab, go to previous element or last element if we're at the start
+            (anchorIndex > 0 ? anchorIndex - 1 : focusableElements.length - 1) : 
+            // For Tab, go to next element or first element if we're at the end
+            (anchorIndex < focusableElements.length - 1 ? anchorIndex + 1 : 0);
+        }
+        
+        // Store the next element to focus before closing the menu
+        const nextElementToFocus = nextElementIndex >= 0 ? focusableElements[nextElementIndex] : null;
+        
+        // Create a flag that prevents focus restoration
+        const tabNavigationInProgress = true;
+        
+        // Close the menu with focus restoration explicitly disabled
+        closeMenu(e, false, true);
+        
+        // Focus the next element if found, with a slight delay to ensure menu is closed
+        if (nextElementToFocus) {
+          // Use setTimeout with a very small delay to ensure this happens after all other operations
+          setTimeout(() => {
+            // Set a flag to prevent any other focus management from interfering
+            document.body.setAttribute('data-menu-tab-navigation', 'true');
+            
+            // Focus the element
+            nextElementToFocus.focus();
+            
+            // Remove the flag after focus is set
+            setTimeout(() => {
+              document.body.removeAttribute('data-menu-tab-navigation');
+            }, 100);
+          }, 10);
         }
         break;
     }
   };
 
+  /**
+   * Gets all focusable elements in the document
+   * Useful for Tab navigation management
+   */
+  const getFocusableElements = (): HTMLElement[] => {
+    // Query all potentially focusable elements
+    const focusableElementsString = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+    const elements = document.querySelectorAll(focusableElementsString) as NodeListOf<HTMLElement>;
+    
+    // Convert to array and filter out hidden elements
+    return Array.from(elements).filter(element => {
+      return element.offsetParent !== null && !element.classList.contains('hidden');
+    });
+  };
+
+  /**
+   * Find a menu item by its ID in the items array
+   */
+  const findItemById = (id: string): MenuItem | null => {
+    // Search in top-level items
+    for (const item of state.items) {
+      if ('id' in item && item.id === id) {
+        return item as MenuItem;
+      }
+      
+      // Search in submenu items
+      if ('submenu' in item && Array.isArray((item as MenuItem).submenu)) {
+        for (const subItem of (item as MenuItem).submenu) {
+          if ('id' in subItem && subItem.id === id) {
+            return subItem as MenuItem;
+          }
+        }
+      }
+    }
+    
+    return null;
+  };
+
   /**
    * Sets up the menu
    */
@@ -877,7 +1313,10 @@ export const withController = (config: MenuConfig) => component => {
     
     // Position if visible
     if (state.visible) {
-      positionMenu();
+      const anchorElement = getAnchorElement();
+      if (anchorElement) {
+        positioner.positionMenu(anchorElement);
+      }
       
       // Show immediately
       component.element.classList.add(`${component.getClass('menu--visible')}`);
@@ -917,8 +1356,12 @@ export const withController = (config: MenuConfig) => component => {
       window.removeEventListener('scroll', handleWindowScrollForSubmenu);
       
       // Clean up submenu element
-      if (state.activeSubmenu && state.activeSubmenu.parentNode) {
-        state.activeSubmenu.parentNode.removeChild(state.activeSubmenu);
+      if (state.activeSubmenus.length > 0) {
+        state.activeSubmenus.forEach(submenu => {
+          if (submenu.element.parentNode) {
+            submenu.element.parentNode.removeChild(submenu.element);
+          }
+        });
       }
       
       originalDestroy();
@@ -929,20 +1372,20 @@ export const withController = (config: MenuConfig) => component => {
   return {
     ...component,
     menu: {
-      open: (event) => {
-        openMenu(event);
-        return component;
-      },
-      
-      close: (event) => {
-        closeMenu(event);
-        return component;
-      },
-      
-      toggle: (event) => {
-        toggleMenu(event);
-        return component;
-      },
+    open: (event, interactionType = 'mouse') => {
+      openMenu(event, interactionType);
+      return component;
+    },
+    
+    close: (event, restoreFocus = true, skipAnimation = false) => {
+      closeMenu(event, restoreFocus, skipAnimation);
+      return component;
+    },
+    
+    toggle: (event, interactionType = 'mouse') => {
+      toggleMenu(event, interactionType);
+      return component;
+    },
       
       isOpen: () => state.visible,
       
@@ -954,15 +1397,25 @@ export const withController = (config: MenuConfig) => component => {
       
       getItems: () => state.items,
       
-      setPlacement: (placement) => {
-        state.placement = placement;
+      setPosition: (position) => {
+        state.position = position;
         if (state.visible) {
-          positionMenu();
+          const anchorElement = getAnchorElement();
+          if (anchorElement) {
+            positioner.positionMenu(anchorElement);
+          }
         }
         return component;
       },
       
-      getPlacement: () => state.placement
+      getPosition: () => state.position,
+
+      setSelected: (itemId: string | null) => {
+        updateSelectedState(itemId);
+        return component;
+      },
+    
+      getSelected: () => state.selectedItemId
     }
   };
 };