mtrl 0.3.3 → 0.3.6

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

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

package/src/components/menu/index.ts

@@ -1,76 +1,44 @@
 // src/components/menu/index.ts
 
 /**
- * @module Menu
+ * Menu component module
  * 
- * Menu component following Material Design 3 guidelines.
- * Menus display a list of choices on a temporary surface, appearing when users
- * interact with a button, action, or other control.
- * 
- * The main export is the {@link default | createMenu} factory function that creates
- * a {@link MenuComponent} instance with the provided configuration.
- * 
- * Features:
- * - Configurable positioning relative to other elements
- * - Support for nested submenus
- * - Keyboard navigation and accessibility
- * - Item selection events
- * - Automatic handling of outside clicks
- * - Support for dividers and disabled items
- * - Dynamic item management
- * 
- * @example
- * ```typescript
- * // Create a basic menu
- * const menu = createMenu({
- *   items: [
- *     { name: 'edit', text: 'Edit' },
- *     { name: 'duplicate', text: 'Duplicate' },
- *     { type: 'divider' },
- *     { name: 'delete', text: 'Delete', class: 'danger-item' }
- *   ]
- * });
- * 
- * // Show the menu positioned relative to a button
- * const button = document.getElementById('menuButton');
- * button.addEventListener('click', () => {
- *   menu.position(button).show();
- * });
- * 
- * // Handle menu selection
- * menu.on('select', (event) => {
- *   console.log(`Selected: ${event.name}`);
- *   
- *   if (event.name === 'delete') {
- *     // Confirm deletion
- *     if (confirm('Are you sure?')) {
- *       deleteItem();
- *     }
- *   }
- * });
- * ```
+ * The Menu component provides a Material Design 3 compliant dropdown menu
+ * system with support for nested menus, keyboard navigation, and accessibility.
  * 
+ * @module components/menu
  * @category Components
  */
 
-/**
- * Factory function to create a new Menu component.
- * @see MenuComponent for the full API reference
- */
+// Export main component factory
 export { default } from './menu';
 
+// Export types and interfaces
+export type { 
+  MenuConfig, 
+  MenuComponent, 
+  MenuItem, 
+  MenuDivider,
+  MenuContent,
+  MenuEvent,
+  MenuSelectEvent,
+  MenuPlacement
+} from './types';
+
 /**
- * Menu component types and interfaces
+ * Constants for menu placement values - use these instead of string literals
+ * for better code completion and type safety.
+ * 
+ * @example
+ * import { createMenu, MENU_PLACEMENT } 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 
+ * });
  * 
- * These types define the structure and behavior of the Menu component.
+ * @category Components
  */
-export {
-  MenuConfig,
-  MenuComponent,
-  MenuItemConfig,
-  MenuPositionConfig,
-  MenuAlign,
-  MenuVerticalAlign,
-  MenuItemType,
-  MenuEvent
-} from './types';
+export { MENU_PLACEMENT } from './types';

package/src/components/menu/menu.ts

@@ -1,150 +1,160 @@
 // 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 { 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.
+ * @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.
  * 
- * The returned component provides these methods:
+ * @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.
  * 
- * `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
+ * @throws {Error} Throws an error if menu creation fails or if required
+ *  configuration (like anchor) is missing.
  * 
- * @param {MenuConfig} config - Menu configuration options
- * @returns {MenuComponent} Menu component instance
+ * @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();
+ * // Add the menu to the document
+ * document.body.appendChild(menu.element);
  * 
- * // 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);
  * });
- * ```
  * 
  * @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
+ *   placement: 'bottom-end'
+ * });
+ * 
+ * @example
+ * // Programmatically control menu visibility
+ * const userMenu = createMenu({
+ *   anchor: userAvatar,
+ *   items: userMenuItems
  * });
  * 
- * // Add items dynamically
- * menu.addItem({ name: 'newItem', text: 'New Item' });
- * ```
+ * // 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
- * ```typescript
- * // Using menu with custom positioning
+ * // Create a simple menu anchored to a button
+ * const menuButton = document.getElementById('menu-button');
  * const menu = createMenu({
+ *   anchor: menuButton,
  *   items: [
- *     { name: 'cut', text: 'Cut' },
- *     { name: 'copy', text: 'Copy' },
- *     { name: 'paste', text: 'Paste' }
+ *     { id: 'item1', text: 'Option 1' },
+ *     { id: 'item2', text: 'Option 2' },
+ *     { type: 'divider' },
+ *     { id: 'item3', text: 'Option 3' }
  *   ]
  * });
  * 
- * // Position with custom alignment
- * contextButton.addEventListener('click', (event) => {
- *   menu.position(contextButton, {
- *     align: 'right',
- *     vAlign: 'top',
- *     offsetY: 8
- *   }).show();
- *   
- *   event.stopPropagation();
+ * // Add event listener for item selection
+ * menu.on('select', (event) => {
+ *   console.log('Selected item:', event.itemId);
  * });
  * 
- * // Close menu when clicking outside
- * document.addEventListener('click', () => {
- *   if (menu.isVisible()) {
- *     menu.hide();
- *   }
- * });
- * ```
- */
-/**
- * @type {Function}
- * @name createMenu
+ * // Menu will be added to the DOM when opened and removed when closed
+ * menuButton.addEventListener('click', () => menu.toggle());
  */
-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
+      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}`);
   }
 };