@optilogic/charts 1.3.10 → 1.4.0

package/src/shared/chart-container.tsx

@@ -1,6 +1,12 @@
 import * as React from "react";
 import { ResponsiveContainer } from "recharts";
-import { cn } from "@optilogic/core";
+import { cn, VisuallyHidden } from "@optilogic/core";
+
+/** Column descriptor for the screen-reader data-table fallback. */
+export interface ChartTableColumn {
+  key: string;
+  label: string;
+}
 
 export interface ChartContainerProps {
   children: React.ReactNode;
@@ -11,6 +17,42 @@ export interface ChartContainerProps {
   emptyMessage?: string;
   title?: string;
   description?: string;
+  /**
+   * Accessible name for the visual chart region (SC 1.1.1). Falls back to
+   * `title` when omitted.
+   */
+  ariaLabel?: string;
+  /**
+   * Accessible description for the chart. Falls back to `description` when
+   * omitted. Exposed to assistive tech via `aria-describedby`.
+   */
+  ariaDescription?: string;
+  /**
+   * Row data rendered as a visually-hidden `<table>` so screen-reader users can
+   * access the underlying numbers (SC 1.1.1, 1.3.1). Requires `tableColumns`.
+   * Accepts any object row; cells are read by `tableColumns[].key`.
+   */
+  tableData?: ReadonlyArray<object>;
+  /** Column definitions for the data-table fallback. Requires `tableData`. */
+  tableColumns?: Array<ChartTableColumn>;
+  /**
+   * Makes each data point actionable (a "visualization link"). When provided, a
+   * keyboard- and screen-reader-reachable list of buttons is rendered — one per
+   * `tableData` row — that is visually hidden until focused (skip-link pattern),
+   * so pointer users click the chart while keyboard users tab to the same
+   * actions without an invisible-focus trap (WCAG SC 2.1.1, 2.4.7).
+   */
+  onRowActivate?: (row: object, index: number) => void;
+  /** Accessible label for a row's action. Defaults to the first column's value. */
+  rowActionLabel?: (row: object, index: number) => string;
+}
+
+function formatCell(value: unknown): string {
+  if (value == null) return "";
+  if (typeof value === "number") return value.toLocaleString();
+  if (value instanceof Date) return value.toLocaleString();
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
 }
 
 export const ChartContainer = React.forwardRef<
@@ -26,9 +68,27 @@ export const ChartContainer = React.forwardRef<
     emptyMessage = "No data available",
     title,
     description,
+    ariaLabel,
+    ariaDescription,
+    tableData,
+    tableColumns,
+    onRowActivate,
+    rowActionLabel,
   },
   ref,
 ) {
+  const descriptionId = React.useId();
+  const accessibleName = ariaLabel ?? title;
+  const accessibleDescription = ariaDescription ?? description;
+
+  const hasTable =
+    !loading &&
+    !empty &&
+    !!tableData &&
+    tableData.length > 0 &&
+    !!tableColumns &&
+    tableColumns.length > 0;
+
   return (
     <div ref={ref} className={cn("w-full", className)} style={{ height }}>
       {(title || description) && (
@@ -92,12 +152,79 @@ export const ChartContainer = React.forwardRef<
           {emptyMessage}
         </div>
       ) : (
-        <ResponsiveContainer
-          width="100%"
-          height={title || description ? "calc(100% - 40px)" : "100%"}
+        <div
+          role="img"
+          aria-label={accessibleName}
+          aria-describedby={
+            accessibleDescription ? descriptionId : undefined
+          }
+          className="relative"
+          style={{
+            width: "100%",
+            height: title || description ? "calc(100% - 40px)" : "100%",
+          }}
         >
-          {children as React.ReactElement}
-        </ResponsiveContainer>
+          {accessibleDescription && (
+            <VisuallyHidden as="span" id={descriptionId}>
+              {accessibleDescription}
+            </VisuallyHidden>
+          )}
+          <ResponsiveContainer width="100%" height="100%">
+            {children as React.ReactElement}
+          </ResponsiveContainer>
+          {hasTable && (
+            <VisuallyHidden as="div">
+              <table>
+                {accessibleName && <caption>{accessibleName}</caption>}
+                <thead>
+                  <tr>
+                    {tableColumns.map((col) => (
+                      <th key={col.key} scope="col">
+                        {col.label}
+                      </th>
+                    ))}
+                  </tr>
+                </thead>
+                <tbody>
+                  {tableData.map((row, rowIndex) => {
+                    const record = row as Record<string, unknown>;
+                    return (
+                      <tr key={rowIndex}>
+                        {tableColumns.map((col) => (
+                          <td key={col.key}>{formatCell(record[col.key])}</td>
+                        ))}
+                      </tr>
+                    );
+                  })}
+                </tbody>
+              </table>
+            </VisuallyHidden>
+          )}
+          {hasTable && onRowActivate && (
+            <nav
+              aria-label={`${accessibleName ?? "Chart"} data point links`}
+              className="sr-only focus-within:not-sr-only focus-within:absolute focus-within:z-20 focus-within:top-1 focus-within:left-1 focus-within:flex focus-within:max-h-[calc(100%-0.5rem)] focus-within:flex-col focus-within:gap-1 focus-within:overflow-auto focus-within:rounded-md focus-within:border focus-within:border-border focus-within:bg-popover focus-within:p-2 focus-within:shadow-md"
+            >
+              {tableData.map((row, rowIndex) => {
+                const record = row as Record<string, unknown>;
+                const firstKey = tableColumns[0]?.key;
+                const label =
+                  rowActionLabel?.(row, rowIndex) ??
+                  (firstKey ? formatCell(record[firstKey]) : `Row ${rowIndex + 1}`);
+                return (
+                  <button
+                    key={rowIndex}
+                    type="button"
+                    onClick={() => onRowActivate(row, rowIndex)}
+                    className="rounded px-1 py-0.5 text-left text-sm text-foreground underline focus:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  >
+                    {label}
+                  </button>
+                );
+              })}
+            </nav>
+          )}
+        </div>
       )}
     </div>
   );

package/src/shared/formatters.ts

@@ -1,3 +1,23 @@
+import type { CellValue } from "@optilogic/core";
+
+/**
+ * Narrow an untyped datum field (chart data is `Record<string, unknown>`) to a
+ * {@link CellValue} at the boundary, without casting. Non-primitive values that
+ * aren't `Date` become `null`.
+ */
+export function toCellValue(value: unknown): CellValue {
+  if (value == null) return null;
+  if (
+    typeof value === "number" ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+  if (value instanceof Date) return value;
+  return null;
+}
+
 const compactThresholds: [number, string][] = [
   [1_000_000_000, "B"],
   [1_000_000, "M"],

package/src/specialized/funnel-chart.tsx

@@ -49,6 +49,12 @@ const FunnelChart = React.forwardRef<HTMLDivElement, FunnelChartProps>(
         height={height}
         loading={loading}
         empty={!data?.length}
+        ariaLabel="Funnel chart"
+        tableData={data}
+        tableColumns={[
+          { key: "name", label: "Stage" },
+          { key: "value", label: "Value" },
+        ]}
       >
         <RechartsFunnelChart margin={margin}>
           <Funnel

package/src/specialized/gantt-chart.tsx

@@ -265,9 +265,18 @@ const GanttChart = React.forwardRef<HTMLDivElement, GanttChartProps>(
             const isHovered = hoveredId === task.id;
             const progress = task.progress ?? 0;
 
+            const taskLabel = `${task.name}, ${task.start.toLocaleDateString()} to ${task.end.toLocaleDateString()}${
+              task.progress != null
+                ? `, ${Math.round((task.progress ?? 0) * 100)}% complete`
+                : ""
+            }`;
+
             return (
               <g
                 key={task.id}
+                tabIndex={0}
+                role={onTaskClick ? "button" : "img"}
+                aria-label={taskLabel}
                 onMouseEnter={(e) => {
                   setHoveredId(task.id);
                   const rect = containerRef.current?.getBoundingClientRect();
@@ -281,7 +290,23 @@ const GanttChart = React.forwardRef<HTMLDivElement, GanttChartProps>(
                   setHoveredId(null);
                   setTooltipInfo(null);
                 }}
+                // Keyboard/focus parity with pointer interaction (SC 2.1.1).
+                onFocus={() => {
+                  setHoveredId(task.id);
+                  setTooltipInfo({ task, x: barX, y: barY });
+                }}
+                onBlur={() => {
+                  setHoveredId(null);
+                  setTooltipInfo(null);
+                }}
+                onKeyDown={(e) => {
+                  if (onTaskClick && (e.key === "Enter" || e.key === " ")) {
+                    e.preventDefault();
+                    onTaskClick(task);
+                  }
+                }}
                 onClick={() => onTaskClick?.(task)}
+                className="focus:outline-none focus-visible:[outline:2px_solid_hsl(var(--ring))]"
                 style={{ cursor: onTaskClick ? "pointer" : "default" }}
               >
                 {/* Row stripe */}

package/src/specialized/heatmap-chart.tsx

@@ -64,6 +64,7 @@ const HeatmapChart = React.forwardRef<HTMLDivElement, HeatmapChartProps>(
   ) {
     const containerRef = React.useRef<HTMLDivElement>(null);
     const [hoveredCell, setHoveredCell] = React.useState<HeatmapCell | null>(null);
+    const [focusedKey, setFocusedKey] = React.useState<string | null>(null);
     const [tooltipPos, setTooltipPos] = React.useState({ x: 0, y: 0 });
 
     const { valueMap, minVal, maxVal } = React.useMemo(() => {
@@ -150,10 +151,21 @@ const HeatmapChart = React.forwardRef<HTMLDivElement, HeatmapChartProps>(
                 const cx = labelColWidth + xi * cellSize;
                 const cy = 28 + yi * cellSize;
                 const cellData: HeatmapCell = { x: xLabel, y: yLabel, value: val ?? 0 };
+                const isInteractive = !!onCellClick;
+                const valueText =
+                  val != null
+                    ? valueFormatter
+                      ? valueFormatter(val)
+                      : val.toLocaleString()
+                    : "no value";
+                const cellLabel = `${yLabel}, ${xLabel}: ${valueText}`;
 
                 return (
                   <g
                     key={key}
+                    role={isInteractive ? "button" : "img"}
+                    tabIndex={0}
+                    aria-label={cellLabel}
                     onMouseEnter={(e) => {
                       setHoveredCell(cellData);
                       const rect = containerRef.current?.getBoundingClientRect();
@@ -163,8 +175,29 @@ const HeatmapChart = React.forwardRef<HTMLDivElement, HeatmapChartProps>(
                       });
                     }}
                     onMouseLeave={() => setHoveredCell(null)}
+                    onFocus={() => {
+                      setHoveredCell(cellData);
+                      setFocusedKey(key);
+                      setTooltipPos({
+                        x: cx + cellSize / 2,
+                        y: cy,
+                      });
+                    }}
+                    onBlur={() => {
+                      setHoveredCell(null);
+                      setFocusedKey(null);
+                    }}
                     onClick={() => onCellClick?.(cellData)}
-                    style={{ cursor: onCellClick ? "pointer" : "default" }}
+                    onKeyDown={(e) => {
+                      if (
+                        isInteractive &&
+                        (e.key === "Enter" || e.key === " ")
+                      ) {
+                        e.preventDefault();
+                        onCellClick?.(cellData);
+                      }
+                    }}
+                    style={{ cursor: onCellClick ? "pointer" : "default", outline: "none" }}
                   >
                     <rect
                       x={cx + 1}
@@ -179,11 +212,13 @@ const HeatmapChart = React.forwardRef<HTMLDivElement, HeatmapChartProps>(
                       }
                       fillOpacity={val != null ? 0.85 : 0.3}
                       stroke={
-                        hoveredCell?.x === xLabel && hoveredCell?.y === yLabel
-                          ? "hsl(var(--foreground))"
-                          : "none"
+                        focusedKey === key
+                          ? "hsl(var(--ring))"
+                          : hoveredCell?.x === xLabel && hoveredCell?.y === yLabel
+                            ? "hsl(var(--foreground))"
+                            : "none"
                       }
-                      strokeWidth={1.5}
+                      strokeWidth={focusedKey === key ? 2.5 : 1.5}
                     />
                     {showValues && val != null && cellSize >= 32 && (
                       <text

package/src/specialized/sankey-chart.tsx

@@ -128,6 +128,16 @@ const SankeyChart = React.forwardRef<HTMLDivElement, SankeyChartProps>(
   ) => {
     const tooltipProps = resolveTooltipProps(tooltip);
 
+    const tableData = React.useMemo(
+      () =>
+        (data?.links ?? []).map((link) => ({
+          source: data.nodes[link.source]?.name ?? String(link.source),
+          target: data.nodes[link.target]?.name ?? String(link.target),
+          value: link.value,
+        })),
+      [data],
+    );
+
     return (
       <ChartContainer
         ref={ref}
@@ -135,6 +145,13 @@ const SankeyChart = React.forwardRef<HTMLDivElement, SankeyChartProps>(
         height={height}
         loading={loading}
         empty={!data?.nodes?.length}
+        ariaLabel="Sankey diagram"
+        tableData={tableData}
+        tableColumns={[
+          { key: "source", label: "Source" },
+          { key: "target", label: "Target" },
+          { key: "value", label: "Value" },
+        ]}
       >
         <Sankey
           data={data}

package/src/specialized/treemap-chart.tsx

@@ -20,6 +20,27 @@ export interface TreemapChartProps extends BaseChartProps {
   loading?: boolean;
 }
 
+/**
+ * Flatten a treemap tree into leaf rows for the screen-reader data table.
+ * Uses each leaf's own name/value so the numbers are exposed to assistive tech.
+ */
+function flattenTreemap(
+  nodes: TreemapDatum[],
+): Array<Record<string, unknown>> {
+  const rows: Array<Record<string, unknown>> = [];
+  const walk = (items: TreemapDatum[]) => {
+    for (const item of items) {
+      if (item.children && item.children.length > 0) {
+        walk(item.children);
+      } else {
+        rows.push({ name: item.name, value: item.value ?? null });
+      }
+    }
+  };
+  walk(nodes);
+  return rows;
+}
+
 interface TreemapContentProps {
   x: number;
   y: number;
@@ -46,6 +67,8 @@ function TreemapContent({
 
   return (
     <g>
+      {/* Full, untruncated label exposed to assistive tech (SC 1.1.1). */}
+      {name && <title>{name}</title>}
       <rect
         x={x}
         y={y}
@@ -86,7 +109,6 @@ const TreemapChart = React.forwardRef<HTMLDivElement, TreemapChartProps>(
       live = false,
       className,
       height = "100%",
-      margin,
       loading,
     },
     ref,
@@ -94,6 +116,8 @@ const TreemapChart = React.forwardRef<HTMLDivElement, TreemapChartProps>(
     const tooltipProps = resolveTooltipProps(tooltip);
     const isAnimated = live ? false : animate;
 
+    const tableData = React.useMemo(() => flattenTreemap(data), [data]);
+
     return (
       <ChartContainer
         ref={ref}
@@ -101,6 +125,12 @@ const TreemapChart = React.forwardRef<HTMLDivElement, TreemapChartProps>(
         height={height}
         loading={loading}
         empty={!data?.length}
+        ariaLabel="Treemap chart"
+        tableData={tableData}
+        tableColumns={[
+          { key: "name", label: "Name" },
+          { key: "value", label: "Value" },
+        ]}
       >
         <Treemap
           data={data}