fix: improve TSDoc comments for HandleProps, NodeBase and InternalNodeBase

packages/system/src/types/handles.ts

@@ -15,29 +15,43 @@ export type Handle = {
 
 export type HandleProps = {
   /**
-   * Type of the handle
+   * Type of the handle.
+   * @default "source"
    * @example HandleType.Source, HandleType.Target
    */
   type: HandleType;
   /**
-   * Position of the handle
-   * @example Position.TopLeft, Position.TopRight,
-   * Position.BottomLeft, Position.BottomRight
+   * The position of the handle relative to the node. In a horizontal flow source handles are
+   * typically `Position.Right` and in a vertical flow they are typically `Position.Top`.
+   * @default Position.Top
+   * @example Position.TopLeft, Position.TopRight, Position.BottomLeft, Position.BottomRight
    */
   position: Position;
-  /** Should you be able to connect to/from this handle */
+  /**
+   * Should you be able to connect to/from this handle.
+   * @default true
+   */
   isConnectable?: boolean;
-  /** Should you be able to connect from this handle */
+  /**
+   * Dictates whether a connection can start from this handle.
+   * @default true
+   */
   isConnectableStart?: boolean;
-  /** Should you be able to connect to this handle */
+  /**
+   * Dictates whether a connection can end on this handle.
+   * @default true
+   */
   isConnectableEnd?: boolean;
   /**
-   * Callback if connection is valid
+   * Called when a connection is dragged to this handle. You can use this callback to perform some
+   * custom validation logic based on the connection target and source, for example. Where possible,
+   * we recommend you move this logic to the `isValidConnection` prop on the main ReactFlow
+   * component for performance reasons.
    * @remarks connection becomes an edge if isValidConnection returns true
    */
   isValidConnection?: IsValidConnection;
   /**
-   * Id of the handle
+   * Id of the handle.
    * @remarks optional if there is only one handle of this type
    */
   id?: string | null;

packages/system/src/types/nodes.ts

@@ -12,52 +12,62 @@ export type NodeBase<
   NodeData extends Record<string, unknown> = Record<string, unknown>,
   NodeType extends string = string
 > = {
-  /** Unique id of a node */
+  /** Unique id of a node. */
   id: string;
   /**
-   * Position of a node on the pane
+   * Position of a node on the pane.
    * @example { x: 0, y: 0 }
    */
   position: XYPosition;
-  /** Arbitrary data passed to a node */
+  /** Arbitrary data passed to a node. */
   data: NodeData;
-  /** Type of node defined in nodeTypes */
+  /** Type of node defined in `nodeTypes`. */
   type?: NodeType;
   /**
-   * Only relevant for default, source, target nodeType. controls source position
+   * Only relevant for default, source, target nodeType. Controls source position.
    * @example 'right', 'left', 'top', 'bottom'
    */
   sourcePosition?: Position;
   /**
-   * Only relevant for default, source, target nodeType. controls target position
+   * Only relevant for default, source, target nodeType. Controls target position.
    * @example 'right', 'left', 'top', 'bottom'
    */
   targetPosition?: Position;
+  /** Whether or not the node should be visible on the canvas. */
   hidden?: boolean;
   selected?: boolean;
-  /** True, if node is being dragged */
+  /** Whether or not the node is currently being dragged. */
   dragging?: boolean;
+  /** Whether or not the node is able to be dragged. */
   draggable?: boolean;
   selectable?: boolean;
   connectable?: boolean;
   deletable?: boolean;
+  /**
+   * A class name that can be applied to elements inside the node that allows those elements to act
+   * as drag handles, letting the user drag the node by clicking and dragging on those elements.
+   */
   dragHandle?: string;
   width?: number;
   height?: number;
   initialWidth?: number;
   initialHeight?: number;
-  /** Parent node id, used for creating sub-flows */
+  /** Parent node id, used for creating sub-flows. */
   parentId?: string;
   zIndex?: number;
   /**
-   * Boundary a node can be moved in
+   * Boundary a node can be moved in.
    * @example 'parent' or [[0, 0], [100, 100]]
    */
   extent?: 'parent' | CoordinateExtent;
+  /**
+   * When `true`, the parent node will automatically expand if this node is dragged to the edge of
+   * the parent node's bounds.
+   */
   expandParent?: boolean;
   ariaLabel?: string;
   /**
-   * Origin of the node relative to it's position
+   * Origin of the node relative to its position.
    * @example
    * [0.5, 0.5] // centers the node
    * [0, 0] // top left
@@ -71,7 +81,7 @@ export type NodeBase<
   };
 };
 
-export type InternalNodeBase<NodeType extends NodeBase = NodeBase> = NodeType & {
+export type InternalNodeBase<NodeType extends NodeBase = NodeBase> = Omit<NodeType, 'measured'> & {
   measured: {
     width?: number;
     height?: number;
@@ -99,11 +109,11 @@ export type NodeProps<NodeType extends NodeBase> = Pick<
   'id' | 'data' | 'width' | 'height' | 'sourcePosition' | 'targetPosition' | 'dragHandle' | 'parentId'
 > &
   Required<Pick<NodeType, 'type' | 'dragging' | 'zIndex' | 'selectable' | 'deletable' | 'selected' | 'draggable'>> & {
-    /** whether a node is connectable or not */
+    /** Whether a node is connectable or not. */
     isConnectable: boolean;
-    /** position absolute x value */
+    /** Position absolute x value. */
     positionAbsoluteX: number;
-    /** position absolute x value */
+    /** Position absolute y value. */
     positionAbsoluteY: number;
   };