@widgetic/embed-sdk 2.0.17 → 2.1.0

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.
Files changed (45) hide show
  1. package/README.md +26 -4
  2. package/dist/browser/chunks/ABTestManager.js +1 -1
  3. package/dist/browser/chunks/api.js +1 -1
  4. package/dist/browser/chunks/core.js +1 -1
  5. package/dist/browser/chunks/renderers.js +1 -1
  6. package/dist/browser/chunks/scanner.js +1 -1
  7. package/dist/browser/chunks/workflows.js +1 -0
  8. package/dist/browser/embed-bootstrap.js +1 -1
  9. package/dist/browser/embed-sdk.js +1 -1
  10. package/dist/esm/chunks/ABTestManager.js +1 -1
  11. package/dist/esm/chunks/api.js +1 -1
  12. package/dist/esm/chunks/core.js +1 -1
  13. package/dist/esm/chunks/renderers.js +1 -1
  14. package/dist/esm/chunks/scanner.js +1 -1
  15. package/dist/esm/chunks/workflows.js +1 -0
  16. package/dist/esm/embed-bootstrap.js +1 -1
  17. package/dist/esm/embed-sdk.js +1 -1
  18. package/dist/esm/types/abTesting/abVisitor.d.ts +2 -0
  19. package/dist/esm/types/core/autoscale-manager.d.ts +6 -0
  20. package/dist/esm/types/embed-sdk.d.ts +1 -0
  21. package/dist/esm/types/sdk/embed-sdk.d.ts +1 -0
  22. package/dist/esm/types/utils/declarative-embed-parser.d.ts +5 -0
  23. package/dist/esm/types/utils/host-workflow-watch.d.ts +62 -0
  24. package/dist/esm/types/utils/hydrate-published-host.d.ts +1 -0
  25. package/dist/esm/types/utils/mount-direct-widget.d.ts +12 -0
  26. package/dist/esm/types/utils/public-embed-lookup.d.ts +5 -0
  27. package/dist/esm/types/utils/published-host-bridge.d.ts +10 -0
  28. package/dist/esm/types/utils/workflow-code-loader.d.ts +14 -0
  29. package/dist/esm/types/utils/workflow-code-loader.umd.d.ts +32 -0
  30. package/dist/esm/types/utils/workflow-embed-registry.d.ts +15 -0
  31. package/dist/esm/types/utils/workflow-page-events.d.ts +41 -0
  32. package/dist/esm/types/utils/workflow-shared-contract.d.ts +35 -0
  33. package/dist/esm/types/utils/workflow-shared-services.d.ts +84 -0
  34. package/dist/esm/types/workflows/umd-entry.d.ts +1 -0
  35. package/dist/esm/types/workflows/visitor-position.d.ts +32 -0
  36. package/dist/esm/types/workflows/workflow-autoscale.d.ts +41 -0
  37. package/dist/esm/types/workflows/workflow-counts.d.ts +65 -0
  38. package/dist/esm/types/workflows/workflow-host.d.ts +71 -0
  39. package/dist/esm/types/workflows/workflow-lookup.d.ts +53 -0
  40. package/dist/esm/types/workflows/workflow-signals.d.ts +34 -0
  41. package/dist/esm/types/workflows/workflow-stage.d.ts +154 -0
  42. package/dist/umd/embed-bootstrap.js +1 -1
  43. package/dist/umd/embed-sdk-workflows.js +1 -0
  44. package/dist/umd/embed-sdk.js +1 -1
  45. package/package.json +2 -1
@@ -0,0 +1,41 @@
1
+ /**
2
+ * What a page can tell a workflow: `sendWorkflowEvent(host, name, values)`, or the DOM event it is made of.
3
+ *
4
+ * Lives outside `src/workflows/` on purpose: that folder is the part of the SDK that is only loaded for a page that
5
+ * has a `workflow-id` tag, and `sendWorkflowEvent` is exported for every page. So this file is small and depends on
6
+ * nothing; it keeps its own copy of the engine's limits, and a test pins that they are the same.
7
+ *
8
+ * A page is not trusted. A name or a value that does not fit is dropped here, before the workflow sees it, and what
9
+ * remains is only ever read by a published condition and then forgotten.
10
+ */
11
+ /** The DOM event a page dispatches on the `<widgetic>` tag to tell its workflow something. */
12
+ export declare const WORKFLOW_EVENT_TYPE = "widgetic:workflow-event";
13
+ /** The DOM event the tag dispatches when a visitor moves to the next composition (`{ workflowId, from, to }`). */
14
+ export declare const WORKFLOW_STEP_EVENT_TYPE = "widgetic:workflow-step";
15
+ /** What a name of an event or of one of its values may look like. The engine's `EVENT_NAME_PATTERN`. */
16
+ export declare const PAGE_EVENT_NAME_PATTERN: RegExp;
17
+ /** How many events a page may send before the workflow is ready; the oldest are dropped past this. */
18
+ export declare const MAX_QUEUED_PAGE_EVENTS = 20;
19
+ export type PageEventValue = string | number | boolean;
20
+ export interface PageEvent {
21
+ name: string;
22
+ values: Record<string, PageEventValue>;
23
+ }
24
+ /** Reads what a page sent: a name that fits, and the values that fit. Null when there is no usable name. */
25
+ export declare function readPageEvent(detail: unknown): PageEvent | null;
26
+ /**
27
+ * Tells the workflow of a `<widgetic workflow-id>` tag that something happened on the page (an Event from your page
28
+ * trigger waits for it by name). Returns false, and does nothing, when the name does not fit.
29
+ */
30
+ export declare function sendWorkflowEvent(host: HTMLElement, name: string, values?: Record<string, unknown>): boolean;
31
+ /**
32
+ * Events a page sends before its workflow is ready (the graph is still being read, or the next composition is still
33
+ * being shown). They are kept, up to a limit, and handed over in order once the workflow can use them.
34
+ */
35
+ export declare class PageEventQueue {
36
+ private events;
37
+ add(event: PageEvent): void;
38
+ /** What was kept, oldest first; the queue is empty afterwards. */
39
+ take(): PageEvent[];
40
+ clear(): void;
41
+ }
@@ -0,0 +1,35 @@
1
+ /**
2
+ * What the two files of the single-file (UMD) build agree on: the SDK itself (`embed-sdk.js`, which every page that
3
+ * embeds a widget loads) and the code of a `<widgetic workflow-id>` tag (`embed-sdk-workflows.js`, which only a page
4
+ * with such a tag loads, and which the SDK asks for when it meets one).
5
+ *
6
+ * The code-split builds (ESM, for bundlers) need none of this: there the workflow code is a chunk of the same build and
7
+ * shares the SDK's modules the way every chunk does.
8
+ *
9
+ * The two files are built together and published together, but a visitor's browser can hold one of them from an
10
+ * earlier release for a while. So the pair checks that it is talking to its own kind:
11
+ *
12
+ * 1. The SDK puts the services the workflow code needs under WORKFLOW_SHARED_SERVICES_GLOBAL (see
13
+ * workflow-shared-services.ts) and adds the script of the workflow code to the page.
14
+ * 2. The workflow code (src/workflows/umd-entry.ts) leaves what it offers under WORKFLOW_EXPORTS_GLOBAL, together
15
+ * with the version of this contract it was built against.
16
+ * 3. The SDK takes it only if that version is its own. Otherwise the tag is embedded as a plain one, which is what
17
+ * happens when the code cannot be loaded at all.
18
+ *
19
+ * Both globals are there for the moment of the hand-over and removed straight after it.
20
+ *
21
+ * Raise WORKFLOW_SHARED_CONTRACT_VERSION whenever the shape of the services or of the exports changes.
22
+ *
23
+ * This file is the one module that both files contain a copy of (scripts-sdk/workflow-bundle.js lets it into the
24
+ * workflow code and tests/unit/scripts/umd-layout.test.ts holds the line on everything else), and it must stay free of
25
+ * state for that reason.
26
+ */
27
+ /** The version of the hand-over described above. */
28
+ export declare const WORKFLOW_SHARED_CONTRACT_VERSION = 1;
29
+ /**
30
+ * Where the SDK leaves the services for the workflow code. scripts-sdk/workflow-shared-modules.js has the same name
31
+ * (the build reads the global from there), and the test next to the layout test holds the two together.
32
+ */
33
+ export declare const WORKFLOW_SHARED_SERVICES_GLOBAL = "__widgeticEmbedSharedServices";
34
+ /** Where the workflow code leaves what it offers to the SDK. */
35
+ export declare const WORKFLOW_EXPORTS_GLOBAL = "__widgeticEmbedWorkflows";
@@ -0,0 +1,84 @@
1
+ import { elementMatchesGoalTarget, readStoredValue, removeStoredValue, writeStoredValue } from "../abTesting/abVisitor";
2
+ import { readStoredAutoscaleHeight, writeStoredAutoscaleHeight } from "../core/autoscale-manager";
3
+ import { declarativeChildrenOf, isReservedHostAttribute } from "./declarative-embed-parser";
4
+ import { buildWorkflowWatch, splitActionId, workflowWatchProperty } from "./host-workflow-watch";
5
+ import { setDirectMountWorkflow, warmDirectModule } from "./mount-direct-widget";
6
+ import { publicEmbedApiOrigins, resolvePublishedEmbed } from "./public-embed-lookup";
7
+ import { dispatchPublishedHostError, getPublishedHostBridge } from "./published-host-bridge";
8
+ import { registerWorkflowEmbed } from "./workflow-embed-registry";
9
+ import { PageEventQueue, readPageEvent } from "./workflow-page-events";
10
+ /**
11
+ * What the code of a `<widgetic workflow-id>` tag takes from the SDK, in the single-file (UMD) build, where that code
12
+ * is a file of its own (see workflow-shared-contract.ts for the hand-over).
13
+ *
14
+ * The workflow code is built without these modules and reads them from the object below instead, so that there is one
15
+ * of each on the page: the registry of embeds, the bridge to the published hosts, the visitor's stored values and the
16
+ * rest keep their state in these modules, and a second copy of any of them in the workflow code would have a state of
17
+ * its own that the SDK never sees.
18
+ *
19
+ * One entry for each module that src/workflows/ imports (the list is in scripts-sdk/workflow-shared-modules.js, which
20
+ * the build uses to leave them out of the workflow code), and in each entry the names that src/workflows/ takes from
21
+ * it. They are named one by one, not handed over as whole modules, so that the SDK keeps tree-shaking what the
22
+ * workflows do not use. tests/unit/utils/workflow-shared-services.test.ts reads the imports of src/workflows/ and fails
23
+ * the moment one is missing here.
24
+ */
25
+ export declare function createWorkflowSharedServices(): {
26
+ contractVersion: number;
27
+ abVisitor: {
28
+ elementMatchesGoalTarget: typeof elementMatchesGoalTarget;
29
+ readStoredValue: typeof readStoredValue;
30
+ removeStoredValue: typeof removeStoredValue;
31
+ writeStoredValue: typeof writeStoredValue;
32
+ };
33
+ autoscaleManager: {
34
+ readStoredAutoscaleHeight: typeof readStoredAutoscaleHeight;
35
+ writeStoredAutoscaleHeight: typeof writeStoredAutoscaleHeight;
36
+ };
37
+ declarativeEmbedParser: {
38
+ declarativeChildrenOf: typeof declarativeChildrenOf;
39
+ isReservedHostAttribute: typeof isReservedHostAttribute;
40
+ };
41
+ hostBridgeMarkers: {
42
+ REFUSED_HOST_ATTRIBUTE: string;
43
+ };
44
+ hostWorkflowWatch: {
45
+ buildWorkflowWatch: typeof buildWorkflowWatch;
46
+ splitActionId: typeof splitActionId;
47
+ workflowWatchProperty: typeof workflowWatchProperty;
48
+ };
49
+ logger: {
50
+ log: {
51
+ debug: (message: string, ...args: any[]) => void;
52
+ info: (message: string, ...args: any[]) => void;
53
+ warn: (message: string, ...args: any[]) => void;
54
+ error: (message: string, ...args: any[]) => void;
55
+ setLevel: (level: "info" | "debug" | "warn" | "error") => void;
56
+ };
57
+ };
58
+ mountDirectWidget: {
59
+ setDirectMountWorkflow: typeof setDirectMountWorkflow;
60
+ warmDirectModule: typeof warmDirectModule;
61
+ };
62
+ publicEmbedLookup: {
63
+ publicEmbedApiOrigins: typeof publicEmbedApiOrigins;
64
+ resolvePublishedEmbed: typeof resolvePublishedEmbed;
65
+ };
66
+ publishedHostBridge: {
67
+ dispatchPublishedHostError: typeof dispatchPublishedHostError;
68
+ getPublishedHostBridge: typeof getPublishedHostBridge;
69
+ };
70
+ publishedHostDisplay: {
71
+ OVERLAY_HOST_ATTRIBUTE: string;
72
+ };
73
+ workflowEmbedRegistry: {
74
+ registerWorkflowEmbed: typeof registerWorkflowEmbed;
75
+ };
76
+ workflowPageEvents: {
77
+ PageEventQueue: typeof PageEventQueue;
78
+ readPageEvent: typeof readPageEvent;
79
+ WORKFLOW_EVENT_TYPE: string;
80
+ WORKFLOW_STEP_EVENT_TYPE: string;
81
+ };
82
+ };
83
+ /** The services as the workflow code finds them. */
84
+ export type WorkflowSharedServices = ReturnType<typeof createWorkflowSharedServices>;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Where a visitor is in a workflow, kept in the visitor's own browser (localStorage, or memory for a page whose
3
+ * browser refuses storage).
4
+ *
5
+ * Only ids and times are kept: the block and composition the visitor is on, the version of the workflow they started
6
+ * on, when they started and when they reached the block. Never a value a visitor typed, never who they are.
7
+ *
8
+ * The version is what lets a visitor finish on the workflow they started on when a newer one is published in the
9
+ * meantime. After 30 days that no longer holds: the position is forgotten and the visitor is treated as a new one.
10
+ */
11
+ /** How long a visitor finishes on the version they started on. */
12
+ export declare const POSITION_MAX_AGE_MILLISECONDS: number;
13
+ export interface StoredPosition {
14
+ /** The published version the visitor started on (and finishes on). */
15
+ versionId: string;
16
+ /** The composition block the visitor is on. */
17
+ nodeId: string;
18
+ /** The composition that block shows, so the first paint of a returning visitor needs no graph. */
19
+ compositionId: string;
20
+ /** When the visitor started on this version (milliseconds since the epoch). */
21
+ startedAt: number;
22
+ /** When the visitor reached this block, which is what a wait in a Scheduled trigger counts from. */
23
+ reachedAt: number;
24
+ }
25
+ /** The key one workflow's position is kept under. */
26
+ export declare function positionStorageKey(workflowId: string): string;
27
+ /** Reads what a visitor's browser kept for a workflow; null for none, for one that ran out, and for anything unreadable. */
28
+ export declare function readStoredPosition(workflowId: string, nowMilliseconds?: number): StoredPosition | null;
29
+ /** Keeps where a visitor is. A browser that refuses storage still remembers it for as long as the page lives. */
30
+ export declare function writeStoredPosition(workflowId: string, position: StoredPosition): void;
31
+ /** Forgets where a visitor is (they start again as a new visitor). */
32
+ export declare function clearStoredPosition(workflowId: string): void;
@@ -0,0 +1,41 @@
1
+ /**
2
+ * The rules of the autoscale a workflow embed always has.
3
+ *
4
+ * A workflow swaps one composition for the next in the same place, and the next one is usually a different height.
5
+ * So the embed follows the height of what is shown, whatever `autoscale` or a fixed height on the tag says. The
6
+ * numbers are the ones the other embeds' autoscale reads (`autoscale-min-height`, `-max-height`, `-debounce`,
7
+ * `-threshold`, `-animate`, `-animation-duration`) and have the same defaults.
8
+ *
9
+ * Only decisions live here (which numbers, what a height is held to, whether a change is worth following). Putting a
10
+ * height on the page is the viewport's job (workflow-stage.ts).
11
+ */
12
+ export interface AutoscaleSettings {
13
+ /** The smallest the embed gets, in pixels. */
14
+ minHeight: number;
15
+ /** The largest the embed gets, in pixels. */
16
+ maxHeight: number;
17
+ /** How long a height has to hold still before the embed follows it, in milliseconds. */
18
+ debounceDelay: number;
19
+ /** The smallest change in height worth following, in pixels. */
20
+ threshold: number;
21
+ /** Whether a change in height is animated. */
22
+ animate: boolean;
23
+ /** How long the animation lasts, in milliseconds. */
24
+ animationDuration: number;
25
+ }
26
+ export declare const AUTOSCALE_DEFAULTS: Readonly<AutoscaleSettings>;
27
+ /**
28
+ * The autoscale settings of a workflow embed, read from its tag. `autoscale="false"` and a fixed height are not
29
+ * read: a workflow embed follows the content.
30
+ */
31
+ export declare function readAutoscaleSettings(host: Element, options?: {
32
+ prefersReducedMotion?: boolean;
33
+ }): AutoscaleSettings;
34
+ /**
35
+ * A height held between the embed's minimum and maximum, and rounded up to a whole pixel (a half pixel less would cut
36
+ * the last line). `capHeight` is a limit that sits on top of the embed's own, such as the largest height an overlay
37
+ * has on the visitor's screen; when it is smaller than the minimum, the cap decides.
38
+ */
39
+ export declare function clampHeight(rawHeight: number, settings: Pick<AutoscaleSettings, "minHeight" | "maxHeight">, capHeight?: number | null): number;
40
+ /** Is a new height different enough from the one shown to be worth following? The first height always is. */
41
+ export declare function shouldApplyHeight(currentHeight: number | null, nextHeight: number, threshold: number): boolean;
@@ -0,0 +1,65 @@
1
+ /**
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`).
4
+ *
5
+ * Counts are ids and numbers. No visitor, no value a visitor typed and no address is ever in a report; the gateway keeps
6
+ * the same and nothing more. The report carries the token the gateway signed for exactly this workflow and version when
7
+ * it handed out the graph, so a page that never read the workflow cannot raise its numbers.
8
+ *
9
+ * Counts are small and lossy by design: they wait a moment so that what happens together goes in one report, they are
10
+ * sent once and never retried, and a report the gateway refuses or cannot take is simply dropped. A workflow never
11
+ * waits for its numbers and never shows a visitor a thing about them.
12
+ */
13
+ /** How long a count waits for company before it is reported. */
14
+ export declare const FLUSH_DELAY_MILLISECONDS = 2000;
15
+ /**
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.
18
+ */
19
+ export declare const MAX_EVENTS_PER_REPORT = 100;
20
+ export type CountKind = "n" | "e" | "f";
21
+ export interface WorkflowCountsOptions {
22
+ workflowId: string;
23
+ /** The published version the visitor is on. Counts belong to it. */
24
+ versionId: string;
25
+ /** What the gateway signed for this version, or null when it could not (nothing is reported then). */
26
+ token: string | null;
27
+ /** The host that served the workflow; the report goes to the same one. */
28
+ apiOrigin: string;
29
+ /** Whether the embed is still on the page. A report is not worth sending for one that is gone. */
30
+ isActive: () => boolean;
31
+ }
32
+ export declare class WorkflowCounts {
33
+ private readonly options;
34
+ private pending;
35
+ /** The last event of each thing counted, so the same thing counted again is added to it. */
36
+ private lastEventOf;
37
+ private flushTimer;
38
+ private stopped;
39
+ private listening;
40
+ constructor(options: WorkflowCountsOptions);
41
+ /** Whether counting has ended for good (the gateway refused the token, or the embed was disposed). */
42
+ isStopped(): boolean;
43
+ /**
44
+ * Starts reporting what is waiting when the page is hidden or closed, which is the last moment a page can still
45
+ * send anything. Safe to call more than once.
46
+ */
47
+ 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;
50
+ /** Reports what is waiting by a beacon, which the browser finishes even when the page is gone. */
51
+ flushBeforeLeaving(): void;
52
+ /** Ends counting: whatever was waiting is forgotten and nothing is sent again. */
53
+ dispose(): void;
54
+ private readonly onPageHide;
55
+ private readonly onVisibilityChange;
56
+ /** Takes the next report's worth off the waiting events. */
57
+ private takeBatch;
58
+ private forgetPending;
59
+ private flush;
60
+ private reportAddress;
61
+ /** The report as text: plain text keeps it a "simple" cross-origin request, which needs no permission round trip. */
62
+ private reportBody;
63
+ private sendWithBeacon;
64
+ private sendWithRequest;
65
+ }
@@ -0,0 +1,71 @@
1
+ /**
2
+ * The runtime of one `<widgetic workflow-id composition-id>` tag: what turns a published workflow into a visitor moving
3
+ * from one composition to the next, in place, without the page reloading.
4
+ *
5
+ * How it goes, in the order it happens:
6
+ *
7
+ * 1. The composition the tag names is shown at once (the visitor's own, if they are coming back), so a workflow never
8
+ * makes a page wait. While that is loading, the workflow is read from the gateway (the live version, or the one a
9
+ * returning visitor started on).
10
+ * 2. When both are in, the workflow starts. A workflow that is paused, gone or does not contain the tag's composition
11
+ * leaves a plain embed of the tag's composition. A running one follows heights from now on, starts listening for what
12
+ * its triggers wait for, tells the widget what to report and starts the clocks of its Scheduled triggers.
13
+ * 3. Each thing that happens (a saved entry, an action in the widget, an event of the page, a wait that is over) goes to
14
+ * the engine, which says whether the visitor moves. If so, the next composition is built beside the one on screen
15
+ * and takes its place when it is ready. If it cannot be shown, the visitor stays where they are, the page and the
16
+ * counts are told, and one more try is made half a minute later.
17
+ *
18
+ * The engine decides, the viewport shows (workflow-stage.ts), and this file connects them to the visitor's browser: where
19
+ * the visitor is kept, what is counted, what the widgets are told, when the clocks go off. Everything it needs from outside
20
+ * is in `WorkflowHostServices`, so every step of the above can be walked through in a test without a gateway or a widget.
21
+ *
22
+ * A workflow is never a reason for a page to show nothing. Whatever goes wrong here ends as a plain embed of the tag's
23
+ * composition (see `startWorkflowEmbed`'s return value and `becomePlain`), and everything is logged once, at debug level.
24
+ */
25
+ import { type WorkflowWatch } from "../utils/host-workflow-watch";
26
+ import { WorkflowCounts, type WorkflowCountsOptions } from "./workflow-counts";
27
+ import { type WorkflowLookup, type WorkflowLookupOptions } from "./workflow-lookup";
28
+ import { type ViewportServices } from "./workflow-stage";
29
+ /** How long after a failed step the visitor is moved on again, if they are still where they were. Once. */
30
+ export declare const RETRY_AFTER_FAILED_STEP_MILLISECONDS = 30000;
31
+ /** What the runtime needs of the counts. */
32
+ type CountsPort = Pick<WorkflowCounts, "start" | "count" | "flushBeforeLeaving" | "dispose">;
33
+ /** What a test may steer about the viewport. */
34
+ export interface ViewportTuning {
35
+ createHeightObserver?: ViewportServices["createHeightObserver"];
36
+ measureStageHeight?: ViewportServices["measureStageHeight"];
37
+ readyTimeoutMilliseconds?: number;
38
+ prefersReducedMotion?: () => boolean;
39
+ }
40
+ /** Everything the runtime reaches for outside itself. The defaults are the real ones. */
41
+ export interface WorkflowHostServices {
42
+ fetchWorkflow: (workflowId: string, options?: WorkflowLookupOptions) => Promise<WorkflowLookup>;
43
+ createCounts: (options: WorkflowCountsOptions) => CountsPort;
44
+ /** Tells the widget in a stage what to report: a widget in a frame by message, a widget in the page by property. */
45
+ deliverWatch: (stage: HTMLElement, compositionId: string, watch: WorkflowWatch) => void;
46
+ /** Gets a composition ready (its lookup, its module) so that showing it takes no time. */
47
+ prefetchComposition: (compositionId: string) => void;
48
+ /** Runs `task` when the page has nothing better to do. Returns what takes it back. */
49
+ whenIdle: (task: () => void) => () => void;
50
+ viewport: ViewportTuning;
51
+ }
52
+ export interface StartWorkflowEmbedOptions {
53
+ /** Gives a stage its widget: the SDK's own hydration of a `<widgetic composition-id>` tag. */
54
+ hydrate: (stage: HTMLElement) => void;
55
+ /** Does for the tag what the SDK does when a plain embed is mounted. */
56
+ markMounted: (host: HTMLElement) => void;
57
+ /** A width every composition takes (an overlay that spans the screen). */
58
+ width?: string;
59
+ services?: Partial<WorkflowHostServices>;
60
+ }
61
+ export interface WorkflowEmbedController {
62
+ /** Ends the workflow: timers, listeners, counts and the compositions it built. Safe to call more than once. */
63
+ stop: () => void;
64
+ }
65
+ /**
66
+ * Runs the workflow of a `<widgetic workflow-id composition-id>` tag. Returns null, having done nothing to the page, when
67
+ * the tag cannot run one (the id cannot be a workflow's, no composition is named, or something fails right at the start):
68
+ * the caller then mounts the tag as a plain embed.
69
+ */
70
+ export declare function startWorkflowEmbed(host: HTMLElement, options: StartWorkflowEmbedOptions): WorkflowEmbedController | null;
71
+ export {};
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Reading a workflow from the gateway's public door.
3
+ *
4
+ * GET {api}/embed/workflows/{id} the live version (or "paused")
5
+ * GET {api}/embed/workflows/{id}/versions/{versionId} one published version, for a visitor who is finishing it
6
+ *
7
+ * The door is at the root of the API host (not under /v1), open to every website and read with a plain cross-origin
8
+ * GET: no cookies, no headers, nothing of the page is sent. The answer may be cached by the browser for a few seconds,
9
+ * which is how a publish or a pause reaches visitors within moments.
10
+ *
11
+ * Everything that is not a usable live or paused workflow ends as "unavailable", and the caller then behaves as a plain
12
+ * embed of its `composition-id`. A workflow can never be a reason for a page to show nothing.
13
+ */
14
+ import { type WorkflowGraph } from "@widgetic/workflows-engine";
15
+ /** What a visitor's browser reads of a live workflow. */
16
+ export interface PublicWorkflow {
17
+ workflowId: string;
18
+ /** The published version this answer is for. A visitor who starts on it finishes on it. */
19
+ versionId: string;
20
+ versionNumber?: number;
21
+ publishedAt?: string;
22
+ /** The composition a new visitor starts on, so the page can show it while the graph is still being read. */
23
+ startCompositionId?: string;
24
+ /** The zone date and time triggers are read in. */
25
+ timezone: string;
26
+ /** In the runtime form: no positions, no editor notes. Checked by the engine's parser. */
27
+ graph: WorkflowGraph;
28
+ /** What lets the page report counts for this version (absent: the page reports nothing). */
29
+ eventToken?: string;
30
+ }
31
+ export type WorkflowLookup = {
32
+ status: "live";
33
+ workflow: PublicWorkflow;
34
+ origin: string;
35
+ } | {
36
+ status: "paused";
37
+ } | {
38
+ status: "unavailable";
39
+ reason: "not_found" | "unreachable" | "unreadable";
40
+ };
41
+ export interface WorkflowLookupOptions {
42
+ /** Read this version instead of the live one. */
43
+ versionId?: string;
44
+ /** The API hosts to ask, in order. By default the ones every public lookup asks. */
45
+ origins?: string[];
46
+ }
47
+ /** Could this be the id of a workflow? (A `workflow-id` that cannot be one is never put in an address.) */
48
+ export declare function isUsableWorkflowId(workflowId: string): boolean;
49
+ /**
50
+ * Reads the live workflow (or one version of it) from the first host that knows it. Always resolves: whatever goes
51
+ * wrong is an "unavailable" answer, and the embed behaves as a plain embed.
52
+ */
53
+ export declare function fetchPublicWorkflow(workflowId: string, options?: WorkflowLookupOptions): Promise<WorkflowLookup>;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * What a visitor does in the composition on screen, turned into the signals the engine decides on.
3
+ *
4
+ * A stage tells the workflow two kinds of thing:
5
+ *
6
+ * - an entry was saved (Input added): the widget reports `widgetic:submitted` with the table, the entry and the
7
+ * values of the columns a published condition reads. A widget in a frame reports it through the host bridge; a
8
+ * widget mounted in the page dispatches the same event on its mount target. Either way it reaches the stage.
9
+ * - an action a trigger waits for (Action in the widget): a widget in a frame reports `widgetic:goal` with the id of
10
+ * the action; for a widget mounted in the page the SDK sees the click, the submit and the play itself, inside the
11
+ * shadow root, as it does for an A/B test.
12
+ *
13
+ * Only what the watch names is passed on: a table nobody waits for, a column nobody reads and an action nobody waits
14
+ * for are dropped here, so they never reach the engine, the counts or the page.
15
+ */
16
+ import type { FieldValue, Signal, WatchList } from "@widgetic/workflows-engine";
17
+ type EntryValue = Exclude<FieldValue, null>;
18
+ /** The values of an entry that a published condition reads: text of up to 200 characters, finite numbers, yes/no. */
19
+ export declare function sanitizeEntryValues(rawValues: unknown, allowedColumns: ReadonlySet<string>): Record<string, EntryValue>;
20
+ export interface StageSignalsOptions {
21
+ /** The stage element the composition is shown in. */
22
+ stage: HTMLElement;
23
+ /** What the composition on this stage needs reported. */
24
+ watch: WatchList;
25
+ /** Handed the signals one thing a visitor did makes, in the order of the watch (the first that moves the visitor wins). */
26
+ emit: (signals: Signal[]) => void;
27
+ }
28
+ export interface StageSignals {
29
+ /** Stops listening. Nothing is reported afterwards. */
30
+ stop: () => void;
31
+ }
32
+ /** Starts listening for what a visitor does on a stage. */
33
+ export declare function attachStageSignals({ stage, watch, emit, }: StageSignalsOptions): StageSignals;
34
+ export {};
@@ -0,0 +1,154 @@
1
+ /**
2
+ * The place a workflow shows its compositions in.
3
+ *
4
+ * A `<widgetic workflow-id>` tag gets one viewport, which holds one stage for the composition on screen. A stage is an
5
+ * ordinary `<widgetic composition-id>` element that the SDK hydrates like any other, so lookups, refusals, errors and
6
+ * the events a widget reports all work the way they do for a plain embed, and every event bubbles up to the tag.
7
+ *
8
+ * To move on to the next composition the viewport builds it beside the one on screen, out of sight. The one on screen
9
+ * is never touched until the next is ready, so a visitor never sees a blank, and the page never reloads. Then the new
10
+ * stage takes the place of the old one and the viewport follows the new height, animated.
11
+ *
12
+ * Until the workflow is known to exist the viewport is plain: it looks, to the page, exactly as the embed would without
13
+ * it. Only when it is told to follow heights does it clip to the height of what is shown (`enableAutoscale`), and it
14
+ * lets go again if the workflow turns out to be paused or gone (`releaseAutoscale`).
15
+ *
16
+ * What to show next, and when, is decided elsewhere (workflow-host.ts). This file only builds and swaps stages and
17
+ * keeps the height right. The decisions about heights are in workflow-autoscale.ts.
18
+ */
19
+ /** Marks the viewport the SDK puts on a tag. */
20
+ export declare const VIEWPORT_ATTRIBUTE = "data-widgetic-workflow-viewport";
21
+ /** Marks a stage: a composition built for a workflow. */
22
+ export declare const STAGE_ATTRIBUTE = "data-widgetic-workflow-stage";
23
+ /** Tells the viewport a stage has this height now. */
24
+ export type HeightReport = (entries: Array<{
25
+ target: Element;
26
+ height: number;
27
+ }>) => void;
28
+ /** Whatever tells the viewport that the height of a stage changed (the browser's ResizeObserver). */
29
+ export interface HeightObserver {
30
+ observe(target: Element): void;
31
+ unobserve(target: Element): void;
32
+ disconnect(): void;
33
+ }
34
+ export interface StageDescription {
35
+ compositionId: string;
36
+ /** The first stage the viewport built. */
37
+ isFirst: boolean;
38
+ /** Whether it shows the composition the tag names, and so gets what the page wrote in the tag for it. */
39
+ carriesPageContent: boolean;
40
+ }
41
+ export interface ViewportServices {
42
+ /** Gives a stage its widget (in the SDK: the same hydration a plain tag gets). */
43
+ hydrate: (stage: HTMLElement) => void;
44
+ /** Starts watching heights. Returns null when the browser cannot (heights are then taken when a stage is ready). */
45
+ createHeightObserver?: (report: HeightReport) => HeightObserver | null;
46
+ /** The height a stage has now, in pixels. */
47
+ measureStageHeight?: (stage: HTMLElement) => number;
48
+ /** A stage was built and is about to be added to the page, before anything is loaded into it. */
49
+ onStageCreated?: (stage: HTMLElement, description: StageDescription) => void;
50
+ /** A stage was taken off the page (replaced, failed, or the viewport went). */
51
+ onStageRemoved?: (stage: HTMLElement) => void;
52
+ /** How long the next composition is given to appear. */
53
+ readyTimeoutMilliseconds?: number;
54
+ }
55
+ export interface WorkflowViewportOptions {
56
+ /** The `<widgetic workflow-id>` tag. */
57
+ host: HTMLElement;
58
+ services: ViewportServices;
59
+ /** Whether the visitor asked their device for less motion. By default read from the browser. */
60
+ prefersReducedMotion?: () => boolean;
61
+ /** A width every stage takes whatever the tag says (an overlay that spans the whole screen). */
62
+ widthOverride?: string;
63
+ }
64
+ export type StageReadiness = {
65
+ status: "ready";
66
+ } | {
67
+ status: "failed";
68
+ reason: "error" | "timeout" | "stopped";
69
+ code?: string;
70
+ };
71
+ export type SwapOutcome = {
72
+ status: "shown";
73
+ stage: HTMLElement;
74
+ } | {
75
+ status: "failed";
76
+ reason: "error" | "timeout" | "busy" | "stopped";
77
+ code?: string;
78
+ };
79
+ export declare class WorkflowViewport {
80
+ private readonly host;
81
+ private readonly services;
82
+ private readonly prefersReducedMotion;
83
+ private readonly widthOverride;
84
+ private readonly viewportElement;
85
+ private current;
86
+ private incoming;
87
+ private heightObserver;
88
+ private attributeObserver;
89
+ private autoscaleOn;
90
+ private appliedHeight;
91
+ private debounceTimer;
92
+ private pendingHeight;
93
+ private destroyed;
94
+ private warnedAboutFrameWithoutHeight;
95
+ constructor(options: WorkflowViewportOptions);
96
+ /** The stage on screen, if any. */
97
+ currentStage(): HTMLElement | null;
98
+ /**
99
+ * Builds the first composition's stage and starts loading it. `ready` settles when it is shown or has failed (it is
100
+ * never given up on for being slow: a plain embed is not either).
101
+ */
102
+ showFirstStage(compositionId: string): {
103
+ stage: HTMLElement;
104
+ ready: Promise<StageReadiness>;
105
+ };
106
+ /**
107
+ * From now on the viewport is as tall as what it shows, and follows when that changes. Until then it is plain. The
108
+ * height is taken as soon as the composition on screen is ready, without an animation.
109
+ */
110
+ enableAutoscale(): void;
111
+ /** The workflow is not going to run (it is paused or gone): the viewport becomes what a plain embed looks like. */
112
+ releaseAutoscale(): void;
113
+ /**
114
+ * Builds the next composition beside the one on screen and, once it is ready, takes the place of it. If it fails or
115
+ * does not appear in time, the one on screen stays exactly as it was.
116
+ */
117
+ swapTo(compositionId: string): Promise<SwapOutcome>;
118
+ /** Takes everything this viewport put on the page away. Safe to call more than once. */
119
+ destroy(): void;
120
+ private buildStage;
121
+ /** The overrides the page wrote on the tag, and the items and JSON blocks in it: the tag composition's alone. */
122
+ private copyWhatThePageWroteForTheTagComposition;
123
+ /** What the page changes on the tag while the workflow runs reaches the stages. */
124
+ private observeMirroredAttributes;
125
+ private mirrorAttributesToStages;
126
+ /**
127
+ * Settles when the stage's widget is up (it says so, or its frame has loaded) or has failed (it says so, or the time
128
+ * allowed ran out). A `null` time is no limit.
129
+ */
130
+ private waitUntilShown;
131
+ private removeStage;
132
+ private noteFrameWithoutHeight;
133
+ /** Out of sight, in the place the stage will take: it loads and lays out but cannot be seen or used. */
134
+ private hideBeside;
135
+ private revealInPlace;
136
+ /** Stages lie on top of each other, so that the viewport's own height is what the page sees. */
137
+ private positionAsLayer;
138
+ private positionInFlow;
139
+ private measure;
140
+ /** Reserves what the composition took last time, so the page does not jump when the first one is shown. */
141
+ private holdRoomFor;
142
+ private settings;
143
+ /** The room an overlay has on the visitor's screen, or null for an embed that sits in the page. */
144
+ private overlayCap;
145
+ private onHeightsReported;
146
+ /**
147
+ * Gives the viewport the height of what is shown. A height that comes from a swap or from the first composition is
148
+ * taken at once; one that comes from the composition changing by itself waits until it has held still, and is only
149
+ * followed when it moved by more than the threshold.
150
+ */
151
+ private applyHeight;
152
+ private setHeight;
153
+ private clearHeightTimer;
154
+ }