tiny-essentials 1.14.0 → 1.16.0

package/docs/v1/README.md

@@ -20,6 +20,7 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🔄 **[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.
@@ -33,6 +34,7 @@ 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.

package/docs/v1/basics/collision.md

@@ -0,0 +1,237 @@
+# 📦 Collision Detection Module
+
+This module provides a complete and flexible system for detecting collisions between rectangles (like DOM elements), extracting direction, depth, and center alignment data.
+
+---
+
+## 📐 Type Definitions
+
+### `Dirs`
+
+```ts
+'top' | 'bottom' | 'left' | 'right'
+```
+
+🔁 A direction relative to a rectangle. Represents one of the four cardinal sides.
+
+---
+
+### `CollDirs`
+
+```ts
+{
+  in: Dirs | 'center' | null;
+  x: Dirs | null;
+  y: Dirs | null;
+}
+```
+
+🚦 Represents all directional aspects of a collision:
+
+* `in`: Dominant entry direction (`null` if no collision, `'center'` if perfectly aligned).
+* `x`: Collision bias on X axis.
+* `y`: Collision bias on Y axis.
+
+---
+
+### `NegCollDirs`
+
+```ts
+{
+  x: Dirs | null;
+  y: Dirs | null;
+}
+```
+
+❌ Negative collision flags indicating **gap** instead of overlap.
+
+---
+
+### `CollData`
+
+```ts
+{
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+```
+
+📏 Collision depth (in pixels) from each side of `rect2` into `rect1`.
+
+* Positive values = overlap
+* Negative values = no collision (gap)
+
+---
+
+### `CollCenter`
+
+```ts
+{
+  x: number;
+  y: number;
+}
+```
+
+🎯 Offset from the center of `rect1` to the center of `rect2`.
+
+---
+
+### `ObjRect`
+
+```ts
+{
+  height: number;
+  width: number;
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+```
+
+📦 Generic rectangle object, similar to `DOMRect`.
+
+---
+
+## 🔍 Collision Checks
+
+### Loose Collision (Partial Overlap Only)
+
+| Function                         | Description                             |
+| -------------------------------- | --------------------------------------- |
+| `areElsCollTop(rect1, rect2)`    | `rect1` is **above** `rect2`            |
+| `areElsCollBottom(rect1, rect2)` | `rect1` is **below** `rect2`            |
+| `areElsCollLeft(rect1, rect2)`   | `rect1` is **left of** `rect2`          |
+| `areElsCollRight(rect1, rect2)`  | `rect1` is **right of** `rect2`         |
+| `areElsColliding(rect1, rect2)`  | Returns `true` if **any side overlaps** |
+
+---
+
+### Perfect Collision (Touch or Overlap)
+
+| Function                             | Description                                        |
+| ------------------------------------ | -------------------------------------------------- |
+| `areElsCollPerfTop(rect1, rect2)`    | `rect1` is **fully above** or touching `rect2`     |
+| `areElsCollPerfBottom(rect1, rect2)` | `rect1` is **fully below** or touching `rect2`     |
+| `areElsCollPerfLeft(rect1, rect2)`   | `rect1` is **fully left** or touching `rect2`      |
+| `areElsCollPerfRight(rect1, rect2)`  | `rect1` is **fully right** or touching `rect2`     |
+| `areElsPerfColliding(rect1, rect2)`  | Returns `true` if there's **any overlap or touch** |
+
+---
+
+### Collision Direction (Single Side Detection)
+
+| Function                            | Returns                                            |
+| ----------------------------------- | -------------------------------------------------- |
+| `getElsColliding(rect1, rect2)`     | `'left'`, `'right'`, `'top'`, `'bottom'` or `null` |
+| `getElsPerfColliding(rect1, rect2)` | Same as above, but includes **touch detection**    |
+
+---
+
+## 🔬 Overlap & Direction
+
+### `getElsCollOverlap(rect1, rect2)`
+
+📏 Returns the depth of overlap between two rectangles:
+
+```js
+{
+  overlapLeft,
+  overlapRight,
+  overlapTop,
+  overlapBottom
+}
+```
+
+---
+
+### `getElsCollOverlapPos({ overlapLeft, overlapRight, overlapTop, overlapBottom })`
+
+📍 Determines which axis and direction has the strongest collision.
+
+```js
+{
+  dirX: 'left' | 'right',
+  dirY: 'top' | 'bottom'
+}
+```
+
+---
+
+## 🎯 Center Detection
+
+### `getRectCenter(rect)`
+
+Returns the **center X and Y coordinates** of a rectangle.
+
+---
+
+### `getElsRelativeCenterOffset(rect1, rect2)`
+
+Returns the distance from `rect1`'s center to `rect2`'s center:
+
+```js
+{
+  x: number,
+  y: number
+}
+```
+
+✅ Values are `0` when centers are aligned.
+
+---
+
+## 🧠 Direction & Depth
+
+### `getElsCollDirDepth(rect1, rect2)`
+
+Detects:
+
+* Which axis has the dominant collision
+* Overlap depths
+
+```js
+{
+  inDir: 'left' | 'right' | 'top' | 'bottom' | null,
+  dirX: 'left' | 'right' | null,
+  dirY: 'top' | 'bottom' | null,
+  depthX: number,
+  depthY: number
+}
+```
+
+---
+
+### `getElsCollDetails(rect1, rect2)`
+
+🔍 Full analysis of the collision:
+
+* Depth of overlap
+* Direction of entry
+* Negative axis gaps
+* Center hit detection
+
+```js
+{
+  depth: CollData,
+  dirs: CollDirs,
+  isNeg: NegCollDirs
+}
+```
+
+---
+
+## 🧪 Example Use
+
+```js
+const box = element1.getBoundingClientRect();
+const wall = element2.getBoundingClientRect();
+
+const result = getElsCollDetails(box, wall);
+
+console.log(result.depth); // { top, bottom, left, right }
+console.log(result.dirs.in); // e.g. 'left'
+console.log(result.isNeg); // e.g. { x: 'left', y: null }
+```

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.
@@ -136,7 +84,7 @@ input.addEventListener('change', async () => {
 
 ### 📖 `readJsonBlob(file: File): Promise<any>`
 
-Reads and parses a JSON file using the [`FileReader`](https://developer.mozilla.org/en-US/docs/Web/API/FileReader) API.
+Reads and parses a JSON file using the FileReader API.
 
 #### 📥 Parameters
 
@@ -266,58 +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.
-
----
-
-### 🔳 `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/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: