microsoft · compulim · Jan 13, 2023 · Dec 1, 2022 · Dec 1, 2022 · Dec 1, 2022
@@ -22,6 +22,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+### Added
+
+-  Added ability for developers to customize Web Chat by extending the default UI without having to re-implement existing components. [@dawolff-ms](https://github.com/dawolff-ms) in PR [#4539](https://github.com/microsoft/BotFramework-WebChat/pull/4539)
+
 ### Fixed
 
 -  Fixes [#4558](https://github.com/microsoft/BotFramework-WebChat/issues/4558). In high contrast mode, "Retry" link button should use link color as defined by [CSS System Colors](https://w3c.github.io/csswg-drafts/css-color/#css-system-colors), by [@beyackle2](https://github.com/beyackle2) in PR [#4537](https://github.com/microsoft/BotFramework-WebChat/pull/4537)

@@ -0,0 +1,69 @@
+<!DOCTYPE html>
+<html lang="en-US">
+  <head>
+    <link href="/assets/index.css" rel="stylesheet" type="text/css" />
+    <script crossorigin="anonymous" src="https://unpkg.com/@babel/standalone@7.8.7/babel.min.js"></script>
+    <script crossorigin="anonymous" src="https://unpkg.com/react@16.8.6/umd/react.development.js"></script>
+    <script crossorigin="anonymous" src="https://unpkg.com/react-dom@16.8.6/umd/react-dom.development.js"></script>
+    <script crossorigin="anonymous" src="/test-harness.js"></script>
+    <script crossorigin="anonymous" src="/test-page-object.js"></script>
+    <script crossorigin="anonymous" src="/__dist__/webchat-es5.js"></script>
+  </head>
+  <body>
+    <div id="webchat"></div>
+    <script type="text/babel" data-presets="env,stage-3,react">
+      const {
+        ReactDOM: { render },
+        WebChat: {
+          Components: { AccessKeySinkSurface, BasicToaster, BasicTranscript, BasicConnectivityStatus, BasicSendBox, Composer },
+          createDirectLine
+        }
+      } = window;
+
+      run(async function () {
+        const directLine = await createDirectLine({ token: await testHelpers.token.fetchDirectLineToken() });
+        const store = testHelpers.createStore();
+
+        const classes = {
+          surface: "surface-class-name",
+          sendBox: "send-box-class-name",
+          transcript: "transcript-class-name",
+          customComponent: "custom-component-class-name"
+        }
+        const role = "main";
+
+        render(
+          <Composer directLine={directLine} store={store}>
+            <AccessKeySinkSurface className={classes.surface} role={role}>
+              <BasicToaster />
+              <BasicSendBox className={classes.sendBox} />
+              <BasicConnectivityStatus />
+              <div className={classes.customComponent}>This is a custom component.</div>
+              <BasicTranscript className={classes.transcript} />
+            </AccessKeySinkSurface>
+          </Composer>,
+          document.getElementById('webchat')
+        );
+
+        await pageConditions.uiConnected();
+
+        const container = document.getElementById('webchat');
+        expect(container?.firstChild).not.toBeUndefined();
+
+        const surface = container.firstChild;
+        expect(surface.className).toContain(classes.surface);
+        expect(surface.role).toEqual(role);
+
+        const components = surface.childNodes;
+        expect(components[0].className).toContain("toaster");
+        expect(components[1].className).toContain(classes.sendBox);
+        expect(components[2].textContent).toContain("Connectivity Status");
+        expect(components[3].className).toContain(classes.customComponent);
+        expect(components[4].className).toContain("keyboard-help");
+        expect(components[5].className).toContain(classes.transcript);
+
+        await host.snapshot();
+      });
+    </script>
+  </body>
+</html>
@@ -0,0 +1,5 @@
+/** @jest-environment ./packages/test/harness/src/host/jest/WebDriverEnvironment.js */
+
+describe('customization', () => {
+  test('should render BasicWebChat components in a different structure', () => runHTML('customization.basicWebChat.restructure.html'));
+});
@@ -4,7 +4,13 @@ import ReactWebChat, { ReactWebChatProps } from './ReactWebChat';
 
 import Composer, { ComposerProps } from './Composer';
 
+import AccessKeySinkSurface from './Utils/AccessKeySink/Surface';
+
 import BasicWebChat, { BasicWebChatProps } from './BasicWebChat';
+import BasicConnectivityStatus from './BasicConnectivityStatus';
+import BasicSendBox from './BasicSendBox';
+import BasicToaster from './BasicToaster';
+import BasicTranscript from './BasicTranscript';
 
 import Avatar from './Activity/Avatar';
 import Bubble from './Activity/Bubble';
@@ -51,6 +57,13 @@ const Components = {
   Composer,
   Localize,
 
+  // Components for restructuring BasicWebChat
+  AccessKeySinkSurface,
+  BasicConnectivityStatus,
+  BasicSendBox,
+  BasicToaster,
+  BasicTranscript,
+
   // Components for recomposing activities and attachments
   AudioContent,
   FileContent,

@@ -0,0 +1,5 @@
+# We are hitting an issue around react-scripts preflight check, and it is by design.
+# When react-scripts start supporting newer babel-jest@24, we could remove this check skip.
+# https://github.com/facebook/create-react-app/issues/4167
+
+SKIP_PREFLIGHT_CHECK=true
@@ -0,0 +1,23 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
@@ -0,0 +1,219 @@
+# Extending Web Chat with custom UI components
+
+This sample shows how to extend the default UI for Web Chat to include your own UI components. This allows developers to create features within the Web Chat UI without having to re-implement already existing UI elements. For example, this sample will show how to insert a custom button between the chat transcript and the chat message box.
+
+# Test out the hosted sample
+
+-  [Try out MockBot](https://microsoft.github.io/BotFramework-WebChat/06.recomposing-ui/e.extending-ui)
+
+# Things to try out
+
+-  Click the custom "Say Hello!" button.
+
+# Code
+
+This project is based on [`create-react-app`](https://github.com/facebook/create-react-app).
+
+The completed code contains multiple files. You can start by reading [`App.js`](https://github.com/microsoft/BotFramework-WebChat/tree/main/samples/06.recomposing-ui/e.extending-ui/src/App.js), which replaces the default Web Chat renderer with [`<CustomWebChat>`](https://github.com/microsoft/BotFramework-WebChat/tree/main/samples/06.recomposing-ui/e.extending-ui/src/CustomWebChat.js). The `<CustomWebChat>` component resembles the implementation of the [`<BasicWebChat>`](https://github.com/microsoft/BotFramework-WebChat/blob/main/packages/component/src/BasicWebChat.tsx) component that's used in the default Web Chat.
+
+> Jump to [completed code](#completed-code) to see the end-result `App.js`, `CustomWebChat.js`, and `HelloButton.js`.
+
+## Overview
+
+### `App.js`
+
+[`App.js`](https://github.com/microsoft/BotFramework-WebChat/tree/main/samples/06.recomposing-ui/e.extending-ui/src/App.js) will set up the container for hosting Web Chat components. The container will be using Direct Line chat channel. `getDirectLineToken()` asynchronously retrieves and sets the Direct Line token (you'll need to implement this yourself).
+
+<!-- prettier-ignore-start -->
+```javascript
+const App = () => {
+  const [directLine, setDirectLine] = React.useState();
+
+  if (!directLine) {
+    getDirectLineToken().then(token => setDirectLine(createDirectLine({ token })));
+  }
+  ...
+```
+<!-- prettier-ignore-end -->
+
+We then pass the `directLine` token to the `Composer` component when it has a value. The `Composer` component is provided by Web Chat to allow developers to compose their own UI. Any component that is a descendant of the `Composer` will have access to the context of the chat through higher-order components and React Hooks.
+
+<!-- prettier-ignore-start -->
+```javascript
+  ...
+  return (
+    <React.Fragment>
+      {!!directLine && (
+        <Components.Composer directLine={directLine}>
+          <CustomWebChat />
+        </Components.Composer>
+      )}
+    </React.Fragment>
+  );
+}
+```
+<!-- prettier-ignore-end -->
+
+### `CustomWebChat.js`
+
+The `App.js` implementation places a component named `CustomWebChat` as a child of the `Composer`. The purpose of this component is to resemble the [`BasicWebChat`](https://github.com/microsoft/BotFramework-WebChat/blob/main/packages/component/src/BasicWebChat.tsx) component provided by the Web Chat components library, but provide a way for us to add our own custom components into the UI.
+
+Lets start by first implementing the default `BasicWebChat` inside of `CustomWebChat`:
+
+<!-- prettier-ignore-start -->
+```javascript
+import { Components } from 'botframework-webchat-component';
+
+const CustomWebChat = () => {
+  return (
+    <Components.AccessKeySinkSurface>
+      <Components.BasicToaster />
+      <Components.BasicTranscript />
+      <Components.BasicConnectivityStatus />
+      <Components.BasicSendBox />
+    </Components.AccessKeySinkSurface>
+  );
+};
+```
+<!-- prettier-ignore-end -->
+
+If you were to save, compile and run the code right now, you'll see the default Web Chat experience. This is because the `Basic*` components are the exact same components used by the `BasicWebChat` component. You can choose to modify these components however you like: remove, reorder, pass custom props (such as styling), etc. In this sample, however, we're going to demonstrate adding a completely new component to the UI.
+
+### `HelloButton.js`
+
+Our new component will be a "Say Hello!" button place right above the message box. When a user clicks this button, "Hello!" will be sent to the chat. This component will need to take advantage of the `useSendMessage` hook in order to be able to interact with the chat.
+
+<!-- prettier-ignore-start -->
+```javascript
+import { hooks } from 'botframework-webchat-component';
+
+const { useSendMessage } = hooks;
+
+const HelloButton = () => {  
+  const sendMessage = useSendMessage();
+
+  return (
+    <button onClick={() => sendMessage("Hello!")}>Say Hello!</button>
+  );
+};
+```
+<!-- prettier-ignore-end -->
+
+We can then place our `HelloButton` component in the `CustomWebChat` component wherever we want. In our scenario, we want it right above the `BasicSendBox`.
+
+<!-- prettier-ignore-start -->
+```javascript
+import { Components } from 'botframework-webchat-component';
+import HelloButton from './HelloButton';
+
+const CustomWebChat = () => {
+  return (
+    <Components.AccessKeySinkSurface>
+      <Components.BasicToaster />
+      <Components.BasicTranscript />
+      <Components.BasicConnectivityStatus />
+      <HelloButton />
+      <Components.BasicSendBox />
+    </Components.AccessKeySinkSurface>
+  );
+};
+```
+<!-- prettier-ignore-end -->
+
+If you save, compile and run the code, you'll see a "Say Hello!" button right above the message box. When you click it, "Hello!" will be sent to the chat!
+
+## Completed Code
+
+`App.js` (simplified):
+
+<!-- prettier-ignore-start -->
+```javascript
+import { createDirectLine } from 'botframework-webchat';
+import { Components } from 'botframework-webchat-component';
+import React from 'react';
+import CustomWebChat from './CustomWebChat';
+
+// In this demo, we are using Direct Line token from MockBot.
+// To talk to your bot, you should use the token exchanged using your Direct Line secret.
+// You should never put the Direct Line secret in the browser or client app.
+// https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication
+
+async function getDirectLineToken() {
+  const res = await fetch('https://webchat-mockbot.azurewebsites.net/directline/token', { method: 'POST' });
+  const { token } = await res.json();
+
+  return token;
+}
+
+const App = () => {
+  const [directLine, setDirectLine] = React.useState();
+
+  if (!directLine) {
+    getDirectLineToken().then(token => setDirectLine(createDirectLine({ token })));
+  }
+
+  return (
+    <React.Fragment>
+      {!!directLine && (
+        <Components.Composer directLine={directLine}>
+          <CustomWebChat />
+        </Components.Composer>
+      )}
+    </React.Fragment>
+  );
+};
+
+export default App;
+```
+<!-- prettier-ignore-end -->
+
+`CustomWebChat.js`:
+
+<!-- prettier-ignore-start -->
+```javascript
+import React from 'react';
+import { Components } from 'botframework-webchat-component';
+import HelloButton from './HelloButton';
+
+const CustomWebChat = () => {
+  return (
+    <Components.AccessKeySinkSurface>
+      <Components.BasicToaster />
+      <Components.BasicTranscript />
+      <Components.BasicConnectivityStatus />
+      <HelloButton />
+      <Components.BasicSendBox />
+    </Components.AccessKeySinkSurface>
+  );
+};
+
+export default CustomWebChat;
+```
+<!-- prettier-ignore-end -->
+
+`HelloButton.js`:
+
+<!-- prettier-ignore-start -->
+```javascript
+import React from 'react';
+import { hooks } from 'botframework-webchat-component';
+
+const { useSendMessage } = hooks;
+
+const HelloButton = () => {  
+  const sendMessage = useSendMessage();
+
+  return (
+    <button onClick={() => sendMessage("Hello!")}>Say Hello!</button>
+  );
+};
+
+export default HelloButton;
+```
+<!-- prettier-ignore-end -->
+
+# Further reading
+
+## Full list of Web Chat hosted samples
+
+View the list of [available Web Chat samples](https://github.com/microsoft/BotFramework-WebChat/tree/main/samples)