tiny-essentials 1.12.2 → 1.13.1

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),
@@ -2919,6 +2920,7 @@ __webpack_require__.d(__webpack_exports__, {
   formatCustomTimer: () => (/* reexport */ formatCustomTimer),
   formatDayTimer: () => (/* reexport */ formatDayTimer),
   formatTimer: () => (/* reexport */ formatTimer),
+  genFibonacciSeq: () => (/* reexport */ genFibonacciSeq),
   getAge: () => (/* reexport */ getAge),
   getHtmlElBorders: () => (/* reexport */ getHtmlElBorders),
   getHtmlElBordersWidth: () => (/* reexport */ getHtmlElBordersWidth),
@@ -4131,6 +4133,43 @@ function formatBytes(bytes, decimals = null, maxUnit = null) {
   return { unit, value };
 }
 
+/**
+ * Generates a Fibonacci-like sequence as an array of vectors.
+ *
+ * @param {Object} [settings={}]
+ * @param {number[]} [settings.baseValues=[0, 1]] - An array of two starting numbers (e.g. [0, 1] or [1, 1]).
+ * @param {number} [settings.length=10] - Total number of items to generate in the sequence.
+ * @param {(a: number, b: number, index: number) => number} [settings.combiner=((a, b) => a + b)] - A custom function to combine previous two numbers.
+ * @returns {number[]} The resulting Fibonacci sequence.
+ *
+ * FibonacciVectors2D
+ * @example
+ * generateFibonacciSequence({
+ *   baseValues: [[0, 1], [1, 1]],
+ *   length: 10,
+ *   combiner: ([x1, y1], [x2, y2]) => [x1 + x2, y1 + y2]
+ * });
+ *
+ * @beta
+ */
+function genFibonacciSeq({
+  baseValues = [0, 1],
+  length = 10,
+  combiner = (a, b) => a + b,
+} = {}) {
+  if (!Array.isArray(baseValues) || baseValues.length !== 2)
+    throw new Error('baseValues must be an array of exactly two numbers');
+
+  const sequence = [...baseValues.slice(0, 2)];
+
+  for (let i = 2; i < length; i++) {
+    const next = combiner(sequence[i - 2], sequence[i - 1], i);
+    sequence.push(next);
+  }
+
+  return sequence;
+}
+
 ;// ./src/v1/basics/text.mjs
 /**
  * Converts a string to title case where the first letter of each word is capitalized.
@@ -8200,6 +8239,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 +8437,7 @@ class TinyDragger {
 
 
 
+
 
 
 })();