mtrl 0.3.6 → 0.3.7

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

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

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

@@ -0,0 +1,353 @@
+// src/components/menu/features/position.ts
+
+import { MenuConfig } from '../types';
+
+/**
+ * Menu position helper
+ * Provides functions for positioning menus and submenus
+ */
+export const createPositioner = (component, config: MenuConfig) => {
+  /**
+   * Positions the menu relative to its anchor
+   * Ensures the menu maintains proper spacing from viewport edges
+   * Makes sure the menu stays attached to anchor during scrolling
+   * 
+   * @param menuElement - The menu element to position
+   * @param anchorElement - The element to anchor against
+   * @param preferredPosition - The preferred position
+   * @param isSubmenu - Whether this is a submenu (affects positioning logic)
+   */
+  const positionElement = (
+    menuElement: HTMLElement, 
+    anchorElement: HTMLElement, 
+    preferredPosition: string,
+    isSubmenu = false
+  ): void => {
+    if (!menuElement || !anchorElement) return;
+    
+    // Ensure menu is positioned absolutely for proper scroll behavior
+    menuElement.style.position = 'absolute';
+    
+    // Get current scroll position - critical for absolute positioning that tracks anchor
+    const scrollX = window.pageXOffset || document.documentElement.scrollLeft;
+    const scrollY = window.pageYOffset || document.documentElement.scrollTop;
+    
+    // Make a copy of the menu for measurement without affecting the real menu
+    const tempMenu = menuElement.cloneNode(true) as HTMLElement;
+    
+    // Make the temp menu visible but not displayed for measurement
+    tempMenu.style.visibility = 'hidden';
+    tempMenu.style.display = 'block';
+    tempMenu.style.position = 'absolute';
+    tempMenu.style.top = '0';
+    tempMenu.style.left = '0';
+    tempMenu.style.transform = 'none';
+    tempMenu.style.opacity = '0';
+    tempMenu.style.pointerEvents = 'none';
+    tempMenu.classList.add(`${component.getClass('menu--visible')}`); // Add visible class for proper dimensions
+    
+    // Add it to the DOM temporarily
+    document.body.appendChild(tempMenu);
+    
+    // Get measurements
+    const anchorRect = anchorElement.getBoundingClientRect();
+    const menuRect = tempMenu.getBoundingClientRect();
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+    
+    // Remove the temp element after measurements
+    document.body.removeChild(tempMenu);
+    
+    // Get values needed for calculations
+    const offset = config.offset !== undefined ? config.offset : 8;
+    
+    // Calculate position based on position
+    let top = 0;
+    let left = 0;
+    let calculatedPosition = preferredPosition;
+    
+    // Different positioning logic for main menu vs submenu
+    if (isSubmenu) {
+      // Default position is to the right of parent
+      calculatedPosition = preferredPosition || 'right-start';
+      
+      // Check if this would push the submenu out of the viewport
+      if (calculatedPosition.startsWith('right') && anchorRect.right + menuRect.width + offset > viewportWidth - 16) {
+        // Flip to the left side if it doesn't fit on the right
+        calculatedPosition = calculatedPosition.replace('right', 'left');
+      } else if (calculatedPosition.startsWith('left') && anchorRect.left - menuRect.width - offset < 16) {
+        // Flip to the right side if it doesn't fit on the left
+        calculatedPosition = calculatedPosition.replace('left', 'right');
+      }
+      
+      // Check vertical positioning as well for submenus
+      // If submenu would extend beyond the bottom of the viewport, adjust positioning
+      if (anchorRect.top + menuRect.height > viewportHeight - 16) {
+        if (calculatedPosition === 'right-start') {
+          calculatedPosition = 'right-end';
+        } else if (calculatedPosition === 'left-start') {
+          calculatedPosition = 'left-end';
+        }
+      }
+    } else {
+      // For main menu, follow the standard position calculation
+      // First determine correct position based on original position
+      switch (preferredPosition) {
+        case 'top-start':
+        case 'top':
+        case 'top-end':
+          // Check if enough space above
+          if (anchorRect.top < menuRect.height + offset + 16) {
+            // Not enough space above, flip to bottom
+            calculatedPosition = preferredPosition.replace('top', 'bottom');
+          }
+          break;
+        
+        case 'bottom-start':
+        case 'bottom':
+        case 'bottom-end':
+          // Check if enough space below
+          if (anchorRect.bottom + menuRect.height + offset + 16 > viewportHeight) {
+            // Not enough space below, check if more space above
+            if (anchorRect.top > (viewportHeight - anchorRect.bottom)) {
+              // More space above, flip to top
+              calculatedPosition = preferredPosition.replace('bottom', 'top');
+            }
+          }
+          break;
+          
+        // Specifically handle right-start, right, left-start, and left positions
+        case 'right-start':
+        case 'right':
+        case 'left-start':
+        case 'left':
+          // Check if enough space below for these side positions
+          if (anchorRect.bottom + menuRect.height > viewportHeight - 16) {
+            // Not enough space below, shift the menu upward
+            if (preferredPosition === 'right-start') {
+              calculatedPosition = 'right-end';
+            } else if (preferredPosition === 'left-start') {
+              calculatedPosition = 'left-end';
+            } else if (preferredPosition === 'right') {
+              // For center aligned, shift up by half menu height plus some spacing
+              top = anchorRect.top - (menuRect.height - anchorRect.height) - offset;
+            } else if (preferredPosition === 'left') {
+              // For center aligned, shift up by half menu height plus some spacing
+              top = anchorRect.top - (menuRect.height - anchorRect.height) - offset;
+            }
+          }
+          break;
+      }
+    }
+    
+    // Reset any existing position classes
+    const positionClasses = [
+      'position-top', 'position-bottom', 'position-right', 'position-left'
+    ];
+    
+    positionClasses.forEach(posClass => {
+      menuElement.classList.remove(`${component.getClass('menu')}--${posClass}`);
+    });
+    
+    // Determine transform origin based on vertical position
+    // Start by checking the calculated position to determine transform origin
+    const menuAppearsAboveAnchor = 
+      calculatedPosition.startsWith('top') || 
+      calculatedPosition === 'right-end' || 
+      calculatedPosition === 'left-end' ||
+      (calculatedPosition === 'right' && top < anchorRect.top) ||
+      (calculatedPosition === 'left' && top < anchorRect.top);
+    
+    if (menuAppearsAboveAnchor) {
+      menuElement.classList.add(`${component.getClass('menu')}--position-top`);
+    } else if (calculatedPosition.startsWith('left')) {
+      menuElement.classList.add(`${component.getClass('menu')}--position-left`);
+    } else if (calculatedPosition.startsWith('right')) {
+      menuElement.classList.add(`${component.getClass('menu')}--position-right`);
+    } else {
+      menuElement.classList.add(`${component.getClass('menu')}--position-bottom`);
+    }
+    
+    // Position calculation - important: getBoundingClientRect() returns values relative to viewport
+    // We need to add scroll position to get absolute position
+    switch (calculatedPosition) {
+      case 'top-start':
+        top = anchorRect.top + scrollY - menuRect.height - offset;
+        left = anchorRect.left + scrollX;
+        break;
+      case 'top':
+        top = anchorRect.top + scrollY - menuRect.height - offset;
+        left = anchorRect.left + scrollX + (anchorRect.width / 2) - (menuRect.width / 2);
+        break;
+      case 'top-end':
+        top = anchorRect.top + scrollY - menuRect.height - offset;
+        left = anchorRect.right + scrollX - menuRect.width;
+        break;
+      case 'right-start':
+        top = anchorRect.top + scrollY;
+        left = anchorRect.right + scrollX + offset;
+        break;
+      case 'right':
+        // Custom top position might be set above; only set if not already defined
+        if (top === 0) {
+          top = anchorRect.top + scrollY + (anchorRect.height / 2) - (menuRect.height / 2);
+        } else {
+          top += scrollY;
+        }
+        left = anchorRect.right + scrollX + offset;
+        break;
+      case 'right-end':
+        top = anchorRect.bottom + scrollY - menuRect.height;
+        left = anchorRect.right + scrollX + offset;
+        break;
+      case 'bottom-start':
+        top = anchorRect.bottom + scrollY + offset;
+        left = anchorRect.left + scrollX;
+        break;
+      case 'bottom':
+        top = anchorRect.bottom + scrollY + offset;
+        left = anchorRect.left + scrollX + (anchorRect.width / 2) - (menuRect.width / 2);
+        break;
+      case 'bottom-end':
+        top = anchorRect.bottom + scrollY + offset;
+        left = anchorRect.right + scrollX - menuRect.width;
+        break;
+      case 'left-start':
+        top = anchorRect.top + scrollY;
+        left = anchorRect.left + scrollX - menuRect.width - offset;
+        break;
+      case 'left':
+        // Custom top position might be set above; only set if not already defined
+        if (top === 0) {
+          top = anchorRect.top + scrollY + (anchorRect.height / 2) - (menuRect.height / 2);
+        } else {
+          top += scrollY;
+        }
+        left = anchorRect.left + scrollX - menuRect.width - offset;
+        break;
+      case 'left-end':
+        top = anchorRect.bottom + scrollY - menuRect.height;
+        left = anchorRect.left + scrollX - menuRect.width - offset;
+        break;
+    }
+    
+    // Ensure the menu has proper spacing from viewport edges
+    
+    // Top edge spacing - ensure the menu doesn't go above the viewport + padding
+    const minTopSpacing = 16; // Minimum distance from top of viewport
+    if (top - scrollY < minTopSpacing) {
+      top = minTopSpacing + scrollY;
+    }
+    
+    // Bottom edge spacing - ensure the menu doesn't go below the viewport - padding
+    const viewportBottomMargin = 16; // Minimum space from bottom of viewport
+    const bottomEdge = (top - scrollY) + menuRect.height;
+    
+    if (bottomEdge > viewportHeight - viewportBottomMargin) {
+      // Option 1: We could adjust the top position
+      // top = scrollY + viewportHeight - viewportBottomMargin - menuRect.height;
+      
+      // Option 2: Instead of moving the menu, adjust its height to fit (better UX)
+      const availableHeight = viewportHeight - (top - scrollY) - viewportBottomMargin;
+      
+      // Set a minimum height to prevent tiny menus
+      const minMenuHeight = Math.min(menuRect.height, 100);
+      const newMaxHeight = Math.max(availableHeight, minMenuHeight);
+      
+      // Update maxHeight to fit within viewport
+      menuElement.style.maxHeight = `${newMaxHeight}px`;
+      
+      // If user has explicitly set a maxHeight, respect it if smaller
+      if (config.maxHeight) {
+        const configMaxHeight = parseInt(config.maxHeight, 10);
+        if (!isNaN(configMaxHeight) && configMaxHeight < parseInt(menuElement.style.maxHeight || '0', 10)) {
+          menuElement.style.maxHeight = config.maxHeight;
+        }
+      }
+    } else {
+      // If there's plenty of space, use the config's maxHeight (if provided)
+      if (config.maxHeight) {
+        menuElement.style.maxHeight = config.maxHeight;
+      }
+    }
+    
+    // For 'width: 100%' configuration, match the anchor width
+    if (config.width === '100%' && !isSubmenu) {
+      menuElement.style.width = `${anchorRect.width}px`;
+    }
+    
+    // Apply final positions, ensuring menu stays within viewport
+    // The position is absolute, not fixed, so it must account for scroll
+    menuElement.style.top = `${Math.max(minTopSpacing + scrollY, top)}px`;
+    menuElement.style.left = `${Math.max(16 + scrollX, left)}px`;
+    
+    // Make sure menu doesn't extend past right edge 
+    if ((left - scrollX) + menuRect.width > viewportWidth - 16) {
+      // If we're going past the right edge, set right with fixed distance from edge
+      menuElement.style.left = 'auto';
+      menuElement.style.right = '16px';
+    }
+  };
+
+  /**
+   * Positions the main menu relative to its anchor
+   */
+  const positionMenu = (anchorElement: HTMLElement): void => {
+    if (!anchorElement || !component.element) return;
+    positionElement(component.element, anchorElement, config.position, false);
+  };
+
+  /**
+   * Positions a submenu relative to its parent menu item
+   * For deeply nested submenus, alternates side placement (right/left)
+   * @param submenuElement - The submenu element to position
+   * @param parentItemElement - The parent menu item element
+   * @param level - Nesting level for calculating position
+   */
+  const positionSubmenu = (
+    submenuElement: HTMLElement, 
+    parentItemElement: HTMLElement,
+    level: number = 1
+  ): void => {
+    if (!submenuElement || !parentItemElement) return;
+    
+    // Alternate between right and left positioning for deeper nesting levels
+    // This helps prevent menus from cascading off the screen
+    const prefPosition = level % 2 === 1 ? 'right-start' : 'left-start';
+    
+    // Use higher z-index for deeper nested menus to ensure proper layering
+    submenuElement.style.zIndex = `${1000 + (level * 10)}`;
+    
+    positionElement(submenuElement, parentItemElement, prefPosition, true);
+  };
+
+  return {
+    positionMenu,
+    positionSubmenu,
+    positionElement
+  };
+};
+
+/**
+ * Adds positioning functionality to the menu component
+ * 
+ * @param config - Menu configuration options
+ * @returns Component enhancer with positioning functionality
+ */
+export const withPosition = (config: MenuConfig) => component => {
+  // Do nothing if no element
+  if (!component.element) {
+    return component;
+  }
+
+  // Create the positioner
+  const positioner = createPositioner(component, config);
+  
+  // Return enhanced component
+  return {
+    ...component,
+    position: positioner
+  };
+};
+
+export default withPosition;

package/src/components/menu/index.ts

@@ -22,23 +22,23 @@ export type {
   MenuContent,
   MenuEvent,
   MenuSelectEvent,
-  MenuPlacement
+  MenuPosition
 } from './types';
 
 /**
- * Constants for menu placement values - use these instead of string literals
+ * Constants for menu position values - use these instead of string literals
  * for better code completion and type safety.
  * 
  * @example
- * import { createMenu, MENU_PLACEMENT } from 'mtrl';
+ * import { createMenu, MENU_POSITION } from 'mtrl';
  * 
  * // Create a menu positioned at the bottom-right of its anchor
  * const menu = createMenu({ 
  *   anchor: '#dropdown-button',
  *   items: [...],
- *   placement: MENU_PLACEMENT.BOTTOM_END 
+ *   position: MENU_POSITION.BOTTOM_END 
  * });
  * 
  * @category Components
  */
-export { MENU_PLACEMENT } from './types';
+export { MENU_POSITION } from './types';

package/src/components/menu/menu.ts

@@ -4,6 +4,7 @@ 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 { withAPI } from './api';
 import { MenuConfig, MenuComponent } from './types';
 import { createBaseConfig, getElementConfig, getApiConfig } from './config';
@@ -18,6 +19,9 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
  * Menus are built using a functional composition pattern, applying various 
  * features through the pipe function for a modular architecture.
  * 
+ * The menu element is not added to the DOM until it's opened, and it's removed
+ * from the DOM when closed, following best practices for dropdown menus.
+ * 
  * @param {MenuConfig} config - Configuration options for the menu
  *  This must include an anchor element or selector, and an array of menu items.
  *  See {@link MenuConfig} for all available options.
@@ -44,14 +48,14 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
  *   ]
  * });
  * 
- * // Add the menu to the document
- * document.body.appendChild(menu.element);
- * 
  * // Add event listener for item selection
  * menu.on('select', (event) => {
  *   console.log('Selected item:', event.itemId);
  * });
  * 
+ * // Menu will be added to the DOM when opened and removed when closed
+ * menuButton.addEventListener('click', () => menu.toggle());
+ * 
  * @example
  * // Create a menu with nested submenus
  * const menu = createMenu({
@@ -70,68 +74,21 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
  *     { type: 'divider' },
  *     { id: 'delete', text: 'Delete', icon: '<svg>...</svg>' }
  *   ],
- *   placement: 'bottom-end'
+ *   position: 'bottom-end'
  * });
  * 
  * @example
- * // Programmatically control menu visibility
- * const userMenu = createMenu({
- *   anchor: userAvatar,
- *   items: userMenuItems
+ * // Specify a custom position for the menu
+ * const filterMenu = createMenu({
+ *   anchor: filterButton,
+ *   items: filterOptions,
+ *   position: MENU_POSITION.TOP_START,
+ *   width: '240px',
+ *   maxHeight: '400px'
  * });
  * 
- * // Open the menu programmatically
- * userMenu.open();
- * 
- * // Later, close the menu
- * userMenu.close();
- */
-/**
- * Creates a new Menu component with the specified configuration.
- * 
- * The Menu component implements the Material Design 3 menu specifications,
- * providing a flexible dropdown menu system with support for nested menus,
- * keyboard navigation, and ARIA accessibility.
- * 
- * Menus are built using a functional composition pattern, applying various 
- * features through the pipe function for a modular architecture.
- * 
- * The menu element is not added to the DOM until it's opened, and it's removed
- * from the DOM when closed, following best practices for dropdown menus.
- * 
- * @param {MenuConfig} config - Configuration options for the menu
- *  This must include an anchor element or selector, and an array of menu items.
- *  See {@link MenuConfig} for all available options.
- * 
- * @returns {MenuComponent} A fully configured menu component instance with
- *  all requested features applied. The returned component has methods for
- *  menu manipulation, event handling, and lifecycle management.
- * 
- * @throws {Error} Throws an error if menu creation fails or if required
- *  configuration (like anchor) is missing.
- * 
- * @category Components
- * 
- * @example
- * // Create a simple menu anchored to a button
- * const menuButton = document.getElementById('menu-button');
- * const menu = createMenu({
- *   anchor: menuButton,
- *   items: [
- *     { id: 'item1', text: 'Option 1' },
- *     { id: 'item2', text: 'Option 2' },
- *     { type: 'divider' },
- *     { id: 'item3', text: 'Option 3' }
- *   ]
- * });
- * 
- * // Add event listener for item selection
- * menu.on('select', (event) => {
- *   console.log('Selected item:', event.itemId);
- * });
- * 
- * // Menu will be added to the DOM when opened and removed when closed
- * menuButton.addEventListener('click', () => menu.toggle());
+ * // Update the menu's position programmatically
+ * filterMenu.setPosition(MENU_POSITION.BOTTOM_END);
  */
 const createMenu = (config: MenuConfig): MenuComponent => {
   try {
@@ -143,6 +100,7 @@ const createMenu = (config: MenuConfig): MenuComponent => {
       createBase,                                // Base component
       withEvents(),                              // Event handling
       withElement(getElementConfig(baseConfig)), // DOM element
+      withPosition(baseConfig),                  // Position management
       withController(baseConfig),                // Menu controller
       withAnchor(baseConfig),                    // Anchor management
       withLifecycle(),                           // Lifecycle management

package/src/components/menu/types.ts

@@ -1,12 +1,12 @@
 // src/components/menu/types.ts
 
 /**
- * Menu placement options
+ * Menu position options
  * Controls where the menu will appear relative to its anchor element
  * 
  * @category Components
  */
-export const MENU_PLACEMENT = {
+export const MENU_POSITION = {
   /** Places menu below the anchor, aligned to left edge */
   BOTTOM_START: 'bottom-start',
   /** Places menu below the anchor, centered */
@@ -34,11 +34,11 @@ export const MENU_PLACEMENT = {
 } as const;
 
 /**
- * Alignment options for the menu
+ * Position options for the menu
  * 
  * @category Components
  */
-export type MenuPlacement = typeof MENU_PLACEMENT[keyof typeof MENU_PLACEMENT];
+export type MenuPosition = typeof MENU_POSITION[keyof typeof MENU_POSITION];
 
 /**
  * Configuration interface for a menu item
@@ -126,9 +126,9 @@ export type MenuContent = MenuItem | MenuDivider;
 export interface MenuConfig {
   /**
    * Element to which the menu will be anchored
-   * Can be an HTML element or a CSS selector string
+   * Can be an HTML element, a CSS selector string, or a component with an element property
    */
-  anchor: HTMLElement | string;
+  anchor: HTMLElement | string | { element: HTMLElement };
   
   /**
    * Array of menu items and dividers to display
@@ -136,10 +136,10 @@ export interface MenuConfig {
   items: MenuContent[];
   
   /**
-   * Placement of the menu relative to the anchor
+   * Position of the menu relative to the anchor
    * @default 'bottom-start'
    */
-  placement?: MenuPlacement;
+  position?: MenuPosition;
   
   /**
    * Whether the menu should close when an item is clicked
@@ -184,7 +184,7 @@ export interface MenuConfig {
   offset?: number;
   
   /**
-   * Whether the menu should automatically flip placement to stay in viewport
+   * Whether the menu should automatically flip position to stay in viewport
    * @default true
    */
   autoFlip?: boolean;
@@ -280,9 +280,10 @@ export interface MenuComponent {
   /**
    * 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 The menu component for chaining
    */
-  open: (event?: Event) => MenuComponent;
+  open: (event?: Event, interactionType?: 'mouse' | 'keyboard') => MenuComponent;
   
   /**
    * Closes the menu
@@ -331,17 +332,17 @@ export interface MenuComponent {
   getAnchor: () => HTMLElement;
   
   /**
-   * Updates the menu's placement
-   * @param placement - New placement value
+   * Updates the menu's position
+   * @param position - New position value
    * @returns The menu component for chaining
    */
-  setPlacement: (placement: MenuPlacement) => MenuComponent;
+  setPosition: (position: MenuPosition) => MenuComponent;
   
   /**
-   * Gets the current menu placement
-   * @returns Current placement
+   * Gets the current menu position
+   * @returns Current position
    */
-  getPlacement: () => MenuPlacement;
+  getPosition: () => MenuPosition;
   
   /**
    * Adds an event listener to the menu

package/src/components/select/api.ts

@@ -0,0 +1,78 @@
+// src/components/select/api.ts
+import { SelectComponent, ApiOptions, SelectOption } from './types';
+
+/**
+ * Enhances a select component with API methods
+ * @param options - API configuration options
+ * @returns Higher-order function that adds API methods to component
+ * @internal
+ */
+export const withAPI = (options: ApiOptions) => 
+  (component: any): SelectComponent => ({
+    ...component,
+    element: component.element,
+    textfield: component.textfield,
+    menu: component.menu,
+    
+    getValue: options.select.getValue,
+    
+    setValue(value: string): SelectComponent {
+      options.select.setValue(value);
+      return this;
+    },
+    
+    getText: options.select.getText,
+    
+    getSelectedOption: options.select.getSelectedOption,
+    
+    getOptions: options.select.getOptions,
+    
+    setOptions(options: SelectOption[]): SelectComponent {
+      options.select.setOptions(options);
+      return this;
+    },
+    
+    open(interactionType: 'mouse' | 'keyboard' = 'mouse'): SelectComponent {
+      options.select.open(undefined, interactionType);
+      return this;
+    },
+    
+    close(): SelectComponent {
+      options.select.close();
+      return this;
+    },
+    
+    isOpen: options.select.isOpen,
+    
+    on(event, handler) {
+      if (options.events?.on) {
+        options.events.on(event, handler);
+      } else if (component.on) {
+        component.on(event, handler);
+      }
+      return this;
+    },
+    
+    off(event, handler) {
+      if (options.events?.off) {
+        options.events.off(event, handler);
+      } else if (component.off) {
+        component.off(event, handler);
+      }
+      return this;
+    },
+    
+    enable(): SelectComponent {
+      options.disabled.enable();
+      return this;
+    },
+    
+    disable(): SelectComponent {
+      options.disabled.disable();
+      return this;
+    },
+    
+    destroy() {
+      options.lifecycle.destroy();
+    }
+  });