From eb2a33c6dfb0629e851ab3a0f2cd70eca92efc42 Mon Sep 17 00:00:00 2001
From: Dimitri POSTOLOV <dmytropostolov@gmail.com>
Date: Sun, 6 Apr 2025 04:46:01 +0200
Subject: [PATCH] Improve TSDoc comments for `interface
 GetSimpleBezierPathParams` and `getSimpleBezierPath`

---
 .changeset/tall-dryers-smell.md                    |  5 +++++
 .../src/components/Edges/SimpleBezierEdge.tsx      | 14 ++++++++++++--
 .../react/src/components/StoreUpdater/index.tsx    |  2 +-
 packages/react/src/utils/changes.ts                | 12 ++++++------
 4 files changed, 24 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/tall-dryers-smell.md

diff --git a/.changeset/tall-dryers-smell.md b/.changeset/tall-dryers-smell.md
new file mode 100644
index 00000000..8c34da74
--- /dev/null
+++ b/.changeset/tall-dryers-smell.md
@@ -0,0 +1,5 @@
+---
+'@xyflow/react': patch
+---
+
+Improve TSDoc comments for `interface GetSimpleBezierPathParams` and `getSimpleBezierPath`
diff --git a/packages/react/src/components/Edges/SimpleBezierEdge.tsx b/packages/react/src/components/Edges/SimpleBezierEdge.tsx
index a11cbc1d..3d1cdb3d 100644
--- a/packages/react/src/components/Edges/SimpleBezierEdge.tsx
+++ b/packages/react/src/components/Edges/SimpleBezierEdge.tsx
@@ -7,9 +7,11 @@ import type { SimpleBezierEdgeProps } from '../../types';
 export interface GetSimpleBezierPathParams {
   sourceX: number;
   sourceY: number;
+  /** @default Position.Bottom */
   sourcePosition?: Position;
   targetX: number;
   targetY: number;
+  /** @default Position.Top */
   targetPosition?: Position;
 }
 
@@ -33,6 +35,14 @@ function getControl({ pos, x1, y1, x2, y2 }: GetControlParams): [number, number]
  * The `getSimpleBezierPath` util returns everything you need to render a simple
  * bezier edge between two nodes.
  * @public
+ * @returns
+ * - `path`: the path to use in an SVG `<path>` element.
+ * - `labelX`: the `x` position you can use to render a label for this edge.
+ * - `labelY`: the `y` position you can use to render a label for this edge.
+ * - `offsetX`: the absolute difference between the source `x` position and the `x` position of the
+ * middle of this path.
+ * - `offsetY`: the absolute difference between the source `y` position and the `y` position of the
+ * middle of this path.
  */
 export function getSimpleBezierPath({
   sourceX,
@@ -85,8 +95,8 @@ function createSimpleBezierEdge(params: { isInternal: boolean }) {
       sourceY,
       targetX,
       targetY,
-      sourcePosition = Position.Bottom,
-      targetPosition = Position.Top,
+      sourcePosition,
+      targetPosition,
       label,
       labelStyle,
       labelShowBg,
diff --git a/packages/react/src/components/StoreUpdater/index.tsx b/packages/react/src/components/StoreUpdater/index.tsx
index ac9122ba..5cad0358 100644
--- a/packages/react/src/components/StoreUpdater/index.tsx
+++ b/packages/react/src/components/StoreUpdater/index.tsx
@@ -11,7 +11,7 @@ import { useStore, useStoreApi } from '../../hooks/useStore';
 import type { Node, Edge, ReactFlowState, ReactFlowProps, FitViewOptions } from '../../types';
 import { defaultNodeOrigin } from '../../container/ReactFlow/init-values';
 
-// these fields exist in the global store and we need to keep them up to date
+// These fields exist in the global store, and we need to keep them up to date
 const reactFlowFieldsToTrack = [
   'nodes',
   'edges',
diff --git a/packages/react/src/utils/changes.ts b/packages/react/src/utils/changes.ts
index 0bc30e46..f1494bf4 100644
--- a/packages/react/src/utils/changes.ts
+++ b/packages/react/src/utils/changes.ts
@@ -147,9 +147,9 @@ function applyChange(change: any, element: any): any {
 /**
  * Drop in function that applies node changes to an array of nodes.
  * @public
- * @param changes - Array of changes to apply
- * @param nodes - Array of nodes to apply the changes to
- * @returns Array of updated nodes
+ * @param changes - Array of changes to apply.
+ * @param nodes - Array of nodes to apply the changes to.
+ * @returns Array of updated nodes.
  * @example
  *```tsx
  *import { useState, useCallback } from 'react';
@@ -185,9 +185,9 @@ export function applyNodeChanges<NodeType extends Node = Node>(
 /**
  * Drop in function that applies edge changes to an array of edges.
  * @public
- * @param changes - Array of changes to apply
- * @param edges - Array of edge to apply the changes to
- * @returns Array of updated edges
+ * @param changes - Array of changes to apply.
+ * @param edges - Array of edge to apply the changes to.
+ * @returns Array of updated edges.
  * @example
  * ```tsx
  *import { useState, useCallback } from 'react';