@gitlab/ui 39.3.0 → 39.4.0

package/src/components/base/new_dropdowns/base_dropdown/base_dropdown.vue

@@ -0,0 +1,221 @@
+<script>
+import { createPopper } from '@popperjs/core';
+import {
+  buttonCategoryOptions,
+  buttonSizeOptions,
+  dropdownVariantOptions,
+} from '../../../../utils/constants';
+import { POPPER_CONFIG, GL_DROPDOWN_SHOWN, GL_DROPDOWN_HIDDEN } from '../constants';
+
+import GlButton from '../../button/button.vue';
+import GlIcon from '../../icon/icon.vue';
+import { OutsideDirective } from '../../../../directives/outside/outside';
+
+export default {
+  components: {
+    GlButton,
+    GlIcon,
+  },
+  directives: { Outside: OutsideDirective },
+  props: {
+    toggleText: {
+      type: String,
+      required: false,
+      default: '',
+    },
+    textSrOnly: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    category: {
+      type: String,
+      required: false,
+      default: buttonCategoryOptions.primary,
+      validator: (value) => Object.keys(buttonCategoryOptions).includes(value),
+    },
+    variant: {
+      type: String,
+      required: false,
+      default: dropdownVariantOptions.default,
+      validator: (value) => Object.keys(dropdownVariantOptions).includes(value),
+    },
+    size: {
+      type: String,
+      required: false,
+      default: buttonSizeOptions.medium,
+      validator: (value) => Object.keys(buttonSizeOptions).includes(value),
+    },
+    icon: {
+      type: String,
+      required: false,
+      default: '',
+    },
+    disabled: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    loading: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    toggleClass: {
+      type: [String, Array, Object],
+      required: false,
+      default: null,
+    },
+    noCaret: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    /**
+     * Right align dropdown menu with respect to the toggle button
+     */
+    right: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    // ARIA props
+    ariaHaspopup: {
+      type: [String, Boolean],
+      required: false,
+      default: false,
+      validator: (value) => {
+        return ['menu', 'listbox', 'tree', 'grid', 'dialog', true, false].includes(value);
+      },
+    },
+    /**
+     * Id that will be referenced by `aria-labelledby` attribute of the dropdown content`
+     */
+    toggleId: {
+      type: String,
+      required: true,
+    },
+    /**
+     * The `aria-labelledby` attribute value for the  toggle `button`
+     */
+    ariaLabelledby: {
+      type: String,
+      required: false,
+      default: null,
+    },
+  },
+  data() {
+    return {
+      visible: false,
+    };
+  },
+  computed: {
+    isIconOnly() {
+      return Boolean(this.icon && (!this.toggleText?.length || this.textSrOnly));
+    },
+    isIconWithText() {
+      return Boolean(this.icon && this.toggleText?.length && !this.textSrOnly);
+    },
+    toggleButtonClasses() {
+      return [
+        this.toggleClass,
+        {
+          'gl-dropdown-toggle': true,
+          'dropdown-toggle': true,
+          'dropdown-icon-only': this.isIconOnly,
+          'dropdown-icon-text': this.isIconWithText,
+          'dropdown-toggle-no-caret': this.noCaret,
+        },
+      ];
+    },
+    toggleLabelledBy() {
+      return this.ariaLabelledby ? `${this.ariaLabelledby} ${this.toggleId}` : this.toggleId;
+    },
+    popperConfig() {
+      return {
+        placement: this.right ? 'bottom-end' : 'bottom-start',
+        ...POPPER_CONFIG,
+      };
+    },
+  },
+  updated() {
+    if (this.visible) {
+      this.popper?.update();
+    }
+  },
+  mounted() {
+    this.$nextTick(() => {
+      this.popper = createPopper(this.$refs.toggle.$el, this.$refs.content, this.popperConfig);
+    });
+  },
+  beforeDestroy() {
+    this.popper.destroy();
+  },
+  methods: {
+    toggle() {
+      this.visible = !this.visible;
+
+      if (this.visible) {
+        this.popper.update();
+        this.$emit(GL_DROPDOWN_SHOWN);
+      } else {
+        this.$emit(GL_DROPDOWN_HIDDEN);
+      }
+    },
+    close() {
+      if (!this.visible) {
+        return;
+      }
+      this.toggle();
+    },
+    closeAndFocus() {
+      if (!this.visible) {
+        return;
+      }
+      this.toggle();
+      this.focusToggle();
+    },
+    focusToggle() {
+      this.$refs.toggle.$el.focus();
+    },
+  },
+};
+</script>
+
+<template>
+  <div v-outside="close" class="gl-new-dropdown dropdown btn-group">
+    <gl-button
+      :id="toggleId"
+      ref="toggle"
+      data-testid="base-dropdown-toggle"
+      :icon="icon"
+      :category="category"
+      :variant="variant"
+      :size="size"
+      :disabled="disabled"
+      :loading="loading"
+      :class="toggleButtonClasses"
+      :aria-haspopup="ariaHaspopup"
+      :aria-expanded="visible"
+      :aria-labelledby="toggleLabelledBy"
+      @click="toggle"
+    >
+      <span class="gl-new-dropdown-button-text" :class="{ 'gl-sr-only': textSrOnly }">
+        {{ toggleText }}
+      </span>
+      <gl-icon v-if="!noCaret" class="gl-button-icon dropdown-chevron" name="chevron-down" />
+    </gl-button>
+
+    <div
+      ref="content"
+      data-testid="base-dropdown-menu"
+      class="dropdown-menu"
+      :class="{ show: visible }"
+      @keydown.esc.stop.prevent="closeAndFocus"
+    >
+      <div class="gl-new-dropdown-inner">
+        <slot></slot>
+      </div>
+    </div>
+  </div>
+</template>

package/src/components/base/new_dropdowns/constants.js

@@ -0,0 +1,22 @@
+export const POPPER_CONFIG = {
+  modifiers: [
+    {
+      name: 'offset',
+      options: {
+        offset: [0, 4],
+      },
+    },
+  ],
+};
+
+// base dropdown events
+export const GL_DROPDOWN_SHOWN = 'shown';
+export const GL_DROPDOWN_HIDDEN = 'hidden';
+
+// KEY Codes
+export const HOME = 'Home';
+export const END = 'End';
+export const ARROW_UP = 'ArrowUp';
+export const ARROW_DOWN = 'ArrowDown';
+export const ENTER = 'Enter';
+export const SPACE = 'Space';

package/src/components/base/new_dropdowns/listbox/listbox.md

@@ -0,0 +1,71 @@
+A listbox dropdown is a button that toggles a panel containing a list of options.
+Listbox supports single and multi-selection.
+
+**Single-select:** By default, selecting an option will update the toggle label with the choice.
+But the custom toggle text can be provided.
+When option is selected, the dropdown will be closed and focus set on the toggle button.
+
+**Multi-select:** Selecting an option will not update the toggle, but it can be customized
+providing `toggleText` property. Also, selecting or deselecting an item won't close the dropdown.
+
+### Icon-only listbox
+
+Icon-only listboxes must have an accessible name.
+You can provide this with the combination of `toggleText` and `textSrOnly` props.
+For single-select listboxes `toggleText` will be set to the selected item's `text` property value
+by default.
+
+Optionally, you can use `no-caret` to remove the caret and `category="tertiary"` to remove the border.
+
+```html
+<gl-listbox
+  icon="ellipsis_v"
+  toggle-text="More options"
+  text-sr-only
+  category="tertiary"
+  no-caret
+>
+```
+
+### Opening the listbox
+
+Listbox will open on toggle button click (if it was previously closed).
+On open, `GlListbox` will emit the `shown` event.
+
+### Closing the listbox
+
+The listbox is closed by any of the following:
+
+- pressing <kbd>Esc</kbd>
+- clicking anywhere outside the component
+- selecting an option in single-select mode
+
+After closing, `GlListbox` emits a `hidden` event.
+
+### Selecting items
+
+Set the `v-model` on the listbox to have 2-way data binding for the selected items in the listbox.
+Alternatively, you can set `selected` property to the array of selected items
+`value` properties (for multi-select) or to the selected item `value` property for a single-select.
+On selection the listbox will emit the `select` event with the selected values.
+
+### Setting listbox options
+
+Provide the list of options for the listbox - each item in the array should have `value` property.
+It is used as a primary key.
+To render the default listbox item template, the item should also have `text` property.
+If you want to use custom template for rendering the listbox item, use the `list-item` template.
+
+```html
+<gl-listbox :items="items">
+    <template #list-item="{ item }">
+        <span class="gl-display-flex gl-align-items-center">
+            <gl-avatar :size="32" class-="gl-mr-3"/>
+            <span class="gl-display-flex gl-flex-direction-column">
+              <span class="gl-font-weight-bold gl-white-space-nowrap">{{ item.text }}</span>
+              <span class="gl-text-gray-400"> {{ item.secondaryText }}</span>
+            </span>
+          </span>
+      </template>
+</gl-litsbox>
+```

package/src/components/base/new_dropdowns/listbox/listbox.spec.js

@@ -0,0 +1,236 @@
+import { mount } from '@vue/test-utils';
+import { nextTick } from 'vue';
+import GlBaseDropdown from '../base_dropdown/base_dropdown.vue';
+import {
+  GL_DROPDOWN_SHOWN,
+  GL_DROPDOWN_HIDDEN,
+  ARROW_DOWN,
+  ARROW_UP,
+  HOME,
+  END,
+} from '../constants';
+import GlListbox, { ITEM_SELECTOR } from './listbox.vue';
+import GlListboxItem from './listbox_item.vue';
+
+const mockItems = [
+  {
+    value: 'eng',
+    text: 'Engineering',
+  },
+  {
+    value: 'sales',
+    text: 'Sales',
+  },
+  {
+    value: 'marketing',
+    text: 'Marketing',
+  },
+];
+
+describe('GlListbox', () => {
+  let wrapper;
+
+  const buildWrapper = (propsData, slots = {}) => {
+    wrapper = mount(GlListbox, {
+      propsData,
+      slots,
+      attachTo: document.body,
+    });
+  };
+
+  const findBaseDropdown = () => wrapper.findComponent(GlBaseDropdown);
+  const findListContainer = () => wrapper.find('[role="listbox"]');
+  const findListboxItems = () => wrapper.findAllComponents(GlListboxItem);
+  const findListItem = (index) => findListboxItems().at(index).find(ITEM_SELECTOR);
+
+  describe('toggle text', () => {
+    describe.each`
+      toggleText          | multiple | selected                | expectedToggleText
+      ${'Toggle caption'} | ${true}  | ${[mockItems[0].value]} | ${'Toggle caption'}
+      ${''}               | ${true}  | ${[mockItems[0]].value} | ${''}
+      ${''}               | ${false} | ${mockItems[0].value}   | ${mockItems[0].text}
+      ${''}               | ${false} | ${''}                   | ${''}
+    `('when listbox', ({ toggleText, multiple, selected, expectedToggleText }) => {
+      beforeEach(() => {
+        buildWrapper({ items: mockItems, toggleText, multiple, selected });
+      });
+
+      it(`is ${multiple ? 'multi' : 'single'}-select, toggleText is ${
+        toggleText.length ? '' : 'not '
+      }provided and ${selected ? 'has' : 'does not have'} selected`, () => {
+        expect(findBaseDropdown().props('toggleText')).toBe(expectedToggleText);
+      });
+    });
+  });
+
+  describe('ARIA attributes', () => {
+    it('should provide `toggleId` to the base dropdown and reference it in`aria-labelledby` attribute of the list container` ', async () => {
+      await buildWrapper();
+      expect(findBaseDropdown().props('toggleId')).toBe(
+        findListContainer().attributes('aria-labelledby')
+      );
+    });
+  });
+
+  describe('selecting items', () => {
+    describe('multi-select', () => {
+      beforeEach(() => {
+        buildWrapper({
+          multiple: true,
+          selected: [mockItems[1].value, mockItems[2].value],
+          items: mockItems,
+        });
+      });
+
+      it('should render items as selected when `selected` provided ', () => {
+        expect(findListboxItems().at(1).props('isSelected')).toBe(true);
+        expect(findListboxItems().at(2).props('isSelected')).toBe(true);
+      });
+
+      it('should deselect previously selected', async () => {
+        findListboxItems().at(1).vm.$emit('select', false);
+        await nextTick();
+        expect(wrapper.emitted('select')[0][0]).toEqual([mockItems[2].value]);
+      });
+
+      it('should add to selection', async () => {
+        findListboxItems().at(0).vm.$emit('select', true);
+        await nextTick();
+        expect(wrapper.emitted('select')[0][0]).toEqual(
+          expect.arrayContaining(mockItems.map(({ value }) => value))
+        );
+      });
+    });
+
+    describe('single-select', () => {
+      beforeEach(() => {
+        buildWrapper({ selected: mockItems[1].value, items: mockItems });
+      });
+
+      it('should throw an error when array of selections is provided', () => {
+        expect(() => {
+          buildWrapper({
+            selected: [mockItems[1].value, mockItems[2].value],
+            items: mockItems,
+          });
+        }).toThrowError('To allow multi-selection, please, set "multiple" property to "true"');
+        expect(wrapper).toHaveLoggedVueErrors();
+      });
+
+      it('should render item as selected when `selected` provided ', () => {
+        expect(findListboxItems().at(1).props('isSelected')).toBe(true);
+      });
+
+      it('should deselect previously selected and select a new item', async () => {
+        findListboxItems().at(2).vm.$emit('select', true);
+        await nextTick();
+        expect(wrapper.emitted('select')[0][0]).toEqual(mockItems[2].value);
+      });
+    });
+  });
+
+  describe('onShow', () => {
+    beforeEach(async () => {
+      buildWrapper({
+        multiple: true,
+        items: mockItems,
+        selected: [mockItems[2].value, mockItems[1].value],
+      });
+      findBaseDropdown().vm.$emit(GL_DROPDOWN_SHOWN);
+      await nextTick();
+    });
+
+    it('should re-emit the event', () => {
+      expect(wrapper.emitted(GL_DROPDOWN_SHOWN)).toHaveLength(1);
+    });
+
+    it('should focus the first selected item', () => {
+      expect(findListboxItems().at(1).find(ITEM_SELECTOR).element).toHaveFocus();
+    });
+  });
+
+  describe('onHide', () => {
+    beforeEach(() => {
+      buildWrapper();
+      findBaseDropdown().vm.$emit(GL_DROPDOWN_HIDDEN);
+    });
+
+    it('should re-emit the event', () => {
+      expect(wrapper.emitted(GL_DROPDOWN_HIDDEN)).toHaveLength(1);
+    });
+  });
+
+  describe('navigating the items', () => {
+    let firstItem;
+    let secondItem;
+    let thirdItem;
+
+    beforeEach(() => {
+      buildWrapper({ items: mockItems });
+      findBaseDropdown().vm.$emit(GL_DROPDOWN_SHOWN);
+      firstItem = findListItem(0);
+      secondItem = findListItem(1);
+      thirdItem = findListItem(2);
+    });
+
+    it('should move the focus down the list of items on `arrow down` and stop on the last item', async () => {
+      expect(firstItem.element).toHaveFocus();
+      await firstItem.trigger('keydown', { code: ARROW_DOWN });
+      expect(secondItem.element).toHaveFocus();
+      await secondItem.trigger('keydown', { code: ARROW_DOWN });
+      expect(thirdItem.element).toHaveFocus();
+      await thirdItem.trigger('keydown', { code: ARROW_DOWN });
+      expect(thirdItem.element).toHaveFocus();
+    });
+
+    it('should move the focus up the list of items on `arrow up` and stop on the first item', async () => {
+      await firstItem.trigger('keydown', { code: ARROW_DOWN });
+      await secondItem.trigger('keydown', { code: ARROW_DOWN });
+      expect(thirdItem.element).toHaveFocus();
+      await thirdItem.trigger('keydown', { code: ARROW_UP });
+      expect(secondItem.element).toHaveFocus();
+      await secondItem.trigger('keydown', { code: ARROW_UP });
+      expect(firstItem.element).toHaveFocus();
+      await firstItem.trigger('keydown', { code: ARROW_UP });
+      expect(firstItem.element).toHaveFocus();
+    });
+
+    it('should move focus to the last item on `END` keydown', async () => {
+      expect(firstItem.element).toHaveFocus();
+      await firstItem.trigger('keydown', { code: END });
+      expect(thirdItem.element).toHaveFocus();
+      await thirdItem.trigger('keydown', { code: END });
+      expect(thirdItem.element).toHaveFocus();
+    });
+
+    it('should move focus to the first item on `HOME` keydown', async () => {
+      await firstItem.trigger('keydown', { code: ARROW_DOWN });
+      await secondItem.trigger('keydown', { code: ARROW_DOWN });
+      expect(thirdItem.element).toHaveFocus();
+      await thirdItem.trigger('keydown', { code: HOME });
+      expect(firstItem.element).toHaveFocus();
+      await thirdItem.trigger('keydown', { code: HOME });
+      expect(firstItem.element).toHaveFocus();
+    });
+  });
+
+  describe('when the header slot content is provided', () => {
+    const headerContent = 'Header Content';
+    const slots = { header: headerContent };
+
+    it('renders it', () => {
+      buildWrapper({}, slots);
+      expect(wrapper.text()).toContain(headerContent);
+    });
+  });
+
+  describe('when the footer slot content is provided', () => {
+    const footerContent = 'Footer Content';
+    const slots = { footer: footerContent };
+
+    it('renders it', () => {
+      buildWrapper({}, slots);
+      expect(wrapper.text()).toContain(footerContent);
+    });
+  });
+});