mtrl 0.3.5 → 0.3.7

package/src/components/menu/menu.ts

@@ -1,150 +1,118 @@
 // src/components/menu/menu.ts
+
 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 { withVisibility } from './features/visibility';
-import { withItemsManager } from './features/items-manager';
-import { withPositioning } from './features/positioning';
-import { withKeyboardNavigation } from './features/keyboard-navigation';
 import { MenuConfig, MenuComponent } from './types';
-import { 
-  createBaseConfig, 
-  getElementConfig,
-  getApiConfig
-} from './config';
+import { createBaseConfig, getElementConfig, getApiConfig } from './config';
 
 /**
- * Creates a new Menu component
+ * 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.
  * 
- * Creates a Material Design 3 menu that displays a list of choices on a temporary surface.
- * The menu can be positioned relative to other elements, trigger events on selection,
- * and support keyboard navigation.
+ * 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.
  * 
- * The returned component provides these methods:
+ * @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.
  * 
- * `show()` - Shows the menu
- * `hide()` - Hides the menu
- * `position(target, options)` - Positions the menu relative to a target element
- * `addItem(config)` - Adds a menu item
- * `removeItem(name)` - Removes a menu item
- * `getItems()` - Gets all menu items
- * `isVisible()` - Checks if the menu is visible
- * `on(event, handler)` - Adds event listener
- * `off(event, handler)` - Removes event listener
- * `destroy()` - Destroys the menu component
+ * @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.
  * 
- * @param {MenuConfig} config - Menu configuration options
- * @returns {MenuComponent} Menu component instance
+ * @throws {Error} Throws an error if menu creation fails or if required
+ *  configuration (like anchor) is missing.
+ * 
+ * @category Components
  * 
  * @example
- * ```typescript
- * // Create a basic menu with items
+ * // Create a simple menu anchored to a button
+ * const menuButton = document.getElementById('menu-button');
  * const menu = createMenu({
+ *   anchor: menuButton,
  *   items: [
- *     { name: 'item1', text: 'Option 1' },
- *     { name: 'item2', text: 'Option 2' },
+ *     { id: 'item1', text: 'Option 1' },
+ *     { id: 'item2', text: 'Option 2' },
  *     { type: 'divider' },
- *     { name: 'item3', text: 'Option 3' }
+ *     { id: 'item3', text: 'Option 3' }
  *   ]
  * });
  * 
- * // Show the menu positioned relative to a button
- * const button = document.getElementById('menuButton');
- * menu.position(button).show();
- * 
- * // Listen for item selection
+ * // Add event listener for item selection
  * menu.on('select', (event) => {
- *   console.log(`Selected: ${event.name}`);
+ *   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
- * ```typescript
  * // Create a menu with nested submenus
  * const menu = createMenu({
+ *   anchor: '#more-button',
  *   items: [
- *     { name: 'edit', text: 'Edit' },
+ *     { id: 'edit', text: 'Edit', icon: '<svg>...</svg>' },
  *     { 
- *       name: 'share', 
+ *       id: 'share', 
  *       text: 'Share', 
- *       items: [
- *         { name: 'email', text: 'Email' },
- *         { name: 'link', text: 'Copy Link' }
+ *       hasSubmenu: true,
+ *       submenu: [
+ *         { id: 'email', text: 'Email' },
+ *         { id: 'link', text: 'Copy link' }
  *       ]
  *     },
  *     { type: 'divider' },
- *     { name: 'delete', text: 'Delete' }
+ *     { id: 'delete', text: 'Delete', icon: '<svg>...</svg>' }
  *   ],
- *   stayOpenOnSelect: true
+ *   position: 'bottom-end'
  * });
  * 
- * // Add items dynamically
- * menu.addItem({ name: 'newItem', text: 'New Item' });
- * ```
- * 
  * @example
- * ```typescript
- * // Using menu with custom positioning
- * const menu = createMenu({
- *   items: [
- *     { name: 'cut', text: 'Cut' },
- *     { name: 'copy', text: 'Copy' },
- *     { name: 'paste', text: 'Paste' }
- *   ]
- * });
- * 
- * // Position with custom alignment
- * contextButton.addEventListener('click', (event) => {
- *   menu.position(contextButton, {
- *     align: 'right',
- *     vAlign: 'top',
- *     offsetY: 8
- *   }).show();
- *   
- *   event.stopPropagation();
+ * // Specify a custom position for the menu
+ * const filterMenu = createMenu({
+ *   anchor: filterButton,
+ *   items: filterOptions,
+ *   position: MENU_POSITION.TOP_START,
+ *   width: '240px',
+ *   maxHeight: '400px'
  * });
  * 
- * // Close menu when clicking outside
- * document.addEventListener('click', () => {
- *   if (menu.isVisible()) {
- *     menu.hide();
- *   }
- * });
- * ```
+ * // Update the menu's position programmatically
+ * filterMenu.setPosition(MENU_POSITION.BOTTOM_END);
  */
-/**
- * @type {Function}
- * @name createMenu
- */
-const createMenu = (config: MenuConfig = {}): MenuComponent => {
-  const baseConfig = createBaseConfig(config);
-
+const createMenu = (config: MenuConfig): MenuComponent => {
   try {
-    // Create menu component
+    // Validate and create the base configuration
+    const baseConfig = createBaseConfig(config);
+    
+    // Create the component through functional composition
     const menu = pipe(
-      createBase,
-      withEvents(),
-      withElement(getElementConfig(baseConfig)),
-      withLifecycle(),
-      withItemsManager(baseConfig),
-      withVisibility(baseConfig),
-      withPositioning,
-      withKeyboardNavigation(baseConfig),
-      comp => withAPI(getApiConfig(comp))(comp)
+      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
+      comp => withAPI(getApiConfig(comp))(comp)  // Public API
     )(baseConfig);
-
-    // Handle circular dependency for submenus
-    // This is needed because we need the complete menu factory function
-    // to create submenus, but we can't import it directly in items-manager
-    if (menu.setCreateSubmenuFunction) {
-      menu.setCreateSubmenuFunction(createMenu);
-    }
-
-    return menu as MenuComponent;
+    
+    // The menu will be added to the DOM when opened and removed when closed
+    
+    return menu;
   } catch (error) {
-    console.error('Menu creation error:', error instanceof Error ? error.message : String(error));
-    throw new Error(`Failed to create menu: ${error instanceof Error ? error.message : String(error)}`);
+    console.error('Menu creation error:', error);
+    throw new Error(`Failed to create menu: ${(error as Error).message}`);
   }
 };