@gitlab/ui 37.10.0 → 38.1.0

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

@@ -1,82 +1,6 @@
-import examples from './examples';
 import * as description from './filtered_search.md';
 
 export default {
   description,
   followsDesignSystem: true,
-  bootstrapComponent: null,
-  examples,
-  propsInfo: {
-    value: {
-      additionalInfo: 'If provided, used as value of filtered search',
-    },
-    historyItems: {
-      additionalInfo: 'If provided, used as history items for this component',
-    },
-    availableTokens: {
-      additionalInfo: 'Available tokens',
-    },
-    placeholder: {
-      additionalInfo: 'If provided, used as history items for this component',
-    },
-    recentSearchesHeader: {
-      additionalInfo: 'i18n for recent searches title within history dropdown',
-    },
-    clearButtonTitle: {
-      additionalInfo: 'i18n for clear button title',
-    },
-    closeButtonTitle: {
-      additionalInfo: 'i18n for close button title within history dropdown',
-    },
-    clearRecentSearchesText: {
-      additionalInfo: 'i18n for recent searches clear text',
-    },
-    suggestionsListClass: {
-      additionalInfo:
-        'Additional classes to add to the suggestion list menu. NOTE: this not reactive, and the value must be available and fixed when the component is instantiated',
-    },
-    searchButtonAttributes: {
-      additionalInfo: 'HTML attributes to add to the search button',
-    },
-    searchInputAttributes: {
-      additionalInfo: 'HTML attributes to add to the search input',
-    },
-  },
-  events: [
-    {
-      event: 'clear',
-      description: 'Emitted when search is cleared',
-    },
-    {
-      event: 'submit',
-      args: [
-        {
-          arg: 'tokens',
-          description: '(Array)',
-        },
-      ],
-      description: 'Emitted when search is submitted',
-    },
-    {
-      event: 'history-item-selected',
-      args: [
-        {
-          arg: 'value',
-          description: 'History item',
-        },
-      ],
-      description: 'Emitted when item from history is selected',
-    },
-    {
-      event: 'clear-history',
-      description: 'Emitted when clear history button is clicked',
-    },
-  ],
-  slots: [
-    {
-      name: 'history-item',
-      description:
-        'Slot to customize history item in history dropdown. Used only if using history items',
-    },
-  ],
 };

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

@@ -1,5 +1,3 @@
-# Filtered Search
-
 The filtered search component is responsible for managing search with possible filters.
 
 ## Usage
@@ -61,6 +59,7 @@ const availableTokens = [
 Pass the list of tokens to the search component. Optionally, you can use `v-model` to receive
 realtime updates:
 
-```js
- <gl-filtered-search :available-tokens="tokens" v-model="value" />
+```html
+
+<gl-filtered-search :available-tokens="tokens" v-model="value" />
 ```

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

@@ -1,14 +1,16 @@
-import { withKnobs } from '@storybook/addon-knobs';
-import { documentedStoriesOf } from '../../../../documentation/documented_stories';
 import {
   GlFilteredSearch,
   GlFilteredSearchToken,
   GlFilteredSearchSuggestion,
+  GlFilteredSearchSuggestionList,
+  GlFilteredSearchTerm,
+  GlFilteredSearchTokenSegment,
   GlLoadingIcon,
   GlToken,
   GlAvatar,
 } from '../../../index';
 import { setStoryTimeout } from '../../../utils/test_utils';
+import { makeContainer } from '../../../utils/story_decorators/container';
 import readme from './filtered_search.md';
 
 const fakeUsers = [
@@ -296,19 +298,252 @@ const components = {
   GlFilteredSearch,
 };
 
-documentedStoriesOf('base/filtered-search', readme)
-  .addDecorator(withKnobs)
-  .add('default', () => ({
+export const Default = () => ({
+  data() {
+    return {
+      tokens,
+      value: [
+        { type: 'author', value: { data: 'beta', operator: '=' } },
+        { type: 'label', value: { data: 'Bug', operator: '=' } },
+        'raw text',
+      ],
+    };
+  },
+  components,
+  template: `<gl-filtered-search :available-tokens="tokens" :value="value" />`,
+});
+
+export const WithHistoryItems = () => ({
+  components,
+  data() {
+    return {
+      tokens: [
+        {
+          type: 'demotoken',
+          title: 'Unique',
+          icon: 'document',
+          token: 'gl-filtered-search-token',
+          operators: [{ value: '=', description: 'is', default: 'true' }],
+          options: [
+            { icon: 'heart', title: 'heart', value: 1 },
+            { icon: 'hook', title: 'hook', value: 2 },
+          ],
+          unique: true,
+        },
+      ],
+      value: [],
+      historyItems: [
+        [{ type: 'demotoken', value: { operator: '=', data: 1 } }, 'item 1'],
+        ['item 2', { type: 'demotoken', value: { operator: '=', data: 2 } }],
+      ],
+    };
+  },
+  methods: {
+    isString(val) {
+      return typeof val === 'string';
+    },
+  },
+  mounted() {
+    this.$nextTick(() => this.$el.querySelector('.gl-dropdown-toggle').click());
+  },
+  template: `
+    <div>
+      {{ value }}
+      <gl-filtered-search v-model="value" :available-tokens="tokens" :history-items="historyItems">
+        <template #history-item="{ historyItem }">
+          <template v-for="(token, idx) in historyItem">
+            <span v-if="isString(token)" :key="idx" class="gl-px-1">{{ token }}</span>
+            <span v-else :key="idx" class="gl-px-1">
+              <strong>{{ token.type }}</strong> {{ token.value.operator }}
+              <strong>{{ token.value.data }}</strong>
+            </span>
+          </template>
+        </template>
+      </gl-filtered-search>
+    </div>
+  `,
+});
+
+export const WithFriendlyText = () => ({
+  components,
+  data() {
+    return {
+      tokens: [
+        {
+          type: 'weight',
+          icon: 'weight',
+          title: 'Weight',
+          unique: true,
+          token: 'gl-filtered-search-token',
+        },
+        {
+          type: 'confidential',
+          icon: 'eye-slash',
+          title: 'Confidential',
+          unique: true,
+          token: 'gl-filtered-search-token',
+          options: [
+            { icon: 'eye-slash', value: 'Yes', title: 'Yes' },
+            { icon: 'eye', value: 'No', title: 'No' },
+          ],
+        },
+      ],
+      value: [
+        { type: 'weight', value: { data: '3', operator: '=' } },
+        { type: 'confidential', value: { data: 'Yes', operator: '!=' } },
+      ],
+    };
+  },
+  template: `
+    <gl-filtered-search
+      v-model="value"
+      :available-tokens="tokens"
+      :show-friendly-text="true"
+    />
+  `,
+});
+
+export const WithMultiSelect = () => {
+  const MultiUserToken = {
+    props: ['value', 'active', 'config'],
+    inheritAttrs: false,
     data() {
       return {
-        tokens,
-        value: [
-          { type: 'author', value: { data: 'beta', operator: '=' } },
-          { type: 'label', value: { data: 'Bug', operator: '=' } },
-          'raw text',
-        ],
+        users: fakeUsers,
+        selectedUsernames: this.value.data ? this.value.data.split(',') : [],
+        activeUser: null,
       };
     },
+    computed: {
+      filteredUsers() {
+        return this.users.filter((user) => user.username.includes(this.value.data));
+      },
+      selectedUsers() {
+        return this.config.multiSelect
+          ? this.users.filter((user) => this.selectedUsernames.includes(user.username))
+          : this.users.filter((user) => user.username === this.activeUser);
+      },
+    },
+    methods: {
+      loadView() {
+        this.activeUser = fakeUsers.find((u) => u.username === this.value.data);
+      },
+      loadSuggestions() {
+        this.users = fakeUsers;
+      },
+      handleSelect(username) {
+        if (!this.config.multiSelect) {
+          return;
+        }
+
+        if (this.selectedUsernames.includes(username)) {
+          this.selectedUsernames = this.selectedUsernames.filter((user) => user !== username);
+        } else {
+          this.selectedUsernames.push(username);
+        }
+      },
+      isLastUser(index) {
+        return index === this.selectedUsers.length - 1;
+      },
+    },
+    watch: {
+      // eslint-disable-next-line func-names
+      'value.data': function () {
+        if (this.active) {
+          this.loadSuggestions();
+        }
+      },
+      active: {
+        immediate: true,
+        handler(newValue) {
+          if (!newValue) {
+            this.loadView();
+          } else {
+            this.loadSuggestions();
+          }
+        },
+      },
+    },
+    template: `
+    <gl-filtered-search-token
+      v-bind="{ ...this.$props, ...this.$attrs }"
+      v-on="$listeners"
+      :multi-select-values="selectedUsernames"
+      @select="handleSelect"
+    >
+    <template #view="{ inputValue }">
+      <template v-for="(user, index) in selectedUsers">
+        <gl-avatar :size="16" :entity-name="user.username" shape="circle" />
+        {{ user.name }}
+        <span v-if="!isLastUser(index)" class="gl-mx-2">,&nbsp;</span>
+      </template>
+    </template>
+    <template #suggestions>
+      <gl-filtered-search-suggestion :key="user.id" v-for="user in filteredUsers" :value="user.username">
+        <div class="gl-display-flex gl-align-items-center">
+          <gl-icon
+            v-if="config.multiSelect"
+            name="check"
+            class="gl-mr-3 gl-text-gray-700"
+            :class="{ 'gl-visibility-hidden': !selectedUsernames.includes(user.username) }"
+          />
+          <gl-avatar :size="32" :entity-name="user.username" />
+          <div>
+            <p class="gl-m-0">{{ user.name }}</p>
+            <p class="gl-m-0">@{{ user.username }}</p>
+          </div>
+        </div>
+      </gl-filtered-search-suggestion>
+    </template>
+    </gl-filtered-search-token>
+  `,
+  };
+
+  return {
     components,
-    template: `<gl-filtered-search :available-tokens="tokens" :value="value" />`,
-  }));
+    data() {
+      return {
+        tokens: [
+          {
+            type: 'assignee',
+            icon: 'user',
+            title: 'Assignee',
+            token: MultiUserToken,
+            operators: [
+              { value: '=', description: 'is', default: 'true' },
+              { value: '!=', description: 'is not one of' },
+              { value: '||', description: 'is one of' },
+            ],
+            multiSelect: true,
+          },
+        ],
+        value: [{ type: 'assignee', value: { data: 'alpha,beta', operator: '=' } }],
+      };
+    },
+    template: `
+      <gl-filtered-search v-model="value" :available-tokens="tokens" />
+    `,
+  };
+};
+
+export default {
+  title: 'base/filtered-search',
+  // Make room for suggestion lists
+  decorators: [makeContainer({ height: '250px' })],
+  component: GlFilteredSearch,
+  subcomponents: {
+    GlFilteredSearchSuggestion,
+    GlFilteredSearchSuggestionList,
+    GlFilteredSearchTerm,
+    GlFilteredSearchTokenSegment,
+    GlFilteredSearchToken,
+  },
+  parameters: {
+    docs: {
+      description: {
+        component: readme,
+      },
+    },
+  },
+  argTypes: {},
+};

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

@@ -1,5 +1,5 @@
 <script>
-import { cloneDeep, isEqual } from 'lodash';
+import { cloneDeep } from 'lodash';
 import PortalVue from 'portal-vue';
 import Vue from 'vue';
 import { GlTooltipDirective } from '../../../directives/tooltip';
@@ -31,6 +31,7 @@ function initialState() {
 }
 
 export default {
+  name: 'GlFilteredSearch',
   components: {
     GlSearchBoxByClick,
     GlIcon,
@@ -51,16 +52,25 @@ export default {
   },
   inheritAttrs: false,
   props: {
+    /**
+     * If provided, used as value of filtered search
+     */
     value: {
       required: false,
       type: Array,
       default: () => [],
     },
+    /**
+     * Available tokens
+     */
     availableTokens: {
       type: Array,
       required: false,
       default: () => [],
     },
+    /**
+     * If provided, used as history items for this component
+     */
     placeholder: {
       type: String,
       required: false,
@@ -76,21 +86,34 @@ export default {
       required: false,
       default: null,
     },
+    /**
+     * Additional classes to add to the suggestion list menu. NOTE: this not reactive, and the value
+     * must be available and fixed when the component is instantiated
+     */
     suggestionsListClass: {
       type: [String, Array, Object],
       required: false,
       default: null,
     },
+    /**
+     * Display operators' descriptions instead of their values (e.g., "is" instead of "=").
+     */
     showFriendlyText: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * HTML attributes to add to the search button
+     */
     searchButtonAttributes: {
       type: Object,
       required: false,
       default: () => ({}),
     },
+    /**
+     * HTML attributes to add to the search input
+     */
     searchInputAttributes: {
       type: Object,
       required: false,
@@ -141,26 +164,22 @@ export default {
           this.tokens.push(createTerm());
         }
 
+        /**
+         * Emitted when the tokens (value) changes
+         * @property {array} tokens
+         */
         this.$emit('input', this.tokens);
       },
       deep: true,
       immediate: true,
     },
-    value: {
-      handler(newValue, oldValue) {
-        if (newValue.length && !isEqual(newValue, oldValue)) {
-          this.applyNewValue(cloneDeep(newValue));
-        }
-      },
-      deep: true,
-      immediate: true,
-    },
   },
   mounted() {
     if (this.value.length) {
       this.applyNewValue(cloneDeep(this.value));
     }
   },
+
   methods: {
     applyNewValue(newValue) {
       this.tokens = needDenormalization(newValue) ? denormalizeTokens(newValue) : newValue;
@@ -269,6 +288,10 @@ export default {
     },
 
     submit() {
+      /**
+       * Emitted when search is submitted
+       * @property {array} tokens
+       */
       this.$emit('submit', normalizeTokens(cloneDeep(this.tokens)));
     },
 
@@ -281,6 +304,19 @@ export default {
 </script>
 
 <template>
+  <!--
+  Emitted when search is cleared
+  @event clear
+  -->
+  <!--
+  Emitted when item from history is selected
+  @event history-item-selected
+  @property {object} value History item
+  -->
+  <!--
+  Emitted when clear history button is clicked
+  @event clear-history
+  -->
   <gl-search-box-by-click
     v-bind="$attrs"
     :value="tokens"
@@ -295,6 +331,7 @@ export default {
     @clear-history="$emit('clear-history')"
   >
     <template #history-item="slotScope">
+      <!-- @slot Slot to customize history item in history dropdown. Used only if using history items -->
       <slot name="history-item" v-bind="slotScope"></slot>
     </template>
     <template #input>

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

@@ -2,10 +2,4 @@ import description from './filtered_search_suggestion.md';
 
 export default {
   description,
-  bootstrapComponent: 'b-dropdown-item',
-  propsInfo: {
-    value: {
-      additionalInfo: 'Value which will be emitted if this suggestion will be selected in list',
-    },
-  },
 };

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

@@ -1,13 +1,7 @@
-# Filtered Search Suggestion
-
-<!-- STORY -->
-
-## Usage
-
 The filtered search suggestion component is a wrapper around `GlDropdownItem`, which registers
 suggestions in a top-level suggestion list:
 
-```js
+```html
 <gl-filtered-search-suggestion-list>
   <gl-filtered-search-suggestion value="foo">Example suggestion</gl-filtered-search-suggestion>
   <gl-filtered-search-suggestion value="bar">Example suggestion 2</gl-filtered-search-suggestion>

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

@@ -1,25 +1,33 @@
-import { withKnobs } from '@storybook/addon-knobs';
 import { GlFilteredSearchSuggestion } from '../../../index';
-import { documentedStoriesOf } from '../../../../documentation/documented_stories';
 import readme from './filtered_search_suggestion.md';
 
 const noop = () => {};
 
-documentedStoriesOf('base/filtered-search/suggestion', readme)
-  .addDecorator(withKnobs)
-  .add('default', () => ({
-    components: { GlFilteredSearchSuggestion },
-    provide: {
-      filteredSearchSuggestionListInstance: {
-        register: noop,
-        unregister: noop,
-        $emit: noop,
-        activeItem: null,
+export const Default = () => ({
+  components: { GlFilteredSearchSuggestion },
+  provide: {
+    filteredSearchSuggestionListInstance: {
+      register: noop,
+      unregister: noop,
+      $emit: noop,
+      activeItem: null,
+    },
+  },
+  template: `
+    <ul>
+      <gl-filtered-search-suggestion value="demo">Demo suggestion</gl-filtered-search-suggestion>
+    </ul>
+  `,
+});
+
+export default {
+  title: 'base/filtered-search/suggestion',
+  component: GlFilteredSearchSuggestion,
+  parameters: {
+    docs: {
+      description: {
+        component: readme,
       },
     },
-    template: `
-      <ul>
-        <gl-filtered-search-suggestion value="demo">Demo suggestion</gl-filtered-search-suggestion>
-      </ul>
-    `,
-  }));
+  },
+};

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

@@ -2,12 +2,16 @@
 import GlDropdownItem from '../dropdown/dropdown_item.vue';
 
 export default {
+  name: 'GlFilteredSearchSuggestion',
   components: {
     GlDropdownItem,
   },
   inject: ['filteredSearchSuggestionListInstance'],
   inheritAttrs: false,
   props: {
+    /**
+     * Value that will be emitted if this suggestion is selected.
+     */
     value: {
       required: true,
       validator: () => true,
@@ -52,6 +56,7 @@ export default {
     href="#"
     @mousedown.native.prevent="emitValue"
   >
+    <!-- @slot The suggestion content. -->
     <slot></slot>
   </gl-dropdown-item>
 </template>

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

@@ -2,9 +2,4 @@ import description from './filtered_search_suggestion_list.md';
 
 export default {
   description,
-  propsInfo: {
-    initialValue: {
-      additionalInfo: 'Value to be initially selected in list',
-    },
-  },
 };

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

@@ -1,9 +1,3 @@
-# Filtered Search Suggestion
-
-<!-- STORY -->
-
-## Usage
-
 The filtered search suggestion list component is responsible for managing underlying suggestion instances.
 You obtain the ref for this component and manage suggestion selection via the component public API:
 
@@ -11,7 +5,7 @@ You obtain the ref for this component and manage suggestion selection via the co
 - `nextItem()` - Selects the next suggestion. If last suggestion was selected, selection is cleared.
 - `prevItem()` - Selects the previous suggestion. If first suggestion was selected, selection is cleared.
 
-```js
+```html
 <gl-filtered-search-suggestion-list ref="suggestions">
   <gl-filtered-search-suggestion value="foo">Example suggestion</gl-filtered-search-suggestion>
   <gl-filtered-search-suggestion value="bar">Example suggestion 2</gl-filtered-search-suggestion>