feat: add onLegendItemHighlight callback (#66)

* feat: add onLegendHover callback

* fix tests

* fix: improve naming

* rename missing type

Author: jsilll

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

@@ -3,10 +3,11 @@
 
 import { act } from "react";
 import highcharts from "highcharts";
+import { vi } from "vitest";
 
 import { KeyCode } from "@cloudscape-design/component-toolkit/internal";
 
-import { createChartWrapper, renderChart } from "./common";
+import { createChartWrapper, hoverLegendItem, renderChart } from "./common";
 import { HighchartsTestHelper } from "./highcharts-utils";
 
 import legendTestClasses from "../../../lib/components/internal/components/chart-legend/test-classes/styles.selectors.js";
@@ -451,4 +452,23 @@ describe("CoreChart: legend", () => {
       expect(wrapper.findLegend()!.findItemTooltip()!.findHeader()!.getElement().textContent).toBe("P2");
     });
   });
+
+  test("calls onLegendItemHighlight when hovering over a legend item", () => {
+    const onLegendItemHighlight = vi.fn();
+    const { wrapper } = renderChart({ highcharts, options: { series }, onLegendItemHighlight });
+
+    hoverLegendItem(0, wrapper);
+
+    expect(onLegendItemHighlight).toHaveBeenCalledWith(
+      expect.objectContaining({
+        item: expect.objectContaining({
+          id: "L1",
+          name: "L1",
+          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";
@@ -33,6 +33,7 @@ export function StatefulChart(props: CoreChartProps) {
 }
 
 type TestProps = Partial<CoreChartProps> & {
+  onLegendItemHighlight?: () => void;
   i18nProvider?: Record<string, Record<string, string>>;
 };
 
@@ -86,3 +87,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,
+  onLegendItemHighlight,
   onClearHighlight,
   onVisibleItemsChange,
   visibleItems,
@@ -307,6 +308,7 @@ export function InternalCoreChart({
               position={legendPosition}
               api={api}
               i18nStrings={i18nStrings}
+              onItemHighlight={onLegendItemHighlight}
               getLegendTooltipContent={rest.getLegendTooltipContent}
             />
           ) : null

src/core/components/core-legend.tsx

@@ -14,13 +14,15 @@ export function ChartLegend({
   actions,
   position,
   i18nStrings,
+  onItemHighlight,
   getLegendTooltipContent,
 }: {
   api: ChartAPI;
   title?: string;
   actions?: React.ReactNode;
   position: "bottom" | "side";
   i18nStrings?: BaseI18nStrings;
+  onItemHighlight?: (detail: CoreChartProps.LegendItemHighlightDetail) => 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]);
+        onItemHighlight?.({ 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 a legend item is highlighted.
+   */
+  onLegendItemHighlight?: (detail: CoreChartProps.LegendItemHighlightDetail) => void;
   /**
    * Called when series/points visibility changes due to user interaction with legend or filter.
    */
@@ -441,6 +445,9 @@ export namespace CoreChartProps {
     items: TooltipContentItem[];
   }
 
+  export interface LegendItemHighlightDetail {
+    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 = () => {