vevet 3.19.2 → 4.0.0-beta.0

package/src/components/SplitText/types.ts

@@ -4,41 +4,49 @@ import { TOnResizeTarget } from '@/utils/listeners/onResize';
 export namespace NSplitText {
   export interface IStaticProps extends NComponent.IStaticProps {
     /**
-     * The text container. You may use a CSS selector or the element itself
+     * The text container where the content will be split.
+     * Can be a CSS selector (string) or an actual HTML element.
      */
     container: string | Element;
+
     /**
-     * If need to split text into letters.
+     * Specifies whether the text should be split into individual letters.
      * @default true
      */
     hasLetters?: boolean;
+
     /**
-     * If need to split text into lines.
+     * Specifies whether the text should be split into lines.
      * @default false
      */
     hasLines?: boolean;
+
     /**
-     * Letter tagName
+     * HTML tag to wrap each letter.
      * @default `span`
      */
     letterTag?: keyof HTMLElementTagNameMap;
+
     /**
-     * Word tagName
+     * HTML tag to wrap each word.
      * @default `span`
      */
     wordTag?: keyof HTMLElementTagNameMap;
+
     /**
-     * Line tagName
+     * HTML tag to wrap each line.
      * @default `span`
      */
     lineTag?: keyof HTMLElementTagNameMap;
+
     /**
-     * Viewport target
+     * Determines the viewport target for resizing behavior.
      * @default 'any'
      */
     viewportTarget?: TOnResizeTarget;
+
     /**
-     * Timeout of resize event
+     * Debounce timeout for the resize event in milliseconds.
      * @default 0
      */
     resizeDebounce?: number;
@@ -47,23 +55,55 @@ export namespace NSplitText {
   export interface IChangeableProps extends NComponent.IChangeableProps {}
 
   export interface ICallbacksTypes extends NComponent.ICallbacksTypes {
+    /**
+     * Fired before the text is split.
+     */
     beforeSplit: undefined;
+
+    /**
+     * Fired after the text has been split.
+     */
     split: undefined;
   }
 
   export interface ILine {
+    /**
+     * HTML element representing a single line of split text.
+     */
     element: HTMLElement;
+
+    /**
+     * Array of word objects within the line.
+     */
     words: NSplitText.IWord[];
   }
 
   export interface IWord {
+    /**
+     * HTML element representing a single word.
+     */
     element: HTMLElement;
+
+    /**
+     * The text content of the word.
+     */
     text: string;
+
+    /**
+     * Array of letter objects within the word.
+     */
     letters: NSplitText.ILetter[];
   }
 
   export interface ILetter {
+    /**
+     * HTML element representing a single letter.
+     */
     element: HTMLElement;
+
+    /**
+     * The text content of the letter.
+     */
     text: string;
   }
 }

package/src/components/SplitText/utils/splitBase.ts

@@ -1,4 +1,3 @@
-/* eslint-disable no-param-reassign */
 import { NSplitText } from '../types';
 import { wrapLetters } from './wrapLetters';
 import { wrapWords } from './wrapWords';
@@ -12,7 +11,9 @@ interface IProps {
   wordTag: keyof HTMLElementTagNameMap;
 }
 
-/** Split text into letters & words */
+/**
+ * Splits text in the container into words and optionally into letters.
+ */
 export function splitBase({
   container,
   letterClassName,
@@ -21,8 +22,10 @@ export function splitBase({
   letterTag,
   wordTag,
 }: IProps) {
+  // Clone the container to manipulate the DOM without affecting the original
   const helper = container.cloneNode(true) as HTMLElement;
 
+  // Wrap the text into words
   const words = wrapWords({
     container: helper,
     classname: wordClassName,
@@ -31,6 +34,7 @@ export function splitBase({
 
   const letters: NSplitText.ILetter[] = [];
 
+  // If enabled, wrap words into letters
   if (hasLetters) {
     const wrappedLetters = wrapLetters({
       words,

package/src/components/SplitText/utils/wrapLetters.ts

@@ -6,10 +6,13 @@ interface IProps {
   tagName: keyof HTMLElementTagNameMap;
 }
 
-/** Wrap each word inside the container */
+/**
+ * Wraps each letter in every word inside the container with the specified HTML tag and class name.
+ */
 export function wrapLetters({ words, classname, tagName }: IProps) {
   const letters: NSplitText.ILetter[] = [];
 
+  // Iterate over each word to wrap its letters
   words.forEach((word) => {
     const textNode = word.element.childNodes[0];
     const text = textNode.textContent;
@@ -18,22 +21,27 @@ export function wrapLetters({ words, classname, tagName }: IProps) {
       return;
     }
 
-    const slitLetters = text.split('');
+    // Split the word into individual letters
+    const splitLetters = text.split('');
 
-    slitLetters.forEach((splitLetter) => {
+    splitLetters.forEach((splitLetter) => {
+      // Create a new element for each letter
       const element = document.createElement(tagName);
       element.style.display = 'inline-block';
       element.classList.add(classname);
       element.appendChild(document.createTextNode(splitLetter));
 
+      // Append the letter element to the word's container
       word.element.appendChild(element);
 
       const letter: NSplitText.ILetter = { element, text: splitLetter };
 
+      // Add the letter to the word's letters array and the global letters array
       word.letters.push(letter);
       letters.push(letter);
     });
 
+    // Remove the original text node after wrapping the letters
     textNode.remove();
   });
 

package/src/components/SplitText/utils/wrapLines.ts

@@ -13,6 +13,9 @@ interface ILine extends NSplitText.ILine {
   nodes: Node[];
 }
 
+/**
+ * Recursively retrieves the top parent element of a given element within a container.
+ */
 function getTopParent(ref: Element | null, topParent: Element): Element {
   if (ref?.parentElement === topParent) {
     return ref;
@@ -21,13 +24,15 @@ function getTopParent(ref: Element | null, topParent: Element): Element {
   return getTopParent(ref?.parentElement ?? null, topParent);
 }
 
-/** Wrap each word inside the container */
+/**
+ * Wraps each word in the container into lines, based on their vertical position.
+ */
 export function wrapLines({ container, words, className, tagName }: IProps) {
   const lines: ILine[] = [];
   let lineIndex = -1;
   let prevTop = Infinity;
 
-  // create lines
+  // Create lines by wrapping words
   words.forEach((word) => {
     const currentTop = Math.round(word.element.getBoundingClientRect().top);
     const topParent = getTopParent(word.element, container);
@@ -56,14 +61,14 @@ export function wrapLines({ container, words, className, tagName }: IProps) {
     }
   });
 
-  // append lines
+  // Append line elements to the container
   lines.forEach((line) => {
     container.insertBefore(line.element, line.nodes[0]);
 
     line.element.append(...line.nodes);
   });
 
-  // hide extra br
+  // Hide any extra <br> elements after lines
   const hiddenBr: HTMLBRElement[] = [];
   lines.forEach((line) => {
     const nextSibling = line.element.nextElementSibling;
@@ -73,13 +78,14 @@ export function wrapLines({ container, words, className, tagName }: IProps) {
     }
   });
 
-  // add words
+  // Associate words with the corresponding lines
   lines.forEach((line) => {
     line.words.push(
       ...words.filter((word) => childOf(word.element, line.element)),
     );
   });
 
+  // Destroy method to undo the line wrapping
   const destroy = () => {
     hiddenBr.forEach((br) => {
       br.style.display = '';

package/src/components/SplitText/utils/wrapWords.ts

@@ -1,19 +1,25 @@
+/* eslint-disable no-param-reassign */
 import { NSplitText } from '../types';
 
-/* eslint-disable no-param-reassign */
 interface IProps {
   container: ChildNode;
   classname: string;
   tagName: keyof HTMLElementTagNameMap;
 }
 
-/** Wrap each word inside the container */
+/**
+ * Wraps each word inside the container in an HTML element with the specified tag and class.
+ */
 export function wrapWords({ container, classname, tagName }: IProps) {
-  const whitespace = String.fromCharCode(32);
+  const whitespace = String.fromCharCode(32); // ASCII for space
 
   const words: NSplitText.IWord[] = [];
 
+  /**
+   * Recursively processes each child node within the container to wrap words.
+   */
   function recursive(node: ChildNode) {
+    // If the node is an element, process its children
     if (node instanceof HTMLElement) {
       if (node.tagName !== 'BR') {
         node.style.display = 'inline-block';
@@ -25,11 +31,13 @@ export function wrapWords({ container, classname, tagName }: IProps) {
       return;
     }
 
+    // If the node is a text node, split it into words
     if (node.nodeType === 3) {
       const nodeParent = node.parentElement;
       const text = node.nodeValue ?? '';
       const splitWords = text.split(whitespace);
 
+      // Handle case where node contains only whitespace
       if (text === whitespace) {
         nodeParent?.insertBefore(document.createTextNode(whitespace), node);
         node.remove();
@@ -37,6 +45,7 @@ export function wrapWords({ container, classname, tagName }: IProps) {
         return;
       }
 
+      // Wrap each word in an element and insert it into the DOM
       splitWords.forEach((splitWord, index) => {
         if (splitWord) {
           const element = document.createElement(tagName);
@@ -49,6 +58,7 @@ export function wrapWords({ container, classname, tagName }: IProps) {
           nodeParent?.insertBefore(element, node);
         }
 
+        // Add a space between words, except after the last word
         if (index < splitWords.length - 1) {
           nodeParent?.insertBefore(document.createTextNode(whitespace), node);
         }
@@ -58,6 +68,7 @@ export function wrapWords({ container, classname, tagName }: IProps) {
     }
   }
 
+  // Begin processing the container
   recursive(container);
 
   return words;

package/src/components/Timeline/index.ts

@@ -1,53 +1,102 @@
-import { clamp } from '@/utils/math';
-import { BaseTimeline } from '../BaseTimeline';
+import { clamp, easing } from '@/utils/math';
 import { NTimeline } from './types';
+import { getApp } from '@/utils/internal/getApp';
+import { Component as ComponentClass } from '@/base/Component';
 
 export type { NTimeline };
 
 /**
- * Animation timeline
+ * Animation timeline that handles time-based animations with progress, easing, play, reverse, and pause functionality.
  */
 export class Timeline<
   StaticProps extends NTimeline.IStaticProps = NTimeline.IStaticProps,
   ChangeableProps extends
     NTimeline.IChangeableProps = NTimeline.IChangeableProps,
   CallbacksTypes extends NTimeline.ICallbacksTypes = NTimeline.ICallbacksTypes,
-> extends BaseTimeline<StaticProps, ChangeableProps, CallbacksTypes> {
+> extends ComponentClass<StaticProps, ChangeableProps, CallbacksTypes> {
   protected _getDefaultProps() {
     return {
       ...super._getDefaultProps(),
+      easing: getApp().props.easing,
+      isDestroyedOnEnd: false,
       duration: 1000,
-      shouldDestroyOnEnd: false,
     };
   }
 
-  /** The animation frame */
+  /**
+   * Global timeline progress, from 0 (start) to 1 (end).
+   */
+  protected _p: number;
+
+  /**
+   * Global timeline progress. Can be manually set, triggering updates.
+   */
+  get p() {
+    return this._p;
+  }
+
+  set p(val: number) {
+    this._p = val;
+
+    this._handleProgressUpdate();
+  }
+
+  /**
+   * Eased progress of the timeline, calculated based on the easing function.
+   */
+  protected _e: number;
+
+  /**
+   * Eased progress, which applies the easing function to the global progress.
+   */
+  get e() {
+    return this._e;
+  }
+
+  /**
+   * Stores the requestAnimationFrame ID for the ongoing animation.
+   */
   protected _raf?: number;
 
-  /** Last time when animationFrame callback has been called */
+  /**
+   * Stores the time of the last animation frame.
+   */
   protected _rafTime: number;
 
-  /** Timeline is playing */
+  /**
+   * Indicates if the timeline is currently playing.
+   */
   get isPlaying() {
     return typeof this._raf !== 'undefined';
   }
 
-  /** Timeline is reversed */
+  /**
+   * Indicates if the timeline is playing in reverse.
+   */
   protected _isReversed: boolean;
 
-  /** Timeline is reversed */
+  /**
+   * Returns whether the timeline is reversed.
+   */
   get isReversed() {
     return this._isReversed;
   }
 
-  /** Timeline is paused */
+  /**
+   * Indicates if the timeline is paused.
+   */
   protected _isPaused: boolean;
 
-  /** Timeline is paused */
+  /**
+   * Returns whether the timeline is paused.
+   */
   get isPaused() {
     return this._isPaused;
   }
 
+  /**
+   * Returns the duration of the timeline, ensuring a minimum duration of 1 ms.
+   */
   get duration() {
     return Math.max(this.props.duration, 1);
   }
@@ -55,7 +104,9 @@ export class Timeline<
   constructor(initialProps?: StaticProps & ChangeableProps, canInit = true) {
     super(initialProps, false);
 
-    // set default variables
+    // Set default variables
+    this._p = 0;
+    this._e = 0;
     this._raf = undefined;
     this._rafTime = 0;
     this._isReversed = false;
@@ -66,7 +117,10 @@ export class Timeline<
     }
   }
 
-  /** Play the timeline */
+  /**
+   * Plays the timeline, advancing progress from its current state toward completion.
+   * Will not play if the timeline has already been destroyed or has fully completed.
+   */
   public play() {
     if (this.isDestroyed || this.p === 1) {
       return;
@@ -81,7 +135,10 @@ export class Timeline<
     }
   }
 
-  /** Reverse timeline */
+  /**
+   * Reverses the timeline, moving progress from its current state toward the start.
+   * Will not reverse if the timeline has already been destroyed or is at the start.
+   */
   public reverse() {
     if (this.isDestroyed || this.p === 0) {
       return;
@@ -96,7 +153,9 @@ export class Timeline<
     }
   }
 
-  /** Pause animation */
+  /**
+   * Pauses the timeline's progress, stopping the animation at its current state.
+   */
   public pause() {
     if (this.isDestroyed) {
       return;
@@ -110,7 +169,9 @@ export class Timeline<
     this._raf = undefined;
   }
 
-  /** Reset timeline */
+  /**
+   * Resets the timeline to the beginning (progress = 0).
+   */
   public reset() {
     if (this.isDestroyed) {
       return;
@@ -120,7 +181,9 @@ export class Timeline<
     this.p = 0;
   }
 
-  /** Start animation */
+  /**
+   * Starts the animation process, updating the timeline's progress based on elapsed time.
+   */
   protected _animate() {
     if (this.isPaused) {
       return;
@@ -128,17 +191,17 @@ export class Timeline<
 
     const { isReversed } = this;
 
-    // calculate difference between frames
+    // Calculate time difference between frames
     const currentTime = Date.now();
     const frameDiff = Math.abs(this._rafTime - currentTime);
     this._rafTime = currentTime;
 
-    // calculate current progress
+    // Calculate current progress
     const progressIterator = frameDiff / this.duration / (isReversed ? -1 : 1);
     const progressTarget = clamp(this.p + progressIterator, [0, 1]);
     this.p = progressTarget;
 
-    // end animation
+    // End animation if progress reaches start or end
     if (
       (progressTarget === 1 && !isReversed) ||
       (progressTarget === 0 && isReversed)
@@ -150,13 +213,20 @@ export class Timeline<
       return;
     }
 
-    // continue animation
+    // Continue animation
     this._raf = window.requestAnimationFrame(this._animate.bind(this));
   }
 
-  /** Events on progress */
+  /**
+   * Handles updates to the timeline's progress and triggers associated callbacks.
+   */
   protected _handleProgressUpdate() {
-    super._handleProgressUpdate();
+    this._e = easing(this._p, this.props.easing);
+
+    this.callbacks.tbt('progress', {
+      p: this._p,
+      e: this._e,
+    });
 
     if (this.p === 0) {
       this.callbacks.tbt('start', undefined);
@@ -167,13 +237,15 @@ export class Timeline<
     if (this.p === 1) {
       this.callbacks.tbt('end', undefined);
 
-      if (this.props.shouldDestroyOnEnd) {
+      if (this.props.isDestroyedOnEnd) {
         this.destroy();
       }
     }
   }
 
-  /** Destroy the timeline */
+  /**
+   * Destroys the timeline, pausing any ongoing animation and cleaning up resources.
+   */
   protected _destroy() {
     this.pause();
 

package/src/components/Timeline/stories/index.stories.tsx

@@ -1,7 +1,6 @@
 import React from 'react';
 import type { Meta, StoryFn } from '@storybook/react';
 import { Basic } from './Basic';
-import { Nested } from './Nested';
 
 const meta: Meta = {
   title: 'Components/Timeline',
@@ -10,7 +9,3 @@ const meta: Meta = {
 export default meta;
 
 export const Default: StoryFn<typeof Basic> = (props) => <Basic {...props} />;
-
-export const WithNested: StoryFn<typeof Nested> = (props) => (
-  <Nested {...props} />
-);

package/src/components/Timeline/types.ts

@@ -1,24 +1,54 @@
-import { NBaseTimeline } from '../BaseTimeline';
+import { NComponent } from '@/base/Component';
+import { IVevetProps } from '@/src/Vevet/types';
 
 export namespace NTimeline {
-  export interface IStaticProps extends NBaseTimeline.IStaticProps {
+  export interface IStaticProps extends NComponent.IStaticProps {
     /**
-     * Destroy the timeline on animation end
+     * Easing function for the timeline animation.
+     */
+    easing?: IVevetProps['easing'];
+
+    /**
+     * Whether to destroy the timeline when the animation ends.
      * @default false
      */
-    shouldDestroyOnEnd?: boolean;
+    isDestroyedOnEnd?: boolean;
   }
 
-  export interface IChangeableProps extends NBaseTimeline.IChangeableProps {
+  export interface IChangeableProps extends NComponent.IChangeableProps {
     /**
-     * Timeline duration
+     * Duration of the timeline animation in milliseconds.
      * @default 1000
      */
     duration?: number;
   }
 
-  export interface ICallbacksTypes extends NBaseTimeline.ICallbacksTypes {
+  export interface ICallbacksTypes extends NComponent.ICallbacksTypes {
+    /**
+     * Triggered when the timeline starts.
+     */
     start: undefined;
+
+    /**
+     * Triggered during timeline progress updates.
+     */
+    progress: IProgressParameter;
+
+    /**
+     * Triggered when the timeline reaches the end.
+     */
     end: undefined;
   }
+
+  export interface IProgressParameter {
+    /**
+     * Current progress of the timeline, ranging from 0 to 1.
+     */
+    p: number;
+
+    /**
+     * Eased progress value based on the easing function.
+     */
+    e: number;
+  }
 }

package/src/components/index.ts

@@ -1,8 +1,8 @@
 export * from './AnimationFrame';
-export * from './BaseTimeline';
 export * from './Ctx2D';
 export * from './Ctx2DPrerender';
 export * from './CustomCursor';
+export * from './DraggerBase';
 export * from './DraggerDirection';
 export * from './DraggerMove';
 export * from './Marquee';
@@ -12,8 +12,8 @@ export * from './ScrollBar';
 export * from './ScrollView';
 export * from './SectionScrollProgress';
 export * from './SlideProgress';
-export * from './SmoothScroll';
-export * from './SmoothScrollDragPlugin';
-export * from './SmoothScrollKeyboardPlugin';
+export * from './CustomScroll';
+export * from './CustomScrollDragPlugin';
+export * from './CustomScrollKeyboardPlugin';
 export * from './SplitText';
 export * from './Timeline';

package/src/index.ts

@@ -1,11 +1,21 @@
-export * from './types/general';
+import { getApp } from './utils/internal/getApp';
+import { IVevet } from './Vevet/global';
 
-export * from './utils';
+/**
+ * Vevet Application
+ *
+ * @see {@linkcode IVevet}
+ */
+export const vevet = (
+  typeof window !== 'undefined' ? getApp() : undefined
+) as IVevet;
+
+export * from './Vevet/exported';
 
-export * from './Application';
+export * from './utils';
 
 export * from './base';
 
 export * from './components';
 
-// TODO: add jsdoc examples
+export * from './types';

package/src/styles/base.scss

@@ -1,3 +1 @@
-$prefix: 'v-' !default;
-
 @import './mixins/index';