From 9e2e3c22a9c460d7e4895f594c0211656e1ac3b3 Mon Sep 17 00:00:00 2001
From: Dimitri POSTOLOV <dmytropostolov@gmail.com>
Date: Tue, 25 Mar 2025 18:58:01 +0100
Subject: [PATCH] fix: improve TSDoc comments for `ControlProps`

---
 .../additional-components/Controls/types.ts   | 42 +++++++++++++++----
 packages/system/src/types/general.ts          |  7 ++--
 2 files changed, 36 insertions(+), 13 deletions(-)

diff --git a/packages/react/src/additional-components/Controls/types.ts b/packages/react/src/additional-components/Controls/types.ts
index bccd1117..dad4813b 100644
--- a/packages/react/src/additional-components/Controls/types.ts
+++ b/packages/react/src/additional-components/Controls/types.ts
@@ -7,24 +7,42 @@ import type { FitViewOptions } from '../../types';
  * @expand
  */
 export type ControlProps = {
-  /** Show button for zoom in/out */
+  /**
+   * Whether or not to show the zoom in and zoom out buttons. These buttons will adjust the viewport
+   * zoom by a fixed amount each press.
+   * @default true
+   */
   showZoom?: boolean;
-  /** Show button for fit view */
+  /**
+   * Whether or not to show the fit view button. By default, this button will adjust the viewport so
+   * that all nodes are visible at once.
+   * @default true
+   */
   showFitView?: boolean;
-  /** Show button for toggling interactivity */
+  /**
+   * Show button for toggling interactivity
+   * @default true
+   */
   showInteractive?: boolean;
-  /** Options being used when fit view button is clicked */
+  /**
+   * Customise the options for the fit view button. These are the same options you would pass to the
+   * fitView function.
+   */
   fitViewOptions?: FitViewOptions;
-  /** Callback when zoom in button is clicked */
+  /** Called in addition the default zoom behavior when the zoom in button is clicked. */
   onZoomIn?: () => void;
-  /** Callback when zoom out button is clicked */
+  /** Called in addition the default zoom behavior when the zoom out button is clicked. */
   onZoomOut?: () => void;
-  /** Callback when fit view button is clicked */
+  /**
+   * Called when the fit view button is clicked. When this is not provided, the viewport will be
+   * adjusted so that all nodes are visible.
+   */
   onFitView?: () => void;
-  /** Callback when interactivity is toggled */
+  /** Called when the interactive (lock) button is clicked. */
   onInteractiveChange?: (interactiveStatus: boolean) => void;
   /**
    * Position of the controls on the pane
+   * @default PanelPosition.BottomLeft
    * @example PanelPosition.TopLeft, PanelPosition.TopRight,
    * PanelPosition.BottomLeft, PanelPosition.BottomRight
    */
@@ -32,9 +50,15 @@ export type ControlProps = {
   children?: ReactNode;
   /** Style applied to container */
   style?: React.CSSProperties;
-  /** ClassName applied to container */
+  /** Class name applied to container */
   className?: string;
+  /**
+   * @default 'React Flow controls'
+   */
   'aria-label'?: string;
+  /**
+   * @default 'vertical'
+   */
   orientation?: 'horizontal' | 'vertical';
 };
 
diff --git a/packages/system/src/types/general.ts b/packages/system/src/types/general.ts
index fc92bc7e..418902da 100644
--- a/packages/system/src/types/general.ts
+++ b/packages/system/src/types/general.ts
@@ -2,8 +2,7 @@
 import type { Selection as D3Selection } from 'd3-selection';
 import type { D3DragEvent, SubjectPosition } from 'd3-drag';
 import type { ZoomBehavior } from 'd3-zoom';
-// this is needed for the Selection type to include the transition function :/
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- this is needed for the Selection type to include the transition function :/
 import type { Transition } from 'd3-transition';
 
 import type { XYPosition, Rect, Position } from './utils';
@@ -41,14 +40,14 @@ export type Connection = {
 };
 
 /**
- * The `HandleConnection` type is an extention of a basic [Connection](/api-reference/types/connection) that includes the `edgeId`.
+ * The `HandleConnection` type is an extension of a basic [Connection](/api-reference/types/connection) that includes the `edgeId`.
  */
 export type HandleConnection = Connection & {
   edgeId: string;
 };
 
 /**
- * The `NodeConnection` type is an extention of a basic [Connection](/api-reference/types/connection) that includes the `edgeId`.
+ * The `NodeConnection` type is an extension of a basic [Connection](/api-reference/types/connection) that includes the `edgeId`.
  *
  */
 export type NodeConnection = Connection & {