@a13y/react 0.1.0

package/dist/hooks/index.d.ts

@@ -0,0 +1,725 @@
+export { A as AccessibleButtonProps, P as PressEvent, U as UseAccessibleButtonProps, a as UseAccessibleButtonReturn, u as useAccessibleButton } from '../use-accessible-button-B0syf-Az.js';
+import { AriaRole } from 'react';
+
+/**
+ * @a13y/react - useAccessibleDialog
+ * Type-safe dialog/modal hook with full ARIA support
+ */
+
+/**
+ * Props for useAccessibleDialog
+ */
+interface UseAccessibleDialogProps {
+    /**
+     * Whether the dialog is open
+     */
+    isOpen: boolean;
+    /**
+     * Callback when dialog should close
+     * Called on Escape key or backdrop click
+     */
+    onClose: () => void;
+    /**
+     * Dialog title - REQUIRED for accessibility
+     * This becomes the aria-labelledby target
+     */
+    title: string;
+    /**
+     * Optional dialog description
+     * This becomes the aria-describedby target
+     */
+    description?: string;
+    /**
+     * ARIA role
+     * @default 'dialog'
+     */
+    role?: Extract<AriaRole, 'dialog' | 'alertdialog'>;
+    /**
+     * Whether dialog is modal (blocking)
+     * @default true
+     */
+    isModal?: boolean;
+    /**
+     * Whether clicking backdrop closes dialog
+     * @default true
+     */
+    closeOnBackdropClick?: boolean;
+}
+/**
+ * Dialog container props
+ */
+interface DialogContainerProps {
+    ref: React.RefObject<HTMLElement | null>;
+    role: AriaRole;
+    'aria-labelledby': string;
+    'aria-describedby'?: string;
+    'aria-modal': boolean;
+    tabIndex: -1;
+}
+/**
+ * Title props
+ */
+interface DialogTitleProps {
+    id: string;
+}
+/**
+ * Description props
+ */
+interface DialogDescriptionProps {
+    id: string;
+}
+/**
+ * Backdrop props
+ */
+interface DialogBackdropProps {
+    onClick: () => void;
+    'aria-hidden': true;
+}
+/**
+ * Return type
+ */
+interface UseAccessibleDialogReturn {
+    dialogProps: DialogContainerProps;
+    titleProps: DialogTitleProps;
+    descriptionProps: DialogDescriptionProps | null;
+    backdropProps: DialogBackdropProps | null;
+    close: () => void;
+}
+/**
+ * Hook for creating accessible dialogs/modals
+ *
+ * Features:
+ * - Focus trap with Tab/Shift+Tab cycling
+ * - Escape key to close
+ * - Focus restoration on close
+ * - ARIA attributes (modal, labelledby, describedby)
+ * - Backdrop click handling
+ * - Development-time validation
+ *
+ * @example
+ * ```tsx
+ * const { dialogProps, titleProps, descriptionProps, backdropProps } =
+ *   useAccessibleDialog({
+ *     isOpen,
+ *     onClose: () => setIsOpen(false),
+ *     title: 'Delete Item',
+ *     description: 'This action cannot be undone',
+ *   });
+ *
+ * if (!isOpen) return null;
+ *
+ * return (
+ *   <>
+ *     <div {...backdropProps} />
+ *     <div {...dialogProps}>
+ *       <h2 {...titleProps}>Delete Item</h2>
+ *       <p {...descriptionProps}>This action cannot be undone</p>
+ *       <button onClick={close}>Cancel</button>
+ *     </div>
+ *   </>
+ * );
+ * ```
+ */
+declare const useAccessibleDialog: (props: UseAccessibleDialogProps) => UseAccessibleDialogReturn;
+
+/**
+ * @a13y/react - useFocusTrap
+ * Focus trap hook for modals and dialogs
+ */
+/**
+ * Props for useFocusTrap
+ */
+interface UseFocusTrapProps {
+    /**
+     * Whether the focus trap is active
+     */
+    isActive: boolean;
+    /**
+     * Callback when Escape key is pressed
+     */
+    onEscape?: () => void;
+    /**
+     * Whether to restore focus when trap is deactivated
+     * @default true
+     */
+    restoreFocus?: boolean;
+    /**
+     * Whether to auto-focus first element when activated
+     * @default true
+     */
+    autoFocus?: boolean;
+}
+/**
+ * Return type
+ */
+interface UseFocusTrapReturn {
+    /**
+     * Ref to attach to the container element
+     */
+    trapRef: React.RefObject<HTMLElement | null>;
+}
+/**
+ * Hook for creating focus traps
+ *
+ * Features:
+ * - Traps Tab/Shift+Tab within container
+ * - Handles Escape key
+ * - Restores focus on deactivation
+ * - Auto-focuses first element
+ * - Development-time validation
+ *
+ * @example
+ * ```tsx
+ * const { trapRef } = useFocusTrap({
+ *   isActive: isOpen,
+ *   onEscape: () => setIsOpen(false),
+ * });
+ *
+ * return (
+ *   <div ref={trapRef} role="dialog">
+ *     <button>Close</button>
+ *   </div>
+ * );
+ * ```
+ */
+declare const useFocusTrap: (props: UseFocusTrapProps) => UseFocusTrapReturn;
+
+/**
+ * @a13y/react - useKeyboardNavigation
+ * Roving tabindex keyboard navigation hook
+ */
+/**
+ * Navigation orientation
+ */
+type Orientation = 'horizontal' | 'vertical' | 'both';
+/**
+ * Props for useKeyboardNavigation
+ */
+interface UseKeyboardNavigationProps {
+    /**
+     * Navigation orientation
+     * - 'horizontal': Arrow Left/Right
+     * - 'vertical': Arrow Up/Down
+     * - 'both': All arrow keys
+     */
+    orientation: Orientation;
+    /**
+     * Whether to loop at boundaries
+     * @default false
+     */
+    loop?: boolean;
+    /**
+     * Callback when navigation occurs
+     */
+    onNavigate?: (index: number) => void;
+    /**
+     * Initial focused index
+     * @default 0
+     */
+    defaultIndex?: number;
+    /**
+     * Controlled current index
+     */
+    currentIndex?: number;
+}
+/**
+ * Item props for navigable items
+ */
+interface NavigableItemProps {
+    ref: (element: HTMLElement | null) => void;
+    tabIndex: number;
+    onKeyDown: (event: React.KeyboardEvent) => void;
+    'data-index': number;
+}
+/**
+ * Return type
+ */
+interface UseKeyboardNavigationReturn {
+    /**
+     * Current focused index
+     */
+    currentIndex: number;
+    /**
+     * Navigate to specific index
+     */
+    setCurrentIndex: (index: number) => void;
+    /**
+     * Get props for navigable item
+     */
+    getItemProps: (index: number) => NavigableItemProps;
+    /**
+     * Container props
+     */
+    containerProps: {
+        role: 'toolbar' | 'listbox' | 'menu';
+        'aria-orientation': Orientation;
+    };
+}
+/**
+ * Hook for keyboard navigation with roving tabindex
+ *
+ * Features:
+ * - Arrow key navigation
+ * - Home/End navigation
+ * - Roving tabindex pattern
+ * - Automatic focus management
+ * - Development-time validation
+ *
+ * @example
+ * ```tsx
+ * const { containerProps, getItemProps, currentIndex } =
+ *   useKeyboardNavigation({
+ *     orientation: 'horizontal',
+ *     loop: true,
+ *   });
+ *
+ * return (
+ *   <div {...containerProps}>
+ *     {items.map((item, index) => (
+ *       <button key={index} {...getItemProps(index)}>
+ *         {item.label}
+ *       </button>
+ *     ))}
+ *   </div>
+ * );
+ * ```
+ */
+declare const useKeyboardNavigation: (props: UseKeyboardNavigationProps) => UseKeyboardNavigationReturn;
+
+/**
+ * @a13y/react - useAccessibleForm Hook
+ * Form management with accessibility built-in
+ */
+/**
+ * Field-level validation function
+ */
+type FieldValidator<T> = (value: T) => string | true;
+/**
+ * Form-level validation function (for cross-field validation)
+ */
+type FormValidator<T> = (values: T) => Record<string, string> | null;
+/**
+ * Field configuration
+ */
+interface FieldConfig<T> {
+    /**
+     * Initial value
+     */
+    initialValue: T;
+    /**
+     * Validation function (optional)
+     * Return true if valid, or error message if invalid
+     */
+    validate?: FieldValidator<T>;
+    /**
+     * Required field
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Custom required message
+     */
+    requiredMessage?: string;
+}
+/**
+ * Form configuration
+ */
+interface FormConfig<T extends Record<string, unknown>> {
+    /**
+     * Field configurations
+     */
+    fields: {
+        [K in keyof T]: FieldConfig<T[K]>;
+    };
+    /**
+     * Form-level validation (optional)
+     * For cross-field validation
+     */
+    validate?: FormValidator<T>;
+    /**
+     * Called when form is successfully submitted
+     */
+    onSubmit: (values: T) => void | Promise<void>;
+    /**
+     * Auto-focus first error on validation failure
+     * @default true
+     */
+    autoFocusError?: boolean;
+    /**
+     * Announce errors to screen readers
+     * @default true
+     */
+    announceErrors?: boolean;
+    /**
+     * Validate on blur
+     * @default true
+     */
+    validateOnBlur?: boolean;
+    /**
+     * Validate on change (after first blur)
+     * @default true
+     */
+    validateOnChange?: boolean;
+}
+/**
+ * Form state
+ */
+interface FormState<T extends Record<string, unknown>> {
+    /**
+     * Current form values
+     */
+    values: T;
+    /**
+     * Field errors
+     */
+    errors: Partial<Record<keyof T, string>>;
+    /**
+     * Fields that have been touched (blurred at least once)
+     */
+    touched: Partial<Record<keyof T, boolean>>;
+    /**
+     * Is form submitting
+     */
+    isSubmitting: boolean;
+    /**
+     * Is form valid (no errors)
+     */
+    isValid: boolean;
+    /**
+     * Has form been submitted at least once
+     */
+    hasSubmitted: boolean;
+}
+/**
+ * Field props for binding to input elements
+ */
+interface FieldProps<T> {
+    name: string;
+    value: T;
+    onChange: (value: T) => void;
+    onBlur: () => void;
+    'aria-invalid': boolean;
+    'aria-describedby'?: string;
+    'aria-required'?: boolean;
+}
+/**
+ * Form return value
+ */
+interface UseAccessibleFormReturn<T extends Record<string, unknown>> {
+    /**
+     * Form state
+     */
+    state: FormState<T>;
+    /**
+     * Get props for a field
+     */
+    getFieldProps: <K extends keyof T>(name: K, options?: {
+        'aria-describedby'?: string;
+    }) => FieldProps<T[K]>;
+    /**
+     * Set field value programmatically
+     */
+    setFieldValue: <K extends keyof T>(name: K, value: T[K]) => void;
+    /**
+     * Set field error programmatically
+     */
+    setFieldError: <K extends keyof T>(name: K, error: string) => void;
+    /**
+     * Set multiple field errors at once
+     */
+    setErrors: (errors: Partial<Record<keyof T, string>>) => void;
+    /**
+     * Validate a single field
+     */
+    validateField: <K extends keyof T>(name: K) => boolean;
+    /**
+     * Validate entire form
+     */
+    validateForm: () => boolean;
+    /**
+     * Handle form submit
+     */
+    handleSubmit: (e?: React.FormEvent) => void;
+    /**
+     * Reset form to initial values
+     */
+    reset: () => void;
+    /**
+     * Clear all errors
+     */
+    clearErrors: () => void;
+    /**
+     * Field refs for focus management
+     */
+    fieldRefs: Map<keyof T, HTMLElement>;
+}
+/**
+ * useAccessibleForm Hook
+ *
+ * Comprehensive form management with accessibility built-in:
+ * - Automatic error announcements to screen readers
+ * - Auto-focus first error field on validation failure
+ * - Required field validation
+ * - Field-level and form-level validation
+ * - aria-invalid and aria-describedby management
+ * - Touch tracking for better UX
+ *
+ * Pattern Explanation:
+ * - Each field gets automatic ARIA attributes
+ * - Errors are announced via screen reader
+ * - First error field receives focus on submit
+ * - Validation can run on blur or change
+ * - Required fields enforced via TypeScript
+ *
+ * @example
+ * ```tsx
+ * const form = useAccessibleForm({
+ *   fields: {
+ *     email: {
+ *       initialValue: '',
+ *       required: true,
+ *       validate: (value) => {
+ *         if (!value.includes('@')) return 'Invalid email';
+ *         return true;
+ *       },
+ *     },
+ *     password: {
+ *       initialValue: '',
+ *       required: true,
+ *       validate: (value) => {
+ *         if (value.length < 8) return 'Password must be at least 8 characters';
+ *         return true;
+ *       },
+ *     },
+ *   },
+ *   onSubmit: (values) => {
+ *     console.log('Form submitted:', values);
+ *   },
+ * });
+ *
+ * return (
+ *   <form onSubmit={form.handleSubmit}>
+ *     <input {...form.getFieldProps('email')} type="email" />
+ *     {form.state.errors.email && (
+ *       <span id="email-error">{form.state.errors.email}</span>
+ *     )}
+ *   </form>
+ * );
+ * ```
+ */
+declare const useAccessibleForm: <T extends Record<string, unknown>>(config: FormConfig<T>) => UseAccessibleFormReturn<T>;
+
+/**
+ * @a13y/react - useFormField Hook
+ * Individual form field management with accessibility built-in
+ */
+/**
+ * Props for useFormField
+ */
+interface UseFormFieldProps<T = string> {
+    /**
+     * Field label (required for accessibility)
+     * This will be used as the accessible name
+     */
+    label: string;
+    /**
+     * Initial field value
+     */
+    initialValue?: T;
+    /**
+     * Validation function
+     * Return true if valid, or error message if invalid
+     */
+    validate?: (value: T) => string | true;
+    /**
+     * Is field required
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Custom required message
+     */
+    requiredMessage?: string;
+    /**
+     * Help text to display
+     */
+    helpText?: string;
+    /**
+     * Validate on blur
+     * @default true
+     */
+    validateOnBlur?: boolean;
+    /**
+     * Validate on change (after first blur)
+     * @default true
+     */
+    validateOnChange?: boolean;
+    /**
+     * Announce errors to screen readers
+     * @default true
+     */
+    announceErrors?: boolean;
+    /**
+     * Called when value changes
+     */
+    onChange?: (value: T) => void;
+    /**
+     * Called when field is blurred
+     */
+    onBlur?: () => void;
+}
+/**
+ * Return value from useFormField
+ */
+interface UseFormFieldReturn<T = string> {
+    /**
+     * Field ID (generated)
+     */
+    id: string;
+    /**
+     * Label ID (generated)
+     */
+    labelId: string;
+    /**
+     * Error message ID (generated)
+     */
+    errorId: string;
+    /**
+     * Help text ID (generated)
+     */
+    helpTextId: string;
+    /**
+     * Current field value
+     */
+    value: T;
+    /**
+     * Current error message (if any)
+     */
+    error: string | null;
+    /**
+     * Has field been touched (blurred at least once)
+     */
+    isTouched: boolean;
+    /**
+     * Is field valid
+     */
+    isValid: boolean;
+    /**
+     * Set field value
+     */
+    setValue: (value: T) => void;
+    /**
+     * Set field error
+     */
+    setError: (error: string | null) => void;
+    /**
+     * Validate field
+     */
+    validate: () => boolean;
+    /**
+     * Clear error
+     */
+    clearError: () => void;
+    /**
+     * Reset field to initial value
+     */
+    reset: () => void;
+    /**
+     * Props for label element
+     */
+    labelProps: {
+        id: string;
+        htmlFor: string;
+    };
+    /**
+     * Props for input element
+     */
+    inputProps: {
+        id: string;
+        name: string;
+        value: T;
+        onChange: (value: T) => void;
+        onBlur: () => void;
+        'aria-labelledby': string;
+        'aria-describedby'?: string;
+        'aria-invalid': boolean;
+        'aria-required'?: boolean;
+        ref: React.RefObject<HTMLInputElement | null>;
+    };
+    /**
+     * Props for error message element
+     */
+    errorProps: {
+        id: string;
+        role: 'alert';
+        'aria-live': 'polite';
+    };
+    /**
+     * Props for help text element
+     */
+    helpTextProps: {
+        id: string;
+    };
+    /**
+     * Field ref for focus management
+     */
+    fieldRef: React.RefObject<HTMLInputElement | null>;
+}
+/**
+ * useFormField Hook
+ *
+ * Manages a single form field with accessibility built-in:
+ * - Required label via TypeScript
+ * - Automatic ARIA attributes
+ * - Error announcements to screen readers
+ * - Help text support
+ * - Validation on blur/change
+ * - ID generation for ARIA relationships
+ *
+ * Pattern Explanation:
+ * - Label is required (enforced at compile-time)
+ * - aria-labelledby automatically connects label to input
+ * - aria-describedby automatically connects errors and help text
+ * - aria-invalid automatically set when error exists
+ * - Errors announced to screen readers when they appear
+ *
+ * @example
+ * ```tsx
+ * const emailField = useFormField({
+ *   label: 'Email Address',
+ *   required: true,
+ *   validate: (value) => {
+ *     if (!value.includes('@')) return 'Invalid email address';
+ *     return true;
+ *   },
+ *   helpText: 'We will never share your email',
+ * });
+ *
+ * return (
+ *   <div>
+ *     <label {...emailField.labelProps}>{emailField.label}</label>
+ *     <input
+ *       {...emailField.inputProps}
+ *       type="email"
+ *       onChange={(e) => emailField.inputProps.onChange(e.target.value)}
+ *     />
+ *     {emailField.helpText && (
+ *       <span {...emailField.helpTextProps}>{emailField.helpText}</span>
+ *     )}
+ *     {emailField.error && (
+ *       <span {...emailField.errorProps}>{emailField.error}</span>
+ *     )}
+ *   </div>
+ * );
+ * ```
+ */
+declare const useFormField: <T = string>(props: UseFormFieldProps<T>) => UseFormFieldReturn<T>;
+/**
+ * Helper type to ensure label is provided
+ * Use this in component props to enforce accessible labels
+ */
+type RequireLabel<T> = T & {
+    label: string;
+};
+
+export { type DialogBackdropProps, type DialogContainerProps, type DialogDescriptionProps, type DialogTitleProps, type FieldConfig, type FieldProps, type FieldValidator, type FormConfig, type FormState, type FormValidator, type NavigableItemProps, type RequireLabel, type UseAccessibleDialogProps, type UseAccessibleDialogReturn, type UseAccessibleFormReturn, type UseFocusTrapProps, type UseFocusTrapReturn, type UseFormFieldProps, type UseFormFieldReturn, type UseKeyboardNavigationProps, type UseKeyboardNavigationReturn, useAccessibleDialog, useAccessibleForm, useFocusTrap, useFormField, useKeyboardNavigation };