tiny-essentials 1.16.1 → 1.17.0

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/TinyAfterScrollWatcher.md

@@ -10,7 +10,8 @@ Perfect for optimizing logic that should only run **after** the user has finishe
 * ✅ Works on any scrollable element or the window
 * ⏱️ Customizable "inactivity timeout" (default: `100ms`)
 * 🧠 Executes queued callbacks after scroll ends
-* 🧩 Add/remove your own scroll listeners easily (`onScroll` / `offScroll`)
+* 🧷 Add/remove scroll listeners easily (`onScroll` / `offScroll`)
+* 🛑 Execute logic right before after-scroll queue (`onStop`)
 * 🧹 Cleanly destroy the instance when no longer needed
 
 ---
@@ -36,6 +37,11 @@ watcher.doAfterScroll(() => {
   console.log('Scroll has stopped for 300ms!');
 });
 
+// Add a function to run immediately when scroll stops
+watcher.onStop(() => {
+  console.log('User just stopped scrolling!');
+});
+
 // Add a custom scroll listener
 const myScrollHandler = () => console.log('Scrolling...');
 watcher.onScroll(myScrollHandler);
@@ -43,6 +49,9 @@ watcher.onScroll(myScrollHandler);
 // Remove it later
 watcher.offScroll(myScrollHandler);
 
+// Also remove onStop listener
+watcher.offStop(myStopFunction);
+
 // Fully destroy the watcher
 watcher.destroy();
 ```
@@ -106,6 +115,46 @@ doAfterScroll(fn: FnData): void
 
 ---
 
+### 🛑 Method: `onStop(fn)`
+
+Registers a function to be called **immediately after scrolling stops**, but **before** the `doAfterScroll` queue is executed.
+
+```ts
+onStop(fn: FnData): void
+```
+
+#### Parameters:
+
+| Name | Type     | Description                                     |
+| ---- | -------- | ----------------------------------------------- |
+| `fn` | `FnData` | Function to call as soon as scroll has stopped. |
+
+#### Throws:
+
+* `TypeError` if the argument is not a function.
+
+---
+
+### 🔁 Method: `offStop(fn)`
+
+Removes a function previously registered with `onStop`.
+
+```ts
+offStop(fn: FnData): void
+```
+
+#### Parameters:
+
+| Name | Type     | Description                        |
+| ---- | -------- | ---------------------------------- |
+| `fn` | `FnData` | Function to remove from onStop set |
+
+#### Throws:
+
+* `TypeError` if the argument is not a function.
+
+---
+
 ### 🧷 Method: `onScroll(fn)`
 
 Registers a custom scroll listener on the tracked element.
@@ -176,6 +225,7 @@ type OnScrollFunc = (ev: Event) => void;
 
 ## 📝 Notes
 
-* The scroll queue is **LIFO** (last-in, first-out)
-* The internal check loop uses `requestAnimationFrame`, so it's efficient
-* Setting `inactivityTime` to a lower value makes it more sensitive
+* `onStop` functions are called **before** the `doAfterScroll` queue.
+* The `doAfterScroll` queue runs in **LIFO** order (last-in, first-out).
+* `requestAnimationFrame` is used for efficient polling.
+* Lower `inactivityTime` makes scroll-stop detection more responsive.

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` |
 
 ---
 
@@ -949,10 +1034,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 +1421,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.