chore(types): add tsdocs

packages/react/src/additional-components/Background/types.ts

@@ -1,11 +1,20 @@
 import { CSSProperties } from 'react';
 
+/**
+ * The three variants are exported as an enum for convenience. You can either import
+ * the enum and use it like `BackgroundVariant.Lines` or you can use the raw string
+ * value directly.
+ * @public
+ */
 export enum BackgroundVariant {
   Lines = 'lines',
   Dots = 'dots',
   Cross = 'cross',
 }
 
+/**
+ * @expand
+ */
 export type BackgroundProps = {
   id?: string;
   /** Color of the pattern */

packages/react/src/additional-components/Controls/Controls.tsx

@@ -143,8 +143,7 @@ ControlsComponent.displayName = 'Controls';
  *}
  *```
  *
- * @remarks To extend or customise the controls, you can use the [`<ControlButton />`](/api-reference/components/control-button)
+ * @remarks To extend or customise the controls, you can use the [`<ControlButton />`](/api-reference/components/control-button) component
- *component
  *
  */
 export const Controls = memo(ControlsComponent);

packages/react/src/additional-components/MiniMap/types.ts

@@ -58,6 +58,11 @@ export type MiniMapNodes<NodeType extends Node = Node> = Pick<
   onClick?: (event: MouseEvent, nodeId: string) => void;
 };
 
+/**
+ * The props that are passed to the MiniMapNode component
+ *
+ * @public
+ */
 export type MiniMapNodeProps = {
   id: string;
   x: number;

packages/react/src/additional-components/NodeToolbar/NodeToolbar.tsx

@@ -71,8 +71,7 @@ const storeSelector = (state: ReactFlowState) => ({
  *```
  * @remarks By default, the toolbar is only visible when a node is selected. If multiple
  * nodes are selected it will not be visible to prevent overlapping toolbars or
- *clutter. You can override this behavior by setting the `isVisible` prop to
+ * clutter. You can override this behavior by setting the `isVisible` prop to `true`.
- *`true`.
  */
 export function NodeToolbar({
   nodeId,

packages/react/src/components/EdgeLabelRenderer/index.tsx

@@ -10,8 +10,7 @@ const selector = (s: ReactFlowState) => s.domNode?.querySelector('.react-flow__e
  * Edges are SVG-based. If you want to render more complex labels you can use the
  * `<EdgeLabelRenderer />` component to access a div based renderer. This component
  * is a portal that renders the label in a `<div />` that is positioned on top of
- *the edges. You can see an example usage of the component in the [edge label renderer](/examples/edges/edge-label-renderer)
+ * the edges. You can see an example usage of the component in the [edge label renderer](/examples/edges/edge-label-renderer) example.
- *example.
  * @public
  *
  * @example

packages/react/src/components/Edges/BaseEdge.tsx

@@ -28,8 +28,8 @@ import type { BaseEdgeProps } from '../../types';
  *
  * @remarks If you want to use an edge marker with the [`<BaseEdge />`](/api-reference/components/base-edge) component,
  * you can pass the `markerStart` or `markerEnd` props passed to your custom edge
- *through to the [`<BaseEdge />`](/api-reference/components/base-edge) component. You can see all the props
+ * through to the [`<BaseEdge />`](/api-reference/components/base-edge) component.
- *passed to a custom edge by looking at the [`EdgeProps`](/api-reference/types/edge-props) type.
+ * You can see all the props passed to a custom edge by looking at the [`EdgeProps`](/api-reference/types/edge-props) type.
  */
 export function BaseEdge({
   path,

packages/react/src/components/Panel/index.tsx

@@ -6,9 +6,9 @@ import { useStore } from '../../hooks/useStore';
 import type { ReactFlowState } from '../../types';
 
 /**
- * The `<Panel />` component helps you position content above the viewport. It is
+ * The `<Panel />` component helps you position content above the viewport.
- *used internally by the [`<MiniMap />`](/api-reference/components/minimap) and [`<Controls />`](/api-reference/components/controls)
+ * It is used internally by the [`<MiniMap />`](/api-reference/components/minimap)
- *components.
+ * and [`<Controls />`](/api-reference/components/controls) components.
  *
  * @public
  *

packages/react/src/components/ReactFlowProvider/index.tsx

@@ -20,9 +20,8 @@ export type ReactFlowProviderProps = {
 };
 
 /**
- * The `<ReactFlowProvider />` component is a
+ * The `<ReactFlowProvider />` component is a [context provider](https://react.dev/learn/passing-data-deeply-with-context#)
- *[context provider](https://react.dev/learn/passing-data-deeply-with-context#) that
+ * that makes it possible to access a flow's internal state outside of the
- *makes it possible to access a flow's internal state outside of the
  * [`<ReactFlow />`](/api-reference/react-flow) component. Many of the hooks we
  * provide rely on this component to work.
  * @public

packages/react/src/components/ViewportPortal/index.tsx

@@ -7,9 +7,10 @@ import type { ReactFlowState } from '../../types';
 const selector = (s: ReactFlowState) => s.domNode?.querySelector('.react-flow__viewport-portal');
 
 /**
- * The `<ViewportPortal />` component can be used to add components to the same viewport of the flow where nodes and edges are rendered.
+ * The `<ViewportPortal />` component can be used to add components to the same viewport
- *This is useful when you want to render your own components that are adhere to the same coordinate system as the nodes & edges and are also
+ * of the flow where nodes and edges are rendered. This is useful when you want to render
- *affected by zooming and panning
+ * your own components that are adhere to the same coordinate system as the nodes & edges
+ * and are also affected by zooming and panning
  * @public
  * @example
  *

packages/react/src/container/ReactFlow/index.tsx

@@ -302,8 +302,8 @@ function ReactFlow<NodeType extends Node = Node, EdgeType extends Edge = Edge>(
 }
 
 /**
- * The `<ReactFlow />` component is the heart of your React Flow application. It
+ * The `<ReactFlow />` component is the heart of your React Flow application.
- *renders your nodes and edges and handles user interaction
+ * It renders your nodes and edges and handles user interaction
  *
  * @public
  *

packages/react/src/hooks/useInternalNode.ts

@@ -5,9 +5,9 @@ import { useStore } from './useStore';
 import type { InternalNode, Node } from '../types';
 
 /**
- * This hook returns the internal representation of a specific node. Components that use this hook
+ * This hook returns the internal representation of a specific node.
- *will re-render **whenever the node changes**, including when a node is selected
+ * Components that use this hook will re-render **whenever the node changes**,
- *or moved.
+ * including when a node is selected or moved.
  *
  * @public
  * @param id - id of the node

packages/react/src/types/edges.ts

@@ -19,6 +19,9 @@ import type {
 
 import { EdgeTypes, InternalNode, Node } from '.';
 
+/**
+ * @inline
+ */
 export type EdgeLabelOptions = {
   label?: string | ReactNode;
   labelStyle?: CSSProperties;
@@ -29,7 +32,8 @@ export type EdgeLabelOptions = {
 };
 
 /**
- * The Edge type is mainly used for the `edges` that get passed to the ReactFlow component
+ * An `Edge` is the complete description with everything React Flow needs
+ *to know in order to render it.
  * @public
  */
 export type Edge<
@@ -91,6 +95,12 @@ export type EdgeWrapperProps<EdgeType extends Edge = Edge> = {
   disableKeyboardA11y?: boolean;
 };
 
+/**
+ * Many properties on an [`Edge`](/api-reference/types/edge) are optional. When a new edge is created,
+ *the properties that are not provided will be filled in with the default values
+ *passed to the `defaultEdgeOptions` prop of the [`<ReactFlow />`](/api-reference/react-flow#defaultedgeoptions)
+ *component.
+ */
 export type DefaultEdgeOptions = DefaultEdgeOptionsBase<Edge>;
 
 export type EdgeTextProps = SVGAttributes<SVGElement> &
@@ -100,8 +110,10 @@ export type EdgeTextProps = SVGAttributes<SVGElement> &
   };
 
 /**
- * Custom edge component props
+ * When you implement a custom edge it is wrapped in a component that enables some
+ *basic functionality. The `EdgeProps` type is the props that are passed to this.
  * @public
+ * @expand
  */
 export type EdgeProps<EdgeType extends Edge = Edge> = Pick<
   EdgeType,
@@ -185,6 +197,13 @@ export type SimpleBezierEdgeProps = EdgeComponentProps;
 
 export type OnReconnect<EdgeType extends Edge = Edge> = (oldEdge: EdgeType, newConnection: Connection) => void;
 
+/**
+ * If you want to render a custom component for connection lines, you can set the
+ *`connectionLineComponent` prop on the [`<ReactFlow />`](/api-reference/react-flow#connection-connectionLineComponent)
+ *component. The `ConnectionLineComponentProps` are passed to your custom component.
+ *
+ * @public
+ */
 export type ConnectionLineComponentProps<NodeType extends Node = Node> = {
   connectionLineStyle?: CSSProperties;
   connectionLineType: ConnectionLineType;

packages/react/src/types/general.ts

@@ -64,12 +64,23 @@ export type OnSelectionChangeParams = {
 export type OnSelectionChangeFunc = (params: OnSelectionChangeParams) => void;
 
 export type FitViewParams<NodeType extends Node = Node> = FitViewParamsBase<NodeType>;
+
+/**
+ * When calling [`fitView`](/api-reference/types/react-flow-instance#fitview) these options
+ * can be used to customize the behaviour. For example, the `duration` option can be used to
+ * transform the viewport smoothly over a given amount of time.
+ *
+ * @public
+ */
 export type FitViewOptions<NodeType extends Node = Node> = FitViewOptionsBase<NodeType>;
 export type FitView = (fitViewOptions?: FitViewOptions) => Promise<boolean>;
 export type OnInit<NodeType extends Node = Node, EdgeType extends Edge = Edge> = (
   reactFlowInstance: ReactFlowInstance<NodeType, EdgeType>
 ) => void;
 
+/**
+ * @inline
+ */
 export type ViewportHelperFunctions = {
   /**
    * Zooms viewport in by 1.2.

packages/react/src/types/instance.ts

@@ -217,6 +217,14 @@ export type GeneralHelpers<NodeType extends Node = Node, EdgeType extends Edge =
   }) => NodeConnection[];
 };
 
+/**
+ * The `ReactFlowInstance` provides a collection of methods to query and manipulate
+ *the internal state of your flow. You can get an instance by using the
+ *[`useReactFlow`](/api-reference/hooks/use-react-flow) hook or attaching a listener to the
+ *[`onInit`](/api-reference/react-flow#event-oninit) event.
+ *
+ * @public
+ */
 export type ReactFlowInstance<NodeType extends Node = Node, EdgeType extends Edge = Edge> = GeneralHelpers<
   NodeType,
   EdgeType

packages/react/src/types/nodes.ts

@@ -4,7 +4,9 @@ import type { CoordinateExtent, NodeBase, OnError, NodeProps as NodePropsBase, I
 import { NodeTypes } from './general';
 
 /**
- * The node data structure that gets used for the nodes prop.
+ * The `Node` type represents everything React Flow needs to know about a given node.
+ * Many of these properties can be manipulated both by React Flow or by you, but
+ * some such as `width` and `height` should be considered read-only.
  * @public
  */
 export type Node<
@@ -18,9 +20,10 @@ export type Node<
 };
 
 /**
- * The node data structure that gets used for internal nodes.
+ * The `InternalNode` type is identical to the base [`Node`](/api-references/types/node)
- * There are some data structures added under node.internal
+ * type but is extended with some additional properties used internall by React
- * that are needed for tracking some properties
+ * Flow. Some functions and callbacks that return nodes may return an `InternalNode`.
+ *
  * @public
  */
 export type InternalNode<NodeType extends Node = Node> = InternalNodeBase<NodeType>;
@@ -60,4 +63,31 @@ export type BuiltInNode =
   | Node<{ label: string }, 'input' | 'output' | 'default'>
   | Node<Record<string, never>, 'group'>;
 
+/**
+ * When you implement a [custom node](/learn/customization/custom-nodes) it is
+ * wrapped in a component that enables basic functionality like selection and
+ * dragging. Your custom node receives `NodeProps` as props.
+ *
+ * @public
+ * @example
+ * ```tsx
+ *import { useState } from 'react';
+ *import { NodeProps, Node } from '@xyflow/react';
+ *
+ *export type CounterNode = Node<{ initialCount?: number }, 'counter'>;
+ *
+ *export default function CounterNode(props: NodeProps<CounterNode>) {
+ *  const [count, setCount] = useState(props.data?.initialCount ?? 0);
+ *
+ *  return (
+ *    <div>
+ *      <p>Count: {count}</p>
+ *      <button className="nodrag" onClick={() => setCount(count + 1)}>
+ *        Increment
+ *      </button>
+ *    </div>
+ *  );
+ *}
+ *```
+ */
 export type NodeProps<NodeType extends Node = Node> = NodePropsBase<NodeType>;

packages/react/src/utils/general.ts

@@ -4,9 +4,10 @@ import { isNodeBase, isEdgeBase } from '@xyflow/system';
 import type { Edge, Node } from '../types';
 
 /**
- * Test whether an object is useable as an [`Node`](/api-reference/types/node). In TypeScript
+ * Test whether an object is useable as an [`Node`](/api-reference/types/node).
- *this is a type guard that will narrow the type of whatever you pass in to
+ * In TypeScript this is a type guard that will narrow the type of whatever you pass in to
  * [`Node`](/api-reference/types/node) if it returns `true`.
+ *
  * @public
  * @remarks In TypeScript this is a type guard that will narrow the type of whatever you pass in to Node if it returns true
  * @param element - The element to test
@@ -25,9 +26,10 @@ export const isNode = <NodeType extends Node = Node>(element: unknown): element
   isNodeBase<NodeType>(element);
 
 /**
- * Test whether an object is useable as an [`Edge`](/api-reference/types/edge). In TypeScript
+ * Test whether an object is useable as an [`Edge`](/api-reference/types/edge).
- *this is a type guard that will narrow the type of whatever you pass in to
+ * In TypeScript this is a type guard that will narrow the type of whatever you pass in to
  * [`Edge`](/api-reference/types/edge) if it returns `true`.
+ *
  * @public
  * @remarks In TypeScript this is a type guard that will narrow the type of whatever you pass in to Edge if it returns true
  * @param element - The element to test

packages/svelte/src/lib/types/edges.ts

@@ -11,7 +11,9 @@ import type {
 import type { Node } from '$lib/types';
 
 /**
- * The Edge type is mainly used for the `edges` that get passed to the SvelteFlow component.
+ * An `Edge` is the complete description with everything React Flow needs
+ *to know in order to render it.
+ * @public
  */
 export type Edge<
   EdgeData extends Record<string, unknown> = Record<string, unknown>,

packages/system/src/types/edges.ts

@@ -103,6 +103,12 @@ export type EdgeMarker = {
 
 export type EdgeMarkerType = string | EdgeMarker;
 
+/**
+ * Edges may optionally have a marker on either end. The MarkerType type enumerates
+ * the options available to you when configuring a given marker.
+ *
+ * @public
+ */
 export enum MarkerType {
   Arrow = 'arrow',
   ArrowClosed = 'arrowclosed',

packages/system/src/types/general.ts

@@ -40,15 +40,28 @@ export type Connection = {
   targetHandle: string | null;
 };
 
-// TODO: remove in next version
+/**
+ * The `HandleConnection` type is an extention 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`.
+ *
+ */
 export type NodeConnection = Connection & {
   edgeId: string;
 };
 
+/**
+ * The `ConnectionMode` is used to set the mode of connection between nodes.
+ * The `Strict` mode is the default one and only allows source to target edges.
+ * `Loose` mode allows source to source and target to target edges as well.
+ *
+ * @public
+ */
 export enum ConnectionMode {
   Strict = 'strict',
   Loose = 'loose',
@@ -66,6 +79,9 @@ export type OnConnectEnd = (event: MouseEvent | TouchEvent, connectionState: Fin
 
 export type IsValidConnection = (edge: EdgeBase | Connection) => boolean;
 
+/**
+ * @inline
+ */
 export type FitViewParamsBase<NodeType extends NodeBase> = {
   nodes: Map<string, InternalNodeBase<NodeType>>;
   width: number;
@@ -75,6 +91,9 @@ export type FitViewParamsBase<NodeType extends NodeBase> = {
   maxZoom: number;
 };
 
+/**
+ * @inline
+ */
 export type FitViewOptionsBase<NodeType extends NodeBase = NodeBase> = {
   padding?: number;
   includeHiddenNodes?: boolean;
@@ -84,6 +103,17 @@ export type FitViewOptionsBase<NodeType extends NodeBase = NodeBase> = {
   nodes?: (NodeType | { id: string })[];
 };
 
+/**
+ * Internally, React Flow maintains a coordinate system that is independent of the
+ * rest of the page. The `Viewport` type tells you where in that system your flow
+ * is currently being display at and how zoomed in or out it is.
+ *
+ * @public
+ * @remarks A `Transform` has the same properties as the viewport, but they represent
+ * different things. Make sure you don't get them muddled up or things will start
+ * to look weird!
+ *
+ */
 export type Viewport = {
   x: number;
   y: number;
@@ -94,12 +124,23 @@ export type KeyCode = string | Array<string>;
 
 export type SnapGrid = [number, number];
 
+/**
+ * This enum is used to set the different modes of panning the viewport when the
+ * user scrolls. The `Free` mode allows the user to pan in any direction by scrolling
+ * with a device like a trackpad. The `Vertical` and `Horizontal` modes restrict
+ * scroll panning to only the vertical or horizontal axis, respectively.
+ *
+ * @public
+ */
 export enum PanOnScrollMode {
   Free = 'free',
   Vertical = 'vertical',
   Horizontal = 'horizontal',
 }
 
+/**
+ * @inline
+ */
 export type ViewportHelperFunctionOptions = {
   duration?: number;
 };
@@ -120,6 +161,14 @@ export type D3ZoomHandler = (this: Element, event: any, d: unknown) => void;
 
 export type UpdateNodeInternals = (nodeId: string | string[]) => void;
 
+/**
+ * This type is mostly used to help position things on top of the flow viewport. For
+ * example both the [`<MiniMap />`](/api-reference/components/minimap) and
+ * [`<Controls />`](/api-reference/components/controls) components take a `position`
+ * prop of this type.
+ *
+ * @public
+ */
 export type PanelPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
 
 export type ProOptions = {
@@ -183,7 +232,8 @@ export type ConnectionInProgress<NodeType extends InternalNodeBase = InternalNod
 };
 
 /**
- * The `ConnectionState` type bundles all information about an ongoing connection. It is returned by the [`useConnection`](/api-reference/hooks/use-connection) hook.
+ * The `ConnectionState` type bundles all information about an ongoing connection.
+ * It is returned by the [`useConnection`](/api-reference/hooks/use-connection) hook.
  *
  * @public
  */

packages/system/src/types/nodes.ts

@@ -4,6 +4,7 @@ import { Optional } from '../utils/types';
 /**
  * Framework independent node data structure.
  *
+ * @inline
  * @typeParam NodeData - type of the node data
  * @typeParam NodeType - type of the node
  */
@@ -89,7 +90,7 @@ export type InternalNodeBase<NodeType extends NodeBase = NodeBase> = NodeType &
 };
 
 /**
- * The node data structure that gets used for the nodes prop.
+ * The node data structure that gets used for the custom nodes props.
  *
  * @public
  */
@@ -141,10 +142,22 @@ export type NodeDragItem = {
   expandParent?: boolean;
 };
 
+/**
+ * The origin of a Node determines how it is placed relative to its own coordinates.
+ * `[0, 0]` places it at the top left corner, `[0.5, 0.5]` right in the center and
+ * `[1, 1]` at the bottom right of its position.
+ *
+ * @public
+ */
 export type NodeOrigin = [number, number];
 
 export type OnSelectionDrag = (event: MouseEvent, nodes: NodeBase[]) => void;
 
+/**
+ * Type for the handles of a node
+ *
+ * @public
+ */
 export type NodeHandle = Omit<Optional<Handle, 'width' | 'height'>, 'nodeId'>;
 
 export type Align = 'center' | 'start' | 'end';

packages/system/src/types/utils.ts

@@ -1,3 +1,10 @@
+/**
+ * While [`PanelPosition`](/api-reference/types/panel-position) can be used to place a
+ * component in the corners of a container, the `Position` enum is less precise and used
+ * primarily in relation to edges and handles.
+ *
+ * @public
+ */
 export enum Position {
   Left = 'left',
   Top = 'top',
@@ -12,6 +19,11 @@ export const oppositePosition = {
   [Position.Bottom]: Position.Top,
 };
 
+/**
+ * All positions are stored in an object with x and y coordinates.
+ *
+ * @public
+ */
 export type XYPosition = {
   x: number;
   y: number;