@abstraks-dev/ui-library 1.0.1

package/dist/utils/useHeadingAccessibility.js

@@ -0,0 +1,298 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useHeadingId = exports.useHeadingHierarchy = exports.useHeadingAccessibility = exports.HeadingHierarchyProvider = void 0;
+var _react = require("react");
+// Context for tracking heading hierarchy across components
+const HeadingHierarchyContext = /*#__PURE__*/(0, _react.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>
+ */
+const HeadingHierarchyProvider = ({
+  children
+}) => {
+  const [registeredHeadings, setRegisteredHeadings] = (0, _react.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 /*#__PURE__*/React.createElement(HeadingHierarchyContext.Provider, {
+    value: value
+  }, children);
+};
+
+/**
+ * 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
+ * });
+ */
+exports.HeadingHierarchyProvider = HeadingHierarchyProvider;
+const useHeadingAccessibility = ({
+  level = 1,
+  autoFocus = false,
+  announceOnChange = false,
+  onFocus = null,
+  registerWithContext = true,
+  id = null
+} = {}) => {
+  const headingRef = (0, _react.useRef)(null);
+  const previousContent = (0, _react.useRef)('');
+  const headingId = (0, _react.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 = (0, _react.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;
+    }
+  }
+  (0, _react.useEffect)(() => {
+    if (autoFocus && headingRef.current) {
+      // Focus the heading for immediate screen reader announcement
+      headingRef.current.focus();
+    }
+  }, [autoFocus]);
+  (0, _react.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]);
+  (0, _react.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
+ */
+exports.useHeadingAccessibility = useHeadingAccessibility;
+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] });
+ */
+const useHeadingHierarchy = (level, options = {}) => {
+  const {
+    existingLevels: manualLevels = null,
+    useContext: useContextDetection = true,
+    autoDetect = true
+  } = options;
+  const hierarchyContext = (0, _react.useContext)(HeadingHierarchyContext);
+  const [detectedLevels, setDetectedLevels] = (0, _react.useState)([]);
+  const warnings = [];
+  let isValidHierarchy = true;
+
+  // Auto-detect existing heading levels when component mounts or when autoDetect is enabled
+  (0, _react.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
+  (0, _react.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'
+ */
+exports.useHeadingHierarchy = useHeadingHierarchy;
+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;
+};
+exports.useHeadingId = useHeadingId;

package/dist/utils/useRadioGroup.js

@@ -0,0 +1,260 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.validateRadioGroupAccessibility = exports.useRadioKeyboardNavigation = exports.useRadioGroup = void 0;
+var _react = require("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
+ */
+const useRadioGroup = (options = {}) => {
+  const {
+    name,
+    defaultValue = '',
+    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);
+
+  // Handle radio selection change
+  const handleChange = (0, _react.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 = (0, _react.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 = (0, _react.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 = (0, _react.useCallback)(() => {
+    setSelectedValue(defaultValue);
+    setHasError(false);
+    setErrorMessage('');
+    setTouched(false);
+  }, [defaultValue]);
+
+  // Set value programmatically
+  const setValue = (0, _react.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
+ */
+exports.useRadioGroup = useRadioGroup;
+const useRadioKeyboardNavigation = (groupElement, options = {}) => {
+  const {
+    onChange
+  } = options;
+  const getRadioInputs = (0, _react.useCallback)(() => {
+    if (!groupElement) return [];
+    return Array.from(groupElement.querySelectorAll('input[type="radio"]:not(:disabled)'));
+  }, [groupElement]);
+  const focusRadio = (0, _react.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 = (0, _react.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: (0, _react.useCallback)(() => {
+      const radios = getRadioInputs();
+      const checkedRadio = radios.find(radio => radio.checked);
+      focusRadio(checkedRadio || radios[0]);
+    }, [getRadioInputs, focusRadio]),
+    focusChecked: (0, _react.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
+ */
+exports.useRadioKeyboardNavigation = useRadioKeyboardNavigation;
+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;
+};
+exports.validateRadioGroupAccessibility = validateRadioGroupAccessibility;