feat: add support for programmatically highlight chart items

Author: jsilll

src/core/__tests__/chart-core-api.test.tsx

@@ -5,7 +5,7 @@ import { act } from "react";
 import highcharts from "highcharts";
 import { vi } from "vitest";
 
-import { CoreChartAPI } from "../../../lib/components/core/interfaces";
+import { CoreChartProps } from "../../../lib/components/core/interfaces";
 import { renderChart, selectLegendItem } from "./common";
 import { HighchartsTestHelper } from "./highcharts-utils";
 
@@ -18,10 +18,27 @@ const series: Highcharts.SeriesOptionsType[] = [
   { type: "line", name: "Line 2", data: [4, 5, 6] },
 ];
 
+const threeSeries: Highcharts.SeriesOptionsType[] = [
+  { type: "line", name: "Line 1", data: [1, 2, 3] },
+  { type: "line", name: "Line 2", data: [4, 5, 6] },
+  { type: "line", name: "Line 3", data: [7, 8, 9] },
+];
+
+const pieSeries: Highcharts.SeriesOptionsType[] = [
+  {
+    type: "pie",
+    name: "Data",
+    data: [
+      { name: "Segment 1", y: 33.3 },
+      { name: "Segment 2", y: 33.3 },
+      { name: "Segment 3", y: 33.4 },
+    ],
+  },
+];
+
 describe("CoreChart: API tests", () => {
   test("passes isApiCall=false to onHighlight when triggered by an user interaction", () => {
     const onHighlight = vi.fn();
-    renderChart({ highcharts, options: { series }, onHighlight });
 
     act(() => hc.highlightChartPoint(0, 0));
 
@@ -32,7 +49,7 @@ describe("CoreChart: API tests", () => {
 
   test("passes isApiCall=true to onHighlight when triggered programmatically through API", () => {
     const onHighlight = vi.fn();
-    let chartApi: CoreChartAPI | null = null;
+    let chartApi: CoreChartProps.ChartAPI | null = null;
 
     renderChart({ highcharts, onHighlight, options: { series }, callback: (api) => (chartApi = api) });
 
@@ -55,7 +72,7 @@ describe("CoreChart: API tests", () => {
 
   test("passes isApiCall=true to onClearHighlight when triggered programmatically through API", () => {
     const onClearHighlight = vi.fn();
-    let chartApi: CoreChartAPI | null = null;
+    let chartApi: CoreChartProps.ChartAPI | null = null;
 
     renderChart({ highcharts, onClearHighlight, options: { series }, callback: (api) => (chartApi = api) });
 
@@ -74,11 +91,49 @@ describe("CoreChart: API tests", () => {
 
   test("passes isApiCall=true to onVisibleItemsChange when triggered programmatically through API", () => {
     const onVisibleItemsChange = vi.fn();
-    let chartApi: CoreChartAPI | null = null;
+    let chartApi: CoreChartProps.ChartAPI | null = null;
 
     renderChart({ highcharts, options: { series }, onVisibleItemsChange, callback: (api) => (chartApi = api) });
 
     act(() => chartApi!.setItemsVisible(["Line 1"]));
     expect(onVisibleItemsChange).toHaveBeenCalledWith({ items: expect.any(Array), isApiCall: true });
   });
+
+  test("highlightSeries should only highlight the specified series in a line chart", () => {
+    let chartApi: CoreChartProps.ChartAPI | null = null;
+    renderChart({ highcharts, options: { series: threeSeries }, callback: (api) => (chartApi = api) });
+
+    act(() => chartApi!.highlightItems([hc.getChartSeries(1).name]));
+
+    expect(hc.getChartSeries(0).state).toBe("inactive");
+    expect(hc.getChartSeries(1).state).not.toBe("inactive");
+    expect(hc.getChartSeries(2).state).toBe("inactive");
+
+    act(() => chartApi!.clearChartHighlight());
+    act(() => chartApi!.highlightItems([hc.getChartSeries(0).name, hc.getChartSeries(2).name]));
+
+    expect(hc.getChartSeries(0).state).not.toBe("inactive");
+    expect(hc.getChartSeries(1).state).toBe("inactive");
+    expect(hc.getChartSeries(2).state).not.toBe("inactive");
+  });
+
+  test("highlightChartPoint should only highlight the specified point in a pie chart", () => {
+    let chartApi: CoreChartProps.ChartAPI | null = null;
+    renderChart({ highcharts, options: { series: pieSeries }, callback: (api) => (chartApi = api) });
+
+    const series = hc.getChartSeries(0);
+
+    act(() => chartApi!.highlightItems([series.points[1].name]));
+
+    expect(hc.getChartPoint(0, 0).state).not.toBe("inactive");
+    expect(hc.getChartPoint(0, 1).state).toBe("hover");
+    expect(hc.getChartPoint(0, 2).state).not.toBe("inactive");
+
+    act(() => chartApi!.clearChartHighlight());
+    act(() => chartApi!.highlightItems([series.points[0].name, series.points[2].name]));
+
+    expect(hc.getChartPoint(0, 0).state).toBe("hover");
+    expect(hc.getChartPoint(0, 1).state).not.toBe("hover");
+    expect(hc.getChartPoint(0, 2).state).toBe("hover");
+  });
 });

src/core/__tests__/chart-core-rendering.test.tsx

@@ -38,6 +38,7 @@ describe("CoreChart: rendering", () => {
     expect(callback).toHaveBeenCalledWith({
       chart: hc.getChart(),
       highcharts,
+      highlightItems: expect.any(Function),
       setItemsVisible: expect.any(Function),
       highlightChartPoint: expect.any(Function),
       highlightChartGroup: expect.any(Function),

src/core/chart-api/index.tsx

@@ -208,6 +208,9 @@ export class ChartAPI {
 
   // 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.
+  public highlightChartItems = (itemIds: readonly string[]) => {
+    this.chartExtraHighlight.highlightChartItems(itemIds);
+  };
   public setItemsVisible = (visibleItemsIds: readonly string[], { isApiCall }: { isApiCall: boolean }) => {
     this.chartExtraLegend.onItemVisibilityChange(visibleItemsIds, { isApiCall });
   };
@@ -228,6 +231,7 @@ export class ChartAPI {
   };
   public get publicApi() {
     return {
+      highlightItems: (itemIds: readonly string[]) => this.highlightChartItems(itemIds),
       setItemsVisible: (visibleItemIds: readonly string[]) => this.setItemsVisible(visibleItemIds, { isApiCall: true }),
       highlightChartPoint: (point: Highcharts.Point) => this.highlightChartPoint(point, { isApiCall: true }),
       highlightChartGroup: (group: readonly Highcharts.Point[]) => this.highlightChartGroup(group, { isApiCall: true }),

src/core/interfaces.ts

@@ -379,6 +379,7 @@ export namespace CoreChartProps {
   export interface ChartAPI {
     chart: Highcharts.Chart;
     highcharts: typeof Highcharts;
+    highlightItems(itemIds: readonly string[]): void;
     setItemsVisible(itemIds: readonly string[]): void;
     highlightChartPoint(point: Highcharts.Point): void;
     highlightChartGroup(group: readonly Highcharts.Point[]): void;