tiny-essentials 1.28.18 → 1.29.0

package/docs/v1/webTemplates/bootstrap/5.3/html/BootstrapDialogs.md

@@ -0,0 +1,174 @@
+# 🚀 BootstrapDialogs Documentation
+
+`BootstrapDialogs` is a asynchronous JavaScript utility designed to replace native browser dialogs (`alert`, `confirm`, `prompt`) with beautiful, customizable **Bootstrap 5 Modals**. 
+
+It provides a non-blocking, Promise-based workflow and features a robust configuration system to ensure your UI remains consistent and visually appealing.
+
+## ✨ Key Features
+
+*   **💎 Promise-Based:** All dialogs are `async`, allowing for clean `await` syntax in your business logic.
+*   **🎨 Deep Customization:** Every single part of the modal (header, body, footer, buttons, etc.) can be styled with custom CSS classes and inline styles.
+*   **🛡️ Security Focused:** Uses strict DOM manipulation to prevent XSS attacks.
+*   **⏳ Loading State:** Includes a built-in, non-dismissible global loading overlay for background tasks with customization support.
+*   **🧹 Automatic Cleanup:** Automatically manages DOM elements and body classes (`modal-open`) to prevent memory leaks or broken scrolling.
+
+---
+
+## 🛠️ Setup
+
+To use this library, you must have **Bootstrap 5** (JavaScript and CSS) included in your project. You must also initialize the library with the Bootstrap Modal class.
+
+```javascript
+import { BootstrapDialogs } from 'tiny-essentials/webTemplates/bootstrap/5.3/html/BootstrapDialogs';
+import { Modal } from 'bootstrap';
+
+// 1. Initialize the Modal class
+BootstrapDialogs.Modal = Modal;
+```
+
+## 🔄 Global Replacement (Monkey Patching)
+
+If you want to automatically use Bootstrap modals instead of the default browser dialogs throughout your entire application, you can "monkey patch" the global `window` object.
+
+```javascript
+import { BootstrapDialogs } from 'tiny-essentials/webTemplates/bootstrap/5.3/html/BootstrapDialogs';
+
+window.alert = (msg) => BootstrapDialogs.alert(msg);
+window.confirm = (msg) => BootstrapDialogs.confirm(msg);
+window.prompt = (msg, def) => BootstrapDialogs.prompt(msg, def);
+```
+
+> [!WARNING]
+> **⚠️ Breaking Change Alert:** Native `window.confirm` and `window.prompt` are **synchronous** (they pause code execution). `BootstrapDialogs` methods are **asynchronous** (they return a `Promise`).
+>
+> If you use this replacement, you **must** update your existing code to use `await` when calling these functions.
+>
+> ❌ **Old (Synchronous):**
+> `if (confirm("Are you sure?")) { ... }`
+>
+> ✅ **New (Asynchronous):**
+> `if (await confirm("Are you sure?")) { ... }`
+
+---
+
+## ⚙️ Configuration
+
+### 1. Global Defaults
+You can set a global configuration that applies to all dialogs created by the library.
+
+```javascript
+BootstrapDialogs.defaultConfig = {
+  modalConfig: { className: 'my-custom-modal', styles: { 'border': '2px solid blue' } },
+  confirmBtnConfig: { className: 'btn-success' },
+  // ... other config keys
+};
+```
+
+### 2. Data Types (JSDoc Reference)
+
+#### `CustomElementConfig` 🎨
+Used to customize specific parts of the modal.
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `className` | `string \| string[]` | CSS classes to add to the element. |
+| `styles` | `Object<string, string>` | CSS properties and values (e.g., `{ 'color': 'red' }`). |
+
+#### `ModalOptions` 📋
+Configuration options for customization of the modal structure.
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `title` | `string` | `'Alert'` | Text for the modal header. |
+| `confirmText` | `string` | `'OK'` | Text for the primary button. |
+| `cancelText` | `string` | `'Cancel'` | Text for the secondary button. |
+| `defaultValue` | `string` | `''` | Initial value for prompt inputs. |
+| `modalConfig` | `CustomElementConfig` | `{}` | Customization for the main container. |
+| `headerConfig` | `CustomElementConfig` | `{}` | Customization for the header. |
+| `titleConfig` | `CustomElementConfig` | `{}` | Customization for the title. |
+| `closeBtnConfig` | `CustomElementConfig` | `{}` | Customization for the close button. |
+| `bodyConfig` | `CustomElementConfig` | `{}` | Customization for the body. |
+| `footerConfig` | `CustomElementConfig` | `{}` | Customization for the footer. |
+| `confirmBtnConfig`| `CustomElementConfig` | `{}` | Customization for the confirm button. |
+| `cancelBtnConfig` | `CustomElementConfig` | `{}` | Customization for the cancel button. |
+| `contentConfig` | `CustomElementConfig` | `{}` | Customization for the content wrapper. |
+| `dialogConfig` | `CustomElementConfig` | `{}` | Customization for the dialog wrapper. |
+
+---
+
+## 🚀 API Reference
+
+### 📢 `alert(message, options)`
+Displays a simple informational modal.
+*   **Returns:** `Promise<void>`
+*   **Usage:** `await alert('Operation successful!');`
+
+### ❓ `confirm(message, options)`
+Displays a confirmation modal with "Yes" and "No" options.
+*   **Returns:** `Promise<boolean>` (Resolves `true` if confirmed, `false` if cancelled).
+*   **Usage:** 
+    ```javascript
+    const isDeleted = await confirm('Do you really want to delete this user?', {
+      title: '⚠️ Warning',
+      confirmText: 'Delete Forever',
+      cancelText: 'Keep User',
+      confirmBtnConfig: { className: 'btn-danger' }
+    });
+    ```
+
+### ⌨️ `prompt(message, defaultValue, options)`
+Displays a modal with a text input field.
+*   **Parameters:**
+    *   `message` (string): The instruction or question.
+    *   `defaultValue` (string): The initial value for the input field.
+    *   `options` (`ModalOptions`): Configuration options.
+*   **Returns:** `Promise<string | null>` (Resolves with the input value, or `null` if cancelled).
+*   **Usage:**
+    ```javascript
+    const name = await prompt('Enter your name', 'Guest');
+    ```
+
+### ⏳ `showLoading(message, config)`
+Displays a global, non-dismissible loading spinner.
+*   **Parameters:**
+    *   `message` (string): The text to display.
+    *   `config` (`CustomElementConfig`): Customization for the loading message element.
+*   **Returns:** `void`
+*   **Usage:** `showLoading('Fetching data...', { className: 'text-warning' });`
+
+### ✅ `hideLoading()`
+Removes the loading overlay.
+*   **Returns:** `void`
+*   **Usage:** `hideLoading();`
+
+---
+
+## 💡 Usage Example
+
+```javascript
+import { confirm, prompt, showLoading, hideLoading } from 'tiny-essentials/webTemplates/bootstrap/5.3/html/BootstrapDialogs';
+
+async function handleDeleteUser(userId) {
+  // 1. Show loading state
+  showLoading('Processing request...');
+
+  try {
+    // 2. Ask for confirmation
+    const confirmed = await confirm('Do you really want to delete this user?', {
+      title: '⚠️ Warning',
+      confirmText: 'Delete Forever',
+      cancelText: 'Keep User',
+      confirmBtnConfig: { className: 'btn-danger' }
+    });
+
+    if (confirmed) {
+      // 3. Simulate API Call
+      await new Promise(res => setTimeout(res, 2000));
+      console.log(`User ${userId} deleted.`);
+    }
+  } catch (error) {
+    console.error(error);
+  } finally {
+    // 4. Hide loading
+    hideLoading();
+  }
+}
+```

package/docs/v1/webTemplates/media/MediaValidator/v1/Browser.md

@@ -0,0 +1,123 @@
+# 🛡️ MediaShield: Robust Media Validation Library
+
+Welcome to **MediaShield**! This library is designed to provide security, multi-layered validation for media files (Images, Audio, and Video). 
+
+When building modern web applications, users often upload files. A common security risk is "File Spoofing," where a malicious actor renames a dangerous script (like `.exe` or `.js`) to a harmless extension (like `.jpg`). **MediaShield** prevents this by looking *inside* the file, not just at the filename.
+
+---
+
+## 🚀 Core Concept: The Two-Layer Defense
+
+MediaShield operates on a "Defense in Depth" principle. We don't just trust the file extension; we verify the actual data.
+
+1.  **Layer 1: Magic Number Validation (The Identity Check) 🔍**
+    We inspect the "Magic Numbers" (the first few bytes of a file). This tells us what the file *actually* is, regardless of its name.
+2.  **Layer 2: Structural Validation (The Integrity Check) 🏗️**
+    Once we know the identity, we ask the browser to attempt to decode the file. If the browser cannot read the internal structure (like height/width for images or duration for video), the file is considered corrupted or malicious.
+
+---
+
+## 📖 API Reference
+
+### 1. `validateMagicNumbers`
+The first line of defense. It checks the binary signature of the file.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `inputData` | `Buffer \| Uint8Array \| Blob` | The raw binary data of the file. |
+| `expectedType` | `'image' \| 'audio' \| 'video'` | The category you are expecting. |
+| `fileTypeFromBuffer` | `Function` | A callback function that identifies MIME types from buffers. |
+
+**Returns:** `Promise<string>` (The confirmed MIME type).
+**Throws:** `Error` if the signature doesn't match the expected category.
+
+---
+
+### 2. `validateImage`
+Deep structural validation specifically for images.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `inputData` | `Blob` | The image file as a Blob. |
+
+**Returns:** `Promise<ValidationResult>`
+*   **On Success:** `{ mimeType, error: null, data: { width, height, format } }`
+*   **On Failure:** `{ mimeType: null, error: "Error message" }`
+
+---
+
+### 3. `validateAudioVideo`
+Deep structural validation for multimedia containers.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `inputData` | `Blob` | The media file as a Blob. |
+| `mimeType` | `string` | The MIME type obtained from `validateMagicNumbers`. |
+
+**Returns:** `Promise<ValidationResult>`
+*   **On Success:** `{ mimeType, error: null, data: { duration } }`
+*   **On Failure:** `{ mimeType: null, error: "Error message" }`
+
+---
+
+## 🛠️ Daily Workflow: How to use it
+
+To use MediaShield in your project, you should follow this logical sequence to ensure security.
+
+### Step-by-Step Implementation Guide
+
+1.  **Step 1: Capture the File** 📥
+    Get the file from an `<input type="file">` element.
+2.  **Step 2: Run Magic Number Check** 🛡️
+    Call `validateMagicNumbers`. If this fails, stop immediately. The file is a spoof.
+3.  **Step 3: Perform Deep Validation** 🏗️
+    Based on the result of Step 2, call either `validateImage` or `validateAudioVideo`.
+4.  **Step 4: Proceed or Reject** ✅
+    If both layers pass, the file is safe to upload to your server.
+
+### 💻 Code Example
+
+Here is how you would implement the full pipeline in a real-world scenario:
+
+```javascript
+import { validateMagicNumbers, validateImage, validateAudioVideo } from 'tiny-essentials/webTemplates/media/MediaValidator/v1/Browser';
+
+async function handleFileUpload(fileBlob) {
+  try {
+    const fileDetector = async () => ({ mime: fileBlob.type });
+
+    // --- LAYER 1: Identity Check ---
+    const confirmedMime = await validateMagicNumbers({
+      inputData: fileBlob,
+      expectedType: 'image',
+      fileTypeFromBuffer: fileDetector
+    });
+    console.log(`✅ Identity confirmed: ${confirmedMime}`);
+
+    // --- LAYER 2: Structural Check ---
+    const validation = await validateImage({
+      inputData: fileBlob
+    });
+
+    if (validation.error) {
+      throw new Error(`❌ Structural validation failed: ${validation.error}`);
+    }
+
+    console.log(`🎉 File is safe! Dimensions: ${validation.data.width}x${validation.data.height}`);
+    return validation.data;
+
+  } catch (error) {
+    console.error(`🚨 Security/Validation Error: ${error.message}`);
+  }
+}
+
+// Usage
+const fileInput = document.querySelector('input[type="file"]');
+ fileInput.addEventListener('change', (e) => handleFileUpload(e.target.files[0]));
+```
+
+---
+
+## ⚠️ Security Notes
+*   **Always** perform Layer 1 validation on the client side for immediate user feedback.
+*   **Crucial:** Client-side validation is for UX and basic security. Always perform a second round of validation on your **Server/Backend** before saving files to permanent storage.

package/docs/v1/webTemplates/media/MediaValidator/v1/Node.md

@@ -0,0 +1,136 @@
+# 🛡️ Secure Media Validator
+
+A multi-layered validation toolkit designed to ensure file integrity and prevent security exploits such as **MIME-spoofing** (where a malicious file is disguised with a fake extension).
+
+## 📋 Overview
+
+When handling file uploads, simply checking a file extension (like `.jpg`) is not enough. An attacker can rename a malicious script to `image.jpg`. This project implements a two-layer defense strategy:
+
+1.  **Layer 1: Fast Binary Validation (Magic Numbers) 🔍**
+    Checks the actual file header (the first few bytes) to see if the internal signature matches the expected category.
+2.  **Layer 2: Deep Structural Validation 🏗️**
+    Forces the system to parse the internal structure of the file (metadata/frames) to ensure the file isn't just a valid header followed by corrupted or malicious data.
+
+---
+
+## 📦 Dependencies
+
+To use this toolkit, you must have the following packages installed in your project:
+
+*   `file-type`: For magic number detection.
+*   `sharp`: For deep image structural analysis.
+*   `music-metadata`: For deep audio/video container parsing.
+
+```bash
+npm install file-type sharp music-metadata
+```
+
+---
+
+## 🛠️ API Reference
+
+### 1. Layer 1: `validateMagicNumbers` 🔍
+
+This is your first line of defense. It is extremely fast because it only reads the beginning of the file.
+
+**Purpose:** To verify that the file's internal "signature" matches the category you expect (image, audio, or video).
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `buffer` | `Buffer` | The raw binary data of the uploaded file. |
+| `expectedType` | `'image' \| 'audio' \| 'video'` | The category you are expecting. |
+| `fileTypeFromBuffer` | `Function` | The `fileTypeFromBuffer` function from the `file-type` package. |
+
+**Returns:** `Promise<string>` (The confirmed MIME type).
+**Throws:** `Error` if the signature is unknown or does not match the `expectedType`.
+
+---
+
+### 2. Layer 2 (Images): `validateImage` 🖼️
+
+Once the magic numbers are confirmed, use this to inspect the image's internal structure.
+
+**Purpose:** Uses the `sharp` engine to parse the image. This detects "Polyglot" files (files that are valid in two different formats) or files with corrupted headers designed to exploit image parsers.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `buffer` | `Buffer` | The raw image buffer. |
+| `Sharp` | `SharpConstructor` | The `sharp` constructor. |
+
+**Returns:** `Promise<ValidationResult<{ data: Sharp, metadata: SharpMetadata }>>`
+
+---
+
+### 3. Layer 2 (Audio/Video): `validateAudioVideo` 🎵
+
+For media files, we need to ensure the container (like MP3 or MP4) is actually intact.
+
+**Purpose:** Uses `music-metadata` to parse the container. It ensures the file contains valid audio/video streams and a valid duration.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `buffer` | `Buffer` | The raw media buffer. |
+| `parseBuffer` | `Function` | The `parseBuffer` function from `music-metadata`. |
+
+**Returns:** `Promise<ValidationResult<IAudioMetadata>>`
+
+---
+
+## 🚀 Implementation Guide: Daily Workflow
+
+To implement this in a real-world upload service, you should follow this sequential logic. **Do not skip Layer 1**, as Layer 2 is more computationally expensive.
+
+### 🛠️ Step-by-Step Integration
+
+1.  **Receive the file** as a Buffer from your upload middleware (e.g., Multer).
+2.  **Run `validateMagicNumbers`**: If this fails, reject the upload immediately.
+3.  **Branch by Type**:
+    *   If `mimeType` starts with `image/` $\rightarrow$ Call `validateImage`.
+    *   If `mimeType` is `audio/` or `video/` $\rightarrow$ Call `validateAudioVideo`.
+4.  **Handle the Result**: If the `error` property is present in the result, reject the upload and log the security event.
+
+### 💻 Code Example
+
+```javascript
+import { validateMagicNumbers, validateImage } from 'tiny-essentials/webTemplates/media/MediaValidator/v1/Node';
+import fileType from 'file-type';
+import sharp from 'sharp';
+
+async function handleUpload(fileBuffer, userExpectedType) {
+  try {
+    // STEP 1: Fast Check
+    const mimeType = await validateMagicNumbers({
+      buffer: fileBuffer,
+      expectedType: userExpectedType,
+      fileTypeFromBuffer: fileType.fileTypeFromBuffer
+    });
+
+    // STEP 2: Deep Check (if it's an image)
+    if (mimeType.startsWith('image/')) {
+      const result = await validateImage({
+        buffer: fileBuffer,
+        Sharp: sharp
+      });
+
+      if (result.error) {
+        console.error("❌ Image Security Violation:", result.error);
+        return { success: false, message: "Invalid image structure." };
+      }
+
+      console.log("✅ Image is safe and valid:", result.metadata.format);
+      return { success: true, data: result.data };
+    }
+
+    // ... handle audio/video similarly
+    
+  } catch (error) {
+    console.error("🚨 Security Block:", error.message);
+    return { success: false, message: error.message };
+  }
+}
+```
+
+## ⚠️ Security Notes
+
+*   **Error Handling:** The `ValidationResult` object is used to prevent the application from crashing during deep parsing. Always check `if (result.error)` before accessing `result.data`.
+*   **Performance:** Layer 2 functions are CPU-intensive. Always run them in a worker thread or ensure your server has adequate resources if handling high volumes of uploads.