@telia-ace/widget-conversation 1.0.23 → 1.0.26

package/README.md

@@ -2,24 +2,22 @@
 
 The Widget Conversation API provides support for reading and writing to a conversational component inside a widget.
 
-## Sandbox
+## Explore the API
 
-For demonstration purposes, we've set up a sandbox for the Widget Conversational API so that you can see it in action. Keep in mind that this is for demonstration purposes only and may not reflect best practice.
-
-> We do not recommend binding functions to the `window` object.
+You can try out and watch the Conversation API in action by clicking the button below.
+Keep in mind that this is for demonstration purposes only and may not be best practice.
+We do not recommend binding functions to the `Window` object.
 
 [![Edit elegant-jones-rnyrd](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/elegant-jones-rnyrd?fontsize=14&hidenavigation=1&theme=dark)
 
 ## Accessing the API
 
-In order to access the API you need to have a widget with a conversational component.
-
-### Creating the plugin
-
-You need to register the conversational provider in the `providers`-property in the component. To access the global instance of `ConversationPlatform`, you pass in the current `Container` to the `getInstance()` method. It will return a `Promise` that is resolved to the `ConversationPlatform` instance. In the instance, register a provider and pass in name and handler by calling the `registerProvider()` function as shown below.
+Inside a plugin, access the global instance of `ConversationPlatform` by passing in the current `Container` to the `getInstance()` method. It will return a `Promise` that is resolved to the `ConversationPlatform` instance. On the instance, register a provider and pass in a name and handler by calling the `registerProvider()` function as shown below.
 
 The handler function will be called once a conversational component for the specified provider is activated in the widget. Use the provider to interact with the conversation.
 
+##### Example
+
 ```ts
 import { ConversationPlatform } from '@telia-ace/widget-conversation';
 
@@ -32,122 +30,71 @@ const MyPlugin = async (container) => {
 };
 ```
 
-You also need to register the provider inside the widget configuration:
+## Writing to the conversation
+
+When writing content to the conversation you will first need to create an `Agent` object and then use its `print()` function. Specify the type of entry to print and pass in the content.
 
-```JSON
-   "my-conversation-component": {
-        "type": "conversation",
-        "properties": {
-            "providers": ["my-chat"],
-            // ...
-        },
-        "context": {}
-    },
-```
+### `print(content: object)`
 
-### Creating an agent in the conversation
+Returns a `ConversationEntry` message that can be used to update and/or remove the content from the conversation at a later stage.
 
-When using `createAgent` you can specify both a name and an avatar. These will then be displayed in the conversation alongside that agent's entries.
+##### Example
 
 ```ts
-const agent = conversation.createAgent({
-    name: 'Agent Smith',
-    avatar: 'https://www.site.com/avatar.jpg',
-});
-```
+const agent = conversation.createAgent();
+const entry = agent.print('Lorem ipsum');
 
-## Writing to the conversation
+entry.update({
+    // ...
+});
 
-***`print()` accepts an array, which is considered best practice when writing to the conversation. The previous way of posting an object is still currently be supported, but is considered to be deprecated.**
+entry.remove();
+```
 
-### Posting, updating and removing content
+### Messages
 
-When managing content in the conversation you'll first need to create an `Agent`-object and then use its `print()` function. There are serveral types of entries in order to accommodate different types of content.
+#### Simple text message
 
-The `print(items: ConversationMessageItem[])` function let's you return a `ConversationEntry` message that can be used to update and/or remove the content from the conversation.
+Used to render plain text without HTML-formatting.
 
-##### Example of simple text message
+##### Example
 
 ```ts
 // print user message
-conversation.user.print([['text', 'Lorem ipsum']]);
+conversation.user.print('Lorem ipsum');
 
 // print agent message
 const agent = conversation.createAgent();
-agent.print([['text', 'Lorem ipsum']]);
+agent.print('Lorem ipsum');
 ```
 
-##### Example of updating or removing content
+#### Message with list of actions
 
-```ts
-const agent = conversation.createAgent();
-const entry = agent.print([['text', 'Hello world!']]);
+Example of how to render a list with actions. Is only supported on `Agent` and as system message.
 
-entry.update([
-    // ...
-]);
-
-entry.remove();
-```
-
-### Entry with list of actions
+| Name      | Type     | Description                                                   |
+| --------- | -------- | ------------------------------------------------------------- |
+| `title`   | `string` | Title for the entry.                                          |
+| `body`    | `string` | Body content for the entry. Supports HTML.                    |
+| `actions` | `object` | Key-value-pairs representing available actions for the entry. |
 
-You can post an entry into the conversation with actions. You can specify a title, body and available actions. This is only supported for the `Agent` and will be displayed as a system message.
-
-This can be either in the form of a "ButtonList" or an "LinkList" as demostrated below.
-
-| Name      | Type     | Description                                  |
-| --------- | -------- | -------------------------------------------- |
-| `header`  | `string` | Header for the entry.                        |
-| `actions` | `array`  | Array of of available actions for the entry. |
-
-##### Example of a list of actions
+##### Example
 
 ```ts
-// example of button list
-agent.print([
-    [
-        'button-list',
-        {
-            header: 'Download invoices',
-            actions: [
-                {
-                    actionKey: 'invoice_190201',
-                    label: 'Invoice 190201',
-                },
-                {
-                    actionKey: 'invoice_190301',
-                    label: 'Invoice 190301',
-                },
-            ],
-        },
-    ],
-]);
-
-// here we use a link list instead, but with the same actions
-agent.print([
-    [
-        'link-list',
-        {
-            header: 'Download invoices',
-            actions: [
-                {
-                    actionKey: 'invoice_190201',
-                    label: 'Invoice 190201',
-                },
-                {
-                    actionKey: 'invoice_190301',
-                    label: 'Invoice 190301',
-                },
-            ],
-        },
-    ],
-]);
+agent.print({
+    title: 'Download invoices',
+    body: 'Click an invoice below to download a copy.',
+    actions: {
+        invoice_190201: 'Invoice 190201',
+        invoice_190301: 'Invoice 190301',
+        invoice_190401: 'Invoice 190401',
+    },
+});
 ```
 
-### Entry with a form
+#### Message with a form
 
-You can also post a message with a form attached. This uses the `FormBuilder`-method. This is handled by the `conversation.form` event. It is only supported for `Agent` and will be displayed as a system message.
+Example of how to render a form that can be handled by the `conversation.form` event. Is only supported on `Agent` and as system message.
 
 | Name    | Type                    | Description                                                                                                                                                                                  |
 | ------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -156,7 +103,7 @@ You can also post a message with a form attached. This uses the `FormBuilder`-me
 | `form`  | `(FormBuilder) => void` | A callback function for building the form. Refer to the [`@telia-ace/widget-forms`](https://www.npmjs.com/package/@telia-ace/widget-forms) package for more information about `FormBuilder`. |
 | `key`   | `string`                | The key used to refer to the form when validating and submitting the form.                                                                                                                   |
 
-##### Example of an entry with a form
+##### Example
 
 ```ts
 agent.print({
@@ -185,63 +132,47 @@ agent.print({
 });
 ```
 
-### Entry with a video call
-
-Use the `video-request` item type to create an entry representing an incoming video call. This entry can also have a form attached, which uses the `FormBuilder`-method and is handled by the `conversation.form` event. It is only supported for an `Agent` and will be displayed as a system message.
+### Specify a sender name and/or avatar
 
-| Name           | Type     | Description                                     |
-| -------------- | -------- | ----------------------------------------------- |
-| `header`       | `string` | Header for the entry.                           |
-| `acceptLabel`  | `string` | Label to be shown for the "accept call button"  |
-| `declineLabel` | `string` | Label to be shown for the "decline call button" |
+To create an agent with a name and avatar use the `createAgent` method on the conversation.
 
-##### Example of an entry for an incoming video call
+##### Example
 
 ```ts
-agent.print([
-    [
-        'video-request',
-        {
-            header: 'Video call',
-            accept: 'Accept',
-            decline: 'Decline',
-        },
-    ],
-]);
-```
-
-When the user presses one of these buttons to accept or decline the call, an action will be dispatched with actionKey `accept-video-call` or `decline-video-call`, depending on which button was clicked.
-
-Listening to these actions can be done as following:
+const agent = conversation.createAgent({
+    name: 'Mr. Agent',
+    avatar: 'https://www.site.com/avatar.jpg',
+});
 
-```ts
-component.actions.watch('conversation.action', (input, next) => {
-    if (input.actionKey === 'accept-video-call') {
-        // this will render an overlay over the widget,
-        // and prepare the widget for displaying the actual call
-        component.actions.dispatch('show-overlay', {});
-    } else if (input.actionKey === 'decline-video-call') {
-        // ...
-    }
-    return next(input);
+agent.print({
+    title: 'I found the following invoices associated to your account:',
+    actions: {
+        action1: 'Action 1',
+        action2: 'Action 2',
+        action3: 'Action 3',
+    },
 });
 ```
 
-Use an overlay over the conversation to render your video call. The `show-overlay`-action, as described above, accomplishes this. After the overlay is rendered and ready it will dispatch another event: `overlay-mounted`. Use the HTML element this generates to render your video call.
+### Writing system messages
+
+In order to print a system message to the conversation you invoke the `print` method on the `conversation`. The `print` method accepts the same arguments as on the `Agent`.
+
+#### Example
 
 ```ts
-component.actions.watch('overlay-mounted', (overlayElem, next) => {
-    // the overlayElem here may be used to render the ongoing call
-});
+conversation.print('Lorem ipsum');
 ```
 
-### The loading and typing indicators
+### Loading/typing indicator
 
-When you need to fetch data from external resource you should use the `loading()` function on the `ConversationProvider` to inform the user that something is about to happen. Even in cases when the response is available immediately it gives a better user experience to present a loading indicator for a short while.
+In many cases you will likely fetch data from an external resource before the content is written to the conversation. In this case you should use the `loading()` function on the `ConversationProvider` to inform the user that something is about to happen. Even in cases when the response is available immediately it gives a better user experience to present a loading indicator for a short while.
 
-When you need to make the user aware that your agent is currently typing, you should use the `typing` function on `Agent`.
+In cases where you want to notify the user that the agent is currently typing, you should use the `typing` function on `Agent`.
+
+#### Example
 
-#### Example of `loading`
+##### Loading
 
 ```ts
 const done = conversation.loading();
@@ -249,7 +180,7 @@ const done = conversation.loading();
 done(); // remove loader
 ```
 
-#### Example of `typing`
+##### Typing indicator
 
 ```ts
 const done = agent.typing();
@@ -257,34 +188,51 @@ const done = agent.typing();
 done(); // remove loader
 ```
 
-## Writing system messages
+## Reading from the conversation
 
-System message in the conversation are sent by using the `print` method on the `conversation`. The `print` method accepts the same arguments as on the `Agent`.
+The second parameter to your provider handler is a `ComponentNode` instance representing the conversational component. On it you can read the component's properties and react to action emitted by the component.
 
-#### Example
+### Actions
 
-```ts
-conversation.print([['text', 'Hello world!']]);
-```
+The following actions are emitted from the conversational component.
 
-## Reading from the conversation
+**Important**: For default actions it is important to call `next()` unless you want to completely stop the execution flow for the particular action. Not doing so will stop any succeeding handlers and may unintentionally break functionality.
+
+#### `conversation.user-typing`
+
+Is emitted when the user´s typing indicator is changed.
+
+| Name         | Type     | Description                                    |
+| ------------ | -------- | ---------------------------------------------- |
+| `textLength` | `number` | The current text length of the user's message. |
+
+#### `conversation.user-submit`
+
+Is emitted when the user submits a message.
 
-The second parameter to your provider handler is a `ComponentNode` instance representing the conversational component. From it you can read the component's properties and react to action emitted by the component.
+| Name   | Type     | Description         |
+| ------ | -------- | ------------------- |
+| `text` | `string` | The submitted text. |
 
-The following actions are emitted from the conversational component:
+#### `conversation.action`
 
-> For default actions it is necessary to call `next()` unless you want to completely stop the execution flow for the particular action. Not doing so will stop any succeeding handlers and may unintentionally break functionality.
+Is emitted when the user clicks on an action.
 
-| Action                     | Name         | Type       | Description                                               |
-| -------------------------- | ------------ | ---------- | --------------------------------------------------------- |
-| `conversation.user-typing` | `textLength` | `number`   | The current text length of the user's message.            |
-| `conversation.user-submit` | `text`       | `string`   | The submitted text.                                       |
-| `conversation.action`      | `text`       | `string`   | Key of the submitted action.                              |
-| `conversation.form`        | `data`       | `FormData` | The form data.                                            |
-| `conversation.form`        | `formKey`    | `string`   | The unique key for the form.                              |
-| `conversation.form`        | `actionKey`  | `string`   | The key of the form component responsible for the change. |
+| Name   | Type     | Description                  |
+| ------ | -------- | ---------------------------- |
+| `text` | `string` | Key of the submitted action. |
 
-If you want to subscribe to any of the `conversation.form`-actions you have access to the `ComponentNodeController`. Example below:
+#### `conversation.form`
+
+Is emitted when the data of a form is changed.
+
+| Name        | Type       | Description                                               |
+| ----------- | ---------- | --------------------------------------------------------- |
+| `data`      | `FormData` | The form data.                                            |
+| `formKey`   | `string`   | The unique key for the form.                              |
+| `actionKey` | `string`   | The key of the form component responsible for the change. |
+
+In order to subscribe to any of these actions you have access to the `ComponentNodeController`. Below is an example how to subscribe to the `conversation.form` action.
 
 ```ts
 component.actions.watch('conversation.form', (input, next) => {
@@ -294,7 +242,7 @@ component.actions.watch('conversation.form', (input, next) => {
 
 ### Submitting forms
 
-If you want to listen for form events you should subscribe to the `conversation.form` event. By passing a `key` to the form, you are able to target the form in this listener.
+In order to listen for form events you should subscribe to the `conversation.form` event. By passing a `key` to the form, you are able to target the form in this listener.
 
 ```ts
 component.actions.watch('conversation.form', (input, next) => {
@@ -306,51 +254,3 @@ component.actions.watch('conversation.form', (input, next) => {
     return next(input);
 });
 ```
-
-### Adding custom list items
-
-You can add custom list items to the conversation. To do so you have to register your own custom React component, which will be mapped to a key also provided by you.
-
-#### Example of custom list items
-
-```ts
-import { registerCustomMessageComponent } from '@telia-ace/widget-conversation';
-
-registerCustomMessageComponent(container, 'my-custom-list-item', import('./my-custom-list-item'));
-```
-
-Once the component has been registered it will be available to be used as any other item in the `print` method on the Conversation API.
-
-## Custom secondary action
-
-You can add a secondary action button that's displayed next to the user input field. This button can run any event that you write. You need to add the `secondaryAction` property to the conversation component in the configuration. It accepts an object with the following properties:
-
-| Name     | Type     | Description                                                         |
-| -------- | -------- | ------------------------------------------------------------------- |
-| `action` | `string` | An action that will be dispatched when the button is pressed        |
-| `label`  | `string` | Will be used as a "title" and aria-label on the HTML button element |
-| `icon`   | `string` | An icon to be displayed, defaults to "browse" icon if left empty    |
-
-```json
-    "conversation": {
-        "type": "conversation",
-        "properties": {
-            "secondaryAction": {
-                "action": "my-secondary-action",
-                "label": "Label for the secondary action",
-                "icon": "my-icon"
-            }
-            // ...other properties
-        }
-    }
-```
-
-When you have added this property to the component, you can create an event for it in your code:
-
-```ts
-component.actions.watch('conversation.action', (input, next) => {
-    if (input === 'my-secondary-action') {
-        // handle action
-    }
-});
-```