@gitlab/ui 32.41.0 → 32.43.2

package/src/components/base/token_selector/token_selector.vue

@@ -14,6 +14,9 @@ export default {
     event: 'input',
   },
   props: {
+    /**
+     * Items to display in dropdown
+     */
     dropdownItems: {
       type: Array,
       // All items need to have an `id` key
@@ -21,57 +24,89 @@ export default {
       required: false,
       default: () => [],
     },
+    /**
+     * Should users be allowed to add tokens that are not in `dropdown-items`
+     */
     allowUserDefinedTokens: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * Dropdown items are loading, can be used when requesting new dropdown items
+     */
     loading: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * Hide the dropdown if `dropdown-items` is empty. Will show `no-results-content` slot if this is `false`
+     */
     hideDropdownWithNoItems: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * CSS classes to add to the main token selector container (`.gl-token-selector`)
+     */
     containerClass: {
       type: String,
       required: false,
       default: '',
     },
+    /**
+     * CSS classes to add to dropdown menu `ul` element
+     */
     menuClass: {
       type: [String, Array, Object],
       required: false,
       default: '',
     },
+    /**
+     * The autocomplete attribute value for the underlying `input` element
+     */
     autocomplete: {
       type: String,
       required: false,
       default: 'off',
     },
+    /**
+     * The `aria-labelledby` attribute value for the underlying `input` element
+     */
     ariaLabelledby: {
       type: String,
       required: false,
       default: null,
     },
+    /**
+     * The `placeholder` attribute value for the underlying `input` element
+     */
     placeholder: {
       type: String,
       required: false,
       default: null,
     },
+    /**
+     * HTML attributes to add to the text input. Helpful for adding `data-testid` and `data-qa-selector` attributes
+     */
     textInputAttrs: {
       type: Object,
       required: false,
       default: null,
     },
+    /**
+     * Controls the validation state appearance of the component. `true` for valid, `false` for invalid, or `null` for no validation state
+     */
     state: {
       type: Boolean,
       required: false,
       default: null,
     },
-    // Used for custom `v-model`
+    /**
+     * Tokens that are selected. This prop will automatically be added when using `v-model`
+     */
     selectedTokens: {
       type: Array,
       // All tokens need to have an `id` key
@@ -134,6 +169,11 @@ export default {
   watch: {
     inputText(newValue, oldValue) {
       if (newValue !== oldValue) {
+        /**
+         * Fired when user types in the token selector
+         *
+         * @property {string} inputText
+         */
         this.$emit('text-input', newValue);
 
         this.resetFocusedDropdownItem();
@@ -159,6 +199,11 @@ export default {
   },
   methods: {
     handleFocus(event) {
+      /**
+       * Fired when the token selector is focused
+       *
+       * @property {FocusEvent} event
+       */
       this.$emit('focus', event);
 
       this.openDropdown();
@@ -170,6 +215,11 @@ export default {
       }
     },
     handleBlur(event) {
+      /**
+       * Fired when the token selector is blurred
+       *
+       * @property {FocusEvent} event
+       */
       this.$emit('blur', event);
 
       this.inputFocused = false;
@@ -234,18 +284,38 @@ export default {
               name: this.inputText,
             };
 
+      /**
+       * Fired when a token is added or removed
+       *
+       * @property {array} selectedTokens
+       */
       this.$emit('input', [...this.selectedTokens, token]);
 
       this.inputText = '';
       this.closeDropdown();
 
+      /**
+       * Fired when a token is added
+       *
+       * @property {object} token
+       */
       this.$emit('token-add', token);
     },
     removeToken(token) {
+      /**
+       * Fired when user types in the token selector
+       *
+       * @property {string} inputText
+       */
       this.$emit(
         'input',
         this.selectedTokens.filter((selectedToken) => selectedToken.id !== token.id)
       );
+      /**
+       * Fired when a token is removed
+       *
+       * @property {object} token
+       */
       this.$emit('token-remove', token);
     },
     cancelTokenFocus() {
@@ -296,6 +366,10 @@ export default {
         @cancel-focus="cancelTokenFocus"
       >
         <template #token-content="{ token }">
+          <!-- @slot Content to pass to the token component slot. Can be used
+            to add an avatar to the token. Default content is "{{ token.name }}".
+               @binding {object} token
+          -->
           <slot name="token-content" :token="token"></slot>
         </template>
         <template #text-input>
@@ -342,18 +416,32 @@ export default {
       @show="openDropdown"
     >
       <template #loading-content>
+        <!-- @slot Content to display when `loading` prop is `true`. Default
+          content is "Searching..." -->
         <slot name="loading-content"></slot>
       </template>
       <template #user-defined-token-content>
+        <!-- @slot Content to display when adding a user defined token. Default content is 'Add "{{ inputText }}"'.
+             @binding {string} inputText
+        -->
         <slot name="user-defined-token-content" :input-text="inputText"></slot>
       </template>
       <template #no-results-content>
+        <!-- @slot Content to display when `dropdown-items` is empty and
+          `allow-user-defined-tokens` is `false`. Default content is "No matches found". -->
         <slot name="no-results-content"></slot>
       </template>
       <template #dropdown-item-content="{ dropdownItem }">
+        <!-- @slot Dropdown item content. Default content is "{{ dropdownItem.name }}".
+             @binding {object} dropdownItem
+        -->
         <slot name="dropdown-item-content" :dropdown-item="dropdownItem"></slot>
       </template>
       <template #dropdown-footer>
+        <!-- @slot Content to add to the bottom of the dropdown.
+          Can be used in conjunction with `gl-intersection-observer` to load
+          more items as the user scrolls.
+        -->
         <slot name="dropdown-footer"></slot>
       </template>
     </gl-token-selector-dropdown>

package/src/components/base/token_selector/token_selector_dropdown.spec.js

@@ -75,11 +75,6 @@ describe('GlTokenSelectorDropdown', () => {
     }
   });
 
-  afterEach(() => {
-    wrapper.destroy();
-    wrapper = null;
-  });
-
   describe('props', () => {
     describe('show', () => {
       it('displays dropdown when `true`', () => {

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

@@ -1,9 +1,6 @@
-import examples from './examples';
 import description from './tooltip.md';
 
 export default {
   followsDesignSystem: true,
   description,
-  examples,
-  bootstrapComponent: 'b-tooltip',
 };

package/src/components/base/tooltip/tooltip.md

@@ -1,8 +1,6 @@
-## Usage
-
 Using the tooltip component is recommended if you have HTML content.
 It is also currently required if the tooltip content needs to change while it's visible
-(see [this upstream issue]). In all other cases, please use the directive.
+(see [this upstream issue][this upstream issue]). In all other cases, please use the directive.
 
 [this upstream issue]: https://github.com/bootstrap-vue/bootstrap-vue/issues/2142
 
@@ -43,11 +41,11 @@ export default {
 
 ## Directive attributes
 
-`v-gl-tooltip` directive uses the same attributes as [`v-b-tooltip`].
+`v-gl-tooltip` directive uses the same attributes as [`v-b-tooltip`][`v-b-tooltip`].
 
 ## Under the hood
 
-Tooltip uses [`<b-tooltip>`] and [`v-b-tooltip`] internally.
+Tooltip uses [`<b-tooltip>`][`<b-tooltip>`] and [`v-b-tooltip`][`v-b-tooltip`] internally.
 
 [`<b-tooltip>`]: https://bootstrap-vue.org/docs/components/tooltip
 

package/src/components/base/tooltip/tooltip.spec.js

@@ -19,11 +19,6 @@ describe('GlTooltip', () => {
     createWrapper();
   });
 
-  afterEach(() => {
-    wrapper.destroy();
-    wrapper = null;
-  });
-
   it.each(tooltipActionEvents)('passes through the %s event to the bvTooltip instance', (event) => {
     wrapper.vm.$emit(event);
 

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

@@ -1,34 +1,58 @@
-import { withKnobs } from '@storybook/addon-knobs';
-import { documentedStoriesOf } from '../../../../documentation/documented_stories';
-import { GlTooltipDirective } from '../../../../index';
+import { GlTooltip, GlTooltipDirective } from '../../../../index';
 import readme from './tooltip.md';
 
-const directives = {
-  GlTooltip: GlTooltipDirective,
-};
-
 function makeTooltip(modifier = '') {
-  return () => ({
-    directives,
+  return {
+    directives: {
+      GlTooltip: GlTooltipDirective,
+    },
     template: `
-      <div class="d-flex align-items-center justify-content-center p-5 m-5">
-        <gl-button
-          v-gl-tooltip${modifier}
-          title="some tooltip text"
-        >
-            Tooltip
-        </gl-button>
-      </div>
-    `,
+    <div class="gl-display-flex gl-align-items-center gl-justify-content-center gl-p-7 gl-m-7">
+      <gl-button
+        v-gl-tooltip${modifier}
+        title="some tooltip text"
+      >
+          Tooltip
+      </gl-button>
+    </div>
+  `,
     mounted() {
       this.$nextTick(() => this.$el.querySelector('button').focus());
     },
-  });
+  };
 }
 
-documentedStoriesOf('base/tooltip', readme)
-  .addDecorator(withKnobs)
-  .add('top (default)', makeTooltip())
-  .add('right', makeTooltip('.right'))
-  .add('bottom', makeTooltip('.bottom'))
-  .add('left', makeTooltip('.left'));
+export const TopDefault = (args, argTypes) => ({
+  ...makeTooltip(),
+  props: Object.keys(argTypes),
+});
+
+export const Right = (args, argTypes) => ({
+  ...makeTooltip('.right'),
+  props: Object.keys(argTypes),
+});
+
+export const Bottom = (args, argTypes) => ({
+  ...makeTooltip('.bottom'),
+  props: Object.keys(argTypes),
+});
+
+export const Left = (args, argTypes) => ({
+  ...makeTooltip('.left'),
+  props: Object.keys(argTypes),
+});
+
+// A default export contains higher-level info about the component and the stories' settings.
+export default {
+  title: 'base/tooltip',
+  component: GlTooltip,
+  parameters: {
+    bootstrapComponent: 'b-tooltip',
+    knobs: { disable: true },
+    docs: {
+      description: {
+        component: readme,
+      },
+    },
+  },
+};

package/src/components/base/tooltip/tooltip.vue

@@ -23,6 +23,7 @@ export default {
     :delay="$options.tooltipDelay"
     v-on="$listeners"
   >
+    <!-- @slot Tooltip content -->
     <slot></slot>
   </b-tooltip>
 </template>

package/src/components/charts/area/area.spec.js

@@ -5,6 +5,7 @@ import ChartLegend from '../legend/legend.vue';
 import AreaChart from './area.vue';
 
 import { LEGEND_LAYOUT_INLINE, LEGEND_LAYOUT_TABLE } from '~/utils/charts/constants';
+import { createMockChartInstance, ChartTooltipStub } from '~helpers/chart_stubs';
 
 let mockChartInstance;
 
@@ -14,7 +15,6 @@ jest.mock('echarts', () => ({
 
 describe('area component', () => {
   let wrapper;
-  let option;
 
   const findChart = () => wrapper.findComponent(Chart);
   const findLegend = () => wrapper.findComponent(ChartLegend);
@@ -24,33 +24,17 @@ describe('area component', () => {
   const emitChartCreated = () => findChart().vm.$emit('created', mockChartInstance);
 
   const createShallowWrapper = (props = {}) => {
-    wrapper = shallowMount(AreaChart, { propsData: { option, data: [], ...props } });
+    wrapper = shallowMount(AreaChart, {
+      propsData: { option: { series: [] }, data: [], ...props },
+      stubs: {
+        'chart-tooltip': ChartTooltipStub,
+      },
+    });
     emitChartCreated();
   };
 
   beforeEach(() => {
-    option = {
-      series: [],
-    };
-
-    mockChartInstance = {
-      getDom: () => {
-        return {
-          addEventListener: jest.fn(),
-          removeEventListener: jest.fn(),
-        };
-      },
-      on: jest.fn(),
-      off: jest.fn(),
-      convertToPixel: jest.fn(),
-      getOption: () => {
-        return option;
-      },
-    };
-  });
-
-  afterEach(() => {
-    wrapper.destroy();
+    mockChartInstance = createMockChartInstance();
   });
 
   it('emits `created`, with the chart instance', async () => {

package/src/components/charts/area/area.vue

@@ -345,8 +345,9 @@ export default {
       :left="annotationsTooltipPosition.left"
       placement="bottom"
     >
-      <!-- eslint-disable-next-line vue/no-deprecated-slot-attribute -->
-      <div slot="title">{{ annotationsTooltipTitle }}</div>
+      <template #title>
+        <div>{{ annotationsTooltipTitle }}</div>
+      </template>
       <div>{{ annotationsTooltipContent }}</div>
     </chart-tooltip>
     <chart-tooltip
@@ -359,19 +360,15 @@ export default {
       :top="dataTooltipPosition.top"
       :left="dataTooltipPosition.left"
     >
-      <template v-if="formatTooltipText">
-        <!-- eslint-disable-next-line vue/no-deprecated-slot-attribute -->
-        <slot slot="title" name="tooltip-title"></slot>
-        <slot name="tooltip-content"></slot>
-      </template>
-      <template v-else>
-        <!-- eslint-disable-next-line vue/no-deprecated-slot-attribute -->
-        <div slot="title">
+      <template #title>
+        <slot v-if="formatTooltipText" name="tooltip-title"></slot>
+        <template v-else>
           {{ dataTooltipTitle }}
           <template v-if="options.xAxis.name">({{ options.xAxis.name }})</template>
-        </div>
-        <tooltip-default-format :tooltip-content="dataTooltipContent" />
+        </template>
       </template>
+      <slot v-if="formatTooltipText" name="tooltip-content"></slot>
+      <tooltip-default-format v-else :tooltip-content="dataTooltipContent" />
     </chart-tooltip>
     <chart-legend
       v-if="compiledOptions"

package/src/components/charts/bar/bar.spec.js

@@ -2,16 +2,9 @@ import { shallowMount } from '@vue/test-utils';
 import Chart from '../chart/chart.vue';
 import BarChart from './bar.vue';
 import TooltipDefaultFormat from '~/components/shared_components/charts/tooltip_default_format.vue';
+import { createMockChartInstance } from '~helpers/chart_stubs';
 
-const mockChartInstance = {
-  getDom: () => {
-    return {
-      addEventListener: jest.fn(),
-      removeEventListener: jest.fn(),
-    };
-  },
-  convertToPixel: jest.fn(),
-};
+let mockChartInstance;
 
 jest.mock('echarts', () => ({
   getInstanceByDom: () => mockChartInstance,
@@ -45,8 +38,8 @@ describe('Bar chart component', () => {
     });
   };
 
-  afterEach(() => {
-    wrapper.destroy();
+  beforeEach(() => {
+    mockChartInstance = createMockChartInstance();
   });
 
   describe('when mounted', () => {

package/src/components/charts/chart/chart.spec.js

@@ -25,10 +25,6 @@ describe('chart component', () => {
     wrapper = shallowMount(...mountArgs);
   });
 
-  afterEach(() => {
-    wrapper.destroy();
-  });
-
   it('initializes chart using $refs.chart', () => {
     expect(echarts.init).toHaveBeenCalledWith(
       wrapper.findComponent({ ref: 'chart' }).element,

package/src/components/charts/column/column_chart.spec.js

@@ -52,10 +52,6 @@ describe('column chart component', () => {
     factory();
   });
 
-  afterEach(() => {
-    wrapper.destroy();
-  });
-
   it('emits "created" when onCreated is called', () => {
     wrapper.vm.onCreated(wrapper.vm.chart);
 

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

@@ -13,6 +13,7 @@ const template = `
     :option="option"
     :y-axis-title="yAxisTitle"
     :x-axis-title="xAxisTitle"
+    data-testid="discrete-scatter-chart"
   />
 `;
 

package/src/components/charts/discrete_scatter/discrete_scatter.vue

@@ -174,16 +174,13 @@ export default {
       :top="tooltipPosition.top"
       :left="tooltipPosition.left"
     >
-      <template v-if="formatTooltipText">
-        <!-- eslint-disable-next-line vue/no-deprecated-slot-attribute -->
-        <slot slot="title" name="tooltip-title"></slot>
-        <slot name="tooltip-content"></slot>
+      <template #title>
+        <slot name="tooltip-title">{{ tooltipTitle }} ({{ xAxisTitle }})</slot>
       </template>
-      <template v-else>
-        <!-- eslint-disable-next-line vue/no-deprecated-slot-attribute -->
-        <div slot="title">{{ tooltipTitle }} ({{ xAxisTitle }})</div>
+
+      <slot name="tooltip-content">
         <tooltip-default-format :tooltip-content="tooltipContent" />
-      </template>
+      </slot>
     </chart-tooltip>
   </div>
 </template>

package/src/components/charts/gauge/gauge.spec.js

@@ -1,8 +1,8 @@
 import { shallowMount } from '@vue/test-utils';
-
 import { gaugeSafeHues, gaugeWarningHue } from '../../../utils/charts/theme';
 import Chart from '../chart/chart.vue';
 import GlGauge from './gauge.vue';
+import { createMockChartInstance } from '~helpers/chart_stubs';
 
 const placeholder = '--';
 
@@ -20,7 +20,6 @@ jest.mock('echarts', () => ({
 
 describe('gauge component', () => {
   let wrapper;
-  let options;
 
   const findChart = () => wrapper.findComponent(Chart);
   const findChartOptions = () => findChart().props('options');
@@ -38,28 +37,7 @@ describe('gauge component', () => {
   };
 
   beforeEach(() => {
-    options = {
-      series: [],
-    };
-
-    mockChartInstance = {
-      getDom: () => {
-        return {
-          addEventListener: jest.fn(),
-          removeEventListener: jest.fn(),
-        };
-      },
-      on: jest.fn(),
-      off: jest.fn(),
-      convertToPixel: jest.fn(),
-      getOption: () => {
-        return options;
-      },
-    };
-  });
-
-  afterEach(() => {
-    wrapper.destroy();
+    mockChartInstance = createMockChartInstance();
   });
 
   it('emits `created`, with the chart instance', () => {

package/src/components/charts/heatmap/heatmap.spec.js

@@ -4,6 +4,7 @@ import Chart from '../chart/chart.vue';
 import ChartTooltip from '../tooltip/tooltip.vue';
 import HeatMapChart from './heatmap.vue';
 import { TOOLTIP_LEFT_OFFSET } from '~/utils/charts/constants';
+import { createMockChartInstance } from '~helpers/chart_stubs';
 
 let mockChartInstance;
 
@@ -13,7 +14,6 @@ jest.mock('echarts', () => ({
 
 describe('heatmap component', () => {
   let wrapper;
-  let options;
 
   const findChart = () => wrapper.findComponent(Chart);
   const findChartTooltip = () => wrapper.findComponent(ChartTooltip);
@@ -22,33 +22,16 @@ describe('heatmap component', () => {
   const emitChartCreated = () => findChart().vm.$emit('created', mockChartInstance);
 
   beforeEach(() => {
-    options = {
-      series: [],
-    };
-
-    mockChartInstance = {
-      getDom: () => {
-        return {
-          addEventListener: jest.fn(),
-          removeEventListener: jest.fn(),
-        };
-      },
-      convertToPixel: jest.fn(),
-      getOption: () => {
-        return options;
-      },
-    };
-
-    wrapper = shallowMount(HeatMapChart, { propsData: { options, dataSeries: [] } });
+    mockChartInstance = createMockChartInstance();
+
+    wrapper = shallowMount(HeatMapChart, {
+      propsData: { options: { series: [] }, dataSeries: [] },
+    });
     emitChartCreated();
 
     return wrapper.vm.$nextTick();
   });
 
-  afterEach(() => {
-    wrapper.destroy();
-  });
-
   it('emits `created`, with the chart instance', () => {
     expect(wrapper.emitted('created').length).toBe(1);
     expect(wrapper.emitted('created')[0][0]).toBe(mockChartInstance);