tiny-essentials 1.16.1 → 1.17.0

package/dist/v1/libs/TinyAfterScrollWatcher.mjs

@@ -14,14 +14,16 @@
 class TinyAfterScrollWatcher {
     /** @type {Element|Window} */
     #scrollTarget;
-    /** @type {number} */
-    lastScrollTime = 0;
+    /** @type {null|NodeJS.Timeout} */
+    #lastScrollTime = null;
     /** @type {FnData[]} */
     #afterScrollQueue = [];
     /** @type {number} */
     #inactivityTime = 100;
     /** @type {Set<OnScrollFunc>} */
     #externalScrollListeners = new Set();
+    /** @type {Set<FnData>} */
+    #onStopListeners = new Set();
     /** @type {boolean} */
     #destroyed = false;
     /**
@@ -34,12 +36,18 @@ class TinyAfterScrollWatcher {
         if (!(scrollTarget instanceof Element) && !(scrollTarget instanceof Window))
             throw new TypeError('scrollTarget must be an Element or the Window object.');
         this.#scrollTarget = scrollTarget;
-        this._onScroll = this._onScroll.bind(this);
-        this._checkQueue = this._checkQueue.bind(this);
-        this.#scrollTarget.addEventListener('scroll', this._onScroll);
+        this._checkTimer = this._checkTimer.bind(this);
+        this.#scrollTarget.addEventListener('scroll', this._checkTimer);
         this.#inactivityTime = inactivityTime;
-        requestAnimationFrame(this._checkQueue);
     }
+    _checkTimer = () => {
+        if (this.#lastScrollTime)
+            clearTimeout(this.#lastScrollTime);
+        this.#lastScrollTime = setTimeout(() => {
+            this.#lastScrollTime = null;
+            this.#checkQueue();
+        }, this.#inactivityTime);
+    };
     /**
      * Gets the current inactivity time in milliseconds.
      * @returns {number}
@@ -58,29 +66,23 @@ class TinyAfterScrollWatcher {
             throw new Error('inactivityTime must be a positive number in milliseconds.');
         this.#inactivityTime = value;
     }
-    /**
-     * Internal handler for scroll events.
-     * Updates the last scroll timestamp.
-     * @private
-     */
-    _onScroll() {
-        this.lastScrollTime = Date.now();
-    }
     /**
      * Continuously checks whether the user has stopped scrolling,
      * and if so, runs all queued functions.
-     * @private
      */
-    _checkQueue() {
+    #checkQueue() {
         if (this.#destroyed)
             return;
-        requestAnimationFrame(this._checkQueue);
-        if (Date.now() - this.lastScrollTime > this.#inactivityTime) {
-            while (this.#afterScrollQueue.length) {
-                const fn = this.#afterScrollQueue.pop();
-                if (typeof fn === 'function')
-                    fn();
-            }
+        // Runs all onStop first listeners
+        for (const fn of this.#onStopListeners) {
+            if (typeof fn === 'function')
+                fn();
+        }
+        // Then execute the queue afterScrollQueue
+        while (this.#afterScrollQueue.length) {
+            const fn = this.#afterScrollQueue.pop();
+            if (typeof fn === 'function')
+                fn();
         }
     }
     /**
@@ -96,6 +98,29 @@ class TinyAfterScrollWatcher {
         this.lastScrollTime = Date.now();
         this.#afterScrollQueue.push(fn);
     }
+    /**
+     * Registers a function to run once after scrolling has stopped,
+     * before any afterScrollQueue functions.
+     *
+     * @param {FnData} fn - A function to execute after scroll stop.
+     * @throws {TypeError} If the argument is not a function.
+     */
+    onStop(fn) {
+        if (typeof fn !== 'function')
+            throw new TypeError('Argument must be a function.');
+        this.#onStopListeners.add(fn);
+    }
+    /**
+     * Removes a previously registered onStop function.
+     *
+     * @param {FnData} fn - The function to remove.
+     * @throws {TypeError} If the argument is not a function.
+     */
+    offStop(fn) {
+        if (typeof fn !== 'function')
+            throw new TypeError('Argument must be a function.');
+        this.#onStopListeners.delete(fn);
+    }
     /**
      * Registers an external scroll listener on the tracked element.
      *
@@ -129,10 +154,11 @@ class TinyAfterScrollWatcher {
         if (this.#destroyed)
             return;
         this.#destroyed = true;
-        this.#scrollTarget.removeEventListener('scroll', this._onScroll);
+        this.#scrollTarget.removeEventListener('scroll', this._checkTimer);
         for (const fn of this.#externalScrollListeners)
             this.#scrollTarget.removeEventListener('scroll', fn);
         this.#externalScrollListeners.clear();
+        this.#onStopListeners.clear();
     }
 }
 export default TinyAfterScrollWatcher;