@tangle-network/charts 0.1.13 → 0.2.0

package/README.md

@@ -27,7 +27,7 @@ Malformed rates, intervals, matrix counts, and breakdown counts return a refusal
 Unmeasured and flagged matrix attempts keep distinct marks and table counts, even without tier grades.
 An interval whisker is omitted when its bounds exclude the row's rate.
 
-It has no runtime dependencies and uses no DOM, so it runs in a Worker, a build step or a browser.
+The static root has no runtime dependencies and uses no DOM, so it runs in a Worker, a build step or a browser. The separate opt-in `@tangle-network/charts/react` entrypoint requires React; it is never re-exported by the root.
 
 ## Use
 
@@ -134,3 +134,72 @@ Plot presentation uses labels of at least 14px and numeric axes of 15px.
 Dedicated phone SVGs retain their intended width inside a keyboard-accessible scroll region.
 Wide plots reserve side gutters so enlarged labels remain visible.
 These typography rules do not apply to report or chart presentation.
+
+## Optional React renderers
+
+```tsx
+import { useState } from "react";
+import { Sparkline, StackedBarChart } from "@tangle-network/charts/react";
+
+export function RecordedUnits() {
+  const [selectedBucketId, onSelectionChange] = useState<string | null>(null);
+  return <>
+    <Sparkline label="Completion delta" values={[-2, 0, null, 3]} format={String} />
+    <StackedBarChart
+      label="Recorded units"
+      series={[{ id: "a", label: "Series A", color: "var(--chart-accent)" }]}
+      buckets={[
+        { id: "first", label: "First window", total: 3, segments: [{ seriesId: "a", value: 3 }] },
+        { id: "missing", label: "Second window", total: null, segments: [{ seriesId: "a", value: null }] },
+      ]}
+      maxValue={10}
+      formatValue={(value) => `${value} units`}
+      selectedBucketId={selectedBucketId}
+      onSelectionChange={onSelectionChange}
+    />
+  </>;
+}
+```
+
+Install React 18 or 19 in the consuming app. It is an **optional peer** so static-only consumers need neither React nor its types. There is no React DOM, chart framework or UI-package runtime dependency. The renderers need no generated stylesheet; `figure.css` remains exclusively the unchanged static-figure stylesheet. Supply application font/color styles and readable series colors. Apps with server/client component boundaries mark their interactive wrapper as a client component.
+
+**Different scales, on purpose.** `Sparkline` ports Agent App's observed-extent scale; it does not implicitly include zero. Equal readings sit at mid-height, a single reading is a point, null/nonfinite samples retain their sample index and break the line, and finite negative readings are supported. Width/height props control its viewBox. Its accessible name describes the count, gaps, range and direction; the SVG description contains each sample's formatted value. It is not animated and has no selection interaction. The default `en-US` formatter retains Agent App's two-decimal behavior; pass `format={String}` or a domain-specific formatter when exact precision is important.
+
+`StackedBarChart` always uses the caller's **explicit `[0, maxValue]` domain**. It accepts already-grouped buckets with unique IDs, labels, supplied totals and ordered segments referencing declared series IDs. It never fetches, sorts, groups, calculates billed amounts, chooses a currency, maps products/categories, or invents a maximum. Input bucket order is the sample axis, not an inferred date axis; supply every intended bucket, including gaps. Omitted segments are not synthesized as zero.
+
+A null/nonfinite total or segment makes the whole stack a gap rather than a misleading complete bar. The known values remain in the readout and data table. Zero remains measured zero and draws no positive segment. As in the handoff, positive subpixel segments have a one-pixel visual minimum; their reported values and the total are not changed. Negative or out-of-domain finite values, duplicate/unknown identities, and inconsistent complete totals throw `RangeError` rather than clamp or silently aggregate. Nonnegative stacks do not model credits or diverging signed stacks. The existing static `Refusal` API is unchanged; it is not repurposed as React component state.
+
+Selection is controlled by bucket ID. Hover, focus, click, Enter, Space and touch activation select rather than toggle; mouse leave, blur and Escape dismiss. A removed selected ID shows no stale readout, and reordering never selects another bucket by index. The stabilized SVG keeps full-height hit targets and highlights the actual stack. A named keyboard-scrollable region contains its fluid SVG with a 400px minimum. A cursor-adjacent tooltip repeats the selected values for mouse and pen users. It flips at viewport edges and uses a native manual popover to escape transformed or clipped panels. Browsers without popover support use a fixed-position fallback, which a transformed ancestor can constrain. The selected breakdown remains in flow and live-announced; every bucket also carries its formatted values in its accessible name, and a native “View data” disclosure contains the full table. No Tailwind build or hover-only tooltip is required to read the values.
+
+**Provenance and extraction boundary.** Sparkline comes from `tangle-network/agent-app`, `src/web-react/sparkline.tsx` and its tests at `a8947683a050394d13848bb7e4cbbe7cf08d208e`. Stacked SVG rendering and select-never-toggle regressions come from merged ADC [PR #8746](https://github.com/tangle-network/agent-dev-container/pull/8746), `products/platform/web/src/client/components/UsageChartSvg.tsx` and `UsageChart.test.tsx` at `a1c3958fd73a3894d4515f9dc476dae9ace30ce0`. Platform's aggregation, currency/product/category functions, legend composition and portal-tooltip positioning are **not** copied. The persistent readout and native pointer popover avoid a new React DOM peer. This is not a new universal usage-chart API, a zero-baseline replacement for SpendCard's sparkline, or a consumer migration; Platform and Agent App are not edited.
+
+### React and package-boundary checks
+
+```sh
+pnpm exec vitest run packages/charts/src/react/sparkline.test.tsx packages/charts/src/react/stacked-bar-chart.test.tsx
+pnpm exec vitest run packages/charts/src/package-boundary.test.ts
+pnpm exec vitest run packages/charts
+pnpm --filter @tangle-network/charts exec tsc --noEmit
+pnpm --filter @tangle-network/charts build
+```
+
+The package-boundary test builds and packs Charts, installs the tarball in an OS-temporary consumer with a normal offline npm install (no peer-omission flags), asserts React/React DOM/React types cannot resolve, and executes the static root without DOM globals. It compares root exports, static SVG/tables, Refusals, report/chart/plot HTML and CSS with the untouched source implementation, then compiles a static-only consumer with `lib: ["ES2022"]`, `types: []` and `skipLibCheck: false`. Only afterward does it supply the workspace React peer/types to verify the packed React runtime and declarations. It runs under the existing root `pnpm test`; no CI workflow or shared UI smoke-script changes are needed.
+
+The component tests cover gap/zero/one/equal/negative cases, controlled identity, keyboard/touch selection, nonvisual values and resize contracts. The jsdom resize check verifies fluid/minimum-width attributes and preserved selection, **not browser-computed layout**; The retained packed-browser fixture checks Chromium at 1100px and 390px, keyboard selection, emulated touch, light/dark Brand tokens, reduced motion, and top-layer positioning inside a transformed, paint-contained panel. It passes with React 18 and React 19; the React 18 consumer also compiles the packed declarations with React 18 types. Physical touch hardware and screen-reader audio remain unchecked.
+
+### Packed browser proof
+
+Build Charts, then run the reusable fixture from the repository root.
+Pass a tarball path to test a published artifact after downloading it with npm pack.
+
+```sh
+pnpm --filter @tangle-network/charts build
+PORT=46489 node scripts/charts-browser-smoke.mjs /absolute/path/to/charts.tgz
+python3 scripts/charts-browser-proof.py http://127.0.0.1:46489 /tmp/charts-proof
+```
+
+Set `CHARTS_REACT_VERSION=18` to install and check an isolated React 18 runtime and type consumer.
+The default fixture uses the installed workspace React peer and bundles only the packed Charts export.
+The fixture imports Brand token CSS and creates a transformed, paint-contained panel.
+It needs Python Playwright and Chromium at `/snap/bin/chromium`.
+Receipts and screenshots are in [the retained proof](../../docs/evidence/charts-react-189/README.md).

package/dist/index.js

@@ -2345,6 +2345,10 @@ function timeSeries(rows, o) {
 	}
 	const xLabel = (x) => o.formatX ? o.formatX(x) : String(x);
 	const yLabel = (y) => scalarLabel(y, o.y.unit, o.formatY);
+	if (axisGutter(Array.from({ length: 5 }, (_, i) => o.y.domain[0] + i / 4 * (o.y.domain[1] - o.y.domain[0])), yLabel) >= 270) return {
+		id,
+		refused: "Formatted y-axis labels leave no room for the phone chart. Use a shorter formatter or unit."
+	};
 	const flat = rows.flatMap((row) => row.points.map((point) => ({
 		row,
 		point
@@ -2397,18 +2401,17 @@ function timeSeries(rows, o) {
 	};
 }
 function plot(rows, o, width, xLabel, yLabel, facts) {
-	const left = 64, right = width - 24, top = 36, bottom = 260;
+	const ticks = Array.from({ length: 5 }, (_, i) => o.y.domain[0] + i / 4 * (o.y.domain[1] - o.y.domain[0]));
+	const left = axisGutter(ticks, yLabel);
+	const right = width - 24, top = 36, bottom = 260;
 	const px = (x) => left + (x - o.x.domain[0]) / (o.x.domain[1] - o.x.domain[0]) * (right - left);
 	const py = (y) => bottom - (y - o.y.domain[0]) / (o.y.domain[1] - o.y.domain[0]) * 224;
 	let marks = text(left, 18, o.y.label, { cls: "tgc-ink-muted" });
-	for (let i = 0; i <= 4; i++) {
-		const y = o.y.domain[0] + i / 4 * (o.y.domain[1] - o.y.domain[0]);
-		marks += line(left, py(y), right, py(y), i === 0 ? "tgc-axis" : "tgc-gridline") + text(56, py(y) + 4, yLabel(y), {
-			anchor: "end",
-			cls: "tgc-ink-muted tgc-num",
-			size: 11
-		});
-	}
+	for (const [i, y] of ticks.entries()) marks += line(left, py(y), right, py(y), i === 0 ? "tgc-axis" : "tgc-gridline") + text(left - 8, py(y) + 4, yLabel(y), {
+		anchor: "end",
+		cls: "tgc-ink-muted tgc-num",
+		size: 12
+	});
 	const xs = [...new Set(rows.flatMap((row) => row.points.map((point) => point.x)))].sort((a, b) => a - b);
 	const tickStep = Math.max(1, Math.ceil(xs.length / (width < 720 ? 5 : 10)));
 	for (const [i, x] of xs.entries()) if (i % tickStep === 0 || i === xs.length - 1) marks += text(px(x), 280, xLabel(x), {
@@ -2448,10 +2451,13 @@ function plot(rows, o, width, xLabel, yLabel, facts) {
 		}
 		flush();
 		const label = wrap(row.label, right - left - 32, 12, "sans", 8);
-		marks += `<g style="stroke-dasharray:${dash}">${line(left, legendY - 4, 88, legendY - 4, "tgc-series-line")}</g>` + textBlock(label.lines, 96, legendY, 16, "class=\"tgc-ink\" font-size=\"12\"");
+		marks += `<g style="stroke-dasharray:${dash}">${line(left, legendY - 4, left + 24, legendY - 4, "tgc-series-line")}</g>` + textBlock(label.lines, left + 32, legendY, 16, "class=\"tgc-ink\" font-size=\"12\"");
 		legendY += label.lines.length * 16 + 8;
 	}
 	return `<svg class="tgc-svg tgc-trajectories" xmlns="http://www.w3.org/2000/svg" width="${width}" height="${legendY + 12}" viewBox="0 0 ${width} ${legendY + 12}" role="group" aria-label="${esc(o.y.label)} by ${esc(o.x.label)}"><style>${rules}</style>${marks}${points}${tips}</svg>`;
 }
+function axisGutter(ticks, label) {
+	return Math.max(64, ...ticks.map((value) => Math.ceil(textWidth(label(value), 12, "mono")) + 20));
+}
 //#endregion
 export { breakdown, chartTokensCss, comparisonIntervals, costFrontier, figureCss, isRefusal, metricBars, rankedRates, rateOrder, renderFigure, renderNotes, renderRefusals, taskMatrix, timeSeries };

package/dist/react/index.d.ts

@@ -0,0 +1,84 @@
+import { ReactElement } from "react";
+//#region src/react/sparkline.d.ts
+type SparklineDirection = "rising" | "falling" | "flat";
+type SparklineValues = readonly (number | null)[];
+interface SparklinePoint {
+  readonly x: number;
+  readonly y: number;
+}
+interface SparklineGeometry {
+  readonly readings: readonly number[];
+  readonly points: readonly SparklinePoint[];
+  /** One run per set of consecutive, finite samples. */
+  readonly segments: readonly (readonly SparklinePoint[])[];
+  readonly gaps: number;
+  readonly min: number;
+  readonly max: number;
+  readonly first: number;
+  readonly last: number;
+  readonly direction: SparklineDirection;
+}
+interface SparklineGeometryOptions {
+  width?: number;
+  height?: number;
+  inset?: number;
+}
+export declare const DEFAULT_SPARKLINE_WIDTH = 96;
+export declare const DEFAULT_SPARKLINE_HEIGHT = 24;
+export declare const DEFAULT_SPARKLINE_LABEL = "Trend";
+export declare const DEFAULT_SPARKLINE_EMPTY_LABEL = "No history yet";
+export declare const DEFAULT_SPARKLINE_UNAVAILABLE_LABEL = "No readings available";
+export declare function formatSparklineValue(value: number): string;
+export declare function sparklineReadings(values: SparklineValues): number[];
+export declare function sparklineGeometry(values: SparklineValues, { width, height, inset }?: SparklineGeometryOptions): SparklineGeometry;
+export declare function sparklinePointsAttribute(points: readonly SparklinePoint[]): string;
+interface SparklineLabelOptions {
+  label?: string;
+  format?: (value: number) => string;
+}
+export declare function sparklineLabel(values: SparklineValues, { label, format }?: SparklineLabelOptions): string;
+interface SparklineProps extends SparklineLabelOptions {
+  values: SparklineValues;
+  width?: number;
+  height?: number;
+  emptyLabel?: string;
+  unavailableLabel?: string;
+  className?: string;
+}
+export declare function Sparkline({ values, label, format, width, height, emptyLabel, unavailableLabel, className }: SparklineProps): ReactElement;
+//#endregion
+//#region src/react/stacked-bar-chart.d.ts
+interface StackedBarSeries {
+  readonly id: string;
+  readonly label: string;
+  /** Caller-owned CSS color, e.g. a brand token. Never inferred from an ID. */
+  readonly color: string;
+}
+interface StackedBarSegment {
+  readonly seriesId: string;
+  readonly value: number | null;
+}
+interface StackedBarBucket {
+  readonly id: string;
+  readonly label: string;
+  /** Pre-aggregated by the caller. Null/nonfinite readings are gaps, not zero. */
+  readonly total: number | null;
+  /** Stack order is input order. Charts neither groups nor sorts. */
+  readonly segments: readonly StackedBarSegment[];
+}
+interface StackedBarChartProps {
+  label: string;
+  series: readonly StackedBarSeries[];
+  buckets: readonly StackedBarBucket[];
+  /** Explicit [0, maxValue] domain. Zero is valid only for zero-valued data. */
+  maxValue: number;
+  formatValue: (value: number) => string;
+  selectedBucketId: string | null;
+  onSelectionChange: (bucketId: string | null) => void;
+  emptyLabel?: string;
+  unavailableLabel?: string;
+  className?: string;
+}
+export declare function StackedBarChart(props: StackedBarChartProps): import("react").JSX.Element;
+//#endregion
+export type { SparklineDirection, SparklineGeometry, SparklineGeometryOptions, SparklineLabelOptions, SparklinePoint, SparklineProps, SparklineValues, StackedBarBucket, StackedBarChartProps, StackedBarSegment, StackedBarSeries };

package/dist/react/index.js

@@ -0,0 +1,538 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, useId, useRef, useState } from "react";
+//#region src/react/sparkline.tsx
+const DEFAULT_SPARKLINE_WIDTH = 96;
+const DEFAULT_SPARKLINE_HEIGHT = 24;
+const DEFAULT_SPARKLINE_LABEL = "Trend";
+const DEFAULT_SPARKLINE_EMPTY_LABEL = "No history yet";
+const DEFAULT_SPARKLINE_UNAVAILABLE_LABEL = "No readings available";
+const DEFAULT_INSET = 2.5;
+const STROKE_WIDTH = 1.5;
+const DOT_RADIUS = 1.75;
+const NUMBER_FORMAT = new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 });
+const hidden = {
+	position: "absolute",
+	width: 1,
+	height: 1,
+	padding: 0,
+	margin: -1,
+	overflow: "hidden",
+	clipPath: "inset(50%)",
+	whiteSpace: "nowrap",
+	border: 0
+};
+function formatSparklineValue(value) {
+	return NUMBER_FORMAT.format(value);
+}
+function isReading(value) {
+	return typeof value === "number" && Number.isFinite(value);
+}
+function sparklineReadings(values) {
+	return values.filter(isReading);
+}
+function round(value) {
+	return Math.round(value * 100) / 100;
+}
+function sparklineGeometry(values, { width = 96, height = 24, inset = DEFAULT_INSET } = {}) {
+	if (!Number.isFinite(width) || !Number.isFinite(height) || !Number.isFinite(inset) || width <= 0 || height <= 0 || inset < 0 || inset * 2 > Math.min(width, height)) throw new RangeError("Sparkline requires finite positive dimensions and an inset inside the viewBox");
+	const plotted = [];
+	for (let index = 0; index < values.length; index += 1) {
+		const value = values[index];
+		if (isReading(value)) plotted.push({
+			index,
+			value
+		});
+	}
+	const readings = plotted.map(({ value }) => value);
+	const gaps = values.length - readings.length;
+	if (readings.length === 0) return {
+		readings,
+		points: [],
+		segments: [],
+		gaps,
+		min: 0,
+		max: 0,
+		first: 0,
+		last: 0,
+		direction: "flat"
+	};
+	let min = readings[0];
+	let max = readings[0];
+	for (const value of readings) {
+		if (value < min) min = value;
+		if (value > max) max = value;
+	}
+	const first = readings[0];
+	const last = readings[readings.length - 1];
+	const span = max - min;
+	const points = plotted.map(({ index, value }) => {
+		const fraction = span === 0 ? .5 : Number.isFinite(span) ? (value - min) / span : (value / 2 - min / 2) / (max / 2 - min / 2);
+		return {
+			x: round(values.length <= 1 ? width / 2 : inset + (width - 2 * inset) * index / (values.length - 1)),
+			y: round(height - inset - (height - 2 * inset) * fraction)
+		};
+	});
+	const segments = [];
+	let run = [];
+	let previous = Number.NEGATIVE_INFINITY;
+	plotted.forEach(({ index }, position) => {
+		if (index !== previous + 1 && run.length > 0) {
+			segments.push(run);
+			run = [];
+		}
+		run.push(points[position]);
+		previous = index;
+	});
+	if (run.length > 0) segments.push(run);
+	return {
+		readings,
+		points,
+		segments,
+		gaps,
+		min,
+		max,
+		first,
+		last,
+		direction: last > first ? "rising" : last < first ? "falling" : "flat"
+	};
+}
+function sparklinePointsAttribute(points) {
+	return points.map(({ x, y }) => `${x},${y}`).join(" ");
+}
+function sparklineLabel(values, { label = DEFAULT_SPARKLINE_LABEL, format = formatSparklineValue } = {}) {
+	const { readings, gaps, min, max, first, last, direction } = sparklineGeometry(values);
+	const missing = gaps === 0 ? "" : `, ${gaps} not available`;
+	if (readings.length === 0) return gaps === 0 ? `${label}: no readings yet` : `${label}: no readings${missing}`;
+	if (readings.length === 1) return `${label}: one reading${missing}, ${format(first)}`;
+	if (max === min) return `${label}: ${readings.length} readings${missing}, unchanged at ${format(first)}`;
+	const movement = direction === "flat" ? "net unchanged" : direction;
+	return `${label}: ${readings.length} readings${missing}, range ${format(min)} to ${format(max)}, ${movement} from ${format(first)} to ${format(last)}`;
+}
+function Sparkline({ values, label = DEFAULT_SPARKLINE_LABEL, format = formatSparklineValue, width = 96, height = 24, emptyLabel = DEFAULT_SPARKLINE_EMPTY_LABEL, unavailableLabel = DEFAULT_SPARKLINE_UNAVAILABLE_LABEL, className }) {
+	const geometry = sparklineGeometry(values, {
+		width,
+		height
+	});
+	const accessibleName = sparklineLabel(values, {
+		label,
+		format
+	});
+	if (geometry.points.length === 0) return /* @__PURE__ */ jsxs("span", {
+		"data-sparkline": geometry.gaps > 0 ? "unavailable" : "empty",
+		className,
+		children: [/* @__PURE__ */ jsx("span", {
+			style: hidden,
+			children: accessibleName
+		}), /* @__PURE__ */ jsx("span", {
+			"aria-hidden": "true",
+			children: geometry.gaps > 0 ? unavailableLabel : emptyLabel
+		})]
+	});
+	const drawsLine = geometry.segments.some((segment) => segment.length > 1);
+	const end = geometry.points[geometry.points.length - 1];
+	return /* @__PURE__ */ jsxs("svg", {
+		role: "img",
+		"aria-label": accessibleName,
+		"data-scale": "extent",
+		"data-sparkline": drawsLine ? "line" : "point",
+		"data-direction": geometry.direction,
+		"data-gaps": geometry.gaps > 0 ? geometry.gaps : void 0,
+		width,
+		height,
+		viewBox: `0 0 ${width} ${height}`,
+		className,
+		focusable: "false",
+		children: [
+			/* @__PURE__ */ jsx("desc", { children: Array.from(values, (value, index) => `Sample ${index + 1}: ${isReading(value) ? format(value) : "not available"}`).join("; ") }),
+			geometry.segments.map((segment, index) => {
+				if (segment.length > 1) return /* @__PURE__ */ jsx("polyline", {
+					points: sparklinePointsAttribute(segment),
+					fill: "none",
+					stroke: "currentColor",
+					strokeWidth: STROKE_WIDTH,
+					strokeLinecap: "round",
+					strokeLinejoin: "round",
+					vectorEffect: "non-scaling-stroke"
+				}, `segment-${index}`);
+				const only = segment[0];
+				if (only.x === end.x && only.y === end.y) return null;
+				return /* @__PURE__ */ jsx("circle", {
+					cx: only.x,
+					cy: only.y,
+					r: DOT_RADIUS,
+					fill: "currentColor"
+				}, `segment-${index}`);
+			}),
+			/* @__PURE__ */ jsx("circle", {
+				cx: end.x,
+				cy: end.y,
+				r: DOT_RADIUS,
+				fill: "currentColor"
+			})
+		]
+	});
+}
+//#endregion
+//#region src/react/stacked-bar-chart.tsx
+/**
+* Renderer extracted from ADC PR #8746, a1c3958fd73a3894d4515f9dc476dae9ace30ce0:
+* products/platform/web/src/client/components/UsageChartSvg.tsx.
+* Keeps its viewBox, hit targets, actual-stack highlight and select-never-toggle
+* interaction. Product/category mapping, aggregation, currency and the portal
+* tooltip formatting remain caller-owned; no React DOM dependency is needed here.
+*/
+function isValue(value) {
+	return value !== null && Number.isFinite(value);
+}
+function hasGap(bucket) {
+	return !isValue(bucket.total) || bucket.segments.some(({ value }) => !isValue(value));
+}
+function validate({ series, buckets, maxValue }) {
+	if (!Number.isFinite(maxValue) || maxValue < 0) throw new RangeError("StackedBarChart maxValue must be finite and nonnegative");
+	const seriesIds = /* @__PURE__ */ new Set();
+	for (const { id } of series) {
+		if (!id || seriesIds.has(id)) throw new RangeError("StackedBarChart requires unique, nonempty series IDs");
+		seriesIds.add(id);
+	}
+	const bucketIds = /* @__PURE__ */ new Set();
+	for (const bucket of buckets) {
+		if (!bucket.id || bucketIds.has(bucket.id)) throw new RangeError("StackedBarChart requires unique, nonempty bucket IDs");
+		bucketIds.add(bucket.id);
+		const segments = /* @__PURE__ */ new Set();
+		let sum = 0;
+		for (const { seriesId, value } of bucket.segments) {
+			if (!seriesIds.has(seriesId) || segments.has(seriesId)) throw new RangeError("StackedBarChart segments require distinct, declared series IDs");
+			segments.add(seriesId);
+			if (isValue(value)) {
+				if (value < 0 || value > maxValue) throw new RangeError("StackedBarChart values must lie in [0, maxValue]");
+				sum += value;
+			}
+		}
+		if (isValue(bucket.total) && (bucket.total < 0 || bucket.total > maxValue)) throw new RangeError("StackedBarChart totals must lie in [0, maxValue]");
+		if (!hasGap(bucket)) {
+			const total = bucket.total;
+			const tolerance = Number.EPSILON * 8 * Math.max(Math.abs(sum), Math.abs(total), Number.MIN_VALUE);
+			if (!Number.isFinite(sum) || Math.abs(sum - total) > tolerance) throw new RangeError("StackedBarChart total must match its supplied segments");
+		}
+	}
+}
+function StackedBarChart(props) {
+	const { label, series, buckets, maxValue, formatValue, selectedBucketId, onSelectionChange, emptyLabel = "No data yet", unavailableLabel = "Not available", className } = props;
+	const readoutId = useId();
+	const touchInteraction = useRef(false);
+	const [pointerBucketId, setPointerBucketId] = useState(null);
+	const pointerPosition = useRef({
+		x: 0,
+		y: 0
+	});
+	const tooltipRef = useRef(null);
+	const positionTooltip = (element) => {
+		const viewport = element.ownerDocument.defaultView;
+		if (!viewport) return;
+		const { width, height } = element.getBoundingClientRect();
+		const { x, y } = pointerPosition.current;
+		const left = x + 14 + width <= viewport.innerWidth - 8 ? x + 14 : x - width - 14;
+		const top = y + 14 + height <= viewport.innerHeight - 8 ? y + 14 : y - height - 14;
+		element.style.transform = `translate(${Math.max(8, Math.min(left, viewport.innerWidth - width - 8))}px, ${Math.max(8, Math.min(top, viewport.innerHeight - height - 8))}px)`;
+	};
+	const trackPointer = (event, bucketId) => {
+		pointerPosition.current = {
+			x: event.clientX,
+			y: event.clientY
+		};
+		if (pointerBucketId !== bucketId) setPointerBucketId(bucketId);
+		if (tooltipRef.current) positionTooltip(tooltipRef.current);
+	};
+	validate(props);
+	const bySeries = new Map(series.map((entry) => [entry.id, entry]));
+	const formatted = (value) => isValue(value) ? formatValue(value) : unavailableLabel;
+	const summary = (bucket) => `${bucket.label}: total ${formatted(bucket.total)}` + (hasGap(bucket) ? ` — ${unavailableLabel}` : "") + (bucket.segments.length ? ` — ${bucket.segments.map((segment) => `${bySeries.get(segment.seriesId).label} ${formatted(segment.value)}`).join(", ")}` : "");
+	const activeIndex = selectedBucketId === null ? -1 : buckets.findIndex(({ id }) => id === selectedBucketId);
+	const activeBucket = activeIndex >= 0 ? buckets[activeIndex] : null, marginTop = 12, marginRight = 16, marginLeft = 56;
+	const chartHeight = 220;
+	const innerHeight = 176;
+	const barGap = 6;
+	const barWidth = Math.max(8, Math.min(36, 648 / Math.max(1, buckets.length) - barGap));
+	const viewWidth = Math.max(buckets.length * (barWidth + barGap) + marginLeft + marginRight, 400);
+	const denseLabels = buckets.length > 14;
+	if (buckets.length === 0) return /* @__PURE__ */ jsxs("p", {
+		className,
+		children: [
+			label,
+			": ",
+			emptyLabel
+		]
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		className,
+		"data-stacked-bar-chart": "",
+		"data-scale": "zero",
+		children: [
+			/* @__PURE__ */ jsx("section", {
+				tabIndex: 0,
+				"aria-label": `${label} chart`,
+				style: { overflowX: "auto" },
+				children: /* @__PURE__ */ jsxs("svg", {
+					"aria-label": label,
+					width: "100%",
+					viewBox: `0 0 ${viewWidth} ${chartHeight}`,
+					style: {
+						display: "block",
+						minWidth: 400,
+						maxWidth: "100%",
+						maxHeight: 300
+					},
+					preserveAspectRatio: "xMinYMin meet",
+					children: [[
+						0,
+						.25,
+						.5,
+						.75,
+						1
+					].map((fraction) => {
+						const y = 188 - fraction * innerHeight;
+						return /* @__PURE__ */ jsxs("g", {
+							"aria-hidden": "true",
+							children: [/* @__PURE__ */ jsx("line", {
+								x1: marginLeft,
+								y1: y,
+								x2: viewWidth - marginRight,
+								y2: y,
+								stroke: "currentColor",
+								strokeDasharray: fraction === 0 ? "0" : "3 3",
+								opacity: fraction === 0 ? .4 : .2
+							}), /* @__PURE__ */ jsx("text", {
+								x: 48,
+								y,
+								dy: "0.32em",
+								textAnchor: "end",
+								fontSize: "11",
+								fill: "currentColor",
+								fontFamily: "inherit",
+								children: formatValue(maxValue * fraction)
+							})]
+						}, fraction);
+					}), buckets.map((bucket, index) => {
+						const x = marginLeft + index * (barWidth + barGap) + barGap / 2;
+						const isActive = index === activeIndex;
+						const gap = hasGap(bucket);
+						const stackHeight = !gap && maxValue > 0 ? bucket.total / maxValue * innerHeight : 0;
+						let yOffset = 0;
+						const select = () => onSelectionChange(bucket.id);
+						const clear = () => {
+							if (isActive) onSelectionChange(null);
+						};
+						return /* @__PURE__ */ jsxs("g", {
+							role: "button",
+							tabIndex: 0,
+							"data-bucket-id": bucket.id,
+							"data-gap": gap || void 0,
+							"aria-label": summary(bucket),
+							"aria-describedby": isActive ? readoutId : void 0,
+							onPointerEnter: (event) => {
+								touchInteraction.current = event.pointerType === "touch";
+								if (!touchInteraction.current) {
+									trackPointer(event, bucket.id);
+									select();
+								}
+							},
+							onPointerLeave: () => {
+								if (!touchInteraction.current) {
+									setPointerBucketId(null);
+									clear();
+								}
+							},
+							onPointerDown: (event) => {
+								touchInteraction.current = event.pointerType === "touch";
+								if (touchInteraction.current) setPointerBucketId(null);
+							},
+							onPointerMove: (event) => {
+								touchInteraction.current = event.pointerType === "touch";
+								if (!touchInteraction.current) {
+									trackPointer(event, bucket.id);
+									if (selectedBucketId !== bucket.id) select();
+								}
+							},
+							onMouseEnter: (event) => {
+								if (!touchInteraction.current) {
+									trackPointer(event, bucket.id);
+									select();
+								}
+							},
+							onMouseMove: (event) => {
+								if (!touchInteraction.current) {
+									trackPointer(event, bucket.id);
+									if (selectedBucketId !== bucket.id) select();
+								}
+							},
+							onMouseLeave: () => {
+								if (!touchInteraction.current) {
+									setPointerBucketId(null);
+									clear();
+								}
+							},
+							onFocus: select,
+							onBlur: clear,
+							onClick: select,
+							onKeyDown: (event) => {
+								setPointerBucketId(null);
+								if (event.key === "Enter" || event.key === " ") {
+									event.preventDefault();
+									select();
+								} else if (event.key === "Escape") {
+									event.preventDefault();
+									clear();
+								}
+							},
+							style: { cursor: "pointer" },
+							children: [
+								/* @__PURE__ */ jsx("rect", {
+									"data-hit-target": "",
+									x,
+									y: marginTop,
+									width: barWidth,
+									height: innerHeight,
+									fill: "transparent",
+									stroke: "none",
+									rx: 3
+								}),
+								!gap && bucket.segments.map((segment, segmentIndex) => {
+									const height = maxValue > 0 ? segment.value / maxValue * innerHeight : 0;
+									const y = 188 - yOffset - height;
+									yOffset += height;
+									return /* @__PURE__ */ jsx("rect", {
+										"data-series-id": segment.seriesId,
+										x,
+										y,
+										width: barWidth,
+										height: Math.max(height, height > 0 ? 1 : 0),
+										rx: segmentIndex === bucket.segments.length - 1 ? 3 : 0,
+										fill: bySeries.get(segment.seriesId).color,
+										opacity: isActive ? 1 : .92,
+										pointerEvents: "none"
+									}, segment.seriesId);
+								}),
+								gap && /* @__PURE__ */ jsx("text", {
+									x: x + barWidth / 2,
+									y: 184,
+									textAnchor: "middle",
+									fill: "currentColor",
+									"aria-hidden": "true",
+									pointerEvents: "none",
+									children: "—"
+								}),
+								isActive && /* @__PURE__ */ jsx("rect", {
+									"data-selection": "",
+									x,
+									y: 188 - Math.max(1, stackHeight),
+									width: barWidth,
+									height: Math.max(1, stackHeight),
+									fill: "none",
+									stroke: "currentColor",
+									strokeWidth: 1.5,
+									rx: 3,
+									pointerEvents: "none"
+								}),
+								/* @__PURE__ */ jsx("text", {
+									x: x + barWidth / 2,
+									y: 204,
+									textAnchor: denseLabels ? "end" : "middle",
+									fontSize: "10",
+									fill: "currentColor",
+									fontFamily: "inherit",
+									pointerEvents: "none",
+									"aria-hidden": "true",
+									transform: denseLabels ? `rotate(-40, ${x + barWidth / 2}, 204)` : void 0,
+									children: bucket.label
+								})
+							]
+						}, bucket.id);
+					})]
+				})
+			}),
+			activeBucket && pointerBucketId === activeBucket.id && !touchInteraction.current && /* @__PURE__ */ jsxs("div", {
+				"data-chart-tooltip": "",
+				role: "tooltip",
+				"aria-hidden": "true",
+				popover: "manual",
+				ref: (element) => {
+					tooltipRef.current = element;
+					if (element) {
+						if (typeof element.showPopover === "function") element.showPopover();
+						positionTooltip(element);
+					}
+				},
+				style: {
+					position: "fixed",
+					inset: "auto",
+					margin: 0,
+					left: 0,
+					top: 0,
+					zIndex: 1e3,
+					pointerEvents: "none",
+					width: "max-content",
+					maxWidth: "min(280px, calc(100vw - 16px))",
+					padding: "10px 12px",
+					borderRadius: "var(--radius-md, 8px)",
+					background: "var(--md3-surface-container-highest, #3b3b3b)",
+					color: "var(--md3-on-surface, #e6e6e6)",
+					border: "1px solid var(--md3-outline-variant, #4c4c4c)",
+					fontFamily: "inherit",
+					fontSize: "0.75rem",
+					lineHeight: 1.5,
+					overflowWrap: "anywhere"
+				},
+				children: [
+					/* @__PURE__ */ jsx("strong", { children: activeBucket.label }),
+					/* @__PURE__ */ jsxs("div", { children: ["Total ", formatted(activeBucket.total)] }),
+					activeBucket.segments.map((segment) => /* @__PURE__ */ jsxs("div", { children: [
+						bySeries.get(segment.seriesId).label,
+						": ",
+						formatted(segment.value)
+					] }, segment.seriesId))
+				]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				id: readoutId,
+				role: "status",
+				"aria-live": "polite",
+				"aria-atomic": "true",
+				children: activeBucket ? summary(activeBucket) : "Hover, tap, or focus a bar to see its breakdown."
+			}),
+			/* @__PURE__ */ jsxs("details", { children: [/* @__PURE__ */ jsx("summary", { children: "View data" }), /* @__PURE__ */ jsxs("table", { children: [
+				/* @__PURE__ */ jsx("caption", { children: label }),
+				/* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [
+					/* @__PURE__ */ jsx("th", {
+						scope: "col",
+						children: "Bucket"
+					}),
+					/* @__PURE__ */ jsx("th", {
+						scope: "col",
+						children: "Series"
+					}),
+					/* @__PURE__ */ jsx("th", {
+						scope: "col",
+						children: "Value"
+					})
+				] }) }),
+				/* @__PURE__ */ jsx("tbody", { children: buckets.map((bucket) => /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("tr", { children: [
+					/* @__PURE__ */ jsx("th", {
+						scope: "row",
+						children: bucket.label
+					}),
+					/* @__PURE__ */ jsx("td", { children: "Total" }),
+					/* @__PURE__ */ jsx("td", { children: formatted(bucket.total) })
+				] }), bucket.segments.map((segment) => /* @__PURE__ */ jsxs("tr", { children: [
+					/* @__PURE__ */ jsx("th", {
+						scope: "row",
+						children: bucket.label
+					}),
+					/* @__PURE__ */ jsx("td", { children: bySeries.get(segment.seriesId).label }),
+					/* @__PURE__ */ jsx("td", { children: formatted(segment.value) })
+				] }, segment.seriesId))] }, bucket.id)) })
+			] })] })
+		]
+	});
+}
+//#endregion
+export { DEFAULT_SPARKLINE_EMPTY_LABEL, DEFAULT_SPARKLINE_HEIGHT, DEFAULT_SPARKLINE_LABEL, DEFAULT_SPARKLINE_UNAVAILABLE_LABEL, DEFAULT_SPARKLINE_WIDTH, Sparkline, StackedBarChart, formatSparklineValue, sparklineGeometry, sparklineLabel, sparklinePointsAttribute, sparklineReadings };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/charts",
-  "version": "0.1.13",
+  "version": "0.2.0",
   "description": "Benchmark figures as static SVG and HTML tables: ranked rates, cost frontier, comparison intervals, task matrix and breakdown. Draws from producer data and refuses what it cannot draw honestly.",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,20 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
-    "./figure.css": "./dist/figure.css"
+    "./figure.css": "./dist/figure.css",
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
+    }
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "tsdown": "^0.23.0",