tiny-essentials 1.19.3 → 1.20.0

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.0",
   "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",