react-confetti-burst 1.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * react-confetti-burst
+ *
+ * A high-performance, zero-dependency React confetti component
+ * with directional bursts using the native Canvas API.
+ * Exceeds the feature set of both react-confetti and canvas-confetti.
+ *
+ * @packageDocumentation
+ */
+/**
+ * ============================================================================
+ * FEATURE RELEASE FLAGS
+ * ============================================================================
+ *
+ * Uncomment features as they are released:
+ *
+ * v1.0.0 - Basic Usage (ConfettiButton, useConfetti, basic confetti())
+ * v1.1.0 - React Hooks (useConfettiTrigger, useConfettiSequence, useConfettiCenter)
+ * v1.2.0 - Built-in Presets (16 presets)
+ * v1.3.0 - canvas-confetti API (confetti.create, confetti.reset)
+ * v1.4.0 - Custom Shapes (shapeFromPath, shapeFromText, shapesFromEmoji)
+ * v1.5.0 - Advanced Effects (trails, glow, fireworks, continuous mode)
+ * v1.6.0 - Full Feature Set
+ *
+ * ============================================================================
+ */
+export type { Point, Vector2D, RGBAColor, GradientColor, ColorInput, ParticleShape, BurstDirection, EasingFunction, EasingPreset, PhysicsConfig, DirectionConfig, ParticleConfig, ConfettiBurstConfig, ConfettiBurstOptions, BurstOrigin, ParticleState, AnimationState, CanvasContext, ExplosionHandle, UseConfettiReturn, ConfettiBurstProps, ConfettiButtonProps, } from './types';
+export { DEFAULT_COLORS, DEFAULT_PHYSICS, DEFAULT_DIRECTION, DEFAULT_PARTICLE, DEFAULT_CONFIG, DIRECTION_ANGLES, EASING_FUNCTIONS, COLOR_PALETTES, } from './constants';
+export { ConfettiEngine, createConfettiExplosion, fireFromElement, getActiveAnimationCount, forceCleanup, } from './confetti-engine';
+export { useConfetti, } from './hooks';
+export { ConfettiBurst, ConfettiButton, } from './components';
+export { parseColor, rgbaToString, randomInRange, randomInt, randomFromArray, clamp, lerp, degToRad, radToDeg, getDirectionAngle, getElementCenter, mergeConfig, isBrowser, } from './utils';
+export { confetti, confetti as default } from './confetti';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;GAgBG;AAOH,YAAY,EAEV,KAAK,EACL,QAAQ,EACR,SAAS,EACT,aAAa,EACb,UAAU,EACV,aAAa,EACb,cAAc,EACd,cAAc,EACd,YAAY,EAGZ,aAAa,EACb,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,EAGX,aAAa,EACb,cAAc,EACd,aAAa,EAGb,eAAe,EACf,iBAAiB,EAGjB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,eAAe,EACf,uBAAuB,EACvB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,WAAW,GACZ,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,aAAa,EACb,cAAc,GACf,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,UAAU,EACV,YAAY,EACZ,aAAa,EACb,SAAS,EACT,eAAe,EACf,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,SAAS,GACV,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,QAAQ,EAAE,QAAQ,IAAI,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/dist/types/particle.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Particle class for confetti animation
+ *
+ * Represents a single confetti particle with all physics properties
+ * and methods for updating and rendering.
+ */
+import type { ParticleState, ParticleShape, PhysicsConfig, ImageParticle, TrailConfig, GlowConfig, ColorInput, CustomDrawFunction } from './types';
+/**
+ * Loads an image and caches it
+ */
+export declare function loadImage(src: string): Promise<HTMLImageElement>;
+/**
+ * Clears the image cache
+ */
+export declare function clearImageCache(): void;
+/**
+ * Creates a new particle state object
+ */
+export declare function createParticle(x: number, y: number, angle: number, velocity: number, colors: readonly ColorInput[], shapes: readonly ParticleShape[], sizeRange: readonly [number, number], opacityRange: readonly [number, number], lifespan: number, rotationSpeed: number, options?: {
+    images?: readonly ImageParticle[];
+    tiltRange?: readonly [number, number];
+    spinSpeedRange?: readonly [number, number];
+    depth3D?: number;
+}): ParticleState;
+/**
+ * Updates a particle's physics state
+ */
+export declare function updateParticle(particle: ParticleState, deltaTime: number, physics: PhysicsConfig, fadeOut: boolean, scaleDown: boolean, trailConfig?: Partial<TrailConfig>, canvasHeight?: number): void;
+/**
+ * Renders a particle to a canvas context
+ */
+export declare function renderParticle(ctx: CanvasRenderingContext2D, particle: ParticleState, options?: {
+    trailConfig?: Partial<TrailConfig>;
+    glowConfig?: Partial<GlowConfig>;
+    customDraw?: CustomDrawFunction;
+    elapsed?: number;
+}): void;
+/**
+ * Checks if all particles in an array are inactive
+ */
+export declare function areAllParticlesInactive(particles: readonly ParticleState[]): boolean;
+/**
+ * Counts active particles
+ */
+export declare function countActiveParticles(particles: readonly ParticleState[]): number;
+/**
+ * Resets the particle ID counter (useful for testing)
+ */
+export declare function resetParticleIdCounter(): void;
+//# sourceMappingURL=particle.d.ts.map

package/dist/types/particle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle.d.ts","sourceRoot":"","sources":["../../src/particle.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EAEb,aAAa,EACb,aAAa,EACb,WAAW,EACX,UAAU,EACV,UAAU,EAEV,kBAAkB,EACnB,MAAM,SAAS,CAAC;AA+BjB;;GAEG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAchE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,SAAS,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,YAAY,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EACvC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE;IACR,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,SAAS,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,cAAc,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACA,aAAa,CAgDf;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,OAAO,EAClB,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,EAClC,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CA2FN;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,wBAAwB,EAC7B,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE;IACR,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACA,IAAI,CAuFN;AA4ND;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAEpF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAEhF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/types/shapes.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Shape helper functions
+ *
+ * Provides canvas-confetti compatible shape creation utilities
+ * for custom SVG paths, text, and emoji shapes.
+ *
+ * @module shapes
+ */
+import type { PathShape, TextShape, CustomShape } from './types';
+/**
+ * Options for creating a shape from an SVG path
+ */
+export interface ShapeFromPathOptions {
+    /** SVG path string (d attribute) */
+    readonly path: string;
+    /** Optional 2D transformation matrix [a, b, c, d, e, f] */
+    readonly matrix?: readonly number[];
+    /** Fill color (optional, will use particle color if not set) */
+    readonly fillColor?: string;
+    /** Stroke color (optional) */
+    readonly strokeColor?: string;
+    /** Stroke width (optional) */
+    readonly strokeWidth?: number;
+}
+/**
+ * Options for creating a shape from text/emoji
+ */
+export interface ShapeFromTextOptions {
+    /** Text or emoji to render */
+    readonly text: string;
+    /** Scale factor for the text size. Default: 1 */
+    readonly scalar?: number;
+    /** Text color (optional, will use particle color if not set) */
+    readonly color?: string;
+    /** Font family. Default: 'serif' */
+    readonly fontFamily?: string;
+    /** Font weight. Default: 'normal' */
+    readonly fontWeight?: string | number;
+    /** Font style. Default: 'normal' */
+    readonly fontStyle?: 'normal' | 'italic' | 'oblique';
+}
+/**
+ * Create a custom shape from an SVG path string.
+ *
+ * This is compatible with canvas-confetti's shapeFromPath function.
+ *
+ * @example
+ * ```typescript
+ * // Simple star shape
+ * const star = shapeFromPath({
+ *   path: 'M0,-1 L0.588,0.809 L-0.951,-0.309 L0.951,-0.309 L-0.588,0.809 Z'
+ * });
+ *
+ * // With transformation matrix
+ * const scaledStar = shapeFromPath({
+ *   path: 'M0,-1 L0.588,0.809 L-0.951,-0.309 L0.951,-0.309 L-0.588,0.809 Z',
+ *   matrix: [2, 0, 0, 2, 0, 0] // Scale 2x
+ * });
+ *
+ * // Usage with confetti
+ * fire({ x: 0.5, y: 0.5 }, {
+ *   particle: { shapes: [star, 'circle'] }
+ * });
+ * ```
+ *
+ * @param options - Shape configuration options
+ * @returns PathShape object for use in confetti configuration
+ */
+export declare function shapeFromPath(options: ShapeFromPathOptions): PathShape;
+/**
+ * Create a custom shape from text or an emoji.
+ *
+ * This is compatible with canvas-confetti's shapeFromText function.
+ *
+ * @example
+ * ```typescript
+ * // Emoji confetti
+ * const heart = shapeFromText({ text: '❤️' });
+ * const party = shapeFromText({ text: '🎉', scalar: 2 });
+ *
+ * // Custom text
+ * const yay = shapeFromText({
+ *   text: 'YAY',
+ *   fontFamily: 'Impact',
+ *   color: '#ff0000'
+ * });
+ *
+ * // Usage with confetti
+ * fire({ x: 0.5, y: 0.5 }, {
+ *   particle: { shapes: [heart, party, yay] }
+ * });
+ * ```
+ *
+ * @param options - Text shape configuration options
+ * @returns TextShape object for use in confetti configuration
+ */
+export declare function shapeFromText(options: ShapeFromTextOptions): TextShape;
+/**
+ * Create a bitmap shape from an image URL or HTMLImageElement.
+ *
+ * @example
+ * ```typescript
+ * const logo = await shapeFromImage({
+ *   src: '/logo.png',
+ *   width: 32,
+ *   height: 32
+ * });
+ *
+ * fire({ x: 0.5, y: 0.5 }, {
+ *   particle: { shapes: [logo] }
+ * });
+ * ```
+ *
+ * @param options - Image shape configuration options
+ * @returns Promise resolving to a custom shape
+ */
+export declare function shapeFromImage(options: {
+    readonly src: string | HTMLImageElement;
+    readonly width?: number;
+    readonly height?: number;
+    readonly scalar?: number;
+}): Promise<CustomShape>;
+/**
+ * Create multiple shapes from an array of emoji.
+ *
+ * @example
+ * ```typescript
+ * const partyEmoji = shapesFromEmoji(['🎉', '🎊', '✨', '🥳']);
+ *
+ * fire({ x: 0.5, y: 0.5 }, {
+ *   particle: { shapes: partyEmoji }
+ * });
+ * ```
+ *
+ * @param emojis - Array of emoji strings
+ * @param options - Optional common options for all emoji
+ * @returns Array of TextShape objects
+ */
+export declare function shapesFromEmoji(emojis: readonly string[], options?: Omit<ShapeFromTextOptions, 'text'>): TextShape[];
+/**
+ * Common predefined path shapes
+ */
+export declare const pathShapes: {
+    /** Five-pointed star */
+    star: PathShape;
+    /** Heart shape */
+    heart: PathShape;
+    /** Diamond shape */
+    diamond: PathShape;
+    /** Hexagon shape */
+    hexagon: PathShape;
+    /** Triangle shape */
+    triangle: PathShape;
+    /** Plus/cross shape */
+    plus: PathShape;
+    /** Moon/crescent shape */
+    moon: PathShape;
+    /** Lightning bolt */
+    lightning: PathShape;
+    /** Spiral shape */
+    spiral: PathShape;
+    /** Ribbon/wave shape */
+    ribbon: PathShape;
+};
+/**
+ * Common emoji sets for quick use
+ */
+export declare const emojiShapes: {
+    /** Party/celebration emoji */
+    party: TextShape[];
+    /** Heart emoji */
+    hearts: TextShape[];
+    /** Star emoji */
+    stars: TextShape[];
+    /** Nature emoji */
+    nature: TextShape[];
+    /** Food emoji */
+    food: TextShape[];
+    /** Sports emoji */
+    sports: TextShape[];
+    /** Weather emoji */
+    weather: TextShape[];
+    /** Money emoji */
+    money: TextShape[];
+    /** Animals emoji */
+    animals: TextShape[];
+    /** Holiday emoji */
+    holiday: TextShape[];
+};
+//# sourceMappingURL=shapes.d.ts.map

package/dist/types/shapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapes.d.ts","sourceRoot":"","sources":["../../src/shapes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,8BAA8B;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC,oCAAoC;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;CACtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,CAetE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,CAmBtE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC,WAAW,CAAC,CAwBvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,GAAE,IAAI,CAAC,oBAAoB,EAAE,MAAM,CAAM,GAC/C,SAAS,EAAE,CAEb;AAED;;GAEG;AACH,eAAO,MAAM,UAAU;IACrB,wBAAwB;;IAKxB,kBAAkB;;IAKlB,oBAAoB;;IAKpB,oBAAoB;;IAKpB,qBAAqB;;IAKrB,uBAAuB;;IAKvB,0BAA0B;;IAK1B,qBAAqB;;IAKrB,mBAAmB;;IAKnB,wBAAwB;;CAIzB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB,8BAA8B;;IAG9B,kBAAkB;;IAGlB,iBAAiB;;IAGjB,mBAAmB;;IAGnB,iBAAiB;;IAGjB,mBAAmB;;IAGnB,oBAAoB;;IAGpB,kBAAkB;;IAGlB,oBAAoB;;IAGpB,oBAAoB;;CAErB,CAAC"}