@patternfly/chatbot 2.2.0-prerelease.9 → 2.2.0

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

@@ -0,0 +1,219 @@
+---
+# Sidenav top-level section
+# should be the same for all markdown files
+section: PatternFly-AI
+subsection: ChatBot
+# Sidenav secondary level section
+# should be the same for all markdown files
+id: Analytics
+source: Analytics
+# Tab (react | react-demos | html | html-demos | design-guidelines | accessibility)
+# If you use typescript, the name of the interface to display props for
+# These are found through the sourceProps function provided in patternfly-docs.source.js
+sortValue: 60
+---
+
+import "../../images.css"
+
+To gain more insight into the ways that your users interact with your ChatBot, you can add support for **analytics**. To add analytics tracking, you can refer to this guide and configure tracking for the interactions you care about most.
+
+## Elements
+
+This following diagram shows the main components of ChatBot analytics tracking code, as well as the flow of information between components:
+
+<div class="ws-docs-content-img">
+![Main elements of the tracking code.](../../img/chatbot-analytics.svg)
+</div>
+
+The user code (1) first calls the static `getTrackingProviders()` method (3) which initializes the tracking providers (4). This returns an instance of the `trackingAPI` (2), which can then subsequently be used to emit analytics events.
+
+Note that user code only interacts with:
+
+- `trackingAPI` (including `identify`, `trackPageview`, `trackSingleItem`)
+- `TrackingRegistry` (including `getTrackingProviders`)
+
+## Usage
+
+### Setup
+
+1. Before you can use the `trackingAPI`, you must first supply the API keys of the respective providers.
+
+```nolive
+const initProps: InitProps = {
+  segmentKey: 'TODO-key', // TODO add your key here
+//  segmentCdn: 'https://my.org/cdn',  // Set up segment cdn (optional)
+//  segmentIntegrations: { // Provide Segment integrations (optional)
+//          'Segment.io': {
+//            apiHost: 'my.api.host/api/v1',
+//            protocol: 'https'
+//          }
+        },
+
+  posthogKey: 'TODO-key',
+  umamiKey: 'TODO-key',
+  umamiHostUrl: 'http://localhost:3000', // TODO where is your JS provider?
+  something: 'test',
+  console: 'true' // Console provider
+};
+```
+
+1. Once this is done, you can create an instance of the `trackingAPI` and start sending events.
+
+   ```nolive
+   const trackingAPI = getTrackingProviders(initProps);
+   ```
+
+1. One of your first events should identify the user in some way, such as a UUID that stays consistent for the same user.
+
+```nolive
+const trackingAPI = getTrackingProviders(initProps);
+trackingAPI.identify('user-123'); // TODO get real user id
+// Track the page that is currently visited. Best put into a react effect (see below)
+trackingAPI.trackPageView();
+// Track a single Event
+trackingAPI.trackSingleItem("MyEvent", { response: 'Good response' })
+```
+
+#### Tracking providers
+
+Only providers with a matching key in the `InitProps` will be started and used.
+
+```nolive
+const initProps: InitProps = {
+  segmentKey: 'TODO-key', // TODO add your key here
+  posthogKey: 'TODO-key',
+  umamiKey: 'TODO-key',
+  umamiHostUrl: 'http://localhost:3000', // TODO where is your JS provider?
+  console: true
+```
+
+##### Modifying providers
+
+If you know upfront that you only want to use 1 of the supported providers, you can modify `getTrackingProviders()` and remove all other providers in the providers array.
+
+When using the providers you need to add additional dependencies to your package.json file:
+
+```nolive
+"dependencies": {
+  "@segment/analytics-next": "^1.76.0",
+  "posthog-js": "^1.194.4"
+```
+
+##### Adding providers
+
+To add another analytics provider, you need to implement 2 interfaces, `TrackingSpi` and `trackingApi`.
+
+1. It is easiest to start by copying the `ConsoleTrackingProvider`
+1. The first thing you should do is to provide a correct value in `getKey()`
+1. Once you are happy enough with the implementation, add it to the array of providers in `getTrackingProviders()`
+
+### Page flow tracking
+
+To understand how users move through their ChatBot journey, you can track their page flow.
+
+To add tracking to each page view, use the `trackPageView()` method.
+
+```nolive
+import React from 'react';
+import { useLocation } from 'react-router-dom';
+
+export const useTrackPageFlow = (): void => {
+  const { pathname } = useLocation();
+
+  // notify url change events
+  React.useEffect(() => {
+    trackingAPI.trackPageView();
+  }, [pathname]);
+};
+```
+
+### Event tracking
+
+To get more specific insight into how users are interacting with the UI, you can track single events, including button clicks, form submissions, and so on.
+
+To add tracking to an interaction of your choice, use the `trackSingleItem` method.
+
+```nolive
+trackingAPI.trackSingleItem(eventName, propertyDict)
+```
+
+This method takes 2 parameters:
+
+- `eventName`: The unique name of the event. To differentiate different events that use the same name, you'll need to add an additional property.
+- `propertyDict`: A dict with key-value pairs that represent important properties of the event. If there are none, this value can be empty.
+
+#### Form submissions
+
+Only add tracking to the form itself, not the button that opens the form. You should track both successful and failed form submissions, as well as cancelled forms
+
+```nolive
+trackingAPI.trackSingleItem(Event_Name, {
+    outcome: << submit , cancel >>,
+    success? : boolean,
+    error? : string,
+    <properties>, string/number/boolean } )
+```
+
+Parameters to pass with the `trackSingleItem` method can include:
+
+- `outcome`: Communicates if the form was submitted or cancelled.
+- `success`: Used for a "submit" outcome to communicate if the submission was successful for not in the backend.
+- `error`: Used for a "submit" outcome to communicate the error message associated with a failed submission. Try to remove extraneous parts of the message, like part of a container-name.
+- `properties`: Any additional properties from the form, to be tracked for analytics.
+  - Use your judgement to determine what will be useful for your analytics.
+  - Highly specific data, like names provided by the user or description text input, should not be tracked.
+  - Less personal data, like deployment replica count or memory server size, is more likely to help you understand your users.
+
+## Examples
+
+To better understand the analytics tracking process, here are 3 examples of what you could see in an analytics tool.
+
+For all 3 tools, consider the following example, where the user has started a ChatBot and taken actions 1-5 in order:
+
+<div class="ws-docs-content-img" style="width:60%">
+![Events done in the ChatBot](../../img/analytics-example.svg)
+</div>
+
+1. Selected a model
+2. Sent a question
+3. Received a response from the model
+4. Clicked the "thumbs up" button
+5. Closed the ChatBot window
+
+This pattern of actions will be applied to the following 3 analytics tools.
+
+1. Segment
+
+   - [Segment](https://segment.com/) shows all user events in its source debugger:
+
+     <div class="ws-docs-content-img" style="width:70%">
+     ![Events displayed in the Segment debugger](../../img/segment.svg)
+     </div>
+
+     - 1-5: User actions with the newest event at the top.
+     - 6-7: You can also see the results of `identify` (6) and `trackPageView` (7).
+     - If you clicked on an event, you would also see the properties.
+
+   - **Note**: When using the Segment provider, you may also want to set the `segmentCdn` and `segmentIntegrations` initialization properties.
+
+1. Umami
+
+   - In [Umami](https://umami.is/), events are visible within **Website** / **Events**.
+   - The list is similar to Segment, with different formatting:
+
+     <div class="ws-docs-content-img">
+     ![Events in Umami](../../img/umami.svg)
+     </div>
+
+     - 1-5: User actions with the newest event at the top.
+
+1. PostHog
+
+   - In [PostHog](https://posthog.com/), events are located in the **Activity** section.
+   - PostHog integrates deeper in the provided code, so there are more default events tracked:
+
+     <div class="ws-docs-content-img">
+     ![Events in PostHog](../../img/posthog.svg)
+     </div>
+
+     - 1-5: User actions with the newest event at the top.

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

@@ -6,8 +6,8 @@ export const AttachmentErrorExample: React.FunctionComponent = () => (
     variant="danger"
     // eslint-disable-next-line no-console
     onClose={() => console.log('Clicked the close button')}
-    title="File upload failed"
+    title="Could not upload file"
   >
-    Your file size is too large. Please ensure that your file is less than 25 MB.
+    Your file size must be less than 25 MB.
   </ChatbotAlert>
 );

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

@@ -2,9 +2,43 @@ import React from 'react';
 import Message from '@patternfly/chatbot/dist/dynamic/Message';
 import patternflyAvatar from './patternfly_avatar.jpg';
 import squareImg from './PF-social-color-square.svg';
+import { AlertActionLink, Form, FormGroup, Radio } from '@patternfly/react-core';
 
 export const BotMessageExample: React.FunctionComponent = () => {
-  const markdown = `
+  const [variant, setVariant] = React.useState('code');
+
+  /* eslint-disable indent */
+  const renderContent = () => {
+    switch (variant) {
+      case 'code':
+        return code;
+      case 'heading':
+        return heading;
+      case 'emphasis':
+        return emphasis;
+      case 'blockQuotes':
+        return blockQuotes;
+      case 'orderedList':
+        return orderedList;
+      case 'unorderedList':
+        return unorderedList;
+      case 'moreComplexList':
+        return moreComplexList;
+      case 'inlineCode':
+        return inlineCode;
+      case 'link':
+        return link;
+      case 'table':
+        return table;
+      case 'image':
+        return image;
+      default:
+        return;
+    }
+  };
+  /* eslint-enable indent */
+
+  const code = `
 Here is some YAML code:
 
 ~~~yaml
@@ -35,6 +69,36 @@ export default MessageLoading;
 ~~~
 `;
 
+  const heading = `
+# h1 Heading
+
+## h2 Heading
+
+### h3 Heading
+
+#### h4 Heading
+
+##### h5 Heading
+
+###### h6 Heading
+`;
+
+  const emphasis = `
+**Bold text, formatted with double asterisks**
+
+__Bold text, formatted with double underscores__
+
+*Italic text, formatted with single asterisks*
+
+_Italic text, formatted with single underscores_
+
+~~Strikethrough~~
+`;
+
+  const blockQuotes = `> Blockquotes can also be nested...
+>> ...by using additional greater-than signs (>) right next to each other...
+> > > ...or with spaces between each sign.`;
+
   const orderedList = `
   Here is an ordered list:
 
@@ -53,43 +117,181 @@ export default MessageLoading;
 
 1. **Using a \`toaster\`:**
 
-   - Place \`bread\` in a \`toaster\`
-   - Once \`bread\` is lightly browned, remove from \`toaster\`
+   - Place \`bread\` in a \`toaster\`.
+   - Once \`bread\` is lightly browned, remove from \`toaster\`.
 
 2. **Using a \`knife\`:**
 
      Acquire 1 tablespoon of room temperature \`butter\`. Use \`knife\` to spread butter on \`toast\`. Bon appétit!
  `;
 
+  const link = `A paragraph with a URL: https://reactjs.org.`;
+
+  const inlineCode = `Here is an inline code - \`() => void\``;
+
+  const table = `To customize your table, you can use [PatternFly TableProps](/components/table#table)
+
+ | Version | GA date | User role 
+ |-|-|-|
+ | 2.5 | September 30, 2024 | Administrator |
+ | 2.5 | June 27, 2023 | Editor |
+ | 3.0 | April 1, 2025 | Administrator
+ `;
+
+  const image = `![Multi-colored wavy lines on a black background](https://cdn.dribbble.com/userupload/10651749/file/original-8a07b8e39d9e8bf002358c66fce1223e.gif)`;
+
+  const error = {
+    title: 'Could not load chat',
+    children: 'Wait a few minutes and check your network settings. If the issue persists: ',
+    actionLinks: (
+      <React.Fragment>
+        <AlertActionLink component="a" href="#">
+          Start a new chat
+        </AlertActionLink>
+        <AlertActionLink component="a" href="#">
+          Contact support
+        </AlertActionLink>
+      </React.Fragment>
+    )
+  };
+
   return (
     <>
-      <Message name="Bot" role="bot" avatar={patternflyAvatar} content={`Text-based message from a bot named "Bot"`} />
       <Message
         name="Bot"
         role="bot"
         avatar={patternflyAvatar}
-        content={`Text-based message from a bot named "Bot," with updated timestamp`}
+        content={`This is a text-based message from a bot named "Bot."`}
+      />
+      <Message
+        name="Bot"
+        role="bot"
+        avatar={patternflyAvatar}
+        content={`This is a text-based message from "Bot," with an updated timestamp.`}
         timestamp="1 hour ago"
       />
-      <Message name="Bot" role="bot" avatar={patternflyAvatar} content={markdown} />
-      <Message name="Bot" role="bot" avatar={patternflyAvatar} content={orderedList} />
-      <Message name="Bot" role="bot" avatar={patternflyAvatar} content={unorderedList} />
-      <Message name="Bot" role="bot" avatar={patternflyAvatar} content={moreComplexList} />
       <Message name="Bot" role="bot" avatar={patternflyAvatar} content="Example content" isLoading />
-      <Message role="bot" avatar={patternflyAvatar} content="Text-based message from a nameless bot" />
+      <Message role="bot" avatar={patternflyAvatar} content="This message is from a nameless bot." />
       <Message
         name="Default Openshift Container Platform Assistant That Can Help With Any Query You Might Need Help With"
         role="bot"
         avatar={patternflyAvatar}
-        content="Text-based message, where the bot's name is truncated"
+        content="This is a message from a bot with really long name: it's truncated!"
       />
       <Message
         name="Bot"
         role="bot"
         avatar={squareImg}
-        content="Text-based message from a bot with a square avatar. You can further customize the avatar by applying an additional class or passing [PatternFly avatar props](/components/avatar) to the `<Message>` component via `avatarProps`."
+        content="This bot has a square avatar. You can further customize the avatar by applying an additional class or passing [PatternFly avatar props](/components/avatar) to the `<Message>` component via `avatarProps`."
         hasRoundAvatar={false}
       />
+      <Message
+        name="Bot"
+        role="bot"
+        avatar={patternflyAvatar}
+        content={`Text-based message from a bot named "Bot," with updated timestamp`}
+        timestamp="1 hour ago"
+      />
+      <Message name="Bot" role="bot" avatar={patternflyAvatar} content="Example content" isLoading />
+
+      <Form>
+        <FormGroup role="radiogroup" isInline fieldId="bot-message-type" label="Message content type">
+          <Radio
+            isChecked={variant === 'code'}
+            onChange={() => setVariant('code')}
+            name="bot-message-type"
+            label="Code"
+            id="code"
+          />
+          <Radio
+            isChecked={variant === 'inlineCode'}
+            onChange={() => setVariant('inlineCode')}
+            name="bot-message-type"
+            label="Inline code"
+            id="inline-code"
+          />
+          <Radio
+            isChecked={variant === 'heading'}
+            onChange={() => setVariant('heading')}
+            name="bot-message-type"
+            label="Heading"
+            id="heading"
+          />
+          <Radio
+            isChecked={variant === 'blockQuotes'}
+            onChange={() => setVariant('blockQuotes')}
+            name="bot-message-type"
+            label="Block quote"
+            id="block-quotes"
+          />
+          <Radio
+            isChecked={variant === 'emphasis'}
+            onChange={() => setVariant('emphasis')}
+            name="bot-message-type"
+            label="Emphasis"
+            id="emphasis"
+          />
+          <Radio
+            isChecked={variant === 'link'}
+            onChange={() => setVariant('link')}
+            name="bot-message-type"
+            label="Link"
+            id="link"
+          />
+          <Radio
+            isChecked={variant === 'unorderedList'}
+            onChange={() => setVariant('unorderedList')}
+            name="bot-message-type"
+            label="Unordered list"
+            id="unordered-list"
+          />
+          <Radio
+            isChecked={variant === 'orderedList'}
+            onChange={() => setVariant('orderedList')}
+            name="bot-message-type"
+            label="Ordered list"
+            id="ordered-list"
+          />
+          <Radio
+            isChecked={variant === 'moreComplexList'}
+            onChange={() => setVariant('moreComplexList')}
+            name="bot-message-type"
+            label="More complex list"
+            id="more-complex-list"
+          />
+          <Radio
+            isChecked={variant === 'table'}
+            onChange={() => setVariant('table')}
+            name="bot-message-type"
+            label="Table"
+            id="table"
+          />
+          <Radio
+            isChecked={variant === 'image'}
+            onChange={() => setVariant('image')}
+            name="bot-message-type"
+            label="Image"
+            id="image"
+          />
+          <Radio
+            isChecked={variant === 'error'}
+            onChange={() => setVariant('error')}
+            name="bot-message-error"
+            label="Error"
+            id="error"
+          />
+        </FormGroup>
+      </Form>
+      <Message
+        name="Bot"
+        role="bot"
+        avatar={patternflyAvatar}
+        content={renderContent()}
+        tableProps={
+          variant === 'table' ? { 'aria-label': 'App information and user roles for bot messages' } : undefined
+        }
+        error={variant === 'error' ? error : undefined}
+      />
     </>
   );
 };

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

@@ -53,7 +53,8 @@ export const DropzoneExample: React.FunctionComponent = () => {
   return (
     <FileDropZone onFileDrop={handleFileDrop} displayMode="fullscreen">
       <div className="pf-chatbot__file-drop-zone-example">
-        Content that shows when no dragging is happening (drag an item here to see the drop zone)
+        This is example content that would be shown when no dragging is happening. To see the drop zone, start to drag
+        an item into this section. The static content will be replaced by an active drop zone message.
       </div>
     </FileDropZone>
   );

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

@@ -32,14 +32,14 @@ export const AttachmentMenuExample: React.FunctionComponent = () => {
         name="User"
         role="user"
         avatar={userAvatar}
-        content="Here is an uploaded file"
+        content="Here is an uploaded file:"
         attachments={[{ name: 'auth-operator.yml', id: '1', onClick, onClose }]}
       />
       <Message
         name="User"
         role="user"
         avatar={userAvatar}
-        content="Here are two uploaded files"
+        content="Here are 2 uploaded files:"
         attachments={[
           { name: 'auth-operator.yml', id: '1' },
           { name: 'patternfly.svg', id: '2' }

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

@@ -11,7 +11,7 @@ export const CustomActionExample: React.FunctionComponent = () => (
     name="Bot"
     role="bot"
     avatar={patternflyAvatar}
-    content="Example with custom actions"
+    content="I updated your account with those settings. You're ready to set up your first dashboard!"
     actions={{
       regenerate: {
         ariaLabel: 'Regenerate',

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

@@ -0,0 +1,71 @@
+import React from 'react';
+import Message from '@patternfly/chatbot/dist/dynamic/Message';
+import patternflyAvatar from './patternfly_avatar.jpg';
+import { Checkbox, FormGroup, Stack } from '@patternfly/react-core';
+
+export const MessageWithFeedbackExample: React.FunctionComponent = () => {
+  const [hasCloseButton, setHasCloseButton] = React.useState(false);
+  const [hasTextArea, setHasTextArea] = React.useState(false);
+
+  return (
+    <>
+      <Stack hasGutter>
+        <FormGroup role="radiogroup" isInline fieldId="feedback-card" label="Variant">
+          <Checkbox
+            isChecked={hasTextArea}
+            onChange={() => {
+              setHasTextArea(!hasTextArea);
+            }}
+            name="basic-inline-radio"
+            label="Has text area"
+            id="has-text-area"
+          />
+        </FormGroup>
+        <Message
+          name="Bot"
+          role="bot"
+          avatar={patternflyAvatar}
+          content="This is a message with the feedback card:"
+          userFeedbackForm={{
+            quickResponses: [
+              { id: '1', content: 'Helpful information' },
+              { id: '2', content: 'Easy to understand' },
+              { id: '3', content: 'Resolved my issue' }
+            ],
+            onSubmit: (quickResponse, additionalFeedback) =>
+              alert(`Selected ${quickResponse} and received the additional feedback: ${additionalFeedback}`),
+            hasTextArea,
+            // eslint-disable-next-line no-console
+            onClose: () => console.log('closed feedback form'),
+            focusOnLoad: false
+          }}
+        />
+      </Stack>
+      <Stack hasGutter>
+        <FormGroup role="radiogroup" isInline fieldId="feedback-thank-you" label="Variant">
+          <Checkbox
+            isChecked={hasCloseButton}
+            onChange={() => {
+              setHasCloseButton(!hasCloseButton);
+            }}
+            name="basic-inline-radio"
+            label="Has close button"
+            id="has-close"
+          />
+        </FormGroup>
+        <Message
+          name="Bot"
+          role="bot"
+          avatar={patternflyAvatar}
+          content="This is a thank-you message, which is displayed once the feedback card is submitted:"
+          // eslint-disable-next-line no-console
+          userFeedbackComplete={{
+            // eslint-disable-next-line no-console
+            onClose: hasCloseButton ? () => console.log('closed completion message') : undefined,
+            focusOnLoad: false
+          }}
+        />
+      </Stack>
+    </>
+  );
+};

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

@@ -0,0 +1,27 @@
+import React from 'react';
+import Message from '@patternfly/chatbot/dist/dynamic/Message';
+import patternflyAvatar from './patternfly_avatar.jpg';
+import { Button } from '@patternfly/react-core';
+
+export const MessageWithFeedbackTimeoutExample: React.FunctionComponent = () => {
+  const [hasFeedback, setHasFeedback] = React.useState(false);
+
+  return (
+    <>
+      <Button variant="secondary" onClick={() => setHasFeedback(true)}>
+        Show card
+      </Button>
+      <Button variant="secondary" onClick={() => setHasFeedback(false)}>
+        Remove card
+      </Button>
+      <Message
+        name="Bot"
+        role="bot"
+        avatar={patternflyAvatar}
+        content="This completion message times out after you click **Show card**:"
+        userFeedbackComplete={hasFeedback ? { timeout: true, onTimeout: () => setHasFeedback(false) } : undefined}
+        isLiveRegion
+      />
+    </>
+  );
+};

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

@@ -31,7 +31,7 @@ export const MessageWithQuickResponsesExample: React.FunctionComponent = () => (
       name="Bot"
       role="bot"
       avatar={patternflyAvatar}
-      content="Welcome back! How can I help?"
+      content="Welcome back, User! How can I help you today?"
       quickResponses={[
         { id: '1', content: 'Help me with an access issue', onClick: () => alert('Clicked id 1') },
         { id: '2', content: 'Show my critical vulnerabilities', onClick: () => alert('Clicked id 2') },

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

@@ -11,7 +11,7 @@ export const MessageWithQuickStartExample: React.FunctionComponent = () => (
       name="Bot"
       role="bot"
       avatar={patternflyAvatar}
-      content="Text-based bot message with a quick start tile."
+      content="Follow this quick guide to install the Pipelines Operator."
       quickStarts={{
         quickStart: explorePipelinesQuickStart as QuickStart,
         onSelectQuickStart: (id) => alert(id)
@@ -21,7 +21,7 @@ export const MessageWithQuickStartExample: React.FunctionComponent = () => (
       name="Bot"
       role="bot"
       avatar={patternflyAvatar}
-      content="Text-based bot message with a quick start tile that includes prerequisites and a default icon."
+      content="This quick start tile includes prerequisites and a default icon."
       quickStarts={{
         quickStart: monitorSampleAppQuickStart,
         onSelectQuickStart: (id) => alert(id)

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

@@ -8,7 +8,7 @@ export const ResponseActionExample: React.FunctionComponent = () => (
     name="Bot"
     role="bot"
     avatar={patternflyAvatar}
-    content="Example with all prebuilt actions"
+    content="I updated your account with those settings. You're ready to set up your first dashboard!"
     actions={{
       // eslint-disable-next-line no-console
       positive: { onClick: () => console.log('Good response') },