From 1f671bd48f06230da841fdd1d7a312413ef16d03 Mon Sep 17 00:00:00 2001
From: Dimitri POSTOLOV <dmytropostolov@gmail.com>
Date: Sun, 6 Apr 2025 04:41:00 +0200
Subject: [PATCH] Improve TSDoc comments for `type ReconnectEdgeOptions` and
 `getViewportForBounds`

---
 .changeset/lazy-avocados-talk.md           |  5 +++++
 packages/system/src/utils/edges/general.ts | 19 +++++++++++--------
 packages/system/src/utils/general.ts       | 16 ++++++++--------
 3 files changed, 24 insertions(+), 16 deletions(-)
 create mode 100644 .changeset/lazy-avocados-talk.md

diff --git a/.changeset/lazy-avocados-talk.md b/.changeset/lazy-avocados-talk.md
new file mode 100644
index 00000000..f17b232f
--- /dev/null
+++ b/.changeset/lazy-avocados-talk.md
@@ -0,0 +1,5 @@
+---
+'@xyflow/system': patch
+---
+
+Improve TSDoc comments for `type ReconnectEdgeOptions` and `getViewportForBounds`
diff --git a/packages/system/src/utils/edges/general.ts b/packages/system/src/utils/edges/general.ts
index 7f98d00f..c094ab0b 100644
--- a/packages/system/src/utils/edges/general.ts
+++ b/packages/system/src/utils/edges/general.ts
@@ -92,9 +92,9 @@ const connectionExists = (edge: EdgeBase, edges: EdgeBase[]) => {
 /**
  * This util is a convenience function to add a new Edge to an array of edges. It also performs some validation to make sure you don't add an invalid edge or duplicate an existing one.
  * @public
- * @param edgeParams - Either an Edge or a Connection you want to add
- * @param edges -  The array of all current edges
- * @returns A new array of edges with the new edge added
+ * @param edgeParams - Either an `Edge` or a `Connection` you want to add.
+ * @param edges - The array of all current edges.
+ * @returns A new array of edges with the new edge added.
  *
  * @remarks If an edge with the same `target` and `source` already exists (and the same
  *`targetHandle` and `sourceHandle` if those are set), then this util won't add
@@ -137,6 +137,10 @@ export const addEdge = <EdgeType extends EdgeBase>(
 };
 
 export type ReconnectEdgeOptions = {
+  /**
+   * Should the id of the old edge be replaced with the new connection id.
+   * @default true
+   */
   shouldReplaceId?: boolean;
 };
 
@@ -145,11 +149,10 @@ export type ReconnectEdgeOptions = {
  *This searches your edge array for an edge with a matching `id` and updates its
  *properties with the connection you provide.
  * @public
- * @param oldEdge - The edge you want to update
- * @param newConnection - The new connection you want to update the edge with
- * @param edges - The array of all current edges
- * @param options.shouldReplaceId - should the id of the old edge be replaced with the new connection id
- * @returns the updated edges array
+ * @param oldEdge - The edge you want to update.
+ * @param newConnection - The new connection you want to update the edge with.
+ * @param edges - The array of all current edges.
+ * @returns The updated edges array.
  *
  * @example
  * ```js
diff --git a/packages/system/src/utils/general.ts b/packages/system/src/utils/general.ts
index 5b4c6995..67743b5d 100644
--- a/packages/system/src/utils/general.ts
+++ b/packages/system/src/utils/general.ts
@@ -275,16 +275,16 @@ function calculateAppliedPaddings(bounds: Rect, x: number, y: number, zoom: numb
 }
 
 /**
- * Returns a viewport that encloses the given bounds with optional padding.
+ * Returns a viewport that encloses the given bounds with padding.
  * @public
  * @remarks You can determine bounds of nodes with {@link getNodesBounds} and {@link getBoundsOfRects}
- * @param bounds - Bounds to fit inside viewport
- * @param width - Width of the viewport
- * @param height  - Height of the viewport
- * @param minZoom - Minimum zoom level of the resulting viewport
- * @param maxZoom - Maximum zoom level of the resulting viewport
- * @param padding - Optional padding around the bounds
- * @returns A transforned {@link Viewport} that encloses the given bounds which you can pass to e.g. {@link setViewport}
+ * @param bounds - Bounds to fit inside viewport.
+ * @param width - Width of the viewport.
+ * @param height  - Height of the viewport.
+ * @param minZoom - Minimum zoom level of the resulting viewport.
+ * @param maxZoom - Maximum zoom level of the resulting viewport.
+ * @param padding - Padding around the bounds.
+ * @returns A transformed {@link Viewport} that encloses the given bounds which you can pass to e.g. {@link setViewport}.
  * @example
  * const { x, y, zoom } = getViewportForBounds(
  * { x: 0, y: 0, width: 100, height: 100},