From f0f378e5b6918c2c30d9dc1e32587063cb942d4e Mon Sep 17 00:00:00 2001
From: Dimitri POSTOLOV <dmytropostolov@gmail.com>
Date: Tue, 1 Apr 2025 20:46:13 +0200
Subject: [PATCH] fix: improve TSDoc comments for `Connection` and
 `ConnectionInProgress`

---
 .changeset/tall-knives-wink.md       |  5 +++++
 packages/system/src/types/general.ts | 17 +++++++++++++++++
 2 files changed, 22 insertions(+)
 create mode 100644 .changeset/tall-knives-wink.md

diff --git a/.changeset/tall-knives-wink.md b/.changeset/tall-knives-wink.md
new file mode 100644
index 00000000..c6b2f9b3
--- /dev/null
+++ b/.changeset/tall-knives-wink.md
@@ -0,0 +1,5 @@
+---
+'@xyflow/system': patch
+---
+
+fix: improve TSDoc comments for `Connection` and `ConnectionInProgress`
diff --git a/packages/system/src/types/general.ts b/packages/system/src/types/general.ts
index ac0d95b7..a2fba7dd 100644
--- a/packages/system/src/types/general.ts
+++ b/packages/system/src/types/general.ts
@@ -33,9 +33,13 @@ export type FitBounds = (bounds: Rect, options?: FitBoundsOptions) => Promise<bo
  * @public
  */
 export type Connection = {
+  /** The id of the node this connection originates from. */
   source: string;
+  /** The id of the node this connection terminates at. */
   target: string;
+  /** When not `null`, the id of the handle on the source node that this connection originates from. */
   sourceHandle: string | null;
+  /** When not `null`, the id of the handle on the target node that this connection terminates at. */
   targetHandle: string | null;
 };
 
@@ -240,15 +244,28 @@ export type NoConnection = {
   toNode: null;
 };
 export type ConnectionInProgress<NodeType extends InternalNodeBase = InternalNodeBase> = {
+  /** Indicates whether a connection is currently in progress. */
   inProgress: true;
+  /**
+   * If an ongoing connection is above a handle or inside the connection radius, this will be `true`
+   * or `false`, otherwise `null`.
+   */
   isValid: boolean | null;
+  /** Returns the xy start position or `null` if no connection is in progress. */
   from: XYPosition;
+  /** Returns the start handle or `null` if no connection is in progress. */
   fromHandle: Handle;
+  /** Returns the side (called position) of the start handle or `null` if no connection is in progress. */
   fromPosition: Position;
+  /** Returns the start node or `null` if no connection is in progress. */
   fromNode: NodeType;
+  /** Returns the xy end position or `null` if no connection is in progress. */
   to: XYPosition;
+  /** Returns the end handle or `null` if no connection is in progress. */
   toHandle: Handle | null;
+  /** Returns the side (called position) of the end handle or `null` if no connection is in progress. */
   toPosition: Position;
+  /** Returns the end node or `null` if no connection is in progress. */
   toNode: NodeType | null;
 };