feat: add onLegendHover callback

Author: jsilll

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

@@ -5,8 +5,8 @@ import { act } from "react";
 import highcharts from "highcharts";
 import { vi } from "vitest";
 
-import { CoreChartAPI } from "../../../lib/components/core/interfaces";
-import { renderChart, selectLegendItem } from "./common";
+import { CoreChartProps } from "../interfaces";
+import { hoverLegendItem, renderChart, selectLegendItem } from "./common";
 import { HighchartsTestHelper } from "./highcharts-utils";
 
 const clearHighlightPause = () => new Promise((resolve) => setTimeout(resolve, 100));
@@ -32,7 +32,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 +55,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 +74,30 @@ 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("calls onLegendHover when hovering over a legend item", () => {
+    const onLegendHover = vi.fn();
+    const { wrapper } = renderChart({ highcharts, options: { series }, onLegendHover });
+
+    hoverLegendItem(0, wrapper);
+
+    expect(onLegendHover).toHaveBeenCalledWith(
+      expect.objectContaining({
+        item: expect.objectContaining({
+          id: "Line 1",
+          name: "Line 1",
+          marker: expect.any(Object),
+          visible: expect.any(Boolean),
+          highlighted: expect.any(Boolean),
+        }),
+      }),
+    );
+  });
 });

src/core/__tests__/common.tsx

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { act, useState } from "react";
-import { render } from "@testing-library/react";
+import { fireEvent, render } from "@testing-library/react";
 
 import "@cloudscape-design/components/test-utils/dom";
 import { CoreChartProps } from "../../../lib/components/core/interfaces";
@@ -86,3 +86,8 @@ export function toggleLegendItem(index: number, wrapper: BaseChartWrapper = crea
   const modifier = Math.random() > 0.5 ? { metaKey: true } : { ctrlKey: true };
   act(() => wrapper.findLegend()!.findItems()[index].click(modifier));
 }
+export function hoverLegendItem(index: number, wrapper: BaseChartWrapper = createChartWrapper()) {
+  act(() => {
+    fireEvent.mouseOver(wrapper.findLegend()!.findItems()[index].getElement());
+  });
+}

src/core/chart-core.tsx

@@ -58,6 +58,7 @@ export function InternalCoreChart({
   filter,
   keyboardNavigation = true,
   onHighlight,
+  onLegendHover,
   onClearHighlight,
   onVisibleItemsChange,
   visibleItems,
@@ -307,6 +308,7 @@ export function InternalCoreChart({
               position={legendPosition}
               api={api}
               i18nStrings={i18nStrings}
+              onItemHover={onLegendHover}
               getLegendTooltipContent={rest.getLegendTooltipContent}
             />
           ) : null

src/core/components/core-legend.tsx

@@ -14,13 +14,15 @@ export function ChartLegend({
   actions,
   position,
   i18nStrings,
+  onItemHover,
   getLegendTooltipContent,
 }: {
   api: ChartAPI;
   title?: string;
   actions?: React.ReactNode;
   position: "bottom" | "side";
   i18nStrings?: BaseI18nStrings;
+  onItemHover?: (detail: CoreChartProps.LegendHoverDetail) => void;
   getLegendTooltipContent?: CoreChartProps.GetLegendTooltipContent;
 }) {
   const i18n = useInternalI18n("[charts]");
@@ -39,8 +41,11 @@ export function ChartLegend({
       actions={actions}
       position={position}
       onItemVisibilityChange={api.onItemVisibilityChange}
-      onItemHighlightEnter={(itemId) => api.onHighlightChartItems([itemId])}
       onItemHighlightExit={api.onClearChartItemsHighlight}
+      onItemHighlightEnter={(item) => {
+        api.onHighlightChartItems([item.id]);
+        onItemHover?.({ item });
+      }}
       getTooltipContent={(props) => {
         if (isChartTooltipPinned) {
           return null;

src/core/interfaces.ts

@@ -341,6 +341,10 @@ export interface CoreChartProps
    * IDs of visible series or points.
    */
   visibleItems?: readonly string[];
+  /**
+   * Called when the user hovers over a legend item.
+   */
+  onLegendHover?: (detail: CoreChartProps.LegendHoverDetail) => void;
   /**
    * Called when series/points visibility changes due to user interaction with legend or filter.
    */
@@ -440,6 +444,9 @@ export namespace CoreChartProps {
     items: TooltipContentItem[];
   }
 
+  export interface LegendHoverDetail {
+    item: LegendItem;
+  }
   export interface VisibleItemsChangeDetail {
     items: readonly LegendItem[];
     isApiCall: boolean;

src/internal/components/chart-legend/index.tsx

@@ -32,7 +32,7 @@ export interface ChartLegendProps {
   ariaLabel?: string;
   actions?: React.ReactNode;
   position: "bottom" | "side";
-  onItemHighlightEnter: (itemId: string) => void;
+  onItemHighlightEnter: (item: LegendItem) => void;
   onItemHighlightExit: () => void;
   onItemVisibilityChange: (hiddenItems: string[]) => void;
   getTooltipContent: (props: GetLegendTooltipContentProps) => null | LegendTooltipContent;
@@ -120,7 +120,7 @@ export const ChartLegend = ({
     const item = items.find((item) => item.id === itemId);
     if (item?.visible) {
       highlightControl.cancelPrevious();
-      onItemHighlightEnter(itemId);
+      onItemHighlightEnter(item);
     }
   };
   const clearHighlight = () => {