@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.
package/README.md CHANGED
@@ -74,13 +74,27 @@ export function WidgeticEmbed({ compositionId }) {
74
74
  | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75
75
  | `composition-id` | **Required.** The id of the composition to show. |
76
76
  | `width`, `height` | The size of the frame in pixels. When they are missing the frame is 400 by 300. |
77
- | `resize` | How the frame follows its place on the page: `fixed` (the default), `fill-width`, `fill-height`, `fixed-width`, `fixed-height`, `fill` or `allow-scale-down`. |
77
+ | `resize` | How the box follows its place on the page. On a published embed: `fill-width` makes it as wide as its place, `responsive` as wide as its place up to `width`, and `fixed` (the default), `custom` or no `resize` keep the `width` by `height` box of the tag. The other names the SDK knows (`fill-height`, `fixed-width`, `fixed-height`, `fill`, `allow-scale-down`) leave a published box as it is. See "Resize Mode and breakpoint" below. |
78
78
  | `autoscale` | `on` turns automatic scaling on. Without the attribute, or with `autoscale="false"`, it is off. |
79
- | `adaptive` | An adaptive breakpoint in pixels. |
79
+ | `adaptive` | A breakpoint in pixels. The tag says `data-widgetic-mobile="true"` while the window is that wide or narrower, and sends `widgetic:adaptive` when that changes. A `responsive` tag that names none has 480. |
80
80
  | `workflow-id` | The id of a published workflow. `composition-id` is then where a new visitor starts (see "Workflows" below). |
81
81
 
82
82
  The tag has more attributes: `embed-target`, and the ones for an overlay, a pop-up and for when a widget shows (`overlay-*`, `popup-*`, `trigger-*`). They are described in the Widgetic Partner integration guide, page 8, "Embed widgets on your pages".
83
83
 
84
+ ### Resize Mode and breakpoint
85
+
86
+ The Embed Editor writes its **Resize Mode** into the embed code as `resize` and its **Responsive Breakpoint** as `adaptive`. A published embed (a tag with a `composition-id`) acts on both, whether the widget is mounted in the page or shown in a frame:
87
+
88
+ | Embed Editor | Embed code | The box |
89
+ | ------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
90
+ | Fill width | `resize="fill-width"` | As wide as the place the tag is in. |
91
+ | Responsive | `resize="responsive"` | As wide as its place, up to the `width` of the tag. Its breakpoint is 480 unless `adaptive` says so. |
92
+ | Fixed, Custom | `resize="fixed"`, `resize="custom"`, or no `resize` | The `width` by `height` of the tag, never wider than its place. Nothing changes for an older code. |
93
+
94
+ - **The height** of a `fill-width` or `responsive` box is the `height` of the tag, and with `autoscale` it is what the widget needs (`autoscale` keeps priority over the height). A tag without `autoscale`, whose `width` and `height` are both numbers, keeps the proportions of that width and height as the box gets narrower, as a picture does.
95
+ - **The breakpoint** is a whole number of pixels in `adaptive` (`adaptive="480"`), and it is the width of the window, not of the box. The tag says `data-widgetic-mobile="true"` while the window is that wide or narrower and `"false"` above it, and it sends `widgetic:adaptive` once when the embed is drawn and again every time the window crosses the breakpoint (the event bubbles and leaves the shadow root; `detail` is `{ compositionId, isMobile, breakpoint }`), so the page can switch to its mobile layout. The breakpoint does not change the box: a `fixed` tag stays fixed.
96
+ - **Left alone:** an embed whose `embed-target` is `overlay` or `mixed` (the overlay decides its own size) and the stages of a workflow (the workflow's viewport sizes them).
97
+
84
98
  ### Inline `<script type="application/json">` configuration
85
99
 
86
100
  You can also pass `design`, `content`, and `contentItems` overrides (or raw `design.json` / `content.json` meta schemas) directly inside `<widgetic>` using a standard `<script type="application/json">` child block:
@@ -111,7 +125,7 @@ A widget keeps the language and the colours its author gave it, whatever page it
111
125
 
112
126
  The few words the script draws itself on your page, the accessible names of its close buttons and of the frame, follow the page's own `lang` (`<body lang>` first, then `<html lang>`). Twelve languages are built in, the same twelve that `@widgetic/ui-sdk` ships packs for (French, German, Spanish, Brazilian Portuguese, Dutch, Danish, Swedish, simplified Chinese, Arabic, Hebrew, Persian, Urdu); any other language, and a page that does not say its own, gets English. They are provisional until a native speaker has read them.
113
127
 
114
- The element fires DOM events (bubbling, composed) that match the frame protocol: `widgetic:ready`, `widgetic:error`, `widgetic:submitted`, `widgetic:resize`, `widgetic:data`, `widgetic:interaction`, `widgetic:form-submit`; a tag with a `workflow-id` also fires `widgetic:workflow-step`. Lookup failures use `widgetic:error` with `detail.code` in lower case (`not_found`, `domain_not_allowed`, `device_restricted`, …).
128
+ The element fires DOM events (bubbling, composed) that match the frame protocol: `widgetic:ready`, `widgetic:error`, `widgetic:submitted`, `widgetic:resize`, `widgetic:data`, `widgetic:interaction`, `widgetic:form-submit`; a tag with a `workflow-id` also fires `widgetic:workflow-step`. A tag with an `adaptive` breakpoint also fires `widgetic:adaptive` (see "Resize Mode and breakpoint"). Lookup failures use `widgetic:error` with `detail.code` in lower case (`not_found`, `domain_not_allowed`, `device_restricted`, …).
115
129
 
116
130
  Markers the script writes: `data-widgetic-mounting`, `data-widgetic-mounted`, `data-device-restricted`, `data-widgetic-refused="CODE"`, `data-widgetic-context-invalid`. See `docs/host-contract.md` for the full contract.
117
131