tiny-essentials 1.16.2 → 1.17.1

package/docs/v1/README.md

@@ -35,6 +35,8 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🕒 **[TinyDomReadyManager](./libs/TinyDomReadyManager.md)** — A readiness manager for DOM and async conditions, supporting prioritized callbacks, custom filters, and event-based or promise-based bootstrapping.
 - 📣 **[TinyNotifications](./libs/TinyNotifications.md)** — A browser notification utility with sound support, permission management, truncation logic, default icons, and enforced validation to ensure safe and predictable usage.
 - 🧱 **[TinyHtml](./libs/TinyHtml.md)** — A minimalist DOM utility class that offers jQuery-like methods in pure JavaScript for querying, styling, traversing, event handling, collision detection, and visibility logic — all in a lightweight and chainable interface.
+- 🌀 **[TinySmartScroller](./libs/TinySmartScroller.md)** — A smart scroll monitor that detects user scroll behavior, visibility changes, element sizes, and automatically handles scroll preservation, bottom detection, debounce, and more.
+- 🍮 **[UltraRandomMsgGen](./libs/UltraRandomMsgGen.md)** — A whimsical random message generator using grammar templates, word sets, emojis, and chaotic modes to craft playful text outputs.
 
 ### 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/basics/html.md

@@ -140,9 +140,9 @@ const data = { name: 'Yasmin', type: 'dev' };
 saveJsonFile('yasmin.json', data);
 ```
 
-### 🌐 `fetchJson(url, options?): Promise<any>`
+### 🌐 `fetchTemplate(...)`
 
-Loads and parses a JSON from a remote URL using the Fetch API, with support for custom HTTP methods, retries, timeouts, headers, and even external abort controllers.
+Loads data from a remote URL using Fetch API, with support for custom HTTP methods, retries, timeouts, headers, and even external abort controllers.
 
 #### 📥 Parameters
 
@@ -156,6 +156,21 @@ Loads and parses a JSON from a remote URL using the Fetch API, with support for
   * `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>>`
+
+Loads and parses a JSON.
+
+* `url` *(string)*: The full URL to fetch JSON from (must start with `http://`, `https://`, `/`, `./`, or `../`).
+* `options` *(object)* *(optional)*:
+
+#### `fetchBlob(url, options?): Promise<any[] | Record<string | number | symbol, unknown>>`
+
+Loads a remote file as a Blob.
+
+* `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)*:
+
 ##### `signal` (`AbortSignal` | `null`) — *optional*
 
 Custom abort signal. If set:

package/docs/v1/libs/TinyHtml.md

@@ -1,10 +1,21 @@
 # 📚 TinyHtml Class
 
-`TinyHtml` is a lightweight utility class that provides DOM element manipulation and querying utilities, inspired by jQuery — but with modern native browser APIs.
+`TinyHtml` is a lightweight utility class that provides DOM element manipulation and querying utilities, inspired by jQuery — but built with modern native browser APIs.
 
-It supports both static and instance-level operations, making it easy to work with elements' dimensions, collisions, and more in a readable, performant way.
+It supports both static and instance-level operations, making it easy to work with elements’ dimensions, collisions, and more in a readable and performant way.
+
+Most instance methods that do not return a specific value are designed to return the `TinyHtml` instance itself, enabling **method chaining**.
+This allows you to write fluent and expressive code like:
+
+```js
+TinyHtml.createElement('div')
+  .addClass('box')
+  .setAttr('role', 'dialog')
+  .appendTo(document.body);
+```
+
+This design keeps your code concise while maintaining clarity and control over the DOM structure.
 
----
 
 ## 🧩 Type Definitions – Core Building Blocks
 
@@ -69,8 +80,28 @@ ElementAndWindow | TinyHtml
 
 ---
 
+#### `TinyElementAndWinAndDoc`
+
+Accepts both raw DOM elements, `document`, and the `window` object.
+
+```ts
+ElementAndWinAndDoc | TinyHtml
+```
+
+---
+
 ### 🔀 Union Types
 
+#### `ElementAndWinAndDoc`
+
+Used for scrollable or measurable targets.
+
+```ts
+Element | Window | Document
+```
+
+---
+
 #### `ElementAndWindow`
 
 Used for scrollable or measurable targets.
@@ -97,7 +128,7 @@ Flexible type for querying or filtering elements:
 Values accepted by the TinyHtml constructor:
 
 ```ts
-Window | Element | Document
+Window | Element | Document | Text
 ```
 
 ---
@@ -271,13 +302,63 @@ HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLOptionElement
 
 These methods wrap native DOM query methods and return results as `TinyHtml` instances for consistency.
 
+### `TinyHtml.createElement(tagName, ops)`
+
+Creates a new DOM element with the given tag name and optional creation options.
+
+* **Parameters**:
+
+  * `tagName` *(string)* — The tag name of the element to create (e.g., `'div'`, `'span'`).
+  * `ops` *(ElementCreationOptions)* — *(optional)* Options for advanced element creation.
+* **Returns**: `TinyHtml` — A `TinyHtml` instance wrapping the newly created element.
+* **Throws**:
+
+  * `TypeError` — If `tagName` is not a string.
+  * `TypeError` — If `ops` is defined but not an object.
+
+---
+
+### `TinyHtml.createTextNode(value)`
+
+Creates a new `TinyHtml` instance that wraps a DOM `TextNode`.
+
+This method is useful when you want to insert raw text content into the DOM without it being interpreted as HTML. The returned instance behaves like any other `TinyHtml` element and can be appended or manipulated as needed.
+
+* **Parameters**:
+
+  * `value` *(string)* — The plain text content to be wrapped in a `TextNode`.
+
+* **Returns**: `TinyHtml` — A `TinyHtml` instance wrapping the newly created DOM `TextNode`.
+
+* **Throws**:
+
+  * `TypeError` — If the provided `value` is not a string.
+
+---
+
+### `TinyHtml.createElementFromHTML(htmlString)`
+
+Creates an `HTMLElement` or `TextNode` from an HTML string.
+Supports both elements and plain text.
+
+* **Parameters**:
+
+  * `htmlString` *(string)* — The HTML string to convert.
+
+* **Returns**: `TinyHtml` — A `TinyHtml` instance wrapping the resulting `HTMLElement` or `TextNode`.
+
+* **Throws**:
+
+  * `Error` — If the parsed content does not produce a valid `Element` when expecting an HTML structure.
+
+---
+
 ### `TinyHtml.query(selector)`
 Finds the first element by CSS selector.
 
 - **Parameters**:
   - `selector` *(string)* — CSS selector
-- **Returns**: `TinyHtml`
-- **Throws**: If no element is found.
+- **Returns**: `TinyHtml` or `null`
 
 ---
 
@@ -291,7 +372,9 @@ Finds all elements by CSS selector.
 ### `TinyHtml.getById(selector)`
 Selects an element by ID.
 
-- **Throws**: If no element is found.
+- **Parameters**:
+  - `selector` *(string)* — Id selector
+- **Returns**: `TinyHtml` or `null`
 
 ---
 
@@ -363,6 +446,8 @@ Each method below ensures type and returns raw DOM objects:
 | `_preEventTargetElem(...)`    | `EventTarget`    | `EventTarget`  |
 | `_preElemsAndWindow(...)`     | `Element\|Window` | `ElementAndWindow[]` |
 | `_preElemAndWindow(...)`      | `Element\|Window` | `ElementAndWindow` |
+| `_preElemsAndWinAndDoc(...)`     | `Element\|Window\|Document` | `ElementAndWindow[]` |
+| `_preElemAndWinAndDoc(...)`      | `Element\|Window\|Document` | `ElementAndWindow` |
 
 ---
 
@@ -662,6 +747,102 @@ Normalizes and converts input (elements, arrays, or strings) into appendable DOM
 
 ---
 
+## 🧮 Easing Functions
+
+### `TinyHtml.easings`
+
+A collection of predefined easing functions used for scroll and animation calculations.
+Each easing function takes a normalized time (`t` from 0 to 1) and returns a transformed progress value.
+
+| Name             | Description                           |
+| ---------------- | ------------------------------------- |
+| `linear`         | Constant speed, no easing.            |
+| `easeInQuad`     | Accelerates from zero velocity.       |
+| `easeOutQuad`    | Decelerates to zero velocity.         |
+| `easeInOutQuad`  | Accelerates, then decelerates.        |
+| `easeInCubic`    | Starts slow, speeds up sharply.       |
+| `easeOutCubic`   | Starts fast, slows down gradually.    |
+| `easeInOutCubic` | Smooth acceleration and deceleration. |
+
+```ts
+type Easings =
+  | 'linear'
+  | 'easeInQuad'
+  | 'easeOutQuad'
+  | 'easeInOutQuad'
+  | 'easeInCubic'
+  | 'easeOutCubic'
+  | 'easeInOutCubic';
+```
+
+```ts
+TinyHtml.easings = {
+  linear: (t) => t,
+  easeInQuad: (t) => t * t,
+  easeOutQuad: (t) => t * (2 - t),
+  easeInOutQuad: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+  easeInCubic: (t) => t * t * t,
+  easeOutCubic: (t) => --t * t * t + 1,
+  easeInOutCubic: (t) => (t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1),
+};
+```
+
+---
+
+## 🧭 Smooth Scrolling
+
+### `TinyHtml.scrollToXY(el, settings)`
+
+Smoothly scrolls one or more elements (or `window`) to a target position using a custom duration and easing.
+
+If no `duration` or invalid `easing` is provided, the scroll happens instantly.
+
+```ts
+TinyHtml.scrollToXY(el, {
+  targetX?: number,
+  targetY?: number,
+  duration?: number,
+  easing?: Easings,
+});
+```
+
+| Parameter            | Type                                             | Description                                                                                                                                        |
+| -------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `el`                 | `TinyElementAndWindow \| TinyElementAndWindow[]` | One or more elements or the `window` to scroll.                                                                                                    |
+| `settings`           | `Object`                                         | Scroll configuration.                                                                                                                              |
+| `targetX`            | `number` *(optional)*                            | Final horizontal scroll position.                                                                                                                  |
+| `targetY`            | `number` *(optional)*                            | Final vertical scroll position.                                                                                                                    |
+| `duration`           | `number` *(optional)*                            | Duration of the scroll animation in milliseconds.                                                                                                  |
+| `easing`             | `Easings` *(optional)*                           | Name of easing function to control animation curve.                                                                                                |
+| `onAnimation`        | `OnScrollAnimation` *(optional)*                 | Optional callback invoked on each animation frame with the current scroll position, normalized animation time (`0` to `1`), and a completion flag. |
+
+---
+
+## ⚙️ Internal Scroll Mechanism
+
+When called, `scrollToXY()` performs:
+
+1. **Start Position Detection** – Gets current scroll positions.
+2. **Delta Calculation** – Calculates the distance to scroll.
+3. **Easing Evaluation** – Determines the easing curve to use.
+4. **Scroll Loop** – Uses `requestAnimationFrame` to animate over time.
+5. **Instant Scroll Fallback** – If no easing/duration is defined, scrolls instantly.
+
+```ts
+function executeScroll(elem, newX, newY) {
+  if (elem instanceof Window) {
+    window.scrollTo(newX, newY);
+  } else if (elem.nodeType === 9) {
+    elem.defaultView.scrollTo(newX, newY); // For documents
+  } else {
+    if (elem.scrollLeft !== newX) elem.scrollLeft = newX;
+    if (elem.scrollTop !== newY) elem.scrollTop = newY;
+  }
+}
+```
+
+---
+
 ## 📏 Dimensions (Size API)
 
 TinyHtml provides methods to **read** and **set** an element's dimensions, similar to jQuery’s width/height API, with support for box models: `content`, `padding`, `border`, and `margin`.
@@ -738,6 +919,9 @@ This API set focuses on **measuring element offsets**, **scroll positions**, and
 
 ### 📍 Element Positioning
 
+#### `.animate(keyframes, ops?)` / `TinyHtml.animate(el, keyframes, ops?)`
+Applies an animation to one or more TinyElement instances using the Web Animations API.
+
 #### `.offset()` / `TinyHtml.offset(el)`
 Returns the coordinates `{ top, left }` of the element **relative to the document**.
 
@@ -949,10 +1133,12 @@ element.empty();
 
 ---
 
-### 🔍 `.html()` / `TinyHtml.html(el)`
+### 🔍 `.html(ops?)` / `TinyHtml.html(el, ops?)`
 
 Gets the `innerHTML` string of the element.
 
+* `ops?`: GetHTMLOptions from native DOM.
+
 ```js
 element.html(); // → "<p>Some HTML content</p>"
 ```
@@ -1334,6 +1520,108 @@ TinyHtml.isScrolledIntoView(element);
 
 ---
 
+### 🫣 `.isInContainer(container)`
+
+Partially Visible in Container
+
+```js
+element.isInContainer(container);
+```
+
+Checks if **any part** of the element is visible **inside the scrollable container** — meaning:
+
+* It **overlaps** the visible area of the container.
+* At least part of it is within the container’s viewport.
+
+#### ✅ Use when:
+
+* You want to detect if an element is **partially scrolled into view**.
+* Useful for triggering **lazy loading**, **animations**, or **UI changes** when something starts to appear.
+
+#### 🔍 Logic:
+
+* It compares the element's `getBoundingClientRect()` with the container’s.
+* Ensures there's **some overlap**, vertically or horizontally.
+
+#### 🔁 Static version:
+
+```js
+TinyHtml.isInContainer(element, container);
+```
+
+---
+
+### ✅ `.isFullyInContainer(container)`
+
+Fully Visible in Container
+
+```js
+element.isFullyInContainer(container);
+```
+
+Checks if the element is **completely visible** inside the scrollable container — meaning:
+
+* **Top and bottom** of the element are within the container.
+* **Left and right** are also inside the container’s boundaries.
+
+#### ✅ Use when:
+
+* You want to detect if an element is **entirely inside** its scrollable container.
+* Useful for triggering **lazy loading**, **animations**, or **UI changes** when something starts to appear.
+
+#### 🔍 Logic:
+
+* It compares the full bounding box of the element to the container's.
+* All four edges must be within bounds to return `true`.
+
+#### 🔁 Static version:
+
+```js
+TinyHtml.isFullyInContainer(element, container);
+```
+
+---
+
+### ✅ `.hasScroll()`
+
+Detect Scrollability in Any Direction
+
+```js
+element.hasScroll();
+```
+
+Checks if the element has **scrollable content** in either vertical or horizontal direction.
+
+Returns:
+
+```js
+{ v: true|false, h: true|false }
+```
+
+Where:
+
+* `v` = vertical scroll present
+* `h` = horizontal scroll present
+
+#### ✅ Use when:
+
+* You want to detect **whether an element needs scrollbars**.
+* Useful for adjusting layout, showing scroll indicators, or enabling custom scrolling behaviors.
+
+#### 🔍 Logic:
+
+* It compares the element's `scrollHeight` with `clientHeight` for vertical,
+* And `scrollWidth` with `clientWidth` for horizontal.
+* If content overflows in either direction, it returns `true` for that axis.
+
+#### 🔁 Static version:
+
+```js
+TinyHtml.hasScroll(element);
+```
+
+---
+
 ## 🎨 CSS Property Aliases (`cssPropAliases`)
 
 TinyHtml provides automatic conversion between `camelCase` and `kebab-case` style properties to simplify working with inline styles in HTML elements.