@abstraks-dev/ui-library 1.0.1

package/dist/utils/utils/index.js

@@ -0,0 +1,9 @@
+export * from './ScrollHandler';
+export * from './useWindowSize';
+export * from './accessibility';
+export * from './validation';
+export * from './keyboardNavigation';
+export * from './useHeadingAccessibility';
+export * from './useTypographyAccessibility';
+export * from './useRadioGroup';
+export * from './useSelectAccessibility';

package/dist/utils/utils/inputValidation.js

@@ -0,0 +1,22 @@
+// inputValidation.js
+// Utility functions for input validation
+import isEmail from 'validator/lib/isEmail';
+import { isValidPhoneNumber } from 'libphonenumber-js';
+
+export function validateEmail(value) {
+	return isEmail(value);
+}
+
+export function validatePhone(value, country = 'US') {
+	return isValidPhoneNumber(value, country);
+}
+
+export function validateLength(value, minLength, maxLength) {
+	if (minLength && value.length < minLength) return false;
+	if (maxLength && value.length > maxLength) return false;
+	return true;
+}
+
+export function validateRequired(value) {
+	return value.trim().length > 0;
+}

package/dist/utils/utils/keyboardNavigation.js

@@ -0,0 +1,664 @@
+/**
+ * Keyboard Navigation Testing Utilities
+ *
+ * Provides helper functions for testing keyboard accessibility in components.
+ * These utilities help ensure WCAG 2.1 AA compliance for keyboard navigation.
+ */
+
+/**
+ * Essential keyboard event codes for navigation testing
+ * Simplified to most commonly used keys
+ */
+export const KEYBOARD_KEYS = {
+	TAB: 'Tab',
+	ENTER: 'Enter',
+	SPACE: ' ',
+	ESCAPE: 'Escape',
+	ARROW_UP: 'ArrowUp',
+	ARROW_DOWN: 'ArrowDown',
+	ARROW_LEFT: 'ArrowLeft',
+	ARROW_RIGHT: 'ArrowRight',
+	HOME: 'Home',
+	END: 'End',
+};
+
+/**
+ * Common accessibility test patterns
+ */
+export const A11Y_PATTERNS = {
+	// ARIA roles that require specific keyboard behaviors
+	ROVING_TABINDEX: ['tablist', 'menubar', 'listbox', 'tree', 'grid'],
+	SINGLE_TAB_STOP: ['radiogroup', 'tablist', 'toolbar'],
+	ARROW_NAVIGATION: ['menu', 'menubar', 'listbox', 'tree', 'tablist'],
+
+	// Required ARIA attributes for interactive elements
+	REQUIRED_ARIA: {
+		button: [],
+		menuitem: ['role'],
+		tab: ['role', 'aria-selected'],
+		tabpanel: ['role', 'aria-labelledby'],
+		listbox: ['role'],
+		option: ['role', 'aria-selected'],
+	},
+};
+
+/**
+ * Tests keyboard navigation for a component
+ * @param {HTMLElement} container - The container element to test
+ * @param {Object} options - Testing options
+ * @returns {Object} Test results
+ */
+export const testKeyboardNavigation = (container, options = {}) => {
+	const {
+		expectedFocusableCount = null,
+		shouldTrapFocus = false,
+		customKeys = [],
+		skipNativeElements = false,
+	} = options;
+
+	const results = {
+		passed: true,
+		errors: [],
+		focusableElements: [],
+		tabOrder: [],
+	};
+
+	try {
+		// Get all focusable elements
+		const focusableSelectors = [
+			'a[href]',
+			'button:not([disabled])',
+			'input:not([disabled])',
+			'select:not([disabled])',
+			'textarea:not([disabled])',
+			'[tabindex]:not([tabindex="-1"])',
+			'[role="button"]:not([disabled])',
+			'[role="link"]:not([disabled])',
+			'[role="menuitem"]:not([disabled])',
+			'[role="tab"]:not([disabled])',
+		];
+
+		const focusableElements = container.querySelectorAll(
+			focusableSelectors.join(', ')
+		);
+		results.focusableElements = Array.from(focusableElements);
+
+		// Check expected count
+		if (
+			expectedFocusableCount !== null &&
+			focusableElements.length !== expectedFocusableCount
+		) {
+			results.passed = false;
+			results.errors.push(
+				`Expected ${expectedFocusableCount} focusable elements, found ${focusableElements.length}`
+			);
+		}
+
+		// Test tab order
+		focusableElements.forEach((element, index) => {
+			const tabIndex = element.getAttribute('tabindex');
+			results.tabOrder.push({
+				index,
+				element: element.tagName.toLowerCase(),
+				tabIndex: tabIndex ? parseInt(tabIndex) : 0,
+				ariaLabel: element.getAttribute('aria-label'),
+				text: element.textContent?.trim().substring(0, 50),
+			});
+		});
+
+		// Check for focus indicators
+		focusableElements.forEach((element, index) => {
+			const computedStyle = window.getComputedStyle(element, ':focus');
+			const hasOutline =
+				computedStyle.outline !== 'none' && computedStyle.outline !== '';
+			const hasBoxShadow = computedStyle.boxShadow !== 'none';
+			const hasCustomFocus =
+				element.classList.contains('focus-visible') ||
+				element.hasAttribute('data-focus-visible');
+
+			if (!hasOutline && !hasBoxShadow && !hasCustomFocus) {
+				results.passed = false;
+				results.errors.push(
+					`Element ${index + 1} (${
+						element.tagName
+					}) lacks visible focus indicator`
+				);
+			}
+		});
+
+		// Test ARIA attributes
+		focusableElements.forEach((element, index) => {
+			const role = element.getAttribute('role');
+			const ariaLabel = element.getAttribute('aria-label');
+			const ariaLabelledBy = element.getAttribute('aria-labelledby');
+			const ariaDescribedBy = element.getAttribute('aria-describedby');
+
+			// Interactive elements should have accessible names
+			if (!ariaLabel && !ariaLabelledBy && !element.textContent?.trim()) {
+				const tagName = element.tagName.toLowerCase();
+				if (['button', 'a'].includes(tagName) || role) {
+					results.passed = false;
+					results.errors.push(
+						`Element ${index + 1} (${tagName}) lacks accessible name`
+					);
+				}
+			}
+		});
+	} catch (error) {
+		results.passed = false;
+		results.errors.push(`Test error: ${error.message}`);
+	}
+
+	return results;
+};
+
+/**
+ * Simulates keyboard events for testing
+ * @param {HTMLElement} element - Element to receive the event
+ * @param {string} key - Key code to simulate
+ * @param {Object} options - Event options
+ */
+export const simulateKeyPress = (element, key, options = {}) => {
+	const {
+		shiftKey = false,
+		ctrlKey = false,
+		altKey = false,
+		metaKey = false,
+		preventDefault = true,
+	} = options;
+
+	const event = new KeyboardEvent('keydown', {
+		key,
+		code: key,
+		shiftKey,
+		ctrlKey,
+		altKey,
+		metaKey,
+		bubbles: true,
+		cancelable: true,
+	});
+
+	if (preventDefault) {
+		event.preventDefault = () => {};
+	}
+
+	element.dispatchEvent(event);
+	return event;
+};
+
+/**
+ * Tests focus trapping in modal/dropdown components
+ * @param {HTMLElement} container - The container that should trap focus
+ * @returns {Object} Test results
+ */
+export const testFocusTrapping = (container) => {
+	const results = {
+		passed: true,
+		errors: [],
+		firstFocusable: null,
+		lastFocusable: null,
+	};
+
+	try {
+		const focusableElements = container.querySelectorAll(
+			'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+		);
+
+		if (focusableElements.length === 0) {
+			results.passed = false;
+			results.errors.push('No focusable elements found for focus trapping');
+			return results;
+		}
+
+		results.firstFocusable = focusableElements[0];
+		results.lastFocusable = focusableElements[focusableElements.length - 1];
+
+		// Test that first element receives focus on container open
+		// Test that focus cycles from last to first element
+		// Test that focus cycles from first to last element (shift+tab)
+		// These would need to be implemented in actual test scenarios
+	} catch (error) {
+		results.passed = false;
+		results.errors.push(`Focus trapping test error: ${error.message}`);
+	}
+
+	return results;
+};
+
+/**
+ * Validates ARIA attributes for dropdown/menu components
+ * @param {HTMLElement} trigger - The trigger element
+ * @param {HTMLElement} menu - The menu/dropdown element
+ * @returns {Object} Validation results
+ */
+export const validateMenuARIA = (trigger, menu) => {
+	const results = {
+		passed: true,
+		errors: [],
+		warnings: [],
+	};
+
+	try {
+		// Check trigger attributes
+		const ariaExpanded = trigger.getAttribute('aria-expanded');
+		const ariaHaspopup = trigger.getAttribute('aria-haspopup');
+		const ariaControls = trigger.getAttribute('aria-controls');
+
+		if (!ariaExpanded) {
+			results.passed = false;
+			results.errors.push('Trigger missing aria-expanded attribute');
+		}
+
+		if (!ariaHaspopup) {
+			results.warnings.push(
+				'Trigger missing aria-haspopup attribute (recommended)'
+			);
+		}
+
+		if (!ariaControls) {
+			results.warnings.push(
+				'Trigger missing aria-controls attribute (recommended)'
+			);
+		}
+
+		// Check menu attributes
+		const menuRole = menu.getAttribute('role');
+		const menuId = menu.getAttribute('id');
+		const ariaLabelledBy = menu.getAttribute('aria-labelledby');
+
+		if (!menuRole || !['menu', 'listbox', 'tree'].includes(menuRole)) {
+			results.passed = false;
+			results.errors.push('Menu missing appropriate role attribute');
+		}
+
+		if (ariaControls && !menuId) {
+			results.passed = false;
+			results.errors.push(
+				'Menu missing id attribute (referenced by aria-controls)'
+			);
+		}
+
+		if (ariaControls && menuId && ariaControls !== menuId) {
+			results.passed = false;
+			results.errors.push('aria-controls value does not match menu id');
+		}
+
+		// Check menu items
+		const menuItems = menu.querySelectorAll(
+			'[role="menuitem"], [role="option"]'
+		);
+		menuItems.forEach((item, index) => {
+			if (!item.getAttribute('role')) {
+				results.warnings.push(`Menu item ${index + 1} missing role attribute`);
+			}
+
+			if (!item.getAttribute('aria-label') && !item.textContent?.trim()) {
+				results.passed = false;
+				results.errors.push(`Menu item ${index + 1} lacks accessible name`);
+			}
+		});
+	} catch (error) {
+		results.passed = false;
+		results.errors.push(`ARIA validation error: ${error.message}`);
+	}
+
+	return results;
+};
+
+/**
+ * High contrast mode detection for testing
+ * @returns {boolean} Whether high contrast mode is active
+ */
+export const isHighContrastMode = () => {
+	// Create a test element to detect high contrast mode
+	const testElement = document.createElement('div');
+	testElement.style.borderWidth = '1px';
+	testElement.style.borderStyle = 'solid';
+	testElement.style.borderColor = 'red green blue';
+	testElement.style.position = 'absolute';
+	testElement.style.left = '-9999px';
+
+	document.body.appendChild(testElement);
+
+	const computedStyle = window.getComputedStyle(testElement);
+	const borderColors = [
+		computedStyle.borderTopColor,
+		computedStyle.borderRightColor,
+		computedStyle.borderBottomColor,
+		computedStyle.borderLeftColor,
+	];
+
+	document.body.removeChild(testElement);
+
+	// In high contrast mode, all borders will be the same color
+	const allSameColor = borderColors.every((color) => color === borderColors[0]);
+	return allSameColor && borderColors[0] !== 'rgba(0, 0, 0, 0)';
+};
+
+/**
+ * Generates a keyboard navigation test report
+ * @param {Object} testResults - Results from testKeyboardNavigation
+ * @returns {string} Formatted report
+ */
+export const generateTestReport = (testResults) => {
+	const { passed, errors, focusableElements, tabOrder } = testResults;
+
+	let report = `🔍 Keyboard Navigation Test Report\n`;
+	report += `Status: ${passed ? '✅ PASSED' : '❌ FAILED'}\n`;
+	report += `Focusable Elements: ${focusableElements.length}\n\n`;
+
+	if (errors.length > 0) {
+		report += `❌ Errors:\n`;
+		errors.forEach((error, index) => {
+			report += `${index + 1}. ${error}\n`;
+		});
+		report += '\n';
+	}
+
+	report += `📋 Tab Order:\n`;
+	tabOrder.forEach((item, index) => {
+		report += `${index + 1}. ${item.element}`;
+		if (item.ariaLabel) report += ` (${item.ariaLabel})`;
+		if (item.text) report += ` - "${item.text}"`;
+		report += '\n';
+	});
+
+	return report;
+};
+
+/**
+ * Tests roving tabindex behavior (common in toolbars, tab lists, etc.)
+ * @param {HTMLElement} container - Container with roving tabindex pattern
+ * @param {Object} options - Testing options
+ * @returns {Object} Test results
+ */
+export const testRovingTabindex = (container, options = {}) => {
+	const {
+		expectedActiveIndex = 0,
+		orientation = 'horizontal', // 'horizontal', 'vertical', 'both'
+		wraparound = true,
+	} = options;
+
+	const results = {
+		passed: true,
+		errors: [],
+		warnings: [],
+		activeElement: null,
+		tabbableElements: [],
+		focusableElements: [],
+	};
+
+	try {
+		// Find all elements that should participate in roving tabindex
+		const allElements = container.querySelectorAll(
+			'[role="tab"], [role="menuitem"], [role="option"], .roving-tabindex'
+		);
+		results.focusableElements = Array.from(allElements);
+
+		if (allElements.length === 0) {
+			results.passed = false;
+			results.errors.push('No elements found for roving tabindex pattern');
+			return results;
+		}
+
+		// Check that only one element has tabindex="0" (is tabbable)
+		const tabbableElements = Array.from(allElements).filter(
+			(el) =>
+				el.getAttribute('tabindex') === '0' ||
+				(!el.hasAttribute('tabindex') && el.tabIndex === 0)
+		);
+
+		const nonTabbableElements = Array.from(allElements).filter(
+			(el) => el.getAttribute('tabindex') === '-1'
+		);
+
+		results.tabbableElements = tabbableElements;
+
+		if (tabbableElements.length !== 1) {
+			results.passed = false;
+			results.errors.push(
+				`Expected exactly 1 tabbable element, found ${tabbableElements.length}`
+			);
+		}
+
+		if (
+			tabbableElements.length + nonTabbableElements.length !==
+			allElements.length
+		) {
+			results.passed = false;
+			results.errors.push(
+				'Some elements missing explicit tabindex values (-1 or 0)'
+			);
+		}
+
+		// Verify active element matches expected
+		if (tabbableElements.length === 1) {
+			results.activeElement = tabbableElements[0];
+			const activeIndex = Array.from(allElements).indexOf(
+				results.activeElement
+			);
+
+			if (expectedActiveIndex !== null && activeIndex !== expectedActiveIndex) {
+				results.warnings.push(
+					`Expected element ${expectedActiveIndex} to be active, but element ${activeIndex} is active`
+				);
+			}
+		}
+
+		// Check for proper ARIA attributes
+		allElements.forEach((element, index) => {
+			const role = element.getAttribute('role');
+
+			if (!role) {
+				results.warnings.push(
+					`Element ${index} missing role attribute for roving tabindex`
+				);
+			}
+
+			// Check for aria-selected on tabs/options
+			if (
+				['tab', 'option'].includes(role) &&
+				!element.hasAttribute('aria-selected')
+			) {
+				results.passed = false;
+				results.errors.push(
+					`Element ${index} with role="${role}" missing aria-selected attribute`
+				);
+			}
+		});
+	} catch (error) {
+		results.passed = false;
+		results.errors.push(`Roving tabindex test error: ${error.message}`);
+	}
+
+	return results;
+};
+
+/**
+ * Tests arrow key navigation patterns
+ * @param {HTMLElement} container - Container with arrow navigation
+ * @param {string} expectedPattern - Expected navigation pattern ('horizontal', 'vertical', 'both', 'grid')
+ * @returns {Object} Test results
+ */
+export const testArrowKeyNavigation = (
+	container,
+	expectedPattern = 'horizontal'
+) => {
+	const results = {
+		passed: true,
+		errors: [],
+		warnings: [],
+		pattern: expectedPattern,
+		navigableElements: [],
+	};
+
+	try {
+		// Find navigable elements
+		const elements = container.querySelectorAll(
+			'[role="tab"], [role="menuitem"], [role="option"], .arrow-navigable'
+		);
+		results.navigableElements = Array.from(elements);
+
+		if (elements.length < 2) {
+			results.warnings.push(
+				'Need at least 2 elements to test arrow navigation'
+			);
+			return results;
+		}
+
+		// Check if elements have proper event handlers (this is tricky to test statically)
+		// In real implementation, we'd simulate arrow key events and check focus changes
+
+		// Check for proper ARIA orientation attribute
+		const orientationAttr = container.getAttribute('aria-orientation');
+
+		if (expectedPattern === 'vertical' && orientationAttr !== 'vertical') {
+			results.warnings.push(
+				'Container should have aria-orientation="vertical" for vertical navigation'
+			);
+		}
+
+		if (expectedPattern === 'horizontal' && orientationAttr === 'vertical') {
+			results.warnings.push(
+				'Container has aria-orientation="vertical" but horizontal navigation expected'
+			);
+		}
+
+		// Check grid pattern requirements
+		if (expectedPattern === 'grid') {
+			const gridRole = container.getAttribute('role');
+			if (gridRole !== 'grid' && gridRole !== 'treegrid') {
+				results.passed = false;
+				results.errors.push(
+					'Grid navigation pattern requires role="grid" or role="treegrid"'
+				);
+			}
+		}
+	} catch (error) {
+		results.passed = false;
+		results.errors.push(`Arrow navigation test error: ${error.message}`);
+	}
+
+	return results;
+};
+
+/**
+ * Comprehensive accessibility audit for interactive components
+ * @param {HTMLElement} component - Component to audit
+ * @param {Object} options - Audit options
+ * @returns {Object} Comprehensive audit results
+ */
+export const auditComponentAccessibility = (component, options = {}) => {
+	const {
+		expectedRole = null,
+		checkColorContrast = false,
+		checkFocusManagement = true,
+		checkARIACompliance = true,
+	} = options;
+
+	const audit = {
+		passed: true,
+		score: 100,
+		errors: [],
+		warnings: [],
+		recommendations: [],
+		tests: {},
+	};
+
+	try {
+		// Basic keyboard navigation test
+		audit.tests.keyboardNavigation = testKeyboardNavigation(component, {
+			expectedFocusableCount: null,
+		});
+
+		if (!audit.tests.keyboardNavigation.passed) {
+			audit.passed = false;
+			audit.score -= 30;
+		}
+
+		// Check for roving tabindex patterns
+		const rovingElements = component.querySelectorAll(
+			'[role="tablist"], [role="menubar"], [role="toolbar"]'
+		);
+		if (rovingElements.length > 0) {
+			audit.tests.rovingTabindex = testRovingTabindex(rovingElements[0]);
+			if (!audit.tests.rovingTabindex.passed) {
+				audit.score -= 20;
+			}
+		}
+
+		// ARIA compliance check
+		if (checkARIACompliance) {
+			const interactiveElements = component.querySelectorAll(
+				'button, [role="button"], [role="menuitem"], [role="tab"]'
+			);
+
+			interactiveElements.forEach((element, index) => {
+				const role =
+					element.getAttribute('role') || element.tagName.toLowerCase();
+				const requiredAttrs = A11Y_PATTERNS.REQUIRED_ARIA[role] || [];
+
+				requiredAttrs.forEach((attr) => {
+					if (!element.hasAttribute(attr)) {
+						audit.errors.push(
+							`Element ${index} missing required ${attr} attribute`
+						);
+						audit.passed = false;
+						audit.score -= 10;
+					}
+				});
+			});
+		}
+
+		// Focus management check
+		if (checkFocusManagement) {
+			const focusableElements = component.querySelectorAll(
+				'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+			);
+
+			if (focusableElements.length === 0) {
+				audit.warnings.push('Component has no focusable elements');
+				audit.score -= 5;
+			}
+		}
+
+		// Expected role check
+		if (expectedRole) {
+			const actualRole = component.getAttribute('role');
+			if (actualRole !== expectedRole) {
+				audit.warnings.push(
+					`Expected role="${expectedRole}" but found "${actualRole || 'none'}"`
+				);
+				audit.score -= 10;
+			}
+		}
+
+		// Generate recommendations based on findings
+		if (audit.score < 100) {
+			if (audit.errors.length > 0) {
+				audit.recommendations.push(
+					'Fix critical accessibility errors before release'
+				);
+			}
+			if (audit.warnings.length > 0) {
+				audit.recommendations.push(
+					'Address accessibility warnings to improve user experience'
+				);
+			}
+			if (audit.score < 70) {
+				audit.recommendations.push(
+					'Consider comprehensive accessibility review with disabled users'
+				);
+			}
+		}
+
+		// Ensure score doesn't go below 0
+		audit.score = Math.max(0, audit.score);
+	} catch (error) {
+		audit.passed = false;
+		audit.score = 0;
+		audit.errors.push(`Audit error: ${error.message}`);
+	}
+
+	return audit;
+};