@telia-ace/widget-conversation 1.0.15 → 1.0.18

package/LICENSE.txt

@@ -1,6 +1,6 @@
-Copyright © 2021, Telia Company AB. All rights reserved.
-
-THIS PACKAGE AND CONTAINING SOFTWARE IS PART OF
-THE HUMANY SERVICE. BY USING THIS SOFTWARE YOU
-AGREE TO THE FOLLOWING TERMS AND CONDITIONS:
+Copyright © 2021, Telia Company AB. All rights reserved.
+
+THIS PACKAGE AND CONTAINING SOFTWARE IS PART OF
+THE HUMANY SERVICE. BY USING THIS SOFTWARE YOU
+AGREE TO THE FOLLOWING TERMS AND CONDITIONS:
 http://www.humany.com/legal

package/README.md

@@ -1,256 +1,273 @@
-# Widget Conversation API
-
-The Widget Conversation API provides support for reading and writing to a conversational component inside a widget.
-
-## Explore the API
-
-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
-
-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';
-
-const MyPlugin = async (container) => {
-    const platform = await ConversationPlatform.getInstance(container);
-
-    platform.registerProvider('my-chat', (conversation, component) => {
-        // start interacting with the conversation here
-    });
-};
-```
-
-## 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.
-
-### `print(content: object)`
-
-Returns a `ConversationEntry` message that can be used to update and/or remove the content from the conversation at a later stage.
-
-##### Example
-
-```ts
-const agent = conversation.createAgent();
-const entry = agent.print('Lorem ipsum');
-
-entry.update({
-    // ...
-});
-
-entry.remove();
-```
-
-### Messages
-
-#### Simple text message
-
-Used to render plain text without HTML-formatting.
-
-##### Example
-
-```ts
-// print user message
-conversation.user.print('Lorem ipsum');
-
-// print agent message
-const agent = conversation.createAgent();
-agent.print('Lorem ipsum');
-```
-
-#### Message with list of actions
-
-Example of how to render a list with actions. Is only supported on `Agent` and as system message.
-
-| 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. |
-
-##### Example
-
-```ts
-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',
-    },
-});
-```
-
-#### Message 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.
-
-| Name    | Type                    | Description                                                                                                                                                                                  |
-| ------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `title` | `string`                | Title for the entry.                                                                                                                                                                         |
-| `body`  | `string`                | Body content for the entry. Supports HTML.                                                                                                                                                   |
-| `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
-
-```ts
-agent.print({
-    title: 'Log in',
-    body: 'Enter your ID to login',
-    key: 'my-login-form',
-    form: (builder) => {
-        builder
-            .createComponent({
-                component: 'Text',
-                type: 'number',
-                name: 'id',
-                title: 'ID',
-                required: true,
-            })
-            .createComponent({
-                title: 'Log in',
-                actionKey: 'submit',
-                name: 'submit',
-                component: 'Submit',
-                type: 'submit',
-                evaluate: true,
-                value: 'Log in',
-            });
-    },
-});
-```
-
-### Specify a sender name and/or avatar
-
-To create an agent with a name and avatar use the `createAgent` method on the conversation.
-
-##### Example
-
-```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',
-    },
-});
-```
-
-### 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
-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
-
-```ts
-const done = conversation.loading();
-// ...
-done(); // remove loader
-```
-
-##### Typing indicator
-
-```ts
-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`
-
-Is emitted when the user submits a message.
-
-| Name   | Type     | Description         |
-| ------ | -------- | ------------------- |
-| `text` | `string` | The submitted text. |
-
-#### `conversation.action`
-
-Is emitted when the user clicks on an action.
-
-| Name   | Type     | Description                  |
-| ------ | -------- | ---------------------------- |
-| `text` | `string` | Key of the submitted action. |
-
-#### `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) => {
-    return next(input);
-});
-```
-
-### 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.
-
-```ts
-component.actions.watch('conversation.form', (input, next) => {
-    if (input.formKey === 'my-login-form' && input.actionKey === 'submit') {
-        const username = input.data.username;
-        const password = input.data.password;
-    }
-
-    return next(input);
-});
-```
+# Widget Conversation API
+
+The Widget Conversation API provides support for reading and writing to a conversational component inside a widget.
+
+## Sandbox
+
+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
+
+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.
+
+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';
+
+const MyPlugin = async (container) => {
+    const platform = await ConversationPlatform.getInstance(container);
+
+    platform.registerProvider('my-chat', (conversation, component) => {
+        // start interacting with the conversation here
+    });
+};
+```
+
+You also need to register the provider inside the widget configuration:
+
+```JSON
+   "my-conversation-component": {
+        "type": "conversation",
+        "properties": {
+            "providers": ["my-chat"],
+            // ...
+        },
+        "context": {}
+    },
+```
+
+### Creating an agent in the conversation
+
+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({
+    name: 'Agent Smith',
+    avatar: 'https://www.site.com/avatar.jpg',
+});
+```
+
+## Writing to the conversation
+
+### Posting, updating and removing content
+
+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.
+
+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 of simple text message
+
+```ts
+// print user message
+conversation.user.print('Lorem ipsum');
+
+// print agent message
+const agent = conversation.createAgent();
+agent.print('Lorem ipsum');
+```
+
+##### Example of updating or removing content
+
+```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                                                   |
+| --------- | -------- | ------------------------------------------------------------- |
+| `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. |
+
+##### Example of a list of actions
+
+```ts
+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
+
+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                                                                                                                                                                                  |
+| ------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title` | `string`                | Title for the entry.                                                                                                                                                                         |
+| `body`  | `string`                | Body content for the entry. Supports HTML.                                                                                                                                                   |
+| `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
+
+```ts
+agent.print({
+    title: 'Log in',
+    body: 'Enter your ID to login',
+    key: 'my-login-form',
+    form: (builder) => {
+        builder
+            .createComponent({
+                component: 'Text',
+                type: 'number',
+                name: 'id',
+                title: 'ID',
+                required: true,
+            })
+            .createComponent({
+                title: 'Log in',
+                actionKey: 'submit',
+                name: 'submit',
+                component: 'Submit',
+                type: 'submit',
+                evaluate: true,
+                value: 'Log in',
+            });
+    },
+});
+```
+
+### The loading and typing indicators
+
+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.
+
+When you need to make the user aware that your agent is currently typing, you should use the `typing` function on `Agent`.
+
+#### Example of `loading`
+
+```ts
+const done = conversation.loading();
+// ...
+done(); // remove loader
+```
+
+#### Example of `typing`
+
+```ts
+const done = agent.typing();
+// ...
+done(); // remove loader
+```
+
+## Writing system messages
+
+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`.
+
+#### Example
+
+```ts
+conversation.print('Hello world!');
+```
+
+## Reading from the conversation
+
+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.
+
+The following actions are emitted from the conversational component:
+
+> 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.
+
+| 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. |
+
+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) => {
+    return next(input);
+});
+```
+
+### 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.
+
+```ts
+component.actions.watch('conversation.form', (input, next) => {
+    if (input.formKey === 'my-login-form' && input.actionKey === 'submit') {
+        const username = input.data.username;
+        const password = input.data.password;
+    }
+
+    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
+    }
+});
+```

package/dist/agent.d.ts

@@ -1,17 +1,17 @@
-import { Symbol } from '@telia-ace/widget-ui';
-import { ConversationEntry } from './conversation-controller';
-import { ConversationProvider } from './conversation-provider';
-import { ConversationMessageSettings, ConverstationMessageItem } from './types';
-export declare type AgentSettings = {
-    name?: string;
-    avatar?: string | Symbol;
-};
-export declare class Agent {
-    private provider;
-    name?: string;
-    avatar?: string | Symbol;
-    constructor(provider: ConversationProvider, settings: AgentSettings);
-    print: (settings: string | ConversationMessageSettings | ConverstationMessageItem<any> | ConverstationMessageItem<any>[]) => ConversationEntry | undefined;
-    typing: () => (() => void) | undefined;
-    update(settings: AgentSettings): void;
-}
+import { Symbol } from '@telia-ace/widget-ui';
+import { ConversationEntry } from './conversation-controller';
+import { ConversationProvider } from './conversation-provider';
+import { ConversationMessageSettings, ConverstationMessageItem } from './types';
+export declare type AgentSettings = {
+    name?: string;
+    avatar?: string | Symbol;
+};
+export declare class Agent {
+    private provider;
+    name?: string;
+    avatar?: string | Symbol;
+    constructor(provider: ConversationProvider, settings: AgentSettings);
+    print: (settings: string | ConversationMessageSettings | ConverstationMessageItem<any> | ConverstationMessageItem<any>[]) => ConversationEntry | undefined;
+    typing: () => (() => void) | undefined;
+    update(settings: AgentSettings): void;
+}

package/dist/{ui → components}/conversation/conversation.d.ts

@@ -1,6 +1,6 @@
-import React from 'react';
-declare type Props = {
-    className: string;
-};
-declare const Conversation: React.FC<Props>;
-export default Conversation;
+import React from 'react';
+declare type Props = {
+    className: string;
+};
+declare const Conversation: React.FC<Props>;
+export default Conversation;