@gitlab/ui 39.3.2 → 39.4.0

package/dist/index.js

@@ -44,6 +44,8 @@ export { default as GlDropdownSectionHeader } from './components/base/dropdown/d
 export { default as GlDropdownDivider } from './components/base/dropdown/dropdown_divider';
 export { default as GlDropdownText } from './components/base/dropdown/dropdown_text';
 export { default as GlDropdown } from './components/base/dropdown/dropdown';
+export { default as GlListbox } from './components/base/new_dropdowns/listbox/listbox';
+export { default as GlListboxItem } from './components/base/new_dropdowns/listbox/listbox_item';
 export { default as GlPath } from './components/base/path/path';
 export { default as GlTable } from './components/base/table/table';
 export { default as GlBreadcrumb } from './components/base/breadcrumb/breadcrumb';

package/dist/utils/utils.js

@@ -119,5 +119,28 @@ function logWarning() {
     console.warn(message); // eslint-disable-line no-console
   }
 }
+/**
+ * Stop default event handling and propagation
+ */
+
+function stopEvent(event) {
+  let {
+    preventDefault = true,
+    stopPropagation = true,
+    stopImmediatePropagation = false
+  } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+
+  if (preventDefault) {
+    event.preventDefault();
+  }
+
+  if (stopPropagation) {
+    event.stopPropagation();
+  }
+
+  if (stopImmediatePropagation) {
+    event.stopImmediatePropagation();
+  }
+}
 
-export { colorFromBackground, debounceByAnimationFrame, focusFirstFocusableElement, hexToRgba, isDev, isElementFocusable, logWarning, rgbFromHex, rgbFromString, throttle, uid };
+export { colorFromBackground, debounceByAnimationFrame, focusFirstFocusableElement, hexToRgba, isDev, isElementFocusable, logWarning, rgbFromHex, rgbFromString, stopEvent, throttle, uid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitlab/ui",
-  "version": "39.3.2",
+  "version": "39.4.0",
   "description": "GitLab UI Components",
   "license": "MIT",
   "main": "dist/index.js",
@@ -55,6 +55,7 @@
     "generate:component": "plop"
   },
   "dependencies": {
+    "@popperjs/core": "^2.11.2",
     "bootstrap-vue": "2.20.1",
     "dompurify": "^2.3.6",
     "echarts": "^5.2.1",

package/src/components/base/dropdown/dropdown.scss

@@ -128,8 +128,14 @@
     }
   }
 
-  .gl-dropdown-toggle.btn-block {
-    @include gl-justify-content-space-between;
+  .gl-dropdown-toggle {
+    &.btn-block {
+      @include gl-justify-content-space-between;
+    }
+
+    .gl-button-text {
+      @include gl-display-inline-flex;
+    }
   }
 
   .gl-new-dropdown-button-text {
@@ -173,7 +179,8 @@
   }
 
   .dropdown-icon-only {
-    .dropdown-icon {
+    .dropdown-icon,
+    .gl-button-icon.gl-button-icon {
       @include gl-mr-0;
     }
 

package/src/components/base/dropdown/dropdown_item.scss

@@ -20,6 +20,7 @@
 .gl-new-dropdown-item {
   .dropdown-item {
     @include gl-tmp-dropdown-item-style;
+    @include gl-cursor-pointer;
 
     .gl-avatar {
       @include gl-flex-shrink-0;

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

@@ -0,0 +1,171 @@
+import { mount } from '@vue/test-utils';
+import { nextTick } from 'vue';
+import { GL_DROPDOWN_HIDDEN, GL_DROPDOWN_SHOWN, POPPER_CONFIG } from '../constants';
+import GlBaseDropdown from './base_dropdown.vue';
+
+const destroyPopper = jest.fn();
+const updatePopper = jest.fn();
+const mockCreatePopper = jest.fn().mockImplementation(() => ({
+  destroy: destroyPopper,
+  update: updatePopper,
+}));
+
+jest.mock('@popperjs/core', () => ({
+  createPopper: (...args) => mockCreatePopper(...args),
+}));
+
+const DEFAULT_BTN_TOGGLE_CLASSES = [
+  'btn',
+  'btn-default',
+  'btn-md',
+  'gl-button',
+  'dropdown-toggle',
+  'gl-dropdown-toggle',
+];
+
+describe('base dropdown', () => {
+  let wrapper;
+
+  const buildWrapper = (propsData, slots = {}) => {
+    wrapper = mount(GlBaseDropdown, {
+      propsData: {
+        toggleId: 'dropdown-toggle-btn-1',
+        ...propsData,
+      },
+      slots,
+      attachTo: document.body,
+    });
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  const findDropdownToggle = () => wrapper.find('.btn.gl-dropdown-toggle');
+  const findDropdownMenu = () => wrapper.find('.dropdown-menu');
+
+  describe('popper.js instance', () => {
+    it('should initialize popper.js instance with toggle and menu elements and config for left-aligned menu', async () => {
+      await buildWrapper();
+      expect(mockCreatePopper).toHaveBeenCalledWith(
+        findDropdownToggle().element,
+        findDropdownMenu().element,
+        { ...POPPER_CONFIG, placement: 'bottom-start' }
+      );
+    });
+
+    it('should initialize popper.js instance with toggle and menu elements and config for right-aligned menu', async () => {
+      await buildWrapper({ right: true });
+      expect(mockCreatePopper).toHaveBeenCalledWith(
+        findDropdownToggle().element,
+        findDropdownMenu().element,
+        { ...POPPER_CONFIG, placement: 'bottom-end' }
+      );
+    });
+
+    it('should update popper instance when component is updated', async () => {
+      await buildWrapper();
+      await findDropdownToggle().trigger('click');
+      await wrapper.setProps({ category: 'tertiary' });
+      expect(updatePopper).toHaveBeenCalled();
+    });
+
+    it('should destroy popper instance when component is destroyed', async () => {
+      await buildWrapper();
+      wrapper.destroy();
+      expect(destroyPopper).toHaveBeenCalled();
+    });
+  });
+
+  describe('renders content to the default slot', () => {
+    const defaultContent = 'Some content here';
+    const slots = { default: defaultContent };
+
+    it('renders the content', () => {
+      buildWrapper({}, slots);
+      expect(wrapper.find('.gl-new-dropdown-inner').html()).toContain(defaultContent);
+    });
+  });
+
+  describe.each`
+    props                                                            | toggleClasses
+    ${{}}                                                            | ${[]}
+    ${{ toggleText: 'toggleText' }}                                  | ${[]}
+    ${{ toggleText: 'toggleText', icon: 'close' }}                   | ${['dropdown-icon-text']}
+    ${{ icon: 'close' }}                                             | ${['dropdown-icon-only']}
+    ${{ icon: 'close', toggleText: 'toggleText', textSrOnly: true }} | ${['dropdown-icon-only']}
+    ${{ icon: 'close', textSrOnly: true }}                           | ${['dropdown-icon-only']}
+    ${{ toggleText: 'toggleText', noCaret: true }}                   | ${['dropdown-toggle-no-caret']}
+  `('dropdown with props $props', ({ props, toggleClasses }) => {
+    beforeEach(async () => {
+      buildWrapper(props);
+
+      await nextTick();
+    });
+
+    it(`sets toggle button classes to '${toggleClasses}'`, () => {
+      const classes = findDropdownToggle().classes().sort();
+
+      expect(classes).toEqual([...DEFAULT_BTN_TOGGLE_CLASSES, ...toggleClasses].sort());
+    });
+  });
+
+  describe.each`
+    toggleClass             | expectedClasses                                      | type
+    ${'my-class'}           | ${[...DEFAULT_BTN_TOGGLE_CLASSES, 'my-class']}       | ${'string'}
+    ${{ 'my-class': true }} | ${[...DEFAULT_BTN_TOGGLE_CLASSES, 'my-class']}       | ${'object'}
+    ${['cls-1', 'cls-2']}   | ${[...DEFAULT_BTN_TOGGLE_CLASSES, 'cls-1', 'cls-2']} | ${'array'}
+    ${null}                 | ${[...DEFAULT_BTN_TOGGLE_CLASSES]}                   | ${'null'}
+  `('with toggle classes', ({ toggleClass, expectedClasses, type }) => {
+    beforeEach(async () => {
+      buildWrapper({ toggleClass });
+
+      await nextTick();
+    });
+
+    it(`class is inherited from toggle class of type ${type}`, () => {
+      expect(findDropdownToggle().classes().sort()).toEqual(
+        expect.arrayContaining(expectedClasses.sort())
+      );
+    });
+  });
+
+  describe('toggle visibility', () => {
+    beforeEach(() => {
+      buildWrapper();
+    });
+
+    it('should toggle menu visibility on toggle button click ', async () => {
+      const toggle = findDropdownToggle();
+      const menu = findDropdownMenu();
+
+      // open menu clicking toggle btn
+      await toggle.trigger('click');
+      expect(menu.classes('show')).toBe(true);
+      expect(toggle.attributes('aria-expanded')).toBe('true');
+      expect(wrapper.emitted(GL_DROPDOWN_SHOWN).length).toBe(1);
+
+      // close menu clicking toggle btn again
+      await toggle.trigger('click');
+      expect(menu.classes('show')).toBe(false);
+      expect(toggle.attributes('aria-expanded')).toBeUndefined();
+      expect(wrapper.emitted(GL_DROPDOWN_HIDDEN).length).toBe(1);
+    });
+
+    it('should close the menu when Escape is pressed inside menu and focus toggle', async () => {
+      const toggle = findDropdownToggle();
+      const menu = findDropdownMenu();
+
+      // open menu clicking toggle btn
+      await toggle.trigger('click');
+      expect(menu.classes('show')).toBe(true);
+
+      // close menu pressing ESC on it
+      await menu.trigger('keydown.esc');
+      expect(menu.classes('show')).toBe(false);
+      expect(toggle.attributes('aria-expanded')).toBeUndefined();
+      expect(wrapper.emitted(GL_DROPDOWN_HIDDEN).length).toBe(1);
+      expect(toggle.element).toHaveFocus();
+    });
+  });
+});

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>
+```