@gitlab/ui 38.0.1 → 38.2.1

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/filtered_search/filtered_search_utils.js

@@ -39,7 +39,42 @@ export function needDenormalization(tokens) {
 
   assertValidTokens(tokens);
 
-  return tokens.some((t) => typeof t === 'string');
+  return tokens.some((t) => typeof t === 'string' || !t.id);
+}
+
+let tokenIdCounter = 0;
+const getTokenId = () => {
+  const tokenId = `token-${tokenIdCounter}`;
+  tokenIdCounter += 1;
+  return tokenId;
+};
+/**
+ * Ensure the given token has an `id` property, which `GlFilteredSearch` relies
+ * on as a unique key for the token.
+ *
+ * If the given token does not have an `id`, it returns a shallow copy of the
+ * token with an `id`. Otherwise, it returns the given token.
+ *
+ * @param {object} token The token to check.
+ * @returns {object} A token with an `id`.
+ */
+export function ensureTokenId(token) {
+  if (!token.id) {
+    return {
+      ...token,
+      id: getTokenId(),
+    };
+  }
+
+  return token;
+}
+
+export function createTerm(data = '') {
+  return {
+    id: getTokenId(),
+    type: TERM_TOKEN_TYPE,
+    value: { data },
+  };
 }
 
 export function denormalizeTokens(inputTokens) {
@@ -51,11 +86,9 @@ export function denormalizeTokens(inputTokens) {
   tokens.forEach((t) => {
     if (typeof t === 'string') {
       const stringTokens = t.split(' ').filter(Boolean);
-      stringTokens.forEach((strToken) =>
-        result.push({ type: TERM_TOKEN_TYPE, value: { data: strToken } })
-      );
+      stringTokens.forEach((strToken) => result.push(createTerm(strToken)));
     } else {
-      result.push(t);
+      result.push(ensureTokenId(t));
     }
   });
   return result;

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

@@ -4,6 +4,7 @@ import {
   GlFormInput,
   GlFormSelect,
   GlFormCheckbox,
+  GlFormCheckboxGroup,
   GlButton,
 } from '../../../index';
 import { setStoryTimeout } from '../../../utils/test_utils';
@@ -16,6 +17,7 @@ export const Default = (args) => ({
     GlFormInput,
     GlFormSelect,
     GlFormCheckbox,
+    GlFormCheckboxGroup,
     GlButton,
   },
   props: Object.keys(args),

package/src/components/base/form/form_checkbox_tree/form_checkbox_tree.documentation.js

@@ -1,31 +1,5 @@
-import examples from './examples';
 import * as description from './form_checkbox_tree.md';
-import { V_MODEL } from './models/constants';
 
 export default {
   description,
-  examples,
-  propsInfo: {
-    options: {
-      additionalInfo: 'The options tree.',
-    },
-    [V_MODEL.PROP]: {
-      additionalInfo: 'The selected options as an array of values.',
-    },
-    hideToggleAll: {
-      additionalInfo: 'Set to true to hide the "Select/unselect all" checkbox',
-    },
-    selectAllLabel: {
-      additionalInfo: 'Label for the toggle all checkbox when some or all options are unchecked',
-    },
-    unselectAllLabel: {
-      additionalInfo: 'Label for the toggle all checkbox when all options are checked',
-    },
-  },
-  events: [
-    {
-      event: V_MODEL.EVENT,
-      description: 'Emitted the selection changes.',
-    },
-  ],
 };

package/src/components/base/form/form_checkbox_tree/form_checkbox_tree.md

@@ -1,7 +1,3 @@
-# GlFormCheckboxTree
-
-<!-- STORY -->
-
 `GlFormCheckboxTree` lets you display an options structure where any option can have n-level of
 children. It can be useful for creating a search filter that has nested facets.
 

package/src/components/base/form/form_checkbox_tree/form_checkbox_tree.stories.js

@@ -1,5 +1,3 @@
-import { withKnobs, boolean } from '@storybook/addon-knobs';
-import { documentedStoriesOf } from '../../../../../documentation/documented_stories';
 import GlToken from '../../token/token.vue';
 import readme from './form_checkbox_tree.md';
 import GlFormCheckboxTree from './form_checkbox_tree.vue';
@@ -9,95 +7,128 @@ const components = {
   GlToken,
 };
 
-documentedStoriesOf('base/form/form-checkbox-tree', readme)
-  .addDecorator(withKnobs)
-  .add('default', () => ({
-    props: {
-      hideToggleAll: {
-        default: boolean('Hide toggle all checkbox?', false),
+const defaultOptions = [
+  {
+    value: 1,
+    label: 'Felidae',
+    children: [
+      {
+        value: 11,
+        label: 'Lion',
+      },
+      {
+        value: 12,
+        label: 'Felinae',
+        children: [
+          {
+            value: 121,
+            label: 'Cheetah',
+          },
+          {
+            value: 122,
+            label: 'Ocelot',
+          },
+        ],
+      },
+    ],
+  },
+  {
+    value: 2,
+    label: 'Canidae',
+    children: [
+      {
+        value: 21,
+        label: 'Caninae',
+        children: [
+          {
+            value: 211,
+            label: 'Canis lupus',
+            children: [
+              {
+                value: 2112,
+                label: 'Wolf',
+              },
+              {
+                value: 2113,
+                label: 'Himalayan wolf',
+              },
+              {
+                value: 2114,
+                label: 'Dingo',
+              },
+            ],
+          },
+          {
+            value: 212,
+            label: 'Black-backed jackal',
+          },
+        ],
+      },
+      {
+        value: 22,
+        label: 'Fennec fox',
+      },
+    ],
+  },
+  {
+    value: 3,
+    label: 'Karabair',
+  },
+  {
+    value: 4,
+    label: 'Okapi',
+  },
+];
+
+const defaultValue = (prop) => GlFormCheckboxTree.props[prop].default;
+
+const generateProps = ({
+  options = defaultOptions,
+  hideToggleAll = defaultValue('hideToggleAll'),
+  selectAllLabel = defaultValue('selectAllLabel'),
+  unselectAllLabel = defaultValue('unselectAllLabel'),
+  label = defaultValue('label'),
+  labelSrOnly = defaultValue('labelSrOnly'),
+} = {}) => ({
+  options,
+  hideToggleAll,
+  selectAllLabel,
+  unselectAllLabel,
+  label,
+  labelSrOnly,
+});
+
+export const Default = (args, { argTypes }) => ({
+  props: Object.keys(argTypes),
+  data: () => ({
+    checked: [1, 11, 12, 121, 122, 2113, 3],
+  }),
+  components,
+  template: `
+    <div>
+      <gl-form-checkbox-tree
+        v-model="checked"
+        :options="options"
+        :hide-toggle-all="hideToggleAll"
+        :select-all-label="selectAllLabel"
+        :unselect-all-label="unselectAllLabel"
+        :label="label"
+        :label-sr-only="labelSrOnly" />
+      Selected options:
+      <gl-token v-for="value in checked" :key="value" class="gl-mr-1" view-only>{{ value }}</gl-token>
+    </div>
+  `,
+});
+Default.args = generateProps();
+
+export default {
+  title: 'base/form/form-checkbox-tree',
+  component: GlFormCheckboxTree,
+  parameters: {
+    docs: {
+      description: {
+        component: readme,
       },
     },
-    data: () => ({
-      checked: [1, 11, 12, 121, 122, 2113, 3],
-      options: [
-        {
-          value: 1,
-          label: 'Felidae',
-          children: [
-            {
-              value: 11,
-              label: 'Lion',
-            },
-            {
-              value: 12,
-              label: 'Felinae',
-              children: [
-                {
-                  value: 121,
-                  label: 'Cheetah',
-                },
-                {
-                  value: 122,
-                  label: 'Ocelot',
-                },
-              ],
-            },
-          ],
-        },
-        {
-          value: 2,
-          label: 'Canidae',
-          children: [
-            {
-              value: 21,
-              label: 'Caninae',
-              children: [
-                {
-                  value: 211,
-                  label: 'Canis lupus',
-                  children: [
-                    {
-                      value: 2112,
-                      label: 'Wolf',
-                    },
-                    {
-                      value: 2113,
-                      label: 'Himalayan wolf',
-                    },
-                    {
-                      value: 2114,
-                      label: 'Dingo',
-                    },
-                  ],
-                },
-                {
-                  value: 212,
-                  label: 'Black-backed jackal',
-                },
-              ],
-            },
-            {
-              value: 22,
-              label: 'Fennec fox',
-            },
-          ],
-        },
-        {
-          value: 3,
-          label: 'Karabair',
-        },
-        {
-          value: 4,
-          label: 'Okapi',
-        },
-      ],
-    }),
-    components,
-    template: `
-      <div>
-        <gl-form-checkbox-tree :hide-toggle-all="hideToggleAll" :options="options" v-model="checked" />
-        Selected options:
-        <gl-token v-for="value in checked" :key="value" class="gl-mr-1" view-only>{{ value }}</gl-token>
-      </div>
-    `,
-  }));
+  },
+};

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

@@ -34,23 +34,32 @@ export default {
       required: true,
     },
     /**
-     * Selected options
+     * The selected options as an array of values
      */
     value: {
       type: Array,
       required: false,
       default: () => [],
     },
+    /**
+     * Set to true to hide the "Select/unselect all" checkbox
+     */
     hideToggleAll: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * Label for the toggle all checkbox when some or all options are unchecked
+     */
     selectAllLabel: {
       type: String,
       required: false,
       default: 'Select all',
     },
+    /**
+     * Label for the toggle all checkbox when all options are checked
+     */
     unselectAllLabel: {
       type: String,
       required: false,
@@ -80,6 +89,9 @@ export default {
   watch: {
     'tree.selected': {
       handler(selected) {
+        /**
+         * Emitted when the selection changes.
+         */
         this.$emit(V_MODEL.EVENT, selected);
       },
     },