@gitlab/ui 44.1.0 → 45.0.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [45.0.0](https://gitlab.com/gitlab-org/gitlab-ui/compare/v44.1.0...v45.0.0) (2022-10-05)
+
+
+### Features
+
+* **GlListbox:** add support for listbox filtering ([c6edcc4](https://gitlab.com/gitlab-org/gitlab-ui/commit/c6edcc44966891ce4e2682c9b9785e6bd16ae642))
+
+
+### BREAKING CHANGES
+
+* **GlListbox:** `ariaLabelledby` property was renamed
+to `toggleAriaLabelledBy `for better consistency
+with a new `listAriaLabelledBy` property
+
 # [44.1.0](https://gitlab.com/gitlab-org/gitlab-ui/compare/v44.0.0...v44.1.0) (2022-10-05)
 
 

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

@@ -177,6 +177,14 @@ var script = {
       }
     },
 
+    open() {
+      if (this.visible) {
+        return;
+      }
+
+      this.toggle();
+    },
+
     close() {
       if (!this.visible) {
         return;

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

@@ -3,6 +3,8 @@ import _clamp from 'lodash/clamp';
 import { stopEvent } from '../../../../utils/utils';
 import { GL_DROPDOWN_SHOWN, GL_DROPDOWN_HIDDEN, HOME, END, ARROW_UP, ARROW_DOWN } from '../constants';
 import { buttonCategoryOptions, dropdownVariantOptions, buttonSizeOptions } from '../../../../utils/constants';
+import GlLoadingIcon from '../../loading_icon/loading_icon';
+import GlSearchBoxByType from '../../search_box_by_type/search_box_by_type';
 import GlBaseDropdown from '../base_dropdown/base_dropdown';
 import GlListboxItem from './listbox_item';
 import GlListboxGroup from './listbox_group';
@@ -11,6 +13,7 @@ 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'];
+const SEARCH_INPUT_SELECTOR = '.gl-search-box-by-type-input';
 var script = {
   events: {
     GL_DROPDOWN_SHOWN,
@@ -19,7 +22,9 @@ var script = {
   components: {
     GlBaseDropdown,
     GlListboxItem,
-    GlListboxGroup
+    GlListboxGroup,
+    GlSearchBoxByType,
+    GlLoadingIcon
   },
   model: {
     prop: 'selected',
@@ -122,6 +127,7 @@ var script = {
 
     /**
      * Set to "true" when dropdown content (items) is loading
+     * It will render a small loader in the dropdown toggle and make it disabled
      */
     loading: {
       type: Boolean,
@@ -167,11 +173,50 @@ var script = {
 
     /**
      * The `aria-labelledby` attribute value for the toggle button
+     * Provide the string of ids seperated by space
      */
-    ariaLabelledby: {
+    toggleAriaLabelledBy: {
       type: String,
       required: false,
       default: null
+    },
+
+    /**
+     * The `aria-labelledby` attribute value for the list of options
+     * Provide the string of ids seperated by space
+     */
+    listAriaLabelledBy: {
+      type: String,
+      required: false,
+      default: null
+    },
+
+    /**
+     * Enable search
+     */
+    searchable: {
+      type: Boolean,
+      required: false,
+      default: false
+    },
+
+    /**
+     * Set to "true" when items search is in progress.
+     * It will display loading icon below the search input
+     */
+    searching: {
+      type: Boolean,
+      required: false,
+      default: false
+    },
+
+    /**
+     * Message to be displayed when filtering produced no results
+     */
+    noResultsText: {
+      type: String,
+      required: false,
+      default: 'No results found'
     }
   },
 
@@ -179,7 +224,9 @@ var script = {
     return {
       selectedValues: [],
       toggleId: _uniqueId('dropdown-toggle-btn-'),
-      nextFocusedItemIndex: null
+      listboxId: _uniqueId('listbox-'),
+      nextFocusedItemIndex: null,
+      searchStr: ''
     };
   },
 
@@ -219,6 +266,18 @@ var script = {
         } = _ref2;
         return value === selected;
       })).sort();
+    },
+
+    showList() {
+      return this.flattenedOptions.length && !this.searching;
+    },
+
+    showNoResultsText() {
+      return !this.flattenedOptions.length && !this.searching;
+    },
+
+    announceSRSearchResults() {
+      return this.searchable && !this.showNoResultsText && this.$scopedSlots['search-summary-sr-only'];
     }
 
   },
@@ -241,21 +300,34 @@ var script = {
     }
   },
   methods: {
+    open() {
+      this.$refs.baseDropdown.open();
+    },
+
+    close() {
+      this.$refs.baseDropdown.close();
+    },
+
     groupClasses(index) {
       return index === 0 ? null : GROUP_TOP_BORDER_CLASSES;
     },
 
     onShow() {
       this.$nextTick(() => {
-        var _this$selectedIndices;
+        if (this.searchable) {
+          this.focusSearchInput();
+        } else {
+          var _this$selectedIndices;
 
-        this.focusItem((_this$selectedIndices = this.selectedIndices[0]) !== null && _this$selectedIndices !== void 0 ? _this$selectedIndices : 0, this.getFocusableListItemElements());
+          this.focusItem((_this$selectedIndices = this.selectedIndices[0]) !== null && _this$selectedIndices !== void 0 ? _this$selectedIndices : 0, this.getFocusableListItemElements());
+        }
         /**
          * Emitted when dropdown is shown
          *
          * @event shown
          */
 
+
         this.$emit(GL_DROPDOWN_SHOWN);
       });
     },
@@ -272,20 +344,34 @@ var script = {
 
     onKeydown(event) {
       const {
-        code
+        code,
+        target
       } = event;
       const elements = this.getFocusableListItemElements();
       if (elements.length < 1) return;
       let stop = true;
+      const isSearchInput = target.matches(SEARCH_INPUT_SELECTOR);
 
       if (code === HOME) {
         this.focusItem(0, elements);
       } else if (code === END) {
         this.focusItem(elements.length - 1, elements);
       } else if (code === ARROW_UP) {
-        this.focusNextItem(event, elements, -1);
+        if (isSearchInput) {
+          return;
+        }
+
+        if (this.searchable && elements.indexOf(target) === 0) {
+          this.focusSearchInput();
+        } else {
+          this.focusNextItem(event, elements, -1);
+        }
       } else if (code === ARROW_DOWN) {
-        this.focusNextItem(event, elements, 1);
+        if (isSearchInput) {
+          this.focusItem(0, elements);
+        } else {
+          this.focusNextItem(event, elements, 1);
+        }
       } else {
         stop = false;
       }
@@ -296,8 +382,10 @@ var script = {
     },
 
     getFocusableListItemElements() {
-      const items = this.$refs.list.querySelectorAll(ITEM_SELECTOR);
-      return Array.from(items);
+      var _this$$refs$list;
+
+      const items = (_this$$refs$list = this.$refs.list) === null || _this$$refs$list === void 0 ? void 0 : _this$$refs$list.querySelectorAll(ITEM_SELECTOR);
+      return Array.from(items || []);
     },
 
     focusNextItem(event, elements, offset) {
@@ -320,15 +408,15 @@ var script = {
       });
     },
 
-    onSelect(_ref3, isSelected) {
-      let {
-        value
-      } = _ref3;
+    focusSearchInput() {
+      this.$refs.searchBox.focusInput();
+    },
 
+    onSelect(item, isSelected) {
       if (this.multiple) {
-        this.onMultiSelect(value, isSelected);
+        this.onMultiSelect(item.value, isSelected);
       } else {
-        this.onSingleSelect(value, isSelected);
+        this.onSingleSelect(item.value, isSelected);
       }
     },
 
@@ -361,6 +449,16 @@ var script = {
       }
     },
 
+    search(searchTerm) {
+      /**
+       * Emitted when the search query string is changed
+       *
+       * @event search
+       * @type {string}
+       */
+      this.$emit('search', searchTerm);
+    },
+
     isOption
   }
 };
@@ -369,7 +467,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(_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_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.toggleAriaLabelledBy,"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(" "),(_vm.searchable)?_c('div',{staticClass:"gl-border-b-1 gl-border-b-solid gl-border-b-gray-200"},[_c('gl-search-box-by-type',{ref:"searchBox",attrs:{"aria-owns":_vm.listboxId,"data-testid":"listbox-search-input"},on:{"input":_vm.search,"keydown":_vm.onKeydown},model:{value:(_vm.searchStr),callback:function ($$v) {_vm.searchStr=$$v;},expression:"searchStr"}}),_vm._v(" "),(_vm.searching)?_c('gl-loading-icon',{staticClass:"gl-my-3",attrs:{"data-testid":"listbox-search-loader","size":"md"}}):_vm._e()],1):_vm._e(),_vm._v(" "),(_vm.showList)?_c(_vm.listboxTag,{ref:"list",tag:"component",staticClass:"gl-new-dropdown-contents gl-list-style-none gl-pl-0 gl-mb-0",attrs:{"id":"listbox","aria-labelledby":_vm.listAriaLabelledBy || _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._e(),_vm._v(" "),(_vm.announceSRSearchResults)?_c('span',{staticClass:"gl-sr-only",attrs:{"data-testid":"listbox-number-of-results","aria-live":"assertive"}},[_vm._t("search-summary-sr-only")],2):(_vm.showNoResultsText)?_c('div',{staticClass:"gl-pl-7 gl-pr-5 gl-pt-3 gl-font-base gl-text-gray-600",attrs:{"aria-live":"assertive","data-testid":"listbox-no-results-text"}},[_vm._v("\n    "+_vm._s(_vm.noResultsText)+"\n  ")]):_vm._e(),_vm._v(" "),_vm._t("footer")],2)};
 var __vue_staticRenderFns__ = [];
 
   /* style */
@@ -402,4 +500,4 @@ var __vue_staticRenderFns__ = [];
   );
 
 export default __vue_component__;
-export { ITEM_SELECTOR };
+export { ITEM_SELECTOR, SEARCH_INPUT_SELECTOR };

package/package.json

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

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

@@ -162,6 +162,12 @@ export default {
         this.$emit(GL_DROPDOWN_HIDDEN);
       }
     },
+    open() {
+      if (this.visible) {
+        return;
+      }
+      this.toggle();
+    },
     close() {
       if (!this.visible) {
         return;

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

@@ -112,3 +112,25 @@ To render custom group labels, use the `group-label` scoped slot:
   </template>
 </gl-listbox>
 ```
+
+#### Search
+
+To filter out items by  search query set `searchable` property to `true`.
+Listbox will render the search field and will emit `search` event with the `searchQuery` value.
+Performing the search is the responsibility of the listbox's consumer component.
+When performing search set `searching` prop to `true` - this will render the loader
+while search is in progress instead of the list of items.
+To update content of the listbox, toggle the `searching` property
+and update the `items` property with a new array. Be sure to debounce (or
+similar) the `search` event handler to avoid rendering stale results.
+To improve the accessibility, provide the `search-summary-sr-only` scoped slot
+with a number of found search results text.
+Screen reader will announce this text when the list is updated.
+
+```html
+<gl-listbox :items="items" searchable>
+  <template #search-summary-sr-only>
+    5 users found
+  </template>
+</gl-listbox>
+```

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

@@ -30,6 +30,10 @@ describe('GlListbox', () => {
   const findListboxItems = (root = wrapper) => root.findAllComponents(GlListboxItem);
   const findListboxGroups = () => wrapper.findAllComponents(GlListboxGroup);
   const findListItem = (index) => findListboxItems().at(index).find(ITEM_SELECTOR);
+  const findSearchBox = () => wrapper.find("[data-testid='listbox-search-input']");
+  const findNoResultsText = () => wrapper.find("[data-testid='listbox-no-results-text']");
+  const findLoadingIcon = () => wrapper.find("[data-testid='listbox-search-loader']");
+  const findSRNumberOfResultsText = () => wrapper.find("[data-testid='listbox-number-of-results']");
 
   describe('toggle text', () => {
     describe.each`
@@ -53,11 +57,17 @@ describe('GlListbox', () => {
 
   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();
+      await buildWrapper({ items: mockOptions });
       expect(findBaseDropdown().props('toggleId')).toBe(
         findListContainer().attributes('aria-labelledby')
       );
     });
+
+    it('should reference `listAriaLabelledby`', async () => {
+      const listAriaLabelledBy = 'first-label-id second-label-id';
+      await buildWrapper({ items: mockOptions, listAriaLabelledBy });
+      expect(findListContainer().attributes('aria-labelledby')).toBe(listAriaLabelledBy);
+    });
   });
 
   describe('selecting items', () => {
@@ -137,23 +147,36 @@ describe('GlListbox', () => {
   });
 
   describe('onShow', () => {
-    beforeEach(async () => {
+    let focusSpy;
+
+    const showDropdown = async ({ searchable = false } = {}) => {
       buildWrapper({
         multiple: true,
         items: mockOptions,
         selected: [mockOptions[2].value, mockOptions[1].value],
+        searchable,
       });
+      if (searchable) {
+        focusSpy = jest.spyOn(wrapper.vm.$refs.searchBox, 'focusInput');
+      }
       findBaseDropdown().vm.$emit(GL_DROPDOWN_SHOWN);
       await nextTick();
-    });
+    };
 
-    it('should re-emit the event', () => {
+    it('should re-emit the event', async () => {
+      await showDropdown();
       expect(wrapper.emitted(GL_DROPDOWN_SHOWN)).toHaveLength(1);
     });
 
-    it('should focus the first selected item', () => {
+    it('should focus the first selected item', async () => {
+      await showDropdown();
       expect(findListboxItems().at(1).find(ITEM_SELECTOR).element).toHaveFocus();
     });
+
+    it('should focus the search input when search is enabled', async () => {
+      await showDropdown({ searchable: true });
+      expect(focusSpy).toHaveBeenCalled();
+    });
   });
 
   describe('onHide', () => {
@@ -181,7 +204,7 @@ describe('GlListbox', () => {
       thirdItem = findListItem(2);
     });
 
-    it('should move the focus down the list of items on `arrow down` and stop on the last item', async () => {
+    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();
@@ -191,7 +214,7 @@ describe('GlListbox', () => {
       expect(thirdItem.element).toHaveFocus();
     });
 
-    it('should move the focus up the list of items on `arrow up` and stop on the first item', async () => {
+    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();
@@ -220,6 +243,23 @@ describe('GlListbox', () => {
       await thirdItem.trigger('keydown', { code: HOME });
       expect(firstItem.element).toHaveFocus();
     });
+
+    describe('when `searchable` is enabled', () => {
+      it('should move focus to the first item on search input `ARROW_DOWN`', async () => {
+        buildWrapper({ items: mockOptions, searchable: true });
+        findBaseDropdown().vm.$emit(GL_DROPDOWN_SHOWN);
+        findSearchBox().trigger('keydown', { code: ARROW_DOWN });
+        expect(firstItem.element).toHaveFocus();
+      });
+
+      it('should move focus to the search input on first item `ARROW_UP', async () => {
+        buildWrapper({ items: mockOptions, searchable: true });
+        findBaseDropdown().vm.$emit(GL_DROPDOWN_SHOWN);
+        const focusSpy = jest.spyOn(wrapper.vm.$refs.searchBox, 'focusInput');
+        await firstItem.trigger('keydown', { code: ARROW_UP });
+        expect(focusSpy).toHaveBeenCalled();
+      });
+    });
   });
 
   describe('when the header slot content is provided', () => {
@@ -260,4 +300,58 @@ describe('GlListbox', () => {
       });
     });
   });
+
+  describe('when `searchable` is enabled', () => {
+    it('should render the search box', () => {
+      buildWrapper({ items: mockOptions, searchable: true });
+
+      expect(findSearchBox().exists()).toBe(true);
+    });
+
+    it('should emit the search value when typing in the search box', async () => {
+      buildWrapper({ items: mockOptions, searchable: true });
+
+      const searchStr = 'search  value';
+      findSearchBox().vm.$emit('input', searchStr);
+      await nextTick();
+      expect(wrapper.emitted('search')[0][0]).toEqual(searchStr);
+    });
+
+    it('should not render the loading icon and render the list if NOT searching', () => {
+      buildWrapper({ items: mockOptions, searchable: true });
+
+      expect(findLoadingIcon().exists()).toBe(false);
+      expect(findListContainer().exists()).toBe(true);
+    });
+
+    it('should render the loading icon and NOT render the list when searching', () => {
+      buildWrapper({ items: mockOptions, searchable: true, searching: true });
+
+      expect(findLoadingIcon().exists()).toBe(true);
+      expect(findListContainer().exists()).toBe(false);
+    });
+
+    it('should display `noResultText` if no items found', () => {
+      const noResultsText = 'Nothing found';
+      buildWrapper({ items: [], searchable: true, searching: false, noResultsText });
+
+      expect(findLoadingIcon().exists()).toBe(false);
+      expect(findListContainer().exists()).toBe(false);
+      expect(findNoResultsText().text()).toBe(noResultsText);
+    });
+
+    describe('Screen reader text with number of search results', () => {
+      it('when the #search-summary-sr-only slot content is provided', () => {
+        const searchResultsContent = 'Found 5 results';
+        const slots = { 'search-summary-sr-only': searchResultsContent };
+        buildWrapper({ items: mockOptions, searchable: true, searching: false }, slots);
+        expect(findSRNumberOfResultsText().text()).toBe(searchResultsContent);
+      });
+
+      it('should not display SR text when no matching results', () => {
+        buildWrapper({ items: [], searchable: true, searching: false });
+        expect(findSRNumberOfResultsText().exists()).toBe(false);
+      });
+    });
+  });
 });

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

@@ -15,6 +15,7 @@ import {
 import { makeContainer } from '../../../../utils/story_decorators/container';
 import readme from './listbox.md';
 import { mockOptions, mockGroups } from './mock_data';
+import { flattenedOptions } from './utils';
 
 const defaultValue = (prop) => GlListbox.props[prop].default;
 
@@ -25,6 +26,9 @@ const generateProps = ({
   size = defaultValue('size'),
   disabled = defaultValue('disabled'),
   loading = defaultValue('loading'),
+  searchable = defaultValue('searchable'),
+  searching = defaultValue('searching'),
+  noResultsText = defaultValue('noResultsText'),
   noCaret = defaultValue('noCaret'),
   right = defaultValue('right'),
   toggleText,
@@ -32,7 +36,8 @@ const generateProps = ({
   icon = '',
   multiple = defaultValue('multiple'),
   isCheckCentered = defaultValue('isCheckCentered'),
-  ariaLabelledby,
+  toggleAriaLabelledBy,
+  listAriaLabelledBy,
   startOpened = true,
 } = {}) => ({
   items,
@@ -41,6 +46,9 @@ const generateProps = ({
   size,
   disabled,
   loading,
+  searchable,
+  searching,
+  noResultsText,
   noCaret,
   right,
   toggleText,
@@ -48,12 +56,15 @@ const generateProps = ({
   icon,
   multiple,
   isCheckCentered,
-  ariaLabelledby,
+  toggleAriaLabelledBy,
+  listAriaLabelledBy,
   startOpened,
 });
 
 function openListbox(component) {
-  component.$nextTick(() => component.$el.querySelector('.dropdown-toggle').click());
+  component.$nextTick(() => {
+    component.$refs.listbox.open();
+  });
 }
 
 const template = (content, label = '') => `
@@ -61,6 +72,7 @@ const template = (content, label = '') => `
     ${label}
     <br/>
     <gl-listbox
+      ref="listbox"
       v-model="selected"
       :items="items"
       :category="category"
@@ -68,6 +80,9 @@ const template = (content, label = '') => `
       :size="size"
       :disabled="disabled"
       :loading="loading"
+      :searchable="searchable"
+      :searching="searching"
+      :no-results-text="noResultsText"
       :no-caret="noCaret"
       :right="right"
       :toggle-text="toggleText"
@@ -75,7 +90,8 @@ const template = (content, label = '') => `
       :icon="icon"
       :multiple="multiple"
       :is-check-centered="isCheckCentered"
-      :aria-labelledby="ariaLabelledby"
+      :toggle-aria-labelled-by="toggleAriaLabelledBy"
+      :list-aria-labelled-by="listAriaLabelledBy"
     >
       ${content}
     </gl-listbox>
@@ -99,7 +115,7 @@ export const Default = (args, { argTypes }) => ({
   },
   template: template('', `<span class="gl-my-0" id="listbox-label">Select a department</span>`),
 });
-Default.args = generateProps({ ariaLabelledby: 'listbox-label' });
+Default.args = generateProps({ toggleAriaLabelledBy: 'listbox-label' });
 Default.decorators = [makeContainer({ height: '370px' })];
 
 export const HeaderAndFooter = (args, { argTypes }) => ({
@@ -125,9 +141,9 @@ export const HeaderAndFooter = (args, { argTypes }) => ({
       this.selected.push(mockOptions[index].value);
     },
   },
-  template: template(`
-    <template #header>
-      <gl-search-box-by-type/>
+  template: template(
+    `<template #header>
+        <p class="gl-font-weight-bold gl-font-sm gl-m-0 gl-text-center gl-py-2 gl-border-1 gl-border-b-solid gl-border-gray-200">Assign to department</p>
     </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">
@@ -138,7 +154,8 @@ export const HeaderAndFooter = (args, { argTypes }) => ({
         </gl-button-group>
       </div>
     </template>
-  `),
+  `
+  ),
 });
 HeaderAndFooter.args = generateProps({
   toggleText: 'Header and Footer',
@@ -172,6 +189,7 @@ export const CustomListItem = (args, { argTypes }) => ({
   },
   template: `
     <gl-listbox
+      ref="listbox"
       v-model="selected"
       :items="items"
       :category="category"
@@ -179,6 +197,9 @@ export const CustomListItem = (args, { argTypes }) => ({
       :size="size"
       :disabled="disabled"
       :loading="loading"
+      :searchable="searchable"
+      :searching="searching"
+      :no-results-text="noResultsText"
       :no-caret="noCaret"
       :right="right"
       :toggle-text="headerText"
@@ -186,24 +207,30 @@ export const CustomListItem = (args, { argTypes }) => ({
       :icon="icon"
       :multiple="multiple"
       :is-check-centered="isCheckCentered"
-      :aria-labelledby="ariaLabelledby"
+      :toggle-aria-labelled-by="toggleAriaLabelledBy"
+      :list-aria-labelled-by="listAriaLabelledBy"
     >
-      <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>
   `,
 });
 
 CustomListItem.args = generateProps({
   items: [
-    { value: 'mikegreiling', text: 'Mike Greiling', secondaryText: '@mikegreiling', icon: 'foo' },
+    {
+      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' },
   ],
@@ -283,3 +310,200 @@ export default {
     },
   },
 };
+
+export const Searchable = (args, { argTypes }) => ({
+  props: Object.keys(argTypes),
+  components: {
+    GlListbox,
+  },
+  data() {
+    return {
+      selected: mockOptions[1].value,
+      filteredItems: mockOptions,
+      searchInProgress: false,
+      timeoutId: null,
+      headerId: 'listbox-header',
+    };
+  },
+  mounted() {
+    if (this.startOpened) {
+      openListbox(this);
+    }
+  },
+  methods: {
+    filterList(searchTerm) {
+      if (this.timeoutId) {
+        clearTimeout(this.timeoutId);
+      }
+      this.searchInProgress = true;
+
+      // eslint-disable-next-line no-restricted-globals
+      this.timeoutId = setTimeout(() => {
+        this.filteredItems = this.items.filter(({ text }) =>
+          text.toLowerCase().includes(searchTerm.toLowerCase())
+        );
+
+        this.searchInProgress = false;
+      }, 2000);
+    },
+  },
+  computed: {
+    customToggleText() {
+      let toggleText = 'Search for department';
+      const selectedValues = Array.isArray(this.selected) ? this.selected : [this.selected];
+
+      if (selectedValues.length === 1) {
+        toggleText = this.items.find(({ value }) => value === selectedValues[0]).text;
+      } else {
+        toggleText = `Selected ${selectedValues.length} departments`;
+      }
+
+      return toggleText;
+    },
+    numberOfSearchResults() {
+      return this.filteredItems.length === 1 ? '1 result' : `${this.filteredItems.length} results`;
+    },
+  },
+  template: `
+    <gl-listbox
+      ref="listbox"
+      v-model="selected"
+      :items="filteredItems"
+      :category="category"
+      :variant="variant"
+      :size="size"
+      :disabled="disabled"
+      :loading="loading"
+      :no-caret="noCaret"
+      :right="right"
+      :toggle-text="customToggleText"
+      :text-sr-only="textSrOnly"
+      :icon="icon"
+      :multiple="multiple"
+      :is-check-centered="isCheckCentered"
+      :toggle-aria-labelled-by="toggleAriaLabelledBy"
+      :list-aria-labelled-by="headerId"
+      :searchable="searchable"
+      :searching="searchInProgress"
+      :no-results-text="noResultsText"
+      @search="filterList"
+    >
+      <template #header>
+        <p :id="headerId"
+          class="gl-font-weight-bold gl-font-sm gl-m-0 gl-text-center gl-py-2 gl-border-1 gl-border-b-solid gl-border-gray-200">
+          Assign to department</p>
+      </template>
+      <template #search-summary-sr-only>
+        {{ numberOfSearchResults }}
+      </template>
+    </gl-listbox>
+  `,
+});
+Searchable.args = generateProps({ searchable: true });
+Searchable.decorators = [makeContainer({ height: '370px' })];
+
+export const SearchableGroups = (args, { argTypes }) => ({
+  props: Object.keys(argTypes),
+  components: {
+    GlListbox,
+  },
+  data() {
+    return {
+      selected: mockGroups[1].options[0].value,
+      filteredGroupOptions: mockGroups,
+      searchInProgress: false,
+      timeoutId: null,
+      headerId: 'listbox-header',
+    };
+  },
+  mounted() {
+    if (this.startOpened) {
+      openListbox(this);
+    }
+  },
+  computed: {
+    flattenedOptions() {
+      return flattenedOptions(this.items);
+    },
+    flattenedFilteredOptions() {
+      return flattenedOptions(this.filteredGroupOptions);
+    },
+    customToggleText() {
+      let toggleText = 'Search for department';
+      const selectedValues = Array.isArray(this.selected) ? this.selected : [this.selected];
+
+      if (selectedValues.length === 1) {
+        toggleText = this.flattenedOptions.find(({ value }) => value === selectedValues[0]).text;
+      } else {
+        toggleText = `Selected ${selectedValues.length} departments`;
+      }
+
+      return toggleText;
+    },
+    numberOfSearchResults() {
+      return this.flattenedFilteredOptions.length === 1
+        ? '1 result'
+        : `${this.flattenedFilteredOptions.length} results`;
+    },
+  },
+  methods: {
+    filterList(searchTerm) {
+      if (this.timeoutId) {
+        clearTimeout(this.timeoutId);
+      }
+      this.searchInProgress = true;
+
+      // eslint-disable-next-line no-restricted-globals
+      this.timeoutId = setTimeout(() => {
+        this.filteredGroupOptions = this.items
+          .map(({ text, options }) => {
+            return {
+              text,
+              options: options.filter((option) =>
+                option.text.toLowerCase().includes(searchTerm.toLowerCase())
+              ),
+            };
+          })
+          .filter(({ options }) => options.length);
+
+        this.searchInProgress = false;
+      }, 2000);
+    },
+  },
+  template: `
+    <gl-listbox
+      ref="listbox"
+      v-model="selected"
+      :items="filteredGroupOptions"
+      :category="category"
+      :variant="variant"
+      :size="size"
+      :disabled="disabled"
+      :loading="loading"
+      :no-caret="noCaret"
+      :right="right"
+      :toggle-text="customToggleText"
+      :text-sr-only="textSrOnly"
+      :icon="icon"
+      :multiple="multiple"
+      :is-check-centered="isCheckCentered"
+      :toggle-aria-labelled-by="toggleAriaLabelledBy"
+      :list-aria-labelled-by="headerId"
+      :searching="searchInProgress"
+      :no-results-text="noResultsText"
+      :searchable="searchable"
+      @search="filterList"
+    >
+      <template #header>
+        <p :id="headerId"
+          class="gl-font-weight-bold gl-font-sm gl-m-0 gl-text-center gl-py-2 gl-border-1 gl-border-b-solid gl-border-gray-200">
+          Assign to department</p>
+      </template>
+      <template #search-summary-sr-only>
+        {{ numberOfSearchResults }}
+      </template>
+    </gl-listbox>
+  `,
+});
+SearchableGroups.args = generateProps({ searchable: true, items: mockGroups });
+SearchableGroups.decorators = [makeContainer({ height: '370px' })];

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

@@ -15,6 +15,8 @@ import {
   buttonSizeOptions,
   dropdownVariantOptions,
 } from '../../../../utils/constants';
+import GlLoadingIcon from '../../loading_icon/loading_icon.vue';
+import GlSearchBoxByType from '../../search_box_by_type/search_box_by_type.vue';
 import GlBaseDropdown from '../base_dropdown/base_dropdown.vue';
 import GlListboxItem from './listbox_item.vue';
 import GlListboxGroup from './listbox_group.vue';
@@ -22,6 +24,7 @@ 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 const SEARCH_INPUT_SELECTOR = '.gl-search-box-by-type-input';
 
 export default {
   events: {
@@ -32,6 +35,8 @@ export default {
     GlBaseDropdown,
     GlListboxItem,
     GlListboxGroup,
+    GlSearchBoxByType,
+    GlLoadingIcon,
   },
   model: {
     prop: 'selected',
@@ -124,6 +129,7 @@ export default {
     },
     /**
      * Set to "true" when dropdown content (items) is loading
+     * It will render a small loader in the dropdown toggle and make it disabled
      */
     loading: {
       type: Boolean,
@@ -164,18 +170,55 @@ export default {
     },
     /**
      * The `aria-labelledby` attribute value for the toggle button
+     * Provide the string of ids seperated by space
      */
-    ariaLabelledby: {
+    toggleAriaLabelledBy: {
       type: String,
       required: false,
       default: null,
     },
+    /**
+     * The `aria-labelledby` attribute value for the list of options
+     * Provide the string of ids seperated by space
+     */
+    listAriaLabelledBy: {
+      type: String,
+      required: false,
+      default: null,
+    },
+    /**
+     * Enable search
+     */
+    searchable: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    /**
+     * Set to "true" when items search is in progress.
+     * It will display loading icon below the search input
+     */
+    searching: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    /**
+     * Message to be displayed when filtering produced no results
+     */
+    noResultsText: {
+      type: String,
+      required: false,
+      default: 'No results found',
+    },
   },
   data() {
     return {
       selectedValues: [],
       toggleId: uniqueId('dropdown-toggle-btn-'),
+      listboxId: uniqueId('listbox-'),
       nextFocusedItemIndex: null,
+      searchStr: '',
     };
   },
   computed: {
@@ -201,6 +244,17 @@ export default {
         .map((selected) => this.flattenedOptions.findIndex(({ value }) => value === selected))
         .sort();
     },
+    showList() {
+      return this.flattenedOptions.length && !this.searching;
+    },
+    showNoResultsText() {
+      return !this.flattenedOptions.length && !this.searching;
+    },
+    announceSRSearchResults() {
+      return (
+        this.searchable && !this.showNoResultsText && this.$scopedSlots['search-summary-sr-only']
+      );
+    },
   },
   watch: {
     selected: {
@@ -218,12 +272,22 @@ export default {
     },
   },
   methods: {
+    open() {
+      this.$refs.baseDropdown.open();
+    },
+    close() {
+      this.$refs.baseDropdown.close();
+    },
     groupClasses(index) {
       return index === 0 ? null : GROUP_TOP_BORDER_CLASSES;
     },
     onShow() {
       this.$nextTick(() => {
-        this.focusItem(this.selectedIndices[0] ?? 0, this.getFocusableListItemElements());
+        if (this.searchable) {
+          this.focusSearchInput();
+        } else {
+          this.focusItem(this.selectedIndices[0] ?? 0, this.getFocusableListItemElements());
+        }
         /**
          * Emitted when dropdown is shown
          *
@@ -242,21 +306,33 @@ export default {
       this.nextFocusedItemIndex = null;
     },
     onKeydown(event) {
-      const { code } = event;
+      const { code, target } = event;
       const elements = this.getFocusableListItemElements();
 
       if (elements.length < 1) return;
 
       let stop = true;
+      const isSearchInput = target.matches(SEARCH_INPUT_SELECTOR);
 
       if (code === HOME) {
         this.focusItem(0, elements);
       } else if (code === END) {
         this.focusItem(elements.length - 1, elements);
       } else if (code === ARROW_UP) {
-        this.focusNextItem(event, elements, -1);
+        if (isSearchInput) {
+          return;
+        }
+        if (this.searchable && elements.indexOf(target) === 0) {
+          this.focusSearchInput();
+        } else {
+          this.focusNextItem(event, elements, -1);
+        }
       } else if (code === ARROW_DOWN) {
-        this.focusNextItem(event, elements, 1);
+        if (isSearchInput) {
+          this.focusItem(0, elements);
+        } else {
+          this.focusNextItem(event, elements, 1);
+        }
       } else {
         stop = false;
       }
@@ -266,8 +342,8 @@ export default {
       }
     },
     getFocusableListItemElements() {
-      const items = this.$refs.list.querySelectorAll(ITEM_SELECTOR);
-      return Array.from(items);
+      const items = this.$refs.list?.querySelectorAll(ITEM_SELECTOR);
+      return Array.from(items || []);
     },
     focusNextItem(event, elements, offset) {
       const { target } = event;
@@ -283,11 +359,14 @@ export default {
         elements[index]?.focus();
       });
     },
-    onSelect({ value }, isSelected) {
+    focusSearchInput() {
+      this.$refs.searchBox.focusInput();
+    },
+    onSelect(item, isSelected) {
       if (this.multiple) {
-        this.onMultiSelect(value, isSelected);
+        this.onMultiSelect(item.value, isSelected);
       } else {
-        this.onSingleSelect(value, isSelected);
+        this.onSingleSelect(item.value, isSelected);
       }
     },
     isSelected(item) {
@@ -318,6 +397,15 @@ export default {
         );
       }
     },
+    search(searchTerm) {
+      /**
+       * Emitted when the search query string is changed
+       *
+       * @event search
+       * @type {string}
+       */
+      this.$emit('search', searchTerm);
+    },
     isOption,
   },
 };
@@ -327,7 +415,7 @@ export default {
   <gl-base-dropdown
     ref="baseDropdown"
     aria-haspopup="listbox"
-    :aria-labelledby="ariaLabelledby"
+    :aria-labelledby="toggleAriaLabelledBy"
     :toggle-id="toggleId"
     :toggle-text="listboxToggleText"
     :toggle-class="toggleClass"
@@ -346,10 +434,29 @@ export default {
     <!-- @slot Content to display in dropdown header -->
     <slot name="header"></slot>
 
+    <div v-if="searchable" class="gl-border-b-1 gl-border-b-solid gl-border-b-gray-200">
+      <gl-search-box-by-type
+        ref="searchBox"
+        v-model="searchStr"
+        :aria-owns="listboxId"
+        data-testid="listbox-search-input"
+        @input="search"
+        @keydown="onKeydown"
+      />
+      <gl-loading-icon
+        v-if="searching"
+        data-testid="listbox-search-loader"
+        size="md"
+        class="gl-my-3"
+      />
+    </div>
+
     <component
       :is="listboxTag"
+      v-if="showList"
+      id="listbox"
       ref="list"
-      :aria-labelledby="toggleId"
+      :aria-labelledby="listAriaLabelledBy || toggleId"
       role="listbox"
       class="gl-new-dropdown-contents gl-list-style-none gl-pl-0 gl-mb-0"
       tabindex="-1"
@@ -395,6 +502,25 @@ export default {
         </template>
       </template>
     </component>
+
+    <span
+      v-if="announceSRSearchResults"
+      data-testid="listbox-number-of-results"
+      class="gl-sr-only"
+      aria-live="assertive"
+    >
+      <!-- @slot Text read by screen reader announcing a number of search results -->
+      <slot name="search-summary-sr-only"></slot>
+    </span>
+
+    <div
+      v-else-if="showNoResultsText"
+      aria-live="assertive"
+      class="gl-pl-7 gl-pr-5 gl-pt-3 gl-font-base gl-text-gray-600"
+      data-testid="listbox-no-results-text"
+    >
+      {{ noResultsText }}
+    </div>
     <!-- @slot Content to display in dropdown footer -->
     <slot name="footer"></slot>
   </gl-base-dropdown>