tiny-essentials 1.27.1 → 1.28.1

package/dist/v1/libs/TinySmartScroller.mjs

@@ -1,6 +1,8 @@
+import { EventEmitter } from 'events';
 import TinyHtml from './TinyHtml.mjs';
 import * as TinyCollision from '../basics/collision.mjs';
-import TinyEvents from './TinyEvents.mjs';
+import { createCheckDestroyed } from './utils.mjs';
+const checkDestroy = createCheckDestroyed('TinySmartScroller');
 /**
  * Represents the dimensions of a DOM element.
  *
@@ -42,181 +44,8 @@ import TinyEvents from './TinyEvents.mjs';
  * 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 EventEmitter {
     static Utils = { ...TinyCollision, 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>} */
@@ -281,6 +110,7 @@ class TinySmartScroller {
      *     - Which attributes to observe for changes.
      */
     constructor(target, { extraScrollBoundary = 0, autoScrollBottom = true, observeMutations = true, preserveScrollOnLayoutShift = true, debounceTime = 100, querySelector = null, attributeFilter = ['class', 'style', 'src', 'data-*', 'height', 'width'], } = {}) {
+        super();
         // === target ===
         if (!(target instanceof Element ||
             // @ts-ignore
@@ -344,6 +174,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) => {
@@ -362,6 +193,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);
@@ -374,6 +206,7 @@ class TinySmartScroller {
      * @returns {string[]} Array of tag names.
      */
     getLoadTags() {
+        checkDestroy(this.#destroyed);
         return Array.from(this.#loadTags);
     }
     /**
@@ -382,6 +215,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());
@@ -392,6 +226,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());
@@ -403,6 +238,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());
@@ -414,6 +250,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();
@@ -429,6 +266,7 @@ class TinySmartScroller {
      * @returns {string[]} Array of attribute names.
      */
     getAttributeFilters() {
+        checkDestroy(this.#destroyed);
         return Array.from(this.#attributeFilter);
     }
     /**
@@ -437,6 +275,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);
@@ -447,6 +286,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);
@@ -458,6 +298,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);
@@ -470,6 +311,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();
@@ -483,8 +325,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);
@@ -495,8 +336,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);
@@ -505,6 +345,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();
@@ -519,6 +360,7 @@ class TinySmartScroller {
     }
     /**
      * Handles scroll events, calculates position-related statuses, and emits appropriate events.
+     * @private
      */
     _onScroll() {
         if (this.#destroyed)
@@ -574,6 +416,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)
@@ -650,6 +493,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) => {
@@ -685,6 +529,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
@@ -722,6 +567,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)
@@ -757,6 +603,7 @@ class TinySmartScroller {
      * @returns {NodeSizes|null} The old size, or undefined.
      */
     getOldSize(el) {
+        checkDestroy(this.#destroyed);
         return this.#oldSizes.get(el) ?? null;
     }
     /**
@@ -766,6 +613,7 @@ class TinySmartScroller {
      * @returns {NodeSizes|null} The new size, or undefined.
      */
     getNewSize(el) {
+        checkDestroy(this.#destroyed);
         return this.#newSizes.get(el) ?? null;
     }
     /**
@@ -775,6 +623,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;
     }
     /**
@@ -784,6 +633,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;
     }
     /**
@@ -793,6 +643,7 @@ class TinySmartScroller {
      * @returns {boolean} Visibility state from the previous timed check.
      */
     wasTimedVisible(el) {
+        checkDestroy(this.#destroyed);
         return this.#oldVisiblesByTime.get(el) ?? false;
     }
     /**
@@ -802,6 +653,7 @@ class TinySmartScroller {
      * @returns {boolean} Visibility state from the current timed check.
      */
     isTimedVisible(el) {
+        checkDestroy(this.#destroyed);
         return this.#newVisiblesByTime.get(el) ?? false;
     }
     /**
@@ -810,6 +662,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;
@@ -820,6 +673,7 @@ class TinySmartScroller {
      * @returns {number}
      */
     getExtraScrollBoundary() {
+        checkDestroy(this.#destroyed);
         return this.#extraScrollBoundary;
     }
     /**
@@ -828,18 +682,21 @@ class TinySmartScroller {
      * @returns {number}
      */
     getLastKnownScrollBottomOffset() {
+        checkDestroy(this.#destroyed);
         return this.#lastKnownScrollBottomOffset;
     }
     /**
      * Forces the scroll position to move to the very bottom of the target.
      */
     scrollToBottom() {
+        checkDestroy(this.#destroyed);
         this.#targetElement.scrollTop = this.#targetElement.scrollHeight;
     }
     /**
      * Forces the scroll position to move to the very top of the target.
      */
     scrollToTop() {
+        checkDestroy(this.#destroyed);
         this.#targetElement.scrollTop = 0;
     }
     /**
@@ -848,6 +705,7 @@ class TinySmartScroller {
      * @returns {boolean}
      */
     isAtCustomBottom() {
+        checkDestroy(this.#destroyed);
         return this.#isAtCustomBottom;
     }
     /**
@@ -856,6 +714,7 @@ class TinySmartScroller {
      * @returns {boolean}
      */
     isAtCustomTop() {
+        checkDestroy(this.#destroyed);
         return this.#isAtCustomTop;
     }
     /**
@@ -864,6 +723,7 @@ class TinySmartScroller {
      * @returns {boolean}
      */
     isAtBottom() {
+        checkDestroy(this.#destroyed);
         return this.#isAtBottom;
     }
     /**
@@ -872,6 +732,7 @@ class TinySmartScroller {
      * @returns {boolean}
      */
     isAtTop() {
+        checkDestroy(this.#destroyed);
         return this.#isAtTop;
     }
     /**
@@ -880,6 +741,7 @@ class TinySmartScroller {
      * @returns {boolean}
      */
     isPastAtBottom() {
+        checkDestroy(this.#destroyed);
         return this.#isPastAtBottom;
     }
     /**
@@ -888,6 +750,7 @@ class TinySmartScroller {
      * @returns {boolean}
      */
     isPastAtTop() {
+        checkDestroy(this.#destroyed);
         return this.#isPastAtTop;
     }
     /**
@@ -896,6 +759,7 @@ class TinySmartScroller {
      * @returns {boolean}
      */
     isPastAtCustomTop() {
+        checkDestroy(this.#destroyed);
         return this.#isPastAtCustomTop;
     }
     /**
@@ -904,6 +768,7 @@ class TinySmartScroller {
      * @returns {boolean}
      */
     isPastAtCustomBottom() {
+        checkDestroy(this.#destroyed);
         return this.#isPastAtCustomBottom;
     }
     /**
@@ -912,6 +777,7 @@ class TinySmartScroller {
      * @returns {boolean}
      */
     isScrollPaused() {
+        checkDestroy(this.#destroyed);
         return this.#scrollPaused;
     }
     /**
@@ -920,6 +786,7 @@ class TinySmartScroller {
      * @returns {boolean} True if the scroll target is window, false otherwise.
      */
     isWindow() {
+        checkDestroy(this.#destroyed);
         return this.#useWindow;
     }
     /**
@@ -936,6 +803,7 @@ class TinySmartScroller {
      * @returns {boolean} True if auto-scroll is active, false otherwise.
      */
     getAutoScrollBottom() {
+        checkDestroy(this.#destroyed);
         return this.#autoScrollBottom;
     }
     /**
@@ -944,6 +812,7 @@ class TinySmartScroller {
      * @returns {boolean} True if mutation observation is active, false otherwise.
      */
     getObserveMutations() {
+        checkDestroy(this.#destroyed);
         return this.#observeMutations;
     }
     /**
@@ -952,6 +821,7 @@ class TinySmartScroller {
      * @returns {boolean} True if scroll preservation is active, false otherwise.
      */
     getPreserveScrollOnLayoutShift() {
+        checkDestroy(this.#destroyed);
         return this.#preserveScrollOnLayoutShift;
     }
     /**
@@ -960,6 +830,7 @@ class TinySmartScroller {
      * @returns {number} Debounce delay time.
      */
     getDebounceTime() {
+        checkDestroy(this.#destroyed);
         return this.#debounceTime;
     }
     /**
@@ -968,6 +839,7 @@ class TinySmartScroller {
      * @returns {number} Current count of matching elements.
      */
     getElemAmount() {
+        checkDestroy(this.#destroyed);
         return this.#elemAmount;
     }
     /**
@@ -976,6 +848,7 @@ class TinySmartScroller {
      * @returns {number} Previous count of matching elements.
      */
     getPrevElemAmount() {
+        checkDestroy(this.#destroyed);
         return this.#elemOldAmount;
     }
     /**
@@ -984,6 +857,7 @@ class TinySmartScroller {
      * @returns {string} The CSS selector string, or an empty string if none was provided.
      */
     getQuerySelector() {
+        checkDestroy(this.#destroyed);
         return this.#querySelector;
     }
     /**
@@ -993,7 +867,6 @@ class TinySmartScroller {
     destroy() {
         if (this.#destroyed)
             return;
-        this.#destroyed = true;
         // Disconnects MutationObserver
         if (this.#mutationObserver) {
             this.#mutationObserver.disconnect();
@@ -1016,9 +889,10 @@ class TinySmartScroller {
         this.#newVisiblesByTime = new WeakMap();
         this.#oldVisiblesByTime = new WeakMap();
         // Cleans listeners and filters
-        this.#events.offAllTypes();
+        this.removeAllListeners();
         this.#sizeFilter.clear();
         this.#loadTags.clear();
+        this.#destroyed = true;
     }
 }
 export default TinySmartScroller;