From 881e84265bddf0934f4e3946f841470aadc67b17 Mon Sep 17 00:00:00 2001 From: Rebecca Alpert Date: Tue, 3 Dec 2024 14:31:27 -0500 Subject: [PATCH 1/5] fix(MicrophoneButton): Turn button off when recognition ends This came out of reviewing the docs - realized button stops doing recognition, but doesn't turn off. --- packages/module/src/MessageBar/MicrophoneButton.tsx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/module/src/MessageBar/MicrophoneButton.tsx b/packages/module/src/MessageBar/MicrophoneButton.tsx index 05df70a9..8598f81c 100644 --- a/packages/module/src/MessageBar/MicrophoneButton.tsx +++ b/packages/module/src/MessageBar/MicrophoneButton.tsx @@ -66,6 +66,8 @@ export const MicrophoneButton: React.FunctionComponent = const result = event.results[0][0].transcript; onSpeechRecognition(result); recognition.stop(); + // turn button off + onIsListeningChange(false); }; recognition.onerror = (event) => { From 53bba5bee7f7e6133c4e9dcbf931fd008fa35c40 Mon Sep 17 00:00:00 2001 From: Rebecca Alpert Date: Tue, 3 Dec 2024 14:38:01 -0500 Subject: [PATCH 2/5] fix(MicrophoneButton): Allow for speech recognition in other languages Tested with ja-JP and it was picking it up. --- .../examples/UI/ChatbotMessageBarLanguage.tsx | 17 +++++++++++++++++ .../extensions/chatbot/examples/UI/UI.md | 10 ++++++++++ packages/module/src/MessageBar/MessageBar.tsx | 2 ++ .../module/src/MessageBar/MicrophoneButton.tsx | 5 ++++- 4 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/ChatbotMessageBarLanguage.tsx diff --git a/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/ChatbotMessageBarLanguage.tsx b/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/ChatbotMessageBarLanguage.tsx new file mode 100644 index 00000000..ed63f03f --- /dev/null +++ b/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/ChatbotMessageBarLanguage.tsx @@ -0,0 +1,17 @@ +import React from 'react'; +import { MessageBar } from '@patternfly/chatbot/dist/dynamic/MessageBar'; + +export const ChatbotMessageBarExample: React.FunctionComponent = () => { + const handleSend = (message) => alert(message); + + return ( + + ); +}; diff --git a/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md b/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md index ccd1649a..5ae63a78 100644 --- a/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md +++ b/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md @@ -247,6 +247,16 @@ By default the message bar supports file uploads via an attach button. Setting ` ``` +### Message bar with speech recognition in a different language + +Speech recognition defaults to en-US. You can update the locale as needed. Locale codes are a combination of the ISO 639-1 language code and the ISO 3166-1 country code, separated by a dash. + +In this example, we are changing it to ja-JP. You can try it out by saying "hajimemashite" (初めまして). + +```js file="./ChatbotMessageBarLanguage.tsx" + +``` + ### Message bar with attach menu appended to attach button You can change the behavior of the attach button to open a menu, rather than the default file viewer for your operating system. This menu can display different actions related to attachments. diff --git a/packages/module/src/MessageBar/MessageBar.tsx b/packages/module/src/MessageBar/MessageBar.tsx index 48d10c44..7c2fc56e 100644 --- a/packages/module/src/MessageBar/MessageBar.tsx +++ b/packages/module/src/MessageBar/MessageBar.tsx @@ -58,6 +58,7 @@ export interface MessageBarProps { send?: { tooltipContent?: string; props?: ButtonProps }; microphone?: { tooltipContent?: { active?: string; inactive?: string }; + language?: string; props?: ButtonProps; }; }; @@ -184,6 +185,7 @@ export const MessageBar: React.FunctionComponent = ({ onIsListeningChange={setIsListeningMessage} onSpeechRecognition={handleSpeechRecognition} tooltipContent={buttonProps?.microphone?.tooltipContent} + language={buttonProps?.microphone?.language} {...buttonProps?.microphone?.props} /> )} diff --git a/packages/module/src/MessageBar/MicrophoneButton.tsx b/packages/module/src/MessageBar/MicrophoneButton.tsx index 8598f81c..54b64dc7 100644 --- a/packages/module/src/MessageBar/MicrophoneButton.tsx +++ b/packages/module/src/MessageBar/MicrophoneButton.tsx @@ -22,6 +22,8 @@ export interface MicrophoneButtonProps extends ButtonProps { tooltipProps?: TooltipProps; /** English text "Use microphone" and "Stop listening" used in the tooltip */ tooltipContent?: { active?: string; inactive?: string }; + /** Locale code for language speech recognition is conducted in. This should be in the format 'en-US', a.k.a. the ISO 639-1 code, a dash, and the ISO_3166-1 code. */ + language?: string; } export const MicrophoneButton: React.FunctionComponent = ({ @@ -31,6 +33,7 @@ export const MicrophoneButton: React.FunctionComponent = className, tooltipProps, tooltipContent = { active: 'Stop listening', inactive: 'Use microphone' }, + language = 'en-US', ...props }: MicrophoneButtonProps) => { // Microphone @@ -60,7 +63,7 @@ export const MicrophoneButton: React.FunctionComponent = const recognition: SpeechRecognition = new (window.SpeechRecognition || window.webkitSpeechRecognition)(); recognition.continuous = false; recognition.interimResults = false; - recognition.lang = 'en-US'; + recognition.lang = language; recognition.onresult = (event) => { const result = event.results[0][0].transcript; From 074f3a52fe668f59c9d55493e3ea6963b70a68a5 Mon Sep 17 00:00:00 2001 From: Rebecca Alpert Date: Tue, 3 Dec 2024 15:37:05 -0500 Subject: [PATCH 3/5] chore(docs): Update design guidelines --- .../extensions/chatbot/design-guidelines.md | 54 ++++++++++--------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/packages/module/patternfly-docs/content/extensions/chatbot/design-guidelines.md b/packages/module/patternfly-docs/content/extensions/chatbot/design-guidelines.md index e8a3615b..541c54fe 100644 --- a/packages/module/patternfly-docs/content/extensions/chatbot/design-guidelines.md +++ b/packages/module/patternfly-docs/content/extensions/chatbot/design-guidelines.md @@ -8,7 +8,7 @@ source: design-guidelines import "./images.css" -## Elements +## Elements
![Main elements of a ChatBot.](./img/chatbot-elements.svg) @@ -17,14 +17,14 @@ import "./images.css" 1. **Container:** The window that contains the entire ChatBot experience and all of its components. 1. **Header:** A persistent region at the top of the ChatBot window that contains navigation, branding, and actions. 1. **Navigation:** A menu that contains navigational options, including access to the conversation history. -1. **Options menu:** Contains display options and other settings. More details can be found in the [ChatBot variations section](#variations). +1. **Options menu:** Contains display options and other settings. More details can be found in the [ChatBot variations section](#variations). 1. **Messages:** Elements of the conversation between a ChatBot and user. More details can be found in the [message guidelines](#messages). 1. **Attachments:** Details about files that a user has uploaded to the ChatBot. 1. **Footer:** A persistent region at the bottom of the ChatBot window that contains the message bar and the footnote. 1. **Footnote (optional):** A persistent, short message that contains any legal disclaimers or important information about the ChatBot. Footnotes are optional, but strongly recommended. More details can be found in the [footnote guidelines](#footnotes). 1. **Toggle:** The button that allows users to open and close the ChatBot window. When the ChatBot is opened, the toggle should appear below the ChatBot window. The toggle shape and icon can be customized as needed, as shown in these [ChatBot toggle examples](/patternfly-ai/chatbot/ui#custom-toggle-icon). More details can be found in the [guidelines for accessing a ChatBot](#accessing-a-chatbot). -### Messages +### Messages
![A basic user message, bot message, and quick reply buttons.](./img/message-elements.svg) @@ -33,26 +33,26 @@ import "./images.css" 1. **User message:** Messages that the user has sent to the ChatBot. 1. **Bot message:** Messages from the ChatBot, which are marked with an "AI" label to communicate the use of AI to users. You should choose a descriptive name for your ChatBot. 1. **Avatar:** Representative image for your ChatBot and the user. ChatBot avatars should align with your product's brand and any existing brand standards. -1. **Name:** Identifier for your ChatBot and the user. Choose a name for your ChatBot that users can easily identify as a bot. +1. **Name:** Identifier for your ChatBot and the user. Choose a name for your ChatBot that users can easily identify as a bot. 1. **Timestamp:** The relative or absolute time that a message was sent. 1. **Label:** Labels ChatBot messages as "AI." 1. **Quick responses:** Programmable, clickable actions that allow users to quickly answer questions from the ChatBot. -1. **Sources:** Cards that link to documentation or other external resources. When multiple sources are included, users can paginate through the different options. +1. **Sources:** Cards that link to documentation or other external resources. When multiple sources are included, users can paginate through the different options. 1. **Response actions:** Actions that allow users to interact with a bot message. these typically include providing feedback, copying, sharing, or reading aloud, but [custom message actions](/patternfly-ai/chatbot/messages#custom-message-actions) are also supported. -### Message bar +### Message bar -To message the ChatBot, users can type directly into the message bar in the footer or click any included actions. +To message the ChatBot, users can type directly into the message bar in the footer or click any included actions.
![Elements of a message bar, including input actions.](./img/message-bar-elements.svg)
-1. **Attach button:** Allows users to upload files from their computer. +1. **Attach button:** Allows users to upload files from their computer. 1. **Use microphone button:** Supports speech recognition to allow users to use voice input. This feature is currently only available in Chrome and Safari. -1. **Send button:** Allows users to send a typed message. This button should be disabled until a user has input text. +1. **Send button:** Allows users to send a typed message. This button should be disabled until a user has input text. -When a user chooses to use speech input via the microphone button, the button will display an animation to indicate that the ChatBot is listening to the user (as shown in [this speech recognition example](/patternfly-ai/chatbot/ui#message-bar-with-speech-recognition-and-file-attachment)). To stop voice input, users will need to select the microphone button again. +When a user chooses to use speech input via the microphone button, the button will display an animation to indicate that the ChatBot is listening to the user (as shown in [this speech recognition example](/patternfly-ai/chatbot/ui#message-bar-with-speech-recognition-and-file-attachment)).
![Active listening button in the message bar.](./img/listening.svg) @@ -64,11 +64,11 @@ When a bot is responding (or "streaming") to the user, a stop button will be dis ![Stop button in the message bar.](./img/stop-button.svg)
-### Footnotes +### Footnotes The footnote provides a persistent space to display messaging about your product's Terms and Conditions, which focus on the rules of using the service, and Privacy Policy, which focuses on the handling of personal data. -Though footnotes are not required, they are highly recommended to ensure legal compliance, establish user trust, and clearly define the usage guidelines and data handling practices. +Though footnotes are not required, they are highly recommended to ensure legal compliance, establish user trust, and clearly define the usage guidelines and data handling practices. When users select the footnote, you can display a popover that provides more information than would fit in the footnote: @@ -81,6 +81,7 @@ When users select the footnote, you can display a popover that provides more inf When ChatBots are designed to meet the needs of your users, they can improve the overall UX of your product by offering convenient, efficient, and persistent support. When your ChatBot cannot find an answer for your users, you must provide them with a method to contact human support. Before building a ChatBot, make sure that you have justified it as an appropriate solution by asking yourself these questions: + - What are the users’ goals? - How in-depth is the assistance the user will need? - Does human assistance better serve your users? @@ -89,9 +90,10 @@ Before building a ChatBot, make sure that you have justified it as an appropriat Do not create a ChatBot simply for the sake of novelty. -### When to use a ChatBot +### When to use a ChatBot Use a ChatBot to offer your users on-demand help at any time, including: + - Technical support and troubleshooting. - Product information and documentation. - Sales and product recommendations. @@ -102,12 +104,13 @@ Use a ChatBot to offer your users on-demand help at any time, including: ### When not to use a ChatBot -Do not use a ChatBot when: -- A task could be accomplished more efficiently through the UI. +Do not use a ChatBot when: + +- A task could be accomplished more efficiently through the UI. - A process is very complex or could take a long time. - A real human is needed for sensitive or emotional topics. -## Behavior +## Behavior ### Accessing a ChatBot @@ -125,19 +128,20 @@ When there is an unread message from the ChatBot, a notification badge should be ### Using the navigation menu -The ChatBot navigation menu primarily contains a users' conversation history with the ChatBot. Clicking the menu icon opens a side drawer in the ChatBot window. +The ChatBot navigation menu primarily contains a users' conversation history with the ChatBot. Clicking the menu icon opens a side drawer in the ChatBot window. -By clicking into the navigation menu, users can search through previous conversations and perform additional actions, such as sharing a conversation with others. +By clicking into the navigation menu, users can search through previous conversations and perform additional actions, such as sharing a conversation with others.
![Conversation history with an options menu opened on a previous conversation.](./img/conversation-history.svg)
-### Attaching files +### Attaching files + +Using [the attach button](/patternfly-ai/chatbot/overview/design-guidelines#message-bar) in the message bar, users can [attach files](/patternfly-ai/chatbot/messages#file-attachments) to their message to share with the ChatBot. -Using [the attach button](/patternfly-ai/chatbot/overview/design-guidelines#message-bar) in the message bar, users can [attach files](/patternfly-ai/chatbot/messages#file-attachments) to their message to share with the ChatBot. +The attach button can follow a couple of patterns, including: -The attach button can follow a couple of patterns, including: - Opening the file explorer for a user's operating system - Opening a menu with attachment options that are chosen by designers and developers @@ -165,7 +169,7 @@ If a message attachment fails, an error message should share the reason for fail ![Error alert for failed attachment.](./img/attachment-error.svg)
-## Variations +## Variations ### Display modes @@ -175,7 +179,7 @@ There are a few display modes that users can choose when interacting with a Chat ![Menu of display options.](./img/display-menu.svg)
-1. **Overlay:** The default display mode, which floats the ChatBot window on top of a product's UI. In overlay mode, the ChatBot can be opened and minimized with the toggle. +1. **Overlay:** The default display mode, which floats the ChatBot window on top of a product's UI. In overlay mode, the ChatBot can be opened and minimized with the toggle.
![ChatBot in overlay mode.](./img/overlay.svg) @@ -207,6 +211,6 @@ Your users will expect your ChatBot to be in a reliable, permanent location. Ove For guidance on writing ChatBot content, refer to our [conversation design guidelines](/patternfly-ai/conversation-design). -## Accessibility +## Accessibility -Although accessibility has been integrated into the design of our ChatBot components, it is important to ensure that your implementation is inclusive of all users. For more guidance, refer to [our accessibility guidelines](/accessibility/about-accessibility). \ No newline at end of file +Although accessibility has been integrated into the design of our ChatBot components, it is important to ensure that your implementation is inclusive of all users. For more guidance, refer to [our accessibility guidelines](/accessibility/about-accessibility). From 3525c86ae450af431fca463e8bde1951006137bc Mon Sep 17 00:00:00 2001 From: Rebecca Alpert Date: Tue, 3 Dec 2024 16:13:04 -0500 Subject: [PATCH 4/5] Update packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> --- .../content/extensions/chatbot/examples/UI/UI.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md b/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md index 5ae63a78..72fcc5e1 100644 --- a/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md +++ b/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md @@ -251,7 +251,7 @@ By default the message bar supports file uploads via an attach button. Setting ` Speech recognition defaults to en-US. You can update the locale as needed. Locale codes are a combination of the ISO 639-1 language code and the ISO 3166-1 country code, separated by a dash. -In this example, we are changing it to ja-JP. You can try it out by saying "hajimemashite" (初めまして). +In this example, the locale is set to to ja-JP. You can try it out by saying "hajimemashite" (初めまして). ```js file="./ChatbotMessageBarLanguage.tsx" From b245ae7453a545a1fe7975361cb525803b579038 Mon Sep 17 00:00:00 2001 From: Rebecca Alpert Date: Tue, 3 Dec 2024 16:13:21 -0500 Subject: [PATCH 5/5] Update packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> --- .../content/extensions/chatbot/examples/UI/UI.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md b/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md index 72fcc5e1..2f841801 100644 --- a/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md +++ b/packages/module/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md @@ -249,7 +249,7 @@ By default the message bar supports file uploads via an attach button. Setting ` ### Message bar with speech recognition in a different language -Speech recognition defaults to en-US. You can update the locale as needed. Locale codes are a combination of the ISO 639-1 language code and the ISO 3166-1 country code, separated by a dash. +Speech recognition defaults to en-US. You can update the locale as needed. Locale codes are a combination of the [ISO 639-1 language code](https://www.iso.org/iso-639-language-code) and the [ISO 3166-1 country code](https://www.iso.org/iso-3166-country-codes.html), separated by a hyphen. In this example, the locale is set to to ja-JP. You can try it out by saying "hajimemashite" (初めまして).