@gitlab/ui 43.13.0 → 43.14.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [43.14.0](https://gitlab.com/gitlab-org/gitlab-ui/compare/v43.13.0...v43.14.0) (2022-09-08)
+
+
+### Features
+
+* **GlListbox:** Add support for grouping ([c6ec8f1](https://gitlab.com/gitlab-org/gitlab-ui/commit/c6ec8f1a53eb4fad9a3ec077a762b23e67ef0245))
+
 # [43.13.0](https://gitlab.com/gitlab-org/gitlab-ui/compare/v43.12.0...v43.13.0) (2022-09-06)
 
 

package/dist/components/base/new_dropdowns/listbox/listbox.js

@@ -5,9 +5,12 @@ import { GL_DROPDOWN_SHOWN, GL_DROPDOWN_HIDDEN, HOME, END, ARROW_UP, ARROW_DOWN
 import { buttonCategoryOptions, dropdownVariantOptions, buttonSizeOptions } from '../../../../utils/constants';
 import GlBaseDropdown from '../base_dropdown/base_dropdown';
 import GlListboxItem from './listbox_item';
+import GlListboxGroup from './listbox_group';
+import { itemsValidator, isOption, flattenedOptions } from './utils';
 import __vue_normalize__ from 'vue-runtime-helpers/dist/normalize-component.js';
 
 const ITEM_SELECTOR = '[role="option"]';
+const GROUP_TOP_BORDER_CLASSES = ['gl-border-t', 'gl-pt-3', 'gl-mt-3'];
 var script = {
   events: {
     GL_DROPDOWN_SHOWN,
@@ -15,7 +18,8 @@ var script = {
   },
   components: {
     GlBaseDropdown,
-    GlListboxItem
+    GlListboxItem,
+    GlListboxGroup
   },
   model: {
     prop: 'selected',
@@ -29,14 +33,7 @@ var script = {
       type: Array,
       required: false,
       default: () => [],
-      validator: items => {
-        return items.every(_ref => {
-          let {
-            value
-          } = _ref;
-          return typeof value === 'string';
-        });
-      }
+      validator: itemsValidator
     },
 
     /**
@@ -187,17 +184,26 @@ var script = {
   },
 
   computed: {
+    listboxTag() {
+      if (this.items.length === 0 || isOption(this.items[0])) return 'ul';
+      return 'div';
+    },
+
+    flattenedOptions() {
+      return flattenedOptions(this.items);
+    },
+
     listboxToggleText() {
       if (!this.toggleText) {
         if (!this.multiple && this.selectedValues.length) {
-          var _this$items$find;
+          var _this$flattenedOption;
 
-          return (_this$items$find = this.items.find(_ref2 => {
+          return (_this$flattenedOption = this.flattenedOptions.find(_ref => {
             let {
               value
-            } = _ref2;
+            } = _ref;
             return value === this.selectedValues[0];
-          })) === null || _this$items$find === void 0 ? void 0 : _this$items$find.text;
+          })) === null || _this$flattenedOption === void 0 ? void 0 : _this$flattenedOption.text;
         }
 
         return '';
@@ -207,10 +213,10 @@ var script = {
     },
 
     selectedIndices() {
-      return this.selectedValues.map(selected => this.items.findIndex(_ref3 => {
+      return this.selectedValues.map(selected => this.flattenedOptions.findIndex(_ref2 => {
         let {
           value
-        } = _ref3;
+        } = _ref2;
         return value === selected;
       })).sort();
     }
@@ -235,6 +241,10 @@ var script = {
     }
   },
   methods: {
+    groupClasses(index) {
+      return index === 0 ? null : GROUP_TOP_BORDER_CLASSES;
+    },
+
     onShow() {
       this.$nextTick(() => {
         var _this$selectedIndices;
@@ -310,10 +320,10 @@ var script = {
       });
     },
 
-    onSelect(_ref4, isSelected) {
+    onSelect(_ref3, isSelected) {
       let {
         value
-      } = _ref4;
+      } = _ref3;
 
       if (this.multiple) {
         this.onMultiSelect(value, isSelected);
@@ -326,6 +336,10 @@ var script = {
       return this.selectedValues.some(value => value === item.value);
     },
 
+    isFocused(item) {
+      return this.nextFocusedItemIndex === this.flattenedOptions.indexOf(item);
+    },
+
     onSingleSelect(value, isSelected) {
       if (isSelected) {
         /**
@@ -345,8 +359,9 @@ var script = {
       } else {
         this.$emit('select', this.selectedValues.filter(selectedValue => selectedValue !== value));
       }
-    }
+    },
 
+    isOption
   }
 };
 
@@ -354,7 +369,7 @@ var script = {
 const __vue_script__ = script;
 
 /* template */
-var __vue_render__ = function () {var _vm=this;var _h=_vm.$createElement;var _c=_vm._self._c||_h;return _c('gl-base-dropdown',{ref:"baseDropdown",attrs:{"aria-haspopup":"listbox","aria-labelledby":_vm.ariaLabelledby,"toggle-id":_vm.toggleId,"toggle-text":_vm.listboxToggleText,"toggle-class":_vm.toggleClass,"text-sr-only":_vm.textSrOnly,"category":_vm.category,"variant":_vm.variant,"size":_vm.size,"icon":_vm.icon,"disabled":_vm.disabled,"loading":_vm.loading,"no-caret":_vm.noCaret,"right":_vm.right},on:_vm._d({},[_vm.$options.events.GL_DROPDOWN_SHOWN,_vm.onShow,_vm.$options.events.GL_DROPDOWN_HIDDEN,_vm.onHide])},[_vm._t("header"),_vm._v(" "),_c('ul',{ref:"list",staticClass:"gl-new-dropdown-contents gl-list-style-none gl-pl-0 gl-mb-0",attrs:{"aria-labelledby":_vm.toggleId,"role":"listbox","tabindex":"-1"},on:{"keydown":_vm.onKeydown}},_vm._l((_vm.items),function(item,index){return _c('gl-listbox-item',{key:item.value,attrs:{"is-selected":_vm.isSelected(item),"is-focused":_vm.nextFocusedItemIndex === index,"is-check-centered":_vm.isCheckCentered},on:{"select":function($event){return _vm.onSelect(item, $event)}}},[_vm._t("list-item",function(){return [_vm._v("\n        "+_vm._s(item.text)+"\n      ")]},{"item":item})],2)}),1),_vm._v(" "),_vm._t("footer")],2)};
+var __vue_render__ = function () {var _vm=this;var _h=_vm.$createElement;var _c=_vm._self._c||_h;return _c('gl-base-dropdown',{ref:"baseDropdown",attrs:{"aria-haspopup":"listbox","aria-labelledby":_vm.ariaLabelledby,"toggle-id":_vm.toggleId,"toggle-text":_vm.listboxToggleText,"toggle-class":_vm.toggleClass,"text-sr-only":_vm.textSrOnly,"category":_vm.category,"variant":_vm.variant,"size":_vm.size,"icon":_vm.icon,"disabled":_vm.disabled,"loading":_vm.loading,"no-caret":_vm.noCaret,"right":_vm.right},on:_vm._d({},[_vm.$options.events.GL_DROPDOWN_SHOWN,_vm.onShow,_vm.$options.events.GL_DROPDOWN_HIDDEN,_vm.onHide])},[_vm._t("header"),_vm._v(" "),_c(_vm.listboxTag,{ref:"list",tag:"component",staticClass:"gl-new-dropdown-contents gl-list-style-none gl-pl-0 gl-mb-0",attrs:{"aria-labelledby":_vm.toggleId,"role":"listbox","tabindex":"-1"},on:{"keydown":_vm.onKeydown}},[_vm._l((_vm.items),function(item,index){return [(_vm.isOption(item))?[_c('gl-listbox-item',{key:item.value,attrs:{"is-selected":_vm.isSelected(item),"is-focused":_vm.isFocused(item),"is-check-centered":_vm.isCheckCentered},on:{"select":function($event){return _vm.onSelect(item, $event)}}},[_vm._t("list-item",function(){return [_vm._v("\n            "+_vm._s(item.text)+"\n          ")]},{"item":item})],2)]:[_c('gl-listbox-group',{key:item.text,class:_vm.groupClasses(index),attrs:{"name":item.text},scopedSlots:_vm._u([(_vm.$scopedSlots['group-label'])?{key:"group-label",fn:function(){return [_vm._t("group-label",null,{"group":item})]},proxy:true}:null],null,true)},[_vm._v(" "),_vm._l((item.options),function(option){return _c('gl-listbox-item',{key:option.value,attrs:{"is-selected":_vm.isSelected(option),"is-focused":_vm.isFocused(option),"is-check-centered":_vm.isCheckCentered},on:{"select":function($event){return _vm.onSelect(option, $event)}}},[_vm._t("list-item",function(){return [_vm._v("\n              "+_vm._s(option.text)+"\n            ")]},{"item":option})],2)})],2)]]})],2),_vm._v(" "),_vm._t("footer")],2)};
 var __vue_staticRenderFns__ = [];
 
   /* style */

package/dist/components/base/new_dropdowns/listbox/listbox_group.js

@@ -0,0 +1,54 @@
+import _uniqueId from 'lodash/uniqueId';
+import __vue_normalize__ from 'vue-runtime-helpers/dist/normalize-component.js';
+
+var script = {
+  props: {
+    name: {
+      type: String,
+      required: true
+    }
+  },
+
+  created() {
+    this.nameId = _uniqueId('gl-listbox-group-');
+  }
+
+};
+
+/* script */
+const __vue_script__ = script;
+
+/* template */
+var __vue_render__ = function () {var _vm=this;var _h=_vm.$createElement;var _c=_vm._self._c||_h;return _c('ul',{staticClass:"gl-mb-0 gl-pl-0 gl-list-style-none",attrs:{"role":"group","aria-labelledby":_vm.nameId}},[_c('li',{staticClass:"gl-pl-5! gl-py-2! gl-font-base gl-font-weight-bold",attrs:{"id":_vm.nameId,"role":"presentation"}},[_vm._t("group-label",function(){return [_vm._v(_vm._s(_vm.name))]})],2),_vm._v(" "),_vm._t("default")],2)};
+var __vue_staticRenderFns__ = [];
+
+  /* style */
+  const __vue_inject_styles__ = undefined;
+  /* scoped */
+  const __vue_scope_id__ = undefined;
+  /* module identifier */
+  const __vue_module_identifier__ = undefined;
+  /* functional template */
+  const __vue_is_functional_template__ = false;
+  /* style inject */
+  
+  /* style inject SSR */
+  
+  /* style inject shadow dom */
+  
+
+  
+  const __vue_component__ = __vue_normalize__(
+    { render: __vue_render__, staticRenderFns: __vue_staticRenderFns__ },
+    __vue_inject_styles__,
+    __vue_script__,
+    __vue_scope_id__,
+    __vue_is_functional_template__,
+    __vue_module_identifier__,
+    false,
+    undefined,
+    undefined,
+    undefined
+  );
+
+export default __vue_component__;

package/dist/components/base/new_dropdowns/listbox/mock_data.js

@@ -0,0 +1,61 @@
+const mockOptions = [{
+  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 mockGroups = [{
+  text: 'Branches',
+  options: [{
+    text: 'main',
+    value: 'main'
+  }, {
+    text: 'feature-123',
+    value: 'feature-123'
+  }]
+}, {
+  text: 'Tags',
+  options: [{
+    text: 'v1.0',
+    value: 'v1.0'
+  }, {
+    text: 'v2.0',
+    value: 'v2.0'
+  }, {
+    text: 'v2.1',
+    value: 'v2.1'
+  }]
+}];
+
+export { mockGroups, mockOptions };

package/dist/components/base/new_dropdowns/listbox/utils.js

@@ -0,0 +1,34 @@
+import _isString from 'lodash/isString';
+
+const isOption = item => Boolean(item) && _isString(item.value);
+
+const isGroup = function () {
+  let {
+    options
+  } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return Array.isArray(options) && options.every(isOption);
+};
+
+const hasNoDuplicates = array => array.length === new Set(array).size;
+
+const flattenedOptions = items => items.flatMap(item => isOption(item) ? item : item.options);
+
+const isAllOptionsOrAllGroups = items => items.every(isOption) || items.every(isGroup);
+
+const hasUniqueValues = items => hasNoDuplicates(flattenedOptions(items).map(_ref => {
+  let {
+    value
+  } = _ref;
+  return value;
+}));
+
+const hasUniqueGroups = items => hasNoDuplicates(items.filter(isGroup).map(_ref2 => {
+  let {
+    text
+  } = _ref2;
+  return text;
+}));
+
+const itemsValidator = items => isAllOptionsOrAllGroups(items) && hasUniqueValues(items) && hasUniqueGroups(items);
+
+export { flattenedOptions, isOption, itemsValidator };

package/package.json

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

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

@@ -51,21 +51,64 @@ 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.
+Use the `items` prop to provide options to the listbox. Each item can be
+either an option or a group. Below are the expected shapes of these
+objects:
+
+```typescript
+type Option = {
+  value: string
+  text?: string
+}
+
+type Group = {
+  text: string
+  options: Array<Option>
+}
+
+type ItemsProp = Array<Option> | Array<Group>
+```
+
+#### Options
+
+The `value` property of options must be unique across all options
+provided to the listbox, as it's used as a primary key.
+
+The optional `text` property is used to render the default listbox item
+template. If you want to render a custom template for items, use the
+`list-item` scoped slot:
 
 ```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>
+  <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>
+```
+
+#### Groups
+
+Options can be contained within groups. A group has a required `text`
+property, which must be unique across all groups within the listbox, as
+it's used as a primary key. It also has a required property `items` that
+must be an array of options.
+
+Groups can be at most one level deep: a group can only contain options.
+Options and groups _cannot_ be siblings. Either all items are options,
+or they are all groups.
+
+To render custom group labels, use the `group-label` scoped slot:
+
+```html
+<gl-listbox :items="groups">
+  <template #group-label="{ group }">
+    {{ group.text }} <gl-badge size="sm">{{ group.options.length }}</gl-badge>
+  </template>
 </gl-listbox>
 ```

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

@@ -11,21 +11,8 @@ import {
 } 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',
-  },
-];
+import GlListboxGroup from './listbox_group.vue';
+import { mockOptions, mockGroups } from './mock_data';
 
 describe('GlListbox', () => {
   let wrapper;
@@ -40,19 +27,20 @@ describe('GlListbox', () => {
 
   const findBaseDropdown = () => wrapper.findComponent(GlBaseDropdown);
   const findListContainer = () => wrapper.find('[role="listbox"]');
-  const findListboxItems = () => wrapper.findAllComponents(GlListboxItem);
+  const findListboxItems = (root = wrapper) => root.findAllComponents(GlListboxItem);
+  const findListboxGroups = () => wrapper.findAllComponents(GlListboxGroup);
   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} | ${''}                   | ${''}
+      toggleText          | multiple | selected                  | expectedToggleText
+      ${'Toggle caption'} | ${true}  | ${[mockOptions[0].value]} | ${'Toggle caption'}
+      ${''}               | ${true}  | ${[mockOptions[0]].value} | ${''}
+      ${''}               | ${false} | ${mockOptions[0].value}   | ${mockOptions[0].text}
+      ${''}               | ${false} | ${''}                     | ${''}
     `('when listbox', ({ toggleText, multiple, selected, expectedToggleText }) => {
       beforeEach(() => {
-        buildWrapper({ items: mockItems, toggleText, multiple, selected });
+        buildWrapper({ items: mockOptions, toggleText, multiple, selected });
       });
 
       it(`is ${multiple ? 'multi' : 'single'}-select, toggleText is ${
@@ -77,8 +65,8 @@ describe('GlListbox', () => {
       beforeEach(() => {
         buildWrapper({
           multiple: true,
-          selected: [mockItems[1].value, mockItems[2].value],
-          items: mockItems,
+          selected: [mockOptions[1].value, mockOptions[2].value],
+          items: mockOptions,
         });
       });
 
@@ -90,28 +78,29 @@ describe('GlListbox', () => {
       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]);
+        expect(wrapper.emitted('select')[0][0]).toEqual([mockOptions[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))
+          // The first three items should now be selected.
+          expect.arrayContaining(mockOptions.slice(0, 3).map(({ value }) => value))
         );
       });
     });
 
     describe('single-select', () => {
       beforeEach(() => {
-        buildWrapper({ selected: mockItems[1].value, items: mockItems });
+        buildWrapper({ selected: mockOptions[1].value, items: mockOptions });
       });
 
       it('should throw an error when array of selections is provided', () => {
         expect(() => {
           buildWrapper({
-            selected: [mockItems[1].value, mockItems[2].value],
-            items: mockItems,
+            selected: [mockOptions[1].value, mockOptions[2].value],
+            items: mockOptions,
           });
         }).toThrowError('To allow multi-selection, please, set "multiple" property to "true"');
         expect(wrapper).toHaveLoggedVueErrors();
@@ -124,7 +113,25 @@ describe('GlListbox', () => {
       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);
+        expect(wrapper.emitted('select')[0][0]).toEqual(mockOptions[2].value);
+      });
+    });
+
+    describe('with groups', () => {
+      const selected = mockGroups[1].options[1].value;
+
+      beforeEach(() => {
+        buildWrapper({ selected, items: mockGroups });
+      });
+
+      it('should render item as selected when `selected` provided ', () => {
+        expect(findListboxItems().at(3).props('isSelected')).toBe(true);
+      });
+
+      it('should deselect previously selected and select a new item', async () => {
+        findListboxItems().at(0).vm.$emit('select', true);
+        await nextTick();
+        expect(wrapper.emitted('select')[0][0]).toEqual(mockGroups[0].options[0].value);
       });
     });
   });
@@ -133,8 +140,8 @@ describe('GlListbox', () => {
     beforeEach(async () => {
       buildWrapper({
         multiple: true,
-        items: mockItems,
-        selected: [mockItems[2].value, mockItems[1].value],
+        items: mockOptions,
+        selected: [mockOptions[2].value, mockOptions[1].value],
       });
       findBaseDropdown().vm.$emit(GL_DROPDOWN_SHOWN);
       await nextTick();
@@ -166,7 +173,8 @@ describe('GlListbox', () => {
     let thirdItem;
 
     beforeEach(() => {
-      buildWrapper({ items: mockItems });
+      // These tests are more easily written with a small list of items.
+      buildWrapper({ items: mockOptions.slice(0, 3) });
       findBaseDropdown().vm.$emit(GL_DROPDOWN_SHOWN);
       firstItem = findListItem(0);
       secondItem = findListItem(1);
@@ -233,4 +241,23 @@ describe('GlListbox', () => {
       expect(wrapper.text()).toContain(footerContent);
     });
   });
+
+  describe('with groups', () => {
+    it('renders groups of items', () => {
+      buildWrapper({ items: mockGroups });
+
+      const groups = findListboxGroups();
+
+      expect(groups.length).toBe(mockGroups.length);
+
+      const expectedNameProps = mockGroups.map((group) => group.text);
+      const actualNameProps = groups.wrappers.map((group) => group.props('name'));
+
+      expect(actualNameProps).toEqual(expectedNameProps);
+
+      mockGroups.forEach((group, i) => {
+        expect(findListboxItems(groups.at(i))).toHaveLength(group.options.length);
+      });
+    });
+  });
 });

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

@@ -9,65 +9,17 @@ import {
   GlSearchBoxByType,
   GlButtonGroup,
   GlButton,
+  GlBadge,
   GlAvatar,
 } from '../../../../index';
 import { makeContainer } from '../../../../utils/story_decorators/container';
 import readme from './listbox.md';
+import { mockOptions, mockGroups } from './mock_data';
 
 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,
+  items = mockOptions,
   category = defaultValue('category'),
   variant = defaultValue('variant'),
   size = defaultValue('size'),
@@ -137,7 +89,7 @@ export const Default = (args, { argTypes }) => ({
   },
   data() {
     return {
-      selected: defaultItems[1].value,
+      selected: mockOptions[1].value,
     };
   },
   mounted() {
@@ -170,21 +122,23 @@ export const HeaderAndFooter = (args, { argTypes }) => ({
   },
   methods: {
     selectItem(index) {
-      this.selected.push(defaultItems[index].value);
+      this.selected.push(mockOptions[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>`),
+  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',
@@ -217,33 +171,33 @@ export const CustomListItem = (args, { argTypes }) => ({
     },
   },
   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"
-        :is-check-centered="isCheckCentered"
-        :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>
+    <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"
+      :is-check-centered="isCheckCentered"
+      :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>
   `,
 });
 
@@ -258,6 +212,46 @@ CustomListItem.args = generateProps({
 });
 CustomListItem.decorators = [makeContainer({ height: '200px' })];
 
+const makeGroupedExample = (changes) => {
+  const story = (args, { argTypes }) => ({
+    props: Object.keys(argTypes),
+    components: {
+      GlBadge,
+      GlListbox,
+    },
+    data() {
+      return {
+        selected: 'v1.0',
+      };
+    },
+    mounted() {
+      if (this.startOpened) {
+        openListbox(this);
+      }
+    },
+    template: template(''),
+    ...changes,
+  });
+
+  story.args = generateProps({ items: mockGroups });
+  story.decorators = [makeContainer({ height: '280px' })];
+
+  return story;
+};
+
+export const Groups = makeGroupedExample();
+
+export const CustomGroupsAndItems = makeGroupedExample({
+  template: template(`
+    <template #group-label="{ group }">
+      {{ group.text }} <gl-badge size="sm">{{ group.options.length }}</gl-badge>
+    </template>
+    <template #list-item="{ item }">
+      {{ item.text }} <gl-badge v-if="item.value === 'main'" size="sm">default</gl-badge>
+    </template>
+  `),
+});
+
 export default {
   title: 'base/new-dropdowns/listbox',
   component: GlListbox,

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

@@ -17,8 +17,11 @@ import {
 } from '../../../../utils/constants';
 import GlBaseDropdown from '../base_dropdown/base_dropdown.vue';
 import GlListboxItem from './listbox_item.vue';
+import GlListboxGroup from './listbox_group.vue';
+import { isOption, itemsValidator, flattenedOptions } from './utils';
 
 export const ITEM_SELECTOR = '[role="option"]';
+const GROUP_TOP_BORDER_CLASSES = ['gl-border-t', 'gl-pt-3', 'gl-mt-3'];
 
 export default {
   events: {
@@ -28,6 +31,7 @@ export default {
   components: {
     GlBaseDropdown,
     GlListboxItem,
+    GlListboxGroup,
   },
   model: {
     prop: 'selected',
@@ -41,9 +45,7 @@ export default {
       type: Array,
       required: false,
       default: () => [],
-      validator: (items) => {
-        return items.every(({ value }) => typeof value === 'string');
-      },
+      validator: itemsValidator,
     },
     /**
      * array of selected items values for multi-select and selected item value for single-select
@@ -177,10 +179,17 @@ export default {
     };
   },
   computed: {
+    listboxTag() {
+      if (this.items.length === 0 || isOption(this.items[0])) return 'ul';
+      return 'div';
+    },
+    flattenedOptions() {
+      return flattenedOptions(this.items);
+    },
     listboxToggleText() {
       if (!this.toggleText) {
         if (!this.multiple && this.selectedValues.length) {
-          return this.items.find(({ value }) => value === this.selectedValues[0])?.text;
+          return this.flattenedOptions.find(({ value }) => value === this.selectedValues[0])?.text;
         }
         return '';
       }
@@ -189,7 +198,7 @@ export default {
     },
     selectedIndices() {
       return this.selectedValues
-        .map((selected) => this.items.findIndex(({ value }) => value === selected))
+        .map((selected) => this.flattenedOptions.findIndex(({ value }) => value === selected))
         .sort();
     },
   },
@@ -209,6 +218,9 @@ export default {
     },
   },
   methods: {
+    groupClasses(index) {
+      return index === 0 ? null : GROUP_TOP_BORDER_CLASSES;
+    },
     onShow() {
       this.$nextTick(() => {
         this.focusItem(this.selectedIndices[0] ?? 0, this.getFocusableListItemElements());
@@ -281,6 +293,9 @@ export default {
     isSelected(item) {
       return this.selectedValues.some((value) => value === item.value);
     },
+    isFocused(item) {
+      return this.nextFocusedItemIndex === this.flattenedOptions.indexOf(item);
+    },
     onSingleSelect(value, isSelected) {
       if (isSelected) {
         /**
@@ -303,6 +318,7 @@ export default {
         );
       }
     },
+    isOption,
   },
 };
 </script>
@@ -330,7 +346,8 @@ export default {
     <!-- @slot Content to display in dropdown header -->
     <slot name="header"></slot>
 
-    <ul
+    <component
+      :is="listboxTag"
       ref="list"
       :aria-labelledby="toggleId"
       role="listbox"
@@ -338,20 +355,46 @@ export default {
       tabindex="-1"
       @keydown="onKeydown"
     >
-      <gl-listbox-item
-        v-for="(item, index) in items"
-        :key="item.value"
-        :is-selected="isSelected(item)"
-        :is-focused="nextFocusedItemIndex === index"
-        :is-check-centered="isCheckCentered"
-        @select="onSelect(item, $event)"
-      >
-        <!-- @slot Custom template of the listbox item -->
-        <slot name="list-item" :item="item">
-          {{ item.text }}
-        </slot>
-      </gl-listbox-item>
-    </ul>
+      <template v-for="(item, index) in items">
+        <template v-if="isOption(item)">
+          <gl-listbox-item
+            :key="item.value"
+            :is-selected="isSelected(item)"
+            :is-focused="isFocused(item)"
+            :is-check-centered="isCheckCentered"
+            @select="onSelect(item, $event)"
+          >
+            <!-- @slot Custom template of the listbox item -->
+            <slot name="list-item" :item="item">
+              {{ item.text }}
+            </slot>
+          </gl-listbox-item>
+        </template>
+
+        <template v-else>
+          <gl-listbox-group :key="item.text" :name="item.text" :class="groupClasses(index)">
+            <template v-if="$scopedSlots['group-label']" #group-label>
+              <!-- @slot Custom template for group names -->
+              <slot name="group-label" :group="item"></slot>
+            </template>
+
+            <gl-listbox-item
+              v-for="option in item.options"
+              :key="option.value"
+              :is-selected="isSelected(option)"
+              :is-focused="isFocused(option)"
+              :is-check-centered="isCheckCentered"
+              @select="onSelect(option, $event)"
+            >
+              <!-- @slot Custom template of the listbox item -->
+              <slot name="list-item" :item="option">
+                {{ option.text }}
+              </slot>
+            </gl-listbox-item>
+          </gl-listbox-group>
+        </template>
+      </template>
+    </component>
     <!-- @slot Content to display in dropdown footer -->
     <slot name="footer"></slot>
   </gl-base-dropdown>

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

@@ -0,0 +1,47 @@
+import { shallowMount } from '@vue/test-utils';
+import GlListboxGroup from './listbox_group.vue';
+
+describe('GlListboxGroup', () => {
+  let wrapper;
+  const name = 'Group name';
+
+  const buildWrapper = ({ propsData, slots } = {}) => {
+    wrapper = shallowMount(GlListboxGroup, {
+      propsData: {
+        name,
+        ...propsData,
+      },
+      slots,
+    });
+  };
+
+  const findByTestId = (testid, root = wrapper) => root.find(`[data-testid="${testid}"]`);
+  const findLabelElement = () => {
+    const labelElementId = wrapper.attributes('aria-labelledby');
+    return wrapper.find(`#${labelElementId}`);
+  };
+
+  it('renders a group', () => {
+    buildWrapper();
+
+    expect(wrapper.find('ul[role="group"]').element).toBe(wrapper.element);
+  });
+
+  it('renders default slot content', () => {
+    buildWrapper({ slots: { default: '<li data-testid="default-slot-content"></li>' } });
+
+    expect(findByTestId('default-slot-content').exists()).toBe(true);
+  });
+
+  it('labels the group', () => {
+    buildWrapper();
+
+    expect(findLabelElement().text()).toBe(name);
+  });
+
+  it('allows arbitrary content for group label', () => {
+    buildWrapper({ slots: { 'group-label': '<i data-testid="custom-name"></i>' } });
+
+    expect(findByTestId('custom-name', findLabelElement()).exists()).toBe(true);
+  });
+});

package/src/components/base/new_dropdowns/listbox/listbox_group.vue

@@ -0,0 +1,24 @@
+<script>
+import { uniqueId } from 'lodash';
+
+export default {
+  props: {
+    name: {
+      type: String,
+      required: true,
+    },
+  },
+  created() {
+    this.nameId = uniqueId('gl-listbox-group-');
+  },
+};
+</script>
+
+<template>
+  <ul role="group" :aria-labelledby="nameId" class="gl-mb-0 gl-pl-0 gl-list-style-none">
+    <li :id="nameId" role="presentation" class="gl-pl-5! gl-py-2! gl-font-base gl-font-weight-bold">
+      <slot name="group-label">{{ name }}</slot>
+    </li>
+    <slot></slot>
+  </ul>
+</template>

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

@@ -0,0 +1,68 @@
+export const mockOptions = [
+  {
+    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',
+  },
+];
+
+export const mockGroups = [
+  {
+    text: 'Branches',
+    options: [
+      { text: 'main', value: 'main' },
+      { text: 'feature-123', value: 'feature-123' },
+    ],
+  },
+  {
+    text: 'Tags',
+    options: [
+      { text: 'v1.0', value: 'v1.0' },
+      { text: 'v2.0', value: 'v2.0' },
+      { text: 'v2.1', value: 'v2.1' },
+    ],
+  },
+];

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

@@ -0,0 +1,21 @@
+import { isString } from 'lodash';
+
+const isOption = (item) => Boolean(item) && isString(item.value);
+
+const isGroup = ({ options } = {}) => Array.isArray(options) && options.every(isOption);
+
+const hasNoDuplicates = (array) => array.length === new Set(array).size;
+
+const flattenedOptions = (items) => items.flatMap((item) => (isOption(item) ? item : item.options));
+
+const isAllOptionsOrAllGroups = (items) => items.every(isOption) || items.every(isGroup);
+
+const hasUniqueValues = (items) =>
+  hasNoDuplicates(flattenedOptions(items).map(({ value }) => value));
+
+const hasUniqueGroups = (items) => hasNoDuplicates(items.filter(isGroup).map(({ text }) => text));
+
+const itemsValidator = (items) =>
+  isAllOptionsOrAllGroups(items) && hasUniqueValues(items) && hasUniqueGroups(items);
+
+export { isOption, itemsValidator, flattenedOptions };

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

@@ -0,0 +1,56 @@
+import { isOption, flattenedOptions, itemsValidator } from './utils';
+import { mockOptions, mockGroups } from './mock_data';
+
+describe('isOption', () => {
+  it.each([null, undefined, {}, { value: null }, { text: 'group', options: [] }])(
+    'isOption(%p) === false',
+    (notAnOption) => {
+      expect(isOption(notAnOption)).toBe(false);
+    }
+  );
+
+  it.each([{ value: '' }, { value: 'foo', text: 'bar' }, { value: 'qux', foo: true }])(
+    'isOption(%p) === true',
+    (option) => {
+      expect(isOption(option)).toBe(true);
+    }
+  );
+});
+
+describe('flattenedOptions', () => {
+  it('returns flattened items as-is', () => {
+    expect(flattenedOptions(mockOptions)).toEqual(mockOptions);
+  });
+
+  it('returns flattened items given groups items', () => {
+    expect(flattenedOptions(mockGroups)).toEqual([
+      ...mockGroups[0].options,
+      ...mockGroups[1].options,
+    ]);
+  });
+
+  it('returns flattened items given mixed items/groups', () => {
+    expect(flattenedOptions([...mockOptions, ...mockGroups])).toEqual([
+      ...mockOptions,
+      ...mockGroups[0].options,
+      ...mockGroups[1].options,
+    ]);
+  });
+});
+
+describe('itemsValidator', () => {
+  it.each`
+    description                         | value                                                                                   | expected
+    ${'valid flat items'}               | ${mockOptions}                                                                          | ${true}
+    ${'valid grouped items'}            | ${mockGroups}                                                                           | ${true}
+    ${'empty list'}                     | ${[]}                                                                                   | ${true}
+    ${'invalid items'}                  | ${[{ foo: true }]}                                                                      | ${false}
+    ${'group with invalid items'}       | ${[{ text: 'foo', options: [{ foo: true }] }]}                                          | ${false}
+    ${'non-unique items'}               | ${[{ value: 'a' }, { value: 'a' }]}                                                     | ${false}
+    ${'non-unique items across groups'} | ${[{ text: 'a', options: [{ value: 'b' }] }, { text: 'z', options: [{ value: 'b' }] }]} | ${false}
+    ${'non-unique groups'}              | ${[{ text: 'a', options: [] }, { text: 'a', options: [] }]}                             | ${false}
+    ${'sibling groups and options'}     | ${[...mockOptions, ...mockGroups]}                                                      | ${false}
+  `('returns $expected given $description', ({ value, expected }) => {
+    expect(itemsValidator(value)).toBe(expected);
+  });
+});