@idealyst/components 1.1.3 → 1.1.5

package/src/utils/accessibility/keyboardPatterns.ts

@@ -0,0 +1,263 @@
+/**
+ * WCAG 2.1 keyboard patterns for common widgets.
+ * These constants define the standard key bindings for accessible interactions.
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/
+ */
+
+/**
+ * Keys for button activation.
+ * WCAG requirement: Buttons must be activatable with Enter and Space.
+ */
+export const BUTTON_KEYS = {
+  /** Keys that activate the button */
+  activate: ['Enter', ' '] as const,
+} as const;
+
+/**
+ * Keys for link activation.
+ * Links only use Enter (Space typically scrolls the page).
+ */
+export const LINK_KEYS = {
+  /** Keys that activate the link */
+  activate: ['Enter'] as const,
+} as const;
+
+/**
+ * Keys for menu navigation.
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/menu/
+ */
+export const MENU_KEYS = {
+  /** Keys that open the menu */
+  open: ['Enter', ' ', 'ArrowDown', 'ArrowUp'] as const,
+  /** Keys that close the menu */
+  close: ['Escape', 'Tab'] as const,
+  /** Keys for navigating between items */
+  navigateVertical: ['ArrowUp', 'ArrowDown'] as const,
+  /** Keys for navigating horizontal menus/menubars */
+  navigateHorizontal: ['ArrowLeft', 'ArrowRight'] as const,
+  /** Keys for selecting an item */
+  select: ['Enter', ' '] as const,
+  /** Keys for jumping to first item */
+  first: ['Home'] as const,
+  /** Keys for jumping to last item */
+  last: ['End'] as const,
+} as const;
+
+/**
+ * Keys for accordion navigation.
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
+ */
+export const ACCORDION_KEYS = {
+  /** Keys that toggle the accordion panel */
+  toggle: ['Enter', ' '] as const,
+  /** Keys for navigating between headers */
+  navigate: ['ArrowUp', 'ArrowDown'] as const,
+  /** Keys for jumping to first header */
+  first: ['Home'] as const,
+  /** Keys for jumping to last header */
+  last: ['End'] as const,
+} as const;
+
+/**
+ * Keys for tab navigation.
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
+ */
+export const TAB_KEYS = {
+  /** Keys that select a tab (when autoActivate is true, navigation also selects) */
+  select: ['Enter', ' '] as const,
+  /** Keys for navigating between tabs */
+  navigate: ['ArrowLeft', 'ArrowRight'] as const,
+  /** Keys for vertical tab lists */
+  navigateVertical: ['ArrowUp', 'ArrowDown'] as const,
+  /** Keys for jumping to first tab */
+  first: ['Home'] as const,
+  /** Keys for jumping to last tab */
+  last: ['End'] as const,
+} as const;
+
+/**
+ * Keys for slider/range control.
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/slider/
+ */
+export const SLIDER_KEYS = {
+  /** Keys that increase the value by step */
+  increase: ['ArrowRight', 'ArrowUp'] as const,
+  /** Keys that decrease the value by step */
+  decrease: ['ArrowLeft', 'ArrowDown'] as const,
+  /** Keys that increase the value by large step (typically 10x) */
+  increaseLarge: ['PageUp'] as const,
+  /** Keys that decrease the value by large step (typically 10x) */
+  decreaseLarge: ['PageDown'] as const,
+  /** Keys that set value to maximum */
+  max: ['End'] as const,
+  /** Keys that set value to minimum */
+  min: ['Home'] as const,
+} as const;
+
+/**
+ * Keys for listbox/select navigation.
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/listbox/
+ */
+export const LISTBOX_KEYS = {
+  /** Keys for navigating between options */
+  navigate: ['ArrowUp', 'ArrowDown'] as const,
+  /** Keys for selecting an option */
+  select: ['Enter', ' '] as const,
+  /** Keys that close the listbox (if popup) */
+  close: ['Escape'] as const,
+  /** Keys for jumping to first option */
+  first: ['Home'] as const,
+  /** Keys for jumping to last option */
+  last: ['End'] as const,
+  /** Keys that select all (multi-select only) */
+  selectAll: ['Control+a', 'Meta+a'] as const,
+} as const;
+
+/**
+ * Keys for dialog/modal.
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+ */
+export const DIALOG_KEYS = {
+  /** Keys that close the dialog */
+  close: ['Escape'] as const,
+} as const;
+
+/**
+ * Keys for checkbox control.
+ */
+export const CHECKBOX_KEYS = {
+  /** Keys that toggle the checkbox */
+  toggle: [' '] as const,
+} as const;
+
+/**
+ * Keys for radio group navigation.
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/radio/
+ */
+export const RADIO_KEYS = {
+  /** Keys for navigating and selecting in radio groups */
+  navigate: ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'] as const,
+} as const;
+
+/**
+ * Keys for switch/toggle control.
+ */
+export const SWITCH_KEYS = {
+  /** Keys that toggle the switch */
+  toggle: ['Enter', ' '] as const,
+} as const;
+
+/**
+ * Keys for tree view navigation.
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/treeview/
+ */
+export const TREE_KEYS = {
+  /** Keys for navigating between items */
+  navigate: ['ArrowUp', 'ArrowDown'] as const,
+  /** Keys for expanding a collapsed node */
+  expand: ['ArrowRight'] as const,
+  /** Keys for collapsing an expanded node */
+  collapse: ['ArrowLeft'] as const,
+  /** Keys for activating/selecting an item */
+  select: ['Enter', ' '] as const,
+  /** Keys for jumping to first item */
+  first: ['Home'] as const,
+  /** Keys for jumping to last visible item */
+  last: ['End'] as const,
+  /** Expand all siblings (Shift + *) */
+  expandAll: ['*'] as const,
+} as const;
+
+/**
+ * Keys for grid/table navigation.
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/grid/
+ */
+export const GRID_KEYS = {
+  /** Keys for moving between cells */
+  navigateCell: ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'] as const,
+  /** Keys for jumping to first cell in row */
+  rowStart: ['Home'] as const,
+  /** Keys for jumping to last cell in row */
+  rowEnd: ['End'] as const,
+  /** Keys for jumping to first cell in grid */
+  gridStart: ['Control+Home', 'Meta+Home'] as const,
+  /** Keys for jumping to last cell in grid */
+  gridEnd: ['Control+End', 'Meta+End'] as const,
+  /** Keys for page up/down in grid */
+  page: ['PageUp', 'PageDown'] as const,
+} as const;
+
+/**
+ * Keys for combobox navigation.
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+ */
+export const COMBOBOX_KEYS = {
+  /** Keys that open the dropdown */
+  open: ['ArrowDown', 'ArrowUp', 'Alt+ArrowDown'] as const,
+  /** Keys that close the dropdown */
+  close: ['Escape', 'Alt+ArrowUp'] as const,
+  /** Keys for navigating options */
+  navigate: ['ArrowUp', 'ArrowDown'] as const,
+  /** Keys for selecting an option */
+  select: ['Enter'] as const,
+  /** Keys for autocomplete */
+  first: ['Home'] as const,
+  last: ['End'] as const,
+} as const;
+
+/**
+ * Keys for tooltip display.
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/
+ */
+export const TOOLTIP_KEYS = {
+  /** Keys that dismiss the tooltip */
+  dismiss: ['Escape'] as const,
+} as const;
+
+/**
+ * Key code helper - checks if a keyboard event matches any of the specified keys.
+ * @param event - The keyboard event
+ * @param keys - Array of key names to check
+ * @returns true if the event key matches any of the specified keys
+ */
+export function matchesKey(event: { key: string }, keys: readonly string[]): boolean {
+  return keys.includes(event.key);
+}
+
+/**
+ * Key code helper with modifier support.
+ * @param event - The keyboard event
+ * @param keyPattern - Key pattern like 'Control+a' or 'Enter'
+ * @returns true if the event matches the pattern
+ */
+export function matchesKeyPattern(
+  event: { key: string; ctrlKey?: boolean; metaKey?: boolean; shiftKey?: boolean; altKey?: boolean },
+  keyPattern: string
+): boolean {
+  const parts = keyPattern.split('+');
+  const key = parts[parts.length - 1];
+  const modifiers = parts.slice(0, -1);
+
+  // Check the key
+  if (event.key !== key && event.key.toLowerCase() !== key.toLowerCase()) {
+    return false;
+  }
+
+  // Check modifiers
+  const requiresControl = modifiers.includes('Control');
+  const requiresMeta = modifiers.includes('Meta');
+  const requiresShift = modifiers.includes('Shift');
+  const requiresAlt = modifiers.includes('Alt');
+
+  if (requiresControl && !event.ctrlKey) return false;
+  if (requiresMeta && !event.metaKey) return false;
+  if (requiresShift && !event.shiftKey) return false;
+  if (requiresAlt && !event.altKey) return false;
+
+  // Ensure no extra modifiers are pressed (unless we're checking for ControlOrMeta)
+  if (!requiresControl && !requiresMeta && (event.ctrlKey || event.metaKey)) return false;
+  if (!requiresShift && event.shiftKey) return false;
+  if (!requiresAlt && event.altKey) return false;
+
+  return true;
+}

package/src/utils/accessibility/types.ts

@@ -0,0 +1,223 @@
+import type { AccessibilityRole as RNAccessibilityRole } from 'react-native';
+
+/**
+ * ARIA roles supported for cross-platform accessibility.
+ * Maps to native roles where possible via ariaHelpers.
+ */
+export type AriaRole =
+  // Interactive roles
+  | 'button'
+  | 'link'
+  | 'checkbox'
+  | 'radio'
+  | 'switch'
+  | 'slider'
+  | 'progressbar'
+  | 'spinbutton'
+  // Form roles
+  | 'textbox'
+  | 'searchbox'
+  | 'combobox'
+  | 'listbox'
+  | 'option'
+  // Menu roles
+  | 'menu'
+  | 'menuitem'
+  | 'menuitemcheckbox'
+  | 'menuitemradio'
+  // Tab roles
+  | 'tab'
+  | 'tablist'
+  | 'tabpanel'
+  // Dialog roles
+  | 'dialog'
+  | 'alertdialog'
+  | 'tooltip'
+  // Grid/table roles
+  | 'grid'
+  | 'row'
+  | 'cell'
+  | 'columnheader'
+  | 'rowheader'
+  | 'table'
+  // List roles
+  | 'list'
+  | 'listitem'
+  // Landmark roles
+  | 'article'
+  | 'region'
+  | 'navigation'
+  | 'main'
+  | 'banner'
+  | 'contentinfo'
+  | 'complementary'
+  | 'form'
+  | 'search'
+  // Live region roles
+  | 'status'
+  | 'alert'
+  | 'log'
+  | 'marquee'
+  | 'timer'
+  // Other roles
+  | 'img'
+  | 'figure'
+  | 'separator'
+  | 'none'
+  | 'presentation'
+  | 'heading'
+  | 'group';
+
+/**
+ * Base accessibility props shared across all components.
+ * These props provide essential screen reader and assistive technology support.
+ */
+export interface AccessibilityProps {
+  /** Text alternative for screen readers. Required for non-text content. */
+  accessibilityLabel?: string;
+  /** Additional hint text providing context (e.g., "Double tap to activate") */
+  accessibilityHint?: string;
+  /** Whether the element is disabled for assistive technology */
+  accessibilityDisabled?: boolean;
+  /** Whether the element is hidden from assistive technology */
+  accessibilityHidden?: boolean;
+  /** The semantic role of the element for assistive technology */
+  accessibilityRole?: AriaRole;
+}
+
+/**
+ * Accessibility props for interactive elements that can be activated or controlled.
+ * Extends base props with relationship and state attributes.
+ */
+export interface InteractiveAccessibilityProps extends AccessibilityProps {
+  /** ID of element that labels this element (aria-labelledby) */
+  accessibilityLabelledBy?: string;
+  /** ID of element that describes this element (aria-describedby) */
+  accessibilityDescribedBy?: string;
+  /** ID of element controlled by this element (aria-controls) */
+  accessibilityControls?: string;
+  /** Whether an expandable element is currently expanded */
+  accessibilityExpanded?: boolean;
+  /** Whether a toggle element is pressed (true, false, or 'mixed' for tri-state) */
+  accessibilityPressed?: boolean | 'mixed';
+  /** Whether this element owns another element (aria-owns) */
+  accessibilityOwns?: string;
+  /** Whether this element has a popup (aria-haspopup) */
+  accessibilityHasPopup?: boolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog';
+}
+
+/**
+ * Accessibility props for form controls.
+ * Extends interactive props with validation and requirement states.
+ */
+export interface FormAccessibilityProps extends InteractiveAccessibilityProps {
+  /** Whether the field is required */
+  accessibilityRequired?: boolean;
+  /** Whether the field has a validation error */
+  accessibilityInvalid?: boolean;
+  /** ID of element containing the error message (aria-errormessage) */
+  accessibilityErrorMessage?: string;
+  /** Autocomplete hint for the field */
+  accessibilityAutoComplete?: 'none' | 'inline' | 'list' | 'both';
+}
+
+/**
+ * Accessibility props for range controls (Slider, Progress, Spinbutton).
+ * Provides value information for screen readers.
+ */
+export interface RangeAccessibilityProps extends AccessibilityProps {
+  /** Current numeric value */
+  accessibilityValueNow?: number;
+  /** Minimum allowed value */
+  accessibilityValueMin?: number;
+  /** Maximum allowed value */
+  accessibilityValueMax?: number;
+  /** Human-readable value description (e.g., "50 percent", "Medium") */
+  accessibilityValueText?: string;
+}
+
+/**
+ * Accessibility props for selection controls (Checkbox, Radio, Switch).
+ * Extends interactive props with checked state.
+ */
+export interface SelectionAccessibilityProps extends InteractiveAccessibilityProps {
+  /** Whether the element is checked (true, false, or 'mixed' for indeterminate) */
+  accessibilityChecked?: boolean | 'mixed';
+}
+
+/**
+ * Accessibility props for live regions that announce dynamic content.
+ * Used for alerts, status messages, and real-time updates.
+ */
+export interface LiveRegionAccessibilityProps extends AccessibilityProps {
+  /** How updates should be announced: 'polite' waits, 'assertive' interrupts */
+  accessibilityLive?: 'off' | 'polite' | 'assertive';
+  /** Whether the region is currently loading/updating */
+  accessibilityBusy?: boolean;
+  /** Which changes should be announced */
+  accessibilityRelevant?: 'additions' | 'removals' | 'text' | 'all' | 'additions text';
+  /** Whether to announce the entire region or just changes */
+  accessibilityAtomic?: boolean;
+}
+
+/**
+ * Accessibility props for sortable columns in tables/grids.
+ */
+export interface SortableAccessibilityProps extends AccessibilityProps {
+  /** Current sort direction */
+  accessibilitySort?: 'ascending' | 'descending' | 'none' | 'other';
+}
+
+/**
+ * Accessibility props for selectable items in lists/grids.
+ */
+export interface SelectableAccessibilityProps extends AccessibilityProps {
+  /** Whether the item is currently selected */
+  accessibilitySelected?: boolean;
+  /** Position in the set (1-based) */
+  accessibilityPosInSet?: number;
+  /** Total number of items in the set */
+  accessibilitySetSize?: number;
+}
+
+/**
+ * Accessibility props for heading elements.
+ */
+export interface HeadingAccessibilityProps extends AccessibilityProps {
+  /** Heading level (1-6) for aria-level */
+  accessibilityLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+}
+
+/**
+ * Accessibility props for current/active navigation items.
+ */
+export interface CurrentAccessibilityProps extends AccessibilityProps {
+  /** Indicates the current item in a set (aria-current) */
+  accessibilityCurrent?: boolean | 'page' | 'step' | 'location' | 'date' | 'time';
+}
+
+/**
+ * React Native AccessibilityRole type re-export for convenience.
+ */
+export type NativeAccessibilityRole = RNAccessibilityRole;
+
+/**
+ * React Native accessibility state shape.
+ */
+export interface NativeAccessibilityState {
+  disabled?: boolean;
+  selected?: boolean;
+  checked?: boolean | 'mixed';
+  busy?: boolean;
+  expanded?: boolean;
+}
+
+/**
+ * React Native accessibility value shape.
+ */
+export interface NativeAccessibilityValue {
+  min?: number;
+  max?: number;
+  now?: number;
+  text?: string;
+}

package/src/utils/accessibility/useAnnounce.ts

@@ -0,0 +1,210 @@
+import { useCallback, useRef, useEffect } from 'react';
+
+/**
+ * Announcement priority level.
+ * - 'polite': Waits for current speech to finish before announcing
+ * - 'assertive': Interrupts current speech to announce immediately
+ */
+export type AnnounceMode = 'polite' | 'assertive';
+
+/**
+ * Options for the useAnnounce hook.
+ */
+export interface UseAnnounceOptions {
+  /** Default announcement mode (default: 'polite') */
+  defaultMode?: AnnounceMode;
+  /** Time in ms before clearing the announcement (default: 1000) */
+  clearDelay?: number;
+}
+
+/**
+ * Return type for the useAnnounce hook.
+ */
+export interface UseAnnounceReturn {
+  /** Announce a message with the specified mode */
+  announce: (message: string, mode?: AnnounceMode) => void;
+  /** Announce a message politely (waits for current speech) */
+  announcePolite: (message: string) => void;
+  /** Announce a message assertively (interrupts current speech) */
+  announceAssertive: (message: string) => void;
+  /** Clear any pending announcements */
+  clear: () => void;
+}
+
+/**
+ * Visually hidden styles for the live region.
+ * Element is hidden from view but readable by screen readers.
+ */
+const VISUALLY_HIDDEN_STYLES = `
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+`;
+
+/**
+ * Hook for announcing dynamic content to screen readers using ARIA live regions.
+ *
+ * Creates hidden live regions in the DOM that screen readers will announce
+ * when content changes. Useful for:
+ * - Form validation feedback
+ * - Loading state changes
+ * - Action confirmations
+ * - Dynamic content updates
+ *
+ * @example
+ * ```tsx
+ * const { announce, announceAssertive } = useAnnounce();
+ *
+ * const handleSubmit = async () => {
+ *   announce('Submitting form...');
+ *   try {
+ *     await submitForm();
+ *     announce('Form submitted successfully');
+ *   } catch (error) {
+ *     announceAssertive('Error submitting form. Please try again.');
+ *   }
+ * };
+ * ```
+ */
+export function useAnnounce(options: UseAnnounceOptions = {}): UseAnnounceReturn {
+  const { defaultMode = 'polite', clearDelay = 1000 } = options;
+
+  const politeRegionRef = useRef<HTMLDivElement | null>(null);
+  const assertiveRegionRef = useRef<HTMLDivElement | null>(null);
+  const clearTimeoutRef = useRef<ReturnType<typeof setTimeout>>();
+
+  /**
+   * Create a live region element.
+   */
+  const createLiveRegion = useCallback((mode: AnnounceMode): HTMLDivElement => {
+    const region = document.createElement('div');
+    region.setAttribute('aria-live', mode);
+    region.setAttribute('aria-atomic', 'true');
+    region.setAttribute('role', mode === 'assertive' ? 'alert' : 'status');
+    region.style.cssText = VISUALLY_HIDDEN_STYLES;
+    region.id = `a11y-live-region-${mode}`;
+    return region;
+  }, []);
+
+  // Create live regions on mount, clean up on unmount
+  useEffect(() => {
+    // Check if regions already exist (e.g., from another instance)
+    let politeRegion = document.getElementById('a11y-live-region-polite') as HTMLDivElement | null;
+    let assertiveRegion = document.getElementById('a11y-live-region-assertive') as HTMLDivElement | null;
+
+    if (!politeRegion) {
+      politeRegion = createLiveRegion('polite');
+      document.body.appendChild(politeRegion);
+    }
+    politeRegionRef.current = politeRegion;
+
+    if (!assertiveRegion) {
+      assertiveRegion = createLiveRegion('assertive');
+      document.body.appendChild(assertiveRegion);
+    }
+    assertiveRegionRef.current = assertiveRegion;
+
+    // Don't remove on unmount as other components may still use them
+    // The regions are shared across the application
+    return () => {
+      if (clearTimeoutRef.current) {
+        clearTimeout(clearTimeoutRef.current);
+      }
+    };
+  }, [createLiveRegion]);
+
+  /**
+   * Clear the live regions.
+   */
+  const clear = useCallback(() => {
+    if (clearTimeoutRef.current) {
+      clearTimeout(clearTimeoutRef.current);
+    }
+    if (politeRegionRef.current) {
+      politeRegionRef.current.textContent = '';
+    }
+    if (assertiveRegionRef.current) {
+      assertiveRegionRef.current.textContent = '';
+    }
+  }, []);
+
+  /**
+   * Announce a message to screen readers.
+   */
+  const announce = useCallback(
+    (message: string, mode: AnnounceMode = defaultMode) => {
+      const region = mode === 'assertive' ? assertiveRegionRef.current : politeRegionRef.current;
+      if (!region) return;
+
+      // Clear any pending timeout
+      if (clearTimeoutRef.current) {
+        clearTimeout(clearTimeoutRef.current);
+      }
+
+      // Clear first, then set - ensures re-announcement of same message
+      region.textContent = '';
+
+      // Use requestAnimationFrame to ensure the clear is processed first
+      requestAnimationFrame(() => {
+        region.textContent = message;
+      });
+
+      // Clear after delay to avoid accumulation
+      clearTimeoutRef.current = setTimeout(() => {
+        region.textContent = '';
+      }, clearDelay);
+    },
+    [defaultMode, clearDelay]
+  );
+
+  /**
+   * Announce a message politely (waits for current speech to finish).
+   */
+  const announcePolite = useCallback(
+    (message: string) => announce(message, 'polite'),
+    [announce]
+  );
+
+  /**
+   * Announce a message assertively (interrupts current speech).
+   */
+  const announceAssertive = useCallback(
+    (message: string) => announce(message, 'assertive'),
+    [announce]
+  );
+
+  return {
+    announce,
+    announcePolite,
+    announceAssertive,
+    clear,
+  };
+}
+
+/**
+ * React Native version of useAnnounce.
+ * Uses AccessibilityInfo.announceForAccessibility on native platforms.
+ */
+export function useAnnounceNative(): UseAnnounceReturn {
+  const announce = useCallback((message: string, _mode?: AnnounceMode) => {
+    // This will be imported dynamically in native files
+    // import { AccessibilityInfo } from 'react-native';
+    // AccessibilityInfo.announceForAccessibility(message);
+
+    // For now, this is a placeholder that native components will override
+    console.log(`[Accessibility] ${message}`);
+  }, []);
+
+  return {
+    announce,
+    announcePolite: announce,
+    announceAssertive: announce,
+    clear: () => {},
+  };
+}