@voila.dev/ui-chart 1.1.9

package/src/components/chart-polar-grid.tsx

@@ -0,0 +1,64 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import type * as React from "react";
+
+import { useChartContext } from "#/context/chart-context.tsx";
+import { polygonPath } from "#/core/geometry.ts";
+import { polarFrame, ringPoints, ringRadii } from "#/core/polar.ts";
+
+/**
+ * The web behind a radar chart: rings at even value steps plus one spoke per
+ * axis. The rings are polygons, not circles, so they meet the spokes exactly
+ * where the data will.
+ */
+
+export interface ChartPolarGridProps extends React.ComponentProps<"g"> {
+	readonly rings?: number;
+	readonly spokes?: boolean;
+	readonly inset?: number;
+}
+
+function ChartPolarGrid({
+	className,
+	rings = 4,
+	spokes = true,
+	inset = 24,
+	...props
+}: ChartPolarGridProps) {
+	const { innerWidth, innerHeight, categories } = useChartContext();
+	const { cx, cy, radius } = polarFrame({ innerWidth, innerHeight, inset });
+	const axisCount = categories.length;
+
+	if (axisCount === 0 || radius <= 0) {
+		return null;
+	}
+
+	return (
+		<g
+			data-slot="chart-polar-grid"
+			className={cn("fill-none stroke-border/60", className)}
+			{...props}
+		>
+			{ringRadii(radius, rings).map((ringRadius) => (
+				<path
+					key={ringRadius}
+					data-slot="chart-polar-ring"
+					d={polygonPath(ringPoints(cx, cy, ringRadius, axisCount))}
+				/>
+			))}
+			{spokes
+				? ringPoints(cx, cy, radius, axisCount).map((point, index) => (
+						<line
+							key={categories[index] ?? index}
+							data-slot="chart-polar-spoke"
+							x1={cx}
+							y1={cy}
+							x2={point.x}
+							y2={point.y}
+						/>
+					))
+				: null}
+		</g>
+	);
+}
+
+export { ChartPolarGrid };

package/src/components/chart-radar.tsx

@@ -0,0 +1,103 @@
+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 { polygonPath } from "#/core/geometry.ts";
+import { axisAngle, polarFrame, polarToCartesian } from "#/core/polar.ts";
+
+/**
+ * One closed shape per series, with a vertex on every category axis. Radii come
+ * from the value axis's domain, so two radar series on the same chart are
+ * directly comparable.
+ */
+
+export interface ChartRadarProps extends React.ComponentProps<"g"> {
+	readonly keys?: ReadonlyArray<string>;
+	readonly fillOpacity?: number;
+	readonly strokeWidth?: number;
+	readonly dots?: boolean;
+	readonly inset?: number;
+}
+
+const DOT_RADIUS = 3;
+
+function ChartRadar({
+	className,
+	keys,
+	fillOpacity = 0.35,
+	strokeWidth = 2,
+	dots = false,
+	inset = 24,
+	...props
+}: ChartRadarProps) {
+	const {
+		data,
+		innerWidth,
+		innerHeight,
+		categories,
+		valueKeys,
+		valueScale,
+		config,
+	} = useChartContext();
+
+	const drawnKeys = keys ?? valueKeys;
+	const { cx, cy, radius } = polarFrame({ innerWidth, innerHeight, inset });
+	const [domainStart, domainEnd] = valueScale.domain;
+	const span = domainEnd - domainStart;
+	const count = categories.length;
+
+	if (count === 0 || radius <= 0) {
+		return null;
+	}
+
+	const radiusFor = (value: number): number =>
+		span === 0 ? 0 : Math.max(0, ((value - domainStart) / span) * radius);
+
+	return (
+		<g data-slot="chart-radar" className={cn(className)} {...props}>
+			{drawnKeys.map((key, seriesIndex) => {
+				const color = seriesColor(config, key, seriesIndex);
+				const vertices = data.map((datum, index) =>
+					polarToCartesian(
+						cx,
+						cy,
+						radiusFor(readNumber(datum, key)),
+						axisAngle(index, count),
+					),
+				);
+				return (
+					<g key={key} data-slot="chart-radar-series" data-series={key}>
+						<path
+							data-slot="chart-radar-shape"
+							data-chart-animate=""
+							d={polygonPath(vertices)}
+							fill={color}
+							fillOpacity={fillOpacity}
+							stroke={color}
+							strokeWidth={strokeWidth}
+							strokeLinejoin="round"
+						/>
+						{dots
+							? vertices.map((vertex, index) => (
+									<circle
+										key={categories[index] ?? index}
+										data-slot="chart-dot"
+										data-series={key}
+										data-index={index}
+										cx={vertex.x}
+										cy={vertex.y}
+										r={DOT_RADIUS}
+										fill={color}
+									/>
+								))
+							: null}
+					</g>
+				);
+			})}
+		</g>
+	);
+}
+
+export { ChartRadar };

package/src/components/chart-radial-bar.tsx

@@ -0,0 +1,122 @@
+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 { configKeyFor, seriesColor } from "#/core/config.ts";
+import { arcPath } from "#/core/geometry.ts";
+import { polarFrame } from "#/core/polar.ts";
+
+/**
+ * Bars bent around the centre — one concentric track per row. Reads as a set of
+ * gauges, which is what it is usually asked to be: a completion rate, a fill
+ * rate, a share of a target.
+ */
+
+export interface ChartRadialBarProps extends React.ComponentProps<"g"> {
+	readonly dataKey?: string;
+	readonly nameKey?: string;
+	/** Value that fills a whole track. Defaults to the value axis maximum. */
+	readonly max?: number;
+	readonly startAngle?: number;
+	readonly endAngle?: number;
+	/** Fraction of the radius left hollow in the middle. */
+	readonly innerRadiusRatio?: number;
+	/** Draw the unfilled remainder of each track. */
+	readonly background?: boolean;
+	readonly inset?: number;
+	/** Pixels between two tracks. */
+	readonly gap?: number;
+}
+
+function ChartRadialBar({
+	className,
+	dataKey,
+	nameKey,
+	max,
+	startAngle = 0,
+	endAngle = 360,
+	innerRadiusRatio = 0.3,
+	background = true,
+	inset = 8,
+	gap = 4,
+	...props
+}: ChartRadialBarProps) {
+	const {
+		data,
+		innerWidth,
+		innerHeight,
+		valueKeys,
+		valueScale,
+		config,
+		category,
+		categories,
+		active,
+		setActive,
+	} = useChartContext();
+
+	const key = dataKey ?? valueKeys[0];
+	if (key === undefined || data.length === 0) {
+		return null;
+	}
+
+	const { cx, cy, radius } = polarFrame({ innerWidth, innerHeight, inset });
+	const innerRadius = radius * innerRadiusRatio;
+	const trackDepth = (radius - innerRadius) / data.length;
+	const ceiling = max ?? valueScale.domain[1];
+	const span = endAngle - startAngle;
+
+	return (
+		<g data-slot="chart-radial-bar" className={cn(className)} {...props}>
+			{data.map((datum, index) => {
+				// Track zero is the outermost, so the first row of data reads first.
+				const trackOuter = radius - index * trackDepth;
+				const trackInner = trackOuter - trackDepth + gap;
+				const fraction =
+					ceiling === 0 ? 0 : Math.min(1, readNumber(datum, key) / ceiling);
+				const configKey = configKeyFor(
+					datum,
+					categories[index] ?? String(index),
+					nameKey ?? category?.key,
+				);
+				const track = {
+					cx,
+					cy,
+					innerRadius: trackInner,
+					outerRadius: trackOuter,
+				};
+				return (
+					<g
+						key={configKey}
+						data-slot="chart-radial-track"
+						data-series={configKey}
+						data-index={index}
+						data-state={active?.index === index ? "active" : "idle"}
+						onPointerEnter={() => setActive({ index, x: cx, y: cy })}
+						onPointerLeave={() => setActive(null)}
+					>
+						{background ? (
+							<path
+								data-slot="chart-radial-background"
+								d={arcPath({ ...track, startAngle, endAngle })}
+								className="fill-muted"
+							/>
+						) : null}
+						<path
+							data-slot="chart-radial-value"
+							data-chart-animate=""
+							d={arcPath({
+								...track,
+								startAngle,
+								endAngle: startAngle + span * fraction,
+							})}
+							fill={seriesColor(config, configKey, index)}
+						/>
+					</g>
+				);
+			})}
+		</g>
+	);
+}
+
+export { ChartRadialBar };

package/src/components/chart-reference-line.tsx

@@ -0,0 +1,60 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import type * as React from "react";
+
+import { useChartContext } from "#/context/chart-context.tsx";
+import { formatTickValue } from "#/core/format.ts";
+
+/**
+ * A marker line across the plot at one value — a target, a threshold, or the
+ * zero baseline a chart with negative values needs in order to be readable.
+ */
+
+export interface ChartReferenceLineProps extends React.ComponentProps<"g"> {
+	/** Position on the value axis. */
+	readonly value: number;
+	readonly label?: string;
+	readonly strokeDasharray?: string;
+}
+
+function ChartReferenceLine({
+	className,
+	value,
+	label,
+	strokeDasharray = "4 4",
+	...props
+}: ChartReferenceLineProps) {
+	const { valueScale, orientation, innerWidth, innerHeight } =
+		useChartContext();
+	const offset = valueScale.scale(value);
+	const isVertical = orientation === "vertical";
+
+	return (
+		<g
+			data-slot="chart-reference-line"
+			data-value={value}
+			className={cn("stroke-border", className)}
+			{...props}
+		>
+			<line
+				x1={isVertical ? 0 : offset}
+				x2={isVertical ? innerWidth : offset}
+				y1={isVertical ? offset : 0}
+				y2={isVertical ? offset : innerHeight}
+				strokeDasharray={strokeDasharray}
+			/>
+			<text
+				data-slot="chart-reference-label"
+				x={isVertical ? innerWidth : offset}
+				y={isVertical ? offset : 0}
+				dx={isVertical ? -4 : 4}
+				dy={isVertical ? -4 : 10}
+				textAnchor={isVertical ? "end" : "start"}
+				className="fill-muted-foreground stroke-none text-[10px]"
+			>
+				{label ?? formatTickValue(value)}
+			</text>
+		</g>
+	);
+}
+
+export { ChartReferenceLine };

package/src/components/chart-root.tsx

@@ -0,0 +1,188 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import * as React from "react";
+
+import { ChartDataTable } from "#/components/chart-data-table.tsx";
+import { ChartStyle } from "#/components/chart-style.tsx";
+import {
+	type ChartContextValue,
+	ChartProvider,
+} from "#/context/chart-context.tsx";
+import {
+	buildChartModel,
+	type ChartCategorySpec,
+	type ChartValueSpec,
+} from "#/core/chart-model.ts";
+import { type ChartConfig, seriesLabelText } from "#/core/config.ts";
+import type {
+	ChartDatum,
+	ChartMargin,
+	ChartOrientation,
+} from "#/core/types.ts";
+import { useChartDimensions } from "#/hooks/use-chart-dimensions.ts";
+import { useChartPointer } from "#/hooks/use-chart-pointer.ts";
+
+/**
+ * The frame every other chart part draws into: it measures itself, derives the
+ * scales, owns the active datum and publishes all of it on context.
+ *
+ * Marks are placed inside the plotting area, which is the SVG inset by
+ * `margin`. Chrome that is not SVG — tooltip, legend — portals into an overlay
+ * layer above it, so composition stays flat at the call site.
+ */
+
+const DEFAULT_MARGIN: ChartMargin = {
+	top: 8,
+	right: 8,
+	bottom: 24,
+	left: 40,
+};
+
+export interface ChartRootProps
+	extends Omit<React.ComponentProps<"div">, "children"> {
+	/** Per-series labels, colours and icons. */
+	readonly config: ChartConfig;
+	readonly data?: ReadonlyArray<ChartDatum>;
+	/** The category axis: which field names each row. */
+	readonly x?: ChartCategorySpec;
+	/** The value axis: which fields are plotted, and how they combine. */
+	readonly y?: ChartValueSpec;
+	/** `horizontal` puts the categories down the side. */
+	readonly orientation?: ChartOrientation;
+	readonly margin?: Partial<ChartMargin>;
+	/** Turns pointer scrubbing and keyboard navigation off. */
+	readonly interactive?: boolean;
+	readonly children?: React.ReactNode;
+}
+
+/**
+ * A one-line description of the picture, for readers who get the `role="img"`
+ * label but not the drawing. The hidden data table underneath carries the
+ * numbers themselves.
+ */
+function describeChart(
+	config: ChartConfig,
+	valueKeys: ReadonlyArray<string>,
+	count: number,
+): string {
+	if (valueKeys.length === 0) {
+		return "Chart";
+	}
+	const names = valueKeys.map((key) => seriesLabelText(config, key)).join(", ");
+	return `Chart of ${names} over ${count} ${count === 1 ? "point" : "points"}`;
+}
+
+function ChartRoot({
+	id,
+	className,
+	config,
+	data = [],
+	x,
+	y,
+	orientation = "vertical",
+	margin: marginProp,
+	interactive = true,
+	children,
+	"aria-label": ariaLabel,
+	...props
+}: ChartRootProps) {
+	const generatedId = React.useId();
+	const chartId = `chart-${id ?? generatedId.replace(/:/g, "")}`;
+	const { ref, width, height } = useChartDimensions();
+	const [overlay, setOverlay] = React.useState<HTMLDivElement | null>(null);
+
+	const margin: ChartMargin = { ...DEFAULT_MARGIN, ...marginProp };
+	const innerWidth = Math.max(0, width - margin.left - margin.right);
+	const innerHeight = Math.max(0, height - margin.top - margin.bottom);
+
+	const model = React.useMemo(
+		() =>
+			buildChartModel({
+				data,
+				category: x,
+				value: y,
+				orientation,
+				innerWidth,
+				innerHeight,
+			}),
+		[data, x, y, orientation, innerWidth, innerHeight],
+	);
+
+	const { active, setActive, handlers } = useChartPointer({
+		enabled: interactive && x !== undefined,
+		count: data.length,
+		width,
+		height,
+		margin,
+		orientation,
+		categoryScale: model.categoryScale,
+	});
+
+	const description =
+		ariaLabel ?? describeChart(config, model.valueKeys, data.length);
+
+	const context: ChartContextValue = {
+		chartId,
+		config,
+		data,
+		width,
+		height,
+		margin,
+		innerWidth,
+		innerHeight,
+		orientation,
+		category: x,
+		value: y,
+		active,
+		setActive,
+		overlay,
+		...model,
+	};
+
+	return (
+		<div
+			data-slot="chart-root"
+			data-chart={chartId}
+			data-orientation={orientation}
+			ref={ref}
+			className={cn(
+				"relative flex aspect-video w-full justify-center text-xs",
+				className,
+			)}
+			{...props}
+		>
+			<ChartStyle id={chartId} config={config} />
+			<svg
+				data-slot="chart-svg"
+				role="img"
+				aria-label={description}
+				width={width}
+				height={height}
+				viewBox={`0 0 ${width} ${height}`}
+				className="absolute inset-0 h-full w-full rounded-md outline-none focus-visible:ring-2 focus-visible:ring-ring"
+				{...handlers}
+			>
+				<g
+					data-slot="chart-plot"
+					transform={`translate(${margin.left},${margin.top})`}
+				>
+					<ChartProvider value={context}>{children}</ChartProvider>
+				</g>
+			</svg>
+			<div
+				data-slot="chart-overlay"
+				ref={setOverlay}
+				className="pointer-events-none absolute inset-0"
+			/>
+			<ChartDataTable
+				caption={description}
+				categoryLabel={x?.key ?? "Category"}
+				categories={model.categories}
+				valueKeys={model.valueKeys}
+				data={data}
+				config={config}
+			/>
+		</div>
+	);
+}
+
+export { ChartRoot };

package/src/components/chart-skeleton.tsx

@@ -0,0 +1,45 @@
+import { Skeleton } from "@voila.dev/ui/components/skeleton";
+import { cn } from "@voila.dev/ui/lib/utils";
+import type * as React from "react";
+
+/**
+ * Loading placeholder shaped like a bar chart. Defaults to the root's
+ * aspect-video box — size it like the chart it stands in for (the same
+ * `h-* w-full`), or the page will jump when the data lands.
+ *
+ * The English default label matches the kit's other built-in labels; pass a
+ * localized `label` from the app.
+ */
+
+/** Fixed, not random, so the server and the client render the same bars. */
+const BAR_HEIGHTS = [40, 70, 55, 90, 65, 80, 50] as const;
+
+export interface ChartSkeletonProps extends React.ComponentProps<"div"> {
+	readonly label?: string;
+}
+
+function ChartSkeleton({
+	className,
+	label = "Loading",
+	...props
+}: ChartSkeletonProps) {
+	return (
+		<div
+			data-slot="chart-skeleton"
+			role="status"
+			aria-label={label}
+			className={cn("flex aspect-video w-full items-end gap-2", className)}
+			{...props}
+		>
+			{BAR_HEIGHTS.map((barHeight) => (
+				<Skeleton
+					key={barHeight}
+					className="w-full"
+					style={{ height: `${barHeight}%` }}
+				/>
+			))}
+		</div>
+	);
+}
+
+export { ChartSkeleton };

package/src/components/chart-slice.tsx

@@ -0,0 +1,59 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import type * as React from "react";
+
+import { type ArcOptions, arcPath } from "#/core/geometry.ts";
+
+/**
+ * One wedge of a pie or donut. Exposed on its own so a caller can build a
+ * bespoke round chart out of the same part the built-in ones use.
+ */
+
+export interface ChartSliceProps
+	extends ArcOptions,
+		Omit<React.ComponentProps<"path">, "d" | "cx" | "cy"> {
+	readonly state?: "idle" | "active" | "muted";
+}
+
+/** How far the active wedge lifts out of the ring. */
+const ACTIVE_LIFT = 4;
+
+function ChartSlice({
+	cx,
+	cy,
+	innerRadius,
+	outerRadius,
+	startAngle,
+	endAngle,
+	state = "idle",
+	className,
+	...props
+}: ChartSliceProps) {
+	const path = arcPath({
+		cx,
+		cy,
+		innerRadius,
+		outerRadius: state === "active" ? outerRadius + ACTIVE_LIFT : outerRadius,
+		startAngle,
+		endAngle,
+	});
+	if (path === "") {
+		return null;
+	}
+
+	return (
+		<path
+			data-slot="chart-slice"
+			data-state={state}
+			data-chart-animate=""
+			d={path}
+			className={cn(
+				"stroke-background transition-opacity duration-150 data-[state=muted]:opacity-60",
+				className,
+			)}
+			strokeWidth={2}
+			{...props}
+		/>
+	);
+}
+
+export { ChartSlice };