From 93f926c0f5a1f844eafb06272d950ba38566e28f Mon Sep 17 00:00:00 2001 From: Matteo Bruni <176620+matteobruni@users.noreply.github.com> Date: Mon, 11 May 2026 19:58:12 +0200 Subject: [PATCH] docs: updated docs for better typedoc output --- bundles/confetti/src/ConfettiOptions.ts | 74 ++---- bundles/confetti/src/ConfettiParams.ts | 16 +- bundles/confetti/src/IConfettiOptions.ts | 68 ++---- bundles/confetti/src/confetti.lazy.ts | 24 +- bundles/confetti/src/confetti.ts | 24 +- bundles/confetti/src/index.lazy.ts | 4 +- bundles/confetti/src/index.ts | 4 +- bundles/confetti/src/types.ts | 11 +- bundles/confetti/src/utils.ts | 2 + bundles/fireworks/src/FireworkOptions.ts | 16 ++ bundles/fireworks/src/FireworksInstance.ts | 8 + bundles/fireworks/src/IFireworkOptions.ts | 11 + bundles/fireworks/src/fireworks.lazy.ts | 12 + bundles/fireworks/src/fireworks.ts | 12 + bundles/fireworks/src/index.lazy.ts | 1 + bundles/fireworks/src/index.ts | 1 + bundles/fireworks/src/types.ts | 1 + bundles/fireworks/src/utils.ts | 7 +- bundles/particles/src/IParticlesOptions.ts | 11 + bundles/particles/src/ParticlesInstance.ts | 8 + bundles/particles/src/index.lazy.ts | 1 + bundles/particles/src/index.ts | 1 + bundles/particles/src/particles.lazy.ts | 27 ++- bundles/particles/src/particles.ts | 27 ++- bundles/particles/src/types.ts | 1 + .../pjs/src/VincentGarreau/IParticlesJS.ts | 32 +++ bundles/pjs/src/VincentGarreau/particles.ts | 8 + bundles/pjs/src/marcbruederlin/Particles.ts | 27 ++- effects/bubble/src/BubbleDrawer.ts | 5 + effects/filter/src/FilterDrawer.ts | 14 ++ effects/filter/src/IFilterData.ts | 12 + effects/particles/src/ParticlesDrawer.ts | 41 +++- effects/shadow/src/ShadowDrawer.ts | 38 ++- effects/trail/src/TrailDrawer.ts | 40 +++- engine/src/Core/CanvasManager.ts | 7 + engine/src/Core/Container.ts | 37 ++- engine/src/Core/Engine.ts | 7 + engine/src/Core/Interfaces/Colors.ts | 6 + engine/src/Core/Interfaces/IBounds.ts | 7 +- .../Core/Interfaces/IBubbleParticleData.ts | 9 +- engine/src/Core/Interfaces/ICircleBouncer.ts | 6 + engine/src/Core/Interfaces/IColorManager.ts | 5 + .../src/Core/Interfaces/IContainerPlugin.ts | 40 +++- engine/src/Core/Interfaces/ICoordinates.ts | 14 ++ engine/src/Core/Interfaces/IDelta.ts | 5 +- engine/src/Core/Interfaces/IDimension.ts | 7 +- engine/src/Core/Interfaces/IDistance.ts | 3 + .../Core/Interfaces/IDrawParticleParams.ts | 3 + engine/src/Core/Interfaces/IEffectDrawer.ts | 3 + engine/src/Core/Interfaces/IPalette.ts | 16 ++ .../Core/Interfaces/IParticleColorStyle.ts | 3 + .../Core/Interfaces/IParticleHslAnimation.ts | 4 + engine/src/Core/Interfaces/IParticleLife.ts | 6 + .../Core/Interfaces/IParticleOpacityData.ts | 4 + .../Core/Interfaces/IParticleRetinaProps.ts | 6 + engine/src/Core/Interfaces/IParticleRoll.ts | 7 + .../Core/Interfaces/IParticleRotateData.ts | 3 + .../Interfaces/IParticleTransformValues.ts | 5 + .../src/Core/Interfaces/IParticleUpdater.ts | 11 + .../Interfaces/IParticleValueAnimation.ts | 18 +- engine/src/Core/Interfaces/IPlugin.ts | 5 + engine/src/Core/Interfaces/IRangeValue.ts | 3 + engine/src/Core/Interfaces/IShapeDrawData.ts | 3 + engine/src/Core/Interfaces/IShapeDrawer.ts | 1 + engine/src/Core/Interfaces/IShapeValues.ts | 6 +- .../src/Core/Interfaces/ISlowParticleData.ts | 3 + engine/src/Core/Particle.ts | 36 +++ engine/src/Core/ParticlesManager.ts | 68 +++++- engine/src/Core/RenderManager.ts | 24 ++ engine/src/Core/Retina.ts | 9 +- engine/src/Core/Utils/PluginManager.ts | 75 +++++- engine/src/Core/Utils/Ranges.ts | 33 ++- engine/src/Core/Utils/SpatialHashGrid.ts | 28 ++- engine/src/Core/Utils/Vectors.ts | 4 + engine/src/Enums/AnimationStatus.ts | 3 + engine/src/Enums/Directions/MoveDirection.ts | 15 +- .../src/Enums/Directions/OutModeDirection.ts | 5 + .../src/Enums/Directions/RotateDirection.ts | 7 +- engine/src/Enums/Modes/AnimationMode.ts | 5 + engine/src/Enums/Modes/LimitMode.ts | 3 + engine/src/Enums/Modes/OutMode.ts | 8 +- engine/src/Enums/Modes/PixelMode.ts | 5 +- engine/src/Enums/RangeType.ts | 3 + engine/src/Enums/Types/AlterType.ts | 3 + engine/src/Enums/Types/DestroyType.ts | 6 +- engine/src/Enums/Types/EasingType.ts | 44 ++++ engine/src/Enums/Types/EventType.ts | 13 ++ engine/src/Enums/Types/GradientType.ts | 4 + engine/src/Enums/Types/ParticleOutType.ts | 4 + engine/src/Enums/Types/StartValueType.ts | 6 +- engine/src/Options/Classes/AnimatableColor.ts | 6 + .../src/Options/Classes/AnimationOptions.ts | 10 + engine/src/Options/Classes/ColorAnimation.ts | 10 +- engine/src/Options/Classes/Options.ts | 26 ++- engine/src/Options/Classes/OptionsColor.ts | 6 + .../Classes/Particles/Effect/Effect.ts | 3 + .../Classes/Particles/Move/MoveAngle.ts | 9 +- .../Classes/Particles/Move/MoveGravity.ts | 9 + .../Classes/Particles/Move/OutModes.ts | 10 + .../Classes/Particles/Move/Path/MovePath.ts | 1 + .../Particles/Number/ParticlesDensity.ts | 1 + .../Particles/Opacity/OpacityAnimation.ts | 1 + .../Classes/Particles/Size/SizeAnimation.ts | 1 + .../Classes/Particles/ZIndex/ZIndex.ts | 1 + engine/src/Options/Classes/ValueWithRandom.ts | 5 + engine/src/Options/Interfaces/IAnimatable.ts | 3 + engine/src/Options/Interfaces/IAnimation.ts | 6 + .../src/Options/Interfaces/IColorAnimation.ts | 8 +- .../src/Options/Interfaces/IHslAnimation.ts | 3 + engine/src/Options/Interfaces/IOptions.ts | 6 + engine/src/Options/Interfaces/IResizeEvent.ts | 3 + .../Options/Interfaces/IValueWithRandom.ts | 3 + .../Particles/Bounce/IParticlesBounce.ts | 3 + .../Interfaces/Particles/Effect/IEffect.ts | 2 + .../Interfaces/Particles/Move/IMoveAngle.ts | 5 +- .../Interfaces/Particles/Move/IMoveCenter.ts | 1 + .../Interfaces/Particles/Move/IMoveGravity.ts | 5 + .../Interfaces/Particles/Move/IOutModes.ts | 6 + .../Interfaces/Particles/Move/ISpin.ts | 4 + .../Particles/Move/Path/IMovePath.ts | 3 +- .../Particles/Number/IParticlesDensity.ts | 3 +- .../Particles/Number/IParticlesNumberLimit.ts | 1 + .../Particles/Opacity/IOpacityAnimation.ts | 3 +- .../Particles/Size/ISizeAnimation.ts | 3 +- engine/src/Types/CanvasContextType.ts | 3 + engine/src/Types/CustomEventArgs.ts | 3 + engine/src/Types/CustomEventListener.ts | 3 + engine/src/Types/EasingFunction.ts | 3 + engine/src/Types/EngineInitializers.ts | 8 + engine/src/Types/ExportResult.ts | 4 + engine/src/Types/ISourceOptions.ts | 3 + engine/src/Types/PathOptions.ts | 3 + engine/src/Types/RangeValue.ts | 3 + engine/src/Types/RecursivePartial.ts | 1 + engine/src/Types/ShapeData.ts | 1 + engine/src/Types/SingleOrMultiple.ts | 1 + engine/src/Utils/ColorUtils.ts | 57 +++-- engine/src/Utils/EventDispatcher.ts | 26 ++- engine/src/Utils/LogUtils.ts | 10 +- engine/src/Utils/OptionsUtils.ts | 5 +- engine/src/Utils/Utils.ts | 39 ++-- engine/src/index.lazy.ts | 3 + engine/src/index.ts | 3 + .../external/attract/src/Attractor.ts | 8 + .../attract/src/Options/Classes/Attract.ts | 15 +- .../src/Options/Classes/AttractOptions.ts | 1 + .../src/Options/Interfaces/IAttract.ts | 9 +- interactions/external/attract/src/Types.ts | 8 +- interactions/external/attract/src/Utils.ts | 32 +-- .../external/attract/src/index.lazy.ts | 3 +- interactions/external/attract/src/index.ts | 3 +- interactions/external/bounce/src/Bouncer.ts | 8 + .../external/bounce/src/IRectSideResult.ts | 6 + .../bounce/src/Options/Classes/Bounce.ts | 3 + .../src/Options/Classes/BounceOptions.ts | 1 + .../bounce/src/Options/Interfaces/IBounce.ts | 2 + interactions/external/bounce/src/Types.ts | 6 + interactions/external/bounce/src/Utils.ts | 40 ++-- .../external/bounce/src/index.lazy.ts | 3 +- interactions/external/bounce/src/index.ts | 3 +- interactions/external/bubble/src/Bubbler.ts | 8 + interactions/external/bubble/src/Enums.ts | 8 +- .../external/bubble/src/Interfaces.ts | 14 +- .../bubble/src/Options/Classes/Bubble.ts | 5 +- .../bubble/src/Options/Classes/BubbleBase.ts | 16 +- .../bubble/src/Options/Classes/BubbleDiv.ts | 6 +- .../src/Options/Classes/BubbleOptions.ts | 1 + .../bubble/src/Options/Interfaces/IBubble.ts | 4 +- .../src/Options/Interfaces/IBubbleBase.ts | 9 +- .../src/Options/Interfaces/IBubbleDiv.ts | 3 +- interactions/external/bubble/src/Types.ts | 12 +- .../external/bubble/src/index.lazy.ts | 3 +- interactions/external/bubble/src/index.ts | 3 +- interactions/external/cannon/src/Cannoner.ts | 24 ++ .../cannon/src/Options/Classes/Cannon.ts | 17 ++ .../src/Options/Classes/CannonOptions.ts | 1 + .../cannon/src/Options/Interfaces/ICannon.ts | 5 + interactions/external/cannon/src/Types.ts | 3 + .../external/cannon/src/index.lazy.ts | 3 +- interactions/external/cannon/src/index.ts | 3 +- .../external/connect/src/Connector.ts | 6 + .../connect/src/Options/Classes/Connect.ts | 9 +- .../src/Options/Classes/ConnectLinks.ts | 5 +- .../src/Options/Classes/ConnectOptions.ts | 1 + .../src/Options/Interfaces/IConnect.ts | 6 +- .../src/Options/Interfaces/IConnectLinks.ts | 4 +- interactions/external/connect/src/Types.ts | 4 + interactions/external/connect/src/Utils.ts | 28 +-- .../external/connect/src/index.lazy.ts | 3 +- interactions/external/connect/src/index.ts | 3 +- .../external/destroy/src/Destroyer.ts | 8 + .../destroy/src/Options/Classes/Destroy.ts | 3 + .../src/Options/Classes/DestroyOptions.ts | 1 + .../src/Options/Interfaces/IDestroy.ts | 2 + interactions/external/destroy/src/Types.ts | 3 + interactions/external/destroy/src/Utils.ts | 8 +- .../external/destroy/src/index.lazy.ts | 3 +- interactions/external/destroy/src/index.ts | 3 +- interactions/external/drag/src/Dragger.ts | 21 ++ .../external/drag/src/Options/Classes/Drag.ts | 8 +- .../drag/src/Options/Classes/DragOptions.ts | 1 + interactions/external/drag/src/Types.ts | 3 + interactions/external/grab/src/Grabber.ts | 7 + .../external/grab/src/Options/Classes/Grab.ts | 7 +- .../grab/src/Options/Classes/GrabLinks.ts | 11 +- .../grab/src/Options/Classes/GrabOptions.ts | 1 + .../grab/src/Options/Interfaces/IGrab.ts | 5 +- .../grab/src/Options/Interfaces/IGrabLinks.ts | 7 +- interactions/external/grab/src/Types.ts | 4 + interactions/external/grab/src/Utils.ts | 11 +- .../parallax/src/Options/Classes/Parallax.ts | 7 +- .../src/Options/Classes/ParallaxOptions.ts | 1 + .../src/Options/Interfaces/IParallax.ts | 3 +- .../external/parallax/src/Parallaxer.ts | 7 + interactions/external/parallax/src/Types.ts | 3 + .../src/InteractivityParticleMaker.ts | 10 +- .../Classes/InteractivityParticleOptions.ts | 11 +- .../InteractivityParticleOptionsData.ts | 1 + .../IInteractivityParticleOptions.ts | 7 +- interactions/external/particle/src/Types.ts | 3 + interactions/external/pause/src/Pauser.ts | 7 + interactions/external/pop/src/Popper.ts | 7 + .../external/push/src/Options/Classes/Push.ts | 8 +- .../push/src/Options/Interfaces/IPush.ts | 7 +- interactions/external/push/src/Pusher.ts | 8 + .../remove/src/Options/Classes/Remove.ts | 5 +- .../remove/src/Options/Interfaces/IRemove.ts | 4 +- interactions/external/remove/src/Remover.ts | 8 + .../repulse/src/Options/Classes/Repulse.ts | 5 +- .../src/Options/Classes/RepulseBase.ts | 8 + .../repulse/src/Options/Classes/RepulseDiv.ts | 5 +- .../src/Options/Interfaces/IRepulse.ts | 4 +- .../src/Options/Interfaces/IRepulseBase.ts | 7 + .../src/Options/Interfaces/IRepulseDiv.ts | 3 +- interactions/external/repulse/src/Repulser.ts | 7 + interactions/external/repulse/src/Types.ts | 9 +- .../external/slow/src/Options/Classes/Slow.ts | 6 +- .../slow/src/Options/Interfaces/ISlow.ts | 5 +- interactions/external/slow/src/Slower.ts | 7 + .../trail/src/Options/Classes/Trail.ts | 9 +- .../trail/src/Options/Interfaces/ITrail.ts | 10 +- interactions/external/trail/src/TrailMaker.ts | 8 + interactions/external/trail/src/Types.ts | 3 + interactions/light/src/ExternalLighter.ts | 8 + .../light/src/Options/Classes/Light.ts | 5 + .../light/src/Options/Classes/LightArea.ts | 5 + .../src/Options/Classes/LightGradient.ts | 5 + .../light/src/Options/Classes/LightOptions.ts | 2 + .../light/src/Options/Classes/LightShadow.ts | 5 + .../light/src/Options/Interfaces/ILight.ts | 3 + .../src/Options/Interfaces/ILightArea.ts | 3 + .../src/Options/Interfaces/ILightGradient.ts | 3 + .../src/Options/Interfaces/ILightShadow.ts | 3 + interactions/light/src/ParticlesLighter.ts | 7 + interactions/light/src/Types.ts | 4 + interactions/light/src/Utils.ts | 17 +- .../particles/attract/src/Attractor.ts | 10 +- .../particles/collisions/src/Bounce.ts | 6 +- .../particles/collisions/src/Collider.ts | 9 + .../src/Options/Classes/Collisions.ts | 6 + .../src/Options/Classes/CollisionsAbsorb.ts | 1 + .../src/Options/Classes/CollisionsOverlap.ts | 2 + .../src/Options/Interfaces/ICollisions.ts | 6 + .../Options/Interfaces/ICollisionsAbsorb.ts | 2 + .../Options/Interfaces/ICollisionsOverlap.ts | 3 + .../particles/links/src/Interfaces.ts | 17 +- interactions/particles/links/src/Linker.ts | 8 + .../links/src/Options/Classes/Links.ts | 13 ++ .../links/src/Options/Classes/LinksShadow.ts | 7 +- .../src/Options/Classes/LinksTriangle.ts | 8 +- .../src/Options/Interfaces/ILinksShadow.ts | 6 +- .../src/Options/Interfaces/ILinksTriangle.ts | 7 +- interactions/particles/links/src/Types.ts | 13 ++ .../src/Options/Classes/ParticlesRepulse.ts | 9 +- .../Options/Interfaces/IParticlesRepulse.ts | 10 +- .../particles/repulse/src/Repulser.ts | 15 +- paths/branches/src/BranchesPathGenerator.ts | 18 ++ paths/brownian/src/BrownianPathGenerator.ts | 18 ++ paths/curlNoise/src/CurlNoiseGenerator.ts | 9 + paths/curlNoise/src/ICurlOptions.ts | 4 + paths/curves/src/CurvesPathGenerator.ts | 17 ++ .../fractalNoise/src/FractalNoiseGenerator.ts | 1 + paths/grid/src/GridPathGenerator.ts | 18 ++ paths/levy/src/LevyPathGenerator.ts | 18 ++ paths/perlinNoise/src/PerlinNoiseGenerator.ts | 1 + paths/polygon/src/PolygonPathGenerator.ts | 19 ++ paths/random/src/RandomPathGenerator.ts | 7 + .../simplexNoise/src/SimplexNoiseGenerator.ts | 1 + paths/spiral/src/SpiralParticle.ts | 11 +- paths/spiral/src/SpiralPathGenerator.ts | 19 ++ paths/svg/src/SVGPathGenerator.ts | 36 ++- paths/zigzag/src/ZigZagPathGenerator.ts | 37 ++- plugins/absorbers/src/AbsorberInstance.ts | 4 +- plugins/absorbers/src/AbsorbersInteractor.ts | 34 +++ .../absorbers/src/Options/Classes/Absorber.ts | 31 +++ .../src/Options/Classes/AbsorberSize.ts | 13 ++ .../src/Options/Interfaces/IAbsorberSize.ts | 3 + .../Options/Interfaces/IAbsorberSizeLimit.ts | 3 + plugins/absorbers/src/types.ts | 10 + .../src/Options/Classes/BackgroundMask.ts | 4 + .../Options/Classes/BackgroundMaskCover.ts | 14 ++ plugins/blend/src/types.ts | 15 ++ .../src/CanvasMaskPluginInstance.ts | 11 + .../src/Options/Classes/CanvasMask.ts | 31 +++ .../src/Options/Classes/CanvasMaskOverride.ts | 13 ++ .../src/Options/Interfaces/ICanvasMask.ts | 12 +- .../Options/Interfaces/ICanvasMaskOverride.ts | 5 +- .../Options/Interfaces/ICanvasMaskPixels.ts | 5 +- .../src/Options/Interfaces/IFontTextMask.ts | 1 + .../src/Options/Interfaces/IImageMask.ts | 4 +- .../src/Options/Interfaces/ITextMask.ts | 4 + .../src/Options/Interfaces/ITextMaskLine.ts | 1 + plugins/canvasMask/src/types.ts | 6 + plugins/colors/hex/src/HexColorManager.ts | 22 ++ plugins/colors/hsl/src/HslColorManager.ts | 24 +- plugins/colors/hsv/src/HsvColorManager.ts | 17 ++ plugins/colors/hwb/src/HwbColorManager.ts | 22 ++ plugins/colors/lab/src/LabColorManager.ts | 17 ++ plugins/colors/lch/src/LchColorManager.ts | 17 ++ plugins/colors/named/src/NamedColorManager.ts | 17 ++ plugins/colors/oklab/src/OklabColorManager.ts | 17 ++ plugins/colors/oklch/src/OklchColorManager.ts | 17 ++ plugins/colors/rgb/src/RgbColorManager.ts | 24 +- plugins/easings/back/src/index.ts | 3 +- plugins/easings/bounce/src/index.ts | 3 +- plugins/easings/circ/src/index.ts | 3 +- plugins/easings/cubic/src/index.ts | 3 +- plugins/easings/elastic/src/index.ts | 3 +- plugins/easings/expo/src/index.ts | 3 +- plugins/easings/gaussian/src/index.ts | 3 +- plugins/easings/linear/src/index.ts | 3 +- plugins/easings/quad/src/index.ts | 3 +- plugins/easings/quart/src/index.ts | 3 +- plugins/easings/quint/src/index.ts | 3 +- plugins/easings/sigmoid/src/index.ts | 3 +- plugins/easings/sine/src/index.ts | 3 +- plugins/easings/smoothstep/src/index.ts | 3 +- plugins/emitters/src/EmitterInstance.ts | 57 +++++ plugins/emitters/src/EmitterShapeBase.ts | 36 +++ plugins/emitters/src/EmittersInteractor.ts | 39 ++++ .../emitters/src/Enums/EmitterClickMode.ts | 4 + .../emitters/src/Options/Classes/Emitter.ts | 47 ++++ .../src/Options/Classes/EmitterLife.ts | 17 ++ .../src/Options/Classes/EmitterRate.ts | 11 + .../src/Options/Classes/EmitterSize.ts | 14 ++ .../src/Options/Interfaces/IEmitter.ts | 3 + .../src/Options/Interfaces/IEmitterShape.ts | 4 + .../Interfaces/IEmitterShapeReplace.ts | 3 + .../src/Options/Interfaces/IEmitterSize.ts | 4 +- .../src/Options/Interfaces/IEmitterSpawn.ts | 3 + plugins/emitters/src/types.ts | 22 ++ .../Classes/EmittersCanvasShapeOptions.ts | 28 +++ .../Interfaces/IEmittersCanvasShapeOptions.ts | 8 + plugins/emittersShapes/canvas/src/types.ts | 9 + .../Classes/EmittersPathShapeOptions.ts | 10 + .../Interfaces/IEmittersPathShapeOptions.ts | 2 + .../Classes/EmittersPolygonShapeOptions.ts | 13 ++ .../IEmittersPolygonShapeOptions.ts | 3 + .../exports/image/src/ExportImagePlugin.ts | 5 +- .../image/src/ExportImagePluginInstance.ts | 1 + plugins/exports/image/src/IExportImageData.ts | 3 + plugins/exports/image/src/index.ts | 3 +- plugins/exports/json/src/ExportJSONPlugin.ts | 5 +- .../json/src/ExportJSONPluginInstance.ts | 1 + plugins/exports/json/src/index.ts | 3 +- .../exports/video/src/ExportVideoPlugin.ts | 5 +- .../video/src/ExportVideoPluginInstance.ts | 1 + plugins/exports/video/src/IExportVideoData.ts | 4 + plugins/exports/video/src/index.ts | 3 +- .../infection/src/InfectionPluginInstance.ts | 8 + .../src/Options/Classes/Infection.ts | 5 + .../src/Options/Classes/InfectionStage.ts | 8 +- plugins/infection/src/Types.ts | 12 + plugins/interactivity/src/Enums/DivType.ts | 3 +- .../src/Enums/InteractivityDetect.ts | 3 +- .../interactivity/src/InteractionManager.ts | 20 ++ .../src/InteractivityConstants.ts | 9 + .../interactivity/src/InteractivityPlugin.ts | 3 +- .../src/InteractivityPluginInstance.ts | 18 ++ .../src/Interfaces/IExternalInteractor.ts | 1 + .../src/Interfaces/IInteractivityData.ts | 3 +- .../src/Interfaces/IInteractor.ts | 7 +- .../src/Interfaces/IMouseData.ts | 3 +- .../src/Interfaces/IParticleInteractorBase.ts | 6 +- .../src/Interfaces/IParticlesInteractor.ts | 1 + .../src/Options/Interfaces/Modes/IModeDiv.ts | 3 +- plugins/interactivity/src/types.ts | 22 ++ .../src/ManualParticlesPluginInstance.ts | 5 + .../src/Options/Classes/ManualParticle.ts | 2 + plugins/motion/src/MotionPluginInstance.ts | 6 + .../src/Options/Interfaces/IMotionReduce.ts | 3 +- plugins/motion/src/types.ts | 3 + plugins/move/src/IMovePathGenerator.ts | 7 +- plugins/move/src/MovePluginInstance.ts | 23 +- plugins/move/src/Types.ts | 18 +- .../poisson/src/Options/Classes/Poisson.ts | 5 + .../src/Options/Interfaces/IPoisson.ts | 5 + .../poisson/src/PoissonDiscPluginInstance.ts | 9 + .../src/Options/Classes/PolygonMask.ts | 9 + .../src/Options/Classes/PolygonMaskDraw.ts | 5 +- .../Options/Classes/PolygonMaskDrawStroke.ts | 7 +- .../src/Options/Classes/PolygonMaskInline.ts | 4 +- .../Options/Classes/PolygonMaskLocalSvg.ts | 5 +- .../src/Options/Classes/PolygonMaskMove.ts | 5 +- .../src/Options/Interfaces/IPolygonMask.ts | 9 + .../Options/Interfaces/IPolygonMaskDraw.ts | 5 +- .../Interfaces/IPolygonMaskDrawStroke.ts | 6 +- .../Options/Interfaces/IPolygonMaskInline.ts | 4 +- .../Interfaces/IPolygonMaskLocalSvg.ts | 5 +- .../Options/Interfaces/IPolygonMaskMove.ts | 5 +- .../polygonMask/src/PolygonMaskInstance.ts | 26 +++ plugins/polygonMask/src/pathseg.d.ts | 221 ++++++++++++++++++ plugins/polygonMask/src/types.ts | 5 + .../src/Options/Interfaces/IResponsive.ts | 1 + .../src/ResponsivePluginInstance.ts | 5 + plugins/sounds/src/Options/Classes/Sounds.ts | 5 + .../sounds/src/Options/Classes/SoundsEvent.ts | 5 + .../src/Options/Classes/SoundsVolume.ts | 4 + .../sounds/src/Options/Interfaces/ISounds.ts | 6 + .../src/Options/Interfaces/ISoundsAudio.ts | 3 + .../src/Options/Interfaces/ISoundsEvent.ts | 6 + .../src/Options/Interfaces/ISoundsIcon.ts | 6 + .../src/Options/Interfaces/ISoundsIcons.ts | 6 + .../src/Options/Interfaces/ISoundsMelody.ts | 4 + .../src/Options/Interfaces/ISoundsNote.ts | 3 + .../src/Options/Interfaces/ISoundsVolume.ts | 5 + plugins/sounds/src/SoundsPluginInstance.ts | 23 ++ plugins/sounds/src/types.ts | 21 ++ plugins/themes/src/Options/Classes/Theme.ts | 3 + .../src/Options/Classes/ThemeDefault.ts | 3 + plugins/themes/src/ThemesPluginInstance.ts | 13 ++ plugins/themes/src/types.ts | 18 ++ plugins/trail/src/Options/Classes/Trail.ts | 3 + .../trail/src/Options/Interfaces/ITrail.ts | 6 +- .../src/Options/Interfaces/ITrailFill.ts | 3 + plugins/trail/src/TrailPluginInstance.ts | 12 + plugins/zoom/src/Options/Classes/Zoom.ts | 3 + plugins/zoom/src/Options/Interfaces/IZoom.ts | 1 + plugins/zoom/src/types.ts | 3 + pnpm-lock.yaml | 12 - shapes/arrow/src/ArrowDrawer.ts | 10 + shapes/cards/src/CardValue.ts | 14 ++ shapes/cards/src/cards/CardDrawer.ts | 15 ++ shapes/circle/src/CircleDrawer.ts | 13 +- shapes/cog/src/CogDrawer.ts | 14 ++ shapes/emoji/src/EmojiDrawer.ts | 20 ++ shapes/emoji/src/IEmojiShape.ts | 8 + shapes/heart/src/HeartDrawer.ts | 5 + .../image/src/Options/Interfaces/IPreload.ts | 7 + shapes/image/src/Utils.ts | 1 + shapes/infinity/src/InfinityDrawer.ts | 5 + shapes/line/src/LineDrawer.ts | 8 +- shapes/matrix/src/MatrixDrawer.ts | 5 + shapes/path/src/PathDrawer.ts | 10 + shapes/polygon/src/PolygonDrawer.ts | 8 +- shapes/polygon/src/PolygonDrawerBase.ts | 12 +- shapes/polygon/src/TriangleDrawer.ts | 9 +- .../src/RoundedPolygonDrawer.ts | 16 +- shapes/rounded-rect/src/RoundedRectDrawer.ts | 10 + shapes/spiral/src/SpiralDrawer.ts | 10 + shapes/square/src/SquareDrawer.ts | 8 +- shapes/squircle/src/SquircleDrawer.ts | 10 + shapes/star/src/StarDrawer.ts | 16 +- shapes/text/src/TextDrawer.ts | 8 + updaters/destroy/src/DestroyUpdater.ts | 31 +++ .../destroy/src/Options/Classes/Destroy.ts | 10 + .../src/Options/Classes/DestroyBounds.ts | 9 + .../destroy/src/Options/Classes/Explode.ts | 8 + updaters/destroy/src/Options/Classes/Split.ts | 15 ++ .../src/Options/Classes/SplitFactor.ts | 2 + .../destroy/src/Options/Classes/SplitRate.ts | 2 + .../src/Options/Interfaces/IDestroy.ts | 6 +- .../src/Options/Interfaces/IDestroyBounds.ts | 5 + .../src/Options/Interfaces/IExplode.ts | 3 + .../destroy/src/Options/Interfaces/ISplit.ts | 10 + updaters/destroy/src/Types.ts | 15 ++ updaters/gradient/src/GradientUpdater.ts | 33 +++ .../src/Options/Classes/AnimatableGradient.ts | 9 + .../Classes/AnimatableGradientColor.ts | 9 + .../src/Options/Classes/GradientAngle.ts | 9 + .../Options/Classes/GradientAngleAnimation.ts | 12 + .../Options/Classes/GradientColorOpacity.ts | 8 + .../Classes/GradientColorOpacityAnimation.ts | 13 ++ .../src/Options/Interfaces/Gradients.ts | 13 ++ .../Options/Interfaces/IAnimatableGradient.ts | 3 + .../Options/Interfaces/IOptionsGradient.ts | 6 + updaters/gradient/src/Types.ts | 14 ++ updaters/life/src/LifeUpdater.ts | 24 ++ updaters/life/src/Options/Classes/Life.ts | 9 + .../life/src/Options/Classes/LifeDelay.ts | 7 + .../life/src/Options/Classes/LifeDuration.ts | 7 + updaters/life/src/Options/Interfaces/ILife.ts | 4 + .../life/src/Options/Interfaces/ILifeDelay.ts | 2 + .../src/Options/Interfaces/ILifeDuration.ts | 2 + updaters/life/src/Types.ts | 13 ++ updaters/orbit/src/Options/Classes/Orbit.ts | 12 + .../src/Options/Classes/OrbitRotation.ts | 8 +- .../orbit/src/Options/Interfaces/IOrbit.ts | 5 + updaters/orbit/src/OrbitUpdater.ts | 39 ++++ updaters/orbit/src/Types.ts | 17 ++ updaters/outModes/src/BounceOutMode.ts | 14 ++ updaters/outModes/src/IBounceData.ts | 8 + updaters/outModes/src/IOutModeManager.ts | 3 + updaters/outModes/src/OutOfCanvasUpdater.ts | 20 ++ updaters/paint/src/PaintUpdater.ts | 21 ++ updaters/roll/src/Options/Classes/Roll.ts | 12 + .../roll/src/Options/Classes/RollLight.ts | 8 + updaters/roll/src/Options/Interfaces/IRoll.ts | 7 + .../roll/src/Options/Interfaces/IRollLight.ts | 3 + updaters/roll/src/RollUpdater.ts | 28 +++ updaters/rotate/src/Options/Classes/Rotate.ts | 8 + .../src/Options/Classes/RotateAnimation.ts | 12 +- .../Options/Interfaces/IRotateAnimation.ts | 7 +- updaters/rotate/src/RotateUpdater.ts | 42 +++- updaters/size/src/SizeUpdater.ts | 23 ++ updaters/tilt/src/Options/Classes/Tilt.ts | 8 + .../tilt/src/Options/Classes/TiltAnimation.ts | 12 +- .../src/Options/Interfaces/ITiltAnimation.ts | 8 +- updaters/tilt/src/TiltUpdater.ts | 28 +++ .../twinkle/src/Options/Classes/Twinkle.ts | 7 + .../src/Options/Classes/TwinkleLinksValues.ts | 12 +- .../Options/Classes/TwinkleParticlesValues.ts | 13 +- .../Options/Interfaces/ITwinkleLinksValues.ts | 7 +- .../Interfaces/ITwinkleParticlesValues.ts | 8 +- updaters/twinkle/src/TwinkleUpdater.ts | 26 +++ updaters/wobble/src/Options/Classes/Wobble.ts | 9 + .../wobble/src/Options/Classes/WobbleSpeed.ts | 8 + .../wobble/src/Options/Interfaces/IWobble.ts | 4 + .../src/Options/Interfaces/IWobbleSpeed.ts | 3 + updaters/wobble/src/Types.ts | 8 +- websites/website/docs/fr/releases/index.md | 2 +- websites/website/package.json | 14 +- .../website/scripts/fix-palette-types.mjs | 83 ------- websites/website/typedoc.json | 165 ++----------- 534 files changed, 4724 insertions(+), 871 deletions(-) delete mode 100644 websites/website/scripts/fix-palette-types.mjs diff --git a/bundles/confetti/src/ConfettiOptions.ts b/bundles/confetti/src/ConfettiOptions.ts index 14946698562..26fc47ffcb6 100644 --- a/bundles/confetti/src/ConfettiOptions.ts +++ b/bundles/confetti/src/ConfettiOptions.ts @@ -12,93 +12,57 @@ import { } from "@tsparticles/engine"; import type { IConfettiOptions } from "./IConfettiOptions.js"; -/** - * - */ +/** Confetti options class */ export class ConfettiOptions implements IConfettiOptions, IOptionLoader { - /** - * - */ + /** Confetti angle */ angle: number; - /** - * - */ + /** Confetti colors */ colors: SingleOrMultiple; - /** - * - */ + /** Number of confetti particles to emit */ count: number; - /** - * - */ + /** Confetti decay rate */ decay: number; - /** - * - */ + /** Disables confetti for users who prefer reduced motion */ disableForReducedMotion: boolean; - /** - * - */ + /** Confetti drift offset */ drift: number; - /** - * - */ + /** Enables flat confetti */ flat: boolean; - /** - * - */ + /** Confetti gravity */ gravity: number; - /** - * - */ + /** Confetti position, in percent values */ position: ICoordinates; - /** - * - */ + /** Confetti size scalar */ scalar: number; - /** - * - */ + /** Per-shape options */ shapeOptions: ShapeData; - /** - * - */ + /** Confetti shape types */ shapes: SingleOrMultiple; - /** - * - */ + /** Confetti spread angle */ spread: number; - /** - * - */ + /** Confetti initial velocity */ startVelocity: number; - /** - * - */ + /** Confetti animation ticks */ ticks: number; - /** - * - */ + /** Confetti z-index */ zIndex: number; - /** - * - */ + /** Creates a new ConfettiOptions instance with default values */ constructor() { this.angle = 90; this.count = 50; @@ -156,7 +120,7 @@ export class ConfettiOptions implements IConfettiOptions, IOptionLoader): void { diff --git a/bundles/confetti/src/ConfettiParams.ts b/bundles/confetti/src/ConfettiParams.ts index e4e67ffc45d..e607bf1743a 100644 --- a/bundles/confetti/src/ConfettiParams.ts +++ b/bundles/confetti/src/ConfettiParams.ts @@ -1,22 +1,14 @@ import type { IConfettiOptions } from "./IConfettiOptions.js"; import type { RecursivePartial } from "@tsparticles/engine"; -/** - * The {@link confetti} parameter object definition - */ +/** The confetti parameter object definition */ export interface ConfettiParams { - /** - * - */ + /** The canvas element to use for the confetti animation */ canvas?: HTMLCanvasElement; - /** - * - */ + /** The unique identifier for the confetti canvas */ id: string; - /** - * - */ + /** The confetti options object */ options: RecursivePartial; } diff --git a/bundles/confetti/src/IConfettiOptions.ts b/bundles/confetti/src/IConfettiOptions.ts index 0ec34436c96..4790e437cce 100644 --- a/bundles/confetti/src/IConfettiOptions.ts +++ b/bundles/confetti/src/IConfettiOptions.ts @@ -1,47 +1,29 @@ import type { ICoordinates, SingleOrMultiple } from "@tsparticles/engine"; -/** - * - */ +/** Confetti options interface */ export interface IConfettiOptions { - /** - * - */ + /** Confetti emission angle */ angle: number; - /** - * - */ + /** Confetti colors */ colors: SingleOrMultiple; - /** - * - */ + /** Number of confetti particles */ count: number; - /** - * - */ + /** Confetti decay rate */ decay: number; - /** - * - */ + /** Disables confetti for users who prefer reduced motion */ disableForReducedMotion: boolean; - /** - * - */ + /** Confetti drift */ drift: number; - /** - * - */ + /** Enables flat confetti */ flat: boolean; - /** - * - */ + /** Confetti gravity */ gravity: number; /** @@ -54,43 +36,27 @@ export interface IConfettiOptions { */ particleCount: number; - /** - * - */ + /** Confetti position in percent */ position: ICoordinates; - /** - * - */ + /** Confetti size scalar */ scalar: number; - /** - * - */ + /** Per-shape options */ shapeOptions: Record>; - /** - * - */ + /** Confetti shape types */ shapes: SingleOrMultiple; - /** - * - */ + /** Confetti spread */ spread: number; - /** - * - */ + /** Confetti initial velocity */ startVelocity: number; - /** - * - */ + /** Number of animation ticks */ ticks: number; - /** - * - */ + /** Confetti z-index */ zIndex: number; } diff --git a/bundles/confetti/src/confetti.lazy.ts b/bundles/confetti/src/confetti.lazy.ts index fd1ee64b4fa..12f0284f63d 100644 --- a/bundles/confetti/src/confetti.lazy.ts +++ b/bundles/confetti/src/confetti.lazy.ts @@ -6,23 +6,15 @@ import { setConfetti } from "./utils.js"; declare const __VERSION__: string; declare global { - /** - * - */ + /** The global confetti function */ var confetti: ConfettiFunc & { - /** - * - * @param canvas - - * @param options - - * @returns the confetti function - */ + /** Creates a confetti animation bound to a specific canvas */ create: (canvas?: HTMLCanvasElement | null, options?: RecursivePartial) => Promise; + /** Initializes the confetti plugins */ init: () => Promise; - /** - * the confetti version number - */ + /** The confetti bundle version */ version: string; }; } @@ -30,7 +22,8 @@ declare global { let initPromise: Promise | null = null; /** - * @param engine - + * Initializes all required plugins for the confetti bundle + * @param engine - The engine to register plugins with * @returns the init plugins promise * @internal */ @@ -186,13 +179,12 @@ confetti.create = async ( }; }; +/** Initializes the confetti plugins without creating an animation */ confetti.init = async (): Promise => { await initPlugins(tsParticles); }; -/** - * - */ +/** The confetti bundle version */ confetti.version = __VERSION__; globalThis.confetti = confetti; diff --git a/bundles/confetti/src/confetti.ts b/bundles/confetti/src/confetti.ts index d493b2a6cb4..c019ad6df76 100644 --- a/bundles/confetti/src/confetti.ts +++ b/bundles/confetti/src/confetti.ts @@ -21,23 +21,15 @@ import { setConfetti } from "./utils.js"; declare const __VERSION__: string; declare global { - /** - * - */ + /** The global confetti function */ var confetti: ConfettiFunc & { - /** - * - * @param canvas - - * @param options - - * @returns the confetti function - */ + /** Creates a confetti animation bound to a specific canvas */ create: (canvas?: HTMLCanvasElement | null, options?: RecursivePartial) => Promise; + /** Initializes the confetti plugins */ init: () => Promise; - /** - * the confetti version number - */ + /** The confetti bundle version */ version: string; }; } @@ -45,7 +37,8 @@ declare global { let initPromise: Promise | null = null; /** - * @param engine - + * Initializes all required plugins for the confetti bundle + * @param engine - The engine to register plugins with * @returns the init plugins promise * @internal */ @@ -161,13 +154,12 @@ confetti.create = async ( }; }; +/** Initializes the confetti plugins without creating an animation */ confetti.init = async (): Promise => { await initPlugins(tsParticles); }; -/** - * - */ +/** The confetti bundle version */ confetti.version = __VERSION__; globalThis.confetti = confetti; diff --git a/bundles/confetti/src/index.lazy.ts b/bundles/confetti/src/index.lazy.ts index 60ed4cf0bed..ea6246636a2 100644 --- a/bundles/confetti/src/index.lazy.ts +++ b/bundles/confetti/src/index.lazy.ts @@ -1,9 +1,7 @@ import type { IConfettiOptions } from "./IConfettiOptions.js"; import type { RecursivePartial } from "@tsparticles/engine/lazy"; -/** - * - */ +/** Confetti options type */ export type ConfettiOptions = RecursivePartial; export * from "./confetti.lazy.js"; diff --git a/bundles/confetti/src/index.ts b/bundles/confetti/src/index.ts index dae33531c8c..ba83a1ded9c 100644 --- a/bundles/confetti/src/index.ts +++ b/bundles/confetti/src/index.ts @@ -1,9 +1,7 @@ import type { IConfettiOptions } from "./IConfettiOptions.js"; import type { RecursivePartial } from "@tsparticles/engine"; -/** - * - */ +/** Confetti options type */ export type ConfettiOptions = RecursivePartial; export * from "./confetti.js"; diff --git a/bundles/confetti/src/types.ts b/bundles/confetti/src/types.ts index bb5db7c6f72..4025b62d7a6 100644 --- a/bundles/confetti/src/types.ts +++ b/bundles/confetti/src/types.ts @@ -1,17 +1,10 @@ import type { Container, RecursivePartial } from "@tsparticles/engine"; import type { IConfettiOptions } from "./IConfettiOptions.js"; -/** - * - */ +/** Confetti function first parameter type */ export type ConfettiFirstParam = string | RecursivePartial; -/** - * - * @param idOrOptions - the id used for the canvas, or if not using two parameters, the animation configuration object - * @param confettiOptions - the animation configuration object, this parameter is mandatory only if providing an id - * @returns the container of the animation, or undefined if no canvas was found - */ +/** Confetti function type */ export type ConfettiFunc = ( idOrOptions: ConfettiFirstParam, confettiOptions?: RecursivePartial, diff --git a/bundles/confetti/src/utils.ts b/bundles/confetti/src/utils.ts index 34b67b8ff6a..4d6e840b229 100644 --- a/bundles/confetti/src/utils.ts +++ b/bundles/confetti/src/utils.ts @@ -12,6 +12,7 @@ const defaultGravity = 9.81, ids = new Map | undefined>(); /** + * Adds an emitter to the container for confetti particles * @param container - * @param actualOptions - * @param opacitySpeed - @@ -133,6 +134,7 @@ export async function addEmitter( } /** + * Converts confetti options to tsParticles source options * @param actualOptions - * @param params - * @param opacitySpeed - diff --git a/bundles/fireworks/src/FireworkOptions.ts b/bundles/fireworks/src/FireworkOptions.ts index 556fd4edd90..9ebfff90e08 100644 --- a/bundles/fireworks/src/FireworkOptions.ts +++ b/bundles/fireworks/src/FireworkOptions.ts @@ -9,18 +9,30 @@ import { } from "@tsparticles/engine"; import type { IFireworkOptions } from "./IFireworkOptions.js"; +/** Firework options class */ export class FireworkOptions implements IFireworkOptions, IOptionLoader { + /** Background color */ background: string; + /** Brightness offset for stroke colors */ brightness: RangeValue; + /** Firework colors */ colors: SingleOrMultiple; + /** Gravity acceleration */ gravity: RangeValue; + /** Minimum height before splitting */ minHeight: RangeValue; + /** Firework launch rate */ rate: RangeValue; + /** Saturation offset for stroke colors */ saturation: RangeValue; + /** Enables explosion sounds */ sounds; + /** Rocket speed */ speed: RangeValue; + /** Number of split particles per explosion */ splitCount: RangeValue; + /** Creates a new FireworkOptions instance with default values */ constructor() { this.background = "none"; this.brightness = { @@ -80,6 +92,10 @@ export class FireworkOptions implements IFireworkOptions, IOptionLoader): void { if (isNull(data)) { return; diff --git a/bundles/fireworks/src/FireworksInstance.ts b/bundles/fireworks/src/FireworksInstance.ts index c9fb073bf62..35e5f5a74f4 100644 --- a/bundles/fireworks/src/FireworksInstance.ts +++ b/bundles/fireworks/src/FireworksInstance.ts @@ -1,20 +1,28 @@ import type { Container } from "@tsparticles/engine"; +/** Fireworks instance wrapping a tsParticles container */ export class FireworksInstance { private readonly _container: Container; + /** + * Creates a new FireworksInstance + * @param container + */ constructor(container: Container) { this._container = container; } + /** Pauses the fireworks animation */ pause(): void { this._container.pause(); } + /** Resumes the fireworks animation */ play(): void { this._container.play(); } + /** Stops the fireworks animation */ stop(): void { this._container.stop(); } diff --git a/bundles/fireworks/src/IFireworkOptions.ts b/bundles/fireworks/src/IFireworkOptions.ts index c65eec25f45..5f5d747efe2 100644 --- a/bundles/fireworks/src/IFireworkOptions.ts +++ b/bundles/fireworks/src/IFireworkOptions.ts @@ -1,14 +1,25 @@ import type { RangeValue, SingleOrMultiple } from "@tsparticles/engine"; +/** Firework options interface */ export interface IFireworkOptions { + /** Background color */ background: string; + /** Brightness offset for stroke colors */ brightness: RangeValue; + /** Firework colors */ colors: SingleOrMultiple; + /** Gravity acceleration */ gravity: RangeValue; + /** Minimum height before splitting the rocket */ minHeight: RangeValue; + /** Firework launch rate */ rate: RangeValue; + /** Saturation offset for stroke colors */ saturation: RangeValue; + /** Enables explosion sounds */ sounds: boolean; + /** Rocket speed */ speed: RangeValue; + /** Number of split particles per explosion */ splitCount: RangeValue; } diff --git a/bundles/fireworks/src/fireworks.lazy.ts b/bundles/fireworks/src/fireworks.lazy.ts index d87f9ee1db7..fd29f83e870 100644 --- a/bundles/fireworks/src/fireworks.lazy.ts +++ b/bundles/fireworks/src/fireworks.lazy.ts @@ -9,17 +9,22 @@ declare const __VERSION__: string; let initPromise: Promise | null = null; declare global { + /** The global fireworks function */ var fireworks: FireworksFunc & { + /** Creates a fireworks animation bound to a specific canvas */ create: ( canvas?: HTMLCanvasElement | null, options?: RecursivePartial, ) => Promise; + /** Initializes the fireworks plugins */ init: () => Promise; + /** The fireworks bundle version */ version: string; }; } /** + * Initializes all required plugins for the fireworks bundle * @param engine - the engine to use for loading all plugins * @returns the promise of initialization * @internal @@ -110,6 +115,11 @@ export async function fireworks( return getFireworksInstance(tsParticles, id, options); } +/** + * Creates a fireworks animation on the given canvas + * @param canvas + * @param options + */ fireworks.create = async ( canvas?: HTMLCanvasElement | null, options?: RecursivePartial, @@ -121,10 +131,12 @@ fireworks.create = async ( return getFireworksInstance(tsParticles, id, options ?? {}, canvas ?? undefined); }; +/** Initializes the fireworks plugins without creating an animation */ fireworks.init = async (): Promise => { await initPlugins(tsParticles); }; +/** The fireworks bundle version */ fireworks.version = __VERSION__; globalThis.fireworks = fireworks; diff --git a/bundles/fireworks/src/fireworks.ts b/bundles/fireworks/src/fireworks.ts index c1e37d310ba..508a29739d3 100644 --- a/bundles/fireworks/src/fireworks.ts +++ b/bundles/fireworks/src/fireworks.ts @@ -19,17 +19,22 @@ declare const __VERSION__: string; let initPromise: Promise | null = null; declare global { + /** The global fireworks function */ var fireworks: FireworksFunc & { + /** Creates a fireworks animation bound to a specific canvas */ create: ( canvas?: HTMLCanvasElement | null, options?: RecursivePartial, ) => Promise; + /** Initializes the fireworks plugins */ init: () => Promise; + /** The fireworks bundle version */ version: string; }; } /** + * Initializes all required plugins for the fireworks bundle * @param engine - the engine to use for loading all plugins * @returns the promise of initialization * @internal @@ -97,6 +102,11 @@ export async function fireworks( return getFireworksInstance(tsParticles, id, options); } +/** + * Creates a fireworks animation on the given canvas + * @param canvas + * @param options + */ fireworks.create = async ( canvas?: HTMLCanvasElement | null, options?: RecursivePartial, @@ -108,10 +118,12 @@ fireworks.create = async ( return getFireworksInstance(tsParticles, id, options ?? {}, canvas ?? undefined); }; +/** Initializes the fireworks plugins without creating an animation */ fireworks.init = async (): Promise => { await initPlugins(tsParticles); }; +/** The fireworks bundle version */ fireworks.version = __VERSION__; globalThis.fireworks = fireworks; diff --git a/bundles/fireworks/src/index.lazy.ts b/bundles/fireworks/src/index.lazy.ts index d0281d9a772..77c6714bb99 100644 --- a/bundles/fireworks/src/index.lazy.ts +++ b/bundles/fireworks/src/index.lazy.ts @@ -1,6 +1,7 @@ import type { IFireworkOptions } from "./IFireworkOptions.js"; import type { RecursivePartial } from "@tsparticles/engine/lazy"; +/** Firework options type */ export type FireworkOptions = RecursivePartial; export * from "./fireworks.lazy.js"; diff --git a/bundles/fireworks/src/index.ts b/bundles/fireworks/src/index.ts index 5c6100fbccf..c53e2a683a6 100644 --- a/bundles/fireworks/src/index.ts +++ b/bundles/fireworks/src/index.ts @@ -1,6 +1,7 @@ import type { IFireworkOptions } from "./IFireworkOptions.js"; import type { RecursivePartial } from "@tsparticles/engine"; +/** Firework options type */ export type FireworkOptions = RecursivePartial; export * from "./fireworks.js"; diff --git a/bundles/fireworks/src/types.ts b/bundles/fireworks/src/types.ts index d39a7857deb..9bddca696eb 100644 --- a/bundles/fireworks/src/types.ts +++ b/bundles/fireworks/src/types.ts @@ -2,6 +2,7 @@ import type { FireworksInstance } from "./FireworksInstance.js"; import type { IFireworkOptions } from "./IFireworkOptions.js"; import type { RecursivePartial } from "@tsparticles/engine"; +/** Fireworks function type */ export type FireworksFunc = (( idOrOptions: string | RecursivePartial, sourceOptions?: RecursivePartial, diff --git a/bundles/fireworks/src/utils.ts b/bundles/fireworks/src/utils.ts index b90d9f495c9..65a2d252123 100644 --- a/bundles/fireworks/src/utils.ts +++ b/bundles/fireworks/src/utils.ts @@ -20,6 +20,10 @@ import type { IFireworkOptions } from "./IFireworkOptions.js"; const instances = new Map>(); +/** + * Checks if a particle supports explosion sounds + * @param args + */ export const explodeSoundCheck = (args: CustomEventArgs): boolean => { const data = args.data as { particle?: Particle } | undefined; @@ -27,7 +31,7 @@ export const explodeSoundCheck = (args: CustomEventArgs): boolean => { }; /** - * + * Converts firework options to tsParticles source options * @param options - * @param canvas - * @returns the options for the tsParticles instance @@ -200,6 +204,7 @@ export function getOptions(options: IFireworkOptions, canvas?: HTMLCanvasElement } /** + * Gets or creates a fireworks instance for the given id * @param engine - * @param id - * @param sourceOptions - diff --git a/bundles/particles/src/IParticlesOptions.ts b/bundles/particles/src/IParticlesOptions.ts index 25b30dccbd7..8cc0139c0fe 100644 --- a/bundles/particles/src/IParticlesOptions.ts +++ b/bundles/particles/src/IParticlesOptions.ts @@ -1,14 +1,25 @@ import type { RangeValue, SingleOrMultiple } from "@tsparticles/engine"; +/** Particles options interface */ export interface IParticlesOptions { + /** Enables particle collisions */ collisions?: boolean; + /** Particle color */ color?: string; + /** Number of particles */ count?: number; + /** Enables particle links */ links?: boolean; + /** Links color */ linksColor?: string; + /** Links distance */ linksLength?: number; + /** Particle opacity */ opacity?: number; + /** Particle radius */ radius?: RangeValue; + /** Particle shape */ shape?: SingleOrMultiple; + /** Particle speed */ speed?: RangeValue; } diff --git a/bundles/particles/src/ParticlesInstance.ts b/bundles/particles/src/ParticlesInstance.ts index 938233376ec..7e73ff14a53 100644 --- a/bundles/particles/src/ParticlesInstance.ts +++ b/bundles/particles/src/ParticlesInstance.ts @@ -1,20 +1,28 @@ import type { Container } from "@tsparticles/engine"; +/** Particles instance wrapper */ export class ParticlesInstance { private readonly _container: Container; + /** + * Creates a new ParticlesInstance + * @param container + */ constructor(container: Container) { this._container = container; } + /** Pause the particles animation */ pause(): void { this._container.pause(); } + /** Resume the particles animation */ play(): void { this._container.play(); } + /** Stop the particles animation */ stop(): void { this._container.stop(); } diff --git a/bundles/particles/src/index.lazy.ts b/bundles/particles/src/index.lazy.ts index a8dcc79dfc6..7cfc4856dcb 100644 --- a/bundles/particles/src/index.lazy.ts +++ b/bundles/particles/src/index.lazy.ts @@ -1,6 +1,7 @@ import type { IParticlesOptions } from "./IParticlesOptions.js"; import type { RecursivePartial } from "@tsparticles/engine/lazy"; +/** Particles options type */ export type ParticlesOptions = RecursivePartial; export * from "./particles.lazy.js"; diff --git a/bundles/particles/src/index.ts b/bundles/particles/src/index.ts index d86d76c1170..5a7b60380a7 100644 --- a/bundles/particles/src/index.ts +++ b/bundles/particles/src/index.ts @@ -1,6 +1,7 @@ import type { IParticlesOptions } from "./IParticlesOptions.js"; import type { RecursivePartial } from "@tsparticles/engine"; +/** Particles options type */ export type ParticlesOptions = RecursivePartial; export * from "./particles.js"; diff --git a/bundles/particles/src/particles.lazy.ts b/bundles/particles/src/particles.lazy.ts index 7f932684370..8527d13e64d 100644 --- a/bundles/particles/src/particles.lazy.ts +++ b/bundles/particles/src/particles.lazy.ts @@ -9,19 +9,23 @@ declare const __VERSION__: string; let initPromise: Promise | null = null; declare global { + /** The global particles function */ var particles: ParticlesFunc & { + /** Creates a particles animation bound to a specific canvas */ create: ( canvas?: HTMLCanvasElement | null, options?: RecursivePartial, ) => Promise; + /** Initializes the particles plugins */ init: () => Promise; + /** The particles bundle version */ version: string; }; } /** - * @param engine - - * @returns - + * Initializes all required plugins for the particles bundle + * @param engine - The engine to register plugins with */ async function doInitPlugins(engine: Engine): Promise { engine.checkVersion(__VERSION__); @@ -55,8 +59,9 @@ async function doInitPlugins(engine: Engine): Promise { } /** - * @param engine - - * @returns - + * Ensures plugins are initialized only once + * @param engine - The engine to register plugins with + * @returns The initialization promise */ async function initPlugins(engine: Engine): Promise { if (initPromise) { @@ -69,9 +74,10 @@ async function initPlugins(engine: Engine): Promise { } /** - * @param idOrOptions - - * @param sourceOptions - - * @returns - + * Creates a particles animation + * @param idOrOptions - The id or options for the animation + * @param sourceOptions - The animation options when providing an id + * @returns The particles instance */ export async function particles( idOrOptions?: string | RecursivePartial, @@ -92,6 +98,11 @@ export async function particles( return getParticlesInstance(tsParticles, id, options); } +/** + * Creates a particles animation on the given canvas + * @param canvas + * @param options + */ particles.create = async ( canvas?: HTMLCanvasElement | null, options?: RecursivePartial, @@ -103,10 +114,12 @@ particles.create = async ( return getParticlesInstance(tsParticles, id, options ?? {}, canvas ?? undefined); }; +/** Initializes the particles plugins without creating an animation */ particles.init = async (): Promise => { await initPlugins(tsParticles); }; +/** The particles bundle version */ particles.version = __VERSION__; globalThis.particles = particles; diff --git a/bundles/particles/src/particles.ts b/bundles/particles/src/particles.ts index f49829e5aa6..e8fd9fe4d84 100644 --- a/bundles/particles/src/particles.ts +++ b/bundles/particles/src/particles.ts @@ -13,19 +13,23 @@ declare const __VERSION__: string; let initPromise: Promise | null = null; declare global { + /** The global particles function */ var particles: ParticlesFunc & { + /** Creates a particles animation bound to a specific canvas */ create: ( canvas?: HTMLCanvasElement | null, options?: RecursivePartial, ) => Promise; + /** Initializes the particles plugins */ init: () => Promise; + /** The particles bundle version */ version: string; }; } /** - * @param engine - - * @returns - + * Initializes all required plugins for the particles bundle + * @param engine - The engine to register plugins with */ async function doInitPlugins(engine: Engine): Promise { engine.checkVersion(__VERSION__); @@ -48,8 +52,9 @@ async function doInitPlugins(engine: Engine): Promise { } /** - * @param engine - - * @returns - + * Ensures plugins are initialized only once + * @param engine - The engine to register plugins with + * @returns The initialization promise */ async function initPlugins(engine: Engine): Promise { if (initPromise) { @@ -62,9 +67,10 @@ async function initPlugins(engine: Engine): Promise { } /** - * @param idOrOptions - - * @param sourceOptions - - * @returns - + * Creates a particles animation + * @param idOrOptions - The id or options for the animation + * @param sourceOptions - The animation options when providing an id + * @returns The particles instance */ export async function particles( idOrOptions?: string | RecursivePartial, @@ -85,6 +91,11 @@ export async function particles( return getParticlesInstance(tsParticles, id, options); } +/** + * Creates a particles animation on the given canvas + * @param canvas + * @param options + */ particles.create = async ( canvas?: HTMLCanvasElement | null, options?: RecursivePartial, @@ -96,10 +107,12 @@ particles.create = async ( return getParticlesInstance(tsParticles, id, options ?? {}, canvas ?? undefined); }; +/** Initializes the particles plugins without creating an animation */ particles.init = async (): Promise => { await initPlugins(tsParticles); }; +/** The particles bundle version */ particles.version = __VERSION__; globalThis.particles = particles; diff --git a/bundles/particles/src/types.ts b/bundles/particles/src/types.ts index eaa6a40ce5f..8f769fcc8b2 100644 --- a/bundles/particles/src/types.ts +++ b/bundles/particles/src/types.ts @@ -2,6 +2,7 @@ import type { IParticlesOptions } from "./IParticlesOptions.js"; import type { ParticlesInstance } from "./ParticlesInstance.js"; import type { RecursivePartial } from "@tsparticles/engine"; +/** Particles function type */ export type ParticlesFunc = (( idOrOptions?: string | RecursivePartial, sourceOptions?: RecursivePartial, diff --git a/bundles/pjs/src/VincentGarreau/IParticlesJS.ts b/bundles/pjs/src/VincentGarreau/IParticlesJS.ts index 97535842e4e..1b4f42b4583 100644 --- a/bundles/pjs/src/VincentGarreau/IParticlesJS.ts +++ b/bundles/pjs/src/VincentGarreau/IParticlesJS.ts @@ -1,21 +1,32 @@ import type { Container, IHsl, IRgb, IValueColor, MoveDirection, OutMode } from "@tsparticles/engine"; import type { InteractivityDetect } from "@tsparticles/plugin-interactivity"; +/** + * @deprecated this interface is obsolete, please use the new tsParticles options format + */ export interface IParticlesJSOptions { + /** Interactivity configuration */ interactivity: { + /** Event detection mode */ detect_on: InteractivityDetect | keyof typeof InteractivityDetect; + /** Interaction events */ events: { + /** Click event configuration */ onclick: { enable: boolean; mode: string; }; + /** Hover event configuration */ onhover: { enable: boolean; mode: string; }; + /** Resize event enabled */ resize: boolean; }; + /** Interaction modes */ modes: { + /** Bubble mode configuration */ bubble: { distance: number; duration: number; @@ -23,28 +34,35 @@ export interface IParticlesJSOptions { size: number; speed: number; }; + /** Grab mode configuration */ grab: { distance: number; line_linked: { opacity: number; }; }; + /** Push mode configuration */ push: { particles_nb: number; }; + /** Remove mode configuration */ remove: { particles_nb: number; }; + /** Repulse mode configuration */ repulse: { distance: number; duration: number; }; }; }; + /** Particle configuration */ particles: { + /** Particle color */ color: { value: string | IRgb | IHsl | IValueColor; }; + /** Line linked (links) configuration */ line_linked: { color: string; distance: number; @@ -52,7 +70,9 @@ export interface IParticlesJSOptions { opacity: number; width: number; }; + /** Movement configuration */ move: { + /** Attract configuration */ attract: { enable: boolean; rotateX: number; @@ -66,14 +86,18 @@ export interface IParticlesJSOptions { speed: number; straight: boolean; }; + /** Number of particles */ number: { + /** Density configuration */ density: { enable: boolean; value_area: number; }; value: number; }; + /** Opacity configuration */ opacity: { + /** Opacity animation */ anim: { enable: boolean; opacity_min: number; @@ -83,23 +107,29 @@ export interface IParticlesJSOptions { random: boolean; value: number; }; + /** Shape configuration */ shape: { + /** Image shape options */ image: { height: number; replace_color?: boolean; src: string; width: number; }; + /** Polygon shape options */ polygon: { nb_sides: number; }; + /** Stroke configuration */ stroke: { color: string | IRgb | IHsl | IValueColor; width: number; }; type: string; }; + /** Size configuration */ size: { + /** Size animation */ anim: { enable: boolean; size_min: number; @@ -110,6 +140,7 @@ export interface IParticlesJSOptions { value: number; }; }; + /** Enables retina detection */ retina_detect: boolean; } @@ -123,6 +154,7 @@ export interface IParticlesJS { * @param tagId - the particles container element id * @param options - the options object to initialize the {@link Container} */ + // eslint-disable-next-line @typescript-eslint/no-deprecated (tagId: string, options: IParticlesJSOptions): Promise; /** diff --git a/bundles/pjs/src/VincentGarreau/particles.ts b/bundles/pjs/src/VincentGarreau/particles.ts index 1703b46fc7a..cb8274a1e32 100644 --- a/bundles/pjs/src/VincentGarreau/particles.ts +++ b/bundles/pjs/src/VincentGarreau/particles.ts @@ -5,6 +5,8 @@ import type { InteractivityEngine } from "@tsparticles/plugin-interactivity"; const defaultMinOpacity = 0, defaultMinSize = 0, speedFactor = 3, + /** Default particles.js options */ + // eslint-disable-next-line @typescript-eslint/no-deprecated defaultPjsOptions: IParticlesJSOptions = { particles: { number: { @@ -115,6 +117,10 @@ const defaultMinOpacity = 0, }, retina_detect: false, }, + /** + * Initializes particlesJS compatibility layer + * @param engine + */ initParticlesJS = ( engine: InteractivityEngine, ): { @@ -139,8 +145,10 @@ const defaultMinOpacity = 0, */ const particlesJS = async ( tagId: string, + // eslint-disable-next-line @typescript-eslint/no-deprecated options: RecursivePartial, ): Promise => { + // eslint-disable-next-line @typescript-eslint/no-deprecated const fixedOptions = deepExtend({}, defaultPjsOptions, options) as IParticlesJSOptions; return await engine.load({ diff --git a/bundles/pjs/src/marcbruederlin/Particles.ts b/bundles/pjs/src/marcbruederlin/Particles.ts index 10186d8c5e8..f5e40ca2548 100644 --- a/bundles/pjs/src/marcbruederlin/Particles.ts +++ b/bundles/pjs/src/marcbruederlin/Particles.ts @@ -7,19 +7,31 @@ import { tsParticles, } from "@tsparticles/engine"; -interface ResponsiveOptions { +/** Responsive options for Marc Bruederlin's particles */ +export interface ResponsiveOptions { + /** Viewport breakpoint */ breakpoint: number; + /** Options for this breakpoint */ options: ParticlesOptions; } -interface ParticlesOptions { +/** Marc Bruederlin's particles options */ +export interface ParticlesOptions { + /** Particle colors */ color: SingleOrMultiple; + /** Enables connecting particles with lines */ connectParticles: boolean; + /** Maximum number of particles */ maxParticles: number; + /** Minimum distance for connections */ minDistance: number; + /** Responsive breakpoints */ responsive: ResponsiveOptions[]; + /** CSS selector for the container */ selector: string; + /** Size variation */ sizeVariations: number; + /** Movement speed */ speed: number; } @@ -28,9 +40,17 @@ const linksMinDistance = 120, particlesMinCount = 100, sizeMinValue = 3; +/** Marc Bruederlin's particles compatibility class */ +/** Marc Bruederlin's particles compatibility class */ export class MBParticles { + /** The tsParticles container instance */ private _container?: Container; + /** Initializes a new particles instance with the given options */ + /** + * Initializes a new particles instance with the given options + * @param options + */ static init(options: RecursivePartial): MBParticles { const particles = new MBParticles(), selector = options.selector; @@ -108,18 +128,21 @@ export class MBParticles { return particles; } + /** Destroys the particles instance and cleans up resources */ destroy(): void { const container = this._container; container?.destroy(); } + /** Pauses the particle animation */ pauseAnimation(): void { const container = this._container; container?.pause(); } + /** Resumes the particle animation */ resumeAnimation(): void { const container = this._container; diff --git a/effects/bubble/src/BubbleDrawer.ts b/effects/bubble/src/BubbleDrawer.ts index 1c705e6652e..e345bffc2bf 100644 --- a/effects/bubble/src/BubbleDrawer.ts +++ b/effects/bubble/src/BubbleDrawer.ts @@ -2,7 +2,12 @@ import { type IEffectDrawer, type IShapeDrawData, defaultAngle, doublePI } from const bubbleFactor = 3; +/** Bubble effect drawer plugin */ export class BubbleDrawer implements IEffectDrawer { + /** + * Draws the bubble highlight after particle rendering + * @param data + */ drawAfter(data: IShapeDrawData): void { const { context, radius } = data, bubbleRadius = radius / bubbleFactor; diff --git a/effects/filter/src/FilterDrawer.ts b/effects/filter/src/FilterDrawer.ts index 746f02620e6..fc923e9bf52 100644 --- a/effects/filter/src/FilterDrawer.ts +++ b/effects/filter/src/FilterDrawer.ts @@ -1,13 +1,22 @@ import { type Container, type IEffectDrawer, type IShapeDrawData, isNull } from "@tsparticles/engine"; import type { FilterParticle } from "./FilterParticle.js"; +/** CSS filter effect drawer plugin */ export class FilterDrawer implements IEffectDrawer { + /** + * Restores the canvas context after filter rendering + * @param data + */ drawAfter(data: IShapeDrawData): void { const { context } = data; context.restore(); } + /** + * Applies CSS filters before particle rendering + * @param data + */ drawBefore(data: IShapeDrawData): void { const { context, particle } = data; @@ -41,6 +50,11 @@ export class FilterDrawer implements IEffectDrawer { `${blurString} ${brightnessString} ${contrastString} ${dropShadowString} ${grayscaleString} ${hueRotateString} ${invertString} ${opacityString} ${saturateString} ${sepiaString} ${urlString}`.trim(); } + /** + * Initializes filter-related particle properties + * @param _container + * @param particle + */ particleInit(_container: Container, particle: FilterParticle): void { const effectData = particle.effectData; diff --git a/effects/filter/src/IFilterData.ts b/effects/filter/src/IFilterData.ts index 42a4432d86d..38a6e6789a3 100644 --- a/effects/filter/src/IFilterData.ts +++ b/effects/filter/src/IFilterData.ts @@ -1,15 +1,27 @@ import type { IShapeValues } from "@tsparticles/engine"; +/** CSS filter effect data interface */ export interface IFilterData extends IShapeValues { + /** Blur filter value */ blur?: number | string; + /** Brightness filter value */ brightness?: number; + /** Contrast filter value */ contrast?: number; + /** Drop shadow filter value */ dropShadow?: string; + /** Grayscale filter value */ grayscale?: number; + /** Hue rotate filter value */ hueRotate?: number | string; + /** Invert filter value */ invert?: number; + /** Opacity filter value */ opacity?: number; + /** Saturate filter value */ saturate?: number; + /** Sepia filter value */ sepia?: number; + /** URL filter */ url?: string; } diff --git a/effects/particles/src/ParticlesDrawer.ts b/effects/particles/src/ParticlesDrawer.ts index 4746eeb6a1c..70202165981 100644 --- a/effects/particles/src/ParticlesDrawer.ts +++ b/effects/particles/src/ParticlesDrawer.ts @@ -16,35 +16,63 @@ const minSpawnRate = 0, defaultSpawnRate = 1, defaultSpawnQuantity = 1; -interface IParticlesRateData { +/** Particles spawn rate data */ +export interface IParticlesRateData { + /** Delay between spawns */ delay: RangeValue; + /** Number of particles per spawn */ quantity: RangeValue; } -interface ISpawnParticlesData { +/** Particles spawn data */ +export interface ISpawnParticlesData { + /** Particles options to spawn */ particles?: RecursivePartial; + /** Spawn rate configuration */ rate?: IParticlesRateData; } -interface IParticlesData extends IShapeValues { +/** + * Particles effect shape data + */ +export interface IParticlesData extends IShapeValues { + /** Spawn configuration */ spawn?: ISpawnParticlesData; } -type ParticlesParticle = Particle & { +/** + * Particles effect particle extension type + */ +export type ParticlesParticle = Particle & { + /** Effect data */ effectData?: IParticlesData; + /** Particles data for spawning */ particlesData?: IParticlesData; + /** Next spawn time */ particlesNextSpawn?: number; + /** Number of particles to spawn each time */ particlesSpawnQuantity?: number; + /** Spawn rate in ms */ particlesSpawnRate?: number; }; +/** Particles spawning effect drawer plugin */ export class ParticlesDrawer implements IEffectDrawer { + /** The particles container */ private readonly _container; + /** + * ParticlesDrawer constructor + * @param container + */ constructor(container: Container) { this._container = container; } + /** + * Spawns new particles after rendering + * @param data + */ drawAfter(data: IShapeDrawData): void { const { particle } = data, { _container: container } = this; @@ -71,6 +99,11 @@ export class ParticlesDrawer implements IEffectDrawer { } } + /** + * Initializes the particle spawner properties + * @param _container + * @param particle + */ particleInit(_container: Container, particle: ParticlesParticle): void { const effectData = particle.effectData, spawnRate = getRangeValue(effectData?.spawn?.rate?.delay ?? defaultSpawnRate); diff --git a/effects/shadow/src/ShadowDrawer.ts b/effects/shadow/src/ShadowDrawer.ts index 40e94d7d00a..489317d9ea1 100644 --- a/effects/shadow/src/ShadowDrawer.ts +++ b/effects/shadow/src/ShadowDrawer.ts @@ -17,34 +17,63 @@ import { const defaultShadowBlur = 0, defaultShadowOffsetValue = 0; -interface IShadowData extends IShapeValues { +/** + * Shadow effect shape data + */ +export interface IShadowData extends IShapeValues { + /** Shadow blur radius */ blur?: number; + /** Shadow color */ color?: IOptionsColor; + /** Shadow offset */ offset?: ICoordinates; } -type ShadowParticle = Particle & { +/** + * Shadow effect particle extension type + */ +export type ShadowParticle = Particle & { + /** Shadow effect data */ effectData?: IShadowData; + /** Shadow blur radius */ shadowBlur?: number; + /** Shadow color */ shadowColor?: IRgb; + /** Shadow offset */ shadowOffset?: ICoordinates; }; +/** Shadow effect drawer plugin */ export class ShadowDrawer implements IEffectDrawer { + /** The particles container */ private readonly _container; + /** The plugin manager */ private readonly _pluginManager; + /** + * ShadowDrawer constructor + * @param pluginManager + * @param container + */ constructor(pluginManager: PluginManager, container: Container) { this._pluginManager = pluginManager; this._container = container; } + /** + * Restores the canvas context after shadow rendering + * @param data + */ drawAfter(data: IShapeDrawData): void { const { context } = data; context.restore(); } + /** + * Applies shadow styles before particle rendering + * @param data + */ drawBefore(data: IShapeDrawData): void { const { particle, context } = data, { _container: container } = this, @@ -64,6 +93,11 @@ export class ShadowDrawer implements IEffectDrawer { context.shadowOffsetY = shadowOffset?.y ?? defaultShadowOffsetValue; } + /** + * Initializes shadow-related particle properties + * @param _container + * @param particle + */ particleInit(_container: Container, particle: ShadowParticle): void { const effectData = particle.effectData, shadowColor = OptionsColor.create(new OptionsColor(), effectData?.color); diff --git a/effects/trail/src/TrailDrawer.ts b/effects/trail/src/TrailDrawer.ts index 6eda6daef58..50453fe9b68 100644 --- a/effects/trail/src/TrailDrawer.ts +++ b/effects/trail/src/TrailDrawer.ts @@ -21,7 +21,8 @@ const minTrailLength = 3, loopTrailLengthOffset = 2, loopTrailLengthMinIndex = 0; -interface TrailStep { +/** Trail step data */ +export interface TrailStep { break: boolean; color: string | CanvasGradient | CanvasPattern; position: ICoordinates; @@ -33,21 +34,39 @@ interface TrailStep { }; } -interface ITrailData extends IShapeValues { +/** + * Trail effect shape data + */ +export interface ITrailData extends IShapeValues { + /** Whether the trail fades */ fade?: boolean; + /** Trail length */ length?: RangeValue; + /** Maximum trail width */ maxWidth?: RangeValue; + /** Minimum trail width */ minWidth?: RangeValue; + /** Whether to use transform data */ transform?: boolean; } -type TrailParticle = Particle & { +/** + * Trail effect particle extension type + */ +export type TrailParticle = Particle & { + /** Trail effect data */ effectData?: ITrailData; + /** Trail step history */ trail?: TrailStep[]; + /** Whether the trail fades */ trailFade?: boolean; + /** Trail length */ trailLength?: number; + /** Maximum trail width */ trailMaxWidth?: number; + /** Minimum trail width */ trailMinWidth?: number; + /** Whether to apply transform data */ trailTransform?: boolean; }; @@ -58,13 +77,23 @@ const defaultTransform = { d: 1, }; +/** Trail effect drawer plugin */ export class TrailDrawer implements IEffectDrawer { + /** The particles container */ private readonly _container; + /** + * TrailDrawer constructor + * @param container + */ constructor(container: Container) { this._container = container; } + /** + * Draws the particle trail after particle rendering + * @param data + */ drawAfter(data: IShapeDrawData): void { const { context, drawPosition, drawRadius, drawScale, particle, transformData } = data, container = this._container, @@ -157,6 +186,11 @@ export class TrailDrawer implements IEffectDrawer { context.restore(); } + /** + * Initializes trail-related particle properties + * @param container + * @param particle + */ particleInit(container: Container, particle: TrailParticle): void { particle.trail = []; diff --git a/engine/src/Core/CanvasManager.ts b/engine/src/Core/CanvasManager.ts index d41a2c391a3..1105c37250a 100644 --- a/engine/src/Core/CanvasManager.ts +++ b/engine/src/Core/CanvasManager.ts @@ -63,6 +63,7 @@ export class CanvasManager { */ element?: HTMLCanvasElement; + /** The render manager */ readonly render; /** @@ -141,6 +142,7 @@ export class CanvasManager { this._resizePlugins = []; } + /** Gets the zoom center point */ getZoomCenter(): ICoordinates { const pxRatio = this._container.retina.pixelRatio, { width, height } = this.size; @@ -330,6 +332,10 @@ export class CanvasManager { return true; } + /** + * Sets the pointer events style on the canvas + * @param type + */ setPointerEvents(type: string): void { const element = this.element; @@ -351,6 +357,7 @@ export class CanvasManager { this._zoomCenter = center; } + /** Stops the canvas manager */ stop(): void { this._safeMutationObserver(obs => { obs.disconnect(); diff --git a/engine/src/Core/Container.ts b/engine/src/Core/Container.ts index d88fec3efd1..725ebf9d6ab 100644 --- a/engine/src/Core/Container.ts +++ b/engine/src/Core/Container.ts @@ -18,11 +18,17 @@ import { Retina } from "./Retina.js"; import { getLogger } from "../Utils/LogUtils.js"; import { loadOptions } from "../Utils/OptionsUtils.js"; -interface ContainerParams { +/** Container constructor parameters */ +export interface ContainerParams { + /** Event dispatch callback */ dispatchCallback: (eventType: string, args?: CustomEventArgs) => void; + /** The container id */ id: string; + /** Destroy callback */ onDestroy: (remove: boolean) => void; + /** The plugin manager instance */ pluginManager: PluginManager; + /** Source options to load */ sourceOptions?: ISourceOptions; } @@ -84,6 +90,7 @@ export class Container { */ destroyed; + /** The effect drawers map */ effectDrawers: Map; /** @@ -96,6 +103,7 @@ export class Container { */ hdr; + /** The container id */ readonly id; /** @@ -103,10 +111,14 @@ export class Container { */ pageHidden; + /** Particle created plugins */ readonly particleCreatedPlugins: IContainerPlugin[]; + /** Particle destroyed plugins */ readonly particleDestroyedPlugins: IContainerPlugin[]; + /** Particle position plugins */ readonly particlePositionPlugins: IContainerPlugin[]; + /** The particle updaters array */ particleUpdaters: IParticleUpdater[]; /** @@ -119,8 +131,10 @@ export class Container { */ readonly plugins: IContainerPlugin[]; + /** The retina manager */ readonly retina; + /** The shape drawers map */ shapeDrawers: Map; /** @@ -128,6 +142,7 @@ export class Container { */ started; + /** The number of z-layers */ zLayers; private _delay: number; @@ -226,10 +241,15 @@ export class Container { return this._sourceOptions; } + /** + * Adds to the container lifetime + * @param value + */ addLifeTime(value: number): void { this._lifeTime += value; } + /** Checks if the container is still alive */ alive(): boolean { return !this._duration || this._lifeTime <= this._duration; } @@ -274,6 +294,11 @@ export class Container { this.dispatchEvent(EventType.containerDestroyed); } + /** + * Dispatches an event from the container + * @param type + * @param data + */ dispatchEvent(type: string, data?: unknown): void { this._dispatchCallback(type, { container: this, @@ -303,6 +328,11 @@ export class Container { }); } + /** + * Exports the container canvas to the specified format + * @param type + * @param options + */ async export(type: string, options: Record = {}): Promise { for (const plugin of this.plugins) { if (!plugin.export) { @@ -408,6 +438,7 @@ export class Container { this.dispatchEvent(EventType.particlesSetup); } + /** Initializes the effect drawers, shape drawers and particle updaters */ async initDrawersAndUpdaters(): Promise { const pluginManager = this._pluginManager; @@ -494,6 +525,10 @@ export class Container { return this.start(); } + /** + * Resets the container with new options + * @param sourceOptions + */ async reset(sourceOptions?: ISourceOptions): Promise { if (!guardCheck(this)) { return; diff --git a/engine/src/Core/Engine.ts b/engine/src/Core/Engine.ts index 40d934f2aed..2f55f4d9238 100644 --- a/engine/src/Core/Engine.ts +++ b/engine/src/Core/Engine.ts @@ -134,6 +134,7 @@ const getCanvasFromContainer = (domContainer: HTMLElement): HTMLCanvasElement => * and for Plugins class responsible for every external feature */ export class Engine { + /** The plugin manager */ readonly pluginManager = new PluginManager(this); /** * Contains all the {@link Container} instances of the current engine instance @@ -147,10 +148,12 @@ export class Engine { */ private _initialized = false; + /** The container instances */ get items(): Container[] { return this._domArray; } + /** The engine version */ get version(): string { return __VERSION__; } @@ -167,6 +170,10 @@ export class Engine { /** * @param pluginVersion - the plugin version to check against */ + /** + * Checks if a plugin version matches the engine version + * @param pluginVersion + */ checkVersion(pluginVersion: string): void { if (this.version === pluginVersion) { return; diff --git a/engine/src/Core/Interfaces/Colors.ts b/engine/src/Core/Interfaces/Colors.ts index c266349a6df..ea01e3401e6 100644 --- a/engine/src/Core/Interfaces/Colors.ts +++ b/engine/src/Core/Interfaces/Colors.ts @@ -387,8 +387,11 @@ export interface ILaba extends IOklab, IAlphaColor {} * [[include:Color.md]] */ export interface IHwb { + /** Blackness */ b: number; + /** Hue */ h: number; + /** Whiteness */ w: number; } @@ -402,8 +405,11 @@ export interface IHwba extends IHwb, IAlphaColor {} * Range HWB Color */ export interface IRangeHwb { + /** Blackness range */ b: RangeValue; + /** Hue range */ h: RangeValue; + /** Whiteness range */ w: RangeValue; } diff --git a/engine/src/Core/Interfaces/IBounds.ts b/engine/src/Core/Interfaces/IBounds.ts index 2e2a23968c3..d8bbc9bc91f 100644 --- a/engine/src/Core/Interfaces/IBounds.ts +++ b/engine/src/Core/Interfaces/IBounds.ts @@ -1,8 +1,11 @@ -/** - */ +/** Bounding box coordinates */ export interface IBounds { + /** Bottom boundary */ bottom: number; + /** Left boundary */ left: number; + /** Right boundary */ right: number; + /** Top boundary */ top: number; } diff --git a/engine/src/Core/Interfaces/IBubbleParticleData.ts b/engine/src/Core/Interfaces/IBubbleParticleData.ts index 25a8d059684..f8551738f25 100644 --- a/engine/src/Core/Interfaces/IBubbleParticleData.ts +++ b/engine/src/Core/Interfaces/IBubbleParticleData.ts @@ -1,12 +1,17 @@ import type { IHsl } from "./Colors.js"; -/** - */ +/** Bubble effect data for a particle */ export interface IBubbleParticleData { + /** Bubble color */ color?: IHsl; + /** Optional div element for hover bubbles */ div?: HTMLElement; + /** Final calculated bubble color */ finalColor?: IHsl; + /** Whether the particle is within bubble range */ inRange: boolean; + /** Bubble opacity */ opacity?: number; + /** Bubble radius */ radius?: number; } diff --git a/engine/src/Core/Interfaces/ICircleBouncer.ts b/engine/src/Core/Interfaces/ICircleBouncer.ts index 93b7419f679..1c2dbde3035 100644 --- a/engine/src/Core/Interfaces/ICircleBouncer.ts +++ b/engine/src/Core/Interfaces/ICircleBouncer.ts @@ -1,10 +1,16 @@ import type { ICoordinates } from "./ICoordinates.js"; import type { Vector } from "../Utils/Vectors.js"; +/** Circle bounce data used for particle-particle collision bouncing */ export interface ICircleBouncer { + /** Bounce factor vector */ factor: Vector; + /** Particle mass for collision calculation */ mass: number; + /** Current position */ position: ICoordinates; + /** Particle radius */ radius: number; + /** Current velocity vector */ velocity: Vector; } diff --git a/engine/src/Core/Interfaces/IColorManager.ts b/engine/src/Core/Interfaces/IColorManager.ts index 64775020670..950ad9b0ec5 100644 --- a/engine/src/Core/Interfaces/IColorManager.ts +++ b/engine/src/Core/Interfaces/IColorManager.ts @@ -1,11 +1,16 @@ import type { IColor, IRangeColor, IRgb, IRgba } from "./Colors.js"; +/** Color manager interface for parsing and converting colors */ export interface IColorManager { + /** Checks if the manager accepts the given input string */ accepts(input: string): boolean; + /** Converts a color to RGB */ handleColor(color: IColor): IRgb | undefined; + /** Converts a range color to RGB */ handleRangeColor(color: IRangeColor): IRgb | undefined; + /** Parses a string into RGBA */ parseString(input: string): IRgba | undefined; } diff --git a/engine/src/Core/Interfaces/IContainerPlugin.ts b/engine/src/Core/Interfaces/IContainerPlugin.ts index 9b253b9d5ab..cd68ce3f884 100644 --- a/engine/src/Core/Interfaces/IContainerPlugin.ts +++ b/engine/src/Core/Interfaces/IContainerPlugin.ts @@ -7,44 +7,80 @@ import type { IShapeDrawData } from "./IShapeDrawData.js"; import type { OutModeDirection } from "../../Enums/Directions/OutModeDirection.js"; import type { Particle } from "../Particle.js"; -/** - */ +/** Container plugin interface for extending container behavior */ export interface IContainerPlugin { + /** Handles canvas clearing, returns true if handled */ canvasClear?: () => boolean; + /** Handles canvas painting, returns true if handled */ canvasPaint?: () => boolean; + /** Checks if a particle position is valid, with retry count */ checkParticlePosition?: (particle: Particle, position: ICoordinates, tryCount: number) => boolean; + /** Clears plugin-specific drawings from the canvas */ clearDraw?: (context: CanvasContextType, delta: IDelta) => void; + /** Validates a click position */ clickPositionValid?: (position: ICoordinates) => boolean; + /** Cleans up plugin resources */ destroy?: () => void; + /** Draws plugin content on the canvas */ draw?: (context: CanvasContextType, delta: IDelta) => void; + /** Draws a particle managed by the plugin */ drawParticle?: (context: CanvasContextType, particle: Particle, delta: IDelta) => void; + /** Cleanup after drawing a particle */ drawParticleCleanup?: (context: CanvasContextType, particle: Particle, delta: IDelta) => void; + /** Setup before drawing a particle */ drawParticleSetup?: (context: CanvasContextType, particle: Particle, delta: IDelta) => void; + /** Applies canvas transform before drawing a particle */ drawParticleTransform?: (data: IShapeDrawData) => void; + /** Cleanup after drawing settings */ drawSettingsCleanup?: (context: CanvasContextType, delta: IDelta) => void; + /** Setup before drawing settings */ drawSettingsSetup?: (context: CanvasContextType, delta: IDelta) => void; + /** Exports the container content */ export?: (type: string, data: Record) => Promise; + /** Initializes the plugin */ init?: () => Promise; + /** Handles particle bounce with the given direction */ particleBounce?: (particle: Particle, delta: IDelta, direction: OutModeDirection) => boolean; + /** Called when a particle is created */ particleCreated?: (particle: Particle) => void; + /** Called when a particle is destroyed */ particleDestroyed?: (particle: Particle, override?: boolean) => void; + /** Returns the fill color for a particle */ particleFillColor?: (particle: Particle) => string | IOptionsColor | undefined; + /** Returns a custom position for a particle */ particlePosition?: (position?: ICoordinates, particle?: Particle) => ICoordinates | undefined; + /** Resets a particle state */ particleReset?: (particle: Particle) => void; + /** Returns the stroke color for a particle */ particleStrokeColor?: (particle: Particle) => string | IOptionsColor | undefined; + /** Updates a particle each frame */ particleUpdate?: (particle: Particle, delta: IDelta) => void; + /** Returns the particle density count */ particlesDensityCount?: () => number; + /** Handles particle initialization, returns true if handled */ particlesInitialization?: () => boolean; + /** Sets up particles for the container */ particlesSetup?: () => void; + /** Pauses the plugin */ pause?: () => void; + /** Resumes the plugin */ play?: () => void; + /** Called after each particle update */ postParticleUpdate?: (particle: Particle, delta: IDelta) => void; + /** Called after all updates */ postUpdate?: (delta: IDelta) => void; + /** Called before initialization */ preInit?: () => Promise; + /** Reinitializes for redraw */ redrawInit?: () => Promise; + /** Handles container resize */ resize?: () => void; + /** Starts the plugin */ start?: () => Promise; + /** Stops the plugin */ stop?: () => void; + /** Updates the plugin each frame */ update?: (delta: IDelta) => void; + /** Updates actual options, returns true if options changed */ updateActualOptions?: () => boolean; } diff --git a/engine/src/Core/Interfaces/ICoordinates.ts b/engine/src/Core/Interfaces/ICoordinates.ts index 490df976ea5..e25991bd662 100644 --- a/engine/src/Core/Interfaces/ICoordinates.ts +++ b/engine/src/Core/Interfaces/ICoordinates.ts @@ -1,28 +1,42 @@ import type { PixelMode } from "../../Enums/Modes/PixelMode.js"; import type { RangeValue } from "../../Types/RangeValue.js"; +/** 2D coordinates interface */ export interface ICoordinates { + /** The x coordinate */ x: number; + /** The y coordinate */ y: number; } +/** 3D coordinates interface extending 2D coordinates */ export interface ICoordinates3d extends ICoordinates { + /** The z coordinate */ z: number; } +/** Ranged 2D coordinates with range values */ export interface IRangedCoordinates { + /** The x coordinate range */ x: RangeValue; + /** The y coordinate range */ y: RangeValue; } +/** Ranged 3D coordinates extending ranged 2D coordinates */ export interface IRangedCoordinates3d extends IRangedCoordinates { + /** The z coordinate range */ z: RangeValue; } +/** Coordinates with pixel mode */ export interface ICoordinatesWithMode extends ICoordinates { + /** The pixel mode */ mode: PixelMode | keyof typeof PixelMode; } +/** Center coordinates with radius and pixel mode */ export interface ICenterCoordinates extends ICoordinatesWithMode { + /** The center radius */ radius: number; } diff --git a/engine/src/Core/Interfaces/IDelta.ts b/engine/src/Core/Interfaces/IDelta.ts index 9953f34080e..3ce49b4bcf8 100644 --- a/engine/src/Core/Interfaces/IDelta.ts +++ b/engine/src/Core/Interfaces/IDelta.ts @@ -1,6 +1,7 @@ -/** - */ +/** Frame delta time values */ export interface IDelta { + /** Delta factor for frame-independent calculations */ factor: number; + /** Delta value in milliseconds */ value: number; } diff --git a/engine/src/Core/Interfaces/IDimension.ts b/engine/src/Core/Interfaces/IDimension.ts index 1a7e6705bea..d02749c48a7 100644 --- a/engine/src/Core/Interfaces/IDimension.ts +++ b/engine/src/Core/Interfaces/IDimension.ts @@ -1,12 +1,15 @@ import type { PixelMode } from "../../Enums/Modes/PixelMode.js"; -/** - */ +/** Dimensions with width and height */ export interface IDimension { + /** The height value */ height: number; + /** The width value */ width: number; } +/** Dimensions with pixel mode */ export interface IDimensionWithMode extends IDimension { + /** Pixel mode (precise or percent) */ mode: PixelMode | keyof typeof PixelMode; } diff --git a/engine/src/Core/Interfaces/IDistance.ts b/engine/src/Core/Interfaces/IDistance.ts index 743958d547c..1f4a0c602d1 100644 --- a/engine/src/Core/Interfaces/IDistance.ts +++ b/engine/src/Core/Interfaces/IDistance.ts @@ -1,4 +1,7 @@ +/** Horizontal and vertical distance values */ export interface IDistance { + /** Horizontal distance */ horizontal: number; + /** Vertical distance */ vertical: number; } diff --git a/engine/src/Core/Interfaces/IDrawParticleParams.ts b/engine/src/Core/Interfaces/IDrawParticleParams.ts index 657ffcebd7f..3db5557ffa9 100644 --- a/engine/src/Core/Interfaces/IDrawParticleParams.ts +++ b/engine/src/Core/Interfaces/IDrawParticleParams.ts @@ -5,6 +5,9 @@ import type { IParticleColorStyle } from "./IParticleColorStyle.js"; import type { IParticleTransformValues } from "./IParticleTransformValues.js"; import type { Particle } from "../Particle.js"; +/** + * Parameters used to draw a particle on the canvas. + */ export interface IDrawParticleParams { /** * The color styles value diff --git a/engine/src/Core/Interfaces/IEffectDrawer.ts b/engine/src/Core/Interfaces/IEffectDrawer.ts index 7ab1cfa116e..f98a7bbce83 100644 --- a/engine/src/Core/Interfaces/IEffectDrawer.ts +++ b/engine/src/Core/Interfaces/IEffectDrawer.ts @@ -2,6 +2,9 @@ import type { Container } from "../Container.js"; import type { IShapeDrawData } from "./IShapeDrawData.js"; import type { Particle } from "../Particle.js"; +/** + * Effect drawer lifecycle callbacks. + */ export interface IEffectDrawer { /** * Shape destroy function diff --git a/engine/src/Core/Interfaces/IPalette.ts b/engine/src/Core/Interfaces/IPalette.ts index 009f96a1271..ee75a39fd05 100644 --- a/engine/src/Core/Interfaces/IPalette.ts +++ b/engine/src/Core/Interfaces/IPalette.ts @@ -1,26 +1,42 @@ import type { RangeValue } from "../../Types/RangeValue.js"; import type { SingleOrMultiple } from "../../Types/SingleOrMultiple.js"; +/** Palette fill color configuration */ export interface IPaletteColorsFill { + /** Enables or disables the fill color */ enable: boolean; + /** Fill color opacity range */ opacity?: RangeValue; + /** Fill color value, single or multiple */ value: SingleOrMultiple; } +/** Palette stroke color configuration */ export interface IPaletteColorsStroke { + /** Stroke color opacity range */ opacity?: RangeValue; + /** Stroke color value, single or multiple */ value: SingleOrMultiple; + /** Stroke width range */ width: RangeValue; } +/** Palette colors with optional fill and stroke */ export interface IPaletteColors { + /** Fill color configuration */ fill?: IPaletteColorsFill; + /** Stroke color configuration */ stroke?: IPaletteColorsStroke; } +/** Color palette definition */ export interface IPalette { + /** Background color */ background: string; + /** Canvas blend mode */ blendMode: GlobalCompositeOperation; + /** Palette colors, single or multiple sets */ colors: SingleOrMultiple; + /** Palette name */ name: string; } diff --git a/engine/src/Core/Interfaces/IParticleColorStyle.ts b/engine/src/Core/Interfaces/IParticleColorStyle.ts index 5f1ddfa0c4f..2e36171f54d 100644 --- a/engine/src/Core/Interfaces/IParticleColorStyle.ts +++ b/engine/src/Core/Interfaces/IParticleColorStyle.ts @@ -1,4 +1,7 @@ +/** Particle color styles for fill and stroke */ export interface IParticleColorStyle { + /** Fill color style */ fill?: string | CanvasGradient | CanvasPattern; + /** Stroke color style */ stroke?: string | CanvasGradient | CanvasPattern; } diff --git a/engine/src/Core/Interfaces/IParticleHslAnimation.ts b/engine/src/Core/Interfaces/IParticleHslAnimation.ts index 56709ea2603..26bddf811e1 100644 --- a/engine/src/Core/Interfaces/IParticleHslAnimation.ts +++ b/engine/src/Core/Interfaces/IParticleHslAnimation.ts @@ -1,7 +1,11 @@ import type { IParticleColorAnimation } from "./IParticleValueAnimation.js"; +/** Particle HSL animation data for all three color channels */ export interface IParticleHslAnimation { + /** Hue channel animation */ h: IParticleColorAnimation; + /** Lightness channel animation */ l: IParticleColorAnimation; + /** Saturation channel animation */ s: IParticleColorAnimation; } diff --git a/engine/src/Core/Interfaces/IParticleLife.ts b/engine/src/Core/Interfaces/IParticleLife.ts index c09a7f4ad15..25d9b39eca9 100644 --- a/engine/src/Core/Interfaces/IParticleLife.ts +++ b/engine/src/Core/Interfaces/IParticleLife.ts @@ -1,7 +1,13 @@ +/** Particle life cycle data */ export interface IParticleLife { + /** Number of times the particle has been reset */ count: number; + /** Delay before the particle starts */ delay: number; + /** Delay time value in seconds */ delayTime: number; + /** Total duration of the particle life */ duration: number; + /** Elapsed time in the current life cycle */ time: number; } diff --git a/engine/src/Core/Interfaces/IParticleOpacityData.ts b/engine/src/Core/Interfaces/IParticleOpacityData.ts index d4f52735b8c..d59d7849e72 100644 --- a/engine/src/Core/Interfaces/IParticleOpacityData.ts +++ b/engine/src/Core/Interfaces/IParticleOpacityData.ts @@ -1,7 +1,11 @@ +/** Particle opacity data with separate fill and stroke values */ export interface IParticleOpacityData { + /** Fill opacity value */ fillOpacity: number; + /** Overall opacity value */ opacity: number; + /** Stroke opacity value */ strokeOpacity: number; } diff --git a/engine/src/Core/Interfaces/IParticleRetinaProps.ts b/engine/src/Core/Interfaces/IParticleRetinaProps.ts index d6fd085f328..6a81204344d 100644 --- a/engine/src/Core/Interfaces/IParticleRetinaProps.ts +++ b/engine/src/Core/Interfaces/IParticleRetinaProps.ts @@ -1,9 +1,15 @@ import type { IDistance } from "./IDistance.js"; +/** Particle retina-scaled property values */ export interface IParticleRetinaProps { + /** Maximum distance for retina displays */ maxDistance: Partial; + /** Maximum speed adjusted for retina */ maxSpeed: number; + /** Movement drift adjusted for retina */ moveDrift: number; + /** Movement speed adjusted for retina */ moveSpeed: number; + /** Size animation speed adjusted for retina */ sizeAnimationSpeed: number; } diff --git a/engine/src/Core/Interfaces/IParticleRoll.ts b/engine/src/Core/Interfaces/IParticleRoll.ts index 1c51a26c9cf..5882c287e55 100644 --- a/engine/src/Core/Interfaces/IParticleRoll.ts +++ b/engine/src/Core/Interfaces/IParticleRoll.ts @@ -1,13 +1,20 @@ import type { AlterType } from "../../Enums/Types/AlterType.js"; +/** Particle roll animation data */ export interface IParticleRoll { + /** Roll color alteration configuration */ alter?: { type: AlterType; value: number; }; + /** Current roll angle */ angle: number; + /** Enables or disables the roll animation */ enable: boolean; + /** Enables horizontal roll */ horizontal: boolean; + /** Roll animation speed */ speed: number; + /** Enables vertical roll */ vertical: boolean; } diff --git a/engine/src/Core/Interfaces/IParticleRotateData.ts b/engine/src/Core/Interfaces/IParticleRotateData.ts index 9fd46ea6b66..19cb4f01460 100644 --- a/engine/src/Core/Interfaces/IParticleRotateData.ts +++ b/engine/src/Core/Interfaces/IParticleRotateData.ts @@ -1,4 +1,7 @@ +/** Particle rotation angle data with pre-computed trig values */ export interface IParticleRotateData { + /** Cosine of the rotation angle */ cos: number; + /** Sine of the rotation angle */ sin: number; } diff --git a/engine/src/Core/Interfaces/IParticleTransformValues.ts b/engine/src/Core/Interfaces/IParticleTransformValues.ts index 312cbd43cb2..fbaa53248fa 100644 --- a/engine/src/Core/Interfaces/IParticleTransformValues.ts +++ b/engine/src/Core/Interfaces/IParticleTransformValues.ts @@ -1,6 +1,11 @@ +/** Particle canvas transform values (2x2 matrix) */ export interface IParticleTransformValues { + /** Horizontal scaling */ a: number; + /** Horizontal skewing */ b: number; + /** Vertical skewing */ c: number; + /** Vertical scaling */ d: number; } diff --git a/engine/src/Core/Interfaces/IParticleUpdater.ts b/engine/src/Core/Interfaces/IParticleUpdater.ts index c9416a62e00..2d6c767a914 100644 --- a/engine/src/Core/Interfaces/IParticleUpdater.ts +++ b/engine/src/Core/Interfaces/IParticleUpdater.ts @@ -7,11 +7,15 @@ import type { Particle } from "../Particle.js"; import type { ParticlesOptions } from "../../Options/Classes/Particles/ParticlesOptions.js"; import type { RecursivePartial } from "../../Types/RecursivePartial.js"; +/** Particle updater interface for custom particle behavior */ export interface IParticleUpdater { + /** Called after drawing a particle */ afterDraw?: (particle: Particle) => void; + /** Called before drawing a particle */ beforeDraw?: (particle: Particle) => void; + /** Returns custom color styles for a particle */ getColorStyles?: ( particle: Particle, context: CanvasContextType, @@ -19,17 +23,24 @@ export interface IParticleUpdater { opacity: number, ) => IParticleColorStyle; + /** Returns custom transform values for a particle */ getTransformValues?: (particle: Particle) => Partial; + /** Loads particle updater options */ loadOptions?: (options: ParticlesOptions, ...sources: (RecursivePartial | undefined)[]) => void; + /** Called when a particle is destroyed */ particleDestroyed?: (particle: Particle, override?: boolean) => void; + /** Resets the updater state for a particle */ reset?: (particle: Particle) => void; + /** Initializes the updater for a particle */ init(particle: Particle): void; + /** Checks if the updater is enabled for the given particle */ isEnabled(particle: Particle): boolean; + /** Updates the particle each frame */ update(particle: Particle, delta: IDelta): void; } diff --git a/engine/src/Core/Interfaces/IParticleValueAnimation.ts b/engine/src/Core/Interfaces/IParticleValueAnimation.ts index 6a7bf025044..861de371193 100644 --- a/engine/src/Core/Interfaces/IParticleValueAnimation.ts +++ b/engine/src/Core/Interfaces/IParticleValueAnimation.ts @@ -1,26 +1,40 @@ import type { AnimationStatus } from "../../Enums/AnimationStatus.js"; import type { RangeValue } from "../../Types/RangeValue.js"; -/** - */ +/** Particle value animation state */ export interface IParticleValueAnimation { + /** Value decay factor applied each frame */ decay?: number; + /** Delay before the animation starts, in seconds */ delayTime?: number; + /** Enables or disables the animation */ enable: boolean; + /** The initial value before any animation is applied */ initialValue?: number; + /** Current loop count */ loops?: number; + /** Maximum number of loops before the animation stops */ maxLoops?: number; + /** Current animation status (increasing, decreasing, or none) */ status?: AnimationStatus; + /** Elapsed time since the animation started */ time?: number; + /** Current animated value */ value: T; + /** Animation velocity per frame */ velocity?: number; } +/** Particle numeric value animation state with min/max bounds */ export interface IParticleNumericValueAnimation extends IParticleValueAnimation { + /** Maximum value */ max: number; + /** Minimum value */ min: number; } +/** Particle color channel animation state with optional offset */ export interface IParticleColorAnimation extends IParticleNumericValueAnimation { + /** Random offset applied to the color value */ offset?: RangeValue; } diff --git a/engine/src/Core/Interfaces/IPlugin.ts b/engine/src/Core/Interfaces/IPlugin.ts index 2695f6601f8..23e5ca2e766 100644 --- a/engine/src/Core/Interfaces/IPlugin.ts +++ b/engine/src/Core/Interfaces/IPlugin.ts @@ -10,17 +10,22 @@ import type { RecursivePartial } from "../../Types/RecursivePartial.js"; * [[include:Plugins.md]] */ export interface IPlugin { + /** The unique identifier for this plugin */ readonly id: string; + /** Loads options for particles, called when building particle options */ loadParticlesOptions?: ( container: Container, options: ParticlesOptions, source?: RecursivePartial, ) => void; + /** Gets the container plugin instance for the given container */ getPlugin(container: Container): Promise; + /** Loads the plugin options into the given options object */ loadOptions(container: Container, options: Options, source?: ISourceOptions): void; + /** Checks if this plugin is needed for the given options */ needsPlugin(options?: ISourceOptions): boolean; } diff --git a/engine/src/Core/Interfaces/IRangeValue.ts b/engine/src/Core/Interfaces/IRangeValue.ts index c6bd9b2d76d..096a75a454f 100644 --- a/engine/src/Core/Interfaces/IRangeValue.ts +++ b/engine/src/Core/Interfaces/IRangeValue.ts @@ -1,4 +1,7 @@ +/** Numeric range with minimum and maximum values */ export interface IRangeValue { + /** Maximum value */ max: number; + /** Minimum value */ min: number; } diff --git a/engine/src/Core/Interfaces/IShapeDrawData.ts b/engine/src/Core/Interfaces/IShapeDrawData.ts index 57357caacaa..cee5dec5938 100644 --- a/engine/src/Core/Interfaces/IShapeDrawData.ts +++ b/engine/src/Core/Interfaces/IShapeDrawData.ts @@ -3,6 +3,9 @@ import type { ICoordinates } from "./ICoordinates.js"; import type { IDelta } from "./IDelta.js"; import type { Particle } from "../Particle.js"; +/** + * Data passed to shape and effect draw callbacks. + */ export interface IShapeDrawData { /** * the canvas context for drawing diff --git a/engine/src/Core/Interfaces/IShapeDrawer.ts b/engine/src/Core/Interfaces/IShapeDrawer.ts index 97934e6476d..875a1609c4f 100644 --- a/engine/src/Core/Interfaces/IShapeDrawer.ts +++ b/engine/src/Core/Interfaces/IShapeDrawer.ts @@ -3,6 +3,7 @@ import type { IShapeDrawData } from "./IShapeDrawData.js"; import type { Particle } from "../Particle.js"; /** + * Shape drawer contract used by particle shape plugins. */ export interface IShapeDrawer { /** diff --git a/engine/src/Core/Interfaces/IShapeValues.ts b/engine/src/Core/Interfaces/IShapeValues.ts index 8b38a3efdcc..16206bb4d4e 100644 --- a/engine/src/Core/Interfaces/IShapeValues.ts +++ b/engine/src/Core/Interfaces/IShapeValues.ts @@ -1,12 +1,12 @@ import type { IParticlesOptions } from "../../Options/Interfaces/Particles/IParticlesOptions.js"; import type { RecursivePartial } from "../../Types/RecursivePartial.js"; -/** - */ - +/** Shape values interface for custom particle shapes */ export interface IShapeValues { [key: string]: unknown; + /** Whether the shape path should be closed */ close?: boolean; + /** Particles options for shape-specific particles */ particles?: RecursivePartial; } diff --git a/engine/src/Core/Interfaces/ISlowParticleData.ts b/engine/src/Core/Interfaces/ISlowParticleData.ts index 63c688f8d86..9d275e5ff13 100644 --- a/engine/src/Core/Interfaces/ISlowParticleData.ts +++ b/engine/src/Core/Interfaces/ISlowParticleData.ts @@ -1,4 +1,7 @@ +/** Slow effect data for a particle */ export interface ISlowParticleData { + /** Slow factor applied to the particle */ factor: number; + /** Whether the particle is within slow range */ inRange: boolean; } diff --git a/engine/src/Core/Particle.ts b/engine/src/Core/Particle.ts index 1154711231a..8624136a5cc 100644 --- a/engine/src/Core/Particle.ts +++ b/engine/src/Core/Particle.ts @@ -208,8 +208,10 @@ export class Particle { */ fillOpacity?: number; + /** The particle group */ group?: string; + /** The particle id */ id!: number; /** @@ -227,8 +229,10 @@ export class Particle { */ initialVelocity!: Vector; + /** Checks if the particle is rotating */ isRotating!: boolean; + /** Checks if the particle just warped */ justWarped!: boolean; /** @@ -241,6 +245,7 @@ export class Particle { */ misplaced!: boolean; + /** The move center coordinates */ moveCenter!: ICenterCoordinates; /** @@ -258,6 +263,7 @@ export class Particle { */ options!: ParticlesOptions; + /** The particle out type */ outType!: ParticleOutType; /** @@ -383,6 +389,10 @@ export class Particle { this._container = container; } + /** + * Destroys the particle + * @param override + */ destroy(override?: boolean): void { if (this.unbreakable || this.destroyed) { return; @@ -410,6 +420,10 @@ export class Particle { }); } + /** + * Draws the particle + * @param delta + */ draw(delta: IDelta): void { const container = this._container, render = container.canvas.render; @@ -418,18 +432,22 @@ export class Particle { render.drawParticle(this, delta); } + /** Gets the particle angle */ getAngle(): number { return this.rotation + (this.pathRotation ? this.velocity.angle : defaultAngle); } + /** Gets the particle fill color */ getFillColor(): IHsl | undefined { return this._getRollColor(this.bubble.color ?? getHslFromAnimation(this.fillColor)); } + /** Gets the particle mass */ getMass(): number { return this.getRadius() ** squareExp * Math.PI * half; } + /** Gets the particle opacity */ getOpacity(): IParticleOpacityData { const zIndexOptions = this.options.zIndex, zIndexFactor = zIndexFactorOffset - this.zIndexFactor, @@ -445,6 +463,7 @@ export class Particle { return this._cachedOpacityData; } + /** Gets the particle position */ getPosition(): ICoordinates3d { this._cachedPosition.x = this.position.x + this.offset.x; this._cachedPosition.y = this.position.y + this.offset.y; @@ -453,10 +472,12 @@ export class Particle { return this._cachedPosition; } + /** Gets the particle radius */ getRadius(): number { return this.bubble.radius ?? this.size.value; } + /** Gets the particle rotation data */ getRotateData(): IParticleRotateData { const angle = this.getAngle(); @@ -466,10 +487,15 @@ export class Particle { return this._cachedRotateData; } + /** Gets the particle stroke color */ getStrokeColor(): IHsl | undefined { return this._getRollColor(this.bubble.color ?? getHslFromAnimation(this.strokeColor)); } + /** + * Gets the particle transform data + * @param externalTransform + */ getTransformData(externalTransform: Partial): IParticleTransformValues { const rotateData = this.getRotateData(), rotating = this.isRotating; @@ -486,6 +512,13 @@ export class Particle { return this._cachedTransform; } + /** + * Initializes the particle with the given parameters + * @param id + * @param position + * @param overrideOptions + * @param group + */ init( id: number, position?: ICoordinates, @@ -652,6 +685,7 @@ export class Particle { } } + /** Checks if the particle is inside the canvas */ isInsideCanvas(): boolean { const radius = this.getRadius(), canvasSize = this._container.canvas.size, @@ -665,6 +699,7 @@ export class Particle { ); } + /** Checks if the particle is showing its back side */ isShowingBack(): boolean { if (!this.roll) { return false; @@ -696,6 +731,7 @@ export class Particle { return false; } + /** Checks if the particle is visible */ isVisible(): boolean { return !this.destroyed && !this.spawning && this.isInsideCanvas(); } diff --git a/engine/src/Core/ParticlesManager.ts b/engine/src/Core/ParticlesManager.ts index 4e8d6ce2c6b..6e626d4135a 100644 --- a/engine/src/Core/ParticlesManager.ts +++ b/engine/src/Core/ParticlesManager.ts @@ -31,8 +31,10 @@ import { loadParticlesOptions } from "../Utils/OptionsUtils.js"; * Particles manager object */ export class ParticlesManager { + /** Check particle position plugins */ checkParticlePositionPlugins: IContainerPlugin[]; + /** The spatial hash grid */ grid; /** @@ -82,10 +84,18 @@ export class ParticlesManager { this._updatePlugins = []; } + /** Gets the number of particles */ get count(): number { return this._array.length; } + /** + * Adds a particle to the manager + * @param position + * @param overrideOptions + * @param group + * @param initializer + */ addParticle( position?: ICoordinates, overrideOptions?: RecursivePartial, @@ -161,6 +171,7 @@ export class ParticlesManager { this._zArray = []; } + /** Destroys the particles manager */ destroy(): void { this._array = []; this._pool.length = 0; @@ -173,25 +184,41 @@ export class ParticlesManager { this._updatePlugins = []; } + /** + * Draws all particles + * @param delta + */ drawParticles(delta: IDelta): void { for (const particle of this._zArray) { particle.draw(delta); } } + /** + * Filters particles with a condition + * @param condition + */ filter(condition: (particle: Particle) => boolean): Particle[] { return this._array.filter(condition); } + /** + * Finds a particle with a condition + * @param condition + */ find(condition: (particle: Particle) => boolean): Particle | undefined { return this._array.find(condition); } + /** + * Gets a particle by index + * @param index + */ get(index: number): Particle | undefined { return this._array[index]; } - /* --------- tsParticles functions - particles ----------- */ + /** Initializes the particles manager */ async init(): Promise { const container = this._container, options = container.actualOptions; @@ -280,6 +307,13 @@ export class ParticlesManager { } } + /** + * Adds particles to the manager + * @param nb + * @param position + * @param overrideOptions + * @param group + */ push( nb: number, position?: ICoordinates, @@ -291,6 +325,7 @@ export class ParticlesManager { } } + /** Redraws all particles */ async redraw(): Promise { this.clear(); await this.init(); @@ -298,10 +333,23 @@ export class ParticlesManager { this._container.canvas.render.drawParticles({ value: 0, factor: 0 }); } + /** + * Removes a particle + * @param particle + * @param group + * @param override + */ remove(particle: Particle, group?: string, override?: boolean): void { this.removeAt(this._array.indexOf(particle), undefined, group, override); } + /** + * Removes particles at a specific index + * @param index + * @param quantity + * @param group + * @param override + */ removeAt(index: number, quantity = defaultRemoveQuantity, group?: string, override?: boolean): void { if (index < minIndex || index > this.count) { return; @@ -317,10 +365,16 @@ export class ParticlesManager { } } + /** + * Removes a quantity of particles + * @param quantity + * @param group + */ removeQuantity(quantity: number, group?: string): void { this.removeAt(minIndex, quantity, group); } + /** Sets the particle density */ setDensity(): void { const options = this._container.actualOptions, groups = options.particles.groups; @@ -348,14 +402,26 @@ export class ParticlesManager { this._applyDensity(options.particles, pluginsCount); } + /** + * Sets the last z-index + * @param zIndex + */ setLastZIndex(zIndex: number): void { this._needsSort ||= zIndex >= this._maxZIndex || (zIndex > this._minZIndex && zIndex < this._maxZIndex); } + /** + * Sets the resize factor + * @param factor + */ setResizeFactor(factor: IDimension): void { this._resizeFactor = factor; } + /** + * Updates all particles + * @param delta + */ update(delta: IDelta): void { const particlesToDelete = new Set(); diff --git a/engine/src/Core/RenderManager.ts b/engine/src/Core/RenderManager.ts index 3e6236cb973..9090aad3866 100644 --- a/engine/src/Core/RenderManager.ts +++ b/engine/src/Core/RenderManager.ts @@ -86,10 +86,12 @@ export class RenderManager { this._drawSettingsCleanupPlugins = []; } + /** Canvas rendering context settings */ get settings(): CanvasRenderingContext2DSettings | undefined { return this._contextSettings; } + /** Clears the canvas directly */ canvasClear(): void { if (!this._container.actualOptions.clear) { return; @@ -237,6 +239,10 @@ export class RenderManager { }); } + /** + * Draws all particles for the current frame + * @param delta + */ drawParticles(delta: IDelta): void { const { particles } = this._container; @@ -372,18 +378,31 @@ export class RenderManager { this.paintBase(); } + /** + * Paints the canvas background with an optional base color + * @param baseColor + */ paintBase(baseColor?: string): void { this.draw(ctx => { paintBase(ctx, this._canvasManager.size, baseColor); }); } + /** + * Paints an image on the canvas with the given opacity + * @param image + * @param opacity + */ paintImage(image: HTMLImageElement, opacity: number): void { this.draw(ctx => { paintImage(ctx, this._canvasManager.size, image, opacity); }); } + /** + * Sets the canvas rendering context + * @param context + */ setContext(context: CanvasContextType | null): void { this._context = context; @@ -392,10 +411,15 @@ export class RenderManager { } } + /** + * Sets the canvas rendering context settings + * @param settings + */ setContextSettings(settings: CanvasRenderingContext2DSettings): void { this._contextSettings = settings; } + /** Stops the renderer and clears the canvas */ stop(): void { this.draw(ctx => { clear(ctx, this._canvasManager.size); diff --git a/engine/src/Core/Retina.ts b/engine/src/Core/Retina.ts index e8752565bf4..6b9c16bff97 100644 --- a/engine/src/Core/Retina.ts +++ b/engine/src/Core/Retina.ts @@ -3,10 +3,11 @@ import type { Container } from "./Container.js"; import type { Particle } from "./Particle.js"; import { getRangeValue } from "../Utils/MathUtils.js"; -/** - */ +/** Retina handling class for device pixel ratio adjustments */ export class Retina { + /** Device pixel ratio */ pixelRatio: number; + /** Reduce factor for performance */ reduceFactor: number; constructor(private readonly container: Container) { @@ -35,6 +36,10 @@ export class Retina { } } + /** + * Initializes retina-scaled properties for a particle + * @param particle + */ initParticle(particle: Particle): void { const options = particle.options, ratio = this.pixelRatio, diff --git a/engine/src/Core/Utils/PluginManager.ts b/engine/src/Core/Utils/PluginManager.ts index fc1d8c92fc2..d814d335e34 100644 --- a/engine/src/Core/Utils/PluginManager.ts +++ b/engine/src/Core/Utils/PluginManager.ts @@ -21,19 +21,29 @@ import type { ISourceOptions } from "../../Types/ISourceOptions.js"; import type { ParticlesOptions } from "../../Options/Classes/Particles/ParticlesOptions.js"; import type { RecursivePartial } from "../../Types/RecursivePartial.js"; -type AsyncLoadPluginFunction = (engine: Engine) => Promise; -type SyncLoadPluginFunction = (engine: Engine) => void; -type AsyncLoadPluginNoEngine = () => Promise; -type SyncLoadPluginNoEngine = () => void; -type LoadPluginFunction = +/** Async plugin loader with engine parameter */ +export type AsyncLoadPluginFunction = (engine: Engine) => Promise; +/** Sync plugin loader with engine parameter */ +export type SyncLoadPluginFunction = (engine: Engine) => void; +/** Async plugin loader without engine parameter */ +export type AsyncLoadPluginNoEngine = () => Promise; +/** Sync plugin loader without engine parameter */ +export type SyncLoadPluginNoEngine = () => void; +/** Plugin loader function type */ +export type LoadPluginFunction = | AsyncLoadPluginFunction | SyncLoadPluginFunction | AsyncLoadPluginNoEngine | SyncLoadPluginNoEngine; +/** + * Stores and resolves plugins, shapes, effects, palettes and updaters. + */ export class PluginManager { + /** The color managers map */ readonly colorManagers = new Map(); + /** The easing functions map */ readonly easingFunctions = new Map(); /** @@ -41,12 +51,14 @@ export class PluginManager { */ readonly effectDrawers = new Map>(); + /** The initializers map */ readonly initializers: Initializers = { effects: new Map(), shapes: new Map(), updaters: new Map(), }; + /** The palettes map */ readonly palettes = new Map(); /** @@ -57,6 +69,7 @@ export class PluginManager { /** * The presets array */ + /** The presets map */ readonly presets = new Map(); /** @@ -90,6 +103,7 @@ export class PluginManager { this._engine = engine; } + /** The configs record */ get configs(): Record { const res: Record = {}; @@ -101,13 +115,18 @@ export class PluginManager { } /** - * @param name - - * @param manager - + * Registers a color manager. + * @param name - Color manager identifier. + * @param manager - Color manager implementation. */ addColorManager(name: string, manager: IColorManager): void { this.colorManagers.set(name, manager); } + /** + * Adds a config to the manager + * @param config - the configuration to add + */ addConfig(config: ISourceOptions): void { const key = config.key ?? config.name ?? "default"; @@ -116,8 +135,9 @@ export class PluginManager { } /** - * @param name - - * @param easing - + * Registers an easing function. + * @param name - Easing identifier. + * @param easing - Easing function implementation. */ addEasing(name: EasingType | EasingTypeAlt, easing: EasingFunction): void { if (this.easingFunctions.get(name)) { @@ -136,6 +156,11 @@ export class PluginManager { this.initializers.effects.set(effect, drawer); } + /** + * Adds a palette to the manager + * @param name - the palette name + * @param palette - the palette to add + */ addPalette(name: string, palette: IPalette): void { this.palettes.set(name, palette); } @@ -186,6 +211,10 @@ export class PluginManager { } } + /** + * Clears plugins for a container + * @param container - the container to clear plugins for + */ clearPlugins(container: Container): void { this.effectDrawers.delete(container); this.shapeDrawers.delete(container); @@ -193,17 +222,29 @@ export class PluginManager { } /** - * @param name - - * @returns the easing function + * Gets an easing function by name. + * @param name - Easing identifier. + * @returns The easing function, or a passthrough easing if not found. */ getEasing(name: EasingType | EasingTypeAlt): EasingFunction { return this.easingFunctions.get(name) ?? ((value: number): number => value); } + /** + * Gets the effect drawers for a container + * @param container - the container to get effect drawers for + * @param force - if true, reloads the effect drawers + * @returns the effect drawers map + */ getEffectDrawers(container: Container, force = false): Promise> { return getItemMapFromInitializer(container, this.effectDrawers, this.initializers.effects, force); } + /** + * Gets a palette by name + * @param name - the palette name + * @returns the palette if found + */ getPalette(name: string): IPalette | undefined { return this.palettes.get(name); } @@ -226,6 +267,12 @@ export class PluginManager { return this.presets.get(preset); } + /** + * Gets the shape drawers for a container + * @param container - the container to get shape drawers for + * @param force - if true, reloads the shape drawers + * @returns the shape drawers map + */ async getShapeDrawers(container: Container, force = false): Promise> { return getItemMapFromInitializer(container, this.shapeDrawers, this.initializers.shapes, force); } @@ -265,7 +312,7 @@ export class PluginManager { } /** - * Load the given particles options for all the updaters + * Loads particles options for all updaters. * @param container - the container of the updaters * @param options - the actual options to set * @param sourceOptions - the source options to read @@ -284,6 +331,10 @@ export class PluginManager { updaters.forEach(updater => updater.loadOptions?.(options, ...sourceOptions)); } + /** + * Registers plugin loaders + * @param loaders - the plugin loader functions to register + */ async register(...loaders: LoadPluginFunction[]): Promise { if (this._initialized) { throw new Error("Register plugins can only be done before calling tsParticles.load()"); diff --git a/engine/src/Core/Utils/Ranges.ts b/engine/src/Core/Utils/Ranges.ts index 3975f859b2d..216451291fd 100644 --- a/engine/src/Core/Utils/Ranges.ts +++ b/engine/src/Core/Utils/Ranges.ts @@ -4,14 +4,14 @@ import { RangeType } from "../../Enums/RangeType.js"; import { checkDistance } from "../../Utils/MathUtils.js"; import { squareExp } from "./Constants.js"; -/** - */ +/** Abstract base class for spatial ranges */ export abstract class BaseRange { /** * Range position */ readonly position: ICoordinates; + /** The range type identifier */ readonly type: string; /** @@ -29,6 +29,11 @@ export abstract class BaseRange { this.type = type; } + /** + * Updates the internal position values. + * @param x - New x coordinate. + * @param y - New y coordinate. + */ protected _resetPosition(x: number, y: number): void { this.position.x = x; this.position.y = y; @@ -49,9 +54,9 @@ export abstract class BaseRange { abstract intersects(range: BaseRange): boolean; } -/** - */ +/** Circular spatial range */ export class Circle extends BaseRange { + /** Circle radius */ radius; /** @@ -67,7 +72,7 @@ export class Circle extends BaseRange { } /** - * Check if the given point is inside the circle + * Checks if the given point is inside the circle * @param point - the point to check * @returns true or false, checking if the given point is inside the circle */ @@ -104,6 +109,13 @@ export class Circle extends BaseRange { return false; } + /** + * Resets the circle position and radius, reusing the instance + * @param x - X coordinate of the position + * @param y - Y coordinate of the position + * @param radius - Circle's radius + * @returns the circle instance for chaining + */ reset(x: number, y: number, radius: number): this { this._resetPosition(x, y); @@ -113,8 +125,7 @@ export class Circle extends BaseRange { } } -/** - */ +/** Rectangular spatial range */ export class Rectangle extends BaseRange { /** * The rectangle size @@ -175,6 +186,14 @@ export class Rectangle extends BaseRange { return pos2.x < pos1.x + w && pos2.x + w2 > pos1.x && pos2.y < pos1.y + h && pos2.y + h2 > pos1.y; } + /** + * Resets the rectangle position and size, reusing the instance + * @param x - X coordinate of the position + * @param y - Y coordinate of the position + * @param width - Rectangle width + * @param height - Rectangle height + * @returns the rectangle instance for chaining + */ reset(x: number, y: number, width: number, height: number): this { this._resetPosition(x, y); this.size.width = width; diff --git a/engine/src/Core/Utils/SpatialHashGrid.ts b/engine/src/Core/Utils/SpatialHashGrid.ts index a73cb494e70..5796c1fb16b 100644 --- a/engine/src/Core/Utils/SpatialHashGrid.ts +++ b/engine/src/Core/Utils/SpatialHashGrid.ts @@ -46,7 +46,7 @@ export class SpatialHashGrid { /** * Adds a particle to the appropriate cell - * @param particle - + * @param particle - the particle to insert */ insert(particle: Particle): void { const { x, y } = particle.getPosition(), @@ -61,10 +61,10 @@ export class SpatialHashGrid { /** * Queries particles within a range (Circle or Rectangle) - * @param range - + * @param range - the range to query particles in * @param check - optional callback to check particles against, if not provided all particles will be returned - * @param out - - * @returns Particle[] + * @param out - optional output array to fill with results + * @returns the array of particles within the range */ query(range: BaseRange, check?: (particle: Particle) => boolean, out: Particle[] = []): Particle[] { const bounds = this._getRangeBounds(range); @@ -102,6 +102,14 @@ export class SpatialHashGrid { return out; } + /** + * Queries particles within a circular range + * @param position - the center position of the circle + * @param radius - the circle radius + * @param check - optional callback to filter particles + * @param out - optional output array to fill with results + * @returns the array of particles within the circle + */ queryCircle( position: ICoordinates, radius: number, @@ -116,6 +124,14 @@ export class SpatialHashGrid { return result; } + /** + * Queries particles within a rectangular range + * @param position - the top-left position of the rectangle + * @param size - the rectangle size + * @param check - optional callback to filter particles + * @param out - optional output array to fill with results + * @returns the array of particles within the rectangle + */ queryRectangle( position: ICoordinates, size: IDimension, @@ -130,6 +146,10 @@ export class SpatialHashGrid { return result; } + /** + * Sets the cell size (applied on next clear) + * @param cellSize - the new cell size + */ setCellSize(cellSize: number): void { this._pendingCellSize = cellSize; } diff --git a/engine/src/Core/Utils/Vectors.ts b/engine/src/Core/Utils/Vectors.ts index e52d2f260d3..4044d692a2a 100644 --- a/engine/src/Core/Utils/Vectors.ts +++ b/engine/src/Core/Utils/Vectors.ts @@ -10,6 +10,7 @@ function getZ(source: ICoordinates | ICoordinates3d): number { } /** + * 3D vector utility class used by particle math helpers. */ export class Vector3d implements ICoordinates3d { /** @@ -244,6 +245,9 @@ export class Vector3d implements ICoordinates3d { /** */ +/** + * 2D vector specialization built on top of Vector3d. + */ export class Vector extends Vector3d { /** * Vector constructor, creating an instance with the given coordinates diff --git a/engine/src/Enums/AnimationStatus.ts b/engine/src/Enums/AnimationStatus.ts index cb29d11cf02..bb8b7a2c12f 100644 --- a/engine/src/Enums/AnimationStatus.ts +++ b/engine/src/Enums/AnimationStatus.ts @@ -1,4 +1,7 @@ +/** Animation status values */ export enum AnimationStatus { + /** Animation value is increasing */ increasing = "increasing", + /** Animation value is decreasing */ decreasing = "decreasing", } diff --git a/engine/src/Enums/Directions/MoveDirection.ts b/engine/src/Enums/Directions/MoveDirection.ts index 0001cf67be8..e0b35aaf2cf 100644 --- a/engine/src/Enums/Directions/MoveDirection.ts +++ b/engine/src/Enums/Directions/MoveDirection.ts @@ -1,17 +1,28 @@ -/** - */ +/** Move direction values for particles */ export enum MoveDirection { + /** Move towards the bottom */ bottom = "bottom", + /** Move towards the bottom-left */ bottomLeft = "bottom-left", + /** Move towards the bottom-right */ bottomRight = "bottom-right", + /** Move towards the left */ left = "left", + /** No movement */ none = "none", + /** Move towards the right */ right = "right", + /** Move towards the top */ top = "top", + /** Move towards the top-left */ topLeft = "top-left", + /** Move towards the top-right */ topRight = "top-right", + /** Move outside the canvas */ outside = "outside", + /** Move inside the canvas */ inside = "inside", } +/** Alternative move direction type as a string literal union */ export type MoveDirectionAlt = "bottom-left" | "bottom-right" | "top-left" | "top-right"; diff --git a/engine/src/Enums/Directions/OutModeDirection.ts b/engine/src/Enums/Directions/OutModeDirection.ts index 127adb76288..97f8ea14324 100644 --- a/engine/src/Enums/Directions/OutModeDirection.ts +++ b/engine/src/Enums/Directions/OutModeDirection.ts @@ -1,6 +1,11 @@ +/** Out mode direction values for particles leaving the canvas */ export enum OutModeDirection { + /** Out mode applied to the bottom edge */ bottom = "bottom", + /** Out mode applied to the left edge */ left = "left", + /** Out mode applied to the right edge */ right = "right", + /** Out mode applied to the top edge */ top = "top", } diff --git a/engine/src/Enums/Directions/RotateDirection.ts b/engine/src/Enums/Directions/RotateDirection.ts index 85f12fc7e0a..00c54b7910a 100644 --- a/engine/src/Enums/Directions/RotateDirection.ts +++ b/engine/src/Enums/Directions/RotateDirection.ts @@ -1,9 +1,12 @@ -/** - */ +/** Rotate direction values for particles */ export enum RotateDirection { + /** Clockwise rotation */ clockwise = "clockwise", + /** Counter-clockwise rotation */ counterClockwise = "counter-clockwise", + /** Random rotation direction */ random = "random", } +/** Alternative rotate direction type as a string literal */ export type RotateDirectionAlt = "counter-clockwise"; diff --git a/engine/src/Enums/Modes/AnimationMode.ts b/engine/src/Enums/Modes/AnimationMode.ts index 87415104de1..9ee6d8a7b8a 100644 --- a/engine/src/Enums/Modes/AnimationMode.ts +++ b/engine/src/Enums/Modes/AnimationMode.ts @@ -1,6 +1,11 @@ +/** Animation mode values for particle value animations */ export enum AnimationMode { + /** Automatically chooses increase or decrease based on start value */ auto = "auto", + /** Animates from minimum to maximum value */ increase = "increase", + /** Animates from maximum to minimum value */ decrease = "decrease", + /** Randomly selects increase or decrease */ random = "random", } diff --git a/engine/src/Enums/Modes/LimitMode.ts b/engine/src/Enums/Modes/LimitMode.ts index 19fa93e6d81..b60d25e9bae 100644 --- a/engine/src/Enums/Modes/LimitMode.ts +++ b/engine/src/Enums/Modes/LimitMode.ts @@ -1,3 +1,6 @@ +/** + * Behavior to apply when particle limits are reached. + */ export enum LimitMode { /** * When limit is reached, older particles are removed diff --git a/engine/src/Enums/Modes/OutMode.ts b/engine/src/Enums/Modes/OutMode.ts index dbd65e26388..3a4f84886b6 100644 --- a/engine/src/Enums/Modes/OutMode.ts +++ b/engine/src/Enums/Modes/OutMode.ts @@ -1,9 +1,13 @@ -/** - */ +/** Out mode values for particles leaving the canvas */ export enum OutMode { + /** Bounce the particle back into the canvas */ bounce = "bounce", + /** No action, particle stays outside */ none = "none", + /** Let the particle move out of the canvas */ out = "out", + /** Destroy the particle when it leaves */ destroy = "destroy", + /** Split the particle into multiple particles */ split = "split", } diff --git a/engine/src/Enums/Modes/PixelMode.ts b/engine/src/Enums/Modes/PixelMode.ts index bb1ce014096..81498f65026 100644 --- a/engine/src/Enums/Modes/PixelMode.ts +++ b/engine/src/Enums/Modes/PixelMode.ts @@ -1,6 +1,7 @@ -/** - */ +/** Pixel mode values for coordinate and size interpretation */ export enum PixelMode { + /** Values are treated as exact pixel values */ precise = "precise", + /** Values are treated as percentages */ percent = "percent", } diff --git a/engine/src/Enums/RangeType.ts b/engine/src/Enums/RangeType.ts index dcd0ecef104..16fe5840672 100644 --- a/engine/src/Enums/RangeType.ts +++ b/engine/src/Enums/RangeType.ts @@ -1,4 +1,7 @@ +/** Spatial range types */ export enum RangeType { + /** Circular range */ circle = "circle", + /** Rectangular range */ rectangle = "rectangle", } diff --git a/engine/src/Enums/Types/AlterType.ts b/engine/src/Enums/Types/AlterType.ts index 7b65884aa9e..8fd3d9388e6 100644 --- a/engine/src/Enums/Types/AlterType.ts +++ b/engine/src/Enums/Types/AlterType.ts @@ -1,4 +1,7 @@ +/** Color alteration types */ export enum AlterType { + /** Darkens the color */ darken = "darken", + /** Lightens the color */ enlighten = "enlighten", } diff --git a/engine/src/Enums/Types/DestroyType.ts b/engine/src/Enums/Types/DestroyType.ts index 16a77ce2eab..3992a91adeb 100644 --- a/engine/src/Enums/Types/DestroyType.ts +++ b/engine/src/Enums/Types/DestroyType.ts @@ -1,7 +1,9 @@ -/** - */ +/** Destroy type values for particle destruction */ export enum DestroyType { + /** No destruction */ none = "none", + /** Destroy when reaching the maximum value */ max = "max", + /** Destroy when reaching the minimum value */ min = "min", } diff --git a/engine/src/Enums/Types/EasingType.ts b/engine/src/Enums/Types/EasingType.ts index 84fede0b4ac..0c2b9fcb6b1 100644 --- a/engine/src/Enums/Types/EasingType.ts +++ b/engine/src/Enums/Types/EasingType.ts @@ -1,48 +1,92 @@ +/** Easing type values for animations */ export enum EasingType { + /** Ease-in back easing */ easeInBack = "ease-in-back", + /** Ease-in bounce easing */ easeInBounce = "ease-in-bounce", + /** Ease-in circular easing */ easeInCirc = "ease-in-circ", + /** Ease-in cubic easing */ easeInCubic = "ease-in-cubic", + /** Ease-in elastic easing */ easeInElastic = "ease-in-elastic", + /** Ease-in exponential easing */ easeInExpo = "ease-in-expo", + /** Ease-in gaussian easing */ easeInGaussian = "ease-in-gaussian", + /** Ease-in linear easing */ easeInLinear = "ease-in-linear", + /** Ease-in quadratic easing */ easeInQuad = "ease-in-quad", + /** Ease-in quartic easing */ easeInQuart = "ease-in-quart", + /** Ease-in quintic easing */ easeInQuint = "ease-in-quint", + /** Ease-in sigmoid easing */ easeInSigmoid = "ease-in-sigmoid", + /** Ease-in sine easing */ easeInSine = "ease-in-sine", + /** Ease-in smoothstep easing */ easeInSmoothstep = "ease-in-smoothstep", + /** Ease-out back easing */ easeOutBack = "ease-out-back", + /** Ease-out bounce easing */ easeOutBounce = "ease-out-bounce", + /** Ease-out circular easing */ easeOutCirc = "ease-out-circ", + /** Ease-out cubic easing */ easeOutCubic = "ease-out-cubic", + /** Ease-out elastic easing */ easeOutElastic = "ease-out-elastic", + /** Ease-out exponential easing */ easeOutExpo = "ease-out-expo", + /** Ease-out gaussian easing */ easeOutGaussian = "ease-out-gaussian", + /** Ease-out linear easing */ easeOutLinear = "ease-out-linear", + /** Ease-out quadratic easing */ easeOutQuad = "ease-out-quad", + /** Ease-out quartic easing */ easeOutQuart = "ease-out-quart", + /** Ease-out quintic easing */ easeOutQuint = "ease-out-quint", + /** Ease-out sigmoid easing */ easeOutSigmoid = "ease-out-sigmoid", + /** Ease-out sine easing */ easeOutSine = "ease-out-sine", + /** Ease-out smoothstep easing */ easeOutSmoothstep = "ease-out-smoothstep", + /** Ease-in-out back easing */ easeInOutBack = "ease-in-out-back", + /** Ease-in-out bounce easing */ easeInOutBounce = "ease-in-out-bounce", + /** Ease-in-out circular easing */ easeInOutCirc = "ease-in-out-circ", + /** Ease-in-out cubic easing */ easeInOutCubic = "ease-in-out-cubic", + /** Ease-in-out elastic easing */ easeInOutElastic = "ease-in-out-elastic", + /** Ease-in-out exponential easing */ easeInOutExpo = "ease-in-out-expo", + /** Ease-in-out gaussian easing */ easeInOutGaussian = "ease-in-out-gaussian", + /** Ease-in-out linear easing */ easeInOutLinear = "ease-in-out-linear", + /** Ease-in-out quadratic easing */ easeInOutQuad = "ease-in-out-quad", + /** Ease-in-out quartic easing */ easeInOutQuart = "ease-in-out-quart", + /** Ease-in-out quintic easing */ easeInOutQuint = "ease-in-out-quint", + /** Ease-in-out sigmoid easing */ easeInOutSigmoid = "ease-in-out-sigmoid", + /** Ease-in-out sine easing */ easeInOutSine = "ease-in-out-sine", + /** Ease-in-out smoothstep easing */ easeInOutSmoothstep = "ease-in-out-smoothstep", } +/** Alternative easing type values as a string literal union */ export type EasingTypeAlt = | "ease-in-back" | "ease-out-back" diff --git a/engine/src/Enums/Types/EventType.ts b/engine/src/Enums/Types/EventType.ts index 4c7ee46becb..093d66bd03a 100644 --- a/engine/src/Enums/Types/EventType.ts +++ b/engine/src/Enums/Types/EventType.ts @@ -1,14 +1,27 @@ +/** Event types emitted by the engine */ export enum EventType { + /** A configuration has been added */ configAdded = "configAdded", + /** A container has been initialized */ containerInit = "containerInit", + /** Particles have been set up */ particlesSetup = "particlesSetup", + /** A container has started */ containerStarted = "containerStarted", + /** A container has stopped */ containerStopped = "containerStopped", + /** A container has been destroyed */ containerDestroyed = "containerDestroyed", + /** A container has been paused */ containerPaused = "containerPaused", + /** A container has resumed playback */ containerPlay = "containerPlay", + /** A container has been built */ containerBuilt = "containerBuilt", + /** A particle has been added */ particleAdded = "particleAdded", + /** A particle has been destroyed */ particleDestroyed = "particleDestroyed", + /** A particle has been removed */ particleRemoved = "particleRemoved", } diff --git a/engine/src/Enums/Types/GradientType.ts b/engine/src/Enums/Types/GradientType.ts index 14eef9f0269..008ba16379f 100644 --- a/engine/src/Enums/Types/GradientType.ts +++ b/engine/src/Enums/Types/GradientType.ts @@ -1,5 +1,9 @@ +/** Gradient type values */ export enum GradientType { + /** Linear gradient */ linear = "linear", + /** Radial gradient */ radial = "radial", + /** Random gradient type */ random = "random", } diff --git a/engine/src/Enums/Types/ParticleOutType.ts b/engine/src/Enums/Types/ParticleOutType.ts index 0fa66c2750c..fdfe6a29c35 100644 --- a/engine/src/Enums/Types/ParticleOutType.ts +++ b/engine/src/Enums/Types/ParticleOutType.ts @@ -1,5 +1,9 @@ +/** Particle out type values */ export enum ParticleOutType { + /** Normal out behavior */ normal = "normal", + /** Particle is inside the canvas */ inside = "inside", + /** Particle is outside the canvas */ outside = "outside", } diff --git a/engine/src/Enums/Types/StartValueType.ts b/engine/src/Enums/Types/StartValueType.ts index 42032914382..e22fc9dbdfb 100644 --- a/engine/src/Enums/Types/StartValueType.ts +++ b/engine/src/Enums/Types/StartValueType.ts @@ -1,7 +1,9 @@ -/** - */ +/** Start value types for animations */ export enum StartValueType { + /** Start from the maximum value */ max = "max", + /** Start from the minimum value */ min = "min", + /** Start from a random value */ random = "random", } diff --git a/engine/src/Options/Classes/AnimatableColor.ts b/engine/src/Options/Classes/AnimatableColor.ts index cb58622addf..f726022ec53 100644 --- a/engine/src/Options/Classes/AnimatableColor.ts +++ b/engine/src/Options/Classes/AnimatableColor.ts @@ -20,6 +20,12 @@ export class AnimatableColor extends OptionsColor implements IAnimatableColor, I this.animation = new HslAnimation(); } + /** + * Creates an animatable color from optional source and input data. + * @param source - Existing color instance to clone from. + * @param data - Color input data. + * @returns A configured animatable color instance. + */ static override create( source?: AnimatableColor, data?: SingleOrMultiple | RecursivePartial, diff --git a/engine/src/Options/Classes/AnimationOptions.ts b/engine/src/Options/Classes/AnimationOptions.ts index cdb44c5994a..1c2875f6824 100644 --- a/engine/src/Options/Classes/AnimationOptions.ts +++ b/engine/src/Options/Classes/AnimationOptions.ts @@ -7,12 +7,19 @@ import { StartValueType } from "../../Enums/Types/StartValueType.js"; import { isNull } from "../../Utils/TypeUtils.js"; import { setRangeValue } from "../../Utils/MathUtils.js"; +/** Animation options configuration class */ export class AnimationOptions implements IAnimation, IOptionLoader { + /** Number of animation loops (0 = infinite) */ count: RangeValue; + /** Animation decay factor */ decay: RangeValue; + /** Delay before animation starts */ delay: RangeValue; + /** Enables the animation */ enable; + /** Animation speed */ speed: RangeValue; + /** Whether the animation is synchronized across particles */ sync; constructor() { @@ -55,9 +62,12 @@ export class AnimationOptions implements IAnimation, IOptionLoader { } } +/** Ranged animation options with mode and start value */ export class RangedAnimationOptions extends AnimationOptions implements IOptionLoader { + /** Animation mode (auto, increase, decrease, random) */ mode: AnimationMode | keyof typeof AnimationMode; + /** Start value type for the animation */ startValue: StartValueType | keyof typeof StartValueType; constructor() { diff --git a/engine/src/Options/Classes/ColorAnimation.ts b/engine/src/Options/Classes/ColorAnimation.ts index ebea724d1ac..d647bf36705 100644 --- a/engine/src/Options/Classes/ColorAnimation.ts +++ b/engine/src/Options/Classes/ColorAnimation.ts @@ -6,11 +6,13 @@ import type { RecursivePartial } from "../../Types/RecursivePartial.js"; import { isNull } from "../../Utils/TypeUtils.js"; import { setRangeValue } from "../../Utils/MathUtils.js"; -/** - */ +/** Color animation options class */ export class ColorAnimation extends AnimationOptions implements IColorAnimation, IOptionLoader { + /** Maximum color value */ max; + /** Minimum color value */ min; + /** Color value offset */ offset: RangeValue; constructor(min: number, max: number) { @@ -22,6 +24,10 @@ export class ColorAnimation extends AnimationOptions implements IColorAnimation, this.sync = true; } + /** + * Loads color animation options from the given data + * @param data + */ override load(data?: RecursivePartial): void { super.load(data); diff --git a/engine/src/Options/Classes/Options.ts b/engine/src/Options/Classes/Options.ts index 6a90d603ea2..8f3ad6cf53a 100644 --- a/engine/src/Options/Classes/Options.ts +++ b/engine/src/Options/Classes/Options.ts @@ -14,8 +14,11 @@ import type { SingleOrMultiple } from "../../Types/SingleOrMultiple.js"; import { loadParticlesOptions } from "../../Utils/OptionsUtils.js"; import { setRangeValue } from "../../Utils/MathUtils.js"; -interface DefaultThemes { +/** Default themes configuration */ +export interface DefaultThemes { + /** The default dark theme */ dark?: string; + /** The default light theme */ light?: string; } @@ -25,26 +28,47 @@ interface DefaultThemes { export class Options implements IOptions, IOptionLoader { [name: string]: unknown; + /** The autoPlay flag */ autoPlay; + /** The background options */ readonly background; + /** The clear flag */ clear: boolean; + /** The default themes */ defaultThemes: DefaultThemes; + /** The delay value */ delay: RangeValue; + /** The detect retina flag */ detectRetina; + /** The duration value */ duration: RangeValue; + /** The FPS limit */ fpsLimit; + /** The full screen options */ readonly fullScreen; + /** The HDR flag */ hdr; + /** The key value */ key?: string; + /** The name value */ name?: string; + /** The palette value */ palette?: string; + /** The particles options */ readonly particles; + /** The pause on blur flag */ pauseOnBlur; + /** The pause on outside viewport flag */ pauseOnOutsideViewport; + /** The preset value */ preset?: SingleOrMultiple; + /** The resize options */ readonly resize; + /** The smooth flag */ smooth: boolean; + /** The style options */ style: RecursivePartial; + /** The z-layers value */ zLayers; private readonly _container; diff --git a/engine/src/Options/Classes/OptionsColor.ts b/engine/src/Options/Classes/OptionsColor.ts index 04f8163b2c3..917e798207f 100644 --- a/engine/src/Options/Classes/OptionsColor.ts +++ b/engine/src/Options/Classes/OptionsColor.ts @@ -36,6 +36,12 @@ export class OptionsColor implements IOptionsColor, IOptionLoader this.value = ""; } + /** + * Creates an options color from optional source and input data. + * @param source - Existing color instance to clone from. + * @param data - Color input data. + * @returns A configured color instance. + */ static create( source?: OptionsColor, data?: SingleOrMultiple | RecursivePartial, diff --git a/engine/src/Options/Classes/Particles/Effect/Effect.ts b/engine/src/Options/Classes/Particles/Effect/Effect.ts index 64b039f59f7..10cc1cbae83 100644 --- a/engine/src/Options/Classes/Particles/Effect/Effect.ts +++ b/engine/src/Options/Classes/Particles/Effect/Effect.ts @@ -11,8 +11,11 @@ import { isNull } from "../../../../Utils/TypeUtils.js"; * [[include:Options/Particles/Effect.md]] */ export class Effect implements IEffect, IOptionLoader { + /** Whether the effect shape is closed */ close; + /** Effect shape options data */ options: ShapeData; + /** Effect type name or array of names */ type: SingleOrMultiple; constructor() { diff --git a/engine/src/Options/Classes/Particles/Move/MoveAngle.ts b/engine/src/Options/Classes/Particles/Move/MoveAngle.ts index 3a828c47482..07075eb7d70 100644 --- a/engine/src/Options/Classes/Particles/Move/MoveAngle.ts +++ b/engine/src/Options/Classes/Particles/Move/MoveAngle.ts @@ -5,10 +5,11 @@ import type { RecursivePartial } from "../../../../Types/RecursivePartial.js"; import { isNull } from "../../../../Utils/TypeUtils.js"; import { setRangeValue } from "../../../../Utils/MathUtils.js"; -/** - */ +/** Movement angle options class */ export class MoveAngle implements IMoveAngle, IOptionLoader { + /** Angle offset value */ offset: RangeValue; + /** Angle value in degrees */ value: RangeValue; constructor() { @@ -16,6 +17,10 @@ export class MoveAngle implements IMoveAngle, IOptionLoader { this.value = 90; } + /** + * Loads move angle options from the given data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/engine/src/Options/Classes/Particles/Move/MoveGravity.ts b/engine/src/Options/Classes/Particles/Move/MoveGravity.ts index 8c58f0bc194..59bf2b81b47 100644 --- a/engine/src/Options/Classes/Particles/Move/MoveGravity.ts +++ b/engine/src/Options/Classes/Particles/Move/MoveGravity.ts @@ -5,10 +5,15 @@ import type { RecursivePartial } from "../../../../Types/RecursivePartial.js"; import { isNull } from "../../../../Utils/TypeUtils.js"; import { setRangeValue } from "../../../../Utils/MathUtils.js"; +/** Movement gravity options class */ export class MoveGravity implements IMoveGravity, IOptionLoader { + /** Gravity acceleration value */ acceleration: RangeValue; + /** Enables or disables gravity */ enable; + /** If true, gravity pulls particles upward instead of downward */ inverse; + /** Maximum speed limit for gravity-affected particles */ maxSpeed: RangeValue; constructor() { @@ -18,6 +23,10 @@ export class MoveGravity implements IMoveGravity, IOptionLoader { this.maxSpeed = 50; } + /** + * Loads gravity options from the given data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/engine/src/Options/Classes/Particles/Move/OutModes.ts b/engine/src/Options/Classes/Particles/Move/OutModes.ts index 5be27d0c89a..3c2218589f6 100644 --- a/engine/src/Options/Classes/Particles/Move/OutModes.ts +++ b/engine/src/Options/Classes/Particles/Move/OutModes.ts @@ -4,17 +4,27 @@ import { OutMode } from "../../../../Enums/Modes/OutMode.js"; import type { RecursivePartial } from "../../../../Types/RecursivePartial.js"; import { isNull } from "../../../../Utils/TypeUtils.js"; +/** Out modes options class */ export class OutModes implements IOutModes, IOptionLoader { + /** Out mode for the bottom edge */ bottom?: OutMode | keyof typeof OutMode; + /** Default out mode used when per-edge modes are not set */ default: OutMode | keyof typeof OutMode; + /** Out mode for the left edge */ left?: OutMode | keyof typeof OutMode; + /** Out mode for the right edge */ right?: OutMode | keyof typeof OutMode; + /** Out mode for the top edge */ top?: OutMode | keyof typeof OutMode; constructor() { this.default = OutMode.out; } + /** + * Loads out modes from the given data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/engine/src/Options/Classes/Particles/Move/Path/MovePath.ts b/engine/src/Options/Classes/Particles/Move/Path/MovePath.ts index fad9e9b3bf1..83000e7d4b6 100644 --- a/engine/src/Options/Classes/Particles/Move/Path/MovePath.ts +++ b/engine/src/Options/Classes/Particles/Move/Path/MovePath.ts @@ -7,6 +7,7 @@ import { deepExtend } from "../../../../../Utils/Utils.js"; import { isNull } from "../../../../../Utils/TypeUtils.js"; /** + * Path movement options. */ export class MovePath implements IMovePath, IOptionLoader { clamp; diff --git a/engine/src/Options/Classes/Particles/Number/ParticlesDensity.ts b/engine/src/Options/Classes/Particles/Number/ParticlesDensity.ts index 593f5c555ff..179f56c1fa2 100644 --- a/engine/src/Options/Classes/Particles/Number/ParticlesDensity.ts +++ b/engine/src/Options/Classes/Particles/Number/ParticlesDensity.ts @@ -4,6 +4,7 @@ import type { RecursivePartial } from "../../../../Types/RecursivePartial.js"; import { isNull } from "../../../../Utils/TypeUtils.js"; /** + * Density options used to scale particle count with area. */ export class ParticlesDensity implements IParticlesDensity, IOptionLoader { enable; diff --git a/engine/src/Options/Classes/Particles/Opacity/OpacityAnimation.ts b/engine/src/Options/Classes/Particles/Opacity/OpacityAnimation.ts index c9a422e6295..7c5bcf89c3d 100644 --- a/engine/src/Options/Classes/Particles/Opacity/OpacityAnimation.ts +++ b/engine/src/Options/Classes/Particles/Opacity/OpacityAnimation.ts @@ -6,6 +6,7 @@ import type { RecursivePartial } from "../../../../Types/RecursivePartial.js"; import { isNull } from "../../../../Utils/TypeUtils.js"; /** + * Opacity animation options. */ export class OpacityAnimation extends RangedAnimationOptions diff --git a/engine/src/Options/Classes/Particles/Size/SizeAnimation.ts b/engine/src/Options/Classes/Particles/Size/SizeAnimation.ts index f2ac1324e77..6c1d7e2837d 100644 --- a/engine/src/Options/Classes/Particles/Size/SizeAnimation.ts +++ b/engine/src/Options/Classes/Particles/Size/SizeAnimation.ts @@ -6,6 +6,7 @@ import type { RecursivePartial } from "../../../../Types/RecursivePartial.js"; import { isNull } from "../../../../Utils/TypeUtils.js"; /** + * Size animation options. */ export class SizeAnimation extends RangedAnimationOptions implements ISizeAnimation, IOptionLoader { destroy: DestroyType | keyof typeof DestroyType; diff --git a/engine/src/Options/Classes/Particles/ZIndex/ZIndex.ts b/engine/src/Options/Classes/Particles/ZIndex/ZIndex.ts index 1d16951cd36..662cc843fe9 100644 --- a/engine/src/Options/Classes/Particles/ZIndex/ZIndex.ts +++ b/engine/src/Options/Classes/Particles/ZIndex/ZIndex.ts @@ -5,6 +5,7 @@ import { ValueWithRandom } from "../../ValueWithRandom.js"; import { isNull } from "../../../../Utils/TypeUtils.js"; /** + * Z-index related particle behavior options. */ export class ZIndex extends ValueWithRandom implements IZIndex, IOptionLoader { opacityRate; diff --git a/engine/src/Options/Classes/ValueWithRandom.ts b/engine/src/Options/Classes/ValueWithRandom.ts index 4d1561d2dd9..4c74b0c931e 100644 --- a/engine/src/Options/Classes/ValueWithRandom.ts +++ b/engine/src/Options/Classes/ValueWithRandom.ts @@ -10,7 +10,9 @@ import type { RecursivePartial } from "../../Types/RecursivePartial.js"; import { isNull } from "../../Utils/TypeUtils.js"; import { setRangeValue } from "../../Utils/MathUtils.js"; +/** Value with random range option class */ export class ValueWithRandom implements IValueWithRandom, IOptionLoader { + /** The value or range of values */ value: RangeValue; constructor() { @@ -28,7 +30,9 @@ export class ValueWithRandom implements IValueWithRandom, IOptionLoader { + /** Animation options */ readonly animation = new AnimationOptions(); override load(data?: RecursivePartial): void { @@ -46,6 +50,7 @@ export class AnimationValueWithRandom extends ValueWithRandom implements IOption } } +/** Ranged animation value with random range option class */ export class RangedAnimationValueWithRandom extends AnimationValueWithRandom implements IOptionLoader diff --git a/engine/src/Options/Interfaces/IAnimatable.ts b/engine/src/Options/Interfaces/IAnimatable.ts index 78cf7bc658e..414976d761a 100644 --- a/engine/src/Options/Interfaces/IAnimatable.ts +++ b/engine/src/Options/Interfaces/IAnimatable.ts @@ -1,5 +1,8 @@ import type { IAnimation } from "./IAnimation.js"; +/** + * Marks an options object as containing animation settings. + */ export interface IAnimatable { /** * The animation property diff --git a/engine/src/Options/Interfaces/IAnimation.ts b/engine/src/Options/Interfaces/IAnimation.ts index 4dfc0b6e260..ff995fadd06 100644 --- a/engine/src/Options/Interfaces/IAnimation.ts +++ b/engine/src/Options/Interfaces/IAnimation.ts @@ -2,6 +2,9 @@ import type { AnimationMode } from "../../Enums/Modes/AnimationMode.js"; import type { RangeValue } from "../../Types/RangeValue.js"; import type { StartValueType } from "../../Enums/Types/StartValueType.js"; +/** + * Base animation settings. + */ export interface IAnimation { /** * Animation loop count @@ -35,8 +38,11 @@ export interface IAnimation { sync: boolean; } +/** Ranged animation options */ export interface IRangedAnimation extends IAnimation { + /** Animation mode */ mode: AnimationMode | keyof typeof AnimationMode; + /** Animation start value */ startValue: StartValueType | keyof typeof StartValueType; } diff --git a/engine/src/Options/Interfaces/IColorAnimation.ts b/engine/src/Options/Interfaces/IColorAnimation.ts index 73acafaab58..64235104579 100644 --- a/engine/src/Options/Interfaces/IColorAnimation.ts +++ b/engine/src/Options/Interfaces/IColorAnimation.ts @@ -1,11 +1,13 @@ -/** - * Color animation interface, these properties are used to animate colors - */ import type { IAnimation } from "./IAnimation.js"; import type { RangeValue } from "../../Types/RangeValue.js"; +/** + * Color animation settings. + */ export interface IColorAnimation extends IAnimation { + /** Maximum animation value */ max: number; + /** Minimum animation value */ min: number; /** diff --git a/engine/src/Options/Interfaces/IHslAnimation.ts b/engine/src/Options/Interfaces/IHslAnimation.ts index fb827b05f66..94a20c67478 100644 --- a/engine/src/Options/Interfaces/IHslAnimation.ts +++ b/engine/src/Options/Interfaces/IHslAnimation.ts @@ -1,5 +1,8 @@ import type { IColorAnimation } from "./IColorAnimation.js"; +/** + * HSL channel animation settings. + */ export interface IHslAnimation { /** * Animation for hue. diff --git a/engine/src/Options/Interfaces/IOptions.ts b/engine/src/Options/Interfaces/IOptions.ts index 90683c33bef..2f4eb44a3ab 100644 --- a/engine/src/Options/Interfaces/IOptions.ts +++ b/engine/src/Options/Interfaces/IOptions.ts @@ -71,6 +71,9 @@ export interface IOptions { */ name?: string; + /** + * The palette name to use for coloring particles + */ palette?: string; /** @@ -109,6 +112,9 @@ export interface IOptions { */ smooth: boolean; + /** + * Inline CSS style applied to the particles canvas element. + */ style: RecursivePartial; /** diff --git a/engine/src/Options/Interfaces/IResizeEvent.ts b/engine/src/Options/Interfaces/IResizeEvent.ts index 11d203a6c55..35b8aad65c5 100644 --- a/engine/src/Options/Interfaces/IResizeEvent.ts +++ b/engine/src/Options/Interfaces/IResizeEvent.ts @@ -1,3 +1,6 @@ +/** + * Resize handling settings. + */ export interface IResizeEvent { /** * This property is used to define the delay between resize events. diff --git a/engine/src/Options/Interfaces/IValueWithRandom.ts b/engine/src/Options/Interfaces/IValueWithRandom.ts index b174e85c1f3..8a2c505b74f 100644 --- a/engine/src/Options/Interfaces/IValueWithRandom.ts +++ b/engine/src/Options/Interfaces/IValueWithRandom.ts @@ -1,6 +1,7 @@ import type { IAnimation, IRangedAnimation } from "./IAnimation.js"; import type { RangeValue } from "../../Types/RangeValue.js"; +/** Value with random range configuration */ export interface IValueWithRandom { /** * Value of property. @@ -8,6 +9,7 @@ export interface IValueWithRandom { value: RangeValue; } +/** Animation value with random range configuration */ export interface IAnimationValueWithRandom extends IValueWithRandom { /** * Animation options, based on {@link value}. @@ -15,6 +17,7 @@ export interface IAnimationValueWithRandom extends IValueWithRandom { animation: IAnimation; } +/** Ranged animation value with random options */ export interface IRangedAnimationValueWithRandom extends IAnimationValueWithRandom { /** * Animation options, based on {@link value}. diff --git a/engine/src/Options/Interfaces/Particles/Bounce/IParticlesBounce.ts b/engine/src/Options/Interfaces/Particles/Bounce/IParticlesBounce.ts index e4804700b5b..fe2f3e5054d 100644 --- a/engine/src/Options/Interfaces/Particles/Bounce/IParticlesBounce.ts +++ b/engine/src/Options/Interfaces/Particles/Bounce/IParticlesBounce.ts @@ -1,6 +1,9 @@ import type { IValueWithRandom } from "../../IValueWithRandom.js"; +/** Particles bounce factor options */ export interface IParticlesBounce { + /** Horizontal bounce factor */ horizontal: IValueWithRandom; + /** Vertical bounce factor */ vertical: IValueWithRandom; } diff --git a/engine/src/Options/Interfaces/Particles/Effect/IEffect.ts b/engine/src/Options/Interfaces/Particles/Effect/IEffect.ts index e9985372aa9..cedea18761c 100644 --- a/engine/src/Options/Interfaces/Particles/Effect/IEffect.ts +++ b/engine/src/Options/Interfaces/Particles/Effect/IEffect.ts @@ -10,7 +10,9 @@ export interface IEffect { */ close: boolean; + /** Effect shape options data */ options: ShapeData; + /** Effect type name or array of names */ type: SingleOrMultiple; } diff --git a/engine/src/Options/Interfaces/Particles/Move/IMoveAngle.ts b/engine/src/Options/Interfaces/Particles/Move/IMoveAngle.ts index f30411a6fcd..b7758087b4f 100644 --- a/engine/src/Options/Interfaces/Particles/Move/IMoveAngle.ts +++ b/engine/src/Options/Interfaces/Particles/Move/IMoveAngle.ts @@ -1,8 +1,9 @@ import type { RangeValue } from "../../../../Types/RangeValue.js"; -/** - */ +/** Particle movement angle options */ export interface IMoveAngle { + /** Angle offset value */ offset: RangeValue; + /** Angle value in degrees */ value: RangeValue; } diff --git a/engine/src/Options/Interfaces/Particles/Move/IMoveCenter.ts b/engine/src/Options/Interfaces/Particles/Move/IMoveCenter.ts index c2794916cb7..343a02bd75b 100644 --- a/engine/src/Options/Interfaces/Particles/Move/IMoveCenter.ts +++ b/engine/src/Options/Interfaces/Particles/Move/IMoveCenter.ts @@ -1,3 +1,4 @@ import type { ICenterCoordinates } from "../../../../Core/Interfaces/ICoordinates.js"; +/** Move center position type */ export type IMoveCenter = ICenterCoordinates; diff --git a/engine/src/Options/Interfaces/Particles/Move/IMoveGravity.ts b/engine/src/Options/Interfaces/Particles/Move/IMoveGravity.ts index 3464744bfdc..bf088b4060a 100644 --- a/engine/src/Options/Interfaces/Particles/Move/IMoveGravity.ts +++ b/engine/src/Options/Interfaces/Particles/Move/IMoveGravity.ts @@ -1,8 +1,13 @@ import type { RangeValue } from "../../../../Types/RangeValue.js"; +/** Particle movement gravity options */ export interface IMoveGravity { + /** Gravity acceleration value */ acceleration: RangeValue; + /** Enables or disables gravity */ enable: boolean; + /** If true, gravity pulls particles upward instead of downward */ inverse: boolean; + /** Maximum speed limit for gravity-affected particles */ maxSpeed: RangeValue; } diff --git a/engine/src/Options/Interfaces/Particles/Move/IOutModes.ts b/engine/src/Options/Interfaces/Particles/Move/IOutModes.ts index 437b03215b6..b2bbe449046 100644 --- a/engine/src/Options/Interfaces/Particles/Move/IOutModes.ts +++ b/engine/src/Options/Interfaces/Particles/Move/IOutModes.ts @@ -1,9 +1,15 @@ import type { OutMode } from "../../../../Enums/Modes/OutMode.js"; +/** Out modes configuration for each canvas edge */ export interface IOutModes { + /** Out mode for the bottom edge */ bottom?: OutMode | keyof typeof OutMode; + /** Default out mode used when per-edge modes are not set */ default: OutMode | keyof typeof OutMode; + /** Out mode for the left edge */ left?: OutMode | keyof typeof OutMode; + /** Out mode for the right edge */ right?: OutMode | keyof typeof OutMode; + /** Out mode for the top edge */ top?: OutMode | keyof typeof OutMode; } diff --git a/engine/src/Options/Interfaces/Particles/Move/ISpin.ts b/engine/src/Options/Interfaces/Particles/Move/ISpin.ts index 9df8b154a50..523e6d4c7e0 100644 --- a/engine/src/Options/Interfaces/Particles/Move/ISpin.ts +++ b/engine/src/Options/Interfaces/Particles/Move/ISpin.ts @@ -1,8 +1,12 @@ import type { ICoordinatesWithMode } from "../../../../Core/Interfaces/ICoordinates.js"; import type { RangeValue } from "../../../../Types/RangeValue.js"; +/** Spin animation options */ export interface ISpin { + /** Spin acceleration */ acceleration: RangeValue; + /** Enables/disables the spin */ enable: boolean; + /** Spin center position */ position?: ICoordinatesWithMode; } diff --git a/engine/src/Options/Interfaces/Particles/Move/Path/IMovePath.ts b/engine/src/Options/Interfaces/Particles/Move/Path/IMovePath.ts index 7a247d45037..b1a7286f342 100644 --- a/engine/src/Options/Interfaces/Particles/Move/Path/IMovePath.ts +++ b/engine/src/Options/Interfaces/Particles/Move/Path/IMovePath.ts @@ -1,8 +1,7 @@ import type { IValueWithRandom } from "../../../IValueWithRandom.js"; import type { PathOptions } from "../../../../../Types/PathOptions.js"; -/** - */ +/** Move path options */ export interface IMovePath { /** * Checks if the output value is clamped between -1 and 1, the velocity range, values out of range must be handled correctly. diff --git a/engine/src/Options/Interfaces/Particles/Number/IParticlesDensity.ts b/engine/src/Options/Interfaces/Particles/Number/IParticlesDensity.ts index 48e961f0d18..67d7dca2940 100644 --- a/engine/src/Options/Interfaces/Particles/Number/IParticlesDensity.ts +++ b/engine/src/Options/Interfaces/Particles/Number/IParticlesDensity.ts @@ -1,5 +1,4 @@ -/** - */ +/** Particles density options */ export interface IParticlesDensity { /** * Enable density to increase or reduce the number of particles depending on the size of the container diff --git a/engine/src/Options/Interfaces/Particles/Number/IParticlesNumberLimit.ts b/engine/src/Options/Interfaces/Particles/Number/IParticlesNumberLimit.ts index 6f0370d5566..d33e14db5b0 100644 --- a/engine/src/Options/Interfaces/Particles/Number/IParticlesNumberLimit.ts +++ b/engine/src/Options/Interfaces/Particles/Number/IParticlesNumberLimit.ts @@ -1,5 +1,6 @@ import type { LimitMode } from "../../../../Enums/Modes/LimitMode.js"; +/** Particles number limit options */ export interface IParticlesNumberLimit { /** * The mode of handling the limit diff --git a/engine/src/Options/Interfaces/Particles/Opacity/IOpacityAnimation.ts b/engine/src/Options/Interfaces/Particles/Opacity/IOpacityAnimation.ts index 9904856a927..f98968bd6b3 100644 --- a/engine/src/Options/Interfaces/Particles/Opacity/IOpacityAnimation.ts +++ b/engine/src/Options/Interfaces/Particles/Opacity/IOpacityAnimation.ts @@ -1,8 +1,7 @@ import type { DestroyType } from "../../../../Enums/Types/DestroyType.js"; import type { IRangedAnimation } from "../../IAnimation.js"; -/** - */ +/** Opacity animation options */ export interface IOpacityAnimation extends IRangedAnimation { /** * The value to use for destroying the particle. diff --git a/engine/src/Options/Interfaces/Particles/Size/ISizeAnimation.ts b/engine/src/Options/Interfaces/Particles/Size/ISizeAnimation.ts index 742c30da852..96959da7830 100644 --- a/engine/src/Options/Interfaces/Particles/Size/ISizeAnimation.ts +++ b/engine/src/Options/Interfaces/Particles/Size/ISizeAnimation.ts @@ -1,8 +1,7 @@ import type { DestroyType } from "../../../../Enums/Types/DestroyType.js"; import type { IRangedAnimation } from "../../IAnimation.js"; -/** - */ +/** Size animation options */ export interface ISizeAnimation extends IRangedAnimation { /** * The value to use for destroying the particle. diff --git a/engine/src/Types/CanvasContextType.ts b/engine/src/Types/CanvasContextType.ts index 6a52a153883..86adc71aff7 100644 --- a/engine/src/Types/CanvasContextType.ts +++ b/engine/src/Types/CanvasContextType.ts @@ -1 +1,4 @@ +/** + * Supported canvas rendering contexts. + */ export type CanvasContextType = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D; diff --git a/engine/src/Types/CustomEventArgs.ts b/engine/src/Types/CustomEventArgs.ts index 53149425513..94095bf3292 100644 --- a/engine/src/Types/CustomEventArgs.ts +++ b/engine/src/Types/CustomEventArgs.ts @@ -1,6 +1,9 @@ import type { Container } from "../Core/Container.js"; +/** Custom event arguments with optional container reference and data */ export interface CustomEventArgs { + /** The container that emitted the event */ container?: Container; + /** Additional event data */ data?: unknown; } diff --git a/engine/src/Types/CustomEventListener.ts b/engine/src/Types/CustomEventListener.ts index 89a4a598971..c50a1569864 100644 --- a/engine/src/Types/CustomEventListener.ts +++ b/engine/src/Types/CustomEventListener.ts @@ -1,3 +1,6 @@ import type { CustomEventArgs } from "./CustomEventArgs.js"; +/** + * Event listener used by the engine event dispatcher. + */ export type CustomEventListener = (args?: CustomEventArgs) => void; diff --git a/engine/src/Types/EasingFunction.ts b/engine/src/Types/EasingFunction.ts index b9a177f6288..480abac237c 100644 --- a/engine/src/Types/EasingFunction.ts +++ b/engine/src/Types/EasingFunction.ts @@ -1 +1,4 @@ +/** + * Generic easing function mapping a progress value to an eased value. + */ export type EasingFunction = (value: number) => number; diff --git a/engine/src/Types/EngineInitializers.ts b/engine/src/Types/EngineInitializers.ts index 64a3cb293fa..ca81b293a96 100644 --- a/engine/src/Types/EngineInitializers.ts +++ b/engine/src/Types/EngineInitializers.ts @@ -3,13 +3,21 @@ import type { IEffectDrawer } from "../Core/Interfaces/IEffectDrawer.js"; import type { IParticleUpdater } from "../Core/Interfaces/IParticleUpdater.js"; import type { IShapeDrawer } from "../Core/Interfaces/IShapeDrawer.js"; +/** Generic initializer function type that takes a container and returns a promise */ export type GenericInitializer = (container: Container) => Promise; +/** Effect drawer initializer type */ export type EffectInitializer = GenericInitializer; +/** Shape drawer initializer type */ export type ShapeInitializer = GenericInitializer; +/** Particle updater initializer type */ export type UpdaterInitializer = GenericInitializer; +/** Collection of initializers for effects, shapes, and updaters */ export interface Initializers { + /** Effect drawer initializers mapped by name */ effects: Map; + /** Shape drawer initializers mapped by name */ shapes: Map; + /** Particle updater initializers mapped by name */ updaters: Map; } diff --git a/engine/src/Types/ExportResult.ts b/engine/src/Types/ExportResult.ts index 5ae141e67f2..7039bc7e843 100644 --- a/engine/src/Types/ExportResult.ts +++ b/engine/src/Types/ExportResult.ts @@ -1,5 +1,9 @@ +/** Export operation result */ export interface ExportResult { + /** The exported blob data, if successful */ blob?: Blob; + /** Error information if export failed */ error?: Error; + /** Whether the export format is supported */ supported: boolean; } diff --git a/engine/src/Types/ISourceOptions.ts b/engine/src/Types/ISourceOptions.ts index bc8947b2017..84830a6b612 100644 --- a/engine/src/Types/ISourceOptions.ts +++ b/engine/src/Types/ISourceOptions.ts @@ -1,4 +1,7 @@ import type { IOptions } from "../Options/Interfaces/IOptions.js"; import type { RecursivePartial } from "./RecursivePartial.js"; +/** + * User-provided options input accepted by loaders. + */ export type ISourceOptions = RecursivePartial; diff --git a/engine/src/Types/PathOptions.ts b/engine/src/Types/PathOptions.ts index 1bfaa8fc351..e74a4e08747 100644 --- a/engine/src/Types/PathOptions.ts +++ b/engine/src/Types/PathOptions.ts @@ -1 +1,4 @@ +/** + * Generic options container for custom path generators. + */ export type PathOptions = Record; diff --git a/engine/src/Types/RangeValue.ts b/engine/src/Types/RangeValue.ts index 9111da10dd2..ff382fe9b48 100644 --- a/engine/src/Types/RangeValue.ts +++ b/engine/src/Types/RangeValue.ts @@ -1,3 +1,6 @@ import type { IRangeValue } from "../Core/Interfaces/IRangeValue.js"; +/** + * Numeric value that can be a fixed number or a min/max range object. + */ export type RangeValue = number | IRangeValue; diff --git a/engine/src/Types/RecursivePartial.ts b/engine/src/Types/RecursivePartial.ts index 49bea4f0305..51147d9390e 100644 --- a/engine/src/Types/RecursivePartial.ts +++ b/engine/src/Types/RecursivePartial.ts @@ -1,4 +1,5 @@ /** + * Recursive partial helper type used by options loaders. */ export type RecursivePartial = { [P in keyof T]?: T[P] extends (infer U)[] diff --git a/engine/src/Types/ShapeData.ts b/engine/src/Types/ShapeData.ts index 1a7e035bbe3..ac7bd3ed0b9 100644 --- a/engine/src/Types/ShapeData.ts +++ b/engine/src/Types/ShapeData.ts @@ -2,5 +2,6 @@ import type { IShapeValues } from "../Core/Interfaces/IShapeValues.js"; import type { SingleOrMultiple } from "./SingleOrMultiple.js"; /** + * Shape name to shape options mapping. */ export type ShapeData = Record>; diff --git a/engine/src/Types/SingleOrMultiple.ts b/engine/src/Types/SingleOrMultiple.ts index b2f271995ca..fb35c901186 100644 --- a/engine/src/Types/SingleOrMultiple.ts +++ b/engine/src/Types/SingleOrMultiple.ts @@ -1,3 +1,4 @@ /** + * Utility type that accepts either one value or an array of values. */ export type SingleOrMultiple = T | T[]; diff --git a/engine/src/Utils/ColorUtils.ts b/engine/src/Utils/ColorUtils.ts index a0a748e36fd..1433a4bec15 100644 --- a/engine/src/Utils/ColorUtils.ts +++ b/engine/src/Utils/ColorUtils.ts @@ -462,11 +462,12 @@ function getSdrStyleFromHsl(color: IHsl, opacity?: number): string { } /** - * @param color1 - - * @param color2 - - * @param size1 - - * @param size2 - - * @returns the return value is a color mix between the two parameters, using sizes to mix more the biggest value + * Mixes two colors based on size proportions + * @param color1 - the first color + * @param color2 - the second color + * @param size1 - the size of the first color + * @param size2 - the size of the second color + * @returns the mixed RGB color */ export function colorMix(color1: IRgb | IHsl, color2: IRgb | IHsl, size1: number, size2: number): IRgb { let rgb1 = color1 as IRgb, @@ -488,10 +489,11 @@ export function colorMix(color1: IRgb | IHsl, color2: IRgb | IHsl, size1: number } /** - * @param p1 - - * @param p2 - - * @param linkColor - - * @returns the link color calculated using the two linked particles + * Gets the link color between two linked particles + * @param p1 - the first particle + * @param p2 - the second particle + * @param linkColor - the link color configuration + * @returns the calculated link color */ export function getLinkColor(p1: Particle, p2?: Particle, linkColor?: string | IRgb): IRgb | undefined { if (linkColor === randomColorValue) { @@ -517,11 +519,12 @@ export function getLinkColor(p1: Particle, p2?: Particle, linkColor?: string | I } /** - * @param pluginManager - - * @param optColor - - * @param blink - - * @param consent - - * @returns returns a link random color, if needed + * Gets a random link color or a specific one based on parameters + * @param pluginManager - the plugin manager + * @param optColor - the color option + * @param blink - whether the link color blinks + * @param consent - whether the user consented + * @returns a link color */ export function getLinkRandomColor( pluginManager: PluginManager, @@ -553,8 +556,9 @@ export function getLinkRandomColor( } /** - * @param animation - - * @returns returns an animatable HSL color, if needed + * Gets the HSL color values from an HSL animation + * @param animation - the HSL animation to extract values from + * @returns the HSL color or undefined */ export function getHslFromAnimation(animation?: IParticleHslAnimation): IHsl | undefined { return animation === undefined @@ -567,10 +571,11 @@ export function getHslFromAnimation(animation?: IParticleHslAnimation): IHsl | u } /** - * @param hsl - - * @param animationOptions - - * @param reduceFactor - - * @returns returns the particle HSL animation values + * Creates an HSL animation from a base HSL color and animation options + * @param hsl - the base HSL color + * @param animationOptions - the HSL animation options + * @param reduceFactor - the reduce factor for velocity + * @returns the HSL animation data */ export function getHslAnimationFromHsl( hsl: IHsl, @@ -644,9 +649,10 @@ function setColorAnimation( } /** - * @param data - - * @param decrease - - * @param delta - + * Updates a color animation value for the current frame + * @param data - the color animation data + * @param decrease - whether the color should decrease over time + * @param delta - the frame delta time */ export function updateColorValue(data: IParticleColorAnimation, decrease: boolean, delta: IDelta): void { const minLoops = 0, @@ -711,8 +717,9 @@ export function updateColorValue(data: IParticleColorAnimation, decrease: boolea } /** - * @param color - - * @param delta - + * Updates all HSL color channels for the current frame + * @param color - the HSL animation to update + * @param delta - the frame delta time */ export function updateColor(color: IParticleHslAnimation | undefined, delta: IDelta): void { if (!color) { diff --git a/engine/src/Utils/EventDispatcher.ts b/engine/src/Utils/EventDispatcher.ts index 8c9769f322a..8c9d10c2faf 100644 --- a/engine/src/Utils/EventDispatcher.ts +++ b/engine/src/Utils/EventDispatcher.ts @@ -2,8 +2,7 @@ import { deleteCount, minIndex } from "../Core/Utils/Constants.js"; import type { CustomEventArgs } from "../Types/CustomEventArgs.js"; import type { CustomEventListener } from "../Types/CustomEventListener.js"; -/** - */ +/** Custom event dispatcher for managing event listeners */ export class EventDispatcher { private _listeners: Map; @@ -11,6 +10,11 @@ export class EventDispatcher { this._listeners = new Map(); } + /** + * Adds an event listener for the given type + * @param type + * @param listener + */ addEventListener(type: string, listener: CustomEventListener): void { this.removeEventListener(type, listener); @@ -25,6 +29,11 @@ export class EventDispatcher { arr.push(listener); } + /** + * Dispatches an event to all registered listeners + * @param type + * @param args + */ dispatchEvent(type: string, args?: CustomEventArgs): void { const listeners = this._listeners.get(type); @@ -33,10 +42,18 @@ export class EventDispatcher { }); } + /** + * Checks if any listeners are registered for the given type + * @param type + */ hasEventListener(type: string): boolean { return !!this._listeners.get(type); } + /** + * Removes all event listeners, optionally filtered by type + * @param type + */ removeAllEventListeners(type?: string): void { if (!type) { this._listeners = new Map(); @@ -45,6 +62,11 @@ export class EventDispatcher { } } + /** + * Removes a specific event listener + * @param type + * @param listener + */ removeEventListener(type: string, listener: CustomEventListener): void { const arr = this._listeners.get(type); diff --git a/engine/src/Utils/LogUtils.ts b/engine/src/Utils/LogUtils.ts index 65757f5ae84..1dbf86a345e 100644 --- a/engine/src/Utils/LogUtils.ts +++ b/engine/src/Utils/LogUtils.ts @@ -1,25 +1,33 @@ /* eslint-disable no-console */ const errorPrefix = "tsParticles - Error"; -interface ILogger { +/** Logger interface for tsParticles */ +export interface ILogger { + /** Debug log */ // eslint-disable-next-line @typescript-eslint/no-invalid-void-type debug(this: void, message?: unknown, ...optionalParams: unknown[]): void; + /** Error log */ // eslint-disable-next-line @typescript-eslint/no-invalid-void-type error(this: void, message?: unknown, ...optionalParams: unknown[]): void; + /** Info log */ // eslint-disable-next-line @typescript-eslint/no-invalid-void-type info(this: void, message?: unknown, ...optionalParams: unknown[]): void; + /** General log */ // eslint-disable-next-line @typescript-eslint/no-invalid-void-type log(this: void, message?: unknown, ...optionalParams: unknown[]): void; + /** Trace log */ // eslint-disable-next-line @typescript-eslint/no-invalid-void-type trace(this: void, ...data: unknown[]): void; + /** Verbose log */ // eslint-disable-next-line @typescript-eslint/no-invalid-void-type verbose(this: void, message?: unknown, ...optionalParams: unknown[]): void; + /** Warning log */ // eslint-disable-next-line @typescript-eslint/no-invalid-void-type warning(this: void, message?: unknown, ...optionalParams: unknown[]): void; } diff --git a/engine/src/Utils/OptionsUtils.ts b/engine/src/Utils/OptionsUtils.ts index 0473e4c3001..360d3325f3b 100644 --- a/engine/src/Utils/OptionsUtils.ts +++ b/engine/src/Utils/OptionsUtils.ts @@ -6,8 +6,9 @@ import type { PluginManager } from "../Core/Utils/PluginManager.js"; import type { RecursivePartial } from "../Types/RecursivePartial.js"; /** - * @param options - - * @param sourceOptionsArr - + * Loads one or more partial source options into an option loader. + * @param options - Target option loader. + * @param sourceOptionsArr - Source option chunks to merge. */ export function loadOptions( options: IOptionLoader, diff --git a/engine/src/Utils/Utils.ts b/engine/src/Utils/Utils.ts index f2aee701ab8..9561df5cfb2 100644 --- a/engine/src/Utils/Utils.ts +++ b/engine/src/Utils/Utils.ts @@ -32,9 +32,15 @@ import { Vector } from "../Core/Utils/Vectors.js"; const minRadius = 0, minMemoizeSize = 0; -interface MemoizeOptions { +/** + * Memoize function options + */ +export interface MemoizeOptions { + /** Custom key function for cache lookups */ keyFn?: (args: TArgs) => string; + /** Maximum cache size */ maxSize?: number; + /** Time-to-live in milliseconds */ ttlMs?: number; } @@ -166,7 +172,8 @@ export function safeDocument(): Document { } /** - * @param query - + * Safely queries a media query string + * @param query - the media query string * @returns the media query list, if supported */ export function safeMatchMedia(query: string): MediaQueryList | undefined { @@ -178,8 +185,9 @@ export function safeMatchMedia(query: string): MediaQueryList | undefined { } /** - * @param callback - - * @returns the interaction observer, if supported + * Safely creates an IntersectionObserver if supported + * @param callback - the observer callback + * @returns the intersection observer, if supported */ export function safeIntersectionObserver( callback: (records: IntersectionObserverEntry[]) => void, @@ -192,7 +200,8 @@ export function safeIntersectionObserver( } /** - * @param callback - + * Safely creates a MutationObserver if supported + * @param callback - the observer callback * @returns the mutation observer, if supported */ export function safeMutationObserver(callback: (records: MutationRecord[]) => void): MutationObserver | undefined { @@ -645,11 +654,12 @@ function checkDestroy( } /** - * @param particle - - * @param data - - * @param changeDirection - - * @param destroyType - - * @param delta - + * Updates a numeric particle animation state. + * @param particle - Particle owning the animated value. + * @param data - Numeric animation state. + * @param changeDirection - Whether the animation should ping-pong. + * @param destroyType - Destroy behavior applied at bounds. + * @param delta - Frame delta data. */ export function updateAnimation( particle: Particle, @@ -780,9 +790,9 @@ export function cloneStyle(style: Partial): CSSStyleDeclara } /** - * - * @param zIndex - the z-index value - * @returns the full screen style + * Computes full-screen canvas style for a given z-index. + * @param zIndex - The z-index value. + * @returns Full-screen CSS style declaration. */ function computeFullScreenStyle(zIndex: number): CSSStyleDeclaration { const fullScreenStyle = safeDocument().createElement("div").style, @@ -814,6 +824,9 @@ function computeFullScreenStyle(zIndex: number): CSSStyleDeclaration { return fullScreenStyle; } +/** + * Memoized full-screen style builder. + */ export const getFullScreenStyle = memoize(computeFullScreenStyle); /** diff --git a/engine/src/index.lazy.ts b/engine/src/index.lazy.ts index aa2f6282228..1347f1e558d 100644 --- a/engine/src/index.lazy.ts +++ b/engine/src/index.lazy.ts @@ -1,5 +1,8 @@ import { initEngine } from "./initEngine.js"; +/** + * Shared tsParticles engine instance for lazy/global builds. + */ const tsParticles = initEngine(); globalThis.tsParticles = tsParticles; diff --git a/engine/src/index.ts b/engine/src/index.ts index 862f0106f9f..6fc5ee3322a 100644 --- a/engine/src/index.ts +++ b/engine/src/index.ts @@ -1,5 +1,8 @@ import { initEngine } from "./initEngine.js"; +/** + * Shared tsParticles engine instance. + */ const tsParticles = initEngine(); export * from "./exports.js"; diff --git a/interactions/external/attract/src/Attractor.ts b/interactions/external/attract/src/Attractor.ts index d17e12688a5..bf35a791eae 100644 --- a/interactions/external/attract/src/Attractor.ts +++ b/interactions/external/attract/src/Attractor.ts @@ -17,6 +17,7 @@ const attractMode = "attract"; * Particle external attract manager */ export class Attractor extends ExternalInteractorBase { + /** @inheritDoc */ handleClickMode: (mode: string, interactivityData: IInteractivityData) => void; private _maxDistance; @@ -66,14 +67,17 @@ export class Attractor extends ExternalInteractorBase { }; } + /** @inheritDoc */ get maxDistance(): number { return this._maxDistance; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { const container = this.container, attract = container.actualOptions.interactivity?.modes.attract; @@ -87,6 +91,7 @@ export class Attractor extends ExternalInteractorBase { container.retina.attractModeDistance = attract.distance * container.retina.pixelRatio; } + /** @inheritDoc */ interact(interactivityData: IInteractivityData): void { const container = this.container, options = container.actualOptions, @@ -107,6 +112,7 @@ export class Attractor extends ExternalInteractorBase { } } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, options = container.actualOptions, @@ -123,6 +129,7 @@ export class Attractor extends ExternalInteractorBase { return isInArray(attractMode, hoverMode) || isInArray(attractMode, clickMode); } + /** @inheritDoc */ loadModeOptions( options: Modes & AttractMode, ...sources: RecursivePartial<(IModes & IAttractMode) | undefined>[] @@ -134,6 +141,7 @@ export class Attractor extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/external/attract/src/Options/Classes/Attract.ts b/interactions/external/attract/src/Options/Classes/Attract.ts index 1537dddfa10..25a213fdde0 100644 --- a/interactions/external/attract/src/Options/Classes/Attract.ts +++ b/interactions/external/attract/src/Options/Classes/Attract.ts @@ -1,14 +1,24 @@ import { EasingType, type EasingTypeAlt, type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { IAttract } from "../Interfaces/IAttract.js"; -/** - */ +/** Attract mode options class */ export class Attract implements IAttract, IOptionLoader { + /** Attraction distance in pixels */ distance; + + /** Attraction animation duration in seconds */ duration; + + /** Easing type used for the attraction animation */ easing: EasingType | EasingTypeAlt; + + /** Attraction factor multiplier */ factor; + + /** Maximum speed of attracted particles */ maxSpeed; + + /** Attraction speed */ speed; constructor() { @@ -20,6 +30,7 @@ export class Attract implements IAttract, IOptionLoader { this.speed = 1; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/attract/src/Options/Classes/AttractOptions.ts b/interactions/external/attract/src/Options/Classes/AttractOptions.ts index c6c7d31cac9..89e3224fceb 100644 --- a/interactions/external/attract/src/Options/Classes/AttractOptions.ts +++ b/interactions/external/attract/src/Options/Classes/AttractOptions.ts @@ -1,6 +1,7 @@ import type { AttractMode } from "../../Types.js"; import type { InteractivityOptions } from "@tsparticles/plugin-interactivity"; +/** Attract interaction options */ export type AttractOptions = InteractivityOptions & { interactivity?: { modes: AttractMode; diff --git a/interactions/external/attract/src/Options/Interfaces/IAttract.ts b/interactions/external/attract/src/Options/Interfaces/IAttract.ts index d6a961d7739..4931a2b61c2 100644 --- a/interactions/external/attract/src/Options/Interfaces/IAttract.ts +++ b/interactions/external/attract/src/Options/Interfaces/IAttract.ts @@ -1,12 +1,17 @@ import type { EasingType, EasingTypeAlt } from "@tsparticles/engine"; -/** - */ +/** Attract mode options */ export interface IAttract { + /** Attract distance in pixels */ distance: number; + /** Attract animation duration in seconds */ duration: number; + /** Attract animation easing type */ easing: EasingType | EasingTypeAlt; + /** Attract factor multiplier */ factor: number; + /** Maximum attract speed */ maxSpeed: number; + /** Attract speed */ speed: number; } diff --git a/interactions/external/attract/src/Types.ts b/interactions/external/attract/src/Types.ts index cd641d43af7..b42a7255259 100644 --- a/interactions/external/attract/src/Types.ts +++ b/interactions/external/attract/src/Types.ts @@ -3,21 +3,27 @@ import type { Attract } from "./Options/Classes/Attract.js"; import type { AttractOptions } from "./Options/Classes/AttractOptions.js"; import type { IAttract } from "./Options/Interfaces/IAttract.js"; +/** Attract mode interface */ export interface IAttractMode { + /** Attract options */ attract: IAttract; } +/** Attract mode options */ export interface AttractMode { + /** Attract options, undefined if not set */ attract?: Attract; } -interface IContainerAttract { +/** Container attract data */ +export interface IContainerAttract { clicking?: boolean; count?: number; finish?: boolean; particles: InteractivityParticle[]; } +/** Attract container interface */ export type AttractContainer = InteractivityContainer & { actualOptions: AttractOptions; attract?: IContainerAttract; diff --git a/interactions/external/attract/src/Utils.ts b/interactions/external/attract/src/Utils.ts index 86c8c1f25b8..4b8591dfd5b 100644 --- a/interactions/external/attract/src/Utils.ts +++ b/interactions/external/attract/src/Utils.ts @@ -17,13 +17,13 @@ const minFactor = 1, updateVector = Vector.origin; /** - * - * @param pluginManager - - * @param container - - * @param position - - * @param attractRadius - - * @param area - - * @param queryCb - + * Processes particle attraction within a given area + * @param pluginManager - The plugin manager instance + * @param container - The attract container + * @param position - The center position of the attraction + * @param attractRadius - The radius of the attraction effect + * @param area - The area to query particles from + * @param queryCb - Callback to filter which particles to attract */ function processAttract( pluginManager: PluginManager, @@ -58,10 +58,11 @@ function processAttract( } /** - * @param pluginManager - - * @param container - - * @param interactivityData - - * @param enabledCb - + * Handles click-based particle attraction + * @param pluginManager - The plugin manager instance + * @param container - The attract container + * @param interactivityData - The interactivity data containing mouse position + * @param enabledCb - Callback to check if a particle should be attracted */ export function clickAttract( pluginManager: PluginManager, @@ -104,10 +105,11 @@ export function clickAttract( } /** - * @param pluginManager - - * @param container - - * @param interactivityData - - * @param enabledCb - + * Handles hover-based particle attraction + * @param pluginManager - The plugin manager instance + * @param container - The attract container + * @param interactivityData - The interactivity data containing mouse position + * @param enabledCb - Callback to check if a particle should be attracted */ export function hoverAttract( pluginManager: PluginManager, diff --git a/interactions/external/attract/src/index.lazy.ts b/interactions/external/attract/src/index.lazy.ts index c8ae1aa2fbf..f6085f1db62 100644 --- a/interactions/external/attract/src/index.lazy.ts +++ b/interactions/external/attract/src/index.lazy.ts @@ -4,7 +4,8 @@ import type { InteractivityEngine } from "@tsparticles/plugin-interactivity/lazy declare const __VERSION__: string; /** - * @param engine - + * Loads the external attract interaction plugin (lazy version) + * @param engine - The engine instance to register the plugin with */ export async function loadExternalAttractInteraction(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/interactions/external/attract/src/index.ts b/interactions/external/attract/src/index.ts index 0d0dbafb141..33e8b933c41 100644 --- a/interactions/external/attract/src/index.ts +++ b/interactions/external/attract/src/index.ts @@ -5,7 +5,8 @@ import { type Engine } from "@tsparticles/engine"; declare const __VERSION__: string; /** - * @param engine - + * Loads the external attract interaction plugin + * @param engine - The engine instance to register the plugin with */ export async function loadExternalAttractInteraction(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/interactions/external/bounce/src/Bouncer.ts b/interactions/external/bounce/src/Bouncer.ts index 3df079cfdf7..e9736d543a1 100644 --- a/interactions/external/bounce/src/Bouncer.ts +++ b/interactions/external/bounce/src/Bouncer.ts @@ -14,6 +14,7 @@ import { Bounce } from "./Options/Classes/Bounce.js"; const bounceMode = "bounce"; +/** Particle bounce manager */ export class Bouncer extends ExternalInteractorBase { private _maxDistance; @@ -23,14 +24,17 @@ export class Bouncer extends ExternalInteractorBase { this._maxDistance = 0; } + /** @inheritDoc */ get maxDistance(): number { return this._maxDistance; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { const container = this.container, bounce = container.actualOptions.interactivity?.modes.bounce; @@ -44,6 +48,7 @@ export class Bouncer extends ExternalInteractorBase { container.retina.bounceModeDistance = bounce.distance * container.retina.pixelRatio; } + /** @inheritDoc */ interact(interactivityData: IInteractivityData): void { const container = this.container, options = container.actualOptions, @@ -65,6 +70,7 @@ export class Bouncer extends ExternalInteractorBase { } } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, options = container.actualOptions, @@ -83,6 +89,7 @@ export class Bouncer extends ExternalInteractorBase { ); } + /** @inheritDoc */ loadModeOptions( options: Modes & BounceMode, ...sources: RecursivePartial<(IModes & IBounceMode) | undefined>[] @@ -94,6 +101,7 @@ export class Bouncer extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/external/bounce/src/IRectSideResult.ts b/interactions/external/bounce/src/IRectSideResult.ts index 7c375db2d1a..3e1eafa0a2b 100644 --- a/interactions/external/bounce/src/IRectSideResult.ts +++ b/interactions/external/bounce/src/IRectSideResult.ts @@ -1,5 +1,11 @@ +/** Rectangle side collision result */ export interface IRectSideResult { + /** Whether the particle bounced on this side */ bounced: boolean; + + /** Bounce position offset */ position?: number; + + /** Resulting velocity after bounce */ velocity?: number; } diff --git a/interactions/external/bounce/src/Options/Classes/Bounce.ts b/interactions/external/bounce/src/Options/Classes/Bounce.ts index 813923910e4..2d30954b510 100644 --- a/interactions/external/bounce/src/Options/Classes/Bounce.ts +++ b/interactions/external/bounce/src/Options/Classes/Bounce.ts @@ -1,13 +1,16 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { IBounce } from "../Interfaces/IBounce.js"; +/** Bounce mode options class */ export class Bounce implements IBounce, IOptionLoader { + /** Bounce distance in pixels */ distance: number; constructor() { this.distance = 200; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/bounce/src/Options/Classes/BounceOptions.ts b/interactions/external/bounce/src/Options/Classes/BounceOptions.ts index b5eef4ba584..2c225c13723 100644 --- a/interactions/external/bounce/src/Options/Classes/BounceOptions.ts +++ b/interactions/external/bounce/src/Options/Classes/BounceOptions.ts @@ -1,6 +1,7 @@ import type { BounceMode } from "../../Types.js"; import type { InteractivityOptions } from "@tsparticles/plugin-interactivity"; +/** Bounce interaction options */ export type BounceOptions = InteractivityOptions & { interactivity?: { modes: BounceMode; diff --git a/interactions/external/bounce/src/Options/Interfaces/IBounce.ts b/interactions/external/bounce/src/Options/Interfaces/IBounce.ts index 33bbb518e9d..2f38761e144 100644 --- a/interactions/external/bounce/src/Options/Interfaces/IBounce.ts +++ b/interactions/external/bounce/src/Options/Interfaces/IBounce.ts @@ -1,3 +1,5 @@ +/** Bounce mode options */ export interface IBounce { + /** The bounce distance */ distance: number; } diff --git a/interactions/external/bounce/src/Types.ts b/interactions/external/bounce/src/Types.ts index e00624a706f..a2c333a9eea 100644 --- a/interactions/external/bounce/src/Types.ts +++ b/interactions/external/bounce/src/Types.ts @@ -3,17 +3,23 @@ import type { BounceOptions } from "./Options/Classes/BounceOptions.js"; import type { IBounce } from "./Options/Interfaces/IBounce.js"; import type { InteractivityContainer } from "@tsparticles/plugin-interactivity"; +/** Bounce mode interface */ export interface IBounceMode { + /** Bounce options */ bounce: IBounce; } +/** Bounce mode options */ export interface BounceMode { + /** Bounce options, undefined if not set */ bounce?: Bounce; } +/** Bounce container interface */ export type BounceContainer = InteractivityContainer & { actualOptions: BounceOptions; retina: { + /** Bounce mode distance in pixels */ bounceModeDistance?: number; }; }; diff --git a/interactions/external/bounce/src/Utils.ts b/interactions/external/bounce/src/Utils.ts index 0fc5b211fab..d0ed83cb917 100644 --- a/interactions/external/bounce/src/Utils.ts +++ b/interactions/external/bounce/src/Utils.ts @@ -54,12 +54,12 @@ interface RectSideBounceData { } /** - * - * @param container - - * @param position - - * @param radius - - * @param area - - * @param enabledCb - + * Processes particle bounce within a given area + * @param container - The bounce container + * @param position - The center position of the bounce effect + * @param radius - The radius of the bounce effect + * @param area - The area to query particles from + * @param enabledCb - Callback to check if a particle should bounce */ function processBounce( container: BounceContainer, @@ -86,11 +86,11 @@ function processBounce( } /** - * - * @param container - - * @param selector - - * @param div - - * @param bounceCb - + * Processes bounce for a single CSS selector element + * @param container - The bounce container + * @param selector - The CSS selector string + * @param div - The div event configuration + * @param bounceCb - Callback to execute bounce with position, radius and area */ function singleSelectorBounce( container: BounceContainer, @@ -128,11 +128,11 @@ function singleSelectorBounce( } /** - * - * @param container - - * @param divs - - * @param bounceMode - - * @param enabledCb - + * Handles bounce from HTML div elements + * @param container - The bounce container + * @param divs - Single or multiple div event configurations + * @param bounceMode - The bounce mode identifier + * @param enabledCb - Callback to check if a particle should bounce */ export function divBounce( container: BounceContainer, @@ -148,10 +148,10 @@ export function divBounce( } /** - * - * @param container - - * @param interactivityData - - * @param enabledCb - + * Handles mouse-based particle bounce + * @param container - The bounce container + * @param interactivityData - The interactivity data containing mouse position + * @param enabledCb - Callback to check if a particle should bounce */ export function mouseBounce( container: BounceContainer, diff --git a/interactions/external/bounce/src/index.lazy.ts b/interactions/external/bounce/src/index.lazy.ts index 11b981443e0..f41fed32a83 100644 --- a/interactions/external/bounce/src/index.lazy.ts +++ b/interactions/external/bounce/src/index.lazy.ts @@ -4,7 +4,8 @@ import type { InteractivityEngine } from "@tsparticles/plugin-interactivity/lazy declare const __VERSION__: string; /** - * @param engine - + * Loads the external bounce interaction plugin (lazy version) + * @param engine - The engine instance to register the plugin with */ export async function loadExternalBounceInteraction(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/interactions/external/bounce/src/index.ts b/interactions/external/bounce/src/index.ts index b27e7461e25..7038ac30920 100644 --- a/interactions/external/bounce/src/index.ts +++ b/interactions/external/bounce/src/index.ts @@ -5,7 +5,8 @@ import { type Engine } from "@tsparticles/engine"; declare const __VERSION__: string; /** - * @param engine - + * Loads the external bounce interaction plugin + * @param engine - The engine instance to register the plugin with */ export async function loadExternalBounceInteraction(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/interactions/external/bubble/src/Bubbler.ts b/interactions/external/bubble/src/Bubbler.ts index 0bb4a3b63b8..964667b4a85 100644 --- a/interactions/external/bubble/src/Bubbler.ts +++ b/interactions/external/bubble/src/Bubbler.ts @@ -51,6 +51,7 @@ const bubbleMode = "bubble", * Particle bubble manager */ export class Bubbler extends ExternalInteractorBase { + /** @inheritDoc */ handleClickMode: (mode: string, interactivityData: IInteractivityData) => void; private _maxDistance; @@ -75,10 +76,12 @@ export class Bubbler extends ExternalInteractorBase { }; } + /** @inheritDoc */ get maxDistance(): number { return this._maxDistance; } + /** @inheritDoc */ clear(particle: Particle, _delta: IDelta, force?: boolean): void { if (particle.bubble.inRange && !force) { return; @@ -90,6 +93,7 @@ export class Bubbler extends ExternalInteractorBase { delete particle.bubble.color; } + /** @inheritDoc */ init(): void { const container = this.container, bubble = container.actualOptions.interactivity?.modes.bubble; @@ -107,6 +111,7 @@ export class Bubbler extends ExternalInteractorBase { } } + /** @inheritDoc */ interact(interactivityData: IInteractivityData, delta: IDelta): void { const options = this.container.actualOptions, events = options.interactivity?.events; @@ -135,6 +140,7 @@ export class Bubbler extends ExternalInteractorBase { } } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, options = container.actualOptions, @@ -155,6 +161,7 @@ export class Bubbler extends ExternalInteractorBase { return isInArray(bubbleMode, onHover.mode) || isInArray(bubbleMode, onClick.mode) || divBubble; } + /** @inheritDoc */ loadModeOptions( options: Modes & BubbleMode, ...sources: RecursivePartial<(IModes & IBubbleMode) | undefined>[] @@ -166,6 +173,7 @@ export class Bubbler extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(_interactivityData: IInteractivityData, particle: Particle): void { particle.bubble.inRange = false; } diff --git a/interactions/external/bubble/src/Enums.ts b/interactions/external/bubble/src/Enums.ts index 03a89988a5c..d092fbbb5f5 100644 --- a/interactions/external/bubble/src/Enums.ts +++ b/interactions/external/bubble/src/Enums.ts @@ -1,7 +1,11 @@ -/** - */ +/** Bubble processing types */ export enum ProcessBubbleType { + /** Process bubble color */ color = "color", + + /** Process bubble opacity */ opacity = "opacity", + + /** Process bubble size */ size = "size", } diff --git a/interactions/external/bubble/src/Interfaces.ts b/interactions/external/bubble/src/Interfaces.ts index ddbdf6e8036..86cc601e38e 100644 --- a/interactions/external/bubble/src/Interfaces.ts +++ b/interactions/external/bubble/src/Interfaces.ts @@ -1,16 +1,22 @@ import type { ProcessBubbleType } from "./Enums.js"; -/** - */ +/** Interfaces for bubble process param objects */ export interface Interfaces { + /** Bubble option value object */ bubbleObj: IBubblerProcessParamObj; + + /** Particle option value object */ particlesObj: IBubblerProcessParamObj; + + /** Processing type */ type: ProcessBubbleType; } -/** - */ +/** Bubble process param object */ export interface IBubblerProcessParamObj { + /** Option value */ optValue?: number; + + /** Current value */ value?: number; } diff --git a/interactions/external/bubble/src/Options/Classes/Bubble.ts b/interactions/external/bubble/src/Options/Classes/Bubble.ts index 7b05fa9533a..400858941b9 100644 --- a/interactions/external/bubble/src/Options/Classes/Bubble.ts +++ b/interactions/external/bubble/src/Options/Classes/Bubble.ts @@ -9,11 +9,12 @@ import { BubbleBase } from "./BubbleBase.js"; import { BubbleDiv } from "./BubbleDiv.js"; import type { IBubble } from "../Interfaces/IBubble.js"; -/** - */ +/** Bubble mode options class */ export class Bubble extends BubbleBase implements IBubble, IOptionLoader { + /** Bubble divs to apply the mode to */ divs?: SingleOrMultiple; + /** @inheritDoc */ override load(data?: RecursivePartial): void { super.load(data); diff --git a/interactions/external/bubble/src/Options/Classes/BubbleBase.ts b/interactions/external/bubble/src/Options/Classes/BubbleBase.ts index 28cc516cd37..fa64162b677 100644 --- a/interactions/external/bubble/src/Options/Classes/BubbleBase.ts +++ b/interactions/external/bubble/src/Options/Classes/BubbleBase.ts @@ -9,22 +9,34 @@ import { } from "@tsparticles/engine"; import type { IBubbleBase } from "../Interfaces/IBubbleBase.js"; -/** - */ +/** Bubble base options class */ export abstract class BubbleBase implements IBubbleBase, IOptionLoader { + /** Bubble color */ color?: SingleOrMultiple; + + /** Bubble distance in pixels */ distance; + + /** Bubble animation duration in seconds */ duration; + + /** Whether to mix the bubble color with the particle color */ mix; + + /** Bubble opacity */ opacity?: number; + + /** Bubble size */ size?: number; + /** @inheritDoc */ constructor() { this.distance = 200; this.duration = 0.4; this.mix = false; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/bubble/src/Options/Classes/BubbleDiv.ts b/interactions/external/bubble/src/Options/Classes/BubbleDiv.ts index 5ccfc4ccc67..97ea31f2160 100644 --- a/interactions/external/bubble/src/Options/Classes/BubbleDiv.ts +++ b/interactions/external/bubble/src/Options/Classes/BubbleDiv.ts @@ -2,17 +2,19 @@ import { type IOptionLoader, type RecursivePartial, type SingleOrMultiple, isNul import { BubbleBase } from "./BubbleBase.js"; import type { IBubbleDiv } from "../Interfaces/IBubbleDiv.js"; -/** - */ +/** Bubble div options class */ export class BubbleDiv extends BubbleBase implements IBubbleDiv, IOptionLoader { + /** CSS selectors for the div elements */ selectors: SingleOrMultiple; + /** @inheritDoc */ constructor() { super(); this.selectors = []; } + /** @inheritDoc */ override load(data?: RecursivePartial): void { super.load(data); diff --git a/interactions/external/bubble/src/Options/Classes/BubbleOptions.ts b/interactions/external/bubble/src/Options/Classes/BubbleOptions.ts index e18955f394d..a5ddf2f8568 100644 --- a/interactions/external/bubble/src/Options/Classes/BubbleOptions.ts +++ b/interactions/external/bubble/src/Options/Classes/BubbleOptions.ts @@ -1,6 +1,7 @@ import type { BubbleMode } from "../../Types.js"; import type { InteractivityOptions } from "@tsparticles/plugin-interactivity"; +/** Bubble interaction options */ export type BubbleOptions = InteractivityOptions & { interactivity?: { modes: BubbleMode; diff --git a/interactions/external/bubble/src/Options/Interfaces/IBubble.ts b/interactions/external/bubble/src/Options/Interfaces/IBubble.ts index 446ef0e3050..fcba3250444 100644 --- a/interactions/external/bubble/src/Options/Interfaces/IBubble.ts +++ b/interactions/external/bubble/src/Options/Interfaces/IBubble.ts @@ -2,8 +2,8 @@ import type { IBubbleBase } from "./IBubbleBase.js"; import type { IBubbleDiv } from "./IBubbleDiv.js"; import type { SingleOrMultiple } from "@tsparticles/engine"; -/** - */ +/** The bubble mode options */ export interface IBubble extends IBubbleBase { + /** The bubble divs options */ divs?: SingleOrMultiple; } diff --git a/interactions/external/bubble/src/Options/Interfaces/IBubbleBase.ts b/interactions/external/bubble/src/Options/Interfaces/IBubbleBase.ts index f50c2940915..219c4a48b34 100644 --- a/interactions/external/bubble/src/Options/Interfaces/IBubbleBase.ts +++ b/interactions/external/bubble/src/Options/Interfaces/IBubbleBase.ts @@ -1,12 +1,17 @@ import type { IOptionsColor, SingleOrMultiple } from "@tsparticles/engine"; -/** - */ +/** The bubble base mode options */ export interface IBubbleBase { + /** The bubble base color */ color?: SingleOrMultiple; + /** The bubble base distance */ distance: number; + /** The bubble base duration */ duration: number; + /** The bubble base mix */ mix: boolean; + /** The bubble base opacity */ opacity?: number; + /** The bubble base size */ size?: number; } diff --git a/interactions/external/bubble/src/Options/Interfaces/IBubbleDiv.ts b/interactions/external/bubble/src/Options/Interfaces/IBubbleDiv.ts index 2f36f03e2f9..36433db8dad 100644 --- a/interactions/external/bubble/src/Options/Interfaces/IBubbleDiv.ts +++ b/interactions/external/bubble/src/Options/Interfaces/IBubbleDiv.ts @@ -1,6 +1,5 @@ import type { IBubbleBase } from "./IBubbleBase.js"; import type { IModeDiv } from "@tsparticles/plugin-interactivity"; -/** - */ +/** The bubble div mode options */ export interface IBubbleDiv extends IBubbleBase, IModeDiv {} diff --git a/interactions/external/bubble/src/Types.ts b/interactions/external/bubble/src/Types.ts index 43e125ec1dc..38b34fd1fc2 100644 --- a/interactions/external/bubble/src/Types.ts +++ b/interactions/external/bubble/src/Types.ts @@ -3,24 +3,34 @@ import type { BubbleOptions } from "./Options/Classes/BubbleOptions.js"; import type { IBubble } from "./Options/Interfaces/IBubble.js"; import type { InteractivityContainer } from "@tsparticles/plugin-interactivity"; +/** Bubble mode interface */ export interface IBubbleMode { + /** Bubble options */ bubble: IBubble; } +/** Bubble mode options */ export interface BubbleMode { + /** Bubble options, undefined if not set */ bubble?: Bubble; } -interface IContainerBubble { +/** Container bubble data */ +export interface IContainerBubble { + /** Whether the user is clicking */ clicking?: boolean; + /** Whether the bubble duration has ended */ durationEnd?: boolean; } +/** Bubble container interface */ export type BubbleContainer = InteractivityContainer & { actualOptions: BubbleOptions; bubble?: IContainerBubble; retina: { + /** Bubble mode distance in pixels */ bubbleModeDistance?: number; + /** Bubble mode size in pixels */ bubbleModeSize?: number; }; }; diff --git a/interactions/external/bubble/src/index.lazy.ts b/interactions/external/bubble/src/index.lazy.ts index bdbcf64468f..9d613749451 100644 --- a/interactions/external/bubble/src/index.lazy.ts +++ b/interactions/external/bubble/src/index.lazy.ts @@ -4,7 +4,8 @@ import type { InteractivityEngine } from "@tsparticles/plugin-interactivity/lazy declare const __VERSION__: string; /** - * @param engine - + * Loads the external bubble interaction plugin (lazy version) + * @param engine - The engine instance to register the plugin with */ export async function loadExternalBubbleInteraction(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/interactions/external/bubble/src/index.ts b/interactions/external/bubble/src/index.ts index d7d96581ab1..fe5dee085bc 100644 --- a/interactions/external/bubble/src/index.ts +++ b/interactions/external/bubble/src/index.ts @@ -5,7 +5,8 @@ import { type Engine } from "@tsparticles/engine"; declare const __VERSION__: string; /** - * @param engine - + * Loads the external bubble interaction plugin + * @param engine - The engine instance to register the plugin with */ export async function loadExternalBubbleInteraction(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/interactions/external/cannon/src/Cannoner.ts b/interactions/external/cannon/src/Cannoner.ts index 3f28ab8a63e..3ed7518c2f7 100644 --- a/interactions/external/cannon/src/Cannoner.ts +++ b/interactions/external/cannon/src/Cannoner.ts @@ -49,14 +49,30 @@ function angleRad(x0: number, y0: number, x1: number, y1: number): number { return Math.atan2(y1 - y0, x1 - x0); } +/** Cannon mode internal data */ interface CannonData { + /** Whether to draw the aiming vector line */ drawVector: boolean; + + /** Maximum drag distance in pixels */ maxDragDistance: number; + + /** Maximum number of particles to spawn */ maxParticles: number; + + /** Minimum number of particles to spawn */ minParticles: number; + + /** Particles per pixel of drag distance */ particleFactor: number; + + /** Spread half-angle in radians */ spread: number; + + /** CSS color for the aiming line */ vectorColor: string; + + /** Velocity multiplier from drag distance */ velocityFactor: number; } @@ -88,6 +104,7 @@ interface CannonGesture { * - `vectorColor` — CSS color for the aiming line (default "#ffffff80") */ export class Cannoner extends ExternalInteractorBase { + /** @inheritDoc */ readonly maxDistance = 0; private _data?: CannonData; @@ -100,15 +117,18 @@ export class Cannoner extends ExternalInteractorBase { private _lastDownPosition: ICoordinates | undefined = undefined; private _state: CannonState = CannonState.idle; + /** @inheritDoc */ // eslint-disable-next-line @typescript-eslint/no-useless-constructor constructor(container: CannonContainer) { super(container); } + /** @inheritDoc */ clear(_particle: InteractivityParticle, _delta: IDelta): void { // nothing to clear per-particle } + /** @inheritDoc */ init(): void { const options = this.container.actualOptions.interactivity?.modes.cannon ?? new Cannon(); @@ -124,6 +144,7 @@ export class Cannoner extends ExternalInteractorBase { }; } + /** @inheritDoc */ interact(interactivityData: IInteractivityData, _delta: IDelta): void { const mouse = interactivityData.mouse, mousePos = mouse.position, @@ -155,6 +176,7 @@ export class Cannoner extends ExternalInteractorBase { } } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData): boolean { const { container } = this, events = container.actualOptions.interactivity?.events; @@ -175,6 +197,7 @@ export class Cannoner extends ExternalInteractorBase { return this._state !== CannonState.idle || interactivityData.mouse.clicking; } + /** @inheritDoc */ loadModeOptions( options: Modes & CannonMode, ...sources: RecursivePartial<(IModes & ICannonMode) | undefined>[] @@ -186,6 +209,7 @@ export class Cannoner extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(_interactivityData: IInteractivityData, _particle: InteractivityParticle): void { // nothing to reset } diff --git a/interactions/external/cannon/src/Options/Classes/Cannon.ts b/interactions/external/cannon/src/Options/Classes/Cannon.ts index f31fec97a3c..c459723f615 100644 --- a/interactions/external/cannon/src/Options/Classes/Cannon.ts +++ b/interactions/external/cannon/src/Options/Classes/Cannon.ts @@ -1,14 +1,30 @@ import type { ICannon } from "../Interfaces/ICannon.js"; import type { RecursivePartial } from "@tsparticles/engine"; +/** Cannon mode options class */ export class Cannon implements ICannon { + /** Whether to draw the aiming vector */ drawVector; + + /** Maximum drag distance in pixels */ maxDragDistance; + + /** Maximum number of particles to spawn */ maxParticles; + + /** Minimum number of particles to spawn */ minParticles; + + /** Particles per pixel of drag distance */ particleFactor; + + /** Spread angle in degrees */ spread; + + /** CSS color for the aiming vector line */ vectorColor; + + /** Velocity multiplier from drag distance */ velocityFactor; constructor() { @@ -22,6 +38,7 @@ export class Cannon implements ICannon { this.vectorColor = "#ffffff80"; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (!data) { return; diff --git a/interactions/external/cannon/src/Options/Classes/CannonOptions.ts b/interactions/external/cannon/src/Options/Classes/CannonOptions.ts index 0f30d69508e..d1abed8440a 100644 --- a/interactions/external/cannon/src/Options/Classes/CannonOptions.ts +++ b/interactions/external/cannon/src/Options/Classes/CannonOptions.ts @@ -1,6 +1,7 @@ import type { CannonMode } from "../../Types.js"; import type { InteractivityOptions } from "@tsparticles/plugin-interactivity"; +/** Cannon interaction options */ export type CannonOptions = InteractivityOptions & { interactivity?: { modes: CannonMode; diff --git a/interactions/external/cannon/src/Options/Interfaces/ICannon.ts b/interactions/external/cannon/src/Options/Interfaces/ICannon.ts index 97a56a3cf84..3892f4b76ff 100644 --- a/interactions/external/cannon/src/Options/Interfaces/ICannon.ts +++ b/interactions/external/cannon/src/Options/Interfaces/ICannon.ts @@ -1,9 +1,14 @@ +/** Cannon mode options */ export interface ICannon { /** * Whether to render the dashed aim line and power circle while dragging. */ drawVector: boolean; + /** + * Maximum drag distance in canvas pixels. + * The drag vector is clamped to this length for both visual feedback and force calculation. + */ maxDragDistance: number; /** diff --git a/interactions/external/cannon/src/Types.ts b/interactions/external/cannon/src/Types.ts index f390a3a0417..1ae04c31d96 100644 --- a/interactions/external/cannon/src/Types.ts +++ b/interactions/external/cannon/src/Types.ts @@ -3,14 +3,17 @@ import type { CannonOptions } from "./Options/Classes/CannonOptions.js"; import type { ICannon } from "./Options/Interfaces/ICannon.js"; import type { InteractivityContainer } from "@tsparticles/plugin-interactivity"; +/** Cannon mode interface */ export interface ICannonMode { cannon: ICannon; } +/** Cannon mode options */ export interface CannonMode { cannon?: Cannon; } +/** Cannon container interface */ export type CannonContainer = InteractivityContainer & { actualOptions: CannonOptions; }; diff --git a/interactions/external/cannon/src/index.lazy.ts b/interactions/external/cannon/src/index.lazy.ts index 6bae6c3c0ea..97b4a719175 100644 --- a/interactions/external/cannon/src/index.lazy.ts +++ b/interactions/external/cannon/src/index.lazy.ts @@ -8,7 +8,8 @@ export { Cannon } from "./Options/Classes/Cannon.js"; declare const __VERSION__: string; /** - * @param engine - + * Registers the cannon external interaction in the given engine. + * @param engine - The engine to register the interaction into */ export async function loadExternalCannonInteraction(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/interactions/external/cannon/src/index.ts b/interactions/external/cannon/src/index.ts index 38bac26f3b0..ff686450def 100644 --- a/interactions/external/cannon/src/index.ts +++ b/interactions/external/cannon/src/index.ts @@ -8,7 +8,8 @@ export type { CannonContainer, CannonMode, ICannonMode } from "./Types.js"; declare const __VERSION__: string; /** - * @param engine - + * Registers the cannon external interaction in the given engine. + * @param engine - The engine to register the interaction into */ export async function loadExternalCannonInteraction(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/interactions/external/connect/src/Connector.ts b/interactions/external/connect/src/Connector.ts index c3a22420711..853f90fa5e7 100644 --- a/interactions/external/connect/src/Connector.ts +++ b/interactions/external/connect/src/Connector.ts @@ -25,14 +25,17 @@ export class Connector extends ExternalInteractorBase { this._maxDistance = 0; } + /** @inheritDoc */ get maxDistance(): number { return this._maxDistance; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { const container = this.container, connect = container.actualOptions.interactivity?.modes.connect; @@ -90,6 +93,7 @@ export class Connector extends ExternalInteractorBase { } } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, mouse = interactivityData.mouse, @@ -102,6 +106,7 @@ export class Connector extends ExternalInteractorBase { return isInArray(connectMode, events.onHover.mode); } + /** @inheritDoc */ loadModeOptions( options: Modes & ConnectMode, ...sources: RecursivePartial<(IModes & IConnectMode) | undefined>[] @@ -113,6 +118,7 @@ export class Connector extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/external/connect/src/Options/Classes/Connect.ts b/interactions/external/connect/src/Options/Classes/Connect.ts index ebdc92beb75..6a42c770422 100644 --- a/interactions/external/connect/src/Options/Classes/Connect.ts +++ b/interactions/external/connect/src/Options/Classes/Connect.ts @@ -2,11 +2,15 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/ import { ConnectLinks } from "./ConnectLinks.js"; import type { IConnect } from "../Interfaces/IConnect.js"; -/** - */ +/** Connect mode options class */ export class Connect implements IConnect, IOptionLoader { + /** Connect distance in pixels */ distance; + + /** Connect links options */ links; + + /** Connect radius in pixels */ radius; constructor() { @@ -15,6 +19,7 @@ export class Connect implements IConnect, IOptionLoader { this.radius = 60; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/connect/src/Options/Classes/ConnectLinks.ts b/interactions/external/connect/src/Options/Classes/ConnectLinks.ts index 09c51bf2506..f8421f7f2e4 100644 --- a/interactions/external/connect/src/Options/Classes/ConnectLinks.ts +++ b/interactions/external/connect/src/Options/Classes/ConnectLinks.ts @@ -1,15 +1,16 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { IConnectLinks } from "../Interfaces/IConnectLinks.js"; -/** - */ +/** Connect links options class */ export class ConnectLinks implements IConnectLinks, IOptionLoader { + /** Connect line opacity */ opacity; constructor() { this.opacity = 0.5; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/connect/src/Options/Classes/ConnectOptions.ts b/interactions/external/connect/src/Options/Classes/ConnectOptions.ts index 1a91bd59b0f..f3dd511c934 100644 --- a/interactions/external/connect/src/Options/Classes/ConnectOptions.ts +++ b/interactions/external/connect/src/Options/Classes/ConnectOptions.ts @@ -1,6 +1,7 @@ import type { ConnectMode } from "../../Types.js"; import type { InteractivityOptions } from "@tsparticles/plugin-interactivity"; +/** Connect interaction options */ export type ConnectOptions = InteractivityOptions & { interactivity?: { modes: ConnectMode; diff --git a/interactions/external/connect/src/Options/Interfaces/IConnect.ts b/interactions/external/connect/src/Options/Interfaces/IConnect.ts index 0dc87706440..ca86197430e 100644 --- a/interactions/external/connect/src/Options/Interfaces/IConnect.ts +++ b/interactions/external/connect/src/Options/Interfaces/IConnect.ts @@ -1,9 +1,11 @@ import type { IConnectLinks } from "./IConnectLinks.js"; -/** - */ +/** The connect mode options */ export interface IConnect { + /** The connect distance */ distance: number; + /** The connect links options */ links: IConnectLinks; + /** The connect radius */ radius: number; } diff --git a/interactions/external/connect/src/Options/Interfaces/IConnectLinks.ts b/interactions/external/connect/src/Options/Interfaces/IConnectLinks.ts index 1842a7469bf..1cdcb9aa974 100644 --- a/interactions/external/connect/src/Options/Interfaces/IConnectLinks.ts +++ b/interactions/external/connect/src/Options/Interfaces/IConnectLinks.ts @@ -1,5 +1,5 @@ -/** - */ +/** The connect links options */ export interface IConnectLinks { + /** The connect links opacity */ opacity: number; } diff --git a/interactions/external/connect/src/Types.ts b/interactions/external/connect/src/Types.ts index 7118f6e5239..ec9cba9819a 100644 --- a/interactions/external/connect/src/Types.ts +++ b/interactions/external/connect/src/Types.ts @@ -3,14 +3,17 @@ import type { Connect } from "./Options/Classes/Connect.js"; import type { ConnectOptions } from "./Options/Classes/ConnectOptions.js"; import type { IConnect } from "./Options/Interfaces/IConnect.js"; +/** Connect mode interface */ export interface IConnectMode { connect: IConnect; } +/** Connect mode options */ export interface ConnectMode { connect?: Connect; } +/** Connect container interface */ export type ConnectContainer = InteractivityContainer & { actualOptions: ConnectOptions; retina: { @@ -19,6 +22,7 @@ export type ConnectContainer = InteractivityContainer & { }; }; +/** Connect link particle */ export type LinkParticle = InteractivityParticle & { retina: { linksWidth?: number; diff --git a/interactions/external/connect/src/Utils.ts b/interactions/external/connect/src/Utils.ts index efaa45b482f..98ec6d52e17 100644 --- a/interactions/external/connect/src/Utils.ts +++ b/interactions/external/connect/src/Utils.ts @@ -51,11 +51,12 @@ export function gradient( } /** - * @param context - - * @param width - - * @param lineStyle - - * @param begin - - * @param end - + * Draw a connect line between two points + * @param context + * @param width + * @param lineStyle + * @param begin + * @param end */ export function drawConnectLine( context: CanvasContextType, @@ -72,11 +73,11 @@ export function drawConnectLine( } /** - * @param container - - * @param ctx - - * @param p1 - - * @param p2 - - * @returns The gradient. + * Get the line style for a connection + * @param container + * @param ctx + * @param p1 + * @param p2 */ export function lineStyle( container: ConnectContainer, @@ -95,9 +96,10 @@ export function lineStyle( } /** - * @param container - - * @param p1 - - * @param p2 - + * Draw a connection between two particles + * @param container + * @param p1 + * @param p2 */ export function drawConnection(container: ConnectContainer, p1: LinkParticle, p2: LinkParticle): void { container.canvas.render.draw(ctx => { diff --git a/interactions/external/connect/src/index.lazy.ts b/interactions/external/connect/src/index.lazy.ts index 8629fa78c33..4d1dc863b8a 100644 --- a/interactions/external/connect/src/index.lazy.ts +++ b/interactions/external/connect/src/index.lazy.ts @@ -4,7 +4,8 @@ import type { InteractivityEngine } from "@tsparticles/plugin-interactivity/lazy declare const __VERSION__: string; /** - * @param engine - + * Registers the connect external interaction in the given engine. + * @param engine - The engine to register the interaction into */ export async function loadExternalConnectInteraction(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/interactions/external/connect/src/index.ts b/interactions/external/connect/src/index.ts index 87d1a10b650..9b6b08aca62 100644 --- a/interactions/external/connect/src/index.ts +++ b/interactions/external/connect/src/index.ts @@ -5,7 +5,8 @@ import { type Engine } from "@tsparticles/engine"; declare const __VERSION__: string; /** - * @param engine - + * Registers the connect external interaction in the given engine. + * @param engine - The engine to register the interaction into */ export async function loadExternalConnectInteraction(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/interactions/external/destroy/src/Destroyer.ts b/interactions/external/destroy/src/Destroyer.ts index fa7f6f0edd0..58e1203348c 100644 --- a/interactions/external/destroy/src/Destroyer.ts +++ b/interactions/external/destroy/src/Destroyer.ts @@ -14,6 +14,7 @@ import { Destroy } from "./Options/Classes/Destroy.js"; const destroyMode = "destroy"; +/** Particle destroy manager */ export class Destroyer extends ExternalInteractorBase { private _maxDistance; @@ -23,14 +24,17 @@ export class Destroyer extends ExternalInteractorBase { this._maxDistance = 0; } + /** @inheritDoc */ get maxDistance(): number { return this._maxDistance; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { const container = this.container, destroy = container.actualOptions.interactivity?.modes.destroy; @@ -44,6 +48,7 @@ export class Destroyer extends ExternalInteractorBase { container.retina.destroyModeDistance = destroy.distance * container.retina.pixelRatio; } + /** @inheritDoc */ interact(interactivityData: IInteractivityData): void { const container = this.container, options = container.actualOptions, @@ -65,6 +70,7 @@ export class Destroyer extends ExternalInteractorBase { } } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, options = container.actualOptions, @@ -83,6 +89,7 @@ export class Destroyer extends ExternalInteractorBase { ); } + /** @inheritDoc */ loadModeOptions( options: Modes & DestroyMode, ...sources: RecursivePartial<(IModes & IDestroyMode) | undefined>[] @@ -94,6 +101,7 @@ export class Destroyer extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/external/destroy/src/Options/Classes/Destroy.ts b/interactions/external/destroy/src/Options/Classes/Destroy.ts index 3ea6300377d..42ef6b76ff9 100644 --- a/interactions/external/destroy/src/Options/Classes/Destroy.ts +++ b/interactions/external/destroy/src/Options/Classes/Destroy.ts @@ -1,13 +1,16 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { IDestroy } from "../Interfaces/IDestroy.js"; +/** Destroy mode options class */ export class Destroy implements IDestroy, IOptionLoader { + /** Destroy distance in pixels */ distance: number; constructor() { this.distance = 200; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/destroy/src/Options/Classes/DestroyOptions.ts b/interactions/external/destroy/src/Options/Classes/DestroyOptions.ts index 47299350c4e..51cff4cf288 100644 --- a/interactions/external/destroy/src/Options/Classes/DestroyOptions.ts +++ b/interactions/external/destroy/src/Options/Classes/DestroyOptions.ts @@ -1,6 +1,7 @@ import type { DestroyMode } from "../../Types.js"; import type { InteractivityOptions } from "@tsparticles/plugin-interactivity"; +/** Destroy interaction options */ export type DestroyOptions = InteractivityOptions & { interactivity?: { modes: DestroyMode; diff --git a/interactions/external/destroy/src/Options/Interfaces/IDestroy.ts b/interactions/external/destroy/src/Options/Interfaces/IDestroy.ts index a187f08919f..7438d2bd7b8 100644 --- a/interactions/external/destroy/src/Options/Interfaces/IDestroy.ts +++ b/interactions/external/destroy/src/Options/Interfaces/IDestroy.ts @@ -1,3 +1,5 @@ +/** Destroy mode options */ export interface IDestroy { + /** The destroy distance */ distance: number; } diff --git a/interactions/external/destroy/src/Types.ts b/interactions/external/destroy/src/Types.ts index a4a7965edd5..485e79cc45f 100644 --- a/interactions/external/destroy/src/Types.ts +++ b/interactions/external/destroy/src/Types.ts @@ -3,14 +3,17 @@ import type { DestroyOptions } from "./Options/Classes/DestroyOptions.js"; import type { IDestroy } from "./Options/Interfaces/IDestroy.js"; import type { InteractivityContainer } from "@tsparticles/plugin-interactivity"; +/** Destroy mode interface */ export interface IDestroyMode { destroy: IDestroy; } +/** Destroy mode options */ export interface DestroyMode { destroy?: Destroy; } +/** Destroy container interface */ export type DestroyContainer = InteractivityContainer & { actualOptions: DestroyOptions; retina: { diff --git a/interactions/external/destroy/src/Utils.ts b/interactions/external/destroy/src/Utils.ts index 3d6165b0932..89bd0fddb36 100644 --- a/interactions/external/destroy/src/Utils.ts +++ b/interactions/external/destroy/src/Utils.ts @@ -7,7 +7,7 @@ const half = 0.5, minRadius = 0; /** - * + * Process destroy in an area * @param container * @param area */ @@ -20,7 +20,7 @@ function processDestroy(container: DestroyContainer, area: Circle | Rectangle): } /** - * + * Process destroy for a single selector * @param container * @param selector * @param div @@ -56,7 +56,7 @@ function singleSelectorDestroy(container: DestroyContainer, selector: string, di } /** - * + * Destroy particles in div elements * @param container * @param divs * @param destroyMode @@ -68,7 +68,7 @@ export function divDestroy(container: DestroyContainer, divs: SingleOrMultiple { engine.checkVersion(__VERSION__); diff --git a/interactions/external/destroy/src/index.ts b/interactions/external/destroy/src/index.ts index ec8b497c241..e15db96ee80 100644 --- a/interactions/external/destroy/src/index.ts +++ b/interactions/external/destroy/src/index.ts @@ -5,7 +5,8 @@ import { type Engine } from "@tsparticles/engine"; declare const __VERSION__: string; /** - * @param engine - + * Registers the destroy external interaction in the given engine. + * @param engine - The engine to register the interaction into */ export async function loadExternalDestroyInteraction(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/interactions/external/drag/src/Dragger.ts b/interactions/external/drag/src/Dragger.ts index e67a3fe9046..bed18c520d9 100644 --- a/interactions/external/drag/src/Dragger.ts +++ b/interactions/external/drag/src/Dragger.ts @@ -44,6 +44,7 @@ interface MomentumSample { * - `momentumFactor` — scaling factor for the computed drag velocity (default `0.03`). */ export class Dragger extends ExternalInteractorBase { + /** @inheritDoc */ readonly maxDistance = 0; private _dragStartClickTime?: number; @@ -55,19 +56,23 @@ export class Dragger extends ExternalInteractorBase { private _mouseDownHandled = false; private _savedVelocity?: ICoordinates; + /** @inheritDoc */ // eslint-disable-next-line @typescript-eslint/no-useless-constructor constructor(container: DragContainer) { super(container); } + /** @inheritDoc */ clear(_particle: InteractivityParticle, _delta: IDelta): void { // do nothing } + /** @inheritDoc */ init(): void { // do nothing } + /** @inheritDoc */ interact(interactivityData: IInteractivityData, _delta: IDelta): void { const mouse = interactivityData.mouse, mousePos = mouse.position; @@ -174,6 +179,7 @@ export class Dragger extends ExternalInteractorBase { closest.misplaced = false; } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, mouse = interactivityData.mouse, @@ -186,6 +192,7 @@ export class Dragger extends ExternalInteractorBase { return !!events?.onClick.enable && mouse.clicking && !!mouse.position && isInArray(dragMode, events.onClick.mode); } + /** @inheritDoc */ loadModeOptions(options: Modes & DragMode, ...sources: RecursivePartial<(IModes & IDragMode) | undefined>[]): void { options.drag ??= new Drag(); @@ -194,10 +201,19 @@ export class Dragger extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(_interactivityData: IInteractivityData, _particle: InteractivityParticle): void { // do nothing - release logic is handled in interact() } + /** + * Finds the closest particle under the cursor within its radius + * @param interactivityData - + * @param mousePos - + * @param mousePos.x + * @param mousePos.y + * @returns - + */ private _findParticleUnderCursor( interactivityData: IInteractivityData, mousePos?: { x: number; y: number }, @@ -226,6 +242,10 @@ export class Dragger extends ExternalInteractorBase { return closest; } + /** + * Checks whether a new click cycle has begun since drag started + * @param mouse + */ private _hasClickEnded(mouse: IInteractivityData["mouse"]): boolean { return ( this._dragStartClickTime !== undefined && @@ -234,6 +254,7 @@ export class Dragger extends ExternalInteractorBase { ); } + /** Releases the dragged particle, optionally applying momentum */ private _releaseDragged(): void { if (this._draggedParticle) { const dragOptions = this.container.actualOptions.interactivity?.modes.drag, diff --git a/interactions/external/drag/src/Options/Classes/Drag.ts b/interactions/external/drag/src/Options/Classes/Drag.ts index 4800fb1028d..88b72c3ca67 100644 --- a/interactions/external/drag/src/Options/Classes/Drag.ts +++ b/interactions/external/drag/src/Options/Classes/Drag.ts @@ -4,11 +4,12 @@ import type { IDrag } from "../Interfaces/IDrag.js"; const defaultMomentumFactor = 0.03, defaultPreserveMomentum = false; -/** - * Options class for the drag interaction mode. - */ +/** Options class for the drag interaction mode */ export class Drag implements IDrag, IOptionLoader { + /** Momentum factor applied on drag release */ momentumFactor; + + /** Whether to preserve drag momentum on release */ preserveMomentum; constructor() { @@ -16,6 +17,7 @@ export class Drag implements IDrag, IOptionLoader { this.preserveMomentum = defaultPreserveMomentum; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/drag/src/Options/Classes/DragOptions.ts b/interactions/external/drag/src/Options/Classes/DragOptions.ts index 71b7205547b..0959a30a5c2 100644 --- a/interactions/external/drag/src/Options/Classes/DragOptions.ts +++ b/interactions/external/drag/src/Options/Classes/DragOptions.ts @@ -1,6 +1,7 @@ import type { DragMode } from "../../Types.js"; import type { InteractivityOptions } from "@tsparticles/plugin-interactivity"; +/** Drag interaction options */ export type DragOptions = InteractivityOptions & { interactivity?: { modes: DragMode; diff --git a/interactions/external/drag/src/Types.ts b/interactions/external/drag/src/Types.ts index 0016112bf3c..e3e0f8ec650 100644 --- a/interactions/external/drag/src/Types.ts +++ b/interactions/external/drag/src/Types.ts @@ -3,14 +3,17 @@ import type { DragOptions } from "./Options/Classes/DragOptions.js"; import type { IDrag } from "./Options/Interfaces/IDrag.js"; import type { InteractivityContainer } from "@tsparticles/plugin-interactivity"; +/** Drag mode interface */ export interface IDragMode { drag: IDrag; } +/** Drag mode options */ export interface DragMode { drag?: Drag; } +/** Drag container interface */ export type DragContainer = InteractivityContainer & { actualOptions: DragOptions; }; diff --git a/interactions/external/grab/src/Grabber.ts b/interactions/external/grab/src/Grabber.ts index cec65cde480..ccd87adbc31 100644 --- a/interactions/external/grab/src/Grabber.ts +++ b/interactions/external/grab/src/Grabber.ts @@ -36,14 +36,17 @@ export class Grabber extends ExternalInteractorBase { this._maxDistance = 0; } + /** @inheritDoc */ get maxDistance(): number { return this._maxDistance; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { const container = this.container, grab = container.actualOptions.interactivity?.modes.grab; @@ -57,6 +60,7 @@ export class Grabber extends ExternalInteractorBase { container.retina.grabModeDistance = grab.distance * container.retina.pixelRatio; } + /** @inheritDoc */ interact(interactivityData: IInteractivityData): void { const container = this.container, options = container.actualOptions, @@ -129,6 +133,7 @@ export class Grabber extends ExternalInteractorBase { } } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, mouse = interactivityData.mouse, @@ -137,6 +142,7 @@ export class Grabber extends ExternalInteractorBase { return !!events?.onHover.enable && !!mouse.position && isInArray(grabMode, events.onHover.mode); } + /** @inheritDoc */ loadModeOptions(options: Modes & GrabMode, ...sources: RecursivePartial<(IModes & IGrabMode) | undefined>[]): void { options.grab ??= new Grab(); @@ -145,6 +151,7 @@ export class Grabber extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/external/grab/src/Options/Classes/Grab.ts b/interactions/external/grab/src/Options/Classes/Grab.ts index 4a4129fb465..4096f6622da 100644 --- a/interactions/external/grab/src/Options/Classes/Grab.ts +++ b/interactions/external/grab/src/Options/Classes/Grab.ts @@ -2,10 +2,12 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/ import { GrabLinks } from "./GrabLinks.js"; import type { IGrab } from "../Interfaces/IGrab.js"; -/** - */ +/** Grab mode options class */ export class Grab implements IGrab, IOptionLoader { + /** Grab distance in pixels */ distance; + + /** Grab links options */ links; constructor() { @@ -13,6 +15,7 @@ export class Grab implements IGrab, IOptionLoader { this.links = new GrabLinks(); } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/grab/src/Options/Classes/GrabLinks.ts b/interactions/external/grab/src/Options/Classes/GrabLinks.ts index 98d08daf3e5..6bad13593c3 100644 --- a/interactions/external/grab/src/Options/Classes/GrabLinks.ts +++ b/interactions/external/grab/src/Options/Classes/GrabLinks.ts @@ -1,12 +1,18 @@ import { type IOptionLoader, OptionsColor, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { IGrabLinks } from "../Interfaces/IGrabLinks.js"; -/** - */ +/** Grab links options class */ export class GrabLinks implements IGrabLinks, IOptionLoader { + /** Whether to blink the grab line */ blink; + + /** Grab line color */ color?: OptionsColor; + + /** Whether the user consented to the grab link */ consent; + + /** Grab line opacity */ opacity; constructor() { @@ -15,6 +21,7 @@ export class GrabLinks implements IGrabLinks, IOptionLoader { this.opacity = 1; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/grab/src/Options/Classes/GrabOptions.ts b/interactions/external/grab/src/Options/Classes/GrabOptions.ts index 54c92454b19..759ffcd739b 100644 --- a/interactions/external/grab/src/Options/Classes/GrabOptions.ts +++ b/interactions/external/grab/src/Options/Classes/GrabOptions.ts @@ -1,6 +1,7 @@ import type { GrabMode } from "../../Types.js"; import type { InteractivityOptions } from "@tsparticles/plugin-interactivity"; +/** Grab interaction options */ export type GrabOptions = InteractivityOptions & { interactivity?: { modes: GrabMode; diff --git a/interactions/external/grab/src/Options/Interfaces/IGrab.ts b/interactions/external/grab/src/Options/Interfaces/IGrab.ts index 41e1f075782..775d46e1df2 100644 --- a/interactions/external/grab/src/Options/Interfaces/IGrab.ts +++ b/interactions/external/grab/src/Options/Interfaces/IGrab.ts @@ -1,9 +1,10 @@ import type { IGrabLinks } from "./IGrabLinks.js"; -/** - */ +/** The grab mode options */ export interface IGrab { + /** The distance of the grab */ distance: number; + /** The grab links options */ links: IGrabLinks; } diff --git a/interactions/external/grab/src/Options/Interfaces/IGrabLinks.ts b/interactions/external/grab/src/Options/Interfaces/IGrabLinks.ts index 7f5264cbca2..b5348ea4ee1 100644 --- a/interactions/external/grab/src/Options/Interfaces/IGrabLinks.ts +++ b/interactions/external/grab/src/Options/Interfaces/IGrabLinks.ts @@ -1,10 +1,13 @@ import type { IOptionsColor } from "@tsparticles/engine"; -/** - */ +/** The grab links options */ export interface IGrabLinks { + /** The grab links blink animation */ blink: boolean; + /** The grab links color */ color?: string | IOptionsColor; + /** The grab links consent */ consent: boolean; + /** The grab links opacity */ opacity: number; } diff --git a/interactions/external/grab/src/Types.ts b/interactions/external/grab/src/Types.ts index ea2aa21038c..6af132c2986 100644 --- a/interactions/external/grab/src/Types.ts +++ b/interactions/external/grab/src/Types.ts @@ -4,14 +4,17 @@ import type { Grab } from "./Options/Classes/Grab.js"; import type { GrabOptions } from "./Options/Classes/GrabOptions.js"; import type { IGrab } from "./Options/Interfaces/IGrab.js"; +/** Grab mode interface */ export interface IGrabMode { grab: IGrab; } +/** Grab mode options */ export interface GrabMode { grab?: Grab; } +/** Grab container interface */ export type GrabContainer = InteractivityContainer & { actualOptions: GrabOptions; particles: { @@ -22,6 +25,7 @@ export type GrabContainer = InteractivityContainer & { }; }; +/** Grab link particle */ export type LinkParticle = InteractivityParticle & { options: { links?: { diff --git a/interactions/external/grab/src/Utils.ts b/interactions/external/grab/src/Utils.ts index 517af789c46..1a7bc8f7d9a 100644 --- a/interactions/external/grab/src/Utils.ts +++ b/interactions/external/grab/src/Utils.ts @@ -31,11 +31,12 @@ export function drawGrabLine( } /** - * @param container - - * @param particle - - * @param lineColor - - * @param opacity - - * @param mousePos - + * Draw the grab interaction + * @param container + * @param particle + * @param lineColor + * @param opacity + * @param mousePos */ export function drawGrab( container: GrabContainer, diff --git a/interactions/external/parallax/src/Options/Classes/Parallax.ts b/interactions/external/parallax/src/Options/Classes/Parallax.ts index 0cfdd4f1c20..42802587888 100644 --- a/interactions/external/parallax/src/Options/Classes/Parallax.ts +++ b/interactions/external/parallax/src/Options/Classes/Parallax.ts @@ -1,10 +1,12 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { IParallax } from "../Interfaces/IParallax.js"; -/** - */ +/** Parallax effect options */ export class Parallax implements IParallax, IOptionLoader { + /** The parallax force */ force; + + /** The parallax smoothing factor */ smooth; constructor() { @@ -12,6 +14,7 @@ export class Parallax implements IParallax, IOptionLoader { this.smooth = 10; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/parallax/src/Options/Classes/ParallaxOptions.ts b/interactions/external/parallax/src/Options/Classes/ParallaxOptions.ts index 8136a9eff91..f751aeaa0f4 100644 --- a/interactions/external/parallax/src/Options/Classes/ParallaxOptions.ts +++ b/interactions/external/parallax/src/Options/Classes/ParallaxOptions.ts @@ -1,6 +1,7 @@ import type { InteractivityOptions } from "@tsparticles/plugin-interactivity"; import type { ParallaxMode } from "../../Types.js"; +/** Parallax interaction options */ export type ParallaxOptions = InteractivityOptions & { interactivity?: { modes: ParallaxMode; diff --git a/interactions/external/parallax/src/Options/Interfaces/IParallax.ts b/interactions/external/parallax/src/Options/Interfaces/IParallax.ts index dd774dc6592..5cde0b8fb37 100644 --- a/interactions/external/parallax/src/Options/Interfaces/IParallax.ts +++ b/interactions/external/parallax/src/Options/Interfaces/IParallax.ts @@ -1,5 +1,4 @@ -/** - */ +/** The parallax mode options */ export interface IParallax { /** * This property is used to define the parallax force. diff --git a/interactions/external/parallax/src/Parallaxer.ts b/interactions/external/parallax/src/Parallaxer.ts index 72fd1f103f1..43bd31707b9 100644 --- a/interactions/external/parallax/src/Parallaxer.ts +++ b/interactions/external/parallax/src/Parallaxer.ts @@ -15,6 +15,7 @@ const parallaxMode = "parallax"; * Particle parallax manager */ export class Parallaxer extends ExternalInteractorBase { + /** @inheritDoc */ readonly maxDistance = 0; // eslint-disable-next-line @typescript-eslint/no-useless-constructor @@ -22,20 +23,24 @@ export class Parallaxer extends ExternalInteractorBase { super(container); } + /** @inheritDoc */ clear(): void { // no-op } + /** @inheritDoc */ init(): void { // no-op } + /** @inheritDoc */ interact(interactivityData: IInteractivityData): void { for (const particle of this.container.particles.filter(p => this.isEnabled(interactivityData, p))) { this._parallaxInteract(interactivityData, particle); } } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, mouse = interactivityData.mouse, @@ -44,6 +49,7 @@ export class Parallaxer extends ExternalInteractorBase { return !!events?.onHover.enable && !!mouse.position && isInArray(parallaxMode, events.onHover.mode); } + /** @inheritDoc */ loadModeOptions( options: Modes & ParallaxMode, ...sources: RecursivePartial<(IModes & IParallaxMode) | undefined>[] @@ -55,6 +61,7 @@ export class Parallaxer extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(): void { // no-op } diff --git a/interactions/external/parallax/src/Types.ts b/interactions/external/parallax/src/Types.ts index 58c8db48945..823b2cb2b2c 100644 --- a/interactions/external/parallax/src/Types.ts +++ b/interactions/external/parallax/src/Types.ts @@ -3,14 +3,17 @@ import type { InteractivityContainer } from "@tsparticles/plugin-interactivity"; import type { Parallax } from "./Options/Classes/Parallax.js"; import type { ParallaxOptions } from "./Options/Classes/ParallaxOptions.js"; +/** Parallax mode interface */ export interface IParallaxMode { parallax: IParallax; } +/** Parallax mode options */ export interface ParallaxMode { parallax?: Parallax; } +/** Parallax container interface */ export type ParallaxContainer = InteractivityContainer & { actualOptions: ParallaxOptions; }; diff --git a/interactions/external/particle/src/InteractivityParticleMaker.ts b/interactions/external/particle/src/InteractivityParticleMaker.ts index dc083b5c53f..e1ce36374a6 100644 --- a/interactions/external/particle/src/InteractivityParticleMaker.ts +++ b/interactions/external/particle/src/InteractivityParticleMaker.ts @@ -19,9 +19,9 @@ import { InteractivityParticleOptions } from "./Options/Classes/InteractivityPar const particleMode = "particle"; -/** - */ +/** Interactivity particle maker interactor */ export class InteractivityParticleMaker extends ExternalInteractorBase { + /** @inheritDoc */ readonly maxDistance = 0; private _clearTimeout?: number; @@ -33,14 +33,17 @@ export class InteractivityParticleMaker extends ExternalInteractorBase[] @@ -163,6 +168,7 @@ export class InteractivityParticleMaker extends ExternalInteractorBase { + /** The particle options applied to the interactivity particle */ options?: RecursivePartial; + + /** Whether to pause the particle when the mouse stops moving */ pauseOnStop: boolean; + + /** Whether to replace the cursor with a custom one */ replaceCursor: boolean; + + /** The delay in milliseconds before stopping the particle */ stopDelay: number; constructor() { @@ -23,6 +29,7 @@ export class InteractivityParticleOptions this.stopDelay = 0; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/particle/src/Options/Classes/InteractivityParticleOptionsData.ts b/interactions/external/particle/src/Options/Classes/InteractivityParticleOptionsData.ts index 9873b7f9683..14c8caea449 100644 --- a/interactions/external/particle/src/Options/Classes/InteractivityParticleOptionsData.ts +++ b/interactions/external/particle/src/Options/Classes/InteractivityParticleOptionsData.ts @@ -1,6 +1,7 @@ import type { Options } from "@tsparticles/engine"; import type { ParticleMode } from "../../Types.js"; +/** Interactivity particle options data type */ export type InteractivityParticleOptionsData = Options & { interactivity?: { modes: ParticleMode; diff --git a/interactions/external/particle/src/Options/Interfaces/IInteractivityParticleOptions.ts b/interactions/external/particle/src/Options/Interfaces/IInteractivityParticleOptions.ts index 472d4492ccf..d1be5005b70 100644 --- a/interactions/external/particle/src/Options/Interfaces/IInteractivityParticleOptions.ts +++ b/interactions/external/particle/src/Options/Interfaces/IInteractivityParticleOptions.ts @@ -1,10 +1,13 @@ import type { IParticlesOptions, RecursivePartial } from "@tsparticles/engine"; -/** - */ +/** The interactivity particle options */ export interface IInteractivityParticleOptions { + /** The particle options to use when spawning */ options?: RecursivePartial; + /** Pause the animation when the mouse stops interacting */ pauseOnStop: boolean; + /** Replace the cursor with the particle image */ replaceCursor: boolean; + /** The delay before stopping the animation */ stopDelay: number; } diff --git a/interactions/external/particle/src/Types.ts b/interactions/external/particle/src/Types.ts index a40a5d03ca9..e8278d9765b 100644 --- a/interactions/external/particle/src/Types.ts +++ b/interactions/external/particle/src/Types.ts @@ -3,14 +3,17 @@ import type { InteractivityContainer } from "@tsparticles/plugin-interactivity"; import type { InteractivityParticleOptions } from "./Options/Classes/InteractivityParticleOptions.js"; import type { InteractivityParticleOptionsData } from "./Options/Classes/InteractivityParticleOptionsData.js"; +/** Particle mode interface */ export interface IParticleMode { particle: IInteractivityParticleOptions; } +/** Particle mode options */ export interface ParticleMode { particle?: InteractivityParticleOptions; } +/** Interactivity particle container */ export type InteractivityParticleContainer = InteractivityContainer & { actualOptions: InteractivityParticleOptionsData; }; diff --git a/interactions/external/pause/src/Pauser.ts b/interactions/external/pause/src/Pauser.ts index f25a0552de6..cc43f708be9 100644 --- a/interactions/external/pause/src/Pauser.ts +++ b/interactions/external/pause/src/Pauser.ts @@ -12,8 +12,10 @@ const pauseMode = "pause"; * Particle attract manager */ export class Pauser extends ExternalInteractorBase { + /** @inheritDoc */ handleClickMode: (mode: string, interactivityData: IInteractivityData) => void; + /** @inheritDoc */ readonly maxDistance = 0; constructor(container: InteractivityContainer) { @@ -34,18 +36,22 @@ export class Pauser extends ExternalInteractorBase { }; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { // do nothing } + /** @inheritDoc */ interact(): void { // do nothing } + /** @inheritDoc */ isEnabled(_interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, options = container.actualOptions, @@ -54,6 +60,7 @@ export class Pauser extends ExternalInteractorBase { return !!events && isInArray(pauseMode, events.onClick.mode); } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/external/pop/src/Popper.ts b/interactions/external/pop/src/Popper.ts index 01d74cd3285..451dd49d3ed 100644 --- a/interactions/external/pop/src/Popper.ts +++ b/interactions/external/pop/src/Popper.ts @@ -12,8 +12,10 @@ const popMode = "pop"; * Particle attract manager */ export class Popper extends ExternalInteractorBase { + /** @inheritDoc */ handleClickMode: (mode: string, interactivityData: IInteractivityData) => void; + /** @inheritDoc */ readonly maxDistance = 0; constructor(container: InteractivityContainer) { @@ -44,18 +46,22 @@ export class Popper extends ExternalInteractorBase { }; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { // do nothing } + /** @inheritDoc */ interact(): void { // do nothing } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, options = container.actualOptions, @@ -65,6 +71,7 @@ export class Popper extends ExternalInteractorBase { return !!events && mouse.clicking && mouse.inside && !!mouse.position && isInArray(popMode, events.onClick.mode); } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/external/push/src/Options/Classes/Push.ts b/interactions/external/push/src/Options/Classes/Push.ts index c73ff1137d0..ce3ec1dc55e 100644 --- a/interactions/external/push/src/Options/Classes/Push.ts +++ b/interactions/external/push/src/Options/Classes/Push.ts @@ -11,12 +11,15 @@ import { } from "@tsparticles/engine"; import type { IPush } from "../Interfaces/IPush.js"; -/** - */ +/** Push mode options class */ export class Push implements IPush, IOptionLoader { + /** Whether to use the default groups */ default; + /** Groups to push particles from */ groups: string[]; + /** Particles options for pushed particles */ particles?: SingleOrMultiple>; + /** Number of particles to push */ quantity: RangeValue; constructor() { @@ -25,6 +28,7 @@ export class Push implements IPush, IOptionLoader { this.quantity = 4; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/push/src/Options/Interfaces/IPush.ts b/interactions/external/push/src/Options/Interfaces/IPush.ts index 4f6655755c3..a41eb939d27 100644 --- a/interactions/external/push/src/Options/Interfaces/IPush.ts +++ b/interactions/external/push/src/Options/Interfaces/IPush.ts @@ -1,10 +1,13 @@ import type { IParticlesOptions, RangeValue, RecursivePartial, SingleOrMultiple } from "@tsparticles/engine"; -/** - */ +/** Push mode options */ export interface IPush { + /** Whether to use the default groups */ default: boolean; + /** Groups to push particles from */ groups: string[]; + /** Particles options for pushed particles */ particles?: SingleOrMultiple>; + /** Number of particles to push */ quantity: RangeValue; } diff --git a/interactions/external/push/src/Pusher.ts b/interactions/external/push/src/Pusher.ts index 08dbbadde78..188948027e3 100644 --- a/interactions/external/push/src/Pusher.ts +++ b/interactions/external/push/src/Pusher.ts @@ -24,8 +24,10 @@ const pushMode = "push", * Particle attract manager */ export class Pusher extends ExternalInteractorBase { + /** @inheritDoc */ handleClickMode: (mode: string, interactivityData: IInteractivityData) => void; + /** @inheritDoc */ readonly maxDistance = 0; constructor(container: PushContainer) { @@ -59,18 +61,22 @@ export class Pusher extends ExternalInteractorBase { }; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { // do nothing } + /** @inheritDoc */ interact(): void { // do nothing } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, options = container.actualOptions, @@ -80,6 +86,7 @@ export class Pusher extends ExternalInteractorBase { return !!events && mouse.clicking && mouse.inside && !!mouse.position && isInArray(pushMode, events.onClick.mode); } + /** @inheritDoc */ loadModeOptions(options: Modes & PushMode, ...sources: RecursivePartial<(IModes & IPushMode) | undefined>[]): void { options.push ??= new Push(); @@ -88,6 +95,7 @@ export class Pusher extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/external/remove/src/Options/Classes/Remove.ts b/interactions/external/remove/src/Options/Classes/Remove.ts index 5fdcf156e35..d55df0dbca8 100644 --- a/interactions/external/remove/src/Options/Classes/Remove.ts +++ b/interactions/external/remove/src/Options/Classes/Remove.ts @@ -1,15 +1,16 @@ import { type IOptionLoader, type RangeValue, type RecursivePartial, isNull, setRangeValue } from "@tsparticles/engine"; import type { IRemove } from "../Interfaces/IRemove.js"; -/** - */ +/** Remove mode options class */ export class Remove implements IRemove, IOptionLoader { + /** Number of particles to remove */ quantity: RangeValue; constructor() { this.quantity = 2; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/remove/src/Options/Interfaces/IRemove.ts b/interactions/external/remove/src/Options/Interfaces/IRemove.ts index 94fa9eac742..93c31f63fdf 100644 --- a/interactions/external/remove/src/Options/Interfaces/IRemove.ts +++ b/interactions/external/remove/src/Options/Interfaces/IRemove.ts @@ -1,7 +1,7 @@ import type { RangeValue } from "@tsparticles/engine"; -/** - */ +/** Remove mode options */ export interface IRemove { + /** Number of particles to remove */ quantity: RangeValue; } diff --git a/interactions/external/remove/src/Remover.ts b/interactions/external/remove/src/Remover.ts index 39e23e361e7..76b41d13763 100644 --- a/interactions/external/remove/src/Remover.ts +++ b/interactions/external/remove/src/Remover.ts @@ -15,8 +15,10 @@ const removeMode = "remove"; * Particle attract manager */ export class Remover extends ExternalInteractorBase { + /** @inheritDoc */ handleClickMode: (mode: string, interactivityData: IInteractivityData) => void; + /** @inheritDoc */ readonly maxDistance = 0; constructor(container: RemoveContainer) { @@ -38,18 +40,22 @@ export class Remover extends ExternalInteractorBase { }; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { // do nothing } + /** @inheritDoc */ interact(): void { // do nothing } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, options = container.actualOptions, @@ -59,6 +65,7 @@ export class Remover extends ExternalInteractorBase { return !!events && mouse.clicking && mouse.inside && !!mouse.position && isInArray(removeMode, events.onClick.mode); } + /** @inheritDoc */ loadModeOptions( options: Modes & RemoveMode, ...sources: RecursivePartial<(IModes & IRemoveMode) | undefined>[] @@ -70,6 +77,7 @@ export class Remover extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/external/repulse/src/Options/Classes/Repulse.ts b/interactions/external/repulse/src/Options/Classes/Repulse.ts index 1b2ae417b0d..264abc7bb29 100644 --- a/interactions/external/repulse/src/Options/Classes/Repulse.ts +++ b/interactions/external/repulse/src/Options/Classes/Repulse.ts @@ -9,11 +9,12 @@ import type { IRepulse } from "../Interfaces/IRepulse.js"; import { RepulseBase } from "./RepulseBase.js"; import { RepulseDiv } from "./RepulseDiv.js"; -/** - */ +/** Repulse mode options class */ export class Repulse extends RepulseBase implements IRepulse, IOptionLoader { + /** Repulse divs to apply the mode to */ divs?: SingleOrMultiple; + /** @inheritDoc */ override load(data?: RecursivePartial): void { super.load(data); diff --git a/interactions/external/repulse/src/Options/Classes/RepulseBase.ts b/interactions/external/repulse/src/Options/Classes/RepulseBase.ts index 4567f165ce4..ca4cf0e0222 100644 --- a/interactions/external/repulse/src/Options/Classes/RepulseBase.ts +++ b/interactions/external/repulse/src/Options/Classes/RepulseBase.ts @@ -2,13 +2,20 @@ import { EasingType, type EasingTypeAlt, type IOptionLoader, type RecursiveParti import type { IRepulseBase } from "../Interfaces/IRepulseBase.js"; /** + * Repulse mode base options */ export abstract class RepulseBase implements IRepulseBase, IOptionLoader { + /** Repulse distance in pixels */ distance; + /** Repulse animation duration in seconds */ duration; + /** Easing type used for the repulse animation */ easing: EasingType | EasingTypeAlt; + /** Repulse factor multiplier */ factor; + /** Maximum repulse speed */ maxSpeed; + /** Repulse speed */ speed; constructor() { @@ -20,6 +27,7 @@ export abstract class RepulseBase implements IRepulseBase, IOptionLoader): void { if (isNull(data)) { return; diff --git a/interactions/external/repulse/src/Options/Classes/RepulseDiv.ts b/interactions/external/repulse/src/Options/Classes/RepulseDiv.ts index 7646250e302..de1def330ed 100644 --- a/interactions/external/repulse/src/Options/Classes/RepulseDiv.ts +++ b/interactions/external/repulse/src/Options/Classes/RepulseDiv.ts @@ -2,9 +2,9 @@ import { type IOptionLoader, type RecursivePartial, type SingleOrMultiple, isNul import type { IRepulseDiv } from "../Interfaces/IRepulseDiv.js"; import { RepulseBase } from "./RepulseBase.js"; -/** - */ +/** Repulse mode div options class */ export class RepulseDiv extends RepulseBase implements IRepulseDiv, IOptionLoader { + /** CSS selectors for div elements to apply repulse to */ selectors: SingleOrMultiple; constructor() { @@ -13,6 +13,7 @@ export class RepulseDiv extends RepulseBase implements IRepulseDiv, IOptionLoade this.selectors = []; } + /** @inheritDoc */ override load(data?: RecursivePartial): void { super.load(data); diff --git a/interactions/external/repulse/src/Options/Interfaces/IRepulse.ts b/interactions/external/repulse/src/Options/Interfaces/IRepulse.ts index ffaf5d83431..e7e387f7dbd 100644 --- a/interactions/external/repulse/src/Options/Interfaces/IRepulse.ts +++ b/interactions/external/repulse/src/Options/Interfaces/IRepulse.ts @@ -2,8 +2,8 @@ import type { IRepulseBase } from "./IRepulseBase.js"; import type { IRepulseDiv } from "./IRepulseDiv.js"; import type { SingleOrMultiple } from "@tsparticles/engine"; -/** - */ +/** Repulse mode options */ export interface IRepulse extends IRepulseBase { + /** Repulse divs to apply the mode to */ divs?: SingleOrMultiple; } diff --git a/interactions/external/repulse/src/Options/Interfaces/IRepulseBase.ts b/interactions/external/repulse/src/Options/Interfaces/IRepulseBase.ts index 47d37a586bb..bfc71b701c4 100644 --- a/interactions/external/repulse/src/Options/Interfaces/IRepulseBase.ts +++ b/interactions/external/repulse/src/Options/Interfaces/IRepulseBase.ts @@ -1,12 +1,19 @@ import type { EasingType, EasingTypeAlt } from "@tsparticles/engine"; /** + * Repulse mode base options */ export interface IRepulseBase { + /** Repulse distance in pixels */ distance: number; + /** Repulse animation duration in seconds */ duration: number; + /** Repulse animation easing type */ easing: EasingType | EasingTypeAlt; + /** Repulse factor multiplier */ factor: number; + /** Maximum repulse speed */ maxSpeed: number; + /** Repulse speed */ speed: number; } diff --git a/interactions/external/repulse/src/Options/Interfaces/IRepulseDiv.ts b/interactions/external/repulse/src/Options/Interfaces/IRepulseDiv.ts index 76302943d9e..22fbc4f062a 100644 --- a/interactions/external/repulse/src/Options/Interfaces/IRepulseDiv.ts +++ b/interactions/external/repulse/src/Options/Interfaces/IRepulseDiv.ts @@ -1,6 +1,5 @@ import type { IModeDiv } from "@tsparticles/plugin-interactivity"; import type { IRepulseBase } from "./IRepulseBase.js"; -/** - */ +/** Repulse mode div options */ export interface IRepulseDiv extends IRepulseBase, IModeDiv {} diff --git a/interactions/external/repulse/src/Repulser.ts b/interactions/external/repulse/src/Repulser.ts index 4ad7db7a50b..8ef0ef086e2 100644 --- a/interactions/external/repulse/src/Repulser.ts +++ b/interactions/external/repulse/src/Repulser.ts @@ -43,6 +43,7 @@ const repulseMode = "repulse", * Particle repulse manager */ export class Repulser extends ExternalInteractorBase { + /** @inheritDoc */ handleClickMode: (mode: string, interactivityData: IInteractivityData) => void; private readonly _clickVec: Vector; @@ -100,10 +101,12 @@ export class Repulser extends ExternalInteractorBase { return this._maxDistance; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { const container = this.container, repulse = container.actualOptions.interactivity?.modes.repulse; @@ -117,6 +120,7 @@ export class Repulser extends ExternalInteractorBase { container.retina.repulseModeDistance = repulse.distance * container.retina.pixelRatio; } + /** @inheritDoc */ interact(interactivityData: IInteractivityData): void { const container = this.container, options = container.actualOptions, @@ -146,6 +150,7 @@ export class Repulser extends ExternalInteractorBase { } } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, options = container.actualOptions, @@ -171,6 +176,7 @@ export class Repulser extends ExternalInteractorBase { return isInArray(repulseMode, hoverMode) || isInArray(repulseMode, clickMode) || divRepulse; } + /** @inheritDoc */ loadModeOptions( options: Modes & RepulseMode, ...sources: RecursivePartial<(IModes & IRepulseMode) | undefined>[] @@ -182,6 +188,7 @@ export class Repulser extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/external/repulse/src/Types.ts b/interactions/external/repulse/src/Types.ts index b22247a8986..3df0d4a832e 100644 --- a/interactions/external/repulse/src/Types.ts +++ b/interactions/external/repulse/src/Types.ts @@ -12,10 +12,17 @@ export interface RepulseMode { repulse?: Repulse; } -interface IContainerRepulse { +/** + * Container repulse data + */ +export interface IContainerRepulse { + /** Whether the user is clicking */ clicking?: boolean; + /** Number of repulsed particles */ count?: number; + /** Whether the repulse action has finished */ finish?: boolean; + /** Particles being repulsed */ particles: Particle[]; } diff --git a/interactions/external/slow/src/Options/Classes/Slow.ts b/interactions/external/slow/src/Options/Classes/Slow.ts index a97398cd79a..08504c572b3 100644 --- a/interactions/external/slow/src/Options/Classes/Slow.ts +++ b/interactions/external/slow/src/Options/Classes/Slow.ts @@ -1,10 +1,11 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { ISlow } from "../Interfaces/ISlow.js"; -/** - */ +/** Slow mode options class */ export class Slow implements ISlow, IOptionLoader { + /** Slow factor multiplier */ factor; + /** Slow radius in pixels */ radius; constructor() { @@ -12,6 +13,7 @@ export class Slow implements ISlow, IOptionLoader { this.radius = 200; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/external/slow/src/Options/Interfaces/ISlow.ts b/interactions/external/slow/src/Options/Interfaces/ISlow.ts index 7671736e27a..b86abf7e049 100644 --- a/interactions/external/slow/src/Options/Interfaces/ISlow.ts +++ b/interactions/external/slow/src/Options/Interfaces/ISlow.ts @@ -1,6 +1,7 @@ -/** - */ +/** Slow mode options */ export interface ISlow { + /** Slow factor multiplier */ factor: number; + /** Slow radius in pixels */ radius: number; } diff --git a/interactions/external/slow/src/Slower.ts b/interactions/external/slow/src/Slower.ts index 92d5f1a03cc..cfb3d2dcbe5 100644 --- a/interactions/external/slow/src/Slower.ts +++ b/interactions/external/slow/src/Slower.ts @@ -24,10 +24,12 @@ export class Slower extends ExternalInteractorBase { this._maxDistance = 0; } + /** @inheritDoc */ get maxDistance(): number { return this._maxDistance; } + /** @inheritDoc */ clear(particle: Particle, _delta: IDelta, force?: boolean): void { if (particle.slow.inRange && !force) { return; @@ -36,6 +38,7 @@ export class Slower extends ExternalInteractorBase { particle.slow.factor = 1; } + /** @inheritDoc */ init(): void { const container = this.container, slow = container.actualOptions.interactivity?.modes.slow; @@ -49,10 +52,12 @@ export class Slower extends ExternalInteractorBase { container.retina.slowModeRadius = slow.radius * container.retina.pixelRatio; } + /** @inheritDoc */ interact(): void { // nothing to do } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, mouse = interactivityData.mouse, @@ -61,6 +66,7 @@ export class Slower extends ExternalInteractorBase { return !!events?.onHover.enable && !!mouse.position && isInArray(slowMode, events.onHover.mode); } + /** @inheritDoc */ loadModeOptions(options: Modes & SlowMode, ...sources: RecursivePartial<(IModes & ISlowMode) | undefined>[]): void { options.slow ??= new Slow(); @@ -69,6 +75,7 @@ export class Slower extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(interactivityData: IInteractivityData, particle: Particle): void { particle.slow.inRange = false; diff --git a/interactions/external/trail/src/Options/Classes/Trail.ts b/interactions/external/trail/src/Options/Classes/Trail.ts index 40ebb2819a5..cbb5c0bf945 100644 --- a/interactions/external/trail/src/Options/Classes/Trail.ts +++ b/interactions/external/trail/src/Options/Classes/Trail.ts @@ -8,11 +8,17 @@ import { import type { ITrail } from "../Interfaces/ITrail.js"; import { TrailColorCoords } from "./TrailColorCoords.js"; +/** Trail mode options class */ export class Trail implements ITrail, IOptionLoader { - colorCoords?: TrailColorCoords; // Now initialized by default + /** Optional configuration to map mouse coordinates to particle colors */ + colorCoords?: TrailColorCoords; + /** Trail emission delay in seconds */ delay: number; + /** Trail particles options */ particles?: RecursivePartial; + /** Whether to pause trail when mouse stops moving */ pauseOnStop: boolean; + /** Number of particles to emit per trail step */ quantity: number; constructor() { @@ -22,6 +28,7 @@ export class Trail implements ITrail, IOptionLoader { this.colorCoords = new TrailColorCoords(); } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) return; diff --git a/interactions/external/trail/src/Options/Interfaces/ITrail.ts b/interactions/external/trail/src/Options/Interfaces/ITrail.ts index 70a915963a0..dd4102744c4 100644 --- a/interactions/external/trail/src/Options/Interfaces/ITrail.ts +++ b/interactions/external/trail/src/Options/Interfaces/ITrail.ts @@ -1,14 +1,16 @@ import type { IParticlesOptions, RecursivePartial } from "@tsparticles/engine"; import type { ITrailColorCoords } from "./ITrailColorCoords.js"; +/** Trail mode options */ export interface ITrail { - /** - * Optional configuration to map mouse coordinates to particle colors - */ + /** Optional configuration to map mouse coordinates to particle colors */ colorCoords?: ITrailColorCoords; - + /** Trail emission delay in seconds */ delay: number; + /** Trail particles options */ particles?: RecursivePartial; + /** Whether to pause trail when mouse stops moving */ pauseOnStop: boolean; + /** Number of particles to emit per trail step */ quantity: number; } diff --git a/interactions/external/trail/src/TrailMaker.ts b/interactions/external/trail/src/TrailMaker.ts index 934b963ae31..f92b4bad02a 100644 --- a/interactions/external/trail/src/TrailMaker.ts +++ b/interactions/external/trail/src/TrailMaker.ts @@ -32,7 +32,9 @@ const trailMode = "trail", defaultMin = 0, defaultWeight = 0; +/** Trail mode interactor */ export class TrailMaker extends ExternalInteractorBase { + /** @inheritDoc */ readonly maxDistance = 0; private _delay: number; @@ -45,14 +47,17 @@ export class TrailMaker extends ExternalInteractorBase { this._delay = 0; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { // do nothing } + /** @inheritDoc */ interact(interactivityData: IInteractivityData, delta: IDelta): void { const container = this.container; @@ -149,6 +154,7 @@ export class TrailMaker extends ExternalInteractorBase { this._delay -= optDelay; } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, options = container.actualOptions, @@ -162,6 +168,7 @@ export class TrailMaker extends ExternalInteractorBase { ); } + /** @inheritDoc */ loadModeOptions(options: Modes & TrailMode, ...sources: RecursivePartial<(IModes & ITrailMode) | undefined>[]): void { options.trail ??= new Trail(); for (const source of sources) { @@ -169,6 +176,7 @@ export class TrailMaker extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/external/trail/src/Types.ts b/interactions/external/trail/src/Types.ts index b8c3d58bede..f9cf7c04412 100644 --- a/interactions/external/trail/src/Types.ts +++ b/interactions/external/trail/src/Types.ts @@ -3,14 +3,17 @@ import type { InteractivityContainer } from "@tsparticles/plugin-interactivity"; import type { Trail } from "./Options/Classes/Trail.js"; import type { TrailOptions } from "./Options/Classes/TrailOptions.js"; +/** Trail mode interface */ export interface ITrailMode { trail: ITrail; } +/** Trail mode options interface */ export interface TrailMode { trail?: Trail; } +/** Trail container type */ export type TrailContainer = InteractivityContainer & { actualOptions: TrailOptions; }; diff --git a/interactions/light/src/ExternalLighter.ts b/interactions/light/src/ExternalLighter.ts index 40871196b07..e53160c83cf 100644 --- a/interactions/light/src/ExternalLighter.ts +++ b/interactions/light/src/ExternalLighter.ts @@ -9,7 +9,9 @@ import { type PluginManager, type RecursivePartial, isInArray, rangeColorToRgb } import { drawLight, lightMode } from "./Utils.js"; import { Light } from "./Options/Classes/Light.js"; +/** External light interactor */ export class ExternalLighter extends ExternalInteractorBase { + /** @inheritDoc */ readonly maxDistance = 0; private readonly _pluginManager; @@ -19,14 +21,17 @@ export class ExternalLighter extends ExternalInteractorBase { this._pluginManager = pluginManager; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { // do nothing } + /** @inheritDoc */ interact(interactivityData: IInteractivityData): void { const container = this.container, options = container.actualOptions, @@ -47,6 +52,7 @@ export class ExternalLighter extends ExternalInteractorBase { }); } + /** @inheritDoc */ isEnabled(interactivityData: IInteractivityData, particle?: LightParticle): boolean { const container = this.container, mouse = interactivityData.mouse, @@ -71,6 +77,7 @@ export class ExternalLighter extends ExternalInteractorBase { return res; } + /** @inheritDoc */ loadModeOptions(options: Modes & LightMode, ...sources: RecursivePartial<(IModes & ILightMode) | undefined>[]): void { options.light ??= new Light(); @@ -79,6 +86,7 @@ export class ExternalLighter extends ExternalInteractorBase { } } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/light/src/Options/Classes/Light.ts b/interactions/light/src/Options/Classes/Light.ts index 98967266ebe..451781f7e43 100644 --- a/interactions/light/src/Options/Classes/Light.ts +++ b/interactions/light/src/Options/Classes/Light.ts @@ -3,8 +3,12 @@ import type { ILight } from "../Interfaces/ILight.js"; import { LightArea } from "./LightArea.js"; import { LightShadow } from "./LightShadow.js"; +/** Light mode options class */ export class Light implements ILight, IOptionLoader { + /** The light area options */ area; + + /** The light shadow options */ shadow; constructor() { @@ -12,6 +16,7 @@ export class Light implements ILight, IOptionLoader { this.shadow = new LightShadow(); } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/light/src/Options/Classes/LightArea.ts b/interactions/light/src/Options/Classes/LightArea.ts index bf97be9b811..d35088fc576 100644 --- a/interactions/light/src/Options/Classes/LightArea.ts +++ b/interactions/light/src/Options/Classes/LightArea.ts @@ -2,8 +2,12 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/ import type { ILightArea } from "../Interfaces/ILightArea.js"; import { LightGradient } from "./LightGradient.js"; +/** Light area options class */ export class LightArea implements ILightArea, IOptionLoader { + /** The light gradient options */ gradient; + + /** The light radius */ radius; constructor() { @@ -11,6 +15,7 @@ export class LightArea implements ILightArea, IOptionLoader { this.radius = 1000; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/light/src/Options/Classes/LightGradient.ts b/interactions/light/src/Options/Classes/LightGradient.ts index a6bf189f51c..081974bc998 100644 --- a/interactions/light/src/Options/Classes/LightGradient.ts +++ b/interactions/light/src/Options/Classes/LightGradient.ts @@ -1,8 +1,12 @@ import { type IOptionLoader, OptionsColor, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { ILightGradient } from "../Interfaces/ILightGradient.js"; +/** Light gradient options class */ export class LightGradient implements ILightGradient, IOptionLoader { + /** The start color of the gradient */ start; + + /** The stop color of the gradient */ stop; constructor() { @@ -13,6 +17,7 @@ export class LightGradient implements ILightGradient, IOptionLoader): void { if (isNull(data)) { return; diff --git a/interactions/light/src/Options/Classes/LightOptions.ts b/interactions/light/src/Options/Classes/LightOptions.ts index 781bcd49241..6b92b8f085d 100644 --- a/interactions/light/src/Options/Classes/LightOptions.ts +++ b/interactions/light/src/Options/Classes/LightOptions.ts @@ -1,12 +1,14 @@ import type { InteractivityOptions, InteractivityParticlesOptions } from "@tsparticles/plugin-interactivity"; import type { LightMode } from "../../Types.js"; +/** Light interaction options */ export type LightOptions = InteractivityOptions & { interactivity?: { modes: LightMode; }; }; +/** Light particle options */ export type LightParticlesOptions = InteractivityParticlesOptions & { interactivity?: { modes: LightMode; diff --git a/interactions/light/src/Options/Classes/LightShadow.ts b/interactions/light/src/Options/Classes/LightShadow.ts index 6a90f4a4a3e..521fb57fcad 100644 --- a/interactions/light/src/Options/Classes/LightShadow.ts +++ b/interactions/light/src/Options/Classes/LightShadow.ts @@ -1,8 +1,12 @@ import { type IOptionLoader, OptionsColor, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { ILightShadow } from "../Interfaces/ILightShadow.js"; +/** Light shadow options class */ export class LightShadow implements ILightShadow, IOptionLoader { + /** The shadow color */ color; + + /** The shadow length */ length; constructor() { @@ -12,6 +16,7 @@ export class LightShadow implements ILightShadow, IOptionLoader { this.length = 2000; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/light/src/Options/Interfaces/ILight.ts b/interactions/light/src/Options/Interfaces/ILight.ts index 6a215274c50..2d80855c036 100644 --- a/interactions/light/src/Options/Interfaces/ILight.ts +++ b/interactions/light/src/Options/Interfaces/ILight.ts @@ -1,7 +1,10 @@ import type { ILightArea } from "./ILightArea.js"; import type { ILightShadow } from "./ILightShadow.js"; +/** Light mode options */ export interface ILight { + /** The light area options */ area: ILightArea; + /** The light shadow options */ shadow: ILightShadow; } diff --git a/interactions/light/src/Options/Interfaces/ILightArea.ts b/interactions/light/src/Options/Interfaces/ILightArea.ts index 569738c187d..c2dae510421 100644 --- a/interactions/light/src/Options/Interfaces/ILightArea.ts +++ b/interactions/light/src/Options/Interfaces/ILightArea.ts @@ -1,6 +1,9 @@ import type { ILightGradient } from "./ILightGradient.js"; +/** Light area options */ export interface ILightArea { + /** The light gradient options */ gradient: ILightGradient; + /** The light radius */ radius: number; } diff --git a/interactions/light/src/Options/Interfaces/ILightGradient.ts b/interactions/light/src/Options/Interfaces/ILightGradient.ts index d958c9ffb33..d185607b152 100644 --- a/interactions/light/src/Options/Interfaces/ILightGradient.ts +++ b/interactions/light/src/Options/Interfaces/ILightGradient.ts @@ -1,6 +1,9 @@ import type { IOptionsColor } from "@tsparticles/engine"; +/** Light gradient options */ export interface ILightGradient { + /** The start color of the gradient */ start: string | IOptionsColor; + /** The stop color of the gradient */ stop: string | IOptionsColor; } diff --git a/interactions/light/src/Options/Interfaces/ILightShadow.ts b/interactions/light/src/Options/Interfaces/ILightShadow.ts index b6e6c8194cc..a97d5f32a60 100644 --- a/interactions/light/src/Options/Interfaces/ILightShadow.ts +++ b/interactions/light/src/Options/Interfaces/ILightShadow.ts @@ -1,6 +1,9 @@ import type { IOptionsColor } from "@tsparticles/engine"; +/** Light shadow options */ export interface ILightShadow { + /** The shadow color */ color: string | IOptionsColor; + /** The shadow length */ length: number; } diff --git a/interactions/light/src/ParticlesLighter.ts b/interactions/light/src/ParticlesLighter.ts index ae440c60350..8a16dacda28 100644 --- a/interactions/light/src/ParticlesLighter.ts +++ b/interactions/light/src/ParticlesLighter.ts @@ -3,7 +3,9 @@ import type { LightContainer, LightParticle } from "./Types.js"; import { type PluginManager, isInArray, rangeColorToRgb } from "@tsparticles/engine"; import { drawParticleShadow, lightMode } from "./Utils.js"; +/** Particles lighter interactor */ export class ParticlesLighter extends ParticlesInteractorBase { + /** @inheritDoc */ readonly maxDistance; private readonly _pluginManager; @@ -15,14 +17,17 @@ export class ParticlesLighter extends ParticlesInteractorBase { this.maxDistance = 0; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { // do nothing } + /** @inheritDoc */ interact(particle: LightParticle, interactivityData: IInteractivityData): void { const container = this.container, options = container.actualOptions; @@ -42,6 +47,7 @@ export class ParticlesLighter extends ParticlesInteractorBase { }); } + /** @inheritDoc */ isEnabled(particle: LightParticle, interactivityData: IInteractivityData): boolean { const interactivity = particle.interactivity, mouse = interactivityData.mouse, @@ -62,6 +68,7 @@ export class ParticlesLighter extends ParticlesInteractorBase { return res; } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/light/src/Types.ts b/interactions/light/src/Types.ts index 97a3895fe04..fc7eb75c5e0 100644 --- a/interactions/light/src/Types.ts +++ b/interactions/light/src/Types.ts @@ -4,14 +4,17 @@ import type { ILight } from "./Options/Interfaces/ILight.js"; import type { IRgb } from "@tsparticles/engine"; import type { Light } from "./Options/Classes/Light.js"; +/** Light mode interface */ export interface ILightMode { light?: ILight; } +/** Light mode options */ export interface LightMode { light?: Light; } +/** Light container interface */ export type LightContainer = InteractivityContainer & { actualOptions: LightOptions; canvas: { @@ -19,6 +22,7 @@ export type LightContainer = InteractivityContainer & { }; }; +/** Light particle interface */ export type LightParticle = InteractivityParticle & { interactivity: { modes: ILightMode; diff --git a/interactions/light/src/Utils.ts b/interactions/light/src/Utils.ts index e09f0bd0336..89c2905c8f6 100644 --- a/interactions/light/src/Utils.ts +++ b/interactions/light/src/Utils.ts @@ -16,12 +16,14 @@ const gradientPos = { quarterPI = Math.PI * quarter, arcStart = 0; +/** Light mode identifier */ export const lightMode = "light"; /** - * @param container - - * @param context - - * @param mousePos - + * Draw the light area around the mouse + * @param container + * @param context + * @param mousePos */ export function drawLight(container: LightContainer, context: CanvasContextType, mousePos: ICoordinates): void { const lightOptions = container.actualOptions.interactivity?.modes.light?.area; @@ -55,10 +57,11 @@ export function drawLight(container: LightContainer, context: CanvasContextType, } /** - * @param container - - * @param context - - * @param particle - - * @param mousePos - + * Draw the shadow of a particle in light mode + * @param container + * @param context + * @param particle + * @param mousePos */ export function drawParticleShadow( container: LightContainer, diff --git a/interactions/particles/attract/src/Attractor.ts b/interactions/particles/attract/src/Attractor.ts index fda7f36c0d5..8780dcea613 100644 --- a/interactions/particles/attract/src/Attractor.ts +++ b/interactions/particles/attract/src/Attractor.ts @@ -6,8 +6,7 @@ import { ParticlesInteractorBase } from "@tsparticles/plugin-interactivity"; const attractFactor = 1000, identity = 1; -/** - */ +/** Particle attract interactor */ export class Attractor extends ParticlesInteractorBase { private _maxDistance; @@ -17,18 +16,22 @@ export class Attractor extends ParticlesInteractorBase | undefined)[] @@ -85,6 +90,7 @@ export class Attractor extends ParticlesInteractorBase { + /** @inheritDoc */ readonly maxDistance; constructor(container: Container) { @@ -15,14 +18,17 @@ export class Collider extends ParticlesInteractorBase | undefined)[] @@ -79,6 +87,7 @@ export class Collider extends ParticlesInteractorBase { + /** The collisions absorb options */ readonly absorb; + /** The collisions bounce options */ readonly bounce; + /** Enables collisions */ enable; + /** The maximum collision speed */ maxSpeed: RangeValue; + /** The collision mode */ mode: CollisionMode | keyof typeof CollisionMode; + /** The collision overlap options */ readonly overlap; constructor() { diff --git a/interactions/particles/collisions/src/Options/Classes/CollisionsAbsorb.ts b/interactions/particles/collisions/src/Options/Classes/CollisionsAbsorb.ts index 95c59c6f725..e8ff3123107 100644 --- a/interactions/particles/collisions/src/Options/Classes/CollisionsAbsorb.ts +++ b/interactions/particles/collisions/src/Options/Classes/CollisionsAbsorb.ts @@ -2,6 +2,7 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/ import type { ICollisionsAbsorb } from "../Interfaces/ICollisionsAbsorb.js"; export class CollisionsAbsorb implements ICollisionsAbsorb, IOptionLoader { + /** The absorb speed */ speed; constructor() { diff --git a/interactions/particles/collisions/src/Options/Classes/CollisionsOverlap.ts b/interactions/particles/collisions/src/Options/Classes/CollisionsOverlap.ts index 1c8648e9d24..6ab073f340b 100644 --- a/interactions/particles/collisions/src/Options/Classes/CollisionsOverlap.ts +++ b/interactions/particles/collisions/src/Options/Classes/CollisionsOverlap.ts @@ -2,7 +2,9 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/ import type { ICollisionsOverlap } from "../Interfaces/ICollisionsOverlap.js"; export class CollisionsOverlap implements ICollisionsOverlap, IOptionLoader { + /** Enables collision overlap */ enable: boolean; + /** The number of overlap retries */ retries: number; constructor() { diff --git a/interactions/particles/collisions/src/Options/Interfaces/ICollisions.ts b/interactions/particles/collisions/src/Options/Interfaces/ICollisions.ts index 638af9427cc..f7ceefd9097 100644 --- a/interactions/particles/collisions/src/Options/Interfaces/ICollisions.ts +++ b/interactions/particles/collisions/src/Options/Interfaces/ICollisions.ts @@ -7,10 +7,16 @@ import type { ICollisionsOverlap } from "./ICollisionsOverlap.js"; * [[include:Collisions.md]] */ export interface ICollisions { + /** The collisions absorb options */ absorb: ICollisionsAbsorb; + /** The collisions bounce options */ bounce: IParticlesBounce; + /** Enables collisions */ enable: boolean; + /** The maximum collision speed */ maxSpeed: RangeValue; + /** The collision mode */ mode: CollisionMode | keyof typeof CollisionMode; + /** The collision overlap options */ overlap: ICollisionsOverlap; } diff --git a/interactions/particles/collisions/src/Options/Interfaces/ICollisionsAbsorb.ts b/interactions/particles/collisions/src/Options/Interfaces/ICollisionsAbsorb.ts index 542a20647ac..12b889e22a2 100644 --- a/interactions/particles/collisions/src/Options/Interfaces/ICollisionsAbsorb.ts +++ b/interactions/particles/collisions/src/Options/Interfaces/ICollisionsAbsorb.ts @@ -1,3 +1,5 @@ +/** Collisions absorb options */ export interface ICollisionsAbsorb { + /** The absorb speed */ speed: number; } diff --git a/interactions/particles/collisions/src/Options/Interfaces/ICollisionsOverlap.ts b/interactions/particles/collisions/src/Options/Interfaces/ICollisionsOverlap.ts index 6b7698c1bea..5661abd07a4 100644 --- a/interactions/particles/collisions/src/Options/Interfaces/ICollisionsOverlap.ts +++ b/interactions/particles/collisions/src/Options/Interfaces/ICollisionsOverlap.ts @@ -1,4 +1,7 @@ +/** Collisions overlap options */ export interface ICollisionsOverlap { + /** Enables collision overlap */ enable: boolean; + /** The number of overlap retries */ retries: number; } diff --git a/interactions/particles/links/src/Interfaces.ts b/interactions/particles/links/src/Interfaces.ts index 6d81cd6bc24..5e788631e9d 100644 --- a/interactions/particles/links/src/Interfaces.ts +++ b/interactions/particles/links/src/Interfaces.ts @@ -1,29 +1,44 @@ import type { IRangeColor, IRgb, RangeValue } from "@tsparticles/engine"; import type { LinkParticle } from "./Types.js"; +/** Link data between two particles */ export interface ILink { + /** Link line color */ color?: IRgb; + /** Destination particle */ destination: LinkParticle; - /* if true, the link crosses the canvas boundaries */ + /** Whether the link crosses the canvas boundaries */ isWarped?: boolean; + /** Link line opacity */ opacity: number; } +/** Triangle data between linked particles */ export interface ILinkTriangle { + /** Triangle fill opacity */ opacity: number; + /** Triangle vertices */ vertices: LinkParticle[]; } +/** Particles link frequencies */ export interface IParticlesFrequencies { + /** Link frequencies per link id */ links: Map; + /** Triangle frequencies per link id */ triangles: Map; } +/** Twinkle animation options for links */ export interface ITwinkle { links: { + /** Twinkle color */ color: IRangeColor; + /** Enable twinkle animation */ enable: boolean; + /** Twinkle frequency */ frequency: number; + /** Twinkle opacity */ opacity: RangeValue; }; } diff --git a/interactions/particles/links/src/Linker.ts b/interactions/particles/links/src/Linker.ts index efa160ccd39..b159ca67c78 100644 --- a/interactions/particles/links/src/Linker.ts +++ b/interactions/particles/links/src/Linker.ts @@ -37,6 +37,7 @@ function getWarpDistance(pos1: ICoordinates, pos2: ICoordinates, canvasSize: IDi return Math.hypot(warpDistances.x, warpDistances.y); } +/** Particles link interactor */ export class Linker extends ParticlesInteractorBase { private _maxDistance; private readonly _pluginManager; @@ -48,19 +49,23 @@ export class Linker extends ParticlesInteractorBase this._maxDistance = 0; } + /** @inheritDoc */ get maxDistance(): number { return this._maxDistance; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { this.container.particles.linksColor = undefined; this.container.particles.linksColors = new Map(); } + /** @inheritDoc */ interact(p1: LinkParticle): void { if (!p1.options.links) { return; @@ -132,10 +137,12 @@ export class Linker extends ParticlesInteractorBase } } + /** @inheritDoc */ isEnabled(particle: LinkParticle): boolean { return !!particle.options.links?.enable; } + /** @inheritDoc */ loadParticlesOptions( options: ParticlesLinkOptions, ...sources: (RecursivePartial | undefined)[] @@ -146,6 +153,7 @@ export class Linker extends ParticlesInteractorBase } } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/interactions/particles/links/src/Options/Classes/Links.ts b/interactions/particles/links/src/Options/Classes/Links.ts index 52b4b5f0b92..b8c22b29c2f 100644 --- a/interactions/particles/links/src/Options/Classes/Links.ts +++ b/interactions/particles/links/src/Options/Classes/Links.ts @@ -7,17 +7,29 @@ import { LinksTriangle } from "./LinksTriangle.js"; * [[include:Options/Particles/Links.md]] */ export class Links implements ILinks, IOptionLoader { + /** Enables random blinking of link colors */ blink; + /** Link line color */ color; + /** Whether a random color applies to all links (consent) */ consent; + /** Maximum link line distance */ distance; + /** Enables particle links */ enable; + /** Link frequency */ frequency; + /** Link ID for grouping */ id?: string; + /** Maximum link opacity */ opacity; + /** Link shadow options */ shadow; + /** Link triangle fill options */ triangles; + /** Enable link wrap around canvas edges */ warp; + /** Link line width */ width; constructor() { @@ -35,6 +47,7 @@ export class Links implements ILinks, IOptionLoader { this.warp = false; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/particles/links/src/Options/Classes/LinksShadow.ts b/interactions/particles/links/src/Options/Classes/LinksShadow.ts index e72650a2454..c62b2ec598a 100644 --- a/interactions/particles/links/src/Options/Classes/LinksShadow.ts +++ b/interactions/particles/links/src/Options/Classes/LinksShadow.ts @@ -1,11 +1,13 @@ import { type IOptionLoader, OptionsColor, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { ILinksShadow } from "../Interfaces/ILinksShadow.js"; -/** - */ +/** Links shadow options class */ export class LinksShadow implements ILinksShadow, IOptionLoader { + /** Shadow blur radius */ blur; + /** Shadow color */ color; + /** Enables link shadow */ enable; constructor() { @@ -15,6 +17,7 @@ export class LinksShadow implements ILinksShadow, IOptionLoader { this.enable = false; } + /** @inheritDoc */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/interactions/particles/links/src/Options/Classes/LinksTriangle.ts b/interactions/particles/links/src/Options/Classes/LinksTriangle.ts index dfc9de76f01..d9438895452 100644 --- a/interactions/particles/links/src/Options/Classes/LinksTriangle.ts +++ b/interactions/particles/links/src/Options/Classes/LinksTriangle.ts @@ -1,12 +1,15 @@ import { type IOptionLoader, OptionsColor, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { ILinksTriangle } from "../Interfaces/ILinksTriangle.js"; -/** - */ +/** Links triangle options class */ export class LinksTriangle implements ILinksTriangle, IOptionLoader { + /** Triangle fill color */ color?: OptionsColor; + /** Enables link triangles */ enable; + /** Triangle fill frequency */ frequency; + /** Triangle fill opacity */ opacity?: number; constructor() { @@ -14,6 +17,7 @@ export class LinksTriangle implements ILinksTriangle, IOptionLoader): void { if (isNull(data)) { return; diff --git a/interactions/particles/links/src/Options/Interfaces/ILinksShadow.ts b/interactions/particles/links/src/Options/Interfaces/ILinksShadow.ts index 265ecaf30da..2a1b879d88f 100644 --- a/interactions/particles/links/src/Options/Interfaces/ILinksShadow.ts +++ b/interactions/particles/links/src/Options/Interfaces/ILinksShadow.ts @@ -1,9 +1,11 @@ import type { IOptionsColor } from "@tsparticles/engine"; -/** - */ +/** Links shadow options */ export interface ILinksShadow { + /** Shadow blur radius */ blur: number; + /** Shadow color */ color: string | IOptionsColor; + /** Enables link shadow */ enable: boolean; } diff --git a/interactions/particles/links/src/Options/Interfaces/ILinksTriangle.ts b/interactions/particles/links/src/Options/Interfaces/ILinksTriangle.ts index e778910167b..3338916c8f8 100644 --- a/interactions/particles/links/src/Options/Interfaces/ILinksTriangle.ts +++ b/interactions/particles/links/src/Options/Interfaces/ILinksTriangle.ts @@ -1,10 +1,13 @@ import type { IOptionsColor } from "@tsparticles/engine"; -/** - */ +/** Links triangle options */ export interface ILinksTriangle { + /** Triangle fill color */ color?: string | IOptionsColor; + /** Enables link triangles */ enable: boolean; + /** Triangle fill frequency */ frequency: number; + /** Triangle fill opacity */ opacity?: number; } diff --git a/interactions/particles/links/src/Types.ts b/interactions/particles/links/src/Types.ts index 4b0fb64075e..39cec76bcdf 100644 --- a/interactions/particles/links/src/Types.ts +++ b/interactions/particles/links/src/Types.ts @@ -9,6 +9,7 @@ import type { ILinks } from "./Options/Interfaces/ILinks.js"; import type { IRgb } from "@tsparticles/engine"; import type { Links } from "./Options/Classes/Links.js"; +/** Link container type */ export type LinkContainer = InteractivityContainer & { particles: { linksColor?: IRgb | string; @@ -16,6 +17,7 @@ export type LinkContainer = InteractivityContainer & { }; }; +/** Link particle type */ export type LinkParticle = InteractivityParticle & { links?: ILink[]; linksDistance?: number; @@ -27,23 +29,34 @@ export type LinkParticle = InteractivityParticle & { }; }; +/** Link batch data for rendering */ export interface LinkBatch { + /** CSS color string */ colorStyle: string; + /** Quad vertex coordinates [x1,y1, x2,y2, x3,y3, x4,y4] */ coords: number[]; + /** Line opacity */ opacity: number; + /** Line width */ width: number; } +/** Triangle batch data for rendering */ export interface TriangleBatch { + /** CSS color string */ colorStyle: string; + /** Triangle vertex coordinates [x1,y1, x2,y2, x3,y3] */ coords: number[]; + /** Triangle fill opacity */ opacity: number; } +/** Particles link options interface */ export type IParticlesLinkOptions = IInteractivityParticlesOptions & { links?: ILinks; }; +/** Particles link options class */ export type ParticlesLinkOptions = InteractivityParticlesOptions & { links?: Links; }; diff --git a/interactions/particles/repulse/src/Options/Classes/ParticlesRepulse.ts b/interactions/particles/repulse/src/Options/Classes/ParticlesRepulse.ts index c242715985d..3e0d50d50bd 100644 --- a/interactions/particles/repulse/src/Options/Classes/ParticlesRepulse.ts +++ b/interactions/particles/repulse/src/Options/Classes/ParticlesRepulse.ts @@ -8,13 +8,17 @@ import { } from "@tsparticles/engine"; import type { IParticlesRepulse } from "../Interfaces/IParticlesRepulse.js"; -/** - */ +/** Particles repulse options class */ export class ParticlesRepulse extends ValueWithRandom implements IParticlesRepulse, IOptionLoader { + /** Repulse distance */ distance: RangeValue; + /** Repulse duration */ duration: RangeValue; + /** Enables particle repulse */ enabled; + /** Repulse factor */ factor: RangeValue; + /** Repulse speed */ speed: RangeValue; constructor() { @@ -26,6 +30,7 @@ export class ParticlesRepulse extends ValueWithRandom implements IParticlesRepul this.speed = 1; } + /** @inheritDoc */ override load(data?: RecursivePartial): void { super.load(data); diff --git a/interactions/particles/repulse/src/Options/Interfaces/IParticlesRepulse.ts b/interactions/particles/repulse/src/Options/Interfaces/IParticlesRepulse.ts index 0b491803971..fd7c5700a86 100644 --- a/interactions/particles/repulse/src/Options/Interfaces/IParticlesRepulse.ts +++ b/interactions/particles/repulse/src/Options/Interfaces/IParticlesRepulse.ts @@ -1,13 +1,15 @@ import type { IValueWithRandom, RangeValue } from "@tsparticles/engine"; -/** - - * [[include:Options/Particles/Repulse.md]] - */ +/** Particles repulse options */ export interface IParticlesRepulse extends IValueWithRandom { + /** Repulse distance */ distance: RangeValue; + /** Repulse duration */ duration: RangeValue; + /** Enables particle repulse */ enabled: boolean; + /** Repulse factor */ factor: RangeValue; + /** Repulse speed */ speed: RangeValue; } diff --git a/interactions/particles/repulse/src/Repulser.ts b/interactions/particles/repulse/src/Repulser.ts index e1763e26cf3..e7ee7bd6753 100644 --- a/interactions/particles/repulse/src/Repulser.ts +++ b/interactions/particles/repulse/src/Repulser.ts @@ -8,15 +8,21 @@ const minDistance = 0, squareExp = 2, minVelocity = 0; -type RepulseParticle = Particle & { +/** Repulse particle extension type */ +export type RepulseParticle = Particle & { options: RepulseParticlesOptions; + /** Repulse interaction data for this particle */ repulse?: { + /** Repulse distance */ distance: number; + /** Repulse factor */ factor: number; + /** Repulse speed */ speed: number; }; }; +/** Particles repulse interactor */ export class Repulser extends ParticlesInteractorBase { private _maxDistance; private readonly _normVec: Vector; @@ -30,18 +36,22 @@ export class Repulser extends ParticlesInteractorBase { this._velocityVec = Vector.origin; } + /** @inheritDoc */ get maxDistance(): number { return this._maxDistance; } + /** @inheritDoc */ clear(): void { // do nothing } + /** @inheritDoc */ init(): void { // do nothing } + /** @inheritDoc */ interact(p1: RepulseParticle): void { const container = this.container; @@ -97,10 +107,12 @@ export class Repulser extends ParticlesInteractorBase { } } + /** @inheritDoc */ isEnabled(particle: RepulseParticle): boolean { return particle.options.repulse?.enabled ?? false; } + /** @inheritDoc */ loadParticlesOptions?( options: RepulseParticlesOptions, ...sources: (RecursivePartial | undefined)[] @@ -112,6 +124,7 @@ export class Repulser extends ParticlesInteractorBase { } } + /** @inheritDoc */ reset(): void { // do nothing } diff --git a/paths/branches/src/BranchesPathGenerator.ts b/paths/branches/src/BranchesPathGenerator.ts index e7e66919ca6..945722f8f5e 100644 --- a/paths/branches/src/BranchesPathGenerator.ts +++ b/paths/branches/src/BranchesPathGenerator.ts @@ -15,11 +15,19 @@ const defaultOptions = { }, }; +/** Branches path generator plugin */ export class BranchesPathGenerator implements IMovePathGenerator { + /** Branches path options */ readonly options: IBranchesPathOptions; + /** The particles container */ private readonly _container; + /** The result vector */ private readonly _res: Vector; + /** + * BranchesPathGenerator constructor + * @param container + */ constructor(container: Container) { this._container = container; this._res = Vector.origin; @@ -30,6 +38,10 @@ export class BranchesPathGenerator implements IMovePathGenerator { }; } + /** + * Generates the next movement vector for the particle + * @param p + */ generate(p: BranchesPathParticle): Vector { const opts = this.options; @@ -80,6 +92,7 @@ export class BranchesPathGenerator implements IMovePathGenerator { return this._res; } + /** Initializes the path generator options */ init(): void { const source = this._container.actualOptions.particles.move.path.options; @@ -100,10 +113,15 @@ export class BranchesPathGenerator implements IMovePathGenerator { } } + /** + * Resets the particle branching state + * @param p + */ reset(p: BranchesPathParticle): void { delete p.branching; } + /** Updates the path generator (no-op) */ update(): void { // nothing to do } diff --git a/paths/brownian/src/BrownianPathGenerator.ts b/paths/brownian/src/BrownianPathGenerator.ts index 0f28f5c3ffd..1f2fe6ec6ad 100644 --- a/paths/brownian/src/BrownianPathGenerator.ts +++ b/paths/brownian/src/BrownianPathGenerator.ts @@ -4,11 +4,19 @@ import type { BrownianPathParticle } from "./BrownianPathParticle.js"; import type { IBrownianPathOptions } from "./IBrownianPathOptions.js"; import { type IMovePathGenerator } from "@tsparticles/plugin-move"; +/** Brownian motion path generator plugin */ export class BrownianPathGenerator implements IMovePathGenerator { + /** Brownian path options */ readonly options: IBrownianPathOptions; + /** The particles container */ private readonly _container: Container; + /** The result vector */ private readonly _res: Vector; + /** + * BrownianPathGenerator constructor + * @param container + */ constructor(container: Container) { this._container = container; this._res = Vector.origin; @@ -19,6 +27,10 @@ export class BrownianPathGenerator implements IMovePathGenerator { }; } + /** + * Generates the next movement vector for the particle + * @param p + */ generate(p: BrownianPathParticle): Vector { p.brownian ??= { angle: getRandom() * doublePI, @@ -41,6 +53,7 @@ export class BrownianPathGenerator implements IMovePathGenerator { return this._res; } + /** Initializes the path generator options */ init(): void { const source = this._container.actualOptions.particles.move.path.options; @@ -48,10 +61,15 @@ export class BrownianPathGenerator implements IMovePathGenerator { this.options.damping = (source["damping"] as number | undefined) ?? this.options.damping; } + /** + * Resets the particle brownian state + * @param p + */ reset(p: BrownianPathParticle): void { delete p.brownian; } + /** Updates the path generator (no-op) */ update(): void { // nothing to do } diff --git a/paths/curlNoise/src/CurlNoiseGenerator.ts b/paths/curlNoise/src/CurlNoiseGenerator.ts index a7293e31bbd..02aa5e535c4 100644 --- a/paths/curlNoise/src/CurlNoiseGenerator.ts +++ b/paths/curlNoise/src/CurlNoiseGenerator.ts @@ -8,7 +8,9 @@ const defaultOptions: ICurlOptions = { step: 250, }; +/** Curl noise path generator for particle motion */ export class CurlNoiseGenerator implements IMovePathGenerator { + /** Curl noise configuration options */ readonly options; private readonly _container; @@ -25,6 +27,10 @@ export class CurlNoiseGenerator implements IMovePathGenerator { this.options = deepExtend({}, defaultOptions) as ICurlOptions; } + /** + * Generates a curl noise vector for the given particle + * @param particle + */ generate(particle: Particle): Vector { const pos = particle.getPosition(), { speed, step } = this.options, @@ -47,6 +53,7 @@ export class CurlNoiseGenerator implements IMovePathGenerator { return this._res; } + /** Initializes the curl noise generator with container options */ init(): void { const container = this._container, sourceOptions = container.actualOptions.particles.move.path.options; @@ -59,10 +66,12 @@ export class CurlNoiseGenerator implements IMovePathGenerator { this._simplex.seed(this.options.seed ?? getRandom()); } + /** Resets the generator state */ reset(): void { // nothing to do } + /** Updates the generator state */ update(): void { // nothing to do } diff --git a/paths/curlNoise/src/ICurlOptions.ts b/paths/curlNoise/src/ICurlOptions.ts index a06af9feffc..d41ae5fa7ef 100644 --- a/paths/curlNoise/src/ICurlOptions.ts +++ b/paths/curlNoise/src/ICurlOptions.ts @@ -1,5 +1,9 @@ +/** Curl noise path options */ export interface ICurlOptions { + /** Random seed for noise generation */ seed?: number; + /** Movement speed along the curl field */ speed: number; + /** Step size for sampling the noise field */ step: number; } diff --git a/paths/curves/src/CurvesPathGenerator.ts b/paths/curves/src/CurvesPathGenerator.ts index 85a989ab235..89e2d50f729 100644 --- a/paths/curves/src/CurvesPathGenerator.ts +++ b/paths/curves/src/CurvesPathGenerator.ts @@ -23,17 +23,28 @@ function randomVelocity(): number { return getRandom() * factor + offset; } +/** Curves path generator plugin */ export class CurvesPathGenerator implements IMovePathGenerator { + /** Curves path options */ readonly options; + /** The particles container */ private readonly _container; + /** + * CurvesPathGenerator constructor + * @param container + */ constructor(container: Container) { this._container = container; this.options = deepExtend({}, defaultOptions) as ICurvesOptions; } + /** + * Generates the next movement vector using curve harmonics + * @param particle + */ generate(particle: CurvesPathParticle): Vector { if (!particle.pathGen) { const { options } = this; @@ -64,6 +75,7 @@ export class CurvesPathGenerator implements IMovePathGenerator { return particle.curveVelocity; } + /** Initializes the path generator options */ init(): void { const sourceOptions = this._container.actualOptions.particles.move.path.options; @@ -83,11 +95,16 @@ export class CurvesPathGenerator implements IMovePathGenerator { this.options.highValue = (sourceOptions["highValue"] as number | undefined) ?? this.options.highValue; } + /** + * Resets the particle curve state + * @param particle + */ reset(particle: CurvesPathParticle): void { delete particle.pathGen; delete particle.curveVelocity; } + /** Updates the path generator (no-op) */ update(): void { // do nothing } diff --git a/paths/fractalNoise/src/FractalNoiseGenerator.ts b/paths/fractalNoise/src/FractalNoiseGenerator.ts index d6a62f25222..b37fa7bd9da 100644 --- a/paths/fractalNoise/src/FractalNoiseGenerator.ts +++ b/paths/fractalNoise/src/FractalNoiseGenerator.ts @@ -2,6 +2,7 @@ import type { Container } from "@tsparticles/engine"; import { FractalNoise } from "@tsparticles/fractal-noise"; import { NoiseFieldGenerator } from "@tsparticles/noise-field"; +/** Fractal noise path generator for particle motion */ export class FractalNoiseGenerator extends NoiseFieldGenerator { constructor(container: Container) { const fractalNoise = new FractalNoise(); diff --git a/paths/grid/src/GridPathGenerator.ts b/paths/grid/src/GridPathGenerator.ts index 837507f053c..8473d4868b1 100644 --- a/paths/grid/src/GridPathGenerator.ts +++ b/paths/grid/src/GridPathGenerator.ts @@ -23,11 +23,19 @@ const dirs = [ opposite = [2, 3, 0, 1], minLength = 0; +/** Grid path generator plugin */ export class GridPathGenerator implements IMovePathGenerator { + /** Grid path options */ readonly options: IGridPathOptions; + /** The particles container */ private readonly _container: Container; + /** The result vector */ private readonly _res: Vector; + /** + * GridPathGenerator constructor + * @param container + */ constructor(container: Container) { this._container = container; this._res = Vector.origin; @@ -40,6 +48,10 @@ export class GridPathGenerator implements IMovePathGenerator { // ------------------------------------------- + /** + * Generates the next movement vector along the grid + * @param p + */ generate(p: GridPathParticle): Vector { const size = this.options.cellSize; @@ -87,6 +99,7 @@ export class GridPathGenerator implements IMovePathGenerator { // ------------------------------------------- + /** Initializes the path generator options */ init(): void { const source = this._container.actualOptions.particles.move.path.options; @@ -107,10 +120,15 @@ export class GridPathGenerator implements IMovePathGenerator { } } + /** + * Resets the particle grid state + * @param p + */ reset(p: GridPathParticle): void { delete p.grid; } + /** Updates the path generator (no-op) */ update(): void { // nothing to do } diff --git a/paths/levy/src/LevyPathGenerator.ts b/paths/levy/src/LevyPathGenerator.ts index 987dd1421ab..6f407f0dac4 100644 --- a/paths/levy/src/LevyPathGenerator.ts +++ b/paths/levy/src/LevyPathGenerator.ts @@ -7,11 +7,19 @@ import type { LevyPathParticle } from "./LevyPathParticle.js"; const defaultScale = 1, defaultLevyAlpha = 1.5; +/** L\u00e9vy flight path generator plugin */ export class LevyPathGenerator implements IMovePathGenerator { + /** Levy path options */ readonly options: ILevyPathOptions; + /** The particles container */ private readonly _container: Container; + /** The result vector */ private readonly _res: Vector; + /** + * LevyPathGenerator constructor + * @param container + */ constructor(container: Container) { this._container = container; this._res = Vector.origin; @@ -23,6 +31,10 @@ export class LevyPathGenerator implements IMovePathGenerator { }; } + /** + * Generates the next movement vector using L\u00e9vy flight + * @param p + */ generate(p: LevyPathParticle): Vector { p.levy ??= { angle: getRandom() * Math.PI * 2, @@ -56,6 +68,7 @@ export class LevyPathGenerator implements IMovePathGenerator { return this._res; } + /** Initializes the path generator options */ init(): void { const source = this._container.actualOptions.particles.move.path.options; @@ -64,10 +77,15 @@ export class LevyPathGenerator implements IMovePathGenerator { this.options.maxStep = (source["maxStep"] as number | undefined) ?? this.options.maxStep; } + /** + * Resets the particle L\u00e9vy state + * @param p + */ reset(p: LevyPathParticle): void { delete p.levy; } + /** Updates the path generator (no-op) */ update(): void { // nothing to do } diff --git a/paths/perlinNoise/src/PerlinNoiseGenerator.ts b/paths/perlinNoise/src/PerlinNoiseGenerator.ts index 85cabd64ad5..ea965b1cfb9 100644 --- a/paths/perlinNoise/src/PerlinNoiseGenerator.ts +++ b/paths/perlinNoise/src/PerlinNoiseGenerator.ts @@ -2,6 +2,7 @@ import type { Container } from "@tsparticles/engine"; import { NoiseFieldGenerator } from "@tsparticles/noise-field"; import { PerlinNoise } from "@tsparticles/perlin-noise"; +/** Perlin noise path generator for particle motion */ export class PerlinNoiseGenerator extends NoiseFieldGenerator { constructor(container: Container) { const perlinNoise = new PerlinNoise(); diff --git a/paths/polygon/src/PolygonPathGenerator.ts b/paths/polygon/src/PolygonPathGenerator.ts index 53aad71b8e7..481e4c2f2fd 100644 --- a/paths/polygon/src/PolygonPathGenerator.ts +++ b/paths/polygon/src/PolygonPathGenerator.ts @@ -11,12 +11,21 @@ const defaultOptions = { angle: 30, }; +/** Polygon path generator plugin */ export class PolygonPathGenerator implements IMovePathGenerator { + /** Direction list for polygon movement */ dirsList: ICoordinates[]; + /** Polygon path options */ readonly options; + /** The particles container */ private readonly _container; + /** The result vector */ private readonly _res: Vector; + /** + * PolygonPathGenerator constructor + * @param container + */ constructor(container: Container) { this._container = container; this._res = Vector.origin; @@ -24,6 +33,10 @@ export class PolygonPathGenerator implements IMovePathGenerator { this.options = deepExtend({}, defaultOptions) as IPolygonPathOptions; } + /** + * Generates the next movement vector along polygon vertices + * @param p + */ generate(p: PolygonPathParticle): Vector { const { sides, turnSteps } = this.options; @@ -48,6 +61,7 @@ export class PolygonPathGenerator implements IMovePathGenerator { return this._res; } + /** Initializes the path generator options */ init(): void { const container = this._container, sourceOptions = container.actualOptions.particles.move.path.options; @@ -61,12 +75,17 @@ export class PolygonPathGenerator implements IMovePathGenerator { this._createDirs(); } + /** + * Resets the particle polygon state + * @param particle + */ reset(particle: PolygonPathParticle): void { delete particle.hexStep; delete particle.hexDirection; delete particle.hexSpeed; } + /** Updates the path generator (no-op) */ update(): void { // do nothing } diff --git a/paths/random/src/RandomPathGenerator.ts b/paths/random/src/RandomPathGenerator.ts index 210ade2537c..a2a86b3da76 100644 --- a/paths/random/src/RandomPathGenerator.ts +++ b/paths/random/src/RandomPathGenerator.ts @@ -4,13 +4,17 @@ import { type IMovePathGenerator } from "@tsparticles/plugin-move"; const minRandom = -1, maxRandom = 1; +/** Random path generator plugin */ export class RandomPathGenerator implements IMovePathGenerator { + /** The result vector */ private readonly _res: Vector; + /** RandomPathGenerator constructor */ constructor() { this._res = Vector.origin; } + /** Generates a random movement vector */ generate(): Vector { this._res.x = getRandomInRange(minRandom, maxRandom); this._res.y = getRandomInRange(minRandom, maxRandom); @@ -18,14 +22,17 @@ export class RandomPathGenerator implements IMovePathGenerator { return this._res; } + /** Initializes the path generator (no-op) */ init(): void { // do nothing } + /** Resets the path generator (no-op) */ reset(): void { // do nothing } + /** Updates the path generator (no-op) */ update(): void { // do nothing } diff --git a/paths/simplexNoise/src/SimplexNoiseGenerator.ts b/paths/simplexNoise/src/SimplexNoiseGenerator.ts index 606814e31bf..605264ef440 100644 --- a/paths/simplexNoise/src/SimplexNoiseGenerator.ts +++ b/paths/simplexNoise/src/SimplexNoiseGenerator.ts @@ -2,6 +2,7 @@ import type { Container } from "@tsparticles/engine"; import { NoiseFieldGenerator } from "@tsparticles/noise-field"; import { SimplexNoise } from "@tsparticles/simplex-noise"; +/** Simplex noise path generator for particle motion */ export class SimplexNoiseGenerator extends NoiseFieldGenerator { constructor(container: Container) { const simplex = new SimplexNoise(); diff --git a/paths/spiral/src/SpiralParticle.ts b/paths/spiral/src/SpiralParticle.ts index 9ad328a2910..056a282d1a7 100644 --- a/paths/spiral/src/SpiralParticle.ts +++ b/paths/spiral/src/SpiralParticle.ts @@ -1,12 +1,21 @@ import type { Particle } from "@tsparticles/engine"; import type { SpiralDirection } from "./SpiralDirection.js"; -interface SpiralData { +/** + * Spiral path data for a particle + */ +export interface SpiralData { + /** Current angle */ angle: number; + /** Angular speed */ angularSpeed: number; + /** Spiral direction */ direction: SpiralDirection; + /** Maximum radius */ maxRadius: number; + /** Radial speed */ radialSpeed: number; + /** Current radius */ radius: number; } diff --git a/paths/spiral/src/SpiralPathGenerator.ts b/paths/spiral/src/SpiralPathGenerator.ts index fd6f22fc0ff..c35571e3131 100644 --- a/paths/spiral/src/SpiralPathGenerator.ts +++ b/paths/spiral/src/SpiralPathGenerator.ts @@ -21,17 +21,30 @@ const minRadius = 0, radialSpeed: { min: 0.1, max: 0.3 }, }; +/** Spiral path generator plugin */ export class SpiralPathGenerator implements IMovePathGenerator { + /** Spiral path options */ readonly options; + /** The particles container */ private readonly _container; + /** The result vector */ private readonly _res: Vector; + /** + * SpiralPathGenerator constructor + * @param container + */ constructor(container: Container) { this._container = container; this._res = Vector.origin; this.options = deepExtend({}, defaultOptions) as ISpiralOptions; } + /** + * Generates the next movement vector with spiral oscillation + * @param particle + * @param delta + */ generate(particle: SpiralParticle, delta: IDelta): Vector { const { options } = this; @@ -74,6 +87,7 @@ export class SpiralPathGenerator implements IMovePathGenerator { return this._res; } + /** Initializes the path generator options */ init(): void { const sourceOptions = this._container.actualOptions.particles.move.path.options; @@ -82,10 +96,15 @@ export class SpiralPathGenerator implements IMovePathGenerator { this.options.radialSpeed = (sourceOptions["radialSpeed"] as RangeValue | undefined) ?? this.options.radialSpeed; } + /** + * Resets the particle spiral state + * @param particle + */ reset(particle: SpiralParticle): void { delete particle.spiral; } + /** Updates the path generator (no-op) */ update(): void { // no-op } diff --git a/paths/svg/src/SVGPathGenerator.ts b/paths/svg/src/SVGPathGenerator.ts index 7e52a7cbdc0..ffaab608f15 100644 --- a/paths/svg/src/SVGPathGenerator.ts +++ b/paths/svg/src/SVGPathGenerator.ts @@ -18,7 +18,8 @@ import type { SVGPathData } from "./types.js"; import { createSVGPaths } from "./createSVGPaths.js"; import { loadSVGFromString } from "./loadSVGFromString.js"; -enum SVGPathDirection { +/** SVG path direction */ +export enum SVGPathDirection { normal, reverse, } @@ -28,15 +29,25 @@ const minStep = 0, minWidth = 0, minScale = 1; -type SVGPathParticle = Particle & { +/** + * SVG path particle extension type + */ +export type SVGPathParticle = Particle & { + /** Direction along the SVG path */ svgDirection?: SVGPathDirection; + /** Initial position when the particle started following the path */ svgInitialPosition?: ICoordinates; + /** Offset from the path */ svgOffset?: IDimension; + /** Current path index */ svgPathIndex?: number; + /** Speed along the path */ svgSpeed?: number; + /** Current step on the path */ svgStep?: number; }; +/** @internal */ interface SVGPathOptions { path?: { data: string[]; @@ -49,16 +60,29 @@ interface SVGPathOptions { width?: number; } +/** SVG path generator plugin */ export class SVGPathGenerator implements IMovePathGenerator { + /** The particles container */ private readonly _container; + /** The position offset */ private readonly _offset: ICoordinatesWithMode; + /** The parsed SVG paths */ private _paths: SVGPathData[]; + /** The result vector */ private readonly _res: Vector; + /** Whether to reverse path direction */ private _reverse: boolean; + /** The scale factor */ private _scale: number; + /** The SVG size */ private readonly _size: IDimension; + /** The path width */ private _width: number; + /** + * SVGPathGenerator constructor + * @param container + */ constructor(container: Container) { this._container = container; this._paths = []; @@ -70,6 +94,11 @@ export class SVGPathGenerator implements IMovePathGenerator { this._res = Vector.origin; } + /** + * Generates the next position along the SVG path + * @param particle + * @param delta + */ generate(particle: SVGPathParticle, delta: IDelta): Vector { const container = this._container, pxRatio = container.retina.pixelRatio; @@ -148,6 +177,7 @@ export class SVGPathGenerator implements IMovePathGenerator { return this._res; } + /** Initializes the SVG path data */ init(): void { const options = this._container.actualOptions.particles.move.path.options as SVGPathOptions, position = options.position ?? this._offset; @@ -180,10 +210,12 @@ export class SVGPathGenerator implements IMovePathGenerator { } } + /** Resets the path generator (no-op) */ reset(): void { // do nothing } + /** Updates the path generator (no-op) */ update(): void { // do nothing } diff --git a/paths/zigzag/src/ZigZagPathGenerator.ts b/paths/zigzag/src/ZigZagPathGenerator.ts index f4b6d1cc7e3..6775a7aabb1 100644 --- a/paths/zigzag/src/ZigZagPathGenerator.ts +++ b/paths/zigzag/src/ZigZagPathGenerator.ts @@ -14,18 +14,33 @@ import { type IMovePathGenerator } from "@tsparticles/plugin-move"; const angularFrequencyFactor = 0.5, halfPI = Math.PI * half; -interface ZigZagParticle extends Particle { +/** + * Zigzag path particle extension type + */ +export interface ZigZagParticle extends Particle { + /** Zigzag data for this particle */ zigzag?: ZigZagData; } -interface ZigZagData { +/** + * Zigzag path data for a particle + */ +export interface ZigZagData { + /** Animation counter */ counter: number; + /** Height of the wave */ waveHeight: number; + /** Length of the wave */ waveLength: number; } -interface IZigZagOptions { +/** + * Zigzag path generator options + */ +export interface IZigZagOptions { + /** Wave height range */ waveHeight: RangeValue; + /** Wave length range */ waveLength: RangeValue; } @@ -34,18 +49,31 @@ const defaultOptions: IZigZagOptions = { waveLength: { min: 0, max: 5 }, }; +/** Zigzag path generator plugin */ export class ZigZagPathGenerator implements IMovePathGenerator { + /** Zigzag path options */ readonly options; + /** The particles container */ private readonly _container; + /** The result vector */ private readonly _res: Vector; + /** + * ZigZagPathGenerator constructor + * @param container + */ constructor(container: Container) { this._container = container; this._res = Vector.origin; this.options = deepExtend({}, defaultOptions) as IZigZagOptions; } + /** + * Generates the next movement vector with zigzag oscillation + * @param particle + * @param delta + */ generate(particle: ZigZagParticle, delta: IDelta): Vector { const { options } = this; @@ -70,6 +98,7 @@ export class ZigZagPathGenerator implements IMovePathGenerator { return this._res; } + /** Initializes the path generator options */ init(): void { const sourceOptions = this._container.actualOptions.particles.move.path.options; @@ -77,10 +106,12 @@ export class ZigZagPathGenerator implements IMovePathGenerator { this.options.waveHeight = (sourceOptions["waveHeight"] as RangeValue | undefined) ?? this.options.waveHeight; } + /** Resets the path generator (no-op) */ reset(): void { // do nothing } + /** Updates the path generator (no-op) */ update(): void { // do nothing } diff --git a/plugins/absorbers/src/AbsorberInstance.ts b/plugins/absorbers/src/AbsorberInstance.ts index 39edc4fe1f9..2b79455e638 100644 --- a/plugins/absorbers/src/AbsorberInstance.ts +++ b/plugins/absorbers/src/AbsorberInstance.ts @@ -47,7 +47,7 @@ const squareExp = 2, /** * Particle extension type for Absorber orbit options */ -type OrbitingParticle = Particle & { +export type OrbitingParticle = Particle & { /** * Vector representing the orbit of the particle around the absorber */ @@ -65,6 +65,8 @@ type OrbitingParticle = Particle & { }; /** + * The AbsorberInstance class manages a single absorber, handling particle attraction, + * orbit, destruction, and lifecycle management */ export class AbsorberInstance { /** diff --git a/plugins/absorbers/src/AbsorbersInteractor.ts b/plugins/absorbers/src/AbsorbersInteractor.ts index d4c1d41bbc4..1ff8fea598e 100644 --- a/plugins/absorbers/src/AbsorbersInteractor.ts +++ b/plugins/absorbers/src/AbsorbersInteractor.ts @@ -21,8 +21,17 @@ import type { AbsorbersInstancesManager } from "./AbsorbersInstancesManager.js"; const absorbersMode = "absorbers"; +/** + * Handles the interaction between particles and absorbers, including click-to-add and dragging + */ export class AbsorbersInteractor extends ExternalInteractorBase { + /** + * Handles the click mode for adding absorbers + */ handleClickMode: (mode: string, interactivityData: IInteractivityData) => void; + /** + * The maximum distance for the interactor + */ readonly maxDistance; private _dragging = false; @@ -64,14 +73,25 @@ export class AbsorbersInteractor extends ExternalInteractorBase this.isEnabled(interactivityData, p))) { for (const absorber of this._instancesManager.getArray(this.container)) { @@ -105,6 +125,12 @@ export class AbsorbersInteractor extends ExternalInteractorBase[] @@ -147,6 +178,9 @@ export class AbsorbersInteractor extends ExternalInteractorBase { + /** + * The absorber color + */ color; + /** + * Enables particle destruction, if disabled the particle will randomly respawn + */ destroy; + /** + * Enables dragging on absorbers + */ draggable; + /** + * The absorber life options + */ life; + /** + * The absorber name + */ name?: string; + /** + * The absorber opacity + */ opacity; + /** + * Enables particles orbiting while being attracted by the absorber + */ orbits; + /** + * The absorber position, percent values calculated on canvas size + */ position?: RecursivePartial; + /** + * The absorber size options + */ size; constructor() { @@ -35,6 +62,10 @@ export class Absorber implements IAbsorber, IOptionLoader { this.size = new AbsorberSize(); } + /** + * Loads the absorber options from the given data + * @param data - the data to load from + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/plugins/absorbers/src/Options/Classes/AbsorberSize.ts b/plugins/absorbers/src/Options/Classes/AbsorberSize.ts index 39e008c729c..0b640e773a5 100644 --- a/plugins/absorbers/src/Options/Classes/AbsorberSize.ts +++ b/plugins/absorbers/src/Options/Classes/AbsorberSize.ts @@ -2,8 +2,17 @@ import { type IOptionLoader, type RecursivePartial, ValueWithRandom, isNull, isN import { AbsorberSizeLimit } from "./AbsorberSizeLimit.js"; import type { IAbsorberSize } from "../Interfaces/IAbsorberSize.js"; +/** + * The absorber size options + */ export class AbsorberSize extends ValueWithRandom implements IAbsorberSize, IOptionLoader { + /** + * The absorber size density, affects the attraction force + */ density; + /** + * The absorber size limit + */ limit: AbsorberSizeLimit; constructor() { @@ -13,6 +22,10 @@ export class AbsorberSize extends ValueWithRandom implements IAbsorberSize, IOpt this.limit = new AbsorberSizeLimit(); } + /** + * Loads the absorber size options from the given data + * @param data - the data to load from + */ override load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/plugins/absorbers/src/Options/Interfaces/IAbsorberSize.ts b/plugins/absorbers/src/Options/Interfaces/IAbsorberSize.ts index 6abbfca1281..c9d582ae222 100644 --- a/plugins/absorbers/src/Options/Interfaces/IAbsorberSize.ts +++ b/plugins/absorbers/src/Options/Interfaces/IAbsorberSize.ts @@ -1,7 +1,10 @@ import type { IAbsorberSizeLimit } from "./IAbsorberSizeLimit.js"; import type { IValueWithRandom } from "@tsparticles/engine"; +/** The absorber size options */ export interface IAbsorberSize extends IValueWithRandom { + /** The absorber size density */ density: number; + /** The absorber size limit */ limit?: number | IAbsorberSizeLimit; } diff --git a/plugins/absorbers/src/Options/Interfaces/IAbsorberSizeLimit.ts b/plugins/absorbers/src/Options/Interfaces/IAbsorberSizeLimit.ts index 2114ae23082..afc0879fc51 100644 --- a/plugins/absorbers/src/Options/Interfaces/IAbsorberSizeLimit.ts +++ b/plugins/absorbers/src/Options/Interfaces/IAbsorberSizeLimit.ts @@ -1,4 +1,7 @@ +/** The absorber size limit options */ export interface IAbsorberSizeLimit { + /** The absorber size limit mass */ mass: number; + /** The absorber size limit radius */ radius: number; } diff --git a/plugins/absorbers/src/types.ts b/plugins/absorbers/src/types.ts index cd40e27310d..f9baab035bb 100644 --- a/plugins/absorbers/src/types.ts +++ b/plugins/absorbers/src/types.ts @@ -3,23 +3,33 @@ import type { Absorber } from "./Options/Classes/Absorber.js"; import type { IAbsorber } from "./Options/Interfaces/IAbsorber.js"; import type { SingleOrMultiple } from "@tsparticles/engine"; +/** Absorber mode options */ export interface AbsorberModeOptions { + /** The absorbers array */ absorbers?: Absorber[]; } +/** Absorber mode options interface */ export interface IAbsorberModeOptions { + /** The absorbers, single or multiple */ absorbers?: SingleOrMultiple; } +/** Absorber options */ export type AbsorberOptions = InteractivityOptions & { + /** The absorbers */ absorbers: SingleOrMultiple; + /** Interactivity modes */ interactivity: { modes: AbsorberModeOptions; }; }; +/** Absorber options interface */ export type IAbsorberOptions = IInteractivityOptions & { + /** The absorbers */ absorbers: SingleOrMultiple; + /** Interactivity modes */ interactivity: { modes: IAbsorberModeOptions; }; diff --git a/plugins/backgroundMask/src/Options/Classes/BackgroundMask.ts b/plugins/backgroundMask/src/Options/Classes/BackgroundMask.ts index 9bf921d14fc..5af66f9ed1d 100644 --- a/plugins/backgroundMask/src/Options/Classes/BackgroundMask.ts +++ b/plugins/backgroundMask/src/Options/Classes/BackgroundMask.ts @@ -29,6 +29,10 @@ export class BackgroundMask implements IBackgroundMask, IOptionLoader): void { if (isNull(data)) { return; diff --git a/plugins/backgroundMask/src/Options/Classes/BackgroundMaskCover.ts b/plugins/backgroundMask/src/Options/Classes/BackgroundMaskCover.ts index c83501d1929..e6ffe0b6562 100644 --- a/plugins/backgroundMask/src/Options/Classes/BackgroundMaskCover.ts +++ b/plugins/backgroundMask/src/Options/Classes/BackgroundMaskCover.ts @@ -2,16 +2,30 @@ import { type IOptionLoader, OptionsColor, type RecursivePartial, isNull } from import type { IBackgroundMaskCover } from "../Interfaces/IBackgroundMaskCover.js"; /** + * The background mask cover options */ export class BackgroundMaskCover implements IBackgroundMaskCover, IOptionLoader { + /** + * The background color hiding all elements behind + */ color?: OptionsColor; + /** + * The background image hiding all elements behind + */ image?: string; + /** + * The opacity of the background + */ opacity; constructor() { this.opacity = 1; } + /** + * Loads the background mask cover options from the given data + * @param data - the data to load from + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/plugins/blend/src/types.ts b/plugins/blend/src/types.ts index 0d19d92b2d0..f098765b203 100644 --- a/plugins/blend/src/types.ts +++ b/plugins/blend/src/types.ts @@ -2,31 +2,46 @@ import type { Container, IOptions, IParticlesOptions, Options, Particle, Particl import type { Blend } from "./Options/Classes/Blend.js"; import type { IBlend } from "./Options/Interfaces/IBlend.js"; +/** Blend particles options interface */ export type IBlendParticlesOptions = IParticlesOptions & { + /** The blend options */ blend?: IBlend; }; +/** Blend particles options */ export type BlendParticlesOptions = ParticlesOptions & { + /** The blend options */ blend?: Blend; }; +/** Blend options interface */ export type IBlendOptions = IOptions & { + /** The blend options */ blend?: IBlend; + /** The particles options */ particles: IBlendParticlesOptions; }; +/** Blend options */ export type BlendOptions = Options & { + /** The blend options */ blend?: Blend; + /** The particles options */ particles: BlendParticlesOptions; }; +/** Blend container type */ export type BlendContainer = Container & { + /** The blend options */ actualOptions: BlendOptions; }; +/** Blend particle type */ export type BlendParticle = Particle & { + /** The particle's blend options */ options: BlendParticlesOptions; + /** The original blend mode before applying the blend effect */ originalBlendMode?: GlobalCompositeOperation; }; diff --git a/plugins/canvasMask/src/CanvasMaskPluginInstance.ts b/plugins/canvasMask/src/CanvasMaskPluginInstance.ts index 753ca999818..c05e7da101c 100644 --- a/plugins/canvasMask/src/CanvasMaskPluginInstance.ts +++ b/plugins/canvasMask/src/CanvasMaskPluginInstance.ts @@ -3,13 +3,24 @@ import { type IContainerPlugin, isNull, safeDocument } from "@tsparticles/engine import type { CanvasMaskContainer } from "./types.js"; import { addParticlesFromCanvasPixels } from "./utils.js"; +/** + * The CanvasMaskPluginInstance class handles the initialization of the canvas mask, + * converting image, text, or canvas element data into particles + */ export class CanvasMaskPluginInstance implements IContainerPlugin { + /** The canvas mask container */ private readonly _container; + /** + * @param container - the container using the canvas mask + */ constructor(container: CanvasMaskContainer) { this._container = container; } + /** + * Initializes the canvas mask, loading pixel data from the configured source + */ async init(): Promise { const container = this._container, options = container.actualOptions.canvasMask; diff --git a/plugins/canvasMask/src/Options/Classes/CanvasMask.ts b/plugins/canvasMask/src/Options/Classes/CanvasMask.ts index 4e37fbc3157..2fd383717b1 100644 --- a/plugins/canvasMask/src/Options/Classes/CanvasMask.ts +++ b/plugins/canvasMask/src/Options/Classes/CanvasMask.ts @@ -9,14 +9,41 @@ import { TextMask } from "./TextMask.js"; * [[include:Options/Plugins/CanvasMask.md]] */ export class CanvasMask implements ICanvasMask, IOptionLoader { + /** + * The canvas element to use as the mask source + */ element?: HTMLCanvasElement; + /** + * Enables the canvas mask + */ enable; + /** + * The image mask options + */ image?: ImageMask; + /** + * The canvas mask override options + */ override; + /** + * The canvas mask pixels options + */ pixels; + /** + * The canvas mask position, in percent values + */ position: ICoordinates; + /** + * The scale factor for the mask + */ scale; + /** + * The CSS selector for the canvas element + */ selector?: string; + /** + * The text mask options + */ text?: TextMask; constructor() { @@ -30,6 +57,10 @@ export class CanvasMask implements ICanvasMask, IOptionLoader { this.scale = 1; } + /** + * Loads the canvas mask options from the given data + * @param data - the data to load from + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/plugins/canvasMask/src/Options/Classes/CanvasMaskOverride.ts b/plugins/canvasMask/src/Options/Classes/CanvasMaskOverride.ts index 781a07e094c..1cf87a9170f 100644 --- a/plugins/canvasMask/src/Options/Classes/CanvasMaskOverride.ts +++ b/plugins/canvasMask/src/Options/Classes/CanvasMaskOverride.ts @@ -1,8 +1,17 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { ICanvasMaskOverride } from "../Interfaces/ICanvasMaskOverride.js"; +/** + * The canvas mask override options + */ export class CanvasMaskOverride implements ICanvasMaskOverride, IOptionLoader { + /** + * Override the particle color with the canvas pixel color + */ color: boolean; + /** + * Override the particle opacity with the canvas pixel opacity + */ opacity: boolean; constructor() { @@ -10,6 +19,10 @@ export class CanvasMaskOverride implements ICanvasMaskOverride, IOptionLoader): void { if (isNull(data)) { return; diff --git a/plugins/canvasMask/src/Options/Interfaces/ICanvasMask.ts b/plugins/canvasMask/src/Options/Interfaces/ICanvasMask.ts index 2b7834a58e8..823da4158cc 100644 --- a/plugins/canvasMask/src/Options/Interfaces/ICanvasMask.ts +++ b/plugins/canvasMask/src/Options/Interfaces/ICanvasMask.ts @@ -4,16 +4,24 @@ import type { ICoordinates } from "@tsparticles/engine"; import type { IImageMask } from "./IImageMask.js"; import type { ITextMask } from "./ITextMask.js"; -/** - */ +/** The canvas mask options */ export interface ICanvasMask { + /** The canvas mask element */ element?: HTMLCanvasElement; + /** Enables the canvas mask */ enable: boolean; + /** The canvas mask image options */ image?: IImageMask; + /** The canvas mask override options */ override: ICanvasMaskOverride; + /** The canvas mask pixels options */ pixels: ICanvasMaskPixels; + /** The canvas mask position */ position: ICoordinates; + /** The canvas mask scale */ scale: number; + /** The canvas mask element selector */ selector?: string; + /** The canvas mask text options */ text?: ITextMask; } diff --git a/plugins/canvasMask/src/Options/Interfaces/ICanvasMaskOverride.ts b/plugins/canvasMask/src/Options/Interfaces/ICanvasMaskOverride.ts index b69413b96ad..fd7f0777549 100644 --- a/plugins/canvasMask/src/Options/Interfaces/ICanvasMaskOverride.ts +++ b/plugins/canvasMask/src/Options/Interfaces/ICanvasMaskOverride.ts @@ -1,6 +1,7 @@ -/** - */ +/** The canvas mask override options */ export interface ICanvasMaskOverride { + /** Override the color */ color: boolean; + /** Override the opacity */ opacity: boolean; } diff --git a/plugins/canvasMask/src/Options/Interfaces/ICanvasMaskPixels.ts b/plugins/canvasMask/src/Options/Interfaces/ICanvasMaskPixels.ts index 651e4e5b632..1031854bffc 100644 --- a/plugins/canvasMask/src/Options/Interfaces/ICanvasMaskPixels.ts +++ b/plugins/canvasMask/src/Options/Interfaces/ICanvasMaskPixels.ts @@ -1,8 +1,9 @@ import type { IRgba } from "@tsparticles/engine"; -/** - */ +/** The canvas mask pixels options */ export interface ICanvasMaskPixels { + /** The pixels filter function or pattern */ filter: string | ((pixel: IRgba) => boolean); + /** The pixels offset */ offset: number; } diff --git a/plugins/canvasMask/src/Options/Interfaces/IFontTextMask.ts b/plugins/canvasMask/src/Options/Interfaces/IFontTextMask.ts index c2dcaf94a7a..aafe22f22d9 100644 --- a/plugins/canvasMask/src/Options/Interfaces/IFontTextMask.ts +++ b/plugins/canvasMask/src/Options/Interfaces/IFontTextMask.ts @@ -1,3 +1,4 @@ import type { ITextDataFontOptions } from "@tsparticles/canvas-utils"; +/** The canvas mask font options */ export type IFontTextMask = ITextDataFontOptions; diff --git a/plugins/canvasMask/src/Options/Interfaces/IImageMask.ts b/plugins/canvasMask/src/Options/Interfaces/IImageMask.ts index 62206eaf727..70e93eecffa 100644 --- a/plugins/canvasMask/src/Options/Interfaces/IImageMask.ts +++ b/plugins/canvasMask/src/Options/Interfaces/IImageMask.ts @@ -1,5 +1,5 @@ -/** - */ +/** The canvas mask image options */ export interface IImageMask { + /** The image source */ src: string; } diff --git a/plugins/canvasMask/src/Options/Interfaces/ITextMask.ts b/plugins/canvasMask/src/Options/Interfaces/ITextMask.ts index 1ee04cff444..fc81cbc196a 100644 --- a/plugins/canvasMask/src/Options/Interfaces/ITextMask.ts +++ b/plugins/canvasMask/src/Options/Interfaces/ITextMask.ts @@ -2,8 +2,12 @@ import type { IFontTextMask } from "./IFontTextMask.js"; import type { ITextDataOptions } from "@tsparticles/canvas-utils"; import type { ITextMaskLine } from "./ITextMaskLine.js"; +/** The canvas mask text options */ export interface ITextMask extends ITextDataOptions { + /** Enables the text fill */ fill: boolean; + /** The text font options */ font: IFontTextMask; + /** The text lines options */ lines: ITextMaskLine; } diff --git a/plugins/canvasMask/src/Options/Interfaces/ITextMaskLine.ts b/plugins/canvasMask/src/Options/Interfaces/ITextMaskLine.ts index 921531f0458..22f296b3eb1 100644 --- a/plugins/canvasMask/src/Options/Interfaces/ITextMaskLine.ts +++ b/plugins/canvasMask/src/Options/Interfaces/ITextMaskLine.ts @@ -1,3 +1,4 @@ import type { ITextDataLinesOptions } from "@tsparticles/canvas-utils"; +/** The canvas mask text line options */ export type ITextMaskLine = ITextDataLinesOptions; diff --git a/plugins/canvasMask/src/types.ts b/plugins/canvasMask/src/types.ts index cd042720316..31f03c06152 100644 --- a/plugins/canvasMask/src/types.ts +++ b/plugins/canvasMask/src/types.ts @@ -2,14 +2,20 @@ import type { Container, IOptions, Options } from "@tsparticles/engine"; import type { CanvasMask } from "./Options/Classes/CanvasMask.js"; import type { ICanvasMask } from "./Options/Interfaces/ICanvasMask.js"; +/** Canvas mask options interface */ export type ICanvasMaskOptions = IOptions & { + /** The canvas mask options */ canvasMask?: ICanvasMask; }; +/** Canvas mask options */ export type CanvasMaskOptions = Options & { + /** The canvas mask options */ canvasMask?: CanvasMask; }; +/** Canvas mask container type */ export type CanvasMaskContainer = Container & { + /** The canvas mask options */ actualOptions: CanvasMaskOptions; }; diff --git a/plugins/colors/hex/src/HexColorManager.ts b/plugins/colors/hex/src/HexColorManager.ts index 85f5459dde8..6631e8294a3 100644 --- a/plugins/colors/hex/src/HexColorManager.ts +++ b/plugins/colors/hex/src/HexColorManager.ts @@ -4,10 +4,15 @@ import type { IColor, IColorManager, IRangeColor, IRgb, IRgba } from "@tsparticl * Indexes for accessing color components from regex capture groups. * Uses 1-based indexing as index 0 contains the full match. */ +/** Indexes for RGB regex capture groups */ enum RgbIndexes { + /** Red component index */ r = 1, + /** Green component index */ g = 2, + /** Blue component index */ b = 3, + /** Alpha component index */ a = 4, } @@ -21,19 +26,36 @@ const shorthandHexRegex = /^#?([a-f\d])([a-f\d])([a-f\d])([a-f\d])?$/i, * Manages hexadecimal color string parsing and conversion to RGB/RGBA format. * Implements the IColorManager interface for handling hex color values. */ +/** Hexadecimal color manager */ export class HexColorManager implements IColorManager { + /** + * Checks if the input starts with # + * @param input + */ accepts(input: string): boolean { return input.startsWith("#"); } + /** + * Converts an IColor to RGB + * @param color + */ handleColor(color: IColor): IRgb | undefined { return this._parseString(color.value); } + /** + * Converts an IRangeColor to RGB + * @param color + */ handleRangeColor(color: IRangeColor): IRgb | undefined { return this._parseString(color.value); } + /** + * Parses a hex color string to RGBA + * @param input + */ parseString(input: string): IRgba | undefined { return this._parseString(input); } diff --git a/plugins/colors/hsl/src/HslColorManager.ts b/plugins/colors/hsl/src/HslColorManager.ts index 1ea42ad8108..7ba00f336cb 100644 --- a/plugins/colors/hsl/src/HslColorManager.ts +++ b/plugins/colors/hsl/src/HslColorManager.ts @@ -14,22 +14,34 @@ import { parseAlpha, } from "@tsparticles/engine"; +/** Indexes for HSL regex capture groups */ enum HslIndexes { + /** Hue component index */ h = 1, + /** Saturation component index */ s = 2, + /** Lightness component index */ l = 3, + /** Alpha component index */ a = 5, } const hslRegex = /hsla?\(\s*(\d+)\s*[\s,]\s*(\d+)%\s*[\s,]\s*(\d+)%\s*([\s,]\s*(0|1|0?\.\d+|(\d{1,3})%)\s*)?\)/i; -/** - */ +/** HSL color manager */ export class HslColorManager implements IColorManager { + /** + * Checks if the input starts with hsl + * @param input + */ accepts(input: string): boolean { return input.startsWith("hsl"); } + /** + * Converts an IColor to RGB + * @param color + */ handleColor(color: IColor): IRgb | undefined { const colorValue = color.value as IValueColor, hslColor = colorValue.hsl ?? (color.value as IHsl); @@ -41,6 +53,10 @@ export class HslColorManager implements IColorManager { return hslToRgb(hslColor); } + /** + * Converts an IRangeColor to RGB + * @param color + */ handleRangeColor(color: IRangeColor): IRgb | undefined { const colorValue = color.value as IRangeValueColor, hslColor = colorValue.hsl ?? (color.value as IRangeHsl); @@ -56,6 +72,10 @@ export class HslColorManager implements IColorManager { }); } + /** + * Parses an HSL color string to RGBA + * @param input + */ parseString(input: string): IRgba | undefined { if (!this.accepts(input)) { return; diff --git a/plugins/colors/hsv/src/HsvColorManager.ts b/plugins/colors/hsv/src/HsvColorManager.ts index 06db1682624..656cee6f355 100644 --- a/plugins/colors/hsv/src/HsvColorManager.ts +++ b/plugins/colors/hsv/src/HsvColorManager.ts @@ -15,11 +15,20 @@ import { hsvToRgb, hsvaToRgba } from "./utils.js"; const hsvRegex = /hsva?\(\s*(\d+)°\s*[\s,]\s*(\d+)%\s*[\s,]\s*(\d+)%\s*([\s,]\s*(0|1|0?\.\d+|(\d{1,3})%)\s*)?\)/i; +/** HSV color manager */ export class HsvColorManager implements IColorManager { + /** + * Checks if the input starts with hsv + * @param input + */ accepts(input: string): boolean { return input.startsWith("hsv"); } + /** + * Converts an IColor to RGB + * @param color + */ handleColor(color: IColor): IRgb | undefined { const colorValue = color.value as IValueColor, hsvColor = colorValue.hsv ?? (color.value as IHsv); @@ -31,6 +40,10 @@ export class HsvColorManager implements IColorManager { return hsvToRgb(hsvColor); } + /** + * Converts an IRangeColor to RGB + * @param color + */ handleRangeColor(color: IRangeColor): IRgb | undefined { const colorValue = color.value as IRangeValueColor, hsvColor = colorValue.hsv ?? (color.value as IRangeHsv); @@ -46,6 +59,10 @@ export class HsvColorManager implements IColorManager { }); } + /** + * Parses an HSV color string to RGBA + * @param input + */ parseString(input: string): IRgba | undefined { if (!this.accepts(input)) { return; diff --git a/plugins/colors/hwb/src/HwbColorManager.ts b/plugins/colors/hwb/src/HwbColorManager.ts index 160e9594e46..f8b1744dd43 100644 --- a/plugins/colors/hwb/src/HwbColorManager.ts +++ b/plugins/colors/hwb/src/HwbColorManager.ts @@ -11,10 +11,15 @@ import { parseAlpha, } from "@tsparticles/engine"; +/** Indexes for HWB regex capture groups */ enum HwbIndexes { + /** Hue component index */ h = 1, + /** Whiteness component index */ w = 2, + /** Blackness component index */ b = 3, + /** Alpha component index */ a = 5, } @@ -88,11 +93,20 @@ function hwbaToRgba(hwba: IHwba): IRgba { }; } +/** HWB color manager */ export class HwbColorManager implements IColorManager { + /** + * Checks if the input starts with hwb + * @param input + */ accepts(input: string): boolean { return input.startsWith("hwb"); } + /** + * Converts an IColor to RGB + * @param color + */ handleColor(color: IColor): IRgb | undefined { const colorValue = color.value as IValueColor, hwbColor = colorValue.hwb ?? (color.value as unknown as IHwb); @@ -104,6 +118,10 @@ export class HwbColorManager implements IColorManager { return hwbToRgb(hwbColor); } + /** + * Converts an IRangeColor to RGB + * @param color + */ handleRangeColor(color: IRangeColor): IRgb | undefined { const colorValue = color.value as IValueColor, hwbColor = colorValue.hwb ?? (color.value as unknown as IHwb); @@ -119,6 +137,10 @@ export class HwbColorManager implements IColorManager { }); } + /** + * Parses an HWB color string to RGBA + * @param input + */ parseString(input: string): IRgba | undefined { if (!this.accepts(input)) { return; diff --git a/plugins/colors/lab/src/LabColorManager.ts b/plugins/colors/lab/src/LabColorManager.ts index 8ea8c64be5e..53ca01cb31d 100644 --- a/plugins/colors/lab/src/LabColorManager.ts +++ b/plugins/colors/lab/src/LabColorManager.ts @@ -15,11 +15,20 @@ import { labToRgb, labaToRgba } from "./utils.js"; const labRegex = /lab\(\s*(\d+(\.\d+)?)%\s+(\d+(\.\d+)?)\s+(\d+(\.\d+)?)(?:\s*\/\s*(0|1|0?\.\d+|\d{1,3}%))?\s*\)/i; +/** LAB color manager */ export class LabColorManager implements IColorManager { + /** + * Checks if the input starts with lab + * @param input + */ accepts(input: string): boolean { return input.startsWith("lab"); } + /** + * Converts an IColor to RGB + * @param color + */ handleColor(color: IColor): IRgb | undefined { const colorValue = color.value as IValueColor, labColor = colorValue.lab ?? (color.value as ILab); @@ -31,6 +40,10 @@ export class LabColorManager implements IColorManager { return labToRgb(labColor); // Handle LAB conversion } + /** + * Converts an IRangeColor to RGB + * @param color + */ handleRangeColor(color: IRangeColor): IRgb | undefined { const colorValue = color.value as IRangeValueColor, labColor = colorValue.lab ?? (color.value as IRangeLab); // Support for LAB @@ -46,6 +59,10 @@ export class LabColorManager implements IColorManager { }); } + /** + * Parses a LAB color string to RGBA + * @param input + */ parseString(input: string): IRgba | undefined { if (!this.accepts(input)) { return; diff --git a/plugins/colors/lch/src/LchColorManager.ts b/plugins/colors/lch/src/LchColorManager.ts index d6e0267af5f..2262196eb90 100644 --- a/plugins/colors/lch/src/LchColorManager.ts +++ b/plugins/colors/lch/src/LchColorManager.ts @@ -15,11 +15,20 @@ import { lchToRgb, lchaToRgba } from "./utils.js"; const lchRegex = /lch\(\s*(\d+(\.\d+)?)%\s+(\d+(\.\d+)?)\s+(\d+(\.\d+)?)(?:\s*\/\s*(0|1|0?\.\d+|\d{1,3}%))?\s*\)/i; +/** LCH color manager */ export class LchColorManager implements IColorManager { + /** + * Checks if the input starts with lch + * @param input + */ accepts(input: string): boolean { return input.startsWith("lch"); } + /** + * Converts an IColor to RGB + * @param color + */ handleColor(color: IColor): IRgb | undefined { const colorValue = color.value as IValueColor, lchColor = colorValue.lch ?? (color.value as ILch); @@ -31,6 +40,10 @@ export class LchColorManager implements IColorManager { return lchToRgb(lchColor); // Handle LCH conversion } + /** + * Converts an IRangeColor to RGB + * @param color + */ handleRangeColor(color: IRangeColor): IRgb | undefined { const colorValue = color.value as IRangeValueColor, lchColor = colorValue.lch ?? (color.value as IRangeLch); // Support for LCH @@ -46,6 +59,10 @@ export class LchColorManager implements IColorManager { }); } + /** + * Parses an LCH color string to RGBA + * @param input + */ parseString(input: string): IRgba | undefined { if (!this.accepts(input)) { return; diff --git a/plugins/colors/named/src/NamedColorManager.ts b/plugins/colors/named/src/NamedColorManager.ts index 7b5cc71e19c..f6965c2e314 100644 --- a/plugins/colors/named/src/NamedColorManager.ts +++ b/plugins/colors/named/src/NamedColorManager.ts @@ -158,19 +158,36 @@ const namedColors = new Map([ ["yellowgreen", { r: 154, g: 205, b: 50 }], ]); +/** Named CSS color manager */ export class NamedColorManager implements IColorManager { + /** + * Checks if the input is a named CSS color + * @param input + */ accepts(input: string): boolean { return namedColors.has(input.toLowerCase()); } + /** + * Converts an IColor to RGB + * @param color + */ handleColor(color: IColor): IRgb | undefined { return this._parseString(color.value); } + /** + * Converts an IRangeColor to RGB + * @param color + */ handleRangeColor(color: IRangeColor): IRgb | undefined { return this._parseString(color.value); } + /** + * Parses a named color string to RGBA + * @param input + */ parseString(input: string): IRgba | undefined { return this._parseString(input); } diff --git a/plugins/colors/oklab/src/OklabColorManager.ts b/plugins/colors/oklab/src/OklabColorManager.ts index 329791fca28..29be1ff54ec 100644 --- a/plugins/colors/oklab/src/OklabColorManager.ts +++ b/plugins/colors/oklab/src/OklabColorManager.ts @@ -16,11 +16,20 @@ import { oklabToRgb, oklabaToRgba } from "./utils.js"; const oklabRegex = /oklab\(\s*(\d+(\.\d+)?)%\s+(-?\d+(\.\d+)?)\s+(-?\d+(\.\d+)?)(?:\s*\/\s*(0|1|0?\.\d+|\d{1,3}%))?\s*\)/i; +/** OKLAB color manager */ export class OklabColorManager implements IColorManager { + /** + * Checks if the input starts with oklab + * @param input + */ accepts(input: string): boolean { return input.startsWith("oklab"); } + /** + * Converts an IColor to RGB + * @param color + */ handleColor(color: IColor): IRgb | undefined { const colorValue = color.value as IValueColor, oklabColor = colorValue.oklab ?? (color.value as IOklab); @@ -32,6 +41,10 @@ export class OklabColorManager implements IColorManager { return oklabToRgb(oklabColor); } + /** + * Converts an IRangeColor to RGB + * @param color + */ handleRangeColor(color: IRangeColor): IRgb | undefined { const colorValue = color.value as IRangeValueColor, oklabColor = colorValue.oklab ?? (color.value as IRangeOklab); @@ -47,6 +60,10 @@ export class OklabColorManager implements IColorManager { }); } + /** + * Parses an OKLAB color string to RGBA + * @param input + */ parseString(input: string): IRgba | undefined { if (!this.accepts(input)) { return; diff --git a/plugins/colors/oklch/src/OklchColorManager.ts b/plugins/colors/oklch/src/OklchColorManager.ts index 354804e150c..1c01e45dd54 100644 --- a/plugins/colors/oklch/src/OklchColorManager.ts +++ b/plugins/colors/oklch/src/OklchColorManager.ts @@ -16,11 +16,20 @@ import { oklchToRgb, oklchaToRgba } from "./utils.js"; const oklchRegex = /oklch\(\s*(\d+(\.\d+)?)%\s+(\d+(\.\d+)?)\s+(\d+(\.\d+)?)(°)?(?:\s*\/\s*(0|1|0?\.\d+|\d{1,3}%))?\s*\)/i; +/** OKLCH color manager */ export class OklchColorManager implements IColorManager { + /** + * Checks if the input starts with oklch + * @param input + */ accepts(input: string): boolean { return input.startsWith("oklch"); } + /** + * Converts an IColor to RGB + * @param color + */ handleColor(color: IColor): IRgb | undefined { const colorValue = color.value as IValueColor, oklchColor = colorValue.oklch ?? (color.value as IOklch); @@ -32,6 +41,10 @@ export class OklchColorManager implements IColorManager { return oklchToRgb(oklchColor); } + /** + * Converts an IRangeColor to RGB + * @param color + */ handleRangeColor(color: IRangeColor): IRgb | undefined { const colorValue = color.value as IRangeValueColor, oklchColor = colorValue.oklch ?? (color.value as IRangeOklch); @@ -47,6 +60,10 @@ export class OklchColorManager implements IColorManager { }); } + /** + * Parses an OKLCH color string to RGBA + * @param input + */ parseString(input: string): IRgba | undefined { if (!this.accepts(input)) { return; diff --git a/plugins/colors/rgb/src/RgbColorManager.ts b/plugins/colors/rgb/src/RgbColorManager.ts index d6547065f53..34579fb877d 100644 --- a/plugins/colors/rgb/src/RgbColorManager.ts +++ b/plugins/colors/rgb/src/RgbColorManager.ts @@ -10,23 +10,35 @@ import { parseAlpha, } from "@tsparticles/engine"; +/** Indexes for RGB regex capture groups */ enum RgbIndexes { + /** Red component index */ r = 1, + /** Green component index */ g = 2, + /** Blue component index */ b = 3, + /** Alpha component index */ a = 5, } const rgbRegex = /rgba?\(\s*(\d{1,3})\s*[\s,]\s*(\d{1,3})\s*[\s,]\s*(\d{1,3})\s*([\s,]\s*(0|1|0?\.\d+|(\d{1,3})%)\s*)?\)/i; -/** - */ +/** RGB color manager */ export class RgbColorManager implements IColorManager { + /** + * Checks if the input starts with rgb + * @param input + */ accepts(input: string): boolean { return input.startsWith("rgb"); } + /** + * Converts an IColor to RGB + * @param color + */ handleColor(color: IColor): IRgb | undefined { const colorValue = color.value as IValueColor, rgbColor = colorValue.rgb ?? (color.value as IRgb); @@ -38,6 +50,10 @@ export class RgbColorManager implements IColorManager { return rgbColor; } + /** + * Converts an IRangeColor to RGB + * @param color + */ handleRangeColor(color: IRangeColor): IRgb | undefined { const colorValue = color.value as IValueColor, rgbColor = colorValue.rgb ?? (color.value as IRangeRgb); @@ -53,6 +69,10 @@ export class RgbColorManager implements IColorManager { }; } + /** + * Parses an RGB color string to RGBA + * @param input + */ parseString(input: string): IRgba | undefined { if (!this.accepts(input)) { return; diff --git a/plugins/easings/back/src/index.ts b/plugins/easings/back/src/index.ts index 9a0c914fb32..e0d00da5187 100644 --- a/plugins/easings/back/src/index.ts +++ b/plugins/easings/back/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing back plugin for tsParticles + * @param engine */ export async function loadEasingBackPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/easings/bounce/src/index.ts b/plugins/easings/bounce/src/index.ts index a617cf70ef0..6edd903d096 100644 --- a/plugins/easings/bounce/src/index.ts +++ b/plugins/easings/bounce/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing bounce plugin for tsParticles + * @param engine */ export async function loadEasingBouncePlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/easings/circ/src/index.ts b/plugins/easings/circ/src/index.ts index 457ff2dd35d..b556dd120ad 100644 --- a/plugins/easings/circ/src/index.ts +++ b/plugins/easings/circ/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing circ plugin for tsParticles + * @param engine */ export async function loadEasingCircPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/easings/cubic/src/index.ts b/plugins/easings/cubic/src/index.ts index a7ab60b2ca3..37b376fa95e 100644 --- a/plugins/easings/cubic/src/index.ts +++ b/plugins/easings/cubic/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing cubic plugin for tsParticles + * @param engine */ export async function loadEasingCubicPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/easings/elastic/src/index.ts b/plugins/easings/elastic/src/index.ts index 3399c2960c8..4082feda3f7 100644 --- a/plugins/easings/elastic/src/index.ts +++ b/plugins/easings/elastic/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing elastic plugin for tsParticles + * @param engine */ export async function loadEasingElasticPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/easings/expo/src/index.ts b/plugins/easings/expo/src/index.ts index cee59db49f6..a42a95115ce 100644 --- a/plugins/easings/expo/src/index.ts +++ b/plugins/easings/expo/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing expo plugin for tsParticles + * @param engine */ export async function loadEasingExpoPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/easings/gaussian/src/index.ts b/plugins/easings/gaussian/src/index.ts index fea44e30466..b80c26ab437 100644 --- a/plugins/easings/gaussian/src/index.ts +++ b/plugins/easings/gaussian/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing gaussian plugin for tsParticles + * @param engine */ export async function loadEasingGaussianPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/easings/linear/src/index.ts b/plugins/easings/linear/src/index.ts index d19340aa154..75e9ce1664e 100644 --- a/plugins/easings/linear/src/index.ts +++ b/plugins/easings/linear/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing linear plugin for tsParticles + * @param engine */ export async function loadEasingLinearPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/easings/quad/src/index.ts b/plugins/easings/quad/src/index.ts index 652e127d534..99b86f8d276 100644 --- a/plugins/easings/quad/src/index.ts +++ b/plugins/easings/quad/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing quad plugin for tsParticles + * @param engine */ export async function loadEasingQuadPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/easings/quart/src/index.ts b/plugins/easings/quart/src/index.ts index cec4127e692..fa47bf0a89d 100644 --- a/plugins/easings/quart/src/index.ts +++ b/plugins/easings/quart/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing quart plugin for tsParticles + * @param engine */ export async function loadEasingQuartPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/easings/quint/src/index.ts b/plugins/easings/quint/src/index.ts index d63867a6133..e5375d89595 100644 --- a/plugins/easings/quint/src/index.ts +++ b/plugins/easings/quint/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing quint plugin for tsParticles + * @param engine */ export async function loadEasingQuintPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/easings/sigmoid/src/index.ts b/plugins/easings/sigmoid/src/index.ts index 38582da604e..6fd00ad9850 100644 --- a/plugins/easings/sigmoid/src/index.ts +++ b/plugins/easings/sigmoid/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing sigmoid plugin for tsParticles + * @param engine */ export async function loadEasingSigmoidPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/easings/sine/src/index.ts b/plugins/easings/sine/src/index.ts index 58ef9c34f92..5c88d8d59a9 100644 --- a/plugins/easings/sine/src/index.ts +++ b/plugins/easings/sine/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing sine plugin for tsParticles + * @param engine */ export async function loadEasingSinePlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/easings/smoothstep/src/index.ts b/plugins/easings/smoothstep/src/index.ts index 3fd3529615a..61f5065f4eb 100644 --- a/plugins/easings/smoothstep/src/index.ts +++ b/plugins/easings/smoothstep/src/index.ts @@ -4,7 +4,8 @@ import { easingsFunctions } from "./easingsFunctions.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the easing smoothstep plugin for tsParticles + * @param engine */ export async function loadEasingSmoothstepPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/emitters/src/EmitterInstance.ts b/plugins/emitters/src/EmitterInstance.ts index c10bfa121b8..be9193314c5 100644 --- a/plugins/emitters/src/EmitterInstance.ts +++ b/plugins/emitters/src/EmitterInstance.ts @@ -91,18 +91,53 @@ function setParticlesOptionsStrokeColor( } /** + * The EmitterInstance class manages a single emitter, handling particle emission, + * lifecycle (duration/count), positioning, sizing, and shape-based spawning. */ export class EmitterInstance { + /** + * Sets if the particles will spawn at the emitter perimeter or inside the area + */ fill; + /** + * The emitter name + */ readonly name?: string; + /** + * The emitter options + */ options; + /** + * The emitter position + */ position: ICoordinates; + /** + * The emitter size + */ size: IDimension; + /** + * The emitter spawn fill color + */ spawnFillColor?: IHsl; + /** + * The emitter spawn fill enabled flag + */ spawnFillEnabled?: boolean; + /** + * The emitter spawn fill opacity + */ spawnFillOpacity?: number; + /** + * The emitter spawn stroke color + */ spawnStrokeColor?: IHsl; + /** + * The emitter spawn stroke opacity + */ spawnStrokeOpacity?: number; + /** + * The emitter spawn stroke width + */ spawnStrokeWidth?: number; private readonly _container; @@ -214,22 +249,34 @@ export class EmitterInstance { this.play(); } + /** + * Pauses the emitter from external calls + */ externalPause(): void { this._paused = true; this.pause(); } + /** + * Resumes the emitter from external calls + */ externalPlay(): void { this._paused = false; this.play(); } + /** + * Initializes the emitter shape + */ async init(): Promise { await this._shape?.init(); } + /** + * Pauses the emitter + */ pause(): void { if (this._paused) { return; @@ -238,6 +285,9 @@ export class EmitterInstance { delete this._emitDelay; } + /** + * Starts or resumes the emitter + */ play(): void { if (this._paused) { return; @@ -267,6 +317,9 @@ export class EmitterInstance { } } + /** + * Resizes the emitter, recalculating position and size, and notifying the shape + */ resize(): void { const initialPosition = this._initialPosition, container = this._container; @@ -282,6 +335,10 @@ export class EmitterInstance { this._shape?.resize(this.position, this.size); } + /** + * Updates the emitter state, handling spawning delays, life cycle, and particle emission + * @param delta - the delta time of the frame + */ update(delta: IDelta): void { if (this._paused) { return; diff --git a/plugins/emitters/src/EmitterShapeBase.ts b/plugins/emitters/src/EmitterShapeBase.ts index cad4b01cf15..2976beb9e33 100644 --- a/plugins/emitters/src/EmitterShapeBase.ts +++ b/plugins/emitters/src/EmitterShapeBase.ts @@ -2,12 +2,36 @@ import type { ICoordinates, IDimension } from "@tsparticles/engine"; import type { IEmitterShape } from "./IEmitterShape.js"; import type { IRandomPositionData } from "./IRandomPositionData.js"; +/** + * Base class for emitter shapes, providing common position, size, and fill handling + */ export abstract class EmitterShapeBase implements IEmitterShape { + /** + * Sets if the particles will spawn at the shape perimeter or inside the area + */ fill: boolean; + + /** + * The shape options + */ options: TOptions; + + /** + * The shape position + */ position: ICoordinates; + + /** + * The shape size + */ size: IDimension; + /** + * @param position - the shape position + * @param size - the shape size + * @param fill - whether to fill the shape or spawn on the perimeter + * @param options - the shape options + */ protected constructor(position: ICoordinates, size: IDimension, fill: boolean, options: TOptions) { this.position = position; this.size = size; @@ -15,12 +39,24 @@ export abstract class EmitterShapeBase implements IEmitterSh this.options = options; } + /** + * Updates the shape position and size + * @param position - the new position + * @param size - the new size + */ resize(position: ICoordinates, size: IDimension): void { this.position = position; this.size = size; } + /** + * Initializes the shape + */ abstract init(): Promise; + /** + * Gets a random position within or on the perimeter of the shape + * @returns the random position data, or null if unavailable + */ abstract randomPosition(): IRandomPositionData | null; } diff --git a/plugins/emitters/src/EmittersInteractor.ts b/plugins/emitters/src/EmittersInteractor.ts index c3ba8d47043..ffa66282904 100644 --- a/plugins/emitters/src/EmittersInteractor.ts +++ b/plugins/emitters/src/EmittersInteractor.ts @@ -25,8 +25,18 @@ import { defaultRandomOptions } from "./constants.js"; const emittersMode = "emitters"; +/** + * The EmittersInteractor class handles the interaction between the user and the emitters, + * processing click modes and updating emitter instances each frame. + */ export class EmittersInteractor extends ExternalInteractorBase { + /** + * Handles click mode for adding emitters on click + */ handleClickMode: (mode: string, interactivityData: IInteractivityData) => void; + /** + * The maximum distance for the interactor + */ readonly maxDistance; private readonly _instancesManager; @@ -91,20 +101,37 @@ export class EmittersInteractor extends ExternalInteractorBase }; } + /** + * Clears the interactor state + */ clear(): void { // no-op } + /** + * Initializes the interactor + */ init(): void { // no-op } + /** + * Processes the interaction for each frame, updating all emitter instances + * @param _interactivityData - the interactivity data + * @param delta - the delta time + */ interact(_interactivityData: IInteractivityData, delta: IDelta): void { for (const emitter of this._instancesManager.getArray(this.container)) { emitter.update(delta); } } + /** + * Checks if the interactor is enabled for the given interactivity data + * @param interactivityData - the interactivity data + * @param particle - the optional particle + * @returns true if the interactor is enabled + */ isEnabled(interactivityData: IInteractivityData, particle?: InteractivityParticle): boolean { const container = this.container, options = container.actualOptions, @@ -118,6 +145,11 @@ export class EmittersInteractor extends ExternalInteractorBase return isInArray(emittersMode, events.onClick.mode); } + /** + * Loads the emitter mode options from sources + * @param options - the target options to load into + * @param sources - the source options to load from + */ loadModeOptions( options: Modes & EmitterModeOptions, ...sources: RecursivePartial<(IModes & IEmitterModeOptions) | undefined>[] @@ -171,6 +203,10 @@ export class EmittersInteractor extends ExternalInteractorBase } } + /** + * Removes an emitter from the instances manager + * @param emitter - the emitter instance to remove + */ removeEmitter(emitter: EmitterInstance): void { const index = this._instancesManager.getArray(this.container).indexOf(emitter), minIndex = 0, @@ -181,6 +217,9 @@ export class EmittersInteractor extends ExternalInteractorBase } } + /** + * Resets the interactor state + */ reset(): void { // no-op } diff --git a/plugins/emitters/src/Enums/EmitterClickMode.ts b/plugins/emitters/src/Enums/EmitterClickMode.ts index de3b620ae3d..c4330175e8d 100644 --- a/plugins/emitters/src/Enums/EmitterClickMode.ts +++ b/plugins/emitters/src/Enums/EmitterClickMode.ts @@ -1,5 +1,9 @@ /** + * Emitter click mode enum */ export enum EmitterClickMode { + /** + * The emitter click mode + */ emitter = "emitter", } diff --git a/plugins/emitters/src/Options/Classes/Emitter.ts b/plugins/emitters/src/Options/Classes/Emitter.ts index 7dba2f0a0f8..6845a590c32 100644 --- a/plugins/emitters/src/Options/Classes/Emitter.ts +++ b/plugins/emitters/src/Options/Classes/Emitter.ts @@ -23,20 +23,63 @@ import type { IEmitter } from "../Interfaces/IEmitter.js"; * [[include:Options/Plugins/Emitters.md]] */ export class Emitter implements IEmitter, IOptionLoader { + /** + * Starts the emitter automatically + */ autoPlay; + /** + * The direction of the emitted particles + */ direction?: MoveDirection | keyof typeof MoveDirection | MoveDirectionAlt | number; + /** + * The DOM element id to link the emitter to an HTML element + */ domId?: string; + /** + * Sets if the particles will spawn at the emitter perimeter or inside the area + */ fill; + /** + * The emitter life options + */ life; + /** + * The emitter name + */ name?: string; + /** + * Particles emitted customization + */ particles?: SingleOrMultiple>; + /** + * The relative position of the emitter + */ position?: RecursivePartial; + /** + * The particles emitting rate options + */ rate; + /** + * The emitter shape options + */ shape; + /** + * The size of the particles emitter area + */ size?: EmitterSize; + /** + * The emitter spawn options + */ spawn; + /** + * The particle spawn fill color + */ spawnFillColor?: AnimatableColor; + /** + * The particle spawn stroke color + */ spawnStrokeColor?: AnimatableColor; + /** The number of starting particles of the emitter */ startCount; constructor() { @@ -49,6 +92,10 @@ export class Emitter implements IEmitter, IOptionLoader { this.startCount = 0; } + /** + * Loads the emitter options from the given data + * @param data - the data to load from + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/plugins/emitters/src/Options/Classes/EmitterLife.ts b/plugins/emitters/src/Options/Classes/EmitterLife.ts index 2f40e9bf2de..89ba132b918 100644 --- a/plugins/emitters/src/Options/Classes/EmitterLife.ts +++ b/plugins/emitters/src/Options/Classes/EmitterLife.ts @@ -2,17 +2,34 @@ import { type IOptionLoader, type RangeValue, type RecursivePartial, isNull, set import type { IEmitterLife } from "../Interfaces/IEmitterLife.js"; /** + * The emitter life options */ export class EmitterLife implements IEmitterLife, IOptionLoader { + /** + * The count of lives the emitter has + */ count?: number; + /** + * The delay between spawns + */ delay?: RangeValue; + /** + * The duration of each emitter life + */ duration?: RangeValue; + /** + * If enabled the first delay will be applied + */ wait; constructor() { this.wait = false; } + /** + * Loads the emitter life options from the given data + * @param data - the data to load from + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/plugins/emitters/src/Options/Classes/EmitterRate.ts b/plugins/emitters/src/Options/Classes/EmitterRate.ts index 6c4c7006738..3034b260226 100644 --- a/plugins/emitters/src/Options/Classes/EmitterRate.ts +++ b/plugins/emitters/src/Options/Classes/EmitterRate.ts @@ -2,9 +2,16 @@ import { type IOptionLoader, type RangeValue, type RecursivePartial, isNull, set import type { IEmitterRate } from "../Interfaces/IEmitterRate.js"; /** + * The emitter rate options */ export class EmitterRate implements IEmitterRate, IOptionLoader { + /** + * The delay between emissions in seconds + */ delay: RangeValue; + /** + * The quantity of particles emitted per emission event + */ quantity: RangeValue; constructor() { @@ -12,6 +19,10 @@ export class EmitterRate implements IEmitterRate, IOptionLoader { this.delay = 0.1; } + /** + * Loads the emitter rate options from the given data + * @param data - the data to load from + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/plugins/emitters/src/Options/Classes/EmitterSize.ts b/plugins/emitters/src/Options/Classes/EmitterSize.ts index dec440d102f..658a85bd5b3 100644 --- a/plugins/emitters/src/Options/Classes/EmitterSize.ts +++ b/plugins/emitters/src/Options/Classes/EmitterSize.ts @@ -2,10 +2,20 @@ import { type IOptionLoader, PixelMode, type RecursivePartial, isNull } from "@t import type { IEmitterSize } from "../Interfaces/IEmitterSize.js"; /** + * The emitter size options */ export class EmitterSize implements IEmitterSize, IOptionLoader { + /** + * The emitter area height + */ height; + /** + * The emitter size mode (percent or precise) + */ mode: PixelMode | keyof typeof PixelMode; + /** + * The emitter area width + */ width; constructor() { @@ -14,6 +24,10 @@ export class EmitterSize implements IEmitterSize, IOptionLoader { this.width = 0; } + /** + * Loads the emitter size options from the given data + * @param data - the data to load from + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/plugins/emitters/src/Options/Interfaces/IEmitter.ts b/plugins/emitters/src/Options/Interfaces/IEmitter.ts index e87e14e80ee..3da6d1b2ee7 100644 --- a/plugins/emitters/src/Options/Interfaces/IEmitter.ts +++ b/plugins/emitters/src/Options/Interfaces/IEmitter.ts @@ -76,6 +76,9 @@ export interface IEmitter { */ size?: IEmitterSize; + /** + * The emitter spawn options + */ spawn: IEmitterSpawn; /** diff --git a/plugins/emitters/src/Options/Interfaces/IEmitterShape.ts b/plugins/emitters/src/Options/Interfaces/IEmitterShape.ts index c0e90409729..9ea17c23030 100644 --- a/plugins/emitters/src/Options/Interfaces/IEmitterShape.ts +++ b/plugins/emitters/src/Options/Interfaces/IEmitterShape.ts @@ -1,7 +1,11 @@ import type { IEmitterShapeReplace } from "./IEmitterShapeReplace.js"; +/** The emitter shape options */ export interface IEmitterShape { + /** The emitter shape options */ options: Record; + /** The emitter shape replace options */ replace: IEmitterShapeReplace; + /** The emitter shape type */ type: string; } diff --git a/plugins/emitters/src/Options/Interfaces/IEmitterShapeReplace.ts b/plugins/emitters/src/Options/Interfaces/IEmitterShapeReplace.ts index 5eaa327dfad..cc28926d110 100644 --- a/plugins/emitters/src/Options/Interfaces/IEmitterShapeReplace.ts +++ b/plugins/emitters/src/Options/Interfaces/IEmitterShapeReplace.ts @@ -1,4 +1,7 @@ +/** The emitter shape replace options */ export interface IEmitterShapeReplace { + /** Replace the color */ color: boolean; + /** Replace the opacity */ opacity: boolean; } diff --git a/plugins/emitters/src/Options/Interfaces/IEmitterSize.ts b/plugins/emitters/src/Options/Interfaces/IEmitterSize.ts index 0565a17eb6a..a0a9259884c 100644 --- a/plugins/emitters/src/Options/Interfaces/IEmitterSize.ts +++ b/plugins/emitters/src/Options/Interfaces/IEmitterSize.ts @@ -1,7 +1,7 @@ import type { IDimension, PixelMode } from "@tsparticles/engine"; -/** - */ +/** The emitter size options */ export interface IEmitterSize extends IDimension { + /** The emitter size mode */ mode: PixelMode | keyof typeof PixelMode; } diff --git a/plugins/emitters/src/Options/Interfaces/IEmitterSpawn.ts b/plugins/emitters/src/Options/Interfaces/IEmitterSpawn.ts index 056b32465a7..cfa8c9429da 100644 --- a/plugins/emitters/src/Options/Interfaces/IEmitterSpawn.ts +++ b/plugins/emitters/src/Options/Interfaces/IEmitterSpawn.ts @@ -1,7 +1,10 @@ import type { IFill, IStroke } from "@tsparticles/engine"; +/** The emitter spawn options */ export interface IEmitterSpawn { + /** The emitter spawn fill */ fill?: IFill; + /** The emitter spawn stroke */ stroke?: IStroke; } diff --git a/plugins/emitters/src/types.ts b/plugins/emitters/src/types.ts index 6b921158030..cfa8742f245 100644 --- a/plugins/emitters/src/types.ts +++ b/plugins/emitters/src/types.ts @@ -2,43 +2,65 @@ import type { IOptions, Options, SingleOrMultiple } from "@tsparticles/engine"; import type { Emitter } from "./Options/Classes/Emitter.js"; import type { IEmitter } from "./Options/Interfaces/IEmitter.js"; +/** Emitter data mode options interface */ export interface IEmitterDataModeOptions { + /** The random mode options */ random: IEmitterModeRandomOptions; + /** The emitter value, single or multiple */ value: SingleOrMultiple; } +/** Random mode options for the emitter */ export interface IEmitterModeRandomOptions { + /** Number of emitters to pick */ count: number; + /** Enables random mode */ enable: boolean; } +/** Random mode options class */ export interface EmitterModeRandomOptions { + /** Number of emitters to pick */ count: number; + /** Enables random mode */ enable: boolean; } +/** Emitter data mode options */ export interface EmitterDataModeOptions { + /** Random mode options */ random: EmitterModeRandomOptions; + /** Emitter values */ value: Emitter[]; } +/** Emitter mode options */ export interface EmitterModeOptions { + /** Emitter data */ emitters?: EmitterDataModeOptions; } +/** Emitter mode options interface */ export interface IEmitterModeOptions { + /** Emitter data */ emitters?: IEmitterDataModeOptions | SingleOrMultiple; } +/** Emitter options type */ export type IEmitterOptions = IOptions & { + /** The emitters */ emitters: SingleOrMultiple; + /** Interactivity modes */ interactivity: { modes: IEmitterModeOptions; }; }; +/** Emitter options */ export type EmitterOptions = Options & { + /** The emitters */ emitters: SingleOrMultiple; + /** Interactivity modes */ interactivity: { modes: EmitterModeOptions; }; diff --git a/plugins/emittersShapes/canvas/src/Options/Classes/EmittersCanvasShapeOptions.ts b/plugins/emittersShapes/canvas/src/Options/Classes/EmittersCanvasShapeOptions.ts index 6d68e0e5749..0c5fce24041 100644 --- a/plugins/emittersShapes/canvas/src/Options/Classes/EmittersCanvasShapeOptions.ts +++ b/plugins/emittersShapes/canvas/src/Options/Classes/EmittersCanvasShapeOptions.ts @@ -5,15 +5,39 @@ import { TextOptions } from "./TextOptions.js"; const minAlpha = 0; +/** + * Canvas emitter shape options + */ export class EmittersCanvasShapeOptions implements IEmittersCanvasShapeOptions, IOptionLoader { + /** + * The canvas element to use as the shape source + */ element?: HTMLCanvasElement; + /** + * A filter function or string to apply to pixels + */ filter: string | ((pixel: IRgba) => boolean); + /** + * The image element to use as the shape source + */ image?: HTMLImageElement; + /** + * The pixels options + */ pixels: PixelsOptions; + /** + * The scale factor for the shape + */ scale: number; + /** + * The CSS selector for the canvas element + */ selector: string; + /** + * The text options for rendering text as the shape + */ text: TextOptions; constructor() { @@ -24,6 +48,10 @@ export class EmittersCanvasShapeOptions this.text = new TextOptions(); } + /** + * Loads the canvas shape options from the given data + * @param data - the data to load from + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/plugins/emittersShapes/canvas/src/Options/Interfaces/IEmittersCanvasShapeOptions.ts b/plugins/emittersShapes/canvas/src/Options/Interfaces/IEmittersCanvasShapeOptions.ts index 352d7033ba0..bd976ea1671 100644 --- a/plugins/emittersShapes/canvas/src/Options/Interfaces/IEmittersCanvasShapeOptions.ts +++ b/plugins/emittersShapes/canvas/src/Options/Interfaces/IEmittersCanvasShapeOptions.ts @@ -2,12 +2,20 @@ import type { IPixelsOptions } from "./IPixelsOptions.js"; import type { IRgba } from "@tsparticles/engine"; import type { ITextOptions } from "./ITextOptions.js"; +/** Canvas emitter shape options interface */ export interface IEmittersCanvasShapeOptions { + /** The canvas element to use as the shape source */ element?: HTMLCanvasElement; + /** A filter function or string to apply to pixels */ filter: string | ((pixel: IRgba) => boolean); + /** The image element to use as the shape source */ image?: HTMLImageElement; + /** The pixels options */ pixels: IPixelsOptions; + /** The scale factor for the shape */ scale: number; + /** The CSS selector for the canvas element */ selector: string; + /** The text options */ text: ITextOptions; } diff --git a/plugins/emittersShapes/canvas/src/types.ts b/plugins/emittersShapes/canvas/src/types.ts index 02a4bb94d6b..f1b8921eb67 100644 --- a/plugins/emittersShapes/canvas/src/types.ts +++ b/plugins/emittersShapes/canvas/src/types.ts @@ -1,14 +1,23 @@ import type { IRgba } from "@tsparticles/engine"; +/** Canvas pixel data extracted from an image or canvas element */ export interface CanvasPixelData { + /** The pixel data height */ height: number; + /** The pixel data as a 2D array of RGBA values */ pixels: IRgba[][]; + /** The pixel data width */ width: number; } +/** Text line rendering data */ export interface TextLineData { + /** The line height */ height: number; + /** The text measurement data */ measure: TextMetrics; + /** The line text content */ text: string; + /** The line width */ width: number; } diff --git a/plugins/emittersShapes/path/src/Options/Classes/EmittersPathShapeOptions.ts b/plugins/emittersShapes/path/src/Options/Classes/EmittersPathShapeOptions.ts index 49c8ee936d6..0f1fcded31a 100644 --- a/plugins/emittersShapes/path/src/Options/Classes/EmittersPathShapeOptions.ts +++ b/plugins/emittersShapes/path/src/Options/Classes/EmittersPathShapeOptions.ts @@ -3,13 +3,23 @@ import type { IEmittersPathShapeOptions } from "../Interfaces/IEmittersPathShape const defaultPosition: ICoordinates = { x: 50, y: 50 }; +/** + * Path shape options for the emitter + */ export class EmittersPathShapeOptions implements IEmittersPathShapeOptions, IOptionLoader { + /** + * The points defining the path + */ points: ICoordinates[]; constructor() { this.points = []; } + /** + * Loads the path shape options from the given data + * @param data - the data to load from + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/plugins/emittersShapes/path/src/Options/Interfaces/IEmittersPathShapeOptions.ts b/plugins/emittersShapes/path/src/Options/Interfaces/IEmittersPathShapeOptions.ts index 67fc13bb847..9bc5e532015 100644 --- a/plugins/emittersShapes/path/src/Options/Interfaces/IEmittersPathShapeOptions.ts +++ b/plugins/emittersShapes/path/src/Options/Interfaces/IEmittersPathShapeOptions.ts @@ -1,5 +1,7 @@ import type { ICoordinates } from "@tsparticles/engine"; +/** Path shape options for the emitter */ export interface IEmittersPathShapeOptions { + /** The points defining the path */ points: ICoordinates[]; } diff --git a/plugins/emittersShapes/polygon/src/Options/Classes/EmittersPolygonShapeOptions.ts b/plugins/emittersShapes/polygon/src/Options/Classes/EmittersPolygonShapeOptions.ts index 581a3a2a297..16b1a32ad21 100644 --- a/plugins/emittersShapes/polygon/src/Options/Classes/EmittersPolygonShapeOptions.ts +++ b/plugins/emittersShapes/polygon/src/Options/Classes/EmittersPolygonShapeOptions.ts @@ -1,10 +1,19 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { IEmittersPolygonShapeOptions } from "../Interfaces/IEmittersPolygonShapeOptions.js"; +/** + * Polygon shape options for the emitter + */ export class EmittersPolygonShapeOptions implements IEmittersPolygonShapeOptions, IOptionLoader { + /** + * The rotation angle of the polygon in radians + */ angle: number; + /** + * The number of sides of the polygon + */ sides: number; constructor() { @@ -12,6 +21,10 @@ export class EmittersPolygonShapeOptions this.sides = 5; } + /** + * Loads the polygon shape options from the given data + * @param data - the data to load from + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/plugins/emittersShapes/polygon/src/Options/Interfaces/IEmittersPolygonShapeOptions.ts b/plugins/emittersShapes/polygon/src/Options/Interfaces/IEmittersPolygonShapeOptions.ts index 14c3f001657..37f95eee547 100644 --- a/plugins/emittersShapes/polygon/src/Options/Interfaces/IEmittersPolygonShapeOptions.ts +++ b/plugins/emittersShapes/polygon/src/Options/Interfaces/IEmittersPolygonShapeOptions.ts @@ -1,4 +1,7 @@ +/** Polygon shape options for the emitter */ export interface IEmittersPolygonShapeOptions { + /** The rotation angle of the polygon in radians */ angle: number; + /** The number of sides of the polygon */ sides: number; } diff --git a/plugins/exports/image/src/ExportImagePlugin.ts b/plugins/exports/image/src/ExportImagePlugin.ts index 85eadf0dfcc..0f604353862 100644 --- a/plugins/exports/image/src/ExportImagePlugin.ts +++ b/plugins/exports/image/src/ExportImagePlugin.ts @@ -1,8 +1,8 @@ import type { Container, IContainerPlugin, IPlugin } from "@tsparticles/engine"; -/** - */ +/** Image export plugin */ export class ExportImagePlugin implements IPlugin { + /** Plugin ID */ readonly id = "export-image"; async getPlugin(container: Container): Promise { @@ -15,6 +15,7 @@ export class ExportImagePlugin implements IPlugin { // do nothing } + /** Checks if the plugin is needed */ needsPlugin(): boolean { return true; } diff --git a/plugins/exports/image/src/ExportImagePluginInstance.ts b/plugins/exports/image/src/ExportImagePluginInstance.ts index 7cd4459eb10..ee77d22b062 100644 --- a/plugins/exports/image/src/ExportImagePluginInstance.ts +++ b/plugins/exports/image/src/ExportImagePluginInstance.ts @@ -1,6 +1,7 @@ import type { Container, ExportResult, IContainerPlugin } from "@tsparticles/engine"; import type { IExportImageData } from "./IExportImageData.js"; +/** Image export plugin instance */ export class ExportImagePluginInstance implements IContainerPlugin { private readonly _container: Container; diff --git a/plugins/exports/image/src/IExportImageData.ts b/plugins/exports/image/src/IExportImageData.ts index 0c2c2b0e59d..19cda45bbfd 100644 --- a/plugins/exports/image/src/IExportImageData.ts +++ b/plugins/exports/image/src/IExportImageData.ts @@ -1,4 +1,7 @@ +/** Image export data options */ export interface IExportImageData { + /** Image quality (0-1) */ quality?: number; + /** MIME type for the exported image */ type?: string; } diff --git a/plugins/exports/image/src/index.ts b/plugins/exports/image/src/index.ts index 116a13471ab..ddba3dfd09f 100644 --- a/plugins/exports/image/src/index.ts +++ b/plugins/exports/image/src/index.ts @@ -4,7 +4,8 @@ import { ExportImagePlugin } from "./ExportImagePlugin.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the image export plugin for tsParticles + * @param engine */ export async function loadExportImagePlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/exports/json/src/ExportJSONPlugin.ts b/plugins/exports/json/src/ExportJSONPlugin.ts index dfbc141c0c6..8413cb28f4e 100644 --- a/plugins/exports/json/src/ExportJSONPlugin.ts +++ b/plugins/exports/json/src/ExportJSONPlugin.ts @@ -1,8 +1,8 @@ import type { Container, IContainerPlugin, IPlugin } from "@tsparticles/engine"; -/** - */ +/** JSON export plugin */ export class ExportJSONPlugin implements IPlugin { + /** Plugin ID */ readonly id = "export-json"; async getPlugin(container: Container): Promise { @@ -15,6 +15,7 @@ export class ExportJSONPlugin implements IPlugin { // do nothing } + /** Checks if the plugin is needed */ needsPlugin(): boolean { return true; } diff --git a/plugins/exports/json/src/ExportJSONPluginInstance.ts b/plugins/exports/json/src/ExportJSONPluginInstance.ts index 76637f2f30d..2eae0e179f1 100644 --- a/plugins/exports/json/src/ExportJSONPluginInstance.ts +++ b/plugins/exports/json/src/ExportJSONPluginInstance.ts @@ -2,6 +2,7 @@ import type { Container, ExportResult, IContainerPlugin } from "@tsparticles/eng const indent = 2; +/** JSON export plugin instance */ export class ExportJSONPluginInstance implements IContainerPlugin { private readonly _container: Container; diff --git a/plugins/exports/json/src/index.ts b/plugins/exports/json/src/index.ts index 3b9494d0f40..5dc2c405dfa 100644 --- a/plugins/exports/json/src/index.ts +++ b/plugins/exports/json/src/index.ts @@ -4,7 +4,8 @@ import { ExportJSONPlugin } from "./ExportJSONPlugin.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the JSON export plugin for tsParticles + * @param engine */ export async function loadExportJSONPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/exports/video/src/ExportVideoPlugin.ts b/plugins/exports/video/src/ExportVideoPlugin.ts index a770ae46bfb..81c5fcbd85c 100644 --- a/plugins/exports/video/src/ExportVideoPlugin.ts +++ b/plugins/exports/video/src/ExportVideoPlugin.ts @@ -1,8 +1,8 @@ import type { Container, IContainerPlugin, IPlugin } from "@tsparticles/engine"; -/** - */ +/** Video export plugin */ export class ExportVideoPlugin implements IPlugin { + /** Plugin ID */ readonly id = "export-video"; async getPlugin(container: Container): Promise { @@ -15,6 +15,7 @@ export class ExportVideoPlugin implements IPlugin { // do nothing } + /** Checks if the plugin is needed */ needsPlugin(): boolean { return true; } diff --git a/plugins/exports/video/src/ExportVideoPluginInstance.ts b/plugins/exports/video/src/ExportVideoPluginInstance.ts index e3483c2c629..7ae81e693ba 100644 --- a/plugins/exports/video/src/ExportVideoPluginInstance.ts +++ b/plugins/exports/video/src/ExportVideoPluginInstance.ts @@ -52,6 +52,7 @@ function getVideoSupportedMimeTypes(): string[] { return supported; } +/** Video export plugin instance */ export class ExportVideoPluginInstance implements IContainerPlugin { private readonly _container: Container; private readonly _supportedTypes: string[] = []; diff --git a/plugins/exports/video/src/IExportVideoData.ts b/plugins/exports/video/src/IExportVideoData.ts index fc824ddd102..00845a9942c 100644 --- a/plugins/exports/video/src/IExportVideoData.ts +++ b/plugins/exports/video/src/IExportVideoData.ts @@ -1,5 +1,9 @@ +/** Video export data options */ export interface IExportVideoData { + /** Video duration in seconds */ duration?: number; + /** Frames per second */ fps?: number; + /** MIME type for the exported video */ mimeType?: string; } diff --git a/plugins/exports/video/src/index.ts b/plugins/exports/video/src/index.ts index a1b90d069e6..4149980edb2 100644 --- a/plugins/exports/video/src/index.ts +++ b/plugins/exports/video/src/index.ts @@ -4,7 +4,8 @@ import { ExportVideoPlugin } from "./ExportVideoPlugin.js"; declare const __VERSION__: string; /** - * @param engine - + * Loads the video export plugin for tsParticles + * @param engine */ export async function loadExportVideoPlugin(engine: Engine): Promise { engine.checkVersion(__VERSION__); diff --git a/plugins/infection/src/InfectionPluginInstance.ts b/plugins/infection/src/InfectionPluginInstance.ts index 9cdc19c6437..3c16aaae021 100644 --- a/plugins/infection/src/InfectionPluginInstance.ts +++ b/plugins/infection/src/InfectionPluginInstance.ts @@ -5,13 +5,19 @@ import { Infecter } from "./Infecter.js"; const minStage = 0; export class InfectionPluginInstance implements IContainerPlugin { + /** The particles container */ private readonly _container; + /** + * Creates a new InfectionPluginInstance + * @param container - the infectable container + */ constructor(container: InfectableContainer) { this._container = container; this._container.infecter = new Infecter(this._container); } + /** @inheritDoc */ particleFillColor(particle: InfectableParticle): string | IOptionsColor | undefined { const options = this._container.actualOptions; @@ -26,10 +32,12 @@ export class InfectionPluginInstance implements IContainerPlugin { return infectionStage === undefined ? undefined : infectionStages[infectionStage]?.color; } + /** @inheritDoc */ particleStrokeColor(particle: Particle): string | IOptionsColor | undefined { return this.particleFillColor(particle); } + /** @inheritDoc */ particlesSetup(): void { const options = this._container.actualOptions; diff --git a/plugins/infection/src/Options/Classes/Infection.ts b/plugins/infection/src/Options/Classes/Infection.ts index 0da4622914f..1683b0ec1fa 100644 --- a/plugins/infection/src/Options/Classes/Infection.ts +++ b/plugins/infection/src/Options/Classes/Infection.ts @@ -6,10 +6,15 @@ import { InfectionStage } from "./InfectionStage.js"; * [[include:Options/Plugins/Infection.md]] */ export class Infection implements IInfection, IOptionLoader { + /** This property specifies if particles can turn back to the original state after being infected */ cure; + /** The infection delay of the new infected particles */ delay; + /** Enables the infection animations */ enable; + /** The initial number of infected particles */ infections; + /** This property contains all the infection stages configurations */ stages: InfectionStage[]; constructor() { diff --git a/plugins/infection/src/Options/Classes/InfectionStage.ts b/plugins/infection/src/Options/Classes/InfectionStage.ts index b9b207ce0f0..3162f2c52f8 100644 --- a/plugins/infection/src/Options/Classes/InfectionStage.ts +++ b/plugins/infection/src/Options/Classes/InfectionStage.ts @@ -1,13 +1,17 @@ import { type IOptionLoader, OptionsColor, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { IInfectionStage } from "../Interfaces/IInfectionStage.js"; -/** - */ +/** Infection stage options */ export class InfectionStage implements IInfectionStage, IOptionLoader { + /** Infection stage particle color */ color; + /** Infection stage duration, after this time has passed it will go to the next stage */ duration?: number; + /** The infected stage set to the infected particles by the current stage */ infectedStage?: number; + /** Infection stage contagious area radius, if 0 only particles touching would be affected */ radius; + /** Infection rate, the higher it is, the more particles will be infected */ rate; constructor() { diff --git a/plugins/infection/src/Types.ts b/plugins/infection/src/Types.ts index 37a49d8b68f..85185bf674b 100644 --- a/plugins/infection/src/Types.ts +++ b/plugins/infection/src/Types.ts @@ -9,25 +9,37 @@ import type { Infection } from "./Options/Classes/Infection.js"; import type { Particle } from "@tsparticles/engine"; export interface IParticleInfection { + /** The infection delay for this particle */ delay?: number; + /** The delay stage */ delayStage?: number; + /** The current infection stage */ stage?: number; + /** The time since infection started */ time?: number; } +/** Container with infection capabilities */ export type InfectableContainer = InteractivityContainer & { + /** The actual infection options */ actualOptions: InfectionOptions; + /** The infecter instance */ infecter?: Infecter; }; +/** Infection plugin options interface */ export type IInfectionOptions = IInteractivityOptions & { + /** The infection options */ infection: IInfection; }; +/** Infection plugin options class */ export type InfectionOptions = InteractivityOptions & { + /** The infection options */ infection?: Infection; }; +/** Particle with infection data */ export type InfectableParticle = Particle & { infection?: IParticleInfection; }; diff --git a/plugins/interactivity/src/Enums/DivType.ts b/plugins/interactivity/src/Enums/DivType.ts index e6f34fb3249..8203fcfae89 100644 --- a/plugins/interactivity/src/Enums/DivType.ts +++ b/plugins/interactivity/src/Enums/DivType.ts @@ -1,5 +1,4 @@ -/** - */ +/** Div element shape types for interactivity */ export enum DivType { circle = "circle", rectangle = "rectangle", diff --git a/plugins/interactivity/src/Enums/InteractivityDetect.ts b/plugins/interactivity/src/Enums/InteractivityDetect.ts index 747e503b8b7..ee9bd90afed 100644 --- a/plugins/interactivity/src/Enums/InteractivityDetect.ts +++ b/plugins/interactivity/src/Enums/InteractivityDetect.ts @@ -1,5 +1,4 @@ -/** - */ +/** Event detection modes for interactivity */ export enum InteractivityDetect { canvas = "canvas", parent = "parent", diff --git a/plugins/interactivity/src/InteractionManager.ts b/plugins/interactivity/src/InteractionManager.ts index 447eaee4548..9546295161e 100644 --- a/plugins/interactivity/src/InteractionManager.ts +++ b/plugins/interactivity/src/InteractionManager.ts @@ -24,13 +24,17 @@ const clickRadius = 1, touchEndLengthOffset = 1, minCoordinate = 0; +/** Container click handler type */ type ContainerClickHandler = (evt: Event) => void; export class InteractionManager { + /** The current interactivity state data */ interactivityData: IInteractivityData; + /** Map of event names to click handlers */ private readonly _clickHandlers; + /** The event listeners instance */ private readonly _eventListeners; /** @@ -45,6 +49,7 @@ export class InteractionManager { */ private _interactors: IInteractor[]; + /** The intersection observer for viewport detection */ private readonly _intersectionObserver; /** @@ -85,6 +90,10 @@ export class InteractionManager { }); } + /** + * Adds a click/touch handler to the container element + * @param callback - the callback to invoke on click/touch + */ addClickHandler(callback: (evt: Event, particles?: Particle[]) => void): void { const { container, interactivityData } = this; @@ -189,10 +198,12 @@ export class InteractionManager { } } + /** Adds interactivity event listeners */ addListeners(): void { this._eventListeners.addListeners(); } + /** Clears all click and touch handlers */ clearClickHandlers(): void { const { container, interactivityData } = this; @@ -221,6 +232,10 @@ export class InteractionManager { } } + /** + * Handles a click mode for all external interactors + * @param mode - the click mode to handle + */ handleClickMode(mode: string): void { if (this.container.destroyed) { return; @@ -255,6 +270,7 @@ export class InteractionManager { } } + /** Initializes all interactors from the plugin manager */ async initInteractors(): Promise { const interactors = await this._pluginManager.getInteractors?.(this.container, true); @@ -287,6 +303,7 @@ export class InteractionManager { } } + /** Removes all interactivity event listeners */ removeListeners(): void { this._eventListeners.removeListeners(); } @@ -311,6 +328,7 @@ export class InteractionManager { } } + /** Starts observing the container element for intersection changes */ startObserving(): void { const { interactivityData } = this; @@ -319,6 +337,7 @@ export class InteractionManager { } } + /** Stops observing the container element for intersection changes */ stopObserving(): void { const { interactivityData } = this; @@ -327,6 +346,7 @@ export class InteractionManager { } } + /** Updates the maximum distance for the spatial grid */ updateMaxDistance(): void { let maxTotalDistance = 0; diff --git a/plugins/interactivity/src/InteractivityConstants.ts b/plugins/interactivity/src/InteractivityConstants.ts index b2c2a89dd7a..8797d7a764d 100644 --- a/plugins/interactivity/src/InteractivityConstants.ts +++ b/plugins/interactivity/src/InteractivityConstants.ts @@ -1,9 +1,18 @@ +/** Click event name */ export const clickEvent = "click", + /** Pointer down event name */ mouseDownEvent = "pointerdown", + /** Pointer up event name */ mouseUpEvent = "pointerup", + /** Pointer leave event name */ mouseLeaveEvent = "pointerleave", + /** Pointer move event name */ mouseMoveEvent = "pointermove", + /** Touch start event name */ touchStartEvent = "touchstart", + /** Touch end event name */ touchEndEvent = "touchend", + /** Touch move event name */ touchMoveEvent = "touchmove", + /** Touch cancel event name */ touchCancelEvent = "touchcancel"; diff --git a/plugins/interactivity/src/InteractivityPlugin.ts b/plugins/interactivity/src/InteractivityPlugin.ts index 9fbf39c6a22..5db28e2fc03 100644 --- a/plugins/interactivity/src/InteractivityPlugin.ts +++ b/plugins/interactivity/src/InteractivityPlugin.ts @@ -16,8 +16,7 @@ import type { IInteractivity } from "./Options/Interfaces/IInteractivity.js"; import type { IParticleInteractorBase } from "./Interfaces/IParticleInteractorBase.js"; import { Interactivity } from "./Options/Classes/Interactivity.js"; -/** - */ +/** Interactivity plugin class implementing IPlugin */ export class InteractivityPlugin implements IPlugin { readonly id = "interactivity"; diff --git a/plugins/interactivity/src/InteractivityPluginInstance.ts b/plugins/interactivity/src/InteractivityPluginInstance.ts index 2748740bfda..dd072b65950 100644 --- a/plugins/interactivity/src/InteractivityPluginInstance.ts +++ b/plugins/interactivity/src/InteractivityPluginInstance.ts @@ -4,11 +4,19 @@ import { InteractionManager } from "./InteractionManager.js"; import { Interactivity } from "./Options/Classes/Interactivity.js"; export class InteractivityPluginInstance implements IContainerPlugin { + /** The interaction manager for this container */ readonly interactionManager: InteractionManager; + /** The particles container */ private readonly _container; + /** The plugin manager */ private readonly _pluginManager; + /** + * Creates a new InteractivityPluginInstance + * @param pluginManager - the plugin manager + * @param container - the particles container + */ constructor(pluginManager: InteractivityPluginManager, container: InteractivityContainer) { this._container = container; this._pluginManager = pluginManager; @@ -27,16 +35,19 @@ export class InteractivityPluginInstance implements IContainerPlugin { this.interactionManager.addClickHandler(callback); } + /** Clears all click handlers */ clearClickHandlers(): void { this.interactionManager.clearClickHandlers(); } + /** @inheritDoc */ destroy(): void { this.clearClickHandlers(); this._pluginManager.interactors?.delete(this._container); } + /** @inheritDoc */ particleCreated(particle: Particle): void { const interactivityParticle = particle as InteractivityParticle, interactivity = new Interactivity(this._pluginManager, this._container); @@ -47,29 +58,35 @@ export class InteractivityPluginInstance implements IContainerPlugin { interactivityParticle.interactivity = interactivity; } + /** @inheritDoc */ particleReset(particle: Particle): void { this.interactionManager.reset(particle); } + /** @inheritDoc */ postParticleUpdate(particle: Particle, delta: IDelta): void { this.interactionManager.particlesInteract(particle, delta); } + /** @inheritDoc */ postUpdate(delta: IDelta): void { this.interactionManager.externalInteract(delta); this.interactionManager.updateMaxDistance(); } + /** @inheritDoc */ async preInit(): Promise { await this.interactionManager.initInteractors(); this.interactionManager.init(); } + /** @inheritDoc */ async redrawInit(): Promise { await this.interactionManager.initInteractors(); this.interactionManager.init(); } + /** @inheritDoc */ start(): Promise { this.interactionManager.addListeners(); this.interactionManager.startObserving(); @@ -77,6 +94,7 @@ export class InteractivityPluginInstance implements IContainerPlugin { return Promise.resolve(); } + /** @inheritDoc */ stop(): void { this.interactionManager.removeListeners(); this.interactionManager.stopObserving(); diff --git a/plugins/interactivity/src/Interfaces/IExternalInteractor.ts b/plugins/interactivity/src/Interfaces/IExternalInteractor.ts index 27d9c79f245..32654f4e9fc 100644 --- a/plugins/interactivity/src/Interfaces/IExternalInteractor.ts +++ b/plugins/interactivity/src/Interfaces/IExternalInteractor.ts @@ -5,6 +5,7 @@ import type { IParticleInteractorBase } from "./IParticleInteractorBase.js"; import type { Modes } from "../Options/Classes/Modes/Modes.js"; /** + External interactor interface */ export interface IExternalInteractor extends IParticleInteractorBase { handleClickMode?: (mode: string, interactivityData: IInteractivityData) => void; diff --git a/plugins/interactivity/src/Interfaces/IInteractivityData.ts b/plugins/interactivity/src/Interfaces/IInteractivityData.ts index 7be48f2535b..f4e31f2c06a 100644 --- a/plugins/interactivity/src/Interfaces/IInteractivityData.ts +++ b/plugins/interactivity/src/Interfaces/IInteractivityData.ts @@ -1,7 +1,6 @@ import type { IMouseData } from "./IMouseData.js"; -/** - */ +/** Interactivity data interface containing mouse and element info */ export interface IInteractivityData { element?: HTMLElement | Node | typeof globalThis | null; mouse: IMouseData; diff --git a/plugins/interactivity/src/Interfaces/IInteractor.ts b/plugins/interactivity/src/Interfaces/IInteractor.ts index 26786aabbdc..0b94193aaf6 100644 --- a/plugins/interactivity/src/Interfaces/IInteractor.ts +++ b/plugins/interactivity/src/Interfaces/IInteractor.ts @@ -1,14 +1,17 @@ import type { ISourceOptions, Options } from "@tsparticles/engine"; import type { InteractorType } from "../Enums/InteractorType.js"; -/** - */ +/** Interactor base interface */ export interface IInteractor { + /** Loads interactor options from source options */ loadOptions?: (options: Options, ...sources: (ISourceOptions | undefined)[]) => void; + /** The maximum distance for this interactor */ maxDistance: number; + /** The interactor type */ type: InteractorType; + /** Initializes the interactor */ init(): void; } diff --git a/plugins/interactivity/src/Interfaces/IMouseData.ts b/plugins/interactivity/src/Interfaces/IMouseData.ts index ad147881c75..28d9cfeac2e 100644 --- a/plugins/interactivity/src/Interfaces/IMouseData.ts +++ b/plugins/interactivity/src/Interfaces/IMouseData.ts @@ -1,7 +1,6 @@ import type { ICoordinates } from "@tsparticles/engine"; -/** - */ +/** Mouse event data for interactivity */ export interface IMouseData { clickPosition?: ICoordinates; clickTime?: number; diff --git a/plugins/interactivity/src/Interfaces/IParticleInteractorBase.ts b/plugins/interactivity/src/Interfaces/IParticleInteractorBase.ts index 4e12612f617..cda6fec451d 100644 --- a/plugins/interactivity/src/Interfaces/IParticleInteractorBase.ts +++ b/plugins/interactivity/src/Interfaces/IParticleInteractorBase.ts @@ -3,15 +3,17 @@ import type { IInteractivityParticlesOptions, InteractivityParticlesOptions } fr import type { IInteractivityData } from "./IInteractivityData.js"; import type { IInteractor } from "./IInteractor.js"; -/** - */ +/** Particle interactor base interface */ export interface IParticleInteractorBase extends IInteractor { + /** Loads particles options from source options */ loadParticlesOptions?: ( options: InteractivityParticlesOptions, ...sources: (RecursivePartial | undefined)[] ) => void; + /** Clears the interactor state for a particle */ clear(particle: TParticle, delta: IDelta): void; + /** Resets the interactor state for a particle */ reset(interactivityData: IInteractivityData, particle: TParticle): void; } diff --git a/plugins/interactivity/src/Interfaces/IParticlesInteractor.ts b/plugins/interactivity/src/Interfaces/IParticlesInteractor.ts index 116e7f27cc5..9a87b557a2c 100644 --- a/plugins/interactivity/src/Interfaces/IParticlesInteractor.ts +++ b/plugins/interactivity/src/Interfaces/IParticlesInteractor.ts @@ -3,6 +3,7 @@ import type { IInteractivityData } from "./IInteractivityData.js"; import type { IParticleInteractorBase } from "./IParticleInteractorBase.js"; /** + Particles interactor interface */ export interface IParticlesInteractor< TParticle extends Particle = Particle, diff --git a/plugins/interactivity/src/Options/Interfaces/Modes/IModeDiv.ts b/plugins/interactivity/src/Options/Interfaces/Modes/IModeDiv.ts index 8196f489a83..b050bac206b 100644 --- a/plugins/interactivity/src/Options/Interfaces/Modes/IModeDiv.ts +++ b/plugins/interactivity/src/Options/Interfaces/Modes/IModeDiv.ts @@ -1,7 +1,6 @@ import type { SingleOrMultiple } from "@tsparticles/engine"; -/** - */ +/** Mode div interface with selector support */ export interface IModeDiv { selectors: SingleOrMultiple; } diff --git a/plugins/interactivity/src/types.ts b/plugins/interactivity/src/types.ts index 9071e479a47..0978e5d9a89 100644 --- a/plugins/interactivity/src/types.ts +++ b/plugins/interactivity/src/types.ts @@ -14,30 +14,43 @@ import type { IInteractivity } from "./Options/Interfaces/IInteractivity.js"; import type { IInteractor } from "./Interfaces/IInteractor.js"; import type { Interactivity } from "./Options/Classes/Interactivity.js"; +/** Interactivity plugin options interface */ export type IInteractivityOptions = IOptions & { + /** The interactivity options */ interactivity?: IInteractivity; }; +/** Interactivity plugin options class */ export type InteractivityOptions = Options & { interactivity?: Interactivity; }; +/** Container with interactivity capabilities */ export type InteractivityContainer = Container & { + /** The actual interactivity options */ actualOptions: InteractivityOptions; + /** Adds a click handler for interactivity */ addClickHandler?: (callback: (evt: Event, particles?: Particle[]) => void) => void; }; +/** Particle with interactivity data */ export type InteractivityParticle = Particle & { + /** The interactivity options for this particle */ interactivity?: Interactivity; + /** The particle options including interactivity */ options: InteractivityParticlesOptions; }; +/** Interactivity particles options interface */ export type IInteractivityParticlesOptions = IParticlesOptions & { + /** The interactivity options for particles */ interactivity?: RecursivePartial; }; +/** Interactivity particles options class */ export type InteractivityParticlesOptions = RecursivePartial & { + /** The interactivity options for particles */ interactivity?: RecursivePartial; }; @@ -46,20 +59,29 @@ export type InteractivityParticlesOptions = RecursivePartial & */ export type InteractorInitializer = GenericInitializer; +/** Interactivity plugin manager */ export type InteractivityPluginManager = PluginManager & { + /** Adds an interactor by name */ addInteractor?: (name: string, interactorInitializer: InteractorInitializer) => void; + /** Gets all interactors for the container */ getInteractors?: (container: Container, force?: boolean) => Promise; + /** The interactor initializers */ initializers: { + /** Map of interactor initializers */ interactors?: Map; }; + /** Map of containers to their interactors */ interactors?: Map; + /** Sets a click handler for interactivity */ setOnClickHandler?: (callback: (e: Event, particles?: Particle[]) => void) => void; }; +/** Engine with interactivity plugin manager */ export type InteractivityEngine = Engine & { + /** The interactivity plugin manager */ pluginManager: InteractivityPluginManager; }; diff --git a/plugins/manualParticles/src/ManualParticlesPluginInstance.ts b/plugins/manualParticles/src/ManualParticlesPluginInstance.ts index e60f5b63cea..68393bc1dfc 100644 --- a/plugins/manualParticles/src/ManualParticlesPluginInstance.ts +++ b/plugins/manualParticles/src/ManualParticlesPluginInstance.ts @@ -4,8 +4,13 @@ import type { ManualParticlesContainer } from "./types.js"; const noParticles = 0; export class ManualParticlesPluginInstance implements IContainerPlugin { + /** The manual particles container */ private readonly _container; + /** + * Creates a new ManualParticlesPluginInstance + * @param container - the manual particles container + */ constructor(container: ManualParticlesContainer) { this._container = container; } diff --git a/plugins/manualParticles/src/Options/Classes/ManualParticle.ts b/plugins/manualParticles/src/Options/Classes/ManualParticle.ts index d71612d7141..7f14a213053 100644 --- a/plugins/manualParticles/src/Options/Classes/ManualParticle.ts +++ b/plugins/manualParticles/src/Options/Classes/ManualParticle.ts @@ -12,7 +12,9 @@ import type { IManualParticle } from "../Interfaces/IManualParticle.js"; const manualDefaultPosition = 50; export class ManualParticle implements IManualParticle, IOptionLoader { + /** Particle options, these properties will override the general particles configuration */ options?: RecursivePartial; + /** Particle position in canvas size percent, if undefined a random position will be used */ position?: ICoordinatesWithMode; load(data?: RecursivePartial): void { diff --git a/plugins/motion/src/MotionPluginInstance.ts b/plugins/motion/src/MotionPluginInstance.ts index a8532904f8b..ceb1610540f 100644 --- a/plugins/motion/src/MotionPluginInstance.ts +++ b/plugins/motion/src/MotionPluginInstance.ts @@ -7,12 +7,18 @@ const defaultFactor = 1, identity = 1; export class MotionPluginInstance implements IContainerPlugin { + /** The motion container */ private readonly _container; + /** + * Creates a new MotionPluginInstance + * @param container - the motion container + */ constructor(container: MotionContainer) { this._container = container; } + /** @inheritDoc */ async init(): Promise { const container = this._container, options = container.actualOptions.motion; diff --git a/plugins/motion/src/Options/Interfaces/IMotionReduce.ts b/plugins/motion/src/Options/Interfaces/IMotionReduce.ts index 6445657527c..b44fc44bd9a 100644 --- a/plugins/motion/src/Options/Interfaces/IMotionReduce.ts +++ b/plugins/motion/src/Options/Interfaces/IMotionReduce.ts @@ -1,5 +1,4 @@ -/** - */ +/** Motion reduce options for prefers-reduced-motion */ export interface IMotionReduce { /** * Factor used to reduce motion, the higher the value, the higher the motion reduction diff --git a/plugins/motion/src/types.ts b/plugins/motion/src/types.ts index f1fe731179c..2f9e16b6496 100644 --- a/plugins/motion/src/types.ts +++ b/plugins/motion/src/types.ts @@ -2,14 +2,17 @@ import type { Container, IOptions, Options } from "@tsparticles/engine"; import type { IMotion } from "./Options/Interfaces/IMotion.js"; import type { Motion } from "./Options/Classes/Motion.js"; +/** Motion plugin options interface */ export type IMotionOptions = IOptions & { motion?: IMotion; }; +/** Motion plugin options class */ export type MotionOptions = Options & { motion?: Motion; }; +/** Container with motion capabilities */ export type MotionContainer = Container & { actualOptions: MotionOptions; }; diff --git a/plugins/move/src/IMovePathGenerator.ts b/plugins/move/src/IMovePathGenerator.ts index 4834723ce77..09a9ccce99a 100644 --- a/plugins/move/src/IMovePathGenerator.ts +++ b/plugins/move/src/IMovePathGenerator.ts @@ -1,13 +1,16 @@ import type { IDelta, Particle, Vector } from "@tsparticles/engine"; -/** - */ +/** Move path generator interface */ export interface IMovePathGenerator { + /** Generates a path vector for the given particle */ generate: (particle: Particle, delta: IDelta) => Vector; + /** Initializes the path generator */ init: () => void; + /** Resets the path generator state for the given particle */ reset: (particle: Particle) => void; + /** Updates the path generator state */ update: () => void; } diff --git a/plugins/move/src/MovePluginInstance.ts b/plugins/move/src/MovePluginInstance.ts index 262cf2ef63a..b6c7bf5be32 100644 --- a/plugins/move/src/MovePluginInstance.ts +++ b/plugins/move/src/MovePluginInstance.ts @@ -16,12 +16,21 @@ const defaultSizeFactor = 1, defaultDeltaFactor = 1; export class MovePluginInstance implements IContainerPlugin { + /** Available path generators from the engine */ availablePathGenerators: Map; + /** Active path generators for this container */ pathGenerators: Map; + /** The particles container */ private readonly _container; + /** The plugin manager */ private readonly _pluginManager; + /** + * Creates a new MovePluginInstance + * @param pluginManager - the plugin manager + * @param container - the particles container + */ constructor(pluginManager: MovePluginManager, container: Container) { this._pluginManager = pluginManager; this._container = container; @@ -30,6 +39,7 @@ export class MovePluginInstance implements IContainerPlugin { this.pathGenerators = new Map(); } + /** @inheritDoc */ destroy(): void { this.availablePathGenerators = new Map(); this.pathGenerators = new Map(); @@ -43,9 +53,7 @@ export class MovePluginInstance implements IContainerPlugin { return !particle.destroyed && particle.options.move.enable; } - /** - * @param particle - - */ + /** @inheritDoc */ particleCreated(particle: MoveParticle): void { const options = particle.options, moveOptions = options.move, @@ -80,16 +88,14 @@ export class MovePluginInstance implements IContainerPlugin { initSpin(this._container, particle); } + /** @inheritDoc */ particleDestroyed(particle: MoveParticle): void { const pathGenerator = particle.pathGenerator; pathGenerator?.reset(particle); } - /** - * @param particle - - * @param delta - - */ + /** @inheritDoc */ particleUpdate(particle: MoveParticle, delta: IDelta): void { const particleOptions = particle.options, moveOptions = particleOptions.move; @@ -119,14 +125,17 @@ export class MovePluginInstance implements IContainerPlugin { applyDistance(particle); } + /** @inheritDoc */ preInit(): Promise { return this._init(); } + /** @inheritDoc */ redrawInit(): Promise { return this._init(); } + /** Updates all active path generators */ update(): void { for (const pathGenerator of this.pathGenerators.values()) { pathGenerator.update(); diff --git a/plugins/move/src/Types.ts b/plugins/move/src/Types.ts index 0f41b4586cf..8d6ef8f7bdc 100644 --- a/plugins/move/src/Types.ts +++ b/plugins/move/src/Types.ts @@ -3,21 +3,30 @@ import type { IMovePathGenerator } from "./IMovePathGenerator.js"; import type { IParticleGravity } from "./IParticleGravity.js"; import type { IParticleSpin } from "./IParticleSpin.js"; +/** Path generator initializer type */ export type PathGeneratorInitializer = GenericInitializer; +/** Move plugin manager */ export type MovePluginManager = PluginManager & { + /** Adds a path generator by name */ addPathGenerator?: (name: string, generator: PathGeneratorInitializer) => void; + /** Gets all path generators for the container */ getPathGenerators?: (container: Container, force?: boolean) => Promise>; + /** The path generator initializers */ initializers: { + /** Map of path generator initializers */ pathGenerators?: Map; }; + /** Map of containers to their path generators */ pathGenerators?: Map>; }; +/** Engine with move plugin manager */ export type MoveEngine = Engine & { + /** The move plugin manager */ pluginManager: MovePluginManager; }; @@ -42,15 +51,12 @@ export type MoveParticle = Particle & { */ pathGenerator?: IMovePathGenerator; - /** - */ + /** The retina properties for this particle */ retina: { - /** - */ + /** The spin acceleration value */ spinAcceleration?: number; }; - /** - */ + /** The particle spin animation data */ spin?: IParticleSpin; }; diff --git a/plugins/poisson/src/Options/Classes/Poisson.ts b/plugins/poisson/src/Options/Classes/Poisson.ts index 3d42e48b42a..220977f14e6 100644 --- a/plugins/poisson/src/Options/Classes/Poisson.ts +++ b/plugins/poisson/src/Options/Classes/Poisson.ts @@ -5,10 +5,15 @@ import type { IPoisson } from "../Interfaces/IPoisson.js"; * [[include:Options/Plugins/Poisson.md]] */ export class Poisson implements IPoisson, IOptionLoader { + /** The poisson dimensions */ dimensions; + /** Enables the poisson disc sampling */ enable; + /** The poisson radius */ radius; + /** The poisson retries */ retries; + /** The poisson steps */ steps; constructor() { diff --git a/plugins/poisson/src/Options/Interfaces/IPoisson.ts b/plugins/poisson/src/Options/Interfaces/IPoisson.ts index a1cc1afc6c4..32843f08239 100644 --- a/plugins/poisson/src/Options/Interfaces/IPoisson.ts +++ b/plugins/poisson/src/Options/Interfaces/IPoisson.ts @@ -2,9 +2,14 @@ * [[include:Options/Plugins/Poisson.md]] */ export interface IPoisson { + /** The poisson dimensions */ dimensions: number; + /** Enables the poisson disc sampling */ enable: boolean; + /** The poisson radius */ radius: number; + /** The poisson retries */ retries: number; + /** The poisson steps */ steps: number; } diff --git a/plugins/poisson/src/PoissonDiscPluginInstance.ts b/plugins/poisson/src/PoissonDiscPluginInstance.ts index 4d639c26719..bc023c187c6 100644 --- a/plugins/poisson/src/PoissonDiscPluginInstance.ts +++ b/plugins/poisson/src/PoissonDiscPluginInstance.ts @@ -6,17 +6,26 @@ import type { PoissonDisc } from "./PoissonDisc.js"; * Poisson Disc manager */ export class PoissonDiscPluginInstance implements IContainerPlugin { + /** The poisson disc sampler */ poissonDisc?: PoissonDisc; + /** The redraw timeout handle */ redrawTimeout?: number; + /** The poisson container */ private readonly _container: PoissonContainer; + /** The current point index */ private _currentIndex: number; + /** + * Creates a new PoissonDiscPluginInstance + * @param container - the poisson container + */ constructor(container: PoissonContainer) { this._container = container; this._currentIndex = 0; } + /** @inheritDoc */ async init(): Promise { await this._initData(); } diff --git a/plugins/polygonMask/src/Options/Classes/PolygonMask.ts b/plugins/polygonMask/src/Options/Classes/PolygonMask.ts index a510c06593b..26b7de85131 100644 --- a/plugins/polygonMask/src/Options/Classes/PolygonMask.ts +++ b/plugins/polygonMask/src/Options/Classes/PolygonMask.ts @@ -18,14 +18,23 @@ import { PolygonMaskType } from "../../Enums/PolygonMaskType.js"; * [[include:Options/Plugins/PolygonMask.md]] */ export class PolygonMask implements IPolygonMask, IOptionLoader { + /** The polygon mask SVG data */ data?: string | PolygonMaskLocalSvg; + /** The polygon mask draw options */ draw; + /** Enables the polygon mask */ enable; + /** The polygon mask inline options */ inline; + /** The polygon mask move options */ move; + /** The polygon mask position */ position?: ICoordinates; + /** The polygon mask scale */ scale; + /** The polygon mask type */ type; + /** The polygon mask SVG url */ url?: string; constructor(pluginManager: PluginManager) { diff --git a/plugins/polygonMask/src/Options/Classes/PolygonMaskDraw.ts b/plugins/polygonMask/src/Options/Classes/PolygonMaskDraw.ts index 2ae1f360b4f..5494023149f 100644 --- a/plugins/polygonMask/src/Options/Classes/PolygonMaskDraw.ts +++ b/plugins/polygonMask/src/Options/Classes/PolygonMaskDraw.ts @@ -2,10 +2,11 @@ import { type IOptionLoader, type PluginManager, type RecursivePartial, isNull } import type { IPolygonMaskDraw } from "../Interfaces/IPolygonMaskDraw.js"; import { PolygonMaskDrawStroke } from "./PolygonMaskDrawStroke.js"; -/** - */ +/** The polygon mask draw options */ export class PolygonMaskDraw implements IPolygonMaskDraw, IOptionLoader { + /** Enables the polygon mask drawing */ enable; + /** The polygon mask draw stroke options */ stroke; constructor(pluginManager: PluginManager) { diff --git a/plugins/polygonMask/src/Options/Classes/PolygonMaskDrawStroke.ts b/plugins/polygonMask/src/Options/Classes/PolygonMaskDrawStroke.ts index 3377c94ccb2..1ac24cb1bbf 100644 --- a/plugins/polygonMask/src/Options/Classes/PolygonMaskDrawStroke.ts +++ b/plugins/polygonMask/src/Options/Classes/PolygonMaskDrawStroke.ts @@ -9,13 +9,16 @@ import { } from "@tsparticles/engine"; import type { IPolygonMaskDrawStroke } from "../Interfaces/IPolygonMaskDrawStroke.js"; -/** - */ +/** The polygon mask draw stroke options */ export class PolygonMaskDrawStroke implements IPolygonMaskDrawStroke, IOptionLoader { + /** The polygon mask draw stroke color */ color; + /** The polygon mask draw stroke opacity */ opacity; + /** The polygon mask draw stroke width */ width; + /** The plugin manager */ private readonly _pluginManager; constructor(pluginManager: PluginManager) { diff --git a/plugins/polygonMask/src/Options/Classes/PolygonMaskInline.ts b/plugins/polygonMask/src/Options/Classes/PolygonMaskInline.ts index eef9984e18d..3755c439f98 100644 --- a/plugins/polygonMask/src/Options/Classes/PolygonMaskInline.ts +++ b/plugins/polygonMask/src/Options/Classes/PolygonMaskInline.ts @@ -5,9 +5,9 @@ import { } from "../../Enums/PolygonMaskInlineArrangement.js"; import type { IPolygonMaskInline } from "../Interfaces/IPolygonMaskInline.js"; -/** - */ +/** The polygon mask inline options */ export class PolygonMaskInline implements IPolygonMaskInline, IOptionLoader { + /** The polygon mask inline arrangement */ arrangement: | PolygonMaskInlineArrangement | keyof typeof PolygonMaskInlineArrangement diff --git a/plugins/polygonMask/src/Options/Classes/PolygonMaskLocalSvg.ts b/plugins/polygonMask/src/Options/Classes/PolygonMaskLocalSvg.ts index f93431a8802..21f2dbaf0ab 100644 --- a/plugins/polygonMask/src/Options/Classes/PolygonMaskLocalSvg.ts +++ b/plugins/polygonMask/src/Options/Classes/PolygonMaskLocalSvg.ts @@ -7,10 +7,11 @@ import { } from "@tsparticles/engine"; import type { IPolygonMaskLocalSvg } from "../Interfaces/IPolygonMaskLocalSvg.js"; -/** - */ +/** The polygon mask local svg options */ export class PolygonMaskLocalSvg implements IPolygonMaskLocalSvg, IOptionLoader { + /** The svg path */ path: SingleOrMultiple; + /** The svg size */ size: IDimension; constructor() { diff --git a/plugins/polygonMask/src/Options/Classes/PolygonMaskMove.ts b/plugins/polygonMask/src/Options/Classes/PolygonMaskMove.ts index e5009af3fe3..4c22e4b9112 100644 --- a/plugins/polygonMask/src/Options/Classes/PolygonMaskMove.ts +++ b/plugins/polygonMask/src/Options/Classes/PolygonMaskMove.ts @@ -2,10 +2,11 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/ import type { IPolygonMaskMove } from "../Interfaces/IPolygonMaskMove.js"; import { PolygonMaskMoveType } from "../../Enums/PolygonMaskMoveType.js"; -/** - */ +/** The polygon mask move options */ export class PolygonMaskMove implements IPolygonMaskMove, IOptionLoader { + /** The polygon mask move radius */ radius; + /** The polygon mask move type */ type: PolygonMaskMoveType | keyof typeof PolygonMaskMoveType; constructor() { diff --git a/plugins/polygonMask/src/Options/Interfaces/IPolygonMask.ts b/plugins/polygonMask/src/Options/Interfaces/IPolygonMask.ts index b4c92f16603..20e84c27807 100644 --- a/plugins/polygonMask/src/Options/Interfaces/IPolygonMask.ts +++ b/plugins/polygonMask/src/Options/Interfaces/IPolygonMask.ts @@ -9,13 +9,22 @@ import type { PolygonMaskType } from "../../Enums/PolygonMaskType.js"; * [[include:Options/Plugins/PolygonMask.md]] */ export interface IPolygonMask { + /** The polygon mask SVG data */ data?: string | IPolygonMaskLocalSvg; + /** The polygon mask draw options */ draw: IPolygonMaskDraw; + /** Enables the polygon mask */ enable: boolean; + /** The polygon mask inline options */ inline: IPolygonMaskInline; + /** The polygon mask move options */ move: IPolygonMaskMove; + /** The polygon mask position */ position?: ICoordinates; + /** The polygon mask scale */ scale: number; + /** The polygon mask type */ type: PolygonMaskType; + /** The polygon mask SVG url */ url?: string; } diff --git a/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskDraw.ts b/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskDraw.ts index 100b57d839a..dd6f243b037 100644 --- a/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskDraw.ts +++ b/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskDraw.ts @@ -1,8 +1,9 @@ import type { IPolygonMaskDrawStroke } from "./IPolygonMaskDrawStroke.js"; -/** - */ +/** The polygon mask draw options */ export interface IPolygonMaskDraw { + /** Enables the polygon mask drawing */ enable: boolean; + /** The polygon mask draw stroke options */ stroke: IPolygonMaskDrawStroke; } diff --git a/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskDrawStroke.ts b/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskDrawStroke.ts index 7b1f14290b2..309f80f1dc1 100644 --- a/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskDrawStroke.ts +++ b/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskDrawStroke.ts @@ -1,9 +1,11 @@ import type { IOptionsColor } from "@tsparticles/engine"; -/** - */ +/** The polygon mask draw stroke options */ export interface IPolygonMaskDrawStroke { + /** The polygon mask draw stroke color */ color: string | IOptionsColor; + /** The polygon mask draw stroke opacity */ opacity: number; + /** The polygon mask draw stroke width */ width: number; } diff --git a/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskInline.ts b/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskInline.ts index 4e75909708f..703f53b8b29 100644 --- a/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskInline.ts +++ b/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskInline.ts @@ -3,9 +3,9 @@ import type { PolygonMaskInlineArrangementAlt, } from "../../Enums/PolygonMaskInlineArrangement.js"; -/** - */ +/** The polygon mask inline options */ export interface IPolygonMaskInline { + /** The polygon mask inline arrangement */ arrangement: | PolygonMaskInlineArrangement | keyof typeof PolygonMaskInlineArrangement diff --git a/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskLocalSvg.ts b/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskLocalSvg.ts index 6e82a745dbd..94b254e9bf6 100644 --- a/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskLocalSvg.ts +++ b/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskLocalSvg.ts @@ -1,8 +1,9 @@ import type { IDimension, SingleOrMultiple } from "@tsparticles/engine"; -/** - */ +/** The polygon mask local svg options */ export interface IPolygonMaskLocalSvg { + /** The svg path */ path: SingleOrMultiple; + /** The svg size */ size: IDimension; } diff --git a/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskMove.ts b/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskMove.ts index a0642c67f73..acf5024091c 100644 --- a/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskMove.ts +++ b/plugins/polygonMask/src/Options/Interfaces/IPolygonMaskMove.ts @@ -1,8 +1,9 @@ import type { PolygonMaskMoveType } from "../../Enums/PolygonMaskMoveType.js"; -/** - */ +/** The polygon mask move options */ export interface IPolygonMaskMove { + /** The polygon mask move radius */ radius: number; + /** The polygon mask move type */ type: PolygonMaskMoveType | keyof typeof PolygonMaskMoveType; } diff --git a/plugins/polygonMask/src/PolygonMaskInstance.ts b/plugins/polygonMask/src/PolygonMaskInstance.ts index beab99fe844..fc3bee32dbe 100644 --- a/plugins/polygonMask/src/PolygonMaskInstance.ts +++ b/plugins/polygonMask/src/PolygonMaskInstance.ts @@ -34,17 +34,31 @@ const noPolygonDataLoaded = `No polygon data loaded.`, * Polygon Mask manager */ export class PolygonMaskInstance implements IContainerPlugin { + /** The polygon mask dimensions */ dimension: IDimension; + /** The polygon mask offset */ offset?: ICoordinates; + /** The parsed SVG paths */ paths?: ISvgPath[]; + /** The raw polygon coordinates */ raw?: ICoordinates[]; + /** The redraw timeout handle */ redrawTimeout?: number; + /** The particles container */ private readonly _container; + /** The movement radius for inline particles */ private _moveRadius; + /** The plugin manager */ private readonly _pluginManager; + /** The scale factor */ private _scale; + /** + * Creates a new PolygonMaskInstance + * @param pluginManager - the plugin manager + * @param container - the polygon mask container + */ constructor(pluginManager: PluginManager, container: PolygonMaskContainer) { this._container = container; this._pluginManager = pluginManager; @@ -56,6 +70,11 @@ export class PolygonMaskInstance implements IContainerPlugin { this._scale = 1; } + /** + * Checks if a click position is valid inside the polygon + * @param position - the click position + * @returns true if the position is valid + */ clickPositionValid(position: ICoordinates): boolean { const options = this._container.actualOptions.polygon; @@ -67,6 +86,7 @@ export class PolygonMaskInstance implements IContainerPlugin { ); } + /** @inheritDoc */ draw(context: CanvasContextType): void { if (!this.paths?.length) { return; @@ -97,6 +117,7 @@ export class PolygonMaskInstance implements IContainerPlugin { } } + /** @inheritDoc */ async init(): Promise { const container = this._container, polygonMaskOptions = container.actualOptions.polygon, @@ -115,10 +136,12 @@ export class PolygonMaskInstance implements IContainerPlugin { } } + /** @inheritDoc */ particleBounce(particle: Particle, delta: IDelta, direction: OutModeDirection): boolean { return this._polygonBounce(particle, delta, direction); } + /** @inheritDoc */ particlePosition(position?: ICoordinates): ICoordinates | undefined { const options = this._container.actualOptions.polygon, defaultLength = 0; @@ -130,6 +153,7 @@ export class PolygonMaskInstance implements IContainerPlugin { return deepExtend({}, position ?? this._randomPoint()) as ICoordinates; } + /** @inheritDoc */ particlesInitialization(): boolean { const options = this._container.actualOptions.polygon; @@ -147,6 +171,7 @@ export class PolygonMaskInstance implements IContainerPlugin { return false; } + /** @inheritDoc */ resize(): void { const container = this._container, options = container.actualOptions.polygon; @@ -170,6 +195,7 @@ export class PolygonMaskInstance implements IContainerPlugin { }, timeout); } + /** @inheritDoc */ stop(): void { delete this.raw; delete this.paths; diff --git a/plugins/polygonMask/src/pathseg.d.ts b/plugins/polygonMask/src/pathseg.d.ts index 373592b3cf5..7a189e0ad6a 100644 --- a/plugins/polygonMask/src/pathseg.d.ts +++ b/plugins/polygonMask/src/pathseg.d.ts @@ -1,330 +1,551 @@ /* eslint-disable */ +/** Export value */ export interface SVGElementInstance extends EventTarget { + /** Correspondingelement value */ readonly correspondingElement: SVGElement; + /** Correspondinguseelement value */ readonly correspondingUseElement: SVGUseElement; } +/** Interface value */ interface SVGElementInstanceList { + /** Length value */ readonly length: number; + /** Item value */ item(index: number): SVGElementInstance; } +/** Interface value */ interface SVGPathSeg { + /** Pathsegtype value */ readonly pathSegType: number; + /** Pathsegtypeasletter value */ readonly pathSegTypeAsLetter: string; + /** Absolute arcto path segment type */ readonly PATHSEG_ARC_ABS: number; + /** Relative arcto path segment type */ readonly PATHSEG_ARC_REL: number; + /** Close path segment type */ readonly PATHSEG_CLOSEPATH: number; + /** Absolute cubic curveto path segment type */ readonly PATHSEG_CURVETO_CUBIC_ABS: number; + /** Relative cubic curveto path segment type */ readonly PATHSEG_CURVETO_CUBIC_REL: number; + /** Absolute smooth cubic curveto path segment type */ readonly PATHSEG_CURVETO_CUBIC_SMOOTH_ABS: number; + /** Relative smooth cubic curveto path segment type */ readonly PATHSEG_CURVETO_CUBIC_SMOOTH_REL: number; + /** Absolute quadratic curveto path segment type */ readonly PATHSEG_CURVETO_QUADRATIC_ABS: number; + /** Relative quadratic curveto path segment type */ readonly PATHSEG_CURVETO_QUADRATIC_REL: number; + /** Absolute smooth quadratic curveto path segment type */ readonly PATHSEG_CURVETO_QUADRATIC_SMOOTH_ABS: number; + /** Relative smooth quadratic curveto path segment type */ readonly PATHSEG_CURVETO_QUADRATIC_SMOOTH_REL: number; + /** Absolute lineto path segment type */ readonly PATHSEG_LINETO_ABS: number; + /** Absolute horizontal lineto path segment type */ readonly PATHSEG_LINETO_HORIZONTAL_ABS: number; + /** Relative horizontal lineto path segment type */ readonly PATHSEG_LINETO_HORIZONTAL_REL: number; + /** Relative lineto path segment type */ readonly PATHSEG_LINETO_REL: number; + /** Absolute vertical lineto path segment type */ readonly PATHSEG_LINETO_VERTICAL_ABS: number; + /** Relative vertical lineto path segment type */ readonly PATHSEG_LINETO_VERTICAL_REL: number; + /** Absolute moveto path segment type */ readonly PATHSEG_MOVETO_ABS: number; + /** Relative moveto path segment type */ readonly PATHSEG_MOVETO_REL: number; + /** Unknown path segment type */ readonly PATHSEG_UNKNOWN: number; } +/** Declare value */ declare var SVGPathSeg: { + /** Prototype value */ prototype: SVGPathSeg; + /** New value */ new (): SVGPathSeg; + /** Absolute arcto path segment type */ readonly PATHSEG_ARC_ABS: number; + /** Relative arcto path segment type */ readonly PATHSEG_ARC_REL: number; + /** Close path segment type */ readonly PATHSEG_CLOSEPATH: number; + /** Absolute cubic curveto path segment type */ readonly PATHSEG_CURVETO_CUBIC_ABS: number; + /** Relative cubic curveto path segment type */ readonly PATHSEG_CURVETO_CUBIC_REL: number; + /** Absolute smooth cubic curveto path segment type */ readonly PATHSEG_CURVETO_CUBIC_SMOOTH_ABS: number; + /** Relative smooth cubic curveto path segment type */ readonly PATHSEG_CURVETO_CUBIC_SMOOTH_REL: number; + /** Absolute quadratic curveto path segment type */ readonly PATHSEG_CURVETO_QUADRATIC_ABS: number; + /** Relative quadratic curveto path segment type */ readonly PATHSEG_CURVETO_QUADRATIC_REL: number; + /** Absolute smooth quadratic curveto path segment type */ readonly PATHSEG_CURVETO_QUADRATIC_SMOOTH_ABS: number; + /** Relative smooth quadratic curveto path segment type */ readonly PATHSEG_CURVETO_QUADRATIC_SMOOTH_REL: number; + /** Absolute lineto path segment type */ readonly PATHSEG_LINETO_ABS: number; + /** Absolute horizontal lineto path segment type */ readonly PATHSEG_LINETO_HORIZONTAL_ABS: number; + /** Relative horizontal lineto path segment type */ readonly PATHSEG_LINETO_HORIZONTAL_REL: number; + /** Relative lineto path segment type */ readonly PATHSEG_LINETO_REL: number; + /** Absolute vertical lineto path segment type */ readonly PATHSEG_LINETO_VERTICAL_ABS: number; + /** Relative vertical lineto path segment type */ readonly PATHSEG_LINETO_VERTICAL_REL: number; + /** Absolute moveto path segment type */ readonly PATHSEG_MOVETO_ABS: number; + /** Relative moveto path segment type */ readonly PATHSEG_MOVETO_REL: number; + /** Unknown path segment type */ readonly PATHSEG_UNKNOWN: number; }; +/** Interface value */ interface SVGPathSegArcAbs extends SVGPathSeg { + /** Angle value */ angle: number; + /** Largearcflag value */ largeArcFlag: boolean; + /** R1 value */ r1: number; + /** R2 value */ r2: number; + /** Sweepflag value */ sweepFlag: boolean; + /** X value */ x: number; + /** Y value */ y: number; } +/** Declare value */ declare var SVGPathSegArcAbs: { + /** Prototype value */ prototype: SVGPathSegArcAbs; + /** New value */ new (): SVGPathSegArcAbs; }; +/** Interface value */ interface SVGPathSegArcRel extends SVGPathSeg { + /** Angle value */ angle: number; + /** Largearcflag value */ largeArcFlag: boolean; + /** R1 value */ r1: number; + /** R2 value */ r2: number; + /** Sweepflag value */ sweepFlag: boolean; + /** X value */ x: number; + /** Y value */ y: number; } +/** Declare value */ declare var SVGPathSegArcRel: { + /** Prototype value */ prototype: SVGPathSegArcRel; + /** New value */ new (): SVGPathSegArcRel; }; +/** Type value */ type SVGPathSegClosePath = SVGPathSeg; +/** Declare value */ declare var SVGPathSegClosePath: { + /** Prototype value */ prototype: SVGPathSegClosePath; + /** New value */ new (): SVGPathSegClosePath; }; +/** Interface value */ interface SVGPathSegCurvetoCubicAbs extends SVGPathSeg { + /** X value */ x: number; + /** X1 value */ x1: number; + /** X2 value */ x2: number; + /** Y value */ y: number; + /** Y1 value */ y1: number; + /** Y2 value */ y2: number; } +/** Declare value */ declare var SVGPathSegCurvetoCubicAbs: { + /** Prototype value */ prototype: SVGPathSegCurvetoCubicAbs; + /** New value */ new (): SVGPathSegCurvetoCubicAbs; }; +/** Interface value */ interface SVGPathSegCurvetoCubicRel extends SVGPathSeg { + /** X value */ x: number; + /** X1 value */ x1: number; + /** X2 value */ x2: number; + /** Y value */ y: number; + /** Y1 value */ y1: number; + /** Y2 value */ y2: number; } +/** Declare value */ declare var SVGPathSegCurvetoCubicRel: { + /** Prototype value */ prototype: SVGPathSegCurvetoCubicRel; + /** New value */ new (): SVGPathSegCurvetoCubicRel; }; +/** Interface value */ interface SVGPathSegCurvetoCubicSmoothAbs extends SVGPathSeg { + /** X value */ x: number; + /** X2 value */ x2: number; + /** Y value */ y: number; + /** Y2 value */ y2: number; } +/** Declare value */ declare var SVGPathSegCurvetoCubicSmoothAbs: { + /** Prototype value */ prototype: SVGPathSegCurvetoCubicSmoothAbs; + /** New value */ new (): SVGPathSegCurvetoCubicSmoothAbs; }; +/** Interface value */ interface SVGPathSegCurvetoCubicSmoothRel extends SVGPathSeg { + /** X value */ x: number; + /** X2 value */ x2: number; + /** Y value */ y: number; + /** Y2 value */ y2: number; } +/** Declare value */ declare var SVGPathSegCurvetoCubicSmoothRel: { + /** Prototype value */ prototype: SVGPathSegCurvetoCubicSmoothRel; + /** New value */ new (): SVGPathSegCurvetoCubicSmoothRel; }; +/** Interface value */ interface SVGPathSegCurvetoQuadraticAbs extends SVGPathSeg { + /** X value */ x: number; + /** X1 value */ x1: number; + /** Y value */ y: number; + /** Y1 value */ y1: number; } +/** Declare value */ declare var SVGPathSegCurvetoQuadraticAbs: { + /** Prototype value */ prototype: SVGPathSegCurvetoQuadraticAbs; + /** New value */ new (): SVGPathSegCurvetoQuadraticAbs; }; +/** Interface value */ interface SVGPathSegCurvetoQuadraticRel extends SVGPathSeg { + /** X value */ x: number; + /** X1 value */ x1: number; + /** Y value */ y: number; + /** Y1 value */ y1: number; } +/** Declare value */ declare var SVGPathSegCurvetoQuadraticRel: { + /** Prototype value */ prototype: SVGPathSegCurvetoQuadraticRel; + /** New value */ new (): SVGPathSegCurvetoQuadraticRel; }; +/** Interface value */ interface SVGPathSegCurvetoQuadraticSmoothAbs extends SVGPathSeg { + /** X value */ x: number; + /** Y value */ y: number; } +/** Declare value */ declare var SVGPathSegCurvetoQuadraticSmoothAbs: { + /** Prototype value */ prototype: SVGPathSegCurvetoQuadraticSmoothAbs; + /** New value */ new (): SVGPathSegCurvetoQuadraticSmoothAbs; }; +/** Interface value */ interface SVGPathSegCurvetoQuadraticSmoothRel extends SVGPathSeg { + /** X value */ x: number; + /** Y value */ y: number; } +/** Declare value */ declare var SVGPathSegCurvetoQuadraticSmoothRel: { + /** Prototype value */ prototype: SVGPathSegCurvetoQuadraticSmoothRel; + /** New value */ new (): SVGPathSegCurvetoQuadraticSmoothRel; }; +/** Interface value */ interface SVGPathSegLinetoAbs extends SVGPathSeg { + /** X value */ x: number; + /** Y value */ y: number; } +/** Declare value */ declare var SVGPathSegLinetoAbs: { + /** Prototype value */ prototype: SVGPathSegLinetoAbs; + /** New value */ new (): SVGPathSegLinetoAbs; }; +/** Interface value */ interface SVGPathSegLinetoHorizontalAbs extends SVGPathSeg { + /** X value */ x: number; } +/** Declare value */ declare var SVGPathSegLinetoHorizontalAbs: { + /** Prototype value */ prototype: SVGPathSegLinetoHorizontalAbs; + /** New value */ new (): SVGPathSegLinetoHorizontalAbs; }; +/** Interface value */ interface SVGPathSegLinetoHorizontalRel extends SVGPathSeg { + /** X value */ x: number; } +/** Declare value */ declare var SVGPathSegLinetoHorizontalRel: { + /** Prototype value */ prototype: SVGPathSegLinetoHorizontalRel; + /** New value */ new (): SVGPathSegLinetoHorizontalRel; }; +/** Interface value */ interface SVGPathSegLinetoRel extends SVGPathSeg { + /** X value */ x: number; + /** Y value */ y: number; } +/** Declare value */ declare var SVGPathSegLinetoRel: { + /** Prototype value */ prototype: SVGPathSegLinetoRel; + /** New value */ new (): SVGPathSegLinetoRel; }; +/** Interface value */ interface SVGPathSegLinetoVerticalAbs extends SVGPathSeg { + /** Y value */ y: number; } +/** Declare value */ declare var SVGPathSegLinetoVerticalAbs: { + /** Prototype value */ prototype: SVGPathSegLinetoVerticalAbs; + /** New value */ new (): SVGPathSegLinetoVerticalAbs; }; +/** Interface value */ interface SVGPathSegLinetoVerticalRel extends SVGPathSeg { + /** Y value */ y: number; } +/** Declare value */ declare var SVGPathSegLinetoVerticalRel: { + /** Prototype value */ prototype: SVGPathSegLinetoVerticalRel; + /** New value */ new (): SVGPathSegLinetoVerticalRel; }; +/** Interface value */ interface SVGPathSegList { + /** Numberofitems value */ readonly numberOfItems: number; + /** Appenditem value */ appendItem(newItem: SVGPathSeg): SVGPathSeg; + /** Clear value */ clear(): void; + /** Getitem value */ getItem(index: number): SVGPathSeg; + /** Initialize value */ initialize(newItem: SVGPathSeg): SVGPathSeg; + /** Insertitembefore value */ insertItemBefore(newItem: SVGPathSeg, index: number): SVGPathSeg; + /** Removeitem value */ removeItem(index: number): SVGPathSeg; + /** Replaceitem value */ replaceItem(newItem: SVGPathSeg, index: number): SVGPathSeg; } +/** Declare value */ declare var SVGPathSegList: { + /** Prototype value */ prototype: SVGPathSegList; + /** New value */ new (): SVGPathSegList; }; +/** Interface value */ interface SVGPathSegMovetoAbs extends SVGPathSeg { + /** X value */ x: number; + /** Y value */ y: number; } +/** Declare value */ declare var SVGPathSegMovetoAbs: { + /** Prototype value */ prototype: SVGPathSegMovetoAbs; + /** New value */ new (): SVGPathSegMovetoAbs; }; +/** Interface value */ interface SVGPathSegMovetoRel extends SVGPathSeg { + /** X value */ x: number; + /** Y value */ y: number; } +/** Declare value */ declare var SVGPathSegMovetoRel: { + /** Prototype value */ prototype: SVGPathSegMovetoRel; + /** New value */ new (): SVGPathSegMovetoRel; }; +/** Interface value */ interface SVGZoomAndPan { + /** Zoomandpan value */ zoomAndPan: number; + /** Svg zoomandpan disable value */ readonly SVG_ZOOMANDPAN_DISABLE: number; + /** Svg zoomandpan magnify value */ readonly SVG_ZOOMANDPAN_MAGNIFY: number; + /** Svg zoomandpan unknown value */ readonly SVG_ZOOMANDPAN_UNKNOWN: number; } +/** Interface value */ interface SVGZoomEvent extends UIEvent { + /** Newscale value */ readonly newScale: number; + /** Newtranslate value */ readonly newTranslate: SVGPoint; + /** Previousscale value */ readonly previousScale: number; + /** Previoustranslate value */ readonly previousTranslate: SVGPoint; + /** Zoomrectscreen value */ readonly zoomRectScreen: SVGRect; } +/** Declare value */ declare var SVGZoomEvent: { + /** Prototype value */ prototype: SVGZoomEvent; + /** New value */ new (): SVGZoomEvent; }; +/** Interface value */ interface SVGPathElement extends SVGGraphicsElement { + /** Pathseglist value */ readonly pathSegList?: SVGPathSegList; + /** Getpointatlength value */ getPointAtLength(distance: number): SVGPoint; + /** Gettotallength value */ getTotalLength(): number; } +/** Declare value */ declare var SVGPathElement: { + /** Prototype value */ prototype: SVGPathElement; + /** New value */ new (): SVGPathElement; }; +/** Declare value */ declare global { + /** Var value */ var SVGPathSeg: SVGPathSeg; } diff --git a/plugins/polygonMask/src/types.ts b/plugins/polygonMask/src/types.ts index 9b16eadadb5..34fc6f71825 100644 --- a/plugins/polygonMask/src/types.ts +++ b/plugins/polygonMask/src/types.ts @@ -18,6 +18,7 @@ import type { import type { IPolygonMask } from "./Options/Interfaces/IPolygonMask.js"; import type { PolygonMask } from "./Options/Classes/PolygonMask.js"; +/** SVG path segment types with absolute coordinates */ export type SvgAbsoluteCoordinatesTypes = | SVGPathSegArcAbs | SVGPathSegCurvetoCubicAbs @@ -27,6 +28,7 @@ export type SvgAbsoluteCoordinatesTypes = | SVGPathSegLinetoAbs | SVGPathSegMovetoAbs; +/** SVG path segment types with relative coordinates */ export type SvgRelativeCoordinatesTypes = | SVGPathSegArcRel | SVGPathSegCurvetoCubicRel @@ -36,14 +38,17 @@ export type SvgRelativeCoordinatesTypes = | SVGPathSegLinetoRel | SVGPathSegMovetoRel; +/** Polygon mask plugin options interface */ export type IPolygonMaskOptions = IOptions & { polygon: IPolygonMask; }; +/** Polygon mask plugin options class */ export type PolygonMaskOptions = Options & { polygon?: PolygonMask; }; +/** Polygon mask container type */ export type PolygonMaskContainer = Container & { actualOptions: PolygonMaskOptions; }; diff --git a/plugins/responsive/src/Options/Interfaces/IResponsive.ts b/plugins/responsive/src/Options/Interfaces/IResponsive.ts index 166e6cdf4ec..6ef97972fcc 100644 --- a/plugins/responsive/src/Options/Interfaces/IResponsive.ts +++ b/plugins/responsive/src/Options/Interfaces/IResponsive.ts @@ -1,6 +1,7 @@ import type { ISourceOptions } from "@tsparticles/engine"; import type { ResponsiveMode } from "../../ResponsiveMode.js"; +/** The responsive options */ export interface IResponsive { /** * Maximum width of the canvas or the screen, depending on {@link mode} value. diff --git a/plugins/responsive/src/ResponsivePluginInstance.ts b/plugins/responsive/src/ResponsivePluginInstance.ts index 2587ff33354..4b68a41d190 100644 --- a/plugins/responsive/src/ResponsivePluginInstance.ts +++ b/plugins/responsive/src/ResponsivePluginInstance.ts @@ -2,8 +2,13 @@ import { type IContainerPlugin } from "@tsparticles/engine"; import type { ResponsiveContainer } from "./types.js"; export class ResponsivePluginInstance implements IContainerPlugin { + /** The responsive container */ private readonly _container; + /** + * Creates a new ResponsivePluginInstance + * @param container - the responsive container + */ constructor(container: ResponsiveContainer) { this._container = container; } diff --git a/plugins/sounds/src/Options/Classes/Sounds.ts b/plugins/sounds/src/Options/Classes/Sounds.ts index e3e64283555..bd251ff7d36 100644 --- a/plugins/sounds/src/Options/Classes/Sounds.ts +++ b/plugins/sounds/src/Options/Classes/Sounds.ts @@ -5,10 +5,15 @@ import { SoundsIcons } from "./SoundsIcons.js"; import { SoundsVolume } from "./SoundsVolume.js"; export class Sounds implements ISounds, IOptionLoader { + /** Enables auto play */ autoPlay: boolean; + /** Enables the sounds */ enable; + /** The sounds events */ events: SoundsEvent[]; + /** The sounds icons */ icons; + /** The sounds volume */ volume; constructor() { diff --git a/plugins/sounds/src/Options/Classes/SoundsEvent.ts b/plugins/sounds/src/Options/Classes/SoundsEvent.ts index 68a5f3f24bc..932172d9d5c 100644 --- a/plugins/sounds/src/Options/Classes/SoundsEvent.ts +++ b/plugins/sounds/src/Options/Classes/SoundsEvent.ts @@ -14,14 +14,19 @@ import { SoundsMelody } from "./SoundsMelody.js"; import { SoundsNote } from "./SoundsNote.js"; export class SoundsEvent implements ISoundsEvent, IOptionLoader { + /** The sounds event audio */ audio?: SingleOrMultiple; + /** The sounds event name */ event: SingleOrMultiple; + /** The sounds event filter */ filter?: FilterFunction; + /** The sounds event melodies */ melodies?: SoundsMelody[]; + /** The sounds event notes */ notes?: SoundsNote[]; constructor() { diff --git a/plugins/sounds/src/Options/Classes/SoundsVolume.ts b/plugins/sounds/src/Options/Classes/SoundsVolume.ts index 4a660fe97f0..b3df496fa1f 100644 --- a/plugins/sounds/src/Options/Classes/SoundsVolume.ts +++ b/plugins/sounds/src/Options/Classes/SoundsVolume.ts @@ -2,9 +2,13 @@ import { type IOptionLoader, type RecursivePartial, isNull, isObject } from "@ts import type { ISoundsVolume } from "../Interfaces/ISoundsVolume.js"; export class SoundsVolume implements ISoundsVolume, IOptionLoader { + /** The maximum volume */ max: number; + /** The minimum volume */ min: number; + /** The volume step */ step: number; + /** The default volume */ value: number; constructor() { diff --git a/plugins/sounds/src/Options/Interfaces/ISounds.ts b/plugins/sounds/src/Options/Interfaces/ISounds.ts index 09648ac1342..c6432d07cf5 100644 --- a/plugins/sounds/src/Options/Interfaces/ISounds.ts +++ b/plugins/sounds/src/Options/Interfaces/ISounds.ts @@ -2,14 +2,20 @@ import type { ISoundsEvent } from "./ISoundsEvent.js"; import type { ISoundsIcons } from "./ISoundsIcons.js"; import type { ISoundsVolume } from "./ISoundsVolume.js"; +/** The sounds options */ export interface ISounds { + /** Enables auto play */ autoPlay: boolean; + /** Enables the sounds */ enable: boolean; + /** The sounds events */ events: ISoundsEvent[]; + /** The sounds icons */ icons: ISoundsIcons; + /** The sounds volume */ volume: ISoundsVolume | number; } diff --git a/plugins/sounds/src/Options/Interfaces/ISoundsAudio.ts b/plugins/sounds/src/Options/Interfaces/ISoundsAudio.ts index d3806518aae..afb48f55634 100644 --- a/plugins/sounds/src/Options/Interfaces/ISoundsAudio.ts +++ b/plugins/sounds/src/Options/Interfaces/ISoundsAudio.ts @@ -1,4 +1,7 @@ +/** The sounds audio options */ export interface ISoundsAudio { + /** Enables audio loop */ loop: boolean; + /** The audio source */ source: string; } diff --git a/plugins/sounds/src/Options/Interfaces/ISoundsEvent.ts b/plugins/sounds/src/Options/Interfaces/ISoundsEvent.ts index f6522d835fa..c1d760182eb 100644 --- a/plugins/sounds/src/Options/Interfaces/ISoundsEvent.ts +++ b/plugins/sounds/src/Options/Interfaces/ISoundsEvent.ts @@ -4,14 +4,20 @@ import type { ISoundsMelody } from "./ISoundsMelody.js"; import type { ISoundsNote } from "./ISoundsNote.js"; import type { SingleOrMultiple } from "@tsparticles/engine"; +/** The sounds event options */ export interface ISoundsEvent { + /** The sounds event audio */ audio?: SingleOrMultiple; + /** The sounds event name */ event: SingleOrMultiple; + /** The sounds event filter */ filter?: string | FilterFunction; + /** The sounds event melodies */ melodies?: ISoundsMelody[]; + /** The sounds event notes */ notes?: ISoundsNote[]; } diff --git a/plugins/sounds/src/Options/Interfaces/ISoundsIcon.ts b/plugins/sounds/src/Options/Interfaces/ISoundsIcon.ts index 36cefef7f21..31775897ebd 100644 --- a/plugins/sounds/src/Options/Interfaces/ISoundsIcon.ts +++ b/plugins/sounds/src/Options/Interfaces/ISoundsIcon.ts @@ -1,7 +1,13 @@ +/** The sounds icon options */ export interface ISoundsIcon { + /** The icon height */ height: number; + /** The icon path */ path?: string; + /** The icon style */ style: string; + /** The icon svg */ svg?: string; + /** The icon width */ width: number; } diff --git a/plugins/sounds/src/Options/Interfaces/ISoundsIcons.ts b/plugins/sounds/src/Options/Interfaces/ISoundsIcons.ts index d6edbb29841..25d8a3d3295 100644 --- a/plugins/sounds/src/Options/Interfaces/ISoundsIcons.ts +++ b/plugins/sounds/src/Options/Interfaces/ISoundsIcons.ts @@ -1,9 +1,15 @@ import type { ISoundsIcon } from "./ISoundsIcon.js"; +/** The sounds icons options */ export interface ISoundsIcons { + /** Enables the sounds icons */ enable: boolean; + /** The mute icon */ mute: ISoundsIcon; + /** The unmute icon */ unmute: ISoundsIcon; + /** The volume down icon */ volumeDown: ISoundsIcon; + /** The volume up icon */ volumeUp: ISoundsIcon; } diff --git a/plugins/sounds/src/Options/Interfaces/ISoundsMelody.ts b/plugins/sounds/src/Options/Interfaces/ISoundsMelody.ts index 3607be8aa9b..390976497ad 100644 --- a/plugins/sounds/src/Options/Interfaces/ISoundsMelody.ts +++ b/plugins/sounds/src/Options/Interfaces/ISoundsMelody.ts @@ -1,7 +1,11 @@ import type { ISoundsNote } from "./ISoundsNote.js"; +/** The sounds melody options */ export interface ISoundsMelody { + /** Enables loop */ loop: boolean; + /** The nested melodies */ melodies: ISoundsMelody[]; + /** The melody notes */ notes: ISoundsNote[]; } diff --git a/plugins/sounds/src/Options/Interfaces/ISoundsNote.ts b/plugins/sounds/src/Options/Interfaces/ISoundsNote.ts index cdae28bac25..543ed541b52 100644 --- a/plugins/sounds/src/Options/Interfaces/ISoundsNote.ts +++ b/plugins/sounds/src/Options/Interfaces/ISoundsNote.ts @@ -1,7 +1,10 @@ import type { SingleOrMultiple } from "@tsparticles/engine"; +/** The sounds note options */ export interface ISoundsNote { + /** The note duration */ duration: number; + /** The note value */ value: SingleOrMultiple; } diff --git a/plugins/sounds/src/Options/Interfaces/ISoundsVolume.ts b/plugins/sounds/src/Options/Interfaces/ISoundsVolume.ts index e1d4b1f7ed7..15904e95587 100644 --- a/plugins/sounds/src/Options/Interfaces/ISoundsVolume.ts +++ b/plugins/sounds/src/Options/Interfaces/ISoundsVolume.ts @@ -1,6 +1,11 @@ +/** The sounds volume options */ export interface ISoundsVolume { + /** The maximum volume */ max: number; + /** The minimum volume */ min: number; + /** The volume step */ step: number; + /** The default volume */ value: number; } diff --git a/plugins/sounds/src/SoundsPluginInstance.ts b/plugins/sounds/src/SoundsPluginInstance.ts index fd14905cd67..58c18347af3 100644 --- a/plugins/sounds/src/SoundsPluginInstance.ts +++ b/plugins/sounds/src/SoundsPluginInstance.ts @@ -100,17 +100,32 @@ function setIconStyle( } export class SoundsPluginInstance implements IContainerPlugin { + /** Map of audio source URLs to decoded audio buffers */ private _audioMap: Map; + /** Array of active audio source nodes */ private readonly _audioSources: AudioScheduledSourceNode[]; + /** The particles container */ private readonly _container; + /** The particles engine */ private readonly _engine; + /** The gain node for volume control */ private _gain?: GainNode; + /** The mute icon image element */ private _muteImg?: HTMLImageElement; + /** The unmute icon image element */ private _unmuteImg?: HTMLImageElement; + /** The current volume level */ private _volume: number; + /** The volume down icon image element */ private _volumeDownImg?: HTMLImageElement; + /** The volume up icon image element */ private _volumeUpImg?: HTMLImageElement; + /** + * Creates a new SoundsPluginInstance + * @param container - the container using this plugin + * @param engine - the engine instance + */ constructor(container: SoundsContainer, engine: Engine) { this._container = container; this._engine = engine; @@ -119,6 +134,7 @@ export class SoundsPluginInstance implements IContainerPlugin { this._audioMap = new Map(); } + /** @inheritDoc */ async init(): Promise { const container = this._container, options = container.actualOptions, @@ -179,12 +195,14 @@ export class SoundsPluginInstance implements IContainerPlugin { } } + /** Mutes the audio */ async mute(): Promise { if (!this._container.muted) { await this.toggleMute(); } } + /** @inheritDoc */ async start(): Promise { const container = this._container, options = container.actualOptions, @@ -262,6 +280,7 @@ export class SoundsPluginInstance implements IContainerPlugin { } } + /** @inheritDoc */ stop(): void { this._container.muted = true; @@ -275,6 +294,7 @@ export class SoundsPluginInstance implements IContainerPlugin { })(); } + /** Toggles between mute and unmute */ async toggleMute(): Promise { const container = this._container; @@ -284,12 +304,14 @@ export class SoundsPluginInstance implements IContainerPlugin { await this._updateMuteStatus(); } + /** Unmutes the audio */ async unmute(): Promise { if (this._container.muted) { await this.toggleMute(); } } + /** Decreases the volume by the configured step */ async volumeDown(): Promise { const container = this._container, soundsOptions = container.actualOptions.sounds; @@ -307,6 +329,7 @@ export class SoundsPluginInstance implements IContainerPlugin { await this._updateVolume(); } + /** Increases the volume by the configured step */ async volumeUp(): Promise { const container = this._container, soundsOptions = container.actualOptions.sounds; diff --git a/plugins/sounds/src/types.ts b/plugins/sounds/src/types.ts index 9e8a32bf159..a1bde2b79cb 100644 --- a/plugins/sounds/src/types.ts +++ b/plugins/sounds/src/types.ts @@ -4,34 +4,55 @@ import type { ImageDisplay } from "./enums.js"; import type { Sounds } from "./Options/Classes/Sounds.js"; import type { SoundsIcon } from "./Options/Classes/SoundsIcon.js"; +/** Filter function for sound events */ export type FilterFunction = (args: CustomEventArgs) => boolean; +/** Sounds plugin options interface */ export type ISoundsOptions = IOptions & { + /** The sounds options */ sounds?: ISounds; }; +/** Sounds plugin options class */ export type SoundsOptions = Options & { + /** The sounds options */ sounds?: Sounds; }; +/** Sounds container with audio context */ export type SoundsContainer = Container & { + /** The actual sounds options */ actualOptions: SoundsOptions; + /** The audio context for sound playback */ audioContext?: AudioContext; + /** Whether the audio is muted */ muted?: boolean; }; +/** Image margins for sound icons */ export interface ImageMargins { + /** The right margin */ right: number; + /** The top margin */ top: number; } +/** Initialization data for sound icon images */ export interface InitImageData { + /** Click callback for the icon */ clickCb: () => Promise; + /** The sounds container */ container: SoundsContainer; + /** The image display type */ display: ImageDisplay; + /** The icon options */ iconOptions: SoundsIcon; + /** The icon margin */ margin: number; + /** The particles options */ options: Options; + /** The icon position */ pos: ImageMargins; + /** The right offsets for icon positioning */ rightOffsets: number[]; } diff --git a/plugins/themes/src/Options/Classes/Theme.ts b/plugins/themes/src/Options/Classes/Theme.ts index 81b6a85af2d..9f2a8f3f51f 100644 --- a/plugins/themes/src/Options/Classes/Theme.ts +++ b/plugins/themes/src/Options/Classes/Theme.ts @@ -9,8 +9,11 @@ import type { ITheme } from "../Interfaces/ITheme.js"; import { ThemeDefault } from "./ThemeDefault.js"; export class Theme implements ITheme, IOptionLoader { + /** Options to set the default theme */ readonly default; + /** Theme name, use it when changing theme */ name; + /** All options the theme will override */ options?: ISourceOptions; constructor() { diff --git a/plugins/themes/src/Options/Classes/ThemeDefault.ts b/plugins/themes/src/Options/Classes/ThemeDefault.ts index 2d0e18debba..9ba53a13437 100644 --- a/plugins/themes/src/Options/Classes/ThemeDefault.ts +++ b/plugins/themes/src/Options/Classes/ThemeDefault.ts @@ -3,8 +3,11 @@ import type { IThemeDefault } from "../Interfaces/IThemeDefault.js"; import { ThemeMode } from "../../ThemeMode.js"; export class ThemeDefault implements IThemeDefault, IOptionLoader { + /** If set to true, this theme will be switched when the mode matches the user OS theme */ auto; + /** Default theme mode */ mode: ThemeMode | keyof typeof ThemeMode; + /** Sets or unsets the default flag to this theme and mode */ value; constructor() { diff --git a/plugins/themes/src/ThemesPluginInstance.ts b/plugins/themes/src/ThemesPluginInstance.ts index e2a2f169e69..d6b1240047f 100644 --- a/plugins/themes/src/ThemesPluginInstance.ts +++ b/plugins/themes/src/ThemesPluginInstance.ts @@ -2,12 +2,18 @@ import { type IContainerPlugin, manageListener, safeMatchMedia } from "@tspartic import type { ThemesContainer } from "./types.js"; export class ThemesPluginInstance implements IContainerPlugin { + /** The themes container */ private readonly _container; + /** + * Creates a new ThemesPluginInstance + * @param container - the themes container + */ constructor(container: ThemesContainer) { this._container = container; } + /** @inheritDoc */ init(): Promise { const container = this._container; @@ -51,22 +57,29 @@ export class ThemesPluginInstance implements IContainerPlugin { return Promise.resolve(); } + /** + * Manages theme media query listeners + * @param add + */ manageListeners(add: boolean): void { const container = this._container; container.manageMediaMatch?.(add); } + /** @inheritDoc */ async start(): Promise { this.manageListeners(true); return Promise.resolve(); } + /** @inheritDoc */ stop(): void { this.manageListeners(false); } + /** @inheritDoc */ updateActualOptions(): boolean { const container = this._container; diff --git a/plugins/themes/src/types.ts b/plugins/themes/src/types.ts index e6b86af0d03..130fcffe006 100644 --- a/plugins/themes/src/types.ts +++ b/plugins/themes/src/types.ts @@ -3,28 +3,46 @@ import type { ITheme } from "./Options/Interfaces/ITheme.js"; import type { Theme } from "./Options/Classes/Theme.js"; import type { ThemeMode } from "./ThemeMode.js"; +/** Themes plugin options interface */ export type IThemesOptions = IOptions & { + /** The theme configurations */ themes?: ITheme[]; }; +/** Themes plugin options class */ export type ThemesOptions = Options & { + /** Finds the default theme for the given mode */ findDefaultTheme?: (mode: ThemeMode) => Theme | undefined; + /** Sets the active theme by name */ setTheme?: (name?: string) => void; + /** The array of theme configurations */ themes?: Theme[]; }; +/** Theme event listeners handlers */ export interface ThemeEventListenersHandlers { + /** Handler for the old-style theme change event */ readonly oldThemeChange: (this: MediaQueryList, ev: MediaQueryListEvent) => unknown; + /** Handler for the theme change event */ readonly themeChange: EventListenerOrEventListenerObject; } +/** Container with theme capabilities */ export type ThemesContainer = Container & { + /** The actual theme options */ actualOptions: ThemesOptions; + /** The currently active theme name */ currentTheme?: string; + /** Loads a theme by name */ loadTheme?: (name?: string) => Promise; + /** Manages media query listeners */ manageMediaMatch?: (add: boolean) => void; + /** The theme options */ options: ThemesOptions; + /** The theme change event handlers */ themeHandlers?: ThemeEventListenersHandlers; + /** The media query list for dark mode detection */ themeMatchMedia?: MediaQueryList; + /** The maximum width for responsive theme */ themesMaxWidth?: number; }; diff --git a/plugins/trail/src/Options/Classes/Trail.ts b/plugins/trail/src/Options/Classes/Trail.ts index 9e50a6118f2..0a4c7125754 100644 --- a/plugins/trail/src/Options/Classes/Trail.ts +++ b/plugins/trail/src/Options/Classes/Trail.ts @@ -5,8 +5,11 @@ import { TrailFill } from "./TrailFill.js"; /** */ export class Trail implements ITrail, IOptionLoader { + /** Enables the trail */ enable; + /** The trail fill options */ readonly fill; + /** The trail length */ length; constructor() { diff --git a/plugins/trail/src/Options/Interfaces/ITrail.ts b/plugins/trail/src/Options/Interfaces/ITrail.ts index 47d38d6267f..f215307ffe5 100644 --- a/plugins/trail/src/Options/Interfaces/ITrail.ts +++ b/plugins/trail/src/Options/Interfaces/ITrail.ts @@ -1,11 +1,13 @@ import type { ITrailFill } from "./ITrailFill.js"; -/** - */ +/** The trail mode options */ export interface ITrail { + /** Enables the trail */ enable: boolean; + /** The trail fill options */ fill: ITrailFill; + /** The trail length */ length: number; } diff --git a/plugins/trail/src/Options/Interfaces/ITrailFill.ts b/plugins/trail/src/Options/Interfaces/ITrailFill.ts index 9fe21522c9c..2bf965ab57f 100644 --- a/plugins/trail/src/Options/Interfaces/ITrailFill.ts +++ b/plugins/trail/src/Options/Interfaces/ITrailFill.ts @@ -1,6 +1,9 @@ import { type IOptionsColor } from "@tsparticles/engine"; +/** The trail fill options */ export interface ITrailFill { + /** The trail fill color */ color?: string | IOptionsColor; + /** The trail fill image */ image?: string; } diff --git a/plugins/trail/src/TrailPluginInstance.ts b/plugins/trail/src/TrailPluginInstance.ts index caa2e9ce36c..18584c738bd 100644 --- a/plugins/trail/src/TrailPluginInstance.ts +++ b/plugins/trail/src/TrailPluginInstance.ts @@ -12,17 +12,29 @@ import type { TrailContainer } from "./types.js"; const minimumLength = 0; +/** Trail fill data for rendering */ interface ITrailFillData { + /** The trail fill color */ color?: IRgb; + /** The trail fill image */ image?: HTMLImageElement; + /** The trail fill opacity */ opacity: number; } export class TrailPluginInstance implements IContainerPlugin { + /** The particles container */ private readonly _container; + /** The plugin manager */ private readonly _pluginManager; + /** The trail fill data */ private _trailFill?: ITrailFillData; + /** + * Creates a new TrailPluginInstance + * @param pluginManager - the plugin manager + * @param container - the trail container + */ constructor(pluginManager: PluginManager, container: TrailContainer) { this._container = container; this._pluginManager = pluginManager; diff --git a/plugins/zoom/src/Options/Classes/Zoom.ts b/plugins/zoom/src/Options/Classes/Zoom.ts index 254496fd474..1d8b1dc27d9 100644 --- a/plugins/zoom/src/Options/Classes/Zoom.ts +++ b/plugins/zoom/src/Options/Classes/Zoom.ts @@ -5,8 +5,11 @@ import type { IZoom } from "../Interfaces/IZoom.js"; const defaultZoom = 1; export class Zoom implements IZoom, IOptionLoader { + /** Enables or disables zoom interactions */ enable; + /** Maximum zoom level */ max; + /** Minimum zoom level */ min; constructor() { diff --git a/plugins/zoom/src/Options/Interfaces/IZoom.ts b/plugins/zoom/src/Options/Interfaces/IZoom.ts index fb11aa09e06..1073d7c324b 100644 --- a/plugins/zoom/src/Options/Interfaces/IZoom.ts +++ b/plugins/zoom/src/Options/Interfaces/IZoom.ts @@ -1,3 +1,4 @@ +/** The zoom mode options */ export interface IZoom { /** * Enables or disables zoom interactions. diff --git a/plugins/zoom/src/types.ts b/plugins/zoom/src/types.ts index e6e375348dc..4c648e0aa37 100644 --- a/plugins/zoom/src/types.ts +++ b/plugins/zoom/src/types.ts @@ -2,14 +2,17 @@ import type { Container, IOptions, Options } from "@tsparticles/engine"; import type { IZoom } from "./Options/Interfaces/IZoom.js"; import type { Zoom } from "./Options/Classes/Zoom.js"; +/** Zoom plugin options interface */ export type IZoomOptions = IOptions & { zoom?: IZoom; }; +/** Zoom plugin options class */ export type ZoomOptions = Options & { zoom?: Zoom; }; +/** Container with zoom capabilities */ export type ZoomContainer = Container & { actualOptions: ZoomOptions; }; diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5c9325280bf..af3dcbcd8ae 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -12434,9 +12434,6 @@ importers: typedoc-plugin-missing-exports: specifier: ^4.1.3 version: 4.1.3(typedoc@0.28.19(typescript@6.0.3)) - typedoc-vitepress-theme: - specifier: ^1.1.2 - version: 1.1.2(typedoc-plugin-markdown@4.11.0(typedoc@0.28.19(typescript@6.0.3))) vitepress: specifier: ^1.6.4 version: 1.6.4(@algolia/client-search@5.48.1)(@types/node@25.6.2)(@types/react@18.3.28)(axios@1.15.0)(fuse.js@7.3.0)(less@4.6.4)(lightningcss@1.32.0)(postcss@8.5.14)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(sass@1.99.0)(search-insights@2.17.3)(stylus@0.64.0)(terser@5.46.1)(typescript@6.0.3) @@ -40265,11 +40262,6 @@ packages: peerDependencies: typedoc: ^0.28.1 - typedoc-vitepress-theme@1.1.2: - resolution: {integrity: sha512-hQvCZRr5uKDqY1bRuY1+eNTNn6d4TE4OP5pnw65Y7WGgajkJW9X1/lVJK2UJpcwCmwkdjw1QIO49H9JQlxWhhw==} - peerDependencies: - typedoc-plugin-markdown: '>=4.4.0' - typedoc@0.28.19: resolution: {integrity: sha512-wKh+lhdmMFivMlc6vRRcMGXeGEHGU2g8a2CkPTJjJlwRf1iXbimWIPcFolCqe4E0d/FRtGszpIrsp3WLpDB8Pw==} engines: {node: '>= 18', pnpm: '>= 10'} @@ -79945,10 +79937,6 @@ snapshots: dependencies: typedoc: 0.28.19(typescript@6.0.3) - typedoc-vitepress-theme@1.1.2(typedoc-plugin-markdown@4.11.0(typedoc@0.28.19(typescript@6.0.3))): - dependencies: - typedoc-plugin-markdown: 4.11.0(typedoc@0.28.19(typescript@6.0.3)) - typedoc@0.28.19(typescript@6.0.3): dependencies: '@gerrit0/mini-shiki': 3.23.0 diff --git a/shapes/arrow/src/ArrowDrawer.ts b/shapes/arrow/src/ArrowDrawer.ts index 11ade10c197..97effc41e2e 100644 --- a/shapes/arrow/src/ArrowDrawer.ts +++ b/shapes/arrow/src/ArrowDrawer.ts @@ -6,11 +6,21 @@ const defaultHeightFactor = 0.5, defaultHeadWidthFactor = 0.2, defaultBodyHeightFactor = 0.5; +/** Arrow shape drawer plugin */ export class ArrowDrawer implements IShapeDrawer { + /** + * Draws the arrow shape + * @param data + */ draw(data: IShapeDrawData): void { drawArrow(data); } + /** + * Initializes arrow-specific particle properties + * @param _container + * @param particle + */ particleInit(_container: Container, particle: ArrowParticle): void { const shapeData = particle.shapeData; diff --git a/shapes/cards/src/CardValue.ts b/shapes/cards/src/CardValue.ts index 3c3a4917fe6..b03ad1057eb 100644 --- a/shapes/cards/src/CardValue.ts +++ b/shapes/cards/src/CardValue.ts @@ -1,15 +1,29 @@ +/** Card playing card values */ export enum CardValue { + /** Ace */ ace = "A", + /** Two */ two = "2", + /** Three */ three = "3", + /** Four */ four = "4", + /** Five */ five = "5", + /** Six */ six = "6", + /** Seven */ seven = "7", + /** Eight */ eight = "8", + /** Nine */ nine = "9", + /** Ten */ ten = "10", + /** Jack */ jack = "J", + /** Queen */ queen = "Q", + /** King */ king = "K", } diff --git a/shapes/cards/src/cards/CardDrawer.ts b/shapes/cards/src/cards/CardDrawer.ts index 3762b7ca1bc..8295550b3ef 100644 --- a/shapes/cards/src/cards/CardDrawer.ts +++ b/shapes/cards/src/cards/CardDrawer.ts @@ -3,13 +3,23 @@ import type { CardParticle } from "../CardParticle.js"; import type { ICardData } from "../ICardData.js"; import { drawRoundedCard } from "../utils.js"; +/** Card drawer plugin */ export class CardDrawer implements IShapeDrawer { + /** The particles container */ private readonly _container; + /** + * CardDrawer constructor + * @param container + */ constructor(container: Container) { this._container = container; } + /** + * Draws the card shape + * @param data + */ draw(data: IShapeDrawData): void { const { context, particle, opacity, radius } = data; @@ -34,6 +44,11 @@ export class CardDrawer implements IShapeDrawer { context.globalAlpha = defaultOpacity; } + /** + * Initializes the card shape on the particle + * @param _container + * @param particle + */ particleInit(_container: Container, particle: CardParticle): void { const shape = particle.shapeData; diff --git a/shapes/circle/src/CircleDrawer.ts b/shapes/circle/src/CircleDrawer.ts index 3375b8cf947..6da507f0222 100644 --- a/shapes/circle/src/CircleDrawer.ts +++ b/shapes/circle/src/CircleDrawer.ts @@ -7,17 +7,26 @@ const sides = 12, maxAngle = 360, minAngle = 0; -/** - */ +/** Circle shape drawer plugin */ export class CircleDrawer implements IShapeDrawer { + /** + * Draws the circle shape + * @param data + */ draw(data: IShapeDrawData): void { drawCircle(data); } + /** Gets the number of sides for this shape */ getSidesCount(): number { return sides; } + /** + * Initializes circle-specific particle properties + * @param _container + * @param particle + */ particleInit(_container: Container, particle: CircleParticle): void { const shapeData = particle.shapeData as ICircleShapeData | undefined, angle = shapeData?.angle ?? { diff --git a/shapes/cog/src/CogDrawer.ts b/shapes/cog/src/CogDrawer.ts index 759677c8626..a98076138ef 100644 --- a/shapes/cog/src/CogDrawer.ts +++ b/shapes/cog/src/CogDrawer.ts @@ -8,15 +8,29 @@ const defaultHoleRadius = 44, defaultNotches = 7, defaultOuterTaper = 50; +/** Cog shape drawer plugin */ export class CogDrawer implements IShapeDrawer { + /** + * Draws the cog hole after the main shape + * @param data + */ afterDraw(data: IShapeDrawData): void { drawCogHole(data); } + /** + * Draws the cog shape + * @param data + */ draw(data: IShapeDrawData): void { drawCog(data); } + /** + * Initializes cog-specific particle properties + * @param _container + * @param particle + */ particleInit(_container: Container, particle: CogParticle): void { const shapeData = particle.shapeData; diff --git a/shapes/emoji/src/EmojiDrawer.ts b/shapes/emoji/src/EmojiDrawer.ts index b02464f1657..e50f4168171 100644 --- a/shapes/emoji/src/EmojiDrawer.ts +++ b/shapes/emoji/src/EmojiDrawer.ts @@ -20,9 +20,12 @@ const defaultFont = '"Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", noPadding = 0, firstItem = 0; +/** Emoji shape drawer plugin */ export class EmojiDrawer implements IShapeDrawer { + /** Cached emoji renderings mapped by value and font */ private readonly _emojiShapeDict: Map = new Map(); + /** Clears the emoji cache */ destroy(): void { for (const [key, data] of this._emojiShapeDict) { if (data instanceof ImageBitmap) { @@ -33,6 +36,10 @@ export class EmojiDrawer implements IShapeDrawer { } } + /** + * Draws the emoji shape + * @param data + */ draw(data: IShapeDrawData): void { const key = data.particle.emojiDataKey; @@ -49,6 +56,10 @@ export class EmojiDrawer implements IShapeDrawer { drawEmoji(data, image); } + /** + * Loads the required emoji fonts + * @param container + */ async init(container: Container): Promise { const options = container.actualOptions, shapeData = options.particles.shape; @@ -69,10 +80,19 @@ export class EmojiDrawer implements IShapeDrawer { await Promise.all(promises); } + /** + * Cleans up emoji data when particle is destroyed + * @param particle + */ particleDestroy(particle: EmojiParticle): void { particle.emojiDataKey = undefined; } + /** + * Initializes the emoji shape for a particle + * @param container + * @param particle + */ particleInit(container: Container, particle: EmojiParticle): void { const shapeData = particle.shapeData as unknown as IEmojiShape; diff --git a/shapes/emoji/src/IEmojiShape.ts b/shapes/emoji/src/IEmojiShape.ts index 9e8d9120a4d..fca6b5a37be 100644 --- a/shapes/emoji/src/IEmojiShape.ts +++ b/shapes/emoji/src/IEmojiShape.ts @@ -1,13 +1,21 @@ import type { IShapeValues, SingleOrMultiple } from "@tsparticles/engine"; +/** Single emoji shape options */ export interface ISingleEmojiShape { + /** Emoji font family */ font?: string; + /** Emoji padding */ padding?: number; + /** Emoji character value */ value: string; } +/** Emoji shape options */ export interface IEmojiShape extends IShapeValues { + /** Emoji font family */ font?: string; + /** Emoji padding */ padding?: number; + /** Emoji value, single or multiple */ value: SingleOrMultiple; } diff --git a/shapes/heart/src/HeartDrawer.ts b/shapes/heart/src/HeartDrawer.ts index d75f51b1dfe..e30416e228b 100644 --- a/shapes/heart/src/HeartDrawer.ts +++ b/shapes/heart/src/HeartDrawer.ts @@ -1,7 +1,12 @@ import type { IShapeDrawData, IShapeDrawer } from "@tsparticles/engine"; import { drawHeart } from "./Utils.js"; +/** Heart shape drawer plugin */ export class HeartDrawer implements IShapeDrawer { + /** + * Draws the heart shape + * @param data + */ draw(data: IShapeDrawData): void { drawHeart(data); } diff --git a/shapes/image/src/Options/Interfaces/IPreload.ts b/shapes/image/src/Options/Interfaces/IPreload.ts index d5d49125ba4..63dbbc7be79 100644 --- a/shapes/image/src/Options/Interfaces/IPreload.ts +++ b/shapes/image/src/Options/Interfaces/IPreload.ts @@ -1,8 +1,15 @@ +/** The preload image options */ export interface IPreload { + /** Enables gif support */ gif: boolean; + /** The image height */ height?: number; + /** The image name */ name?: string; + /** Replace the color with the particle color */ replaceColor?: boolean; + /** The image source */ src: string; + /** The image width */ width?: number; } diff --git a/shapes/image/src/Utils.ts b/shapes/image/src/Utils.ts index acb905e592d..b71de1bc50f 100644 --- a/shapes/image/src/Utils.ts +++ b/shapes/image/src/Utils.ts @@ -2,6 +2,7 @@ import { type IHsl, type Particle, getLogger, getStyleFromHsl } from "@tsparticl import type { GIF } from "./GifUtils/Types/GIF.js"; import type { IImageShape } from "./IImageShape.js"; +/** Image shape types */ export const shapeTypes = ["image", "images"]; const stringStart = 0, diff --git a/shapes/infinity/src/InfinityDrawer.ts b/shapes/infinity/src/InfinityDrawer.ts index 2ccc703b1e8..ccc60946ceb 100644 --- a/shapes/infinity/src/InfinityDrawer.ts +++ b/shapes/infinity/src/InfinityDrawer.ts @@ -1,7 +1,12 @@ import { type IShapeDrawData, type IShapeDrawer } from "@tsparticles/engine"; import { drawInfinity } from "./Utils.js"; +/** Infinity shape drawer plugin */ export class InfinityDrawer implements IShapeDrawer { + /** + * Draws the infinity shape + * @param data + */ draw(data: IShapeDrawData): void { drawInfinity(data); } diff --git a/shapes/line/src/LineDrawer.ts b/shapes/line/src/LineDrawer.ts index e9edf5d4d63..a85293037b5 100644 --- a/shapes/line/src/LineDrawer.ts +++ b/shapes/line/src/LineDrawer.ts @@ -3,13 +3,17 @@ import { drawLine } from "./Utils.js"; const sides = 1; -/** - */ +/** Line shape drawer plugin */ export class LineDrawer implements IShapeDrawer { + /** + * Draws the line shape + * @param data + */ draw(data: IShapeDrawData): void { drawLine(data); } + /** Gets the number of sides for this shape */ getSidesCount(): number { return sides; } diff --git a/shapes/matrix/src/MatrixDrawer.ts b/shapes/matrix/src/MatrixDrawer.ts index 603c2bee94a..982ebb24557 100644 --- a/shapes/matrix/src/MatrixDrawer.ts +++ b/shapes/matrix/src/MatrixDrawer.ts @@ -2,7 +2,12 @@ import type { IShapeDrawData, IShapeDrawer } from "@tsparticles/engine"; import type { MatrixParticle } from "./MatrixParticle.js"; import { drawMatrix } from "./Utils.js"; +/** Matrix shape drawer plugin */ export class MatrixDrawer implements IShapeDrawer { + /** + * Draws the matrix character shape + * @param data + */ draw(data: IShapeDrawData): void { drawMatrix(data); } diff --git a/shapes/path/src/PathDrawer.ts b/shapes/path/src/PathDrawer.ts index cc098ea0954..985e10c6a3f 100644 --- a/shapes/path/src/PathDrawer.ts +++ b/shapes/path/src/PathDrawer.ts @@ -3,7 +3,12 @@ import type { IShapePathData } from "./IShapePathData.js"; import type { PathParticle } from "./PathParticle.js"; import { drawPath } from "@tsparticles/path-utils"; +/** SVG path shape drawer plugin */ export class PathDrawer implements IShapeDrawer { + /** + * Draws the SVG path shape + * @param data + */ draw(data: IShapeDrawData): void { const { context, particle, radius } = data; @@ -14,6 +19,11 @@ export class PathDrawer implements IShapeDrawer { drawPath(context, radius, particle.pathData); } + /** + * Initializes the path data for the particle + * @param _container + * @param particle + */ particleInit(_container: Container, particle: PathParticle): void { const shape = particle.shapeData as IShapePathData | undefined; diff --git a/shapes/polygon/src/PolygonDrawer.ts b/shapes/polygon/src/PolygonDrawer.ts index 0eb57be1b86..27ec39edddc 100644 --- a/shapes/polygon/src/PolygonDrawer.ts +++ b/shapes/polygon/src/PolygonDrawer.ts @@ -5,9 +5,13 @@ import { PolygonDrawerBase } from "./PolygonDrawerBase.js"; const yFactor = 2.66, sidesFactor = 3; -/** - */ +/** Polygon shape drawer plugin */ export class PolygonDrawer extends PolygonDrawerBase { + /** + * Gets the side data for the polygon + * @param particle + * @param radius + */ getSidesData(particle: Particle, radius: number): ISide { const { sides } = particle; diff --git a/shapes/polygon/src/PolygonDrawerBase.ts b/shapes/polygon/src/PolygonDrawerBase.ts index ff97d4d681f..558a607ccb7 100644 --- a/shapes/polygon/src/PolygonDrawerBase.ts +++ b/shapes/polygon/src/PolygonDrawerBase.ts @@ -5,9 +5,12 @@ import { drawPolygon } from "./Utils.js"; const defaultSides = 5; -/** - */ +/** Base class for polygon-based shape drawers */ export abstract class PolygonDrawerBase implements IShapeDrawer { + /** + * Draws the polygon shape + * @param data + */ draw(data: IShapeDrawData): void { const { particle, radius } = data, side = this.getSidesData(particle, radius); @@ -15,11 +18,16 @@ export abstract class PolygonDrawerBase implements IShapeDrawer { drawPolygon(data, side); } + /** + * Gets the number of sides for the polygon + * @param particle + */ getSidesCount(particle: Particle): number { const polygon = particle.shapeData as IPolygonShape | undefined; return Math.round(getRangeValue(polygon?.sides ?? defaultSides)); } + /** Gets the side data for computing polygon vertices */ abstract getSidesData(particle: Particle, radius: number): ISide; } diff --git a/shapes/polygon/src/TriangleDrawer.ts b/shapes/polygon/src/TriangleDrawer.ts index 9a7db8c7388..0c5cf25326f 100644 --- a/shapes/polygon/src/TriangleDrawer.ts +++ b/shapes/polygon/src/TriangleDrawer.ts @@ -6,13 +6,18 @@ const sides = 3, yFactor = 2.66, sidesFactor = 3; -/** - */ +/** Triangle shape drawer plugin */ export class TriangleDrawer extends PolygonDrawerBase { + /** Gets the sides count for a triangle */ override getSidesCount(): number { return sides; } + /** + * Gets the side data for the triangle + * @param _particle + * @param radius + */ getSidesData(_particle: Particle, radius: number): ISide { return { count: { diff --git a/shapes/rounded-polygon/src/RoundedPolygonDrawer.ts b/shapes/rounded-polygon/src/RoundedPolygonDrawer.ts index b9f9b0e18c8..70e94bca7c1 100644 --- a/shapes/rounded-polygon/src/RoundedPolygonDrawer.ts +++ b/shapes/rounded-polygon/src/RoundedPolygonDrawer.ts @@ -5,21 +5,33 @@ import type { RoundedParticle } from "./RoundedParticle.js"; const defaultSides = 5, defaultRadius = 5; -/** - */ +/** Rounded polygon shape drawer plugin */ export class RoundedPolygonDrawer implements IShapeDrawer { + /** + * Draws the rounded polygon shape + * @param data + */ draw(data: IShapeDrawData): void { const { context, particle, radius } = data; roundedPath(context, polygon(particle.sides, radius), particle.borderRadius ?? defaultRadius); } + /** + * Gets the number of sides + * @param particle + */ getSidesCount(particle: RoundedParticle): number { const roundedPolygon = particle.shapeData; return Math.round(getRangeValue(roundedPolygon?.sides ?? defaultSides)); } + /** + * Initializes the rounded polygon particle properties + * @param container + * @param particle + */ particleInit(container: Container, particle: RoundedParticle): void { const shapeData = particle.shapeData; diff --git a/shapes/rounded-rect/src/RoundedRectDrawer.ts b/shapes/rounded-rect/src/RoundedRectDrawer.ts index 6fdd775942f..14d939d2a3c 100644 --- a/shapes/rounded-rect/src/RoundedRectDrawer.ts +++ b/shapes/rounded-rect/src/RoundedRectDrawer.ts @@ -4,7 +4,12 @@ import { drawRoundedRect } from "./Utils.js"; const defaultRadius = 5; +/** Rounded rectangle shape drawer plugin */ export class RoundedRectDrawer implements IShapeDrawer { + /** + * Draws the rounded rectangle shape + * @param data + */ draw(data: IShapeDrawData): void { const { context, particle, radius } = data, fixedRadius = radius * Math.SQRT1_2, @@ -18,6 +23,11 @@ export class RoundedRectDrawer implements IShapeDrawer { } } + /** + * Initializes the rounded rectangle particle properties + * @param container + * @param particle + */ particleInit(container: Container, particle: RoundedParticle): void { const shapeData = particle.shapeData; diff --git a/shapes/spiral/src/SpiralDrawer.ts b/shapes/spiral/src/SpiralDrawer.ts index 7f0d10cb7b9..551899ff3b2 100644 --- a/shapes/spiral/src/SpiralDrawer.ts +++ b/shapes/spiral/src/SpiralDrawer.ts @@ -6,11 +6,21 @@ const defaultInnerRadius = 1, defaultLineSpacing = 1, defaultWidthFactor = 10; +/** Spiral shape drawer plugin */ export class SpiralDrawer implements IShapeDrawer { + /** + * Draws the spiral shape + * @param data + */ draw(data: IShapeDrawData): void { drawSpiral(data); } + /** + * Initializes spiral-specific particle properties + * @param container + * @param particle + */ particleInit(container: Container, particle: SpiralParticle): void { const pixelRatio = container.retina.pixelRatio, shapeData = particle.shapeData; diff --git a/shapes/square/src/SquareDrawer.ts b/shapes/square/src/SquareDrawer.ts index 126512deeb5..d39dbfec3a1 100644 --- a/shapes/square/src/SquareDrawer.ts +++ b/shapes/square/src/SquareDrawer.ts @@ -3,13 +3,17 @@ import { drawSquare } from "./Utils.js"; const sides = 4; -/** - */ +/** Square shape drawer plugin */ export class SquareDrawer implements IShapeDrawer { + /** + * Draws the square shape + * @param data + */ draw(data: IShapeDrawData): void { drawSquare(data); } + /** Gets the number of sides for this shape */ getSidesCount(): number { return sides; } diff --git a/shapes/squircle/src/SquircleDrawer.ts b/shapes/squircle/src/SquircleDrawer.ts index f0135d3cffc..2f14b3e5751 100644 --- a/shapes/squircle/src/SquircleDrawer.ts +++ b/shapes/squircle/src/SquircleDrawer.ts @@ -2,11 +2,21 @@ import { type Container, type IShapeDrawData, type IShapeDrawer, getRangeValue } import { defaultExponent, defaultSteps, drawSquircle } from "./Utils.js"; import type { SquircleParticle } from "./SquircleParticle.js"; +/** Squircle shape drawer plugin */ export class SquircleDrawer implements IShapeDrawer { + /** + * Draws the squircle shape + * @param data + */ draw(data: IShapeDrawData): void { drawSquircle(data); } + /** + * Initializes squircle-specific particle properties + * @param _container + * @param particle + */ particleInit(_container: Container, particle: SquircleParticle): void { const shapeData = particle.shapeData; diff --git a/shapes/star/src/StarDrawer.ts b/shapes/star/src/StarDrawer.ts index 19136920889..efcb907b0e8 100644 --- a/shapes/star/src/StarDrawer.ts +++ b/shapes/star/src/StarDrawer.ts @@ -12,19 +12,31 @@ import { drawStar } from "./Utils.js"; const defaultInset = 2, defaultSides = 5; -/** - */ +/** Star shape drawer plugin */ export class StarDrawer implements IShapeDrawer { + /** + * Draws the star shape + * @param data + */ draw(data: IShapeDrawData): void { drawStar(data); } + /** + * Gets the number of sides for this shape + * @param particle + */ getSidesCount(particle: Particle): number { const star = particle.shapeData as IStarShape | undefined; return Math.round(getRangeValue(star?.sides ?? defaultSides)); } + /** + * Initializes the star inset for the particle + * @param _container + * @param particle + */ particleInit(_container: Container, particle: StarParticle): void { const star = particle.shapeData as IStarShape | undefined; diff --git a/shapes/text/src/TextDrawer.ts b/shapes/text/src/TextDrawer.ts index c41f07244af..f6d1bf12dda 100644 --- a/shapes/text/src/TextDrawer.ts +++ b/shapes/text/src/TextDrawer.ts @@ -19,10 +19,18 @@ const firstIndex = 0, * Multiline text drawer */ export class TextDrawer implements IShapeDrawer { + /** + * Draws the text shape + * @param data + */ draw(data: IShapeDrawData): void { drawText(data); } + /** + * Loads the required fonts + * @param container + */ async init(container: Container): Promise { const options = container.actualOptions; diff --git a/updaters/destroy/src/DestroyUpdater.ts b/updaters/destroy/src/DestroyUpdater.ts index 90d6ea0dfa0..74c2e9f0a25 100644 --- a/updaters/destroy/src/DestroyUpdater.ts +++ b/updaters/destroy/src/DestroyUpdater.ts @@ -18,15 +18,27 @@ const defaultDeltaFactor = 1, minExplodeSpeed = 0.01, maxExplodeProgress = 1; +/** Destroy updater plugin */ export class DestroyUpdater implements IParticleUpdater { + /** The particles container */ private readonly _container; + /** The plugin manager */ private readonly _pluginManager; + /** + * DestroyUpdater constructor + * @param pluginManager + * @param container + */ constructor(pluginManager: PluginManager, container: Container) { this._container = container; this._pluginManager = pluginManager; } + /** + * Initializes destroy-related particle properties + * @param particle + */ init(particle: DestroyParticle): void { const container = this._container, particlesOptions = particle.options, @@ -65,12 +77,21 @@ export class DestroyUpdater implements IParticleUpdater { } } + /** + * Checks if the particle needs destroy handling + * @param particle + */ isEnabled(particle: Particle): boolean { const destroyParticle = particle as DestroyParticle; return !destroyParticle.destroyed || !!destroyParticle.exploding; } + /** + * Loads the destroy options + * @param options + * @param sources + */ loadOptions( options: DestroyParticlesOptions, ...sources: (RecursivePartial | undefined)[] @@ -82,6 +103,11 @@ export class DestroyUpdater implements IParticleUpdater { } } + /** + * Handles particle destruction (split or explode) + * @param particle + * @param override + */ particleDestroyed(particle: DestroyParticle, override?: boolean): void { if (override) { return; @@ -126,6 +152,11 @@ export class DestroyUpdater implements IParticleUpdater { } } + /** + * Updates particle destruction state + * @param particle + * @param delta + */ update(particle: DestroyParticle, delta: IDelta): void { if (particle.exploding) { const explosionState = particle.exploding, diff --git a/updaters/destroy/src/Options/Classes/Destroy.ts b/updaters/destroy/src/Options/Classes/Destroy.ts index 7192bfca619..d793d5364a3 100644 --- a/updaters/destroy/src/Options/Classes/Destroy.ts +++ b/updaters/destroy/src/Options/Classes/Destroy.ts @@ -5,12 +5,18 @@ import { Explode } from "./Explode.js"; import type { IDestroy } from "../Interfaces/IDestroy.js"; import { Split } from "./Split.js"; +/** Destroy options class */ export class Destroy implements IDestroy, IOptionLoader { + /** The destroy bounds */ bounds: DestroyBounds; + /** The explode options */ explode: Explode; + /** The destroy mode */ mode: DestroyMode | keyof typeof DestroyMode; + /** The split options */ split: Split; + /** Destroy constructor */ constructor() { this.bounds = new DestroyBounds(); this.explode = new Explode(); @@ -18,6 +24,10 @@ export class Destroy implements IDestroy, IOptionLoader { this.split = new Split(); } + /** + * Loads the destroy options from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/destroy/src/Options/Classes/DestroyBounds.ts b/updaters/destroy/src/Options/Classes/DestroyBounds.ts index cfc5ff8b3ac..33feb7fff8f 100644 --- a/updaters/destroy/src/Options/Classes/DestroyBounds.ts +++ b/updaters/destroy/src/Options/Classes/DestroyBounds.ts @@ -1,12 +1,21 @@ import { type IOptionLoader, type RangeValue, type RecursivePartial, isNull, setRangeValue } from "@tsparticles/engine"; import type { IDestroyBounds } from "../Interfaces/IDestroyBounds.js"; +/** Destroy bounds options class */ export class DestroyBounds implements IDestroyBounds, IOptionLoader { + /** Bottom bound */ bottom?: RangeValue; + /** Left bound */ left?: RangeValue; + /** Right bound */ right?: RangeValue; + /** Top bound */ top?: RangeValue; + /** + * Loads the destroy bounds from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/destroy/src/Options/Classes/Explode.ts b/updaters/destroy/src/Options/Classes/Explode.ts index a811e34ba0d..93bd3e62d2e 100644 --- a/updaters/destroy/src/Options/Classes/Explode.ts +++ b/updaters/destroy/src/Options/Classes/Explode.ts @@ -1,15 +1,23 @@ import { type IOptionLoader, type RecursivePartial, isNull } from "@tsparticles/engine"; import type { IExplode } from "../Interfaces/IExplode.js"; +/** Explode options class */ export class Explode implements IExplode, IOptionLoader { + /** Maximum size factor for the explosion */ maxSizeFactor: number; + /** Speed of the explosion */ speed: number; + /** Explode constructor */ constructor() { this.maxSizeFactor = 3; this.speed = 2; } + /** + * Loads the explode options from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/destroy/src/Options/Classes/Split.ts b/updaters/destroy/src/Options/Classes/Split.ts index 391c6fb6434..bd667efe27d 100644 --- a/updaters/destroy/src/Options/Classes/Split.ts +++ b/updaters/destroy/src/Options/Classes/Split.ts @@ -13,17 +13,28 @@ import type { ISplit } from "../Interfaces/ISplit.js"; import { SplitFactor } from "./SplitFactor.js"; import { SplitRate } from "./SplitRate.js"; +/** Split options class */ export class Split implements ISplit, IOptionLoader { + /** The split count */ count: number; + /** The split factor */ factor: SplitFactor; + /** The split fill color */ fillColor?: OptionsColor; + /** The split fill color offset */ fillColorOffset?: Partial; + /** The split particles options */ particles?: SingleOrMultiple>; + /** The split rate */ rate: SplitRate; + /** The split size offset */ sizeOffset: boolean; + /** The split stroke color */ strokeColor?: OptionsColor; + /** The split stroke color offset */ strokeColorOffset?: Partial; + /** Split constructor */ constructor() { this.count = 1; this.factor = new SplitFactor(); @@ -31,6 +42,10 @@ export class Split implements ISplit, IOptionLoader { this.sizeOffset = true; } + /** + * Loads the split options from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/destroy/src/Options/Classes/SplitFactor.ts b/updaters/destroy/src/Options/Classes/SplitFactor.ts index 18f4d49c759..6c97ebe19c8 100644 --- a/updaters/destroy/src/Options/Classes/SplitFactor.ts +++ b/updaters/destroy/src/Options/Classes/SplitFactor.ts @@ -1,6 +1,8 @@ import { ValueWithRandom } from "@tsparticles/engine"; +/** Split factor options class */ export class SplitFactor extends ValueWithRandom { + /** SplitFactor constructor */ constructor() { super(); diff --git a/updaters/destroy/src/Options/Classes/SplitRate.ts b/updaters/destroy/src/Options/Classes/SplitRate.ts index 897b3a1cff5..b771bb311ec 100644 --- a/updaters/destroy/src/Options/Classes/SplitRate.ts +++ b/updaters/destroy/src/Options/Classes/SplitRate.ts @@ -1,6 +1,8 @@ import { ValueWithRandom } from "@tsparticles/engine"; +/** Split rate options class */ export class SplitRate extends ValueWithRandom { + /** SplitRate constructor */ constructor() { super(); diff --git a/updaters/destroy/src/Options/Interfaces/IDestroy.ts b/updaters/destroy/src/Options/Interfaces/IDestroy.ts index 85ae69628b9..6fc18567f92 100644 --- a/updaters/destroy/src/Options/Interfaces/IDestroy.ts +++ b/updaters/destroy/src/Options/Interfaces/IDestroy.ts @@ -4,12 +4,16 @@ import type { IExplode } from "./IExplode.js"; import type { ISplit } from "./ISplit.js"; /** - + * The destroy updater options * [[include:Destroy.md]] */ export interface IDestroy { + /** The destroy bounds options */ bounds: IDestroyBounds; + /** The destroy explode options */ explode: IExplode; + /** The destroy mode */ mode: DestroyMode | keyof typeof DestroyMode; + /** The destroy split options */ split: ISplit; } diff --git a/updaters/destroy/src/Options/Interfaces/IDestroyBounds.ts b/updaters/destroy/src/Options/Interfaces/IDestroyBounds.ts index 48de2476fd8..ea68c654a5c 100644 --- a/updaters/destroy/src/Options/Interfaces/IDestroyBounds.ts +++ b/updaters/destroy/src/Options/Interfaces/IDestroyBounds.ts @@ -1,8 +1,13 @@ import type { RangeValue } from "@tsparticles/engine"; +/** The destroy bounds options */ export interface IDestroyBounds { + /** The bottom bound */ bottom?: RangeValue; + /** The left bound */ left?: RangeValue; + /** The right bound */ right?: RangeValue; + /** The top bound */ top?: RangeValue; } diff --git a/updaters/destroy/src/Options/Interfaces/IExplode.ts b/updaters/destroy/src/Options/Interfaces/IExplode.ts index f81da1fab83..4c77cd32148 100644 --- a/updaters/destroy/src/Options/Interfaces/IExplode.ts +++ b/updaters/destroy/src/Options/Interfaces/IExplode.ts @@ -1,4 +1,7 @@ +/** The explode options */ export interface IExplode { + /** The maximum size factor */ maxSizeFactor: number; + /** The explode speed */ speed: number; } diff --git a/updaters/destroy/src/Options/Interfaces/ISplit.ts b/updaters/destroy/src/Options/Interfaces/ISplit.ts index 307d7a0a93f..d4fccf93389 100644 --- a/updaters/destroy/src/Options/Interfaces/ISplit.ts +++ b/updaters/destroy/src/Options/Interfaces/ISplit.ts @@ -7,14 +7,24 @@ import type { SingleOrMultiple, } from "@tsparticles/engine"; +/** The split options */ export interface ISplit { + /** The split count */ count: number; + /** The split factor */ factor: IValueWithRandom; + /** The split fill color */ fillColor?: string | IOptionsColor; + /** The split fill color offset */ fillColorOffset?: Partial; + /** The split particles options */ particles?: SingleOrMultiple>; + /** The split rate */ rate: IValueWithRandom; + /** The split size offset */ sizeOffset: boolean; + /** The split stroke color */ strokeColor?: string | IOptionsColor; + /** The split stroke color offset */ strokeColorOffset?: Partial; } diff --git a/updaters/destroy/src/Types.ts b/updaters/destroy/src/Types.ts index d93f28ec5b1..d3612a3e0d4 100644 --- a/updaters/destroy/src/Types.ts +++ b/updaters/destroy/src/Types.ts @@ -2,28 +2,43 @@ import type { IBounds, IParticlesOptions, Particle, ParticlesOptions } from "@ts import type { Destroy } from "./Options/Classes/Destroy.js"; import type { IDestroy } from "./Options/Interfaces/IDestroy.js"; +/** Destroy particles options interface */ export type IDestroyParticlesOptions = IParticlesOptions & { + /** Destroy options */ destroy?: IDestroy; }; +/** Destroy particles options */ export type DestroyParticlesOptions = ParticlesOptions & { + /** Destroy options */ destroy?: Destroy; }; +/** Destroy particle extension type */ export type DestroyParticle = Particle & { + /** Destroy bounds */ destroyBounds?: Partial; + /** Explosion state */ exploding?: { + /** Initial fill opacity */ initialFillOpacity: number; + /** Initial size */ initialSize: number; + /** Initial stroke opacity */ initialStrokeOpacity: number; + /** Maximum size */ maxSize: number; + /** Explosion progress */ progress: number; + /** Explosion speed */ speed: number; }; + /** Destroy particles options */ options: DestroyParticlesOptions; /** * Sets the count of particles created when destroyed with split mode */ splitCount?: number; + /** Timestamp until the particle becomes breakable */ unbreakableUntil?: number; }; diff --git a/updaters/gradient/src/GradientUpdater.ts b/updaters/gradient/src/GradientUpdater.ts index c397bd7c8cb..1974814adab 100644 --- a/updaters/gradient/src/GradientUpdater.ts +++ b/updaters/gradient/src/GradientUpdater.ts @@ -30,15 +30,30 @@ import type { GradientParticle, GradientParticlesOptions, IGradientParticlesOpti import { AnimatableGradient } from "./Options/Classes/AnimatableGradient.js"; import { updateGradient } from "./Utils.js"; +/** Gradient updater plugin */ export class GradientUpdater implements IParticleUpdater { + /** The particles container */ private readonly _container; + /** The plugin manager */ private readonly _pluginManager; + /** + * GradientUpdater constructor + * @param pluginManager + * @param container + */ constructor(pluginManager: PluginManager, container: Container) { this._pluginManager = pluginManager; this._container = container; } + /** + * Gets the color styles for the gradient + * @param particle + * @param context + * @param radius + * @param opacity + */ getColorStyles( particle: GradientParticle, context: CanvasContextType, @@ -78,6 +93,10 @@ export class GradientUpdater implements IParticleUpdater { return { fill: fillGradient }; } + /** + * Initializes the particle gradient + * @param particle + */ init(particle: GradientParticle): void { const gradient = itemFromSingleOrMultiple(particle.options.gradient); @@ -188,6 +207,10 @@ export class GradientUpdater implements IParticleUpdater { } } + /** + * Checks if gradient animation is enabled + * @param particle + */ isEnabled(particle: GradientParticle): boolean { return ( !particle.destroyed && @@ -197,6 +220,11 @@ export class GradientUpdater implements IParticleUpdater { ); } + /** + * Loads the gradient options + * @param options + * @param sources + */ loadOptions( options: GradientParticlesOptions, ...sources: (RecursivePartial | undefined)[] @@ -218,6 +246,11 @@ export class GradientUpdater implements IParticleUpdater { } } + /** + * Updates particle gradient animation + * @param particle + * @param delta + */ update(particle: GradientParticle, delta: IDelta): void { updateGradient(particle, delta); } diff --git a/updaters/gradient/src/Options/Classes/AnimatableGradient.ts b/updaters/gradient/src/Options/Classes/AnimatableGradient.ts index f972737cf72..974495184f9 100644 --- a/updaters/gradient/src/Options/Classes/AnimatableGradient.ts +++ b/updaters/gradient/src/Options/Classes/AnimatableGradient.ts @@ -3,17 +3,26 @@ import { AnimatableGradientColor } from "./AnimatableGradientColor.js"; import { GradientAngle } from "./GradientAngle.js"; import type { IAnimatableGradient } from "../Interfaces/IAnimatableGradient.js"; +/** Animatable gradient options class */ export class AnimatableGradient implements IAnimatableGradient, IOptionLoader { + /** Gradient angle */ angle: GradientAngle; + /** Gradient colors */ colors: AnimatableGradientColor[]; + /** Gradient type */ type: GradientType; + /** AnimatableGradient constructor */ constructor() { this.angle = new GradientAngle(); this.colors = []; this.type = GradientType.random; } + /** + * Loads the animatable gradient from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/gradient/src/Options/Classes/AnimatableGradientColor.ts b/updaters/gradient/src/Options/Classes/AnimatableGradientColor.ts index e0da054768c..6e8606d7e56 100644 --- a/updaters/gradient/src/Options/Classes/AnimatableGradientColor.ts +++ b/updaters/gradient/src/Options/Classes/AnimatableGradientColor.ts @@ -2,16 +2,25 @@ import { AnimatableColor, type IOptionLoader, type RecursivePartial, isNull, isN import { GradientColorOpacity } from "./GradientColorOpacity.js"; import type { IAnimatableGradientColor } from "../Interfaces/IOptionsGradient.js"; +/** Animatable gradient color options class */ export class AnimatableGradientColor implements IAnimatableGradientColor, IOptionLoader { + /** Color opacity */ opacity?: GradientColorOpacity; + /** Color stop position */ stop; + /** Color value */ value; + /** AnimatableGradientColor constructor */ constructor() { this.stop = 0; this.value = new AnimatableColor(); } + /** + * Loads the animatable gradient color from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/gradient/src/Options/Classes/GradientAngle.ts b/updaters/gradient/src/Options/Classes/GradientAngle.ts index 2b156582eb5..a93e209d425 100644 --- a/updaters/gradient/src/Options/Classes/GradientAngle.ts +++ b/updaters/gradient/src/Options/Classes/GradientAngle.ts @@ -12,19 +12,28 @@ import { import { GradientAngleAnimation } from "./GradientAngleAnimation.js"; import type { IGradientAngle } from "../Interfaces/Gradients.js"; +/** Gradient angle options class */ export class GradientAngle implements IGradientAngle, IAnimatable, IOptionLoader> { + /** Angle animation */ animation; + /** Angle direction */ direction: RotateDirection | keyof typeof RotateDirection | RotateDirectionAlt; + /** Angle value */ value: RangeValue; + /** GradientAngle constructor */ constructor() { this.value = 0; this.animation = new GradientAngleAnimation(); this.direction = RotateDirection.clockwise; } + /** + * Loads the gradient angle from data + * @param data + */ load(data?: RecursivePartial>): void { if (isNull(data)) { return; diff --git a/updaters/gradient/src/Options/Classes/GradientAngleAnimation.ts b/updaters/gradient/src/Options/Classes/GradientAngleAnimation.ts index 7e0312cddbb..85016e82161 100644 --- a/updaters/gradient/src/Options/Classes/GradientAngleAnimation.ts +++ b/updaters/gradient/src/Options/Classes/GradientAngleAnimation.ts @@ -7,14 +7,22 @@ import { setRangeValue, } from "@tsparticles/engine"; +/** Gradient angle animation options class */ export class GradientAngleAnimation implements IAnimation, IOptionLoader { + /** Animation repeat count */ count: RangeValue; + /** Animation decay */ decay: RangeValue; + /** Animation delay */ delay: RangeValue; + /** Enables the animation */ enable; + /** Animation speed */ speed: RangeValue; + /** Enables animation sync */ sync; + /** GradientAngleAnimation constructor */ constructor() { this.count = 0; this.enable = false; @@ -24,6 +32,10 @@ export class GradientAngleAnimation implements IAnimation, IOptionLoader): void { if (isNull(data)) { return; diff --git a/updaters/gradient/src/Options/Classes/GradientColorOpacity.ts b/updaters/gradient/src/Options/Classes/GradientColorOpacity.ts index 28b79c295d0..da81479d0f4 100644 --- a/updaters/gradient/src/Options/Classes/GradientColorOpacity.ts +++ b/updaters/gradient/src/Options/Classes/GradientColorOpacity.ts @@ -11,20 +11,28 @@ import { GradientColorOpacityAnimation } from "./GradientColorOpacityAnimation.j import type { IGradientColorOpacity } from "../Interfaces/Gradients.js"; import type { IGradientColorOpacityAnimation } from "../Interfaces/IOptionsGradient.js"; +/** Gradient color opacity options class */ export class GradientColorOpacity implements IGradientColorOpacity, IAnimatable, IOptionLoader> { + /** Color opacity animation */ animation; + /** Color opacity value */ value: RangeValue; + /** GradientColorOpacity constructor */ constructor() { this.value = 0; this.animation = new GradientColorOpacityAnimation(); } + /** + * Loads the gradient color opacity from data + * @param data + */ load(data?: RecursivePartial>): void { if (isNull(data)) { return; diff --git a/updaters/gradient/src/Options/Classes/GradientColorOpacityAnimation.ts b/updaters/gradient/src/Options/Classes/GradientColorOpacityAnimation.ts index b3efd0f6665..d503b94365e 100644 --- a/updaters/gradient/src/Options/Classes/GradientColorOpacityAnimation.ts +++ b/updaters/gradient/src/Options/Classes/GradientColorOpacityAnimation.ts @@ -8,17 +8,26 @@ import { } from "@tsparticles/engine"; import type { IGradientColorOpacityAnimation } from "../Interfaces/IOptionsGradient.js"; +/** Gradient color opacity animation options class */ export class GradientColorOpacityAnimation implements IGradientColorOpacityAnimation, IOptionLoader { + /** Animation repeat count */ count: RangeValue; + /** Animation decay */ decay: RangeValue; + /** Animation delay */ delay: RangeValue; + /** Enables the animation */ enable; + /** Animation speed */ speed: RangeValue; + /** Animation start value */ startValue: StartValueType | keyof typeof StartValueType; + /** Enables animation sync */ sync; + /** GradientColorOpacityAnimation constructor */ constructor() { this.count = 0; this.enable = false; @@ -29,6 +38,10 @@ export class GradientColorOpacityAnimation this.startValue = StartValueType.random; } + /** + * Loads the gradient color opacity animation from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/gradient/src/Options/Interfaces/Gradients.ts b/updaters/gradient/src/Options/Interfaces/Gradients.ts index 613666109f9..9b6abad74e0 100644 --- a/updaters/gradient/src/Options/Interfaces/Gradients.ts +++ b/updaters/gradient/src/Options/Interfaces/Gradients.ts @@ -1,22 +1,35 @@ import type { GradientType, IOptionsColor, RangeValue, RotateDirection, RotateDirectionAlt } from "@tsparticles/engine"; +/** The gradient color opacity options */ export interface IGradientColorOpacity { + /** The gradient color opacity value */ value: RangeValue; } +/** The gradient color options */ export interface IGradientColor { + /** The gradient color opacity */ opacity?: IGradientColorOpacity | number; + /** The gradient color stop */ stop: number; + /** The gradient color value */ value: IOptionsColor; } +/** The gradient angle options */ export interface IGradientAngle { + /** The gradient angle direction */ direction: RotateDirection | keyof typeof RotateDirection | RotateDirectionAlt; + /** The gradient angle value */ value: RangeValue; } +/** The gradient options */ export interface IGradient { + /** The gradient angle */ angle?: IGradientAngle; + /** The gradient colors */ colors: IGradientColor[]; + /** The gradient type */ type: GradientType; } diff --git a/updaters/gradient/src/Options/Interfaces/IAnimatableGradient.ts b/updaters/gradient/src/Options/Interfaces/IAnimatableGradient.ts index d689cd0c0b2..f77acdf1b0b 100644 --- a/updaters/gradient/src/Options/Interfaces/IAnimatableGradient.ts +++ b/updaters/gradient/src/Options/Interfaces/IAnimatableGradient.ts @@ -2,7 +2,10 @@ import type { IAnimatable, IAnimation } from "@tsparticles/engine"; import type { IAnimatableGradientColor, IOptionsGradient } from "./IOptionsGradient.js"; import type { IGradientAngle } from "./Gradients.js"; +/** The animatable gradient options */ export type IAnimatableGradient = IOptionsGradient & { + /** The animatable gradient angle */ angle: IGradientAngle & IAnimatable; + /** The animatable gradient colors */ colors: IAnimatableGradientColor[]; }; diff --git a/updaters/gradient/src/Options/Interfaces/IOptionsGradient.ts b/updaters/gradient/src/Options/Interfaces/IOptionsGradient.ts index 57fa949f2dd..019454a1a57 100644 --- a/updaters/gradient/src/Options/Interfaces/IOptionsGradient.ts +++ b/updaters/gradient/src/Options/Interfaces/IOptionsGradient.ts @@ -1,13 +1,19 @@ import type { IAnimatable, IAnimatableColor, IAnimation, StartValueType } from "@tsparticles/engine"; import type { IGradient, IGradientColor, IGradientColorOpacity } from "./Gradients.js"; +/** The gradient color opacity animation options */ export interface IGradientColorOpacityAnimation extends IAnimation { + /** The gradient color opacity animation start value */ startValue: StartValueType | keyof typeof StartValueType; } +/** The animatable gradient color options */ export interface IAnimatableGradientColor extends IGradientColor { + /** The animatable gradient color opacity */ opacity?: (IGradientColorOpacity & IAnimatable) | number; + /** The animatable gradient color value */ value: IAnimatableColor; } +/** The gradient options */ export type IOptionsGradient = IGradient; diff --git a/updaters/gradient/src/Types.ts b/updaters/gradient/src/Types.ts index d763c9fb6fa..38af0bf9008 100644 --- a/updaters/gradient/src/Types.ts +++ b/updaters/gradient/src/Types.ts @@ -10,30 +10,44 @@ import type { import type { AnimatableGradient } from "./Options/Classes/AnimatableGradient.js"; import type { IAnimatableGradient } from "./Options/Interfaces/IAnimatableGradient.js"; +/** Particle gradient color animation interface */ export interface IParticleGradientColorAnimation { + /** Opacity animation */ opacity?: IParticleNumericValueAnimation; + /** Color stop position */ stop: number; + /** HSL animation values */ value: IParticleHslAnimation; } +/** Particle gradient animation interface */ export interface IParticleGradientAnimation { + /** Angle animation */ angle: IParticleNumericValueAnimation; + /** Gradient colors */ colors: IParticleGradientColorAnimation[]; + /** Gradient type */ type: GradientType; } +/** Gradient particle extension type */ export type GradientParticle = Particle & { /** * Gets the particle gradient options */ gradient?: IParticleGradientAnimation; + /** Gradient particles options */ options: GradientParticlesOptions; }; +/** Gradient particles options interface */ export type IGradientParticlesOptions = IParticlesOptions & { + /** Gradient options */ gradient?: SingleOrMultiple; }; +/** Gradient particles options */ export type GradientParticlesOptions = ParticlesOptions & { + /** Gradient options */ gradient?: SingleOrMultiple; }; diff --git a/updaters/life/src/LifeUpdater.ts b/updaters/life/src/LifeUpdater.ts index b3b92bf86cd..a705fc19903 100644 --- a/updaters/life/src/LifeUpdater.ts +++ b/updaters/life/src/LifeUpdater.ts @@ -16,13 +16,23 @@ const noTime = 0, identity = 1, infiniteValue = -1; +/** Life updater plugin */ export class LifeUpdater implements IParticleUpdater { + /** The particles container */ private readonly container; + /** + * LifeUpdater constructor + * @param container + */ constructor(container: Container) { this.container = container; } + /** + * Initializes particle life values + * @param particle + */ init(particle: LifeParticle): void { const container = this.container, particlesOptions = particle.options, @@ -60,10 +70,19 @@ export class LifeUpdater implements IParticleUpdater { particle.spawning = particle.life.delay > noTime; } + /** + * Checks if life updater is enabled + * @param particle + */ isEnabled(particle: Particle): boolean { return !particle.destroyed; } + /** + * Loads the life options + * @param options + * @param sources + */ loadOptions( options: LifeParticlesOptions, ...sources: (RecursivePartial | undefined)[] @@ -75,6 +94,11 @@ export class LifeUpdater implements IParticleUpdater { } } + /** + * Updates the particle life state + * @param particle + * @param delta + */ update(particle: LifeParticle, delta: IDelta): void { if (!this.isEnabled(particle) || !particle.life) { return; diff --git a/updaters/life/src/Options/Classes/Life.ts b/updaters/life/src/Options/Classes/Life.ts index 96ce709a73b..46d8828cc40 100644 --- a/updaters/life/src/Options/Classes/Life.ts +++ b/updaters/life/src/Options/Classes/Life.ts @@ -3,17 +3,26 @@ import type { ILife } from "../Interfaces/ILife.js"; import { LifeDelay } from "./LifeDelay.js"; import { LifeDuration } from "./LifeDuration.js"; +/** Life options class */ export class Life implements ILife, IOptionLoader { + /** Life count */ count; + /** Life delay */ delay; + /** Life duration */ duration; + /** Life constructor */ constructor() { this.count = 0; this.delay = new LifeDelay(); this.duration = new LifeDuration(); } + /** + * Loads the life options from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/life/src/Options/Classes/LifeDelay.ts b/updaters/life/src/Options/Classes/LifeDelay.ts index 9c1874e8cc0..171abc84081 100644 --- a/updaters/life/src/Options/Classes/LifeDelay.ts +++ b/updaters/life/src/Options/Classes/LifeDelay.ts @@ -1,14 +1,21 @@ import { type IOptionLoader, type RecursivePartial, ValueWithRandom, isNull } from "@tsparticles/engine"; import type { ILifeDelay } from "../Interfaces/ILifeDelay.js"; +/** Life delay options class */ export class LifeDelay extends ValueWithRandom implements ILifeDelay, IOptionLoader { + /** Enables the life delay sync */ sync; + /** LifeDelay constructor */ constructor() { super(); this.sync = false; } + /** + * Loads the life delay from data + * @param data + */ override load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/life/src/Options/Classes/LifeDuration.ts b/updaters/life/src/Options/Classes/LifeDuration.ts index 836c475dace..32b6eb0ff2b 100644 --- a/updaters/life/src/Options/Classes/LifeDuration.ts +++ b/updaters/life/src/Options/Classes/LifeDuration.ts @@ -1,14 +1,21 @@ import { type IOptionLoader, type RecursivePartial, ValueWithRandom, isNull } from "@tsparticles/engine"; import type { ILifeDuration } from "../Interfaces/ILifeDuration.js"; +/** Life duration options class */ export class LifeDuration extends ValueWithRandom implements ILifeDuration, IOptionLoader { + /** Enables the life duration sync */ sync; + /** LifeDuration constructor */ constructor() { super(); this.sync = false; } + /** + * Loads the life duration from data + * @param data + */ override load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/life/src/Options/Interfaces/ILife.ts b/updaters/life/src/Options/Interfaces/ILife.ts index 6700ec82e17..4668f12203f 100644 --- a/updaters/life/src/Options/Interfaces/ILife.ts +++ b/updaters/life/src/Options/Interfaces/ILife.ts @@ -1,8 +1,12 @@ import type { ILifeDelay } from "./ILifeDelay.js"; import type { ILifeDuration } from "./ILifeDuration.js"; +/** The life options */ export interface ILife { + /** The life count */ count: number; + /** The life delay options */ delay: ILifeDelay; + /** The life duration options */ duration: ILifeDuration; } diff --git a/updaters/life/src/Options/Interfaces/ILifeDelay.ts b/updaters/life/src/Options/Interfaces/ILifeDelay.ts index bc92fd60c5e..474b7369b19 100644 --- a/updaters/life/src/Options/Interfaces/ILifeDelay.ts +++ b/updaters/life/src/Options/Interfaces/ILifeDelay.ts @@ -1,5 +1,7 @@ import type { IValueWithRandom } from "@tsparticles/engine"; +/** The life delay options */ export interface ILifeDelay extends IValueWithRandom { + /** Enables the life delay sync */ sync: boolean; } diff --git a/updaters/life/src/Options/Interfaces/ILifeDuration.ts b/updaters/life/src/Options/Interfaces/ILifeDuration.ts index 785e59a6519..15cc5cff23f 100644 --- a/updaters/life/src/Options/Interfaces/ILifeDuration.ts +++ b/updaters/life/src/Options/Interfaces/ILifeDuration.ts @@ -1,5 +1,7 @@ import type { IValueWithRandom } from "@tsparticles/engine"; +/** The life duration options */ export interface ILifeDuration extends IValueWithRandom { + /** Enables the life duration sync */ sync: boolean; } diff --git a/updaters/life/src/Types.ts b/updaters/life/src/Types.ts index 98048b6d289..e504cfcf9d2 100644 --- a/updaters/life/src/Types.ts +++ b/updaters/life/src/Types.ts @@ -2,23 +2,36 @@ import type { IParticlesOptions, Particle, ParticlesOptions } from "@tsparticles import type { ILife } from "./Options/Interfaces/ILife.js"; import type { Life } from "./Options/Classes/Life.js"; +/** Particle life animation interface */ export interface IParticleLife { + /** Number of life cycles remaining */ count: number; + /** Delay between life cycles */ delay: number; + /** Current delay time */ delayTime: number; + /** Duration of each life cycle */ duration: number; + /** Current life time */ time: number; } +/** Life particles options interface */ export type ILifeParticlesOptions = IParticlesOptions & { + /** Life options */ life?: ILife; }; +/** Life particles options */ export type LifeParticlesOptions = ParticlesOptions & { + /** Life options */ life?: Life; }; +/** Life particle extension type */ export type LifeParticle = Particle & { + /** Life animation state */ life?: IParticleLife; + /** Life particles options */ options: LifeParticlesOptions; }; diff --git a/updaters/orbit/src/Options/Classes/Orbit.ts b/updaters/orbit/src/Options/Classes/Orbit.ts index beee803c157..77e0d6e46f2 100644 --- a/updaters/orbit/src/Options/Classes/Orbit.ts +++ b/updaters/orbit/src/Options/Classes/Orbit.ts @@ -15,14 +15,22 @@ import { OrbitRotation } from "./OrbitRotation.js"; * [[include:Options/Particles/Orbit.md]] */ export class Orbit implements IOrbit, IOptionLoader, IAnimatable { + /** Orbit animation options */ animation; + /** Orbit color */ color?: OptionsColor; + /** Enables the orbit */ enable: boolean; + /** Orbit opacity */ opacity: RangeValue; + /** Orbit radius */ radius?: RangeValue; + /** Orbit rotation */ rotation; + /** Orbit width */ width: RangeValue; + /** Orbit constructor */ constructor() { this.animation = new AnimationOptions(); this.enable = false; @@ -31,6 +39,10 @@ export class Orbit implements IOrbit, IOptionLoader, IAnimatable): void { if (isNull(data)) { return; diff --git a/updaters/orbit/src/Options/Classes/OrbitRotation.ts b/updaters/orbit/src/Options/Classes/OrbitRotation.ts index 7361c6fad57..436a561441d 100644 --- a/updaters/orbit/src/Options/Classes/OrbitRotation.ts +++ b/updaters/orbit/src/Options/Classes/OrbitRotation.ts @@ -1,14 +1,18 @@ import { type IValueWithRandom, type RecursivePartial, ValueWithRandom, isNull } from "@tsparticles/engine"; -/** - */ +/** Orbit rotation options class */ export class OrbitRotation extends ValueWithRandom { + /** OrbitRotation constructor */ constructor() { super(); this.value = 45; } + /** + * Loads the orbit rotation from data + * @param data + */ override load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/orbit/src/Options/Interfaces/IOrbit.ts b/updaters/orbit/src/Options/Interfaces/IOrbit.ts index 30bcf383588..31e6e9f8e65 100644 --- a/updaters/orbit/src/Options/Interfaces/IOrbit.ts +++ b/updaters/orbit/src/Options/Interfaces/IOrbit.ts @@ -4,6 +4,7 @@ import type { IAnimatable, IAnimation, IOptionsColor, IValueWithRandom, RangeVal * [[include:Options/Particles/Orbit.md]] */ export interface IOrbit extends IAnimatable { + /** The orbit color */ color?: string | IOptionsColor; /** @@ -11,8 +12,12 @@ export interface IOrbit extends IAnimatable { */ enable: boolean; + /** The orbit opacity */ opacity: RangeValue; + /** The orbit radius */ radius?: RangeValue; + /** The orbit rotation */ rotation: IValueWithRandom; + /** The orbit width */ width: RangeValue; } diff --git a/updaters/orbit/src/OrbitUpdater.ts b/updaters/orbit/src/OrbitUpdater.ts index 2b490c79d5e..4c1bd7a89a5 100644 --- a/updaters/orbit/src/OrbitUpdater.ts +++ b/updaters/orbit/src/OrbitUpdater.ts @@ -21,15 +21,27 @@ const defaultOrbitSpeed = 0, defaultWidth = 1, defaultRotation = 0; +/** Orbit updater plugin */ export class OrbitUpdater implements IParticleUpdater { + /** The particles container */ private readonly _container; + /** The plugin manager */ private readonly _pluginManager; + /** + * OrbitUpdater constructor + * @param pluginManager + * @param container + */ constructor(pluginManager: PluginManager, container: OrbitContainer) { this._pluginManager = pluginManager; this._container = container; } + /** + * Draws the orbit after particle rendering + * @param particle + */ afterDraw(particle: OrbitParticle): void { const orbitOptions = particle.options.orbit; @@ -38,6 +50,10 @@ export class OrbitUpdater implements IParticleUpdater { } } + /** + * Draws the orbit before particle rendering + * @param particle + */ beforeDraw(particle: OrbitParticle): void { const orbitOptions = particle.options.orbit; @@ -46,6 +62,11 @@ export class OrbitUpdater implements IParticleUpdater { } } + /** + * Draws the orbit ellipse + * @param particle + * @param type + */ drawOrbit(particle: OrbitParticle, type: OrbitType): void { const container = this._container; @@ -81,6 +102,10 @@ export class OrbitUpdater implements IParticleUpdater { }); } + /** + * Initializes the particle orbit + * @param particle + */ init(particle: OrbitParticle): void { /* orbit */ const container = this._container, @@ -103,12 +128,21 @@ export class OrbitUpdater implements IParticleUpdater { particle.orbitOpacity = getRangeValue(orbitOptions.opacity); } + /** + * Checks if orbit is enabled for the particle + * @param particle + */ isEnabled(particle: OrbitParticle): boolean { const orbitAnimations = particle.options.orbit?.animation; return !particle.destroyed && !particle.spawning && !!orbitAnimations?.enable; } + /** + * Loads the orbit options + * @param options + * @param sources + */ loadOptions( options: OrbitParticlesOptions, ...sources: (RecursivePartial | undefined)[] @@ -120,6 +154,11 @@ export class OrbitUpdater implements IParticleUpdater { } } + /** + * Updates the particle orbit rotation + * @param particle + * @param delta + */ update(particle: OrbitParticle, delta: IDelta): void { if (!this.isEnabled(particle)) { return; diff --git a/updaters/orbit/src/Types.ts b/updaters/orbit/src/Types.ts index d7cd39236b5..f17ac446559 100644 --- a/updaters/orbit/src/Types.ts +++ b/updaters/orbit/src/Types.ts @@ -10,30 +10,47 @@ import type { import type { IOrbit } from "./Options/Interfaces/IOrbit.js"; import type { Orbit } from "./Options/Classes/Orbit.js"; +/** Orbit particles options interface */ export type IOrbitParticlesOptions = IParticlesOptions & { + /** Orbit options */ orbit?: IOrbit; }; +/** Orbit particles options */ export type OrbitParticlesOptions = ParticlesOptions & { + /** Orbit options */ orbit?: Orbit; }; +/** Orbit retina extension type */ export type OrbitRetina = Retina & { + /** Orbit radius */ orbitRadius?: number; }; +/** Orbit container extension type */ export type OrbitContainer = Container & { + /** Orbit retina */ retina: OrbitRetina; }; +/** Orbit particle extension type */ export type OrbitParticle = Particle & { + /** Orbit particles options */ options: OrbitParticlesOptions; + /** Orbit animation speed */ orbitAnimationSpeed?: number; + /** Orbit color */ orbitColor?: IHsl; + /** Orbit opacity */ orbitOpacity?: number; + /** Orbit rotation */ orbitRotation?: number; + /** Orbit width */ orbitWidth?: number; + /** Orbit retina properties */ retina: IParticleRetinaProps & { + /** Orbit radius */ orbitRadius?: number; }; }; diff --git a/updaters/outModes/src/BounceOutMode.ts b/updaters/outModes/src/BounceOutMode.ts index 637e307a759..57eca1da88c 100644 --- a/updaters/outModes/src/BounceOutMode.ts +++ b/updaters/outModes/src/BounceOutMode.ts @@ -10,11 +10,18 @@ import { import { bounceHorizontal, bounceVertical } from "./Utils.js"; import type { IOutModeManager } from "./IOutModeManager.js"; +/** Bounce out mode manager */ export class BounceOutMode implements IOutModeManager { + /** Supported out modes */ modes: (OutMode | keyof typeof OutMode)[]; + /** Particle bounce plugins */ private readonly _particleBouncePlugins: IContainerPlugin[]; + /** + * BounceOutMode constructor + * @param container + */ constructor(private readonly container: Container) { this.modes = [ OutMode.bounce, @@ -23,6 +30,13 @@ export class BounceOutMode implements IOutModeManager { this._particleBouncePlugins = container.plugins.filter(p => p.particleBounce !== undefined); } + /** + * Updates the particle bouncing off the canvas edges + * @param particle + * @param direction + * @param delta + * @param outMode + */ update( particle: Particle, direction: OutModeDirection, diff --git a/updaters/outModes/src/IBounceData.ts b/updaters/outModes/src/IBounceData.ts index ed600b621bb..76e1aab4638 100644 --- a/updaters/outModes/src/IBounceData.ts +++ b/updaters/outModes/src/IBounceData.ts @@ -1,11 +1,19 @@ import type { IBounds, ICoordinates, IDimension, OutMode, OutModeDirection, Particle } from "@tsparticles/engine"; +/** Bounce data interface for out mode handling */ export interface IBounceData { + /** Particle bounds */ bounds: IBounds; + /** Canvas dimensions */ canvasSize: IDimension; + /** Out mode direction */ direction: OutModeDirection; + /** Position offset */ offset: ICoordinates; + /** Out mode type */ outMode: OutMode | keyof typeof OutMode; + /** The particle */ particle: Particle; + /** Particle size */ size: number; } diff --git a/updaters/outModes/src/IOutModeManager.ts b/updaters/outModes/src/IOutModeManager.ts index 2605a8be94e..143ff2cb005 100644 --- a/updaters/outModes/src/IOutModeManager.ts +++ b/updaters/outModes/src/IOutModeManager.ts @@ -1,7 +1,10 @@ import type { IDelta, OutMode, OutModeDirection, Particle } from "@tsparticles/engine"; +/** Out mode manager interface */ export interface IOutModeManager { + /** Supported out modes */ modes: (OutMode | keyof typeof OutMode)[]; + /** Updates the particle based on the out mode */ update(particle: Particle, direction: OutModeDirection, delta: IDelta, outMode: OutMode | keyof typeof OutMode): void; } diff --git a/updaters/outModes/src/OutOfCanvasUpdater.ts b/updaters/outModes/src/OutOfCanvasUpdater.ts index 936f9e06b38..77a5a2f727b 100644 --- a/updaters/outModes/src/OutOfCanvasUpdater.ts +++ b/updaters/outModes/src/OutOfCanvasUpdater.ts @@ -23,16 +23,27 @@ const checkOutMode = (outModes: OutModes, outMode: OutMode | keyof typeof OutMod ); }; +/** Out of canvas updater plugin */ export class OutOfCanvasUpdater implements IParticleUpdater { + /** Out mode managers by out mode */ updaters: Map; + /** The particles container */ private readonly container; + /** + * OutOfCanvasUpdater constructor + * @param container + */ constructor(container: Container) { this.container = container; this.updaters = new Map(); } + /** + * Initializes particle out mode handlers + * @param particle + */ init(particle: Particle): void { this._addUpdaterIfMissing(particle, OutMode.bounce, container => new BounceOutMode(container)); this._addUpdaterIfMissing(particle, OutMode.out, container => new OutOutMode(container)); @@ -40,10 +51,19 @@ export class OutOfCanvasUpdater implements IParticleUpdater { this._addUpdaterIfMissing(particle, OutMode.none, container => new NoneOutMode(container)); } + /** + * Checks if out of canvas handling is enabled + * @param particle + */ isEnabled(particle: Particle): boolean { return !particle.destroyed && !particle.spawning; } + /** + * Updates particle out mode handling + * @param particle + * @param delta + */ update(particle: Particle, delta: IDelta): void { const outModes = particle.options.move.outModes; diff --git a/updaters/paint/src/PaintUpdater.ts b/updaters/paint/src/PaintUpdater.ts index d0ee9692330..2bf5ff1e6e1 100644 --- a/updaters/paint/src/PaintUpdater.ts +++ b/updaters/paint/src/PaintUpdater.ts @@ -15,15 +15,27 @@ import type { PaintParticle } from "./Types.js"; const defaultOpacity = 1; +/** Paint updater plugin */ export class PaintUpdater implements IParticleUpdater { + /** The particles container */ private readonly _container; + /** The plugin manager */ private readonly _pluginManager; + /** + * PaintUpdater constructor + * @param pluginManager + * @param container + */ constructor(pluginManager: PluginManager, container: Container) { this._container = container; this._pluginManager = pluginManager; } + /** + * Initializes paint-related particle properties + * @param particle + */ init(particle: PaintParticle): void { const container = this._container, options = particle.options, @@ -86,6 +98,10 @@ export class PaintUpdater implements IParticleUpdater { } } + /** + * Checks if paint animation is enabled + * @param particle + */ isEnabled(particle: PaintParticle): boolean { const { fillAnimation, fillColor, strokeAnimation, strokeColor } = particle, fillEnabled = @@ -102,6 +118,11 @@ export class PaintUpdater implements IParticleUpdater { return !particle.destroyed && !particle.spawning && (fillEnabled || strokeEnabled); } + /** + * Updates the particle paint colors + * @param particle + * @param delta + */ update(particle: Particle, delta: IDelta): void { if (!this.isEnabled(particle)) { return; diff --git a/updaters/roll/src/Options/Classes/Roll.ts b/updaters/roll/src/Options/Classes/Roll.ts index d9ffbaa4ceb..18155f561bf 100644 --- a/updaters/roll/src/Options/Classes/Roll.ts +++ b/updaters/roll/src/Options/Classes/Roll.ts @@ -10,14 +10,22 @@ import type { IRoll } from "../Interfaces/IRoll.js"; import { RollLight } from "./RollLight.js"; import { RollMode } from "../../RollMode.js"; +/** Roll options class */ export class Roll implements IRoll, IOptionLoader { + /** Roll back color */ backColor?: OptionsColor; + /** Roll darken options */ darken; + /** Enables the roll */ enable; + /** Roll enlighten options */ enlighten; + /** Roll mode */ mode: RollMode | keyof typeof RollMode; + /** Roll speed */ speed: RangeValue; + /** Roll constructor */ constructor() { this.darken = new RollLight(); this.enable = false; @@ -26,6 +34,10 @@ export class Roll implements IRoll, IOptionLoader { this.speed = 25; } + /** + * Loads the roll options from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/roll/src/Options/Classes/RollLight.ts b/updaters/roll/src/Options/Classes/RollLight.ts index 612efffe2a9..0d78889ee7e 100644 --- a/updaters/roll/src/Options/Classes/RollLight.ts +++ b/updaters/roll/src/Options/Classes/RollLight.ts @@ -1,15 +1,23 @@ import { type IOptionLoader, type RangeValue, type RecursivePartial, isNull, setRangeValue } from "@tsparticles/engine"; import type { IRollLight } from "../Interfaces/IRollLight.js"; +/** Roll light options class */ export class RollLight implements IRollLight, IOptionLoader { + /** Enables the roll light effect */ enable; + /** Roll light value */ value: RangeValue; + /** RollLight constructor */ constructor() { this.enable = false; this.value = 0; } + /** + * Loads the roll light from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/roll/src/Options/Interfaces/IRoll.ts b/updaters/roll/src/Options/Interfaces/IRoll.ts index 5a17da693a7..b53444483b6 100644 --- a/updaters/roll/src/Options/Interfaces/IRoll.ts +++ b/updaters/roll/src/Options/Interfaces/IRoll.ts @@ -2,11 +2,18 @@ import type { IOptionsColor, RangeValue, SingleOrMultiple } from "@tsparticles/e import type { IRollLight } from "./IRollLight.js"; import type { RollMode } from "../../RollMode.js"; +/** The roll options */ export interface IRoll { + /** The roll back color */ backColor?: SingleOrMultiple | IOptionsColor; + /** The roll darken options */ darken: IRollLight; + /** Enables the roll */ enable: boolean; + /** The roll enlighten options */ enlighten: IRollLight; + /** The roll mode */ mode: RollMode | keyof typeof RollMode; + /** The roll speed */ speed: RangeValue; } diff --git a/updaters/roll/src/Options/Interfaces/IRollLight.ts b/updaters/roll/src/Options/Interfaces/IRollLight.ts index 60730ee0b30..42a6f7be7d7 100644 --- a/updaters/roll/src/Options/Interfaces/IRollLight.ts +++ b/updaters/roll/src/Options/Interfaces/IRollLight.ts @@ -1,6 +1,9 @@ import type { RangeValue } from "@tsparticles/engine"; +/** The roll light options */ export interface IRollLight { + /** Enables the roll light */ enable: boolean; + /** The roll light value */ value: RangeValue; } diff --git a/updaters/roll/src/RollUpdater.ts b/updaters/roll/src/RollUpdater.ts index b59d67ef1b8..6c00966c004 100644 --- a/updaters/roll/src/RollUpdater.ts +++ b/updaters/roll/src/RollUpdater.ts @@ -10,13 +10,23 @@ import type { IRollParticlesOptions, RollParticle, RollParticlesOptions } from " import { initParticle, updateRoll } from "./Utils.js"; import { Roll } from "./Options/Classes/Roll.js"; +/** Roll updater plugin */ export class RollUpdater implements IParticleUpdater { + /** The plugin manager */ private readonly _pluginManager; + /** + * RollUpdater constructor + * @param pluginManager + */ constructor(pluginManager: PluginManager) { this._pluginManager = pluginManager; } + /** + * Gets the transform values for the roll effect + * @param particle + */ getTransformValues(particle: Particle): Partial { const roll = particle.roll?.enable && particle.roll, rollHorizontal = roll && roll.horizontal, @@ -28,16 +38,29 @@ export class RollUpdater implements IParticleUpdater { }; } + /** + * Initializes the particle roll + * @param particle + */ init(particle: RollParticle): void { initParticle(this._pluginManager, particle); } + /** + * Checks if roll is enabled for the particle + * @param particle + */ isEnabled(particle: RollParticle): boolean { const roll = particle.options.roll; return !particle.destroyed && !particle.spawning && !!roll?.enable; } + /** + * Loads the roll options + * @param options + * @param sources + */ loadOptions( options: RollParticlesOptions, ...sources: (RecursivePartial | undefined)[] @@ -49,6 +72,11 @@ export class RollUpdater implements IParticleUpdater { } } + /** + * Updates the particle roll + * @param particle + * @param delta + */ update(particle: Particle, delta: IDelta): void { if (!this.isEnabled(particle)) { return; diff --git a/updaters/rotate/src/Options/Classes/Rotate.ts b/updaters/rotate/src/Options/Classes/Rotate.ts index dbeeedcff09..be82414c84b 100644 --- a/updaters/rotate/src/Options/Classes/Rotate.ts +++ b/updaters/rotate/src/Options/Classes/Rotate.ts @@ -13,10 +13,14 @@ import { RotateAnimation } from "./RotateAnimation.js"; * [[include:Options/Particles/Rotate.md]] */ export class Rotate extends ValueWithRandom implements IRotate, IOptionLoader { + /** Rotate animation options */ animation; + /** Rotate direction */ direction: RotateDirection | keyof typeof RotateDirection | RotateDirectionAlt; + /** Enables path rotation */ path; + /** Rotate constructor */ constructor() { super(); this.animation = new RotateAnimation(); @@ -25,6 +29,10 @@ export class Rotate extends ValueWithRandom implements IRotate, IOptionLoader): void { if (isNull(data)) { return; diff --git a/updaters/rotate/src/Options/Classes/RotateAnimation.ts b/updaters/rotate/src/Options/Classes/RotateAnimation.ts index 8d754f54f27..de71a72f9ce 100644 --- a/updaters/rotate/src/Options/Classes/RotateAnimation.ts +++ b/updaters/rotate/src/Options/Classes/RotateAnimation.ts @@ -1,14 +1,18 @@ import { type IOptionLoader, type RangeValue, type RecursivePartial, isNull, setRangeValue } from "@tsparticles/engine"; import type { IRotateAnimation } from "../Interfaces/IRotateAnimation.js"; -/** - */ +/** Rotate animation options class */ export class RotateAnimation implements IRotateAnimation, IOptionLoader { + /** Animation decay */ decay: RangeValue; + /** Enables the animation */ enable; + /** Animation speed */ speed: RangeValue; + /** Enables animation sync */ sync; + /** RotateAnimation constructor */ constructor() { this.enable = false; this.speed = 0; @@ -16,6 +20,10 @@ export class RotateAnimation implements IRotateAnimation, IOptionLoader): void { if (isNull(data)) { return; diff --git a/updaters/rotate/src/Options/Interfaces/IRotateAnimation.ts b/updaters/rotate/src/Options/Interfaces/IRotateAnimation.ts index a7f3de0d9cf..21780d9dd6c 100644 --- a/updaters/rotate/src/Options/Interfaces/IRotateAnimation.ts +++ b/updaters/rotate/src/Options/Interfaces/IRotateAnimation.ts @@ -1,10 +1,13 @@ import type { RangeValue } from "@tsparticles/engine"; -/** - */ +/** The rotate animation options */ export interface IRotateAnimation { + /** The rotate animation decay */ decay: RangeValue; + /** Enables the rotate animation */ enable: boolean; + /** The rotate animation speed */ speed: RangeValue; + /** Enables the rotate animation sync */ sync: boolean; } diff --git a/updaters/rotate/src/RotateUpdater.ts b/updaters/rotate/src/RotateUpdater.ts index 12195125db9..aed7d6c6418 100644 --- a/updaters/rotate/src/RotateUpdater.ts +++ b/updaters/rotate/src/RotateUpdater.ts @@ -21,28 +21,50 @@ import { import type { IRotate } from "./Options/Interfaces/IRotate.js"; import { Rotate } from "./Options/Classes/Rotate.js"; -type RotateParticle = Particle & { +/** + * Rotate particle extension type + */ +export type RotateParticle = Particle & { options: RotateParticlesOptions; + /** Rotate animation data */ rotate?: IParticleNumericValueAnimation; }; -type IRotateParticlesOptions = IParticlesOptions & { +/** + * Rotate particles options interface + */ +export type IRotateParticlesOptions = IParticlesOptions & { + /** Rotate options */ rotate?: IRotate; }; -type RotateParticlesOptions = ParticlesOptions & { +/** + * Rotate particles options + */ +export type RotateParticlesOptions = ParticlesOptions & { + /** Rotate options */ rotate?: Rotate; }; const doublePIDeg = 360; +/** Rotate updater plugin */ export class RotateUpdater implements IParticleUpdater { + /** The particles container */ private readonly container; + /** + * RotateUpdater constructor + * @param container + */ constructor(container: Container) { this.container = container; } + /** + * Initializes the particle rotation + * @param particle + */ init(particle: RotateParticle): void { const rotateOptions = particle.options.rotate; @@ -96,6 +118,10 @@ export class RotateUpdater implements IParticleUpdater { particle.rotation = particle.rotate.value; } + /** + * Checks if rotation is enabled + * @param particle + */ isEnabled(particle: RotateParticle): boolean { const rotate = particle.options.rotate; @@ -106,6 +132,11 @@ export class RotateUpdater implements IParticleUpdater { return !particle.destroyed && !particle.spawning && (!!rotate.value || rotate.animation.enable || rotate.path); } + /** + * Loads the rotate options + * @param options + * @param sources + */ loadOptions( options: RotateParticlesOptions, ...sources: (RecursivePartial | undefined)[] @@ -117,6 +148,11 @@ export class RotateUpdater implements IParticleUpdater { } } + /** + * Updates the particle rotation + * @param particle + * @param delta + */ update(particle: RotateParticle, delta: IDelta): void { if (!this.isEnabled(particle)) { return; diff --git a/updaters/size/src/SizeUpdater.ts b/updaters/size/src/SizeUpdater.ts index 13ac7f9cc6c..e1008a0136c 100644 --- a/updaters/size/src/SizeUpdater.ts +++ b/updaters/size/src/SizeUpdater.ts @@ -10,13 +10,23 @@ import { const minLoops = 0; +/** Size updater plugin */ export class SizeUpdater implements IParticleUpdater { + /** The particles container */ private readonly _container; + /** + * SizeUpdater constructor + * @param container + */ constructor(container: Container) { this._container = container; } + /** + * Initializes the particle size animation velocity + * @param particle + */ init(particle: Particle): void { const container = this._container, sizeOptions = particle.options.size, @@ -32,6 +42,10 @@ export class SizeUpdater implements IParticleUpdater { } } + /** + * Checks if size animation is enabled + * @param particle + */ isEnabled(particle: Particle): boolean { return ( !particle.destroyed && @@ -43,11 +57,20 @@ export class SizeUpdater implements IParticleUpdater { ); } + /** + * Resets the particle size state + * @param particle + */ reset(particle: Particle): void { particle.size.time = 0; particle.size.loops = 0; } + /** + * Updates the particle size + * @param particle + * @param delta + */ update(particle: Particle, delta: IDelta): void { if (!this.isEnabled(particle)) { return; diff --git a/updaters/tilt/src/Options/Classes/Tilt.ts b/updaters/tilt/src/Options/Classes/Tilt.ts index 60a74294c11..e51e7871878 100644 --- a/updaters/tilt/src/Options/Classes/Tilt.ts +++ b/updaters/tilt/src/Options/Classes/Tilt.ts @@ -7,10 +7,14 @@ import { TiltAnimation } from "./TiltAnimation.js"; * [[include:Options/Particles/Rotate.md]] */ export class Tilt extends ValueWithRandom implements ITilt, IOptionLoader { + /** Tilt animation options */ animation; + /** Tilt direction */ direction: TiltDirection | keyof typeof TiltDirection | TiltDirectionAlt; + /** Enables the tilt */ enable; + /** Tilt constructor */ constructor() { super(); this.animation = new TiltAnimation(); @@ -19,6 +23,10 @@ export class Tilt extends ValueWithRandom implements ITilt, IOptionLoader this.value = 0; } + /** + * Loads the tilt options from data + * @param data + */ override load(data?: RecursivePartial): void { super.load(data); diff --git a/updaters/tilt/src/Options/Classes/TiltAnimation.ts b/updaters/tilt/src/Options/Classes/TiltAnimation.ts index b3caf8796a7..636f116464f 100644 --- a/updaters/tilt/src/Options/Classes/TiltAnimation.ts +++ b/updaters/tilt/src/Options/Classes/TiltAnimation.ts @@ -1,14 +1,18 @@ import { type IOptionLoader, type RangeValue, type RecursivePartial, isNull, setRangeValue } from "@tsparticles/engine"; import type { ITiltAnimation } from "../Interfaces/ITiltAnimation.js"; -/** - */ +/** Tilt animation options class */ export class TiltAnimation implements ITiltAnimation, IOptionLoader { + /** Animation decay */ decay: RangeValue; + /** Enables the animation */ enable; + /** Animation speed */ speed: RangeValue; + /** Enables animation sync */ sync; + /** TiltAnimation constructor */ constructor() { this.enable = false; this.speed = 0; @@ -16,6 +20,10 @@ export class TiltAnimation implements ITiltAnimation, IOptionLoader): void { if (isNull(data)) { return; diff --git a/updaters/tilt/src/Options/Interfaces/ITiltAnimation.ts b/updaters/tilt/src/Options/Interfaces/ITiltAnimation.ts index 7cf396ad78c..abdedab5fbf 100644 --- a/updaters/tilt/src/Options/Interfaces/ITiltAnimation.ts +++ b/updaters/tilt/src/Options/Interfaces/ITiltAnimation.ts @@ -1,11 +1,13 @@ import type { RangeValue } from "@tsparticles/engine"; -/** - */ - +/** The tilt animation options */ export interface ITiltAnimation { + /** The tilt animation decay */ decay: RangeValue; + /** Enables the tilt animation */ enable: boolean; + /** The tilt animation speed */ speed: RangeValue; + /** Enables the tilt animation sync */ sync: boolean; } diff --git a/updaters/tilt/src/TiltUpdater.ts b/updaters/tilt/src/TiltUpdater.ts index 6f563a8e47f..d17f1d877e3 100644 --- a/updaters/tilt/src/TiltUpdater.ts +++ b/updaters/tilt/src/TiltUpdater.ts @@ -21,13 +21,23 @@ import { TiltDirection } from "./TiltDirection.js"; const maxAngle = 360; +/** Tilt updater plugin */ export class TiltUpdater implements IParticleUpdater { + /** The particles container */ private readonly container; + /** + * TiltUpdater constructor + * @param container + */ constructor(container: Container) { this.container = container; } + /** + * Gets the transform values for the tilt effect + * @param particle + */ getTransformValues(particle: TiltParticle): Partial { const tilt = particle.tilt?.enable && particle.tilt; @@ -37,6 +47,10 @@ export class TiltUpdater implements IParticleUpdater { }; } + /** + * Initializes the particle tilt + * @param particle + */ init(particle: TiltParticle): void { const tiltOptions = particle.options.tilt; @@ -87,12 +101,21 @@ export class TiltUpdater implements IParticleUpdater { } } + /** + * Checks if tilt animation is enabled + * @param particle + */ isEnabled(particle: TiltParticle): boolean { const tiltAnimation = particle.options.tilt?.animation; return !particle.destroyed && !particle.spawning && !!tiltAnimation?.enable; } + /** + * Loads the tilt options + * @param options + * @param sources + */ loadOptions( options: TiltParticlesOptions, ...sources: (RecursivePartial | undefined)[] @@ -104,6 +127,11 @@ export class TiltUpdater implements IParticleUpdater { } } + /** + * Updates the particle tilt + * @param particle + * @param delta + */ update(particle: TiltParticle, delta: IDelta): void { if (!this.isEnabled(particle) || !particle.tilt) { return; diff --git a/updaters/twinkle/src/Options/Classes/Twinkle.ts b/updaters/twinkle/src/Options/Classes/Twinkle.ts index 1f2c3d9bbcf..e000c16415f 100644 --- a/updaters/twinkle/src/Options/Classes/Twinkle.ts +++ b/updaters/twinkle/src/Options/Classes/Twinkle.ts @@ -7,14 +7,21 @@ import { TwinkleParticlesValues } from "./TwinkleParticlesValues.js"; * [[include:Options/Particles/Twinkle.md]] */ export class Twinkle implements ITwinkle, IOptionLoader { + /** Twinkle links values */ links; + /** Twinkle particles values */ particles; + /** Twinkle constructor */ constructor() { this.links = new TwinkleLinksValues(); this.particles = new TwinkleParticlesValues(); } + /** + * Loads the twinkle options from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/twinkle/src/Options/Classes/TwinkleLinksValues.ts b/updaters/twinkle/src/Options/Classes/TwinkleLinksValues.ts index d0f30c805d1..a21cc946f6d 100644 --- a/updaters/twinkle/src/Options/Classes/TwinkleLinksValues.ts +++ b/updaters/twinkle/src/Options/Classes/TwinkleLinksValues.ts @@ -8,20 +8,28 @@ import { } from "@tsparticles/engine"; import type { ITwinkleLinksValues } from "../Interfaces/ITwinkleLinksValues.js"; -/** - */ +/** Twinkle links values options class */ export class TwinkleLinksValues implements ITwinkleLinksValues, IOptionLoader { + /** Twinkle links color */ color?: OptionsColor; + /** Enables the twinkle links */ enable; + /** Twinkle links frequency */ frequency; + /** Twinkle links opacity */ opacity: RangeValue; + /** TwinkleLinksValues constructor */ constructor() { this.enable = false; this.frequency = 0.05; this.opacity = 1; } + /** + * Loads the twinkle links values from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/twinkle/src/Options/Classes/TwinkleParticlesValues.ts b/updaters/twinkle/src/Options/Classes/TwinkleParticlesValues.ts index 643d101655c..2e6bf243778 100644 --- a/updaters/twinkle/src/Options/Classes/TwinkleParticlesValues.ts +++ b/updaters/twinkle/src/Options/Classes/TwinkleParticlesValues.ts @@ -8,21 +8,30 @@ import { } from "@tsparticles/engine"; import type { ITwinkleParticlesValues } from "../Interfaces/ITwinkleParticlesValues.js"; -/** - */ +/** Twinkle particles values options class */ export class TwinkleParticlesValues implements ITwinkleParticlesValues, IOptionLoader { + /** Enables the twinkle particles */ enable; + /** Twinkle particles fill color */ fillColor?: OptionsColor; + /** Twinkle particles frequency */ frequency; + /** Twinkle particles opacity */ opacity: RangeValue; + /** Twinkle particles stroke color */ strokeColor?: OptionsColor; + /** TwinkleParticlesValues constructor */ constructor() { this.enable = false; this.frequency = 0.05; this.opacity = 1; } + /** + * Loads the twinkle particles values from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/twinkle/src/Options/Interfaces/ITwinkleLinksValues.ts b/updaters/twinkle/src/Options/Interfaces/ITwinkleLinksValues.ts index ad34cadc11d..47bbf734c86 100644 --- a/updaters/twinkle/src/Options/Interfaces/ITwinkleLinksValues.ts +++ b/updaters/twinkle/src/Options/Interfaces/ITwinkleLinksValues.ts @@ -1,10 +1,13 @@ import type { IOptionsColor, RangeValue } from "@tsparticles/engine"; -/** - */ +/** The twinkle links values options */ export interface ITwinkleLinksValues { + /** The twinkle links color */ color?: string | IOptionsColor; + /** Enables the twinkle links */ enable: boolean; + /** The twinkle links frequency */ frequency: number; + /** The twinkle links opacity */ opacity: RangeValue; } diff --git a/updaters/twinkle/src/Options/Interfaces/ITwinkleParticlesValues.ts b/updaters/twinkle/src/Options/Interfaces/ITwinkleParticlesValues.ts index f7d7929eb84..e6c15dedd61 100644 --- a/updaters/twinkle/src/Options/Interfaces/ITwinkleParticlesValues.ts +++ b/updaters/twinkle/src/Options/Interfaces/ITwinkleParticlesValues.ts @@ -1,11 +1,15 @@ import type { IOptionsColor, RangeValue } from "@tsparticles/engine"; -/** - */ +/** The twinkle particles values options */ export interface ITwinkleParticlesValues { + /** Enables the twinkle particles */ enable: boolean; + /** The twinkle particles fill color */ fillColor?: string | IOptionsColor; + /** The twinkle particles frequency */ frequency: number; + /** The twinkle particles opacity */ opacity: RangeValue; + /** The twinkle particles stroke color */ strokeColor?: string | IOptionsColor; } diff --git a/updaters/twinkle/src/TwinkleUpdater.ts b/updaters/twinkle/src/TwinkleUpdater.ts index cc5b64ff3fc..568f7c0b0ad 100644 --- a/updaters/twinkle/src/TwinkleUpdater.ts +++ b/updaters/twinkle/src/TwinkleUpdater.ts @@ -14,15 +14,30 @@ import { import type { ITwinkleParticlesOptions, TwinkeParticle, TwinkleParticlesOptions } from "./Types.js"; import { Twinkle } from "./Options/Classes/Twinkle.js"; +/** Twinkle updater plugin */ export class TwinkleUpdater implements IParticleUpdater { + /** The particles container */ private readonly _container; + /** The plugin manager */ private readonly _pluginManager; + /** + * TwinkleUpdater constructor + * @param pluginManager + * @param container + */ constructor(pluginManager: PluginManager, container: Container) { this._pluginManager = pluginManager; this._container = container; } + /** + * Gets the twinkle color styles + * @param particle + * @param _context + * @param _radius + * @param opacity + */ getColorStyles( particle: Particle, _context: CanvasContextType, @@ -70,10 +85,15 @@ export class TwinkleUpdater implements IParticleUpdater { return res; } + /** Initializes the twinkle (no-op) */ init(): void { // nothing to do } + /** + * Checks if twinkle is enabled + * @param particle + */ isEnabled(particle: TwinkeParticle): boolean { const pOptions = particle.options, twinkleOptions = pOptions.twinkle; @@ -85,6 +105,11 @@ export class TwinkleUpdater implements IParticleUpdater { return twinkleOptions.particles.enable; } + /** + * Loads the twinkle options + * @param options + * @param sources + */ loadOptions( options: TwinkleParticlesOptions, ...sources: (RecursivePartial | undefined)[] @@ -96,6 +121,7 @@ export class TwinkleUpdater implements IParticleUpdater { } } + /** Updates the twinkle (no-op) */ update(): void { // nothing to do } diff --git a/updaters/wobble/src/Options/Classes/Wobble.ts b/updaters/wobble/src/Options/Classes/Wobble.ts index 778282718cc..ee7f6a8d1d0 100644 --- a/updaters/wobble/src/Options/Classes/Wobble.ts +++ b/updaters/wobble/src/Options/Classes/Wobble.ts @@ -11,17 +11,26 @@ import type { IWobble } from "../Interfaces/IWobble.js"; import type { IWobbleSpeed } from "../Interfaces/IWobbleSpeed.js"; import { WobbleSpeed } from "./WobbleSpeed.js"; +/** Wobble options class */ export class Wobble implements IWobble, IOptionLoader { + /** Wobble distance */ distance: RangeValue; + /** Enables the wobble */ enable: boolean; + /** Wobble speed */ speed: WobbleSpeed; + /** Wobble constructor */ constructor() { this.distance = 5; this.enable = false; this.speed = new WobbleSpeed(); } + /** + * Loads the wobble options from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/wobble/src/Options/Classes/WobbleSpeed.ts b/updaters/wobble/src/Options/Classes/WobbleSpeed.ts index c301d1b6482..f6d076ce1b9 100644 --- a/updaters/wobble/src/Options/Classes/WobbleSpeed.ts +++ b/updaters/wobble/src/Options/Classes/WobbleSpeed.ts @@ -1,15 +1,23 @@ import { type IOptionLoader, type RangeValue, type RecursivePartial, isNull, setRangeValue } from "@tsparticles/engine"; import type { IWobbleSpeed } from "../Interfaces/IWobbleSpeed.js"; +/** Wobble speed options class */ export class WobbleSpeed implements IWobbleSpeed, IOptionLoader { + /** Wobble speed angle */ angle: RangeValue; + /** Wobble speed movement */ move: RangeValue; + /** WobbleSpeed constructor */ constructor() { this.angle = 50; this.move = 10; } + /** + * Loads the wobble speed from data + * @param data + */ load(data?: RecursivePartial): void { if (isNull(data)) { return; diff --git a/updaters/wobble/src/Options/Interfaces/IWobble.ts b/updaters/wobble/src/Options/Interfaces/IWobble.ts index 60c285cc279..3071cb0c1f8 100644 --- a/updaters/wobble/src/Options/Interfaces/IWobble.ts +++ b/updaters/wobble/src/Options/Interfaces/IWobble.ts @@ -1,8 +1,12 @@ import type { IWobbleSpeed } from "./IWobbleSpeed.js"; import type { RangeValue } from "@tsparticles/engine"; +/** The wobble options */ export interface IWobble { + /** The wobble distance */ distance: RangeValue; + /** Enables the wobble */ enable: boolean; + /** The wobble speed */ speed: RangeValue | IWobbleSpeed; } diff --git a/updaters/wobble/src/Options/Interfaces/IWobbleSpeed.ts b/updaters/wobble/src/Options/Interfaces/IWobbleSpeed.ts index b4a0d3a6bbe..1da8e057924 100644 --- a/updaters/wobble/src/Options/Interfaces/IWobbleSpeed.ts +++ b/updaters/wobble/src/Options/Interfaces/IWobbleSpeed.ts @@ -1,6 +1,9 @@ import type { RangeValue } from "@tsparticles/engine"; +/** The wobble speed options */ export interface IWobbleSpeed { + /** The wobble speed angle */ angle: RangeValue; + /** The wobble speed movement */ move: RangeValue; } diff --git a/updaters/wobble/src/Types.ts b/updaters/wobble/src/Types.ts index f33c2d28f16..ac41155807f 100644 --- a/updaters/wobble/src/Types.ts +++ b/updaters/wobble/src/Types.ts @@ -2,9 +2,15 @@ import type { IParticlesOptions, Particle, ParticlesOptions } from "@tsparticles import type { IWobble } from "./Options/Interfaces/IWobble.js"; import type { Wobble } from "./Options/Classes/Wobble.js"; -interface IParticleWobble { +/** + * Particle wobble data + */ +export interface IParticleWobble { + /** Current wobble angle */ angle: number; + /** Wobble angle speed */ angleSpeed: number; + /** Wobble movement speed */ moveSpeed: number; } diff --git a/websites/website/docs/fr/releases/index.md b/websites/website/docs/fr/releases/index.md index 3eeeb52ba74..6c758540b24 100644 --- a/websites/website/docs/fr/releases/index.md +++ b/websites/website/docs/fr/releases/index.md @@ -11,7 +11,7 @@ Ce projet est désormais livré à partir d'un seul référentiel : `tsparticle - Moteur : - Emballages : - Préréglages : --Palettes : +- Palettes : ## Règle d'alignement des versions diff --git a/websites/website/package.json b/websites/website/package.json index f6fcad5c91e..6303993d3e5 100644 --- a/websites/website/package.json +++ b/websites/website/package.json @@ -6,7 +6,6 @@ "main": "docs/index.md", "type": "module", "scripts": { - "postinstall": "node ./scripts/fix-palette-types.mjs", "typedoc:api": "typedoc --options typedoc.json", "docs:typedoc": "node ./scripts/sync-typedoc.mjs", "docs:assets": "node ./scripts/sync-public-assets.mjs", @@ -259,14 +258,21 @@ "typedoc-plugin-markdown": "^4.11.0", "typedoc-plugin-mdn-links": "^5.1.1", "typedoc-plugin-missing-exports": "^4.1.3", - "typedoc-vitepress-theme": "^1.1.2", "vitepress": "^1.6.4" }, "nx": { "targets": { "build": { - "outputs": ["{projectRoot}/docs/.vitepress/dist", "{projectRoot}/docs/docs/"], - "inputs": ["production", "^production", "{projectRoot}/docs/**/*", "{projectRoot}/typedoc.json"] + "outputs": [ + "{projectRoot}/docs/.vitepress/dist", + "{projectRoot}/docs/docs/" + ], + "inputs": [ + "production", + "^production", + "{projectRoot}/docs/**/*", + "{projectRoot}/typedoc.json" + ] } } } diff --git a/websites/website/scripts/fix-palette-types.mjs b/websites/website/scripts/fix-palette-types.mjs deleted file mode 100644 index 899f9530148..00000000000 --- a/websites/website/scripts/fix-palette-types.mjs +++ /dev/null @@ -1,83 +0,0 @@ -#!/usr/bin/env node -/** - * Fix type declarations for palette packages that were published - * with types/index.js instead of types/index.d.ts. - * This script generates proper .d.ts declaration files for the affected packages. - */ - -import { writeFileSync, existsSync, readFileSync } from "node:fs"; -import { join, dirname } from "node:path"; -import { fileURLToPath } from "node:url"; -import { createRequire } from "node:module"; - -const __dirname = dirname(fileURLToPath(import.meta.url)); -const require = createRequire(import.meta.url); - -/** - * Derive the loader function name from the js source file. - * @param {string} jsPath - * @returns {string | undefined} - */ -function extractLoaderName(jsPath) { - try { - const src = readFileSync(jsPath, "utf-8"); - const match = src.match(/export\s+async\s+function\s+(\w+)/); - return match ? match[1] : undefined; - } catch { - return undefined; - } -} - -const affectedPackages = [ - "@tsparticles/palette-apple", - "@tsparticles/palette-apple-green", - "@tsparticles/palette-apple-red", - "@tsparticles/palette-avocado", - "@tsparticles/palette-bell-peppers", - "@tsparticles/palette-berries", - "@tsparticles/palette-cherry", - "@tsparticles/palette-citrus-twist", - "@tsparticles/palette-gingerbread-house", - "@tsparticles/palette-grapes", - "@tsparticles/palette-iris", - "@tsparticles/palette-macaron", - "@tsparticles/palette-melon", - "@tsparticles/palette-mermaid", - "@tsparticles/palette-pineapple", - "@tsparticles/palette-pizza", - "@tsparticles/palette-sakura", - "@tsparticles/palette-salad", - "@tsparticles/palette-spice-rack", - "@tsparticles/palette-steak", - "@tsparticles/palette-sushi", - "@tsparticles/palette-tropical-fruits", - "@tsparticles/palette-unicorn", - "@tsparticles/palette-watermelon", -]; - -for (const pkg of affectedPackages) { - try { - const pkgJsonPath = require.resolve(`${pkg}/package.json`); - const pkgDir = dirname(pkgJsonPath); - const typesDir = join(pkgDir, "types"); - - for (const [srcFile, destFile] of [ - ["index.js", "index.d.ts"], - ["index.lazy.js", "index.lazy.d.ts"], - ]) { - const srcJs = join(typesDir, srcFile); - const destDts = join(typesDir, destFile); - - if (existsSync(srcJs)) { - const loaderName = extractLoaderName(srcJs); - const dtsContent = loaderName - ? `import type { Engine } from "@tsparticles/engine";\nexport declare function ${loaderName}(engine: Engine): Promise;\n` - : `export declare function load(engine: unknown): Promise;\n`; - writeFileSync(destDts, dtsContent, "utf-8"); - console.log(`[fix-palette-types] Created ${destDts}`); - } - } - } catch { - // Package not installed, skip - } -} diff --git a/websites/website/typedoc.json b/websites/website/typedoc.json index 056a0815362..5fbc68cbf1b 100644 --- a/websites/website/typedoc.json +++ b/websites/website/typedoc.json @@ -2,156 +2,21 @@ "$schema": "https://typedoc.org/schema.json", "entryPoints": [ "../../engine", - "../../bundles/all", - "../../bundles/basic", - "../../bundles/confetti", - "../../bundles/fireworks", - "../../bundles/full", - "../../bundles/particles", - "../../bundles/pjs", - "../../bundles/slim", - "../../interactions/light", - "../../interactions/external/attract", - "../../interactions/external/bounce", - "../../interactions/external/bubble", - "../../interactions/external/cannon", - "../../interactions/external/connect", - "../../interactions/external/destroy", - "../../interactions/external/drag", - "../../interactions/external/grab", - "../../interactions/external/parallax", - "../../interactions/external/particle", - "../../interactions/external/pause", - "../../interactions/external/pop", - "../../interactions/external/push", - "../../interactions/external/remove", - "../../interactions/external/repulse", - "../../interactions/external/slow", - "../../interactions/external/trail", - "../../interactions/particles/attract", - "../../interactions/particles/collisions", - "../../interactions/particles/links", - "../../interactions/particles/repulse", - "../../paths/branches", - "../../paths/brownian", - "../../paths/curlNoise", - "../../paths/curves", - "../../paths/fractalNoise", - "../../paths/grid", - "../../paths/levy", - "../../paths/perlinNoise", - "../../paths/polygon", - "../../paths/random", - "../../paths/simplexNoise", - "../../paths/spiral", - "../../paths/svg", - "../../paths/zigzag", - "../../plugins/absorbers", - "../../plugins/backgroundMask", - "../../plugins/blend", - "../../plugins/canvasMask", - "../../plugins/emitters", - "../../plugins/infection", - "../../plugins/interactivity", - "../../plugins/manualParticles", - "../../plugins/motion", - "../../plugins/move", - "../../plugins/poisson", - "../../plugins/polygonMask", - "../../plugins/responsive", - "../../plugins/sounds", - "../../plugins/themes", - "../../plugins/trail", - "../../plugins/zoom", - "../../plugins/colors/hex", - "../../plugins/colors/hsl", - "../../plugins/colors/hsv", - "../../plugins/colors/hwb", - "../../plugins/colors/lab", - "../../plugins/colors/lch", - "../../plugins/colors/named", - "../../plugins/colors/oklab", - "../../plugins/colors/oklch", - "../../plugins/colors/rgb", - "../../plugins/easings/back", - "../../plugins/easings/bounce", - "../../plugins/easings/circ", - "../../plugins/easings/cubic", - "../../plugins/easings/elastic", - "../../plugins/easings/expo", - "../../plugins/easings/gaussian", - "../../plugins/easings/linear", - "../../plugins/easings/quad", - "../../plugins/easings/quart", - "../../plugins/easings/quint", - "../../plugins/easings/sigmoid", - "../../plugins/easings/sine", - "../../plugins/easings/smoothstep", - "../../plugins/emittersShapes/canvas", - "../../plugins/emittersShapes/circle", - "../../plugins/emittersShapes/path", - "../../plugins/emittersShapes/polygon", - "../../plugins/emittersShapes/square", - "../../plugins/exports/image", - "../../plugins/exports/json", - "../../plugins/exports/video", - "../../shapes/arrow", - "../../shapes/cards", - "../../shapes/circle", - "../../shapes/cog", - "../../shapes/emoji", - "../../shapes/heart", - "../../shapes/image", - "../../shapes/infinity", - "../../shapes/line", - "../../shapes/matrix", - "../../shapes/path", - "../../shapes/polygon", - "../../shapes/rounded-polygon", - "../../shapes/rounded-rect", - "../../shapes/spiral", - "../../shapes/square", - "../../shapes/squircle", - "../../shapes/star", - "../../shapes/text", - "../../updaters/destroy", - "../../updaters/gradient", - "../../updaters/life", - "../../updaters/opacity", - "../../updaters/orbit", - "../../updaters/outModes", - "../../updaters/paint", - "../../updaters/roll", - "../../updaters/rotate", - "../../updaters/size", - "../../updaters/tilt", - "../../updaters/twinkle", - "../../updaters/wobble", - "../../effects/bubble", - "../../effects/filter", - "../../effects/particles", - "../../effects/shadow", - "../../effects/trail", - "../../presets/ambient", - "../../presets/bigCircles", - "../../presets/bubbles", - "../../presets/confetti", - "../../presets/confettiCannon", - "../../presets/confettiExplosions", - "../../presets/confettiFalling", - "../../presets/confettiParade", - "../../presets/fire", - "../../presets/firefly", - "../../presets/fireworks", - "../../presets/fountain", - "../../presets/hyperspace", - "../../presets/links", - "../../presets/matrix", - "../../presets/seaAnemone", - "../../presets/snow", - "../../presets/squares", - "../../presets/stars", - "../../presets/triangles" + "../../bundles/*", + "../../interactions/*", + "../../interactions/external/*", + "../../interactions/particles/*", + "../../paths/*", + "../../plugins/*", + "../../plugins/colors/*", + "../../plugins/easings/*", + "../../plugins/emittersShapes/*", + "../../plugins/exports/*", + "../../shapes/*", + "../../updaters/*", + "../../effects/*", + "../../presets/*", + "../../palettes/*/*" ], "entryPointStrategy": "packages", "name": "tsParticles",