tiny-essentials 1.13.2 → 1.15.0

package/dist/v1/libs/TinyNotifications.mjs

@@ -0,0 +1,211 @@
+import { safeTextTrim } from '../basics/text.mjs';
+/**
+ * A utility class to manage browser notifications with sound and custom behavior.
+ * Useful for triggering system notifications with optional sound, avatar icon, body truncation, and click actions.
+ *
+ * @class
+ */
+class TinyNotifications {
+    /** @type {boolean} Whether notifications are currently allowed by the user. */
+    #allowed = false;
+    /** @type {boolean} Indicates whether the user has already requested permission at least once. */
+    #permissionRequested = false;
+    /** @type {HTMLAudioElement|null} Audio element to play when a notification is triggered. */
+    #audio = null;
+    /** @type {number} Maximum number of characters in the notification body. */
+    #bodyLimit = 100;
+    /** @type {string|null} Default avatar icon URL for notifications. */
+    #defaultIcon = null;
+    /** @type {(this: Notification, evt: Event) => any} Default handler when a notification is clicked. */
+    #defaultOnClick;
+    /**
+     * Constructs a new instance of TinyNotifications.
+     *
+     * @param {Object} [settings={}] - Optional settings to initialize the notification manager.
+     * @param {string|HTMLAudioElement|null} [settings.audio] - Path or URL to the audio file for notification sounds.
+     * @param {string|null} [settings.defaultIcon] - Default icon URL to be used in notifications.
+     * @param {number} [settings.bodyLimit=100] - Maximum number of characters allowed in the notification body.
+     * @param {(this: Notification, evt: Event) => any} [settings.defaultOnClick] - Default function to execute when a notification is clicked.
+     * @throws {TypeError} If any of the parameters are of an invalid type.
+     */
+    constructor({ audio = null, defaultIcon = null, bodyLimit = 100, defaultOnClick = function (event) {
+        event.preventDefault();
+        if (window.focus)
+            window.focus();
+        this.close();
+    }, } = {}) {
+        if (!(audio instanceof HTMLAudioElement) && typeof audio !== 'string' && audio !== null)
+            throw new TypeError('audio must be an instance of HTMLAudioElement or null.');
+        if (defaultIcon !== null && typeof defaultIcon !== 'string')
+            throw new TypeError('defaultIcon must be a string or null.');
+        if (!Number.isFinite(bodyLimit) || bodyLimit < 0)
+            throw new TypeError('bodyLimit must be a non-negative number.');
+        if (typeof defaultOnClick !== 'function')
+            throw new TypeError('defaultOnClick must be a function.');
+        this.#audio = typeof audio !== 'string' ? audio : new Audio(audio);
+        this.#defaultIcon = defaultIcon;
+        this.#bodyLimit = bodyLimit;
+        this.#defaultOnClick = defaultOnClick;
+    }
+    /**
+     * Requests permission from the user to show notifications.
+     * Updates the internal `#allowed` flag.
+     *
+     * @returns {Promise<boolean>} Resolves to `true` if permission is granted, otherwise `false`.
+     */
+    requestPerm() {
+        const tinyThis = this;
+        return new Promise((resolve, reject) => {
+            if (tinyThis.isCompatible()) {
+                if (Notification.permission === 'default') {
+                    Notification.requestPermission()
+                        .then((permission) => {
+                        this.#permissionRequested = true;
+                        tinyThis.#allowed = permission === 'granted';
+                        resolve(tinyThis.#allowed);
+                    })
+                        .catch(reject);
+                }
+                else {
+                    this.#permissionRequested = true;
+                    tinyThis.#allowed = Notification.permission === 'granted';
+                    resolve(tinyThis.#allowed);
+                }
+            }
+            else {
+                this.#permissionRequested = true;
+                tinyThis.#allowed = false;
+                resolve(false);
+            }
+        });
+    }
+    /**
+     * Checks if the Notification API is supported by the current browser.
+     *
+     * @returns {boolean} Returns `true` if notifications are supported, otherwise `false`.
+     */
+    isCompatible() {
+        return 'Notification' in window;
+    }
+    /**
+     * Sends a browser notification with the provided title and configuration.
+     * Truncates the body if necessary and plays a sound if configured.
+     *
+     * @param {string} title - The title of the notification.
+     * @param {NotificationOptions & { vibrate?: number[] }} [config={}] - Optional configuration for the notification.
+     * @returns {Notification|null} The created `Notification` instance, or `null` if permission is not granted.
+     * @throws {TypeError} If the title is not a string or config is not a valid object.
+     */
+    send(title, config = {}) {
+        if (!this.#permissionRequested)
+            throw new Error('You must call requestPerm() before sending a notification.');
+        if (typeof title !== 'string')
+            throw new TypeError('title must be a string.');
+        if (typeof config !== 'object' || config === null)
+            throw new TypeError('config must be a non-null object.');
+        if (!this.#allowed)
+            return null;
+        const { icon = this.#defaultIcon || undefined, vibrate = [200, 100, 200] } = config;
+        const options = { ...config };
+        if (typeof icon === 'string')
+            options.icon = icon;
+        if (Array.isArray(vibrate))
+            options.vibrate = vibrate;
+        if (typeof options.body === 'string')
+            options.body = safeTextTrim(options.body, this.#bodyLimit);
+        const notification = new Notification(title, options);
+        notification.addEventListener('show', () => {
+            if (!(this.#audio instanceof HTMLAudioElement))
+                return;
+            this.#audio.currentTime = 0;
+            this.#audio.play().catch((err) => console.error(err));
+        });
+        if (typeof this.#defaultOnClick === 'function')
+            notification.addEventListener('click', this.#defaultOnClick);
+        return notification;
+    }
+    // === Getters and Setters ===
+    /**
+     * Whether the requestPerm() method was already called.
+     * @returns {boolean}
+     */
+    wasPermissionRequested() {
+        return this.#permissionRequested;
+    }
+    /**
+     * Returns the current permission status.
+     * @returns {boolean} `true` if permission was granted, otherwise `false`.
+     */
+    isAllowed() {
+        return this.#allowed;
+    }
+    /**
+     * Gets the current notification audio.
+     * @returns {HTMLAudioElement|null} The sound element, or `null` if not set.
+     */
+    getAudio() {
+        return this.#audio;
+    }
+    /**
+     * Sets the audio element used for notification sounds.
+     * @param {HTMLAudioElement|string|null} value - A valid `HTMLAudioElement` or `null` to disable sound.
+     * @throws {TypeError} If the value is not an `HTMLAudioElement` or `null`.
+     */
+    setAudio(value) {
+        if (!(value instanceof HTMLAudioElement) && typeof value !== 'string' && value !== null)
+            throw new TypeError('sound must be an instance of HTMLAudioElement or null.');
+        this.#audio = typeof value !== 'string' ? value : new Audio(value);
+    }
+    /**
+     * Gets the maximum length of the notification body text.
+     * @returns {number} Number of characters allowed.
+     */
+    getBodyLimit() {
+        return this.#bodyLimit;
+    }
+    /**
+     * Sets the maximum number of characters allowed in the notification body.
+     * @param {number} value - A non-negative integer.
+     * @throws {TypeError} If the value is not a valid non-negative number.
+     */
+    setBodyLimit(value) {
+        if (!Number.isFinite(value) || value < 0)
+            throw new TypeError('bodyLimit must be a non-negative number.');
+        this.#bodyLimit = value;
+    }
+    /**
+     * Gets the default avatar icon URL.
+     * @returns {string|null} The URL string or `null`.
+     */
+    getDefaultAvatar() {
+        return this.#defaultIcon;
+    }
+    /**
+     * Sets the default avatar icon URL.
+     * @param {string|null} value - A string URL or `null` to disable default icon.
+     * @throws {TypeError} If the value is not a string or `null`.
+     */
+    setDefaultAvatar(value) {
+        if (!(typeof value === 'string' || value === null))
+            throw new TypeError('defaultIcon must be a string or null.');
+        this.#defaultIcon = value;
+    }
+    /**
+     * Gets the default click event handler for notifications.
+     * @returns {(this: Notification, evt: Event) => any} The current click handler function.
+     */
+    getDefaultOnClick() {
+        return this.#defaultOnClick;
+    }
+    /**
+     * Sets the default click event handler for notifications.
+     * @param {(this: Notification, evt: Event) => any} value - A function to handle the notification click event.
+     * @throws {TypeError} If the value is not a function.
+     */
+    setDefaultOnClick(value) {
+        if (typeof value !== 'function')
+            throw new TypeError('defaultOnClick must be a function.');
+        this.#defaultOnClick = value;
+    }
+}
+export default TinyNotifications;

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.
@@ -29,9 +30,10 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🔔 **[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.
-* 🕒 **[TinyDomReadyManager](./libs/TinyDomReadyManager.md)** — A readiness manager for DOM and async conditions, supporting prioritized callbacks, custom filters, and event-based or promise-based bootstrapping.
+- 📂 **[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.
+- 🕒 **[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.
 
 ### 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/array.md

@@ -1,16 +1,18 @@
 # 📦 array.mjs
 
-A tiny utility for shuffling arrays using the good old Fisher–Yates algorithm. Simple, efficient, and perfectly random (as far as JavaScript's `Math.random()` allows, anyway).
+A minimal and handy module offering a couple of focused utilities for working with arrays — from shuffling items randomly to generating smart sort functions for object arrays. Ideal for quick scripting or modular use in larger projects.
 
-## ✨ Features
+---
+
+## `shuffleArray(items: string[]): string[]`
 
-- 📚 Uses the classic **Fisher–Yates** algorithm
-- 🔄 Shuffles arrays **in-place**
-- 🎯 Guarantees **uniform distribution** of permutations
-- 🔍 Well-documented and easy to read
-- 🧪 No dependencies — just plug and play
+🔄 A tiny utility for shuffling arrays using the good old Fisher–Yates algorithm. Simple, efficient, and perfectly random (as far as JavaScript's `Math.random()` allows, anyway).
 
-## 🚀 Usage
+- **items** — An array of strings to shuffle.
+- **Returns** — The same array instance, but now shuffled.
+
+
+### 🚀 Usage
 
 ```js
 import { shuffleArray } from './array.mjs';
@@ -23,54 +25,29 @@ console.log(fruits); // ['banana', 'cherry', 'apple', 'date'] (order will vary)
 
 > Note: The original array is shuffled in place. If you want to preserve the original order, make a copy before shuffling.
 
-## 🧠 How It Works
-
-This function implements the **Fisher–Yates shuffle** (also known as the Knuth shuffle), which runs in linear time and guarantees uniform randomness:
-
-```js
-while (currentIndex !== 0) {
-  randomIndex = Math.floor(Math.random() * currentIndex);
-  currentIndex--;
-  [items[currentIndex], items[randomIndex]] = [items[randomIndex], items[currentIndex]];
-}
-```
-
 You can find the original discussion here:  
 🔗 https://stackoverflow.com/questions/2450954/how-to-randomize-shuffle-a-javascript-array
 
-## 📁 API
-
-### `shuffleArray(items: string[]): string[]`
-
-- **items** — An array of strings to shuffle.
-- **Returns** — The same array instance, but now shuffled.
-
 ---
 
-# 📦 `arraySortPositions`
+## 📦 `arraySortPositions`
 
 🔧 **Generates a comparator function** to sort an array of objects by a specified key, with optional reverse order.
 
----
-
-## 📌 Function Signature
+### 📌 Function Signature
 
 ```js
 arraySortPositions(item: string, isReverse?: boolean): (a: Object<string|number, *>, b: Object<string|number, *>) => number
 ```
 
----
-
-## 🧠 Parameters
+### 🧠 Parameters
 
 | Name        | Type      | Default | Description                                                |
 | ----------- | --------- | ------- | ---------------------------------------------------------- |
 | `item`      | `string`  | —       | 🔑 The key to sort the objects by.                         |
 | `isReverse` | `boolean` | `false` | 🔄 If `true`, the sorting will be in **descending** order. |
 
----
-
-## 🎯 Returns
+### 🎯 Returns
 
 🧩 A **comparator function** compatible with `Array.prototype.sort()`:
 
@@ -80,9 +57,7 @@ arraySortPositions(item: string, isReverse?: boolean): (a: Object<string|number,
 
 It compares two objects based on the specified `item` key.
 
----
-
-## 💡 Examples
+### 💡 Examples
 
 ```js
 const arr = [{ pos: 2 }, { pos: 1 }, { pos: 3 }];
@@ -96,9 +71,7 @@ arr.sort(arraySortPositions('pos', true));
 // 🔽 Descending: [{ pos: 3 }, { pos: 2 }, { pos: 1 }]
 ```
 
----
-
-## 🛠️ Use Case
+### 🛠️ Use Case
 
 Great for situations where you need to **dynamically sort objects** by one of their keys, such as:
 

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 }
+```