tiny-essentials 1.15.0 → 1.16.1

package/dist/v1/libs/TinyUploadClicker.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var objFilter = require('../basics/objFilter.cjs');
+require('./TinyHtml.cjs');
 require('fs');
 require('path');
 require('fs/promises');

package/docs/v1/README.md

@@ -12,15 +12,15 @@ Here, you can navigate through different sections of the project. Below are the
 
 This folder contains the core scripts we have worked on so far. Each file is a module focused on specific functionality.
 
-- 📦 **[array](./basics/array.md)** — A tiny utility for shuffling arrays using the Fisher–Yates algorithm.
-- ⏰ **[clock](./basics/clock.md)** — A versatile time utility module for calculating and formatting time durations.
-- 🧠 **[objFilter](./basics/objFilter.md)** — Type detection, extension, and analysis made easy with simple and extensible type validation.
-- 🔢 **[simpleMath](./basics/simpleMath.md)** — A collection of simple math utilities for calculations like the Rule of Three and percentages.
-- ✍️ **[text](./basics/text.md)** — A utility for transforming text into title case formats, with multiple options for capitalization.
-- 🔄 **[asyncReplace](./basics/asyncReplace.md)** — Asynchronously replaces matches in a string using a regex and an async function.
-- 🖼️ **[html](./basics/html.md)** — Utilities for handling DOM element interactions like collision detection and basic element manipulation.
-- 📺 **[fullScreen](./basics/fullScreen.md)** — A complete fullscreen API manager with detection, event handling, and cross-browser compatibility.
-- 🧱 **[collision](./basics/collision.md)** — Full-featured rectangle collision detection system with directional analysis, depth calculation, and center offset metrics.
+- 📦 **[Array](./basics/array.md)** — A tiny utility for shuffling arrays using the Fisher–Yates algorithm.
+- ⏰ **[Clock](./basics/clock.md)** — A versatile time utility module for calculating and formatting time durations.
+- 🧠 **[ObjFilter](./basics/objFilter.md)** — Type detection, extension, and analysis made easy with simple and extensible type validation.
+- 🔢 **[SimpleMath](./basics/simpleMath.md)** — A collection of simple math utilities for calculations like the Rule of Three and percentages.
+- ✍️ **[Text](./basics/text.md)** — A utility for transforming text into title case formats, with multiple options for capitalization.
+- 🔄 **[AsyncReplace](./basics/asyncReplace.md)** — Asynchronously replaces matches in a string using a regex and an async function.
+- 🖼️ **[Html](./basics/html.md)** — Utilities for handling DOM element interactions like collision detection and basic element manipulation.
+- 📺 **[FullScreen](./basics/fullScreen.md)** — A complete fullscreen API manager with detection, event handling, and cross-browser compatibility.
+- 🧱 **[Collision](./basics/collision.md)** — Full-featured rectangle collision detection system with directional analysis, depth calculation, and center offset metrics.
 
 ### 2. **`libs/`**
 - 🗂️ **[TinyPromiseQueue](./libs/TinyPromiseQueue.md)** — A class that allows sequential execution of asynchronous tasks, supporting task delays, cancellation, and queue management.
@@ -34,9 +34,10 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🧲 **[TinyDragger](./libs/TinyDragger.md)** — A flexible drag-and-drop manager with collision detection, jail constraints, vibration feedback, visual proxies, revert-on-drop, and full custom event support.
 - 🕒 **[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.
 
 ### 3. **`fileManager/`**
-* 📁 **[main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.
+* 📁 **[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

@@ -1,55 +1,3 @@
-### 🚀 `areHtmlElsColliding()`
-
-Check if two DOM elements are **colliding on the screen**! Perfect for games, draggable elements, UI interactions, and more.
-
-This function checks whether **two HTML elements are overlapping** (colliding) within the viewport. It uses their bounding boxes (`getBoundingClientRect()`) to perform a simple AABB (Axis-Aligned Bounding Box) collision detection.
-
-Combine it with `mousemove`, `drag`, or animation listeners for dynamic collision detection in real-time!
-
-It compares the bounding rectangles of both elements:
-
-* ✅ Checks if **rect1** is NOT entirely to the left, right, above, or below **rect2**.
-* ✅ If none of these are true, then the elements are overlapping.
-
-#### 🧠 Syntax
-
-```javascript
-areHtmlElsColliding(elem1, elem2);
-```
-
-#### 🎯 Parameters
-
-| Parameter | Type      | Description             |
-| --------- | --------- | ----------------------- |
-| `elem1`   | `Element` | The first DOM element.  |
-| `elem2`   | `Element` | The second DOM element. |
-
-#### 🔁 Return
-
-| Type      | Description                                                        |
-| --------- | ------------------------------------------------------------------ |
-| `boolean` | ✅ `true` if elements are colliding. <br>❌ `false` if they are not. |
-
-#### 📦 Example
-
-```javascript
-const box1 = document.getElementById('box1');
-const box2 = document.getElementById('box2');
-
-if (areHtmlElsColliding(box1, box2)) {
-  console.log('🎯 Collision detected!');
-} else {
-  console.log('❌ No collision.');
-}
-```
-
-#### 🚧 Limitations
-
-* Only works with **axis-aligned elements** (rectangular shapes).
-* Does not handle rotated elements or complex shapes.
-
----
-
 ### 📖 `readBase64Blob(file: File, isDataUrl?: boolean | string): Promise<string>`
 
 Reads a file and returns its Base64 content using the FileReader API, with optional formatting as a full Data URL.
@@ -266,84 +214,6 @@ A common return format used to describe the box model dimensions (borders, paddi
 
 ---
 
-### 🔲 `getHtmlElBordersWidth(el)`
-
-📏 Returns the total **border width** of an element using `border{Side}Width` values from computed styles.
-
-```js
-getHtmlElBordersWidth(el: Element): HtmlElBoxSides
-```
-
-* `el`: The target DOM element.
-* **Returns**: An object containing total horizontal/vertical border widths, and each side individually.
-
----
-
-### 👁️ `isInViewport(element)`
-
-🔍 Checks if an element is **partially visible** in the current viewport.
-
-```js
-isInViewport(element: HTMLElement): boolean
-```
-
-* `element`: The DOM element to check.
-* **Returns**: `true` if the element is at least partially visible; `false` otherwise.
-
----
-
-### ✅ `isScrolledIntoView(element)`
-
-📦 Checks if an element is **fully visible** (top and bottom) within the viewport.
-
-```js
-isScrolledIntoView(element: HTMLElement): boolean
-```
-
-* `element`: The DOM element to check.
-* **Returns**: `true` if the entire element is within the viewport; `false` otherwise.
-
----
-
-### 🔳 `getHtmlElBorders(el)`
-
-📐 Returns the total **border size** of an element using `border{Side}` shorthand values from computed styles.
-
-```js
-getHtmlElBorders(el: Element): HtmlElBoxSides
-```
-
-* `el`: The target DOM element.
-* **Returns**: An object with total horizontal/vertical border sizes and all four sides.
-
----
-
-### ➖ `getHtmlElMargin(el)`
-
-📏 Returns the total **margin** of an element using `margin{Side}` from computed styles.
-
-```js
-getHtmlElMargin(el: Element): HtmlElBoxSides
-```
-
-* `el`: The target DOM element.
-* **Returns**: An object containing margin values for each side and totals for horizontal (`x`) and vertical (`y`).
-
----
-
-### ➕ `getHtmlElPadding(el)`
-
-🧩 Returns the total **padding** of an element using `padding{Side}` from computed styles.
-
-```js
-getHtmlElPadding(el: Element): HtmlElBoxSides
-```
-
-* `el`: The target DOM element.
-* **Returns**: Padding values for all sides and summed horizontal (`x`) and vertical (`y`) values.
-
----
-
 ### 📄 `installWindowHiddenScript`
 
 Automatically toggles CSS classes on a given element based on the browser window or tab **visibility** and **focus** state.

package/docs/v1/basics/html_deprecated.md

@@ -0,0 +1,127 @@
+### 🚀 `areHtmlElsColliding()`
+
+Check if two DOM elements are **colliding on the screen**! Perfect for games, draggable elements, UI interactions, and more.
+
+This function checks whether **two HTML elements are overlapping** (colliding) within the viewport. It uses their bounding boxes (`getBoundingClientRect()`) to perform a simple AABB (Axis-Aligned Bounding Box) collision detection.
+
+Combine it with `mousemove`, `drag`, or animation listeners for dynamic collision detection in real-time!
+
+It compares the bounding rectangles of both elements:
+
+* ✅ Checks if **rect1** is NOT entirely to the left, right, above, or below **rect2**.
+* ✅ If none of these are true, then the elements are overlapping.
+
+#### 🧠 Syntax
+
+```javascript
+areHtmlElsColliding(elem1, elem2);
+```
+
+#### 🎯 Parameters
+
+| Parameter | Type      | Description             |
+| --------- | --------- | ----------------------- |
+| `elem1`   | `Element` | The first DOM element.  |
+| `elem2`   | `Element` | The second DOM element. |
+
+#### 🔁 Return
+
+| Type      | Description                                                        |
+| --------- | ------------------------------------------------------------------ |
+| `boolean` | ✅ `true` if elements are colliding. <br>❌ `false` if they are not. |
+
+#### 📦 Example
+
+```javascript
+const box1 = document.getElementById('box1');
+const box2 = document.getElementById('box2');
+
+if (areHtmlElsColliding(box1, box2)) {
+  console.log('🎯 Collision detected!');
+} else {
+  console.log('❌ No collision.');
+}
+```
+
+#### 🚧 Limitations
+
+* Only works with **axis-aligned elements** (rectangular shapes).
+* Does not handle rotated elements or complex shapes.
+
+---
+
+### 🔲 `getHtmlElBordersWidth(el)`
+
+📏 Returns the total **border width** of an element using `border{Side}Width` values from computed styles.
+
+```js
+getHtmlElBordersWidth(el: Element): HtmlElBoxSides
+```
+
+* `el`: The target DOM element.
+* **Returns**: An object containing total horizontal/vertical border widths, and each side individually.
+
+---
+
+### 🔳 `getHtmlElBorders(el)`
+
+📐 Returns the total **border size** of an element using `border{Side}` shorthand values from computed styles.
+
+```js
+getHtmlElBorders(el: Element): HtmlElBoxSides
+```
+
+* `el`: The target DOM element.
+* **Returns**: An object with total horizontal/vertical border sizes and all four sides.
+
+---
+
+### ➖ `getHtmlElMargin(el)`
+
+📏 Returns the total **margin** of an element using `margin{Side}` from computed styles.
+
+```js
+getHtmlElMargin(el: Element): HtmlElBoxSides
+```
+
+* `el`: The target DOM element.
+* **Returns**: An object containing margin values for each side and totals for horizontal (`x`) and vertical (`y`).
+
+---
+
+### ➕ `getHtmlElPadding(el)`
+
+🧩 Returns the total **padding** of an element using `padding{Side}` from computed styles.
+
+```js
+getHtmlElPadding(el: Element): HtmlElBoxSides
+```
+
+* `el`: The target DOM element.
+* **Returns**: Padding values for all sides and summed horizontal (`x`) and vertical (`y`) values.
+
+---
+
+### 👁️ `isInViewport(element)`
+
+🔍 Checks if an element is **partially visible** in the current viewport.
+
+```js
+isInViewport(element: HTMLElement): boolean
+```
+
+* `element`: The DOM element to check.
+* **Returns**: `true` if the element is at least partially visible; `false` otherwise.
+
+---
+
+### ✅ `isScrolledIntoView(element)`
+
+📦 Checks if an element is **fully visible** (top and bottom) within the viewport.
+
+```js
+isScrolledIntoView(element: HTMLElement): boolean
+```
+
+* `element`: The DOM element to check.
+* **Returns**: `true` if the entire element is within the viewport; `false` otherwise.

package/docs/v1/libs/TinyAfterScrollWatcher.md

@@ -0,0 +1,181 @@
+# 📜 TinyAfterScrollWatcher
+
+A minimalistic scroll watcher that queues and executes functions **after scrolling has stopped** on a given element or the window.
+Perfect for optimizing logic that should only run **after** the user has finished scrolling.
+
+---
+
+## 🚀 Features
+
+* ✅ 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`)
+* 🧹 Cleanly destroy the instance when no longer needed
+
+---
+
+## 📦 Import
+
+```js
+import TinyAfterScrollWatcher from './TinyAfterScrollWatcher.mjs';
+```
+
+---
+
+## 🧪 Example
+
+```js
+const watcher = new TinyAfterScrollWatcher(window);
+
+// Optional: set a custom delay (in ms)
+watcher.inactivityTime = 300;
+
+// Add a function to run after scroll has stopped
+watcher.doAfterScroll(() => {
+  console.log('Scroll has stopped for 300ms!');
+});
+
+// Add a custom scroll listener
+const myScrollHandler = () => console.log('Scrolling...');
+watcher.onScroll(myScrollHandler);
+
+// Remove it later
+watcher.offScroll(myScrollHandler);
+
+// Fully destroy the watcher
+watcher.destroy();
+```
+
+---
+
+## 🧠 Class: `TinyAfterScrollWatcher`
+
+### 🔧 Constructor
+
+```ts
+new TinyAfterScrollWatcher(scrollTarget?: Element | Window, inactivityTime?: number)
+```
+
+#### Parameters:
+
+| Name             | Type                | Default  | Description                                                            |
+| ---------------- | ------------------- | -------- | ---------------------------------------------------------------------- |
+| `scrollTarget`   | `Element \| Window` | `window` | The scrollable element to watch. Can also be the global `window`.      |
+| `inactivityTime` | `number`            | `100`    | Milliseconds to wait after the last scroll before executing the queue. |
+
+---
+
+### ⏲️ Property: `inactivityTime`
+
+* **Type:** `number`
+* **Getter/Setter**
+
+Defines how many milliseconds to wait after scroll stops before executing the queue.
+
+#### Example:
+
+```js
+watcher.inactivityTime = 500;
+console.log(watcher.inactivityTime); // 500
+```
+
+#### Throws:
+
+* `TypeError` if the value is not a finite positive number.
+
+---
+
+### 🧩 Method: `doAfterScroll(fn)`
+
+Adds a function to the queue that runs once scroll has stopped for the configured delay.
+
+```ts
+doAfterScroll(fn: FnData): void
+```
+
+#### Parameters:
+
+| Name | Type     | Description                          |
+| ---- | -------- | ------------------------------------ |
+| `fn` | `FnData` | Function to run after scrolling ends |
+
+#### Throws:
+
+* `TypeError` if the argument is not a function.
+
+---
+
+### 🧷 Method: `onScroll(fn)`
+
+Registers a custom scroll listener on the tracked element.
+
+```ts
+onScroll(fn: OnScrollFunc): void
+```
+
+#### Parameters:
+
+| Name | Type           | Description                             |
+| ---- | -------------- | --------------------------------------- |
+| `fn` | `OnScrollFunc` | The listener function for scroll events |
+
+#### Throws:
+
+* `TypeError` if the argument is not a function.
+
+---
+
+### 🗑️ Method: `offScroll(fn)`
+
+Removes a previously registered scroll listener.
+
+```ts
+offScroll(fn: OnScrollFunc): void
+```
+
+#### Parameters:
+
+| Name | Type           | Description                   |
+| ---- | -------------- | ----------------------------- |
+| `fn` | `OnScrollFunc` | The scroll listener to remove |
+
+#### Throws:
+
+* `TypeError` if the argument is not a function.
+
+---
+
+### 💣 Method: `destroy()`
+
+Cleans up all internal and external listeners.
+Once destroyed, the instance stops functioning and cannot be reused.
+
+```ts
+destroy(): void
+```
+
+---
+
+## 🧾 Typedefs
+
+```ts
+/**
+ * A function with no parameters and no return value.
+ */
+type FnData = () => void;
+
+/**
+ * A function that handles a scroll event.
+ * It receives a standard `Event` object when a scroll occurs.
+ */
+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

package/docs/v1/libs/TinyDragger.md

@@ -42,21 +42,23 @@ new TinyDragger(targetElement, options?)
 
 ### Options:
 
-| Option                  | Type                           | Default                | Description                                              |
-| ----------------------- | ------------------------------ | ---------------------- | -------------------------------------------------------- |
-| `jail`                  | `HTMLElement`                  | `null`                 | Optional container that restricts movement               |
-| `collisionByMouse`      | `boolean`                      | `false`                | Use mouse position instead of bounding box for collision |
-| `classDragging`         | `string`                       | `'dragging'`           | Class applied to the clone element                       |
-| `classBodyDragging`     | `string`                       | `'drag-active'`        | Class applied to the `<body>` during dragging            |
-| `classJailDragging`     | `string`                       | `'jail-drag-active'`   | Class applied to jail while dragging                     |
-| `classJailDragDisabled` | `string`                       | `'jail-drag-disabled'` | Class applied to jail when dragging is disabled          |
-| `classDragCollision`    | `string`                       | `'dragging-collision'` | Class applied to elements when collision is detected     |
-| `classHidden`           | `string`                       | `'drag-hidden'`        | Class used to hide the original element while dragging   |
-| `lockInsideJail`        | `boolean`                      | `false`                | Prevent drag from exceeding jail bounds                  |
-| `dropInJailOnly`        | `boolean`                      | `false`                | Prevent drop outside the jail area                       |
-| `multiCollision`        | `boolean`                      | `false`                | Enables returning multiple collided elements             |
-| `vibration`             | `VibrationPatterns` or `false` | `false`                | Vibration feedback configuration                         |
-| `revertOnDrop`          | `boolean`                      | `false`                | Return to original position after dropping               |
+| Option                  | Type                           | Default                | Description                                                 |
+| ----------------------- | ------------------------------ | ---------------------- | ----------------------------------------------------------- |
+| `jail`                  | `HTMLElement`                  | `null`                 | Optional container that restricts movement                  |
+| `collisionByMouse`      | `boolean`                      | `false`                | Use mouse position instead of bounding box for collision    |
+| `classDragging`         | `string`                       | `'dragging'`           | Class applied to the clone element                          |
+| `classBodyDragging`     | `string`                       | `'drag-active'`        | Class applied to the `<body>` during dragging               |
+| `classJailDragging`     | `string`                       | `'jail-drag-active'`   | Class applied to jail while dragging                        |
+| `classJailDragDisabled` | `string`                       | `'jail-drag-disabled'` | Class applied to jail when dragging is disabled             |
+| `classDragCollision`    | `string`                       | `'dragging-collision'` | Class applied to elements when collision is detected        |
+| `classHidden`           | `string`                       | `'drag-hidden'`        | Class used to hide the original element while dragging      |
+| `lockInsideJail`        | `boolean`                      | `false`                | Prevent drag from exceeding jail bounds                     |
+| `dropInJailOnly`        | `boolean`                      | `false`                | Prevent drop outside the jail area                          |
+| `multiCollision`        | `boolean`                      | `false`                | Enables returning multiple collided elements                |
+| `vibration`             | `VibrationPatterns` or `false` | `false`                | Vibration feedback configuration                            |
+| `revertOnDrop`          | `boolean`                      | `false`                | Return to original position after dropping                  |
+| `mirrorElem`            | `boolean`                      | `true`                 | Use a visual clone instead of dragging the original element |
+| `defaultZIndex`         | `number`                       | `9999`                 | Sets the z-index value applied when dragging starts         |
 
 ---
 
@@ -334,6 +336,34 @@ Returns `null` if no proxy is active.
 
 ---
 
+### `getDefaultZIndex(): number`
+
+🎯 Returns the current default `z-index` used when a draggable item is picked up.
+
+---
+
+### `setDefaultZIndex(newZIndex: number): void`
+
+🛠️ Sets a new default `z-index` to be used during drag operations.
+
+> Throws `TypeError` if `newZIndex` is not a finite number.
+
+---
+
+### `isMirrorEnabled(): boolean`
+
+🎯 Returns whether the draggable element uses a **mirror** (`true`) or the **original element** (`false`) during dragging.
+
+---
+
+### `setMirrorEnabled(useMirror: boolean): void`
+
+🛠️ Defines whether the draggable element should use a **mirror clone** or move the **original element**.
+
+> Throws `TypeError` if `useMirror` is not a boolean.
+
+---
+
 ## 🔁 Events
 
 The target element will emit these events: