npm - tiny-essentials - Versions diffs - 1.10.2 → 1.11.0 - Mend

tiny-essentials 1.10.2 → 1.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (56) hide show

package/README.md +1 -1
package/dist/{TinyEssentials.js → v1/TinyEssentials.js} +804 -0
package/dist/v1/TinyEssentials.min.js +2 -0
package/dist/v1/TinyNotifyCenter.js +461 -0
package/dist/v1/TinyNotifyCenter.min.js +1 -0
package/dist/v1/TinyToastNotify.js +417 -0
package/dist/v1/TinyToastNotify.min.js +1 -0
package/dist/v1/build/TinyNotifyCenter.cjs +7 -0
package/dist/v1/build/TinyNotifyCenter.d.mts +3 -0
package/dist/v1/build/TinyNotifyCenter.mjs +2 -0
package/dist/v1/build/TinyToastNotify.cjs +7 -0
package/dist/v1/build/TinyToastNotify.d.mts +3 -0
package/dist/v1/build/TinyToastNotify.mjs +2 -0
package/dist/v1/css/TinyNotify.css +350 -0
package/dist/v1/css/TinyNotify.min.css +1 -0
package/dist/v1/index.cjs +4 -0
package/dist/v1/index.d.mts +3 -1
package/dist/v1/index.mjs +3 -1
package/dist/v1/libs/TinyNotifyCenter.cjs +422 -0
package/dist/v1/libs/TinyNotifyCenter.d.mts +166 -0
package/dist/v1/libs/TinyNotifyCenter.mjs +385 -0
package/dist/v1/libs/TinyToastNotify.cjs +378 -0
package/dist/v1/libs/TinyToastNotify.d.mts +157 -0
package/dist/v1/libs/TinyToastNotify.mjs +332 -0
package/docs/{README.md → v1/README.md} +2 -0
package/docs/{basics → v1/basics}/text.md +2 -2
package/docs/v1/libs/TinyNotifyCenter.md +291 -0
package/docs/v1/libs/TinyToastNotify.md +290 -0
package/package.json +4 -2
package/dist/TinyEssentials.min.js +0 -2
package/dist/v1/libs/TinyRateLimit.cjs +0 -196
package/dist/v1/libs/TinyRateLimit.d.mts +0 -86
package/dist/v1/libs/TinyRateLimit.mjs +0 -171
/package/dist/{ColorSafeStringify.js → v1/ColorSafeStringify.js} +0 -0
/package/dist/{ColorSafeStringify.min.js → v1/ColorSafeStringify.min.js} +0 -0
/package/dist/{TinyBasicsEs.js → v1/TinyBasicsEs.js} +0 -0
/package/dist/{TinyBasicsEs.min.js → v1/TinyBasicsEs.min.js} +0 -0
/package/dist/{TinyBasicsEs.min.js.LICENSE.txt → v1/TinyBasicsEs.min.js.LICENSE.txt} +0 -0
/package/dist/{TinyEssentials.min.js.LICENSE.txt → v1/TinyEssentials.min.js.LICENSE.txt} +0 -0
/package/dist/{TinyLevelUp.js → v1/TinyLevelUp.js} +0 -0
/package/dist/{TinyLevelUp.min.js → v1/TinyLevelUp.min.js} +0 -0
/package/dist/{TinyPromiseQueue.js → v1/TinyPromiseQueue.js} +0 -0
/package/dist/{TinyPromiseQueue.min.js → v1/TinyPromiseQueue.min.js} +0 -0
/package/dist/{TinyRateLimiter.js → v1/TinyRateLimiter.js} +0 -0
/package/dist/{TinyRateLimiter.min.js → v1/TinyRateLimiter.min.js} +0 -0
/package/dist/{aiMarker.css → v1/css/aiMarker.css} +0 -0
/package/dist/{aiMarker.min.css → v1/css/aiMarker.min.css} +0 -0
/package/docs/{basics → v1/basics}/array.md +0 -0
/package/docs/{basics → v1/basics}/asyncReplace.md +0 -0
/package/docs/{basics → v1/basics}/clock.md +0 -0
/package/docs/{basics → v1/basics}/objFilter.md +0 -0
/package/docs/{basics → v1/basics}/simpleMath.md +0 -0
/package/docs/{libs → v1/libs}/ColorSafeStringify.md +0 -0
/package/docs/{libs → v1/libs}/TinyLevelUp.md +0 -0
/package/docs/{libs → v1/libs}/TinyPromiseQueue.md +0 -0
/package/docs/{libs → v1/libs}/TinyRateLimiter.md +0 -0

package/dist/v1/libs/TinyNotifyCenter.cjs ADDED Viewed

@@ -0,0 +1,422 @@
+'use strict';
+/**
+ * Represents a single notification entry.
+ *
+ * A notification can be provided as a simple string (treated as a plain message),
+ * or as an object with additional data such as a title, an avatar image, and a click handler.
+ *
+ * @typedef {string | {
+ *   title?: string,              // Optional title displayed above the message
+ *   message: string,             // Required message content
+ *   avatar?: string,             // Optional avatar image URL (displayed on the left)
+ *   onClick?: (e: MouseEvent) => void // Optional click handler for the entire notification
+ * }} NotifyData
+ */
+/**
+ * A notification center component for displaying interactive alerts in the UI.
+ *
+ * This class renders a notification overlay on the page and allows dynamically
+ * adding, clearing, or interacting with notification items. Notifications can
+ * contain plain text or HTML, and optionally support click events, titles, and avatars.
+ *
+ * Features:
+ * - Dynamic rendering of notification UI with `insertTemplate()`
+ * - Supports text and HTML content modes
+ * - Optional avatars for each notification
+ * - Callback support on notification click
+ * - Per-notification close buttons
+ * - Notification count badge
+ *
+ * @class
+ */
+class TinyNotifyCenter {
+  /**
+   * Returns the full HTML structure for the notification system as a string.
+   *
+   * This includes:
+   * - A hidden `.notify-overlay` containing the central notification panel (`#notifCenter`),
+   *   which has a header with a "Notifications" label, a "clear all" button, and a close button.
+   * - A `.list` container for dynamically added notifications.
+   * - A bell button (`.notify-bell`) to toggle the notification center, with an embedded badge.
+   *
+   * This template can be inserted into the DOM using `insertAdjacentHTML()` or parsed dynamically
+   * into elements using JavaScript or jQuery, depending on the needs of the system.
+   *
+   * @returns {string} The complete HTML structure for the notification center.
+   */
+  static getTemplate() {
+    return `
+<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">
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            viewBox="0 0 24 24"
+            width="24"
+            height="24"
+            fill="currentColor"
+          >
+            <path
+              d="M21.6 2.4a1 1 0 0 0-1.4 0L13 9.6l-1.3-1.3a1 1 0 0 0-1.4 0L3 15.6a1 1 0 0 0 0 1.4l4 4a1 1 0 0 0 1.4 0l7.3-7.3a1 1 0 0 0 0-1.4l-1.3-1.3 7.2-7.2a1 1 0 0 0 0-1.4zM6 17l3.5-3.5 1.5 1.5L7.5 18.5 6 17z"
+            />
+          </svg>
+        </button>
+        <button class="close">×</button>
+      </div>
+    </div>
+    <div class="list"></div>
+  </div>
+</div>
+<button class="notify-bell" aria-label="Open notifications">
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="20"
+    height="20"
+    fill="currentColor"
+    viewBox="0 0 24 24"
+  >
+    <path
+      d="M12 2C10.3 2 9 3.3 9 5v1.1C6.7 7.2 5 9.4 5 12v5l-1 1v1h16v-1l-1-1v-5c0-2.6-1.7-4.8-4-5.9V5c0-1.7-1.3-3-3-3zm0 20c1.1 0 2-.9 2-2h-4c0 1.1.9 2 2 2z"
+    />
+  </svg>
+  <span class="badge" id="notifBadge">0</span>
+</button>
+    `;
+  }
+  /**
+   * Inserts the full notification center template into the document body.
+   *
+   * The structure is injected directly into the DOM using
+   * `insertAdjacentHTML`.
+   *
+   * The `where` parameter allows control over where inside the `document.body`
+   * the HTML is inserted:
+   * - `'afterbegin'` (default): Inserts right after the opening <body> tag.
+   * - `'beforeend'`: Inserts right before the closing </body> tag.
+   * - Any valid position accepted by `insertAdjacentHTML`.
+   *
+   * @param {'beforebegin'|'afterbegin'|'beforeend'|'afterend'} [where='afterbegin']
+   * The position relative to `document.body` where the HTML should be inserted.
+   */
+  static insertTemplate(where = 'afterbegin') {
+    document.body.insertAdjacentHTML(where, TinyNotifyCenter.getTemplate());
+  }
+  /** @type {HTMLElement} */
+  #center;
+  /** @type {HTMLElement} */
+  #list;
+  /** @type {HTMLElement} */
+  #badge;
+  /** @type {HTMLElement} */
+  #button;
+  /** @type {HTMLElement} */
+  #overlay;
+  #count = 0;
+  #maxCount = 99;
+  #removeDelay = 300;
+  #markAllAsReadOnClose = false;
+  #modes = new WeakMap();
+  /** @param {HTMLElement|ChildNode} item */
+  #removeItem(item) {
+    this.#modes.delete(item);
+    if (item instanceof HTMLElement) {
+      item.classList.add('removing');
+      setTimeout(() => {
+        this.markAsRead(item);
+        item.remove();
+      }, this.#removeDelay);
+    } else throw new Error('Invalid HTMLElement to clear.');
+  }
+  /**
+   * Update notify count and badge.
+   * @param {number} value
+   */
+  #updateCount(value) {
+    this.#count = Math.max(0, value);
+    this.#badge.setAttribute('data-value', String(this.#count));
+    this.#badge.textContent =
+      this.#count > this.#maxCount ? `${this.#maxCount}+` : String(this.#count);
+  }
+  /**
+   * Options for configuring the NotificationCenter instance.
+   *
+   * Allows manual specification of the main elements used by the notification center.
+   * If not provided, default elements will be selected from the DOM automatically.
+   *
+   * @param {Object} options - Configuration object.
+   * @param {HTMLElement} [options.center=document.getElementById('notifCenter')] - The container element that holds the list of notifications.
+   * @param {HTMLElement} [options.badge=document.getElementById('notifBadge')] - The badge element used to display the current notification count.
+   * @param {HTMLElement} [options.button=document.querySelector('.notify-bell')] - The button element that toggles the notification center.
+   * @param {HTMLElement} [options.overlay=document.querySelector('.notify-overlay')] - The overlay element that covers the screen when the center is visible.
+   */
+  constructor(options = {}) {
+    const {
+      center = document.getElementById('notifCenter'),
+      badge = document.getElementById('notifBadge'),
+      button = document.querySelector('.notify-bell'),
+      overlay = document.querySelector('.notify-overlay'),
+    } = options;
+    // Element existence and type validation
+    if (!(center instanceof HTMLElement))
+      throw new Error(`NotificationCenter: "center" must be an HTMLElement. Got: ${center}`);
+    if (!(overlay instanceof HTMLElement))
+      throw new Error(`NotificationCenter: "overlay" must be an HTMLElement. Got: ${overlay}`);
+    if (!(badge instanceof HTMLElement))
+      throw new Error(`NotificationCenter: "badge" must be an HTMLElement. Got: ${badge}`);
+    if (!(button instanceof HTMLElement))
+      throw new Error(`NotificationCenter: "button" must be an HTMLElement. Got: ${button}`);
+    const clearAllBtn = center?.querySelector('.clear-all');
+    const list = center?.querySelector('.list') ?? null;
+    if (!(list instanceof HTMLElement))
+      throw new Error(
+        `NotificationCenter: ".list" inside center must be an HTMLElement. Got: ${list}`,
+      );
+    this.#center = center;
+    this.#list = list;
+    this.#badge = badge;
+    this.#button = button;
+    this.#overlay = overlay;
+    this.#button.addEventListener('click', () => this.toggle());
+    this.#center.querySelector('.close')?.addEventListener('click', () => this.close());
+    if (clearAllBtn) clearAllBtn.addEventListener('click', () => this.clear());
+    this.#overlay.addEventListener('click', (e) => {
+      if (e.target === this.#overlay) this.close();
+    });
+  }
+  /**
+   * Enable or disable automatic mark-as-read on close.
+   * @param {boolean} value
+   */
+  setMarkAllAsReadOnClose(value) {
+    if (typeof value !== 'boolean')
+      throw new TypeError(`Expected boolean for markAllAsReadOnClose, got ${typeof value}`);
+    this.#markAllAsReadOnClose = value;
+  }
+  /**
+   * Define how long the remove animation takes (in ms).
+   * @param {number} ms
+   */
+  setRemoveDelay(ms) {
+    if (typeof ms !== 'number') throw new Error(`NotificationCenter: "ms" must be an number.`);
+    this.#removeDelay = ms;
+  }
+  /**
+   * Get rendering mode ('text' or 'html') by index.
+   * @param {number} index
+   * @returns {'text' | 'html' | null}
+   */
+  getItemMode(index) {
+    const item = this.getItem(index);
+    return item ? this.#modes.get(item) : null;
+  }
+  /**
+   * Get a notify element by index.
+   * @param {number} index
+   * @returns {HTMLElement}
+   */
+  getItem(index) {
+    const element = this.#list.children.item(index);
+    if (!(element instanceof HTMLElement))
+      throw new Error(`NotificationCenter: "item" must be an HTMLElement. Got: ${element}`);
+    return element;
+  }
+  /**
+   * Check if a notify exists at the given index.
+   * @param {number} index
+   * @returns {boolean}
+   */
+  hasItem(index) {
+    return index >= 0 && index < this.#list.children.length;
+  }
+  /**
+   * Mark a notification index as read.
+   * @param {number|HTMLElement} index
+   */
+  markAsRead(index) {
+    const item = index instanceof HTMLElement ? index : this.getItem(index);
+    if (item.classList.contains('unread')) {
+      item.classList.remove('unread');
+      this.#updateCount(this.#count - 1);
+    }
+  }
+  /**
+   * Add a new notify to the center.
+   *
+   * @param {NotifyData} message - Notification content or a full object with title, avatar, and callback.
+   * @param {'text'|'html'} [mode='text'] - How to treat the message content.
+   */
+  add(message, mode = 'text') {
+    const item = document.createElement('div');
+    item.className = 'item unread';
+    let titleText = null;
+    let messageText = null;
+    let avatarUrl = null;
+    let onClick = null;
+    if (typeof message === 'object' && message !== null) {
+      titleText = message.title;
+      messageText = message.message;
+      avatarUrl = message.avatar;
+      onClick = message.onClick;
+    } else {
+      messageText = message;
+    }
+    // Optional avatar
+    if (avatarUrl) {
+      const avatarElem = document.createElement('div');
+      avatarElem.className = 'avatar';
+      avatarElem.style.backgroundImage = `url("${avatarUrl}")`;
+      item.appendChild(avatarElem);
+    }
+    // Content wrapper
+    const contentWrapper = document.createElement('div');
+    contentWrapper.className = 'content';
+    // Optional title
+    if (titleText) {
+      const titleElem = document.createElement('div');
+      titleElem.className = 'title';
+      titleElem.textContent = titleText;
+      contentWrapper.appendChild(titleElem);
+    }
+    // Message
+    const messageElem = document.createElement('div');
+    messageElem.className = 'message';
+    if (mode === 'html') {
+      messageElem.innerHTML = messageText;
+    } else {
+      messageElem.textContent = messageText;
+    }
+    contentWrapper.appendChild(messageElem);
+    // Action by clicking (if provided)
+    if (typeof onClick === 'function') {
+      item.classList.add('clickable');
+      item.addEventListener('click', (e) => {
+        // Prevents the close button from clicking
+        if (e.target instanceof HTMLElement && !e.target.closest('.notify-close')) {
+          onClick(e);
+        }
+      });
+    }
+    // Close button
+    const closeBtn = document.createElement('button');
+    closeBtn.className = 'notify-close';
+    closeBtn.setAttribute('type', 'button');
+    closeBtn.innerHTML = '&times;';
+    closeBtn.addEventListener('click', (e) => {
+      e.stopPropagation(); // prevents propagation for the main onClick
+      this.#removeItem(item);
+    });
+    item.append(contentWrapper, closeBtn);
+    this.#list.prepend(item);
+    this.#modes.set(item, mode);
+    this.#updateCount(this.#count + 1);
+  }
+  /**
+   * Remove a notify by index.
+   * @param {number} index
+   */
+  remove(index) {
+    const item = this.getItem(index);
+    this.#removeItem(item);
+  }
+  /**
+   * Clear all notifications safely.
+   */
+  clear() {
+    let needAgain = true;
+    while (needAgain) {
+      needAgain = false;
+      const items = Array.from(this.#list.children);
+      for (const item of items) {
+        if (item instanceof HTMLElement && !item.classList.contains('removing')) {
+          this.#removeItem(item);
+          needAgain = true;
+        }
+      }
+    }
+  }
+  /**
+   * Open the notify center.
+   */
+  open() {
+    this.#overlay.classList.remove('hidden');
+    this.#center.classList.add('open');
+  }
+  /**
+   * Close the notify center.
+   */
+  close() {
+    this.#overlay.classList.add('hidden');
+    this.#center.classList.remove('open');
+    if (this.#markAllAsReadOnClose) {
+      const items = this.#list.querySelectorAll('.item.unread');
+      for (const item of items) {
+        if (item instanceof HTMLElement) this.markAsRead(item);
+      }
+    }
+  }
+  /**
+   * Toggle open/close state.
+   */
+  toggle() {
+    if (this.#center.classList.contains('open')) this.close();
+    else this.open();
+  }
+  /**
+   * Recalculate the number of notifications based on the actual DOM list.
+   */
+  recount() {
+    const count = this.#list.querySelectorAll('.item.unread').length;
+    this.#updateCount(count);
+  }
+  /**
+   * Get current count.
+   * @returns {number}
+   */
+  get count() {
+    return this.#count;
+  }
+}
+module.exports = TinyNotifyCenter;

package/dist/v1/libs/TinyNotifyCenter.d.mts ADDED Viewed

@@ -0,0 +1,166 @@
+export default TinyNotifyCenter;
+/**
+ * Represents a single notification entry.
+ *
+ * A notification can be provided as a simple string (treated as a plain message),
+ * or as an object with additional data such as a title, an avatar image, and a click handler.
+ */
+export type NotifyData = string | {
+    title?: string;
+    message: string;
+    avatar?: string;
+    onClick?: (e: MouseEvent) => void;
+};
+/**
+ * Represents a single notification entry.
+ *
+ * A notification can be provided as a simple string (treated as a plain message),
+ * or as an object with additional data such as a title, an avatar image, and a click handler.
+ *
+ * @typedef {string | {
+ *   title?: string,              // Optional title displayed above the message
+ *   message: string,             // Required message content
+ *   avatar?: string,             // Optional avatar image URL (displayed on the left)
+ *   onClick?: (e: MouseEvent) => void // Optional click handler for the entire notification
+ * }} NotifyData
+ */
+/**
+ * A notification center component for displaying interactive alerts in the UI.
+ *
+ * This class renders a notification overlay on the page and allows dynamically
+ * adding, clearing, or interacting with notification items. Notifications can
+ * contain plain text or HTML, and optionally support click events, titles, and avatars.
+ *
+ * Features:
+ * - Dynamic rendering of notification UI with `insertTemplate()`
+ * - Supports text and HTML content modes
+ * - Optional avatars for each notification
+ * - Callback support on notification click
+ * - Per-notification close buttons
+ * - Notification count badge
+ *
+ * @class
+ */
+declare class TinyNotifyCenter {
+    /**
+     * Returns the full HTML structure for the notification system as a string.
+     *
+     * This includes:
+     * - A hidden `.notify-overlay` containing the central notification panel (`#notifCenter`),
+     *   which has a header with a "Notifications" label, a "clear all" button, and a close button.
+     * - A `.list` container for dynamically added notifications.
+     * - A bell button (`.notify-bell`) to toggle the notification center, with an embedded badge.
+     *
+     * This template can be inserted into the DOM using `insertAdjacentHTML()` or parsed dynamically
+     * into elements using JavaScript or jQuery, depending on the needs of the system.
+     *
+     * @returns {string} The complete HTML structure for the notification center.
+     */
+    static getTemplate(): string;
+    /**
+     * Inserts the full notification center template into the document body.
+     *
+     * The structure is injected directly into the DOM using
+     * `insertAdjacentHTML`.
+     *
+     * The `where` parameter allows control over where inside the `document.body`
+     * the HTML is inserted:
+     * - `'afterbegin'` (default): Inserts right after the opening <body> tag.
+     * - `'beforeend'`: Inserts right before the closing </body> tag.
+     * - Any valid position accepted by `insertAdjacentHTML`.
+     *
+     * @param {'beforebegin'|'afterbegin'|'beforeend'|'afterend'} [where='afterbegin']
+     * The position relative to `document.body` where the HTML should be inserted.
+     */
+    static insertTemplate(where?: "beforebegin" | "afterbegin" | "beforeend" | "afterend"): void;
+    /**
+     * Options for configuring the NotificationCenter instance.
+     *
+     * Allows manual specification of the main elements used by the notification center.
+     * If not provided, default elements will be selected from the DOM automatically.
+     *
+     * @param {Object} options - Configuration object.
+     * @param {HTMLElement} [options.center=document.getElementById('notifCenter')] - The container element that holds the list of notifications.
+     * @param {HTMLElement} [options.badge=document.getElementById('notifBadge')] - The badge element used to display the current notification count.
+     * @param {HTMLElement} [options.button=document.querySelector('.notify-bell')] - The button element that toggles the notification center.
+     * @param {HTMLElement} [options.overlay=document.querySelector('.notify-overlay')] - The overlay element that covers the screen when the center is visible.
+     */
+    constructor(options?: {
+        center?: HTMLElement | undefined;
+        badge?: HTMLElement | undefined;
+        button?: HTMLElement | undefined;
+        overlay?: HTMLElement | undefined;
+    });
+    /**
+     * Enable or disable automatic mark-as-read on close.
+     * @param {boolean} value
+     */
+    setMarkAllAsReadOnClose(value: boolean): void;
+    /**
+     * Define how long the remove animation takes (in ms).
+     * @param {number} ms
+     */
+    setRemoveDelay(ms: number): void;
+    /**
+     * Get rendering mode ('text' or 'html') by index.
+     * @param {number} index
+     * @returns {'text' | 'html' | null}
+     */
+    getItemMode(index: number): "text" | "html" | null;
+    /**
+     * Get a notify element by index.
+     * @param {number} index
+     * @returns {HTMLElement}
+     */
+    getItem(index: number): HTMLElement;
+    /**
+     * Check if a notify exists at the given index.
+     * @param {number} index
+     * @returns {boolean}
+     */
+    hasItem(index: number): boolean;
+    /**
+     * Mark a notification index as read.
+     * @param {number|HTMLElement} index
+     */
+    markAsRead(index: number | HTMLElement): void;
+    /**
+     * Add a new notify to the center.
+     *
+     * @param {NotifyData} message - Notification content or a full object with title, avatar, and callback.
+     * @param {'text'|'html'} [mode='text'] - How to treat the message content.
+     */
+    add(message: NotifyData, mode?: "text" | "html"): void;
+    /**
+     * Remove a notify by index.
+     * @param {number} index
+     */
+    remove(index: number): void;
+    /**
+     * Clear all notifications safely.
+     */
+    clear(): void;
+    /**
+     * Open the notify center.
+     */
+    open(): void;
+    /**
+     * Close the notify center.
+     */
+    close(): void;
+    /**
+     * Toggle open/close state.
+     */
+    toggle(): void;
+    /**
+     * Recalculate the number of notifications based on the actual DOM list.
+     */
+    recount(): void;
+    /**
+     * Get current count.
+     * @returns {number}
+     */
+    get count(): number;
+    #private;
+}
+//# sourceMappingURL=TinyNotifyCenter.d.mts.map