react-native-puff-pop 1.0.6 → 1.0.8

package/src/index.tsx

@@ -4,6 +4,7 @@ import {
   useState,
   useCallback,
   useMemo,
+  memo,
   Children,
   type ReactNode,
   type ReactElement,
@@ -33,7 +34,12 @@ export type PuffPopEffect =
   | 'bounce' // Bounce effect with overshoot
   | 'flip' // 3D flip effect
   | 'zoom' // Zoom with slight overshoot
-  | 'rotateScale'; // Rotate + Scale combined
+  | 'rotateScale' // Rotate + Scale combined
+  | 'shake' // Shake left-right (흔들림 효과)
+  | 'pulse' // Pulse scale effect (맥박처럼 커졌다 작아짐)
+  | 'swing' // Swing like pendulum (시계추처럼 흔들림)
+  | 'wobble' // Wobble with tilt (기울어지며 이동)
+  | 'elastic'; // Elastic stretch effect (탄성 효과)
 
 /**
  * Easing function types
@@ -46,6 +52,51 @@ export type PuffPopEasing =
   | 'spring'
   | 'bounce';
 
+/**
+ * Anchor point for scale/rotate transformations
+ * Determines the origin point of the transformation
+ */
+export type PuffPopAnchorPoint =
+  | 'center' // Default center point
+  | 'top' // Top center
+  | 'bottom' // Bottom center
+  | 'left' // Left center
+  | 'right' // Right center
+  | 'topLeft' // Top left corner
+  | 'topRight' // Top right corner
+  | 'bottomLeft' // Bottom left corner
+  | 'bottomRight'; // Bottom right corner
+
+/**
+ * Spring animation configuration
+ * Used when useSpring is true for physics-based animations
+ */
+export interface PuffPopSpringConfig {
+  /**
+   * Controls the spring stiffness. Higher values = faster, snappier animation
+   * @default 100
+   */
+  tension?: number;
+
+  /**
+   * Controls the spring damping. Higher values = less oscillation
+   * @default 10
+   */
+  friction?: number;
+
+  /**
+   * Animation speed multiplier
+   * @default 12
+   */
+  speed?: number;
+
+  /**
+   * Controls the bounciness. Higher values = more bouncy
+   * @default 8
+   */
+  bounciness?: number;
+}
+
 export interface PuffPopProps {
   /**
    * Children to animate
@@ -135,6 +186,114 @@ export interface PuffPopProps {
    * Test ID for testing purposes
    */
   testID?: string;
+
+  // ============ Exit Animation Settings ============
+
+  /**
+   * Animation effect type when hiding (exit animation)
+   * If not specified, uses the reverse of the enter effect
+   */
+  exitEffect?: PuffPopEffect;
+
+  /**
+   * Animation duration for exit animation in milliseconds
+   * If not specified, uses the same duration as enter animation
+   */
+  exitDuration?: number;
+
+  /**
+   * Easing function for exit animation
+   * If not specified, uses the same easing as enter animation
+   */
+  exitEasing?: PuffPopEasing;
+
+  /**
+   * Delay before exit animation starts in milliseconds
+   * @default 0
+   */
+  exitDelay?: number;
+
+  // ============ Custom Initial Values ============
+
+  /**
+   * Custom initial opacity value (0-1)
+   * Overrides the default initial opacity for the effect
+   */
+  initialOpacity?: number;
+
+  /**
+   * Custom initial scale value
+   * Overrides the default initial scale for effects like 'scale', 'zoom', 'bounce'
+   */
+  initialScale?: number;
+
+  /**
+   * Custom initial rotation value in degrees
+   * Overrides the default initial rotation for effects like 'rotate', 'rotateScale'
+   */
+  initialRotate?: number;
+
+  /**
+   * Custom initial translateX value in pixels
+   * Overrides the default initial translateX for effects like 'slideLeft', 'slideRight'
+   */
+  initialTranslateX?: number;
+
+  /**
+   * Custom initial translateY value in pixels
+   * Overrides the default initial translateY for effects like 'slideUp', 'slideDown'
+   */
+  initialTranslateY?: number;
+
+  // ============ Reverse Mode ============
+
+  /**
+   * If true, reverses the animation direction
+   * - slideUp becomes slide from top
+   * - slideLeft becomes slide from left
+   * - rotate spins clockwise instead of counter-clockwise
+   * @default false
+   */
+  reverse?: boolean;
+
+  // ============ Animation Intensity ============
+
+  /**
+   * Animation intensity multiplier (0-1)
+   * Controls how far/much elements move during animation
+   * - 1 = full animation (default)
+   * - 0.5 = half the movement distance
+   * - 0 = no movement (instant appear)
+   * @default 1
+   */
+  intensity?: number;
+
+  // ============ Anchor Point ============
+
+  /**
+   * Anchor point for scale/rotate transformations
+   * Determines the origin point of the transformation
+   * - 'center' = default center point
+   * - 'top', 'bottom', 'left', 'right' = edge centers
+   * - 'topLeft', 'topRight', 'bottomLeft', 'bottomRight' = corners
+   * @default 'center'
+   */
+  anchorPoint?: PuffPopAnchorPoint;
+
+  // ============ Spring Animation ============
+
+  /**
+   * Use spring physics-based animation instead of timing
+   * Provides more natural, bouncy animations
+   * @default false
+   */
+  useSpring?: boolean;
+
+  /**
+   * Spring animation configuration
+   * Only used when useSpring is true
+   */
+  springConfig?: PuffPopSpringConfig;
 }
 
 /**
@@ -159,10 +318,133 @@ function getEasing(type: PuffPopEasing): (value: number) => number {
   }
 }
 
+/**
+ * Get effect flags for any effect type
+ * Returns flags indicating which transforms are needed for the effect
+ */
+function getEffectFlags(eff: PuffPopEffect) {
+  return {
+    hasScale: ['scale', 'bounce', 'zoom', 'rotateScale', 'flip', 'pulse', 'elastic'].includes(eff),
+    hasRotate: ['rotate', 'rotateScale', 'swing', 'wobble'].includes(eff),
+    hasFlip: eff === 'flip',
+    hasTranslateX: ['slideLeft', 'slideRight', 'shake', 'wobble'].includes(eff),
+    hasTranslateY: ['slideUp', 'slideDown', 'bounce'].includes(eff),
+    hasRotateEffect: ['rotate', 'rotateScale', 'flip', 'swing', 'wobble'].includes(eff),
+    // Special effects that need sequence animation
+    isShake: eff === 'shake',
+    isPulse: eff === 'pulse',
+    isSwing: eff === 'swing',
+    isWobble: eff === 'wobble',
+    isElastic: eff === 'elastic',
+  };
+}
+
+/**
+ * Get anchor point offset multipliers
+ * Returns { x: -1 to 1, y: -1 to 1 } where 0 is center
+ */
+function getAnchorPointOffset(anchorPoint: PuffPopAnchorPoint): { x: number; y: number } {
+  switch (anchorPoint) {
+    case 'top':
+      return { x: 0, y: -0.5 };
+    case 'bottom':
+      return { x: 0, y: 0.5 };
+    case 'left':
+      return { x: -0.5, y: 0 };
+    case 'right':
+      return { x: 0.5, y: 0 };
+    case 'topLeft':
+      return { x: -0.5, y: -0.5 };
+    case 'topRight':
+      return { x: 0.5, y: -0.5 };
+    case 'bottomLeft':
+      return { x: -0.5, y: 0.5 };
+    case 'bottomRight':
+      return { x: 0.5, y: 0.5 };
+    case 'center':
+    default:
+      return { x: 0, y: 0 };
+  }
+}
+
+/**
+ * Props comparison function for PuffPop memoization
+ * Performs shallow comparison of props to prevent unnecessary re-renders
+ */
+function arePuffPopPropsEqual(
+  prevProps: PuffPopProps,
+  nextProps: PuffPopProps
+): boolean {
+  // Compare primitive props
+  if (
+    prevProps.effect !== nextProps.effect ||
+    prevProps.duration !== nextProps.duration ||
+    prevProps.delay !== nextProps.delay ||
+    prevProps.easing !== nextProps.easing ||
+    prevProps.skeleton !== nextProps.skeleton ||
+    prevProps.visible !== nextProps.visible ||
+    prevProps.animateOnMount !== nextProps.animateOnMount ||
+    prevProps.loop !== nextProps.loop ||
+    prevProps.loopDelay !== nextProps.loopDelay ||
+    prevProps.respectReduceMotion !== nextProps.respectReduceMotion ||
+    prevProps.testID !== nextProps.testID ||
+    prevProps.reverse !== nextProps.reverse ||
+    prevProps.intensity !== nextProps.intensity ||
+    prevProps.anchorPoint !== nextProps.anchorPoint ||
+    prevProps.useSpring !== nextProps.useSpring ||
+    prevProps.exitEffect !== nextProps.exitEffect ||
+    prevProps.exitDuration !== nextProps.exitDuration ||
+    prevProps.exitEasing !== nextProps.exitEasing ||
+    prevProps.exitDelay !== nextProps.exitDelay ||
+    prevProps.initialOpacity !== nextProps.initialOpacity ||
+    prevProps.initialScale !== nextProps.initialScale ||
+    prevProps.initialRotate !== nextProps.initialRotate ||
+    prevProps.initialTranslateX !== nextProps.initialTranslateX ||
+    prevProps.initialTranslateY !== nextProps.initialTranslateY
+  ) {
+    return false;
+  }
+
+  // Compare springConfig object (shallow)
+  if (prevProps.springConfig !== nextProps.springConfig) {
+    if (
+      !prevProps.springConfig ||
+      !nextProps.springConfig ||
+      prevProps.springConfig.tension !== nextProps.springConfig.tension ||
+      prevProps.springConfig.friction !== nextProps.springConfig.friction ||
+      prevProps.springConfig.speed !== nextProps.springConfig.speed ||
+      prevProps.springConfig.bounciness !== nextProps.springConfig.bounciness
+    ) {
+      return false;
+    }
+  }
+
+  // Compare callbacks (reference equality - if changed, should re-render)
+  if (
+    prevProps.onAnimationStart !== nextProps.onAnimationStart ||
+    prevProps.onAnimationComplete !== nextProps.onAnimationComplete
+  ) {
+    return false;
+  }
+
+  // Style comparison - if style prop changes, re-render
+  // Note: Deep comparison of style is expensive, so we use reference equality
+  if (prevProps.style !== nextProps.style) {
+    return false;
+  }
+
+  // Children comparison - if children change, re-render
+  if (prevProps.children !== nextProps.children) {
+    return false;
+  }
+
+  return true;
+}
+
 /**
  * PuffPop - Animate children with beautiful entrance effects
  */
-export function PuffPop({
+function PuffPopComponent({
   children,
   effect = 'scale',
   duration = 400,
@@ -178,13 +460,57 @@ export function PuffPop({
   loopDelay = 0,
   respectReduceMotion = true,
   testID,
+  // Exit animation settings
+  exitEffect,
+  exitDuration,
+  exitEasing,
+  exitDelay = 0,
+  // Custom initial values
+  initialOpacity,
+  initialScale,
+  initialRotate,
+  initialTranslateX,
+  initialTranslateY,
+  // Reverse mode
+  reverse = false,
+  // Animation intensity
+  intensity = 1,
+  // Anchor point
+  anchorPoint = 'center',
+  // Spring animation
+  useSpring = false,
+  springConfig,
 }: PuffPopProps): ReactElement {
+  // Clamp intensity between 0 and 1
+  const clampedIntensity = Math.max(0, Math.min(1, intensity));
+
+  // Helper to get initial value with custom override, reverse, and intensity support
+  const getInitialOpacityValue = () => initialOpacity ?? 0;
+  const getInitialScaleValue = (eff: PuffPopEffect) => {
+    if (initialScale !== undefined) return initialScale;
+    const baseScale = getInitialScale(eff, reverse);
+    // Scale goes from baseScale to 1, so we interpolate: 1 - (1 - baseScale) * intensity
+    return 1 - (1 - baseScale) * clampedIntensity;
+  };
+  const getInitialRotateValue = (eff: PuffPopEffect) => {
+    if (initialRotate !== undefined) return initialRotate;
+    return getInitialRotate(eff, reverse) * clampedIntensity;
+  };
+  const getInitialTranslateXValue = (eff: PuffPopEffect) => {
+    if (initialTranslateX !== undefined) return initialTranslateX;
+    return getInitialTranslateX(eff, reverse) * clampedIntensity;
+  };
+  const getInitialTranslateYValue = (eff: PuffPopEffect) => {
+    if (initialTranslateY !== undefined) return initialTranslateY;
+    return getInitialTranslateY(eff, reverse) * clampedIntensity;
+  };
+
   // Animation values
-  const opacity = useRef(new Animated.Value(animateOnMount ? 0 : 1)).current;
-  const scale = useRef(new Animated.Value(animateOnMount ? getInitialScale(effect) : 1)).current;
-  const rotate = useRef(new Animated.Value(animateOnMount ? getInitialRotate(effect) : 0)).current;
-  const translateX = useRef(new Animated.Value(animateOnMount ? getInitialTranslateX(effect) : 0)).current;
-  const translateY = useRef(new Animated.Value(animateOnMount ? getInitialTranslateY(effect) : 0)).current;
+  const opacity = useRef(new Animated.Value(animateOnMount ? getInitialOpacityValue() : 1)).current;
+  const scale = useRef(new Animated.Value(animateOnMount ? getInitialScaleValue(effect) : 1)).current;
+  const rotate = useRef(new Animated.Value(animateOnMount ? getInitialRotateValue(effect) : 0)).current;
+  const translateX = useRef(new Animated.Value(animateOnMount ? getInitialTranslateXValue(effect) : 0)).current;
+  const translateY = useRef(new Animated.Value(animateOnMount ? getInitialTranslateYValue(effect) : 0)).current;
   
   // For non-skeleton mode
   const [measuredHeight, setMeasuredHeight] = useState<number | null>(null);
@@ -218,16 +544,15 @@ export function PuffPop({
 
   // Effective duration (0 if reduce motion is enabled)
   const effectiveDuration = respectReduceMotion && isReduceMotionEnabled ? 0 : duration;
+  const effectiveExitDuration = respectReduceMotion && isReduceMotionEnabled ? 0 : (exitDuration ?? duration);
 
   // Memoize effect type checks to avoid repeated includes() calls
-  const effectFlags = useMemo(() => ({
-    hasScale: ['scale', 'bounce', 'zoom', 'rotateScale', 'flip'].includes(effect),
-    hasRotate: ['rotate', 'rotateScale'].includes(effect),
-    hasFlip: effect === 'flip',
-    hasTranslateX: ['slideLeft', 'slideRight'].includes(effect),
-    hasTranslateY: ['slideUp', 'slideDown', 'bounce'].includes(effect),
-    hasRotateEffect: ['rotate', 'rotateScale', 'flip'].includes(effect),
-  }), [effect]);
+  const effectFlags = useMemo(() => getEffectFlags(effect), [effect]);
+  
+  // Exit effect flags (use exitEffect if specified, otherwise same as enter effect)
+  const exitEffectFlags = useMemo(() => 
+    exitEffect ? getEffectFlags(exitEffect) : effectFlags
+  , [exitEffect, effectFlags]);
 
   // Memoize interpolations to avoid recreating on every render
   const rotateInterpolation = useMemo(() => 
@@ -261,78 +586,116 @@ export function PuffPop({
         onAnimationStart();
       }
 
-      const easingFn = getEasing(easing);
+      // Determine which effect settings to use based on direction
+      const currentEffect = toVisible ? effect : (exitEffect ?? effect);
+      const currentDuration = toVisible ? effectiveDuration : effectiveExitDuration;
+      const currentEasing = toVisible ? easing : (exitEasing ?? easing);
+      const currentDelay = toVisible ? delay : exitDelay;
+      const currentFlags = toVisible ? effectFlags : exitEffectFlags;
+
+      const easingFn = getEasing(currentEasing);
       // When skeleton is false, we animate height which doesn't support native driver
       // So we must use JS driver for all animations in that case
       const useNative = skeleton;
-      const config = {
-        duration: effectiveDuration,
+      
+      // Spring configuration
+      const springConf = {
+        tension: springConfig?.tension ?? 100,
+        friction: springConfig?.friction ?? 10,
+        speed: springConfig?.speed,
+        bounciness: springConfig?.bounciness,
+        useNativeDriver: useNative,
+      };
+
+      const timingConfig = {
+        duration: currentDuration,
         easing: easingFn,
         useNativeDriver: useNative,
       };
 
+      // Helper to create animation (spring or timing)
+      const createAnimation = (
+        value: Animated.Value,
+        toValue: number,
+        customEasing?: (t: number) => number
+      ): Animated.CompositeAnimation => {
+        if (useSpring) {
+          return Animated.spring(value, {
+            toValue,
+            ...springConf,
+          });
+        }
+        return Animated.timing(value, {
+          toValue,
+          ...timingConfig,
+          ...(customEasing ? { easing: customEasing } : {}),
+        });
+      };
+
       const animations: Animated.CompositeAnimation[] = [];
 
-      // Opacity animation
+      // Opacity animation (always use timing for opacity for smoother fade)
       animations.push(
         Animated.timing(opacity, {
           toValue: toVisible ? 1 : 0,
-          ...config,
+          ...timingConfig,
         })
       );
 
       // Scale animation
-      if (effectFlags.hasScale) {
-        const targetScale = toVisible ? 1 : getInitialScale(effect);
-        animations.push(
-          Animated.timing(scale, {
-            toValue: targetScale,
-            ...config,
-            easing: effect === 'bounce' ? Easing.bounce : easingFn,
-          })
-        );
+      if (currentFlags.hasScale) {
+        const targetScale = toVisible ? 1 : getInitialScaleValue(currentEffect);
+        // Special easing for different effects
+        let scaleEasing = easingFn;
+        if (currentEffect === 'bounce') {
+          scaleEasing = Easing.bounce;
+        } else if (currentEffect === 'elastic') {
+          scaleEasing = Easing.elastic(1.5);
+        } else if (currentEffect === 'pulse') {
+          scaleEasing = Easing.out(Easing.back(3));
+        }
+        animations.push(createAnimation(scale, targetScale, scaleEasing));
       }
 
       // Rotate animation
-      if (effectFlags.hasRotate || effectFlags.hasFlip) {
-        const targetRotate = toVisible ? 0 : getInitialRotate(effect);
-        animations.push(
-          Animated.timing(rotate, {
-            toValue: targetRotate,
-            ...config,
-          })
-        );
+      if (currentFlags.hasRotate || currentFlags.hasFlip) {
+        const targetRotate = toVisible ? 0 : getInitialRotateValue(currentEffect);
+        // Special easing for swing and wobble
+        let rotateEasing = easingFn;
+        if (currentEffect === 'swing') {
+          rotateEasing = Easing.elastic(1.2);
+        } else if (currentEffect === 'wobble') {
+          rotateEasing = Easing.elastic(1.5);
+        }
+        animations.push(createAnimation(rotate, targetRotate, rotateEasing));
       }
 
       // TranslateX animation
-      if (effectFlags.hasTranslateX) {
-        const targetX = toVisible ? 0 : getInitialTranslateX(effect);
-        animations.push(
-          Animated.timing(translateX, {
-            toValue: targetX,
-            ...config,
-          })
-        );
+      if (currentFlags.hasTranslateX) {
+        const targetX = toVisible ? 0 : getInitialTranslateXValue(currentEffect);
+        // Special easing for shake and wobble
+        let translateXEasing = easingFn;
+        if (currentEffect === 'shake') {
+          translateXEasing = Easing.elastic(3);
+        } else if (currentEffect === 'wobble') {
+          translateXEasing = Easing.elastic(1.5);
+        }
+        animations.push(createAnimation(translateX, targetX, translateXEasing));
       }
 
       // TranslateY animation
-      if (effectFlags.hasTranslateY) {
-        const targetY = toVisible ? 0 : getInitialTranslateY(effect);
-        animations.push(
-          Animated.timing(translateY, {
-            toValue: targetY,
-            ...config,
-          })
-        );
+      if (currentFlags.hasTranslateY) {
+        const targetY = toVisible ? 0 : getInitialTranslateYValue(currentEffect);
+        animations.push(createAnimation(translateY, targetY));
       }
 
-      // Height animation for non-skeleton mode
+      // Height animation for non-skeleton mode (always use timing)
       if (!skeleton && measuredHeight !== null) {
         const targetHeight = toVisible ? measuredHeight : 0;
         animations.push(
           Animated.timing(animatedHeight, {
             toValue: targetHeight,
-            duration: effectiveDuration,
+            duration: currentDuration,
             easing: easingFn,
             useNativeDriver: false,
           })
@@ -344,11 +707,11 @@ export function PuffPop({
 
       // Reset values function for looping
       const resetValues = () => {
-        opacity.setValue(0);
-        scale.setValue(getInitialScale(effect));
-        rotate.setValue(getInitialRotate(effect));
-        translateX.setValue(getInitialTranslateX(effect));
-        translateY.setValue(getInitialTranslateY(effect));
+        opacity.setValue(getInitialOpacityValue());
+        scale.setValue(getInitialScaleValue(effect));
+        rotate.setValue(getInitialRotateValue(effect));
+        translateX.setValue(getInitialTranslateXValue(effect));
+        translateY.setValue(getInitialTranslateYValue(effect));
         if (!skeleton && measuredHeight !== null) {
           animatedHeight.setValue(0);
         }
@@ -357,9 +720,9 @@ export function PuffPop({
       // Build the animation sequence
       let animation: Animated.CompositeAnimation;
       
-      if (delay > 0) {
+      if (currentDelay > 0) {
         animation = Animated.sequence([
-          Animated.delay(delay),
+          Animated.delay(currentDelay),
           parallelAnimation,
         ]);
       } else {
@@ -430,9 +793,14 @@ export function PuffPop({
     [
       delay,
       effectiveDuration,
+      effectiveExitDuration,
       easing,
       effect,
       effectFlags,
+      exitEffect,
+      exitEffectFlags,
+      exitEasing,
+      exitDelay,
       measuredHeight,
       onAnimationComplete,
       onAnimationStart,
@@ -445,6 +813,8 @@ export function PuffPop({
       animatedHeight,
       loop,
       loopDelay,
+      useSpring,
+      springConfig,
     ]
   );
 
@@ -475,12 +845,36 @@ export function PuffPop({
     };
   }, []);
 
+  // Calculate anchor point offset (using 100px as base size for skeleton mode)
+  const anchorOffset = useMemo(() => {
+    const offset = getAnchorPointOffset(anchorPoint);
+    // Use measured height if available, otherwise use 100px as base
+    const baseSize = measuredHeight ?? 100;
+    return {
+      x: offset.x * baseSize,
+      y: offset.y * baseSize,
+    };
+  }, [anchorPoint, measuredHeight]);
+
   // Memoize transform array to avoid recreating on every render
   // IMPORTANT: All hooks must be called before any conditional returns
   const transform = useMemo(() => {
     const { hasScale, hasRotate, hasFlip, hasTranslateX, hasTranslateY } = effectFlags;
-    const transforms = [];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const transforms: any[] = [];
+    const needsAnchorOffset = anchorPoint !== 'center' && (hasScale || hasRotate || hasFlip);
+
+    // Step 1: Move to anchor point (negative offset)
+    if (needsAnchorOffset) {
+      if (anchorOffset.x !== 0) {
+        transforms.push({ translateX: -anchorOffset.x });
+      }
+      if (anchorOffset.y !== 0) {
+        transforms.push({ translateY: -anchorOffset.y });
+      }
+    }
 
+    // Step 2: Apply scale/rotate transforms
     if (hasScale) {
       transforms.push({ scale });
     }
@@ -493,6 +887,17 @@ export function PuffPop({
       transforms.push({ rotateY: flipInterpolation });
     }
 
+    // Step 3: Move back from anchor point (positive offset)
+    if (needsAnchorOffset) {
+      if (anchorOffset.x !== 0) {
+        transforms.push({ translateX: anchorOffset.x });
+      }
+      if (anchorOffset.y !== 0) {
+        transforms.push({ translateY: anchorOffset.y });
+      }
+    }
+
+    // Step 4: Apply other translate transforms
     if (hasTranslateX) {
       transforms.push({ translateX });
     }
@@ -502,7 +907,7 @@ export function PuffPop({
     }
 
     return transforms.length > 0 ? transforms : undefined;
-  }, [effectFlags, scale, rotateInterpolation, flipInterpolation, translateX, translateY]);
+  }, [effectFlags, scale, rotateInterpolation, flipInterpolation, translateX, translateY, anchorPoint, anchorOffset]);
 
   // Memoize animated style
   const animatedStyle = useMemo(() => ({
@@ -540,13 +945,18 @@ export function PuffPop({
   );
 }
 
+// Memoize PuffPop to prevent unnecessary re-renders
+export const PuffPop = memo(PuffPopComponent, arePuffPopPropsEqual);
+
 /**
  * Get initial scale value based on effect
  */
-function getInitialScale(effect: PuffPopEffect): number {
+function getInitialScale(effect: PuffPopEffect, _reverse = false): number {
+  // Scale doesn't change with reverse (parameter kept for consistent API)
   switch (effect) {
     case 'scale':
     case 'rotateScale':
+    case 'elastic':
       return 0;
     case 'bounce':
       return 0.3;
@@ -554,6 +964,8 @@ function getInitialScale(effect: PuffPopEffect): number {
       return 0.5;
     case 'flip':
       return 0.8;
+    case 'pulse':
+      return 0.6;
     default:
       return 1;
   }
@@ -562,14 +974,19 @@ function getInitialScale(effect: PuffPopEffect): number {
 /**
  * Get initial rotate value based on effect
  */
-function getInitialRotate(effect: PuffPopEffect): number {
+function getInitialRotate(effect: PuffPopEffect, reverse = false): number {
+  const multiplier = reverse ? -1 : 1;
   switch (effect) {
     case 'rotate':
-      return -360;
+      return -360 * multiplier;
     case 'rotateScale':
-      return -180;
+      return -180 * multiplier;
     case 'flip':
-      return -180;
+      return -180 * multiplier;
+    case 'swing':
+      return -15 * multiplier;
+    case 'wobble':
+      return -5 * multiplier;
     default:
       return 0;
   }
@@ -578,12 +995,17 @@ function getInitialRotate(effect: PuffPopEffect): number {
 /**
  * Get initial translateX value based on effect
  */
-function getInitialTranslateX(effect: PuffPopEffect): number {
+function getInitialTranslateX(effect: PuffPopEffect, reverse = false): number {
+  const multiplier = reverse ? -1 : 1;
   switch (effect) {
     case 'slideLeft':
-      return 100;
+      return 100 * multiplier;
     case 'slideRight':
-      return -100;
+      return -100 * multiplier;
+    case 'shake':
+      return -10 * multiplier;
+    case 'wobble':
+      return -25 * multiplier;
     default:
       return 0;
   }
@@ -592,14 +1014,15 @@ function getInitialTranslateX(effect: PuffPopEffect): number {
 /**
  * Get initial translateY value based on effect
  */
-function getInitialTranslateY(effect: PuffPopEffect): number {
+function getInitialTranslateY(effect: PuffPopEffect, reverse = false): number {
+  const multiplier = reverse ? -1 : 1;
   switch (effect) {
     case 'slideUp':
-      return 50;
+      return 50 * multiplier;
     case 'slideDown':
-      return -50;
+      return -50 * multiplier;
     case 'bounce':
-      return 30;
+      return 30 * multiplier;
     default:
       return 0;
   }
@@ -721,6 +1144,191 @@ export interface PuffPopGroupProps {
    * Gap between children (uses flexbox gap)
    */
   gap?: number;
+
+  // ============ Custom Initial Values ============
+
+  /**
+   * Custom initial opacity value (0-1) for all children
+   */
+  initialOpacity?: number;
+
+  /**
+   * Custom initial scale value for all children
+   */
+  initialScale?: number;
+
+  /**
+   * Custom initial rotation value in degrees for all children
+   */
+  initialRotate?: number;
+
+  /**
+   * Custom initial translateX value in pixels for all children
+   */
+  initialTranslateX?: number;
+
+  /**
+   * Custom initial translateY value in pixels for all children
+   */
+  initialTranslateY?: number;
+
+  // ============ Reverse Mode ============
+
+  /**
+   * If true, reverses the animation direction for all children
+   * @default false
+   */
+  reverse?: boolean;
+
+  // ============ Animation Intensity ============
+
+  /**
+   * Animation intensity multiplier (0-1) for all children
+   * Controls how far/much elements move during animation
+   * @default 1
+   */
+  intensity?: number;
+
+  // ============ Anchor Point ============
+
+  /**
+   * Anchor point for scale/rotate transformations for all children
+   * @default 'center'
+   */
+  anchorPoint?: PuffPopAnchorPoint;
+
+  // ============ Spring Animation ============
+
+  /**
+   * Use spring physics-based animation for all children
+   * @default false
+   */
+  useSpring?: boolean;
+
+  /**
+   * Spring animation configuration for all children
+   */
+  springConfig?: PuffPopSpringConfig;
+
+  // ============ Exit Animation Settings ============
+
+  /**
+   * Animation effect type when hiding (exit animation) for all children
+   * If not specified, uses the reverse of the enter effect
+   */
+  exitEffect?: PuffPopEffect;
+
+  /**
+   * Animation duration for exit animation in milliseconds for all children
+   * If not specified, uses the same duration as enter animation
+   */
+  exitDuration?: number;
+
+  /**
+   * Easing function for exit animation for all children
+   * If not specified, uses the same easing as enter animation
+   */
+  exitEasing?: PuffPopEasing;
+
+  /**
+   * Delay before exit animation starts in milliseconds
+   * @default 0
+   */
+  exitDelay?: number;
+
+  /**
+   * Delay between each child's exit animation start in milliseconds
+   * If not specified, all children exit simultaneously
+   * @default 0
+   */
+  exitStaggerDelay?: number;
+
+  /**
+   * Direction of exit stagger animation
+   * - 'forward': First to last child
+   * - 'reverse': Last to first child (most natural for exit)
+   * - 'center': From center outward
+   * - 'edges': From edges toward center
+   * @default 'reverse'
+   */
+  exitStaggerDirection?: 'forward' | 'reverse' | 'center' | 'edges';
+}
+
+/**
+ * Props comparison function for PuffPopGroup memoization
+ * Performs shallow comparison of props to prevent unnecessary re-renders
+ */
+function arePuffPopGroupPropsEqual(
+  prevProps: PuffPopGroupProps,
+  nextProps: PuffPopGroupProps
+): boolean {
+  // Compare primitive props
+  if (
+    prevProps.effect !== nextProps.effect ||
+    prevProps.duration !== nextProps.duration ||
+    prevProps.staggerDelay !== nextProps.staggerDelay ||
+    prevProps.initialDelay !== nextProps.initialDelay ||
+    prevProps.easing !== nextProps.easing ||
+    prevProps.skeleton !== nextProps.skeleton ||
+    prevProps.visible !== nextProps.visible ||
+    prevProps.animateOnMount !== nextProps.animateOnMount ||
+    prevProps.respectReduceMotion !== nextProps.respectReduceMotion ||
+    prevProps.testID !== nextProps.testID ||
+    prevProps.staggerDirection !== nextProps.staggerDirection ||
+    prevProps.horizontal !== nextProps.horizontal ||
+    prevProps.gap !== nextProps.gap ||
+    prevProps.reverse !== nextProps.reverse ||
+    prevProps.intensity !== nextProps.intensity ||
+    prevProps.anchorPoint !== nextProps.anchorPoint ||
+    prevProps.useSpring !== nextProps.useSpring ||
+    prevProps.exitEffect !== nextProps.exitEffect ||
+    prevProps.exitDuration !== nextProps.exitDuration ||
+    prevProps.exitEasing !== nextProps.exitEasing ||
+    prevProps.exitDelay !== nextProps.exitDelay ||
+    prevProps.exitStaggerDelay !== nextProps.exitStaggerDelay ||
+    prevProps.exitStaggerDirection !== nextProps.exitStaggerDirection ||
+    prevProps.initialOpacity !== nextProps.initialOpacity ||
+    prevProps.initialScale !== nextProps.initialScale ||
+    prevProps.initialRotate !== nextProps.initialRotate ||
+    prevProps.initialTranslateX !== nextProps.initialTranslateX ||
+    prevProps.initialTranslateY !== nextProps.initialTranslateY
+  ) {
+    return false;
+  }
+
+  // Compare springConfig object (shallow)
+  if (prevProps.springConfig !== nextProps.springConfig) {
+    if (
+      !prevProps.springConfig ||
+      !nextProps.springConfig ||
+      prevProps.springConfig.tension !== nextProps.springConfig.tension ||
+      prevProps.springConfig.friction !== nextProps.springConfig.friction ||
+      prevProps.springConfig.speed !== nextProps.springConfig.speed ||
+      prevProps.springConfig.bounciness !== nextProps.springConfig.bounciness
+    ) {
+      return false;
+    }
+  }
+
+  // Compare callbacks
+  if (
+    prevProps.onAnimationStart !== nextProps.onAnimationStart ||
+    prevProps.onAnimationComplete !== nextProps.onAnimationComplete
+  ) {
+    return false;
+  }
+
+  // Style comparison
+  if (prevProps.style !== nextProps.style) {
+    return false;
+  }
+
+  // Children comparison - if children change, re-render
+  if (prevProps.children !== nextProps.children) {
+    return false;
+  }
+
+  return true;
 }
 
 /**
@@ -735,7 +1343,7 @@ export interface PuffPopGroupProps {
  * </PuffPopGroup>
  * ```
  */
-export function PuffPopGroup({
+function PuffPopGroupComponent({
   children,
   effect = 'scale',
   duration = 400,
@@ -753,6 +1361,28 @@ export function PuffPopGroup({
   staggerDirection = 'forward',
   horizontal = false,
   gap,
+  // Custom initial values
+  initialOpacity,
+  initialScale,
+  initialRotate,
+  initialTranslateX,
+  initialTranslateY,
+  // Reverse mode
+  reverse,
+  // Animation intensity
+  intensity,
+  // Anchor point
+  anchorPoint,
+  // Spring animation
+  useSpring,
+  springConfig,
+  // Exit animation settings
+  exitEffect,
+  exitDuration,
+  exitEasing,
+  exitDelay,
+  exitStaggerDelay = 0,
+  exitStaggerDirection = 'reverse',
 }: PuffPopGroupProps): ReactElement {
   const childArray = Children.toArray(children);
   const childCount = childArray.length;
@@ -789,6 +1419,41 @@ export function PuffPopGroup({
     [childCount, initialDelay, staggerDelay, staggerDirection]
   );
 
+  // Calculate exit delay for each child based on exit stagger direction
+  const getChildExitDelay = useCallback(
+    (index: number): number => {
+      if (exitStaggerDelay === 0) {
+        return exitDelay ?? 0;
+      }
+
+      let delayIndex: number;
+
+      switch (exitStaggerDirection) {
+        case 'forward':
+          delayIndex = index;
+          break;
+        case 'center': {
+          const center = (childCount - 1) / 2;
+          delayIndex = Math.abs(index - center);
+          break;
+        }
+        case 'edges': {
+          const center = (childCount - 1) / 2;
+          delayIndex = center - Math.abs(index - center);
+          break;
+        }
+        case 'reverse':
+        default:
+          // Reverse is default for exit (last in, first out)
+          delayIndex = childCount - 1 - index;
+          break;
+      }
+
+      return (exitDelay ?? 0) + delayIndex * exitStaggerDelay;
+    },
+    [childCount, exitDelay, exitStaggerDelay, exitStaggerDirection]
+  );
+
   // Handle individual child animation complete
   const handleChildComplete = useCallback(() => {
     completedCount.current += 1;
@@ -838,6 +1503,20 @@ export function PuffPopGroup({
           onAnimationComplete={handleChildComplete}
           onAnimationStart={index === 0 ? handleChildStart : undefined}
           respectReduceMotion={respectReduceMotion}
+          initialOpacity={initialOpacity}
+          initialScale={initialScale}
+          initialRotate={initialRotate}
+          initialTranslateX={initialTranslateX}
+          initialTranslateY={initialTranslateY}
+          reverse={reverse}
+          intensity={intensity}
+          anchorPoint={anchorPoint}
+          useSpring={useSpring}
+          springConfig={springConfig}
+          exitEffect={exitEffect}
+          exitDuration={exitDuration}
+          exitEasing={exitEasing}
+          exitDelay={getChildExitDelay(index)}
         >
           {child}
         </PuffPop>
@@ -846,5 +1525,8 @@ export function PuffPopGroup({
   );
 }
 
+// Memoize PuffPopGroup to prevent unnecessary re-renders
+export const PuffPopGroup = memo(PuffPopGroupComponent, arePuffPopGroupPropsEqual);
+
 export default PuffPop;