tiny-essentials 1.20.2 → 1.20.3

package/dist/v1/libs/TinyTextarea.mjs

@@ -0,0 +1,198 @@
+/**
+ * @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);
+    }
+}
+export default TinyTextarea;

package/docs/v1/README.md

@@ -46,6 +46,7 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 📦 **[TinyLocalStorage](./libs/TinyLocalStorage.md)** — A tiny wrapper for `localStorage` with full support for objects, arrays, `Map`, `Set`, and typed value helpers like string, number, and boolean.
 - 🖼️ **[TinyIframeEvents](./libs/TinyIframeEvents.md)** — A structured `postMessage`-based event router for secure and reliable communication between a parent window and its embedded iframe. Supports directional filtering, origin enforcement, payload transport, and listener lifecycle.
 - 🪟 **[TinyNewWinEvents](./libs/TinyNewWinEvents.md)** — A smart, route-based `postMessage` system for structured communication between a main window and a popup (`window.open`). Includes queueing, origin enforcement, and lifecycle tracking.
+- ✨ **[TinyTextarea](./libs/TinyTextarea.md)** — A minimal auto-expanding `<textarea>` manager with configurable row limits, extra height padding, and real-time resize/input event hooks.
 
 ### 3. **`fileManager/`**
 * 📁 **[Main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.

package/docs/v1/libs/TinySmartScroller.md

@@ -442,19 +442,19 @@ Scrolls the target all the way to the top immediately.
 
 ## 🧭 Scroll Position Status
 
-### 🔚 `isUserAtCustomBottom()`
+### 🔚 `isAtCustomBottom()`
 
 Returns `true` if the user is within the custom boundary of the bottom.
 
-### 🔝 `isUserAtCustomTop()`
+### 🔝 `isAtCustomTop()`
 
 Returns `true` if the user is within the custom boundary of the top.
 
-### 🧨 `isUserAtBottom()`
+### 🧨 `isAtBottom()`
 
 Returns `true` if user is currently scrolled to the actual bottom.
 
-### 🧷 `isUserAtTop()`
+### 🧷 `isAtTop()`
 
 Returns `true` if user is currently scrolled to the actual top.
 

package/docs/v1/libs/TinyTextarea.md

@@ -0,0 +1,156 @@
+# ✨ `TinyTextarea`
+
+A lightweight JavaScript utility for automatically resizing `<textarea>` elements as users type — without ugly scrollbars!
+
+---
+
+## 📦 Features
+
+* 🔁 **Auto-resizing**: Grows or shrinks with the content
+* 🚫 **No scrollbars** (until limit): Prevents `overflow-y` unless needed
+* 🔧 **Configurable**: Set `maxRows`, `extraHeight`, and hooks
+* 📡 **Live events**: Hooks for `onInput` and `onResize`
+* 🧼 **Clean lifecycle**: Includes `.refresh()` and `.destroy()`
+
+---
+
+## 🚀 Usage
+
+```js
+import TinyTextarea from './TinyTextarea.js';
+
+const textarea = document.querySelector('textarea');
+
+const autoResize = new TinyTextarea(textarea, {
+  maxRows: 8,
+  extraHeight: 0,
+  onResize: (info) => console.log('Resized:', info),
+  onInput: (info) => console.log('Input event:', info),
+});
+```
+
+To stop behavior and clean up:
+
+```js
+autoResize.destroy();
+```
+
+---
+
+## 🔧 Constructor
+
+```js
+new TinyTextarea(textarea, options?);
+```
+
+### Parameters
+
+| Name                  | Type                          | Description                                           |
+| --------------------- | ----------------------------- | ----------------------------------------------------- |
+| `textarea`            | `HTMLTextAreaElement`         | The `<textarea>` element to be managed.               |
+| `options`             | `Object` *(optional)*         | Configuration options.                                |
+| `options.maxRows`     | `number`                      | Max number of visible rows before scrollbars appear.  |
+| `options.extraHeight` | `number`                      | Extra height (in px) to add on top of computed value. |
+| `options.onResize`    | `(info: OnInputInfo) => void` | Called when number of visible rows changes.           |
+| `options.onInput`     | `(info: OnInputInfo) => void` | Called on every `input` event.                        |
+
+---
+
+## 📚 API
+
+### `.getData() → { height, rows }`
+
+Returns the last known height and number of visible rows.
+
+```js
+const { height, rows } = autoResize.getData();
+```
+
+---
+
+### `.refresh()`
+
+Forces a manual recalculation and resize of the `<textarea>`.
+
+```js
+autoResize.refresh();
+```
+
+---
+
+### `.destroy()`
+
+Cleans up listeners and disables resizing behavior. Use this if you remove the element or want to stop automatic behavior.
+
+```js
+autoResize.destroy();
+```
+
+---
+
+### 🔍 Getters
+
+TinyTextarea exposes several readonly properties to let you inspect the current configuration and state of the managed `<textarea>`.
+
+#### 📏 `lineHeight: number`
+
+Returns the height in pixels of a single line of text in the textarea, computed from its current CSS styles.
+Useful for calculating exact space usage or aligning UI elements.
+
+---
+
+#### 📐 `maxRows: number`
+
+Returns the maximum number of visible text rows allowed before the textarea begins to scroll.
+This value reflects the limit set via `options.maxRows`.
+
+---
+
+#### ➕ `extraHeight: number`
+
+Returns the number of extra pixels added to the calculated height of the textarea.
+This is useful for custom padding or visual adjustments.
+
+---
+
+#### 📏 `currentHeight: number`
+
+Returns the most recently applied height (in pixels) that was set on the `<textarea>` after resizing.
+
+---
+
+#### 📊 `currentRows: number`
+
+Returns the most recent number of visible text rows that the textarea is currently using.
+This value is calculated dynamically and may change as the user types.
+
+---
+
+#### 🧩 `textarea: HTMLTextAreaElement`
+
+Returns the original `<textarea>` DOM element that was enhanced by this instance.
+You can use this for direct styling, value changes, or other DOM-level operations.
+
+---
+
+## 📤 Event Payload: `OnInputInfo`
+
+Whenever `onResize` or `onInput` is triggered, the following object is passed:
+
+```ts
+{
+  breakLines: number;    // Total number of '\n' in the textarea
+  height: number;        // Final computed height (px)
+  scrollHeight: number;  // Natural scrollHeight of textarea
+  maxHeight: number;     // Max height before scrollbars show
+  lineHeight: number;    // Height of one line of text
+  maxRows: number;       // Maximum number of visible rows allowed
+  rows: number;          // Final calculated number of rows used
+}
+```
+
+---
+
+## 🧪 Beta Notice
+
+> 🧪 This library is currently marked as `@beta`. The API is stable but may be adjusted slightly during updates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.20.2",
+  "version": "1.20.3",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",