@telia-ace/widget-conversation 1.0.14 → 1.0.17

package/README.md

@@ -2,21 +2,23 @@
 
 The Widget Conversation API provides support for reading and writing to a conversational component inside a widget.
 
-## Explore the API
+## Sandbox
 
-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.
+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.
 
 [![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
 
-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.
+In order to access the API you need to have a widget with a conversational component.
 
-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.
+### 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.
 
-##### Example
+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.
 
 ```ts
 import { ConversationPlatform } from '@telia-ace/widget-conversation';
@@ -30,34 +32,39 @@ const MyPlugin = async (container) => {
 };
 ```
 
-## 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.
+You also need to register the provider inside the widget configuration:
 
-### `print(content: object)`
+```JSON
+   "my-conversation-component": {
+        "type": "conversation",
+        "properties": {
+            "providers": ["my-chat"],
+            // ...
+        },
+        "context": {}
+    },
+```
 
-Returns a `ConversationEntry` message that can be used to update and/or remove the content from the conversation at a later stage.
+### Creating an agent in the conversation
 
-##### Example
+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.
 
 ```ts
-const agent = conversation.createAgent();
-const entry = agent.print('Lorem ipsum');
-
-entry.update({
-    // ...
+const agent = conversation.createAgent({
+    name: 'Agent Smith',
+    avatar: 'https://www.site.com/avatar.jpg',
 });
-
-entry.remove();
 ```
 
-### Messages
+## Writing to the conversation
+
+### Posting, updating and removing content
 
-#### Simple text message
+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 accommedate different types of content.
 
-Used to render plain text without HTML-formatting.
+The `print(content: object)` function let's you return a `ConversationEntry` message that can be used to update and/or remove the content from the conversation.
 
-##### Example
+##### Example of simple text message
 
 ```ts
 // print user message
@@ -68,9 +75,22 @@ const agent = conversation.createAgent();
 agent.print('Lorem ipsum');
 ```
 
-#### Message with list of actions
+##### Example of updating or removing content
 
-Example of how to render a list with actions. Is only supported on `Agent` and as system message.
+```ts
+const agent = conversation.createAgent();
+const entry = agent.print('Hello world!');
+
+entry.update({
+    // ...
+});
+
+entry.remove();
+```
+
+### Entry with list of actions
+
+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.
 
 | Name      | Type     | Description                                                   |
 | --------- | -------- | ------------------------------------------------------------- |
@@ -78,7 +98,7 @@ Example of how to render a list with actions. Is only supported on `Agent` and a
 | `body`    | `string` | Body content for the entry. Supports HTML.                    |
 | `actions` | `object` | Key-value-pairs representing available actions for the entry. |
 
-##### Example
+##### Example of a list of actions
 
 ```ts
 agent.print({
@@ -92,9 +112,9 @@ agent.print({
 });
 ```
 
-#### Message with a form
+### Entry with a form
 
-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.
+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.
 
 | Name    | Type                    | Description                                                                                                                                                                                  |
 | ------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -103,7 +123,7 @@ Example of how to render a form that can be handled by the `conversation.form` e
 | `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
+##### Example of an entry with a form
 
 ```ts
 agent.print({
@@ -132,47 +152,13 @@ agent.print({
 });
 ```
 
-### Specify a sender name and/or avatar
-
-To create an agent with a name and avatar use the `createAgent` method on the conversation.
-
-##### Example
+### The loading and typing indicators
 
-```ts
-const agent = conversation.createAgent({
-    name: 'Mr. Agent',
-    avatar: 'https://www.site.com/avatar.jpg',
-});
-
-agent.print({
-    title: 'I found the following invoices associated to your account:',
-    actions: {
-        action1: 'Action 1',
-        action2: 'Action 2',
-        action3: 'Action 3',
-    },
-});
-```
+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.
 
-### Writing system messages
+When you need to make the user aware that your agent is currently typing, you should use the `typing` function on `Agent`.
 
-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
-conversation.print('Lorem ipsum');
-```
-
-### Loading/typing indicator
-
-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.
-
-In cases where you want to notify the user that the agent is currently typing, you should use the `typing` function on `Agent`.
-
-#### Example
-
-##### Loading
+#### Example of `loading`
 
 ```ts
 const done = conversation.loading();
@@ -180,7 +166,7 @@ const done = conversation.loading();
 done(); // remove loader
 ```
 
-##### Typing indicator
+#### Example of `typing`
 
 ```ts
 const done = agent.typing();
@@ -188,51 +174,34 @@ const done = agent.typing();
 done(); // remove loader
 ```
 
-## Reading from the conversation
-
-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.
-
-### Actions
-
-The following actions are emitted from the conversational component.
-
-**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`
+## Writing system messages
 
-Is emitted when the user submits a message.
+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`.
 
-| Name   | Type     | Description         |
-| ------ | -------- | ------------------- |
-| `text` | `string` | The submitted text. |
+#### Example
 
-#### `conversation.action`
+```ts
+conversation.print('Hello world!');
+```
 
-Is emitted when the user clicks on an action.
+## Reading from the conversation
 
-| Name   | Type     | Description                  |
-| ------ | -------- | ---------------------------- |
-| `text` | `string` | Key of the submitted action. |
+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.
 
-#### `conversation.form`
+The following actions are emitted from the conversational component:
 
-Is emitted when the data of a form is changed.
+> 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.
 
-| 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. |
+| 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. |
 
-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.
+If you want to subscribe to any of the `conversation.form`-actions you have access to the `ComponentNodeController`. Example below:
 
 ```ts
 component.actions.watch('conversation.form', (input, next) => {
@@ -242,7 +211,7 @@ component.actions.watch('conversation.form', (input, next) => {
 
 ### Submitting forms
 
-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.
+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.
 
 ```ts
 component.actions.watch('conversation.form', (input, next) => {
@@ -254,3 +223,51 @@ 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
+    }
+});
+```