@gitlab/duo-ui 0.1.0

package/src/components/charts/legend/legend.vue

@@ -0,0 +1,284 @@
+<!-- eslint-disable vue/multi-word-component-names -->
+<script>
+import * as echarts from 'echarts';
+import { GRAY_200 } from '../../../tokens/build/js/tokens';
+import { defaultFontSize } from '../../../utils/charts/config';
+import {
+  LEGEND_LAYOUT_INLINE,
+  LEGEND_LAYOUT_TABLE,
+  LEGEND_AVERAGE_TEXT,
+  LEGEND_CURRENT_TEXT,
+  LEGEND_MIN_TEXT,
+  LEGEND_MAX_TEXT,
+} from '../../../utils/charts/constants';
+import { average, engineeringNotation } from '../../../utils/number_utils';
+import GlTruncate from '../../utilities/truncate/truncate.vue';
+import GlChartSeriesLabel from '../series_label/series_label.vue';
+
+export default {
+  name: 'GlChartLegend',
+  components: {
+    GlChartSeriesLabel,
+    GlTruncate,
+  },
+  props: {
+    chart: {
+      type: Object,
+      required: true,
+      validator(chart) {
+        return Object.is(chart, echarts.getInstanceByDom(chart.getDom()));
+      },
+    },
+    seriesInfo: {
+      type: Array,
+      required: true,
+      validator(seriesInfo) {
+        return seriesInfo.every((series) => series.type && series.name && series.color);
+      },
+    },
+    textStyle: {
+      type: Object,
+      required: false,
+      default: () => ({}),
+    },
+    /**
+     * Text for data average (overridden by prop if needed for internationalization)
+     */
+    averageText: {
+      type: String,
+      required: false,
+      default: LEGEND_AVERAGE_TEXT,
+    },
+    currentText: {
+      type: String,
+      required: false,
+      default: LEGEND_CURRENT_TEXT,
+    },
+    minText: {
+      type: String,
+      required: false,
+      default: LEGEND_MIN_TEXT,
+    },
+    /**
+     * Text for max amount (overridden by prop if needed for internationalization)
+     */
+    maxText: {
+      type: String,
+      required: false,
+      default: LEGEND_MAX_TEXT,
+    },
+    /**
+     * Sets the display layout
+     */
+    layout: {
+      type: String,
+      required: false,
+      default: LEGEND_LAYOUT_INLINE,
+      validator(layout) {
+        return [LEGEND_LAYOUT_INLINE, LEGEND_LAYOUT_TABLE].indexOf(layout) !== -1;
+      },
+    },
+  },
+  data() {
+    return {
+      disabledSeries: {},
+      lastActiveSeriesLabel: null,
+      shouldApplyFadeClass: false,
+    };
+  },
+  computed: {
+    fontStyle() {
+      return {
+        fontFamily: this.textStyle.fontFamily || 'sans-serif',
+        fontSize: `${this.textStyle.fontSize || defaultFontSize}px`,
+      };
+    },
+    hasOneSeriesElement() {
+      return this.seriesInfo.length === 1;
+    },
+  },
+  created() {
+    this.chart.on('legendselectchanged', this.suppressLastActiveSeriesLabelToggle);
+  },
+  mounted() {
+    this.applyFadeClass();
+  },
+  async updated() {
+    await this.$nextTick();
+    this.applyFadeClass();
+  },
+  beforeDestroy() {
+    this.chart.off('legendselectchanged', this.suppressLastActiveSeriesLabelToggle);
+  },
+  methods: {
+    sanitizeSeriesData(seriesData) {
+      return seriesData?.filter((d) => !Number.isNaN(d)) ?? [];
+    },
+    seriesAverage(seriesData) {
+      const sanitized = this.sanitizeSeriesData(seriesData);
+      return engineeringNotation(average(...sanitized));
+    },
+    seriesMax(seriesData) {
+      const sanitized = this.sanitizeSeriesData(seriesData);
+      return engineeringNotation(Math.max(...sanitized));
+    },
+    seriesMin(seriesData) {
+      const sanitized = this.sanitizeSeriesData(seriesData);
+      return engineeringNotation(Math.min(...sanitized));
+    },
+    seriesLast(seriesData) {
+      const sanitized = this.sanitizeSeriesData(seriesData);
+      return engineeringNotation(sanitized[sanitized.length - 1]);
+    },
+    seriesNameIsLong(seriesName) {
+      return seriesName.length > 120;
+    },
+    handleClick({ name, disabled }, key) {
+      if (this.hasOneSeriesElement || this.isToggleDisabled(name, disabled)) return;
+
+      this.chart.dispatchAction({ type: 'legendToggleSelect', name });
+      this.disabledSeries = { ...this.disabledSeries, [key]: !this.disabledSeries[key] };
+    },
+    handleMouseEnter(name) {
+      this.chart.dispatchAction({ type: 'highlight', seriesName: name });
+    },
+    handleMouseLeave(name) {
+      this.chart.dispatchAction({ type: 'downplay', seriesName: name });
+    },
+    getColor(color, key) {
+      return this.disabledSeries[key] ? GRAY_200 : color;
+    },
+    suppressLastActiveSeriesLabelToggle({ selected }) {
+      const selectedSeriesLabels = Object.entries(selected).filter(([, isSelected]) =>
+        Boolean(isSelected)
+      );
+
+      this.lastActiveSeriesLabel = null;
+
+      if (selectedSeriesLabels.length === 1) {
+        const [lastActiveSeriesLabelName] = selectedSeriesLabels[0];
+
+        this.lastActiveSeriesLabel = lastActiveSeriesLabelName;
+      }
+    },
+    /**
+     * Disables toggling legend if it is the last active one or if its data series
+     * has a disabled property set to true
+     * @param {String} name Series name
+     * @param {Boolean} isDisabled Value of the series element's disabled property
+     * @returns {boolean}
+     */
+    isToggleDisabled(name, isDisabled) {
+      return name === this.lastActiveSeriesLabel || isDisabled;
+    },
+    applyFadeClass() {
+      if (this.$refs.inlineLegendEl) {
+        const { scrollHeight, clientHeight } = this.$refs.inlineLegendEl;
+        this.shouldApplyFadeClass = scrollHeight > clientHeight;
+      }
+    },
+  },
+  legendLayoutTypes: {
+    LEGEND_LAYOUT_INLINE,
+    LEGEND_LAYOUT_TABLE,
+  },
+};
+</script>
+
+<template>
+  <div class="gl-legend" data-testid="gl-chart-legend">
+    <template v-if="layout === $options.legendLayoutTypes.LEGEND_LAYOUT_INLINE">
+      <div
+        ref="inlineLegendEl"
+        class="gl-legend-inline"
+        :class="{ 'gl-legend-b-fade': shouldApplyFadeClass }"
+      >
+        <div
+          v-for="(series, key) in seriesInfo"
+          :key="key"
+          :class="{
+            'text-muted': disabledSeries[key],
+            'w-100': seriesNameIsLong(series.name),
+            'hover:!gl-cursor-not-allowed':
+              hasOneSeriesElement || isToggleDisabled(series.name, series.disabled),
+          }"
+          class="gl-legend-inline-series"
+          :style="fontStyle"
+          :aria-disabled="hasOneSeriesElement || isToggleDisabled(series.name, series.disabled)"
+          role="button"
+          @click="handleClick(series, key)"
+          @mouseenter="handleMouseEnter(series.name)"
+          @mouseleave="handleMouseLeave(series.name)"
+        >
+          <gl-chart-series-label
+            :color="getColor(series.color, key)"
+            :type="series.type"
+            class="gl-legend-inline-series-label"
+            :class="{ 'w-75': seriesNameIsLong(series.name) }"
+          >
+            <gl-truncate class="gl-font-bold" :text="series.name" />
+          </gl-chart-series-label>
+          <span
+            v-if="series.data && series.data.length"
+            :class="{ 'gl-whitespace-nowrap': seriesNameIsLong(series.name) }"
+          >
+            {{ averageText }}: {{ seriesAverage(series.data) }} · {{ maxText }}:
+            {{ seriesMax(series.data) }}
+          </span>
+        </div>
+      </div>
+    </template>
+
+    <template v-if="layout === $options.legendLayoutTypes.LEGEND_LAYOUT_TABLE">
+      <div class="gl-legend-tabular gl-legend-b-fade" :style="fontStyle">
+        <header class="gl-legend-tabular-header">
+          <div class="gl-legend-tabular-header-cell">{{ minText }}</div>
+          <div class="gl-legend-tabular-header-cell">{{ maxText }}</div>
+          <div class="gl-legend-tabular-header-cell">{{ averageText }}</div>
+          <div class="gl-legend-tabular-header-cell">{{ currentText }}</div>
+        </header>
+        <section class="gl-legend-tabular-body">
+          <div
+            v-for="(series, key) in seriesInfo"
+            :key="key"
+            :class="{
+              'text-muted': disabledSeries[key],
+              'hover:!gl-cursor-not-allowed':
+                hasOneSeriesElement || isToggleDisabled(series.name, series.disabled),
+            }"
+            class="gl-legend-tabular-row"
+            :style="fontStyle"
+            :aria-disabled="isToggleDisabled(series.name, series.disabled)"
+            role="button"
+            @click="handleClick(series, key)"
+            @mouseenter="handleMouseEnter(series.name)"
+            @mouseleave="handleMouseLeave(series.name)"
+          >
+            <div class="gl-legend-tabular-title-cell">
+              <gl-chart-series-label
+                :color="getColor(series.color, key)"
+                :style="fontStyle"
+                :type="series.type"
+              >
+                <gl-truncate class="gl-font-bold" :text="series.name" />
+              </gl-chart-series-label>
+            </div>
+
+            <template v-if="sanitizeSeriesData(series.data).length">
+              <div class="gl-legend-tabular-details-cell">{{ seriesMin(series.data) }}</div>
+              <div class="gl-legend-tabular-details-cell">{{ seriesMax(series.data) }}</div>
+              <div class="gl-legend-tabular-details-cell">{{ seriesAverage(series.data) }}</div>
+              <div class="gl-legend-tabular-details-cell">{{ seriesLast(series.data) }}</div>
+            </template>
+            <template v-else>
+              <div class="gl-legend-tabular-details-cell">-</div>
+              <div class="gl-legend-tabular-details-cell">-</div>
+              <div class="gl-legend-tabular-details-cell">-</div>
+              <div class="gl-legend-tabular-details-cell">-</div>
+            </template>
+          </div>
+        </section>
+      </div>
+    </template>
+  </div>
+</template>

package/src/components/charts/line/line.md

@@ -0,0 +1,7 @@
+This is a basic line chart.
+
+### Implementation Details
+
+This component wraps the GitLab UI `chart` component, which in turn wraps the ECharts component.
+
+See the [chart](./?path=/story/charts-chart--default) component for more info.

package/src/components/charts/line/line.vue

@@ -0,0 +1,368 @@
+<!-- eslint-disable vue/multi-word-component-names -->
+<script>
+/**
+ * Line 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. Most of this
+ * logic is in GitLab and should be eventually moved to
+ * GitLab UI https://gitlab.com/gitlab-org/gitlab/-/issues/213390.
+ *
+ * Similar to how custom tooltips are displayed when line 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 { GRAY_200 } from '../../../tokens/build/js/tokens';
+import {
+  defaultChartOptions,
+  grid,
+  getThresholdConfig,
+  generateAnnotationSeries,
+  dataZoomAdjustments,
+  symbolSize,
+  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: 'GlLineChart',
+  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,
+    },
+    /**
+     * 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;
+      },
+    },
+    showLegend: {
+      type: Boolean,
+      required: false,
+      default: true,
+    },
+    /**
+     * 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() {
+    // 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]?.color ?? defaultColor;
+
+        return merge(
+          {
+            showSymbol: true,
+            lineStyle: {
+              color: getColor('lineStyle'),
+            },
+            itemStyle: {
+              color: getColor('itemStyle'),
+            },
+          },
+          symbolSize,
+          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 defaultLineChartOptions = {
+        xAxis: {
+          axisPointer: {
+            show: true,
+            label: {
+              formatter: this.formatTooltipText,
+            },
+          },
+          axisTick: {
+            alignWithLabel: true,
+            show: true,
+            lineStyle: {
+              color: GRAY_200,
+            },
+          },
+        },
+        legend: {
+          show: false,
+        },
+      };
+      const mergedOptions = merge(
+        {},
+        defaultChartOptions,
+        defaultLineChartOptions,
+        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` };
+    },
+    hasLegend() {
+      return this.compiledOptions && this.showLegend;
+    },
+    seriesInfo() {
+      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.onChartDataPointMouseOut);
+    this.chart.off('mouseover', this.onChartDataPointMouseOver);
+  },
+  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"
+      :chart="chart"
+      :top="annotationsTooltipPosition.top"
+      :left="annotationsTooltipPosition.left"
+      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="hasLegend"
+      :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/series_label/series_label.md

@@ -0,0 +1 @@
+Displays chart data series name as a label for chart legend, tooltip, etc.

package/src/components/charts/series_label/series_label.scss

@@ -0,0 +1,23 @@
+.gl-series-label-container {
+  @apply gl-flex;
+  @apply gl-text-base;
+  @apply gl-overflow-hidden;
+  @apply gl-break-words;
+}
+
+.gl-series-label-color {
+  @apply gl-shrink-0;
+  @apply gl-mr-3;
+
+  svg {
+    @apply gl-block;
+  }
+}
+
+.gl-series-label-text {
+  // In case there are no spaces in the series label -
+  // as there are quite a few possible cases where
+  // Prometheus queries return long labels with no spaces.
+  @apply gl-overflow-hidden;
+  @apply gl-break-words;
+}