tiny-essentials 1.27.1 → 1.28.1

package/dist/v1/libs/TinySmartScroller.cjs

@@ -1,8 +1,11 @@
 'use strict';
 
+var events = require('events');
 var TinyHtml = require('./TinyHtml.cjs');
 var collision = require('../basics/collision.cjs');
-var TinyEvents = require('./TinyEvents.cjs');
+var utils = require('./utils.cjs');
+
+const checkDestroy = utils.createCheckDestroyed('TinySmartScroller');
 
 /**
  * Represents the dimensions of a DOM element.
@@ -48,208 +51,9 @@ var TinyEvents = require('./TinyEvents.cjs');
  * This class is **not framework-dependent** and works with vanilla DOM elements and the window object.
  * @template {Element|Window} HTMLTarget
  */
-class TinySmartScroller {
+class TinySmartScroller extends events.EventEmitter {
   static Utils = { ...collision, TinyHtml };
 
-  #events = new TinyEvents();
-
-  /**
-   * Enables or disables throwing an error when the maximum number of listeners is exceeded.
-   *
-   * @param {boolean} shouldThrow - If true, an error will be thrown when the max is exceeded.
-   */
-  setThrowOnMaxListeners(shouldThrow) {
-    return this.#events.setThrowOnMaxListeners(shouldThrow);
-  }
-
-  /**
-   * Checks whether an error will be thrown when the max listener limit is exceeded.
-   *
-   * @returns {boolean} True if an error will be thrown, false if only a warning is shown.
-   */
-  getThrowOnMaxListeners() {
-    return this.#events.getThrowOnMaxListeners();
-  }
-
-  /////////////////////////////////////////////////////////////
-
-  /**
-   * Adds a listener to the beginning of the listeners array for the specified event.
-   *
-   * @param {string|string[]} event - Event name.
-   * @param {ScrollListenersFunc} handler - The callback function.
-   */
-  prependListener(event, handler) {
-    return this.#events.prependListener(event, handler);
-  }
-
-  /**
-   * Adds a one-time listener to the beginning of the listeners array for the specified event.
-   *
-   * @param {string|string[]} event - Event name.
-   * @param {ScrollListenersFunc} handler - The callback function.
-   * @returns {ScrollListenersFunc[]} - The wrapped handler used internally.
-   */
-  prependListenerOnce(event, handler) {
-    return this.#events.prependListenerOnce(event, handler);
-  }
-
-  //////////////////////////////////////////////////////////////////////
-
-  /**
-   * Adds a event listener.
-   *
-   * @param {string|string[]} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
-   * @param {ScrollListenersFunc} handler - Callback function to be called when event fires.
-   */
-  appendListener(event, handler) {
-    return this.#events.appendListener(event, handler);
-  }
-
-  /**
-   * Registers an event listener that runs only once, then is removed.
-   *
-   * @param {string|string[]} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
-   * @param {ScrollListenersFunc} handler - The callback function to run on event.
-   * @returns {ScrollListenersFunc[]} - The wrapped version of the handler.
-   */
-  appendListenerOnce(event, handler) {
-    return this.#events.appendListenerOnce(event, handler);
-  }
-
-  /**
-   * Adds a event listener.
-   *
-   * @param {string|string[]} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
-   * @param {ScrollListenersFunc} handler - Callback function to be called when event fires.
-   */
-  on(event, handler) {
-    return this.#events.on(event, handler);
-  }
-
-  /**
-   * Registers an event listener that runs only once, then is removed.
-   *
-   * @param {string|string[]} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
-   * @param {ScrollListenersFunc} handler - The callback function to run on event.
-   * @returns {ScrollListenersFunc[]} - The wrapped version of the handler.
-   */
-  once(event, handler) {
-    return this.#events.once(event, handler);
-  }
-
-  ////////////////////////////////////////////////////////////////////
-
-  /**
-   * Removes a previously registered event listener.
-   *
-   * @param {string|string[]} event - The name of the event to remove the handler from.
-   * @param {ScrollListenersFunc} handler - The specific callback function to remove.
-   */
-  off(event, handler) {
-    return this.#events.off(event, handler);
-  }
-
-  /**
-   * Removes all event listeners of a specific type from the element.
-   *
-   * @param {string|string[]} event - The event type to remove (e.g. 'onScrollBoundary').
-   */
-  offAll(event) {
-    return this.#events.offAll(event);
-  }
-
-  /**
-   * Removes all event listeners of all types from the element.
-   */
-  offAllTypes() {
-    return this.#events.offAllTypes();
-  }
-
-  ////////////////////////////////////////////////////////////
-
-  /**
-   * Returns the number of listeners for a given event.
-   *
-   * @param {string} event - The name of the event.
-   * @returns {number} Number of listeners for the event.
-   */
-  listenerCount(event) {
-    return this.#events.listenerCount(event);
-  }
-
-  /**
-   * Returns a copy of the array of listeners for the specified event.
-   *
-   * @param {string} event - The name of the event.
-   * @returns {ScrollListenersFunc[]} Array of listener functions.
-   */
-  listeners(event) {
-    return this.#events.listeners(event);
-  }
-
-  /**
-   * Returns a copy of the array of listeners for the specified event.
-   *
-   * @param {string} event - The name of the event.
-   * @returns {ScrollListenersFunc[]} Array of listener functions.
-   */
-  onceListeners(event) {
-    return this.#events.onceListeners(event);
-  }
-
-  /**
-   * Returns a copy of the internal listeners array for the specified event,
-   * including wrapper functions like those used by `.once()`.
-   * @param {string | symbol} event - The event name.
-   * @returns {ScrollListenersFunc[]} An array of raw listener functions.
-   */
-  allListeners(event) {
-    return this.#events.allListeners(event);
-  }
-
-  /**
-   * Returns an array of event names for which there are registered listeners.
-   *
-   * @returns {string[]} Array of registered event names.
-   */
-  eventNames() {
-    return this.#events.eventNames();
-  }
-
-  //////////////////////////////////////////////////////
-
-  /**
-   * Emits an event, triggering all registered handlers for that event.
-   *
-   * @param {string} event - The event name to emit.
-   * @param {...any} payload - Optional data to pass to each handler.
-   * @returns {boolean[]} True if any listeners were called, false otherwise.
-   */
-  emit(event, ...payload) {
-    return this.#events.emit(event, ...payload);
-  }
-
-  /**
-   * Sets the maximum number of listeners per event before a warning is shown.
-   *
-   * @param {number} n - The maximum number of listeners.
-   */
-  setMaxListeners(n) {
-    return this.#events.setMaxListeners(n);
-  }
-
-  /**
-   * Gets the maximum number of listeners allowed per event.
-   *
-   * @returns {number} The maximum number of listeners.
-   */
-  getMaxListeners() {
-    return this.#events.getMaxListeners();
-  }
-
-  ///////////////////////////////////////////////////
-
   /** @type {WeakMap<Element, NodeSizes>} */
   #oldSizes = new WeakMap();
   /** @type {WeakMap<Element, NodeSizes>} */
@@ -338,6 +142,7 @@ class TinySmartScroller {
       attributeFilter = ['class', 'style', 'src', 'data-*', 'height', 'width'],
     } = {},
   ) {
+    super();
     // === target ===
     if (!(
       target instanceof Element ||
@@ -425,6 +230,7 @@ class TinySmartScroller {
    * @returns {NodeSizesEvent} A function that compares previous and current height, returning height delta.
    */
   getSimpleOnHeight(filter = []) {
+    checkDestroy(this.#destroyed);
     if (!Array.isArray(filter))
       throw new TypeError('getSimpleOnHeight(filter): filter must be an array of tag names');
     return (elem, sizes, amounts) => {
@@ -444,6 +250,7 @@ class TinySmartScroller {
    * @returns {NodeSizesEvent} The added size difference callback.
    */
   addSimpleOnHeight(filter) {
+    checkDestroy(this.#destroyed);
     if (!Array.isArray(filter))
       throw new TypeError('addSimpleOnHeight(filter): filter must be an array of tag names');
     const result = this.getSimpleOnHeight(filter);
@@ -457,6 +264,7 @@ class TinySmartScroller {
    * @returns {string[]} Array of tag names.
    */
   getLoadTags() {
+    checkDestroy(this.#destroyed);
     return Array.from(this.#loadTags);
   }
 
@@ -466,6 +274,7 @@ class TinySmartScroller {
    * @param {string} tag - The tag name to add (e.g., 'IMG').
    */
   addLoadTag(tag) {
+    checkDestroy(this.#destroyed);
     if (typeof tag !== 'string') throw new TypeError('addLoadTag(tag): tag must be a string');
     this.#loadTags.add(tag.toUpperCase());
   }
@@ -476,6 +285,7 @@ class TinySmartScroller {
    * @param {string} tag - The tag name to remove.
    */
   removeLoadTag(tag) {
+    checkDestroy(this.#destroyed);
     if (typeof tag !== 'string') throw new TypeError('removeLoadTag(tag): tag must be a string');
     this.#loadTags.delete(tag.toUpperCase());
   }
@@ -487,6 +297,7 @@ class TinySmartScroller {
    * @returns {boolean} True if the tag is being tracked.
    */
   hasLoadTag(tag) {
+    checkDestroy(this.#destroyed);
     if (typeof tag !== 'string') throw new TypeError('hasLoadTag(tag): tag must be a string');
     return this.#loadTags.has(tag.toUpperCase());
   }
@@ -498,6 +309,7 @@ class TinySmartScroller {
    * @throws {TypeError} If `addDefault` is not a boolean.
    */
   resetLoadTags(addDefault = false) {
+    checkDestroy(this.#destroyed);
     if (typeof addDefault !== 'boolean')
       throw new TypeError('resetLoadTags(addDefault): addDefault must be a boolean');
     this.#loadTags.clear();
@@ -513,6 +325,7 @@ class TinySmartScroller {
    * @returns {string[]} Array of attribute names.
    */
   getAttributeFilters() {
+    checkDestroy(this.#destroyed);
     return Array.from(this.#attributeFilter);
   }
 
@@ -522,6 +335,7 @@ class TinySmartScroller {
    * @param {string} attr - The attribute name to add.
    */
   addAttributeFilter(attr) {
+    checkDestroy(this.#destroyed);
     if (typeof attr !== 'string')
       throw new TypeError('addAttributeFilter(attr): attr must be a string');
     this.#attributeFilter.add(attr);
@@ -533,6 +347,7 @@ class TinySmartScroller {
    * @param {string} attr - The attribute name to remove.
    */
   removeAttributeFilter(attr) {
+    checkDestroy(this.#destroyed);
     if (typeof attr !== 'string')
       throw new TypeError('removeAttributeFilter(attr): attr must be a string');
     this.#attributeFilter.delete(attr);
@@ -545,6 +360,7 @@ class TinySmartScroller {
    * @returns {boolean} True if the attribute is being filtered.
    */
   hasAttributeFilter(attr) {
+    checkDestroy(this.#destroyed);
     if (typeof attr !== 'string')
       throw new TypeError('hasAttributeFilter(attr): attr must be a string');
     return this.#attributeFilter.has(attr);
@@ -558,6 +374,7 @@ class TinySmartScroller {
    * @throws {TypeError} If `addDefault` is not a boolean.
    */
   resetAttributeFilters(addDefault = false) {
+    checkDestroy(this.#destroyed);
     if (typeof addDefault !== 'boolean')
       throw new TypeError('resetAttributeFilters(addDefault): addDefault must be a boolean');
     this.#attributeFilter.clear();
@@ -573,7 +390,7 @@ class TinySmartScroller {
    * @param {NodeSizesEvent} handler - Function that compares old and new sizes.
    */
   onSize(handler) {
-    if (this.#destroyed) return;
+    checkDestroy(this.#destroyed);
     if (typeof handler !== 'function')
       throw new TypeError('onSize(handler): handler must be a function');
     this.#sizeFilter.add(handler);
@@ -585,7 +402,7 @@ class TinySmartScroller {
    * @param {NodeSizesEvent} handler - The handler function to remove.
    */
   offSize(handler) {
-    if (this.#destroyed) return;
+    checkDestroy(this.#destroyed);
     if (typeof handler !== 'function')
       throw new TypeError('offSize(handler): handler must be a function');
     this.#sizeFilter.delete(handler);
@@ -595,6 +412,7 @@ class TinySmartScroller {
    * Checks which elements inside the target are currently visible and updates internal maps.
    *
    * @returns {Map<Element, { oldIsVisible: boolean; isVisible: boolean }>} Visibility comparison results.
+   * @private
    */
   _scrollDataUpdater() {
     const results = new Map();
@@ -612,6 +430,7 @@ class TinySmartScroller {
 
   /**
    * Handles scroll events, calculates position-related statuses, and emits appropriate events.
+   * @private
    */
   _onScroll() {
     if (this.#destroyed) return;
@@ -673,6 +492,7 @@ class TinySmartScroller {
    * Attempts to correct the scroll position when layout shifts happen, preserving the user position if needed.
    *
    * @param {Element[]} [targets=[]] - List of elements involved in the size change.
+   * @private
    */
   _fixScroll(targets = []) {
     if (this.#destroyed) return;
@@ -762,6 +582,7 @@ class TinySmartScroller {
   }
   /**
    * Sets up a MutationObserver to watch for DOM changes and react accordingly to maintain scroll consistency.
+   * @private
    */
   _observeMutations() {
     this.#mutationObserver = new MutationObserver((mutations) => {
@@ -802,6 +623,7 @@ class TinySmartScroller {
    * Adds a ResizeObserver to monitor elements' size changes and trigger layout adjustments.
    *
    * @param {NodeListOf<Element>|Element[]|HTMLCollection} elements - Elements to observe.
+   * @private
    */
   _observeResizes(elements) {
     // Add resize observer
@@ -842,6 +664,7 @@ class TinySmartScroller {
    * Listens for media/content load events (e.g., images, iframes, videos) to trigger scroll updates.
    *
    * @param {NodeListOf<Element>|Element} elements - Target element(s) to listen on.
+   * @private
    */
   _listenLoadEvents(elements) {
     if (this.#destroyed) return;
@@ -880,6 +703,7 @@ class TinySmartScroller {
    * @returns {NodeSizes|null} The old size, or undefined.
    */
   getOldSize(el) {
+    checkDestroy(this.#destroyed);
     return this.#oldSizes.get(el) ?? null;
   }
 
@@ -890,6 +714,7 @@ class TinySmartScroller {
    * @returns {NodeSizes|null} The new size, or undefined.
    */
   getNewSize(el) {
+    checkDestroy(this.#destroyed);
     return this.#newSizes.get(el) ?? null;
   }
 
@@ -900,6 +725,7 @@ class TinySmartScroller {
    * @returns {boolean} True if visible, false if not, or undefined if not tracked.
    */
   wasVisible(el) {
+    checkDestroy(this.#destroyed);
     return this.#oldVisibles.get(el) ?? false;
   }
 
@@ -910,6 +736,7 @@ class TinySmartScroller {
    * @returns {boolean} True if visible, false if not, or undefined if not tracked.
    */
   isVisible(el) {
+    checkDestroy(this.#destroyed);
     return this.#newVisibles.get(el) ?? false;
   }
 
@@ -920,6 +747,7 @@ class TinySmartScroller {
    * @returns {boolean} Visibility state from the previous timed check.
    */
   wasTimedVisible(el) {
+    checkDestroy(this.#destroyed);
     return this.#oldVisiblesByTime.get(el) ?? false;
   }
 
@@ -930,6 +758,7 @@ class TinySmartScroller {
    * @returns {boolean} Visibility state from the current timed check.
    */
   isTimedVisible(el) {
+    checkDestroy(this.#destroyed);
     return this.#newVisiblesByTime.get(el) ?? false;
   }
 
@@ -939,6 +768,7 @@ class TinySmartScroller {
    * @param {number} value - Pixels of additional margin to use.
    */
   setExtraScrollBoundary(value) {
+    checkDestroy(this.#destroyed);
     if (typeof value !== 'number' || Number.isNaN(value))
       throw new TypeError('setExtraScrollBoundary(value): value must be a valid number');
     this.#extraScrollBoundary = value;
@@ -950,6 +780,7 @@ class TinySmartScroller {
    * @returns {number}
    */
   getExtraScrollBoundary() {
+    checkDestroy(this.#destroyed);
     return this.#extraScrollBoundary;
   }
 
@@ -959,6 +790,7 @@ class TinySmartScroller {
    * @returns {number}
    */
   getLastKnownScrollBottomOffset() {
+    checkDestroy(this.#destroyed);
     return this.#lastKnownScrollBottomOffset;
   }
 
@@ -966,6 +798,7 @@ class TinySmartScroller {
    * Forces the scroll position to move to the very bottom of the target.
    */
   scrollToBottom() {
+    checkDestroy(this.#destroyed);
     this.#targetElement.scrollTop = this.#targetElement.scrollHeight;
   }
 
@@ -973,6 +806,7 @@ class TinySmartScroller {
    * Forces the scroll position to move to the very top of the target.
    */
   scrollToTop() {
+    checkDestroy(this.#destroyed);
     this.#targetElement.scrollTop = 0;
   }
 
@@ -982,6 +816,7 @@ class TinySmartScroller {
    * @returns {boolean}
    */
   isAtCustomBottom() {
+    checkDestroy(this.#destroyed);
     return this.#isAtCustomBottom;
   }
 
@@ -991,6 +826,7 @@ class TinySmartScroller {
    * @returns {boolean}
    */
   isAtCustomTop() {
+    checkDestroy(this.#destroyed);
     return this.#isAtCustomTop;
   }
 
@@ -1000,6 +836,7 @@ class TinySmartScroller {
    * @returns {boolean}
    */
   isAtBottom() {
+    checkDestroy(this.#destroyed);
     return this.#isAtBottom;
   }
 
@@ -1009,6 +846,7 @@ class TinySmartScroller {
    * @returns {boolean}
    */
   isAtTop() {
+    checkDestroy(this.#destroyed);
     return this.#isAtTop;
   }
 
@@ -1018,6 +856,7 @@ class TinySmartScroller {
    * @returns {boolean}
    */
   isPastAtBottom() {
+    checkDestroy(this.#destroyed);
     return this.#isPastAtBottom;
   }
 
@@ -1027,6 +866,7 @@ class TinySmartScroller {
    * @returns {boolean}
    */
   isPastAtTop() {
+    checkDestroy(this.#destroyed);
     return this.#isPastAtTop;
   }
 
@@ -1036,6 +876,7 @@ class TinySmartScroller {
    * @returns {boolean}
    */
   isPastAtCustomTop() {
+    checkDestroy(this.#destroyed);
     return this.#isPastAtCustomTop;
   }
 
@@ -1045,6 +886,7 @@ class TinySmartScroller {
    * @returns {boolean}
    */
   isPastAtCustomBottom() {
+    checkDestroy(this.#destroyed);
     return this.#isPastAtCustomBottom;
   }
 
@@ -1054,6 +896,7 @@ class TinySmartScroller {
    * @returns {boolean}
    */
   isScrollPaused() {
+    checkDestroy(this.#destroyed);
     return this.#scrollPaused;
   }
 
@@ -1063,6 +906,7 @@ class TinySmartScroller {
    * @returns {boolean} True if the scroll target is window, false otherwise.
    */
   isWindow() {
+    checkDestroy(this.#destroyed);
     return this.#useWindow;
   }
 
@@ -1081,6 +925,7 @@ class TinySmartScroller {
    * @returns {boolean} True if auto-scroll is active, false otherwise.
    */
   getAutoScrollBottom() {
+    checkDestroy(this.#destroyed);
     return this.#autoScrollBottom;
   }
 
@@ -1090,6 +935,7 @@ class TinySmartScroller {
    * @returns {boolean} True if mutation observation is active, false otherwise.
    */
   getObserveMutations() {
+    checkDestroy(this.#destroyed);
     return this.#observeMutations;
   }
 
@@ -1099,6 +945,7 @@ class TinySmartScroller {
    * @returns {boolean} True if scroll preservation is active, false otherwise.
    */
   getPreserveScrollOnLayoutShift() {
+    checkDestroy(this.#destroyed);
     return this.#preserveScrollOnLayoutShift;
   }
 
@@ -1108,6 +955,7 @@ class TinySmartScroller {
    * @returns {number} Debounce delay time.
    */
   getDebounceTime() {
+    checkDestroy(this.#destroyed);
     return this.#debounceTime;
   }
 
@@ -1117,6 +965,7 @@ class TinySmartScroller {
    * @returns {number} Current count of matching elements.
    */
   getElemAmount() {
+    checkDestroy(this.#destroyed);
     return this.#elemAmount;
   }
 
@@ -1126,6 +975,7 @@ class TinySmartScroller {
    * @returns {number} Previous count of matching elements.
    */
   getPrevElemAmount() {
+    checkDestroy(this.#destroyed);
     return this.#elemOldAmount;
   }
 
@@ -1135,6 +985,7 @@ class TinySmartScroller {
    * @returns {string} The CSS selector string, or an empty string if none was provided.
    */
   getQuerySelector() {
+    checkDestroy(this.#destroyed);
     return this.#querySelector;
   }
 
@@ -1144,7 +995,6 @@ class TinySmartScroller {
    */
   destroy() {
     if (this.#destroyed) return;
-    this.#destroyed = true;
 
     // Disconnects MutationObserver
     if (this.#mutationObserver) {
@@ -1171,9 +1021,10 @@ class TinySmartScroller {
     this.#oldVisiblesByTime = new WeakMap();
 
     // Cleans listeners and filters
-    this.#events.offAllTypes();
+    this.removeAllListeners();
     this.#sizeFilter.clear();
     this.#loadTags.clear();
+    this.#destroyed = true;
   }
 }