@widgetic/embed-sdk 2.1.3 → 2.1.4
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/dist/browser/chunks/ABTestManager.js +1 -1
- package/dist/browser/chunks/api.js +1 -1
- package/dist/browser/chunks/core.js +1 -1
- package/dist/browser/chunks/display.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/chunks/workflows.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/api.js +1 -1
- package/dist/esm/chunks/core.js +1 -1
- package/dist/esm/chunks/display.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/chunks/workflows.js +1 -1
- package/dist/esm/embed-bootstrap.js +1 -1
- package/dist/esm/embed-sdk.js +1 -1
- package/dist/esm/types/core/constants.d.ts +1 -1
- package/dist/esm/types/core/version.d.ts +1 -1
- package/dist/esm/types/utils/autoscale-request.d.ts +11 -0
- package/dist/esm/types/utils/embed-autoscale.d.ts +139 -0
- package/dist/esm/types/utils/hydrate-published-host.d.ts +8 -2
- package/dist/esm/types/utils/mount-direct-widget.d.ts +5 -0
- package/dist/esm/types/utils/workflow-shared-contract.d.ts +7 -0
- package/dist/esm/types/workflows/workflow-stage.d.ts +1 -1
- package/dist/umd/embed-bootstrap.js +1 -1
- package/dist/umd/embed-sdk.js +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Autoscale of a plain embed: the `autoscale` attribute of a `<widgetic composition-id>` tag.
|
|
3
|
+
*
|
|
4
|
+
* A tag with `autoscale` is as tall as its widget needs, and follows when that changes (an entry is added to a
|
|
5
|
+
* guestbook, a list loads, the page gets narrower). Without it the embed keeps the size its tag gives, the way an
|
|
6
|
+
* iframe does. The height the tag asks for is the least the embed is tall (`autoscale-min-height` replaces it); the most
|
|
7
|
+
* is `autoscale-max-height` (2000 by default), and `autoscale-debounce`, `-threshold`, `-animate` and
|
|
8
|
+
* `-animation-duration` tune it, with the numbers a workflow embed and the legacy autoscale already use.
|
|
9
|
+
*
|
|
10
|
+
* Two kinds of embed can follow:
|
|
11
|
+
*
|
|
12
|
+
* - A widget mounted in the page (direct): the SDK looks into the widget and works out the height at which none of
|
|
13
|
+
* its scrolling regions has to scroll (`measureNaturalHeight`). The box of the widget keeps an explicit height all
|
|
14
|
+
* the time, so a widget that fills its frame (`height: 100%` all the way down) works as it does in an iframe, and a
|
|
15
|
+
* list that has more entries than fit makes the box taller, not the page longer.
|
|
16
|
+
* - A widget in an iframe: the frame is another document, so it is the widget that says how tall it is, with the
|
|
17
|
+
* `widgetic:resize` message every widget page may send (`detail.height`). The SDK follows what it hears. A widget
|
|
18
|
+
* that never says anything keeps the height of its tag.
|
|
19
|
+
*
|
|
20
|
+
* Not for a workflow's stages (the workflow code follows their height itself, workflows/workflow-stage.ts) and not for an
|
|
21
|
+
* overlay (the overlay decides its own size). A workflow tag has its own rules in src/workflows/workflow-autoscale.ts;
|
|
22
|
+
* the numbers here are the same (embed-autoscale-parity.test.ts holds the two together).
|
|
23
|
+
*
|
|
24
|
+
* The code-split build and the single-file build both put this file in the SDK's own code, not the workflow code, so it
|
|
25
|
+
* never imports from src/workflows/.
|
|
26
|
+
*/
|
|
27
|
+
/** Non-secret runtime constants of an embed's autoscale. The same defaults as the legacy autoscale and a workflow embed. */
|
|
28
|
+
export declare const EMBED_AUTOSCALE_DEFAULTS: {
|
|
29
|
+
readonly MAX_HEIGHT_PIXELS: 2000;
|
|
30
|
+
readonly DEBOUNCE_MILLISECONDS: 150;
|
|
31
|
+
readonly THRESHOLD_PIXELS: 5;
|
|
32
|
+
readonly ANIMATE: true;
|
|
33
|
+
readonly ANIMATION_MILLISECONDS: 300;
|
|
34
|
+
};
|
|
35
|
+
export interface EmbedAutoscaleSettings {
|
|
36
|
+
/** The least the embed is tall, in pixels: the height its tag asks for, or `autoscale-min-height` when the tag names one. */
|
|
37
|
+
floorHeight: number;
|
|
38
|
+
/** The most the embed is tall, in pixels. Never below the floor. */
|
|
39
|
+
maxHeight: number;
|
|
40
|
+
/** The longest the embed waits before it looks at the widget again, in milliseconds. */
|
|
41
|
+
debounceDelay: number;
|
|
42
|
+
/** The smallest change in height worth following, in pixels. */
|
|
43
|
+
threshold: number;
|
|
44
|
+
/** Whether a change in height is animated. */
|
|
45
|
+
animate: boolean;
|
|
46
|
+
/** How long the animation lasts, in milliseconds. */
|
|
47
|
+
animationDuration: number;
|
|
48
|
+
}
|
|
49
|
+
/** Whether a host is a stage of a workflow: the workflow code, not this one, follows its height. */
|
|
50
|
+
export declare function isWorkflowStageHost(host: Element): boolean;
|
|
51
|
+
/**
|
|
52
|
+
* Whether a tag's embed follows its widget's height: it asked for it (`autoscale`) and nothing else decides its size.
|
|
53
|
+
*/
|
|
54
|
+
export declare function shouldAutoscaleEmbed(host: Element): boolean;
|
|
55
|
+
/**
|
|
56
|
+
* The settings of an embed, read from its tag. `tagHeightPixels` is the height the tag's embed starts at (the floor,
|
|
57
|
+
* unless the tag names `autoscale-min-height`).
|
|
58
|
+
*/
|
|
59
|
+
export declare function readEmbedAutoscaleSettings(host: Element, tagHeightPixels: number, prefersReducedMotion?: boolean): EmbedAutoscaleSettings;
|
|
60
|
+
/** A height held between the floor and the maximum, rounded up to a whole pixel (half a pixel less would cut the last line). */
|
|
61
|
+
export declare function clampEmbedHeight(rawHeight: number, settings: Pick<EmbedAutoscaleSettings, "floorHeight" | "maxHeight">): number;
|
|
62
|
+
/**
|
|
63
|
+
* The scroll regions that did not follow the box when it changed height: a list that is as tall as its own CSS says
|
|
64
|
+
* (`max-height: 24rem`, `height: 20rem`), which scrolls inside the widget whatever the widget's box is. Making the box
|
|
65
|
+
* taller for one only leaves empty space, and every look would ask for more, so a region found like this is not asked
|
|
66
|
+
* about again.
|
|
67
|
+
*/
|
|
68
|
+
export type RigidRegions = WeakSet<HTMLElement>;
|
|
69
|
+
/**
|
|
70
|
+
* The height a widget needs: the one at which none of its scrolling regions has to scroll. `boxHeight` is the height of
|
|
71
|
+
* the box the widget is in now; the answer is that plus what the regions are short of (or minus the room they have to
|
|
72
|
+
* spare), so it comes out the same however far a change of height has got. It is null when the box has no size (hidden).
|
|
73
|
+
*/
|
|
74
|
+
export declare function measureNaturalHeight(root: ParentNode, boxHeight: number, rigidRegions?: RigidRegions): number | null;
|
|
75
|
+
/**
|
|
76
|
+
* The height a widget needs, found as `measureNaturalHeight` finds it and then tried out: the box is given that height for
|
|
77
|
+
* a moment and each region says how much of the change it took. A region that took none (a list with a `max-height`, a
|
|
78
|
+
* fixed `height`) is left out from then on; a region that took part of it (a list that stopped growing at its
|
|
79
|
+
* `max-height`) counts for what it took. Without this a box asked to grow for a list that cannot grow would grow at every
|
|
80
|
+
* look, up to its maximum, and leave the widget in a box of empty space.
|
|
81
|
+
*/
|
|
82
|
+
export declare function measureProvenHeight(root: ParentNode, box: HTMLElement, boxHeight: number, settings: Pick<EmbedAutoscaleSettings, "floorHeight" | "maxHeight" | "threshold">, rigidRegions: RigidRegions): number | null;
|
|
83
|
+
export interface HeightFollowerOptions {
|
|
84
|
+
/** The `<widgetic>` tag: the page's `widgetic:autoscale` listeners hear changes here. */
|
|
85
|
+
host: HTMLElement;
|
|
86
|
+
/** The element that has the height: the widget's box, or the iframe. */
|
|
87
|
+
box: HTMLElement;
|
|
88
|
+
compositionId: string;
|
|
89
|
+
settings: EmbedAutoscaleSettings;
|
|
90
|
+
/** The height the box has before autoscale, in pixels: the height its tag asked for. */
|
|
91
|
+
startHeight: number;
|
|
92
|
+
/** What `style.height` of the box was before autoscale, put back when the box is as tall as the tag asked for (in the unit it asked in). */
|
|
93
|
+
originalHeightCss: string;
|
|
94
|
+
}
|
|
95
|
+
export interface HeightFollower {
|
|
96
|
+
/** The height the box has now, in pixels (the height of its tag until it is given another). */
|
|
97
|
+
currentHeight(): number;
|
|
98
|
+
/** Gives the box the height that fits `naturalHeight` when that is worth a change. Returns whether the box changed. */
|
|
99
|
+
follow(naturalHeight: number): boolean;
|
|
100
|
+
/** Starts at the height this composition had the last time it was shown, when that was taller than the floor. */
|
|
101
|
+
startAtStoredHeight(): boolean;
|
|
102
|
+
/** Whether the box is still on its way to the height it was last given (it is not tried out or measured until it is there). */
|
|
103
|
+
isAnimating(): boolean;
|
|
104
|
+
}
|
|
105
|
+
/** Whether a new height is different enough from the one shown to be worth following. */
|
|
106
|
+
export declare function isChangeWorthFollowing(currentHeight: number, nextHeight: number, threshold: number): boolean;
|
|
107
|
+
export declare function createHeightFollower(options: HeightFollowerOptions): HeightFollower;
|
|
108
|
+
export interface DirectAutoscaleOptions {
|
|
109
|
+
/** The `<widgetic>` tag. */
|
|
110
|
+
host: HTMLElement;
|
|
111
|
+
/** The box the SDK made for the widget (`div[data-widgetic-direct]`), already in the page. */
|
|
112
|
+
box: HTMLElement;
|
|
113
|
+
/** The shadow root of the box, where the widget is. */
|
|
114
|
+
shadowRoot: ShadowRoot;
|
|
115
|
+
compositionId: string;
|
|
116
|
+
/** The height of the tag in pixels when the browser cannot say how tall the box is (the tag is not shown yet). */
|
|
117
|
+
fallbackHeightPixels: number;
|
|
118
|
+
}
|
|
119
|
+
export interface AutoscaleHandle {
|
|
120
|
+
/** Looks at the widget again, soon (changes close together are followed once). */
|
|
121
|
+
refresh(): void;
|
|
122
|
+
/** Stops following. The box keeps the height it has. */
|
|
123
|
+
stop(): void;
|
|
124
|
+
}
|
|
125
|
+
export declare function startDirectAutoscale(options: DirectAutoscaleOptions): AutoscaleHandle;
|
|
126
|
+
/** Stops following the iframe of this tag, if it is being followed. */
|
|
127
|
+
export declare function stopFramedAutoscale(host: HTMLElement): void;
|
|
128
|
+
export interface FramedAutoscaleOptions {
|
|
129
|
+
host: HTMLElement;
|
|
130
|
+
iframe: HTMLIFrameElement;
|
|
131
|
+
compositionId: string;
|
|
132
|
+
/** The height of the tag in pixels when the browser cannot say how tall the iframe is (the tag is not shown yet). */
|
|
133
|
+
fallbackHeightPixels: number;
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* The iframe of this tag is as tall as its widget says it is. The widget says it with `widgetic:resize` (`detail.height`
|
|
137
|
+
* in pixels), which reaches the tag as an event. A widget that does not say keeps the height of its tag.
|
|
138
|
+
*/
|
|
139
|
+
export declare function startFramedAutoscale(options: FramedAutoscaleOptions): AutoscaleHandle;
|
|
@@ -1,11 +1,17 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Hydrate customer `<widgetic composition-id>` in place.
|
|
3
|
-
* Customer tag is one word: `<widgetic>`. No `<widgetic-widget
|
|
3
|
+
* Customer tag is one word: `<widgetic>`. No `<widgetic-widget>`.
|
|
4
4
|
*
|
|
5
5
|
* Copy iframe = raw `<iframe src>` without SDK.
|
|
6
6
|
* Copy web component = SDK + `<widgetic composition-id>`. When the published
|
|
7
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
|
+
* with only widget.html asks for a republish and does not insert an iframe
|
|
9
|
+
* (`render-mode="iframe"` on the tag asks for the iframe).
|
|
10
|
+
*
|
|
11
|
+
* The box of either is as big as the tag says. A tag that also says `autoscale`
|
|
12
|
+
* gets a box that follows the height of the widget (embed-autoscale.ts): the
|
|
13
|
+
* list the widget measures for a mount in the page, the widget's own
|
|
14
|
+
* `widgetic:resize` for an iframe.
|
|
9
15
|
*/
|
|
10
16
|
import { REFUSED_HOST_ATTRIBUTE } from "./host-bridge-markers.js";
|
|
11
17
|
export { REFUSED_HOST_ATTRIBUTE };
|
|
@@ -60,6 +60,11 @@ export declare const DIRECT_BOX_DEFAULTS: {
|
|
|
60
60
|
* A value that is not a number or a number with a unit gives the fallback, in pixels.
|
|
61
61
|
*/
|
|
62
62
|
export declare function cssLengthOfEmbedAttribute(value: string | null | undefined, fallbackPixels: number): string;
|
|
63
|
+
/**
|
|
64
|
+
* The number of pixels a `width` or `height` of an embed code stands for when it is a plain number or a number of
|
|
65
|
+
* pixels (`405`, `405px`), or the fallback for anything else (a percentage has no size until the box is in the page).
|
|
66
|
+
*/
|
|
67
|
+
export declare function pixelsOfEmbedAttribute(value: string | null | undefined, fallbackPixels: number): number;
|
|
63
68
|
/**
|
|
64
69
|
* The rules, in the shadow root and ahead of the module's own, that make the mount target what `#app.widgetic-root-el`
|
|
65
70
|
* is in the widget's frame page: it fills the box, and so does the first thing the module puts in it (the widget's root;
|
|
@@ -33,3 +33,10 @@ export declare const WORKFLOW_SHARED_CONTRACT_VERSION = 1;
|
|
|
33
33
|
export declare const WORKFLOW_SHARED_SERVICES_GLOBAL = "__widgeticEmbedSharedServices";
|
|
34
34
|
/** Where the workflow code leaves what it offers to the SDK. */
|
|
35
35
|
export declare const WORKFLOW_EXPORTS_GLOBAL = "__widgeticEmbedWorkflows";
|
|
36
|
+
/**
|
|
37
|
+
* Marks a stage: a composition the workflow code built for a workflow. The workflow code writes it on the `<widgetic>`
|
|
38
|
+
* element it makes (src/workflows/workflow-stage.ts), and the SDK reads it when it mounts the widget in that element:
|
|
39
|
+
* a stage is as tall as its widget, and the viewport follows that, so the SDK must not give it a box of a fixed size.
|
|
40
|
+
* It lives here because both files need the same name and this is the one module they share.
|
|
41
|
+
*/
|
|
42
|
+
export declare const WORKFLOW_STAGE_ATTRIBUTE = "data-widgetic-workflow-stage";
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
*/
|
|
19
19
|
/** Marks the viewport the SDK puts on a tag. */
|
|
20
20
|
export declare const VIEWPORT_ATTRIBUTE = "data-widgetic-workflow-viewport";
|
|
21
|
-
/** Marks a stage: a composition built for a workflow. */
|
|
21
|
+
/** Marks a stage: a composition built for a workflow (the name is shared with the SDK, see workflow-shared-contract.ts). */
|
|
22
22
|
export declare const STAGE_ATTRIBUTE = "data-widgetic-workflow-stage";
|
|
23
23
|
/** Tells the viewport a stage has this height now. */
|
|
24
24
|
export type HeightReport = (entries: Array<{
|