@widgetic/embed-sdk 2.1.6 → 2.1.8

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.
@@ -0,0 +1,56 @@
1
+ /**
2
+ * The Resize Mode and the Responsive Breakpoint of a hydrated `<widgetic composition-id>` tag.
3
+ *
4
+ * The Embed Editor writes both into the embed code (`resize="fill-width"`, `adaptive="480"`), and until this module
5
+ * existed nothing on the published path read them: `parseWidgetConfig` parsed them and the batch renderer that acts on
6
+ * them is only reached by tags that do not hydrate (the same gap published-host-display.ts closed for the device switches
7
+ * and the overlay). A published embed was always the fixed box of its `width` and `height`, whatever "Fill width" or
8
+ * "Responsive" said.
9
+ *
10
+ * This is the missing wire. It leaves the box the tag has always had (embed-resize-request.ts says what each Resize Mode
11
+ * means) and changes only what the tag asks to change:
12
+ *
13
+ * - `fill-width` and `responsive` make the box as wide as the space the tag is in (`responsive` stops at the tag's own
14
+ * `width`). The height stays the tag's `height`, and a tag with `autoscale` keeps following its widget as it did. A tag
15
+ * without `autoscale`, whose `width` and `height` are both numbers, keeps the proportions of that width and height
16
+ * instead, so a box that gets narrower gets shorter as a picture does.
17
+ * - `adaptive` is the breakpoint of the window: the tag says `data-widgetic-mobile="true"` while the window is as
18
+ * narrow as the breakpoint or narrower and `"false"` above it, and sends `widgetic:adaptive` when that changes, so the
19
+ * page (or a widget that listens) can switch to its mobile layout. A `responsive` tag that names no breakpoint
20
+ * gets the Embed Editor's own, 480. The box itself is not changed by the breakpoint: a `fixed` tag stays fixed.
21
+ *
22
+ * It is not for a stage of a workflow (the workflow's viewport sizes it), nor for an overlay or a mixed embed: the overlay
23
+ * decides its own size (`overlay-resize-mode`), and a widget that is moved into it must not be left with a width that is
24
+ * a percentage of the place it was moved from.
25
+ *
26
+ * Nothing here may stop a widget from showing: a failure leaves the box as it is.
27
+ */
28
+ /** The Responsive Breakpoint a `responsive` tag gets when it names none: the one the Embed Editor's control starts at. */
29
+ export declare const RESPONSIVE_BREAKPOINT_DEFAULT_PIXELS = 480;
30
+ /** Set on a tag that has a breakpoint: "true" while the window is as narrow as the breakpoint or narrower, "false" above it. */
31
+ export declare const MOBILE_HOST_ATTRIBUTE = "data-widgetic-mobile";
32
+ /** What the tag sends when the window crosses its breakpoint (and once, when the box is made). Bubbles, and is composed. */
33
+ export declare const ADAPTIVE_EVENT_NAME = "widgetic:adaptive";
34
+ export interface PublishedBoxOptions {
35
+ /** The `<widgetic>` tag. */
36
+ host: HTMLElement;
37
+ /** The element that is the widget's box: the SDK's `div[data-widgetic-direct]`, or the iframe. */
38
+ box: HTMLElement;
39
+ /** The tag's width as a CSS length that is safe to write into a style (`800px`, `100%`): see cssLengthOfEmbedAttribute. */
40
+ widthCss: string;
41
+ /** The tag's width in pixels, or null when it is not a number of pixels (`100%`): see readEmbedPixels. */
42
+ widthPixels: number | null;
43
+ /** The tag's height in pixels, or null when it is not a number of pixels. */
44
+ heightPixels: number | null;
45
+ }
46
+ /** Stops following the box of this tag, if it is being followed. The box keeps the size it has. */
47
+ export declare function stopFollowingPublishedBox(host: HTMLElement): void;
48
+ /**
49
+ * Sizes the box of a published tag the way its Resize Mode says, and tells the tag about its Responsive Breakpoint.
50
+ * Returns the function that stops following (also reachable with `stopFollowingPublishedBox(host)`); a tag with nothing to
51
+ * follow, and any failure, give a function that does nothing.
52
+ *
53
+ * Called with the box in the page and before autoscale starts: autoscale reads the height of the box, and this changes
54
+ * only its width (and its height, for a tag that does not autoscale).
55
+ */
56
+ export declare function followPublishedBox(options: PublishedBoxOptions): () => void;
@@ -1,23 +1,49 @@
1
1
  /**
2
2
  * What a workflow embed reports back to the gateway: how many visitors reached a block (`n`), took a connection (`e`),
3
- * or could not be moved on to a composition (`f`).
3
+ * or could not be moved on to a composition (`f`), and how tall the first step stood for a visitor who had not seen it
4
+ * before (a height: a composition id and a whole number of pixels).
4
5
  *
5
6
  * Counts are ids and numbers. No visitor, no value a visitor typed and no address is ever in a report; the gateway keeps
6
7
  * the same and nothing more. The report carries the token the gateway signed for exactly this workflow and version when
7
8
  * it handed out the graph, so a page that never read the workflow cannot raise its numbers.
8
9
  *
10
+ * A failure (`f`) may say why it happened, with one of four words (`FailureReason`) sent as one letter. It is a closed
11
+ * list on purpose: never a message, never the code a widget reported, never anything a visitor or a page could have
12
+ * written. The gateway counts the reason beside the failure, so a workflow's owner can tell a step that is too slow
13
+ * from one that is broken.
14
+ *
9
15
  * Counts are small and lossy by design: they wait a moment so that what happens together goes in one report, they are
10
16
  * sent once and never retried, and a report the gateway refuses or cannot take is simply dropped. A workflow never
11
17
  * waits for its numbers and never shows a visitor a thing about them.
18
+ *
19
+ * A height is reported to teach the gateway what height the embed code of the workflow should start at, instead of a
20
+ * guess. It is noted as the step's height changes, reported once it has held still (or as the page goes), and only once
21
+ * per step in a page view.
12
22
  */
13
23
  /** How long a count waits for company before it is reported. */
14
24
  export declare const FLUSH_DELAY_MILLISECONDS = 2000;
15
25
  /**
16
- * The most events one report carries (the gateway's limit). At most 90 characters each, so a report of this many is far
17
- * below the 16 KB the gateway takes, whatever the ids are.
26
+ * The most events one report carries (the gateway's limit). At most 100 characters each (`{"k":"f","id":<64>,"c":50,"r":"t"}`
27
+ * is 96), so a report of this many is about 10 KB, below the 16 KB the gateway takes, whatever the ids are.
18
28
  */
19
29
  export declare const MAX_EVENTS_PER_REPORT = 100;
30
+ /** How long the height of a step has to hold still before it is reported as the height the step settled at. */
31
+ export declare const HEIGHT_SETTLE_MILLISECONDS = 3000;
32
+ /**
33
+ * The most steps one embed reports a height for (the gateway's limit for one report). The embed reports the first step
34
+ * only, so this is a bound and not a number it comes near.
35
+ */
36
+ export declare const MAX_HEIGHTS_PER_REPORT = 10;
20
37
  export type CountKind = "n" | "e" | "f";
38
+ /**
39
+ * Why a composition could not be shown, in the four words the gateway counts (its `WORKFLOW_FAILURE_REASONS`).
40
+ * - `timeout`: the composition did not say it was up in time (8 seconds, unless the page asked for another), and nothing
41
+ * said why.
42
+ * - `widget_error`: the widget in it reported that it could not start.
43
+ * - `build`: the embed itself could not build the step (it threw before the widget could say anything).
44
+ * - `other`: anything else, such as a step that was still being built, or a page that went away meanwhile.
45
+ */
46
+ export type FailureReason = "timeout" | "widget_error" | "build" | "other";
21
47
  export interface WorkflowCountsOptions {
22
48
  workflowId: string;
23
49
  /** The published version the visitor is on. Counts belong to it. */
@@ -35,6 +61,12 @@ export declare class WorkflowCounts {
35
61
  /** The last event of each thing counted, so the same thing counted again is added to it. */
36
62
  private lastEventOf;
37
63
  private flushTimer;
64
+ /** The latest height noted for each step that has not held still yet, and the timer that says when it has. */
65
+ private waitingHeights;
66
+ /** Heights that held still and wait to go in the next report. */
67
+ private settledHeights;
68
+ /** The steps a height was handed over for: a step is reported once per page view, whatever it does after. */
69
+ private reportedSteps;
38
70
  private stopped;
39
71
  private listening;
40
72
  constructor(options: WorkflowCountsOptions);
@@ -45,8 +77,18 @@ export declare class WorkflowCounts {
45
77
  * send anything. Safe to call more than once.
46
78
  */
47
79
  start(): void;
48
- /** Counts that something happened `times` times (once by default). Anything that cannot be an event is ignored. */
49
- count(kind: CountKind, id: string, times?: number): void;
80
+ /**
81
+ * Counts that something happened `times` times (once by default). Anything that cannot be an event is ignored.
82
+ * A failure may say why (`reason`); a reason that is not one of the four, or one given to a count that is not a
83
+ * failure, is left out and the count is made all the same: how often it happened matters more than why.
84
+ */
85
+ count(kind: CountKind, id: string, times?: number, reason?: FailureReason): void;
86
+ /**
87
+ * Notes how tall a step is, for the gateway to learn what height the embed code of the workflow starts at. The latest
88
+ * height noted is reported once it has held still for `HEIGHT_SETTLE_MILLISECONDS`, or as the page is hidden or
89
+ * closed; a step is reported once per page view. Anything that cannot be a height is ignored.
90
+ */
91
+ noteHeight(compositionId: string, height: number): void;
50
92
  /** Reports what is waiting by a beacon, which the browser finishes even when the page is gone. */
51
93
  flushBeforeLeaving(): void;
52
94
  /** Ends counting: whatever was waiting is forgotten and nothing is sent again. */
@@ -55,6 +97,13 @@ export declare class WorkflowCounts {
55
97
  private readonly onVisibilityChange;
56
98
  /** Takes the next report's worth off the waiting events. */
57
99
  private takeBatch;
100
+ /** Takes the heights that held still off the waiting ones, to go in a report. */
101
+ private takeSettledHeights;
102
+ /** A step's height held still: it goes in the next report, and that step is not reported again. */
103
+ private settleHeight;
104
+ /** The page is going: a height that has not held still yet is the last one the visitor saw, and the last chance to report it. */
105
+ private settleWaitingHeights;
106
+ private handOver;
58
107
  private forgetPending;
59
108
  private flush;
60
109
  private reportAddress;
@@ -30,9 +30,9 @@
30
30
  * composition (see `startWorkflowEmbed`'s return value and `becomePlain`), and everything is logged once, at debug level.
31
31
  */
32
32
  import { type WorkflowWatch } from "../utils/host-workflow-watch";
33
- import { WorkflowCounts, type WorkflowCountsOptions } from "./workflow-counts";
33
+ import { WorkflowCounts, type FailureReason, type WorkflowCountsOptions } from "./workflow-counts";
34
34
  import { type WorkflowLookup, type WorkflowLookupOptions } from "./workflow-lookup";
35
- import { type ViewportServices } from "./workflow-stage";
35
+ import { type SwapOutcome, type ViewportServices } from "./workflow-stage";
36
36
  /** How long after a failed step the visitor is moved on again, if they are still where they were. Once. */
37
37
  export declare const RETRY_AFTER_FAILED_STEP_MILLISECONDS = 30000;
38
38
  /**
@@ -42,7 +42,16 @@ export declare const RETRY_AFTER_FAILED_STEP_MILLISECONDS = 30000;
42
42
  */
43
43
  export declare const FIRST_COMPOSITION_WAIT_MILLISECONDS = 2000;
44
44
  /** What the runtime needs of the counts. */
45
- type CountsPort = Pick<WorkflowCounts, "start" | "count" | "flushBeforeLeaving" | "dispose">;
45
+ type CountsPort = Pick<WorkflowCounts, "start" | "count" | "noteHeight" | "flushBeforeLeaving" | "dispose">;
46
+ /**
47
+ * Why a composition could not be shown, in the four words the counts carry. What the viewport says (`timeout`, or
48
+ * `error` when the widget reported it could not start) is told apart from the embed failing to build the step at all
49
+ * (`threw`), and the rest (a step still being built, a viewport that was taken away) is `other`. A closed list: nothing
50
+ * the widget or the page said ever travels with it.
51
+ */
52
+ export declare function failureReasonOf(outcome: Extract<SwapOutcome, {
53
+ status: "failed";
54
+ }>, threw: boolean): FailureReason;
46
55
  /** What a test may steer about the viewport. */
47
56
  export interface ViewportTuning {
48
57
  createHeightObserver?: ViewportServices["createHeightObserver"];
@@ -56,6 +56,14 @@ export interface ViewportServices {
56
56
  onStageCreated?: (stage: HTMLElement, description: StageDescription) => void;
57
57
  /** A stage was taken off the page (replaced, failed, or the viewport went). */
58
58
  onStageRemoved?: (stage: HTMLElement) => void;
59
+ /**
60
+ * How tall the first stage is, as the visitor sees it, when nobody has seen it in this browser before (a visitor who
61
+ * comes back is not told: the height remembered for them is not what a first visit looks like). `standsFor` is the
62
+ * composition of the workflow the stage is for. Told again as the height changes; it is for the one that listens to
63
+ * decide when the height has settled. Only a stage that shows the composition itself, in the page and not in an
64
+ * overlay, and whose height is the widget's own and not a frame's guess, is told about.
65
+ */
66
+ onFirstStageHeight?: (standsFor: string, height: number) => void;
59
67
  /** How long the next composition is given to appear. */
60
68
  readyTimeoutMilliseconds?: number;
61
69
  }
@@ -99,6 +107,10 @@ export declare class WorkflowViewport {
99
107
  private pendingHeight;
100
108
  private destroyed;
101
109
  private warnedAboutFrameWithoutHeight;
110
+ /** The first stage, while its height is one a first-time visitor sees (see `onFirstStageHeight`); otherwise none. */
111
+ private firstVisitStage;
112
+ /** Whether that stage's widget is up: its height before that is a placeholder's. */
113
+ private firstVisitStageIsReady;
102
114
  constructor(options: WorkflowViewportOptions);
103
115
  /** The stage on screen, if any. */
104
116
  currentStage(): HTMLElement | null;
@@ -148,7 +160,10 @@ export declare class WorkflowViewport {
148
160
  private positionAsLayer;
149
161
  private positionInFlow;
150
162
  private measure;
151
- /** Reserves what the composition took last time, so the page does not jump when the first one is shown. */
163
+ /**
164
+ * Reserves what the composition took last time, so the page does not jump when the first one is shown. Says whether
165
+ * there was anything remembered: if not, this browser has not seen the composition (in a day).
166
+ */
152
167
  private holdRoomFor;
153
168
  private settings;
154
169
  /** The room an overlay has on the visitor's screen, or null for an embed that sits in the page. */
@@ -160,6 +175,12 @@ export declare class WorkflowViewport {
160
175
  * followed when it moved by more than the threshold.
161
176
  */
162
177
  private applyHeight;
178
+ /**
179
+ * Tells what is listening how tall the first stage is, when it is what a first-time visitor sees. The height told is what
180
+ * the stage measures, not what the viewport settles at: a page's own minimum, maximum or overlay limit is the page's
181
+ * wish, and the step is as tall as it is whatever page it stands in.
182
+ */
183
+ private tellFirstVisitHeight;
163
184
  private setHeight;
164
185
  private clearHeightTimer;
165
186
  }