Merge pull request #5171 from dimaMachina/tsdoc2-17

Improve TSDoc comments for `ReactFlowProps`

.changeset/bright-rabbits-remember.md

@@ -0,0 +1,5 @@
+---
+'@xyflow/react': patch
+---
+
+Improve TSDoc comments for `ReactFlowProps`

packages/react/src/types/component-props.ts

@@ -54,6 +54,7 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
   extends Omit<HTMLAttributes<HTMLDivElement>, 'onError'> {
   /**
    * An array of nodes to render in a controlled flow.
+   * @default []
    * @example
    * const nodes = [
    *  {
@@ -67,6 +68,7 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
   nodes?: NodeType[];
   /**
    * An array of edges to render in a controlled flow.
+   * @default []
    * @example
    * const edges = [
    *  {
@@ -102,41 +104,56 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
    * }
    */
   defaultEdgeOptions?: DefaultEdgeOptions;
-  /** This event handler is called when a user clicks on a node */
+  /** This event handler is called when a user clicks on a node. */
   onNodeClick?: NodeMouseHandler<NodeType>;
-  /** This event handler is called when a user double clicks on a node */
+  /** This event handler is called when a user double-clicks on a node. */
   onNodeDoubleClick?: NodeMouseHandler<NodeType>;
-  /** This event handler is called when mouse of a user enters a node */
+  /** This event handler is called when mouse of a user enters a node. */
   onNodeMouseEnter?: NodeMouseHandler<NodeType>;
-  /** This event handler is called when mouse of a user moves over a node */
+  /** This event handler is called when mouse of a user moves over a node. */
   onNodeMouseMove?: NodeMouseHandler<NodeType>;
-  /** This event handler is called when mouse of a user leaves a node */
+  /** This event handler is called when mouse of a user leaves a node. */
   onNodeMouseLeave?: NodeMouseHandler<NodeType>;
-  /** This event handler is called when a user right clicks on a node */
+  /** This event handler is called when a user right-clicks on a node. */
   onNodeContextMenu?: NodeMouseHandler<NodeType>;
-  /** This event handler is called when a user starts to drag a node */
+  /** This event handler is called when a user starts to drag a node. */
   onNodeDragStart?: OnNodeDrag<NodeType>;
-  /** This event handler is called when a user drags a node */
+  /** This event handler is called when a user drags a node. */
   onNodeDrag?: OnNodeDrag<NodeType>;
-  /** This event handler is called when a user stops dragging a node */
+  /** This event handler is called when a user stops dragging a node. */
   onNodeDragStop?: OnNodeDrag<NodeType>;
-  /** This event handler is called when a user clicks on an edge */
+  /** This event handler is called when a user clicks on an edge. */
   onEdgeClick?: (event: ReactMouseEvent, edge: EdgeType) => void;
-  /** This event handler is called when a user right clicks on an edge */
+  /** This event handler is called when a user right-clicks on an edge. */
   onEdgeContextMenu?: EdgeMouseHandler<EdgeType>;
-  /** This event handler is called when mouse of a user enters an edge */
+  /** This event handler is called when mouse of a user enters an edge. */
   onEdgeMouseEnter?: EdgeMouseHandler<EdgeType>;
-  /** This event handler is called when mouse of a user moves over an edge */
+  /** This event handler is called when mouse of a user moves over an edge. */
   onEdgeMouseMove?: EdgeMouseHandler<EdgeType>;
-  /** This event handler is called when mouse of a user leaves an edge */
+  /** This event handler is called when mouse of a user leaves an edge. */
   onEdgeMouseLeave?: EdgeMouseHandler<EdgeType>;
-  /** This event handler is called when a user double clicks on an edge */
+  /** This event handler is called when a user double-clicks on an edge. */
   onEdgeDoubleClick?: EdgeMouseHandler<EdgeType>;
+  /**
+   * This handler is called when the source or target of a reconnectable edge is dragged from the
+   * current node. It will fire even if the edge's source or target do not end up changing.
+   *
+   * You can use the `reconnectEdge` utility to convert the connection to a new edge.
+   */
   onReconnect?: OnReconnect<EdgeType>;
+  /**
+   * This event fires when the user begins dragging the source or target of an editable edge.
+   */
   onReconnectStart?: (event: ReactMouseEvent, edge: EdgeType, handleType: HandleType) => void;
+  /**
+   * This event fires when the user releases the source or target of an editable edge. It is called
+   * even if an edge update does not occur.
+   *
+   */
   onReconnectEnd?: (event: MouseEvent | TouchEvent, edge: EdgeType, handleType: HandleType) => void;
   /**
-   * This event handler is called when a Node is updated
+   * Use this event handler to add interactivity to a controlled flow.
+   * It is called on node drag, select, and move.
    * @example // Use NodesState hook to create edges and get onNodesChange handler
    * import ReactFlow, { useNodesState } from '@xyflow/react';
    * const [edges, setNodes, onNodesChange] = useNodesState(initialNodes);
@@ -154,7 +171,8 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
    */
   onNodesChange?: OnNodesChange<NodeType>;
   /**
-   * This event handler is called when a Edge is updated
+   * Use this event handler to add interactivity to a controlled flow. It is called on edge select
+   * and remove.
    * @example // Use EdgesState hook to create edges and get onEdgesChange handler
    * import ReactFlow, { useEdgesState } from '@xyflow/react';
    * const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);
@@ -171,25 +189,28 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
    * return (<ReactFlow onEdgesChange={onEdgesChange} {...rest} />)
    */
   onEdgesChange?: OnEdgesChange<EdgeType>;
-  /** This event handler gets called when a Node is deleted */
+  /** This event handler gets called when a node is deleted. */
   onNodesDelete?: OnNodesDelete<NodeType>;
-  /** This event handler gets called when a Edge is deleted */
+  /** This event handler gets called when an edge is deleted. */
   onEdgesDelete?: OnEdgesDelete<EdgeType>;
-  /** This event handler gets called when a Node or Edge is deleted */
+  /** This event handler gets called when a node or edge is deleted. */
   onDelete?: OnDelete<NodeType, EdgeType>;
-  /** This event handler gets called when a user starts to drag a selection box */
+  /** This event handler gets called when a user starts to drag a selection box. */
   onSelectionDragStart?: SelectionDragHandler<NodeType>;
-  /** This event handler gets called when a user drags a selection box */
+  /** This event handler gets called when a user drags a selection box. */
   onSelectionDrag?: SelectionDragHandler<NodeType>;
-  /** This event handler gets called when a user stops dragging a selection box */
+  /** This event handler gets called when a user stops dragging a selection box. */
   onSelectionDragStop?: SelectionDragHandler<NodeType>;
   onSelectionStart?: (event: ReactMouseEvent) => void;
   onSelectionEnd?: (event: ReactMouseEvent) => void;
+  /**
+   * This event handler is called when a user right-clicks on a node selection.
+   */
   onSelectionContextMenu?: (event: ReactMouseEvent, nodes: NodeType[]) => void;
   /**
    * When a connection line is completed and two nodes are connected by the user, this event fires with the new connection.
    *
-   * You can use the addEdge utility to convert the connection to a complete edge.
+   * You can use the `addEdge` utility to convert the connection to a complete edge.
    * @example // Use helper function to update edges onConnect
    * import ReactFlow, { addEdge } from '@xyflow/react';
    *
@@ -201,50 +222,70 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
    * return (<ReactFlow onConnect={onConnect} {...rest} />)
    */
   onConnect?: OnConnect;
-  /** This event handler gets called when a user starts to drag a connection line */
+  /** This event handler gets called when a user starts to drag a connection line. */
   onConnectStart?: OnConnectStart;
-  /** This event handler gets called when a user stops dragging a connection line */
+  /**
+   * This callback will fire regardless of whether a valid connection could be made or not. You can
+   * use the second `connectionState` parameter to have different behavior when a connection was
+   * unsuccessful.
+   */
   onConnectEnd?: OnConnectEnd;
   onClickConnectStart?: OnConnectStart;
   onClickConnectEnd?: OnConnectEnd;
-  /** This event handler gets called when a flow has finished initializing */
+  /**
+   * The `onInit` callback is called when the viewport is initialized. At this point you can use the
+   * instance to call methods like `fitView` or `zoomTo`.
+   */
   onInit?: OnInit<NodeType, EdgeType>;
   /** This event handler is called while the user is either panning or zooming the viewport. */
   onMove?: OnMove;
-  /** This event handler gets called when a user starts to pan or zoom the viewport */
+  /** This event handler is called when the user begins to pan or zoom the viewport. */
   onMoveStart?: OnMoveStart;
-  /** This event handler gets called when a user stops panning or zooming the viewport */
+  /**
+   * This event handler is called when panning or zooming viewport movement stops.
+   * If the movement is not user-initiated, the event parameter will be `null`.
+   */
   onMoveEnd?: OnMoveEnd;
-  /** This event handler gets called when a user changes group of selected elements in the flow */
+  /** This event handler gets called when a user changes group of selected elements in the flow. */
   onSelectionChange?: OnSelectionChangeFunc<NodeType, EdgeType>;
-  /** This event handler gets called when user scroll inside the pane */
+  /** This event handler gets called when user scroll inside the pane. */
   onPaneScroll?: (event?: WheelEvent) => void;
-  /** This event handler gets called when user clicks inside the pane */
+  /** This event handler gets called when user clicks inside the pane. */
   onPaneClick?: (event: ReactMouseEvent) => void;
-  /** This event handler gets called when user right clicks inside the pane */
+  /** This event handler gets called when user right clicks inside the pane. */
   onPaneContextMenu?: (event: ReactMouseEvent | MouseEvent) => void;
-  /** This event handler gets called when mouse enters the pane */
+  /** This event handler gets called when mouse enters the pane. */
   onPaneMouseEnter?: (event: ReactMouseEvent) => void;
-  /** This event handler gets called when mouse moves over the pane */
+  /** This event handler gets called when mouse moves over the pane. */
   onPaneMouseMove?: (event: ReactMouseEvent) => void;
-  /** This event handler gets called when mouse leaves the pane */
+  /** This event handler gets called when mouse leaves the pane. */
   onPaneMouseLeave?: (event: ReactMouseEvent) => void;
   /**
-   * Distance that the mouse can move between mousedown/up that will trigger a click
+   * Distance that the mouse can move between mousedown/up that will trigger a click.
    * @default 0
    */
   paneClickDistance?: number;
   /**
-   * Distance that the mouse can move between mousedown/up that will trigger a click
+   * Distance that the mouse can move between mousedown/up that will trigger a click.
    * @default 0
    */
   nodeClickDistance?: number;
-  /** This handler gets called before the user deletes nodes or edges and provides a way to abort the deletion by returning false. */
+  /**
+   * This handler is called before nodes or edges are deleted, allowing the deletion to be aborted
+   * by returning `false` or modified by returning updated nodes and edges.
+   */
   onBeforeDelete?: OnBeforeDelete<NodeType, EdgeType>;
   /**
    * Custom node types to be available in a flow.
    *
-   * React Flow matches a node's type to a component in the nodeTypes object.
+   * React Flow matches a node's type to a component in the `nodeTypes` object.
+   * @TODO check if @default is correct
+   * @default {
+   *   input: InputNode,
+   *   default: DefaultNode,
+   *   output: OutputNode,
+   *   group: GroupNode
+   * }
    * @example
    * import CustomNode from './CustomNode';
    *
@@ -254,7 +295,15 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
   /**
    * Custom edge types to be available in a flow.
    *
-   * React Flow matches an edge's type to a component in the edgeTypes object.
+   * React Flow matches an edge's type to a component in the `edgeTypes` object.
+   * @TODO check if @default is correct
+   * @default {
+   *   default: BezierEdge,
+   *   straight: StraightEdge,
+   *   step: StepEdge,
+   *   smoothstep: SmoothStepEdge,
+   *   simplebezier: SimpleBezier
+   * }
    * @example
    * import CustomEdge from './CustomEdge';
    *
@@ -265,91 +314,110 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
    * The type of edge path to use for connection lines.
    *
    * Although created edges can be of any type, React Flow needs to know what type of path to render for the connection line before the edge is created!
+   * @default ConnectionLineType.Bezier
    */
   connectionLineType?: ConnectionLineType;
-  /** Styles to be applied to the connection line */
+  /** Styles to be applied to the connection line. */
   connectionLineStyle?: CSSProperties;
-  /** React Component to be used as a connection line */
+  /** React Component to be used as a connection line. */
   connectionLineComponent?: ConnectionLineComponent<NodeType>;
-  /** Styles to be applied to the container of the connection line */
+  /** Styles to be applied to the container of the connection line. */
   connectionLineContainerStyle?: CSSProperties;
   /**
-   * 'strict' connection mode will only allow you to connect source handles to target handles.
+   * A loose connection mode will allow you to connect handles with differing types, including
-   *
+   * source-to-source connections. However, it does not support target-to-target connections. Strict
-   * 'loose' connection mode will allow you to connect handles of any type to one another.
+   * mode allows only connections between source handles and target handles.
    * @default 'strict'
    */
   connectionMode?: ConnectionMode;
   /**
-   * Pressing down this key deletes all selected nodes & edges.
+   * If set, pressing the key or chord will delete any selected nodes and edges. Passing an array
+   * represents multiple keys that can be pressed.
+   *
+   * For example, `["Delete", "Backspace"]` will delete selected elements when either key is pressed.
    * @default 'Backspace'
    */
   deleteKeyCode?: KeyCode | null;
   /**
-   * If a key is set, you can pan the viewport while that key is held down even if panOnScroll is set to false.
+   * If set, holding this key will let you click and drag to draw a selection box around multiple
+   * nodes and edges. Passing an array represents multiple keys that can be pressed.
    *
-   * By setting this prop to null you can disable this functionality.
+   * For example, `["Shift", "Meta"]` will allow you to draw a selection box when either key is
-   * @default 'Space'
+   * pressed.
+   * @default 'Shift'
    */
   selectionKeyCode?: KeyCode | null;
-  /** Select multiple elements with a selection box, without pressing down selectionKey */
+  /**
+   * Select multiple elements with a selection box, without pressing down `selectionKey`.
+   * @default false
+   */
   selectionOnDrag?: boolean;
   /**
-   * When set to "partial", when the user creates a selection box by click and dragging nodes that are only partially in the box are still selected.
+   * When set to `"partial"`, when the user creates a selection box by click and dragging nodes that
+   * are only partially in the box are still selected.
    * @default 'full'
    */
   selectionMode?: SelectionMode;
   /**
-   * If a key is set, you can pan the viewport while that key is held down even if panOnScroll is set to false.
+   * If a key is set, you can pan the viewport while that key is held down even if `panOnScroll`
+   * is set to `false`.
    *
-   * By setting this prop to null you can disable this functionality.
+   * By setting this prop to `null` you can disable this functionality.
    * @default 'Space'
    */
   panActivationKeyCode?: KeyCode | null;
   /**
    * Pressing down this key you can select multiple elements by clicking.
-   * @default 'Meta' for macOS, "Ctrl" for other systems
+   * @default "Meta" for macOS, "Control" for other systems
    */
   multiSelectionKeyCode?: KeyCode | null;
   /**
-   * If a key is set, you can zoom the viewport while that key is held down even if panOnScroll is set to false.
+   * If a key is set, you can zoom the viewport while that key is held down even if `panOnScroll`
+   * is set to `false`.
    *
-   * By setting this prop to null you can disable this functionality.
+   * By setting this prop to `null` you can disable this functionality.
-   * @default 'Meta' for macOS, "Ctrl" for other systems
+   * @default "Meta" for macOS, "Control" for other systems
    *
    */
   zoomActivationKeyCode?: KeyCode | null;
-  /** Set this prop to make the flow snap to the grid */
+  /** When enabled, nodes will snap to the grid when dragged. */
   snapToGrid?: boolean;
   /**
-   * Grid all nodes will snap to
+   * If `snapToGrid` is enabled, this prop configures the grid that nodes will snap to.
    * @example [20, 20]
    */
   snapGrid?: SnapGrid;
   /**
-   * You can enable this optimisation to instruct Svelte Flow to only render nodes and edges that would be visible in the viewport.
+   * You can enable this optimisation to instruct React Flow to only render nodes and edges that would be visible in the viewport.
    *
    * This might improve performance when you have a large number of nodes and edges but also adds an overhead.
    * @default false
    */
   onlyRenderVisibleElements?: boolean;
   /**
-   * Controls if all nodes should be draggable
+   * Controls whether all nodes should be draggable or not. Individual nodes can override this
+   * setting by setting their `draggable` prop. If you want to use the mouse handlers on
+   * non-draggable nodes, you need to add the `"nopan"` class to those nodes.
    * @default true
    */
   nodesDraggable?: boolean;
   /**
-   * Controls if all nodes should be connectable to each other
+   * Controls whether all nodes should be connectable or not. Individual nodes can override this
+   * setting by setting their `connectable` prop.
    * @default true
    */
   nodesConnectable?: boolean;
   /**
-   * Controls if all nodes should be focusable
+   * When `true`, focus between nodes can be cycled with the `Tab` key and selected with the `Enter`
+   * key. This option can be overridden by individual nodes by setting their `focusable` prop.
    * @default true
    */
   nodesFocusable?: boolean;
   /**
-   * Defines nodes relative position to its coordinates
+   * The origin of the node to use when placing it in the flow or looking up its `x` and `y`
+   * position. An origin of `[0, 0]` means that a node's top left corner will be placed at the `x`
+   * and `y` position.
+   * @default [0, 0]
    * @example
    * [0, 0] // default, top left
    * [0.5, 0.5] // center
@@ -357,49 +425,57 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
    */
   nodeOrigin?: NodeOrigin;
   /**
-   * Controls if all edges should be focusable
+   * When `true`, focus between edges can be cycled with the `Tab` key and selected with the `Enter`
+   * key. This option can be overridden by individual edges by setting their `focusable` prop.
    * @default true
    */
   edgesFocusable?: boolean;
   /**
-   * Controls if all edges should be updateable
+   * Whether edges can be updated once they are created. When both this prop is `true` and an
+   * `onReconnect` handler is provided, the user can drag an existing edge to a new source or
+   * target. Individual edges can override this value with their reconnectable property.
    * @default true
    */
   edgesReconnectable?: boolean;
   /**
-   * Controls if all elements should (nodes & edges) be selectable
+   * When `true`, elements (nodes and edges) can be selected by clicking on them. This option can be
+   * overridden by individual elements by setting their `selectable` prop.
    * @default true
    */
   elementsSelectable?: boolean;
   /**
-   * If true, nodes get selected on drag
+   * If `true`, nodes get selected on drag.
    * @default true
    */
   selectNodesOnDrag?: boolean;
   /**
-   * Enableing this prop allows users to pan the viewport by clicking and dragging.
+   * Enabling this prop allows users to pan the viewport by clicking and dragging.
    *
    * You can also set this prop to an array of numbers to limit which mouse buttons can activate panning.
+   * @default true
    * @example [0, 2] // allows panning with the left and right mouse buttons
    * [0, 1, 2, 3, 4] // allows panning with all mouse buttons
    */
   panOnDrag?: boolean | number[];
   /**
-   * Minimum zoom level
+   * Minimum zoom level.
    * @default 0.5
    */
   minZoom?: number;
   /**
-   * Maximum zoom level
+   * Maximum zoom level.
    * @default 2
    */
   maxZoom?: number;
-  /** Controlled viewport to be used instead of internal one */
+  /**
+   * When you pass a `viewport` prop, it's controlled, and you also need to pass `onViewportChange`
+   * to handle internal changes.
+   */
   viewport?: Viewport;
   /**
-   * Sets the initial position and zoom of the viewport.
+   * Sets the initial position and zoom of the viewport. If a default viewport is provided but
-   *
+   * `fitView` is enabled, the default viewport will be ignored.
-   * If a default viewport is provided but fitView is enabled, the default viewport will be ignored.
+   * @default { x: 0, y: 0, zoom: 1 }
    * @example
    * const initialViewport = {
    *  zoom: 0.5,
@@ -408,13 +484,14 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
    */
   defaultViewport?: Viewport;
   /**
-   * Gets called when the viewport changes.
+   * Used when working with a controlled viewport for updating the user viewport state.
    */
   onViewportChange?: (viewport: Viewport) => void;
   /**
-   * By default the viewport extends infinitely. You can use this prop to set a boundary.
+   * By default, the viewport extends infinitely. You can use this prop to set a boundary.
    *
    * The first pair of coordinates is the top left boundary and the second pair is the bottom right.
+   * @default [[-∞, -∞], [+∞, +∞]]
    * @example [[-1000, -10000], [1000, 1000]]
    */
   translateExtent?: CoordinateExtent;
@@ -424,51 +501,86 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
    */
   preventScrolling?: boolean;
   /**
-   * By default nodes can be placed on an infinite flow. You can use this prop to set a boundary.
+   * By default, nodes can be placed on an infinite flow. You can use this prop to set a boundary.
    *
    * The first pair of coordinates is the top left boundary and the second pair is the bottom right.
    * @example [[-1000, -10000], [1000, 1000]]
    */
   nodeExtent?: CoordinateExtent;
   /**
-   * Color of edge markers
+   * Color of edge markers.
-   * @example "#b1b1b7"
+   * @default '#b1b1b7'
    */
   defaultMarkerColor?: string;
-  /** Controls if the viewport should zoom by scrolling inside the container */
+  /**
+   * Controls if the viewport should zoom by scrolling inside the container.
+   * @default true
+   */
   zoomOnScroll?: boolean;
-  /** Controls if the viewport should zoom by pinching on a touch screen */
+  /**
+   * Controls if the viewport should zoom by pinching on a touch screen.
+   * @default true
+   */
   zoomOnPinch?: boolean;
   /**
-   * Controls if the viewport should pan by scrolling inside the container
+   * Controls if the viewport should pan by scrolling inside the container.
    *
-   * Can be limited to a specific direction with panOnScrollMode
+   * Can be limited to a specific direction with `panOnScrollMode`.
+   * @default false
    */
   panOnScroll?: boolean;
   /**
    * Controls how fast viewport should be panned on scroll.
    *
-   * Use togther with panOnScroll prop.
+   * Use together with `panOnScroll` prop.
+   * @default 0.5
    */
   panOnScrollSpeed?: number;
   /**
-   * This prop is used to limit the direction of panning when panOnScroll is enabled.
+   * This prop is used to limit the direction of panning when `panOnScroll` is enabled.
    *
-   * The "free" option allows panning in any direction.
+   * The `"free"` option allows panning in any direction.
    * @default "free"
    * @example "horizontal" | "vertical"
    */
   panOnScrollMode?: PanOnScrollMode;
-  /** Controls if the viewport should zoom by double clicking somewhere on the flow */
+  /**
+   * Controls if the viewport should zoom by double-clicking somewhere on the flow.
+   * @default true
+   */
   zoomOnDoubleClick?: boolean;
+  /**
+   * The radius around an edge connection that can trigger an edge reconnection.
+   * @default 10
+   */
   reconnectRadius?: number;
+  /**
+   * If a node is draggable, clicking and dragging that node will move it around the canvas. Adding
+   * the `"nodrag"` class prevents this behavior and this prop allows you to change the name of that
+   * class.
+   * @default "nodrag"
+   */
   noDragClassName?: string;
+  /**
+   * Typically, scrolling the mouse wheel when the mouse is over the canvas will zoom the viewport.
+   * Adding the `"nowheel"` class to an element n the canvas will prevent this behavior and this prop
+   * allows you to change the name of that class.
+   * @default "nowheel"
+   */
   noWheelClassName?: string;
+  /**
+   * If an element in the canvas does not stop mouse events from propagating, clicking and dragging
+   * that element will pan the viewport. Adding the `"nopan"` class prevents this behavior and this
+   * prop allows you to change the name of that class.
+   * @default "nopan"
+   */
   noPanClassName?: string;
-  /** If set, initial viewport will show all nodes & edges */
+  /** When `true`, the flow will be zoomed and panned to fit all the nodes initially provided. */
   fitView?: boolean;
   /**
-   * Options to be used in combination with fitView
+   * When you typically call `fitView` on a `ReactFlowInstance`, you can provide an object of
+   * options to customize its behavior. This prop lets you do the same for the initial `fitView`
+   * call.
    * @example
    * const fitViewOptions = {
    *  padding: 0.1,
@@ -481,15 +593,18 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
    */
   fitViewOptions?: FitViewOptions;
   /**
-   *The connectOnClick option lets you click or tap on a source handle to start a connection
+   * The `connectOnClick` option lets you click or tap on a source handle to start a connection
    * and then click on a target handle to complete the connection.
    *
-   * If you set this option to false, users will need to drag the connection line to the target
+   * If you set this option to `false`, users will need to drag the connection line to the target
    * handle to create a connection.
+   * @default true
    */
   connectOnClick?: boolean;
   /**
-   * Set position of the attribution
+   * By default, React Flow will render a small attribution in the bottom right corner of the flow.
+   *
+   * You can use this prop to change its position in case you want to place something else there.
    * @default 'bottom-right'
    * @example 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
    */
@@ -509,21 +624,23 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
   elevateNodesOnSelect?: boolean;
   /**
    * Enabling this option will raise the z-index of edges when they are selected.
-   * @default true
    */
   elevateEdgesOnSelect?: boolean;
   /**
-   * Can be set true if built-in keyboard controls should be disabled.
+   * You can use this prop to disable keyboard accessibility features such as selecting nodes or
+   * moving selected nodes with the arrow keys.
    * @default false
    */
   disableKeyboardA11y?: boolean;
   /**
-   * You can enable this prop to automatically pan the viewport while dragging a node.
+   * When `true`, the viewport will pan automatically when the cursor moves to the edge of the
+   * viewport while dragging a node.
    * @default true
    */
   autoPanOnNodeDrag?: boolean;
   /**
-   * You can enable this prop to automatically pan the viewport while dragging a node.
+   * When `true`, the viewport will pan automatically when the cursor moves to the edge of the
+   * viewport while creating a connection.
    * @default true
    */
   autoPanOnConnect?: boolean;
@@ -533,12 +650,12 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
    */
   autoPanSpeed?: number;
   /**
-   * You can enable this prop to automatically pan the viewport while making a new connection.
+   * The radius around a handle where you drop a connection line to create a new edge.
-   * @default true
+   * @default 20
    */
   connectionRadius?: number;
   /**
-   * Ocassionally something may happen that causes Svelte Flow to throw an error.
+   * Occasionally something may happen that causes React Flow to throw an error.
    *
    * Instead of exploding your application, we log a message to the console and then call this event handler.
    * You might use it for additional logging or to show a message to the user.
@@ -547,32 +664,33 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
   /**
    * This callback can be used to validate a new connection
    *
-   * If you return false, the edge will not be added to your flow.
+   * If you return `false`, the edge will not be added to your flow.
-   * If you have custom connection logic its preferred to use this callback over the isValidConnection prop on the handle component for performance reasons.
+   * If you have custom connection logic its preferred to use this callback over the
-   * @default (connection: Connection) => true
+   * `isValidConnection` prop on the handle component for performance reasons.
    */
   isValidConnection?: IsValidConnection<EdgeType>;
   /**
-   * With a threshold greater than zero you can control the distinction between node drag and click events.
+   * With a threshold greater than zero you can delay node drag events.
    *
    * If threshold equals 1, you need to drag the node 1 pixel before a drag event is fired.
+   *
+   * 1 is the default value, so clicks don't trigger drag events.
    * @default 1
    */
   nodeDragThreshold?: number;
-  /** Sets a fixed width for the flow */
+  /** Sets a fixed width for the flow. */
   width?: number;
-  /** Sets a fixed height for the flow */
+  /** Sets a fixed height for the flow. */
   height?: number;
   /**
-   * Controls color scheme used for styling the flow
+   * Controls color scheme used for styling the flow.
-   * @default 'system'
+   * @default 'light'
    * @example 'system' | 'light' | 'dark'
    */
   colorMode?: ColorMode;
   /**
-   * If set true, some debug information will be logged to the console like which events are fired.
+   * If set `true`, some debug information will be logged to the console like which events are fired.
-   *
+   * @default false
-   * @default undefined
    */
   debug?: boolean;
 }