@gitlab/ui 43.11.0 → 43.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitlab/ui",
-  "version": "43.11.0",
+  "version": "43.14.0",
   "description": "GitLab UI Components",
   "license": "MIT",
   "main": "dist/index.js",
@@ -102,7 +102,7 @@
     "babel-plugin-require-context-hook": "^1.0.0",
     "babel-preset-vue": "^2.0.2",
     "bootstrap": "4.5.3",
-    "cypress": "^10.6.0",
+    "cypress": "^10.7.0",
     "emoji-regex": "^10.0.0",
     "eslint": "8.22.0",
     "eslint-import-resolver-jest": "3.0.2",
@@ -112,9 +112,9 @@
     "glob": "^7.2.0",
     "identity-obj-proxy": "^3.0.0",
     "inquirer-select-directory": "^1.2.0",
-    "jest": "^29.0.1",
-    "jest-circus": "29.0.1",
-    "jest-environment-jsdom": "29.0.1",
+    "jest": "^29.0.2",
+    "jest-circus": "29.0.2",
+    "jest-environment-jsdom": "29.0.2",
     "jest-serializer-vue": "^2.0.2",
     "markdownlint-cli": "^0.29.0",
     "mockdate": "^2.0.5",

package/scss_to_js/scss_variables.js

@@ -26,6 +26,7 @@ export const breakpointLg = '992px'
 export const breakpointXl = '1200px'
 export const breakpoints = '(xs: 0, sm: 576px, md: 768px, lg: 992px, xl: 1200px)'
 export const limitedLayoutWidth = '990px'
+export const containerXl = '1280px'
 export const black = '#000'
 export const blackNormal = '#333'
 export const white = '#fff'

package/scss_to_js/scss_variables.json

@@ -167,6 +167,11 @@
       "value": "990px",
       "compiledValue": "990px"
     },
+    {
+      "name": "$container-xl",
+      "value": "1280px",
+      "compiledValue": "1280px"
+    },
     {
       "name": "$black",
       "value": "#000",

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'),
@@ -79,6 +31,7 @@ const generateProps = ({
   textSrOnly = defaultValue('textSrOnly'),
   icon = '',
   multiple = defaultValue('multiple'),
+  isCheckCentered = defaultValue('isCheckCentered'),
   ariaLabelledby,
   startOpened = true,
 } = {}) => ({
@@ -94,6 +47,7 @@ const generateProps = ({
   textSrOnly,
   icon,
   multiple,
+  isCheckCentered,
   ariaLabelledby,
   startOpened,
 });
@@ -120,6 +74,7 @@ const template = (content, label = '') => `
       :text-sr-only="textSrOnly"
       :icon="icon"
       :multiple="multiple"
+      :is-check-centered="isCheckCentered"
       :aria-labelledby="ariaLabelledby"
     >
       ${content}
@@ -134,7 +89,7 @@ export const Default = (args, { argTypes }) => ({
   },
   data() {
     return {
-      selected: defaultItems[1].value,
+      selected: mockOptions[1].value,
     };
   },
   mounted() {
@@ -167,23 +122,28 @@ 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',
+  multiple: true,
 });
-HeaderAndFooter.args = generateProps({ toggleText: 'Header and Footer', multiple: true });
 HeaderAndFooter.decorators = [makeContainer({ height: '370px' })];
 
 export const CustomListItem = (args, { argTypes }) => ({
@@ -211,32 +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"
-        :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>
   `,
 });
 
@@ -247,9 +208,50 @@ CustomListItem.args = generateProps({
     { value: 'markian', text: 'Mark Florian', secondaryText: '@markian', icon: 'bin' },
   ],
   multiple: true,
+  isCheckCentered: true,
 });
 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,