Merge branch 'refactor/tsdoc' of github.com:xyflow/xyflow into refactor/tsdoc

packages/react/src/utils/changes.ts

@@ -139,10 +139,50 @@ function applyChanges(changes: any[], elements: any[]): any[] {
   }, initElements);
 }
 
+/**
+ * Drop in function that applies node changes to an array of nodes.
+ * @public
+ * @remarks Various events on the <ReactFlow /> component can produce an {@link NodeChange} that describes how to update the edges of your flow in some way.
+ If you don't need any custom behaviour, this util can be used to take an array of these changes and apply them to your edges.
+ * @param changes - Array of changes to apply
+ * @param nodes - Array of nodes to apply the changes to
+ * @returns Array of updated nodes
+ * @example
+ *  const onNodesChange = useCallback(
+      (changes) => {
+        setNodes((oldNodes) => applyNodeChanges(changes, oldNodes));
+      },
+      [setNodes],
+    );
+  
+    return (
+      <ReactFLow nodes={nodes} edges={edges} onNodesChange={onNodesChange} />
+    );
+ */
 export function applyNodeChanges<NodeData = any>(changes: NodeChange[], nodes: Node<NodeData>[]): Node<NodeData>[] {
   return applyChanges(changes, nodes) as Node<NodeData>[];
 }
 
+/**
+ * Drop in function that applies edge changes to an array of edges.
+ * @public
+ * @remarks Various events on the <ReactFlow /> component can produce an {@link EdgeChange} that describes how to update the edges of your flow in some way.
+ If you don't need any custom behaviour, this util can be used to take an array of these changes and apply them to your edges.
+ * @param changes - Array of changes to apply
+ * @param edges - Array of edge to apply the changes to
+ * @returns Array of updated edges
+ * @example
+ *  const onEdgesChange = useCallback(
+      (changes) => {
+        setEdges((oldEdges) => applyEdgeChanges(changes, oldEdges));
+      },
+      [setEdges],
+    );
+  
+    return (
+      <ReactFLow nodes={nodes} edges={edges} onEdgesChange={onEdgesChange} />
+    );
+ */
 export function applyEdgeChanges<EdgeData = any>(changes: EdgeChange[], edges: Edge<EdgeData>[]): Edge<EdgeData>[] {
   return applyChanges(changes, edges) as Edge<EdgeData>[];
 }

packages/react/src/utils/general.ts

@@ -58,6 +58,14 @@ export const getIncomers = getIncomersBase<Node, Edge>;
  */
 export const addEdge = addEdgeBase<Edge>;
 
+/**
+ * A handy utility to update an existing Edge with new properties
+ * @param oldEdge - The edge you want to update
+ * @param newConnection - The new connection you want to update the edge with
+ * @param edges - The array of all current edges
+ * @param options.shouldReplaceId - should the id of the old edge be replaced with the new connection id
+ * @returns the updated edges array
+ */
 export const updateEdge = updateEdgeBase<Edge>;
 
 /**

packages/svelte/src/lib/utils/index.ts

@@ -10,10 +10,68 @@ import {
 
 import type { Edge, Node } from '$lib/types';
 
+/**
+ * Test whether an object is useable as a Node
+ * @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
+ */
 export const isNode = isNodeBase<Node, Edge>;
+
+/**
+ * Test whether an object is useable as an Edge
+ * @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
+ */
 export const isEdge = isEdgeBase<Node, Edge>;
+
+/**
+ * Pass in a node, and get connected nodes where edge.source === node.id
+ * @public
+ * @param node - The node to get the connected nodes from
+ * @param nodes - The array of all nodes
+ * @param edges - The array of all edges
+ * @returns An array of nodes that are connected over eges where the source is the given node
+ */
 export const getOutgoers = getOutgoersBase<Node, Edge>;
+
+/**
+ * Pass in a node, and get connected nodes where edge.target === node.id
+ * @public
+ * @param node - The node to get the connected nodes from
+ * @param nodes - The array of all nodes
+ * @param edges - The array of all edges
+ * @returns An array of nodes that are connected over eges where the target is the given node
+ */
 export const getIncomers = getIncomersBase<Node, Edge>;
+
+/**
+ * This util is a convenience function to add a new Edge to an array of edges
+ * @remarks It also performs some validation to make sure you don't add an invalid edge or duplicate an existing one.
+ * @public
+ * @param edgeParams - Either an Edge or a Connection you want to add
+ * @param edges -  The array of all current edges
+ * @returns A new array of edges with the new edge added
+ */
 export const addEdge = addEdgeBase<Edge>;
+
+/**
+ * A handy utility to update an existing Edge with new properties
+ * @param oldEdge - The edge you want to update
+ * @param newConnection - The new connection you want to update the edge with
+ * @param edges - The array of all current edges
+ * @param options.shouldReplaceId - should the id of the old edge be replaced with the new connection id
+ * @returns the updated edges array
+ */
 export const updateEdge = updateEdgeBase<Edge>;
+
+/**
+ * Get all connecting edges for a given set of nodes
+ * @param nodes - Nodes you want to get the connected edges for
+ * @param edges - All edges
+ * @returns Array of edges that connect any of the given nodes with each other
+ */
 export const getConnectedEdges = getConnectedEdgesBase<Node, Edge>;

packages/system/src/utils/edges/general.ts

@@ -174,10 +174,10 @@ export type UpdateEdgeOptions = {
 /**
  * A handy utility to update an existing Edge with new properties
  * @param oldEdge - The edge you want to update
- * @param newConnection - The new Connection you want to update the edge with
+ * @param newConnection - The new connection you want to update the edge with
  * @param edges - The array of all current edges
- * @param options.shouldReplaceId -
+ * @param options.shouldReplaceId - should the id of the old edge be replaced with the new connection id
- * @returns
+ * @returns the updated edges array
  */
 export const updateEdgeBase = <EdgeType extends EdgeBase>(
   oldEdge: EdgeType,