tiny-essentials 1.20.1 → 1.20.3

package/docs/v1/basics/html.md

@@ -142,11 +142,11 @@ saveJsonFile('yasmin.json', data);
 
 ### 🌐 `fetchTemplate(...)`
 
-Loads data from a remote URL using Fetch API, with support for custom HTTP methods, retries, timeouts, headers, and even external abort controllers.
+Loads data from a remote URL using the Fetch API, with support for custom HTTP methods, retries, timeouts, headers, and even external abort controllers.
 
 #### 📥 Parameters
 
-* `url` *(string)*: The full URL to fetch JSON from (must start with `http://`, `https://`, `/`, `./`, or `../`).
+* `url` *(string)*: The full URL to fetch from (must start with `http://`, `https://`, `/`, `./`, or `../`).
 * `options` *(object)* *(optional)*:
 
   * `signal` *(`AbortSignal` | `null`)*: Custom abort signal.
@@ -156,42 +156,88 @@ Loads data from a remote URL using Fetch API, with support for custom HTTP metho
   * `headers` *(object)*: Additional headers to include in the request.
   * `body` *(object)*: Request body. If the value is a plain object, it will be automatically stringified as JSON.
 
-#### `fetchJson(url, options?): Promise<any[] | Record<string | number | symbol, unknown>>`
+#### `fetchJson(url, options?)`
 
-Loads and parses a JSON.
+Loads and parses a remote JSON file.
 
-* `url` *(string)*: The full URL to fetch JSON from (must start with `http://`, `https://`, `/`, `./`, or `../`).
-* `options` *(object)* *(optional)*:
+* **Parameters**:
 
-#### `fetchBlob(url, options?): Promise<any[] | Record<string | number | symbol, unknown>>`
+  * `url` *(string)*: URL to fetch the JSON from.
+  * `options` *(object)* *(optional)*: Same structure as `fetchTemplate`.
 
-Loads a remote file as a Blob.
+* **Returns**:
+  `Promise<any[] | Record<string | number | symbol, unknown>>` — The parsed JSON data.
 
-* `url` *(string)*: The full URL to fetch JSON from (must start with `http://`, `https://`, `/`, `./`, or `../`).
-* `allowedMimeTypes` Optional list of accepted MIME types (e.g., ['image/jpeg']).
-* `options` *(object)* *(optional)*:
+* **Throws**:
 
-##### `signal` (`AbortSignal` | `null`) — *optional*
+  * `Error` if the fetch fails, times out, or returns invalid JSON.
+  * `Error` if the `Content-Type` is not `application/json`.
 
-Custom abort signal. If set:
+---
 
-* The internal timeout mechanism is **disabled**
-* Retry logic is **disabled**
-* Abortion is handled externally
+#### `fetchBlob(url, allowedMimeTypes?, options?)`
 
-#### 📤 Returns
+Loads a remote file as a Blob object.
+
+* **Parameters**:
+
+  * `url` *(string)*: URL of the remote file.
+  * `allowedMimeTypes` *(string\[])* *(optional)*: List of accepted MIME types.
+  * `options` *(object)* *(optional)*: Same structure as `fetchTemplate`.
+
+* **Returns**:
+  `Promise<Blob>`
+
+* **Throws**:
+
+  * `Error` if fetch fails or the MIME type is not allowed.
+  * `Error` if the response is not OK.
+
+---
+
+#### `fetchText(url, allowedMimeTypes?, options?)`
+
+Loads a remote file as **plain text** using the Fetch API.
+
+* **Parameters**:
+
+  * `url` *(string)*: Full URL of the file to fetch.
+  * `allowedMimeTypes` *(string\[])* *(optional)*: List of accepted MIME types (e.g., `['text/plain']`).
+  * `options` *(object)* *(optional)*: Same structure as `fetchTemplate`.
+
+* **Returns**:
+  `Promise<string>` — The content of the file as a text string.
+
+* **Throws**:
 
-* `Promise<any>`: Resolves with the parsed JSON data.
+  * `Error` if the fetch fails or the response is not OK.
+  * `Error` if the MIME type is not in the allowed list (when provided).
+
+---
+
+#### 📤 Returns (for all helpers)
+
+* `Promise<any>` — Depends on the function:
+
+  * `fetchJson`: Parsed JSON
+  * `fetchBlob`: File as a Blob
+  * `fetchText`: File as plain text
+
+---
 
 #### ⚠️ Throws
 
-* `Error` if the fetch fails or exceeds the timeout
-* `Error` if the response is not `application/json`
-* `Error` if the result is not a plain JSON object
+All functions may throw the following:
+
+* `Error` if the request fails or the response times out.
+* `Error` if `Content-Type` does not match expected type (JSON, Blob, Text, etc).
+* `Error` if response is malformed or rejected by MIME type filter.
+
+---
 
 #### 🧠 Tip
 
-If you pass your own `signal`, this disables both `timeout` and `retries`. Use it when you're managing cancellation manually (e.g. in UI components or async workflows).
+Using a custom `signal` disables both `timeout` and `retries`. This is useful when you want to handle cancellation yourself, like in user interfaces or abortable workflows.
 
 #### 🧪 Example
 
@@ -210,6 +256,16 @@ const data = await fetchJson('https://api.example.com/data', {
 });
 ```
 
+```js
+const text = await fetchText('/example.txt', ['text/plain'], {
+  timeout: 3000,
+});
+```
+
+```js
+const blob = await fetchBlob('/image.jpg', ['image/jpeg']);
+```
+
 ---
 
 ### 📦 `HtmlElBoxSides` Type

package/docs/v1/basics/simpleMath.md

@@ -36,19 +36,37 @@ ruleOfThree(2, 6, 3, true); // → 4
 
 ### 💯 `getSimplePerc(price, percentage)`
 
-**Calculates the percentage of a given base value.**
+**Calculates the actual value that corresponds to a percentage of a base number.**
 
-- **`price`**: The base value (for example, the original price of an item).
-- **`percentage`**: The percentage to calculate from the base value.
+Unlike `getPercentage`, which tells how much something represents in percent,  
+this function tells how much a given percentage *is worth* in actual value.
 
-#### Example:
+- **`price`**: The base number to apply the percentage to.  
+- **`percentage`**: The percentage to calculate from the base.
 
+#### Example:
 ```js
 getSimplePerc(200, 15); // → 30
 ```
 
 ---
 
+### 📊 `getPercentage(part, total)`
+
+**Calculates how much percent a partial value represents of the total value.**
+
+This function is useful when you want to know what fraction of the total a value is, in percentage form.
+
+- **`part`**: The partial value to compare.  
+- **`total`**: The total or maximum value.
+
+#### Example:
+```js
+getPercentage(5, 100); // → 5
+```
+
+---
+
 ### 🎂 `getAge(timeData, now)`
 
 **Calculates the age based on a birthdate.**

package/docs/v1/libs/TinyHtml.md

@@ -445,6 +445,139 @@ Finds elements by tag name in a namespace (defaults to XHTML).
 
 ---
 
+## 📑 HTML Parser
+
+### Type Definition
+
+A parsed HTML element represented as an array:
+
+```ts
+type HtmlParsed = [
+  tagName: string,                 // e.g., 'div', 'span', 'img'
+  attributes: Record<string, string>, // Key-value map of all element attributes
+  ...children: (string | HtmlParsed)[] // Nested elements or text content
+];
+```
+
+---
+
+### `fetchHtmlFile(url, ops?)`
+
+Fetches an HTML file from a URL and parses it into a JSON-like structure.
+
+```ts
+static async fetchHtmlFile(url: string | URL | Request, ops?: RequestInit): Promise<HtmlParsed[]>
+```
+
+* **url**: The URL of the HTML file.
+* **ops**: (Optional) `fetch()` options (method, headers, etc).
+* **Returns**: Promise of parsed JSON structure (`HtmlParsed[]`).
+* Throws if content-type is not `text/html`.
+
+---
+
+### `fetchHtmlNodes(url, ops?)`
+
+Fetches an HTML file and returns it as DOM nodes.
+
+```ts
+static async fetchHtmlNodes(url: string, ops?: RequestInit): Promise<(HTMLElement | Text)[]>
+```
+
+* **Returns**: Array of real DOM nodes (`HTMLElement | Text`).
+
+---
+
+### `fetchHtmlTinyElems(url, ops?)`
+
+Fetches HTML and converts it into an array of `TinyHtml` instances.
+
+```ts
+static async fetchHtmlTinyElems(url: string, ops?: RequestInit): Promise<TinyHtml[]>
+```
+
+* **Returns**: `TinyHtml[]` (custom wrapper elements).
+
+---
+
+### `templateToJson(template)`
+
+Converts the contents of a `<template>` to JSON format.
+
+```ts
+static templateToJson(template: HTMLTemplateElement): HtmlParsed[]
+```
+
+* **Returns**: Structured JSON representation (`HtmlParsed[]`).
+
+---
+
+### `templateToNodes(template)`
+
+Converts `<template>` content into real DOM nodes.
+
+```ts
+static templateToNodes(template: HTMLTemplateElement): (Element | Text)[]
+```
+
+* **Returns**: Cloned nodes excluding comments.
+* Throws error if unexpected node types are encountered.
+
+---
+
+### `templateToTinyElems(template)`
+
+Converts a `<template>` into `TinyHtml` instances.
+
+```ts
+static templateToTinyElems(template: HTMLTemplateElement): TinyHtml[]
+```
+
+* **Returns**: Array of `TinyHtml` objects.
+
+---
+
+### `htmlToJson(htmlString)`
+
+Parses an HTML string into structured JSON (`HtmlParsed[]`).
+
+```ts
+static htmlToJson(htmlString: string): HtmlParsed[]
+```
+
+* **Returns**: Parsed representation as an array of `[tag, attributes, ...children]`.
+
+---
+
+### `jsonToNodes(jsonArray)`
+
+Converts parsed JSON back into actual DOM nodes.
+
+```ts
+static jsonToNodes(jsonArray: HtmlParsed[]): (HTMLElement | Text)[]
+```
+
+* **Returns**: Array of DOM elements/text nodes.
+* Skips comments.
+
+---
+
+### `jsonToTinyElems(jsonArray)`
+
+Converts parsed JSON back into `TinyHtml` instances.
+
+```ts
+static jsonToTinyElems(jsonArray: HtmlParsed[]): TinyHtml[]
+```
+
+* **Returns**: TinyHtml-wrapped elements.
+
+---
+
+💡 **Tip**: All conversion methods rely on a consistent internal format (`HtmlParsed[]`). That means you can seamlessly switch between representations (JSON ⇄ DOM ⇄ TinyHtml)!
+
+---
+
 ## 🧩 Internal Element Access
 
 ### `exists(index)`
@@ -461,6 +594,13 @@ Returns the raw DOM element associated with this instance.
 
 ---
 
+### `size`
+Returns the number of elements currently stored in the internal element list.
+
+- **Returns**: `number`
+
+---
+
 ### `extract(index)`
 Extracts a single DOM element from the internal list at the specified index.
 

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.1",
+  "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",