@gitlab/ui 38.0.1 → 38.2.1

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

@@ -1,7 +1,5 @@
-import { withKnobs, boolean } from '@storybook/addon-knobs';
 import PortalVue from 'portal-vue';
 import Vue from 'vue';
-import { documentedStoriesOf } from '../../../../documentation/documented_stories';
 import { GlIcon } from '../../../index';
 import { provide } from './common_story_options';
 import GlFilteredSearchSuggestion from './filtered_search_suggestion.vue';
@@ -10,152 +8,159 @@ import GlFilteredSearchToken from './filtered_search_token.vue';
 
 Vue.use(PortalVue);
 
-documentedStoriesOf('base/filtered-search/token', readme)
-  .addDecorator(withKnobs)
-  .add('default', () => ({
-    components: {
-      GlFilteredSearchToken,
-      GlFilteredSearchSuggestion,
-      GlIcon,
-    },
-    provide,
-    props: {
-      active: {
-        type: Boolean,
-        default: boolean('active', true),
+const generateProps = ({ active = true } = {}) => ({
+  active,
+});
+
+// eslint-disable-next-line no-unused-vars
+export const Default = (args, { argTypes }) => ({
+  components: {
+    GlFilteredSearchToken,
+    GlFilteredSearchSuggestion,
+    GlIcon,
+  },
+  provide,
+  props: ['active'],
+  data() {
+    return {
+      value: { operator: '=', data: 'Yes' },
+      config: {
+        title: 'Confidential',
       },
-    },
-    data() {
-      return {
-        value: { operator: '=', data: 'Yes' },
-        config: {
-          title: 'Confidential',
-        },
-      };
-    },
-    mounted() {
-      this.$nextTick(() => {
-        document.activeElement.blur();
-      });
-    },
-    template: `
+    };
+  },
+  mounted() {
+    this.$nextTick(() => {
+      document.activeElement.blur();
+    });
+  },
+  template: `
+    <div>
+      <div> {{ value }} </div>
+      <div class="gl-border-1 gl-border-solid gl-border-gray-200">
+        <gl-filtered-search-token
+          v-model="value"
+          class="gl-h-full"
+          :config="config"
+          :active="active"
+        >
+          <template #suggestions>
+            <gl-filtered-search-suggestion value="Yes"><gl-icon name="eye-slash" :size="16"/> Yes</gl-filtered-search-suggestion>
+            <gl-filtered-search-suggestion value="No"><gl-icon name="eye" :size="16"/> No</gl-filtered-search-suggestion>
+          </template>
+        </gl-filtered-search-token>
+      </div>
       <div>
-        <div> {{ value }} </div>
-        <div class="gl-border-1 gl-border-solid gl-border-gray-200">
-          <gl-filtered-search-token
-            v-model="value"
-            class="gl-h-full"
-            :config="config"
-            :active="active"
-          >
-            <template #suggestions>
-              <gl-filtered-search-suggestion value="Yes"><gl-icon name="eye-slash" :size="16"/> Yes</gl-filtered-search-suggestion>
-              <gl-filtered-search-suggestion value="No"><gl-icon name="eye" :size="16"/> No</gl-filtered-search-suggestion>
-            </template>
-          </gl-filtered-search-token>
-        </div>
-        <div>
-          <portal-target name="portal" class="gl-relative" />
-        </div>
+        <portal-target name="portal" class="gl-relative" />
       </div>
-    `,
-  }))
-  .add('with custom operators options', () => ({
-    components: {
-      GlFilteredSearchToken,
-      GlFilteredSearchSuggestion,
-    },
-    provide,
-    props: {
-      active: {
-        type: Boolean,
-        default: boolean('active', true),
-      },
-    },
-    data() {
-      return {
-        value: { operator: '=', data: 'Yes' },
-        config: {
-          title: 'Confidential',
-        },
+    </div>
+  `,
+});
+Default.args = generateProps();
+
+// eslint-disable-next-line no-unused-vars
+export const WithCustomOperatorsOptions = (args, { argTypes }) => ({
+  components: {
+    GlFilteredSearchToken,
+    GlFilteredSearchSuggestion,
+    GlIcon,
+  },
+  provide,
+  props: ['active'],
+  data() {
+    return {
+      value: { operator: '!', data: 'Yes' },
+      config: {
+        title: 'Confidential',
         operators: [
           { value: '^', description: 'or' },
           { value: '!', description: 'is not', default: 'true' },
         ],
-      };
-    },
-    mounted() {
-      this.$nextTick(() => {
-        document.activeElement.blur();
-      });
-    },
-    template: `
-      <div>
-        <div> {{ value }} </div>
-        <div class="gl-border-1 gl-border-solid gl-border-gray-200">
-          <gl-filtered-search-token
-            v-model="value"
-            class="gl-h-full"
-            :config="config"
-            :active="active"
-            :operators="operators"
-          >
+      },
+    };
+  },
+  mounted() {
+    this.$nextTick(() => {
+      document.activeElement.blur();
+    });
+  },
+  template: `
+    <div>
+      <div> {{ value }} </div>
+      <div class="gl-border-1 gl-border-solid gl-border-gray-200">
+        <gl-filtered-search-token
+          v-model="value"
+          class="gl-h-full"
+          :config="config"
+          :active="active"
+        >
           <template #suggestions>
             <gl-filtered-search-suggestion value="Yes"><gl-icon name="eye-slash" :size="16"/> Yes</gl-filtered-search-suggestion>
             <gl-filtered-search-suggestion value="No"><gl-icon name="eye" :size="16"/> No</gl-filtered-search-suggestion>
           </template>
-        </div>
-        <div>
-          <portal-target name="portal" class="gl-relative" />
-        </div>
+        </gl-filtered-search-token>
       </div>
-    `,
-  }))
-  .add('with static options', () => ({
-    components: {
-      GlFilteredSearchToken,
-      GlFilteredSearchSuggestion,
-    },
-    provide,
-    props: {
-      active: {
-        type: Boolean,
-        default: boolean('active', true),
-      },
-    },
-    data() {
-      return {
-        value: { operator: '=', data: 'first' },
-        config: {
-          title: 'Confidential',
-        },
+      <div>
+        <portal-target name="portal" class="gl-relative" />
+      </div>
+    </div>
+  `,
+});
+WithCustomOperatorsOptions.args = generateProps();
+
+// eslint-disable-next-line no-unused-vars
+export const WithStaticOptions = (args, { argTypes }) => ({
+  components: {
+    GlFilteredSearchToken,
+    GlFilteredSearchSuggestion,
+  },
+  provide,
+  props: ['active'],
+  data() {
+    return {
+      value: { operator: '=', data: 'first' },
+      config: {
+        title: 'Confidential',
         options: [
           { icon: 'hourglass', title: 'first', value: 'one' },
           { title: 'second-without-icon', value: 'two' },
           { icon: 'issues', title: 'third', value: 'three' },
         ],
-      };
-    },
-    mounted() {
-      this.$nextTick(() => {
-        document.activeElement.blur();
-      });
-    },
-    template: `
+      },
+    };
+  },
+  mounted() {
+    this.$nextTick(() => {
+      document.activeElement.blur();
+    });
+  },
+  template: `
+    <div>
+      <div> {{ value }} </div>
+      <div class="gl-border-1 gl-border-solid gl-border-gray-200">
+        <gl-filtered-search-token
+          v-model="value"
+          class="gl-h-full"
+          :config="config"
+          :active="active"
+        />
+      </div>
       <div>
-        <div> {{ value }} </div>
-        <div class="gl-border-1 gl-border-solid gl-border-gray-200">
-          <gl-filtered-search-token
-            v-model="value"
-            class="gl-h-full"
-            :config="config"
-            :active="active"
-            :options="options"
-          />
-        </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',
+  component: GlFilteredSearchToken,
+  parameters: {
+    docs: {
+      description: {
+        component: readme,
+      },
+    },
+  },
+};

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

@@ -1,8 +1,9 @@
 <script>
+import { cloneDeep } from 'lodash';
 import { COMMA } from '../../../utils/constants';
 import GlToken from '../token/token.vue';
 import GlFilteredSearchTokenSegment from './filtered_search_token_segment.vue';
-import { TERM_TOKEN_TYPE } from './filtered_search_utils';
+import { createTerm } from './filtered_search_utils';
 
 const SEGMENT_TITLE = 'TYPE';
 const SEGMENT_OPERATOR = 'OPERATOR';
@@ -15,6 +16,7 @@ const DEFAULT_OPERATORS = [
 ];
 
 export default {
+  name: 'GlFilteredSearchToken',
   components: {
     GlToken,
     GlFilteredSearchTokenSegment,
@@ -26,11 +28,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 +49,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,
@@ -55,6 +69,7 @@ export default {
   data() {
     return {
       activeSegment: null,
+      tokenValue: cloneDeep(this.value),
     };
   },
 
@@ -64,7 +79,7 @@ export default {
     },
 
     hasDataOrDataSegmentIsCurrentlyActive() {
-      return this.value.data !== '' || this.isSegmentActive(SEGMENT_DATA);
+      return this.tokenValue.data !== '' || this.isSegmentActive(SEGMENT_DATA);
     },
 
     availableTokensWithSelf() {
@@ -75,7 +90,7 @@ export default {
     },
 
     operatorDescription() {
-      const operator = this.operators.find((op) => op.value === this.value.operator);
+      const operator = this.operators.find((op) => op.value === this.tokenValue.operator);
       return this.showFriendlyText ? operator?.description : operator?.value;
     },
   },
@@ -85,22 +100,43 @@ export default {
     SEGMENT_OPERATOR,
   },
   watch: {
-    value: {
+    tokenValue: {
       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);
       },
     },
 
+    value: {
+      handler(newValue, oldValue) {
+        if (newValue?.data === oldValue?.data && newValue?.operator === oldValue?.operator) {
+          return;
+        }
+
+        this.tokenValue = cloneDeep(newValue);
+      },
+    },
+
     active: {
       immediate: true,
       handler(newValue) {
         if (newValue) {
           if (!this.activeSegment) {
-            this.activateSegment(this.value.data !== '' ? SEGMENT_DATA : SEGMENT_OPERATOR);
+            this.activateSegment(this.tokenValue.data !== '' ? SEGMENT_DATA : SEGMENT_OPERATOR);
           }
-        } else if (this.value.data === '') {
+        } else if (this.tokenValue.data === '') {
           this.activeSegment = null;
+          /**
+           * Emitted when token is about to be destroyed.
+           *
+           * @event destroy
+           */
           this.$emit('destroy');
         }
       },
@@ -108,13 +144,13 @@ export default {
   },
 
   created() {
-    if (!('operator' in this.value)) {
+    if (!('operator' in this.tokenValue)) {
       if (this.operators.length === 1) {
         const operator = this.operators[0].value;
-        this.$emit('input', { ...this.value, operator });
+        this.$emit('input', { ...this.tokenValue, operator });
         this.activeSegment = SEGMENT_DATA;
       } else {
-        this.$emit('input', { ...this.value, operator: '' });
+        this.$emit('input', { ...this.tokenValue, operator: '' });
       }
     }
   },
@@ -124,6 +160,11 @@ export default {
       this.activeSegment = segment;
 
       if (!this.active) {
+        /**
+         * Emitted when this term token is clicked.
+         *
+         * @event activate
+         */
         this.$emit('activate');
       }
     },
@@ -137,8 +178,12 @@ export default {
     },
 
     replaceWithTermIfEmpty() {
-      if (this.value.operator === '' && this.value.data === '') {
-        this.$emit('replace', { type: TERM_TOKEN_TYPE, value: { data: this.config.title } });
+      if (this.tokenValue.operator === '' && this.tokenValue.data === '') {
+        /**
+         * Emitted when this token is converted to another type
+         * @property {object} token Replacement token configuration
+         */
+        this.$emit('replace', createTerm(this.config.title));
       }
     },
 
@@ -147,6 +192,11 @@ export default {
 
       if (newTokenConfig === this.config) {
         this.$nextTick(() => {
+          /**
+           * Emitted when this term token will lose its focus.
+           *
+           * @event deactivate
+           */
           this.$emit('deactivate');
         });
         return;
@@ -157,7 +207,7 @@ export default {
           this.config.dataType && this.config.dataType === newTokenConfig.dataType;
         this.$emit('replace', {
           type: newTokenConfig.type,
-          value: isCompatible ? this.value : { data: '' },
+          value: isCompatible ? this.tokenValue : { data: '' },
         });
       }
     },
@@ -174,7 +224,7 @@ export default {
         key.length === 1 &&
         !this.operators.find(({ value }) => value.startsWith(potentialValue))
       ) {
-        if (this.value.data === '') {
+        if (this.tokenValue.data === '') {
           applySuggestion(suggestedValue);
         } else {
           evt.preventDefault();
@@ -184,21 +234,27 @@ export default {
 
     activateDataSegment() {
       if (this.config.multiSelect) {
-        this.$emit('input', { ...this.value, data: '' });
+        this.$emit('input', { ...this.tokenValue, data: '' });
       }
       this.activateSegment(this.$options.segments.SEGMENT_DATA);
     },
 
     handleComplete() {
       if (this.config.multiSelect) {
-        this.$emit('input', { ...this.value, data: this.multiSelectValues.join(COMMA) });
+        this.$emit('input', { ...this.tokenValue, data: this.multiSelectValues.join(COMMA) });
       }
+      /**
+       * Emitted when the token entry has been completed.
+       *
+       * @event complete
+       */
       this.$emit('complete');
     },
 
     destroyByClose(event) {
       if (event.target.closest(TOKEN_CLOSE_SELECTOR)) {
         event.preventDefault();
+        event.stopPropagation();
         this.$emit('destroy');
       }
     },
@@ -208,6 +264,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"
@@ -228,10 +288,9 @@ export default {
         >
       </template>
     </gl-filtered-search-token-segment>
-    <!-- eslint-disable vue/no-mutating-props -->
     <gl-filtered-search-token-segment
       key="operator-segment"
-      v-model="value.operator"
+      v-model="tokenValue.operator"
       :active="isSegmentActive($options.segments.SEGMENT_OPERATOR)"
       :options="operators"
       :custom-input-keydown-handler="handleOperatorKeydown"
@@ -241,7 +300,6 @@ export default {
       @complete="activateSegment($options.segments.SEGMENT_DATA)"
       @deactivate="$emit('deactivate')"
     >
-      <!-- eslint-enable vue/no-mutating-props -->
       <template #view>
         <gl-token
           class="gl-filtered-search-token-operator"
@@ -260,11 +318,20 @@ export default {
         </div>
       </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"
-      v-model="value.data"
+      v-model="tokenValue.data"
       :active="isSegmentActive($options.segments.SEGMENT_DATA)"
       :multi-select="config.multiSelect"
       :options="config.options"
@@ -277,11 +344,12 @@ export default {
       @deactivate="$emit('deactivate')"
       @split="$emit('split', $event)"
     >
-      <!-- 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 +368,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