@abstraks-dev/ui-library 1.0.1

package/dist/utils/utils/labelUtils.js

@@ -0,0 +1,772 @@
+/**
+ * Label Component Utilities
+ * Provides helper functions and hooks for Label component functionality
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+
+/**
+ * Counter for generating unique IDs
+ */
+let idCounter = 0;
+
+/**
+ * Generates a robust unique ID using a combination of counter and timestamp
+ * @param {string} prefix - Optional prefix for the ID
+ * @returns {string} Unique ID
+ */
+const generateUniqueId = (prefix = 'id') => {
+	return `${prefix}-${++idCounter}-${Date.now().toString(36)}${Math.random()
+		.toString(36)
+		.substr(2, 4)}`;
+};
+
+/**
+ * Generates a UUID v4 compatible ID (simplified version)
+ * @returns {string} UUID-like string
+ */
+const generateUUID = () => {
+	return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+		const r = (Math.random() * 16) | 0;
+		const v = c === 'x' ? r : (r & 0x3) | 0x8;
+		return v.toString(16);
+	});
+};
+
+/**
+ * Singleton live region manager for screen reader announcements
+ */
+class LiveRegionManager {
+	constructor() {
+		this.liveRegion = null;
+		this.referenceCount = 0;
+		this.announcementQueue = [];
+		this.isProcessing = false;
+	}
+
+	/**
+	 * Creates or returns existing live region
+	 * @returns {HTMLElement} Live region element
+	 */
+	getLiveRegion() {
+		if (!this.liveRegion) {
+			this.liveRegion = document.createElement('div');
+			this.liveRegion.setAttribute('aria-live', 'assertive');
+			this.liveRegion.setAttribute('aria-atomic', 'true');
+			this.liveRegion.className = 'sr-only';
+			this.liveRegion.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(this.liveRegion);
+		}
+		return this.liveRegion;
+	}
+
+	/**
+	 * Increment reference count and return live region
+	 * @returns {HTMLElement} Live region element
+	 */
+	addReference() {
+		this.referenceCount++;
+		return this.getLiveRegion();
+	}
+
+	/**
+	 * Decrement reference count and cleanup if no references remain
+	 */
+	removeReference() {
+		this.referenceCount--;
+		if (this.referenceCount <= 0 && this.liveRegion) {
+			if (document.body.contains(this.liveRegion)) {
+				document.body.removeChild(this.liveRegion);
+			}
+			this.liveRegion = null;
+			this.referenceCount = 0;
+			this.announcementQueue = [];
+		}
+	}
+
+	/**
+	 * Announce text to screen readers with queuing to prevent conflicts
+	 * @param {string} text - Text to announce
+	 */
+	async announce(text) {
+		if (!text) return;
+
+		this.announcementQueue.push(text);
+
+		if (!this.isProcessing) {
+			this.isProcessing = true;
+			await this.processQueue();
+		}
+	}
+
+	/**
+	 * Process announcement queue to prevent conflicts
+	 */
+	async processQueue() {
+		while (this.announcementQueue.length > 0) {
+			const text = this.announcementQueue.shift();
+			const liveRegion = this.getLiveRegion();
+
+			// Clear previous announcement
+			liveRegion.textContent = '';
+
+			// Small delay to ensure screen reader picks up the change
+			await new Promise((resolve) => setTimeout(resolve, 10));
+
+			// Set new announcement
+			liveRegion.textContent = text;
+
+			// Wait before processing next announcement
+			await new Promise((resolve) => setTimeout(resolve, 100));
+		}
+		this.isProcessing = false;
+	}
+
+	/**
+	 * Get current reference count (useful for debugging)
+	 * @returns {number} Current reference count
+	 */
+	getReferenceCount() {
+		return this.referenceCount;
+	}
+}
+
+// Singleton instance
+const liveRegionManager = new LiveRegionManager();
+
+/**
+ * Hook for managing form field validation states
+ * @param {Object} options - Configuration options
+ * @param {boolean} options.required - Whether the field is required
+ * @param {Function} options.validator - Custom validation function
+ * @param {string} options.initialValue - Initial field value
+ * @returns {Object} Validation state and handlers
+ */
+export const useFieldValidation = ({
+	required = false,
+	validator = null,
+	initialValue = '',
+} = {}) => {
+	const [value, setValue] = useState(initialValue);
+	const [validationState, setValidationState] = useState('default');
+	const [errorText, setErrorText] = useState('');
+	const [successText, setSuccessText] = useState('');
+	const [touched, setTouched] = useState(false);
+
+	const validate = useCallback(
+		(inputValue) => {
+			// Required validation
+			if (required && (!inputValue || inputValue.trim() === '')) {
+				return {
+					state: 'error',
+					errorText: 'This field is required',
+					successText: '',
+				};
+			}
+
+			// Custom validation
+			if (validator && inputValue) {
+				const result = validator(inputValue);
+				if (result.isValid === false) {
+					return {
+						state: 'error',
+						errorText: result.message || 'Invalid input',
+						successText: '',
+					};
+				}
+				if (result.isValid === true) {
+					return {
+						state: 'success',
+						errorText: '',
+						successText: result.message || 'Valid input',
+					};
+				}
+			}
+
+			// Default state for valid input
+			if (inputValue && inputValue.trim() !== '') {
+				return {
+					state: 'success',
+					errorText: '',
+					successText: '',
+				};
+			}
+
+			return {
+				state: 'default',
+				errorText: '',
+				successText: '',
+			};
+		},
+		[required, validator]
+	);
+
+	const handleChange = (newValue) => {
+		setValue(newValue);
+		if (touched) {
+			const validation = validate(newValue);
+			setValidationState(validation.state);
+			setErrorText(validation.errorText);
+			setSuccessText(validation.successText);
+		}
+	};
+
+	const handleBlur = () => {
+		setTouched(true);
+		const validation = validate(value);
+		setValidationState(validation.state);
+		setErrorText(validation.errorText);
+		setSuccessText(validation.successText);
+	};
+
+	const reset = () => {
+		setValue(initialValue);
+		setValidationState('default');
+		setErrorText('');
+		setSuccessText('');
+		setTouched(false);
+	};
+
+	return {
+		value,
+		validationState,
+		errorText,
+		successText,
+		touched,
+		handleChange,
+		handleBlur,
+		reset,
+		isValid:
+			validationState === 'success' ||
+			(validationState === 'default' && (!required || value)),
+	};
+};
+
+/**
+ * Hook to manage label accessibility attributes
+ * @param {Object} options - Configuration options
+ * @returns {Object} Accessibility props and handlers
+ */
+export const useLabelAccessibility = ({
+	labelId = '',
+	inputId = '',
+	helpText = '',
+	errorText = '',
+	successText = '',
+	required = false,
+} = {}) => {
+	const [announceText, setAnnounceText] = useState('');
+	const previousErrorRef = useRef('');
+	const liveRegionRef = useRef(null);
+
+	// Generate unique IDs if not provided
+	const generatedLabelId = labelId || generateUniqueId('label');
+	const generatedInputId = inputId || generateUniqueId('input');
+
+	const helpId = helpText ? `${generatedInputId}-help` : '';
+	const errorId = errorText ? `${generatedInputId}-error` : '';
+	const successId = successText ? `${generatedInputId}-success` : '';
+
+	// Build aria-describedby
+	const ariaDescribedBy =
+		[helpId, errorId, successId].filter(Boolean).join(' ') || undefined;
+
+	// Handle error announcements
+	useEffect(() => {
+		if (errorText && errorText !== previousErrorRef.current) {
+			setAnnounceText(errorText);
+			previousErrorRef.current = errorText;
+		} else if (!errorText && previousErrorRef.current) {
+			setAnnounceText('');
+			previousErrorRef.current = '';
+		}
+	}, [errorText]);
+
+	// Manage live region reference and announcements
+	useEffect(() => {
+		// Add reference to live region manager on mount
+		liveRegionRef.current = liveRegionManager.addReference();
+
+		return () => {
+			// Remove reference on unmount
+			liveRegionManager.removeReference();
+			liveRegionRef.current = null;
+		};
+	}, []);
+
+	// Handle announcements
+	useEffect(() => {
+		if (announceText) {
+			liveRegionManager.announce(announceText);
+		}
+	}, [announceText]);
+
+	return {
+		labelProps: {
+			id: generatedLabelId,
+			htmlFor: generatedInputId,
+		},
+		inputProps: {
+			id: generatedInputId,
+			'aria-describedby': ariaDescribedBy,
+			'aria-required': required ? 'true' : undefined,
+			'aria-invalid': errorText ? 'true' : undefined,
+		},
+		helpProps: helpText ? { id: helpId } : {},
+		errorProps: errorText ? { id: errorId, role: 'alert' } : {},
+		successProps: successText ? { id: successId, role: 'status' } : {},
+	};
+};
+
+/**
+ * Common validation functions for form fields
+ */
+export const validators = {
+	/**
+	 * Email validation
+	 */
+	email: (value) => {
+		const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+		return {
+			isValid: emailRegex.test(value),
+			message: emailRegex.test(value)
+				? 'Valid email address'
+				: 'Please enter a valid email address',
+		};
+	},
+
+	/**
+	 * Password validation (minimum 8 characters, mixed case, number)
+	 */
+	password: (value) => {
+		const hasMinLength = value.length >= 8;
+		const hasLowerCase = /[a-z]/.test(value);
+		const hasUpperCase = /[A-Z]/.test(value);
+		const hasNumber = /\d/.test(value);
+
+		const isValid = hasMinLength && hasLowerCase && hasUpperCase && hasNumber;
+
+		let message = '';
+		if (!isValid) {
+			const missing = [];
+			if (!hasMinLength) missing.push('at least 8 characters');
+			if (!hasLowerCase) missing.push('lowercase letter');
+			if (!hasUpperCase) missing.push('uppercase letter');
+			if (!hasNumber) missing.push('number');
+			message = `Password must contain ${missing.join(', ')}`;
+		} else {
+			message = 'Strong password';
+		}
+
+		return { isValid, message };
+	},
+
+	/**
+	 * Phone number validation (US format)
+	 */
+	phone: (value) => {
+		const phoneRegex = /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/;
+		return {
+			isValid: phoneRegex.test(value),
+			message: phoneRegex.test(value)
+				? 'Valid phone number'
+				: 'Please enter a valid phone number (e.g., 555-123-4567)',
+		};
+	},
+
+	/**
+	 * URL validation
+	 */
+	url: (value) => {
+		try {
+			new URL(value);
+			return { isValid: true, message: 'Valid URL' };
+		} catch {
+			return {
+				isValid: false,
+				message: 'Please enter a valid URL (e.g., https://example.com)',
+			};
+		}
+	},
+
+	/**
+	 * Minimum length validation
+	 */
+	minLength: (min) => (value) => {
+		const isValid = value.length >= min;
+		return {
+			isValid,
+			message: isValid
+				? `Meets minimum length requirement`
+				: `Must be at least ${min} characters`,
+		};
+	},
+
+	/**
+	 * Maximum length validation
+	 */
+	maxLength: (max) => (value) => {
+		const isValid = value.length <= max;
+		return {
+			isValid,
+			message: isValid
+				? `Within length limit`
+				: `Must be no more than ${max} characters`,
+		};
+	},
+
+	/**
+	 * Custom regex validation
+	 */
+	regex: (pattern, message) => (value) => {
+		const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+		const isValid = regex.test(value);
+		return {
+			isValid,
+			message: isValid ? 'Valid format' : message || 'Invalid format',
+		};
+	},
+};
+
+/**
+ * Hook for managing form validation state across multiple fields
+ * @param {Object} fields - Field configuration object
+ * @returns {Object} Form state and handlers
+ */
+export const useFormValidation = (fields = {}) => {
+	const [formState, setFormState] = useState({});
+	const [isSubmitting, setIsSubmitting] = useState(false);
+	const [submitError, setSubmitError] = useState('');
+
+	// Initialize form state
+	useEffect(() => {
+		const initialState = {};
+		Object.keys(fields).forEach((fieldName) => {
+			initialState[fieldName] = {
+				value: fields[fieldName].initialValue || '',
+				validationState: 'default',
+				errorText: '',
+				successText: '',
+				touched: false,
+			};
+		});
+		setFormState(initialState);
+	}, [fields]);
+
+	const updateField = (fieldName, updates) => {
+		setFormState((prev) => ({
+			...prev,
+			[fieldName]: {
+				...prev[fieldName],
+				...updates,
+			},
+		}));
+	};
+
+	const validateField = (fieldName, value) => {
+		const fieldConfig = fields[fieldName];
+		if (!fieldConfig)
+			return { state: 'default', errorText: '', successText: '' };
+
+		// Required validation
+		if (fieldConfig.required && (!value || value.trim() === '')) {
+			return {
+				state: 'error',
+				errorText: fieldConfig.requiredMessage || 'This field is required',
+				successText: '',
+			};
+		}
+
+		// Custom validation
+		if (fieldConfig.validator && value) {
+			const result = fieldConfig.validator(value);
+			if (result.isValid === false) {
+				return {
+					state: 'error',
+					errorText: result.message || 'Invalid input',
+					successText: '',
+				};
+			}
+			if (result.isValid === true) {
+				return {
+					state: 'success',
+					errorText: '',
+					successText: result.message || '',
+				};
+			}
+		}
+
+		return {
+			state: value ? 'success' : 'default',
+			errorText: '',
+			successText: '',
+		};
+	};
+
+	const handleFieldChange = (fieldName, value) => {
+		const validation = validateField(fieldName, value);
+		updateField(fieldName, {
+			value,
+			validationState: formState[fieldName]?.touched
+				? validation.state
+				: 'default',
+			errorText: formState[fieldName]?.touched ? validation.errorText : '',
+			successText: formState[fieldName]?.touched ? validation.successText : '',
+		});
+	};
+
+	const handleFieldBlur = (fieldName) => {
+		const value = formState[fieldName]?.value || '';
+		const validation = validateField(fieldName, value);
+		updateField(fieldName, {
+			touched: true,
+			validationState: validation.state,
+			errorText: validation.errorText,
+			successText: validation.successText,
+		});
+	};
+
+	const validateForm = () => {
+		let isValid = true;
+		const newFormState = { ...formState };
+
+		Object.keys(fields).forEach((fieldName) => {
+			const value = formState[fieldName]?.value || '';
+			const validation = validateField(fieldName, value);
+
+			newFormState[fieldName] = {
+				...newFormState[fieldName],
+				touched: true,
+				validationState: validation.state,
+				errorText: validation.errorText,
+				successText: validation.successText,
+			};
+
+			if (validation.state === 'error') {
+				isValid = false;
+			}
+		});
+
+		setFormState(newFormState);
+		return isValid;
+	};
+
+	const handleSubmit = async (onSubmit) => {
+		setIsSubmitting(true);
+		setSubmitError('');
+
+		const isValid = validateForm();
+
+		if (isValid) {
+			try {
+				const formData = {};
+				Object.keys(formState).forEach((fieldName) => {
+					formData[fieldName] = formState[fieldName].value;
+				});
+				await onSubmit(formData);
+			} catch (error) {
+				setSubmitError(
+					error.message || 'An error occurred while submitting the form'
+				);
+			}
+		}
+
+		setIsSubmitting(false);
+	};
+
+	const resetForm = () => {
+		const resetState = {};
+		Object.keys(fields).forEach((fieldName) => {
+			resetState[fieldName] = {
+				value: fields[fieldName].initialValue || '',
+				validationState: 'default',
+				errorText: '',
+				successText: '',
+				touched: false,
+			};
+		});
+		setFormState(resetState);
+		setSubmitError('');
+	};
+
+	return {
+		formState,
+		isSubmitting,
+		submitError,
+		handleFieldChange,
+		handleFieldBlur,
+		handleSubmit,
+		resetForm,
+		isFormValid: Object.values(formState).every(
+			(field) =>
+				field.validationState === 'success' ||
+				(field.validationState === 'default' &&
+					!fields[
+						Object.keys(formState).find((key) => formState[key] === field)
+					]?.required)
+		),
+	};
+};
+
+/**
+ * Accessibility testing utilities for labels
+ */
+export const labelTestingUtils = {
+	/**
+	 * Validates label-input associations
+	 */
+	validateLabelAssociations() {
+		const labels = document.querySelectorAll('label[for]');
+		const results = [];
+
+		labels.forEach((label) => {
+			const forValue = label.getAttribute('for');
+			const associatedInput = document.getElementById(forValue);
+
+			results.push({
+				labelText: label.textContent?.trim(),
+				forAttribute: forValue,
+				hasAssociatedInput: !!associatedInput,
+				inputType: associatedInput?.type || 'N/A',
+				hasAriaDescribedBy: !!associatedInput?.getAttribute('aria-describedby'),
+				isValid: !!associatedInput,
+			});
+		});
+
+		return results;
+	},
+
+	/**
+	 * Checks for proper required field indicators
+	 */
+	validateRequiredFields() {
+		const requiredInputs = document.querySelectorAll(
+			'input[required], select[required], textarea[required]'
+		);
+		const results = [];
+
+		requiredInputs.forEach((input) => {
+			const id = input.id;
+			const label = document.querySelector(`label[for="${id}"]`);
+			const hasVisualIndicator =
+				label?.textContent?.includes('*') ||
+				label?.querySelector('.required, .label__required');
+			const hasAriaRequired = input.getAttribute('aria-required') === 'true';
+
+			results.push({
+				inputId: id,
+				inputType: input.type,
+				hasLabel: !!label,
+				hasVisualIndicator,
+				hasAriaRequired,
+				labelText: label?.textContent?.trim() || 'No label',
+				isAccessible: hasVisualIndicator && hasAriaRequired,
+			});
+		});
+
+		return results;
+	},
+
+	/**
+	 * Tests validation message accessibility
+	 */
+	validateErrorMessages() {
+		const errorMessages = document.querySelectorAll(
+			'[role="alert"], .label__message--error'
+		);
+		const results = [];
+
+		errorMessages.forEach((message) => {
+			const id = message.id;
+			const referencingInputs = document.querySelectorAll(
+				`[aria-describedby*="${id}"]`
+			);
+
+			results.push({
+				messageId: id,
+				messageText: message.textContent?.trim(),
+				hasRole: message.getAttribute('role') === 'alert',
+				hasAriaLive: !!message.getAttribute('aria-live'),
+				isReferencedByInput: referencingInputs.length > 0,
+				referencingInputCount: referencingInputs.length,
+			});
+		});
+
+		return results;
+	},
+
+	/**
+	 * Simulates keyboard navigation through form labels
+	 */
+	async simulateKeyboardNavigation() {
+		const labels = document.querySelectorAll('label');
+		const results = [];
+
+		for (let label of labels) {
+			// Simulate click on label
+			label.click();
+
+			const forValue = label.getAttribute('for');
+			const associatedInput = document.getElementById(forValue);
+			const isFocused = document.activeElement === associatedInput;
+
+			results.push({
+				labelText: label.textContent?.trim(),
+				forAttribute: forValue,
+				clickFocusesInput: isFocused,
+				focusedElementId: document.activeElement?.id || 'none',
+				isAccessible: isFocused,
+			});
+
+			// Small delay for real-world simulation
+			await new Promise((resolve) => setTimeout(resolve, 50));
+		}
+
+		return results;
+	},
+
+	/**
+	 * Checks color contrast ratios for labels
+	 */
+	checkColorContrast() {
+		const labels = document.querySelectorAll('label, .label__message');
+		const results = [];
+
+		labels.forEach((label) => {
+			const styles = window.getComputedStyle(label);
+			const color = styles.color;
+			const backgroundColor = styles.backgroundColor;
+
+			// Note: Actual contrast calculation would require a color library
+			// This is a simplified check
+			results.push({
+				element: label.tagName,
+				className: label.className,
+				color,
+				backgroundColor,
+				// In a real implementation, calculate actual contrast ratio
+				contrastNote: 'Manual contrast checking required',
+			});
+		});
+
+		return results;
+	},
+};
+
+export default {
+	useFieldValidation,
+	useLabelAccessibility,
+	useFormValidation,
+	validators,
+	labelTestingUtils,
+};