@idealyst/components 1.1.4 → 1.1.5

package/src/utils/accessibility/ariaHelpers.ts

@@ -0,0 +1,393 @@
+import type {
+  AccessibilityProps,
+  InteractiveAccessibilityProps,
+  FormAccessibilityProps,
+  RangeAccessibilityProps,
+  SelectionAccessibilityProps,
+  LiveRegionAccessibilityProps,
+  SortableAccessibilityProps,
+  SelectableAccessibilityProps,
+  HeadingAccessibilityProps,
+  CurrentAccessibilityProps,
+  AriaRole,
+  NativeAccessibilityRole,
+  NativeAccessibilityState,
+  NativeAccessibilityValue,
+} from './types';
+
+/**
+ * Filter out undefined values from an object.
+ * ARIA attributes should not be present if undefined.
+ */
+function filterUndefined<T extends Record<string, unknown>>(obj: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([, value]) => value !== undefined)
+  ) as Partial<T>;
+}
+
+// =============================================================================
+// WEB ARIA ATTRIBUTE MAPPERS
+// =============================================================================
+
+/**
+ * Maps base AccessibilityProps to web ARIA attributes.
+ */
+export function getWebAriaProps(props: AccessibilityProps): Record<string, unknown> {
+  return filterUndefined({
+    'aria-label': props.accessibilityLabel,
+    'aria-hidden': props.accessibilityHidden,
+    'aria-disabled': props.accessibilityDisabled,
+    role: props.accessibilityRole,
+  });
+}
+
+/**
+ * Maps InteractiveAccessibilityProps to web ARIA attributes.
+ */
+export function getWebInteractiveAriaProps(
+  props: InteractiveAccessibilityProps
+): Record<string, unknown> {
+  return filterUndefined({
+    ...getWebAriaProps(props),
+    'aria-labelledby': props.accessibilityLabelledBy,
+    'aria-describedby': props.accessibilityDescribedBy,
+    'aria-controls': props.accessibilityControls,
+    'aria-expanded': props.accessibilityExpanded,
+    'aria-pressed': props.accessibilityPressed,
+    'aria-owns': props.accessibilityOwns,
+    'aria-haspopup': props.accessibilityHasPopup,
+  });
+}
+
+/**
+ * Maps FormAccessibilityProps to web ARIA attributes.
+ */
+export function getWebFormAriaProps(props: FormAccessibilityProps): Record<string, unknown> {
+  return filterUndefined({
+    ...getWebInteractiveAriaProps(props),
+    'aria-required': props.accessibilityRequired,
+    'aria-invalid': props.accessibilityInvalid,
+    'aria-errormessage': props.accessibilityErrorMessage,
+    'aria-autocomplete': props.accessibilityAutoComplete,
+  });
+}
+
+/**
+ * Maps RangeAccessibilityProps to web ARIA attributes.
+ */
+export function getWebRangeAriaProps(props: RangeAccessibilityProps): Record<string, unknown> {
+  return filterUndefined({
+    ...getWebAriaProps(props),
+    'aria-valuenow': props.accessibilityValueNow,
+    'aria-valuemin': props.accessibilityValueMin,
+    'aria-valuemax': props.accessibilityValueMax,
+    'aria-valuetext': props.accessibilityValueText,
+  });
+}
+
+/**
+ * Maps SelectionAccessibilityProps to web ARIA attributes.
+ */
+export function getWebSelectionAriaProps(
+  props: SelectionAccessibilityProps
+): Record<string, unknown> {
+  return filterUndefined({
+    ...getWebInteractiveAriaProps(props),
+    'aria-checked': props.accessibilityChecked,
+  });
+}
+
+/**
+ * Maps LiveRegionAccessibilityProps to web ARIA attributes.
+ */
+export function getWebLiveRegionAriaProps(
+  props: LiveRegionAccessibilityProps
+): Record<string, unknown> {
+  return filterUndefined({
+    ...getWebAriaProps(props),
+    'aria-live': props.accessibilityLive,
+    'aria-busy': props.accessibilityBusy,
+    'aria-relevant': props.accessibilityRelevant,
+    'aria-atomic': props.accessibilityAtomic,
+  });
+}
+
+/**
+ * Maps SortableAccessibilityProps to web ARIA attributes.
+ */
+export function getWebSortableAriaProps(
+  props: SortableAccessibilityProps
+): Record<string, unknown> {
+  return filterUndefined({
+    ...getWebAriaProps(props),
+    'aria-sort': props.accessibilitySort,
+  });
+}
+
+/**
+ * Maps SelectableAccessibilityProps to web ARIA attributes.
+ */
+export function getWebSelectableAriaProps(
+  props: SelectableAccessibilityProps
+): Record<string, unknown> {
+  return filterUndefined({
+    ...getWebAriaProps(props),
+    'aria-selected': props.accessibilitySelected,
+    'aria-posinset': props.accessibilityPosInSet,
+    'aria-setsize': props.accessibilitySetSize,
+  });
+}
+
+/**
+ * Maps HeadingAccessibilityProps to web ARIA attributes.
+ */
+export function getWebHeadingAriaProps(props: HeadingAccessibilityProps): Record<string, unknown> {
+  return filterUndefined({
+    ...getWebAriaProps(props),
+    'aria-level': props.accessibilityLevel,
+  });
+}
+
+/**
+ * Maps CurrentAccessibilityProps to web ARIA attributes.
+ */
+export function getWebCurrentAriaProps(props: CurrentAccessibilityProps): Record<string, unknown> {
+  return filterUndefined({
+    ...getWebAriaProps(props),
+    'aria-current': props.accessibilityCurrent,
+  });
+}
+
+// =============================================================================
+// REACT NATIVE ACCESSIBILITY MAPPERS
+// =============================================================================
+
+/**
+ * Maps ARIA role to React Native accessibilityRole.
+ * Not all ARIA roles have direct RN equivalents.
+ */
+export function mapRoleToNative(role?: AriaRole): NativeAccessibilityRole | undefined {
+  if (!role) return undefined;
+
+  const roleMap: Partial<Record<AriaRole, NativeAccessibilityRole>> = {
+    button: 'button',
+    link: 'link',
+    checkbox: 'checkbox',
+    radio: 'radio',
+    switch: 'switch',
+    slider: 'adjustable',
+    progressbar: 'progressbar',
+    textbox: 'text',
+    searchbox: 'search',
+    combobox: 'combobox',
+    menu: 'menu',
+    menuitem: 'menuitem',
+    tab: 'tab',
+    tablist: 'tablist',
+    alert: 'alert',
+    img: 'image',
+    list: 'list',
+    timer: 'timer',
+    heading: 'header',
+    // Roles without direct mapping return undefined
+    // dialog, tooltip, grid, table, etc. don't have RN equivalents
+  };
+
+  return roleMap[role];
+}
+
+/**
+ * Maps base AccessibilityProps to React Native accessibility props.
+ */
+export function getNativeAccessibilityProps(props: AccessibilityProps): Record<string, unknown> {
+  const state: NativeAccessibilityState = {};
+
+  if (props.accessibilityDisabled !== undefined) {
+    state.disabled = props.accessibilityDisabled;
+  }
+
+  return filterUndefined({
+    accessibilityLabel: props.accessibilityLabel,
+    accessibilityHint: props.accessibilityHint,
+    accessibilityRole: mapRoleToNative(props.accessibilityRole),
+    accessibilityElementsHidden: props.accessibilityHidden,
+    importantForAccessibility: props.accessibilityHidden ? 'no-hide-descendants' : undefined,
+    accessibilityState: Object.keys(state).length > 0 ? state : undefined,
+  });
+}
+
+/**
+ * Maps InteractiveAccessibilityProps to React Native accessibility props.
+ */
+export function getNativeInteractiveAccessibilityProps(
+  props: InteractiveAccessibilityProps
+): Record<string, unknown> {
+  const state: NativeAccessibilityState = {};
+
+  if (props.accessibilityDisabled !== undefined) {
+    state.disabled = props.accessibilityDisabled;
+  }
+  if (props.accessibilityExpanded !== undefined) {
+    state.expanded = props.accessibilityExpanded;
+  }
+
+  return filterUndefined({
+    accessibilityLabel: props.accessibilityLabel,
+    accessibilityHint: props.accessibilityHint,
+    accessibilityRole: mapRoleToNative(props.accessibilityRole),
+    accessibilityElementsHidden: props.accessibilityHidden,
+    importantForAccessibility: props.accessibilityHidden ? 'no-hide-descendants' : undefined,
+    accessibilityState: Object.keys(state).length > 0 ? state : undefined,
+  });
+}
+
+/**
+ * Maps FormAccessibilityProps to React Native accessibility props.
+ * Note: aria-describedby, aria-invalid, aria-errormessage don't have direct RN equivalents.
+ * Error information should be included in accessibilityLabel.
+ */
+export function getNativeFormAccessibilityProps(
+  props: FormAccessibilityProps
+): Record<string, unknown> {
+  const state: NativeAccessibilityState = {};
+
+  if (props.accessibilityDisabled !== undefined) {
+    state.disabled = props.accessibilityDisabled;
+  }
+  if (props.accessibilityExpanded !== undefined) {
+    state.expanded = props.accessibilityExpanded;
+  }
+
+  // Build label with error info since RN doesn't support aria-describedby
+  let label = props.accessibilityLabel;
+  if (props.accessibilityRequired && label) {
+    label = `${label}, required`;
+  }
+  if (props.accessibilityInvalid && label) {
+    label = `${label}, invalid`;
+  }
+
+  return filterUndefined({
+    accessibilityLabel: label,
+    accessibilityHint: props.accessibilityHint,
+    accessibilityRole: mapRoleToNative(props.accessibilityRole),
+    accessibilityElementsHidden: props.accessibilityHidden,
+    importantForAccessibility: props.accessibilityHidden ? 'no-hide-descendants' : undefined,
+    accessibilityState: Object.keys(state).length > 0 ? state : undefined,
+  });
+}
+
+/**
+ * Maps RangeAccessibilityProps to React Native accessibility props.
+ */
+export function getNativeRangeAccessibilityProps(
+  props: RangeAccessibilityProps
+): Record<string, unknown> {
+  const value: NativeAccessibilityValue = {};
+
+  if (props.accessibilityValueNow !== undefined) {
+    value.now = props.accessibilityValueNow;
+  }
+  if (props.accessibilityValueMin !== undefined) {
+    value.min = props.accessibilityValueMin;
+  }
+  if (props.accessibilityValueMax !== undefined) {
+    value.max = props.accessibilityValueMax;
+  }
+  if (props.accessibilityValueText !== undefined) {
+    value.text = props.accessibilityValueText;
+  }
+
+  return filterUndefined({
+    accessibilityLabel: props.accessibilityLabel,
+    accessibilityHint: props.accessibilityHint,
+    accessibilityRole: mapRoleToNative(props.accessibilityRole),
+    accessibilityElementsHidden: props.accessibilityHidden,
+    importantForAccessibility: props.accessibilityHidden ? 'no-hide-descendants' : undefined,
+    accessibilityValue: Object.keys(value).length > 0 ? value : undefined,
+  });
+}
+
+/**
+ * Maps SelectionAccessibilityProps to React Native accessibility props.
+ */
+export function getNativeSelectionAccessibilityProps(
+  props: SelectionAccessibilityProps
+): Record<string, unknown> {
+  const state: NativeAccessibilityState = {};
+
+  if (props.accessibilityDisabled !== undefined) {
+    state.disabled = props.accessibilityDisabled;
+  }
+  if (props.accessibilityExpanded !== undefined) {
+    state.expanded = props.accessibilityExpanded;
+  }
+  if (props.accessibilityChecked !== undefined) {
+    state.checked = props.accessibilityChecked;
+  }
+
+  return filterUndefined({
+    accessibilityLabel: props.accessibilityLabel,
+    accessibilityHint: props.accessibilityHint,
+    accessibilityRole: mapRoleToNative(props.accessibilityRole),
+    accessibilityElementsHidden: props.accessibilityHidden,
+    importantForAccessibility: props.accessibilityHidden ? 'no-hide-descendants' : undefined,
+    accessibilityState: Object.keys(state).length > 0 ? state : undefined,
+  });
+}
+
+/**
+ * Maps LiveRegionAccessibilityProps to React Native accessibility props.
+ */
+export function getNativeLiveRegionAccessibilityProps(
+  props: LiveRegionAccessibilityProps
+): Record<string, unknown> {
+  const state: NativeAccessibilityState = {};
+
+  if (props.accessibilityBusy !== undefined) {
+    state.busy = props.accessibilityBusy;
+  }
+
+  // Map aria-live to accessibilityLiveRegion
+  let liveRegion: 'none' | 'polite' | 'assertive' | undefined;
+  if (props.accessibilityLive === 'off') {
+    liveRegion = 'none';
+  } else if (props.accessibilityLive) {
+    liveRegion = props.accessibilityLive;
+  }
+
+  return filterUndefined({
+    accessibilityLabel: props.accessibilityLabel,
+    accessibilityHint: props.accessibilityHint,
+    accessibilityRole: mapRoleToNative(props.accessibilityRole),
+    accessibilityElementsHidden: props.accessibilityHidden,
+    importantForAccessibility: props.accessibilityHidden ? 'no-hide-descendants' : undefined,
+    accessibilityState: Object.keys(state).length > 0 ? state : undefined,
+    accessibilityLiveRegion: liveRegion,
+  });
+}
+
+/**
+ * Maps SelectableAccessibilityProps to React Native accessibility props.
+ */
+export function getNativeSelectableAccessibilityProps(
+  props: SelectableAccessibilityProps
+): Record<string, unknown> {
+  const state: NativeAccessibilityState = {};
+
+  if (props.accessibilityDisabled !== undefined) {
+    state.disabled = props.accessibilityDisabled;
+  }
+  if (props.accessibilitySelected !== undefined) {
+    state.selected = props.accessibilitySelected;
+  }
+
+  return filterUndefined({
+    accessibilityLabel: props.accessibilityLabel,
+    accessibilityHint: props.accessibilityHint,
+    accessibilityRole: mapRoleToNative(props.accessibilityRole),
+    accessibilityElementsHidden: props.accessibilityHidden,
+    importantForAccessibility: props.accessibilityHidden ? 'no-hide-descendants' : undefined,
+    accessibilityState: Object.keys(state).length > 0 ? state : undefined,
+  });
+}

package/src/utils/accessibility/index.ts

@@ -0,0 +1,210 @@
+/**
+ * @idealyst/components - Accessibility Utilities
+ *
+ * This module provides comprehensive accessibility support for building
+ * WCAG 2.1 AA compliant React and React Native applications.
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   AccessibilityProps,
+ *   getWebAriaProps,
+ *   useKeyboardNavigation,
+ *   useFocusTrap,
+ *   MENU_KEYS,
+ * } from '@idealyst/components/utils/accessibility';
+ * ```
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type {
+  // Role types
+  AriaRole,
+  NativeAccessibilityRole,
+  // Accessibility prop interfaces
+  AccessibilityProps,
+  InteractiveAccessibilityProps,
+  FormAccessibilityProps,
+  RangeAccessibilityProps,
+  SelectionAccessibilityProps,
+  LiveRegionAccessibilityProps,
+  SortableAccessibilityProps,
+  SelectableAccessibilityProps,
+  HeadingAccessibilityProps,
+  CurrentAccessibilityProps,
+  // Native types
+  NativeAccessibilityState,
+  NativeAccessibilityValue,
+} from './types';
+
+// =============================================================================
+// ARIA HELPERS
+// =============================================================================
+
+export {
+  // Web ARIA mappers
+  getWebAriaProps,
+  getWebInteractiveAriaProps,
+  getWebFormAriaProps,
+  getWebRangeAriaProps,
+  getWebSelectionAriaProps,
+  getWebLiveRegionAriaProps,
+  getWebSortableAriaProps,
+  getWebSelectableAriaProps,
+  getWebHeadingAriaProps,
+  getWebCurrentAriaProps,
+  // React Native mappers
+  mapRoleToNative,
+  getNativeAccessibilityProps,
+  getNativeInteractiveAccessibilityProps,
+  getNativeFormAccessibilityProps,
+  getNativeRangeAccessibilityProps,
+  getNativeSelectionAccessibilityProps,
+  getNativeLiveRegionAccessibilityProps,
+  getNativeSelectableAccessibilityProps,
+} from './ariaHelpers';
+
+// =============================================================================
+// HOOKS
+// =============================================================================
+
+export { useKeyboardNavigation } from './useKeyboardNavigation';
+export type {
+  UseKeyboardNavigationOptions,
+  UseKeyboardNavigationReturn,
+} from './useKeyboardNavigation';
+
+export { useFocusTrap, useFocusTrapNative } from './useFocusTrap';
+export type { UseFocusTrapOptions, UseFocusTrapReturn } from './useFocusTrap';
+
+export { useAnnounce, useAnnounceNative } from './useAnnounce';
+export type { AnnounceMode, UseAnnounceOptions, UseAnnounceReturn } from './useAnnounce';
+
+// =============================================================================
+// KEYBOARD PATTERNS
+// =============================================================================
+
+export {
+  // Key pattern constants
+  BUTTON_KEYS,
+  LINK_KEYS,
+  MENU_KEYS,
+  ACCORDION_KEYS,
+  TAB_KEYS,
+  SLIDER_KEYS,
+  LISTBOX_KEYS,
+  DIALOG_KEYS,
+  CHECKBOX_KEYS,
+  RADIO_KEYS,
+  SWITCH_KEYS,
+  TREE_KEYS,
+  GRID_KEYS,
+  COMBOBOX_KEYS,
+  TOOLTIP_KEYS,
+  // Helper functions
+  matchesKey,
+  matchesKeyPattern,
+} from './keyboardPatterns';
+
+// =============================================================================
+// UTILITIES
+// =============================================================================
+
+/**
+ * Counter for generating unique accessibility IDs.
+ */
+let idCounter = 0;
+
+/**
+ * Generate a unique ID for accessibility attributes.
+ * Use this for aria-labelledby, aria-describedby, aria-controls, etc.
+ *
+ * @param prefix - Optional prefix for the ID (default: 'a11y')
+ * @returns A unique string ID
+ *
+ * @example
+ * ```tsx
+ * const inputId = generateAccessibilityId('input');     // 'input-1'
+ * const errorId = generateAccessibilityId('error');     // 'error-2'
+ * const helperId = generateAccessibilityId('helper');   // 'helper-3'
+ *
+ * <Input
+ *   id={inputId}
+ *   aria-describedby={`${helperId} ${errorId}`}
+ * />
+ * <Text id={helperId}>Enter your email</Text>
+ * <Text id={errorId}>Invalid email format</Text>
+ * ```
+ */
+export function generateAccessibilityId(prefix: string = 'a11y'): string {
+  return `${prefix}-${++idCounter}`;
+}
+
+/**
+ * Reset the ID counter. Useful for testing.
+ * @internal
+ */
+export function resetAccessibilityIdCounter(): void {
+  idCounter = 0;
+}
+
+/**
+ * Combine multiple accessibility IDs into a space-separated string.
+ * Filters out undefined/null values.
+ *
+ * @param ids - Array of IDs (can include undefined/null)
+ * @returns Space-separated string of IDs, or undefined if all are empty
+ *
+ * @example
+ * ```tsx
+ * const describedBy = combineIds([helperId, hasError ? errorId : undefined]);
+ * // Returns: "helper-1 error-2" or "helper-1" depending on hasError
+ * ```
+ */
+export function combineIds(ids: (string | undefined | null)[]): string | undefined {
+  const filtered = ids.filter((id): id is string => Boolean(id));
+  return filtered.length > 0 ? filtered.join(' ') : undefined;
+}
+
+/**
+ * Check if the user prefers reduced motion.
+ * Useful for disabling animations/transitions for accessibility.
+ *
+ * @returns true if the user prefers reduced motion
+ *
+ * @example
+ * ```tsx
+ * const prefersReducedMotion = checkReducedMotion();
+ * const transitionDuration = prefersReducedMotion ? 0 : 300;
+ * ```
+ */
+export function checkReducedMotion(): boolean {
+  if (typeof window === 'undefined') return false;
+  const mediaQuery = window.matchMedia?.('(prefers-reduced-motion: reduce)');
+  return mediaQuery?.matches ?? false;
+}
+
+/**
+ * Minimum touch target size in pixels (WCAG 2.5.5 Target Size).
+ * Interactive elements should be at least 44x44 pixels.
+ */
+export const MIN_TOUCH_TARGET_SIZE = 44;
+
+/**
+ * Minimum contrast ratio for normal text (WCAG 2.1 AA).
+ */
+export const MIN_CONTRAST_RATIO_NORMAL = 4.5;
+
+/**
+ * Minimum contrast ratio for large text (WCAG 2.1 AA).
+ * Large text is 18pt+ or 14pt+ bold.
+ */
+export const MIN_CONTRAST_RATIO_LARGE = 3;
+
+/**
+ * Minimum contrast ratio for UI components (WCAG 2.1 AA).
+ */
+export const MIN_CONTRAST_RATIO_UI = 3;