@a13y/react 0.1.0

package/dist/hooks/index.js

@@ -0,0 +1,648 @@
+import { useRef, useEffect, useCallback, useId, useState } from 'react';
+import { announce } from '@a13y/core/runtime/announce';
+
+var useAccessibleButton = (props) => {
+  const { label, onPress, isDisabled = false, role = "button", elementType = "button" } = props;
+  const buttonRef = useRef(null);
+  const isPressedRef = useRef(false);
+  useEffect(() => {
+    {
+      import('@a13y/devtools/runtime/invariants').then(
+        ({ assertHasAccessibleName, assertKeyboardAccessible }) => {
+          if (buttonRef.current) {
+            assertHasAccessibleName(buttonRef.current, "useAccessibleButton");
+            assertKeyboardAccessible(buttonRef.current, "useAccessibleButton");
+          }
+        }
+      );
+    }
+  }, []);
+  const handlePress = useCallback(
+    (event) => {
+      if (isDisabled) {
+        return;
+      }
+      onPress(event);
+    },
+    [onPress, isDisabled]
+  );
+  const handlePointerDown = useCallback(
+    (event) => {
+      if (isDisabled) {
+        event.preventDefault();
+        return;
+      }
+      isPressedRef.current = true;
+      handlePress({ type: "mouse" });
+    },
+    [handlePress, isDisabled]
+  );
+  const handleKeyDown = useCallback(
+    (event) => {
+      if (isDisabled) {
+        return;
+      }
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault();
+        handlePress({ type: "keyboard", key: event.key });
+      }
+    },
+    [handlePress, isDisabled]
+  );
+  const buttonProps = {
+    role,
+    tabIndex: isDisabled ? -1 : 0,
+    "aria-label": label,
+    "aria-disabled": isDisabled ? true : void 0,
+    disabled: elementType === "button" ? isDisabled : void 0,
+    onPointerDown: handlePointerDown,
+    onKeyDown: handleKeyDown
+  };
+  return {
+    buttonProps,
+    isPressed: isPressedRef.current
+  };
+};
+var useFocusTrap = (props) => {
+  const { isActive, onEscape, restoreFocus = true, autoFocus = true } = props;
+  const trapRef = useRef(null);
+  const focusTrapRef = useRef(null);
+  const previousFocusRef = useRef(null);
+  useEffect(() => {
+    if (!isActive || !trapRef.current) {
+      return;
+    }
+    if (restoreFocus) {
+      previousFocusRef.current = document.activeElement;
+    }
+    import('@a13y/core/runtime/focus').then(({ createFocusTrap }) => {
+      if (!trapRef.current) {
+        return;
+      }
+      const options = {
+        returnFocus: false,
+        onEscape
+      };
+      if (autoFocus) {
+        options.initialFocus = void 0;
+      }
+      const trap = createFocusTrap(trapRef.current, options);
+      trap.activate();
+      focusTrapRef.current = trap;
+      {
+        import('@a13y/devtools/runtime/validators').then(({ focusValidator }) => {
+          if (trapRef.current) {
+            focusValidator.validateFocusTrap(trapRef.current, true);
+          }
+        });
+      }
+    });
+    return () => {
+      if (focusTrapRef.current) {
+        focusTrapRef.current.deactivate();
+        focusTrapRef.current = null;
+      }
+      if (restoreFocus && previousFocusRef.current) {
+        previousFocusRef.current.focus();
+        {
+          import('@a13y/devtools/runtime/validators').then(({ focusValidator }) => {
+            if (previousFocusRef.current) {
+              focusValidator.expectFocusRestoration(
+                previousFocusRef.current,
+                "focus trap deactivation"
+              );
+            }
+          });
+        }
+      }
+    };
+  }, [isActive, onEscape, restoreFocus, autoFocus]);
+  return {
+    trapRef
+  };
+};
+
+// src/hooks/use-accessible-dialog.ts
+var useAccessibleDialog = (props) => {
+  const {
+    isOpen,
+    onClose,
+    title,
+    description,
+    role = "dialog",
+    isModal = true,
+    closeOnBackdropClick = true
+  } = props;
+  {
+    if (!title || title.trim().length === 0) {
+      throw new Error(
+        '@a13y/react [useAccessibleDialog]: "title" prop is required for accessibility'
+      );
+    }
+  }
+  const dialogRef = useRef(null);
+  const titleId = useId();
+  const descriptionId = useId();
+  const { trapRef } = useFocusTrap({
+    isActive: isOpen,
+    onEscape: onClose,
+    restoreFocus: true,
+    autoFocus: true
+  });
+  useEffect(() => {
+    if (dialogRef.current && trapRef.current !== dialogRef.current) {
+      trapRef.current = dialogRef.current;
+    }
+  }, [trapRef]);
+  useEffect(() => {
+    if (!isOpen || !isModal) {
+      return;
+    }
+    const originalOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.body.style.overflow = originalOverflow;
+    };
+  }, [isOpen, isModal]);
+  useEffect(() => {
+    if (isOpen) {
+      import('@a13y/devtools/runtime/invariants').then(
+        ({ assertHasAccessibleName, assertValidAriaAttributes }) => {
+          if (dialogRef.current) {
+            assertHasAccessibleName(dialogRef.current, "useAccessibleDialog");
+            assertValidAriaAttributes(dialogRef.current);
+          }
+        }
+      );
+    }
+  }, [isOpen]);
+  const dialogProps = {
+    ref: dialogRef,
+    role,
+    "aria-labelledby": titleId,
+    "aria-describedby": description ? descriptionId : void 0,
+    "aria-modal": isModal,
+    tabIndex: -1
+  };
+  const titleProps = {
+    id: titleId
+  };
+  const descriptionProps = description ? { id: descriptionId } : null;
+  const backdropProps = closeOnBackdropClick && isModal ? {
+    onClick: onClose,
+    "aria-hidden": true
+  } : null;
+  return {
+    dialogProps,
+    titleProps,
+    descriptionProps,
+    backdropProps,
+    close: onClose
+  };
+};
+var useKeyboardNavigation = (props) => {
+  const {
+    orientation,
+    loop = false,
+    onNavigate,
+    defaultIndex = 0,
+    currentIndex: controlledIndex
+  } = props;
+  const isControlled = controlledIndex !== void 0;
+  const [uncontrolledIndex, setUncontrolledIndex] = useState(defaultIndex);
+  const currentIndex = isControlled ? controlledIndex : uncontrolledIndex;
+  const itemsRef = useRef(/* @__PURE__ */ new Map());
+  const containerRef = useRef(null);
+  const setCurrentIndex = useCallback(
+    (index) => {
+      if (!isControlled) {
+        setUncontrolledIndex(index);
+      }
+      onNavigate?.(index);
+      const element = itemsRef.current.get(index);
+      if (element) {
+        element.focus();
+      }
+    },
+    [isControlled, onNavigate]
+  );
+  const navigate = useCallback(
+    (direction) => {
+      const itemCount = itemsRef.current.size;
+      if (itemCount === 0) {
+        return;
+      }
+      let nextIndex = currentIndex;
+      switch (direction) {
+        case "forward":
+          nextIndex = currentIndex + 1;
+          if (nextIndex >= itemCount) {
+            nextIndex = loop ? 0 : itemCount - 1;
+          }
+          break;
+        case "backward":
+          nextIndex = currentIndex - 1;
+          if (nextIndex < 0) {
+            nextIndex = loop ? itemCount - 1 : 0;
+          }
+          break;
+        case "first":
+          nextIndex = 0;
+          break;
+        case "last":
+          nextIndex = itemCount - 1;
+          break;
+      }
+      if (nextIndex !== currentIndex) {
+        setCurrentIndex(nextIndex);
+      }
+    },
+    [currentIndex, loop, setCurrentIndex]
+  );
+  const handleKeyDown = useCallback(
+    (event) => {
+      const { key } = event;
+      let direction = null;
+      if (key === "ArrowRight") {
+        if (orientation === "horizontal" || orientation === "both") {
+          direction = "forward";
+        }
+      } else if (key === "ArrowLeft") {
+        if (orientation === "horizontal" || orientation === "both") {
+          direction = "backward";
+        }
+      } else if (key === "ArrowDown") {
+        if (orientation === "vertical" || orientation === "both") {
+          direction = "forward";
+        }
+      } else if (key === "ArrowUp") {
+        if (orientation === "vertical" || orientation === "both") {
+          direction = "backward";
+        }
+      } else if (key === "Home") {
+        direction = "first";
+      } else if (key === "End") {
+        direction = "last";
+      }
+      if (direction) {
+        event.preventDefault();
+        navigate(direction);
+      }
+    },
+    [orientation, navigate]
+  );
+  const getItemProps = useCallback(
+    (index) => {
+      return {
+        ref: (element) => {
+          if (element) {
+            itemsRef.current.set(index, element);
+          } else {
+            itemsRef.current.delete(index);
+          }
+        },
+        tabIndex: index === currentIndex ? 0 : -1,
+        onKeyDown: handleKeyDown,
+        "data-index": index
+      };
+    },
+    [currentIndex, handleKeyDown]
+  );
+  useEffect(() => {
+    {
+      import('@a13y/devtools/runtime/validators').then(({ keyboardValidator }) => {
+        if (containerRef.current) {
+          keyboardValidator.validateContainer(containerRef.current);
+        }
+        const container = Array.from(itemsRef.current.values())[0]?.parentElement;
+        if (container) {
+          keyboardValidator.validateRovingTabindex(container);
+        }
+      });
+    }
+  }, []);
+  const containerProps = {
+    role: "toolbar",
+    "aria-orientation": orientation
+  };
+  return {
+    currentIndex,
+    setCurrentIndex,
+    getItemProps,
+    containerProps
+  };
+};
+var useAccessibleForm = (config) => {
+  const {
+    fields,
+    validate: formValidator,
+    onSubmit,
+    autoFocusError = true,
+    announceErrors = true,
+    validateOnBlur = true,
+    validateOnChange = true
+  } = config;
+  const initialValues = Object.keys(fields).reduce((acc, key) => {
+    acc[key] = fields[key].initialValue;
+    return acc;
+  }, {});
+  const [values, setValues] = useState(initialValues);
+  const [errors, setErrors] = useState({});
+  const [touched, setTouched] = useState({});
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [hasSubmitted, setHasSubmitted] = useState(false);
+  const fieldRefs = useRef(/* @__PURE__ */ new Map());
+  const validateField = useCallback(
+    (name) => {
+      const fieldConfig = fields[name];
+      const value = values[name];
+      if (fieldConfig.required) {
+        const isEmpty = value === "" || value === null || value === void 0 || Array.isArray(value) && value.length === 0;
+        if (isEmpty) {
+          const errorMessage = fieldConfig.requiredMessage || `${String(name)} is required`;
+          setErrors((prev) => ({ ...prev, [name]: errorMessage }));
+          return false;
+        }
+      }
+      if (fieldConfig.validate) {
+        const result = fieldConfig.validate(value);
+        if (result !== true) {
+          setErrors((prev) => ({ ...prev, [name]: result }));
+          return false;
+        }
+      }
+      setErrors((prev) => {
+        const newErrors = { ...prev };
+        delete newErrors[name];
+        return newErrors;
+      });
+      return true;
+    },
+    [fields, values]
+  );
+  const validateForm = useCallback(() => {
+    let isValid2 = true;
+    const newErrors = {};
+    for (const name of Object.keys(fields)) {
+      const fieldConfig = fields[name];
+      const value = values[name];
+      if (fieldConfig.required) {
+        const isEmpty = value === "" || value === null || value === void 0 || Array.isArray(value) && value.length === 0;
+        if (isEmpty) {
+          const errorMessage = fieldConfig.requiredMessage || `${String(name)} is required`;
+          newErrors[name] = errorMessage;
+          isValid2 = false;
+          continue;
+        }
+      }
+      if (fieldConfig.validate) {
+        const result = fieldConfig.validate(value);
+        if (result !== true) {
+          newErrors[name] = result;
+          isValid2 = false;
+        }
+      }
+    }
+    if (formValidator) {
+      const formErrors = formValidator(values);
+      if (formErrors) {
+        Object.assign(newErrors, formErrors);
+        isValid2 = false;
+      }
+    }
+    setErrors(newErrors);
+    return isValid2;
+  }, [fields, values, formValidator]);
+  const setFieldValue = useCallback((name, value) => {
+    setValues((prev) => ({ ...prev, [name]: value }));
+  }, []);
+  const setFieldError = useCallback((name, error) => {
+    setErrors((prev) => ({ ...prev, [name]: error }));
+  }, []);
+  const getFieldProps = useCallback(
+    (name, options) => {
+      const fieldConfig = fields[name];
+      const hasError = !!errors[name];
+      const errorId = `${String(name)}-error`;
+      return {
+        name: String(name),
+        value: values[name],
+        onChange: (value) => {
+          setFieldValue(name, value);
+          if (validateOnChange && touched[name]) {
+            validateField(name);
+          }
+        },
+        onBlur: () => {
+          setTouched((prev) => ({ ...prev, [name]: true }));
+          if (validateOnBlur) {
+            validateField(name);
+          }
+        },
+        "aria-invalid": hasError,
+        "aria-describedby": hasError ? options?.["aria-describedby"] ? `${errorId} ${options["aria-describedby"]}` : errorId : options?.["aria-describedby"],
+        "aria-required": fieldConfig.required
+      };
+    },
+    [
+      fields,
+      values,
+      errors,
+      touched,
+      setFieldValue,
+      validateField,
+      validateOnBlur,
+      validateOnChange
+    ]
+  );
+  const handleSubmit = useCallback(
+    async (e) => {
+      e?.preventDefault();
+      setHasSubmitted(true);
+      const isValid2 = validateForm();
+      if (!isValid2) {
+        const errorCount = Object.keys(errors).length;
+        if (announceErrors) {
+          const errorMessage = errorCount === 1 ? "Form has 1 error. Please correct it and try again." : `Form has ${errorCount} errors. Please correct them and try again.`;
+          announce(errorMessage, { politeness: "assertive" });
+        }
+        if (autoFocusError) {
+          const firstErrorField = Object.keys(errors)[0];
+          const fieldElement = fieldRefs.current.get(firstErrorField);
+          if (fieldElement) {
+            fieldElement.focus();
+          }
+        }
+        return;
+      }
+      setIsSubmitting(true);
+      try {
+        await onSubmit(values);
+        announce("Form submitted successfully", { politeness: "polite" });
+      } catch (error) {
+        if (announceErrors) {
+          announce("Form submission failed. Please try again.", {
+            politeness: "assertive"
+          });
+        }
+        throw error;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [validateForm, errors, announceErrors, autoFocusError, onSubmit, values]
+  );
+  const reset = useCallback(() => {
+    setValues(initialValues);
+    setErrors({});
+    setTouched({});
+    setHasSubmitted(false);
+  }, [initialValues]);
+  const clearErrors = useCallback(() => {
+    setErrors({});
+  }, []);
+  const isValid = Object.keys(errors).length === 0;
+  return {
+    state: {
+      values,
+      errors,
+      touched,
+      isSubmitting,
+      isValid,
+      hasSubmitted
+    },
+    getFieldProps,
+    setFieldValue,
+    setFieldError,
+    setErrors,
+    validateField,
+    validateForm,
+    handleSubmit,
+    reset,
+    clearErrors,
+    fieldRefs: fieldRefs.current
+  };
+};
+var useFormField = (props) => {
+  const {
+    label,
+    initialValue = "",
+    validate: validator,
+    required = false,
+    requiredMessage,
+    helpText,
+    validateOnBlur = true,
+    validateOnChange = true,
+    announceErrors = true,
+    onChange,
+    onBlur
+  } = props;
+  {
+    if (!label || label.trim().length === 0) {
+      throw new Error('@a13y/react [useFormField]: "label" prop is required for accessibility');
+    }
+  }
+  const [value, setValue] = useState(initialValue);
+  const [error, setError] = useState(null);
+  const [isTouched, setIsTouched] = useState(false);
+  const fieldRef = useRef(null);
+  const id = useId();
+  const labelId = `${id}-label`;
+  const errorId = `${id}-error`;
+  const helpTextId = `${id}-help`;
+  const validate = useCallback(() => {
+    if (required) {
+      const isEmpty = value === "" || value === null || value === void 0 || Array.isArray(value) && value.length === 0;
+      if (isEmpty) {
+        const errorMessage = requiredMessage || `${label} is required`;
+        setError(errorMessage);
+        return false;
+      }
+    }
+    if (validator) {
+      const result = validator(value);
+      if (result !== true) {
+        setError(result);
+        return false;
+      }
+    }
+    setError(null);
+    return true;
+  }, [value, required, validator, label, requiredMessage]);
+  useEffect(() => {
+    if (error && isTouched && announceErrors) {
+      announce(error, { politeness: "assertive", delay: 100 });
+    }
+  }, [error, isTouched, announceErrors]);
+  const handleChange = useCallback(
+    (newValue) => {
+      setValue(newValue);
+      onChange?.(newValue);
+      if (validateOnChange && isTouched) {
+        setTimeout(() => validate(), 0);
+      }
+    },
+    [onChange, validateOnChange, isTouched, validate]
+  );
+  const handleBlur = useCallback(() => {
+    setIsTouched(true);
+    onBlur?.();
+    if (validateOnBlur) {
+      validate();
+    }
+  }, [onBlur, validateOnBlur, validate]);
+  const clearError = useCallback(() => {
+    setError(null);
+  }, []);
+  const reset = useCallback(() => {
+    setValue(initialValue);
+    setError(null);
+    setIsTouched(false);
+  }, [initialValue]);
+  const isValid = error === null;
+  const describedBy = [helpText ? helpTextId : null, error ? errorId : null].filter(Boolean).join(" ");
+  return {
+    id,
+    labelId,
+    errorId,
+    helpTextId,
+    value,
+    error,
+    isTouched,
+    isValid,
+    setValue: handleChange,
+    setError,
+    validate,
+    clearError,
+    reset,
+    labelProps: {
+      id: labelId,
+      htmlFor: id
+    },
+    inputProps: {
+      id,
+      name: id,
+      value,
+      onChange: handleChange,
+      onBlur: handleBlur,
+      "aria-labelledby": labelId,
+      "aria-describedby": describedBy || void 0,
+      "aria-invalid": !isValid,
+      "aria-required": required ? true : void 0,
+      ref: fieldRef
+    },
+    errorProps: {
+      id: errorId,
+      role: "alert",
+      "aria-live": "polite"
+    },
+    helpTextProps: {
+      id: helpTextId
+    },
+    fieldRef
+  };
+};
+
+export { useAccessibleButton, useAccessibleDialog, useAccessibleForm, useFocusTrap, useFormField, useKeyboardNavigation };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map