@abstraks-dev/ui-library 1.0.1

package/dist/utils/keyboardNavigation.js

@@ -0,0 +1,536 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.validateMenuARIA = exports.testRovingTabindex = exports.testKeyboardNavigation = exports.testFocusTrapping = exports.testArrowKeyNavigation = exports.simulateKeyPress = exports.isHighContrastMode = exports.generateTestReport = exports.auditComponentAccessibility = exports.KEYBOARD_KEYS = exports.A11Y_PATTERNS = void 0;
+/**
+ * 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
+ */
+const KEYBOARD_KEYS = exports.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
+ */
+const A11Y_PATTERNS = exports.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
+ */
+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
+ */
+exports.testKeyboardNavigation = testKeyboardNavigation;
+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
+ */
+exports.simulateKeyPress = simulateKeyPress;
+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
+ */
+exports.testFocusTrapping = testFocusTrapping;
+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
+ */
+exports.validateMenuARIA = validateMenuARIA;
+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
+ */
+exports.isHighContrastMode = isHighContrastMode;
+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
+ */
+exports.generateTestReport = generateTestReport;
+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
+ */
+exports.testRovingTabindex = testRovingTabindex;
+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
+ */
+exports.testArrowKeyNavigation = testArrowKeyNavigation;
+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;
+};
+exports.auditComponentAccessibility = auditComponentAccessibility;