rn-iconify 1.0.0 → 2.0.0

package/src/accessibility/types.ts

@@ -0,0 +1,152 @@
+/**
+ * Accessibility types for rn-iconify
+ */
+
+import type { AccessibilityRole } from 'react-native';
+
+/**
+ * Accessibility configuration
+ */
+export interface AccessibilityConfig {
+  /**
+   * Enable auto-generated accessibility labels
+   * @default true
+   */
+  autoLabels?: boolean;
+
+  /**
+   * Custom label generator function
+   */
+  labelGenerator?: (iconName: string) => string;
+
+  /**
+   * Enable high contrast mode
+   * @default false (auto-detect from system)
+   */
+  highContrast?: boolean;
+
+  /**
+   * Respect reduced motion preference
+   * @default true
+   */
+  respectReducedMotion?: boolean;
+
+  /**
+   * Default accessibility role for icons
+   * @default 'image'
+   */
+  defaultRole?: AccessibilityRole;
+
+  /**
+   * Enable focus indicators
+   * @default true
+   */
+  showFocusIndicators?: boolean;
+
+  /**
+   * Minimum touch target size (for pressable icons)
+   * @default 44
+   */
+  minTouchTargetSize?: number;
+}
+
+/**
+ * Resolved accessibility config with defaults applied
+ */
+export interface ResolvedAccessibilityConfig {
+  autoLabels: boolean;
+  labelGenerator: (iconName: string) => string;
+  highContrast: boolean;
+  respectReducedMotion: boolean;
+  defaultRole: AccessibilityRole;
+  showFocusIndicators: boolean;
+  minTouchTargetSize: number;
+}
+
+/**
+ * Accessibility context value
+ */
+export interface AccessibilityContextValue {
+  /**
+   * Current accessibility configuration
+   */
+  config: ResolvedAccessibilityConfig;
+
+  /**
+   * System prefers reduced motion
+   */
+  prefersReducedMotion: boolean;
+
+  /**
+   * System high contrast mode enabled
+   */
+  isHighContrast: boolean;
+
+  /**
+   * Update accessibility configuration
+   */
+  setConfig: (config: Partial<AccessibilityConfig>) => void;
+
+  /**
+   * Generate label for icon
+   */
+  getLabel: (iconName: string, customLabel?: string) => string | undefined;
+
+  /**
+   * Get color adjusted for high contrast
+   */
+  getContrastColor: (color: string) => string;
+
+  /**
+   * Check if animations should be disabled
+   */
+  shouldDisableAnimations: () => boolean;
+}
+
+/**
+ * Props for accessibility-enhanced icons
+ */
+export interface AccessibleIconProps {
+  /**
+   * Accessibility label (auto-generated if not provided)
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * Accessibility hint
+   */
+  accessibilityHint?: string;
+
+  /**
+   * Accessibility role
+   * @default 'image'
+   */
+  accessibilityRole?: AccessibilityRole;
+
+  /**
+   * Whether the icon is part of a button or pressable
+   */
+  accessibilityState?: {
+    disabled?: boolean;
+    selected?: boolean;
+    checked?: boolean | 'mixed';
+    busy?: boolean;
+    expanded?: boolean;
+  };
+
+  /**
+   * Override high contrast mode for this icon
+   */
+  highContrast?: boolean;
+
+  /**
+   * Whether this icon should be hidden from screen readers
+   * Useful for decorative icons
+   */
+  accessibilityElementsHidden?: boolean;
+
+  /**
+   * Import for Android accessibility
+   */
+  importantForAccessibility?: 'auto' | 'yes' | 'no' | 'no-hide-descendants';
+}

package/src/accessibility/useAccessibleIcon.ts

@@ -0,0 +1,220 @@
+/**
+ * Hook for creating accessible icon props
+ */
+
+import { useMemo } from 'react';
+import type { AccessibilityRole } from 'react-native';
+import { useAccessibility } from './AccessibilityProvider';
+import type { AccessibleIconProps } from './types';
+import { calculateTouchTargetPadding, adjustForHighContrast } from './utils';
+
+/**
+ * Input props for useAccessibleIcon hook
+ */
+export interface UseAccessibleIconInput {
+  /**
+   * Icon name for auto-label generation
+   */
+  iconName: string;
+
+  /**
+   * Icon size for touch target calculation
+   */
+  size?: number;
+
+  /**
+   * Custom accessibility label
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * Custom accessibility hint
+   */
+  accessibilityHint?: string;
+
+  /**
+   * Custom accessibility role
+   */
+  accessibilityRole?: AccessibilityRole;
+
+  /**
+   * Override high contrast for this icon
+   */
+  highContrast?: boolean;
+
+  /**
+   * Hide from screen readers (decorative icon)
+   */
+  accessibilityElementsHidden?: boolean;
+
+  /**
+   * Android importantForAccessibility
+   */
+  importantForAccessibility?: 'auto' | 'yes' | 'no' | 'no-hide-descendants';
+
+  /**
+   * Icon color for contrast adjustment
+   */
+  color?: string;
+
+  /**
+   * Whether the icon is interactive (button, etc.)
+   */
+  isInteractive?: boolean;
+}
+
+/**
+ * Output props from useAccessibleIcon hook
+ */
+export interface UseAccessibleIconOutput {
+  /**
+   * Props to spread on the icon component
+   */
+  accessibilityProps: {
+    accessible: boolean;
+    accessibilityLabel?: string;
+    accessibilityHint?: string;
+    accessibilityRole: AccessibilityRole;
+    accessibilityElementsHidden?: boolean;
+    importantForAccessibility?: 'auto' | 'yes' | 'no' | 'no-hide-descendants';
+  };
+
+  /**
+   * Adjusted color for high contrast
+   */
+  adjustedColor?: string;
+
+  /**
+   * Padding needed to meet minimum touch target
+   */
+  touchTargetPadding: number;
+
+  /**
+   * Whether animations should be disabled
+   */
+  shouldDisableAnimations: boolean;
+
+  /**
+   * Whether high contrast mode is active
+   */
+  isHighContrast: boolean;
+}
+
+/**
+ * Hook for creating accessible icon props
+ * Automatically generates labels, adjusts colors, and calculates touch targets
+ *
+ * @example
+ * ```tsx
+ * function MyIcon({ name, size, color }) {
+ *   const { accessibilityProps, adjustedColor, touchTargetPadding } = useAccessibleIcon({
+ *     iconName: name,
+ *     size,
+ *     color,
+ *   });
+ *
+ *   return (
+ *     <View style={{ padding: touchTargetPadding }} {...accessibilityProps}>
+ *       <Icon name={name} size={size} color={adjustedColor} />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useAccessibleIcon(input: UseAccessibleIconInput): UseAccessibleIconOutput {
+  const accessibility = useAccessibility();
+
+  return useMemo(() => {
+    // Default values when no provider is present
+    const defaults: UseAccessibleIconOutput = {
+      accessibilityProps: {
+        accessible: true,
+        accessibilityRole: input.accessibilityRole ?? 'image',
+        accessibilityLabel: input.accessibilityLabel,
+        accessibilityHint: input.accessibilityHint,
+        accessibilityElementsHidden: input.accessibilityElementsHidden,
+        importantForAccessibility: input.importantForAccessibility,
+      },
+      adjustedColor: input.color,
+      touchTargetPadding: 0,
+      shouldDisableAnimations: false,
+      isHighContrast: false,
+    };
+
+    // Return defaults if no accessibility context
+    if (!accessibility) {
+      return defaults;
+    }
+
+    const { config, getLabel, getContrastColor, shouldDisableAnimations, isHighContrast } =
+      accessibility;
+
+    // Determine accessibility role
+    const role: AccessibilityRole = input.accessibilityRole ?? config.defaultRole;
+
+    // Generate label
+    const label = input.accessibilityElementsHidden
+      ? undefined
+      : getLabel(input.iconName, input.accessibilityLabel);
+
+    // Calculate touch target padding for interactive icons
+    const touchTargetPadding =
+      input.isInteractive && input.size
+        ? calculateTouchTargetPadding(input.size, config.minTouchTargetSize)
+        : 0;
+
+    // Adjust color for high contrast if needed
+    const shouldUseHighContrast = input.highContrast ?? isHighContrast;
+    // Use adjustForHighContrast directly when prop is set, otherwise use context's getContrastColor
+    const adjustedColor =
+      input.color && shouldUseHighContrast
+        ? input.highContrast
+          ? adjustForHighContrast(input.color)
+          : getContrastColor(input.color)
+        : input.color;
+
+    return {
+      accessibilityProps: {
+        accessible: !input.accessibilityElementsHidden,
+        accessibilityLabel: label,
+        accessibilityHint: input.accessibilityHint,
+        accessibilityRole: role,
+        accessibilityElementsHidden: input.accessibilityElementsHidden,
+        importantForAccessibility: input.importantForAccessibility,
+      },
+      adjustedColor,
+      touchTargetPadding,
+      shouldDisableAnimations: shouldDisableAnimations(),
+      isHighContrast: shouldUseHighContrast,
+    };
+  }, [
+    accessibility,
+    input.iconName,
+    input.size,
+    input.accessibilityLabel,
+    input.accessibilityHint,
+    input.accessibilityRole,
+    input.highContrast,
+    input.accessibilityElementsHidden,
+    input.importantForAccessibility,
+    input.color,
+    input.isInteractive,
+  ]);
+}
+
+/**
+ * Higher-order component props enhancer
+ * Use this to add accessibility to existing icon components
+ */
+export function withAccessibility<P extends AccessibleIconProps>(
+  props: P & UseAccessibleIconInput
+): P & UseAccessibleIconOutput['accessibilityProps'] {
+  // This is a simple merge for use without hooks (SSR, etc.)
+  return {
+    ...props,
+    accessible: !props.accessibilityElementsHidden,
+    accessibilityRole: props.accessibilityRole ?? 'image',
+  };
+}
+
+export default useAccessibleIcon;

package/src/accessibility/utils.ts

@@ -0,0 +1,180 @@
+/**
+ * Accessibility utility functions for rn-iconify
+ */
+
+/**
+ * Default label generator - converts icon names to readable labels
+ * Examples:
+ *   - "mdi:home" -> "home icon"
+ *   - "heroicons:user-circle" -> "user circle icon"
+ *   - "lucide:arrow-left" -> "arrow left icon"
+ */
+export function defaultLabelGenerator(iconName: string): string {
+  // Extract icon name from prefix:name format
+  const parts = iconName.split(':');
+  const name = parts.length > 1 ? parts[1] : parts[0];
+
+  // Convert kebab-case and camelCase to readable text
+  const readable = name
+    // Insert space before capital letters (camelCase)
+    .replace(/([A-Z])/g, ' $1')
+    // Replace hyphens and underscores with spaces
+    .replace(/[-_]/g, ' ')
+    // Remove extra spaces
+    .replace(/\s+/g, ' ')
+    // Trim and lowercase
+    .trim()
+    .toLowerCase();
+
+  return `${readable} icon`;
+}
+
+/**
+ * Adjust color for high contrast mode
+ * Increases contrast by pushing colors toward black or white
+ */
+export function adjustForHighContrast(color: string): string {
+  // Parse color
+  const rgb = parseColor(color);
+  if (!rgb) return color;
+
+  // Calculate luminance
+  const luminance = (0.299 * rgb.r + 0.587 * rgb.g + 0.114 * rgb.b) / 255;
+
+  // Push toward black or white based on luminance
+  if (luminance > 0.5) {
+    // Light color - make it darker (black)
+    return '#000000';
+  } else {
+    // Dark color - make it lighter (white)
+    return '#FFFFFF';
+  }
+}
+
+/**
+ * Parse color string to RGB values
+ */
+function parseColor(color: string): { r: number; g: number; b: number } | null {
+  // Handle hex colors
+  if (color.startsWith('#')) {
+    const hex = color.slice(1);
+    if (hex.length === 3) {
+      return {
+        r: parseInt(hex[0] + hex[0], 16),
+        g: parseInt(hex[1] + hex[1], 16),
+        b: parseInt(hex[2] + hex[2], 16),
+      };
+    }
+    if (hex.length === 6) {
+      return {
+        r: parseInt(hex.slice(0, 2), 16),
+        g: parseInt(hex.slice(2, 4), 16),
+        b: parseInt(hex.slice(4, 6), 16),
+      };
+    }
+  }
+
+  // Handle rgb/rgba colors
+  const rgbMatch = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
+  if (rgbMatch) {
+    return {
+      r: parseInt(rgbMatch[1], 10),
+      g: parseInt(rgbMatch[2], 10),
+      b: parseInt(rgbMatch[3], 10),
+    };
+  }
+
+  // Handle named colors (common ones)
+  const namedColors: Record<string, { r: number; g: number; b: number }> = {
+    black: { r: 0, g: 0, b: 0 },
+    white: { r: 255, g: 255, b: 255 },
+    red: { r: 255, g: 0, b: 0 },
+    green: { r: 0, g: 128, b: 0 },
+    blue: { r: 0, g: 0, b: 255 },
+    yellow: { r: 255, g: 255, b: 0 },
+    cyan: { r: 0, g: 255, b: 255 },
+    magenta: { r: 255, g: 0, b: 255 },
+    gray: { r: 128, g: 128, b: 128 },
+    grey: { r: 128, g: 128, b: 128 },
+    orange: { r: 255, g: 165, b: 0 },
+    purple: { r: 128, g: 0, b: 128 },
+    pink: { r: 255, g: 192, b: 203 },
+    brown: { r: 165, g: 42, b: 42 },
+  };
+
+  const lowerColor = color.toLowerCase();
+  if (namedColors[lowerColor]) {
+    return namedColors[lowerColor];
+  }
+
+  return null;
+}
+
+/**
+ * Check if a color meets WCAG contrast requirements against a background
+ */
+export function meetsContrastRequirement(
+  foreground: string,
+  background: string,
+  level: 'AA' | 'AAA' = 'AA'
+): boolean {
+  const fgRgb = parseColor(foreground);
+  const bgRgb = parseColor(background);
+
+  if (!fgRgb || !bgRgb) return true; // Assume it meets if we can't parse
+
+  const fgLuminance = getRelativeLuminance(fgRgb);
+  const bgLuminance = getRelativeLuminance(bgRgb);
+
+  const lighter = Math.max(fgLuminance, bgLuminance);
+  const darker = Math.min(fgLuminance, bgLuminance);
+
+  const contrastRatio = (lighter + 0.05) / (darker + 0.05);
+
+  // WCAG requirements for normal text
+  const requiredRatio = level === 'AAA' ? 7 : 4.5;
+
+  return contrastRatio >= requiredRatio;
+}
+
+/**
+ * Calculate relative luminance for WCAG calculations
+ */
+function getRelativeLuminance(rgb: { r: number; g: number; b: number }): number {
+  const rsRGB = rgb.r / 255;
+  const gsRGB = rgb.g / 255;
+  const bsRGB = rgb.b / 255;
+
+  const r = rsRGB <= 0.03928 ? rsRGB / 12.92 : Math.pow((rsRGB + 0.055) / 1.055, 2.4);
+  const g = gsRGB <= 0.03928 ? gsRGB / 12.92 : Math.pow((gsRGB + 0.055) / 1.055, 2.4);
+  const b = bsRGB <= 0.03928 ? bsRGB / 12.92 : Math.pow((bsRGB + 0.055) / 1.055, 2.4);
+
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/**
+ * Generate a high contrast alternative for a color
+ */
+export function getHighContrastAlternative(color: string, background: string = '#FFFFFF'): string {
+  const fgRgb = parseColor(color);
+  const bgRgb = parseColor(background);
+
+  if (!fgRgb || !bgRgb) return color;
+
+  const bgLuminance = getRelativeLuminance(bgRgb);
+
+  // If background is light, use black; if dark, use white
+  if (bgLuminance > 0.5) {
+    return '#000000';
+  } else {
+    return '#FFFFFF';
+  }
+}
+
+/**
+ * Calculate minimum touch target padding needed
+ */
+export function calculateTouchTargetPadding(iconSize: number, minTargetSize: number): number {
+  if (iconSize >= minTargetSize) return 0;
+  return (minTargetSize - iconSize) / 2;
+}

package/src/alias/Icon.tsx

@@ -0,0 +1,113 @@
+/**
+ * Generic Icon Component
+ * Renders any icon by full name (prefix:name) or alias
+ */
+
+import React from 'react';
+import { IconRenderer } from '../IconRenderer';
+import { useIconTheme } from '../theme';
+import { DEFAULT_ICON_THEME } from '../theme/types';
+import { useIconAliasContext } from './IconAliasContext';
+import type { GenericIconProps } from './types';
+
+/**
+ * Generic Icon component that accepts any icon name or alias
+ *
+ * @example With full icon name
+ * ```tsx
+ * import { Icon } from 'rn-iconify';
+ *
+ * <Icon name="mdi:home" size={24} color="blue" />
+ * <Icon name="heroicons:user" size={24} />
+ * ```
+ *
+ * @example With aliases (requires IconAliasProvider)
+ * ```tsx
+ * import { Icon, IconAliasProvider } from 'rn-iconify';
+ *
+ * const aliases = {
+ *   back: 'mdi:arrow-left',
+ *   menu: 'heroicons:bars-3',
+ * };
+ *
+ * <IconAliasProvider aliases={aliases}>
+ *   <Icon name="back" size={24} />
+ *   <Icon name="menu" size={24} />
+ * </IconAliasProvider>
+ * ```
+ */
+export function Icon({
+  name,
+  size,
+  color,
+  width,
+  height,
+  style,
+  rotate,
+  flip,
+  fallback,
+  fallbackDelay,
+  placeholder,
+  placeholderColor,
+  placeholderDuration,
+  onLoad,
+  onError,
+  accessibilityLabel,
+  testID,
+}: GenericIconProps) {
+  // Get theme defaults
+  const { theme } = useIconTheme();
+
+  // Get alias context
+  const { resolveIcon } = useIconAliasContext();
+
+  // Resolve the icon name (alias → full name)
+  const resolvedName = resolveIcon(name);
+
+  // Merge props with theme defaults (props take precedence)
+  const mergedSize = size ?? theme.size ?? DEFAULT_ICON_THEME.size;
+  const mergedColor = color ?? theme.color ?? DEFAULT_ICON_THEME.color;
+  const mergedRotate = rotate ?? theme.rotate ?? DEFAULT_ICON_THEME.rotate;
+  const mergedFlip = flip ?? theme.flip;
+  const mergedFallbackDelay =
+    fallbackDelay ?? theme.fallbackDelay ?? DEFAULT_ICON_THEME.fallbackDelay;
+  const mergedPlaceholder = placeholder ?? theme.placeholder;
+  const mergedPlaceholderColor =
+    placeholderColor ?? theme.placeholderColor ?? DEFAULT_ICON_THEME.placeholderColor;
+  const mergedPlaceholderDuration =
+    placeholderDuration ?? theme.placeholderDuration ?? DEFAULT_ICON_THEME.placeholderDuration;
+
+  // Validate icon name format in development
+  if (__DEV__ && !resolvedName.includes(':')) {
+    console.warn(
+      `[rn-iconify] Icon name "${name}" is not a valid icon name or registered alias. ` +
+        `Expected format: "prefix:name" (e.g., "mdi:home") or a registered alias.`
+    );
+  }
+
+  return (
+    <IconRenderer
+      iconName={resolvedName}
+      size={mergedSize}
+      color={mergedColor}
+      width={width}
+      height={height}
+      style={style}
+      rotate={mergedRotate}
+      flip={mergedFlip}
+      fallback={fallback}
+      fallbackDelay={mergedFallbackDelay}
+      placeholder={mergedPlaceholder}
+      placeholderColor={mergedPlaceholderColor}
+      placeholderDuration={mergedPlaceholderDuration}
+      onLoad={onLoad}
+      onError={onError}
+      accessibilityLabel={accessibilityLabel ?? name}
+      testID={testID}
+    />
+  );
+}
+
+Icon.displayName = 'Icon';
+
+export default Icon;