refactor(chart): standardize chart mark identity and hover logic

Sayhi-bzb · Sayhi-bzb · commit daa7eb97a964 · 2026-06-12T18:04:59.000+08:00
centralize chart mark key generation and hover state handling into shared helpers, replace ad-hoc hover logic across all chart components
diff --git a/agent-html/components/chart/README.md b/agent-html/components/chart/README.md
@@ -176,6 +176,9 @@ Use visx primitives by responsibility:
 
 - `components/ui/chart.tsx` owns generic hover state, presence, opacity, and transition
   tokens.
+- `components/ui/chart.tsx` owns mark identity helpers. Discrete charts use
+  `getChartMarkKey`, `getChartMarkPresence`, and `getChartMarkOpacity` instead
+  of hand-built hover keys or local opacity branches.
 - `BarChart`, `BarHChart`, `PieChart`, `HeatmapChart`, `NetworkChart`, and
   `SankeyChart` consume the shared hover protocol for highlighted and faded
   marks.
diff --git a/agent-html/components/chart/bar-chart.tsx b/agent-html/components/chart/bar-chart.tsx
@@ -21,9 +21,10 @@ import {
   createBandScale,
   createCartesianLayout,
   createLinearScale,
-  getChartHoverOpacity,
-  getChartHoverPresence,
   getChartCssVariable,
+  getChartMarkKey,
+  getChartMarkOpacity,
+  getChartMarkPresence,
   getFiniteValues,
   getValue,
   isFiniteNumber,
@@ -361,15 +362,16 @@ function BarChartCore<T>({
                   }
 
                   const rect = model.getBarRect(datum, value)
-                  const presence = getChartHoverPresence({
+                  const key = getChartMarkKey("bar", category)
+                  const presence = getChartMarkPresence({
                     hover,
-                    isRelated: hover?.key === category,
+                    key,
                   })
-                  const opacity = getChartHoverOpacity({ presence })
+                  const opacity = getChartMarkOpacity({ presence })
                   const showTooltip = (
                     event: React.PointerEvent<SVGRectElement>
                   ) => {
-                    setHover({ key: category, type: "bar" })
+                    setHover({ key, type: "bar" })
                     showMarkTooltip(event, {
                       datum,
                     })
diff --git a/agent-html/components/chart/heatmap-chart.tsx b/agent-html/components/chart/heatmap-chart.tsx
@@ -16,6 +16,9 @@ import {
   ChartTooltipPanel,
   chartMotion,
   getChartCssVariable,
+  getChartMarkKey,
+  getChartMarkOpacity,
+  getChartMarkPresence,
   getValue,
   isFiniteNumber,
   useChartMarkTooltip,
@@ -238,9 +241,19 @@ export function HeatmapChart<T>({
                     <>
                       {heatmap.flatMap((column) =>
                         column.map((cell) => {
-                          const key = `${cell.datum.key}-${cell.bin.key}`
-                          const isActive = hover?.key === key
-                          const opacity = isActive ? 1 : cell.opacity
+                          const key = getChartMarkKey(
+                            "cell",
+                            cell.datum.key,
+                            cell.bin.key
+                          )
+                          const presence = getChartMarkPresence({
+                            hover,
+                            key,
+                          })
+                          const opacity = getChartMarkOpacity({
+                            baseOpacity: cell.opacity,
+                            presence,
+                          })
 
                           return (
                             <g key={key}>
diff --git a/agent-html/components/chart/network-chart.tsx b/agent-html/components/chart/network-chart.tsx
@@ -16,8 +16,9 @@ import {
   ChartTooltipPanel,
   type ChartRenderer,
   chartMotion,
-  getChartHoverOpacity,
-  getChartHoverPresence,
+  getChartMarkKey,
+  getChartMarkOpacity,
+  getChartMarkPresence,
   isFiniteNumber,
   useChartMarkTooltip,
 } from "../ui/chart"
@@ -223,7 +224,7 @@ function resolveNetworkGraph<
 
     return {
       datum: link,
-      key: `${link.source}-${link.target}-${index}`,
+      key: getChartMarkKey("link", link.source, link.target, index),
       source,
       target,
       width,
@@ -233,13 +234,6 @@ function resolveNetworkGraph<
   return { links, nodes }
 }
 
-function isLinkRelatedToNode<
-  TNode extends NetworkNodeDatum,
-  TLink extends NetworkLinkDatum,
->(link: PositionedLink<TNode, TLink>, nodeId: string) {
-  return link.source.id === nodeId || link.target.id === nodeId
-}
-
 function isNodeRelatedToLink<
   TNode extends NetworkNodeDatum,
   TLink extends NetworkLinkDatum,
@@ -335,16 +329,16 @@ function NetworkLinkMark<
     showTooltip,
   } = useNetworkRenderContext<TNode, TLink>()
   const linkIndex = graph.links.indexOf(link)
-  const presence = getChartHoverPresence({
+  const presence = getChartMarkPresence({
     hover,
+    key: link.key,
     isRelated:
-      hover?.type === "link"
-        ? hover.key === link.key
-        : hover?.type === "node"
-          ? isLinkRelatedToNode(link, String(hover.key))
-          : false,
+      hover?.type === "node"
+        ? hover.key === getChartMarkKey("node", link.source.id) ||
+          hover.key === getChartMarkKey("node", link.target.id)
+        : undefined,
   })
-  const opacity = getChartHoverOpacity({
+  const opacity = getChartMarkOpacity({
     baseOpacity: 0.72,
     presence,
   })
@@ -411,19 +405,19 @@ function NetworkNodeMark<TNode extends NetworkNodeDatum>({
     showTooltip,
   } = useNetworkRenderContext<TNode, NetworkLinkDatum>()
   const nodeIndex = graph.nodes.indexOf(node)
-  const presence = getChartHoverPresence({
+  const nodeKey = getChartMarkKey("node", node.id)
+  const presence = getChartMarkPresence({
     hover,
+    key: nodeKey,
     isRelated:
-      hover?.type === "node"
-        ? hover.key === node.id
-        : hover?.type === "link" && activeLink
-          ? isNodeRelatedToLink(node, activeLink)
-          : false,
+      hover?.type === "link" && activeLink
+        ? isNodeRelatedToLink(node, activeLink)
+        : undefined,
   })
-  const opacity = getChartHoverOpacity({ presence })
+  const opacity = getChartMarkOpacity({ presence })
   const color = getNodeColor?.(node, nodeIndex) ?? getDefaultNodeColor(node)
   const handlePointerEnter = (event: React.PointerEvent<SVGCircleElement>) => {
-    setHover({ key: node.id, type: "node" })
+    setHover({ key: nodeKey, type: "node" })
     showTooltip(event, {
       index: nodeIndex,
       type: "node",
diff --git a/agent-html/components/chart/pie-chart.tsx b/agent-html/components/chart/pie-chart.tsx
@@ -17,9 +17,10 @@ import {
   ChartTooltip,
   ChartTooltipContent,
   chartMotion,
-  getChartHoverOpacity,
-  getChartHoverPresence,
   getChartCssVariable,
+  getChartMarkKey,
+  getChartMarkOpacity,
+  getChartMarkPresence,
   getValue,
   isFiniteNumber,
   useChartMarkTooltip,
@@ -180,15 +181,16 @@ export function PieChart<T>({
                     {arcs.map((arc) => {
                       const d = path(arc) ?? ""
                       const color = getChartCssVariable(arc.data.key)
-                      const presence = getChartHoverPresence({
+                      const key = getChartMarkKey("slice", arc.data.key)
+                      const presence = getChartMarkPresence({
                         hover,
-                        isRelated: hover?.key === arc.data.key,
+                        key,
                       })
-                      const opacity = getChartHoverOpacity({ presence })
+                      const opacity = getChartMarkOpacity({ presence })
                       const showTooltip = (
                         event: React.PointerEvent<SVGPathElement>
                       ) => {
-                        setHover({ key: arc.data.key, type: "slice" })
+                        setHover({ key, type: "slice" })
                         showMarkTooltip(event, {
                           slice: arc.data,
                         })
diff --git a/agent-html/components/chart/sankey-chart.tsx b/agent-html/components/chart/sankey-chart.tsx
@@ -27,8 +27,9 @@ import {
   ChartTooltipPanel,
   chartHoverOpacity,
   chartMotion,
-  getChartHoverOpacity,
-  getChartHoverPresence,
+  getChartMarkKey,
+  getChartMarkOpacity,
+  getChartMarkPresence,
   useChartMarkTooltip,
 } from "../ui/chart";
 import { RoughPath } from "@/lib/rough-svg";
@@ -119,6 +120,14 @@ type NodeOrIndex = SankeyNodeType<SankeyNodeDatum, SankeyLinkDatum> | number;
 const DEFAULT_MARGIN: Margin = { top: 40, right: 180, bottom: 40, left: 180 };
 const intFmt = new Intl.NumberFormat("en-US").format;
 
+function getSankeyLinkKey(index: number) {
+  return getChartMarkKey("link", index);
+}
+
+function getSankeyNodeKey(index: number) {
+  return getChartMarkKey("node", index);
+}
+
 function getNodeIndex(nodeOrIndex: NodeOrIndex): number | undefined {
   if (typeof nodeOrIndex === "number") {
     return nodeOrIndex;
@@ -349,23 +358,26 @@ function SankeyLinks({
         const roughPath = roughOptions ? createRibbonPath(link) : undefined;
         const sourceIndex = getNodeIndex(link.source as NodeOrIndex) ?? -1;
         const targetIndex = getNodeIndex(link.target as NodeOrIndex) ?? -1;
-        const presence = getChartHoverPresence({
+        const linkKey = getSankeyLinkKey(index);
+        const presence = getChartMarkPresence({
           hover,
+          key: linkKey,
           isRelated:
-            hover?.type === "link"
-              ? hover.key === index
-              : hover?.key === sourceIndex || hover?.key === targetIndex,
+            hover?.type === "node"
+              ? hover.key === getSankeyNodeKey(sourceIndex) ||
+                hover.key === getSankeyNodeKey(targetIndex)
+              : undefined,
         });
         const stroke = getLinkColor
           ? getLinkColor(link, index)
           : "var(--chart-line-primary)";
-        const targetOpacity = getChartHoverOpacity({
+        const targetOpacity = getChartMarkOpacity({
           baseOpacity: strokeOpacity,
           presence,
         });
 
         const handlePointerEnter = (event: React.PointerEvent<Element>) => {
-          setHover({ key: index, type: "link" });
+          setHover({ key: linkKey, type: "link" });
           showTooltip(event, { type: "link", linkIndex: index });
         };
         const handlePointerLeave = () => {
@@ -379,7 +391,7 @@ function SankeyLinks({
             <ChartMotionGroup
               animate={{ opacity: targetOpacity }}
               initial={{ opacity: strokeOpacity }}
-              key={`link-${sourceIndex}-${targetIndex}-${link.width ?? link.value ?? ""}`}
+              key={linkKey}
               onPointerEnter={handlePointerEnter}
               onPointerLeave={handlePointerLeave}
               style={{ cursor: "pointer" }}
@@ -406,7 +418,7 @@ function SankeyLinks({
             d={path}
             fill="none"
             initial={{ opacity: strokeOpacity }}
-            key={`link-${sourceIndex}-${targetIndex}-${link.width ?? link.value ?? ""}`}
+            key={linkKey}
             onPointerEnter={handlePointerEnter}
             onPointerLeave={handlePointerLeave}
             stroke={stroke}
@@ -455,8 +467,10 @@ function SankeyNodes({
         const nodeY = node.y0 ?? 0;
         const nodeWidth = (node.x1 ?? 0) - nodeX;
         const nodeHeight = (node.y1 ?? 0) - nodeY;
-        const presence = getChartHoverPresence({
+        const nodeKey = getSankeyNodeKey(index);
+        const presence = getChartMarkPresence({
           hover,
+          key: nodeKey,
           isRelated: isNodeConnected({ hover, links, nodeIndex: index }),
         });
         const isLeftSide = nodeX < innerWidth / 2;
@@ -468,7 +482,7 @@ function SankeyNodes({
           presence === "faded" ? chartHoverOpacity.textFaded : 0.6;
 
         const handlePointerEnter = (event: React.PointerEvent<Element>) => {
-          setHover({ key: index, type: "node" });
+          setHover({ key: nodeKey, type: "node" });
           showTooltip(event, { type: "node", nodeIndex: index });
         };
         const handlePointerLeave = () => {
@@ -514,20 +528,24 @@ function isNodeConnected({
   }
 
   if (hover.type === "node") {
-    if (hover.key === nodeIndex) {
+    if (hover.key === getSankeyNodeKey(nodeIndex)) {
       return true;
     }
     return links.some((link) => {
       const sourceIndex = getNodeIndex(link.source as NodeOrIndex);
       const targetIndex = getNodeIndex(link.target as NodeOrIndex);
       return (
-        (sourceIndex === hover.key && targetIndex === nodeIndex) ||
-        (targetIndex === hover.key && sourceIndex === nodeIndex)
+        (sourceIndex !== undefined &&
+          getSankeyNodeKey(sourceIndex) === hover.key &&
+          targetIndex === nodeIndex) ||
+        (targetIndex !== undefined &&
+          getSankeyNodeKey(targetIndex) === hover.key &&
+          sourceIndex === nodeIndex)
       );
     });
   }
 
-  const link = links[Number(hover.key)];
+  const link = links.find((_, index) => getSankeyLinkKey(index) === hover.key);
   if (!link) {
     return false;
   }
diff --git a/agent-html/components/chart/scatter-chart.tsx b/agent-html/components/chart/scatter-chart.tsx
