@widgetic/embed-sdk 2.1.6 → 2.1.7

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;