@xyflow/react 12.5.4 → 12.5.5

package/dist/esm/index.mjs

@@ -18,9 +18,13 @@ const zustandErrorMessage = errorMessages['error001']();
  * state management library, so you should check out their docs for more details.
  *
  * @public
- * @param selector
- * @param equalityFn
- * @returns The selected state slice
+ * @param selector - A selector function that returns a slice of the flow's internal state.
+ * Extracting or transforming just the state you need is a good practice to avoid unnecessary
+ * re-renders.
+ * @param equalityFn - A function to compare the previous and next value. This is incredibly useful
+ * for preventing unnecessary re-renders. Good sensible defaults are using `Object.is` or importing
+ * `zustand/shallow`, but you can be as granular as you like.
+ * @returns The selected state slice.
  *
  * @example
  * ```ts
@@ -41,8 +45,7 @@ function useStore(selector, equalityFn) {
 /**
  * In some cases, you might need to access the store directly. This hook returns the store object which can be used on demand to access the state or dispatch actions.
  *
- * @returns The store object
- *
+ * @returns The store object.
  * @example
  * ```ts
  * const store = useStoreApi();
@@ -175,7 +178,7 @@ const defaultViewport = { x: 0, y: 0, zoom: 1 };
  * We distinguish between values we can update directly with `useDirectStoreUpdater` (like `snapGrid`)
  * and values that have a dedicated setter function in the store (like `setNodes`).
  */
-// these fields exist in the global store and we need to keep them up to date
+// These fields exist in the global store, and we need to keep them up to date
 const reactFlowFieldsToTrack = [
     'nodes',
     'edges',
@@ -348,9 +351,7 @@ const defaultDoc = typeof document !== 'undefined' ? document : null;
  * currently pressed or not.
  *
  * @public
- * @param param.keyCode - The key code (string or array of strings) to use
- * @param param.options - Options
- * @returns boolean
+ * @param options - Options
  *
  * @example
  * ```tsx
@@ -370,11 +371,17 @@ const defaultDoc = typeof document !== 'undefined' ? document : null;
  *```
  */
 function useKeyPress(
-/*
- * the keycode can be a string 'a' or an array of strings ['a', 'a+d']
- * a string means a single key 'a' or a combination when '+' is used 'a+d'
- * an array means different possibilites. Explainer: ['a', 'd+s'] here the
- * user can use the single key 'a' or the combination 'd' + 's'
+/**
+ * The key code (string or array of strings) specifies which key(s) should trigger
+ * an action.
+ *
+ * A **string** can represent:
+ * - A **single key**, e.g. `'a'`
+ * - A **key combination**, using `'+'` to separate keys, e.g. `'a+d'`
+ *
+ * An  **array of strings** represents **multiple possible key inputs**. For example, `['a', 'd+s']`
+ * means the user can press either the single key `'a'` or the combination of `'d'` and `'s'`.
+ * @default null
  */
 keyCode = null, options = { target: defaultDoc, actInsideInputWithModifier: true }) {
     const [keyPressed, setKeyPressed] = useState(false);
@@ -692,9 +699,9 @@ function applyChange(change, element) {
 /**
  * Drop in function that applies node changes to an array of nodes.
  * @public
- * @param changes - Array of changes to apply
- * @param nodes - Array of nodes to apply the changes to
- * @returns Array of updated nodes
+ * @param changes - Array of changes to apply.
+ * @param nodes - Array of nodes to apply the changes to.
+ * @returns Array of updated nodes.
  * @example
  *```tsx
  *import { useState, useCallback } from 'react';
@@ -726,9 +733,9 @@ function applyNodeChanges(changes, nodes) {
 /**
  * Drop in function that applies edge changes to an array of edges.
  * @public
- * @param changes - Array of changes to apply
- * @param edges - Array of edge to apply the changes to
- * @returns Array of updated edges
+ * @param changes - Array of changes to apply.
+ * @param edges - Array of edge to apply the changes to.
+ * @returns Array of updated edges.
  * @example
  * ```tsx
  *import { useState, useCallback } from 'react';
@@ -812,41 +819,45 @@ function elementToRemoveChange(item) {
 }
 
 /**
- * Test whether an object is useable as an [`Node`](/api-reference/types/node).
+ * Test whether an object is usable 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
- * @returns A boolean indicating whether the element is an Node
+ * @param element - The element to test.
+ * @returns Tests whether the provided value can be used as a `Node`. If you're using TypeScript,
+ * this function acts as a type guard and will narrow the type of the value to `Node` if it returns
+ * `true`.
  *
  * @example
  * ```js
  *import { isNode } from '@xyflow/react';
  *
  *if (isNode(node)) {
- * // ..
+ * // ...
  *}
  *```
  */
 const isNode = (element) => isNodeBase(element);
 /**
- * Test whether an object is useable as an [`Edge`](/api-reference/types/edge).
+ * Test whether an object is usable 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
- * @returns A boolean indicating whether the element is an Edge
+ * @returns Tests whether the provided value can be used as an `Edge`. If you're using TypeScript,
+ * this function acts as a type guard and will narrow the type of the value to `Edge` if it returns
+ * `true`.
  *
  * @example
  * ```js
  *import { isEdge } from '@xyflow/react';
  *
  *if (isEdge(edge)) {
- * // ..
+ * // ...
  *}
  *```
  */
@@ -990,8 +1001,6 @@ const selector$k = (s) => !!s.panZoom;
  * This hook returns a ReactFlowInstance that can be used to update nodes and edges, manipulate the viewport, or query the current state of the flow.
  *
  * @public
- * @returns ReactFlowInstance
- *
  * @example
  * ```jsx
  *import { useCallback, useState } from 'react';
@@ -1646,7 +1655,7 @@ NodeIdContext.Consumer;
  * drill down the id as a prop.
  *
  * @public
- * @returns id of the node
+ * @returns The id for a node in the flow.
  *
  * @example
  *```jsx
@@ -2409,6 +2418,14 @@ function getControl({ pos, x1, y1, x2, y2 }) {
  * The `getSimpleBezierPath` util returns everything you need to render a simple
  * bezier edge between two nodes.
  * @public
+ * @returns
+ * - `path`: the path to use in an SVG `<path>` element.
+ * - `labelX`: the `x` position you can use to render a label for this edge.
+ * - `labelY`: the `y` position you can use to render a label for this edge.
+ * - `offsetX`: the absolute difference between the source `x` position and the `x` position of the
+ * middle of this path.
+ * - `offsetY`: the absolute difference between the source `y` position and the `y` position of the
+ * middle of this path.
  */
 function getSimpleBezierPath({ sourceX, sourceY, sourcePosition = Position.Bottom, targetX, targetY, targetPosition = Position.Top, }) {
     const [sourceControlX, sourceControlY] = getControl({
@@ -2445,7 +2462,7 @@ function getSimpleBezierPath({ sourceX, sourceY, sourcePosition = Position.Botto
 }
 function createSimpleBezierEdge(params) {
     // eslint-disable-next-line react/display-name
-    return memo(({ id, sourceX, sourceY, targetX, targetY, sourcePosition = Position.Bottom, targetPosition = Position.Top, label, labelStyle, labelShowBg, labelBgStyle, labelBgPadding, labelBgBorderRadius, style, markerEnd, markerStart, interactionWidth, }) => {
+    return memo(({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, label, labelStyle, labelShowBg, labelBgStyle, labelBgPadding, labelBgBorderRadius, style, markerEnd, markerStart, interactionWidth, }) => {
         const [path, labelX, labelY] = getSimpleBezierPath({
             sourceX,
             sourceY,
@@ -2921,6 +2938,10 @@ function getSelector(connectionSelector) {
  * based on a certain condition (e.g. if the connection is valid or not).
  *
  * @public
+ * @param connectionSelector - An optional selector function used to extract a slice of the
+ * `ConnectionState` data. Using a selector can prevent component re-renders where data you don't
+ * otherwise care about might change. If a selector is not provided, the entire `ConnectionState`
+ * object is returned unchanged.
  * @example
  *
  * ```tsx
@@ -3565,12 +3586,13 @@ function ViewportPortal({ children }) {
 
 /**
  * When you programmatically add or remove handles to a node or update a node's
- *handle position, you need to let React Flow know about it using this hook. This
- *will update the internal dimensions of the node and properly reposition handles
- *on the canvas if necessary.
+ * handle position, you need to let React Flow know about it using this hook. This
+ * will update the internal dimensions of the node and properly reposition handles
+ * on the canvas if necessary.
  *
  * @public
- * @returns function for updating node internals
+ * @returns Use this function to tell React Flow to update the internal state of one or more nodes
+ * that you have changed programmatically.
  *
  * @example
  * ```jsx
@@ -3630,7 +3652,7 @@ const nodesSelector = (state) => state.nodes;
  * or moved.
  *
  * @public
- * @returns An array of nodes
+ * @returns An array of all nodes currently in the flow.
  *
  * @example
  * ```jsx
@@ -3654,7 +3676,7 @@ const edgesSelector = (state) => state.edges;
  * will re-render **whenever any edge changes**.
  *
  * @public
- * @returns An array of edges
+ * @returns An array of all edges currently in the flow.
  *
  * @example
  * ```tsx
@@ -3679,11 +3701,11 @@ const viewportSelector = (state) => ({
 });
 /**
  * The `useViewport` hook is a convenient way to read the current state of the
- *{@link Viewport} in a component. Components that use this hook
- *will re-render **whenever the viewport changes**.
+ * {@link Viewport} in a component. Components that use this hook
+ * will re-render **whenever the viewport changes**.
  *
  * @public
- * @returns The current viewport
+ * @returns The current viewport.
  *
  * @example
  *
@@ -3717,8 +3739,16 @@ function useViewport() {
  * like React's `useState` hook with an additional helper callback.
  *
  * @public
- * @param initialNodes
- * @returns an array [nodes, setNodes, onNodesChange]
+ * @returns
+ * - `nodes`: The current array of nodes. You might pass this directly to the `nodes` prop of your
+ * `<ReactFlow />` component, or you may want to manipulate it first to perform some layouting,
+ * for example.
+ * - `setNodes`: A function that you can use to update the nodes. You can pass it a new array of
+ * nodes or a callback that receives the current array of nodes and returns a new array of nodes.
+ * This is the same as the second element of the tuple returned by React's `useState` hook.
+ * - `onNodesChange`: A handy callback that can take an array of `NodeChanges` and update the nodes
+ * state accordingly. You'll typically pass this directly to the `onNodesChange` prop of your
+ * `<ReactFlow />` component.
  * @example
  *
  *```tsx
@@ -3759,8 +3789,18 @@ function useNodesState(initialNodes) {
  * like React's `useState` hook with an additional helper callback.
  *
  * @public
- * @param initialEdges
- * @returns an array [edges, setEdges, onEdgesChange]
+ * @returns
+ * - `edges`: The current array of edges. You might pass this directly to the `edges` prop of your
+ * `<ReactFlow />` component, or you may want to manipulate it first to perform some layouting,
+ * for example.
+ *
+ * - `setEdges`: A function that you can use to update the edges. You can pass it a new array of
+ * edges or a callback that receives the current array of edges and returns a new array of edges.
+ * This is the same as the second element of the tuple returned by React's `useState` hook.
+ *
+ * - `onEdgesChange`: A handy callback that can take an array of `EdgeChanges` and update the edges
+ * state accordingly. You'll typically pass this directly to the `onEdgesChange` prop of your
+ * `<ReactFlow />` component.
  * @example
  *
  *```tsx
@@ -3798,14 +3838,10 @@ function useEdgesState(initialEdges) {
 
 /**
  * The `useOnViewportChange` hook lets you listen for changes to the viewport such
- *as panning and zooming. You can provide a callback for each phase of a viewport
- *change: `onStart`, `onChange`, and `onEnd`.
+ * as panning and zooming. You can provide a callback for each phase of a viewport
+ * change: `onStart`, `onChange`, and `onEnd`.
  *
  * @public
- * @param params.onStart - gets called when the viewport starts changing
- * @param params.onChange - gets called when the viewport changes
- * @param params.onEnd - gets called when the viewport stops changing
- *
  * @example
  * ```jsx
  *import { useCallback } from 'react';
@@ -3841,8 +3877,6 @@ function useOnViewportChange({ onStart, onChange, onEnd }) {
  *_either_ nodes or edges changes.
  *
  * @public
- * @param params.onChange - The handler to register
- *
  * @example
  * ```jsx
  *import { useState } from 'react';
@@ -3904,8 +3938,8 @@ const selector$4 = (options) => (s) => {
  *`false` and then `true` again once the node has been measured.
  *
  * @public
- * @param options.includeHiddenNodes - defaults to false
- * @returns boolean indicating whether all nodes are initialized
+ * @returns Whether or not the nodes have been initialized by the `<ReactFlow />` component and
+ * given a width and height.
  *
  * @example
  * ```jsx
@@ -3943,12 +3977,7 @@ function useNodesInitialized(options = {
  *
  * @public
  * @deprecated Use `useNodeConnections` instead.
- * @param param.type - handle type 'source' or 'target'
- * @param param.nodeId - node id - if not provided, the node id from the NodeIdContext is used
- * @param param.id - the handle id (this is only needed if the node has multiple handles of the same type)
- * @param param.onConnect - gets called when a connection is established
- * @param param.onDisconnect - gets called when a connection is removed
- * @returns an array with handle connections
+ * @returns An array with handle connections.
  */
 function useHandleConnections({ type, id, nodeId, onConnect, onDisconnect, }) {
     console.warn('[DEPRECATED] `useHandleConnections` is deprecated. Instead use `useNodeConnections` https://reactflow.dev/api-reference/hooks/useNodeConnections');
@@ -3973,12 +4002,7 @@ const error014 = errorMessages['error014']();
  * This hook returns an array of connections on a specific node, handle type ('source', 'target') or handle ID.
  *
  * @public
- * @param param.id - node id - optional if called inside a custom node
- * @param param.handleType - filter by handle type 'source' or 'target'
- * @param param.handleId - filter by handle id (this is only needed if the node has multiple handles of the same type)
- * @param param.onConnect - gets called when a connection is established
- * @param param.onDisconnect - gets called when a connection is removed
- * @returns an array with connections
+ * @returns An array with connections.
  *
  * @example
  * ```jsx
@@ -4005,7 +4029,7 @@ function useNodeConnections({ id, handleType, handleId, onConnect, onDisconnect,
     const prevConnections = useRef(null);
     const connections = useStore((state) => state.connectionLookup.get(`${currentNodeId}${handleType ? (handleId ? `-${handleType}-${handleId}` : `-${handleType}`) : ''}`), areConnectionMapsEqual);
     useEffect(() => {
-        // @todo dicuss if onConnect/onDisconnect should be called when the component mounts/unmounts
+        // @todo discuss if onConnect/onDisconnect should be called when the component mounts/unmounts
         if (prevConnections.current && prevConnections.current !== connections) {
             const _connections = connections ?? new Map();
             handleConnectionChange(prevConnections.current, _connections, onDisconnect);
@@ -4043,8 +4067,8 @@ function useNodesData(nodeIds) {
  * including when a node is selected or moved.
  *
  * @public
- * @param id - id of the node
- * @returns array with visible node ids
+ * @param id - The ID of a node you want to observe.
+ * @returns The `InternalNode` object for the node with the given ID.
  *
  * @example
  * ```tsx