tiny-essentials 1.28.17 → 1.28.19

package/docs/v1/Exports.md

@@ -225,6 +225,16 @@ Each library can be imported separately:
 
 ---
 
+## 🎨 Web Templates
+
+### Bootstrap 5.3 🅱️
+
+* `webTemplates/bootstrap/5.3/html/BootstrapDialogs`
+* `webTemplates/bootstrap/5.3/scss/input/Placeholder-Colors-Fix.scss`
+* `webTemplates/bootstrap/5.3/scss/spacing/Spacing-Plus.scss`
+
+---
+
 ## ✅ Import Examples
 
 **ESM (modern projects)**

package/docs/v1/README.md

@@ -123,7 +123,13 @@ Here, you can navigate through different sections of the project. Below are the
 * ⚙️ **[TinyClassManager](./libs/tools/TinyClassManager.md)** — A lightweight, immutable manager designed to linearly compose a base class with multiple modular plugins, featuring automatic dependency verification and duplicate conflict protection.
 * 🛠️ **[TinyPluginInliner](./libs/tools/TinyClassManager/TinyPluginInliner.md)** — A powerful build-time utility that inlines plugin code into a single bundle, automatically rewriting import paths and hoisting dependencies for seamless deployment.
 
-### 3. **`fileManager/`**
+### 3. **`webTemplates/`**
+
+#### 3.1. **`webTemplates/bootstrap/`**
+
+- 🖼️ **[BootstrapDialogs](./webTemplates/bootstrap/5.3/html/BootstrapDialogs.md)** — An asynchronous JavaScript utility designed to replace native browser dialogs with customizable Bootstrap 5 Modals.
+
+### 4. **`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/libs/media/TinyRadioFm.md

@@ -12,9 +12,9 @@
 * **🎵 Dual-Stream Logic:** Manages separate playlists for `music` and `voice`, with configurable interaction rules (e.g., playing voices after music).
 * **📅 Scheduled Mutations:** Schedule tasks to `add`, `remove`, or `move` items in the playlist at specific future timestamps.
 * **⚡ Custom Injections:** Inject "Custom Positions" into the timeline that interrupt the standard cycle.
-* **🧠 Smart Queuing:** Intelligent logic to prevent audio overlaps by automatically adjusting timestamps to the end of currently playing content.
+* **🧠 Smart Queuing:** Intelligent logic to prevent audio overlaps by automatically adjusting timestamps to the end of the currently playing content.
 * **💾 State Persistence:** Full export/import capabilities, including automatic conversion of Blob URLs to Base64 for easy storage.
-* **🧹 Memory Management:** Proactive cleanup of Blob URLs and event listeners to prevent memory leaks.
+* **🧹 Memory Management:** Proactive cleanup of Blob URLs and event listeners to prevent memory leaks, with configurable optimization for media and pictures.
 
 ---
 
@@ -31,6 +31,7 @@ The behavior of the engine is controlled via the `RadioConfig` object.
 | `voiceAfterMusic` | `boolean` | `true` | If `true`, voice messages play after music tracks. |
 | `voiceMin` | `number` | `0` | Minimum number of voice messages to play in a cycle. |
 | `voiceMax` | `number` | `1` | Maximum number of voice messages to play in a cycle. |
+| `voiceWeight` | `number` | `1` | Weight used to calculate the probability of a voice block occurring ($P = W / (W + 1)$). |
 | `musicMinConsecutive`| `number` | `0` | Min times a music track must repeat consecutively. |
 | `musicMaxConsecutive`| `number` | `0` | Max consecutive music repeats (`-1` = unlimited, `0` = no repeats). |
 | `voiceMinConsecutive`| `number` | `0` | Min times a voice track must repeat consecutively. |
@@ -50,11 +51,41 @@ Prepares a `MediaContent` object by extracting metadata from an audio source.
     * `metadata`: Optional manual overrides.
     * `parseFile`: Internal helper for file parsing.
     * `callbacks`: Object containing `onProgress` and `onError` handlers.
-    * `convertBase64toBlob`: If true, the image content will be converted directly into a high-performance Blob URL, use this method.
+    * `convertBase64toBlob`: If true, the image content will be converted directly into a high-performance Blob URL.
 * **Returns:** `Promise<MediaContent>`
 * **Throws:** `MediaLoadingError`
 
----
+#### `static get/set unknownArtist(value)`
+Gets or sets the identifier used when an artist cannot be determined.
+* **Value:** A `string` or a `function` that returns a `string`.
+* **Throws:** `TypeError` if the value is not a string or a function.
+
+### 📋 Properties (Getters & Setters)
+
+#### **System State & Lifecycle**
+* `destroyed`: Returns `true` if the instance has been destroyed.
+* `size`: Total count of all content items (music + voice).
+* `seed`: Gets/Sets the core randomness seed.
+* `anchorDate`: Gets the absolute timestamp used as the timeline anchor.
+* `cycleCacheSize`: Returns the number of items currently stored in the cycle cache.
+
+#### **Playlist Access (Returns Deep Clones)**
+* `musicList`: Returns a deep clone of the music playlist.
+* `voiceList`: Returns a deep clone of the voice playlist.
+* `allList`: Returns a deep clone of the combined music and voice playlists.
+* `customPositions`: Returns a deep clone of the custom position injections.
+* `scheduledTasks`: Returns a deep clone of the pending scheduled tasks.
+
+#### **Counters**
+* `musicSize`: Total number of items in the music playlist.
+* `voiceSize`: Total number of items in the voice playlist.
+* `customPosSize`: Number of active custom position injections.
+* `tasksSize`: Number of pending scheduled tasks.
+
+#### **Configuration & Optimization**
+* `config`: Gets/Sets the current `RadioConfig` object.
+* `optimizeMediaMemory`: Gets/Sets whether Blob URLs for media should be converted to Base64 during export.
+* `optimizePictureMemory`: Gets/Sets whether Blob URLs for pictures should be converted to Base64 during export.
 
 ### 📥 Content Management
 
@@ -67,12 +98,10 @@ Adds new content to the engine immediately.
 * **Emits:** `contentAdded`
 
 #### `remove(id)`
-Instantly removes content by its unique ID across all lists, custom positions, and pending tasks. It also revokes associated Blob URLs.
+Instantly removes content by its unique ID across all lists, custom positions, and pending tasks. It also revokes associated Blob URLs to free memory.
 * **Parameters:** `id` (string)
 * **Emits:** `contentRemoved`
 
----
-
 ### 📅 Task & Config Management
 
 #### `scheduleTask(timestamp, action, type, payload, smartQueue = true)`
@@ -90,8 +119,6 @@ Performs a partial or full update of the engine configuration.
 * **Parameters:** `config` (Partial or full `RadioConfig` object).
 * **Emits:** `configChanged`
 
----
-
 ### 🔍 Timeline & Querying
 
 #### `getCurrentEvent()`
@@ -106,7 +133,9 @@ Predicts upcoming events from a specific date forward using a virtual sandbox to
 * **Returns:** `RadioEvent[]`
 * **Throws:** `TypeError` or `RangeError` if limit is invalid.
 
----
+#### `searchCustomPositions()`
+Returns a shallow copy of all active custom positions currently injected into the timeline.
+* **Returns:** `CustomPosition[]`
 
 ### 💾 Persistence & Lifecycle
 
@@ -161,4 +190,4 @@ A structural block representing a single full iteration of the radio sequence.
 * `lastMusicId`: ID of the last music played in this block.
 * `musicConsecutiveCount`: Current consecutive count for music.
 * `lastVoiceId`: ID of the last voice played in this block.
-* `voiceConsecutiveCount`: Current consecutive count for voice.
+* `voiceConsecutiveCount`: Current consecutive count for voice.

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

@@ -0,0 +1,162 @@
+# 🚀 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.
+*   **🧹 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 individual dialog calls.
+| 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('Are you sure you want to delete this?');
+    ```
+
+### ⌨️ `prompt(message, defaultValue, options)`
+Displays a modal with a text input field.
+*   **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)`
+Displays a global, non-dismissible loading spinner.
+*   **Returns:** `void`
+*   **Usage:** `showLoading('Fetching data...');`
+
+### ✅ `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.28.17",
+  "version": "1.28.19",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "bin": {
     "tiny-essentials-fork": "./TinyFork.mjs"
@@ -18,8 +18,9 @@
     "test:mjs:levelup": "node test/index.mjs levelUp",
     "test:mjs:filemanager": "node test/index.mjs fileManager",
     "test:mjs:i18": "node test/index.mjs i18",
-    "fix:prettier": "npm run fix:prettier:src && npm run fix:prettier:test && npm run fix:prettier:rollup.config && npm run fix:prettier:webpack.config && npm run fix:prettier:tiny_fork && npm run fix:prettier:check_exports",
+    "fix:prettier": "npm run fix:prettier:src && npm run fix:prettier:build && npm run fix:prettier:test && npm run fix:prettier:rollup.config && npm run fix:prettier:webpack.config && npm run fix:prettier:tiny_fork && npm run fix:prettier:check_exports",
     "fix:prettier:src": "prettier --write ./src/*",
+    "fix:prettier:build": "prettier --write ./build/*",
     "fix:prettier:test": "prettier --write ./test/*",
     "fix:prettier:rollup.config": "prettier --write ./rollup.config.mjs",
     "fix:prettier:webpack.config": "prettier --write ./webpack.config.mjs",
@@ -31,12 +32,7 @@
     "build:js": "tsc -p tsconfig.json && rollup -c && webpack --mode production",
     "build-clean": "npm run clean && npm run build",
     "build-dist": "npm run build",
-    "build:css": "npm run build:css:aimaker && npm run build:css:tinynotify && npm run build:css:tinydragger:example && npm run build:css:tinycookieconsent && npm run build:css:tinyloadingscreen",
-    "build:css:tinydragger:example": "sass src/v1/scss/TinyDraggerExample.scss dist/v1/css/TinyDraggerExample.min.css --no-source-map --style=compressed",
-    "build:css:aimaker": "sass src/v1/scss/aiMarker.scss dist/v1/css/aiMarker.min.css --no-source-map --style=compressed",
-    "build:css:tinynotify": "sass src/v1/scss/TinyNotify.scss dist/v1/css/TinyNotify.min.css --no-source-map --style=compressed",
-    "build:css:tinycookieconsent": "sass src/v1/scss/TinyCookieConsent.scss dist/v1/css/TinyCookieConsent.min.css --no-source-map --style=compressed",
-    "build:css:tinyloadingscreen": "sass src/v1/scss/TinyLoadingScreen.scss dist/v1/css/TinyLoadingScreen.min.css --no-source-map --style=compressed",
+    "build:css": "node build/sass.mjs && node build/scss.mjs",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build"
   },
@@ -50,10 +46,16 @@
     "./css/TinyDraggerExample.min.css": "./dist/v1/css/TinyDraggerExample.min.css",
     "./css/TinyNotify.min.css": "./dist/v1/css/TinyNotify.min.css",
     "./css/TinyLoadingScreen.min.css": "./dist/v1/css/TinyLoadingScreen.min.css",
+    "./webTemplates/bootstrap/5.3/scss/input/Placeholder-Colors-Fix.scss": "./dist/v1/webTemplates/bootstrap/5.3/scss/input/Placeholder-Colors-Fix.scss",
+    "./webTemplates/bootstrap/5.3/scss/spacing/Spacing-Plus.scss": "./dist/v1/webTemplates/bootstrap/5.3/scss/spacing/Spacing-Plus.scss",
     ".": {
       "require": "./dist/v1/index.cjs",
       "import": "./dist/v1/index.mjs"
     },
+    "./webTemplates/bootstrap/5.3/html/BootstrapDialogs": {
+      "require": "./dist/v1/webTemplates/bootstrap/5.3/html/BootstrapDialogs.cjs",
+      "import": "./dist/v1/webTemplates/bootstrap/5.3/html/BootstrapDialogs.mjs"
+    },
     "./basics": {
       "require": "./dist/v1/basics/index.cjs",
       "import": "./dist/v1/basics/index.mjs"
@@ -621,11 +623,13 @@
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
+    "@types/bootstrap": "^5.2.11",
     "@types/lodash": "^4.17.16",
     "@types/md5": "^2.3.6",
     "@types/node": "^26.1.0",
     "@types/node-fetch": "^2.6.12",
     "babel-preset-es2015": "^6.24.1",
+    "bootstrap": "^5.3.8",
     "buffer": "^6.0.3",
     "esbuild": "^0.28.1",
     "express": "^5.1.0",
@@ -638,6 +642,7 @@
     "rollup-preserve-directives": "^1.1.3",
     "safe-stable-stringify": "^2.5.0",
     "sass": "^1.101.0",
+    "sass-embedded": "^1.102.0",
     "tslib": "^2.8.1",
     "type-fest": "^5.7.0",
     "typescript": "^7.0.2",