@statelyai/flow-react 0.4.0

package/README.md

@@ -0,0 +1,103 @@
+# @statelyai/flow-react
+
+<!-- description from package.json -->
+
+Thin React adapter for `@statelyai/flow` and `@statelyai/flow-dom`.
+
+## 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.
+
+The adapter abstracts over two lower layers:
+
+- `@statelyai/flow` owns the graph, viewport, selection, interaction state, semantic events, and derived engine queries.
+- `@statelyai/flow-dom` owns browser-only measurement and container attachment.
+
+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.
+
+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.
+
+## Core API
+
+<!-- exported React adapter API from src/index.ts -->
+
+| Export                                | Description                                                                      |
+| ------------------------------------- | -------------------------------------------------------------------------------- |
+| `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            |
+| `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                                         |
+| `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                                  |
+| `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       |
+| `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 |
+
+`@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)`.
+
+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.
+
+## Usage
+
+```tsx
+import {
+  StatelyFlow,
+  useFlow,
+  useFlowSelector,
+} from "@statelyai/flow-react";
+import { createEdge, createGraph, createNode } from "@statelyai/flow";
+
+const graph = createGraph({
+  nodes: [
+    createNode({ id: "a", x: 0, y: 0, data: { label: "Start" } }),
+    createNode({ id: "b", x: 240, y: 120, data: { label: "Done" } }),
+  ],
+  edges: [createEdge({ id: "a-b", sourceId: "a", targetId: "b" })],
+});
+
+function Flow() {
+  const flow = useFlow({
+    graph,
+    settings: {
+      store: { snapToGrid: true, snapGrid: [16, 16] },
+    },
+    listeners: [
+      {
+        selector: (context) => context.selection.size,
+        onChange: (selectionSize) => {
+          console.log("selection size", selectionSize);
+        },
+      },
+    ],
+  });
+
+  return (
+    <StatelyFlow
+      flow={flow}
+      graph={graph}
+      renderNode={({ node, selected }) => (
+        <div data-selected={selected}>{node.data?.label ?? node.id}</div>
+      )}
+    />
+  );
+}
+```
+
+## Storybook
+
+```bash
+pnpm --filter @statelyai/flow-react storybook
+```

package/dist/esm/backgrounds.d.ts

@@ -0,0 +1,20 @@
+import * as react0 from "react";
+import { CSSProperties } from "react";
+
+//#region src/backgrounds.d.ts
+type BackgroundVariant = "dots" | "lines" | "cross";
+type BackgroundProps = {
+  variant?: BackgroundVariant;
+  gap?: number;
+  size?: number;
+  color?: string;
+  backgroundColor?: string;
+  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;
+//#endregion
+export { Background, BackgroundProps, BackgroundVariant, CrossBackground, DotsBackground, LinesBackground };

package/dist/esm/backgrounds.js

@@ -0,0 +1,53 @@
+import { l as useFlowSelector } from "./hooks.js";
+import { jsx } from "react/jsx-runtime";
+//#region src/backgrounds.tsx
+function Background(props) {
+	const viewport = useFlowSelector((context) => context.viewport);
+	const variant = props.variant ?? "dots";
+	const gap = props.gap ?? 24;
+	const size = props.size ?? 1;
+	const color = props.color ?? "#cbd5e1";
+	const scaledGap = gap * viewport.zoom;
+	const scaledSize = size * viewport.zoom;
+	return /* @__PURE__ */ jsx("div", {
+		"aria-hidden": true,
+		className: props.className,
+		style: {
+			position: "absolute",
+			inset: 0,
+			backgroundColor: props.backgroundColor,
+			backgroundImage: getBackgroundImage(variant, color, scaledSize),
+			backgroundPosition: `${viewport.x}px ${viewport.y}px`,
+			backgroundSize: `${scaledGap}px ${scaledGap}px`,
+			pointerEvents: "none",
+			...props.style
+		}
+	});
+}
+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 { Background, CrossBackground, DotsBackground, LinesBackground };

package/dist/esm/hooks.js

@@ -0,0 +1,255 @@
+import { createContext, useContext, useEffect, useRef, useState } from "react";
+import { createEntityChangeNotifier, createFlow } from "@statelyai/flow";
+import { getAttachedContainer } from "@statelyai/flow-dom";
+import { jsx } from "react/jsx-runtime";
+//#region src/createFlowInstance.ts
+function createFlowInstance(options) {
+	const flow = createFlow({
+		graph: options.graph,
+		...options.settings
+	});
+	const cleanup = /* @__PURE__ */ new Set();
+	function getSnapshot() {
+		return flow.store.getSnapshot().context;
+	}
+	function clientToCanvas(point) {
+		const rect = getAttachedContainer(flow.store)?.getBoundingClientRect();
+		return flow.screenToCanvas({
+			x: point.x - (rect?.left ?? 0),
+			y: point.y - (rect?.top ?? 0)
+		});
+	}
+	function listen(selector, listener, listenerOptions = {}) {
+		const isEqual = listenerOptions.isEqual ?? Object.is;
+		let previousValue = selector(getSnapshot());
+		if (listenerOptions.fireImmediately) listener(previousValue, previousValue, getSnapshot());
+		const unsubscribe = flow.subscribe((context) => {
+			const nextValue = selector(context);
+			if (isEqual(previousValue, nextValue)) return;
+			const currentPreviousValue = previousValue;
+			previousValue = nextValue;
+			listener(nextValue, currentPreviousValue, context);
+		});
+		cleanup.add(unsubscribe);
+		return () => {
+			cleanup.delete(unsubscribe);
+			unsubscribe();
+		};
+	}
+	function subscribeEvent(event, listener) {
+		const subscription = flow.on(event, listener);
+		const unsubscribe = () => subscription.unsubscribe();
+		cleanup.add(unsubscribe);
+		return () => {
+			cleanup.delete(unsubscribe);
+			unsubscribe();
+		};
+	}
+	if (options.events?.connectionEnded) subscribeEvent("connectionEnded", options.events.connectionEnded);
+	if (options.events?.layoutRequested) subscribeEvent("layoutRequested", options.events.layoutRequested);
+	for (const listener of options.listeners ?? []) listen(listener.selector, listener.onChange, listener);
+	return {
+		...flow,
+		getSnapshot,
+		listen,
+		clientToCanvas,
+		destroy() {
+			for (const unsubscribe of cleanup) unsubscribe();
+			cleanup.clear();
+			flow.destroy();
+		}
+	};
+}
+//#endregion
+//#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/hooks.ts
+function useFlow(options) {
+	return useCreateFlowInstance(options);
+}
+function useCreateFlowInstance(options) {
+	const instanceRef = useRef(null);
+	const listenersRef = useRef(options.listeners);
+	const eventsRef = useRef(options.events);
+	const didMountRef = useRef(false);
+	listenersRef.current = options.listeners;
+	eventsRef.current = options.events;
+	if (!instanceRef.current) instanceRef.current = createFlowInstance({
+		graph: options.graph,
+		settings: options.settings
+	});
+	const flow = instanceRef.current;
+	useEffect(() => {
+		if (!didMountRef.current) {
+			didMountRef.current = true;
+			return;
+		}
+		flow.trigger.setGraph({ graph: options.graph });
+	}, [flow, options.graph]);
+	useEffect(() => {
+		const cleanup = [];
+		if (eventsRef.current?.connectionEnded) {
+			const subscription = flow.on("connectionEnded", eventsRef.current.connectionEnded);
+			cleanup.push(() => subscription.unsubscribe());
+		}
+		if (eventsRef.current?.layoutRequested) {
+			const subscription = flow.on("layoutRequested", eventsRef.current.layoutRequested);
+			cleanup.push(() => subscription.unsubscribe());
+		}
+		for (const listener of listenersRef.current ?? []) cleanup.push(flow.listen(listener.selector, listener.onChange, listener));
+		return () => {
+			for (const dispose of cleanup) dispose();
+		};
+	}, [
+		flow,
+		options.listeners,
+		options.events
+	]);
+	useEffect(() => () => flow.destroy(), [flow]);
+	return flow;
+}
+function useFlowSelector(selector, options = {}) {
+	const contextFlow = useOptionalFlowInstance();
+	const flow = options.flow ?? contextFlow;
+	if (!flow) throw new Error("Flow instance is missing. Pass { flow } or render inside <FlowInstanceProvider>.");
+	const selectorRef = useRef(selector);
+	const isEqualRef = useRef(options.isEqual ?? Object.is);
+	selectorRef.current = selector;
+	isEqualRef.current = options.isEqual ?? Object.is;
+	const [selected, setSelected] = useState(() => selector(flow.getSnapshot()));
+	useEffect(() => {
+		setSelected((previous) => {
+			const next = selectorRef.current(flow.getSnapshot());
+			return isEqualRef.current(previous, next) ? previous : next;
+		});
+		return flow.listen((context) => selectorRef.current(context), (value) => {
+			setSelected((previous) => isEqualRef.current(previous, value) ? previous : value);
+		});
+	}, [flow]);
+	return selected;
+}
+function useFlowContext() {
+	return useFlowSelector((context) => context);
+}
+const entityNotifiers = /* @__PURE__ */ new WeakMap();
+function getEntityNotifier(flow) {
+	let notifier = entityNotifiers.get(flow.store);
+	if (!notifier) {
+		notifier = createEntityChangeNotifier(flow.store);
+		entityNotifiers.set(flow.store, notifier);
+	}
+	return notifier;
+}
+/**
+* Like `useFlowSelector`, but subscribed through the entity-change notifier:
+* the selector re-runs only when the entity with `id` may have changed, not
+* on every store transition. This is what makes thousands of mounted entity
+* views affordable — see BENCHMARK.md.
+*/
+function useFlowEntity(id, selector, options = {}) {
+	const contextFlow = useOptionalFlowInstance();
+	const flow = options.flow ?? contextFlow;
+	if (!flow) throw new Error("Flow instance is missing. Pass { flow } or render inside <FlowInstanceProvider>.");
+	const selectorRef = useRef(selector);
+	const isEqualRef = useRef(options.isEqual ?? Object.is);
+	selectorRef.current = selector;
+	isEqualRef.current = options.isEqual ?? Object.is;
+	const [selected, setSelected] = useState(() => selector(flow.getSnapshot()));
+	useEffect(() => {
+		const update = () => {
+			setSelected((previous) => {
+				const next = selectorRef.current(flow.getSnapshot());
+				return isEqualRef.current(previous, next) ? previous : next;
+			});
+		};
+		update();
+		return getEntityNotifier(flow).subscribe(id, update);
+	}, [flow, id]);
+	return selected;
+}
+function useFlowValue(selector, isEqual) {
+	return useFlowSelector(selector, { isEqual });
+}
+function useFlowNode(id, selector, isEqual) {
+	return useFlowSelector((context) => {
+		const node = context.graph.nodes.find((candidate) => candidate.id === id);
+		if (!node) throw new Error(`Flow node "${id}" was not found.`);
+		if (selector) return selector(node, context);
+		return {
+			...node,
+			...getDerivedFields(context, id, {
+				"data-flow-target": "entity",
+				"data-flow-entity-id": id,
+				"data-entity-id": id
+			})
+		};
+	}, { isEqual });
+}
+function useFlowEdge(id, selector, isEqual) {
+	const flow = useOptionalFlowInstance();
+	return useFlowSelector((context) => {
+		const edge = context.graph.edges.find((candidate) => candidate.id === id);
+		if (!edge) throw new Error(`Flow edge "${id}" was not found.`);
+		if (selector) return selector(edge, context);
+		return {
+			...edge,
+			pathData: flow?.getAllEdgePaths().get(id) ?? null,
+			...getDerivedFields(context, id, {
+				"data-flow-target": "entity",
+				"data-flow-entity-id": id,
+				"data-entity-id": id
+			})
+		};
+	}, { isEqual });
+}
+function useFlowPort(id, selector, isEqual) {
+	const flow = useFlowInstance();
+	return useFlowSelector((context) => {
+		const addressable = flow?.getAddressable(id);
+		if (!addressable || addressable.kind !== "port") throw new Error(`Flow port "${id}" was not found.`);
+		const binding = {
+			...addressable.port,
+			id,
+			nodeId: addressable.nodeId,
+			portName: addressable.portName,
+			...getDerivedFields(context, id, {
+				"data-flow-target": "port",
+				"data-flow-port-id": id,
+				"data-flow-node-id": addressable.nodeId,
+				"data-flow-port-name": addressable.portName
+			})
+		};
+		return selector ? selector(binding, context) : binding;
+	}, { isEqual });
+}
+function useFlowViewport() {
+	return useFlowSelector((context) => context.viewport);
+}
+function useFlowMeasurement(id) {
+	return useFlowSelector((context) => context.measurements.get(id) ?? null);
+}
+function getDerivedFields(context, id, props) {
+	return {
+		selected: context.selection.has(id),
+		focused: context.focusedEntityId === id,
+		hovered: context.hoveredEntityIds.has(id),
+		props
+	};
+}
+//#endregion
+export { useFlowEntity as a, useFlowPort as c, useFlowViewport as d, FlowInstanceProvider as f, createFlowInstance as h, useFlowEdge as i, useFlowSelector as l, useOptionalFlowInstance as m, useFlow as n, useFlowMeasurement as o, useFlowInstance as p, useFlowContext as r, useFlowNode as s, useCreateFlowInstance as t, useFlowValue as u };