@telia-ace/widget-conversation 1.0.16 → 1.0.19

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
 
-##### Example
+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';
@@ -30,34 +32,39 @@ const MyPlugin = async (container) => {
 };
 ```
 
-## Writing to the conversation
+You also need to register the provider inside the widget configuration:
 
-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)`
+```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
-
-```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.
+### The loading and typing indicators
 
-In cases where you want to notify the user that the agent is currently typing, you should use the `typing` function on `Agent`.
+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.
 
-#### Example
+When you need to make the user aware that your agent is currently typing, you should use the `typing` function on `Agent`.
 
-##### 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`
+## Writing system messages
 
-Is emitted when the user´s typing indicator is changed.
+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                                    |
-| ------------ | -------- | ---------------------------------------------- |
-| `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. |
+#### 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) => {
@@ -257,24 +226,21 @@ component.actions.watch('conversation.form', (input, next) => {
 
 ### Adding custom list items
 
-In order to add custom list items to the conversation you may register your own custom React component, which will be mapped to a key also provided by you.
+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.
 
-You register the component like below:
+#### Example of custom list items
 
 ```ts
-const platform = await ConversationPlatform.getInstance(container);
+import { registerCustomMessageComponent } from '@telia-ace/widget-conversation';
 
-platform.registerConversationItem('my-custom-list-item', import('./my-custom-list-item'));
+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.
 
-### Secondary action
-
-You may add a secondary action next to the user input field, which will fire a custom event that you provide.
+## Custom secondary action
 
-In order to accomplish this you need to add the `secondaryAction` property to the conversation component in the configuration.
-It accepts an object with the following properties:
+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                                                         |
 | -------- | -------- | ------------------------------------------------------------------- |
@@ -296,7 +262,7 @@ It accepts an object with the following properties:
     }
 ```
 
-When you have added this property to the component, you may listen to it in your code.
+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) => {

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;
@@ -33,5 +39,5 @@ export declare type ConversationComponentProperties = {
         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/{ui/conversation/conversation-loader.d.ts → components/conversation/ui/loader.d.ts}

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

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/{ui/conversation/message-types/custom-message-list-item.d.ts → components/conversation/ui/message-list-items/custom.d.ts}

@@ -5,5 +5,5 @@ declare type Props = {
         [key: string]: any;
     };
 };
-declare const CustomMessageListItem: React.FC<Props>;
-export default CustomMessageListItem;
+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/{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/components/conversation/ui/message.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+import { BundledConversationMessage } from '../plugin';
+declare type Props = {
+    className?: string;
+} & BundledConversationMessage;
+export declare const ConversationMessage: React.FC<Props>;
+export {};

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 {};

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

@@ -0,0 +1,27 @@
+/// <reference types="react" />
+export declare const Avatar: import("styled-components").StyledComponent<"div", any, any, never>;
+export declare const LoaderAnimation: import("styled-components").Keyframes;
+export declare const Loader: import("styled-components").StyledComponent<"div", any, {}, never>;
+export declare const ContentBundle: import("styled-components").StyledComponent<"div", any, {}, never>;
+export declare const MessageTitle: import("styled-components").StyledComponent<import("react").FC<import("@telia-ace/widget-ui").TypographyProps>, any, {}, never>;
+export declare const MessageContainer: import("styled-components").StyledComponent<"div", any, {
+    user?: boolean | undefined;
+}, never>;
+export declare type Stacked = 'first' | 'last' | 'middle';
+export declare const MessageContent: import("styled-components").StyledComponent<"div", any, {
+    user?: boolean | undefined;
+    fullWidth?: boolean | undefined;
+    stacked?: Stacked | undefined;
+}, never>;
+export declare const MessageContentPart: import("styled-components").StyledComponent<"div", any, {}, never>;
+export declare const messageContentPadding: import("styled-components").FlattenInterpolation<import("styled-components").ThemeProps<any>>;
+export declare const StyledForm: import("styled-components").StyledComponent<import("react").FC<{
+    data?: import("@telia-ace/widget-forms").FormData | null | undefined;
+    className?: string | undefined;
+    onChange?: Function | undefined;
+    autoFocus?: boolean | undefined;
+    schema: import("@telia-ace/widget-forms/dist/form").FormSchema;
+    layout: import("@telia-ace/widget-forms/dist/form").FormLayout;
+}>, any, {}, never>;
+export declare const StyledActionList: import("styled-components").StyledComponent<import("react").ForwardRefExoticComponent<Pick<import("@telia-ace/widget-ui").ListProps, "key" | "items" | keyof import("react").HTMLAttributes<HTMLUListElement> | "renderItem" | "renderLi"> & import("react").RefAttributes<HTMLUListElement>>, any, {}, never>;
+export declare const StyledActionButton: import("styled-components").StyledComponent<"button", any, {}, never>;

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

@@ -15,5 +15,4 @@ export declare type ReturnButtonProps = {
         label?: string;
     };
 };
-declare const ConversationReturnButtonComponent: (container: Container) => Promise<void>;
-export default ConversationReturnButtonComponent;
+export declare const ConversationReturnButtonComponent: (container: Container) => Promise<void>;

package/dist/conversation-platform.d.ts

@@ -1,4 +1,4 @@
-import { ComponentNodeController, ComponentPlatform, ReactComponent } from '@telia-ace/widget-core';
+import { ComponentNodeController, ComponentPlatform } from '@telia-ace/widget-core';
 import { RouteData } from '@telia-ace/widget-routing';
 import { Container, EventManager, EventSubscriptionCancellation } from '@webprovisions/platform';
 import { ConversationController } from './conversation-controller';
@@ -38,7 +38,6 @@ export declare class ConversationPlatform {
     navigateToConversationIfActive(id: string): Promise<void>;
     setConversationEndedBehavior(behavior: ConversationEndedBehavior): Promise<void>;
     createController(id: string): ConversationController;
-    registerConversationItem(name: string, component: ReactComponent): Promise<void>;
     registerProvider(name: string, handler: ConversationHandler): void;
     registerController(conversation: ConversationController, component: ComponentNodeController): boolean;
     private writeToComponents;