rn-iconify 1.0.0 → 2.0.0

package/src/placeholder/Pulse.tsx

@@ -0,0 +1,86 @@
+/**
+ * Pulse Placeholder Component
+ * Animated opacity fade effect while icon is loading
+ */
+
+import React, { memo, useEffect, useRef } from 'react';
+import { Animated, StyleSheet, Easing } from 'react-native';
+import { DEFAULT_PLACEHOLDER_CONFIG } from './types';
+import type { PlaceholderProps } from './types';
+
+/**
+ * Pulse placeholder - animated opacity fade effect
+ * Provides subtle visual feedback during loading
+ */
+function PulseComponent({
+  width,
+  height,
+  color = DEFAULT_PLACEHOLDER_CONFIG.color,
+  duration = DEFAULT_PLACEHOLDER_CONFIG.duration,
+  borderRadius = DEFAULT_PLACEHOLDER_CONFIG.borderRadius,
+  testID,
+}: PlaceholderProps): React.ReactElement {
+  const opacity = useRef(new Animated.Value(1)).current;
+  const animationRef = useRef<Animated.CompositeAnimation | null>(null);
+
+  useEffect(() => {
+    // Create looping pulse animation
+    animationRef.current = Animated.loop(
+      Animated.sequence([
+        Animated.timing(opacity, {
+          toValue: 0.4,
+          duration: duration / 2,
+          easing: Easing.inOut(Easing.ease),
+          useNativeDriver: true,
+        }),
+        Animated.timing(opacity, {
+          toValue: 1,
+          duration: duration / 2,
+          easing: Easing.inOut(Easing.ease),
+          useNativeDriver: true,
+        }),
+      ])
+    );
+
+    animationRef.current.start();
+
+    return () => {
+      // Clean up animation on unmount
+      if (animationRef.current) {
+        animationRef.current.stop();
+      }
+    };
+  }, [opacity, duration]);
+
+  return (
+    <Animated.View
+      style={[
+        styles.pulse,
+        {
+          width,
+          height,
+          backgroundColor: color,
+          borderRadius,
+          opacity,
+        },
+      ]}
+      testID={testID}
+      accessibilityRole="none"
+      accessibilityElementsHidden
+      importantForAccessibility="no"
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  pulse: {
+    overflow: 'hidden',
+  },
+});
+
+/**
+ * Memoized Pulse component
+ * Animation runs independently of re-renders
+ */
+export const Pulse = memo(PulseComponent);
+Pulse.displayName = 'Pulse';

package/src/placeholder/Shimmer.tsx

@@ -0,0 +1,104 @@
+/**
+ * Shimmer Placeholder Component
+ * Animated gradient sweep effect while icon is loading
+ */
+
+import React, { memo, useEffect, useRef } from 'react';
+import { Animated, StyleSheet, View, Easing } from 'react-native';
+import { DEFAULT_PLACEHOLDER_CONFIG } from './types';
+import type { PlaceholderProps } from './types';
+
+/**
+ * Shimmer placeholder - animated light sweep effect
+ * Provides prominent visual feedback during loading
+ * Uses translateX animation for smooth performance
+ */
+function ShimmerComponent({
+  width,
+  height,
+  color = DEFAULT_PLACEHOLDER_CONFIG.color,
+  highlightColor = DEFAULT_PLACEHOLDER_CONFIG.highlightColor,
+  duration = DEFAULT_PLACEHOLDER_CONFIG.duration,
+  borderRadius = DEFAULT_PLACEHOLDER_CONFIG.borderRadius,
+  testID,
+}: PlaceholderProps): React.ReactElement {
+  const translateX = useRef(new Animated.Value(-width)).current;
+  const animationRef = useRef<Animated.CompositeAnimation | null>(null);
+
+  useEffect(() => {
+    // Reset animation when width changes
+    translateX.setValue(-width);
+
+    // Create looping shimmer animation
+    animationRef.current = Animated.loop(
+      Animated.timing(translateX, {
+        toValue: width,
+        duration: duration,
+        easing: Easing.linear,
+        useNativeDriver: true,
+      })
+    );
+
+    animationRef.current.start();
+
+    return () => {
+      // Clean up animation on unmount
+      if (animationRef.current) {
+        animationRef.current.stop();
+      }
+    };
+  }, [translateX, width, duration]);
+
+  // Calculate shimmer bar width (30% of container width)
+  const shimmerWidth = Math.max(width * 0.3, 20);
+
+  return (
+    <View
+      style={[
+        styles.container,
+        {
+          width,
+          height,
+          backgroundColor: color,
+          borderRadius,
+        },
+      ]}
+      testID={testID}
+      accessibilityRole="none"
+      accessibilityElementsHidden
+      importantForAccessibility="no"
+    >
+      <Animated.View
+        style={[
+          styles.shimmer,
+          {
+            width: shimmerWidth,
+            height,
+            backgroundColor: highlightColor,
+            transform: [{ translateX }],
+          },
+        ]}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    overflow: 'hidden',
+    position: 'relative',
+  },
+  shimmer: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    opacity: 0.5,
+  },
+});
+
+/**
+ * Memoized Shimmer component
+ * Animation runs independently of re-renders
+ */
+export const Shimmer = memo(ShimmerComponent);
+Shimmer.displayName = 'Shimmer';

package/src/placeholder/Skeleton.tsx

@@ -0,0 +1,52 @@
+/**
+ * Skeleton Placeholder Component
+ * Static gray box shown while icon is loading
+ */
+
+import React, { memo } from 'react';
+import { View, StyleSheet } from 'react-native';
+import { DEFAULT_PLACEHOLDER_CONFIG } from './types';
+import type { PlaceholderProps } from './types';
+
+/**
+ * Skeleton placeholder - a simple static colored box
+ * Lightweight alternative when animation is not needed
+ */
+function SkeletonComponent({
+  width,
+  height,
+  color = DEFAULT_PLACEHOLDER_CONFIG.color,
+  borderRadius = DEFAULT_PLACEHOLDER_CONFIG.borderRadius,
+  testID,
+}: PlaceholderProps): React.ReactElement {
+  return (
+    <View
+      style={[
+        styles.skeleton,
+        {
+          width,
+          height,
+          backgroundColor: color,
+          borderRadius,
+        },
+      ]}
+      testID={testID}
+      accessibilityRole="none"
+      accessibilityElementsHidden
+      importantForAccessibility="no"
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  skeleton: {
+    overflow: 'hidden',
+  },
+});
+
+/**
+ * Memoized Skeleton component
+ * Only re-renders when dimensions or styling change
+ */
+export const Skeleton = memo(SkeletonComponent);
+Skeleton.displayName = 'Skeleton';

package/src/placeholder/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Placeholder System
+ * Provides visual feedback while icons are loading
+ */
+
+// Types
+export type {
+  PlaceholderPreset,
+  PlaceholderType,
+  PlaceholderConfig,
+  PlaceholderProps,
+} from './types';
+
+export { DEFAULT_PLACEHOLDER_CONFIG } from './types';
+
+// Components
+export { Skeleton } from './Skeleton';
+export { Pulse } from './Pulse';
+export { Shimmer } from './Shimmer';
+export { PlaceholderFactory } from './PlaceholderFactory';
+export type { PlaceholderFactoryProps } from './PlaceholderFactory';

package/src/placeholder/types.ts

@@ -0,0 +1,78 @@
+/**
+ * Placeholder System Types
+ * Provides type definitions for icon loading placeholders
+ */
+
+import type { ReactNode } from 'react';
+
+/**
+ * Built-in placeholder animation types
+ * - skeleton: Static gray box (no animation)
+ * - pulse: Opacity fade animation
+ * - shimmer: Gradient sweep animation
+ */
+export type PlaceholderPreset = 'skeleton' | 'pulse' | 'shimmer';
+
+/**
+ * Placeholder type - can be a preset string or custom ReactNode
+ */
+export type PlaceholderType = PlaceholderPreset | ReactNode;
+
+/**
+ * Configuration for placeholder appearance
+ */
+export interface PlaceholderConfig {
+  /**
+   * Placeholder background color
+   * @default '#E1E1E1'
+   */
+  color?: string;
+
+  /**
+   * Secondary color for shimmer gradient
+   * @default '#F5F5F5'
+   */
+  highlightColor?: string;
+
+  /**
+   * Animation duration in milliseconds
+   * @default 1000
+   */
+  duration?: number;
+
+  /**
+   * Border radius of the placeholder
+   * @default 4
+   */
+  borderRadius?: number;
+}
+
+/**
+ * Props for placeholder components
+ */
+export interface PlaceholderProps extends PlaceholderConfig {
+  /**
+   * Width of the placeholder
+   */
+  width: number;
+
+  /**
+   * Height of the placeholder
+   */
+  height: number;
+
+  /**
+   * Test ID for testing
+   */
+  testID?: string;
+}
+
+/**
+ * Default placeholder configuration values
+ */
+export const DEFAULT_PLACEHOLDER_CONFIG: Required<PlaceholderConfig> = {
+  color: '#E1E1E1',
+  highlightColor: '#F5F5F5',
+  duration: 1000,
+  borderRadius: 4,
+};

package/src/theme/IconThemeProvider.tsx

@@ -0,0 +1,94 @@
+/**
+ * IconThemeProvider
+ * Provides global theme configuration for all icon components
+ */
+
+import React, { useState, useMemo, useCallback, memo } from 'react';
+import { IconThemeContext, mergeWithDefaults } from './context';
+import type { IconThemeProviderProps, IconTheme, IconThemeContextValue } from './types';
+
+/**
+ * IconThemeProvider
+ *
+ * Wraps your app to provide global icon theming.
+ * All descendant icon components will inherit these defaults.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { IconThemeProvider } from 'rn-iconify';
+ *
+ * export default function App() {
+ *   return (
+ *     <IconThemeProvider theme={{ size: 20, color: '#333' }}>
+ *       <YourApp />
+ *     </IconThemeProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example With placeholder defaults
+ * ```tsx
+ * <IconThemeProvider
+ *   theme={{
+ *     size: 24,
+ *     color: '#1a1a1a',
+ *     placeholder: 'shimmer',
+ *     placeholderColor: '#f0f0f0',
+ *   }}
+ * >
+ *   <YourApp />
+ * </IconThemeProvider>
+ * ```
+ *
+ * @example Dynamic theme switching
+ * ```tsx
+ * function App() {
+ *   const [isDark, setIsDark] = useState(false);
+ *
+ *   return (
+ *     <IconThemeProvider
+ *       theme={{
+ *         color: isDark ? '#ffffff' : '#000000',
+ *         placeholderColor: isDark ? '#333333' : '#e1e1e1',
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </IconThemeProvider>
+ *   );
+ * }
+ * ```
+ */
+function IconThemeProviderComponent({
+  theme: initialTheme,
+  children,
+}: IconThemeProviderProps): React.ReactElement {
+  const [theme, setThemeState] = useState<IconTheme>(() => mergeWithDefaults(initialTheme));
+
+  // Memoized setTheme that supports both direct value and updater function
+  const setTheme = useCallback((newTheme: IconTheme | ((prev: IconTheme) => IconTheme)) => {
+    setThemeState((prevTheme) => {
+      const nextTheme = typeof newTheme === 'function' ? newTheme(prevTheme) : newTheme;
+      return mergeWithDefaults(nextTheme);
+    });
+  }, []);
+
+  // Update internal state when prop changes
+  React.useEffect(() => {
+    setThemeState(mergeWithDefaults(initialTheme));
+  }, [initialTheme]);
+
+  // Memoize context value to prevent unnecessary re-renders
+  const contextValue = useMemo<IconThemeContextValue>(
+    () => ({
+      theme,
+      setTheme,
+    }),
+    [theme, setTheme]
+  );
+
+  return <IconThemeContext.Provider value={contextValue}>{children}</IconThemeContext.Provider>;
+}
+
+IconThemeProviderComponent.displayName = 'IconThemeProvider';
+
+export const IconThemeProvider = memo(IconThemeProviderComponent);

package/src/theme/context.ts

@@ -0,0 +1,51 @@
+/**
+ * IconThemeContext
+ * React Context for icon theming
+ */
+
+import { createContext } from 'react';
+import type { IconThemeContextValue, IconTheme } from './types';
+import { DEFAULT_ICON_THEME } from './types';
+
+/**
+ * Default context value when no provider is present
+ * setTheme is a no-op by default
+ */
+const defaultContextValue: IconThemeContextValue = {
+  theme: DEFAULT_ICON_THEME,
+  setTheme: () => {
+    if (__DEV__) {
+      console.warn(
+        '[rn-iconify] setTheme called without IconThemeProvider. ' +
+          'Wrap your app with <IconThemeProvider> to enable theme updates.'
+      );
+    }
+  },
+};
+
+/**
+ * IconThemeContext
+ *
+ * Provides icon theme configuration to all descendant icon components.
+ * Use with IconThemeProvider for proper functionality.
+ *
+ * @example
+ * ```tsx
+ * // Access theme directly (prefer useIconTheme hook instead)
+ * const { theme, setTheme } = useContext(IconThemeContext);
+ * ```
+ */
+export const IconThemeContext = createContext<IconThemeContextValue>(defaultContextValue);
+
+IconThemeContext.displayName = 'IconThemeContext';
+
+/**
+ * Helper to merge theme with defaults
+ * Ensures all required properties have values
+ */
+export function mergeWithDefaults(theme: IconTheme): IconTheme {
+  return {
+    ...DEFAULT_ICON_THEME,
+    ...theme,
+  };
+}

package/src/theme/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Theme System
+ * Global icon theming and configuration
+ */
+
+// Components
+export { IconThemeProvider } from './IconThemeProvider';
+
+// Context
+export { IconThemeContext, mergeWithDefaults } from './context';
+
+// Hooks
+export { useIconTheme, useIconThemeValue, useMergedIconProps } from './useIconTheme';
+
+// Types
+export type { IconTheme, IconThemeProviderProps, IconThemeContextValue } from './types';
+
+// Constants
+export { DEFAULT_ICON_THEME } from './types';

package/src/theme/types.ts

@@ -0,0 +1,108 @@
+/**
+ * Theme System Types
+ * Defines types for global icon theming and configuration
+ */
+
+import type { ReactNode } from 'react';
+import type { PlaceholderType } from '../placeholder/types';
+import type { IconRotation, IconFlip } from '../types';
+
+/**
+ * Icon theme configuration
+ * All properties are optional - components will use their own defaults if not provided
+ */
+export interface IconTheme {
+  /**
+   * Default icon size (width and height)
+   * @default 24
+   */
+  size?: number;
+
+  /**
+   * Default icon color
+   * @default '#000000'
+   */
+  color?: string;
+
+  /**
+   * Default placeholder type shown while icons load
+   * @example 'shimmer'
+   */
+  placeholder?: PlaceholderType;
+
+  /**
+   * Default placeholder background color
+   * @default '#E1E1E1'
+   */
+  placeholderColor?: string;
+
+  /**
+   * Default placeholder animation duration in milliseconds
+   * @default 1000
+   */
+  placeholderDuration?: number;
+
+  /**
+   * Default rotation for all icons
+   * @default 0
+   */
+  rotate?: IconRotation;
+
+  /**
+   * Default flip direction for all icons
+   */
+  flip?: IconFlip;
+
+  /**
+   * Default fallback delay in milliseconds
+   * @default 0
+   */
+  fallbackDelay?: number;
+}
+
+/**
+ * Props for IconThemeProvider component
+ */
+export interface IconThemeProviderProps {
+  /**
+   * Theme configuration
+   */
+  theme: IconTheme;
+
+  /**
+   * Child components that will receive the theme
+   */
+  children: ReactNode;
+}
+
+/**
+ * Context value for icon theme
+ */
+export interface IconThemeContextValue {
+  /**
+   * Current theme configuration
+   */
+  theme: IconTheme;
+
+  /**
+   * Update theme dynamically
+   * Useful for theme switching (e.g., dark mode)
+   */
+  setTheme: (theme: IconTheme | ((prev: IconTheme) => IconTheme)) => void;
+}
+
+/**
+ * Default theme values
+ * Used when no theme is provided or for missing properties
+ */
+export const DEFAULT_ICON_THEME: Required<Omit<IconTheme, 'placeholder' | 'flip'>> &
+  Pick<IconTheme, 'placeholder' | 'flip'> = {
+  size: 24,
+  color: '#000000',
+  placeholder: undefined,
+  placeholderColor: '#E1E1E1',
+  placeholderDuration: 1000,
+  rotate: 0,
+  flip: undefined,
+  fallbackDelay: 0,
+};