tiny-essentials 1.11.0 → 1.12.1

package/docs/v1/README.md

@@ -18,14 +18,20 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🔢 **[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.
+* 📁 **[fileManager](./basics/fileManager.mjs.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.
 
 ### 2. **`libs/`**
 - 🗂️ **[TinyPromiseQueue](./libs/TinyPromiseQueue.md)** — A class that allows sequential execution of asynchronous tasks, supporting task delays, cancellation, and queue management.
 - 🏅 **[TinyLevelUp](./libs/TinyLevelUp.md)** — A class to manage user level-up logic based on experience points, providing methods for experience validation, addition, removal, and calculation.
 - 🎨 **[ColorSafeStringify](./libs/ColorSafeStringify.md)** — A utility for applying customizable ANSI colors to JSON strings in terminal outputs, supporting presets and fine-grained type-based highlighting.
 - 🚦 **[TinyRateLimiter](./libs/TinyRateLimiter.md)** — A flexible per-user rate limiter supporting time windows, hit caps, and automatic cleanup of inactive users.
-* 🔔 **[TinyNotifyCenter](./libs/TinyNotifyCenter.md)** — A dynamic notification center class to display, manage, and interact with notifications, supporting avatars, clickable items, HTML/text modes, and clean UI controls.
-* 🍞 **[TinyToastNotify](./libs/TinyToastNotify.md)** — A lightweight toast notification system supporting positioning, timing customization, avatars, click actions, and fade-out animations.
+- 🔔 **[TinyNotifyCenter](./libs/TinyNotifyCenter.md)** — A dynamic notification center class to display, manage, and interact with notifications, supporting avatars, clickable items, HTML/text modes, and clean UI controls.
+- 🍞 **[TinyToastNotify](./libs/TinyToastNotify.md)** — A lightweight toast notification system supporting positioning, timing customization, avatars, click actions, and fade-out animations.
+- 📥 **[TinyDragDropDetector](./libs/TinyDragDropDetector.md)** — A lightweight drag-and-drop detector for files, handling the full drag lifecycle (`enter`, `over`, `leave`, `drop`) with CSS hover management and safe event handling on any DOM element or the full page.
+* 📂 **[TinyUploadClicker](./libs/TinyUploadClicker.md)** — A minimal utility to bind any clickable element to a hidden file input, offering full control over styling, behavior, and upload event hooks.
+* 🧲 **[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.
 
 ---
 

package/docs/v1/basics/fileManager.md

@@ -0,0 +1,222 @@
+# 📁 Node.js File & Directory Utilities
+
+A powerful and flexible utility toolkit for managing files and directories in Node.js using `fs` and `path`. Includes support for JSON operations, text handling, backups, renaming strategies, and more!
+
+---
+
+## 📦 JSON Operations
+
+### `readJsonFile(filePath: string): any`
+
+📖 Reads and parses a JSON file.
+
+* Throws an error if the file doesn't exist or contains invalid JSON.
+* Async version: `readJsonFileAsync`.
+
+### `writeJsonFile(filePath: string, data: any, spaces: number = 2): void`
+
+💾 Saves a JavaScript object as a formatted JSON file.
+
+* Automatically creates the directory if it doesn't exist.
+* Async version: `writeJsonFileAsync`.
+
+---
+
+## 📂 Directory Management
+
+### `ensureDirectory(dirPath: string): void`
+
+🛠️ Ensures a directory exists. Creates it recursively if needed.
+
+### `clearDirectory(dirPath: string): void`
+
+🧹 Deletes all contents inside a directory while keeping the directory itself.
+
+---
+
+## 🧪 File Checks
+
+### `fileExists(filePath: string): boolean`
+
+🔎 Checks if a file exists.
+
+### `dirExists(dirPath: string): boolean`
+
+🏢 Checks if a directory exists.
+
+### `isDirEmpty(dirPath: string): boolean`
+
+📭 Checks if a directory is empty.
+
+---
+
+## 📄 File Operations
+
+### `ensureCopyFile(src: string, dest: string): void`
+
+📋 Copies a file from `src` to `dest`, ensuring the destination directory exists.
+
+* Async version: `ensureCopyFileAsync`.
+
+### `tryDeleteFile(filePath: string): boolean`
+
+🗑️ Tries to delete a file if it exists. Returns `true` if deleted.
+
+* Async version: `tryDeleteFileAsync`.
+
+---
+
+## 📝 Text Operations
+
+### `writeTextFile(filePath: string, content: string, ops?: fs.WriteFileOptions): void`
+
+✍️ Writes text content to a file. Ensures the directory exists before writing.
+
+* Async version: `writeTextFileAsync`.
+
+---
+
+## 🧾 Directory Listings
+
+### `listFiles(dirPath: string, recursive?: boolean): string[]`
+
+📃 Lists all files and dirs in a directory. Can be recursive.
+
+### `listDirs(dirPath: string, recursive?: boolean): string[]`
+
+📁 Lists all directories in a directory. Can be recursive.
+
+---
+
+## 📏 File Info
+
+### `fileSize(filePath: string): number`
+
+⚖️ Gets the size of a single file in bytes.
+
+### `dirSize(dirPath: string): number`
+
+📦 Gets the total size of all files inside a directory (recursive).
+
+---
+
+## 💾 Backup Utilities
+
+### `backupFile(filePath: string, ext: string = 'bak'): void`
+
+🛟 Creates a timestamped `.bak` copy of the file.
+
+* Async version: `backupFileAsync`.
+
+### `getLatestBackupPath(filePath: string, ext: string = 'bak'): void`
+
+📦 Returns the **most recent backup file path** for a given file, without modifying anything. Useful for checking which backup would be restored.
+
+### `restoreLatestBackup(filePath: string, ext: string = 'bak'): void`
+
+♻️ Restores the most recent backup for the file.
+
+Output: `/home/yasmin/notes.txt.bak.20250625T153000`
+
+```
+<file name>.<ext>.<timestamp>
+```
+
+* Async version: `restoreLatestBackupAsync`.
+
+---
+
+## 🔄 Rename Utilities
+
+### `renameFileBatch(dirPath, renameFn, extensions?)`
+
+🧠 Renames all files using a custom renaming function.
+
+* Only affects files with the specified extensions (if any).
+
+### `renameFileRegex(dirPath, pattern, replacement, extensions?)`
+
+🔡 Renames files using a regex pattern and replacement string.
+
+### `renameFileAddPrefixSuffix(dirPath, { prefix, suffix }, extensions?)`
+
+🔠 Adds a prefix and/or suffix to each filename.
+
+### `renameFileNormalizeCase(dirPath, mode, extensions?, normalizeExt: boolean = false)`
+
+🆎 Converts filenames to lowercase or uppercase.
+
+* `mode`: `'lower'` or `'upper'`.
+
+### `renameFilePadNumbers(dirPath, totalDigits, extensions?)`
+
+🔢 Pads the first numeric sequence in a filename with leading zeros.
+
+---
+
+## 🔡 `renameFileNormalizeCase(dirPath, mode = 'lower', extensions = [])`
+
+Normalizes all filenames in a directory to lowercase or uppercase.
+
+### 📥 Parameters:
+
+* `dirPath` *(string)*: Path to the target directory.
+* `mode` *(`'lower' | 'upper'`)*: Case conversion mode.
+
+  * `'lower'`: Converts filenames to lowercase.
+  * `'upper'`: Converts filenames to uppercase.
+* `extensions` *(string\[])* *(optional)*: List of file extensions to filter. If provided, only files with these extensions will be renamed.
+
+### 🎯 Example:
+
+```js
+renameFileNormalizeCase('./images', 'lower', ['.jpg', '.png']);
+```
+
+🔁 **Effect**:
+`Photo01.JPG` → `photo01.jpg`
+`Logo.PNG` → `logo.png`
+
+---
+
+## 🔢 `renameFilePadNumbers(dirPath, totalDigits = 3, extensions = [])`
+
+Pads the first numeric sequence found in each filename to a specified number of digits.
+
+### 📥 Parameters:
+
+* `dirPath` *(string)*: Path to the target directory.
+* `totalDigits` *(number)*: Minimum number of digits. Numbers will be padded with leading zeros.
+* `extensions` *(string\[])* *(optional)*: Only rename files with matching extensions.
+
+### 🎯 Example:
+
+```js
+renameFilePadNumbers('./screenshots', 4, ['.jpg']);
+```
+
+🔁 **Effect**:
+`screenshot1.jpg` → `screenshot0001.jpg`
+`photo23.jpg` → `photo0023.jpg`
+
+### 🧠 Notes:
+
+* Only the **first** number in the filename is affected.
+* If a filename has no digits, it will not be changed.
+
+---
+
+## 📦 More Example Use
+
+```js
+import { readJsonFile, writeJsonFile, listFiles, backupFile } from './utils/files.js';
+
+const data = readJsonFile('./config/settings.json');
+data.debug = false;
+writeJsonFile('./config/settings.json', data);
+
+const files = listFiles('./src/assets', true);
+console.log('Found files:', files);
+
+backupFile('./config/settings.json');
+```

package/docs/v1/basics/fullScreen.md

@@ -0,0 +1,183 @@
+# 📺 Fullscreen Utility API
+
+A lightweight JavaScript utility to manage fullscreen behavior easily with cross-browser support! 🚀
+
+---
+
+## 🧠 Features
+
+* ✅ Check if fullscreen is active
+* ✅ Check if the screen is completely filled
+* ✅ Enter fullscreen mode (with legacy browser support)
+* ✅ Exit fullscreen mode (with legacy browser support)
+* ✅ Listen to fullscreen change events
+* ✅ Remove fullscreen change listeners
+
+---
+
+## 🚀 Functions
+
+---
+
+### 🔍 `documentIsFullScreen()`
+
+Checks if the **document** is currently in fullscreen mode.
+
+```js
+documentIsFullScreen();
+```
+
+#### ✅ Returns
+
+* `boolean` → `true` if the document is in fullscreen, `false` otherwise.
+
+---
+
+### 🔍 `isScreenFilled()`
+
+Checks if the **window is filling the entire screen**, based on window dimensions.
+
+```js
+isScreenFilled();
+```
+
+#### ✅ Returns
+
+* `boolean` → `true` if the window occupies the full screen (matching `screen.width` and `screen.height`), otherwise `false`.
+
+---
+
+### 🔍 `isFullScreenMode()`
+
+Checks whether fullscreen mode is active **by API** (`documentIsFullScreen`) **or by matching window dimensions** (`isScreenFilled`).
+
+```js
+isFullScreenMode();
+```
+
+#### ✅ Returns
+
+* `boolean` → `true` if fullscreen mode is detected by either method.
+
+---
+
+### 🖥️ `requestFullScreen(ops?)`
+
+Requests fullscreen mode for the entire document.
+
+```js
+await requestFullScreen();
+```
+
+#### 🔧 Parameters
+
+| Name | Type                 | Description        |
+| ---- | -------------------- | ------------------ |
+| ops  | `FullscreenOptions?` | Optional settings. |
+
+#### ✅ Returns
+
+* `Promise<void>` → Resolves when fullscreen mode is successfully entered.
+
+#### ⚠️ Notes
+
+* Fully supports modern and legacy browsers (`moz`, `webkit`, `ms` prefixes).
+
+---
+
+### 🖥️ `exitFullScreen()`
+
+Exits fullscreen mode.
+
+```js
+await exitFullScreen();
+```
+
+#### ✅ Returns
+
+* `Promise<void>` → Resolves when fullscreen mode is successfully exited.
+
+#### ⚠️ Notes
+
+* Fully supports modern and legacy browsers (`moz`, `webkit`, `ms` prefixes).
+
+---
+
+### 🔔 `onFullScreenChange(listener, ops?)`
+
+Attaches a listener for fullscreen change events.
+
+```js
+onFullScreenChange((event) => {
+  console.log('Fullscreen changed!', event);
+});
+```
+
+#### 🔧 Parameters
+
+| Name     | Type                                        | Description        |
+| -------- | ------------------------------------------- | ------------------ |
+| listener | `EventListenerOrEventListenerObject`        | Callback function. |
+| ops      | `boolean \| AddEventListenerOptions` (opt.) | Optional options.  |
+
+#### ✅ Returns
+
+* `void`
+
+---
+
+### 🔕 `offFullScreenChange(listener, ops?)`
+
+Removes a listener from fullscreen change events.
+
+```js
+offFullScreenChange(myListener);
+```
+
+#### 🔧 Parameters
+
+| Name     | Type                                        | Description        |
+| -------- | ------------------------------------------- | ------------------ |
+| listener | `EventListenerOrEventListenerObject`        | Callback function. |
+| ops      | `boolean \| AddEventListenerOptions` (opt.) | Optional options.  |
+
+#### ✅ Returns
+
+* `void`
+
+---
+
+## 📜 Fullscreen Events Supported
+
+The following events are internally used for compatibility:
+
+* `'fullscreenchange'`
+* `'webkitfullscreenchange'`
+* `'mozfullscreenchange'`
+* `'MSFullscreenChange'`
+
+---
+
+## 💡 Example Usage
+
+```js
+import {
+  requestFullScreen,
+  exitFullScreen,
+  isFullScreenMode,
+  onFullScreenChange,
+  offFullScreenChange,
+} from './fullScreen';
+
+async function toggleFullscreen() {
+  if (isFullScreenMode()) {
+    await exitFullScreen();
+  } else {
+    await requestFullScreen();
+  }
+}
+
+onFullScreenChange(() => {
+  console.log('Fullscreen mode changed!');
+});
+```

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.