festive-effects 1.0.3 → 1.1.1

package/README.md

@@ -40,9 +40,9 @@ function App() {
 
 ## 🎨 Available Festivals
 
-| Festival | Prop Value | Effect |
-|----------|------------|--------|
-| 🎄 Christmas | `christmas` | Falling snowflakes |
+| Festival | Prop Value | Effect | Particles |
+|----------|------------|--------|----------|
+| 🎄 Christmas | `christmas` | Falling snowflakes | snowflake, gift, star |
 | 🎆 New Year | `newyear` | Fireworks & confetti |
 | 💝 Valentine | `valentine` | Floating hearts |
 | 🐰 Easter | `easter` | Eggs & flowers |
@@ -65,6 +65,7 @@ function App() {
 | `zIndex` | `number` | `9999` | CSS z-index of overlay |
 | `respectReducedMotion` | `boolean` | `true` | Honor user's motion preferences |
 | `colors` | `string[]` | festival default | Custom color palette |
+| `particleTypes` | `ParticleType[]` | festival default | Override which particles to show |
 
 ## 📖 Examples
 
@@ -101,6 +102,22 @@ function App() {
 />
 ```
 
+### Filter Particle Types (New in 1.1.0)
+
+```tsx
+// Only snowflakes
+<FestiveEffects 
+  festival="christmas" 
+  particleTypes={['snowflake']} 
+/>
+
+// Snowflakes + gifts (no stars)
+<FestiveEffects 
+  festival="christmas" 
+  particleTypes={['snowflake', 'gift']} 
+/>
+```
+
 ### Conditional Rendering
 
 ```tsx

package/dist/animations/compositeAnimations.d.ts

@@ -0,0 +1,50 @@
+import type { Variants, Transition } from 'framer-motion';
+import type { AnimationCustomData } from './index';
+/**
+ * Burst animation variants
+ * Particles burst from click/center then fade with gravity
+ * Combines explosive outward motion with falling behavior
+ */
+export declare const burstVariants: Variants;
+/**
+ * Get transition for burst animation
+ */
+export declare function getBurstTransition(custom: AnimationCustomData): Transition;
+/**
+ * Spiral animation variants
+ * Particles spiral outward/inward from center
+ * Creates a hypnotic vortex effect
+ */
+export declare const spiralVariants: Variants;
+/**
+ * Get transition for spiral animation
+ */
+export declare function getSpiralTransition(custom: AnimationCustomData): Transition;
+/**
+ * Wave animation variants
+ * Particles move in wave patterns (sine/cosine motion)
+ * Creates flowing, organic movement
+ */
+export declare const waveVariants: Variants;
+/**
+ * Get transition for wave animation
+ */
+export declare function getWaveTransition(custom: AnimationCustomData): Transition;
+/**
+ * Twinkle animation variants
+ * Random opacity flickering for stars/sparks
+ * Creates a shimmering, magical effect
+ */
+export declare const twinkleVariants: Variants;
+/**
+ * Get transition for twinkle animation
+ */
+export declare function getTwinkleTransition(custom: AnimationCustomData): Transition;
+/**
+ * Get animation props for composite animation types
+ */
+export declare function getCompositeAnimationProps(animationType: 'burst' | 'spiral' | 'wave' | 'twinkle', custom: AnimationCustomData): {
+    initial: Record<string, unknown>;
+    animate: Record<string, unknown>;
+    transition: Transition;
+};

package/dist/components/FestiveEffects.d.ts

@@ -1,19 +1,3 @@
 import React from 'react';
 import type { FestiveEffectsProps } from '../types';
-/**
- * FestiveEffects - Main component for rendering festival-themed visual effects
- *
- * Renders a full-screen overlay with animated particles for various festivals.
- * Uses Framer Motion for smooth, GPU-accelerated animations.
- *
- * Features:
- * - Automatic cleanup of timeouts and event listeners on unmount
- * - Pauses animations when browser tab is not visible (performance optimization)
- * - Respects user's reduced motion preferences
- *
- * @example
- * ```tsx
- * <FestiveEffects festival="christmas" intensity="medium" />
- * ```
- */
 export declare const FestiveEffects: React.FC<FestiveEffectsProps>;

package/dist/effects/index.d.ts

@@ -1,3 +1,4 @@
+import type { FestivalType, ParticleData, Viewport } from '../types';
 export { ChristmasEffect, generateChristmasParticles, CHRISTMAS_CONFIG } from './ChristmasEffect';
 export { NewYearEffect, generateNewYearParticles, NEWYEAR_CONFIG } from './NewYearEffect';
 export { ValentineEffect, generateValentineParticles, VALENTINE_CONFIG } from './ValentineEffect';
@@ -10,6 +11,5 @@ export { HoliEffect, generateHoliParticles, HOLI_CONFIG } from './HoliEffect';
 export { EidEffect, generateEidParticles, EID_CONFIG } from './EidEffect';
 export { StPatricksEffect, generateStPatricksParticles, STPATRICKS_CONFIG } from './StPatricksEffect';
 export { IndependenceEffect, generateIndependenceParticles, INDEPENDENCE_CONFIG } from './IndependenceEffect';
-import type { FestivalType, ParticleData, Viewport } from '../types';
 export type EffectGenerator = (count: number, viewport: Viewport, colors?: string[]) => ParticleData[];
 export declare const EFFECT_GENERATORS: Record<FestivalType, EffectGenerator>;

package/dist/index.d.ts

@@ -13,6 +13,14 @@ declare const FESTIVAL_TYPES: FestivalType[];
  * Intensity levels for particle effects
  */
 type IntensityLevel = 'low' | 'medium' | 'high';
+/**
+ * Interactive modes for particle effects
+ */
+type InteractiveMode = 'onHover' | 'onClick' | 'follow' | 'repel';
+/**
+ * Particle layer for depth perception (parallax effect)
+ */
+type ParticleLayer = 'far' | 'mid' | 'near';
 /**
  * Props for the main FestiveEffects component
  */
@@ -29,6 +37,34 @@ interface FestiveEffectsProps {
     respectReducedMotion?: boolean;
     /** Custom colors to override default festival colors */
     colors?: string[];
+    /** Override which particle types to show (e.g., ['snowflake', 'gift']) */
+    particleTypes?: ParticleType[];
+    /** Interactive mode for particle behavior */
+    interactiveMode?: InteractiveMode;
+    /** Particle density multiplier (overrides intensity) */
+    particleDensity?: number;
+    /** Delay before effect starts (ms) */
+    startDelay?: number;
+    /** Fade in duration (ms) */
+    fadeIn?: number;
+    /** Fade out duration (ms) */
+    fadeOut?: number;
+    /** Origin point for particles */
+    origin?: {
+        x: number;
+        y: number;
+    } | 'center' | 'mouse';
+    /** Bounding box to contain particles */
+    boundingBox?: {
+        top: number;
+        left: number;
+        width: number;
+        height: number;
+    };
+    /** Callback when duration ends */
+    onComplete?: () => void;
+    /** Callback when particles spawn */
+    onParticleSpawn?: (count: number) => void;
 }
 /**
  * Settings for each intensity level
@@ -55,11 +91,11 @@ interface PhysicsConfig {
 /**
  * All particle types available for effects
  */
-type ParticleType = 'snowflake' | 'firework' | 'confetti' | 'spark' | 'heart' | 'egg' | 'flower' | 'bat' | 'pumpkin' | 'spider' | 'leaf' | 'diya' | 'rangoli' | 'lantern' | 'dragon' | 'color-splash' | 'moon' | 'star' | 'shamrock' | 'rainbow';
+type ParticleType = 'snowflake' | 'firework' | 'confetti' | 'spark' | 'heart' | 'egg' | 'flower' | 'bat' | 'pumpkin' | 'spider' | 'leaf' | 'diya' | 'rangoli' | 'lantern' | 'dragon' | 'color-splash' | 'moon' | 'star' | 'shamrock' | 'rainbow' | 'cracker' | 'ribbon' | 'gift' | 'candle';
 /**
  * Animation types for particle effects
  */
-type AnimationType = 'fall' | 'rise' | 'explode' | 'float' | 'scatter';
+type AnimationType = 'fall' | 'rise' | 'explode' | 'float' | 'scatter' | 'burst' | 'spiral' | 'wave' | 'twinkle';
 /**
  * Configuration for a festival effect
  */
@@ -104,6 +140,10 @@ interface ParticleData {
     duration: number;
     /** Additional custom properties for animation */
     custom: Record<string, unknown>;
+    /** Particle layer for depth perception */
+    layer?: ParticleLayer;
+    /** Whether glow effect is enabled */
+    hasGlow?: boolean;
 }
 /**
  * Framer Motion animation configuration
@@ -144,24 +184,12 @@ interface ParticleProps {
     type: ParticleType;
     /** Animation configuration */
     animationConfig: AnimationConfig;
+    /** Particle layer */
+    layer?: ParticleLayer;
+    /** Glow effect enabled */
+    hasGlow?: boolean;
 }
 
-/**
- * FestiveEffects - Main component for rendering festival-themed visual effects
- *
- * Renders a full-screen overlay with animated particles for various festivals.
- * Uses Framer Motion for smooth, GPU-accelerated animations.
- *
- * Features:
- * - Automatic cleanup of timeouts and event listeners on unmount
- * - Pauses animations when browser tab is not visible (performance optimization)
- * - Respects user's reduced motion preferences
- *
- * @example
- * ```tsx
- * <FestiveEffects festival="christmas" intensity="medium" />
- * ```
- */
 declare const FestiveEffects: React.FC<FestiveEffectsProps>;
 
 /**
@@ -183,7 +211,7 @@ declare function getParticleCount(baseCount: number, intensity?: IntensityLevel)
 declare const FESTIVAL_CONFIGS: Record<FestivalType, FestivalConfig>;
 
 /**
- * SVG definitions for all 18 particle types
+ * SVG definitions for all 22 particle types
  * Each SVG is designed to work with currentColor for dynamic coloring
  */
 declare const PARTICLE_SVGS: Record<ParticleType, string>;