tsparticles 1.35.2 → 1.37.0

package/browser/Core/Container.js

@@ -1,3 +1,7 @@
+/**
+ * [[include:Container.md]]
+ * @packageDocumentation
+ */
 import { Canvas } from "./Canvas";
 import { Particles } from "./Particles";
 import { Retina } from "./Retina";
@@ -5,7 +9,19 @@ import { FrameManager } from "./FrameManager";
 import { Options } from "../Options/Classes/Options";
 import { animate, cancelAnimation, EventListeners, getRangeValue, Plugins } from "../Utils";
 import { Vector } from "./Particle/Vector";
+/**
+ * The object loaded into an HTML element, it'll contain options loaded and all data to let everything working
+ * [[include:Container.md]]
+ * @category Core
+ */
 export class Container {
+    /**
+     * This is the core class, create an instance to have a new working particles manager
+     * @constructor
+     * @param id the id to identify this instance
+     * @param sourceOptions the options to load
+     * @param presets all the presets to load with options
+     */
     constructor(id, sourceOptions, ...presets) {
         this.id = id;
         this.fpsLimit = 60;
@@ -23,6 +39,7 @@ export class Container {
         this.canvas = new Canvas(this);
         this.particles = new Particles(this);
         this.drawer = new FrameManager(this);
+        this.presets = presets;
         this.pathGenerator = {
             generate: () => {
                 const v = Vector.create(0, 0);
@@ -31,8 +48,10 @@ export class Container {
                 return v;
             },
             init: () => {
+                // nothing required
             },
             update: () => {
+                // nothing required
             },
         };
         this.interactivity = {
@@ -47,30 +66,28 @@ export class Container {
         this.plugins = new Map();
         this.drawers = new Map();
         this.density = 1;
+        /* tsParticles variables with default values */
         this._options = new Options();
         this.actualOptions = new Options();
-        for (const preset of presets) {
-            this._options.load(Plugins.getPreset(preset));
-        }
-        const shapes = Plugins.getSupportedShapes();
-        for (const type of shapes) {
-            const drawer = Plugins.getShapeDrawer(type);
-            if (drawer) {
-                this.drawers.set(type, drawer);
-            }
-        }
-        this._options.load(this._sourceOptions);
+        /* ---------- tsParticles - start ------------ */
         this.eventListeners = new EventListeners(this);
         if (typeof IntersectionObserver !== "undefined" && IntersectionObserver) {
             this.intersectionObserver = new IntersectionObserver((entries) => this.intersectionManager(entries));
         }
     }
+    /**
+     * The options used by the container, it's a full [[Options]] object
+     */
     get options() {
         return this._options;
     }
     get sourceOptions() {
         return this._sourceOptions;
     }
+    /**
+     * Starts animations and resume from pause
+     * @param force
+     */
     play(force) {
         const needsUpdate = this.paused || force;
         if (this.firstStart && !this.actualOptions.autoPlay) {
@@ -89,6 +106,9 @@ export class Container {
         }
         this.draw(needsUpdate || false);
     }
+    /**
+     * Pauses animations
+     */
     pause() {
         if (this.drawAnimationFrame !== undefined) {
             cancelAnimation()(this.drawAnimationFrame);
@@ -106,6 +126,9 @@ export class Container {
             this.paused = true;
         }
     }
+    /**
+     * Draws a frame
+     */
     draw(force) {
         let refreshTime = force;
         this.drawAnimationFrame = animate()((timestamp) => {
@@ -116,12 +139,29 @@ export class Container {
             this.drawer.nextFrame(timestamp);
         });
     }
+    /**
+     * Gets the animation status
+     * @returns `true` is playing, `false` is paused
+     */
     getAnimationStatus() {
         return !this.paused && !this.pageHidden;
     }
+    /**
+     * Customise path generation
+     * @deprecated Use the new setPath
+     * @param noiseOrGenerator the [[IMovePathGenerator]] object or a function that generates a [[Vector]] object from [[Particle]]
+     * @param init the [[IMovePathGenerator]] init function, if the first parameter is a generator function
+     * @param update the [[IMovePathGenerator]] update function, if the first parameter is a generator function
+     */
     setNoise(noiseOrGenerator, init, update) {
         this.setPath(noiseOrGenerator, init, update);
     }
+    /**
+     * Customise path generation
+     * @param pathOrGenerator the [[IMovePathGenerator]] object or a function that generates a [[Vector]] object from [[Particle]]
+     * @param init the [[IMovePathGenerator]] init function, if the first parameter is a generator function
+     * @param update the [[IMovePathGenerator]] update function, if the first parameter is a generator function
+     */
     setPath(pathOrGenerator, init, update) {
         if (!pathOrGenerator) {
             return;
@@ -147,6 +187,9 @@ export class Container {
             }
         }
     }
+    /**
+     * Destroys the current container, invalidating it
+     */
     destroy() {
         this.stop();
         this.canvas.destroy();
@@ -160,17 +203,35 @@ export class Container {
         }
         this.destroyed = true;
     }
+    /**
+     * @deprecated this method is deprecated, please use the exportImage method
+     * @param callback The callback to handle the image
+     */
     exportImg(callback) {
         this.exportImage(callback);
     }
+    /**
+     * Exports the current canvas image, `background` property of `options` won't be rendered because it's css related
+     * @param callback The callback to handle the image
+     * @param type The exported image type
+     * @param quality The exported image quality
+     */
     exportImage(callback, type, quality) {
         var _a;
         return (_a = this.canvas.element) === null || _a === void 0 ? void 0 : _a.toBlob(callback, type !== null && type !== void 0 ? type : "image/png", quality);
     }
+    /**
+     * Exports the current configuration using `options` property
+     * @returns a JSON string created from `options` property
+     */
     exportConfiguration() {
         return JSON.stringify(this.actualOptions, undefined, 2);
     }
+    /**
+     * Restarts the container, just a [[stop]]/[[start]] alias
+     */
     refresh() {
+        /* restart */
         this.stop();
         return this.start();
     }
@@ -178,6 +239,9 @@ export class Container {
         this._options = new Options();
         return this.refresh();
     }
+    /**
+     * Stops the container, opposite to `start`. Clears some resources and stops events.
+     */
     stop() {
         if (!this.started) {
             return;
@@ -202,11 +266,19 @@ export class Container {
         this.particles.linksColors = new Map();
         delete this.particles.grabLineColor;
         delete this.particles.linksColor;
+        this._sourceOptions = this._options;
     }
+    /**
+     * Loads the given theme, overriding the options
+     * @param name the theme name, if `undefined` resets the default options or the default theme
+     */
     async loadTheme(name) {
         this.currentTheme = name;
         await this.refresh();
     }
+    /**
+     * Starts the container, initializes what are needed to create animations and event handling
+     */
     async start() {
         if (this.started) {
             return;
@@ -306,12 +378,32 @@ export class Container {
         el.addEventListener("touchcancel", touchCancelHandler);
     }
     updateActualOptions() {
-        this.actualOptions.setResponsive(this.canvas.size.width, this.retina.pixelRatio, this._options);
+        this.actualOptions.responsive = [];
+        const newMaxWidth = this.actualOptions.setResponsive(this.canvas.size.width, this.retina.pixelRatio, this._options);
         this.actualOptions.setTheme(this.currentTheme);
+        if (this.responsiveMaxWidth != newMaxWidth) {
+            this.responsiveMaxWidth = newMaxWidth;
+            return true;
+        }
+        return false;
     }
     async init() {
+        this._options = new Options();
+        for (const preset of this.presets) {
+            this._options.load(Plugins.getPreset(preset));
+        }
+        const shapes = Plugins.getSupportedShapes();
+        for (const type of shapes) {
+            const drawer = Plugins.getShapeDrawer(type);
+            if (drawer) {
+                this.drawers.set(type, drawer);
+            }
+        }
+        /* options settings */
+        this._options.load(this._sourceOptions);
         this.actualOptions = new Options();
         this.actualOptions.load(this._options);
+        /* init canvas + particles */
         this.retina.init();
         this.canvas.init();
         this.updateActualOptions();

package/browser/Core/FrameManager.d.ts

@@ -1,6 +1,14 @@
 import type { Container } from "./Container";
+/**
+ * @category Core
+ */
 export declare class FrameManager {
     private readonly container;
     constructor(container: Container);
+    /**
+     * Handles the rAF method preparing the next animation frame to be drawn
+     * limiting it if it's needed by the current configuration
+     * @param timestamp
+     */
     nextFrame(timestamp: DOMHighResTimeStamp): void;
 }

package/browser/Core/FrameManager.js

@@ -1,11 +1,20 @@
+/**
+ * @category Core
+ */
 export class FrameManager {
     constructor(container) {
         this.container = container;
     }
+    /**
+     * Handles the rAF method preparing the next animation frame to be drawn
+     * limiting it if it's needed by the current configuration
+     * @param timestamp
+     */
     nextFrame(timestamp) {
         var _a;
         try {
             const container = this.container;
+            // FPS limit logic - if we are too fast, just draw without updating
             if (container.lastFrameTime !== undefined &&
                 timestamp < container.lastFrameTime + 1000 / container.fpsLimit) {
                 container.draw(false);

package/browser/Core/InteractionManager.d.ts

@@ -1,6 +1,9 @@
 import type { Container } from "./Container";
 import type { Particle } from "./Particle";
 import type { IDelta } from "./Interfaces";
+/**
+ * @category Core
+ */
 export declare class InteractionManager {
     private readonly container;
     private readonly externalInteractors;

package/browser/Core/InteractionManager.js

@@ -1,5 +1,8 @@
 import { Plugins } from "../Utils";
 import { InteractorType } from "../Enums";
+/**
+ * @category Core
+ */
 export class InteractionManager {
     constructor(container) {
         this.container = container;
@@ -28,6 +31,7 @@ export class InteractionManager {
         for (const interactor of this.externalInteractors) {
             interactor.reset(particle);
         }
+        /* interaction auto between particles */
         for (const interactor of this.particleInteractors) {
             if (interactor.isEnabled(particle)) {
                 interactor.interact(particle, delta);

package/browser/Core/Interfaces/Colors.d.ts

@@ -2,14 +2,28 @@ import type { SingleOrMultiple } from "../../Types";
 export interface IAlphaColor {
     a: number;
 }
+/**
+ * Color
+ * [[include:Color.md]]
+ * @category Interfaces
+ */
 export interface IColor {
+    /**
+     * Color value, can be a single or an array of [[IValueColor]], [[IRgb]], [[IHsl]] or string
+     */
     value: SingleOrMultiple<IValueColor | IRgb | IHsl | IHsv | SingleOrMultiple<string>>;
 }
+/**
+ * @category Interfaces
+ */
 export interface IHsl {
     h: number;
     s: number;
     l: number;
 }
+/**
+ * @category Interfaces
+ */
 export interface IHsla extends IHsl, IAlphaColor {
 }
 export interface IHsv {
@@ -19,13 +33,22 @@ export interface IHsv {
 }
 export interface IHsva extends IHsv, IAlphaColor {
 }
+/**
+ * @category Interfaces
+ */
 export interface IRgb {
     r: number;
     g: number;
     b: number;
 }
+/**
+ * @category Interfaces
+ */
 export interface IRgba extends IRgb, IAlphaColor {
 }
+/**
+ * @category Interfaces
+ */
 export interface IValueColor {
     rgb?: IRgb;
     hsl?: IHsl;

package/browser/Core/Interfaces/IAttract.d.ts

@@ -1,4 +1,7 @@
 import type { IParticle } from "./IParticle";
+/**
+ * @category Interfaces
+ */
 export interface IAttract {
     particles: IParticle[];
     finish?: boolean;

package/browser/Core/Interfaces/IBounds.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Interfaces
+ */
 export interface IBounds {
     bottom: number;
     left: number;

package/browser/Core/Interfaces/IBubble.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Interfaces
+ */
 export interface IBubble {
     clicking?: boolean;
     durationEnd?: boolean;

package/browser/Core/Interfaces/IBubbleParticleData.d.ts

@@ -1,4 +1,7 @@
 import type { IHsl } from "./Colors";
+/**
+ * @category Interfaces
+ */
 export interface IBubbleParticleData {
     inRange: boolean;
     opacity?: number;

package/browser/Core/Interfaces/IContainerInteractivity.d.ts

@@ -1,4 +1,7 @@
 import type { IMouseData } from "./IMouseData";
+/**
+ * @category Interfaces
+ */
 export interface IContainerInteractivity {
     element?: HTMLElement | Window | Node | null;
     status?: string;

package/browser/Core/Interfaces/IContainerPlugin.d.ts

@@ -5,6 +5,9 @@ import type { RecursivePartial } from "../../Types";
 import type { IOptions } from "../../Options/Interfaces/IOptions";
 import type { IDelta } from "./IDelta";
 import type { IColor } from "./Colors";
+/**
+ * @category Interfaces
+ */
 export interface IContainerPlugin {
     clickPositionValid?: (position: ICoordinates) => boolean;
     draw?: (context: CanvasRenderingContext2D, delta: IDelta) => void;

package/browser/Core/Interfaces/ICoordinates.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Interfaces
+ */
 export interface ICoordinates {
     x: number;
     y: number;

package/browser/Core/Interfaces/IDelta.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Interfaces
+ */
 export interface IDelta {
     value: number;
     factor: number;

package/browser/Core/Interfaces/IDimension.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Interfaces
+ */
 export interface IDimension {
     width: number;
     height: number;

package/browser/Core/Interfaces/IExternalInteractor.d.ts

@@ -1,5 +1,8 @@
 import type { IInteractor } from "./IInteractor";
 import type { IDelta } from "./IDelta";
+/**
+ * @category Interfaces
+ */
 export interface IExternalInteractor extends IInteractor {
     isEnabled(): boolean;
     interact(delta: IDelta): void;

package/browser/Core/Interfaces/IInteractor.d.ts

@@ -1,5 +1,8 @@
 import type { Particle } from "../Particle";
 import type { InteractorType } from "../../Enums";
+/**
+ * @category Interfaces
+ */
 export interface IInteractor {
     type: InteractorType;
     reset(particle: Particle): void;

package/browser/Core/Interfaces/IMouseData.d.ts

@@ -1,4 +1,7 @@
 import type { ICoordinates } from "./ICoordinates";
+/**
+ * @category Interfaces
+ */
 export interface IMouseData {
     clickPosition?: ICoordinates;
     position?: ICoordinates;

package/browser/Core/Interfaces/IMovePathGenerator.d.ts

@@ -1,6 +1,9 @@
 import type { Container } from "../Container";
 import type { Particle } from "../Particle";
 import { Vector } from "../Particle/Vector";
+/**
+ * @category Interfaces
+ */
 export interface IMovePathGenerator {
     generate: (particle: Particle) => Vector;
     init: (container: Container) => void;

package/browser/Core/Interfaces/IParticle.d.ts

@@ -12,6 +12,9 @@ import type { IParticleGradientAnimation } from "./IParticleGradientAnimation";
 import type { IParticleRetinaProps } from "./IParticleRetinaProps";
 import type { IParticleRoll } from "./IParticleRoll";
 import type { IParticleWobble } from "./IParticleWobble";
+/**
+ * @category Interfaces
+ */
 export interface IParticle {
     misplaced: boolean;
     randomIndexData?: number;

package/browser/Core/Interfaces/IParticleValueAnimation.d.ts

@@ -1,4 +1,7 @@
 import type { AnimationStatus } from "../../Enums";
+/**
+ * @category Interfaces
+ */
 export interface IParticleValueAnimation<T> {
     enable: boolean;
     status?: AnimationStatus;

package/browser/Core/Interfaces/IParticlesInteractor.d.ts

@@ -1,6 +1,9 @@
 import type { Particle } from "../Particle";
 import type { IInteractor } from "./IInteractor";
 import type { IDelta } from "./IDelta";
+/**
+ * @category Interfaces
+ */
 export interface IParticlesInteractor extends IInteractor {
     isEnabled(particle: Particle): boolean;
     interact(particle: Particle, delta: IDelta): void;

package/browser/Core/Interfaces/IPlugin.d.ts

@@ -1,8 +1,16 @@
+/**
+ * [[include:Plugins.md]]
+ * @packageDocumentation
+ */
 import type { Container } from "../Container";
 import type { IContainerPlugin } from "./IContainerPlugin";
 import type { IOptions } from "../../Options/Interfaces/IOptions";
 import type { RecursivePartial } from "../../Types";
 import type { Options } from "../../Options/Classes/Options";
+/**
+ * [[include:Plugins.md]]
+ * @category Interfaces
+ */
 export interface IPlugin {
     readonly id: string;
     needsPlugin(options?: RecursivePartial<IOptions>): boolean;

package/browser/Core/Interfaces/IRepulse.d.ts

@@ -1,4 +1,7 @@
 import type { IParticle } from "./IParticle";
+/**
+ * @category Interfaces
+ */
 export interface IRepulse {
     particles: IParticle[];
     finish?: boolean;

package/browser/Core/Interfaces/IShapeDrawer.d.ts

@@ -1,4 +1,7 @@
 import type { ShapeDrawerAfterEffectFunction, ShapeDrawerDestroyFunction, ShapeDrawerDrawFunction, ShapeDrawerInitFunction, ShapeDrawerLoadFunction, ShapeDrawerParticleInitFunction, ShapeDrawerSidesCountFunction } from "../../Types";
+/**
+ * @category Interfaces
+ */
 export interface IShapeDrawer {
     getSidesCount?: ShapeDrawerSidesCountFunction;
     init?: ShapeDrawerInitFunction;

package/browser/Core/Interfaces/IShapeValues.d.ts

@@ -1,5 +1,8 @@
 import type { IParticles } from "../../Options/Interfaces/Particles/IParticles";
 import type { RecursivePartial } from "../../Types";
+/**
+ * @category Options
+ */
 export interface IShapeValues {
     close?: boolean;
     fill?: boolean;

package/browser/Core/Loader.d.ts

@@ -3,12 +3,72 @@ import type { IOptions } from "../Options/Interfaces/IOptions";
 import type { RecursivePartial } from "../Types";
 import type { Particle } from "./Particle";
 import type { SingleOrMultiple } from "../Types";
+interface LoaderParams {
+    element?: HTMLElement;
+    index?: number;
+    options?: SingleOrMultiple<RecursivePartial<IOptions>>;
+    tagId?: string;
+}
+interface RemoteLoaderParams {
+    element?: HTMLElement;
+    index?: number;
+    tagId?: string;
+    url?: SingleOrMultiple<string>;
+}
+/**
+ * Main class for creating the [[Container]] objects
+ * @category Core
+ */
 export declare class Loader {
+    /**
+     * All the [[Container]] objects loaded
+     */
     static dom(): Container[];
+    /**
+     * Retrieves a [[Container]] from all the objects loaded
+     * @param index the object index
+     */
     static domItem(index: number): Container | undefined;
-    static load(tagId: string, options?: SingleOrMultiple<RecursivePartial<IOptions>>, index?: number): Promise<Container | undefined>;
-    static set(id: string, domContainer: HTMLElement, options?: SingleOrMultiple<RecursivePartial<IOptions>>, index?: number): Promise<Container | undefined>;
-    static loadJSON(tagId: string, jsonUrl: SingleOrMultiple<string>, index?: number): Promise<Container | undefined>;
-    static setJSON(id: string, domContainer: HTMLElement, jsonUrl: SingleOrMultiple<string>, index?: number): Promise<Container | undefined>;
+    static loadOptions(params: LoaderParams): Promise<Container | undefined>;
+    static loadRemoteOptions(params: RemoteLoaderParams): Promise<Container | undefined>;
+    /**
+     * Loads the provided options to create a [[Container]] object.
+     * @param tagId the particles container element id
+     * @param options the options object to initialize the [[Container]]
+     * @param index if an options array is provided, this will retrieve the exact index of that array
+     */
+    static load(tagId: string | SingleOrMultiple<RecursivePartial<IOptions>>, options?: SingleOrMultiple<RecursivePartial<IOptions>> | number, index?: number): Promise<Container | undefined>;
+    /**
+     * Loads the provided options to create a [[Container]] object.
+     * @param id the particles container element id
+     * @param domContainer the dom container
+     * @param options the options object to initialize the [[Container]]
+     * @param index if an options array is provided, this will retrieve the exact index of that array
+     */
+    static set(id: string | HTMLElement, domContainer: HTMLElement | SingleOrMultiple<RecursivePartial<IOptions>>, options?: SingleOrMultiple<RecursivePartial<IOptions>> | number, index?: number): Promise<Container | undefined>;
+    /**
+     * Loads the provided json with a GET request. The content will be used to create a [[Container]] object.
+     * This method is async, so if you need a callback refer to JavaScript function `fetch`
+     * @param tagId the particles container element id
+     * @param jsonUrl the json path (or paths array) to use in the GET request
+     * @param index the index of the paths array, if a single path is passed this value is ignored
+     * @returns A Promise with the [[Container]] object created
+     */
+    static loadJSON(tagId: string | SingleOrMultiple<string>, jsonUrl?: SingleOrMultiple<string> | number, index?: number): Promise<Container | undefined>;
+    /**
+     * Loads the provided json with a GET request. The content will be used to create a [[Container]] object.
+     * This method is async, so if you need a callback refer to JavaScript function `fetch`
+     * @param id the particles container element id
+     * @param domContainer the container used to contains the particles
+     * @param jsonUrl the json path (or paths array) to use in the GET request
+     * @param index the index of the paths array, if a single path is passed this value is ignored
+     * @returns A Promise with the [[Container]] object created
+     */
+    static setJSON(id: string | HTMLElement, domContainer: HTMLElement | SingleOrMultiple<string>, jsonUrl: SingleOrMultiple<string> | (number | undefined), index?: number): Promise<Container | undefined>;
+    /**
+     * Adds an additional click handler to all the loaded [[Container]] objects.
+     * @param callback the function called after the click event is fired
+     */
     static setOnClickHandler(callback: (evt: Event, particles?: Particle[]) => void): void;
 }
+export {};