mtrl 0.3.3 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrl",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "A functional TypeScript/JavaScript component library with composable architecture based on Material Design 3",
   "author": "floor",
   "license": "MIT License",

package/src/components/menu/api.ts

@@ -1,316 +1,191 @@
 // src/components/menu/api.ts
-import { ApiOptions, BaseComponent, MenuComponent, MenuItemConfig, MenuPositionConfig } from './types';
+
+import { MenuComponent, MenuContent, MenuPlacement, MenuEvent, MenuSelectEvent } from './types';
 
 /**
- * Enhances a menu component with public API methods
- * 
- * This is a higher-order function that wraps a base component and exposes
- * a standardized public API following the MenuComponent interface. It ensures
- * all methods return the component instance for method chaining and handles
- * proper resource cleanup during component destruction.
+ * API configuration options for menu component
+ * @category Components
+ * @internal
+ */
+interface ApiOptions {
+  menu: {
+    open: (event?: Event) => any;
+    close: (event?: Event) => any;
+    toggle: (event?: Event) => any;
+    isOpen: () => boolean;
+    setItems: (items: MenuContent[]) => any;
+    getItems: () => MenuContent[];
+    setPlacement: (placement: MenuPlacement) => any;
+    getPlacement: () => MenuPlacement;
+  };
+  anchor: {
+    setAnchor: (anchor: HTMLElement | string) => any;
+    getAnchor: () => HTMLElement;
+  };
+  events?: {
+    on: <T extends string>(event: T, handler: (event: any) => void) => any;
+    off: <T extends string>(event: T, handler: (event: any) => void) => any;
+  };
+  lifecycle: {
+    destroy: () => void;
+  };
+}
+
+/**
+ * Component with required elements and methods for API enhancement
+ * @category Components
+ * @internal
+ */
+interface ComponentWithElements {
+  element: HTMLElement;
+  on?: <T extends string>(event: T, handler: (event: any) => void) => any;
+  off?: <T extends string>(event: T, handler: (event: any) => void) => any;
+  emit?: (event: string, data: any) => void;
+}
+
+/**
+ * Enhances a menu component with API methods.
+ * This follows the higher-order function pattern to add public API methods
+ * to the component, making them available to the end user.
  * 
- * @param {ApiOptions} options - API configuration including lifecycle methods
+ * @param {ApiOptions} options - API configuration options
  * @returns {Function} Higher-order function that adds API methods to component
- * @internal
  * @category Components
+ * @internal This is an internal utility for the Menu component
  */
-export const withAPI = ({ lifecycle }: ApiOptions) => 
-  (component: BaseComponent): MenuComponent => ({
+export const withAPI = ({ menu, anchor, events, lifecycle }: ApiOptions) => 
+  (component: ComponentWithElements): MenuComponent => ({
     ...component as any,
     element: component.element,
-
+    
     /**
-     * Shows the menu
-     * 
-     * Makes the menu visible in the DOM. This method triggers the 'open' event.
-     * If called when the menu is already visible, it has no effect.
-     * 
-     * @returns {MenuComponent} Component instance for method chaining
-     * @example
-     * ```typescript
-     * // Show a menu
-     * menu.show();
-     * 
-     * // Position and show a menu in one chain
-     * menu.position(buttonElement).show();
-     * ```
+     * Opens the menu
+     * @param event - Optional event that triggered the open
+     * @returns Menu component for chaining
      */
-    show(): MenuComponent {
-      component.show?.();
+    open(event?: Event) {
+      menu.open(event);
       return this;
     },
-
+    
     /**
-     * Hides the menu
-     * 
-     * Makes the menu invisible in the DOM. This method triggers the 'close' event.
-     * If called when the menu is already hidden, it has no effect.
-     * 
-     * @returns {MenuComponent} Component instance for method chaining
-     * @example
-     * ```typescript
-     * // Hide a menu
-     * menu.hide();
-     * 
-     * // Listen for clicks outside the menu to hide it
-     * document.addEventListener('click', (event) => {
-     *   if (menu.isVisible() && !menu.element.contains(event.target)) {
-     *     menu.hide();
-     *   }
-     * });
-     * ```
+     * Closes the menu
+     * @param event - Optional event that triggered the close
+     * @returns Menu component for chaining
      */
-    hide(): MenuComponent {
-      component.hide?.();
+    close(event?: Event) {
+      menu.close(event);
       return this;
     },
-
+    
     /**
-     * Positions the menu relative to a target element
-     * 
-     * Calculates and sets the position of the menu relative to the specified target element.
-     * This allows precise control over menu placement in the UI.
-     * 
-     * @param {HTMLElement} target - Target element to position against
-     * @param {MenuPositionConfig} options - Position configuration
-     * @returns {MenuComponent} Component instance for method chaining
-     * @example
-     * ```typescript
-     * // Position relative to a button with default alignment (left, bottom)
-     * menu.position(document.getElementById('menuButton'));
-     * 
-     * // Position with custom alignment
-     * menu.position(buttonElement, {
-     *   align: 'right',    // Align to the right edge of the target
-     *   vAlign: 'top',     // Position above the target
-     *   offsetX: 5,        // Add 5px horizontal offset
-     *   offsetY: 10        // Add 10px vertical offset
-     * });
-     * ```
+     * Toggles the menu's open state
+     * @param event - Optional event that triggered the toggle
+     * @returns Menu component for chaining
      */
-    position(target: HTMLElement, options?: MenuPositionConfig): MenuComponent {
-      component.position?.(target, options);
+    toggle(event?: Event) {
+      menu.toggle(event);
       return this;
     },
-
+    
     /**
-     * Adds an item to the menu
-     * 
-     * Dynamically adds a new item to the menu. This can be called at any time,
-     * even after the menu has been rendered and shown.
-     * 
-     * @param {MenuItemConfig} config - Item configuration
-     * @returns {MenuComponent} Component instance for method chaining
-     * @example
-     * ```typescript
-     * // Add a standard item
-     * menu.addItem({ name: 'edit', text: 'Edit' });
-     * 
-     * // Add a divider
-     * menu.addItem({ type: 'divider' });
-     * 
-     * // Add a disabled item
-     * menu.addItem({ name: 'print', text: 'Print', disabled: true });
-     * 
-     * // Add an item with a submenu
-     * menu.addItem({
-     *   name: 'share',
-     *   text: 'Share',
-     *   items: [
-     *     { name: 'email', text: 'Email' },
-     *     { name: 'link', text: 'Copy Link' }
-     *   ]
-     * });
-     * ```
+     * Checks if the menu is currently open
+     * @returns True if the menu is open
      */
-    addItem(config: MenuItemConfig): MenuComponent {
-      component.addItem?.(config);
-      return this;
+    isOpen() {
+      return menu.isOpen();
     },
-
+    
     /**
-     * Removes an item from the menu
-     * 
-     * Dynamically removes an item from the menu by its name identifier.
-     * If the item doesn't exist, no action is taken.
-     * 
-     * @param {string} name - Name identifier of the item to remove
-     * @returns {MenuComponent} Component instance for method chaining
-     * @example
-     * ```typescript
-     * // Remove an item by name
-     * menu.removeItem('delete');
-     * 
-     * // Check if a condition is met, then remove an item
-     * if (!userHasEditPermission) {
-     *   menu.removeItem('edit');
-     * }
-     * ```
+     * Updates the menu items
+     * @param items - New array of menu items and dividers
+     * @returns Menu component for chaining
      */
-    removeItem(name: string): MenuComponent {
-      component.removeItem?.(name);
+    setItems(items: MenuContent[]) {
+      menu.setItems(items);
       return this;
     },
-
+    
     /**
-     * Gets all registered menu items
-     * 
-     * Returns a Map containing all the current menu items, indexed by their name.
-     * Each entry contains the item's DOM element and configuration.
-     * 
-     * @returns {Map<string, MenuItemData>} Map of item names to their data
-     * @example
-     * ```typescript
-     * // Get all items
-     * const items = menu.getItems();
-     * 
-     * // Check if a specific item exists
-     * if (items.has('delete')) {
-     *   console.log('Delete item exists');
-     * }
-     * 
-     * // Get the element for a specific item
-     * const editItem = items.get('edit');
-     * if (editItem) {
-     *   console.log('Edit item element:', editItem.element);
-     *   console.log('Edit item config:', editItem.config);
-     * }
-     * ```
+     * Gets the current menu items
+     * @returns Array of current menu items and dividers
      */
     getItems() {
-      return component.getItems?.() || new Map();
+      return menu.getItems();
     },
-
+    
     /**
-     * Checks if the menu is currently visible
-     * 
-     * Returns true if the menu is currently visible in the DOM,
-     * false otherwise.
-     * 
-     * @returns {boolean} Whether the menu is visible
-     * @example
-     * ```typescript
-     * // Check if menu is visible before performing an action
-     * if (menu.isVisible()) {
-     *   menu.hide();
-     * } else {
-     *   menu.position(button).show();
-     * }
-     * 
-     * // Toggle menu visibility
-     * toggleButton.addEventListener('click', () => {
-     *   if (menu.isVisible()) {
-     *     menu.hide();
-     *   } else {
-     *     menu.position(toggleButton).show();
-     *   }
-     * });
-     * ```
+     * Updates the menu's anchor element
+     * @param anchorElement - New anchor element or selector
+     * @returns Menu component for chaining
      */
-    isVisible(): boolean {
-      return component.isVisible?.() || false;
+    setAnchor(anchorElement: HTMLElement | string) {
+      anchor.setAnchor(anchorElement);
+      return this;
     },
-
+    
+    /**
+     * Gets the current anchor element
+     * @returns Current anchor element
+     */
+    getAnchor() {
+      return anchor.getAnchor();
+    },
+    
     /**
-     * Registers an event handler
-     * 
-     * Subscribes to menu events like 'select', 'open', 'close', etc.
-     * The handler will be called whenever the specified event occurs.
-     * 
-     * @param {string} event - Event name to listen for
-     * @param {Function} handler - Callback function to execute when the event occurs
-     * @returns {MenuComponent} Component instance for method chaining
-     * @example
-     * ```typescript
-     * // Listen for item selection
-     * menu.on('select', (event) => {
-     *   console.log(`Selected item: ${event.name}`);
-     *   
-     *   if (event.name === 'delete') {
-     *     confirmDelete();
-     *   }
-     * });
-     * 
-     * // Listen for menu opening
-     * menu.on('open', () => {
-     *   console.log('Menu opened');
-     *   analytics.trackMenuOpen();
-     * });
-     * 
-     * // Listen for submenu opening
-     * menu.on('submenuOpen', (data) => {
-     *   console.log('Submenu opened:', data);
-     * });
-     * ```
+     * Updates the menu's placement
+     * @param placement - New placement value
+     * @returns Menu component for chaining
      */
-    on(event: string, handler: Function): MenuComponent {
-      component.on?.(event, handler);
+    setPlacement(placement: MenuPlacement) {
+      menu.setPlacement(placement);
       return this;
     },
-
+    
     /**
-     * Unregisters an event handler
-     * 
-     * Removes a previously registered event handler.
-     * If the handler is not found, no action is taken.
-     * 
-     * @param {string} event - Event name to stop listening for
-     * @param {Function} handler - The handler function to remove
-     * @returns {MenuComponent} Component instance for method chaining
-     * @example
-     * ```typescript
-     * // Define a handler function
-     * const handleSelection = (event) => {
-     *   console.log(`Selected: ${event.name}`);
-     * };
-     * 
-     * // Register the handler
-     * menu.on('select', handleSelection);
-     * 
-     * // Later, unregister the handler
-     * menu.off('select', handleSelection);
-     * ```
+     * Gets the current menu placement
+     * @returns Current placement
      */
-    off(event: string, handler: Function): MenuComponent {
-      component.off?.(event, handler);
+    getPlacement() {
+      return menu.getPlacement();
+    },
+    
+    /**
+     * Adds an event listener to the menu
+     * @param event - Event name ('open', 'close', 'select')
+     * @param handler - Event handler function
+     * @returns Menu component for chaining
+     */
+    on(event, handler) {
+      if (events?.on) {
+        events.on(event, handler);
+      } else if (component.on) {
+        component.on(event, handler);
+      }
       return this;
     },
-
+    
     /**
-     * Destroys the menu component and cleans up resources
-     * 
-     * Performs complete cleanup by removing event listeners, DOM elements,
-     * and references to prevent memory leaks. After calling this method,
-     * the menu instance should not be used again.
-     * 
-     * @returns {MenuComponent} Component instance
-     * @example
-     * ```typescript
-     * // When no longer needed, destroy the menu
-     * menu.destroy();
-     * 
-     * // When navigating away or changing views
-     * function changeView() {
-     *   // Clean up existing components
-     *   contextMenu.destroy();
-     *   
-     *   // Set up new view
-     *   setupNewView();
-     * }
-     * ```
+     * Removes an event listener from the menu
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns Menu component for chaining
      */
-    destroy(): MenuComponent {
-      // First close any open submenus
-      component.hide?.();
-
-      // Then destroy the component
-      lifecycle.destroy?.();
-
-      // Final cleanup - forcibly remove from DOM if still attached
-      if (component.element && component.element.parentNode) {
-        component.element.remove();
+    off(event, handler) {
+      if (events?.off) {
+        events.off(event, handler);
+      } else if (component.off) {
+        component.off(event, handler);
       }
-
       return this;
+    },
+    
+    /**
+     * Destroys the menu component and cleans up resources
+     */
+    destroy() {
+      lifecycle.destroy();
     }
-  });
+  });
+
+export default withAPI;

package/src/components/menu/config.ts

@@ -1,80 +1,124 @@
 // src/components/menu/config.ts
-import { PREFIX } from '../../core/config';
+
 import { 
   createComponentConfig, 
   createElementConfig,
   BaseComponentConfig 
 } from '../../core/config/component-config';
-import { MenuConfig, BaseComponent, ApiOptions } from './types';
+import { MenuConfig, MENU_PLACEMENT } from './types';
 
 /**
  * Default configuration for the Menu component
+ * These values will be used when not explicitly specified by the user.
  * 
- * Defines the standard behavior and initial state for menus.
- * These defaults are merged with user-provided configuration options.
- * 
- * @internal
  * @category Components
  */
 export const defaultConfig: MenuConfig = {
-  /** Empty initial items array */
   items: [],
-  
-  /** By default, menus close when an item is selected */
-  stayOpenOnSelect: false
+  placement: MENU_PLACEMENT.BOTTOM_START,
+  closeOnSelect: true,
+  closeOnClickOutside: true,
+  closeOnEscape: true,
+  openSubmenuOnHover: true,
+  offset: 8,
+  autoFlip: true,
+  visible: false
 };
 
 /**
- * Creates the base configuration for Menu component
- * 
- * Merges user-provided configuration with default values
- * to ensure all required properties are available.
+ * Creates the base configuration for Menu component by merging user-provided
+ * config with default values.
  * 
  * @param {MenuConfig} config - User provided configuration
  * @returns {MenuConfig} Complete configuration with defaults applied
- * @internal
  * @category Components
+ * @internal
  */
-export const createBaseConfig = (config: MenuConfig = {}): MenuConfig => 
-  createComponentConfig(defaultConfig, config, 'menu') as MenuConfig;
+export const createBaseConfig = (config: MenuConfig): MenuConfig => {
+  // First, ensure we have an anchor element
+  if (!config.anchor) {
+    throw new Error('Menu component requires an anchor element or selector');
+  }
+  
+  // Apply default configuration
+  return createComponentConfig(defaultConfig, config, 'menu') as MenuConfig;
+};
 
 /**
- * Generates element configuration for the Menu component
- * 
- * Creates the configuration needed for the DOM element creation.
- * Sets up proper accessibility attributes like ARIA roles and states.
+ * Generates element configuration for the Menu component.
+ * This function creates the necessary attributes and configuration
+ * for the DOM element creation process.
  * 
  * @param {MenuConfig} config - Menu configuration
  * @returns {Object} Element configuration object for withElement
- * @internal
  * @category Components
+ * @internal
  */
-export const getElementConfig = (config: MenuConfig) => 
-  createElementConfig(config, {
+export const getElementConfig = (config: MenuConfig) => {
+  // Custom styles based on configuration
+  const styles: Record<string, string> = {};
+  
+  if (config.width) {
+    styles.width = config.width;
+  }
+  
+  if (config.maxHeight) {
+    styles.maxHeight = config.maxHeight;
+  }
+  
+  // Element attributes
+  const attrs: Record<string, any> = {
+    role: 'menu',
+    tabindex: '-1',
+    'aria-hidden': (!config.visible).toString(),
+    style: Object.entries(styles)
+      .map(([key, value]) => `${key}: ${value}`)
+      .join(';')
+  };
+  
+  return createElementConfig(config, {
     tag: 'div',
-    componentName: 'menu',
-    attrs: {
-      role: 'menu',
-      tabindex: '-1',
-      'aria-hidden': 'true'
-    },
-    className: config.class
+    attrs,
+    className: [
+      config.visible ? 'menu--visible' : null,
+      config.class
+    ].filter(Boolean),
+    forwardEvents: {
+      keydown: true
+    }
   });
+};
 
 /**
- * Creates API configuration for the Menu component
- * 
- * Builds the configuration needed for the withAPI feature,
- * including lifecycle methods for proper resource cleanup.
+ * Creates API configuration for the Menu component.
+ * This connects the core component features to the public API.
  * 
- * @param {BaseComponent} comp - Component with lifecycle feature
- * @returns {ApiOptions} API configuration object
- * @internal
+ * @param {Object} component - Component with menu features
+ * @returns {Object} API configuration object
  * @category Components
+ * @internal
  */
-export const getApiConfig = (comp: BaseComponent): ApiOptions => ({
+export const getApiConfig = (component) => ({
+  menu: {
+    open: () => component.menu?.open(),
+    close: () => component.menu?.close(),
+    toggle: () => component.menu?.toggle(),
+    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()
+  },
+  anchor: {
+    setAnchor: (anchor) => component.anchor?.setAnchor(anchor),
+    getAnchor: () => component.anchor?.getAnchor()
+  },
+  events: {
+    on: (event, handler) => component.on?.(event, handler),
+    off: (event, handler) => component.off?.(event, handler)
+  },
   lifecycle: {
-    destroy: comp.lifecycle?.destroy || (() => {})
+    destroy: () => component.lifecycle?.destroy()
   }
 });