@voila.dev/chart 4.0.0

package/src/react/focus-overlay.tsx

@@ -0,0 +1,164 @@
+import type * as React from "react";
+import { arcPath, roundedBarPath } from "#/core/paths.ts";
+import type { ChartPoint, ChartScene, ChartTheme } from "#/core/types.ts";
+import type { ActiveFocus } from "#/react/use-chart-focus.ts";
+
+const RING_RADIUS = 4.5;
+const RING_OUTSET = 2;
+
+function PointRing({
+	point,
+	keyboard,
+	theme,
+}: {
+	point: ChartPoint;
+	keyboard: boolean;
+	theme: ChartTheme;
+}) {
+	const ring = keyboard ? "var(--ring, Highlight)" : theme.background;
+	if (point.hit?.kind === "rect" && point.hit.rect.width > RING_RADIUS * 4) {
+		if (!keyboard) {
+			return null;
+		}
+		const { rect } = point.hit;
+		return (
+			<path
+				data-slot="chart-focus-ring"
+				d={roundedBarPath({
+					x: rect.x - RING_OUTSET,
+					y: rect.y - RING_OUTSET,
+					width: rect.width + RING_OUTSET * 2,
+					height: rect.height + RING_OUTSET * 2,
+					radius: 4,
+				})}
+				fill="none"
+				stroke={ring}
+				strokeWidth={2}
+			/>
+		);
+	}
+	if (point.hit?.kind === "arc") {
+		return (
+			<path
+				data-slot="chart-focus-ring"
+				d={arcPath({
+					...point.hit,
+					outerRadius: point.hit.outerRadius + RING_OUTSET,
+				})}
+				fill="none"
+				stroke={keyboard ? ring : theme.foreground}
+				strokeWidth={2}
+			/>
+		);
+	}
+	return (
+		<circle
+			data-slot="chart-focus-ring"
+			cx={point.x}
+			cy={point.y}
+			r={RING_RADIUS}
+			fill={point.color}
+			stroke={ring}
+			strokeWidth={2}
+		/>
+	);
+}
+
+/**
+ * The focus layer, drawn over the marks whichever renderer drew them: the
+ * column or row band under the pointer, and a ring on the focused point.
+ * Hidden from assistive tech: the live region says what it shows.
+ */
+export function FocusOverlay({
+	scene,
+	active,
+	theme,
+}: {
+	scene: ChartScene;
+	active: ActiveFocus | null;
+	theme: ChartTheme;
+}) {
+	if (active === null) {
+		return null;
+	}
+	const { focusOrder, scales } = scene;
+	// On a faceted chart the cursor spans the focused point's own cell.
+	const plot =
+		scene.cells?.find((cell) => cell.key === active.point.facet)?.plot ??
+		scene.plot;
+	const keyboard = active.source === "keyboard";
+	const along = focusOrder === "y" ? scales.y : scales.x;
+	const band = along?.kind === "band" ? along.bandwidth : 0;
+	let cursor: React.ReactNode = null;
+	if (focusOrder !== "point") {
+		cursor =
+			band > 0 ? (
+				<rect
+					data-slot="chart-cursor"
+					{...(focusOrder === "y"
+						? {
+								x: plot.x,
+								y: active.stop.at - band / 2,
+								width: plot.width,
+								height: band,
+							}
+						: {
+								x: active.stop.at - band / 2,
+								y: plot.y,
+								width: band,
+								height: plot.height,
+							})}
+					fill="currentColor"
+					opacity={0.06}
+				/>
+			) : (
+				<line
+					data-slot="chart-cursor"
+					{...(focusOrder === "y"
+						? {
+								x1: plot.x,
+								x2: plot.x + plot.width,
+								y1: active.stop.at,
+								y2: active.stop.at,
+							}
+						: {
+								x1: active.stop.at,
+								x2: active.stop.at,
+								y1: plot.y,
+								y2: plot.y + plot.height,
+							})}
+					stroke={theme.muted}
+					strokeWidth={1}
+					strokeDasharray="3 3"
+				/>
+			);
+	}
+	const ringed =
+		focusOrder === "point" || (keyboard && active.stop.points.length > 1)
+			? [active.point]
+			: active.stop.points;
+	return (
+		<svg
+			aria-hidden="true"
+			data-slot="chart-focus"
+			width={scene.width}
+			height={scene.height}
+			style={{
+				position: "absolute",
+				inset: 0,
+				overflow: "visible",
+				pointerEvents: "none",
+			}}
+		>
+			{cursor}
+			{ringed.map((point) => (
+				<PointRing
+					key={point.key}
+					point={point}
+					keyboard={keyboard}
+					theme={theme}
+				/>
+			))}
+		</svg>
+	);
+}

package/src/react/index.ts

@@ -0,0 +1,9 @@
+export type { ChartBrush, ChartBrushRange } from "#/react/brush-contract.ts";
+export { Chart } from "#/react/chart.tsx";
+export {
+	ChartTooltipContent,
+	type ChartTooltipRenderProps,
+} from "#/react/chart-tooltip.tsx";
+export type { ChartRenderer, ChartRendererProps } from "#/react/renderer.ts";
+export { SvgRenderer } from "#/react/svg-renderer.tsx";
+export type { ActiveFocus } from "#/react/use-chart-focus.ts";

package/src/react/messages.ts

@@ -0,0 +1,49 @@
+/** The few words the chart says itself. French when the chart's locale is, English otherwise. */
+export interface ChartMessages {
+	readonly keyboardHint: string;
+	readonly roleDescription: string;
+	readonly legend: string;
+	readonly series: string;
+	readonly resetZoom: string;
+	readonly showing: (from: string, to: string) => string;
+	readonly zoomHint: string;
+	readonly brushStart: string;
+	readonly brushEnd: string;
+	readonly selected: (from: string, to: string) => string;
+	readonly dataTable: (label: string) => string;
+}
+
+const FRENCH: ChartMessages = {
+	keyboardHint:
+		"Flèches pour parcourir les valeurs, Entrée pour épingler, Échap pour quitter.",
+	roleDescription: "graphique",
+	legend: "Légende",
+	series: "Série",
+	resetZoom: "Réinitialiser le zoom",
+	showing: (from, to) => `Affiché : ${from} – ${to}`,
+	zoomHint:
+		" + et − pour zoomer, Maj et flèches pour se déplacer, 0 pour revenir.",
+	brushStart: "Début de la sélection",
+	brushEnd: "Fin de la sélection",
+	selected: (from, to) => `Sélection : ${from} – ${to}`,
+	dataTable: (label) => `Données : ${label}`,
+};
+
+const ENGLISH: ChartMessages = {
+	keyboardHint:
+		"Arrow keys to move through the values, Enter to pin, Escape to leave.",
+	roleDescription: "chart",
+	legend: "Legend",
+	series: "Series",
+	resetZoom: "Reset zoom",
+	showing: (from, to) => `Showing ${from} – ${to}`,
+	zoomHint: " + and − to zoom, Shift and the arrows to pan, 0 to reset.",
+	brushStart: "Selection start",
+	brushEnd: "Selection end",
+	selected: (from, to) => `Selected ${from} – ${to}`,
+	dataTable: (label) => `Data: ${label}`,
+};
+
+export function messagesFor(locale: string): ChartMessages {
+	return locale.toLowerCase().startsWith("fr") ? FRENCH : ENGLISH;
+}

package/src/react/renderer.ts

@@ -0,0 +1,15 @@
+import type * as React from "react";
+import type { ChartScene } from "#/core/types.ts";
+
+/**
+ * What draws the scene. The SVG renderer is the default; `@voila.dev/chart/canvas`
+ * exports one that paints the same scene onto a canvas, for thousands of marks.
+ * Either way the focus ring, tooltip, legend and data table are the same.
+ */
+export interface ChartRendererProps {
+	readonly scene: ChartScene;
+	/** Unique per chart, for clip-path ids. */
+	readonly chartId: string;
+}
+
+export type ChartRenderer = React.ComponentType<ChartRendererProps>;

package/src/react/sr-only.ts

@@ -0,0 +1,14 @@
+import type * as React from "react";
+
+/** Present to assistive tech, invisible on screen, and never wider than one pixel. */
+export const SR_ONLY: React.CSSProperties = {
+	position: "absolute",
+	width: 1,
+	height: 1,
+	padding: 0,
+	margin: -1,
+	overflow: "hidden",
+	clip: "rect(0, 0, 0, 0)",
+	whiteSpace: "nowrap",
+	border: 0,
+};

package/src/react/svg-renderer.tsx

@@ -0,0 +1,18 @@
+import type { ChartRendererProps } from "#/react/renderer.ts";
+import { SvgSceneNodes } from "#/react/svg-scene.tsx";
+
+/** The default renderer: the scene as inline SVG, server-renderable and crisp at any zoom. */
+export function SvgRenderer({ scene, chartId }: ChartRendererProps) {
+	return (
+		<svg
+			data-slot="chart-svg"
+			aria-hidden="true"
+			width={scene.width}
+			height={scene.height}
+			viewBox={`0 0 ${scene.width} ${scene.height}`}
+			style={{ position: "absolute", inset: 0, overflow: "visible" }}
+		>
+			<SvgSceneNodes scene={scene} clipPrefix={chartId} />
+		</svg>
+	);
+}

package/src/react/svg-scene.tsx

@@ -0,0 +1,146 @@
+import type * as React from "react";
+import { roundedBarPath } from "#/core/paths.ts";
+import type {
+	ChartPaint,
+	ChartScene,
+	ChartTextPaint,
+	SceneNode,
+} from "#/core/types.ts";
+
+const BASELINE: Record<
+	NonNullable<ChartTextPaint["baseline"]>,
+	React.SVGAttributes<SVGTextElement>["dominantBaseline"]
+> = {
+	top: "hanging",
+	middle: "central",
+	bottom: "text-after-edge",
+	alphabetic: "alphabetic",
+};
+
+function paintProps(paint: ChartPaint): React.SVGAttributes<SVGElement> {
+	return {
+		fill: paint.fill ?? "none",
+		stroke: paint.stroke,
+		strokeWidth: paint.strokeWidth,
+		strokeDasharray: paint.strokeDasharray,
+		strokeLinecap: paint.strokeLinecap,
+		strokeLinejoin: paint.strokeLinejoin,
+		opacity: paint.opacity,
+		fillOpacity: paint.fillOpacity,
+		strokeOpacity: paint.strokeOpacity,
+	};
+}
+
+function SceneElement({
+	node,
+	clipPrefix,
+}: {
+	node: SceneNode;
+	clipPrefix: string;
+}) {
+	const data = { "data-role": node.role, "data-series": node.series };
+	switch (node.kind) {
+		case "group": {
+			const clipId = node.clip ? `${clipPrefix}-${node.key}` : undefined;
+			return (
+				<g
+					{...data}
+					transform={
+						node.translate
+							? `translate(${node.translate.x} ${node.translate.y})`
+							: undefined
+					}
+					clipPath={clipId ? `url(#${clipId})` : undefined}
+				>
+					{node.clip && clipId ? (
+						<clipPath id={clipId}>
+							<rect {...node.clip} />
+						</clipPath>
+					) : null}
+					{node.children.map((child) => (
+						<SceneElement
+							key={child.key}
+							node={child}
+							clipPrefix={clipPrefix}
+						/>
+					))}
+				</g>
+			);
+		}
+		case "rect":
+			return node.corners ? (
+				<path
+					{...data}
+					d={roundedBarPath({ ...node, radius: node.corners })}
+					{...paintProps(node.paint)}
+				/>
+			) : (
+				<rect
+					{...data}
+					x={node.x}
+					y={node.y}
+					width={node.width}
+					height={node.height}
+					{...paintProps(node.paint)}
+				/>
+			);
+		case "path":
+			return <path {...data} d={node.d} {...paintProps(node.paint)} />;
+		case "circle":
+			return (
+				<circle
+					{...data}
+					cx={node.cx}
+					cy={node.cy}
+					r={node.r}
+					{...paintProps(node.paint)}
+				/>
+			);
+		case "line":
+			return (
+				<line
+					{...data}
+					x1={node.x1}
+					y1={node.y1}
+					x2={node.x2}
+					y2={node.y2}
+					{...paintProps(node.paint)}
+				/>
+			);
+		case "text":
+			return (
+				<text
+					{...data}
+					x={node.x}
+					y={node.y}
+					transform={
+						node.rotate
+							? `rotate(${node.rotate} ${node.x} ${node.y})`
+							: undefined
+					}
+					fontSize={node.paint.fontSize}
+					fontWeight={node.paint.fontWeight}
+					textAnchor={node.paint.textAnchor}
+					dominantBaseline={
+						node.paint.baseline ? BASELINE[node.paint.baseline] : undefined
+					}
+					{...paintProps(node.paint)}
+				>
+					{node.text}
+				</text>
+			);
+	}
+}
+
+/** The scene's nodes as SVG elements, keyed so React reconciles a data update in place. */
+export function SvgSceneNodes({
+	scene,
+	clipPrefix,
+}: {
+	scene: ChartScene;
+	clipPrefix: string;
+}) {
+	return scene.nodes.map((node) => (
+		<SceneElement key={node.key} node={node} clipPrefix={clipPrefix} />
+	));
+}

package/src/react/use-animated-scene.ts

@@ -0,0 +1,57 @@
+import * as React from "react";
+import { easeOutCubic, tweenScene } from "#/core/motion/tween.ts";
+import type { ChartScene } from "#/core/types.ts";
+
+function prefersReducedMotion(): boolean {
+	return (
+		typeof window !== "undefined" &&
+		window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true
+	);
+}
+
+/**
+ * The scene to draw this frame. A data change (`trigger` changed: a new
+ * definition, a series toggled) tweens from what is on screen to the new
+ * scene; a resize snaps, since watching bars slide while a window is dragged
+ * helps no one. Reduced motion always snaps. An update that lands mid-tween
+ * starts from the frame already painted, so nothing jumps.
+ */
+export function useAnimatedScene(
+	scene: ChartScene,
+	trigger: unknown,
+	duration: number,
+): ChartScene {
+	const [shown, setShown] = React.useState(scene);
+	const shownRef = React.useRef(scene);
+	const triggerRef = React.useRef(trigger);
+
+	React.useLayoutEffect(() => {
+		const changed = triggerRef.current !== trigger;
+		triggerRef.current = trigger;
+		if (!changed || duration <= 0 || prefersReducedMotion()) {
+			shownRef.current = scene;
+			setShown(scene);
+			return;
+		}
+		const from = shownRef.current;
+		// Frame zero now, before paint: nodes that left are gone at once.
+		const first = tweenScene(from, scene, 0);
+		shownRef.current = first;
+		setShown(first);
+		const start = performance.now();
+		let frame = 0;
+		function step(now: number) {
+			const t = Math.min(1, (now - start) / duration);
+			const next = tweenScene(from, scene, easeOutCubic(t));
+			shownRef.current = next;
+			setShown(next);
+			if (t < 1) {
+				frame = requestAnimationFrame(step);
+			}
+		}
+		frame = requestAnimationFrame(step);
+		return () => cancelAnimationFrame(frame);
+	}, [scene, trigger, duration]);
+
+	return shown;
+}