vevet 3.20.0 → 4.0.0-beta.0

package/src/components/SlideProgress/index.ts

@@ -11,7 +11,8 @@ import { NDraggerBase } from '../DraggerBase';
 export type { NSlideProgress };
 
 /**
- * Slide progress handler
+ * Slide progress handler.
+ * This class manages sliding progress with options like dragging, wheel interactions, and smooth transitions.
  */
 export class SlideProgress<
   StaticProps extends NSlideProgress.IStaticProps = NSlideProgress.IStaticProps,
@@ -39,44 +40,48 @@ export class SlideProgress<
     };
   }
 
-  /** Animation frame */
+  /** Animation frame for smooth animations */
   protected _animationFrame: AnimationFrame;
 
-  /** Dragger events */
+  /** Dragging behavior manager */
   protected _dragger: DraggerMove;
 
-  /** Progress (current and target) */
+  /** Stores the current and target progress values */
   protected _progressLerp: NSlideProgress.IWithLerp = { current: 0, target: 0 };
 
-  /** Progress */
+  /**
+   * Gets the current progress value.
+   */
   get progress() {
     return this._progressLerp.current;
   }
 
-  /** Stepped progress */
+  /**
+   * Gets the nearest stepped progress value.
+   */
   get steppedProgress() {
     return this._getNearestStep(this._progressLerp.current);
   }
 
-  /** Progress timeline */
+  /** Timeline for smooth transitions */
   protected _timelineTo?: Timeline;
 
-  /** Sticky timeout */
+  /** Timeout for sticky behavior at the end */
   protected _stickyEndTimeout?: NodeJS.Timeout;
 
-  /** Can drag */
+  /** Determines if dragging is allowed */
   protected _canDragMove = false;
 
-  /** Direction */
+  /** Direction of progress */
   protected _direction: 1 | -1 = 1;
 
-  /** Wheel intensity */
+  /** Intensity of wheel interaction */
   protected _wheelIntensity = 0;
 
-  /** Current handler */
+  /** Current handler for user interactions: 'wheel' or 'drag' */
   protected _currentHandler: 'wheel' | 'drag' = 'wheel';
 
-  /** If page is scrolling */
+  /** Checks if the page is scrolling */
   protected _createIsPageScrolling: ReturnType<typeof createIsPageScrolling>;
 
   constructor(initialProps?: StaticProps & ChangeableProps, canInit = true) {
@@ -84,80 +89,88 @@ export class SlideProgress<
 
     const { container } = this.props;
 
-    // create animation frame
+    // Create the animation frame
     this._animationFrame = new AnimationFrame();
     this._animationFrame.addCallback('frame', () =>
       this._handleAnimationFrame(),
     );
 
-    // create dragger
+    // Create the dragger
     this._dragger = new DraggerMove({ container });
     this._dragger.addCallback('move', (event) => this._handleDrag(event));
     this._dragger.addCallback('start', ({ event }) => event.stopPropagation());
     this._dragger.addCallback('end', () => this._handleDragEnd());
 
-    // add wheel event
+    // Add wheel event listener
     this.addEventListener(container, 'wheel', (event) =>
       this._handleWheel(event),
     );
 
-    // create is page scrolling
+    // Create page scrolling check
     this._createIsPageScrolling = createIsPageScrolling();
 
-    // initialize the class
+    // Initialize the class
     if (canInit) {
       this.init();
     }
   }
 
+  /**
+   * Handles mutation of properties.
+   */
   protected _onPropsMutate() {
     super._onPropsMutate();
 
     this._dragger.changeProps({ isEnabled: this.props.hasDrag });
   }
 
-  /** Handle wheel event */
+  /**
+   * Handles wheel events for adjusting progress.
+   * @param event - The wheel event.
+   */
   protected _handleWheel(event: WheelEvent) {
     if (this._timelineTo || !this.props.hasWheel) {
       return;
     }
 
-    // clear sticky timeout
+    // Clear sticky timeout
     if (this._stickyEndTimeout) {
       clearTimeout(this._stickyEndTimeout);
       this._stickyEndTimeout = undefined;
     }
 
-    // vars
+    // Vars
     const { _progressLerp: progress } = this;
     const { container, min, max, wheelSpeed } = this.props;
 
-    // update handler
+    // Update handler
     this._currentHandler = 'wheel';
 
-    // normalize wheel
+    // Normalize wheel data
     const wheel = normalizeWheel(event);
     const y = (wheel.pixelY / container.clientHeight) * wheelSpeed;
 
-    // update direction
+    // Update direction and target progress
     this._wheelIntensity += y;
     this._direction = this._wheelIntensity > 0 ? 1 : -1;
-
-    // update target
     progress.target = clamp(progress.target + y, [min, max]);
+
     this._animationFrame.play();
 
-    // go sticky
+    // Set timeout for sticky behavior
     this._stickyEndTimeout = setTimeout(() => {
       this._wheelIntensity = 0;
       this._goStickyEnd();
     }, 100);
 
-    // callbacks
+    // Callbacks
     this.callbacks.tbt('wheel', wheel);
   }
 
-  /** Check if can move */
+  /**
+   * Checks if dragging is allowed.
+   * @param absDiff - Absolute difference in dragging distance.
+   */
   protected _checkCanDragMove(absDiff: NDraggerBase.IVector2) {
     const { dragDirection, dragThreshold } = this.props;
 
@@ -180,7 +193,10 @@ export class SlideProgress<
     return false;
   }
 
-  /** Handle drag move event */
+  /**
+   * Handles the drag movement for adjusting progress.
+   * @param data - The drag event data.
+   */
   protected _handleDrag(data: NDraggerMove.IMoveParameter) {
     const isPageScrolling = this._createIsPageScrolling.get();
 
@@ -201,11 +217,10 @@ export class SlideProgress<
     }
     event.stopPropagation();
 
-    // update handler
+    // Update handler
     this._currentHandler = 'drag';
 
-    // drag logic
-
+    // Drag logic
     const defaultIterator = dragDirection === 'y' ? step.y : step.x;
     const iteratorDivider =
       dragDirection === 'y' ? container.clientHeight : container.clientWidth;
@@ -218,18 +233,23 @@ export class SlideProgress<
 
     this._animationFrame.play();
 
-    // callbacks
+    // Callbacks
     this.callbacks.tbt('dragMove', data);
   }
 
-  /** Handler drag end event */
+  /**
+   * Handles the end of a drag event and triggers sticky behavior.
+   */
   private _handleDragEnd() {
     this._canDragMove = false;
 
     this._goStickyEnd();
   }
 
-  /** Get nearest stepped value to given progress */
+  /**
+   * Gets the nearest step value to the given progress value.
+   * @param value - The progress value.
+   */
   protected _getNearestStep(value: number) {
     const { step, stepThreshold: stepThresholdProp, dragSpeed } = this.props;
     const threshold = clamp(stepThresholdProp, [0.001, 0.5]);
@@ -255,11 +275,13 @@ export class SlideProgress<
     return Math.round(value / this.props.step) * this.props.step;
   }
 
-  /** Callback on animation frame */
+  /**
+   * Handles the animation frame and updates the progress values.
+   */
   protected _handleAnimationFrame() {
     const { _progressLerp: progress } = this;
     const { ease, friction, step } = this.props;
-    const { easeMultiplier } = this._animationFrame;
+    const { fpsMultiplier } = this._animationFrame;
 
     const nearestSteppedProgress = this._getNearestStep(progress.target);
 
@@ -267,11 +289,11 @@ export class SlideProgress<
       progress.target = lerp(
         progress.target,
         nearestSteppedProgress,
-        friction * ease * easeMultiplier,
+        friction * ease * fpsMultiplier,
         0,
       );
 
-      this._updateCurrentProgress(ease * easeMultiplier);
+      this._updateCurrentProgress(ease * fpsMultiplier);
 
       if (
         progress.current === progress.target &&
@@ -284,12 +306,17 @@ export class SlideProgress<
     this.render();
   }
 
-  /** Render scene */
+  /**
+   * Renders the component and triggers any necessary callbacks.
+   */
   public render() {
     this.callbacks.tbt('render', undefined);
   }
 
-  /** Interpolate current progress & launch callbacks if needed */
+  /**
+   * Updates the current progress and triggers callbacks if necessary.
+   * @param ease - The ease value for interpolation.
+   */
   protected _updateCurrentProgress(ease: number) {
     const progress = this._progressLerp;
 
@@ -304,7 +331,9 @@ export class SlideProgress<
     }
   }
 
-  /** Sticky to the nearest step */
+  /**
+   * Sticks the progress to the nearest step at the end of user interaction.
+   */
   protected _goStickyEnd() {
     const { stickyEndDuration } = this.props;
 
@@ -328,7 +357,9 @@ export class SlideProgress<
     });
   }
 
-  /** Animate progress to a certain value */
+  /**
+   * Animates the progress to a specific value.
+   */
   public to({
     value: endValue,
     duration: durationProp = 500,
@@ -370,7 +401,9 @@ export class SlideProgress<
     this._animationFrame.play();
   }
 
-  /** Destroy the module */
+  /**
+   * Destroys the component and clears all timeouts and resources.
+   */
   protected _destroy() {
     super._destroy();
 

package/src/components/SlideProgress/types.ts

@@ -5,88 +5,97 @@ import { NDraggerMove } from '../DraggerMove';
 
 export namespace NSlideProgress {
   export interface IStaticProps extends NComponent.IStaticProps {
-    /** HTML Container */
+    /** HTML container element where the component is applied */
     container: HTMLElement;
   }
 
   export interface IChangeableProps extends NComponent.IChangeableProps {
-    /** Minimum progress value */
+    /** Minimum value of the progress */
     min: number;
-    /** Maximum progress value */
+    /** Maximum value of the progress */
     max: number;
-    /** Progress step */
+    /** The step size for progress increments */
     step: number;
     /**
-     * Step threshold (from 0.001 to 0.5)
+     * Threshold to determine step size changes. Ranges from 0.001 to 0.5.
      * @default 0.1
      */
     stepThreshold?: number;
     /**
-     * Linear interpolation ease
+     * Linear interpolation easing factor
      * @default 0.1
      */
     ease?: number;
     /**
-     * Linear interpolation friction
+     * Friction applied during interpolation
      * @default 0.5
      */
     friction?: number;
     /**
-     * Use drag events
+     * Enable or disable drag events for progress control
      * @default true
      */
     hasDrag?: boolean;
     /**
-     * Dragger speed
+     * Speed factor for dragging movements
      * @default 1
      */
     dragSpeed?: number;
     /**
-     * Dragger direction
+     * Direction of the drag movement (either 'x' or 'y')
      * @default 'y'
      */
     dragDirection?: 'x' | 'y';
     /**
-     * Use wheel events
+     * Enable or disable mouse wheel events for progress control
      * @default true
      */
     hasWheel?: boolean;
     /**
-     * Wheel speed
+     * Speed factor for mouse wheel movements
      * @default 1
      */
     wheelSpeed?: number;
     /**
-     * Duration of sticky animation to the nearest step. If nullable, the animation is disabled.
+     * Duration for sticky animation to snap to the nearest step. If `null`, sticky animation is disabled.
      * @default 500
      */
     stickyEndDuration?: TDuration | null;
     /**
-     * Drag threshold
+     * Minimum threshold for drag movements (in pixels).
      * @default 3
      */
     dragThreshold?: number;
   }
 
   export interface ICallbacksTypes extends NComponent.ICallbacksTypes {
+    /** Fired during the rendering process */
     render: undefined;
+    /** Fired when a step is completed */
     step: undefined;
+    /** Fired when a wheel event is detected */
     wheel: TNormalizeWheel;
+    /** Fired when a drag event moves the slider */
     dragMove: NDraggerMove.IMoveParameter;
   }
 
   export interface IWithLerp {
+    /** Current progress value */
     current: number;
+    /** Target progress value */
     target: number;
   }
 
   export type TDuration = number | ((multiplier: number) => number);
 
   export interface IToProps {
+    /** Target progress value */
     value: number;
-    /** @default 500 */
+    /** Duration of the animation (in ms or function). Default is `500`. */
     duration?: TDuration;
+    /** Callback to be fired during the animation progress */
     onProgress?: (props: NTimeline.ICallbacksTypes['progress']) => void;
+    /** Callback to be fired when the animation ends */
     onEnd?: () => void;
   }
 }

package/src/components/SplitText/index.ts

@@ -10,8 +10,9 @@ export type { NSplitText };
 
 /**
  * SplitText is a component that splits your text into lines, words, and letters so that you can animate them.
- * It supports auto-resizing for lines and styled content when using html inside your text.
- * It was inspired both by GSAP's SplitText plugin and SplitType.
+ * It supports auto-resizing for lines and styled content when using HTML inside your text.
+ *
+ * Inspired by GSAP's SplitText plugin and SplitType.
  *
  * P.S. Apply `fontKerning: none` to your container to prevent large layout shifts.
  *
@@ -46,73 +47,105 @@ export class SplitText<
     return `${getApp().prefix}split-text`;
   }
 
+  /**
+   * Class name used for individual letters.
+   */
   get letterClassName() {
     return this.className('__letter');
   }
 
+  /**
+   * Class name used for individual words.
+   */
   get wordClassName() {
     return this.className('__word');
   }
 
+  /**
+   * Class name used for individual lines.
+   */
   get lineClassName() {
     return this.className('__line');
   }
 
-  /** Initial HTML content */
+  /**
+   * Initial HTML content of the container before splitting.
+   */
   protected _initialHTML: string;
 
-  /** If the text is already split into words & letters */
+  /**
+   * Tracks if the text has already been split into base elements (words & letters).
+   */
   protected _isBaseSplit = false;
 
-  /** Text container */
+  /**
+   * The text container where the split text is stored.
+   */
   protected _container: HTMLElement;
 
-  /** Text container */
+  /**
+   * Returns the text container element.
+   */
   get container() {
     return this._container;
   }
 
-  /** Letters */
+  /**
+   * List of letter elements generated after splitting.
+   */
   protected _letters: NSplitText.ILetter[];
 
-  /** Letters */
+  /**
+   * Returns the list of letter elements.
+   */
   get letters() {
     return this._letters;
   }
 
-  /** Words */
+  /**
+   * List of word elements generated after splitting.
+   */
   protected _words: NSplitText.IWord[];
 
-  /** Words */
+  /**
+   * Returns the list of word elements.
+   */
   get words() {
     return this._words;
   }
 
-  /** Lines */
+  /**
+   * List of line elements generated after splitting.
+   */
   protected _lines: NSplitText.ILine[];
 
-  /** Lines */
+  /**
+   * Returns the list of line elements.
+   */
   get lines() {
     return this._lines;
   }
 
-  /** What `wrapLines` returns */
+  /**
+   * Result from `wrapLines` utility used to manage the split lines.
+   * @ignore
+   */
   protected _lineWrapper?: ReturnType<typeof wrapLines>;
 
   constructor(initialProps: StaticProps & ChangeableProps, canInit = true) {
     super(initialProps, false);
 
-    // get text container
+    // Get text container
     this._container = selectOne(this.props.container) as HTMLElement;
     this.toggleClassName(this._container, this.className(''), true);
 
-    // attributes
+    // Disable translation for text elements
     this._container.translate = false;
 
-    // save initial html
+    // Store initial HTML content
     this._initialHTML = this._container.innerHTML;
 
-    // set default vars
+    // Initialize default properties
     this._letters = [];
     this._words = [];
     this._lines = [];
@@ -122,13 +155,18 @@ export class SplitText<
     }
   }
 
+  /**
+   * Initializes the component.
+   */
   protected _init() {
     super._init();
 
     this._setResize();
   }
 
-  /** Set resize events */
+  /**
+   * Sets up resize events for the component, allowing it to respond to viewport or container size changes.
+   */
   protected _setResize() {
     const { viewportTarget, resizeDebounce, hasLines } = this.props;
 
@@ -150,24 +188,24 @@ export class SplitText<
     this.addDestroyableAction(() => resizeHandler.remove());
   }
 
-  /** Split the text */
+  /**
+   * Splits the text in the container into letters, words, and optionally lines, based on the component properties.
+   */
   public splitText() {
-    // launch callbacks
     this.callbacks.tbt('beforeSplit', undefined);
 
-    // split intro base elements
     this._splitBase();
 
-    // split text into lines
     if (this.props.hasLines) {
       this._splitIntoLines();
     }
 
-    // launch callbacks
     this.callbacks.tbt('split', undefined);
   }
 
-  /** Split base */
+  /**
+   * Splits the text into base elements (letters and words).
+   */
   private _splitBase() {
     if (this._isBaseSplit) {
       return;
@@ -178,8 +216,6 @@ export class SplitText<
 
     this._isBaseSplit = true;
 
-    // split text
-
     const { helper, words, letters } = splitBase({
       container,
       letterClassName,
@@ -189,22 +225,24 @@ export class SplitText<
       wordTag,
     });
 
-    // append nodes
-
+    // Clear the original content
     while (container.childNodes[0]) {
       container.childNodes[0].remove();
     }
 
+    // Append the new elements
     while (helper.childNodes[0]) {
       container.appendChild(helper.childNodes[0]);
     }
 
-    // update elements
+    // Update elements
     this._words = words;
     this._letters = letters;
   }
 
-  /** Split the text into lines */
+  /**
+   * Splits the text into lines by wrapping word elements into line containers.
+   */
   protected _splitIntoLines() {
     const { container, words, lineClassName } = this;
     const { lineTag } = this.props;
@@ -226,7 +264,9 @@ export class SplitText<
     this._lines = this._lineWrapper.lines;
   }
 
-  /** Destroy the module */
+  /**
+   * Destroys the component, restoring the container to its initial HTML state.
+   */
   protected _destroy() {
     super._destroy();