Merge remote-tracking branch 'upstream/main'

Author: edonehoo

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,58 @@
+name: Bug report
+description: Report an issue with a chatbot component or interaction.
+title: "[Bug] - [short description]"
+type: bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please provide a clear way to reproduce the issue.
+
+  - type: textarea
+    id: bug_description
+    attributes:
+      label: Description
+      description: What is the current (incorrect) behavior?
+      placeholder: e.g., "The message bubble overflows the container when a long URL is pasted."
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction_steps
+    attributes:
+      label: Steps to Reproduce
+      placeholder: |
+        1. Go to '...'
+        2. Enter '...' in the chat input
+        3. Observe the error
+    validations:
+      required: true
+
+  - type: textarea
+    id: data_context
+    attributes:
+      label: Data/JSON Context (if applicable)
+      description: Provide the message object or JSON that triggered the bug.
+      placeholder: |
+        {
+          "role": "assistant",
+          "content": "...",
+          "metadata": { ... }
+        }
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      placeholder: |
+        - PatternFly Chatbot Version:
+        - Browser & Version:
+        - Viewport size:
+    validations:
+      required: false
+
+  - type: textarea
+    id: visuals
+    attributes:
+      label: Screenshots or Logs
+      description: Drag and drop images or paste console errors here.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,81 @@
+name: Chatbot Feature Request
+description: Suggest a new component or extension specifically for the PatternFly Chatbot library.
+title: "[Chatbot] - [short description]"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ### AI & Conversational UX Proposal
+        Use this form for components like message bubbles, action footers, streaming indicators, or persona headers.
+
+  - type: dropdown
+    id: chatbot_category
+    attributes:
+      label: Chatbot Component Area
+      options:
+        - Message Content (Text, Markdown, Citations)
+        - Input/Action (Prompts, Attachments, Voice)
+        - Layout (Chat Drawer, Header, Persona)
+        - System (Loading, Error, Streaming)
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the feature
+      description: What is the specific chatbot interaction or UI component you are proposing?
+      placeholder: e.g., "A source citation component that appears below assistant responses."
+    validations:
+      required: true
+
+  - type: textarea
+    id: data_structure
+    attributes:
+      label: Expected Data Structure
+      description: Chatbot components often rely on specific JSON or object shapes. How should the data be passed?
+      placeholder: |
+        e.g.,
+        {
+          "source_id": 1,
+          "title": "Documentation",
+          "url": "..."
+        }
+    validations:
+      required: false
+
+  - type: textarea
+    id: interaction_flow
+    attributes:
+      label: Conversational Flow
+      description: How does this appear in the message stream? Does it support streaming?
+      placeholder: |
+        - Is it interactive (clickable)?
+        - Does it appear only in Assistant or User messages?
+        - How does it look while the message is still "typing" (streaming)?
+    validations:
+      required: false
+
+  - type: textarea
+    id: visuals
+    attributes:
+      label: Visuals & Mockups
+      description: Focus on how it integrates into the Chat Drawer or Window.
+      placeholder: "Figma links or screenshots go here."
+
+  - type: textarea
+    id: accessibility
+    attributes:
+      label: Conversational Accessibility
+      description: Focus on screen reader announcements for new messages or state changes.
+      placeholder: "e.g., Screen reader should announce when the 'Thought' block expands."
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Validation
+      options:
+        - label: This request aligns with PatternFly AI/Chatbot design guidelines.
+          required: true
+        - label: I have searched for existing chatbot-specific components.
+          required: true

packages/module/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,23 +310,23 @@ 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.
 
 <div class="ws-docs-content-img">
 ![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)

packages/module/patternfly-docs/content/extensions/chatbot/examples/Messages/BotMessage.tsx

@@ -319,6 +319,13 @@ _Italic text, formatted with single underscores_
         hasRoundAvatar={false}
       />
       <Message name="Bot" role="bot" content="This is a message from a bot with no avatar." />
+      <Message
+        name="Bot"
+        role="bot"
+        avatar={patternflyAvatar}
+        isMetadataVisible={false}
+        content="This is a message from a bot with metadata not visible."
+      />
       <Select
         id="single-select"
         isOpen={isOpen}

packages/module/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
+      }}
+    />
   </>
 );

packages/module/patternfly-docs/content/extensions/chatbot/examples/Messages/MessageWithIconSwapping.tsx

@@ -0,0 +1,22 @@
+import { FunctionComponent } from 'react';
+
+import Message from '@patternfly/chatbot/dist/dynamic/Message';
+import patternflyAvatar from './patternfly_avatar.jpg';
+
+export const IconSwappingExample: FunctionComponent = () => (
+  <Message
+    name="Bot"
+    role="bot"
+    avatar={patternflyAvatar}
+    content="Click the response actions to see the outlined icons swapped with the filled variants!"
+    actions={{
+      // eslint-disable-next-line no-console
+      positive: { onClick: () => console.log('Good response') },
+      // eslint-disable-next-line no-console
+      negative: { onClick: () => console.log('Bad response') },
+      // eslint-disable-next-line no-console
+      copy: { onClick: () => console.log('Copied') }
+    }}
+    useFilledIconsOnClick
+  />
+);