@gitlab/ui 37.10.0 → 38.1.0

package/src/components/base/filtered_search/filtered_search_token.vue

@@ -15,6 +15,7 @@ const DEFAULT_OPERATORS = [
 ];
 
 export default {
+  name: 'GlFilteredSearchToken',
   components: {
     GlToken,
     GlFilteredSearchTokenSegment,
@@ -26,11 +27,17 @@ export default {
       required: false,
       default: () => [],
     },
+    /**
+     * Token configuration with available operators and options.
+     */
     config: {
       type: Object,
       required: false,
       default: () => ({}),
     },
+    /**
+     * Determines if the token is being edited or not.
+     */
     active: {
       type: Boolean,
       required: false,
@@ -41,11 +48,17 @@ export default {
       required: false,
       default: () => [],
     },
+    /**
+     * Current token value.
+     */
     value: {
       type: Object,
       required: false,
       default: () => ({ operator: '', data: '' }),
     },
+    /**
+     * Display operators' descriptions instead of their values (e.g., "is" instead of "=").
+     */
     showFriendlyText: {
       type: Boolean,
       required: false,
@@ -88,6 +101,12 @@ export default {
     value: {
       deep: true,
       handler(newValue) {
+        /**
+         * Emitted when the token changes its value.
+         *
+         * @event input
+         * @type {object} dataObj Object containing the update value.
+         */
         this.$emit('input', newValue);
       },
     },
@@ -101,6 +120,11 @@ export default {
           }
         } else if (this.value.data === '') {
           this.activeSegment = null;
+          /**
+           * Emitted when token is about to be destroyed.
+           *
+           * @event destroy
+           */
           this.$emit('destroy');
         }
       },
@@ -124,6 +148,11 @@ export default {
       this.activeSegment = segment;
 
       if (!this.active) {
+        /**
+         * Emitted when this term token is clicked.
+         *
+         * @event activate
+         */
         this.$emit('activate');
       }
     },
@@ -138,6 +167,10 @@ export default {
 
     replaceWithTermIfEmpty() {
       if (this.value.operator === '' && this.value.data === '') {
+        /**
+         * Emitted when this token is converted to another type
+         * @property {object} token Replacement token configuration
+         */
         this.$emit('replace', { type: TERM_TOKEN_TYPE, value: { data: this.config.title } });
       }
     },
@@ -147,6 +180,11 @@ export default {
 
       if (newTokenConfig === this.config) {
         this.$nextTick(() => {
+          /**
+           * Emitted when this term token will lose its focus.
+           *
+           * @event deactivate
+           */
           this.$emit('deactivate');
         });
         return;
@@ -193,6 +231,11 @@ export default {
       if (this.config.multiSelect) {
         this.$emit('input', { ...this.value, data: this.multiSelectValues.join(COMMA) });
       }
+      /**
+       * Emitted when the token entry has been completed.
+       *
+       * @event complete
+       */
       this.$emit('complete');
     },
 
@@ -208,6 +251,10 @@ export default {
 
 <template>
   <div class="gl-filtered-search-token" :class="{ 'gl-filtered-search-token-active': active }">
+    <!--
+      Emitted when the token is submitted.
+      @event submit
+    -->
     <gl-filtered-search-token-segment
       key="title-segment"
       :value="config.title"
@@ -261,6 +308,16 @@ export default {
       </template>
     </gl-filtered-search-token-segment>
     <!-- eslint-disable vue/no-mutating-props -->
+    <!--
+      Emitted when a suggestion has been selected.
+      @event select
+      @type {string} value The value of the selected suggestion.
+    -->
+    <!--
+      Emitted when Space is pressed in-between term text.
+      @event split
+      @property {array} newTokens Token configurations
+    -->
     <gl-filtered-search-token-segment
       v-if="hasDataOrDataSegmentIsCurrentlyActive"
       key="data-segment"
@@ -279,9 +336,11 @@ export default {
     >
       <!-- eslint-enable vue/no-mutating-props -->
       <template #suggestions>
+        <!-- @slot The suggestions (implemented with GlFilteredSearchSuggestion). -->
         <slot name="suggestions"></slot>
       </template>
       <template #view="{ inputValue }">
+        <!-- @slot Used to customize how the token is rendered. -->
         <slot
           name="view-token"
           v-bind="{
@@ -300,6 +359,10 @@ export default {
             @mousedown="destroyByClose"
           >
             <span class="gl-filtered-search-token-data-content">
+              <!--
+              @slot Template for token value in inactive state
+              @binding {array} suggestions Slot for rendering autocomplete suggestions when no options are provided.
+              -->
               <slot name="view" v-bind="{ inputValue }">{{ inputValue }}</slot>
             </span>
           </gl-token>

package/src/components/base/filtered_search/filtered_search_token_segment.documentation.js

@@ -2,47 +2,4 @@ import * as description from './filtered_search_token_segment.md';
 
 export default {
   description,
-  bootstrapComponent: null,
-  propsInfo: {
-    active: {
-      additionalInfo: 'If this term token is currently active',
-    },
-    options: {
-      additionalInfo: '',
-    },
-    optionTextField: {
-      additionalInfo: '',
-    },
-    customInputKeydownHandler: {
-      additionalInfo: '',
-    },
-    value: {
-      additionalInfo: 'Current term value',
-    },
-    searchInputAttributes: {
-      additionalInfo: 'HTML attributes to add to the search input',
-    },
-    isLastToken: {
-      additionalInfo: 'If this is the last token',
-    },
-  },
-  events: [
-    { event: 'activate', description: 'Emitted on mousedown event on the main component' },
-    { event: 'backspace', description: 'Emitted when Backspace is pressed and the value is empty' },
-    {
-      event: 'complete',
-      description: 'Emitted when suggestion is selected from the suggestion list',
-    },
-    { event: 'submit', description: 'Emitted when Enter is pressed and no suggestion is selected' },
-    {
-      event: 'split',
-      args: [
-        {
-          arg: 'newStrings',
-          description: '(Array of strings) New strings to be converted into term tokens',
-        },
-      ],
-      description: 'Emitted when Space appears in token segment value',
-    },
-  ],
 };

package/src/components/base/filtered_search/filtered_search_token_segment.md

@@ -1,5 +1,3 @@
-# Filtered Search Token Segment
-
 The filtered search token segment is a component for managing token input either via free typing
 or by selecting item through dropdown list
 

package/src/components/base/filtered_search/filtered_search_token_segment.stories.js

@@ -1,8 +1,6 @@
-import { withKnobs, boolean } from '@storybook/addon-knobs';
 import PortalVue from 'portal-vue';
 import Vue from 'vue';
 import { GlFilteredSearchSuggestion } from '../../../index';
-import { documentedStoriesOf } from '../../../../documentation/documented_stories';
 import { provide } from './common_story_options';
 import readme from './filtered_search_term.md';
 import GlFilteredSearchTokenSegment from './filtered_search_token_segment.vue';
@@ -14,84 +12,93 @@ const staticOptions = [
   { icon: 'eye', value: false, title: 'No' },
 ];
 
-documentedStoriesOf('base/filtered-search/token-segment', readme)
-  .addDecorator(withKnobs)
-  .add('default', () => ({
-    components: {
-      GlFilteredSearchTokenSegment,
-      GlFilteredSearchSuggestion,
-    },
-    provide,
-    props: {
-      active: {
-        type: Boolean,
-        default: boolean('active', true),
-      },
-    },
-    data() {
-      return {
-        value: 'demo1',
-      };
-    },
-    mounted() {
-      this.$nextTick(() => document.activeElement.blur());
-    },
-    template: `
+const generateProps = ({ active = true } = {}) => ({
+  active,
+});
+
+// eslint-disable-next-line no-unused-vars
+export const Default = (args, { argTypes }) => ({
+  components: {
+    GlFilteredSearchTokenSegment,
+    GlFilteredSearchSuggestion,
+  },
+  provide,
+  props: ['active'],
+  data() {
+    return {
+      value: 'demo1',
+    };
+  },
+  mounted() {
+    this.$nextTick(() => document.activeElement.blur());
+  },
+  template: `
+    <div>
+      <div>v-model value: {{ value }} </div>
+      <div class="gl-border-1 gl-border-solid gl-border-gray-200">
+        <gl-filtered-search-token-segment
+          v-model="value"
+          class="gl-h-full"
+          :active="active"
+        >
+          <template #suggestions>
+            <gl-filtered-search-suggestion value="demo1">Static suggestion 1</gl-filtered-search-suggestion>
+            <gl-filtered-search-suggestion value="demo2">Static suggestion 2</gl-filtered-search-suggestion>
+          </template>
+        </gl-filtered-search-token-segment>
+      </div>
       <div>
-        <div>v-model value: {{ value }} </div>
-        <div class="gl-border-1 gl-border-solid gl-border-gray-200">
-          <gl-filtered-search-token-segment
-            v-model="value"
-            class="gl-h-full"
-            :active="active"
-          >
-            <template #suggestions>
-              <gl-filtered-search-suggestion value="demo1">Static suggestion 1</gl-filtered-search-suggestion>
-              <gl-filtered-search-suggestion value="demo2">Static suggestion 2</gl-filtered-search-suggestion>
-            </template>
-          </gl-filtered-search-token-segment>
-        </div>
-        <div>
-          <portal-target name="portal" class="gl-relative" />
-        </div>
+        <portal-target name="portal" class="gl-relative" />
+      </div>
+    </div>
+  `,
+});
+Default.args = generateProps();
+
+// eslint-disable-next-line no-unused-vars
+export const WithStaticOptions = (args, { argTypes }) => ({
+  components: {
+    GlFilteredSearchTokenSegment,
+  },
+  provide,
+  props: ['active'],
+  data() {
+    return {
+      value: true,
+      staticOptions,
+    };
+  },
+  mounted() {
+    this.$nextTick(() => document.activeElement.blur());
+  },
+  template: `
+    <div>
+      <div>v-model value: {{ value }} </div>
+      <div class="gl-border-1 gl-border-solid gl-border-gray-200">
+        <gl-filtered-search-token-segment
+          v-model="value"
+          class="gl-h-full"
+          :active="active"
+          :options="staticOptions"
+          option-text-field="title"
+        />
       </div>
-    `,
-  }))
-  .add('with static options', () => ({
-    components: {
-      GlFilteredSearchTokenSegment,
-    },
-    provide,
-    props: {
-      active: {
-        type: Boolean,
-        default: boolean('active', true),
-      },
-    },
-    data() {
-      return {
-        value: true,
-        staticOptions,
-      };
-    },
-    mounted() {
-      this.$nextTick(() => document.activeElement.blur());
-    },
-    template: `
       <div>
-        <div>v-model value: {{ value }} </div>
-        <div class="gl-border-1 gl-border-solid gl-border-gray-200">
-          <gl-filtered-search-token-segment
-            v-model="value"
-            class="gl-h-full"
-            :active="active"
-            :options="staticOptions"
-            option-text-field="title"
-          />
-        </div>
-        <div>
-          <portal-target name="portal" class="gl-relative" />
-        </div>
+        <portal-target name="portal" class="gl-relative" />
       </div>
-    `,
-  }));
+    </div>
+  `,
+});
+WithStaticOptions.args = generateProps();
+
+export default {
+  title: 'base/filtered-search/token-segment',
+  component: GlFilteredSearchTokenSegment,
+  parameters: {
+    docs: {
+      description: {
+        component: readme,
+      },
+    },
+  },
+};

package/src/components/base/filtered_search/filtered_search_token_segment.vue

@@ -7,6 +7,7 @@ import GlFilteredSearchSuggestionList from './filtered_search_suggestion_list.vu
 import { splitOnQuotes, wrapTokenInQuotes } from './filtered_search_utils';
 
 export default {
+  name: 'GlFilteredSearchTokenSegment',
   components: {
     Portal,
     GlFilteredSearchSuggestionList,
@@ -15,6 +16,9 @@ export default {
   inject: ['portalName', 'alignSuggestions'],
   inheritAttrs: false,
   props: {
+    /**
+     * If this token segment is currently being edited.
+     */
     active: {
       type: Boolean,
       required: false,
@@ -45,15 +49,24 @@ export default {
       required: false,
       default: () => () => false,
     },
+    /**
+     * Current term value
+     */
     value: {
       required: true,
       validator: () => true,
     },
+    /**
+     * HTML attributes to add to the search input
+     */
     searchInputAttributes: {
       type: Object,
       required: false,
       default: () => ({}),
     },
+    /**
+     * If this is the last token
+     */
     isLastToken: {
       type: Boolean,
       required: false,
@@ -89,6 +102,11 @@ export default {
       },
 
       set(v) {
+        /**
+         * Emitted when this token segment's value changes.
+         *
+         * @type {object} option The current option.
+         */
         this.$emit('input', this.getMatchingOptionForInputValue(v)?.value ?? v);
       },
     },
@@ -145,6 +163,10 @@ export default {
       this.$emit('input', this.getMatchingOptionForInputValue(firstWord)?.value ?? firstWord);
 
       if (otherWords.length) {
+        /**
+         * Emitted when Space appears in token segment value
+         * @property {array|string} newStrings New strings to be converted into term tokens
+         */
         this.$emit('split', otherWords);
       }
     },
@@ -153,6 +175,9 @@ export default {
   methods: {
     emitIfInactive(e) {
       if (!this.active) {
+        /**
+         * Emitted on mousedown event on the main component.
+         */
         this.$emit('activate');
         e.preventDefault();
       }
@@ -190,6 +215,11 @@ export default {
     applySuggestion(suggestedValue) {
       const formattedSuggestedValue = wrapTokenInQuotes(suggestedValue);
 
+      /**
+       * Emitted when autocomplete entry is selected.
+       *
+       * @type {string} value The selected value.
+       */
       this.$emit('select', formattedSuggestedValue);
 
       if (!this.multiSelect) {
@@ -205,6 +235,9 @@ export default {
       if (key === 'Backspace') {
         if (this.inputValue === '') {
           e.preventDefault();
+          /**
+           * Emitted when Backspace is pressed and the value is empty
+           */
           this.$emit('backspace');
         }
         return;
@@ -216,6 +249,9 @@ export default {
           if (suggestedValue != null) {
             this.applySuggestion(suggestedValue);
           } else {
+            /**
+             * Emitted when Enter is pressed and no suggestion is selected
+             */
             this.$emit('submit');
           }
         },
@@ -227,6 +263,9 @@ export default {
         },
         Escape: () => {
           e.preventDefault();
+          /**
+           * Emitted when suggestion is selected from the suggestion list
+           */
           this.$emit('complete');
         },
       };
@@ -258,6 +297,9 @@ export default {
       if (this.multiSelect) {
         this.$emit('complete');
       } else if (this.active) {
+        /**
+         * Emitted when this term token will lose its focus.
+         */
         this.$emit('deactivate');
       }
     },

package/src/components/base/form/form_radio/form_radio.spec.js

@@ -5,6 +5,8 @@ import GlFormRadio from './form_radio.vue';
 describe('GlFormRadio', () => {
   let wrapper;
   let options;
+  let eventHandlers;
+
   const firstOption = {
     text: 'One',
     value: 'one',
@@ -16,6 +18,10 @@ describe('GlFormRadio', () => {
 
   const createWrapper = () => {
     options = [firstOption, secondOption];
+    eventHandlers = {
+      input: jest.fn(),
+      change: jest.fn(),
+    };
 
     wrapper = mount({
       data() {
@@ -32,9 +38,15 @@ describe('GlFormRadio', () => {
             :key="option.value"
             v-model="selected"
             :value="option.value"
+            @change="changeHandler"
+            @input="inputHandler"
           >{{ option.text }}</gl-form-radio>
         </div>
       `,
+      methods: {
+        changeHandler: eventHandlers.change,
+        inputHandler: eventHandlers.input,
+      },
     });
   };
 
@@ -79,16 +91,17 @@ describe('GlFormRadio', () => {
     });
 
     it('emits an input event on each radio, and a change event on the newly selected radio', () => {
-      const [formRadioOne, formRadioTwo] = wrapper.findAllComponents(GlFormRadio).wrappers;
+      const { input, change } = eventHandlers;
+      const { value: clickedRadioValue } = secondOption;
 
-      expect(formRadioOne.emitted()).toEqual({
-        input: [[secondOption.value]],
-      });
+      // The input handler is called twice because each radio emits one input event.
+      expect(input).toHaveBeenCalledTimes(2);
+      expect(input).toHaveBeenNthCalledWith(1, clickedRadioValue);
+      expect(input).toHaveBeenNthCalledWith(2, clickedRadioValue);
 
-      expect(formRadioTwo.emitted()).toEqual({
-        input: [[secondOption.value]],
-        change: [[secondOption.value]],
-      });
+      // The change handler is only called once, since only the newly selected radio emits a change event.
+      expect(change).toHaveBeenCalledTimes(1);
+      expect(change).toHaveBeenCalledWith(clickedRadioValue);
     });
 
     it('updates the bound value', () => {

package/src/components/base/form/form_radio/form_radio.vue

@@ -38,7 +38,6 @@ export default {
     class="gl-form-radio"
     :checked="checked"
     v-bind="$attrs"
-    v-on="$listeners"
     @input="$emit('input', $event)"
     @change="$emit('change', $event)"
   >

package/src/components/charts/series_label/series_label.stories.js

@@ -35,14 +35,13 @@ const Template = (_args, { argTypes }) => ({
 });
 
 export const Default = Template.bind({});
-Default.args = generateProps({ color: '' });
+Default.args = generateProps();
 
 export const WithLongName = Template.bind({});
-WithLongName.args = generateProps({ color: '', text: SERIES_NAME[SERIES_NAME_LONG] });
+WithLongName.args = generateProps({ text: SERIES_NAME[SERIES_NAME_LONG] });
 
 export const WithLongNameWithNoSpaces = Template.bind({});
 WithLongNameWithNoSpaces.args = generateProps({
-  color: '',
   text: SERIES_NAME[SERIES_NAME_LONG_WITHOUT_SPACES],
 });
 
@@ -72,6 +71,10 @@ export default {
     },
   },
   argTypes: {
+    type: {
+      control: 'select',
+      options: ['solid', 'dashed'],
+    },
     color: {
       control: 'color',
     },

package/src/components/charts/series_label/series_label.vue

@@ -12,6 +12,9 @@ export default {
       type: String,
       required: false,
       default: 'solid',
+      validator(value) {
+        return ['solid', 'dashed'].indexOf(value) !== -1;
+      },
     },
   },
   data() {