@abstraks-dev/ui-library 1.0.1

package/dist/utils/labelUtils.js

@@ -0,0 +1,708 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.validators = exports.useLabelAccessibility = exports.useFormValidation = exports.useFieldValidation = exports.labelTestingUtils = exports.default = void 0;
+var _react = require("react");
+/**
+ * Label Component Utilities
+ * Provides helper functions and hooks for Label component functionality
+ */
+
+/**
+ * Counter for generating unique IDs
+ */
+let idCounter = 0;
+
+/**
+ * Generates a robust unique ID using a combination of counter and timestamp
+ * @param {string} prefix - Optional prefix for the ID
+ * @returns {string} Unique ID
+ */
+const generateUniqueId = (prefix = 'id') => {
+  return `${prefix}-${++idCounter}-${Date.now().toString(36)}${Math.random().toString(36).substr(2, 4)}`;
+};
+
+/**
+ * Generates a UUID v4 compatible ID (simplified version)
+ * @returns {string} UUID-like string
+ */
+const generateUUID = () => {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+    const r = Math.random() * 16 | 0;
+    const v = c === 'x' ? r : r & 0x3 | 0x8;
+    return v.toString(16);
+  });
+};
+
+/**
+ * Singleton live region manager for screen reader announcements
+ */
+class LiveRegionManager {
+  constructor() {
+    this.liveRegion = null;
+    this.referenceCount = 0;
+    this.announcementQueue = [];
+    this.isProcessing = false;
+  }
+
+  /**
+   * Creates or returns existing live region
+   * @returns {HTMLElement} Live region element
+   */
+  getLiveRegion() {
+    if (!this.liveRegion) {
+      this.liveRegion = document.createElement('div');
+      this.liveRegion.setAttribute('aria-live', 'assertive');
+      this.liveRegion.setAttribute('aria-atomic', 'true');
+      this.liveRegion.className = 'sr-only';
+      this.liveRegion.style.cssText = `
+				position: absolute !important;
+				width: 1px !important;
+				height: 1px !important;
+				padding: 0 !important;
+				margin: -1px !important;
+				overflow: hidden !important;
+				clip: rect(0, 0, 0, 0) !important;
+				white-space: nowrap !important;
+				border: 0 !important;
+			`;
+      document.body.appendChild(this.liveRegion);
+    }
+    return this.liveRegion;
+  }
+
+  /**
+   * Increment reference count and return live region
+   * @returns {HTMLElement} Live region element
+   */
+  addReference() {
+    this.referenceCount++;
+    return this.getLiveRegion();
+  }
+
+  /**
+   * Decrement reference count and cleanup if no references remain
+   */
+  removeReference() {
+    this.referenceCount--;
+    if (this.referenceCount <= 0 && this.liveRegion) {
+      if (document.body.contains(this.liveRegion)) {
+        document.body.removeChild(this.liveRegion);
+      }
+      this.liveRegion = null;
+      this.referenceCount = 0;
+      this.announcementQueue = [];
+    }
+  }
+
+  /**
+   * Announce text to screen readers with queuing to prevent conflicts
+   * @param {string} text - Text to announce
+   */
+  async announce(text) {
+    if (!text) return;
+    this.announcementQueue.push(text);
+    if (!this.isProcessing) {
+      this.isProcessing = true;
+      await this.processQueue();
+    }
+  }
+
+  /**
+   * Process announcement queue to prevent conflicts
+   */
+  async processQueue() {
+    while (this.announcementQueue.length > 0) {
+      const text = this.announcementQueue.shift();
+      const liveRegion = this.getLiveRegion();
+
+      // Clear previous announcement
+      liveRegion.textContent = '';
+
+      // Small delay to ensure screen reader picks up the change
+      await new Promise(resolve => setTimeout(resolve, 10));
+
+      // Set new announcement
+      liveRegion.textContent = text;
+
+      // Wait before processing next announcement
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    this.isProcessing = false;
+  }
+
+  /**
+   * Get current reference count (useful for debugging)
+   * @returns {number} Current reference count
+   */
+  getReferenceCount() {
+    return this.referenceCount;
+  }
+}
+
+// Singleton instance
+const liveRegionManager = new LiveRegionManager();
+
+/**
+ * Hook for managing form field validation states
+ * @param {Object} options - Configuration options
+ * @param {boolean} options.required - Whether the field is required
+ * @param {Function} options.validator - Custom validation function
+ * @param {string} options.initialValue - Initial field value
+ * @returns {Object} Validation state and handlers
+ */
+const useFieldValidation = ({
+  required = false,
+  validator = null,
+  initialValue = ''
+} = {}) => {
+  const [value, setValue] = (0, _react.useState)(initialValue);
+  const [validationState, setValidationState] = (0, _react.useState)('default');
+  const [errorText, setErrorText] = (0, _react.useState)('');
+  const [successText, setSuccessText] = (0, _react.useState)('');
+  const [touched, setTouched] = (0, _react.useState)(false);
+  const validate = (0, _react.useCallback)(inputValue => {
+    // Required validation
+    if (required && (!inputValue || inputValue.trim() === '')) {
+      return {
+        state: 'error',
+        errorText: 'This field is required',
+        successText: ''
+      };
+    }
+
+    // Custom validation
+    if (validator && inputValue) {
+      const result = validator(inputValue);
+      if (result.isValid === false) {
+        return {
+          state: 'error',
+          errorText: result.message || 'Invalid input',
+          successText: ''
+        };
+      }
+      if (result.isValid === true) {
+        return {
+          state: 'success',
+          errorText: '',
+          successText: result.message || 'Valid input'
+        };
+      }
+    }
+
+    // Default state for valid input
+    if (inputValue && inputValue.trim() !== '') {
+      return {
+        state: 'success',
+        errorText: '',
+        successText: ''
+      };
+    }
+    return {
+      state: 'default',
+      errorText: '',
+      successText: ''
+    };
+  }, [required, validator]);
+  const handleChange = newValue => {
+    setValue(newValue);
+    if (touched) {
+      const validation = validate(newValue);
+      setValidationState(validation.state);
+      setErrorText(validation.errorText);
+      setSuccessText(validation.successText);
+    }
+  };
+  const handleBlur = () => {
+    setTouched(true);
+    const validation = validate(value);
+    setValidationState(validation.state);
+    setErrorText(validation.errorText);
+    setSuccessText(validation.successText);
+  };
+  const reset = () => {
+    setValue(initialValue);
+    setValidationState('default');
+    setErrorText('');
+    setSuccessText('');
+    setTouched(false);
+  };
+  return {
+    value,
+    validationState,
+    errorText,
+    successText,
+    touched,
+    handleChange,
+    handleBlur,
+    reset,
+    isValid: validationState === 'success' || validationState === 'default' && (!required || value)
+  };
+};
+
+/**
+ * Hook to manage label accessibility attributes
+ * @param {Object} options - Configuration options
+ * @returns {Object} Accessibility props and handlers
+ */
+exports.useFieldValidation = useFieldValidation;
+const useLabelAccessibility = ({
+  labelId = '',
+  inputId = '',
+  helpText = '',
+  errorText = '',
+  successText = '',
+  required = false
+} = {}) => {
+  const [announceText, setAnnounceText] = (0, _react.useState)('');
+  const previousErrorRef = (0, _react.useRef)('');
+  const liveRegionRef = (0, _react.useRef)(null);
+
+  // Generate unique IDs if not provided
+  const generatedLabelId = labelId || generateUniqueId('label');
+  const generatedInputId = inputId || generateUniqueId('input');
+  const helpId = helpText ? `${generatedInputId}-help` : '';
+  const errorId = errorText ? `${generatedInputId}-error` : '';
+  const successId = successText ? `${generatedInputId}-success` : '';
+
+  // Build aria-describedby
+  const ariaDescribedBy = [helpId, errorId, successId].filter(Boolean).join(' ') || undefined;
+
+  // Handle error announcements
+  (0, _react.useEffect)(() => {
+    if (errorText && errorText !== previousErrorRef.current) {
+      setAnnounceText(errorText);
+      previousErrorRef.current = errorText;
+    } else if (!errorText && previousErrorRef.current) {
+      setAnnounceText('');
+      previousErrorRef.current = '';
+    }
+  }, [errorText]);
+
+  // Manage live region reference and announcements
+  (0, _react.useEffect)(() => {
+    // Add reference to live region manager on mount
+    liveRegionRef.current = liveRegionManager.addReference();
+    return () => {
+      // Remove reference on unmount
+      liveRegionManager.removeReference();
+      liveRegionRef.current = null;
+    };
+  }, []);
+
+  // Handle announcements
+  (0, _react.useEffect)(() => {
+    if (announceText) {
+      liveRegionManager.announce(announceText);
+    }
+  }, [announceText]);
+  return {
+    labelProps: {
+      id: generatedLabelId,
+      htmlFor: generatedInputId
+    },
+    inputProps: {
+      id: generatedInputId,
+      'aria-describedby': ariaDescribedBy,
+      'aria-required': required ? 'true' : undefined,
+      'aria-invalid': errorText ? 'true' : undefined
+    },
+    helpProps: helpText ? {
+      id: helpId
+    } : {},
+    errorProps: errorText ? {
+      id: errorId,
+      role: 'alert'
+    } : {},
+    successProps: successText ? {
+      id: successId,
+      role: 'status'
+    } : {}
+  };
+};
+
+/**
+ * Common validation functions for form fields
+ */
+exports.useLabelAccessibility = useLabelAccessibility;
+const validators = exports.validators = {
+  /**
+   * Email validation
+   */
+  email: value => {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return {
+      isValid: emailRegex.test(value),
+      message: emailRegex.test(value) ? 'Valid email address' : 'Please enter a valid email address'
+    };
+  },
+  /**
+   * Password validation (minimum 8 characters, mixed case, number)
+   */
+  password: value => {
+    const hasMinLength = value.length >= 8;
+    const hasLowerCase = /[a-z]/.test(value);
+    const hasUpperCase = /[A-Z]/.test(value);
+    const hasNumber = /\d/.test(value);
+    const isValid = hasMinLength && hasLowerCase && hasUpperCase && hasNumber;
+    let message = '';
+    if (!isValid) {
+      const missing = [];
+      if (!hasMinLength) missing.push('at least 8 characters');
+      if (!hasLowerCase) missing.push('lowercase letter');
+      if (!hasUpperCase) missing.push('uppercase letter');
+      if (!hasNumber) missing.push('number');
+      message = `Password must contain ${missing.join(', ')}`;
+    } else {
+      message = 'Strong password';
+    }
+    return {
+      isValid,
+      message
+    };
+  },
+  /**
+   * Phone number validation (US format)
+   */
+  phone: value => {
+    const phoneRegex = /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/;
+    return {
+      isValid: phoneRegex.test(value),
+      message: phoneRegex.test(value) ? 'Valid phone number' : 'Please enter a valid phone number (e.g., 555-123-4567)'
+    };
+  },
+  /**
+   * URL validation
+   */
+  url: value => {
+    try {
+      new URL(value);
+      return {
+        isValid: true,
+        message: 'Valid URL'
+      };
+    } catch {
+      return {
+        isValid: false,
+        message: 'Please enter a valid URL (e.g., https://example.com)'
+      };
+    }
+  },
+  /**
+   * Minimum length validation
+   */
+  minLength: min => value => {
+    const isValid = value.length >= min;
+    return {
+      isValid,
+      message: isValid ? `Meets minimum length requirement` : `Must be at least ${min} characters`
+    };
+  },
+  /**
+   * Maximum length validation
+   */
+  maxLength: max => value => {
+    const isValid = value.length <= max;
+    return {
+      isValid,
+      message: isValid ? `Within length limit` : `Must be no more than ${max} characters`
+    };
+  },
+  /**
+   * Custom regex validation
+   */
+  regex: (pattern, message) => value => {
+    const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+    const isValid = regex.test(value);
+    return {
+      isValid,
+      message: isValid ? 'Valid format' : message || 'Invalid format'
+    };
+  }
+};
+
+/**
+ * Hook for managing form validation state across multiple fields
+ * @param {Object} fields - Field configuration object
+ * @returns {Object} Form state and handlers
+ */
+const useFormValidation = (fields = {}) => {
+  const [formState, setFormState] = (0, _react.useState)({});
+  const [isSubmitting, setIsSubmitting] = (0, _react.useState)(false);
+  const [submitError, setSubmitError] = (0, _react.useState)('');
+
+  // Initialize form state
+  (0, _react.useEffect)(() => {
+    const initialState = {};
+    Object.keys(fields).forEach(fieldName => {
+      initialState[fieldName] = {
+        value: fields[fieldName].initialValue || '',
+        validationState: 'default',
+        errorText: '',
+        successText: '',
+        touched: false
+      };
+    });
+    setFormState(initialState);
+  }, [fields]);
+  const updateField = (fieldName, updates) => {
+    setFormState(prev => ({
+      ...prev,
+      [fieldName]: {
+        ...prev[fieldName],
+        ...updates
+      }
+    }));
+  };
+  const validateField = (fieldName, value) => {
+    const fieldConfig = fields[fieldName];
+    if (!fieldConfig) return {
+      state: 'default',
+      errorText: '',
+      successText: ''
+    };
+
+    // Required validation
+    if (fieldConfig.required && (!value || value.trim() === '')) {
+      return {
+        state: 'error',
+        errorText: fieldConfig.requiredMessage || 'This field is required',
+        successText: ''
+      };
+    }
+
+    // Custom validation
+    if (fieldConfig.validator && value) {
+      const result = fieldConfig.validator(value);
+      if (result.isValid === false) {
+        return {
+          state: 'error',
+          errorText: result.message || 'Invalid input',
+          successText: ''
+        };
+      }
+      if (result.isValid === true) {
+        return {
+          state: 'success',
+          errorText: '',
+          successText: result.message || ''
+        };
+      }
+    }
+    return {
+      state: value ? 'success' : 'default',
+      errorText: '',
+      successText: ''
+    };
+  };
+  const handleFieldChange = (fieldName, value) => {
+    const validation = validateField(fieldName, value);
+    updateField(fieldName, {
+      value,
+      validationState: formState[fieldName]?.touched ? validation.state : 'default',
+      errorText: formState[fieldName]?.touched ? validation.errorText : '',
+      successText: formState[fieldName]?.touched ? validation.successText : ''
+    });
+  };
+  const handleFieldBlur = fieldName => {
+    const value = formState[fieldName]?.value || '';
+    const validation = validateField(fieldName, value);
+    updateField(fieldName, {
+      touched: true,
+      validationState: validation.state,
+      errorText: validation.errorText,
+      successText: validation.successText
+    });
+  };
+  const validateForm = () => {
+    let isValid = true;
+    const newFormState = {
+      ...formState
+    };
+    Object.keys(fields).forEach(fieldName => {
+      const value = formState[fieldName]?.value || '';
+      const validation = validateField(fieldName, value);
+      newFormState[fieldName] = {
+        ...newFormState[fieldName],
+        touched: true,
+        validationState: validation.state,
+        errorText: validation.errorText,
+        successText: validation.successText
+      };
+      if (validation.state === 'error') {
+        isValid = false;
+      }
+    });
+    setFormState(newFormState);
+    return isValid;
+  };
+  const handleSubmit = async onSubmit => {
+    setIsSubmitting(true);
+    setSubmitError('');
+    const isValid = validateForm();
+    if (isValid) {
+      try {
+        const formData = {};
+        Object.keys(formState).forEach(fieldName => {
+          formData[fieldName] = formState[fieldName].value;
+        });
+        await onSubmit(formData);
+      } catch (error) {
+        setSubmitError(error.message || 'An error occurred while submitting the form');
+      }
+    }
+    setIsSubmitting(false);
+  };
+  const resetForm = () => {
+    const resetState = {};
+    Object.keys(fields).forEach(fieldName => {
+      resetState[fieldName] = {
+        value: fields[fieldName].initialValue || '',
+        validationState: 'default',
+        errorText: '',
+        successText: '',
+        touched: false
+      };
+    });
+    setFormState(resetState);
+    setSubmitError('');
+  };
+  return {
+    formState,
+    isSubmitting,
+    submitError,
+    handleFieldChange,
+    handleFieldBlur,
+    handleSubmit,
+    resetForm,
+    isFormValid: Object.values(formState).every(field => field.validationState === 'success' || field.validationState === 'default' && !fields[Object.keys(formState).find(key => formState[key] === field)]?.required)
+  };
+};
+
+/**
+ * Accessibility testing utilities for labels
+ */
+exports.useFormValidation = useFormValidation;
+const labelTestingUtils = exports.labelTestingUtils = {
+  /**
+   * Validates label-input associations
+   */
+  validateLabelAssociations() {
+    const labels = document.querySelectorAll('label[for]');
+    const results = [];
+    labels.forEach(label => {
+      const forValue = label.getAttribute('for');
+      const associatedInput = document.getElementById(forValue);
+      results.push({
+        labelText: label.textContent?.trim(),
+        forAttribute: forValue,
+        hasAssociatedInput: !!associatedInput,
+        inputType: associatedInput?.type || 'N/A',
+        hasAriaDescribedBy: !!associatedInput?.getAttribute('aria-describedby'),
+        isValid: !!associatedInput
+      });
+    });
+    return results;
+  },
+  /**
+   * Checks for proper required field indicators
+   */
+  validateRequiredFields() {
+    const requiredInputs = document.querySelectorAll('input[required], select[required], textarea[required]');
+    const results = [];
+    requiredInputs.forEach(input => {
+      const id = input.id;
+      const label = document.querySelector(`label[for="${id}"]`);
+      const hasVisualIndicator = label?.textContent?.includes('*') || label?.querySelector('.required, .label__required');
+      const hasAriaRequired = input.getAttribute('aria-required') === 'true';
+      results.push({
+        inputId: id,
+        inputType: input.type,
+        hasLabel: !!label,
+        hasVisualIndicator,
+        hasAriaRequired,
+        labelText: label?.textContent?.trim() || 'No label',
+        isAccessible: hasVisualIndicator && hasAriaRequired
+      });
+    });
+    return results;
+  },
+  /**
+   * Tests validation message accessibility
+   */
+  validateErrorMessages() {
+    const errorMessages = document.querySelectorAll('[role="alert"], .label__message--error');
+    const results = [];
+    errorMessages.forEach(message => {
+      const id = message.id;
+      const referencingInputs = document.querySelectorAll(`[aria-describedby*="${id}"]`);
+      results.push({
+        messageId: id,
+        messageText: message.textContent?.trim(),
+        hasRole: message.getAttribute('role') === 'alert',
+        hasAriaLive: !!message.getAttribute('aria-live'),
+        isReferencedByInput: referencingInputs.length > 0,
+        referencingInputCount: referencingInputs.length
+      });
+    });
+    return results;
+  },
+  /**
+   * Simulates keyboard navigation through form labels
+   */
+  async simulateKeyboardNavigation() {
+    const labels = document.querySelectorAll('label');
+    const results = [];
+    for (let label of labels) {
+      // Simulate click on label
+      label.click();
+      const forValue = label.getAttribute('for');
+      const associatedInput = document.getElementById(forValue);
+      const isFocused = document.activeElement === associatedInput;
+      results.push({
+        labelText: label.textContent?.trim(),
+        forAttribute: forValue,
+        clickFocusesInput: isFocused,
+        focusedElementId: document.activeElement?.id || 'none',
+        isAccessible: isFocused
+      });
+
+      // Small delay for real-world simulation
+      await new Promise(resolve => setTimeout(resolve, 50));
+    }
+    return results;
+  },
+  /**
+   * Checks color contrast ratios for labels
+   */
+  checkColorContrast() {
+    const labels = document.querySelectorAll('label, .label__message');
+    const results = [];
+    labels.forEach(label => {
+      const styles = window.getComputedStyle(label);
+      const color = styles.color;
+      const backgroundColor = styles.backgroundColor;
+
+      // Note: Actual contrast calculation would require a color library
+      // This is a simplified check
+      results.push({
+        element: label.tagName,
+        className: label.className,
+        color,
+        backgroundColor,
+        // In a real implementation, calculate actual contrast ratio
+        contrastNote: 'Manual contrast checking required'
+      });
+    });
+    return results;
+  }
+};
+var _default = exports.default = {
+  useFieldValidation,
+  useLabelAccessibility,
+  useFormValidation,
+  validators,
+  labelTestingUtils
+};