vevet 3.19.2 → 4.0.0-beta.0

package/src/base/Plugin/index.ts

@@ -4,7 +4,9 @@ import { NPlugin } from './types';
 export type { NPlugin };
 
 /**
- * A class for Plugins.
+ * A base abstract class for Plugins that extend the functionality of components.
+ * A plugin is designed to attach to a component and modify or enhance its behavior.
+ * It inherits from the {@link Module} class and adds functionality to work with a component.
  */
 export abstract class Plugin<
   StaticProps extends NPlugin.IStaticProps = NPlugin.IStaticProps,
@@ -12,20 +14,41 @@ export abstract class Plugin<
   CallbacksTypes extends NPlugin.ICallbacksTypes = NPlugin.ICallbacksTypes,
   Component = any,
 > extends Module<StaticProps, ChangeableProps, CallbacksTypes> {
+  /**
+   * Constructs the plugin.
+   *
+   * @param initialProps - Initial static and changeable properties for the plugin.
+   */
   constructor(initialProps?: StaticProps & ChangeableProps) {
     super(initialProps, false);
   }
 
+  /**
+   * The component to which the plugin is attached.
+   * This property must be set before initializing the plugin.
+   */
   private _component!: Component;
 
+  /**
+   * Retrieves the component to which this plugin is attached.
+   */
   get component() {
     return this._component;
   }
 
+  /**
+   * Sets the component for this plugin. This method is called by the parent component when the plugin is added.
+   */
   set component(value) {
     this._component = value;
   }
 
+  /**
+   * Initializes the plugin and ensures it is properly associated with a component.
+   * If the component is not set before calling `init`, it throws an error.
+   *
+   * @throws {Error} If `component` is not set.
+   */
   public init() {
     if (!this.component) {
       throw new Error(

package/src/base/Plugin/types.ts

@@ -1,9 +1,20 @@
 import { NModule } from '../Module/types';
 
 export namespace NPlugin {
+  /**
+   * Static properties for plugins. These properties remain constant throughout the lifecycle of the plugin.
+   */
   export interface IStaticProps extends NModule.IStaticProps {}
 
+  /**
+   * Changeable properties for plugins. These properties can change dynamically during the lifecycle of the plugin.
+   * Extends from {@link NModule.IChangeableProps}, providing plugins with the ability to update their properties over time.
+   */
   export interface IChangeableProps extends NModule.IChangeableProps {}
 
+  /**
+   * Defines the available callback types for plugins. These callbacks allow plugins to respond to lifecycle events or property changes.
+   * Extends from {@link NModule.ICallbacksTypes}, meaning that plugins share the same callback structure as modules.
+   */
   export interface ICallbacksTypes extends NModule.ICallbacksTypes {}
 }

package/src/components/AnimationFrame/index.ts

@@ -4,7 +4,8 @@ import { NAnimationFrame } from './types';
 export type { NAnimationFrame };
 
 /**
- * Launch an animation frame with a certain FPS
+ * Launches an animation frame with a specified FPS, allowing
+ * control over playback and FPS calculations in real-time.
  */
 export class AnimationFrame<
   StaticProps extends
@@ -23,38 +24,39 @@ export class AnimationFrame<
     };
   }
 
-  /** If the frame is launched */
+  /** Whether the animation frame is currently playing */
   protected _isPlaying: boolean;
 
+  /** Returns the current playback state of the animation frame */
   get isPlaying() {
     return this._isPlaying;
   }
 
-  /** The animation frame */
+  /** The ID of the currently active requestAnimationFrame, or `null` if inactive */
   protected _raf: number | null;
 
-  /** Last frame time */
+  /** Index of the current animation frame */
   protected _rafIndex: number;
 
-  /** First frame time */
+  /** The timestamp of the first frame in the animation sequence */
   protected _rafFirst: null | number;
 
-  /** Last frame time */
+  /** The timestamp of the last frame in the animation sequence */
   protected _rafLast: null | number;
 
-  /** Array of frame time durations */
+  /** Array storing the duration of each frame in milliseconds */
   protected _durations: number[];
 
-  /** Computed fps */
+  /** The computed frames per second based on real-time performance */
   protected _computedFPS: number;
 
-  /** Computed real time fps */
+  /** Returns the current computed FPS, which may differ from the set FPS */
   get computedFPS() {
     return this._computedFPS;
   }
 
-  /** Coefficient of standard fps (60) divided by computed fps */
-  get easeMultiplier() {
+  /** Coefficient that scales based on a target of 60 FPS compared to the computed FPS */
+  get fpsMultiplier() {
     return 60 / this.computedFPS;
   }
 
@@ -78,7 +80,7 @@ export class AnimationFrame<
     super._init();
 
     if (this.props.isEnabled) {
-      this.play();
+      this._play();
     }
   }
 
@@ -96,7 +98,7 @@ export class AnimationFrame<
     }
   }
 
-  /** Play animation */
+  /** Begins the animation loop */
   public play() {
     if (this.isDestroyed) {
       return;
@@ -109,7 +111,7 @@ export class AnimationFrame<
     this.changeProps({ isEnabled: true } as ChangeableProps);
   }
 
-  /** Play animation */
+  /** Internal method to start the animation loop */
   protected _play() {
     if (this.isPlaying) {
       return;
@@ -123,7 +125,7 @@ export class AnimationFrame<
     this._raf = window.requestAnimationFrame(this._animate.bind(this));
   }
 
-  /** Pause animation */
+  /** Pauses the animation loop */
   public pause() {
     if (!this.props.isEnabled) {
       return;
@@ -132,7 +134,7 @@ export class AnimationFrame<
     this.changeProps({ isEnabled: false } as ChangeableProps);
   }
 
-  /** Pause animation */
+  /** Internal method to pause the animation loop */
   protected _pause() {
     if (!this.isPlaying) {
       return;
@@ -149,7 +151,7 @@ export class AnimationFrame<
     this.callbacks.tbt('toggle', undefined);
   }
 
-  /** Launch the animation frame */
+  /** Handles each frame of the animation, calculates FPS, and triggers callbacks */
   protected _animate() {
     if (!this._isPlaying) {
       return;
@@ -157,42 +159,34 @@ export class AnimationFrame<
 
     this._raf = window.requestAnimationFrame(this._animate.bind(this));
 
-    // update time
     const startTime = Date.now();
     if (this._rafFirst === null) {
       this._rafFirst = startTime;
     }
 
-    // calculate frame index
     const minFrameDuration =
       this.props.fps === 'auto' ? 1 : 1000 / this.props.fps;
     const newFrameIndex = Math.floor(
       (startTime - this._rafFirst) / minFrameDuration,
     );
 
-    // break if frame index the same
     if (newFrameIndex <= this._rafIndex) {
       return;
     }
 
-    // update frame index
     this._rafIndex = newFrameIndex;
 
-    // compute fps
     this._computeFPS(startTime);
 
-    // launch callbacks
     this.callbacks.tbt('frame', undefined);
 
-    // update vars
     this._rafLast = startTime;
   }
 
-  /** Compute real-time FPS */
+  /** Computes the real-time FPS based on the duration between frames */
   protected _computeFPS(startTime: number) {
     const lastFrameDuration = startTime - (this._rafLast ?? startTime);
 
-    // skip frames that seem not real
     if (lastFrameDuration <= 0 || lastFrameDuration > 250) {
       return;
     }
@@ -215,11 +209,10 @@ export class AnimationFrame<
 
     this._computedFPS = normalizedFPS;
 
-    // clear durations
     this._durations = [];
   }
 
-  /** Destroy the animation frame */
+  /** Destroys the animation frame and stops the loop */
   protected _destroy() {
     this.pause();
 

package/src/components/AnimationFrame/types.ts

@@ -5,26 +5,46 @@ export namespace NAnimationFrame {
 
   export interface IChangeableProps extends NComponent.IChangeableProps {
     /**
-     * Frames per second
+     * Frames per second (FPS) for the animation.
+     * If set to 'auto', the FPS will be dynamically determined based on the system's performance.
      * @default 'auto'
      */
     fps?: 'auto' | number;
+
     /**
-     * How many frames to be tested to detect real FPS
+     * The number of frames to test for detecting the real FPS when 'auto' is selected.
+     * This determines how many frames are measured before calculating the average FPS.
      * @default 10
      */
     autoFpsFrames?: number;
+
     /**
-     * Enabled animation
+     * Determines whether the AnimationFrame is enabled or not.
+     * When set to `true`, the animation loop will run.
      * @default false
      */
     isEnabled?: boolean;
   }
 
   export interface ICallbacksTypes extends NComponent.ICallbacksTypes {
+    /**
+     * Triggered when the animation starts playing.
+     */
     play: undefined;
+
+    /**
+     * Triggered when the animation is paused.
+     */
     pause: undefined;
+
+    /**
+     * Triggered when the animation toggles between play and pause.
+     */
     toggle: undefined;
+
+    /**
+     * Triggered on each frame of the animation.
+     */
     frame: undefined;
   }
 }

package/src/components/Ctx2D/index.ts

@@ -6,15 +6,15 @@ import { getApp } from '@/utils/internal/getApp';
 export type { NCtx2D };
 
 /**
- * Makes working with canvas easier.
- * It creates an HTML5 Canvas element and its 2d context and can
- * implement automatic resize.
+ * A class that simplifies working with an HTML5 Canvas element and its 2D context.
+ * It can handle automatic resizing and provides helper methods for rendering and managing canvas properties.
  */
 export class Ctx2D<
   StaticProps extends NCtx2D.IStaticProps = NCtx2D.IStaticProps,
   ChangeableProps extends NCtx2D.IChangeableProps = NCtx2D.IChangeableProps,
   CallbacksTypes extends NCtx2D.ICallbacksTypes = NCtx2D.ICallbacksTypes,
 > extends ComponentClass<StaticProps, ChangeableProps, CallbacksTypes> {
+  /** @inheritDoc */
   protected _getDefaultProps() {
     return {
       ...super._getDefaultProps(),
@@ -30,66 +30,69 @@ export class Ctx2D<
     };
   }
 
-  /** The parent element of the canvas */
+  /** The parent element of the canvas used to calculate size */
   get container() {
     return this.props.container;
   }
 
-  /** The Canvas element itself */
+  /** The canvas element created for rendering */
   protected _canvas: HTMLCanvasElement;
 
-  /** The Canvas element itself */
+  /** Returns the current canvas element */
   get canvas() {
     return this._canvas;
   }
 
-  /** 2D Context */
+  /** The 2D rendering context for the canvas */
   protected _ctx: CanvasRenderingContext2D;
 
-  /** 2D Context */
+  /** Returns the 2D rendering context */
   get ctx() {
     return this._ctx;
   }
 
-  /* Canvas width (with DPR) */
+  /** The current width of the canvas, considering the device pixel ratio (DPR) */
   protected _width: number;
 
-  /* Canvas width (with DPR) */
+  /** Returns the current width of the canvas (with DPR applied) */
   get width() {
     return this._width;
   }
 
-  /* Canvas width (without DPR) */
+  /** Returns the width of the canvas without the device pixel ratio (DPR) */
   get clientWidth() {
     return this.width / this.dpr;
   }
 
-  /* Canvas height (with DPR) */
+  /** The current height of the canvas, considering the device pixel ratio (DPR) */
   protected _height: number;
 
-  /* Canvas height (with DPR) */
+  /** Returns the current height of the canvas (with DPR applied) */
   get height() {
     return this._height;
   }
 
-  /* Canvas height (without DPR) */
+  /** Returns the height of the canvas without the device pixel ratio (DPR) */
   get clientHeight() {
     return this.height / this.dpr;
   }
 
-  /** Device pixel ratio */
+  /** The current device pixel ratio (DPR) */
   protected _dpr: number;
 
-  /** Device pixel ratio */
+  /** Returns the current device pixel ratio (DPR) */
   get dpr() {
     return this._dpr;
   }
 
-  /** If content may be successfully rendered */
+  /** Checks if the canvas is ready to be rendered */
   get canRender() {
     return this.width > 0 && this.height > 0;
   }
 
+  /**
+   * Constructor for the Ctx2D class.
+   */
   constructor(initialProps?: StaticProps & ChangeableProps, canInit = true) {
     super(initialProps, false);
 
@@ -100,7 +103,7 @@ export class Ctx2D<
     this._height = 0;
     this._dpr = 1;
 
-    // create canvas
+    // create canvas element
     this._canvas = document.createElement('canvas');
     this._canvas.style.position = 'absolute';
     this._canvas.style.top = '0';
@@ -108,14 +111,13 @@ export class Ctx2D<
     this._canvas.style.width = '100%';
     this._canvas.style.height = '100%';
 
-    // append canvas
+    // append canvas to container if required
     if (shouldAppend && container instanceof Element) {
       container.append(this._canvas);
-
       this.addDestroyableAction(() => this.canvas.remove());
     }
 
-    // create context
+    // create 2D context
     this._ctx = this._canvas.getContext('2d')!;
 
     if (canInit) {
@@ -123,19 +125,21 @@ export class Ctx2D<
     }
   }
 
+  /** @inheritDoc */
   protected _onPropsMutate() {
     super._onPropsMutate();
-
     this.resize();
   }
 
+  /** @inheritDoc */
   protected _init() {
     super._init();
-
     this._setResize();
   }
 
-  /** Set resize events */
+  /**
+   * Sets up the resize event listener for the canvas, if enabled.
+   */
   protected _setResize() {
     const { hasInitialResize, hasResize, viewportTarget, resizeDebounce } =
       this.props;
@@ -158,7 +162,9 @@ export class Ctx2D<
     }
   }
 
-  /** Resize the canvas */
+  /**
+   * Resizes the canvas based on the container or viewport size and applies the device pixel ratio (DPR).
+   */
   public resize() {
     const { props, canvas } = this;
 
@@ -168,16 +174,17 @@ export class Ctx2D<
 
     const { viewport } = getApp();
 
-    // calculate dpr
+    // calculate DPR
     if (typeof props.dpr === 'number') {
       this._dpr = props.dpr;
     } else {
       this._dpr = viewport.dpr;
     }
 
-    // calculate new width & height
+    // calculate new width and height
     let newWidth = 0;
     let newHeight = 0;
+
     if (typeof props.width === 'number' && typeof props.height === 'number') {
       newWidth = props.width;
       newHeight = props.height;
@@ -189,27 +196,32 @@ export class Ctx2D<
       newHeight = viewport.height;
     }
 
-    // apply dpr
+    // apply DPR
     newWidth *= this._dpr;
     newHeight *= this._dpr;
 
-    // update sizes
+    // update canvas size
     this._width = newWidth;
     this._height = newHeight;
-
-    // apply sizes
     canvas.width = newWidth;
     canvas.height = newHeight;
 
-    // launch callbacks
+    // handle resize event and trigger callbacks
     this._handleResize();
     this.callbacks.tbt('resize', undefined);
   }
 
-  /** Method called on resize */
+  /**
+   * A method called after the canvas has been resized.
+   * This can be extended or customized in subclasses.
+   */
   protected _handleResize() {}
 
-  /** Render the scene if possible */
+  /**
+   * Renders content on the canvas if it is ready.
+   *
+   * @param renderProp - A function that performs the actual rendering on the canvas.
+   */
   public render(renderProp: NCtx2D.TRender) {
     if (!this.canRender) {
       return;

package/src/components/Ctx2D/types.ts

@@ -4,33 +4,38 @@ import { TOnResizeTarget } from '@/utils/listeners/onResize';
 export namespace NCtx2D {
   export interface IStaticProps extends NComponent.IStaticProps {
     /**
-     * The parent element of the canvas that will be used to calculate current canvas size.
-     * If `false`, it will be `Window`.
+     * The parent element of the canvas, used to calculate the canvas size.
+     * If set to `false`, the canvas size will be based on the `Window` object.
      * @default false
      */
     container?: false | Element;
+
     /**
-     * Defines if you need to append the canvas element to the parent element
+     * Determines whether the canvas element should be appended to the parent element.
      * @default true
      */
     shouldAppend?: boolean;
+
     /**
-     * Resize on init
+     * Resizes the canvas during initialization.
      * @default true
      */
     hasInitialResize?: boolean;
+
     /**
-     * Update sizes on resize
+     * Enables updating the canvas size when the window is resized.
      * @default false
      */
     hasResize?: boolean;
+
     /**
-     * Viewport target
+     * The target for the viewport resize event.
      * @default 'any'
      */
     viewportTarget?: TOnResizeTarget;
+
     /**
-     * Timeout of resize event
+     * The debounce time (in milliseconds) for the resize event.
      * @default 0
      */
     resizeDebounce?: number;
@@ -38,38 +43,73 @@ export namespace NCtx2D {
 
   export interface IChangeableProps extends NComponent.IChangeableProps {
     /**
-     * The width of the canvas without dpr.
-     * If `auto`, the width will be the same as of the container.
+     * The width of the canvas (without considering device pixel ratio).
+     * If set to `auto`, the width will match the container's width.
      * @default 'auto'
      */
     width?: 'auto' | number;
+
     /**
-     * The height of the canvas (dpr = 1).
-     * If `auto`, the height will be the same as of the container.
+     * The height of the canvas (without considering device pixel ratio).
+     * If set to `auto`, the height will match the container's height.
      * @default 'auto'
      */
     height?: 'auto' | number;
+
     /**
-     * Device pixel ratio.
-     * If `auto`, the value will be calculated automatically.
+     * The device pixel ratio (DPR) to be used for the canvas.
+     * If set to `auto`, the DPR will be automatically calculated.
      * @default 'auto'
      */
     dpr?: 'auto' | number;
   }
 
   export interface ICallbacksTypes extends NComponent.ICallbacksTypes {
+    /**
+     * Triggered when the canvas is resized.
+     */
     resize: undefined;
   }
 
   export interface IRenderProps {
+    /**
+     * The 2D rendering context of the canvas.
+     */
     ctx: CanvasRenderingContext2D;
+
+    /**
+     * The width of the canvas, including the device pixel ratio.
+     */
     width: number;
+
+    /**
+     * The height of the canvas, including the device pixel ratio.
+     */
     height: number;
+
+    /**
+     * The device pixel ratio for rendering on the canvas.
+     */
     dpr: number;
+
+    /**
+     * The client width of the canvas (before DPR is applied).
+     */
     clientWidth: number;
+
+    /**
+     * The client height of the canvas (before DPR is applied).
+     */
     clientHeight: number;
+
+    /**
+     * The HTMLCanvasElement associated with the canvas.
+     */
     canvas: HTMLCanvasElement;
   }
 
+  /**
+   * A function that performs rendering on the canvas using the provided rendering properties.
+   */
   export type TRender = (props: IRenderProps) => void;
 }