mtrl 0.3.8 → 0.4.0

package/dist/components/menu/config.d.ts

@@ -0,0 +1,78 @@
+import { MenuConfig } from './types';
+/**
+ * Default configuration for the Menu component
+ * These values will be used when not explicitly specified by the user.
+ *
+ * @category Components
+ */
+export declare const defaultConfig: Partial<MenuConfig>;
+/**
+ * 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
+ * @category Components
+ * @internal
+ */
+export declare const createBaseConfig: (config: MenuConfig) => MenuConfig;
+/**
+ * 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
+ * @category Components
+ * @internal
+ */
+export declare const getElementConfig: (config: MenuConfig) => {
+    tag: string;
+    componentName: string;
+    attributes: Record<string, any>;
+    className: string[];
+    rawClass: string | string[];
+    html: string;
+    text: string;
+    forwardEvents: Record<string, boolean | ((component: any, event: Event) => boolean)>;
+    interactive: boolean;
+};
+/**
+ * Creates API configuration for the Menu component.
+ * This connects the core component features to the public API.
+ *
+ * @param {Object} component - Component with menu features
+ * @returns {Object} API configuration object
+ * @category Components
+ * @internal
+ */
+export declare const getApiConfig: (component: any) => {
+    menu: {
+        open: (event: any, interactionType: any) => any;
+        close: (event: any, restoreFocus: any, skipAnimation: any) => any;
+        toggle: (event: any, interactionType: any) => any;
+        isOpen: () => any;
+        setItems: (items: any) => any;
+        getItems: () => any;
+        setPosition: (position: any) => any;
+        getPosition: () => any;
+        setSelected: (itemId: any) => any;
+        getSelected: () => any;
+    };
+    opener: {
+        setOpener: (opener: any) => any;
+        getOpener: () => any;
+    };
+    submenu: {
+        hasOpenSubmenu: () => any;
+        closeAllSubmenus: () => any;
+    };
+    events: {
+        on: (event: any, handler: any) => any;
+        off: (event: any, handler: any) => any;
+    };
+    lifecycle: {
+        destroy: () => any;
+    };
+};
+export default defaultConfig;

package/dist/components/menu/constants.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Menu position options for alignment relative to opener element
+ */
+export declare const MENU_POSITION: {
+    /** Places menu below the opener, aligned to left edge */
+    readonly BOTTOM_START: "bottom-start";
+    /** Places menu below the opener, centered */
+    readonly BOTTOM: "bottom";
+    /** Places menu below the opener, aligned to right edge */
+    readonly BOTTOM_END: "bottom-end";
+    /** Places menu above the opener, aligned to left edge */
+    readonly TOP_START: "top-start";
+    /** Places menu above the opener, centered */
+    readonly TOP: "top";
+    /** Places menu above the opener, aligned to right edge */
+    readonly TOP_END: "top-end";
+    /** Places menu to the right of the opener, aligned to top edge */
+    readonly RIGHT_START: "right-start";
+    /** Places menu to the right of the opener, centered */
+    readonly RIGHT: "right";
+    /** Places menu to the right of the opener, aligned to bottom edge */
+    readonly RIGHT_END: "right-end";
+    /** Places menu to the left of the opener, aligned to top edge */
+    readonly LEFT_START: "left-start";
+    /** Places menu to the left of the opener, centered */
+    readonly LEFT: "left";
+    /** Places menu to the left of the opener, aligned to bottom edge */
+    readonly LEFT_END: "left-end";
+};
+/**
+ * Default configuration values for menus
+ */
+export declare const MENU_DEFAULTS: {
+    /** Default menu position */
+    readonly POSITION: "bottom-start";
+    /** Default offset from the opener (in pixels) */
+    readonly OFFSET: 0;
+    /** Close menu when an item is selected */
+    readonly CLOSE_ON_SELECT: true;
+    /** Close menu when clicking outside */
+    readonly CLOSE_ON_CLICK_OUTSIDE: true;
+    /** Close menu when escape key is pressed */
+    readonly CLOSE_ON_ESCAPE: true;
+    /** Open submenus on hover */
+    readonly OPEN_SUBMENU_ON_HOVER: true;
+    /** Automatically flip menu position to stay in viewport */
+    readonly AUTO_FLIP: true;
+};
+/**
+ * Interaction types for menu opening/closing
+ */
+export declare const MENU_INTERACTION_TYPES: {
+    /** Interaction via mouse or touch */
+    readonly MOUSE: "mouse";
+    /** Interaction via keyboard */
+    readonly KEYBOARD: "keyboard";
+};
+/**
+ * Menu item types
+ */
+export declare const MENU_ITEM_TYPES: {
+    /** Standard interactive menu item */
+    readonly ITEM: "item";
+    /** Non-interactive dividing line */
+    readonly DIVIDER: "divider";
+};
+/**
+ * Menu event names
+ */
+export declare const MENU_EVENTS: {
+    /** Fired when the menu is opened */
+    readonly OPEN: "open";
+    /** Fired when the menu is closed */
+    readonly CLOSE: "close";
+    /** Fired when a menu item is selected */
+    readonly SELECT: "select";
+};
+/**
+ * CSS classes for menu elements
+ */
+export declare const MENU_CLASSES: {
+    /** Menu container */
+    readonly CONTAINER: "menu";
+    /** Visible menu */
+    readonly VISIBLE: "menu--visible";
+    /** Menu inner container */
+    readonly INNER: "menu__inner";
+    /** Individual menu item */
+    readonly ITEM: "menu__item";
+    /** Disabled menu item */
+    readonly ITEM_DISABLED: "menu__item--disabled";
+    /** Selected menu item */
+    readonly ITEM_SELECTED: "menu__item--selected";
+    /** Menu item with submenu */
+    readonly ITEM_HAS_SUBMENU: "menu__item--has-submenu";
+    /** Divider */
+    readonly DIVIDER: "menu__divider";
+    /** Item icon */
+    readonly ITEM_ICON: "menu__item-icon";
+    /** Item text */
+    readonly ITEM_TEXT: "menu__item-text";
+    /** Item keyboard shortcut */
+    readonly ITEM_SHORTCUT: "menu__item-shortcut";
+    /** Submenu indicator */
+    readonly SUBMENU_INDICATOR: "menu__submenu-indicator";
+};

package/dist/components/menu/features/controller.d.ts

@@ -0,0 +1,10 @@
+import { MenuConfig } from '../types';
+/**
+ * Adds controller functionality to the menu component
+ * Manages state, rendering, positioning, and event handling
+ *
+ * @param config - Menu configuration
+ * @returns Component enhancer with menu controller functionality
+ */
+declare const withController: (config: MenuConfig) => (component: any) => any;
+export default withController;

package/dist/components/menu/features/index.d.ts

@@ -0,0 +1,6 @@
+import withController from './controller';
+import withOpener from './opener';
+import withPosition from './position';
+import withKeyboard from './keyboard';
+import withSubmenu from './submenu';
+export { withController, withOpener, withPosition, withKeyboard, withSubmenu };

package/dist/components/menu/features/keyboard.d.ts

@@ -0,0 +1,26 @@
+import { MenuItem } from '../types';
+/**
+ * Keyboard navigation handler for menus
+ * Manages focus management and keyboard interactions for accessibility
+ */
+export declare const createKeyboardNavigation: (component: any) => {
+    handleInitialFocus: (menuElement: HTMLElement, interactionType: "keyboard" | "mouse") => void;
+    handleMenuKeydown: (e: KeyboardEvent, state: any, actions: {
+        closeMenu: (event: Event, restoreFocus?: boolean) => void;
+        closeSubmenu: (level: number) => void;
+        findItemById: (id: string) => MenuItem | null;
+        handleSubmenuClick: (item: MenuItem, index: number, itemElement: HTMLElement) => void;
+        handleNestedSubmenuClick: (item: MenuItem, index: number, itemElement: HTMLElement) => void;
+    }) => void;
+    setupKeyboardHandlers: (menuElement: HTMLElement, state: any, actions: any) => void;
+    isTabNavigationActive: () => boolean;
+    getFocusableElements: () => HTMLElement[];
+};
+/**
+ * Adds keyboard navigation functionality to the menu component
+ *
+ * @param config - Menu configuration
+ * @returns Component enhancer with keyboard navigation functionality
+ */
+declare const withKeyboard: (config: any) => (component: any) => any;
+export default withKeyboard;

package/dist/components/menu/features/opener.d.ts

@@ -0,0 +1,10 @@
+import { MenuConfig } from '../types';
+/**
+ * Adds opener functionality to menu component
+ * Manages the relationship between menu and its opener element
+ *
+ * @param config - Menu configuration
+ * @returns Component enhancer with opener management functionality
+ */
+declare const withOpener: (config: MenuConfig) => (component: any) => any;
+export default withOpener;

package/dist/components/menu/features/position.d.ts

@@ -0,0 +1,18 @@
+import { MenuConfig } from '../types';
+/**
+ * Menu position helper
+ * Provides functions for positioning menus and submenus
+ */
+export declare const createPositioner: (component: any, config: MenuConfig) => {
+    positionMenu: (openerElement: HTMLElement) => void;
+    positionSubmenu: (submenuElement: HTMLElement, parentItemElement: HTMLElement, level?: number) => void;
+    positionElement: (menuElement: HTMLElement, openerElement: HTMLElement, preferredPosition: string, isSubmenu?: boolean) => void;
+};
+/**
+ * Adds positioning functionality to the menu component
+ *
+ * @param config - Menu configuration options
+ * @returns Component enhancer with positioning functionality
+ */
+declare const withPosition: (config: MenuConfig) => (component: any) => any;
+export default withPosition;

package/dist/components/menu/features/submenu.d.ts

@@ -0,0 +1,10 @@
+import { MenuConfig } from '../types';
+/**
+ * Adds submenu functionality to the menu component
+ * Manages creation, positioning, and interaction with nested submenus
+ *
+ * @param config - Menu configuration
+ * @returns Component enhancer with submenu functionality
+ */
+declare const withSubmenu: (config: MenuConfig) => (component: any) => any;
+export default withSubmenu;

package/{src/components/menu/index.ts → dist/components/menu/index.d.ts}

@@ -1,44 +1,28 @@
-// src/components/menu/index.ts
-
 /**
  * Menu component module
- * 
+ *
  * 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
  */
-
-// Export main component factory
 export { default } from './menu';
-
-// Export types and interfaces
-export type { 
-  MenuConfig, 
-  MenuComponent, 
-  MenuItem, 
-  MenuDivider,
-  MenuContent,
-  MenuEvent,
-  MenuSelectEvent,
-  MenuPosition
-} from './types';
-
+export type { MenuConfig, MenuComponent, MenuItem, MenuDivider, MenuContent, MenuEvent, MenuSelectEvent, MenuPosition } from './types';
 /**
  * Constants for menu position values - use these instead of string literals
  * for better code completion and type safety.
- * 
+ *
  * @example
  * import { createMenu, MENU_POSITION } from 'mtrl';
- * 
- * // Create a menu positioned at the bottom-right of its anchor
- * const menu = createMenu({ 
- *   anchor: '#dropdown-button',
+ *
+ * // Create a menu positioned at the bottom-right of its opener
+ * const menu = createMenu({
+ *   opener: '#dropdown-button',
  *   items: [...],
- *   position: MENU_POSITION.BOTTOM_END 
+ *   position: MENU_POSITION.BOTTOM_END
  * });
- * 
+ *
  * @category Components
  */
-export { MENU_POSITION } from './types';
+export { MENU_POSITION, MENU_DEFAULTS, MENU_INTERACTION_TYPES, MENU_ITEM_TYPES, MENU_EVENTS, MENU_CLASSES } from './constants';

package/dist/components/menu/menu.d.ts

@@ -0,0 +1,29 @@
+import { MenuConfig, MenuComponent } from './types';
+/**
+ * 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 opener 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 opener) is missing.
+ *
+ * @category Components
+ */
+declare const createMenu: (config: MenuConfig) => MenuComponent;
+export default createMenu;

package/dist/components/menu/types.d.ts

@@ -0,0 +1,338 @@
+/**
+ * Menu position options
+ * Controls where the menu will appear relative to its opener element
+ *
+ * @category Components
+ */
+export declare const MENU_POSITION: {
+    /** Places menu below the opener, aligned to left edge */
+    readonly BOTTOM_START: "bottom-start";
+    /** Places menu below the opener, centered */
+    readonly BOTTOM: "bottom";
+    /** Places menu below the opener, aligned to right edge */
+    readonly BOTTOM_END: "bottom-end";
+    /** Places menu above the opener, aligned to left edge */
+    readonly TOP_START: "top-start";
+    /** Places menu above the opener, centered */
+    readonly TOP: "top";
+    /** Places menu above the opener, aligned to right edge */
+    readonly TOP_END: "top-end";
+    /** Places menu to the right of the opener, aligned to top edge */
+    readonly RIGHT_START: "right-start";
+    /** Places menu to the right of the opener, centered */
+    readonly RIGHT: "right";
+    /** Places menu to the right of the opener, aligned to bottom edge */
+    readonly RIGHT_END: "right-end";
+    /** Places menu to the left of the opener, aligned to top edge */
+    readonly LEFT_START: "left-start";
+    /** Places menu to the left of the opener, centered */
+    readonly LEFT: "left";
+    /** Places menu to the left of the opener, aligned to bottom edge */
+    readonly LEFT_END: "left-end";
+};
+/**
+ * Position options for the menu
+ *
+ * @category Components
+ */
+export type MenuPosition = typeof MENU_POSITION[keyof typeof MENU_POSITION];
+/**
+ * Configuration interface for a menu item
+ *
+ * @category Components
+ */
+export interface MenuItem {
+    /**
+     * Unique ID for the menu item
+     * Required for accessibility and event handling
+     */
+    id: string;
+    /**
+     * Display text for the menu item
+     */
+    text: string;
+    /**
+     * Optional icon to display before the text
+     * Accepts HTML string (typically SVG)
+     */
+    icon?: string;
+    /**
+     * Optional keyboard shortcut hint to display
+     * Shown at the end of the menu item
+     */
+    shortcut?: string;
+    /**
+     * Whether the menu item is disabled
+     * Disabled items cannot be clicked but remain visible
+     */
+    disabled?: boolean;
+    /**
+     * Whether this item has a submenu
+     * If true, the item will show an indicator and can open a nested menu
+     */
+    hasSubmenu?: boolean;
+    /**
+     * Optional array of submenu items
+     * Only used when hasSubmenu is true
+     */
+    submenu?: MenuItem[];
+    /**
+     * Additional data to associate with the menu item
+     * This can be used for custom behavior in click handlers
+     */
+    data?: any;
+}
+/**
+ * Menu item type for dividers
+ *
+ * @category Components
+ */
+export interface MenuDivider {
+    /**
+     * Type must be 'divider' to differentiate from regular menu items
+     */
+    type: 'divider';
+    /**
+     * Optional ID for the divider (for accessibility)
+     */
+    id?: string;
+}
+/**
+ * Combined type for menu content items (regular items or dividers)
+ *
+ * @category Components
+ */
+export type MenuContent = MenuItem | MenuDivider;
+/**
+ * Configuration interface for the Menu component
+ *
+ * @category Components
+ */
+export interface MenuConfig {
+    /**
+     * Element to which the menu will be openered
+     * Can be an HTML element, a CSS selector string, or a component with an element property
+     */
+    opener: HTMLElement | string | {
+        element: HTMLElement;
+    };
+    /**
+     * Array of menu items and dividers to display
+     */
+    items: MenuContent[];
+    /**
+     * Position of the menu relative to the opener
+     * @default 'bottom-start'
+     */
+    position?: MenuPosition;
+    /**
+     * Whether the menu should close when an item is clicked
+     * @default true
+     */
+    closeOnSelect?: boolean;
+    /**
+     * Whether the menu should close when the user clicks outside
+     * @default true
+     */
+    closeOnClickOutside?: boolean;
+    /**
+     * Whether the menu should close when the escape key is pressed
+     * @default true
+     */
+    closeOnEscape?: boolean;
+    /**
+     * Whether submenus should open on hover
+     * @default true
+     */
+    openSubmenuOnHover?: boolean;
+    /**
+     * Optional width for the menu (in CSS units)
+     * If not provided, menu will size to its content
+     */
+    width?: string;
+    /**
+     * Optional maximum height for the menu (in CSS units)
+     * If content exceeds this height, the menu will scroll
+     */
+    maxHeight?: string;
+    /**
+     * Optional offset from the opener (in pixels)
+     * @default 8
+     */
+    offset?: number;
+    /**
+     * Whether the menu should automatically flip position 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 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 event interface
+ *
+ * @category Components
+ */
+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
+ *
+ * @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
+ *
+ * @category Components
+ */
+export interface MenuComponent {
+    /** The menu's root DOM element */
+    element: HTMLElement;
+    /**
+     * Opens the menu
+     * @param event - Optional event that triggered the open
+     * @param interactionType - The type of interaction that triggered the open ('mouse' or 'keyboard')
+     * @returns The menu component for chaining
+     */
+    open: (event?: Event, interactionType?: 'mouse' | 'keyboard') => MenuComponent;
+    /**
+     * Closes the menu
+     * @param event - Optional event that triggered the close
+     * @returns The menu component for chaining
+     */
+    close: (event?: Event) => MenuComponent;
+    /**
+     * Toggles the menu's open state
+     * @param event - Optional event that triggered the toggle
+     * @returns The menu component for chaining
+     */
+    toggle: (event?: Event) => MenuComponent;
+    /**
+     * Checks if the menu is currently open
+     * @returns True if the menu is open
+     */
+    isOpen: () => boolean;
+    /**
+     * Updates the menu items
+     * @param items - New array of menu items and dividers
+     * @returns The menu component for chaining
+     */
+    setItems: (items: MenuContent[]) => MenuComponent;
+    /**
+     * Gets the current menu items
+     * @returns Array of current menu items and dividers
+     */
+    getItems: () => MenuContent[];
+    /**
+     * Updates the menu's opener element
+     * @param opener - New opener element or selector
+     * @returns The menu component for chaining
+     */
+    setOpener: (opener: HTMLElement | string) => MenuComponent;
+    /**
+     * Gets the current opener element
+     * @returns Current opener element
+     */
+    getOpener: () => HTMLElement;
+    /**
+     * Updates the menu's position
+     * @param position - New position value
+     * @returns The menu component for chaining
+     */
+    setPosition: (position: MenuPosition) => MenuComponent;
+    /**
+     * Gets the current menu position
+     * @returns Current position
+     */
+    getPosition: () => MenuPosition;
+    /**
+     * Sets the selected menu item
+     * @param itemId - ID of the menu item to mark as selected
+     * @returns The menu component for chaining
+     */
+    setSelected: (itemId: string) => MenuComponent;
+    /**
+     * Gets the currently selected menu item's ID
+     * @returns ID of the selected menu item or null if none is selected
+     */
+    getSelected: () => string | null;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Destroys the menu component and cleans up resources
+     */
+    destroy: () => void;
+}
+/**
+ * Menu events interface for type-checking
+ *
+ * @category Components
+ * @internal
+ */
+export interface MenuEvents {
+    'open': (event: MenuEvent) => void;
+    'close': (event: MenuEvent) => void;
+    'select': (event: MenuSelectEvent) => void;
+}