diff --git a/pages/03-core/boost.page.tsx b/pages/03-core/boost.page.tsx
index 88ad1821..9c9b84f8 100644
--- a/pages/03-core/boost.page.tsx
+++ b/pages/03-core/boost.page.tsx
@@ -35,6 +35,7 @@ export default function () {
),
},
+ "hoverDebounce",
]}
/>
}
@@ -56,7 +57,7 @@ function Component({ boostEnabled }: { boostEnabled: boolean }) {
const { chartProps } = useChartSettings({ boost: true });
return (
}>
+ }>
}
>
}
+ settings={
}
>
}
diff --git a/pages/03-core/heatmap.page.tsx b/pages/03-core/heatmap.page.tsx
index 22af22f3..0892d837 100644
--- a/pages/03-core/heatmap.page.tsx
+++ b/pages/03-core/heatmap.page.tsx
@@ -1,7 +1,12 @@
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
+import { ComponentType } from "react";
+
+import { CoreChartProps } from "../../lib/components/core/interfaces";
+import { InternalHoverProps } from "../../lib/components/core/internal-interfaces";
import CoreChart from "../../lib/components/internal-do-not-use/core-chart";
+import { PageSettingsForm, useChartSettings } from "../common/page-settings";
import { Page } from "../common/templates";
import { useHighcharts } from "../common/use-highcharts";
import pseudoRandom from "../utils/pseudo-random";
@@ -39,13 +44,21 @@ function generateHeatmapData() {
const { series, instances } = generateHeatmapData();
+const HoverCoreChart = CoreChart as ComponentType;
+
export default function () {
const highcharts = useHighcharts({ heatmap: true });
+ const { chartProps } = useChartSettings();
return (
-
- }
+ >
+ ({ more: true });
- const commonProps = omit(chartProps.cartesian, ["ref"]);
+ const commonProps = chartProps.core;
const scatterChartRef = useRef(null) as React.MutableRefObject;
const getScatterChart = () => scatterChartRef.current!;
const navigatorChartRef = useRef(null) as React.MutableRefObject;
diff --git a/pages/03-core/solidgauge.page.tsx b/pages/03-core/solidgauge.page.tsx
index a34963f6..9f24a6ca 100644
--- a/pages/03-core/solidgauge.page.tsx
+++ b/pages/03-core/solidgauge.page.tsx
@@ -1,8 +1,6 @@
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
-import { omit } from "lodash";
-
import CoreChart from "../../lib/components/internal-do-not-use/core-chart";
import { PageSettingsForm, useChartSettings } from "../common/page-settings";
import { Page } from "../common/templates";
@@ -28,12 +26,19 @@ export default function () {
subtitle="This page demonstrates the use of solid gauge charts for displaying single-value metrics."
settings={
}
>
(DEFAULT_SETTINGS);
@@ -92,7 +94,7 @@ export function useChartSettings & InternalZoomProps & { ref: React.Ref };
pie: Omit & { ref: React.Ref };
- core: Omit & InternalZoomProps;
+ core: Omit & InternalZoomProps & InternalHoverProps;
};
isEmpty: boolean;
} {
@@ -119,6 +121,7 @@ export function useChartSettings) => {
setUrlParams(partial as Partial>);
@@ -206,6 +209,7 @@ export function useChartSettings 0 ? settings.hoverDebounce : undefined,
},
},
isEmpty: settings.emptySeries || settings.seriesLoading || settings.seriesError,
@@ -517,6 +521,16 @@ export function PageSettingsForm({
Hide zoom controls
);
+ case "hoverDebounce":
+ return (
+
+ setSettings({ hoverDebounce: detail.value ? parseInt(detail.value) : 0 })}
+ />
+
+ );
case "useFallback":
return (
({
+ header: () => `${point?.series.name} ${point?.x}`,
+ body: () => "Body",
+});
+
+const getLegendTooltipContent: CoreChartProps.GetLegendTooltipContent = ({ legendItem }) => ({
+ header: {legendItem.name}
,
+ body: <>Body>,
+});
+
+const dimmedLegendItems = () =>
+ createChartWrapper()
+ .findLegend()!
+ .findAll(`.${legendTestClasses["dimmed-item"]}`)
+ .map((w) => w.getElement().textContent);
+
+function mockPointCoordinates() {
+ hc.getChart().series.forEach((s, sIndex) => {
+ s.points.forEach((p) => {
+ p.plotX = p.index;
+ p.plotY = 1 + sIndex;
+ });
+ });
+}
+
+const highlightMarkers = () => createChartWrapper().findAllByClassName(testClasses["highlight-marker"]).length;
+const selectedMarkers = () => createChartWrapper().findAllByClassName(testClasses["highlight-marker-selected"]).length;
+const selectedMarkerFill = () =>
+ createChartWrapper().findByClassName(testClasses["highlight-marker-selected"])?.getElement().getAttribute("fill") ??
+ null;
+
+const tooltipHeader = () => createChartWrapper().findTooltip()?.findHeader()?.getElement().textContent ?? null;
+const legendTooltip = () => createChartWrapper().findLegend()!.findItemTooltip();
+const pressEscape = () => act(() => fireEvent.keyDown(document.body, { key: "Escape", keyCode: 27 }));
+const focusLegendItem = (index: number) => act(() => createChartWrapper().findLegend()!.findItems()[index].focus());
+
+beforeEach(() => {
+ vi.useFakeTimers();
+});
+
+afterEach(() => {
+ vi.useRealTimers();
+});
+
+describe("CoreChart: hover debounce", () => {
+ test("highlights the hovered series and cursor at once, and dims the others and shows the tooltip once the delay passes", () => {
+ const onHighlight = vi.fn();
+ renderChart({ highcharts, options: { series }, hoverDebounce: 100, getTooltipContent, onHighlight });
+
+ mockPointCoordinates();
+ act(() => hc.highlightChartPoint(0, 1));
+ act(() => vi.advanceTimersByTime(99));
+
+ expect(hc.getChartSeries(0).state).toBe("hover");
+ expect(hc.getChartSeries(1).state).toBe("");
+ expect(highlightMarkers()).toBe(2);
+ expect(selectedMarkers()).toBe(1);
+ expect(dimmedLegendItems()).toEqual([]);
+ expect(tooltipHeader()).toBe(null);
+ expect(onHighlight).toHaveBeenCalledTimes(1);
+ expect(onHighlight.mock.calls[0][0].detail.point).toBe(hc.getChartPoint(0, 1));
+
+ act(() => hc.highlightChartPoint(0, 1));
+ act(() => vi.advanceTimersByTime(1));
+
+ expect(tooltipHeader()).toBe("L1 1");
+ expect(hc.getChartSeries(1).state).toBe("inactive");
+ expect(dimmedLegendItems()).toEqual(["L2"]);
+ expect(onHighlight).toHaveBeenCalledTimes(1);
+ });
+
+ test("drops a pending hover once the pointer leaves it, and restores the series and cursor", () => {
+ const onClearHighlight = vi.fn();
+ renderChart({ highcharts, options: { series }, hoverDebounce: 100, getTooltipContent, onClearHighlight });
+
+ mockPointCoordinates();
+ act(() => hc.highlightChartPoint(0, 1));
+ act(() => vi.advanceTimersByTime(99));
+ act(() => hc.leaveChartPoint(0, 1));
+ act(() => vi.advanceTimersByTime(1));
+
+ expect(tooltipHeader()).toBe(null);
+ expect(dimmedLegendItems()).toEqual([]);
+
+ act(() => vi.advanceTimersByTime(200));
+
+ expect(highlightMarkers()).toBe(0);
+ expect(hc.getChartSeries(0).state).toBe("");
+ expect(hc.getChartSeries(1).state).toBe("");
+ expect(onClearHighlight).toHaveBeenCalled();
+ });
+
+ test("swaps the highlighted series at once once dimmed and applies the last target once it settles", () => {
+ const onHighlight = vi.fn();
+ renderChart({ highcharts, options: { series }, hoverDebounce: 100, getTooltipContent, onHighlight });
+
+ act(() => hc.highlightChartPoint(0, 1));
+ act(() => vi.advanceTimersByTime(100));
+ act(() => hc.highlightChartPoint(1, 1));
+ act(() => vi.advanceTimersByTime(60));
+ act(() => hc.highlightChartPoint(1, 2));
+ act(() => vi.advanceTimersByTime(60));
+
+ expect(tooltipHeader()).toBe("L1 1");
+ expect(hc.getChartSeries(0).state).toBe("inactive");
+ expect(dimmedLegendItems()).toEqual(["L1"]);
+
+ act(() => vi.advanceTimersByTime(40));
+
+ expect(tooltipHeader()).toBe("L2 2");
+ expect(onHighlight).toHaveBeenCalledTimes(3);
+ });
+
+ test.each([
+ {
+ type: "column",
+ series: [
+ { type: "column", name: "C1", data: [1, 2] },
+ { type: "column", name: "C2", data: [3, 4] },
+ ],
+ first: [0, 0],
+ second: [1, 1],
+ dimmedAtOnce: ["C2"],
+ },
+ {
+ type: "pie",
+ series: [
+ {
+ type: "pie",
+ name: "P",
+ data: [
+ { name: "A", y: 1 },
+ { name: "B", y: 2 },
+ ],
+ },
+ ],
+ first: [0, 0],
+ second: [0, 1],
+ dimmedAtOnce: [],
+ },
+ ] as const)(
+ "highlights a hovered $type point at once, dims the others at once for columns, and swaps it at once when dimmed",
+ ({ series, first, second, dimmedAtOnce }) => {
+ renderChart({ highcharts, options: { series: series as Highcharts.SeriesOptionsType[] }, hoverDebounce: 100 });
+
+ act(() => hc.highlightChartPoint(...first));
+
+ expect(hc.getChartPoint(...first).state).toBe("hover");
+ expect(hc.getChartPoint(...second).state === "inactive").toBe(dimmedAtOnce.length > 0);
+ expect(dimmedLegendItems()).toEqual(dimmedAtOnce);
+
+ act(() => vi.advanceTimersByTime(100));
+
+ expect(hc.getChartPoint(...second).state).toBe("inactive");
+
+ act(() => hc.highlightChartPoint(...second));
+
+ expect(hc.getChartPoint(...second).state).toBe("hover");
+ expect(hc.getChartPoint(...first).state).toBe("inactive");
+ },
+ );
+
+ test("uses a 150ms delay when hoverDebounce=true and ignores tooltip.debounce", () => {
+ renderChart({
+ highcharts,
+ options: { series },
+ hoverDebounce: true,
+ tooltip: { debounce: 500 },
+ getTooltipContent,
+ });
+
+ act(() => hc.highlightChartPoint(0, 1));
+ act(() => vi.advanceTimersByTime(149));
+ expect(tooltipHeader()).toBe(null);
+
+ act(() => hc.highlightChartPoint(0, 1));
+ act(() => vi.advanceTimersByTime(1));
+ expect(tooltipHeader()).toBe("L1 1");
+ });
+
+ test("applies the same effects at once with a zero delay", () => {
+ renderChart({ highcharts, options: { series }, hoverDebounce: 0, getLegendTooltipContent });
+
+ hoverLegendItem(0);
+
+ expect(hc.getChartSeries(1).state).toBe("inactive");
+ expect(dimmedLegendItems()).toEqual(["L2"]);
+
+ act(() => vi.advanceTimersByTime(1));
+
+ expect(legendTooltip()).not.toBe(null);
+ });
+
+ test("drops a pending target when the pointer enters the tooltip", () => {
+ renderChart({ highcharts, options: { series }, hoverDebounce: 100, getTooltipContent });
+
+ act(() => hc.highlightChartPoint(0, 1));
+ act(() => vi.advanceTimersByTime(100));
+ act(() => hc.highlightChartPoint(1, 2));
+ act(() => {
+ fireEvent.mouseEnter(createChartWrapper().findTooltip()!.getElement());
+ });
+ act(() => vi.advanceTimersByTime(200));
+
+ expect(tooltipHeader()).toBe("L1 1");
+ expect(dimmedLegendItems()).toEqual(["L2"]);
+ });
+
+ test("pins the tooltip on click without waiting for the delay", () => {
+ const data = [
+ { name: "P1", y: 10 },
+ { name: "P2", y: 30 },
+ ];
+ renderChart({
+ highcharts,
+ options: { series: [{ type: "pie", name: "Pie", data }] },
+ hoverDebounce: 100,
+ getTooltipContent: ({ point }) => ({ header: () => `${point?.name}`, body: () => "Body" }),
+ });
+
+ act(() => hc.highlightChartPoint(0, 1));
+ act(() => hc.clickChartPoint(0, 1));
+
+ expect(tooltipHeader()).toBe("P2");
+ expect(createChartWrapper().findTooltip()!.findDismissButton()).not.toBe(null);
+ });
+
+ test("skips a pending point that is no longer visible and clears its cursor", () => {
+ renderChart({ highcharts, options: { series }, hoverDebounce: 100, getTooltipContent });
+
+ mockPointCoordinates();
+ act(() => hc.highlightChartPoint(0, 1));
+ act(() => {
+ hc.getChartPoint(0, 1).visible = false;
+ });
+ act(() => vi.advanceTimersByTime(200));
+
+ expect(tooltipHeader()).toBe(null);
+ expect(highlightMarkers()).toBe(0);
+ expect(hc.getChartSeries(0).state).toBe("");
+ });
+
+ test.each([
+ {
+ name: "the chart receives keyboard focus",
+ action: () => act(() => createChartWrapper().findApplication()!.focus()),
+ },
+ { name: "Escape is pressed", action: pressEscape },
+ { name: "series visibility changes", action: () => toggleLegendItem(1) },
+ ])("drops a pending pointer hover when $name", ({ action }) => {
+ const onHighlight = vi.fn();
+ renderStatefulChart({
+ highcharts,
+ options: { series },
+ hoverDebounce: 100,
+ visibleItems: ["L1", "L2"],
+ getTooltipContent,
+ onHighlight,
+ });
+
+ act(() => hc.highlightChartPoint(0, 1));
+ action();
+ act(() => vi.advanceTimersByTime(200));
+
+ expect(tooltipHeader()).toBe(null);
+ expect(dimmedLegendItems()).toEqual([]);
+ expect(onHighlight).toHaveBeenCalledTimes(1);
+ });
+
+ test("drops a pending pointer hover when a zoom selection starts", () => {
+ renderZoomChart({ zoom: { enabled: true }, hoverDebounce: 100, getTooltipContent });
+
+ act(() => hc.highlightChartPoint(0, 1));
+ enterZoomMode();
+ act(() => vi.advanceTimersByTime(200));
+
+ expect(tooltipHeader()).toBe(null);
+ expect(dimmedLegendItems()).toEqual([]);
+ });
+
+ describe("API", () => {
+ test("lights the series at once and dims the others after the delay", () => {
+ let api: null | CoreChartProps.ChartAPI = null;
+ renderChart({ highcharts, options: { series }, hoverDebounce: 100, callback: (chartApi) => (api = chartApi) });
+
+ act(() => api!.highlightItems(["L1"]));
+
+ expect(hc.getChartSeries(0).state).toBe("hover");
+ expect(hc.getChartSeries(1).state).toBe("");
+ expect(dimmedLegendItems()).toEqual([]);
+
+ act(() => vi.advanceTimersByTime(100));
+
+ expect(hc.getChartSeries(1).state).toBe("inactive");
+ expect(dimmedLegendItems()).toEqual(["L2"]);
+
+ act(() => api!.clearChartHighlight());
+
+ expect(hc.getChartSeries(1).state).toBe("");
+ expect(dimmedLegendItems()).toEqual([]);
+ });
+
+ test("replaces a pending pointer hover and its cursor", () => {
+ let api: null | CoreChartProps.ChartAPI = null;
+ renderChart({
+ highcharts,
+ options: { series },
+ hoverDebounce: 100,
+ getTooltipContent,
+ callback: (chartApi) => (api = chartApi),
+ });
+
+ mockPointCoordinates();
+ act(() => hc.highlightChartPoint(0, 1));
+ act(() => api!.highlightChartPoint(hc.getChartPoint(1, 2)));
+
+ expect(hc.getChartSeries(1).state).toBe("hover");
+ expect(selectedMarkerFill()).toBe(hc.getChartSeries(1).color);
+
+ act(() => vi.advanceTimersByTime(200));
+
+ expect(tooltipHeader()).toBe("L2 2");
+ });
+ });
+
+ describe("legend", () => {
+ test("highlights a hovered item's series at once, and dims the others and shows the item tooltip once the delay passes", () => {
+ const onLegendItemHighlight = vi.fn();
+ renderChart({
+ highcharts,
+ options: { series },
+ hoverDebounce: 100,
+ getLegendTooltipContent,
+ onLegendItemHighlight,
+ });
+
+ hoverLegendItem(0);
+ act(() => vi.advanceTimersByTime(99));
+
+ expect(hc.getChartSeries(0).state).toBe("hover");
+ expect(hc.getChartSeries(1).state).toBe("");
+ expect(dimmedLegendItems()).toEqual([]);
+ expect(legendTooltip()).toBe(null);
+ expect(onLegendItemHighlight).toHaveBeenCalledTimes(1);
+
+ act(() => vi.advanceTimersByTime(1));
+
+ expect(hc.getChartSeries(0).state).toBe("hover");
+ expect(hc.getChartSeries(1).state).toBe("inactive");
+ expect(dimmedLegendItems()).toEqual(["L2"]);
+ expect(legendTooltip()).not.toBe(null);
+ expect(onLegendItemHighlight).toHaveBeenCalledTimes(1);
+ });
+
+ test("drops a pending item highlight as soon as the pointer leaves it", () => {
+ renderChart({ highcharts, options: { series }, hoverDebounce: 100 });
+
+ hoverLegendItem(0);
+ act(() => vi.advanceTimersByTime(90));
+ leaveLegendItem(0);
+ act(() => vi.advanceTimersByTime(15));
+
+ expect(dimmedLegendItems()).toEqual([]);
+
+ act(() => vi.advanceTimersByTime(500));
+
+ expect(hc.getChartSeries(0).state).toBe("");
+ });
+
+ test("drops a pending item highlight when the item is toggled", () => {
+ renderStatefulChart({ highcharts, options: { series }, hoverDebounce: 100, visibleItems: ["L1", "L2"] });
+
+ hoverLegendItem(0);
+ toggleLegendItem(0);
+ act(() => vi.advanceTimersByTime(200));
+
+ expect(hc.getChartSeries(1).state).toBe("");
+ });
+
+ test("lets Escape cancel a pending item highlight and tooltip, and clears the highlight it reported", () => {
+ const onClearHighlight = vi.fn();
+ renderChart({ highcharts, options: { series }, hoverDebounce: 100, getLegendTooltipContent, onClearHighlight });
+
+ hoverLegendItem(0);
+ act(() => vi.advanceTimersByTime(50));
+ pressEscape();
+ act(() => vi.advanceTimersByTime(200));
+
+ expect(legendTooltip()).toBe(null);
+ expect(hc.getChartSeries(0).state).toBe("");
+ expect(dimmedLegendItems()).toEqual([]);
+ expect(onClearHighlight).toHaveBeenCalledTimes(1);
+ });
+
+ test("highlights a focused item at once, replacing pending pointer and legend hovers", () => {
+ renderChart({ highcharts, options: { series }, hoverDebounce: 100, getTooltipContent });
+
+ act(() => hc.highlightChartPoint(0, 1));
+ hoverLegendItem(0);
+ focusLegendItem(1);
+
+ expect(dimmedLegendItems()).toEqual(["L1"]);
+
+ act(() => vi.advanceTimersByTime(200));
+
+ expect(dimmedLegendItems()).toEqual(["L1"]);
+ expect(tooltipHeader()).toBe(null);
+ });
+
+ test("keeps a new item highlight when the plot hover is lost", () => {
+ renderChart({ highcharts, options: { series }, hoverDebounce: 100, getTooltipContent });
+
+ act(() => hc.highlightChartPoint(0, 1));
+ act(() => hc.leaveChartPoint(0, 1));
+ hoverLegendItem(1);
+ act(() => vi.advanceTimersByTime(200));
+
+ expect(dimmedLegendItems()).toEqual(["L1"]);
+ });
+
+ test("does not reopen the item tooltip after the delay changes and the pointer leaves", () => {
+ const { rerender } = renderChart({
+ highcharts,
+ options: { series },
+ hoverDebounce: 300,
+ getLegendTooltipContent,
+ });
+
+ hoverLegendItem(0);
+ rerender({ highcharts, options: { series }, hoverDebounce: 100, getLegendTooltipContent });
+ leaveLegendItem(0);
+ act(() => vi.advanceTimersByTime(500));
+
+ expect(legendTooltip()).toBe(null);
+ });
+ });
+});
diff --git a/src/core/__tests__/common.tsx b/src/core/__tests__/common.tsx
index c8405afe..68dc7e52 100644
--- a/src/core/__tests__/common.tsx
+++ b/src/core/__tests__/common.tsx
@@ -10,7 +10,7 @@ import { ButtonWrapper } from "@cloudscape-design/components/test-utils/dom";
import "@cloudscape-design/components/test-utils/dom";
import { CoreChartProps } from "../../../lib/components/core/interfaces";
-import { InternalZoomProps } from "../../../lib/components/core/internal-interfaces";
+import { InternalHoverProps, InternalZoomProps } from "../../../lib/components/core/internal-interfaces";
import testClasses from "../../../lib/components/core/test-classes/styles.selectors";
import { fireNonCancelableEvent } from "../../../lib/components/internal/events";
import { TestI18nProvider } from "../../../lib/components/internal/utils/test-i18n-provider";
@@ -31,9 +31,9 @@ export class ExtendedTestWrapper extends CoreChartWrapper {
}
// The core chart accepts the internal zoom properties, which are not part of its public interface yet.
-const CoreChartWithZoom = CoreChart as React.ComponentType;
+const CoreChartWithZoom = CoreChart as React.ComponentType;
-export function StatefulChart(props: CoreChartProps & InternalZoomProps) {
+export function StatefulChart(props: CoreChartProps & InternalZoomProps & InternalHoverProps) {
const [visibleItems, setVisibleItems] = useState(props.visibleItems ?? []);
const [zoomRange, setZoomRange] = useState(props.zoomRange);
return (
@@ -55,16 +55,17 @@ export function StatefulChart(props: CoreChartProps & InternalZoomProps) {
}
export type CoreChartTestProps = Partial &
- InternalZoomProps & {
+ InternalZoomProps &
+ InternalHoverProps & {
onLegendItemHighlight?: () => void;
i18nProvider?: Record>;
};
export function renderChart(
{ i18nProvider, ...props }: CoreChartTestProps,
- Component: React.ComponentType = CoreChartWithZoom,
+ Component: React.ComponentType = CoreChartWithZoom,
) {
- const ComponentWrapper = (props: CoreChartProps & InternalZoomProps) => {
+ const ComponentWrapper = (props: CoreChartProps & InternalZoomProps & InternalHoverProps) => {
return i18nProvider ? (
diff --git a/src/core/chart-api/chart-extra-context.tsx b/src/core/chart-api/chart-extra-context.tsx
index 47d5e053..c9a85232 100644
--- a/src/core/chart-api/chart-extra-context.tsx
+++ b/src/core/chart-api/chart-extra-context.tsx
@@ -34,6 +34,8 @@ export namespace ChartExtraContext {
labels: ChartLabels;
getItemOptions?: CoreChartProps.GetItemOptions;
zoomEnabled: boolean;
+ hoverDelay: number;
+ hoverDebounceEnabled: boolean;
}
export interface Handlers {
@@ -68,6 +70,8 @@ export function createChartContext(): ChartExtraContext {
keyboardNavigationEnabled: false,
labels: {},
zoomEnabled: false,
+ hoverDelay: -1,
+ hoverDebounceEnabled: false,
},
handlers: {},
state: {},
diff --git a/src/core/chart-api/chart-extra-highlight.ts b/src/core/chart-api/chart-extra-highlight.ts
index 6abf89a7..49135900 100644
--- a/src/core/chart-api/chart-extra-highlight.ts
+++ b/src/core/chart-api/chart-extra-highlight.ts
@@ -8,6 +8,7 @@ import {
getChartSeries,
getLinkedSeries,
getMasterSeries,
+ getMasterSeriesOf,
getSeriesData,
SafeChart,
SafeSeries,
@@ -32,6 +33,8 @@ export class ChartExtraHighlight {
// The recover is necessary if the chart was re-rendered while the highlighting is set. For example,
// when triggered a state update from the consumer-provided tooltip footer action.
private seriesState = new Map();
+ private previewState = new Map();
+ private pointPreviewState = new Map>();
private pointState = new Map>();
private columnStatesSynced = false;
@@ -43,6 +46,7 @@ export class ChartExtraHighlight {
// The method highlights specified series or points (by id). It is used when hovering over the legend items.
public highlightChartItems = (itemIds: readonly string[]) => {
+ this.discardPreview();
const itemIdsSet = new Set(itemIds);
for (const s of getChartSeries(this.context.chart())) {
// In pie charts it is the points, not series, that are shown in the legend, and can be highlighted.
@@ -55,7 +59,8 @@ export class ChartExtraHighlight {
} else {
const seriesActive = itemIdsSet.has(getSeriesId(s));
const masterSeriesActive = s.linkedParent ? itemIdsSet.has(getSeriesId(s.linkedParent)) : false;
- this.setSeriesState(s, seriesActive || masterSeriesActive ? "" : "inactive");
+ const activeState = this.context.settings.hoverDebounceEnabled ? "hover" : "";
+ this.setSeriesState(s, seriesActive || masterSeriesActive ? activeState : "inactive");
}
}
setPlotLinesState(this.context.chart(), (lineId) => itemIdsSet.has(lineId));
@@ -65,6 +70,7 @@ export class ChartExtraHighlight {
// do not have IDs, so we match points and series by their references instead. This is used to control
// highlight state when chart elements are hovered or focused.
public highlightChartGroup = (points: readonly Highcharts.Point[]) => {
+ this.discardPreview();
const includedPoints = new Set();
const includedSeries = new Set();
const includedSeriesIds = new Set();
@@ -92,6 +98,7 @@ export class ChartExtraHighlight {
// This method is similar to the above, but it takes a single point. This is used for point highlighting
// in cartesian charts, and for pie chart segments.
public highlightChartPoint = (point: Highcharts.Point) => {
+ this.discardPreview();
const masterSeries = getMasterSeries(point);
const linkedSeries = new Set(getLinkedSeries(point));
for (const s of getChartSeries(this.context.chart())) {
@@ -116,8 +123,149 @@ export class ChartExtraHighlight {
setPlotLinesState(this.context.chart(), (lineId) => lineId === getSeriesId(masterSeries));
};
+ public previewChartPoint = (point: Highcharts.Point) => {
+ const linkedSeries = new Set(getLinkedSeries(point));
+ return this.previewStates(
+ (s) => (linkedSeries.has(s) ? "hover" : null),
+ (p) => (p === point ? "hover" : null),
+ ["pie", "column"],
+ point.series.type === "column",
+ );
+ };
+
+ public previewChartGroup = (group: readonly Highcharts.Point[]) => {
+ const groupPoints = new Set(group);
+ const groupSeriesIds = new Set(group.map((p) => getSeriesId(getMasterSeries(p))));
+ return this.previewStates(
+ (s) => (groupSeriesIds.has(getSeriesId(getMasterSeriesOf(s))) ? "" : null),
+ (p) => (groupPoints.has(p) ? "" : null),
+ ["column"],
+ group.some((p) => p.series.type === "column"),
+ );
+ };
+
+ public previewChartItems = (itemIds: readonly string[]) => {
+ return this.previewStates(
+ (s) => (itemIds.includes(getSeriesId(getMasterSeriesOf(s))) ? "hover" : null),
+ (p) => (itemIds.includes(getPointId(p)) ? "hover" : null),
+ ["pie"],
+ getChartSeries(this.context.chart()).some(
+ (s) => s.type === "column" && itemIds.includes(getSeriesId(getMasterSeriesOf(s))),
+ ),
+ );
+ };
+
+ private previewStates(
+ getSeriesTargetState: (series: SafeSeries) => null | "" | "hover",
+ getPointTargetState: (point: Highcharts.Point) => null | "" | "hover",
+ pointSeriesTypes: readonly string[],
+ dimAtOnce: boolean,
+ ) {
+ const dimmed = dimAtOnce || this.isDimmed();
+ const getNonTargetState = (appliedState: "" | State) =>
+ dimmed ? "inactive" : appliedState === "hover" ? "" : appliedState;
+ const hoveredPoints: Highcharts.Point[] = [];
+ for (const s of getChartSeries(this.context.chart())) {
+ if (s.type !== "pie") {
+ this.setSeriesPreviewState(s, getSeriesTargetState(s) ?? getNonTargetState(this.getSeriesState(s)));
+ }
+ if (pointSeriesTypes.includes(s.type)) {
+ for (const p of getSeriesData(s)) {
+ const state = getPointTargetState(p) ?? getNonTargetState(this.getPointState(p));
+ if (state === "hover") {
+ hoveredPoints.push(p);
+ } else {
+ this.setPointPreviewState(p, state);
+ }
+ }
+ }
+ }
+ hoveredPoints.forEach((p) => this.setPointPreviewState(p, "hover"));
+ return dimmed;
+ }
+
+ public cancelPreview = () => {
+ if (this.previewState.size === 0 && this.pointPreviewState.size === 0) {
+ return;
+ }
+ const previewedSeries = this.previewState;
+ const previewedPoints = this.pointPreviewState;
+ this.discardPreview();
+ const hoveredPoints: Highcharts.Point[] = [];
+ for (const s of getChartSeries(this.context.chart())) {
+ if (previewedSeries.has(getSeriesId(s))) {
+ this.applySeriesState(s, this.getSeriesState(s));
+ }
+ const previewedSeriesPoints = previewedPoints.get(getSeriesId(s));
+ for (const p of previewedSeriesPoints ? getSeriesData(s) : []) {
+ if (previewedSeriesPoints?.has(this.getPointKey(p))) {
+ const state = this.getPointState(p);
+ if (state === "hover") {
+ hoveredPoints.push(p);
+ } else {
+ this.applyPointState(p, state);
+ }
+ }
+ }
+ }
+ hoveredPoints.forEach((p) => this.applyPointState(p, "hover"));
+ };
+
+ private discardPreview() {
+ this.previewState = new Map();
+ this.pointPreviewState = new Map();
+ }
+
+ private isDimmed() {
+ return (
+ [...this.seriesState.values()].includes("inactive") ||
+ [...this.pointState.values()].some((states) => [...states.values()].includes("inactive"))
+ );
+ }
+
+ private getSeriesState(series: SafeSeries) {
+ return this.seriesState.get(getSeriesId(series)) ?? "";
+ }
+
+ private getPointState(point: Highcharts.Point) {
+ return this.pointState.get(getSeriesId(point.series))?.get(this.getPointKey(point)) ?? "";
+ }
+
+ private withInstantUndim(series: { options: object }, state: string, setState: () => void) {
+ if (this.context.settings.hoverDebounceEnabled) {
+ applyWithInstantUndim(series, state, setState);
+ } else {
+ setState();
+ }
+ }
+
+ private setSeriesPreviewState(series: SafeSeries, state: "" | Highcharts.SeriesStateValue) {
+ this.previewState.set(getSeriesId(series), state);
+ this.applySeriesState(series, state);
+ }
+
+ private setPointPreviewState(point: Highcharts.Point, state: "" | Highcharts.PointStateValue) {
+ const seriesPoints = this.pointPreviewState.get(getSeriesId(point.series)) ?? new Map();
+ seriesPoints.set(this.getPointKey(point), state);
+ this.pointPreviewState.set(getSeriesId(point.series), seriesPoints);
+ this.applyPointState(point, state, point.series.type !== "column" || !this.columnStatesSynced);
+ }
+
+ private applySeriesState(series: SafeSeries, state: "" | Highcharts.SeriesStateValue) {
+ (series.setState as SeriesSetStateWithLock)[SET_STATE_LOCK] = false;
+ this.withInstantUndim(series, state, () => series.setState(state, false));
+ (series.setState as SeriesSetStateWithLock)[SET_STATE_LOCK] = true;
+ }
+
+ private applyPointState(point: Highcharts.Point, state: "" | Highcharts.PointStateValue, move = true) {
+ (point.setState as PointSetStateWithLock)[SET_STATE_LOCK] = false;
+ this.withInstantUndim(point.series, state, () => point.setState(state, move));
+ (point.setState as PointSetStateWithLock)[SET_STATE_LOCK] = true;
+ }
+
// Removes dimmed state from all series and points.
public clearChartItemsHighlight = () => {
+ this.discardPreview();
for (const s of getChartSeries(this.context.chart())) {
this.setSeriesState(s, "");
for (const p of getSeriesData(s)) {
@@ -129,18 +277,14 @@ export class ChartExtraHighlight {
// Makes the specified series active or dimmed.
private setSeriesState(series: SafeSeries, state: "" | Highcharts.SeriesStateValue) {
- (series.setState as SeriesSetStateWithLock)[SET_STATE_LOCK] = false;
- series.setState(state, false);
+ this.applySeriesState(series, state);
this.updateStoredSeriesState(series, state);
- (series.setState as SeriesSetStateWithLock)[SET_STATE_LOCK] = true;
}
// Makes the specified point active or dimmed.
private setPointState(point: Highcharts.Point, state: "" | Highcharts.PointStateValue, move = true) {
- (point.setState as PointSetStateWithLock)[SET_STATE_LOCK] = false;
- point.setState(state, move);
+ this.applyPointState(point, state, move);
this.updateStoredPointState(point, state);
- (point.setState as PointSetStateWithLock)[SET_STATE_LOCK] = true;
}
// Restores series and points highlight state after chart's re-render.
@@ -162,6 +306,19 @@ export class ChartExtraHighlight {
}
}
setPlotLinesState(this.context.chart(), (lineId) => !inactiveSeriesIds.has(lineId));
+ for (const s of getChartSeries(this.context.chart())) {
+ const previewState = this.previewState.get(getSeriesId(s));
+ if (previewState !== undefined) {
+ this.applySeriesState(s, previewState);
+ }
+ const pointPreviewStates = this.pointPreviewState.get(getSeriesId(s));
+ for (const p of pointPreviewStates ? getSeriesData(s) : []) {
+ const pointPreviewState = pointPreviewStates?.get(this.getPointKey(p));
+ if (pointPreviewState !== undefined) {
+ this.applyPointState(p, pointPreviewState);
+ }
+ }
+ }
}
private updateStoredSeriesState(series: SafeSeries, state: "" | Highcharts.SeriesStateValue) {
@@ -236,3 +393,17 @@ function iteratePlotLines(chart: SafeChart, cb: (lineId: string, line: Highchart
}
});
}
+
+function applyWithInstantUndim(series: { options: object }, state: string, setState: () => void) {
+ const states = (series.options as { states?: Record }).states;
+ if (state === "inactive" || !states) {
+ setState();
+ return;
+ }
+ const key = state || "normal";
+ const stateOptions = states[key] ?? (states[key] = {});
+ const animation = stateOptions.animation;
+ stateOptions.animation = { duration: 1 };
+ setState();
+ stateOptions.animation = animation;
+}
diff --git a/src/core/chart-api/chart-extra-legend.tsx b/src/core/chart-api/chart-extra-legend.tsx
index bdbde6f0..223e308d 100644
--- a/src/core/chart-api/chart-extra-legend.tsx
+++ b/src/core/chart-api/chart-extra-legend.tsx
@@ -17,6 +17,8 @@ import { ChartExtraContext } from "./chart-extra-context";
// The reactive state is used to propagate changes in legend items to the core legend React component.
export interface ReactiveLegendState {
items: readonly CoreChartProps.LegendItem[];
+ previewItemIds: readonly string[];
+ previewDimmed: boolean;
}
// Chart helper that implements custom legend behaviors.
@@ -25,7 +27,7 @@ export class ChartExtraLegend extends AsyncStore {
private visibilityMode: "internal" | "external" = "external";
constructor(context: ChartExtraContext) {
- super({ items: [] });
+ super({ items: [], previewItemIds: [], previewDimmed: false });
this.context = context;
}
@@ -74,15 +76,42 @@ export class ChartExtraLegend extends AsyncStore {
public onHighlightItems = (highlightedItems: readonly string[]) => {
const currentItems = this.get().items;
const updatedItems = currentItems.map(({ ...i }) => ({ ...i, highlighted: highlightedItems.includes(i.id) }));
+ this.onCancelPreview();
this.updateLegendItems(updatedItems);
};
// Clears legend highlight state.
public onClearHighlight = () => {
const nextItems = this.get().items.map(({ ...item }) => ({ ...item, highlighted: false }));
+ this.onCancelPreview();
this.updateLegendItems(nextItems);
};
+ public onPreviewPoint = (point: Highcharts.Point, dimmed: boolean) => {
+ const itemIds = point.series.type === "pie" ? [getPointId(point)] : [getSeriesId(getMasterSeries(point))];
+ this.onPreviewItems(itemIds, dimmed);
+ };
+
+ public onPreviewGroup = (group: readonly Highcharts.Point[], dimmed: boolean) => {
+ this.onPreviewItems(
+ group.map((point) => getSeriesId(getMasterSeries(point))),
+ dimmed,
+ );
+ };
+
+ public onPreviewItems = (itemIds: readonly string[], dimmed: boolean) => {
+ const state = this.get();
+ if (!isEqualArrays(state.previewItemIds, itemIds, (a, b) => a === b) || state.previewDimmed !== dimmed) {
+ this.set((state) => ({ ...state, previewItemIds: itemIds, previewDimmed: dimmed }));
+ }
+ };
+
+ public onCancelPreview = () => {
+ if (this.get().previewItemIds.length > 0) {
+ this.set((state) => ({ ...state, previewItemIds: [], previewDimmed: false }));
+ }
+ };
+
private initLegend = () => {
const prevState = this.get().items.reduce((map, item) => map.set(item.id, item), new Map());
const itemSpecs = getChartLegendItems({
@@ -111,7 +140,7 @@ export class ChartExtraLegend extends AsyncStore {
);
}
if (!isEqualArrays(this.get().items, nextItems, isLegendItemsEqual)) {
- this.set(() => ({ items: nextItems }));
+ this.set((state) => ({ ...state, items: nextItems }));
}
};
diff --git a/src/core/chart-api/chart-extra-pointer.tsx b/src/core/chart-api/chart-extra-pointer.tsx
index eaf70eae..98464956 100644
--- a/src/core/chart-api/chart-extra-pointer.tsx
+++ b/src/core/chart-api/chart-extra-pointer.tsx
@@ -4,16 +4,20 @@
import type Highcharts from "highcharts";
import { getChartSeries, isPointVisible, SafeChart } from "../../internal/utils/highcharts";
-import { DebouncedCall } from "../../internal/utils/utils";
+import { DebouncedCall, isEqualArrays } from "../../internal/utils/utils";
import { isInsidePlot } from "../utils";
import { ChartExtraContext } from "./chart-extra-context";
const HOVER_LOST_DELAY = 25;
+export type PointerHoverTarget = Highcharts.Point | Highcharts.Point[];
+
export interface ChartExtraPointerHandlers {
onPointHover(point: Highcharts.Point): void;
onGroupHover(group: Highcharts.Point[]): void;
onHoverLost(): void;
+ onHoverPreview(target: PointerHoverTarget): void;
+ onHoverPreviewCancel(): void;
onPointClick(point: Highcharts.Point): void;
onGroupClick(group: Highcharts.Point[]): void;
isLocked(): boolean;
@@ -27,6 +31,9 @@ export class ChartExtraPointer {
private hoveredGroup: null | Highcharts.Point[] = null;
private tooltipHovered = false;
private hoverLostCall = new DebouncedCall();
+ private hover = new DebouncedCall(isSameHoverTarget);
+ private pointerMoveDocument: null | Document = null;
+ private lastPointerMoveAt = 0;
constructor(context: ChartExtraContext, handlers: ChartExtraPointerHandlers) {
this.context = context;
@@ -34,11 +41,28 @@ export class ChartExtraPointer {
}
public onChartLoad = (chart: SafeChart) => {
+ this.trackPointerMoves(chart.container.ownerDocument);
chart.container.addEventListener("mousemove", this.onChartMousemove);
chart.container.addEventListener("mouseout", this.onChartMouseout);
};
+ public cancelPendingHover = () => this.hover.cancelPending();
+
+ public getLastPointerMoveAt = () => this.lastPointerMoveAt;
+
+ private trackPointerMoves(document: null | Document) {
+ this.pointerMoveDocument?.removeEventListener("mousemove", this.onDocumentMousemove, { capture: true });
+ this.pointerMoveDocument = document;
+ this.pointerMoveDocument?.addEventListener("mousemove", this.onDocumentMousemove, { capture: true, passive: true });
+ }
+
+ private onDocumentMousemove = () => {
+ this.lastPointerMoveAt = Date.now();
+ };
+
public onChartDestroy = () => {
+ this.hover.cancelPending();
+ this.trackPointerMoves(null);
this.context.chartOrNull?.container?.removeEventListener("mousemove", this.onChartMousemove);
this.context.chartOrNull?.container?.removeEventListener("mouseout", this.onChartMouseout);
};
@@ -67,6 +91,9 @@ export class ChartExtraPointer {
this.tooltipHovered = true;
this.hoveredPoint = null;
this.hoveredGroup = null;
+ if (this.hover.cancelPending()) {
+ this.handlers.onHoverPreviewCancel();
+ }
};
// When the pointer leaves the tooltip it can hover another point or group. If that does not happen,
@@ -150,6 +177,7 @@ export class ChartExtraPointer {
if (this.handlers.isLocked()) {
return false;
}
+ this.hover.flush();
const targetPoint = point ?? (this.hoveredPoint && isPointVisible(this.hoveredPoint) ? this.hoveredPoint : null);
if (targetPoint) {
this.handlers.onPointClick(targetPoint);
@@ -166,7 +194,7 @@ export class ChartExtraPointer {
if (isPointVisible(point)) {
this.hoveredPoint = point;
this.hoveredGroup = null;
- this.handlers.onPointHover(point);
+ this.scheduleHover(point);
this.applyCursorStyle();
}
};
@@ -176,7 +204,7 @@ export class ChartExtraPointer {
const availablePoints = group.filter(isPointVisible);
this.hoveredPoint = null;
this.hoveredGroup = availablePoints;
- this.handlers.onGroupHover(availablePoints);
+ this.scheduleHover(availablePoints);
this.applyCursorStyle();
}
};
@@ -193,6 +221,30 @@ export class ChartExtraPointer {
}, HOVER_LOST_DELAY);
};
+ private scheduleHover = (target: PointerHoverTarget) => {
+ if (this.hover.call(() => this.applyHover(target), this.context.settings.hoverDelay, target)) {
+ this.handlers.onHoverPreview(target);
+ }
+ };
+
+ private applyHover = (target: PointerHoverTarget) => {
+ const current = this.hoveredPoint ?? this.hoveredGroup;
+ if (!current || !isSameHoverTarget(current, target)) {
+ this.handlers.onHoverPreviewCancel();
+ } else if (Array.isArray(target)) {
+ const group = target.filter(isPointVisible);
+ if (group.length > 0 || target.length === 0) {
+ this.handlers.onGroupHover(group);
+ } else {
+ this.handlers.onHoverPreviewCancel();
+ }
+ } else if (isPointVisible(target)) {
+ this.handlers.onPointHover(target);
+ } else {
+ this.handlers.onHoverPreviewCancel();
+ }
+ };
+
private applyCursorStyle = () => {
const container = this.context.chart().container;
if (container) {
@@ -201,3 +253,10 @@ export class ChartExtraPointer {
}
};
}
+
+export function isSameHoverTarget(a: PointerHoverTarget, b: PointerHoverTarget) {
+ if (Array.isArray(a) && Array.isArray(b)) {
+ return isEqualArrays(a, b, (x, y) => x === y);
+ }
+ return a === b;
+}
diff --git a/src/core/chart-api/chart-extra-tooltip.tsx b/src/core/chart-api/chart-extra-tooltip.tsx
index d9c8cce2..6c36a39c 100644
--- a/src/core/chart-api/chart-extra-tooltip.tsx
+++ b/src/core/chart-api/chart-extra-tooltip.tsx
@@ -96,6 +96,20 @@ export class ChartExtraTooltip extends AsyncStore {
}
}
+ public showCursor(point: null | Highcharts.Point, group: readonly Highcharts.Point[]) {
+ if (!this.tooltipLock && this.chartType === "cartesian") {
+ this.createCursor(point, group);
+ }
+ }
+
+ public restoreCursor() {
+ if (this.lastGroup && this.get().visible) {
+ this.updateTooltipCursor({ point: this.lastPoint, group: this.lastGroup });
+ } else {
+ this.cursor.hide();
+ }
+ }
+
public hideTooltip() {
this.cursor.hide();
this.targetTrack.hide();
@@ -127,9 +141,7 @@ export class ChartExtraTooltip extends AsyncStore {
this.lastPoint = props.point;
this.lastGroup = props.group;
- const chartType =
- getChartSeries(this.context.chart()).find((s) => s.type === "pie" || s.type === "solidgauge")?.type ??
- "cartesian";
+ const chartType = this.chartType;
if (chartType === "pie") {
return this.updateTooltipCursorPie(props.group[0]);
} else if (chartType === "solidgauge") {
@@ -148,14 +160,24 @@ export class ChartExtraTooltip extends AsyncStore {
}) => {
const pointRect = point ? getPointRect(point) : getGroupRect(group.slice(0, 1));
const groupRect = getGroupRect(group);
+ this.createCursor(point, group);
+ this.targetTrack.rect(this.context.chart().renderer, { ...pointRect, ...this.commonTrackAttrs });
+ this.groupTrack.rect(this.context.chart().renderer, { ...groupRect, ...this.commonTrackAttrs });
+ };
+
+ private createCursor(point: null | Highcharts.Point, group: readonly Highcharts.Point[]) {
// The cursor is not shown when column series are present (a UX decision).
const hideCursorLine = getChartSeries(this.context.chart()).some(
(s) => s.type === "column" || s.type === "heatmap",
);
- this.cursor.create(groupRect, point, group, !hideCursorLine);
- this.targetTrack.rect(this.context.chart().renderer, { ...pointRect, ...this.commonTrackAttrs });
- this.groupTrack.rect(this.context.chart().renderer, { ...groupRect, ...this.commonTrackAttrs });
- };
+ this.cursor.create(getGroupRect(group), point, group, !hideCursorLine);
+ }
+
+ private get chartType() {
+ return (
+ getChartSeries(this.context.chart()).find((s) => s.type === "pie" || s.type === "solidgauge")?.type ?? "cartesian"
+ );
+ }
private updateTooltipCursorPie = (point: Highcharts.Point) => {
// We only create target track for pie chart as pie chart does not support groups.
diff --git a/src/core/chart-api/index.tsx b/src/core/chart-api/index.tsx
index 0a517d72..ec72f679 100644
--- a/src/core/chart-api/index.tsx
+++ b/src/core/chart-api/index.tsx
@@ -7,7 +7,7 @@ import type Highcharts from "highcharts";
import { fireNonCancelableEvent } from "../../internal/events";
import { ReadonlyAsyncStore } from "../../internal/utils/async-store";
import { getChartSeries, getSeriesData } from "../../internal/utils/highcharts";
-import { Writeable } from "../../internal/utils/utils";
+import { DebouncedCall, isEqualArrays, Writeable } from "../../internal/utils/utils";
import { CoreChartProps } from "../interfaces";
import {
getChartAccessibleDescription,
@@ -21,10 +21,20 @@ import { ChartExtraHighlight } from "./chart-extra-highlight";
import { ChartExtraLegend, ReactiveLegendState } from "./chart-extra-legend";
import { ChartExtraNavigation, ChartExtraNavigationHandlers } from "./chart-extra-navigation";
import { ChartExtraNodata, ReactiveNodataState } from "./chart-extra-nodata";
-import { ChartExtraPointer, ChartExtraPointerHandlers } from "./chart-extra-pointer";
+import {
+ ChartExtraPointer,
+ ChartExtraPointerHandlers,
+ isSameHoverTarget,
+ PointerHoverTarget,
+} from "./chart-extra-pointer";
import { ChartExtraTooltip, ReactiveTooltipState } from "./chart-extra-tooltip";
import { ChartExtraZoom, ChartExtraZoomHandlers, ReactiveZoomState } from "./chart-extra-zoom";
+interface HighlightTarget {
+ point: null | Highcharts.Point;
+ group: readonly Highcharts.Point[];
+}
+
// The API helper injects Cloudscape custom behaviors, and returns the API instance that comes with
// reactive state and handlers to be assigned as Highcharts options, used by Cloudscape components
// (tooltip, legend, and other), or exposed as public core chart API.
@@ -95,6 +105,12 @@ export class ChartAPI {
private chartExtraNodata = new ChartExtraNodata(this.context);
private chartExtraAxisTitles = new ChartExtraAxisTitles(this.context);
private chartExtraZoom = new ChartExtraZoom(this.context, this.zoomHandlers);
+ private legendItemHighlight = new DebouncedCall();
+ private apiHighlight = new DebouncedCall((a, b) =>
+ typeof a === "string" || typeof b === "string" ? a === b : isSameHoverTarget(a, b),
+ );
+ private appliedHighlight: null | HighlightTarget = null;
+ private notifiedHighlight: null | HighlightTarget = null;
constructor(
settings: ChartExtraContext.Settings,
@@ -157,6 +173,8 @@ export class ChartAPI {
// There is no cleanup or destroy event in Highcharts options, so we define a custom one
// to be used when the React component unmounts.
public onChartDestroy = () => {
+ this.legendItemHighlight.cancelPending();
+ this.apiHighlight.cancelPending();
this.chartExtraNavigation.onChartDestroy();
this.chartExtraPointer.onChartDestroy();
this.chartExtraTooltip.onChartDestroy();
@@ -232,36 +250,52 @@ export class ChartAPI {
public updateItemsVisibility = this.chartExtraLegend.updateItemsVisibility.bind(this.chartExtraLegend);
// A callback used by the legend and filter components when series/segments visibility changes.
- public onItemVisibilityChange = (items: readonly string[], detail: CoreChartProps.InteractionKind) =>
- this.chartExtraLegend.onItemVisibilityChange(items, detail);
+ public onItemVisibilityChange = (items: readonly string[], detail: CoreChartProps.InteractionKind) => {
+ this.changeItemsVisibility(items, detail);
+ };
// Callbacks used by the legend component when items highlight state changes.
- public onHighlightChartItems = (itemIds: readonly string[]) => {
- if (!this.isTooltipPinned) {
- this.chartExtraHighlight.highlightChartItems(itemIds);
- this.chartExtraLegend.onHighlightItems(itemIds);
+ public onHighlightChartItems = (itemIds: readonly string[]) => this.highlightChartItems(itemIds);
+ public onEnterLegendItem = (itemId: string, highlight: () => void) => {
+ this.scheduleHighlight(
+ "legend",
+ this.legendItemHighlight,
+ itemId,
+ () => {
+ if (this.chartExtraLegend.get().items.some((item) => item.id === itemId && item.visible)) {
+ highlight();
+ }
+ },
+ () => this.previewItems([itemId]),
+ );
+ };
+ public onLeaveLegendItem = () => {
+ if (this.legendItemHighlight.cancelPending()) {
+ this.restorePreview({ notify: false });
}
};
public onClearChartItemsHighlight = () => {
+ this.cancelPendingHovers({ notify: false });
if (!this.isTooltipPinned) {
this.chartExtraHighlight.clearChartItemsHighlight();
this.chartExtraLegend.onClearHighlight();
+ this.notifiedHighlight = null;
// Notify the consumer that a clear-highlight action was made.
fireNonCancelableEvent(this.context.handlers.onClearHighlight, { isApiCall: false });
}
};
- // Callbacks used for hover and keyboard navigation, and also exposed to the public API to give the ability
- // to highlight and show tooltip for the given point or group manually.
+ // Callbacks used for hover and keyboard navigation.
public highlightChartItems = (itemIds: readonly string[]) => {
+ this.cancelPendingHovers({ notify: false });
if (!this.isTooltipPinned) {
this.chartExtraHighlight.highlightChartItems(itemIds);
this.chartExtraLegend.onHighlightItems(itemIds);
}
};
public setItemsVisible = (visibleItemsIds: readonly string[]) => {
- this.chartExtraLegend.onItemVisibilityChange(visibleItemsIds, { interactionType: "api" });
+ this.changeItemsVisibility(visibleItemsIds, { interactionType: "api" });
};
public highlightChartPoint = (point: Highcharts.Point, { isApiCall }: { isApiCall: boolean }) => {
if (!this.isTooltipPinned) {
@@ -273,17 +307,17 @@ export class ChartAPI {
this.highlightActions(group as Writeable, { isApiCall });
}
};
- public clearChartHighlight = ({ isApiCall }: { isApiCall: boolean }) => {
+ public clearChartHighlight = ({ isApiCall, keepLegendHover }: { isApiCall: boolean; keepLegendHover?: boolean }) => {
if (!this.isTooltipPinned) {
- this.clearHighlightActions({ isApiCall });
+ this.clearHighlightActions({ isApiCall, keepLegendHover });
}
};
public get publicApi() {
return {
- highlightItems: (itemIds: readonly string[]) => this.highlightChartItems(itemIds),
+ highlightItems: (itemIds: readonly string[]) => this.highlightItemsFromApi(itemIds),
setItemsVisible: (visibleItemIds: readonly string[]) => this.setItemsVisible(visibleItemIds),
- highlightChartPoint: (point: Highcharts.Point) => this.highlightChartPoint(point, { isApiCall: true }),
- highlightChartGroup: (group: readonly Highcharts.Point[]) => this.highlightChartGroup(group, { isApiCall: true }),
+ highlightChartPoint: (point: Highcharts.Point) => this.highlightTargetFromApi(point),
+ highlightChartGroup: (group: readonly Highcharts.Point[]) => this.highlightTargetFromApi([...group]),
clearChartHighlight: () => this.clearChartHighlight({ isApiCall: true }),
};
}
@@ -299,6 +333,7 @@ export class ChartAPI {
// Dismiss any visible non-pinned tooltip when ESC is pressed.
// Returns true if a tooltip was dismissed, false otherwise.
// Used by ESC handlers at group/point level to decide whether to also navigate.
+ this.cancelPendingHovers();
const tooltipState = this.chartExtraTooltip.get();
if (tooltipState.visible && !tooltipState.pinned) {
this.clearChartHighlight({ isApiCall: false });
@@ -350,7 +385,16 @@ export class ChartAPI {
this.highlightChartGroup(group, { isApiCall: false });
},
onHoverLost: () => {
- this.clearChartHighlight({ isApiCall: false });
+ this.clearChartHighlight({ isApiCall: false, keepLegendHover: true });
+ },
+ onHoverPreview: (target) => {
+ this.cancelPendingHovers({ pointer: false, notify: false });
+ if (!this.isTooltipPinned) {
+ this.showPreview(target);
+ }
+ },
+ onHoverPreviewCancel: () => {
+ this.restorePreview({ notify: true });
},
onPointClick: (point) => {
this.pinTooltipOnPoint(point);
@@ -452,8 +496,8 @@ export class ChartAPI {
target: Highcharts.Point | Highcharts.Point[],
{ isApiCall, overrideTooltipLock }: { isApiCall: boolean; overrideTooltipLock?: boolean },
) {
- const point = Array.isArray(target) ? null : target;
- const group = Array.isArray(target) ? target : this.context.derived.getPointsByX(target.x);
+ this.cancelPendingHovers({ notify: false });
+ const { point, group } = this.getHighlightTarget(target);
if (!this.isTooltipPinned) {
// Update Highcharts elements state.
@@ -473,11 +517,134 @@ export class ChartAPI {
}
// Notify the consumer that a highlight action was made.
- fireNonCancelableEvent(this.context.handlers.onHighlight, { point, group, isApiCall });
+ this.appliedHighlight = { point, group };
+ this.notifyHighlight(point, group, isApiCall);
+ }
+ }
+
+ public cancelPendingHovers = ({ pointer = true, legend = true, api = true, notify = true } = {}) => {
+ const hadPointerHover = pointer && this.chartExtraPointer.cancelPendingHover();
+ const hadLegendHighlight = legend && this.legendItemHighlight.cancelPending();
+ const hadApiHighlight = api && this.apiHighlight.cancelPending();
+ if (hadPointerHover || hadLegendHighlight || hadApiHighlight) {
+ this.restorePreview({ notify, legendPreviewed: hadLegendHighlight });
+ }
+ };
+
+ public getLegendScrollDelay = () => {
+ const delay = this.context.settings.hoverDelay;
+ return delay > 0 ? Math.max(0, this.chartExtraPointer.getLastPointerMoveAt() + delay - Date.now()) : 0;
+ };
+
+ public get hoverDebounceEnabled() {
+ return this.context.settings.hoverDebounceEnabled;
+ }
+
+ private notifyHighlight(point: null | Highcharts.Point, group: readonly Highcharts.Point[], isApiCall: boolean) {
+ const notified = this.notifiedHighlight;
+ if (
+ this.hoverDebounceEnabled &&
+ !isApiCall &&
+ notified &&
+ notified.point === point &&
+ isEqualArrays(notified.group, group, (a, b) => a === b)
+ ) {
+ return;
}
+ this.notifiedHighlight = { point, group };
+ fireNonCancelableEvent(this.context.handlers.onHighlight, { point, group, isApiCall });
+ }
+
+ private showPreview(target: PointerHoverTarget, { notify = true } = {}) {
+ const { point, group } = this.getHighlightTarget(target);
+ this.chartExtraTooltip.showCursor(point, group);
+ if (!this.hoverDebounceEnabled) {
+ return;
+ }
+ if (point) {
+ this.chartExtraLegend.onPreviewPoint(point, this.chartExtraHighlight.previewChartPoint(point));
+ } else {
+ this.chartExtraLegend.onPreviewGroup(group, this.chartExtraHighlight.previewChartGroup(group));
+ }
+ if (notify) {
+ this.notifyHighlight(point, group, false);
+ }
+ }
+
+ private get isApiHighlightDelayed() {
+ return this.hoverDebounceEnabled && this.context.settings.hoverDelay > 0 && !this.isTooltipPinned;
+ }
+
+ private highlightItemsFromApi(itemIds: readonly string[]) {
+ const apply = () => this.highlightChartItems(itemIds);
+ if (this.isApiHighlightDelayed) {
+ this.scheduleHighlight("api", this.apiHighlight, itemIds.join("\u0000"), apply, () => this.previewItems(itemIds));
+ } else {
+ apply();
+ }
+ }
+
+ private highlightTargetFromApi(target: PointerHoverTarget) {
+ const apply = () => this.highlightActions(target, { isApiCall: true });
+ if (this.isApiHighlightDelayed) {
+ this.scheduleHighlight("api", this.apiHighlight, target, apply, () =>
+ this.showPreview(target, { notify: false }),
+ );
+ } else {
+ apply();
+ }
+ }
+
+ private scheduleHighlight(
+ source: "legend" | "api",
+ call: DebouncedCall,
+ key: Key,
+ apply: () => void,
+ preview: () => void,
+ ) {
+ this.cancelPendingHovers({ [source]: false, notify: false });
+ if (call.call(apply, this.context.settings.hoverDelay, key) && !this.isTooltipPinned) {
+ preview();
+ }
+ }
+
+ private previewItems(itemIds: readonly string[]) {
+ this.chartExtraLegend.onPreviewItems(itemIds, this.chartExtraHighlight.previewChartItems(itemIds));
+ }
+
+ private changeItemsVisibility(itemIds: readonly string[], detail: CoreChartProps.InteractionKind) {
+ this.cancelPendingHovers();
+ this.chartExtraLegend.onItemVisibilityChange(itemIds, detail);
+ }
+
+ private restorePreview({ notify, legendPreviewed = false }: { notify: boolean; legendPreviewed?: boolean }) {
+ this.chartExtraTooltip.restoreCursor();
+ this.chartExtraHighlight.cancelPreview();
+ this.chartExtraLegend.onCancelPreview();
+ if (notify && !this.isTooltipPinned && this.hoverDebounceEnabled) {
+ if (this.appliedHighlight) {
+ this.notifyHighlight(this.appliedHighlight.point, this.appliedHighlight.group, false);
+ } else if (this.notifiedHighlight || legendPreviewed) {
+ this.notifiedHighlight = null;
+ fireNonCancelableEvent(this.context.handlers.onClearHighlight, { isApiCall: false });
+ }
+ }
+ }
+
+ private getHighlightTarget(target: PointerHoverTarget) {
+ const point = Array.isArray(target) ? null : target;
+ const group = Array.isArray(target) ? target : this.context.derived.getPointsByX(target.x);
+ return { point, group };
}
- private clearHighlightActions = ({ isApiCall }: { isApiCall: boolean }) => {
+ private clearHighlightActions = ({
+ isApiCall,
+ keepLegendHover,
+ }: {
+ isApiCall: boolean;
+ keepLegendHover?: boolean;
+ }) => {
+ this.cancelPendingHovers({ legend: !keepLegendHover, notify: false });
if (!this.isTooltipPinned) {
// Update Highcharts elements state.
this.chartExtraHighlight.clearChartItemsHighlight();
@@ -485,6 +652,8 @@ export class ChartAPI {
// Update tooltip and legend state.
this.chartExtraTooltip.hideTooltip();
this.chartExtraLegend.onClearHighlight();
+ this.appliedHighlight = null;
+ this.notifiedHighlight = null;
// Notify the consumer that a clear-highlight action was made.
fireNonCancelableEvent(this.context.handlers.onClearHighlight, { isApiCall });
diff --git a/src/core/chart-core.tsx b/src/core/chart-core.tsx
index 66f919ec..51dff0f1 100644
--- a/src/core/chart-core.tsx
+++ b/src/core/chart-core.tsx
@@ -35,12 +35,14 @@ import { ChartZoomLiveRegion } from "./components/core-zoom-live-region";
import { getFormatter } from "./formatters";
import { useChartI18n } from "./i18n-utils";
import { CoreChartProps } from "./interfaces";
-import { InternalZoomProps } from "./internal-interfaces";
+import { InternalHoverProps, InternalZoomProps } from "./internal-interfaces";
import { getLegendsProps, getPointAccessibleDescription } from "./utils";
import styles from "./styles.css.js";
import testClasses from "./test-classes/styles.css.js";
+const DEFAULT_HOVER_DEBOUNCE = 150;
+
/**
* CoreChart is the core internal abstraction that accepts the entire set of Highcharts options along
* with Cloudscape props to define custom tooltip, no-data, formatters, items visibility, and more.
@@ -59,6 +61,7 @@ export function InternalCoreChart({
zoom: zoomOptions,
zoomRange,
onZoomRangeChange,
+ hoverDebounce,
legend: legendOptions,
fallback = ,
callback,
@@ -78,11 +81,18 @@ export function InternalCoreChart({
__internalRootRef,
getItemOptions,
...rest
-}: CoreChartProps & InternalBaseComponentProps & InternalZoomProps) {
+}: CoreChartProps & InternalBaseComponentProps & InternalZoomProps & InternalHoverProps) {
const highcharts = rest.highcharts as null | typeof Highcharts;
const labels = useChartI18n({ ariaLabel, ariaDescription, i18nStrings });
// The zoom applies to the first x-axis, and is ignored when the chart does not define one.
const zoomEnabled = !!zoomOptions?.enabled && (castArray(options.xAxis)?.length ?? 0) > 0;
+ const hoverDelay =
+ hoverDebounce === true
+ ? DEFAULT_HOVER_DEBOUNCE
+ : typeof hoverDebounce === "number" && hoverDebounce > 0
+ ? hoverDebounce
+ : -1;
+ const hoverDebounceEnabled = hoverDebounce !== undefined && hoverDebounce !== false;
const context: ChartExtraContext["settings"] = {
chartId: useUniqueId(),
noDataEnabled: !!noDataOptions,
@@ -92,6 +102,8 @@ export function InternalCoreChart({
labels,
getItemOptions: getItemOptions ?? (() => ({})),
zoomEnabled,
+ hoverDelay,
+ hoverDebounceEnabled,
};
const handlers = { onHighlight, onClearHighlight, onVisibleItemsChange, onZoomRangeChange };
const state = { visibleItems, zoomRange };
@@ -107,6 +119,8 @@ export function InternalCoreChart({
i18nStrings,
onItemHighlight: onLegendItemHighlight,
getLegendTooltipContent: rest.getLegendTooltipContent,
+ tooltipShowDelay: hoverDebounceEnabled ? Math.max(hoverDelay, 0) : undefined,
+ delayScrollIntoView: hoverDebounceEnabled,
};
const containerProps = {
fitHeight,
@@ -130,10 +144,13 @@ export function InternalCoreChart({
return;
}
- if (event.keyCode === KeyCode.escape && context.tooltipEnabled) {
- const tooltipState = api.tooltipStore.get();
- if (tooltipState.visible && !tooltipState.pinned) {
- api.hideTooltip();
+ if (event.keyCode === KeyCode.escape) {
+ api.cancelPendingHovers();
+ if (context.tooltipEnabled) {
+ const tooltipState = api.tooltipStore.get();
+ if (tooltipState.visible && !tooltipState.pinned) {
+ api.hideTooltip();
+ }
}
}
};
@@ -415,6 +432,9 @@ export function InternalCoreChart({
{context.tooltipEnabled && (
;
getLegendTooltipContent?: CoreChartProps.GetLegendTooltipContent;
+ tooltipShowDelay?: number;
+ delayScrollIntoView?: boolean;
}) {
const i18n = useInternalI18n("[charts]");
const legendAriaLabel = i18n("i18nStrings.legendAriaLabel", i18nStrings?.legendAriaLabel);
@@ -44,7 +48,9 @@ export function ChartLegend({
const ariaLabel = isSecondary ? secondaryLegendAriaLabel : legendAriaLabel;
const legendItems = useSelector(api.legendStore, (s) => s.items);
- const someHighlighted = legendItems.some((item) => item.highlighted);
+ const previewItemIds = useSelector(api.legendStore, (s) => s.previewItemIds);
+ const previewDimmed = useSelector(api.legendStore, (s) => s.previewDimmed);
+ const someHighlighted = legendItems.some((item) => item.highlighted) || (previewItemIds.length > 0 && previewDimmed);
const isChartTooltipPinned = useSelector(api.tooltipStore, (s) => s.pinned);
const filteredItems = isSecondary
? legendItems.filter((item) => item.isSecondary)
@@ -87,18 +93,35 @@ export function ChartLegend({
ariaLabel={ariaLabel}
className={className}
legendTitle={title}
- items={filteredItems}
+ items={
+ previewItemIds.length > 0
+ ? filteredItems.map((item) => ({ ...item, highlighted: previewItemIds.includes(item.id) }))
+ : filteredItems
+ }
someHighlighted={someHighlighted}
horizontalAlignment={horizontalAlignment}
enableHorizontalScroll={enableHorizontalScroll}
+ tooltipShowDelay={tooltipShowDelay}
+ getScrollIntoViewDelay={delayScrollIntoView ? api.getLegendScrollDelay : undefined}
actions={actions}
alignment={alignment}
onToggleItem={onToggleItem}
onSelectItem={onSelectItem}
onItemHighlightExit={api.onClearChartItemsHighlight}
- onItemHighlightEnter={(item) => {
- api.onHighlightChartItems([item.id]);
- fireNonCancelableEvent(onItemHighlight, { item });
+ onItemHoverLeave={api.onLeaveLegendItem}
+ onItemHighlightEnter={(item, detail) => {
+ if (!detail.pointer) {
+ api.onHighlightChartItems([item.id]);
+ fireNonCancelableEvent(onItemHighlight, { item });
+ } else if (api.hoverDebounceEnabled) {
+ fireNonCancelableEvent(onItemHighlight, { item });
+ api.onEnterLegendItem(item.id, () => api.onHighlightChartItems([item.id]));
+ } else {
+ api.onEnterLegendItem(item.id, () => {
+ api.onHighlightChartItems([item.id]);
+ fireNonCancelableEvent(onItemHighlight, { item });
+ });
+ }
}}
getTooltipContent={(props) => {
if (isChartTooltipPinned) {
diff --git a/src/core/interfaces.ts b/src/core/interfaces.ts
index 9c910817..bf242282 100644
--- a/src/core/interfaces.ts
+++ b/src/core/interfaces.ts
@@ -549,6 +549,7 @@ export namespace CoreChartProps {
enabled?: boolean;
placement?: "middle" | "outside" | "target";
size?: "small" | "medium" | "large";
+ // Superseded by the internal hoverDebounce prop (see InternalHoverProps) and planned for removal.
debounce?: number | boolean;
seriesSorting?: "as-added" | "by-value-desc";
}
diff --git a/src/core/internal-interfaces.ts b/src/core/internal-interfaces.ts
index 254b4b0d..5d59d4e7 100644
--- a/src/core/internal-interfaces.ts
+++ b/src/core/internal-interfaces.ts
@@ -25,3 +25,11 @@ export interface InternalZoomProps {
zoomRange?: ZoomRange | null;
onZoomRangeChange?: NonCancelableEventHandler;
}
+
+// Highlights the hovered series and legend item immediately, and delays dimming the other series and legend items,
+// the tooltip, and legend scroll-into-view until the pointer settles on a target. It supersedes tooltip.debounce,
+// which only delays the tooltip: tooltip.debounce is ignored while hoverDebounce is set, and is planned for removal
+// once consumers have moved to hoverDebounce.
+export interface InternalHoverProps {
+ hoverDebounce?: number | boolean;
+}
diff --git a/src/internal/components/chart-legend/index.tsx b/src/internal/components/chart-legend/index.tsx
index b2107a03..ccd05376 100644
--- a/src/internal/components/chart-legend/index.tsx
+++ b/src/internal/components/chart-legend/index.tsx
@@ -44,9 +44,12 @@ export interface ChartLegendProps {
horizontalAlignment: LegendHorizontalAlignment;
onToggleItem: (itemId: string) => void;
onSelectItem: (itemId: string) => void;
- onItemHighlightEnter: (item: LegendItem) => void;
+ onItemHighlightEnter: (item: LegendItem, detail: { pointer: boolean }) => void;
onItemHighlightExit: () => void;
+ onItemHoverLeave?: () => void;
getTooltipContent: (props: GetLegendTooltipContentProps) => null | LegendTooltipContent;
+ tooltipShowDelay?: number;
+ getScrollIntoViewDelay?: () => number;
}
export const ChartLegend = ({
@@ -62,9 +65,12 @@ export const ChartLegend = ({
onSelectItem,
onItemHighlightEnter,
onItemHighlightExit,
+ onItemHoverLeave,
getTooltipContent,
horizontalAlignment,
enableHorizontalScroll,
+ tooltipShowDelay = TOOLTIP_SHOW_DELAY,
+ getScrollIntoViewDelay,
}: ChartLegendProps) => {
const containerRef = useRef(null);
const elementsByIndexRef = useRef>([]);
@@ -74,11 +80,13 @@ export const ChartLegend = ({
const scrollIntoViewControl = useMemo(() => new DebouncedCall(), []);
const [selectedIndex, setSelectedIndex] = useState(0);
const [tooltipItemId, setTooltipItemId] = useState(null);
- const { showTooltip, hideTooltip } = useMemo(() => {
+ const tooltipShowDelayRef = useRef(tooltipShowDelay);
+ tooltipShowDelayRef.current = tooltipShowDelay;
+ const { showTooltip, hideTooltip, cancelTooltip } = useMemo(() => {
const control = new DebouncedCall();
return {
showTooltip(itemId: string) {
- control.call(() => setTooltipItemId(itemId), TOOLTIP_SHOW_DELAY);
+ control.call(() => setTooltipItemId(itemId), tooltipShowDelayRef.current);
},
hideTooltip(lock = false) {
control.call(() => setTooltipItemId(null), TOOLTIP_BLUR_DELAY);
@@ -86,34 +94,47 @@ export const ChartLegend = ({
control.lock(TOOLTIP_BLUR_DELAY);
}
},
+ cancelTooltip() {
+ control.cancelPending();
+ },
};
}, []);
+ useEffect(() => cancelTooltip, [cancelTooltip]);
useEffect(() => {
- if (!tooltipItemId) {
- return;
- }
const onDocumentKeyDown = (event: KeyboardEvent) => {
- if (event.keyCode === KeyCode.escape) {
+ if (event.keyCode !== KeyCode.escape) {
+ return;
+ }
+ if (tooltipItemId) {
hideTooltip(true);
elementsByIdRef.current[tooltipItemId]?.focus();
+ } else {
+ cancelTooltip();
}
};
document.addEventListener("keydown", onDocumentKeyDown, true);
return () => {
document.removeEventListener("keydown", onDocumentKeyDown, true);
};
- }, [tooltipItemId, hideTooltip]);
+ }, [tooltipItemId, hideTooltip, cancelTooltip]);
const isMouseInContainer = useRef(false);
// Scrolling to the highlighted legend item.
+ const getScrollIntoViewDelayRef = useRef(getScrollIntoViewDelay);
+ getScrollIntoViewDelayRef.current = getScrollIntoViewDelay;
useEffect(() => {
const highlightedIndex = items.findIndex((item) => item.highlighted);
if (highlightedIndex === -1) {
return;
}
- scrollIntoViewControl.call(() => {
+ const scroll = () => {
+ const delay = getScrollIntoViewDelayRef.current?.() ?? 0;
+ if (delay > 0) {
+ scrollIntoViewControl.call(scroll, delay);
+ return;
+ }
if (isMouseInContainer.current) {
return;
}
@@ -122,14 +143,15 @@ export const ChartLegend = ({
return;
}
scrollIntoViewNearestContainer(element, { behavior: "smooth", scrollMode: "if-needed" });
- }, SCROLL_DELAY);
+ };
+ scrollIntoViewControl.call(scroll, getScrollIntoViewDelayRef.current?.() ?? SCROLL_DELAY);
}, [items, scrollIntoViewControl]);
- const showHighlight = (itemId: string) => {
+ const showHighlight = (itemId: string, pointer = false) => {
const item = items.find((item) => item.id === itemId);
if (item?.visible) {
- highlightControl.cancelPrevious();
- onItemHighlightEnter(item);
+ highlightControl.cancelPending();
+ onItemHighlightEnter(item, { pointer });
}
};
const clearHighlight = () => {
@@ -265,10 +287,11 @@ export const ChartLegend = ({
{items.map((item, index) => {
const handlers = {
onMouseEnter: () => {
- showHighlight(item.id);
+ showHighlight(item.id, true);
showTooltip(item.id);
},
onMouseLeave: () => {
+ onItemHoverLeave?.();
clearHighlight();
hideTooltip();
},
diff --git a/src/internal/utils/__tests__/utils.test.ts b/src/internal/utils/__tests__/utils.test.ts
index a40444f0..7133b029 100644
--- a/src/internal/utils/__tests__/utils.test.ts
+++ b/src/internal/utils/__tests__/utils.test.ts
@@ -1,7 +1,9 @@
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
-import { escapeHtml } from "../../../../lib/components/internal/utils/utils";
+import { vi } from "vitest";
+
+import { DebouncedCall, escapeHtml } from "../../../../lib/components/internal/utils/utils";
describe("escapeHtml", () => {
test.each([
@@ -19,3 +21,83 @@ describe("escapeHtml", () => {
expect(escapeHtml(input)).toBe(expected);
});
});
+
+describe("DebouncedCall", () => {
+ beforeEach(() => vi.useFakeTimers());
+ afterEach(() => vi.useRealTimers());
+
+ test("keeps a pending call for the same key instead of restarting the delay", () => {
+ const debounced = new DebouncedCall();
+ const first = vi.fn();
+ const second = vi.fn();
+
+ expect(debounced.call(first, 100, "a")).toBe(true);
+ vi.advanceTimersByTime(60);
+ expect(debounced.call(second, 100, "a")).toBe(false);
+ vi.advanceTimersByTime(40);
+
+ expect(first).toHaveBeenCalledTimes(1);
+ expect(second).not.toHaveBeenCalled();
+ });
+
+ test("replaces a pending call for a different key", () => {
+ const debounced = new DebouncedCall();
+ const first = vi.fn();
+ const second = vi.fn();
+
+ debounced.call(first, 100, "a");
+ vi.advanceTimersByTime(60);
+ debounced.call(second, 100, "b");
+ vi.advanceTimersByTime(60);
+
+ expect(first).not.toHaveBeenCalled();
+ expect(second).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(40);
+
+ expect(second).toHaveBeenCalledTimes(1);
+ });
+
+ test("compares keys with the given function", () => {
+ const debounced = new DebouncedCall<{ id: string }>((a, b) => a.id === b.id);
+ const first = vi.fn();
+
+ debounced.call(first, 100, { id: "a" });
+ expect(debounced.call(vi.fn(), 100, { id: "a" })).toBe(false);
+ vi.advanceTimersByTime(100);
+
+ expect(first).toHaveBeenCalledTimes(1);
+ });
+
+ test("runs the pending call at once on flush", () => {
+ const debounced = new DebouncedCall();
+ const callback = vi.fn();
+
+ debounced.call(callback, 100);
+ debounced.flush();
+ vi.advanceTimersByTime(100);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ test("reports whether a call was pending when cancelled", () => {
+ const debounced = new DebouncedCall();
+ const callback = vi.fn();
+
+ debounced.call(callback, 100);
+
+ expect(debounced.cancelPending()).toBe(true);
+ expect(debounced.cancelPending()).toBe(false);
+ vi.advanceTimersByTime(100);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ test("calls at once without a delay", () => {
+ const debounced = new DebouncedCall();
+ const callback = vi.fn();
+
+ expect(debounced.call(callback, -1, "a")).toBe(false);
+ expect(callback).toHaveBeenCalledTimes(1);
+ expect(debounced.cancelPending()).toBe(false);
+ });
+});
diff --git a/src/internal/utils/highcharts.ts b/src/internal/utils/highcharts.ts
index 661fa3fd..28e4062c 100644
--- a/src/internal/utils/highcharts.ts
+++ b/src/internal/utils/highcharts.ts
@@ -39,8 +39,11 @@ export function getChartSeries(chart: SafeChart): SafeSeries[] {
* Returns point series or series it is linked to.
*/
export function getMasterSeries(point: Point): SafeSeries {
- const masterSeries = point.series.linkedParent ?? point.series;
- return masterSeries;
+ return getMasterSeriesOf(point.series);
+}
+
+export function getMasterSeriesOf(series: SafeSeries): SafeSeries {
+ return series.linkedParent ?? series;
}
/**
diff --git a/src/internal/utils/use-debounced-value.tsx b/src/internal/utils/use-debounced-value.tsx
index a3722093..6039d3a4 100644
--- a/src/internal/utils/use-debounced-value.tsx
+++ b/src/internal/utils/use-debounced-value.tsx
@@ -22,7 +22,9 @@ export function useDebouncedValue(value: T, duration: number) {
setShouldRender(true);
}, duration);
- return () => current.cancelPrevious();
+ return () => {
+ current.cancelPending();
+ };
}, [value, duration]);
if (duration <= 0) {
diff --git a/src/internal/utils/utils.ts b/src/internal/utils/utils.ts
index 083cf8e7..009a2eb5 100644
--- a/src/internal/utils/utils.ts
+++ b/src/internal/utils/utils.ts
@@ -39,24 +39,42 @@ export function escapeHtml(value: string): string {
return value.replace(/[&<>"']/g, (char) => htmlEscapes[char]);
}
-export class DebouncedCall {
+export class DebouncedCall {
private locked = false;
private lockTimeoutRef = setTimeout(() => {}, 0);
private timeoutRef = setTimeout(() => {}, 0);
+ private pending: null | { callback: () => void; key?: Key } = null;
- public call(callback: () => void, delay = -1) {
- if (!this.locked) {
- this.cancelPrevious();
- if (delay === -1) {
- callback();
- } else {
- this.timeoutRef = setTimeout(callback, delay);
- }
+ constructor(private isSameKey: (a: Key, b: Key) => boolean = (a, b) => a === b) {}
+
+ public call(callback: () => void, delay = -1, key?: Key): boolean {
+ if (this.locked) {
+ return false;
+ }
+ if (key !== undefined && this.pending?.key !== undefined && this.isSameKey(this.pending.key, key)) {
+ return false;
}
+ this.cancelPending();
+ if (delay === -1) {
+ callback();
+ return false;
+ }
+ this.pending = { callback, key };
+ this.timeoutRef = setTimeout(this.flush, delay);
+ return true;
}
- public cancelPrevious() {
+ public flush = () => {
+ const pending = this.pending;
+ this.cancelPending();
+ pending?.callback();
+ };
+
+ public cancelPending(): boolean {
+ const hadPending = this.pending !== null;
clearTimeout(this.timeoutRef);
+ this.pending = null;
+ return hadPending;
}
public lock(timeout: number) {
diff --git a/test/functional/hover-debounce.test.ts b/test/functional/hover-debounce.test.ts
new file mode 100644
index 00000000..b28bd2d1
--- /dev/null
+++ b/test/functional/hover-debounce.test.ts
@@ -0,0 +1,85 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { expect, test } from "vitest";
+
+import "@cloudscape-design/components/test-utils/selectors";
+import "../../lib/components/test-utils/selectors";
+import createWrapper from "../../lib/components/test-utils/selectors";
+import CoreChartWrapper from "../../lib/components/test-utils/selectors/internal/core";
+import { setupTest } from "../utils";
+
+import coreTestClasses from "../../lib/components/core/test-classes/styles.selectors.js";
+import legendTestClasses from "../../lib/components/internal/components/chart-legend/test-classes/styles.selectors.js";
+
+const chart = createWrapper().findComponent(`.${coreTestClasses.root}`, CoreChartWrapper);
+const tooltip = chart.findTooltip().toSelector();
+const tooltipHeader = chart.findTooltip().findHeader().toSelector();
+const dimmedLegendItems = `${chart.findLegend().toSelector()} .${legendTestClasses["dimmed-item"]}`;
+const inactiveSeries = `${chart.toSelector()} .highcharts-series-inactive`;
+const cursorMarkers = `${chart.toSelector()} .${coreTestClasses["highlight-marker"]}`;
+const point = (series: number, index: number) =>
+ `${chart.toSelector()} g.highcharts-markers.highcharts-series-${series} path.highcharts-point:nth-child(${index})`;
+const legendItem = (index: number) => chart.findLegend().findItems().get(index).toSelector();
+
+const pageUrl = (hoverDebounce: number) => `#/03-core/core-line-chart?hoverDebounce=${hoverDebounce}`;
+
+type ChartPage = Parameters[1]>[0];
+
+async function center(page: ChartPage, selector: string) {
+ const box = await page.getBoundingBox(selector);
+ return [box.left + box.width / 2, box.top + box.height / 2] as const;
+}
+
+test(
+ "shows the cursor at once and the tooltip once the delay passes",
+ setupTest(pageUrl(1000), async (page) => {
+ const [x, y] = await center(page, point(0, 10));
+ await page.moveCursorTo(x, y);
+
+ await expect(page.getElementsCount(cursorMarkers)).resolves.toBeGreaterThan(0);
+ await expect(page.isExisting(tooltip)).resolves.toBe(false);
+
+ await page.waitForAssertion(() => expect(page.isExisting(tooltip)).resolves.toBe(true));
+ }),
+);
+
+test(
+ "keeps the current tooltip while the pointer moves to another point until it rests",
+ setupTest(pageUrl(1000), async (page) => {
+ const [ax, ay] = await center(page, point(0, 10));
+ await page.moveCursorTo(ax, ay);
+ await page.waitForAssertion(() => expect(page.isExisting(tooltip)).resolves.toBe(true));
+ const [firstHeader] = await page.getElementsText(tooltipHeader);
+
+ const [bx, by] = await center(page, point(1, 25));
+ await page.moveCursorTo(bx, by);
+ await expect(page.getElementsText(tooltipHeader)).resolves.toEqual([firstHeader]);
+
+ await page.waitForAssertion(() => expect(page.getElementsText(tooltipHeader)).resolves.not.toEqual([firstHeader]));
+ }),
+);
+
+test(
+ "delays dimming the other series when hovering a legend item",
+ setupTest(pageUrl(1000), async (page) => {
+ const [x, y] = await center(page, legendItem(1));
+ await page.moveCursorTo(x, y);
+
+ await expect(page.getElementsCount(dimmedLegendItems)).resolves.toBe(0);
+ await expect(page.getElementsCount(inactiveSeries)).resolves.toBe(0);
+
+ await page.waitForAssertion(() => expect(page.getElementsCount(dimmedLegendItems)).resolves.toBeGreaterThan(0));
+ await expect(page.getElementsCount(inactiveSeries)).resolves.toBeGreaterThan(0);
+ }),
+);
+
+test(
+ "shows the tooltip immediately when the delay is 0",
+ setupTest(pageUrl(0), async (page) => {
+ const [x, y] = await center(page, point(0, 10));
+ await page.moveCursorTo(x, y);
+
+ await expect(page.isExisting(tooltip)).resolves.toBe(true);
+ }),
+);