mtrl 0.3.0 → 0.3.2

package/src/components/menu/api.ts

@@ -2,9 +2,17 @@
 import { ApiOptions, BaseComponent, MenuComponent, MenuItemConfig, MenuPositionConfig } from './types';
 
 /**
- * Enhances menu component with API methods
- * @param {ApiOptions} options - API configuration
+ * 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.
+ * 
+ * @param {ApiOptions} options - API configuration including lifecycle methods
  * @returns {Function} Higher-order function that adds API methods to component
+ * @internal
+ * @category Components
  */
 export const withAPI = ({ lifecycle }: ApiOptions) => 
   (component: BaseComponent): MenuComponent => ({
@@ -13,7 +21,19 @@ export const withAPI = ({ lifecycle }: ApiOptions) =>
 
     /**
      * Shows the menu
-     * @returns {MenuComponent} Component instance
+     * 
+     * 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();
+     * ```
      */
     show(): MenuComponent {
       component.show?.();
@@ -22,7 +42,23 @@ export const withAPI = ({ lifecycle }: ApiOptions) =>
 
     /**
      * Hides the menu
-     * @returns {MenuComponent} Component instance
+     * 
+     * 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();
+     *   }
+     * });
+     * ```
      */
     hide(): MenuComponent {
       component.hide?.();
@@ -30,10 +66,27 @@ export const withAPI = ({ lifecycle }: ApiOptions) =>
     },
 
     /**
-     * Positions the menu relative to a target
-     * @param {HTMLElement} target - Target element
-     * @param {MenuPositionConfig} options - Position options
-     * @returns {MenuComponent} Component instance
+     * 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
+     * });
+     * ```
      */
     position(target: HTMLElement, options?: MenuPositionConfig): MenuComponent {
       component.position?.(target, options);
@@ -42,8 +95,33 @@ export const withAPI = ({ lifecycle }: ApiOptions) =>
 
     /**
      * 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
+     * @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' }
+     *   ]
+     * });
+     * ```
      */
     addItem(config: MenuItemConfig): MenuComponent {
       component.addItem?.(config);
@@ -51,9 +129,23 @@ export const withAPI = ({ lifecycle }: ApiOptions) =>
     },
 
     /**
-     * Removes an item by name
-     * @param {string} name - Item name to remove
-     * @returns {MenuComponent} Component instance
+     * 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');
+     * }
+     * ```
      */
     removeItem(name: string): MenuComponent {
       component.removeItem?.(name);
@@ -61,8 +153,29 @@ export const withAPI = ({ lifecycle }: ApiOptions) =>
     },
 
     /**
-     * Gets all registered items
-     * @returns {Map<string, any>} Map of item names to configurations
+     * 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);
+     * }
+     * ```
      */
     getItems() {
       return component.getItems?.() || new Map();
@@ -70,7 +183,29 @@ export const withAPI = ({ lifecycle }: ApiOptions) =>
 
     /**
      * 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();
+     *   }
+     * });
+     * ```
      */
     isVisible(): boolean {
       return component.isVisible?.() || false;
@@ -78,9 +213,35 @@ export const withAPI = ({ lifecycle }: ApiOptions) =>
 
     /**
      * Registers an event handler
-     * @param {string} event - Event name
-     * @param {Function} handler - Event handler
-     * @returns {MenuComponent} Component instance
+     * 
+     * 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);
+     * });
+     * ```
      */
     on(event: string, handler: Function): MenuComponent {
       component.on?.(event, handler);
@@ -89,9 +250,26 @@ export const withAPI = ({ lifecycle }: ApiOptions) =>
 
     /**
      * Unregisters an event handler
-     * @param {string} event - Event name
-     * @param {Function} handler - Event handler
-     * @returns {MenuComponent} Component instance
+     * 
+     * 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);
+     * ```
      */
     off(event: string, handler: Function): MenuComponent {
       component.off?.(event, handler);
@@ -100,7 +278,26 @@ export const withAPI = ({ lifecycle }: ApiOptions) =>
 
     /**
      * 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();
+     * }
+     * ```
      */
     destroy(): MenuComponent {
       // First close any open submenus

package/src/components/menu/config.ts

@@ -9,24 +9,45 @@ import { MenuConfig, BaseComponent, ApiOptions } from './types';
 
 /**
  * Default configuration for the Menu component
+ * 
+ * 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
 };
 
 /**
  * Creates the base configuration for Menu component
+ * 
+ * Merges user-provided configuration with default values
+ * to ensure all required properties are available.
+ * 
  * @param {MenuConfig} config - User provided configuration
  * @returns {MenuConfig} Complete configuration with defaults applied
+ * @internal
+ * @category Components
  */
 export const createBaseConfig = (config: MenuConfig = {}): MenuConfig => 
   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.
+ * 
  * @param {MenuConfig} config - Menu configuration
  * @returns {Object} Element configuration object for withElement
+ * @internal
+ * @category Components
  */
 export const getElementConfig = (config: MenuConfig) => 
   createElementConfig(config, {
@@ -42,8 +63,14 @@ export const getElementConfig = (config: MenuConfig) =>
 
 /**
  * Creates API configuration for the Menu component
+ * 
+ * Builds the configuration needed for the withAPI feature,
+ * including lifecycle methods for proper resource cleanup.
+ * 
  * @param {BaseComponent} comp - Component with lifecycle feature
  * @returns {ApiOptions} API configuration object
+ * @internal
+ * @category Components
  */
 export const getApiConfig = (comp: BaseComponent): ApiOptions => ({
   lifecycle: {

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

@@ -4,8 +4,24 @@ import { MENU_EVENT, MENU_CLASSES } from '../utils';
 
 /**
  * Adds visibility management functionality to a menu component
- * @param {MenuConfig} config - Menu configuration
- * @returns {Function} Component enhancer
+ * 
+ * This feature adds the ability to show and hide the menu with smooth transitions,
+ * along with proper event handling for clicks outside the menu and keyboard shortcuts.
+ * It implements the following functionality:
+ * 
+ * - Tracking visibility state
+ * - Showing the menu with animation
+ * - Hiding the menu with animation
+ * - Automatic handling of clicks outside the menu
+ * - Keyboard shortcut (Escape) for dismissing the menu
+ * - Proper ARIA attributes for accessibility
+ * - Event emission for component state changes
+ * 
+ * @param {MenuConfig} config - Menu configuration options
+ * @returns {Function} Component enhancer function that adds visibility features
+ * 
+ * @internal
+ * @category Components
  */
 export const withVisibility = (config: MenuConfig) => (component: BaseComponent): BaseComponent => {
   let isVisible = false;
@@ -19,6 +35,13 @@ export const withVisibility = (config: MenuConfig) => (component: BaseComponent)
 
     /**
      * Shows the menu
+     * 
+     * Makes the menu visible with a smooth transition animation.
+     * Handles DOM insertion, event binding, and ARIA attribute updates.
+     * Emits an 'open' event when the menu becomes visible.
+     * 
+     * @returns {BaseComponent} The component instance for method chaining
+     * @internal
      */
     show() {
       if (isVisible) return this;
@@ -67,6 +90,14 @@ export const withVisibility = (config: MenuConfig) => (component: BaseComponent)
 
     /**
      * Hides the menu
+     * 
+     * Makes the menu invisible with a smooth transition animation.
+     * Handles event cleanup, ARIA attribute updates, and DOM removal.
+     * Emits a 'close' event when the menu becomes hidden.
+     * Also ensures any open submenus are closed first.
+     * 
+     * @returns {BaseComponent} The component instance for method chaining
+     * @internal
      */
     hide() {
       // Return early if already hidden
@@ -130,7 +161,12 @@ export const withVisibility = (config: MenuConfig) => (component: BaseComponent)
 
     /**
      * Returns whether the menu is currently visible
-     * @returns {boolean} Visibility state
+     * 
+     * Provides the current visibility state of the menu component.
+     * This method is used internally and exposed via the public API.
+     * 
+     * @returns {boolean} True if the menu is visible, false otherwise
+     * @internal
      */
     isVisible() {
       return isVisible;
@@ -139,7 +175,14 @@ export const withVisibility = (config: MenuConfig) => (component: BaseComponent)
 
   /**
    * Handles clicks outside the menu
-   * @param {MouseEvent} event - Mouse event
+   * 
+   * Event handler for detecting and responding to mouse clicks outside the menu.
+   * Checks if the click occurred outside both the menu and its origin element,
+   * and if so, hides the menu. This provides the auto-dismiss behavior expected
+   * of temporary surfaces like menus.
+   * 
+   * @param {MouseEvent} event - Mouse event containing target information
+   * @internal
    */
   const handleOutsideClick = (event: MouseEvent) => {
     if (!isVisible) return;
@@ -165,8 +208,14 @@ export const withVisibility = (config: MenuConfig) => (component: BaseComponent)
   };
 
   /**
-   * Handles keyboard events
-   * @param {KeyboardEvent} event - Keyboard event
+   * Handles keyboard events for the menu
+   * 
+   * Event handler for keyboard interactions with the menu.
+   * Currently implements the Escape key to dismiss the menu,
+   * following standard interaction patterns for temporary UI surfaces.
+   * 
+   * @param {KeyboardEvent} event - Keyboard event containing key information
+   * @internal
    */
   const handleKeydown = (event: KeyboardEvent) => {
     if (!isVisible) return;

package/src/components/menu/index.ts

@@ -1,5 +1,69 @@
 // src/components/menu/index.ts
+
+/**
+ * @module Menu
+ * 
+ * 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();
+ *     }
+ *   }
+ * });
+ * ```
+ * 
+ * @category Components
+ */
+
+/**
+ * Factory function to create a new Menu component.
+ * @see MenuComponent for the full API reference
+ */
 export { default } from './menu';
+
+/**
+ * Menu component types and interfaces
+ * 
+ * These types define the structure and behavior of the Menu component.
+ */
 export {
   MenuConfig,
   MenuComponent,

package/src/components/menu/menu-item.ts

@@ -3,10 +3,53 @@ import { MenuItemConfig } from './types';
 import { MENU_ITEM_TYPE, getMenuClass } from './utils';
 
 /**
- * Creates a menu item element
+ * Creates a DOM element for a menu item
+ * 
+ * Generates an HTMLElement (li) based on the provided configuration.
+ * Handles different types of menu items (standard, divider, submenu),
+ * applies proper CSS classes, and sets appropriate ARIA attributes
+ * for accessibility.
+ * 
  * @param {MenuItemConfig} itemConfig - Item configuration
- * @param {string} prefix - CSS class prefix
- * @returns {HTMLElement} Menu item element
+ * @param {string} prefix - CSS class prefix (default: 'mtrl')
+ * @returns {HTMLElement} Menu item DOM element
+ * 
+ * @example
+ * ```typescript
+ * // Create a standard menu item
+ * const itemElement = createMenuItem(
+ *   { name: 'edit', text: 'Edit' },
+ *   'mtrl'
+ * );
+ * 
+ * // Create a disabled menu item
+ * const disabledItem = createMenuItem(
+ *   { name: 'print', text: 'Print', disabled: true },
+ *   'mtrl'
+ * );
+ * 
+ * // Create a divider
+ * const divider = createMenuItem(
+ *   { type: 'divider' },
+ *   'mtrl'
+ * );
+ * 
+ * // Create an item with submenu indicator
+ * const submenuItem = createMenuItem(
+ *   {
+ *     name: 'share',
+ *     text: 'Share',
+ *     items: [
+ *       { name: 'email', text: 'Email' },
+ *       { name: 'link', text: 'Copy Link' }
+ *     ]
+ *   },
+ *   'mtrl'
+ * );
+ * ```
+ * 
+ * @internal
+ * @category Components
  */
 export const createMenuItem = (itemConfig: MenuItemConfig, prefix: string): HTMLElement => {
   const item = document.createElement('li');

package/src/components/menu/menu.ts

@@ -16,7 +16,25 @@ import {
 
 /**
  * Creates a new Menu component
- * @param {MenuConfig} config - Menu configuration
+ * 
+ * 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 returned component provides these methods:
+ * 
+ * `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
+ * 
+ * @param {MenuConfig} config - Menu configuration options
  * @returns {MenuComponent} Menu component instance
  * 
  * @example
@@ -40,6 +58,64 @@ import {
  *   console.log(`Selected: ${event.name}`);
  * });
  * ```
+ * 
+ * @example
+ * ```typescript
+ * // Create a menu with nested submenus
+ * const menu = createMenu({
+ *   items: [
+ *     { name: 'edit', text: 'Edit' },
+ *     { 
+ *       name: 'share', 
+ *       text: 'Share', 
+ *       items: [
+ *         { name: 'email', text: 'Email' },
+ *         { name: 'link', text: 'Copy Link' }
+ *       ]
+ *     },
+ *     { type: 'divider' },
+ *     { name: 'delete', text: 'Delete' }
+ *   ],
+ *   stayOpenOnSelect: true
+ * });
+ * 
+ * // 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();
+ * });
+ * 
+ * // Close menu when clicking outside
+ * document.addEventListener('click', () => {
+ *   if (menu.isVisible()) {
+ *     menu.hide();
+ *   }
+ * });
+ * ```
+ */
+/**
+ * @type {Function}
+ * @name createMenu
  */
 const createMenu = (config: MenuConfig = {}): MenuComponent => {
   const baseConfig = createBaseConfig(config);