vevet 4.4.1 → 5.0.0

package/src/components/ProgressPreloader/types.ts

@@ -1,133 +1,88 @@
-import { NPreloader } from '../Preloader';
-
-export namespace NProgressPreloader {
-  export interface IStaticProps extends NPreloader.IStaticProps {
-    /**
-     * The default number of resources to preload. This can be incremented using custom logic.
-     * @default 0
-     */
-    resourcesQuantity?: number;
-
-    /**
-     * Whether to preload images automatically.
-     * @default true
-     */
-    canPreloadImages?: boolean;
-
-    /**
-     * Whether to preload videos automatically.
-     * @default false
-     */
-    canPreloadVideos?: boolean;
-
-    /**
-     * 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;
-
-    /**
-     * 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;
-
-    /**
-     * 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 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;
-  }
-
-  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;
-  }
+import {
+  IPreloaderCallbacksMap,
+  IPreloaderMutableProps,
+  IPreloaderStaticProps,
+} from '../Preloader';
+
+/**
+ * Static properties for configuring the progress preloader.
+ */
+export interface IProgressPreloaderStaticProps extends IPreloaderStaticProps {
+  /**
+   * Enables automatic preloading of images.
+   * @default true
+   */
+  preloadImages?: boolean;
+
+  /**
+   * Enables automatic preloading of videos.
+   * @default false
+   */
+  preloadVideos?: boolean;
+
+  /**
+   * Selector for custom resources to preload. Elements should include `data-weight` and `data-loaded` attributes.
+   * Example: `data-weight="10"` for a weight of 10, `data-loaded="10"` when loaded.
+   * @default '.js-preload'
+   */
+  customSelector?: string;
+
+  /**
+   * Class name for elements to exclude from preloading.
+   * @default 'js-preload-ignore'
+   */
+  ignoreClassName?: string;
+
+  /**
+   * Linear interpolation factor for smooth progress updates. `1` disables interpolation for instant updates.
+   * @default 0.1
+   */
+  lerp?: number;
+
+  /**
+   * Duration (ms) to complete the preloader if resources are loaded but progress < 1.
+   * @default 500
+   */
+  endDuration?: number;
+}
 
-  export interface ICustomResourceData {
-    /**
-     * The custom resource element to be preloaded.
-     */
-    element: ICustomResource;
+/**
+ * Mutable properties for the progress preloader.
+ */
+export interface IProgressPreloaderMutableProps
+  extends IPreloaderMutableProps {}
+
+/**
+ * Callback events for the progress preloader.
+ */
+export interface IProgressPreloaderCallbacksMap extends IPreloaderCallbacksMap {
+  /**
+   * Fired when the preloader's progress updates.
+   */
+  progress: undefined;
+
+  /**
+   * Fired each time a resource is loaded during preloading.
+   */
+  resource: IProgressPreloaderResource;
+}
 
-    /**
-     * The target progress value (between 0 and 1) for this resource, based on its `data-load-count` attribute.
-     */
-    targetProgress: number;
-  }
+/**
+ * Data structure for custom resources to preload.
+ */
+export interface IProgressPreloaderResource {
+  /**
+   * The custom resource identifier.
+   */
+  id: Element | string;
+
+  /**
+   * A resource may be split into multiple parts. This is the resource weight
+   */
+  weight: number;
+
+  /**
+   * Loaded weight
+   */
+  loaded: number;
 }

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

@@ -1,84 +1,46 @@
-import { Module } from '@/base/Module';
-import { NProgressPreloader } from '../types';
+import { clamp } from '@/utils/math';
+import { IProgressPreloaderResource } from '../types';
 
 /**
- * Retrieves the load progress of a custom resource element based on its properties or attributes.
+ * Retrieves the load progress of a custom resource element based on its attributes.
  */
-function getLoadProgress({
-  element,
-  targetProgress,
-}: 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;
-    }
-
-    if (typeof element.isComplete === 'number') {
-      return element.isComplete;
-    }
-
-    return 0;
-  }
-
-  // Check if the element is marked as loaded
-  if (typeof element.isLoaded !== 'undefined') {
-    if (typeof element.isLoaded === 'boolean' && element.isLoaded) {
-      return targetProgress;
-    }
-
-    if (typeof element.isLoaded === 'number') {
-      return element.isLoaded;
-    }
-  }
-
-  // Check for a `data-is-loaded` attribute
-  const isLoadedAttr = element.getAttribute('data-is-loaded');
-  if (
-    isLoadedAttr !== null &&
-    isLoadedAttr !== '' &&
-    isLoadedAttr !== 'false'
-  ) {
-    const isLoadedAttrNum = parseFloat(isLoadedAttr);
+function getLoaded(element: Element) {
+  let loaded = parseInt(element.getAttribute('data-loaded') || '0', 10);
+  loaded = Number.isNaN(loaded) ? 0 : clamp(loaded, 0, Infinity);
 
-    // If the value is non-numeric, treat the resource as loaded
-    if (Number.isNaN(isLoadedAttrNum)) {
-      return targetProgress;
-    }
-
-    return isLoadedAttrNum;
-  }
-
-  return 0;
+  return loaded;
 }
 
 /**
  * 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>,
+  { id, weight }: IProgressPreloaderResource,
+  onLoad: (loadedWeight: number) => void,
 ) {
-  return new Promise<void>((resolve) => {
-    const { targetProgress } = data;
-    const loadProgress = getLoadProgress(data);
+  if (!(id instanceof Element)) {
+    return;
+  }
 
-    // If the load progress has reached or exceeded the target, resolve the promise
-    if (loadProgress >= targetProgress) {
-      resolve();
+  // If the load progress has reached or exceeded the target, resolve the promise
+  if (getLoaded(id) >= weight) {
+    onLoad(weight);
 
-      return;
-    }
+    return;
+  }
+
+  // Set up a mutation observer to monitor changes in the 'data-loaded' attribute
+  const observer = new MutationObserver(() => {
+    const loaded = getLoaded(id);
+    onLoad(loaded);
 
-    // Recursively check the load progress every 50ms
-    setTimeout(() => {
-      if (instance.isDestroyed) {
-        return;
-      }
+    if (loaded >= weight) {
+      observer.disconnect();
+    }
+  });
 
-      preloadCustomElement(data, instance)
-        .then(() => resolve())
-        .catch(() => {});
-    }, 50);
+  observer.observe(id, {
+    attributes: true,
+    attributeFilter: ['data-loaded'],
   });
 }

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

@@ -1,18 +1,15 @@
-export function preloadImage(
-  imageProp: HTMLImageElement,
-  action: (isSuccess: boolean) => void,
-) {
-  if (imageProp.complete) {
-    action(true);
+export function preloadImage(resource: HTMLImageElement, onLoad: () => void) {
+  if (resource.complete) {
+    onLoad();
 
     return;
   }
 
   const image = new Image();
 
-  image.addEventListener('load', () => action(true));
-  image.addEventListener('error', () => action(false));
+  image.addEventListener('load', () => onLoad());
+  image.addEventListener('error', () => onLoad());
 
   image.crossOrigin = 'anonymous';
-  image.src = imageProp.currentSrc || imageProp.src;
+  image.src = resource.currentSrc || resource.src;
 }

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

@@ -1,19 +1,16 @@
-export function preloadVideo(
-  video: HTMLVideoElement,
-  action: (isSuccess: boolean) => void,
-) {
-  if (video.readyState > 0) {
-    action(true);
+export function preloadVideo(resource: HTMLVideoElement, onLoad: () => void) {
+  if (resource.readyState > 0) {
+    onLoad();
 
     return;
   }
 
-  if (video.preload === 'none') {
-    action(false);
+  if (resource.preload === 'none') {
+    onLoad();
 
     return;
   }
 
-  video.addEventListener('error', () => action(false));
-  video.addEventListener('loadedmetadata', () => action(true));
+  resource.addEventListener('error', () => onLoad());
+  resource.addEventListener('loadedmetadata', () => onLoad());
 }

package/src/components/Raf/index.ts

@@ -0,0 +1,223 @@
+import { TRequiredProps } from '@/internal/requiredProps';
+import { Module } from '@/base/Module';
+import { IRafCallbacksMap, IRafMutableProps, IRafStaticProps } from './types';
+
+export * from './types';
+
+/**
+ * Manages an animation frame loop with configurable FPS and playback controls.
+ *
+ * [Documentation](https://antonbobrov.github.io/vevet/docs/components/Raf)
+ *
+ * @group Components
+ */
+export class Raf<
+  CallbacksMap extends IRafCallbacksMap = IRafCallbacksMap,
+  StaticProps extends IRafStaticProps = IRafStaticProps,
+  MutableProps extends IRafMutableProps = IRafMutableProps,
+> 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._getMutable(),
+      fps: 'auto',
+      enabled: false,
+      fpsRecalcFrames: 10,
+    } as TRequiredProps<MutableProps>;
+  }
+
+  /** Indicates if the animation frame is currently running */
+  protected _isPlaying = false;
+
+  /** Playback state of the animation frame */
+  get isPlaying() {
+    return this._isPlaying;
+  }
+
+  /** Active requestAnimationFrame ID, or `null` if not running */
+  protected _raf: number | null = null;
+
+  /** Timestamp of the last frame */
+  protected _lastTimestamp: null | number = null;
+
+  /** Timestamp of the current frame */
+  protected _timestamp: null | number = null;
+
+  /** Timestamp of the current frame */
+  get timestamp() {
+    return this._timestamp ?? 0;
+  }
+
+  /** Current frame index */
+  protected _index = 0;
+
+  /** Current frame index */
+  get index() {
+    return this._index;
+  }
+
+  /** Real-time FPS */
+  protected _fps = 60;
+
+  /** Real-time FPS */
+  get fps() {
+    return this._fps;
+  }
+
+  /** Duration of the last frame in ms */
+  protected _duration = 0;
+
+  /** Duration of the last frame in ms */
+  get duration() {
+    return this._duration;
+  }
+
+  /** Scaling coefficient based on a 60 FPS target */
+  get fpsFactor() {
+    return 60 / this.fps;
+  }
+
+  constructor(props?: StaticProps & MutableProps) {
+    super(props);
+
+    // Initialize FPS
+    this._fps = this.props.fps === 'auto' ? this._fps : this.props.fps;
+
+    // Play on init
+    if (this.props.enabled) {
+      this._play();
+    }
+  }
+
+  /** Handle property mutations */
+  protected _handleProps() {
+    super._handleProps();
+
+    this._lastTimestamp = null;
+
+    if (this.props.enabled) {
+      this._play();
+    } else {
+      this._pause();
+    }
+  }
+
+  /** Start the animation loop */
+  public play() {
+    if (this.isDestroyed || this.props.enabled) {
+      return;
+    }
+
+    this.updateProps({ enabled: true } as MutableProps);
+  }
+
+  /** Internal method to start the loop */
+  protected _play() {
+    if (this.isPlaying) {
+      return;
+    }
+
+    this._isPlaying = true;
+
+    this.callbacks.emit('play', undefined);
+    this.callbacks.emit('toggle', undefined);
+
+    this._raf = window.requestAnimationFrame(this._animate.bind(this));
+  }
+
+  /** Pause the animation loop */
+  public pause() {
+    if (!this.props.enabled) {
+      return;
+    }
+
+    this.updateProps({ enabled: false } as MutableProps);
+  }
+
+  /** Internal method to pause the loop */
+  protected _pause() {
+    if (!this.isPlaying) {
+      return;
+    }
+
+    if (this._raf) {
+      window.cancelAnimationFrame(this._raf);
+      this._raf = null;
+    }
+
+    this._isPlaying = false;
+
+    this.callbacks.emit('pause', undefined);
+    this.callbacks.emit('toggle', undefined);
+  }
+
+  /** Animation loop handler, calculates FPS, and triggers callbacks */
+  protected _animate() {
+    if (!this._isPlaying) {
+      return;
+    }
+
+    this._raf = window.requestAnimationFrame(this._animate.bind(this));
+
+    const minFrameDuration =
+      this.props.fps === 'auto' ? 1 : 1000 / this.props.fps;
+
+    this._timestamp = performance.now();
+    this._lastTimestamp ??= this._timestamp;
+
+    const duration = this._timestamp - (this._lastTimestamp ?? this._timestamp);
+
+    if (duration < minFrameDuration) {
+      return;
+    }
+
+    this._duration = duration;
+    this._lastTimestamp = this._timestamp;
+    this._index += 1;
+
+    this._computeFPS();
+
+    this.callbacks.emit('frame', {
+      fps: this.fps,
+      fpsFactor: this.fpsFactor,
+      duration: this.duration,
+      lerpFactor: this.lerpFactor.bind(this),
+    });
+  }
+
+  /** Calculate linear interpolation factor to make animations run the same regardless of FPS */
+  public lerpFactor(ease: number) {
+    return 1 - Math.exp(-ease * 60 * (this.duration / 1000));
+  }
+
+  /** Compute real-time FPS from frame durations */
+  protected _computeFPS() {
+    const { duration, index, props } = this;
+
+    if (
+      (index > 10 && index % props.fpsRecalcFrames !== 0) ||
+      duration <= 0 ||
+      duration > 250
+    ) {
+      return;
+    }
+
+    const standardFps = 60;
+    const standardFrameTime = 1000 / standardFps;
+    const fpsMultiplier = standardFrameTime / duration;
+
+    this._fps = Math.round(60 * fpsMultiplier) || 1;
+  }
+
+  /** Destroy the animation frame and stop the loop */
+  protected _destroy() {
+    this.pause();
+
+    super._destroy();
+  }
+}

package/src/components/Raf/types.ts

@@ -0,0 +1,54 @@
+import {
+  IModuleCallbacksMap,
+  IModuleMutableProps,
+  IModuleStaticProps,
+} from '@/base/Module';
+
+/** Static properties for the Raf module */
+export interface IRafStaticProps extends IModuleStaticProps {}
+
+/** Mutable properties for the Raf module */
+export interface IRafMutableProps extends IModuleMutableProps {
+  /**
+   * Frames per second (FPS) for the animation. Set to 'auto' for dynamic adjustment.
+   * @default 'auto'
+   */
+  fps?: 'auto' | number;
+
+  /**
+   * Enables or disables the Raf animation loop.
+   * @default false
+   */
+  enabled?: boolean;
+
+  /**
+   * The number of frames after which the FPS is recalculated.
+   * This value determines how often the FPS calculation is updated based on frame counts.
+   * @default 10
+   */
+  fpsRecalcFrames?: number;
+}
+
+/** Callbacks for Raf module events */
+export interface IRafCallbacksMap extends IModuleCallbacksMap {
+  /** Triggered when the animation starts */
+  play: undefined;
+
+  /** Triggered when the animation is paused */
+  pause: undefined;
+
+  /** Triggered when play/pause state toggles */
+  toggle: undefined;
+
+  /** Triggered on every animation frame */
+  frame: {
+    /** Current frames per second */
+    fps: number;
+    /** Scaling coefficient based on a 60 FPS target */
+    fpsFactor: number;
+    /** Duration of the last frame in ms */
+    duration: number;
+    /** Calculate linear interpolation factor to make animations run the same regardless of FPS */
+    lerpFactor: (factor: number) => number;
+  };
+}