@tangle-network/charts 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,17 @@
 # @tangle-network/charts
 
-Benchmark figures as static SVG and HTML tables.
+Benchmark figures as static SVG and HTML tables, plus optional React timing primitives.
+
+`WaterfallHeader`, `WaterfallTimeAxis`, `WaterfallBar` and `WaterfallRow` from
+`@tangle-network/charts/react` own the timing presentation extracted from
+Intelligence's trace viewer. Supply actual span start/end milliseconds and the
+same `{ startMs, endMs }` window to every row. Hierarchy, selection, attribution,
+formatting and failure interpretation stay with the consumer. The original
+minimum/clipped marker remains visible; its tooltip reports the actual duration.
+Set `--waterfall-timing-width`, `--waterfall-duration-width` and the existing
+`--intel-waterfall-*` colors for the consumer's layout and theme. No stylesheet,
+router or React DOM dependency is required.
+
 Five figures cover the decisions a benchmark reader makes:
 
 | Figure | Question |

package/dist/react/index.d.ts

@@ -1,4 +1,4 @@
-import { ReactElement } from "react";
+import { ReactElement, ReactNode } from "react";
 //#region src/react/sparkline.d.ts
 type SparklineDirection = "rising" | "falling" | "flat";
 type SparklineValues = readonly (number | null)[];
@@ -81,4 +81,54 @@ interface StackedBarChartProps {
 }
 export declare function StackedBarChart(props: StackedBarChartProps): import("react").JSX.Element;
 //#endregion
-export type { SparklineDirection, SparklineGeometry, SparklineGeometryOptions, SparklineLabelOptions, SparklinePoint, SparklineProps, SparklineValues, StackedBarBucket, StackedBarChartProps, StackedBarSegment, StackedBarSeries };
+//#region src/react/waterfall.d.ts
+interface WaterfallWindow {
+  readonly startMs: number;
+  readonly endMs: number;
+}
+interface WaterfallSpanGeometry {
+  readonly offsetPct: number;
+  readonly widthPct: number;
+  readonly startOffsetMs: number;
+  readonly durationMs: number;
+  readonly clipped: boolean;
+}
+/** The Intelligence clipping/minimum-marker policy, applied to relative times. */
+export declare function waterfallSpanGeometry(startMs: number, endMs: number, window: WaterfallWindow): WaterfallSpanGeometry;
+/** Intelligence's round-duration ticks, with the original 208px default. */
+export declare function waterfallTicks(windowMs: number, widthPx?: number, minLabelGapPx?: number): number[];
+export declare function formatWaterfallDuration(ms: number): string;
+interface WaterfallTimeAxisProps {
+  windowMs: number;
+  originMs?: number;
+  widthPx?: number;
+  formatDuration?: (ms: number) => string;
+  className?: string;
+}
+export declare function WaterfallTimeAxis({ windowMs, originMs, widthPx, formatDuration, className }: WaterfallTimeAxisProps): import("react").JSX.Element | null;
+interface WaterfallBarProps {
+  startMs: number;
+  endMs: number;
+  window: WaterfallWindow;
+  tone?: "default" | "error" | "critical";
+  formatDuration?: (ms: number) => string;
+  className?: string;
+}
+export declare function WaterfallBar({ startMs, endMs, window, tone, formatDuration, className }: WaterfallBarProps): import("react").JSX.Element;
+interface WaterfallRowProps extends Omit<WaterfallBarProps, "className"> {
+  label: ReactNode;
+  attribution?: ReactNode;
+  timingClassName?: string;
+  durationClassName?: string;
+  className?: string;
+}
+/** Non-interactive row body; its caller owns treeitems, buttons and selection. */
+export declare function WaterfallRow({ label, attribution, startMs, endMs, window, tone, formatDuration, className, timingClassName, durationClassName }: WaterfallRowProps): import("react").JSX.Element;
+interface WaterfallHeaderProps extends WaterfallTimeAxisProps {
+  label?: ReactNode;
+  attribution?: ReactNode;
+  durationLabel?: ReactNode;
+}
+export declare function WaterfallHeader({ label, attribution, durationLabel, ...axis }: WaterfallHeaderProps): import("react").JSX.Element;
+//#endregion
+export type { SparklineDirection, SparklineGeometry, SparklineGeometryOptions, SparklineLabelOptions, SparklinePoint, SparklineProps, SparklineValues, StackedBarBucket, StackedBarChartProps, StackedBarSegment, StackedBarSeries, WaterfallBarProps, WaterfallHeaderProps, WaterfallRowProps, WaterfallSpanGeometry, WaterfallTimeAxisProps, WaterfallWindow };

package/dist/react/index.js

@@ -535,4 +535,224 @@ function StackedBarChart(props) {
 	});
 }
 //#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 };
+//#region src/react/waterfall.tsx
+/** The Intelligence clipping/minimum-marker policy, applied to relative times. */
+function waterfallSpanGeometry(startMs, endMs, window) {
+	if (![
+		startMs,
+		endMs,
+		window.startMs,
+		window.endMs
+	].every(Number.isFinite) || endMs < startMs || window.endMs < window.startMs) throw new RangeError("Waterfall requires finite, ordered span and window times");
+	const durationMs = endMs - startMs;
+	const startOffsetMs = startMs - window.startMs;
+	const windowMs = window.endMs - window.startMs;
+	const span = windowMs === 0 ? 1 : windowMs;
+	const rawOffsetPct = startOffsetMs / span * 100;
+	const endPct = rawOffsetPct + durationMs / span * 100;
+	const fullyOutside = endPct <= 0 || rawOffsetPct >= 100;
+	const offsetPct = Math.min(99, Math.max(0, rawOffsetPct));
+	return {
+		offsetPct,
+		widthPct: fullyOutside ? .5 : Math.max(.5, Math.min(100 - offsetPct, endPct - offsetPct)),
+		startOffsetMs,
+		durationMs,
+		clipped: fullyOutside || rawOffsetPct < 0 || endPct > 100
+	};
+}
+function niceTickMs(spanMs, target = 4) {
+	if (!(spanMs > 0)) return 1;
+	const rough = spanMs / target;
+	const mag = 10 ** Math.floor(Math.log10(rough));
+	const norm = rough / mag;
+	return (norm >= 5 ? 5 : norm >= 2 ? 2 : 1) * mag;
+}
+/** Intelligence's round-duration ticks, with the original 208px default. */
+function waterfallTicks(windowMs, widthPx = 208, minLabelGapPx = 64) {
+	if (!Number.isFinite(windowMs) || windowMs < 0 || !Number.isFinite(widthPx) || widthPx <= 0 || !Number.isFinite(minLabelGapPx) || minLabelGapPx <= 0) throw new RangeError("Waterfall axis requires finite, nonnegative time and positive dimensions");
+	if (windowMs === 0) return [];
+	const step = niceTickMs(windowMs, Math.max(2, Math.floor(widthPx / minLabelGapPx)));
+	const raw = [];
+	for (let t = 0; t <= windowMs + 1e-6; t += step) raw.push(t);
+	const minGapPct = minLabelGapPx / widthPx * 100;
+	const kept = [];
+	let lastPct = Number.NEGATIVE_INFINITY;
+	for (const t of raw) {
+		const pct = t / windowMs * 100;
+		if (kept.length === 0 || pct - lastPct >= minGapPct) {
+			kept.push(t);
+			lastPct = pct;
+		}
+	}
+	return kept;
+}
+function formatWaterfallDuration(ms) {
+	if (ms < 1e3) return `${Math.round(ms)}ms`;
+	if (ms < 6e4) return `${(ms / 1e3).toFixed(1)}s`;
+	if (ms < 36e5) return `${(ms / 6e4).toFixed(1)}m`;
+	return `${(ms / 36e5).toFixed(1)}h`;
+}
+const timingCell = {
+	width: "var(--waterfall-timing-width, 208px)",
+	flexShrink: 0
+};
+const rowStyle = {
+	display: "flex",
+	alignItems: "center",
+	gap: "0.5rem",
+	width: "100%",
+	minWidth: 0
+};
+const labelStyle = {
+	display: "flex",
+	alignItems: "center",
+	gap: "0.5rem",
+	flex: "1 1 0%",
+	minWidth: 0
+};
+const durationStyle = {
+	width: "var(--waterfall-duration-width, 4rem)",
+	flexShrink: 0,
+	textAlign: "right",
+	fontFamily: "var(--font-mono, monospace)",
+	fontVariantNumeric: "tabular-nums"
+};
+const ordered = (start, end) => Number.isFinite(start) && Number.isFinite(end) && end >= start;
+function WaterfallTimeAxis({ windowMs, originMs = 0, widthPx = 208, formatDuration = formatWaterfallDuration, className }) {
+	if (!ordered(0, windowMs) || !Number.isFinite(originMs)) return null;
+	const ticks = waterfallTicks(windowMs, widthPx);
+	if (windowMs === 0) return null;
+	return /* @__PURE__ */ jsx("div", {
+		className,
+		"data-waterfall-axis": "",
+		"aria-hidden": "true",
+		style: {
+			...timingCell,
+			position: "relative",
+			height: "var(--waterfall-axis-height, 1.5rem)"
+		},
+		children: ticks.map((t) => {
+			const pct = t / windowMs * 100;
+			return /* @__PURE__ */ jsxs("span", {
+				style: {
+					position: "absolute",
+					top: 0,
+					bottom: 0,
+					left: `${pct}%`,
+					display: "flex",
+					flexDirection: "column",
+					alignItems: "start"
+				},
+				children: [/* @__PURE__ */ jsx("span", { style: {
+					height: "0.5rem",
+					width: 1,
+					background: "var(--intel-chart-grid, var(--color-border, #d1d3e1))"
+				} }), /* @__PURE__ */ jsx("span", {
+					style: {
+						marginTop: "0.25rem",
+						whiteSpace: "nowrap",
+						fontFamily: "var(--font-mono, monospace)",
+						fontSize: "var(--waterfall-axis-font-size, 11px)",
+						lineHeight: 1,
+						fontVariantNumeric: "tabular-nums",
+						transform: pct > 75 ? "translateX(-100%)" : void 0
+					},
+					children: formatDuration(originMs + t)
+				})]
+			}, t);
+		})
+	});
+}
+function WaterfallBar({ startMs, endMs, window, tone = "default", formatDuration = formatWaterfallDuration, className }) {
+	if (!ordered(startMs, endMs) || !ordered(window.startMs, window.endMs)) return /* @__PURE__ */ jsx("span", {
+		className,
+		"data-waterfall-track": "",
+		"data-unavailable": "true",
+		title: "Timing unavailable",
+		style: {
+			...timingCell,
+			textAlign: "center"
+		},
+		children: "—"
+	});
+	const geometry = waterfallSpanGeometry(startMs, endMs, window);
+	const color = tone === "error" ? "var(--intel-waterfall-error, #dc2626)" : tone === "critical" ? "var(--intel-waterfall-critical, #0891b2)" : "var(--intel-waterfall-bar, #2563eb)";
+	return /* @__PURE__ */ jsx("span", {
+		className,
+		"data-waterfall-track": "",
+		"data-tone": tone,
+		title: `+${formatDuration(geometry.startOffsetMs)} · ${formatDuration(geometry.durationMs)}${tone === "critical" ? " · critical path" : ""}`,
+		style: {
+			...timingCell,
+			position: "relative",
+			height: "var(--waterfall-bar-height, 0.875rem)",
+			overflow: "hidden",
+			borderRadius: "var(--waterfall-bar-radius, 999px)",
+			background: "var(--intel-waterfall-track, rgb(148 163 184 / 22%))"
+		},
+		children: /* @__PURE__ */ jsx("span", {
+			"data-waterfall-bar": "",
+			"data-clipped": geometry.clipped || void 0,
+			style: {
+				position: "absolute",
+				top: 0,
+				height: "100%",
+				borderRadius: "inherit",
+				background: color,
+				left: `${geometry.offsetPct}%`,
+				width: `${geometry.widthPct}%`,
+				boxShadow: tone === "default" ? void 0 : `0 0 0 1px ${color}`
+			}
+		})
+	});
+}
+/** Non-interactive row body; its caller owns treeitems, buttons and selection. */
+function WaterfallRow({ label, attribution, startMs, endMs, window, tone, formatDuration = formatWaterfallDuration, className, timingClassName, durationClassName }) {
+	return /* @__PURE__ */ jsxs("span", {
+		"data-waterfall-row": "",
+		className,
+		style: rowStyle,
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"data-waterfall-label": "",
+				style: labelStyle,
+				children: label
+			}),
+			attribution,
+			/* @__PURE__ */ jsx(WaterfallBar, {
+				startMs,
+				endMs,
+				window,
+				tone,
+				formatDuration,
+				className: timingClassName
+			}),
+			/* @__PURE__ */ jsx("span", {
+				"data-waterfall-duration": "",
+				className: durationClassName,
+				style: durationStyle,
+				children: ordered(startMs, endMs) ? formatDuration(endMs - startMs) : "—"
+			})
+		]
+	});
+}
+function WaterfallHeader({ label = "Span", attribution, durationLabel = "Duration", ...axis }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-waterfall-header": "",
+		style: rowStyle,
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				style: labelStyle,
+				children: label
+			}),
+			attribution,
+			/* @__PURE__ */ jsx(WaterfallTimeAxis, { ...axis }),
+			/* @__PURE__ */ jsx("span", {
+				style: durationStyle,
+				children: durationLabel
+			})
+		]
+	});
+}
+//#endregion
+export { DEFAULT_SPARKLINE_EMPTY_LABEL, DEFAULT_SPARKLINE_HEIGHT, DEFAULT_SPARKLINE_LABEL, DEFAULT_SPARKLINE_UNAVAILABLE_LABEL, DEFAULT_SPARKLINE_WIDTH, Sparkline, StackedBarChart, WaterfallBar, WaterfallHeader, WaterfallRow, WaterfallTimeAxis, formatSparklineValue, formatWaterfallDuration, sparklineGeometry, sparklineLabel, sparklinePointsAttribute, sparklineReadings, waterfallSpanGeometry, waterfallTicks };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/charts",
-  "version": "0.2.0",
+  "version": "0.3.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",