@gitlab/ui 67.4.0 → 67.5.1

package/src/components/base/sorting/sorting.md

@@ -1,8 +1,88 @@
-## Usage
-
 The sorting component allows the user to select the field on which they would like to sort a list
 and whether to sort in ascending or descending order.
 
+Provide a list of sort options via the `sortOptions` prop with this structure:
+
+```typescript
+type sortOptionsProp = Array<{
+  value: string
+  text: string
+}>
+```
+
+The `value` should be a unique primitive value, and `text` is the user-facing
+string for that option.
+
+Set the currently selected sort option by passing a value to the `sortBy` prop.
+This should equal one of the `sortOptions` values. The selected sort option is
+rendered with a check mark next to it in the dropdown menu.
+
+When the user changes the selected sort option, a `sortByChange` event is
+emitted, with the `value` of the option as the only payload.
+
+The text of the dropdown trigger button is the `text` of the selected sort
+option. Pass a string to the `text` prop to override this behavior.
+
+When the user clicks on the sort direction button, a `sortDirectionChange`
+event is emitted, with a boolean value as its only payload. If the payload is
+`true`, the new order is ascending; otherwise it's descending.
+
+A complete implementation example might look like:
+
+```html
+<template>
+  <gl-sorting
+    :sort-options="sortOptions"
+    :sort-by="sortBy"
+    :is-ascending="isAscending"
+    @sortByChange="onSortByChange"
+    @sortDirectionChange="onDirectionChange"
+  />
+</template>
+
+<script>
+import { GlSorting } from '@gitlab/ui';
+
+export default {
+  components: {
+    GlSorting,
+  },
+  data() {
+    const sortOptions = [{
+      value: 'name',
+      text: 'Name',
+    }, {
+      value: 'date',
+      text: 'Date',
+    }];
+
+    return {
+      isAscending: false,
+      sortBy: sortOptions[0].value,
+      sortOptions,
+    }
+  },
+  methods: {
+    onSortByChange(value) {
+      this.sortBy = value;
+      this.sortMyData(this.sortBy, this.isAscending);
+    },
+    onDirectionChange(isAscending) {
+      this.isAscending = isAscending;
+      this.sortMyData(this.sortBy, this.isAscending);
+    },
+    sortMyData(sortBy, isAscending) {
+      // Use sortBy and direction to sort your data
+    },
+  }
+}
+</script>
+```
+
+## Deprecated usage
+
+> **NOTE:** This documents the deprecated API, which will be removed in a future major release.
+
 The dropdown part of the sorting component is a standard `gl-dropdown` component, with the items
 exposed as a slot. Inside the `gl-sorting` component, you should add a list of `gl-sorting-item`
 components to construct your sorting options. The check icon will be displayed when a

package/src/components/base/sorting/sorting.spec.js

@@ -1,4 +1,6 @@
 import { mount } from '@vue/test-utils';
+import { useMockIntersectionObserver } from '~/utils/use_mock_intersection_observer';
+import GlCollapsibleListbox from '../new_dropdowns/listbox/listbox.vue';
 import GlDropdown from '../dropdown/dropdown.vue';
 import GlIcon from '../icon/icon.vue';
 import GlSorting from './sorting.vue';
@@ -14,9 +16,15 @@ describe('sorting component', () => {
     isAscending,
   };
 
-  const selectDropdownButton = () => wrapper.find('.gl-dropdown button');
-  const selectDirectionButton = () => wrapper.find('.sorting-direction-button');
+  const selectDropdownButton = () => wrapper.find('button');
+  const selectDirectionButton = () => wrapper.findAll('button').at(1);
   const selectDropdown = () => wrapper.findComponent(GlDropdown);
+  const findListbox = () => wrapper.findComponent(GlCollapsibleListbox);
+  const findListboxItem = (text) =>
+    wrapper
+      .findAll('[role="option"]')
+      .filter((w) => w.text().includes(text))
+      .at(0);
 
   const createComponent = (propsData) => {
     wrapper = mount(GlSorting, {
@@ -30,14 +38,12 @@ describe('sorting component', () => {
   it('should display default text in dropdown', () => {
     createComponent();
 
-    expect(wrapper.vm.text).toBe(defaultDropdownText);
     expect(selectDropdownButton().text()).toBe(defaultDropdownText);
   });
 
   it('should have a default sort direction of desc and displays the descending icon', () => {
     createComponent();
 
-    expect(wrapper.vm.isAscending).toBe(false);
     expect(selectDirectionButton().findComponent(GlIcon).props('name')).toBe('sort-highest');
   });
 
@@ -45,21 +51,17 @@ describe('sorting component', () => {
     const newDropdownText = 'Some new text';
 
     createComponent({
-      ...defaultProps,
       text: newDropdownText,
     });
 
-    expect(wrapper.vm.text).toBe(newDropdownText);
     expect(selectDropdownButton().text()).toBe(newDropdownText);
   });
 
   it('should accept isAscending true as a default sort direction and display the ascending icon', () => {
     createComponent({
-      ...defaultProps,
       isAscending: true,
     });
 
-    expect(wrapper.vm.isAscending).toBe(true);
     expect(selectDirectionButton().findComponent(GlIcon).props('name')).toBe('sort-lowest');
   });
 
@@ -71,21 +73,19 @@ describe('sorting component', () => {
     expect(wrapper.emitted('sortDirectionChange')[0]).toEqual([true]);
   });
 
-  it('should allow custom sort tooltip to be applied', () => {
+  it('should allow custom sort direction text to be applied', () => {
     const newDirectionTooltip = 'New tooltip text';
 
     createComponent({
-      ...defaultProps,
       sortDirectionToolTip: newDirectionTooltip,
     });
 
-    expect(wrapper.vm.sortDirectionToolTip).toBe(newDirectionTooltip);
     expect(selectDirectionButton().attributes('title')).toBe(newDirectionTooltip);
+    expect(selectDirectionButton().attributes('aria-label')).toBe(newDirectionTooltip);
   });
 
   it('adds classes passed in `dropdownClass` prop to dropdown', () => {
     createComponent({
-      ...defaultProps,
       dropdownClass: 'foo-bar',
     });
 
@@ -94,7 +94,6 @@ describe('sorting component', () => {
 
   it('adds classes passed in `dropdownToggleClass` prop to dropdown toggle', () => {
     createComponent({
-      ...defaultProps,
       dropdownToggleClass: 'foo-bar',
     });
 
@@ -103,7 +102,6 @@ describe('sorting component', () => {
 
   it('adds classes passed in `sortDirectionToggleClass` prop to sort direction toggle', () => {
     createComponent({
-      ...defaultProps,
       sortDirectionToggleClass: 'foo-bar',
     });
 
@@ -111,4 +109,130 @@ describe('sorting component', () => {
       expect.arrayContaining(['sorting-direction-button', 'foo-bar'])
     );
   });
+
+  it('sets aria-label of sort direction button', async () => {
+    createComponent();
+
+    expect(selectDirectionButton().attributes('aria-label')).toBe('Sort direction: descending');
+
+    await wrapper.setProps({ isAscending: true });
+
+    expect(selectDirectionButton().attributes('aria-label')).toBe('Sort direction: ascending');
+  });
+
+  describe('using listbox', () => {
+    useMockIntersectionObserver();
+
+    it('should display given toggle text in dropdown', () => {
+      createComponent({ sortOptions: [] });
+
+      expect(selectDropdownButton().text()).toBe(defaultDropdownText);
+    });
+
+    it('should use the selected sort option text in dropdown if text is not given', () => {
+      createComponent({ text: null, sortOptions: [{ value: 0, text: 'Foo' }], sortBy: 0 });
+
+      expect(selectDropdownButton().text()).toBe('Foo');
+    });
+
+    it('renders the given sort options', () => {
+      createComponent({
+        sortOptions: [
+          { value: 'foo', text: 'Foo' },
+          { value: 'bar', text: 'Bar' },
+        ],
+      });
+
+      expect(findListboxItem('Foo').exists()).toBe(true);
+      expect(findListboxItem('Bar').exists()).toBe(true);
+    });
+
+    it('emits sortByChange event when user changes sort option', async () => {
+      createComponent({
+        sortOptions: [
+          { value: 'foo', text: 'Foo' },
+          { value: 'bar', text: 'Bar' },
+        ],
+        sortBy: 'foo',
+      });
+
+      await findListboxItem('Foo').trigger('click');
+      expect(wrapper.emitted('sortByChange')).toBe(undefined);
+
+      await findListboxItem('Bar').trigger('click');
+      expect(wrapper.emitted('sortByChange')).toEqual([['bar']]);
+    });
+
+    it('should have a default sort direction of desc and displays the descending icon', () => {
+      createComponent({ sortOptions: [] });
+
+      expect(selectDirectionButton().findComponent(GlIcon).props('name')).toBe('sort-highest');
+    });
+
+    it('should accept isAscending true as a default sort direction and display the ascending icon', () => {
+      createComponent({
+        sortOptions: [],
+        isAscending: true,
+      });
+
+      expect(selectDirectionButton().findComponent(GlIcon).props('name')).toBe('sort-lowest');
+    });
+
+    it('should emit the sortDirectionChange event when direction button is clicked', () => {
+      createComponent({ sortOptions: [] });
+
+      selectDirectionButton().trigger('click');
+
+      expect(wrapper.emitted('sortDirectionChange')[0]).toEqual([true]);
+    });
+
+    it('should allow custom sort tooltip to be applied', () => {
+      const newDirectionTooltip = 'New tooltip text';
+
+      createComponent({
+        sortDirectionToolTip: newDirectionTooltip,
+      });
+
+      expect(selectDirectionButton().attributes('title')).toBe(newDirectionTooltip);
+    });
+
+    it('adds classes passed in `dropdownClass` prop to dropdown', () => {
+      createComponent({
+        sortOptions: [],
+        dropdownClass: 'foo-bar',
+      });
+
+      expect(findListbox().classes()).toContain('foo-bar');
+    });
+
+    it('adds classes passed in `dropdownToggleClass` prop to dropdown toggle', () => {
+      createComponent({
+        sortOptions: [],
+        dropdownToggleClass: 'foo-bar',
+      });
+
+      expect(selectDropdownButton().classes()).toEqual(expect.arrayContaining(['foo-bar']));
+    });
+
+    it('adds classes passed in `sortDirectionToggleClass` prop to sort direction toggle', () => {
+      createComponent({
+        sortOptions: [],
+        sortDirectionToggleClass: 'foo-bar',
+      });
+
+      expect(selectDirectionButton().classes()).toEqual(
+        expect.arrayContaining(['sorting-direction-button', 'foo-bar'])
+      );
+    });
+
+    it('sets aria-label of sort direction button', async () => {
+      createComponent({ sortOptions: [] });
+
+      expect(selectDirectionButton().attributes('aria-label')).toBe('Sort direction: descending');
+
+      await wrapper.setProps({ isAscending: true });
+
+      expect(selectDirectionButton().attributes('aria-label')).toBe('Sort direction: ascending');
+    });
+  });
 });

package/src/components/base/sorting/sorting.stories.js

@@ -12,6 +12,8 @@ const propDefault = (prop) => GlSorting.props[prop].default;
 
 const generateProps = ({
   text = 'Sorting options',
+  sortOptions = propDefault('sortOptions'),
+  sortBy = propDefault('sortBy'),
   isAscending = propDefault('isAscending'),
   sortDirectionToolTip = propDefault('sortDirectionToolTip'),
   dropdownClass = propDefault('dropdownClass'),
@@ -19,6 +21,8 @@ const generateProps = ({
   sortDirectionToggleClass = propDefault('sortDirectionToggleClass'),
 } = {}) => ({
   text,
+  sortOptions,
+  sortBy,
   isAscending,
   sortDirectionToolTip,
   dropdownClass,
@@ -50,12 +54,75 @@ const Template = (args) => ({
 });
 
 export const Default = Template.bind({});
-Default.args = generateProps();
+Object.assign(Default, {
+  args: generateProps(),
+  parameters: {
+    controls: {
+      // These props/events only apply when using the listbox form, so don't
+      // show their controls.
+      exclude: ['sortBy', 'sortOptions', 'sortByChange'],
+    },
+  },
+});
+
+export const UsingListbox = (args) => ({
+  components,
+  props: Object.keys(args),
+  mounted() {
+    // The first button is the dropdown trigger.
+    this.$nextTick(() => this.$el.querySelector('button').click());
+  },
+  template: `
+    <gl-sorting
+      :text="text"
+      :sort-options="sortOptions"
+      :sort-by="sortBy"
+      :is-ascending="isAscending"
+      :sort-direction-tool-tip="sortDirectionToolTip"
+      :dropdown-class="dropdownClass"
+      :dropdown-toggle-class="dropdownToggleClass"
+      :sort-direction-toggle-class="sortDirectionToggleClass"
+    />
+  `,
+});
+Object.assign(UsingListbox, {
+  args: generateProps({
+    text: '',
+    sortOptions: [
+      {
+        value: 'first',
+        text: 'First item',
+      },
+      {
+        value: 'second',
+        text: 'Second item',
+      },
+      {
+        value: 'third',
+        text: 'Third item',
+      },
+    ],
+    sortBy: 'first',
+  }),
+  parameters: {
+    controls: {
+      // The default slot is deprecated, so don't show it in the controls.
+      exclude: ['default'],
+    },
+  },
+});
 
 export default {
   title: 'base/sorting',
   component: GlSorting,
-  decorators: [makeContainer({ height: '100px', paddingLeft: '100px' })],
+  decorators: [
+    makeContainer({
+      height: '150px',
+      display: 'flex',
+      justifyContent: 'center',
+      alignItems: 'flex-start',
+    }),
+  ],
   parameters: {
     docs: {
       description: {

package/src/components/base/sorting/sorting.vue

@@ -2,13 +2,17 @@
 import { GlTooltipDirective } from '../../../directives/tooltip';
 import GlButton from '../button/button.vue';
 import GlButtonGroup from '../button_group/button_group.vue';
+import GlCollapsibleListbox from '../new_dropdowns/listbox/listbox.vue';
+import { isOption } from '../new_dropdowns/listbox/utils';
 import GlDropdown from '../dropdown/dropdown.vue';
+import { translate } from '../../../utils/i18n';
 
 export default {
   name: 'GlSorting',
   components: {
     GlButton,
     GlButtonGroup,
+    GlCollapsibleListbox,
     GlDropdown,
   },
   directives: {
@@ -23,6 +27,24 @@ export default {
       required: false,
       default: '',
     },
+    /**
+     * Sort options to display in the dropdown
+     */
+    sortOptions: {
+      type: Array,
+      required: false,
+      default: null,
+      validator: (sortOptions) => sortOptions.every(isOption),
+    },
+    /**
+     * The value of the item currently selected in the dropdown.
+     * Only to be used with the `sortOptions` prop.
+     */
+    sortBy: {
+      type: [String, Number],
+      required: false,
+      default: null,
+    },
     /**
      * Determines the current sort order icon displayed.
      */
@@ -32,12 +54,13 @@ export default {
       default: false,
     },
     /**
-     * The text of the tool tip for the sort direction toggle button.
+     * The text for the tooltip and aria-label of the sort direction toggle
+     * button instead of the defaults for ascending/descending.
      */
     sortDirectionToolTip: {
       type: String,
       required: false,
-      default: 'Sort direction',
+      default: null,
     },
     /**
      * Additional class(es) to apply to the root element of the GlDropdown.
@@ -68,8 +91,23 @@ export default {
     localSortDirection() {
       return this.isAscending ? 'sort-lowest' : 'sort-highest';
     },
-    sortDirectionAriaLabel() {
-      return this.isAscending ? 'Sorting Direction: Ascending' : 'Sorting Direction: Descending';
+    sortDirectionText() {
+      if (this.sortDirectionToolTip) return this.sortDirectionToolTip;
+
+      return this.isAscending
+        ? translate('GlSorting.sortAscending', 'Sort direction: ascending')
+        : translate('GlSorting.sortDescending', 'Sort direction: descending');
+    },
+    useListbox() {
+      return Boolean(this.sortOptions);
+    },
+    listboxToggleClass() {
+      return [
+        this.dropdownToggleClass,
+        'gl-rounded-top-right-none!',
+        'gl-rounded-bottom-right-none!',
+        'gl-focus-z-index-1',
+      ];
     },
   },
   methods: {
@@ -86,13 +124,36 @@ export default {
        */
       this.$emit('sortDirectionChange', newDirection);
     },
+    onSortByChanged(event) {
+      /**
+       * Emitted when the sort field is changed.
+       *
+       * The event's payload is the value of the selected sort field.
+       *
+       * Only emitted when using the `sortOptions` prop.
+       *
+       * @property {string|number} value
+       */
+      this.$emit('sortByChange', event);
+    },
   },
 };
 </script>
 
 <template>
   <gl-button-group class="gl-sorting">
+    <gl-collapsible-listbox
+      v-if="useListbox"
+      :toggle-text="text"
+      :items="sortOptions"
+      :selected="sortBy"
+      :toggle-class="listboxToggleClass"
+      :class="dropdownClass"
+      placement="right"
+      @select="onSortByChanged"
+    />
     <gl-dropdown
+      v-else
       v-bind="$props"
       :text="text"
       category="secondary"
@@ -100,14 +161,14 @@ export default {
       :toggle-class="dropdownToggleClass"
       right
     >
-      <!-- @slot Slot to place the dropdown items, works best with a gl-sorting-item component. -->
+      <!-- @slot Deprecated slot to place the dropdown items, works best with a gl-sorting-item component. -->
       <slot></slot>
     </gl-dropdown>
     <gl-button
       v-gl-tooltip
-      :title="sortDirectionToolTip"
+      :title="sortDirectionText"
       :icon="localSortDirection"
-      :aria-label="sortDirectionAriaLabel"
+      :aria-label="sortDirectionText"
       :class="['sorting-direction-button', sortDirectionToggleClass]"
       @click="toggleSortDirection"
     />

package/src/components/base/sorting/sorting_item.md

@@ -1,4 +1,4 @@
-## Usage
+> **NOTE:** This component is deprecated. Instead, use the `sortOptions` prop of `GlSorting`.
 
 The sorting item component is meant to be used for clickable entries inside a `gl-sorting` component.
 This is a wrapper around the `gl-dropdown-item` component and includes a check icon when active,

package/src/components/base/sorting/sorting_item.vue

@@ -5,6 +5,9 @@ import GlIcon from '../icon/icon.vue';
 /**
  * Sorting Item
  *
+ * NOTE: This component is deprecated. Instead, use the `sortOptions` prop of
+ * `GlSorting`.
+ *
  * This is written as a functional component because it is a simple wrapper over
  * the GlDropdownItem component and does not use internal state. Functional
  * components are cheaper to render and often used as wrappers like this. We're

package/src/components/experimental/duo/chat/components/duo_chat_message/duo_chat_message.vue

@@ -1,5 +1,4 @@
 <script>
-import { nextTick } from 'vue';
 import GlDuoUserFeedback from '../../../user_feedback/user_feedback.vue';
 import { SafeHtmlDirective as SafeHtml } from '../../../../../../directives/safe_html/safe_html';
 import { MESSAGE_MODEL_ROLES } from '../../constants';
@@ -77,7 +76,7 @@ export default {
   },
   methods: {
     async hydrateContentWithGFM() {
-      await nextTick();
+      await this.$nextTick();
       this.renderGFM(this.$refs.content);
     },
     async messageUpdateHandler() {

package/src/scss/storybook.scss

@@ -1,3 +1,4 @@
+@import 'tokens';
 @import 'functions';
 @import 'variables';
 
@@ -15,7 +16,6 @@
 
 @import 'components';
 
-@import '../../dist/tokens/css/tokens';
 @import 'storybook_dark_mode';
 
 /**

package/src/scss/storybook_dark_mode.scss

@@ -1,5 +1,4 @@
 @import 'variables';
-@import '../../dist/tokens/css/tokens.dark';
 
 // conditional overrides for dark mode for use in storybook.
 // Because we only use application.css from gitlab (and not

package/src/scss/tokens.scss

@@ -0,0 +1,2 @@
+@import '../../dist/tokens/css/tokens';
+@import '../../dist/tokens/css/tokens.dark';

package/src/scss/utilities.scss

@@ -9285,10 +9285,18 @@ $gl-animate-skeleton-loader-max-width: 64 * $grid-size;
   z-index: 1
 }
 
+.gl-focus-z-index-1:focus {
+  z-index: 1
+}
+
 .gl-z-index-1\! {
   z-index: 1 !important
 }
 
+.gl-focus-z-index-1\!:focus {
+  z-index: 1 !important
+}
+
 .gl-z-index-2 {
   z-index: 2
 }

package/src/scss/utility-mixins/z-index.scss

@@ -8,7 +8,7 @@
   z-index: 0;
 }
 
-@mixin gl-z-index-1 {
+@mixin gl-z-index-1($focus: true) {
   z-index: 1;
 }