nimbus-docs 0.1.7 → 0.1.8

package/dist/react.js

@@ -1,4 +1,4 @@
-import { Component, createContext, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useReducer, useRef, useState } from "react";
+import { Component, createContext, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useReducer, useRef, useState, useSyncExternalStore } from "react";
 import { clsx } from "clsx";
 import { twMerge } from "tailwind-merge";
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -30,8 +30,14 @@ var DiagramRegistry = class {
 			this.notify();
 		};
 	}
+	/**
+	* Pause everything when at least one diagram is unpaused; resume
+	* everything otherwise. A naive per-entry toggle would *invert* mixed
+	* states — resuming the diagrams a reader had deliberately paused.
+	*/
 	toggleAll() {
-		for (const entry of this.entries.values()) entry.toggle();
+		const anyUnpaused = [...this.entries.values()].some((e) => !e.userPaused());
+		for (const entry of this.entries.values()) entry.setPaused(anyUnpaused);
 	}
 	count = () => this.entries.size;
 	getVersion = () => this.version;
@@ -71,6 +77,10 @@ function reducer(state, event) {
 			...state,
 			userPaused: !state.userPaused
 		};
+		case "SET_PAUSED": return state.userPaused === event.paused ? state : {
+			...state,
+			userPaused: event.paused
+		};
 	}
 }
 function derivePhase(state, reducedMotionMode, pauseWhenOffscreen) {
@@ -260,7 +270,13 @@ function DiagramRoot(props) {
 		};
 	}, []);
 	const toggle = useCallback(() => dispatch({ type: "TOGGLE" }), []);
-	const reset = useCallback(() => setResetKey((k) => k + 1), []);
+	const reset = useCallback(() => {
+		setResetKey((k) => k + 1);
+		dispatch({
+			type: "SET_PAUSED",
+			paused: false
+		});
+	}, []);
 	const handleKeyDown = useCallback((event) => {
 		if (!keyboard) return;
 		if (isInteractiveTarget(event.target)) return;
@@ -276,12 +292,18 @@ function DiagramRoot(props) {
 		toggle,
 		reset
 	]);
+	const userPausedRef = useRef(state.userPaused);
+	userPausedRef.current = state.userPaused;
 	useEffect(() => {
 		return diagramRegistry.register({
 			id,
-			toggle
+			setPaused: (paused) => dispatch({
+				type: "SET_PAUSED",
+				paused
+			}),
+			userPaused: () => userPausedRef.current
 		});
-	}, [id, toggle]);
+	}, [id]);
 	const phase = derivePhase(state, reducedMotionMode, pauseWhenOffscreen);
 	const playing = phase === "playing";
 	const reducedMotionEffective = reducedMotionMode === "respect" ? state.reducedMotion : false;
@@ -324,7 +346,8 @@ function DiagramRoot(props) {
 			"data-tab-visible": String(state.tabVisible),
 			"data-reduced-motion": String(reducedMotionEffective),
 			"aria-label": label,
-			role: "region",
+			role: label ? "region" : void 0,
+			tabIndex: keyboard ? 0 : void 0,
 			onKeyDown: handleKeyDown,
 			className: cn("flex flex-col", className),
 			children: [/* @__PURE__ */ jsx("span", {
@@ -349,14 +372,27 @@ const Diagram = DiagramRoot;
 * automatically when any gate fails.
 *
 * Steps may carry a `when(ctx)` predicate that filters them out for a
-* given cycle. Mode toggles, branches, alternating loops — anything
-* cycle-dependent — composes via the predicate plus user-supplied
-* `context`.
+* given cycle, and a `data` payload surfaced while the step holds. Mode
+* toggles, branches, alternating loops — anything cycle-dependent —
+* composes via the predicate plus user-supplied `context`.
+*
+* Two run modes:
+* - `autoplay: true` (default) — ambient looping animation. Freezes under
+*   reduced motion (`data` reads `null`).
+* - `autoplay: false` — idle until `start()`. Started runs are
+*   user-initiated *function*, not decoration: they keep advancing under
+*   reduced motion (gate your CSS transition durations card-side), and a
+*   `start()` while the page is paused arms as soon as play resumes.
+*
+* The scheduler depends on the current step's *values* (id, hold), not
+* on `steps` / `context` identity — inline literals are safe and won't
+* re-arm the hold timer under frequent re-renders.
 */
-function usePhase({ steps, context, loop = true }) {
+function usePhase({ steps, context, loop = true, autoplay = true }) {
 	const ctx = useDiagramOrDefault("usePhase");
 	const [cycle, setCycle] = useState(0);
 	const [index, setIndex] = useState(0);
+	const [running, setRunning] = useState(autoplay);
 	const sequence = useMemo(() => {
 		const seq = [];
 		let prev = "";
@@ -379,53 +415,77 @@ function usePhase({ steps, context, loop = true }) {
 		steps
 	]);
 	const currentStep = sequence[index] ?? sequence[sequence.length - 1] ?? null;
-	const currentId = currentStep?.id ?? "";
+	const currentId = running ? currentStep?.id ?? "" : "";
+	const currentHold = currentStep?.hold ?? null;
+	const advanceRef = useRef(() => {});
+	const sequenceRef = useRef(sequence);
+	const runningRef = useRef(running);
 	useEffect(() => {
-		if (!ctx.playing) return;
-		if (ctx.reducedMotion) return;
-		if (!currentStep || sequence.length === 0) return;
-		const t = setTimeout(() => {
+		advanceRef.current = () => {
 			if (index + 1 >= sequence.length) {
 				if (loop) {
 					setCycle((c) => c + 1);
 					setIndex(0);
+				} else if (!autoplay) {
+					setCycle((c) => c + 1);
+					setIndex(0);
+					setRunning(false);
 				}
 			} else setIndex((i) => i + 1);
-		}, currentStep.hold);
+		};
+		sequenceRef.current = sequence;
+		runningRef.current = running;
+	});
+	const hasSteps = steps.length > 0;
+	useEffect(() => {
+		if (!running) return;
+		if (!ctx.playing) return;
+		if (ctx.reducedMotion && autoplay) return;
+		if (currentHold === null) {
+			if (!hasSteps) return;
+			const t = setTimeout(() => advanceRef.current(), 0);
+			return () => clearTimeout(t);
+		}
+		const t = setTimeout(() => advanceRef.current(), currentHold);
 		return () => clearTimeout(t);
 	}, [
 		index,
 		cycle,
+		running,
+		autoplay,
 		ctx.playing,
 		ctx.reducedMotion,
-		currentStep,
-		sequence.length,
-		loop
+		currentId,
+		currentHold,
+		hasSteps
 	]);
+	const start = useCallback(() => {
+		if (runningRef.current) return;
+		setIndex(0);
+		setRunning(true);
+	}, []);
+	const advance = useCallback(() => advanceRef.current(), []);
+	const goto = useCallback((id) => {
+		const i = sequenceRef.current.findIndex((s) => s.id === id);
+		if (i < 0) return;
+		setIndex(i);
+		setRunning(true);
+	}, []);
+	const reset = useCallback(() => {
+		setCycle(0);
+		setIndex(0);
+		setRunning(autoplay);
+	}, [autoplay]);
 	return {
 		current: currentId,
 		index,
 		cycle,
-		advance: useCallback(() => {
-			if (index + 1 >= sequence.length) {
-				if (loop) {
-					setCycle((c) => c + 1);
-					setIndex(0);
-				}
-			} else setIndex((i) => i + 1);
-		}, [
-			index,
-			sequence.length,
-			loop
-		]),
-		goto: useCallback((id) => {
-			const i = sequence.findIndex((s) => s.id === id);
-			if (i >= 0) setIndex(i);
-		}, [sequence]),
-		reset: useCallback(() => {
-			setCycle(0);
-			setIndex(0);
-		}, [])
+		data: running && currentStep && !(ctx.reducedMotion && autoplay) ? currentStep.data ?? null : null,
+		running,
+		start,
+		advance,
+		goto,
+		reset
 	};
 }
 
@@ -434,8 +494,7 @@ function usePhase({ steps, context, loop = true }) {
 /**
 * DOM rect + optional selector callback. The selector receives the
 * observed element and its rect, and returns whatever derived geometry
-* the author needs (NodeRect, EdgeData, etc.). Subsumes momito's
-* `useWeldedMeasure` pattern.
+* the author needs (NodeRect, EdgeData, etc.).
 *
 * For multi-element measurements (e.g. measuring a container plus 5
 * child nodes), pass the container ref and read the other refs from
@@ -452,9 +511,9 @@ function useMeasure(ref, selector, options = {}) {
 	const selectorRef = useRef(selector);
 	selectorRef.current = selector;
 	const sampleRef = useRef(() => {});
-	useLayoutEffect(() => {
-		const el = ref.current;
-		if (!el) return;
+	const boundElRef = useRef(null);
+	const unbindRef = useRef(null);
+	const bind = (el) => {
 		const sample = (r) => {
 			setRect(r);
 			const s = selectorRef.current;
@@ -463,18 +522,39 @@ function useMeasure(ref, selector, options = {}) {
 		sampleRef.current = () => {
 			sample(el.getBoundingClientRect());
 		};
+		let cancelled = false;
+		el.ownerDocument.fonts?.ready.then(() => {
+			if (!cancelled) sampleRef.current();
+		});
 		const win = el.ownerDocument.defaultView ?? window;
 		if (typeof win.ResizeObserver === "undefined") {
 			sampleRef.current();
-			return;
+			return () => {
+				cancelled = true;
+			};
 		}
-		const ro = new win.ResizeObserver((entries) => {
-			for (const entry of entries) sample(entry.contentRect);
+		const ro = new win.ResizeObserver(() => {
+			sample(el.getBoundingClientRect());
 		});
 		ro.observe(el);
 		sampleRef.current();
-		return () => ro.disconnect();
-	}, [ref]);
+		return () => {
+			cancelled = true;
+			ro.disconnect();
+		};
+	};
+	useLayoutEffect(() => {
+		const el = ref.current;
+		if (el === boundElRef.current) return;
+		unbindRef.current?.();
+		boundElRef.current = el;
+		unbindRef.current = el ? bind(el) : null;
+	});
+	useLayoutEffect(() => () => {
+		unbindRef.current?.();
+		unbindRef.current = null;
+		boundElRef.current = null;
+	}, []);
 	useLayoutEffect(() => {
 		sampleRef.current();
 	}, deps);
@@ -538,5 +618,165 @@ function useTabIndicator(containerRef, getTab, activeId) {
 }
 
 //#endregion
-export { Diagram, cn, diagramRegistry, useDiagram, useDiagramOrDefault, useMeasure, usePhase, useTabIndicator };
+//#region src/react/hooks/use-ref-setters.ts
+/**
+* Stable per-id ref callbacks for a refs map — the ergonomic half of the
+* "refs map + setter factory" pattern. Instead of N individual `useRef`s
+* and N inline `ref={(el) => …}` arrows (which churn refs every render),
+* keep one map and hand each element a cached callback:
+*
+* ```tsx
+* const nodeRefs = useRef<Partial<Record<NodeId, HTMLDivElement | null>>>({});
+* const setNode = useRefSetters(nodeRefs);
+*
+* <div ref={setNode("prompt")}>Prompt</div>
+* <div ref={setNode("model")}>Model</div>
+* ```
+*
+* Measurement stays caller-side (read `refs.current` inside a `useMeasure`
+* selector) — this hook owns only the ref plumbing.
+*/
+function useRefSetters(refs) {
+	const cache = useRef(/* @__PURE__ */ new Map());
+	return (id) => {
+		let cb = cache.current.get(id);
+		if (!cb) {
+			cb = (el) => {
+				refs.current[id] = el;
+			};
+			cache.current.set(id, cb);
+		}
+		return cb;
+	};
+}
+
+//#endregion
+//#region src/react/hooks/use-media-query.ts
+/**
+* Reactive `window.matchMedia` subscription, SSR-safe.
+*
+* The server snapshot returns `defaultValue` (default `false`), so static
+* builds render the no-match branch and hydrate without mismatch warnings;
+* the first client render corrects it if the query matches.
+*
+* ```ts
+* const isMobile = useMediaQuery("(max-width: 640px)");
+* ```
+*/
+function useMediaQuery(query, defaultValue = false) {
+	return useSyncExternalStore(useCallback((onChange) => {
+		const mq = window.matchMedia(query);
+		mq.addEventListener("change", onChange);
+		return () => mq.removeEventListener("change", onChange);
+	}, [query]), () => window.matchMedia(query).matches, () => defaultValue);
+}
+
+//#endregion
+//#region src/react/geometry.ts
+/** Anchor point on a rect edge. `frac` runs 0→1 from top/left. */
+function edgePoint(rect, side, frac = .5) {
+	if (side === "top") return {
+		x: rect.l + rect.w * frac,
+		y: rect.t
+	};
+	if (side === "bottom") return {
+		x: rect.l + rect.w * frac,
+		y: rect.t + rect.h
+	};
+	if (side === "left") return {
+		x: rect.l,
+		y: rect.t + rect.h * frac
+	};
+	return {
+		x: rect.l + rect.w,
+		y: rect.t + rect.h * frac
+	};
+}
+function straightPath(from, to, arrowOffset) {
+	const dx = Math.abs(to.x - from.x);
+	if (Math.abs(to.y - from.y) < 2) {
+		const dir = to.x > from.x ? 1 : -1;
+		return `M ${from.x},${from.y} L ${to.x - dir * arrowOffset},${to.y}`;
+	}
+	if (dx < 2) {
+		const dir = to.y > from.y ? 1 : -1;
+		return `M ${from.x},${from.y} L ${to.x},${to.y - dir * arrowOffset}`;
+	}
+	return `M ${from.x},${from.y} L ${to.x},${to.y}`;
+}
+function elbowPath(from, to, r, arrowOffset) {
+	const dx = to.x - from.x;
+	const dy = to.y - from.y;
+	const corner = Math.abs(dx) > Math.abs(dy) ? {
+		x: to.x,
+		y: from.y
+	} : {
+		x: from.x,
+		y: to.y
+	};
+	const dx1 = Math.sign(corner.x - from.x);
+	const dy1 = Math.sign(corner.y - from.y);
+	const dx2 = Math.sign(to.x - corner.x);
+	const dy2 = Math.sign(to.y - corner.y);
+	const seg1Len = Math.abs(corner.x - from.x) + Math.abs(corner.y - from.y);
+	const seg2Len = Math.abs(to.x - corner.x) + Math.abs(to.y - corner.y);
+	const rr = Math.max(2, Math.min(r, seg1Len / 2, seg2Len / 2));
+	const preX = corner.x - dx1 * rr;
+	const preY = corner.y - dy1 * rr;
+	const postX = corner.x + dx2 * rr;
+	const postY = corner.y + dy2 * rr;
+	const endX = to.x - dx2 * arrowOffset;
+	const endY = to.y - dy2 * arrowOffset;
+	return `M ${from.x},${from.y} L ${preX},${preY} Q ${corner.x},${corner.y} ${postX},${postY} L ${endX},${endY}`;
+}
+function vSplitPath(from, to, r) {
+	if (Math.abs(from.x - to.x) < 1) return `M ${from.x},${from.y} L ${to.x},${to.y}`;
+	const midY = (from.y + to.y) / 2;
+	const sx = Math.sign(to.x - from.x);
+	const sy1 = Math.sign(midY - from.y);
+	const sy2 = Math.sign(to.y - midY);
+	const rr = Math.min(r, Math.abs(midY - from.y), Math.abs(to.x - from.x) / 2, Math.abs(to.y - midY));
+	return [
+		`M ${from.x},${from.y}`,
+		`L ${from.x},${midY - rr * sy1}`,
+		`Q ${from.x},${midY} ${from.x + rr * sx},${midY}`,
+		`L ${to.x - rr * sx},${midY}`,
+		`Q ${to.x},${midY} ${to.x},${midY + rr * sy2}`,
+		`L ${to.x},${to.y}`
+	].join(" ");
+}
+/** Build an SVG path string between two points using the given route. */
+function routeEdge(from, to, route = "auto", options = {}) {
+	const arrowOffset = options.arrowOffset ?? 6;
+	if (route === "vSplit") return vSplitPath(from, to, options.radius ?? 6);
+	if (route === "straight") return straightPath(from, to, arrowOffset);
+	if (route === "elbow") return elbowPath(from, to, options.radius ?? 10, arrowOffset);
+	return Math.abs(from.x - to.x) < 2 || Math.abs(from.y - to.y) < 2 ? straightPath(from, to, arrowOffset) : elbowPath(from, to, options.radius ?? 10, arrowOffset);
+}
+/**
+* Resolve declarative edge specs against a map of measured rects.
+* Specs whose endpoints aren't in `rects` yet (unmounted nodes,
+* first-paint gaps) are skipped rather than rendered degenerate.
+*/
+function resolveEdges(specs, rects, options = {}) {
+	const out = [];
+	for (const spec of specs) {
+		const fromRect = rects[spec.from[0]];
+		const toRect = rects[spec.to[0]];
+		if (!fromRect || !toRect) continue;
+		const from = edgePoint(fromRect, spec.from[1], spec.from[2] ?? .5);
+		const to = edgePoint(toRect, spec.to[1], spec.to[2] ?? .5);
+		out.push({
+			id: spec.id,
+			from,
+			to,
+			d: routeEdge(from, to, spec.route ?? "auto", options),
+			ghost: spec.ghost
+		});
+	}
+	return out;
+}
+
+//#endregion
+export { Diagram, cn, diagramRegistry, edgePoint, resolveEdges, routeEdge, useDiagram, useDiagramOrDefault, useMeasure, useMediaQuery, usePhase, useRefSetters, useTabIndicator };
 //# sourceMappingURL=react.js.map