react-native-puff-pop 1.0.3 → 1.0.5

package/README.md

@@ -102,6 +102,35 @@ By default, `skeleton={true}` reserves space for the component before animation:
 
 ### Staggered Animations
 
+Use `PuffPopGroup` for easy staggered animations:
+
+```tsx
+import { PuffPopGroup } from 'react-native-puff-pop';
+
+// Simple stagger
+<PuffPopGroup staggerDelay={100} effect="scale">
+  <Card title="First" />
+  <Card title="Second" />
+  <Card title="Third" />
+</PuffPopGroup>
+
+// With different directions
+<PuffPopGroup staggerDelay={80} staggerDirection="reverse">
+  <Item />
+  <Item />
+  <Item />
+</PuffPopGroup>
+
+// Horizontal layout with gap
+<PuffPopGroup horizontal gap={12} effect="slideUp">
+  <Avatar />
+  <Avatar />
+  <Avatar />
+</PuffPopGroup>
+```
+
+Or use manual delays with `PuffPop`:
+
 ```tsx
 <View>
   <PuffPop delay={0}>
@@ -164,10 +193,35 @@ function App() {
 | `skeleton` | `boolean` | `true` | Reserve space before animation |
 | `visible` | `boolean` | `true` | Control visibility |
 | `animateOnMount` | `boolean` | `true` | Animate when component mounts |
+| `onAnimationStart` | `() => void` | - | Callback when animation starts |
 | `onAnimationComplete` | `() => void` | - | Callback when animation completes |
 | `style` | `ViewStyle` | - | Custom container style |
 | `loop` | `boolean \| number` | `false` | Loop animation (true=infinite, number=times) |
 | `loopDelay` | `number` | `0` | Delay between loop iterations in ms |
+| `respectReduceMotion` | `boolean` | `true` | Respect system reduce motion setting |
+| `testID` | `string` | - | Test ID for testing purposes |
+
+### PuffPopGroup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Children to animate with stagger effect |
+| `effect` | `PuffPopEffect` | `'scale'` | Animation effect for all children |
+| `duration` | `number` | `400` | Animation duration for each child in ms |
+| `staggerDelay` | `number` | `100` | Delay between each child's animation in ms |
+| `initialDelay` | `number` | `0` | Delay before the first child animates in ms |
+| `easing` | `PuffPopEasing` | `'easeOut'` | Easing function for all children |
+| `skeleton` | `boolean` | `true` | Reserve space before animation |
+| `visible` | `boolean` | `true` | Control visibility of all children |
+| `animateOnMount` | `boolean` | `true` | Animate when component mounts |
+| `onAnimationStart` | `() => void` | - | Callback when first child starts animating |
+| `onAnimationComplete` | `() => void` | - | Callback when all children complete |
+| `style` | `ViewStyle` | - | Custom container style |
+| `staggerDirection` | `'forward' \| 'reverse' \| 'center' \| 'edges'` | `'forward'` | Direction of stagger animation |
+| `horizontal` | `boolean` | `false` | Render children in horizontal layout |
+| `gap` | `number` | - | Gap between children |
+| `respectReduceMotion` | `boolean` | `true` | Respect system reduce motion setting |
+| `testID` | `string` | - | Test ID for testing purposes |
 
 ### Animation Effects (`PuffPopEffect`)
 
@@ -204,6 +258,22 @@ The component reserves its full space immediately, and only the visual appearanc
 ### `skeleton={false}`
 The component's height starts at 0 and expands during animation, pushing other content below it. This creates a more dynamic entrance effect.
 
+## Accessibility
+
+PuffPop respects the system's "Reduce Motion" accessibility setting by default. When users have enabled reduce motion in their device settings, animations will be instant (0 duration) to avoid discomfort.
+
+```tsx
+// Respect reduce motion setting (default)
+<PuffPop respectReduceMotion={true}>
+  <YourComponent />
+</PuffPop>
+
+// Ignore reduce motion setting (always animate)
+<PuffPop respectReduceMotion={false}>
+  <YourComponent />
+</PuffPop>
+```
+
 ## License
 
 MIT

package/lib/module/index.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useRef, useState, useCallback, useMemo, } from 'react';
-import { View, Animated, StyleSheet, Easing, } from 'react-native';
+import { useEffect, useRef, useState, useCallback, useMemo, Children, } from 'react';
+import { View, Animated, StyleSheet, Easing, AccessibilityInfo, } from 'react-native';
 /**
  * Get easing function based on type
  */
@@ -25,7 +25,7 @@ function getEasing(type) {
 /**
  * PuffPop - Animate children with beautiful entrance effects
  */
-export function PuffPop({ children, effect = 'scale', duration = 400, delay = 0, easing = 'easeOut', skeleton = true, visible = true, onAnimationComplete, style, animateOnMount = true, loop = false, loopDelay = 0, }) {
+export function PuffPop({ children, effect = 'scale', duration = 400, delay = 0, easing = 'easeOut', skeleton = true, visible = true, onAnimationComplete, onAnimationStart, style, animateOnMount = true, loop = false, loopDelay = 0, respectReduceMotion = true, testID, }) {
     // Animation values
     const opacity = useRef(new Animated.Value(animateOnMount ? 0 : 1)).current;
     const scale = useRef(new Animated.Value(animateOnMount ? getInitialScale(effect) : 1)).current;
@@ -38,6 +38,23 @@ export function PuffPop({ children, effect = 'scale', duration = 400, delay = 0,
     const hasAnimated = useRef(false);
     const loopAnimationRef = useRef(null);
     const loopTimeoutRef = useRef(null);
+    // Reduce motion accessibility support
+    const [isReduceMotionEnabled, setIsReduceMotionEnabled] = useState(false);
+    useEffect(() => {
+        if (!respectReduceMotion)
+            return;
+        const checkReduceMotion = async () => {
+            const reduceMotion = await AccessibilityInfo.isReduceMotionEnabled();
+            setIsReduceMotionEnabled(reduceMotion);
+        };
+        checkReduceMotion();
+        const subscription = AccessibilityInfo.addEventListener('reduceMotionChanged', setIsReduceMotionEnabled);
+        return () => {
+            subscription.remove();
+        };
+    }, [respectReduceMotion]);
+    // Effective duration (0 if reduce motion is enabled)
+    const effectiveDuration = respectReduceMotion && isReduceMotionEnabled ? 0 : duration;
     // Memoize effect type checks to avoid repeated includes() calls
     const effectFlags = useMemo(() => ({
         hasScale: ['scale', 'bounce', 'zoom', 'rotateScale', 'flip'].includes(effect),
@@ -65,12 +82,16 @@ export function PuffPop({ children, effect = 'scale', duration = 400, delay = 0,
     }, [skeleton, measuredHeight]);
     // Animate function
     const animate = useCallback((toVisible) => {
+        // Call onAnimationStart callback
+        if (toVisible && onAnimationStart) {
+            onAnimationStart();
+        }
         const easingFn = getEasing(easing);
         // 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,
+            duration: effectiveDuration,
             easing: easingFn,
             useNativeDriver: useNative,
         };
@@ -118,7 +139,7 @@ export function PuffPop({ children, effect = 'scale', duration = 400, delay = 0,
             const targetHeight = toVisible ? measuredHeight : 0;
             animations.push(Animated.timing(animatedHeight, {
                 toValue: targetHeight,
-                duration,
+                duration: effectiveDuration,
                 easing: easingFn,
                 useNativeDriver: false,
             }));
@@ -152,11 +173,19 @@ export function PuffPop({ children, effect = 'scale', duration = 400, delay = 0,
             // Stop any existing loop animation
             if (loopAnimationRef.current) {
                 loopAnimationRef.current.stop();
+                loopAnimationRef.current = null;
+            }
+            // Clear any existing timeout
+            if (loopTimeoutRef.current) {
+                clearTimeout(loopTimeoutRef.current);
+                loopTimeoutRef.current = null;
             }
             const loopCount = typeof loop === 'number' ? loop : -1;
             let currentIteration = 0;
             const runLoop = () => {
                 resetValues();
+                // Store the current animation reference so it can be stopped
+                loopAnimationRef.current = animation;
                 animation.start(({ finished }) => {
                     if (finished) {
                         currentIteration++;
@@ -173,13 +202,17 @@ export function PuffPop({ children, effect = 'scale', duration = 400, delay = 0,
                                 runLoop();
                             }
                         }
-                        else if (onAnimationComplete) {
-                            onAnimationComplete();
+                        else {
+                            // Loop finished, clear reference
+                            loopAnimationRef.current = null;
+                            if (onAnimationComplete) {
+                                onAnimationComplete();
+                            }
                         }
                     }
                 });
             };
-            // Store reference and start
+            // Start the loop
             runLoop();
         }
         else {
@@ -196,12 +229,13 @@ export function PuffPop({ children, effect = 'scale', duration = 400, delay = 0,
         }
     }, [
         delay,
-        duration,
+        effectiveDuration,
         easing,
         effect,
         effectFlags,
         measuredHeight,
         onAnimationComplete,
+        onAnimationStart,
         opacity,
         rotate,
         scale,
@@ -277,7 +311,7 @@ export function PuffPop({ children, effect = 'scale', duration = 400, delay = 0,
     if (!skeleton && measuredHeight === null) {
         return (_jsx(View, { style: styles.measureContainer, onLayout: onLayout, children: _jsx(View, { style: styles.hidden, children: children }) }));
     }
-    return (_jsx(Animated.View, { style: [styles.container, style, containerAnimatedStyle], children: _jsx(Animated.View, { style: animatedStyle, children: children }) }));
+    return (_jsx(Animated.View, { style: [styles.container, style, containerAnimatedStyle], testID: testID, children: _jsx(Animated.View, { style: animatedStyle, children: children }) }));
 }
 /**
  * Get initial scale value based on effect
@@ -350,5 +384,79 @@ const styles = StyleSheet.create({
     hidden: {
         opacity: 0,
     },
+    groupContainer: {},
 });
+/**
+ * PuffPopGroup - Animate multiple children with staggered entrance effects
+ *
+ * @example
+ * ```tsx
+ * <PuffPopGroup staggerDelay={100} effect="scale">
+ *   <Card title="First" />
+ *   <Card title="Second" />
+ *   <Card title="Third" />
+ * </PuffPopGroup>
+ * ```
+ */
+export function PuffPopGroup({ children, effect = 'scale', duration = 400, staggerDelay = 100, initialDelay = 0, easing = 'easeOut', skeleton = true, visible = true, animateOnMount = true, onAnimationComplete, onAnimationStart, style, respectReduceMotion = true, testID, staggerDirection = 'forward', horizontal = false, gap, }) {
+    const childArray = Children.toArray(children);
+    const childCount = childArray.length;
+    const completedCount = useRef(0);
+    const hasCalledStart = useRef(false);
+    // Calculate delay for each child based on stagger direction
+    const getChildDelay = useCallback((index) => {
+        let delayIndex;
+        switch (staggerDirection) {
+            case 'reverse':
+                delayIndex = childCount - 1 - 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 'forward':
+            default:
+                delayIndex = index;
+                break;
+        }
+        return initialDelay + delayIndex * staggerDelay;
+    }, [childCount, initialDelay, staggerDelay, staggerDirection]);
+    // Handle individual child animation complete
+    const handleChildComplete = useCallback(() => {
+        completedCount.current += 1;
+        if (completedCount.current >= childCount && onAnimationComplete) {
+            onAnimationComplete();
+        }
+    }, [childCount, onAnimationComplete]);
+    // Handle first child animation start
+    const handleChildStart = useCallback(() => {
+        if (!hasCalledStart.current && onAnimationStart) {
+            hasCalledStart.current = true;
+            onAnimationStart();
+        }
+    }, [onAnimationStart]);
+    // Reset counters when visibility changes
+    useEffect(() => {
+        if (visible) {
+            completedCount.current = 0;
+            hasCalledStart.current = false;
+        }
+    }, [visible]);
+    const containerStyle = useMemo(() => {
+        const baseStyle = {
+            flexDirection: horizontal ? 'row' : 'column',
+        };
+        if (gap !== undefined) {
+            baseStyle.gap = gap;
+        }
+        return baseStyle;
+    }, [horizontal, gap]);
+    return (_jsx(View, { style: [styles.groupContainer, containerStyle, style], testID: testID, children: childArray.map((child, index) => (_jsx(PuffPop, { effect: effect, duration: duration, delay: getChildDelay(index), easing: easing, skeleton: skeleton, visible: visible, animateOnMount: animateOnMount, onAnimationComplete: handleChildComplete, onAnimationStart: index === 0 ? handleChildStart : undefined, respectReduceMotion: respectReduceMotion, children: child }, index))) }));
+}
 export default PuffPop;

package/lib/typescript/src/index.d.ts

@@ -69,9 +69,124 @@ export interface PuffPopProps {
      * @default 0
      */
     loopDelay?: number;
+    /**
+     * Callback when animation starts
+     */
+    onAnimationStart?: () => void;
+    /**
+     * Respect system reduce motion accessibility setting
+     * When true and reduce motion is enabled, animations will be instant
+     * @default true
+     */
+    respectReduceMotion?: boolean;
+    /**
+     * Test ID for testing purposes
+     */
+    testID?: string;
 }
 /**
  * PuffPop - Animate children with beautiful entrance effects
  */
-export declare function PuffPop({ children, effect, duration, delay, easing, skeleton, visible, onAnimationComplete, style, animateOnMount, loop, loopDelay, }: PuffPopProps): ReactElement;
+export declare function PuffPop({ children, effect, duration, delay, easing, skeleton, visible, onAnimationComplete, onAnimationStart, style, animateOnMount, loop, loopDelay, respectReduceMotion, testID, }: PuffPopProps): ReactElement;
+/**
+ * Props for PuffPopGroup component
+ */
+export interface PuffPopGroupProps {
+    /**
+     * Children to animate with stagger effect
+     */
+    children: ReactNode;
+    /**
+     * Animation effect type applied to all children
+     * @default 'scale'
+     */
+    effect?: PuffPopEffect;
+    /**
+     * Base animation duration in milliseconds for each child
+     * @default 400
+     */
+    duration?: number;
+    /**
+     * Delay between each child's animation start in milliseconds
+     * @default 100
+     */
+    staggerDelay?: number;
+    /**
+     * Initial delay before the first child animates in milliseconds
+     * @default 0
+     */
+    initialDelay?: number;
+    /**
+     * Easing function for all children
+     * @default 'easeOut'
+     */
+    easing?: PuffPopEasing;
+    /**
+     * If true, reserves space for children before animation
+     * @default true
+     */
+    skeleton?: boolean;
+    /**
+     * Whether children are visible
+     * @default true
+     */
+    visible?: boolean;
+    /**
+     * Whether to animate on mount
+     * @default true
+     */
+    animateOnMount?: boolean;
+    /**
+     * Callback when all children animations complete
+     */
+    onAnimationComplete?: () => void;
+    /**
+     * Callback when the first child animation starts
+     */
+    onAnimationStart?: () => void;
+    /**
+     * Custom style for the group container
+     */
+    style?: StyleProp<ViewStyle>;
+    /**
+     * Respect system reduce motion accessibility setting
+     * @default true
+     */
+    respectReduceMotion?: boolean;
+    /**
+     * Test ID for testing purposes
+     */
+    testID?: string;
+    /**
+     * Direction of stagger animation
+     * - 'forward': First to last child
+     * - 'reverse': Last to first child
+     * - 'center': From center outward
+     * - 'edges': From edges toward center
+     * @default 'forward'
+     */
+    staggerDirection?: 'forward' | 'reverse' | 'center' | 'edges';
+    /**
+     * If true, children are rendered in a row (horizontal layout)
+     * @default false
+     */
+    horizontal?: boolean;
+    /**
+     * Gap between children (uses flexbox gap)
+     */
+    gap?: number;
+}
+/**
+ * PuffPopGroup - Animate multiple children with staggered entrance effects
+ *
+ * @example
+ * ```tsx
+ * <PuffPopGroup staggerDelay={100} effect="scale">
+ *   <Card title="First" />
+ *   <Card title="Second" />
+ *   <Card title="Third" />
+ * </PuffPopGroup>
+ * ```
+ */
+export declare function PuffPopGroup({ children, effect, duration, staggerDelay, initialDelay, easing, skeleton, visible, animateOnMount, onAnimationComplete, onAnimationStart, style, respectReduceMotion, testID, staggerDirection, horizontal, gap, }: PuffPopGroupProps): ReactElement;
 export default PuffPop;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-puff-pop",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "A React Native animation library for revealing children components with beautiful puff and pop effects",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/index.tsx

@@ -4,6 +4,7 @@ import {
   useState,
   useCallback,
   useMemo,
+  Children,
   type ReactNode,
   type ReactElement,
 } from 'react';
@@ -12,6 +13,7 @@ import {
   Animated,
   StyleSheet,
   Easing,
+  AccessibilityInfo,
   type LayoutChangeEvent,
   type StyleProp,
   type ViewStyle,
@@ -116,6 +118,23 @@ export interface PuffPopProps {
    * @default 0
    */
   loopDelay?: number;
+
+  /**
+   * Callback when animation starts
+   */
+  onAnimationStart?: () => void;
+
+  /**
+   * Respect system reduce motion accessibility setting
+   * When true and reduce motion is enabled, animations will be instant
+   * @default true
+   */
+  respectReduceMotion?: boolean;
+
+  /**
+   * Test ID for testing purposes
+   */
+  testID?: string;
 }
 
 /**
@@ -152,10 +171,13 @@ export function PuffPop({
   skeleton = true,
   visible = true,
   onAnimationComplete,
+  onAnimationStart,
   style,
   animateOnMount = true,
   loop = false,
   loopDelay = 0,
+  respectReduceMotion = true,
+  testID,
 }: PuffPopProps): ReactElement {
   // Animation values
   const opacity = useRef(new Animated.Value(animateOnMount ? 0 : 1)).current;
@@ -171,6 +193,32 @@ export function PuffPop({
   const loopAnimationRef = useRef<Animated.CompositeAnimation | null>(null);
   const loopTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
+  // Reduce motion accessibility support
+  const [isReduceMotionEnabled, setIsReduceMotionEnabled] = useState(false);
+
+  useEffect(() => {
+    if (!respectReduceMotion) return;
+
+    const checkReduceMotion = async () => {
+      const reduceMotion = await AccessibilityInfo.isReduceMotionEnabled();
+      setIsReduceMotionEnabled(reduceMotion);
+    };
+
+    checkReduceMotion();
+
+    const subscription = AccessibilityInfo.addEventListener(
+      'reduceMotionChanged',
+      setIsReduceMotionEnabled
+    );
+
+    return () => {
+      subscription.remove();
+    };
+  }, [respectReduceMotion]);
+
+  // Effective duration (0 if reduce motion is enabled)
+  const effectiveDuration = respectReduceMotion && isReduceMotionEnabled ? 0 : duration;
+
   // Memoize effect type checks to avoid repeated includes() calls
   const effectFlags = useMemo(() => ({
     hasScale: ['scale', 'bounce', 'zoom', 'rotateScale', 'flip'].includes(effect),
@@ -208,12 +256,17 @@ export function PuffPop({
   // Animate function
   const animate = useCallback(
     (toVisible: boolean) => {
+      // Call onAnimationStart callback
+      if (toVisible && onAnimationStart) {
+        onAnimationStart();
+      }
+
       const easingFn = getEasing(easing);
       // 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,
+        duration: effectiveDuration,
         easing: easingFn,
         useNativeDriver: useNative,
       };
@@ -279,7 +332,7 @@ export function PuffPop({
         animations.push(
           Animated.timing(animatedHeight, {
             toValue: targetHeight,
-            duration,
+            duration: effectiveDuration,
             easing: easingFn,
             useNativeDriver: false,
           })
@@ -318,6 +371,12 @@ export function PuffPop({
         // Stop any existing loop animation
         if (loopAnimationRef.current) {
           loopAnimationRef.current.stop();
+          loopAnimationRef.current = null;
+        }
+        // Clear any existing timeout
+        if (loopTimeoutRef.current) {
+          clearTimeout(loopTimeoutRef.current);
+          loopTimeoutRef.current = null;
         }
 
         const loopCount = typeof loop === 'number' ? loop : -1;
@@ -325,6 +384,8 @@ export function PuffPop({
 
         const runLoop = () => {
           resetValues();
+          // Store the current animation reference so it can be stopped
+          loopAnimationRef.current = animation;
           animation.start(({ finished }) => {
             if (finished) {
               currentIteration++;
@@ -339,14 +400,18 @@ export function PuffPop({
                 } else {
                   runLoop();
                 }
-              } else if (onAnimationComplete) {
-                onAnimationComplete();
+              } else {
+                // Loop finished, clear reference
+                loopAnimationRef.current = null;
+                if (onAnimationComplete) {
+                  onAnimationComplete();
+                }
               }
             }
           });
         };
 
-        // Store reference and start
+        // Start the loop
         runLoop();
       } else {
         // Stop any existing loop animation
@@ -364,12 +429,13 @@ export function PuffPop({
     },
     [
       delay,
-      duration,
+      effectiveDuration,
       easing,
       effect,
       effectFlags,
       measuredHeight,
       onAnimationComplete,
+      onAnimationStart,
       opacity,
       rotate,
       scale,
@@ -465,7 +531,10 @@ export function PuffPop({
   }
 
   return (
-    <Animated.View style={[styles.container, style, containerAnimatedStyle]}>
+    <Animated.View 
+      style={[styles.container, style, containerAnimatedStyle]}
+      testID={testID}
+    >
       <Animated.View style={animatedStyle}>{children}</Animated.View>
     </Animated.View>
   );
@@ -546,7 +615,236 @@ const styles = StyleSheet.create({
   hidden: {
     opacity: 0,
   },
+  groupContainer: {},
 });
 
+/**
+ * Props for PuffPopGroup component
+ */
+export interface PuffPopGroupProps {
+  /**
+   * Children to animate with stagger effect
+   */
+  children: ReactNode;
+
+  /**
+   * Animation effect type applied to all children
+   * @default 'scale'
+   */
+  effect?: PuffPopEffect;
+
+  /**
+   * Base animation duration in milliseconds for each child
+   * @default 400
+   */
+  duration?: number;
+
+  /**
+   * Delay between each child's animation start in milliseconds
+   * @default 100
+   */
+  staggerDelay?: number;
+
+  /**
+   * Initial delay before the first child animates in milliseconds
+   * @default 0
+   */
+  initialDelay?: number;
+
+  /**
+   * Easing function for all children
+   * @default 'easeOut'
+   */
+  easing?: PuffPopEasing;
+
+  /**
+   * If true, reserves space for children before animation
+   * @default true
+   */
+  skeleton?: boolean;
+
+  /**
+   * Whether children are visible
+   * @default true
+   */
+  visible?: boolean;
+
+  /**
+   * Whether to animate on mount
+   * @default true
+   */
+  animateOnMount?: boolean;
+
+  /**
+   * Callback when all children animations complete
+   */
+  onAnimationComplete?: () => void;
+
+  /**
+   * Callback when the first child animation starts
+   */
+  onAnimationStart?: () => void;
+
+  /**
+   * Custom style for the group container
+   */
+  style?: StyleProp<ViewStyle>;
+
+  /**
+   * Respect system reduce motion accessibility setting
+   * @default true
+   */
+  respectReduceMotion?: boolean;
+
+  /**
+   * Test ID for testing purposes
+   */
+  testID?: string;
+
+  /**
+   * Direction of stagger animation
+   * - 'forward': First to last child
+   * - 'reverse': Last to first child
+   * - 'center': From center outward
+   * - 'edges': From edges toward center
+   * @default 'forward'
+   */
+  staggerDirection?: 'forward' | 'reverse' | 'center' | 'edges';
+
+  /**
+   * If true, children are rendered in a row (horizontal layout)
+   * @default false
+   */
+  horizontal?: boolean;
+
+  /**
+   * Gap between children (uses flexbox gap)
+   */
+  gap?: number;
+}
+
+/**
+ * PuffPopGroup - Animate multiple children with staggered entrance effects
+ * 
+ * @example
+ * ```tsx
+ * <PuffPopGroup staggerDelay={100} effect="scale">
+ *   <Card title="First" />
+ *   <Card title="Second" />
+ *   <Card title="Third" />
+ * </PuffPopGroup>
+ * ```
+ */
+export function PuffPopGroup({
+  children,
+  effect = 'scale',
+  duration = 400,
+  staggerDelay = 100,
+  initialDelay = 0,
+  easing = 'easeOut',
+  skeleton = true,
+  visible = true,
+  animateOnMount = true,
+  onAnimationComplete,
+  onAnimationStart,
+  style,
+  respectReduceMotion = true,
+  testID,
+  staggerDirection = 'forward',
+  horizontal = false,
+  gap,
+}: PuffPopGroupProps): ReactElement {
+  const childArray = Children.toArray(children);
+  const childCount = childArray.length;
+  const completedCount = useRef(0);
+  const hasCalledStart = useRef(false);
+
+  // Calculate delay for each child based on stagger direction
+  const getChildDelay = useCallback(
+    (index: number): number => {
+      let delayIndex: number;
+
+      switch (staggerDirection) {
+        case 'reverse':
+          delayIndex = childCount - 1 - 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 'forward':
+        default:
+          delayIndex = index;
+          break;
+      }
+
+      return initialDelay + delayIndex * staggerDelay;
+    },
+    [childCount, initialDelay, staggerDelay, staggerDirection]
+  );
+
+  // Handle individual child animation complete
+  const handleChildComplete = useCallback(() => {
+    completedCount.current += 1;
+    if (completedCount.current >= childCount && onAnimationComplete) {
+      onAnimationComplete();
+    }
+  }, [childCount, onAnimationComplete]);
+
+  // Handle first child animation start
+  const handleChildStart = useCallback(() => {
+    if (!hasCalledStart.current && onAnimationStart) {
+      hasCalledStart.current = true;
+      onAnimationStart();
+    }
+  }, [onAnimationStart]);
+
+  // Reset counters when visibility changes
+  useEffect(() => {
+    if (visible) {
+      completedCount.current = 0;
+      hasCalledStart.current = false;
+    }
+  }, [visible]);
+
+  const containerStyle = useMemo(() => {
+    const baseStyle: ViewStyle = {
+      flexDirection: horizontal ? 'row' : 'column',
+    };
+    if (gap !== undefined) {
+      baseStyle.gap = gap;
+    }
+    return baseStyle;
+  }, [horizontal, gap]);
+
+  return (
+    <View style={[styles.groupContainer, containerStyle, style]} testID={testID}>
+      {childArray.map((child, index) => (
+        <PuffPop
+          key={index}
+          effect={effect}
+          duration={duration}
+          delay={getChildDelay(index)}
+          easing={easing}
+          skeleton={skeleton}
+          visible={visible}
+          animateOnMount={animateOnMount}
+          onAnimationComplete={handleChildComplete}
+          onAnimationStart={index === 0 ? handleChildStart : undefined}
+          respectReduceMotion={respectReduceMotion}
+        >
+          {child}
+        </PuffPop>
+      ))}
+    </View>
+  );
+}
+
 export default PuffPop;