@voila.dev/ui-chart 1.1.9

package/src/core/ticks.ts

@@ -0,0 +1,118 @@
+/**
+ * Round tick values for a continuous axis. The step is always 1, 2, 5 or 10
+ * times a power of ten, which is what makes an axis readable: 0/25/50/75/100
+ * rather than 0/23.4/46.8.
+ */
+
+/** Steps the eye reads as round, in units of the current power of ten. */
+const NICE_FACTORS = [
+	{ threshold: Math.SQRT2, factor: 1 },
+	{ threshold: Math.sqrt(10), factor: 2 },
+	{ threshold: Math.sqrt(50), factor: 5 },
+] as const;
+
+const DEFAULT_TICK_COUNT = 5;
+/** Beyond this many decimals the rounding helper stops fighting IEEE noise. */
+const MAX_TICK_PRECISION = 12;
+
+/**
+ * Drops the floating-point dust `i * step` leaves behind (0.30000000000000004)
+ * by rounding to the number of decimals the step itself carries.
+ */
+function roundToStep(value: number, step: number): number {
+	if (step === 0 || !Number.isFinite(step)) {
+		return value;
+	}
+	const decimals = Math.max(0, -Math.floor(Math.log10(Math.abs(step))));
+	return Number(value.toFixed(Math.min(decimals, MAX_TICK_PRECISION)));
+}
+
+/**
+ * The round step closest to covering `[min, max]` in about `count` intervals.
+ * Returns `0` for a degenerate span, which callers read as "no ticks".
+ */
+export function tickStep(
+	min: number,
+	max: number,
+	count: number = DEFAULT_TICK_COUNT,
+): number {
+	const span = max - min;
+	if (!Number.isFinite(span) || span <= 0 || count <= 0) {
+		return 0;
+	}
+	const rough = span / count;
+	const power = Math.floor(Math.log10(rough));
+	const error = rough / 10 ** power;
+	const match = NICE_FACTORS.find((candidate) => error < candidate.threshold);
+	return (match?.factor ?? 10) * 10 ** power;
+}
+
+/**
+ * Round values strictly inside `[min, max]`. An axis that has been through
+ * `niceDomain` first gets ticks on both bounds; a raw domain does not, on
+ * purpose — a tick outside the data would be a lie.
+ */
+export function niceTicks(
+	min: number,
+	max: number,
+	count: number = DEFAULT_TICK_COUNT,
+): ReadonlyArray<number> {
+	if (min === max) {
+		return [min];
+	}
+	const step = tickStep(min, max, count);
+	if (step === 0) {
+		return [];
+	}
+	const first = Math.ceil(min / step);
+	const last = Math.floor(max / step);
+	const ticks: number[] = [];
+	for (let index = first; index <= last; index += 1) {
+		ticks.push(roundToStep(index * step, step));
+	}
+	return ticks;
+}
+
+/**
+ * Widens `[min, max]` outwards to the nearest round step, so the axis starts
+ * and ends on a tick instead of mid-air.
+ */
+export function niceDomain(
+	min: number,
+	max: number,
+	count: number = DEFAULT_TICK_COUNT,
+): readonly [number, number] {
+	if (!Number.isFinite(min) || !Number.isFinite(max)) {
+		return [0, 1];
+	}
+	if (min === max) {
+		return min === 0 ? [0, 1] : [Math.min(0, min), Math.max(0, max)];
+	}
+	const step = tickStep(min, max, count);
+	if (step === 0) {
+		return [min, max];
+	}
+	return [
+		roundToStep(Math.floor(min / step) * step, step),
+		roundToStep(Math.ceil(max / step) * step, step),
+	];
+}
+
+/**
+ * The `[min, max]` of a set of values, always including zero so bars are
+ * measured from a real baseline rather than from an arbitrary floor.
+ */
+export function extentFromZero(
+	values: ReadonlyArray<number>,
+): readonly [number, number] {
+	let min = 0;
+	let max = 0;
+	for (const value of values) {
+		if (!Number.isFinite(value)) {
+			continue;
+		}
+		min = Math.min(min, value);
+		max = Math.max(max, value);
+	}
+	return [min, max];
+}

package/src/core/types.ts

@@ -0,0 +1,71 @@
+/**
+ * The vocabulary every other core module and component speaks. Deliberately
+ * plain: no class instances, no branded types, nothing that would make a scale
+ * awkward to build in a test or to serialize in a snapshot.
+ */
+
+/** A row of chart data. Marks read named fields off it by key. */
+export type ChartDatum = Record<string, unknown>;
+
+/** A `[start, end]` pair. Not sorted: a range may run backwards (y axes do). */
+export type ChartInterval = readonly [number, number];
+
+/** Inner padding between the SVG edge and the plotting area. */
+export interface ChartMargin {
+	readonly top: number;
+	readonly right: number;
+	readonly bottom: number;
+	readonly left: number;
+}
+
+/**
+ * A continuous scale: numbers in, pixels out, and back again. `ticks` returns
+ * round values inside the domain, never the raw domain bounds.
+ */
+export interface ChartLinearScale {
+	readonly kind: "linear";
+	readonly domain: ChartInterval;
+	readonly range: ChartInterval;
+	readonly scale: (value: number) => number;
+	readonly invert: (pixel: number) => number;
+	readonly ticks: (count?: number) => ReadonlyArray<number>;
+	/** Continuous scales have no band, but marks ask uniformly. */
+	readonly bandwidth: number;
+}
+
+/**
+ * A discrete scale: one category in, the pixel offset of its slot out.
+ * `bandwidth` is the slot width for band scales and `0` for point scales.
+ */
+export interface ChartDiscreteScale {
+	readonly kind: "band" | "point";
+	readonly domain: ReadonlyArray<string>;
+	readonly range: ChartInterval;
+	readonly scale: (value: string) => number;
+	/** Centre of a category's slot — where a point or tick belongs. */
+	readonly center: (value: string) => number;
+	/** Nearest category index for a pixel offset. Used by pointer scrubbing. */
+	readonly invert: (pixel: number) => number;
+	readonly ticks: () => ReadonlyArray<string>;
+	readonly bandwidth: number;
+	readonly step: number;
+}
+
+export type ChartScale = ChartLinearScale | ChartDiscreteScale;
+
+/** Whether the category axis runs along the bottom (vertical bars) or the side. */
+export type ChartOrientation = "vertical" | "horizontal";
+
+/** How a line or area joins its points. */
+export type ChartCurve = "linear" | "monotone" | "step";
+
+/** A point in plotting-area pixels. */
+export interface ChartPoint {
+	readonly x: number;
+	readonly y: number;
+}
+
+/** Per-corner radii for a rounded bar, clockwise from the top-left. */
+export type ChartCornerRadius =
+	| number
+	| readonly [number, number, number, number];

package/src/hooks/use-chart-dimensions.ts

@@ -0,0 +1,50 @@
+import * as React from "react";
+
+/**
+ * Measures the element the returned `ref` is attached to. Charts are drawn in
+ * pixels, so every scale needs a real width and height before it can place
+ * anything.
+ *
+ * Server-safe: nothing is read from the document during render, and the first
+ * paint uses `initial` so a chart rendered on the server still has sensible
+ * geometry. The real size arrives on the first observer callback.
+ */
+
+const DEFAULT_DIMENSION = { width: 320, height: 200 } as const;
+
+export interface ChartDimension {
+	readonly width: number;
+	readonly height: number;
+}
+
+export interface ChartDimensionsResult extends ChartDimension {
+	readonly ref: (node: HTMLDivElement | null) => void;
+}
+
+export function useChartDimensions(
+	initial: ChartDimension = DEFAULT_DIMENSION,
+): ChartDimensionsResult {
+	const [node, setNode] = React.useState<HTMLDivElement | null>(null);
+	const [dimension, setDimension] = React.useState<ChartDimension>(initial);
+
+	React.useEffect(() => {
+		if (node === null || typeof ResizeObserver === "undefined") {
+			return;
+		}
+		const observer = new ResizeObserver((entries) => {
+			const box = entries[0]?.contentRect;
+			if (box === undefined || box.width === 0 || box.height === 0) {
+				return;
+			}
+			setDimension((current) =>
+				current.width === box.width && current.height === box.height
+					? current
+					: { width: box.width, height: box.height },
+			);
+		});
+		observer.observe(node);
+		return () => observer.disconnect();
+	}, [node]);
+
+	return { ref: setNode, width: dimension.width, height: dimension.height };
+}

package/src/hooks/use-chart-pointer.ts

@@ -0,0 +1,152 @@
+import * as React from "react";
+
+import type {
+	ChartDiscreteScale,
+	ChartMargin,
+	ChartOrientation,
+} from "#/core/types.ts";
+
+/**
+ * Turns pointer, touch and keyboard input over the plotting area into a single
+ * "which datum is the reader looking at" index. One state, three input methods:
+ * scrubbing with a finger, hovering with a mouse and arrowing with a keyboard
+ * all land on the same active datum, so the tooltip and cursor never have to
+ * care which one it was.
+ */
+
+/** Where the reader is, in plotting-area pixels. */
+export interface ChartActive {
+	readonly index: number;
+	readonly x: number;
+	readonly y: number;
+}
+
+export interface ChartPointerOptions {
+	readonly enabled: boolean;
+	readonly count: number;
+	readonly width: number;
+	readonly height: number;
+	readonly margin: ChartMargin;
+	readonly orientation: ChartOrientation;
+	readonly categoryScale: ChartDiscreteScale;
+}
+
+export interface ChartPointerHandlers {
+	readonly onPointerMove: React.PointerEventHandler<SVGSVGElement>;
+	readonly onPointerDown: React.PointerEventHandler<SVGSVGElement>;
+	readonly onPointerLeave: React.PointerEventHandler<SVGSVGElement>;
+	readonly onKeyDown: React.KeyboardEventHandler<SVGSVGElement>;
+	readonly onBlur: React.FocusEventHandler<SVGSVGElement>;
+	readonly tabIndex: number | undefined;
+}
+
+export interface ChartPointerResult {
+	readonly active: ChartActive | null;
+	readonly setActive: React.Dispatch<React.SetStateAction<ChartActive | null>>;
+	readonly handlers: ChartPointerHandlers;
+}
+
+/** Keyboard steps, keyed by the axis the categories run along. */
+const KEY_STEPS: Record<ChartOrientation, Record<string, number>> = {
+	vertical: { ArrowRight: 1, ArrowLeft: -1, ArrowUp: 1, ArrowDown: -1 },
+	horizontal: { ArrowDown: 1, ArrowUp: -1, ArrowRight: 1, ArrowLeft: -1 },
+};
+
+/**
+ * Converts a pointer event into plotting-area coordinates, correcting for any
+ * scaling between the SVG's user units and its rendered box.
+ */
+function plotPoint(
+	event: React.PointerEvent<SVGSVGElement>,
+	options: ChartPointerOptions,
+): { readonly x: number; readonly y: number } {
+	const box = event.currentTarget.getBoundingClientRect();
+	const scaleX = box.width === 0 ? 1 : options.width / box.width;
+	const scaleY = box.height === 0 ? 1 : options.height / box.height;
+	return {
+		x: (event.clientX - box.left) * scaleX - options.margin.left,
+		y: (event.clientY - box.top) * scaleY - options.margin.top,
+	};
+}
+
+function activeFromPoint(
+	point: { readonly x: number; readonly y: number },
+	options: ChartPointerOptions,
+): ChartActive {
+	const along = options.orientation === "vertical" ? point.x : point.y;
+	return { index: options.categoryScale.invert(along), ...point };
+}
+
+/** Places the active marker on a datum's own slot, for keyboard navigation. */
+function activeFromIndex(
+	index: number,
+	options: ChartPointerOptions,
+): ChartActive {
+	const category = options.categoryScale.domain[index] ?? "";
+	const center = options.categoryScale.center(category);
+	return options.orientation === "vertical"
+		? { index, x: center, y: 0 }
+		: { index, x: 0, y: center };
+}
+
+export function useChartPointer(
+	options: ChartPointerOptions,
+): ChartPointerResult {
+	const [active, setActive] = React.useState<ChartActive | null>(null);
+	const { enabled, count, orientation } = options;
+
+	// Built fresh every render rather than memoized: the handlers close over
+	// scales that are themselves rebuilt whenever the geometry changes, and they
+	// only ever land on a DOM element, where a stable identity buys nothing.
+	const track = (event: React.PointerEvent<SVGSVGElement>) => {
+		if (!enabled || count === 0) {
+			return;
+		}
+		setActive(activeFromPoint(plotPoint(event, options), options));
+	};
+
+	const stepFrom = (delta: number): number => {
+		const from = active?.index ?? null;
+		if (from === null) {
+			return delta > 0 ? 0 : count - 1;
+		}
+		return Math.min(Math.max(from + delta, 0), count - 1);
+	};
+
+	const targetIndexFor = (key: string): number | null => {
+		if (key === "Home") {
+			return 0;
+		}
+		if (key === "End") {
+			return count - 1;
+		}
+		const delta = KEY_STEPS[orientation][key];
+		return delta === undefined ? null : stepFrom(delta);
+	};
+
+	const handlers: ChartPointerHandlers = {
+		tabIndex: enabled && count > 0 ? 0 : undefined,
+		onPointerMove: track,
+		// Touch fires no hover: the first contact has to select outright.
+		onPointerDown: track,
+		onPointerLeave: () => setActive(null),
+		onBlur: () => setActive(null),
+		onKeyDown: (event) => {
+			if (!enabled || count === 0) {
+				return;
+			}
+			if (event.key === "Escape") {
+				setActive(null);
+				return;
+			}
+			const target = targetIndexFor(event.key);
+			if (target === null) {
+				return;
+			}
+			event.preventDefault();
+			setActive(activeFromIndex(target, options));
+		},
+	};
+
+	return { active, setActive, handlers };
+}

package/src/styles.css

@@ -0,0 +1,10 @@
+/*
+ * Tailwind must scan this package or none of its classes are generated — the
+ * components ship as .tsx source, not as compiled CSS.
+ *
+ * `@source` resolves relative to the file that declares it, so this works
+ * wherever the package ends up: node_modules in an app, a symlink in a
+ * workspace. Consumers import this file and add nothing of their own.
+ */
+@source "./";
+@source not "./**/*.test.*";