@gitlab/duo-ui 0.1.0

package/src/components/experimental/duo/chat/duo_chat.md

@@ -0,0 +1,194 @@
+The component represents the complete Duo Chat feature.
+
+The component provides a configurable chat UI interface. The primary use is communication with
+GitLab Duo, however, the component is BE-agnostic and can accept information from any source.
+
+## Usage
+
+To use the component in its simplest form, import it and add it to the `template` part of your
+consumer component.
+
+```html
+<gl-duo-chat
+  :title="title"
+  :messages="messages"
+  :error="error"
+  :is-loading="isLoading"
+  :is-chat-available="isChatAvailable"
+  :predefined-prompts="predefinedPrompts"
+  :badge-help-page-url="badgeHelpPageUrl"
+  :canceled-request-ids="cancelledRequestIds"
+  :tool-name="toolName"
+  :empty-state-title="emptyStateTitle"
+  :empty-state-description="emptyStateDescription"
+  :chat-prompt-placeholder="chatPromptPlaceholder"
+  :slash-commands="slashCommands"
+  @chat-hidden="onChatHidden"
+  @send-chat-prompt="onSendChatPrompt"
+  @track-feedback="onTrackFeedback"
+/>
+```
+
+## Integration
+
+To demonstrate how to connect this component to a backend implementation, let's consider its use
+for GitLab Duo. First, some general notes on the best practices and expectations when using this
+component.
+
+### Expected dependency injection
+
+To be universal, the component delegates some of its responsibilities to the consumer component.
+
+The component expects two function props:
+
+- `renderMarkdown`
+- `renderGFM`
+
+#### `renderMarkdown`
+
+This function prop converts plain Markdown text into HTML markup. To have a better understanding
+of what is expected from this function, take a look at
+[the existing GitLab example](https://gitlab.com/gitlab-org/gitlab/-/blob/774ecc1f2b15a581e8eab6441de33585c9691c82/app/assets/javascripts/notes/utils.js#L22-24).
+
+#### `renderGFM`
+
+This function prop extends the standard Markdown rendering with support for the
+[GitLab Flavored Markdown (GLFM)](https://docs.gitlab.com/ee/user/markdown.html). To
+have a better understanding of what is expected from this function, take a look at
+[the existing GitLab example](https://gitlab.com/gitlab-org/gitlab/-/blob/774ecc1f2b15a581e8eab6441de33585c9691c82/app/assets/javascripts/behaviors/markdown/render_gfm.js#L18-40).
+
+The reason to have two different functions for rendering Markdown is performance. `renderGFM`
+operates on a DOM node and might come with many additional mutations for the node's content.
+Such behavior suits a one-time update. However, Duo Chat also supports streaming of the AI
+responses (check the [Interactive story for this component](?path=/story/experimental-duo-chat-duo-chat--interactive))
+and, in this case, when the message is constantly updating, we rely on a more lightweight
+`renderMarkdown` to render the updated message faster.
+
+### Don't use reactivity where unnecessary
+
+The `GlDuoChat` component exposes many properties, as seen below. But not all of those should
+be necessarily reactive in the consumer component. The properties that might be static:
+
+- `title`. The title is shown in the head of the component.
+- `isChatAvailable`. The flag indicates whether the communication interface should allow follow-up
+  questions. Usually, this decision stays the same during the component's lifecycle.
+- `predefinedPrompts`. The `Array` of strings that represents the possible questions to ask when
+  there are no messages in the chat.
+- `badgeHelpPageUrl`. The link to an external page explaining the meaning of an "experiment".
+  The prop is passed down to the [`GlExperimentBadge` component](?path=/docs/experimental-experiment-badge--docs).
+- `emptyStateTitle`. Title of the empty state component. Visible when there are no messages.
+- `emptyStateDescription`. Description text of the empty state component. Visible when there are no messages.
+- `chatPromptPlaceholder`. Placeholder text for the chat prompt input.
+
+### Set up communication with consumer
+
+```javascript
+import { GlDuoChat } from '@gitlab/ui';
+
+export default {
+  ...
+  data() {
+    return {
+      messages: [],
+      error: null,
+      isLoading: false,
+      toolName: '',
+      cancelledRequestIds: []
+    }
+  },
+  provide: {
+    renderMarkdown: (content) => {
+      // implementation of the `renderMarkdown` functionality
+    },
+    renderGFM: (el) => {
+      // implementation of the `renderGFM` functionality
+    },
+  },
+  beforeCreate() {
+    // Here, we set up our non-reactive properties if we must change the default values
+    this.title = 'Foo Bar';
+    this.isChatAvailable = true; // this is just an example. `true` is the default value
+    this.predefinedPrompts = ['How to …?', 'Where do I …?'];
+    this.badgeHelpPageUrl = 'https://dev.null';
+    this.emptyStateTitle = 'Ask anything';
+    this.emptyStateDescription = 'You will see the answers below';
+    this.chatPromptPlaceholder = 'Type your question here';
+  }
+  methods: {
+    onChatCancel() {
+       // pushing last requestId of messages to canceled Request Ids
+      this.cancelledRequestIds.push(this.messages[this.messages.length - 1].requestId);
+      this.isLoading = false;
+    },
+    onChatHidden() {
+      ...
+    },
+    onSendChatPrompt(prompt = '') {
+      this.isLoading = true;
+      this.messages.push(constructUserMessage(prompt));
+      ...
+    },
+    onTrackFeedback(feedbackObj = {}) {
+      ...
+    },
+    onAiResponse(data) {
+      // check if requestId was not cancelled
+      if (requestId && !this.cancelledRequestIds.includes(data.requestId)) {
+        this.messages = data
+      }
+      …
+      this.isLoading = false;
+    },
+    onAiResponseError(error) {
+      this.error = error;
+      this.isLoading = false;
+    },
+    onToolNameChange(toolMessage) {
+      this.toolName = toolMessage.content;
+    }
+  }
+}
+```
+
+With this template in place, consumer is left with the following things to implement:
+
+- Fetch `messages`. For Duo Chat, we rely on GraphQL query to get the cached
+  messages and subscription to monitor new messages when:
+
+  - streaming response
+  - listening to chat messages in other tabs/environments
+  - listen to updates from different tools to update `toolName`
+
+- Send the new user's prompt. For Duo Chat, we rely on GraphQL mutation for this purpose.
+- Send user feedback to the telemetry of your choice when `track-feedback` event arrives.
+
+## Slash commands
+
+One of the props accepted by the component is the `slashCommands`. This is an `Array` of
+the commands, shown to user when they start typing the prompt with a slash (`/`)
+character.
+
+```javascript
+<script>
+  const slashCommands = [
+    {
+      name: '/mycommand', // This is the exact name of my command as it will be submitted
+      shouldSubmit: true, // If the command should be submitted right away without free text
+      description: 'The description of my super-duper command.',
+    },
+    ...
+  ];
+  export default {
+    ...
+    options: {
+      slashCommands
+    }
+  }
+<script>
+<template>
+  <gl-duo-chat
+    ...
+    :slash-commands="slashCommands"
+  />
+</template>
+```

package/src/components/experimental/duo/chat/duo_chat.scss

@@ -0,0 +1,168 @@
+$duo-chat-scrim-gradient: linear-gradient(to bottom, rgba($gray-10, 0), $gray-10);
+
+.duo-chat {
+  z-index: 999;
+
+  .message-enter-active,
+  .message-leave-active {
+    transition: all 0.5s ease;
+  }
+
+  .message-enter,
+  .message-leave-to {
+    @apply gl-opacity-0;
+    transform: translateY(10px);
+  }
+
+  .duo-chat-loader.message-leave,
+  .duo-chat-loader.message-leave-to {
+    transition: none;
+  }
+
+  .duo-chat-drawer-body-scrim-on-footer {
+    &::before {
+      background: $duo-chat-scrim-gradient;
+    }
+  }
+
+  .duo-chat-drawer-body {
+    overflow-y: auto;
+  }
+
+  .duo-chat-drawer-header,
+  .duo-chat-drawer-body > * {
+    @apply gl-p-5;
+  }
+}
+
+.duo-chat-drawer {
+  right: 0;
+  @apply gl-transition-all;
+  position: fixed;
+  @apply gl-h-full;
+  @apply gl-w-full;
+  @apply gl-overflow-y-auto;
+  @apply gl-shadow-lg;
+  @apply gl-text-base;
+  @apply gl-leading-normal;
+  @apply gl-flex;
+  @apply gl-flex-col;
+}
+
+.duo-chat-drawer-header {
+  @apply gl-border-b-solid gl-border-b-gray-100 gl-border-b-1;
+}
+
+.duo-chat-drawer-header-sticky {
+  top: 0;
+  position: sticky;
+  @apply gl-border-b-solid gl-border-b-gray-100 gl-border-b-1;
+}
+
+.duo-chat-drawer-body {
+  @apply gl-grow;
+  // prevent safari bug where box shadow is visible
+  // above the drawer when hovering interactive elements
+  // see https://gitlab.com/gitlab-org/gitlab/-/issues/366558
+  background-color: inherit;
+}
+
+.duo-chat-drawer-footer {
+  @apply gl-border-t-solid gl-border-t-gray-100 gl-border-t-1;
+  @apply gl-p-5;
+}
+
+.duo-chat-drawer-footer-sticky {
+  @apply gl-bg-white;
+  bottom: 0;
+  position: sticky;
+}
+
+.duo-chat-drawer-body-scrim-on-footer {
+  &::before {
+    background: $duo-chat-scrim-gradient;
+    top: -$gl-border-size-1;
+    @apply -gl-translate-y-full;
+    content: '';
+    left: 0;
+    position: absolute;
+    @apply gl-pointer-events-none;
+    @apply gl-w-full;
+    @apply gl-h-7;
+  }
+}
+
+.duo-chat-history {
+  scroll-behavior: smooth;
+
+  &.force-scroll-bar {
+    min-height: calc(100% + 1rem);
+  }
+
+  /*
+  Browsers a are pretty good at keeping the focus on an element while
+  the parent element grows in size. With this we mark all child elements
+  of the chat history as "non" anchors.
+  https://developer.mozilla.org/en-US/docs/Web/CSS/overflow-anchor
+  */
+  * {
+    overflow-anchor: none;
+  }
+
+  /*
+  Right at the bottom of the chat history we add a scroll-anchor element.
+  This scroll-anchor element is the only "possible" anchor. The beauty of it:
+  It only will be used as an anchor _if_ it is currently inside the view port.
+  So if the user manually scrolls up while a chunked message is coming in,
+  it won't stick to the bottom while the message still loads.
+  */
+  .scroll-anchor {
+    overflow-anchor: auto;
+    height: 1px;
+    margin-top: -1px; // In order to not add 1px vertically, we add a negative margin
+  }
+}
+
+.duo-chat-input {
+  @apply gl-flex;
+  @apply gl-flex-col;
+  max-height: 240px;
+  overflow: hidden;
+
+  &:focus-within {
+    @include gl-focus($color: $gray-900);
+  }
+
+  .gl-form-textarea.form-control {
+    flex: 1;
+    resize: none;
+    max-height: 240px;
+    padding-right: 40px;
+  }
+
+  &::after {
+    content: attr(data-value) ' ';
+    @apply gl-invisible;
+    @apply gl-whitespace-pre-wrap;
+    @apply gl-py-4;
+  }
+}
+
+.slash-commands {
+  @apply -gl-mt-2;
+
+  .active-command {
+    @apply gl-bg-gray-50;
+    @apply gl-rounded-base;
+  }
+
+  .gl-dropdown-item button.dropdown-item {
+    @apply gl-text-sm;
+    @apply gl-px-3;
+    @apply gl-bg-transparent;
+
+    &:hover {
+      @apply gl-bg-transparent;
+    }
+  }
+}