From 4accceb202a0ecc30ea2f527342b95e2626a497f Mon Sep 17 00:00:00 2001 From: Peter Date: Tue, 5 Dec 2023 12:12:21 +0100 Subject: [PATCH] Added TSDocs for several public util functions & converted comments to TSDocs for internal functions --- .../system/src/utils/edges/bezier-edge.ts | 11 ++++ packages/system/src/utils/general.ts | 21 +++++--- packages/system/src/utils/graph.ts | 50 +++++++++++++++++-- 3 files changed, 72 insertions(+), 10 deletions(-) diff --git a/packages/system/src/utils/edges/bezier-edge.ts b/packages/system/src/utils/edges/bezier-edge.ts index 810b07d7..a8ecae31 100644 --- a/packages/system/src/utils/edges/bezier-edge.ts +++ b/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, diff --git a/packages/system/src/utils/general.ts b/packages/system/src/utils/general.ts index 7480a5e9..bc8f4dfe 100644 --- a/packages/system/src/utils/general.ts +++ b/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); */ diff --git a/packages/system/src/utils/graph.ts b/packages/system/src/utils/graph.ts index 6a946a10..38d83dc2 100644 --- a/packages/system/src/utils/graph.ts +++ b/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 = ( 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 = ( 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 = ( node: NodeType | { id: string }, nodes: NodeType[], @@ -53,6 +75,14 @@ export const getOutgoersBase = 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 = ( 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( }; } -// 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 -// and the function only returns elements that are deletable and also handles connected nodes and child nodes +/** + * Pass in nodes & edges to delete, get arrays of nodes and edges that actually can be deleted + * @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({ nodesToRemove, edgesToRemove,