@voila.dev/ui-chart 1.1.9

package/src/components/chart-label-list.tsx

@@ -0,0 +1,178 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import type * as React from "react";
+
+import { useChartContext } from "#/context/chart-context.tsx";
+import { type BarRect, barRects } from "#/core/bars.ts";
+import { readNumber } from "#/core/chart-model.ts";
+import { formatTickValue } from "#/core/format.ts";
+import { seriesPoints } from "#/core/series.ts";
+import type {
+	ChartDatum,
+	ChartDiscreteScale,
+	ChartLinearScale,
+	ChartOrientation,
+	ChartPoint,
+} from "#/core/types.ts";
+
+/**
+ * The value written beside each point of a series. Small charts read better
+ * with the numbers on them than with an axis the reader has to trace back to.
+ */
+
+export interface ChartLabelListProps extends React.ComponentProps<"g"> {
+	/** Series to label. Defaults to the first of the root's value keys. */
+	readonly seriesKey?: string;
+	/**
+	 * Which mark the labels belong to, because the two anchor differently.
+	 *
+	 * `points` (the default) puts each label on the series point — right for
+	 * `Chart.Line`, `Chart.Area` and `Chart.Points`.
+	 *
+	 * `bars` puts it at the end of that series' OWN bar. A grouped bar chart
+	 * splits its category slot into one lane per series, while the series point
+	 * sits at the centre of the whole slot — so the label lands over the middle
+	 * of the group rather than over the bar it describes. With a single series
+	 * the two coincide, which is why this only appears once a second key is
+	 * added. Stacked bars have the same problem for a different reason: every
+	 * segment but the first starts off a running total, not the baseline.
+	 *
+	 * Pass `bars` beside any `Chart.Bars`, mirroring the `stacked` and `gap` you
+	 * gave it so the lanes line up.
+	 */
+	readonly marks?: "points" | "bars";
+	/** Mirrors `Chart.Bars`; only read when `marks` is `bars`. */
+	readonly stacked?: boolean;
+	/** Mirrors `Chart.Bars`; only read when `marks` is `bars`. */
+	readonly gap?: number;
+	/** Distance from the mark, along the value axis. */
+	readonly offset?: number;
+	readonly formatter?: (value: number) => string;
+}
+
+/**
+ * The end of a bar that points away from the baseline — where its label goes —
+ * centred across the lane the bar occupies.
+ */
+function barAnchor(rect: BarRect, orientation: ChartOrientation): ChartPoint {
+	if (orientation === "vertical") {
+		return {
+			x: rect.x + rect.width / 2,
+			y: rect.value < 0 ? rect.y + rect.height : rect.y,
+		};
+	}
+	return {
+		x: rect.value < 0 ? rect.x : rect.x + rect.width,
+		y: rect.y + rect.height / 2,
+	};
+}
+
+interface AnchorOptions {
+	readonly marks: "points" | "bars";
+	readonly data: ReadonlyArray<ChartDatum>;
+	readonly keys: ReadonlyArray<string>;
+	readonly key: string;
+	readonly categories: ReadonlyArray<string>;
+	readonly categoryScale: ChartDiscreteScale;
+	readonly valueScale: ChartLinearScale;
+	readonly orientation: ChartOrientation;
+	readonly stacked: boolean;
+	readonly gap: number | undefined;
+}
+
+/** One anchor per datum, in datum order, for whichever mark is being labelled. */
+function anchorsFor(options: AnchorOptions): ReadonlyArray<ChartPoint> {
+	if (options.marks === "points") {
+		return seriesPoints(options);
+	}
+
+	// Laid out with the FULL key set, not just the labelled one: which lane a bar
+	// occupies depends on how many series share its slot.
+	const rects = barRects(options);
+	const byIndex = new Map(
+		rects
+			.filter((rect) => rect.key === options.key)
+			.map((rect) => [rect.index, rect] as const),
+	);
+	return options.data.map((_, index) => {
+		const rect = byIndex.get(index);
+		// Unreachable for a key that is in `keys`, which it always is; the origin
+		// is a harmless fallback rather than a crash mid-render.
+		return rect === undefined
+			? { x: 0, y: 0 }
+			: barAnchor(rect, options.orientation);
+	});
+}
+
+function ChartLabelList({
+	className,
+	seriesKey,
+	marks = "points",
+	stacked,
+	gap,
+	offset = 8,
+	formatter = formatTickValue,
+	...props
+}: ChartLabelListProps) {
+	const {
+		data,
+		categories,
+		categoryScale,
+		valueScale,
+		orientation,
+		valueKeys,
+		value,
+	} = useChartContext();
+
+	const key = seriesKey ?? valueKeys[0];
+	if (key === undefined) {
+		return null;
+	}
+
+	const isVertical = orientation === "vertical";
+	const anchors = anchorsFor({
+		marks,
+		data,
+		keys: valueKeys,
+		key,
+		categories,
+		categoryScale,
+		valueScale,
+		orientation,
+		stacked: stacked ?? value?.stacked ?? false,
+		gap,
+	});
+
+	return (
+		<g
+			data-slot="chart-label-list"
+			data-series={key}
+			className={cn("fill-foreground", className)}
+			{...props}
+		>
+			{anchors.map((point, index) => {
+				// Labels sit outside the mark, which means below it for a negative
+				// value and to its left on a horizontal chart.
+				const datumValue = readNumber(data[index] ?? {}, key);
+				const away = datumValue < 0 ? -offset : offset;
+				return (
+					<text
+						key={`${categories[index] ?? index}`}
+						data-slot="chart-label"
+						data-index={index}
+						x={isVertical ? point.x : point.x + away}
+						y={isVertical ? point.y - away : point.y}
+						dy={isVertical ? 0 : "0.32em"}
+						textAnchor={
+							isVertical ? "middle" : datumValue < 0 ? "end" : "start"
+						}
+						className="stroke-none text-[10px] tabular-nums"
+					>
+						{formatter(datumValue)}
+					</text>
+				);
+			})}
+		</g>
+	);
+}
+
+export { ChartLabelList };

package/src/components/chart-legend.tsx

@@ -0,0 +1,106 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import type * as React from "react";
+import { createPortal } from "react-dom";
+
+import { useChartContext } from "#/context/chart-context.tsx";
+import { configKeyFor, seriesColor } from "#/core/config.ts";
+
+/**
+ * The colour key. Portals into the root's overlay layer, so it composes inside
+ * `Chart.Root` like every other part while still being ordinary HTML — leave
+ * room for it in the root's `margin`.
+ */
+
+export interface ChartLegendProps {
+	readonly content?: React.ReactNode;
+	readonly align?: "top" | "bottom";
+	readonly className?: string;
+}
+
+function ChartLegend({
+	content,
+	align = "bottom",
+	className,
+}: ChartLegendProps) {
+	const { overlay } = useChartContext();
+	if (overlay === null) {
+		return null;
+	}
+
+	return createPortal(
+		<div
+			data-slot="chart-legend"
+			data-align={align}
+			className={cn(
+				"pointer-events-auto absolute inset-x-0",
+				align === "top" ? "top-0" : "bottom-0",
+				className,
+			)}
+		>
+			{content ?? <ChartLegendContent />}
+		</div>,
+		overlay,
+	);
+}
+
+export interface ChartLegendContentProps extends React.ComponentProps<"div"> {
+	readonly hideIcon?: boolean;
+	/**
+	 * Field naming the config entry for each row. Pass it on charts coloured per
+	 * row (a pie): without it the legend lists the series instead.
+	 */
+	readonly nameKey?: string;
+}
+
+function ChartLegendContent({
+	className,
+	hideIcon = false,
+	nameKey,
+	...props
+}: ChartLegendContentProps) {
+	const { config, data, valueKeys } = useChartContext();
+
+	const entries =
+		nameKey === undefined
+			? valueKeys.map((key, index) => ({ key, index }))
+			: data.map((datum, index) => ({
+					key: configKeyFor(datum, String(index), nameKey),
+					index,
+				}));
+
+	return (
+		<div
+			data-slot="chart-legend-content"
+			className={cn(
+				"flex flex-wrap items-center justify-center gap-x-4 gap-y-1",
+				className,
+			)}
+			{...props}
+		>
+			{entries.map(({ key, index }) => {
+				const Icon = config[key]?.icon;
+				return (
+					<div
+						key={`${key}-${index}`}
+						data-slot="chart-legend-item"
+						data-series={key}
+						className="flex items-center gap-1.5 text-muted-foreground text-xs"
+					>
+						{Icon !== undefined && !hideIcon ? (
+							<Icon />
+						) : (
+							<span
+								data-slot="chart-legend-swatch"
+								className="h-2 w-2 shrink-0 rounded-[2px]"
+								style={{ backgroundColor: seriesColor(config, key, index) }}
+							/>
+						)}
+						{config[key]?.label ?? key}
+					</div>
+				);
+			})}
+		</div>
+	);
+}
+
+export { ChartLegend, ChartLegendContent };

package/src/components/chart-line.tsx

@@ -0,0 +1,100 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import type * as React from "react";
+
+import { useChartContext } from "#/context/chart-context.tsx";
+import { seriesColor } from "#/core/config.ts";
+import { linePath } from "#/core/geometry.ts";
+import { seriesPoints } from "#/core/series.ts";
+import type { ChartCurve } from "#/core/types.ts";
+
+/**
+ * One line per series. The active datum grows a dot, so scrubbing with a finger
+ * shows where you are without needing the tooltip to be readable at the same
+ * time.
+ */
+
+export interface ChartLineProps extends React.ComponentProps<"g"> {
+	readonly keys?: ReadonlyArray<string>;
+	readonly curve?: ChartCurve;
+	readonly strokeWidth?: number;
+	/** Draw a dot on every point, not only the active one. */
+	readonly dots?: boolean;
+}
+
+const ACTIVE_DOT_RADIUS = 4;
+const DOT_RADIUS = 2.5;
+
+function ChartLine({
+	className,
+	keys,
+	curve = "monotone",
+	strokeWidth = 2,
+	dots = false,
+	...props
+}: ChartLineProps) {
+	const {
+		data,
+		categories,
+		categoryScale,
+		valueScale,
+		orientation,
+		valueKeys,
+		config,
+		active,
+	} = useChartContext();
+
+	const drawnKeys = keys ?? valueKeys;
+
+	return (
+		<g data-slot="chart-line" className={cn(className)} {...props}>
+			{drawnKeys.map((key, seriesIndex) => {
+				const points = seriesPoints({
+					data,
+					categories,
+					categoryScale,
+					valueScale,
+					orientation,
+					key,
+				});
+				const color = seriesColor(config, key, seriesIndex);
+				return (
+					<g key={key} data-slot="chart-line-series" data-series={key}>
+						<path
+							data-slot="chart-line-path"
+							data-chart-animate=""
+							d={linePath(points, curve)}
+							fill="none"
+							stroke={color}
+							strokeWidth={strokeWidth}
+							strokeLinecap="round"
+							strokeLinejoin="round"
+						/>
+						{points.map((point, index) => {
+							const isActive = active?.index === index;
+							if (!dots && !isActive) {
+								return null;
+							}
+							return (
+								<circle
+									key={`${key}-${categories[index] ?? index}`}
+									data-slot="chart-dot"
+									data-series={key}
+									data-index={index}
+									data-state={isActive ? "active" : "idle"}
+									cx={point.x}
+									cy={point.y}
+									r={isActive ? ACTIVE_DOT_RADIUS : DOT_RADIUS}
+									fill={color}
+									className="stroke-background"
+									strokeWidth={isActive ? 2 : 0}
+								/>
+							);
+						})}
+					</g>
+				);
+			})}
+		</g>
+	);
+}
+
+export { ChartLine };

package/src/components/chart-pie.tsx

@@ -0,0 +1,130 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import type * as React from "react";
+
+import { ChartSlice } from "#/components/chart-slice.tsx";
+import { useChartContext } from "#/context/chart-context.tsx";
+import { readNumber } from "#/core/chart-model.ts";
+import { configKeyFor, seriesColor } from "#/core/config.ts";
+import { polarFrame, polarToCartesian, sliceAngles } from "#/core/polar.ts";
+
+/**
+ * The pie mark, and its donut variant. Each row of data is one wedge, so the
+ * colours come from the row (via `nameKey`) rather than from a series — which
+ * is also how the tooltip and legend read a round chart.
+ */
+
+export interface ChartPieProps extends React.ComponentProps<"g"> {
+	/** Field holding each wedge's size. Defaults to the first value key. */
+	readonly dataKey?: string;
+	/** Field naming each wedge's config entry. Defaults to the category field. */
+	readonly nameKey?: string;
+	/** Fraction of the outer radius left hollow. `0` draws a full pie. */
+	readonly innerRadiusRatio?: number;
+	readonly padAngle?: number;
+	readonly startAngle?: number;
+	readonly endAngle?: number;
+	/** Pixels kept clear around the wedges, for the active one to lift into. */
+	readonly inset?: number;
+}
+
+/** Milliseconds each wedge waits behind the one before it, on entry. */
+const STAGGER_MS = 40;
+
+function ChartPie({
+	className,
+	dataKey,
+	nameKey,
+	innerRadiusRatio = 0,
+	padAngle = 1,
+	startAngle = 0,
+	endAngle = 360,
+	inset = 8,
+	...props
+}: ChartPieProps) {
+	const {
+		data,
+		innerWidth,
+		innerHeight,
+		valueKeys,
+		config,
+		category,
+		categories,
+		active,
+		setActive,
+	} = useChartContext();
+
+	const key = dataKey ?? valueKeys[0];
+	if (key === undefined) {
+		return null;
+	}
+
+	const { cx, cy, radius } = polarFrame({ innerWidth, innerHeight, inset });
+	const innerRadius = radius * innerRadiusRatio;
+	const slices = sliceAngles(
+		data.map((datum) => readNumber(datum, key)),
+		{ startAngle, endAngle, padAngle },
+	);
+
+	return (
+		<g
+			data-slot="chart-pie"
+			data-variant={innerRadiusRatio > 0 ? "donut" : "pie"}
+			className={cn(className)}
+			{...props}
+		>
+			{slices.map((slice) => {
+				const datum = data[slice.index];
+				const configKey = configKeyFor(
+					datum,
+					categories[slice.index] ?? String(slice.index),
+					nameKey ?? category?.key,
+				);
+				const state =
+					active === null
+						? "idle"
+						: active.index === slice.index
+							? "active"
+							: "muted";
+				// The tooltip follows the wedge's own middle: a pointer inside a ring
+				// is nowhere near the category slots the root's scrubbing uses.
+				const centroid = polarToCartesian(
+					cx,
+					cy,
+					(innerRadius + radius) / 2,
+					(slice.startAngle + slice.endAngle) / 2,
+				);
+				return (
+					<ChartSlice
+						key={configKey}
+						data-index={slice.index}
+						data-series={configKey}
+						cx={cx}
+						cy={cy}
+						innerRadius={innerRadius}
+						outerRadius={radius}
+						startAngle={slice.startAngle}
+						endAngle={slice.endAngle}
+						state={state}
+						fill={seriesColor(config, configKey, slice.index)}
+						style={
+							{
+								"--chart-enter-delay": `${slice.index * STAGGER_MS}ms`,
+							} as React.CSSProperties
+						}
+						onPointerEnter={() =>
+							setActive({ index: slice.index, x: centroid.x, y: centroid.y })
+						}
+						onPointerLeave={() => setActive(null)}
+					/>
+				);
+			})}
+		</g>
+	);
+}
+
+/** A pie with its middle cut out — room for a total, and easier to compare. */
+function ChartDonut({ innerRadiusRatio = 0.6, ...props }: ChartPieProps) {
+	return <ChartPie innerRadiusRatio={innerRadiusRatio} {...props} />;
+}
+
+export { ChartDonut, ChartPie };

package/src/components/chart-points.tsx

@@ -0,0 +1,94 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import type * as React from "react";
+
+import { useChartContext } from "#/context/chart-context.tsx";
+import { readNumber } from "#/core/chart-model.ts";
+import { seriesColor } from "#/core/config.ts";
+import { seriesPoints } from "#/core/series.ts";
+
+/** The scatter mark: one dot per datum per series, optionally sized by a field. */
+
+export interface ChartPointsProps extends React.ComponentProps<"g"> {
+	readonly keys?: ReadonlyArray<string>;
+	readonly radius?: number;
+	/** Field driving the dot area, for a bubble chart. */
+	readonly sizeKey?: string;
+	readonly maxRadius?: number;
+}
+
+/** Milliseconds each dot waits behind the one before it, on entry. */
+const STAGGER_MS = 16;
+
+function ChartPoints({
+	className,
+	keys,
+	radius = 4,
+	sizeKey,
+	maxRadius = 14,
+	...props
+}: ChartPointsProps) {
+	const {
+		data,
+		categories,
+		categoryScale,
+		valueScale,
+		orientation,
+		valueKeys,
+		config,
+		active,
+	} = useChartContext();
+
+	const drawnKeys = keys ?? valueKeys;
+	// Area, not radius, carries the size: doubling a value should double the ink.
+	const largestSize =
+		sizeKey === undefined
+			? 0
+			: Math.max(...data.map((datum) => readNumber(datum, sizeKey)), 0);
+
+	const radiusFor = (index: number): number => {
+		if (sizeKey === undefined || largestSize <= 0) {
+			return radius;
+		}
+		const share = readNumber(data[index] ?? {}, sizeKey) / largestSize;
+		return Math.max(2, maxRadius * Math.sqrt(share));
+	};
+
+	return (
+		<g data-slot="chart-points" className={cn(className)} {...props}>
+			{drawnKeys.map((key, seriesIndex) => {
+				const color = seriesColor(config, key, seriesIndex);
+				return seriesPoints({
+					data,
+					categories,
+					categoryScale,
+					valueScale,
+					orientation,
+					key,
+				}).map((point, index) => (
+					<circle
+						key={`${key}-${categories[index] ?? index}`}
+						data-slot="chart-point"
+						data-series={key}
+						data-index={index}
+						data-state={active?.index === index ? "active" : "idle"}
+						data-chart-animate=""
+						cx={point.x}
+						cy={point.y}
+						r={radiusFor(index)}
+						fill={color}
+						fillOpacity={active?.index === index ? 1 : 0.75}
+						className="stroke-background"
+						strokeWidth={1}
+						style={
+							{
+								"--chart-enter-delay": `${index * STAGGER_MS}ms`,
+							} as React.CSSProperties
+						}
+					/>
+				));
+			})}
+		</g>
+	);
+}
+
+export { ChartPoints };

package/src/components/chart-polar-angle-axis.tsx

@@ -0,0 +1,76 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import type * as React from "react";
+
+import { useChartContext } from "#/context/chart-context.tsx";
+import { axisAngle, polarFrame, polarToCartesian } from "#/core/polar.ts";
+
+/**
+ * The category labels around a radar chart. Each one is anchored away from the
+ * centre, so a label on the left reads right-to-left into the chart rather than
+ * overlapping it.
+ */
+
+export interface ChartPolarAngleAxisProps extends React.ComponentProps<"g"> {
+	readonly tickFormatter?: (value: string) => string;
+	/** Pixels between the outer ring and the labels. */
+	readonly tickMargin?: number;
+	readonly inset?: number;
+}
+
+/** Below this much horizontal offset a label is treated as centred. */
+const ANCHOR_EPSILON = 1;
+
+function ChartPolarAngleAxis({
+	className,
+	tickFormatter,
+	tickMargin = 10,
+	inset = 24,
+	...props
+}: ChartPolarAngleAxisProps) {
+	const { innerWidth, innerHeight, categories } = useChartContext();
+	const { cx, cy, radius } = polarFrame({ innerWidth, innerHeight, inset });
+	const count = categories.length;
+
+	if (count === 0) {
+		return null;
+	}
+
+	return (
+		<g
+			data-slot="chart-polar-angle-axis"
+			className={cn("fill-muted-foreground text-[10px]", className)}
+			{...props}
+		>
+			{categories.map((category, index) => {
+				const point = polarToCartesian(
+					cx,
+					cy,
+					radius + tickMargin,
+					axisAngle(index, count),
+				);
+				const offset = point.x - cx;
+				return (
+					<text
+						key={category}
+						data-slot="chart-polar-tick"
+						x={point.x}
+						y={point.y}
+						dy="0.32em"
+						textAnchor={
+							Math.abs(offset) < ANCHOR_EPSILON
+								? "middle"
+								: offset > 0
+									? "start"
+									: "end"
+						}
+						className="stroke-none"
+					>
+						{tickFormatter ? tickFormatter(category) : category}
+					</text>
+				);
+			})}
+		</g>
+	);
+}
+
+export { ChartPolarAngleAxis };