chore(types): add tsdocs

2025-02-11 17:57:21 +01:00
parent 7b0f96f017
commit 381ed2a5bf
34 changed files with 264 additions and 100 deletions
@@ -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 */
@@ -143,8 +143,7 @@ ControlsComponent.displayName = 'Controls';
 *}
 *```
 *
- * @remarks To extend or customise the controls, you can use the [`<ControlButton />`](/api-reference/components/control-button)
- *component
+ * @remarks To extend or customise the controls, you can use the [`<ControlButton />`](/api-reference/components/control-button) component
 *
 */
 export const Controls = memo(ControlsComponent);
@@ -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;
@@ -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
- *`true`.
+ * clutter. You can override this behavior by setting the `isVisible` prop to `true`.
 */
 export function NodeToolbar({
  nodeId,
@@ -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)
- *example.
+ * the edges. You can see an example usage of the component in the [edge label renderer](/examples/edges/edge-label-renderer) example.
 * @public
 *
 * @example
@@ -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
- *passed to a custom edge by looking at the [`EdgeProps`](/api-reference/types/edge-props) type.
+ * through to the [`<BaseEdge />`](/api-reference/components/base-edge) component.
+ * 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,
@@ -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
- *used internally by the [`<MiniMap />`](/api-reference/components/minimap) and [`<Controls />`](/api-reference/components/controls)
- *components.
+ * The `<Panel />` component helps you position content above the viewport.
+ * It is used internally by the [`<MiniMap />`](/api-reference/components/minimap)
+ * and [`<Controls />`](/api-reference/components/controls) components.
 *
 * @public
 *
@@ -20,9 +20,8 @@ export type ReactFlowProviderProps = {
 };

 /**
- * The `<ReactFlowProvider />` component is a
- *[context provider](https://react.dev/learn/passing-data-deeply-with-context#) that
- *makes it possible to access a flow's internal state outside of the
+ * The `<ReactFlowProvider />` component is a [context provider](https://react.dev/learn/passing-data-deeply-with-context#)
+ * that 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
@@ -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.
- *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
- *affected by zooming and panning
+ * The `<ViewportPortal />` component can be used to add components to the same viewport
+ * of the flow where nodes and edges are rendered. 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 affected by zooming and panning
 * @public
 * @example
 *
@@ -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
- *renders your nodes and edges and handles user interaction
+ * The `<ReactFlow />` component is the heart of your React Flow application.
+ * It renders your nodes and edges and handles user interaction
 *
 * @public
 *
@@ -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
- *will re-render **whenever the node changes**, including when a node is selected
- *or moved.
+ * This hook returns the internal representation of a specific node.
+ * Components that use this hook will re-render **whenever the node changes**,
+ * including when a node is selected or moved.
 *
 * @public
 * @param id - id of the node
@@ -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;
@@ -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.
@@ -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
@@ -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.
- * There are some data structures added under node.internal
- * that are needed for tracking some properties
+ * The `InternalNode` type is identical to the base [`Node`](/api-references/types/node)
+ * type but is extended with some additional properties used internall by React
+ * 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>;
@@ -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
- *this is a type guard that will narrow the type of whatever you pass in to
+ * Test whether an object is useable as an [`Node`](/api-reference/types/node).
+ * 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
- *this is a type guard that will narrow the type of whatever you pass in to
+ * Test whether an object is useable as an [`Edge`](/api-reference/types/edge).
+ * 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
@@ -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>,
@@ -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',
@@ -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
 */
@@ -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';
@@ -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;