tiny-essentials 1.10.2 → 1.12.0

package/docs/v1/basics/html.md

@@ -0,0 +1,243 @@
+## 🚀 `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.
+
+---
+
+## 📖 `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.
+
+### 📥 Parameters
+
+* `file` *(File)*: The file object selected by the user (e.g., from an `<input type="file">` element).
+
+### 📤 Returns
+
+* `Promise<any>`: Resolves with the parsed JSON object, or rejects with an error if the content is invalid.
+
+### ⚠️ Throws
+
+* An error if the content is not valid JSON.
+* An error if the file can't be read.
+
+### 🧪 Example
+
+```js
+const input = document.querySelector('input[type="file"]');
+input.addEventListener('change', async () => {
+  try {
+    const result = await readJsonBlob(input.files[0]);
+    console.log(result);
+  } catch (err) {
+    alert(err.message);
+  }
+});
+```
+
+---
+
+## 💾 `saveJsonFile(filename: string, data: any, spaces: number = 2): void`
+
+Converts a JavaScript object to JSON and triggers a download in the browser.
+
+### 📥 Parameters
+
+* `filename` *(string)*: The name of the file to save (e.g., `"data.json"`).
+* `data` *(any)*: The JavaScript object to convert to JSON.
+* `spaces` *(number)* *(optional)*: Indentation level for formatting the JSON string. Default is `2`.
+
+### 📤 Returns
+
+* `void`
+
+### 📂 Behavior
+
+Creates a temporary `<a>` element, downloads the file, and cleans up the URL.
+
+### 🧪 Example
+
+```js
+const data = { name: 'Yasmin', type: 'dev' };
+saveJsonFile('yasmin.json', data);
+```
+
+## 🌐 `fetchJson(url, options?): Promise<any>`
+
+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.
+
+### 📥 Parameters
+
+* `url` *(string)*: The full URL to fetch JSON from (must start with `http://`, `https://`, `/`, `./`, or `../`).
+* `options` *(object)* *(optional)*:
+
+  * `signal` *(`AbortSignal` | `null`)*: Custom abort signal.
+  * `method` *(string)*: The HTTP method to use (e.g., `GET`, `POST`, `PUT`, `DELETE`, etc.).
+  * `timeout` *(number)*: Request timeout in milliseconds. Default is `0` (no timeout).
+  * `retries` *(number)*: Number of retry attempts if the request fails. Default is `0`.
+  * `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.
+
+#### `signal` (`AbortSignal` | `null`) — *optional*
+
+Custom abort signal. If set:
+
+* The internal timeout mechanism is **disabled**
+* Retry logic is **disabled**
+* Abortion is handled externally
+
+### 📤 Returns
+
+* `Promise<any>`: Resolves with the parsed JSON data.
+
+### ⚠️ 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
+
+## 🧠 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).
+
+### 🧪 Example
+
+```js
+const controller = new AbortController();
+
+const data = await fetchJson('https://api.example.com/data', {
+  method: 'POST',
+  body: { name: 'Yasmin' },
+  headers: {
+    'Content-Type': 'application/json'
+  },
+  timeout: 5000,
+  retries: 2,
+  signal: controller.signal, // optional
+});
+```
+
+---
+
+### 📦 `HtmlElBoxSides` Type
+
+```ts
+type HtmlElBoxSides = {
+  x: number;      // Total horizontal size (left + right)
+  y: number;      // Total vertical size (top + bottom)
+  left: number;
+  right: number;
+  top: number;
+  bottom: number;
+}
+```
+
+A common return format used to describe the box model dimensions (borders, padding, margin) of an HTML element.
+
+---
+
+### 🔲 `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.

package/docs/{basics → v1/basics}/text.md

@@ -123,7 +123,7 @@ document.addEventListener('DOMContentLoaded', () => {
 
 You can use a pre-built CSS template for the `detect-made-by-ai` class, available in the following files:
 
-* `/dist/aiMarker.min.css` – A minified version of the CSS for production use.
-* `/dist/aiMarker.css` – The non-minified version for easier readability and customization.
+* `/dist/v1/css/aiMarker.min.css` – A minified version of the CSS for production use.
+* `/dist/v1/css/aiMarker.css` – The non-minified version for easier readability and customization.
 
 Simply include the appropriate file in your project to style the elements marked with the `detect-made-by-ai` class.

package/docs/v1/libs/TinyDragDropDetector.md

@@ -0,0 +1,143 @@
+# 📥 TinyDragDropDetector
+
+A lightweight JavaScript utility for detecting drag-and-drop file operations on a specific DOM element or the entire page. It manages the full drag lifecycle (`enter`, `over`, `leave`, `drop`) and provides hooks for handling UI changes or file uploads.
+
+---
+
+## 📦 Features
+
+* Simple and lightweight.
+* Full drag event lifecycle handling.
+* CSS hover class management.
+* Works on any DOM element or the entire page.
+* Fully typed with JSDoc.
+* Safe with robust error handling.
+
+---
+
+## 🔧 Usage Example
+
+```javascript
+import TinyDragDropDetector from './TinyDragDropDetector.js';
+
+const dnd = new TinyDragDropDetector({
+  fullscreen: false,
+  target: document.getElementById('drop-area'),
+  hoverClass: 'hover-effect',
+  onDrop: (files, event) => {
+    console.log('Files dropped:', files);
+  },
+  onEnter: (event) => {
+    console.log('Drag entered');
+  },
+  onLeave: (event) => {
+    console.log('Drag left');
+  },
+});
+
+// Destroy when not needed
+// dnd.destroy();
+```
+
+---
+
+## 🔗 API Reference
+
+### Class: `TinyDragDropDetector`
+
+A drag-and-drop detector instance.
+
+### Constructor
+
+```javascript
+new TinyDragDropDetector(options)
+```
+
+#### Parameters:
+
+| Name      | Type                                        | Default | Description           |
+| --------- | ------------------------------------------- | ------- | --------------------- |
+| `options` | [`DragAndDropOptions`](#draganddropoptions) | `{}`    | Configuration object. |
+
+#### Throws:
+
+* `TypeError` if `target` is not an `HTMLElement`.
+* `TypeError` if `fullscreen` is not a boolean.
+* `TypeError` if `hoverClass` is not a string.
+* `TypeError` if `onDrop` is not a function.
+* `TypeError` if `onEnter` is defined but not a function.
+* `TypeError` if `onLeave` is defined but not a function.
+
+---
+
+### Instance Methods
+
+| Method            | Returns       | Description                                                              |
+| ----------------- | ------------- | ------------------------------------------------------------------------ |
+| `getTarget()`     | `HTMLElement` | Returns the DOM element where listeners are attached.                    |
+| `getHoverClass()` | `string`      | Returns the CSS class applied during drag hover.                         |
+| `isFullScreen()`  | `boolean`     | Indicates whether the detector is in fullscreen mode (`document.body`).  |
+| `isDragging()`    | `boolean`     | Returns whether a drag operation is currently active over the target.    |
+| `bound()`         | `boolean`     | Returns whether the event listeners are currently bound to the target.   |
+| `destroy()`       | `void`        | Destroys the detector, unbinding all events and cleaning up CSS classes. |
+
+---
+
+## 🏗️ Event Callbacks
+
+| Event     | Signature                                     | Description                                 |
+| --------- | --------------------------------------------- | ------------------------------------------- |
+| `onDrop`  | `(files: FileList, event: DragEvent) => void` | Fired when files are dropped. **Required**. |
+| `onEnter` | `(event: DragEvent) => void`                  | Fired when dragging enters the target.      |
+| `onLeave` | `(event: DragEvent) => void`                  | Fired when dragging leaves the target.      |
+
+---
+
+## 🛠️ DragAndDropOptions
+
+```javascript
+/**
+ * @typedef {Object} DragAndDropOptions
+ * @property {HTMLElement} [target=document.body] - The DOM element where drag listeners will be attached. Defaults to `document.body` if `fullscreen` is true or no target is provided.
+ * @property {boolean} [fullscreen=true] - If true, listeners are attached to the entire page (`document.body`). If false, the `target` must be specified.
+ * @property {string} [hoverClass="dnd-hover"] - CSS class applied to the target element while files are being dragged over it.
+ * @property {(files: FileList, event: DragEvent) => void} onDrop - Callback function executed when files are dropped onto the target.
+ * @property {(event: DragEvent) => void} [onEnter] - Optional callback triggered when dragging enters the target area.
+ * @property {(event: DragEvent) => void} [onLeave] - Optional callback triggered when dragging leaves the target area.
+ */
+```
+
+---
+
+## ⚠️ Warnings
+
+* If `dataTransfer` is missing in a `dragover` or `drop` event, a console warning will be shown:
+
+  * `[TinyDragDropDetector] [handleDragOver] DragOver event missing dataTransfer.`
+  * `[TinyDragDropDetector] [handleDrop] Drop event missing dataTransfer.`
+
+This is a safe check to prevent runtime errors in malformed events.
+
+---
+
+## 🗑️ Cleanup
+
+Call `destroy()` when the detector is no longer needed to prevent memory leaks:
+
+```javascript
+dnd.destroy();
+```
+
+This unbinds all event listeners and removes the hover class if applied.
+
+---
+
+## 🎨 CSS Example
+
+```css
+/* Example hover effect */
+.hover-effect {
+  outline: 3px dashed #4caf50;
+  background-color: rgba(76, 175, 80, 0.1);
+}
+```