@patternfly/chatbot 1.0.0

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

@@ -0,0 +1,223 @@
+---
+# Sidenav top-level section
+# should be the same for all markdown files
+section: extensions
+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. To enable a provider, it must be added to the `activeProviders` property:
+
+```nolive
+const initProps: InitProps = {
+  verbose: false,
+  activeProviders: ['Segment', 'Umami', 'Posthog', 'Console' ], 
+  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-umami-key',
+  umamiHostUrl: 'http://localhost:3000', // TODO where is your JS provider?
+  'umami-data-domains': 'TODO umami data domain',
+  something: 'test',
+};
+```
+
+- **Note:** To enable output debugging via the web-browser console, set the `verbose` key to `true`. By default, this is set to `false`.
+
+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 entry in the `InitProps.activeProviders` array will be started and used.
+
+Possible values are:
+* Umami
+* Posthog
+* Segment
+* Console
+
+
+##### 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 might need to add additional dependencies to your package.json file:
+
+```nolive
+"dependencies": {
+  "@segment/analytics-next": "^1.76.0",
+  "posthog-js": "^1.194.4"
+```
+
+Depending on your local setup, this might not be necessary. For example, if you pull the ChatBot codebase as a dependency into your project, you don't need to add it as an additional dependency in your package.json.
+
+##### 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. Add an entry for your new provider to the `Providers` enum in `tracking_spi.ts`
+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/Customizing Messages/Customizing Messages.md

@@ -0,0 +1,51 @@
+---
+# Sidenav top-level section
+# should be the same for all markdown files
+section: extensions
+subsection: ChatBot
+# Sidenav secondary level section
+# should be the same for all markdown files
+id: Customizing messages
+source: Customizing messages
+# 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
+---
+
+## Modifying static content
+
+The ChatBot extension `<Message>` component transforms Markdown to PatternFly React components via [react-markdown](https://github.com/remarkjs/react-markdown), which supports both [rehype](https://unifiedjs.com/explore/package/rehype/) and [remark](https://unifiedjs.com/explore/package/remark/) plugins for further output customization.
+
+remark parses Markdown as input and serializes Markdown as output, while rehype does the same for HTML. This allows you to target and make transformations at specific checkpoints in the transformation process: either while the text tree is still in Markdown, or while the text tree is in HTML format. For more detailed information on the architecture of this library, see the [react-markdown documentation](https://github.com/remarkjs/react-markdown?tab=readme-ov-file#architecture).
+
+You may need these plugins if, for example, you wanted to change the `href` on a link based on the link text. The `<Message>` prop `rehypePlugins` will accept any custom rehype plugins. We use already use these plugins in ChatBot to [render images a certain way](https://www.npmjs.com/package/rehype-unwrap-images) and [handle external links](https://www.npmjs.com/package/rehype-external-links).
+
+There are many open source libraries available for other common customization needs. If you can't find one for your use case, [Unified](https://unifiedjs.com/) has a helpful [guide on creating custom plugins](https://unifiedjs.com/learn/guide/create-a-rehype-plugin/).
+For a more direct example, if we wanted to change the `href` on links that included the text string `react`, we could write a very basic plugin like this:
+
+```
+import { visit } from 'unist-util-visit';
+
+export const rehypeLinkHrefUpdater = (options) => (tree) => {
+  visit(tree, 'element', (node) => {
+    if (node.tagName === 'a' && node.properties) {
+      if (node.properties.href.includes('react')) {
+        node.properties.href = '#';
+      }
+    }
+  });
+};
+
+```
+
+You could then pass `[rehypeLinkHrefUpdater]` to the `additionalRehypePlugins` prop on `<Message>` to have this applied to all relevant links read by that `<Message>` component.
+
+## Modifying dynamic content
+
+Props can also be used to modify dynamic content in messages.
+
+Continuing with our link modification example, let's say you also wanted to add custom `onClick` events. In this case, you would not use `remark` or `rehype`, since they're for static tree manipulation.
+
+Instead, you can utilize ChatBot features to customize dynamic content. We offer many `<Message>` props that allow you to implement custom behavior.
+For example, you can use `linkProps` to pass `onClick` events and other PatternFly `<Button>` props down to links. A very basic example would be `linkProps={{onClick: (event) => console.log(event}}`, which would apply to every link in the `<Message>`. Or, you could use the `event.target`, adding your own custom `onClick` logic based on the `innerText`, `innerHTML`, or other attributes of the `event.target`.

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

@@ -0,0 +1,149 @@
+import { useState, isValidElement, cloneElement, Children, FunctionComponent, ReactNode } from 'react';
+import AttachMenu from '@patternfly/chatbot/dist/dynamic/AttachMenu';
+import SourceDetailsMenuItem from '@patternfly/chatbot/dist/dynamic/SourceDetailsMenuItem';
+import { Button, Divider, DropdownGroup, DropdownItem, DropdownList } from '@patternfly/react-core';
+import { BellIcon, CodeIcon, ClipboardIcon, CalendarAltIcon, UploadIcon } from '@patternfly/react-icons';
+import PaperclipIcon from './PaperclipIcon';
+
+const initialMenuItems = [
+  <DropdownList key="list-1">
+    <DropdownItem className="pf-chatbot-source-details-dropdown-item" value="auth-operator Pod" id="0">
+      <SourceDetailsMenuItem
+        icon={
+          <svg width="24" height="25" viewBox="0 0 24 25" fill="none" xmlns="http://www.w3.org/2000/svg">
+            <path
+              d="M0 12.5C0 5.87258 5.37258 0.5 12 0.5C18.6274 0.5 24 5.87258 24 12.5C24 19.1274 18.6274 24.5 12 24.5C5.37258 24.5 0 19.1274 0 12.5Z"
+              fill="currentColor"
+            />
+            <g clipPath="url(#clip0_3280_27488)">
+              <path
+                d="M8.25 8.75C8.25 7.92266 8.92266 7.25 9.75 7.25H12C14.0719 7.25 15.75 8.92812 15.75 11C15.75 13.0719 14.0719 14.75 12 14.75H9.75V17C9.75 17.4148 9.41484 17.75 9 17.75C8.58516 17.75 8.25 17.4148 8.25 17V14V8.75ZM9.75 13.25H12C13.2422 13.25 14.25 12.2422 14.25 11C14.25 9.75781 13.2422 8.75 12 8.75H9.75V13.25Z"
+                fill="white"
+              />
+            </g>
+            <defs>
+              <clipPath id="clip0_3280_27488">
+                <rect width="7.5" height="12" fill="white" transform="translate(8.25 6.5)" />
+              </clipPath>
+            </defs>
+          </svg>
+        }
+        name="auth-operator"
+        type="Pod"
+      />
+    </DropdownItem>
+  </DropdownList>,
+  <DropdownGroup key="group2">
+    <DropdownList>
+      <DropdownItem value="Alerts" id="1" icon={<BellIcon />}>
+        Alerts
+      </DropdownItem>
+      <DropdownItem value="Events" id="2" icon={<CalendarAltIcon />}>
+        Events
+      </DropdownItem>
+      <DropdownItem value="Logs" id="3" icon={<ClipboardIcon />}>
+        Logs
+      </DropdownItem>
+      <DropdownItem value="YAML - Status" id="4" icon={<CodeIcon />}>
+        YAML - Status
+      </DropdownItem>
+      <DropdownItem value="YAML - All contents" id="5" icon={<CodeIcon />}>
+        YAML - All contents
+      </DropdownItem>
+    </DropdownList>
+  </DropdownGroup>
+];
+
+const uploadMenuItems = [
+  <Divider key="divider" />,
+  <DropdownList key="list-2">
+    <DropdownItem key="upload" value="upload" id="upload" icon={<UploadIcon />}>
+      Upload from computer
+    </DropdownItem>
+  </DropdownList>
+];
+
+export const AttachmentMenuExample: FunctionComponent = () => {
+  const [isOpen, setIsOpen] = useState<boolean>(false);
+  const [userFacingMenuItems, setUserFacingMenuItems] = useState<ReactNode>([]);
+
+  const onToggleClick = () => {
+    setIsOpen(!isOpen);
+    setUserFacingMenuItems(initialMenuItems.concat(uploadMenuItems));
+  };
+
+  const findMatchingElements = (elements: ReactNode[], targetValue: string) => {
+    let matchingElements = [] as ReactNode[];
+
+    elements.forEach((element) => {
+      if (isValidElement(element)) {
+        // Check if the element's value matches the targetValue
+        if (element.props.value && element.props.value.toLowerCase().includes(targetValue.toLowerCase())) {
+          matchingElements.push(cloneElement(element, { key: element.props.value }));
+        }
+
+        // Recursively check the element's children
+        const children = Children.toArray(element.props.children);
+        matchingElements = matchingElements.concat(findMatchingElements(children, targetValue));
+      }
+    });
+
+    return matchingElements;
+  };
+
+  const onTextChange = (textValue: string) => {
+    if (textValue === '') {
+      setUserFacingMenuItems(initialMenuItems.concat(uploadMenuItems));
+      return;
+    }
+
+    const newMenuItems = findMatchingElements(initialMenuItems, textValue);
+    // this is necessary because the React nodes we find traversing the recursive search
+    // aren't correctly wrapped in a DropdownList. This leads to problems with the
+    // auth-operator item where it winds up floating in a bad place in the DOM and never
+    // gets removed
+    setUserFacingMenuItems(
+      <>
+        <DropdownList>
+          {newMenuItems.length === 0 ? (
+            <DropdownItem key="no-items">No results found</DropdownItem>
+          ) : (
+            newMenuItems.map((item) => item)
+          )}
+        </DropdownList>
+        {uploadMenuItems.map((item) => item)}
+      </>
+    );
+  };
+
+  return (
+    <AttachMenu
+      filteredItems={userFacingMenuItems}
+      isOpen={isOpen}
+      onOpenChange={(isOpen) => setIsOpen(isOpen)}
+      onOpenChangeKeys={['Escape']}
+      // eslint-disable-next-line no-console
+      onSelect={(_ev, value) => console.log('selected', value)}
+      handleTextInputChange={onTextChange}
+      popperProps={{ direction: 'up', distance: 8 }}
+      searchInputPlaceholder="Search cluster resources..."
+      toggle={(toggleRef) => (
+        <Button
+          style={{
+            alignItems: 'center',
+            borderRadius: '50%',
+            display: 'flex',
+            height: '48px',
+            justifyContent: 'center',
+            padding: '0',
+            width: '48px',
+            lineHeight: '1rem'
+          }}
+          ref={toggleRef}
+          onClick={onToggleClick}
+          icon={<img src={PaperclipIcon} alt="Add an attachment" />}
+        />
+      )}
+    />
+  );
+};

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

@@ -0,0 +1,35 @@
+import { FunctionComponent, MouseEvent as ReactMouseEvent, useState } from 'react';
+import { Button, Checkbox } from '@patternfly/react-core';
+import { AttachmentEdit } from '@patternfly/chatbot/dist/dynamic/AttachmentEdit';
+
+export const AttachmentEditModalExample: FunctionComponent = () => {
+  const [isModalOpen, setIsModalOpen] = useState(false);
+  const [isCompact, setIsCompact] = useState(false);
+
+  const handleModalToggle = (_event: ReactMouseEvent | MouseEvent | KeyboardEvent) => {
+    setIsModalOpen(!isModalOpen);
+  };
+
+  return (
+    <>
+      <Checkbox
+        label="Show compact version"
+        isChecked={isCompact}
+        onChange={() => setIsCompact(!isCompact)}
+        id="modal-compact-edit"
+        name="modal-compact-edit"
+      ></Checkbox>
+      <Button onClick={handleModalToggle}>Launch attachment edit modal</Button>
+      <AttachmentEdit
+        code="I am a code snippet"
+        fileName="test.yaml"
+        handleModalToggle={handleModalToggle}
+        isModalOpen={isModalOpen}
+        onCancel={() => null}
+        // eslint-disable-next-line no-console
+        onSave={(_event, code) => console.log(`The new code is "${code}"`)}
+        isCompact={isCompact}
+      />
+    </>
+  );
+};

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

@@ -0,0 +1,13 @@
+import { FunctionComponent } from 'react';
+import ChatbotAlert from '@patternfly/chatbot/dist/dynamic/ChatbotAlert';
+
+export const AttachmentErrorExample: FunctionComponent = () => (
+  <ChatbotAlert
+    variant="danger"
+    // eslint-disable-next-line no-console
+    onClose={() => console.log('Clicked the close button')}
+    title="Could not upload file"
+  >
+    Your file size must be less than 25 MB.
+  </ChatbotAlert>
+);