tiny-essentials 1.11.0 → 1.12.1

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

package/docs/v1/libs/TinyDragger.md

@@ -0,0 +1,430 @@
+# 🧲 TinyDragger
+
+TinyDragger enables customizable **drag-and-drop** behavior for HTML elements.  
+It supports visual proxies, jail boundaries, collision detection, vibration feedback, drop restrictions, and custom events — all with a lightweight and flexible architecture.
+
+---
+
+## ✨ Features
+
+- 🖱️ Mouse & touch drag support  
+- 🔒 Jail constraints to restrict dragging area  
+- 💥 Collision detection with other elements  
+- 🔄 Auto-revert to original position  
+- 🎮 Vibration feedback via `navigator.vibrate()`  
+- 👻 Visual clone during drag (proxy)  
+- 🎨 Fully configurable class names  
+- 📦 Clean destroy method with memory-safe teardown  
+- 🔔 Custom drag and drop events  
+
+---
+
+## 📦 Installation
+
+```js
+import TinyDragger from './TinyDragger.js';
+```
+
+---
+
+## 🧰 Constructor
+
+```ts
+new TinyDragger(targetElement, options?)
+```
+
+### Parameters:
+
+| Name            | Type          | Default      | Description                       |
+| --------------- | ------------- | ------------ | --------------------------------- |
+| `targetElement` | `HTMLElement` | **required** | The element to enable dragging on |
+| `options`       | `Object`      | `{}`         | Optional configuration            |
+
+### 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               |
+
+---
+
+## 📳 Vibration Patterns
+
+```ts
+type VibrationPatterns = {
+  start: number[] | false,
+  end: number[] | false,
+  collide: number[] | false,
+  move: number[] | false
+}
+```
+
+---
+
+## 📚 Public Methods
+
+### `enable()`
+
+🔓 Re-enables dragging after being disabled.
+
+---
+
+### `disable()`
+
+🚫 Temporarily disables dragging. Still allows re-enabling later.
+
+---
+
+### `destroy()`
+
+💣 Fully disables the instance, removes event listeners, and clears any DOM state.
+
+---
+
+### `addCollidable(element: HTMLElement)`
+
+➕ Adds an element to the collision tracking list.  
+🛑 Throws if the element is not a valid `HTMLElement`.
+
+---
+
+### `removeCollidable(element: HTMLElement)`
+
+➖ Removes an element from the collision list.  
+🛑 Throws if the element is not a valid `HTMLElement`.
+
+---
+
+### `setVibrationPattern({ startPattern, endPattern, collidePattern, movePattern })`
+
+📳 Updates the vibration patterns used during drag events.
+Each pattern must be either `false` or an array of numbers.
+
+---
+
+### `disableVibration()`
+
+🔕 Turns off all vibration feedback.
+
+---
+
+### `getOffset(event: MouseEvent | Touch): { x: number, y: number }`
+
+📐 Returns the X and Y offset from the event to the top-left corner of the element.  
+🛑 Throws if the event is invalid.
+
+---
+
+### `getCollidedElementByRect(rect: DOMRect): HTMLElement | null`
+
+🎯 Detects if a `DOMRect` collides with any registered collidable elements.  
+🛑 Throws if the rect is invalid.
+
+---
+
+### `getAllCollidedElementsByRect(rect: DOMRect): HTMLElement[]`
+
+📌 Returns **all elements** currently intersecting the given rectangle. Useful for detecting multiple overlaps when dragging.
+🛑 Throws if `rect` is not a valid `DOMRect` with numeric `left`, `right`, `top`, and `bottom` properties.
+
+---
+
+### `getCollidedElement(x: number, y: number): HTMLElement | null`
+
+📌 Detects if the given screen coordinates collide with any tracked element.  
+🛑 Throws if `x` or `y` is not a number.
+
+---
+
+### `getAllCollidedElements(x: number, y: number): HTMLElement[]`
+
+📌 Detects **all elements** currently under the given screen coordinates. Works well when `collisionByMouse` is enabled.
+🛑 Throws if `x` or `y` is not a number.
+
+---
+
+### `getDragging(): boolean`
+
+🔄 Returns whether dragging is currently active.
+
+---
+
+### `getLockInsideJail(): boolean`
+
+🔒 Returns whether movement is restricted inside the jail container.
+
+---
+
+### `setLockInsideJail(value: boolean): void`
+
+⚙️ Sets whether movement is restricted inside the jail container.  
+🛑 Throws if `value` is not a boolean.
+
+---
+
+### `getRevertOnDrop(): boolean`
+
+↩️ Returns whether the element should revert to its original position on drop.
+
+---
+
+### `setRevertOnDrop(value: boolean): void`
+
+⚙️ Sets whether the element should revert to its original position on drop.  
+🛑 Throws if `value` is not a boolean.
+
+---
+
+### `getCollisionByMouse(): boolean`
+
+🖱️ Returns whether collision detection uses mouse position instead of element bounding rectangles.
+
+---
+
+### `setCollisionByMouse(value: boolean): void`
+
+⚙️ Sets whether collision detection uses mouse position instead of element bounding rectangles.  
+🛑 Throws if `value` is not a boolean.
+
+---
+
+### `getDropInJailOnly(): boolean`
+
+🚫 Returns whether dropping is restricted inside the jail container.
+
+---
+
+### `setDropInJailOnly(value: boolean): void`
+
+⚙️ Sets whether dropping is restricted inside the jail container.  
+🛑 Throws if `value` is not a boolean.
+
+---
+
+### `checkDragCollision(event: MouseEvent | Touch): void`
+
+🎯 Checks for collision between the drag proxy and registered elements.  
+💥 Applies or removes the collision class depending on overlap.  
+📳 Triggers vibration if configured.
+
+---
+
+### `execCollision(event: MouseEvent | Touch): { inJail: boolean; collidedElement: HTMLElement | null }`
+
+🧩 Executes collision detection logic based on the drag position and mode.  
+📍 Uses either the mouse point or the proxy rectangle depending on `collisionByMouse`.  
+🔒 Respects `dropInJailOnly` and jail boundaries.  
+🛑 Returns `{ inJail: false, collidedElement: null }` if dragging is not active.
+
+---
+
+### `getTarget(): HTMLElement`
+
+🎯 Returns the original element being dragged.
+
+---
+
+### `getJail(): HTMLElement | null`
+
+🚧 Returns the jail container element if one is set.  
+Returns `null` if no jail is configured.
+
+---
+
+### `getDragProxy(): HTMLElement | null`
+
+👻 Returns the current proxy (clone) element being dragged.  
+Returns `null` if no proxy is active.
+
+---
+
+### `getLastCollision(): HTMLElement | null`
+
+💥 Returns the last collided element (if any).
+
+---
+
+### `getCollidables(): HTMLElement[]`
+
+🧲 Returns the list of elements that are considered for collision detection.
+
+---
+
+### `getDragHiddenClass(): string`
+
+👀 Returns the CSS class used to hide the original element during dragging.
+
+---
+
+### `getClassDragging(): string`
+
+🎬 Returns the CSS class applied to the clone while it is being dragged.
+
+---
+
+### `getClassBodyDragging(): string`
+
+🧍 Returns the CSS class applied to `<body>` when dragging is active.
+
+---
+
+### `getClassJailDragging(): string`
+
+🏗️ Returns the CSS class applied to the jail element while dragging is active.
+
+---
+
+### `getClassJailDragDisabled(): string`
+
+🚫 Returns the CSS class applied to the jail when dragging is disabled.
+
+---
+
+### `getClassDragCollision(): string`
+
+⚠️ Returns the CSS class applied to elements when a collision is detected.
+
+---
+
+### `getVibrations(): { start: number[] | false, end: number[] | false, collide: number[] | false, move: number[] | false }`
+
+🎵 Returns the full vibration pattern configuration used during dragging.
+
+---
+
+### `getStartVibration(): number[] | false`
+
+📳 Returns the vibration pattern used at the **start** of a drag.
+
+---
+
+### `getEndVibration(): number[] | false`
+
+📴 Returns the vibration pattern used at the **end** of a drag.
+
+---
+
+### `getCollideVibration(): number[] | false`
+
+🎯 Returns the vibration pattern used when **colliding** with another element.
+
+---
+
+### `getMoveVibration(): number[] | false`
+
+🚶 Returns the vibration pattern used during **movement** while dragging.
+
+---
+
+### `isEnabled(): boolean`
+
+✅ Returns whether the drag-and-drop functionality is currently enabled.
+
+---
+
+## 🔁 Events
+
+The target element will emit these events:
+
+| Event      | Description                                      |
+| ---------- | ------------------------------------------------ |
+| `drag`     | Fired at the beginning of a drag                 |
+| `dragging` | Continuously fired while dragging                |
+| `drop`     | Fired at the end of the drag with collision info |
+
+### Example:
+
+```js
+targetEl.addEventListener('drop', (e) => {
+  console.log('Dropped on:', e.detail.target);
+});
+```
+
+---
+
+## 🛡️ Error Handling
+
+* Throws errors if the constructor options are of invalid types.
+* Throws if using destroyed instances (`destroy()` has been called).
+* Throws on invalid usage of methods like `addCollidable` or `getOffset`.
+
+---
+
+## ✅ Example
+
+```js
+const box = document.getElementById('draggableBox');
+const jail = document.getElementById('jailContainer');
+
+const dragger = new TinyDragger(box, {
+    jail,
+    lockInsideJail: false,
+    collisionByMouse: false,
+    revertOnDrop: false,
+    vibration: {
+      start: [30],
+      move: [5],
+      collide: [80],
+      end: [20, 10, 20],
+    },
+});
+
+const dropTarget = document.getElementById('dropArea');
+dragger.addCollidable(dropTarget);
+
+box.addEventListener('drop', (e) => {
+  if (e.detail.target === dropTarget) {
+    alert('Dropped successfully!');
+  }
+});
+```
+
+---
+
+## 🧼 Clean-Up
+
+Call `.destroy()` to completely remove drag behavior and all event listeners:
+
+```js
+dragger.destroy();
+```
+
+---
+
+## 🧪 Testing & Styling
+
+* 🎨 **Example Stylesheets:**
+  You can find optional example styles to get started or test layout integration in:
+
+  ```
+  dist/v1/css/TinyDraggerExample.css
+  dist/v1/css/TinyDraggerExample.min.css
+  ```
+
+* 🧱 **Test Environment:**
+  A ready-to-use HTML test page is available at:
+
+  ```
+  test/html/TinyDragger
+  ```
+
+  This includes practical demos and scenarios to test dragging, collision, jail constraints, and more.
+
+---
+
+## 🧠 Notes
+
+* Touch support uses the first touch point only.
+* Make sure your draggable element has `position: relative` or `absolute` if it’s meant to be positioned manually after drop.

package/docs/v1/libs/TinyLevelUp.md

@@ -6,7 +6,7 @@ A lightweight XP-based leveling system for managing user experience and levels.
 
 ## 📐 Type Definitions
 
-### `UserEditor` ✍️
+### ✍️ `UserEditor`
 
 Represents the structure of a user object used in the leveling system.
 

package/docs/v1/libs/TinyNotifyCenter.md

@@ -274,6 +274,26 @@ You create a rich notification element dynamically, with optional avatar, title,
 
 ---
 
+## 🔥 `destroy()`
+
+Destroys the current **TinyNotifyCenter** instance.
+It **removes all event listeners**, **clears all notifications**, and **optionally removes the entire notification center template from the DOM**.
+
+### Syntax
+
+```js
+tinyNotifyCenter.destroy();
+```
+
+### Behavior
+
+* Removes all event listeners (`click`, `close`, `clear all`, overlay clicks).
+* Clears all notifications from the list.
+* Removes the UI (`.notify-overlay`, `.notify-bell`, etc.) from the DOM.
+* Cleans internal references (`center`, `list`, `button`, `overlay`, `badge`, `modes`).
+
+---
+
 ## 🎨 CSS Files Location
 
 The CSS files for the TinyNotify project build can be found in the following folder:

package/docs/v1/libs/TinyToastNotify.md

@@ -273,6 +273,25 @@ Displays a notification with customizable content and duration based on message
 
 ---
 
+## 🔥 `destroy()`
+
+Destroys the current **TinyToastNotify** instance.
+It **removes the notification container from the DOM** and **clears all pending notifications**. This method is useful when the notification system is no longer needed or when changing views in a single-page application.
+
+### Syntax
+
+```js
+tinyToastNotify.destroy();
+```
+
+### Behavior
+
+* Removes the entire container (`.notify-container`) from the DOM.
+* Automatically cancels any pending or visible toasts.
+* Cleans up internal references.
+
+---
+
 ## 🎨 CSS Files Location
 
 The CSS files for the TinyNotify project build can be found in the following folder: