@abstraks-dev/ui-library 1.0.1

package/dist/utils/useSelectAccessibility.js

@@ -0,0 +1,426 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.validateSelectAccessibility = exports.useSelectLiveRegion = exports.useSelectKeyboardNavigation = exports.useSelectAccessibility = void 0;
+var _react = require("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
+ */
+const useSelectAccessibility = (options = {}) => {
+  const {
+    name,
+    defaultValue = '',
+    multiple = false,
+    required = false,
+    onChange,
+    onValidate
+  } = options;
+  const [selectedValue, setSelectedValue] = (0, _react.useState)(defaultValue);
+  const [hasError, setHasError] = (0, _react.useState)(false);
+  const [errorMessage, setErrorMessage] = (0, _react.useState)('');
+  const [touched, setTouched] = (0, _react.useState)(false);
+  const [isFocused, setIsFocused] = (0, _react.useState)(false);
+
+  // Handle select value change
+  const handleChange = (0, _react.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 = (0, _react.useCallback)(event => {
+    setIsFocused(true);
+  }, []);
+
+  // Handle blur events
+  const handleBlur = (0, _react.useCallback)(event => {
+    setIsFocused(false);
+    setTouched(true);
+  }, []);
+
+  // Validate the current selection
+  const validate = (0, _react.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 = (0, _react.useCallback)(() => {
+    setSelectedValue(defaultValue);
+    setHasError(false);
+    setErrorMessage('');
+    setTouched(false);
+    setIsFocused(false);
+  }, [defaultValue]);
+
+  // Set value programmatically
+  const setValue = (0, _react.useCallback)(value => {
+    setSelectedValue(value);
+    setTouched(true);
+    if (hasError) {
+      setHasError(false);
+      setErrorMessage('');
+    }
+  }, [hasError]);
+
+  // Get props for the select element
+  const getSelectProps = (0, _react.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
+ */
+exports.useSelectAccessibility = useSelectAccessibility;
+const useSelectKeyboardNavigation = (selectElement, options = {}) => {
+  const {
+    onNavigate
+  } = options;
+  const getOptions = (0, _react.useCallback)(() => {
+    if (!selectElement) return [];
+    return Array.from(selectElement.options).filter(option => !option.disabled);
+  }, [selectElement]);
+  const handleKeyDown = (0, _react.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 = (0, _react.useCallback)(() => {
+    if (!selectElement) return;
+    const options = getOptions();
+    if (options.length > 0) {
+      selectElement.selectedIndex = 0;
+      selectElement.focus();
+    }
+  }, [selectElement, getOptions]);
+  const focusLast = (0, _react.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
+ */
+exports.useSelectKeyboardNavigation = useSelectKeyboardNavigation;
+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
+ */
+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
+ */
+exports.validateSelectAccessibility = validateSelectAccessibility;
+const useSelectLiveRegion = (selectElement, options = {}) => {
+  const {
+    enableSelectionAnnouncement = true,
+    enableOptionsAnnouncement = false,
+    customMessages = {}
+  } = options;
+  const [liveRegion, setLiveRegion] = (0, _react.useState)(null);
+
+  // Create live region for announcements
+  (0, _react.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 = (0, _react.useCallback)(message => {
+    if (liveRegion) {
+      liveRegion.textContent = message;
+    }
+  }, [liveRegion]);
+  const announceSelection = (0, _react.useCallback)(selectedOption => {
+    if (!enableSelectionAnnouncement || !selectedOption) return;
+    const message = customMessages.selection || `Selected: ${selectedOption.textContent}`;
+    announce(message);
+  }, [announce, enableSelectionAnnouncement, customMessages.selection]);
+  const announceOptionsCount = (0, _react.useCallback)(count => {
+    if (!enableOptionsAnnouncement) return;
+    const message = customMessages.optionsCount || `${count} options available`;
+    announce(message);
+  }, [announce, enableOptionsAnnouncement, customMessages.optionsCount]);
+  return {
+    announce,
+    announceSelection,
+    announceOptionsCount,
+    liveRegion
+  };
+};
+exports.useSelectLiveRegion = useSelectLiveRegion;

package/dist/utils/useTabsAccessibility.js

@@ -0,0 +1,278 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.validateTabsAccessibility = exports.useTabsLiveRegion = exports.useTabsAccessibility = void 0;
+var _react = require("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
+ */
+const useTabsAccessibility = (options = {}) => {
+  const {
+    tabs = [],
+    defaultActiveTab = '',
+    onChange
+  } = options;
+  const [activeTabId, setActiveTabId] = (0, _react.useState)(defaultActiveTab || tabs[0]?.id || '');
+  const [focusedTabIndex, setFocusedTabIndex] = (0, _react.useState)(0);
+  const tabListRef = (0, _react.useRef)(null);
+  const tabRefs = (0, _react.useRef)({});
+
+  // Handle tab selection
+  const handleTabSelect = (0, _react.useCallback)((tabId, index) => {
+    setActiveTabId(tabId);
+    setFocusedTabIndex(index);
+    onChange?.(tabId, index);
+  }, [onChange]);
+
+  // Handle keyboard navigation
+  const handleKeyDown = (0, _react.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 = (0, _react.useCallback)(() => ({
+    ref: tabListRef,
+    role: 'tablist',
+    'aria-orientation': 'horizontal'
+  }), []);
+
+  // Get props for individual tabs
+  const getTabProps = (0, _react.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 = (0, _react.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
+  (0, _react.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
+ */
+exports.useTabsAccessibility = useTabsAccessibility;
+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
+ */
+exports.validateTabsAccessibility = validateTabsAccessibility;
+const useTabsLiveRegion = (tabs, activeTabId, options = {}) => {
+  const {
+    enableTabAnnouncement = true,
+    customMessages = {}
+  } = options;
+  const [liveRegion, setLiveRegion] = (0, _react.useState)(null);
+
+  // Create live region for announcements
+  (0, _react.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 = (0, _react.useCallback)(message => {
+    if (liveRegion) {
+      liveRegion.textContent = message;
+    }
+  }, [liveRegion]);
+  const announceTabChange = (0, _react.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
+  (0, _react.useEffect)(() => {
+    if (activeTabId) {
+      announceTabChange(activeTabId);
+    }
+  }, [activeTabId, announceTabChange]);
+  return {
+    announce,
+    announceTabChange,
+    liveRegion
+  };
+};
+exports.useTabsLiveRegion = useTabsLiveRegion;