reactflow-edge-routing 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reactflow-edge-routing",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",

package/src/routing-core.ts

@@ -114,10 +114,10 @@ export type AvoidRouterOptions = {
   edgeRounding?: number;
   /** Snap waypoints to grid. Default: 0 (no grid) */
   diagramGridSize?: number;
-  /** When true, edges spread out along the node border near handles (pin-based). When false, edges converge to exact handle point. Default: true */
-  shouldSplitEdgesNearHandle?: boolean;
-  /** Length (px) of the stub segment when shouldSplitEdgesNearHandle is off. Default: 20 */
+  /** Length (px) of the stub exit segment from the node border. Default: 20 */
   stubSize?: number;
+  /** When true, each edge gets its own stub spread laterally by handleSpacing (fan-out at handle). When false, all edges share one stub exit point and libavoid routes them apart after. Default: true */
+  shouldSplitEdgesNearHandle?: boolean;
   /** Auto-select best connection side based on relative node positions. Default: true */
   autoBestSideConnection?: boolean;
   /** Debounce delay for routing updates (ms). Default: 0 */
@@ -199,6 +199,59 @@ function getRouterFlags(connectorType: ConnectorType | undefined): number {
   }
 }
 
+// ---- Label Positioning Helpers ----
+
+/** Walk path points and return the point at fraction t (0–1) of total arc length. */
+function pointAtFraction(points: { x: number; y: number }[], t: number): { x: number; y: number } {
+  if (points.length === 1) return points[0];
+  let total = 0;
+  for (let i = 1; i < points.length; i++) {
+    const dx = points[i].x - points[i - 1].x;
+    const dy = points[i].y - points[i - 1].y;
+    total += Math.sqrt(dx * dx + dy * dy);
+  }
+  const target = total * Math.max(0, Math.min(1, t));
+  let walked = 0;
+  for (let i = 1; i < points.length; i++) {
+    const dx = points[i].x - points[i - 1].x;
+    const dy = points[i].y - points[i - 1].y;
+    const segLen = Math.sqrt(dx * dx + dy * dy);
+    if (walked + segLen >= target) {
+      const frac = segLen > 0 ? (target - walked) / segLen : 0;
+      return { x: points[i - 1].x + dx * frac, y: points[i - 1].y + dy * frac };
+    }
+    walked += segLen;
+  }
+  return points[points.length - 1];
+}
+
+/**
+ * For each edge that has routed points, compute the fraction t (0–1) along
+ * the path where its label should sit. Edges sharing the same source handle
+ * are staggered so their labels don't overlap.
+ */
+function buildLabelFractions(
+  edges: FlowEdge[],
+  edgePoints: Map<string, { x: number; y: number }[]>
+): Map<string, number> {
+  const groups = new Map<string, string[]>();
+  for (const edge of edges) {
+    if (!edgePoints.has(edge.id)) continue;
+    const key = `${edge.source}|${edge.sourceHandle ?? ""}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key)!.push(edge.id);
+  }
+  const fractions = new Map<string, number>();
+  for (const group of groups.values()) {
+    const n = group.length;
+    const step = Math.min(0.12, 0.4 / Math.max(1, n - 1));
+    for (let i = 0; i < n; i++) {
+      fractions.set(group[i], 0.5 + (i - (n - 1) / 2) * step);
+    }
+  }
+  return fractions;
+}
+
 // ---- Geometry ----
 
 export class Geometry {
@@ -613,10 +666,8 @@ function configureRouter(router: AvoidRouter, options: AvoidRouterOptions): void
   }
 
   // --- Routing options ---
-  const splitNearHandle = options.shouldSplitEdgesNearHandle ?? true;
-  // When splitNearHandle is off, disable nudging at shapes so edges converge to exact handle point
-  router.setRoutingOption(nudgeOrthogonalSegmentsConnectedToShapesOpt, splitNearHandle ? (options.nudgeOrthogonalSegmentsConnectedToShapes ?? true) : false);
-  router.setRoutingOption(nudgeSharedPathsWithCommonEndPointOpt, splitNearHandle ? (options.nudgeSharedPathsWithCommonEndPoint ?? true) : false);
+  router.setRoutingOption(nudgeOrthogonalSegmentsConnectedToShapesOpt, options.nudgeOrthogonalSegmentsConnectedToShapes ?? true);
+  router.setRoutingOption(nudgeSharedPathsWithCommonEndPointOpt, options.nudgeSharedPathsWithCommonEndPoint ?? true);
   router.setRoutingOption(performUnifyingNudgingPreprocessingStepOpt, options.performUnifyingNudgingPreprocessingStep ?? true);
   router.setRoutingOption(nudgeOrthogonalTouchingColinearSegmentsOpt, options.nudgeOrthogonalTouchingColinearSegments ?? false);
   router.setRoutingOption(improveHyperedgeRoutesMovingJunctionsOpt, options.improveHyperedgeRoutesMovingJunctions ?? true);
@@ -686,17 +737,6 @@ function createObstacles(
 }
 
 
-/**
- * Find the first enriched pin matching a handle type (source/target).
- * Used when edge.sourceHandle/targetHandle is null (default handles).
- */
-function findDefaultHandle(node: FlowNode, kind: "source" | "target"): string | null {
-  const pins = (node._handlePins as HandlePin[] | undefined) ?? [];
-  // Enriched pins from default handles are named __source_N or __target_N
-  const prefix = `__${kind}_`;
-  const pin = pins.find((p) => p.handleId.startsWith(prefix));
-  return pin?.handleId ?? null;
-}
 
 
 /** Offset a point away from the node border by stubLength in the direction of the side */
@@ -709,87 +749,109 @@ function offsetFromSide(pt: { x: number; y: number }, side: HandlePosition, stub
   }
 }
 
-/** Info needed to add stubs after routing when splitNearHandle is off */
+/** Shift a point laterally along a node border (perpendicular to the exit direction) */
+function applyLateralOffset(pt: { x: number; y: number }, side: HandlePosition, offset: number): { x: number; y: number } {
+  switch (side) {
+    case "left":
+    case "right": return { x: pt.x, y: pt.y + offset };
+    case "top":
+    case "bottom": return { x: pt.x + offset, y: pt.y };
+  }
+}
+
+
+/** Info needed to add stubs after routing */
 type StubInfo = {
   edgeId: string;
   srcHandlePt: { x: number; y: number };
   tgtHandlePt: { x: number; y: number };
+  srcStubPt: { x: number; y: number };
+  tgtStubPt: { x: number; y: number };
+  merged: boolean; // true = shared stub mode (splitNearHandle=false)
 };
 
 function createConnections(
   router: AvoidRouter,
   edges: FlowEdge[],
   nodeById: Map<string, FlowNode>,
-  shapeRefMap: Map<string, AvoidShapeRef>,
-  pinRegistry: PinRegistry,
   options: AvoidRouterOptions
 ): { connRefs: { edgeId: string; connRef: AvoidConnRef }[]; stubs: StubInfo[] } {
   const connRefs: { edgeId: string; connRef: AvoidConnRef }[] = [];
   const stubs: StubInfo[] = [];
   const autoBestSide = options.autoBestSideConnection ?? true;
-  const splitNearHandle = options.shouldSplitEdgesNearHandle ?? true;
   const stubLength = options.stubSize ?? 20;
+  const handleSpacing = options.handleNudgingDistance ?? 0;
   const connType = getConnType(options.connectorType);
   const hateCrossings = options.hateCrossings ?? false;
 
+  // Pre-pass: group edges by node+side and compute lateral fan-out offsets so each edge
+  // gets its own stub spread by handleSpacing pixels along the node border.
+  const stubLateralOffsets = new Map<string, { srcOffset: number; tgtOffset: number }>();
+  const splitNearHandle = options.shouldSplitEdgesNearHandle ?? true;
+  if (splitNearHandle && handleSpacing > 0) {
+    const srcGroups = new Map<string, string[]>();
+    const tgtGroups = new Map<string, string[]>();
+    for (const edge of edges) {
+      const src = nodeById.get(edge.source);
+      const tgt = nodeById.get(edge.target);
+      if (!src || !tgt) continue;
+      const sb = Geometry.getNodeBoundsAbsolute(src, nodeById);
+      const tb = Geometry.getNodeBoundsAbsolute(tgt, nodeById);
+      const srcSide = autoBestSide ? Geometry.getBestSides(sb, tb).sourcePos : Geometry.getHandlePosition(src, "source");
+      const tgtSide = autoBestSide ? Geometry.getBestSides(sb, tb).targetPos : Geometry.getHandlePosition(tgt, "target");
+      const sk = `${edge.source}:${srcSide}`;
+      const tk = `${edge.target}:${tgtSide}`;
+      if (!srcGroups.has(sk)) srcGroups.set(sk, []);
+      srcGroups.get(sk)!.push(edge.id);
+      if (!tgtGroups.has(tk)) tgtGroups.set(tk, []);
+      tgtGroups.get(tk)!.push(edge.id);
+    }
+    for (const [, ids] of srcGroups) {
+      const n = ids.length;
+      ids.forEach((id, i) => {
+        const prev = stubLateralOffsets.get(id) ?? { srcOffset: 0, tgtOffset: 0 };
+        prev.srcOffset = (i - (n - 1) / 2) * handleSpacing;
+        stubLateralOffsets.set(id, prev);
+      });
+    }
+    for (const [, ids] of tgtGroups) {
+      const n = ids.length;
+      ids.forEach((id, i) => {
+        const prev = stubLateralOffsets.get(id) ?? { srcOffset: 0, tgtOffset: 0 };
+        prev.tgtOffset = (i - (n - 1) / 2) * handleSpacing;
+        stubLateralOffsets.set(id, prev);
+      });
+    }
+  }
+
   for (const edge of edges) {
     const src = nodeById.get(edge.source);
     const tgt = nodeById.get(edge.target);
     if (!src || !tgt) continue;
 
-    const srcShapeRef = shapeRefMap.get(edge.source);
-    const tgtShapeRef = shapeRefMap.get(edge.target);
-
     const srcBounds = Geometry.getNodeBoundsAbsolute(src, nodeById);
     const tgtBounds = Geometry.getNodeBoundsAbsolute(tgt, nodeById);
 
     let srcEnd: AvoidConnEnd;
     let tgtEnd: AvoidConnEnd;
 
-    if (splitNearHandle) {
-      // Pin-based: edges spread out along the node border near handles
-      // When autoBestSide is on, ignore explicit sourceHandle/targetHandle on edges
-      // and let the router pick the optimal side. Only use explicit handles when
-      // autoBestSide is off (pin-based routing with fixed handle positions).
-      const srcHandle = autoBestSide ? null : (edge.sourceHandle ?? findDefaultHandle(src, "source"));
-      if (srcShapeRef && srcHandle) {
-        const pinId = pinRegistry.getOrCreate(edge.source, srcHandle);
-        srcEnd = AvoidConnEnd.fromShapePin(srcShapeRef as any, pinId);
-      } else if (srcShapeRef) {
-        srcEnd = AvoidConnEnd.fromShapePin(srcShapeRef as any, pinRegistry.getOrCreate(edge.source, `__auto_best`));
-      } else {
-        const side = autoBestSide ? Geometry.getBestSides(srcBounds, tgtBounds).sourcePos : Geometry.getHandlePosition(src, "source");
-        srcEnd = (() => { const pt = Geometry.getHandlePoint(srcBounds, side); return AvoidConnEnd.fromPoint(new AvoidPoint(pt.x, pt.y)); })();
-      }
-
-      const tgtHandle = autoBestSide ? null : (edge.targetHandle ?? findDefaultHandle(tgt, "target"));
-      if (tgtShapeRef && tgtHandle) {
-        const pinId = pinRegistry.getOrCreate(edge.target, tgtHandle);
-        tgtEnd = AvoidConnEnd.fromShapePin(tgtShapeRef as any, pinId);
-      } else if (tgtShapeRef) {
-        tgtEnd = AvoidConnEnd.fromShapePin(tgtShapeRef as any, pinRegistry.getOrCreate(edge.target, `__auto_best`));
-      } else {
-        const side = autoBestSide ? Geometry.getBestSides(srcBounds, tgtBounds).targetPos : Geometry.getHandlePosition(tgt, "target");
-        tgtEnd = (() => { const pt = Geometry.getHandlePoint(tgtBounds, side); return AvoidConnEnd.fromPoint(new AvoidPoint(pt.x, pt.y)); })();
-      }
-    } else {
-      // Point-based with stubs: all edges from the same side converge to center of side,
-      // then route from a stub point offset outward
+    {
+      // Each edge fans out laterally from its side center by handleSpacing,
+      // then exits outward via a stub of stubLength before libavoid routes the middle.
       const srcSide = autoBestSide ? Geometry.getBestSides(srcBounds, tgtBounds).sourcePos : Geometry.getHandlePosition(src, "source");
       const tgtSide = autoBestSide ? Geometry.getBestSides(srcBounds, tgtBounds).targetPos : Geometry.getHandlePosition(tgt, "target");
 
-      // Use center of the side (ignore individual handle positions)
-      const srcHandlePt = Geometry.getHandlePoint(srcBounds, srcSide);
-      const tgtHandlePt = Geometry.getHandlePoint(tgtBounds, tgtSide);
+      const lateral = stubLateralOffsets.get(edge.id) ?? { srcOffset: 0, tgtOffset: 0 };
+      const srcHandlePt = applyLateralOffset(Geometry.getHandlePoint(srcBounds, srcSide), srcSide, lateral.srcOffset);
+      const tgtHandlePt = applyLateralOffset(Geometry.getHandlePoint(tgtBounds, tgtSide), tgtSide, lateral.tgtOffset);
 
-      // Route from stub endpoints (offset from center of side)
       const srcStubPt = offsetFromSide(srcHandlePt, srcSide, stubLength);
       const tgtStubPt = offsetFromSide(tgtHandlePt, tgtSide, stubLength);
 
       srcEnd = AvoidConnEnd.fromPoint(new AvoidPoint(srcStubPt.x, srcStubPt.y));
       tgtEnd = AvoidConnEnd.fromPoint(new AvoidPoint(tgtStubPt.x, tgtStubPt.y));
 
-      stubs.push({ edgeId: edge.id, srcHandlePt, tgtHandlePt });
+      stubs.push({ edgeId: edge.id, srcHandlePt, tgtHandlePt, srcStubPt, tgtStubPt, merged: !splitNearHandle });
     }
 
     const connRef = new AvoidConnRef(router as any, srcEnd, tgtEnd);
@@ -832,8 +894,8 @@ export class RoutingEngine {
     const router = createRouter(routerFlags);
     configureRouter(router, opts);
 
-    const { shapeRefMap, shapeRefList } = createObstacles(router, nodes, nodeById, pinRegistry, opts);
-    const { connRefs, stubs } = createConnections(router, edges, nodeById, shapeRefMap, pinRegistry, opts);
+    const { shapeRefList } = createObstacles(router, nodes, nodeById, pinRegistry, opts);
+    const { connRefs, stubs } = createConnections(router, edges, nodeById, opts);
 
     const result: Record<string, AvoidRoute> = {};
     try { router.processTransaction(); } catch (e) { console.error("[edge-routing] processTransaction failed:", e); RoutingEngine.cleanup(router, connRefs, shapeRefList); return result; }
@@ -848,25 +910,18 @@ export class RoutingEngine {
       if (stub) {
         points.unshift(stub.srcHandlePt);
         points.push(stub.tgtHandlePt);
-      }
-    }
-
-    // Adjust spacing at shared handles (fan-out effect).
-    // Only for splitNearHandle=false (convergence mode): edges all start from the same center
-    // point, libavoid nudges them apart by idealNudgingDistance, and HandleSpacing.adjust scales
-    // that spread by handleNudging/idealNudging → final fan-out = handleNudging (clean decoupling).
-    // For splitNearHandle=true (pin-based), pins already fix the fan-out; scaling would incorrectly
-    // compress or expand existing pin spread, causing edgeToEdgeSpacing to reduce visible spacing.
-    const splitNearHandle = opts.shouldSplitEdgesNearHandle ?? true;
-    if (!splitNearHandle) {
-      const idealNudging = opts.idealNudgingDistance ?? 10;
-      const handleNudging = opts.handleNudgingDistance ?? idealNudging;
-      if (handleNudging !== idealNudging && edgePoints.size > 0) {
-        HandleSpacing.adjust(edges, edgePoints, handleNudging, idealNudging);
+        // In merged mode (splitNearHandle=false), force the adjacent stub waypoints
+        // back to the exact stub endpoints so libavoid's nudging doesn't spread the
+        // entry/exit segments — all edges share one visible trunk line to the stub point.
+        if (stub.merged && points.length >= 3) {
+          points[1] = { ...stub.srcStubPt };
+          points[points.length - 2] = { ...stub.tgtStubPt };
+        }
       }
     }
 
     const connType = opts.connectorType ?? "orthogonal";
+    const labelFractions = buildLabelFractions(edges, edgePoints);
     for (const [edgeId, points] of edgePoints) {
       const edgeRounding = opts.edgeRounding ?? 0;
       const path = connType === "bezier"
@@ -874,8 +929,8 @@ export class RoutingEngine {
         : edgeRounding > 0
           ? PathBuilder.polylineToPath(points.length, (i) => points[i], { cornerRadius: edgeRounding })
           : PathBuilder.pointsToSvgPath(points);
-      const mid = Math.floor(points.length / 2);
-      const midP = points[mid];
+      const t = labelFractions.get(edgeId) ?? 0.5;
+      const midP = pointAtFraction(points, t);
       const labelP = gridSize > 0 ? Geometry.snapToGrid(midP.x, midP.y, gridSize) : midP;
       const first = points[0];
       const last = points[points.length - 1];
@@ -1000,7 +1055,7 @@ export class PersistentRouter {
     const result = createObstacles(this.router, this.prevNodes, this.nodeById, this.pinRegistry, opts);
     this.shapeRefMap = result.shapeRefMap;
     this.shapeRefList = result.shapeRefList;
-    const conn = createConnections(this.router, this.prevEdges, this.nodeById, this.shapeRefMap, this.pinRegistry, opts);
+    const conn = createConnections(this.router, this.prevEdges, this.nodeById, opts);
     this.connRefList = conn.connRefs;
     this.stubList = conn.stubs;
 
@@ -1012,8 +1067,6 @@ export class PersistentRouter {
 
   private readRoutes(): Record<string, AvoidRoute> {
     const opts = this.prevOptions;
-    const idealNudging = opts.idealNudgingDistance ?? 10;
-    const handleNudging = opts.handleNudgingDistance ?? idealNudging;
     const gridSize = opts.diagramGridSize ?? 0;
     const result: Record<string, AvoidRoute> = {};
 
@@ -1027,16 +1080,18 @@ export class PersistentRouter {
       if (stub) {
         points.unshift(stub.srcHandlePt);
         points.push(stub.tgtHandlePt);
+        // In merged mode (splitNearHandle=false), force the adjacent stub waypoints
+        // back to the exact stub endpoints so libavoid's nudging doesn't spread the
+        // entry/exit segments — all edges share one visible trunk line to the stub point.
+        if (stub.merged && points.length >= 3) {
+          points[1] = { ...stub.srcStubPt };
+          points[points.length - 2] = { ...stub.tgtStubPt };
+        }
       }
     }
 
-    // Adjust spacing at shared handles (fan-out effect) — only for splitNearHandle=false (convergence mode)
-    const splitNearHandle = opts.shouldSplitEdgesNearHandle ?? true;
-    if (!splitNearHandle && handleNudging !== idealNudging && edgePoints.size > 0) {
-      HandleSpacing.adjust(this.prevEdges, edgePoints, handleNudging, idealNudging);
-    }
-
     const connType = opts.connectorType ?? "orthogonal";
+    const labelFractions = buildLabelFractions(this.prevEdges, edgePoints);
     for (const [edgeId, points] of edgePoints) {
       const edgeRounding = opts.edgeRounding ?? 0;
       const path = connType === "bezier"
@@ -1044,10 +1099,8 @@ export class PersistentRouter {
         : edgeRounding > 0
           ? PathBuilder.polylineToPath(points.length, (i) => points[i], { cornerRadius: edgeRounding })
           : PathBuilder.pointsToSvgPath(points);
-
-
-      const mid = Math.floor(points.length / 2);
-      const midP = points[mid];
+      const t = labelFractions.get(edgeId) ?? 0.5;
+      const midP = pointAtFraction(points, t);
       const labelP = gridSize > 0 ? Geometry.snapToGrid(midP.x, midP.y, gridSize) : midP;
       const first = points[0];
       const last = points[points.length - 1];

package/src/use-edge-routing.ts

@@ -64,10 +64,10 @@ export interface UseEdgeRoutingOptions {
   // --- Rendering / layout ---
   edgeRounding?: number;
   diagramGridSize?: number;
-  /** When true, edges spread out along the node border near handles. When false, edges converge to exact handle point. Default: true */
-  shouldSplitEdgesNearHandle?: boolean;
-  /** Length (px) of the stub segment when shouldSplitEdgesNearHandle is off. Default: 20 */
+  /** Length (px) of the stub exit segment from the node border. Default: 20 */
   stubSize?: number;
+  /** When true, each edge gets its own stub spread by handleSpacing (fan-out). When false, all edges share one stub and libavoid routes them apart after. Default: true */
+  shouldSplitEdgesNearHandle?: boolean;
   autoBestSideConnection?: boolean;
   debounceMs?: number;
 
@@ -90,7 +90,6 @@ const DEFAULT_OPTIONS: UseEdgeRoutingOptions = {
   edgeToNodeSpacing: 8,
   handleSpacing: 2,
   diagramGridSize: 0,
-  shouldSplitEdgesNearHandle: true,
   autoBestSideConnection: false,
   debounceMs: 0,
 };
@@ -100,7 +99,7 @@ function toRouterOptions(opts?: UseEdgeRoutingOptions): AvoidRouterOptions {
     // Core spacing
     idealNudgingDistance: opts?.edgeToEdgeSpacing ?? DEFAULT_OPTIONS.edgeToEdgeSpacing,
     shapeBufferDistance: opts?.edgeToNodeSpacing ?? DEFAULT_OPTIONS.edgeToNodeSpacing,
-    handleNudgingDistance: opts?.handleSpacing ?? DEFAULT_OPTIONS.handleSpacing,
+    handleNudgingDistance: opts?.handleSpacing ?? opts?.edgeToEdgeSpacing ?? DEFAULT_OPTIONS.edgeToEdgeSpacing,
 
     // Routing parameters
     segmentPenalty: opts?.segmentPenalty,
@@ -128,8 +127,8 @@ function toRouterOptions(opts?: UseEdgeRoutingOptions): AvoidRouterOptions {
     // Rendering
     edgeRounding: opts?.edgeRounding ?? DEFAULT_OPTIONS.edgeRounding,
     diagramGridSize: opts?.diagramGridSize ?? DEFAULT_OPTIONS.diagramGridSize,
-    shouldSplitEdgesNearHandle: opts?.shouldSplitEdgesNearHandle ?? DEFAULT_OPTIONS.shouldSplitEdgesNearHandle,
-    stubSize: opts?.stubSize,
+    stubSize: opts?.stubSize ?? opts?.edgeToEdgeSpacing ?? DEFAULT_OPTIONS.edgeToEdgeSpacing,
+    shouldSplitEdgesNearHandle: opts?.shouldSplitEdgesNearHandle ?? true,
     // bezier defaults to autoBestSideConnection: true — explicit handles
     // make no visual sense on curved paths, so auto-side is the right default.
     autoBestSideConnection: opts?.autoBestSideConnection ?? (opts?.connectorType === "bezier" ? true : DEFAULT_OPTIONS.autoBestSideConnection),