mtrl 0.2.8 → 0.3.0

package/index.ts

@@ -1,6 +1,7 @@
 // index.js
 import {
   createLayout,
+  createStructure,
   createElement,
   createBadge,
   createBottomAppBar,
@@ -18,6 +19,7 @@ import {
   createList,
   createMenu,
   createNavigation,
+  createNavigationSystem,
   createProgress,
   createRadios,
   createSearch,
@@ -34,6 +36,7 @@ import {
 
 export {
   createLayout,
+  createStructure,
   createElement,
   createBadge,
   createBottomAppBar,
@@ -51,6 +54,7 @@ export {
   createList,
   createMenu,
   createNavigation,
+  createNavigationSystem,
   createProgress,
   createRadios,
   createSearch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrl",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "A functional TypeScript/JavaScript component library with composable architecture based on Material Design 3",
   "author": "floor",
   "license": "MIT License",

package/src/components/button/button.ts

@@ -16,13 +16,43 @@ import { ButtonConfig } from './types';
 import { createBaseConfig, getElementConfig, getApiConfig } from './config';
 
 /**
- * Creates a new Button component
- * @param {ButtonConfig} config - Button configuration object
- * @returns {ButtonComponent} Button component instance
+ * Creates a new Button component with the specified configuration.
+ * 
+ * The Button component is created using a functional composition pattern,
+ * applying various features through the pipe function. This approach allows
+ * for flexible and modular component construction.
+ * 
+ * @param {ButtonConfig} config - Configuration options for the button
+ *  This can include text content, icon options, variant styling, disabled state, 
+ *  and other button properties. See {@link ButtonConfig} for available options.
+ * 
+ * @returns {ButtonComponent} A fully configured button component instance with
+ *  all requested features applied. The returned component has methods for
+ *  manipulation, event handling, and lifecycle management.
+ * 
+ * @throws {Error} Throws an error if button creation fails for any reason
+ * 
+ * @example
+ * // Create a simple text button
+ * const textButton = createButton({ text: 'Click me' });
+ * 
+ * @example
+ * // Create a primary button with an icon
+ * const primaryButton = createButton({ 
+ *   text: 'Submit',
+ *   variant: 'primary',
+ *   icon: 'send'
+ * });
+ * 
+ * @example
+ * // Create a disabled button
+ * const disabledButton = createButton({
+ *   text: 'Not available',
+ *   disabled: true
+ * });
  */
 const createButton = (config: ButtonConfig = {}) => {
   const baseConfig = createBaseConfig(config);
-
   try {
     const button = pipe(
       createBase,
@@ -36,7 +66,6 @@ const createButton = (config: ButtonConfig = {}) => {
       withLifecycle(),
       comp => withAPI(getApiConfig(comp))(comp)
     )(baseConfig);
-
     return button;
   } catch (error) {
     console.error('Button creation error:', error);

package/src/components/navigation/api.ts

@@ -1,107 +1,142 @@
-// src/components/button/api.ts
-import { ButtonComponent } from './types';
-
-interface ApiOptions {
-  disabled: {
-    enable: () => void;
-    disable: () => void;
-  };
-  lifecycle: {
-    destroy: () => void;
-  };
-}
-
-interface ComponentWithElements {
-  element: HTMLElement;
-  text: {
-    setText: (content: string) => any;
-    getText: () => string;
-    getElement: () => HTMLElement | null;
-  };
-  icon: {
-    setIcon: (html: string) => any;
-    getIcon: () => string;
-    getElement: () => HTMLElement | null;
-  };
-  getClass: (name: string) => string;
-}
+// src/components/navigation/api.ts
+import { NavigationComponent, NavItemConfig, NavItemData, BaseComponent, ApiOptions } from './types';
 
 /**
- * Enhances a button component with API methods
+ * Enhances a component with navigation-specific API methods
  * @param {ApiOptions} options - API configuration options
  * @returns {Function} Higher-order function that adds API methods to component
- * @internal This is an internal utility for the Button component
  */
-export const withAPI = ({ disabled, lifecycle }: ApiOptions) => 
-  (component: ComponentWithElements): ButtonComponent => ({
-    ...component as any,
-    element: component.element as HTMLButtonElement,
+export const withAPI = (options: ApiOptions) => 
+  (component: BaseComponent): NavigationComponent => {
     
-    getValue: () => component.element.value,
-    
-    setValue(value: string) {
-      component.element.value = value;
-      return this;
-    },
-    
-    enable() {
-      disabled.enable();
-      return this;
-    },
-    
-    disable() {
-      disabled.disable();
-      return this;
-    },
-    
-    setText(content: string) {
-      component.text.setText(content);
-      this.updateCircularStyle();
+    const navComponent = {
+      ...component,
+      element: component.element,
+      items: component.items || new Map(),
+      
+      // Basic item operations
+      addItem(config: NavItemConfig): NavigationComponent {
+        if (typeof component.addItem === 'function') {
+          component.addItem(config);
+        }
+        return this;
+      },
+      
+      removeItem(id: string): NavigationComponent {
+        if (typeof component.removeItem === 'function') {
+          component.removeItem(id);
+        }
+        return this;
+      },
+      
+      getItem(id: string): NavItemData | undefined {
+        if (typeof component.getItem === 'function') {
+          return component.getItem(id);
+        }
+        return this.items.get(id);
+      },
+      
+      getAllItems(): NavItemData[] {
+        if (typeof component.getAllItems === 'function') {
+          return component.getAllItems();
+        }
+        return Array.from(this.items.values());
+      },
+      
+      // Path and active item management
+      getActive(): NavItemData | null {
+        if (typeof component.getActive === 'function') {
+          return component.getActive();
+        }
+        return null;
+      },
+      
+      getItemPath(id: string): string[] {
+        if (typeof component.getItemPath === 'function') {
+          return component.getItemPath(id);
+        }
+        return [];
+      },
       
-      // If removing text from a button with an icon, ensure it has an accessible name
-      if (!content && component.icon.getElement()) {
-        if (!this.element.getAttribute('aria-label')) {
-          const className = this.element.className.split(' ')
-            .find(cls => !cls.startsWith(`${component.getClass('button')}`));
-          
-          if (className) {
-            this.element.setAttribute('aria-label', className);
+      setActive(id: string, silent): NavigationComponent {
+        // Use the controller if available for consistent handling
+        if (typeof component.handleItemClick === 'function') {
+          component.handleItemClick(id);
+        } else if (typeof component.setActive === 'function') {
+          component.setActive(id);
+        } else {
+          // Fallback if setActive is not available
+          const item = this.items.get(id);
+          if (item && item.element) {
+            // Emit a change event to propagate the state change
+            if (component.emit) {
+              component.emit('change', {
+                id,
+                item,
+                source: 'api'
+              });
+            }
           }
         }
-      }
+        return this;
+      },
       
-      return this;
-    },
-    
-    getText() {
-      return component.text.getText();
-    },
-    
-    setIcon(icon: string) {
-      component.icon.setIcon(icon);
-      this.updateCircularStyle();
-      return this;
-    },
-    
-    getIcon() {
-      return component.icon.getIcon();
-    },
-    
-    setAriaLabel(label: string) {
-      component.element.setAttribute('aria-label', label);
-      return this;
-    },
-    
-    destroy() {
-      lifecycle.destroy();
-    },
-    
-    updateCircularStyle() {
-      const hasText = component.text.getText();
-      if (!hasText && component.icon.getElement()) {
-        component.element.classList.add(`${component.getClass('button')}--circular`);
-      } else {
-        component.element.classList.remove(`${component.getClass('button')}--circular`);
+      // Navigation state management
+      enable(): NavigationComponent {
+        if (options.disabled.enable) {
+          options.disabled.enable();
+        }
+        return this;
+      },
+      
+      disable(): NavigationComponent {
+        if (options.disabled.disable) {
+          options.disabled.disable();
+        }
+        return this;
+      },
+      
+      expand(): NavigationComponent {
+        this.element.classList.remove(`${this.element.className.split(' ')[0]}--hidden`);
+        this.element.setAttribute('aria-hidden', 'false');
+        
+        if (component.emit) {
+          component.emit('expanded', { source: 'api' });
+        }
+        return this;
+      },
+      
+      collapse(): NavigationComponent {
+        this.element.classList.add(`${this.element.className.split(' ')[0]}--hidden`);
+        this.element.setAttribute('aria-hidden', 'true');
+        
+        if (component.emit) {
+          component.emit('collapsed', { source: 'api' });
+        }
+        return this;
+      },
+      
+      isExpanded(): boolean {
+        return !this.element.classList.contains(`${this.element.className.split(' ')[0]}--hidden`);
+      },
+      
+      toggle(): NavigationComponent {
+        return this.isExpanded() ? this.collapse() : this.expand();
+      },
+      // on: component.on,
+      // off: component.off,
+      // emit: component.emit,
+      
+      // Destruction
+      destroy(): void {
+        if (options.lifecycle.destroy) {
+          options.lifecycle.destroy();
+        }
       }
-    }
-  });
+    };
+    
+    // Return the enhanced component
+    return navComponent;
+  };
+
+export default withAPI;

package/src/components/navigation/features/controller.ts

@@ -0,0 +1,273 @@
+// src/components/navigation/features/controller.ts
+import { BaseComponent, NavClass, NavItemData } from '../types';
+
+/**
+ * Configuration interface for controller feature
+ */
+interface ControllerConfig {
+  /** Component prefix for class names */
+  prefix?: string;
+  
+  /** Debug mode flag */
+  debug?: boolean;
+  
+  /** Component name */
+  componentName?: string;
+  
+  /** Additional configuration options */
+  [key: string]: any;
+}
+
+/**
+ * Enhanced component with controller capabilities
+ */
+interface ControllerComponent extends BaseComponent {
+  /** Handler method for item click events */
+  handleItemClick: (id: string) => void;
+}
+
+/**
+ * Adds event delegation controller to a navigation component
+ * This centralizes event handling for all navigation items
+ * 
+ * @param {ControllerConfig} config - Controller configuration
+ * @returns {Function} Component enhancer function
+ */
+export const withController = (config: ControllerConfig) => (component: BaseComponent): ControllerComponent => {
+  const prefix = config.prefix || 'mtrl';
+  
+  /**
+   * Updates the active state for an item
+   * @param {HTMLElement} item - Item element to activate
+   * @param {boolean} active - Whether to make active or inactive
+   */
+  const updateItemState = (item: HTMLElement, active: boolean): void => {
+    // Safety check - ensure item exists
+    if (!item) return;
+    
+    // Determine the correct active attribute based on role
+    const role = item.getAttribute('role');
+    
+    if (active) {
+      item.classList.add(`${prefix}-${NavClass.ITEM}--active`);
+      
+      // Set appropriate attribute based on role
+      if (role === 'tab') {
+        item.setAttribute('aria-selected', 'true');
+        item.setAttribute('tabindex', '0');
+      } else if (!item.getAttribute('aria-haspopup')) {
+        // Use aria-current for navigation items that aren't expandable
+        item.setAttribute('aria-current', 'page');
+      }
+    } else {
+      item.classList.remove(`${prefix}-${NavClass.ITEM}--active`);
+      
+      // Remove appropriate attribute based on role
+      if (role === 'tab') {
+        item.setAttribute('aria-selected', 'false');
+        item.setAttribute('tabindex', '-1');
+      } else if (item.hasAttribute('aria-current')) {
+        item.removeAttribute('aria-current');
+      }
+    }
+  };
+  
+  /**
+   * Handle expandable item toggle
+   * @param {HTMLElement} item - Expandable item element
+   * @returns {boolean} Whether the item was expandable and handled
+   */
+  const handleExpandableItem = (item: HTMLElement): boolean => {
+    const isExpandable = item.getAttribute('aria-expanded') !== null;
+    if (!isExpandable) return false;
+    
+    // Toggle expanded state
+    const isExpanded = item.getAttribute('aria-expanded') === 'true';
+    item.setAttribute('aria-expanded', (!isExpanded).toString());
+    
+    // Find and toggle nested container - use flexible selectors
+    const container = item.closest(`.${prefix}-${NavClass.ITEM_CONTAINER}, .mtrl-nav-item-container`);
+    if (container) {
+      const nestedContainer = container.querySelector(
+        `.${prefix}-${NavClass.NESTED_CONTAINER}, .mtrl-nav-nested-container`
+      );
+      if (nestedContainer) {
+        nestedContainer.hidden = isExpanded;
+        
+        // Also toggle expand icon rotation if present
+        const expandIcon = item.querySelector(
+          `.${prefix}-${NavClass.EXPAND_ICON}, .mtrl-nav-expand-icon`
+        );
+        if (expandIcon && expandIcon.style) {
+          expandIcon.style.transform = isExpanded ? '' : 'rotate(90deg)';
+        }
+      }
+    }
+    
+    // For expandable items, we still emit a change event
+    const id = item.dataset.id;
+    if (id && component.emit) {
+      component.emit('expandToggle', {
+        id,
+        expanded: !isExpanded
+      });
+    }
+    
+    return true;
+  };
+  
+  // Create the enhanced component with handleItemClick method
+  const enhancedComponent: ControllerComponent = {
+    ...component,
+    
+    /**
+     * Handler method for item click events
+     * @param {string} id - ID of the clicked item
+     */
+    handleItemClick(id: string) {
+      if (!component.items) {
+        return;
+      }
+      
+      const itemData = component.items.get(id);
+      if (!itemData) {
+        return;
+      }
+      
+      // Find the currently active item by DOM query instead of relying on getActive
+      const activeElement = component.element.querySelector(`.${prefix}-${NavClass.ITEM}--active, .mtrl-nav-item--active`);
+      
+      // Check if this item is already active - prevent infinite loops
+      // if (activeElement && activeElement === itemData.element) {
+      //   return;
+      // }
+      
+      // Deactivate previous active item if found
+      if (activeElement) {
+        updateItemState(activeElement as HTMLElement, false);
+      }
+      
+      // Make sure itemData.element exists before updating
+      if (itemData.element) {
+        updateItemState(itemData.element, true);
+      }
+      
+      // Emit change event
+      if (component.emit) {
+        // Get the path to the item (for nested items)
+        const path = component.getItemPath ? component.getItemPath(id) : [];
+        
+        component.emit('change', {
+          id,
+          item: itemData,
+          previousItem: activeElement ? { 
+            element: activeElement as HTMLElement,
+            config: { id: activeElement.dataset.id } 
+          } : null,
+          path,
+          source: 'userAction'
+        });
+      }
+    }
+  };
+  
+  // Set up click event delegation for all navigation items
+  component.element.addEventListener('click', (event: Event) => {
+    const target = event.target as HTMLElement;
+    
+    // Use more flexible selectors that match actual DOM structure
+    const item = target.closest(`.${prefix}-${NavClass.ITEM}, .mtrl-nav-item`) as HTMLElement;
+    
+    if (!item) {
+      // Fallback to elements with data-id attribute
+      const itemByDataId = target.closest('[data-id]') as HTMLElement;
+      if (!itemByDataId) {
+        return;
+      }
+    }
+    
+    // Use the found item or fallback
+    const navItem = item || target.closest('[data-id]') as HTMLElement;
+    
+    if (navItem.hasAttribute('disabled') || navItem.getAttribute('aria-disabled') === 'true') {
+      return;
+    }
+    
+    // Get the ID from the data attribute
+    const id = navItem.dataset.id;
+    if (!id) {
+      return;
+    }
+    
+    // Handle expandable items first
+    if (handleExpandableItem(navItem)) {
+      return;
+    }
+    
+    // Let the enhanced component handle normal item activation
+    enhancedComponent.handleItemClick(id);
+  });
+  
+  // Add keyboard support for navigation
+  component.element.addEventListener('keydown', (event: KeyboardEvent) => {
+    // Only handle specific keys
+    if (!['Enter', ' ', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) {
+      return;
+    }
+    
+    const isVertical = ['rail', 'drawer'].includes(component.variant || '');
+    const isHorizontal = ['bar'].includes(component.variant || '');
+    
+    // Handle Enter/Space for activation
+    if (event.key === 'Enter' || event.key === ' ') {
+      const item = document.activeElement as HTMLElement;
+      if (item && item.classList.contains(`${prefix}-${NavClass.ITEM}`)) {
+        event.preventDefault();
+        
+        const id = item.dataset.id;
+        if (id) {
+          item.click(); // Trigger a click event for the item
+        }
+      }
+      return;
+    }
+    
+    // Get all focusable navigation items - use flexible selector
+    const items = Array.from(
+      component.element.querySelectorAll(
+        `.${prefix}-${NavClass.ITEM}:not([disabled]):not([aria-disabled="true"]), 
+         .mtrl-nav-item:not([disabled]):not([aria-disabled="true"])`
+      )
+    ) as HTMLElement[];
+    
+    if (items.length === 0) return;
+    
+    // Find the currently focused item
+    const focusedItem = document.activeElement as HTMLElement;
+    const focusedIndex = items.indexOf(focusedItem);
+    
+    // Handle navigation keys
+    let newIndex = -1;
+    
+    if ((isVertical && (event.key === 'ArrowDown' || event.key === 'ArrowRight')) || 
+        (isHorizontal && event.key === 'ArrowRight')) {
+      newIndex = focusedIndex < 0 ? 0 : (focusedIndex + 1) % items.length;
+    } else if ((isVertical && (event.key === 'ArrowUp' || event.key === 'ArrowLeft')) || 
+               (isHorizontal && event.key === 'ArrowLeft')) {
+      newIndex = focusedIndex < 0 ? items.length - 1 : (focusedIndex - 1 + items.length) % items.length;
+    } else if (event.key === 'Home') {
+      newIndex = 0;
+    } else if (event.key === 'End') {
+      newIndex = items.length - 1;
+    }
+    
+    if (newIndex >= 0) {
+      event.preventDefault();
+      items[newIndex].focus();
+    }
+  });
+  
+  return enhancedComponent;
+};
+
+export default withController;