vevet 4.4.2 → 5.0.0

package/src/components/Snap/types.ts

@@ -0,0 +1,164 @@
+import {
+  IModuleCallbacksMap,
+  IModuleMutableProps,
+  IModuleStaticProps,
+} from '@/base';
+import { SnapSlide } from './Slide';
+import { TEasingType } from '@/utils/math';
+import { ISnapWheelProps } from './Wheel/types';
+import { ISnapSwipeProps } from './Swipe/types';
+import { ISwipeCoords } from '../Swipe';
+import { ITimelineProgressArg } from '../Timeline';
+
+/** Static properties for the Snap component */
+export interface ISnapStaticProps extends IModuleStaticProps {
+  /** HTML container element where listeners are attached */
+  container: HTMLElement;
+  /**
+   * Default active index
+   * @default 0
+   */
+  activeIndex?: number;
+}
+
+/** Mutable properties for the Snap component */
+export interface ISnapMutableProps
+  extends IModuleMutableProps,
+    ISnapWheelProps,
+    ISnapSwipeProps {
+  /**
+   * Slides instances. If `false`, all container's children will be considered as slides.
+   * @default false
+   */
+  slides?: (HTMLElement | SnapSlide)[] | false;
+
+  /**
+   * Sliding direction
+   * @default 'horizontal'
+   */
+  direction?: 'horizontal' | 'vertical';
+
+  /**
+   * Centered slides
+   * @default false
+   */
+  centered?: boolean;
+
+  /**
+   * Detects if need to loop the progress
+   * @default false
+   */
+  loop?: boolean;
+
+  /**
+   * The gap between slides. Supports css units like `px`, `rem`, `vw`, `vh`, `svh`.
+   * @default 0
+   */
+  gap?: number | string;
+
+  /**
+   * Linear interpolation factor for smooth coordinates updates.
+   * @default 0.2
+   */
+  lerp?: number;
+
+  /**
+   * Disables `friction` and snapping to the nearest slide.
+   * @default false
+   */
+  freemode?: boolean;
+
+  /**
+   * Stick to the nearest slide on window resize
+   * @default true
+   */
+  stickOnResize?: boolean;
+
+  /**
+   * Friction that makes the slides tend to the nearest slide magnet. The value is a number between 0 and 1
+   * which is multiplied by the `lerp` value.
+   * 0 disables friction
+   * @default 0.15
+   */
+  friction?: number;
+
+  /**
+   * Maximum friction between the final slide and the maximum translation value.
+   * From 0 to 1. The higher value the more resistance is applied.
+   * @default 0.85
+   */
+  edgeFriction?: number;
+
+  /**
+   * Change slide duration
+   * @default 500
+   */
+  duration?: TSnapDuration;
+
+  /**
+   * Easing type for timelines
+   * @default EaseOutCubic
+   */
+  easing?: TEasingType;
+}
+
+/** Callbacks map for the Snap component */
+export interface ISnapCallbacksMap extends IModuleCallbacksMap {
+  /** Fired on resize */
+  resize: undefined;
+
+  /** Fired on reflow: staticValues update */
+  reflow: undefined;
+
+  /** Fired during the rendering process */
+  update: undefined;
+
+  /** Fired after active slide change */
+  activeSlide: SnapSlide;
+
+  /** Fired on requestAnimationFrame play */
+  rafPlay?: undefined;
+
+  /** Fired on requestAnimationFrame pause */
+  rafPause?: undefined;
+
+  /** Fired on wheel start */
+  wheelStart: undefined;
+
+  /** Fired on wheel event */
+  wheel: WheelEvent;
+
+  /** Fired on wheel end */
+  wheelEnd: undefined;
+
+  /** Fired on swipe start */
+  swipeStart: ISwipeCoords;
+
+  /** Fired on swipe move */
+  swipe: ISwipeCoords;
+
+  /** Fired on swipe end */
+  swipeEnd: ISwipeCoords;
+
+  /** Fired on timeline animation start */
+  timelineStart: undefined;
+
+  /** Fired on timeline animation update */
+  timelineUpdate: ITimelineProgressArg;
+
+  /** Fired on timeline animation end */
+  timelineEnd: undefined;
+}
+
+export type TSnapDuration = number | ((distance: number) => number);
+
+export interface ISnapMagnet {
+  /** Slide */
+  slide: SnapSlide;
+  /** Magnet coordinate */
+  magnetCoord: number;
+  /** Difference between the magnet coodintate and the current track value */
+  magnetDiff: number;
+  /** Static magnet coordinate (as if the slide was never moved) */
+  staticMagnetCoord: number;
+}

package/src/components/SplitText/index.ts

@@ -1,279 +1,264 @@
-import { Component as ComponentClass } from '@/base/Component';
-import { NSplitText } from './types';
 import { onResize } from '@/utils/listeners/onResize';
 import { splitBase } from './utils/splitBase';
 import { wrapLines } from './utils/wrapLines';
-import { getApp } from '@/utils/internal/getApp';
-import { selectOne } from '@/utils/dom/selectOne';
-
-export type { NSplitText };
+import {
+  ISplitTextCallbacksMap,
+  ISplitTextLetterMeta,
+  ISplitTextLineMeta,
+  ISplitTextMutableProps,
+  ISplitTextStaticProps,
+  ISplitTextWordMeta,
+} from './types';
+import { Module } from '@/base';
+import { TRequiredProps } from '@/internal/requiredProps';
+import { initVevet } from '@/global/initVevet';
+import { saveInitialNodes } from './utils/saveInitialNodes';
+
+export * from './types';
 
 /**
- * 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.
- *
- * Inspired by GSAP's SplitText plugin and SplitType.
- *
- * P.S. Apply `fontKerning: none` to your container to prevent large layout shifts.
+ * `SplitText` splits text within a container into individual lines, words, and letters.
  *
- * @link See examples https://antonbobrov.github.io/vevet-demo/split-text/
+ * Features:
+ * - Supports resizing, HTML content, and special symbols like emojis.
+ * - Handles multi-line breaks and non-breaking spaces.
+ * - Saves initial nodes and listeners for easy restoration.
+ * - Allows splitting into lines, words, or letters as needed.
  *
- * @link See docs https://antonbobrov.github.io/vevet/classes/SplitText.html
+ * **Note**: Apply `fontKerning: none` to prevent layout shifts.
  *
- * @see Performance comparison of splitting your text into words: https://measurethat.net/Benchmarks/Show/31805/0/vevetsplittext-splittype-comparison-words-only
+ * [Documentation](https://antonbobrov.github.io/vevet/docs/components/SplitText)
  *
- * @see Performance comparison of splitting your text into words and letters: https://measurethat.net/Benchmarks/Show/31806/0/vevetsplittext-splittype-comparison-words-letters
- *
- * @see Performance comparison of splitting your text into words and lines: https://measurethat.net/Benchmarks/Show/31847/0/vevetsplittext-splittype-comparison-words-lines
+ * @group Components
  */
 export class SplitText<
-  StaticProps extends NSplitText.IStaticProps = NSplitText.IStaticProps,
-  ChangeableProps extends
-    NSplitText.IChangeableProps = NSplitText.IChangeableProps,
-  CallbacksTypes extends
-    NSplitText.ICallbacksTypes = NSplitText.ICallbacksTypes,
-> extends ComponentClass<StaticProps, ChangeableProps, CallbacksTypes> {
-  protected _getDefaultProps() {
+  CallbacksMap extends ISplitTextCallbacksMap = ISplitTextCallbacksMap,
+  StaticProps extends ISplitTextStaticProps = ISplitTextStaticProps,
+  MutableProps extends ISplitTextMutableProps = ISplitTextMutableProps,
+> extends Module<CallbacksMap, StaticProps, MutableProps> {
+  /**
+   * Retrieves the default static properties.
+   */
+  public _getStatic(): TRequiredProps<StaticProps> {
     return {
-      ...super._getDefaultProps(),
-      container: `#${this.prefix}`,
-      hasLetters: true,
-      hasLines: false,
+      ...super._getStatic(),
+      letters: false,
+      lines: false,
+      linesWrapper: false,
       letterTag: 'span',
       wordTag: 'span',
       lineTag: 'span',
-      viewportTarget: 'any',
       resizeDebounce: 0,
-    };
-  }
-
-  get prefix() {
-    return `${getApp().prefix}split-text`;
+    } as TRequiredProps<StaticProps>;
   }
 
   /**
-   * Class name used for individual letters.
+   * Retrieves the default mutable properties.
    */
-  get letterClassName() {
-    return this.className('__letter');
+  public _getMutable(): TRequiredProps<MutableProps> {
+    return { ...super._getMutable() } as TRequiredProps<MutableProps>;
   }
 
   /**
-   * Class name used for individual words.
+   * Classname prefix for styling elements.
    */
-  get wordClassName() {
-    return this.className('__word');
+  get prefix() {
+    return `${initVevet().prefix}split-text`;
   }
 
   /**
-   * Class name used for individual lines.
+   * Saved initial HTML nodes of the container.
    */
-  get lineClassName() {
-    return this.className('__line');
-  }
+  protected _savedNodes: ReturnType<typeof saveInitialNodes>;
 
   /**
-   * Initial HTML content of the container before splitting.
+   * Tracks whether the text is already split into base elements: words and letters.
    */
-  protected _initialHTML: string;
+  protected _isBaseSplit = false;
 
   /**
-   * Tracks if the text has already been split into base elements (words & letters).
+   * List of letters metadata.
    */
-  protected _isBaseSplit = false;
+  protected _lettersMeta: ISplitTextLetterMeta[] = [];
 
   /**
-   * The text container where the split text is stored.
+   * Retrieves an array of letters metadata.
    */
-  protected _container: HTMLElement;
+  get lettersMeta() {
+    return this._lettersMeta;
+  }
 
   /**
-   * Returns the text container element.
+   * Retrieves an array of letter elements.
    */
-  get container() {
-    return this._container;
+  get letters() {
+    return this._lettersMeta.map((letter) => letter.element);
   }
 
   /**
-   * List of letter elements generated after splitting.
+   * List of words metadata.
    */
-  protected _letters: NSplitText.ILetter[];
+  protected _wordsMeta: ISplitTextWordMeta[] = [];
 
   /**
-   * Returns the list of letter elements.
+   * Retrieves an array of words metadata.
    */
-  get letters() {
-    return this._letters;
+  get wordsMeta() {
+    return this._wordsMeta;
   }
 
   /**
-   * List of word elements generated after splitting.
+   * Retrieves an array of word elements.
    */
-  protected _words: NSplitText.IWord[];
+  get words() {
+    return this._wordsMeta.map((word) => word.element);
+  }
 
   /**
-   * Returns the list of word elements.
+   * List of lines metadata.
    */
-  get words() {
-    return this._words;
-  }
+  protected _linesMeta: ISplitTextLineMeta[] = [];
 
   /**
-   * List of line elements generated after splitting.
+   * Retrieves an array of lines metadata.
    */
-  protected _lines: NSplitText.ILine[];
+  get linesMeta() {
+    return this._linesMeta;
+  }
 
   /**
-   * Returns the list of line elements.
+   * Retrieves an array of line elements.
    */
   get lines() {
-    return this._lines;
+    return this._linesMeta.map((line) => line.element);
   }
 
   /**
-   * Result from `wrapLines` utility used to manage the split lines.
-   * @ignore
+   * Utility for wrapping words into line containers.
    */
-  protected _lineWrapper?: ReturnType<typeof wrapLines>;
+  protected _lineSplitWrapper?: ReturnType<typeof wrapLines>;
 
-  constructor(initialProps: StaticProps & ChangeableProps, canInit = true) {
-    super(initialProps, false);
+  /**
+   * Initializes the SplitText instance and saves the initial state.
+   */
+  constructor(props?: StaticProps & MutableProps) {
+    super(props);
 
-    // Get text container
-    this._container = selectOne(this.props.container) as HTMLElement;
-    this.toggleClassName(this._container, this.className(''), true);
+    const { container } = this.props;
 
-    // Disable translation for text elements
-    this._container.translate = false;
+    container.style.fontKerning = 'none';
+    this._addTempClassName(container, this._cn(''));
 
-    // Store initial HTML content
-    this._initialHTML = this._container.innerHTML;
+    container.translate = false;
 
-    // Initialize default properties
-    this._letters = [];
-    this._words = [];
-    this._lines = [];
+    this._savedNodes = saveInitialNodes(container);
 
-    if (canInit) {
-      this.init();
-    }
+    this._setup();
   }
 
   /**
-   * Initializes the component.
+   * Sets up event listeners and handles initial splitting.
    */
-  protected _init() {
-    super._init();
+  protected _setup() {
+    const { container, resizeDebounce } = this.props;
 
-    this._setResize();
-  }
-
-  /**
-   * 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;
-
-    if (!hasLines) {
-      this.splitText();
+    if (!this.props.lines) {
+      this.split();
 
       return;
     }
 
     const resizeHandler = onResize({
-      onResize: () => this.splitText(),
-      element: this.container,
-      viewportTarget,
+      callback: () => this.split(),
+      element: container,
+      viewportTarget: 'width',
       resizeDebounce,
+      name: this.name,
     });
 
     resizeHandler.resize();
 
-    this.addDestroyableAction(() => resizeHandler.remove());
+    this.onDestroy(() => resizeHandler.remove());
   }
 
   /**
-   * Splits the text in the container into letters, words, and optionally lines, based on the component properties.
+   * Splits the text into letters, words, and optionally lines based on configuration.
    */
-  public splitText() {
-    this.callbacks.tbt('beforeSplit', undefined);
+  public split() {
+    this.callbacks.emit('beforeSplit', undefined);
 
     this._splitBase();
 
-    if (this.props.hasLines) {
-      this._splitIntoLines();
+    if (this.props.lines) {
+      this._splitLines();
     }
 
-    this.callbacks.tbt('split', undefined);
+    this.callbacks.emit('split', undefined);
   }
 
   /**
-   * Splits the text into base elements (letters and words).
+   * Splits text into base elements: letters and words.
    */
-  private _splitBase() {
+  protected _splitBase() {
     if (this._isBaseSplit) {
       return;
     }
 
-    const { container, letterClassName, wordClassName } = this;
-    const { letterTag, wordTag } = this.props;
+    const { container, letterTag, wordTag } = this.props;
 
     this._isBaseSplit = true;
 
-    const { helper, words, letters } = splitBase({
+    const { wordsMeta, lettersMeta } = splitBase({
       container,
-      letterClassName,
-      wordClassName,
-      hasLetters: this.props.hasLetters,
+      letterClassName: this._cn('__letter'),
+      wordClassName: this._cn('__word'),
+      hasLetters: this.props.letters,
       letterTag,
       wordTag,
     });
 
-    // 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
-    this._words = words;
-    this._letters = letters;
+    this._wordsMeta = wordsMeta;
+    this._lettersMeta = lettersMeta;
   }
 
   /**
-   * Splits the text into lines by wrapping word elements into line containers.
+   * Wraps words into line containers.
    */
-  protected _splitIntoLines() {
-    const { container, words, lineClassName } = this;
-    const { lineTag } = this.props;
+  protected _splitLines() {
+    const { wordsMeta } = this;
+    const { container, lineTag } = this.props;
 
     const isHidden = container.offsetParent === null;
     if (isHidden) {
       return;
     }
 
-    this._lineWrapper?.destroy();
+    this._lineSplitWrapper?.destroy();
 
-    this._lineWrapper = wrapLines({
+    this._lineSplitWrapper = wrapLines({
       container,
-      words,
-      className: lineClassName,
+      hasLinesWrapper: this.props.linesWrapper,
+      wordsMeta,
+      lineClassName: this._cn('__line'),
+      lineWrapperClassName: this._cn('__line-wrapper'),
       tagName: lineTag,
     });
 
-    this._lines = this._lineWrapper.lines;
+    this._linesMeta = this._lineSplitWrapper.linesMeta;
   }
 
   /**
-   * Destroys the component, restoring the container to its initial HTML state.
+   * Destroys the component.
+   * This method does not restore the initial nodes. For this purpose, use `restore()`.
    */
   protected _destroy() {
     super._destroy();
 
-    this._container.innerHTML = this._initialHTML;
+    const isSuccess = this._lineSplitWrapper?.destroy();
+    this._lineSplitWrapper = undefined;
+
+    if (isSuccess) {
+      this._savedNodes.restore();
+    }
   }
 }