vevet 4.4.2 → 5.0.0

package/src/components/Marquee/index.ts

@@ -1,12 +1,17 @@
-import { NMarquee } from './types';
-import { Component as ComponentClass } from '@/base/Component';
-import { AnimationFrame } from '../AnimationFrame';
-import { getApp } from '@/utils/internal/getApp';
-import { wrap } from '@/utils/math';
-import { onResize } from '@/utils/listeners';
-import { selectOne } from '@/utils/dom/selectOne';
-
-export type { NMarquee };
+import { TRequiredProps } from '@/internal/requiredProps';
+import { loop } from '@/utils/math';
+import { onResize, addEventListener } from '@/utils/listeners';
+import {
+  IMarqueeCallbacksMap,
+  IMarqueeMutableProps,
+  IMarqueeStaticProps,
+} from './types';
+import { Module } from '@/base/Module';
+import { Raf } from '../Raf';
+import { initVevet } from '@/global/initVevet';
+import { toPixels } from '@/utils';
+
+export * from './types';
 
 /**
  * A custom marquee component that smoothly scrolls its child elements.
@@ -14,66 +19,53 @@ export type { NMarquee };
  * This component is designed to loop elements horizontally within a container,
  * with support for customization such as speed, gap, pause on hover, and more.
  *
- * @link See examples https://antonbobrov.github.io/vevet-demo/marquee/
+ * [Documentation](https://antonbobrov.github.io/vevet/docs/components/Marquee)
  *
- * @link See docs https://antonbobrov.github.io/vevet/classes/Marquee.html
+ * @group Components
  */
 export class Marquee<
-  StaticProps extends NMarquee.IStaticProps = NMarquee.IStaticProps,
-  ChangeableProps extends NMarquee.IChangeableProps = NMarquee.IChangeableProps,
-  CallbacksTypes extends NMarquee.ICallbacksTypes = NMarquee.ICallbacksTypes,
-> extends ComponentClass<StaticProps, ChangeableProps, CallbacksTypes> {
-  /**
-   * Returns the default properties for the marquee.
-   */
-  protected _getDefaultProps() {
+  CallbacksMap extends IMarqueeCallbacksMap = IMarqueeCallbacksMap,
+  StaticProps extends IMarqueeStaticProps = IMarqueeStaticProps,
+  MutableProps extends IMarqueeMutableProps = IMarqueeMutableProps,
+> extends Module<CallbacksMap, StaticProps, MutableProps> {
+  /** Get default static properties. */
+  public _getStatic(): TRequiredProps<StaticProps> {
     return {
-      ...super._getDefaultProps(),
-      container: `#${this.prefix}`,
+      ...super._getStatic(),
       resizeDebounce: 0,
       hasWillChange: true,
-      canCloneNodes: true,
+      cloneNodes: true,
+    } as TRequiredProps<StaticProps>;
+  }
+
+  /** Get default mutable properties. */
+  public _getMutable(): TRequiredProps<MutableProps> {
+    return {
+      ...super._getMutable(),
       speed: 1,
       gap: 0,
-      isEnabled: true,
+      enabled: true,
       pauseOnHover: false,
-      isFpsNormalized: true,
-      isCentered: false,
-    };
-  }
-
-  /**
-   * Returns the prefix for the marquee.
-   */
-  get prefix() {
-    return `${getApp().prefix}marquee`;
-  }
-
-  /** Marquee container element */
-  protected _container: HTMLElement;
-
-  /** Marquee container element */
-  get container() {
-    return this._container;
+      centered: false,
+      adjustSpeed: true,
+      pauseOnOut: true,
+    } as TRequiredProps<MutableProps>;
   }
 
   /** Current container width */
-  private _width = 0;
+  protected _width = 0;
 
   /** Initial child nodes of the container */
-  private _initialNodes: ChildNode[] = [];
+  protected _initialNodes: ChildNode[] = [];
 
   /** Array of marquee element nodes */
-  private _elements: HTMLElement[] = [];
+  protected _elements: HTMLElement[] = [];
 
-  /** Timeout for resize debounce */
-  private _resizeTimeout: NodeJS.Timeout | null = null;
-
-  /** Array of widths of each element in the marquee */
-  private _widths: number[] = [];
+  /** Array of widths of each child element */
+  protected _widths: number[] = [];
 
   /** Total width of all elements in the marquee */
-  private _totalWidth = 0;
+  protected _totalWidth = 0;
 
   /** Total width of all elements in the marquee */
   get totalWidth() {
@@ -81,12 +73,12 @@ export class Marquee<
   }
 
   /** Last setup handler for teardown */
-  private _lastSetup?: () => void;
+  protected _lastSetup?: () => void;
 
-  /** Current animation X position */
-  protected _x: number;
+  /** The current X coordinate of the marquee. */
+  protected _x = 0;
 
-  /** Current animation X position */
+  /** The current X coordinate of the marquee. */
   get x() {
     return this._x;
   }
@@ -96,26 +88,20 @@ export class Marquee<
     this.render(0);
   }
 
-  /** Whether the marquee can play (used for pausing) */
-  protected _canPlay: boolean;
-
-  /** Animation frame instance */
-  protected _raf: AnimationFrame;
+  /** Raf instance */
+  protected _raf: Raf;
 
-  constructor(initialProps?: StaticProps & ChangeableProps, canInit = true) {
-    super(initialProps, false);
+  /** Intersection observer */
+  protected _intersection?: IntersectionObserver;
 
-    this._container = selectOne(this.props.container)! as HTMLElement;
-    const container = this._container;
-    if (!(container instanceof HTMLElement)) {
-      throw new Error('No container');
-    }
+  constructor(props?: StaticProps & MutableProps) {
+    super(props);
 
-    this.toggleClassName(container, this.className(''), true);
+    const { container } = this.props;
 
-    // Initialize internal variables
-    this._x = 0;
-    this._canPlay = true;
+    if (!container) {
+      throw new Error('Marquee container is not defined');
+    }
 
     // Apply base styles to the container
     container.style.position = 'relative';
@@ -130,52 +116,49 @@ export class Marquee<
     this._setup();
 
     // Create animation frame
-    this._raf = new AnimationFrame({
-      isEnabled: this.props.isEnabled,
+    this._raf = new Raf({ enabled: this.props.enabled, fpsRecalcFrames: 1 });
+    this._raf.on('frame', () => {
+      const factor = this.props.adjustSpeed ? this._raf.fpsFactor : 1;
+      const speed = toPixels(this.props.speed);
+      this._render(speed * factor);
     });
-    this._raf.addCallback('frame', () => this._render());
-
-    // Initialize the component if canInit is true
-    if (canInit) {
-      this.init();
-    }
-  }
-
-  /** Initializes the component and sets up event listeners */
-  protected _init() {
-    super._init();
-
-    this._setEvents();
-  }
-
-  /** Sets up event listeners for the marquee component */
-  protected _setEvents() {
-    const { container, props } = this;
 
     // Pause on hover
-    this.addEventListener(container, 'mouseenter', () => {
-      if (props.pauseOnHover) {
-        this._canPlay = false;
+    const mouseenter = addEventListener(container, 'mouseenter', () => {
+      if (this.props.pauseOnHover) {
+        this._raf.pause();
       }
     });
+    this.onDestroy(() => mouseenter());
 
     // Resume on mouse leave
-    this.addEventListener(container, 'mouseleave', () => {
-      this._canPlay = true;
+    const mouseleave = addEventListener(container, 'mouseleave', () => {
+      if (this.props.enabled) {
+        this._raf.play();
+      }
     });
+    this.onDestroy(() => mouseleave());
+
+    // Intersection observer
+    this._intersection = new IntersectionObserver(
+      this._handleIntersection.bind(this),
+      { root: null },
+    );
+    this._intersection.observe(container);
   }
 
-  /** Handles property changes and re-renders the component */
-  protected _onPropsMutate() {
-    super._onPropsMutate();
+  /** Handles property changes  */
+  protected _handleProps() {
+    super._handleProps();
 
-    if (this.props.isEnabled) {
-      this._raf?.play();
+    if (this.props.enabled) {
+      this._raf.play();
     } else {
-      this._raf?.pause();
+      this._raf.pause();
     }
 
     // Rerender the elements
+    this.resize();
     this.render(0);
   }
 
@@ -187,7 +170,7 @@ export class Marquee<
       return;
     }
 
-    const container = this._container;
+    const { container, resizeDebounce } = this.props;
 
     // Save initial child nodes
     this._initialNodes = [...Array.from(container.childNodes)];
@@ -196,53 +179,46 @@ export class Marquee<
     this._wrapTextNode();
 
     // Store element references
-    this._elements = Array.from(this._container.children) as any;
-
-    // Handle container resizing
-    const onContainerResize = onResize({
-      onResize: () => this._handleResize(),
-      element: container,
-      viewportTarget: 'width',
-      hasBothEvents: false,
-    });
+    this._elements = Array.from(container.children) as any;
 
     // initial resize
-    this._handleResize();
+    this.resize();
 
     // Resize on page load
-    getApp()
-      .onPageLoad()
-      .then(() => this._handleResize())
-      .catch(() => {});
-
-    // Set resize events for individual elements
-    const elementsResize = onResize({
-      onResize: () => this._handleResize(),
-      element: this._elements,
+    const onPageLoad = initVevet().onLoad(() => this.resize());
+
+    // Handle resizing
+    const resizeHandler = onResize({
+      callback: () => this.resize(),
+      element: [container, ...this._elements],
       viewportTarget: 'width',
-      hasBothEvents: false,
+      resizeDebounce,
+      name: this.name,
     });
 
     // Add necessary styles to elements
     this._elements.forEach((element, index) =>
-      this._addElementStyles(element, index !== 0),
+      this._applyNodeStyles(element, index !== 0),
     );
 
     // Setup cleanup function
     this._lastSetup = () => {
-      onContainerResize.remove();
-      elementsResize.remove();
+      onPageLoad();
+      resizeHandler.remove();
     };
   }
 
   /**
    * Wraps the first text node in the container in a span if no other elements exist.
    */
-  private _wrapTextNode() {
-    const node = this._container.childNodes[0];
+  protected _wrapTextNode() {
+    const { container } = this.props;
+
+    const hasOneNode = container.childNodes.length === 1;
+    const node = container.childNodes[0];
 
     // Wrap text node if it's the first child and not already wrapped
-    if (!node || node.nodeType !== 3) {
+    if (!node || node.nodeType !== 3 || !hasOneNode) {
       return;
     }
 
@@ -251,14 +227,15 @@ export class Marquee<
     wrapper.style.display = 'block';
     wrapper.style.width = 'max-content';
     wrapper.style.whiteSpace = 'nowrap';
+
     wrapper.appendChild(node);
-    this._container.appendChild(wrapper);
+    container.appendChild(wrapper);
   }
 
   /**
    * Adds necessary styles to a given element.
    */
-  private _addElementStyles(element: HTMLElement, isAbsolute: boolean) {
+  protected _applyNodeStyles(element: HTMLElement, isAbsolute: boolean) {
     const el = element;
 
     el.style.position = isAbsolute ? 'absolute' : 'relative';
@@ -268,38 +245,21 @@ export class Marquee<
     el.style.willChange = this.props.hasWillChange ? 'transform' : '';
   }
 
-  /** Handles resize events and updates the layout accordingly */
-  private _handleResize() {
-    if (this.isDestroyed) {
-      return;
-    }
-
-    if (this._resizeTimeout) {
-      clearTimeout(this._resizeTimeout);
-    }
-
-    this._resizeTimeout = setTimeout(
-      () => this.resize(),
-      this.props.resizeDebounce,
-    );
-  }
-
-  /** Resizes the marquee, recalculating element positions and cloning if necessary */
+  /** Resizes the marquee, recalculating element positions and cloning if necessary. */
   public resize() {
     if (this.isDestroyed) {
       return;
     }
 
-    const { container, props } = this;
+    const { props } = this;
+    const { container } = props;
+    const gap = toPixels(props.gap);
 
     // Update container width
     this._width = container.offsetWidth;
 
     // Update element widths
-    this._widths = [];
-    this._elements.forEach((element, index) => {
-      this._widths[index] = element.offsetWidth + props.gap;
-    });
+    this._widths = this._elements.map((element) => element.offsetWidth + gap);
     this._totalWidth = this._widths.reduce((a, b) => a + b, 0);
 
     // Determine how many times to duplicate elements
@@ -310,52 +270,46 @@ export class Marquee<
     this._totalWidth = Math.max(this._totalWidth, this._width + maxWidth);
 
     // Clone elements if necessary
-    if (props.canCloneNodes && copyQuantity > 1) {
+    if (props.cloneNodes && copyQuantity > 1) {
       for (let i = 1; i < copyQuantity; i += 1) {
         this._elements.forEach((element) => {
           const copy = element.cloneNode(true) as HTMLElement;
-          this._addElementStyles(copy, true);
+          this._applyNodeStyles(copy, true);
           container.appendChild(copy);
         });
       }
 
       // Update element references after cloning
-      this._elements = Array.from(this._container.children) as any;
+      this._elements = Array.from(container.children) as any;
       this.resize();
     }
 
     // Trigger resize callbacks
-    this.callbacks.tbt('resize', undefined);
+    this.callbacks.emit('resize', undefined);
 
     // Rerender the marquee
-    this.render(0);
+    setTimeout(() => this.render(0), 0);
   }
 
-  /** Renders the marquee, adjusting element positions */
-  public render(speed?: number) {
-    this._render(speed);
+  /** Renders the marquee, adjusting element positions. */
+  public render(step?: number) {
+    this._render(step);
   }
 
   /**
    * Renders the marquee, calculating element positions based on the provided speed.
    */
-  protected _render(speedProp = this.props.speed) {
-    if (!this._canPlay || this.isDestroyed) {
+  protected _render(step = this.props.speed) {
+    if (this.isDestroyed) {
       return;
     }
 
-    const { isFpsNormalized, isCentered } = this.props;
-
-    // Calculate speed, adjusting for frame rate if necessary
-    const fpsMultiplier = isFpsNormalized ? this._raf.fpsMultiplier : 1;
-    const speed = speedProp * fpsMultiplier;
-
     // Update animation time
-    this._x -= speed;
+    this._x -= toPixels(step);
 
     // Calculate current position of the elements
     const centerX = this._width * 0.5;
-    const position = this._x + (isCentered ? centerX : 0);
+    const position = this._x + (this.props.centered ? centerX : 0);
 
     // Update each element's position
     let prevStaticX = 0;
@@ -363,10 +317,10 @@ export class Marquee<
       const element = this._elements[index];
       const elementWidth = this._widths[index];
 
-      const x = wrap(
+      const x = loop(
+        position + prevStaticX,
         -elementWidth,
         this._totalWidth - elementWidth,
-        position + prevStaticX,
       );
 
       // Apply transformations to position the element
@@ -377,26 +331,42 @@ export class Marquee<
     }
 
     // Trigger render callbacks
-    this.callbacks.tbt('render', undefined);
+    this.callbacks.emit('render', undefined);
   }
 
-  /** Destroys the marquee and removes all event listeners */
+  /**
+   * Handle intersection observer
+   */
+  protected _handleIntersection(entries: IntersectionObserverEntry[]) {
+    if (!this.props.pauseOnOut) {
+      return;
+    }
+
+    entries.forEach((entry) => {
+      if (entry.isIntersecting && this.props.enabled) {
+        this._raf.play();
+      } else {
+        this._raf.pause();
+      }
+    });
+  }
+
+  /** Destroys the instance and cleans up resources */
   protected _destroy() {
+    const { container } = this.props;
+
     super._destroy();
 
-    this._raf?.destroy();
-    this._lastSetup?.();
+    this._raf.destroy();
+    this._intersection?.disconnect();
 
-    if (this._resizeTimeout) {
-      clearTimeout(this._resizeTimeout);
-      this._resizeTimeout = null;
-    }
+    this._lastSetup?.();
 
     // Remove all children and restore the initial nodes
-    while (this._container.firstChild) {
-      this._container.removeChild(this._container.firstChild);
+    while (container.firstChild) {
+      container.removeChild(container.firstChild);
     }
 
-    this._initialNodes.forEach((node) => this._container.appendChild(node));
+    this._initialNodes.forEach((node) => container.appendChild(node));
   }
 }

package/src/components/Marquee/types.ts

@@ -1,65 +1,98 @@
-import { NComponent } from '@/base/Component/types';
+import {
+  IModuleCallbacksMap,
+  IModuleMutableProps,
+  IModuleStaticProps,
+} from '@/base/Module';
 
-export namespace NMarquee {
-  export interface IStaticProps extends NComponent.IStaticProps {
-    /**
-     * Marquee container. You may use a CSS selector or the element itself.
-     * @default '#v-marquee'
-     */
-    container?: string | HTMLElement;
-    /**
-     * Timeout of resize event
-     * @default 0
-     */
-    resizeDebounce?: number;
-    /**
-     * If `true`, the `will-change` CSS property will be applied to the elements to improve performance.
-     * @default true
-     */
-    hasWillChange?: boolean;
-    /**
-     * If need to clone nodes for a better animation. May be useful to set `false` when using with such frameworks as React.
-     * @default true
-     */
-    canCloneNodes?: boolean;
-  }
+/**
+ * Static properties for the Marquee component.
+ */
+export interface IMarqueeStaticProps extends IModuleStaticProps {
+  /**
+   * The container element that holds the marquee content.
+   */
+  container: HTMLElement;
 
-  export interface IChangeableProps extends NComponent.IChangeableProps {
-    /**
-     * Marquee speed
-     * @default 1
-     */
-    speed?: number;
-    /**
-     * Gap between elements
-     * @default 0
-     */
-    gap?: number;
-    /**
-     * Enable animation
-     * @default true
-     */
-    isEnabled?: boolean;
-    /**
-     * Pause on hover
-     * @default false
-     */
-    pauseOnHover?: boolean;
-    /**
-     * On different screens with different FPS, animation may be slower or faster.
-     * This property is to normalize animation speed across different screens.
-     * @default true
-     */
-    isFpsNormalized?: boolean;
-    /**
-     * If need to center elements
-     * @default false
-     */
-    isCentered?: boolean;
-  }
+  /**
+   * The debounce delay for the resize event in milliseconds.
+   * @default 0
+   */
+  resizeDebounce?: number;
 
-  export interface ICallbacksTypes extends NComponent.ICallbacksTypes {
-    render: undefined;
-    resize: undefined;
-  }
+  /**
+   * Determines whether to apply the `will-change` CSS property to the marquee elements to optimize rendering.
+   * Setting this to `true` may improve performance.
+   * @default true
+   */
+  hasWillChange?: boolean;
+
+  /**
+   * Indicates whether to clone the marquee nodes.
+   * Indicates whether to clone the marquee nodes. Can be set to `false` if DOM cloning is not preferred.
+   * @default true
+   */
+  cloneNodes?: boolean;
+}
+
+/**
+ * Mutable properties for the Marquee component.
+ */
+export interface IMarqueeMutableProps extends IModuleMutableProps {
+  /**
+   * The speed of the marquee animation. Supports css units like `px`, `rem`, `vw`, `vh`, `svh`.
+   * @default 1
+   */
+  speed?: number | string;
+
+  /**
+   * The gap between the marquee elements. Supports css units like `px`, `rem`, `vw`, `vh`, `svh`.
+   * @default 0
+   */
+  gap?: number | string;
+
+  /**
+   * Enables or disables the marquee animation.
+   * When `false`, the marquee will be paused.
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Pauses the marquee when the mouse hovers over it.
+   * @default false
+   */
+  pauseOnHover?: boolean;
+
+  /**
+   * Centers the marquee content within the container.
+   * @default false
+   */
+  centered?: boolean;
+
+  /**
+   * When need to use dynamic FPS factor to adjust the speed of the marquee.
+   * @default true
+   */
+  adjustSpeed?: boolean;
+
+  /**
+   * Pauses the marquee when the mouse leaves the viewport.
+   * @default true
+   */
+  pauseOnOut?: boolean;
+}
+
+/**
+ * Marquee callbacks
+ */
+export interface IMarqueeCallbacksMap extends IModuleCallbacksMap {
+  /**
+   * Called during marquee rendering.
+   */
+  render: undefined;
+
+  /**
+   * Called on marquee resize
+   */
+  resize: undefined;
 }