@abstraks-dev/ui-library 1.0.1

package/dist/utils/utils/loaderUtils.js

@@ -0,0 +1,436 @@
+/**
+ * Loader Component Utilities
+ * Provides helper functions and hooks for Loader component functionality
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+/**
+ * Hook for managing loading states with automatic timeout
+ * @param {Object} options - Configuration options
+ * @param {boolean} options.initialLoading - Initial loading state
+ * @param {number} options.minLoadTime - Minimum loading time in ms
+ * @param {number} options.maxLoadTime - Maximum loading time before timeout
+ * @param {Function} options.onTimeout - Callback when loading times out
+ * @returns {Object} Loading state and handlers
+ */
+export const useLoadingState = ({
+	initialLoading = false,
+	minLoadTime = 300,
+	maxLoadTime = 30000,
+	onTimeout = null,
+} = {}) => {
+	const [isLoading, setIsLoading] = useState(initialLoading);
+	const [loadingProgress, setLoadingProgress] = useState(0);
+	const [hasTimedOut, setHasTimedOut] = useState(false);
+	const [loadingMessage, setLoadingMessage] = useState('Loading...');
+
+	const startTimeRef = useRef(null);
+	const timeoutRef = useRef(null);
+	const progressIntervalRef = useRef(null);
+
+	const startLoading = useCallback(
+		(message = 'Loading...') => {
+			setIsLoading(true);
+			setHasTimedOut(false);
+			setLoadingProgress(0);
+			setLoadingMessage(message);
+			startTimeRef.current = Date.now();
+
+			// Set up timeout
+			if (maxLoadTime > 0) {
+				timeoutRef.current = setTimeout(() => {
+					setHasTimedOut(true);
+					setLoadingMessage('Loading is taking longer than expected...');
+					if (onTimeout) onTimeout();
+				}, maxLoadTime);
+			}
+
+			// Set up progress simulation
+			progressIntervalRef.current = setInterval(() => {
+				setLoadingProgress((prev) => {
+					const newProgress = Math.min(prev + Math.random() * 10, 90);
+					return newProgress;
+				});
+			}, 200);
+		},
+		[maxLoadTime, onTimeout]
+	);
+
+	const stopLoading = useCallback(() => {
+		const loadTime = startTimeRef.current
+			? Date.now() - startTimeRef.current
+			: 0;
+
+		// Ensure minimum load time for UX
+		const remainingTime = Math.max(0, minLoadTime - loadTime);
+
+		setTimeout(() => {
+			setIsLoading(false);
+			setLoadingProgress(100);
+			setHasTimedOut(false);
+
+			// Clean up timers
+			if (timeoutRef.current) {
+				clearTimeout(timeoutRef.current);
+				timeoutRef.current = null;
+			}
+			if (progressIntervalRef.current) {
+				clearInterval(progressIntervalRef.current);
+				progressIntervalRef.current = null;
+			}
+		}, remainingTime);
+	}, [minLoadTime]);
+
+	const updateMessage = useCallback((message) => {
+		setLoadingMessage(message);
+	}, []);
+
+	// Cleanup on unmount
+	useEffect(() => {
+		return () => {
+			if (timeoutRef.current) clearTimeout(timeoutRef.current);
+			if (progressIntervalRef.current)
+				clearInterval(progressIntervalRef.current);
+		};
+	}, []);
+
+	return {
+		isLoading,
+		loadingProgress,
+		hasTimedOut,
+		loadingMessage,
+		startLoading,
+		stopLoading,
+		updateMessage,
+	};
+};
+
+/**
+ * Hook for managing loader accessibility announcements
+ * @param {Object} options - Configuration options
+ * @returns {Object} Accessibility utilities
+ */
+export const useLoaderAnnouncements = ({
+	politeAnnouncements = true,
+	announceProgress = false,
+} = {}) => {
+	const [announcement, setAnnouncement] = useState('');
+	const liveRegionRef = useRef(null);
+
+	const announce = useCallback((message, priority = 'polite') => {
+		setAnnouncement(message);
+
+		// Create live region if needed
+		if (!liveRegionRef.current) {
+			const region = document.createElement('div');
+			region.setAttribute('aria-live', priority);
+			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);
+	}, []);
+
+	const announceLoadingStart = useCallback(
+		(message = 'Loading started') => {
+			if (politeAnnouncements) {
+				announce(message, 'polite');
+			}
+		},
+		[announce, politeAnnouncements]
+	);
+
+	const announceLoadingComplete = useCallback(
+		(message = 'Loading complete') => {
+			if (politeAnnouncements) {
+				announce(message, 'polite');
+			}
+		},
+		[announce, politeAnnouncements]
+	);
+
+	const announceProgressUpdate = useCallback(
+		(progress, message) => {
+			if (announceProgress && progress % 25 === 0) {
+				announce(`${message} ${progress}% complete`, 'polite');
+			}
+		},
+		[announce, announceProgress]
+	);
+
+	// Cleanup
+	useEffect(() => {
+		return () => {
+			if (
+				liveRegionRef.current &&
+				document.body.contains(liveRegionRef.current)
+			) {
+				document.body.removeChild(liveRegionRef.current);
+			}
+		};
+	}, []);
+
+	return {
+		announcement,
+		announce,
+		announceLoadingStart,
+		announceLoadingComplete,
+		announceProgressUpdate,
+	};
+};
+
+/**
+ * Common loading messages for different contexts
+ */
+export const loadingMessages = {
+	general: 'Loading...',
+	saving: 'Saving your changes...',
+	loading: 'Loading content...',
+	processing: 'Processing your request...',
+	uploading: 'Uploading file...',
+	downloading: 'Downloading...',
+	authenticating: 'Signing you in...',
+	searching: 'Searching...',
+	deleting: 'Deleting item...',
+	creating: 'Creating new item...',
+	updating: 'Updating information...',
+	connecting: 'Connecting...',
+	syncing: 'Syncing data...',
+	importing: 'Importing data...',
+	exporting: 'Exporting data...',
+};
+
+/**
+ * Size recommendations based on container/context
+ */
+export const sizeGuide = {
+	button: 'sm',
+	card: 'md',
+	modal: 'md',
+	page: 'lg',
+	fullscreen: 'xl',
+	inline: 'sm',
+	sidebar: 'md',
+	dashboard: 'lg',
+};
+
+/**
+ * Variant recommendations based on context
+ */
+export const variantGuide = {
+	data: 'svg', // Data loading
+	file: 'pulse', // File operations
+	search: 'dots', // Search operations
+	save: 'spinner', // Save operations
+	general: 'svg', // General loading
+	processing: 'pulse', // Heavy processing
+	quick: 'dots', // Quick operations
+};
+
+/**
+ * Accessibility testing utilities for loaders
+ */
+export const loaderTestingUtils = {
+	/**
+	 * Validates loader accessibility attributes
+	 */
+	validateLoaderAccessibility() {
+		const loaders = document.querySelectorAll('[role="status"]');
+		const results = [];
+
+		loaders.forEach((loader) => {
+			const hasAriaLabel = !!loader.getAttribute('aria-label');
+			const hasAriaLive = !!loader.getAttribute('aria-live');
+			const hasAriaBusy = loader.getAttribute('aria-busy') === 'true';
+			const hasScreenReaderText = !!loader.querySelector('.sr-only');
+
+			results.push({
+				element: loader.className,
+				hasRole: loader.getAttribute('role') === 'status',
+				hasAriaLabel,
+				hasAriaLive,
+				hasAriaBusy,
+				hasScreenReaderText,
+				ariaLabel: loader.getAttribute('aria-label'),
+				isAccessible: hasAriaLabel && hasAriaLive && hasScreenReaderText,
+			});
+		});
+
+		return results;
+	},
+
+	/**
+	 * Tests animation respect for reduced motion
+	 */
+	validateMotionPreferences() {
+		const prefersReducedMotion = window.matchMedia(
+			'(prefers-reduced-motion: reduce)'
+		).matches;
+		const animatedElements = document.querySelectorAll(
+			'.loader__svg, .loader__spinner, .loader__dots, .loader__pulse'
+		);
+		const results = [];
+
+		animatedElements.forEach((element) => {
+			const computedStyle = window.getComputedStyle(element);
+			const hasAnimation = computedStyle.animationName !== 'none';
+			const animationDuration = computedStyle.animationDuration;
+
+			results.push({
+				element: element.className,
+				prefersReducedMotion,
+				hasAnimation,
+				animationDuration,
+				respectsPreference: prefersReducedMotion
+					? animationDuration === '0s'
+					: true,
+			});
+		});
+
+		return results;
+	},
+
+	/**
+	 * Tests loader focus management
+	 */
+	validateFocusManagement() {
+		const loaders = document.querySelectorAll('[role="status"]');
+		const results = [];
+
+		loaders.forEach((loader) => {
+			const isFocusable = loader.tabIndex >= 0;
+			const hasProperFocusStyle = !!window.getComputedStyle(loader, ':focus')
+				.outline;
+
+			results.push({
+				element: loader.className,
+				isFocusable,
+				hasProperFocusStyle,
+				tabIndex: loader.tabIndex,
+				isAccessible: !isFocusable, // Loaders shouldn't be focusable
+			});
+		});
+
+		return results;
+	},
+
+	/**
+	 * Tests high contrast compatibility
+	 */
+	validateHighContrast() {
+		const loaders = document.querySelectorAll('.loader');
+		const results = [];
+
+		loaders.forEach((loader) => {
+			const style = window.getComputedStyle(loader);
+			const spinnerElements = loader.querySelectorAll(
+				'.loader__svg, .loader__spinner, .loader__dots, .loader__pulse'
+			);
+
+			let hasContrastStyles = false;
+			spinnerElements.forEach((spinner) => {
+				const spinnerStyle = window.getComputedStyle(spinner);
+				// Check if element has contrast-friendly styling
+				hasContrastStyles =
+					spinnerStyle.border !== 'none' || spinnerStyle.outline !== 'none';
+			});
+
+			results.push({
+				element: loader.className,
+				hasContrastStyles,
+				backgroundColor: style.backgroundColor,
+				color: style.color,
+				isHighContrastReady: hasContrastStyles,
+			});
+		});
+
+		return results;
+	},
+
+	/**
+	 * Comprehensive loader audit
+	 */
+	auditLoader() {
+		return {
+			accessibility: this.validateLoaderAccessibility(),
+			motionPreferences: this.validateMotionPreferences(),
+			focusManagement: this.validateFocusManagement(),
+			highContrast: this.validateHighContrast(),
+			timestamp: new Date().toISOString(),
+		};
+	},
+};
+
+/**
+ * Performance utilities for loaders
+ */
+export const loaderPerformanceUtils = {
+	/**
+	 * Measures loader render performance
+	 */
+	measureRenderTime: (callback) => {
+		const start = performance.now();
+		callback();
+		const end = performance.now();
+		return end - start;
+	},
+
+	/**
+	 * Monitors loader animation performance
+	 */
+	monitorAnimationPerformance: (element) => {
+		let frameCount = 0;
+		let lastTime = performance.now();
+
+		const monitor = () => {
+			frameCount++;
+			const currentTime = performance.now();
+			const deltaTime = currentTime - lastTime;
+
+			if (deltaTime >= 1000) {
+				const fps = Math.round((frameCount * 1000) / deltaTime);
+				console.log(`Loader animation FPS: ${fps}`);
+				frameCount = 0;
+				lastTime = currentTime;
+			}
+
+			if (element && element.offsetParent) {
+				requestAnimationFrame(monitor);
+			}
+		};
+
+		requestAnimationFrame(monitor);
+	},
+};
+
+export default {
+	useLoadingState,
+	useLoaderAnnouncements,
+	loadingMessages,
+	sizeGuide,
+	variantGuide,
+	loaderTestingUtils,
+	loaderPerformanceUtils,
+};