mtrl 0.2.8 → 0.3.0

package/src/components/navigation/system/events.ts

@@ -0,0 +1,240 @@
+// src/components/navigation/system/events.ts
+
+import { NavigationSystemState } from './types';
+import { NavigationItem, NavigationSection } from './types';
+
+/**
+ * Registers rail navigation event handlers
+ * 
+ * @param state - System state
+ * @param config - System configuration
+ * @param updateDrawerContent - Function to update drawer content
+ * @param showDrawer - Function to show the drawer
+ * @param hideDrawer - Function to hide the drawer
+ * @param systemApi - Reference to the public system API
+ */
+export const registerRailEvents = (
+  state: NavigationSystemState,
+  config: any,
+  updateDrawerContent: (sectionId: string) => void,
+  showDrawer: () => void,
+  hideDrawer: () => void,
+  systemApi: any
+): void => {
+  const rail = state.rail;
+  if (!rail) return;
+
+  // Register for change events - will listen for when rail items are clicked
+  rail.on('change', (event: any) => {
+    // Extract ID from event data
+    const id = event?.id;
+    
+    if (!id || state.processingChange) {
+      return;
+    }
+    
+    // Check if this is a user action
+    const isUserAction = event?.source === 'userAction';
+    
+    // Set processing flag to prevent loops
+    state.processingChange = true;
+    
+    // Update active section
+    state.activeSection = id;
+    
+    // Handle internally first - update drawer content
+    updateDrawerContent(id);
+    
+    // Then notify external handlers
+    if (systemApi.onSectionChange && isUserAction) {
+      systemApi.onSectionChange(id, { source: isUserAction ? 'userClick' : 'programmatic' });
+    }
+    
+    // Clear the processing flag after a delay
+    setTimeout(() => {
+      state.processingChange = false;
+    }, 50);
+  });
+
+  rail.on('mouseover', (event: any) => {
+    const id = event?.id;
+    
+    // Set rail mouse state
+    state.mouseInRail = true;
+    
+    // Clear any existing hover timer
+    clearTimeout(state.hoverTimer as number);
+    state.hoverTimer = null;
+    
+    // Only schedule drawer operations if there's an ID
+    if (id) {
+      // Check if this section has items
+      if (state.items[id]?.items?.length > 0) {
+        // Has items - schedule drawer opening
+        state.hoverTimer = window.setTimeout(() => {
+          updateDrawerContent(id);
+        }, config.hoverDelay) as unknown as number;
+      } else {
+        // No items - hide drawer after a delay to prevent flickering
+        state.closeTimer = window.setTimeout(() => {
+          // Only hide if we're still in the rail but not in the drawer
+          if (state.mouseInRail && !state.mouseInDrawer) {
+            hideDrawer();
+          }
+        }, config.hoverDelay) as unknown as number;
+      }
+    }
+  });
+
+  rail.on('mouseenter', () => {
+    state.mouseInRail = true;
+    
+    // Clear any pending drawer close timer when entering rail
+    clearTimeout(state.closeTimer as number);
+    state.closeTimer = null;
+  });
+
+  rail.on('mouseleave', () => {
+    state.mouseInRail = false;
+    
+    // Clear any existing hover timer
+    clearTimeout(state.hoverTimer as number);
+    state.hoverTimer = null;
+    
+    // Only set timer to hide drawer if we're not in drawer either
+    if (!state.mouseInDrawer) {
+      state.closeTimer = window.setTimeout(() => {
+        // Double-check we're still not in rail or drawer before hiding
+        if (!state.mouseInRail && !state.mouseInDrawer) {
+          hideDrawer();
+        }
+      }, config.closeDelay) as unknown as number;
+    }
+  });
+};
+
+/**
+ * Registers drawer navigation event handlers
+ * 
+ * @param state - System state
+ * @param config - System configuration
+ * @param hideDrawer - Function to hide the drawer
+ * @param systemApi - Reference to the public system API
+ */
+export const registerDrawerEvents = (
+  state: NavigationSystemState,
+  config: any,
+  hideDrawer: () => void,
+  systemApi: any
+): void => {
+  const drawer = state.drawer;
+  if (!drawer) return;
+
+  // Use the component's native event system
+  if (typeof drawer.on === 'function') {
+    // Handle item selection
+    drawer.on('change', (event: any) => {
+      const id = event.id;
+      
+      state.activeSubsection = id;
+      
+      // If configuration specifies to hide drawer on click, do so
+      if (config.hideDrawerOnClick) {
+        hideDrawer();
+      }
+      
+      // Emit item selection event
+      if (systemApi.onItemSelect) {
+        systemApi.onItemSelect(event);
+      }
+    });
+    
+    // Handle mouseenter/mouseleave for drawer
+    drawer.on('mouseenter', () => {
+      state.mouseInDrawer = true;
+      
+      // Clear any hover and close timers
+      clearTimeout(state.hoverTimer as number);
+      clearTimeout(state.closeTimer as number);
+      state.hoverTimer = null;
+      state.closeTimer = null;
+    });
+    
+    drawer.on('mouseleave', () => {
+      state.mouseInDrawer = false;
+      
+      // Only set timer to hide drawer if we're not in rail
+      if (!state.mouseInRail) {
+        state.closeTimer = window.setTimeout(() => {
+          // Double-check we're still not in drawer or rail before hiding
+          if (!state.mouseInDrawer && !state.mouseInRail) {
+            hideDrawer();
+          }
+        }, config.closeDelay) as unknown as number;
+      }
+    });
+  }
+};
+
+/**
+ * Sets up window resize and orientation change handling
+ * 
+ * @param state - System state 
+ * @param checkMobileState - Function to check and update mobile state
+ */
+export const setupResponsiveHandling = (
+  state: NavigationSystemState,
+  checkMobileState: () => void
+): void => {
+  // Setup responsive behavior
+  if (window.ResizeObserver) {
+    // Use ResizeObserver for better performance
+    state.resizeObserver = new ResizeObserver(() => {
+      checkMobileState();
+    });
+    state.resizeObserver.observe(document.body);
+  } else {
+    // Fallback to window resize event
+    window.addEventListener('resize', checkMobileState);
+  }
+  
+  // Listen for orientation changes on mobile
+  window.addEventListener('orientationchange', () => {
+    // Small delay to ensure dimensions have updated
+    setTimeout(checkMobileState, 100);
+  });
+};
+
+/**
+ * Cleans up all event handlers and resources
+ * 
+ * @param state - System state
+ * @param checkMobileState - Function reference to remove event handlers
+ */
+export const cleanupEvents = (
+  state: NavigationSystemState,
+  checkMobileState: () => void
+): void => {
+  // Clean up resize observer
+  if (state.resizeObserver) {
+    state.resizeObserver.disconnect();
+    state.resizeObserver = null;
+  } else {
+    window.removeEventListener('resize', checkMobileState);
+  }
+  
+  // Remove orientation change listener
+  window.removeEventListener('orientationchange', checkMobileState);
+  
+  // Remove outside click handler
+  if (state.outsideClickHandler) {
+    const eventType = ('ontouchend' in window) ? 'touchend' : 'click';
+    document.removeEventListener(eventType, state.outsideClickHandler);
+  }
+  
+  // Clear timers
+  clearTimeout(state.hoverTimer as number);
+  clearTimeout(state.closeTimer as number);
+  state.hoverTimer = null;
+  state.closeTimer = null;
+};

package/src/components/navigation/system/index.ts

@@ -0,0 +1,184 @@
+// src/components/navigation/system/index.ts
+
+import { 
+  NavigationSystemConfig, 
+  NavigationSystemState, 
+  NavigationSystem,
+  ViewChangeEvent
+} from './types';
+
+import { 
+  createInitialState, 
+  createConfig, 
+  createMobileConfig 
+} from './state';
+
+import {
+  createRailNavigation,
+  createDrawerNavigation,
+  updateDrawerContent,
+  showDrawer as showDrawerCore,
+  hideDrawer as hideDrawerCore,
+  isDrawerVisible as isDrawerVisibleCore,
+  checkMobileState as checkMobileStateCore,
+  cleanupResources,
+  navigateTo as navigateToCore
+} from './core';
+
+import {
+  registerRailEvents,
+  registerDrawerEvents,
+  setupResponsiveHandling,
+  cleanupEvents
+} from './events';
+
+import {
+  setupMobileMode as setupMobileModeCore,
+  teardownMobileMode
+} from './mobile';
+
+/**
+ * Creates a complete navigation system with synchronized rail and drawer components
+ * 
+ * @param options - System configuration options
+ * @returns Navigation system API
+ */
+export const createNavigationSystem = (options: NavigationSystemConfig = {}): NavigationSystem => {
+  // Initialize state and configuration
+  const state = createInitialState(options);
+  const config = createConfig(options);
+  const mobileConfig = createMobileConfig(options);
+
+  // Create system API object with placeholders
+  const system: NavigationSystem = {
+    initialize: () => system,
+    cleanup: () => {},
+    navigateTo: () => {},
+    getRail: () => state.rail,
+    getDrawer: () => state.drawer,
+    getActiveSection: () => state.activeSection,
+    getActiveSubsection: () => state.activeSubsection,
+    showDrawer: () => {},
+    hideDrawer: () => {},
+    isDrawerVisible: () => false,
+    configure: () => system,
+    setProcessingChange: () => {},
+    isProcessingChange: () => false,
+    isMobile: () => state.isMobile,
+    checkMobileState: () => {},
+    onSectionChange: undefined,
+    onItemSelect: undefined,
+    onViewChange: undefined
+  };
+
+  // Implementation functions that use the state
+  const showDrawer = () => showDrawerCore(state, mobileConfig);
+  const hideDrawer = () => hideDrawerCore(state, mobileConfig);
+  const isDrawerVisible = () => isDrawerVisibleCore(state);
+  
+  const updateDrawerContentWrapper = (sectionId: string) => {
+    updateDrawerContent(state, sectionId, showDrawer, hideDrawer);
+  };
+
+  const setupMobileMode = () => {
+    setupMobileModeCore(
+      state, 
+      mobileConfig, 
+      hideDrawer, 
+      isDrawerVisible,
+      showDrawer
+    );
+  };
+
+  const checkMobileState = () => {
+    checkMobileStateCore(
+      state, 
+      mobileConfig, 
+      setupMobileMode, 
+      () => teardownMobileMode(state, mobileConfig), 
+      system
+    );
+  };
+
+  const navigateTo = (section: string, subsection?: string, silent?: boolean) => {
+    navigateToCore(state, section, subsection, silent);
+  };
+
+  // Implementation of the initialize method
+  const initialize = (): NavigationSystem => {
+    // Create rail component
+    state.rail = createRailNavigation(state, config);
+    
+    // Create drawer component
+    state.drawer = createDrawerNavigation(state, config);
+    
+    // Register event handlers
+    registerRailEvents(state, config, updateDrawerContentWrapper, showDrawer, hideDrawer, system);
+    registerDrawerEvents(state, config, hideDrawer, system);
+    
+    // Set up responsive behavior
+    setupResponsiveHandling(state, checkMobileState);
+    
+    // Set active section if specified
+    if (options.activeSection && state.items[options.activeSection]) {
+      state.activeSection = options.activeSection;
+      
+      if (state.rail) {
+        state.rail.setActive(options.activeSection);
+      }
+      
+      // Update drawer content without showing it
+      updateDrawerContentWrapper(options.activeSection);
+      
+      // Only show drawer if expanded is explicitly true
+      if (options.expanded === true) {
+        showDrawer();
+      } else {
+        // Explicitly ensure drawer is hidden
+        hideDrawer();
+      }
+    }
+    
+    // Check initial mobile state
+    checkMobileState();
+    
+    return system;
+  };
+
+  // Implementation of the cleanup method
+  const cleanup = (): void => {
+    cleanupEvents(state, checkMobileState);
+    cleanupResources(state);
+  };
+
+  // Configure method implementation
+  const configure = (newConfig: Partial<NavigationSystemConfig>): NavigationSystem => {
+    Object.assign(options, newConfig);
+    Object.assign(config, createConfig({...options, ...newConfig}));
+    Object.assign(mobileConfig, createMobileConfig({...options, ...newConfig}));
+    return system;
+  };
+
+  // Assign implementations to system object
+  system.initialize = initialize;
+  system.cleanup = cleanup;
+  system.navigateTo = navigateTo;
+  system.showDrawer = showDrawer;
+  system.hideDrawer = hideDrawer;
+  system.isDrawerVisible = isDrawerVisible;
+  system.configure = configure;
+  system.setProcessingChange = (isProcessing: boolean) => {
+    state.processingChange = isProcessing;
+  };
+  system.isProcessingChange = () => state.processingChange;
+  system.isMobile = () => state.isMobile;
+  system.checkMobileState = checkMobileState;
+
+  // Return the uninitialized system
+  return system;
+};
+
+export default createNavigationSystem;
+
+// Re-export types for external use
+export * from './types';

package/src/components/navigation/system/mobile.ts

@@ -0,0 +1,278 @@
+// src/components/navigation/system/mobile.ts
+
+import { NavigationSystemState } from './types';
+import { 
+  hasTouchSupport, 
+  normalizeEvent,
+  TOUCH_CONFIG,
+  TOUCH_TARGETS 
+} from '../../../core/utils/mobile';
+
+/**
+ * Creates and appends overlay element for mobile
+ *
+ * @param state - System state
+ * @param mobileConfig - Mobile configuration
+ * @param hideDrawer - Function to hide the drawer
+ * @returns Overlay element
+ */
+export const createOverlay = (
+  state: NavigationSystemState, 
+  mobileConfig: any, 
+  hideDrawer: () => void
+): HTMLElement => {
+  if (state.overlayElement) return state.overlayElement;
+  
+  state.overlayElement = document.createElement('div');
+  state.overlayElement.className = mobileConfig.overlayClass;
+  state.overlayElement.setAttribute('aria-hidden', 'true');
+  document.body.appendChild(state.overlayElement);
+  
+  state.overlayElement.addEventListener('click', (event) => {
+    if (event.target === state.overlayElement) {
+      hideDrawer();
+    }
+  });
+  
+  return state.overlayElement;
+};
+
+/**
+ * Creates and adds close button to the drawer
+ *
+ * @param state - System state
+ * @param mobileConfig - Mobile configuration
+ * @param hideDrawer - Function to hide the drawer
+ * @returns Close button element
+ */
+export const createCloseButton = (
+  state: NavigationSystemState, 
+  mobileConfig: any, 
+  hideDrawer: () => void
+): HTMLElement | null => {
+  if (!state.drawer || state.closeButtonElement) return null;
+  
+  state.closeButtonElement = document.createElement('button');
+  state.closeButtonElement.className = mobileConfig.closeButtonClass;
+  state.closeButtonElement.setAttribute('aria-label', 'Close navigation');
+  state.closeButtonElement.innerHTML = `
+    <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+      <line x1="18" y1="6" x2="6" y2="18"></line>
+      <line x1="6" y1="6" x2="18" y2="18"></line>
+    </svg>
+  `;
+  
+  // Handle click event
+  state.closeButtonElement.addEventListener('click', () => {
+    hideDrawer();
+  });
+  
+  // Apply touch-friendly styles if needed
+  if (hasTouchSupport() && mobileConfig.optimizeForTouch) {
+    state.closeButtonElement.style.minWidth = `${TOUCH_TARGETS.COMFORTABLE}px`;
+    state.closeButtonElement.style.minHeight = `${TOUCH_TARGETS.COMFORTABLE}px`;
+    
+    // Add touch feedback
+    state.closeButtonElement.addEventListener('touchstart', () => {
+      state.closeButtonElement.classList.add('active');
+    }, { passive: true });
+    
+    state.closeButtonElement.addEventListener('touchend', () => {
+      setTimeout(() => {
+        state.closeButtonElement.classList.remove('active');
+      }, TOUCH_CONFIG.FEEDBACK_DURATION);
+    }, { passive: true });
+  }
+  
+  state.drawer.element.appendChild(state.closeButtonElement);
+  return state.closeButtonElement;
+};
+
+/**
+ * Sets up mobile mode features
+ *
+ * @param state - System state
+ * @param mobileConfig - Mobile configuration
+ * @param hideDrawer - Function to hide the drawer
+ * @param isDrawerVisible - Function to check if drawer is visible
+ */
+export const setupMobileMode = (
+  state: NavigationSystemState, 
+  mobileConfig: any, 
+  hideDrawer: () => void,
+  isDrawerVisible: () => boolean
+): void => {
+  const drawer = state.drawer;
+  const rail = state.rail;
+  
+  if (!drawer || !rail) return;
+  
+  // Create mobile UI elements
+  createOverlay(state, mobileConfig, hideDrawer);
+  createCloseButton(state, mobileConfig, hideDrawer);
+  
+  // Setup outside click handling
+  setupOutsideClickHandling(state, mobileConfig, hideDrawer, isDrawerVisible);
+  
+  // Setup touch gestures if enabled
+  if (mobileConfig.enableSwipeGestures && hasTouchSupport()) {
+    setupTouchGestures(state, hideDrawer, isDrawerVisible);
+  }
+  
+  // Hide drawer initially in mobile mode
+  hideDrawer();
+};
+
+/**
+ * Sets up outside click handling for mobile
+ *
+ * @param state - System state
+ * @param mobileConfig - Mobile configuration
+ * @param hideDrawer - Function to hide the drawer
+ * @param isDrawerVisible - Function to check if drawer is visible
+ */
+export const setupOutsideClickHandling = (
+  state: NavigationSystemState, 
+  mobileConfig: any, 
+  hideDrawer: () => void,
+  isDrawerVisible: () => boolean
+): void => {
+  if (!mobileConfig.hideOnClickOutside) return;
+  
+  // Only set up once
+  if (state.outsideClickHandlerSet) return;
+  state.outsideClickHandlerSet = true;
+  
+  // Use either click or touchend event depending on device capability
+  const eventType = hasTouchSupport() ? 'touchend' : 'click';
+  
+  // The handler function
+  const handleOutsideClick = (event: Event) => {
+    if (!state.isMobile || !isDrawerVisible()) return;
+    
+    const normalizedEvent = normalizeEvent(event);
+    const target = normalizedEvent.target as HTMLElement;
+    
+    // Don't close if clicking on drawer, rail, or excluded elements
+    if (state.drawer.element.contains(target) || 
+        state.rail.element.contains(target)) {
+      return;
+    }
+    
+    // Close drawer - it's an outside click/touch
+    hideDrawer();
+  };
+  
+  // Store handler for cleanup
+  state.outsideClickHandler = handleOutsideClick;
+  
+  // Add listener
+  document.addEventListener(eventType, handleOutsideClick,
+    hasTouchSupport() ? { passive: true } : false);
+};
+
+/**
+ * Sets up touch gestures for mobile
+ *
+ * @param state - System state
+ * @param hideDrawer - Function to hide the drawer
+ * @param isDrawerVisible - Function to check if drawer is visible
+ */
+export const setupTouchGestures = (
+  state: NavigationSystemState, 
+  hideDrawer: () => void,
+  isDrawerVisible: () => boolean,
+  showDrawer?: () => void
+): void => {
+  const drawer = state.drawer;
+  const rail = state.rail;
+  
+  if (!drawer || !rail) return;
+  
+  let touchStartX = 0;
+  let touchStartY = 0;
+  
+  // Rail swipe right to open drawer
+  rail.element.addEventListener('touchstart', (event: TouchEvent) => {
+    const touch = event.touches[0];
+    touchStartX = touch.clientX;
+    touchStartY = touch.clientY;
+  }, { passive: true });
+  
+  rail.element.addEventListener('touchmove', (event: TouchEvent) => {
+    if (!state.isMobile || isDrawerVisible() || !showDrawer) return;
+    
+    const touch = event.touches[0];
+    const deltaX = touch.clientX - touchStartX;
+    const deltaY = touch.clientY - touchStartY;
+    
+    // Only consider horizontal swipes
+    if (Math.abs(deltaX) > Math.abs(deltaY) && 
+        deltaX > TOUCH_CONFIG.SWIPE_THRESHOLD) {
+      showDrawer();
+    }
+  }, { passive: true });
+  
+  // Drawer swipe left to close
+  drawer.element.addEventListener('touchstart', (event: TouchEvent) => {
+    const touch = event.touches[0];
+    touchStartX = touch.clientX;
+    touchStartY = touch.clientY;
+  }, { passive: true });
+  
+  // Use touchmove with transform for visual feedback
+  drawer.element.addEventListener('touchmove', (event: TouchEvent) => {
+    if (!state.isMobile || !isDrawerVisible()) return;
+    
+    const touch = event.touches[0];
+    const deltaX = touch.clientX - touchStartX;
+    
+    // Only apply transform for leftward swipes
+    if (deltaX < 0) {
+      // Apply transform with resistance
+      drawer.element.style.transform = `translateX(${deltaX / 2}px)`;
+      
+      // Close if threshold reached
+      if (deltaX < -TOUCH_CONFIG.SWIPE_THRESHOLD) {
+        hideDrawer();
+      }
+    }
+  }, { passive: true });
+  
+  // Reset transforms when touch ends
+  drawer.element.addEventListener('touchend', () => {
+    if (drawer.element.style.transform) {
+      drawer.element.style.transition = 'transform 0.2s ease';
+      drawer.element.style.transform = '';
+      
+      setTimeout(() => {
+        drawer.element.style.transition = '';
+      }, 200);
+    }
+  }, { passive: true });
+};
+
+/**
+ * Tears down mobile-specific features
+ *
+ * @param state - System state
+ * @param mobileConfig - Mobile configuration
+ */
+export const teardownMobileMode = (
+  state: NavigationSystemState, 
+  mobileConfig: any
+): void => {
+  // Hide overlay
+  if (state.overlayElement) {
+    state.overlayElement.classList.remove('active');
+    state.overlayElement.setAttribute('aria-hidden', 'true');
+  }
+  
+  // Hide close button
+  if (state.closeButtonElement) {
+    state.closeButtonElement.style.display = 'none';
+  }
+  
+  // Remove body scroll lock if applied
+  document.body.classList.remove(mobileConfig.bodyLockClass);
+};