@joshrp/react-flow-smart-edge 4.0.2

package/src/getSmartEdge/index.ts

@@ -0,0 +1,160 @@
+import {
+  createGrid,
+  getBoundingBoxes,
+  gridToGraphPoint,
+  pathfindingAStarDiagonal,
+  svgDrawSmoothLinePath,
+  toInteger,
+} from "../functions";
+import type {
+  PointInfo,
+  PathFindingFunction,
+  SVGDrawFunction,
+} from "../functions";
+import type { Node, EdgeProps } from "@xyflow/react";
+
+export type EdgeParams = Pick<
+  EdgeProps,
+  | "sourceX"
+  | "sourceY"
+  | "targetX"
+  | "targetY"
+  | "sourcePosition"
+  | "targetPosition"
+>;
+
+export interface GetSmartEdgeOptions {
+  gridRatio?: number;
+  nodePadding?: number;
+  drawEdge?: SVGDrawFunction;
+  generatePath?: PathFindingFunction;
+  // Internal-only debug hook. Not intended for public consumption.
+  debug?: {
+    enabled?: boolean;
+    setGraphBox?: (box: {
+      x: number;
+      y: number;
+      width: number;
+      height: number;
+    }) => void;
+  };
+}
+
+export type GetSmartEdgeParams<
+  NodeDataType extends Record<string, unknown> = Record<string, unknown>,
+> = EdgeParams & {
+  options?: GetSmartEdgeOptions;
+  nodes: Node<NodeDataType>[];
+};
+
+export interface GetSmartEdgeReturn {
+  svgPathString: string;
+  edgeCenterX: number;
+  edgeCenterY: number;
+}
+
+export const getSmartEdge = <
+  NodeDataType extends Record<string, unknown> = Record<string, unknown>,
+>({
+  options = {},
+  nodes = [],
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourcePosition,
+  targetPosition,
+}: GetSmartEdgeParams<NodeDataType>): GetSmartEdgeReturn | Error => {
+  try {
+    const {
+      drawEdge = svgDrawSmoothLinePath,
+      generatePath = pathfindingAStarDiagonal,
+    } = options;
+
+    let { gridRatio = 10, nodePadding = 10 } = options;
+    gridRatio = toInteger(gridRatio);
+    nodePadding = toInteger(nodePadding);
+
+    // We use the node's information to generate bounding boxes for them
+    // and the graph
+    const { graphBox, nodeBoxes } = getBoundingBoxes(
+      nodes,
+      nodePadding,
+      gridRatio,
+    );
+
+    // Internal: publish computed bounding box for debugging visualization
+    if (options.debug?.enabled && options.debug.setGraphBox) {
+      options.debug.setGraphBox({
+        x: graphBox.topLeft.x,
+        y: graphBox.topLeft.y,
+        width: graphBox.width,
+        height: graphBox.height,
+      });
+    }
+
+    const source: PointInfo = {
+      x: sourceX,
+      y: sourceY,
+      position: sourcePosition,
+    };
+
+    const target: PointInfo = {
+      x: targetX,
+      y: targetY,
+      position: targetPosition,
+    };
+
+    // With this information, we can create a 2D grid representation of
+    // our graph, that tells us where in the graph there is a "free" space or not
+    const { grid, start, end } = createGrid(
+      graphBox,
+      nodeBoxes,
+      source,
+      target,
+      gridRatio,
+    );
+
+    // We then can use the grid representation to do pathfinding
+    const generatePathResult = generatePath(grid, start, end);
+
+    const fullPath = generatePathResult;
+
+    // Here we convert the grid path to a sequence of graph coordinates.
+    const graphPath = fullPath.map((gridPoint) => {
+      const [x, y] = gridPoint;
+      const graphPoint = gridToGraphPoint(
+        { x, y },
+        graphBox.xMin,
+        graphBox.yMin,
+        gridRatio,
+      );
+      return [graphPoint.x, graphPoint.y];
+    });
+
+    // Finally, we can use the graph path to draw the edge
+    const svgPathString = drawEdge(source, target, graphPath);
+
+    // Compute the edge's middle point using the full path, so users can use
+    // it to position their custom labels
+    const index = Math.floor(fullPath.length / 2);
+    const middlePoint = fullPath[index];
+    const [middleX, middleY] = middlePoint;
+    const { x: edgeCenterX, y: edgeCenterY } = gridToGraphPoint(
+      { x: middleX, y: middleY },
+      graphBox.xMin,
+      graphBox.yMin,
+      gridRatio,
+    );
+
+    return { svgPathString, edgeCenterX, edgeCenterY };
+  } catch (error) {
+    if (error instanceof Error) {
+      return error;
+    } else {
+      return new Error(`Unknown error: ${String(error)}`);
+    }
+  }
+};
+
+export type GetSmartEdgeFunction = typeof getSmartEdge;

package/src/index.tsx

@@ -0,0 +1,18 @@
+export { SmartBezierEdge } from "./SmartBezierEdge";
+export { SmartStraightEdge } from "./SmartStraightEdge";
+export { SmartStepEdge } from "./SmartStepEdge";
+export { getSmartEdge } from "./getSmartEdge";
+export {
+  svgDrawSmoothLinePath,
+  svgDrawStraightLinePath,
+} from "./functions/drawSvgPath";
+export {
+  pathfindingAStarDiagonal,
+  pathfindingAStarNoDiagonal,
+} from "./functions/generatePath";
+
+export type { GetSmartEdgeOptions } from "./getSmartEdge";
+export type { SVGDrawFunction } from "./functions/drawSvgPath";
+export type { PathFindingFunction } from "./functions/generatePath";
+export type { Grid, GridNode } from "./pathfinding/grid";
+export type { XYPosition } from "@xyflow/react";

package/src/internal/SmartEdgeDebug.tsx

@@ -0,0 +1,43 @@
+import { useMemo, useState } from "react";
+import type { PropsWithChildren } from "react";
+import type {
+  SmartEdgeGraphBox,
+  SmartEdgeDebugContextValue,
+} from "./useSmartEdgeDebug";
+import { SmartEdgeDebugContext } from "./useSmartEdgeDebug";
+
+interface SmartEdgeDebugProviderProps {
+  value?: boolean;
+}
+
+export const SmartEdgeDebugProvider = ({
+  value = true,
+  children,
+}: PropsWithChildren<SmartEdgeDebugProviderProps>) => {
+  const [graphBox, setGraphBoxState] = useState<SmartEdgeGraphBox>(null);
+
+  const setGraphBox = (next: SmartEdgeGraphBox) => {
+    setGraphBoxState((prev) => {
+      if (
+        prev?.x === next?.x &&
+        prev?.y === next?.y &&
+        prev?.width === next?.width &&
+        prev?.height === next?.height
+      ) {
+        return prev;
+      }
+      return next;
+    });
+  };
+
+  const contextValue = useMemo<SmartEdgeDebugContextValue>(
+    () => ({ enabled: value, graphBox, setGraphBox }),
+    [value, graphBox],
+  );
+
+  return (
+    <SmartEdgeDebugContext.Provider value={contextValue}>
+      {children}
+    </SmartEdgeDebugContext.Provider>
+  );
+};

package/src/internal/SmartEdgeDebugOverlay.tsx

@@ -0,0 +1,24 @@
+import { memo } from "react";
+import type { CSSProperties } from "react";
+import { useSmartEdgeDebug } from "./useSmartEdgeDebug";
+
+export const SmartEdgeDebugOverlay = memo(() => {
+  const { enabled, graphBox } = useSmartEdgeDebug();
+
+  if (!enabled || !graphBox) return null;
+
+  const style: CSSProperties = {
+    position: "absolute",
+    left: graphBox.x,
+    top: graphBox.y,
+    width: graphBox.width,
+    height: graphBox.height,
+    pointerEvents: "none",
+    border: "1px solid red",
+    backgroundColor: "transparent",
+    boxSizing: "border-box",
+    zIndex: 1,
+  };
+
+  return <div style={style} data-testid="smart-edge-debug-overlay" />;
+});

package/src/internal/useSmartEdgeDebug.ts

@@ -0,0 +1,26 @@
+import { createContext, useContext } from "react";
+
+export type SmartEdgeGraphBox = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+} | null;
+
+export interface SmartEdgeDebugContextValue {
+  enabled: boolean;
+  graphBox: SmartEdgeGraphBox;
+  setGraphBox: (next: SmartEdgeGraphBox) => void;
+}
+
+export const SmartEdgeDebugContext = createContext<SmartEdgeDebugContextValue>({
+  enabled: false,
+  graphBox: null,
+  setGraphBox: () => {
+    // Do nothing
+  },
+});
+
+export const useSmartEdgeDebug = (): SmartEdgeDebugContextValue => {
+  return useContext(SmartEdgeDebugContext);
+};

package/src/pathfinding/aStar.ts

@@ -0,0 +1,134 @@
+// Based on https://github.com/qiao/PathFinding.js
+
+import type { Grid, GridNode } from "./grid";
+import type { DiagonalMovement } from "./types.ts";
+
+export interface AStarOptions {
+  diagonalMovement?: DiagonalMovement;
+  heuristic?: (dx: number, dy: number) => number;
+  weight?: number;
+}
+
+const manhattan = (dx: number, dy: number): number => dx + dy;
+
+const octile = (dx: number, dy: number): number => {
+  const F = Math.SQRT2 - 1;
+  return dx < dy ? F * dx + dy : F * dy + dx;
+};
+
+const reconstructPath = (endNode: GridNode): number[][] => {
+  const path: number[][] = [];
+  let node: GridNode | undefined = endNode;
+
+  while (node) {
+    path.push([node.x, node.y]);
+    node = node.parent;
+  }
+
+  return path.reverse();
+};
+
+const getHeuristic = (
+  diagonalMovement: DiagonalMovement,
+): ((dx: number, dy: number) => number) => {
+  if (diagonalMovement === "Never") return manhattan;
+  return octile;
+};
+
+const selectNodeWithLowestEstimatedTotalCost = (
+  openList: GridNode[],
+): GridNode => {
+  let bestIdx = 0;
+
+  for (let i = 1; i < openList.length; i++) {
+    if (
+      (openList[i].estimatedTotalCost ?? Infinity) <
+      (openList[bestIdx].estimatedTotalCost ?? Infinity)
+    ) {
+      bestIdx = i;
+    }
+  }
+
+  return openList.splice(bestIdx, 1)[0];
+};
+
+const processNeighbor = (
+  neighbor: GridNode,
+  current: GridNode,
+  end: GridNode,
+  openList: GridNode[],
+  heuristic: (dx: number, dy: number) => number,
+  weight: number,
+): void => {
+  if (neighbor.closed) return;
+
+  const dx = Math.abs(neighbor.x - current.x);
+  const dy = Math.abs(neighbor.y - current.y);
+
+  const tentativeG =
+    (current.costFromStart ?? 0) + (dx === 0 || dy === 0 ? 1 : Math.SQRT2);
+
+  if (!neighbor.opened || tentativeG < (neighbor.costFromStart ?? Infinity)) {
+    neighbor.costFromStart = tentativeG;
+
+    neighbor.heuristicCostToGoal =
+      neighbor.heuristicCostToGoal ??
+      weight *
+        heuristic(Math.abs(neighbor.x - end.x), Math.abs(neighbor.y - end.y));
+
+    neighbor.estimatedTotalCost =
+      (neighbor.costFromStart ?? 0) + (neighbor.heuristicCostToGoal ?? 0);
+
+    neighbor.parent = current;
+
+    if (!neighbor.opened) {
+      neighbor.opened = true;
+      openList.push(neighbor);
+    }
+  }
+};
+
+export const createAStarFinder = (opts: AStarOptions = {}) => {
+  const diagonalMovement: DiagonalMovement = opts.diagonalMovement ?? "Never";
+  const heuristic = opts.heuristic ?? getHeuristic(diagonalMovement);
+  const weight = opts.weight ?? 1;
+
+  const findPath = (
+    startX: number,
+    startY: number,
+    endX: number,
+    endY: number,
+    grid: Grid,
+  ): number[][] => {
+    const start = grid.getNodeAt(startX, startY);
+    const end = grid.getNodeAt(endX, endY);
+
+    // Open list implemented as a simple array with linear min search for clarity
+    const openList: GridNode[] = [];
+
+    start.costFromStart = 0;
+    start.heuristicCostToGoal = 0;
+    start.estimatedTotalCost = 0;
+    start.opened = true;
+    openList.push(start);
+
+    while (openList.length > 0) {
+      const node = selectNodeWithLowestEstimatedTotalCost(openList);
+      node.closed = true;
+
+      if (node === end) {
+        return reconstructPath(end);
+      }
+
+      const neighbors = grid.getNeighbors(node, diagonalMovement);
+      for (const neighbor of neighbors) {
+        processNeighbor(neighbor, node, end, openList, heuristic, weight);
+      }
+    }
+
+    // no path found
+    return [];
+  };
+
+  return { findPath };
+};

package/src/pathfinding/grid.ts

@@ -0,0 +1,141 @@
+// Based on https://github.com/qiao/PathFinding.js
+import type { DiagonalMovement } from "./types.ts";
+
+// A modern, typed, functional replacement for PathFinding.js Grid
+// Provides the same runtime API shape used by finders/utilities:
+// - width, height, nodes[][]
+// - getNodeAt, isWalkableAt, setWalkableAt, getNeighbors, clone
+
+export interface GridNode {
+  x: number;
+  y: number;
+  walkable: boolean;
+  // A* search metadata (set during pathfinding)
+  costFromStart?: number;
+  heuristicCostToGoal?: number;
+  estimatedTotalCost?: number;
+  opened?: boolean;
+  closed?: boolean;
+  parent?: GridNode;
+}
+
+export interface Grid {
+  width: number;
+  height: number;
+  nodes: GridNode[][]; // nodes[row][col] i.e., nodes[y][x]
+
+  getNodeAt: (x: number, y: number) => GridNode;
+  isWalkableAt: (x: number, y: number) => boolean;
+  setWalkableAt: (x: number, y: number, walkable: boolean) => void;
+  getNeighbors: (
+    node: GridNode,
+    diagonalMovement: DiagonalMovement,
+  ) => GridNode[];
+  isInside: (x: number, y: number) => boolean;
+  clone: () => Grid;
+}
+
+const createNodes = (
+  width: number,
+  height: number,
+  matrix?: (number | boolean)[][],
+): GridNode[][] => {
+  const rows: GridNode[][] = new Array<GridNode[]>(height);
+  for (let y = 0; y < height; y++) {
+    const row: GridNode[] = new Array<GridNode>(width);
+    for (let x = 0; x < width; x++) {
+      // PathFinding.js semantics: a truthy matrix cell means non-walkable
+      // (e.g., 1 indicates obstacle). Falsy (0) means walkable.
+      const cell = matrix ? matrix[y]?.[x] : undefined;
+      const isBlocked = !!cell;
+      const walkable = matrix ? !isBlocked : true;
+      row[x] = { x, y, walkable };
+    }
+    rows[y] = row;
+  }
+  return rows;
+};
+
+const withinBounds = (width: number, height: number, x: number, y: number) =>
+  x >= 0 && x < width && y >= 0 && y < height;
+
+/**
+ * Create a grid with the given width/height. Optionally accepts a matrix
+ * of booleans/numbers indicating obstacles (truthy = blocked, falsy/0 = walkable).
+ */
+export const createGrid = (
+  width: number,
+  height: number,
+  matrix?: (number | boolean)[][],
+): Grid => {
+  const nodes = createNodes(width, height, matrix);
+
+  const getNodeAt = (x: number, y: number): GridNode => nodes[y][x];
+
+  const isWalkableAt = (x: number, y: number): boolean =>
+    withinBounds(width, height, x, y) && nodes[y][x].walkable;
+
+  const setWalkableAt = (x: number, y: number, walkable: boolean): void => {
+    if (!withinBounds(width, height, x, y)) return;
+    nodes[y][x].walkable = walkable;
+  };
+
+  // Diagonal movement policy using string literal union values:
+  // "Always", "Never", "IfAtMostOneObstacle", "OnlyWhenNoObstacles"
+  const getNeighbors = (
+    node: GridNode,
+    diagonalMovement: import("./types.ts").DiagonalMovement,
+  ): GridNode[] => {
+    const x = node.x;
+    const y = node.y;
+    const neighbors: GridNode[] = [];
+
+    // ↑, →, ↓, ←
+    const s0 = isWalkableAt(x, y - 1);
+    const s1 = isWalkableAt(x + 1, y);
+    const s2 = isWalkableAt(x, y + 1);
+    const s3 = isWalkableAt(x - 1, y);
+
+    if (s0) neighbors.push(getNodeAt(x, y - 1));
+    if (s1) neighbors.push(getNodeAt(x + 1, y));
+    if (s2) neighbors.push(getNodeAt(x, y + 1));
+    if (s3) neighbors.push(getNodeAt(x - 1, y));
+
+    // Diagonals: ↗, ↘, ↙, ↖
+    const d0Walkable = isWalkableAt(x + 1, y - 1);
+    const d1Walkable = isWalkableAt(x + 1, y + 1);
+    const d2Walkable = isWalkableAt(x - 1, y + 1);
+    const d3Walkable = isWalkableAt(x - 1, y - 1);
+
+    if (diagonalMovement === "Never") {
+      return neighbors;
+    }
+
+    // default: "Always"
+    if (d0Walkable) neighbors.push(getNodeAt(x + 1, y - 1));
+    if (d1Walkable) neighbors.push(getNodeAt(x + 1, y + 1));
+    if (d2Walkable) neighbors.push(getNodeAt(x - 1, y + 1));
+    if (d3Walkable) neighbors.push(getNodeAt(x - 1, y - 1));
+    return neighbors;
+  };
+
+  const clone = (): Grid => {
+    // Recreate the original matrix semantics: truthy = blocked
+    const clonedMatrix: number[][] = nodes.map((row) =>
+      row.map((node) => (node.walkable ? 0 : 1)),
+    );
+    return createGrid(width, height, clonedMatrix);
+  };
+
+  return {
+    width,
+    height,
+    nodes,
+    getNodeAt,
+    isWalkableAt,
+    setWalkableAt,
+    getNeighbors,
+    isInside: (x: number, y: number) => withinBounds(width, height, x, y),
+    clone,
+  };
+};

package/src/pathfinding/types.ts

@@ -0,0 +1,3 @@
+// Shared types for pathfinding
+
+export type DiagonalMovement = "Always" | "Never";

package/src/stories/CustomLabel.tsx

@@ -0,0 +1,94 @@
+import { useNodes, BezierEdge } from "@xyflow/react";
+import { getSmartEdge } from "../getSmartEdge";
+import type { EdgeProps } from "@xyflow/react";
+
+const size = 20;
+
+export function SmartEdgeCustomLabel(props: EdgeProps) {
+  const {
+    id,
+    sourcePosition,
+    targetPosition,
+    sourceX,
+    sourceY,
+    targetX,
+    targetY,
+    style,
+    markerStart,
+    markerEnd,
+  } = props;
+
+  const nodes = useNodes();
+
+  const getSmartEdgeResponse = getSmartEdge({
+    sourcePosition,
+    targetPosition,
+    sourceX,
+    sourceY,
+    targetX,
+    targetY,
+    nodes,
+  });
+
+  if (getSmartEdgeResponse instanceof Error) {
+    return <BezierEdge {...props} />;
+  }
+
+  const { edgeCenterX, edgeCenterY, svgPathString } = getSmartEdgeResponse;
+
+  return (
+    <>
+      <path
+        style={style}
+        className="react-flow__edge-path"
+        d={svgPathString}
+        markerEnd={markerEnd}
+        markerStart={markerStart}
+      />
+      <foreignObject
+        width={size}
+        height={size}
+        x={edgeCenterX - size / 2}
+        y={edgeCenterY - size / 2}
+        style={{
+          background: "transparent",
+          width: "minContent",
+          height: "minContent",
+          display: "flex",
+          justifyContent: "center",
+          alignItems: "center",
+          minHeight: "40px",
+        }}
+        requiredExtensions="http://www.w3.org/1999/xhtml"
+      >
+        <div
+          style={{
+            display: "flex",
+            justifyContent: "center",
+            alignItems: "center",
+            flexDirection: "column",
+          }}
+        >
+          <button
+            style={{
+              width: "20px",
+              height: "20px",
+              background: "#eee",
+              border: "1px solid #fff",
+              cursor: "pointer",
+              borderRadius: "50%",
+              fontSize: "12px",
+              lineHeight: "1",
+            }}
+            onClick={() => {
+              alert(`Clicked on edge with id ${id}`);
+            }}
+            type="button"
+          >
+            x
+          </button>
+        </div>
+      </foreignObject>
+    </>
+  );
+}