@statelyai/flow-react 0.9.4 → 0.9.6

package/README.md

@@ -17,7 +17,7 @@ The React package owns React lifecycle, context, selector subscriptions, and a c
 
 <!-- transient entity rendering split between src/StatelyFlow.tsx and flow-dom src/entity-geometry.ts -->
 
-Optimization is part of the architecture, not a later cleanup pass. Components subscribe only to durable content and interaction state. During drag and animated layout sessions, `@statelyai/flow-dom` batches node rectangles, edge paths, endpoint handles, label positions, and multi-selection bounds into imperative animation-frame writes, so React commits only at transient-session boundaries. Default edge paths expose `data-flow-edge-segment`; custom edge renderers can use the same indexed attribute to join the imperative path updates. Router-provided `PathData.svgPath` geometry is honored by both initial React rendering and those imperative updates.
+Optimization is part of the architecture, not a later cleanup pass. Components subscribe only to durable content and interaction state. During drag and animated layout sessions, `@statelyai/flow-dom` batches node rectangles, default group child-area and header rectangles, edge paths, endpoint handles, label positions, and multi-selection bounds into imperative animation-frame writes, so React commits only at transient-session boundaries. Default group headers keep projected styles on a separate element from imperative geometry, preserving projected transforms during drag. Default edge paths expose `data-flow-edge-segment`; custom edge renderers can use the same indexed attribute to join the imperative path updates. Existing custom paths whose `d` exactly matches a routed segment are also bound automatically, including duplicate hit strokes; unrelated decoration paths are left alone. Router-provided `PathData.svgPath` geometry is honored by both initial React rendering and those imperative updates.
 
 The graph data structure is the source of truth for graph content, not for transient UI state. Core node and edge data should not grow flags like `selected: true` or `dragging: true`; selection, focus, dragging, hover, connection state, and similar interaction state live in the flow store and are derived into render props such as `selected` or `dragging`.
 

package/dist/esm/index.d.ts

@@ -341,10 +341,8 @@ type MiniMapProps = {
   renderNode?: (node: FlowNode, rect: Rect) => ReactNode;
 };
 /**
- * Overview map. Deliberately thin: all math lives in core
- * (`getMinimapProjection`, `viewportCenteredOn`) and every interaction is a
- * controller viewport command — this component is exactly what you would write in
- * userland, kept here as a convenience.
+ * Overview map. Projection and navigation math live in core; this adapter owns
+ * only React rendering and the browser pointer session.
  */
 declare function MiniMap(props: MiniMapProps): import("react").JSX.Element;
 //#endregion

package/dist/esm/index.js

@@ -1,8 +1,8 @@
 import { a as FlowInstanceProvider, i as LinesBackground, n as CrossBackground, o as useFlowInstance, r as DotsBackground, s as useOptionalFlowInstance, t as Background } from "./backgrounds2.js";
 import { applyFlowColorMode, attachContainer, attachInput, attachViewportTransform, clientToCanvas, computeRenderableIds, createEntityGeometryObserver, createFlowView, createMeasurementObserver, nodePositionStyle, renderableIdsEqual, resolveFlowColorMode, viewportStyle } from "@statelyai/flow-dom";
-import { CONNECTION_PREVIEW_EDGE_ID, areNodesMeasured, createConnectionPreviewGraph, createEntityChangeNotifier, createFlow, createFlowInputRuntime, getAnchorTransform, getAutoPanDelta, getMinimapProjection, getProjectedEdgeAttrs, getProjectedNodeAttrs, getToolbarPlacement, markerToSVG, pathToSVG, profileModesForContext, profilePoliciesForContext, viewportCenteredOn } from "@statelyai/flow";
-import { createContext, memo, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { CONNECTION_PREVIEW_EDGE_ID, areNodesMeasured, createConnectionPreviewGraph, createEntityChangeNotifier, createFlow, createFlowInputRuntime, getAnchorTransform, getAutoPanDelta, getMinimapProjection, getMinimapViewportCenter, getProjectedEdgeAttrs, getProjectedNodeAttrs, getToolbarPlacement, getVisibleBounds, markerToSVG, pathToSVG, profileModesForContext, profilePoliciesForContext, viewportCenteredOn } from "@statelyai/flow";
+import { Fragment, createContext, memo, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector";
 import { createPortal } from "react-dom";
 export * from "@statelyai/flow-dom";
@@ -323,7 +323,7 @@ function useFlowInput(flow, containerRef, options = {}) {
 			store: flow.internals.store,
 			runtime,
 			keyboardTarget,
-			autoPan: (context, screenPoint) => getAutoPanDelta(context, screenPoint, flow.internals.engine)
+			autoPan: getAutoPanDelta
 		});
 	}, [
 		flow,
@@ -1114,7 +1114,7 @@ function ConnectionPreviewEdge(props) {
 	});
 }
 function DefaultEdge(props) {
-	return /* @__PURE__ */ jsxs(Fragment, { children: [props.pathData.segments.map((segment, index) => {
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [props.pathData.segments.map((segment, index) => {
 		const d = pathToSVG(segment);
 		return /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("path", {
 			d,
@@ -1190,7 +1190,7 @@ function DefaultMarkerDefinitions(props) {
 	] });
 }
 function EdgeHitTarget(props) {
-	return /* @__PURE__ */ jsx(Fragment, { children: props.pathData.segments.map((segment, index) => {
+	return /* @__PURE__ */ jsx(Fragment$1, { children: props.pathData.segments.map((segment, index) => {
 		return /* @__PURE__ */ jsx("path", {
 			d: pathToSVG(segment),
 			"data-flow-edge-segment": index,
@@ -1211,7 +1211,7 @@ function EdgeEndpointHandles(props) {
 	if (!first || !last) return null;
 	const radius = 6 / props.flow.getContext().viewport.zoom;
 	const strokeWidth = 2 / props.flow.getContext().viewport.zoom;
-	return /* @__PURE__ */ jsx(Fragment, { children: [{
+	return /* @__PURE__ */ jsx(Fragment$1, { children: [{
 		end: "source",
 		point: first,
 		cursor: "crosshair"
@@ -1588,6 +1588,7 @@ const NodeView = memo(function NodeView(props) {
 					highlights
 				})
 			}) : node.group ? /* @__PURE__ */ jsx(DefaultGroupNode, {
+				geometryObserver: props.geometryObserver,
 				flow: props.flow,
 				node,
 				bounds,
@@ -1615,51 +1616,92 @@ const NodeView = memo(function NodeView(props) {
 * `engine.getGroupGeometry`; custom renderers can do the same.
 */
 function DefaultGroupNode(props) {
+	const childAreaRef = useRef(null);
+	const contentRef = useRef(null);
+	useLayoutEffect(() => {
+		const observePart = (element, part) => {
+			if (!element) return () => {};
+			return props.geometryObserver.observeRect(element, {
+				id: props.node.id,
+				getRect: () => {
+					const geometry = props.flow.internals.engine.getGroupGeometry(props.node.id);
+					const bounds = props.flow.internals.engine.visualBounds(props.node.id);
+					if (!geometry || !bounds) return null;
+					return {
+						...geometry[part],
+						x: geometry[part].x - bounds.x,
+						y: geometry[part].y - bounds.y
+					};
+				}
+			});
+		};
+		const stopChildArea = observePart(childAreaRef.current, "childArea");
+		const stopContent = observePart(contentRef.current, "contentBounds");
+		return () => {
+			stopChildArea();
+			stopContent();
+		};
+	}, [
+		props.flow,
+		props.geometryObserver,
+		props.node.id
+	]);
 	const geometry = props.flow.internals.engine.getGroupGeometry(props.node.id);
 	const label = props.node.data?.label;
 	const badges = decorationsToArray(props.attrs.badge);
 	const title = decorationTitle(props.attrs.tooltip);
 	if (!geometry) return /* @__PURE__ */ jsx(DefaultNode, { ...props });
 	const relative = (rect) => ({
-		left: rect.x - props.bounds.x,
-		top: rect.y - props.bounds.y,
+		left: 0,
+		top: 0,
+		transform: `translate(${rect.x - props.bounds.x}px, ${rect.y - props.bounds.y}px)`,
 		width: rect.width,
 		height: rect.height
 	});
 	const dropTarget = props.highlights.some((entry) => entry.kind === "drop-target");
-	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("div", { style: {
-		position: "absolute",
-		...relative(geometry.childArea),
-		boxSizing: "border-box",
-		border: `2px dashed ${dropTarget ? "#16a34a" : props.selected ? "#93c5fd" : props.attrs.color ?? "#cbd5e1"}`,
-		...dropTarget ? { background: "rgba(22, 163, 74, 0.08)" } : null,
-		borderRadius: 10,
-		background: "rgba(148, 163, 184, 0.07)",
-		pointerEvents: "none"
-	} }), /* @__PURE__ */ jsxs("div", {
-		"data-flow-drag-handle": true,
-		title,
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("div", {
+		ref: childAreaRef,
 		style: {
 			position: "absolute",
-			...relative(geometry.contentBounds),
+			...relative(geometry.childArea),
 			boxSizing: "border-box",
-			display: "flex",
-			alignItems: "center",
-			padding: "0 12px",
-			border: `2px solid ${props.selected ? "#2563eb" : props.attrs.color ?? "#94a3b8"}`,
-			borderRadius: 8,
-			background: props.selected ? "#eff6ff" : "#f8fafc",
-			color: "#0f172a",
-			font: "600 13px/1.2 system-ui, sans-serif",
-			cursor: props.dragging ? "grabbing" : "grab",
-			pointerEvents: "auto",
-			userSelect: "none",
-			...props.attrs.style
+			border: `2px dashed ${dropTarget ? "#16a34a" : props.selected ? "#93c5fd" : props.attrs.color ?? "#cbd5e1"}`,
+			...dropTarget ? { background: "rgba(22, 163, 74, 0.08)" } : null,
+			borderRadius: 10,
+			background: "rgba(148, 163, 184, 0.07)",
+			pointerEvents: "none"
+		}
+	}), /* @__PURE__ */ jsx("div", {
+		ref: contentRef,
+		style: {
+			position: "absolute",
+			...relative(geometry.contentBounds)
 		},
-		children: [/* @__PURE__ */ jsx("span", { children: String(label ?? props.node.id) }), badges.length ? /* @__PURE__ */ jsx("span", {
-			style: defaultBadgeListStyle,
-			children: badges
-		}) : null]
+		children: /* @__PURE__ */ jsxs("div", {
+			"data-flow-drag-handle": true,
+			title,
+			style: {
+				width: "100%",
+				height: "100%",
+				boxSizing: "border-box",
+				display: "flex",
+				alignItems: "center",
+				padding: "0 12px",
+				border: `2px solid ${props.selected ? "#2563eb" : props.attrs.color ?? "#94a3b8"}`,
+				borderRadius: 8,
+				background: props.selected ? "#eff6ff" : "#f8fafc",
+				color: "#0f172a",
+				font: "600 13px/1.2 system-ui, sans-serif",
+				cursor: props.dragging ? "grabbing" : "grab",
+				pointerEvents: "auto",
+				userSelect: "none",
+				...props.attrs.style
+			},
+			children: [/* @__PURE__ */ jsx("span", { children: String(label ?? props.node.id) }), badges.length ? /* @__PURE__ */ jsx("span", {
+				style: defaultBadgeListStyle,
+				children: badges
+			}) : null]
+		})
 	})] });
 }
 function DefaultNode(props) {
@@ -1812,35 +1854,115 @@ function FlowToolbar(props) {
 }
 //#endregion
 //#region src/MiniMap.tsx
+const DRAG_JITTER_THRESHOLD_SQ = 4;
+function containsPoint(rect, point) {
+	return point.x >= rect.x && point.x <= rect.x + rect.width && point.y >= rect.y && point.y <= rect.y + rect.height;
+}
+function setRect(element, rect) {
+	if (!element) return;
+	element.setAttribute("x", String(rect.x));
+	element.setAttribute("y", String(rect.y));
+	element.setAttribute("width", String(rect.width));
+	element.setAttribute("height", String(rect.height));
+}
+function projectionTransform(from, to) {
+	const scale = to.scale / from.scale;
+	const fromOrigin = from.toMinimap({
+		x: 0,
+		y: 0
+	});
+	const toOrigin = to.toMinimap({
+		x: 0,
+		y: 0
+	});
+	return `translate(${toOrigin.x - fromOrigin.x * scale} ${toOrigin.y - fromOrigin.y * scale}) scale(${scale})`;
+}
 /**
-* Overview map. Deliberately thin: all math lives in core
-* (`getMinimapProjection`, `viewportCenteredOn`) and every interaction is a
-* controller viewport command — this component is exactly what you would write in
-* userland, kept here as a convenience.
+* Overview map. Projection and navigation math live in core; this adapter owns
+* only React rendering and the browser pointer session.
 */
 function MiniMap(props) {
 	const flow = useFlowInstance();
 	const width = props.width ?? 200;
 	const height = props.height ?? 140;
 	const nodes = useFlowSelector((context) => context.graph.nodes);
-	const viewport = useFlowSelector((context) => context.viewport);
+	const measurements = useFlowSelector((context) => context.measurements);
 	const viewportSize = useFlowSelector((context) => context.viewportSize);
-	const draggingRef = useRef(false);
-	const projection = getMinimapProjection({
-		contentBounds: flow.getGraphBounds(),
-		viewport,
+	const markerGroupRef = useRef(null);
+	const viewportRectRef = useRef(null);
+	const sessionRef = useRef(null);
+	const endSessionRef = useRef(null);
+	const paintViewportRef = useRef(() => {});
+	const contentBounds = useMemo(() => {
+		return flow.getGraphBounds();
+	}, [
+		flow,
+		nodes,
+		measurements
+	]);
+	const nodeBounds = useMemo(() => {
+		return nodes.map((node) => flow.internals.engine.visualBounds(node.id));
+	}, [
+		flow,
+		nodes,
+		measurements
+	]);
+	const baseProjection = useMemo(() => getMinimapProjection({
+		contentBounds,
+		viewport: flow.getSnapshot().viewport,
 		viewportSize,
 		width,
 		height,
 		padding: props.padding
-	});
-	const jumpTo = (event) => {
+	}), [
+		contentBounds,
+		flow,
+		height,
+		props.padding,
+		viewportSize,
+		width
+	]);
+	const projectedNodes = useMemo(() => nodeBounds.map((bounds) => baseProjection.rectToMinimap(bounds)), [baseProjection, nodeBounds]);
+	const initialViewport = flow.getSnapshot().viewport;
+	const viewportRect = baseProjection.rectToMinimap(getVisibleBounds(initialViewport, viewportSize));
+	paintViewportRef.current = (nextViewport) => {
+		const projection = sessionRef.current?.projection ?? getMinimapProjection({
+			contentBounds,
+			viewport: nextViewport,
+			viewportSize,
+			width,
+			height,
+			padding: props.padding
+		});
+		markerGroupRef.current?.setAttribute("transform", projectionTransform(baseProjection, projection));
+		setRect(viewportRectRef.current, projection.rectToMinimap(getVisibleBounds(nextViewport, viewportSize)));
+	};
+	useLayoutEffect(() => {
+		paintViewportRef.current(flow.getSnapshot().viewport);
+	}, [
+		baseProjection,
+		flow,
+		nodeBounds
+	]);
+	useEffect(() => flow.listen((context) => context.viewport, (nextViewport) => paintViewportRef.current(nextViewport)), [flow]);
+	useEffect(() => () => endSessionRef.current?.(), []);
+	const pointFromEvent = (event, activeProjection) => {
 		const rect = event.currentTarget.getBoundingClientRect();
-		const canvasPoint = projection.toCanvas({
+		return activeProjection.toCanvas({
 			x: event.clientX - rect.left,
 			y: event.clientY - rect.top
 		});
-		flow.viewport.set(viewportCenteredOn(canvasPoint, viewportSize, viewport.zoom));
+	};
+	const navigate = (event, session) => {
+		const viewport = flow.getSnapshot().viewport;
+		const visibleBounds = getVisibleBounds(viewport, viewportSize);
+		const center = getMinimapViewportCenter({
+			point: pointFromEvent(event, session.projection),
+			grabOffset: session.grabOffset,
+			contentBounds,
+			viewportBounds: visibleBounds
+		});
+		flow.viewport.set(viewportCenteredOn(center, viewportSize, viewport.zoom));
 	};
 	return /* @__PURE__ */ jsxs("svg", {
 		"aria-label": "minimap",
@@ -1848,19 +1970,84 @@ function MiniMap(props) {
 		height,
 		className: props.className,
 		onPointerDown: (event) => {
-			draggingRef.current = true;
-			jumpTo(event);
+			if (event.button !== 0 || nodes.length === 0) return;
+			endSessionRef.current?.();
+			const viewport = flow.getSnapshot().viewport;
+			const currentProjection = getMinimapProjection({
+				contentBounds,
+				viewport,
+				viewportSize,
+				width,
+				height,
+				padding: props.padding
+			});
+			const pointerPoint = pointFromEvent(event, currentProjection);
+			const visibleBounds = getVisibleBounds(viewport, viewportSize);
+			const viewportCenter = {
+				x: visibleBounds.x + visibleBounds.width / 2,
+				y: visibleBounds.y + visibleBounds.height / 2
+			};
+			const grabbedLens = containsPoint(visibleBounds, pointerPoint);
+			const session = {
+				pointerId: event.pointerId,
+				originClient: {
+					x: event.clientX,
+					y: event.clientY
+				},
+				grabOffset: grabbedLens ? {
+					x: pointerPoint.x - viewportCenter.x,
+					y: pointerPoint.y - viewportCenter.y
+				} : {
+					x: 0,
+					y: 0
+				},
+				projection: currentProjection
+			};
+			sessionRef.current = session;
+			const element = event.currentTarget;
+			const body = element.ownerDocument.body;
+			const finish = (pointerId) => {
+				if (pointerId !== void 0 && pointerId !== session.pointerId) return;
+				if (sessionRef.current?.pointerId !== session.pointerId) return;
+				sessionRef.current = null;
+				endSessionRef.current = null;
+				body.removeEventListener("pointerup", onPointerEnd);
+				body.removeEventListener("pointercancel", onPointerEnd);
+				body.removeEventListener("contextmenu", onContextMenu, true);
+				try {
+					if (element.hasPointerCapture?.(session.pointerId)) element.releasePointerCapture(session.pointerId);
+				} catch {}
+				paintViewportRef.current(flow.getSnapshot().viewport);
+			};
+			const onPointerEnd = (pointerEvent) => finish(pointerEvent.pointerId);
+			const onContextMenu = () => finish();
+			endSessionRef.current = () => finish();
+			body.addEventListener("pointerup", onPointerEnd);
+			body.addEventListener("pointercancel", onPointerEnd);
+			body.addEventListener("contextmenu", onContextMenu, true);
 			try {
-				event.currentTarget.setPointerCapture(event.pointerId);
+				element.setPointerCapture(event.pointerId);
 			} catch {}
+			if (!grabbedLens) navigate(event, session);
 		},
 		onPointerMove: (event) => {
-			if (draggingRef.current) jumpTo(event);
+			const session = sessionRef.current;
+			if (!session || event.pointerId !== session.pointerId) return;
+			const dx = event.clientX - session.originClient.x;
+			const dy = event.clientY - session.originClient.y;
+			if (dx * dx + dy * dy <= DRAG_JITTER_THRESHOLD_SQ) return;
+			navigate(event, session);
 		},
 		onPointerUp: (event) => {
-			draggingRef.current = false;
-			if (event.currentTarget.hasPointerCapture(event.pointerId)) event.currentTarget.releasePointerCapture(event.pointerId);
+			if (sessionRef.current?.pointerId === event.pointerId) endSessionRef.current?.();
 		},
+		onPointerCancel: (event) => {
+			if (sessionRef.current?.pointerId === event.pointerId) endSessionRef.current?.();
+		},
+		onLostPointerCapture: (event) => {
+			if (sessionRef.current?.pointerId === event.pointerId) endSessionRef.current?.();
+		},
+		onContextMenu: () => endSessionRef.current?.(),
 		style: {
 			position: "absolute",
 			right: 12,
@@ -1873,21 +2060,27 @@ function MiniMap(props) {
 			pointerEvents: "auto",
 			...props.style
 		},
-		children: [nodes.map((node) => {
-			const rect = projection.rectToMinimap(flow.internals.engine.visualBounds(node.id));
-			return props.renderNode?.(node, rect) ?? /* @__PURE__ */ jsx("rect", {
-				x: rect.x,
-				y: rect.y,
-				width: Math.max(rect.width, 1),
-				height: Math.max(rect.height, 1),
-				rx: 1,
-				fill: "#94a3b8"
-			}, node.id);
+		children: [/* @__PURE__ */ jsx("g", {
+			ref: markerGroupRef,
+			children: nodes.map((node, index) => {
+				const rect = projectedNodes[index];
+				return /* @__PURE__ */ jsx(Fragment, { children: props.renderNode?.(node, rect) ?? /* @__PURE__ */ jsx("rect", {
+					"data-flow-minimap-node": node.id,
+					x: rect.x,
+					y: rect.y,
+					width: Math.max(rect.width, 1),
+					height: Math.max(rect.height, 1),
+					rx: 1,
+					fill: "#94a3b8"
+				}) }, node.id);
+			})
 		}), /* @__PURE__ */ jsx("rect", {
-			x: projection.viewportRect.x,
-			y: projection.viewportRect.y,
-			width: projection.viewportRect.width,
-			height: projection.viewportRect.height,
+			ref: viewportRectRef,
+			"data-flow-minimap-viewport": "",
+			x: viewportRect.x,
+			y: viewportRect.y,
+			width: viewportRect.width,
+			height: viewportRect.height,
 			fill: "rgba(37, 99, 235, 0.08)",
 			stroke: "#2563eb",
 			strokeWidth: 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/flow-react",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "Thin React adapter for @statelyai/flow with core and DOM re-exports.",
   "type": "module",
   "sideEffects": false,
@@ -34,8 +34,8 @@
   "license": "MIT",
   "dependencies": {
     "use-sync-external-store": "^1.6.0",
-    "@statelyai/flow": "0.9.1",
-    "@statelyai/flow-dom": "3.4.4"
+    "@statelyai/flow": "0.11.0",
+    "@statelyai/flow-dom": "3.4.6"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",
@@ -45,6 +45,7 @@
     "@dagrejs/dagre": "^3.0.0",
     "@playwright/test": "^1.60.0",
     "@statelyai/graph": "^2.1.0",
+    "@statelyai/layout": "^0.0.5",
     "@storybook/addon-docs": "^10.1.2",
     "@storybook/react-vite": "^10.1.2",
     "@testing-library/react": "^16.1.0",