feat(core): add EdgePathParams type to edge utils (#1479)

* feat(core): add `EdgePathParams` type to edge utils

* chore(changeset): add

* chore(core): cleanup jsdocs

Author: bcakmakoglu

.changeset/twenty-chicken-mix.md

@@ -0,0 +1,5 @@
+---
+"@vue-flow/core": minor
+---
+
+Add `EdgePathParams` type and export it

packages/core/src/components/Edges/utils/bezier.ts

@@ -1,4 +1,5 @@
 import { Position } from '../../../types'
+import type { EdgePathParams } from './general'
 import { getBezierEdgeCenter } from './general'
 
 export interface GetBezierPathParams {
@@ -51,15 +52,31 @@ function getControlWithCurvature({ pos, x1, y1, x2, y2, c }: GetControlWithCurva
   return [ctX, ctY]
 }
 
-export function getBezierPath({
-  sourceX,
-  sourceY,
-  sourcePosition = Position.Bottom,
-  targetX,
-  targetY,
-  targetPosition = Position.Top,
-  curvature = 0.25,
-}: GetBezierPathParams): [path: string, labelX: number, labelY: number, offsetX: number, offsetY: number] {
+/**
+ * Get a bezier path from source to target handle
+ * @public
+ *
+ * @param bezierPathParams
+ * @param bezierPathParams.sourceX - The x position of the source handle
+ * @param bezierPathParams.sourceY - The y position of the source handle
+ * @param bezierPathParams.sourcePosition - The position of the source handle (default: Position.Bottom)
+ * @param bezierPathParams.targetX - The x position of the target handle
+ * @param bezierPathParams.targetY - The y position of the target handle
+ * @param bezierPathParams.targetPosition - The position of the target handle (default: Position.Top)
+ * @param bezierPathParams.curvature - The curvature of the edge (default: 0.25)
+ * @returns A path string you can use in an SVG, the labelX and labelY position (center of path) and offsetX, offsetY between source handle and label
+ */
+export function getBezierPath(bezierPathParams: GetBezierPathParams): EdgePathParams {
+  const {
+    sourceX,
+    sourceY,
+    sourcePosition = Position.Bottom,
+    targetX,
+    targetY,
+    targetPosition = Position.Top,
+    curvature = 0.25,
+  } = bezierPathParams
+
   const [sourceControlX, sourceControlY] = getControlWithCurvature({
     pos: sourcePosition,
     x1: sourceX,

packages/core/src/components/Edges/utils/general.ts

@@ -1,3 +1,5 @@
+export type EdgePathParams = [path: string, labelX: number, labelY: number, offsetX: number, offsetY: number]
+
 // this is used for straight edges and simple smoothstep edges (LTR, RTL, BTT, TTB)
 export function getSimpleEdgeCenter({
   sourceX,

packages/core/src/components/Edges/utils/simple-bezier.ts

@@ -1,4 +1,5 @@
 import { Position } from '../../../types'
+import type { EdgePathParams } from './general'
 import { getBezierEdgeCenter } from './general'
 
 export interface GetSimpleBezierPathParams {
@@ -35,14 +36,29 @@ function getControl({ pos, x1, y1, x2, y2 }: GetControlParams): [number, number]
   return [ctX, ctY]
 }
 
-export function getSimpleBezierPath({
-  sourceX,
-  sourceY,
-  sourcePosition = Position.Bottom,
-  targetX,
-  targetY,
-  targetPosition = Position.Top,
-}: GetSimpleBezierPathParams): [path: string, labelX: number, labelY: number, offsetX: number, offsetY: number] {
+/**
+ * Get a simple bezier path from source to target handle (no curvature)
+ * @public
+ *
+ * @param simpleBezierPathParams
+ * @param simpleBezierPathParams.sourceX - The x position of the source handle
+ * @param simpleBezierPathParams.sourceY - The y position of the source handle
+ * @param simpleBezierPathParams.sourcePosition - The position of the source handle (default: Position.Bottom)
+ * @param simpleBezierPathParams.targetX - The x position of the target handle
+ * @param simpleBezierPathParams.targetY - The y position of the target handle
+ * @param simpleBezierPathParams.targetPosition - The position of the target handle (default: Position.Top)
+ * @returns A path string you can use in an SVG, the labelX and labelY position (center of path) and offsetX, offsetY between source handle and label
+ */
+export function getSimpleBezierPath(simpleBezierPathParams: GetSimpleBezierPathParams): EdgePathParams {
+  const {
+    sourceX,
+    sourceY,
+    sourcePosition = Position.Bottom,
+    targetX,
+    targetY,
+    targetPosition = Position.Top,
+  } = simpleBezierPathParams
+
   const [sourceControlX, sourceControlY] = getControl({
     pos: sourcePosition,
     x1: sourceX,

packages/core/src/components/Edges/utils/smoothstep.ts

@@ -1,5 +1,6 @@
 import type { XYPosition } from '../../../types'
 import { Position } from '../../../types'
+import type { EdgePathParams } from './general'
 import { getSimpleEdgeCenter } from './general'
 
 export interface GetSmoothStepPathParams {
@@ -196,27 +197,32 @@ function getBend(a: XYPosition, b: XYPosition, c: XYPosition, size: number): str
 
 /**
  * Get a smooth step path from source to target handle
- * @param params
- * @param params.sourceX - The x position of the source handle
- * @param params.sourceY - The y position of the source handle
- * @param params.sourcePosition - The position of the source handle (default: Position.Bottom)
- * @param params.targetX - The x position of the target handle
- * @param params.targetY - The y position of the target handle
- * @param params.targetPosition - The position of the target handle (default: Position.Top)
+ * @public
+ *
+ * @param smoothStepPathParams
+ * @param smoothStepPathParams.sourceX - The x position of the source handle
+ * @param smoothStepPathParams.sourceY - The y position of the source handle
+ * @param smoothStepPathParams.sourcePosition - The position of the source handle (default: Position.Bottom)
+ * @param smoothStepPathParams.targetX - The x position of the target handle
+ * @param smoothStepPathParams.targetY - The y position of the target handle
+ * @param smoothStepPathParams.targetPosition - The position of the target handle (default: Position.Top)
+ * @param smoothStepPathParams.borderRadius - The border radius of the edge (default: 5)
  * @returns A path string you can use in an SVG, the labelX and labelY position (center of path) and offsetX, offsetY between source handle and label
  */
-export function getSmoothStepPath({
-  sourceX,
-  sourceY,
-  sourcePosition = Position.Bottom,
-  targetX,
-  targetY,
-  targetPosition = Position.Top,
-  borderRadius = 5,
-  centerX,
-  centerY,
-  offset = 20,
-}: GetSmoothStepPathParams): [path: string, labelX: number, labelY: number, offsetX: number, offsetY: number] {
+export function getSmoothStepPath(smoothStepPathParams: GetSmoothStepPathParams): EdgePathParams {
+  const {
+    sourceX,
+    sourceY,
+    sourcePosition = Position.Bottom,
+    targetX,
+    targetY,
+    targetPosition = Position.Top,
+    borderRadius = 5,
+    centerX,
+    centerY,
+    offset = 20,
+  } = smoothStepPathParams
+
   const [points, labelX, labelY, offsetX, offsetY] = getPoints({
     source: { x: sourceX, y: sourceY },
     sourcePosition,

packages/core/src/components/Edges/utils/straight.ts

@@ -1,3 +1,4 @@
+import type { EdgePathParams } from './general'
 import { getSimpleEdgeCenter } from './general'
 
 export interface GetStraightPathParams {
@@ -7,12 +8,20 @@ export interface GetStraightPathParams {
   targetY: number
 }
 
-export function getStraightPath({
-  sourceX,
-  sourceY,
-  targetX,
-  targetY,
-}: GetStraightPathParams): [path: string, labelX: number, labelY: number, offsetX: number, offsetY: number] {
+/**
+ * Get a straight path from source to target handle
+ * @public
+ *
+ * @param straightEdgeParams
+ * @param straightEdgeParams.sourceX - The x position of the source handle
+ * @param straightEdgeParams.sourceY - The y position of the source handle
+ * @param straightEdgeParams.targetX - The x position of the target handle
+ * @param straightEdgeParams.targetY - The y position of the target handle
+ * @returns A path string you can use in an SVG, the labelX and labelY position (center of path) and offsetX, offsetY between source handle and label
+ */
+export function getStraightPath(straightEdgeParams: GetStraightPathParams): EdgePathParams {
+  const { sourceX, sourceY, targetX, targetY } = straightEdgeParams
+
   const [centerX, centerY, offsetX, offsetY] = getSimpleEdgeCenter({
     sourceX,
     sourceY,