@xyflow/react 12.4.2 → 12.4.4

package/dist/umd/hooks/useNodesInitialized.d.ts

@@ -2,11 +2,37 @@ export type UseNodesInitializedOptions = {
     includeHiddenNodes?: boolean;
 };
 /**
- * Hook which returns true when all nodes are initialized.
+ * This hook tells you whether all the nodes in a flow have been measured and given
+ *a width and height. When you add a node to the flow, this hook will return
+ *`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
+ *
+ * @example
+ * ```jsx
+ *import { useReactFlow, useNodesInitialized } from '@xyflow/react';
+ *import { useEffect, useState } from 'react';
+ *
+ *const options = {
+ *  includeHiddenNodes: false,
+ *};
+ *
+ *export default function useLayout() {
+ *  const { getNodes } = useReactFlow();
+ *  const nodesInitialized = useNodesInitialized(options);
+ *  const [layoutedNodes, setLayoutedNodes] = useState(getNodes());
+ *
+ *  useEffect(() => {
+ *    if (nodesInitialized) {
+ *      setLayoutedNodes(yourLayoutingFunction(getNodes()));
+ *    }
+ *  }, [nodesInitialized]);
+ *
+ *  return layoutedNodes;
+ *}
+ *```
  */
 export declare function useNodesInitialized(options?: UseNodesInitializedOptions): boolean;
 //# sourceMappingURL=useNodesInitialized.d.ts.map

package/dist/umd/hooks/useNodesInitialized.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useNodesInitialized.d.ts","sourceRoot":"","sources":["../../src/hooks/useNodesInitialized.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,0BAA0B,GAAG;IACvC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAsBF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA2C,GAAG,OAAO,CAIjG"}
+{"version":3,"file":"useNodesInitialized.d.ts","sourceRoot":"","sources":["../../src/hooks/useNodesInitialized.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,0BAA0B,GAAG;IACvC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAkBF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,0BAER,GACA,OAAO,CAIT"}

package/dist/umd/hooks/useOnSelectionChange.d.ts

@@ -1,12 +1,44 @@
-import type { OnSelectionChangeFunc } from '../types';
-export type UseOnSelectionChangeOptions = {
-    onChange: OnSelectionChangeFunc;
+import type { OnSelectionChangeFunc, Node, Edge } from '../types';
+export type UseOnSelectionChangeOptions<NodeType extends Node = Node, EdgeType extends Edge = Edge> = {
+    onChange: OnSelectionChangeFunc<NodeType, EdgeType>;
 };
 /**
- * Hook for registering an onSelectionChange handler.
+ * This hook lets you listen for changes to both node and edge selection. As the
+ *name implies, the callback you provide will be called whenever the selection of
+ *_either_ nodes or edges changes.
  *
  * @public
  * @param params.onChange - The handler to register
+ *
+ * @example
+ * ```jsx
+ *import { useState } from 'react';
+ *import { ReactFlow, useOnSelectionChange } from '@xyflow/react';
+ *
+ *function SelectionDisplay() {
+ *  const [selectedNodes, setSelectedNodes] = useState([]);
+ *  const [selectedEdges, setSelectedEdges] = useState([]);
+ *
+ *  // the passed handler has to be memoized, otherwise the hook will not work correctly
+ *  const onChange = useCallback(({ nodes, edges }) => {
+ *    setSelectedNodes(nodes.map((node) => node.id));
+ *    setSelectedEdges(edges.map((edge) => edge.id));
+ *  }, []);
+ *
+ *  useOnSelectionChange({
+ *    onChange,
+ *  });
+ *
+ *  return (
+ *    <div>
+ *      <p>Selected nodes: {selectedNodes.join(', ')}</p>
+ *      <p>Selected edges: {selectedEdges.join(', ')}</p>
+ *    </div>
+ *  );
+ *}
+ *```
+ *
+ * @remarks You need to memoize the passed `onChange` handler, otherwise the hook will not work correctly.
  */
-export declare function useOnSelectionChange({ onChange }: UseOnSelectionChangeOptions): void;
+export declare function useOnSelectionChange<NodeType extends Node = Node, EdgeType extends Edge = Edge>({ onChange, }: UseOnSelectionChangeOptions<NodeType, EdgeType>): void;
 //# sourceMappingURL=useOnSelectionChange.d.ts.map

package/dist/umd/hooks/useOnSelectionChange.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOnSelectionChange.d.ts","sourceRoot":"","sources":["../../src/hooks/useOnSelectionChange.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEtD,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,EAAE,qBAAqB,CAAC;CACjC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,QAAQ,EAAE,EAAE,2BAA2B,QAY7E"}
+{"version":3,"file":"useOnSelectionChange.d.ts","sourceRoot":"","sources":["../../src/hooks/useOnSelectionChange.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAElE,MAAM,MAAM,2BAA2B,CAAC,QAAQ,SAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,SAAS,IAAI,GAAG,IAAI,IAAI;IACpG,QAAQ,EAAE,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,SAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,SAAS,IAAI,GAAG,IAAI,EAAE,EAC/F,QAAQ,GACT,EAAE,2BAA2B,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAYjD"}

package/dist/umd/hooks/useOnViewportChange.d.ts

@@ -5,12 +5,30 @@ export type UseOnViewportChangeOptions = {
     onEnd?: OnViewportChange;
 };
 /**
- * Hook for registering an onViewportChange handler.
+ * 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`.
  *
  * @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';
+ *import { useOnViewportChange } from '@xyflow/react';
+ *
+ *function ViewportChangeLogger() {
+ *  useOnViewportChange({
+ *    onStart: (viewport: Viewport) => console.log('start', viewport),
+ *    onChange: (viewport: Viewport) => console.log('change', viewport),
+ *    onEnd: (viewport: Viewport) => console.log('end', viewport),
+ *  });
+ *
+ *  return null;
+ *}
+ *```
  */
 export declare function useOnViewportChange({ onStart, onChange, onEnd }: UseOnViewportChangeOptions): void;
 //# sourceMappingURL=useOnViewportChange.d.ts.map

package/dist/umd/hooks/useOnViewportChange.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOnViewportChange.d.ts","sourceRoot":"","sources":["../../src/hooks/useOnViewportChange.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIvD,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,0BAA0B,QAc3F"}
+{"version":3,"file":"useOnViewportChange.d.ts","sourceRoot":"","sources":["../../src/hooks/useOnViewportChange.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIvD,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,0BAA0B,QAc3F"}

package/dist/umd/hooks/useReactFlow.d.ts

@@ -1,9 +1,32 @@
 import type { ReactFlowInstance, Node, Edge } from '../types';
 /**
- * Hook for accessing the ReactFlow instance.
+ * 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';
+ *import { useReactFlow } from '@xyflow/react';
+ *
+ *export function NodeCounter() {
+ *  const reactFlow = useReactFlow();
+ *  const [count, setCount] = useState(0);
+ *  const countNodes = useCallback(() => {
+ *    setCount(reactFlow.getNodes().length);
+ *    // you need to pass it as a dependency if you are using it with useEffect or useCallback
+ *    // because at the first render, it's not initialized yet and some functions might not work.
+ *  }, [reactFlow]);
+ *
+ *  return (
+ *    <div>
+ *      <button onClick={countNodes}>Update count</button>
+ *      <p>There are {count} nodes in the flow.</p>
+ *    </div>
+ *  );
+ *}
+ *```
  */
 export declare function useReactFlow<NodeType extends Node = Node, EdgeType extends Edge = Edge>(): ReactFlowInstance<NodeType, EdgeType>;
 //# sourceMappingURL=useReactFlow.d.ts.map

package/dist/umd/hooks/useReactFlow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useReactFlow.d.ts","sourceRoot":"","sources":["../../src/hooks/useReactFlow.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,IAAI,EAAgD,MAAM,UAAU,CAAC;AAI5G;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,SAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,SAAS,IAAI,GAAG,IAAI,KAAK,iBAAiB,CAC3G,QAAQ,EACR,QAAQ,CACT,CAsOA"}
+{"version":3,"file":"useReactFlow.d.ts","sourceRoot":"","sources":["../../src/hooks/useReactFlow.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,IAAI,EAAgD,MAAM,UAAU,CAAC;AAI5G;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAAC,QAAQ,SAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,SAAS,IAAI,GAAG,IAAI,KAAK,iBAAiB,CAC3G,QAAQ,EACR,QAAQ,CACT,CAsOA"}

package/dist/umd/hooks/useStore.d.ts

@@ -1,6 +1,8 @@
 import type { Edge, Node, ReactFlowState } from '../types';
 /**
- * Hook for accessing the internal store. Should only be used in rare cases.
+ * 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.
  *
  * @public
  * @param selector
@@ -8,10 +10,29 @@ import type { Edge, Node, ReactFlowState } from '../types';
  * @returns The selected state slice
  *
  * @example
- * const nodes = useStore((state: ReactFlowState<MyNodeType>) => state.nodes);
+ * ```ts
+ * const nodes = useStore((state) => state.nodes);
+ * ```
  *
+ * @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.
  */
 declare function useStore<StateSlice = unknown>(selector: (state: ReactFlowState) => StateSlice, equalityFn?: (a: StateSlice, b: StateSlice) => boolean): StateSlice;
+/**
+ * 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
+ *
+ * @example
+ * ```ts
+ * const store = useStoreApi();
+ * ```
+ *
+ * @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.
+ */
 declare function useStoreApi<NodeType extends Node = Node, EdgeType extends Edge = Edge>(): {
     getState: () => ReactFlowState<NodeType, EdgeType>;
     setState: (partial: ReactFlowState<NodeType, EdgeType> | Partial<ReactFlowState<NodeType, EdgeType>> | ((state: ReactFlowState<NodeType, EdgeType>) => ReactFlowState<NodeType, EdgeType> | Partial<ReactFlowState<NodeType, EdgeType>>), replace?: boolean | undefined) => void;

package/dist/umd/hooks/useStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useStore.d.ts","sourceRoot":"","sources":["../../src/hooks/useStore.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAI3D;;;;;;;;;;;GAWG;AACH,iBAAS,QAAQ,CAAC,UAAU,GAAG,OAAO,EACpC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,UAAU,EAC/C,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,KAAK,OAAO,cASvD;AAED,iBAAS,WAAW,CAAC,QAAQ,SAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,SAAS,IAAI,GAAG,IAAI;;;;EAiB9E;AAED,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"useStore.d.ts","sourceRoot":"","sources":["../../src/hooks/useStore.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAI3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,iBAAS,QAAQ,CAAC,UAAU,GAAG,OAAO,EACpC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,UAAU,EAC/C,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,KAAK,OAAO,cASvD;AAED;;;;;;;;;;;;;GAaG;AACH,iBAAS,WAAW,CAAC,QAAQ,SAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,SAAS,IAAI,GAAG,IAAI;;;;EAiB9E;AAED,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC"}

package/dist/umd/hooks/useUpdateNodeInternals.d.ts

@@ -1,9 +1,47 @@
 import type { UpdateNodeInternals } from '@xyflow/system';
 /**
- * Hook for updating node internals.
+ * 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.
  *
  * @public
  * @returns function for updating node internals
+ *
+ * @example
+ * ```jsx
+ *import { useCallback, useState } from 'react';
+ *import { Handle, useUpdateNodeInternals } from '@xyflow/react';
+ *
+ *export default function RandomHandleNode({ id }) {
+ *  const updateNodeInternals = useUpdateNodeInternals();
+ *  const [handleCount, setHandleCount] = useState(0);
+ *  const randomizeHandleCount = useCallback(() => {
+ *   setHandleCount(Math.floor(Math.random() * 10));
+ *    updateNodeInternals(id);
+ *  }, [id, updateNodeInternals]);
+ *
+ *  return (
+ *    <>
+ *      {Array.from({ length: handleCount }).map((_, index) => (
+ *        <Handle
+ *          key={index}
+ *          type="target"
+ *          position="left"
+ *          id={`handle-${index}`}
+ *        />
+ *      ))}
+ *
+ *      <div>
+ *        <button onClick={randomizeHandleCount}>Randomize handle count</button>
+ *        <p>There are {handleCount} handles on this node.</p>
+ *      </div>
+ *    </>
+ *  );
+ *}
+ *```
+ * @remarks This hook can only be used in a component that is a child of a
+ *{@link ReactFlowProvider} or a {@link ReactFlow} component.
  */
 export declare function useUpdateNodeInternals(): UpdateNodeInternals;
 //# sourceMappingURL=useUpdateNodeInternals.d.ts.map

package/dist/umd/hooks/useUpdateNodeInternals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useUpdateNodeInternals.d.ts","sourceRoot":"","sources":["../../src/hooks/useUpdateNodeInternals.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAsB,MAAM,gBAAgB,CAAC;AAI9E;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,mBAAmB,CAkB5D"}
+{"version":3,"file":"useUpdateNodeInternals.d.ts","sourceRoot":"","sources":["../../src/hooks/useUpdateNodeInternals.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAsB,MAAM,gBAAgB,CAAC;AAI9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,sBAAsB,IAAI,mBAAmB,CAkB5D"}

package/dist/umd/hooks/useViewport.d.ts

@@ -1,9 +1,32 @@
 import type { Viewport } from '@xyflow/system';
 /**
- * Hook for getting the current viewport from the store.
+ * 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**.
  *
  * @public
  * @returns The current viewport
+ *
+ * @example
+ *
+ *```jsx
+ *import { useViewport } from '@xyflow/react';
+ *
+ *export default function ViewportDisplay() {
+ *  const { x, y, zoom } = useViewport();
+ *
+ *  return (
+ *    <div>
+ *      <p>
+ *        The viewport is currently at ({x}, {y}) and zoomed to {zoom}.
+ *      </p>
+ *    </div>
+ *  );
+ *}
+ *```
+ *
+ * @remarks This hook can only be used in a component that is a child of a
+ *{@link ReactFlowProvider} or a {@link ReactFlow} component.
  */
 export declare function useViewport(): Viewport;
 //# sourceMappingURL=useViewport.d.ts.map

package/dist/umd/hooks/useViewport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useViewport.d.ts","sourceRoot":"","sources":["../../src/hooks/useViewport.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAW/C;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAItC"}
+{"version":3,"file":"useViewport.d.ts","sourceRoot":"","sources":["../../src/hooks/useViewport.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAW/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAItC"}

package/dist/umd/hooks/useViewportHelper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useViewportHelper.d.ts","sourceRoot":"","sources":["../../src/hooks/useViewportHelper.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAExD;;;;;GAKG;AACH,QAAA,MAAM,iBAAiB,QAAO,uBAsI7B,CAAC;AAEF,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"useViewportHelper.d.ts","sourceRoot":"","sources":["../../src/hooks/useViewportHelper.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAExD;;;;;GAKG;AACH,QAAA,MAAM,iBAAiB,QAAO,uBA0I7B,CAAC;AAEF,eAAe,iBAAiB,CAAC"}