@gitlab/ui 39.3.1 → 39.5.0

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);
+    });
+  });
+});

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

@@ -0,0 +1,276 @@
+import {
+  buttonCategoryOptions,
+  buttonSizeOptions,
+  buttonVariantOptions,
+} from '../../../../utils/constants';
+import {
+  GlIcon,
+  GlListbox,
+  GlSearchBoxByType,
+  GlButtonGroup,
+  GlButton,
+  GlAvatar,
+} from '../../../../index';
+import { makeContainer } from '../../../../utils/story_decorators/container';
+import readme from './listbox.md';
+
+const defaultValue = (prop) => GlListbox.props[prop].default;
+
+const defaultItems = [
+  {
+    value: 'prod',
+    text: 'Product',
+  },
+  {
+    value: 'ppl',
+    text: 'People',
+  },
+  {
+    value: 'fin',
+    text: 'Finance',
+  },
+  {
+    value: 'leg',
+    text: 'Legal',
+  },
+  {
+    value: 'eng',
+    text: 'Engineering',
+  },
+  {
+    value: 'sales',
+    text: 'Sales',
+  },
+  {
+    value: 'marketing',
+    text: 'Marketing',
+  },
+  {
+    value: 'acc',
+    text: 'Accounting',
+  },
+  {
+    value: 'hr',
+    text: 'Human Resource Management',
+  },
+  {
+    value: 'rnd',
+    text: 'Research and Development',
+  },
+  {
+    value: 'cust',
+    text: 'Customer Service',
+  },
+  {
+    value: 'sup',
+    text: 'Support',
+  },
+];
+const generateProps = ({
+  items = defaultItems,
+  category = defaultValue('category'),
+  variant = defaultValue('variant'),
+  size = defaultValue('size'),
+  disabled = defaultValue('disabled'),
+  loading = defaultValue('loading'),
+  noCaret = defaultValue('noCaret'),
+  right = defaultValue('right'),
+  toggleText,
+  textSrOnly = defaultValue('textSrOnly'),
+  icon = '',
+  multiple = defaultValue('multiple'),
+  ariaLabelledby,
+} = {}) => ({
+  items,
+  category,
+  variant,
+  size,
+  disabled,
+  loading,
+  noCaret,
+  right,
+  toggleText,
+  textSrOnly,
+  icon,
+  multiple,
+  ariaLabelledby,
+});
+
+function openListbox(component) {
+  component.$nextTick(() => component.$el.querySelector('.dropdown-toggle').click());
+}
+
+const template = (content, label = '') => `
+  <div>
+    ${label}
+    <br/>
+    <gl-listbox
+      v-model="selected"
+      :items="items"
+      :category="category"
+      :variant="variant"
+      :size="size"
+      :disabled="disabled"
+      :loading="loading"
+      :no-caret="noCaret"
+      :right="right"
+      :toggle-text="toggleText"
+      :text-sr-only="textSrOnly"
+      :icon="icon"
+      :multiple="multiple"
+      :aria-labelledby="ariaLabelledby"
+    >
+      ${content}
+    </gl-listbox>
+  </div>
+`;
+
+export const Default = (args, { argTypes }) => ({
+  props: Object.keys(argTypes),
+  components: {
+    GlListbox,
+  },
+  data() {
+    return {
+      selected: defaultItems[1].value,
+    };
+  },
+  mounted() {
+    openListbox(this);
+  },
+  template: template('', `<span class="gl-my-0" id="listbox-label">Select a department</span>`),
+});
+Default.args = generateProps({ ariaLabelledby: 'listbox-label' });
+Default.decorators = [makeContainer({ height: '150px' })];
+
+export const HeaderAndFooter = (args, { argTypes }) => ({
+  props: Object.keys(argTypes),
+  components: {
+    GlListbox,
+    GlSearchBoxByType,
+    GlButtonGroup,
+    GlButton,
+  },
+  data() {
+    return {
+      selected: [],
+    };
+  },
+  mounted() {
+    openListbox(this);
+  },
+  methods: {
+    selectItem(index) {
+      this.selected.push(defaultItems[index].value);
+    },
+  },
+  template: template(`<template #header>
+                                <gl-search-box-by-type/>
+                              </template>
+                              <template #footer>
+                                <div class="gl-border-t-solid gl-border-t-1 gl-border-t-gray-100 gl-display-flex gl-justify-content-center gl-p-3">
+                                  <gl-button-group :vertical="false">
+                                    <gl-button @click="selectItem(0)">1st</gl-button>
+                                    <gl-button @click="selectItem(1)">2nd</gl-button>
+                                    <gl-button @click="selectItem(2)">3rd</gl-button>
+                                  </gl-button-group>
+                                </div>
+                              </template>`),
+});
+HeaderAndFooter.args = generateProps({ toggleText: 'Header and Footer', multiple: true });
+HeaderAndFooter.decorators = [makeContainer({ height: '220px' })];
+
+export const CustomListItem = (args, { argTypes }) => ({
+  props: Object.keys(argTypes),
+  data() {
+    return {
+      selected: ['mikegreiling'],
+    };
+  },
+  components: {
+    GlListbox,
+    GlIcon,
+    GlAvatar,
+  },
+  mounted() {
+    openListbox(this);
+  },
+  computed: {
+    headerText() {
+      return this.selected.length !== 1
+        ? `${this.selected.length} assignees`
+        : this.items.find(({ value }) => value === this.selected[0]).text;
+    },
+  },
+  template: `
+      <gl-listbox
+        v-model="selected"
+        :items="items"
+        :category="category"
+        :variant="variant"
+        :size="size"
+        :disabled="disabled"
+        :loading="loading"
+        :no-caret="noCaret"
+        :right="right"
+        :toggle-text="headerText"
+        :text-sr-only="textSrOnly"
+        :icon="icon"
+        :multiple="multiple"
+        :aria-labelledby="ariaLabelledby"
+      >
+        <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-listbox>
+  `,
+});
+
+CustomListItem.args = generateProps({
+  items: [
+    { value: 'mikegreiling', text: 'Mike Greiling', secondaryText: '@mikegreiling', icon: 'foo' },
+    { value: 'ohoral', text: 'Olena Horal-Koretska', secondaryText: '@ohoral', icon: 'bar' },
+    { value: 'markian', text: 'Mark Florian', secondaryText: '@markian', icon: 'bin' },
+  ],
+  multiple: true,
+});
+CustomListItem.decorators = [makeContainer({ height: '200px' })];
+
+export default {
+  title: 'base/new-dropdowns/listbox',
+  component: GlListbox,
+  parameters: {
+    knobs: { disable: true },
+    docs: {
+      description: {
+        component: readme,
+      },
+    },
+  },
+  argTypes: {
+    category: {
+      control: {
+        type: 'select',
+        options: buttonCategoryOptions,
+      },
+    },
+    variant: {
+      control: {
+        type: 'select',
+        options: buttonVariantOptions,
+      },
+    },
+    size: {
+      control: {
+        type: 'select',
+        options: buttonSizeOptions,
+      },
+    },
+  },
+};