@abstraks-dev/ui-library 1.0.1

package/dist/utils/utils/menuUtils.js

@@ -0,0 +1,651 @@
+/**
+ * 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
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+/**
+ * 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
+ */
+export const useSideMenuState = ({
+	initialOpen = false,
+	closeOnEscape = true,
+	closeOnBackdrop = true,
+	trapFocus = true,
+	onOpen = null,
+	onClose = null,
+} = {}) => {
+	const [isOpen, setIsOpen] = useState(initialOpen);
+	const [previousFocus, setPreviousFocus] = useState(null);
+	const menuRef = useRef(null);
+	const triggerRef = useRef(null);
+
+	const openMenu = 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 = 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 = useCallback(() => {
+		if (isOpen) {
+			closeMenu();
+		} else {
+			openMenu();
+		}
+	}, [isOpen, openMenu, closeMenu]);
+
+	// Handle escape key
+	const handleEscapeKey = useCallback(
+		(event) => {
+			if (closeOnEscape && event.key === 'Escape' && isOpen) {
+				event.preventDefault();
+				event.stopPropagation();
+				closeMenu();
+			}
+		},
+		[closeOnEscape, isOpen, closeMenu]
+	);
+
+	// Handle backdrop click
+	const handleBackdropClick = useCallback(
+		(event) => {
+			if (closeOnBackdrop && isOpen) {
+				event.preventDefault();
+				closeMenu();
+			}
+		},
+		[closeOnBackdrop, isOpen, closeMenu]
+	);
+
+	// Focus trap functionality
+	const handleKeyDown = 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
+	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
+ */
+export const useMenuAnnouncements = ({ announceStateChanges = true } = {}) => {
+	const [announcement, setAnnouncement] = useState('');
+	const liveRegionRef = useRef(null);
+
+	const announce = 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 = useCallback(
+		(menuTitle = 'Menu') => {
+			announce(`${menuTitle} opened`);
+		},
+		[announce]
+	);
+
+	const announceMenuClosed = useCallback(
+		(menuTitle = 'Menu') => {
+			announce(`${menuTitle} closed`);
+		},
+		[announce]
+	);
+
+	// Cleanup
+	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
+ */
+export const 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
+ */
+export const 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
+ */
+export const 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
+ */
+export const 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
+ */
+export const 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,
+};
+
+export default {
+	useSideMenuState,
+	useMenuAnnouncements,
+	menuTestingUtils,
+	menuConfigurations,
+	menuPerformanceUtils,
+	scrollLockUtils,
+	menuSelectors,
+};