tiny-essentials 1.28.14 → 1.28.16

package/docs/v1/libs/{TinyAfterScrollWatcher.md → html/scroll/TinyAfterScrollWatcher.md}

@@ -19,7 +19,7 @@ Perfect for optimizing logic that should only run **after** the user has finishe
 ## 📦 Import
 
 ```js
-import TinyAfterScrollWatcher from 'tiny-essentials/libs/TinyAfterScrollWatcher';
+import TinyAfterScrollWatcher from 'tiny-essentials/libs/html/scroll/TinyAfterScrollWatcher';
 ```
 
 ---

package/docs/v1/libs/{TinyAnalogClock.md → html/templates/TinyAnalogClock.md}

@@ -19,7 +19,7 @@
 Import the class into your JavaScript module.
 
 ```javascript
-import TinyAnalogClock from 'tiny-essentials/libs/TinyAnalogClock';
+import TinyAnalogClock from 'tiny-essentials/libs/html/templates/TinyAnalogClock';
 ```
 
 ### 2. Basic Usage

package/docs/v1/libs/{TinyCookieConsent.md → html/templates/TinyCookieConsent.md}

@@ -135,7 +135,7 @@ Returns `false` if preferences are missing or category is not allowed.
 ## 🧩 Example Usage
 
 ```js
-import TinyCookieConsent from 'tiny-essentials/libs/TinyCookieConsent';
+import TinyCookieConsent from 'tiny-essentials/libs/html/templates/TinyCookieConsent';
 
 const consent = new TinyCookieConsent({
   message: "We use cookies to personalize your experience.",

package/docs/v1/libs/{TinyLoadingScreen.md → html/templates/TinyLoadingScreen.md}

@@ -121,7 +121,7 @@ loader.onChange = (status) => {
 ### Basic Example
 
 ```js
-import TinyLoadingScreen from 'tiny-essentials/libs/TinyLoadingScreen';
+import TinyLoadingScreen from 'tiny-essentials/libs/html/templates/TinyLoadingScreen';
 
 const loader = new TinyLoadingScreen();
 loader.defaultMessage = 'Loading...';

package/docs/v1/libs/{TinyMediaPlayer.md → media/TinyMediaPlayer.md}

@@ -48,16 +48,16 @@ You can integrate `TinyMediaPlayer` into your project using two methods: using t
 The library provides several optimized adapters for common media sources. You can import them and register them directly with your player instance.
 
 **Available Adapters:**
-* `YoutubeMediaAdapter` from `tiny-essentials/libs/TinyMediaPlayer/Youtube` (https://www.youtube.com/watch?v=XXXXXXXXXXX)
-* `SoundCloudMediaAdapter` from `tiny-essentials/libs/TinyMediaPlayer/SoundCloud` (https://api.soundcloud.com/tracks/XXXXXXXXX (From SoundCloud Embed))
-* `HtmlAudioAdapter` from `tiny-essentials/libs/TinyMediaPlayer/HtmlAudio`
-* `HtmlVideoAdapter` from `tiny-essentials/libs/TinyMediaPlayer/HtmlVideo`
+* `YoutubeMediaAdapter` from `tiny-essentials/libs/media/TinyMediaPlayer/Youtube` (https://www.youtube.com/watch?v=XXXXXXXXXXX)
+* `SoundCloudMediaAdapter` from `tiny-essentials/libs/media/TinyMediaPlayer/SoundCloud` (https://api.soundcloud.com/tracks/XXXXXXXXX (From SoundCloud Embed))
+* `HtmlAudioAdapter` from `tiny-essentials/libs/media/TinyMediaPlayer/HtmlAudio`
+* `HtmlVideoAdapter` from `tiny-essentials/libs/media/TinyMediaPlayer/HtmlVideo`
 
 **Example Usage:**
 ```javascript
-import TinyMediaPlayer from 'tiny-essentials/libs/TinyMediaPlayer';
-import { YoutubeMediaAdapter } from 'tiny-essentials/libs/TinyMediaPlayer/Youtube';
-import { HtmlAudioAdapter } from 'tiny-essentials/libs/TinyMediaPlayer/HtmlAudio';
+import TinyMediaPlayer from 'tiny-essentials/libs/media/TinyMediaPlayer';
+import { YoutubeMediaAdapter } from 'tiny-essentials/libs/media/TinyMediaPlayer/Youtube';
+import { HtmlAudioAdapter } from 'tiny-essentials/libs/media/TinyMediaPlayer/HtmlAudio';
 
 const player = new TinyMediaPlayer({
   persistVolume: true
@@ -82,7 +82,7 @@ If you need to support a service not covered by the pre-built adapters, you can
 
 **Example Implementation:**
 ```javascript
-import { BaseMediaAdapter } from 'tiny-essentials/libs/TinyMediaPlayer/Base';
+import { BaseMediaAdapter } from 'tiny-essentials/libs/media/TinyMediaPlayer/Base';
 
 /**
  * A custom adapter for a hypothetical streaming service.

package/docs/v1/libs/{TinyClipboard.md → text/TinyClipboard.md}

@@ -192,7 +192,7 @@ Gets the current function used for copying blobs.
 ## 🧠 Usage Example
 
 ```ts
-import TinyClipboard from 'tiny-essentials/libs/TinyClipboard';
+import TinyClipboard from 'tiny-essentials/libs/text/TinyClipboard';
 
 const clipboard = new TinyClipboard();
 

package/docs/v1/libs/{TinyTextDiffer.md → text/TinyTextDiffer.md}

@@ -21,7 +21,7 @@ It uses the **Longest Common Subsequence (LCS)** algorithm to ensure that change
 Since this is an ES Module, you can simply import it into your project:
 
 ```javascript
-import TinyTextDiffer from 'tiny-essentials/libs/TinyTextDiffer';
+import TinyTextDiffer from 'tiny-essentials/libs/text/TinyTextDiffer';
 
 const differ = new TinyTextDiffer(["Initial text", "Updated text!"]);
 

package/docs/v1/libs/{TinyTextarea.md → text/TinyTextarea.md}

@@ -17,7 +17,7 @@ A lightweight JavaScript utility for automatically resizing `<textarea>` element
 ## 🚀 Usage
 
 ```js
-import TinyTextarea from 'tiny-essentials/libs/TinyTextarea';
+import TinyTextarea from 'tiny-essentials/libs/text/TinyTextarea';
 
 const textarea = document.querySelector('textarea');
 

package/docs/v1/libs/{TinyClassManager → tools/TinyClassManager}/TinyPluginInliner.md

@@ -55,7 +55,7 @@ This is the file that uses the `TinyClassManager` to compose your final class.
 
 ```javascript
 // src/main.mjs
-import TinyClassManager from 'tiny-essentials/libs/TinyClassManager';
+import TinyClassManager from 'tiny-essentials/libs/tools/TinyClassManager';
 import { LoggerPlugin } from './plugins/LoggerPlugin.mjs';
 
 class BaseUser {}
@@ -72,7 +72,7 @@ export default User;
 Create a build script (e.g., `build.mjs`) to trigger the process.
 
 ```javascript
-import TinyPluginInliner from 'tiny-essentials/libs/TinyClassManager/TinyPluginInliner';
+import TinyPluginInliner from 'tiny-essentials/libs/tools/TinyClassManager/TinyPluginInliner';
 
 const builder = new TinyPluginInliner({
   entryPoint: 'src/main.mjs',

package/docs/v1/libs/{TinyClassManager.md → tools/TinyClassManager.md}

@@ -42,7 +42,7 @@ Let's break down exactly how to design, extend, and instantiate a class structur
 Every structure needs a solid foundation. The core class is the absolute minimum requirement and contains properties that every subsequent plugin might rely on.
 
 ```javascript
-import TinyClassManager from 'tiny-essentials/libs/TinyClassManager';
+import TinyClassManager from 'tiny-essentials/libs/tools/TinyClassManager';
 
 // The foundational class
 class EntityCore {

package/docs/v1/libs/{TinyDebugger.md → tools/TinyDebugger.md}

@@ -7,7 +7,7 @@
 To use `TinyDebugger`, import it into your project and initialize it with a configuration object.
 
 ```javascript
-import TinyDebugger from 'tiny-essentials/libs/TinyDebugger';
+import TinyDebugger from 'tiny-essentials/libs/tools/TinyDebugger';
 
 const debuggerInstance = new TinyDebugger({
   logger: console, // You can use standard console or a custom object

package/docs/v1/libs/tools/TinyPkgExportValidator.md

@@ -0,0 +1,234 @@
+# 📦 TinyPkgExportValidator
+
+`TinyPkgExportValidator` is a specialized utility designed to ensure that the paths defined in the `"exports"` field of your `package.json` file actually exist on your file system. 
+
+When developing Node.js packages, it is easy to misspell a path or forget to include a file in your repository. This tool automates the validation process, preventing "Module not found" errors for your end-users. 🚀
+
+## ✨ Key Features
+
+* **🔍 Automatic Traversal:** Recursively checks all nested paths in the `exports` object.
+* **🎨 Custom Reporting:** Completely redefine the terminal output using custom message templates.
+* **🤫 Silent Mode:** Suppress all console logs for clean integration into build scripts.
+* **🛠 Strict Validation:** High reliability through rigorous type checking and error handling.
+
+## 🔍 How it Works
+
+The validator performs a **recursive traversal** of the `exports` object in your `package.json`. 
+1. It identifies the keys (e.g., `import`, `require`, or sub-paths).
+2. It follows the nested structure.
+3. It resolves the final string paths relative to your project's root directory.
+4. It checks if each file/directory exists using the file system.
+
+---
+
+## 🚀 Quick Start
+
+To use the validator, you need to provide the absolute path to your `package.json` and the root directory of your project.
+
+### Example Implementation
+
+Create a script (e.g., `validate-exports.mjs`) in your project root:
+
+```javascript
+/**
+ * @fileoverview Script to validate if all paths defined in the 'exports' field
+ * of package.json exist physically within the project directory.
+ * @version 1.0.0
+ */
+
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+import TinyPkgExportValidator from 'tiny-essentials/libs/tools/TinyPkgExportValidator';
+
+// Helper to get __dirname in ES Modules
+const __dirname = resolve(process.cwd());
+
+/**
+ * Main execution function.
+ */
+async function main() {
+  // 1. Initialize the validator
+  const validator = new TinyPkgExportValidator(
+    resolve(__dirname, 'package.json'), // Path to your package.json
+    __dirname,                         // Your project root directory
+  );
+
+  try {
+    // 2. Load the package.json data
+    await validator.start();
+
+    // 3. Run the validation
+    const isValid = await validator.validate();
+
+    // 4. Exit with error code if validation fails (useful for CI/CD)
+    if (!isValid) {
+      console.error('❌ Validation failed! Please check the missing paths above.');
+      process.exit(1);
+    }
+
+    console.log('✅ Validation passed successfully!');
+  } catch (error) {
+    console.error('💥 An error occurred during validation:', error.message);
+    process.exit(1);
+  }
+}
+
+main();
+```
+
+### Advanced Usage (Customization)
+
+You can pass an `options` object to the constructor to personalize the validator.
+
+```javascript
+import { resolve } from 'path';
+import TinyPkgExportValidator from 'tiny-essentials/libs/tools/TinyPkgExportValidator';
+
+async function main() {
+  const validator = new TinyPkgExportValidator(
+    resolve(process.cwd(), 'package.json'),
+    process.cwd(),
+    {
+      projectName: 'My Awesome Library',
+      silent: false,
+      messages: {
+        header: `\n🚀 STARTING VALIDATION FOR: {projectName} 🚀\n`,
+        successHeader: `✨ Perfect! Everything is in place. ✨`,
+      }
+    }
+  );
+
+  await validator.start();
+  await validator.validate();
+}
+
+main();
+```
+
+---
+
+## 🛠 API Reference
+
+### `new TinyPkgExportValidator(packageJsonPath, rootDir, options)`
+
+**Constructor**
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `packageJsonPath` | `string` | Yes | Absolute path to your `package.json`. |
+| `rootDir` | `string` | Yes | The project root directory. |
+| `options` | `Object` | No | Configuration for customization. |
+
+#### `options` Object Properties
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `projectName` | `string` | `'Tiny-Essentials Export Validation'` | The name displayed in the report header. |
+| `silent` | `boolean` | `false` | If `true`, no console output is generated. |
+| `messages` | `Object` | `DEFAULT_MESSAGES` | Custom template strings for the report. |
+
+---
+
+### `async start()`
+
+**Method**
+
+Loads and parses the `package.json` file. This must be called before calling `validate()`.
+
+* **Returns:** `Promise<void>`
+* **Throws:** `TypeError` if the JSON is not an object; `Error` if the file cannot be read.
+
+---
+
+### `async validate()`
+
+**Method**
+
+The core logic. It traverses the `exports` field and checks the filesystem.
+
+* **Returns:** `Promise<boolean>` — Returns `true` if all exported paths exist; `false` if any are missing.
+
+---
+
+### `get results()`
+
+**Getter**
+
+Returns a detailed list of the validation results.
+
+* **Returns:** `Array<{path: string, valid: boolean, errorPath?: string}>`
+    * `path`: The key context (e.g., `import -> ./dist/index.js`).
+    * `valid`: `true` if the file exists, `false` otherwise.
+    * `errorPath`: (Optional) The actual path that was missing.
+
+---
+
+### 📝 Customizing Messages (Templates)
+
+The `messages` option allows you to override the default output. You can use **placeholders** within your strings to inject dynamic data at runtime.
+
+#### Available Placeholders:
+* `{projectName}`: The name provided in `options.projectName`.
+* `{path}`: The key path being validated (e.g., `import -> ./dist/index.js`).
+* `{errorPath}`: The actual missing file path.
+* `{errorCount}`: The total number of failed exports.
+* `{message}`: The specific error message (used in unexpected errors).
+
+#### Message Keys to Override:
+To ensure a valid custom message object, you must provide all the following keys:
+
+| Key | Description |
+| :--- | :--- |
+| `header` | The top of the report. |
+| `divider` | The line separating the report parts. |
+| `itemValid` | Message for a successful check. |
+| `itemInvalid` | Message for a failed check. |
+| `itemMissing` | Message showing the missing path. |
+| `successHeader` | Final message on total success. |
+| `failureHeader` | Final message on failure. |
+| `errorLoad` | Error if `package.json` isn't loaded. |
+| `noExports` | Warning if `"exports"` field is missing. |
+| `errorNotFound` | Error if `package.json` file is missing. |
+| `errorParse` | Error if `package.json` is invalid JSON. |
+| `errorUnexpected`| Error for any other runtime exception. |
+
+
+---
+
+## 📊 Console Output
+
+The validator provides high-visibility feedback in your terminal using ANSI colors.
+
+### ✅ Successful Validation
+If everything is correct, you will see:
+```text
+=== Tiny-Essentials Export Validation ===
+
+  [✔] import -> ./dist/main.js
+  [✔] require -> ./dist/main.cjs
+
+-----------------------------------------
+SUCCESS: All exports are correctly mapped.
+```
+
+### ❌ Failed Validation
+If a file is missing, the output will clearly identify the failure:
+```text
+=== Tiny-Essentials Export Validation ===
+
+  [✔] import -> ./dist/main.js
+  [✘] require -> ./dist/main.cjs
+      Missing: ./dist/main.cjs
+
+-----------------------------------------
+FAILURE: 1 export(s) are missing or invalid.
+```
+
+## ⚠️ Error Handling
+
+The validator provides specific feedback for common issues:
+1. **`errorLoad`**: Attempted to validate before calling `.start()`.
+2. **`noExports`**: The `package.json` exists, but the `"exports"` field is missing.
+3. **`errorNotFound`**: The file at `packageJsonPath` does not exist.
+4. **`errorParse`**: The `package.json` file contains syntax errors.
+5. **`errorUnexpected`**: Any other error (e.g., permission issues).

package/docs/v1/libs/{TinyPromiseQueue.md → utils/TinyPromiseQueue.md}

@@ -108,7 +108,7 @@ Cancels a scheduled delay and removes the task from the queue. Adds the ID to a
 ## Usage Example 💻
 
 ```js
-import { TinyPromiseQueue } from 'tiny-essentials/libs/TinyPromiseQueue';
+import { TinyPromiseQueue } from 'tiny-essentials/libs/utils/TinyPromiseQueue';
 
 const queue = new TinyPromiseQueue();
 
@@ -142,7 +142,7 @@ setTimeout(() => {
 ```
 
 ```js
-import { TinyPromiseQueue } from 'tiny-essentials/libs/TinyPromiseQueue';
+import { TinyPromiseQueue } from 'tiny-essentials/libs/utils/TinyPromiseQueue';
 
 const queue = new TinyPromiseQueue();
 await new Promise((resolve) => {