tiny-essentials 1.10.2 → 1.12.0

package/dist/v1/libs/TinyToastNotify.mjs

@@ -0,0 +1,352 @@
+/**
+ * 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;
+    /** @type {HTMLElement|null} */
+    #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);
+    }
+    /**
+     * 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