From d4eb8d52d0e26e9534ec5fc347211ce91d1ddd32 Mon Sep 17 00:00:00 2001
From: Dimitri POSTOLOV <dmytropostolov@gmail.com>
Date: Tue, 1 Apr 2025 20:49:08 +0200
Subject: [PATCH] fix: improve TSDoc comments for `ViewportHelperFunctions` and
 `NodeToolbarProps`

---
 .changeset/pink-toes-care.md                    |  5 +++++
 .../additional-components/NodeToolbar/types.ts  | 11 ++++++-----
 packages/react/src/types/general.ts             | 17 +++++++++++------
 3 files changed, 22 insertions(+), 11 deletions(-)
 create mode 100644 .changeset/pink-toes-care.md

diff --git a/.changeset/pink-toes-care.md b/.changeset/pink-toes-care.md
new file mode 100644
index 00000000..67f016a0
--- /dev/null
+++ b/.changeset/pink-toes-care.md
@@ -0,0 +1,5 @@
+---
+'@xyflow/react': patch
+---
+
+fix: improve TSDoc comments for `ViewportHelperFunctions` and `NodeToolbarProps`
diff --git a/packages/react/src/additional-components/NodeToolbar/types.ts b/packages/react/src/additional-components/NodeToolbar/types.ts
index 96756983..6655547d 100644
--- a/packages/react/src/additional-components/NodeToolbar/types.ts
+++ b/packages/react/src/additional-components/NodeToolbar/types.ts
@@ -10,12 +10,12 @@ export type NodeToolbarProps = HTMLAttributes<HTMLDivElement> & {
    * of nodes.
    */
   nodeId?: string | string[];
-  /** If true, node toolbar is visible even if node is not selected */
+  /** If `true`, node toolbar is visible even if node is not selected. */
   isVisible?: boolean;
   /**
-   * Position of the toolbar relative to the node
-   * @example Position.TopLeft, Position.TopRight,
-   * Position.BottomLeft, Position.BottomRight
+   * Position of the toolbar relative to the node.
+   * @default Position.Top
+   * @example Position.TopLeft, Position.TopRight, Position.BottomLeft, Position.BottomRight
    */
   position?: Position;
   /**
@@ -24,7 +24,8 @@ export type NodeToolbarProps = HTMLAttributes<HTMLDivElement> & {
    */
   offset?: number;
   /**
-   * Align the toolbar relative to the node
+   * Align the toolbar relative to the node.
+   * @default "center"
    * @example Align.Start, Align.Center, Align.End
    */
   align?: Align;
diff --git a/packages/react/src/types/general.ts b/packages/react/src/types/general.ts
index 11021b3a..98302a86 100644
--- a/packages/react/src/types/general.ts
+++ b/packages/react/src/types/general.ts
@@ -131,14 +131,15 @@ export type ViewportHelperFunctions = {
    */
   zoomOut: ZoomInOut;
   /**
-   * Sets the current zoom level.
+   * Zoom the viewport to a given zoom level. Passing in a `duration` will animate the viewport to
+   * the new zoom level.
    *
    * @param zoomLevel - the zoom level to set
    * @param options.duration - optional duration. If set, a transition will be applied
    */
   zoomTo: ZoomTo;
   /**
-   * Returns the current zoom level.
+   * Get the current zoom level of the viewport.
    *
    * @returns current zoom as a number
    */
@@ -157,7 +158,8 @@ export type ViewportHelperFunctions = {
    */
   getViewport: GetViewport;
   /**
-   * Sets the center of the view to the given position.
+   * Center the viewport on a given position. Passing in a `duration` will animate the viewport to
+   * the new position.
    *
    * @param x - x position
    * @param y - y position
@@ -165,14 +167,17 @@ export type ViewportHelperFunctions = {
    */
   setCenter: SetCenter;
   /**
-   * Fits the view to the given bounds .
+   * A low-level utility function to fit the viewport to a given rectangle. By passing in a
+   * `duration`, the viewport will animate from its current position to the new position. The
+   * `padding` option can be used to add space around the bounds.
    *
    * @param bounds - the bounds ({ x: number, y: number, width: number, height: number }) to fit the view to
    * @param options.padding - optional padding
    */
   fitBounds: FitBounds;
   /**
-   * Converts a screen / client position to a flow position.
+   * With this function you can translate a screen pixel position to a flow position. It is useful
+   * for implementing drag and drop from a sidebar for example.
    *
    * @param clientPosition - the screen / client position. When you are working with events you can use event.clientX and event.clientY
    * @param options.snapToGrid - if true, the converted position will be snapped to the grid
@@ -183,7 +188,7 @@ export type ViewportHelperFunctions = {
    */
   screenToFlowPosition: (clientPosition: XYPosition, options?: { snapToGrid: boolean }) => XYPosition;
   /**
-   * Converts a flow position to a screen / client position.
+   * Translate a position inside the flow's canvas to a screen pixel position.
    *
    * @param flowPosition - the screen / client position. When you are working with events you can use event.clientX and event.clientY
    * @returns position as { x: number, y: number }