tiny-essentials 1.22.14 → 1.23.0

package/dist/v1/build/TinyLoadingScreen.cjs

@@ -0,0 +1,7 @@
+'use strict';
+
+var TinyLoadingScreen = require('../libs/TinyLoadingScreen.cjs');
+
+
+
+exports.TinyLoadingScreen = TinyLoadingScreen;

package/dist/v1/build/TinyLoadingScreen.d.mts

@@ -0,0 +1,3 @@
+export { TinyLoadingScreen };
+import TinyLoadingScreen from '../libs/TinyLoadingScreen.mjs';
+//# sourceMappingURL=TinyLoadingScreen.d.mts.map

package/dist/v1/build/TinyLoadingScreen.mjs

@@ -0,0 +1,2 @@
+import TinyLoadingScreen from '../libs/TinyLoadingScreen.mjs';
+export { TinyLoadingScreen };

package/dist/v1/css/TinyLoadingScreen.min.css

@@ -0,0 +1 @@
+.loading-overlay{position:absolute;top:0;left:0;width:100%;height:100%;background:rgba(0,0,0,.6);display:flex;justify-content:center;align-items:center;z-index:9999}.loading-overlay .loading-content{text-align:center;color:#fff;font-family:Arial,sans-serif}.loading-overlay .loading-spinner{border:4px solid hsla(0,0%,100%,.3);border-top:4px solid #fff;border-radius:50%;width:50px;height:50px;margin:0 auto 15px;animation:spin 1s linear infinite}.loading-overlay .loading-message{font-size:1.2em}@keyframes spin{0%{transform:rotate(0deg)}100%{transform:rotate(360deg)}}

package/dist/v1/index.cjs

@@ -47,6 +47,7 @@ var TinyI18 = require('./libs/TinyI18.cjs');
 var TinyNeedBar = require('./libs/TinyNeedBar.cjs');
 var TinySimpleDice = require('./libs/TinySimpleDice.cjs');
 var TinyElementObserver = require('./libs/TinyElementObserver.cjs');
+var TinyLoadingScreen = require('./libs/TinyLoadingScreen.cjs');
 
 
 
@@ -173,3 +174,4 @@ exports.TinyI18 = TinyI18;
 exports.TinyNeedBar = TinyNeedBar;
 exports.TinySimpleDice = TinySimpleDice;
 exports.TinyElementObserver = TinyElementObserver;
+exports.TinyLoadingScreen = TinyLoadingScreen;

package/dist/v1/index.d.mts

@@ -1,3 +1,4 @@
+import TinyLoadingScreen from './libs/TinyLoadingScreen.mjs';
 import TinyElementObserver from './libs/TinyElementObserver.mjs';
 import TinySimpleDice from './libs/TinySimpleDice.mjs';
 import TinyNeedBar from './libs/TinyNeedBar.mjs';
@@ -121,5 +122,5 @@ import { getTimeDuration } from './basics/clock.mjs';
 import { shuffleArray } from './basics/array.mjs';
 import { toTitleCase } from './basics/text.mjs';
 import { toTitleCaseLowerFirst } from './basics/text.mjs';
-export { TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyEvents, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, diffArrayList, diffStrings, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
+export { TinyLoadingScreen, TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyEvents, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, diffArrayList, diffStrings, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/index.mjs

@@ -45,4 +45,5 @@ import TinyI18 from './libs/TinyI18.mjs';
 import TinyNeedBar from './libs/TinyNeedBar.mjs';
 import TinySimpleDice from './libs/TinySimpleDice.mjs';
 import TinyElementObserver from './libs/TinyElementObserver.mjs';
-export { TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyEvents, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, diffArrayList, diffStrings, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+import TinyLoadingScreen from './libs/TinyLoadingScreen.mjs';
+export { TinyLoadingScreen, TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyEvents, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, diffArrayList, diffStrings, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };

package/dist/v1/libs/TinyHtml.cjs

@@ -2633,6 +2633,7 @@ class TinyHtml {
    */
   constructor(el) {
     this.#el = TinyHtml._selector(el);
+    this.#mainDisplay = TinyHtml.#defaultDisplay;
   }
 
   /**
@@ -3735,21 +3736,21 @@ class TinyHtml {
   // TITLE: Animate DOM (Data)
 
   /** @type {string} */
-  #mainDisplay = 'block';
+  #mainDisplay = '';
 
-/**
- * Gets the current display value.
- * @returns {string}
- */
+  /**
+   * Gets the current display value.
+   * @returns {string}
+   */
   get mainDisplay() {
     return this.#mainDisplay;
   }
 
-/**
- * Sets the display value.
- * @param {string} value
- * @throws {TypeError} If the value is not a string.
- */
+  /**
+   * Sets the display value.
+   * @param {string} value
+   * @throws {TypeError} If the value is not a string.
+   */
   set mainDisplay(value) {
     if (typeof value !== 'string') throw new TypeError('mainDisplay must be a string.');
     this.#mainDisplay = value;
@@ -3758,19 +3759,19 @@ class TinyHtml {
   /** @type {string} */
   static #defaultDisplay = 'block';
 
-/**
- * Gets the default display value.
- * @returns {string}
- */
+  /**
+   * Gets the default display value.
+   * @returns {string}
+   */
   static get defaultDisplay() {
     return TinyHtml.#defaultDisplay;
   }
 
-/**
- * Sets the default display value.
- * @param {string} value
- * @throws {TypeError} If the value is not a string.
- */
+  /**
+   * Sets the default display value.
+   * @param {string} value
+   * @throws {TypeError} If the value is not a string.
+   */
   static set defaultDisplay(value) {
     if (typeof value !== 'string') throw new TypeError('defaultDisplay must be a string.');
     TinyHtml.#defaultDisplay = value;

package/dist/v1/libs/TinyHtml.mjs

@@ -2325,6 +2325,7 @@ class TinyHtml {
      */
     constructor(el) {
         this.#el = TinyHtml._selector(el);
+        this.#mainDisplay = TinyHtml.#defaultDisplay;
     }
     /**
      * Checks whether the given object is a window.
@@ -3340,7 +3341,7 @@ class TinyHtml {
     //////////////////////////////////////////////////
     // TITLE: Animate DOM (Data)
     /** @type {string} */
-    #mainDisplay = 'block';
+    #mainDisplay = '';
     /**
      * Gets the current display value.
      * @returns {string}

package/dist/v1/libs/TinyLoadingScreen.cjs

@@ -0,0 +1,361 @@
+'use strict';
+
+/**
+ * Represents the possible states of the loading screen.
+ * - `'none'` → Not visible
+ * - `'fadeIn'` → Appearing with fade-in animation
+ * - `'active'` → Fully visible and active
+ * - `'fadeOut'` → Disappearing with fade-out animation
+ * @typedef {'none'|'active'|'fadeIn'|'fadeOut'} LoadingStatus
+ */
+
+/**
+ * Configuration options for the loading screen.
+ * @typedef {Object} LoadingSettings
+ * @property {number|null} fadeIn - Duration of fade-in animation in milliseconds, or `null` to disable.
+ * @property {number|null} fadeOut - Duration of fade-out animation in milliseconds, or `null` to disable.
+ * @property {number} zIndex - CSS z-index of the overlay element.
+ */
+
+/**
+ * TinyLoadingScreen
+ *
+ * A lightweight, fully-configurable loading overlay component that can be appended to any HTMLElement.
+ *
+ * Key features:
+ * - Configurable fadeIn/fadeOut durations (milliseconds) and zIndex.
+ * - Accepts string or HTMLElement messages.
+ * - Optionally allows HTML inside string messages when `allowHtmlText` is enabled.
+ * - Exposes `overlay`, `messageElement`, `status`, `options` and helpers for testing and integration.
+ *
+ * @class
+ */
+class TinyLoadingScreen {
+  /** @type {HTMLDivElement|null} Overlay container element */
+  #overlay = null;
+
+  /** @returns {HTMLDivElement|null} The overlay element if active, otherwise `null`. */
+  get overlay() {
+    return this.#overlay;
+  }
+
+  /** @type {HTMLDivElement|null} Element containing the loading message */
+  #messageElement = null;
+
+  /** @returns {HTMLDivElement|null} The element used to render the message, or `null` if inactive. */
+  get messageElement() {
+    return this.#messageElement;
+  }
+
+  /** @type {HTMLElement} Container where the overlay will be attached */
+  #container;
+
+  /** @returns {HTMLElement} The container element that holds the overlay. */
+  get container() {
+    return this.#container;
+  }
+
+  /** @type {LoadingSettings} Internal configuration */
+  #options = { fadeIn: null, fadeOut: null, zIndex: 9999 };
+
+  /** @returns {LoadingSettings} A copy of the current configuration options. */
+  get options() {
+    return { ...this.#options };
+  }
+
+  /**
+   * Updates the loading screen options.
+   * @param {Partial<LoadingSettings>} value - New configuration values.
+   * @throws {TypeError} If any option has an invalid type or value.
+   */
+  set options(value) {
+    if (typeof value !== 'object' || value === null)
+      throw new TypeError('options must be an object');
+    if (
+      typeof value.fadeIn !== 'undefined' &&
+      value.fadeIn !== null &&
+      (typeof value.fadeIn !== 'number' || value.fadeIn < 0)
+    )
+      throw new TypeError('fadeIn must be a non-negative number or null');
+    if (
+      typeof value.fadeOut !== 'undefined' &&
+      value.fadeOut !== null &&
+      (typeof value.fadeOut !== 'number' || value.fadeOut < 0)
+    )
+      throw new TypeError('fadeOut must be a non-negative number or null');
+    if (
+      typeof value.zIndex !== 'undefined' &&
+      (typeof value.zIndex !== 'number' || !Number.isInteger(value.zIndex))
+    )
+      throw new TypeError('zIndex must be an integer number');
+
+    this.#options = {
+      fadeIn: value.fadeIn ?? null,
+      fadeOut: value.fadeOut ?? null,
+      zIndex: value.zIndex ?? 9999,
+    };
+  }
+
+  /** @type {LoadingStatus} Current status of the loading screen */
+  #status = 'none';
+
+  /** @returns {LoadingStatus} The current loading screen status. */
+  get status() {
+    return this.#status;
+  }
+
+  /** @type {string|HTMLElement} Default message shown when no custom message is provided */
+  #defaultMessage = '';
+
+  /** @returns {string|HTMLElement} The default message. */
+  get defaultMessage() {
+    return this.#defaultMessage;
+  }
+
+  /**
+   * @param {string|HTMLElement} value - New default message.
+   * @throws {TypeError} If the value is neither a string nor an HTMLElement.
+   */
+  set defaultMessage(value) {
+    if (typeof value !== 'string' && !(value instanceof HTMLElement))
+      throw new TypeError('defaultMessage must be a string or an HTMLElement');
+    this.#defaultMessage = value;
+  }
+
+  /** @type {string|HTMLElement|null} Current active message */
+  #message = null;
+
+  /** @returns {string|HTMLElement|null} The currently displayed message. */
+  get message() {
+    return this.#message;
+  }
+
+  /** @type {boolean} Whether HTML is allowed in string messages */
+  #allowHtmlText = false;
+
+  /** @returns {boolean} True if HTML is allowed inside string messages. */
+  get allowHtmlText() {
+    return this.#allowHtmlText;
+  }
+
+  /**
+   * Enables or disables HTML rendering in string messages.
+   * @param {boolean} value - Whether to allow HTML.
+   * @throws {TypeError} If value is not a boolean.
+   */
+  set allowHtmlText(value) {
+    if (typeof value !== 'boolean') throw new TypeError('allowHtmlText must be a boolean');
+    this.#allowHtmlText = value;
+  }
+
+  /** @type {NodeJS.Timeout|null} Timeout handler for fadeIn */
+  #fadeInTimeout = null;
+
+  /** @returns {boolean} Whether a fadeIn timeout is currently pending. */
+  get fadeInTimeout() {
+    return this.#fadeInTimeout !== null;
+  }
+
+  /** @type {NodeJS.Timeout|null} Timeout handler for fadeOut */
+  #fadeOutTimeout = null;
+
+  /** @returns {boolean} Whether a fadeOut timeout is currently pending. */
+  get fadeOutTimeout() {
+    return this.#fadeOutTimeout !== null;
+  }
+
+  /** @returns {boolean} True if the overlay is currently visible. */
+  get visible() {
+    return !!this.#overlay;
+  }
+
+  /**
+   * Optional callback fired whenever the loading screen status changes.
+   * @type {((status: LoadingStatus) => void) | null}
+   */
+  #onChange = null;
+
+  /**
+   * Returns the current status-change callback.
+   * @returns {((status: LoadingStatus) => void) | null}
+   */
+  get onChange() {
+    return this.#onChange;
+  }
+
+  /**
+   * Sets the status-change callback.
+   * @param {((status: LoadingStatus) => void) | null} value
+   * @throws {TypeError} If value is neither a function nor null.
+   */
+  set onChange(value) {
+    if (value !== null && typeof value !== 'function') {
+      throw new TypeError('onChange must be a function or null');
+    }
+    this.#onChange = value;
+  }
+
+  /**
+   * Internal helper to emit the onChange callback.
+   * @private
+   */
+  _emitChange() {
+    if (typeof this.#onChange === 'function') this.#onChange(this.#status);
+  }
+
+  /**
+   * Creates a new TinyLoadingScreen instance.
+   * @param {HTMLElement} [container=document.body] - The container element where the overlay should be appended.
+   * @throws {TypeError} If container is not an HTMLElement.
+   */
+  constructor(container = document.body) {
+    if (!(container instanceof HTMLElement))
+      throw new TypeError('container must be an HTMLElement');
+    this.#container = container;
+  }
+
+  /**
+   * Internal helper to update the displayed message.
+   * @param {string|HTMLElement} [message=this.#defaultMessage] - The new message.
+   * @throws {TypeError} If the message is not a string or HTMLElement.
+   * @throws {Error} If trying to use HTMLElement without allowHtmlText enabled.
+   * @private
+   */
+  _updateMessage(message = this.#defaultMessage) {
+    if (!this.#messageElement) throw new Error('messageElement is not initialized');
+    if (typeof message !== 'string' && !(message instanceof HTMLElement))
+      throw new TypeError('message must be a string or an HTMLElement');
+
+    this.#message = message;
+
+    if (typeof message === 'string') {
+      if (!this.#allowHtmlText) this.#messageElement.textContent = message;
+      else this.#messageElement.innerHTML = message;
+    } else {
+      if (!this.#allowHtmlText)
+        throw new Error('HTMLElement messages require allowHtmlText = true');
+      this.#messageElement.textContent = '';
+      this.#messageElement.appendChild(message);
+    }
+  }
+
+  /**
+   * Removes all status-related CSS classes (`active`, `fadeIn`, `fadeOut`)
+   * from the overlay element, if it exists.
+   *
+   * @private
+   * @returns {void}
+   */
+  _removeOldClasses() {
+    this.#overlay?.classList.remove('active');
+    this.#overlay?.classList.remove('fadeIn');
+    this.#overlay?.classList.remove('fadeOut');
+  }
+
+  /**
+   * Starts the loading screen or updates its message if already active.
+   * @param {string|HTMLElement} [message=this.#defaultMessage] - Message to display.
+   * @returns {boolean} `true` if the overlay was created, `false` if only the message was updated.
+   * @throws {TypeError} If message is not a string or HTMLElement.
+   */
+  start(message = this.#defaultMessage) {
+    if (typeof message !== 'string' && !(message instanceof HTMLElement))
+      throw new TypeError('message must be a string or an HTMLElement');
+
+    if (!this.#overlay) {
+      this.#overlay = document.createElement('div');
+      this.#overlay.classList.add('loading-overlay');
+      this.#overlay.style.zIndex = String(this.#options.zIndex);
+
+      const content = document.createElement('div');
+      content.classList.add('loading-content');
+
+      const spinner = document.createElement('div');
+      spinner.classList.add('loading-spinner');
+
+      this.#messageElement = document.createElement('div');
+      this.#messageElement.classList.add('loading-message');
+
+      content.appendChild(spinner);
+      content.appendChild(this.#messageElement);
+      this.#overlay.appendChild(content);
+      this.#container.appendChild(this.#overlay);
+
+      // trigger fade in
+      this._removeOldClasses();
+      this.#status = 'fadeIn';
+      this.#overlay.classList.add('fadeIn');
+      this._emitChange();
+      const fadeIn = () => {
+        this._removeOldClasses();
+        this.#fadeInTimeout = null;
+        this.#status = 'active';
+        this.#overlay?.classList.add('active');
+        this._emitChange();
+      };
+
+      if (typeof this.#options.fadeIn === 'number') {
+        if (this.#fadeInTimeout) clearTimeout(this.#fadeInTimeout);
+        this.#fadeInTimeout = setTimeout(fadeIn, this.#options.fadeIn);
+      } else fadeIn();
+
+      this._updateMessage(message);
+      return true;
+    }
+
+    if (this.#messageElement) this._updateMessage(message);
+    return false;
+  }
+
+  /**
+   * Updates the loading screen with a new message.
+   * @param {string|HTMLElement} [message=this.#defaultMessage] - The new message.
+   * @returns {boolean} `true` if the message was updated, `false` if overlay is not active.
+   * @throws {TypeError} If message is not a string or HTMLElement.
+   */
+  update(message = this.#defaultMessage) {
+    if (typeof message !== 'string' && !(message instanceof HTMLElement))
+      throw new TypeError('message must be a string or an HTMLElement');
+
+    if (this.#messageElement) {
+      this._updateMessage(message);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Stops and removes the loading screen.
+   * @returns {boolean} `true` if the overlay was removed, `false` if not active.
+   */
+  stop() {
+    if (this.#overlay) {
+      this._removeOldClasses();
+      this.#status = 'fadeOut';
+      this.#overlay.classList.add('fadeOut');
+      this._emitChange();
+
+      // trigger fade out
+      const fadeOut = () => {
+        this._removeOldClasses();
+        this.#fadeOutTimeout = null;
+        this.#status = 'none';
+        this.#overlay?.remove();
+        this.#overlay = null;
+        this.#messageElement = null;
+        this.#message = null;
+        this._emitChange();
+      };
+
+      if (typeof this.#options.fadeOut === 'number') {
+        if (this.#fadeOutTimeout) clearTimeout(this.#fadeOutTimeout);
+        this.#fadeOutTimeout = setTimeout(fadeOut, this.#options.fadeOut);
+      } else fadeOut();
+
+      return true;
+    }
+    return false;
+  }
+}
+
+module.exports = TinyLoadingScreen;

package/dist/v1/libs/TinyLoadingScreen.d.mts

@@ -0,0 +1,154 @@
+export default TinyLoadingScreen;
+/**
+ * Represents the possible states of the loading screen.
+ * - `'none'` → Not visible
+ * - `'fadeIn'` → Appearing with fade-in animation
+ * - `'active'` → Fully visible and active
+ * - `'fadeOut'` → Disappearing with fade-out animation
+ */
+export type LoadingStatus = "none" | "active" | "fadeIn" | "fadeOut";
+/**
+ * Configuration options for the loading screen.
+ */
+export type LoadingSettings = {
+    /**
+     * - Duration of fade-in animation in milliseconds, or `null` to disable.
+     */
+    fadeIn: number | null;
+    /**
+     * - Duration of fade-out animation in milliseconds, or `null` to disable.
+     */
+    fadeOut: number | null;
+    /**
+     * - CSS z-index of the overlay element.
+     */
+    zIndex: number;
+};
+/**
+ * Represents the possible states of the loading screen.
+ * - `'none'` → Not visible
+ * - `'fadeIn'` → Appearing with fade-in animation
+ * - `'active'` → Fully visible and active
+ * - `'fadeOut'` → Disappearing with fade-out animation
+ * @typedef {'none'|'active'|'fadeIn'|'fadeOut'} LoadingStatus
+ */
+/**
+ * Configuration options for the loading screen.
+ * @typedef {Object} LoadingSettings
+ * @property {number|null} fadeIn - Duration of fade-in animation in milliseconds, or `null` to disable.
+ * @property {number|null} fadeOut - Duration of fade-out animation in milliseconds, or `null` to disable.
+ * @property {number} zIndex - CSS z-index of the overlay element.
+ */
+/**
+ * TinyLoadingScreen
+ *
+ * A lightweight, fully-configurable loading overlay component that can be appended to any HTMLElement.
+ *
+ * Key features:
+ * - Configurable fadeIn/fadeOut durations (milliseconds) and zIndex.
+ * - Accepts string or HTMLElement messages.
+ * - Optionally allows HTML inside string messages when `allowHtmlText` is enabled.
+ * - Exposes `overlay`, `messageElement`, `status`, `options` and helpers for testing and integration.
+ *
+ * @class
+ */
+declare class TinyLoadingScreen {
+    /**
+     * Creates a new TinyLoadingScreen instance.
+     * @param {HTMLElement} [container=document.body] - The container element where the overlay should be appended.
+     * @throws {TypeError} If container is not an HTMLElement.
+     */
+    constructor(container?: HTMLElement);
+    /** @returns {HTMLDivElement|null} The overlay element if active, otherwise `null`. */
+    get overlay(): HTMLDivElement | null;
+    /** @returns {HTMLDivElement|null} The element used to render the message, or `null` if inactive. */
+    get messageElement(): HTMLDivElement | null;
+    /** @returns {HTMLElement} The container element that holds the overlay. */
+    get container(): HTMLElement;
+    /**
+     * Updates the loading screen options.
+     * @param {Partial<LoadingSettings>} value - New configuration values.
+     * @throws {TypeError} If any option has an invalid type or value.
+     */
+    set options(value: Partial<LoadingSettings>);
+    /** @returns {LoadingSettings} A copy of the current configuration options. */
+    get options(): LoadingSettings;
+    /** @returns {LoadingStatus} The current loading screen status. */
+    get status(): LoadingStatus;
+    /**
+     * @param {string|HTMLElement} value - New default message.
+     * @throws {TypeError} If the value is neither a string nor an HTMLElement.
+     */
+    set defaultMessage(value: string | HTMLElement);
+    /** @returns {string|HTMLElement} The default message. */
+    get defaultMessage(): string | HTMLElement;
+    /** @returns {string|HTMLElement|null} The currently displayed message. */
+    get message(): string | HTMLElement | null;
+    /**
+     * Enables or disables HTML rendering in string messages.
+     * @param {boolean} value - Whether to allow HTML.
+     * @throws {TypeError} If value is not a boolean.
+     */
+    set allowHtmlText(value: boolean);
+    /** @returns {boolean} True if HTML is allowed inside string messages. */
+    get allowHtmlText(): boolean;
+    /** @returns {boolean} Whether a fadeIn timeout is currently pending. */
+    get fadeInTimeout(): boolean;
+    /** @returns {boolean} Whether a fadeOut timeout is currently pending. */
+    get fadeOutTimeout(): boolean;
+    /** @returns {boolean} True if the overlay is currently visible. */
+    get visible(): boolean;
+    /**
+     * Sets the status-change callback.
+     * @param {((status: LoadingStatus) => void) | null} value
+     * @throws {TypeError} If value is neither a function nor null.
+     */
+    set onChange(value: ((status: LoadingStatus) => void) | null);
+    /**
+     * Returns the current status-change callback.
+     * @returns {((status: LoadingStatus) => void) | null}
+     */
+    get onChange(): ((status: LoadingStatus) => void) | null;
+    /**
+     * Internal helper to emit the onChange callback.
+     * @private
+     */
+    private _emitChange;
+    /**
+     * Internal helper to update the displayed message.
+     * @param {string|HTMLElement} [message=this.#defaultMessage] - The new message.
+     * @throws {TypeError} If the message is not a string or HTMLElement.
+     * @throws {Error} If trying to use HTMLElement without allowHtmlText enabled.
+     * @private
+     */
+    private _updateMessage;
+    /**
+     * Removes all status-related CSS classes (`active`, `fadeIn`, `fadeOut`)
+     * from the overlay element, if it exists.
+     *
+     * @private
+     * @returns {void}
+     */
+    private _removeOldClasses;
+    /**
+     * Starts the loading screen or updates its message if already active.
+     * @param {string|HTMLElement} [message=this.#defaultMessage] - Message to display.
+     * @returns {boolean} `true` if the overlay was created, `false` if only the message was updated.
+     * @throws {TypeError} If message is not a string or HTMLElement.
+     */
+    start(message?: string | HTMLElement): boolean;
+    /**
+     * Updates the loading screen with a new message.
+     * @param {string|HTMLElement} [message=this.#defaultMessage] - The new message.
+     * @returns {boolean} `true` if the message was updated, `false` if overlay is not active.
+     * @throws {TypeError} If message is not a string or HTMLElement.
+     */
+    update(message?: string | HTMLElement): boolean;
+    /**
+     * Stops and removes the loading screen.
+     * @returns {boolean} `true` if the overlay was removed, `false` if not active.
+     */
+    stop(): boolean;
+    #private;
+}
+//# sourceMappingURL=TinyLoadingScreen.d.mts.map