mtrl 0.3.7 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrl",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "A functional TypeScript/JavaScript component library with composable architecture based on Material Design 3",
   "author": "floor",
   "license": "MIT License",
@@ -10,7 +10,7 @@
     "ui",
     "user interface",
     "typescript",
-    "functional",
+    "functional", 
     "composable",
     "material design 3",
     "md3",

package/src/components/menu/api.ts

@@ -9,14 +9,16 @@ import { MenuComponent, MenuContent, MenuPosition, MenuEvent, MenuSelectEvent }
  */
 interface ApiOptions {
   menu: {
-    open: (event?: Event) => any;
-    close: (event?: Event) => any;
-    toggle: (event?: Event) => any;
+    open: (event?: Event, interactionType?: 'mouse' | 'keyboard') => any;
+    close: (event?: Event, restoreFocus?: boolean, skipAnimation?: boolean) => any;
+    toggle: (event?: Event, interactionType?: 'mouse' | 'keyboard') => any;
     isOpen: () => boolean;
     setItems: (items: MenuContent[]) => any;
     getItems: () => MenuContent[];
     setPosition: (position: MenuPosition) => any;
     getPosition: () => MenuPosition;
+    setSelected: (itemId: string) => any;
+    getSelected: () => string | null;
   };
   anchor: {
     setAnchor: (anchor: HTMLElement | string) => any;
@@ -53,7 +55,7 @@ interface ComponentWithElements {
  * @category Components
  * @internal This is an internal utility for the Menu component
  */
-export const withAPI = ({ menu, anchor, events, lifecycle }: ApiOptions) => 
+const withAPI = ({ menu, anchor, events, lifecycle }: ApiOptions) => 
   (component: ComponentWithElements): MenuComponent => ({
     ...component as any,
     element: component.element,
@@ -66,6 +68,13 @@ export const withAPI = ({ menu, anchor, events, lifecycle }: ApiOptions) =>
      * @returns Menu component for chaining
      */
     open(event?: Event, interactionType: 'mouse' | 'keyboard' = 'mouse') {
+      // Determine interaction type from event if not explicitly provided
+      if (event && !interactionType) {
+        if (event instanceof KeyboardEvent) {
+          interactionType = 'keyboard';
+        }
+      }
+      
       menu.open(event, interactionType);
       return this;
     },
@@ -75,18 +84,28 @@ export const withAPI = ({ menu, anchor, events, lifecycle }: ApiOptions) =>
      * @param event - Optional event that triggered the close
      * @returns Menu component for chaining
      */
-    close(event?: Event) {
-      menu.close(event);
+    close(event?: Event, restoreFocus: boolean = true, skipAnimation: boolean = false) {
+      menu.close(event, restoreFocus, skipAnimation);
       return this;
     },
     
     /**
      * Toggles the menu's open state
      * @param event - Optional event that triggered the toggle
+     * @param interactionType - The type of interaction that triggered the toggle
      * @returns Menu component for chaining
      */
-    toggle(event?: Event) {
-      menu.toggle(event);
+    toggle(event?: Event, interactionType?: 'mouse' | 'keyboard') {
+      // Determine interaction type from event if not explicitly provided
+      if (event && !interactionType) {
+        if (event instanceof KeyboardEvent) {
+          interactionType = 'keyboard';
+        } else if (event instanceof MouseEvent) {
+          interactionType = 'mouse';
+        }
+      }
+      
+      menu.toggle(event, interactionType);
       return this;
     },
     
@@ -152,6 +171,24 @@ export const withAPI = ({ menu, anchor, events, lifecycle }: ApiOptions) =>
       return menu.getPosition();
     },
     
+    /**
+     * Sets the selected menu item
+     * @param itemId - ID of the menu item to mark as selected
+     * @returns Menu component for chaining
+     */
+    setSelected(itemId: string) {
+      menu.setSelected(itemId);
+      return this;
+    },
+    
+    /**
+     * Gets the currently selected menu item's ID
+     * @returns ID of the selected menu item or null if none is selected
+     */
+    getSelected() {
+      return menu.getSelected();
+    },
+    
     /**
      * Adds an event listener to the menu
      * @param event - Event name ('open', 'close', 'select')
@@ -190,4 +227,4 @@ export const withAPI = ({ menu, anchor, events, lifecycle }: ApiOptions) =>
     }
   });
 
-export default withAPI;
+export { withAPI };

package/src/components/menu/config.ts

@@ -100,14 +100,16 @@ export const getElementConfig = (config: MenuConfig) => {
  */
 export const getApiConfig = (component) => ({
   menu: {
-    open: () => component.menu?.open(),
-    close: () => component.menu?.close(),
-    toggle: () => component.menu?.toggle(),
+    open: (event, interactionType) => component.menu?.open(event, interactionType),
+    close: (event, restoreFocus, skipAnimation) => component.menu?.close(event, restoreFocus, skipAnimation),
+    toggle: (event, interactionType) => component.menu?.toggle(event, interactionType),
     isOpen: () => component.menu?.isOpen() || false,
     setItems: (items) => component.menu?.setItems(items),
     getItems: () => component.menu?.getItems() || [],
     setPosition: (position) => component.menu?.setPosition(position),
-    getPosition: () => component.menu?.getPosition()
+    getPosition: () => component.menu?.getPosition(),
+    setSelected: (itemId) => component.menu?.setSelected(itemId),
+    getSelected: () => component.menu?.getSelected()
   },
   anchor: {
     setAnchor: (anchor) => component.anchor?.setAnchor(anchor),

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

@@ -9,12 +9,26 @@ import { MenuConfig } from '../types';
  * @param config - Menu configuration
  * @returns Component enhancer with anchor management functionality
  */
-export const withAnchor = (config: MenuConfig) => component => {
+const withAnchor = (config: MenuConfig) => component => {
   if (!component.element) {
     console.warn('Cannot initialize menu anchor: missing element');
     return component;
   }
 
+  // Track keyboard navigation state
+  let isTabNavigation = false;
+
+  // Add an event listener to detect Tab key navigation
+  document.addEventListener('keydown', (e: KeyboardEvent) => {
+    // Set flag when Tab key is pressed
+    isTabNavigation = e.key === 'Tab';
+    
+    // Reset flag after a short delay
+    setTimeout(() => {
+      isTabNavigation = false;
+    }, 100);
+  });
+
   // Track anchor state
   const state = {
     anchorElement: null as HTMLElement,
@@ -95,6 +109,12 @@ export const withAnchor = (config: MenuConfig) => component => {
     // Add click handler
     anchorElement.addEventListener('click', handleAnchorClick);
     
+    // Add keyboard handlers
+    anchorElement.addEventListener('keydown', handleAnchorKeydown);
+    
+    // Add blur/focusout handler to close menu when anchor loses focus
+    anchorElement.addEventListener('blur', handleAnchorBlur);
+    
     // Add ARIA attributes
     anchorElement.setAttribute('aria-haspopup', 'true');
     anchorElement.setAttribute('aria-expanded', 'false');
@@ -142,17 +162,129 @@ export const withAnchor = (config: MenuConfig) => component => {
   const handleAnchorClick = (e: MouseEvent): void => {
     e.preventDefault();
     
-    // Toggle menu visibility
+    // Toggle menu visibility with mouse interaction type
     if (component.menu) {
       const isOpen = component.menu.isOpen();
       
       if (isOpen) {
         component.menu.close(e);
       } else {
-        component.menu.open(e);
+        component.menu.open(e, 'mouse');
       }
     }
   };
+  
+  /**
+   * Handles keyboard events on the anchor element
+   */
+  const handleAnchorKeydown = (e: KeyboardEvent): void => {
+    // Only handle events if we have a menu controller
+    if (!component.menu) return;
+    
+    // Determine if menu is currently open
+    const isOpen = component.menu.isOpen();
+    
+    switch (e.key) {
+      case 'Enter':
+      case ' ':  // Space
+      case 'ArrowDown':
+      case 'Down':
+        // Prevent default browser behavior
+        e.preventDefault();
+        
+        // Open menu if closed, with keyboard interaction type
+        if (!isOpen) {
+          component.menu.open(e, 'keyboard');
+        }
+        break;
+        
+      case 'Escape':
+        // Close the menu if it's open
+        if (isOpen) {
+          e.preventDefault();
+          component.menu.close(e);
+        }
+        break;
+        
+      case 'ArrowUp':
+      case 'Up':
+        e.preventDefault();
+        
+        // Special case: open menu with focus on last item
+        if (!isOpen) {
+          component.menu.open(e, 'keyboard');
+          
+          // Wait for menu to open and grab the last item
+          setTimeout(() => {
+            const items = component.element.querySelectorAll(
+              `.${component.getClass('menu-item')}:not(.${component.getClass('menu-item--disabled')})`
+            ) as NodeListOf<HTMLElement>;
+            
+            if (items.length > 0) {
+              // Reset tabindex for all items
+              items.forEach(item => item.setAttribute('tabindex', '-1'));
+              
+              // Set the last item as active
+              const lastItem = items[items.length - 1];
+              lastItem.setAttribute('tabindex', '0');
+              lastItem.focus();
+            }
+          }, 100);
+        }
+        break;
+    }
+  };
+
+  /**
+   * Handles anchor blur/focusout events
+   */
+  const handleAnchorBlur = (e: FocusEvent): void => {
+    // Only handle events if we have a menu controller and menu is open
+    if (!component.menu || !component.menu.isOpen()) return;
+    
+    // Get the related target (element receiving focus)
+    const relatedTarget = e.relatedTarget as HTMLElement;
+    
+    // If this is tab navigation, always close the menu regardless of next focus target
+    if (isTabNavigation) {
+      setTimeout(() => {
+        // Verify menu is still open (may have been closed in the meantime)
+        if (component.menu && component.menu.isOpen()) {
+          // Close the menu but don't restore focus
+          component.menu.close(e, false);
+        }
+      }, 10);
+      return;
+    }
+    
+    // For non-tab navigation (like mouse clicks):
+    // Don't close if focus is moving to any of these:
+    // 1. To the menu itself
+    // 2. To a child of the menu
+    // 3. To another menu button/anchor
+    if (relatedTarget) {
+      // Check if focus moved to menu or its children
+      if (component.element.contains(relatedTarget)) {
+        return;
+      }
+      
+      // Check if focus moved to another menu button/anchor (has aria-haspopup)
+      if (relatedTarget.getAttribute('aria-haspopup') === 'true' || 
+          relatedTarget.closest('[aria-haspopup="true"]')) {
+        return;
+      }
+    }
+    
+    // Wait a brief moment to ensure we're not in the middle of another operation
+    // This helps prevent conflicts with click handlers
+    setTimeout(() => {
+      // Verify menu is still open (may have been closed in the meantime)
+      if (component.menu && component.menu.isOpen()) {
+        // Close the menu but don't restore focus since focus has moved elsewhere
+        component.menu.close(e, false);
+      }
+    }, 50);
+  };
 
   /**
    * Removes event listeners from anchor
@@ -160,6 +292,8 @@ export const withAnchor = (config: MenuConfig) => component => {
   const cleanup = (): void => {
     if (state.anchorElement) {
       state.anchorElement.removeEventListener('click', handleAnchorClick);
+      state.anchorElement.removeEventListener('keydown', handleAnchorKeydown);
+      state.anchorElement.removeEventListener('blur', handleAnchorBlur);
       state.anchorElement.removeAttribute('aria-haspopup');
       state.anchorElement.removeAttribute('aria-expanded');
       state.anchorElement.removeAttribute('aria-controls');
@@ -195,10 +329,27 @@ export const withAnchor = (config: MenuConfig) => component => {
     }
   });
 
-  component.on('close', () => {
+  /**
+   * Update the event listener for menu close event to ensure focus restoration
+   */
+  component.on('close', (event) => {
     if (state.anchorElement) {
+      // Always update ARIA attributes
       state.anchorElement.setAttribute('aria-expanded', 'false');
       setAnchorActive(false);
+      
+      // Only handle focus restoration for Escape key cases
+      // Do NOT restore focus if:
+      // 1. It's a tab navigation event, OR
+      // 2. There's a next focus element waiting to be focused
+      const isTabNavigation = event.isTabNavigation || window._menuNextFocusElement !== null;
+      
+      if (event.originalEvent?.key === 'Escape' && !isTabNavigation) {
+        // Only in this case, restore focus to anchor
+        requestAnimationFrame(() => {
+          state.anchorElement.focus();
+        });
+      }
     }
   });
 

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

@@ -3,6 +3,8 @@
 import { MenuConfig, MenuContent, MenuItem, MenuDivider, MenuEvent, MenuSelectEvent } from '../types';
 import { createPositioner } from './position';
 
+let ignoreNextDocumentClick = false;
+
 /**
  * Adds controller functionality to the menu component
  * Manages state, rendering, positioning, and event handling
@@ -10,7 +12,7 @@ import { createPositioner } from './position';
  * @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;
@@ -21,6 +23,7 @@ export const withController = (config: MenuConfig) => component => {
     visible: config.visible || false,
     items: config.items || [],
     position: config.position,
+    selectedItemId: null as string | null,
     activeSubmenu: null as HTMLElement,
     activeSubmenuItem: null as HTMLElement,
     activeItemIndex: -1,
@@ -36,7 +39,8 @@ export const withController = (config: MenuConfig) => component => {
       timer: null,
       activeItem: null
     },
-    component
+    component,
+    keyboardNavActive: false // Track if keyboard navigation is active
   };
 
   // Create positioner
@@ -108,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');
@@ -150,6 +162,7 @@ export const withController = (config: MenuConfig) => component => {
       // Focus and blur events for proper focus styling
       itemElement.addEventListener('focus', () => {
         state.activeItemIndex = index;
+        state.keyboardNavActive = true;
       });
       
       // Additional keyboard event handler for accessibility
@@ -236,10 +249,15 @@ export const withController = (config: MenuConfig) => component => {
       ) 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].setAttribute('tabindex', '0');
         items[0].focus();
         state.activeItemIndex = 0;
+        state.keyboardNavActive = true;
       } else {
         // If no items, focus the menu itself
         component.element.setAttribute('tabindex', '0');
@@ -248,6 +266,18 @@ export const withController = (config: MenuConfig) => component => {
     } 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');
+        });
+      }
     }
   };
 
@@ -321,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();
@@ -343,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();
     
@@ -374,6 +410,11 @@ export const withController = (config: MenuConfig) => component => {
   const openSubmenu = (item: MenuItem, index: number, itemElement: HTMLElement, viaKeyboard = false): void => {
     if (!item.submenu || !item.hasSubmenu) return;
     
+    // 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
@@ -435,12 +476,16 @@ export const withController = (config: MenuConfig) => component => {
     
     // 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);
+      }
     });
     
     // Setup submenu event handlers for nested submenus
@@ -509,6 +554,14 @@ export const withController = (config: MenuConfig) => component => {
       
       // 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);
@@ -520,7 +573,7 @@ export const withController = (config: MenuConfig) => component => {
    * Handles hover on a nested submenu item
    */
   const handleNestedSubmenuHover = (item: MenuItem, index: number, itemElement: HTMLElement): void => {
-    if (!config.openSubmenuOnHover || !item.hasSubmenu) return;
+    if (!config.openSubmenuOnHover || !item.hasSubmenu || state.keyboardNavActive) return;
     
     // Clear any existing timers
     clearHoverIntent();
@@ -733,9 +786,15 @@ export const withController = (config: MenuConfig) => component => {
   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;
     
+    // 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
@@ -773,28 +832,45 @@ export const withController = (config: MenuConfig) => component => {
       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
     
-    // Add document events
-    if (config.closeOnClickOutside) {
-      document.addEventListener('click', handleDocumentClick);
-    }
-    if (config.closeOnEscape) {
-      document.addEventListener('keydown', handleDocumentKeydown);
-    }
-    window.addEventListener('resize', handleWindowResize, { passive: true });
-    window.addEventListener('scroll', handleWindowScroll, { passive: true });
-    
     // Trigger event
     eventHelpers.triggerEvent('open', {}, event);
   };
 
   /**
    * 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();
     
@@ -805,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);
+    
+    // Determine animation duration - for tab navigation we want to close immediately
+    const animationDuration = skipAnimation ? 0 : 300;
     
-    // Remove from DOM after animation completes
+    // 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;
@@ -857,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);
     }
   };
 
@@ -899,6 +1037,9 @@ export const withController = (config: MenuConfig) => component => {
    * 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);
     
@@ -919,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;
         
@@ -938,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':
@@ -972,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
@@ -1008,7 +1174,10 @@ export const withController = (config: MenuConfig) => component => {
             closeSubmenuAtLevel(currentLevel);
             
             // Focus the parent item after closing
-            parentItem.focus();
+            if (parentItem) {
+              parentItem.setAttribute('tabindex', '0');
+              parentItem.focus();
+            }
           } else {
             closeSubmenu();
           }
@@ -1033,25 +1202,105 @@ export const withController = (config: MenuConfig) => component => {
             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
    */
@@ -1123,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,
       
@@ -1159,7 +1408,14 @@ export const withController = (config: MenuConfig) => component => {
         return component;
       },
       
-      getPosition: () => state.position
+      getPosition: () => state.position,
+
+      setSelected: (itemId: string | null) => {
+        updateSelectedState(itemId);
+        return component;
+      },
+    
+      getSelected: () => state.selectedItemId
     }
   };
 };

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

@@ -1,5 +1,13 @@
 // src/components/menu/features/index.ts
 
-export { default as withController } from './controller';
-export { default as withAnchor } from './anchor';
-export { default as withPosition } from './position';
+// Individual feature imports
+import withController from './controller';
+import withAnchor from './anchor';
+import withPosition from './position';
+
+// Export features
+export {
+  withController,
+  withAnchor,
+  withPosition
+};

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

@@ -334,7 +334,7 @@ export const createPositioner = (component, config: MenuConfig) => {
  * @param config - Menu configuration options
  * @returns Component enhancer with positioning functionality
  */
-export const withPosition = (config: MenuConfig) => component => {
+const withPosition = (config: MenuConfig) => component => {
   // Do nothing if no element
   if (!component.element) {
     return component;

package/src/components/menu/menu.ts

@@ -3,8 +3,10 @@
 import { pipe } from '../../core/compose';
 import { createBase, withElement } from '../../core/compose/component';
 import { withEvents, withLifecycle } from '../../core/compose/features';
-import { withController, withAnchor } from './features';
-import { withPosition } from './features/position';
+// Import withController directly from the file
+import withController from './features/controller';
+import withAnchor from './features/anchor';
+import withPosition from './features/position';
 import { withAPI } from './api';
 import { MenuConfig, MenuComponent } from './types';
 import { createBaseConfig, getElementConfig, getApiConfig } from './config';

package/src/components/menu/types.ts

@@ -343,6 +343,19 @@ export interface MenuComponent {
    * @returns Current position
    */
   getPosition: () => MenuPosition;
+
+  /**
+   * Sets the selected menu item
+   * @param itemId - ID of the menu item to mark as selected
+   * @returns The menu component for chaining
+   */
+  setSelected: (itemId: string) => MenuComponent;
+  
+  /**
+   * Gets the currently selected menu item's ID
+   * @returns ID of the selected menu item or null if none is selected
+   */
+  getSelected: () => string | null;
   
   /**
    * Adds an event listener to the menu

package/src/components/select/features.ts

@@ -79,7 +79,7 @@ const processMenuItems = (options) => {
 };
 
 /**
- * Creates a menu for the select component
+ * Creates a menu for the select component with improved keyboard navigation
  * @param config - Select configuration
  * @returns Function that enhances a component with menu functionality
  */
@@ -116,6 +116,9 @@ export const withMenu = (config: SelectConfig) =>
       offset: 0 // Set offset to 0 to eliminate gap between textfield and menu
     });
     
+    // This flag helps us know if we need to restore focus after menu closes
+    let needsFocusRestore = false;
+    
     // Handle menu selection
     menu.on('select', (event) => {
       // Safely access data properties with proper type checking
@@ -135,6 +138,12 @@ export const withMenu = (config: SelectConfig) =>
       // Update textfield
       component.textfield.setValue(option.text);
       
+      // Update the selected state in the menu
+      menu.setSelected(option.id);
+      
+      // Set flag to restore focus after menu closes
+      needsFocusRestore = true;
+      
       // Emit change event
       if (component.emit) {
         component.emit('change', {
@@ -149,23 +158,6 @@ export const withMenu = (config: SelectConfig) =>
       }
     });
     
-    // Handle textfield click to open menu
-    component.textfield.element.addEventListener('click', (e) => {
-      if (!component.textfield.input.disabled) {
-        menu.open(e, 'mouse'); // Specify mouse interaction
-        
-        // Emit open event
-        if (component.emit) {
-          component.emit('open', {
-            select: component,
-            originalEvent: e,
-            preventDefault: () => {},
-            defaultPrevented: false
-          });
-        }
-      }
-    });
-
     // Add keyboard event listener for textfield
     component.textfield.element.addEventListener('keydown', (e) => {
       if (component.textfield.input.disabled) return;
@@ -173,7 +165,18 @@ export const withMenu = (config: SelectConfig) =>
       // Handle keyboard-based open
       if ((e.key === 'Enter' || e.key === ' ' || e.key === 'ArrowDown') && !menu.isOpen()) {
         e.preventDefault();
-        menu.open(e, 'keyboard'); // Specify keyboard interaction
+        
+        // Set flag to restore focus
+        needsFocusRestore = true;
+        
+        // Open menu with keyboard interaction
+        menu.open(e, 'keyboard');
+        
+        // Ensure textfield keeps focus
+        setTimeout(() => {
+          // Focus on the textfield to ensure we can capture further keyboard events
+          component.textfield.input.focus();
+        }, 50);
         
         // Emit open event
         if (component.emit) {
@@ -186,6 +189,7 @@ export const withMenu = (config: SelectConfig) =>
         }
       } else if (e.key === 'Escape' && menu.isOpen()) {
         e.preventDefault();
+        needsFocusRestore = true;
         menu.close(e);
       }
     });
@@ -209,13 +213,32 @@ export const withMenu = (config: SelectConfig) =>
       // Remove open class from the select component
       component.textfield.element.classList.remove(`${config.prefix || 'mtrl'}-select--open`);
       
-      // Remove focused class from the textfield
-      const PREFIX = config.prefix || 'mtrl';
-      component.textfield.element.classList.remove(`${PREFIX}-textfield--focused`);
-      
-      // Remove filled focus class if present
-      if (component.textfield.element.classList.contains(`${PREFIX}-textfield--filled`)) {
-        component.textfield.element.classList.remove(`${PREFIX}-textfield--filled-focused`);
+      // Restore focus to textfield if needed
+      if (needsFocusRestore) {
+        // Small delay to ensure menu is fully closed
+        setTimeout(() => {
+          // Explicitly focus the textfield input
+          component.textfield.input.focus();
+          
+          // Keep focused styling
+          const PREFIX = config.prefix || 'mtrl';
+          component.textfield.element.classList.add(`${PREFIX}-textfield--focused`);
+          
+          if (component.textfield.element.classList.contains(`${PREFIX}-textfield--filled`)) {
+            component.textfield.element.classList.add(`${PREFIX}-textfield--filled-focused`);
+          }
+          
+          // Reset the flag
+          needsFocusRestore = false;
+        }, 50);
+      } else {
+        // Only remove focus styling if we're not restoring focus
+        const PREFIX = config.prefix || 'mtrl';
+        component.textfield.element.classList.remove(`${PREFIX}-textfield--focused`);
+        
+        if (component.textfield.element.classList.contains(`${PREFIX}-textfield--filled`)) {
+          component.textfield.element.classList.remove(`${PREFIX}-textfield--filled-focused`);
+        }
       }
       
       // Emit close event
@@ -233,20 +256,8 @@ export const withMenu = (config: SelectConfig) =>
     const markSelectedMenuItem = () => {
       if (!state.selectedOption) return;
       
-      // Get all menu items
-      const menuList = menu.element.querySelector(`.${config.prefix || 'mtrl'}-menu-list`);
-      if (!menuList) return;
-      
-      // Find and mark the selected item
-      const items = menuList.querySelectorAll(`.${config.prefix || 'mtrl'}-menu-item`);
-      items.forEach(item => {
-        const itemId = item.getAttribute('data-id');
-        if (itemId === state.selectedOption.id) {
-          item.classList.add(`${config.prefix || 'mtrl'}-menu-item--selected`);
-        } else {
-          item.classList.remove(`${config.prefix || 'mtrl'}-menu-item--selected`);
-        }
-      });
+      // Use menu's setSelected method to update the selected state
+      menu.setSelected(state.selectedOption.id);
     };
     
     // Mark selected item when menu opens
@@ -269,10 +280,8 @@ export const withMenu = (config: SelectConfig) =>
             state.selectedOption = option;
             component.textfield.setValue(option.text);
             
-            // Update menu item if menu is open
-            if (menu.isOpen()) {
-              markSelectedMenuItem();
-            }
+            // Update selected state using menu's setSelected
+            menu.setSelected(option.id);
           }
           return component;
         },
@@ -302,6 +311,11 @@ export const withMenu = (config: SelectConfig) =>
         },
         
         open: (event?: Event, interactionType: 'mouse' | 'keyboard' = 'mouse') => {
+          // Set focus restore flag for keyboard interactions
+          if (interactionType === 'keyboard') {
+            needsFocusRestore = true;
+          }
+          
           menu.open(event, interactionType);
           return component;
         },

package/src/index.ts

@@ -12,7 +12,7 @@ import createBadge from './components/badge';
 import createBottomAppBar from './components/bottom-app-bar';
 import createButton from './components/button';
 import createCard from './components/card';
-import { 
+import {
   createCardContent, 
   createCardHeader, 
   createCardActions, 
@@ -87,48 +87,4 @@ export {
   createTimePicker,
   createTopAppBar,
   createTooltip
-};
-
-// Export all "f*" aliases
-export {
-  createElement as fElement,
-  createLayout as fLayout,
-  createBadge as fBadge,
-  createBottomAppBar as fBottomAppBar,
-  createButton as fButton,
-  createCard as fCard,
-  createCardContent as fCardContent, 
-  createCardHeader as fCardHeader, 
-  createCardActions as fCardActions, 
-  createCardMedia as fCardMedia,
-  createCarousel as fCarousel,
-  createCheckbox as fCheckbox,
-  createChip as fChip,
-  createChips as fChips,
-  createDatePicker as fDatePicker,
-  createDialog as fDialog,
-  createDivider as fDivider,
-  createFab as fFab,
-  createExtendedFab as fExtendedFab,
-  createList as fList,
-  createListItem as fListItem,
-  createMenu as fMenu,
-  createNavigation as fNavigation,
-  createNavigationSystem as fNavigationSystem,
-  createProgress as fProgress,
-  createRadios as fRadios,
-  createSearch as fSearch,
-  createSelect as fSelect,
-  createSegmentedButton as fSegmentedButton,
-  createSegment as fSegment,
-  createSheet as fSheet,
-  createSlider as fSlider,
-  createSnackbar as fSnackbar,
-  createSwitch as fSwitch,
-  createTabs as fTabs,
-  createTab as fTab,
-  createTextfield as fTextfield,
-  createTimePicker as fTimePicker,
-  createTopAppBar as fTopAppBar,
-  createTooltip as fTooltip
 };

package/src/styles/components/_menu.scss

@@ -72,6 +72,7 @@ $component: 'mtrl-menu';
     position: relative;
     min-height: 48px;
     padding: 12px 16px;
+    padding-right: 42px;
     cursor: pointer;
     user-select: none;
     color: t.color('on-surface');
@@ -107,14 +108,8 @@ $component: 'mtrl-menu';
         transform: translateY(-50%);
         width: 24px;
         height: 24px;
-        mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' height='24px' viewBox='0 0 24 24' width='24px'%3E%3Cpath d='M0 0h24v24H0V0z' fill='none'/%3E%3Cpath d='M10 17l5-5-5-5v10z'/%3E%3C/svg%3E");
-        -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' height='24px' viewBox='0 0 24 24' width='24px'%3E%3Cpath d='M0 0h24v24H0V0z' fill='none'/%3E%3Cpath d='M10 17l5-5-5-5v10z'/%3E%3C/svg%3E");
-        mask-size: contain;
-        -webkit-mask-size: contain;
-        mask-repeat: no-repeat;
-        -webkit-mask-repeat: no-repeat;
-        mask-position: center;
-        -webkit-mask-position: center;
+        mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M10 17l5-5-5-5v10z'/%3E%3C/svg%3E") center / contain no-repeat;
+        -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M10 17l5-5-5-5v10z'/%3E%3C/svg%3E") center / contain no-repeat;
         background-color: currentColor;
         opacity: 0.87;
       }
@@ -137,19 +132,18 @@ $component: 'mtrl-menu';
     // Selected state for select component
     &--selected {
       color: t.color('primary');
-      font-weight: 500;
       
       &::after {
         content: "";
-        display: block;
         position: absolute;
         right: 12px;
+        top: 50%;
+        transform: translateY(-50%);
         width: 18px;
         height: 18px;
-        background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='18' height='18' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='20 6 9 17 4 12'%3E%3C/polyline%3E%3C/svg%3E");
-        background-repeat: no-repeat;
-        background-position: center;
-        color: t.color('primary');
+        mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpolyline points='20 6 9 17 4 12' stroke='white' stroke-width='2' fill='none'/%3E%3C/svg%3E") center / contain no-repeat;
+        -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpolyline points='20 6 9 17 4 12' stroke='white' stroke-width='2' fill='none'/%3E%3C/svg%3E") center / contain no-repeat;
+        background-color: currentColor;
       }
     }
     

package/src/styles/components/_select.scss

@@ -125,10 +125,17 @@ $component: '#{base.$prefix}-select';
           right: 12px;
           width: 18px;
           height: 18px;
-          background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='18' height='18' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='20 6 9 17 4 12'%3E%3C/polyline%3E%3C/svg%3E");
-          background-repeat: no-repeat;
-          background-position: center;
-          color: t.color('primary');
+          // Use mask-image instead of background-image
+          mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='18' height='18' viewBox='0 0 24 24'%3E%3Cpolyline points='20 6 9 17 4 12'%3E%3C/polyline%3E%3C/svg%3E");
+          -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='18' height='18' viewBox='0 0 24 24'%3E%3Cpolyline points='20 6 9 17 4 12'%3E%3C/polyline%3E%3C/svg%3E");
+          mask-size: contain;
+          -webkit-mask-size: contain;
+          mask-repeat: no-repeat;
+          -webkit-mask-repeat: no-repeat;
+          mask-position: center;
+          -webkit-mask-position: center;
+          // Use currentColor to match the text color
+          background-color: currentColor;
         }
       }
     }