@voila.dev/ui-chart 1.1.9

package/src/components/chart-style.tsx

@@ -0,0 +1,78 @@
+import type { ChartConfig } from "#/core/config.ts";
+
+/**
+ * Per-chart CSS: the `--color-<key>` variable each configured series is drawn
+ * with, and the entrance animation its marks fade in on.
+ *
+ * The variables live in a stylesheet rather than in an inline `style` so a
+ * `theme` pair can serve light and dark from the same markup — no re-render on
+ * theme change, no reading the document during render.
+ */
+
+/** Where each theme's variables apply. Light is the unprefixed default. */
+const THEME_SELECTORS = { light: "", dark: ".dark" } as const;
+
+/** Guards interpolated colours: variables, functions, hex and keywords only. */
+const CSS_VALUE_PATTERN = /^[\w(),.%#\s-]+$/;
+
+function colorDeclarations(
+	config: ChartConfig,
+	theme: "light" | "dark",
+): string {
+	return Object.entries(config)
+		.map(([key, item]) => {
+			const color = item.theme?.[theme] ?? item.color;
+			return color !== undefined && CSS_VALUE_PATTERN.test(color)
+				? `  --color-${key}: ${color};`
+				: null;
+		})
+		.filter((declaration) => declaration !== null)
+		.join("\n");
+}
+
+/**
+ * Marks opt in with `data-chart-animate`. Gated behind
+ * `prefers-reduced-motion: no-preference`, so a reader who has asked for less
+ * motion gets the finished chart immediately instead of a faster animation.
+ */
+const ENTER_ANIMATION = `
+@keyframes voila-chart-enter {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+@media (prefers-reduced-motion: no-preference) {
+  [data-slot="chart-root"] [data-chart-animate] {
+    animation: voila-chart-enter 320ms cubic-bezier(0.4, 0, 0.2, 1) both;
+    animation-delay: var(--chart-enter-delay, 0ms);
+  }
+}`;
+
+export function ChartStyle({
+	id,
+	config,
+}: {
+	readonly id: string;
+	readonly config: ChartConfig;
+}) {
+	const scoped = Object.entries(THEME_SELECTORS)
+		.map(([theme, prefix]) => {
+			const declarations = colorDeclarations(
+				config,
+				theme as keyof typeof THEME_SELECTORS,
+			);
+			return declarations === ""
+				? ""
+				: `${prefix} [data-chart=${id}] {\n${declarations}\n}`;
+		})
+		.filter((block) => block !== "")
+		.join("\n");
+
+	// A <style> element has no other API. Everything interpolated is either a
+	// generated id or a colour that passed CSS_VALUE_PATTERN.
+	return (
+		<style
+			data-slot="chart-style"
+			dangerouslySetInnerHTML={{ __html: `${scoped}\n${ENTER_ANIMATION}` }}
+		/>
+	);
+}

package/src/components/chart-tooltip.tsx

@@ -0,0 +1,205 @@
+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 { readNumber } from "#/core/chart-model.ts";
+import { configKeyFor, seriesColor } from "#/core/config.ts";
+import { formatTickValue } from "#/core/format.ts";
+
+/**
+ * The readout for the active datum. `ChartTooltip` places it; the content is a
+ * separate component so a caller can replace the body without reimplementing
+ * the positioning, which is the fiddly half.
+ *
+ * It is announced politely rather than assertively: scrubbing across a chart
+ * fires a lot of updates, and interrupting the reader on every one of them
+ * would be worse than silence.
+ */
+
+export type ChartTooltipIndicator = "dot" | "line" | "dashed";
+
+export interface ChartTooltipProps {
+	/** Replaces the default body. */
+	readonly content?: React.ReactNode;
+	/** Pixels between the pointer and the panel. */
+	readonly offset?: number;
+	readonly className?: string;
+}
+
+/** Room the panel needs above the pointer before it stops flipping upwards. */
+const PANEL_HEIGHT = 88;
+/** Nominal half-width, used to keep the panel's edges on screen. */
+const HALF_PANEL = 72;
+
+/** Keeps the panel inside the given bounds rather than letting it hang off. */
+function clamp(value: number, low: number, high: number): number {
+	return Math.min(Math.max(value, low), high);
+}
+
+function ChartTooltip({ content, offset = 12, className }: ChartTooltipProps) {
+	const { active, chartId, margin, overlay } = useChartContext();
+
+	if (active === null || overlay === null) {
+		return null;
+	}
+
+	// Positioned against the viewport and portalled to the document, not to the
+	// chart's own overlay: a sparkline inside a card is both tiny and clipped by
+	// `overflow-hidden`, and a readout the card cuts in half is worse than none.
+	const box = overlay.getBoundingClientRect();
+	const view = overlay.ownerDocument.defaultView;
+	const viewportWidth = view?.innerWidth ?? box.right;
+	const viewportHeight = view?.innerHeight ?? box.bottom;
+
+	const anchorX = box.left + margin.left + active.x;
+	const anchorY = box.top + margin.top + active.y;
+
+	// The panel sits above the reader's finger, where it does not hide what is
+	// being pointed at — unless the top of the window is in the way.
+	const above = anchorY - PANEL_HEIGHT > 0;
+	const left = clamp(anchorX, HALF_PANEL, viewportWidth - HALF_PANEL);
+	const top = clamp(anchorY + (above ? -offset : offset), 0, viewportHeight);
+
+	return createPortal(
+		<div
+			data-slot="chart-tooltip"
+			// The `--color-<key>` variables are scoped to `[data-chart=<id>]`, and
+			// the panel no longer lives inside the chart. Carrying the id onto it
+			// keeps the series colours resolvable from the document body.
+			data-chart={chartId}
+			data-placement={above ? "above" : "below"}
+			className={cn(
+				"pointer-events-none fixed z-50 -translate-x-1/2",
+				above && "-translate-y-full",
+				className,
+			)}
+			style={{ left, top }}
+		>
+			{content ?? <ChartTooltipContent />}
+		</div>,
+		overlay.ownerDocument.body,
+	);
+}
+
+export interface ChartTooltipContentProps extends React.ComponentProps<"div"> {
+	readonly hideLabel?: boolean;
+	readonly hideIndicator?: boolean;
+	readonly indicator?: ChartTooltipIndicator;
+	/** Field naming the config entry, for charts coloured per row. */
+	readonly nameKey?: string;
+	/** Field holding the panel's heading. Defaults to the category. */
+	readonly labelKey?: string;
+	readonly labelClassName?: string;
+	readonly formatter?: (
+		value: number,
+		name: React.ReactNode,
+		configKey: string,
+	) => React.ReactNode;
+	readonly labelFormatter?: (label: string) => React.ReactNode;
+}
+
+const indicatorClassNames: Record<ChartTooltipIndicator, string> = {
+	dot: "h-2.5 w-2.5 rounded-[2px]",
+	line: "h-2.5 w-1 rounded-[2px]",
+	dashed: "h-2.5 w-0 border-[1.5px] border-dashed bg-transparent",
+};
+
+function ChartTooltipMarker({
+	indicator,
+	color,
+}: {
+	readonly indicator: ChartTooltipIndicator;
+	readonly color: string;
+}) {
+	return (
+		<div
+			data-slot="chart-tooltip-marker"
+			className={cn("shrink-0", indicatorClassNames[indicator])}
+			style={{ backgroundColor: color, borderColor: color }}
+		/>
+	);
+}
+
+function ChartTooltipContent({
+	className,
+	hideLabel = false,
+	hideIndicator = false,
+	indicator = "dot",
+	nameKey,
+	labelKey,
+	labelClassName,
+	formatter,
+	labelFormatter,
+	...props
+}: ChartTooltipContentProps) {
+	const { active, data, categories, valueKeys, config } = useChartContext();
+
+	if (active === null) {
+		return null;
+	}
+	const datum = data[active.index];
+	if (datum === undefined) {
+		return null;
+	}
+
+	const rawLabel =
+		labelKey === undefined
+			? (categories[active.index] ?? "")
+			: String(datum[labelKey] ?? "");
+	const label = labelFormatter ? labelFormatter(rawLabel) : rawLabel;
+
+	return (
+		<div
+			data-slot="chart-tooltip-content"
+			role="status"
+			aria-live="polite"
+			className={cn(
+				"grid min-w-32 items-start gap-1.5 rounded-lg bg-popover px-2.5 py-1.5 text-xs text-popover-foreground shadow-md ring-1 ring-foreground/10",
+				className,
+			)}
+			{...props}
+		>
+			{hideLabel ? null : (
+				<div className={cn("font-medium", labelClassName)}>{label}</div>
+			)}
+			<div className="grid gap-1.5">
+				{valueKeys.map((key, index) => {
+					const configKey = configKeyFor(datum, key, nameKey);
+					const name = config[configKey]?.label ?? configKey;
+					const value = readNumber(datum, key);
+					const Icon = config[configKey]?.icon;
+					return (
+						<div
+							key={key}
+							data-slot="chart-tooltip-row"
+							data-series={key}
+							className="flex w-full items-center gap-2 leading-none"
+						>
+							{hideIndicator ? null : Icon ? (
+								<Icon />
+							) : (
+								<ChartTooltipMarker
+									indicator={indicator}
+									color={seriesColor(config, configKey, index)}
+								/>
+							)}
+							{formatter ? (
+								formatter(value, name, configKey)
+							) : (
+								<div className="flex flex-1 items-center justify-between gap-2">
+									<span className="text-muted-foreground">{name}</span>
+									<span className="font-medium font-mono text-foreground tabular-nums">
+										{formatTickValue(value)}
+									</span>
+								</div>
+							)}
+						</div>
+					);
+				})}
+			</div>
+		</div>
+	);
+}
+
+export { ChartTooltip, ChartTooltipContent };

package/src/components/chart-x-axis.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 { axisTicks } from "#/core/axis.ts";
+import { formatLabel } from "#/core/format.ts";
+
+/** The bottom axis: categories on a vertical chart, values on a horizontal one. */
+
+export interface ChartXAxisProps extends React.ComponentProps<"g"> {
+	readonly tickLine?: boolean;
+	readonly axisLine?: boolean;
+	readonly tickCount?: number;
+	/** Minimum pixels between two labels before ticks start being dropped. */
+	readonly minTickGap?: number;
+	/** Gap between the axis and its labels. */
+	readonly tickMargin?: number;
+	readonly tickFormatter?: (value: number | string) => string;
+	/** Keeps the scale but draws nothing — useful behind a bar's own labels. */
+	readonly hide?: boolean;
+}
+
+const TICK_LINE_LENGTH = 4;
+
+function ChartXAxis({
+	className,
+	tickLine = false,
+	axisLine = false,
+	tickCount = 5,
+	minTickGap = 8,
+	tickMargin = 8,
+	tickFormatter,
+	hide = false,
+	...props
+}: ChartXAxisProps) {
+	const { xScale, innerWidth, innerHeight } = useChartContext();
+	if (hide) {
+		return null;
+	}
+
+	const ticks = axisTicks(xScale, {
+		count: tickCount,
+		minTickGap,
+		available: innerWidth,
+	});
+	const format = tickFormatter ?? formatLabel;
+
+	return (
+		<g
+			data-slot="chart-x-axis"
+			transform={`translate(0,${innerHeight})`}
+			className={cn("stroke-border text-muted-foreground", className)}
+			{...props}
+		>
+			{axisLine ? (
+				<line
+					data-slot="chart-axis-line"
+					x1={0}
+					x2={innerWidth}
+					y1={0}
+					y2={0}
+				/>
+			) : null}
+			{ticks.map((tick) => (
+				<g
+					key={`${tick.value}`}
+					data-slot="chart-x-axis-tick"
+					transform={`translate(${tick.offset},0)`}
+				>
+					{tickLine ? (
+						<line
+							data-slot="chart-tick-line"
+							x1={0}
+							x2={0}
+							y1={0}
+							y2={TICK_LINE_LENGTH}
+						/>
+					) : null}
+					<text
+						data-slot="chart-tick-label"
+						y={tickMargin}
+						dy="0.71em"
+						textAnchor="middle"
+						className="fill-muted-foreground stroke-none text-[10px]"
+					>
+						{format(tick.value)}
+					</text>
+				</g>
+			))}
+		</g>
+	);
+}
+
+export { ChartXAxis };

package/src/components/chart-y-axis.tsx

@@ -0,0 +1,90 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import type * as React from "react";
+
+import { useChartContext } from "#/context/chart-context.tsx";
+import { axisTicks } from "#/core/axis.ts";
+import { formatLabel } from "#/core/format.ts";
+
+/** The left axis: values on a vertical chart, categories on a horizontal one. */
+
+export interface ChartYAxisProps extends React.ComponentProps<"g"> {
+	readonly tickLine?: boolean;
+	readonly axisLine?: boolean;
+	readonly tickCount?: number;
+	readonly minTickGap?: number;
+	readonly tickMargin?: number;
+	readonly tickFormatter?: (value: number | string) => string;
+	readonly hide?: boolean;
+}
+
+const TICK_LINE_LENGTH = 4;
+
+function ChartYAxis({
+	className,
+	tickLine = false,
+	axisLine = false,
+	tickCount = 5,
+	minTickGap = 4,
+	tickMargin = 8,
+	tickFormatter,
+	hide = false,
+	...props
+}: ChartYAxisProps) {
+	const { yScale, innerHeight } = useChartContext();
+	if (hide) {
+		return null;
+	}
+
+	const ticks = axisTicks(yScale, {
+		count: tickCount,
+		minTickGap,
+		available: innerHeight,
+	});
+	const format = tickFormatter ?? formatLabel;
+
+	return (
+		<g
+			data-slot="chart-y-axis"
+			className={cn("stroke-border text-muted-foreground", className)}
+			{...props}
+		>
+			{axisLine ? (
+				<line
+					data-slot="chart-axis-line"
+					x1={0}
+					x2={0}
+					y1={0}
+					y2={innerHeight}
+				/>
+			) : null}
+			{ticks.map((tick) => (
+				<g
+					key={`${tick.value}`}
+					data-slot="chart-y-axis-tick"
+					transform={`translate(0,${tick.offset})`}
+				>
+					{tickLine ? (
+						<line
+							data-slot="chart-tick-line"
+							x1={0}
+							x2={-TICK_LINE_LENGTH}
+							y1={0}
+							y2={0}
+						/>
+					) : null}
+					<text
+						data-slot="chart-tick-label"
+						x={-tickMargin}
+						dy="0.32em"
+						textAnchor="end"
+						className="fill-muted-foreground stroke-none text-[10px]"
+					>
+						{format(tick.value)}
+					</text>
+				</g>
+			))}
+		</g>
+	);
+}
+
+export { ChartYAxis };

package/src/components/chart.tsx

@@ -0,0 +1,146 @@
+import { ChartArea } from "#/components/chart-area.tsx";
+import { ChartBars } from "#/components/chart-bars.tsx";
+import { ChartCursor } from "#/components/chart-cursor.tsx";
+import { ChartEmpty } from "#/components/chart-empty.tsx";
+import { ChartGrid } from "#/components/chart-grid.tsx";
+import { ChartLabelList } from "#/components/chart-label-list.tsx";
+import { ChartLegend, ChartLegendContent } from "#/components/chart-legend.tsx";
+import { ChartLine } from "#/components/chart-line.tsx";
+import { ChartDonut, ChartPie } from "#/components/chart-pie.tsx";
+import { ChartPoints } from "#/components/chart-points.tsx";
+import { ChartPolarAngleAxis } from "#/components/chart-polar-angle-axis.tsx";
+import { ChartPolarGrid } from "#/components/chart-polar-grid.tsx";
+import { ChartRadar } from "#/components/chart-radar.tsx";
+import { ChartRadialBar } from "#/components/chart-radial-bar.tsx";
+import { ChartReferenceLine } from "#/components/chart-reference-line.tsx";
+import { ChartRoot } from "#/components/chart-root.tsx";
+import { ChartSkeleton } from "#/components/chart-skeleton.tsx";
+import { ChartSlice } from "#/components/chart-slice.tsx";
+import { ChartStyle } from "#/components/chart-style.tsx";
+import {
+	ChartTooltip,
+	ChartTooltipContent,
+} from "#/components/chart-tooltip.tsx";
+import { ChartXAxis } from "#/components/chart-x-axis.tsx";
+import { ChartYAxis } from "#/components/chart-y-axis.tsx";
+import { useChartContext } from "#/context/chart-context.tsx";
+
+/**
+ * The chart kit's public surface.
+ *
+ * `Chart.Root` frames the picture and `Chart.*` draws into it:
+ *
+ * ```tsx
+ * <Chart.Root config={config} data={data} x={{ key: "month" }} y={{ keys: ["missions"] }}>
+ *   <Chart.Grid />
+ *   <Chart.XAxis />
+ *   <Chart.Cursor />
+ *   <Chart.Bars />
+ *   <Chart.Tooltip />
+ * </Chart.Root>
+ * ```
+ *
+ * Every part is also a flat named export, for callers who would rather import
+ * `ChartBars` than reach through the namespace.
+ */
+const Chart = {
+	Root: ChartRoot,
+	Style: ChartStyle,
+	Grid: ChartGrid,
+	XAxis: ChartXAxis,
+	YAxis: ChartYAxis,
+	Bars: ChartBars,
+	Line: ChartLine,
+	Area: ChartArea,
+	Points: ChartPoints,
+	ReferenceLine: ChartReferenceLine,
+	LabelList: ChartLabelList,
+	Pie: ChartPie,
+	Donut: ChartDonut,
+	Slice: ChartSlice,
+	Radar: ChartRadar,
+	PolarGrid: ChartPolarGrid,
+	PolarAngleAxis: ChartPolarAngleAxis,
+	RadialBar: ChartRadialBar,
+	Cursor: ChartCursor,
+	Tooltip: ChartTooltip,
+	TooltipContent: ChartTooltipContent,
+	Legend: ChartLegend,
+	LegendContent: ChartLegendContent,
+	Skeleton: ChartSkeleton,
+	Empty: ChartEmpty,
+} as const;
+
+/** The chart the current part is drawing into. Throws outside a `Chart.Root`. */
+const useChart = useChartContext;
+
+export type { ChartAreaProps } from "#/components/chart-area.tsx";
+export type { ChartBarsProps } from "#/components/chart-bars.tsx";
+export type { ChartCursorProps } from "#/components/chart-cursor.tsx";
+export type { ChartGridProps } from "#/components/chart-grid.tsx";
+export type { ChartLabelListProps } from "#/components/chart-label-list.tsx";
+export type {
+	ChartLegendContentProps,
+	ChartLegendProps,
+} from "#/components/chart-legend.tsx";
+export type { ChartLineProps } from "#/components/chart-line.tsx";
+export type { ChartPieProps } from "#/components/chart-pie.tsx";
+export type { ChartPointsProps } from "#/components/chart-points.tsx";
+export type { ChartPolarAngleAxisProps } from "#/components/chart-polar-angle-axis.tsx";
+export type { ChartPolarGridProps } from "#/components/chart-polar-grid.tsx";
+export type { ChartRadarProps } from "#/components/chart-radar.tsx";
+export type { ChartRadialBarProps } from "#/components/chart-radial-bar.tsx";
+export type { ChartReferenceLineProps } from "#/components/chart-reference-line.tsx";
+export type { ChartRootProps } from "#/components/chart-root.tsx";
+export type { ChartSkeletonProps } from "#/components/chart-skeleton.tsx";
+export type { ChartSliceProps } from "#/components/chart-slice.tsx";
+export type {
+	ChartTooltipContentProps,
+	ChartTooltipIndicator,
+	ChartTooltipProps,
+} from "#/components/chart-tooltip.tsx";
+export type { ChartXAxisProps } from "#/components/chart-x-axis.tsx";
+export type { ChartYAxisProps } from "#/components/chart-y-axis.tsx";
+export type { ChartContextValue } from "#/context/chart-context.tsx";
+export type {
+	ChartCategorySpec,
+	ChartValueSpec,
+} from "#/core/chart-model.ts";
+export type { ChartConfig, ChartTheme } from "#/core/config.ts";
+export type {
+	ChartCurve,
+	ChartDatum,
+	ChartMargin,
+	ChartOrientation,
+} from "#/core/types.ts";
+export type { ChartActive } from "#/hooks/use-chart-pointer.ts";
+export {
+	Chart,
+	ChartArea,
+	ChartBars,
+	ChartCursor,
+	ChartDonut,
+	ChartEmpty,
+	ChartGrid,
+	ChartLabelList,
+	ChartLegend,
+	ChartLegendContent,
+	ChartLine,
+	ChartPie,
+	ChartPoints,
+	ChartPolarAngleAxis,
+	ChartPolarGrid,
+	ChartRadar,
+	ChartRadialBar,
+	ChartReferenceLine,
+	ChartRoot,
+	ChartSkeleton,
+	ChartSlice,
+	ChartStyle,
+	ChartTooltip,
+	ChartTooltipContent,
+	ChartXAxis,
+	ChartYAxis,
+	useChart,
+	useChartContext,
+};

package/src/context/chart-context.tsx

@@ -0,0 +1,70 @@
+import * as React from "react";
+
+import type { ChartCategorySpec, ChartValueSpec } from "#/core/chart-model.ts";
+import type { ChartConfig } from "#/core/config.ts";
+import type {
+	ChartDatum,
+	ChartDiscreteScale,
+	ChartLinearScale,
+	ChartMargin,
+	ChartOrientation,
+	ChartScale,
+} from "#/core/types.ts";
+import type { ChartActive } from "#/hooks/use-chart-pointer.ts";
+
+export type { ChartConfig } from "#/core/config.ts";
+
+export interface ChartContextValue {
+	/** Stable per-chart id. Scopes the injected `--color-<key>` variables. */
+	readonly chartId: string;
+	readonly config: ChartConfig;
+	readonly data: ReadonlyArray<ChartDatum>;
+	readonly width: number;
+	readonly height: number;
+	readonly margin: ChartMargin;
+	readonly innerWidth: number;
+	readonly innerHeight: number;
+	readonly orientation: ChartOrientation;
+	readonly category: ChartCategorySpec | undefined;
+	readonly value: ChartValueSpec | undefined;
+	readonly categories: ReadonlyArray<string>;
+	readonly valueKeys: ReadonlyArray<string>;
+	readonly categoryScale: ChartDiscreteScale;
+	readonly valueScale: ChartLinearScale;
+	readonly xScale: ChartScale;
+	readonly yScale: ChartScale;
+	readonly active: ChartActive | null;
+	readonly setActive: React.Dispatch<React.SetStateAction<ChartActive | null>>;
+	/**
+	 * Where overlay parts (tooltip, legend) portal to. `null` until the root has
+	 * mounted, which is exactly what keeps the server render free of them.
+	 */
+	readonly overlay: HTMLDivElement | null;
+}
+
+const ChartContext = React.createContext<ChartContextValue | null>(null);
+
+export function ChartProvider({
+	value,
+	children,
+}: {
+	readonly value: ChartContextValue;
+	readonly children: React.ReactNode;
+}) {
+	return (
+		<ChartContext.Provider value={value}>{children}</ChartContext.Provider>
+	);
+}
+
+/**
+ * The chart every mark is drawing into. Throws rather than returning `null`:
+ * a `Chart.Bars` outside a `Chart.Root` has no scales, so there is nothing
+ * sensible to render and a clear error beats an empty SVG.
+ */
+export function useChartContext(): ChartContextValue {
+	const context = React.useContext(ChartContext);
+	if (context === null) {
+		throw new Error("Chart parts must be used within a <Chart.Root />");
+	}
+	return context;
+}