@gitlab/duo-ui 0.1.0

package/src/utils/charts/config.js

@@ -0,0 +1,514 @@
+import castArray from 'lodash/castArray';
+import merge from 'lodash/merge';
+import { BLUE_500 } from '../../tokens/build/js/tokens';
+import { GlBreakpointInstance } from '../breakpoints';
+import { columnOptions } from '../constants';
+import { areDatesEqual } from '../datetime_utility';
+import { engineeringNotation } from '../number_utils';
+import { hexToRgba } from '../utils';
+import { ANNOTATIONS_SERIES_NAME, arrowSymbol, CHART_TYPE_BAR, CHART_TYPE_LINE } from './constants';
+
+export const defaultAreaOpacity = 0.2;
+export const defaultFontSize = 12;
+export const defaultHeight = 400;
+export const defaultWidth = 300;
+export const validRenderers = ['canvas', 'svg'];
+export const toolboxHeight = 14;
+
+export const axes = {
+  name: 'Value',
+  type: 'value',
+  nameLocation: 'center',
+};
+
+export const xAxis = merge({}, axes, {
+  boundaryGap: false,
+  splitLine: {
+    show: false,
+  },
+});
+
+export const yAxis = merge({}, axes, {
+  nameGap: 50,
+  axisLabel: {
+    formatter: (num) => engineeringNotation(num, 2),
+  },
+});
+
+export const grid = {
+  top: 16,
+  bottom: 44,
+  left: 64,
+  right: 32,
+};
+
+export const defaultChartOptions = {
+  grid,
+  xAxis,
+  yAxis,
+};
+
+export const gridWithSecondaryYAxis = {
+  ...grid,
+  right: 64,
+};
+
+export const lineStyle = {
+  symbol: 'circle',
+  type: 'line',
+  width: 2,
+};
+
+/**
+ * Annotations series consists of annotations lines
+ * along with markers. Annotations co-exist with data
+ * series but have their own virtual coords so that they stay put
+ * irrespective of data series extents.
+ */
+export const annotationsYAxisCoords = {
+  min: 0,
+  pos: 3, // 3% height of chart's grid
+  max: 100,
+  show: false,
+};
+
+export const symbolSize = 6;
+
+/**
+ * These comparison operators are currently in monitoring
+ * charts that have alerting related data.
+ *
+ * {Array} Possible values for greater than
+ */
+const GREATER_THAN = ['>', '>'];
+
+/**
+ * These comparison operators are currently in monitoring
+ * charts that have alerting related data.
+ *
+ * {Array} Possible values for less than
+ */
+const LESS_THAN = ['<', '&lt;'];
+
+/**
+ * All default dataZoom configs will have slider & inside
+ * (for reference, see https://gitlab.com/gitlab-org/gitlab-ui/issues/240)
+ * Inside is disabled for larger viewports (lg and xl)
+ * and is specifically to enable touch zoom for mobile devices
+ * @param {Object} options
+ */
+export const getDataZoomConfig = ({ filterMode = 'none' } = {}) => {
+  const disabledBreakpoints = ['lg', 'xl'];
+  const disabled = disabledBreakpoints.includes(GlBreakpointInstance.getBreakpointSize());
+  const minSpan = filterMode === 'none' ? 0.01 : null;
+
+  return {
+    grid: {
+      bottom: 81,
+    },
+    xAxis: {
+      nameGap: 67,
+    },
+    dataZoom: [
+      {
+        type: 'slider',
+        bottom: 22,
+        filterMode,
+        minSpan,
+      },
+      {
+        type: 'inside',
+        filterMode,
+        minSpan,
+        disabled,
+      },
+    ],
+  };
+};
+
+// All chart options can be merged but series
+// needs to be concatenated.
+// Series can be an object for single series or
+// an array of objects.
+export const mergeSeriesToOptions = (options, series = []) => {
+  const { series: optSeries = [] } = options;
+  return {
+    ...options,
+    series: [...castArray(series), ...castArray(optSeries)],
+  };
+};
+
+/**
+ * If an annotation series exists, the chart options should have an
+ * array of yAxis settings so that the series can exist in its own
+ * coordinate system without interfering with the data series
+ *
+ * @param {Object} options options to merge annotation series yAxis with
+ * @param {Boolean} hasAnnotations if annotation series yAxis should be merged
+ * @returns {Object} options
+ */
+export const mergeAnnotationAxisToOptions = (options, hasAnnotations = false) => ({
+  ...options,
+  ...(hasAnnotations && { yAxis: [options.yAxis, annotationsYAxisCoords] }),
+});
+
+export const dataZoomAdjustments = (dataZoom) => {
+  // handle cases where dataZoom is array and object.
+  const useSlider = dataZoom && Array.isArray(dataZoom) ? dataZoom.length : Boolean(dataZoom);
+
+  return useSlider ? getDataZoomConfig({ filterMode: 'weakFilter' }) : [];
+};
+
+/**
+ * Generate eCharts markArea arrays for thresholds and annotations.
+ *
+ * This method purposefully has no knowledge of comparison
+ * operators used in thresholds as it is not necessary and instead
+ * expects explict value bounds
+ *
+ * Examples:
+ * { min: 7, max: 10 } => markArea from 7 to 10
+ * { min: 1, max: 7 } => markArea from 1 to 7
+ *
+ * If min and max are equal it would be markLine and would be
+ * generated by `generateMarkLines`
+ *
+ * @param {Object} threshold Threshold/Annotation object with min and max values
+ * @param {String} axis markArea is generated against this axis
+ * @returns {Array}
+ */
+const generateMarkArea = ({ min, max }, axis = 'yAxis') => [{ [axis]: min }, { [axis]: max }];
+
+/**
+ * Generate eCharts markLine objects for thresholds and annotations.
+ *
+ * This method purposefully has no knowledge of comparison
+ * operators used in thresholds as it is not necessary and instead
+ * expects explict value bounds
+ *
+ * In order to continue supporting existing thresholds format, min
+ * is passed as undefined so the correct markLine object is generated.
+ *
+ * For annotations, min and max will be the same value.
+ *
+ * Threshold Examples:
+ * { max: 7 } => markLine at 7
+ *
+ * Annotation Examples:
+ * { min: 7, max: 7 } => markLine at 7
+ *
+ * @param {Object} threshold Threshold/Annotation object with min and max values
+ * @param {String} axis markLine is generated against this axis
+ * @returns {Object}
+ */
+const generateMarkLines = ({ min, max }, axis = 'yAxis') => {
+  if (min) {
+    return { [axis]: min };
+  }
+  return { [axis]: max };
+};
+
+/**
+ * Generates markPoints that are placed under the markLines.
+ *
+ * These are used only in annotation lines. For annotation lines,
+ * both min and max are same values so only one is enough to generate
+ * the markPoint.
+ *
+ * @param {Object} annotation object
+ * @return {Object}
+ */
+const generateMarkPoints = ({ min, tooltipData }) => {
+  return {
+    name: 'annotations',
+    xAxis: min,
+    yAxis: 0,
+    tooltipData,
+  };
+};
+
+/**
+ * Generate set of markAreas and markLines to draw on charts
+ * as alert thresholds.
+ *
+ * Alert thresholds always have a markLine associated with a markArea
+ *
+ * @param {Array} thresholds Array of alert thresholds
+ * @returns {Object} markAreas and markLines
+ */
+export function getThresholdConfig(thresholds) {
+  if (!thresholds.length) {
+    return {};
+  }
+
+  const data = thresholds.reduce(
+    (acc, alert) => {
+      const { threshold, operator } = alert;
+
+      if (GREATER_THAN.includes(operator)) {
+        acc.areas.push(
+          generateMarkArea({
+            min: threshold,
+            max: Infinity,
+          })
+        );
+      } else if (LESS_THAN.includes(operator)) {
+        acc.areas.push(
+          generateMarkArea({
+            min: Number.NEGATIVE_INFINITY,
+            max: threshold,
+          })
+        );
+      }
+
+      acc.lines.push(
+        generateMarkLines({
+          max: threshold,
+        })
+      );
+
+      return acc;
+    },
+    { lines: [], areas: [] }
+  );
+
+  return {
+    markLine: {
+      data: data.lines,
+    },
+    markArea: {
+      data: data.areas,
+      zlevel: -1,
+    },
+  };
+}
+
+/**
+ * This method is only for testing both markLines and markAreas
+ * that are used for annotations.
+ *
+ * `getAnnotationsConfig` as of %12.10 supports only markLines.
+ * But this method can generate lines, points and areas.
+ *
+ * @param {Array} annotations Array of annotation objects
+ * @returns {Object} { areas, lines, points }
+ */
+export const parseAnnotations = (annotations) =>
+  annotations.reduce(
+    (acc, annotation) => {
+      // because only markLines are supported all cases will
+      // satisfy this condition. This is more of a sanity check
+      // until markAreas are supported.
+      // https://gitlab.com/gitlab-org/gitlab/-/issues/212910
+      if (areDatesEqual(annotation.min, annotation.max)) {
+        acc.lines.push(generateMarkLines(annotation, 'xAxis'));
+        acc.points.push(generateMarkPoints(annotation, 'xAxis'));
+        return acc;
+      }
+
+      acc.areas.push(generateMarkArea(annotation, 'xAxis'));
+      return acc;
+    },
+    { areas: [], lines: [], points: [] }
+  );
+
+/**
+ * Generate set of markAreas and markLines to draw on charts
+ * as annotations.
+ *
+ * Annotations as of %12.10 will only be markLines.
+ * markAreas are not supported yet. They are generated by
+ * `parseAnnotations` but not rendered.
+ *
+ * @param {Array} annotations Array of annotations
+ * @returns {Object} { markLines }
+ */
+export const getAnnotationsConfig = (annotations) => {
+  if (!annotations.length) {
+    return {};
+  }
+
+  // annotations parsing is moved out so that it can be tested
+  // for markLines and markAreas.
+  const { lines, points } = parseAnnotations(annotations);
+
+  return {
+    markLine: {
+      lineStyle: {
+        color: BLUE_500,
+      },
+      silent: true,
+      data: lines,
+    },
+    markPoint: {
+      itemStyle: {
+        color: BLUE_500,
+      },
+      symbol: arrowSymbol,
+      symbolSize: '8',
+      symbolOffset: [0, ' 60%'],
+      data: points,
+    },
+  };
+};
+
+/**
+ * Given thresholds and annotations options, this method generates
+ * an annotation series that co-exists along with the data series.
+ *
+ * yAxis option is useful in cases where multiple yAxis settings
+ * are used in a chart. Currently, all of our charts have single
+ * yAxis settings.
+ *
+ * @param {Object} params Thresholds, annotations and yAxis options
+ * @returns {Object} Annotation series
+ */
+export const generateAnnotationSeries = (annotations, yAxisIndex = 1) => {
+  if (!annotations.length) {
+    return null;
+  }
+  return merge(
+    {
+      name: ANNOTATIONS_SERIES_NAME,
+      yAxisIndex,
+      type: 'scatter',
+      data: [],
+    },
+    getAnnotationsConfig(annotations)
+  );
+};
+
+/**
+ * This method generates the data series and relevant defaults for a bar chart
+ *
+ * @param {Object} options
+ * @param {string} options.name - xAxis name for the chart
+ * @param {string} options.color - color to render the data series
+ * @param {Array} options.data - data set to be rendered
+ * @param {string} [options.stack] - controls how the stacked charts should render either `stacked` or `tiled`
+ * @param {number} [options.yAxisIndex] - specifies the yAxis to use (if there are multiple)
+ * @returns {Object} Bar chart series
+ */
+export const generateBarSeries = ({
+  name,
+  color,
+  data = [],
+  stack = columnOptions.stacked,
+  yAxisIndex = 0,
+}) => ({
+  type: CHART_TYPE_BAR,
+  name,
+  data,
+  stack,
+  barMaxWidth: '50%',
+  yAxisIndex,
+  itemStyle: {
+    color: hexToRgba(color, 0.2),
+    borderColor: color,
+    borderWidth: 1,
+  },
+  emphasis: {
+    itemStyle: {
+      color: hexToRgba(color, 0.4),
+    },
+  },
+});
+
+/**
+ * This method generates the data series and relevant defaults for a line chart
+ *
+ * @param {Object} options
+ * @param {string} options.name - xAxis name for the chart
+ * @param {string} options.color - color to render the data series
+ * @param {Array} options.data - data set to be rendered
+ * @param {number} [options.yAxisIndex] - specifies the yAxis to use (if there are multiple)
+ * @returns {Object} Line chart series
+ */
+export const generateLineSeries = ({ name, color, data = [], yAxisIndex = 0 }) => ({
+  name,
+  data,
+  type: CHART_TYPE_LINE,
+  yAxisIndex,
+  lineStyle: { color },
+  itemStyle: { color },
+});
+
+export const getTooltipTitle = (params = null, titleAxisName = null) => {
+  if (!params) return '';
+
+  const title = params.seriesData
+    .reduce((acc, { value }) => {
+      if (acc.includes(value[0])) {
+        return acc;
+      }
+      return [...acc, value[0]];
+    }, [])
+    .join(', ');
+
+  return titleAxisName ? `${title} (${titleAxisName})` : title;
+};
+
+export const getTooltipContent = (params = null, valueAxisName = null) => {
+  if (!params) {
+    return {};
+  }
+
+  const { seriesData } = params;
+
+  if (seriesData.length === 1) {
+    const {
+      value: [, yValue],
+      seriesName,
+    } = seriesData[0];
+
+    return {
+      [valueAxisName || seriesName]: {
+        value: yValue,
+        color: '', // ignore color when showing a single series
+      },
+    };
+  }
+
+  return seriesData.reduce((acc, { value: [, yValue], seriesName, color }) => {
+    acc[seriesName] = { value: yValue, color };
+    return acc;
+  }, {});
+};
+
+/**
+ * The method works well if tooltip content should be against y-axis values.
+ * However, for bar charts, the tooltip should be against x-axis values.
+ * This method should be updated to work with all types of visualizations.
+ * https://gitlab.com/gitlab-org/gitlab-ui/-/issues/674
+ *
+ * @param {Object} params series data
+ * @param {String} yAxisTitle y-axis title
+ * @returns {Object} tooltip title and content
+ * @deprecated Use getTooltipContent and getTooltipContent to obtain the tooltip
+ */
+export const getDefaultTooltipContent = (params, yAxisTitle = null) => {
+  const seriesDataLength = params.seriesData.length;
+  const { xLabels, tooltipContent } = params.seriesData.reduce(
+    (acc, chartItem) => {
+      const [title, value] = chartItem.value || [];
+      // Let's use the y axis title as series name when only one series exists
+      // This way, TooltipDefaultFormat will display the y axis title as label
+      const seriesName = seriesDataLength === 1 && yAxisTitle ? yAxisTitle : chartItem.seriesName;
+      const color = seriesDataLength === 1 ? '' : chartItem.color;
+      acc.tooltipContent[seriesName] = {
+        value,
+        color,
+      };
+      if (!acc.xLabels.includes(title)) {
+        acc.xLabels.push(title);
+      }
+      return acc;
+    },
+    {
+      xLabels: [],
+      tooltipContent: {},
+    }
+  );
+
+  return { xLabels, tooltipContent };
+};

package/src/utils/charts/constants.js

@@ -0,0 +1,61 @@
+/**
+ * As of %12.10 all annotations are added as a decorations
+ * by piggybacking a scatter series. The series should
+ * have 'annotations' as name for the annotation tooltips
+ * to work.
+ *
+ * More info here https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28825
+ *
+ */
+export const ANNOTATIONS_SERIES_NAME = 'annotations';
+/**
+ * Annotations have a line (markLine) and an arrow (markPoint).
+ * When the markPoint is hovered, a tooltip is displayed to
+ * show the annotation description.
+ *
+ * All markPoints have this component type
+ */
+export const ANNOTATIONS_COMPONENT_TYPE = 'markPoint';
+
+/**
+ * This is a slight offset that gets applied to the left
+ * of the chart tooltips to ensure a correct position.
+ */
+export const TOOLTIP_LEFT_OFFSET = 2;
+
+/**
+ * This is a slight offset that gets applied to the left
+ * of the chart tooltips to ensure a correct position.
+ */
+export const TOOLTIP_TOP_OFFSET = 10;
+
+/**
+ * These are the accepted values for the layout prop
+ * of the chart legend component
+ */
+export const LEGEND_LAYOUT_INLINE = 'inline';
+export const LEGEND_LAYOUT_TABLE = 'table';
+
+/**
+ * Default values for the chart legend field labels
+ */
+export const LEGEND_AVERAGE_TEXT = 'Avg';
+export const LEGEND_CURRENT_TEXT = 'Current';
+export const LEGEND_MIN_TEXT = 'Min';
+export const LEGEND_MAX_TEXT = 'Max';
+
+/**
+ * These arrow symbols are used as markPoints under the annotations lines
+ * within area and line charts. This icon doesn't exist in the svg
+ * library yet. The below issue is to track the progress of the svg icon
+ * https://gitlab.com/gitlab-org/gitlab-svgs/-/issues/118
+ */
+export const arrowSymbol = 'path://m5 229 5 8h-10z';
+
+// Constants for the type property of charts
+export const CHART_TYPE_BAR = 'bar';
+export const CHART_TYPE_LINE = 'line';
+
+// Constants for height "auto"
+export const HEIGHT_AUTO_CLASSES = 'gl-chart-h-auto gl-flex gl-flex-col gl-h-full';
+export const HEIGHT_AUTO_HORIZONTAL_LAYOUT_CLASSES = 'gl-flex gl-h-full';