@atomic.io/action-cards-web-sdk-cdn-icons 25.2.2 → 25.3.1

package/README.md

@@ -20,7 +20,7 @@ We currently do not have a boilerplate app for the Web SDK. [Contact us](mailto:
 
 The current version of the Atomic Web SDK is `25.4.1`, and is hosted on our CDN at `https://downloads.atomic.io/web-sdk/release/25.4.1/sdk.js`.
 
-he Web SDK also offers a bundle variant which does not include the font used for icons in action cards. Instead this font is fetched via CDN as required, allowing the size of your initial bundle loaded by the browser to be smaller. Both variations function identically in all other respects.
+The Web SDK also offers a bundle variant which does not include the font used for icons in action cards. Instead this font is fetched via CDN as required, allowing the size of your initial bundle loaded by the browser to be smaller. Both variations function identically in all other respects.
 This variant is hosted on our CDN at `https://downloads.atomic.io/web-sdk/release/25.4.1/sdk-cdn-icons.js`.
 
 To integrate it, add the script for your chosen variant as a source to your web page:
@@ -158,7 +158,7 @@ const instance = AtomicSDK.launch({...})
 
 ## Displaying a stream container
 
-This section applies to all types of container. Containers can be created using the `launch` method (launcher view) , the `embed` method (standalone vertical and horizontal containers), or the `singleCard` method (single card view).
+This section applies to all types of container. Containers can be created using the `launch` method (launcher view) , the `embed` method (standalone vertical and horizontal containers), the `singleCard` method (single card view), or the `modalStreamContainer` method (modal container).
 Specifics and code examples for each type of container are explained in more detail in their dedicated sections below.
 
 Before displaying a stream container, you must initialize the SDK by calling the `initialise` method:
@@ -181,7 +181,7 @@ Some configuration options are common for all types of container, other options
 
 A selection of UI elements can be customized within stream containers (this customization does **not apply to single card views**, with the exception of `toastConfig`). These are configured using the `enabledUiElements` property on a stream container configuration object:
 
-- `cardListToast` - defaults to `true`. Set to `false` to turn off toast messages on the card list.
+- `cardListToast` - defaults to `true`. Set to `false` to turn off toast messages.
 - `customToastContainer` - defaults to `false`. Set to `true` to use an [alternative toast message presentation](https://documentation.atomic.io/sdks/web#custom-toast-message-positioning) for standalone or launcher stream containers which allows you to reposition the toast message.
 - `toastConfig` - an optional configuration object to customize the toast messages displayed by the SDK.
   - `timeout`: optionally supply a number that sets how long the toast message should be displayed for in milliseconds.
@@ -235,6 +235,8 @@ AtomicSDK.launch({
 
 #### Functionality
 
+##### Runtime variables
+
 - `onRuntimeVariablesRequested`: an optional property that can be used on the configuration object to allow your app to resolve runtime variables. If this callback is not implemented, runtime variables will fall back to their default values, as defined in the Atomic Workbench.
 - `runtimeVariableResolutionTimeout` defaults to 5 seconds (5000 ms) if not provided.
 
@@ -318,7 +320,7 @@ AtomicSDK.launch({
 
 #### Displaying a custom header
 
-The Web SDK supports displaying a custom header above your card feed for stream containers created using the `launch` or `embed` methods. It has no effect for `singleCard` stream containers.
+The Web SDK supports displaying a custom header above your card feed for stream containers created using the `launch` or `embed` methods. It has no effect for `singleCard` or `modalStreamContainer` containers.
 
 The custom header is supplied as an HTML string to the `customContainerHeader` property of the [customized UI elements](https://documentation.atomic.io/sdks/web#style-and-presentation). Styles should be applied inline to the HTML elements. Do not attempt to reference classes or other styling from your host application stylesheets because these will not be applied.
 
@@ -343,21 +345,23 @@ You can enforce a minimum height for the cards displayed in your stream containe
 
 ```js
 AtomicSDK.launch({
+    streamContainerId: "1234",
     ...
-    features: {
-        ...
-        cardMinimumHeight: 250 // Replace 250 with your desired minimum height
-    }
+    cardMinimumHeight: 250 // Replace 250 with your desired minimum height
 });
 ```
 
 The minimum height is specified in pixels.
 
+#### Card maximum width
+
+You can enforce a maximum width for cards displayed in the modal stream container variant. See [displaying a modal stream container](https://documentation.atomic.io/sdks/web#modal-stream-container) for more information.
+
 #### Single card container toast messages
 
-Toast messages will now be displayed for the single card stream container. The toast messages are enabled by default, as they are for the other stream container variants. The single card toast message can be configured (or disabled) in the same way as they can for the other stream container variants, see the [style and presentation](https://documentation.atomic.io/sdks/web#style-and-presentation) section of the Web SDK for details on how to do this.
+The single card and modal container toast message can be configured (or disabled) in the same way as they can for the other stream container variants, see the [style and presentation](https://documentation.atomic.io/sdks/web#style-and-presentation) section of the Web SDK for details on how to do this.
 
-The default position of single card toast notifications is in the centre at the bottom of the viewport and with a maximum width of 500px. The SDK exposes a class (`toast-container`) on the iframe containing the toast messages which can be used to apply your own styling should you wish to do so. See the CSS code snippet below for an example of how to reposition single card toasts to the bottom right of the viewport and with a smaller width, if your embed element id was `host-embed-element`.
+The default position of these toast notifications is in the centre at the bottom of the viewport and with a maximum width of 500px. The SDK exposes a class (`toast-container`) on the iframe containing the toast messages which can be used to apply your own styling should you wish to do so. See the CSS code snippet below for an example of how to reposition the toasts to the bottom right of the viewport and with a smaller width, if your embed element id was `host-embed-element`.
 
 ```css
 #host-embed-element iframe.toast-container {
@@ -370,8 +374,6 @@ The default position of single card toast notifications is in the centre at the
 
 #### Reposition launcher or standalone (vertical & horizontal) stream container toast messages
 
-_(introduced in 23.4.2)_
-
 You have the ability customize the positioning of toast messages displayed by the standalone or launcher stream container variants if you wish. To do so set the `customToastContainer` option to true [style and presentation](https://documentation.atomic.io/sdks/web#style-and-presentation)
 
 Once you have done so the toast position will default to the centre at the bottom of the viewport and with a maximum width of 500px, the same as for [single card toasts](https://documentation.atomic.io/sdks/web#single-card-toasts). In the same manner as for single card toasts you can use the `toast-container` class to reposition the iframe containing the toast messages.
@@ -424,7 +426,7 @@ When creating a stream container in the launcher mode you can supply an optional
         ...
         onLauncherToggled: isOpen => {
           if (isOpen) {
-            console.log('the launcher is has been opened')
+            console.log('the launcher has been opened')
           } else {
             console.log('the launcher has been closed')
           }
@@ -533,15 +535,13 @@ When creating a stream container with the `embed` method, pass a configuration o
 AtomicSDK.embed({
   streamContainerId: "1234",
   ...
-  features: {
-    horizontalContainerConfig: {
-      enabled: true,
-      cardWidth: 400,
-      emptyStyle: "standard",
-      headerAlignment: "center",
-      scrollMode: "snap",
-      lastCardAlignment: "left"
-    }
+  horizontalContainerConfig: {
+    enabled: true,
+    cardWidth: 400,
+    emptyStyle: "standard",
+    headerAlignment: "center",
+    scrollMode: "snap",
+    lastCardAlignment: "left"
   }
 })
 ```
@@ -569,9 +569,88 @@ This object allows you to configure the horizontal stream container via the foll
   - `left`: Default value. The last card is aligned to the left of the container.
   - `center`: The last card is aligned in the middle of the container.
 
-## API-driven card containers
+## Displaying a modal stream container
+
+The modal stream container variant presents cards in a fullscreen takeover. It remains hidden until cards are delivered, at which point they are displayed one at a time in a modal over the host app’s content.
+
+The modal cannot be manually dismissed. Once all cards in the container have been actioned (e.g. submitted, dismissed, or snoozed), the container is automatically hidden again.
+
+The following illustrates initializing a modal stream container with example configuration options:
+
+```html
+<html>
+  ...
+  <body>
+    <!--Installation-->
+    <script src="https://downloads.atomic.io/web-sdk/release/25.4.1/sdk.js"></script>
+
+    <script>
+      AtomicSDK.initialise('<apiHost>', '<apiKey>', '<environmentId>')
+      AtomicSDK.setSessionDelegate(() => {
+        return Promise.resolve('<authToken>')
+      })
+
+      AtomicSDK.modalStreamContainer({
+        streamContainerId: '1234',
+        cardMaximumWidth: 400, // a pixel value
+        cardHorizontalAlignment: 'center',
+        modalContainerPositioning: 'center',
+        modalContainerVerticalPadding: 50, // a pixel value
+        onModalStreamToggled: isOpen => {
+          if (isOpen) {
+            console.log('the modal has been opened')
+          } else {
+            console.log('the modal has been closed')
+          }
+        }
+      })
+    </script>
+  </body>
+</html>
+```
+
+### Modal stream container behavior
+
+- Only one modal stream container can be present at a time. Attempts to initialize more than one modal stream container will be ignored.
+- The fullscreen container is displayed automatically when cards are available in the assigned stream container.
+- Only the first card is displayed at any given time, following the same rules as the single card container.
+- The container is automatically hidden when all cards have been actioned or cleared.
+- If log out is called while the container is visible, it closes immediately.
+- The container becomes scrollable when the card content exceeds the viewport height.
+- Clicking the background does nothing - dismissal can only occur through normal card actions.
+- Card subviews are rendered in place of the card content when navigated to.
+
+### Theming and layout
+
+Alignment properties of the modal stream container are controlled via the `modalContainerPositioning` & `cardHorizontalAlignment` configuration properties.
+
+`modalContainerPositioning` controls vertical alignment and can be either `top`, `center` or `bottom`. When configured for 'top' or 'bottom' the `modalContainerVerticalPadding` configuration property (a number value in pixels)
+will dictate whether any padding should be applied between the card and the top/bottom edge of the viewport. If `modalContainerVerticalPadding` is omitted, vertical spacing is determined by the stream container padding defined in the container theme.
+Horizontal padding is always controlled by the container theme.
+
+`cardHorizontalAlignment` controls the horizontal alignment and can be either `leading`, `center` or `trailing`.
+
+The background applied behind the card within the modal stream container can be configured via the [stream container theme](https://documentation.atomic.io/guide/configuration/themes#modal-container). If no background color configuration is applied, the modal background defaults to `rgba(0, 0, 0, 0.5)`.
 
-_(introduced in 23.4.0)_
+### Responding to the modal opening or closing
+
+When creating the modal stream container you can supply an optional callback that will be invoked whenever the stream container is opened or closed. To use this callback set it on the `onModalStreamToggled` property of the configuration object supplied to the `AtomicSDK.modalStreamContainer(config)` method. The function you provide is called with a single boolean argument indicating whether the modal has just been opened (true) or closed (false). The code sample below shows how to set this callback.
+
+```js
+      AtomicSDK.modalStreamContainer({
+        streamContainerId: '1234',
+        ...
+        onModalStreamToggled: isOpen => {
+          if (isOpen) {
+            console.log('the modal has been opened')
+          } else {
+            console.log('the modal has been closed')
+          }
+        }
+      })
+```
+
+## API-driven card containers
 
 The SDK provides the ability to create an "API-driven" card container that can be used for observing a stream container without rendering any UI. This is done using the SDK method `AtomicSDK.observableStreamContainer` which accepts a configuration object that has a subset of the properties accepted by the other stream container variants:
 
@@ -681,8 +760,6 @@ const observableContainer = AtomicSDK.observeStreamContainer({
 
 ## API-driven card actions
 
-_(introduced in 23.4.0)_
-
 The SDK provides the ability to execute card actions through pure SDK API. The currently supported actions are: dismiss, submit, and snooze. To execute these card actions, call the `AtomicSDK.onCardAction` method with the target stream container and card instance ID then call the appropriate card action method from the object that is returned:
 
 ### Dismissing a card
@@ -723,7 +800,7 @@ AtomicSDK.onCardAction('stream-container-id', 'card-id').snooze(
 
 ### Submitting a card
 
-Atomic cards now include button names when they are submitted. The name will be added to analytics to enable referencing the triggering button in an Action Flow. Resulting from this change as of version `24.2.0` the `submitButtonName` parameter must be supplied when performing an API-driven card submission.
+Atomic cards include button names when they are submitted. The name will be added to analytics to enable referencing the triggering button in an Action Flow. To facilitate this, the `submitButtonName` parameter must be supplied when performing an API-driven card submission.
 
 Call the `submit` method with `onActionSuccess`, `onActionFailed` parameters, these are functions to be invoked on success or failure of the dismiss action. Also supply a `submitButtonName` parameter which is the button "name" attribute obtained from the card data. Optionally a fourth parameter may be supplied for the response object that you wish to submit with the card. This object can only contain values with are strings, numbers or booleans.
 
@@ -786,15 +863,13 @@ instance.setOpen(true);
 
 If you have a single card, horizontal or vertical stream container that is selectively displayed to the user (such as one that is hidden inside of a notification drawer) you need to inform the SDK when this stream container is "open" and viewable by the user. This is important so that analytics events such as `stream-displayed` & `card-displayed` are correctly dispatched. Failing to do so will result in an incorrect count of seen and unread cards, as described in the [retrieving the count of cards section](https://documentation.atomic.io/sdks/web#retrieving-the-count-of-active-and-unseen-cards) of this guide.
 
-Use the `controlledContainerOpenState` feature flag in the configuration object when initialising your stream container. This ensures that your container will be initialised in the "closed" state. After initialisation of the container, it is then the responsibility of the host app to call the `setOpen` method on the stream container instance when the stream container is being displayed to or hidden from the user:
+Enable `controlledContainerOpenState` the configuration object when initializing your stream container. This ensures that your container will be initialized in the "closed" state. After initialization of the container, it is then the responsibility of the host app to call the `setOpen` method on the stream container instance when the stream container is being displayed to or hidden from the user:
 
 ```js
 const instance = AtomicSDK.embed({
   streamContainerId: "1234",
   ...
-  features: {
-    controlledContainerOpenState: true
-  }
+  controlledContainerOpenState: true
 });
 
 // when the host app has displayed the container to the user call
@@ -883,19 +958,34 @@ instance.streamFilters.addCardCreatedFilter().greaterThan('2020-02-15T00:00:00.0
 instance.streamFilters.apply()
 ```
 
+This example shows how you can filter on an attribute within the payload of a submit button on the top-level of a card. This example assumes the submit button is always the first item in the card button group.
+
+```js
+const instance = AtomicSDK.launch({
+  ...
+})
+
+instance
+  .addCardContentFilter('actions.0.attributes.values.targetPage')
+  .isIncludedIn(window.location.pathname)
+instance.streamFilters.apply()
+```
+
 ### Filter values
 
 The filter value is used to filter cards in a stream container. The table below summarises the different card attributes that can be filtered on, as well as the permitted data type for that filter and the filter operators that can be applied to it.
 
-| Card attribute             | Description                                                                        | Filter function                             | Value type                      | Permitted operators                                                                                                                              |
-| -------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Priority                   | Card priority defined in Workbench, Card -> Delivery                               | `streamFilters.addCardPriorityFilter()`     | number between 1 & 10 inclusive | `equals`<br/>`notEqualTo`<br/>`greaterThan`<br/>`greaterThanOrEqualTo`<br/>`lessThan`<br/>`lessThanOrEqualTo`<br/>`in`<br/>`notIn`<br/>`between` |
-| Card template ID           | The template ID of a card, see below for how to get it                             | `streamFilters.addCardTemplateIdFilter()`   | string                          | `equals`<br/>`notEqualTo`<br/>`in`<br/>`notIn`                                                                                                   |
-| Card template name         | The template name of a card                                                        | `streamFilters.addCardTemplateNameFilter()` | string                          | `equals`<br/>`notEqualTo`<br/>`in`<br/>`notIn`                                                                                                   |
-| Card template created date | The date time when a card template is created                                      | `streamFilters.addCardCreatedFilter()`      | ISO date string                 | `equals`<br/>`notEqualTo`<br/>`greaterThan`<br/>`greaterThanOrEqualTo`<br/>`lessThan`<br/>`lessThanOrEqualTo`                                    |
-| Custom variable            | The default value for variables defined for a card in Workbench, Card -> Variables | `streamFilters.addVariableFilter()`         | multiple                        | `equals`<br/>`notEqualTo`<br/>`greaterThan`<br/>`greaterThanOrEqualTo`<br/>`lessThan`<br/>`lessThanOrEqualTo`<br/>`in`<br/>`notIn`<br/>`between` |
-| Payload variable           | The value for variables as defined in API event payload                            | `streamFilters.addPayloadVariableFilter()`  | multiple                        | `equals`<br/>`notEqualTo`<br/>`greaterThan`<br/>`greaterThanOrEqualTo`<br/>`lessThan`<br/>`lessThanOrEqualTo`<br/>`in`<br/>`notIn`<br/>`between` |
-| Payload metadata           | The value for metadata as defined in API event payload                             | `streamFilters.addPayloadMetadataFilter()`  | multiple                        | `equals`<br/>`notEqualTo`<br/>`greaterThan`<br/>`greaterThanOrEqualTo`<br/>`lessThan`<br/>`lessThanOrEqualTo`<br/>`in`<br/>`notIn`<br/>`between` |
+| Card attribute             | Description                                                                        | Filter function                             | Value type                      | Permitted operators                                                                                                                                                                                                    |
+| -------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Priority                   | Card priority defined in Workbench, Card -> Delivery                               | `streamFilters.addCardPriorityFilter()`     | number between 1 & 10 inclusive | `equals`<br/>`notEqualTo`<br/>`greaterThan`<br/>`greaterThanOrEqualTo`<br/>`lessThan`<br/>`lessThanOrEqualTo`<br/>`in`<br/>`notIn`<br/>`between`                                                                       |
+| Card template ID           | The template ID of a card, see below for how to get it                             | `streamFilters.addCardTemplateIdFilter()`   | string                          | `equals`<br/>`notEqualTo`<br/>`in`<br/>`notIn`<br/>`includes`<br/>`excludes`<br/>`isIncludedIn`<br/>`isExcludedFrom`                                                                                                   |
+| Card template name         | The template name of a card                                                        | `streamFilters.addCardTemplateNameFilter()` | string                          | `equals`<br/>`notEqualTo`<br/>`in`<br/>`notIn`<br/>`includes`<br/>`excludes`<br/>`isIncludedIn`<br/>`isExcludedFrom`                                                                                                   |
+| Card template created date | The date time when a card template is created                                      | `streamFilters.addCardCreatedFilter()`      | ISO date string                 | `equals`<br/>`notEqualTo`<br/>`greaterThan`<br/>`greaterThanOrEqualTo`<br/>`lessThan`<br/>`lessThanOrEqualTo`                                                                                                          |
+| Custom variable            | The default value for variables defined for a card in Workbench, Card -> Variables | `streamFilters.addVariableFilter()`         | multiple                        | `equals`<br/>`notEqualTo`<br/>`greaterThan`<br/>`greaterThanOrEqualTo`<br/>`lessThan`<br/>`lessThanOrEqualTo`<br/>`in`<br/>`notIn`<br/>`between`<br/>`includes`<br/>`excludes`<br/>`isIncludedIn`<br/>`isExcludedFrom` |
+| Payload variable           | The value for variables as defined in API event payload                            | `streamFilters.addPayloadVariableFilter()`  | multiple                        | `equals`<br/>`notEqualTo`<br/>`greaterThan`<br/>`greaterThanOrEqualTo`<br/>`lessThan`<br/>`lessThanOrEqualTo`<br/>`in`<br/>`notIn`<br/>`between`<br/>`includes`<br/>`excludes`<br/>`isIncludedIn`<br/>`isExcludedFrom` |
+| Payload metadata           | The value for metadata as defined in API event payload                             | `streamFilters.addPayloadMetadataFilter()`  | multiple                        | `equals`<br/>`notEqualTo`<br/>`greaterThan`<br/>`greaterThanOrEqualTo`<br/>`lessThan`<br/>`lessThanOrEqualTo`<br/>`in`<br/>`notIn`<br/>`between`<br/>`includes`<br/>`excludes`<br/>`isIncludedIn`<br/>`isExcludedFrom` |
+| Top-level card content     | The value for content in the top-level of the card                                 | `streamFilters.addCardContentFilter()`      | multiple                        | `equals`<br/>`notEqualTo`<br/>`greaterThan`<br/>`greaterThanOrEqualTo`<br/>`lessThan`<br/>`lessThanOrEqualTo`<br/>`in`<br/>`notIn`<br/>`between`<br/>`includes`<br/>`excludes`<br/>`isIncludedIn`<br/>`isExcludedFrom` |
+| Subview card content       | The value for content in a card subview                                            | `streamFilters.addSubviewContentFilter()`   | multiple                        | `equals`<br/>`notEqualTo`<br/>`greaterThan`<br/>`greaterThanOrEqualTo`<br/>`lessThan`<br/>`lessThanOrEqualTo`<br/>`in`<br/>`notIn`<br/>`between`<br/>`includes`<br/>`excludes`<br/>`isIncludedIn`<br/>`isExcludedFrom` |
 
 **Note:** It's important to specify the right value type when referencing custom variables for filter value. There are five types of variables in the Workbench, currently four are supported: String, Number, Date and Boolean.<br />
 
@@ -939,9 +1029,6 @@ instance.streamFilters.clearFilters()
 
 ## Image linking
 
-_(introduced in 24.1.0)_
-_This is a beta feature in the Atomic Workbench_
-
 Image elements can be used to trigger a navigation action. In the Atomic Workbench you can configure the behavior of the link to trigger a subview navigation, open a URL or to send a payload to your app. For information on how to handle the image link payload see [custom action payloads on image links](https://documentation.atomic.io/sdks/web#supporting-custom-action-payloads-on-image-links)
 
 ## Custom action payloads
@@ -1013,7 +1100,7 @@ Configuration of card voting from within the workbench provides further customiz
 
 Whether enabled in the workbench, or in the SDK configuration, the default wording of card voting options can be configured. See the [custom strings](#custom-strings) section of this guide if you want to change the default wording.
 
-### Configuring card voting within the SDK
+### Configuring card voting within the SDK (deprecated)
 
 The following describes how card voting appears when configured via the SDK feature configuration:
 
@@ -1556,7 +1643,7 @@ There are two options you can customize for the focus ring color:
 
 If you use runtime variables on a card, you can optionally choose to send the resolved values of any runtime variables back to the Atomic Platform as an analytics event. This per-card analytics event - `runtime-vars-updated` - contains the values of runtime variables rendered in the card and seen by the end user. Therefore, you should not enable this feature if your runtime variables contain sensitive data that you do not wish to store on the Atomic Platform.
 
-To enable this feature, set the `features.runtimeVariableAnalytics` flag on your configuration object to `true`:
+To enable this feature, set the `features.runtimeVariableAnalytics` flag on your stream container configuration object to `true`:
 
 ```javascript
 AtomicSDK.launch({
@@ -1722,7 +1809,7 @@ AtomicSDK.updateUser(userUpdateObject)
 
 ## File Upload
 
-_This is currently a preview feature in the Workbench_
+_This is currently a beta feature in the Workbench_
 
 ### Card & feed overlay during file upload
 
@@ -1791,10 +1878,6 @@ Currently, no event is generated to indicate when a user cancels an upload. We w
 
 ## Custom icons
 
-_(introduced in 24.2.0)_
-
-_This is currently a beta feature in the Atomic Workbench._
-
 The SDK now supports the use of custom icons in card elements. When you are editing a card in the card template editor of the Workbench you will notice that for card elements that support it the [properties panel](https://documentation.atomic.io/guide/cards/creating#properties-panel-right) will show an "Include icon" option. From this location you can select an icon to use, either from the Media Library or Font Awesome.
 
 Choosing to use an icon from the Media Library you have the ability to provide an SVG format icon and an optional fallback icon to be used in case the SVG fails to load. The "Select icon" dropdown will present any SVG format assets in your media library which can be used as a custom icon. To add an icon for use you can press the "Open Media Library" button at the bottom of the dropdown.
@@ -1822,11 +1905,7 @@ If the provided SVG image fails to load due to a broken URL or network issues th
 1. The fallback FontAwesome icon is used if it is set in Atomic Workbench for this custom icon.
 2. Otherwise, a default placeholder image is displayed.
 
-## Image things
-
-_(introduced in 24.2.0)_
-
-_This is currently a beta feature in the Atomic Workbench._
+## Multiple display heights
 
 In the Atomic Workbench you can now specify the display height for banner and inline media components. The height of inline image and video elements, along with banner image and video elements, may be specified as one of four different display heights. These are;
 
@@ -1837,6 +1916,76 @@ In the Atomic Workbench you can now specify the display height for banner and in
 
 When using these new layouts be mindful that customers using older versions of the SDK will default to the "Tall" layout.
 
+## File Upload
+
+_This is currently a beta feature in the Workbench_
+
+_Uploaded images are processed and scanned during upload. AVIF, HEIC and HEIF file formats are automatically converted to JPG during this process._
+
+### Card & feed overlay during file upload
+
+The file upload process will commence when a user attempts to submit a card that has files attached. While the file upload is in progress the card (or card subview when submitting from a subview) will be replaced with an overlay to prevent user interaction while this takes place. This overlay displays a loading indicator, a message indicating what is taking place, and a button that may be used to cancel the file upload.
+
+If the card is within a launcher, vertical or horizontal stream container variant, any other cards within the feed will be covered by a scrim while the upload is in progress, to prevent user interaction with other cards in the feed and visually indicate that the upload has not finished.
+
+#### Single card & Horizontal stream container overlay
+
+The modal iframe, used to present subviews in the single card & horizontal stream containers, has an 'uploading-files' class added to the iframe element while there is a file upload in progress. This can be used to trigger any UI you may wish to display in your application while the file upload is in progress.
+
+The following code snippet is an example of how you could detect this:
+
+```js
+// An observer to observe changes in the modal subview iframe class list
+const observer = new MutationObserver(mutations => {
+  mutations.forEach(mutation => {
+    if (mutation.target.classList.contains('uploading-files')) {
+      // Uploading has commenced, modify UI as required
+    } else {
+      // Uploading has finished, modify UI as required
+    }
+  })
+})
+
+// Observe changes in the relevant modal subview, in this case one that
+// has been embedded inside of a host element with the ID "embed-container".
+observer.observe(document.querySelector('#embed-container>.modal-subview'), {
+  attributeFilter: ['class']
+})
+```
+
+### Custom strings
+
+The card overlay message & cancel button label text can be customized using the [custom strings](https://documentation.atomic.io/sdks/web#custom-strings) feature of the SDK. If you wish to change the text used you would supply a value for the `processingStateMessage` and/or the `processingStateCancelButtonTitle` for the stream container(s) that you wanted to customize this for.
+
+### Toast message
+
+If a file upload fails to successfully complete the user will be displayed a toast message indicating this and providing the option to retry. By default the text of this message will be "Couldn't upload file(s)", if you wish to customize this you may do so via the [toast config](https://documentation.atomic.io/sdks/web#style-and-presentation) configuration object for the stream container, setting a value for the `fileUploadFailed` toast message.
+
+### SDK events
+
+There are new events that are emitted during the file upload process. When a user attempts to submit a card that has files attached, the file upload process will commence and these events can be used to track its progression:
+
+- `user-file-uploads-started`, emitted once the file upload process has started.
+- `user-file-uploads-completed`, emitted once the file upload process has completed, with all files having been successfully uploaded.
+- `user-file-uploads-failed`, emitted once the file upload process has completed or been cancelled, with one or more files having failed to upload.
+
+These events can be observed using the [SDK event observer](https://documentation.atomic.io/sdks/web#sdk-event-observer). The details for the relevant files are found in the `properties` of the event object, keyed by the form field they were submitted, for example:
+
+```js
+{
+  eventName: "user-file-uploads-completed",
+  ...
+  properties: {
+    upload_fieldname: {
+      filename: "filename_in_S3_bucket.png",
+      targetBucketId: "S3_bucket_id"
+    }
+  }
+}
+```
+
+_Currently, no event is generated to indicate when a user cancels an upload. We will add a corresponding SDK event in upcoming versions._
+
 ## Cordova/Capacitor
 
 The Atomic Web SDK also supports use within Cordova and Capacitor apps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atomic.io/action-cards-web-sdk-cdn-icons",
-  "version": "25.2.2",
+  "version": "25.3.1",
   "description": "The Atomic Web SDK",
   "main": "public/sdk.js",
   "typings": "public/sdk.d.ts",
@@ -39,7 +39,7 @@
     "@babel/preset-react": "^7.9.4",
     "@babel/preset-typescript": "^7.9.0",
     "@microsoft/api-extractor": "^7.19.5",
-    "@playwright/test": "^1.38.0",
+    "@playwright/test": "^1.55.0",
     "@popa-marius/pushstate-server": "3.1.2",
     "@types/css-font-loading-module": "^0.0.13",
     "@types/jest": "^26.0.4",
@@ -55,7 +55,7 @@
     "enzyme-adapter-preact-pure": "^4.1.0",
     "focus-visible": "^5.2.0",
     "jest": "^26.0.4",
-    "playwright": "^1.38.0",
+    "playwright": "^1.55.0",
     "preact": "10.4.1",
     "prettier": "3.2.5",
     "react": "^18.2.0",
@@ -64,7 +64,7 @@
     "terser-webpack-plugin": "^5.3.10",
     "to-string-loader": "^1.2.0",
     "ts-loader": "^9.5.1",
-    "typescript": "^3.8.3",
+    "typescript": "^5.9.2",
     "url-loader": "^4.1.1",
     "webpack": "^5.90.0",
     "webpack-cli": "^5.1.4",

package/public/LICENSES.txt

@@ -1,4 +1,4 @@
-The Atomic Web SDK (25.2.2) uses the following open sources libraries:
+The Atomic Web SDK (25.3.1) uses the following open sources libraries:
 
 -----------------------