vevet 4.4.1 → 5.0.0

package/src/components/Swipe/types.ts

@@ -0,0 +1,219 @@
+import {
+  IModuleCallbacksMap,
+  IModuleMutableProps,
+  IModuleStaticProps,
+} from '@/base';
+import { TEasingType } from '@/utils/math/easing';
+
+export interface ISwipeStaticProps extends IModuleStaticProps {
+  /** Event listener container. */
+  container: HTMLElement | SVGElement;
+
+  /**
+   * Determines which mouse buttons trigger events.
+   * - 0: Main button pressed, usually the left button or the un-initialized state
+   * - 1: Auxiliary button pressed, usually the wheel button or the middle button (if present)
+   * - 2: Secondary button pressed, usually the right button
+   * - 3: Fourth button, typically the Browser Back button
+   * - 4: Fifth button, typically the Browser Forward button
+   *
+   * See [MouseEvent.button](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button).
+   *
+   * @default [0]
+   */
+  buttons?: number[];
+
+  /**
+   * Required pointer count to activate swiping.
+   * @default 1
+   */
+  pointers?: number;
+
+  /**
+   * Disable user selection on drag.
+   * @default true
+   */
+  disableUserSelect?: boolean;
+}
+
+export interface ISwipeMutableProps extends IModuleMutableProps {
+  /**
+   * Enables or disables swipe events.
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Calculates coordinates relative to the container.
+   * @default false
+   */
+  relative?: boolean;
+
+  /**
+   * Primary swiping axis.
+   * @default null
+   */
+  axis?: null | 'x' | 'y';
+
+  /**
+   * Shows "grab" and "grabbing" cursors during interaction.
+   * @default false
+   */
+  grabCursor?: boolean;
+
+  /**
+   * Determines if swipe should be aborted.
+   * @default `() => false`
+   */
+  willAbort?: (props: ISwipeCanMoveArg) => boolean;
+
+  /**
+   * Minimum swipe distance (px) to trigger swipe start.
+   * @default 5
+   */
+  threshold?: number;
+
+  /**
+   * Minimum duration (ms) to trigger swipe move.
+   * @default 0
+   */
+  minTime?: number;
+
+  /**
+   * Minimum swipe distance (px) for directional callbacks.
+   * @default 50
+   */
+  directionThreshold?: number;
+
+  /**
+   * Prevents edge swiping (iOS swipe-back gesture).
+   * @default true
+   */
+  preventEdgeSwipe?: boolean;
+
+  /**
+   * Edge swipe threshold (px) from the left/right edge.
+   * @default 20
+   */
+  edgeSwipeThreshold?: number;
+
+  /**
+   * Prevents `touchmove` event.
+   * @default true
+   */
+  preventTouchMove?: boolean;
+
+  /**
+   * Requires Ctrl key for swipe (mouse only).
+   * @default false
+   */
+  requireCtrlKey?: boolean;
+
+  /**
+   * Enables inertia animation.
+   * @default false
+   */
+  inertia?: boolean;
+
+  /**
+   * Inertia duration.
+   * @default `(distance) => clamp(distance, 350, 1000)`
+   */
+  inertiaDuration?: (distance: number) => number;
+
+  /**
+   * Easing function for inertia.
+   * @default EaseOutCubic
+   */
+  inertiaEasing?: TEasingType;
+
+  /**
+   * Inertia strength.
+   * @default 0.5
+   */
+  inertiaRatio?: number;
+}
+
+export interface ISwipeCallbacksMap extends IModuleCallbacksMap {
+  /** Swipe start event. */
+  start: ISwipeCoords;
+
+  /** Swipe move event. */
+  move: ISwipeCoords;
+
+  /** Swipe end event. */
+  end: ISwipeCoords;
+
+  /** Swipe from bottom to top. */
+  toTop: undefined;
+
+  /** Swipe from top to bottom. */
+  toBottom: undefined;
+
+  /** Swipe from left to right. */
+  toRight: undefined;
+
+  /** Swipe from right to left. */
+  toLeft: undefined;
+
+  /** Triggered on `touchstart` listener. Triggered before any action related to this event is processed. */
+  touchstart: TouchEvent;
+
+  /** Triggered on `touchmove` listener. Triggered before any action related to this event is processed. */
+  touchmove: TouchEvent;
+
+  /** Triggered on `mousemove` listener. Triggered before any action related to this event is processed. */
+  mousemove: MouseEvent;
+
+  /** Triggered when swipe is aborted. */
+  abort: undefined;
+
+  /** Triggered on edge swipe preventing. */
+  preventEdgeSwipe: undefined;
+
+  /** Triggered on inertia start. */
+  inertiaStart: undefined;
+
+  /** Triggered on inertia progress. */
+  inertia: undefined;
+
+  /** Triggered on inertia end. */
+  inertiaEnd: undefined;
+}
+
+export interface ISwipeVec2 {
+  x: number;
+  y: number;
+}
+
+export interface ISwipeCanMoveArg {
+  type: 'touch' | 'mouse';
+  matrix: ISwipeMatrix;
+  start: ISwipeVec2;
+  diff: ISwipeVec2;
+}
+
+export interface ISwipeMatrix extends ISwipeVec2 {
+  angle: number;
+}
+
+export interface ISwipeVelocity extends ISwipeMatrix {
+  timestamp: number;
+}
+
+export interface ISwipeCoords {
+  /** Event timestamp. */
+  timestamp: number;
+  /** Start position. */
+  start: ISwipeMatrix;
+  /** Previous position. */
+  prev: ISwipeMatrix;
+  /** Current position. */
+  current: ISwipeMatrix;
+  /** Movement offset from start. */
+  diff: ISwipeMatrix;
+  /** Movement offset from previous position. */
+  step: ISwipeMatrix;
+  /** Total accumulated movement. */
+  accum: ISwipeVec2;
+}

package/src/components/Timeline/index.ts

@@ -1,132 +1,126 @@
+import { TRequiredProps } from '@/internal/requiredProps';
+import { Module } from '@/base/Module';
 import { clamp, easing } from '@/utils/math';
-import { NTimeline } from './types';
-import { getApp } from '@/utils/internal/getApp';
-import { Component as ComponentClass } from '@/base/Component';
+import {
+  ITimelineCallbacksMap,
+  ITimelineMutableProps,
+  ITimelineStaticProps,
+} from './types';
 
-export type { NTimeline };
+export * from './types';
 
 /**
- * Animation timeline that handles time-based animations with progress, easing, play, reverse, and pause functionality.
+ * A timeline class for managing animations with easing and precise progress control.
+ * It provides methods for playing, reversing, pausing, and resetting the timeline.
  *
- * @link See examples https://antonbobrov.github.io/vevet-demo/timeline/
+ * [Documentation](https://antonbobrov.github.io/vevet/docs/components/Timeline)
  *
- * @link See docs https://antonbobrov.github.io/vevet/classes/Timeline.html
+ * @group Components
  */
 export class Timeline<
-  StaticProps extends NTimeline.IStaticProps = NTimeline.IStaticProps,
-  ChangeableProps extends
-    NTimeline.IChangeableProps = NTimeline.IChangeableProps,
-  CallbacksTypes extends NTimeline.ICallbacksTypes = NTimeline.ICallbacksTypes,
-> extends ComponentClass<StaticProps, ChangeableProps, CallbacksTypes> {
-  protected _getDefaultProps() {
+  CallbacksMap extends ITimelineCallbacksMap = ITimelineCallbacksMap,
+  StaticProps extends ITimelineStaticProps = ITimelineStaticProps,
+  MutableProps extends ITimelineMutableProps = ITimelineMutableProps,
+> extends Module<CallbacksMap, StaticProps, MutableProps> {
+  /** Get default static properties. */
+  public _getStatic(): TRequiredProps<StaticProps> {
+    return { ...super._getStatic() } as TRequiredProps<StaticProps>;
+  }
+
+  /** Get default mutable properties. */
+  public _getMutable(): TRequiredProps<MutableProps> {
     return {
-      ...super._getDefaultProps(),
-      easing: getApp().props.easing,
-      isDestroyedOnEnd: false,
+      ...super._getMutable(),
+      easing: false,
       duration: 1000,
-    };
+    } as TRequiredProps<MutableProps>;
   }
 
-  /**
-   * Global timeline progress, from 0 (start) to 1 (end).
-   */
-  protected _p: number;
+  /** Current linear progress of the timeline (0 to 1). */
+  protected _progress: number;
 
   /**
-   * Global timeline progress. Can be manually set, triggering updates.
+   * Get or set the linear progress of the timeline.
+   * Setting this triggers an update and associated callbacks.
    */
-  get p() {
-    return this._p;
+  get progress() {
+    return this._progress;
   }
 
-  set p(val: number) {
-    this._p = val;
+  set progress(val: number) {
+    this._progress = clamp(val);
 
-    this._handleProgressUpdate();
+    this._onUpdate();
   }
 
-  /**
-   * Eased progress of the timeline, calculated based on the easing function.
-   */
-  protected _e: number;
+  /** Current eased progress of the timeline (after applying easing function). */
+  protected _eased: number;
 
   /**
-   * Eased progress, which applies the easing function to the global progress.
+   * Get the eased progress of the timeline, derived from the easing function.
    */
-  get e() {
-    return this._e;
+  get eased() {
+    return this._eased;
   }
 
-  /**
-   * Stores the requestAnimationFrame ID for the ongoing animation.
-   */
+  /** Stores the ID of the current animation frame request. */
   protected _raf?: number;
 
-  /**
-   * Stores the time of the last animation frame.
-   */
-  protected _rafTime: number;
+  /** Stores the timestamp of the last frame update. */
+  protected _time: number;
 
   /**
-   * Indicates if the timeline is currently playing.
+   * Whether the timeline is currently playing.
    */
   get isPlaying() {
     return typeof this._raf !== 'undefined';
   }
 
-  /**
-   * Indicates if the timeline is playing in reverse.
-   */
+  /** Indicates whether the timeline is currently reversed. */
   protected _isReversed: boolean;
 
   /**
-   * Returns whether the timeline is reversed.
+   * Whether the timeline is reversed (progress decreases over time).
    */
   get isReversed() {
     return this._isReversed;
   }
 
-  /**
-   * Indicates if the timeline is paused.
-   */
+  /** Indicates whether the timeline is paused. */
   protected _isPaused: boolean;
 
   /**
-   * Returns whether the timeline is paused.
+   * Whether the timeline is paused.
    */
   get isPaused() {
     return this._isPaused;
   }
 
   /**
-   * Returns the duration of the timeline, ensuring a minimum duration of 1 ms.
+   * Get the timeline duration, ensuring it is at least 0 ms.
    */
   get duration() {
-    return Math.max(this.props.duration, 1);
+    return Math.max(this.props.duration, 0);
   }
 
-  constructor(initialProps?: StaticProps & ChangeableProps, canInit = true) {
-    super(initialProps, false);
+  constructor(props?: StaticProps & MutableProps) {
+    super(props);
 
-    // Set default variables
-    this._p = 0;
-    this._e = 0;
+    // Initialize default values
+    this._progress = 0;
+    this._eased = 0;
     this._raf = undefined;
-    this._rafTime = 0;
+    this._time = 0;
     this._isReversed = false;
     this._isPaused = false;
-
-    if (canInit) {
-      this.init();
-    }
   }
 
   /**
-   * 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.
+   * Play the timeline, advancing progress toward completion.
+   * Does nothing if the timeline is destroyed or already completed.
    */
   public play() {
-    if (this.isDestroyed || this.p === 1) {
+    if (this.isDestroyed || this.progress === 1) {
       return;
     }
 
@@ -134,17 +128,17 @@ export class Timeline<
     this._isPaused = false;
 
     if (!this.isPlaying) {
-      this._rafTime = Date.now();
+      this._time = Date.now();
       this._animate();
     }
   }
 
   /**
-   * 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.
+   * Reverse the timeline, moving progress toward the start.
+   * Does nothing if the timeline is destroyed or already at the start.
    */
   public reverse() {
-    if (this.isDestroyed || this.p === 0) {
+    if (this.isDestroyed || this.progress === 0) {
       return;
     }
 
@@ -152,13 +146,13 @@ export class Timeline<
     this._isPaused = false;
 
     if (!this.isPlaying) {
-      this._rafTime = Date.now();
+      this._time = Date.now();
       this._animate();
     }
   }
 
   /**
-   * Pauses the timeline's progress, stopping the animation at its current state.
+   * Pause the timeline, halting progress without resetting it.
    */
   public pause() {
     if (this.isDestroyed) {
@@ -170,11 +164,12 @@ export class Timeline<
     if (this._raf) {
       window.cancelAnimationFrame(this._raf);
     }
+
     this._raf = undefined;
   }
 
   /**
-   * Resets the timeline to the beginning (progress = 0).
+   * Reset the timeline to the beginning (progress = 0).
    */
   public reset() {
     if (this.isDestroyed) {
@@ -182,33 +177,38 @@ export class Timeline<
     }
 
     this.pause();
-    this.p = 0;
+    this.progress = 0;
   }
 
   /**
-   * Starts the animation process, updating the timeline's progress based on elapsed time.
+   * Animate the timeline, updating progress based on elapsed time.
    */
   protected _animate() {
     if (this.isPaused) {
       return;
     }
 
-    const { isReversed } = this;
+    const { isReversed, duration } = this;
+
+    if (duration <= 0) {
+      this.progress = isReversed ? 1 : 0;
+      this.progress = isReversed ? 0 : 1;
+
+      return;
+    }
 
-    // Calculate time difference between frames
     const currentTime = Date.now();
-    const frameDiff = Math.abs(this._rafTime - currentTime);
-    this._rafTime = currentTime;
+    const frameDiff = Math.abs(this._time - currentTime);
+    this._time = currentTime;
 
-    // Calculate current progress
-    const progressIterator = frameDiff / this.duration / (isReversed ? -1 : 1);
-    const progressTarget = clamp(this.p + progressIterator, [0, 1]);
-    this.p = progressTarget;
+    const progressIterator = frameDiff / duration / (isReversed ? -1 : 1);
+    const progressTarget = this.progress + progressIterator;
+
+    this.progress = progressTarget;
 
-    // End animation if progress reaches start or end
     if (
-      (progressTarget === 1 && !isReversed) ||
-      (progressTarget === 0 && isReversed)
+      (this.progress === 1 && !isReversed) ||
+      (this.progress === 0 && isReversed)
     ) {
       this._isReversed = false;
       this._isPaused = false;
@@ -217,38 +217,33 @@ export class Timeline<
       return;
     }
 
-    // Continue animation
-    this._raf = window.requestAnimationFrame(this._animate.bind(this));
+    this._raf = window.requestAnimationFrame(() => this._animate());
   }
 
   /**
-   * Handles updates to the timeline's progress and triggers associated callbacks.
+   * Handle progress updates and trigger callbacks.
    */
-  protected _handleProgressUpdate() {
-    this._e = easing(this._p, this.props.easing);
+  protected _onUpdate() {
+    this._eased = easing(this._progress, this.props.easing);
 
-    this.callbacks.tbt('progress', {
-      p: this._p,
-      e: this._e,
+    this.callbacks.emit('update', {
+      progress: this._progress,
+      eased: this._eased,
     });
 
-    if (this.p === 0) {
-      this.callbacks.tbt('start', undefined);
+    if (this.progress === 0) {
+      this.callbacks.emit('start', undefined);
 
       return;
     }
 
-    if (this.p === 1) {
-      this.callbacks.tbt('end', undefined);
-
-      if (this.props.isDestroyedOnEnd) {
-        this.destroy();
-      }
+    if (this.progress === 1) {
+      this.callbacks.emit('end', undefined);
     }
   }
 
   /**
-   * Destroys the timeline, pausing any ongoing animation and cleaning up resources.
+   * Destroy the timeline, stopping any active animation and cleaning up resources.
    */
   protected _destroy() {
     this.pause();

package/src/components/Timeline/types.ts

@@ -1,54 +1,52 @@
-import { NComponent } from '@/base/Component';
-import { IVevetProps } from '@/src/Vevet/types';
-
-export namespace NTimeline {
-  export interface IStaticProps extends NComponent.IStaticProps {
-    /**
-     * Easing function for the timeline animation.
-     */
-    easing?: IVevetProps['easing'];
-
-    /**
-     * Whether to destroy the timeline when the animation ends.
-     * @default false
-     */
-    isDestroyedOnEnd?: boolean;
-  }
-
-  export interface IChangeableProps extends NComponent.IChangeableProps {
-    /**
-     * Duration of the timeline animation in milliseconds.
-     * @default 1000
-     */
-    duration?: number;
-  }
-
-  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;
-  }
+import {
+  IModuleCallbacksMap,
+  IModuleMutableProps,
+  IModuleStaticProps,
+} from '@/base/Module';
+import { TEasingType } from '@/utils/math/easing';
+
+export interface ITimelineStaticProps extends IModuleStaticProps {}
+
+export interface ITimelineMutableProps extends IModuleMutableProps {
+  /**
+   * Timeline duration in milliseconds.
+   * @default 1000
+   */
+  duration?: number;
+
+  /**
+   * Easing function for timeline progression.
+   * Accepts standard easing types or an array of bezier values.
+   * @default false
+   */
+  easing?: TEasingType;
+}
+
+export interface ITimelineCallbacksMap extends IModuleCallbacksMap {
+  /**
+   * Triggered when the timeline starts.
+   */
+  start: undefined;
+
+  /**
+   * Triggered during timeline updates with progress values.
+   */
+  update: ITimelineProgressArg;
+
+  /**
+   * Triggered when the timeline completes.
+   */
+  end: undefined;
+}
+
+export interface ITimelineProgressArg {
+  /**
+   * Linear progress, ranging from 0 to 1.
+   */
+  progress: number;
+
+  /**
+   * Progress value after applying the easing function.
+   */
+  eased: number;
 }