festive-effects 1.0.0

package/README.md

@@ -0,0 +1,163 @@
+# 🎉 Festive Effects
+
+Beautiful, performant festival animations for React. Powered by Framer Motion.
+
+[![npm version](https://img.shields.io/npm/v/festive-effects.svg)](https://www.npmjs.com/package/festive-effects)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/festive-effects)](https://bundlephobia.com/package/festive-effects)
+[![license](https://img.shields.io/npm/l/festive-effects.svg)](https://github.com/your-username/festive-effects/blob/main/LICENSE)
+
+## ✨ Features
+
+- 🎄 **12 Festival Effects** - Christmas, New Year, Valentine, Easter, Halloween, Thanksgiving, Diwali, Chinese New Year, Holi, Eid, St. Patrick's, Independence Day
+- ⚡ **60fps Performance** - GPU-accelerated animations via Framer Motion
+- 📦 **Lightweight** - Tree-shakeable, minimal bundle impact
+- ♿ **Accessible** - Respects `prefers-reduced-motion`
+- 🔧 **Customizable** - Intensity, duration, colors & more
+- 💪 **TypeScript** - Full type safety out of the box
+
+## 📦 Installation
+
+```bash
+npm install festive-effects framer-motion
+# or
+yarn add festive-effects framer-motion
+# or
+pnpm add festive-effects framer-motion
+```
+
+## 🚀 Quick Start
+
+```tsx
+import { FestiveEffects } from 'festive-effects';
+
+function App() {
+  return (
+    <div>
+      <h1>Happy Holidays!</h1>
+      <FestiveEffects festival="christmas" />
+    </div>
+  );
+}
+```
+
+## 🎨 Available Festivals
+
+| Festival | Prop Value | Effect |
+|----------|------------|--------|
+| 🎄 Christmas | `christmas` | Falling snowflakes |
+| 🎆 New Year | `newyear` | Fireworks & confetti |
+| 💝 Valentine | `valentine` | Floating hearts |
+| 🐰 Easter | `easter` | Eggs & flowers |
+| 🎃 Halloween | `halloween` | Bats & pumpkins |
+| 🍂 Thanksgiving | `thanksgiving` | Autumn leaves |
+| 🪔 Diwali | `diwali` | Diyas & sparkles |
+| 🏮 Chinese New Year | `chinesenewyear` | Lanterns & dragons |
+| 🎨 Holi | `holi` | Color splashes |
+| 🌙 Eid | `eid` | Moons & stars |
+| ☘️ St. Patrick's | `stpatricks` | Shamrocks |
+| 🎇 Independence Day | `independence` | Patriotic fireworks |
+
+## ⚙️ Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `festival` | `FestivalType` | required | The festival effect to display |
+| `intensity` | `'low' \| 'medium' \| 'high'` | `'medium'` | Particle density |
+| `duration` | `number` | `undefined` | Auto-stop after ms (infinite if not set) |
+| `zIndex` | `number` | `9999` | CSS z-index of overlay |
+| `respectReducedMotion` | `boolean` | `true` | Honor user's motion preferences |
+| `colors` | `string[]` | festival default | Custom color palette |
+
+## 📖 Examples
+
+### Basic Usage
+
+```tsx
+<FestiveEffects festival="christmas" />
+```
+
+### With Intensity
+
+```tsx
+<FestiveEffects 
+  festival="newyear" 
+  intensity="high" 
+/>
+```
+
+### Auto-stop After 10 Seconds
+
+```tsx
+<FestiveEffects 
+  festival="valentine" 
+  duration={10000} 
+/>
+```
+
+### Custom Colors
+
+```tsx
+<FestiveEffects 
+  festival="independence" 
+  colors={['#FF0000', '#FFFFFF', '#0000FF']} 
+/>
+```
+
+### Conditional Rendering
+
+```tsx
+function App() {
+  const [showEffects, setShowEffects] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setShowEffects(true)}>
+        Celebrate! 🎉
+      </button>
+      {showEffects && (
+        <FestiveEffects 
+          festival="diwali" 
+          duration={5000}
+        />
+      )}
+    </>
+  );
+}
+```
+
+## 🎯 TypeScript
+
+Full TypeScript support with exported types:
+
+```tsx
+import { 
+  FestiveEffects,
+  type FestivalType,
+  type IntensityLevel,
+  type FestiveEffectsProps 
+} from 'festive-effects';
+
+const festival: FestivalType = 'christmas';
+const intensity: IntensityLevel = 'medium';
+```
+
+## ♿ Accessibility
+
+By default, `FestiveEffects` respects the user's `prefers-reduced-motion` setting. When enabled, no animations will render.
+
+To override this behavior:
+
+```tsx
+<FestiveEffects 
+  festival="christmas" 
+  respectReducedMotion={false} 
+/>
+```
+
+## 📄 License
+
+MIT © [Your Name]
+
+---
+
+Made with 💜 and Framer Motion

package/dist/animations/index.d.ts

@@ -0,0 +1,91 @@
+import type { Variants, Transition } from 'framer-motion';
+import type { AnimationType, PhysicsConfig } from '../types';
+/**
+ * Custom data passed to animation variants
+ */
+export interface AnimationCustomData {
+    /** Horizontal drift amount */
+    drift: number;
+    /** Rotation amount in degrees */
+    rotation: number;
+    /** Animation delay in seconds */
+    delay: number;
+    /** Animation duration in seconds */
+    duration: number;
+    /** Angle for radial animations (explode, scatter) */
+    angle: number;
+    /** Distance for radial animations */
+    distance: number;
+    /** Initial X position */
+    x: number;
+    /** Initial Y position */
+    y: number;
+    /** Viewport height for calculations */
+    viewportHeight: number;
+}
+/**
+ * Fall animation variants - used for snow, leaves, shamrocks
+ * Particles fall from top to bottom with horizontal drift and rotation
+ */
+export declare const fallVariants: Variants;
+/**
+ * Get transition for fall animation
+ */
+export declare function getFallTransition(custom: AnimationCustomData): Transition;
+/**
+ * Rise animation variants - used for hearts, lanterns
+ * Particles rise from bottom to top with gentle sway
+ */
+export declare const riseVariants: Variants;
+/**
+ * Get transition for rise animation
+ */
+export declare function getRiseTransition(custom: AnimationCustomData): Transition;
+/**
+ * Explode animation variants - used for fireworks, confetti
+ * Particles burst outward from center point
+ */
+export declare const explodeVariants: Variants;
+/**
+ * Get transition for explode animation
+ */
+export declare function getExplodeTransition(custom: AnimationCustomData): Transition;
+/**
+ * Float animation variants - used for bats, diyas, moons
+ * Particles float with gentle bobbing motion
+ */
+export declare const floatVariants: Variants;
+/**
+ * Get transition for float animation
+ */
+export declare function getFloatTransition(custom: AnimationCustomData): Transition;
+/**
+ * Scatter animation variants - used for holi colors
+ * Particles scatter outward with fading effect
+ */
+export declare const scatterVariants: Variants;
+/**
+ * Get transition for scatter animation
+ */
+export declare function getScatterTransition(custom: AnimationCustomData): Transition;
+/**
+ * Map of animation types to their variants
+ */
+export declare const ANIMATION_VARIANTS: Record<AnimationType, Variants>;
+/**
+ * Get the appropriate transition function for an animation type
+ */
+export declare function getTransitionForType(animationType: AnimationType, custom: AnimationCustomData): Transition;
+/**
+ * Create custom animation data from particle properties
+ */
+export declare function createAnimationCustomData(x: number, y: number, physics: PhysicsConfig, delay: number, duration: number, viewportHeight: number): AnimationCustomData;
+/**
+ * Get animation props for a particle based on animation type
+ * Returns initial, animate, and transition properties for Framer Motion
+ */
+export declare function getAnimationPropsForType(animationType: AnimationType, custom: AnimationCustomData): {
+    initial: Record<string, unknown>;
+    animate: Record<string, unknown>;
+    transition: Transition;
+};

package/dist/components/FestiveEffects.d.ts

@@ -0,0 +1,19 @@
+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/config/index.d.ts

@@ -0,0 +1,18 @@
+import type { IntensityLevel, IntensitySettings, FestivalType, FestivalConfig } from '../types';
+/**
+ * Intensity configuration for particle effects
+ * Defines particle multipliers and max counts for each intensity level
+ */
+export declare const INTENSITY_CONFIG: Record<IntensityLevel, IntensitySettings>;
+/**
+ * Calculate the actual particle count based on base count and intensity
+ * @param baseCount - The base particle count from festival config
+ * @param intensity - The intensity level
+ * @returns The calculated particle count, capped at maxParticles
+ */
+export declare function getParticleCount(baseCount: number, intensity?: IntensityLevel): number;
+/**
+ * Festival configurations for all 12 supported festivals
+ * Each config defines colors, particle types, animation style, and physics
+ */
+export declare const FESTIVAL_CONFIGS: Record<FestivalType, FestivalConfig>;

package/dist/effects/ChineseNewYearEffect.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { ParticleData, Viewport, ParticleType } from '../types';
+/**
+ * Chinese New Year effect configuration
+ */
+export declare const CHINESENEWYEAR_CONFIG: {
+    baseParticleCount: number;
+    colors: string[];
+    particleTypes: ParticleType[];
+    animationType: "rise";
+    physics: {
+        speed: number;
+        drift: number;
+        rotation: number;
+        scale: [number, number];
+    };
+};
+/**
+ * Generate particles for Chinese New Year effect
+ */
+export declare function generateChineseNewYearParticles(count: number, viewport: Viewport, colors?: string[]): ParticleData[];
+interface ChineseNewYearEffectProps {
+    particles: ParticleData[];
+    viewport: Viewport;
+}
+/**
+ * Chinese New Year Effect Component
+ * Renders rising red lanterns and golden fireworks
+ * Red/gold color palette
+ */
+export declare const ChineseNewYearEffect: React.FC<ChineseNewYearEffectProps>;
+export default ChineseNewYearEffect;

package/dist/effects/ChristmasEffect.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { ParticleData, Viewport } from '../types';
+/**
+ * Christmas effect configuration
+ */
+export declare const CHRISTMAS_CONFIG: {
+    baseParticleCount: number;
+    colors: string[];
+    particleTypes: readonly ["snowflake"];
+    animationType: "fall";
+    physics: {
+        speed: number;
+        drift: number;
+        rotation: number;
+        scale: [number, number];
+    };
+};
+/**
+ * Generate snowflake particles for Christmas effect
+ */
+export declare function generateChristmasParticles(count: number, viewport: Viewport, colors?: string[]): ParticleData[];
+interface ChristmasEffectProps {
+    particles: ParticleData[];
+    viewport: Viewport;
+}
+/**
+ * Christmas Effect Component
+ * Renders falling snowflakes with drift and rotation
+ * White/blue color palette
+ */
+export declare const ChristmasEffect: React.FC<ChristmasEffectProps>;
+export default ChristmasEffect;

package/dist/effects/DiwaliEffect.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { ParticleData, Viewport, ParticleType } from '../types';
+/**
+ * Diwali effect configuration
+ */
+export declare const DIWALI_CONFIG: {
+    baseParticleCount: number;
+    colors: string[];
+    particleTypes: ParticleType[];
+    animationType: "float";
+    physics: {
+        speed: number;
+        drift: number;
+        rotation: number;
+        scale: [number, number];
+    };
+};
+/**
+ * Generate particles for Diwali effect
+ */
+export declare function generateDiwaliParticles(count: number, viewport: Viewport, colors?: string[]): ParticleData[];
+interface DiwaliEffectProps {
+    particles: ParticleData[];
+    viewport: Viewport;
+}
+/**
+ * Diwali Effect Component
+ * Renders glowing diyas with flickering, golden sparkles and rangoli patterns
+ * Golden/orange color palette
+ */
+export declare const DiwaliEffect: React.FC<DiwaliEffectProps>;
+export default DiwaliEffect;

package/dist/effects/EasterEffect.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { ParticleData, Viewport, ParticleType } from '../types';
+/**
+ * Easter effect configuration
+ */
+export declare const EASTER_CONFIG: {
+    baseParticleCount: number;
+    colors: string[];
+    particleTypes: ParticleType[];
+    animationType: "float";
+    physics: {
+        speed: number;
+        drift: number;
+        rotation: number;
+        scale: [number, number];
+    };
+};
+/**
+ * Generate particles for Easter effect
+ */
+export declare function generateEasterParticles(count: number, viewport: Viewport, colors?: string[]): ParticleData[];
+interface EasterEffectProps {
+    particles: ParticleData[];
+    viewport: Viewport;
+}
+/**
+ * Easter Effect Component
+ * Renders floating eggs and spring flowers
+ * Pastel color palette
+ */
+export declare const EasterEffect: React.FC<EasterEffectProps>;
+export default EasterEffect;

package/dist/effects/EidEffect.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { ParticleData, Viewport, ParticleType } from '../types';
+/**
+ * Eid effect configuration
+ */
+export declare const EID_CONFIG: {
+    baseParticleCount: number;
+    colors: string[];
+    particleTypes: ParticleType[];
+    animationType: "float";
+    physics: {
+        speed: number;
+        drift: number;
+        rotation: number;
+        scale: [number, number];
+    };
+};
+/**
+ * Generate particles for Eid effect
+ */
+export declare function generateEidParticles(count: number, viewport: Viewport, colors?: string[]): ParticleData[];
+interface EidEffectProps {
+    particles: ParticleData[];
+    viewport: Viewport;
+}
+/**
+ * Eid Effect Component
+ * Renders floating crescent moons and twinkling stars
+ * Gold/silver/green color palette
+ */
+export declare const EidEffect: React.FC<EidEffectProps>;
+export default EidEffect;

package/dist/effects/HalloweenEffect.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { ParticleData, Viewport, ParticleType } from '../types';
+/**
+ * Halloween effect configuration
+ */
+export declare const HALLOWEEN_CONFIG: {
+    baseParticleCount: number;
+    colors: string[];
+    particleTypes: ParticleType[];
+    animationType: "float";
+    physics: {
+        speed: number;
+        drift: number;
+        rotation: number;
+        scale: [number, number];
+    };
+};
+/**
+ * Generate particles for Halloween effect
+ */
+export declare function generateHalloweenParticles(count: number, viewport: Viewport, colors?: string[]): ParticleData[];
+interface HalloweenEffectProps {
+    particles: ParticleData[];
+    viewport: Viewport;
+}
+/**
+ * Halloween Effect Component
+ * Renders flying bats with erratic movement, floating pumpkins and spiders
+ * Orange/purple/black color palette
+ */
+export declare const HalloweenEffect: React.FC<HalloweenEffectProps>;
+export default HalloweenEffect;

package/dist/effects/HoliEffect.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { ParticleData, Viewport } from '../types';
+/**
+ * Holi effect configuration
+ */
+export declare const HOLI_CONFIG: {
+    baseParticleCount: number;
+    colors: string[];
+    particleTypes: readonly ["color-splash"];
+    animationType: "scatter";
+    physics: {
+        speed: number;
+        drift: number;
+        rotation: number;
+        scale: [number, number];
+    };
+};
+/**
+ * Generate particles for Holi effect
+ */
+export declare function generateHoliParticles(count: number, viewport: Viewport, colors?: string[]): ParticleData[];
+interface HoliEffectProps {
+    particles: ParticleData[];
+    viewport: Viewport;
+}
+/**
+ * Holi Effect Component
+ * Renders scattered color powder bursts
+ * Vibrant multi-color palette
+ */
+export declare const HoliEffect: React.FC<HoliEffectProps>;
+export default HoliEffect;

package/dist/effects/IndependenceEffect.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { ParticleData, Viewport, ParticleType } from '../types';
+/**
+ * Independence Day effect configuration
+ */
+export declare const INDEPENDENCE_CONFIG: {
+    baseParticleCount: number;
+    colors: string[];
+    particleTypes: ParticleType[];
+    animationType: "explode";
+    physics: {
+        speed: number;
+        drift: number;
+        rotation: number;
+        scale: [number, number];
+    };
+};
+/**
+ * Generate particles for Independence Day effect
+ */
+export declare function generateIndependenceParticles(count: number, viewport: Viewport, colors?: string[]): ParticleData[];
+interface IndependenceEffectProps {
+    particles: ParticleData[];
+    viewport: Viewport;
+}
+/**
+ * Independence Day Effect Component
+ * Renders customizable color fireworks and patriotic confetti
+ * Default US colors (red, white, blue), customizable via colors prop
+ */
+export declare const IndependenceEffect: React.FC<IndependenceEffectProps>;
+export default IndependenceEffect;

package/dist/effects/NewYearEffect.d.ts

@@ -0,0 +1,31 @@
+import React from 'react';
+import type { ParticleData, Viewport, ParticleType } from '../types';
+/**
+ * New Year effect configuration
+ */
+export declare const NEWYEAR_CONFIG: {
+    baseParticleCount: number;
+    colors: string[];
+    particleTypes: ParticleType[];
+    animationType: "explode";
+    physics: {
+        speed: number;
+        drift: number;
+        rotation: number;
+        scale: [number, number];
+    };
+};
+/**
+ * Generate particles for New Year effect
+ */
+export declare function generateNewYearParticles(count: number, viewport: Viewport, colors?: string[]): ParticleData[];
+interface NewYearEffectProps {
+    particles: ParticleData[];
+    viewport: Viewport;
+}
+/**
+ * New Year Effect Component
+ * Renders exploding fireworks with sparks and falling confetti
+ */
+export declare const NewYearEffect: React.FC<NewYearEffectProps>;
+export default NewYearEffect;

package/dist/effects/StPatricksEffect.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { ParticleData, Viewport, ParticleType } from '../types';
+/**
+ * St. Patrick's effect configuration
+ */
+export declare const STPATRICKS_CONFIG: {
+    baseParticleCount: number;
+    colors: string[];
+    particleTypes: ParticleType[];
+    animationType: "fall";
+    physics: {
+        speed: number;
+        drift: number;
+        rotation: number;
+        scale: [number, number];
+    };
+};
+/**
+ * Generate particles for St. Patrick's effect
+ */
+export declare function generateStPatricksParticles(count: number, viewport: Viewport, colors?: string[]): ParticleData[];
+interface StPatricksEffectProps {
+    particles: ParticleData[];
+    viewport: Viewport;
+}
+/**
+ * St. Patrick's Effect Component
+ * Renders falling shamrocks with spin
+ * Green color palette with gold accents
+ */
+export declare const StPatricksEffect: React.FC<StPatricksEffectProps>;
+export default StPatricksEffect;

package/dist/effects/ThanksgivingEffect.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { ParticleData, Viewport } from '../types';
+/**
+ * Thanksgiving effect configuration
+ */
+export declare const THANKSGIVING_CONFIG: {
+    baseParticleCount: number;
+    colors: string[];
+    particleTypes: readonly ["leaf"];
+    animationType: "fall";
+    physics: {
+        speed: number;
+        drift: number;
+        rotation: number;
+        scale: [number, number];
+    };
+};
+/**
+ * Generate leaf particles for Thanksgiving effect
+ */
+export declare function generateThanksgivingParticles(count: number, viewport: Viewport, colors?: string[]): ParticleData[];
+interface ThanksgivingEffectProps {
+    particles: ParticleData[];
+    viewport: Viewport;
+}
+/**
+ * Thanksgiving Effect Component
+ * Renders falling autumn leaves with tumbling rotation
+ * Orange/brown color palette
+ */
+export declare const ThanksgivingEffect: React.FC<ThanksgivingEffectProps>;
+export default ThanksgivingEffect;

package/dist/effects/ValentineEffect.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { ParticleData, Viewport } from '../types';
+/**
+ * Valentine effect configuration
+ */
+export declare const VALENTINE_CONFIG: {
+    baseParticleCount: number;
+    colors: string[];
+    particleTypes: readonly ["heart"];
+    animationType: "rise";
+    physics: {
+        speed: number;
+        drift: number;
+        rotation: number;
+        scale: [number, number];
+    };
+};
+/**
+ * Generate heart particles for Valentine effect
+ */
+export declare function generateValentineParticles(count: number, viewport: Viewport, colors?: string[]): ParticleData[];
+interface ValentineEffectProps {
+    particles: ParticleData[];
+    viewport: Viewport;
+}
+/**
+ * Valentine Effect Component
+ * Renders rising hearts with gentle sway
+ * Pink/red color palette
+ */
+export declare const ValentineEffect: React.FC<ValentineEffectProps>;
+export default ValentineEffect;