@gitlab/ui 66.32.1 → 66.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitlab/ui",
-  "version": "66.32.1",
+  "version": "66.34.0",
   "description": "GitLab UI Components",
   "license": "MIT",
   "main": "dist/index.js",

package/src/components/experimental/duo/chat/constants.js

@@ -1,3 +1,5 @@
+export const CHAT_RESET_MESSAGE = '/reset';
+
 export const LOADING_TRANSITION_DURATION = 7500;
 
 export const DOCUMENTATION_SOURCE_TYPES = {

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

@@ -0,0 +1,143 @@
+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"
+  :experiment-help-page-url="experimentHelpPageUrl"
+  :tool-name="toolName"
+  @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.
+- `experimentHelpPageUrl`. 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).
+
+### Set up communication with consumer
+
+```javascript
+import { GlDuoChat } from '@gitlab/ui';
+
+export default {
+  ...
+  data() {
+    return {
+      messages: [],
+      error: null,
+      isLoading: false,
+      toolName: '',
+    }
+  },
+  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.experimentHelpPageUrl = 'https://dev.null';
+  }
+  methods: {
+    onChatHidden() {
+      ...
+    },
+    onSendChatPrompt(prompt = '') {
+      this.isLoading = true;
+      this.messages.push(constructUserMessage(prompt));
+      ...
+    },
+    onTrackFeedback(feedbackObj = {}) {
+      ...
+    },
+    onAiResponse(data) {
+      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.

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

@@ -0,0 +1,50 @@
+.duo-chat {
+  z-index: 999;
+
+  .message-enter-active,
+  .message-leave-active {
+    transition: all 0.5s ease;
+  }
+
+  .message-enter,
+  .message-leave-to {
+    @include gl-opacity-0;
+    transform: translateY(10px);
+  }
+
+  .loader-enter-active,
+  .loader-leave-active {
+    transition: opacity 0.5s ease;
+  }
+
+  .loader-enter,
+  .loader-leave-to {
+    @include gl-opacity-0;
+  }
+
+  .loader-leave-active {
+    @include gl-absolute;
+  }
+
+  .gl-drawer-body-scrim-on-footer {
+    &::before {
+      background: linear-gradient(to bottom, rgba($gray-10, 0), $gray-10);
+    }
+  }
+}
+
+.duo-chat-input {
+  @include gl-display-flex;
+  @include gl-flex-direction-column;
+
+  &:focus-within {
+    @include gl-focus($color: $gray-900);
+  }
+
+  .gl-form-textarea.form-control {
+    flex: 1;
+    resize: none;
+    max-height: 240px;
+    width: calc(100% - 40px);
+  }
+}

package/src/components/experimental/duo/chat/duo_chat.spec.js

@@ -0,0 +1,391 @@
+import { nextTick } from 'vue';
+import { shallowMount } from '@vue/test-utils';
+import GlEmptyState from '../../../regions/empty_state/empty_state.vue';
+import GlExperimentBadge from '../../experiment_badge/experiment_badge.vue';
+import DuoChatLoader from './components/duo_chat_loader/duo_chat_loader.vue';
+import DuoChatPredefinedPrompts from './components/duo_chat_predefined_prompts/duo_chat_predefined_prompts.vue';
+import DuoChatConversation from './components/duo_chat_conversation/duo_chat_conversation.vue';
+import GlDuoChat from './duo_chat.vue';
+
+import { MESSAGE_MODEL_ROLES, CHAT_RESET_MESSAGE } from './constants';
+
+describe('GlDuoChat', () => {
+  let wrapper;
+
+  const createComponent = ({ propsData = {}, data = {}, slots = {} } = {}) => {
+    jest.spyOn(DuoChatLoader.methods, 'computeTransitionWidth').mockImplementation();
+
+    wrapper = shallowMount(GlDuoChat, {
+      propsData,
+      data() {
+        return {
+          ...data,
+        };
+      },
+      slots,
+      stubs: {
+        DuoChatLoader,
+      },
+    });
+  };
+
+  const findChatComponent = () => wrapper.find('[data-testid="chat-component"]');
+  const findCloseButton = () => wrapper.find('[data-testid="chat-close-button"]');
+  const findChatConversations = () => wrapper.findAllComponents(DuoChatConversation);
+  const findCustomLoader = () => wrapper.findComponent(DuoChatLoader);
+  const findError = () => wrapper.find('[data-testid="chat-error"]');
+  const findFooter = () => wrapper.find('[data-testid="chat-footer"]');
+  const findPromptForm = () => wrapper.find('[data-testid="chat-prompt-form"]');
+  const findGeneratedByAI = () => wrapper.find('[data-testid="chat-legal-warning"]');
+  const findBadge = () => wrapper.findComponent(GlExperimentBadge);
+  const findEmptyState = () => wrapper.findComponent(GlEmptyState);
+  const findPredefined = () => wrapper.findComponent(DuoChatPredefinedPrompts);
+  const findChatInput = () => wrapper.find('[data-testid="chat-prompt-input"]');
+  const findCloseChatButton = () => wrapper.find('[data-testid="chat-close-button"]');
+  const findLegalDisclaimer = () => wrapper.find('[data-testid="chat-legal-disclaimer"]');
+
+  beforeEach(() => {
+    createComponent();
+  });
+
+  const promptStr = 'foo';
+  const messages = [
+    {
+      role: MESSAGE_MODEL_ROLES.user,
+      content: promptStr,
+    },
+  ];
+
+  describe('rendering', () => {
+    it('does not fail if no messages are passed', () => {
+      createComponent({
+        propsData: { messages: null },
+      });
+      expect(findChatConversations()).toHaveLength(0);
+      expect(findEmptyState().exists()).toBe(true);
+    });
+
+    it.each`
+      desc                                  | component            | shouldRender
+      ${'renders root component'}           | ${findChatComponent} | ${true}
+      ${'renders experimental label'}       | ${findBadge}         | ${true}
+      ${'renders empty state'}              | ${findEmptyState}    | ${true}
+      ${'renders predefined prompts'}       | ${findPredefined}    | ${true}
+      ${'does not render loading skeleton'} | ${findCustomLoader}  | ${false}
+      ${'does not render chat error'}       | ${findError}         | ${false}
+      ${'does render chat input'}           | ${findChatInput}     | ${true}
+      ${'renders a generated by AI note'}   | ${findGeneratedByAI} | ${true}
+    `('$desc', ({ component, shouldRender }) => {
+      expect(component().exists()).toBe(shouldRender);
+    });
+
+    describe('when messages exist', () => {
+      it('scrolls to the bottom on load', async () => {
+        createComponent({ propsData: { messages } });
+        const { element } = findChatComponent();
+        jest.spyOn(element, 'scrollHeight', 'get').mockReturnValue(200);
+
+        await nextTick();
+
+        expect(element.scrollTop).toEqual(200);
+      });
+    });
+
+    describe('conversations', () => {
+      it('renders one conversation when no reset message is present', () => {
+        const newMessages = [
+          {
+            role: MESSAGE_MODEL_ROLES.user,
+            content: 'How are you?',
+          },
+          {
+            role: MESSAGE_MODEL_ROLES.assistant,
+            content: 'Great!',
+          },
+        ];
+        createComponent({ propsData: { messages: newMessages } });
+
+        expect(findChatConversations().length).toEqual(1);
+        expect(findChatConversations().at(0).props('showDelimiter')).toEqual(false);
+      });
+
+      it('does not render conversations when no message is present', () => {
+        createComponent({ propsData: { messages: [] } });
+
+        expect(findChatConversations().length).toEqual(0);
+      });
+
+      it('splits it up into multiple conversations when reset message is present', () => {
+        const newMessages = [
+          {
+            role: MESSAGE_MODEL_ROLES.user,
+            content: 'Message 1',
+          },
+          {
+            role: MESSAGE_MODEL_ROLES.assistant,
+            content: 'Great!',
+          },
+          {
+            role: MESSAGE_MODEL_ROLES.user,
+            content: CHAT_RESET_MESSAGE,
+          },
+        ];
+        createComponent({ propsData: { messages: newMessages } });
+
+        expect(findChatConversations().length).toEqual(2);
+        expect(findChatConversations().at(0).props('showDelimiter')).toEqual(false);
+        expect(findChatConversations().at(1).props('showDelimiter')).toEqual(true);
+      });
+    });
+
+    describe('slots', () => {
+      const slotContent = 'As Gregor Samsa awoke one morning from uneasy dreams';
+
+      it.each`
+        slot           | content        | isChatAvailable
+        ${'hero'}      | ${slotContent} | ${true}
+        ${'hero'}      | ${slotContent} | ${false}
+        ${'subheader'} | ${slotContent} | ${false}
+        ${'subheader'} | ${slotContent} | ${true}
+      `(
+        'renders the $content passed to the $slot slot when isChatAvailable is $isChatAvailable',
+        ({ slot, content, isChatAvailable }) => {
+          createComponent({
+            propsData: { isChatAvailable },
+            slots: { [slot]: content },
+          });
+          expect(wrapper.text()).toContain(content);
+        }
+      );
+    });
+
+    it('sets correct props on the Experiment badge', () => {
+      const experimentHelpPageUrl = 'https://foo.bar';
+      const containerId = 'chat-component';
+      createComponent({ propsData: { experimentHelpPageUrl } });
+      expect(findBadge().props('experimentHelpPageUrl')).toBe(experimentHelpPageUrl);
+      expect(findBadge().attributes('container-id')).toBe(containerId);
+    });
+  });
+
+  describe('chat', () => {
+    const clickSubmit = () =>
+      findPromptForm().vm.$emit('submit', {
+        preventDefault: jest.fn(),
+        stopPropagation: jest.fn(),
+      });
+
+    it('does render the prompt input by default', () => {
+      createComponent({ propsData: { messages } });
+      expect(findChatInput().exists()).toBe(true);
+    });
+
+    it('does not render the prompt input if `isChatAvailable` prop is `false`', () => {
+      createComponent({ propsData: { messages, isChatAvailable: false } });
+      expect(findChatInput().exists()).toBe(false);
+    });
+
+    it('renders the legal disclaimer if `isChatAvailable` prop is `true', () => {
+      createComponent({ propsData: { messages, isChatAvailable: true } });
+      expect(findLegalDisclaimer().exists()).toBe(true);
+    });
+
+    describe('submit', () => {
+      const ENTER = 'Enter';
+
+      it.each`
+        trigger                                                                            | event                         | action          | expectEmitted
+        ${() => clickSubmit()}                                                             | ${'Submit button click'}      | ${'submit'}     | ${[[promptStr]]}
+        ${() => findChatInput().trigger('keydown.enter', { code: ENTER })}                 | ${`Clicking ${ENTER}`}        | ${'submit'}     | ${[[promptStr]]}
+        ${() => findChatInput().trigger('keydown.enter', { code: ENTER, metaKey: true })}  | ${`Clicking ${ENTER} + ⌘`}    | ${'not submit'} | ${undefined}
+        ${() => findChatInput().trigger('keydown.enter', { code: ENTER, altKey: true })}   | ${`Clicking ${ENTER} + ⎇`}    | ${'not submit'} | ${undefined}
+        ${() => findChatInput().trigger('keydown.enter', { code: ENTER, shiftKey: true })} | ${`Clicking ${ENTER} + ⬆︎`}   | ${'not submit'} | ${undefined}
+        ${() => findChatInput().trigger('keydown.enter', { code: ENTER, ctrlKey: true })}  | ${`Clicking ${ENTER} + CTRL`} | ${'not submit'} | ${undefined}
+      `('$event should $action the prompt form', ({ trigger, expectEmitted } = {}) => {
+        createComponent({
+          propsData: { messages: [], isChatAvailable: true },
+          data: { prompt: promptStr },
+        });
+        trigger();
+        if (expectEmitted) {
+          expect(wrapper.emitted('send-chat-prompt')).toEqual(expectEmitted);
+        } else {
+          expect(wrapper.emitted('send-chat-prompt')).toBe(undefined);
+        }
+      });
+    });
+
+    describe('reset', () => {
+      it('emits the event with the reset prompt', () => {
+        createComponent({
+          propsData: { messages, isChatAvailable: true },
+          data: { prompt: CHAT_RESET_MESSAGE },
+        });
+        clickSubmit();
+
+        expect(wrapper.emitted('send-chat-prompt')).toEqual([[CHAT_RESET_MESSAGE]]);
+        expect(findChatConversations().length).toEqual(1);
+      });
+
+      it('reset does nothing when chat is loading', () => {
+        createComponent({
+          propsData: { messages, isChatAvailable: true, isLoading: true },
+          data: { prompt: CHAT_RESET_MESSAGE },
+        });
+        clickSubmit();
+
+        expect(wrapper.emitted('send-chat-prompt')).toBeUndefined();
+        expect(findChatConversations().length).toEqual(1);
+      });
+
+      it('reset does nothing when there are no messages', () => {
+        createComponent({
+          propsData: { messages: [], isChatAvailable: true },
+          data: { prompt: CHAT_RESET_MESSAGE },
+        });
+        clickSubmit();
+
+        expect(wrapper.emitted('send-chat-prompt')).toBeUndefined();
+        expect(findChatConversations().length).toEqual(0);
+      });
+
+      it('reset does nothing when last message was a reset message', () => {
+        const existingMessages = [
+          ...messages,
+          {
+            role: MESSAGE_MODEL_ROLES.user,
+            content: CHAT_RESET_MESSAGE,
+          },
+        ];
+        createComponent({
+          propsData: {
+            isLoading: false,
+            messages: existingMessages,
+            isChatAvailable: true,
+          },
+          data: { prompt: CHAT_RESET_MESSAGE },
+        });
+        clickSubmit();
+
+        expect(wrapper.emitted('send-chat-prompt')).toBeUndefined();
+
+        expect(findChatConversations().length).toEqual(2);
+        expect(findChatConversations().at(0).props('messages')).toEqual(messages);
+        expect(findChatConversations().at(1).props('messages')).toEqual([]);
+      });
+    });
+  });
+
+  describe('interaction', () => {
+    it('is hidden after the header button is clicked', async () => {
+      findCloseButton().vm.$emit('click');
+      await nextTick();
+      expect(findChatComponent().exists()).toBe(false);
+    });
+
+    it('resets the hidden status of the component on loading', async () => {
+      createComponent({ data: { isHidden: true } });
+      expect(findChatComponent().exists()).toBe(false);
+      // setProps is justified here because we are testing the component's
+      // reactive behavior which consistutes an exception
+      // See https://docs.gitlab.com/ee/development/fe_guide/style/vue.html#setting-component-state
+      wrapper.setProps({
+        isLoading: true,
+      });
+      await nextTick();
+      expect(findChatComponent().exists()).toBe(true);
+    });
+
+    it('resets the prompt when new messages are added', async () => {
+      const prompt = 'foo';
+      createComponent({ data: { prompt } });
+      expect(findChatInput().props('value')).toBe(prompt);
+      // setProps is justified here because we are testing the component's
+      // reactive behavior which consistutes an exception
+      // See https://docs.gitlab.com/ee/development/fe_guide/style/vue.html#setting-component-state
+      wrapper.setProps({
+        messages,
+      });
+      await nextTick();
+      expect(findChatInput().props('value')).toBe('');
+    });
+
+    it('renders custom loader when isLoading', () => {
+      createComponent({ propsData: { isLoading: true } });
+      expect(findCustomLoader().exists()).toBe(true);
+    });
+
+    it('renders alert if error', () => {
+      const errorMessage = 'Something went Wrong';
+      createComponent({ propsData: { error: errorMessage } });
+      expect(findError().text()).toBe(errorMessage);
+    });
+
+    it('hides the chat on button click and emits an event', async () => {
+      createComponent({ propsData: { messages } });
+      expect(findChatComponent().exists()).toBe(true);
+      findCloseChatButton().vm.$emit('click');
+      await nextTick();
+      expect(findChatComponent().exists()).toBe(false);
+      expect(wrapper.emitted('chat-hidden')).toBeDefined();
+    });
+
+    it('does not render the empty state when there are messages available', () => {
+      createComponent({ propsData: { messages } });
+      expect(findEmptyState().exists()).toBe(false);
+    });
+
+    describe('scrolling', () => {
+      let element;
+
+      beforeEach(() => {
+        createComponent({ propsData: { messages, isChatAvailable: true } });
+        element = findChatComponent().element;
+      });
+
+      it('when scrolling to the bottom it removes the scrim class', async () => {
+        jest.spyOn(element, 'scrollTop', 'get').mockReturnValue(100);
+        jest.spyOn(element, 'offsetHeight', 'get').mockReturnValue(100);
+        jest.spyOn(element, 'scrollHeight', 'get').mockReturnValue(200);
+
+        findChatComponent().trigger('scroll');
+
+        await nextTick();
+
+        expect(findFooter().classes()).not.toContain('gl-drawer-body-scrim-on-footer');
+      });
+
+      it('when scrolling up it adds the scrim class', async () => {
+        jest.spyOn(element, 'scrollTop', 'get').mockReturnValue(50);
+        jest.spyOn(element, 'offsetHeight', 'get').mockReturnValue(100);
+        jest.spyOn(element, 'scrollHeight', 'get').mockReturnValue(200);
+
+        findChatComponent().trigger('scroll');
+
+        await nextTick();
+
+        expect(findFooter().classes()).toContain('gl-drawer-body-scrim-on-footer');
+      });
+    });
+
+    describe('predefined prompts', () => {
+      const prompts = ['what is a fork'];
+
+      beforeEach(() => {
+        createComponent({ propsData: { predefinedPrompts: prompts } });
+      });
+
+      it('passes on predefined prompts', () => {
+        expect(findPredefined().props().prompts).toEqual(prompts);
+      });
+
+      it('listens to the click event and sends the predefined prompt', async () => {
+        findPredefined().vm.$emit('click', prompts[0]);
+
+        await nextTick();
+
+        expect(wrapper.emitted('send-chat-prompt')).toEqual([[prompts[0]]]);
+      });
+    });
+  });
+});