@tsparticles/fireworks 4.0.0-beta.9 → 4.0.0

package/README.md

@@ -4,8 +4,7 @@
 
 [![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/fireworks/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/fireworks) [![npmjs](https://badge.fury.io/js/@tsparticles/fireworks.svg)](https://www.npmjs.com/package/@tsparticles/fireworks) [![npmjs](https://img.shields.io/npm/dt/@tsparticles/fireworks)](https://www.npmjs.com/package/@tsparticles/fireworks) [![GitHub Sponsors](https://img.shields.io/github/sponsors/matteobruni)](https://github.com/sponsors/matteobruni)
 
-[tsParticles](https://github.com/tsparticles/tsparticles) fireworks bundle loads all the features necessary to create
-beautiful fireworks effects with ease.
+[tsParticles](https://github.com/tsparticles/tsparticles) fireworks bundle to create fireworks effects with a focused API.
 
 **Included Packages**
 
@@ -13,10 +12,12 @@ beautiful fireworks effects with ease.
 - [@tsparticles/engine](https://github.com/tsparticles/tsparticles/tree/main/engine)
 - [@tsparticles/plugin-blend](https://github.com/tsparticles/tsparticles/tree/main/plugins/blend)
 - [@tsparticles/plugin-emitters](https://github.com/tsparticles/tsparticles/tree/main/plugins/emitters)
-- [@tsparticles/plugin-emitters-shape-square](https://github.com/tsparticles/tsparticles/tree/main/plugins/emitters/shape/square)
+- [@tsparticles/plugin-emitters-shape-square](https://github.com/tsparticles/tsparticles/tree/main/plugins/emittersShapes/square)
 - [@tsparticles/plugin-sounds](https://github.com/tsparticles/tsparticles/tree/main/plugins/sounds)
+- [@tsparticles/shape-line](https://github.com/tsparticles/tsparticles/tree/main/shapes/line)
 - [@tsparticles/updater-destroy](https://github.com/tsparticles/tsparticles/tree/main/updaters/destroy)
 - [@tsparticles/updater-life](https://github.com/tsparticles/tsparticles/tree/main/updaters/life)
+- [@tsparticles/updater-paint](https://github.com/tsparticles/tsparticles/tree/main/updaters/paint)
 - [@tsparticles/updater-rotate](https://github.com/tsparticles/tsparticles/tree/main/updaters/rotate)
 
 ## Dependency Graph
@@ -43,40 +44,98 @@ end
 subgraph u [Updaters]
   ud[tsparticles/updater-destroy]
   ul[tsparticles/updater-life]
+  up[tsparticles/updater-paint]
   ur[tsparticles/updater-rotate]
 end
 
+subgraph s [Shapes]
+  sl[tsparticles/shape-line]
+end
+
 bf --> bb
 bf --> ce
-bf --> e
 bf --> p
+bf --> s
 bf --> u
 ```
 
-## Quick checklist
+## Exposed API
+
+The package API is centered on `fireworks`.
+
+```ts
+import { fireworks } from "@tsparticles/fireworks";
 
-1. Install `@tsparticles/engine` (or use the CDN bundle below)
-2. Call the package loader function(s) before `tsParticles.load(...)`
-3. Apply the package options in your `tsParticles.load(...)` config
+// Main API
+const instance = await fireworks();
+const byId = await fireworks("canvas-id", options);
+const byOptions = await fireworks(options);
+
+// Extra helpers
+await fireworks.init();
+const custom = await fireworks.create(canvas, options);
+
+console.log(fireworks.version);
+```
+
+`@tsparticles/fireworks` does not expose `tsParticles` from its main entrypoint.
+If you need direct engine APIs, import them from `@tsparticles/engine`.
+
+## Installation
+
+```bash
+pnpm add @tsparticles/fireworks
+```
 
 ## How to use it
 
+### ESM / TypeScript
+
+```ts
+import { fireworks } from "@tsparticles/fireworks";
+
+const instance = await fireworks({
+  colors: ["#ffffff", "#ff0000"],
+  sounds: false,
+});
+
+instance?.pause();
+instance?.play();
+instance?.stop();
+```
+
+With explicit canvas id:
+
+```ts
+import { fireworks } from "@tsparticles/fireworks";
+
+await fireworks("tsparticles", {
+  rate: 3,
+  speed: { min: 10, max: 25 },
+});
+```
+
+### Custom canvas via `fireworks.create`
+
+```ts
+import { fireworks } from "@tsparticles/fireworks";
+
+const canvas = document.getElementById("my-canvas") as HTMLCanvasElement;
+await fireworks.create(canvas, { sounds: true });
+```
+
 ### CDN / Vanilla JS / jQuery
 
-The CDN/Vanilla version JS has two different files:
+The CDN/Vanilla JS version has two files:
 
 - One is a bundle file with all the scripts included in a single file
-- One is a file including just the `fireworks` function to load the tsParticles fireworks bunddle, all dependencies must
-  be
-  included manually
-
-#### Bundle
+- One includes only the `fireworks` API, where dependencies must be loaded manually
 
-Including the `tsparticles.fireworks.bundle.min.js` file will out of the box.
+After loading the bundle, `fireworks` is available on `globalThis`.
 
-This is the easiest usage, since it's a single file with all the features loaded.
+#### Bundle
 
-You can still add additional packages, loading them like all the other packages.
+Use the bundle when you want a single script with all required dependencies.
 
 #### Not Bundle
 
@@ -85,47 +144,33 @@ specified in the **Included Packages** section.
 
 ### Usage
 
-Once the scripts are loaded you can set up `tsParticles` like the following examples:
-
-** Easiest Way **
-
 ```javascript
 fireworks();
 ```
 
-** Async Way, best practice **
-
 ```javascript
 (async () => {
-  await fireworks();
+  const instance = await fireworks();
+
+  instance?.pause();
+  instance?.play();
+  instance?.stop();
 })();
 ```
 
-** Custom Canvas **
-
 ```javascript
 fireworks.create(document.getElementById("custom-id"));
 ```
 
-** Fireworks Options **
-
-```javascript
-fireworks({
-  colors: ["#ffffff", "#ff0000"],
-});
-```
-
-** Custom Canvas with Options **
+#### Options
 
-```javascript
-fireworks.create(document.getElementById("custom-id"), {
-  colors: ["#ffffff", "#ff0000"],
-});
-```
+`fireworks` supports these call signatures:
 
-#### Options
+- `fireworks()`
+- `fireworks(options)`
+- `fireworks(id, options)`
 
-The `fireworks` has only a single `options` object parameter, with the following properties:
+Main options:
 
 - `background` String: The background color of the canvas, it can be any valid CSS color, can be transparent as well.
 - `brightness` Number or { min: number; max: number; }: The brightness offset applied to the particles color, from -100
@@ -141,11 +186,19 @@ The `fireworks` has only a single `options` object parameter, with the following
 - `speed` Number or { min: number; max: number; }: The speed of the fireworks particles.
 - `splitCount` Number or { min: number; max: number; }: The number of particles to split the emitter in.
 
+### Returned instance methods
+
+The resolved `FireworksInstance` exposes:
+
+- `pause()`
+- `play()`
+- `stop()`
+
 ## Common pitfalls
 
-- Calling `tsParticles.load(...)` before `package loader(...)`
-- Verify required peer packages before enabling advanced options
-- Change one option group at a time to isolate regressions quickly
+- Calling `fireworks` before scripts are loaded in CDN usage
+- Assuming `tsParticles` is exported by `@tsparticles/fireworks` main entrypoint
+- Reusing the same `id` unintentionally (the package caches instances by id)
 
 ## Related docs
 

package/browser/browser.js

@@ -0,0 +1,5 @@
+import { fireworks } from "./index.js";
+const globalObject = globalThis;
+globalObject.__tsParticlesInternals = globalObject.__tsParticlesInternals ?? {};
+globalObject.fireworks = fireworks;
+export * from "./index.js";

package/browser/bundle.js

@@ -1,2 +1,6 @@
+import { fireworks } from "./index.js";
 export * from "./index.js";
 export * from "@tsparticles/engine";
+const globalObject = globalThis;
+globalObject.__tsParticlesInternals = globalObject.__tsParticlesInternals ?? {};
+globalObject.fireworks = fireworks;

package/browser/fireworks.js

@@ -1,230 +1,45 @@
-import { DestroyType, EventType, MoveDirection, OutMode, StartValueType, getRangeMax, getRangeMin, isNumber, isString, setRangeValue, tsParticles, } from "@tsparticles/engine";
-import { FireworkOptions } from "./FireworkOptions.js";
-let initialized = false, initializing = false;
-const explodeSoundCheck = (args) => {
-    const data = args.data;
-    return data?.particle?.options.move.gravity.enable ?? false;
-};
-async function initPlugins(engine) {
-    if (initialized) {
-        return;
-    }
-    if (initializing) {
-        return new Promise(resolve => {
-            const timeout = 100, interval = setInterval(() => {
-                if (!initialized) {
-                    return;
-                }
-                clearInterval(interval);
-                resolve();
-            }, timeout);
-        });
-    }
-    initializing = true;
-    engine.checkVersion("4.0.0-beta.9");
+import { isString, tsParticles } from "@tsparticles/engine";
+import { getFireworksInstance } from "./utils.js";
+import { loadBasic } from "@tsparticles/basic";
+import { loadBlendPlugin } from "@tsparticles/plugin-blend";
+import { loadDestroyUpdater } from "@tsparticles/updater-destroy";
+import { loadEmittersPluginSimple } from "@tsparticles/plugin-emitters/plugin";
+import { loadEmittersShapeSquare } from "@tsparticles/plugin-emitters-shape-square";
+import { loadLifeUpdater } from "@tsparticles/updater-life";
+import { loadLineShape } from "@tsparticles/shape-line";
+import { loadPaintUpdater } from "@tsparticles/updater-paint";
+import { loadRotateUpdater } from "@tsparticles/updater-rotate";
+import { loadSoundsPlugin } from "@tsparticles/plugin-sounds";
+let initPromise = null;
+async function doInitPlugins(engine) {
+    engine.checkVersion("4.0.0");
     await engine.pluginManager.register(async (e) => {
-        const [{ loadBasic }, { loadLineShape }, { loadBlendPlugin }, { loadEmittersPluginSimple }, { loadEmittersShapeSquare }, { loadSoundsPlugin }, { loadRotateUpdater }, { loadDestroyUpdater }, { loadLifeUpdater }, { loadStrokeColorUpdater },] = await Promise.all([
-            import("@tsparticles/basic"),
-            import("@tsparticles/shape-line"),
-            import("@tsparticles/plugin-blend"),
-            import("@tsparticles/plugin-emitters/plugin"),
-            import("@tsparticles/plugin-emitters-shape-square"),
-            import("@tsparticles/plugin-sounds"),
-            import("@tsparticles/updater-rotate"),
-            import("@tsparticles/updater-destroy"),
-            import("@tsparticles/updater-life"),
-            import("@tsparticles/updater-stroke-color"),
-        ]);
+        const loadEmittersForFireworks = async (e) => {
+            await loadEmittersPluginSimple(e);
+            await loadEmittersShapeSquare(e);
+        };
         await Promise.all([
             loadBasic(e),
             loadLineShape(e),
             loadBlendPlugin(e),
-            (async () => {
-                await loadEmittersPluginSimple(e);
-                await loadEmittersShapeSquare(e);
-            })(),
+            loadEmittersForFireworks(e),
             loadSoundsPlugin(e),
             loadRotateUpdater(e),
             loadDestroyUpdater(e),
             loadLifeUpdater(e),
-            loadStrokeColorUpdater(e),
+            loadPaintUpdater(e),
         ]);
     });
-    initializing = false;
-    initialized = true;
 }
-function getOptions(options, canvas) {
-    const identity = 1;
-    return {
-        detectRetina: true,
-        background: {
-            color: options.background,
-        },
-        blend: {
-            enable: true,
-            mode: "lighter",
-        },
-        fullScreen: {
-            enable: !canvas,
-        },
-        fpsLimit: 60,
-        emitters: {
-            direction: MoveDirection.top,
-            life: {
-                count: 0,
-                duration: 0.1,
-                delay: 0.1,
-            },
-            rate: {
-                delay: isNumber(options.rate)
-                    ? identity / options.rate
-                    : { min: identity / getRangeMin(options.rate), max: identity / getRangeMax(options.rate) },
-                quantity: 1,
-            },
-            size: {
-                width: 100,
-                height: 0,
-            },
-            position: {
-                y: 100,
-                x: 50,
-            },
-        },
-        particles: {
-            number: {
-                value: 0,
-            },
-            stroke: {
-                color: {
-                    value: options.colors,
-                },
-                width: 2,
-            },
-            destroy: {
-                mode: "split",
-                bounds: {
-                    top: setRangeValue(options.minHeight),
-                },
-                split: {
-                    count: 1,
-                    factor: {
-                        value: 0.333333,
-                    },
-                    rate: {
-                        value: options.splitCount,
-                    },
-                    strokeColorOffset: {
-                        s: options.saturation,
-                        l: options.brightness,
-                    },
-                    particles: {
-                        group: "split",
-                        number: {
-                            value: 0,
-                        },
-                        opacity: {
-                            value: {
-                                min: 0.1,
-                                max: 1,
-                            },
-                            animation: {
-                                enable: true,
-                                speed: { min: 2, max: 4 },
-                                sync: true,
-                                startValue: StartValueType.max,
-                                destroy: DestroyType.min,
-                                count: 1,
-                            },
-                        },
-                        size: {
-                            value: { min: 5, max: 10 },
-                        },
-                        life: {
-                            count: 1,
-                            duration: {
-                                value: {
-                                    min: 0.5,
-                                    max: 1,
-                                },
-                            },
-                        },
-                        move: {
-                            decay: 0.05,
-                            enable: true,
-                            gravity: {
-                                enable: false,
-                            },
-                            speed: {
-                                min: 10,
-                                max: 25,
-                            },
-                            direction: "outside",
-                            outModes: OutMode.destroy,
-                        },
-                    },
-                },
-            },
-            life: {
-                count: 1,
-            },
-            shape: {
-                type: "line",
-                options: {
-                    line: {
-                        cap: "round",
-                    },
-                },
-            },
-            size: {
-                value: { min: 10, max: 20 },
-            },
-            rotate: {
-                path: true,
-            },
-            move: {
-                enable: true,
-                gravity: {
-                    acceleration: setRangeValue(options.gravity),
-                    enable: true,
-                    inverse: true,
-                    maxSpeed: 150,
-                },
-                speed: setRangeValue(options.speed),
-                outModes: {
-                    default: OutMode.destroy,
-                    top: OutMode.none,
-                },
-            },
-        },
-        sounds: {
-            enable: options.sounds,
-            events: [
-                {
-                    event: EventType.particleRemoved,
-                    filter: explodeSoundCheck,
-                    audio: [
-                        "https://particles.js.org/audio/explosion0.mp3",
-                        "https://particles.js.org/audio/explosion1.mp3",
-                        "https://particles.js.org/audio/explosion2.mp3",
-                    ],
-                },
-            ],
-            volume: 50,
-        },
-    };
-}
-async function getFireworksInstance(id, sourceOptions, canvas) {
-    await initPlugins(tsParticles);
-    const options = new FireworkOptions();
-    options.load(sourceOptions);
-    const particlesOptions = getOptions(options, canvas), container = await tsParticles.load({ id, element: canvas, options: particlesOptions });
-    if (!container) {
-        return;
+async function initPlugins(engine) {
+    if (initPromise) {
+        return initPromise;
     }
-    const { FireworksInstance } = await import("./FireworksInstance.js");
-    return new FireworksInstance(container);
+    initPromise = doInitPlugins(engine);
+    return initPromise;
 }
 export async function fireworks(idOrOptions, sourceOptions) {
+    await initPlugins(tsParticles);
     let id, options;
     if (isString(idOrOptions)) {
         id = idOrOptions;
@@ -234,14 +49,15 @@ export async function fireworks(idOrOptions, sourceOptions) {
         id = "fireworks";
         options = idOrOptions ?? {};
     }
-    return getFireworksInstance(id, options);
+    return getFireworksInstance(tsParticles, id, options);
 }
 fireworks.create = async (canvas, options) => {
-    const id = canvas.id || "fireworks";
-    return getFireworksInstance(id, options ?? {}, canvas);
+    await initPlugins(tsParticles);
+    const id = canvas?.id ?? "fireworks";
+    return getFireworksInstance(tsParticles, id, options ?? {}, canvas ?? undefined);
 };
 fireworks.init = async () => {
     await initPlugins(tsParticles);
 };
-fireworks.version = "4.0.0-beta.9";
+fireworks.version = "4.0.0";
 globalThis.fireworks = fireworks;

package/browser/fireworks.lazy.js

@@ -0,0 +1,64 @@
+import { isString, tsParticles } from "@tsparticles/engine/lazy";
+import { getFireworksInstance } from "./utils.js";
+let initPromise = null;
+async function doInitPlugins(engine) {
+    engine.checkVersion("4.0.0");
+    await engine.pluginManager.register(async (e) => {
+        const [{ loadBasic }, { loadLineShape }, { loadBlendPlugin }, { loadEmittersPluginSimple }, { loadEmittersShapeSquare }, { loadSoundsPlugin }, { loadRotateUpdater }, { loadDestroyUpdater }, { loadLifeUpdater }, { loadPaintUpdater },] = await Promise.all([
+            import("@tsparticles/basic/lazy"),
+            import("@tsparticles/shape-line"),
+            import("@tsparticles/plugin-blend"),
+            import("@tsparticles/plugin-emitters/plugin"),
+            import("@tsparticles/plugin-emitters-shape-square"),
+            import("@tsparticles/plugin-sounds"),
+            import("@tsparticles/updater-rotate/lazy"),
+            import("@tsparticles/updater-destroy/lazy"),
+            import("@tsparticles/updater-life/lazy"),
+            import("@tsparticles/updater-paint/lazy"),
+        ]), loadEmittersForFireworks = async (e) => {
+            await loadEmittersPluginSimple(e);
+            await loadEmittersShapeSquare(e);
+        };
+        await Promise.all([
+            loadBasic(e),
+            loadLineShape(e),
+            loadBlendPlugin(e),
+            loadEmittersForFireworks(e),
+            loadSoundsPlugin(e),
+            loadRotateUpdater(e),
+            loadDestroyUpdater(e),
+            loadLifeUpdater(e),
+            loadPaintUpdater(e),
+        ]);
+    });
+}
+async function initPlugins(engine) {
+    if (initPromise) {
+        return initPromise;
+    }
+    initPromise = doInitPlugins(engine);
+    return initPromise;
+}
+export async function fireworks(idOrOptions, sourceOptions) {
+    await initPlugins(tsParticles);
+    let id, options;
+    if (isString(idOrOptions)) {
+        id = idOrOptions;
+        options = sourceOptions ?? {};
+    }
+    else {
+        id = "fireworks";
+        options = idOrOptions ?? {};
+    }
+    return getFireworksInstance(tsParticles, id, options);
+}
+fireworks.create = async (canvas, options) => {
+    await initPlugins(tsParticles);
+    const id = canvas?.id ?? "fireworks";
+    return getFireworksInstance(tsParticles, id, options ?? {}, canvas ?? undefined);
+};
+fireworks.init = async () => {
+    await initPlugins(tsParticles);
+};
+fireworks.version = "4.0.0";
+globalThis.fireworks = fireworks;

package/browser/index.lazy.js

@@ -0,0 +1 @@
+export * from "./fireworks.lazy.js";

package/browser/types.js

@@ -0,0 +1 @@
+export {};