fix(charts): descriptive aria labels for all chart types (a11y)

component/src/charts/__tests__/chart-aria.test.tsx

@@ -0,0 +1,118 @@
+import { render, screen, cleanup } from "@testing-library/react";
+import { describe, it, expect, vi, afterEach } from "vitest";
+
+// One place that verifies every chart gives BaseChart a descriptive aria-label
+// (was the generic "Chart visualization" fallback) and honours a caller
+// override. echarts/core + container size are stubbed so the charts mount.
+vi.mock("echarts/core", () => {
+  const init = vi.fn(() => ({
+    setOption: vi.fn(),
+    resize: vi.fn(),
+    dispose: vi.fn(),
+    on: vi.fn(),
+    off: vi.fn(),
+    showLoading: vi.fn(),
+    hideLoading: vi.fn(),
+  }));
+  const stub = {
+    use: vi.fn(),
+    init,
+    registerTheme: vi.fn(),
+    registerMap: vi.fn(),
+    getMap: vi.fn(() => ({})),
+    format: { encodeHTML: (s: string) => s },
+  };
+  return { ...stub, default: stub };
+});
+vi.mock("@/hooks/useContainerSize", () => ({
+  useContainerSize: () => ({ width: 600, height: 400, containerRef: vi.fn() }),
+}));
+
+import { PieChart } from "../pie-chart";
+import { RadarChart } from "../radar-chart";
+import { GaugeChart } from "../gauge-chart";
+import { SankeyChart } from "../sankey-chart";
+import { TreemapChart } from "../treemap-chart";
+import { SunburstChart } from "../sunburst-chart";
+import { CirclePackingChart } from "../circle-packing-chart";
+import { GanttChart } from "../gantt-chart";
+import { ChoroplethChart } from "../choropleth-chart";
+
+const cases: Array<[string, React.ReactElement, RegExp]> = [
+  [
+    "pie",
+    <PieChart data={[{ name: "A", value: 1 }]} />,
+    /Pie chart with 1 segments/,
+  ],
+  [
+    "radar",
+    <RadarChart
+      data={{
+        indicators: [{ name: "X", max: 10 }],
+        series: [{ name: "S", values: [5] }],
+      }}
+    />,
+    /Radar chart comparing 1 series across 1 axes/,
+  ],
+  [
+    "gauge",
+    <GaugeChart data={[{ value: 50 }]} />,
+    /Gauge showing 50 of 0 to 100/,
+  ],
+  [
+    "sankey",
+    <SankeyChart
+      data={{
+        nodes: [{ name: "A" }, { name: "B" }],
+        links: [{ source: "A", target: "B", value: 1 }],
+      }}
+    />,
+    /Sankey diagram with 2 nodes and 1 links/,
+  ],
+  [
+    "treemap",
+    <TreemapChart data={[{ name: "A", value: 1 }]} />,
+    /Treemap with 1 top-level items/,
+  ],
+  [
+    "sunburst",
+    <SunburstChart data={[{ name: "A", value: 1 }]} />,
+    /Sunburst chart with 1 top-level segments/,
+  ],
+  [
+    "circle-packing",
+    <CirclePackingChart data={[{ name: "A", value: 1 }]} />,
+    /Circle-packing chart with 1 top-level groups/,
+  ],
+  [
+    "gantt",
+    <GanttChart data={[{ task: "T", start: 0, end: 1 }]} />,
+    /Gantt chart with 1 tasks/,
+  ],
+  [
+    "choropleth",
+    <ChoroplethChart data={[{ name: "United States", value: 1 }]} />,
+    /Choropleth map with 1 regions/,
+  ],
+];
+
+afterEach(cleanup);
+
+describe("chart aria descriptions", () => {
+  it.each(cases)("%s gets a descriptive aria-label", (_name, el, re) => {
+    render(el);
+    expect(screen.getByTestId("base-chart").getAttribute("aria-label")).toMatch(
+      re,
+    );
+  });
+
+  it("honours a caller-provided ariaDescription override", () => {
+    render(
+      <PieChart data={[{ name: "A", value: 1 }]} ariaDescription="Custom" />,
+    );
+    expect(screen.getByTestId("base-chart")).toHaveAttribute(
+      "aria-label",
+      "Custom",
+    );
+  });
+});

component/src/charts/choropleth-chart.tsx

@@ -68,6 +68,7 @@ function ChoroplethChart({
   minColor = "#fff7d6",
   maxColor = "#993404",
   showLabels = false,
+  ariaDescription,
   ...rest
 }: ChoroplethChartProps) {
   const [mapRegistered, setMapRegistered] = useState(false);
@@ -206,7 +207,15 @@ function ChoroplethChart({
     showLabels,
   ]);
 
-  return <BaseChart options={options} {...rest} />;
+  return (
+    <BaseChart
+      options={options}
+      ariaDescription={
+        ariaDescription ?? `Choropleth map with ${data.length} regions`
+      }
+      {...rest}
+    />
+  );
 }
 
 export { ChoroplethChart };

component/src/charts/circle-packing-chart.tsx

@@ -59,6 +59,7 @@ function CirclePackingChart({
   padding = 3,
   stylingRules,
   paramValues,
+  ariaDescription,
   ...rest
 }: CirclePackingChartProps) {
   const { width, height, containerRef } = useContainerSize();
@@ -266,7 +267,14 @@ function CirclePackingChart({
 
   return (
     <div ref={containerRef} className="h-full w-full">
-      <BaseChart options={options} {...rest} />
+      <BaseChart
+        options={options}
+        ariaDescription={
+          ariaDescription ??
+          `Circle-packing chart with ${data.length} top-level groups`
+        }
+        {...rest}
+      />
     </div>
   );
 }

component/src/charts/gantt-chart.tsx

@@ -68,6 +68,7 @@ function GanttChart({
   showGridLines = true,
   stylingRules,
   paramValues,
+  ariaDescription,
   ...rest
 }: GanttChartProps) {
   const options = useMemo((): EChartsOption => {
@@ -323,7 +324,15 @@ function GanttChart({
     paramValues,
   ]);
 
-  return <BaseChart options={options} {...rest} />;
+  return (
+    <BaseChart
+      options={options}
+      ariaDescription={
+        ariaDescription ?? `Gantt chart with ${data.length} tasks`
+      }
+      {...rest}
+    />
+  );
 }
 
 export { GanttChart };

component/src/charts/gauge-chart.tsx

@@ -64,6 +64,7 @@ function GaugeChart({
   thresholdZones: thresholdZonesJson,
   stylingRules,
   paramValues,
+  ariaDescription,
   ...rest
 }: GaugeChartProps) {
   const { width, height, containerRef } = useContainerSize();
@@ -205,7 +206,14 @@ function GaugeChart({
 
   return (
     <div ref={containerRef} className="h-full w-full">
-      <BaseChart options={options} {...rest} />
+      <BaseChart
+        options={options}
+        ariaDescription={
+          ariaDescription ??
+          `Gauge showing ${data[0]?.value ?? 0} of ${min} to ${max}`
+        }
+        {...rest}
+      />
     </div>
   );
 }

component/src/charts/pie-chart.tsx

@@ -60,6 +60,7 @@ function PieChart({
   donutCenterText,
   stylingRules,
   paramValues,
+  ariaDescription,
   ...rest
 }: PieChartProps) {
   const { width, height, containerRef } = useContainerSize();
@@ -187,7 +188,13 @@ function PieChart({
 
   return (
     <div ref={containerRef} className="h-full w-full">
-      <BaseChart options={options} {...rest} />
+      <BaseChart
+        options={options}
+        ariaDescription={
+          ariaDescription ?? `Pie chart with ${data.length} segments`
+        }
+        {...rest}
+      />
     </div>
   );
 }

component/src/charts/radar-chart.tsx

@@ -69,6 +69,7 @@ function RadarChart({
   showValues = false,
   stylingRules,
   paramValues,
+  ariaDescription,
   ...rest
 }: RadarChartProps) {
   const { width, height, containerRef } = useContainerSize();
@@ -152,7 +153,14 @@ function RadarChart({
 
   return (
     <div ref={containerRef} className="h-full w-full">
-      <BaseChart options={options} {...rest} />
+      <BaseChart
+        options={options}
+        ariaDescription={
+          ariaDescription ??
+          `Radar chart comparing ${data.series.length} series across ${data.indicators.length} axes`
+        }
+        {...rest}
+      />
     </div>
   );
 }

component/src/charts/sankey-chart.tsx

@@ -56,6 +56,7 @@ function SankeyChart({
   nodeGap = 8,
   stylingRules,
   paramValues,
+  ariaDescription,
   ...rest
 }: SankeyChartProps) {
   const { width, height, containerRef } = useContainerSize();
@@ -76,7 +77,11 @@ function SankeyChart({
           data: data.nodes,
           links: stylingRules?.length
             ? data.links.map((link) => {
-                const resolvedColor = resolveItemColor(link.value, stylingRules, paramValues);
+                const resolvedColor = resolveItemColor(
+                  link.value,
+                  stylingRules,
+                  paramValues,
+                );
                 return {
                   ...link,
                   lineStyle: resolvedColor ? { color: resolvedColor } : {},
@@ -99,11 +104,27 @@ function SankeyChart({
         },
       ],
     };
-  }, [data, orient, showLabels, nodeWidth, nodeGap, compact, stylingRules, paramValues]);
+  }, [
+    data,
+    orient,
+    showLabels,
+    nodeWidth,
+    nodeGap,
+    compact,
+    stylingRules,
+    paramValues,
+  ]);
 
   return (
     <div ref={containerRef} className="h-full w-full">
-      <BaseChart options={options} {...rest} />
+      <BaseChart
+        options={options}
+        ariaDescription={
+          ariaDescription ??
+          `Sankey diagram with ${data.nodes.length} nodes and ${data.links.length} links`
+        }
+        {...rest}
+      />
     </div>
   );
 }

component/src/charts/sunburst-chart.tsx

@@ -54,6 +54,7 @@ function SunburstChart({
   highlightOnHover = true,
   stylingRules,
   paramValues,
+  ariaDescription,
   ...rest
 }: SunburstChartProps) {
   const { width, height, containerRef } = useContainerSize();
@@ -196,7 +197,14 @@ function SunburstChart({
 
   return (
     <div ref={containerRef} className="h-full w-full">
-      <BaseChart options={options} {...rest} />
+      <BaseChart
+        options={options}
+        ariaDescription={
+          ariaDescription ??
+          `Sunburst chart with ${data.length} top-level segments`
+        }
+        {...rest}
+      />
     </div>
   );
 }

component/src/charts/treemap-chart.tsx

@@ -60,6 +60,7 @@ function TreemapChart({
   colorSaturation = "medium",
   stylingRules,
   paramValues,
+  ariaDescription,
   ...rest
 }: TreemapChartProps) {
   const { width, height, containerRef } = useContainerSize();
@@ -174,7 +175,13 @@ function TreemapChart({
 
   return (
     <div ref={containerRef} className="h-full w-full">
-      <BaseChart options={options} {...rest} />
+      <BaseChart
+        options={options}
+        ariaDescription={
+          ariaDescription ?? `Treemap with ${data.length} top-level items`
+        }
+        {...rest}
+      />
     </div>
   );
 }