From b264c11c549db15587cac751812a51127894c396 Mon Sep 17 00:00:00 2001 From: Peter Date: Tue, 5 Dec 2023 13:35:12 +0100 Subject: [PATCH] Added some more TSDocs for util functions --- packages/react/src/utils/general.ts | 50 +++++++++++++++++++ .../system/src/utils/edges/bezier-edge.ts | 16 +++++- packages/system/src/utils/edges/general.ts | 16 ++++++ .../system/src/utils/edges/smoothstep-edge.ts | 22 ++++++++ .../system/src/utils/edges/straight-edge.ts | 20 ++++++++ packages/system/src/utils/graph.ts | 6 +++ 6 files changed, 128 insertions(+), 2 deletions(-) diff --git a/packages/react/src/utils/general.ts b/packages/react/src/utils/general.ts index e13247c1..af5443cd 100644 --- a/packages/react/src/utils/general.ts +++ b/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; + +/** + * 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; + +/** + * 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; + +/** + * 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; + +/** + * 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; + export const updateEdge = updateEdgeBase; + +/** + * 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; diff --git a/packages/system/src/utils/edges/bezier-edge.ts b/packages/system/src/utils/edges/bezier-edge.ts index a8ecae31..640deffa 100644 --- a/packages/system/src/utils/edges/bezier-edge.ts +++ b/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, diff --git a/packages/system/src/utils/edges/general.ts b/packages/system/src/utils/edges/general.ts index 9ffd8e24..42baa0dc 100644 --- a/packages/system/src/utils/edges/general.ts +++ b/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 = ( 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 = ( oldEdge: EdgeType, newConnection: Connection, diff --git a/packages/system/src/utils/edges/smoothstep-edge.ts b/packages/system/src/utils/edges/smoothstep-edge.ts index ba3e95a9..40954457 100644 --- a/packages/system/src/utils/edges/smoothstep-edge.ts +++ b/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, diff --git a/packages/system/src/utils/edges/straight-edge.ts b/packages/system/src/utils/edges/straight-edge.ts index 9cc6d928..9940bfea 100644 --- a/packages/system/src/utils/edges/straight-edge.ts +++ b/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, diff --git a/packages/system/src/utils/graph.ts b/packages/system/src/utils/graph.ts index 38d83dc2..4732ff0b 100644 --- a/packages/system/src/utils/graph.ts +++ b/packages/system/src/utils/graph.ts @@ -208,6 +208,12 @@ export const getNodesInside = ( 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 = ( nodes: NodeType[], edges: EdgeType[]