vevet 3.20.0 → 4.0.0-beta.0

package/src/components/ProgressPreloader/types.ts

@@ -3,44 +3,45 @@ import { NPreloader } from '../Preloader';
 export namespace NProgressPreloader {
   export interface IStaticProps extends NPreloader.IStaticProps {
     /**
-     * Default resources quantity
+     * The default number of resources to preload. This can be incremented using custom logic.
      * @default 0
      */
     resourcesQuantity?: number;
+
     /**
-     * Preload images
+     * Whether to preload images automatically.
      * @default true
      */
     canPreloadImages?: boolean;
+
     /**
-     * Preload videos
+     * Whether to preload videos automatically.
      * @default false
      */
     canPreloadVideos?: boolean;
+
     /**
-     * Preload custom resources by selector
-     * These elements should have such properties as `isLoaded` or `isComplete` (all boolean or float - from 0 to 1)
-     * or the attribute `data-is-loaded` (string with float or non-empty string for true).
-     * Custom elements may also have the attribute `data-load-count` (number) which means the element weight.
+     * The selector for custom resources to be preloaded. These elements should have properties such as `isLoaded`, `isComplete`, or the attribute `data-is-loaded` (from 0 to 1 or a boolean) for tracking loading status.
+     * Custom elements may also use the `data-load-count` attribute to indicate their weight.
+     *
      * @default '.js-preload'
      */
     preloadCustomSelector?: string;
+
     /**
-     * If you enable images, video, or custom loaders,
-     * all these resources will be preloaded. In cases when you may want not
-     * to preload some resources, you may add to it the classname specified here.
+     * A class name that can be added to elements (such as images, videos, or custom resources) that should be ignored during the preload process.
      * @default 'js-preload-ignore'
      */
     preloadIgnoreClassName?: string;
+
     /**
-     * Linear interpolation. If `false`, animation will not be used.
+     * The amount of linear interpolation to apply to the loading progress. If set to `false`, no interpolation will be used, and the progress will update instantly.
      * @default 0.1
      */
     lerp?: number | false;
+
     /**
-     * If `true` and `lerp` is less than `1`, interpolation will be stopped
-     * and a `Timeline` will be launched to end the progress calculation.
-     * If `false`, the progress smooth calculation will end via linear interpolation.
+     * If `true` and the animated progress is less than `1`, a timeline will automatically complete the progress when nearing the end. If `false`, progress will continue using linear interpolation until it completes.
      * @default 500
      */
     forceEnd?: number | false;
@@ -49,34 +50,84 @@ export namespace NProgressPreloader {
   export interface IChangeableProps extends NPreloader.IChangeableProps {}
 
   export interface ICallbacksTypes extends NPreloader.ICallbacksTypes {
+    /**
+     * Triggered when the preloader's progress is updated.
+     */
     progress: IProgressParameter;
+
+    /**
+     * Triggered each time a resource is loaded during the preload process.
+     */
     resourceLoad: IResourceLoadParameter;
   }
 
   export interface IProgressParameter {
+    /**
+     * The current preloader progress (between 0 and 1).
+     */
     progress: number;
+
+    /**
+     * The current progress based on loaded resources (between 0 and 1).
+     */
     loadProgress: number;
   }
 
   export interface IResourceLoadParameter {
+    /**
+     * The resource element that was loaded, if applicable.
+     */
     element?: Element;
+
+    /**
+     * The progress value when the resource was loaded.
+     */
     atProgress: number;
+
+    /**
+     * The overall load progress when this resource was loaded.
+     */
     loadProgress: number;
+
+    /**
+     * Whether the resource was successfully loaded.
+     */
     isSuccess: boolean;
   }
 
   export interface IHandleLoadedResourceParameter {
+    /**
+     * The resource element that was loaded, if applicable.
+     */
     element?: Element;
+
+    /**
+     * Whether the resource was successfully loaded.
+     */
     isSuccess: boolean;
   }
 
   export interface ICustomResource extends Element {
+    /**
+     * Indicates whether the custom resource has been fully loaded. Can be a boolean or a number representing the loading progress.
+     */
     isLoaded?: boolean | number;
+
+    /**
+     * Indicates whether the custom resource is complete. Can be a boolean or a number representing the loading progress.
+     */
     isComplete?: boolean | number;
   }
 
   export interface ICustomResourceData {
+    /**
+     * The custom resource element to be preloaded.
+     */
     element: ICustomResource;
+
+    /**
+     * The target progress value (between 0 and 1) for this resource, based on its `data-load-count` attribute.
+     */
     targetProgress: number;
   }
 }

package/src/components/ProgressPreloader/utils/preloadCustomElement.ts

@@ -1,10 +1,14 @@
 import { Module } from '@/base/Module';
 import { NProgressPreloader } from '../types';
 
+/**
+ * Retrieves the load progress of a custom resource element based on its properties or attributes.
+ */
 function getLoadProgress({
   element,
   targetProgress,
-}: NProgressPreloader.ICustomResourceData) {
+}: NProgressPreloader.ICustomResourceData): number {
+  // Check if the element is marked as complete
   if (typeof element.isComplete !== 'undefined') {
     if (typeof element.isComplete === 'boolean' && element.isComplete) {
       return targetProgress;
@@ -17,6 +21,7 @@ function getLoadProgress({
     return 0;
   }
 
+  // Check if the element is marked as loaded
   if (typeof element.isLoaded !== 'undefined') {
     if (typeof element.isLoaded === 'boolean' && element.isLoaded) {
       return targetProgress;
@@ -27,6 +32,7 @@ function getLoadProgress({
     }
   }
 
+  // Check for a `data-is-loaded` attribute
   const isLoadedAttr = element.getAttribute('data-is-loaded');
   if (
     isLoadedAttr !== null &&
@@ -35,7 +41,7 @@ function getLoadProgress({
   ) {
     const isLoadedAttrNum = parseFloat(isLoadedAttr);
 
-    // if the value is non-numeric, we think that the resource is loaded
+    // If the value is non-numeric, treat the resource as loaded
     if (Number.isNaN(isLoadedAttrNum)) {
       return targetProgress;
     }
@@ -46,6 +52,9 @@ function getLoadProgress({
   return 0;
 }
 
+/**
+ * Preloads a custom resource element by recursively checking its load progress until the target progress is reached.
+ */
 export function preloadCustomElement(
   data: NProgressPreloader.ICustomResourceData,
   instance: Module<any, any, any>,
@@ -54,12 +63,14 @@ export function preloadCustomElement(
     const { targetProgress } = data;
     const loadProgress = getLoadProgress(data);
 
+    // If the load progress has reached or exceeded the target, resolve the promise
     if (loadProgress >= targetProgress) {
       resolve();
 
       return;
     }
 
+    // Recursively check the load progress every 50ms
     setTimeout(() => {
       if (instance.isDestroyed) {
         return;

package/src/components/ScrollBar/Bar/index.ts

@@ -1,42 +1,91 @@
 import { IAddEventListener, addEventListener } from 'vevet-dom';
-import { ICoords, IBarProps } from './types';
+import { IBarProps } from './types';
 import { IRemovable } from '@/types/general';
 import { DraggerMove, NDraggerMove } from '@/components/DraggerMove';
 import { IOnScrollCallbackParameter, onScroll } from '@/utils/scroll/onScroll';
 import { clamp } from '@/utils/math';
 import { getScrollValues } from '@/utils/scroll';
 
-export default class Bar {
+/**
+ * Represents a custom scroll bar with a draggable thumb.
+ */
+export class Bar {
+  /** The outer container element of the scroll bar */
   private _outer: HTMLElement;
 
+  /**
+   * Gets the outer container of the scroll bar.
+   */
   get outer() {
     return this._outer;
   }
 
+  /** The scroll bar thumb element */
   private _thumb: HTMLElement;
 
+  /**
+   * Gets the thumb element of the scroll bar.
+   */
   get thumb() {
     return this._thumb;
   }
 
-  get prefix() {
-    return this.props.prefix;
-  }
+  /** The outer height of the scroll bar container */
+  private _outerHeight = 0;
+
+  /** The outer width of the scroll bar container */
+  private _outerWidth = 0;
+
+  /** The thumb's height */
+  private _thumbHeight = 0;
+
+  /** The thumb's width */
+  private _thumbWidth = 0;
+
+  /** Stores the previous scroll value for comparison */
+  private _prevScrollValue = 0;
+
+  /** Stores the coordinates of the scroll element at the start of dragging */
+  private _coordsAtDragStart = { scrollLeft: 0, scrollTop: 0 };
+
+  /** Stores the list of event listeners */
+  private _listeners: IAddEventListener[] = [];
+
+  /** The scroll event handler */
+  private _scrollEvent?: IRemovable;
+
+  /** Timeout for handling auto-hide behavior */
+  private _actionTimeout?: NodeJS.Timeout;
+
+  /** Dragger instance for handling thumb dragging */
+  private _dragger?: DraggerMove;
 
+  /**
+   * Determines if the scroll bar is horizontal.
+   */
   get isHorizontal() {
     return this.props.direction === 'x';
   }
 
+  /**
+   * Determines if the scroll bar is vertical.
+   */
   get isVertical() {
     return !this.isHorizontal;
   }
 
+  /**
+   * Gets the scrollable element.
+   */
   get scrollElement() {
     return this.props.container instanceof Window
       ? document.documentElement
       : this.props.container;
   }
 
+  /**
+   * Gets the total scrollable distance (scroll line) for the scroll bar.
+   */
   get scrollLine() {
     const { scrollElement } = this;
 
@@ -45,34 +94,23 @@ export default class Bar {
       : scrollElement.scrollHeight - scrollElement.clientHeight;
   }
 
+  /**
+   * Gets the total width of the scrollable element.
+   */
   get scrollWidth() {
     return this.scrollElement.scrollWidth;
   }
 
+  /**
+   * Gets the total height of the scrollable element.
+   */
   get scrollHeight() {
     return this.scrollElement.scrollHeight;
   }
 
-  private _outerHeight: number;
-
-  private _outerWidth: number;
-
-  private _thumbHeight: number;
-
-  private _thumbWidth: number;
-
-  private _prevScrollValue: number;
-
-  private _coordsAtDragStart: ICoords;
-
-  private _listeners?: IAddEventListener[];
-
-  private _scrollEvent?: IRemovable;
-
-  private _actionTimeout?: NodeJS.Timeout;
-
-  private _dragger?: DraggerMove;
-
+  /**
+   * Gets the scroll bar properties.
+   */
   get props() {
     return this._props;
   }
@@ -80,15 +118,7 @@ export default class Bar {
   constructor(private _props: IBarProps) {
     const { direction, domParent, container, canAutoHide } = _props;
 
-    // set default vars
-    this._outerHeight = 0;
-    this._outerWidth = 0;
-    this._thumbHeight = 0;
-    this._thumbWidth = 0;
-    this._prevScrollValue = 0;
-    this._coordsAtDragStart = { scrollLeft: 0, scrollTop: 0 };
-
-    // create container
+    // Create the outer scroll bar container
     const outer = document.createElement('div');
     this._outer = outer;
     outer.classList.add(this.className(''));
@@ -99,29 +129,32 @@ export default class Bar {
     outer.classList.toggle(this.className('_auto-hide'), canAutoHide);
     domParent.append(outer);
 
-    // create a thumb
+    // Create the thumb for the scroll bar
     const thumb = document.createElement('div');
     this._thumb = thumb;
     thumb.classList.add(this.className('__thumb'));
     thumb.classList.add(this.className(`__thumb_${direction}`));
     outer.append(thumb);
 
-    // set events
+    // Set events for the scroll bar
     this._setEvents();
   }
 
+  /**
+   * Generates the scroll bar's class name based on the prefix and value.
+   * @param value - The suffix to add to the prefix for the class name.
+   */
   private className(value: string) {
     return `${this.props.prefix}${value}`;
   }
 
-  /** Set scrolblar events */
+  /**
+   * Sets the necessary events for the scroll bar, such as hover and scroll events.
+   */
   private _setEvents() {
-    if (!this._listeners) {
-      this._listeners = [];
-    }
-
     const { outer, thumb, props } = this;
 
+    // Add hover events for the outer container
     this._listeners.push(
       addEventListener(outer, 'mouseenter', () => this._handleHover(true)),
     );
@@ -129,11 +162,13 @@ export default class Bar {
       addEventListener(outer, 'mouseleave', () => this._handleHover(false)),
     );
 
+    // Add scroll event for the container
     this._scrollEvent = onScroll({
       container: props.container,
       callback: (data) => this._handleScroll(data),
     });
 
+    // Set drag events if the scroll bar is draggable
     if (this.props.isDraggable) {
       this._dragger = new DraggerMove({ container: thumb });
 
@@ -145,25 +180,32 @@ export default class Bar {
     }
   }
 
-  /** Remove events */
+  /**
+   * Removes all the event listeners for the scroll bar.
+   */
   private _removeEvents() {
     this._listeners?.forEach((listener) => listener.remove());
     this._scrollEvent?.remove();
     this._dragger?.destroy();
   }
 
-  /** Handle hover state */
+  /**
+   * Handles the hover state of the scroll bar.
+   * @param isHovered - Whether the scroll bar is hovered or not.
+   */
   private _handleHover(isHovered: boolean) {
     const className = this.className('_is-hovered');
-
     this.outer.classList.toggle(className, isHovered);
   }
 
-  /** Handle Scroll Event */
+  /**
+   * Handles the scroll event by updating the thumb position and auto-hide behavior.
+   * @param param - The scroll position of the container.
+   */
   private _handleScroll({ scrollLeft, scrollTop }: IOnScrollCallbackParameter) {
     let hasChanged = false;
 
-    // check if changes happened
+    // Check if changes happened
     if (this.isHorizontal) {
       hasChanged = scrollLeft !== this._prevScrollValue;
       this._prevScrollValue = scrollLeft;
@@ -172,15 +214,14 @@ export default class Bar {
       this._prevScrollValue = scrollTop;
     }
 
-    // continue if there are changes
+    // If no changes, return early
     if (!hasChanged) {
       return;
     }
 
-    // set auto hide
+    // Handle auto-hide behavior
     if (this.props.canAutoHide && hasChanged) {
       const actionClassName = this.className('_in-action');
-
       this.outer.classList.add(actionClassName);
 
       if (this._actionTimeout) {
@@ -193,11 +234,14 @@ export default class Bar {
       );
     }
 
-    // render elements
+    // Render the thumb
     this._renderThumb();
   }
 
-  /** Event on dragger move */
+  /**
+   * Handles the thumb dragging event by calculating new scroll values based on the drag movement.
+   * @param param - The drag event data.
+   */
   private _handleThumbDrag({
     event,
     coords,
@@ -208,7 +252,7 @@ export default class Bar {
     const { scrollLine } = this;
     const { container } = this.props;
 
-    // calculate scroll iterators
+    // Calculate new scroll values based on the drag movement
     const leftIterator =
       ((coords.x - start.x) / (this._outerWidth - this._thumbWidth)) *
       scrollLine;
@@ -216,7 +260,6 @@ export default class Bar {
       ((coords.y - start.y) / (this._outerHeight - this._thumbHeight)) *
       scrollLine;
 
-    // calculate new scroll values
     let { scrollLeft, scrollTop } = this._coordsAtDragStart;
     if (this.isHorizontal) {
       scrollLeft += leftIterator;
@@ -224,18 +267,20 @@ export default class Bar {
       scrollTop += topIterator;
     }
 
-    // apply the values
+    // Apply new scroll values
     container.scrollTo({
       top: scrollTop,
       left: scrollLeft,
       behavior:
-        'isSmoothScroll' in this.props.container
+        'isCustomScroll' in this.props.container
           ? this.props.scrollBehavior
           : 'auto',
     });
   }
 
-  /** Render thumb */
+  /**
+   * Renders the thumb position based on the current scroll position.
+   */
   private _renderThumb() {
     const progress = clamp(this._prevScrollValue / this.scrollLine, [0, 1]);
 
@@ -249,7 +294,9 @@ export default class Bar {
     this._thumb.style.transform = `translate(${x}px, ${y}px)`;
   }
 
-  /** Resize the scene */
+  /**
+   * Resizes the scroll bar by recalculating the thumb and outer container sizes.
+   */
   public resize() {
     const {
       outer,
@@ -262,14 +309,14 @@ export default class Bar {
 
     const { minSize, shouldAutoSize } = this.props;
 
-    // define if empty before other calculations
+    // Define if the scrollbar is empty
     outer.classList.toggle(this.className('_is-empty'), scrollLine === 0);
 
-    // get outer sizes
+    // Get outer sizes
     this._outerHeight = outer.clientHeight;
     this._outerWidth = outer.clientWidth;
 
-    // calculate thumb sizes
+    // Calculate thumb sizes if auto-size is enabled
     if (shouldAutoSize) {
       if (isHorizontal) {
         const barSize = clamp(
@@ -286,14 +333,17 @@ export default class Bar {
       }
     }
 
-    // get thumb sizes
+    // Get thumb sizes
     this._thumbHeight = thumb.clientHeight;
     this._thumbWidth = thumb.clientWidth;
 
-    // render elements
+    // Render the thumb position
     this._renderThumb();
   }
 
+  /**
+   * Destroys the scroll bar by removing events and clearing timeouts.
+   */
   public destroy() {
     this._removeEvents();
 

package/src/components/ScrollBar/Bar/types.ts

@@ -1,30 +1,59 @@
-import type { SmoothScroll } from '@/components/SmoothScroll';
+import type { CustomScroll } from '@/components/CustomScroll';
 
+/**
+ * Properties for configuring the behavior and appearance of a custom scroll bar.
+ */
 export interface IBarProps {
-  /** Scrollable container */
-  container: Window | SmoothScroll | Element;
-  /** DOM parent, where the scrollbar will be appended */
+  /**
+   * The scrollable container element.
+   * It can be the browser `window`, a custom scroll instance, or an HTML element.
+   */
+  container: Window | CustomScroll | Element;
+
+  /**
+   * The parent element where the scroll bar will be appended.
+   * This is the DOM element that will contain the scroll bar.
+   */
   domParent: Element;
-  /** Scrollbar type: horizontal or vertical */
+
+  /**
+   * The scroll bar's orientation or direction.
+   * Can be either horizontal ('x') or vertical ('y').
+   */
   direction: 'x' | 'y';
-  /** Hide scrollbars when not active */
+
+  /**
+   * If `true`, the scroll bars will be hidden when inactive.
+   * The scroll bar will only become visible during scrolling or interactions.
+   */
   canAutoHide: boolean;
-  /** Use auto-size */
+
+  /**
+   * If `true`, the size of the scroll bar's thumb will adjust automatically
+   * based on the content length and the viewport size.
+   */
   shouldAutoSize: boolean;
+
   /**
-   * Minimum size of the scrollbar thumb.
-   * Works when `hasAutoSize` is `true`
+   * The minimum size of the scroll bar's thumb.
+   * This property is only applied when `shouldAutoSize` is `true`.
    */
   minSize: number;
-  /** Prefix */
+
+  /**
+   * A prefix used for generating class names or other identifiers for the scroll bar elements.
+   */
   prefix: string;
-  /** Scrollbars are draggable */
+
+  /**
+   * If `true`, the scroll bars will be draggable, allowing users to drag the thumb to scroll.
+   */
   isDraggable: boolean;
-  /** ScrollBehavior when dragging (works only for `SmoothScroll`) */
-  scrollBehavior: 'smooth' | 'auto';
-}
 
-export interface ICoords {
-  scrollLeft: number;
-  scrollTop: number;
+  /**
+   * Defines the scroll behavior during dragging for custom scroll instances.
+   * This property determines whether the scroll will be smooth or immediate ('auto').
+   * This option is only applicable for `CustomScroll` instances.
+   */
+  scrollBehavior: 'smooth' | 'auto';
 }