ref(dashboards): Move unit scaling into Plottable (#86116)

This is a refactor of the `Plottable` interface. It clarifies and
separates the type definitions, and moves some ugly mutation logic away
out of the React component and into the constructor classes.

This is an important step on the road to multi-type charts, where lines
and bars can coexist. It'll become a lot clearer when the public API for
`TimeSeriesWidgetVisualization` starts accepting plottables directly.

## Changes

The first change is a clarification of the types, and their
relationships.

- `Plottable` is a generic interface. A `Plottable` is an object that
can be put into ECharts. Right now, only one _kind_ of plottable is
implemented: `PlottableData`, but others are coming (e.g., Releases, and
later other marker types). Right now, `PlottableData` is only used
under-the-hood in `TimeSeriesDataVisualization`, but soon this will be
the public API. Charts will be created by passing various plottable
items to the component
- `Area`, `Line`, and `Bars` all implement the `PlottableData`
interface. They do this by extending the `AggreateTimeSeries` plottable.
`AggregateTimeSeries` is there for sharing code. It specifies the
constructor, and some simple scaling logic. Soon, this class will have
more interesting properties that will make coordinating data between
different plottables easier
- A plottable has a _configuration_ and _plotting options_. The
configuration has to do with the data. How much is that data delayed?
Does it have a specific color? The _plotting options_ have to do with
putting the plottable into ECharts. This answers questions like "what is
the fallback color?" and "what is the Y axis unit"? These things are
computed after taking all plottables into consideration

The second change is smaller, and more subtle. It moves data scaling
into the plottables. This creates _just a bit_ of code duplication, but
is much nicer because this logic is now hidden from the chart (so I can
improve it later).

Author: gggritso

static/app/views/dashboards/widgets/common/types.tsx

@@ -1,4 +1,7 @@
+import type {SeriesOption} from 'echarts';
+
 import type {AccuracyStats, Confidence} from 'sentry/types/organization';
+import type {DurationUnit, RateUnit, SizeUnit} from 'sentry/utils/discover/fields';
 
 import type {ThresholdsConfig} from '../../widgetBuilder/buildSteps/thresholdsStep/thresholdsStep';
 
@@ -45,3 +48,27 @@ export type Release = {
 export type Aliases = Record<string, string>;
 
 export type LegendSelection = {[key: string]: boolean};
+
+/**
+ * A `Plottable` is any object that can be converted to an ECharts `Series` and therefore plotted on an ECharts chart. This could be a data series, releases, samples, and other kinds of markers. `TimeSeriesWidgetVisualization` uses `Plottable` objects under the hood, to convert data coming into the component via props into ECharts series.
+ */
+interface Plottable {
+  /**
+   *
+   * @param plottingOptions Plotting options depend on the specific implementation of the interface.
+   */
+  toSeries(plottingOptions: unknown): SeriesOption[];
+}
+
+/**
+ * `PlottableData` is any plottable that represents a data time series. The points in the series are a pair of a timestamp and a numeric value. This could be a continuous time series of aggregated data, or data samples.
+ */
+export interface PlottableData extends Plottable {
+  /**
+   * @param options Plotting options. The resulting series will have the color `color`, and will be scaled to `unit` if needed.
+   */
+  toSeries(plottingOptions: {
+    color: string;
+    unit: DurationUnit | SizeUnit | RateUnit | null;
+  }): SeriesOption[];
+}

static/app/views/dashboards/widgets/timeSeriesWidget/plottables/aggregateTimeSeries.tsx

@@ -0,0 +1,43 @@
+import type {SeriesOption} from 'echarts';
+
+import type {DurationUnit, RateUnit, SizeUnit} from 'sentry/utils/discover/fields';
+
+import type {PlottableData, TimeSeries} from '../../common/types';
+import {scaleTimeSeriesData} from '../scaleTimeSeriesData';
+
+type BasicDataPlottableConfig = {
+  color?: string;
+};
+
+export type AggregateTimePlottingOptions = {
+  /**
+   * Final plottable color. If no color is specified in configuration, a fallback must be provided while attempting to plot
+   */
+  color: string;
+  /**
+   * Final plottable unit. This might be different from the original unit of the data, because we scale all time series to a single common unit.
+   */
+  unit: DurationUnit | SizeUnit | RateUnit | null;
+};
+
+/**
+ * `AggregateTimeSeries` is a plottable that represents a continuous data time series. This is used for tasks like plotting a changing duration over time, for example. This is distinct from plotting items like sample series, threshold lines, etc. This ABC is inherited by specific plottable time series like `Line`, `Area`, and `Bars` to enforce the interface and share functionality.
+ */
+export abstract class AggregateTimeSeries<TConfig extends BasicDataPlottableConfig>
+  implements PlottableData
+{
+  // Ideally both the `timeSeries` and `config` would be protected properties.
+  timeSeries: Readonly<TimeSeries>;
+  config?: Readonly<TConfig>;
+
+  constructor(timeSeries: TimeSeries, config?: TConfig) {
+    this.timeSeries = timeSeries;
+    this.config = config;
+  }
+
+  scaleToUnit(destinationUnit: DurationUnit | SizeUnit | RateUnit | null): TimeSeries {
+    return scaleTimeSeriesData(this.timeSeries, destinationUnit);
+  }
+
+  abstract toSeries(plottingOptions: AggregateTimePlottingOptions): SeriesOption[];
+}

static/app/views/dashboards/widgets/timeSeriesWidget/plottables/area.tsx

@@ -2,30 +2,45 @@ import type {LineSeriesOption} from 'echarts';
 
 import LineSeries from 'sentry/components/charts/series/lineSeries';
 
-import type {TimeSeries} from '../../common/types';
+import type {PlottableData} from '../../common/types';
 import {splitSeriesIntoCompleteAndIncomplete} from '../splitSeriesIntoCompleteAndIncomplete';
 import {timeSeriesItemToEChartsDataPoint} from '../timeSeriesItemToEChartsDataPoint';
 
-import {Plottable} from './plottable';
+import {
+  type AggregateTimePlottingOptions,
+  AggregateTimeSeries,
+} from './aggregateTimeSeries';
 
-interface AreaOptions {
+interface AreaConfig {
+  /**
+   * Optional color. If not provided, a backfill from a common palette will be provided to `toSeries`
+   */
   color?: string;
-  dataCompletenessDelay?: number;
+  /**
+   * Data delay, in seconds. Data older than N seconds will be visually deemphasized.
+   */
+  delay?: number;
 }
 
-export class Area extends Plottable<AreaOptions> {
-  toSeries(timeSeries: TimeSeries, options: AreaOptions) {
+/**
+ * See documentation for `PlottableData` for an explanation.
+ */
+export class Area extends AggregateTimeSeries<AreaConfig> implements PlottableData {
+  toSeries(plottingOptions: AggregateTimePlottingOptions): LineSeriesOption[] {
+    const {timeSeries, config = {}} = this;
+
+    const {color, unit} = plottingOptions;
+
+    const scaledSeries = this.scaleToUnit(unit);
+
     const [completeTimeSeries, incompleteTimeSeries] =
-      splitSeriesIntoCompleteAndIncomplete(
-        timeSeries,
-        options.dataCompletenessDelay ?? 0
-      );
+      splitSeriesIntoCompleteAndIncomplete(scaledSeries, config.delay ?? 0);
 
     const plottableSeries: LineSeriesOption[] = [];
 
     const commonOptions = {
       name: timeSeries.field,
-      color: options.color,
+      color,
       animation: false,
     };
 
@@ -53,7 +68,7 @@ export class Area extends Plottable<AreaOptions> {
             type: 'dotted',
           },
           areaStyle: {
-            color: options.color,
+            color,
             opacity: 0.8,
           },
           silent: true,

static/app/views/dashboards/widgets/timeSeriesWidget/plottables/bars.tsx

@@ -1,36 +1,58 @@
 import Color from 'color';
+import type {BarSeriesOption, LineSeriesOption} from 'echarts';
 
 import BarSeries from 'sentry/components/charts/series/barSeries';
 
-import type {TimeSeries} from '../../common/types';
+import type {PlottableData} from '../../common/types';
 import {markDelayedData} from '../markDelayedData';
 import {timeSeriesItemToEChartsDataPoint} from '../timeSeriesItemToEChartsDataPoint';
 
-import {Plottable} from './plottable';
+import {
+  type AggregateTimePlottingOptions,
+  AggregateTimeSeries,
+} from './aggregateTimeSeries';
 
-interface BarsOptions {
+interface BarsConfig {
+  /**
+   * Optional color. If not provided, a backfill from a common palette will be provided to `toSeries`
+   */
   color?: string;
-  dataCompletenessDelay?: number;
+  /**
+   * Data delay, in seconds. Data older than N seconds will be visually deemphasized.
+   */
+  delay?: number;
+  /**
+   * Stack name. If provided, bar plottables with the same stack will be stacked visually.
+   */
   stack?: string;
 }
 
-export class Bars extends Plottable<BarsOptions> {
-  toSeries(timeSeries: TimeSeries, options: BarsOptions) {
-    const markedSeries = markDelayedData(timeSeries, options.dataCompletenessDelay ?? 0);
+/**
+ * See documentation for `PlottableData` for an explanation.
+ */
+export class Bars extends AggregateTimeSeries<BarsConfig> implements PlottableData {
+  toSeries(
+    plottingOptions: AggregateTimePlottingOptions
+  ): Array<BarSeriesOption | LineSeriesOption> {
+    const {timeSeries, config = {}} = this;
+
+    const {color, unit} = plottingOptions;
+
+    const scaledTimeSeries = this.scaleToUnit(unit);
+
+    const markedSeries = markDelayedData(scaledTimeSeries, config.delay ?? 0);
 
     return [
       BarSeries({
-        name: markedSeries.field,
-        color: markedSeries.color,
-        stack: options.stack ?? GLOBAL_STACK_NAME,
+        name: timeSeries.field,
+        color: timeSeries.color,
+        stack: config.stack ?? GLOBAL_STACK_NAME,
         animation: false,
         itemStyle: {
           color: params => {
             const datum = markedSeries.data[params.dataIndex]!;
 
-            return datum.delayed
-              ? Color(options.color).lighten(0.5).string()
-              : options.color!;
+            return datum.delayed ? Color(color).lighten(0.5).string() : color!;
           },
           opacity: 1.0,
         },

static/app/views/dashboards/widgets/timeSeriesWidget/plottables/line.tsx

@@ -2,30 +2,45 @@ import type {LineSeriesOption} from 'echarts';
 
 import LineSeries from 'sentry/components/charts/series/lineSeries';
 
-import type {TimeSeries} from '../../common/types';
+import type {PlottableData} from '../../common/types';
 import {splitSeriesIntoCompleteAndIncomplete} from '../splitSeriesIntoCompleteAndIncomplete';
 import {timeSeriesItemToEChartsDataPoint} from '../timeSeriesItemToEChartsDataPoint';
 
-import {Plottable} from './plottable';
+import {
+  type AggregateTimePlottingOptions,
+  AggregateTimeSeries,
+} from './aggregateTimeSeries';
 
-interface LineOptions {
+interface LineConfig {
+  /**
+   * Optional color. If not provided, a backfill from a common palette will be provided to `toSeries`
+   */
   color?: string;
-  dataCompletenessDelay?: number;
+  /**
+   * Data delay, in seconds. Data older than N seconds will be visually deemphasized.
+   */
+  delay?: number;
 }
 
-export class Line extends Plottable<LineOptions> {
-  toSeries(timeSeries: TimeSeries, options: LineOptions) {
+/**
+ * See documentation for `PlottableData` for an explanation.
+ */
+export class Line extends AggregateTimeSeries<LineConfig> implements PlottableData {
+  toSeries(plottingOptions: AggregateTimePlottingOptions) {
+    const {timeSeries, config = {}} = this;
+
+    const {color, unit} = plottingOptions;
+
+    const scaledSeries = this.scaleToUnit(unit);
+
     const [completeTimeSeries, incompleteTimeSeries] =
-      splitSeriesIntoCompleteAndIncomplete(
-        timeSeries,
-        options.dataCompletenessDelay ?? 0
-      );
+      splitSeriesIntoCompleteAndIncomplete(scaledSeries, config.delay ?? 0);
 
     const plottableSeries: LineSeriesOption[] = [];
 
     const commonOptions = {
       name: timeSeries.field,
-      color: options.color,
+      color,
       animation: false,
     };
 

static/app/views/dashboards/widgets/timeSeriesWidget/plottables/plottable.tsx

@@ -41,7 +41,6 @@ import {formatXAxisTimestamp} from './formatXAxisTimestamp';
 import {formatYAxisValue} from './formatYAxisValue';
 import {isTimeSeriesOther} from './isTimeSeriesOther';
 import {ReleaseSeries} from './releaseSeries';
-import {scaleTimeSeriesData} from './scaleTimeSeriesData';
 import {FALLBACK_TYPE, FALLBACK_UNIT_FOR_FIELD_TYPE} from './settings';
 
 type VisualizationType = 'area' | 'line' | 'bar';
@@ -178,11 +177,6 @@ export function TimeSeriesWidgetVisualization(props: TimeSeriesWidgetVisualizati
     yAxisUnit = FALLBACK_UNIT_FOR_FIELD_TYPE[yAxisFieldType];
   }
 
-  // Apply unit scaling to all series
-  const scaledSeries = props.timeSeries.map(timeSeries => {
-    return scaleTimeSeriesData(timeSeries, yAxisUnit);
-  });
-
   // Construct plottable items
   const numberOfSeriesNeedingColor = props.timeSeries.filter(needsColor).length;
 
@@ -192,7 +186,7 @@ export function TimeSeriesWidgetVisualization(props: TimeSeriesWidgetVisualizati
       : [];
 
   let seriesColorIndex = 0;
-  const plottables = scaledSeries.map(timeSeries => {
+  const plottables = props.timeSeries.map(timeSeries => {
     let color: string;
 
     if (timeSeries.color) {
@@ -209,21 +203,21 @@ export function TimeSeriesWidgetVisualization(props: TimeSeriesWidgetVisualizati
 
     if (props.visualizationType === 'area') {
       return new Area(timeSeries, {
-        dataCompletenessDelay,
+        delay: dataCompletenessDelay,
         color,
       });
     }
 
     if (props.visualizationType === 'bar') {
       return new Bars(timeSeries, {
-        dataCompletenessDelay,
+        delay: dataCompletenessDelay,
         color,
         stack: props.stacked ? GLOBAL_STACK_NAME : undefined,
       });
     }
 
     return new Line(timeSeries, {
-      dataCompletenessDelay,
+      delay: dataCompletenessDelay,
       color,
     });
   });
@@ -273,13 +267,7 @@ export function TimeSeriesWidgetVisualization(props: TimeSeriesWidgetVisualizati
           return formatTooltipValue(value, FALLBACK_TYPE);
         }
 
-        const timeSeries = scaledSeries.find(t => t.field === field);
-
-        return formatTooltipValue(
-          value,
-          timeSeries?.meta?.fields?.[field] ?? FALLBACK_TYPE,
-          timeSeries?.meta?.units?.[field] ?? undefined
-        );
+        return formatTooltipValue(value, yAxisFieldType, yAxisUnit ?? undefined);
       },
       nameFormatter: seriesName => {
         return props.aliases?.[seriesName] ?? formatSeriesName(seriesName);
@@ -289,14 +277,19 @@ export function TimeSeriesWidgetVisualization(props: TimeSeriesWidgetVisualizati
     })(deDupedParams, asyncTicket);
   };
 
-  let visibleSeriesCount = scaledSeries.length;
+  let visibleSeriesCount = plottables.length;
   if (releaseSeries) {
     visibleSeriesCount += 1;
   }
 
   const showLegend = visibleSeriesCount > 1;
 
-  const dataSeries = plottables.flatMap(plottable => plottable.series);
+  const dataSeries = plottables.flatMap(plottable =>
+    plottable.toSeries({
+      color: plottable.config?.color!, // Colors are assigned from palette, above, so they're guaranteed to be there
+      unit: yAxisUnit,
+    })
+  );
 
   return (
     <BaseChart