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.
165 lines • 6.39 kB
text/typescript
export default TinyToastNotify;
/**
* A callback function used to manually close a notification.
* Passed as a second argument to `onClick` handlers, allowing programmatic dismissal of the toast.
*/
export type CloseToastFunc = () => void;
/**
* Represents the data used to display a notification.
* Can be a plain string (used as the message), or an object with more customization options.
*/
export type NotifyData = string | {
message: string;
title?: string;
onClick?: (arg0: MouseEvent, arg1: CloseToastFunc) => void;
html?: boolean;
avatar?: string;
};
/**
* A callback function used to manually close a notification.
* Passed as a second argument to `onClick` handlers, allowing programmatic dismissal of the toast.
*
* @typedef {() => void} CloseToastFunc
*/
/**
* Represents the data used to display a notification.
* Can be a plain string (used as the message), or an object with more customization options.
*
* @typedef {string | {
* message: string, // The main message to display
* title?: string, // Optional title to appear above the message
* onClick?: function(MouseEvent, CloseToastFunc): void, // Optional click handler for the notification
* html?: boolean, // Whether the message should be interpreted as raw HTML
* avatar?: string // Optional URL to an avatar image shown on the left
* }} NotifyData
*/
/**
* A lightweight notification system designed to display timed messages inside a container.
* Supports positioning, timing customization, click actions, HTML content, and optional avatars.
*
* ## Features:
* - Positioning via `x` (`left`, `center`, `right`) and `y` (`top`, `bottom`).
* - Dynamic display time based on message length.
* - Optional `title`, `avatar`, `onClick`, and `html` message rendering.
* - Fade-out animation with customizable duration.
* - Rigid validation of inputs and internal state.
*
* ## Customization via setters:
* - `setX(position)` — horizontal alignment.
* - `setY(position)` — vertical alignment.
* - `setBaseDuration(ms)` — base visible time in milliseconds.
* - `setExtraPerChar(ms)` — extra time added per character.
* - `setFadeOutDuration(ms)` — fade-out animation duration in milliseconds.
*
* @class
*/
declare class TinyToastNotify {
/**
* @param {'top'|'bottom'} y - 'top' or 'bottom'
* @param {'right'|'left'|'center'} x - 'right', 'left', or 'center'
* @param {number} baseDuration - Base display time in ms
* @param {number} extraPerChar - Extra ms per character
* @param {number} fadeOutDuration - Time in ms for fade-out effect
* @param {string} [selector='.notify-container'] - Base selector for container
*/
constructor(y?: "top" | "bottom", x?: "right" | "left" | "center", baseDuration?: number, extraPerChar?: number, fadeOutDuration?: number, selector?: string);
/**
* Returns the notification container element.
* Ensures that the container is a valid HTMLElement.
*
* @returns {HTMLElement} The notification container.
* @throws {Error} If the container is not a valid HTMLElement.
*/
getContainer(): HTMLElement;
/**
* Returns the current vertical position.
*
* @returns {'top'|'bottom'} The vertical direction of the notification container.
*/
getY(): "top" | "bottom";
/**
* Sets the vertical position of the notification container.
* Updates the container's class to reflect the new position.
*
* @param {'top'|'bottom'} value - The vertical direction to set.
* @throws {Error} If the value is invalid.
*/
setY(value: "top" | "bottom"): void;
/**
* Returns the current horizontal position.
*
* @returns {'left'|'right'|'center'} The horizontal direction of the notification container.
*/
getX(): "left" | "right" | "center";
/**
* Sets the horizontal position of the notification container.
* Updates the container's class to reflect the new position.
*
* @param {'left'|'right'|'center'} value - The horizontal direction to set.
* @throws {Error} If the value is invalid.
*/
setX(value: "left" | "right" | "center"): void;
/**
* Returns the base duration for displaying the notification.
*
* @returns {number} Base time (in milliseconds) that a notification stays on screen.
*/
getBaseDuration(): number;
/**
* Sets the base duration for the notification display time.
*
* @param {number} value - Base display time in milliseconds.
* @throws {Error} If the value is not a valid non-negative finite number.
*/
setBaseDuration(value: number): void;
/**
* Returns the extra display time added per character.
*
* @returns {number} Extra time (in milliseconds) per character in the notification.
*/
getExtraPerChar(): number;
/**
* Sets the additional display time per character.
*
* @param {number} value - Extra time in milliseconds per character.
* @throws {Error} If the value is not a valid non-negative finite number.
*/
setExtraPerChar(value: number): void;
/**
* Returns the fade-out duration.
*
* @returns {number} Time (in milliseconds) used for fade-out transition.
*/
getFadeOutDuration(): number;
/**
* Sets the fade-out transition time for notifications.
*
* @param {number} value - Fade-out duration in milliseconds.
* @throws {Error} If the value is not a valid non-negative finite number.
*/
setFadeOutDuration(value: number): void;
/**
* Displays a notification for a time based on message length.
* Accepts a string or an object with:
* {
* message: string,
* title?: string,
* onClick?: function(MouseEvent, CloseToastFunc): void,
* html?: boolean,
* avatar?: string // Optional avatar image URL
* }
*
* @param {NotifyData} data
*/
show(data: NotifyData): void;
/**
* Destroys the notification container and removes all active notifications.
* This should be called when the notification system is no longer needed,
* such as when unloading a page or switching views in a single-page app.
*
* @returns {void}
*/
destroy(): void;
#private;
}
//# sourceMappingURL=TinyToastNotify.d.mts.map