fix(app): keep the heatmap tooltip from overflowing its tile

.changeset/heatmap-tooltip-portal.md

@@ -0,0 +1,6 @@
+---
+'@hyperdx/app': patch
+---
+
+fix: heatmap hover tooltip no longer adds scrollbars or shifts the tile; it now
+sits above the chart instead of inside it

packages/app/src/components/DBHeatmapChart/HeatmapPlot.tsx

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import cx from 'classnames';
 import uPlot from 'uplot';
 import UplotReact from 'uplot-react';
-import { useElementSize } from '@mantine/hooks';
+import { useElementSize, useMergedRef } from '@mantine/hooks';
 
 import { useStableValue } from '@/hooks/useStableValue';
 import { NumberFormat } from '@/types';
@@ -73,6 +73,16 @@ export function HeatmapPlot({
     HighlightedPoint | undefined
   >(undefined);
 
+  // The tooltip is fixed to the viewport, so a scroll under a still cursor
+  // would leave it behind; hide it until the next mouse move.
+  const hasHighlight = highlightedPoint != null;
+  useEffect(() => {
+    if (!hasHighlight) return;
+    const hide = () => setHighlightedPoint(undefined);
+    window.addEventListener('scroll', hide, { capture: true, passive: true });
+    return () => window.removeEventListener('scroll', hide, { capture: true });
+  }, [hasHighlight]);
+
   // Gate tooltip display on actual mouse interaction. uPlot fires setCursor
   // on init (before user hovers), which would show the tooltip on page load.
   const mouseInsideRef = useRef(false);
@@ -109,6 +119,8 @@ export function HeatmapPlot({
   });
 
   const { ref, width, height } = useElementSize();
+  const [container, setContainer] = useState<HTMLDivElement | null>(null);
+  const mergedRef = useMergedRef(ref, setContainer);
 
   // Reapply the URL-backed selection whenever the bounds prop changes
   // (e.g. a fresh drag-select arrives via the round-trip through the
@@ -329,7 +341,7 @@ export function HeatmapPlot({
 
   return (
     <div
-      ref={ref}
+      ref={mergedRef}
       className={cx('heatmap-selection-container', className)}
       style={{ width: '100%', height: '100%', position: 'relative' }}
       onClick={() => {
@@ -374,8 +386,7 @@ export function HeatmapPlot({
         <HeatmapTooltip
           point={highlightedPoint}
           cell={highlightedCell}
-          width={width}
-          height={height}
+          containerRect={container?.getBoundingClientRect()}
           showDragHint={!!onFilter}
         />
       )}

packages/app/src/components/DBHeatmapChart/HeatmapTooltip.tsx

@@ -1,5 +1,10 @@
+import { createPortal } from 'react-dom';
 import { Divider, Text } from '@mantine/core';
 
+import {
+  toViewportPoint,
+  useChartTooltipZIndex,
+} from '@/components/charts/ChartTooltip';
 import { FormatTime } from '@/useFormatTime';
 
 import type { HighlightedPoint } from './highlightDataPlugin';
@@ -29,19 +34,29 @@ const COUNT_FORMAT = new Intl.NumberFormat('en-US', {
 type HeatmapTooltipProps = {
   point: HighlightedPoint;
   cell: HeatmapTooltipCell;
-  /** Chart container size, used to keep the tooltip inside it. */
-  width: number;
-  height: number;
+  /** Chart container's viewport rect; the tooltip is portaled so a tile can't clip or scroll it. */
+  containerRect: DOMRect | undefined;
   showDragHint: boolean;
 };
 
 export function HeatmapTooltip({
   point,
   cell,
-  width,
-  height,
+  containerRect,
   showDragHint,
 }: HeatmapTooltipProps) {
+  const zIndex = useChartTooltipZIndex();
+  const anchor = toViewportPoint(containerRect, {
+    x: point.xCoord,
+    y: point.yCoord,
+  });
+  // Fixed elements resolve against the viewport minus scrollbars, not window.inner*.
+  const { clientWidth: viewportWidth, clientHeight: viewportHeight } =
+    document.documentElement;
+  // Open away from the nearer edges so the tooltip fits without knowing its size.
+  const flipLeft = point.xCoord > (containerRect?.width ?? 0) / 2;
+  const flipUp = anchor.y > viewportHeight / 2;
+
   return (
     <>
       <div
@@ -55,73 +70,75 @@ export function HeatmapTooltip({
           background: 'var(--mantine-color-default-hover)',
         }}
       />
-      <div
-        className="px-2 py-1 fs-8"
-        style={{
-          position: 'absolute',
-          // Clamp so the tooltip stays within the chart container
-          top: Math.min(point.yCoord + 5, height - 90),
-          ...(point.xCoord > width / 2
-            ? {
-                right: width - point.xCoord + 10,
-              }
-            : {
-                left: point.xCoord + 10,
-              }),
-          maxWidth: '50%',
-          overflow: 'hidden',
-          textOverflow: 'ellipsis',
-          whiteSpace: 'nowrap' as const,
-          backdropFilter: 'blur(8px)',
-          backgroundColor: 'var(--mantine-color-body)',
-          border: '1px solid var(--mantine-color-default-border)',
-          borderRadius: 4,
-          pointerEvents: 'none',
-        }}
-      >
-        {showDragHint && (
-          <>
-            <Text size="10px" pt="4px">
-              Drag to Compare · Click to Clear
-            </Text>
-            <Divider my="xs" />
-          </>
-        )}
-        <div>
-          <FormatTime value={point.xVal} />
-        </div>
-        {cell.kind === 'series' ? (
-          <>
-            <div>
-              <b>Series:</b> {cell.name}
-            </div>
-            <div>
-              <b>Value:</b> {cell.formattedValue}
-            </div>
-          </>
-        ) : (
-          <>
-            <div>
-              {cell.kind === 'bucket' ? (
-                <>
-                  <b>Bucket:</b> {cell.formattedRange}
-                </>
-              ) : (
-                <>
-                  <b>Y Value:</b> {cell.formattedY}
-                </>
-              )}
-              {cell.percentile != null &&
-                ` (p${new Intl.NumberFormat('en-US', {
-                  maximumFractionDigits: 1,
-                }).format(cell.percentile)})`}
-            </div>
-            <div>
-              <b>Count Value:</b> {COUNT_FORMAT.format(point.countVal)}
-            </div>
-          </>
-        )}
-      </div>
+      {createPortal(
+        <div
+          data-testid="heatmap-tooltip"
+          className="px-2 py-1 fs-8"
+          style={{
+            position: 'fixed',
+            zIndex,
+            ...(flipUp
+              ? { bottom: viewportHeight - anchor.y + 5 }
+              : { top: anchor.y + 5 }),
+            ...(flipLeft
+              ? { right: viewportWidth - anchor.x + 10 }
+              : { left: anchor.x + 10 }),
+            maxWidth: (containerRect?.width ?? viewportWidth) / 2,
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap' as const,
+            backdropFilter: 'blur(8px)',
+            backgroundColor: 'var(--mantine-color-body)',
+            border: '1px solid var(--mantine-color-default-border)',
+            borderRadius: 4,
+            pointerEvents: 'none',
+          }}
+        >
+          {showDragHint && (
+            <>
+              <Text size="10px" pt="4px">
+                Drag to Compare · Click to Clear
+              </Text>
+              <Divider my="xs" />
+            </>
+          )}
+          <div>
+            <FormatTime value={point.xVal} />
+          </div>
+          {cell.kind === 'series' ? (
+            <>
+              <div>
+                <b>Series:</b> {cell.name}
+              </div>
+              <div>
+                <b>Value:</b> {cell.formattedValue}
+              </div>
+            </>
+          ) : (
+            <>
+              <div>
+                {cell.kind === 'bucket' ? (
+                  <>
+                    <b>Bucket:</b> {cell.formattedRange}
+                  </>
+                ) : (
+                  <>
+                    <b>Y Value:</b> {cell.formattedY}
+                  </>
+                )}
+                {cell.percentile != null &&
+                  ` (p${new Intl.NumberFormat('en-US', {
+                    maximumFractionDigits: 1,
+                  }).format(cell.percentile)})`}
+              </div>
+              <div>
+                <b>Count Value:</b> {COUNT_FORMAT.format(point.countVal)}
+              </div>
+            </>
+          )}
+        </div>,
+        document.body,
+      )}
     </>
   );
 }

packages/app/src/components/DBHeatmapChart/__tests__/HeatmapPlot.test.tsx

@@ -165,4 +165,16 @@ describe('HeatmapPlot', () => {
       'Count Value: 7',
     );
   });
+
+  it('hides the tooltip when anything scrolls, until the next hover', () => {
+    renderPlot();
+    fireEvent.mouseMove(screen.getByTestId('heatmap-plot'));
+    act(() => onPointHighlight(point));
+
+    fireEvent.scroll(document.body);
+    expect(screen.queryByText('Count Value:')).not.toBeInTheDocument();
+
+    act(() => onPointHighlight(point));
+    expect(screen.getByText('Count Value:')).toBeInTheDocument();
+  });
 });

packages/app/src/components/DBHeatmapChart/__tests__/HeatmapTooltip.test.tsx

@@ -25,8 +25,7 @@ const renderTooltip = (
     <HeatmapTooltip
       point={point}
       cell={{ kind: 'distribution', formattedY: 'y=2', percentile: undefined }}
-      width={400}
-      height={300}
+      containerRect={new DOMRect(100, 200, 400, 300)}
       showDragHint={false}
       {...props}
     />,
@@ -90,4 +89,43 @@ describe('HeatmapTooltip', () => {
     renderTooltip({ showDragHint: true });
     expect(screen.getByText(/Drag to Compare/)).toBeInTheDocument();
   });
+
+  it('renders the tooltip outside the chart container, in viewport coordinates', () => {
+    const viewportHeight = jest
+      .spyOn(document.documentElement, 'clientHeight', 'get')
+      .mockReturnValue(1000);
+    const { container } = renderTooltip();
+
+    const tooltip = screen
+      .getByText('time:1000')
+      .closest<HTMLElement>('div[style*="position: fixed"]');
+    expect(tooltip).not.toBeNull();
+    expect(container.contains(tooltip)).toBe(false);
+    expect(tooltip?.style.top).toBe('215px');
+    expect(tooltip?.style.left).toBe('120px');
+    viewportHeight.mockRestore();
+  });
+
+  it('keeps the tooltip inside the viewport near its bottom and right edges', () => {
+    const viewport = [
+      jest
+        .spyOn(document.documentElement, 'clientHeight', 'get')
+        .mockReturnValue(400),
+      jest
+        .spyOn(document.documentElement, 'clientWidth', 'get')
+        .mockReturnValue(1200),
+    ];
+    renderTooltip({ point: { ...point, xCoord: 300, yCoord: 190 } });
+
+    const tooltip = screen
+      .getByText('time:1000')
+      .closest<HTMLElement>('div[style*="position: fixed"]');
+    // Cursor at y=390 in a 400px viewport: opens above the cursor.
+    expect(tooltip?.style.bottom).toBe('15px');
+    expect(tooltip?.style.top).toBe('');
+    // Right half of the container: anchored to the left of the cursor.
+    expect(tooltip?.style.right).toBe('810px');
+    expect(tooltip?.style.left).toBe('');
+    viewport.forEach(spy => spy.mockRestore());
+  });
 });

packages/app/tests/e2e/components/HeatmapComponent.ts

@@ -29,12 +29,17 @@ export class HeatmapComponent {
     return this.root.getByText('Not enough data points to render heatmap');
   }
 
+  /** The open cell tooltip, rendered into the page body rather than the chart. */
+  private get tooltipRoot() {
+    return this.page.getByTestId('heatmap-tooltip');
+  }
+
   /**
    * The hover tooltip, which only appears for a cell with a non-zero count.
    * Series-axis heatmaps label the cell's series instead of its count.
    */
   get tooltip() {
-    return this.container.getByText(/^(Count Value|Series):$/);
+    return this.tooltipRoot.getByText(/^(Count Value|Series):$/);
   }
 
   /**
@@ -70,7 +75,7 @@ export class HeatmapComponent {
 
   /** The series named by the open cell tooltip of a series-axis heatmap. */
   async hoveredSeriesName() {
-    const row = this.container
+    const row = this.tooltipRoot
       .getByText('Series:', { exact: true })
       .locator('..');
     await expect(row).toBeVisible();
@@ -79,7 +84,7 @@ export class HeatmapComponent {
 
   /** A labelled value of the open cell tooltip, e.g. `Count Value`. */
   async hoveredTooltipValue(label: 'Count Value' | 'Y Value' | 'Bucket') {
-    const row = this.container
+    const row = this.tooltipRoot
       .getByText(`${label}:`, { exact: true })
       .locator('..');
     await expect(row).toBeVisible();