@widgetic/embed-sdk 2.0.11 → 2.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/LICENSE +122 -0
- package/README.md +3 -1
- package/dist/browser/chunks/ABTestManager.js +1 -1
- package/dist/browser/chunks/advanced.js +1 -1
- package/dist/browser/chunks/api.js +1 -1
- package/dist/browser/chunks/display.js +1 -1
- package/dist/browser/chunks/media.js +1 -1
- package/dist/browser/chunks/messaging.js +1 -1
- package/dist/browser/chunks/renderers.js +1 -1
- package/dist/browser/chunks/scanner.js +1 -1
- package/dist/browser/chunks/security.js +1 -1
- package/dist/browser/embed-bootstrap.js +1 -1
- package/dist/browser/embed-sdk.js +1 -1
- package/dist/esm/chunks/ABTestManager.js +1 -1
- package/dist/esm/chunks/advanced.js +1 -1
- package/dist/esm/chunks/api.js +1 -1
- package/dist/esm/chunks/display.js +1 -1
- package/dist/esm/chunks/media.js +1 -1
- package/dist/esm/chunks/messaging.js +1 -1
- package/dist/esm/chunks/renderers.js +1 -1
- package/dist/esm/chunks/scanner.js +1 -1
- package/dist/esm/chunks/security.js +1 -1
- package/dist/esm/embed-bootstrap.js +1 -1
- package/dist/esm/embed-sdk.js +1 -1
- package/dist/esm/types/core/content-position-manager.d.ts +4 -0
- package/dist/esm/types/core/media-manager.d.ts +18 -1
- package/dist/esm/types/core/realtime-manager.d.ts +9 -2
- package/dist/esm/types/utils/chrome-labels.d.ts +26 -0
- package/dist/esm/types/utils/declarative-embed-parser.d.ts +84 -0
- package/dist/esm/types/utils/hydrate-published-host.d.ts +17 -2
- package/dist/esm/types/utils/mount-direct-widget.d.ts +34 -0
- package/dist/esm/types/utils/public-embed-lookup.d.ts +17 -0
- package/dist/esm/types/utils/published-host-bridge.d.ts +24 -0
- package/dist/umd/embed-bootstrap.js +1 -1
- package/dist/umd/embed-sdk.js +1 -1
- package/package.json +2 -2
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Declarative Dynamic Content & Design Parser for `<widgetic>` and `<widgetic-embed>` elements.
|
|
3
|
+
*
|
|
4
|
+
* Supports:
|
|
5
|
+
* 1. Child HTML elements (`<img src="..." image-description="..." />`, `<item title="..." />`, `<audio>`, etc.)
|
|
6
|
+
* converted into repeatable `contentItems`.
|
|
7
|
+
* 2. Declarative attributes on the host element (`design-*`, `content-*`, `design`, `content`, `content-items`,
|
|
8
|
+
* or custom kebab-case / lowercase attributes like `distance-between-images="10"`, `backgroundcolor="#ffffff"`)
|
|
9
|
+
* mapped into `design` and `content` overrides.
|
|
10
|
+
* 3. Direct widget embedding (`widget="<widget_id>"` or `widget-id="<widget_id>"`) in addition to
|
|
11
|
+
* composition embedding (`composition-id="<composition_id>"`).
|
|
12
|
+
* 4. Live DOM `MutationObserver` tracking so mutating child elements or attributes in the host DOM
|
|
13
|
+
* updates the running widget's content and design in place without reloading.
|
|
14
|
+
*/
|
|
15
|
+
import type { PublicEmbedOverlay } from "./public-embed-lookup.js";
|
|
16
|
+
export type EmbedHostTarget = {
|
|
17
|
+
kind: "composition";
|
|
18
|
+
id: string;
|
|
19
|
+
} | {
|
|
20
|
+
kind: "widget";
|
|
21
|
+
id: string;
|
|
22
|
+
};
|
|
23
|
+
export interface DeclarativeContentItem {
|
|
24
|
+
id: string;
|
|
25
|
+
order: number;
|
|
26
|
+
metadata: Record<string, unknown>;
|
|
27
|
+
[key: string]: unknown;
|
|
28
|
+
}
|
|
29
|
+
export interface DeclarativeEmbedOverrides {
|
|
30
|
+
design: Record<string, string>;
|
|
31
|
+
content: Record<string, unknown>;
|
|
32
|
+
contentItems: DeclarativeContentItem[];
|
|
33
|
+
hasOverrides: boolean;
|
|
34
|
+
}
|
|
35
|
+
export type DeclarativeHostOverrides = DeclarativeEmbedOverrides;
|
|
36
|
+
/**
|
|
37
|
+
* Converts a kebab-case (or `data-*` prefixed) attribute name to camelCase.
|
|
38
|
+
*/
|
|
39
|
+
export declare function kebabToCamel(name: string): string;
|
|
40
|
+
/**
|
|
41
|
+
* Converts a camelCase property name to kebab-case for HTML attributes.
|
|
42
|
+
*/
|
|
43
|
+
export declare function camelToKebab(name: string): string;
|
|
44
|
+
/**
|
|
45
|
+
* Determines whether a host element targets a composition (`composition-id`) or a widget (`widget` / `widget-id`).
|
|
46
|
+
*/
|
|
47
|
+
export declare function getEmbedHostTarget(host: HTMLElement): EmbedHostTarget | null;
|
|
48
|
+
/**
|
|
49
|
+
* Installs JS property getters/setters (`values`, `context`, `mediaResolver`, `design`, `content`,
|
|
50
|
+
* `contentItems`, `compositionId`, `widgetId`) on a `<widgetic>` element so frameworks like React 19
|
|
51
|
+
* (which assign object props and camelCase props as DOM properties when `prop in element`) and
|
|
52
|
+
* imperative `ref.current.values = { ... }` updates automatically reflect to HTML attributes and
|
|
53
|
+
* trigger the existing `MutationObserver` pipeline.
|
|
54
|
+
*/
|
|
55
|
+
export declare function installHostPropertyBridge(host: HTMLElement): void;
|
|
56
|
+
/**
|
|
57
|
+
* Returns the identifier used for state tracking (`composition-id` or `widget` / `widget-id`).
|
|
58
|
+
*/
|
|
59
|
+
export declare function getHostInstanceId(host: HTMLElement): string | null;
|
|
60
|
+
export declare function isReservedHostAttribute(attrName: string): boolean;
|
|
61
|
+
/**
|
|
62
|
+
* Parses declarative child elements (`<img>`, `<item>`, `<audio>`, `<div>`, etc.) inside `<widgetic>`
|
|
63
|
+
* into `contentItems`, hiding the raw declarative DOM nodes so they don't render visually alongside
|
|
64
|
+
* the mounted widget while keeping them in the DOM for live `MutationObserver` updates.
|
|
65
|
+
*/
|
|
66
|
+
export declare function parseDeclarativeChildren(host: HTMLElement): DeclarativeContentItem[];
|
|
67
|
+
/**
|
|
68
|
+
* Parses declarative attributes and child elements on a `<widgetic>` host.
|
|
69
|
+
*/
|
|
70
|
+
export declare function parseDeclarativeHostOverrides(host: HTMLElement, baseOverlay?: PublicEmbedOverlay | null): DeclarativeEmbedOverrides;
|
|
71
|
+
/**
|
|
72
|
+
* Merges a gateway `PublicEmbedPayload` with any declarative attributes and child elements on the host.
|
|
73
|
+
*/
|
|
74
|
+
export declare function mergeDeclarativeEmbedPayload<T extends PublicEmbedOverlay>(host: HTMLElement, payload?: T | null): T;
|
|
75
|
+
/**
|
|
76
|
+
* Checks whether a set of `MutationRecord`s includes a declarative content, design, or child-item change.
|
|
77
|
+
*/
|
|
78
|
+
export declare function hasDeclarativeMutation(records: MutationRecord[]): boolean;
|
|
79
|
+
/**
|
|
80
|
+
* Observes a `<widgetic>` host for live DOM changes to declarative attributes or child elements,
|
|
81
|
+
* invoking `onUpdate` without reloading the widget.
|
|
82
|
+
*/
|
|
83
|
+
export declare function observeDeclarativeHostChanges(host: HTMLElement, baseOverlay: PublicEmbedOverlay | null | undefined, onUpdate: (overrides: DeclarativeEmbedOverrides) => void): () => void;
|
|
84
|
+
export declare function stopDeclarativeHostObserver(host: HTMLElement): void;
|
|
@@ -3,12 +3,27 @@
|
|
|
3
3
|
* Customer tag is one word: `<widgetic>`. No `<widgetic-widget>`, no render-mode.
|
|
4
4
|
*
|
|
5
5
|
* Copy iframe = raw `<iframe src>` without SDK.
|
|
6
|
-
* Copy web component = SDK + `<widgetic composition-id
|
|
7
|
-
*
|
|
6
|
+
* Copy web component = SDK + `<widgetic composition-id>`. When the published
|
|
7
|
+
* version has a direct module, the SDK mounts it in a shadow root. A version
|
|
8
|
+
* with only widget.html asks for a republish and does not insert an iframe.
|
|
8
9
|
*/
|
|
9
10
|
import { REFUSED_HOST_ATTRIBUTE } from "./host-bridge-markers.js";
|
|
10
11
|
export { REFUSED_HOST_ATTRIBUTE };
|
|
11
12
|
export declare function hydratePublishedHost(host: HTMLElement): boolean;
|
|
12
13
|
export declare function hydratePublishedHosts(root?: ParentNode): number;
|
|
14
|
+
/** Enables WebSocket real-time subscription for a published host */
|
|
15
|
+
export declare function enableRealtimeForPublishedHost(host: HTMLElement): () => void;
|
|
16
|
+
/**
|
|
17
|
+
* Reloads a published widget host in place while maintaining playback timestamp and selected item state.
|
|
18
|
+
*/
|
|
19
|
+
export declare function reloadPublishedHost(host: HTMLElement): Promise<boolean>;
|
|
20
|
+
/**
|
|
21
|
+
* Applies real-time content updates to a running widget without refreshing or reloading the iframe.
|
|
22
|
+
*/
|
|
23
|
+
export declare function applyLiveContentUpdate(host: HTMLElement, data: unknown): void;
|
|
24
|
+
/**
|
|
25
|
+
* Applies real-time style/design updates to a running widget without refreshing or reloading the iframe.
|
|
26
|
+
*/
|
|
27
|
+
export declare function applyLiveStyleUpdate(host: HTMLElement, styles: unknown): void;
|
|
13
28
|
/** Clears the bridge when a host is removed from the page. */
|
|
14
29
|
export declare function teardownPublishedHost(host: HTMLElement): void;
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Mount a published direct module inside `<widgetic>`.
|
|
3
|
+
* The tag has no hyphen, so the shadow root sits on a child.
|
|
4
|
+
*/
|
|
5
|
+
import type { PublicEmbedPayload } from "./public-embed-lookup.js";
|
|
6
|
+
export declare const DIRECT_CONTRACT_VERSION = 2;
|
|
7
|
+
export type DirectWidgetInstance = {
|
|
8
|
+
update: (next: Record<string, unknown>) => void;
|
|
9
|
+
destroy: () => void;
|
|
10
|
+
};
|
|
11
|
+
export type DirectWidgetModule = {
|
|
12
|
+
contractVersion: number;
|
|
13
|
+
getStyles: () => string;
|
|
14
|
+
mount: (target: HTMLElement, props: Record<string, unknown>) => DirectWidgetInstance;
|
|
15
|
+
};
|
|
16
|
+
type DirectModuleLoader = (url: string) => Promise<DirectWidgetModule>;
|
|
17
|
+
/** Tests replace the network import. Pass null to restore it. */
|
|
18
|
+
export declare function setDirectModuleLoader(loader: DirectModuleLoader | null): void;
|
|
19
|
+
/**
|
|
20
|
+
* Updates a live direct-mounted widget in place (e.g. from a WebSocket content/style push)
|
|
21
|
+
* without destroying or reloading the widget.
|
|
22
|
+
*/
|
|
23
|
+
export declare function updateDirectMount(host: HTMLElement, nextOverlay: {
|
|
24
|
+
design?: Record<string, string>;
|
|
25
|
+
content?: Record<string, unknown>;
|
|
26
|
+
contentItems?: unknown[];
|
|
27
|
+
}): boolean;
|
|
28
|
+
export declare function destroyDirectMount(host: HTMLElement): void;
|
|
29
|
+
/**
|
|
30
|
+
* Loads the module and mounts it. Returns false when the module is missing,
|
|
31
|
+
* the contract is not 2, the load fails, or the host changed while loading.
|
|
32
|
+
*/
|
|
33
|
+
export declare function mountDirectWidget(host: HTMLElement, payload: PublicEmbedPayload, width: string | undefined, markMounted: (host: HTMLElement) => void): Promise<boolean>;
|
|
34
|
+
export {};
|
|
@@ -30,9 +30,21 @@ export type PublicEmbedOverlay = {
|
|
|
30
30
|
content?: Record<string, unknown>;
|
|
31
31
|
contentItems?: unknown[];
|
|
32
32
|
};
|
|
33
|
+
export type PublicEmbedDirect = {
|
|
34
|
+
moduleUrl: string;
|
|
35
|
+
contractVersion: number;
|
|
36
|
+
moduleHash?: string | null;
|
|
37
|
+
};
|
|
33
38
|
export type PublicEmbedPayload = PublicEmbedOverlay & {
|
|
34
39
|
embedUrl: string;
|
|
35
40
|
compositionId?: string;
|
|
41
|
+
widgetId?: string;
|
|
42
|
+
direct?: PublicEmbedDirect;
|
|
43
|
+
entryWriteToken?: string;
|
|
44
|
+
entries?: {
|
|
45
|
+
url: string;
|
|
46
|
+
writeToken?: string;
|
|
47
|
+
};
|
|
36
48
|
};
|
|
37
49
|
/** The gateway's refusal: the owner limited this embed to listed websites and this page is not listed. */
|
|
38
50
|
export type PublishedEmbedRefusal = {
|
|
@@ -67,6 +79,11 @@ export type PublishedEmbedLookup = {
|
|
|
67
79
|
export declare function publicCompositionLookupUrls(compositionId: string): string[];
|
|
68
80
|
export declare function resolvePublishedEmbed(compositionId: string): Promise<PublishedEmbedLookup>;
|
|
69
81
|
export declare function resolvePublishedEmbedUrl(compositionId: string): Promise<string | null>;
|
|
82
|
+
export declare function publicWidgetLookupUrls(widgetId: string): string[];
|
|
83
|
+
/**
|
|
84
|
+
* Resolves a published widget directly by its `widget` / `widget-id` (without requiring a saved composition).
|
|
85
|
+
*/
|
|
86
|
+
export declare function resolvePublishedWidgetEmbed(widgetId: string): Promise<PublishedEmbedLookup>;
|
|
70
87
|
/**
|
|
71
88
|
* Tells the developer, once per composition, why an embed was not shown.
|
|
72
89
|
* It is a console.warn on purpose: the SDK logger prints nothing unless debug
|
|
@@ -1,8 +1,32 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Relays `widgetic:host` into the gateway frame and wrapper events back to the page.
|
|
3
3
|
*/
|
|
4
|
+
declare class PublishedHostBridge {
|
|
5
|
+
private readonly host;
|
|
6
|
+
private readonly iframe;
|
|
7
|
+
private readonly gatewayOrigin;
|
|
8
|
+
private readonly compositionId;
|
|
9
|
+
private readyDispatched;
|
|
10
|
+
private attributeFlushScheduled;
|
|
11
|
+
private attributeObserver;
|
|
12
|
+
private readonly onWindowMessage;
|
|
13
|
+
constructor(host: HTMLElement, iframe: HTMLIFrameElement, gatewayOrigin: string, compositionId: string);
|
|
14
|
+
private observeHostAttributes;
|
|
15
|
+
private scheduleHostSnapshot;
|
|
16
|
+
postHostSnapshot(): void;
|
|
17
|
+
sendWidgetUpdate(payload: {
|
|
18
|
+
design?: Record<string, string>;
|
|
19
|
+
content?: Record<string, unknown>;
|
|
20
|
+
contentItems?: unknown[];
|
|
21
|
+
}): void;
|
|
22
|
+
private handleWrapperMessage;
|
|
23
|
+
private dispatchHostEvent;
|
|
24
|
+
destroy(): void;
|
|
25
|
+
}
|
|
4
26
|
/** Attaches the host bridge for a published iframe mount. */
|
|
5
27
|
export declare function attachPublishedHostBridge(host: HTMLElement, iframe: HTMLIFrameElement, embedUrl: string, compositionId: string): void;
|
|
28
|
+
export declare function getPublishedHostBridge(host: HTMLElement): PublishedHostBridge | undefined;
|
|
6
29
|
export declare function detachPublishedHostBridge(host: HTMLElement): void;
|
|
7
30
|
/** Dispatches a host-level embed error (lookup refusal, not found, device restriction). */
|
|
8
31
|
export declare function dispatchPublishedHostError(host: HTMLElement, compositionId: string, code: string): void;
|
|
32
|
+
export {};
|