@abstraks-dev/ui-library 1.0.1

package/dist/utils/useTypographyAccessibility.js

@@ -0,0 +1,168 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useTypographyAccessibility = exports.useFocusManagement = exports.getTypographyClassNames = void 0;
+var _react = require("react");
+/**
+ * Custom hook for typography accessibility features
+ * Manages user preferences for font size, contrast, and motion
+ *
+ * @returns {Object} Typography accessibility state and utilities
+ */
+const useTypographyAccessibility = () => {
+  const [preferences, setPreferences] = (0, _react.useState)({
+    highContrast: false,
+    reducedMotion: false,
+    fontSize: 100,
+    currentBreakpoint: 'small'
+  });
+
+  // Detect user's system preferences
+  (0, _react.useEffect)(() => {
+    const detectSystemPreferences = () => {
+      setPreferences(prev => ({
+        ...prev,
+        highContrast: window.matchMedia('(prefers-contrast: high)').matches || false,
+        reducedMotion: window.matchMedia('(prefers-reduced-motion: reduce)').matches
+      }));
+    };
+    detectSystemPreferences();
+
+    // Listen for changes in system preferences
+    const contrastQuery = window.matchMedia('(prefers-contrast: high)');
+    const motionQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+    contrastQuery.addEventListener('change', detectSystemPreferences);
+    motionQuery.addEventListener('change', detectSystemPreferences);
+    return () => {
+      contrastQuery.removeEventListener('change', detectSystemPreferences);
+      motionQuery.removeEventListener('change', detectSystemPreferences);
+    };
+  }, []);
+
+  // Detect current breakpoint
+  (0, _react.useEffect)(() => {
+    const updateBreakpoint = () => {
+      const width = window.innerWidth;
+      let breakpoint;
+      if (width >= 1200) breakpoint = 'xlarge';else if (width >= 992) breakpoint = 'large';else if (width >= 768) breakpoint = 'medium';else breakpoint = 'small';
+      setPreferences(prev => ({
+        ...prev,
+        currentBreakpoint: breakpoint
+      }));
+    };
+    updateBreakpoint();
+    window.addEventListener('resize', updateBreakpoint);
+    return () => window.removeEventListener('resize', updateBreakpoint);
+  }, []);
+
+  // Utility functions
+  const toggleHighContrast = () => {
+    setPreferences(prev => ({
+      ...prev,
+      highContrast: !prev.highContrast
+    }));
+  };
+  const setFontSize = size => {
+    setPreferences(prev => ({
+      ...prev,
+      fontSize: Math.max(50, Math.min(200, size))
+    }));
+  };
+  const getAccessibilityStyles = () => {
+    return {
+      fontSize: `${preferences.fontSize}%`,
+      filter: preferences.highContrast ? 'contrast(150%) brightness(120%)' : 'none',
+      transition: preferences.reducedMotion ? 'none' : undefined
+    };
+  };
+  const getBreakpointLabel = () => {
+    const labels = {
+      small: 'Small screens (<768px)',
+      medium: 'Medium (768px+)',
+      large: 'Large (992px+)',
+      xlarge: 'Extra Large (1200px+)'
+    };
+    return labels[preferences.currentBreakpoint];
+  };
+  return {
+    preferences,
+    toggleHighContrast,
+    setFontSize,
+    getAccessibilityStyles,
+    getBreakpointLabel
+  };
+};
+
+/**
+ * Utility for generating typography class names with accessibility considerations
+ *
+ * @param {string} baseClass - Base class name
+ * @param {string} size - Size variant (small, medium, large)
+ * @param {string} additionalClass - Additional class names
+ * @param {Object} preferences - Accessibility preferences
+ * @returns {string} Combined class names
+ */
+exports.useTypographyAccessibility = useTypographyAccessibility;
+const getTypographyClassNames = (baseClass, size = 'medium', additionalClass = '', preferences = {}) => {
+  const classes = [baseClass];
+
+  // Add size modifier
+  if (size && size !== 'medium') {
+    classes.push(`${baseClass}--${size}`);
+  }
+
+  // Add accessibility modifiers
+  if (preferences.highContrast) {
+    classes.push(`${baseClass}--high-contrast`);
+  }
+  if (preferences.reducedMotion) {
+    classes.push(`${baseClass}--reduced-motion`);
+  }
+
+  // Add additional classes
+  if (additionalClass) {
+    classes.push(additionalClass);
+  }
+  return classes.join(' ');
+};
+
+/**
+ * Focus management utility for typography components
+ * Ensures proper focus indicators and keyboard navigation
+ *
+ * @param {React.RefObject} elementRef - Reference to the element
+ * @param {Object} options - Focus options
+ */
+exports.getTypographyClassNames = getTypographyClassNames;
+const useFocusManagement = (elementRef, options = {}) => {
+  const {
+    onFocus,
+    onBlur,
+    focusOnMount = false,
+    trapFocus = false
+  } = options;
+  (0, _react.useEffect)(() => {
+    const element = elementRef.current;
+    if (!element) return;
+    if (focusOnMount) {
+      element.focus();
+    }
+    const handleFocus = event => {
+      element.setAttribute('data-focused', 'true');
+      onFocus?.(event);
+    };
+    const handleBlur = event => {
+      element.removeAttribute('data-focused');
+      onBlur?.(event);
+    };
+    element.addEventListener('focus', handleFocus);
+    element.addEventListener('blur', handleBlur);
+    return () => {
+      element.removeEventListener('focus', handleFocus);
+      element.removeEventListener('blur', handleBlur);
+    };
+  }, [elementRef, onFocus, onBlur, focusOnMount, trapFocus]);
+};
+exports.useFocusManagement = useFocusManagement;

package/dist/utils/useWindowSize.js

@@ -0,0 +1,32 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useWindowSize = void 0;
+var _react = require("react");
+const useWindowSize = () => {
+  // Initialize state with undefined width/height so server and client renders match
+  const [windowSize, setWindowSize] = (0, _react.useState)({
+    width: undefined,
+    height: undefined
+  });
+  (0, _react.useEffect)(() => {
+    // Handler to call on window resize
+    function handleResize() {
+      // Set window width/height to state
+      setWindowSize({
+        width: window.innerWidth,
+        height: window.innerHeight
+      });
+    }
+    // Add event listener
+    window.addEventListener('resize', handleResize);
+    // Call handler right away so state gets updated with initial window size
+    handleResize();
+    // Remove event listener on cleanup
+    return () => window.removeEventListener('resize', handleResize);
+  }, []); // Empty array ensures that effect is only run on mount
+  return windowSize;
+};
+exports.useWindowSize = useWindowSize;

package/dist/utils/utils/ScrollHandler.js

@@ -0,0 +1,26 @@
+import { useEffect } from 'react';
+import PropTypes from 'prop-types';
+import { withRouter } from 'react-router-dom';
+
+const ScrollHandler = ({ location }) => {
+	useEffect(() => {
+		const element = document.getElementById(location.hash);
+
+		setTimeout(() => {
+			window.scrollTo({
+				behavior: element ? 'smooth' : 'auto',
+				top: element ? element.offsetTop : 0,
+			});
+		}, 100);
+	}, [location]);
+
+	return null;
+};
+
+ScrollHandler.propTypes = {
+	location: PropTypes.shape({
+		hash: PropTypes.string,
+	}).isRequired,
+};
+
+export default withRouter(ScrollHandler);

package/dist/utils/utils/accessibility.js

@@ -0,0 +1,133 @@
+/**
+ * Accessibility utility functions for screen readers and ARIA support
+ */
+
+/**
+ * Announces a message to screen readers using ARIA live regions
+ * This is a safer alternative to direct DOM manipulation
+ *
+ * @param {string} message - The message to announce
+ * @param {'polite'|'assertive'} priority - The announcement priority level
+ * @param {number} timeout - How long to keep the announcement (default: 1000ms)
+ * @returns {Function} Cleanup function to remove the announcement early
+ *
+ * @example
+ * // Announce an error assertively
+ * const cleanup = announceToScreenReader('Form validation failed', 'assertive');
+ *
+ * // Announce info politely
+ * announceToScreenReader('Data saved automatically', 'polite');
+ */
+export const announceToScreenReader = (
+	message,
+	priority = 'polite',
+	timeout = 1000
+) => {
+	// Ensure we're in a browser environment
+	if (typeof document === 'undefined') {
+		return () => {}; // Return no-op cleanup function for SSR
+	}
+
+	const announcement = document.createElement('div');
+	announcement.setAttribute('aria-live', priority);
+	announcement.setAttribute('aria-atomic', 'true');
+	announcement.className = 'sr-only'; // Use CSS class instead of inline styles
+	announcement.textContent = message;
+
+	// Add to document body
+	document.body.appendChild(announcement);
+
+	// Set up cleanup
+	const cleanup = () => {
+		if (document.body.contains(announcement)) {
+			document.body.removeChild(announcement);
+		}
+	};
+
+	// Auto cleanup after timeout
+	setTimeout(cleanup, timeout);
+
+	// Return cleanup function for manual cleanup if needed
+	return cleanup;
+};
+
+/**
+ * Creates a live region element that can be reused for announcements
+ * This is more efficient for multiple announcements
+ *
+ * @param {'polite'|'assertive'} priority - The announcement priority level
+ * @returns {Object} Object with announce and destroy methods
+ *
+ * @example
+ * const liveRegion = createLiveRegion('assertive');
+ * liveRegion.announce('First message');
+ * liveRegion.announce('Second message');
+ * liveRegion.destroy(); // Clean up when done
+ */
+export const createLiveRegion = (priority = 'polite') => {
+	// Ensure we're in a browser environment
+	if (typeof document === 'undefined') {
+		return {
+			announce: () => {},
+			destroy: () => {},
+		};
+	}
+
+	const liveRegion = document.createElement('div');
+	liveRegion.setAttribute('aria-live', priority);
+	liveRegion.setAttribute('aria-atomic', 'true');
+	liveRegion.className = 'sr-only';
+	liveRegion.setAttribute(
+		'role',
+		priority === 'assertive' ? 'alert' : 'status'
+	);
+
+	document.body.appendChild(liveRegion);
+
+	return {
+		/**
+		 * Announce a message in this live region
+		 * @param {string} message - The message to announce
+		 */
+		announce: (message) => {
+			liveRegion.textContent = message;
+			// Clear after a short delay to allow for new announcements
+			setTimeout(() => {
+				if (liveRegion.textContent === message) {
+					liveRegion.textContent = '';
+				}
+			}, 1000);
+		},
+
+		/**
+		 * Clean up the live region
+		 */
+		destroy: () => {
+			if (document.body.contains(liveRegion)) {
+				document.body.removeChild(liveRegion);
+			}
+		},
+	};
+};
+
+/**
+ * Utility to focus an element safely with fallback
+ * @param {HTMLElement|string} element - Element or selector to focus
+ * @param {Object} options - Focus options
+ * @returns {boolean} Whether focus was successful
+ */
+export const safeFocus = (element, options = {}) => {
+	try {
+		const el =
+			typeof element === 'string' ? document.querySelector(element) : element;
+
+		if (el && typeof el.focus === 'function') {
+			el.focus(options);
+			return document.activeElement === el;
+		}
+		return false;
+	} catch (error) {
+		console.warn('Failed to focus element:', error);
+		return false;
+	}
+};

package/dist/utils/utils/heroUtils.js

@@ -0,0 +1,348 @@
+/**
+ * Hero Component Utilities
+ * Provides helper functions and hooks for Hero component functionality
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+
+/**
+ * Hook to detect user's motion preference and apply appropriate settings
+ * @returns {Object} Motion preference settings
+ */
+export const useMotionPreference = () => {
+	const [prefersReducedMotion, setPrefersReducedMotion] = useState(false);
+
+	useEffect(() => {
+		if (typeof window !== 'undefined') {
+			const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+			setPrefersReducedMotion(mediaQuery.matches);
+
+			const handleChange = (e) => {
+				setPrefersReducedMotion(e.matches);
+			};
+
+			mediaQuery.addEventListener('change', handleChange);
+			return () => mediaQuery.removeEventListener('change', handleChange);
+		}
+	}, []);
+
+	return {
+		prefersReducedMotion,
+		backgroundAttachment: prefersReducedMotion ? 'scroll' : 'fixed',
+		transitionDuration: prefersReducedMotion ? '0s' : '0.3s',
+	};
+};
+
+/**
+ * Hook to detect high contrast mode preference
+ * @returns {boolean} Whether high contrast mode is enabled
+ */
+export const useHighContrast = () => {
+	const [highContrast, setHighContrast] = useState(false);
+
+	useEffect(() => {
+		if (typeof window !== 'undefined') {
+			const mediaQuery = window.matchMedia('(prefers-contrast: high)');
+			setHighContrast(mediaQuery.matches);
+
+			const handleChange = (e) => {
+				setHighContrast(e.matches);
+			};
+
+			mediaQuery.addEventListener('change', handleChange);
+			return () => mediaQuery.removeEventListener('change', handleChange);
+		}
+	}, []);
+
+	return highContrast;
+};
+
+/**
+ * Hook for responsive hero height based on viewport
+ * @param {Object} options - Configuration options
+ * @param {string} options.minHeight - Minimum height (default: '400px')
+ * @param {string} options.maxHeight - Maximum height (default: '100vh')
+ * @returns {Object} Height settings and viewport info
+ */
+export const useResponsiveHeight = ({
+	minHeight = '400px',
+	maxHeight = '100vh',
+} = {}) => {
+	const [viewportHeight, setViewportHeight] = useState(
+		typeof window !== 'undefined' ? window.innerHeight : 800
+	);
+	const [isMobile, setIsMobile] = useState(false);
+
+	useEffect(() => {
+		const updateHeight = () => {
+			setViewportHeight(window.innerHeight);
+			setIsMobile(window.innerWidth < 768);
+		};
+
+		updateHeight();
+		window.addEventListener('resize', updateHeight);
+		return () => window.removeEventListener('resize', updateHeight);
+	}, []);
+
+	const calculatedHeight = Math.max(
+		parseInt(minHeight),
+		Math.min(viewportHeight * 0.7, parseInt(maxHeight))
+	);
+
+	return {
+		height: `${calculatedHeight}px`,
+		viewportHeight,
+		isMobile,
+		isLandscape: viewportHeight < window.innerWidth,
+	};
+};
+
+/**
+ * Hook for managing background image loading and optimization
+ * @param {string} imageUrl - URL of the background image
+ * @returns {Object} Image loading state and optimized URL
+ */
+export const useBackgroundImage = (imageUrl) => {
+	const [isLoaded, setIsLoaded] = useState(false);
+	const [hasError, setHasError] = useState(false);
+	const [optimizedUrl, setOptimizedUrl] = useState(imageUrl);
+
+	useEffect(() => {
+		if (!imageUrl) return;
+
+		setIsLoaded(false);
+		setHasError(false);
+
+		const img = new Image();
+		img.onload = () => setIsLoaded(true);
+		img.onerror = () => setHasError(true);
+		img.src = imageUrl;
+
+		// Basic URL optimization for common image services
+		if (imageUrl.includes('unsplash.com')) {
+			const size =
+				window.innerWidth > 1200
+					? '2070'
+					: window.innerWidth > 768
+					? '1536'
+					: '1024';
+			setOptimizedUrl(`${imageUrl}&w=${size}&auto=format&fit=crop&q=80`);
+		} else {
+			setOptimizedUrl(imageUrl);
+		}
+	}, [imageUrl]);
+
+	return {
+		isLoaded,
+		hasError,
+		optimizedUrl,
+	};
+};
+
+/**
+ * Generates accessible hero props based on content and configuration
+ * @param {Object} config - Configuration object
+ * @returns {Object} Accessibility props
+ */
+export const generateHeroAccessibility = ({
+	hasHeading = true,
+	hasCallToAction = false,
+	isLandingPage = false,
+	customRole = null,
+	customLabel = null,
+}) => {
+	const role = customRole || (isLandingPage ? 'banner' : 'region');
+
+	const ariaLabel =
+		customLabel ||
+		(hasCallToAction
+			? 'Hero section with call-to-action'
+			: 'Hero content section');
+
+	const props = {
+		role,
+		'aria-label': ariaLabel,
+	};
+
+	// Add landmark navigation hints
+	if (hasHeading && !customLabel) {
+		delete props['aria-label']; // Let heading provide the label
+	}
+
+	return props;
+};
+
+/**
+ * Validates hero content for accessibility compliance
+ * @param {Object} content - Content configuration
+ * @returns {Array} Array of accessibility warnings
+ */
+export const validateHeroAccessibility = ({
+	hasBackground = false,
+	backgroundAlt = '',
+	hasHeading = false,
+	headingLevel = null,
+	hasCallToAction = false,
+	textContrast = 'unknown',
+}) => {
+	const warnings = [];
+
+	// Background image validation
+	if (hasBackground && !backgroundAlt) {
+		warnings.push({
+			type: 'error',
+			message: 'Background images must have alt text for accessibility',
+			recommendation: 'Add backgroundAlt prop with descriptive text',
+		});
+	}
+
+	// Heading validation
+	if (!hasHeading) {
+		warnings.push({
+			type: 'warning',
+			message: 'Hero sections should typically include a heading',
+			recommendation: 'Add an h1 or h2 element to provide section context',
+		});
+	}
+
+	if (hasHeading && headingLevel && headingLevel > 2) {
+		warnings.push({
+			type: 'warning',
+			message: `Hero heading level h${headingLevel} may be too deep`,
+			recommendation: 'Consider using h1 or h2 for hero sections',
+		});
+	}
+
+	// Call-to-action validation
+	if (hasCallToAction) {
+		warnings.push({
+			type: 'info',
+			message: 'Ensure CTA buttons have descriptive aria-label attributes',
+			recommendation:
+				'Use aria-label to describe the action, not just "Click here"',
+		});
+	}
+
+	// Contrast validation
+	if (hasBackground && textContrast === 'low') {
+		warnings.push({
+			type: 'error',
+			message: 'Text contrast may be insufficient over background image',
+			recommendation:
+				'Add overlay or adjust text colors to meet WCAG contrast requirements',
+		});
+	}
+
+	return warnings;
+};
+
+/**
+ * Hero testing utilities for automated and manual testing
+ */
+export const heroTestingUtils = {
+	/**
+	 * Simulates keyboard navigation through hero content
+	 */
+	async simulateKeyboardNavigation() {
+		const focusableElements = document.querySelectorAll(
+			'[role="banner"] a, [role="banner"] button, [role="banner"] input, [role="banner"] [tabindex="0"]'
+		);
+
+		const results = [];
+
+		for (let element of focusableElements) {
+			element.focus();
+			const isVisible = this.isFocusVisible(element);
+			const hasAriaLabel =
+				element.getAttribute('aria-label') ||
+				element.getAttribute('aria-labelledby');
+
+			results.push({
+				element: element.tagName,
+				isFocusVisible: isVisible,
+				hasAriaLabel: !!hasAriaLabel,
+				textContent: element.textContent?.trim().substring(0, 50),
+			});
+
+			// Small delay to simulate real user interaction
+			await new Promise((resolve) => setTimeout(resolve, 100));
+		}
+
+		return results;
+	},
+
+	/**
+	 * Checks if focus indicators are visible
+	 */
+	isFocusVisible(element) {
+		const styles = window.getComputedStyle(element, ':focus-visible');
+		return styles.outlineWidth !== '0px' || styles.boxShadow !== 'none';
+	},
+
+	/**
+	 * Validates screen reader announcements
+	 */
+	validateScreenReaderContent() {
+		const hero = document.querySelector('[role="banner"], [role="region"]');
+		if (!hero) return { valid: false, message: 'No hero section found' };
+
+		const hasAriaLabel =
+			hero.getAttribute('aria-label') || hero.getAttribute('aria-labelledby');
+		const hasHeading = hero.querySelector('h1, h2, h3, h4, h5, h6');
+		const backgroundDescription = hero.querySelector('[id*="bg-description"]');
+
+		return {
+			valid: hasAriaLabel || hasHeading,
+			hasAriaLabel: !!hasAriaLabel,
+			hasHeading: !!hasHeading,
+			hasBackgroundDescription: !!backgroundDescription,
+			recommendations: [
+				...(!(hasAriaLabel || hasHeading)
+					? ['Add aria-label or heading for screen readers']
+					: []),
+				...(!backgroundDescription && hero.style.backgroundImage
+					? ['Add background image description']
+					: []),
+			],
+		};
+	},
+
+	/**
+	 * Tests responsive behavior
+	 */
+	testResponsiveBehavior() {
+		const viewports = [
+			{ width: 320, height: 568, name: 'Mobile Portrait' },
+			{ width: 768, height: 1024, name: 'Tablet' },
+			{ width: 1200, height: 800, name: 'Desktop' },
+			{ width: 1920, height: 1080, name: 'Large Desktop' },
+		];
+
+		const hero = document.querySelector('.hero-wrapper');
+		if (!hero) return { valid: false, message: 'Hero wrapper not found' };
+
+		const results = viewports.map((viewport) => {
+			// Note: In real testing, you'd actually resize the viewport
+			// This is a simulation for documentation purposes
+			return {
+				viewport: viewport.name,
+				dimensions: `${viewport.width}x${viewport.height}`,
+				minHeight: window.getComputedStyle(hero).minHeight,
+				backgroundAttachment:
+					window.getComputedStyle(hero).backgroundAttachment,
+			};
+		});
+
+		return { valid: true, results };
+	},
+};
+
+export default {
+	useMotionPreference,
+	useHighContrast,
+	useResponsiveHeight,
+	useBackgroundImage,
+	generateHeroAccessibility,
+	validateHeroAccessibility,
+	heroTestingUtils,
+};