@widgetic/embed-sdk 2.1.5 → 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
 
@@ -125,6 +139,7 @@ A workflow shows a path of compositions in one place. When a visitor saves an en
125
139
 
126
140
  - `composition-id` is the composition a **new** visitor starts on, and it has to be one of the workflow's. A workflow that is paused, gone or cannot be read leaves a plain embed of `composition-id`, so the page never shows nothing.
127
141
  - Every composition keeps the tag's `width`, `resize`, theme, overlay, and the page's `values`, `context` and `media-resolver`. Inline `design` and `content` overrides written in the tag apply to the composition the tag names only.
142
+ - **Languages.** A composition that has translations is shown in the language of the visitor's browser, the way `<widgetic-translations>` shows it, and so is every composition the visitor moves to, not only the first. The gateway lists the copies with the workflow, so a language added later shows up without a new version. The first composition is built when that list is in (never later than two seconds; a slower answer shows the composition as it is and swaps it for its copy), and a copy that cannot be shown is replaced by the composition itself.
128
143
  - Autoscale is always on for a workflow tag and reads `autoscale-min-height`, `autoscale-max-height`, `autoscale-debounce`, `autoscale-threshold`, `autoscale-animate` and `autoscale-animation-duration` (defaults 50, 2000, 150, 5, animated, 300). `fixed-height` and `autoscale="false"` are ignored.
129
144
  - The tag fires `widgetic:workflow-step` (`{ workflowId, from, to }`) when a visitor moves on. A page tells its workflow that something happened with `sendWorkflowEvent(tag, "name", { value: 1 })`, exported by this package, or by dispatching a `widgetic:workflow-event` (`{ name, values }`) on the tag.
130
145
  - Where the visitor is stays in the visitor's own browser (`localStorage`): ids and times, never a value. A visitor finishes the version they started on, for up to 30 days.