Added some more TSDocs for util functions

packages/react/src/utils/general.ts

@@ -10,10 +10,60 @@ import {
 
 import type { Edge, Node } from '../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>;
+
 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/bezier-edge.ts

@@ -73,12 +73,24 @@ function getControlWithCurvature({ pos, x1, y1, x2, y2, c }: GetControlWithCurva
  * Get a bezier path from source to target handle
  * @param params.sourceX - The x position of the source handle
  * @param params.sourceY - The y position of the source handle
- * @param params.sourcePosition - The position of the source handle
+ * @param params.sourcePosition - The position of the source handle (default: Position.Bottom)
  * @param params.targetX - The x position of the target handle
  * @param params.targetY - The y position of the target handle
- * @param params.targetPosition - The position of the target handle
+ * @param params.targetPosition - The position of the target handle (default: Position.Top)
  * @param params.curvature - The curvature of the bezier edge
  * @returns A path string you can use in an SVG, the labelX and labelY position (center of path) and offsetX, offsetY between source handle and label
+ * @example
+ *  const source = { x: 0, y: 20 };
+    const target = { x: 150, y: 100 };
+    
+    const [path, labelX, labelY, offsetX, offsetY] = getBezierPath({
+      sourceX: source.x,
+      sourceY: source.y,
+      sourcePosition: Position.Right,
+      targetX: target.x,
+      targetY: target.y,
+      targetPosition: Position.Left,
+});
  */
 export function getBezierPath({
   sourceX,

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

@@ -124,6 +124,14 @@ const connectionExists = (edge: EdgeBase, edges: EdgeBase[]) => {
   );
 };
 
+/**
+ * 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 addEdgeBase = <EdgeType extends EdgeBase>(
   edgeParams: EdgeType | Connection,
   edges: EdgeType[]
@@ -163,6 +171,14 @@ export type UpdateEdgeOptions = {
   shouldReplaceId?: boolean;
 };
 
+/**
+ * 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 -
+ * @returns
+ */
 export const updateEdgeBase = <EdgeType extends EdgeBase>(
   oldEdge: EdgeType,
   newConnection: Connection,

packages/system/src/utils/edges/smoothstep-edge.ts

@@ -190,6 +190,28 @@ function getBend(a: XYPosition, b: XYPosition, c: XYPosition, size: number): str
   return `L ${x},${y + bendSize * yDir}Q ${x},${y} ${x + bendSize * xDir},${y}`;
 }
 
+/**
+ * Get a smooth step path from source to target handle
+ * @param params.sourceX - The x position of the source handle
+ * @param params.sourceY - The y position of the source handle
+ * @param params.sourcePosition - The position of the source handle (default: Position.Bottom)
+ * @param params.targetX - The x position of the target handle
+ * @param params.targetY - The y position of the target handle
+ * @param params.targetPosition - The position of the target handle (default: Position.Top)
+ * @returns A path string you can use in an SVG, the labelX and labelY position (center of path) and offsetX, offsetY between source handle and label
+ * @example
+ *  const source = { x: 0, y: 20 };
+    const target = { x: 150, y: 100 };
+    
+    const [path, labelX, labelY, offsetX, offsetY] = getSmoothStepPath({
+      sourceX: source.x,
+      sourceY: source.y,
+      sourcePosition: Position.Right,
+      targetX: target.x,
+      targetY: target.y,
+      targetPosition: Position.Left,
+    });
+ */
 export function getSmoothStepPath({
   sourceX,
   sourceY,

packages/system/src/utils/edges/straight-edge.ts

@@ -7,6 +7,26 @@ export type GetStraightPathParams = {
   targetY: number;
 };
 
+/**
+ * Get a straight path from source to target handle
+ * @param params.sourceX - The x position of the source handle
+ * @param params.sourceY - The y position of the source handle
+ * @param params.targetX - The x position of the target handle
+ * @param params.targetY - The y position of the target handle
+ * @returns A path string you can use in an SVG, the labelX and labelY position (center of path) and offsetX, offsetY between source handle and label
+ * @example
+ *  const source = { x: 0, y: 20 };
+    const target = { x: 150, y: 100 };
+    
+    const [path, labelX, labelY, offsetX, offsetY] = getStraightPath({
+      sourceX: source.x,
+      sourceY: source.y,
+      sourcePosition: Position.Right,
+      targetX: target.x,
+      targetY: target.y,
+      targetPosition: Position.Left,
+    });
+ */
 export function getStraightPath({
   sourceX,
   sourceY,

packages/system/src/utils/graph.ts

@@ -208,6 +208,12 @@ export const getNodesInside = <NodeType extends NodeBase>(
   return visibleNodes;
 };
 
+/**
+ * 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 getConnectedEdgesBase = <NodeType extends NodeBase = NodeBase, EdgeType extends EdgeBase = EdgeBase>(
   nodes: NodeType[],
   edges: EdgeType[]