@abstraks-dev/ui-library 1.0.1

package/dist/utils/utils/useSelectAccessibility.js

@@ -0,0 +1,498 @@
+import { useState, useCallback, useEffect } from 'react';
+
+/**
+ * Custom hook for managing select state with accessibility features
+ * Provides controlled state management for select inputs with validation
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} options.name - Name for the select input (required)
+ * @param {string|Array} options.defaultValue - Default selected value(s)
+ * @param {boolean} options.multiple - Whether multiple selection is allowed
+ * @param {boolean} options.required - Whether selection is required
+ * @param {Function} options.onChange - Change callback function
+ * @param {Function} options.onValidate - Custom validation function
+ * @returns {Object} Select state and handlers
+ */
+export const useSelectAccessibility = (options = {}) => {
+	const {
+		name,
+		defaultValue = '',
+		multiple = false,
+		required = false,
+		onChange,
+		onValidate,
+	} = options;
+
+	const [selectedValue, setSelectedValue] = useState(defaultValue);
+	const [hasError, setHasError] = useState(false);
+	const [errorMessage, setErrorMessage] = useState('');
+	const [touched, setTouched] = useState(false);
+	const [isFocused, setIsFocused] = useState(false);
+
+	// Handle select value change
+	const handleChange = useCallback(
+		(event) => {
+			const value = multiple
+				? Array.from(event.target.selectedOptions, (option) => option.value)
+				: event.target.value;
+
+			setSelectedValue(value);
+			setTouched(true);
+
+			// Clear error when user makes a selection
+			if (hasError && value && (multiple ? value.length > 0 : value !== '')) {
+				setHasError(false);
+				setErrorMessage('');
+			}
+
+			// Call external onChange if provided
+			onChange?.(event, value);
+		},
+		[hasError, multiple, onChange]
+	);
+
+	// Handle focus events
+	const handleFocus = useCallback((event) => {
+		setIsFocused(true);
+	}, []);
+
+	// Handle blur events
+	const handleBlur = useCallback((event) => {
+		setIsFocused(false);
+		setTouched(true);
+	}, []);
+
+	// Validate the current selection
+	const validate = useCallback(() => {
+		let isValid = true;
+		let message = '';
+
+		// Required field validation
+		if (required) {
+			const isEmpty = multiple
+				? !selectedValue || selectedValue.length === 0
+				: !selectedValue || selectedValue === '';
+
+			if (isEmpty) {
+				isValid = false;
+				message = 'Please select an option.';
+			}
+		}
+
+		// Custom validation
+		if (onValidate && selectedValue) {
+			const customValidation = onValidate(selectedValue);
+			if (customValidation !== true) {
+				isValid = false;
+				message = customValidation || 'Invalid selection.';
+			}
+		}
+
+		setHasError(!isValid);
+		setErrorMessage(message);
+		return isValid;
+	}, [required, selectedValue, onValidate, multiple]);
+
+	// Reset the select state
+	const reset = useCallback(() => {
+		setSelectedValue(defaultValue);
+		setHasError(false);
+		setErrorMessage('');
+		setTouched(false);
+		setIsFocused(false);
+	}, [defaultValue]);
+
+	// Set value programmatically
+	const setValue = useCallback(
+		(value) => {
+			setSelectedValue(value);
+			setTouched(true);
+			if (hasError) {
+				setHasError(false);
+				setErrorMessage('');
+			}
+		},
+		[hasError]
+	);
+
+	// Get props for the select element
+	const getSelectProps = useCallback(
+		() => ({
+			name,
+			value: selectedValue,
+			onChange: handleChange,
+			onFocus: handleFocus,
+			onBlur: handleBlur,
+			error: hasError,
+			errorText: hasError ? errorMessage : '',
+			'data-select-name': name,
+		}),
+		[
+			name,
+			selectedValue,
+			handleChange,
+			handleFocus,
+			handleBlur,
+			hasError,
+			errorMessage,
+		]
+	);
+
+	return {
+		// State
+		selectedValue,
+		hasError,
+		errorMessage,
+		touched,
+		isFocused,
+		isValid: !hasError,
+
+		// Handlers
+		handleChange,
+		handleFocus,
+		handleBlur,
+		validate,
+		reset,
+		setValue,
+		getSelectProps,
+	};
+};
+
+/**
+ * Utility for managing keyboard navigation within select dropdowns
+ * Implements proper arrow key navigation and accessibility features
+ *
+ * @param {HTMLElement} selectElement - The select element
+ * @param {Object} options - Navigation options
+ * @param {Function} options.onNavigate - Optional callback when navigation occurs
+ * @returns {Object} Navigation utilities
+ */
+export const useSelectKeyboardNavigation = (selectElement, options = {}) => {
+	const { onNavigate } = options;
+
+	const getOptions = useCallback(() => {
+		if (!selectElement) return [];
+		return Array.from(selectElement.options).filter(
+			(option) => !option.disabled
+		);
+	}, [selectElement]);
+
+	const handleKeyDown = useCallback(
+		(event) => {
+			if (!selectElement) return;
+
+			const options = getOptions();
+			if (options.length === 0) return;
+
+			const currentIndex = selectElement.selectedIndex;
+			let nextIndex = currentIndex;
+
+			switch (event.key) {
+				case 'ArrowUp':
+					event.preventDefault();
+					nextIndex = currentIndex > 0 ? currentIndex - 1 : options.length - 1;
+					break;
+				case 'ArrowDown':
+					event.preventDefault();
+					nextIndex = currentIndex < options.length - 1 ? currentIndex + 1 : 0;
+					break;
+				case 'Home':
+					event.preventDefault();
+					nextIndex = 0;
+					break;
+				case 'End':
+					event.preventDefault();
+					nextIndex = options.length - 1;
+					break;
+				default:
+					return;
+			}
+
+			if (nextIndex !== currentIndex) {
+				selectElement.selectedIndex = nextIndex;
+				selectElement.dispatchEvent(new Event('change', { bubbles: true }));
+				onNavigate?.(options[nextIndex].value, nextIndex);
+			}
+		},
+		[selectElement, getOptions, onNavigate]
+	);
+
+	const focusFirst = useCallback(() => {
+		if (!selectElement) return;
+		const options = getOptions();
+		if (options.length > 0) {
+			selectElement.selectedIndex = 0;
+			selectElement.focus();
+		}
+	}, [selectElement, getOptions]);
+
+	const focusLast = useCallback(() => {
+		if (!selectElement) return;
+		const options = getOptions();
+		if (options.length > 0) {
+			selectElement.selectedIndex = options.length - 1;
+			selectElement.focus();
+		}
+	}, [selectElement, getOptions]);
+
+	return {
+		handleKeyDown,
+		focusFirst,
+		focusLast,
+		getOptions,
+	};
+};
+
+/**
+ * Validates proper labeling for select elements
+ * @param {HTMLElement} selectElement - The select element to validate
+ * @returns {Object} Validation results for labeling
+ */
+const validateSelectLabeling = (selectElement) => {
+	const results = { errors: [], warnings: [] };
+
+	// Check for proper labeling
+	const label =
+		selectElement.closest('label') ||
+		document.querySelector(`label[for="${selectElement.id}"]`);
+	const ariaLabel = selectElement.getAttribute('aria-label');
+	const ariaLabelledBy = selectElement.getAttribute('aria-labelledby');
+
+	if (!label && !ariaLabel && !ariaLabelledBy) {
+		results.errors.push('Select element must have an accessible label');
+	}
+
+	// Check for name attribute
+	if (!selectElement.name) {
+		results.warnings.push(
+			'Select element should have a name attribute for form submission'
+		);
+	}
+
+	return results;
+};
+
+/**
+ * Validates select options for accessibility
+ * @param {HTMLElement} selectElement - The select element to validate
+ * @returns {Object} Validation results for options
+ */
+const validateSelectOptions = (selectElement) => {
+	const results = { errors: [], warnings: [], info: [] };
+
+	// Check for options
+	const options = Array.from(selectElement.options);
+	if (options.length === 0) {
+		results.errors.push('Select element must have at least one option');
+		return results;
+	}
+
+	// Check for unique values
+	const values = options.map((option) => option.value);
+	const uniqueValues = [...new Set(values)];
+	if (values.length !== uniqueValues.length) {
+		results.warnings.push('Select options should have unique values');
+	}
+
+	// Check for accessible option text
+	options.forEach((option, index) => {
+		if (!option.textContent.trim()) {
+			results.warnings.push(
+				`Option ${index + 1} should have descriptive text content`
+			);
+		}
+	});
+
+	results.info.push(
+		`Found ${options.length} options (${
+			options.filter((o) => !o.disabled).length
+		} enabled)`
+	);
+
+	return results;
+};
+
+/**
+ * Validates ARIA attributes for select elements
+ * @param {HTMLElement} selectElement - The select element to validate
+ * @returns {Object} Validation results for ARIA attributes
+ */
+const validateSelectARIA = (selectElement) => {
+	const results = { warnings: [] };
+
+	// Check ARIA attributes
+	if (selectElement.hasAttribute('aria-invalid')) {
+		const ariaInvalid = selectElement.getAttribute('aria-invalid');
+		if (ariaInvalid === 'true') {
+			const describedBy = selectElement.getAttribute('aria-describedby');
+			if (!describedBy) {
+				results.warnings.push(
+					'Select with aria-invalid="true" should have aria-describedby pointing to error message'
+				);
+			}
+		}
+	}
+
+	return results;
+};
+
+/**
+ * Validates select element states and special attributes
+ * @param {HTMLElement} selectElement - The select element to validate
+ * @returns {Object} Validation results for element states
+ */
+const validateSelectStates = (selectElement) => {
+	const results = { warnings: [], info: [] };
+
+	// Check for multiple select considerations
+	if (selectElement.multiple) {
+		results.info.push(
+			'Multiple select detected - ensure users understand multiple selection is possible'
+		);
+
+		if (!selectElement.hasAttribute('size') || selectElement.size < 4) {
+			results.warnings.push(
+				'Multiple selects should show multiple options (size >= 4) for better usability'
+			);
+		}
+	}
+
+	// Check required attribute
+	if (selectElement.required) {
+		results.info.push(
+			'Required select detected - ensure form validation provides clear feedback'
+		);
+	}
+
+	// Check disabled state
+	if (selectElement.disabled) {
+		results.info.push(
+			"Disabled select detected - ensure users understand why it's disabled"
+		);
+	}
+
+	return results;
+};
+
+/**
+ * Accessibility testing utility for select elements
+ * Validates proper ARIA attributes and keyboard navigation
+ *
+ * @param {HTMLElement} selectElement - The select element to test
+ * @returns {Object} Test results
+ */
+export const validateSelectAccessibility = (selectElement) => {
+	const results = {
+		passed: true,
+		errors: [],
+		warnings: [],
+		info: [],
+	};
+
+	if (!selectElement) {
+		results.passed = false;
+		results.errors.push('No select element provided for testing');
+		return results;
+	}
+
+	// Validate different aspects of accessibility
+	const labelingResults = validateSelectLabeling(selectElement);
+	const optionsResults = validateSelectOptions(selectElement);
+	const ariaResults = validateSelectARIA(selectElement);
+	const statesResults = validateSelectStates(selectElement);
+
+	// Combine all results
+	results.errors = [...labelingResults.errors, ...optionsResults.errors];
+
+	results.warnings = [
+		...labelingResults.warnings,
+		...optionsResults.warnings,
+		...ariaResults.warnings,
+		...statesResults.warnings,
+	];
+
+	results.info = [...optionsResults.info, ...statesResults.info];
+
+	// Set overall pass/fail status
+	results.passed = results.errors.length === 0;
+
+	return results;
+};
+
+/**
+ * Utility for enhancing select accessibility with live regions
+ * Provides screen reader announcements for select changes
+ *
+ * @param {HTMLElement} selectElement - The select element
+ * @param {Object} options - Configuration options
+ * @returns {Object} Live region utilities
+ */
+export const useSelectLiveRegion = (selectElement, options = {}) => {
+	const {
+		enableSelectionAnnouncement = true,
+		enableOptionsAnnouncement = false,
+		customMessages = {},
+	} = options;
+
+	const [liveRegion, setLiveRegion] = useState(null);
+
+	// Create live region for announcements
+	useEffect(() => {
+		const region = document.createElement('div');
+		region.setAttribute('aria-live', 'polite');
+		region.setAttribute('aria-atomic', 'true');
+		region.style.position = 'absolute';
+		region.style.left = '-10000px';
+		region.style.top = 'auto';
+		region.style.width = '1px';
+		region.style.height = '1px';
+		region.style.overflow = 'hidden';
+
+		document.body.appendChild(region);
+		setLiveRegion(region);
+
+		return () => {
+			if (document.body.contains(region)) {
+				document.body.removeChild(region);
+			}
+		};
+	}, []);
+
+	const announce = useCallback(
+		(message) => {
+			if (liveRegion) {
+				liveRegion.textContent = message;
+			}
+		},
+		[liveRegion]
+	);
+
+	const announceSelection = useCallback(
+		(selectedOption) => {
+			if (!enableSelectionAnnouncement || !selectedOption) return;
+
+			const message =
+				customMessages.selection || `Selected: ${selectedOption.textContent}`;
+			announce(message);
+		},
+		[announce, enableSelectionAnnouncement, customMessages.selection]
+	);
+
+	const announceOptionsCount = useCallback(
+		(count) => {
+			if (!enableOptionsAnnouncement) return;
+
+			const message =
+				customMessages.optionsCount || `${count} options available`;
+			announce(message);
+		},
+		[announce, enableOptionsAnnouncement, customMessages.optionsCount]
+	);
+
+	return {
+		announce,
+		announceSelection,
+		announceOptionsCount,
+		liveRegion,
+	};
+};