@gitlab/ui 55.2.1 → 55.3.1

package/package.json

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

package/src/components/base/new_dropdowns/disclosure/constants.js

@@ -0,0 +1,2 @@
+export const DISCLOSURE_DROPDOWN_ITEM_NAME = 'GlDisclosureDropdownItem';
+export const DISCLOSURE_DROPDOWN_GROUP_NAME = 'GlDisclosureDropdownGroup';

package/src/components/base/new_dropdowns/disclosure/disclosure_dropdown.spec.js

@@ -22,6 +22,7 @@ describe('GlDisclosureDropdown', () => {
   const buildWrapper = (propsData, slots = {}) => {
     wrapper = mount(GlDisclosureDropdown, {
       propsData,
+      components: { GlDisclosureDropdownItem, GlDisclosureDropdownGroup },
       slots,
       attachTo: document.body,
     });
@@ -216,23 +217,65 @@ describe('GlDisclosureDropdown', () => {
     });
   });
 
-  describe('disclosure options', () => {
-    it('should render the `ul` as content tag and not add `role` attribute when it is a list of items only', () => {
+  describe('disclosure tag', () => {
+    it('should render `ul` as content tag when items is a list of items', () => {
       buildWrapper({ items: mockItems });
       expect(findDisclosureContent().element.tagName).toBe('UL');
-      expect(findDisclosureContent().attributes('role')).toBeUndefined();
     });
 
-    it('should render the `div` as content tag and add `role` attribute when it is a list of groups', () => {
+    it('should render `ul` as content tag when items is a list of groups', () => {
       buildWrapper({ items: mockGroups });
+      expect(findDisclosureContent().element.tagName).toBe('UL');
+    });
+
+    it('should render `ul` as content tag when default slot contains only groups', () => {
+      const slots = {
+        default: `
+          <gl-disclosure-dropdown-group>
+            <gl-disclosure-dropdown-item>Item</gl-disclosure-dropdown-item>
+            <gl-disclosure-dropdown-item>Item</gl-disclosure-dropdown-item>
+          </gl-disclosure-dropdown-group>
+          <gl-disclosure-dropdown-group>
+            <gl-disclosure-dropdown-item>Item</gl-disclosure-dropdown-item>
+          </gl-disclosure-dropdown-group>
+        `,
+      };
+
+      buildWrapper({}, slots);
+      expect(findDisclosureContent().element.tagName).toBe('UL');
+    });
+
+    it('should render `ul` as content tag when default slot contains only items', () => {
+      const slots = {
+        default: `
+          <gl-disclosure-dropdown-item>Item</gl-disclosure-dropdown-item>
+          <gl-disclosure-dropdown-item>Item</gl-disclosure-dropdown-item>
+          <gl-disclosure-dropdown-item>Item</gl-disclosure-dropdown-item>
+        `,
+      };
+
+      buildWrapper({}, slots);
+      expect(findDisclosureContent().element.tagName).toBe('UL');
+    });
+
+    it('should render `div` as content tag when default slot does not contain valid list item', () => {
+      const slots = {
+        default: `
+          <div>Item</div>
+          <gl-disclosure-dropdown-group>
+            <gl-disclosure-dropdown-item>Item</gl-disclosure-dropdown-item>
+            <gl-disclosure-dropdown-item>Item</gl-disclosure-dropdown-item>
+          </gl-disclosure-dropdown-group>
+        `,
+      };
+
+      buildWrapper({}, slots);
       expect(findDisclosureContent().element.tagName).toBe('DIV');
-      expect(findDisclosureContent().attributes('role')).toBe('group');
     });
 
-    it('should render the `div` as content tag and NOT add `role` otherwise', () => {
-      buildWrapper({ items: null }, { default: 'Some other content' });
+    it('should render `div` as content tag when slot is not a list item', () => {
+      buildWrapper({}, { default: 'Some other content' });
       expect(findDisclosureContent().element.tagName).toBe('DIV');
-      expect(findDisclosureContent().attributes('role')).toBeUndefined();
     });
   });
 });

package/src/components/base/new_dropdowns/disclosure/disclosure_dropdown.stories.js

@@ -52,13 +52,16 @@ function openDisclosure(component) {
   });
 }
 
-const template = (content, { bindingOverrides = {} } = {}) => `
+const template = (content, { bindingOverrides = {} } = {}, after) => `
+  <div>
     <gl-disclosure-dropdown
       ref="disclosure"
       ${makeBindings(bindingOverrides)}
     >
       ${content || ''}
     </gl-disclosure-dropdown>
+    ${after || ''}
+  </div>
 `;
 
 const TOGGLE_ID = 'custom-toggle-id';
@@ -217,15 +220,14 @@ CustomGroupsAndItems.args = {
 CustomGroupsAndItems.decorators = [makeContainer({ height: '200px' })];
 
 export const CustomGroupsItemsAndToggle = makeGroupedExample({
-  template: template(`
-    <template #toggle>
-      <span class="gl-sr-only">
-        Orange Fox user's menu
-      </span>
-      <gl-avatar :size="32" entity-name="Orange Fox" aria-hidden="true"></gl-avatar>
-    </template>
-
-    <div role="group">
+  template: template(
+    `
+      <template #toggle>
+        <span class="gl-sr-only">
+          Orange Fox user's menu
+        </span>
+        <gl-avatar :size="32" entity-name="Orange Fox" aria-hidden="true"></gl-avatar>
+      </template>
       <gl-disclosure-dropdown-group>
         <gl-disclosure-dropdown-item>
           <span class="gl-display-flex gl-flex-direction-column">
@@ -256,15 +258,18 @@ export const CustomGroupsItemsAndToggle = makeGroupedExample({
           <gl-toggle label="New navigation" label-position="left" v-model="newNavigation"/>
         </gl-disclosure-dropdown-item>
         <gl-disclosure-dropdown-item @action="toggleModalVisibility(true)">
-          <a>Provide feedback</a>
+          Provide feedback
         </gl-disclosure-dropdown-item>
       </gl-disclosure-dropdown-group>
       <gl-disclosure-dropdown-group bordered :group="$options.groups[1]"> </gl-disclosure-dropdown-group>
+    `,
+    {},
+    `
       <gl-modal :visible="feedBackModalVisible" @change="toggleModalVisibility" modal-id="feedbackModal" size="sm">
         <textarea class="gl-w-full">Tell us what you think!</textarea>
       </gl-modal>
-    </div>
-  `),
+    `
+  ),
   data() {
     return {
       newNavigation: true,

package/src/components/base/new_dropdowns/disclosure/disclosure_dropdown.vue

@@ -19,7 +19,7 @@ import {
 import GlBaseDropdown from '../base_dropdown/base_dropdown.vue';
 import GlDisclosureDropdownItem, { ITEM_CLASS } from './disclosure_dropdown_item.vue';
 import GlDisclosureDropdownGroup from './disclosure_dropdown_group.vue';
-import { itemsValidator, isItem, isAllItems, isAllGroups } from './utils';
+import { itemsValidator, isItem, hasOnlyListItems } from './utils';
 
 export default {
   events: {
@@ -169,22 +169,11 @@ export default {
     };
   },
   computed: {
-    disclosureOptions() {
-      if (this.items) {
-        if (isAllItems(this.items)) {
-          return {
-            tag: 'ul',
-          };
-        }
-
-        if (isAllGroups(this.items))
-          return {
-            tag: 'div',
-            role: 'group',
-          };
+    disclosureTag() {
+      if (this.items?.length || hasOnlyListItems(this.$scopedSlots)) {
+        return 'ul';
       }
-
-      return { tag: 'div' };
+      return 'div';
     },
     hasCustomToggle() {
       return Boolean(this.$scopedSlots.toggle);
@@ -305,10 +294,9 @@ export default {
     <slot name="header"></slot>
 
     <component
-      :is="disclosureOptions.tag"
+      :is="disclosureTag"
       :id="disclosureId"
       ref="content"
-      :role="disclosureOptions.role"
       :aria-labelledby="listAriaLabelledBy || toggleId"
       data-testid="disclosure-content"
       class="gl-new-dropdown-contents"

package/src/components/base/new_dropdowns/disclosure/disclosure_dropdown_group.vue

@@ -2,10 +2,12 @@
 import { uniqueId } from 'lodash';
 import GlDisclosureDropdownItem from './disclosure_dropdown_item.vue';
 import { isGroup } from './utils';
+import { DISCLOSURE_DROPDOWN_GROUP_NAME } from './constants';
 
 export const GROUP_TOP_BORDER_CLASSES = 'gl-border-t gl-pt-2 gl-mt-2';
 
 export default {
+  name: DISCLOSURE_DROPDOWN_GROUP_NAME,
   components: {
     GlDisclosureDropdownItem,
   },
@@ -52,7 +54,7 @@ export default {
 </script>
 
 <template>
-  <div :class="borderClass">
+  <li :class="borderClass">
     <div
       v-if="showHeader"
       :id="nameId"
@@ -73,5 +75,5 @@ export default {
         </gl-disclosure-dropdown-item>
       </slot>
     </ul>
-  </div>
+  </li>
 </template>

package/src/components/base/new_dropdowns/disclosure/disclosure_dropdown_item.vue

@@ -2,10 +2,12 @@
 import { ENTER, SPACE } from '../constants';
 import { stopEvent } from '../../../../utils/utils';
 import { isItem } from './utils';
+import { DISCLOSURE_DROPDOWN_ITEM_NAME } from './constants';
 
 export const ITEM_CLASS = 'gl-new-dropdown-item';
 
 export default {
+  name: DISCLOSURE_DROPDOWN_ITEM_NAME,
   ITEM_CLASS,
   props: {
     item: {

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

@@ -1,3 +1,6 @@
+import { isFunction } from 'lodash';
+import { DISCLOSURE_DROPDOWN_ITEM_NAME, DISCLOSURE_DROPDOWN_GROUP_NAME } from './constants';
+
 const itemValidator = (item) => item?.text?.length > 0 && !Array.isArray(item?.items);
 
 const isItem = (item) => Boolean(item) && itemValidator(item);
@@ -10,8 +13,30 @@ const isGroup = (group) =>
 
 const itemsValidator = (items) => items.every(isItem) || items.every(isGroup);
 
-const isAllItems = (items) => items.every(isItem);
+const isListItem = (tag) =>
+  ['gl-disclosure-dropdown-group', 'gl-disclosure-dropdown-item', 'li'].includes(tag);
+
+const isValidSlotTagVue2 = (vNode) =>
+  Boolean(vNode) && isListItem(vNode.componentOptions?.tag || vNode.tag);
+
+const isValidSlotTag = (vNode) => {
+  return (
+    [DISCLOSURE_DROPDOWN_ITEM_NAME, DISCLOSURE_DROPDOWN_GROUP_NAME].includes(vNode.type?.name) ||
+    vNode.type === 'li'
+  );
+};
 
-const isAllGroups = (items) => items.every(isGroup);
+const hasOnlyListItems = ({ default: defaultSlot }) => {
+  if (!isFunction(defaultSlot)) {
+    return false;
+  }
+  const nodes = defaultSlot();
+  return (
+    Array.isArray(nodes) &&
+    nodes.filter((vNode) => vNode.tag).length &&
+    (nodes.filter((vNode) => vNode.tag).every(isValidSlotTagVue2) ||
+      nodes.filter((vNode) => vNode.tag).every(isValidSlotTag))
+  );
+};
 
-export { itemsValidator, isItem, isGroup, isAllItems, isAllGroups };
+export { itemsValidator, isItem, isGroup, hasOnlyListItems };

package/src/components/base/toggle/toggle.scss

@@ -44,7 +44,7 @@
     }
 
     .gl-toggle-label,
-    .gl-help-label {
+    .gl-description-label {
       @include gl-text-gray-500;
     }
   }
@@ -73,7 +73,6 @@
 }
 
 .gl-toggle-label {
-  @include gl-mb-3;
   @include gl-font-weight-bold;
 }
 

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

@@ -8,6 +8,7 @@ describe('toggle', () => {
   let wrapper;
 
   const label = 'toggle label';
+  const descriptionText = 'description text';
   const helpText = 'help text';
 
   const createWrapper = (props = {}, options = {}) => {
@@ -21,6 +22,7 @@ describe('toggle', () => {
   };
 
   const findButton = () => wrapper.find('button');
+  const findDescriptionElement = () => wrapper.find('[data-testid="toggle-description"]');
   const findHelpElement = () => wrapper.find('[data-testid="toggle-help"]');
 
   it('has role=switch', () => {
@@ -85,6 +87,28 @@ describe('toggle', () => {
     });
   });
 
+  describe.each`
+    state                                        | description        | props                                                                       | options
+    ${'with description'}                        | ${descriptionText} | ${{ description: descriptionText }}                                         | ${undefined}
+    ${'with description in slot'}                | ${descriptionText} | ${undefined}                                                                | ${{ slots: { description: descriptionText } }}
+    ${'without description'}                     | ${undefined}       | ${undefined}                                                                | ${undefined}
+    ${'with description and labelPosition left'} | ${undefined}       | ${{ desciption: descriptionText, labelPosition: toggleLabelPosition.left }} | ${undefined}
+  `('$state', ({ description, props, options }) => {
+    beforeEach(() => {
+      createWrapper(props, options);
+    });
+
+    if (description) {
+      it('shows description', () => {
+        expect(findDescriptionElement().text()).toBe(description);
+      });
+    } else {
+      it('does not show description', () => {
+        expect(findDescriptionElement().exists()).toBe(false);
+      });
+    }
+  });
+
   describe.each`
     state                                 | help         | props                                                          | options                          | getAriaDescribedBy
     ${'with help'}                        | ${helpText}  | ${{ help: helpText }}                                          | ${undefined}                     | ${() => findHelpElement().attributes('id')}

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

@@ -5,7 +5,9 @@ import readme from './toggle.md';
 
 const defaultValue = (prop) => GlToggle.props[prop].default;
 
-const longHelp = `This is a toggle component with a long help message. 
+const withDescription = 'A dark color theme that is easier on the eyes.';
+
+const longHelp = `This is a toggle component with a long help message.
   You can notice how the text wraps when the width of the container
   is not enough to fix the entire text.`;
 
@@ -15,7 +17,8 @@ const generateProps = ({
   isLoading = defaultValue('isLoading'),
   label = 'Dark mode',
   labelId = 'dark-mode-toggle',
-  help = 'Toggle dark mode for the website',
+  description = '',
+  help = 'Toggle dark mode for the website.',
   labelPosition = defaultValue('labelPosition'),
 } = {}) => ({
   value,
@@ -23,6 +26,7 @@ const generateProps = ({
   isLoading,
   label,
   labelId,
+  description,
   help,
   labelPosition,
 });
@@ -35,6 +39,7 @@ const Template = (args, { argTypes }) => ({
     <gl-toggle
       v-model="value"
       :disabled="disabled"
+      :description="description"
       :help="help"
       :label-id="labelId"
       :is-loading="isLoading"
@@ -47,11 +52,21 @@ const Template = (args, { argTypes }) => ({
 export const Default = Template.bind({});
 Default.args = generateProps();
 
+export const WithDescription = Template.bind({});
+WithDescription.args = generateProps({
+  description: withDescription,
+});
+
 export const WithLongHelp = Template.bind({});
 WithLongHelp.args = generateProps({
   help: longHelp,
 });
 
+export const LabelPositionLeft = Template.bind({});
+LabelPositionLeft.args = generateProps({
+  labelPosition: 'left',
+});
+
 export default {
   title: 'base/toggle',
   component: GlToggle,
@@ -71,6 +86,9 @@ export default {
     label: {
       control: 'text',
     },
+    description: {
+      control: 'text',
+    },
     help: {
       control: 'text',
     },

package/src/components/base/toggle/toggle.vue

@@ -55,6 +55,14 @@ export default {
       type: String,
       required: true,
     },
+    /**
+     * The toggle's description.
+     */
+    description: {
+      type: String,
+      required: false,
+      default: undefined,
+    },
     /**
      * A help text to be shown below the toggle.
      */
@@ -81,10 +89,20 @@ export default {
     };
   },
   computed: {
+    shouldRenderDescription() {
+      // eslint-disable-next-line @gitlab/vue-prefer-dollar-scopedslots
+      return Boolean(this.$scopedSlots.description || this.description) && this.isVerticalLayout;
+    },
     shouldRenderHelp() {
       // eslint-disable-next-line @gitlab/vue-prefer-dollar-scopedslots
       return Boolean(this.$slots.help || this.help) && this.isVerticalLayout;
     },
+    toggleClasses() {
+      return [
+        { 'gl-sr-only': this.labelPosition === 'hidden' },
+        this.shouldRenderDescription ? 'gl-mb-2' : 'gl-mb-3',
+      ];
+    },
     icon() {
       return this.value ? 'mobile-issue-close' : 'close';
     },
@@ -132,13 +150,21 @@ export default {
   >
     <span
       :id="labelId"
-      :class="{ 'gl-sr-only': labelPosition === 'hidden' }"
+      :class="toggleClasses"
       class="gl-toggle-label gl-flex-shrink-0"
       data-testid="toggle-label"
     >
       <!-- @slot The toggle's label. -->
       <slot name="label">{{ label }}</slot>
     </span>
+    <span
+      v-if="shouldRenderDescription"
+      class="gl-description-label gl-mb-3"
+      data-testid="toggle-description"
+    >
+      <!-- @slot A description text to be shown below the label. -->
+      <slot name="description">{{ description }}</slot>
+    </span>
     <input v-if="name" :name="name" :value="value" type="hidden" />
     <button
       role="switch"