@a13y/react 0.1.0

package/dist/patterns/index.d.ts

@@ -0,0 +1,539 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Dialog in the stack
+ */
+interface StackedDialog {
+    id: string;
+    title: string;
+    content: ReactNode;
+    description?: string;
+    onClose: () => void;
+    zIndex: number;
+}
+/**
+ * Dialog stack context
+ */
+interface DialogStackContextValue {
+    /**
+     * Push a new dialog onto the stack
+     */
+    push: (dialog: Omit<StackedDialog, 'zIndex'>) => void;
+    /**
+     * Pop the topmost dialog
+     */
+    pop: () => void;
+    /**
+     * Close a specific dialog by ID
+     */
+    close: (id: string) => void;
+    /**
+     * Close all dialogs
+     */
+    closeAll: () => void;
+    /**
+     * Current stack depth
+     */
+    depth: number;
+}
+/**
+ * Hook to access dialog stack
+ */
+declare const useDialogStack: () => DialogStackContextValue;
+/**
+ * Props for DialogStackProvider
+ */
+interface DialogStackProviderProps {
+    children: ReactNode;
+    /**
+     * Base z-index for dialogs
+     * @default 1000
+     */
+    baseZIndex?: number;
+    /**
+     * Z-index increment between layers
+     * @default 10
+     */
+    zIndexIncrement?: number;
+}
+/**
+ * Dialog Stack Provider
+ *
+ * Manages a stack of nested dialogs with:
+ * - Automatic z-index management
+ * - Focus restoration chain
+ * - Escape key closes topmost dialog only
+ * - Backdrop isolation per layer
+ *
+ * Pattern Explanation:
+ * - Each dialog gets a unique z-index: base + (depth * increment)
+ * - Focus is trapped in the topmost dialog
+ * - When a dialog closes, focus returns to the previous dialog
+ * - Escape key only affects the topmost dialog
+ * - Body scroll is locked when any dialog is open
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <DialogStackProvider>
+ *       <MyComponent />
+ *     </DialogStackProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const { push, pop } = useDialogStack();
+ *
+ *   return (
+ *     <button onClick={() => push({
+ *       id: 'dialog1',
+ *       title: 'First Dialog',
+ *       content: <SecondLevelDialog />,
+ *       onClose: () => pop(),
+ *     })}>
+ *       Open Dialog
+ *     </button>
+ *   );
+ * }
+ *
+ * function SecondLevelDialog() {
+ *   const { push, pop } = useDialogStack();
+ *
+ *   return (
+ *     <button onClick={() => push({
+ *       id: 'dialog2',
+ *       title: 'Nested Dialog',
+ *       content: <p>This is nested!</p>,
+ *       onClose: () => pop(),
+ *     })}>
+ *       Open Nested Dialog
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare const DialogStackProvider: (props: DialogStackProviderProps) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Props for InfiniteList
+ */
+interface InfiniteListProps<T> {
+    /**
+     * Current items in the list
+     */
+    items: T[];
+    /**
+     * Function to load more items
+     * Should return a promise that resolves to new items
+     */
+    loadMore: () => Promise<T[]>;
+    /**
+     * Check if there are more items to load
+     */
+    hasMore: boolean;
+    /**
+     * Check if currently loading
+     */
+    isLoading: boolean;
+    /**
+     * Render function for each item
+     */
+    renderItem: (item: T, index: number) => ReactNode;
+    /**
+     * Unique key extractor
+     */
+    getItemKey: (item: T, index: number) => string;
+    /**
+     * Loading indicator
+     */
+    loadingIndicator?: ReactNode;
+    /**
+     * Empty state
+     */
+    emptyState?: ReactNode;
+    /**
+     * Accessible label for the list
+     */
+    'aria-label': string;
+    /**
+     * Distance from bottom to trigger load (px)
+     * @default 200
+     */
+    threshold?: number;
+    /**
+     * Custom className
+     */
+    className?: string;
+}
+/**
+ * Infinite List Component
+ *
+ * Accessible infinite scroll with:
+ * - Intersection Observer for lazy loading
+ * - Screen reader announcements for new items
+ * - Keyboard navigation (Tab through items)
+ * - Loading states announced
+ * - Total count announcements
+ *
+ * Pattern Explanation:
+ * - Uses Intersection Observer to detect when user scrolls near bottom
+ * - Announces new items loaded to screen readers
+ * - Maintains focus position when new items are added
+ * - Works with keyboard navigation (no mouse required)
+ * - Provides loading and empty states
+ *
+ * @example
+ * ```tsx
+ * const [items, setItems] = useState<Item[]>([]);
+ * const [hasMore, setHasMore] = useState(true);
+ * const [isLoading, setIsLoading] = useState(false);
+ *
+ * const loadMore = async () => {
+ *   setIsLoading(true);
+ *   const newItems = await fetchItems(items.length, 20);
+ *   setItems([...items, ...newItems]);
+ *   setHasMore(newItems.length === 20);
+ *   setIsLoading(false);
+ *   return newItems;
+ * };
+ *
+ * return (
+ *   <InfiniteList
+ *     items={items}
+ *     loadMore={loadMore}
+ *     hasMore={hasMore}
+ *     isLoading={isLoading}
+ *     renderItem={(item) => <ItemCard item={item} />}
+ *     getItemKey={(item) => item.id}
+ *     aria-label="Products list"
+ *   />
+ * );
+ * ```
+ */
+declare const InfiniteList: <T>(props: InfiniteListProps<T>) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Menu item with optional submenu
+ */
+interface NestedMenuItem {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    disabled?: boolean;
+    /**
+     * Action when item is selected
+     * Omit for items with submenu
+     */
+    onPress?: () => void;
+    /**
+     * Submenu items
+     */
+    submenu?: NestedMenuItem[];
+}
+/**
+ * Props for NestedMenu
+ */
+interface NestedMenuProps {
+    /**
+     * Menu trigger label for screen readers
+     */
+    label: string;
+    /**
+     * Trigger content
+     */
+    trigger: ReactNode;
+    /**
+     * Menu items (can have nested submenus)
+     */
+    items: NestedMenuItem[];
+    /**
+     * Custom className for trigger
+     */
+    className?: string;
+}
+/**
+ * Nested Menu Component
+ *
+ * Multi-level dropdown menu with full keyboard navigation:
+ * - Arrow Up/Down: Navigate items
+ * - Arrow Right: Open submenu
+ * - Arrow Left: Close submenu and return to parent
+ * - Enter/Space: Select item or open submenu
+ * - Escape: Close current menu level
+ *
+ * Pattern Explanation:
+ * - Each submenu level maintains its own navigation state
+ * - Arrow Right on item with submenu opens it
+ * - Arrow Left closes submenu and returns focus to parent item
+ * - Screen readers announce submenu availability via aria-haspopup
+ * - Submenus are positioned relative to parent items
+ * - Focus is trapped within the active menu level
+ *
+ * @example
+ * ```tsx
+ * <NestedMenu
+ *   label="File menu"
+ *   trigger="File ▼"
+ *   items={[
+ *     {
+ *       id: 'new',
+ *       label: 'New',
+ *       submenu: [
+ *         { id: 'file', label: 'File', onPress: () => console.log('New File') },
+ *         { id: 'folder', label: 'Folder', onPress: () => console.log('New Folder') },
+ *       ],
+ *     },
+ *     { id: 'open', label: 'Open', onPress: () => console.log('Open') },
+ *     {
+ *       id: 'recent',
+ *       label: 'Open Recent',
+ *       submenu: [
+ *         { id: 'file1', label: 'document.txt', onPress: () => {} },
+ *         { id: 'file2', label: 'project.json', onPress: () => {} },
+ *       ],
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
+declare const NestedMenu: (props: NestedMenuProps) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Props for VirtualizedList
+ */
+interface VirtualizedListProps<T> {
+    /**
+     * All items in the list
+     */
+    items: T[];
+    /**
+     * Height of each item (fixed)
+     */
+    itemHeight: number;
+    /**
+     * Height of the visible container
+     */
+    height: number;
+    /**
+     * Render function for each item
+     */
+    renderItem: (item: T, index: number) => ReactNode;
+    /**
+     * Unique key extractor
+     */
+    getItemKey: (item: T, index: number) => string;
+    /**
+     * Accessible label for the list
+     */
+    'aria-label': string;
+    /**
+     * Number of items to render outside viewport (overscan)
+     * @default 3
+     */
+    overscan?: number;
+    /**
+     * Custom className
+     */
+    className?: string;
+    /**
+     * Empty state
+     */
+    emptyState?: ReactNode;
+}
+/**
+ * Virtualized List Component
+ *
+ * Accessible virtualized list that works with screen readers:
+ * - Only renders visible items + overscan
+ * - Maintains total height for scrollbar
+ * - Announces visible range to screen readers
+ * - Keyboard navigation works correctly
+ * - Focus management when scrolling
+ *
+ * Pattern Explanation:
+ * - Calculates visible range based on scroll position
+ * - Renders only visible items + overscan buffer
+ * - Uses absolute positioning to maintain item positions
+ * - Announces visible range changes to screen readers
+ * - Total height maintained for accurate scrollbar
+ * - Works with keyboard navigation (Page Up/Down, Home/End)
+ *
+ * Screen Reader Strategy:
+ * - aria-setsize and aria-posinset tell screen readers total count
+ * - Visible range announced when user scrolls
+ * - Focus is maintained when items are virtualized
+ *
+ * @example
+ * ```tsx
+ * const items = Array.from({ length: 10000 }, (_, i) => ({
+ *   id: i,
+ *   name: `Item ${i}`,
+ * }));
+ *
+ * return (
+ *   <VirtualizedList
+ *     items={items}
+ *     itemHeight={48}
+ *     height={600}
+ *     renderItem={(item) => (
+ *       <div style={{ padding: '0.75rem' }}>
+ *         {item.name}
+ *       </div>
+ *     )}
+ *     getItemKey={(item) => item.id.toString()}
+ *     aria-label="Large list of items"
+ *   />
+ * );
+ * ```
+ */
+declare const VirtualizedList: <T>(props: VirtualizedListProps<T>) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Wizard step definition
+ */
+interface WizardStep {
+    /**
+     * Unique step ID
+     */
+    id: string;
+    /**
+     * Step label (shown in progress indicator)
+     */
+    label: string;
+    /**
+     * Step content
+     */
+    content: ReactNode;
+    /**
+     * Optional validation before proceeding
+     * Return true if valid, or error message if invalid
+     */
+    validate?: () => true | string;
+    /**
+     * Whether this step can be skipped
+     */
+    optional?: boolean;
+}
+/**
+ * Wizard context value
+ */
+interface WizardContextValue {
+    /**
+     * Current step index
+     */
+    currentStep: number;
+    /**
+     * Total number of steps
+     */
+    totalSteps: number;
+    /**
+     * Current step data
+     */
+    step: WizardStep;
+    /**
+     * Navigate to next step
+     */
+    next: () => void;
+    /**
+     * Navigate to previous step
+     */
+    previous: () => void;
+    /**
+     * Navigate to specific step (if valid)
+     */
+    goToStep: (index: number) => void;
+    /**
+     * Check if can go to next step
+     */
+    canGoNext: boolean;
+    /**
+     * Check if can go to previous step
+     */
+    canGoPrevious: boolean;
+    /**
+     * Check if on last step
+     */
+    isLastStep: boolean;
+    /**
+     * Validation error (if any)
+     */
+    validationError: string | null;
+}
+/**
+ * Hook to access wizard context
+ */
+declare const useWizard: () => WizardContextValue;
+/**
+ * Props for Wizard
+ */
+interface WizardProps {
+    /**
+     * Wizard steps (must have at least one)
+     */
+    steps: [WizardStep, ...WizardStep[]];
+    /**
+     * Called when wizard is completed
+     */
+    onComplete: () => void;
+    /**
+     * Called when wizard is cancelled
+     */
+    onCancel?: () => void;
+    /**
+     * Initial step index
+     */
+    initialStep?: number;
+    /**
+     * Custom className
+     */
+    className?: string;
+}
+/**
+ * Wizard Component
+ *
+ * Multi-step form with:
+ * - Progress indicator
+ * - Keyboard navigation (arrows, Home, End)
+ * - Step validation
+ * - Screen reader announcements
+ * - Focus management between steps
+ *
+ * Pattern Explanation:
+ * - Each step can have validation before proceeding
+ * - Arrow keys navigate between steps (if valid)
+ * - Progress indicator shows current position
+ * - Screen readers announce step changes
+ * - Optional steps can be skipped
+ * - Validation errors are announced to screen readers
+ *
+ * @example
+ * ```tsx
+ * <Wizard
+ *   steps={[
+ *     {
+ *       id: 'account',
+ *       label: 'Account Info',
+ *       content: <AccountForm />,
+ *       validate: () => isValidEmail(email) || 'Invalid email',
+ *     },
+ *     {
+ *       id: 'preferences',
+ *       label: 'Preferences',
+ *       content: <PreferencesForm />,
+ *       optional: true,
+ *     },
+ *     {
+ *       id: 'review',
+ *       label: 'Review',
+ *       content: <ReviewScreen />,
+ *     },
+ *   ]}
+ *   onComplete={() => console.log('Wizard completed!')}
+ * />
+ * ```
+ */
+declare const Wizard: (props: WizardProps) => react_jsx_runtime.JSX.Element;
+
+export { DialogStackProvider, type DialogStackProviderProps, InfiniteList, type InfiniteListProps, NestedMenu, type NestedMenuItem, type NestedMenuProps, VirtualizedList, type VirtualizedListProps, Wizard, type WizardProps, type WizardStep, useDialogStack, useWizard };