mtrl 0.2.9 → 0.3.1

package/CLAUDE.md

@@ -0,0 +1,33 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Development Commands
+- Build: `bun run build`
+- Dev server: `bun run dev`
+- Tests: `bun test`
+- Single test: `bun test test/components/button.test.ts`
+- Watch tests: `bun test --watch`
+- Test with UI: `bun test --watch --ui`
+- Test coverage: `bun test --coverage`
+- Docs: `bun run docs` (uses TypeDoc)
+
+## Code Conventions
+- Factory pattern: Use `createComponent` naming for component creators
+- Functional composition with pipe pattern
+- Follow BEM-style CSS naming: `mtrl-component__element--modifier`
+- Use TypeDoc-compatible comments for documentation
+- Use TypeScript with strict typing where possible
+- Error handling: Try/catch blocks for component creation
+- Import order: core modules first, then utility functions, local imports last
+- Components follow a standard structure in their directories (api.ts, config.ts, etc.)
+- Use ES6+ features with full browser compatibility
+
+## Test Conventions
+- Tests live in `test/components/` with `.test.ts` extension
+- Use JSDOM for DOM manipulation in tests
+- Create mock implementations to avoid circular dependencies
+- Test structure follows `describe/test` pattern
+- Test component creation, options, events, and state changes
+- Use `import type` to avoid circular dependencies in TypeScript tests
+- Test directory structure mirrors src directory structure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrl",
-  "version": "0.2.9",
+  "version": "0.3.1",
   "description": "A functional TypeScript/JavaScript component library with composable architecture based on Material Design 3",
   "author": "floor",
   "license": "MIT License",
@@ -42,6 +42,8 @@
     "url": "https://github.com/floor/mtrl.git"
   },
   "devDependencies": {
+    "@types/jsdom": "^21.1.7",
+    "jsdom": "^26.0.0",
     "sass": "^1.85.1",
     "typedoc": "^0.27.9"
   }

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/index.ts

@@ -4,5 +4,8 @@ export {
   NavigationConfig,
   NavigationComponent,
   NavItemConfig,
-  NavGroupConfig
+  NavGroupConfig,
+  NAV_VARIANTS,
+  NAV_POSITIONS,
+  NAV_BEHAVIORS
 } from './types'

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

@@ -0,0 +1,302 @@
+// src/components/navigation/system/core.ts
+
+import { NavigationSystemState, NavigationSystemConfig, NavigationItem } from './types';
+import { isMobileDevice } from '../../../core/utils/mobile';
+import createNavigation from '../navigation';
+
+/**
+ * Update drawer content for a specific section WITHOUT changing visibility
+ * 
+ * @param state - System state
+ * @param sectionId - Section ID to display
+ * @param showDrawer - Function to show the drawer
+ * @param hideDrawer - Function to hide the drawer
+ */
+export const updateDrawerContent = (
+  state: NavigationSystemState,
+  sectionId: string,
+  showDrawer: () => void,
+  hideDrawer: () => void
+): void => {
+  if (!state.drawer || !sectionId || !state.items[sectionId]) {
+    return;
+  }
+  
+  // Get section items
+  const sectionData = state.items[sectionId];
+  const items = sectionData.items || [];
+  
+  // If no items, hide drawer and exit
+  if (items.length === 0) {
+    hideDrawer();
+    return;
+  }
+  
+  // Clear existing drawer items first using the API
+  const currentItems = state.drawer.getAllItems();
+  if (currentItems?.length > 0) {
+    currentItems.forEach((item: any) => {
+      state.drawer.removeItem(item.config.id);
+    });
+  }
+  
+  // Add new items to drawer through the API
+  items.forEach((item: NavigationItem) => {
+    state.drawer.addItem(item);
+  });
+  
+  // Show the drawer
+  showDrawer();
+};
+
+/**
+ * Creates the rail navigation component
+ * 
+ * @param state - System state
+ * @param config - System configuration
+ * @returns Rail navigation component
+ */
+export const createRailNavigation = (
+  state: NavigationSystemState,
+  config: any
+): any => {
+  // Build rail items from sections
+  const railItems = Object.keys(state.items || {}).map(sectionId => ({
+    id: sectionId,
+    label: state.items[sectionId]?.label || sectionId,
+    icon: state.items[sectionId]?.icon || '',
+    active: sectionId === state.activeSection
+  }));
+  
+  // Create the rail component
+  const rail = createNavigation({
+    variant: 'rail',
+    position: 'left',
+    showLabels: config.showLabelsOnRail,
+    items: railItems,
+    ...config.railOptions
+  });
+
+  document.body.appendChild(rail.element);
+  return rail;
+};
+
+/**
+ * Creates the drawer navigation component
+ * 
+ * @param state - System state
+ * @param config - System configuration
+ * @returns Drawer navigation component
+ */
+export const createDrawerNavigation = (
+  state: NavigationSystemState,
+  config: any
+): any => {
+  // Create the drawer component (initially empty)
+  const drawer = createNavigation({
+    variant: 'drawer',
+    position: 'left',
+    items: [], // Start empty
+    ...config.drawerOptions
+  });
+  
+  document.body.appendChild(drawer.element);
+
+  // Mark drawer with identifier
+  drawer.element.dataset.id = 'drawer';
+  
+  // IMPORTANT: Make drawer initially hidden unless explicitly expanded
+  if (!config.expanded) {
+    drawer.element.classList.add('mtrl-nav--hidden');
+    drawer.element.setAttribute('aria-hidden', 'true');
+  }
+  
+  return drawer;
+};
+
+/**
+ * Shows the drawer with mobile-specific behaviors
+ * 
+ * @param state - System state
+ * @param mobileConfig - Mobile configuration
+ */
+export const showDrawer = (
+  state: NavigationSystemState,
+  mobileConfig: any
+): void => {
+  if (!state.drawer) return;
+  
+  state.drawer.element.classList.remove('mtrl-nav--hidden');
+  state.drawer.element.setAttribute('aria-hidden', 'false');
+  
+  // Apply mobile-specific behaviors
+  if (state.isMobile) {
+    if (state.overlayElement) {
+      state.overlayElement.classList.add('active');
+      state.overlayElement.setAttribute('aria-hidden', 'false');
+    }
+    
+    // Lock body scroll if enabled
+    if (mobileConfig.lockBodyScroll) {
+      document.body.classList.add(mobileConfig.bodyLockClass);
+    }
+    
+    // Ensure close button is visible
+    if (state.closeButtonElement) {
+      state.closeButtonElement.style.display = 'flex';
+    }
+  }
+};
+
+/**
+ * Hides the drawer with mobile-specific behaviors
+ * 
+ * @param state - System state
+ * @param mobileConfig - Mobile configuration
+ */
+export const hideDrawer = (
+  state: NavigationSystemState,
+  mobileConfig: any
+): void => {
+  if (!state.drawer) return;
+  
+  state.drawer.element.classList.add('mtrl-nav--hidden');
+  state.drawer.element.setAttribute('aria-hidden', 'true');
+  
+  // Remove mobile-specific effects
+  if (state.overlayElement) {
+    state.overlayElement.classList.remove('active');
+    state.overlayElement.setAttribute('aria-hidden', 'true');
+  }
+  
+  // Unlock body scroll
+  if (mobileConfig.lockBodyScroll) {
+    document.body.classList.remove(mobileConfig.bodyLockClass);
+  }
+};
+
+/**
+ * Checks if drawer is visible
+ * 
+ * @param state - System state
+ * @returns true if drawer is visible
+ */
+export const isDrawerVisible = (
+  state: NavigationSystemState
+): boolean => {
+  if (!state.drawer) return false;
+  return !state.drawer.element.classList.contains('mtrl-nav--hidden');
+};
+
+/**
+ * Checks and updates the mobile state
+ * 
+ * @param state - System state
+ * @param mobileConfig - Mobile configuration
+ * @param setupMobileMode - Function to set up mobile mode
+ * @param teardownMobileMode - Function to tear down mobile mode
+ * @param systemApi - Reference to the public system API
+ */
+export const checkMobileState = (
+  state: NavigationSystemState,
+  mobileConfig: any,
+  setupMobileMode: () => void,
+  teardownMobileMode: () => void,
+  systemApi: any
+): void => {
+  const prevState = state.isMobile;
+  state.isMobile = window.innerWidth <= mobileConfig.breakpoint || isMobileDevice();
+  
+  // If state changed, adjust UI
+  if (prevState !== state.isMobile) {
+    if (state.isMobile) {
+      // Switched to mobile mode
+      setupMobileMode();
+    } else {
+      // Switched to desktop mode
+      teardownMobileMode();
+    }
+    
+    // Emit a view change event
+    if (systemApi.onViewChange) {
+      systemApi.onViewChange({
+        mobile: state.isMobile,
+        previousMobile: prevState,
+        width: window.innerWidth
+      });
+    }
+  }
+};
+
+/**
+ * Clean up resources when the system is destroyed
+ * 
+ * @param state - System state
+ */
+export const cleanupResources = (
+  state: NavigationSystemState
+): void => {
+  // Clean up overlay
+  if (state.overlayElement && state.overlayElement.parentNode) {
+    state.overlayElement.parentNode.removeChild(state.overlayElement);
+    state.overlayElement = null;
+  }
+  
+  // Destroy components
+  if (state.rail) {
+    state.rail.destroy();
+    state.rail = null;
+  }
+  
+  if (state.drawer) {
+    state.drawer.destroy();
+    state.drawer = null;
+  }
+  
+  // Reset state
+  state.activeSection = null;
+  state.activeSubsection = null;
+  state.mouseInDrawer = false;
+  state.mouseInRail = false;
+  state.processingChange = false;
+  state.isMobile = false;
+};
+
+/**
+ * Navigate to a specific section and subsection
+ * 
+ * @param state - System state
+ * @param section - Section ID
+ * @param subsection - Subsection ID (optional)
+ * @param silent - Whether to suppress change events
+ */
+export const navigateTo = (
+  state: NavigationSystemState,
+  section: string,
+  subsection?: string,
+  silent?: boolean
+): void => {
+  // Skip if section doesn't exist
+  if (!section || !state.items[section]) {
+    return;
+  }
+  
+  // Check if we're already on this section and subsection
+  if (state.activeSection === section && state.activeSubsection === subsection) {
+    return;
+  }
+  
+  // Update active section
+  state.activeSection = section;
+  
+  // Update rail if it exists
+  if (state.rail) {
+    state.rail.setActive(section, silent);
+  }
+  
+  // Update active subsection if specified
+  if (subsection && state.drawer) {
+    state.activeSubsection = subsection;
+    state.drawer.setActive(subsection, silent);
+  }
+};

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;
+};