mtrl 0.3.3 → 0.3.6

package/src/components/menu/types.ts

@@ -1,562 +1,378 @@
 // src/components/menu/types.ts
 
 /**
- * Menu horizontal alignment options
- * 
- * Determines how the menu is horizontally aligned relative to its anchor element.
- * 
- * @category Components
- * @example
- * ```typescript
- * // Position menu with right alignment
- * menu.position(buttonElement, { align: 'right' });
- * ```
- */
-export type MenuAlign = 'left' | 'right' | 'center';
-
-/**
- * Menu vertical alignment options
- * 
- * Determines how the menu is vertically positioned relative to its anchor element.
- * 
- * @category Components
- * @example
- * ```typescript
- * // Position menu above the anchor element
- * menu.position(buttonElement, { vAlign: 'top' });
- * ```
- */
-export type MenuVerticalAlign = 'top' | 'bottom' | 'middle';
-
-/**
- * Menu item types
- * 
- * Defines the different types of items that can be added to a menu.
- * - 'item': Standard selectable menu item (default)
- * - 'divider': Horizontal line separating groups of menu items
+ * Menu placement options
+ * Controls where the menu will appear relative to its anchor element
  * 
  * @category Components
- * @example
- * ```typescript
- * // Adding a divider between menu items
- * menu.addItem({ type: 'divider' });
- * ```
  */
-export type MenuItemType = 'item' | 'divider';
+export const MENU_PLACEMENT = {
+  /** Places menu below the anchor, aligned to left edge */
+  BOTTOM_START: 'bottom-start',
+  /** Places menu below the anchor, centered */
+  BOTTOM: 'bottom',
+  /** Places menu below the anchor, aligned to right edge */
+  BOTTOM_END: 'bottom-end',
+  /** Places menu above the anchor, aligned to left edge */
+  TOP_START: 'top-start',
+  /** Places menu above the anchor, centered */
+  TOP: 'top',
+  /** Places menu above the anchor, aligned to right edge */
+  TOP_END: 'top-end',
+  /** Places menu to the right of the anchor, aligned to top edge */
+  RIGHT_START: 'right-start',
+  /** Places menu to the right of the anchor, centered */
+  RIGHT: 'right',
+  /** Places menu to the right of the anchor, aligned to bottom edge */
+  RIGHT_END: 'right-end',
+  /** Places menu to the left of the anchor, aligned to top edge */
+  LEFT_START: 'left-start',
+  /** Places menu to the left of the anchor, centered */
+  LEFT: 'left',
+  /** Places menu to the left of the anchor, aligned to bottom edge */
+  LEFT_END: 'left-end'
+} as const;
 
 /**
- * Menu events
- * 
- * Events that can be subscribed to for the Menu component.
- * - 'select': Fired when a menu item is selected
- * - 'open': Fired when the menu is shown
- * - 'close': Fired when the menu is hidden
- * - 'submenuOpen': Fired when a submenu is opened
- * - 'submenuClose': Fired when a submenu is closed
+ * Alignment options for the menu
  * 
  * @category Components
- * @example
- * ```typescript
- * // Listen for menu open events
- * menu.on('open', () => {
- *   console.log('Menu opened');
- * });
- * 
- * // Listen for item selection
- * menu.on('select', (event) => {
- *   console.log(`Selected item: ${event.name}`);
- * });
- * ```
  */
-export type MenuEvent = 'select' | 'open' | 'close' | 'submenuOpen' | 'submenuClose';
+export type MenuPlacement = typeof MENU_PLACEMENT[keyof typeof MENU_PLACEMENT];
 
 /**
- * Menu item configuration
- * 
- * Configuration object for individual menu items.
+ * Configuration interface for a menu item
  * 
  * @category Components
- * @example
- * ```typescript
- * // Basic menu item
- * const basicItem: MenuItemConfig = { 
- *   name: 'edit', 
- *   text: 'Edit Document' 
- * };
- * 
- * // Disabled menu item
- * const disabledItem: MenuItemConfig = { 
- *   name: 'print', 
- *   text: 'Print', 
- *   disabled: true 
- * };
- * 
- * // Menu item with a submenu
- * const itemWithSubmenu: MenuItemConfig = { 
- *   name: 'share', 
- *   text: 'Share', 
- *   items: [
- *     { name: 'email', text: 'Email' },
- *     { name: 'link', text: 'Copy Link' }
- *   ]
- * };
- * 
- * // Divider item
- * const divider: MenuItemConfig = { type: 'divider' };
- * ```
  */
-export interface MenuItemConfig {
+export interface MenuItem {
   /** 
-   * Unique identifier for the item
-   * Used for identifying the item when handling selection events
+   * Unique ID for the menu item
+   * Required for accessibility and event handling
    */
-  name: string;
+  id: string;
   
-  /** 
-   * Text content displayed for the item
-   * This is the visible label shown in the menu
+  /**
+   * Display text for the menu item
    */
   text: string;
   
-  /** 
-   * Type of menu item
-   * Defaults to 'item' if not specified
+  /**
+   * Optional icon to display before the text
+   * Accepts HTML string (typically SVG)
    */
-  type?: MenuItemType | string;
-  
-  /** 
-   * Whether the item is disabled
-   * Disabled items can't be selected and appear visually muted
-   */
-  disabled?: boolean;
+  icon?: string;
   
-  /** 
-   * Additional CSS classes to apply to the item
-   * Useful for custom styling or visual indicators
+  /**
+   * Optional keyboard shortcut hint to display
+   * Shown at the end of the menu item
    */
-  class?: string;
+  shortcut?: string;
   
-  /** 
-   * Submenu items
-   * Creates a nested menu that appears when this item is hovered
-   */
-  items?: MenuItemConfig[];
-}
-
-/**
- * Menu position configuration
- * 
- * Configures how a menu is positioned relative to an anchor element.
- * This allows for precise control over menu placement in the UI.
- * 
- * @category Components
- * @example
- * ```typescript
- * // Position menu at the bottom-right of the anchor with additional offset
- * menu.position(buttonElement, {
- *   align: 'right',
- *   vAlign: 'bottom',
- *   offsetX: 5,
- *   offsetY: 10
- * });
- * 
- * // Center align menu below the anchor
- * menu.position(buttonElement, {
- *   align: 'center',
- *   vAlign: 'bottom'
- * });
- * ```
- */
-export interface MenuPositionConfig {
-  /** 
-   * Horizontal alignment
-   * Controls how the menu aligns horizontally with the anchor element
-   * @default 'left'
+  /**
+   * Whether the menu item is disabled
+   * Disabled items cannot be clicked but remain visible
    */
-  align?: MenuAlign | string;
+  disabled?: boolean;
   
-  /** 
-   * Vertical alignment
-   * Controls how the menu aligns vertically with the anchor element
-   * @default 'bottom'
+  /**
+   * Whether this item has a submenu
+   * If true, the item will show an indicator and can open a nested menu
    */
-  vAlign?: MenuVerticalAlign | string;
+  hasSubmenu?: boolean;
   
-  /** 
-   * Horizontal offset in pixels
-   * Additional horizontal offset from the aligned position
-   * Positive values move the menu to the right
-   * @default 0
+  /**
+   * Optional array of submenu items
+   * Only used when hasSubmenu is true
    */
-  offsetX?: number;
+  submenu?: MenuItem[];
   
-  /** 
-   * Vertical offset in pixels
-   * Additional vertical offset from the aligned position
-   * Positive values move the menu downward
-   * @default 0
+  /**
+   * Additional data to associate with the menu item
+   * This can be used for custom behavior in click handlers
    */
-  offsetY?: number;
+  data?: any;
 }
 
 /**
- * Menu position result
- * 
- * Contains the calculated position values for a menu.
- * Used internally by the positioning system.
+ * Menu item type for dividers
  * 
  * @category Components
- * @internal
  */
-export interface MenuPosition {
-  /** 
-   * Left position in pixels
-   * Absolute position from the left edge of the viewport
+export interface MenuDivider {
+  /**
+   * Type must be 'divider' to differentiate from regular menu items
    */
-  left: number;
+  type: 'divider';
   
-  /** 
-   * Top position in pixels
-   * Absolute position from the top edge of the viewport
+  /**
+   * Optional ID for the divider (for accessibility)
    */
-  top: number;
+  id?: string;
 }
 
 /**
- * Menu item internal data structure
- * 
- * Used internally to track menu item DOM elements and their configurations.
- * This helps with item management and event handling.
+ * Combined type for menu content items (regular items or dividers)
  * 
  * @category Components
- * @internal
  */
-export interface MenuItemData {
-  /** 
-   * DOM element for the item
-   * Reference to the rendered menu item element
-   */
-  element: HTMLElement;
-  
-  /** 
-   * Item configuration
-   * The configuration that was used to create this item
-   */
-  config: MenuItemConfig;
-}
+export type MenuContent = MenuItem | MenuDivider;
 
 /**
- * Menu selection event data
- * 
- * Contains information about a selected menu item.
- * This is passed to event handlers when an item is selected.
+ * Configuration interface for the Menu component
  * 
  * @category Components
- * @example
- * ```typescript
- * menu.on('select', (event: MenuSelectEvent) => {
- *   console.log(`Selected: ${event.name}`);
- *   console.log(`Text: ${event.text}`);
- *   
- *   // For submenu items, path contains the hierarchy
- *   if (event.path) {
- *     console.log(`From submenu path: ${event.path.join(' > ')}`);
- *   }
- * });
- * ```
  */
-export interface MenuSelectEvent {
-  /** 
-   * Name of the selected item
-   * Matches the name property from MenuItemConfig
+export interface MenuConfig {
+  /**
+   * Element to which the menu will be anchored
+   * Can be an HTML element or a CSS selector string
    */
-  name: string;
+  anchor: HTMLElement | string;
   
-  /** 
-   * Text content of the selected item
-   * The visible text that was displayed in the menu
+  /**
+   * Array of menu items and dividers to display
    */
-  text: string;
+  items: MenuContent[];
   
-  /** 
-   * Path of parent item names (for submenus)
-   * For nested menu selections, contains the names of all parent items
-   * from top level to the selected item
+  /**
+   * Placement of the menu relative to the anchor
+   * @default 'bottom-start'
    */
-  path?: string[];
-}
-
-/**
- * Configuration interface for the Menu component
- * 
- * Provides options for creating and configuring a Menu component.
- * 
- * @category Components
- * @example
- * ```typescript
- * // Create a basic menu with initial items
- * const menu = createMenu({
- *   items: [
- *     { name: 'copy', text: 'Copy' },
- *     { name: 'paste', text: 'Paste' },
- *     { type: 'divider' },
- *     { name: 'delete', text: 'Delete' }
- *   ],
- *   stayOpenOnSelect: false,
- *   class: 'custom-menu'
- * });
- * 
- * // Create a submenu
- * const submenu = createMenu({
- *   items: [
- *     { name: 'option1', text: 'Option 1' },
- *     { name: 'option2', text: 'Option 2' }
- *   ],
- *   parentItem: parentElement
- * });
- * ```
- */
-export interface MenuConfig {
-  /** 
-   * Initial menu items
-   * Array of item configurations to populate the menu with
+  placement?: MenuPlacement;
+  
+  /**
+   * Whether the menu should close when an item is clicked
+   * @default true
    */
-  items?: MenuItemConfig[];
+  closeOnSelect?: boolean;
   
-  /** 
-   * Additional CSS classes
-   * Custom classes to apply to the menu container element
+  /**
+   * Whether the menu should close when the user clicks outside
+   * @default true
    */
-  class?: string;
+  closeOnClickOutside?: boolean;
   
-  /** 
-   * Whether to keep menu open after selection
-   * When true, selecting an item will not automatically close the menu
-   * @default false
+  /**
+   * Whether the menu should close when the escape key is pressed
+   * @default true
    */
-  stayOpenOnSelect?: boolean;
+  closeOnEscape?: boolean;
   
-  /** 
-   * Origin element that opens the menu
-   * Element used to trigger the menu appearance (like a button)
+  /**
+   * Whether submenus should open on hover
+   * @default true
    */
-  origin?: HTMLElement | { element: HTMLElement };
+  openSubmenuOnHover?: boolean;
   
-  /** 
-   * Parent item element (for submenus)
-   * For submenus, references the parent menu item this menu belongs to
+  /**
+   * Optional width for the menu (in CSS units)
+   * If not provided, menu will size to its content
    */
-  parentItem?: HTMLElement;
+  width?: string;
   
-  /** 
-   * Prefix for class names
-   * Custom prefix for all CSS class names generated by the component
+  /**
+   * Optional maximum height for the menu (in CSS units)
+   * If content exceeds this height, the menu will scroll
+   */
+  maxHeight?: string;
+  
+  /**
+   * Optional offset from the anchor (in pixels)
+   * @default 8
+   */
+  offset?: number;
+  
+  /**
+   * Whether the menu should automatically flip placement to stay in viewport
+   * @default true
+   */
+  autoFlip?: boolean;
+  
+  /**
+   * Whether the menu is initially visible
+   * @default false
+   */
+  visible?: boolean;
+  
+  /**
+   * Additional CSS classes to add to the menu
+   */
+  class?: string;
+  
+  /**
+   * Component prefix for CSS class names
    * @default 'mtrl'
    */
   prefix?: string;
   
-  /** 
-   * Component name
-   * Name identifier used in CSS classes and debugging
+  /**
+   * Component name used in CSS class generation
    * @default 'menu'
    */
   componentName?: string;
+  
+  /**
+   * Event handlers for the menu
+   */
+  on?: {
+    /**
+     * Called when the menu is opened
+     */
+    open?: (event: MenuEvent) => void;
+    
+    /**
+     * Called when the menu is closed
+     */
+    close?: (event: MenuEvent) => void;
+    
+    /**
+     * Called when a menu item is selected
+     */
+    select?: (event: MenuSelectEvent) => void;
+  };
 }
 
 /**
- * Menu component interface
- * 
- * Represents a Material Design 3 menu component that provides a temporary
- * surface containing choices that users can interact with.
- * 
- * The menu supports positioning, item management, keyboard navigation,
- * and event handling for user interactions.
- * 
- * This interface is implemented by the object returned from the {@link ../menu!default | createMenu} function.
+ * Menu event interface
  * 
  * @category Components
- * @example
- * ```typescript
- * // Create a menu with items
- * const menu = createMenu({
- *   items: [
- *     { name: 'edit', text: 'Edit' },
- *     { name: 'duplicate', text: 'Duplicate' },
- *     { type: 'divider' },
- *     { name: 'delete', text: 'Delete' }
- *   ]
- * });
- * 
- * // Position and show the menu
- * const button = document.getElementById('menuButton');
- * button.addEventListener('click', () => {
- *   menu.position(button).show();
- * });
+ */
+export interface MenuEvent {
+  /** The menu component that triggered the event */
+  menu: MenuComponent;
+  
+  /** Original DOM event if available */
+  originalEvent?: Event;
+  
+  /** Function to prevent default behavior */
+  preventDefault: () => void;
+  
+  /** Whether default behavior was prevented */
+  defaultPrevented: boolean;
+}
+
+/**
+ * Menu selection event interface
  * 
- * // Handle selection
- * menu.on('select', (event) => {
- *   console.log(`Selected: ${event.name}`);
- *   if (event.name === 'delete') {
- *     // Handle delete action
- *   }
- * });
- * ```
+ * @category Components
+ */
+export interface MenuSelectEvent extends MenuEvent {
+  /** The selected menu item */
+  item: MenuItem;
+  
+  /** ID of the selected menu item */
+  itemId: string;
+  
+  /** Data associated with the menu item (if any) */
+  itemData?: any;
+}
+
+/**
+ * Menu component interface
  * 
- * @see {@link ../menu!default | createMenu} for creating menu instances
+ * @category Components
  */
 export interface MenuComponent {
-  /** 
-   * The root element of the menu
-   * Access to the underlying DOM element for direct manipulation if needed
-   */
+  /** The menu's root DOM element */
   element: HTMLElement;
   
-  /** 
-   * Shows the menu
-   * Makes the menu visible in the DOM
-   * @returns The menu component for method chaining
+  /**
+   * Opens the menu
+   * @param event - Optional event that triggered the open
+   * @returns The menu component for chaining
    */
-  show: () => MenuComponent;
+  open: (event?: Event) => MenuComponent;
   
-  /** 
-   * Hides the menu
-   * Makes the menu invisible in the DOM
-   * @returns The menu component for method chaining
+  /**
+   * Closes the menu
+   * @param event - Optional event that triggered the close
+   * @returns The menu component for chaining
    */
-  hide: () => MenuComponent;
+  close: (event?: Event) => MenuComponent;
   
-  /** 
-   * Checks if the menu is visible
-   * @returns True if the menu is currently visible
+  /**
+   * Toggles the menu's open state
+   * @param event - Optional event that triggered the toggle
+   * @returns The menu component for chaining
    */
-  isVisible: () => boolean;
+  toggle: (event?: Event) => MenuComponent;
   
-  /** 
-   * Positions the menu relative to a target
-   * Places the menu in relation to a target element with customizable alignment
-   * @param target - The element to position the menu against
-   * @param options - Configuration for how to align the menu
-   * @returns The menu component for method chaining
+  /**
+   * Checks if the menu is currently open
+   * @returns True if the menu is open
    */
-  position: (target: HTMLElement, options?: MenuPositionConfig) => MenuComponent;
+  isOpen: () => boolean;
   
-  /** 
-   * Adds a menu item
-   * Dynamically adds a new item to the menu
-   * @param config - Configuration for the new menu item
-   * @returns The menu component for method chaining
+  /**
+   * Updates the menu items
+   * @param items - New array of menu items and dividers
+   * @returns The menu component for chaining
    */
-  addItem: (config: MenuItemConfig) => MenuComponent;
+  setItems: (items: MenuContent[]) => MenuComponent;
   
-  /** 
-   * Removes a menu item by name
-   * Dynamically removes an item from the menu
-   * @param name - Name identifier of the item to remove
-   * @returns The menu component for method chaining
+  /**
+   * Gets the current menu items
+   * @returns Array of current menu items and dividers
    */
-  removeItem: (name: string) => MenuComponent;
+  getItems: () => MenuContent[];
   
-  /** 
-   * Gets all menu items
-   * @returns A Map of all items in the menu, indexed by item name
+  /**
+   * Updates the menu's anchor element
+   * @param anchor - New anchor element or selector
+   * @returns The menu component for chaining
    */
-  getItems: () => Map<string, MenuItemData>;
+  setAnchor: (anchor: HTMLElement | string) => MenuComponent;
   
-  /** 
-   * Adds event listener
-   * Subscribes to menu events like 'select', 'open', etc.
-   * @param event - The event name to listen for
-   * @param handler - Callback function to execute when the event occurs
-   * @returns The menu component for method chaining
+  /**
+   * Gets the current anchor element
+   * @returns Current anchor element
    */
-  on: (event: string, handler: Function) => MenuComponent;
+  getAnchor: () => HTMLElement;
   
-  /** 
-   * Removes event listener
-   * Unsubscribes from menu events
-   * @param event - The event name to stop listening for
-   * @param handler - The handler function to remove
-   * @returns The menu component for method chaining
+  /**
+   * Updates the menu's placement
+   * @param placement - New placement value
+   * @returns The menu component for chaining
    */
-  off: (event: string, handler: Function) => MenuComponent;
+  setPlacement: (placement: MenuPlacement) => MenuComponent;
   
-  /** 
-   * Destroys the menu component and cleans up resources
-   * Removes event listeners and DOM elements to prevent memory leaks
-   * @returns The menu component for method chaining
+  /**
+   * Gets the current menu placement
+   * @returns Current placement
    */
-  destroy: () => MenuComponent;
-}
-
-/**
- * Base component interface
- * 
- * Internal interface representing the base structure for menu components
- * before the public API is applied.
- * 
- * @internal
- * @category Components
- */
-export interface BaseComponent {
-  /** The root DOM element */
-  element: HTMLElement;
-  
-  /** Method to emit events */
-  emit?: (event: string, data: any) => void;
+  getPlacement: () => MenuPlacement;
   
-  /** Method to subscribe to events */
-  on?: (event: string, handler: Function) => any;
-  
-  /** Method to unsubscribe from events */
-  off?: (event: string, handler: Function) => any;
-  
-  /** Method to show the component */
-  show?: () => any;
-  
-  /** Method to hide the component */
-  hide?: () => any;
-  
-  /** Method to check visibility */
-  isVisible?: () => boolean;
-  
-  /** Method to position relative to target */
-  position?: (target: HTMLElement, options?: MenuPositionConfig) => any;
-  
-  /** Method to add an item */
-  addItem?: (config: MenuItemConfig) => any;
-  
-  /** Method to remove an item */
-  removeItem?: (name: string) => any;
-  
-  /** Method to get all items */
-  getItems?: () => Map<string, MenuItemData>;
-  
-  /** Method to close submenus */
-  closeSubmenus?: () => any;
-  
-  /** Method to refresh hover handlers */
-  refreshHoverHandlers?: () => any;
+  /**
+   * Adds an event listener to the menu
+   * @param event - Event name ('open', 'close', 'select')
+   * @param handler - Event handler function
+   * @returns The menu component for chaining
+   */
+  on: <T extends keyof MenuEvents>(event: T, handler: MenuEvents[T]) => MenuComponent;
   
-  /** Lifecycle methods container */
-  lifecycle?: {
-    destroy: () => void;
-  };
+  /**
+   * Removes an event listener from the menu
+   * @param event - Event name
+   * @param handler - Event handler function
+   * @returns The menu component for chaining
+   */
+  off: <T extends keyof MenuEvents>(event: T, handler: MenuEvents[T]) => MenuComponent;
   
-  /** Allow for additional properties */
-  [key: string]: any;
+  /**
+   * Destroys the menu component and cleans up resources
+   */
+  destroy: () => void;
 }
 
 /**
- * API options interface
+ * Menu events interface for type-checking
  * 
- * Internal interface used when applying the API to a component.
- * 
- * @internal
  * @category Components
+ * @internal
  */
-export interface ApiOptions {
-  /** Lifecycle methods to include */
-  lifecycle: {
-    destroy: () => void;
-  };
+export interface MenuEvents {
+  'open': (event: MenuEvent) => void;
+  'close': (event: MenuEvent) => void;
+  'select': (event: MenuSelectEvent) => void;
 }