festive-effects 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,754 @@
+import React from 'react';
+import { Variants, Transition } from 'framer-motion';
+
+/**
+ * Union type of all supported festival effects
+ */
+type FestivalType = 'christmas' | 'newyear' | 'valentine' | 'easter' | 'halloween' | 'thanksgiving' | 'diwali' | 'chinesenewyear' | 'holi' | 'eid' | 'stpatricks' | 'independence';
+/**
+ * Array of all valid festival types for validation
+ */
+declare const FESTIVAL_TYPES: FestivalType[];
+/**
+ * Intensity levels for particle effects
+ */
+type IntensityLevel = 'low' | 'medium' | 'high';
+/**
+ * Props for the main FestiveEffects component
+ */
+interface FestiveEffectsProps {
+    /** The festival effect to display */
+    festival: FestivalType;
+    /** Intensity of the effect (particle count) */
+    intensity?: IntensityLevel;
+    /** Duration in milliseconds before effect stops */
+    duration?: number;
+    /** CSS z-index for the overlay */
+    zIndex?: number;
+    /** Whether to respect prefers-reduced-motion setting */
+    respectReducedMotion?: boolean;
+    /** Custom colors to override default festival colors */
+    colors?: string[];
+}
+/**
+ * Settings for each intensity level
+ */
+interface IntensitySettings {
+    /** Multiplier for base particle count */
+    particleMultiplier: number;
+    /** Maximum number of particles allowed */
+    maxParticles: number;
+}
+/**
+ * Physics configuration for particle animations
+ */
+interface PhysicsConfig {
+    /** Base animation speed */
+    speed: number;
+    /** Horizontal drift amount in pixels */
+    drift: number;
+    /** Rotation amount in degrees */
+    rotation: number;
+    /** Min/max scale range */
+    scale: [number, number];
+}
+/**
+ * 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';
+/**
+ * Animation types for particle effects
+ */
+type AnimationType = 'fall' | 'rise' | 'explode' | 'float' | 'scatter';
+/**
+ * Configuration for a festival effect
+ */
+interface FestivalConfig {
+    /** Base number of particles before intensity multiplier */
+    baseParticleCount: number;
+    /** Color palette for the effect */
+    colors: string[];
+    /** Types of particles used in this effect */
+    particleTypes: ParticleType[];
+    /** Primary animation type */
+    animationType: AnimationType;
+    /** Physics settings for animations */
+    physics: PhysicsConfig;
+}
+/**
+ * Viewport dimensions
+ */
+interface Viewport {
+    width: number;
+    height: number;
+}
+/**
+ * Data for a single particle instance
+ */
+interface ParticleData {
+    /** Unique identifier */
+    id: string;
+    /** Initial X position */
+    x: number;
+    /** Initial Y position */
+    y: number;
+    /** Particle size in pixels */
+    size: number;
+    /** Particle color */
+    color: string;
+    /** Type of particle shape */
+    type: ParticleType;
+    /** Animation delay in seconds */
+    delay: number;
+    /** Animation duration in seconds */
+    duration: number;
+    /** Additional custom properties for animation */
+    custom: Record<string, unknown>;
+}
+/**
+ * Framer Motion animation configuration
+ */
+interface AnimationConfig {
+    /** Animation target values */
+    animate: {
+        x?: number | number[];
+        y?: number | number[];
+        rotate?: number | number[];
+        scale?: number | number[];
+        opacity?: number | number[];
+    };
+    /** Transition settings */
+    transition: {
+        duration: number;
+        ease?: string | number[];
+        repeat?: number;
+        repeatType?: 'loop' | 'reverse' | 'mirror';
+        delay?: number;
+    };
+}
+/**
+ * Props for individual particle components
+ */
+interface ParticleProps {
+    /** Unique identifier */
+    id: string;
+    /** Initial X position */
+    initialX: number;
+    /** Initial Y position */
+    initialY: number;
+    /** Particle size */
+    size: number;
+    /** Particle color */
+    color: string;
+    /** Type of particle */
+    type: ParticleType;
+    /** Animation configuration */
+    animationConfig: AnimationConfig;
+}
+
+/**
+ * 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>;
+
+/**
+ * Intensity configuration for particle effects
+ * Defines particle multipliers and max counts for each intensity level
+ */
+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
+ */
+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
+ */
+declare const FESTIVAL_CONFIGS: Record<FestivalType, FestivalConfig>;
+
+/**
+ * SVG definitions for all 18 particle types
+ * Each SVG is designed to work with currentColor for dynamic coloring
+ */
+declare const PARTICLE_SVGS: Record<ParticleType, string>;
+/**
+ * Props for the Particle component
+ */
+interface ParticleComponentProps {
+    particle: ParticleData;
+    animationType: AnimationType;
+    physics: PhysicsConfig;
+}
+/**
+ * Particle component that renders an SVG particle with Framer Motion animations
+ */
+declare const Particle: React.FC<ParticleComponentProps>;
+/**
+ * Generate particles for a festival effect
+ * @param count - Number of particles to generate
+ * @param viewport - Viewport dimensions
+ * @param particleTypes - Array of particle types to use
+ * @param colors - Array of colors to use
+ * @param physics - Physics configuration
+ * @param animationType - Type of animation
+ * @returns Array of ParticleData objects
+ */
+declare function generateParticles(count: number, viewport: Viewport, particleTypes: ParticleType[], colors: string[], physics: PhysicsConfig, animationType: AnimationType): ParticleData[];
+/**
+ * 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
+ */
+declare function calculateParticleCount(baseCount: number, intensity?: IntensityLevel): number;
+
+/**
+ * Custom data passed to animation variants
+ */
+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
+ */
+declare const fallVariants: Variants;
+/**
+ * Get transition for fall animation
+ */
+declare function getFallTransition(custom: AnimationCustomData): Transition;
+/**
+ * Rise animation variants - used for hearts, lanterns
+ * Particles rise from bottom to top with gentle sway
+ */
+declare const riseVariants: Variants;
+/**
+ * Get transition for rise animation
+ */
+declare function getRiseTransition(custom: AnimationCustomData): Transition;
+/**
+ * Explode animation variants - used for fireworks, confetti
+ * Particles burst outward from center point
+ */
+declare const explodeVariants: Variants;
+/**
+ * Get transition for explode animation
+ */
+declare function getExplodeTransition(custom: AnimationCustomData): Transition;
+/**
+ * Float animation variants - used for bats, diyas, moons
+ * Particles float with gentle bobbing motion
+ */
+declare const floatVariants: Variants;
+/**
+ * Get transition for float animation
+ */
+declare function getFloatTransition(custom: AnimationCustomData): Transition;
+/**
+ * Scatter animation variants - used for holi colors
+ * Particles scatter outward with fading effect
+ */
+declare const scatterVariants: Variants;
+/**
+ * Get transition for scatter animation
+ */
+declare function getScatterTransition(custom: AnimationCustomData): Transition;
+/**
+ * Map of animation types to their variants
+ */
+declare const ANIMATION_VARIANTS: Record<AnimationType, Variants>;
+/**
+ * Get the appropriate transition function for an animation type
+ */
+declare function getTransitionForType(animationType: AnimationType, custom: AnimationCustomData): Transition;
+/**
+ * Create custom animation data from particle properties
+ */
+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
+ */
+declare function getAnimationPropsForType(animationType: AnimationType, custom: AnimationCustomData): {
+    initial: Record<string, unknown>;
+    animate: Record<string, unknown>;
+    transition: Transition;
+};
+
+/**
+ * Hook to detect if the user prefers reduced motion
+ * Listens to the prefers-reduced-motion media query
+ *
+ * @returns boolean - true if user prefers reduced motion, false otherwise
+ *
+ * @example
+ * ```tsx
+ * const prefersReducedMotion = useReducedMotion();
+ * if (prefersReducedMotion) {
+ *   // Don't render animations
+ *   return null;
+ * }
+ * ```
+ */
+declare function useReducedMotion(): boolean;
+
+/**
+ * Interface for a festival effect
+ * Each effect provides particle generation and rendering capabilities
+ */
+interface FestivalEffect {
+    /** The festival type identifier */
+    name: FestivalType;
+    /** Generate particles for this effect */
+    generateParticles(count: number, viewport: Viewport): ParticleData[];
+    /** Get the festival configuration */
+    getConfig(): FestivalConfig;
+    /** Render a single particle */
+    renderParticle(particle: ParticleData): React.ReactNode;
+}
+/**
+ * Create a festival effect from a festival type
+ * @param festivalType - The type of festival
+ * @returns A FestivalEffect instance
+ */
+declare function createFestivalEffect(festivalType: FestivalType): FestivalEffect;
+/**
+ * Registry for managing festival effects
+ * Provides methods to register, retrieve, and list festival effects
+ */
+declare class FestivalRegistry {
+    private effects;
+    /**
+     * Register a festival effect
+     * @param effect - The festival effect to register
+     */
+    register(effect: FestivalEffect): void;
+    /**
+     * Get a festival effect by type
+     * @param festival - The festival type to retrieve
+     * @returns The festival effect or undefined if not found
+     */
+    get(festival: FestivalType): FestivalEffect | undefined;
+    /**
+     * Check if a festival effect is registered
+     * @param festival - The festival type to check
+     * @returns True if the effect is registered
+     */
+    has(festival: FestivalType): boolean;
+    /**
+     * List all registered festival types
+     * @returns Array of registered festival types
+     */
+    list(): FestivalType[];
+    /**
+     * Get the number of registered effects
+     * @returns The count of registered effects
+     */
+    get size(): number;
+    /**
+     * Clear all registered effects
+     */
+    clear(): void;
+}
+/**
+ * Default registry instance with all 12 festival effects pre-registered
+ */
+declare const defaultRegistry: FestivalRegistry;
+
+/**
+ * Christmas effect configuration
+ */
+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
+ */
+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
+ */
+declare const ChristmasEffect: React.FC<ChristmasEffectProps>;
+
+/**
+ * New Year effect configuration
+ */
+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
+ */
+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
+ */
+declare const NewYearEffect: React.FC<NewYearEffectProps>;
+
+/**
+ * Valentine effect configuration
+ */
+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
+ */
+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
+ */
+declare const ValentineEffect: React.FC<ValentineEffectProps>;
+
+/**
+ * Easter effect configuration
+ */
+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
+ */
+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
+ */
+declare const EasterEffect: React.FC<EasterEffectProps>;
+
+/**
+ * Halloween effect configuration
+ */
+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
+ */
+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
+ */
+declare const HalloweenEffect: React.FC<HalloweenEffectProps>;
+
+/**
+ * Thanksgiving effect configuration
+ */
+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
+ */
+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
+ */
+declare const ThanksgivingEffect: React.FC<ThanksgivingEffectProps>;
+
+/**
+ * Diwali effect configuration
+ */
+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
+ */
+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
+ */
+declare const DiwaliEffect: React.FC<DiwaliEffectProps>;
+
+/**
+ * Chinese New Year effect configuration
+ */
+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
+ */
+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
+ */
+declare const ChineseNewYearEffect: React.FC<ChineseNewYearEffectProps>;
+
+/**
+ * Holi effect configuration
+ */
+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
+ */
+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
+ */
+declare const HoliEffect: React.FC<HoliEffectProps>;
+
+/**
+ * Eid effect configuration
+ */
+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
+ */
+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
+ */
+declare const EidEffect: React.FC<EidEffectProps>;
+
+/**
+ * St. Patrick's effect configuration
+ */
+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
+ */
+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
+ */
+declare const StPatricksEffect: React.FC<StPatricksEffectProps>;
+
+/**
+ * Independence Day effect configuration
+ */
+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
+ */
+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
+ */
+declare const IndependenceEffect: React.FC<IndependenceEffectProps>;
+
+type EffectGenerator = (count: number, viewport: Viewport, colors?: string[]) => ParticleData[];
+declare const EFFECT_GENERATORS: Record<FestivalType, EffectGenerator>;
+
+export { ANIMATION_VARIANTS, CHINESENEWYEAR_CONFIG, CHRISTMAS_CONFIG, ChineseNewYearEffect, ChristmasEffect, DIWALI_CONFIG, DiwaliEffect, EASTER_CONFIG, EFFECT_GENERATORS, EID_CONFIG, EasterEffect, EidEffect, FESTIVAL_CONFIGS, FESTIVAL_TYPES, FestivalRegistry, FestiveEffects, HALLOWEEN_CONFIG, HOLI_CONFIG, HalloweenEffect, HoliEffect, INDEPENDENCE_CONFIG, INTENSITY_CONFIG, IndependenceEffect, NEWYEAR_CONFIG, NewYearEffect, PARTICLE_SVGS, Particle, STPATRICKS_CONFIG, StPatricksEffect, THANKSGIVING_CONFIG, ThanksgivingEffect, VALENTINE_CONFIG, ValentineEffect, calculateParticleCount, createAnimationCustomData, createFestivalEffect, defaultRegistry, explodeVariants, fallVariants, floatVariants, generateChineseNewYearParticles, generateChristmasParticles, generateDiwaliParticles, generateEasterParticles, generateEidParticles, generateHalloweenParticles, generateHoliParticles, generateIndependenceParticles, generateNewYearParticles, generateParticles, generateStPatricksParticles, generateThanksgivingParticles, generateValentineParticles, getAnimationPropsForType, getExplodeTransition, getFallTransition, getFloatTransition, getParticleCount, getRiseTransition, getScatterTransition, getTransitionForType, riseVariants, scatterVariants, useReducedMotion };
+export type { AnimationConfig, AnimationCustomData, AnimationType, EffectGenerator, FestivalConfig, FestivalEffect, FestivalType, FestiveEffectsProps, IntensityLevel, IntensitySettings, ParticleComponentProps, ParticleData, ParticleProps, ParticleType, PhysicsConfig, Viewport };