@gitlab/ui 55.2.1 → 55.3.0

package/package.json

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

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"