@abstraks-dev/ui-library 1.0.1

package/dist/utils/utils/useTextInputAccessibility.js

@@ -0,0 +1,338 @@
+import { useState, useCallback, useRef } from 'react';
+import {
+	validateEmail,
+	validatePhone,
+	validateLength,
+	validateRequired,
+} from './inputValidation';
+
+/**
+ * Custom hook for managing text input state with accessibility features
+ * Provides controlled state management for text input with ARIA support
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} options.defaultValue - Default input value
+ * @param {Function} options.onChange - Change callback function
+ * @param {boolean} options.required - Whether the field is required
+ * @param {number} options.maxLength - Maximum character count
+ * @param {number} options.minLength - Minimum character count
+ * @param {string} options.type - Input type for validation
+ * @returns {Object} TextInput state and handlers
+ */
+export const useTextInputAccessibility = (options = {}) => {
+	const {
+		defaultValue = '',
+		onChange,
+		required = false,
+		maxLength,
+		minLength,
+		type = 'text',
+	} = options;
+
+	const [value, setValue] = useState(defaultValue);
+	const [isValid, setIsValid] = useState(!required || defaultValue.length > 0);
+	const [hasBeenTouched, setHasBeenTouched] = useState(false);
+	const inputRef = useRef(null);
+
+	const validateInput = useCallback(
+		(inputValue, inputType) => {
+			let valid = true;
+			if (required && !validateRequired(inputValue)) valid = false;
+			if (!validateLength(inputValue, minLength, maxLength)) valid = false;
+			switch (inputType) {
+				case 'email':
+					if (inputValue && !validateEmail(inputValue)) valid = false;
+					break;
+				case 'tel':
+					if (inputValue && !validatePhone(inputValue)) valid = false;
+					break;
+				case 'url':
+					try {
+						if (
+							inputValue &&
+							!(
+								inputValue.startsWith('http://') ||
+								inputValue.startsWith('https://')
+							)
+						) {
+							valid = false;
+						}
+					} catch (e) {
+						valid = false;
+					}
+					break;
+				default:
+					break;
+			}
+			return valid;
+		},
+		[type]
+	);
+
+	const handleFocus = useCallback((event) => {
+		setHasBeenTouched(true);
+	}, []);
+
+	const handleBlur = useCallback(
+		(event) => {
+			const newValue = event.target.value;
+			const valid = validateInput(newValue, type);
+			setIsValid(valid);
+		},
+		[type, validateInput]
+	);
+
+	const reset = useCallback(() => {
+		setValue(defaultValue);
+		setIsValid(!required || defaultValue.length > 0);
+		setHasBeenTouched(false);
+	}, [defaultValue, required]);
+
+	const focus = useCallback(() => {
+		inputRef.current?.focus();
+	}, []);
+
+	// Unified onChange handler for input/textarea
+	const handleChange = useCallback(
+		(event) => {
+			const newValue = event.target.value;
+			setValue(newValue);
+			if (onChange) onChange(newValue);
+		},
+		[onChange]
+	);
+
+	return {
+		// State
+		value,
+		isValid,
+		hasBeenTouched,
+		showError: hasBeenTouched && !isValid,
+
+		// Handlers
+		handleFocus,
+		handleBlur,
+		handleChange,
+		reset,
+		focus,
+
+		// Ref
+		inputRef,
+
+		// Computed properties
+		charCount: value.length,
+		remainingChars: maxLength ? maxLength - value.length : null,
+		isAtMaxLength: maxLength ? value.length >= maxLength : false,
+		isAtMinLength: minLength ? value.length >= minLength : true,
+	};
+};
+
+/**
+ * Validates text input accessibility compliance
+ * Checks for proper ARIA attributes, labels, and keyboard support
+ *
+ * @param {HTMLElement} inputElement - The input element to validate
+ * @returns {Object} Validation results with errors and warnings
+ */
+export const validateTextInputAccessibility = (inputElement) => {
+	const results = {
+		passed: true,
+		errors: [],
+		warnings: [],
+		info: [],
+	};
+
+	if (!inputElement) {
+		results.passed = false;
+		results.errors.push('No input element provided for validation');
+		return results;
+	}
+
+	// Check if it's actually an input element
+	if (inputElement.tagName.toLowerCase() !== 'input') {
+		const input = inputElement.querySelector('input');
+		if (!input) {
+			results.passed = false;
+			results.errors.push(
+				'Element is not an input and contains no input element'
+			);
+			return results;
+		}
+		inputElement = input;
+	}
+
+	// 1. Check for accessible name
+	const hasLabel =
+		inputElement.hasAttribute('aria-label') ||
+		inputElement.hasAttribute('aria-labelledby') ||
+		inputElement.labels?.length > 0;
+
+	if (!hasLabel) {
+		results.passed = false;
+		results.errors.push(
+			'Input must have an accessible name (label, aria-label, or aria-labelledby)'
+		);
+	}
+
+	// 2. Check for proper ID if labelledby is used
+	if (inputElement.hasAttribute('aria-labelledby')) {
+		const labelId = inputElement.getAttribute('aria-labelledby');
+		const labelElement = document.getElementById(labelId);
+		if (!labelElement) {
+			results.passed = false;
+			results.errors.push(
+				`Referenced label element with ID "${labelId}" not found`
+			);
+		}
+	}
+
+	// 3. Check for required field indication
+	if (
+		inputElement.hasAttribute('required') ||
+		inputElement.hasAttribute('aria-required')
+	) {
+		if (!inputElement.hasAttribute('aria-required')) {
+			results.warnings.push(
+				'Consider adding aria-required="true" for screen reader users'
+			);
+		}
+	}
+
+	// 4. Check for error state accessibility
+	if (inputElement.hasAttribute('aria-invalid')) {
+		const isInvalid = inputElement.getAttribute('aria-invalid') === 'true';
+		if (isInvalid && !inputElement.hasAttribute('aria-describedby')) {
+			results.warnings.push(
+				'Invalid input should have aria-describedby pointing to error message'
+			);
+		}
+	}
+
+	// 5. Check input type appropriateness
+	const inputType = inputElement.getAttribute('type') || 'text';
+	if (inputType === 'text' && inputElement.getAttribute('name')) {
+		const name = inputElement.getAttribute('name').toLowerCase();
+		if (name.includes('email')) {
+			results.warnings.push('Consider using type="email" for email inputs');
+		} else if (name.includes('phone') || name.includes('tel')) {
+			results.warnings.push('Consider using type="tel" for phone inputs');
+		} else if (name.includes('url') || name.includes('website')) {
+			results.warnings.push('Consider using type="url" for URL inputs');
+		}
+	}
+
+	// 6. Check for placeholder accessibility
+	if (inputElement.hasAttribute('placeholder')) {
+		results.warnings.push(
+			'Avoid using placeholder as the only label - ensure proper labeling exists'
+		);
+	}
+
+	// 7. Check for disabled state
+	if (inputElement.disabled) {
+		results.info.push('Input is disabled');
+	}
+
+	// 8. Check for keyboard accessibility
+	const tabIndex = inputElement.getAttribute('tabindex');
+	if (tabIndex && parseInt(tabIndex) < 0) {
+		results.warnings.push(
+			'Input has negative tabindex - may not be keyboard accessible'
+		);
+	}
+
+	// 9. Check autocomplete attributes
+	const autocomplete = inputElement.getAttribute('autocomplete');
+	if (!autocomplete && ['email', 'tel', 'url'].includes(inputType)) {
+		results.info.push(
+			`Consider adding autocomplete attribute for ${inputType} inputs`
+		);
+	}
+
+	if (results.errors.length === 0) {
+		results.info.push('Basic accessibility validation passed');
+	}
+
+	return results;
+};
+
+/**
+ * Input validation utility for common input types
+ * Provides validation messages and patterns
+ *
+ * @param {string} value - Current input value
+ * @param {string} type - Input type
+ * @param {Object} options - Validation options
+ * @returns {Object} Validation result with message and validity
+ */
+export const getInputValidationInfo = (value, type, options = {}) => {
+	const { required = false, minLength, maxLength } = options;
+
+	let isValid = true;
+	let message = '';
+	let status = 'valid';
+
+	// Required validation
+	if (required && !value.trim()) {
+		isValid = false;
+		message = 'This field is required';
+		status = 'error';
+		return { isValid, message, status };
+	}
+
+	// Length validation
+	if (minLength && value.length < minLength) {
+		isValid = false;
+		message = `Minimum ${minLength} characters required`;
+		status = 'error';
+	} else if (maxLength && value.length > maxLength) {
+		isValid = false;
+		message = `Maximum ${maxLength} characters allowed`;
+		status = 'error';
+	}
+
+	// Type-specific validation
+	if (value && isValid) {
+		switch (type) {
+			case 'email':
+				const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+				if (!emailRegex.test(value)) {
+					isValid = false;
+					message = 'Please enter a valid email address';
+					status = 'error';
+				}
+				break;
+			case 'tel':
+				const phoneRegex = /^[\+]?[\s\-\(\)]?[\d\s\-\(\)]{10,}$/;
+				if (!phoneRegex.test(value)) {
+					isValid = false;
+					message = 'Please enter a valid phone number';
+					status = 'error';
+				}
+				break;
+			case 'url':
+				if (!value.startsWith('http://') && !value.startsWith('https://')) {
+					isValid = false;
+					message =
+						'Please enter a valid URL (starting with http:// or https://)';
+					status = 'error';
+				}
+				break;
+			case 'number':
+				if (isNaN(Number(value))) {
+					isValid = false;
+					message = 'Please enter a valid number';
+					status = 'error';
+				}
+				break;
+		}
+	}
+
+	return {
+		isValid,
+		message,
+		status,
+		charCount: value.length,
+		remainingChars: maxLength ? maxLength - value.length : null,
+	};
+};

package/dist/utils/utils/useTypographyAccessibility.js

@@ -0,0 +1,180 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Custom hook for typography accessibility features
+ * Manages user preferences for font size, contrast, and motion
+ *
+ * @returns {Object} Typography accessibility state and utilities
+ */
+export const useTypographyAccessibility = () => {
+	const [preferences, setPreferences] = useState({
+		highContrast: false,
+		reducedMotion: false,
+		fontSize: 100,
+		currentBreakpoint: 'small',
+	});
+
+	// Detect user's system preferences
+	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
+	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
+ */
+export 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
+ */
+export const useFocusManagement = (elementRef, options = {}) => {
+	const { onFocus, onBlur, focusOnMount = false, trapFocus = false } = options;
+
+	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]);
+};

package/dist/utils/utils/useWindowSize.js

@@ -0,0 +1,26 @@
+import { useState, useEffect } from 'react';
+
+export const useWindowSize = () => {
+	// Initialize state with undefined width/height so server and client renders match
+	const [windowSize, setWindowSize] = useState({
+		width: undefined,
+		height: undefined,
+	});
+	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;
+};

package/dist/utils/utils/validation.js

@@ -0,0 +1,131 @@
+/**
+ * Validation utilities for form inputs
+ * Contains common validation patterns and functions
+ */
+
+// Common email validation regex pattern
+// This pattern checks for basic email format: user@domain.extension
+export const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// More comprehensive email regex (RFC 5322 compliant, simplified)
+export const EMAIL_REGEX_STRICT =
+	/^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+
+// Common validation patterns
+export const VALIDATION_PATTERNS = {
+	email: EMAIL_REGEX,
+	phone: /^[\+]?[1-9][\d]{0,15}$/,
+	url: /^https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_\+.~#?&//=]*)$/,
+	postalCode: /^[A-Za-z0-9\s-]{3,10}$/,
+	creditCard: /^[0-9]{13,19}$/,
+	strongPassword:
+		/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]{8,}$/,
+};
+
+/**
+ * Validates an email address
+ * @param {string} email - The email address to validate
+ * @param {boolean} strict - Whether to use strict RFC 5322 validation
+ * @returns {boolean} - True if email is valid
+ */
+export const validateEmail = (email, strict = false) => {
+	if (!email || typeof email !== 'string') {
+		return false;
+	}
+	const pattern = strict ? EMAIL_REGEX_STRICT : EMAIL_REGEX;
+	return pattern.test(email.trim());
+};
+
+/**
+ * Validates a phone number
+ * @param {string} phone - The phone number to validate
+ * @returns {boolean} - True if phone is valid
+ */
+export const validatePhone = (phone) => {
+	if (!phone || typeof phone !== 'string') {
+		return false;
+	}
+	return VALIDATION_PATTERNS.phone.test(phone.replace(/[\s\-\(\)]/g, ''));
+};
+
+/**
+ * Validates a URL
+ * @param {string} url - The URL to validate
+ * @returns {boolean} - True if URL is valid
+ */
+export const validateUrl = (url) => {
+	if (!url || typeof url !== 'string') {
+		return false;
+	}
+	return VALIDATION_PATTERNS.url.test(url.trim());
+};
+
+/**
+ * Validates password strength
+ * @param {string} password - The password to validate
+ * @returns {boolean} - True if password meets strength requirements
+ */
+export const validatePasswordStrength = (password) => {
+	if (!password || typeof password !== 'string') {
+		return false;
+	}
+	return VALIDATION_PATTERNS.strongPassword.test(password);
+};
+
+/**
+ * Generic field validation function
+ * @param {string} value - The value to validate
+ * @param {Object} rules - Validation rules object
+ * @param {string} fieldName - Name of the field for error messages
+ * @returns {string|null} - Error message or null if valid
+ */
+export const validateField = (value, rules, fieldName) => {
+	if (!rules) return null;
+
+	// Required validation
+	if (rules.required && (!value || value.trim() === '')) {
+		return `${fieldName} is required`;
+	}
+
+	// Skip other validations if field is empty and not required
+	if (!value || value.trim() === '') {
+		return null;
+	}
+
+	// Email validation
+	if (rules.email && !validateEmail(value, rules.strict)) {
+		return 'Please enter a valid email address';
+	}
+
+	// Phone validation
+	if (rules.phone && !validatePhone(value)) {
+		return 'Please enter a valid phone number';
+	}
+
+	// URL validation
+	if (rules.url && !validateUrl(value)) {
+		return 'Please enter a valid URL';
+	}
+
+	// Password strength validation
+	if (rules.strongPassword && !validatePasswordStrength(value)) {
+		return 'Password must contain at least 8 characters with uppercase, lowercase, number, and special character';
+	}
+
+	// Minimum length validation
+	if (rules.minLength && value.length < rules.minLength) {
+		return `${fieldName} must be at least ${rules.minLength} characters`;
+	}
+
+	// Maximum length validation
+	if (rules.maxLength && value.length > rules.maxLength) {
+		return `${fieldName} must not exceed ${rules.maxLength} characters`;
+	}
+
+	// Pattern validation
+	if (rules.pattern && !rules.pattern.test(value)) {
+		return rules.patternMessage || `${fieldName} format is invalid`;
+	}
+
+	return null;
+};