tiny-essentials 1.19.3 → 1.20.1

package/docs/v1/libs/TinyHtml.md

@@ -310,6 +310,40 @@ HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLOptionElement
 
 ---
 
+## 🔨 Element Creation
+
+### `TinyHtml.createFrom(tagName, attrs?)`
+
+Creates a new `TinyHtml` element from a given tag name and optional attributes.
+
+* **Parameters**:
+
+  * `tagName` *(string)* — The HTML tag name (e.g., `'div'`, `'span'`, `'button'`).
+  * `attrs` *(object)* — *(optional)* Key-value pairs representing HTML attributes.
+
+* **Returns**: `TinyHtml` — A new `TinyHtml` instance representing the created element.
+
+* **Throws**:
+
+  * `TypeError` — If `tagName` is not a string.
+  * `TypeError` — If `attrs` is defined but not a plain object.
+
+### 💡 Example
+
+```js
+const div = TinyHtml.createFrom('div', { class: 'container' });
+const span = TinyHtml.createFrom('span', { id: 'my-span', title: null });
+```
+
+The method can also be aliased for convenience:
+
+```js
+const createElement = TinyHtml.createFrom;
+const button = createElement('button', { type: 'submit', class: 'btn' });
+```
+
+---
+
 ## 🔎 Static DOM Selectors
 
 These methods wrap native DOM query methods and return results as `TinyHtml` instances for consistency.
@@ -377,7 +411,7 @@ Finds the first element by CSS selector.
 ### `TinyHtml.queryAll(selector)`
 Finds all elements by CSS selector.
 
-- **Returns**: `TinyHtml[]`
+- **Returns**: `TinyHtml`
 
 ---
 
@@ -393,38 +427,64 @@ Selects an element by ID.
 ### `TinyHtml.getByClassName(selector)`
 Finds elements by class name.
 
-- **Returns**: `TinyHtml[]`
+- **Returns**: `TinyHtml`
 
 ---
 
 ### `TinyHtml.getByName(selector)`
 Finds elements by `name` attribute.
 
-- **Returns**: `TinyHtml[]`
+- **Returns**: `TinyHtml`
 
 ---
 
 ### `TinyHtml.getByTagNameNS(localName, namespaceURI?)`
 Finds elements by tag name in a namespace (defaults to XHTML).
 
-- **Returns**: `TinyHtml[]`
+- **Returns**: `TinyHtml`
 
 ---
 
 ## 🧩 Internal Element Access
 
-### `get()`
+### `exists(index)`
+Checks whether the element exists at the given index.
+
+- **Returns**: `boolean`
+
+---
+
+### `get(index)`
 Returns the raw DOM element associated with this instance.
 
 - **Returns**: `ConstructorElValues`
 
 ---
 
-### `_getElement(where)`
+### `extract(index)`
+Extracts a single DOM element from the internal list at the specified index.
+
+- **Returns**: `TinyHtml`
+
+---
+
+### `getAll()`
+Returns the current targets held by this instance.
+
+- **Returns**: `ConstructorElValues[]`
+
+---
+
+### `_getElement(where, index)`
 Safely returns the element with error checking.
 
 ---
 
+### `_getElements(where)`
+Returns the current Elements held by this instance.
+
+---
+
 ## 🛠️ Static Pre-Validation Utilities
 
 These methods normalize, validate, and prepare elements/nodes before operations. They're internal and mainly used inside the class.
@@ -1719,6 +1779,68 @@ TinyHtml.hasScroll(element);
 
 ---
 
+## 🧠 Property Name Normalization
+
+The object `TinyHtml.propFix` maps HTML attribute names (as strings) to their corresponding JavaScript DOM property names. This works similarly to jQuery’s `propFix`.
+
+```js
+TinyHtml.propFix['for'];   // "htmlFor"
+TinyHtml.propFix['class']; // "className"
+```
+
+⚠️ **Do not modify** the internal `#propFix` object directly. Instead, use `TinyHtml.propFix` (the public proxy) to ensure the reverse mapping in `TinyHtml.attrFix` stays in sync.
+
+### ✍️ Adding a New Property Mapping
+
+To add a new property normalization:
+
+```js
+TinyHtml.propFix['readonly'] = 'readOnly';
+```
+
+This will automatically make this available:
+
+```js
+TinyHtml.attrFix['readOnly']; // "readonly"
+```
+
+---
+
+## 🔁 Attribute ↔ Property Mapping
+
+### 🧭 `TinyHtml.getPropName(name)`
+
+Normalizes an HTML attribute name to its corresponding DOM property name.
+
+```js
+TinyHtml.getPropName('for');   // "htmlFor"
+TinyHtml.getPropName('class'); // "className"
+TinyHtml.getPropName('title'); // "title" (not mapped, returns input)
+```
+
+Useful when setting DOM properties programmatically.
+
+### 🧭 `TinyHtml.getAttrName(name)`
+
+Converts a DOM property name back to its equivalent HTML attribute name.
+
+```js
+TinyHtml.getAttrName('htmlFor');   // "for"
+TinyHtml.getAttrName('className'); // "class"
+TinyHtml.getAttrName('title');     // "title" (not mapped, returns input)
+```
+
+Useful when serializing an element back to HTML or attributes.
+
+### 🔄 Behind the Scenes
+
+* `TinyHtml.propFix` (public) is a proxy of the internal `#propFix` object.
+* `TinyHtml.attrFix` is auto-generated from `#propFix`, mapping values back in reverse.
+
+These mappings are kept **in sync automatically** whenever you assign a new property to `TinyHtml.propFix`.
+
+---
+
 ## 🎨 CSS Property Aliases (`cssPropAliases`)
 
 TinyHtml provides automatic conversion between `camelCase` and `kebab-case` style properties to simplify working with inline styles in HTML elements.

package/docs/v1/libs/TinyIframeEvents.md

@@ -0,0 +1,149 @@
+# 🧩 TinyIframeEvents
+
+A flexible event routing system for structured communication between a **parent window** and its **iframe** using postMessage.
+
+This module abstracts the complexity of origin validation, window detection, and message direction. It allows **modular, bidirectional, and secure communication** across frames.
+
+---
+
+## ✨ Features
+
+- 🔁 Bidirectional communication (`iframe` ⇄ `parent`)
+- 🎯 Named event routes with custom payloads
+- 🔐 Target window and origin validation
+- 🧠 Smart context detection (no config required inside iframe)
+- 🧹 Clean-up support with `.destroy()`
+
+---
+
+## 🚀 Usage
+
+### In the parent:
+
+```js
+import TinyIframeEvents from './TinyIframeEvents.mjs';
+
+const iframe = document.querySelector('iframe');
+
+const parentEvents = new TinyIframeEvents({
+  targetIframe: iframe, // Will use iframe.contentWindow
+  targetOrigin: window.location.origin
+});
+
+parentEvents.emit('hello:iframe', { text: '👋 From parent!' });
+
+parentEvents.on('reply:fromIframe', (data, event) => {
+  console.log('📨 Received from iframe:', data, event);
+});
+```
+
+---
+
+### In the iframe:
+
+```js
+import TinyIframeEvents from './TinyIframeEvents.mjs';
+
+const iframeEvents = new TinyIframeEvents();
+
+iframeEvents.on('hello:iframe', (data, event) => {
+  console.log('📥 Message from parent:', event);
+});
+
+iframeEvents.emit('reply:fromIframe', { text: '🙋‍♀️ Hi parent!' });
+```
+
+---
+
+## 🧠 API Reference
+
+### `new TinyIframeEvents(config?)`
+
+Creates a new instance for communication.
+
+#### Parameters:
+
+| Name           | Type                 | Description                                                           |
+| -------------- | -------------------- | --------------------------------------------------------------------- |
+| `targetIframe` | `HTMLIFrameElement?` | The iframe element to communicate with (used in the parent only).     |
+| `targetOrigin` | `string?`            | Expected origin (for security). Defaults to `window.location.origin`. |
+
+---
+
+### `emit(eventName, payload)`
+
+Sends a message to the target frame.
+
+| Param       | Type     | Description                                |
+| ----------- | -------- | ------------------------------------------ |
+| `eventName` | `string` | Unique identifier of the event.            |
+| `payload`   | `any`    | The data to send (any serializable value). |
+
+#### Throws:
+
+* `TypeError` if `eventName` is not a string.
+
+---
+
+### `on(eventName, handler)`
+
+Registers a listener for a specific event.
+
+```js
+iframeEvents.on('my:event', (payload, event) => {
+  // event = { origin, source }
+});
+```
+
+---
+
+### `destroy()`
+
+Removes all listeners and message event binding.
+Call this when the instance is no longer needed.
+
+```js
+iframeEvents.destroy();
+```
+
+---
+
+### `isDestroyed()`
+
+Returns `true` if the instance has been destroyed via `.destroy()`.
+
+```js
+if (events.isDestroyed()) {
+  console.warn('Event system is no longer active.');
+}
+```
+
+---
+
+## 🔒 Security Notes
+
+* Only messages with the flag `__tinyEvent: true` are accepted.
+* The source window is checked strictly (`source === targetWindow`).
+* Messages are ignored unless their `direction` matches the current side (`iframe` or `parent`).
+
+---
+
+## 📚 Internals (for advanced users)
+
+This class internally wraps:
+
+* postMessage
+* A minimal event router: `TinyEvents`
+
+---
+
+## 📄 Type Definitions
+
+### `@callback handler`
+
+```ts
+type handler = (
+  payload: any,
+  event: MessageEvent<any>
+) => void;
+```

package/docs/v1/libs/TinyNewWinEvents.md

@@ -0,0 +1,186 @@
+# 🪟 TinyNewWinEvents
+
+Structured and reliable `postMessage`-based communication between a **main window** and a **popup window** (created using `window.open`).
+Ideal for secure, bidirectional messaging with route-based logic.
+
+---
+
+## ✨ Features
+
+* 🔁 Bidirectional communication (`main window` ⇄ `popup`)
+* 📬 Named message routes with flexible payloads
+* 🕓 Queues messages before handshake is ready
+* 🧠 Connection and lifecycle status tracking
+* 🔒 Origin and window reference validation
+* 🧹 Full cleanup support with `.destroy()`
+
+---
+
+## 🚀 Usage
+
+### In the main window:
+
+```js
+import TinyNewWinEvents from './TinyNewWinEvents.mjs';
+
+const events = new TinyNewWinEvents({
+  url: '/popup.html',
+  name: 'MyPopupWindow',
+  features: 'width=400,height=400',
+  targetOrigin: window.location.origin
+});
+
+events.on('user:reply', (payload) => {
+  console.log('📩 From popup:', payload);
+});
+
+events.emit('init:data', { id: 123 });
+```
+
+---
+
+### In the popup window:
+
+```js
+import TinyNewWinEvents from './TinyNewWinEvents.mjs';
+
+const events = new TinyNewWinEvents();
+
+events.on('init:data', (payload) => {
+  console.log('📦 Init payload from main window:', payload);
+});
+
+events.emit('user:reply', { msg: '👋 Hello from popup!' });
+```
+
+---
+
+## 🧠 API Reference
+
+### `new TinyNewWinEvents(config?)`
+
+Creates a new communication instance.
+
+#### Parameters:
+
+| Name           | Type                     | Description                                        |
+| -------------- | ------------------------ | -------------------------------------------------- |
+| `url`          | `string?`                | URL to open in popup.                              |
+| `name`         | `string?`                | Name of the popup window .                         |
+| `features`     | `string?`                | `window.open` features string.                     |
+| `targetOrigin` | `string?`                | Expected origin (defaults to current origin)       |
+
+❗ `name: '_blank'` is **not allowed** for popup tracking.
+
+---
+
+### `emit(route, payload)`
+
+Sends a message on a specific route.
+
+| Param     | Type     | Description                     |
+| --------- | -------- | ------------------------------- |
+| `route`   | `string` | Event route name                |
+| `payload` | `any`    | Data to send (any serializable) |
+
+📝 If the handshake hasn't completed yet, the message is **queued**.
+
+---
+
+### `on(route, handler)`
+
+Registers a callback for a specific route.
+
+```js
+events.on('data:sync', (payload, event) => {
+  console.log(payload, event.origin);
+});
+```
+
+---
+
+### `off(route, handler)`
+
+Removes a previously registered route listener.
+
+---
+
+### `onClose(callback)`
+
+Runs when the **popup window** is closed.
+
+---
+
+### `offClose(callback)`
+
+Removes a previously registered close callback.
+
+---
+
+### `close()`
+
+Closes the popup window (can only be called from the host).
+
+---
+
+### `getWin()`
+
+Returns the current window reference (host or popup).
+
+---
+
+### `isConnected()`
+
+Returns `true` if both:
+
+* Handshake is complete
+* Window is still open
+
+---
+
+### `isDestroyed()`
+
+Returns `true` if the instance has been destroyed.
+
+---
+
+### `destroy()`
+
+Destroys the instance, cleans up all resources:
+
+* Stops polling
+* Removes all listeners
+* Clears queue
+
+---
+
+## 📦 Internals (for advanced use)
+
+| Concept         | Purpose                                     |
+| --------------- | ------------------------------------------- |
+| `postMessage`   | Core transport for messaging                |
+| `TinyEvents`    | Internal event emitter and listener manager |
+| `__TNE_READY__` | Handshake trigger message type              |
+| `__TNE_ROUTE__` | Route-based message delivery type           |
+
+---
+
+## 📄 Type Definitions
+
+### `@callback handler`
+
+```ts
+type handler = (
+  payload: any,
+  event: MessageEvent<any>
+) => void;
+```
+
+---
+
+## 🛡️ Safety and Validation
+
+* 💥 Throws if `emit()` is called after `.destroy()`
+* 💣 Throws if the popup was opened with `_blank` name
+* ✅ Only communicates with expected `targetOrigin`
+* 🧼 Automatically detects closed windows and emits `WINDOW_REF_CLOSED`

package/docs/v1/libs/TinyNotifyCenter.md

@@ -80,7 +80,7 @@ TinyNotifyCenter.insertTemplate();
 
 // Or insert at the end of <body>
 TinyNotifyCenter.insertTemplate('beforeend');
-````
+```
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.19.3",
+  "version": "1.20.1",
   "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.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",