@seekalfred/primitives 0.7.3 → 0.7.4

package/dist/line-chart/line-chart.js

@@ -4,11 +4,13 @@ import { mergeRefs } from "../lib/merge-refs.js";
 import { prefersReducedMotion, useIsomorphicLayoutEffect } from "../lib/motion.js";
 import { SMOOTH, SNAPPY, tween } from "../lib/spring-tween.js";
 import { forwardRef, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/line-chart/line-chart.tsx
 /** Room above the top gridline, and the gap between the crosshair and its tooltip. */
 const TOP = 12;
 const GAP = 14;
+/** Between a point and its label. */
+const LABEL_GAP = 6;
 /** The first draw: 480ms x 1.75, slow at both ends. */
 const LINE_CHART_DRAW_MS = 840;
 const PALETTE = [
@@ -25,9 +27,9 @@ const GRID = Array.from({ length: 241 }, (_, index) => index / 240);
 const clamp = (value, low, high) => Math.min(high, Math.max(low, value));
 const colorOf = (line, index) => line.color ?? PALETTE[Math.min(index, PALETTE.length - 1)];
 const clean = (value) => Number(value.toPrecision(12));
-/** Clean gridlines: the smallest step of 1, 2, 2.5 or 5 that covers the data in four rows or fewer, from zero unless the data dips below it. */
-function niceScale(low, high) {
-	const lo = Math.min(0, low);
+/** Clean gridlines: the smallest step of 1, 2, 2.5 or 5 that covers the data in four rows or fewer, from zero unless the data dips below it (or `fromZero` is off). */
+function niceScale(low, high, fromZero = true) {
+	const lo = fromZero ? Math.min(0, low) : low;
 	const hi = Math.max(high, lo + 1);
 	const magnitude = 10 ** Math.floor(Math.log10((hi - lo) / 4));
 	for (const factor of [
@@ -56,6 +58,23 @@ function niceScale(low, high) {
 		ticks: [lo, hi]
 	};
 }
+/** The nice scale with either end pinned: a pinned end is a tick, and the nice ticks within half a step of it give way. */
+function pinScale(scale, min, max) {
+	if (min === void 0 && max === void 0) return scale;
+	const lo = min ?? scale.min;
+	const hi = max ?? scale.max;
+	if (!(hi > lo)) return scale;
+	const step = scale.ticks.length > 1 ? scale.ticks[1] - scale.ticks[0] : hi - lo;
+	return {
+		min: lo,
+		max: hi,
+		ticks: [
+			lo,
+			...scale.ticks.filter((tick) => tick > lo + step / 2 && tick < hi - step / 2),
+			hi
+		]
+	};
+}
 /** The line through every value, sampled densely on x from 0 to 1 in data units. Monotone tangents keep a smooth curve from swinging past the data. */
 function curveFor(values, smooth) {
 	if (values.length === 0) return [];
@@ -101,18 +120,22 @@ function fillGaps(values) {
 		return values[before] + (values[after] - values[before]) * (index - before) / (after - before);
 	});
 }
-/** Where a line with missing values is not drawn: before its first value, after its last, and between two values with missing ones between them. */
-function breaksFor(values) {
+/** Where a line with missing values is not drawn: before its first value, after its last, and (unless it connects across them) between two values with missing ones between them. */
+function breaksFor(values, across = false) {
 	const present = values.flatMap((value, index) => value === null ? [] : [index]);
 	if (!present.length) return values.length ? [[-Infinity, Infinity]] : [];
 	const last = values.length - 1;
 	if (last === 0) return [];
 	const breaks = [];
 	if (present[0] > 0) breaks.push([-Infinity, present[0] / last]);
-	for (let at = 1; at < present.length; at++) if (present[at] - present[at - 1] > 1) breaks.push([present[at - 1] / last, present[at] / last]);
+	for (let at = 1; at < present.length; at++) if (!across && present[at] - present[at - 1] > 1) breaks.push([present[at - 1] / last, present[at] / last]);
 	if (present[present.length - 1] < last) breaks.push([present[present.length - 1] / last, Infinity]);
 	return breaks;
 }
+function holesFor(values) {
+	const last = values.length - 1;
+	return values.flatMap((value, index) => value === null && last > 0 ? [index / last] : []);
+}
 const EDGE = 1e-9;
 /** Radius of a lone point's dot, inside its 2px stroke. */
 const DOT = 1.5;
@@ -167,7 +190,7 @@ function axisPicks(data, width) {
 	const stride = Math.ceil(labeled.length / room);
 	return labeled.reverse().filter((_, rank) => rank % stride === 0).reverse();
 }
-const LineChart = forwardRef(function LineChart({ data, series, label, unit = "", height = 220, formatValue, formatTick = (value) => COMPACT.format(value), hiddenSeries, defaultHiddenSeries, onHiddenSeriesChange, onActiveChange, loading = false, emptyLabel = "No data for this range", legend, categoryLabel = "Date", curve = "smooth", missing = "zero", missingLabel = "No data", references, className }, ref) {
+const LineChart = forwardRef(function LineChart({ data, series, label, unit = "", height = 220, formatValue, formatTick = (value) => COMPACT.format(value), hiddenSeries, defaultHiddenSeries, onHiddenSeriesChange, onActiveChange, loading = false, emptyLabel = "No data for this range", legend, categoryLabel = "Date", curve = "smooth", missing = "zero", missingLabel = "No data", references, markers, reversed = false, valueDomain, bands, renderTooltip, className }, ref) {
 	const figure = useRef(null);
 	const refs = useMemo(() => mergeRefs(ref, figure), [ref]);
 	const plot = useRef(null);
@@ -186,7 +209,7 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 	};
 	const visible = series.filter((line) => !hidden.includes(line.key));
 	const showLegend = legend ?? series.length > 1;
-	const gaps = missing === "gap";
+	const gaps = missing !== "zero";
 	const read = (item, key) => {
 		const value = item.values[key];
 		if (!gaps) return value ?? 0;
@@ -197,7 +220,8 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 		const values = data.map((item) => read(item, line.key));
 		return [line.key, {
 			shape: curveFor(fillGaps(values), curve === "smooth"),
-			breaks: breaksFor(values)
+			breaks: breaksFor(values, missing === "connect"),
+			holes: holesFor(values)
 		}];
 	})), [signature]);
 	let low = Infinity;
@@ -213,9 +237,12 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 		low = Math.min(low, reference.value);
 		high = Math.max(high, reference.value);
 	}
-	const range = Number.isFinite(low) ? niceScale(low, high) : null;
-	const [steady, setSteady] = useState(() => range ?? niceScale(0, 100));
-	if (range && (range.min !== steady.min || range.max !== steady.max)) setSteady(range);
+	const pinMin = Number.isFinite(valueDomain?.min) ? valueDomain.min : void 0;
+	const pinMax = Number.isFinite(valueDomain?.max) ? valueDomain.max : void 0;
+	const fit = (from, to) => pinScale(niceScale(pinMin ?? from, pinMax ?? to, pinMin === void 0), pinMin, pinMax);
+	const range = Number.isFinite(low) ? fit(low, high) : pinMin !== void 0 && pinMax !== void 0 ? fit(pinMin, pinMax) : null;
+	const [steady, setSteady] = useState(() => range ?? fit(0, 100));
+	if (range && (range.min !== steady.min || range.max !== steady.max || range.ticks.join() !== steady.ticks.join())) setSteady(range);
 	const [active, setActive] = useState(null);
 	const [seen, setSeen] = useState(signature);
 	if (seen !== signature) {
@@ -239,6 +266,9 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 		return at < 0 ? void 0 : last > 0 ? at / last : .5;
 	};
 	const drawnReferences = (references ?? []).filter((reference) => referenceAt(reference) !== void 0);
+	const markerIndex = (marker) => data.findIndex((item) => item.key === marker.at);
+	const drawnMarkers = (markers ?? []).filter((marker) => markerIndex(marker) >= 0);
+	const drawnBands = (bands ?? []).filter((band) => Number.isFinite(band.from) && Number.isFinite(band.to));
 	const live = useRef({
 		series,
 		hidden
@@ -256,14 +286,15 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 		if (!w || !root) return;
 		const lo = scale.current.min;
 		const span = scale.current.max - lo || 1;
-		const toY = (value) => TOP + (1 - (value - lo) / span) * (height - TOP);
+		const toY = (value) => TOP + (reversed ? (value - lo) / span : 1 - (value - lo) / span) * (height - TOP);
+		const base = reversed ? scale.current.max : lo;
 		const at = cursor.current;
 		const dotYs = [];
 		for (const line of live.current.series) {
 			const track = tracks.current.get(line.key);
 			if (!track) continue;
 			const p = track.presence;
-			const y = (value) => toY(lo + (value - lo) * p);
+			const y = (value) => toY(base + (value - base) * p);
 			const group = root.querySelector(`[data-series="${CSS.escape(line.key)}"]`);
 			if (track.breaks.length) {
 				const paths = pathsFor(track.shape, track.breaks, (x) => x * w, y, height);
@@ -277,7 +308,7 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 			if (group) group.style.opacity = String(p);
 			const dot = root.querySelector(`[data-dot="${CSS.escape(line.key)}"]`);
 			if (dot && track.shape.length) {
-				const gap = inBreak(track.breaks, at);
+				const gap = inBreak(track.breaks, at) || track.holes.some((x) => Math.abs(x - at) < 1e-6);
 				const cy = y(valueAt(track.shape, at));
 				dot.setAttribute("cx", (at * w).toFixed(1));
 				dot.setAttribute("cy", cy.toFixed(1));
@@ -292,6 +323,18 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 			node.setAttribute("y2", yy);
 		}
 		for (const node of gutter.current?.querySelectorAll("[data-tick]") ?? []) node.style.translate = `0 ${Math.round(toY(Number(node.dataset.tick)))}px`;
+		for (const node of root.querySelectorAll("[data-band]")) {
+			const ys = [toY(Number(node.dataset.from)), toY(Number(node.dataset.to))];
+			const top = clamp(Math.min(...ys), TOP, height);
+			const bottom = clamp(Math.max(...ys), TOP, height);
+			node.setAttribute("y", String(Math.round(top)));
+			node.setAttribute("height", String(Math.max(0, Math.round(bottom) - Math.round(top))));
+			const text = plot.current?.querySelector(`[data-band-label="${CSS.escape(node.dataset.band)}"]`);
+			if (text) {
+				text.style.translate = `0 ${Math.round(top)}px`;
+				text.style.visibility = bottom - top >= text.offsetHeight ? "" : "hidden";
+			}
+		}
 		for (const node of root.querySelectorAll("[data-reference-value]")) {
 			const yy = String(Math.round(toY(Number(node.dataset.referenceValue))) + .5);
 			node.setAttribute("y1", yy);
@@ -306,6 +349,17 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 			const { referenceValue, referenceAt } = node.dataset;
 			node.style.translate = referenceValue !== void 0 ? `0 ${Math.round(toY(Number(referenceValue)))}px` : `${Math.round(Number(referenceAt) * w)}px 0`;
 		}
+		for (const node of plot.current?.querySelectorAll("[data-point-label]") ?? []) {
+			const track = tracks.current.get(node.dataset.pointLabel);
+			if (!track?.shape.length) continue;
+			const x = Number(node.dataset.x);
+			const cy = toY(base + (valueAt(track.shape, x) - base) * track.presence);
+			const lw = node.offsetWidth;
+			const lh = node.offsetHeight;
+			const top = cy - lh - LABEL_GAP < 0 ? cy + LABEL_GAP : cy - lh - LABEL_GAP;
+			node.style.translate = `${Math.round(clamp(x * w - lw / 2, 0, Math.max(0, w - lw)))}px ${Math.round(clamp(top, 0, Math.max(0, height - lh)))}px`;
+			node.style.opacity = String(track.presence);
+		}
 		const cx = Math.round(at * w) + .5;
 		const cross = root.querySelector("[data-part=crosshair]");
 		cross?.setAttribute("x1", String(cx));
@@ -319,7 +373,7 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 			const middle = dotYs.length ? dotYs.reduce((sum, value) => sum + value, 0) / dotYs.length : height / 2;
 			bubble.style.translate = `${clamp(x, 0, Math.max(0, w - tw))}px ${clamp(middle - th / 2, 0, Math.max(0, height - th))}px`;
 		}
-	}, [height]);
+	}, [height, reversed]);
 	useIsomorphicLayoutEffect(() => {
 		const node = plot.current;
 		if (!node) return;
@@ -337,18 +391,20 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 	useIsomorphicLayoutEffect(paint);
 	useEffect(() => {
 		const moves = [];
-		for (const [key, { shape: target, breaks }] of targets) {
+		for (const [key, { shape: target, breaks, holes }] of targets) {
 			const track = tracks.current.get(key);
 			if (!track) {
 				tracks.current.set(key, {
 					shape: target,
 					breaks,
+					holes,
 					presence: live.current.hidden.includes(key) ? 0 : 1,
 					stop: null
 				});
 				continue;
 			}
 			track.breaks = breaks;
+			track.holes = holes;
 			if (!track.shape.length || !target.length) {
 				track.shape = target;
 				continue;
@@ -479,13 +535,66 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 	const onPointerMove = (event) => {
 		if (!empty && (event.pointerType === "mouse" || event.buttons)) setActive(pointAt(event.clientX));
 	};
-	const formatNumber = (value, line) => `${formatValue ? formatValue(value, line) : GROUPED.format(value)}${unit ? ` ${unit}` : ""}`;
+	const formatShort = (value, line) => formatValue ? formatValue(value, line) : GROUPED.format(value);
+	const formatNumber = (value, line) => `${formatShort(value, line)}${unit ? ` ${unit}` : ""}`;
 	const format = (value, line) => value === null ? missingLabel : formatNumber(value, line);
 	const formatReference = (value) => series[0] ? formatNumber(value, series[0]) : `${GROUPED.format(value)}${unit ? ` ${unit}` : ""}`;
 	const reading = index === null ? null : data[index];
 	const shown = reading ?? data[last];
-	const valueText = reading ? `${reading.label}: ${visible.map((line) => `${line.label} ${format(read(reading, line.key), line)}`).join(", ")}` : empty ? emptyLabel : `${visible.length} of ${series.length} series shown`;
-	const summary = empty ? `${label}. ${emptyLabel}.` : `${label}, ${data[0].label} to ${data[last].label}. ${visible.map((line) => `${line.label}, latest ${format(read(data[last], line.key), line)}`).join(". ")}.${drawnReferences.map((reference) => typeof reference.value === "number" ? ` ${reference.label}: ${formatReference(reference.value)}.` : ` ${reference.label}: ${data.find((item) => item.key === reference.at).label}.`).join("")}`;
+	const markedHere = index === null ? [] : drawnMarkers.filter((marker) => markerIndex(marker) === index);
+	const valueText = reading ? `${reading.label}: ${visible.map((line) => `${line.label} ${format(read(reading, line.key), line)}`).join(", ")}${markedHere.map((marker) => `. ${marker.description ?? marker.label}`).join("")}` : empty ? emptyLabel : `${visible.length} of ${series.length} series shown`;
+	const summary = empty ? `${label}. ${emptyLabel}.` : `${label}, ${data[0].label} to ${data[last].label}. ${visible.map((line) => `${line.label}, latest ${format(read(data[last], line.key), line)}${typeof line.endLabel === "string" ? `, ${line.endLabel}` : ""}`).join(". ")}.${drawnReferences.map((reference) => typeof reference.value === "number" ? ` ${reference.label}: ${formatReference(reference.value)}.` : ` ${reference.label}: ${data.find((item) => item.key === reference.at).label}.`).join("")}${drawnMarkers.map((marker) => ` ${marker.description ?? marker.label}: ${data[markerIndex(marker)].label}.`).join("")}${drawnBands.map((band) => ` ${band.description ?? `${band.label}: ${formatReference(Math.min(band.from, band.to))} to ${formatReference(Math.max(band.from, band.to))}`}.`).join("")}`;
+	const pointLabels = empty ? [] : series.flatMap((line) => {
+		if (!line.pointLabels && !line.endLabel) return [];
+		const present = data.flatMap((item, at) => {
+			const value = read(item, line.key);
+			return value === null ? [] : [{
+				at,
+				value
+			}];
+		});
+		const end = line.endLabel ? present.at(-1) : void 0;
+		return [...(line.pointLabels ? present.filter((point) => point !== end) : []).map((point) => ({
+			line,
+			...point,
+			end: false,
+			text: formatShort(point.value, line)
+		})), ...end ? [{
+			line,
+			...end,
+			end: true,
+			text: typeof line.endLabel === "string" ? line.endLabel : formatShort(end.value, line)
+		}] : []];
+	});
+	const readout = /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("p", {
+		className: "m-0 mb-0.5 whitespace-nowrap text-xs tabular-nums text-text-secondary",
+		children: shown?.label ?? ""
+	}), visible.map((line) => /* @__PURE__ */ jsxs("p", {
+		className: "m-0 flex min-w-0 items-center gap-2 text-sm",
+		style: { "--series": colorOf(line, series.indexOf(line)) },
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"data-dashed": line.dashed || void 0,
+				className: "chart-tip-swatch"
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: "min-w-0 flex-1 truncate text-text-secondary",
+				children: line.label
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: "ms-2 flex-none whitespace-nowrap font-medium tabular-nums text-foreground",
+				children: shown ? format(read(shown, line.key), line) : format(0, line)
+			})
+		]
+	}, line.key))] });
+	const tipContent = renderTooltip && shown ? renderTooltip({
+		datum: shown,
+		index: index ?? last,
+		series: visible,
+		values: Object.fromEntries(visible.map((line) => [line.key, read(shown, line.key)])),
+		format,
+		readout
+	}) : readout;
 	const picks = axisPicks(data, plotWidth);
 	const allHidden = !empty && visible.length === 0;
 	return /* @__PURE__ */ jsxs("figure", {
@@ -570,7 +679,16 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 											style: { width: drawn ? plotWidth + 16 : 0 }
 										})
 									}) }),
-									steady.ticks.slice(1).map((value) => /* @__PURE__ */ jsx("line", {
+									drawnBands.map((band) => /* @__PURE__ */ jsx("rect", {
+										"data-band": band.key,
+										"data-from": band.from,
+										"data-to": band.to,
+										"data-tone": band.tone,
+										className: "line-chart-band",
+										x: 0,
+										width: "100%"
+									}, band.key)),
+									(reversed ? steady.ticks.slice(0, -1) : steady.ticks.slice(1)).map((value) => /* @__PURE__ */ jsx("line", {
 										"data-grid": value,
 										className: "line-chart-grid",
 										x1: 0,
@@ -586,12 +704,14 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 									drawnReferences.map((reference) => typeof reference.value === "number" ? /* @__PURE__ */ jsx("line", {
 										"data-reference": reference.key,
 										"data-reference-value": reference.value,
+										"data-tone": reference.tone,
 										className: "line-chart-reference",
 										x1: 0,
 										x2: "100%"
 									}, reference.key) : /* @__PURE__ */ jsx("line", {
 										"data-reference": reference.key,
 										"data-reference-at": referenceAt(reference),
+										"data-tone": reference.tone,
 										className: "line-chart-reference",
 										y1: 8,
 										y2: height
@@ -627,6 +747,14 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 									}, line.key))
 								]
 							}),
+							drawnBands.map((band) => /* @__PURE__ */ jsx("span", {
+								"aria-hidden": "true",
+								"data-slot": "line-chart-band-label",
+								"data-band-label": band.key,
+								"data-tone": band.tone,
+								className: "line-chart-band-label",
+								children: band.label
+							}, band.key)),
 							drawnReferences.map((reference) => /* @__PURE__ */ jsx("span", {
 								"aria-hidden": "true",
 								"data-slot": "line-chart-reference-label",
@@ -634,35 +762,46 @@ const LineChart = forwardRef(function LineChart({ data, series, label, unit = ""
 								"data-reference-value": typeof reference.value === "number" ? reference.value : void 0,
 								"data-reference-at": typeof reference.value === "number" ? void 0 : referenceAt(reference),
 								"data-axis": typeof reference.value === "number" ? "value" : "category",
+								"data-tone": reference.tone,
 								className: "line-chart-reference-label",
 								children: reference.label
 							}, reference.key)),
-							/* @__PURE__ */ jsxs("div", {
+							drawnMarkers.map((marker) => {
+								const share = last > 0 ? markerIndex(marker) / last : .5;
+								return /* @__PURE__ */ jsx("span", {
+									"aria-hidden": "true",
+									"data-slot": "line-chart-marker",
+									"data-marker": marker.key,
+									"data-tone": marker.tone,
+									className: "line-chart-marker",
+									style: { left: `${share * 100}%` },
+									children: /* @__PURE__ */ jsx("span", {
+										className: "line-chart-marker-label",
+										style: { translate: `${-share * 100}% 0` },
+										children: marker.label
+									})
+								}, marker.key);
+							}),
+							pointLabels.map(({ line, at, end, text }) => /* @__PURE__ */ jsxs("span", {
+								"aria-hidden": "true",
+								"data-slot": end ? "line-chart-end-label" : "line-chart-point-label",
+								"data-point-label": line.key,
+								"data-x": last > 0 ? at / last : .5,
+								className: "line-chart-point-label",
+								"data-end": end || void 0,
+								style: { "--series": colorOf(line, series.indexOf(line)) },
+								children: [end ? /* @__PURE__ */ jsx("span", {
+									"data-dashed": line.dashed || void 0,
+									className: "chart-tip-swatch"
+								}) : null, text]
+							}, `${line.key}:${data[at].key}`)),
+							/* @__PURE__ */ jsx("div", {
 								ref: tip,
 								"aria-hidden": "true",
 								"data-slot": "line-chart-tooltip",
+								"data-empty": !tipContent || void 0,
 								className: "line-chart-tooltip",
-								children: [/* @__PURE__ */ jsx("p", {
-									className: "m-0 mb-0.5 whitespace-nowrap text-xs tabular-nums text-text-secondary",
-									children: shown?.label ?? ""
-								}), visible.map((line) => /* @__PURE__ */ jsxs("p", {
-									className: "m-0 flex min-w-0 items-center gap-2 text-sm",
-									style: { "--series": colorOf(line, series.indexOf(line)) },
-									children: [
-										/* @__PURE__ */ jsx("span", {
-											"data-dashed": line.dashed || void 0,
-											className: "chart-tip-swatch"
-										}),
-										/* @__PURE__ */ jsx("span", {
-											className: "min-w-0 flex-1 truncate text-text-secondary",
-											children: line.label
-										}),
-										/* @__PURE__ */ jsx("span", {
-											className: "ms-2 flex-none whitespace-nowrap font-medium tabular-nums text-foreground",
-											children: shown ? format(read(shown, line.key), line) : format(0, line)
-										})
-									]
-								}, line.key))]
+								children: tipContent
 							}),
 							(empty || allHidden) && !loading ? /* @__PURE__ */ jsx("p", {
 								className: "absolute inset-0 m-0 grid place-items-center text-sm text-muted-foreground pointer-events-none motion-safe:animate-fade-in",