@withalleo/ewidget-utils 1.0.11 → 1.0.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +184 -232
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,17 +1,7 @@
|
|
|
1
1
|
# @withalleo/ewidget-utils
|
|
2
2
|
|
|
3
|
-
## Install
|
|
4
|
-
|
|
5
|
-
```bash
|
|
6
|
-
npm i @withalleo/ewidget-utils
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
## Demo (plain HTML)
|
|
10
|
-
|
|
11
3
|
This package ships a browser bundle at `@withalleo/ewidget-utils/browser` (UMD). You can drop it into a plain HTML page and call `demo()`.
|
|
12
4
|
|
|
13
|
-
> Note: The CDN URL below is an example. Prefer pinning an exact version.
|
|
14
|
-
|
|
15
5
|
```html
|
|
16
6
|
<!doctype html>
|
|
17
7
|
<html lang="en">
|
|
@@ -26,7 +16,7 @@ This package ships a browser bundle at `@withalleo/ewidget-utils/browser` (UMD).
|
|
|
26
16
|
<script src="https://unpkg.com/@withalleo/ewidget-utils/dist/ewidget-utils.umd.cjs"></script>
|
|
27
17
|
<script>
|
|
28
18
|
const alleo = AlleoEWidget.getEmbedWidgetMessenger({ debug: true })
|
|
29
|
-
|
|
19
|
+
|
|
30
20
|
document.getElementById('button').onclick = () =>
|
|
31
21
|
alleo.addContent({ type: 'notepad', textFormat: 'markdown', text: '# Status\n\nAll systems go.' })
|
|
32
22
|
</script>
|
|
@@ -34,6 +24,176 @@ This package ships a browser bundle at `@withalleo/ewidget-utils/browser` (UMD).
|
|
|
34
24
|
</html>
|
|
35
25
|
```
|
|
36
26
|
|
|
27
|
+
#### Commands
|
|
28
|
+
|
|
29
|
+
**Outgoing (iframe -> widget)**
|
|
30
|
+
|
|
31
|
+
- `EmbedWidgetCommandMap` defines the `command` names and their `params` shapes:
|
|
32
|
+
- `triggerAction`, `addContent`, `requestSyncedStatus`, `setSyncedStatus`.
|
|
33
|
+
- `EmbedWidgetCommandEnvelope` is the outbound `postMessage` payload shape:
|
|
34
|
+
- `{ type: 'EmbedWidgetCommand', command, params }`.
|
|
35
|
+
|
|
36
|
+
**Outgoing examples**
|
|
37
|
+
|
|
38
|
+
```js
|
|
39
|
+
alleo.triggerAction('demo', {
|
|
40
|
+
'demo-param': 'Hello from iframe',
|
|
41
|
+
})
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
```js
|
|
45
|
+
alleo.addContent({
|
|
46
|
+
type: 'notepad',
|
|
47
|
+
textFormat: 'markdown',
|
|
48
|
+
text: '# Status\n\nAll systems go.',
|
|
49
|
+
})
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
```js
|
|
53
|
+
alleo.requestSyncedStatus()
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
```js
|
|
57
|
+
alleo.setSyncedStatus({
|
|
58
|
+
color: '#FFAA33',
|
|
59
|
+
})
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
#### Message envelopes
|
|
63
|
+
|
|
64
|
+
**Incoming (widget -> iframe)**
|
|
65
|
+
|
|
66
|
+
- `EmbedWidgetMessageMap` defines inbound `command` names and `params` shapes:
|
|
67
|
+
- `syncedStatusUpdate`, `incomingAction`.
|
|
68
|
+
- `EmbedWidgetMessageEnvelope` is the inbound message shape:
|
|
69
|
+
- `{ type: 'EmbedWidgetMessage', command, params }`.
|
|
70
|
+
- `EmbedWidgetMessageEvent` is the normalized event passed to `onMessage` handlers:
|
|
71
|
+
- `{ command, params, raw }`.
|
|
72
|
+
|
|
73
|
+
**Incoming examples (one per event)**
|
|
74
|
+
|
|
75
|
+
```js
|
|
76
|
+
alleo.onSyncedStatusUpdate((status) => {
|
|
77
|
+
console.log('synced status', status)
|
|
78
|
+
})
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
```js
|
|
82
|
+
alleo.onIncomingAction(({ actionId, data }) => {
|
|
83
|
+
console.log('incoming action', actionId, data)
|
|
84
|
+
})
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## API Reference
|
|
88
|
+
|
|
89
|
+
### Exported helpers
|
|
90
|
+
|
|
91
|
+
#### `getAlleoEwidgetUtils(options?: AlleoEwidgetUtilsOptions): AlleoEwidgetUtils`
|
|
92
|
+
|
|
93
|
+
Returns a singleton instance of `AlleoEwidgetUtils`. If a browser global singleton already exists, the existing instance is reused.
|
|
94
|
+
|
|
95
|
+
#### `getEmbedWidgetMessenger(options?: EmbedWidgetMessengerOptions): EmbedWidgetMessenger`
|
|
96
|
+
|
|
97
|
+
Convenience helper that returns `getAlleoEwidgetUtils().createEmbedWidgetMessenger(options)`.
|
|
98
|
+
|
|
99
|
+
### `EmbedWidgetMessenger`
|
|
100
|
+
|
|
101
|
+
#### Constructor
|
|
102
|
+
|
|
103
|
+
- `new EmbedWidgetMessenger(options?: EmbedWidgetMessengerOptions)`
|
|
104
|
+
- Initializes message handling and, by default, calls `startListening()`.
|
|
105
|
+
|
|
106
|
+
#### Options (`EmbedWidgetMessengerOptions`)
|
|
107
|
+
|
|
108
|
+
- `targetOrigin?: string` (default: `'*'`) - Passed to `postMessage` for outbound commands.
|
|
109
|
+
- `parentWindow?: Window` (default: `window.parent`) - The window that receives outbound commands.
|
|
110
|
+
- `autoListen?: boolean` (default: `true`) - Auto-register the `message` event listener.
|
|
111
|
+
- `debug?: boolean` (default: `false`) - Enables debug logging via `console.debug`.
|
|
112
|
+
|
|
113
|
+
#### Properties
|
|
114
|
+
|
|
115
|
+
- `isListening: boolean` - Whether the instance is currently listening for `message` events.
|
|
116
|
+
|
|
117
|
+
#### Methods (commands)
|
|
118
|
+
|
|
119
|
+
- `triggerAction(actionId: string, data?: Record<string, unknown>): void`
|
|
120
|
+
- Sends a `triggerAction` command. If `actionId` is missing, logs a debug message and skips sending.
|
|
121
|
+
- `addContent(params: AddContentParams): void`
|
|
122
|
+
- Sends an `addContent` command with the provided content payload.
|
|
123
|
+
- `requestSyncedStatus(): void`
|
|
124
|
+
- Sends a `requestSyncedStatus` command.
|
|
125
|
+
- `setSyncedStatus(status: Record<string, unknown>): void`
|
|
126
|
+
- Sends a `setSyncedStatus` command with a `status` object.
|
|
127
|
+
|
|
128
|
+
#### Methods (events)
|
|
129
|
+
|
|
130
|
+
- `onSyncedStatusUpdate(handler: (status: Record<string, unknown>) => void): () => void`
|
|
131
|
+
- Registers a handler for `syncedStatusUpdate` and returns an unsubscribe function.
|
|
132
|
+
- `onIncomingAction(handler: (payload: { actionId: string; data: Record<string, unknown> }) => void): () => void`
|
|
133
|
+
- Registers a handler for `incomingAction` and returns an unsubscribe function.
|
|
134
|
+
- `onMessage(handler: (event: EmbedWidgetMessageEvent) => void): () => void`
|
|
135
|
+
- Registers a handler for all widget messages and returns an unsubscribe function.
|
|
136
|
+
|
|
137
|
+
#### Methods (lifecycle)
|
|
138
|
+
|
|
139
|
+
- `startListening(): void`
|
|
140
|
+
- Adds a `message` event listener if running in a browser.
|
|
141
|
+
- `stopListening(): void`
|
|
142
|
+
- Removes the `message` event listener.
|
|
143
|
+
- `destroy(): void`
|
|
144
|
+
- Stops listening and clears all registered handlers.
|
|
145
|
+
|
|
146
|
+
### `AlleoEwidgetUtils`
|
|
147
|
+
|
|
148
|
+
#### Constructor
|
|
149
|
+
|
|
150
|
+
- `new AlleoEwidgetUtils(options?: AlleoEwidgetUtilsOptions)`
|
|
151
|
+
- Creates an instance and calls `initialize()`.
|
|
152
|
+
- In the browser, a global singleton is stored so multiple bundle loads reuse a single instance.
|
|
153
|
+
|
|
154
|
+
#### Options (`AlleoEwidgetUtilsOptions`)
|
|
155
|
+
|
|
156
|
+
- `autoDestroy?: boolean` (default: `true`) - When `true`, attaches a `beforeunload` listener to call `destroy()`.
|
|
157
|
+
- `debug?: boolean` (default: `false`) - Enables debug logging via `console.debug`.
|
|
158
|
+
|
|
159
|
+
#### Properties
|
|
160
|
+
|
|
161
|
+
- `isInitialized: boolean` - `true` when initialized and not destroyed.
|
|
162
|
+
|
|
163
|
+
#### Methods
|
|
164
|
+
|
|
165
|
+
- `static getInstance(options?: AlleoEwidgetUtilsOptions): AlleoEwidgetUtils`
|
|
166
|
+
- Returns a singleton instance, creating one if needed.
|
|
167
|
+
- `createEmbedWidgetMessenger(options?: EmbedWidgetMessengerOptions): EmbedWidgetMessenger`
|
|
168
|
+
- Creates a new `EmbedWidgetMessenger` configured with the provided options.
|
|
169
|
+
- `initialize(): void`
|
|
170
|
+
- Idempotent; sets initialized state and attaches listeners when `autoDestroy` is enabled.
|
|
171
|
+
- `destroy(): void`
|
|
172
|
+
- Detaches listeners, clears the global singleton reference, and marks the instance destroyed.
|
|
173
|
+
- `log(message: string, data?: unknown): void`
|
|
174
|
+
- Debug logger gated by the `debug` option.
|
|
175
|
+
|
|
176
|
+
### Types
|
|
177
|
+
|
|
178
|
+
#### `AddContentParams`
|
|
179
|
+
|
|
180
|
+
Union of the following shapes for `addContent`:
|
|
181
|
+
|
|
182
|
+
- `AddContentHtmlParams`
|
|
183
|
+
- `{ type: 'html', html: string }`
|
|
184
|
+
- `AddContentNotepadParams`
|
|
185
|
+
- `{ type: 'notepad', text?: string | string[], textFormat?: 'text' | 'markdown' | 'html' }`
|
|
186
|
+
- `AddContentStickyNoteParams`
|
|
187
|
+
- `{ type: 'sticky-note', text?: string, color?: string, outlineColor?: string, shape?: string }`
|
|
188
|
+
- `AddContentImageParams`
|
|
189
|
+
- `{ type: 'image', url: string }`
|
|
190
|
+
- `AddContentVideoParams`
|
|
191
|
+
- `{ type: 'video', fileId: string }`
|
|
192
|
+
|
|
193
|
+
### Notes
|
|
194
|
+
|
|
195
|
+
- The `targetOrigin` option in `EmbedWidgetMessenger` should generally remain as `'*'` to allow communication with the widget.
|
|
196
|
+
|
|
37
197
|
## Samples
|
|
38
198
|
|
|
39
199
|
Below are the exact sample files from `samples/`, included verbatim as quoted blocks.
|
|
@@ -79,20 +239,17 @@ Below are the exact sample files from `samples/`, included verbatim as quoted bl
|
|
|
79
239
|
> logEl.textContent = `${line}\n${logEl.textContent}`
|
|
80
240
|
> }
|
|
81
241
|
>
|
|
82
|
-
> const
|
|
83
|
-
> targetOrigin: '*',
|
|
84
|
-
> debug: true,
|
|
85
|
-
> })
|
|
242
|
+
> const alleo = new AlleoEWidget.getEmbedWidgetMessenger()
|
|
86
243
|
>
|
|
87
|
-
>
|
|
244
|
+
> alleo.onSyncedStatusUpdate((status) => {
|
|
88
245
|
> log('syncedStatusUpdate:', status)
|
|
89
246
|
> })
|
|
90
247
|
>
|
|
91
|
-
>
|
|
248
|
+
> alleo.onIncomingAction(({ actionId, data }) => {
|
|
92
249
|
> log(`incomingAction: ${actionId}`, data)
|
|
93
250
|
> })
|
|
94
251
|
>
|
|
95
|
-
>
|
|
252
|
+
> alleo.getElementById('trigger').addEventListener('click', () => {
|
|
96
253
|
> messenger.triggerAction('demo', {
|
|
97
254
|
> 'demo-param': 'Hello from iframe',
|
|
98
255
|
> })
|
|
@@ -100,7 +257,7 @@ Below are the exact sample files from `samples/`, included verbatim as quoted bl
|
|
|
100
257
|
> })
|
|
101
258
|
>
|
|
102
259
|
> document.getElementById('request').addEventListener('click', () => {
|
|
103
|
-
>
|
|
260
|
+
> alleo.requestSyncedStatus()
|
|
104
261
|
> log('requestSyncedStatus sent')
|
|
105
262
|
> })
|
|
106
263
|
> </script>
|
|
@@ -139,13 +296,9 @@ Below are the exact sample files from `samples/`, included verbatim as quoted bl
|
|
|
139
296
|
>
|
|
140
297
|
> <script src="https://unpkg.com/@withalleo/ewidget-utils/dist/ewidget-utils.umd.cjs"></script>
|
|
141
298
|
> <script>
|
|
142
|
-
> const
|
|
143
|
-
> targetOrigin: '*',
|
|
144
|
-
> debug: true,
|
|
145
|
-
> })
|
|
146
|
-
>
|
|
299
|
+
> const alleo = new AlleoEWidget.getEmbedWidgetMessenger()
|
|
147
300
|
> document.getElementById('add-notepad').addEventListener('click', () => {
|
|
148
|
-
>
|
|
301
|
+
> alleo.addContent({
|
|
149
302
|
> type: 'notepad',
|
|
150
303
|
> textFormat: 'markdown',
|
|
151
304
|
> text: '# New note\n\nAdded from iframe.',
|
|
@@ -153,7 +306,7 @@ Below are the exact sample files from `samples/`, included verbatim as quoted bl
|
|
|
153
306
|
> })
|
|
154
307
|
>
|
|
155
308
|
> document.getElementById('add-sticky').addEventListener('click', () => {
|
|
156
|
-
>
|
|
309
|
+
> alleo.addContent({
|
|
157
310
|
> type: 'sticky-note',
|
|
158
311
|
> text: 'Remember to review the draft',
|
|
159
312
|
> color: '#FFE680',
|
|
@@ -163,7 +316,7 @@ Below are the exact sample files from `samples/`, included verbatim as quoted bl
|
|
|
163
316
|
> })
|
|
164
317
|
>
|
|
165
318
|
> document.getElementById('add-html').addEventListener('click', () => {
|
|
166
|
-
>
|
|
319
|
+
> alleo.addContent({
|
|
167
320
|
> type: 'html',
|
|
168
321
|
> html: '<!doctype html><html><body><h2>Hello from iframe</h2></body></html>',
|
|
169
322
|
> })
|
|
@@ -204,17 +357,14 @@ Below are the exact sample files from `samples/`, included verbatim as quoted bl
|
|
|
204
357
|
> <script>
|
|
205
358
|
> const button = document.getElementById('color')
|
|
206
359
|
>
|
|
207
|
-
> const
|
|
208
|
-
> targetOrigin: '*',
|
|
209
|
-
> debug: true,
|
|
210
|
-
> })
|
|
360
|
+
> const alleo = new AlleoEWidget.getEmbedWidgetMessenger()
|
|
211
361
|
>
|
|
212
362
|
> const applyColor = (status) => {
|
|
213
363
|
> if (!status || !status.color) return
|
|
214
364
|
> button.style.backgroundColor = status.color
|
|
215
365
|
> }
|
|
216
366
|
>
|
|
217
|
-
>
|
|
367
|
+
> alleo.onSyncedStatusUpdate((status) => {
|
|
218
368
|
> applyColor(status)
|
|
219
369
|
> })
|
|
220
370
|
>
|
|
@@ -222,209 +372,11 @@ Below are the exact sample files from `samples/`, included verbatim as quoted bl
|
|
|
222
372
|
> const color = `#${Math.floor(Math.random() * 0xffffff)
|
|
223
373
|
> .toString(16)
|
|
224
374
|
> .padStart(6, '0')}`
|
|
225
|
-
>
|
|
375
|
+
> alleo.setSyncedStatus({ color })
|
|
226
376
|
> })
|
|
227
377
|
>
|
|
228
|
-
>
|
|
378
|
+
> alleo.requestSyncedStatus()
|
|
229
379
|
> </script>
|
|
230
380
|
> </body>
|
|
231
381
|
> </html>
|
|
232
382
|
> ```
|
|
233
|
-
|
|
234
|
-
## API Reference
|
|
235
|
-
|
|
236
|
-
### Exported helpers
|
|
237
|
-
|
|
238
|
-
#### `getAlleoEwidgetUtils(options?: AlleoEwidgetUtilsOptions): AlleoEwidgetUtils`
|
|
239
|
-
|
|
240
|
-
Returns a singleton instance of `AlleoEwidgetUtils`. If a browser global singleton already exists, the existing instance is reused.
|
|
241
|
-
|
|
242
|
-
#### `getEmbedWidgetMessenger(options?: EmbedWidgetMessengerOptions): EmbedWidgetMessenger`
|
|
243
|
-
|
|
244
|
-
Convenience helper that returns `getAlleoEwidgetUtils().createEmbedWidgetMessenger(options)`.
|
|
245
|
-
|
|
246
|
-
### `EmbedWidgetMessenger`
|
|
247
|
-
|
|
248
|
-
#### Constructor
|
|
249
|
-
|
|
250
|
-
- `new EmbedWidgetMessenger(options?: EmbedWidgetMessengerOptions)`
|
|
251
|
-
- Initializes message handling and, by default, calls `startListening()`.
|
|
252
|
-
|
|
253
|
-
#### Options (`EmbedWidgetMessengerOptions`)
|
|
254
|
-
|
|
255
|
-
- `targetOrigin?: string` (default: `'*'`) - Passed to `postMessage` for outbound commands.
|
|
256
|
-
- `parentWindow?: Window` (default: `window.parent`) - The window that receives outbound commands.
|
|
257
|
-
- `autoListen?: boolean` (default: `true`) - Auto-register the `message` event listener.
|
|
258
|
-
- `debug?: boolean` (default: `false`) - Enables debug logging via `console.debug`.
|
|
259
|
-
|
|
260
|
-
#### Properties
|
|
261
|
-
|
|
262
|
-
- `isListening: boolean` - Whether the instance is currently listening for `message` events.
|
|
263
|
-
|
|
264
|
-
#### Methods (commands)
|
|
265
|
-
|
|
266
|
-
- `triggerAction(actionId: string, data?: Record<string, unknown>): void`
|
|
267
|
-
- Sends a `triggerAction` command. If `actionId` is missing, logs a debug message and skips sending.
|
|
268
|
-
- `addContent(params: AddContentParams): void`
|
|
269
|
-
- Sends an `addContent` command with the provided content payload.
|
|
270
|
-
- `requestSyncedStatus(): void`
|
|
271
|
-
- Sends a `requestSyncedStatus` command.
|
|
272
|
-
- `setSyncedStatus(status: Record<string, unknown>): void`
|
|
273
|
-
- Sends a `setSyncedStatus` command with a `status` object.
|
|
274
|
-
|
|
275
|
-
#### Methods (events)
|
|
276
|
-
|
|
277
|
-
- `onSyncedStatusUpdate(handler: (status: Record<string, unknown>) => void): () => void`
|
|
278
|
-
- Registers a handler for `syncedStatusUpdate` and returns an unsubscribe function.
|
|
279
|
-
- `onIncomingAction(handler: (payload: { actionId: string; data: Record<string, unknown> }) => void): () => void`
|
|
280
|
-
- Registers a handler for `incomingAction` and returns an unsubscribe function.
|
|
281
|
-
- `onMessage(handler: (event: EmbedWidgetMessageEvent) => void): () => void`
|
|
282
|
-
- Registers a handler for all widget messages and returns an unsubscribe function.
|
|
283
|
-
|
|
284
|
-
#### Methods (lifecycle)
|
|
285
|
-
|
|
286
|
-
- `startListening(): void`
|
|
287
|
-
- Adds a `message` event listener if running in a browser.
|
|
288
|
-
- `stopListening(): void`
|
|
289
|
-
- Removes the `message` event listener.
|
|
290
|
-
- `destroy(): void`
|
|
291
|
-
- Stops listening and clears all registered handlers.
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
### `AlleoEwidgetUtils`
|
|
296
|
-
|
|
297
|
-
#### Constructor
|
|
298
|
-
|
|
299
|
-
- `new AlleoEwidgetUtils(options?: AlleoEwidgetUtilsOptions)`
|
|
300
|
-
- Creates an instance and calls `initialize()`.
|
|
301
|
-
- In the browser, a global singleton is stored so multiple bundle loads reuse a single instance.
|
|
302
|
-
|
|
303
|
-
#### Options (`AlleoEwidgetUtilsOptions`)
|
|
304
|
-
|
|
305
|
-
- `autoDestroy?: boolean` (default: `true`) - When `true`, attaches a `beforeunload` listener to call `destroy()`.
|
|
306
|
-
- `debug?: boolean` (default: `false`) - Enables debug logging via `console.debug`.
|
|
307
|
-
|
|
308
|
-
#### Properties
|
|
309
|
-
|
|
310
|
-
- `isInitialized: boolean` - `true` when initialized and not destroyed.
|
|
311
|
-
|
|
312
|
-
#### Methods
|
|
313
|
-
|
|
314
|
-
- `static getInstance(options?: AlleoEwidgetUtilsOptions): AlleoEwidgetUtils`
|
|
315
|
-
- Returns a singleton instance, creating one if needed.
|
|
316
|
-
- `createEmbedWidgetMessenger(options?: EmbedWidgetMessengerOptions): EmbedWidgetMessenger`
|
|
317
|
-
- Creates a new `EmbedWidgetMessenger` configured with the provided options.
|
|
318
|
-
- `initialize(): void`
|
|
319
|
-
- Idempotent; sets initialized state and attaches listeners when `autoDestroy` is enabled.
|
|
320
|
-
- `destroy(): void`
|
|
321
|
-
- Detaches listeners, clears the global singleton reference, and marks the instance destroyed.
|
|
322
|
-
- `log(message: string, data?: unknown): void`
|
|
323
|
-
- Debug logger gated by the `debug` option.
|
|
324
|
-
|
|
325
|
-
### Types
|
|
326
|
-
|
|
327
|
-
#### `AddContentParams`
|
|
328
|
-
|
|
329
|
-
Union of the following shapes for `addContent`:
|
|
330
|
-
|
|
331
|
-
- `AddContentHtmlParams`
|
|
332
|
-
- `{ type: 'html', html: string }`
|
|
333
|
-
- `AddContentNotepadParams`
|
|
334
|
-
- `{ type: 'notepad', text?: string | string[], textFormat?: 'text' | 'markdown' | 'html' }`
|
|
335
|
-
- `AddContentStickyNoteParams`
|
|
336
|
-
- `{ type: 'sticky-note', text?: string, color?: string, outlineColor?: string, shape?: string }`
|
|
337
|
-
- `AddContentImageParams`
|
|
338
|
-
- `{ type: 'image', url: string }`
|
|
339
|
-
- `AddContentVideoParams`
|
|
340
|
-
- `{ type: 'video', fileId: string }`
|
|
341
|
-
|
|
342
|
-
#### Command envelopes
|
|
343
|
-
|
|
344
|
-
**Outgoing (iframe -> widget)**
|
|
345
|
-
|
|
346
|
-
- `EmbedWidgetCommandMap` defines the `command` names and their `params` shapes:
|
|
347
|
-
- `triggerAction`, `addContent`, `requestSyncedStatus`, `setSyncedStatus`.
|
|
348
|
-
- `EmbedWidgetCommandEnvelope` is the outbound `postMessage` payload shape:
|
|
349
|
-
- `{ type: 'EmbedWidgetCommand', command, params }`.
|
|
350
|
-
|
|
351
|
-
**Outgoing examples**
|
|
352
|
-
|
|
353
|
-
```json
|
|
354
|
-
{
|
|
355
|
-
"type": "EmbedWidgetCommand",
|
|
356
|
-
"command": "triggerAction",
|
|
357
|
-
"params": {
|
|
358
|
-
"actionId": "demo",
|
|
359
|
-
"data": { "demo-param": "Hello from iframe" }
|
|
360
|
-
}
|
|
361
|
-
}
|
|
362
|
-
```
|
|
363
|
-
|
|
364
|
-
```json
|
|
365
|
-
{
|
|
366
|
-
"type": "EmbedWidgetCommand",
|
|
367
|
-
"command": "addContent",
|
|
368
|
-
"params": {
|
|
369
|
-
"type": "notepad",
|
|
370
|
-
"textFormat": "markdown",
|
|
371
|
-
"text": "# Status\n\nAll systems go."
|
|
372
|
-
}
|
|
373
|
-
}
|
|
374
|
-
```
|
|
375
|
-
|
|
376
|
-
```json
|
|
377
|
-
{
|
|
378
|
-
"type": "EmbedWidgetCommand",
|
|
379
|
-
"command": "requestSyncedStatus",
|
|
380
|
-
"params": {}
|
|
381
|
-
}
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
```json
|
|
385
|
-
{
|
|
386
|
-
"type": "EmbedWidgetCommand",
|
|
387
|
-
"command": "setSyncedStatus",
|
|
388
|
-
"params": {
|
|
389
|
-
"status": { "color": "#FFAA33" }
|
|
390
|
-
}
|
|
391
|
-
}
|
|
392
|
-
```
|
|
393
|
-
|
|
394
|
-
#### Message envelopes
|
|
395
|
-
|
|
396
|
-
**Incoming (widget -> iframe)**
|
|
397
|
-
|
|
398
|
-
- `EmbedWidgetMessageMap` defines inbound `command` names and `params` shapes:
|
|
399
|
-
- `syncedStatusUpdate`, `incomingAction`.
|
|
400
|
-
- `EmbedWidgetMessageEnvelope` is the inbound message shape:
|
|
401
|
-
- `{ type: 'EmbedWidgetMessage', command, params }`.
|
|
402
|
-
- `EmbedWidgetMessageEvent` is the normalized event passed to `onMessage` handlers:
|
|
403
|
-
- `{ command, params, raw }`.
|
|
404
|
-
|
|
405
|
-
**Incoming examples (one per event)**
|
|
406
|
-
|
|
407
|
-
```json
|
|
408
|
-
{
|
|
409
|
-
"type": "EmbedWidgetMessage",
|
|
410
|
-
"command": "syncedStatusUpdate",
|
|
411
|
-
"params": {
|
|
412
|
-
"syncedStatus": { "color": "#FFAA33" }
|
|
413
|
-
}
|
|
414
|
-
}
|
|
415
|
-
```
|
|
416
|
-
|
|
417
|
-
```json
|
|
418
|
-
{
|
|
419
|
-
"type": "EmbedWidgetMessage",
|
|
420
|
-
"command": "incomingAction",
|
|
421
|
-
"params": {
|
|
422
|
-
"actionId": "demo",
|
|
423
|
-
"data": { "demo-param": "Hello from widget" }
|
|
424
|
-
}
|
|
425
|
-
}
|
|
426
|
-
```
|
|
427
|
-
|
|
428
|
-
### Notes
|
|
429
|
-
|
|
430
|
-
- The `targetOrigin` option in `EmbedWidgetMessenger` should generally remain as `'*'` to allow communication with the widget.
|