tiny-essentials 1.28.18 → 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/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.18",
+  "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",