tiny-essentials 1.20.3 → 1.21.1

package/dist/v1/libs/TinyNeedBar.mjs

@@ -0,0 +1,241 @@
+/**
+ * @typedef {Object} TickResult
+ * @property {number} prevValue - Infinite value before applying decay.
+ * @property {number} removedTotal - Total amount removed this tick.
+ * @property {number} removedPercent - Percentage of max removed this tick.
+ * @property {number} currentPercent - Current percentage relative to max.
+ * @property {number} remainingValue - Current clamped value (≥ 0).
+ * @property {number} infiniteRemaining - Current infinite value (can be negative).
+ */
+/**
+ * Represents a decay factor applied to the need bar.
+ *
+ * - `amount`: base value reduced per tick.
+ * - `multiplier`: multiplier applied to the amount.
+ *
+ * @typedef {Object} BarFactor
+ * @property {number} amount - Base reduction value per tick.
+ * @property {number} multiplier - Multiplier applied to the amount.
+ */
+/**
+ * Represents the serialized state of a TinyNeedBar instance.
+ *
+ * This object is typically produced by {@link TinyNeedBar#toJSON} and
+ * can be used to recreate an instance via {@link TinyNeedBar.fromJSON}.
+ *
+ * @typedef {Object} SerializedData
+ * @property {number} maxValue - Maximum value of the bar at the moment of serialization.
+ * @property {number} currentValue - Current clamped value (never below 0).
+ * @property {number} infiniteValue - Infinite value (can go negative).
+ * @property {Record<string, BarFactor>} factors - Active decay factors indexed by their keys.
+ */
+/**
+ * A utility class to simulate a "need bar" system.
+ *
+ * The bar decreases over time according to defined factors (each with an amount and multiplier).
+ * - The **main factor** controls the base decay per tick.
+ * - Additional factors can be added dynamically.
+ *
+ * The system tracks two values:
+ * - `currentValue` → cannot go below zero.
+ * - `infiniteValue` → can decrease infinitely into negative numbers.
+ */
+class TinyNeedBar {
+    /**
+     * Stores all factors that influence decay.
+     * Each entry contains an amount and a multiplier.
+     * @type {Map<string, BarFactor>}
+     */
+    #factors = new Map();
+    /** Maximum value of the bar. @type {number} */
+    #maxValue;
+    /** Current clamped value of the bar (never below 0). @type {number} */
+    #currentValue;
+    /** Current "infinite" value of the bar (can go negative). @type {number} */
+    #infiniteValue;
+    /**
+     * Returns a snapshot of all currently active factors.
+     * Each factor is returned as a plain object to prevent direct mutation of the internal map.
+     *
+     * @returns {Record<string, BarFactor>} A record of all factors indexed by their key.
+     */
+    get factors() {
+        /** @type {Record<string, BarFactor>} */
+        const factors = {};
+        for (let [name, factor] of this.#factors.entries()) {
+            factors[name] = { ...factor };
+        }
+        return factors;
+    }
+    /**
+     * Returns the current percentage of the bar relative to the maximum value.
+     *
+     * @returns {number} Percentage from `0` to `100`.
+     */
+    get currentPercent() {
+        return (this.#currentValue / this.#maxValue) * 100;
+    }
+    /**
+     * Updates the maximum possible value of the bar.
+     * Ensures `currentValue` never exceeds the new maximum.
+     *
+     * @param {number} value - New maximum value.
+     */
+    set maxValue(value) {
+        this.#maxValue = value;
+        this.#currentValue = Math.min(this.#currentValue, value);
+    }
+    /**
+     * Returns the maximum possible value of the bar.
+     *
+     * @returns {number} The maximum value.
+     */
+    get maxValue() {
+        return this.#maxValue;
+    }
+    /**
+     * Returns the current clamped value of the bar.
+     * This value will never be below `0`.
+     *
+     * @returns {number} Current value (≥ 0).
+     */
+    get currentValue() {
+        return this.#currentValue;
+    }
+    /**
+     * Updates the infinite value of the bar.
+     * Automatically recalculates the `currentValue` (never below 0).
+     *
+     * @param {number} value - New infinite value.
+     */
+    set infiniteValue(value) {
+        this.#infiniteValue = value;
+        this.#currentValue = Math.max(0, value);
+        this.#currentValue = Math.min(this.#currentValue, this.#maxValue);
+    }
+    /**
+     * Returns the current infinite value of the bar.
+     * Unlike `currentValue`, this one can go below zero.
+     *
+     * @returns {number} Current infinite value.
+     */
+    get infiniteValue() {
+        return this.#infiniteValue;
+    }
+    /**
+     * Creates a new need bar instance.
+     *
+     * @param {number} [maxValue=100] - Maximum value of the bar.
+     * @param {number} [baseDecay=1] - Base amount reduced each tick.
+     * @param {number} [baseDecayMulti=1] - Multiplier applied to the base decay.
+     */
+    constructor(maxValue = 100, baseDecay = 1, baseDecayMulti = 1) {
+        this.#maxValue = maxValue;
+        this.setFactor('main', baseDecay, baseDecayMulti);
+        this.#currentValue = maxValue;
+        this.#infiniteValue = maxValue;
+    }
+    /**
+     * Retrieves a specific factor by its key.
+     *
+     * @param {string} key - The unique key of the factor.
+     * @returns {BarFactor} The requested factor object.
+     * @throws {Error} If the factor does not exist.
+     */
+    getFactor(key) {
+        const result = this.#factors.get(key);
+        if (!result)
+            throw new Error(`Factor with key "${key}" not found.`);
+        return { ...result };
+    }
+    /**
+     * Checks if a specific factor exists by key.
+     *
+     * @param {string} key - The factor key to check.
+     * @returns {boolean} `true` if the factor exists, otherwise `false`.
+     */
+    hasFactor(key) {
+        return this.#factors.has(key);
+    }
+    /**
+     * Defines or updates a decay factor.
+     *
+     * @param {string} key - Unique identifier for the factor.
+     * @param {number} amount - Amount reduced per tick.
+     * @param {number} [multiplier=1] - Multiplier applied to the amount.
+     */
+    setFactor(key, amount, multiplier = 1) {
+        this.#factors.set(key, { amount, multiplier });
+    }
+    /**
+     * Removes a decay factor by its key.
+     *
+     * @param {string} key - The factor key to remove.
+     */
+    removeFactor(key) {
+        this.#factors.delete(key);
+    }
+    /**
+     * Executes one tick of decay, applying all active factors.
+     *
+     * @returns {TickResult}
+     */
+    tick() {
+        let removedTotal = 0;
+        for (let [_, factor] of this.#factors.entries()) {
+            removedTotal += factor.amount * factor.multiplier;
+        }
+        const prevValue = this.#infiniteValue;
+        this.#infiniteValue -= removedTotal;
+        this.#currentValue = Math.max(0, this.#currentValue - removedTotal);
+        const removedPercent = (removedTotal / this.#maxValue) * 100;
+        return {
+            prevValue,
+            removedTotal,
+            removedPercent,
+            currentPercent: this.currentPercent,
+            remainingValue: this.#currentValue,
+            infiniteRemaining: this.#infiniteValue,
+        };
+    }
+    /**
+     * Serializes the current state of the need bar.
+     * @returns {SerializedData}
+     */
+    toJSON() {
+        return {
+            maxValue: this.#maxValue,
+            currentValue: this.#currentValue,
+            infiniteValue: this.#infiniteValue,
+            factors: this.factors,
+        };
+    }
+    /**
+     * Restores a need bar from a serialized object.
+     * @param {SerializedData} data
+     * @returns {TinyNeedBar}
+     */
+    static fromJSON(data) {
+        const bar = new TinyNeedBar(data.maxValue, 0, 0);
+        bar.infiniteValue = data.infiniteValue;
+        bar.#factors.clear();
+        for (const [key, factor] of Object.entries(data.factors)) {
+            bar.setFactor(key, factor.amount, factor.multiplier);
+        }
+        return bar;
+    }
+    /**
+     * Creates a deep clone of this need bar.
+     * @returns {TinyNeedBar}
+     */
+    clone() {
+        return TinyNeedBar.fromJSON(this.toJSON());
+    }
+    /**
+     * Clear the factors map, clearing all factor data.
+     */
+    clearFactors() {
+        this.#factors.clear();
+    }
+}
+export default TinyNeedBar;

package/dist/v1/libs/TinyRateLimiter.cjs

@@ -327,19 +327,6 @@ class TinyRateLimiter {
     this.groupTTL.delete(groupId);
   }
 
-  /**
-   * Manually reset user data.
-   *
-   * @deprecated Use `resetUserGroup(userId)` instead. This method will be removed in future versions.
-   * @param {string} userId
-   * @returns {void}
-   */
-  reset(userId) {
-    if (process?.env?.NODE_ENV !== 'production')
-      console.warn(`[TinyRateLimiter] 'reset()' is deprecated. Use 'resetUserGroup()' instead.`);
-    return this.resetUserGroup(userId);
-  }
-
   /**
    * Manually reset a user mapping
    * @param {string} userId

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

@@ -119,14 +119,6 @@ declare class TinyRateLimiter {
      * @param {string} groupId
      */
     resetGroup(groupId: string): void;
-    /**
-     * Manually reset user data.
-     *
-     * @deprecated Use `resetUserGroup(userId)` instead. This method will be removed in future versions.
-     * @param {string} userId
-     * @returns {void}
-     */
-    reset(userId: string): void;
     /**
      * Manually reset a user mapping
      * @param {string} userId

package/dist/v1/libs/TinyRateLimiter.mjs

@@ -293,18 +293,6 @@ class TinyRateLimiter {
         this.lastSeen.delete(groupId);
         this.groupTTL.delete(groupId);
     }
-    /**
-     * Manually reset user data.
-     *
-     * @deprecated Use `resetUserGroup(userId)` instead. This method will be removed in future versions.
-     * @param {string} userId
-     * @returns {void}
-     */
-    reset(userId) {
-        if (process?.env?.NODE_ENV !== 'production')
-            console.warn(`[TinyRateLimiter] 'reset()' is deprecated. Use 'resetUserGroup()' instead.`);
-        return this.resetUserGroup(userId);
-    }
     /**
      * Manually reset a user mapping
      * @param {string} userId

package/dist/v1/libs/TinySmartScroller.cjs

@@ -601,17 +601,6 @@ class TinySmartScroller {
     return results;
   }
 
-  /**
-   * Emits a scroll-related event to all registered listeners.
-   *
-   * @param {string} event - Event name.
-   * @param {*} [payload] - Optional event data payload.
-   * @deprecated - Use emit() instead.
-   */
-  _emit(event, payload) {
-    this.emit(event, payload);
-  }
-
   /**
    * Handles scroll events, calculates position-related statuses, and emits appropriate events.
    */
@@ -1046,46 +1035,6 @@ class TinySmartScroller {
     return this.#isPastAtCustomBottom;
   }
 
-  /**
-   * Checks if the user is within the defined extra scroll boundary from the bottom.
-   *
-   * @returns {boolean}
-   * @deprecated - Use isAtCustomBottom instead.
-   */
-  isUserAtCustomBottom() {
-    return this.#isAtCustomBottom;
-  }
-
-  /**
-   * Checks if the user is within the defined extra scroll boundary from the top.
-   *
-   * @returns {boolean}
-   * @deprecated - Use isAtCustomTop instead.
-   */
-  isUserAtCustomTop() {
-    return this.#isAtCustomTop;
-  }
-
-  /**
-   * Returns true if the user is currently scrolled to the bottom of the element.
-   *
-   * @returns {boolean}
-   * @deprecated - Use isAtBottom instead.
-   */
-  isUserAtBottom() {
-    return this.#isAtBottom;
-  }
-
-  /**
-   * Returns true if the user is currently scrolled to the top of the element.
-   *
-   * @returns {boolean}
-   * @deprecated - Use isAtTop instead.
-   */
-  isUserAtTop() {
-    return this.#isAtTop;
-  }
-
   /**
    * Returns true if automatic scrolling is currently paused.
    *

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

@@ -402,14 +402,6 @@ declare class TinySmartScroller {
         oldIsVisible: boolean;
         isVisible: boolean;
     }>;
-    /**
-     * Emits a scroll-related event to all registered listeners.
-     *
-     * @param {string} event - Event name.
-     * @param {*} [payload] - Optional event data payload.
-     * @deprecated - Use emit() instead.
-     */
-    _emit(event: string, payload?: any): void;
     /**
      * Handles scroll events, calculates position-related statuses, and emits appropriate events.
      */
@@ -558,34 +550,6 @@ declare class TinySmartScroller {
      * @returns {boolean}
      */
     isPastAtCustomBottom(): boolean;
-    /**
-     * Checks if the user is within the defined extra scroll boundary from the bottom.
-     *
-     * @returns {boolean}
-     * @deprecated - Use isAtCustomBottom instead.
-     */
-    isUserAtCustomBottom(): boolean;
-    /**
-     * Checks if the user is within the defined extra scroll boundary from the top.
-     *
-     * @returns {boolean}
-     * @deprecated - Use isAtCustomTop instead.
-     */
-    isUserAtCustomTop(): boolean;
-    /**
-     * Returns true if the user is currently scrolled to the bottom of the element.
-     *
-     * @returns {boolean}
-     * @deprecated - Use isAtBottom instead.
-     */
-    isUserAtBottom(): boolean;
-    /**
-     * Returns true if the user is currently scrolled to the top of the element.
-     *
-     * @returns {boolean}
-     * @deprecated - Use isAtTop instead.
-     */
-    isUserAtTop(): boolean;
     /**
      * Returns true if automatic scrolling is currently paused.
      *

package/dist/v1/libs/TinySmartScroller.mjs

@@ -511,16 +511,6 @@ class TinySmartScroller {
         });
         return results;
     }
-    /**
-     * Emits a scroll-related event to all registered listeners.
-     *
-     * @param {string} event - Event name.
-     * @param {*} [payload] - Optional event data payload.
-     * @deprecated - Use emit() instead.
-     */
-    _emit(event, payload) {
-        this.emit(event, payload);
-    }
     /**
      * Handles scroll events, calculates position-related statuses, and emits appropriate events.
      */
@@ -907,42 +897,6 @@ class TinySmartScroller {
     isPastAtCustomBottom() {
         return this.#isPastAtCustomBottom;
     }
-    /**
-     * Checks if the user is within the defined extra scroll boundary from the bottom.
-     *
-     * @returns {boolean}
-     * @deprecated - Use isAtCustomBottom instead.
-     */
-    isUserAtCustomBottom() {
-        return this.#isAtCustomBottom;
-    }
-    /**
-     * Checks if the user is within the defined extra scroll boundary from the top.
-     *
-     * @returns {boolean}
-     * @deprecated - Use isAtCustomTop instead.
-     */
-    isUserAtCustomTop() {
-        return this.#isAtCustomTop;
-    }
-    /**
-     * Returns true if the user is currently scrolled to the bottom of the element.
-     *
-     * @returns {boolean}
-     * @deprecated - Use isAtBottom instead.
-     */
-    isUserAtBottom() {
-        return this.#isAtBottom;
-    }
-    /**
-     * Returns true if the user is currently scrolled to the top of the element.
-     *
-     * @returns {boolean}
-     * @deprecated - Use isAtTop instead.
-     */
-    isUserAtTop() {
-        return this.#isAtTop;
-    }
     /**
      * Returns true if automatic scrolling is currently paused.
      *

package/dist/v1/libs/TinyToastNotify.cjs

@@ -305,10 +305,10 @@ class TinyToastNotify {
 
     // Optional hover effect
     closeBtn.addEventListener('mouseenter', () => {
-      closeBtn.style.color = 'var(--notif-close-color-hover)';
+      closeBtn.style.color = 'var(--notify-close-color-hover)';
     });
     closeBtn.addEventListener('mouseleave', () => {
-      closeBtn.style.color = 'var(--notif-close-color)';
+      closeBtn.style.color = 'var(--notify-close-color)';
     });
 
     // Avatar

package/dist/v1/libs/TinyToastNotify.mjs

@@ -266,10 +266,10 @@ class TinyToastNotify {
         closeBtn.setAttribute('aria-label', 'Close');
         // Optional hover effect
         closeBtn.addEventListener('mouseenter', () => {
-            closeBtn.style.color = 'var(--notif-close-color-hover)';
+            closeBtn.style.color = 'var(--notify-close-color-hover)';
         });
         closeBtn.addEventListener('mouseleave', () => {
-            closeBtn.style.color = 'var(--notif-close-color)';
+            closeBtn.style.color = 'var(--notify-close-color)';
         });
         // Avatar
         if (avatarUrl) {

package/dist/v1/libs/TinyUploadClicker.cjs

@@ -2,10 +2,10 @@
 
 require('../basics/objFilter.cjs');
 var objChecker = require('../basics/objChecker.cjs');
-require('./TinyHtml.cjs');
 require('fs');
 require('path');
 require('fs/promises');
+require('./TinyHtml.cjs');
 require('./TinyLocalStorage.cjs');
 
 /**

package/docs/v1/Ai-Tips.md

@@ -0,0 +1,51 @@
+## 🧭 How I Work with AI (Tips & Workflow)
+
+Over time, I've built a personal workflow to make sure AI helps me *efficiently* — without ruining my focus, logic, or the structure of my code and documentation. Here are some habits and tricks I always follow:
+
+* 📝 **Persistent Prompt Instructions**
+  I noticed that AI often starts forgetting layout and formatting instructions after just a few messages. To prevent this, I keep a notepad with my core prompts and manually repeat key instructions every time I ask something, especially when working on documentation.
+
+* ⚙️ **System Prompt Setup**
+  One of my most effective strategies is maintaining a *System Instruction prompt* that defines the main behaviors I expect in **all my projects**. It includes things like:
+
+  * Avoid adding humor or randomness
+  * Always be 100% sincere and logical
+  * Don’t include jsDoc descriptions unless I explicitly allow it (especially when I'm still working on a WIP feature)
+
+* 🧠 **How I Talk to AI**
+  I don’t try to talk to AI like it’s a person. I speak in a very natural, clear, and structured way — as if I were talking to a computer, because that’s what it is. This keeps things predictable and productive.
+
+* 🔧 **Using the Chat History Interface Carefully**
+  I frequently use history editing tools (when available) to fix incorrect messages and keep the whole conversation aligned and accurate. The cleaner the context, the better the answers — especially over long sessions.
+
+* 🧹 **Avoiding Context Drift**
+  The more you keep talking without resetting or correcting the prompt, the more likely it is that AI starts misunderstanding the conversation. So I always try to keep things clean and well-structured to preserve context.
+
+* 📏 **Limit Code Size per Message**
+  I avoid dumping extremely long blocks of code into the chat. Instead, I share only the relevant part or break the code into smaller, medium-sized chunks. This prevents confusion and makes it easier for AI to focus on what I actually need.
+
+* 💬 **Managing Large Output Responses**
+  If a reply needs to be very long, AI might break or compress the message too much to fit it into a single reply — and this often ruins the meaning or structure of the output. I always consider this when asking questions and sometimes break complex requests into smaller steps.
+
+---
+
+## 🤖 About AI Usage in the Projects
+
+Some parts of this project were assisted by AI, but all the core decisions and logic come directly from me. Here's how I usually balance things:
+
+* 🧠 **Ideas and Logic**:
+  All the concepts, how the system works, and the reasoning behind each part of the code are my own. I use AI mostly as a helper to speed things up or explore alternatives, but I’m always the one guiding and correcting everything.
+
+* 📄 **jsDocs and Type Structures**:
+  I take care of the structure and typing in the documentation myself. When it comes to writing the descriptions, I might use AI to help word things better, but the meaning and context are always mine.
+
+* 🧪 **HTML Test Files**:
+  For testing interfaces, I usually let AI generate the base since it's faster to describe what I need than build it all from scratch. It helps me quickly test the behavior of what I’ve programmed.
+
+* ✍️ **Text (Messages, Descriptions, etc.)**:
+  I often ask AI to help me write or polish messages, explanations, or descriptions. It's great for keeping things clear and readable, but I always review and adjust it to match the logic and personality I want.
+
+* 🌸 **Style and Personality**:
+  I love using emojis and I’ve set up my system to guide how AI writes with my personal style. That includes tone, formatting, and the little details that make the project feel like mine.
+
+This approach is consistent across all my projects. It lets me stay focused on what really matters to me — logic, structure, and creativity — while still using AI as a practical tool when it makes sense.