tiny-essentials 1.22.15 → 1.23.0

package/dist/v1/libs/TinyLoadingScreen.mjs

@@ -0,0 +1,314 @@
+/**
+ * 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;
+    }
+}
+export default TinyLoadingScreen;

package/docs/v1/README.md

@@ -58,6 +58,7 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🎮 **[TinyNeedBar](./libs/TinyNeedBar.md)** — A versatile "need bar" system for simulating decay over time with multiple configurable factors, serialization, cloning, and full control over clamped and infinite values.
 - 🎲 **[TinySimpleDice](./libs/TinySimpleDice.md)** — A lightweight and flexible dice rolling utility with configurable maximum values, zero allowance, and array/Set index rolling support.
 - 👀 **[TinyElementObserver](./libs/TinyElementObserver.md)** — A DOM mutation tracking utility built on MutationObserver, with customizable detectors for handling changes, event dispatching, and lifecycle management.  
+- ⏳ **[TinyLoadingScreen](./libs/TinyLoadingScreen.md)** — A lightweight, fully-configurable loading overlay with fade-in/out animations, custom messages (string or HTMLElement), HTML rendering option, and status-change callbacks.
 
 ### 3. **`fileManager/`**
 * 📁 **[Main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.

package/docs/v1/libs/TinyLoadingScreen.md

@@ -0,0 +1,186 @@
+# TinyLoadingScreen 📦✨
+
+A lightweight, fully-configurable **loading overlay component** that can be appended to any HTML element.
+
+It allows you to display a customizable overlay with a spinner and message while your app is loading content.
+
+---
+
+## Constructor 🏗️
+
+```ts
+new TinyLoadingScreen(container?: HTMLElement)
+```
+
+* `container` — The HTML element where the overlay will be appended. Defaults to `document.body`.
+* Throws `TypeError` if the container is not an `HTMLElement`.
+
+---
+
+## Properties 🔑
+
+| Property         | Type                                      | Description                                                    |
+| ---------------- | ----------------------------------------- | -------------------------------------------------------------- |
+| `overlay`        | `HTMLDivElement \| null`                  | The overlay element if active, otherwise `null`.               |
+| `messageElement` | `HTMLDivElement \| null`                  | The element used to render the message, or `null` if inactive. |
+| `container`      | `HTMLElement`                             | The container element that holds the overlay.                  |
+| `status`         | `'none'\|'fadeIn'\|'active'\|'fadeOut'`    | Current state of the loading screen.                           |
+| `defaultMessage` | `string \| HTMLElement`                   | Default message to display when no custom message is provided. |
+| `message`        | `string \| HTMLElement \| null`           | Currently displayed message.                                   |
+| `allowHtmlText`  | `boolean`                                 | Whether HTML is allowed inside string messages.                |
+| `visible`        | `boolean`                                 | `true` if the overlay is currently visible, `false` otherwise. |
+| `onChange`       | `(status: LoadingStatus) => void \| null` | Optional callback fired whenever the status changes.           |
+
+---
+
+## Options ⚙️
+
+You can configure the loading screen using the `options` property:
+
+```ts
+loader.options = {
+  fadeIn: 300,   // milliseconds, null = no animation
+  fadeOut: 300,  // milliseconds, null = no animation
+  zIndex: 9999   // overlay z-index
+};
+```
+
+* Throws `TypeError` if invalid values are provided.
+
+---
+
+## Methods 🛠️
+
+### `start(message?: string | HTMLElement) → boolean` ✅
+
+* Starts the loading screen, or updates the message if already active.
+* `message` — The message to display. Defaults to `defaultMessage`.
+* Returns `true` if overlay was created, `false` if only the message was updated.
+* Throws `TypeError` if `message` is not a string or HTMLElement.
+
+---
+
+### `update(message?: string | HTMLElement) → boolean` ✏️
+
+* Updates the loading screen message.
+* Returns `true` if the message was updated, `false` if overlay is not active.
+* Throws `TypeError` if `message` is not a string or HTMLElement.
+
+---
+
+### `stop() → boolean` ❌
+
+* Stops and removes the loading screen.
+* Returns `true` if overlay was removed, `false` if overlay was not active.
+
+---
+
+### Internal / Private Methods 🔒
+
+| Method                    | Description                                                                                           |
+| ------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `_updateMessage(message)` | Updates the displayed message. Throws errors if invalid types or HTMLElement without `allowHtmlText`. |
+| `_removeOldClasses()`     | Removes all status-related CSS classes (`active`, `fadeIn`, `fadeOut`) from the overlay.              |
+| `_emitChange()`           | Emits the `onChange` callback with the current `status`.                                              |
+
+> ⚠️ Private methods are for internal use only.
+
+---
+
+## Status States 🟢⚪🔴
+
+The loading screen has four states:
+
+| Status      | Meaning                              |
+| ----------- | ------------------------------------ |
+| `'none'`    | Not visible                          |
+| `'fadeIn'`  | Appearing with fade-in animation     |
+| `'active'`  | Fully visible and active             |
+| `'fadeOut'` | Disappearing with fade-out animation |
+
+* `onChange` callback is fired whenever the status changes.
+
+---
+
+## Callbacks 🔔
+
+### `onChange: (status: LoadingStatus) => void`
+
+```ts
+loader.onChange = (status) => {
+  console.log('Loading screen status:', status);
+};
+```
+
+* Fired on every status change: `fadeIn`, `active`, `fadeOut`, `none`.
+
+---
+
+## Usage Examples 💡
+
+### Basic Example
+
+```js
+import TinyLoadingScreen from './TinyLoadingScreen.mjs';
+
+const loader = new TinyLoadingScreen();
+loader.defaultMessage = 'Loading...';
+loader.start();
+
+// Stop after 2 seconds
+setTimeout(() => loader.stop(), 2000);
+```
+
+---
+
+### Custom Container
+
+```js
+const container = document.getElementById('custom-container');
+const loader2 = new TinyLoadingScreen(container);
+loader2.defaultMessage = 'Loading content...';
+loader2.start();
+
+// Update message dynamically
+loader2.update('Almost done...');
+```
+
+---
+
+### With onChange Callback
+
+```js
+loader.onChange = (status) => {
+  console.log('Status changed:', status);
+};
+```
+
+---
+
+### Custom Animations ⏳
+
+```js
+loader.options = {
+  fadeIn: 500,  // fade-in duration in ms
+  fadeOut: 500, // fade-out duration in ms
+  zIndex: 10000
+};
+```
+
+---
+
+### Allow HTML Messages 🖌️
+
+```js
+loader.allowHtmlText = true;
+loader.start('<b>Loading <i>data</i>...</b>');
+```
+
+---
+
+### Notes 📝
+
+* Fade durations can be `null` to disable animations.
+* HTML messages require `allowHtmlText = true`.
+* `_removeOldClasses()` ensures that multiple animations don't conflict.
+* Use `onChange` to hook into status changes for debugging or UI updates.