@patternfly/chatbot 6.5.0 → 6.6.0-prerelease.2

package/patternfly-docs/content/extensions/chatbot/design-guidelines.md

@@ -16,7 +16,7 @@ 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. **History menu:** A menu that contains a conversation history of previous chats.
+1. **Chat history menu:** A menu that contains a history of previous chats.
 1. **Options menu:** A menu that contains settings that are relevant to your product. This typically includes display options (more details in the [ChatBot variations section](#variations)) and other general settings (more details in the [ChatBot settings and preferences section](#chatbot-settings-and-preferences)).
 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.
@@ -43,7 +43,7 @@ import "./images.css"
 
 At the start of a new chat, you should welcome your users to the ChatBot with a greeting.
 
-If you have user details from their account information, you can personalize this greeting with their username or name. If you don't have this information, or if you'd prefer to not use their personal details, you should instead introduce the ChatBot: 
+As much as possible, the suggested prompts should consider the user’s location in the service or application, or the situation their project is undergoing. If you have user details from their account information, you can personalize this greeting with their username or name. If you don't have this information, or if you'd prefer to not use their personal details, you should instead introduce the ChatBot: 
 
 <div class="ws-docs-content-img">
 ![Welcome messages.](./img/welcome-message.svg)
@@ -55,16 +55,44 @@ To help users get started quickly, it can also be helpful to include welcome pro
 ![Welcome message with prompts.](./img/welcome-elements.svg)
 </div>
 
-#### Source tiles
+#### Source cards
 
-A ChatBot can share relevant sources with users, like documentation that could provide the information a user is searching for. These sources will be contained in a single tile, which users can paginate through and select to navigate to other resources. 
+To share relevant resources with users, like documentation containing the answer to a user's question, you can use source cards. 
 
-To provide users with enough context, sources should have descriptive titles and descriptions. The title is limited to 1 line and the body is limited to 2 lines.
+<div class="ws-docs-content-img">
+![A white card below a message from a ChatBot. In the card is blue text for the title and black text for a short description. There are four pink annotation markers pointing to major sections of the image.](./img/source-card.svg)
+</div>
+
+1. **Source count:** Notes the number of sources shared in a card. 
+2. **Source card title:** Offers a concise, descriptive title of the source content to provide users with quick context about a source. Titles are limited to 1 line and should be truncated when the text overflows or wraps.
+3. **Source card description:** Offers a concise preview or summary of the source content. We recommend limiting the length to 2 lines to provide context without overcrowding the chat window.
+4. **Pagination:** Used to navigate through all options when there are multiple source cards provided. Not displayed when only 1 source is provided.
+
+Instead of a short preview of the linked source's content, you can choose to summarize the contents and use that summary as your description. This is helpful for in-depth resources where the context is not clear from the beginning snippet. You can also choose to elevate a quote from the resource that is most relevant to the user's question.
 
 <div class="ws-docs-content-img">
-![Bot message that include multiple source tiles.](./img/source-tile.svg)
+![A single source card is show below a chatbot message.](./img/source-card-summary.svg)
 </div>
 
+While we generally recommend staying within 2 lines for your source description, you can choose to provide a "show more" button that allows users to expand and view a longer description. When using expandable descriptions, it is recommended to end the description at the end of the sentence. Use your best UX judgment here&mdash;extremely lengthy descriptions can quickly fill out the chat window and obstruct previous conversation details.
+
+<div class="ws-docs-content-img">
+![A before and after image is shown. The before image shows a single source card below a chatbot message, with a blue link at the bottom that says "show more." In the after image, additional description lines are shown and the link now says "show less."](./img/source-card-expanded.svg)
+</div>
+
+##### Custom source cards
+
+You can create a custom source card by utilizing additional components that make sense for your use case. The source card's flexibility can be used in a number of ways, but the following example demonstrates how you might customize its appearance to provide additional details about a source.
+
+<div class="ws-docs-content-img">
+![A source card, annotated with four pink markers. Each marker points to a unique point of the card: a light gray subtitle below the main card title, a filled, green label beneath the card body that is labeled with a confidence % score, a blue help link is to the right of the green label that says "learn about this score", and light gray text at the bottom of the card with the last updated date.](./img/custom-source-card.svg)
+</div>
+
+1. **Subtitle:** Additional context about the resource, such as where the documentation is hosted.
+2. **Label:** A confidence score, to indicate the likelihood that a source contains relevant information for the user.
+3. **Link with popover:** Additional context about the confidence score label.
+4. **Date:** The last time the linked resource was updated. 
+
 #### Quick start tiles
 
 A ChatBot can share a link to a [quick start](/extensions/quick-starts) that will help users complete a given task. Users can either select **Start** or the tile's title to initiate the linked quick start.
@@ -119,7 +147,7 @@ When users select either of these icons, you should present them with either:
     1. **Close button (optional):** Closes the feedback form. The original feedback response should still be collected.
     1. **Quick responses:** Options for users to provide more context around their rating. Customize these to make the most sense for your product. You can present positive and negative options based on the response type originally selected.
     1. **Text area (optional):** Allows users to provide additional written detail if they'd like.
-    1. **Submit button:** Submits the feedback form and triggers the   thank-you card.
+    1. **Submit button:** Submits the feedback form and triggers the thank-you card.
 
 ### Message bar
 
@@ -205,7 +233,7 @@ To help users further identify the toggle, add a "Launch ChatBot" tooltip. You c
 ![Tooltips for ChatBot toggle.](./img/toggle-tooltips.svg)
 </div>
 
-Whichever method you choose, it is critical to be consistent with the toggle location and refer to the following the additional guidelines for each. 
+Whichever method you choose, it is critical to be consistent with the toggle location and refer to the following additional guidelines for each. 
 
 #### Floating toggle
 When users click the toggle, the ChatBot window opens and the toggle will change to display an "angle down" icon to indicate that clicking the toggle again will minimize the ChatBot. Users can select the toggle at any point in their journey to open and close the ChatBot as needed.
@@ -250,17 +278,27 @@ If a UI element within the page content is an AI/ChatBot-supported feature, the
 ![Menu item for an AI action that launches a ChatBot.](./img/ai-action-inpage.svg)
 </div>
 
-When a ChatBot is launches via an AI-supported action, the action should be sent as a user message once the ChatBot opens.  
+When a ChatBot is launched via an AI-supported action, the action should be sent as a user message once the ChatBot opens.
 
 <div class="ws-docs-content-img">
 ![User message in ChatBot for an AI action command.](./img/ai-action-message.svg)
 </div>
 
-### Starting a new conversation 
+### Starting a new chat 
+
+Each time a user begins a new chat, display a [welcome message](#welcome-message), with prompts that provide initial suggestions and indicate the actions that the ChatBot can take.
+
+The default approach for users to create a new chat is by clicking the "New chat" button (which contains a "pen to square" icon) placed at the top of the [chat history menu](#using-the-chat-history-menu). 
 
-Each time a user begins a new conversation, display a [welcome message, with prompts](#welcome-message) that help them learn what the ChatBot can help with.
+<div class="ws-docs-content-img">
+![A blue "New chat" button at the top right of a drawer labeled "Chat history".](./img/new-chat-in-nav.svg)
+</div>
+
+Alternatively, you can choose to surface the "New chat" button as an icon button in the header. For this approach, the "pen to square" icon is displayed in the button and a "New chat" tooltip should appear on hover and focus.
 
-As much as possible, the suggested prompts should consider the user’s location in the service or application, or the situation their project is undergoing. 
+<div class="ws-docs-content-img">
+![An icon button is placed at the start of the ChatBot header, prior to a hamburger menu. It contains the visual of a pen placed within a square and is in a hover state, with a darker gray background and a black tooltip that says "New chat."](./img/starting-new-chat.svg)
+</div>
 
 ### Executing user requests
 
@@ -272,9 +310,9 @@ This can be done using the [quick response](/extensions/chatbot/messages#message
 ![Confirmation options from a bot in response to a user's request.](./img/quick-response-confirmation.svg)
 </div>
 
-### Using the conversation history menu
+### Using the chat history menu
 
-The ChatBot history menu contains a log of a users' previous chats. Clicking the menu icon opens a side drawer in the ChatBot window.
+The ChatBot history menu contains a log of a user's previous chats. Clicking the menu icon opens a side drawer in the ChatBot window.
 
 By clicking into the history menu, users can search through previous conversations and perform additional actions, such as sharing a conversation with others.
 
@@ -282,13 +320,13 @@ By clicking into the history menu, users can search through previous conversatio
 ![Conversation history with an options menu opened on a previous conversation.](./img/conversation-history.svg)
 </div>
 
-When the conversation history is still loading, display skeleton items:
+When the chat history is still loading, display skeleton items:
 
 <div class="ws-docs-content-img">
 ![Chat history items loading.](./img/loading-state.svg)
 </div>
 
-If there's an error loading the conversation history, display an error screen with steps for resolving the error:
+If there's an error loading the chat history, display an error screen with steps for resolving the error:
 
 <div class="ws-docs-content-img">
 ![Error state in chat history.](./img/error-state.svg)
@@ -349,9 +387,9 @@ For guidance, refer to our download transcripts demo, which opens a Markdown fil
 
 Choose the download action location that best works for your ChatBot:
 
-#### Download via conversation history drawer
+#### Download via chat history drawer
 
-If your ChatBot uses a conversation history drawer, you can provide a download option in the [actions menu linked to a previous conversation](/extensions/chatbot/ui#drawer-with-conversation-actions).
+If your ChatBot uses a chat history drawer, you can provide a download option in the [actions menu linked to a previous conversation](/extensions/chatbot/ui#drawer-with-conversation-actions).
 
 <div class="ws-docs-content-img">
 ![Expanded menu for previous chat in the history window, which shows a download option.](./img/download-chat-history.svg)
@@ -367,7 +405,7 @@ To allow users to download individual bot messages, the message actions can incl
 
 #### Download control in header
 
-If you don't use a conversation history drawer, you can place an option to download the transcript for the active chat within the header options menu. 
+If you don't use a chat history drawer, you can place an option to download the transcript for the active chat within the header options menu. 
 
 <div class="ws-docs-content-img">
 ![Download transcript action within the ChatBot header options menu.](./img/download-header.svg)

package/patternfly-docs/content/extensions/chatbot/examples/Messages/MessageWithDeepThinking.tsx

@@ -27,5 +27,18 @@ export const MessageWithDeepThinkingExample: FunctionComponent = () => (
         body: "Here's why I said this."
       }}
     />
+    <Message
+      name="Bot"
+      role="bot"
+      avatar={patternflyAvatar}
+      content="This example has deep thinking that is loading:"
+      deepThinking={{
+        isDefaultExpanded: false,
+        toggleContent: 'Show thinking',
+        subheading: 'Thought for 3 seconds',
+        body: "Here's why I said this.",
+        isLoading: true
+      }}
+    />
   </>
 );

package/patternfly-docs/content/extensions/chatbot/examples/UI/ChatbotMessageBarCustomActions.tsx

@@ -0,0 +1,190 @@
+import { useState, FunctionComponent, ReactNode } from 'react';
+import { MessageBar } from '@patternfly/chatbot/dist/dynamic/MessageBar';
+import {
+  Divider,
+  DropdownItem,
+  DropdownList,
+  Label,
+  MenuToggle,
+  Select,
+  SelectList,
+  SelectOption
+} from '@patternfly/react-core';
+import { PlusIcon, ClipboardIcon, CodeIcon, UploadIcon } from '@patternfly/react-icons';
+import { useDropzone } from 'react-dropzone';
+
+export const ChatbotMessageBarCustomActionsExample: FunctionComponent = () => {
+  const [isFirstMenuOpen, setIsFirstMenuOpen] = useState<boolean>(false);
+  const [isSecondMenuOpen, setIsSecondMenuOpen] = useState<boolean>(false);
+  const [isModelSelectOpen, setIsModelSelectOpen] = useState<boolean>(false);
+  const [selectedModel, setSelectedModel] = useState<string>('GPT-4');
+  const [showCanvasLabel, setShowCanvasLabel] = useState<boolean>(true);
+
+  const handleSend = (message: string | number) => alert(message);
+
+  const { open, getInputProps } = useDropzone({
+    multiple: true,
+    // eslint-disable-next-line no-console
+    onDropAccepted: () => console.log('fileUploaded')
+  });
+
+  const onFirstMenuToggle = () => {
+    setIsFirstMenuOpen(!isFirstMenuOpen);
+  };
+
+  const onSecondMenuToggle = () => {
+    setIsSecondMenuOpen(!isSecondMenuOpen);
+  };
+
+  const onModelSelect = (
+    _event: React.MouseEvent<Element, MouseEvent> | undefined,
+    value: string | number | undefined
+  ) => {
+    setSelectedModel(value as string);
+    setIsModelSelectOpen(false);
+  };
+
+  const firstMenuItems: ReactNode = (
+    <DropdownList>
+      <DropdownItem value="Logs" id="logs" icon={<ClipboardIcon />}>
+        Logs
+      </DropdownItem>
+      <DropdownItem value="YAML - Status" id="yaml-status" icon={<CodeIcon />}>
+        YAML - Status
+      </DropdownItem>
+      <DropdownItem value="YAML - All contents" id="yaml-all" icon={<CodeIcon />}>
+        YAML - All contents
+      </DropdownItem>
+      <Divider key="divider" />
+      <DropdownItem value="Upload from computer" id="upload" icon={<UploadIcon />} onClick={open}>
+        Upload from computer
+      </DropdownItem>
+    </DropdownList>
+  );
+
+  const secondMenuItems: ReactNode = (
+    <DropdownList>
+      <DropdownItem value="canvas" id="canvas">
+        {showCanvasLabel ? 'Disable' : 'Enable'} Canvas
+      </DropdownItem>
+      <Divider key="divider-1" />
+      <DropdownItem value="Logs" id="logs" icon={<ClipboardIcon />}>
+        Logs
+      </DropdownItem>
+      <DropdownItem value="YAML - Status" id="yaml-status" icon={<CodeIcon />}>
+        YAML - Status
+      </DropdownItem>
+      <DropdownItem value="YAML - All contents" id="yaml-all" icon={<CodeIcon />}>
+        YAML - All contents
+      </DropdownItem>
+      <Divider key="divider-2" />
+      <DropdownItem value="Upload from computer" id="upload" icon={<UploadIcon />} onClick={open}>
+        Upload from computer
+      </DropdownItem>
+    </DropdownList>
+  );
+
+  const modelOptions = ['GPT-4', 'GPT-3.5', 'Claude', 'Llama 2'];
+
+  return (
+    <>
+      {/* This is required for react-dropzone to work in Safari and Firefox */}
+      <input {...getInputProps()} hidden />
+      <div style={{ marginBottom: '1rem' }}>
+        <h4 style={{ marginBottom: '0.5rem' }}>Custom attach menu with a PlusIcon at the start</h4>
+        <MessageBar
+          onSendMessage={handleSend}
+          attachButtonPosition="start"
+          attachMenuProps={{
+            isAttachMenuOpen: isFirstMenuOpen,
+            setIsAttachMenuOpen: setIsFirstMenuOpen,
+            attachMenuItems: firstMenuItems,
+            onAttachMenuSelect: (_ev, value) => {
+              // eslint-disable-next-line no-console
+              console.log('selected', value);
+              setIsFirstMenuOpen(false);
+            },
+            attachMenuInputPlaceholder: 'Search options...',
+            onAttachMenuToggleClick: onFirstMenuToggle,
+            onAttachMenuOnOpenChangeKeys: ['Escape', 'Tab']
+          }}
+          buttonProps={{
+            attach: {
+              icon: <PlusIcon />,
+              tooltipContent: 'Message actions',
+              'aria-label': 'Message actions'
+            }
+          }}
+        />
+      </div>
+
+      <div>
+        <h4 style={{ marginBottom: '0.5rem' }}>Custom attach menu with additional actions</h4>
+        <MessageBar
+          onSendMessage={handleSend}
+          attachButtonPosition="start"
+          attachMenuProps={{
+            isAttachMenuOpen: isSecondMenuOpen,
+            setIsAttachMenuOpen: setIsSecondMenuOpen,
+            attachMenuItems: secondMenuItems,
+            onAttachMenuOnOpenChangeKeys: ['Escape', 'Tab'],
+            onAttachMenuSelect: (_ev, value) => {
+              // eslint-disable-next-line no-console
+              console.log('selected', value);
+              if (value === 'canvas') {
+                setShowCanvasLabel(!showCanvasLabel);
+              }
+              setIsSecondMenuOpen(false);
+            },
+            onAttachMenuToggleClick: onSecondMenuToggle
+          }}
+          buttonProps={{
+            attach: {
+              icon: <PlusIcon />,
+              tooltipContent: 'Message actions',
+              'aria-label': 'Message actions'
+            }
+          }}
+          additionalActions={
+            <>
+              <Select
+                isOpen={isModelSelectOpen}
+                selected={selectedModel}
+                shouldFocusToggleOnSelect
+                onSelect={onModelSelect}
+                onOpenChange={(isOpen) => setIsModelSelectOpen(isOpen)}
+                toggle={(toggleRef) => (
+                  <MenuToggle
+                    ref={toggleRef}
+                    variant="plainText"
+                    onClick={() => setIsModelSelectOpen(!isModelSelectOpen)}
+                    isExpanded={isModelSelectOpen}
+                    aria-label={`${selectedModel}, Select a model`}
+                    style={{
+                      minWidth: '120px'
+                    }}
+                  >
+                    {selectedModel}
+                  </MenuToggle>
+                )}
+              >
+                <SelectList>
+                  {modelOptions.map((option) => (
+                    <SelectOption key={option} value={option}>
+                      {option}
+                    </SelectOption>
+                  ))}
+                </SelectList>
+              </Select>
+              {showCanvasLabel && (
+                <Label closeBtnAriaLabel="Remove Canvas mode" onClose={() => setShowCanvasLabel(false)}>
+                  Canvas
+                </Label>
+              )}
+            </>
+          }
+        />
+      </div>
+    </>
+  );
+};

package/patternfly-docs/content/extensions/chatbot/examples/UI/UI.md

@@ -70,11 +70,11 @@ import { MessageBar } from '@patternfly/chatbot/dist/dynamic/MessageBar';
 import SourceDetailsMenuItem from '@patternfly/chatbot/dist/dynamic/SourceDetailsMenuItem';
 import { ChatbotModal } from '@patternfly/chatbot/dist/dynamic/ChatbotModal';
 import SettingsForm from '@patternfly/chatbot/dist/dynamic/Settings';
-import { BellIcon, CalendarAltIcon, ClipboardIcon, CodeIcon, ThumbtackIcon, UploadIcon } from '@patternfly/react-icons';
+import { BellIcon, CalendarAltIcon, ClipboardIcon, CodeIcon, PlusIcon, ThumbtackIcon, UploadIcon } from '@patternfly/react-icons';
 import { useDropzone } from 'react-dropzone';
 
 import ChatbotConversationHistoryNav from '@patternfly/chatbot/dist/dynamic/ChatbotConversationHistoryNav';
-import { Button, DropdownItem, DropdownList, Checkbox, MenuToggle, Select, SelectList, SelectOption } from '@patternfly/react-core';
+import { Button, Label, DropdownItem, DropdownList, Checkbox, MenuToggle, Select, SelectList, SelectOption } from '@patternfly/react-core';
 
 import OutlinedWindowRestoreIcon from '@patternfly/react-icons/dist/esm/icons/outlined-window-restore-icon';
 import ExpandIcon from '@patternfly/react-icons/dist/esm/icons/expand-icon';
@@ -291,6 +291,19 @@ Attachments can also be added to the ChatBot via [drag and drop.](/extensions/ch
 
 ```
 
+### Message bar with custom attach menu and additional actions
+
+You can move the attach button to the start of the message bar and customize it with a different icon. To include additional actions in the message bar you can also use the `additionalActions` prop.
+
+This example shows two message bar variations:
+
+1. A message bar with a custom attach menu where a `PlusIcon` is positioned at the start
+2. The same custom attach menu with additional actions, including a model selector menu and a dismissable "Canvas" label
+
+```js file="./ChatbotMessageBarCustomActions.tsx"
+
+```
+
 ### Footer with message bar and footnote
 
 A simple footer with a message bar and footnote would have this code structure: