tiny-essentials 1.16.0 → 1.16.2

package/dist/v1/TinyAfterScrollWatcher.js

@@ -0,0 +1,219 @@
+/******/ (() => { // webpackBootstrap
+/******/ 	"use strict";
+/******/ 	// The require scope
+/******/ 	var __webpack_require__ = {};
+/******/ 	
+/************************************************************************/
+/******/ 	/* webpack/runtime/define property getters */
+/******/ 	(() => {
+/******/ 		// define getter functions for harmony exports
+/******/ 		__webpack_require__.d = (exports, definition) => {
+/******/ 			for(var key in definition) {
+/******/ 				if(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {
+/******/ 					Object.defineProperty(exports, key, { enumerable: true, get: definition[key] });
+/******/ 				}
+/******/ 			}
+/******/ 		};
+/******/ 	})();
+/******/ 	
+/******/ 	/* webpack/runtime/hasOwnProperty shorthand */
+/******/ 	(() => {
+/******/ 		__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))
+/******/ 	})();
+/******/ 	
+/************************************************************************/
+var __webpack_exports__ = {};
+
+// EXPORTS
+__webpack_require__.d(__webpack_exports__, {
+  TinyAfterScrollWatcher: () => (/* reexport */ libs_TinyAfterScrollWatcher)
+});
+
+;// ./src/v1/libs/TinyAfterScrollWatcher.mjs
+/**
+ * @typedef {(() => void)} FnData - Function with no arguments and no return value
+ */
+
+/**
+ * A function that handles a scroll event.
+ * It receives a standard `Event` object when a scroll occurs.
+ *
+ * @typedef {(ev: Event) => void} OnScrollFunc
+ */
+
+/**
+ * A scroll tracker that queues functions to be executed
+ * after the user stops scrolling a specific element or the window.
+ */
+class TinyAfterScrollWatcher {
+  /** @type {Element|Window} */
+  #scrollTarget;
+
+  /** @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;
+
+  /**
+   * @param {Element|Window} scrollTarget - The element or window to track scrolling on
+   * @param {number} [inactivityTime=100] - Time in milliseconds to wait after scroll ends before executing the queue
+   * @throws {TypeError} If scrollTarget is not a valid Element or Window
+   * @throws {TypeError} If inactivityTime is not a positive number
+   */
+  constructor(scrollTarget = window, inactivityTime = 100) {
+    if (!(scrollTarget instanceof Element) && !(scrollTarget instanceof Window))
+      throw new TypeError('scrollTarget must be an Element or the Window object.');
+    this.#scrollTarget = scrollTarget;
+    this._checkTimer = this._checkTimer.bind(this);
+
+    this.#scrollTarget.addEventListener('scroll', this._checkTimer);
+    this.#inactivityTime = inactivityTime;
+  }
+
+  _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}
+   */
+  get inactivityTime() {
+    return this.#inactivityTime;
+  }
+
+  /**
+   * Sets a new inactivity time.
+   * Must be a positive number (in milliseconds).
+   * @param {number} value
+   * @throws {Error} If value is not a positive number
+   */
+  set inactivityTime(value) {
+    if (typeof value !== 'number' || value <= 0 || !Number.isFinite(value))
+      throw new Error('inactivityTime must be a positive number in milliseconds.');
+    this.#inactivityTime = value;
+  }
+
+  /**
+   * Continuously checks whether the user has stopped scrolling,
+   * and if so, runs all queued functions.
+   */
+  #checkQueue() {
+    if (this.#destroyed) return;
+    // 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();
+    }
+  }
+
+  /**
+   * Adds a function to be executed after scroll has stopped.
+   * The scroll is considered "stopped" after the configured inactivity time.
+   *
+   * @param {() => void} fn - A function to execute once scrolling has stopped.
+   * @throws {TypeError} If the argument is not a function.
+   */
+  doAfterScroll(fn) {
+    if (typeof fn !== 'function') throw new TypeError('Argument must be a function.');
+    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.
+   *
+   * @param {OnScrollFunc} fn - The scroll listener to add
+   * @throws {TypeError} If the argument is not a function.
+   */
+  onScroll(fn) {
+    if (typeof fn !== 'function') throw new TypeError('Argument must be a function.');
+    this.#scrollTarget.addEventListener('scroll', fn);
+    this.#externalScrollListeners.add(fn);
+  }
+
+  /**
+   * Removes a previously registered scroll listener from the tracked element.
+   *
+   * @param {OnScrollFunc} fn - The scroll listener to remove
+   * @throws {TypeError} If the argument is not a function.
+   */
+  offScroll(fn) {
+    if (typeof fn !== 'function') throw new TypeError('Argument must be a function.');
+    if (this.#externalScrollListeners.has(fn)) {
+      this.#scrollTarget.removeEventListener('scroll', fn);
+      this.#externalScrollListeners.delete(fn);
+    }
+  }
+
+  /**
+   * Destroys the watcher by removing internal listeners and clearing data.
+   */
+  destroy() {
+    if (this.#destroyed) return;
+    this.#destroyed = true;
+
+    this.#scrollTarget.removeEventListener('scroll', this._checkTimer);
+    for (const fn of this.#externalScrollListeners)
+      this.#scrollTarget.removeEventListener('scroll', fn);
+
+    this.#externalScrollListeners.clear();
+    this.#onStopListeners.clear();
+  }
+}
+
+/* harmony default export */ const libs_TinyAfterScrollWatcher = (TinyAfterScrollWatcher);
+
+;// ./src/v1/build/TinyAfterScrollWatcher.mjs
+
+
+
+
+window.TinyAfterScrollWatcher = __webpack_exports__.TinyAfterScrollWatcher;
+/******/ })()
+;

package/dist/v1/TinyAfterScrollWatcher.min.js

@@ -0,0 +1 @@
+(()=>{"use strict";var e={d:(t,r)=>{for(var i in r)e.o(r,i)&&!e.o(t,i)&&Object.defineProperty(t,i,{enumerable:!0,get:r[i]})},o:(e,t)=>Object.prototype.hasOwnProperty.call(e,t)},t={};e.d(t,{TinyAfterScrollWatcher:()=>r});const r=class{#e;#t=null;#r=[];#i=100;#o=new Set;#n=new Set;#s=!1;constructor(e=window,t=100){if(!(e instanceof Element||e instanceof Window))throw new TypeError("scrollTarget must be an Element or the Window object.");this.#e=e,this._checkTimer=this._checkTimer.bind(this),this.#e.addEventListener("scroll",this._checkTimer),this.#i=t}_checkTimer=()=>{this.#t&&clearTimeout(this.#t),this.#t=setTimeout((()=>{this.#t=null,this.#l()}),this.#i)};get inactivityTime(){return this.#i}set inactivityTime(e){if("number"!=typeof e||e<=0||!Number.isFinite(e))throw new Error("inactivityTime must be a positive number in milliseconds.");this.#i=e}#l(){if(!this.#s){for(const e of this.#n)"function"==typeof e&&e();for(;this.#r.length;){const e=this.#r.pop();"function"==typeof e&&e()}}}doAfterScroll(e){if("function"!=typeof e)throw new TypeError("Argument must be a function.");this.lastScrollTime=Date.now(),this.#r.push(e)}onStop(e){if("function"!=typeof e)throw new TypeError("Argument must be a function.");this.#n.add(e)}offStop(e){if("function"!=typeof e)throw new TypeError("Argument must be a function.");this.#n.delete(e)}onScroll(e){if("function"!=typeof e)throw new TypeError("Argument must be a function.");this.#e.addEventListener("scroll",e),this.#o.add(e)}offScroll(e){if("function"!=typeof e)throw new TypeError("Argument must be a function.");this.#o.has(e)&&(this.#e.removeEventListener("scroll",e),this.#o.delete(e))}destroy(){if(!this.#s){this.#s=!0,this.#e.removeEventListener("scroll",this._checkTimer);for(const e of this.#o)this.#e.removeEventListener("scroll",e);this.#o.clear(),this.#n.clear()}}};window.TinyAfterScrollWatcher=t.TinyAfterScrollWatcher})();