@perses-dev/timeseries-chart-plugin 0.14.0-beta.7 → 0.14.0-rc.0

package/lib/TimeSeriesChartBase.js

@@ -12,19 +12,22 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import { Box } from "@mui/material";
-import { clearHighlightedSeries, DEFAULT_PINNED_CROSSHAIR, DEFAULT_TOOLTIP_CONFIG, EChart, enableDataZoom, getClosestTimestamp, getCommonTimeScale, getFormattedAxis, getPointInGrid, restoreChart, TimeChartTooltip, useChartsContext, useTimeZone } from "@perses-dev/components";
-import { LineChart as EChartsLineChart, BarChart as EChartsBarChart } from "echarts/charts";
+import { clearHighlightedSeries, DEFAULT_PINNED_CROSSHAIR, DEFAULT_TOOLTIP_CONFIG, EChart, enableDataZoom, ExemplarMetadataTooltip, getClosestTimestamp, getCommonTimeScale, getFormattedAxis, getPointInGrid, restoreChart, TimeChartTooltip, useChartsContext, useTimeZone } from "@perses-dev/components";
+import { LineChart as EChartsLineChart, BarChart as EChartsBarChart, ScatterChart as EChartsScatterChart } from "echarts/charts";
 import { GridComponent, DatasetComponent, DataZoomComponent, MarkAreaComponent, MarkLineComponent, MarkPointComponent, TitleComponent, ToolboxComponent, TooltipComponent } from "echarts/components";
 import { use as registerECharts } from "echarts/core";
 import { CanvasRenderer } from "echarts/renderers";
 import isEqual from "lodash/isEqual";
 import merge from "lodash/merge";
-import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
-import { AnnotationTooltip, buildAnnotationSeries } from "./annotations/AnnotationTooltip.js";
+import { forwardRef, useCallback, useImperativeHandle, useMemo, useRef, useState } from "react";
+import useResizeObserver from "use-resize-observer";
+import { ANNOTATION_Y_AXIS, AnnotationTooltip, buildAnnotationSeries } from "./annotations/AnnotationTooltip.js";
+import { EXEMPLAR_SERIES_ID_PREFIX, EXEMPLAR_SYMBOL_SIZE, getExemplarSeries } from "./utils/data-transform.js";
 import { createTimezoneAwareAxisFormatter } from "./utils/timezone-formatter.js";
 registerECharts([
     EChartsLineChart,
     EChartsBarChart,
+    EChartsScatterChart,
     GridComponent,
     DatasetComponent,
     DataZoomComponent,
@@ -36,7 +39,15 @@ registerECharts([
     TooltipComponent,
     CanvasRenderer
 ]);
-export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({ height, data, seriesMapping, annotations, timeScale: timeScaleProp, yAxis, format, seriesFormatMap, grid, isStackedBar = false, tooltipConfig = DEFAULT_TOOLTIP_CONFIG, noDataVariant = 'message', syncGroup, onDataZoom, onDoubleClick, __experimentalEChartsOptionsOverride }, ref) {
+/**
+ * Maximum pixel distance from an exemplar marker center for the cursor to count as still
+ * hovering it (covers the full diamond bounding box, corners included).
+ */ const EXEMPLAR_HOVER_RADIUS = Math.SQRT2 * EXEMPLAR_SYMBOL_SIZE / 2;
+const CHART_SX = {
+    width: '100%',
+    height: '100%'
+};
+export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({ height, data, seriesMapping, exemplars, annotations, timeScale: timeScaleProp, yAxis, format, seriesFormatMap, grid, isStackedBar = false, tooltipConfig = DEFAULT_TOOLTIP_CONFIG, noDataVariant = 'message', syncGroup, onDataZoom, onDoubleClick, __experimentalEChartsOptionsOverride }, ref) {
     const { chartsTheme, enablePinning, enableSyncGrouping, lastTooltipPinnedCoords, setLastTooltipPinnedCoords } = useChartsContext();
     const isPinningEnabled = tooltipConfig.enablePinning && enablePinning;
     const chartRef = useRef();
@@ -47,33 +58,48 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
     const [startX, setStartX] = useState(0);
     const [hoveredAnnotation, setHoveredAnnotation] = useState(null);
     const [pinnedAnnotation, setPinnedAnnotation] = useState(null);
+    const [hoveredExemplar, setHoveredExemplar] = useState(null);
+    const [pinnedExemplar, setPinnedExemplar] = useState(null);
+    const [pinnedExemplarPos, setPinnedExemplarPos] = useState(null);
     const [pinnedAnnotationPos, setPinnedAnnotationPos] = useState(null);
     const { timeZone, formatWithUserTimeZone } = useTimeZone();
     const getTimezoneAwareAxisFormatter = useCallback((rangeMs)=>createTimezoneAwareAxisFormatter(rangeMs, timeZone), [
         timeZone
     ]);
-    let timeScale;
-    if (timeScaleProp === undefined) {
+    const timeScale = useMemo(()=>{
+        if (timeScaleProp) return timeScaleProp;
         const commonTimeScale = getCommonTimeScale(data);
-        if (commonTimeScale === undefined) {
-            // set default to past 5 years
-            const today = new Date();
-            const pastDate = new Date(today);
-            pastDate.setFullYear(today.getFullYear() - 5);
-            const todayMs = today.getTime();
-            const pastDateMs = pastDate.getTime();
-            timeScale = {
-                startMs: pastDateMs,
-                endMs: todayMs,
-                stepMs: 1,
-                rangeMs: todayMs - pastDateMs
-            };
-        } else {
-            timeScale = commonTimeScale;
+        if (commonTimeScale) return commonTimeScale;
+        // Set the empty chart's default range to the past five years.
+        const today = new Date();
+        const pastDate = new Date(today);
+        pastDate.setFullYear(today.getFullYear() - 5);
+        const startMs = pastDate.getTime();
+        const endMs = today.getTime();
+        return {
+            startMs,
+            endMs,
+            stepMs: 1,
+            rangeMs: endMs - startMs
+        };
+    }, [
+        data,
+        timeScaleProp
+    ]);
+    // EChart resizes whenever its sx identity changes. Keep sx stable and observe
+    // actual container dimensions so hover/pinning never relayouts every series.
+    const handleResize = useCallback(({ width, height: containerHeight })=>{
+        const chart = chartRef.current;
+        if (width && containerHeight && chart && (chart.getWidth() !== width || chart.getHeight() !== containerHeight)) {
+            chart.resize({
+                width,
+                height: containerHeight
+            });
         }
-    } else {
-        timeScale = timeScaleProp;
-    }
+    }, []);
+    const { ref: containerRef } = useResizeObserver({
+        onResize: handleResize
+    });
     useImperativeHandle(ref, ()=>{
         return {
             highlightSeries ({ name }) {
@@ -120,12 +146,24 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
                     enableDataZoom(chartRef.current);
                 }
             },
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             mouseover: (params)=>{
+                if (params.componentType === 'series' && params.seriesType === 'scatter' && 'seriesId' in params && typeof params.seriesId === 'string' && params.seriesId.startsWith(EXEMPLAR_SERIES_ID_PREFIX)) {
+                    // This series ID identifies the metadata embedded by getExemplarSeries.
+                    const point = params.data;
+                    if (point?.exemplar) {
+                        setHoveredExemplar({
+                            exemplar: point.exemplar,
+                            seriesLabels: point.seriesLabels,
+                            plottedValue: point.value?.[1] ?? point.exemplar.value
+                        });
+                        return;
+                    }
+                }
+                setHoveredExemplar(null);
                 // Only markPoint (triangles under the X-axis) opens the annotation tooltip.
                 // Hovering markLine or anything else keeps the regular TimeSeries tooltip visible
                 // and clears any stale hovered annotation (mouseout is sometimes missed by ECharts).
-                if (annotations && params.componentType === 'markPoint' && params.data?.annotationIndex !== undefined) {
+                if (annotations && params.componentType === 'markPoint' && typeof params.data?.annotationIndex === 'number') {
                     const matchedAnnotation = annotations[params.data.annotationIndex] || null;
                     if (matchedAnnotation) {
                         setHoveredAnnotation(matchedAnnotation);
@@ -134,9 +172,12 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
                 }
                 setHoveredAnnotation(null);
             },
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             mouseout: (params)=>{
-                if (annotations && params.componentType === 'markPoint' && params.data?.annotationIndex !== undefined && annotations) {
+                if (params.componentType === 'series' && params.seriesType === 'scatter' && 'seriesId' in params && typeof params.seriesId === 'string' && params.seriesId.startsWith(EXEMPLAR_SERIES_ID_PREFIX)) {
+                    setHoveredExemplar(null);
+                    return;
+                }
+                if (annotations && params.componentType === 'markPoint' && typeof params.data?.annotationIndex === 'number' && annotations) {
                     // Only clear if the mouseout corresponds to the currently hovered annotation, so that
                     // a quick move from one markPoint to another isn't cancelled by a late mouseout event.
                     const leaving = annotations[params.data.annotationIndex] || null;
@@ -148,6 +189,7 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
                     // Cursor left the chart canvas — guarantee the annotation tooltip is dismissed.
                     setHoveredAnnotation(null);
                 }
+                setHoveredExemplar(null);
             }
         };
     }, [
@@ -155,43 +197,47 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
         onDataZoom
     ]);
     // Generate annotation series for ECharts markArea (range), markLine (point), and markPoint (markers under X-axis)
-    const annotationSeries = useMemo(()=>buildAnnotationSeries(annotations), [
-        annotations
+    const annotationYAxisIndex = Array.isArray(yAxis) ? yAxis.length : 1;
+    const annotationSeries = useMemo(()=>buildAnnotationSeries(annotations, annotationYAxisIndex), [
+        annotations,
+        annotationYAxisIndex
+    ]);
+    const preparedExemplarSeries = useMemo(()=>exemplars?.map(getExemplarSeries) ?? [], [
+        exemplars
+    ]);
+    const exemplarSeries = useMemo(()=>{
+        const visibleIds = new Set(seriesMapping.map((series)=>`${EXEMPLAR_SERIES_ID_PREFIX}${series.id}`));
+        return preparedExemplarSeries.filter((series)=>visibleIds.has(String(series.id)));
+    }, [
+        preparedExemplarSeries,
+        seriesMapping
     ]);
     const { noDataOption } = chartsTheme;
-    const option = useMemo(()=>{
-        // The "chart" `noDataVariant` is only used when the `timeSeries` is an
-        // empty array because a `null` value will throw an error.
-        if (data === null || data.length === 0 && noDataVariant === 'message') return noDataOption;
-        // Utilizes ECharts dataset so raw data is separate from series option style properties
-        // https://apache.github.io/echarts-handbook/en/concepts/dataset/
-        const dataset = [];
-        data.map((d, index)=>{
-            const values = d.values.map(([timestamp, value])=>{
-                const val = value === null ? '-' : value; // echarts use '-' to represent null data
-                return [
-                    timestamp,
-                    val
-                ];
-            });
-            dataset.push({
+    // Reuse the dataset when pinning a crosshair or updating annotations/axes.
+    const dataset = useMemo(()=>data?.map((series, index)=>({
                 id: index,
-                source: [
-                    ...values
-                ],
                 dimensions: [
                     'time',
                     'value'
-                ]
-            });
-        });
+                ],
+                // ECharts treats null as missing data; no per-point conversion/copy is needed.
+                source: series.values
+            })) ?? [], [
+        data
+    ]);
+    const option = useMemo(()=>{
+        // The "chart" `noDataVariant` is only used when the `timeSeries` is an
+        // empty array because a `null` value will throw an error.
+        if (data === null || data.length === 0 && noDataVariant === 'message') return noDataOption;
         const updatedSeriesMapping = enablePinning && pinnedCrosshair !== null ? [
             ...seriesMapping,
             pinnedCrosshair,
-            ...annotationSeries
+            ...annotationSeries,
+            ...exemplarSeries
         ] : [
             ...seriesMapping,
-            ...annotationSeries
+            ...annotationSeries,
+            ...exemplarSeries
         ];
         const option = {
             dataset: dataset,
@@ -209,7 +255,12 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
                 }
             },
             // If yAxis is already an array (multiple Y axes), use it directly; otherwise use getFormattedAxis
-            yAxis: Array.isArray(yAxis) ? yAxis : getFormattedAxis(yAxis, format),
+            yAxis: [
+                ...Array.isArray(yAxis) ? yAxis : getFormattedAxis(yAxis, format),
+                ...annotationSeries.length > 0 ? [
+                    ANNOTATION_Y_AXIS
+                ] : []
+            ],
             animation: false,
             tooltip: {
                 show: true,
@@ -243,8 +294,10 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
         return option;
     }, [
         data,
+        dataset,
         seriesMapping,
         annotationSeries,
+        exemplarSeries,
         timeScale,
         yAxis,
         format,
@@ -257,26 +310,30 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
         pinnedCrosshair,
         getTimezoneAwareAxisFormatter
     ]);
-    // Update adjacent charts so tooltip is unpinned when current chart is clicked.
-    useEffect(()=>{
-        // Only allow pinning one tooltip at a time, subsequent tooltip click unpins previous.
-        // Multiple tooltips can only be pinned if Ctrl or Cmd key is pressed while clicking.
-        const multipleTooltipsPinned = tooltipPinnedCoords !== null && lastTooltipPinnedCoords !== null;
-        if (multipleTooltipsPinned) {
-            if (!isEqual(lastTooltipPinnedCoords, tooltipPinnedCoords)) {
-                setTooltipPinnedCoords(null);
-                if (tooltipPinnedCoords !== null && pinnedCrosshair !== null) {
-                    setPinnedCrosshair(null);
-                }
-            }
-        }
-    // tooltipPinnedCoords CANNOT be in dep array or tooltip pinning breaks in the current chart's onClick
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [
+    // Only changes from another chart (or new series) can clear the local pin.
+    // A local click may update its coordinates without updating the shared pin.
+    const [previousPinState, setPreviousPinState] = useState({
         lastTooltipPinnedCoords,
         seriesMapping
-    ]);
+    });
+    if (previousPinState.lastTooltipPinnedCoords !== lastTooltipPinnedCoords || previousPinState.seriesMapping !== seriesMapping) {
+        setPreviousPinState({
+            lastTooltipPinnedCoords,
+            seriesMapping
+        });
+        if (tooltipPinnedCoords !== null && lastTooltipPinnedCoords !== null && !isEqual(lastTooltipPinnedCoords, tooltipPinnedCoords)) {
+            setTooltipPinnedCoords(null);
+            setPinnedCrosshair(null);
+        }
+        // A pinned exemplar tooltip is also unpinned when a tooltip is pinned in another chart,
+        // unless it is the one just pinned by this chart at these exact coordinates.
+        if (pinnedExemplarPos !== null && lastTooltipPinnedCoords !== null && !isEqual(lastTooltipPinnedCoords, pinnedExemplarPos)) {
+            setPinnedExemplar(null);
+            setPinnedExemplarPos(null);
+        }
+    }
     return /*#__PURE__*/ _jsxs(Box, {
+        ref: containerRef,
         style: {
             height
         },
@@ -285,6 +342,51 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
         //   e.preventDefault(); // Prevent the default behaviour when right clicked
         // }}
         onClick: (e)=>{
+            // Allows user to opt-in to multi tooltip pinning when Ctrl or Cmd key held down
+            const isControlKeyPressed = e.ctrlKey || e.metaKey;
+            if (isControlKeyPressed) {
+                e.preventDefault();
+            }
+            // If clicking while hovering an exemplar marker, toggle the exemplar tooltip pin
+            // instead of pinning the TimeChartTooltip. Pinning an exemplar tooltip unpins the
+            // pinned TimeChartTooltip, so only one tooltip stays pinned at a time unless
+            // Ctrl or Cmd is held down.
+            if (hoveredExemplar !== null && e.target instanceof HTMLCanvasElement) {
+                const pinnedPos = {
+                    page: {
+                        x: e.pageX,
+                        y: e.pageY
+                    },
+                    client: {
+                        x: e.clientX,
+                        y: e.clientY
+                    },
+                    plotCanvas: {
+                        x: e.nativeEvent.offsetX,
+                        y: e.nativeEvent.offsetY
+                    },
+                    target: e.target
+                };
+                const isUnpinClick = pinnedExemplar !== null && pinnedExemplar.exemplar === hoveredExemplar.exemplar;
+                // Compute the next state first and call the setters separately: updater functions
+                // may run more than once (e.g. StrictMode), so they must stay side-effect free.
+                setPinnedExemplar(isUnpinClick ? null : hoveredExemplar);
+                setPinnedExemplarPos(isUnpinClick ? null : pinnedPos);
+                if (!isUnpinClick && !isControlKeyPressed) {
+                    // Unpin the pinned TimeChartTooltip and let adjacent charts know a tooltip is
+                    // pinned at these coordinates, so only one tooltip is pinned at a time.
+                    setTooltipPinnedCoords(null);
+                    setPinnedCrosshair(null);
+                    setLastTooltipPinnedCoords(pinnedPos);
+                }
+                return;
+            }
+            // Unpin a pinned exemplar tooltip when clicking elsewhere on the chart canvas,
+            // so the same click can pin the TimeChartTooltip instead. Ctrl or Cmd keeps both.
+            if (pinnedExemplar !== null && !isControlKeyPressed && e.target instanceof HTMLCanvasElement) {
+                setPinnedExemplar(null);
+                setPinnedExemplarPos(null);
+            }
             // If clicking while hovering an annotation, toggle the annotation tooltip pin
             // instead of pinning the TimeChartTooltip, so pinned TimeChartTooltip is preserved.
             if (hoveredAnnotation !== null && e.target instanceof HTMLCanvasElement) {
@@ -313,11 +415,6 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
                 });
                 return;
             }
-            // Allows user to opt-in to multi tooltip pinning when Ctrl or Cmd key held down
-            const isControlKeyPressed = e.ctrlKey || e.metaKey;
-            if (isControlKeyPressed) {
-                e.preventDefault();
-            }
             // Determine where on chart canvas to plot pinned crosshair as markLine.
             const pointInGrid = getPointInGrid(e.nativeEvent.offsetX, e.nativeEvent.offsetY, chartRef.current);
             if (pointInGrid === null) {
@@ -388,6 +485,28 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
                 return;
             }
             const { clientX } = e;
+            // ECharts does not reliably emit mouseout when the cursor moves off an exemplar marker
+            // onto the plain plot area, which would keep the exemplar tooltip stuck on screen and
+            // hide the regular TimeChartTooltip. Clear the hovered exemplar as soon as the cursor
+            // is no longer within its marker, so the next hover can take over.
+            setHoveredExemplar((current)=>{
+                if (current === null || chartRef.current === undefined) return current;
+                let markerPixel;
+                try {
+                    // Use the plotted value so negated markers (negativeY) are tracked correctly.
+                    markerPixel = chartRef.current.convertToPixel('grid', [
+                        current.exemplar.timestamp,
+                        current.plottedValue
+                    ]);
+                } catch  {
+                    // Coordinates cannot be resolved (e.g. grid not ready yet), keep the current hover.
+                    return current;
+                }
+                const [markerPixelX, markerPixelY] = markerPixel ?? [];
+                if (markerPixelX === undefined || markerPixelY === undefined) return current;
+                const distance = Math.hypot(e.nativeEvent.offsetX - markerPixelX, e.nativeEvent.offsetY - markerPixelY);
+                return distance <= EXEMPLAR_HOVER_RADIUS ? current : null;
+            });
             if (isDragging) {
                 const deltaX = clientX - startX;
                 if (deltaX > 0) {
@@ -405,8 +524,9 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
             if (tooltipPinnedCoords === null) {
                 setShowTooltip(false);
             }
-            // Defensive: clear hovered annotation in case ECharts missed a mouseout event.
+            // Defensive: clear hovered annotation and exemplar in case ECharts missed a mouseout event.
             setHoveredAnnotation(null);
+            setHoveredExemplar(null);
             if (chartRef.current !== undefined) {
                 clearHighlightedSeries(chartRef.current);
             }
@@ -429,7 +549,7 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
             }
         },
         children: [
-            showTooltip === true && (tooltipPinnedCoords !== null || hoveredAnnotation === null) && option.tooltip?.showContent === false && tooltipConfig.hidden !== true && /*#__PURE__*/ _jsx(TimeChartTooltip, {
+            showTooltip === true && (tooltipPinnedCoords !== null || pinnedExemplar === null && hoveredAnnotation === null && hoveredExemplar === null) && option.tooltip?.showContent === false && tooltipConfig.hidden !== true && /*#__PURE__*/ _jsx(TimeChartTooltip, {
                 containerId: chartsTheme.tooltipPortalContainerId,
                 chartRef: chartRef,
                 data: data,
@@ -446,6 +566,18 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
                     setPinnedCrosshair(null);
                 }
             }),
+            (pinnedExemplar !== null || hoveredExemplar !== null && tooltipPinnedCoords === null) && /*#__PURE__*/ _jsx(ExemplarMetadataTooltip, {
+                exemplar: (pinnedExemplar ?? hoveredExemplar).exemplar,
+                seriesLabels: (pinnedExemplar ?? hoveredExemplar).seriesLabels,
+                containerId: chartsTheme.tooltipPortalContainerId,
+                format: format,
+                pinnedPos: pinnedExemplar !== null ? pinnedExemplarPos : null,
+                enablePinning: isPinningEnabled,
+                onUnpinClick: ()=>{
+                    setPinnedExemplar(null);
+                    setPinnedExemplarPos(null);
+                }
+            }),
             (pinnedAnnotation ?? hoveredAnnotation) && /*#__PURE__*/ _jsx(AnnotationTooltip, {
                 annotation: pinnedAnnotation ?? hoveredAnnotation,
                 containerId: chartsTheme.tooltipPortalContainerId,
@@ -458,10 +590,7 @@ export const TimeSeriesChartBase = /*#__PURE__*/ forwardRef(function TimeChart({
                 }
             }),
             /*#__PURE__*/ _jsx(EChart, {
-                sx: {
-                    width: '100%',
-                    height: '100%'
-                },
+                sx: CHART_SX,
                 option: option,
                 theme: chartsTheme.echartsTheme,
                 onEvents: handleEvents,