tiny-essentials 1.11.0 → 1.12.0

package/dist/v1/libs/TinyNotifyCenter.cjs

@@ -417,6 +417,38 @@ class TinyNotifyCenter {
   get count() {
     return this.#count;
   }
+
+  /**
+   * Destroys the notification center instance, removing all event listeners,
+   * clearing notifications, and optionally removing DOM elements.
+   *
+   * Call this when the notification center is no longer needed to prevent memory leaks.
+   *
+   * @returns {void}
+   */
+  destroy() {
+    // Remove event listeners
+    this.#button?.removeEventListener('click', this.toggle);
+    this.#center?.querySelector('.close')?.removeEventListener('click', this.close);
+    this.#center?.querySelector('.clear-all')?.removeEventListener('click', this.clear);
+    this.#overlay?.removeEventListener('click', this.close);
+
+    // Clear all notifications
+    this.clear();
+
+    this.#center?.remove();
+    this.#overlay?.remove();
+    this.#button?.remove();
+
+    // Clean internal references
+    // this.#center = null;
+    // this.#list = null;
+    // this.#badge = null;
+    // this.#button = null;
+    // this.#overlay = null;
+    this.#count = 0;
+    this.#modes = new WeakMap();
+  }
 }
 
 module.exports = TinyNotifyCenter;

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

@@ -161,6 +161,15 @@ declare class TinyNotifyCenter {
      * @returns {number}
      */
     get count(): number;
+    /**
+     * Destroys the notification center instance, removing all event listeners,
+     * clearing notifications, and optionally removing DOM elements.
+     *
+     * Call this when the notification center is no longer needed to prevent memory leaks.
+     *
+     * @returns {void}
+     */
+    destroy(): void;
     #private;
 }
 //# sourceMappingURL=TinyNotifyCenter.d.mts.map

package/dist/v1/libs/TinyNotifyCenter.mjs

@@ -381,5 +381,33 @@ class TinyNotifyCenter {
     get count() {
         return this.#count;
     }
+    /**
+     * Destroys the notification center instance, removing all event listeners,
+     * clearing notifications, and optionally removing DOM elements.
+     *
+     * Call this when the notification center is no longer needed to prevent memory leaks.
+     *
+     * @returns {void}
+     */
+    destroy() {
+        // Remove event listeners
+        this.#button?.removeEventListener('click', this.toggle);
+        this.#center?.querySelector('.close')?.removeEventListener('click', this.close);
+        this.#center?.querySelector('.clear-all')?.removeEventListener('click', this.clear);
+        this.#overlay?.removeEventListener('click', this.close);
+        // Clear all notifications
+        this.clear();
+        this.#center?.remove();
+        this.#overlay?.remove();
+        this.#button?.remove();
+        // Clean internal references
+        // this.#center = null;
+        // this.#list = null;
+        // this.#badge = null;
+        // this.#button = null;
+        // this.#overlay = null;
+        this.#count = 0;
+        this.#modes = new WeakMap();
+    }
 }
 export default TinyNotifyCenter;

package/dist/v1/libs/TinyToastNotify.cjs

@@ -46,6 +46,8 @@ class TinyToastNotify {
   #baseDuration;
   #extraPerChar;
   #fadeOutDuration;
+
+  /** @type {HTMLElement|null} */
   #container;
 
   /**
@@ -373,6 +375,28 @@ class TinyToastNotify {
 
     setTimeout(() => close(), totalTime);
   }
+
+  /**
+   * 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() {
+    if (!(this.#container instanceof HTMLElement)) return;
+
+    // Remove all child notifications
+    this.#container.querySelectorAll('.notify').forEach((el) => el.remove());
+
+    // Remove the container itself from the DOM
+    if (this.#container.parentNode) {
+      this.#container.parentNode.removeChild(this.#container);
+    }
+
+    // Optional: Clean internal references (safe practice)
+    this.#container = null;
+  }
 }
 
 module.exports = TinyToastNotify;

package/dist/v1/libs/TinyToastNotify.d.mts

@@ -152,6 +152,14 @@ declare class TinyToastNotify {
      * @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

package/dist/v1/libs/TinyToastNotify.mjs

@@ -42,6 +42,7 @@ class TinyToastNotify {
     #baseDuration;
     #extraPerChar;
     #fadeOutDuration;
+    /** @type {HTMLElement|null} */
     #container;
     /**
      * @param {'top'|'bottom'} y - 'top' or 'bottom'
@@ -328,5 +329,24 @@ class TinyToastNotify {
         }, 1);
         setTimeout(() => close(), totalTime);
     }
+    /**
+     * 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() {
+        if (!(this.#container instanceof HTMLElement))
+            return;
+        // Remove all child notifications
+        this.#container.querySelectorAll('.notify').forEach((el) => el.remove());
+        // Remove the container itself from the DOM
+        if (this.#container.parentNode) {
+            this.#container.parentNode.removeChild(this.#container);
+        }
+        // Optional: Clean internal references (safe practice)
+        this.#container = null;
+    }
 }
 export default TinyToastNotify;

package/dist/v1/libs/TinyUploadClicker.cjs

@@ -0,0 +1,223 @@
+'use strict';
+
+var objFilter = require('../basics/objFilter.cjs');
+require('fs');
+require('path');
+
+/**
+ * @typedef {Object} UploaderConfig
+ *
+ * @property {string | HTMLElement | Array<string | HTMLElement>} triggers -
+ *    Single or multiple elements (or selectors) that will act as upload triggers.
+ *
+ * @property {boolean} [multiple=false] -
+ *    Whether to allow selection of multiple files.
+ *
+ * @property {string|string[]} [accept=""] -
+ *    A comma-separated list of accepted file types (e.g., ".png,.jpg" or "image/*").
+ *
+ * @property {Record<string, string>} [inputAttributes={}] -
+ *    Additional attributes to apply to the created `<input type="file">`.
+ *
+ * @property {Partial<CSSStyleDeclaration>} [inputStyles={ display: 'none' }] -
+ *    Inline CSS styles to apply to the hidden input. Default hides the element.
+ *
+ * @property {((triggerElement: HTMLElement) => void)|null} [onClick=null] -
+ *    Callback executed when a trigger is clicked (before the file dialog opens).
+ *
+ * @property {((files: FileList, triggerElement: HTMLElement) => void)|null} [onFileLoad=null] -
+ *    Callback executed when files are selected through the file input.
+ */
+
+
+/**
+ * TinyUploadClicker is a lightweight utility class for attaching custom clickable elements
+ * (like buttons, divs, icons, etc.) that trigger hidden file input elements.
+ *
+ * It provides full control over the input file element without needing to display it,
+ * and allows per-trigger customization, style injection, and event handling.
+ *
+ * Each trigger element creates its own associated hidden file input, enabling multiple
+ * upload zones with different behaviors. You can handle `onClick` and `onFileLoad` callbacks,
+ * define accepted file types, allow multiple selections, and cleanly destroy everything via `destroy()`.
+ *
+ * Designed for maximum flexibility in pure JavaScript environments, including dynamic UI rendering.
+ *
+ * @example
+ * const uploader = new TinyUploadClicker({
+ *   triggers: '#uploadBtn',
+ *   accept: ['.png', '.jpg'],
+ *   multiple: true,
+ *   inputAttributes: { 'data-tracker': 'upload' },
+ *   inputStyles: { display: 'none' },
+ *   onClick: (el) => console.log('Trigger clicked:', el),
+ *   onFileLoad: (files, el) => console.log('Files selected:', files)
+ * });
+ *
+ * // Later, if needed:
+ * uploader.destroy();
+ */
+class TinyUploadClicker {
+  /** @type {UploaderConfig} */
+  #config;
+
+  /** @type {Array<HTMLElement|Element|null>} */
+  #triggerElements = [];
+
+  /** @type {WeakMap<HTMLElement, HTMLInputElement>} */
+  #inputs = new WeakMap();
+
+  /** @type {(ev: MouseEvent) => void} */
+  #boundClick;
+
+  /**
+   * Creates a new instance of TinyUploadClicker.
+   *
+   * @param {UploaderConfig} options - Configuration object for customizing the uploader behavior and appearance.
+   * @throws {TypeError} If the config is invalid or required options are missing.
+   */
+  constructor(options) {
+    if (!objFilter.isJsonObject(options))
+      throw new TypeError('TinyUploadClicker: "options" must be a valid object.');
+
+    this.#config = {
+      multiple: false,
+      accept: '',
+      inputAttributes: {},
+      inputStyles: { display: 'none' },
+      onClick: null,
+      onFileLoad: null,
+      ...options,
+    };
+
+    const { triggers } = options;
+
+    if (
+      !Array.isArray(triggers) &&
+      typeof triggers !== 'string' &&
+      !(triggers instanceof HTMLElement)
+    )
+      throw new TypeError(
+        'TinyUploadClicker: "triggers" is required and must be a string, HTMLElement, or an array of them.',
+      );
+
+    const triggerList = Array.isArray(this.#config.triggers)
+      ? this.#config.triggers
+      : [this.#config.triggers];
+
+    const resolvedTriggers = triggerList.map((ref) => {
+      if (typeof ref === 'string') {
+        const el = document.querySelector(ref);
+        if (!el) {
+          throw new Error(`TinyUploadClicker: No element found for selector "${ref}".`);
+        }
+        return el;
+      }
+
+      if (!(ref instanceof HTMLElement))
+        throw new TypeError(
+          'TinyUploadClicker: All triggers must be either strings (selectors) or HTMLElements.',
+        );
+      return ref;
+    });
+
+    // Validate optional values
+    if (
+      options.accept !== undefined &&
+      typeof options.accept !== 'string' &&
+      !Array.isArray(options.accept)
+    )
+      throw new TypeError('TinyUploadClicker: "accept" must be a string or an array of strings.');
+
+    if (
+      options.onClick !== undefined &&
+      typeof options.onClick !== 'function' &&
+      options.onClick !== null
+    )
+      throw new TypeError('TinyUploadClicker: "onClick" must be a function or null.');
+
+    if (
+      options.onFileLoad !== undefined &&
+      typeof options.onFileLoad !== 'function' &&
+      options.onFileLoad !== null
+    )
+      throw new TypeError('TinyUploadClicker: "onFileLoad" must be a function or null.');
+
+    if (options.inputAttributes !== undefined && !objFilter.isJsonObject(options.inputAttributes))
+      throw new TypeError('TinyUploadClicker: "inputAttributes" must be an object.');
+
+    if (options.inputStyles !== undefined && !objFilter.isJsonObject(options.inputStyles))
+      throw new TypeError('TinyUploadClicker: "inputStyles" must be an object.');
+
+    this.#boundClick = this.#handleClick.bind(this);
+    this.#triggerElements = resolvedTriggers;
+
+    this.#triggerElements.forEach((trigger) => {
+      if (!(trigger instanceof HTMLElement)) return;
+      const input = document.createElement('input');
+      input.type = 'file';
+      if (this.#config.multiple) input.multiple = true;
+      if (typeof this.#config.accept === 'string') input.accept = this.#config.accept;
+      else if (Array.isArray(this.#config.accept)) input.accept = this.#config.accept.join(',');
+
+      // Apply attributes
+      const attr = this.#config.inputAttributes;
+      if (attr && typeof attr === 'object') {
+        for (const [key, value] of Object.entries(attr)) {
+          input.setAttribute(key, value);
+        }
+      }
+
+      // Apply styles
+      Object.assign(input.style, this.#config.inputStyles || { display: 'none' });
+
+      // Listen for file changes
+      input.addEventListener('change', () => {
+        if (input.files && typeof this.#config.onFileLoad === 'function')
+          this.#config.onFileLoad(input.files, trigger);
+
+        input.value = ''; // reset so same file can be reselected
+      });
+
+      document.body.appendChild(input);
+      this.#inputs.set(trigger, input);
+
+      trigger.addEventListener('click', this.#boundClick);
+    });
+  }
+
+  /**
+   * Handles the click on a trigger element and forwards it to the associated file input.
+   *
+   * @param {MouseEvent} event - The click event object.
+   */
+  #handleClick(event) {
+    const trigger = event.currentTarget;
+    if (!(trigger instanceof HTMLElement)) return;
+    const input = this.#inputs.get(trigger);
+    if (!input) return;
+
+    if (typeof this.#config.onClick === 'function') this.#config.onClick(trigger);
+
+    input.click();
+  }
+
+  /**
+   * Cleans up all internal elements and event listeners, removing created inputs and breaking references.
+   */
+  destroy() {
+    for (const trigger of this.#triggerElements) {
+      if (!(trigger instanceof HTMLElement)) return;
+      trigger.removeEventListener('click', this.#boundClick);
+
+      const input = this.#inputs.get(trigger);
+      if (input && input.parentNode) input.remove();
+
+      this.#inputs.delete(trigger);
+    }
+
+    this.#triggerElements = [];
+  }
+}
+
+module.exports = TinyUploadClicker;

package/dist/v1/libs/TinyUploadClicker.d.mts

@@ -0,0 +1,80 @@
+export default TinyUploadClicker;
+export type UploaderConfig = {
+    /**
+     * -
+     * Single or multiple elements (or selectors) that will act as upload triggers.
+     */
+    triggers: string | HTMLElement | Array<string | HTMLElement>;
+    /**
+     * -
+     * Whether to allow selection of multiple files.
+     */
+    multiple?: boolean | undefined;
+    /**
+     * -
+     * A comma-separated list of accepted file types (e.g., ".png,.jpg" or "image/*").
+     */
+    accept?: string | string[] | undefined;
+    /**
+     * -
+     * Additional attributes to apply to the created `<input type="file">`.
+     */
+    inputAttributes?: Record<string, string> | undefined;
+    /**
+     * -
+     * Inline CSS styles to apply to the hidden input. Default hides the element.
+     */
+    inputStyles?: Partial<CSSStyleDeclaration> | undefined;
+    /**
+     * -
+     * Callback executed when a trigger is clicked (before the file dialog opens).
+     */
+    onClick?: ((triggerElement: HTMLElement) => void) | null | undefined;
+    /**
+     * -
+     * Callback executed when files are selected through the file input.
+     */
+    onFileLoad?: ((files: FileList, triggerElement: HTMLElement) => void) | null | undefined;
+};
+/**
+ * TinyUploadClicker is a lightweight utility class for attaching custom clickable elements
+ * (like buttons, divs, icons, etc.) that trigger hidden file input elements.
+ *
+ * It provides full control over the input file element without needing to display it,
+ * and allows per-trigger customization, style injection, and event handling.
+ *
+ * Each trigger element creates its own associated hidden file input, enabling multiple
+ * upload zones with different behaviors. You can handle `onClick` and `onFileLoad` callbacks,
+ * define accepted file types, allow multiple selections, and cleanly destroy everything via `destroy()`.
+ *
+ * Designed for maximum flexibility in pure JavaScript environments, including dynamic UI rendering.
+ *
+ * @example
+ * const uploader = new TinyUploadClicker({
+ *   triggers: '#uploadBtn',
+ *   accept: ['.png', '.jpg'],
+ *   multiple: true,
+ *   inputAttributes: { 'data-tracker': 'upload' },
+ *   inputStyles: { display: 'none' },
+ *   onClick: (el) => console.log('Trigger clicked:', el),
+ *   onFileLoad: (files, el) => console.log('Files selected:', files)
+ * });
+ *
+ * // Later, if needed:
+ * uploader.destroy();
+ */
+declare class TinyUploadClicker {
+    /**
+     * Creates a new instance of TinyUploadClicker.
+     *
+     * @param {UploaderConfig} options - Configuration object for customizing the uploader behavior and appearance.
+     * @throws {TypeError} If the config is invalid or required options are missing.
+     */
+    constructor(options: UploaderConfig);
+    /**
+     * Cleans up all internal elements and event listeners, removing created inputs and breaking references.
+     */
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=TinyUploadClicker.d.mts.map

package/dist/v1/libs/TinyUploadClicker.mjs

@@ -0,0 +1,182 @@
+/**
+ * @typedef {Object} UploaderConfig
+ *
+ * @property {string | HTMLElement | Array<string | HTMLElement>} triggers -
+ *    Single or multiple elements (or selectors) that will act as upload triggers.
+ *
+ * @property {boolean} [multiple=false] -
+ *    Whether to allow selection of multiple files.
+ *
+ * @property {string|string[]} [accept=""] -
+ *    A comma-separated list of accepted file types (e.g., ".png,.jpg" or "image/*").
+ *
+ * @property {Record<string, string>} [inputAttributes={}] -
+ *    Additional attributes to apply to the created `<input type="file">`.
+ *
+ * @property {Partial<CSSStyleDeclaration>} [inputStyles={ display: 'none' }] -
+ *    Inline CSS styles to apply to the hidden input. Default hides the element.
+ *
+ * @property {((triggerElement: HTMLElement) => void)|null} [onClick=null] -
+ *    Callback executed when a trigger is clicked (before the file dialog opens).
+ *
+ * @property {((files: FileList, triggerElement: HTMLElement) => void)|null} [onFileLoad=null] -
+ *    Callback executed when files are selected through the file input.
+ */
+import { isJsonObject } from '../index.mjs';
+/**
+ * TinyUploadClicker is a lightweight utility class for attaching custom clickable elements
+ * (like buttons, divs, icons, etc.) that trigger hidden file input elements.
+ *
+ * It provides full control over the input file element without needing to display it,
+ * and allows per-trigger customization, style injection, and event handling.
+ *
+ * Each trigger element creates its own associated hidden file input, enabling multiple
+ * upload zones with different behaviors. You can handle `onClick` and `onFileLoad` callbacks,
+ * define accepted file types, allow multiple selections, and cleanly destroy everything via `destroy()`.
+ *
+ * Designed for maximum flexibility in pure JavaScript environments, including dynamic UI rendering.
+ *
+ * @example
+ * const uploader = new TinyUploadClicker({
+ *   triggers: '#uploadBtn',
+ *   accept: ['.png', '.jpg'],
+ *   multiple: true,
+ *   inputAttributes: { 'data-tracker': 'upload' },
+ *   inputStyles: { display: 'none' },
+ *   onClick: (el) => console.log('Trigger clicked:', el),
+ *   onFileLoad: (files, el) => console.log('Files selected:', files)
+ * });
+ *
+ * // Later, if needed:
+ * uploader.destroy();
+ */
+class TinyUploadClicker {
+    /** @type {UploaderConfig} */
+    #config;
+    /** @type {Array<HTMLElement|Element|null>} */
+    #triggerElements = [];
+    /** @type {WeakMap<HTMLElement, HTMLInputElement>} */
+    #inputs = new WeakMap();
+    /** @type {(ev: MouseEvent) => void} */
+    #boundClick;
+    /**
+     * Creates a new instance of TinyUploadClicker.
+     *
+     * @param {UploaderConfig} options - Configuration object for customizing the uploader behavior and appearance.
+     * @throws {TypeError} If the config is invalid or required options are missing.
+     */
+    constructor(options) {
+        if (!isJsonObject(options))
+            throw new TypeError('TinyUploadClicker: "options" must be a valid object.');
+        this.#config = {
+            multiple: false,
+            accept: '',
+            inputAttributes: {},
+            inputStyles: { display: 'none' },
+            onClick: null,
+            onFileLoad: null,
+            ...options,
+        };
+        const { triggers } = options;
+        if (!Array.isArray(triggers) &&
+            typeof triggers !== 'string' &&
+            !(triggers instanceof HTMLElement))
+            throw new TypeError('TinyUploadClicker: "triggers" is required and must be a string, HTMLElement, or an array of them.');
+        const triggerList = Array.isArray(this.#config.triggers)
+            ? this.#config.triggers
+            : [this.#config.triggers];
+        const resolvedTriggers = triggerList.map((ref) => {
+            if (typeof ref === 'string') {
+                const el = document.querySelector(ref);
+                if (!el) {
+                    throw new Error(`TinyUploadClicker: No element found for selector "${ref}".`);
+                }
+                return el;
+            }
+            if (!(ref instanceof HTMLElement))
+                throw new TypeError('TinyUploadClicker: All triggers must be either strings (selectors) or HTMLElements.');
+            return ref;
+        });
+        // Validate optional values
+        if (options.accept !== undefined &&
+            typeof options.accept !== 'string' &&
+            !Array.isArray(options.accept))
+            throw new TypeError('TinyUploadClicker: "accept" must be a string or an array of strings.');
+        if (options.onClick !== undefined &&
+            typeof options.onClick !== 'function' &&
+            options.onClick !== null)
+            throw new TypeError('TinyUploadClicker: "onClick" must be a function or null.');
+        if (options.onFileLoad !== undefined &&
+            typeof options.onFileLoad !== 'function' &&
+            options.onFileLoad !== null)
+            throw new TypeError('TinyUploadClicker: "onFileLoad" must be a function or null.');
+        if (options.inputAttributes !== undefined && !isJsonObject(options.inputAttributes))
+            throw new TypeError('TinyUploadClicker: "inputAttributes" must be an object.');
+        if (options.inputStyles !== undefined && !isJsonObject(options.inputStyles))
+            throw new TypeError('TinyUploadClicker: "inputStyles" must be an object.');
+        this.#boundClick = this.#handleClick.bind(this);
+        this.#triggerElements = resolvedTriggers;
+        this.#triggerElements.forEach((trigger) => {
+            if (!(trigger instanceof HTMLElement))
+                return;
+            const input = document.createElement('input');
+            input.type = 'file';
+            if (this.#config.multiple)
+                input.multiple = true;
+            if (typeof this.#config.accept === 'string')
+                input.accept = this.#config.accept;
+            else if (Array.isArray(this.#config.accept))
+                input.accept = this.#config.accept.join(',');
+            // Apply attributes
+            const attr = this.#config.inputAttributes;
+            if (attr && typeof attr === 'object') {
+                for (const [key, value] of Object.entries(attr)) {
+                    input.setAttribute(key, value);
+                }
+            }
+            // Apply styles
+            Object.assign(input.style, this.#config.inputStyles || { display: 'none' });
+            // Listen for file changes
+            input.addEventListener('change', () => {
+                if (input.files && typeof this.#config.onFileLoad === 'function')
+                    this.#config.onFileLoad(input.files, trigger);
+                input.value = ''; // reset so same file can be reselected
+            });
+            document.body.appendChild(input);
+            this.#inputs.set(trigger, input);
+            trigger.addEventListener('click', this.#boundClick);
+        });
+    }
+    /**
+     * Handles the click on a trigger element and forwards it to the associated file input.
+     *
+     * @param {MouseEvent} event - The click event object.
+     */
+    #handleClick(event) {
+        const trigger = event.currentTarget;
+        if (!(trigger instanceof HTMLElement))
+            return;
+        const input = this.#inputs.get(trigger);
+        if (!input)
+            return;
+        if (typeof this.#config.onClick === 'function')
+            this.#config.onClick(trigger);
+        input.click();
+    }
+    /**
+     * Cleans up all internal elements and event listeners, removing created inputs and breaking references.
+     */
+    destroy() {
+        for (const trigger of this.#triggerElements) {
+            if (!(trigger instanceof HTMLElement))
+                return;
+            trigger.removeEventListener('click', this.#boundClick);
+            const input = this.#inputs.get(trigger);
+            if (input && input.parentNode)
+                input.remove();
+            this.#inputs.delete(trigger);
+        }
+        this.#triggerElements = [];
+    }
+}
+export default TinyUploadClicker;