tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
154 lines • 6.38 kB
text/typescript
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