@abstraks-dev/ui-library 1.0.1

package/dist/utils/loaderUtils.js

@@ -0,0 +1,387 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.variantGuide = exports.useLoadingState = exports.useLoaderAnnouncements = exports.sizeGuide = exports.loadingMessages = exports.loaderTestingUtils = exports.loaderPerformanceUtils = exports.default = void 0;
+var _react = require("react");
+/**
+ * Loader Component Utilities
+ * Provides helper functions and hooks for Loader component functionality
+ */
+
+/**
+ * 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
+ */
+const useLoadingState = ({
+  initialLoading = false,
+  minLoadTime = 300,
+  maxLoadTime = 30000,
+  onTimeout = null
+} = {}) => {
+  const [isLoading, setIsLoading] = (0, _react.useState)(initialLoading);
+  const [loadingProgress, setLoadingProgress] = (0, _react.useState)(0);
+  const [hasTimedOut, setHasTimedOut] = (0, _react.useState)(false);
+  const [loadingMessage, setLoadingMessage] = (0, _react.useState)('Loading...');
+  const startTimeRef = (0, _react.useRef)(null);
+  const timeoutRef = (0, _react.useRef)(null);
+  const progressIntervalRef = (0, _react.useRef)(null);
+  const startLoading = (0, _react.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 = (0, _react.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 = (0, _react.useCallback)(message => {
+    setLoadingMessage(message);
+  }, []);
+
+  // Cleanup on unmount
+  (0, _react.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
+ */
+exports.useLoadingState = useLoadingState;
+const useLoaderAnnouncements = ({
+  politeAnnouncements = true,
+  announceProgress = false
+} = {}) => {
+  const [announcement, setAnnouncement] = (0, _react.useState)('');
+  const liveRegionRef = (0, _react.useRef)(null);
+  const announce = (0, _react.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 = (0, _react.useCallback)((message = 'Loading started') => {
+    if (politeAnnouncements) {
+      announce(message, 'polite');
+    }
+  }, [announce, politeAnnouncements]);
+  const announceLoadingComplete = (0, _react.useCallback)((message = 'Loading complete') => {
+    if (politeAnnouncements) {
+      announce(message, 'polite');
+    }
+  }, [announce, politeAnnouncements]);
+  const announceProgressUpdate = (0, _react.useCallback)((progress, message) => {
+    if (announceProgress && progress % 25 === 0) {
+      announce(`${message} ${progress}% complete`, 'polite');
+    }
+  }, [announce, announceProgress]);
+
+  // Cleanup
+  (0, _react.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
+ */
+exports.useLoaderAnnouncements = useLoaderAnnouncements;
+const loadingMessages = exports.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
+ */
+const sizeGuide = exports.sizeGuide = {
+  button: 'sm',
+  card: 'md',
+  modal: 'md',
+  page: 'lg',
+  fullscreen: 'xl',
+  inline: 'sm',
+  sidebar: 'md',
+  dashboard: 'lg'
+};
+
+/**
+ * Variant recommendations based on context
+ */
+const variantGuide = exports.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
+ */
+const loaderTestingUtils = exports.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
+ */
+const loaderPerformanceUtils = exports.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);
+  }
+};
+var _default = exports.default = {
+  useLoadingState,
+  useLoaderAnnouncements,
+  loadingMessages,
+  sizeGuide,
+  variantGuide,
+  loaderTestingUtils,
+  loaderPerformanceUtils
+};