@spatika/react 1.3.0 → 1.4.0

package/src/composites/chart-composition.tsx

@@ -62,6 +62,14 @@ import {
   seriesMeta,
   type ChartHover,
 } from "./chart-ui";
+import {
+  bindChartMark,
+  seriesItemColor,
+  type ChartItemEvent,
+  type ChartMarkRenderContext,
+  type ChartReferenceLine,
+  type ChartTooltipRenderer,
+} from "./chart-interaction";
 
 export type ComposedSeriesType = "bar" | "line" | "area" | "scatter";
 
@@ -70,6 +78,8 @@ export type ComposedSeries = {
   type?: ComposedSeriesType;
   label?: string;
   color?: string;
+  /** Per-category colors; each entry falls back to `color`. */
+  itemColors?: Array<string | null | undefined>;
   data?: Array<number | null>;
   dataKey?: string;
   stack?: string;
@@ -85,6 +95,7 @@ type ResolvedSeries = {
   type: ComposedSeriesType;
   label: string;
   color: string;
+  itemColors?: Array<string | null | undefined>;
   data: Array<number | null>;
   stack?: string;
   yAxisId?: string;
@@ -135,6 +146,10 @@ type ChartContextValue = {
   brush: { x0: number; x1: number } | null;
   setBrush: (brush: { x0: number; x1: number } | null) => void;
   exportChart: (format: "svg" | "png") => Promise<void>;
+  onItemClick?: (event: ChartItemEvent) => void;
+  renderMark?: (ctx: ChartMarkRenderContext) => ReactNode;
+  referenceLines?: ChartReferenceLine[];
+  showLabels?: boolean;
 };
 
 const ChartContext = createContext<ChartContextValue | null>(null);
@@ -175,6 +190,14 @@ export type ChartContainerProps = {
   locale?: string;
   children?: ReactNode;
   "aria-label"?: string;
+  /** When true, plot height follows the parent instead of the numeric `height`. */
+  fillHeight?: boolean;
+  onItemClick?: (event: ChartItemEvent) => void;
+  renderTooltip?: ChartTooltipRenderer;
+  renderMark?: (ctx: ChartMarkRenderContext) => ReactNode;
+  referenceLines?: ChartReferenceLine[];
+  /** Draw the numeric value at the end of each bar. */
+  showLabels?: boolean;
 };
 
 function useElementSize(ref: RefObject<HTMLElement | null>, fallbackWidth: number, fallbackHeight: number) {
@@ -207,6 +230,7 @@ function resolveSeries(series: ComposedSeries[], dataset: ChartDataset | undefin
       type,
       label: item.label ?? item.dataKey ?? item.id ?? `Series ${index + 1}`,
       color: item.color ?? chartColor(index, colors),
+      itemColors: item.itemColors,
       data,
       stack: item.stack,
       yAxisId: item.yAxisId,
@@ -277,12 +301,19 @@ export function ChartContainer({
   locale,
   children,
   "aria-label": ariaLabel,
+  fillHeight = false,
+  onItemClick,
+  renderTooltip,
+  renderMark,
+  referenceLines,
+  showLabels = false,
 }: ChartContainerProps) {
   const surfaceRef = useRef<HTMLDivElement>(null);
   const svgRef = useRef<SVGSVGElement>(null);
   const clipPathId = `spk-chart-clip-${useId().replace(/:/g, "")}`;
   const measured = useElementSize(surfaceRef, width ?? 320, height);
   const plotWidth = width ?? measured.width;
+  const plotHeight = fillHeight ? measured.height : height;
   const hasRight = yAxis?.some((axis) => axis.position === "right");
   const m = resolveMargin(
     margin ?? (hasRight ? { ...DEFAULT_CHART_MARGIN, right: 48 } : undefined),
@@ -320,7 +351,7 @@ export function ChartContainer({
   const [brush, setBrush] = useState<{ x0: number; x1: number } | null>(null);
   const activeHighlight = selected ?? highlighted;
 
-  const plot = plotBox(plotWidth, height, m);
+  const plot = plotBox(plotWidth, plotHeight, m);
   const visible = resolved.filter((item) => !hidden.has(item.id));
   const leftSeries = visible.filter((item) => !item.yAxisId || item.yAxisId === (leftAxis?.id ?? item.yAxisId));
   const rightSeries = visible.filter((item) => rightAxis && item.yAxisId === rightAxis.id);
@@ -372,7 +403,7 @@ export function ChartContainer({
   const ctx: ChartContextValue = {
     slot,
     width: plotWidth,
-    height,
+    height: plotHeight,
     margin: m,
     plot,
     categories,
@@ -409,6 +440,10 @@ export function ChartContainer({
     brush,
     setBrush,
     exportChart: doExport,
+    onItemClick,
+    renderMark,
+    referenceLines,
+    showLabels,
   };
 
   const legend = seriesMeta(resolved, colors);
@@ -420,7 +455,7 @@ export function ChartContainer({
     <ChartContext.Provider value={ctx}>
       <div
         data-slot={slot}
-        className={cn("spk-chart", animated && "spk-chart--animated", className)}
+        className={cn("spk-chart", animated && "spk-chart--animated", fillHeight && "spk-chart--fill", className)}
         role="img"
         aria-label={label}
       >
@@ -428,9 +463,9 @@ export function ChartContainer({
         {hideLegend ? null : (
           <ChartLegend items={legend} hiddenIds={hidden} onToggle={toggleSeries} />
         )}
-        <div ref={surfaceRef} className="spk-chart-surface" style={{ height }}>
-          {plotWidth > 0 ? children ?? <DefaultChartSurface /> : null}
-          <ChartTooltip hover={hover} boundsWidth={plotWidth} />
+        <div ref={surfaceRef} className="spk-chart-surface" style={fillHeight ? undefined : { height: plotHeight }}>
+          {plotWidth > 0 && plotHeight > 0 ? children ?? <DefaultChartSurface /> : null}
+          <ChartTooltip hover={hover} boundsWidth={plotWidth} render={renderTooltip} />
         </div>
         <ChartA11yTable />
       </div>
@@ -450,6 +485,7 @@ function DefaultChartSurface() {
       <ChartsXAxis />
       <ChartsYAxis />
       {rightAxis ? <ChartsYAxis position="right" /> : null}
+      <ChartsReferenceLine />
       <ChartsBrush />
     </ChartSurface>
   );
@@ -609,50 +645,81 @@ export function BarPlot() {
   const barW = (ctx.bandwidth - gap * (n - 1)) / n;
   const zero = ctx.yAt(0);
   return (
-    <PlotClip slot="bar-plot">
-      {bars.map((item, s) =>
-        item.data.map((value, i) => {
-          if (value == null) return null;
-          let x = ctx.xAt(i);
-          let y1: number;
-          let y2: number;
-          if (stacks) {
-            const seg = stacks[s]![i]!;
-            y1 = ctx.yAt(seg.end, item.yAxisId);
-            y2 = ctx.yAt(seg.start, item.yAxisId);
-          } else {
-            x = ctx.xAt(i) + s * (barW + gap);
-            y1 = ctx.yAt(value, item.yAxisId);
-            y2 = zero;
-          }
-          const y = Math.min(y1, y2);
-          const h = Math.max(1, Math.abs(y2 - y1));
-          const opacity = markOpacity(ctx.highlightScope, ctx.highlighted, item.id, i);
-          return (
-            <path
-              key={`${item.id}-${i}`}
-              className="spk-chart-mark"
-              d={roundedRectPath(x, y, ctx.stacked ? ctx.bandwidth : barW, h, ctx.borderRadius)}
-              fill={item.color}
-              opacity={opacity}
-              onMouseEnter={(event) => {
-                ctx.setHighlighted({ seriesId: item.id, dataIndex: i });
-                ctx.setHover({
-                  x: event.nativeEvent.offsetX,
-                  y: event.nativeEvent.offsetY,
-                  title: String(ctx.categories[i]),
-                  items: [{ color: item.color, label: item.label, value: formatSeriesValue(value) }],
-                });
-              }}
-              onMouseLeave={() => {
-                ctx.setHighlighted(null);
-                ctx.setHover(null);
-              }}
-            />
-          );
-        }),
-      )}
-    </PlotClip>
+    <>
+      <PlotClip slot="bar-plot">
+        {bars.map((item, s) =>
+          item.data.map((value, i) => {
+            if (value == null) return null;
+            let x = ctx.xAt(i);
+            let y1: number;
+            let y2: number;
+            if (stacks) {
+              const seg = stacks[s]![i]!;
+              y1 = ctx.yAt(seg.end, item.yAxisId);
+              y2 = ctx.yAt(seg.start, item.yAxisId);
+            } else {
+              x = ctx.xAt(i) + s * (barW + gap);
+              y1 = ctx.yAt(value, item.yAxisId);
+              y2 = zero;
+            }
+            const y = Math.min(y1, y2);
+            const h = Math.max(1, Math.abs(y2 - y1));
+            const opacity = markOpacity(ctx.highlightScope, ctx.highlighted, item.id, i);
+            const color = seriesItemColor(item.color, item.itemColors, i);
+            const event: ChartItemEvent = {
+              seriesId: item.id,
+              seriesLabel: item.label,
+              dataIndex: i,
+              category: ctx.categories[i] ?? i,
+              value,
+              color,
+            };
+            return (
+              <path
+                key={`${item.id}-${i}`}
+                d={roundedRectPath(x, y, ctx.stacked ? ctx.bandwidth : barW, h, ctx.borderRadius)}
+                fill={color}
+                opacity={opacity}
+                {...bindChartMark({
+                  event,
+                  hover: {
+                    title: String(ctx.categories[i]),
+                    items: [{ color, label: item.label, value: formatSeriesValue(value) }],
+                  },
+                  onItemClick: ctx.onItemClick,
+                  setHover: ctx.setHover,
+                  clearHover: () => ctx.setHover(null),
+                  onHighlight: ctx.setHighlighted,
+                })}
+              />
+            );
+          }),
+        )}
+      </PlotClip>
+      {ctx.showLabels ? (
+        <g data-slot="bar-labels" pointerEvents="none">
+          {bars.map((item, s) =>
+            item.data.map((value, i) => {
+              if (value == null) return null;
+              const x = ctx.stacked ? ctx.xAt(i) : ctx.xAt(i) + s * (barW + gap);
+              const y = ctx.yAt(value, item.yAxisId);
+              const width = ctx.stacked ? ctx.bandwidth : barW;
+              return (
+                <text
+                  key={`${item.id}-${i}-label`}
+                  className="spk-chart-label"
+                  x={x + width / 2}
+                  y={y - 4}
+                  textAnchor="middle"
+                >
+                  {formatSeriesValue(value)}
+                </text>
+              );
+            }),
+          )}
+        </g>
+      ) : null}
+    </>
   );
 }
 
@@ -705,29 +772,40 @@ function LineLikePlot({ types, slot }: { types: ComposedSeriesType[]; slot: stri
               className="spk-chart-mark"
             />
             {item.showMark
-              ? pts.map((pt) => (
-                  <circle
-                    key={pt.i}
-                    cx={pt.x}
-                    cy={pt.y}
-                    r={3.4}
-                    fill={item.color}
-                    className="spk-chart-mark"
-                    onMouseEnter={() => {
-                      ctx.setHighlighted({ seriesId: item.id, dataIndex: pt.i });
-                      ctx.setHover({
-                        x: pt.x,
-                        y: pt.y,
-                        title: String(ctx.categories[pt.i]),
-                        items: [{ color: item.color, label: item.label, value: formatSeriesValue(pt.value) }],
-                      });
-                    }}
-                    onMouseLeave={() => {
-                      ctx.setHighlighted(null);
-                      ctx.setHover(null);
-                    }}
-                  />
-                ))
+              ? pts.map((pt) => {
+                  const color = seriesItemColor(item.color, item.itemColors, pt.i);
+                  const event: ChartItemEvent = {
+                    seriesId: item.id,
+                    seriesLabel: item.label,
+                    dataIndex: pt.i,
+                    category: ctx.categories[pt.i] ?? pt.i,
+                    value: pt.value,
+                    color,
+                  };
+                  const mark = ctx.renderMark?.({ ...event, x: pt.x, y: pt.y }) ?? (
+                    <circle cx={pt.x} cy={pt.y} r={3.4} fill={color} />
+                  );
+                  return (
+                    <g
+                      key={pt.i}
+                      {...bindChartMark({
+                        event,
+                        hover: {
+                          x: pt.x,
+                          y: pt.y,
+                          title: String(ctx.categories[pt.i]),
+                          items: [{ color, label: item.label, value: formatSeriesValue(pt.value) }],
+                        },
+                        onItemClick: ctx.onItemClick,
+                        setHover: ctx.setHover,
+                        clearHover: () => ctx.setHover(null),
+                        onHighlight: ctx.setHighlighted,
+                      })}
+                    >
+                      {mark}
+                    </g>
+                  );
+                })
               : null}
           </g>
         );
@@ -763,31 +841,37 @@ export function ScatterPlot() {
           const cx = applyZoom(xScale(point.x), ctx.plot.left, ctx.plot.iw, ctx.zoom.x);
           const cy = ctx.yAt(point.y, item.yAxisId);
           const opacity = markOpacity(ctx.highlightScope, ctx.highlighted, item.id, i);
+          const color = seriesItemColor(item.color, item.itemColors, i);
+          const event: ChartItemEvent = {
+            seriesId: item.id,
+            seriesLabel: item.label,
+            dataIndex: i,
+            category: point.id ?? i,
+            value: point.y,
+            color,
+          };
           return (
             <circle
               key={`${item.id}-${point.id ?? i}`}
               cx={cx}
               cy={cy}
               r={4.5}
-              fill={item.color}
+              fill={color}
               opacity={opacity}
-              className="spk-chart-mark"
-              onMouseEnter={(event) => {
-                ctx.setHighlighted({ seriesId: item.id, dataIndex: i });
-                ctx.setHover({
-                  x: event.nativeEvent.offsetX,
-                  y: event.nativeEvent.offsetY,
+              {...bindChartMark({
+                event,
+                hover: {
                   title: item.label,
                   items: [
-                    { color: item.color, label: "x", value: formatChartNumber(point.x, ctx.locale) },
-                    { color: item.color, label: "y", value: formatChartNumber(point.y, ctx.locale) },
+                    { color, label: "x", value: formatChartNumber(point.x, ctx.locale) },
+                    { color, label: "y", value: formatChartNumber(point.y, ctx.locale) },
                   ],
-                });
-              }}
-              onMouseLeave={() => {
-                ctx.setHighlighted(null);
-                ctx.setHover(null);
-              }}
+                },
+                onItemClick: ctx.onItemClick,
+                setHover: ctx.setHover,
+                clearHover: () => ctx.setHover(null),
+                onHighlight: ctx.setHighlighted,
+              })}
             />
           );
         });
@@ -813,6 +897,63 @@ export function ChartsBrush() {
   );
 }
 
+/** Horizontal (value) or vertical (category index) guide overlay. */
+export function ChartsReferenceLine() {
+  const { referenceLines, yAt, xAt, plot, bandwidth } = useChartContext();
+  if (!referenceLines?.length) return null;
+  return (
+    <g data-slot="chart-reference-lines">
+      {referenceLines.map((line, index) => {
+        const color = line.color ?? "var(--primary)";
+        const dash = line.strokeDasharray ?? "4 4";
+        if (line.y != null) {
+          const y = yAt(line.y, line.yAxisId);
+          return (
+            <g key={`y-${index}`}>
+              <line
+                className="spk-chart-ref-line"
+                x1={plot.left}
+                x2={plot.right}
+                y1={y}
+                y2={y}
+                stroke={color}
+                strokeDasharray={dash}
+              />
+              {line.label ? (
+                <text className="spk-chart-ref-label" x={plot.right - 4} y={y - 4} textAnchor="end">
+                  {line.label}
+                </text>
+              ) : null}
+            </g>
+          );
+        }
+        if (line.xIndex != null) {
+          const x = xAt(line.xIndex) + bandwidth / 2;
+          return (
+            <g key={`x-${index}`}>
+              <line
+                className="spk-chart-ref-line"
+                x1={x}
+                x2={x}
+                y1={plot.top}
+                y2={plot.bottom}
+                stroke={color}
+                strokeDasharray={dash}
+              />
+              {line.label ? (
+                <text className="spk-chart-ref-label" x={x + 4} y={plot.top + 12}>
+                  {line.label}
+                </text>
+              ) : null}
+            </g>
+          );
+        }
+        return null;
+      })}
+    </g>
+  );
+}
+
 export function ChartsLegend() {
   const { series, hidden, toggleSeries } = useChartContext();
   return (

package/src/composites/chart-interaction.ts

@@ -0,0 +1,136 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+export type ChartTooltipItem = {
+  color: string;
+  label: string;
+  value: string;
+};
+
+export type ChartHover = {
+  x: number;
+  y: number;
+  title?: string;
+  items: ChartTooltipItem[];
+  dataIndex?: number;
+  seriesId?: string;
+  category?: string | number | Date;
+} | null;
+
+/** Payload fired when a chart mark (bar, slice, point, cell) is activated. */
+export type ChartItemEvent = {
+  seriesId: string;
+  seriesLabel: string;
+  dataIndex: number;
+  category: string | number | Date;
+  value: number | null;
+  color: string;
+};
+
+/** Geometry plus item identity, used by `renderMark` on line and area series. */
+export type ChartMarkRenderContext = ChartItemEvent & {
+  x: number;
+  y: number;
+};
+
+/**
+ * Overlay guide on a cartesian plot.
+ * Set `y` for a horizontal value line, or `xIndex` for a vertical category line.
+ */
+export type ChartReferenceLine = {
+  y?: number;
+  xIndex?: number;
+  yAxisId?: string;
+  color?: string;
+  label?: string;
+  strokeDasharray?: string;
+};
+
+export type ChartTooltipRenderer = (hover: NonNullable<ChartHover>) => ReactNode;
+
+export type ChartMarkBind = {
+  className: string;
+  role?: "button";
+  tabIndex?: number;
+  "aria-label"?: string;
+  onClick?: (event: { stopPropagation(): void }) => void;
+  onKeyDown?: (event: { key: string; preventDefault(): void }) => void;
+  onMouseEnter?: (event: { nativeEvent: { offsetX: number; offsetY: number } }) => void;
+  onMouseLeave?: () => void;
+};
+
+/** Per-category color, falling back to the series token. */
+export function seriesItemColor(
+  color: string,
+  itemColors: Array<string | null | undefined> | undefined,
+  index: number,
+): string {
+  return itemColors?.[index] || color;
+}
+
+export function chartItemAriaLabel(event: ChartItemEvent): string {
+  const category = String(event.category);
+  if (event.seriesLabel && event.seriesLabel !== category) {
+    return `${event.seriesLabel} ${category}`;
+  }
+  return category;
+}
+
+/**
+ * Pointer, keyboard, and hover bindings for an SVG mark.
+ * Adds a button role only when `onItemClick` is set so legends stay the sole named buttons.
+ */
+export function bindChartMark({
+  event,
+  hover,
+  onItemClick,
+  setHover,
+  clearHover,
+  onHighlight,
+}: {
+  event: ChartItemEvent;
+  hover: Pick<NonNullable<ChartHover>, "title" | "items"> & Partial<NonNullable<ChartHover>>;
+  onItemClick?: (event: ChartItemEvent) => void;
+  setHover: (hover: ChartHover) => void;
+  clearHover: () => void;
+  onHighlight?: (item: { seriesId: string; dataIndex: number } | null) => void;
+}): ChartMarkBind {
+  const clickable = Boolean(onItemClick);
+  const applyHover = (x: number, y: number) => {
+    onHighlight?.({ seriesId: event.seriesId, dataIndex: event.dataIndex });
+    setHover({
+      x: hover.x ?? x,
+      y: hover.y ?? y,
+      title: hover.title,
+      items: hover.items,
+      dataIndex: event.dataIndex,
+      seriesId: event.seriesId,
+      category: event.category,
+    });
+  };
+  return {
+    className: cn("spk-chart-mark", clickable && "spk-chart-mark--interactive"),
+    role: clickable ? "button" : undefined,
+    tabIndex: clickable ? 0 : undefined,
+    "aria-label": clickable ? chartItemAriaLabel(event) : undefined,
+    onClick: clickable
+      ? (native) => {
+          native.stopPropagation();
+          onItemClick?.(event);
+        }
+      : undefined,
+    onKeyDown: clickable
+      ? (native) => {
+          if (native.key === "Enter" || native.key === " ") {
+            native.preventDefault();
+            onItemClick?.(event);
+          }
+        }
+      : undefined,
+    onMouseEnter: (native) => applyHover(native.nativeEvent.offsetX, native.nativeEvent.offsetY),
+    onMouseLeave: () => {
+      onHighlight?.(null);
+      clearHover();
+    },
+  };
+}