mtrl 0.3.6 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrl",
-  "version": "0.3.6",
+  "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/button/api.ts

@@ -123,6 +123,22 @@ export const withAPI = ({ disabled, lifecycle }: ApiOptions) =>
       return component.icon.getIcon();
     },
 
+    /**
+     * Sets the active state of the button
+     * Used to visually indicate the button's active state, such as when it has a menu open
+     * 
+     * @param active - Whether the button should appear active
+     * @returns Button component for method chaining
+     */
+    setActive(active: boolean) {
+      if (active) {
+        component.element.classList.add(`${component.getClass('button')}--active`);
+      } else {
+        component.element.classList.remove(`${component.getClass('button')}--active`);
+      }
+      return this;
+    },
+
     /**
      * Sets the button's aria-label attribute for accessibility
      * @param label - Accessible label text

package/src/components/button/types.ts

@@ -249,6 +249,15 @@ export interface ButtonComponent {
    */
   updateCircularStyle: () => void;
   
+  /**
+   * Sets the active state of the button
+   * Used to visually indicate the button's active state, such as when it has a menu open
+   * 
+   * @param active - Whether the button should appear active
+   * @returns The button component for chaining
+   */
+  setActive: (active: boolean) => ButtonComponent;
+  
   /**
    * Adds an event listener to the button
    * @param event - Event name ('click', 'focus', etc.)

package/src/components/menu/api.ts

@@ -1,6 +1,6 @@
 // src/components/menu/api.ts
 
-import { MenuComponent, MenuContent, MenuPlacement, MenuEvent, MenuSelectEvent } from './types';
+import { MenuComponent, MenuContent, MenuPosition, MenuEvent, MenuSelectEvent } from './types';
 
 /**
  * API configuration options for menu component
@@ -9,14 +9,16 @@ import { MenuComponent, MenuContent, MenuPlacement, 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[];
-    setPlacement: (placement: MenuPlacement) => any;
-    getPlacement: () => MenuPlacement;
+    setPosition: (position: MenuPosition) => any;
+    getPosition: () => MenuPosition;
+    setSelected: (itemId: string) => any;
+    getSelected: () => string | null;
   };
   anchor: {
     setAnchor: (anchor: HTMLElement | string) => any;
@@ -53,18 +55,27 @@ 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,
     
+
     /**
      * Opens the menu
      * @param event - Optional event that triggered the open
+     * @param interactionType - The type of interaction that triggered the open ('mouse' or 'keyboard')
      * @returns Menu component for chaining
      */
-    open(event?: Event) {
-      menu.open(event);
+    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;
     },
     
@@ -73,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;
     },
     
@@ -133,21 +154,39 @@ export const withAPI = ({ menu, anchor, events, lifecycle }: ApiOptions) =>
     },
     
     /**
-     * Updates the menu's placement
-     * @param placement - New placement value
+     * Updates the menu's position
+     * @param position - New position value
+     * @returns Menu component for chaining
+     */
+    setPosition(position: MenuPosition) {
+      menu.setPosition(position);
+      return this;
+    },
+    
+    /**
+     * Gets the current menu position
+     * @returns Current position
+     */
+    getPosition() {
+      return menu.getPosition();
+    },
+    
+    /**
+     * Sets the selected menu item
+     * @param itemId - ID of the menu item to mark as selected
      * @returns Menu component for chaining
      */
-    setPlacement(placement: MenuPlacement) {
-      menu.setPlacement(placement);
+    setSelected(itemId: string) {
+      menu.setSelected(itemId);
       return this;
     },
     
     /**
-     * Gets the current menu placement
-     * @returns Current placement
+     * Gets the currently selected menu item's ID
+     * @returns ID of the selected menu item or null if none is selected
      */
-    getPlacement() {
-      return menu.getPlacement();
+    getSelected() {
+      return menu.getSelected();
     },
     
     /**
@@ -188,4 +227,4 @@ export const withAPI = ({ menu, anchor, events, lifecycle }: ApiOptions) =>
     }
   });
 
-export default withAPI;
+export { withAPI };

package/src/components/menu/config.ts

@@ -5,7 +5,7 @@ import {
   createElementConfig,
   BaseComponentConfig 
 } from '../../core/config/component-config';
-import { MenuConfig, MENU_PLACEMENT } from './types';
+import { MenuConfig, MENU_POSITION } from './types';
 
 /**
  * Default configuration for the Menu component
@@ -15,12 +15,12 @@ import { MenuConfig, MENU_PLACEMENT } from './types';
  */
 export const defaultConfig: MenuConfig = {
   items: [],
-  placement: MENU_PLACEMENT.BOTTOM_START,
+  position: MENU_POSITION.BOTTOM_START,
   closeOnSelect: true,
   closeOnClickOutside: true,
   closeOnEscape: true,
   openSubmenuOnHover: true,
-  offset: 8,
+  offset: 0,
   autoFlip: true,
   visible: false
 };
@@ -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() || [],
-    setPlacement: (placement) => component.menu?.setPlacement(placement),
-    getPlacement: () => component.menu?.getPlacement()
+    setPosition: (position) => component.menu?.setPosition(position),
+    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,23 +9,40 @@ 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
+    anchorElement: null as HTMLElement,
+    anchorComponent: null as any,
+    activeClass: '' // Store the appropriate active class based on element type
   };
 
   /**
-   * Resolves the anchor element from string or direct reference
+   * Resolves the anchor element from string, direct reference, or component
    */
-  const resolveAnchor = (anchor: HTMLElement | string): HTMLElement => {
+  const resolveAnchor = (anchor: HTMLElement | string | { element: HTMLElement }): HTMLElement => {
     if (!anchor) return null;
 
+    // Handle string selector
     if (typeof anchor === 'string') {
       const element = document.querySelector(anchor);
       if (!element) {
@@ -34,14 +51,41 @@ export const withAnchor = (config: MenuConfig) => component => {
       }
       return element as HTMLElement;
     }
+    
+    // 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;
+  };
 
-    return anchor;
+  /**
+   * Determine the appropriate active class based on element type
+   */
+  const determineActiveClass = (element: HTMLElement): string => {
+    // Check if this is one of our component types
+    const classPrefix = component.getClass('').split('-')[0];
+    
+    // Check element tag and classes to determine appropriate active class
+    if (element.tagName === 'BUTTON') {
+      return `${classPrefix}-button--active`;
+    } else if (element.classList.contains(`${classPrefix}-chip`)) {
+      return `${classPrefix}-chip--selected`;
+    } else if (element.classList.contains(`${classPrefix}-textfield`) || 
+               element.classList.contains(`${classPrefix}-select`)) {
+      return `${classPrefix}-textfield--focused`;
+    } else {
+      // Default active class for other elements
+      return `${classPrefix}-menu-anchor--active`;
+    }
   };
 
   /**
    * Sets up anchor click handler for toggling menu
    */
-  const setupAnchorEvents = (anchorElement: HTMLElement): void => {
+  const setupAnchorEvents = (anchorElement: HTMLElement, originalAnchor?: any): void => {
     if (!anchorElement) return;
 
     // Remove previously attached event if any
@@ -49,12 +93,28 @@ export const withAnchor = (config: MenuConfig) => component => {
       cleanup();
     }
 
-    // Store reference
+    // Store references
     state.anchorElement = anchorElement;
+    
+    // Store reference to component if it was provided
+    if (originalAnchor && typeof originalAnchor === 'object' && 'element' in originalAnchor) {
+      state.anchorComponent = originalAnchor;
+    } else {
+      state.anchorComponent = null;
+    }
+
+    // Determine the appropriate active class for this anchor
+    state.activeClass = determineActiveClass(anchorElement);
 
     // 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');
@@ -70,25 +130,161 @@ export const withAnchor = (config: MenuConfig) => component => {
     anchorElement.setAttribute('aria-controls', menuId);
   };
 
+  /**
+   * Applies active visual state to anchor
+   */
+  const setAnchorActive = (active: boolean): void => {
+    if (!state.anchorElement) return;
+    
+    // For component with setActive method (our button component has this)
+    if (state.anchorComponent && typeof state.anchorComponent.setActive === 'function') {
+      state.anchorComponent.setActive(active);
+    } 
+    // For component with .selected property (like our chip component)
+    else if (state.anchorComponent && 'selected' in state.anchorComponent) {
+      state.anchorComponent.selected = active;
+    }
+    // Standard DOM element fallback
+    else if (state.anchorElement.classList) {
+      if (active) {
+        // Add the appropriate active class
+        state.anchorElement.classList.add(state.activeClass);
+      } else {
+        // Remove active class
+        state.anchorElement.classList.remove(state.activeClass);
+      }
+    }
+  };
+
   /**
    * Handles anchor element click
    */
   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);
-        state.anchorElement.setAttribute('aria-expanded', 'false');
       } else {
-        component.menu.open(e);
-        state.anchorElement.setAttribute('aria-expanded', 'true');
+        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
@@ -96,15 +292,25 @@ 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');
+      
+      // Clean up active state if present
+      setAnchorActive(false);
     }
+    
+    // Reset state
+    state.anchorComponent = null;
+    state.activeClass = '';
   };
 
   // Initialize with provided anchor
-  const initialAnchor = resolveAnchor(config.anchor);
-  setupAnchorEvents(initialAnchor);
+  const initialAnchor = config.anchor;
+  const initialElement = resolveAnchor(initialAnchor);
+  setupAnchorEvents(initialElement, initialAnchor);
 
   // Register with lifecycle if available
   if (component.lifecycle) {
@@ -119,12 +325,31 @@ export const withAnchor = (config: MenuConfig) => component => {
   component.on('open', () => {
     if (state.anchorElement) {
       state.anchorElement.setAttribute('aria-expanded', 'true');
+      setAnchorActive(true);
     }
   });
 
-  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();
+        });
+      }
     }
   });
 
@@ -134,13 +359,13 @@ export const withAnchor = (config: MenuConfig) => component => {
     anchor: {
       /**
        * Sets a new anchor element
-       * @param anchor - New anchor element or selector
+       * @param anchor - New anchor element, selector, or component
        * @returns Component for chaining
        */
-      setAnchor(anchor: HTMLElement | string) {
-        const newAnchor = resolveAnchor(anchor);
-        if (newAnchor) {
-          setupAnchorEvents(newAnchor);
+      setAnchor(anchor: HTMLElement | string | { element: HTMLElement }) {
+        const newElement = resolveAnchor(anchor);
+        if (newElement) {
+          setupAnchorEvents(newElement, anchor);
         }
         return component;
       },
@@ -151,6 +376,16 @@ export const withAnchor = (config: MenuConfig) => component => {
        */
       getAnchor() {
         return state.anchorElement;
+      },
+      
+      /**
+       * Sets the active state of the anchor
+       * @param active - Whether anchor should appear active
+       * @returns Component for chaining
+       */
+      setActive(active: boolean) {
+        setAnchorActive(active);
+        return component;
       }
     }
   };