alighasami/xyflow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(utils): tsdoc update

Browse Source
This commit is contained in:
moklick
2025-02-11 15:18:41 +01:00
parent 6c937546e4
commit fb63462be3
24 changed files with 336 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/system/src/utils/dom.ts
+5 -3
View File
@@ -61,9 +61,11 @@ export const getEventPosition = (event: MouseEvent | TouchEvent, bounds?: DOMRec
};
};
// The handle bounds are calculated relative to the node element.
// We store them in the internals object of the node in order to avoid
// unnecessary recalculations.
/*
* The handle bounds are calculated relative to the node element.
* We store them in the internals object of the node in order to avoid
* unnecessary recalculations.
*/
export const getHandleBounds = (
type: 'source' | 'target',
nodeElement: HTMLDivElement,
packages/system/src/utils/edges/bezier-edge.ts
+22 -13
View File
@@ -38,8 +38,10 @@ export function getBezierEdgeCenter({
targetControlX: number;
targetControlY: number;
}): [number, number, number, number] {
// cubic bezier t=0.5 mid point, not the actual mid point, but easy to calculate
// https://stackoverflow.com/questions/67516101/how-to-find-distance-mid-point-of-bezier-curve
/*
* cubic bezier t=0.5 mid point, not the actual mid point, but easy to calculate
* https://stackoverflow.com/questions/67516101/how-to-find-distance-mid-point-of-bezier-curve
*/
const centerX = sourceX * 0.125 + sourceControlX * 0.375 + targetControlX * 0.375 + targetX * 0.125;
const centerY = sourceY * 0.125 + sourceControlY * 0.375 + targetControlY * 0.375 + targetY * 0.125;
const offsetX = Math.abs(centerX - sourceX);
@@ -70,7 +72,9 @@ function getControlWithCurvature({ pos, x1, y1, x2, y2, c }: GetControlWithCurva
}
/**
* Get a bezier path from source to target handle
* The `getBezierPath` util returns everything you need to render a bezier edge
*between two nodes.
* @public
* @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)
@@ -80,17 +84,22 @@ function getControlWithCurvature({ pos, x1, y1, x2, y2, c }: GetControlWithCurva
* @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
* ```js
* 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,
});
* 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,
*});
*```
*
* @remarks This function returns a tuple (aka a fixed-size array) to make it easier to
*work with multiple edge paths at once.
*/
export function getBezierPath({
sourceX,
packages/system/src/utils/edges/general.ts
+11 -3
View File
@@ -90,12 +90,16 @@ 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.
* This util is a convenience function to add a new Edge to an array of edges. 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
*
* @remarks If an edge with the same `target` and `source` already exists (and the same
*`targetHandle` and `sourceHandle` if those are set), then this util won't add
*a new edge even if the `id` property is different.
*
*/
export const addEdge = <EdgeType extends EdgeBase>(
edgeParams: EdgeType | Connection,
@@ -137,12 +141,16 @@ export type ReconnectEdgeOptions = {
};
/**
* A handy utility to reconnect an existing edge with new properties
* A handy utility to update an existing [`Edge`](/api-reference/types/edge) with new properties.
*This searches your edge array for an edge with a matching `id` and updates its
*properties with the connection you provide.
* @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
*
* @public
*/
export const reconnectEdge = <EdgeType extends EdgeBase>(
oldEdge: EdgeType,
packages/system/src/utils/edges/smoothstep-edge.ts
+31 -19
View File
@@ -38,8 +38,10 @@ const getDirection = ({
const distance = (a: XYPosition, b: XYPosition) => Math.sqrt(Math.pow(b.x - a.x, 2) + Math.pow(b.y - a.y, 2));
// ith this function we try to mimic a orthogonal edge routing behaviour
// It's not as good as a real orthogonal edge routing but it's faster and good enough as a default for step and smooth step edges
/*
* ith this function we try to mimic a orthogonal edge routing behaviour
* It's not as good as a real orthogonal edge routing but it's faster and good enough as a default for step and smooth step edges
*/
function getPoints({
source,
sourcePosition = Position.Bottom,
@@ -83,16 +85,20 @@ function getPoints({
if (sourceDir[dirAccessor] * targetDir[dirAccessor] === -1) {
centerX = center.x ?? defaultCenterX;
centerY = center.y ?? defaultCenterY;
// --->
// |
// >---
/*
* --->
* |
* >---
*/
const verticalSplit: XYPosition[] = [
{ x: centerX, y: sourceGapped.y },
{ x: centerX, y: targetGapped.y },
];
// |
// ---
// |
/*
* |
* ---
* |
*/
const horizontalSplit: XYPosition[] = [
{ x: sourceGapped.x, y: centerY },
{ x: targetGapped.x, y: centerY },
@@ -191,7 +197,10 @@ function getBend(a: XYPosition, b: XYPosition, c: XYPosition, size: number): str
}
/**
* Get a smooth step path from source to target handle
* The `getSmoothStepPath` util returns everything you need to render a stepped path
*between two nodes. The `borderRadius` property can be used to choose how rounded
*the corners of those steps are.
* @public
* @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)
@@ -200,17 +209,20 @@ function getBend(a: XYPosition, b: XYPosition, c: XYPosition, size: number): str
* @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
* ```js
* 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,
});
* 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,
* });
* ```
* @remarks This function returns a tuple (aka a fixed-size array) to make it easier to work with multiple edge paths at once.
*/
export function getSmoothStepPath({
sourceX,
packages/system/src/utils/edges/straight-edge.ts
+15 -11
View File
@@ -8,24 +8,28 @@ export type GetStraightPathParams = {
};
/**
* Get a straight path from source to target handle
* Calculates the straight line path between two points.
* @public
* @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
* ```js
* 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,
});
* 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,
* });
* ```
* @remarks This function returns a tuple (aka a fixed-size array) to make it easier to work with multiple edge paths at once.
*/
export function getStraightPath({
sourceX,
packages/system/src/utils/general.ts
+2 -2
View File
@@ -186,8 +186,8 @@ export const rendererPointToPoint = ({ x, y }: XYPosition, [tx, ty, tScale]: Tra
* @returns A transforned {@link Viewport} that encloses the given bounds which you can pass to e.g. {@link setViewport}
* @example
* const { x, y, zoom } = getViewportForBounds(
{ x: 0, y: 0, width: 100, height: 100},
1200, 800, 0.5, 2);
*{ x: 0, y: 0, width: 100, height: 100},
*1200, 800, 0.5, 2);
*/
export const getViewportForBounds = (
bounds: Rect,
packages/system/src/utils/graph.ts
+86 -9
View File
@@ -54,12 +54,27 @@ export const isInternalNodeBase = <NodeType extends InternalNodeBase = InternalN
): element is NodeType => 'id' in element && 'internals' in element && !('source' in element) && !('target' in element);
/**
* Pass in a node, and get connected nodes where edge.source === node.id
* This util is used to tell you what nodes, if any, are connected to the given node
*as the _target_ of an edge.
* @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
*
* @example
* ```ts
*import { getOutgoers } from '@xyflow/react';
*
*const nodes = [];
*const edges = [];
*
*const outgoers = getOutgoers(
* { id: '1', position: { x: 0, y: 0 }, data: { label: 'node' } },
* nodes,
* edges,
*);
*```
*/
export const getOutgoers = <NodeType extends NodeBase = NodeBase, EdgeType extends EdgeBase = EdgeBase>(
node: NodeType | { id: string },
@@ -81,12 +96,27 @@ export const getOutgoers = <NodeType extends NodeBase = NodeBase, EdgeType exten
};
/**
* Pass in a node, and get connected nodes where edge.target === node.id
* This util is used to tell you what nodes, if any, are connected to the given node
*as the _source_ of an edge.
* @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
*
* @example
* ```ts
*import { getIncomers } from '@xyflow/react';
*
*const nodes = [];
*const edges = [];
*
*const incomers = getIncomers(
* { id: '1', position: { x: 0, y: 0 }, data: { label: 'node' } },
* nodes,
* edges,
*);
*```
*/
export const getIncomers = <NodeType extends NodeBase = NodeBase, EdgeType extends EdgeBase = EdgeBase>(
node: NodeType | { id: string },
@@ -124,12 +154,40 @@ export type GetNodesBoundsParams<NodeType extends NodeBase = NodeBase> = {
};
/**
* Internal function for determining a bounding box that contains all given nodes in an array.
* Returns the bounding box that contains all the given nodes in an array. This can
*be useful when combined with [`getViewportForBounds`](/api-reference/utils/get-viewport-for-bounds)
*to calculate the correct transform to fit the given nodes in a viewport.
* @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 params.nodeOrigin - Origin of the nodes: [0, 0] - top left, [0.5, 0.5] - center
* @returns Bounding box enclosing all nodes
*
* @remarks This function was previously called `getRectOfNodes`
*
* @example
* ```js
*import { getNodesBounds } from '@xyflow/react';
*
*const nodes = [
* {
* id: 'a',
* position: { x: 0, y: 0 },
* data: { label: 'a' },
* width: 50,
* height: 25,
* },
* {
* id: 'b',
* position: { x: 100, y: 100 },
* data: { label: 'b' },
* width: 50,
* height: 25,
* },
*];
*
*const bounds = getNodesBounds(nodes);
*```
*/
export const getNodesBounds = <NodeType extends NodeBase = NodeBase>(
nodes: (NodeType | InternalNodeBase<NodeType> | string)[],
@@ -154,8 +212,8 @@ export const getNodesBounds = <NodeType extends NodeBase = NodeBase>(
currentNode = isId
? params.nodeLookup.get(nodeOrId)
: !isInternalNodeBase(nodeOrId)
? params.nodeLookup.get(nodeOrId.id)
: nodeOrId;
? params.nodeLookup.get(nodeOrId.id)
: nodeOrId;
}
const nodeBox = currentNode ? nodeToBox(currentNode, params.nodeOrigin) : { x: 0, y: 0, x2: 0, y2: 0 };
@@ -238,10 +296,29 @@ export const getNodesInside = <NodeType extends NodeBase = NodeBase>(
};
/**
* Get all connecting edges for a given set of nodes
* This utility filters an array of edges, keeping only those where either the source or target node is present in the given array of nodes.
* @public
* @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
*
* @example
* ```js
*import { getConnectedEdges } from '@xyflow/react';
*
*const nodes = [
* { id: 'a', position: { x: 0, y: 0 } },
* { id: 'b', position: { x: 100, y: 0 } },
*];
*
*const edges = [
* { id: 'a->c', source: 'a', target: 'c' },
* { id: 'c->d', source: 'c', target: 'd' },
*];
*
*const connectedEdges = getConnectedEdges(nodes, edges);
* // => [{ id: 'a->c', source: 'a', target: 'c' }]
*```
*/
export const getConnectedEdges = <NodeType extends NodeBase = NodeBase, EdgeType extends EdgeBase = EdgeBase>(
nodes: NodeType[],
@@ -382,9 +459,9 @@ export async function getElementsToRemove<NodeType extends NodeBase = NodeBase,
edges: EdgeType[];
onBeforeDelete?: OnBeforeDeleteBase<NodeType, EdgeType>;
}): Promise<{
nodes: NodeType[];
edges: EdgeType[];
}> {
nodes: NodeType[];
edges: EdgeType[];
}> {
const nodeIds = new Set(nodesToRemove.map((node) => node.id));
const matchingNodes: NodeType[] = [];
packages/system/src/utils/node-toolbar.ts
+4 -2
View File
@@ -15,8 +15,10 @@ export function getNodeToolbarTransform(
alignmentOffset = 1;
}
// position === Position.Top
// we set the x any y position of the toolbar based on the nodes position
/*
* position === Position.Top
* we set the x any y position of the toolbar based on the nodes position
*/
let pos = [
(nodeRect.x + nodeRect.width * alignmentOffset) * viewport.zoom + viewport.x,
nodeRect.y * viewport.zoom + viewport.y - offset,
packages/system/src/utils/store.ts
+9 -5
View File
@@ -276,8 +276,10 @@ export function handleExpandParent(
},
});
// We move all child nodes in the oppsite direction
// so the x,y changes of the parent do not move the children
/*
* We move all child nodes in the oppsite direction
* so the x,y changes of the parent do not move the children
*/
parentLookup.get(parentId)?.forEach((childNode) => {
if (!children.some((child) => child.id === childNode.id)) {
changes.push({
@@ -472,9 +474,11 @@ function addConnectionToLookup(
nodeId: string,
handleId: string | null
) {
// We add the connection to the connectionLookup at the following keys
// 1. nodeId, 2. nodeId-type, 3. nodeId-type-handleId
// If the key already exists, we add the connection to the existing map
/*
* We add the connection to the connectionLookup at the following keys
* 1. nodeId, 2. nodeId-type, 3. nodeId-type-handleId
* If the key already exists, we add the connection to the existing map
*/
let key = nodeId;
const nodeMap = connectionLookup.get(key) || new Map();
connectionLookup.set(key, nodeMap.set(connectionKey, connection));