@a11y-core/react 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,402 @@
+import * as React$1 from 'react';
+import React__default from 'react';
+import { FocusTrapOptions, AnnouncerOptions, KeyboardHandlers } from '@a11y-core/core';
+export { announce, announceAssertive, announceError, announcePolite, announceProgress, announceStatus, aria, buildAriaProps, checks, createComponentWarnings, hasAccessibleName, isAndroid, isBrowser, isIOS, isMac, mergeAriaIds, prefersDarkMode, prefersHighContrast, prefersReducedMotion, setWarningHandler, warn } from '@a11y-core/core';
+export { DialogCompound as Dialog, DialogActions, DialogActionsProps, Dialog as DialogBase, DialogClose, DialogCloseProps, DialogContent, DialogContentProps, DialogContextValue, DialogDescription, DialogDescriptionProps, DialogProps, DialogTitle, DialogTitleProps, DialogTrigger, DialogTriggerProps, useDialogContext } from './components/dialog/index.js';
+export { ActionMenuCompound as ActionMenu, ActionMenu as ActionMenuBase, ActionMenuContent, ActionMenuContentProps, ActionMenuContextValue, ActionMenuItem, ActionMenuItemProps, ActionMenuLabel, ActionMenuLabelProps, ActionMenuProps, ActionMenuSeparator, ActionMenuSeparatorProps, ActionMenuTrigger, ActionMenuTriggerProps, useActionMenuContext } from './components/menu/index.js';
+export { Tab, TabList, TabListProps, TabPanel, TabPanelProps, TabProps, TabsCompound as Tabs, Tabs as TabsBase, TabsContextValue, TabsProps, useTabsContext } from './components/tabs/index.js';
+export { Toast, ToastProvider, ToastProviderProps, ToastType, ToastViewport, ToastViewportProps, useToast, useToastHelpers } from './components/toast/index.js';
+export { ComboboxCompound as Combobox, Combobox as ComboboxBase, ComboboxInput, ComboboxInputProps, ComboboxListbox, ComboboxListboxProps, ComboboxOption, ComboboxOptionProps, ComboboxOption as ComboboxOptionType, ComboboxProps } from './components/combobox/index.js';
+import 'react/jsx-runtime';
+
+/**
+ * Generate a unique ID for accessibility purposes
+ *
+ * Uses React's useId when available, with a fallback for SSR
+ */
+declare function useId(prefix?: string): string;
+/**
+ * Generate multiple related IDs for a component
+ */
+declare function useIds<T extends readonly string[]>(parts: T, prefix?: string): Record<T[number], string>;
+/**
+ * Create a scoped ID generator for complex components
+ */
+declare function useIdScope(componentName: string): {
+    id: string;
+    generate: (suffix: string) => string;
+    generateMultiple: <T extends readonly string[]>(parts: T) => Record<T[number], string>;
+};
+
+interface UseFocusTrapOptions extends FocusTrapOptions {
+    /** Whether the focus trap is active */
+    active?: boolean;
+}
+/**
+ * Hook to create a focus trap for modals, dialogs, etc.
+ *
+ * @example
+ * ```tsx
+ * function Modal({ isOpen, onClose }) {
+ *   const trapRef = useFocusTrap({
+ *     active: isOpen,
+ *     onDeactivate: onClose,
+ *   });
+ *
+ *   return (
+ *     <div ref={trapRef} role="dialog">
+ *       <button>Close</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useFocusTrap<T extends HTMLElement = HTMLDivElement>(options?: UseFocusTrapOptions): React.RefObject<T>;
+/**
+ * Imperative focus trap controls
+ */
+declare function useFocusTrapControls<T extends HTMLElement = HTMLDivElement>(options?: Omit<FocusTrapOptions, 'onDeactivate'>): {
+    ref: React$1.MutableRefObject<T | null>;
+    activate: () => void;
+    deactivate: () => void;
+    pause: () => void;
+    unpause: () => void;
+    isActive: () => boolean;
+    isPaused: () => boolean;
+};
+
+/**
+ * Hook for screen reader announcements
+ *
+ * @example
+ * ```tsx
+ * function SearchResults({ results }) {
+ *   const { announce } = useAnnouncer();
+ *
+ *   useEffect(() => {
+ *     announce(`Found ${results.length} results`);
+ *   }, [results.length, announce]);
+ *
+ *   return <ul>...</ul>;
+ * }
+ * ```
+ */
+declare function useAnnouncer(): {
+    announce: (message: string, options?: AnnouncerOptions) => void;
+    polite: (message: string, options?: Omit<AnnouncerOptions, "politeness">) => void;
+    assertive: (message: string, options?: Omit<AnnouncerOptions, "politeness">) => void;
+    queue: (message: string, options?: AnnouncerOptions & {
+        debounce?: number;
+    }) => void;
+    clear: () => void;
+};
+/**
+ * Announce a message when a value changes
+ *
+ * @example
+ * ```tsx
+ * function Counter({ count }) {
+ *   useAnnounceOnChange(count, (value) => `Count is now ${value}`);
+ *   return <span>{count}</span>;
+ * }
+ * ```
+ */
+declare function useAnnounceOnChange<T>(value: T, getMessage: (value: T) => string, options?: AnnouncerOptions & {
+    skipInitial?: boolean;
+}): void;
+/**
+ * Announce loading states
+ *
+ * @example
+ * ```tsx
+ * function DataList({ isLoading }) {
+ *   useAnnounceLoading(isLoading, {
+ *     loadingMessage: 'Loading data...',
+ *     loadedMessage: 'Data loaded',
+ *   });
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare function useAnnounceLoading(isLoading: boolean, options?: {
+    loadingMessage?: string;
+    loadedMessage?: string;
+    errorMessage?: string;
+    error?: Error | null;
+}): void;
+
+/**
+ * Hook for keyboard event handling
+ *
+ * @example
+ * ```tsx
+ * function Menu({ items, onSelect }) {
+ *   const keyboardProps = useKeyboard({
+ *     ArrowDown: () => focusNext(),
+ *     ArrowUp: () => focusPrevious(),
+ *     Enter: () => onSelect(focused),
+ *     Escape: () => close(),
+ *   });
+ *
+ *   return <ul {...keyboardProps}>...</ul>;
+ * }
+ * ```
+ */
+declare function useKeyboard(handlers: KeyboardHandlers, options?: {
+    preventDefault?: boolean;
+    stopPropagation?: boolean;
+    disabled?: boolean;
+}): {
+    onKeyDown: (event: React.KeyboardEvent) => void;
+};
+/**
+ * Pre-built keyboard patterns for common widgets
+ */
+declare function useMenuKeyboard(options: {
+    onUp?: () => void;
+    onDown?: () => void;
+    onEnter?: () => void;
+    onEscape?: () => void;
+    onHome?: () => void;
+    onEnd?: () => void;
+    disabled?: boolean;
+}): {
+    onKeyDown: (event: React.KeyboardEvent) => void;
+};
+declare function useTabsKeyboard(options: {
+    onLeft?: () => void;
+    onRight?: () => void;
+    onHome?: () => void;
+    onEnd?: () => void;
+    disabled?: boolean;
+}): {
+    onKeyDown: (event: React.KeyboardEvent) => void;
+};
+declare function useGridKeyboard(options: {
+    onUp?: () => void;
+    onDown?: () => void;
+    onLeft?: () => void;
+    onRight?: () => void;
+    onHome?: () => void;
+    onEnd?: () => void;
+    onCtrlHome?: () => void;
+    onCtrlEnd?: () => void;
+    disabled?: boolean;
+}): {
+    onKeyDown: (event: React.KeyboardEvent) => void;
+};
+/**
+ * Hook for type-ahead search in menus/listboxes
+ *
+ * @example
+ * ```tsx
+ * function Listbox({ items }) {
+ *   const { onKeyDown, reset } = useTypeAhead(
+ *     items.map(i => i.label),
+ *     (match) => focusItem(match)
+ *   );
+ *
+ *   return <ul onKeyDown={onKeyDown}>...</ul>;
+ * }
+ * ```
+ */
+declare function useTypeAhead(items: string[], onMatch: (match: string) => void, options?: {
+    timeout?: number;
+    disabled?: boolean;
+}): {
+    onKeyDown: (event: React.KeyboardEvent) => void;
+    reset: () => void;
+    getSearch: () => string;
+};
+/**
+ * Hook for tracking which key is currently pressed
+ * Useful for showing keyboard shortcuts or modifier states
+ */
+declare function useKeyPressed(targetKey: string): boolean;
+
+/**
+ * Hook to detect if focus should be visible (keyboard navigation)
+ *
+ * @example
+ * ```tsx
+ * function Button({ children }) {
+ *   const { isFocusVisible, focusProps } = useFocusVisible();
+ *
+ *   return (
+ *     <button
+ *       {...focusProps}
+ *       className={isFocusVisible ? 'focus-ring' : ''}
+ *     >
+ *       {children}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useFocusVisible(): {
+    isFocusVisible: boolean;
+    focusProps: {
+        onFocus: () => void;
+        onBlur: () => void;
+    };
+};
+/**
+ * Hook for managing focus on a specific element
+ *
+ * @example
+ * ```tsx
+ * function Combobox() {
+ *   const inputRef = useFocusManager<HTMLInputElement>({
+ *     autoFocus: true,
+ *   });
+ *
+ *   return <input ref={inputRef} />;
+ * }
+ * ```
+ */
+declare function useFocusManager<T extends HTMLElement = HTMLElement>(options?: {
+    autoFocus?: boolean;
+    restoreFocus?: boolean;
+    focusVisible?: boolean;
+}): (node: T | null) => void;
+/**
+ * Focus an element programmatically with proper focus-visible handling
+ */
+declare function useFocusControl<T extends HTMLElement = HTMLElement>(): {
+    ref: (_node: T | null) => void;
+    focus: (options?: {
+        visible?: boolean;
+    }) => void;
+};
+/**
+ * Track if an element has focus
+ */
+declare function useFocusWithin<T extends HTMLElement = HTMLElement>(): {
+    ref: (instance: T | null) => void | React$1.DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof React$1.DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES];
+    hasFocus: boolean;
+    focusWithinProps: {
+        onFocus: () => void;
+        onBlur: (event: React.FocusEvent) => void;
+    };
+};
+
+interface UseRovingTabindexOptions {
+    /** Initial active index */
+    initialIndex?: number;
+    /** Whether navigation wraps around */
+    wrap?: boolean;
+    /** Orientation for arrow keys */
+    orientation?: 'horizontal' | 'vertical' | 'both';
+    /** Called when active index changes */
+    onChange?: (index: number) => void;
+}
+interface RovingTabindexItem {
+    /** Props to spread on the item element */
+    props: {
+        tabIndex: number;
+        onKeyDown: (event: React.KeyboardEvent) => void;
+        onFocus: () => void;
+    };
+    /** Whether this item is the active/focusable one */
+    isActive: boolean;
+}
+/**
+ * Hook for roving tabindex pattern
+ *
+ * @example
+ * ```tsx
+ * function Toolbar() {
+ *   const { getItemProps, activeIndex } = useRovingTabindex({
+ *     itemCount: 3,
+ *     orientation: 'horizontal',
+ *   });
+ *
+ *   return (
+ *     <div role="toolbar">
+ *       <button {...getItemProps(0)}>Cut</button>
+ *       <button {...getItemProps(1)}>Copy</button>
+ *       <button {...getItemProps(2)}>Paste</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useRovingTabindex(options: UseRovingTabindexOptions & {
+    itemCount: number;
+}): {
+    activeIndex: number;
+    setActiveIndex: (index: number) => void;
+    getItemProps: (index: number) => {
+        ref: (el: HTMLElement | null) => void;
+        tabIndex: number;
+        onKeyDown: (event: React.KeyboardEvent) => void;
+        onFocus: () => void;
+    };
+    first: () => void;
+    last: () => void;
+    next: () => void;
+    previous: () => void;
+};
+/**
+ * Simplified roving tabindex for items with known IDs
+ */
+declare function useRovingTabindexMap<T extends string>(ids: T[], options?: Omit<UseRovingTabindexOptions, 'itemCount'>): {
+    activeId: T | undefined;
+    getItemProps: (id: T) => {
+        ref: (el: HTMLElement | null) => void;
+        tabIndex: number;
+        onKeyDown: (event: React.KeyboardEvent) => void;
+        onFocus: () => void;
+    };
+    setActiveId: (id: T) => void;
+    activeIndex: number;
+    setActiveIndex: (index: number) => void;
+    first: () => void;
+    last: () => void;
+    next: () => void;
+    previous: () => void;
+};
+
+interface SwitchProps extends Omit<React__default.ButtonHTMLAttributes<HTMLButtonElement>, 'onChange' | 'role'> {
+    /** Controlled checked state */
+    checked?: boolean;
+    /** Default checked state (uncontrolled) */
+    defaultChecked?: boolean;
+    /** Called when the switch state changes */
+    onCheckedChange?: (checked: boolean) => void;
+    /** Accessible label for the switch (renders visible label next to switch) */
+    label?: string;
+    /** Whether the switch is disabled */
+    disabled?: boolean;
+    /** Remove default styles to allow full customization via className */
+    unstyled?: boolean;
+    /** Custom class name */
+    className?: string;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+}
+/**
+ * Switch component - An accessible toggle switch (on/off control)
+ *
+ * Follows WAI-ARIA Switch pattern with proper keyboard support and screen reader announcements.
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled
+ * <Switch defaultChecked={true} label="Enable notifications" />
+ *
+ * // Controlled
+ * <Switch
+ *   checked={enabled}
+ *   onCheckedChange={setEnabled}
+ *   aria-label="Dark mode"
+ * />
+ *
+ * // With visible label
+ * <Switch checked={enabled} onCheckedChange={setEnabled} label="Dark mode" />
+ * ```
+ */
+declare const Switch: React__default.ForwardRefExoticComponent<SwitchProps & React__default.RefAttributes<HTMLButtonElement>>;
+
+export { type RovingTabindexItem, Switch, type SwitchProps, type UseFocusTrapOptions, type UseRovingTabindexOptions, useAnnounceLoading, useAnnounceOnChange, useAnnouncer, useFocusControl, useFocusManager, useFocusTrap, useFocusTrapControls, useFocusVisible, useFocusWithin, useGridKeyboard, useId, useIdScope, useIds, useKeyPressed, useKeyboard, useMenuKeyboard, useRovingTabindex, useRovingTabindexMap, useTabsKeyboard, useTypeAhead };