@voila.dev/ui-chart 1.1.9

package/src/core/axis.ts

@@ -0,0 +1,53 @@
+import { isLinearScale } from "#/core/scales.ts";
+import type { ChartScale } from "#/core/types.ts";
+
+/**
+ * Where an axis puts its ticks. Works off either kind of scale so `XAxis` and
+ * `YAxis` are the same component twice, once per direction.
+ */
+
+export interface AxisTick {
+	/** The domain value, before formatting. */
+	readonly value: number | string;
+	/** Pixel offset along the axis. */
+	readonly offset: number;
+}
+
+export interface AxisTickOptions {
+	/** Requested tick count. Continuous scales only; ignored by categories. */
+	readonly count?: number;
+	/** Minimum pixels between two rendered labels. Extra ticks are dropped. */
+	readonly minTickGap?: number;
+	/** Length of the axis in pixels, used to apply `minTickGap`. */
+	readonly available?: number;
+}
+
+const DEFAULT_TICK_COUNT = 5;
+
+/**
+ * Keeps every `stride`-th tick. The first tick is always kept, and dropping is
+ * uniform, so labels stay evenly spaced instead of bunching at one end.
+ */
+function thin(ticks: ReadonlyArray<AxisTick>, stride: number): AxisTick[] {
+	return ticks.filter((_tick, index) => index % stride === 0);
+}
+
+export function axisTicks(
+	scale: ChartScale,
+	options: AxisTickOptions = {},
+): ReadonlyArray<AxisTick> {
+	const { count = DEFAULT_TICK_COUNT, minTickGap = 0, available = 0 } = options;
+
+	const ticks: AxisTick[] = isLinearScale(scale)
+		? scale.ticks(count).map((value) => ({ value, offset: scale.scale(value) }))
+		: scale.domain.map((value) => ({ value, offset: scale.center(value) }));
+
+	if (minTickGap <= 0 || available <= 0 || ticks.length < 2) {
+		return ticks;
+	}
+	const stride = Math.max(
+		1,
+		Math.ceil((ticks.length * minTickGap) / available),
+	);
+	return stride === 1 ? ticks : thin(ticks, stride);
+}

package/src/core/bars.ts

@@ -0,0 +1,160 @@
+import { readNumber } from "#/core/chart-model.ts";
+import type {
+	ChartDatum,
+	ChartDiscreteScale,
+	ChartLinearScale,
+	ChartOrientation,
+} from "#/core/types.ts";
+
+/**
+ * Bar geometry, worked out away from React so it can be asserted on directly.
+ * Covers the four combinations that matter: grouped or stacked, upright or on
+ * its side, with values that may go either side of the baseline.
+ */
+
+export interface BarRect {
+	readonly key: string;
+	/** Index of the datum, i.e. of the category slot. */
+	readonly index: number;
+	readonly value: number;
+	readonly x: number;
+	readonly y: number;
+	readonly width: number;
+	readonly height: number;
+	readonly radius: readonly [number, number, number, number];
+}
+
+export interface BarLayoutOptions {
+	readonly data: ReadonlyArray<ChartDatum>;
+	readonly keys: ReadonlyArray<string>;
+	readonly categories: ReadonlyArray<string>;
+	readonly categoryScale: ChartDiscreteScale;
+	readonly valueScale: ChartLinearScale;
+	readonly orientation: ChartOrientation;
+	readonly stacked?: boolean;
+	readonly radius?: number;
+	/** Pixels left between two bars of the same group. */
+	readonly gap?: number;
+}
+
+const DEFAULT_GAP = 2;
+
+/**
+ * Corner radii for the end of a bar that points away from the baseline. The
+ * other end stays square so it meets the axis, or the next stack segment,
+ * cleanly.
+ */
+function endRadius(
+	radius: number,
+	orientation: ChartOrientation,
+	isPositive: boolean,
+): readonly [number, number, number, number] {
+	if (orientation === "vertical") {
+		return isPositive ? [radius, radius, 0, 0] : [0, 0, radius, radius];
+	}
+	return isPositive ? [0, radius, radius, 0] : [radius, 0, 0, radius];
+}
+
+/** The last key on each side of the baseline — the only segments that round. */
+function outerKeys(
+	datum: ChartDatum,
+	keys: ReadonlyArray<string>,
+): { readonly positive: string | null; readonly negative: string | null } {
+	let positive: string | null = null;
+	let negative: string | null = null;
+	for (const key of keys) {
+		const value = readNumber(datum, key);
+		if (value > 0) {
+			positive = key;
+		} else if (value < 0) {
+			negative = key;
+		}
+	}
+	return { positive, negative };
+}
+
+function rectFor(
+	options: BarLayoutOptions,
+	placement: {
+		readonly key: string;
+		readonly index: number;
+		readonly value: number;
+		readonly slotStart: number;
+		readonly slotSize: number;
+		readonly from: number;
+		readonly to: number;
+		readonly radius: readonly [number, number, number, number];
+	},
+): BarRect {
+	const { key, index, value, slotStart, slotSize, from, to, radius } =
+		placement;
+	const low = Math.min(from, to);
+	const span = Math.abs(from - to);
+	const common = { key, index, value, radius };
+	return options.orientation === "vertical"
+		? { ...common, x: slotStart, y: low, width: slotSize, height: span }
+		: { ...common, x: low, y: slotStart, width: span, height: slotSize };
+}
+
+export function barRects(options: BarLayoutOptions): ReadonlyArray<BarRect> {
+	const {
+		data,
+		keys,
+		categories,
+		categoryScale,
+		valueScale,
+		orientation,
+		stacked = false,
+		radius = 0,
+		gap = DEFAULT_GAP,
+	} = options;
+
+	const slotWidth = categoryScale.bandwidth;
+	const lanes = stacked ? 1 : Math.max(1, keys.length);
+	const lane = slotWidth / lanes;
+	const barSize = stacked ? slotWidth : Math.max(0, lane - gap);
+	const baseline = valueScale.scale(0);
+
+	return data.flatMap((datum, index) => {
+		const slotOrigin = categoryScale.scale(categories[index] ?? String(index));
+		const outer = outerKeys(datum, keys);
+		let positiveTop = 0;
+		let negativeTop = 0;
+
+		return keys.map((key, laneIndex) => {
+			const value = readNumber(datum, key);
+			const isPositive = value >= 0;
+
+			let from = baseline;
+			let to = valueScale.scale(value);
+			if (stacked) {
+				const base = isPositive ? positiveTop : negativeTop;
+				const top = base + value;
+				from = valueScale.scale(base);
+				to = valueScale.scale(top);
+				if (isPositive) {
+					positiveTop = top;
+				} else {
+					negativeTop = top;
+				}
+			}
+
+			const rounds =
+				!stacked || key === (isPositive ? outer.positive : outer.negative);
+
+			return rectFor(options, {
+				key,
+				index,
+				value,
+				slotStart:
+					slotOrigin + (stacked ? 0 : laneIndex * lane + (lane - barSize) / 2),
+				slotSize: barSize,
+				from,
+				to,
+				radius: rounds
+					? endRadius(radius, orientation, isPositive)
+					: [0, 0, 0, 0],
+			});
+		});
+	});
+}

package/src/core/chart-model.ts

@@ -0,0 +1,156 @@
+import { bandScale, linearScale, pointScale } from "#/core/scales.ts";
+import { extentFromZero, niceDomain } from "#/core/ticks.ts";
+import type {
+	ChartDatum,
+	ChartDiscreteScale,
+	ChartLinearScale,
+	ChartOrientation,
+	ChartScale,
+} from "#/core/types.ts";
+
+/**
+ * Turns raw rows plus a pair of axis declarations into the two scales every
+ * cartesian mark reads. Pure and synchronous: the components only ever call it
+ * inside a `useMemo`, and the tests call it directly.
+ */
+
+export interface ChartCategorySpec {
+	/** Field on each datum holding the category label. */
+	readonly key: string;
+	/** `band` leaves room for bars; `point` pins lines to the plot edges. */
+	readonly type?: "band" | "point";
+	readonly paddingInner?: number;
+	readonly paddingOuter?: number;
+}
+
+export interface ChartValueSpec {
+	/** Fields plotted against the value axis, in draw order. */
+	readonly keys: ReadonlyArray<string>;
+	/** Overrides the computed domain — use it to pin an axis to `[0, 100]`. */
+	readonly domain?: readonly [number, number];
+	/** Sum the keys per datum instead of taking their maximum. */
+	readonly stacked?: boolean;
+	/** Round the domain out to whole ticks. On by default. */
+	readonly nice?: boolean;
+}
+
+export interface ChartModelOptions {
+	readonly data: ReadonlyArray<ChartDatum>;
+	readonly category?: ChartCategorySpec;
+	readonly value?: ChartValueSpec;
+	readonly orientation: ChartOrientation;
+	readonly innerWidth: number;
+	readonly innerHeight: number;
+}
+
+export interface ChartModel {
+	readonly categories: ReadonlyArray<string>;
+	readonly valueKeys: ReadonlyArray<string>;
+	readonly categoryScale: ChartDiscreteScale;
+	readonly valueScale: ChartLinearScale;
+	readonly xScale: ChartScale;
+	readonly yScale: ChartScale;
+}
+
+/** Reads a numeric field, treating anything unparseable as zero. */
+export function readNumber(datum: ChartDatum, key: string): number {
+	const value = datum[key];
+	if (typeof value === "number" && Number.isFinite(value)) {
+		return value;
+	}
+	if (typeof value === "string") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : 0;
+	}
+	return 0;
+}
+
+function categoryLabels(
+	data: ReadonlyArray<ChartDatum>,
+	spec: ChartCategorySpec | undefined,
+): ReadonlyArray<string> {
+	return data.map((datum, index) => {
+		const raw = spec === undefined ? undefined : datum[spec.key];
+		return raw === undefined || raw === null ? String(index) : String(raw);
+	});
+}
+
+/**
+ * The extent the value axis has to cover. Stacked series are summed per datum
+ * (positives and negatives apart, so a stack that crosses zero still fits);
+ * grouped series are compared one by one.
+ */
+function valueExtent(
+	data: ReadonlyArray<ChartDatum>,
+	spec: ChartValueSpec,
+): readonly [number, number] {
+	if (!spec.stacked) {
+		return extentFromZero(
+			data.flatMap((datum) => spec.keys.map((key) => readNumber(datum, key))),
+		);
+	}
+	const totals = data.flatMap((datum) => {
+		let positive = 0;
+		let negative = 0;
+		for (const key of spec.keys) {
+			const value = readNumber(datum, key);
+			if (value >= 0) {
+				positive += value;
+			} else {
+				negative += value;
+			}
+		}
+		return [positive, negative];
+	});
+	return extentFromZero(totals);
+}
+
+function buildCategoryScale(
+	categories: ReadonlyArray<string>,
+	spec: ChartCategorySpec | undefined,
+	range: readonly [number, number],
+): ChartDiscreteScale {
+	if (spec?.type === "point") {
+		return pointScale({ domain: categories, range });
+	}
+	return bandScale({
+		domain: categories,
+		range,
+		paddingInner: spec?.paddingInner,
+		paddingOuter: spec?.paddingOuter,
+	});
+}
+
+export function buildChartModel(options: ChartModelOptions): ChartModel {
+	const { data, category, value, orientation, innerWidth, innerHeight } =
+		options;
+	const isVertical = orientation === "vertical";
+	const categories = categoryLabels(data, category);
+	const valueSpec: ChartValueSpec = value ?? { keys: [] };
+
+	const rawExtent = valueSpec.domain ?? valueExtent(data, valueSpec);
+	const domain =
+		valueSpec.domain !== undefined || valueSpec.nice === false
+			? rawExtent
+			: niceDomain(rawExtent[0], rawExtent[1]);
+
+	const categoryScale = buildCategoryScale(
+		categories,
+		category,
+		isVertical ? [0, innerWidth] : [0, innerHeight],
+	);
+	const valueScale = linearScale({
+		domain,
+		// A value axis grows upwards, so its pixel range runs backwards.
+		range: isVertical ? [innerHeight, 0] : [0, innerWidth],
+	});
+
+	return {
+		categories,
+		valueKeys: valueSpec.keys,
+		categoryScale,
+		valueScale,
+		xScale: isVertical ? categoryScale : valueScale,
+		yScale: isVertical ? valueScale : categoryScale,
+	};
+}

package/src/core/config.ts

@@ -0,0 +1,68 @@
+import type * as React from "react";
+
+/**
+ * The per-series presentation map every chart is given, plus the two lookups
+ * every mark needs from it: what colour to paint a key, and what to call it.
+ */
+
+/** Light and dark values for one series colour. */
+export type ChartTheme = Record<"light" | "dark", string>;
+
+export type ChartConfigItem = {
+	label?: React.ReactNode;
+	icon?: React.ComponentType;
+} & ({ color?: string; theme?: never } | { color?: never; theme: ChartTheme });
+
+export type ChartConfig = Record<string, ChartConfigItem>;
+
+/** How many `--chart-N` tokens the design system defines. */
+export const CHART_PALETTE_SIZE = 5;
+
+/**
+ * The colour a series is drawn in. A configured series uses the `--color-<key>`
+ * variable the root injects (so light and dark both work without a re-render);
+ * anything else falls back to the shared palette, cycling by draw order rather
+ * than picking one arbitrary colour for every unnamed series.
+ */
+export function seriesColor(
+	config: ChartConfig,
+	key: string,
+	index = 0,
+): string {
+	const item = config[key];
+	if (
+		item !== undefined &&
+		(item.color !== undefined || item.theme !== undefined)
+	) {
+		return `var(--color-${key})`;
+	}
+	return `var(--chart-${(index % CHART_PALETTE_SIZE) + 1})`;
+}
+
+/** The human name of a series, falling back to its raw key. */
+export function seriesLabel(config: ChartConfig, key: string): React.ReactNode {
+	return config[key]?.label ?? key;
+}
+
+/**
+ * Which config entry describes a row. Charts coloured per row (a pie, a status
+ * breakdown) name their entries after a field on the datum — `nameKey` says
+ * which one — while ordinary series charts are keyed by the series itself.
+ */
+export function configKeyFor(
+	datum: Record<string, unknown> | undefined,
+	fallbackKey: string,
+	nameKey?: string,
+): string {
+	if (nameKey === undefined || datum === undefined) {
+		return fallbackKey;
+	}
+	const named = datum[nameKey];
+	return named === undefined || named === null ? fallbackKey : String(named);
+}
+
+/** The same, flattened to a string for `aria-label` and the data table. */
+export function seriesLabelText(config: ChartConfig, key: string): string {
+	const label = config[key]?.label;
+	return typeof label === "string" ? label : key;
+}

package/src/core/format.ts

@@ -0,0 +1,86 @@
+/**
+ * Number formatting for axes, labels and tooltips. The whole app writes its
+ * numbers in French, so that is the default here too — pass an explicit locale
+ * when a chart lives on a page that does not.
+ */
+
+const DEFAULT_LOCALE = "fr-FR";
+/** Above this magnitude an axis tick reads better as "12 k" than as "12 000". */
+const COMPACT_THRESHOLD = 10_000;
+
+const formatterCache = new Map<string, Intl.NumberFormat>();
+
+function formatterFor(
+	locale: string,
+	options: Intl.NumberFormatOptions,
+): Intl.NumberFormat {
+	const cacheKey = `${locale}:${JSON.stringify(options)}`;
+	const cached = formatterCache.get(cacheKey);
+	if (cached !== undefined) {
+		return cached;
+	}
+	const created = new Intl.NumberFormat(locale, options);
+	formatterCache.set(cacheKey, created);
+	return created;
+}
+
+export interface FormatNumberOptions {
+	readonly locale?: string;
+	readonly maximumFractionDigits?: number;
+	readonly minimumFractionDigits?: number;
+}
+
+export function formatNumber(
+	value: number,
+	options: FormatNumberOptions = {},
+): string {
+	const { locale = DEFAULT_LOCALE, ...digits } = options;
+	return formatterFor(locale, digits).format(value);
+}
+
+/** "12 k", "3,4 M" — for axis ticks, where width is the scarce resource. */
+export function formatCompactNumber(
+	value: number,
+	locale: string = DEFAULT_LOCALE,
+): string {
+	return formatterFor(locale, {
+		notation: "compact",
+		maximumFractionDigits: 1,
+	}).format(value);
+}
+
+export function formatPercentage(
+	fraction: number,
+	locale: string = DEFAULT_LOCALE,
+): string {
+	return formatterFor(locale, {
+		style: "percent",
+		maximumFractionDigits: 1,
+	}).format(fraction);
+}
+
+/**
+ * What a value axis uses when the caller has no opinion: plain digits until the
+ * numbers get long, compact notation after that, and at most one decimal so a
+ * tick step of 0.5 still reads correctly.
+ */
+export function formatTickValue(
+	value: number,
+	locale: string = DEFAULT_LOCALE,
+): string {
+	if (Math.abs(value) >= COMPACT_THRESHOLD) {
+		return formatCompactNumber(value, locale);
+	}
+	return formatNumber(value, { locale, maximumFractionDigits: 2 });
+}
+
+/** Renders an unknown datum field as a label without throwing on `null`. */
+export function formatLabel(value: unknown): string {
+	if (value === null || value === undefined) {
+		return "";
+	}
+	if (typeof value === "number") {
+		return formatTickValue(value);
+	}
+	return String(value);
+}