vevet 4.4.2 → 5.0.1

package/src/components/Preloader/index.ts

@@ -1,215 +1,189 @@
-import { PCancelable } from '@/utils/common/PCancelable';
-import { NPreloader } from './types';
-import { Component as ComponentClass } from '@/base/Component';
-import { normalizedTimeoutCallback } from '@/utils/common';
-import { getApp } from '@/utils/internal/getApp';
-import { selectOne } from '@/utils/dom/selectOne';
-
-export type { NPreloader };
+import { TRequiredProps } from '@/internal/requiredProps';
+import {
+  IPreloaderCallbacksMap,
+  IPreloaderMutableProps,
+  IPreloaderStaticProps,
+} from './types';
+import { Module } from '@/base/Module';
+import { Timeline } from '../Timeline';
+import { initVevet } from '@/global/initVevet';
+import { EaseInOutSine } from '@/utils/math/easing';
+
+export * from './types';
 
 /**
- * Page preloader component, which manages the visibility of a preloader during page loading.
- * It can hide the preloader after the page is fully loaded and trigger related events.
- *
- * @requires Requires styles: `@import '~vevet/lib/styles/components/Preloader';`
+ * Page preloader component that manages the visibility and lifecycle of a loading screen.
+ * The module does not provide styling for the container.
  *
- * @link See examples https://antonbobrov.github.io/vevet-demo/preloader/
+ * [Documentation](https://antonbobrov.github.io/vevet/docs/components/Preloader)
  *
- * @link See docs https://antonbobrov.github.io/vevet/classes/Preloader.html
+ * @group Components
  */
 export class Preloader<
-  StaticProps extends NPreloader.IStaticProps = NPreloader.IStaticProps,
-  ChangeableProps extends
-    NPreloader.IChangeableProps = NPreloader.IChangeableProps,
-  CallbacksTypes extends
-    NPreloader.ICallbacksTypes = NPreloader.ICallbacksTypes,
-> extends ComponentClass<StaticProps, ChangeableProps, CallbacksTypes> {
-  protected _getDefaultProps() {
-    return {
-      ...super._getDefaultProps(),
-      container: `#${this.prefix}`,
-      hideAnimation: 250,
-    };
-  }
-
-  get prefix() {
-    return `${getApp().prefix}preloader`;
-  }
-
-  /**
-   * The preloader container element.
-   */
-  protected _container?: HTMLElement | false;
-
+  CallbacksMap extends IPreloaderCallbacksMap = IPreloaderCallbacksMap,
+  StaticProps extends IPreloaderStaticProps = IPreloaderStaticProps,
+  MutableProps extends IPreloaderMutableProps = IPreloaderMutableProps,
+> extends Module<CallbacksMap, StaticProps, MutableProps> {
   /**
-   * Returns the preloader container element.
+   * Retrieves the default static properties.
    */
-  get container() {
-    return this._container;
+  public _getStatic(): TRequiredProps<StaticProps> {
+    return {
+      ...super._getStatic(),
+      hide: 250,
+    } as TRequiredProps<StaticProps>;
   }
 
   /**
-   * Indicates if the preloader is in the process of being hidden.
-   */
-  protected _isToBeHidden: boolean;
-
-  /**
-   * Indicates if the preloader has already been hidden.
+   * Retrieves the default mutable properties.
    */
-  protected _isHidden: boolean;
-
-  /**
-   * Returns whether the preloader is hidden.
-   */
-  get isHidden() {
-    return this._isHidden;
+  public _getMutable(): TRequiredProps<MutableProps> {
+    return { ...super._getMutable() } as TRequiredProps<MutableProps>;
   }
 
-  constructor(initialProps?: StaticProps & ChangeableProps, canInit = true) {
-    super(initialProps, false);
+  /** Indicates if the preloader is in the process of being hidden. */
+  protected _shouldHide = false;
 
-    // Get the preloader container
-    if (this.props.container) {
-      const container = selectOne(this.props.container);
+  /** Indicates if the preloader has already been hidden. */
+  protected _isHidden = false;
 
-      if (container instanceof HTMLElement) {
-        this._container = container;
-        this.toggleClassName(container, this.className(''), true);
-      }
-    }
-
-    // Set default values
-    this._isToBeHidden = false;
-    this._isHidden = false;
-
-    if (canInit) {
-      this.init();
-    }
-  }
+  /** Indicates if the page is fully loaded. */
+  protected _isLoaded = false;
 
   /**
-   * Initializes the preloader and sets event listeners.
+   * Returns whether the preloader is currently hidden.
    */
-  protected _init() {
-    super._init();
-
-    this._setEvents();
+  get isHidden() {
+    return this._isHidden;
   }
 
-  /**
-   * Sets up the preloader's event handling for when the page is fully loaded.
-   */
-  protected _setEvents() {
-    const loadEvent = this._onLoaded();
-
-    loadEvent
-      .then(() => {
-        if (this.isDestroyed) {
-          return;
-        }
+  constructor(props?: StaticProps & MutableProps) {
+    super(props);
 
-        this._handleLoaded();
-      })
-      .catch(() => {});
+    // Handle page load event
+    const timeout = setTimeout(() => {
+      this._onLoaded(() => this._handleLoaded());
+    }, 0);
 
-    this.addDestroyableAction(() => loadEvent.cancel());
+    this.onDestroy(() => clearTimeout(timeout));
   }
 
   /**
    * Handles the page load event, triggering when the page is fully loaded.
    */
-  protected _onLoaded() {
-    return getApp().onPageLoad();
+  protected _onLoaded(callback: () => void) {
+    initVevet().onLoad(callback);
   }
 
   /**
    * Handles the logic that occurs after the page is fully loaded.
    */
   protected _handleLoaded() {
-    this.callbacks.tbt('loaded', undefined);
+    if (this.isDestroyed) {
+      return;
+    }
 
-    if (typeof this.props.hideAnimation !== 'boolean') {
-      this.hide();
+    this._isLoaded = true;
+    this.callbacks.emit('loaded', undefined);
+
+    if (typeof this.props.hide === 'number') {
+      this.hide(this.props.hide);
     }
   }
 
   /**
-   * Hides the preloader with an optional animation duration.
+   * Hides the preloader with a custom animation duration.
+   *
+   * @param duration - The duration of the hide animation (in milliseconds). Applies only when the container is used.
+   * @param callback - The callback to execute when the hide animation is complete.
    *
-   * @param duration - The duration of the hide animation (in milliseconds).
+   * @returns Returns an action destructor.
    */
-  public hide(
-    duration = typeof this.props.hideAnimation !== 'boolean'
-      ? this.props.hideAnimation
-      : 250,
-  ) {
-    this._isToBeHidden = true;
-    this.callbacks.tbt('hide', undefined);
-
-    return new PCancelable((resolve: (...args: any) => void) => {
-      const container = this._container;
-
-      if (!container) {
-        this._handleHidden();
-        resolve();
-
-        return;
+  public hide(duration: number, callback?: () => void) {
+    if (!this._isLoaded || this._shouldHide) {
+      return undefined;
+    }
+
+    let isDestroyed = false;
+
+    this._shouldHide = true;
+    this.callbacks.emit('hide', undefined);
+
+    this._hideContainer(() => {
+      this._onHidden();
+
+      if (!isDestroyed) {
+        callback?.();
       }
+    }, duration);
+
+    return () => {
+      isDestroyed = true;
+    };
+  }
 
-      // Apply hide animation
-      container.style.transition = `opacity ${duration}ms, visibility ${duration}ms`;
-      container.style.opacity = '0';
-      container.style.visibility = 'hidden';
+  /**
+   * Executes the hiding animation for the preloader container.
+   */
+  protected _hideContainer(onHidden: () => void, duration: number) {
+    const { container } = this.props;
 
-      const timeout = normalizedTimeoutCallback(() => {
-        container.style.display = 'none';
+    if (!container) {
+      onHidden();
 
-        this._handleHidden();
+      return;
+    }
 
-        resolve();
-      }, duration);
+    const tm = new Timeline({ duration, easing: EaseInOutSine });
+    this.onDestroy(() => tm.destroy());
 
-      this.addDestroyableAction(() => timeout.clear());
+    tm.on('update', ({ progress }) => {
+      container.style.opacity = String(1 - progress);
+      container.style.display = progress === 1 ? 'none' : 'flex';
     });
+
+    tm.on('end', () => onHidden());
+
+    tm.play();
   }
 
   /**
    * Handles actions when the preloader is fully hidden.
    */
-  protected _handleHidden() {
+  protected _onHidden() {
     this._isHidden = true;
-    this.callbacks.tbt('hidden', undefined);
+    this.callbacks.emit('hidden', undefined);
   }
 
   /**
    * Registers a callback for when the preloader starts hiding.
    *
    * @param action - The callback function to execute.
-   * @returns A cancelable action or undefined if already in hiding process.
+   * @returns A destructor.
    */
   public onHide(action: () => void) {
-    if (this._isToBeHidden) {
+    if (this._shouldHide) {
       action();
 
-      return undefined;
+      return () => {};
     }
 
-    return this.addCallback('hide', (() => action()) as any);
+    return this.on('hide', (() => action()) as any);
   }
 
   /**
    * Registers a callback for when the preloader is fully hidden.
    *
    * @param action - The callback function to execute.
-   * @returns A cancelable action or undefined if already hidden.
+   * @returns A destructor.
    */
   public onHidden(action: () => void) {
     if (this._isHidden) {
       action();
 
-      return undefined;
+      return () => {};
     }
 
-    return this.addCallback('hidden', (() => action()) as any);
+    return this.on('hidden', (() => action()) as any);
   }
 }

package/src/components/Preloader/types.ts

@@ -1,41 +1,49 @@
-import { NComponent } from '@/base/Component/types';
+import {
+  IModuleCallbacksMap,
+  IModuleMutableProps,
+  IModuleStaticProps,
+} from '@/base/Module';
 
-export namespace NPreloader {
-  export interface IStaticProps extends NComponent.IStaticProps {
-    /**
-     * The container for the preloader. You can pass a CSS selector string,
-     * an HTML element, or set it to `false` if you only need the preloader callbacks.
-     *
-     * @default '#v-preloader'
-     */
-    container?: string | HTMLElement | false;
-  }
+/**
+ * Static properties for the Preloader module.
+ */
+export interface IPreloaderStaticProps extends IModuleStaticProps {
+  /**
+   * The container for the preloader. Set it to `null` if you only need the preloader logic.
+   */
+  container: HTMLElement | null;
+  /**
+   * Defines whether to automatically hide the preloader container.
+   * - `false`: Disables the hiding animation, allowing you to manage it manually.
+   * - `number`: Specifies the animation duration in milliseconds.
+   *   This works only if the container is an HTML element.
+   *
+   * @default 250
+   */
+  hide?: false | number;
+}
 
-  export interface IChangeableProps extends NComponent.IChangeableProps {
-    /**
-     * Defines whether to automatically hide the preloader container.
-     * Set `false` to disable the hiding animation, allowing you to manage it manually.
-     * Set a `number` to specify the animation duration in milliseconds.
-     *
-     * @default 250
-     */
-    hideAnimation?: false | number;
-  }
+/**
+ * Mutable properties for the Preloader module.
+ */
+export interface IPreloaderMutableProps extends IModuleMutableProps {}
 
-  export interface ICallbacksTypes extends NComponent.ICallbacksTypes {
-    /**
-     * Triggered when the page is fully loaded.
-     */
-    loaded: undefined;
+/**
+ * Callbacks map for the Preloader module.
+ */
+export interface IPreloaderCallbacksMap extends IModuleCallbacksMap {
+  /**
+   * Triggered when the page is fully loaded.
+   */
+  loaded: undefined;
 
-    /**
-     * Triggered when the preloader starts hiding.
-     */
-    hide: undefined;
+  /**
+   * Triggered when the preloader starts hiding.
+   */
+  hide: undefined;
 
-    /**
-     * Triggered when the preloader is completely hidden.
-     */
-    hidden: undefined;
-  }
+  /**
+   * Triggered when the preloader is completely hidden.
+   */
+  hidden: undefined;
 }