tiny-essentials 1.10.2 → 1.12.0

package/dist/v1/libs/TinyUploadClicker.mjs

@@ -0,0 +1,182 @@
+/**
+ * @typedef {Object} UploaderConfig
+ *
+ * @property {string | HTMLElement | Array<string | HTMLElement>} triggers -
+ *    Single or multiple elements (or selectors) that will act as upload triggers.
+ *
+ * @property {boolean} [multiple=false] -
+ *    Whether to allow selection of multiple files.
+ *
+ * @property {string|string[]} [accept=""] -
+ *    A comma-separated list of accepted file types (e.g., ".png,.jpg" or "image/*").
+ *
+ * @property {Record<string, string>} [inputAttributes={}] -
+ *    Additional attributes to apply to the created `<input type="file">`.
+ *
+ * @property {Partial<CSSStyleDeclaration>} [inputStyles={ display: 'none' }] -
+ *    Inline CSS styles to apply to the hidden input. Default hides the element.
+ *
+ * @property {((triggerElement: HTMLElement) => void)|null} [onClick=null] -
+ *    Callback executed when a trigger is clicked (before the file dialog opens).
+ *
+ * @property {((files: FileList, triggerElement: HTMLElement) => void)|null} [onFileLoad=null] -
+ *    Callback executed when files are selected through the file input.
+ */
+import { isJsonObject } from '../index.mjs';
+/**
+ * TinyUploadClicker is a lightweight utility class for attaching custom clickable elements
+ * (like buttons, divs, icons, etc.) that trigger hidden file input elements.
+ *
+ * It provides full control over the input file element without needing to display it,
+ * and allows per-trigger customization, style injection, and event handling.
+ *
+ * Each trigger element creates its own associated hidden file input, enabling multiple
+ * upload zones with different behaviors. You can handle `onClick` and `onFileLoad` callbacks,
+ * define accepted file types, allow multiple selections, and cleanly destroy everything via `destroy()`.
+ *
+ * Designed for maximum flexibility in pure JavaScript environments, including dynamic UI rendering.
+ *
+ * @example
+ * const uploader = new TinyUploadClicker({
+ *   triggers: '#uploadBtn',
+ *   accept: ['.png', '.jpg'],
+ *   multiple: true,
+ *   inputAttributes: { 'data-tracker': 'upload' },
+ *   inputStyles: { display: 'none' },
+ *   onClick: (el) => console.log('Trigger clicked:', el),
+ *   onFileLoad: (files, el) => console.log('Files selected:', files)
+ * });
+ *
+ * // Later, if needed:
+ * uploader.destroy();
+ */
+class TinyUploadClicker {
+    /** @type {UploaderConfig} */
+    #config;
+    /** @type {Array<HTMLElement|Element|null>} */
+    #triggerElements = [];
+    /** @type {WeakMap<HTMLElement, HTMLInputElement>} */
+    #inputs = new WeakMap();
+    /** @type {(ev: MouseEvent) => void} */
+    #boundClick;
+    /**
+     * Creates a new instance of TinyUploadClicker.
+     *
+     * @param {UploaderConfig} options - Configuration object for customizing the uploader behavior and appearance.
+     * @throws {TypeError} If the config is invalid or required options are missing.
+     */
+    constructor(options) {
+        if (!isJsonObject(options))
+            throw new TypeError('TinyUploadClicker: "options" must be a valid object.');
+        this.#config = {
+            multiple: false,
+            accept: '',
+            inputAttributes: {},
+            inputStyles: { display: 'none' },
+            onClick: null,
+            onFileLoad: null,
+            ...options,
+        };
+        const { triggers } = options;
+        if (!Array.isArray(triggers) &&
+            typeof triggers !== 'string' &&
+            !(triggers instanceof HTMLElement))
+            throw new TypeError('TinyUploadClicker: "triggers" is required and must be a string, HTMLElement, or an array of them.');
+        const triggerList = Array.isArray(this.#config.triggers)
+            ? this.#config.triggers
+            : [this.#config.triggers];
+        const resolvedTriggers = triggerList.map((ref) => {
+            if (typeof ref === 'string') {
+                const el = document.querySelector(ref);
+                if (!el) {
+                    throw new Error(`TinyUploadClicker: No element found for selector "${ref}".`);
+                }
+                return el;
+            }
+            if (!(ref instanceof HTMLElement))
+                throw new TypeError('TinyUploadClicker: All triggers must be either strings (selectors) or HTMLElements.');
+            return ref;
+        });
+        // Validate optional values
+        if (options.accept !== undefined &&
+            typeof options.accept !== 'string' &&
+            !Array.isArray(options.accept))
+            throw new TypeError('TinyUploadClicker: "accept" must be a string or an array of strings.');
+        if (options.onClick !== undefined &&
+            typeof options.onClick !== 'function' &&
+            options.onClick !== null)
+            throw new TypeError('TinyUploadClicker: "onClick" must be a function or null.');
+        if (options.onFileLoad !== undefined &&
+            typeof options.onFileLoad !== 'function' &&
+            options.onFileLoad !== null)
+            throw new TypeError('TinyUploadClicker: "onFileLoad" must be a function or null.');
+        if (options.inputAttributes !== undefined && !isJsonObject(options.inputAttributes))
+            throw new TypeError('TinyUploadClicker: "inputAttributes" must be an object.');
+        if (options.inputStyles !== undefined && !isJsonObject(options.inputStyles))
+            throw new TypeError('TinyUploadClicker: "inputStyles" must be an object.');
+        this.#boundClick = this.#handleClick.bind(this);
+        this.#triggerElements = resolvedTriggers;
+        this.#triggerElements.forEach((trigger) => {
+            if (!(trigger instanceof HTMLElement))
+                return;
+            const input = document.createElement('input');
+            input.type = 'file';
+            if (this.#config.multiple)
+                input.multiple = true;
+            if (typeof this.#config.accept === 'string')
+                input.accept = this.#config.accept;
+            else if (Array.isArray(this.#config.accept))
+                input.accept = this.#config.accept.join(',');
+            // Apply attributes
+            const attr = this.#config.inputAttributes;
+            if (attr && typeof attr === 'object') {
+                for (const [key, value] of Object.entries(attr)) {
+                    input.setAttribute(key, value);
+                }
+            }
+            // Apply styles
+            Object.assign(input.style, this.#config.inputStyles || { display: 'none' });
+            // Listen for file changes
+            input.addEventListener('change', () => {
+                if (input.files && typeof this.#config.onFileLoad === 'function')
+                    this.#config.onFileLoad(input.files, trigger);
+                input.value = ''; // reset so same file can be reselected
+            });
+            document.body.appendChild(input);
+            this.#inputs.set(trigger, input);
+            trigger.addEventListener('click', this.#boundClick);
+        });
+    }
+    /**
+     * Handles the click on a trigger element and forwards it to the associated file input.
+     *
+     * @param {MouseEvent} event - The click event object.
+     */
+    #handleClick(event) {
+        const trigger = event.currentTarget;
+        if (!(trigger instanceof HTMLElement))
+            return;
+        const input = this.#inputs.get(trigger);
+        if (!input)
+            return;
+        if (typeof this.#config.onClick === 'function')
+            this.#config.onClick(trigger);
+        input.click();
+    }
+    /**
+     * Cleans up all internal elements and event listeners, removing created inputs and breaking references.
+     */
+    destroy() {
+        for (const trigger of this.#triggerElements) {
+            if (!(trigger instanceof HTMLElement))
+                return;
+            trigger.removeEventListener('click', this.#boundClick);
+            const input = this.#inputs.get(trigger);
+            if (input && input.parentNode)
+                input.remove();
+            this.#inputs.delete(trigger);
+        }
+        this.#triggerElements = [];
+    }
+}
+export default TinyUploadClicker;

package/docs/{README.md → v1/README.md}

@@ -18,12 +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.
+- 📥 **[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!');
+});
+```