@statelyai/flow-react 0.5.0 → 0.7.0

package/README.md

@@ -2,11 +2,11 @@
 
 <!-- description from package.json -->
 
-Thin React adapter for `@statelyai/flow` and `@statelyai/flow-dom`.
+Thin React adapter for `@statelyai/flow` with core and DOM re-exports.
 
 ## Philosophy
 
-`@statelyai/flow-react` should be completely event-driven and composable. React should not hide a second flow model behind component internals; it should adapt the same `FlowInstance` that consumers can create, inspect, subscribe to, and trigger directly.
+`@statelyai/flow-react` should be completely event-driven and composable. React should not hide a second flow model behind component internals; it should adapt the same `FlowInstance` that consumers can create, inspect, subscribe to, and trigger directly. It re-exports the lower layers so React consumers can install and import from one package.
 
 The adapter abstracts over two lower layers:
 
@@ -15,11 +15,13 @@ The adapter abstracts over two lower layers:
 
 The React package owns React lifecycle, context, selector subscriptions, and a convenience renderer. It should be flexible enough for consumers to build their own stateful flow component from the instance alone.
 
-Optimization is part of the architecture, not a later cleanup pass. Components should subscribe only to the data they actually render or use for derived work. For example, an edge layer should not subscribe to the entire store when it only needs edges, viewport, edge-path inputs, and selected edge ids.
+<!-- 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, resize, and animated layout sessions, `@statelyai/flow-dom` batches node rectangles, edge paths, endpoint handles, and label positions 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.
 
 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`.
 
-DOM measurement is one-directional by default. Nodes, ports, and edge labels report their inherent rendered size back to the engine, but default renderers should not apply measured `width` or `height` back onto the same DOM entities. Consumers can opt into controlled sizing for custom components, but the built-in DOM path should avoid measurement feedback loops.
+DOM measurement is one-directional. Nodes, ports, and edge labels report their rendered size to the engine. For `autoSize` nodes and `label.autoSize` edge labels, the adapter leaves DOM width/height content-driven and Flow keeps measurements as derived session geometry; it never writes them into authored dimensions. Explicitly resizing an `autoSize` node switches its wrapper to the committed dimensions while preserving the content measurement as derived data. Graph-owned entities retain their existing controlled-size behavior.
 
 ## Core API
 
@@ -29,36 +31,72 @@ DOM measurement is one-directional by default. Nodes, ports, and edge labels rep
 | ------------------------------------- | -------------------------------------------------------------------------------- |
 | `createFlowInstance(options)`         | Creates the shared instance used by React and custom renderers                   |
 | `useFlow(options)`                    | TipTap-style hook for creating a stable flow controller                          |
-| `useCreateFlowInstance(options)`      | React lifecycle hook for creating an instance and attaching listeners            |
+| `useCreateFlowInstance(options)`      | Deprecated alias for `useFlow(options)`                                          |
 | `useFlowSelector(selector, options?)` | Subscribe to any part of the flow store from React                               |
 | `useFlowValue(selector, isEqual?)`    | Short selector hook for the nearest provider                                     |
 | `useFlowContext()`                    | Subscribe to the full flow store context                                         |
+| `useConnection()`                     | Subscribe to the active connection gesture state                                 |
+| `useFlowConnections(query)`           | Subscribe to stable, port-aware connections for one node                          |
+| `useFlowView()`                       | Access view-owned image export and measurement refresh                            |
+| `useKeyPress(keys)`                   | Track whether one or more keys are currently pressed                             |
+| `useNodesInitialized()`               | Check whether visible auto-size nodes have measurements                          |
 | `useFlowNode(id, selector?, isEqual?)` | Subscribe to node data plus derived render fields                               |
 | `useFlowEdge(id, selector?, isEqual?)` | Subscribe to edge data plus derived render fields                               |
 | `useFlowPort(id, selector?, isEqual?)` | Subscribe to port data plus derived render fields                               |
 | `useFlowViewport()`                   | Subscribe to viewport state                                                      |
-| `useFlowMeasurement(id)`              | Subscribe to measured bounds for an addressable                                  |
+| `useFlowMeasurement(id)`              | Subscribe to measured bounds for an entity ref                                   |
 | `FlowInstanceProvider`                | Provides a `FlowInstance` through React context                                  |
 | `useFlowInstance()`                   | Reads the nearest `FlowInstance`                                                 |
 | `useOptionalFlowInstance()`           | Reads the nearest `FlowInstance` or returns `null`                               |
-| `StatelyFlow`                         | Convenience component that renders nodes, edges, backgrounds, and overlays       |
+| `StatelyFlow`                         | Convenience component that renders nodes, edges, backgrounds, projections, and overlays |
+| `createEntityGeometryObserver(store)` | Batches transient node/label rectangles and edge paths into imperative animation-frame DOM writes |
+| `PanePortal` / `ViewportPortal`       | Render custom content into fixed screen-coordinate or transformed canvas-coordinate layers |
+| `EntityAnchor`                       | Position custom controls on entity sides or free-standing canvas bounds with screen-stable offsets and inverse scaling |
+| `RenderEdgeLabelProps`                | Edge, path, bounds, interaction state, and projected attrs passed to `renderEdgeLabel` |
+| `Panel`                               | Positioned overlay panel for controls and custom UI                              |
+| `NodeResizer`                         | Resize handles for custom node renderers; constraints live on `node.resize`             |
+| `ReactActiveGraphProjection`          | React-typed active projection for `<StatelyFlow projections={...} />` or controller-owned projections |
+| `ReactGraphNodeAttrs` / `ReactGraphEdgeAttrs` | React-typed visual attrs exposed to custom node/edge renderers           |
 | `FlowColorModeScope`                  | Applies the current flow color mode as DOM data attributes and `color-scheme`    |
 | `useFlowColorMode()`                  | Reads the store color mode and resolves `system` to `light` or `dark`            |
 | `useApplyFlowColorMode(element)`      | Applies flow color mode attributes to an existing DOM element from inside a flow |
+| `FLOW_BASE_CSS` / `useFlowBaseStyles()` | Base data-attribute stylesheet injected by `StatelyFlow`                      |
 
-`@statelyai/flow-react/backgrounds` exports `Background`, `DotsBackground`, `LinesBackground`, and `CrossBackground` helpers for viewport-aware canvas backgrounds. Backgrounds are plain React components, so consumers can also build custom ones with `useFlowSelector((context) => context.viewport)`.
+`@statelyai/flow-react` and `@statelyai/flow-react/backgrounds` export `Background`, `DotsBackground`, `LinesBackground`, and `CrossBackground` helpers for viewport-aware canvas backgrounds. Backgrounds are plain React components, so consumers can also build custom ones with `useFlowSelector((context) => context.viewport)`.
 
 Color mode is store data, not engine behavior. `@statelyai/flow-dom` exports small helpers for resolving and applying `light`, `dark`, and `system`, while React exposes hooks/components that make those values easy to use with CSS variables.
 
+`initialGraph` seeds a graph that the adapter-owned flow instance owns. For caller ownership, create a controller and pass `flow={flow}`. There is no controlled `graph` prop; observe `flow.on('commit', ...)` or `onCommit` for persistence and synchronization. Runtime `settings`, `inputModes`, and `projections` update the existing flow instance. If `projections` is omitted, `StatelyFlow` subscribes to the instance's `flow.projections` lifecycle.
+
+<!-- StatelyFlow renderEdgeLabel and layers props from src/StatelyFlow.tsx plus portal exports from src/LayerPortals.tsx -->
+
+`renderEdgeLabel` replaces the built-in label content while retaining Flow's positioned, measured, interactive label wrapper. Set `edge.label.autoSize: true` for content-driven custom labels; the wrapper then leaves width/height unset while its measurement drives stable routed geometry. Render props include the edge's current `pathData`: the same `EdgePathData` object already routed by `StatelyFlow`, including both source-to-label and label-to-target segments. Transient drag geometry remains on Flow's imperative DOM path, and the renderer receives current committed geometry at gesture boundaries. Use `layers.viewport` for canvas-coordinate content and `layers.pane` for screen-coordinate content. Descendants can target the same named layers with `ViewportPortal` and `PanePortal`. Layer wrappers ignore pointer input; opt individual controls in with `pointerEvents: "auto"` and mark controls inside labels or canvas layers with `data-flow-interactive` when Flow gestures should ignore them.
+
+Custom node and edge renderers should branch on the application-defined `entity.kind`. Keep `entity.type` as the structural `"node"` or `"edge"` discriminant so core selection, drag, connection, and CRUD behavior remains valid.
+
+For controlled reconnect gestures, `reconnectMode({ commit: false, preview: false })` keeps Flow's input lifecycle while suppressing the adapter's projected preview edge, so an external domain store can render its own temporary geometry without duplicate paths.
+
+`EntityAnchor` can be nested inside a node or edge-label renderer with `side`, a child `anchor` point, cross-axis `align`, and an outward `offset`. The nested anchor follows the parent entity's imperative drag geometry without React commits. With `inverseScale`, its size and offset remain constant in screen pixels and its transform origin matches the selected child anchor. The existing `bounds` plus `AnchorSpec` form remains available for free-standing canvas-space overlays.
+
+`StatelyFlow` exposes stable, namespaced selector roles while keeping `data-flow-*` attributes authoritative: `.stately-flow` / `.stately-flow__pane` (interactive root), `.stately-flow__viewport` (transformed canvas), `.stately-flow__edges`, `.stately-flow__nodes`, `.stately-flow__edge-labels`, their singular entity classes, `.stately-flow__background`, `.stately-flow__viewport-layer`, `.stately-flow__pane-layer`, and `.stately-flow__overlays`. Consumer `className` values are merged with these roles.
+
+Use `rootRef` and `rootProps` to access that input-owned root or attach ordinary div attributes and events such as context menu, double-click, and drag/drop. `rootProps.className` and `rootProps.style` merge with the top-level values; Flow's input runtime remains the sole gesture owner.
+
+Keyboard handling is scoped to the `StatelyFlow` root by default so multiple flows on one page do not all receive Delete/undo/arrow keys. Pass `keyboardTarget="window"` to restore global handling. Pass `settings={{ keymap }}` to rebind built-in shortcuts. Double-click zoom is enabled in the default input modes; Shift double-click zooms out.
+
+Alignment and equal-spacing guides stay a constant screen size across zoom and expose `--flow-snap-line-color` and `--flow-spacing-guide-color` for theming. Equal-spacing guides include their rounded canvas distance.
+
 ## Usage
 
 ```tsx
 import {
+  createEdge,
+  createGraph,
+  createNode,
   StatelyFlow,
   useFlow,
   useFlowSelector,
 } from "@statelyai/flow-react";
-import { createEdge, createGraph, createNode } from "@statelyai/flow";
 
 const graph = createGraph({
   nodes: [
@@ -70,7 +108,7 @@ const graph = createGraph({
 
 function Flow() {
   const flow = useFlow({
-    graph,
+    initialGraph: graph,
     settings: {
       store: { snapToGrid: true, snapGrid: [16, 16] },
     },
@@ -87,7 +125,14 @@ function Flow() {
   return (
     <StatelyFlow
       flow={flow}
-      graph={graph}
+      projections={[
+        {
+          projection: { id: "coverage", nodes: { a: "visited" } },
+          mapper: {
+            getNodeAttrs: () => ({ color: "#16a34a", badge: "visited" }),
+          },
+        },
+      ]}
       renderNode={({ node, selected }) => (
         <div data-selected={selected}>{node.data?.label ?? node.id}</div>
       )}

package/dist/esm/backgrounds.d.ts

@@ -1,6 +1,4 @@
-import * as react0 from "react";
 import { CSSProperties } from "react";
-
 //#region src/backgrounds.d.ts
 type BackgroundVariant = "dots" | "lines" | "cross";
 type BackgroundProps = {
@@ -14,15 +12,23 @@ type BackgroundProps = {
   /**
    * Minimum on-screen spacing (px) before the grid subdivides. The effective
    * spacing is kept in `[minSpacing, 2 * minSpacing)` by snapping `gap` to a
-   * power-of-two multiple, so the grid never looks crowded or sparse.
+   * power-of-two multiple, so the grid never looks crowded or sparse. Only used
+   * when `adaptive` is true.
    */
   minSpacing?: number;
+  /**
+   * Whether the grid subdivides/coarsens with zoom to keep a visually constant
+   * density (Figma-style). Defaults to `true`. When `false`, the grid is a plain
+   * `gap`-spaced lattice that scales linearly with zoom — no subdivision — so it
+   * gets denser as you zoom out and sparser as you zoom in.
+   */
+  adaptive?: boolean;
   className?: string;
   style?: CSSProperties;
 };
-declare function Background(props: BackgroundProps): react0.JSX.Element;
-declare function DotsBackground(props: Omit<BackgroundProps, "variant">): react0.JSX.Element;
-declare function LinesBackground(props: Omit<BackgroundProps, "variant">): react0.JSX.Element;
-declare function CrossBackground(props: Omit<BackgroundProps, "variant">): react0.JSX.Element;
+declare function Background(props: BackgroundProps): import("react").JSX.Element;
+declare function DotsBackground(props: Omit<BackgroundProps, "variant">): import("react").JSX.Element;
+declare function LinesBackground(props: Omit<BackgroundProps, "variant">): import("react").JSX.Element;
+declare function CrossBackground(props: Omit<BackgroundProps, "variant">): import("react").JSX.Element;
 //#endregion
 export { Background, BackgroundProps, BackgroundVariant, CrossBackground, DotsBackground, LinesBackground };

package/dist/esm/backgrounds.js

@@ -1,96 +1,2 @@
-import { n as useFlowInstance } from "./FlowInstanceContext.js";
-import { useLayoutEffect, useMemo, useRef } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
-//#region src/backgrounds.tsx
-function Background(props) {
-	const instance = useFlowInstance();
-	const variant = props.variant ?? "dots";
-	const gap = props.gap ?? 24;
-	const size = props.size ?? 1;
-	const color = props.color ?? "#cbd5e1";
-	const minSpacing = props.minSpacing ?? 24;
-	const image = useMemo(() => getBackgroundImage(variant, color, size), [
-		variant,
-		color,
-		size
-	]);
-	const majorRef = useRef(null);
-	const minorRef = useRef(null);
-	useLayoutEffect(() => {
-		const major = majorRef.current;
-		const minor = minorRef.current;
-		if (!major || !minor) return;
-		const phase = variant === "lines" ? 0 : .5;
-		const apply = (viewport) => {
-			const screenGap = gap * viewport.zoom;
-			const majorGap = screenGap * 2 ** Math.ceil(Math.log2(minSpacing / screenGap));
-			const minorGap = majorGap / 2;
-			const t = majorGap / minSpacing - 1;
-			major.style.backgroundSize = `${majorGap}px ${majorGap}px`;
-			major.style.backgroundPosition = `${viewport.x - phase * majorGap}px ${viewport.y - phase * majorGap}px`;
-			minor.style.backgroundSize = `${minorGap}px ${minorGap}px`;
-			minor.style.backgroundPosition = `${viewport.x - phase * minorGap}px ${viewport.y - phase * minorGap}px`;
-			minor.style.opacity = String(t);
-		};
-		apply(instance.getSnapshot().viewport);
-		return instance.listen((context) => context.viewport, (viewport) => apply(viewport));
-	}, [
-		instance,
-		gap,
-		minSpacing,
-		variant
-	]);
-	const layerStyle = {
-		position: "absolute",
-		inset: 0,
-		backgroundImage: image
-	};
-	return /* @__PURE__ */ jsxs("div", {
-		"aria-hidden": true,
-		className: props.className,
-		style: {
-			position: "absolute",
-			inset: 0,
-			backgroundColor: props.backgroundColor,
-			pointerEvents: "none",
-			...props.style
-		},
-		children: [/* @__PURE__ */ jsx("div", {
-			ref: minorRef,
-			style: {
-				...layerStyle,
-				opacity: 0
-			}
-		}), /* @__PURE__ */ jsx("div", {
-			ref: majorRef,
-			style: layerStyle
-		})]
-	});
-}
-function DotsBackground(props) {
-	return /* @__PURE__ */ jsx(Background, {
-		...props,
-		variant: "dots"
-	});
-}
-function LinesBackground(props) {
-	return /* @__PURE__ */ jsx(Background, {
-		...props,
-		variant: "lines"
-	});
-}
-function CrossBackground(props) {
-	return /* @__PURE__ */ jsx(Background, {
-		...props,
-		variant: "cross"
-	});
-}
-function getBackgroundImage(variant, color, size) {
-	switch (variant) {
-		case "dots": return `radial-gradient(circle, ${color} ${size}px, transparent ${size}px)`;
-		case "lines": return [`linear-gradient(${color} ${size}px, transparent ${size}px)`, `linear-gradient(90deg, ${color} ${size}px, transparent ${size}px)`].join(", ");
-		case "cross": return `url("data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><path d="M50 38v24M38 50h24" stroke="${color}" stroke-width="${Math.max(1, size)}" stroke-linecap="round"/></svg>`)}")`;
-	}
-}
-//#endregion
+import { i as LinesBackground, n as CrossBackground, r as DotsBackground, t as Background } from "./backgrounds2.js";
 export { Background, CrossBackground, DotsBackground, LinesBackground };

package/dist/esm/backgrounds2.js

@@ -0,0 +1,124 @@
+import { createContext, useContext, useLayoutEffect, useMemo, useRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/FlowInstanceContext.tsx
+const FlowInstanceContext = createContext(null);
+function FlowInstanceProvider(props) {
+	return /* @__PURE__ */ jsx(FlowInstanceContext.Provider, {
+		value: props.flow,
+		children: props.children
+	});
+}
+function useFlowInstance() {
+	const flow = useContext(FlowInstanceContext);
+	if (!flow) throw new Error("Flow instance is missing. Wrap this tree in <FlowInstanceProvider flow={flow}>.");
+	return flow;
+}
+function useOptionalFlowInstance() {
+	return useContext(FlowInstanceContext);
+}
+//#endregion
+//#region src/backgrounds.tsx
+function classNames(...values) {
+	return values.filter(Boolean).join(" ");
+}
+function Background(props) {
+	const instance = useFlowInstance();
+	const variant = props.variant ?? "dots";
+	const gap = props.gap ?? 24;
+	const size = props.size ?? 1;
+	const color = props.color ?? "#cbd5e1";
+	const minSpacing = props.minSpacing ?? 24;
+	const adaptive = props.adaptive ?? true;
+	const image = useMemo(() => getBackgroundImage(variant, color, size), [
+		variant,
+		color,
+		size
+	]);
+	const majorRef = useRef(null);
+	const minorRef = useRef(null);
+	useLayoutEffect(() => {
+		const major = majorRef.current;
+		const minor = minorRef.current;
+		if (!major || !minor) return;
+		const phase = variant === "lines" ? 0 : .5;
+		const apply = (viewport) => {
+			if (!adaptive) {
+				const fixedGap = gap * viewport.zoom;
+				major.style.backgroundSize = `${fixedGap}px ${fixedGap}px`;
+				major.style.backgroundPosition = `${viewport.x - phase * fixedGap}px ${viewport.y - phase * fixedGap}px`;
+				minor.style.opacity = "0";
+				return;
+			}
+			const screenGap = gap * viewport.zoom;
+			const majorGap = screenGap * 2 ** Math.ceil(Math.log2(minSpacing / screenGap));
+			const minorGap = majorGap / 2;
+			const t = majorGap / minSpacing - 1;
+			major.style.backgroundSize = `${majorGap}px ${majorGap}px`;
+			major.style.backgroundPosition = `${viewport.x - phase * majorGap}px ${viewport.y - phase * majorGap}px`;
+			minor.style.backgroundSize = `${minorGap}px ${minorGap}px`;
+			minor.style.backgroundPosition = `${viewport.x - phase * minorGap}px ${viewport.y - phase * minorGap}px`;
+			minor.style.opacity = String(t);
+		};
+		apply(instance.getSnapshot().viewport);
+		return instance.listen((context) => context.viewport, (viewport) => apply(viewport));
+	}, [
+		instance,
+		gap,
+		minSpacing,
+		variant,
+		adaptive
+	]);
+	const layerStyle = {
+		position: "absolute",
+		inset: 0,
+		backgroundImage: image
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		"aria-hidden": true,
+		className: classNames("stately-flow__background", props.className),
+		style: {
+			position: "absolute",
+			inset: 0,
+			backgroundColor: props.backgroundColor,
+			pointerEvents: "none",
+			...props.style
+		},
+		children: [/* @__PURE__ */ jsx("div", {
+			ref: minorRef,
+			style: {
+				...layerStyle,
+				opacity: 0
+			}
+		}), /* @__PURE__ */ jsx("div", {
+			ref: majorRef,
+			style: layerStyle
+		})]
+	});
+}
+function DotsBackground(props) {
+	return /* @__PURE__ */ jsx(Background, {
+		...props,
+		variant: "dots"
+	});
+}
+function LinesBackground(props) {
+	return /* @__PURE__ */ jsx(Background, {
+		...props,
+		variant: "lines"
+	});
+}
+function CrossBackground(props) {
+	return /* @__PURE__ */ jsx(Background, {
+		...props,
+		variant: "cross"
+	});
+}
+function getBackgroundImage(variant, color, size) {
+	switch (variant) {
+		case "dots": return `radial-gradient(circle, ${color} ${size}px, transparent ${size}px)`;
+		case "lines": return [`linear-gradient(${color} ${size}px, transparent ${size}px)`, `linear-gradient(90deg, ${color} ${size}px, transparent ${size}px)`].join(", ");
+		case "cross": return `url("data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><path d="M50 38v24M38 50h24" stroke="${color}" stroke-width="${Math.max(1, size)}" stroke-linecap="round"/></svg>`)}")`;
+	}
+}
+//#endregion
+export { FlowInstanceProvider as a, LinesBackground as i, CrossBackground as n, useFlowInstance as o, DotsBackground as r, useOptionalFlowInstance as s, Background as t };