@gitlab/duo-ui 0.1.0

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

@@ -0,0 +1,372 @@
+<!-- eslint-disable vue/multi-word-component-names -->
+<script>
+/**
+ * Area charts as of %12.10 support annotations.
+ * Annotations is composed of a dotted line and an arrow
+ * at the bottom. The dotted line is constructed
+ * with markLine and arrows with markPoint.
+ *
+ * Similar to how custom tooltips are displayed when area chart
+ * is hovered, a tooltip should be displayed when the annotation
+ * arrow is hovered. This component adds event listeners
+ * to figure out if mouse is hovered on charts to show tooltips.
+ * While that works for data points inside the grid, for arrows
+ * that live right under the chart, we use eCharts inbuilt
+ * event listeners to detect hover. Given this limitation,
+ * we use a separate tooltip for data point and arrow.
+ */
+
+import merge from 'lodash/merge';
+import {
+  defaultChartOptions,
+  grid,
+  getThresholdConfig,
+  generateAnnotationSeries,
+  dataZoomAdjustments,
+  defaultAreaOpacity,
+  mergeSeriesToOptions,
+  mergeAnnotationAxisToOptions,
+  lineStyle,
+} from '../../../utils/charts/config';
+import {
+  LEGEND_LAYOUT_INLINE,
+  LEGEND_LAYOUT_TABLE,
+  LEGEND_AVERAGE_TEXT,
+  LEGEND_CURRENT_TEXT,
+  LEGEND_MIN_TEXT,
+  LEGEND_MAX_TEXT,
+  HEIGHT_AUTO_CLASSES,
+} from '../../../utils/charts/constants';
+import { colorFromDefaultPalette } from '../../../utils/charts/theme';
+import { seriesHasAnnotations, isDataPointAnnotation } from '../../../utils/charts/utils';
+import Chart from '../chart/chart.vue';
+import ChartLegend from '../legend/legend.vue';
+import ChartTooltip from '../tooltip/tooltip.vue';
+
+export default {
+  name: 'GlAreaChart',
+  components: {
+    Chart,
+    ChartLegend,
+    ChartTooltip,
+  },
+  inheritAttrs: false,
+  props: {
+    data: {
+      type: Array,
+      required: true,
+    },
+    option: {
+      type: Object,
+      required: false,
+      default: () => ({}),
+    },
+    thresholds: {
+      type: Array,
+      required: false,
+      default: () => [],
+    },
+    annotations: {
+      type: Array,
+      required: false,
+      default: () => [],
+    },
+    includeLegendAvgMax: {
+      type: Boolean,
+      required: false,
+      default: true,
+    },
+    formatAnnotationsTooltipText: {
+      type: Function,
+      required: false,
+      default: null,
+    },
+    /**
+     * Callback called when showing or refreshing a tooltip.
+     * **Deprecated:** Use slots `#tooltip-title`, `#tooltip-content` or `#tooltip-value`.
+     *
+     * @deprecated Use slots `#tooltip-title`, `#tooltip-content` or `#tooltip-value`.
+     */
+    formatTooltipText: {
+      type: Function,
+      required: false,
+      default: null,
+    },
+    legendAverageText: {
+      type: String,
+      required: false,
+      default: LEGEND_AVERAGE_TEXT,
+    },
+    legendMaxText: {
+      type: String,
+      required: false,
+      default: LEGEND_MAX_TEXT,
+    },
+    legendMinText: {
+      type: String,
+      required: false,
+      default: LEGEND_MIN_TEXT,
+    },
+    legendCurrentText: {
+      type: String,
+      required: false,
+      default: LEGEND_CURRENT_TEXT,
+    },
+    legendLayout: {
+      type: String,
+      required: false,
+      default: LEGEND_LAYOUT_INLINE,
+      validator(layout) {
+        return [LEGEND_LAYOUT_INLINE, LEGEND_LAYOUT_TABLE].indexOf(layout) !== -1;
+      },
+    },
+    /**
+     * Sets the chart's height in pixels. Set to `"auto"` to use the height of the container.
+     */
+    height: {
+      type: [Number, String],
+      required: false,
+      default: null,
+    },
+    legendSeriesInfo: {
+      type: Array,
+      required: false,
+      default: () => [],
+    },
+  },
+  data() {
+    // Part of the tooltip related data can be
+    // moved into the tooltip component.
+    // Tracking that progress in
+    // https://gitlab.com/gitlab-org/gitlab-ui/-/issues/618
+    return {
+      chart: null,
+      showAnnotationsTooltip: false,
+      annotationsTooltipTitle: '',
+      annotationsTooltipContent: '',
+      annotationsTooltipPosition: {
+        left: '0',
+        top: '0',
+      },
+    };
+  },
+  computed: {
+    series() {
+      const dataSeries = this.data.map((series, index) => {
+        const defaultColor = colorFromDefaultPalette(index);
+        const getColor = (type) =>
+          series[type] && series[type].color ? series[type].color : defaultColor;
+        return merge(
+          {
+            areaStyle: {
+              opacity: defaultAreaOpacity,
+              color: getColor('areaStyle'),
+            },
+            showSymbol: false,
+            lineStyle: {
+              color: getColor('lineStyle'),
+            },
+            itemStyle: {
+              color: getColor('itemStyle'),
+            },
+          },
+          lineStyle,
+          series,
+          getThresholdConfig(this.thresholds)
+        );
+      });
+      // if annotation series exists, append it
+      // along with data series
+      if (this.annotationSeries) {
+        return [...dataSeries, this.annotationSeries];
+      }
+      return dataSeries;
+    },
+    annotationSeries() {
+      return generateAnnotationSeries(this.annotations);
+    },
+    options() {
+      const defaultAreaChartOptions = {
+        xAxis: {
+          axisPointer: {
+            show: true,
+            lineStyle: {
+              type: 'solid',
+            },
+            label: {
+              formatter: this.formatTooltipText,
+            },
+          },
+        },
+        yAxis: {
+          axisTick: {
+            show: false,
+          },
+        },
+        legend: {
+          show: false,
+        },
+      };
+      const mergedOptions = merge(
+        {},
+        defaultChartOptions,
+        defaultAreaChartOptions,
+        this.option,
+        dataZoomAdjustments(this.option.dataZoom)
+      );
+      // All chart options can be merged but series
+      // needs to be handled specially.
+      return mergeSeriesToOptions(
+        mergeAnnotationAxisToOptions(mergedOptions, this.hasAnnotations),
+        this.series
+      );
+    },
+    /**
+     * Annotations currently are passed as series options in monitoring dashboard.
+     * Once https://gitlab.com/gitlab-org/gitlab/-/issues/213390 is closed,
+     * annotations will be passed as props and not as series options.
+     *
+     * For backward compatibility, we're having to check for both.
+     */
+    hasAnnotations() {
+      return this.annotations.length !== 0 || seriesHasAnnotations(this.option.series);
+    },
+    shouldShowAnnotationsTooltip() {
+      return this.chart && this.hasAnnotations;
+    },
+    compiledOptions() {
+      return this.chart ? this.chart.getOption() : null;
+    },
+    legendStyle() {
+      return { paddingLeft: `${grid.left}px` };
+    },
+    seriesInfo() {
+      if (this.legendSeriesInfo.length > 0) return this.legendSeriesInfo;
+
+      return this.compiledOptions.series.reduce((acc, series, index) => {
+        if (series.type === 'line') {
+          acc.push({
+            name: series.name,
+            type: series.lineStyle.type,
+            color: series.lineStyle.color || colorFromDefaultPalette(index),
+            data: this.includeLegendAvgMax ? series.data.map((data) => data[1]) : undefined,
+          });
+        }
+        return acc;
+      }, []);
+    },
+    autoHeight() {
+      return this.height === 'auto';
+    },
+  },
+  beforeDestroy() {
+    this.chart.off('mouseout', this.hideAnnotationsTooltip);
+    this.chart.off('mouseover', this.onChartMouseOver);
+  },
+  methods: {
+    defaultAnnotationTooltipText(params) {
+      return {
+        title: params.data.xAxis,
+        content: params.data.tooltipData?.content,
+      };
+    },
+    onCreated(chart) {
+      // eCharts inbuild mouse events
+      // https://echarts.apache.org/en/api.html#events.Mouse%20events
+      // is used to attach listeners to markPoints. These listeners
+      // are currently used for annotation arrows at the bottom of the chart.
+
+      // Because data points and annotations arrows are in different
+      // sections of the charts with their own mouseovers and mouseouts,
+      // there shouldn't be an overlapping situation where both tooltips
+      // are visible.
+      if (this.hasAnnotations) {
+        chart.on('mouseout', this.onChartDataPointMouseOut);
+        chart.on('mouseover', this.onChartDataPointMouseOver);
+      }
+
+      this.chart = chart;
+      this.$emit('created', chart);
+    },
+    onChartDataPointMouseOut() {
+      this.showAnnotationsTooltip = false;
+    },
+    /**
+     * Check if the hovered data point is an annotation
+     * point to show the annotation tooltip.
+     */
+    onChartDataPointMouseOver(params) {
+      if (isDataPointAnnotation(params)) {
+        const { event } = params;
+        const toolTipFormatter =
+          this.formatAnnotationsTooltipText || this.defaultAnnotationTooltipText;
+        const { title = '', content = '' } = toolTipFormatter(params);
+        this.showAnnotationsTooltip = true;
+        this.annotationsTooltipTitle = title;
+        this.annotationsTooltipContent = content;
+        this.annotationsTooltipPosition = {
+          left: `${event.event.zrX}px`,
+          top: `${event.event.zrY}px`,
+        };
+      }
+    },
+  },
+  HEIGHT_AUTO_CLASSES,
+};
+</script>
+
+<template>
+  <div class="position-relative" :class="{ [$options.HEIGHT_AUTO_CLASSES]: autoHeight }">
+    <chart
+      v-bind="$attrs"
+      :class="{ 'gl-grow': autoHeight }"
+      :height="height"
+      :options="options"
+      v-on="$listeners"
+      @created="onCreated"
+    />
+    <chart-tooltip
+      v-if="shouldShowAnnotationsTooltip"
+      id="annotationsTooltip"
+      ref="annotationsTooltip"
+      :show="showAnnotationsTooltip"
+      :top="annotationsTooltipPosition.top"
+      :left="annotationsTooltipPosition.left"
+      :chart="chart"
+      placement="bottom"
+    >
+      <template #title>
+        <div>{{ annotationsTooltipTitle }}</div>
+      </template>
+      <div>{{ annotationsTooltipContent }}</div>
+    </chart-tooltip>
+    <chart-tooltip
+      v-if="chart"
+      ref="dataTooltip"
+      :chart="chart"
+      :use-default-tooltip-formatter="!formatTooltipText"
+    >
+      <template v-if="$scopedSlots['tooltip-title']" #title="scope">
+        <slot name="tooltip-title" v-bind="scope"></slot>
+      </template>
+      <template v-if="$scopedSlots['tooltip-content']" #default="scope">
+        <slot name="tooltip-content" v-bind="scope"></slot>
+      </template>
+      <template v-if="$scopedSlots['tooltip-value']" #tooltip-value="scope">
+        <slot name="tooltip-value" v-bind="scope"></slot>
+      </template>
+    </chart-tooltip>
+    <chart-legend
+      v-if="compiledOptions"
+      :chart="chart"
+      :style="legendStyle"
+      :series-info="seriesInfo"
+      :text-style="compiledOptions.textStyle"
+      :min-text="legendMinText"
+      :max-text="legendMaxText"
+      :average-text="legendAverageText"
+      :current-text="legendCurrentText"
+      :layout="legendLayout"
+    />
+  </div>
+</template>

package/src/components/charts/bar/bar.md

@@ -0,0 +1,3 @@
+A bar chart is similar to a column chart where the the length of bars represents the data value.
+Although alike, they are cannot be interchangeably used. Bar charts are good for displaying large
+number of categories on the y-axis.

package/src/components/charts/bar/bar.vue

@@ -0,0 +1,237 @@
+<!-- eslint-disable vue/multi-word-component-names -->
+<script>
+import merge from 'lodash/merge';
+import truncate from 'lodash/truncate';
+import { grid, dataZoomAdjustments, mergeSeriesToOptions } from '../../../utils/charts/config';
+import { HEIGHT_AUTO_CLASSES } from '../../../utils/charts/constants';
+import { colorFromDefaultPalette } from '../../../utils/charts/theme';
+import { engineeringNotation } from '../../../utils/number_utils';
+import { hexToRgba } from '../../../utils/utils';
+import TooltipDefaultFormat from '../../shared_components/charts/tooltip_default_format.vue';
+import Chart from '../chart/chart.vue';
+import ChartTooltip from '../tooltip/tooltip.vue';
+
+/**
+ * `nameGap` in charts/config is set to 50 but it is not
+ * used for bar charts as the axes are flipped. That is why
+ * we're explicitly setting it here
+ */
+const DEFAULT_NAME_GAP = 50;
+
+/**
+ * This is the magic number at which the y-axis name
+ * and y-axis labels don't overlap
+ * @Number
+ */
+const AXIS_LABEL_LENGTH = 7;
+
+/**
+ * Because the axes are reversed in bar charts defaultChartOptions
+ * xAxis and yAxis needs to be handled specifically.
+ */
+const defaultOptions = {
+  grid,
+  xAxis: {
+    nameLocation: 'center',
+    axisLabel: {
+      formatter: (num) => engineeringNotation(num, 2),
+    },
+  },
+  yAxis: {
+    nameGap: DEFAULT_NAME_GAP,
+    boundaryGap: true,
+    nameLocation: 'center',
+    splitLine: {
+      show: false,
+    },
+    axisLabel: {
+      interval: 0,
+      formatter: (str) =>
+        truncate(str, {
+          length: AXIS_LABEL_LENGTH,
+          separator: '...',
+        }),
+    },
+  },
+};
+
+export default {
+  name: 'GlBarChart',
+  components: {
+    Chart,
+    ChartTooltip,
+    TooltipDefaultFormat,
+  },
+  inheritAttrs: false,
+  props: {
+    data: {
+      type: Object,
+      required: true,
+    },
+    option: {
+      type: Object,
+      required: false,
+      default: () => ({}),
+    },
+    yAxisTitle: {
+      type: String,
+      required: true,
+    },
+    xAxisTitle: {
+      type: String,
+      required: true,
+    },
+    xAxisType: {
+      type: String,
+      required: false,
+      default: 'value',
+    },
+    /**
+     * Sets the chart's height in pixels. Set to `"auto"` to use the height of the container.
+     */
+    height: {
+      type: [Number, String],
+      required: false,
+      default: null,
+    },
+  },
+  data() {
+    return {
+      chart: null,
+      tooltipTitle: '',
+      tooltipContent: {},
+    };
+  },
+  computed: {
+    series() {
+      return Object.keys(this.data).map((key, index) => {
+        const barColor = colorFromDefaultPalette(index);
+
+        return {
+          name: key,
+          data: this.data[key],
+          type: 'bar',
+          stack: 'chart',
+          itemStyle: {
+            color: hexToRgba(barColor, 0.2),
+            borderColor: barColor,
+            borderWidth: 1,
+          },
+          emphasis: {
+            itemStyle: {
+              color: hexToRgba(barColor, 0.4),
+            },
+          },
+          barMaxWidth: '50%',
+        };
+      });
+    },
+    options() {
+      const mergedOptions = merge(
+        {},
+        defaultOptions,
+        {
+          xAxis: {
+            axisLine: {
+              show: false,
+            },
+            name: this.xAxisTitle,
+            type: this.xAxisType,
+          },
+          yAxis: {
+            name: this.yAxisTitle,
+            type: 'category',
+            axisTick: {
+              show: true,
+            },
+            axisPointer: {
+              show: true,
+              type: 'none',
+              label: {
+                formatter: this.onLabelChange,
+              },
+            },
+          },
+          legend: {
+            show: false,
+          },
+        },
+        this.option,
+        dataZoomAdjustments(this.option.dataZoom)
+      );
+      // All chart options can be merged but series
+      // needs to be handled specially
+      return mergeSeriesToOptions(mergedOptions, this.series);
+    },
+    autoHeight() {
+      return this.height === 'auto';
+    },
+  },
+  methods: {
+    onCreated(chart) {
+      this.chart = chart;
+      this.$emit('created', chart);
+    },
+    onLabelChange(params) {
+      const { yLabels, tooltipContent } = this.getTooltipContent(params, this.xAxisTitle);
+
+      this.$set(this, 'tooltipContent', tooltipContent);
+      this.tooltipTitle = yLabels.join(', ');
+    },
+    /**
+     * For bar charts, the tooltip should be against x-axis values.
+     * This method will be removed after https://gitlab.com/gitlab-org/gitlab-ui/-/issues/674
+     *
+     * @param {Object} params series data
+     * @param {String} xAxisTitle x-axis title
+     * @returns {Object} tooltip title and content
+     */
+    getTooltipContent(params, xAxisTitle = null) {
+      const seriesDataLength = params.seriesData.length;
+      const { yLabels, tooltipContent } = params.seriesData.reduce(
+        (acc, chartItem) => {
+          const [value, title] = chartItem.value || [];
+          // The x axis title is used instead of y axis
+          const seriesName =
+            seriesDataLength === 1 && xAxisTitle ? xAxisTitle : chartItem.seriesName;
+          const color = seriesDataLength === 1 ? '' : chartItem.color;
+          acc.tooltipContent[seriesName] = {
+            value,
+            color,
+          };
+          if (!acc.yLabels.includes(title)) {
+            acc.yLabels.push(title);
+          }
+          return acc;
+        },
+        {
+          yLabels: [],
+          tooltipContent: {},
+        }
+      );
+
+      return { yLabels, tooltipContent };
+    },
+  },
+  HEIGHT_AUTO_CLASSES,
+};
+</script>
+
+<template>
+  <div class="position-relative" :class="{ [$options.HEIGHT_AUTO_CLASSES]: autoHeight }">
+    <chart
+      v-bind="$attrs"
+      :class="{ 'gl-grow': autoHeight }"
+      :height="height"
+      :options="options"
+      v-on="$listeners"
+      @created="onCreated"
+    />
+    <chart-tooltip v-if="chart" :chart="chart">
+      <template #title>
+        <div>{{ tooltipTitle }} ({{ yAxisTitle }})</div>
+      </template>
+      <tooltip-default-format :tooltip-content="tooltipContent" />
+    </chart-tooltip>
+  </div>
+</template>

package/src/components/charts/chart/chart.md

@@ -0,0 +1,19 @@
+### ECharts Wrapper
+
+The chart component is a Vue component wrapper around [Apache ECharts](https://echarts.apache.org/en/api.html#echarts).
+The chart component accepts width and height props in order to allow the user to make it responsive.
+
+> Note: When implementing a chart type that does not already have a GitLab UI component, you can use
+> this component alonside the [ECharts options](https://echarts.apache.org/en/api.html#echarts) to
+> build your chart. Each type of chart should still follow the general guidelines in the
+> [pajamas documentation](https://design.gitlab.com/data-visualization/charts).
+
+### EChart Lifecycle
+
+This component emits the following events during the ECharts lifecycle:
+
+- `created`: emitted after calling `echarts.init`
+- `updated`: emitted after calling `echarts.setOption`
+
+In all cases, the event payload is the
+[echart instance](https://echarts.apache.org/en/api.html#echartsInstance).