Added TSDocs for several public util functions & converted comments to TSDocs for internal functions

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

@@ -69,6 +69,17 @@ 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.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.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
+ */
 export function getBezierPath({
   sourceX,
   sourceY,

packages/system/src/utils/general.ts

@@ -19,8 +19,14 @@ export const clampPosition = (position: XYPosition = { x: 0, y: 0 }, extent: Coo
   y: clamp(position.y, extent[0][1], extent[1][1]),
 });
 
-// returns a number between 0 and 1 that represents the velocity of the movement
+/**
-// when the mouse is close to the edge of the canvas
+ * Calculates the velocity of panning when the mouse is close to the edge of the canvas
+ * @internal
+ * @param value - One dimensional poition of the mouse (x or y)
+ * @param min - Minimal position on canvas before panning starts
+ * @param max - Maximal position on canvas before panning starts
+ * @returns - A number between 0 and 1 that represents the velocity of panning
+ */
 const calcAutoPanVelocity = (value: number, min: number, max: number): number => {
   if (value < min) {
     return clamp(Math.abs(value - min), 1, 50) / 50;
@@ -127,12 +133,12 @@ export const getPositionWithOrigin = ({
   };
 };
 
-export function snapPosition(position: XYPosition, snapGrid: SnapGrid = [1, 1]): XYPosition {
+export const snapPosition = (position: XYPosition, snapGrid: SnapGrid = [1, 1]): XYPosition => {
   return {
     x: snapGrid[0] * Math.round(position.x / snapGrid[0]),
     y: snapGrid[1] * Math.round(position.y / snapGrid[1]),
   };
-}
+};
 
 export const pointToRendererPoint = (
   { x, y }: XYPosition,
@@ -157,16 +163,17 @@ export const rendererPointToPoint = ({ x, y }: XYPosition, [tx, ty, tScale]: Tra
 
 /**
  * Returns a viewport that encloses the given bounds with optional padding.
- * @remarks You can determine bounds eg. with {@link getNodesBounds} and {@link getBoundsOfRects}
+ * @public
+ * @remarks You can determine bounds of nodes with {@link getNodesBounds} and {@link getBoundsOfRects}
  * @param bounds - Bounds to fit inside viewport
  * @param width - Width of the viewport
  * @param height  - Height of the viewport
  * @param minZoom - Minimum zoom level of the resulting viewport
  * @param maxZoom - Maximum zoom level of the resulting viewport
  * @param padding - Optional padding around the bounds
- * @returns A {@link Viewport} that encloses the given bounds which you can pass to {@link setViewport}
+ * @returns A transforned {@link Viewport} that encloses the given bounds which you can pass to e.g. {@link setViewport}
  * @example
- * const { x, y, zoomn } = getViewportForBounds(
+ * const { x, y, zoom } = getViewportForBounds(
   { x: 0, y: 0, width: 100, height: 100},
   1200, 800, 0.5, 2);
  */

packages/system/src/utils/graph.ts

@@ -26,14 +26,36 @@ import {
 } from '../types';
 import { errorMessages } from '../constants';
 
+/**
+ * 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 isEdgeBase = <NodeType extends NodeBase = NodeBase, EdgeType extends EdgeBase = EdgeBase>(
   element: NodeType | Connection | EdgeType
 ): element is EdgeType => 'id' in element && 'source' in element && 'target' in element;
 
+/**
+ * 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 isNodeBase = <NodeType extends NodeBase = NodeBase, EdgeType extends EdgeBase = EdgeBase>(
   element: NodeType | Connection | EdgeType
 ): element is NodeType => 'id' in element && !('source' in element) && !('target' in element);
 
+/**
+ * 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 getOutgoersBase = <NodeType extends NodeBase = NodeBase, EdgeType extends EdgeBase = EdgeBase>(
   node: NodeType | { id: string },
   nodes: NodeType[],
@@ -53,6 +75,14 @@ export const getOutgoersBase = <NodeType extends NodeBase = NodeBase, EdgeType e
   return nodes.filter((n) => outgoerIds.has(n.id));
 };
 
+/**
+ * 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 getIncomersBase = <NodeType extends NodeBase = NodeBase, EdgeType extends EdgeBase = EdgeBase>(
   node: NodeType | { id: string },
   nodes: NodeType[],
@@ -105,6 +135,14 @@ export const getNodePositionWithOrigin = (
   };
 };
 
+/**
+ * Determines a bounding box that contains all given nodes in an array
+ * @public
+ * @remarks Useful when combined with {@link getViewportForBounds} to calculate the correct transform to fit the given nodes in a viewport.
+ * @param nodes - Nodes to calculate the bounds for
+ * @param nodeOrigin - Origin of the nodes: [0, 0] - top left, [0.5, 0.5] - center
+ * @returns Bounding box enclosing all nodes
+ */
 export const getNodesBounds = (nodes: NodeBase[], nodeOrigin: NodeOrigin = [0, 0]): Rect => {
   if (nodes.length === 0) {
     return { x: 0, y: 0, width: 0, height: 0 };
@@ -284,9 +322,15 @@ export function calcNextPosition<NodeType extends NodeBase>(
   };
 }
 
-// helper function to get arrays of nodes and edges that can be deleted
+/**
-// you can pass in a list of nodes and edges that should be deleted
+ * Pass in nodes & edges to delete, get arrays of nodes and edges that actually can be deleted
-// and the function only returns elements that are deletable and also handles connected nodes and child nodes
+ * @internal
+ * @param param.nodesToRemove - The nodes to remove
+ * @param param.edgesToRemove - The edges to remove
+ * @param param.nodes - All nodes
+ * @param param.edges - All edges
+ * @returns matchingNodes: nodes that can be deleted, matchingEdges: edges that can be deleted
+ */
 export function getElementsToRemove<NodeType extends NodeBase = NodeBase, EdgeType extends EdgeBase = EdgeBase>({
   nodesToRemove,
   edgesToRemove,