tiny-essentials 1.21.9 → 1.22.0

package/dist/v1/libs/TinyInventory.d.mts

@@ -328,7 +328,7 @@ declare class TinyInventory {
      * Keys are item IDs, values are configuration objects created with {@link TinyInventory.defineItem}.
      * @type {Map<string, ItemDef>}
      */
-    static "__#27@#ItemRegistry": Map<string, ItemDef>;
+    static "__#28@#ItemRegistry": Map<string, ItemDef>;
     /**
      * Returns a deep-cloned snapshot of all registered items.
      * Ensures the caller cannot mutate the internal registry.

package/dist/v1/libs/UltraRandomMsgGen.d.mts

@@ -160,23 +160,23 @@ export type MsgGenConfig = {
  */
 declare class UltraRandomMsgGen {
     /** @type {string[]} */
-    static "__#12@#defaultWords": string[];
+    static "__#13@#defaultWords": string[];
     /** @type {string[]} */
-    static "__#12@#defaultEmojis": string[];
+    static "__#13@#defaultEmojis": string[];
     /** @type {string[]} */
-    static "__#12@#defaultNouns": string[];
+    static "__#13@#defaultNouns": string[];
     /** @type {string[]} */
-    static "__#12@#defaultVerbs": string[];
+    static "__#13@#defaultVerbs": string[];
     /** @type {string[]} */
-    static "__#12@#defaultAdjectives": string[];
+    static "__#13@#defaultAdjectives": string[];
     /** @type {string[]} */
-    static "__#12@#defaultTemplates": string[];
+    static "__#13@#defaultTemplates": string[];
     /**
      * Utility to validate arrays before setting.
      * @param {any} value
      * @param {string} field
      */
-    static "__#12@#validateArray"(value: any, field: string): void;
+    static "__#13@#validateArray"(value: any, field: string): void;
     /** @param {string[]} value */
     static set defaultWords(value: string[]);
     /** @returns {string[]} */

package/docs/v1/README.md

@@ -57,6 +57,7 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🌐 **[TinyI18](./libs/TinyI18.md)** — A flexible i18n manager supporting local and file modes, regex-based keys, function-based entries, string interpolation, and safe helper functions for advanced rendering.
 - 🎮 **[TinyNeedBar](./libs/TinyNeedBar.md)** — A versatile "need bar" system for simulating decay over time with multiple configurable factors, serialization, cloning, and full control over clamped and infinite values.
 - 🎲 **[TinySimpleDice](./libs/TinySimpleDice.md)** — A lightweight and flexible dice rolling utility with configurable maximum values, zero allowance, and array/Set index rolling support.
+- 👀 **[TinyElementObserver](./libs/TinyElementObserver.md)** — A DOM mutation tracking utility built on MutationObserver, with customizable detectors for handling changes, event dispatching, and lifecycle management.  
 
 ### 3. **`fileManager/`**
 * 📁 **[Main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.
@@ -69,6 +70,14 @@ To get started, navigate to the appropriate directory and explore the files list
 
 ---
 
+## 📖 More Regex Goodies
+
+Looking for practical regex examples and migration helpers?
+
+👉 Check out the **[`Regex-Helpers`](Regex-Helpers.md)** file for a full collection of ready-to-use regex transformations!
+
+---
+
 ## 📑 Contributing
 
 Feel free to suggest changes, improvements, or additional features. You can fork the repository and submit a pull request!

package/docs/v1/Regex-Helpers.md

@@ -0,0 +1,72 @@
+# 🔍 Regex Helpers
+
+Welcome to the **Regex Helpers** guide! ✨
+This document provides a collection of **ready-to-use regex patterns** to help you **transform JavaScript code** more efficiently.
+It’s especially useful when **migrating from jQuery to TinyHtml**, making your workflow faster, cleaner, and less error-prone. 🚀
+
+👉 These helpers were tested only in **Visual Studio Code**, so results may vary in other editors.
+
+---
+
+## ⚡ Basic Function Replacements
+
+Simplify and streamline JavaScript function transformations.
+
+**🔄 Replace `attr`:**
+
+```ruby
+attr\(([^,]+),\s*([^)]+)\)
+```
+
+➡️ with `setAttr`:
+
+```ruby
+setAttr($1, $2)
+```
+
+---
+
+## 🛠️ Migrating from jQuery to TinyHtml
+
+### 📥 Match jQuery with arguments
+
+```ruby
+\$\(\s*['"]<([^'"]+)>['"]\s*,\s*([\s\S]*?)\)
+\$\((?:\s|\n)*['"]<([^'"]+)>['"](?:\s|\n)*,(?:\s|\n)*([\s\S]*?)(?:\s|\n)*\)
+```
+
+➡️ Replace with:
+
+```ruby
+TinyHtml.createFrom('$1', $2)
+```
+
+---
+
+### 📦 Match jQuery without arguments
+
+```ruby
+\$\(\s*['"]<([^'"]+)>['"]\s*\)
+\$\((?:\s|\n)*['"]<([^'"]+)>['"](?:\s|\n)*\)
+```
+
+➡️ Replace with:
+
+```ruby
+TinyHtml.createFrom('$1')
+```
+
+---
+
+### 🔎 Match jQuery queries
+
+```ruby
+\$\(\s*['"]([^'"]+)['"]\s*\)
+\$\((?:\s|\n)*['"]([^'"]+)['"](?:\s|\n)*\)
+```
+
+➡️ Replace with:
+
+```ruby
+TinyHtml.query('$1')
+```

package/docs/v1/basics/array.md

@@ -95,3 +95,23 @@ Generates a flattened array with phases repeated according to the specified coun
 multiplyArrayBlocks(['Full', 'Half1', 'Half2', 'New'], [4, 5, 5, 4]);
 // ➡ ['Full','Full','Full','Full','Half1','Half1','Half1','Half1','Half1', ...]
 ```
+
+---
+
+## 🔀 `diffArrayList(oldItems, newItems)`
+
+Compares two arrays and determines which items were **added** and which were **removed**.
+
+* **`oldItems`** 📜 — Array of original class names.
+* **`newItems`** 📜 — Array of updated class names.
+* **Returns** 📦 — An object with two arrays:
+
+  * `added` → classes that exist in `newItems` but not in `oldItems`.
+  * `removed` → classes that exist in `oldItems` but not in `newItems`.
+
+**Example:**
+
+```js
+diffArrayList(['btn', 'active'], ['btn', 'disabled']);
+// ➡ { added: ['disabled'], removed: ['active'] }
+```

package/docs/v1/basics/text.md

@@ -39,21 +39,23 @@ toTitleCaseLowerFirst('hello world'); // → "hello World"
 
 ---
 
-## 🎯 `addAiMarkerShortcut(key = 'a')`
+## 🎯 `addAiMarkerShortcut({ key = 'a', className = 'detect-made-by-ai' })`
 
-Enables a keyboard shortcut (`Ctrl + Alt + [key]`) that toggles a CSS class on the `<body>` element. Useful for marking or highlighting AI-generated content dynamically.
+Enables a keyboard shortcut (`Ctrl + Alt + [key]`) that toggles a CSS class on the `<body>` element.
+Useful for marking or highlighting AI-generated content dynamically.
 
 ### 🔤 Syntax
 
-```js
-addAiMarkerShortcut(key)
+```ts
+addAiMarkerShortcut({ key, className }) : function
 ```
 
 ### 🧾 Parameters
 
-| Name  | Type     | Default | Description                                                                  |
-| ----- | -------- | ------- | ---------------------------------------------------------------------------- |
-| `key` | `string` | `'a'`   | The character key to use in combination with `Ctrl + Alt`. Case-insensitive. |
+| Name        | Type     | Default               | Description                                                                  |
+| ----------- | -------- | --------------------- | ---------------------------------------------------------------------------- |
+| `key`       | `string` | `'a'`                 | The character key to use in combination with `Ctrl + Alt`. Case-insensitive. |
+| `className` | `string` | `'detect-made-by-ai'` | The CSS class name to toggle on the `<body>` element.                        |
 
 ### ⚙️ Behavior
 
@@ -157,3 +159,32 @@ const longText = "This is a sample sentence that will be trimmed properly.";
 console.log(safeTextTrim(longText, 30));
 // Output: "This is a sample sentence that..."
 ```
+
+---
+
+## 🔎 `diffStrings(oldStrings, newStrings)`
+
+Compares two **style objects** and identifies which properties were **added**, **removed**, or **modified**.
+
+* **`oldStrings`** 🎨 — Record of string values (original state).
+* **`newStrings`** 🎨 — Record of string values (new state).
+* **Returns** 📦 — An object with three sub-objects:
+
+  * `added` → new properties not present before.
+  * `removed` → properties that no longer exist.
+  * `modified` → properties whose values have changed (with `old` and `new`).
+
+**Example:**
+
+```js
+diffStrings(
+  { color: 'red', display: 'block' },
+  { color: 'blue', visibility: 'hidden' }
+);
+
+// ➡ {
+//   added: { visibility: 'hidden' },
+//   removed: { display: 'block' },
+//   modified: { color: { old: 'red', new: 'blue' } }
+// }
+```

package/docs/v1/libs/TinyElementObserver.md

@@ -0,0 +1,107 @@
+# 📌 TinyElementObserver
+
+A utility class for tracking **DOM element mutations** 🧬.
+It leverages the native `MutationObserver` API, providing a higher-level abstraction with a configurable **detector system** ⚙️ that can dispatch custom events or run custom logic.
+
+---
+
+## 🔹 Callback Type
+
+### `ElementDetectorsFn`
+
+```ts
+type ElementDetectorsFn = (
+  mutation: MutationRecord,        // Single mutation being processed
+  index: number,                   // Index of the mutation in the batch
+  mutations: MutationRecord[]      // Full list of mutation records
+) => void;
+```
+
+---
+
+## 🔹 Constructor
+
+```ts
+new TinyElementObserver({
+  el?: Element,
+  initDetectors?: Array<[string, ElementDetectorsFn]>,
+  initCfg?: MutationObserverInit
+})
+```
+
+* **`el`** *(optional)* → Initial element to observe 🏷️
+* **`initDetectors`** *(optional)* → Array of detectors to register on creation 🎛️
+* **`initCfg`** *(optional)* → Initial `MutationObserverInit` configuration ⚙️
+
+---
+
+## 🔹 Properties
+
+| Property    | Type                                  | Description                                               |
+| ----------- | ------------------------------------- | --------------------------------------------------------- |
+| `el`        | `Element \| undefined`                | The DOM element being observed. Can only be set once. 🏗️ |
+| `settings`  | `MutationObserverInit`                | Observer configuration object. 🔧                         |
+| `observer`  | `MutationObserver \| null`            | Internal observer instance.                               |
+| `detectors` | `Array<[string, ElementDetectorsFn]>` | List of registered detectors.                             |
+| `isActive`  | `boolean`                             | `true` if the observer is running. 🚦                     |
+| `size`      | `number`                              | Total number of registered detectors. 📊                  |
+
+---
+
+## 🔹 Methods
+
+### 🎛️ Detector Management
+
+* **`add(name, handler)`** → Add detector at the end of the list.
+* **`insertAtStart(name, handler)`** → Add detector at the start of the list.
+* **`insertAt(index, name, handler, position = "after")`** → Insert detector before or after a given index.
+* **`removeAt(index)`** → Remove detector at index.
+* **`removeAround(index, before = 0, after = 0)`** → Remove detectors around an index.
+* **`isIndexUsed(index)`** → Check if an index has a detector.
+* **`hasHandler(handler)`** → Check if a handler already exists.
+* **`clear()`** → Remove all detectors.
+
+---
+
+### 📡 Observation Control
+
+* **`start()`** → Begin tracking mutations on the defined element.
+  ⚠️ Throws if no element is set.
+
+* **`stop()`** → Stop tracking mutations.
+
+* **`destroy()`** → Stop observer and clear all detectors. Leaves the instance unusable until reconfigured. 💀
+
+---
+
+## 🔹 Example Usage
+
+```js
+import TinyElementObserver from './TinyElementObserver.js';
+
+// Define a detector
+const logDetector = (mutation, index, mutations) => {
+  console.log(`🔍 Mutation detected [${index + 1}/${mutations.length}]:`, mutation);
+};
+
+// Create instance
+const observer = new TinyElementObserver({
+  el: document.querySelector('#target'),
+  initDetectors: [['logger', logDetector]],
+  initCfg: { childList: true, subtree: true }
+});
+
+// Start observing
+observer.start();
+
+// Add another detector
+observer.add('attrChange', (mutation) => {
+  if (mutation.type === 'attributes') {
+    console.log(`⚡ Attribute changed: ${mutation.attributeName}`);
+  }
+});
+```
+
+---
+
+✨ With **TinyElementObserver**, you can easily manage multiple detectors, control observation lifecycle, and create powerful mutation-driven logic with minimal boilerplate.