@withalleo/ewidget-utils 1.0.9 → 1.0.12

package/README.md

@@ -26,7 +26,7 @@ This package ships a browser bundle at `@withalleo/ewidget-utils/browser` (UMD).
         <script src="https://unpkg.com/@withalleo/ewidget-utils/dist/ewidget-utils.umd.cjs"></script>
         <script>
             const alleo = AlleoEWidget.getEmbedWidgetMessenger({ debug: true })
-            
+
             document.getElementById('button').onclick = () =>
                 alleo.addContent({ type: 'notepad', textFormat: 'markdown', text: '# Status\n\nAll systems go.' })
         </script>
@@ -34,6 +34,176 @@ This package ships a browser bundle at `@withalleo/ewidget-utils/browser` (UMD).
 </html>
 ```
 
+#### Commands
+
+**Outgoing (iframe -> widget)**
+
+- `EmbedWidgetCommandMap` defines the `command` names and their `params` shapes:
+    - `triggerAction`, `addContent`, `requestSyncedStatus`, `setSyncedStatus`.
+- `EmbedWidgetCommandEnvelope` is the outbound `postMessage` payload shape:
+    - `{ type: 'EmbedWidgetCommand', command, params }`.
+
+**Outgoing examples**
+
+```js
+messenger.triggerAction('demo', {
+    'demo-param': 'Hello from iframe',
+})
+```
+
+```js
+messenger.addContent({
+    type: 'notepad',
+    textFormat: 'markdown',
+    text: '# Status\n\nAll systems go.',
+})
+```
+
+```js
+messenger.requestSyncedStatus()
+```
+
+```js
+messenger.setSyncedStatus({
+    color: '#FFAA33',
+})
+```
+
+#### Message envelopes
+
+**Incoming (widget -> iframe)**
+
+- `EmbedWidgetMessageMap` defines inbound `command` names and `params` shapes:
+    - `syncedStatusUpdate`, `incomingAction`.
+- `EmbedWidgetMessageEnvelope` is the inbound message shape:
+    - `{ type: 'EmbedWidgetMessage', command, params }`.
+- `EmbedWidgetMessageEvent` is the normalized event passed to `onMessage` handlers:
+    - `{ command, params, raw }`.
+
+**Incoming examples (one per event)**
+
+```js
+messenger.onSyncedStatusUpdate((status) => {
+    console.log('synced status', status)
+})
+```
+
+```js
+messenger.onIncomingAction(({ actionId, data }) => {
+    console.log('incoming action', actionId, data)
+})
+```
+
+## API Reference
+
+### Exported helpers
+
+#### `getAlleoEwidgetUtils(options?: AlleoEwidgetUtilsOptions): AlleoEwidgetUtils`
+
+Returns a singleton instance of `AlleoEwidgetUtils`. If a browser global singleton already exists, the existing instance is reused.
+
+#### `getEmbedWidgetMessenger(options?: EmbedWidgetMessengerOptions): EmbedWidgetMessenger`
+
+Convenience helper that returns `getAlleoEwidgetUtils().createEmbedWidgetMessenger(options)`.
+
+### `EmbedWidgetMessenger`
+
+#### Constructor
+
+- `new EmbedWidgetMessenger(options?: EmbedWidgetMessengerOptions)`
+    - Initializes message handling and, by default, calls `startListening()`.
+
+#### Options (`EmbedWidgetMessengerOptions`)
+
+- `targetOrigin?: string` (default: `'*'`) - Passed to `postMessage` for outbound commands.
+- `parentWindow?: Window` (default: `window.parent`) - The window that receives outbound commands.
+- `autoListen?: boolean` (default: `true`) - Auto-register the `message` event listener.
+- `debug?: boolean` (default: `false`) - Enables debug logging via `console.debug`.
+
+#### Properties
+
+- `isListening: boolean` - Whether the instance is currently listening for `message` events.
+
+#### Methods (commands)
+
+- `triggerAction(actionId: string, data?: Record<string, unknown>): void`
+    - Sends a `triggerAction` command. If `actionId` is missing, logs a debug message and skips sending.
+- `addContent(params: AddContentParams): void`
+    - Sends an `addContent` command with the provided content payload.
+- `requestSyncedStatus(): void`
+    - Sends a `requestSyncedStatus` command.
+- `setSyncedStatus(status: Record<string, unknown>): void`
+    - Sends a `setSyncedStatus` command with a `status` object.
+
+#### Methods (events)
+
+- `onSyncedStatusUpdate(handler: (status: Record<string, unknown>) => void): () => void`
+    - Registers a handler for `syncedStatusUpdate` and returns an unsubscribe function.
+- `onIncomingAction(handler: (payload: { actionId: string; data: Record<string, unknown> }) => void): () => void`
+    - Registers a handler for `incomingAction` and returns an unsubscribe function.
+- `onMessage(handler: (event: EmbedWidgetMessageEvent) => void): () => void`
+    - Registers a handler for all widget messages and returns an unsubscribe function.
+
+#### Methods (lifecycle)
+
+- `startListening(): void`
+    - Adds a `message` event listener if running in a browser.
+- `stopListening(): void`
+    - Removes the `message` event listener.
+- `destroy(): void`
+    - Stops listening and clears all registered handlers.
+
+### `AlleoEwidgetUtils`
+
+#### Constructor
+
+- `new AlleoEwidgetUtils(options?: AlleoEwidgetUtilsOptions)`
+    - Creates an instance and calls `initialize()`.
+    - In the browser, a global singleton is stored so multiple bundle loads reuse a single instance.
+
+#### Options (`AlleoEwidgetUtilsOptions`)
+
+- `autoDestroy?: boolean` (default: `true`) - When `true`, attaches a `beforeunload` listener to call `destroy()`.
+- `debug?: boolean` (default: `false`) - Enables debug logging via `console.debug`.
+
+#### Properties
+
+- `isInitialized: boolean` - `true` when initialized and not destroyed.
+
+#### Methods
+
+- `static getInstance(options?: AlleoEwidgetUtilsOptions): AlleoEwidgetUtils`
+    - Returns a singleton instance, creating one if needed.
+- `createEmbedWidgetMessenger(options?: EmbedWidgetMessengerOptions): EmbedWidgetMessenger`
+    - Creates a new `EmbedWidgetMessenger` configured with the provided options.
+- `initialize(): void`
+    - Idempotent; sets initialized state and attaches listeners when `autoDestroy` is enabled.
+- `destroy(): void`
+    - Detaches listeners, clears the global singleton reference, and marks the instance destroyed.
+- `log(message: string, data?: unknown): void`
+    - Debug logger gated by the `debug` option.
+
+### Types
+
+#### `AddContentParams`
+
+Union of the following shapes for `addContent`:
+
+- `AddContentHtmlParams`
+    - `{ type: 'html', html: string }`
+- `AddContentNotepadParams`
+    - `{ type: 'notepad', text?: string | string[], textFormat?: 'text' | 'markdown' | 'html' }`
+- `AddContentStickyNoteParams`
+    - `{ type: 'sticky-note', text?: string, color?: string, outlineColor?: string, shape?: string }`
+- `AddContentImageParams`
+    - `{ type: 'image', url: string }`
+- `AddContentVideoParams`
+    - `{ type: 'video', fileId: string }`
+
+### Notes
+
+- The `targetOrigin` option in `EmbedWidgetMessenger` should generally remain as `'*'` to allow communication with the widget.
+
 ## Samples
 
 Below are the exact sample files from `samples/`, included verbatim as quoted blocks.
@@ -230,201 +400,3 @@ Below are the exact sample files from `samples/`, included verbatim as quoted bl
 >     </body>
 > </html>
 > ```
-
-## API Reference
-
-### Exported helpers
-
-#### `getAlleoEwidgetUtils(options?: AlleoEwidgetUtilsOptions): AlleoEwidgetUtils`
-
-Returns a singleton instance of `AlleoEwidgetUtils`. If a browser global singleton already exists, the existing instance is reused.
-
-#### `getEmbedWidgetMessenger(options?: EmbedWidgetMessengerOptions): EmbedWidgetMessenger`
-
-Convenience helper that returns `getAlleoEwidgetUtils().createEmbedWidgetMessenger(options)`.
-
-### `EmbedWidgetMessenger`
-
-#### Constructor
-
-- `new EmbedWidgetMessenger(options?: EmbedWidgetMessengerOptions)`
-    - Initializes message handling and, by default, calls `startListening()`.
-
-#### Options (`EmbedWidgetMessengerOptions`)
-
-- `targetOrigin?: string` (default: `'*'`) - Passed to `postMessage` for outbound commands.
-- `parentWindow?: Window` (default: `window.parent`) - The window that receives outbound commands.
-- `autoListen?: boolean` (default: `true`) - Auto-register the `message` event listener.
-- `debug?: boolean` (default: `false`) - Enables debug logging via `console.debug`.
-
-#### Properties
-
-- `isListening: boolean` - Whether the instance is currently listening for `message` events.
-
-#### Methods (commands)
-
-- `triggerAction(actionId: string, data?: Record<string, unknown>): void`
-    - Sends a `triggerAction` command. If `actionId` is missing, logs a debug message and skips sending.
-- `addContent(params: AddContentParams): void`
-    - Sends an `addContent` command with the provided content payload.
-- `requestSyncedStatus(): void`
-    - Sends a `requestSyncedStatus` command.
-- `setSyncedStatus(status: Record<string, unknown>): void`
-    - Sends a `setSyncedStatus` command with a `status` object.
-
-#### Methods (events)
-
-- `onSyncedStatusUpdate(handler: (status: Record<string, unknown>) => void): () => void`
-    - Registers a handler for `syncedStatusUpdate` and returns an unsubscribe function.
-- `onIncomingAction(handler: (payload: { actionId: string; data: Record<string, unknown> }) => void): () => void`
-    - Registers a handler for `incomingAction` and returns an unsubscribe function.
-- `onMessage(handler: (event: EmbedWidgetMessageEvent) => void): () => void`
-    - Registers a handler for all widget messages and returns an unsubscribe function.
-
-#### Methods (lifecycle)
-
-- `startListening(): void`
-    - Adds a `message` event listener if running in a browser.
-- `stopListening(): void`
-    - Removes the `message` event listener.
-- `destroy(): void`
-    - Stops listening and clears all registered handlers.
-
-
-
-### `AlleoEwidgetUtils`
-
-#### Constructor
-
-- `new AlleoEwidgetUtils(options?: AlleoEwidgetUtilsOptions)`
-    - Creates an instance and calls `initialize()`.
-    - In the browser, a global singleton is stored so multiple bundle loads reuse a single instance.
-
-#### Options (`AlleoEwidgetUtilsOptions`)
-
-- `autoDestroy?: boolean` (default: `true`) - When `true`, attaches a `beforeunload` listener to call `destroy()`.
-- `debug?: boolean` (default: `false`) - Enables debug logging via `console.debug`.
-
-#### Properties
-
-- `isInitialized: boolean` - `true` when initialized and not destroyed.
-
-#### Methods
-
-- `static getInstance(options?: AlleoEwidgetUtilsOptions): AlleoEwidgetUtils`
-    - Returns a singleton instance, creating one if needed.
-- `createEmbedWidgetMessenger(options?: EmbedWidgetMessengerOptions): EmbedWidgetMessenger`
-    - Creates a new `EmbedWidgetMessenger` configured with the provided options.
-- `initialize(): void`
-    - Idempotent; sets initialized state and attaches listeners when `autoDestroy` is enabled.
-- `destroy(): void`
-    - Detaches listeners, clears the global singleton reference, and marks the instance destroyed.
-- `log(message: string, data?: unknown): void`
-    - Debug logger gated by the `debug` option.
-
-### Types
-
-#### `AddContentParams`
-
-Union of the following shapes for `addContent`:
-
-- `AddContentHtmlParams`
-    - `{ type: 'html', html: string }`
-- `AddContentNotepadParams`
-    - `{ type: 'notepad', text?: string | string[], textFormat?: 'text' | 'markdown' | 'html' }`
-- `AddContentStickyNoteParams`
-    - `{ type: 'sticky-note', text?: string, color?: string, outlineColor?: string, shape?: string }`
-- `AddContentImageParams`
-    - `{ type: 'image', url: string }`
-- `AddContentVideoParams`
-    - `{ type: 'video', fileId: string }`
-
-#### Command envelopes
-
-**Outgoing (iframe -> widget)**
-
-- `EmbedWidgetCommandMap` defines the `command` names and their `params` shapes:
-    - `triggerAction`, `addContent`, `requestSyncedStatus`, `setSyncedStatus`.
-- `EmbedWidgetCommandEnvelope` is the outbound `postMessage` payload shape:
-    - `{ type: 'EmbedWidgetCommand', command, params }`.
-
-**Outgoing examples**
-
-```json
-{
-  "type": "EmbedWidgetCommand",
-  "command": "triggerAction",
-  "params": {
-    "actionId": "demo",
-    "data": { "demo-param": "Hello from iframe" }
-  }
-}
-```
-
-```json
-{
-  "type": "EmbedWidgetCommand",
-  "command": "addContent",
-  "params": {
-    "type": "notepad",
-    "textFormat": "markdown",
-    "text": "# Status\n\nAll systems go."
-  }
-}
-```
-
-```json
-{
-  "type": "EmbedWidgetCommand",
-  "command": "requestSyncedStatus",
-  "params": {}
-}
-```
-
-```json
-{
-  "type": "EmbedWidgetCommand",
-  "command": "setSyncedStatus",
-  "params": {
-    "status": { "color": "#FFAA33" }
-  }
-}
-```
-
-#### Message envelopes
-
-**Incoming (widget -> iframe)**
-
-- `EmbedWidgetMessageMap` defines inbound `command` names and `params` shapes:
-    - `syncedStatusUpdate`, `incomingAction`.
-- `EmbedWidgetMessageEnvelope` is the inbound message shape:
-    - `{ type: 'EmbedWidgetMessage', command, params }`.
-- `EmbedWidgetMessageEvent` is the normalized event passed to `onMessage` handlers:
-    - `{ command, params, raw }`.
-
-**Incoming examples (one per event)**
-
-```json
-{
-  "type": "EmbedWidgetMessage",
-  "command": "syncedStatusUpdate",
-  "params": {
-    "syncedStatus": { "color": "#FFAA33" }
-  }
-}
-```
-
-```json
-{
-  "type": "EmbedWidgetMessage",
-  "command": "incomingAction",
-  "params": {
-    "actionId": "demo",
-    "data": { "demo-param": "Hello from widget" }
-  }
-}
-```
-
-### Notes
-
-- The `targetOrigin` option in `EmbedWidgetMessenger` should generally remain as `'*'` to allow communication with the widget.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@withalleo/ewidget-utils",
-	"version": "1.0.9",
+	"version": "1.0.12",
 	"description": "Alleo e-widget utility library.",
 	"repository": {
 		"type": "git",
@@ -41,7 +41,7 @@
 	"scripts": {
 		"clean": "rimraf dist",
 		"build": "vite build && tsc -p tsconfig.build.json",
-		"publish": "npm run clean && npm run build && npm version patch && npm publish"
+		"full-publish": "npm run clean && npm run build && npm version patch && npm publish"
 	},
 	"devDependencies": {
 		"@eslint/js": "^9.22.0",