From 95dfd1d6deef2a3ac29d800e73baeab8d8ec7915 Mon Sep 17 00:00:00 2001 From: Peter Date: Tue, 5 Dec 2023 13:46:59 +0100 Subject: [PATCH 1/3] Finished TSDocs for util functions in React --- packages/react/src/utils/general.ts | 8 ++++++++ packages/system/src/utils/edges/general.ts | 6 +++--- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/packages/react/src/utils/general.ts b/packages/react/src/utils/general.ts index af5443cd..aa96ff92 100644 --- a/packages/react/src/utils/general.ts +++ b/packages/react/src/utils/general.ts @@ -58,6 +58,14 @@ export const getIncomers = getIncomersBase; */ export const addEdge = addEdgeBase; +/** + * 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; /** diff --git a/packages/system/src/utils/edges/general.ts b/packages/system/src/utils/edges/general.ts index 42baa0dc..bfadb743 100644 --- a/packages/system/src/utils/edges/general.ts +++ b/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 - - * @returns + * @param options.shouldReplaceId - should the id of the old edge be replaced with the new connection id + * @returns the updated edges array */ export const updateEdgeBase = ( oldEdge: EdgeType, From 8ee3fb64ed805b405c7c6c9476f8ba8f3a4a76c8 Mon Sep 17 00:00:00 2001 From: Peter Date: Tue, 5 Dec 2023 13:48:49 +0100 Subject: [PATCH 2/3] Added TSDoc for util functions in svelte --- packages/svelte/src/lib/utils/index.ts | 58 ++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/packages/svelte/src/lib/utils/index.ts b/packages/svelte/src/lib/utils/index.ts index 23b29448..a44f471d 100644 --- a/packages/svelte/src/lib/utils/index.ts +++ b/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; + +/** + * 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; + +/** + * 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; + +/** + * 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; From 46815e546ae03dc4b6f644cecf961fbb93c6b2cd Mon Sep 17 00:00:00 2001 From: Peter Date: Tue, 5 Dec 2023 14:26:55 +0100 Subject: [PATCH 3/3] TSDocs for applyNodeChanges & applyEdgeChanges --- packages/react/src/utils/changes.ts | 40 +++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/packages/react/src/utils/changes.ts b/packages/react/src/utils/changes.ts index c113ebe1..0cf87e6f 100644 --- a/packages/react/src/utils/changes.ts +++ b/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 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 ( + + ); + */ export function applyNodeChanges(changes: NodeChange[], nodes: Node[]): Node[] { return applyChanges(changes, nodes) as Node[]; } +/** + * Drop in function that applies edge changes to an array of edges. + * @public + * @remarks Various events on the 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 ( + + ); + */ export function applyEdgeChanges(changes: EdgeChange[], edges: Edge[]): Edge[] { return applyChanges(changes, edges) as Edge[]; }