fix: made some fixes to how WebChatContainer handles mounting and changes to the web chat config (#15)

- The container will now destroy and recreate web chat when the config changes.
- The container will properly destroy and recreate web chat when unmounted and remounted.
This address problems caused in development with React 18's strict mode changes.

Author: TazmanianDI

.eslintrc.js

@@ -46,5 +46,11 @@ module.exports = {
     'react/jsx-filename-extension': [1, { extensions: ['.tsx', '.jsx'] }],
     'react/require-default-props': 'off',
     'no-use-before-define': 'off',
+    // Airbnb allows arrow functions but not regular functions which doesn't make any sense.
+    'react/jsx-no-bind': 'off',
+    // This rule is annoying and sometimes just wrong.
+    'no-shadow': 'off',
+    // The properties of object parameters should be allowed to be modified.
+    'no-param-reassign': ['error', { props: false }],
   },
 };

README.md

@@ -5,17 +5,15 @@
 
 `@ibm-watson/assistant-web-chat-react` is a React library to extend the [web chat](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-web-chat) feature of [IBM Watson Assistant](https://www.ibm.com/cloud/watson-assistant) within your React application. This makes it easier to provide user-defined response types written in React, add content to custom elements with React, have the web chat and your site communicate more easily, and more.
 
-There are two utility functions provided by this library:
-
-1. The `WebChatContainer` function is a functional component that makes use of `withWebChat` to load web chat when the component is mounted.
-2. The `withWebChat` function creates a high-order-component (HOC) that you can wrap around an existing component to inject `createWebChatInstance` into it so your component can create a new instance of web chat when appropriate. You can find more information in the [withWebChat documentation](./WITH_WEB_CHAT.md).
+The primary utility provided by this library is the `WebChatContainer` functional component. This component will load and render an instance of web chat when it is mounted and destroy that instance when unmounted.
 
 <details>
   <summary>Table of contents</summary>
 
 - [Installation](#installation)
 - [Using WebChatContainer](#webchatcontainer)
 - [API](#api)
+- [withWebChat](#withWebChat)
 - [Additional resources](#additional-resources)
 - [License](#license)
 
@@ -40,63 +38,101 @@ yarn add @ibm-watson/assistant-web-chat-react
 The `WebChatContainer` function component is intended to make it as easy as possible to include web chat in your React application. To use, you simply need to render this component anywhere in your application and provide the [web chat configuration options object](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#configurationobject) as a prop.
 
 ```javascript
+import React from 'react';
+import { WebChatContainer, setEnableDebug } from '@ibm-watson/assistant-web-chat-react';
+
+const webChatOptions = {
+  integrationID: 'XXXX',
+  region: 'XXXX',
+  serviceInstanceID: 'XXXX',
+  // subscriptionID: 'only on enterprise plans',
+  // Note that there is no onLoad property here. The WebChatContainer component will override it.
+  // Use the onBeforeRender or onAfterRender prop instead.
+};
+
+// Include this if you want to get debugging information.
+setEnableDebug(true);
+
 function App() {
-  const webChatOptions = {
-    integrationID: 'XXXX',
-    region: 'XXXX',
-    serviceInstanceID: 'XXXX',
-    // subscriptionID: 'only on enterprise plans',
-    // Note that there is no onLoad property here. The WebChatContainer component will override it with its own.
-  };
   return <WebChatContainer config={webChatOptions} />;
 }
 ```
 
 This component is also capable of managing custom responses. To do so, you need to pass a `renderCustomResponse` function as a prop. This function should return a React component that will render the content for the specific message for that response. You should make sure that the `WebChatContainer` component does not get unmounted in the middle of the life of your application because it will lose all custom responses that were previously received by web chat.
 
 ```javascript
+import React from 'react';
+import { WebChatContainer } from '@ibm-watson/assistant-web-chat-react';
+
+const webChatOptions = {
+  integrationID: 'XXXX',
+  region: 'XXXX',
+  serviceInstanceID: 'XXXX',
+  // subscriptionID: 'only on enterprise plans',
+  // Note that there is no onLoad property here. The WebChatContainer component will override it.
+  // Use the onBeforeRender or onAfterRender prop instead.
+};
+
 function App() {
-  const webChatOptions = {
-    integrationID: 'XXXX',
-    region: 'XXXX',
-    serviceInstanceID: 'XXXX',
-    // subscriptionID: 'only on enterprise plans',
-    // Note that there is no onLoad property here. The WebChatContainer component will override it with its own.
-  };
   return <WebChatContainer renderCustomResponse={renderCustomResponse} config={webChatOptions} />;
 }
 
 function renderCustomResponse(event) {
-  return <div>My custom content</div>;
+  // The event here will contain details for each custom response that needs to be rendered.
+  // The "user_defined_type" property is just an example; it is not required. You can use any other property or
+  // condition you want here. This makes it easier to handle different response types if you have more than
+  // one custom response type.
+  if (event.data.message.user_defined && event.data.message.user_defined.user_defined_type === 'my-custom-type') {
+    return <div>My custom content</div>
+  }
 }
 ```
 
 ## API
 
 ### WebChatContainer API
 
-The `WebChatContainer` function is a functional component that makes use of `withWebChat` to load web chat when the component is mounted. It can also manage React portals for custom responses.
+The `WebChatContainer` function is a functional component that will load and render an instance of web chat when it is mounted and destroy that instance when unmounted. If the web chat configuration options change, it will also destroy the previous web chat and create a new one with the new configuration. It can also manage React portals for custom responses.
+
+Note that this component will call the [web chat render](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methods#render) method for you. You do not need to call it yourself. You can use the `onBeforeRender` or `onAfterRender` prop to execute operations before or after render is called.
 
 #### Props
 
 `WebChatContainer` has the following props.
 
 | Attribute | Required | Type    | Description |
 |-----------|----------|---------|-------------|
-| config    | Yes      | object  | The [web chat configuration options object](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#configurationobject). Note that any `onLoad` property will be ignored. |
+| config    | Yes      | object  | The [web chat configuration options object](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#configurationobject). Note that any `onLoad` property will be ignored. If this prop is changed and a new object provided, then the current web chat will  be destroyed and a new one created with the new object. |
 |
 | instanceRef    | No      | MutableRefObject  | A convenience prop that is a reference to the web chat instance. This component will set the value of this ref using the `current` property when the instance has been created. |
 |
-| onBeforeRender    | No      | function  | This is a callback function that is called after web chat has been loaded and before the `render` function is called. This function is passed a single argument which is the instance of web chat that was loaded. This function can be used to obtain a reference to the web chat instance if you want to make use of the instance functions that are available. |
+| onBeforeRender    | No      | function  | This is a callback function that is called after web chat has been loaded and before the `render` function is called. This function is passed a single argument which is the instance of web chat that was loaded. This function can be used to obtain a reference to the web chat instance if you want to make use of the instance methods that are available. |
+|
+| onAfterRender    | No      | function  | This is a callback function that is called after web chat has been loaded and after the `render` function is called. This function is passed a single argument which is the instance of web chat that was loaded. This function can be used to obtain a reference to the web chat instance if you want to make use of the instance methods that are available. |
 |
 | renderCustomResponse    | No      | function  | This function is a callback function that will be called by this container to render custom responses. If this prop is provided, then the container will listen for custom response events from web chat and will generate a React portal for each event. This function will be called once during component render for each custom response event. This function takes two arguments. The first is the [custom response event](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-events#customresponse) that triggered the custom response. The second is a convenience argument that is the instance of web chat. The function should return a `ReactNode` that renders the custom content for the response. |
 |
 
+### Debugging
+
+In addition to the props above, the `WebChatContainer` component can output additional debug information. To enable this output, call the `setEnableDebug` function which is exported from this library.
+
+```javascript
+setEnableDebug(true);
+
+function App() {
+  return <WebChatContainer config={webChatOptions} />;
+}
+```
+
+## withWebChat
+
+The [withWebChat](WITH_WEB_CHAT.MD) function is an older function that is used for loading web chat. It is now deprecated in favor of using the `WebChatContainer` component instead.
+
 ## Additional resources
 - [Watson Assistant](https://www.ibm.com/cloud/watson-assistant)
 - [Watson Assistant web chat feature documentation](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-web-chat)
 - [Watson Assistant web chat API documentation](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-overview)
-- [Higher order components](https://reactjs.org/docs/higher-order-components.html)
 
 ## License
 

WITH_WEB_CHAT.MD

@@ -1,5 +1,7 @@
 # Using withWebChat
 
+**NOTE: This function is deprecated and will be removed in a future release of this library. Use the WebChatContainer component instead.**
+
 The `WebChatContainer` component, makes use of the `withWebChat` function to create high-order-components that inject a function for creating instances of web chat. This document explains how to use that function if you wish to bypass the `WebChatContainer`.
 
 <details>