rn-iconify 1.0.0 → 2.0.0

package/src/alias/IconAliasContext.tsx

@@ -0,0 +1,180 @@
+/**
+ * Icon Alias Context
+ * Provides alias resolution throughout the component tree
+ */
+
+import React, { createContext, useContext, useMemo, useCallback, useState } from 'react';
+import type { IconAliasContextValue, IconAliasProviderProps, IconAliasMap } from './types';
+
+/**
+ * Default context value (no aliases)
+ */
+const defaultContextValue: IconAliasContextValue = {
+  aliases: {},
+  resolveIcon: (name: string) => name,
+  isAlias: () => false,
+  registerAliases: () => {},
+};
+
+/**
+ * Icon Alias Context
+ */
+export const IconAliasContext = createContext<IconAliasContextValue>(defaultContextValue);
+
+/**
+ * Hook to access icon alias context
+ *
+ * @example
+ * ```tsx
+ * const { resolveIcon, isAlias } = useIconAliasContext();
+ * const fullName = resolveIcon('back'); // 'mdi:arrow-left'
+ * ```
+ */
+export function useIconAliasContext(): IconAliasContextValue {
+  return useContext(IconAliasContext);
+}
+
+/**
+ * Hook to resolve an icon name (alias or full name)
+ *
+ * @example
+ * ```tsx
+ * const resolvedName = useResolveIcon('back'); // 'mdi:arrow-left'
+ * const resolvedName2 = useResolveIcon('mdi:home'); // 'mdi:home'
+ * ```
+ */
+export function useResolveIcon(name: string): string {
+  const { resolveIcon } = useIconAliasContext();
+  return resolveIcon(name);
+}
+
+/**
+ * Check if a name is a full icon name (contains colon)
+ */
+function isFullIconName(name: string): boolean {
+  return name.includes(':');
+}
+
+/**
+ * Validate icon name format
+ */
+function validateIconName(name: string, source: string): void {
+  if (!name || typeof name !== 'string') {
+    console.warn(`[rn-iconify] Invalid icon name in ${source}: ${name}`);
+    return;
+  }
+
+  if (!isFullIconName(name)) {
+    console.warn(
+      `[rn-iconify] Alias "${source}" should map to a full icon name (prefix:name format), got: "${name}"`
+    );
+  }
+}
+
+/**
+ * Icon Alias Provider
+ * Provides alias resolution to all child components
+ *
+ * @example
+ * ```tsx
+ * const aliases = {
+ *   back: 'mdi:arrow-left',
+ *   menu: 'heroicons:bars-3',
+ * };
+ *
+ * <IconAliasProvider aliases={aliases}>
+ *   <App />
+ * </IconAliasProvider>
+ * ```
+ */
+export function IconAliasProvider({
+  aliases: initialAliases,
+  extend = true,
+  children,
+}: IconAliasProviderProps) {
+  const parentContext = useContext(IconAliasContext);
+  const [dynamicAliases, setDynamicAliases] = useState<IconAliasMap>({});
+
+  // Merge aliases: parent (if extend) + initial + dynamic
+  const mergedAliases = useMemo(() => {
+    const base = extend ? { ...parentContext.aliases } : {};
+    return {
+      ...base,
+      ...initialAliases,
+      ...dynamicAliases,
+    };
+  }, [parentContext.aliases, initialAliases, dynamicAliases, extend]);
+
+  // Validate aliases in development
+  if (__DEV__) {
+    Object.entries(initialAliases).forEach(([alias, iconName]) => {
+      validateIconName(iconName, alias);
+    });
+  }
+
+  // Resolve icon name
+  const resolveIcon = useCallback(
+    (name: string): string => {
+      // If it's already a full icon name, return as-is
+      if (isFullIconName(name)) {
+        return name;
+      }
+
+      // Look up in aliases
+      const resolved = mergedAliases[name];
+      if (resolved) {
+        return resolved;
+      }
+
+      // Not found - warn in dev and return original
+      if (__DEV__) {
+        console.warn(
+          `[rn-iconify] Unknown icon alias "${name}". ` +
+            `Use a full icon name (prefix:name) or register the alias.`
+        );
+      }
+
+      return name;
+    },
+    [mergedAliases]
+  );
+
+  // Check if name is a registered alias
+  const isAlias = useCallback(
+    (name: string): boolean => {
+      return name in mergedAliases;
+    },
+    [mergedAliases]
+  );
+
+  // Register additional aliases at runtime
+  const registerAliases = useCallback((newAliases: IconAliasMap) => {
+    if (__DEV__) {
+      Object.entries(newAliases).forEach(([alias, iconName]) => {
+        validateIconName(iconName, alias);
+      });
+    }
+
+    setDynamicAliases((prev) => ({
+      ...prev,
+      ...newAliases,
+    }));
+  }, []);
+
+  const contextValue = useMemo<IconAliasContextValue>(
+    () => ({
+      aliases: mergedAliases,
+      resolveIcon,
+      isAlias,
+      registerAliases,
+    }),
+    [mergedAliases, resolveIcon, isAlias, registerAliases]
+  );
+
+  return <IconAliasContext.Provider value={contextValue}>{children}</IconAliasContext.Provider>;
+}
+
+/**
+ * Default export for convenience
+ */
+export default IconAliasProvider;

package/src/alias/createIconAliases.tsx

@@ -0,0 +1,233 @@
+/**
+ * createIconAliases - Factory function for creating type-safe icon aliases
+ * Provides full TypeScript autocomplete for alias names
+ */
+
+import React from 'react';
+import { IconRenderer } from '../IconRenderer';
+import { useIconTheme } from '../theme';
+import { DEFAULT_ICON_THEME } from '../theme/types';
+import { IconAliasProvider as BaseProvider } from './IconAliasContext';
+import type {
+  IconAliasMap,
+  IconAliases,
+  AliasName,
+  GenericIconProps,
+  CreateIconAliasesConfig,
+  IconAliasResult,
+} from './types';
+
+/**
+ * Validate that all alias values are valid icon names
+ */
+function validateAliases<T extends IconAliasMap>(aliases: T): void {
+  Object.entries(aliases).forEach(([alias, iconName]) => {
+    if (typeof iconName !== 'string') {
+      throw new Error(
+        `[rn-iconify] Invalid alias value for "${alias}": expected string, got ${typeof iconName}`
+      );
+    }
+
+    if (!iconName.includes(':')) {
+      throw new Error(
+        `[rn-iconify] Invalid icon name for alias "${alias}": "${iconName}". ` +
+          `Icon names must be in "prefix:name" format (e.g., "mdi:home").`
+      );
+    }
+  });
+}
+
+/**
+ * Create a type-safe icon alias system
+ *
+ * This function creates:
+ * - A typed Icon component with autocomplete for alias names
+ * - A Provider component to wrap your app
+ * - A resolve function to convert aliases to full icon names
+ *
+ * @example Basic usage
+ * ```tsx
+ * // icons.ts
+ * import { createIconAliases } from 'rn-iconify';
+ *
+ * export const { Icon, Provider: IconProvider, aliases } = createIconAliases({
+ *   aliases: {
+ *     back: 'mdi:arrow-left',
+ *     forward: 'mdi:arrow-right',
+ *     menu: 'heroicons:bars-3',
+ *     close: 'mdi:close',
+ *     home: 'mdi:home',
+ *     settings: 'lucide:settings',
+ *   } as const,
+ * });
+ *
+ * // App.tsx
+ * import { Icon, IconProvider } from './icons';
+ *
+ * function App() {
+ *   return (
+ *     <IconProvider>
+ *       <Icon name="back" size={24} />    {// TypeScript autocomplete! }
+ *       <Icon name="menu" color="blue" />
+ *     </IconProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example With navigation
+ * ```tsx
+ * import { Icon } from './icons';
+ *
+ * <Tab.Screen
+ *   options={{
+ *     tabBarIcon: ({ color, size }) => (
+ *       <Icon name="home" color={color} size={size} />
+ *     ),
+ *   }}
+ * />
+ * ```
+ */
+export function createIconAliases<T extends IconAliasMap>(
+  config: CreateIconAliasesConfig<T>
+): IconAliasResult<T> {
+  const { aliases, validate = true } = config;
+
+  // Validate in development
+  if (__DEV__ && validate) {
+    validateAliases(aliases);
+  }
+
+  // Create resolve function
+  const resolve = (name: AliasName<T> | string): string => {
+    // If it's already a full icon name, return as-is
+    if (name.includes(':')) {
+      return name;
+    }
+
+    // Look up in aliases
+    const resolved = (aliases as IconAliasMap)[name];
+    if (resolved) {
+      return resolved;
+    }
+
+    // Not found - warn in dev
+    if (__DEV__) {
+      console.warn(
+        `[rn-iconify] Unknown alias "${name}". Available aliases: ${Object.keys(aliases).join(', ')}`
+      );
+    }
+
+    return name;
+  };
+
+  /**
+   * Type-safe Icon component with alias support
+   */
+  function TypedIcon({
+    name,
+    size,
+    color,
+    width,
+    height,
+    style,
+    rotate,
+    flip,
+    fallback,
+    fallbackDelay,
+    placeholder,
+    placeholderColor,
+    placeholderDuration,
+    onLoad,
+    onError,
+    accessibilityLabel,
+    testID,
+  }: GenericIconProps<AliasName<T>>) {
+    // Get theme defaults
+    const { theme } = useIconTheme();
+
+    // Resolve the icon name
+    const resolvedName = resolve(name);
+
+    // Merge props with theme defaults
+    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;
+
+    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}
+      />
+    );
+  }
+
+  TypedIcon.displayName = 'TypedIcon';
+
+  /**
+   * Provider component (pre-configured with aliases)
+   */
+  function Provider({ children }: { children: React.ReactNode }) {
+    return <BaseProvider aliases={aliases}>{children}</BaseProvider>;
+  }
+
+  Provider.displayName = 'IconAliasProvider';
+
+  return {
+    aliases: aliases as IconAliases<T>,
+    Icon: TypedIcon,
+    Provider,
+    resolve,
+    // Type helper - this is just for type inference, not a runtime value
+    AliasName: '' as AliasName<T>,
+  };
+}
+
+/**
+ * Quick helper to create aliases without full type safety
+ * Useful for simple cases or when aliases are dynamic
+ *
+ * @example
+ * ```tsx
+ * import { defineAliases, Icon, IconAliasProvider } from 'rn-iconify';
+ *
+ * const aliases = defineAliases({
+ *   back: 'mdi:arrow-left',
+ *   menu: 'heroicons:bars-3',
+ * });
+ *
+ * <IconAliasProvider aliases={aliases}>
+ *   <Icon name="back" />
+ * </IconAliasProvider>
+ * ```
+ */
+export function defineAliases<T extends IconAliasMap>(aliases: T): T {
+  if (__DEV__) {
+    validateAliases(aliases);
+  }
+  return aliases;
+}
+
+export default createIconAliases;

package/src/alias/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Icon Alias System
+ * Create custom icon name mappings for consistent usage across your app
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { createIconAliases } from 'rn-iconify';
+ *
+ * const { Icon, Provider } = createIconAliases({
+ *   aliases: {
+ *     back: 'mdi:arrow-left',
+ *     menu: 'heroicons:bars-3',
+ *   } as const,
+ * });
+ *
+ * <Provider>
+ *   <Icon name="back" />
+ * </Provider>
+ * ```
+ *
+ * @example With generic Icon component
+ * ```tsx
+ * import { Icon, IconAliasProvider } from 'rn-iconify';
+ *
+ * <IconAliasProvider aliases={{ back: 'mdi:arrow-left' }}>
+ *   <Icon name="back" />
+ *   <Icon name="mdi:home" />  // Full names still work
+ * </IconAliasProvider>
+ * ```
+ */
+
+// Types
+export type {
+  IconAliasMap,
+  IconAliases,
+  AliasName,
+  GenericIconProps,
+  IconAliasContextValue,
+  IconAliasProviderProps,
+  CreateIconAliasesConfig,
+  IconAliasResult,
+} from './types';
+
+// Context and Provider
+export {
+  IconAliasContext,
+  IconAliasProvider,
+  useIconAliasContext,
+  useResolveIcon,
+} from './IconAliasContext';
+
+// Generic Icon component
+export { Icon } from './Icon';
+
+// Factory functions
+export { createIconAliases, defineAliases } from './createIconAliases';
+
+// Default export
+export { createIconAliases as default } from './createIconAliases';

package/src/alias/types.ts

@@ -0,0 +1,132 @@
+/**
+ * Icon Alias System Types
+ * Type definitions for the icon alias feature
+ */
+
+import type { IconProps } from '../types';
+
+/**
+ * Icon alias definition - maps alias name to full icon name
+ * @example { back: 'mdi:arrow-left', menu: 'heroicons:bars-3' }
+ */
+export type IconAliasMap = Record<string, string>;
+
+/**
+ * Type-safe alias configuration
+ * Uses 'as const' for full TypeScript inference
+ */
+export type IconAliases<T extends IconAliasMap> = {
+  readonly [K in keyof T]: T[K];
+};
+
+/**
+ * Extract alias names from an alias map
+ */
+export type AliasName<T extends IconAliasMap> = keyof T & string;
+
+/**
+ * Props for the generic Icon component
+ * Accepts either a full icon name (prefix:name) or an alias
+ */
+export interface GenericIconProps<TAlias extends string = string>
+  extends Omit<IconProps<TAlias>, 'name'> {
+  /**
+   * Icon name - can be:
+   * - Full icon name: "mdi:home", "heroicons:user"
+   * - Alias name: "back", "menu" (if aliases are configured)
+   */
+  name: TAlias | string;
+}
+
+/**
+ * Icon alias context value
+ */
+export interface IconAliasContextValue {
+  /**
+   * Registered aliases
+   */
+  aliases: IconAliasMap;
+
+  /**
+   * Resolve an alias or icon name to full icon name
+   * @param name Alias or full icon name
+   * @returns Full icon name (prefix:name format)
+   */
+  resolveIcon: (name: string) => string;
+
+  /**
+   * Check if a name is a registered alias
+   */
+  isAlias: (name: string) => boolean;
+
+  /**
+   * Register additional aliases at runtime
+   */
+  registerAliases: (newAliases: IconAliasMap) => void;
+}
+
+/**
+ * Props for IconAliasProvider
+ */
+export interface IconAliasProviderProps {
+  /**
+   * Icon alias definitions
+   */
+  aliases: IconAliasMap;
+
+  /**
+   * Allow extending parent aliases (default: true)
+   */
+  extend?: boolean;
+
+  /**
+   * Children components
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * Configuration for createIconAliases
+ */
+export interface CreateIconAliasesConfig<T extends IconAliasMap> {
+  /**
+   * Alias definitions
+   */
+  aliases: T;
+
+  /**
+   * Validate icon names at creation time (dev only)
+   * @default true
+   */
+  validate?: boolean;
+}
+
+/**
+ * Return type for createIconAliases
+ */
+export interface IconAliasResult<T extends IconAliasMap> {
+  /**
+   * The alias map
+   */
+  aliases: IconAliases<T>;
+
+  /**
+   * Type-safe Icon component with alias support
+   */
+  Icon: React.ComponentType<GenericIconProps<AliasName<T>>>;
+
+  /**
+   * Provider component for alias context
+   */
+  Provider: React.ComponentType<{ children: React.ReactNode }>;
+
+  /**
+   * Resolve function
+   */
+  resolve: (name: AliasName<T> | string) => string;
+
+  /**
+   * Type helper for alias names
+   */
+  AliasName: AliasName<T>;
+}

package/src/animated/AnimatedIcon.tsx

@@ -0,0 +1,116 @@
+/**
+ * AnimatedIcon - Wrapper component for animated icons
+ * Provides animation capabilities to any icon component
+ */
+
+import React, { forwardRef, useImperativeHandle } from 'react';
+import { Animated, StyleSheet } from 'react-native';
+import { useIconAnimation } from './useIconAnimation';
+import type { AnimatedIconProps, AnimationControls } from './types';
+
+/**
+ * AnimatedIcon wrapper component
+ * Wraps any icon component to add animation capabilities
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { AnimatedIcon } from 'rn-iconify/animated';
+ * import { Mdi } from 'rn-iconify';
+ *
+ * <AnimatedIcon animate="spin">
+ *   <Mdi name="loading" size={24} />
+ * </AnimatedIcon>
+ * ```
+ *
+ * @example With custom configuration
+ * ```tsx
+ * <AnimatedIcon
+ *   animate={{ type: 'rotate', duration: 2000, easing: 'linear' }}
+ *   autoPlay={true}
+ * >
+ *   <Mdi name="sync" size={24} />
+ * </AnimatedIcon>
+ * ```
+ *
+ * @example With ref for animation control
+ * ```tsx
+ * const animationRef = useRef<AnimationControls>(null);
+ *
+ * <AnimatedIcon ref={animationRef} animate="bounce" autoPlay={false}>
+ *   <Mdi name="heart" size={24} />
+ * </AnimatedIcon>
+ *
+ * // Later
+ * animationRef.current?.start();
+ * ```
+ */
+export const AnimatedIcon = forwardRef<AnimationControls, AnimatedIconProps>(function AnimatedIcon(
+  {
+    children,
+    animate,
+    animationDuration,
+    animationLoop,
+    animationEasing,
+    animationDelay,
+    autoPlay = true,
+    onAnimationComplete,
+    width,
+    height,
+    testID,
+  },
+  ref
+) {
+  const { animatedStyle, hasAnimation, start, stop, pause, resume, reset, state, isAnimating } =
+    useIconAnimation({
+      animation: animate,
+      duration: animationDuration,
+      loop: animationLoop,
+      easing: animationEasing,
+      delay: animationDelay,
+      autoPlay,
+      onComplete: onAnimationComplete,
+    });
+
+  // Expose animation controls via ref
+  useImperativeHandle(
+    ref,
+    () => ({
+      start,
+      stop,
+      pause,
+      resume,
+      reset,
+      state,
+      isAnimating,
+    }),
+    [start, stop, pause, resume, reset, state, isAnimating]
+  );
+
+  // If no animation, render children directly
+  if (!hasAnimation) {
+    return <>{children}</>;
+  }
+
+  return (
+    <Animated.View
+      style={[
+        styles.container,
+        width !== undefined && { width },
+        height !== undefined && { height },
+        animatedStyle,
+      ]}
+      testID={testID}
+    >
+      {children}
+    </Animated.View>
+  );
+});
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+});
+
+export default AnimatedIcon;