@gitlab/ui 52.10.0 → 52.12.0

package/dist/index.js

@@ -46,6 +46,9 @@ export { default as GlDropdownText } from './components/base/dropdown/dropdown_t
 export { default as GlDropdown } from './components/base/dropdown/dropdown';
 export { default as GlCollapsibleListbox, 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 GlDisclosureDropdown } from './components/base/new_dropdowns/disclosure/disclosure_dropdown';
+export { default as GlDisclosureDropdownItem } from './components/base/new_dropdowns/disclosure/disclosure_dropdown_item';
+export { default as GlDisclosureDropdownGroup } from './components/base/new_dropdowns/disclosure/disclosure_dropdown_group';
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitlab/ui",
-  "version": "52.10.0",
+  "version": "52.12.0",
   "description": "GitLab UI Components",
   "license": "MIT",
   "main": "dist/index.js",
@@ -85,9 +85,9 @@
     "@babel/core": "^7.20.12",
     "@babel/preset-env": "^7.20.2",
     "@gitlab/eslint-plugin": "18.1.0",
-    "@gitlab/fonts": "^1.0.1",
+    "@gitlab/fonts": "^1.1.0",
     "@gitlab/stylelint-config": "4.1.0",
-    "@gitlab/svgs": "3.15.0",
+    "@gitlab/svgs": "3.16.0",
     "@rollup/plugin-commonjs": "^11.1.0",
     "@rollup/plugin-node-resolve": "^7.1.3",
     "@rollup/plugin-replace": "^2.3.2",

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

@@ -1,6 +1,6 @@
 import { mount } from '@vue/test-utils';
 import { nextTick } from 'vue';
-import { GL_DROPDOWN_HIDDEN, GL_DROPDOWN_SHOWN, POPPER_CONFIG } from '../constants';
+import { ENTER, GL_DROPDOWN_HIDDEN, GL_DROPDOWN_SHOWN, POPPER_CONFIG } from '../constants';
 import GlBaseDropdown from './base_dropdown.vue';
 
 const destroyPopper = jest.fn();
@@ -197,14 +197,14 @@ describe('base dropdown', () => {
         const toggle = findCustomDropdownToggle();
         const menu = findDropdownMenu();
         // open menu clicking toggle btn
-        await toggle.trigger('keydown.enter');
+        await toggle.trigger('keydown', { code: ENTER });
         expect(menu.classes('show')).toBe(true);
         expect(toggle.attributes('aria-expanded')).toBe('true');
         await nextTick();
         expect(wrapper.emitted(GL_DROPDOWN_SHOWN).length).toBe(1);
 
         // close menu clicking toggle btn again
-        await toggle.trigger('keydown.enter');
+        await toggle.trigger('keydown', { code: ENTER });
         expect(menu.classes('show')).toBe(false);
         expect(toggle.attributes('aria-expanded')).toBeUndefined();
         expect(wrapper.emitted(GL_DROPDOWN_HIDDEN).length).toBe(1);

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

@@ -1,11 +1,12 @@
 <script>
+import { uniqueId } from 'lodash';
 import { createPopper } from '@popperjs/core';
 import {
   buttonCategoryOptions,
   buttonSizeOptions,
   dropdownVariantOptions,
 } from '../../../../utils/constants';
-import { POPPER_CONFIG, GL_DROPDOWN_SHOWN, GL_DROPDOWN_HIDDEN } from '../constants';
+import { POPPER_CONFIG, GL_DROPDOWN_SHOWN, GL_DROPDOWN_HIDDEN, ENTER, SPACE } from '../constants';
 
 import GlButton from '../../button/button.vue';
 import GlIcon from '../../icon/icon.vue';
@@ -107,6 +108,7 @@ export default {
   data() {
     return {
       visible: false,
+      baseDropdownId: uniqueId('base-dropdown-'),
     };
   },
   computed: {
@@ -145,13 +147,21 @@ export default {
           disabled: this.disabled,
           loading: this.loading,
           class: this.toggleButtonClasses,
+          listeners: {
+            click: () => this.toggle(),
+          },
         };
       }
 
       return {
         is: 'div',
+        role: 'button',
         class: 'gl-dropdown-custom-toggle gl-hover-cursor-pointer',
         tabindex: '0',
+        listeners: {
+          keydown: (event) => this.onKeydown(event),
+          click: () => this.toggle(),
+        },
       };
     },
     toggleElement() {
@@ -216,6 +226,13 @@ export default {
     focusToggle() {
       this.toggleElement.focus();
     },
+    onKeydown(event) {
+      const { code } = event;
+
+      if (code === ENTER || code === SPACE) {
+        this.toggle();
+      }
+    },
   },
 };
 </script>
@@ -234,8 +251,8 @@ export default {
       :aria-haspopup="ariaHaspopup"
       :aria-expanded="visible"
       :aria-labelledby="toggleLabelledBy"
-      @keydown.enter="toggle"
-      @click="toggle"
+      :aria-controls="baseDropdownId"
+      v-on="toggleOptions.listeners"
     >
       <!-- @slot Custom toggle button content -->
       <slot name="toggle">
@@ -247,6 +264,7 @@ export default {
     </component>
 
     <div
+      :id="baseDropdownId"
       ref="content"
       data-testid="base-dropdown-menu"
       class="dropdown-menu"

package/src/components/base/new_dropdowns/disclosure/disclosure_dropdown.md

@@ -0,0 +1,114 @@
+A disclosure dropdown is a button that toggles a panel containing a list of actions and/or links. Use
+[this decision tree](https://design.gitlab.com/components/dropdown-overview#which-component-should-you-use)
+to make sure this is the right dropdown component for you.
+
+### Basic usage
+
+```html
+<gl-disclosure-dropdown-dropdown
+  toggle-text="Actions"
+  :items="items"
+/>
+```
+
+### Icon-only disclosure dropdown
+
+Icon-only disclosure dropdowns must have an accessible name.
+You can provide this with the combination of `toggleText` and `textSrOnly` props.
+
+Optionally, you can use `no-caret` to remove the caret and `category="tertiary"` to remove the border.
+
+```html
+<gl-disclosure-dropdown
+  icon="ellipsis_v"
+  toggle-text="Actions"
+  text-sr-only
+  category="tertiary"
+  no-caret
+/>
+```
+
+### Opening the disclosure dropdown
+
+Disclosure dropdown will open on toggle button click (if it was previously closed).
+On open, `GlDisclosureDropdown` will emit the `shown` event.
+
+### Closing the disclosure dropdown
+
+The disclosure dropdown is closed by any of the following:
+
+- pressing <kbd>Esc</kbd>
+- clicking anywhere outside the component
+
+After closing, `GlDisclosureDropdown` emits a `hidden` event.
+
+### Setting disclosure dropdown items
+
+Use the `items` prop to provide actions/links to the disclosure dropdown. Each item can be
+either an item or a group. Below are the expected shapes of these objects:
+
+```typescript
+type Item = {
+  text: string
+  href?: string,
+  action?: function,
+}
+
+type Group = {
+  name?: string
+  items: Array<Item>
+}
+
+type ItemsProp = Array<Item> | Array<Group>
+```
+
+#### Actions/links
+
+The `text` property is used to render the default disclosure dropdown item
+template. If you want to render a custom template for items, use the
+`list-item` scoped slot:
+
+```html
+<gl-disclosure-dropdown :items="items">
+    <template #list-item="{ item }">
+        <a class="gl-hover-text-decoration-none gl-text-gray-900"
+           tabindex="-1"
+           :href="item.href"
+           v-bind="item.extraAttrs">
+            {{ item.text }}
+            <gl-badge pill variant="info" v-if="item.count">{{ item.count }}</gl-badge>
+        </a>
+    </template>
+</gl-disclosure-dropdown>
+```
+
+**Note:** when providing custom content to the item, user should
+define the correct tab order inside the disclosure dropdown by setting
+the `tabindex` attribute on the elements.
+The `li` item will get the focus so you might want elements inside it
+not to be focused - this can be done by setting `tabindex="-1"` on them.
+
+#### Groups
+
+Actions/links can be contained within groups. A group can have a `name`
+property, which will be used as the group header if present.
+It also has a required property `items` that must be an array of links/actions.
+
+Groups can be at most one level deep: a group can only contain actions/links.
+Items and groups _cannot_ be siblings. Either all items are actions/links,
+or they are all groups.
+
+To render custom group labels, use the `group-label` scoped slot:
+
+```html
+<gl-disclosure-dropdown :items="groups">
+  <template #group-label="{ group }">
+    {{ group.name }} <gl-badge size="sm">{{ group.items.length }}</gl-badge>
+  </template>
+</gl-disclosure-dropdown>
+```
+
+#### Miscellaneous content
+
+Besides default components, disclosure dropdown can render miscellaneous content inside it.
+In this case the user is responsible for handling all events and navigation inside the disclosure.

package/src/components/base/new_dropdowns/disclosure/disclosure_dropdown.scss

@@ -0,0 +1,7 @@
+.gl-disclosure-dropdown {
+  &.gl-dropdown {
+    .gl-dropdown-inner {
+      max-height: none;
+    }
+  }
+}

package/src/components/base/new_dropdowns/disclosure/disclosure_dropdown.spec.js

@@ -0,0 +1,210 @@
+import { mount } from '@vue/test-utils';
+import GlBaseDropdown from '../base_dropdown/base_dropdown.vue';
+import {
+  GL_DROPDOWN_SHOWN,
+  GL_DROPDOWN_HIDDEN,
+  ARROW_DOWN,
+  ARROW_UP,
+  HOME,
+  END,
+} from '../constants';
+import GlDisclosureDropdown from './disclosure_dropdown.vue';
+import GlDisclosureDropdownItem from './disclosure_dropdown_item.vue';
+import GlDisclosureDropdownGroup from './disclosure_dropdown_group.vue';
+import { mockItems, mockGroups } from './mock_data';
+
+const ITEM_SELECTOR = '[data-testid="disclosure-dropdown-item"]';
+
+describe('GlDisclosureDropdown', () => {
+  let wrapper;
+
+  const buildWrapper = (propsData, slots = {}) => {
+    wrapper = mount(GlDisclosureDropdown, {
+      propsData,
+      slots,
+      attachTo: document.body,
+    });
+  };
+
+  const findBaseDropdown = () => wrapper.findComponent(GlBaseDropdown);
+  const findDisclosureContent = () => wrapper.find('[data-testid="disclosure-content"]');
+  const findDisclosureItems = (root = wrapper) => root.findAllComponents(GlDisclosureDropdownItem);
+  const findDisclosureGroups = () => wrapper.findAllComponents(GlDisclosureDropdownGroup);
+  const findListItem = (index) => findDisclosureItems().at(index).findComponent(ITEM_SELECTOR);
+
+  describe('toggle text', () => {
+    it('should pass toggle text to base dropdown', () => {
+      const toggleText = 'Merge requests';
+      buildWrapper({ items: mockItems, toggleText });
+      expect(findBaseDropdown().props('toggleText')).toBe(toggleText);
+    });
+  });
+
+  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({ items: mockItems });
+      expect(findBaseDropdown().props('toggleId')).toBe(
+        findDisclosureContent().attributes('aria-labelledby')
+      );
+    });
+
+    it('should reference `listAriaLabelledby`', async () => {
+      const listAriaLabelledBy = 'first-label-id second-label-id';
+      await buildWrapper({ items: mockItems, listAriaLabelledBy });
+      expect(findDisclosureContent().attributes('aria-labelledby')).toBe(listAriaLabelledBy);
+    });
+  });
+
+  describe('onShow', () => {
+    const showDropdown = () => {
+      buildWrapper({
+        items: mockItems,
+      });
+      findBaseDropdown().vm.$emit(GL_DROPDOWN_SHOWN);
+    };
+
+    beforeEach(() => {
+      showDropdown();
+    });
+
+    it('should re-emit the event', () => {
+      expect(wrapper.emitted(GL_DROPDOWN_SHOWN)).toHaveLength(1);
+    });
+
+    it('should focus the first item', () => {
+      expect(findDisclosureItems().at(0).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('slot content', () => {
+    const headerContent = 'Header Content';
+    const footerContent = 'Footer Content';
+    const toggleContent = 'Toggle Content';
+    const defaultContent = 'Toggle Content';
+    const slots = {
+      header: headerContent,
+      footer: footerContent,
+      toggle: toggleContent,
+      default: defaultContent,
+    };
+
+    it('renders all slot content', () => {
+      buildWrapper({}, slots);
+      expect(wrapper.text()).toContain(headerContent);
+      expect(wrapper.text()).toContain(footerContent);
+      expect(wrapper.text()).toContain(toggleContent);
+      expect(wrapper.text()).toContain(defaultContent);
+    });
+  });
+
+  describe('with groups', () => {
+    it('renders groups of items', () => {
+      buildWrapper({ items: mockGroups });
+
+      const groups = findDisclosureGroups();
+
+      expect(groups.length).toBe(mockGroups.length);
+
+      mockGroups.forEach((group, i) => {
+        expect(findDisclosureItems(groups.at(i))).toHaveLength(group.items.length);
+      });
+    });
+  });
+
+  describe('action', () => {
+    it('should re-emit the `action` event when it is emitted on the item for custom handling', () => {
+      buildWrapper({
+        items: mockItems,
+      });
+
+      findListItem(0).vm.$emit('action', mockItems[0]);
+      expect(wrapper.emitted('action')).toHaveLength(1);
+      expect(wrapper.emitted('action')[0][0]).toEqual(mockItems[0]);
+    });
+  });
+
+  describe('disclosure options', () => {
+    it('should render the `ul` as content tag and not add `role` attribute when it is a list of items only', () => {
+      buildWrapper({ items: mockItems });
+      expect(findDisclosureContent().element.tagName).toBe('UL');
+      expect(findDisclosureContent().attributes('role')).toBeUndefined();
+    });
+
+    it('should render the `div` as content tag and add `role` attribute when it is a list of groups', () => {
+      buildWrapper({ items: mockGroups });
+      expect(findDisclosureContent().element.tagName).toBe('DIV');
+      expect(findDisclosureContent().attributes('role')).toBe('group');
+    });
+
+    it('should render the `div` as content tag and NOT add `role` otherwise', () => {
+      buildWrapper({ items: null }, { default: 'Some other content' });
+      expect(findDisclosureContent().element.tagName).toBe('DIV');
+      expect(findDisclosureContent().attributes('role')).toBeUndefined();
+    });
+  });
+});