@gitlab/ui 43.12.0 → 43.15.0

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

package/src/components/base/toggle/toggle.md

@@ -1,5 +1,3 @@
-# Toggle
-
 ## Usage
 
 The toggle component must have a `label` prop to give the toggle button an accessible name.

package/src/scss/utilities.scss

@@ -3112,6 +3112,18 @@
   }
 }
 
+.gl-sm-align-items-center {
+  @include gl-media-breakpoint-up(sm) {
+  align-items: center;
+  }
+}
+
+.gl-sm-align-items-center\! {
+  @include gl-media-breakpoint-up(sm) {
+  align-items: center !important;
+  }
+}
+
 .gl-md-align-items-center {
   @include gl-media-breakpoint-up(md) {
   align-items: center;

package/src/scss/utility-mixins/flex.scss

@@ -36,6 +36,12 @@
   }
 }
 
+@mixin gl-sm-align-items-center {
+  @include gl-media-breakpoint-up(sm) {
+    @include gl-align-items-center;
+  }
+}
+
 @mixin gl-md-align-items-center {
   @include gl-media-breakpoint-up(md) {
     @include gl-align-items-center;