@abstraks-dev/ui-library 1.0.1

package/dist/utils/menuUtils.js

@@ -0,0 +1,575 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useSideMenuState = exports.useMenuAnnouncements = exports.scrollLockUtils = exports.menuTestingUtils = exports.menuSelectors = exports.menuPerformanceUtils = exports.menuConfigurations = exports.default = void 0;
+var _react = require("react");
+/**
+ * Side Menu Component Utilities
+ * Provides helper functions and hooks for SideMenu component functionality
+ *
+ * ## Scroll Lock Implementation
+ * This file includes a robust body scroll lock system that:
+ * - Uses CSS classes instead of direct style manipulation
+ * - Handles multiple overlays with reference counting
+ * - Prevents layout shift by compensating for scrollbar width
+ * - Supports iOS devices with proper position handling
+ * - Provides cleanup mechanisms to prevent memory leaks
+ */
+
+/**
+ * Constants for menu utilities
+ * Centralized selectors and attributes to improve maintainability and prevent duplication
+ */
+// Selector for all focusable elements within menus
+// Used for focus trapping and keyboard navigation
+const FOCUSABLE_ELEMENTS_SELECTOR = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+
+// Selectors for menu elements and triggers
+// Used by accessibility testing and validation functions
+const MENU_DIALOG_SELECTOR = '[role="dialog"]';
+const MENU_TRIGGER_SELECTOR = '[aria-controls]';
+const SIDE_MENU_CLASS_SELECTOR = '.side-menu';
+
+// ARIA attributes
+// Used for consistent attribute handling
+const ARIA_CONTROLS_ATTRIBUTE = 'aria-controls';
+
+/**
+ * Body Scroll Lock Manager
+ * Manages body scroll locking with reference counting to handle multiple overlays
+ */
+class ScrollLockManager {
+  constructor() {
+    this.lockCount = 0;
+    this.originalOverflow = null;
+    this.originalPaddingRight = null;
+  }
+
+  /**
+   * Lock body scroll and prevent layout shift from scrollbar removal
+   */
+  lock() {
+    if (this.lockCount === 0) {
+      // Store original values
+      this.originalOverflow = document.body.style.overflow || '';
+      this.originalPaddingRight = document.body.style.paddingRight || '';
+
+      // Calculate scrollbar width to prevent layout shift
+      const scrollBarWidth = window.innerWidth - document.documentElement.clientWidth;
+
+      // Apply scroll lock with proper padding compensation
+      document.body.style.overflow = 'hidden';
+      if (scrollBarWidth > 0) {
+        document.body.style.paddingRight = `${scrollBarWidth}px`;
+      }
+
+      // Add CSS class for additional styling
+      document.body.classList.add('scroll-locked');
+    }
+    this.lockCount++;
+  }
+
+  /**
+   * Unlock body scroll when no more overlays need it locked
+   */
+  unlock() {
+    this.lockCount = Math.max(0, this.lockCount - 1);
+    if (this.lockCount === 0) {
+      // Restore original values
+      document.body.style.overflow = this.originalOverflow;
+      document.body.style.paddingRight = this.originalPaddingRight;
+      document.body.classList.remove('scroll-locked');
+
+      // Clear stored values
+      this.originalOverflow = null;
+      this.originalPaddingRight = null;
+    }
+  }
+
+  /**
+   * Force unlock (useful for cleanup)
+   */
+  forceUnlock() {
+    this.lockCount = 0;
+    this.unlock();
+  }
+
+  /**
+   * Get current lock count
+   */
+  getLockCount() {
+    return this.lockCount;
+  }
+}
+
+// Global scroll lock manager instance
+const scrollLockManager = new ScrollLockManager();
+
+/**
+ * Hook for managing side menu state with accessibility features
+ * @param {Object} options - Configuration options
+ * @param {boolean} options.initialOpen - Initial menu state
+ * @param {boolean} options.closeOnEscape - Close menu on Escape key
+ * @param {boolean} options.closeOnBackdrop - Close menu on backdrop click
+ * @param {boolean} options.trapFocus - Trap focus within menu
+ * @param {Function} options.onOpen - Callback when menu opens
+ * @param {Function} options.onClose - Callback when menu closes
+ * @returns {Object} Menu state and handlers
+ */
+const useSideMenuState = ({
+  initialOpen = false,
+  closeOnEscape = true,
+  closeOnBackdrop = true,
+  trapFocus = true,
+  onOpen = null,
+  onClose = null
+} = {}) => {
+  const [isOpen, setIsOpen] = (0, _react.useState)(initialOpen);
+  const [previousFocus, setPreviousFocus] = (0, _react.useState)(null);
+  const menuRef = (0, _react.useRef)(null);
+  const triggerRef = (0, _react.useRef)(null);
+  const openMenu = (0, _react.useCallback)(() => {
+    // Store currently focused element
+    setPreviousFocus(document.activeElement);
+    setIsOpen(true);
+    if (onOpen) onOpen();
+
+    // Focus menu after a short delay to ensure it's rendered
+    setTimeout(() => {
+      if (menuRef.current) {
+        menuRef.current.focus();
+      }
+    }, 100);
+  }, [onOpen]);
+  const closeMenu = (0, _react.useCallback)(() => {
+    setIsOpen(false);
+    if (onClose) onClose();
+
+    // Restore focus to trigger element
+    setTimeout(() => {
+      if (previousFocus && previousFocus.focus) {
+        previousFocus.focus();
+      } else if (triggerRef.current) {
+        triggerRef.current.focus();
+      }
+    }, 100);
+  }, [onClose, previousFocus]);
+  const toggleMenu = (0, _react.useCallback)(() => {
+    if (isOpen) {
+      closeMenu();
+    } else {
+      openMenu();
+    }
+  }, [isOpen, openMenu, closeMenu]);
+
+  // Handle escape key
+  const handleEscapeKey = (0, _react.useCallback)(event => {
+    if (closeOnEscape && event.key === 'Escape' && isOpen) {
+      event.preventDefault();
+      event.stopPropagation();
+      closeMenu();
+    }
+  }, [closeOnEscape, isOpen, closeMenu]);
+
+  // Handle backdrop click
+  const handleBackdropClick = (0, _react.useCallback)(event => {
+    if (closeOnBackdrop && isOpen) {
+      event.preventDefault();
+      closeMenu();
+    }
+  }, [closeOnBackdrop, isOpen, closeMenu]);
+
+  // Focus trap functionality
+  const handleKeyDown = (0, _react.useCallback)(event => {
+    if (!trapFocus || !isOpen || !menuRef.current) return;
+    const focusableElements = menuRef.current.querySelectorAll(FOCUSABLE_ELEMENTS_SELECTOR);
+    const firstFocusable = focusableElements[0];
+    const lastFocusable = focusableElements[focusableElements.length - 1];
+    if (event.key === 'Tab') {
+      if (event.shiftKey) {
+        // Shift + Tab
+        if (document.activeElement === firstFocusable) {
+          event.preventDefault();
+          lastFocusable.focus();
+        }
+      } else {
+        // Tab
+        if (document.activeElement === lastFocusable) {
+          event.preventDefault();
+          firstFocusable.focus();
+        }
+      }
+    }
+  }, [trapFocus, isOpen]);
+
+  // Attach global event listeners
+  (0, _react.useEffect)(() => {
+    if (isOpen) {
+      document.addEventListener('keydown', handleEscapeKey);
+      document.addEventListener('keydown', handleKeyDown);
+
+      // Lock body scroll when menu is open
+      scrollLockManager.lock();
+    } else {
+      document.removeEventListener('keydown', handleEscapeKey);
+      document.removeEventListener('keydown', handleKeyDown);
+
+      // Unlock body scroll
+      scrollLockManager.unlock();
+    }
+    return () => {
+      document.removeEventListener('keydown', handleEscapeKey);
+      document.removeEventListener('keydown', handleKeyDown);
+      scrollLockManager.unlock();
+    };
+  }, [isOpen, handleEscapeKey, handleKeyDown]);
+  return {
+    isOpen,
+    openMenu,
+    closeMenu,
+    toggleMenu,
+    handleBackdropClick,
+    menuRef,
+    triggerRef
+  };
+};
+
+/**
+ * Hook for managing menu accessibility announcements
+ * @param {Object} options - Configuration options
+ * @returns {Object} Accessibility utilities
+ */
+exports.useSideMenuState = useSideMenuState;
+const useMenuAnnouncements = ({
+  announceStateChanges = true
+} = {}) => {
+  const [announcement, setAnnouncement] = (0, _react.useState)('');
+  const liveRegionRef = (0, _react.useRef)(null);
+  const announce = (0, _react.useCallback)(message => {
+    if (!announceStateChanges) return;
+    setAnnouncement(message);
+
+    // Create live region if needed
+    if (!liveRegionRef.current) {
+      const region = document.createElement('div');
+      region.setAttribute('aria-live', 'polite');
+      region.setAttribute('aria-atomic', 'true');
+      region.className = 'sr-only';
+      region.style.cssText = `
+				position: absolute !important;
+				width: 1px !important;
+				height: 1px !important;
+				padding: 0 !important;
+				margin: -1px !important;
+				overflow: hidden !important;
+				clip: rect(0, 0, 0, 0) !important;
+				white-space: nowrap !important;
+				border: 0 !important;
+			`;
+      document.body.appendChild(region);
+      liveRegionRef.current = region;
+    }
+
+    // Announce message
+    liveRegionRef.current.textContent = message;
+
+    // Clear after announcement
+    setTimeout(() => {
+      if (liveRegionRef.current) {
+        liveRegionRef.current.textContent = '';
+      }
+    }, 1000);
+  }, [announceStateChanges]);
+  const announceMenuOpened = (0, _react.useCallback)((menuTitle = 'Menu') => {
+    announce(`${menuTitle} opened`);
+  }, [announce]);
+  const announceMenuClosed = (0, _react.useCallback)((menuTitle = 'Menu') => {
+    announce(`${menuTitle} closed`);
+  }, [announce]);
+
+  // Cleanup
+  (0, _react.useEffect)(() => {
+    return () => {
+      if (liveRegionRef.current && document.body.contains(liveRegionRef.current)) {
+        document.body.removeChild(liveRegionRef.current);
+      }
+    };
+  }, []);
+  return {
+    announcement,
+    announce,
+    announceMenuOpened,
+    announceMenuClosed
+  };
+};
+
+/**
+ * Accessibility testing utilities for side menus
+ */
+exports.useMenuAnnouncements = useMenuAnnouncements;
+const menuTestingUtils = exports.menuTestingUtils = {
+  /**
+   * Validates menu accessibility attributes
+   */
+  validateMenuAccessibility() {
+    const menus = document.querySelectorAll(MENU_DIALOG_SELECTOR);
+    const results = [];
+    menus.forEach(menu => {
+      const hasAriaModal = menu.getAttribute('aria-modal') === 'true';
+      const hasAriaLabel = !!menu.getAttribute('aria-label');
+      const hasAriaLabelledBy = !!menu.getAttribute('aria-labelledby');
+      const hasTrigger = !!document.querySelector(`[${ARIA_CONTROLS_ATTRIBUTE}="${menu.id}"]`);
+      results.push({
+        menuId: menu.id,
+        className: menu.className,
+        hasAriaModal,
+        hasAriaLabel,
+        hasAriaLabelledBy,
+        hasTrigger,
+        isAccessible: hasAriaModal && (hasAriaLabel || hasAriaLabelledBy) && hasTrigger
+      });
+    });
+    return results;
+  },
+  /**
+   * Tests trigger button accessibility
+   */
+  validateTriggerAccessibility() {
+    const triggers = document.querySelectorAll(MENU_TRIGGER_SELECTOR);
+    const results = [];
+    triggers.forEach(trigger => {
+      const controlsId = trigger.getAttribute(ARIA_CONTROLS_ATTRIBUTE);
+      const hasExpandedState = trigger.hasAttribute('aria-expanded');
+      const hasAriaLabel = !!trigger.getAttribute('aria-label');
+      const controlsElement = document.getElementById(controlsId);
+      const isButton = trigger.tagName === 'BUTTON' || trigger.getAttribute('role') === 'button';
+      results.push({
+        element: trigger.tagName,
+        controlsId,
+        hasExpandedState,
+        hasAriaLabel,
+        controlsElement: !!controlsElement,
+        isButton,
+        tabIndex: trigger.tabIndex,
+        isAccessible: hasExpandedState && (hasAriaLabel || trigger.textContent.trim()) && isButton
+      });
+    });
+    return results;
+  },
+  /**
+   * Tests focus management
+   */
+  validateFocusManagement() {
+    const menus = document.querySelectorAll(MENU_DIALOG_SELECTOR);
+    const results = [];
+    menus.forEach(menu => {
+      const isVisible = menu.offsetParent !== null;
+      const isFocusable = menu.tabIndex >= 0;
+      const focusableChildren = menu.querySelectorAll(FOCUSABLE_ELEMENTS_SELECTOR);
+      results.push({
+        menuId: menu.id,
+        isVisible,
+        isFocusable,
+        focusableChildrenCount: focusableChildren.length,
+        hasFocusableChildren: focusableChildren.length > 0,
+        isAccessible: !isVisible || isFocusable && focusableChildren.length > 0
+      });
+    });
+    return results;
+  },
+  /**
+   * Simulates keyboard navigation
+   */
+  async simulateKeyboardNavigation() {
+    const triggers = document.querySelectorAll(MENU_TRIGGER_SELECTOR);
+    const results = [];
+    for (let trigger of triggers) {
+      // Test Enter key
+      const enterEvent = new KeyboardEvent('keydown', {
+        key: 'Enter'
+      });
+      trigger.dispatchEvent(enterEvent);
+      await new Promise(resolve => setTimeout(resolve, 100));
+      const controlsId = trigger.getAttribute(ARIA_CONTROLS_ATTRIBUTE);
+      const menu = document.getElementById(controlsId);
+      const menuVisible = menu && menu.offsetParent !== null;
+
+      // Test Escape key if menu is visible
+      let escapeWorks = false;
+      if (menuVisible) {
+        const escapeEvent = new KeyboardEvent('keydown', {
+          key: 'Escape'
+        });
+        document.dispatchEvent(escapeEvent);
+        await new Promise(resolve => setTimeout(resolve, 100));
+        escapeWorks = menu.offsetParent === null;
+      }
+      results.push({
+        triggerText: trigger.textContent?.trim(),
+        enterOpensMenu: menuVisible,
+        escapeClosesMenu: escapeWorks,
+        isAccessible: menuVisible && (escapeWorks || !menuVisible)
+      });
+
+      // Small delay for real-world simulation
+      await new Promise(resolve => setTimeout(resolve, 50));
+    }
+    return results;
+  },
+  /**
+   * Tests high contrast compatibility
+   */
+  validateHighContrast() {
+    const menus = document.querySelectorAll(SIDE_MENU_CLASS_SELECTOR);
+    const results = [];
+    menus.forEach(menu => {
+      const overlay = menu.querySelector('.overlay');
+      const menuPanel = menu.querySelector('.menu');
+      const overlayStyle = overlay ? window.getComputedStyle(overlay) : null;
+      const panelStyle = menuPanel ? window.getComputedStyle(menuPanel) : null;
+      results.push({
+        menuClass: menu.className,
+        overlayBackgroundColor: overlayStyle?.backgroundColor,
+        panelBackgroundColor: panelStyle?.backgroundColor,
+        panelBorder: panelStyle?.border,
+        hasContrast: overlayStyle?.backgroundColor !== 'rgba(0, 0, 0, 0)' && panelStyle?.backgroundColor !== 'transparent'
+      });
+    });
+    return results;
+  },
+  /**
+   * Comprehensive menu audit
+   */
+  auditMenu() {
+    return {
+      accessibility: this.validateMenuAccessibility(),
+      triggers: this.validateTriggerAccessibility(),
+      focusManagement: this.validateFocusManagement(),
+      highContrast: this.validateHighContrast(),
+      timestamp: new Date().toISOString()
+    };
+  }
+};
+
+/**
+ * Common menu configurations for different use cases
+ */
+const menuConfigurations = exports.menuConfigurations = {
+  navigation: {
+    ariaLabel: 'Main navigation menu',
+    closeOnBackdrop: true,
+    closeOnEscape: true,
+    trapFocus: true
+  },
+  settings: {
+    ariaLabel: 'Settings menu',
+    closeOnBackdrop: true,
+    closeOnEscape: true,
+    trapFocus: true
+  },
+  notifications: {
+    ariaLabel: 'Notifications panel',
+    closeOnBackdrop: true,
+    closeOnEscape: true,
+    trapFocus: false // Allow background interaction
+  },
+  quickActions: {
+    ariaLabel: 'Quick actions menu',
+    closeOnBackdrop: true,
+    closeOnEscape: true,
+    trapFocus: true
+  }
+};
+
+/**
+ * Performance utilities for menus
+ */
+const menuPerformanceUtils = exports.menuPerformanceUtils = {
+  /**
+   * Measures menu animation performance
+   */
+  measureAnimationPerformance: menuElement => {
+    let startTime = performance.now();
+    let frameCount = 0;
+    const measureFrame = () => {
+      frameCount++;
+      const currentTime = performance.now();
+      const elapsedTime = currentTime - startTime;
+      if (elapsedTime >= 1000) {
+        const fps = Math.round(frameCount * 1000 / elapsedTime);
+        console.log(`Menu animation FPS: ${fps}`);
+        frameCount = 0;
+        startTime = currentTime;
+      }
+      if (menuElement && menuElement.offsetParent) {
+        requestAnimationFrame(measureFrame);
+      }
+    };
+    requestAnimationFrame(measureFrame);
+  },
+  /**
+   * Optimizes menu rendering
+   */
+  optimizeMenuRendering: menuElement => {
+    if (!menuElement) return;
+
+    // Use GPU acceleration for smooth animations
+    menuElement.style.transform = menuElement.style.transform || 'translateZ(0)';
+    menuElement.style.backfaceVisibility = 'hidden';
+    menuElement.style.perspective = '1000px';
+  }
+};
+
+/**
+ * Scroll Lock Utilities
+ * Public API for managing body scroll locking
+ */
+const scrollLockUtils = exports.scrollLockUtils = {
+  /**
+   * Lock body scroll
+   * Use this to prevent body scrolling when overlays are open
+   */
+  lock: () => scrollLockManager.lock(),
+  /**
+   * Unlock body scroll
+   * Call this when closing overlays
+   */
+  unlock: () => scrollLockManager.unlock(),
+  /**
+   * Force unlock all scroll locks
+   * Useful for cleanup or error recovery
+   */
+  forceUnlock: () => scrollLockManager.forceUnlock(),
+  /**
+   * Get current lock count
+   * Useful for debugging multiple overlay scenarios
+   */
+  getLockCount: () => scrollLockManager.getLockCount(),
+  /**
+   * Check if body is currently scroll locked
+   */
+  isLocked: () => scrollLockManager.getLockCount() > 0
+};
+
+/**
+ * Menu Selector Constants
+ * Exported for use by other components that need consistent menu selectors
+ */
+const menuSelectors = exports.menuSelectors = {
+  FOCUSABLE_ELEMENTS: FOCUSABLE_ELEMENTS_SELECTOR,
+  MENU_DIALOG: MENU_DIALOG_SELECTOR,
+  MENU_TRIGGER: MENU_TRIGGER_SELECTOR,
+  SIDE_MENU_CLASS: SIDE_MENU_CLASS_SELECTOR,
+  ARIA_CONTROLS_ATTR: ARIA_CONTROLS_ATTRIBUTE
+};
+var _default = exports.default = {
+  useSideMenuState,
+  useMenuAnnouncements,
+  menuTestingUtils,
+  menuConfigurations,
+  menuPerformanceUtils,
+  scrollLockUtils,
+  menuSelectors
+};