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/ControlButton.tsx

@@ -4,7 +4,7 @@ import type { ControlButtonProps } from './types';
 
 /**
  * You can add buttons to the control panel by using the `<ControlButton />` component
- *and pass it as a child to the [`<Controls />`](/api-reference/components/controls) component.
+ * and pass it as a child to the [`<Controls />`](/api-reference/components/controls) component.
  *
  * @public
  * @example

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

@@ -127,7 +127,7 @@ ControlsComponent.displayName = 'Controls';
 
 /**
  * The `<Controls />` component renders a small panel that contains convenient
- *buttons to zoom in, zoom out, fit the view, and lock the viewport.
+ * buttons to zoom in, zoom out, fit the view, and lock the viewport.
  *
  * @public
  * @example
@@ -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/MiniMap.tsx

@@ -113,16 +113,16 @@ function MiniMapComponent<NodeType extends Node = Node>({
 
   const onSvgClick = onClick
     ? (event: MouseEvent) => {
-      const [x, y] = minimapInstance.current?.pointer(event) || [0, 0];
+        const [x, y] = minimapInstance.current?.pointer(event) || [0, 0];
-      onClick(event, { x, y });
+        onClick(event, { x, y });
-    }
+      }
     : undefined;
 
   const onSvgNodeClick = onNodeClick
     ? useCallback((event: MouseEvent, nodeId: string) => {
-      const node = store.getState().nodeLookup.get(nodeId)!;
+        const node = store.getState().nodeLookup.get(nodeId)!;
-      onNodeClick(event, node);
+        onNodeClick(event, node);
-    }, [])
+      }, [])
     : undefined;
 
   return (
@@ -180,8 +180,8 @@ MiniMapComponent.displayName = 'MiniMap';
 
 /**
  * The `<MiniMap />` component can be used to render an overview of your flow. It
- *renders each node as an SVG element and visualizes where the current viewport is
+ * renders each node as an SVG element and visualizes where the current viewport is
- *in relation to the rest of the flow.
+ * in relation to the rest of the flow.
  *
  * @public
  * @example

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/NodeResizer/NodeResizer.tsx

@@ -5,7 +5,7 @@ import type { NodeResizerProps } from './types';
 
 /**
  * The `<NodeResizer />` component can be used to add a resize functionality to your
- *nodes. It renders draggable controls around the node to resize in all directions.
+ * nodes. It renders draggable controls around the node to resize in all directions.
  * @public
  *
  * @example

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

@@ -40,7 +40,7 @@ const storeSelector = (state: ReactFlowState) => ({
 
 /**
  * This component can render a toolbar or tooltip to one side of a custom node. This
- *toolbar doesn't scale with the viewport so that the content is always visible.
+ * toolbar doesn't scale with the viewport so that the content is always visible.
  *
  * @public
  * @example
@@ -70,9 +70,8 @@ const storeSelector = (state: ReactFlowState) => ({
  *export default memo(CustomNode);
  *```
  * @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
+ * 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

@@ -8,10 +8,9 @@ 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
+ * `<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
+ * 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
@@ -43,9 +42,9 @@ const selector = (s: ReactFlowState) => s.domNode?.querySelector('.react-flow__e
  *};
  *```
  *
- *@remarks The `<EdgeLabelRenderer />` has no pointer events by default. If you want to
+ * @remarks The `<EdgeLabelRenderer />` has no pointer events by default. If you want to
- *add mouse interactions you need to set the style `pointerEvents: all` and add
+ * add mouse interactions you need to set the style `pointerEvents: all` and add
- *the `nopan` class on the label or the element you want to interact with.
+ * the `nopan` class on the label or the element you want to interact with.
  */
 export function EdgeLabelRenderer({ children }: { children: ReactNode }) {
   const edgeLabelRenderer = useStore(selector);

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

@@ -6,8 +6,8 @@ import type { BaseEdgeProps } from '../../types';
 
 /**
  * The `<BaseEdge />` component gets used internally for all the edges. It can be
- *used inside a custom edge and handles the invisible helper edge and the edge label
+ * used inside a custom edge and handles the invisible helper edge and the edge label
- *for you.
+ * for you.
  *
  * @public
  * @example
@@ -27,9 +27,9 @@ 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
+ * 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/Edges/EdgeText.tsx

@@ -75,7 +75,7 @@ EdgeTextComponent.displayName = 'EdgeText';
 
 /**
  * You can use the `<EdgeText />` component as a helper component to display text
- *within your custom edges.
+ * within your custom edges.
  *
  *@public
  *

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

@@ -31,7 +31,7 @@ function getControl({ pos, x1, y1, x2, y2 }: GetControlParams): [number, number]
 
 /**
  * The `getSimpleBezierPath` util returns everything you need to render a simple
- *bezier edge between two nodes.
+ * bezier edge between two nodes.
  * @public
  */
 export function getSimpleBezierPath({

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

@@ -251,7 +251,7 @@ function HandleComponent(
 
 /**
  * The `<Handle />` component is used in your [custom nodes](/learn/customization/custom-nodes)
- *to define connection points.
+ * to define connection points.
  *
  *@public
  *

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,11 +20,10 @@ 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
- *[`<ReactFlow />`](/api-reference/react-flow) component. Many of the hooks we
+ * provide rely on this component to work.
- *provide rely on this component to work.
  * @public
  *
  * @example
@@ -50,9 +49,9 @@ export type ReactFlowProviderProps = {
  *```
  *
  * @remarks If you're using a router and want your flow's state to persist across routes,
- *it's vital that you place the `<ReactFlowProvider />` component _outside_ of
+ * it's vital that you place the `<ReactFlowProvider />` component _outside_ of
- *your router. If you have multiple flows on the same page you will need to use a separate
+ * your router. If you have multiple flows on the same page you will need to use a separate
- *`<ReactFlowProvider />` for each flow.
+ * `<ReactFlowProvider />` for each flow.
  */
 export function ReactFlowProvider({
   initialNodes: nodes,

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/contexts/NodeIdContext.ts

@@ -6,8 +6,8 @@ export const Consumer = NodeIdContext.Consumer;
 
 /**
  * You can use this hook to get the id of the node it is used inside. It is useful
- *if you need the node's id deeper in the render tree but don't want to manually
+ * if you need the node's id deeper in the render tree but don't want to manually
- *drill down the id as a prop.
+ * drill down the id as a prop.
  *
  * @public
  * @returns id of the node

packages/react/src/hooks/useConnection.ts

@@ -25,9 +25,9 @@ function getSelector<NodeType extends Node = Node, SelectorReturn = ConnectionSt
 }
 /**
  * The `useConnection` hook returns the current connection when there is an active
- *connection interaction. If no connection interaction is active, it returns null
+ * connection interaction. If no connection interaction is active, it returns null
- *for every property. A typical use case for this hook is to colorize handles
+ * for every property. A typical use case for this hook is to colorize handles
- *based on a certain condition (e.g. if the connection is valid or not).
+ * based on a certain condition (e.g. if the connection is valid or not).
  *
  * @public
  * @example

packages/react/src/hooks/useEdges.ts

@@ -7,7 +7,7 @@ const edgesSelector = (state: ReactFlowState) => state.edges;
 
 /**
  * This hook returns an array of the current edges. Components that use this hook
- *will re-render **whenever any edge changes**.
+ * will re-render **whenever any edge changes**.
  *
  * @public
  * @returns An array of edges

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/hooks/useKeyPress.ts

@@ -14,7 +14,7 @@ const defaultDoc = typeof document !== 'undefined' ? document : null;
 
 /**
  * This hook lets you listen for specific key codes and tells you whether they are
- *currently pressed or not.
+ * currently pressed or not.
  *
  * @public
  * @param param.keyCode - The key code (string or array of strings) to use

packages/react/src/hooks/useNodes.ts

@@ -7,8 +7,8 @@ const nodesSelector = (state: ReactFlowState) => state.nodes;
 
 /**
  * This hook returns an array of the current nodes. Components that use this hook
- *will re-render **whenever any node changes**, including when a node is selected
+ * will re-render **whenever any node changes**, including when a node is selected
- *or moved.
+ * or moved.
  *
  * @public
  * @returns An array of nodes

packages/react/src/hooks/useNodesEdgesState.ts

@@ -5,8 +5,8 @@ import type { Node, Edge, OnNodesChange, OnEdgesChange } from '../types';
 
 /**
  * This hook makes it easy to prototype a controlled flow where you manage the
- *state of nodes and edges outside the `ReactFlowInstance`. You can think of it
+ * state of nodes and edges outside the `ReactFlowInstance`. You can think of it
- *like React's `useState` hook with an additional helper callback.
+ * like React's `useState` hook with an additional helper callback.
  *
  * @public
  * @param initialNodes
@@ -34,10 +34,10 @@ import type { Node, Edge, OnNodesChange, OnEdgesChange } from '../types';
  *}
  *```
  *
- *@remarks This hook was created to make prototyping easier and our documentation
+ * @remarks This hook was created to make prototyping easier and our documentation
- *examples clearer. Although it is OK to use this hook in production, in
+ * examples clearer. Although it is OK to use this hook in production, in
- *practice you may want to use a more sophisticated state management solution
+ * practice you may want to use a more sophisticated state management solution
- *like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead.
+ * like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead.
  *
  */
 export function useNodesState<NodeType extends Node>(
@@ -54,8 +54,8 @@ export function useNodesState<NodeType extends Node>(
 
 /**
  * This hook makes it easy to prototype a controlled flow where you manage the
- *state of nodes and edges outside the `ReactFlowInstance`. You can think of it
+ * state of nodes and edges outside the `ReactFlowInstance`. You can think of it
- *like React's `useState` hook with an additional helper callback.
+ * like React's `useState` hook with an additional helper callback.
  *
  * @public
  * @param initialEdges
@@ -84,9 +84,9 @@ export function useNodesState<NodeType extends Node>(
  *```
  *
  * @remarks This hook was created to make prototyping easier and our documentation
- *examples clearer. Although it is OK to use this hook in production, in
+ * examples clearer. Although it is OK to use this hook in production, in
- *practice you may want to use a more sophisticated state management solution
+ * practice you may want to use a more sophisticated state management solution
- *like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead.
+ * like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead.
  *
  */
 export function useEdgesState<EdgeType extends Edge = Edge>(

packages/react/src/hooks/useStore.ts

@@ -10,8 +10,8 @@ const zustandErrorMessage = errorMessages['error001']();
 
 /**
  * This hook can be used to subscribe to internal state changes of the React Flow
- *component. The `useStore` hook is re-exported from the [Zustand](https://github.com/pmndrs/zustand)
+ * component. The `useStore` hook is re-exported from the [Zustand](https://github.com/pmndrs/zustand)
- *state management library, so you should check out their docs for more details.
+ * state management library, so you should check out their docs for more details.
  *
  * @public
  * @param selector
@@ -24,8 +24,8 @@ const zustandErrorMessage = errorMessages['error001']();
  * ```
  *
  * @remarks This hook should only be used if there is no other way to access the internal
- *state. For many of the common use cases, there are dedicated hooks available
+ * state. For many of the common use cases, there are dedicated hooks available
- *such as {@link useReactFlow}, {@link useViewport}, etc.
+ * such as {@link useReactFlow}, {@link useViewport}, etc.
  */
 function useStore<StateSlice = unknown>(
   selector: (state: ReactFlowState) => StateSlice,
@@ -51,8 +51,8 @@ function useStore<StateSlice = unknown>(
  * ```
  *
  * @remarks This hook should only be used if there is no other way to access the internal
- *state. For many of the common use cases, there are dedicated hooks available
+ * state. For many of the common use cases, there are dedicated hooks available
- *such as {@link useReactFlow}, {@link useViewport}, etc.
+ * such as {@link useReactFlow}, {@link useViewport}, etc.
  */
 function useStoreApi<NodeType extends Node = Node, EdgeType extends Edge = Edge>() {
   const store = useContext(StoreContext) as UseBoundStoreWithEqualityFn<

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`.
+ * [`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`.
+ * [`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

@@ -28,8 +28,8 @@ export type FitBounds = (bounds: Rect, options?: FitBoundsOptions) => Promise<bo
 
 /**
  * The `Connection` type is the basic minimal description of an [`Edge`](/api-reference/types/edge)
- *between two nodes. The [`addEdge`](/api-reference/utils/add-edge) util can be used to upgrade
+ * between two nodes. The [`addEdge`](/api-reference/utils/add-edge) util can be used to upgrade
- *a `Connection` to an [`Edge`](/api-reference/types/edge).
+ * a `Connection` to an [`Edge`](/api-reference/types/edge).
  *
  * @public
  */
@@ -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;
@@ -35,12 +47,12 @@ export type Transform = [number, number, number];
 
 /**
  * A coordinate extent represents two points in a coordinate system: one in the top
- *left corner and one in the bottom right corner. It is used to represent the
+ * left corner and one in the bottom right corner. It is used to represent the
- *bounds of nodes in the flow or the bounds of the viewport.
+ * bounds of nodes in the flow or the bounds of the viewport.
  *
  * @public
  *
  * @remarks Props that expect a `CoordinateExtent` usually default to `[[-∞, -∞], [+∞, +∞]]`
- *to represent an unbounded extent.
+ * to represent an unbounded extent.
  */
 export type CoordinateExtent = [[number, number], [number, number]];