feat: highlight the series nearest the cursor in time chart tooltips (#2456)

Multi-series Line and Area chart tooltips list every series at the hovered time. When a Group By produces many series, it is hard to tell which tooltip row maps to which line. This bolds the row for the series whose line is nearest the cursor and updates it as the pointer moves up and down, so a row is easy to trace back to its line.

HDX-4531

## Summary

In the shared tooltip for `HDXMultiSeriesTimeChart`, the row for the series nearest the cursor renders at `font-weight: 600` (the same weight the legend uses for a selected series). The highlighted row updates as the pointer moves vertically and clears when the pointer is farther than a small threshold from every line, so nothing is emphasized in empty space.

The nearest series is found in pure pixel space. Each Area's active dot records its active-point pixel Y, and the tooltip compares those positions against the cursor's pixel Y (`coordinate.y`). No axis-scale reconstruction is involved, which matters because the y domain is often `[0, 'auto']`.

## Changes

- `ChartUtils.tsx`: new pure helper `findNearestSeriesKey(seriesYByKey, candidateKeys, pointerY, maxDistancePx)` that returns the nearest series' key within the threshold, or `undefined`. Isolated so the geometry is unit-testable without rendering Recharts.
- `HDXMultiSeriesTimeChart.tsx`: a small capturing active dot on the `<Area>` branch records each series' active-point pixel Y into a per-chart ref, keyed by `dataKey`. It still draws the same dot Recharts renders by default. The tooltip reads the ref to bold the nearest row. Highlighting only applies when more than one series is shown.
- `ChartTooltip.tsx`: `ChartTooltipItem` takes an optional `highlighted` prop that sets the row weight to 600. Backward compatible; existing callers are unaffected.

## Why a ref read during render

Recharts renders the graphical items and their active dots before it renders the tooltip in the same commit, so the captured dot positions are current when the tooltip reads them. Both the capture write and the tooltip read touch a ref during render; this mirrors the existing pattern in `TimelineMouseCursor` and `TimelineXAxis`, and the `react-hooks/refs` disable is annotated with the reason.

## Out of scope

Stacked bar uses `activeBar` rather than `activeDot`, and vertical stacking makes "nearest line" meaningless, so it is intentionally untouched. Single-series charts have nothing to disambiguate, so highlighting is skipped there. Both cases were verified to render with no bold row.

## Test plan

- [x] `yarn lint:fix`, `make ci-lint`
- [x] `make ci-unit`, with new unit tests for `findNearestSeriesKey`: nearest within threshold, none within threshold, undefined pointer, undefined map, empty candidate list, candidate absent from the map skipped, tie resolves to the first candidate, inclusive boundary at `maxDistancePx`
- [x] Manual in Chart Explorer, a Logs Line chart grouped by `ServiceName` with several series:
  - hovering bolds exactly one row, the series nearest the cursor
  - moving the pointer down moves the bold through the lines in order
  - nothing bolds when the pointer is far above every line or below the baseline
  - confirmed in both light and dark themes
  - stacked-bar tooltip shows no bold row; single-series tooltip shows no bold row

Before this change every tooltip row rendered at the same weight. Before/after captures in light and dark are ready to attach.

[ui-states: allow]
[viewport: allow]
[no-story: allow]

Author: alex-fedotyev

.changeset/tooltip-highlight-nearest-series.md

@@ -0,0 +1,5 @@
+---
+"@hyperdx/app": patch
+---
+
+feat: emphasize the series nearest the cursor in multi-series time charts. The nearest line is thickened and the others fade back, and its tooltip row is bolded while the rest dim, so a value is easy to trace back to its line.

packages/app/src/ChartUtils.tsx

@@ -130,8 +130,8 @@ export function convertToTimeChartConfig(
 
   // When the range is bucket-aligned, the end is the start of the next bucket,
   // so end-exclusive is required to avoid double-counting boundary events.
-  // When alignment is off the end is the user's exact selection — fall back to
-  // the caller's setting, if there is one.
+  // When alignment is off the end is the user's exact selection, so fall back
+  // to the caller's setting, if there is one.
   const isAligned = config.alignDateRangeToGranularity !== false;
   const dateRangeEndInclusive = isAligned
     ? false
@@ -473,6 +473,48 @@ export function getPreviousDateRange(currentRange: [Date, Date]): [Date, Date] {
   ];
 }
 
+/**
+ * Find the series whose active-point pixel Y is closest to the cursor.
+ *
+ * `seriesYByKey` maps each series' dataKey to the pixel Y of its
+ * active point (captured from the chart's active dots), and `pointerY`
+ * is the cursor's pixel Y. Both live in the same chart pixel space, so
+ * the nearest series is the one with the smallest vertical distance.
+ * Returns that series' dataKey, or `undefined` when the pointer is
+ * farther than `maxDistancePx` from every line (so nothing is
+ * highlighted in empty space). Candidates not present in the map are
+ * skipped, and ties resolve to the first candidate in `candidateKeys`.
+ */
+export function findNearestSeriesKey(
+  seriesYByKey: Map<string, number> | undefined,
+  candidateKeys: string[],
+  pointerY: number | undefined,
+  maxDistancePx: number,
+): string | undefined {
+  if (seriesYByKey == null || pointerY == null) {
+    return undefined;
+  }
+
+  let nearestKey: string | undefined;
+  let nearestDistance = Infinity;
+  for (const key of candidateKeys) {
+    const seriesY = seriesYByKey.get(key);
+    if (seriesY == null) {
+      continue;
+    }
+    const distance = Math.abs(seriesY - pointerY);
+    if (distance < nearestDistance) {
+      nearestDistance = distance;
+      nearestKey = key;
+    }
+  }
+
+  if (nearestKey == null || nearestDistance > maxDistancePx) {
+    return undefined;
+  }
+  return nearestKey;
+}
+
 export interface LineData {
   dataKey: string;
   currentPeriodKey: string;

packages/app/src/HDXMultiSeriesTimeChart.tsx

@@ -30,6 +30,7 @@ import {
   ChartTooltipItem,
 } from './components/charts/ChartTooltip';
 import {
+  findNearestSeriesKey,
   LineData,
   MAX_TIME_CHART_SERIES,
   toStartOfInterval,
@@ -40,6 +41,11 @@ import styles from '../styles/HDXLineChart.module.scss';
 
 const MAX_LEGEND_ITEMS = 4;
 
+// Vertical pixel distance within which a series' line counts as "near" the
+// cursor for tooltip highlighting. Beyond this, no row is emphasized so the
+// tooltip is not misleading when the pointer is in empty space.
+const NEAREST_SERIES_MAX_DISTANCE_PX = 30;
+
 const Y_AXIS_WIDTH = 40;
 const SINGLE_POINT_BAR_RIGHT_PADDING = 10;
 const SINGLE_POINT_BAR_WIDTH_RATIO = 0.8;
@@ -60,10 +66,14 @@ export const TooltipItem = memo(
     p,
     previous,
     numberFormat,
+    highlighted,
+    dimmed,
   }: {
     p: TooltipPayload;
     previous?: TooltipPayload;
     numberFormat?: NumberFormat;
+    highlighted?: boolean;
+    dimmed?: boolean;
   }) => {
     return (
       <ChartTooltipItem
@@ -75,6 +85,8 @@ export const TooltipItem = memo(
         strokeDasharray={p.strokeDasharray}
         opacity={p.opacity}
         previous={previous?.value}
+        highlighted={highlighted}
+        dimmed={dimmed}
       />
     );
   },
@@ -85,6 +97,8 @@ type HDXLineChartTooltipProps = {
   previousPeriodOffsetSeconds?: number;
   numberFormat?: NumberFormat;
   numberFormatByKey: Map<string, NumberFormat>;
+  /** Per-series active-point pixel Y, captured by the Area active dots. */
+  activePointYByKeyRef: React.MutableRefObject<Map<string, number>>;
 } & Record<string, any>;
 
 const HDXLineChartTooltip = withErrorBoundary(
@@ -97,6 +111,7 @@ const HDXLineChartTooltip = withErrorBoundary(
       numberFormatByKey,
       lineDataMap,
       previousPeriodOffsetSeconds,
+      activePointYByKeyRef,
     } = props;
     const typedPayload = payload as TooltipPayload[];
 
@@ -120,6 +135,26 @@ const HDXLineChartTooltip = withErrorBoundary(
           )}
         </>
       );
+
+      // `coordinate.y` is the cursor's pixel Y; compare it to each series'
+      // active-dot pixel Y to bold the nearest line. The active dots wrote
+      // their positions earlier in this same render (Recharts renders
+      // graphical items before the tooltip), so the capture is current.
+      const pointerY: number | undefined = props.coordinate?.y;
+      // eslint-disable-next-line react-hooks/refs
+      const activePointYByKey = activePointYByKeyRef?.current ?? undefined;
+      // Only disambiguate when there is more than one series; a single-series
+      // tooltip has nothing to map back to a line.
+      const nearestSeriesKey =
+        typedPayload.length > 1
+          ? findNearestSeriesKey(
+              activePointYByKey,
+              typedPayload.map(p => p.dataKey),
+              pointerY,
+              NEAREST_SERIES_MAX_DISTANCE_PX,
+            )
+          : undefined;
+
       return (
         <ChartTooltipContainer header={header}>
           {payload
@@ -142,6 +177,10 @@ const HDXLineChartTooltip = withErrorBoundary(
                   p={p}
                   numberFormat={numberFormatForKey}
                   previous={previousPayload}
+                  highlighted={p.dataKey === nearestSeriesKey}
+                  dimmed={
+                    nearestSeriesKey != null && p.dataKey !== nearestSeriesKey
+                  }
                 />
               );
             })}
@@ -337,6 +376,58 @@ const StackedBarWithOverlap = (props: BarProps) => {
   );
 };
 
+type CaptureActiveDotProps = {
+  /** Shared ref the tooltip reads to find the series nearest the cursor. */
+  captureRef: React.MutableRefObject<Map<string, number>>;
+  cx?: number;
+  cy?: number;
+  dataKey?: string | number;
+  r?: number;
+  fill?: string;
+  stroke?: string;
+  strokeWidth?: number;
+};
+
+/**
+ * Active dot for an Area series. Records the active point's pixel Y (`cy`)
+ * into `captureRef`, keyed by dataKey, then draws the same dot Recharts
+ * renders by default. Recharts clones this element with the active-point
+ * props (cx, cy, dataKey, r, fill, stroke, strokeWidth) during the render
+ * that precedes the tooltip, so the ref is current when the tooltip reads
+ * it to find the series nearest the cursor.
+ */
+function CaptureActiveDot({
+  captureRef,
+  cx,
+  cy,
+  dataKey,
+  r,
+  fill,
+  stroke,
+  strokeWidth,
+}: CaptureActiveDotProps) {
+  if (dataKey != null && typeof cy === 'number' && Number.isFinite(cy)) {
+    // Written synchronously during render so the tooltip, which Recharts
+    // renders after the graphical items in the same commit, reads the
+    // current frame's positions rather than the previous frame's.
+    // eslint-disable-next-line react-hooks/refs
+    captureRef.current.set(String(dataKey), cy);
+  }
+  if (typeof cx !== 'number' || typeof cy !== 'number') {
+    return null;
+  }
+  return (
+    <circle
+      cx={cx}
+      cy={cy}
+      r={r}
+      fill={fill}
+      stroke={stroke}
+      strokeWidth={strokeWidth}
+    />
+  );
+}
+
 /**
  * Compute the unique set of hexes referenced by `<linearGradient>` defs
  * inside MemoChart. Exported so a unit test can pin the dedup-and-union
@@ -345,7 +436,7 @@ const StackedBarWithOverlap = (props: BarProps) => {
  *
  * Includes every categorical hex up front so any positional `<Area>`
  * fill resolves, then unions in semantic hexes returned by the
- * `getChartColor{Info,Success,Warning,Error}` helpers — those land in
+ * `getChartColor{Info,Success,Warning,Error}` helpers; those land in
  * `lineData[].color` and would otherwise be missing a matching def.
  * `undefined` colors are filtered so `c.replace('#', '')` can't throw
  * on a future caller that leaves a series color unset.
@@ -417,6 +508,21 @@ export const MemoChart = memo(function MemoChart({
 
   const [isHovered, setIsHovered] = useState(false);
 
+  // Filled by each Area's active dot with the series' active-point pixel Y,
+  // keyed by dataKey, so the tooltip can bold the series nearest the cursor.
+  // Read during the same render that draws the active dots.
+  const activePointYByKeyRef = useRef<Map<string, number>>(new Map());
+
+  // Key of the series whose line is nearest the cursor, lifted into state so
+  // the chart can emphasize that line (thicker stroke) and fade the rest.
+  // Set from the chart's mouse-move using the pixel Y the active dots captured
+  // on the prior frame; the one-frame lag is imperceptible and settles as soon
+  // as the pointer stops. The tooltip derives the same nearest row itself,
+  // same-frame, for its own bolding and dimming.
+  const [nearestSeriesKey, setNearestSeriesKey] = useState<
+    string | undefined
+  >();
+
   const ChartComponent = useMemo(
     () => (displayType === DisplayType.StackedBar ? BarChart : AreaChart), // LineChart;
     [displayType],
@@ -435,6 +541,15 @@ export const MemoChart = memo(function MemoChart({
         return !hasSelection || selectedSeriesNames.has(seriesName);
       });
 
+    // When a series is nearest the cursor (only meaningful with more than one
+    // line shown), thicken its line and fade the others so the eye lands on
+    // the same series the tooltip bolds. Mirrors the legend's selected style
+    // (thicker stroke) with a gentle fade that keeps the rest readable.
+    const hasNearest =
+      limitedGroupKeys.length > 1 &&
+      nearestSeriesKey != null &&
+      limitedGroupKeys.includes(nearestSeriesKey);
+
     return limitedGroupKeys.map(key => {
       const lineDataIndex = lineData.findIndex(ld => ld.dataKey === key);
       const color = lineData[lineDataIndex]?.color;
@@ -460,6 +575,11 @@ export const MemoChart = memo(function MemoChart({
           type="monotone"
           stroke={color}
           fillOpacity={1}
+          strokeWidth={hasNearest && key === nearestSeriesKey ? 2.5 : undefined}
+          strokeOpacity={
+            hasNearest && key !== nearestSeriesKey ? 0.5 : undefined
+          }
+          activeDot={<CaptureActiveDot captureRef={activePointYByKeyRef} />}
           {...(isHovered
             ? { fill: 'none', strokeDasharray }
             : {
@@ -472,7 +592,14 @@ export const MemoChart = memo(function MemoChart({
         />
       );
     });
-  }, [lineData, displayType, id, isHovered, selectedSeriesNames]);
+  }, [
+    lineData,
+    displayType,
+    id,
+    isHovered,
+    selectedSeriesNames,
+    nearestSeriesKey,
+  ]);
 
   const yAxisDomain: AxisDomain = useMemo(() => {
     const hasSelection = selectedSeriesNames && selectedSeriesNames.size > 0;
@@ -638,6 +765,7 @@ export const MemoChart = memo(function MemoChart({
         onMouseEnter={() => setIsHovered(true)}
         onMouseLeave={() => {
           setIsHovered(false);
+          setNearestSeriesKey(undefined);
 
           setHighlightStart(undefined);
           setHighlightEnd(undefined);
@@ -652,6 +780,27 @@ export const MemoChart = memo(function MemoChart({
         onMouseMove={e => {
           setIsHovered(true);
 
+          // Track which series' line is nearest the cursor so the lines can
+          // emphasize it. The active dots captured their pixel Y on the prior
+          // frame; comparing the pointer's chartY picks the nearest line. Skip
+          // while a click-frozen tooltip is shown, matching the tooltip, and
+          // only set state when the key changes to keep re-renders rare.
+          const activePointYByKey = activePointYByKeyRef.current;
+          const nextNearest =
+            isClickActive == null &&
+            activePointYByKey.size > 1 &&
+            e?.chartY != null
+              ? findNearestSeriesKey(
+                  activePointYByKey,
+                  Array.from(activePointYByKey.keys()),
+                  e.chartY,
+                  NEAREST_SERIES_MAX_DISTANCE_PX,
+                )
+              : undefined;
+          setNearestSeriesKey(prev =>
+            prev === nextNearest ? prev : nextNearest,
+          );
+
           if (highlightStart != null) {
             setHighlightEnd(e.activeLabel);
             setIsClickActive(undefined); // Clear out any click state as we're highlighting
@@ -722,6 +871,9 @@ export const MemoChart = memo(function MemoChart({
               yPerc: state.chartY / sizeRef.current[1],
               activePayload: state.activePayload,
             });
+            // The click-frozen tooltip hides the live tooltip, so drop any
+            // line emphasis to match.
+            setNearestSeriesKey(undefined);
           } else {
             // We clicked on the chart but outside of a line
             setIsClickActive(undefined);
@@ -785,6 +937,7 @@ export const MemoChart = memo(function MemoChart({
                 numberFormatByKey={tooltipNumberFormatsByKey}
                 lineDataMap={lineDataMap}
                 previousPeriodOffsetSeconds={previousPeriodOffsetSeconds}
+                activePointYByKeyRef={activePointYByKeyRef}
               />
             }
             wrapperStyle={{