@abstraks-dev/ui-library 1.0.1

package/dist/utils/utils/useTabsAccessibility.js

@@ -0,0 +1,316 @@
+import { useState, useCallback, useEffect, useRef } from 'react';
+
+/**
+ * Custom hook for managing tabs state with accessibility features
+ * Provides controlled state management for tab navigation with ARIA support
+ *
+ * @param {Object} options - Configuration options
+ * @param {Array} options.tabs - Array of tab objects with id, label, and content
+ * @param {string} options.defaultActiveTab - Default active tab ID
+ * @param {Function} options.onChange - Change callback function
+ * @returns {Object} Tabs state and handlers
+ */
+export const useTabsAccessibility = (options = {}) => {
+	const { tabs = [], defaultActiveTab = '', onChange } = options;
+
+	const [activeTabId, setActiveTabId] = useState(
+		defaultActiveTab || tabs[0]?.id || ''
+	);
+	const [focusedTabIndex, setFocusedTabIndex] = useState(0);
+	const tabListRef = useRef(null);
+	const tabRefs = useRef({});
+
+	// Handle tab selection
+	const handleTabSelect = useCallback(
+		(tabId, index) => {
+			setActiveTabId(tabId);
+			setFocusedTabIndex(index);
+			onChange?.(tabId, index);
+		},
+		[onChange]
+	);
+
+	// Handle keyboard navigation
+	const handleKeyDown = useCallback(
+		(event, tabId, currentIndex) => {
+			let newIndex = currentIndex;
+
+			switch (event.key) {
+				case 'ArrowLeft':
+					event.preventDefault();
+					newIndex = currentIndex > 0 ? currentIndex - 1 : tabs.length - 1;
+					break;
+				case 'ArrowRight':
+					event.preventDefault();
+					newIndex = currentIndex < tabs.length - 1 ? currentIndex + 1 : 0;
+					break;
+				case 'Home':
+					event.preventDefault();
+					newIndex = 0;
+					break;
+				case 'End':
+					event.preventDefault();
+					newIndex = tabs.length - 1;
+					break;
+				case 'Enter':
+				case ' ':
+					event.preventDefault();
+					handleTabSelect(tabId, currentIndex);
+					return;
+				default:
+					return;
+			}
+
+			// Focus the new tab
+			const newTabId = tabs[newIndex]?.id;
+			if (newTabId && tabRefs.current[newTabId]) {
+				tabRefs.current[newTabId].focus();
+				setFocusedTabIndex(newIndex);
+			}
+		},
+		[tabs, handleTabSelect]
+	);
+
+	// Get props for tab list
+	const getTabListProps = useCallback(
+		() => ({
+			ref: tabListRef,
+			role: 'tablist',
+			'aria-orientation': 'horizontal',
+		}),
+		[]
+	);
+
+	// Get props for individual tabs
+	const getTabProps = useCallback(
+		(tab, index) => ({
+			ref: (el) => {
+				if (el) {
+					tabRefs.current[tab.id] = el;
+				}
+			},
+			id: `tab-${tab.id}`,
+			role: 'tab',
+			'aria-selected': activeTabId === tab.id,
+			'aria-controls': `panel-${tab.id}`,
+			tabIndex: activeTabId === tab.id ? 0 : -1,
+			onClick: () => handleTabSelect(tab.id, index),
+			onKeyDown: (event) => handleKeyDown(event, tab.id, index),
+		}),
+		[activeTabId, handleTabSelect, handleKeyDown]
+	);
+
+	// Get props for tab panels
+	const getTabPanelProps = useCallback(
+		(tab) => ({
+			id: `panel-${tab.id}`,
+			role: 'tabpanel',
+			'aria-labelledby': `tab-${tab.id}`,
+			hidden: activeTabId !== tab.id,
+			tabIndex: activeTabId === tab.id ? 0 : -1,
+		}),
+		[activeTabId]
+	);
+
+	// Focus management - focus active tab on mount
+	useEffect(() => {
+		if (activeTabId && tabRefs.current[activeTabId]) {
+			const timer = setTimeout(() => {
+				tabRefs.current[activeTabId]?.focus();
+			}, 0);
+			return () => clearTimeout(timer);
+		}
+	}, []);
+
+	return {
+		// State
+		activeTabId,
+		focusedTabIndex,
+		tabListRef,
+		tabRefs,
+
+		// Handlers
+		handleTabSelect,
+		handleKeyDown,
+		setActiveTabId,
+
+		// Props getters
+		getTabListProps,
+		getTabProps,
+		getTabPanelProps,
+	};
+};
+
+/**
+ * Accessibility validation utility for tabs
+ * Validates proper ARIA attributes and keyboard navigation
+ *
+ * @param {HTMLElement} tabsElement - The tabs container element to test
+ * @returns {Object} Test results
+ */
+export const validateTabsAccessibility = (tabsElement) => {
+	const results = {
+		passed: true,
+		errors: [],
+		warnings: [],
+		info: [],
+	};
+
+	if (!tabsElement) {
+		results.passed = false;
+		results.errors.push('No tabs element provided for testing');
+		return results;
+	}
+
+	// Check for tablist
+	const tabList = tabsElement.querySelector('[role="tablist"]');
+	if (!tabList) {
+		results.passed = false;
+		results.errors.push('Tabs must have a container with role="tablist"');
+	} else {
+		// Check for aria-orientation
+		if (!tabList.hasAttribute('aria-orientation')) {
+			results.warnings.push('Tablist should have aria-orientation attribute');
+		}
+
+		// Check tabs
+		const tabs = tabList.querySelectorAll('[role="tab"]');
+		if (tabs.length === 0) {
+			results.passed = false;
+			results.errors.push('Tablist must contain elements with role="tab"');
+		} else {
+			let hasSelectedTab = false;
+
+			tabs.forEach((tab, index) => {
+				// Check for aria-selected
+				if (!tab.hasAttribute('aria-selected')) {
+					results.warnings.push(
+						`Tab ${index + 1} should have aria-selected attribute`
+					);
+				} else if (tab.getAttribute('aria-selected') === 'true') {
+					hasSelectedTab = true;
+				}
+
+				// Check for aria-controls
+				if (!tab.hasAttribute('aria-controls')) {
+					results.warnings.push(
+						`Tab ${index + 1} should have aria-controls attribute`
+					);
+				}
+
+				// Check for proper tabindex
+				const tabIndex = tab.getAttribute('tabindex');
+				const isSelected = tab.getAttribute('aria-selected') === 'true';
+				if (isSelected && tabIndex !== '0') {
+					results.warnings.push(`Selected tab should have tabindex="0"`);
+				} else if (!isSelected && tabIndex !== '-1') {
+					results.warnings.push(`Unselected tabs should have tabindex="-1"`);
+				}
+			});
+
+			if (!hasSelectedTab) {
+				results.warnings.push('One tab should have aria-selected="true"');
+			}
+
+			results.info.push(`Found ${tabs.length} tabs`);
+		}
+
+		// Check panels
+		const panels = tabsElement.querySelectorAll('[role="tabpanel"]');
+		tabs.forEach((tab, index) => {
+			const controls = tab.getAttribute('aria-controls');
+			if (controls) {
+				const panel = tabsElement.querySelector(`#${controls}`);
+				if (!panel) {
+					results.warnings.push(
+						`Tab ${index + 1} aria-controls points to non-existent panel`
+					);
+				} else if (panel.getAttribute('role') !== 'tabpanel') {
+					results.warnings.push(
+						`Element referenced by tab ${index + 1} should have role="tabpanel"`
+					);
+				}
+			}
+		});
+
+		results.info.push(`Found ${panels.length} tab panels`);
+	}
+
+	return results;
+};
+
+/**
+ * Utility for enhancing tabs accessibility with live regions
+ * Provides screen reader announcements for tab changes
+ *
+ * @param {Array} tabs - Array of tab objects
+ * @param {string} activeTabId - Currently active tab ID
+ * @param {Object} options - Configuration options
+ * @returns {Object} Live region utilities
+ */
+export const useTabsLiveRegion = (tabs, activeTabId, options = {}) => {
+	const { enableTabAnnouncement = true, 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 announceTabChange = useCallback(
+		(tabId) => {
+			if (!enableTabAnnouncement || !tabId) return;
+
+			const activeTab = tabs.find((tab) => tab.id === tabId);
+			if (activeTab) {
+				const message =
+					customMessages.tabChange ||
+					`${activeTab.label} tab selected. ${tabs.indexOf(activeTab) + 1} of ${
+						tabs.length
+					}`;
+				announce(message);
+			}
+		},
+		[announce, enableTabAnnouncement, customMessages.tabChange, tabs]
+	);
+
+	// Announce tab changes
+	useEffect(() => {
+		if (activeTabId) {
+			announceTabChange(activeTabId);
+		}
+	}, [activeTabId, announceTabChange]);
+
+	return {
+		announce,
+		announceTabChange,
+		liveRegion,
+	};
+};

package/dist/utils/utils/useTextAreaAccessibility.js

@@ -0,0 +1,303 @@
+import { useState, useCallback, useEffect, useRef } from 'react';
+
+/**
+ * Custom hook for managing textarea state with accessibility features
+ * Provides controlled state management for textarea with ARIA support
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} options.defaultValue - Default textarea 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
+ * @returns {Object} TextArea state and handlers
+ */
+export const useTextAreaAccessibility = (options = {}) => {
+	const {
+		defaultValue = '',
+		onChange,
+		required = false,
+		maxLength,
+		minLength,
+	} = options;
+
+	const [value, setValue] = useState(defaultValue);
+	const [charCount, setCharCount] = useState(defaultValue.length);
+	const [isValid, setIsValid] = useState(!required || defaultValue.length > 0);
+	const [hasBeenTouched, setHasBeenTouched] = useState(false);
+	const textareaRef = useRef(null);
+
+	const handleChange = useCallback(
+		(event) => {
+			const newValue = event.target.value;
+			setValue(newValue);
+			setCharCount(newValue.length);
+			setHasBeenTouched(true);
+
+			// Validate the field
+			let valid = true;
+			if (required && newValue.trim().length === 0) {
+				valid = false;
+			}
+			if (minLength && newValue.length < minLength) {
+				valid = false;
+			}
+			if (maxLength && newValue.length > maxLength) {
+				valid = false;
+			}
+			setIsValid(valid);
+
+			// Call external onChange handler
+			onChange?.(event, {
+				value: newValue,
+				isValid: valid,
+				charCount: newValue.length,
+			});
+		},
+		[onChange, required, minLength, maxLength]
+	);
+
+	const handleFocus = useCallback((event) => {
+		// Focus handling for accessibility
+		setHasBeenTouched(true);
+	}, []);
+
+	const handleBlur = useCallback(
+		(event) => {
+			// Blur handling for validation
+			const newValue = event.target.value;
+			let valid = true;
+			if (required && newValue.trim().length === 0) {
+				valid = false;
+			}
+			if (minLength && newValue.length < minLength) {
+				valid = false;
+			}
+			if (maxLength && newValue.length > maxLength) {
+				valid = false;
+			}
+			setIsValid(valid);
+		},
+		[required, minLength, maxLength]
+	);
+
+	const reset = useCallback(() => {
+		setValue(defaultValue);
+		setCharCount(defaultValue.length);
+		setIsValid(!required || defaultValue.length > 0);
+		setHasBeenTouched(false);
+	}, [defaultValue, required]);
+
+	const focus = useCallback(() => {
+		textareaRef.current?.focus();
+	}, []);
+
+	return {
+		// State
+		value,
+		charCount,
+		isValid,
+		hasBeenTouched,
+		showError: hasBeenTouched && !isValid,
+
+		// Handlers
+		handleChange,
+		handleFocus,
+		handleBlur,
+		reset,
+		focus,
+
+		// Ref
+		textareaRef,
+
+		// Computed properties
+		remainingChars: maxLength ? maxLength - charCount : null,
+		isAtMaxLength: maxLength ? charCount >= maxLength : false,
+		isAtMinLength: minLength ? charCount >= minLength : true,
+	};
+};
+
+/**
+ * Validates textarea accessibility compliance
+ * Checks for proper ARIA attributes, labels, and keyboard support
+ *
+ * @param {HTMLElement} textareaElement - The textarea element to validate
+ * @returns {Object} Validation results with errors and warnings
+ */
+export const validateTextAreaAccessibility = (textareaElement) => {
+	const results = {
+		passed: true,
+		errors: [],
+		warnings: [],
+		info: [],
+	};
+
+	if (!textareaElement) {
+		results.passed = false;
+		results.errors.push('No textarea element provided for validation');
+		return results;
+	}
+
+	// Check if it's actually a textarea element
+	if (textareaElement.tagName.toLowerCase() !== 'textarea') {
+		// Look for textarea within the element
+		const textarea = textareaElement.querySelector('textarea');
+		if (!textarea) {
+			results.passed = false;
+			results.errors.push(
+				'Element is not a textarea and contains no textarea element'
+			);
+			return results;
+		}
+		// Use the found textarea for validation
+		textareaElement = textarea;
+	}
+
+	// 1. Check for accessible name (label, aria-label, or aria-labelledby)
+	const hasLabel =
+		textareaElement.hasAttribute('aria-label') ||
+		textareaElement.hasAttribute('aria-labelledby') ||
+		textareaElement.labels?.length > 0;
+
+	if (!hasLabel) {
+		results.passed = false;
+		results.errors.push(
+			'Textarea must have an accessible name (label, aria-label, or aria-labelledby)'
+		);
+	}
+
+	// 2. Check for proper ID if labelledby is used
+	if (textareaElement.hasAttribute('aria-labelledby')) {
+		const labelId = textareaElement.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 (
+		textareaElement.hasAttribute('required') ||
+		textareaElement.hasAttribute('aria-required')
+	) {
+		if (!textareaElement.hasAttribute('aria-required')) {
+			results.warnings.push(
+				'Consider adding aria-required="true" for screen reader users'
+			);
+		}
+	}
+
+	// 4. Check for error state accessibility
+	if (textareaElement.hasAttribute('aria-invalid')) {
+		const isInvalid = textareaElement.getAttribute('aria-invalid') === 'true';
+		if (isInvalid && !textareaElement.hasAttribute('aria-describedby')) {
+			results.warnings.push(
+				'Invalid textarea should have aria-describedby pointing to error message'
+			);
+		}
+	}
+
+	// 5. Check for character count accessibility
+	const hasMaxLength = textareaElement.hasAttribute('maxlength');
+	if (hasMaxLength && !textareaElement.hasAttribute('aria-describedby')) {
+		results.warnings.push(
+			'Textarea with maxlength should have aria-describedby for character count info'
+		);
+	}
+
+	// 6. Check for placeholder accessibility
+	if (textareaElement.hasAttribute('placeholder')) {
+		results.warnings.push(
+			'Avoid using placeholder as the only label - ensure proper labeling exists'
+		);
+	}
+
+	// 7. Check for disabled state
+	if (textareaElement.disabled) {
+		results.info.push('Textarea is disabled');
+	}
+
+	// 8. Check for keyboard accessibility
+	const tabIndex = textareaElement.getAttribute('tabindex');
+	if (tabIndex && parseInt(tabIndex) < 0) {
+		results.warnings.push(
+			'Textarea has negative tabindex - may not be keyboard accessible'
+		);
+	}
+
+	// 9. Check for resize capability
+	const computedStyle = window.getComputedStyle(textareaElement);
+	if (computedStyle.resize === 'none') {
+		results.info.push(
+			'Textarea resize is disabled - consider allowing users to resize for better usability'
+		);
+	}
+
+	// 10. Check for minimum contrast (if possible)
+	const bgColor = computedStyle.backgroundColor;
+	const textColor = computedStyle.color;
+	if (bgColor && textColor) {
+		results.info.push(
+			'Manual contrast check recommended for accessibility compliance'
+		);
+	}
+
+	if (results.errors.length === 0) {
+		results.info.push('Basic accessibility validation passed');
+	}
+
+	return results;
+};
+
+/**
+ * Character count utility for textarea accessibility
+ * Provides screen reader announcements for character limits
+ *
+ * @param {number} currentCount - Current character count
+ * @param {number} maxLength - Maximum allowed characters
+ * @param {number} warningThreshold - Threshold to start warnings (default: 0.8)
+ * @returns {Object} Character count info and announcements
+ */
+export const getCharacterCountInfo = (
+	currentCount,
+	maxLength,
+	warningThreshold = 0.8
+) => {
+	if (!maxLength) return null;
+
+	const remaining = maxLength - currentCount;
+	const percentage = currentCount / maxLength;
+	const isWarning = percentage >= warningThreshold;
+	const isError = currentCount > maxLength;
+
+	let announcement = '';
+	let status = 'info';
+
+	if (isError) {
+		announcement = `Character limit exceeded. ${Math.abs(
+			remaining
+		)} characters over limit.`;
+		status = 'error';
+	} else if (isWarning) {
+		announcement = `${remaining} characters remaining.`;
+		status = 'warning';
+	} else {
+		announcement = `${currentCount} of ${maxLength} characters used.`;
+		status = 'info';
+	}
+
+	return {
+		currentCount,
+		maxLength,
+		remaining,
+		percentage,
+		isWarning,
+		isError,
+		announcement,
+		status,
+		ariaLabel: `Character count: ${announcement}`,
+	};
+};