From e35e0348fe767e121830dec23da5047fcfedbc06 Mon Sep 17 00:00:00 2001
From: peterkogo <peter@xyflow.com>
Date: Mon, 15 Jan 2024 16:53:55 +0100
Subject: [PATCH] added type docs for nodes & edges

---
 packages/system/src/types/edges.ts | 18 +++++++++++++++
 packages/system/src/types/nodes.ts | 37 +++++++++++++++++++++++++++++-
 2 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/packages/system/src/types/edges.ts b/packages/system/src/types/edges.ts
index c2318f0c..0b461e89 100644
--- a/packages/system/src/types/edges.ts
+++ b/packages/system/src/types/edges.ts
@@ -2,22 +2,40 @@ import { Position } from './utils';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type EdgeBase<EdgeData = any> = {
+  /** unique id of an edge */
   id: string;
+  /** type of an edge defined in edgeTypes */
   type?: string;
+  /** id of source node */
   source: string;
+  /** id of target node */
   target: string;
+  /** id of source handle
+   * only needed if there are multiple handles per node
+   */
   sourceHandle?: string | null;
+  /** id of target handle
+   * only needed if there are multiple handles per node
+   */
   targetHandle?: string | null;
   animated?: boolean;
   hidden?: boolean;
   deletable?: boolean;
   selectable?: boolean;
+  /** arbitrary data passed to an edge */
   data?: EdgeData;
   selected?: boolean;
+  /** set the marker on the beginning of an edge
+   * @example 'arrow', 'arrowclosed' or custom marker
+   */
   markerStart?: EdgeMarkerType;
+  /** set the marker on the end of an edge
+   * @example 'arrow', 'arrowclosed' or custom marker
+   */
   markerEnd?: EdgeMarkerType;
   zIndex?: number;
   ariaLabel?: string;
+  /** padding around the edge where interaction is still possible */
   interactionWidth?: number;
 };
 
diff --git a/packages/system/src/types/nodes.ts b/packages/system/src/types/nodes.ts
index c96ee085..dd6b7ac2 100644
--- a/packages/system/src/types/nodes.ts
+++ b/packages/system/src/types/nodes.ts
@@ -3,16 +3,34 @@ import { internalsSymbol } from '../constants';
 import type { XYPosition, Position, CoordinateExtent, HandleElement } from '.';
 import { Optional } from '../utils/types';
 
-// this is stuff that all nodes share independent of the framework
+/**
+ * Framework independent node data structure.
+ *
+ * @typeParam T - type of the node data
+ * @typeParam U - type of the node
+ */
 export type NodeBase<T = any, U extends string | undefined = string | undefined> = {
+  /** unique id of a node */
   id: string;
+  /** position of a node on the pane
+   * @example { x: 0, y: 0 }
+   */
   position: XYPosition;
+  /** arbitrary data passed to a node */
   data: T;
+  /** type of node defined in nodeTypes */
   type?: U;
+  /** only relevant for default, source, target nodeType. controls source position
+   * @example 'right', 'left', 'top', 'bottom'
+   */
   sourcePosition?: Position;
+  /** only relevant for default, source, target nodeType. controls target position
+   * @example 'right', 'left', 'top', 'bottom'
+   */
   targetPosition?: Position;
   hidden?: boolean;
   selected?: boolean;
+  /** is node being dragged */
   dragging?: boolean;
   draggable?: boolean;
   selectable?: boolean;
@@ -21,11 +39,21 @@ export type NodeBase<T = any, U extends string | undefined = string | undefined>
   dragHandle?: string;
   width?: number | null;
   height?: number | null;
+  /** parent node id, used for creating sub-flows */
   parentNode?: string;
   zIndex?: number;
+  /** boundary a node can be moved in
+   * @example 'parent' or [[0, 0], [100, 100]]
+   */
   extent?: 'parent' | CoordinateExtent;
   expandParent?: boolean;
   ariaLabel?: string;
+  /** origin of the node relative to it's position
+   * @example
+   * [0.5, 0.5] // centers the node
+   * [0, 0] // top left
+   * [1, 1] // bottom right
+   */
   origin?: NodeOrigin;
   handles?: NodeHandle[];
   computed?: {
@@ -47,7 +75,14 @@ export type NodeBase<T = any, U extends string | undefined = string | undefined>
 };
 
 // props that get passed to a custom node
+/**
+ * The node data structure that gets used for the nodes prop.
+ *
+ * @public
+ * @param id - The id of the node.
+ */
 export type NodeProps<T = any> = {
+  /** id of the node */
   id: NodeBase['id'];
   data: T;
   dragHandle: NodeBase['dragHandle'];