@tsparticles/ribbons 4.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Matteo Bruni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+[![banner](https://particles.js.org/images/banner2.png)](https://particles.js.org)
+
+# tsParticles Ribbons Bundle
+
+[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/ribbons/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/ribbons) [![npmjs](https://badge.fury.io/js/@tsparticles/ribbons.svg)](https://www.npmjs.com/package/@tsparticles/ribbons) [![npmjs](https://img.shields.io/npm/dt/@tsparticles/ribbons)](https://www.npmjs.com/package/@tsparticles/ribbons) [![GitHub Sponsors](https://img.shields.io/github/sponsors/matteobruni)](https://github.com/sponsors/matteobruni)
+
+[tsParticles](https://github.com/tsparticles/tsparticles) ribbons bundle to create animated ribbons effects with a single API.
+
+## Exposed API
+
+The package API is centered on `ribbons`.
+
+```ts
+import { ribbons } from "@tsparticles/ribbons";
+
+await ribbons(options);
+await ribbons("canvas-id", options);
+
+await ribbons.init();
+const fireOnCanvas = await ribbons.create(canvas, defaultOptions);
+await fireOnCanvas(options);
+
+console.log(ribbons.version);
+```
+
+## Installation
+
+```bash
+pnpm add @tsparticles/ribbons
+```
+
+## How to use it
+
+```ts
+import { ribbons } from "@tsparticles/ribbons";
+
+await ribbons({
+  count: 5,
+  spread: 0,
+  position: { x: 50, y: 0 },
+});
+```
+
+With advanced ribbon shape customization:
+
+```ts
+import { ribbons } from "@tsparticles/ribbons";
+
+await ribbons({
+  ribbonOptions: {
+    count: 70,
+    oscillationDistance: {
+      min: 120,
+      max: 170,
+    },
+  },
+});
+```
+
+## Options
+
+Main options:
+
+- `count` _Integer (default: 5)_
+- `angle` _Number (default: 90)_
+- `spread` _Number (default: 0)_
+- `drift` _Number (default: 0)_
+- `ticks` _Number (default: 200)_
+- `position` _Object_ (`x`/`y`, default 50/0)
+- `colors` _Array<String>_
+- `ribbonOptions` _Object_ (`particles.shape.options.ribbon`)
+  - Includes `darken: { enable: true, value: 30 }` by default
+- `scalar` _Number (default: 1)_
+- `zIndex` _Integer (default: 100)_
+- `disableForReducedMotion` _Boolean (default: true)_
+
+The `ribbons` bundle disables `roll`, `rotate`, `tilt`, and `wobble` on ribbon particles by default for better shape stability.
+The emitter uses a full-width top strip (`width: 100`, `height: 0`) and downward movement speed range (`4..6`) for a falling-from-top behavior.
+
+Deprecated aliases still accepted:
+
+- `particleCount` (use `count`)
+- `origin` (use `position`)

package/browser/IRibbonsOptions.js

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

package/browser/RibbonsOptions.js

@@ -0,0 +1,138 @@
+import { deepExtend, isArray, isNull, percentDenominator, } from "@tsparticles/engine";
+export class RibbonsOptions {
+    angle;
+    colors;
+    count;
+    disableForReducedMotion;
+    drift;
+    emitterSize;
+    position;
+    ribbonOptions;
+    scalar;
+    spread;
+    ticks;
+    zIndex;
+    constructor() {
+        this.angle = 90;
+        this.count = 5;
+        this.spread = 0;
+        this.drift = 0;
+        this.emitterSize = {
+            width: 100,
+            height: 0,
+        };
+        this.ticks = 200;
+        this.position = {
+            x: 50,
+            y: 0,
+        };
+        this.colors = ["#FF0055", "#00D1FF", "#FFD23F", "#61FF7E", "#B284FF"];
+        this.ribbonOptions = {
+            angle: 45,
+            darken: {
+                enable: true,
+                value: 30,
+            },
+            count: 60,
+            drag: 0.02,
+            mass: 1,
+            oscillationDistance: {
+                min: 100,
+                max: 140,
+            },
+            oscillationSpeed: {
+                min: 3,
+                max: 5,
+            },
+            particleDist: 8,
+            velocityInherit: {
+                min: 4,
+                max: 6,
+            },
+        };
+        this.scalar = 1;
+        this.zIndex = 100;
+        this.disableForReducedMotion = true;
+    }
+    get origin() {
+        return {
+            x: this.position.x / percentDenominator,
+            y: this.position.y / percentDenominator,
+        };
+    }
+    set origin(value) {
+        this.position.x = value.x * percentDenominator;
+        this.position.y = value.y * percentDenominator;
+    }
+    get particleCount() {
+        return this.count;
+    }
+    set particleCount(value) {
+        this.count = value;
+    }
+    load(data) {
+        if (isNull(data)) {
+            return;
+        }
+        if (data.angle !== undefined) {
+            this.angle = data.angle;
+        }
+        const count = data.count ?? data.particleCount;
+        if (count !== undefined) {
+            this.count = count;
+        }
+        if (data.spread !== undefined) {
+            this.spread = data.spread;
+        }
+        if (data.drift !== undefined) {
+            this.drift = data.drift;
+        }
+        if (data.ticks !== undefined) {
+            this.ticks = data.ticks;
+        }
+        if (data.emitterSize) {
+            if (data.emitterSize.width !== undefined) {
+                this.emitterSize.width = data.emitterSize.width;
+            }
+            if (data.emitterSize.height !== undefined) {
+                this.emitterSize.height = data.emitterSize.height;
+            }
+        }
+        const origin = data.origin;
+        if (origin && !data.position) {
+            data.position = {
+                x: origin.x === undefined ? undefined : origin.x * percentDenominator,
+                y: origin.y === undefined ? undefined : origin.y * percentDenominator,
+            };
+        }
+        const position = data.position;
+        if (position) {
+            if (position.x !== undefined) {
+                this.position.x = position.x;
+            }
+            if (position.y !== undefined) {
+                this.position.y = position.y;
+            }
+        }
+        if (data.colors !== undefined) {
+            if (isArray(data.colors)) {
+                this.colors = [...data.colors];
+            }
+            else {
+                this.colors = data.colors;
+            }
+        }
+        if (data.ribbonOptions !== undefined) {
+            this.ribbonOptions = deepExtend({}, data.ribbonOptions);
+        }
+        if (data.scalar !== undefined) {
+            this.scalar = data.scalar;
+        }
+        if (data.zIndex !== undefined) {
+            this.zIndex = data.zIndex;
+        }
+        if (data.disableForReducedMotion !== undefined) {
+            this.disableForReducedMotion = data.disableForReducedMotion;
+        }
+    }
+}

package/browser/RibbonsParams.js

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

package/browser/browser.js

@@ -0,0 +1,4 @@
+import { ribbons } from "./index.js";
+const globalObject = globalThis;
+globalObject.ribbons = ribbons;
+export * from "./index.js";

package/browser/bundle.js

@@ -0,0 +1,5 @@
+import { ribbons } from "./index.js";
+export * from "./index.js";
+export * from "@tsparticles/engine";
+const globalObject = globalThis;
+globalObject.ribbons = ribbons;

package/browser/index.js

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

package/browser/index.lazy.js

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

package/browser/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/browser/ribbons.js

@@ -0,0 +1,79 @@
+import { isString, tsParticles } from "@tsparticles/engine";
+import { loadBasic } from "@tsparticles/basic";
+import { loadEmittersPluginSimple } from "@tsparticles/plugin-emitters/plugin";
+import { loadEmittersShapeSquare } from "@tsparticles/plugin-emitters-shape-square";
+import { loadLifeUpdater } from "@tsparticles/updater-life";
+import { loadMotionPlugin } from "@tsparticles/plugin-motion";
+import { loadRibbonShape } from "@tsparticles/shape-ribbon";
+import { setRibbons } from "./utils.js";
+let initPromise = null;
+async function doInitPlugins(engine) {
+    engine.checkVersion("4.0.5");
+    await engine.pluginManager.register(async (e) => {
+        const emittersRegister = async (engine) => {
+            await loadEmittersPluginSimple(engine);
+            await loadEmittersShapeSquare(engine);
+        };
+        await Promise.all([
+            loadBasic(e),
+            loadMotionPlugin(e),
+            emittersRegister(e),
+            loadRibbonShape(e),
+            loadLifeUpdater(e),
+        ]);
+    });
+}
+async function initPlugins(engine) {
+    if (initPromise) {
+        return initPromise;
+    }
+    initPromise = doInitPlugins(engine);
+    return initPromise;
+}
+export async function ribbons(idOrOptions, ribbonsOptions) {
+    await initPlugins(tsParticles);
+    let options, id;
+    if (isString(idOrOptions)) {
+        id = idOrOptions;
+        options = ribbonsOptions ?? {};
+    }
+    else {
+        id = "ribbons";
+        options = idOrOptions ?? {};
+    }
+    return setRibbons(tsParticles, {
+        id,
+        options,
+    });
+}
+ribbons.create = async (canvas, options = {}) => {
+    await initPlugins(tsParticles);
+    const id = canvas?.getAttribute("id") ?? "ribbons";
+    canvas?.setAttribute("id", id);
+    await setRibbons(tsParticles, {
+        id,
+        canvas: canvas ?? undefined,
+        options,
+    });
+    return async (idOrOptions, subRibbonsOptions) => {
+        let subOptions, subId;
+        if (isString(idOrOptions)) {
+            subId = idOrOptions;
+            subOptions = subRibbonsOptions ?? options;
+        }
+        else {
+            subId = id;
+            subOptions = idOrOptions ?? {};
+        }
+        return setRibbons(tsParticles, {
+            id: subId,
+            canvas: canvas ?? undefined,
+            options: subOptions,
+        });
+    };
+};
+ribbons.init = async () => {
+    await initPlugins(tsParticles);
+};
+ribbons.version = "4.0.5";
+globalThis.ribbons = ribbons;

package/browser/ribbons.lazy.js

@@ -0,0 +1,80 @@
+import { isString, tsParticles } from "@tsparticles/engine/lazy";
+import { setRibbons } from "./utils.js";
+let initPromise = null;
+async function doInitPlugins(engine) {
+    engine.checkVersion("4.0.5");
+    await engine.pluginManager.register(async (e) => {
+        const [{ loadBasic }, { loadEmittersPluginSimple }, { loadEmittersShapeSquare }, { loadMotionPlugin }, { loadRibbonShape }, { loadLifeUpdater },] = await Promise.all([
+            import("@tsparticles/basic/lazy"),
+            import("@tsparticles/plugin-emitters/plugin/lazy"),
+            import("@tsparticles/plugin-emitters-shape-square/lazy"),
+            import("@tsparticles/plugin-motion/lazy"),
+            import("@tsparticles/shape-ribbon/lazy"),
+            import("@tsparticles/updater-life/lazy"),
+        ]), emittersRegister = async (engine) => {
+            await loadEmittersPluginSimple(engine);
+            await loadEmittersShapeSquare(engine);
+        };
+        await Promise.all([
+            loadBasic(e),
+            loadMotionPlugin(e),
+            emittersRegister(e),
+            loadRibbonShape(e),
+            loadLifeUpdater(e),
+        ]);
+    });
+}
+async function initPlugins(engine) {
+    if (initPromise) {
+        return initPromise;
+    }
+    initPromise = doInitPlugins(engine);
+    return initPromise;
+}
+export async function ribbons(idOrOptions, ribbonsOptions) {
+    await initPlugins(tsParticles);
+    let options, id;
+    if (isString(idOrOptions)) {
+        id = idOrOptions;
+        options = ribbonsOptions ?? {};
+    }
+    else {
+        id = "ribbons";
+        options = idOrOptions ?? {};
+    }
+    return setRibbons(tsParticles, {
+        id,
+        options,
+    });
+}
+ribbons.create = async (canvas, options = {}) => {
+    await initPlugins(tsParticles);
+    const id = canvas?.getAttribute("id") ?? "ribbons";
+    canvas?.setAttribute("id", id);
+    await setRibbons(tsParticles, {
+        id,
+        canvas: canvas ?? undefined,
+        options,
+    });
+    return async (idOrOptions, subRibbonsOptions) => {
+        let subOptions, subId;
+        if (isString(idOrOptions)) {
+            subId = idOrOptions;
+            subOptions = subRibbonsOptions ?? options;
+        }
+        else {
+            subId = id;
+            subOptions = idOrOptions ?? {};
+        }
+        return setRibbons(tsParticles, {
+            id: subId,
+            canvas: canvas ?? undefined,
+            options: subOptions,
+        });
+    };
+};
+ribbons.init = async () => {
+    await initPlugins(tsParticles);
+};
+ribbons.version = "4.0.5";
+globalThis.ribbons = ribbons;

package/browser/types.js

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

package/browser/utils.js

@@ -0,0 +1,195 @@
+import { RibbonsOptions } from "./RibbonsOptions.js";
+const sizeFactor = 8, emitterTop = 0, ids = new Map();
+export async function addEmitter(container, actualOptions) {
+    await container.addEmitter?.({
+        startCount: actualOptions.count,
+        position: {
+            x: actualOptions.position.x,
+            y: emitterTop,
+        },
+        shape: {
+            type: "square",
+        },
+        size: {
+            width: actualOptions.emitterSize.width,
+            height: actualOptions.emitterSize.height,
+        },
+        rate: {
+            delay: 0,
+            quantity: 0,
+        },
+        life: {
+            duration: 0.1,
+            count: 1,
+        },
+        particles: {
+            paint: {
+                fill: {
+                    color: {
+                        value: actualOptions.colors,
+                    },
+                    enable: true,
+                },
+            },
+            shape: {
+                type: "ribbon",
+                options: {
+                    ribbon: actualOptions.ribbonOptions,
+                },
+            },
+            life: {
+                count: 1,
+            },
+            size: {
+                value: sizeFactor * actualOptions.scalar,
+            },
+            move: {
+                direction: "bottom",
+                enable: true,
+                outModes: {
+                    top: "none",
+                    default: "destroy",
+                },
+                speed: {
+                    min: 4,
+                    max: 6,
+                },
+            },
+            roll: {
+                enable: false,
+            },
+            rotate: {
+                value: 0,
+                move: false,
+                animation: {
+                    enable: false,
+                },
+            },
+            tilt: {
+                enable: false,
+            },
+            wobble: {
+                enable: false,
+            },
+        },
+    });
+}
+export function convertOptions(actualOptions, params) {
+    return {
+        fullScreen: {
+            enable: !params.canvas,
+            zIndex: actualOptions.zIndex,
+        },
+        fpsLimit: 120,
+        particles: {
+            number: {
+                value: 0,
+            },
+            paint: {
+                fill: {
+                    color: {
+                        value: actualOptions.colors,
+                    },
+                    enable: true,
+                },
+            },
+            shape: {
+                type: "ribbon",
+                options: {
+                    ribbon: actualOptions.ribbonOptions,
+                },
+            },
+            size: {
+                value: sizeFactor * actualOptions.scalar,
+            },
+            links: {
+                enable: false,
+            },
+            life: {
+                count: 1,
+            },
+            move: {
+                direction: "bottom",
+                enable: true,
+                outModes: {
+                    top: "none",
+                    default: "destroy",
+                },
+                speed: {
+                    min: 4,
+                    max: 6,
+                },
+            },
+            roll: {
+                enable: false,
+            },
+            rotate: {
+                value: 0,
+                move: false,
+                animation: {
+                    enable: false,
+                },
+            },
+            tilt: {
+                enable: false,
+            },
+            wobble: {
+                enable: false,
+            },
+        },
+        motion: {
+            disable: actualOptions.disableForReducedMotion,
+        },
+        emitters: {
+            name: "ribbons",
+            startCount: actualOptions.count,
+            position: {
+                x: actualOptions.position.x,
+                y: emitterTop,
+            },
+            shape: {
+                type: "square",
+            },
+            size: {
+                width: actualOptions.emitterSize.width,
+                height: actualOptions.emitterSize.height,
+            },
+            rate: {
+                delay: 0,
+                quantity: 0,
+            },
+            life: {
+                duration: 0.1,
+                count: 1,
+            },
+        },
+    };
+}
+export async function setRibbons(engine, params) {
+    const actualOptions = new RibbonsOptions();
+    actualOptions.load(params.options);
+    let containerOrPromise = ids.get(params.id);
+    if (containerOrPromise instanceof Promise) {
+        await containerOrPromise;
+        containerOrPromise = ids.get(params.id);
+    }
+    const container = containerOrPromise;
+    if (container && !container.destroyed) {
+        const alias = container;
+        if ("addEmitter" in alias) {
+            await addEmitter(alias, actualOptions);
+            return container;
+        }
+    }
+    const create = async () => {
+        const particlesOptions = convertOptions(actualOptions, params), newContainer = await engine.load({
+            id: params.id,
+            element: params.canvas,
+            options: particlesOptions,
+        });
+        ids.set(params.id, newContainer);
+        return newContainer;
+    }, createPromise = create();
+    ids.set(params.id, createPromise);
+    return createPromise;
+}

package/cjs/IRibbonsOptions.js

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