diff --git a/packages/react/src/additional-components/Background/types.ts b/packages/react/src/additional-components/Background/types.ts index 9d1cd67b..50219e2d 100644 --- a/packages/react/src/additional-components/Background/types.ts +++ b/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 */ diff --git a/packages/react/src/additional-components/Controls/ControlButton.tsx b/packages/react/src/additional-components/Controls/ControlButton.tsx index 12c58663..a3cc81ad 100644 --- a/packages/react/src/additional-components/Controls/ControlButton.tsx +++ b/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 `` component - *and pass it as a child to the [``](/api-reference/components/controls) component. + * and pass it as a child to the [``](/api-reference/components/controls) component. * * @public * @example diff --git a/packages/react/src/additional-components/Controls/Controls.tsx b/packages/react/src/additional-components/Controls/Controls.tsx index 1b0beae3..84337a28 100644 --- a/packages/react/src/additional-components/Controls/Controls.tsx +++ b/packages/react/src/additional-components/Controls/Controls.tsx @@ -127,7 +127,7 @@ ControlsComponent.displayName = 'Controls'; /** * The `` 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 [``](/api-reference/components/control-button) - *component + * @remarks To extend or customise the controls, you can use the [``](/api-reference/components/control-button) component * */ export const Controls = memo(ControlsComponent); diff --git a/packages/react/src/additional-components/MiniMap/MiniMap.tsx b/packages/react/src/additional-components/MiniMap/MiniMap.tsx index c5e8d719..be6dc453 100644 --- a/packages/react/src/additional-components/MiniMap/MiniMap.tsx +++ b/packages/react/src/additional-components/MiniMap/MiniMap.tsx @@ -113,16 +113,16 @@ function MiniMapComponent({ const onSvgClick = onClick ? (event: MouseEvent) => { - const [x, y] = minimapInstance.current?.pointer(event) || [0, 0]; - onClick(event, { x, y }); - } + const [x, y] = minimapInstance.current?.pointer(event) || [0, 0]; + onClick(event, { x, y }); + } : undefined; const onSvgNodeClick = onNodeClick ? useCallback((event: MouseEvent, nodeId: string) => { - const node = store.getState().nodeLookup.get(nodeId)!; - onNodeClick(event, node); - }, []) + const node = store.getState().nodeLookup.get(nodeId)!; + onNodeClick(event, node); + }, []) : undefined; return ( @@ -180,8 +180,8 @@ MiniMapComponent.displayName = 'MiniMap'; /** * The `` 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 - *in relation to the rest of the flow. + * renders each node as an SVG element and visualizes where the current viewport is + * in relation to the rest of the flow. * * @public * @example diff --git a/packages/react/src/additional-components/MiniMap/types.ts b/packages/react/src/additional-components/MiniMap/types.ts index c6d11ba8..351395f9 100644 --- a/packages/react/src/additional-components/MiniMap/types.ts +++ b/packages/react/src/additional-components/MiniMap/types.ts @@ -58,6 +58,11 @@ export type MiniMapNodes = Pick< onClick?: (event: MouseEvent, nodeId: string) => void; }; +/** + * The props that are passed to the MiniMapNode component + * + * @public + */ export type MiniMapNodeProps = { id: string; x: number; diff --git a/packages/react/src/additional-components/NodeResizer/NodeResizer.tsx b/packages/react/src/additional-components/NodeResizer/NodeResizer.tsx index f3e6cf8a..434be4b7 100644 --- a/packages/react/src/additional-components/NodeResizer/NodeResizer.tsx +++ b/packages/react/src/additional-components/NodeResizer/NodeResizer.tsx @@ -5,7 +5,7 @@ import type { NodeResizerProps } from './types'; /** * The `` 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 diff --git a/packages/react/src/additional-components/NodeToolbar/NodeToolbar.tsx b/packages/react/src/additional-components/NodeToolbar/NodeToolbar.tsx index 4e486425..0248b394 100644 --- a/packages/react/src/additional-components/NodeToolbar/NodeToolbar.tsx +++ b/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 - *clutter. You can override this behavior by setting the `isVisible` prop to - *`true`. + * 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`. */ export function NodeToolbar({ nodeId, diff --git a/packages/react/src/components/EdgeLabelRenderer/index.tsx b/packages/react/src/components/EdgeLabelRenderer/index.tsx index b3aa1a91..647811cb 100644 --- a/packages/react/src/components/EdgeLabelRenderer/index.tsx +++ b/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 - *`` component to access a div based renderer. This component - *is a portal that renders the label in a `
` 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. + * `` component to access a div based renderer. This component + * is a portal that renders the label in a `
` 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. * @public * * @example @@ -43,9 +42,9 @@ const selector = (s: ReactFlowState) => s.domNode?.querySelector('.react-flow__e *}; *``` * - *@remarks The `` has no pointer events by default. If you want to - *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. + * @remarks The `` has no pointer events by default. If you want to + * 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. */ export function EdgeLabelRenderer({ children }: { children: ReactNode }) { const edgeLabelRenderer = useStore(selector); diff --git a/packages/react/src/components/Edges/BaseEdge.tsx b/packages/react/src/components/Edges/BaseEdge.tsx index e19412f2..4d1ac1da 100644 --- a/packages/react/src/components/Edges/BaseEdge.tsx +++ b/packages/react/src/components/Edges/BaseEdge.tsx @@ -6,8 +6,8 @@ import type { BaseEdgeProps } from '../../types'; /** * The `` 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 - *for you. + * used inside a custom edge and handles the invisible helper edge and the edge label + * for you. * * @public * @example @@ -27,9 +27,9 @@ import type { BaseEdgeProps } from '../../types'; *``` * * @remarks If you want to use an edge marker with the [``](/api-reference/components/base-edge) component, - *you can pass the `markerStart` or `markerEnd` props passed to your custom edge - *through to the [``](/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. + * you can pass the `markerStart` or `markerEnd` props passed to your custom edge + * through to the [``](/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, diff --git a/packages/react/src/components/Edges/EdgeText.tsx b/packages/react/src/components/Edges/EdgeText.tsx index e2d162b0..2c79f718 100644 --- a/packages/react/src/components/Edges/EdgeText.tsx +++ b/packages/react/src/components/Edges/EdgeText.tsx @@ -75,7 +75,7 @@ EdgeTextComponent.displayName = 'EdgeText'; /** * You can use the `` component as a helper component to display text - *within your custom edges. + * within your custom edges. * *@public * diff --git a/packages/react/src/components/Edges/SimpleBezierEdge.tsx b/packages/react/src/components/Edges/SimpleBezierEdge.tsx index 1c8c2697..a11cbc1d 100644 --- a/packages/react/src/components/Edges/SimpleBezierEdge.tsx +++ b/packages/react/src/components/Edges/SimpleBezierEdge.tsx @@ -31,8 +31,8 @@ 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. - * @public + * bezier edge between two nodes. + * @public */ export function getSimpleBezierPath({ sourceX, diff --git a/packages/react/src/components/Handle/index.tsx b/packages/react/src/components/Handle/index.tsx index 07d18378..72e7ad21 100644 --- a/packages/react/src/components/Handle/index.tsx +++ b/packages/react/src/components/Handle/index.tsx @@ -251,7 +251,7 @@ function HandleComponent( /** * The `` component is used in your [custom nodes](/learn/customization/custom-nodes) - *to define connection points. + * to define connection points. * *@public * diff --git a/packages/react/src/components/Panel/index.tsx b/packages/react/src/components/Panel/index.tsx index 1859b034..461cc1ba 100644 --- a/packages/react/src/components/Panel/index.tsx +++ b/packages/react/src/components/Panel/index.tsx @@ -6,9 +6,9 @@ import { useStore } from '../../hooks/useStore'; import type { ReactFlowState } from '../../types'; /** - * The `` component helps you position content above the viewport. It is - *used internally by the [``](/api-reference/components/minimap) and [``](/api-reference/components/controls) - *components. + * The `` component helps you position content above the viewport. + * It is used internally by the [``](/api-reference/components/minimap) + * and [``](/api-reference/components/controls) components. * * @public * diff --git a/packages/react/src/components/ReactFlowProvider/index.tsx b/packages/react/src/components/ReactFlowProvider/index.tsx index b8b4bf40..1492ca3f 100644 --- a/packages/react/src/components/ReactFlowProvider/index.tsx +++ b/packages/react/src/components/ReactFlowProvider/index.tsx @@ -20,11 +20,10 @@ export type ReactFlowProviderProps = { }; /** - * The `` 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 - *[``](/api-reference/react-flow) component. Many of the hooks we - *provide rely on this component to work. + * The `` 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 + * [``](/api-reference/react-flow) component. Many of the hooks we + * 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 `` component _outside_ of - *your router. If you have multiple flows on the same page you will need to use a separate - *`` for each flow. + * it's vital that you place the `` component _outside_ of + * your router. If you have multiple flows on the same page you will need to use a separate + * `` for each flow. */ export function ReactFlowProvider({ initialNodes: nodes, diff --git a/packages/react/src/components/ViewportPortal/index.tsx b/packages/react/src/components/ViewportPortal/index.tsx index ea306935..1040d796 100644 --- a/packages/react/src/components/ViewportPortal/index.tsx +++ b/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 `` 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 `` 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 * diff --git a/packages/react/src/container/ReactFlow/index.tsx b/packages/react/src/container/ReactFlow/index.tsx index c9b504aa..439a84e6 100644 --- a/packages/react/src/container/ReactFlow/index.tsx +++ b/packages/react/src/container/ReactFlow/index.tsx @@ -302,8 +302,8 @@ function ReactFlow( } /** - * The `` component is the heart of your React Flow application. It - *renders your nodes and edges and handles user interaction + * The `` component is the heart of your React Flow application. + * It renders your nodes and edges and handles user interaction * * @public * diff --git a/packages/react/src/contexts/NodeIdContext.ts b/packages/react/src/contexts/NodeIdContext.ts index b5811ad6..5458c98c 100644 --- a/packages/react/src/contexts/NodeIdContext.ts +++ b/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 - *drill down the id as a prop. + * 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. * * @public * @returns id of the node diff --git a/packages/react/src/hooks/useConnection.ts b/packages/react/src/hooks/useConnection.ts index 8992d767..9ed14b67 100644 --- a/packages/react/src/hooks/useConnection.ts +++ b/packages/react/src/hooks/useConnection.ts @@ -25,9 +25,9 @@ function getSelector 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 diff --git a/packages/react/src/hooks/useInternalNode.ts b/packages/react/src/hooks/useInternalNode.ts index bfdc74f9..ecd83897 100644 --- a/packages/react/src/hooks/useInternalNode.ts +++ b/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 - *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 diff --git a/packages/react/src/hooks/useKeyPress.ts b/packages/react/src/hooks/useKeyPress.ts index 6f2d01c3..00cd012b 100644 --- a/packages/react/src/hooks/useKeyPress.ts +++ b/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 diff --git a/packages/react/src/hooks/useNodes.ts b/packages/react/src/hooks/useNodes.ts index c64f7fb1..9fa14bcb 100644 --- a/packages/react/src/hooks/useNodes.ts +++ b/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 - *or moved. + * will re-render **whenever any node changes**, including when a node is selected + * or moved. * * @public * @returns An array of nodes diff --git a/packages/react/src/hooks/useNodesEdgesState.ts b/packages/react/src/hooks/useNodesEdgesState.ts index b9722d80..b5919e5e 100644 --- a/packages/react/src/hooks/useNodesEdgesState.ts +++ b/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 - *like React's `useState` hook with an additional helper callback. + * state of nodes and edges outside the `ReactFlowInstance`. You can think of it + * 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 - *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 - *like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead. + * @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 + * practice you may want to use a more sophisticated state management solution + * like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead. * */ export function useNodesState( @@ -54,8 +54,8 @@ export function useNodesState( /** * 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 - *like React's `useState` hook with an additional helper callback. + * state of nodes and edges outside the `ReactFlowInstance`. You can think of it + * like React's `useState` hook with an additional helper callback. * * @public * @param initialEdges @@ -84,9 +84,9 @@ export function useNodesState( *``` * * @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 - *practice you may want to use a more sophisticated state management solution - *like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead. + * 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 + * like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead. * */ export function useEdgesState( diff --git a/packages/react/src/hooks/useStore.ts b/packages/react/src/hooks/useStore.ts index e34e2c36..3b0a2778 100644 --- a/packages/react/src/hooks/useStore.ts +++ b/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) - *state management library, so you should check out their docs for more details. + * 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. * * @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 - *such as {@link useReactFlow}, {@link useViewport}, etc. + * state. For many of the common use cases, there are dedicated hooks available + * such as {@link useReactFlow}, {@link useViewport}, etc. */ function useStore( selector: (state: ReactFlowState) => StateSlice, @@ -51,8 +51,8 @@ function useStore( * ``` * * @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 - *such as {@link useReactFlow}, {@link useViewport}, etc. + * state. For many of the common use cases, there are dedicated hooks available + * such as {@link useReactFlow}, {@link useViewport}, etc. */ function useStoreApi() { const store = useContext(StoreContext) as UseBoundStoreWithEqualityFn< diff --git a/packages/react/src/types/edges.ts b/packages/react/src/types/edges.ts index ce21e84f..1a6de7c2 100644 --- a/packages/react/src/types/edges.ts +++ b/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 = { 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 [``](/api-reference/react-flow#defaultedgeoptions) + *component. + */ export type DefaultEdgeOptions = DefaultEdgeOptionsBase; export type EdgeTextProps = SVGAttributes & @@ -100,8 +110,10 @@ export type EdgeTextProps = SVGAttributes & }; /** - * 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 = Pick< EdgeType, @@ -185,6 +197,13 @@ export type SimpleBezierEdgeProps = EdgeComponentProps; export type OnReconnect = (oldEdge: EdgeType, newConnection: Connection) => void; +/** + * If you want to render a custom component for connection lines, you can set the + *`connectionLineComponent` prop on the [``](/api-reference/react-flow#connection-connectionLineComponent) + *component. The `ConnectionLineComponentProps` are passed to your custom component. + * + * @public + */ export type ConnectionLineComponentProps = { connectionLineStyle?: CSSProperties; connectionLineType: ConnectionLineType; diff --git a/packages/react/src/types/general.ts b/packages/react/src/types/general.ts index 48e5b2fe..249cf01b 100644 --- a/packages/react/src/types/general.ts +++ b/packages/react/src/types/general.ts @@ -64,12 +64,23 @@ export type OnSelectionChangeParams = { export type OnSelectionChangeFunc = (params: OnSelectionChangeParams) => void; export type FitViewParams = FitViewParamsBase; + +/** + * 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 = FitViewOptionsBase; export type FitView = (fitViewOptions?: FitViewOptions) => Promise; export type OnInit = ( reactFlowInstance: ReactFlowInstance ) => void; +/** + * @inline + */ export type ViewportHelperFunctions = { /** * Zooms viewport in by 1.2. diff --git a/packages/react/src/types/instance.ts b/packages/react/src/types/instance.ts index 992655a4..fbfa39ce 100644 --- a/packages/react/src/types/instance.ts +++ b/packages/react/src/types/instance.ts @@ -217,6 +217,14 @@ export type GeneralHelpers 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 = GeneralHelpers< NodeType, EdgeType diff --git a/packages/react/src/types/nodes.ts b/packages/react/src/types/nodes.ts index 0d3924e4..cfdefb13 100644 --- a/packages/react/src/types/nodes.ts +++ b/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. - * 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 = InternalNodeBase; @@ -60,4 +63,31 @@ export type BuiltInNode = | Node<{ label: string }, 'input' | 'output' | 'default'> | Node, '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) { + * const [count, setCount] = useState(props.data?.initialCount ?? 0); + * + * return ( + *
+ *

Count: {count}

+ * + *
+ * ); + *} + *``` + */ export type NodeProps = NodePropsBase; diff --git a/packages/react/src/utils/general.ts b/packages/react/src/utils/general.ts index 6ac2e3c5..e21bdfb6 100644 --- a/packages/react/src/utils/general.ts +++ b/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 - *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`. + * 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 = (element: unknown): element isNodeBase(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 - *[`Edge`](/api-reference/types/edge) if it returns `true`. + * 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 diff --git a/packages/svelte/src/lib/types/edges.ts b/packages/svelte/src/lib/types/edges.ts index de1def91..b2f6ba7e 100644 --- a/packages/svelte/src/lib/types/edges.ts +++ b/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 = Record, diff --git a/packages/system/src/types/edges.ts b/packages/system/src/types/edges.ts index abe7c8f2..9f52b5a3 100644 --- a/packages/system/src/types/edges.ts +++ b/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', diff --git a/packages/system/src/types/general.ts b/packages/system/src/types/general.ts index 485bb4f5..8ac3f9e9 100644 --- a/packages/system/src/types/general.ts +++ b/packages/system/src/types/general.ts @@ -28,8 +28,8 @@ export type FitBounds = (bounds: Rect, options?: FitBoundsOptions) => Promise boolean; +/** + * @inline + */ export type FitViewParamsBase = { nodes: Map>; width: number; @@ -75,6 +91,9 @@ export type FitViewParamsBase = { maxZoom: number; }; +/** + * @inline + */ export type FitViewOptionsBase = { padding?: number; includeHiddenNodes?: boolean; @@ -84,6 +103,17 @@ export type FitViewOptionsBase = { 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; 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 [``](/api-reference/components/minimap) and + * [``](/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 & z: number; /** * Holds a reference to the original node object provided by the user. - * Used as an optimization to avoid certain operations. + * Used as an optimization to avoid certain operations. */ userNode: NodeType; handleBounds?: NodeHandleBounds; @@ -89,7 +90,7 @@ export type InternalNodeBase = 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, 'nodeId'>; export type Align = 'center' | 'start' | 'end'; diff --git a/packages/system/src/types/utils.ts b/packages/system/src/types/utils.ts index 61d55698..274bfe55 100644 --- a/packages/system/src/types/utils.ts +++ b/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 - *bounds of nodes in the flow or the bounds of the viewport. + * 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. * * @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]];