@telia-ace/widget-conversation 1.0.26 → 1.0.28

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,71 +32,122 @@ 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
+
+**`print()` accepts an array, which is considered best practice when writing to the conversation. The previous way of posting an object will still currently be supported, but is considered to be deprecated.**
+
+### 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 accommodate different types of content.
 
-Used to render plain text without HTML-formatting.
+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.
 
-##### Example
+##### Example of simple text message
 
 ```ts
 // print user message
-conversation.user.print('Lorem ipsum');
+conversation.user.print([['text', 'Lorem ipsum']]);
 
 // print agent message
 const agent = conversation.createAgent();
-agent.print('Lorem ipsum');
+agent.print([['text', '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([['text', 'Hello world!']]);
 
-| 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. |
+entry.update([
+    // ...
+]);
 
-##### Example
+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.
+
+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
 
 ```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',
-    },
-});
+// 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',
+                },
+            ],
+        },
+    ],
+]);
 ```
 
-#### 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 +156,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,107 +185,146 @@ agent.print({
 });
 ```
 
-### Specify a sender name and/or avatar
+### 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.
 
-To create an agent with a name and avatar use the `createAgent` method on the conversation.
+| 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" |
 
-##### Example
+##### Example of an entry for an incoming video call
 
 ```ts
-const agent = conversation.createAgent({
-    name: 'Mr. Agent',
-    avatar: 'https://www.site.com/avatar.jpg',
-});
+agent.print([
+    [
+        'video-request',
+        {
+            header: 'Video call',
+            accept: 'Accept',
+            decline: 'Decline',
+        },
+    ],
+]);
+```
 
-agent.print({
-    title: 'I found the following invoices associated to your account:',
-    actions: {
-        action1: 'Action 1',
-        action2: 'Action 2',
-        action3: 'Action 3',
-    },
+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:
+
+```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);
 });
 ```
 
-### Writing system messages
+### Video Call Events
 
-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`.
+| Action Key                  | Description                                                                                    |
+| --------------------------- | ---------------------------------------------------------------------------------------------- |
+| `show-overlay`              | Dispatch this event when you want to render an overlay where you can render the video call     |
+| `overlay-mounted`           | Dispatched when the overlay is rendered, will provide an HTML element to render the video call |
+| `hide-overlay`              | Hide overlay                                                                                   |
+| `show-overlay-conversation` | Show the underlying conversation on top of the video overlay                                   |
+| `hide-overlay-conversation` | Hide the conversation overlay.                                                                 |
 
-#### Example
+#### show-overlay
+
+This event is recommended to be used when a user accept an video call. See the example above for one way of implementing it. This event will result in the `overlay-mounted` event being dispatched, which you may subscribe to and use to render the video call.
+
+#### overlay-mounted
+
+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.
 
 ```ts
-conversation.print('Lorem ipsum');
+component.actions.watch('overlay-mounted', (overlayElem, next) => {
+    // the overlayElem here may be used to render the ongoing call
+});
 ```
 
-### Loading/typing indicator
+#### hide-overlay
 
-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.
+Dispatching this event will hide the overlay
 
-In cases where you want to notify the user that the agent is currently typing, you should use the `typing` function on `Agent`.
+```ts
+component.actions.dispatch('hide-overlay', {});
+```
 
-#### Example
+#### show-overlay-conversation
 
-##### Loading
+Dispatching this event will show the underlying conversation on top of the video overlay.
 
 ```ts
-const done = conversation.loading();
-// ...
-done(); // remove loader
+component.actions.dispatch('show-overlay-conversation', {});
 ```
 
-##### Typing indicator
+#### hide-overlay-conversation
+
+Dispatching this event will hide the conversation overlay.
 
 ```ts
-const done = agent.typing();
-// ...
-done(); // remove loader
+component.actions.dispatch('hide-overlay-conversation', {});
 ```
 
-## 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.
+### The loading and typing indicators
 
-### Actions
+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.
 
-The following actions are emitted from the conversational component.
+When you need to make the user aware that your agent is currently typing, you should use the `typing` function on `Agent`.
 
-**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.
+#### Example of `loading`
 
-#### `conversation.user-typing`
+```ts
+const done = conversation.loading();
+// ...
+done(); // remove loader
+```
 
-Is emitted when the user´s typing indicator is changed.
+#### Example of `typing`
 
-| Name         | Type     | Description                                    |
-| ------------ | -------- | ---------------------------------------------- |
-| `textLength` | `number` | The current text length of the user's message. |
+```ts
+const done = agent.typing();
+// ...
+done(); // remove loader
+```
 
-#### `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([['text', '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 +334,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 +346,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
+    }
+});
+```

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

@@ -18,6 +18,12 @@ export declare type ConversationContent = {
 export declare type ConversationComponentProperties = {
     providers: string[];
     messages: BundledConversationMessage[];
+    overlay?: {
+        conversation: boolean;
+        secondary: boolean;
+    };
+    overlayConversationHeader?: string;
+    overlayConversationCloseLabel?: string;
     loading: boolean;
     inputPlaceholder: string;
     inputDisabled: boolean;
@@ -27,6 +33,11 @@ export declare type ConversationComponentProperties = {
     avatarSize: string;
     typingActors: any[];
     sendButtonLabel: string;
+    secondaryAction?: {
+        icon?: string;
+        action: string;
+        label: string;
+    };
 };
-declare const ConversationComponent: (container: Container) => Promise<void>;
-export default ConversationComponent;
+export declare const ConversationComponent: (container: Container) => Promise<void>;
+export {};

package/dist/components/conversation/ui/content.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export declare const ConversationContent: React.FC;

package/dist/components/conversation/ui/loader.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import { ConversationMessageSender } from '../../../types';
+declare type Props = {
+    className?: string;
+    agentData?: ConversationMessageSender;
+    boxed?: boolean;
+};
+declare const ConversationLoader: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLDivElement>>;
+export default ConversationLoader;

package/dist/components/conversation/ui/message-list-items/button-list.d.ts

@@ -0,0 +1,8 @@
+import { DispatchAction } from '@telia-ace/widget-ui';
+import { FC } from 'react';
+import { ButtonListProperties } from '../../../../types';
+declare type Props = {
+    dispatch: DispatchAction;
+} & ButtonListProperties;
+export declare const ButtonList: FC<Props>;
+export {};

package/dist/components/conversation/ui/message-list-items/custom.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+declare type Props = {
+    type: string;
+    content?: {
+        [key: string]: any;
+    };
+};
+export declare const Custom: React.FC<Props>;
+export {};

package/dist/components/conversation/ui/message-list-items/html.d.ts

@@ -0,0 +1,5 @@
+import { FC } from 'react';
+import { HtmlProperties } from '../../../../types';
+declare type Props = HtmlProperties;
+export declare const Html: FC<Props>;
+export {};

package/dist/components/conversation/ui/message-list-items/link-list.d.ts

@@ -0,0 +1,8 @@
+import { DispatchAction } from '@telia-ace/widget-ui';
+import { FC } from 'react';
+import { LinkListProperties } from '../../../../types';
+declare type Props = {
+    dispatch: DispatchAction;
+} & LinkListProperties;
+export declare const LinkList: FC<Props>;
+export {};

package/dist/components/conversation/ui/message-list-items/separator.d.ts

@@ -0,0 +1,2 @@
+import { FC } from 'react';
+export declare const Separator: FC;

package/dist/components/conversation/ui/message-list-items/text.d.ts

@@ -0,0 +1,6 @@
+import { FC } from 'react';
+declare type Props = {
+    text: string;
+};
+export declare const Text: FC<Props>;
+export {};

package/dist/components/conversation/ui/message-list-items/video-request.d.ts

@@ -0,0 +1,8 @@
+import { DispatchAction } from '@telia-ace/widget-ui';
+import { FC } from 'react';
+import { VideoRequestProperties } from '../../../../types';
+declare type Props = {
+    dispatch: DispatchAction;
+} & VideoRequestProperties;
+export declare const VideoRequest: FC<Props>;
+export {};

package/dist/{ui/conversation → components/conversation/ui}/message-types/agent.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { ConversationMessageSender } from '../../../types';
+import { ConversationMessageSender } from '../../../../types';
 declare type Props = {
     className?: string;
     children: any;

package/dist/{ui/conversation → components/conversation/ui}/message-types/index.d.ts

@@ -1,5 +1,4 @@
 export { default as AgentMessage } from './agent';
-export { default as CustomMessage } from './custom';
 export { default as SystemMessage } from './system';
 export { default as Timestamp } from './timestamp';
 export { default as UserMessage } from './user';

package/dist/components/conversation/ui/message-types/message-list.d.ts

@@ -0,0 +1,9 @@
+import { FC } from 'react';
+import { DispatchAction } from '@telia-ace/widget-ui';
+import { ConverstationMessageItem } from '../../../../types';
+declare type Props = {
+    items: ConverstationMessageItem<any>[];
+    dispatch: DispatchAction;
+};
+export declare const MessageList: FC<Props>;
+export {};

package/dist/{ui/conversation → components/conversation/ui}/message-types/system.d.ts

@@ -6,7 +6,7 @@ export declare type Props = {
     fullWidth?: boolean;
     children: any;
 };
-declare const SystemMessage: React.FC<Props>;
+declare const SystemMessage: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLDivElement>>;
 export declare const StyledSystemMessage: import("styled-components").StyledComponent<"div", any, any, never>;
 export declare const Discrete: import("styled-components").StyledComponent<"div", any, {}, never>;
 export default SystemMessage;

package/dist/components/conversation/ui/message.d.ts

@@ -0,0 +1,5 @@
+import React from 'react';
+import { BundledConversationMessage } from '../plugin';
+export declare const ConversationMessage: React.ForwardRefExoticComponent<{
+    className?: string | undefined;
+} & BundledConversationMessage & React.RefAttributes<HTMLDivElement>>;

package/dist/components/conversation/ui/overlay-outlets.d.ts

@@ -0,0 +1,13 @@
+import { DispatchAction } from '@telia-ace/widget-ui';
+import { FC } from 'react';
+declare type OverlayOutletProps = {
+    dispatch: DispatchAction;
+};
+export declare const OverlayOutlet: FC<OverlayOutletProps>;
+declare type ConversationOverlayProps = {
+    dispatch: DispatchAction;
+    header?: string;
+    buttonLabel?: string;
+};
+export declare const ConversationOverlayOutlet: FC<ConversationOverlayProps>;
+export {};