reactflow-edge-routing 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Awais Shah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,242 @@
+# reactflow-edge-routing
+
+Obstacle-aware edge routing for [React Flow](https://reactflow.dev/). Edges automatically route around nodes using orthogonal, polyline, or bezier paths.
+
+Powered by [`obstacle-router`](../obstacle-router) (TypeScript port of libavoid).
+
+## Installation
+
+```bash
+npm install reactflow-edge-routing obstacle-router
+# or
+yarn add reactflow-edge-routing obstacle-router
+```
+
+**Peer dependencies:** `@xyflow/react ^12.0.0`, `react ^18.0.0 || ^19.0.0`
+
+## Quick Start
+
+```tsx
+import { ReactFlow, applyNodeChanges, applyEdgeChanges } from "@xyflow/react";
+import { useEdgeRouting } from "reactflow-edge-routing";
+import { RoutedEdge } from "./RoutedEdge"; // your custom edge component
+
+const edgeTypes = { routed: RoutedEdge };
+
+function Flow() {
+  const [nodes, setNodes] = useState(initialNodes);
+  const [edges, setEdges] = useState(initialEdges); // edges should have type: "routed"
+
+  const { updateRoutingOnNodesChange, resetRouting } = useEdgeRouting(nodes, edges, {
+    edgeRounding: 12,
+    edgeToEdgeSpacing: 4,
+    edgeToNodeSpacing: 8,
+    autoBestSideConnection: true,
+  });
+
+  const onNodesChange = useCallback((changes) => {
+    setNodes((nds) => applyNodeChanges(changes, nds));
+    updateRoutingOnNodesChange(changes);
+  }, [updateRoutingOnNodesChange]);
+
+  return (
+    <ReactFlow
+      nodes={nodes}
+      edges={edges}
+      onNodesChange={onNodesChange}
+      onNodeDragStop={() => resetRouting()}
+      edgeTypes={edgeTypes}
+    />
+  );
+}
+```
+
+### Custom Edge Component
+
+```tsx
+import { useRoutedEdgePath } from "reactflow-edge-routing";
+import { BaseEdge, type EdgeProps } from "@xyflow/react";
+
+export function RoutedEdge({ id, sourceX, sourceY, targetX, targetY, ...props }: EdgeProps) {
+  const [path, labelX, labelY] = useRoutedEdgePath({
+    id, sourceX, sourceY, targetX, targetY,
+  });
+
+  return <BaseEdge id={id} path={path} labelX={labelX} labelY={labelY} {...props} />;
+}
+```
+
+## Architecture
+
+```
+FlowCanvas (React)
+  useEdgeRouting(nodes, edges, options)
+    enrichNode -> adds _handlePins, _extraHeight
+    RoutingEngine / PersistentRouter -> obstacle-router
+    store -> routes: { [edgeId]: AvoidRoute }
+
+  Edge Components
+    useRoutedEdgePath(id, sourceX, ...)
+      routed path (from store)
+      fallback: getSmoothStepPath
+
+  onNodeDragStop -> resolveCollisions + resetRouting
+```
+
+## API
+
+### `useEdgeRouting(nodes, edges, options?)`
+
+Main hook. Computes routed paths for all edges and stores them in a Zustand store.
+
+**Returns:**
+
+| Property | Description |
+|---|---|
+| `updateRoutingOnNodesChange(changes)` | Call from `onNodesChange` to trigger re-routing |
+| `resetRouting()` | Full re-route (call after drag stop, layout changes) |
+| `refreshRouting()` | Re-route without rebuilding the router |
+| `updateRoutingForNodeIds(ids)` | Re-route only edges connected to specific nodes |
+
+### `useRoutedEdgePath(params)`
+
+Returns the routed SVG path for a single edge.
+
+```typescript
+const [path, labelX, labelY] = useRoutedEdgePath({
+  id, sourceX, sourceY, targetX, targetY,
+});
+```
+
+Falls back to a smooth step path if no routed path is available yet.
+
+### `resolveCollisions(nodes, options?)`
+
+Pushes overlapping nodes apart after layout or drag.
+
+```typescript
+import { resolveCollisions } from "reactflow-edge-routing";
+
+const fixed = resolveCollisions(nodes, {
+  maxIterations: 50,
+  overlapThreshold: 0.5,
+  margin: 20,
+});
+```
+
+## Options
+
+### Core Spacing
+
+| Option | Default | Description |
+|---|---|---|
+| `edgeToEdgeSpacing` | 10 | Distance (px) between parallel edge segments |
+| `edgeToNodeSpacing` | 8 | Buffer distance (px) between edges and node boundaries |
+| `handleSpacing` | 2 | Spacing (px) between edges at shared handles |
+
+### Connector Settings
+
+| Option | Default | Description |
+|---|---|---|
+| `connectorType` | `"orthogonal"` | Edge style: `"orthogonal"`, `"polyline"`, or `"bezier"` |
+| `hateCrossings` | `false` | If true, connectors prefer longer paths to avoid crossings |
+| `pinInsideOffset` | 0 | Offset (px) pushing connector start inside shape boundary |
+
+### Rendering
+
+| Option | Default | Description |
+|---|---|---|
+| `edgeRounding` | 8 | Corner radius (px) for orthogonal bends |
+| `diagramGridSize` | 0 | Snap waypoints to grid (0 = no grid) |
+| `shouldSplitEdgesNearHandle` | `true` | When true, edges fan out at handles. When false, edges converge to a single point |
+| `stubSize` | 20 | Length (px) of stub segment when `shouldSplitEdgesNearHandle` is off |
+| `autoBestSideConnection` | `true` | Auto-detect best handle side based on relative node positions |
+| `debounceMs` | 0 | Debounce delay (ms) for routing updates |
+
+### Routing Penalties
+
+| Option | Default | Description |
+|---|---|---|
+| `segmentPenalty` | 10 | Penalty per path segment. Must be >0 for nudging |
+| `anglePenalty` | 0 | Penalty for non-straight bends |
+| `crossingPenalty` | 0 | Penalty for crossing other connectors |
+| `reverseDirectionPenalty` | 0 | Penalty for routing away from destination |
+
+### Nudging Options
+
+| Option | Default | Description |
+|---|---|---|
+| `nudgeOrthogonalSegmentsConnectedToShapes` | `true` | Nudge final segments at shape boundaries |
+| `nudgeSharedPathsWithCommonEndPoint` | `true` | Nudge segments sharing an endpoint |
+| `performUnifyingNudgingPreprocessingStep` | `true` | Unify segments before nudging |
+| `nudgeOrthogonalTouchingColinearSegments` | `false` | Nudge colinear touching segments apart |
+
+### Other
+
+| Option | Default | Description |
+|---|---|---|
+| `realTimeRouting` | `false` | Re-route in real time while dragging |
+| `enrichNode` | - | Function to add `_handlePins` and `_extraHeight` to nodes |
+
+## Multi-Handle Nodes
+
+For nodes with multiple handles, provide an `enrichNode` function that computes pin positions:
+
+```tsx
+const enrichNode = useCallback((node) => {
+  const internal = getInternalNode(node.id);
+  if (!internal) return node;
+  // compute _handlePins from DOM handle positions
+  return { ...node, _handlePins: computePins(internal) };
+}, [getInternalNode]);
+
+useEdgeRouting(nodes, edges, { enrichNode });
+```
+
+Each pin describes a handle's proportional position on the node:
+
+```typescript
+type HandlePin = {
+  handleId: string;  // matches edge.sourceHandle / edge.targetHandle
+  xPct: number;      // 0-1 from left edge
+  yPct: number;      // 0-1 from top edge
+  side: "left" | "right" | "top" | "bottom";
+};
+```
+
+## Exports
+
+### Classes
+
+- `RoutingEngine` - One-shot routing (builds router, routes, disposes)
+- `PersistentRouter` - Incremental routing (reuses router across updates)
+- `Geometry` - Node bounds, handle positions, best-side detection
+- `PathBuilder` - SVG path generation (orthogonal, bezier, polyline)
+- `HandleSpacing` - Fan-out spacing adjustment at shared handles
+
+### Hooks
+
+- `useEdgeRouting` - Main routing hook
+- `useRoutedEdgePath` - Per-edge path hook
+- `useRoutingWorker` - Low-level worker management
+
+### Stores
+
+- `useEdgeRoutingStore` - Zustand store for routed paths
+- `useEdgeRoutingActionsStore` - Zustand store for routing actions
+
+### Functions
+
+- `resolveCollisions` - Push overlapping nodes apart
+- `attachWorkerListener` - Wire up a Web Worker for background routing
+
+### Types
+
+- `AvoidRoute`, `AvoidRouterOptions`, `FlowNode`, `FlowEdge`
+- `HandlePin`, `HandlePosition`, `ConnectorType`
+- `UseEdgeRoutingOptions`, `UseEdgeRoutingResult`
+- `CollisionAlgorithmOptions`, `CollisionAlgorithm`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "reactflow-edge-routing",
+  "version": "0.1.1",
+  "description": "Orthogonal edge routing for React Flow using obstacle-router. Edges route around nodes while pins stay fixed at their anchor points.",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "obstacle-router": "*",
+    "zustand": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@xyflow/react": "^12.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,6 @@
+/** Debounce (ms) before routing runs after diagram changes.
+ *  Must be > 0 so React has time to apply position state before we read nodesRef. */
+export const DEBOUNCE_ROUTING_MS = 16;
+
+/** Default border radius (px) for routed path corners. */
+export const EDGE_BORDER_RADIUS = 0;

package/src/edge-routing-store.ts

@@ -0,0 +1,38 @@
+import { create } from "zustand";
+import type { AvoidRoute, ConnectorType } from "./routing-core";
+
+export interface EdgeRoutingState {
+  loaded: boolean;
+  routes: Record<string, AvoidRoute>;
+  connectorType: ConnectorType;
+  /** Node IDs currently being dragged — edges connected to these show fallback */
+  draggingNodeIds: Set<string>;
+  setLoaded: (loaded: boolean) => void;
+  setRoutes: (routes: Record<string, AvoidRoute>) => void;
+  setConnectorType: (type: ConnectorType) => void;
+  setDraggingNodeIds: (ids: Set<string>) => void;
+}
+
+export const useEdgeRoutingStore = create<EdgeRoutingState>((set) => ({
+  loaded: false,
+  routes: {},
+  connectorType: "orthogonal",
+  draggingNodeIds: new Set(),
+  setLoaded: (loaded) => set({ loaded }),
+  setRoutes: (routes) => set({ routes }),
+  setConnectorType: (connectorType) => set({ connectorType }),
+  setDraggingNodeIds: (draggingNodeIds) => set({ draggingNodeIds }),
+}));
+
+export interface EdgeRoutingActions {
+  resetRouting: () => void;
+  updateRoutesForNodeId: (nodeId: string) => void;
+}
+
+export const useEdgeRoutingActionsStore = create<{
+  actions: EdgeRoutingActions;
+  setActions: (a: EdgeRoutingActions) => void;
+}>((set) => ({
+  actions: { resetRouting: () => {}, updateRoutesForNodeId: () => {} },
+  setActions: (actions) => set({ actions }),
+}));

package/src/edge-routing.worker.ts

@@ -0,0 +1,206 @@
+/**
+ * Web Worker: handles routing commands using libavoid-js (pure TypeScript).
+ * Uses PersistentRouter to prevent heap growth from repeated alloc/free.
+ *
+ * Pins stay fixed at anchor points — routes go around nodes, not through pins.
+ */
+
+import {
+  type AvoidRoute,
+  type AvoidRouterOptions,
+  type FlowNode,
+  type FlowEdge,
+  PersistentRouter,
+} from "./routing-core";
+
+// ---- Worker command types ----
+
+type WorkerCommand =
+  | { command: "reset"; nodes?: FlowNode[]; edges?: FlowEdge[]; options?: AvoidRouterOptions }
+  | { command: "change"; cell: FlowNode | FlowEdge }
+  | { command: "remove"; id: string }
+  | { command: "add"; cell: FlowNode | FlowEdge }
+  | { command: "updateNodes"; nodes?: FlowNode[] }
+  | { command: "route"; nodes?: FlowNode[]; edges?: FlowEdge[]; options?: AvoidRouterOptions }
+  | { command: "close" };
+
+// ---- Initialization ----
+
+console.log("[edge-routing worker] Worker script started (pure TS, no WASM)");
+postMessage({ command: "loaded", success: true } as const);
+
+// ---- Internal model ----
+
+let currentNodes: FlowNode[] = [];
+let currentEdges: FlowEdge[] = [];
+let currentOptions: AvoidRouterOptions = {};
+let nodeIndex = new Map<string, number>();
+let edgeIndex = new Map<string, number>();
+let topologyDirty = true;
+let positionDirty = false;
+let pendingNodeUpdates: FlowNode[] = [];
+
+const persistentRouter = new PersistentRouter();
+
+function rebuildIndices() {
+  nodeIndex = new Map(currentNodes.map((n, i) => [n.id, i]));
+  edgeIndex = new Map(currentEdges.map((e, i) => [e.id, i]));
+}
+
+function isNode(cell: FlowNode | FlowEdge): cell is FlowNode {
+  return "position" in cell && ("width" in cell || "measured" in cell || !("source" in cell));
+}
+
+function doRoute(): Record<string, AvoidRoute> {
+  if (currentEdges.length === 0) return {};
+  try {
+    if (topologyDirty) {
+      topologyDirty = false;
+      positionDirty = false;
+      pendingNodeUpdates = [];
+      return persistentRouter.reset(currentNodes, currentEdges, currentOptions);
+    } else if (positionDirty && pendingNodeUpdates.length > 0) {
+      positionDirty = false;
+      const updates = pendingNodeUpdates;
+      pendingNodeUpdates = [];
+      return persistentRouter.updateNodes(updates);
+    }
+    return persistentRouter.reset(currentNodes, currentEdges, currentOptions);
+  } catch {
+    return {};
+  }
+}
+
+// ---- Debounce ----
+
+const DEFAULT_DEBOUNCE_MS = 0;
+
+function getDebounceMs(): number {
+  return currentOptions.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+}
+
+let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+function isPending() { return debounceTimer != null; }
+function cancelDebounce() {
+  if (debounceTimer != null) { clearTimeout(debounceTimer); debounceTimer = null; }
+}
+
+function debouncedRoute() {
+  cancelDebounce();
+  debounceTimer = setTimeout(() => {
+    debounceTimer = null;
+    const routes = doRoute();
+    setTimeout(() => {
+      if (!isPending()) {
+        postMessage({ command: "routed", routes } as const);
+      }
+    }, 0);
+  }, getDebounceMs());
+}
+
+// ---- Message handler ----
+
+onmessage = (e: MessageEvent<WorkerCommand>) => {
+  const msg = e.data;
+  if (!msg || typeof msg !== "object" || !("command" in msg)) return;
+
+  switch (msg.command) {
+    case "reset":
+      currentNodes = msg.nodes ?? [];
+      currentEdges = msg.edges ?? [];
+      if (msg.options) currentOptions = msg.options;
+      rebuildIndices();
+      topologyDirty = true;
+      pendingNodeUpdates = [];
+      debouncedRoute();
+      break;
+
+    case "change": {
+      const cell = msg.cell;
+      if (isNode(cell)) {
+        const i = nodeIndex.get(cell.id);
+        if (i != null) {
+          currentNodes[i] = { ...currentNodes[i], ...cell };
+          if (!topologyDirty) { positionDirty = true; pendingNodeUpdates.push(currentNodes[i]); }
+        } else {
+          nodeIndex.set(cell.id, currentNodes.length);
+          currentNodes.push(cell);
+          topologyDirty = true;
+        }
+      } else {
+        const i = edgeIndex.get(cell.id);
+        if (i != null) currentEdges[i] = { ...currentEdges[i], ...cell };
+        else { edgeIndex.set(cell.id, currentEdges.length); currentEdges.push(cell); }
+        topologyDirty = true;
+      }
+      debouncedRoute();
+      break;
+    }
+
+    case "remove": {
+      const id = msg.id;
+      currentNodes = currentNodes.filter((n) => n.id !== id);
+      currentEdges = currentEdges.filter((ed) => ed.id !== id);
+      rebuildIndices();
+      topologyDirty = true;
+      pendingNodeUpdates = [];
+      debouncedRoute();
+      break;
+    }
+
+    case "add": {
+      const cell = msg.cell;
+      if (isNode(cell)) {
+        if (!nodeIndex.has(cell.id)) { nodeIndex.set(cell.id, currentNodes.length); currentNodes.push(cell); }
+      } else {
+        if (!edgeIndex.has(cell.id)) { edgeIndex.set(cell.id, currentEdges.length); currentEdges.push(cell); }
+      }
+      topologyDirty = true;
+      debouncedRoute();
+      break;
+    }
+
+    case "updateNodes": {
+      const updatedNodes = msg.nodes ?? [];
+      for (const updated of updatedNodes) {
+        const i = nodeIndex.get(updated.id);
+        if (i != null) {
+          currentNodes[i] = { ...currentNodes[i], ...updated };
+          if (!topologyDirty) { positionDirty = true; pendingNodeUpdates.push(currentNodes[i]); }
+        } else {
+          nodeIndex.set(updated.id, currentNodes.length);
+          currentNodes.push(updated);
+          topologyDirty = true;
+        }
+      }
+      debouncedRoute();
+      break;
+    }
+
+    case "route": {
+      const routeNodes = msg.nodes ?? [];
+      const routeEdges = msg.edges ?? [];
+      const routeOptions = msg.options ?? currentOptions;
+      if (routeEdges.length === 0) {
+        postMessage({ command: "routed", routes: {} } as const);
+        break;
+      }
+      try {
+        const routes = persistentRouter.reset(routeNodes, routeEdges, routeOptions);
+        postMessage({ command: "routed", routes } as const);
+      } catch {
+        postMessage({ command: "routed", routes: {} } as const);
+      }
+      break;
+    }
+
+    case "close":
+      cancelDebounce();
+      persistentRouter.destroy();
+      self.close();
+      break;
+
+    default:
+      break;
+  }
+};

package/src/index.ts

@@ -0,0 +1,44 @@
+// Core routing
+export {
+  Geometry,
+  PathBuilder,
+  HandleSpacing,
+  RoutingEngine,
+  PersistentRouter,
+} from "./routing-core";
+export type {
+  AvoidRoute,
+  AvoidRouterOptions,
+  HandlePosition,
+  FlowNode,
+  FlowEdge,
+  HandlePin,
+  ConnectorType,
+} from "./routing-core";
+
+// Store
+export { useEdgeRoutingStore, useEdgeRoutingActionsStore } from "./edge-routing-store";
+export type { EdgeRoutingState, EdgeRoutingActions } from "./edge-routing-store";
+
+// Worker messages
+export type { EdgeRoutingWorkerCommand, EdgeRoutingWorkerResponse } from "./worker-messages";
+
+// Worker listener
+export { attachWorkerListener } from "./worker-listener";
+
+// Hooks
+export { useRoutingWorker } from "./use-routing-worker";
+export type { UseRoutingWorkerOptions, UseRoutingWorkerResult } from "./use-routing-worker";
+
+export { useEdgeRouting } from "./use-edge-routing";
+export type { UseEdgeRoutingOptions, UseEdgeRoutingResult } from "./use-edge-routing";
+
+export { useRoutedEdgePath } from "./use-routed-edge-path";
+export type { UseRoutedEdgePathParams } from "./use-routed-edge-path";
+
+// Collision resolution
+export { resolveCollisions } from "./resolve-collisions";
+export type { CollisionAlgorithmOptions, CollisionAlgorithm } from "./resolve-collisions";
+
+// Constants
+export { DEBOUNCE_ROUTING_MS, EDGE_BORDER_RADIUS } from "./constants";