@abstraks-dev/ui-library 1.0.1

package/dist/utils/utils/useHeadingAccessibility.js

@@ -0,0 +1,334 @@
+import { useEffect, useRef, useState, createContext, useContext } from 'react';
+
+// Context for tracking heading hierarchy across components
+const HeadingHierarchyContext = createContext({
+	registeredHeadings: [],
+	registerHeading: () => {},
+	unregisterHeading: () => {},
+});
+
+/**
+ * Provider component for heading hierarchy context
+ * Allows automatic tracking of heading levels across multiple components
+ *
+ * @param {Object} props - Component props
+ * @param {React.ReactNode} props.children - Child components
+ * @returns {JSX.Element} Context provider
+ *
+ * @example
+ * <HeadingHierarchyProvider>
+ *   <YourApp />
+ * </HeadingHierarchyProvider>
+ */
+export const HeadingHierarchyProvider = ({ children }) => {
+	const [registeredHeadings, setRegisteredHeadings] = useState([]);
+
+	const registerHeading = (id, level) => {
+		setRegisteredHeadings((prev) => {
+			const existing = prev.find((h) => h.id === id);
+			if (existing) {
+				return prev.map((h) => (h.id === id ? { ...h, level } : h));
+			}
+			return [...prev, { id, level, timestamp: Date.now() }];
+		});
+	};
+
+	const unregisterHeading = (id) => {
+		setRegisteredHeadings((prev) => prev.filter((h) => h.id !== id));
+	};
+
+	const value = {
+		registeredHeadings,
+		registerHeading,
+		unregisterHeading,
+	};
+
+	return (
+		<HeadingHierarchyContext.Provider value={value}>
+			{children}
+		</HeadingHierarchyContext.Provider>
+	);
+};
+
+/**
+ * Custom hook for enhanced heading accessibility features
+ *
+ * @param {Object} options - Configuration options
+ * @param {number} options.level - Heading level (1-6)
+ * @param {boolean} options.autoFocus - Whether to auto-focus the heading on mount
+ * @param {boolean} options.announceOnChange - Whether to announce content changes to screen readers
+ * @param {Function} options.onFocus - Callback when heading receives focus
+ * @param {boolean} options.registerWithContext - Whether to register with HeadingHierarchyContext (default: true)
+ * @param {string} options.id - Unique identifier for context registration (auto-generated if not provided)
+ * @returns {Object} Ref and accessibility properties
+ *
+ * @example
+ * const { headingRef, ariaProps } = useHeadingAccessibility({
+ *   level: 1,
+ *   autoFocus: true,
+ *   announceOnChange: true
+ * });
+ */
+export const useHeadingAccessibility = ({
+	level = 1,
+	autoFocus = false,
+	announceOnChange = false,
+	onFocus = null,
+	registerWithContext = true,
+	id = null,
+} = {}) => {
+	const headingRef = useRef(null);
+	const previousContent = useRef('');
+	const headingId = useRef(
+		id || `heading-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
+	);
+
+	// Try to get context, but don't fail if not available
+	const hierarchyContext = useContext(HeadingHierarchyContext);
+
+	// Determine if this is the primary header (first h1)
+	let isPrimaryHeader = false;
+	if (level === 1) {
+		if (
+			hierarchyContext &&
+			Array.isArray(hierarchyContext.registeredHeadings) &&
+			hierarchyContext.registeredHeadings.length > 0
+		) {
+			// Find the first registered h1
+			const firstH1 = hierarchyContext.registeredHeadings.find(
+				(h) => h.level === 1
+			);
+			isPrimaryHeader = firstH1 && firstH1.id === headingId.current;
+		} else {
+			// If no context, assume this is the primary header
+			isPrimaryHeader = true;
+		}
+	}
+
+	useEffect(() => {
+		if (autoFocus && headingRef.current) {
+			// Focus the heading for immediate screen reader announcement
+			headingRef.current.focus();
+		}
+	}, [autoFocus]);
+
+	useEffect(() => {
+		// Register with context if available and enabled
+		if (registerWithContext && hierarchyContext?.registerHeading) {
+			hierarchyContext.registerHeading(headingId.current, level);
+		}
+
+		// Cleanup: unregister when component unmounts or level changes
+		return () => {
+			if (registerWithContext && hierarchyContext?.unregisterHeading) {
+				hierarchyContext.unregisterHeading(headingId.current);
+			}
+		};
+	}, [level, registerWithContext, hierarchyContext]);
+
+	useEffect(() => {
+		const heading = headingRef.current;
+		if (!heading || !announceOnChange) return;
+
+		const currentContent = heading.textContent || heading.innerText;
+
+		// Announce content changes to screen readers
+		if (
+			previousContent.current !== currentContent &&
+			previousContent.current !== ''
+		) {
+			const announcement = document.createElement('div');
+			announcement.setAttribute('aria-live', 'polite');
+			announcement.setAttribute('aria-atomic', 'true');
+			announcement.className = 'sr-only';
+			announcement.textContent = `Heading updated: ${currentContent}`;
+
+			document.body.appendChild(announcement);
+
+			// Clean up announcement after screen reader has time to process
+			setTimeout(() => {
+				if (document.body.contains(announcement)) {
+					document.body.removeChild(announcement);
+				}
+			}, 1000);
+		}
+
+		previousContent.current = currentContent;
+	}, [announceOnChange, headingRef]);
+
+	const handleFocus = (event) => {
+		if (onFocus) {
+			onFocus(event);
+		}
+	};
+
+	const ariaProps = {
+		'aria-level': level,
+		tabIndex: autoFocus ? 0 : undefined,
+		onFocus: onFocus ? handleFocus : undefined,
+		id: headingId.current,
+	};
+	// Set role="banner" for the primary h1
+	if (level === 1 && isPrimaryHeader) {
+		ariaProps.role = 'banner';
+	}
+
+	return {
+		headingRef,
+		ariaProps,
+		headingId: headingId.current,
+	};
+};
+
+/**
+ * Automatically detects existing heading levels in the DOM
+ * @returns {Array} Array of existing heading levels found in the document
+ */
+const detectExistingHeadingLevels = () => {
+	const headings = document.querySelectorAll('h1, h2, h3, h4, h5, h6');
+	const levels = Array.from(headings).map((heading) => {
+		const tagName = heading.tagName.toLowerCase();
+		return parseInt(tagName.charAt(1), 10);
+	});
+	return [...new Set(levels)].sort((a, b) => a - b);
+};
+
+/**
+ * Hook to validate heading hierarchy and warn about accessibility issues
+ * Automatically detects existing heading levels in the DOM to eliminate manual tracking
+ *
+ * @param {number} level - Current heading level
+ * @param {Object} options - Configuration options
+ * @param {Array} options.existingLevels - Manual override for existing levels (optional)
+ * @param {boolean} options.autoDetect - Whether to automatically detect existing levels (default: true)
+ * @returns {Object} Validation results and warnings
+ *
+ * @example
+ * // Automatic detection (recommended)
+ * const { isValidHierarchy, warnings } = useHeadingHierarchy(3);
+ *
+ * // Manual override if needed
+ * const { isValidHierarchy, warnings } = useHeadingHierarchy(3, { existingLevels: [1, 2] });
+ */
+/**
+ * Hook to validate heading hierarchy and warn about accessibility issues
+ * Automatically detects existing heading levels using context or DOM scanning
+ *
+ * @param {number} level - Current heading level
+ * @param {Object} options - Configuration options
+ * @param {Array} options.existingLevels - Manual override for existing levels (optional)
+ * @param {boolean} options.useContext - Whether to use HeadingHierarchyContext for detection (default: true)
+ * @param {boolean} options.autoDetect - Whether to automatically detect existing levels via DOM (default: true when context unavailable)
+ * @returns {Object} Validation results and warnings
+ *
+ * @example
+ * // Automatic detection with context (recommended)
+ * const { isValidHierarchy, warnings, detectedLevels } = useHeadingHierarchy(3);
+ *
+ * // Manual override if needed
+ * const { isValidHierarchy, warnings } = useHeadingHierarchy(3, { existingLevels: [1, 2] });
+ */
+export const useHeadingHierarchy = (level, options = {}) => {
+	const {
+		existingLevels: manualLevels = null,
+		useContext: useContextDetection = true,
+		autoDetect = true,
+	} = options;
+
+	const hierarchyContext = useContext(HeadingHierarchyContext);
+	const [detectedLevels, setDetectedLevels] = useState([]);
+	const warnings = [];
+	let isValidHierarchy = true;
+
+	// Auto-detect existing heading levels when component mounts or when autoDetect is enabled
+	useEffect(() => {
+		if (manualLevels !== null) return; // Skip detection if manual levels provided
+
+		if (useContextDetection && hierarchyContext?.registeredHeadings) {
+			// Use context-based detection (preferred)
+			const contextLevels = hierarchyContext.registeredHeadings
+				.map((h) => h.level)
+				.filter((l) => l !== level) // Exclude current level
+				.sort((a, b) => a - b);
+			setDetectedLevels([...new Set(contextLevels)]);
+		} else if (autoDetect) {
+			// Fall back to DOM scanning
+			const domLevels = detectExistingHeadingLevels().filter(
+				(l) => l !== level
+			); // Exclude current level to avoid self-detection
+			setDetectedLevels(domLevels);
+		}
+	}, [
+		level,
+		manualLevels,
+		useContextDetection,
+		autoDetect,
+		hierarchyContext?.registeredHeadings,
+	]);
+
+	// Use manual levels if provided, otherwise use auto-detected levels
+	const existingLevels = manualLevels !== null ? manualLevels : detectedLevels;
+
+	if (existingLevels.length === 0 && level !== 1) {
+		warnings.push('Page should start with an h1 heading');
+		isValidHierarchy = false;
+	}
+
+	if (existingLevels.length > 0) {
+		const lastLevel = Math.max(...existingLevels);
+		const levelGap = level - lastLevel;
+
+		if (levelGap > 1) {
+			warnings.push(
+				`Heading level gap detected: h${lastLevel} → h${level}. Consider using h${
+					lastLevel + 1
+				} instead.`
+			);
+			isValidHierarchy = false;
+		}
+	}
+
+	// Log warnings in development
+	useEffect(() => {
+		if (process.env.NODE_ENV === 'development' && warnings.length > 0) {
+			console.warn('Heading accessibility warnings:', warnings);
+		}
+	}, [warnings]);
+
+	return {
+		isValidHierarchy,
+		warnings,
+		detectedLevels: existingLevels,
+		detectionMethod:
+			manualLevels !== null
+				? 'manual'
+				: useContextDetection && hierarchyContext?.registeredHeadings
+				? 'context'
+				: 'dom',
+	};
+};
+
+/**
+ * Hook to generate heading IDs for anchor links and table of contents
+ *
+ * @param {string} text - Heading text content
+ * @param {string} prefix - Optional prefix for the ID
+ * @returns {string} Generated heading ID
+ *
+ * @example
+ * const headingId = useHeadingId('Getting Started Guide', 'section');
+ * // Returns: 'section-getting-started-guide'
+ */
+export const useHeadingId = (text, prefix = '') => {
+	if (!text) return '';
+
+	const baseId = text
+		.toString()
+		.toLowerCase()
+		.replace(/[^a-z0-9\s-]/g, '') // Remove special characters
+		.replace(/\s+/g, '-') // Replace spaces with hyphens
+		.replace(/-+/g, '-') // Remove multiple consecutive hyphens
+		.replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
+
+	return prefix ? `${prefix}-${baseId}` : baseId;
+};

package/dist/utils/utils/useRadioGroup.js

@@ -0,0 +1,311 @@
+import { useState, useCallback } from 'react';
+
+/**
+ * Custom hook for managing radio group state with accessibility features
+ * Provides controlled state management for radio groups with validation
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} options.name - Name for the radio group (required)
+ * @param {string} options.defaultValue - Default selected value
+ * @param {boolean} options.required - Whether selection is required
+ * @param {Function} options.onChange - Change callback function
+ * @param {Function} options.onValidate - Custom validation function
+ * @returns {Object} Radio group state and handlers
+ */
+export const useRadioGroup = (options = {}) => {
+	const {
+		name,
+		defaultValue = '',
+		required = false,
+		onChange,
+		onValidate,
+	} = options;
+
+	const [selectedValue, setSelectedValue] = useState(defaultValue);
+	const [hasError, setHasError] = useState(false);
+	const [errorMessage, setErrorMessage] = useState('');
+	const [touched, setTouched] = useState(false);
+
+	// Handle radio selection change
+	const handleChange = useCallback(
+		(event) => {
+			const value = event.target.value;
+			setSelectedValue(value);
+			setTouched(true);
+
+			// Clear error when user makes a selection
+			if (hasError && value) {
+				setHasError(false);
+				setErrorMessage('');
+			}
+
+			// Call external onChange if provided
+			onChange?.(event, value);
+		},
+		[hasError, onChange]
+	);
+
+	// Validate the current selection
+	const validate = useCallback(() => {
+		let isValid = true;
+		let message = '';
+
+		// Required field validation
+		if (required && !selectedValue) {
+			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]);
+
+	// Get props for individual radio inputs
+	const getRadioProps = useCallback(
+		(value) => ({
+			name,
+			value,
+			checked: selectedValue === value,
+			onChange: handleChange,
+			error: hasError,
+			errorText: hasError ? errorMessage : '',
+			'data-radio-group': name,
+		}),
+		[name, selectedValue, handleChange, hasError, errorMessage]
+	);
+
+	// Reset the group state
+	const reset = useCallback(() => {
+		setSelectedValue(defaultValue);
+		setHasError(false);
+		setErrorMessage('');
+		setTouched(false);
+	}, [defaultValue]);
+
+	// Set value programmatically
+	const setValue = useCallback(
+		(value) => {
+			setSelectedValue(value);
+			setTouched(true);
+			if (hasError) {
+				setHasError(false);
+				setErrorMessage('');
+			}
+		},
+		[hasError]
+	);
+
+	return {
+		// State
+		selectedValue,
+		hasError,
+		errorMessage,
+		touched,
+		isValid: !hasError,
+
+		// Handlers
+		handleChange,
+		validate,
+		reset,
+		setValue,
+		getRadioProps,
+
+		// Group props for fieldset
+		groupProps: {
+			name,
+			'data-radio-group': name,
+			'aria-invalid': hasError,
+			'aria-required': required,
+		},
+	};
+};
+
+/**
+ * Utility for managing keyboard navigation within radio groups
+ * Implements proper arrow key navigation as per ARIA standards
+ *
+ * @param {HTMLElement} groupElement - The radio group container
+ * @param {Object} options - Navigation options
+ * @param {Function} options.onChange - Optional callback when radio selection changes via keyboard
+ * @returns {Object} Navigation utilities
+ */
+export const useRadioKeyboardNavigation = (groupElement, options = {}) => {
+	const { onChange } = options;
+	const getRadioInputs = useCallback(() => {
+		if (!groupElement) return [];
+		return Array.from(
+			groupElement.querySelectorAll('input[type="radio"]:not(:disabled)')
+		);
+	}, [groupElement]);
+
+	const focusRadio = useCallback(
+		(radio) => {
+			if (radio) {
+				radio.focus();
+				radio.checked = true;
+
+				// Call onChange callback if provided
+				if (onChange) {
+					// Create a synthetic event-like object for consistency
+					const syntheticEvent = {
+						target: radio,
+						currentTarget: radio,
+						type: 'change',
+					};
+					onChange(syntheticEvent, radio.value);
+				}
+			}
+		},
+		[onChange]
+	);
+
+	const handleKeyDown = useCallback(
+		(event) => {
+			if (
+				!['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'].includes(event.key)
+			) {
+				return;
+			}
+
+			event.preventDefault();
+			const radios = getRadioInputs();
+			if (radios.length === 0) return;
+
+			const currentIndex = radios.findIndex(
+				(radio) => radio === document.activeElement
+			);
+			let nextIndex;
+
+			if (event.key === 'ArrowUp' || event.key === 'ArrowLeft') {
+				nextIndex = currentIndex <= 0 ? radios.length - 1 : currentIndex - 1;
+			} else {
+				nextIndex = currentIndex >= radios.length - 1 ? 0 : currentIndex + 1;
+			}
+
+			focusRadio(radios[nextIndex]);
+		},
+		[getRadioInputs, focusRadio]
+	);
+
+	return {
+		handleKeyDown,
+		focusFirst: useCallback(() => {
+			const radios = getRadioInputs();
+			const checkedRadio = radios.find((radio) => radio.checked);
+			focusRadio(checkedRadio || radios[0]);
+		}, [getRadioInputs, focusRadio]),
+
+		focusChecked: useCallback(() => {
+			const radios = getRadioInputs();
+			const checkedRadio = radios.find((radio) => radio.checked);
+			if (checkedRadio) checkedRadio.focus();
+		}, [getRadioInputs]),
+	};
+};
+
+/**
+ * Accessibility testing utility for radio groups
+ * Validates proper ARIA attributes and keyboard navigation
+ *
+ * @param {HTMLElement} groupElement - The radio group to test
+ * @returns {Object} Test results
+ */
+export const validateRadioGroupAccessibility = (groupElement) => {
+	const results = {
+		passed: true,
+		errors: [],
+		warnings: [],
+		info: [],
+	};
+
+	if (!groupElement) {
+		results.passed = false;
+		results.errors.push('No group element provided for testing');
+		return results;
+	}
+
+	// Check for fieldset/legend structure
+	const fieldset =
+		groupElement.closest('fieldset') || groupElement.querySelector('fieldset');
+	const legend = fieldset?.querySelector('legend');
+
+	if (!fieldset) {
+		results.warnings.push(
+			'Radio group should be wrapped in a <fieldset> element for better accessibility'
+		);
+	}
+
+	if (!legend) {
+		results.warnings.push(
+			'Radio group should have a <legend> element to describe the group'
+		);
+	}
+
+	// Check radio inputs
+	const radios = Array.from(
+		groupElement.querySelectorAll('input[type="radio"]')
+	);
+
+	if (radios.length === 0) {
+		results.passed = false;
+		results.errors.push('No radio inputs found in group');
+		return results;
+	}
+
+	// Check for proper name grouping
+	const names = [...new Set(radios.map((radio) => radio.name))];
+	if (names.length > 1) {
+		results.passed = false;
+		results.errors.push(
+			`All radios in group should have same name attribute. Found: ${names.join(
+				', '
+			)}`
+		);
+	}
+
+	// Check for labels
+	radios.forEach((radio, index) => {
+		const label =
+			radio.closest('label') ||
+			document.querySelector(`label[for="${radio.id}"]`);
+		if (!label) {
+			results.warnings.push(
+				`Radio ${index + 1} should have an associated label`
+			);
+		}
+
+		// Check for unique values
+		const duplicateValues = radios.filter(
+			(r) => r.value === radio.value && r !== radio
+		);
+		if (duplicateValues.length > 0) {
+			results.errors.push(
+				`Radio ${index + 1} has duplicate value "${radio.value}"`
+			);
+			results.passed = false;
+		}
+	});
+
+	// Check for at least one enabled radio
+	const enabledRadios = radios.filter((radio) => !radio.disabled);
+	if (enabledRadios.length === 0) {
+		results.passed = false;
+		results.errors.push('At least one radio should be enabled');
+	}
+
+	results.info.push(
+		`Found ${radios.length} radio inputs (${enabledRadios.length} enabled)`
+	);
+
+	return results;
+};