Timeseries: Add hover proximity option (#81421)

docs/sources/panels-visualizations/visualizations/time-series/index.md

@@ -50,6 +50,10 @@ Tooltip options control the information overlay that appears when you hover over
 
 {{< docs/shared lookup="visualizations/tooltip-mode.md" source="grafana" version="<GRAFANA VERSION>" >}}
 
+### Hover proximity
+
+This option controls how close your cursor must be to a data point before the tooltip appears. Values are in pixels.
+
 ## Legend options
 
 Legend options control the series names and statistics that appear under or to the right of the graph.

packages/grafana-ui/src/components/uPlot/config/UPlotConfigBuilder.ts

@@ -313,6 +313,7 @@ type UPlotConfigPrepOpts<T extends Record<string, unknown> = {}> = {
   tweakAxis?: (opts: AxisProps, forField: Field) => AxisProps;
   // Identifies the shared key for uPlot cursor sync
   eventsScope?: string;
+  hoverProximity?: number;
 } & T;
 
 /** @alpha */

packages/grafana-ui/src/options/builder/tooltip.tsx

@@ -4,6 +4,7 @@ import { OptionsWithTooltip, TooltipDisplayMode, SortOrder } from '@grafana/sche
 export function addTooltipOptions<T extends OptionsWithTooltip>(
   builder: PanelOptionsEditorBuilder<T>,
   singleOnly = false,
+  setProximity = false,
   defaultOptions?: Partial<OptionsWithTooltip>
 ) {
   const category = ['Tooltip'];
@@ -43,7 +44,21 @@ export function addTooltipOptions<T extends OptionsWithTooltip>(
       settings: {
         options: sortOptions,
       },
-    })
+    });
+
+  if (setProximity) {
+    builder.addNumberInput({
+      path: 'tooltip.hoverProximity',
+      name: 'Hover proximity',
+      description: 'How close the cursor must be to a point to trigger the tooltip, in pixels',
+      category,
+      settings: {
+        integer: true,
+      },
+    });
+  }
+
+  builder
     .addNumberInput({
       path: 'tooltip.maxWidth',
       name: 'Max width',

public/app/core/components/TimeSeries/TimeSeries.tsx

@@ -20,7 +20,7 @@ export class UnthemedTimeSeries extends Component<TimeSeriesProps> {
 
   prepConfig = (alignedFrame: DataFrame, allFrames: DataFrame[], getTimeRange: () => TimeRange) => {
     const { eventBus, eventsScope, sync } = this.context;
-    const { theme, timeZone, renderers, tweakAxis, tweakScale } = this.props;
+    const { theme, timeZone, options, renderers, tweakAxis, tweakScale } = this.props;
 
     return preparePlotConfigBuilder({
       frame: alignedFrame,
@@ -34,6 +34,7 @@ export class UnthemedTimeSeries extends Component<TimeSeriesProps> {
       tweakScale,
       tweakAxis,
       eventsScope,
+      hoverProximity: options?.tooltip?.hoverProximity,
     });
   };
 

public/app/core/components/TimeSeries/utils.ts

@@ -89,6 +89,7 @@ export const preparePlotConfigBuilder: UPlotConfigPrepFn<{
   tweakScale = (opts) => opts,
   tweakAxis = (opts) => opts,
   eventsScope = '__global_',
+  hoverProximity,
 }) => {
   const builder = new UPlotConfigBuilder(timeZones[0]);
 
@@ -558,20 +559,32 @@ export const preparePlotConfigBuilder: UPlotConfigPrepFn<{
   builder.scaleKeys = [xScaleKey, yScaleKey];
 
   // if hovered value is null, how far we may scan left/right to hover nearest non-null
-  const hoverProximityPx = 15;
+  const DEFAULT_HOVER_NULL_PROXIMITY = 15;
+  const DEFAULT_FOCUS_PROXIMITY = 30;
 
   let cursor: Partial<uPlot.Cursor> = {
+    // horizontal proximity / point hover behavior
     hover: {
       prox: (self, seriesIdx, hoveredIdx) => {
-        const yVal = self.data[seriesIdx][hoveredIdx];
-        if (yVal === null) {
-          return hoverProximityPx;
+        if (hoverProximity != null) {
+          return hoverProximity;
         }
 
+        // when hovering null values, scan data left/right up to 15px
+        const yVal = self.data[seriesIdx][hoveredIdx];
+        if (yVal === null) {
+          return DEFAULT_HOVER_NULL_PROXIMITY;
+        }
+
+        // no proximity limit
         return null;
       },
       skip: [null],
     },
+    // vertical proximity / series focus behavior
+    focus: {
+      prox: hoverProximity ?? DEFAULT_FOCUS_PROXIMITY,
+    },
   };
 
   if (sync && sync() !== DashboardCursorSync.Off && xField.type === FieldType.time) {

public/app/plugins/panel/candlestick/module.tsx

@@ -138,7 +138,7 @@ export const plugin = new PanelPlugin<Options, GraphFieldConfig>(CandlestickPane
     });
 
     if (config.featureToggles.newVizTooltips) {
-      commonOptionsBuilder.addTooltipOptions(builder, false, opts);
+      commonOptionsBuilder.addTooltipOptions(builder, false, true, opts);
     }
 
     commonOptionsBuilder.addLegendOptions(builder);

public/app/plugins/panel/timeseries/module.tsx

@@ -12,7 +12,7 @@ export const plugin = new PanelPlugin<Options, FieldConfig>(TimeSeriesPanel)
   .setPanelChangeHandler(graphPanelChangedHandler)
   .useFieldConfig(getGraphFieldConfig(defaultGraphConfig))
   .setPanelOptions((builder) => {
-    commonOptionsBuilder.addTooltipOptions(builder);
+    commonOptionsBuilder.addTooltipOptions(builder, false, true);
     commonOptionsBuilder.addLegendOptions(builder);
 
     builder.addCustomEditor({

public/app/plugins/panel/trend/module.tsx

@@ -24,7 +24,7 @@ export const plugin = new PanelPlugin<Options, FieldConfig>(TrendPanel)
       },
     });
 
-    commonOptionsBuilder.addTooltipOptions(builder);
+    commonOptionsBuilder.addTooltipOptions(builder, false, true);
     commonOptionsBuilder.addLegendOptions(builder);
   })
   .setSuggestionsSupplier(new TrendSuggestionsSupplier());