tiny-essentials 1.20.2 → 1.21.0

package/dist/v1/libs/TinySmartScroller.cjs

@@ -275,6 +275,11 @@ class TinySmartScroller {
   /** @type {null|EventListenerOrEventListenerObject} */
   #handler = null;
 
+  #isPastAtBottom = false;
+  #isPastAtTop = false;
+  #isPastAtCustomTop = false;
+  #isPastAtCustomBottom = false;
+
   #isAtBottom = false;
   #isAtTop = false;
   #isAtCustomTop = false;
@@ -596,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.
    */
@@ -639,6 +633,12 @@ class TinySmartScroller {
     else if (atCustomTop) atCustomResult = 'top';
     else if (atCustomBottom) atCustomResult = 'bottom';
 
+    this.#isPastAtTop = this.#isAtTop ?? false;
+    this.#isPastAtBottom = this.#isAtBottom ?? false;
+
+    this.#isPastAtCustomTop = this.#isAtCustomTop ?? false;
+    this.#isPastAtCustomBottom = this.#isAtCustomBottom ?? false;
+
     this.#isAtTop = atTop;
     this.#isAtBottom = atBottom;
 
@@ -968,7 +968,7 @@ class TinySmartScroller {
    *
    * @returns {boolean}
    */
-  isUserAtCustomBottom() {
+  isAtCustomBottom() {
     return this.#isAtCustomBottom;
   }
 
@@ -977,7 +977,7 @@ class TinySmartScroller {
    *
    * @returns {boolean}
    */
-  isUserAtCustomTop() {
+  isAtCustomTop() {
     return this.#isAtCustomTop;
   }
 
@@ -986,7 +986,7 @@ class TinySmartScroller {
    *
    * @returns {boolean}
    */
-  isUserAtBottom() {
+  isAtBottom() {
     return this.#isAtBottom;
   }
 
@@ -995,10 +995,46 @@ class TinySmartScroller {
    *
    * @returns {boolean}
    */
-  isUserAtTop() {
+  isAtTop() {
     return this.#isAtTop;
   }
 
+  /**
+   * Returns true if the user has already passed beyond the bottom boundary at some point.
+   *
+   * @returns {boolean}
+   */
+  isPastAtBottom() {
+    return this.#isPastAtBottom;
+  }
+
+  /**
+   * Returns true if the user has already passed beyond the top boundary at some point.
+   *
+   * @returns {boolean}
+   */
+  isPastAtTop() {
+    return this.#isPastAtTop;
+  }
+
+  /**
+   * Returns true if the user has passed beyond the defined extra scroll boundary from the top at some point.
+   *
+   * @returns {boolean}
+   */
+  isPastAtCustomTop() {
+    return this.#isPastAtCustomTop;
+  }
+
+  /**
+   * Returns true if the user has passed beyond the defined extra scroll boundary from the bottom at some point.
+   *
+   * @returns {boolean}
+   */
+  isPastAtCustomBottom() {
+    return this.#isPastAtCustomBottom;
+  }
+
   /**
    * 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.
      */
@@ -515,25 +507,49 @@ declare class TinySmartScroller {
      *
      * @returns {boolean}
      */
-    isUserAtCustomBottom(): boolean;
+    isAtCustomBottom(): boolean;
     /**
      * Checks if the user is within the defined extra scroll boundary from the top.
      *
      * @returns {boolean}
      */
-    isUserAtCustomTop(): boolean;
+    isAtCustomTop(): boolean;
     /**
      * Returns true if the user is currently scrolled to the bottom of the element.
      *
      * @returns {boolean}
      */
-    isUserAtBottom(): boolean;
+    isAtBottom(): boolean;
     /**
      * Returns true if the user is currently scrolled to the top of the element.
      *
      * @returns {boolean}
      */
-    isUserAtTop(): boolean;
+    isAtTop(): boolean;
+    /**
+     * Returns true if the user has already passed beyond the bottom boundary at some point.
+     *
+     * @returns {boolean}
+     */
+    isPastAtBottom(): boolean;
+    /**
+     * Returns true if the user has already passed beyond the top boundary at some point.
+     *
+     * @returns {boolean}
+     */
+    isPastAtTop(): boolean;
+    /**
+     * Returns true if the user has passed beyond the defined extra scroll boundary from the top at some point.
+     *
+     * @returns {boolean}
+     */
+    isPastAtCustomTop(): boolean;
+    /**
+     * Returns true if the user has passed beyond the defined extra scroll boundary from the bottom at some point.
+     *
+     * @returns {boolean}
+     */
+    isPastAtCustomBottom(): boolean;
     /**
      * Returns true if automatic scrolling is currently paused.
      *

package/dist/v1/libs/TinySmartScroller.mjs

@@ -236,6 +236,10 @@ class TinySmartScroller {
     #loadTags = new Set(['IMG', 'IFRAME', 'VIDEO']);
     /** @type {null|EventListenerOrEventListenerObject} */
     #handler = null;
+    #isPastAtBottom = false;
+    #isPastAtTop = false;
+    #isPastAtCustomTop = false;
+    #isPastAtCustomBottom = false;
     #isAtBottom = false;
     #isAtTop = false;
     #isAtCustomTop = false;
@@ -507,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.
      */
@@ -550,6 +544,10 @@ class TinySmartScroller {
             atCustomResult = 'top';
         else if (atCustomBottom)
             atCustomResult = 'bottom';
+        this.#isPastAtTop = this.#isAtTop ?? false;
+        this.#isPastAtBottom = this.#isAtBottom ?? false;
+        this.#isPastAtCustomTop = this.#isAtCustomTop ?? false;
+        this.#isPastAtCustomBottom = this.#isAtCustomBottom ?? false;
         this.#isAtTop = atTop;
         this.#isAtBottom = atBottom;
         this.#isAtCustomTop = atCustomTop;
@@ -840,7 +838,7 @@ class TinySmartScroller {
      *
      * @returns {boolean}
      */
-    isUserAtCustomBottom() {
+    isAtCustomBottom() {
         return this.#isAtCustomBottom;
     }
     /**
@@ -848,7 +846,7 @@ class TinySmartScroller {
      *
      * @returns {boolean}
      */
-    isUserAtCustomTop() {
+    isAtCustomTop() {
         return this.#isAtCustomTop;
     }
     /**
@@ -856,7 +854,7 @@ class TinySmartScroller {
      *
      * @returns {boolean}
      */
-    isUserAtBottom() {
+    isAtBottom() {
         return this.#isAtBottom;
     }
     /**
@@ -864,9 +862,41 @@ class TinySmartScroller {
      *
      * @returns {boolean}
      */
-    isUserAtTop() {
+    isAtTop() {
         return this.#isAtTop;
     }
+    /**
+     * Returns true if the user has already passed beyond the bottom boundary at some point.
+     *
+     * @returns {boolean}
+     */
+    isPastAtBottom() {
+        return this.#isPastAtBottom;
+    }
+    /**
+     * Returns true if the user has already passed beyond the top boundary at some point.
+     *
+     * @returns {boolean}
+     */
+    isPastAtTop() {
+        return this.#isPastAtTop;
+    }
+    /**
+     * Returns true if the user has passed beyond the defined extra scroll boundary from the top at some point.
+     *
+     * @returns {boolean}
+     */
+    isPastAtCustomTop() {
+        return this.#isPastAtCustomTop;
+    }
+    /**
+     * Returns true if the user has passed beyond the defined extra scroll boundary from the bottom at some point.
+     *
+     * @returns {boolean}
+     */
+    isPastAtCustomBottom() {
+        return this.#isPastAtCustomBottom;
+    }
     /**
      * Returns true if automatic scrolling is currently paused.
      *

package/dist/v1/libs/TinyTextarea.cjs

@@ -0,0 +1,230 @@
+'use strict';
+
+/**
+ * @typedef {Object} OnInputInfo
+ * @property {number} breakLines - Total number of `\n` line breaks in the textarea value.
+ * @property {number} height - Final calculated height (in pixels) applied to the textarea.
+ * @property {number} scrollHeight - Internal scrollHeight before limiting.
+ * @property {number} maxHeight - Maximum allowed height before scrolling is forced.
+ * @property {number} lineHeight - Height of one line of text, computed from CSS.
+ * @property {number} maxRows - Maximum number of visible rows allowed.
+ * @property {number} rows - Effective number of visual rows being used.
+ */
+
+/**
+ * A lightweight utility class that automatically adjusts the height of a `<textarea>`
+ * element based on its content. It prevents scrollbars by expanding vertically as needed,
+ * up to a configurable maximum number of visible rows.
+ *
+ * Features:
+ * - Automatically resizes the textarea as the user types
+ * - Prevents vertical scrollbars until a maximum row limit is reached
+ * - Supports additional height padding
+ * - Provides real-time callbacks for input and resize events
+ * - Allows manual refresh and cleanup of behavior
+ *
+ * Ideal for chat inputs, note editors, or any form where dynamic space usage
+ * is preferred without relying on scrollbars too early.
+ *
+ * @class
+ * @beta
+ */
+class TinyTextarea {
+  #lineHeight;
+  #maxRows;
+  #extraHeight;
+
+  #lastKnownHeight = 0;
+  #lastKnownRows = 0;
+
+  /** @type {HTMLTextAreaElement} */
+  #textarea;
+
+  /**
+   * @type {((info: OnInputInfo) => void) | null}
+   */
+  #onResize = null;
+
+  /**
+   * @type {((info: OnInputInfo) => void) | null}
+   */
+  #onInput = null;
+
+  /**
+   * Returns the computed line height in pixels.
+   * @returns {number}
+   */
+  get lineHeight() {
+    return this.#lineHeight;
+  }
+
+  /**
+   * Returns the maximum number of rows allowed.
+   * @returns {number}
+   */
+  get maxRows() {
+    return this.#maxRows - 1;
+  }
+
+  /**
+   * Returns the additional height added to the textarea.
+   * @returns {number}
+   */
+  get extraHeight() {
+    return this.#extraHeight;
+  }
+
+  /**
+   * Returns the most recently applied height.
+   * @returns {number}
+   */
+  get currentHeight() {
+    return this.#lastKnownHeight;
+  }
+
+  /**
+   * Returns the most recently calculated row count.
+   * @returns {number}
+   */
+  get currentRows() {
+    return this.#lastKnownRows;
+  }
+
+  /**
+   * Returns the original textarea element managed by this instance.
+   * @returns {HTMLTextAreaElement}
+   */
+  get textarea() {
+    return this.#textarea;
+  }
+
+  /**
+   * Creates a new TinyTextarea instance.
+   *
+   * @param {HTMLTextAreaElement} textarea - The `<textarea>` element to enhance.
+   * @param {Object} [options={}] - Optional configuration parameters.
+   * @param {number} [options.maxRows] - Maximum number of visible rows before scrolling.
+   * @param {number} [options.extraHeight] - Additional pixels to add to final height.
+   * @param {(info: OnInputInfo) => void} [options.onResize] - Callback when the number of rows changes.
+   * @param {(info: OnInputInfo) => void} [options.onInput] - Callback on every input event.
+   * @throws {Error} If `textarea` is not a valid `<textarea>` element.
+   * @throws {TypeError} If provided options are of invalid types.
+   */
+  constructor(textarea, options = {}) {
+    if (!(textarea instanceof HTMLTextAreaElement))
+      throw new Error('TinyTextarea: Provided element is not a <textarea>.');
+    if (typeof options !== 'object' || options === null)
+      throw new TypeError('TinyTextarea: Options must be an object if provided.');
+    if ('maxRows' in options && typeof options.maxRows !== 'number')
+      throw new TypeError('TinyTextarea: `maxRows` must be a number.');
+    if ('extraHeight' in options && typeof options.extraHeight !== 'number')
+      throw new TypeError('TinyTextarea: `extraHeight` must be a number.');
+    if ('onResize' in options && typeof options.onResize !== 'function')
+      throw new TypeError('TinyTextarea: `onResize` must be a function.');
+    if ('onInput' in options && typeof options.onInput !== 'function')
+      throw new TypeError('TinyTextarea: `onInput` must be a function.');
+
+    this.#textarea = textarea;
+    this.#maxRows = (options.maxRows ?? 5) + 1;
+    this.#extraHeight = options.extraHeight ?? 0;
+    this.#onResize = options.onResize ?? null;
+    this.#onInput = options.onInput ?? null;
+
+    this.#lineHeight = this.#getLineHeight();
+
+    textarea.style.overflowY = 'hidden';
+    textarea.style.resize = 'none';
+
+    this._handleInput = () => this.#resize();
+    textarea.addEventListener('input', this._handleInput);
+    this.#resize();
+  }
+
+  /**
+   * Automatically resize the textarea based on its content and notify listeners.
+   * Triggers `onResize` if the number of rows has changed.
+   * Always triggers `onInput`.
+   */
+  #resize() {
+    this.#textarea.style.height = 'auto';
+
+    const style = window.getComputedStyle(this.#textarea);
+    const paddingTop = parseFloat(style.paddingTop) || 0;
+    const paddingBottom = parseFloat(style.paddingBottom) || 0;
+
+    const breakLines = (this.#textarea.value.match(/\n/g) || []).length;
+    const scrollHeight = this.#textarea.scrollHeight;
+    const maxHeight = this.#lineHeight * this.#maxRows;
+    const newHeight = Math.ceil(
+      Math.min(scrollHeight, maxHeight) - paddingTop - paddingBottom + this.#extraHeight,
+    );
+
+    // const rows = Math.round(newHeight / this.#lineHeight);
+    const maxRows = this.#maxRows - 1;
+    const rows = breakLines < maxRows ? breakLines + 1 : maxRows;
+
+    this.#textarea.style.height = `${newHeight}px`;
+    this.#textarea.style.overflowY = scrollHeight > maxHeight ? 'auto' : 'hidden';
+    this.#lastKnownHeight = newHeight;
+
+    const info = {
+      breakLines,
+      rows,
+      height: newHeight,
+      scrollHeight,
+      maxHeight,
+      lineHeight: this.#lineHeight,
+      maxRows,
+    };
+
+    if (rows !== this.#lastKnownRows) {
+      this.#lastKnownRows = rows;
+      if (typeof this.#onResize === 'function') {
+        this.#onResize({ ...info });
+      }
+    }
+
+    if (typeof this.#onInput === 'function') {
+      this.#onInput(info);
+    }
+  }
+
+  /**
+   * Computes the current line height from the textarea's computed styles.
+   * Falls back to `fontSize * 1.2` if lineHeight is not a number.
+   * @returns {number} - The computed line height in pixels.
+   */
+  #getLineHeight() {
+    const style = window.getComputedStyle(this.#textarea);
+    const line = parseFloat(style.lineHeight);
+    if (!Number.isNaN(line)) return line;
+    return parseFloat(style.fontSize) * 1.2;
+  }
+
+  /**
+   * Returns the latest height and row count of the textarea.
+   * @returns {{ height: number, rows: number }} - Last known resize state.
+   */
+  getData() {
+    return {
+      rows: this.#lastKnownRows,
+      height: this.#lastKnownHeight,
+    };
+  }
+
+  /**
+   * Manually trigger a resize check.
+   */
+  refresh() {
+    this.#resize();
+  }
+
+  /**
+   * Cleans up internal listeners and disables dynamic behavior.
+   */
+  destroy() {
+    this.#textarea.removeEventListener('input', this._handleInput);
+  }
+}
+
+module.exports = TinyTextarea;

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

@@ -0,0 +1,128 @@
+export default TinyTextarea;
+export type OnInputInfo = {
+    /**
+     * - Total number of `\n` line breaks in the textarea value.
+     */
+    breakLines: number;
+    /**
+     * - Final calculated height (in pixels) applied to the textarea.
+     */
+    height: number;
+    /**
+     * - Internal scrollHeight before limiting.
+     */
+    scrollHeight: number;
+    /**
+     * - Maximum allowed height before scrolling is forced.
+     */
+    maxHeight: number;
+    /**
+     * - Height of one line of text, computed from CSS.
+     */
+    lineHeight: number;
+    /**
+     * - Maximum number of visible rows allowed.
+     */
+    maxRows: number;
+    /**
+     * - Effective number of visual rows being used.
+     */
+    rows: number;
+};
+/**
+ * @typedef {Object} OnInputInfo
+ * @property {number} breakLines - Total number of `\n` line breaks in the textarea value.
+ * @property {number} height - Final calculated height (in pixels) applied to the textarea.
+ * @property {number} scrollHeight - Internal scrollHeight before limiting.
+ * @property {number} maxHeight - Maximum allowed height before scrolling is forced.
+ * @property {number} lineHeight - Height of one line of text, computed from CSS.
+ * @property {number} maxRows - Maximum number of visible rows allowed.
+ * @property {number} rows - Effective number of visual rows being used.
+ */
+/**
+ * A lightweight utility class that automatically adjusts the height of a `<textarea>`
+ * element based on its content. It prevents scrollbars by expanding vertically as needed,
+ * up to a configurable maximum number of visible rows.
+ *
+ * Features:
+ * - Automatically resizes the textarea as the user types
+ * - Prevents vertical scrollbars until a maximum row limit is reached
+ * - Supports additional height padding
+ * - Provides real-time callbacks for input and resize events
+ * - Allows manual refresh and cleanup of behavior
+ *
+ * Ideal for chat inputs, note editors, or any form where dynamic space usage
+ * is preferred without relying on scrollbars too early.
+ *
+ * @class
+ * @beta
+ */
+declare class TinyTextarea {
+    /**
+     * Creates a new TinyTextarea instance.
+     *
+     * @param {HTMLTextAreaElement} textarea - The `<textarea>` element to enhance.
+     * @param {Object} [options={}] - Optional configuration parameters.
+     * @param {number} [options.maxRows] - Maximum number of visible rows before scrolling.
+     * @param {number} [options.extraHeight] - Additional pixels to add to final height.
+     * @param {(info: OnInputInfo) => void} [options.onResize] - Callback when the number of rows changes.
+     * @param {(info: OnInputInfo) => void} [options.onInput] - Callback on every input event.
+     * @throws {Error} If `textarea` is not a valid `<textarea>` element.
+     * @throws {TypeError} If provided options are of invalid types.
+     */
+    constructor(textarea: HTMLTextAreaElement, options?: {
+        maxRows?: number | undefined;
+        extraHeight?: number | undefined;
+        onResize?: ((info: OnInputInfo) => void) | undefined;
+        onInput?: ((info: OnInputInfo) => void) | undefined;
+    });
+    /**
+     * Returns the computed line height in pixels.
+     * @returns {number}
+     */
+    get lineHeight(): number;
+    /**
+     * Returns the maximum number of rows allowed.
+     * @returns {number}
+     */
+    get maxRows(): number;
+    /**
+     * Returns the additional height added to the textarea.
+     * @returns {number}
+     */
+    get extraHeight(): number;
+    /**
+     * Returns the most recently applied height.
+     * @returns {number}
+     */
+    get currentHeight(): number;
+    /**
+     * Returns the most recently calculated row count.
+     * @returns {number}
+     */
+    get currentRows(): number;
+    /**
+     * Returns the original textarea element managed by this instance.
+     * @returns {HTMLTextAreaElement}
+     */
+    get textarea(): HTMLTextAreaElement;
+    _handleInput: () => void;
+    /**
+     * Returns the latest height and row count of the textarea.
+     * @returns {{ height: number, rows: number }} - Last known resize state.
+     */
+    getData(): {
+        height: number;
+        rows: number;
+    };
+    /**
+     * Manually trigger a resize check.
+     */
+    refresh(): void;
+    /**
+     * Cleans up internal listeners and disables dynamic behavior.
+     */
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=TinyTextarea.d.mts.map