tiny-essentials 1.10.2 → 1.11.0

package/dist/v1/libs/TinyToastNotify.mjs

@@ -0,0 +1,332 @@
+/**
+ * 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
+ */
+class TinyToastNotify {
+    #y;
+    #x;
+    #baseDuration;
+    #extraPerChar;
+    #fadeOutDuration;
+    #container;
+    /**
+     * @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', x = 'right', baseDuration = 3000, extraPerChar = 50, fadeOutDuration = 300, selector = '.notify-container') {
+        this.#validateY(y);
+        this.#validateX(x);
+        this.#validateTiming(baseDuration, 'baseDuration');
+        this.#validateTiming(extraPerChar, 'extraPerChar');
+        this.#validateTiming(fadeOutDuration, 'fadeOutDuration');
+        this.#y = y;
+        this.#x = x;
+        this.#baseDuration = baseDuration;
+        this.#extraPerChar = extraPerChar;
+        this.#fadeOutDuration = fadeOutDuration;
+        const container = document.querySelector(`${selector}.${y}.${x}`);
+        if (!(container instanceof HTMLElement)) {
+            this.#container = document.createElement('div');
+            this.#container.className = `notify-container ${y} ${x}`;
+            document.body.appendChild(this.#container);
+        }
+        else
+            this.#container = container;
+    }
+    /**
+     * 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() {
+        if (!(this.#container instanceof HTMLElement))
+            throw new Error('Container is not a valid HTMLElement.');
+        return this.#container;
+    }
+    /**
+     * Validates the vertical position value.
+     * Must be either 'top' or 'bottom'.
+     *
+     * @param {string} value - The vertical position to validate.
+     * @throws {Error} If the value is not 'top' or 'bottom'.
+     */
+    #validateY(value) {
+        if (!['top', 'bottom'].includes(value)) {
+            throw new Error(`Invalid vertical direction "${value}". Expected "top" or "bottom".`);
+        }
+    }
+    /**
+     * Validates the horizontal position value.
+     * Must be 'left', 'right', or 'center'.
+     *
+     * @param {string} value - The horizontal position to validate.
+     * @throws {Error} If the value is not one of the accepted directions.
+     */
+    #validateX(value) {
+        if (!['left', 'right', 'center'].includes(value)) {
+            throw new Error(`Invalid horizontal position "${value}". Expected "left", "right" or "center".`);
+        }
+    }
+    /**
+     * Validates a numeric timing value.
+     * Must be a non-negative finite number.
+     *
+     * @param {number} value - The number to validate.
+     * @param {string} name - The name of the parameter (used for error messaging).
+     * @throws {Error} If the number is invalid.
+     */
+    #validateTiming(value, name) {
+        if (typeof value !== 'number' || value < 0 || !Number.isFinite(value)) {
+            throw new Error(`Invalid value for "${name}": ${value}. Must be a non-negative finite number.`);
+        }
+    }
+    /**
+     * Returns the current vertical position.
+     *
+     * @returns {'top'|'bottom'} The vertical direction of the notification container.
+     */
+    getY() {
+        return this.#y;
+    }
+    /**
+     * 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) {
+        this.#validateY(value);
+        const container = this.getContainer();
+        container.classList.remove(this.#y);
+        container.classList.add(value);
+        this.#y = value;
+    }
+    /**
+     * Returns the current horizontal position.
+     *
+     * @returns {'left'|'right'|'center'} The horizontal direction of the notification container.
+     */
+    getX() {
+        return this.#x;
+    }
+    /**
+     * 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) {
+        this.#validateX(value);
+        const container = this.getContainer();
+        container.classList.remove(this.#x);
+        container.classList.add(value);
+        this.#x = value;
+    }
+    /**
+     * Returns the base duration for displaying the notification.
+     *
+     * @returns {number} Base time (in milliseconds) that a notification stays on screen.
+     */
+    getBaseDuration() {
+        return this.#baseDuration;
+    }
+    /**
+     * 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) {
+        this.#validateTiming(value, 'baseDuration');
+        this.#baseDuration = value;
+    }
+    /**
+     * Returns the extra display time added per character.
+     *
+     * @returns {number} Extra time (in milliseconds) per character in the notification.
+     */
+    getExtraPerChar() {
+        return this.#extraPerChar;
+    }
+    /**
+     * 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) {
+        this.#validateTiming(value, 'extraPerChar');
+        this.#extraPerChar = value;
+    }
+    /**
+     * Returns the fade-out duration.
+     *
+     * @returns {number} Time (in milliseconds) used for fade-out transition.
+     */
+    getFadeOutDuration() {
+        return this.#fadeOutDuration;
+    }
+    /**
+     * 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) {
+        this.#validateTiming(value, 'fadeOutDuration');
+        this.#fadeOutDuration = value;
+    }
+    /**
+     * 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) {
+        let message = '';
+        let title = '';
+        let onClick = null;
+        let useHTML = false;
+        let avatarUrl = null;
+        const notify = document.createElement('div');
+        notify.className = 'notify enter';
+        if (typeof data === 'string') {
+            message = data;
+        }
+        else if (typeof data === 'object' && data !== null && typeof data.message === 'string') {
+            message = data.message;
+            title = typeof data.title === 'string' ? data.title : '';
+            useHTML = data.html === true;
+            avatarUrl = typeof data.avatar === 'string' ? data.avatar : null;
+            if (data.onClick !== undefined) {
+                if (typeof data.onClick !== 'function') {
+                    throw new Error('onClick must be a function if defined');
+                }
+                onClick = data.onClick;
+                notify.classList.add('clickable');
+            }
+        }
+        else {
+            throw new Error(`Invalid argument for show(): expected string or { message: string, title?: string, onClick?: function, html?: boolean, avatar?: string }`);
+        }
+        // Add close button
+        const closeBtn = document.createElement('button');
+        closeBtn.innerHTML = '&times;';
+        closeBtn.className = 'close';
+        closeBtn.setAttribute('aria-label', 'Close');
+        // Optional hover effect
+        closeBtn.addEventListener('mouseenter', () => {
+            closeBtn.style.color = 'var(--notif-close-color-hover)';
+        });
+        closeBtn.addEventListener('mouseleave', () => {
+            closeBtn.style.color = 'var(--notif-close-color)';
+        });
+        // Avatar
+        if (avatarUrl) {
+            const avatar = document.createElement('img');
+            avatar.src = avatarUrl;
+            avatar.alt = 'avatar';
+            avatar.className = 'avatar';
+            notify.appendChild(avatar);
+        }
+        // Title
+        if (title) {
+            const titleElem = document.createElement('strong');
+            titleElem.textContent = title;
+            titleElem.style.display = 'block';
+            notify.appendChild(titleElem);
+        }
+        // Message
+        if (useHTML) {
+            const msgWrapper = document.createElement('div');
+            msgWrapper.innerHTML = message;
+            notify.appendChild(msgWrapper);
+        }
+        else {
+            notify.appendChild(document.createTextNode(message));
+        }
+        notify.appendChild(closeBtn);
+        this.getContainer().appendChild(notify);
+        const visibleTime = this.#baseDuration + message.length * this.#extraPerChar;
+        const totalTime = visibleTime + this.#fadeOutDuration;
+        // Close logic
+        let removed = false;
+        const close = () => {
+            if (removed)
+                return;
+            removed = true;
+            notify.classList.remove('enter', 'show');
+            notify.classList.add('exit');
+            setTimeout(() => notify.remove(), this.#fadeOutDuration);
+        };
+        // Click handler
+        if (typeof onClick === 'function') {
+            notify.addEventListener('click', (e) => {
+                if (e.target === closeBtn)
+                    return;
+                onClick(e, close);
+            });
+        }
+        // Close button click
+        closeBtn.addEventListener('click', (e) => {
+            e.stopPropagation();
+            close();
+        });
+        // Transition activation force soon after the element is added
+        setTimeout(() => {
+            notify.classList.remove('enter');
+            notify.classList.add('show');
+        }, 1);
+        setTimeout(() => close(), totalTime);
+    }
+}
+export default TinyToastNotify;

package/docs/{README.md → v1/README.md}

@@ -24,6 +24,8 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🏅 **[TinyLevelUp](./libs/TinyLevelUp.md)** — A class to manage user level-up logic based on experience points, providing methods for experience validation, addition, removal, and calculation.
 - 🎨 **[ColorSafeStringify](./libs/ColorSafeStringify.md)** — A utility for applying customizable ANSI colors to JSON strings in terminal outputs, supporting presets and fine-grained type-based highlighting.
 - 🚦 **[TinyRateLimiter](./libs/TinyRateLimiter.md)** — A flexible per-user rate limiter supporting time windows, hit caps, and automatic cleanup of inactive users.
+* 🔔 **[TinyNotifyCenter](./libs/TinyNotifyCenter.md)** — A dynamic notification center class to display, manage, and interact with notifications, supporting avatars, clickable items, HTML/text modes, and clean UI controls.
+* 🍞 **[TinyToastNotify](./libs/TinyToastNotify.md)** — A lightweight toast notification system supporting positioning, timing customization, avatars, click actions, and fade-out animations.
 
 ---
 

package/docs/{basics → v1/basics}/text.md

@@ -123,7 +123,7 @@ document.addEventListener('DOMContentLoaded', () => {
 
 You can use a pre-built CSS template for the `detect-made-by-ai` class, available in the following files:
 
-* `/dist/aiMarker.min.css` – A minified version of the CSS for production use.
-* `/dist/aiMarker.css` – The non-minified version for easier readability and customization.
+* `/dist/v1/css/aiMarker.min.css` – A minified version of the CSS for production use.
+* `/dist/v1/css/aiMarker.css` – The non-minified version for easier readability and customization.
 
 Simply include the appropriate file in your project to style the elements marked with the `detect-made-by-ai` class.

package/docs/v1/libs/TinyNotifyCenter.md

@@ -0,0 +1,291 @@
+# 🛎️ TinyNotifyCenter
+
+## Overview
+
+`TinyNotifyCenter` is a notification center component designed to display interactive alerts in the UI.
+
+This class renders a notification overlay on the page, allowing dynamic management of notification items — adding, clearing, and interacting with them in real time.
+
+---
+
+## 🔔 NotifyData Type
+
+A notification entry (`NotifyData`) can be either a simple string or an object with extra data:
+
+```ts
+type NotifyData = string | {
+  title?: string;                   // Optional title shown above the message
+  message: string;                  // Required message content (plain text or HTML)
+  avatar?: string;                  // Optional avatar image URL (displayed on the left)
+  onClick?: (e: MouseEvent) => void; // Optional click handler for the entire notification
+}
+```
+
+---
+
+## ✨ Features
+
+* Dynamic rendering of notification UI via the `insertTemplate()` method
+* Supports both plain text and HTML content in notifications
+* Optional avatars shown alongside notifications
+* Supports callback functions on notification click events
+* Each notification includes a close button for dismissal
+* Displays a badge with the count of active notifications
+
+---
+
+## 🏗️ Static Methods
+
+### `static getTemplate() : string`
+
+Returns the full HTML structure for the notification system as a **string**.
+
+This template includes:
+
+- A hidden `.notify-overlay` element containing the central notification panel (`#notifCenter`):
+  - Header with a **"Notifications"** label
+  - A **clear all** button (with checkmark icon)
+  - A **close** button (×)
+- A `.list` container to hold dynamically added notification items
+- A bell button (`.notify-bell`) to toggle the notification center, featuring:
+  - A bell SVG icon
+  - A badge (`#notifBadge`) displaying the number of active notifications
+
+> 💡 This HTML can be injected into the DOM using methods like `insertAdjacentHTML()` or parsed into elements with JavaScript or jQuery.
+
+---
+
+### `static insertTemplate(where = 'afterbegin') : void`
+
+Injects the full notification center HTML template into the `document.body`.
+
+- Uses `insertAdjacentHTML()` to insert the markup.
+- The `where` parameter controls the insertion point relative to the `<body>` element.
+  
+Possible values for `where`:
+
+| Value         | Description                              |
+|---------------|------------------------------------------|
+| `'afterbegin'` (default) | Insert right after the opening `<body>` tag |
+| `'beforeend'`             | Insert right before the closing `</body>` tag |
+| `'beforebegin'` or `'afterend'` | Other valid positions supported by `insertAdjacentHTML` |
+
+---
+
+### Example Usage
+
+```js
+// Insert notification center template at the start of <body>
+TinyNotifyCenter.insertTemplate();
+
+// Or insert at the end of <body>
+TinyNotifyCenter.insertTemplate('beforeend');
+````
+
+---
+
+### Visual Structure Preview
+
+```html
+<div class="notify-overlay hidden">
+  <div class="notify-center" id="notifCenter">
+    <div class="header">
+      <div>Notifications</div>
+      <div class="options">
+        <button class="clear-all" type="button">✔️</button>
+        <button class="close">×</button>
+      </div>
+    </div>
+    <div class="list"></div>
+  </div>
+</div>
+
+<button class="notify-bell" aria-label="Open notifications">
+  🔔 <span class="badge" id="notifBadge">0</span>
+</button>
+```
+
+---
+
+## 🛠️ Instance Methods & Constructor
+
+### `constructor(options = {})`
+
+Creates a new instance of the Notification Center with configurable main elements.
+
+| Option          | Default Selector                         | Description                                  |
+|-----------------|----------------------------------------|----------------------------------------------|
+| `center`        | `document.getElementById('notifCenter')` | Container element holding notification list |
+| `badge`         | `document.getElementById('notifBadge')`  | Badge element showing the notification count |
+| `button`        | `document.querySelector('.notify-bell')` | Button toggling the notification center     |
+| `overlay`       | `document.querySelector('.notify-overlay')` | Overlay element shown when center is visible |
+
+⚠️ Throws an error if any of the elements are not valid HTMLElements.
+
+**Event Listeners added internally:**
+
+- `button` click → toggles notification center
+- `close` button inside center → closes notification center
+- `clear-all` button inside center → clears all notifications
+- Clicking the overlay outside center → closes notification center
+
+---
+
+### ⚙️ Configuration Methods
+
+#### `setMarkAllAsReadOnClose(value: boolean)`
+
+Enable or disable automatic marking of all notifications as read when the center closes.
+
+Throws a `TypeError` if `value` is not a boolean.
+
+---
+
+#### `setRemoveDelay(ms: number)`
+
+Set the delay (in milliseconds) for the remove animation when notifications are removed.
+
+Throws an error if `ms` is not a number.
+
+---
+
+### 📋 Notification Item Accessors
+
+#### `getItemMode(index: number) : 'text' | 'html' | null`
+
+Returns the rendering mode (`'text'` or `'html'`) of the notification at the given index, or `null` if not found.
+
+---
+
+#### `getItem(index: number) : HTMLElement`
+
+Returns the notification element at the specified index.
+
+Throws an error if the element is not an `HTMLElement`.
+
+---
+
+#### `hasItem(index: number) : boolean`
+
+Returns `true` if a notification exists at the given index, `false` otherwise.
+
+---
+
+### ✅ Notification State Management
+
+#### `markAsRead(index: number | HTMLElement)`
+
+Marks the specified notification (by index or element) as read if it was unread, updating the unread count.
+
+---
+
+#### `remove(index: number)`
+
+Removes the notification at the given index, triggering any removal animations or cleanup.
+
+---
+
+#### `clear()`
+
+Safely clears all notifications from the list, removing them one by one, handling animations properly.
+
+---
+
+### 🔔 Notification Center Visibility Controls
+
+#### `open()`
+
+Opens the notification center by showing the overlay and adding the `open` class.
+
+---
+
+#### `close()`
+
+Closes the notification center by hiding the overlay and removing the `open` class.
+
+If `markAllAsReadOnClose` is enabled, marks all unread notifications as read on close.
+
+---
+
+#### `toggle()`
+
+Toggles the notification center open or closed based on current state.
+
+---
+
+### 🔢 Count Management
+
+#### `recount()`
+
+Recalculates the number of unread notifications by counting `.item.unread` elements in the DOM list, updating the badge count.
+
+---
+
+#### `get count() : number`
+
+Returns the current number of unread notifications tracked internally.
+
+---
+
+### ➕ `add(message, mode = 'text')`
+
+Adds a new notification to the notification center. 🎉
+
+**Parameters:**
+
+* `message` (`NotifyData`):
+  Can be either a simple string or an object containing:
+
+  * `title` (optional): notification title 📝
+  * `message`: main notification text or HTML content
+  * `avatar` (optional): URL for an avatar image 🖼️
+  * `onClick` (optional): callback function triggered when the notification is clicked 🎯
+
+* `mode` (`'text' | 'html'`, default `'text'`):
+  Determines if the message content should be treated as plain text or HTML.
+
+---
+
+**How it works:**
+
+1. Creates a new `.item.unread` div to hold the notification.
+
+2. If `message` is an object, it extracts the title, message, avatar URL, and click callback.
+   Otherwise, treats `message` as plain text content.
+
+3. If an avatar URL is provided, creates a `.avatar` div with the avatar image as background.
+
+4. Creates a `.content` wrapper containing:
+
+   * An optional `.title` element if a title exists
+   * A `.message` element containing the message, rendered as text or HTML depending on `mode`
+
+5. If `onClick` callback is provided, marks the item `.clickable` and adds a click event listener that triggers the callback — but **prevents clicks on the close button** from triggering it.
+
+6. Adds a close button (`×`) `.notify-close` inside the notification:
+   Clicking it removes the notification, stopping event propagation to avoid triggering the main click callback.
+
+7. Prepends the notification to the top of the list, stores its mode, and updates the unread count.
+
+---
+
+**In short:**
+You create a rich notification element dynamically, with optional avatar, title, content (text or HTML), clickable actions, and a close button — all neatly wired up! 🚀
+
+---
+
+## 🎨 CSS Files Location
+
+The CSS files for the TinyNotify project build can be found in the following folder:
+
+```
+dist/v1/css
+```
+
+Inside this folder, you'll find the main stylesheets:
+
+- `TinyNotify.css` — the full, unminified CSS file
+- `TinyNotify.min.css` — the minified, optimized CSS file for production 🚀
+
+Use these files to style your notifications!  
+Happy coding! ✨