tiny-essentials 1.12.2 → 1.13.0

package/dist/v1/TinyDomReadyManager.js

@@ -0,0 +1,213 @@
+/******/ (() => { // 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__, {
+  TinyDomReadyManager: () => (/* reexport */ libs_TinyDomReadyManager)
+});
+
+;// ./src/v1/libs/TinyDomReadyManager.mjs
+/**
+ * A basic function that performs a task when the system is ready.
+ * Used for handlers in the readiness queue.
+ *
+ * @typedef {() => void} Fn
+ */
+
+/**
+ * A function that determines whether a specific handler should be executed.
+ * Should return `true` to allow execution, or `false` to skip the handler.
+ *
+ * @typedef {() => boolean} FnFilter
+ */
+
+/**
+ * @typedef {Object} Handler
+ * @property {Fn} fn - Function to execute when ready.
+ * @property {boolean} once - Whether to execute only once.
+ * @property {number} priority - Execution order (higher priority runs first).
+ * @property {FnFilter|null} filter - Optional filter function to determine execution.
+ * @property {boolean} domOnly - Whether to run as soon as DOM is ready (before full readiness).
+ */
+
+class TinyDomReadyManager {
+  /** @type {Handler[]} */
+  #handlers = [];
+
+  /** @type {boolean} */
+  #isDomReady = false;
+
+  /** @type {boolean} */
+  #isFullyReady = false;
+
+  /** @type {Promise<any>[]} */
+  #promises = [];
+
+  /**
+   * Checks if the DOM is ready and if all Promises have been resolved.
+   */
+  #checkAllReady() {
+    if (this.#isDomReady) {
+      Promise.all(this.#promises)
+        .then(() => {
+          this.#isFullyReady = true;
+          this.#runHandlers(false); // run non-domOnly
+        })
+        .catch((err) => {
+          console.error('[TinyDomReadyManager] Promise rejected:', err);
+        });
+    }
+  }
+
+  /**
+   * Executes handlers by filtering them by `domOnly` flag and sorting by priority.
+   * @param {boolean} domOnlyOnly - Whether to run only `domOnly` handlers.
+   */
+  #runHandlers(domOnlyOnly) {
+    this.#handlers
+      .filter((h) => h.domOnly === domOnlyOnly)
+      .sort((a, b) => b.priority - a.priority)
+      .forEach((handler) => this.#invokeHandler(handler));
+
+    this.#handlers = this.#handlers.filter((h) => !(h.once && (domOnlyOnly ? h.domOnly : true)));
+  }
+
+  /**
+   * Executes a handler if its filter passes.
+   * @param {Handler} handler
+   */
+  #invokeHandler(handler) {
+    if (typeof handler.filter === 'function') {
+      try {
+        if (!handler.filter()) return;
+      } catch (err) {
+        console.warn('[TinyDomReadyManager] Filter error:', err);
+        return;
+      }
+    }
+
+    try {
+      handler.fn();
+    } catch (err) {
+      console.error('[TinyDomReadyManager] Handler error:', err);
+    }
+  }
+
+  /**
+   * Marks the system as DOM-ready and runs DOM-only handlers.
+   * @private
+   */
+  _markDomReady() {
+    this.#isDomReady = true;
+    this.#runHandlers(true); // Run domOnly
+    this.#checkAllReady(); // Then check for full readiness
+  }
+
+  /**
+   * Initializes the manager using `DOMContentLoaded`.
+   */
+  init() {
+    if (this.#isDomReady) throw new Error('[TinyDomReadyManager] init() has already been called.');
+
+    if (document.readyState === 'interactive' || document.readyState === 'complete') {
+      this._markDomReady();
+    } else {
+      document.addEventListener('DOMContentLoaded', () => this._markDomReady());
+    }
+  }
+
+  /**
+   * Adds a Promise to delay full readiness.
+   * @param {Promise<any>} promise
+   * @throws {TypeError}
+   */
+  addPromise(promise) {
+    if (!(promise instanceof Promise))
+      throw new TypeError('[TinyDomReadyManager] promise must be a valid Promise.');
+
+    if (this.#isFullyReady) return;
+    this.#promises.push(promise);
+    if (this.#isDomReady) this.#checkAllReady();
+  }
+
+  /**
+   * Registers a handler to run either after DOM is ready or after full readiness.
+   *
+   * @param {Fn} fn - Function to execute.
+   * @param {Object} [options]
+   * @param {boolean} [options.once=true] - Execute only once.
+   * @param {number} [options.priority=0] - Higher priority runs first.
+   * @param {FnFilter|null} [options.filter=null] - Optional filter function.
+   * @param {boolean} [options.domOnly=false] - If true, executes after DOM ready only.
+   * @throws {TypeError} If fn is not a function.
+   */
+  onReady(fn, { once = true, priority = 0, filter = null, domOnly = false } = {}) {
+    if (typeof fn !== 'function')
+      throw new TypeError('[TinyDomReadyManager] fn must be a function.');
+
+    const handler = { fn, once, priority, filter, domOnly };
+
+    if (domOnly && this.#isDomReady) {
+      this.#invokeHandler(handler);
+      if (!once) this.#handlers.push(handler);
+      return;
+    }
+
+    if (!domOnly && this.#isFullyReady) {
+      this.#invokeHandler(handler);
+    } else {
+      this.#handlers.push(handler);
+    }
+  }
+
+  /**
+   * Returns whether the system is fully ready (DOM + Promises).
+   * @returns {boolean}
+   */
+  isReady() {
+    return this.#isFullyReady;
+  }
+
+  /**
+   * Returns whether the DOM is ready (DOMContentLoaded has fired).
+   * Does not wait for promises.
+   * @returns {boolean}
+   */
+  isDomReady() {
+    return this.#isDomReady;
+  }
+}
+
+/* harmony default export */ const libs_TinyDomReadyManager = (TinyDomReadyManager);
+
+;// ./src/v1/build/TinyDomReadyManager.mjs
+
+
+
+
+window.TinyDomReadyManager = __webpack_exports__.TinyDomReadyManager;
+/******/ })()
+;

package/dist/v1/TinyDomReadyManager.min.js

@@ -0,0 +1 @@
+(()=>{"use strict";var e={d:(r,i)=>{for(var a in i)e.o(i,a)&&!e.o(r,a)&&Object.defineProperty(r,a,{enumerable:!0,get:i[a]})},o:(e,r)=>Object.prototype.hasOwnProperty.call(e,r)},r={};e.d(r,{TinyDomReadyManager:()=>i});const i=class{#e=[];#r=!1;#i=!1;#a=[];#n(){this.#r&&Promise.all(this.#a).then((()=>{this.#i=!0,this.#o(!1)})).catch((e=>{console.error("[TinyDomReadyManager] Promise rejected:",e)}))}#o(e){this.#e.filter((r=>r.domOnly===e)).sort(((e,r)=>r.priority-e.priority)).forEach((e=>this.#t(e))),this.#e=this.#e.filter((r=>!(r.once&&(!e||r.domOnly))))}#t(e){if("function"==typeof e.filter)try{if(!e.filter())return}catch(e){return void console.warn("[TinyDomReadyManager] Filter error:",e)}try{e.fn()}catch(e){console.error("[TinyDomReadyManager] Handler error:",e)}}_markDomReady(){this.#r=!0,this.#o(!0),this.#n()}init(){if(this.#r)throw new Error("[TinyDomReadyManager] init() has already been called.");"interactive"===document.readyState||"complete"===document.readyState?this._markDomReady():document.addEventListener("DOMContentLoaded",(()=>this._markDomReady()))}addPromise(e){if(!(e instanceof Promise))throw new TypeError("[TinyDomReadyManager] promise must be a valid Promise.");this.#i||(this.#a.push(e),this.#r&&this.#n())}onReady(e,{once:r=!0,priority:i=0,filter:a=null,domOnly:n=!1}={}){if("function"!=typeof e)throw new TypeError("[TinyDomReadyManager] fn must be a function.");const o={fn:e,once:r,priority:i,filter:a,domOnly:n};if(n&&this.#r)return this.#t(o),void(r||this.#e.push(o));!n&&this.#i?this.#t(o):this.#e.push(o)}isReady(){return this.#i}isDomReady(){return this.#r}};window.TinyDomReadyManager=r.TinyDomReadyManager})();

package/dist/v1/TinyEssentials.js

@@ -2886,6 +2886,7 @@ __webpack_require__.r(__webpack_exports__);
 // EXPORTS
 __webpack_require__.d(__webpack_exports__, {
   ColorSafeStringify: () => (/* reexport */ libs_ColorSafeStringify),
+  TinyDomReadyManager: () => (/* reexport */ libs_TinyDomReadyManager),
   TinyDragDropDetector: () => (/* reexport */ libs_TinyDragDropDetector),
   TinyDragger: () => (/* reexport */ libs_TinyDragger),
   TinyLevelUp: () => (/* reexport */ userLevel),
@@ -8200,6 +8201,180 @@ class TinyDragger {
 
 /* harmony default export */ const libs_TinyDragger = (TinyDragger);
 
+;// ./src/v1/libs/TinyDomReadyManager.mjs
+/**
+ * A basic function that performs a task when the system is ready.
+ * Used for handlers in the readiness queue.
+ *
+ * @typedef {() => void} Fn
+ */
+
+/**
+ * A function that determines whether a specific handler should be executed.
+ * Should return `true` to allow execution, or `false` to skip the handler.
+ *
+ * @typedef {() => boolean} FnFilter
+ */
+
+/**
+ * @typedef {Object} Handler
+ * @property {Fn} fn - Function to execute when ready.
+ * @property {boolean} once - Whether to execute only once.
+ * @property {number} priority - Execution order (higher priority runs first).
+ * @property {FnFilter|null} filter - Optional filter function to determine execution.
+ * @property {boolean} domOnly - Whether to run as soon as DOM is ready (before full readiness).
+ */
+
+class TinyDomReadyManager {
+  /** @type {Handler[]} */
+  #handlers = [];
+
+  /** @type {boolean} */
+  #isDomReady = false;
+
+  /** @type {boolean} */
+  #isFullyReady = false;
+
+  /** @type {Promise<any>[]} */
+  #promises = [];
+
+  /**
+   * Checks if the DOM is ready and if all Promises have been resolved.
+   */
+  #checkAllReady() {
+    if (this.#isDomReady) {
+      Promise.all(this.#promises)
+        .then(() => {
+          this.#isFullyReady = true;
+          this.#runHandlers(false); // run non-domOnly
+        })
+        .catch((err) => {
+          console.error('[TinyDomReadyManager] Promise rejected:', err);
+        });
+    }
+  }
+
+  /**
+   * Executes handlers by filtering them by `domOnly` flag and sorting by priority.
+   * @param {boolean} domOnlyOnly - Whether to run only `domOnly` handlers.
+   */
+  #runHandlers(domOnlyOnly) {
+    this.#handlers
+      .filter((h) => h.domOnly === domOnlyOnly)
+      .sort((a, b) => b.priority - a.priority)
+      .forEach((handler) => this.#invokeHandler(handler));
+
+    this.#handlers = this.#handlers.filter((h) => !(h.once && (domOnlyOnly ? h.domOnly : true)));
+  }
+
+  /**
+   * Executes a handler if its filter passes.
+   * @param {Handler} handler
+   */
+  #invokeHandler(handler) {
+    if (typeof handler.filter === 'function') {
+      try {
+        if (!handler.filter()) return;
+      } catch (err) {
+        console.warn('[TinyDomReadyManager] Filter error:', err);
+        return;
+      }
+    }
+
+    try {
+      handler.fn();
+    } catch (err) {
+      console.error('[TinyDomReadyManager] Handler error:', err);
+    }
+  }
+
+  /**
+   * Marks the system as DOM-ready and runs DOM-only handlers.
+   * @private
+   */
+  _markDomReady() {
+    this.#isDomReady = true;
+    this.#runHandlers(true); // Run domOnly
+    this.#checkAllReady(); // Then check for full readiness
+  }
+
+  /**
+   * Initializes the manager using `DOMContentLoaded`.
+   */
+  init() {
+    if (this.#isDomReady) throw new Error('[TinyDomReadyManager] init() has already been called.');
+
+    if (document.readyState === 'interactive' || document.readyState === 'complete') {
+      this._markDomReady();
+    } else {
+      document.addEventListener('DOMContentLoaded', () => this._markDomReady());
+    }
+  }
+
+  /**
+   * Adds a Promise to delay full readiness.
+   * @param {Promise<any>} promise
+   * @throws {TypeError}
+   */
+  addPromise(promise) {
+    if (!(promise instanceof Promise))
+      throw new TypeError('[TinyDomReadyManager] promise must be a valid Promise.');
+
+    if (this.#isFullyReady) return;
+    this.#promises.push(promise);
+    if (this.#isDomReady) this.#checkAllReady();
+  }
+
+  /**
+   * Registers a handler to run either after DOM is ready or after full readiness.
+   *
+   * @param {Fn} fn - Function to execute.
+   * @param {Object} [options]
+   * @param {boolean} [options.once=true] - Execute only once.
+   * @param {number} [options.priority=0] - Higher priority runs first.
+   * @param {FnFilter|null} [options.filter=null] - Optional filter function.
+   * @param {boolean} [options.domOnly=false] - If true, executes after DOM ready only.
+   * @throws {TypeError} If fn is not a function.
+   */
+  onReady(fn, { once = true, priority = 0, filter = null, domOnly = false } = {}) {
+    if (typeof fn !== 'function')
+      throw new TypeError('[TinyDomReadyManager] fn must be a function.');
+
+    const handler = { fn, once, priority, filter, domOnly };
+
+    if (domOnly && this.#isDomReady) {
+      this.#invokeHandler(handler);
+      if (!once) this.#handlers.push(handler);
+      return;
+    }
+
+    if (!domOnly && this.#isFullyReady) {
+      this.#invokeHandler(handler);
+    } else {
+      this.#handlers.push(handler);
+    }
+  }
+
+  /**
+   * Returns whether the system is fully ready (DOM + Promises).
+   * @returns {boolean}
+   */
+  isReady() {
+    return this.#isFullyReady;
+  }
+
+  /**
+   * Returns whether the DOM is ready (DOMContentLoaded has fired).
+   * Does not wait for promises.
+   * @returns {boolean}
+   */
+  isDomReady() {
+    return this.#isDomReady;
+  }
+}
+
+/* harmony default export */ const libs_TinyDomReadyManager = (TinyDomReadyManager);
+
 ;// ./src/v1/index.mjs
 
 
@@ -8224,6 +8399,7 @@ class TinyDragger {
 
 
 
+
 
 
 })();