chore(docs): Add comments

src/types/changes.ts

@@ -2,13 +2,6 @@ import { XYPosition, Dimensions } from './flow'
 import { NodeHandleBounds, Node, GraphNode, CoordinateExtent } from './node'
 import { Edge } from './edge'
 
-export type CreatePositionChangeParams = {
-  node: GraphNode
-  nodeExtent: CoordinateExtent
-  diff?: XYPosition
-  dragging?: boolean
-}
-
 export type NodeDimensionChange = {
   id: string
   type: 'dimensions'

src/types/components.ts

@@ -23,7 +23,7 @@ export type DefaultEdgeTypes = { [key in 'default' | 'straight' | 'smoothstep' |
 export type DefaultNodeTypes = { [key in 'input' | 'output' | 'default']: NodeComponent }
 
 export interface BackgroundProps {
-  /** The background pattern */
+  /** The background pattern variant, {@link BackgroundVariant} */
   variant?: BackgroundVariant
   /** Background pattern gap */
   gap?: number
@@ -61,6 +61,7 @@ export interface ControlEvents {
   (event: 'interaction-change', active: boolean): void
 }
 
+/** expects a node and returns a color value */
 export type StringFunc<N = any> = (node: Node<N> | GraphNode<N>) => string
 export type ShapeRendering = 'inherit' | 'auto' | 'geometricPrecision' | 'optimizeSpeed' | 'crispEdges' | undefined
 
@@ -79,6 +80,7 @@ export interface MiniMapProps<N = any> {
   maskColor?: string
 }
 
+/** these props are passed to mini map node slots */
 export interface MiniMapNodeProps {
   position: XYPosition
   dimensions: Dimensions
@@ -89,6 +91,7 @@ export interface MiniMapNodeProps {
   strokeWidth?: number
 }
 
+/** these props are passed to edge texts */
 export interface EdgeTextProps extends HTMLAttributes {
   x: number
   y: number

src/types/connection.ts

@@ -39,12 +39,6 @@ export enum ConnectionMode {
   Loose = 'loose',
 }
 
-export type SetConnectionId = {
-  connectionNodeId: string | undefined
-  connectionHandleId: string | undefined
-  connectionHandleType: HandleType | undefined
-}
-
 export interface ConnectionLineProps<N = any> {
   /** Source X position of the connection line */
   sourceX: number
@@ -58,7 +52,9 @@ export interface ConnectionLineProps<N = any> {
   targetY: number
   /** Target position of the connection line */
   targetPosition: Position
+  /** the shape of the connection line when active */
   connectionLineType: ConnectionLineType
+  /** extra styles */
   connectionLineStyle: CSSProperties
   /** All currently stored nodes */
   nodes: GraphNode<N>[]

src/types/edge.ts

@@ -30,7 +30,7 @@ export interface EdgeMarker {
 
 export interface MarkerProps {
   id: string
-  type: MarkerType
+  type: MarkerType | string
   color?: string
   width?: number
   height?: number
@@ -88,6 +88,7 @@ export interface EdgePositions {
   targetY: number
 }
 
+/** Internal edge type */
 export type GraphEdge<T = any, N = T> = Edge<T> & {
   sourceNode: GraphNode<N>
   targetNode: GraphNode<N>
@@ -95,10 +96,11 @@ export type GraphEdge<T = any, N = T> = Edge<T> & {
   z?: number
 } & EdgePositions
 
+/** these props are passed to edge components */
 export interface EdgeProps<Data = any> {
   id: string
-  sourceNode: any
-  targetNode: any
+  sourceNode: GraphNode
+  targetNode: GraphNode
   label?:
     | string
     | {
@@ -121,7 +123,7 @@ export interface EdgeProps<Data = any> {
   target: string
   sourceHandle?: string
   targetHandle?: string
-  labelStyle?: any
+  labelStyle?: CSSProperties
   labelShowBg?: boolean
   labelBgStyle?: any
   labelBgPadding?: [number, number]
@@ -133,10 +135,11 @@ export interface EdgeProps<Data = any> {
   curvature?: number
 }
 
+/** these props are passed to smooth step edges */
 export interface SmoothStepEdgeProps<Data = any> extends EdgeProps<Data> {
   id: string
-  sourceNode: any
-  targetNode: any
+  sourceNode: GraphNode
+  targetNode: GraphNode
   label?:
     | string
     | {

src/types/flow.ts

@@ -5,8 +5,11 @@ import { ConnectionLineType, ConnectionMode } from './connection'
 import { KeyCode, PanOnScrollMode, UseZoomPanHelper } from './zoom'
 import { DefaultEdgeTypes, DefaultNodeTypes, EdgeComponent, NodeComponent } from './components'
 
+/** an internal element  */
 export type FlowElement<N = any, E = any> = GraphNode<N> | GraphEdge<E>
 export type FlowElements<N = any, E = any> = FlowElement<N, E>[]
+
+/** base element props */
 export interface Element<Data = any> {
   id: string
   label?:
@@ -23,8 +26,10 @@ export interface Element<Data = any> {
 }
 export type Elements<N = any, E = any> = (Node<N> | Edge<E>)[]
 
+/** Transform x, y, z */
 export type Transform = [number, number, number]
 
+/** Handle Positions */
 export enum Position {
   Left = 'left',
   Top = 'top',

src/types/node.ts

@@ -10,41 +10,55 @@ export type NodeHandleBounds = {
 }
 
 export interface Node<T = any> extends Element<T> {
+  /** node position x, y */
   position: XYPosition
+  /** node type, can be a default type or a custom type */
   type?: keyof DefaultNodeTypes | string
+  /** handle position */
   targetPosition?: Position
+  /** handle position */
   sourcePosition?: Position
   draggable?: boolean
   selectable?: boolean
   connectable?: boolean
   dragHandle?: string
+  /** move on grid */
   snapGrid?: SnapGrid
+  /** called when used as target for new connection */
   isValidTargetPos?: ValidConnectionFunc
+  /** called when used as source for new connection */
   isValidSourcePos?: ValidConnectionFunc
+  /** define node extent, i.e. area in which node can be moved */
   extent?: 'parent' | CoordinateExtent
+  /** expands parent area to fit child node */
   expandParent?: boolean
+  /** define node as a child node by setting a parent node id */
   parentNode?: string
 }
 
 export interface GraphNode<T = any> extends Node<T> {
+  /** absolute position in relation to parent elements + z-index */
   computedPosition: XYZPosition
   handleBounds: NodeHandleBounds
+  /** node width, height */
   dimensions: Dimensions
   isParent: boolean
   selected: boolean
   dragging: boolean
 }
 
+/** these props are passed to node components */
 export interface NodeProps<T = any> {
   id: string
+  /** node DOM-element */
   nodeElement: HTMLDivElement
   type: string
   data: T
   selected: boolean
   connectable: boolean
-  /** computed position is the position relative to the node's extent (i.e. parent or CoordinateExtent) */
+  /** absolute position in relation to parent elements + z-index */
   computedPosition: XYZPosition
-  /** x and y position on the graph */
+  /** x, y position */
   position: XYPosition
   /** node dimensions (width, height) */
   dimensions: Dimensions
@@ -54,7 +68,9 @@ export interface NodeProps<T = any> {
         props?: any
         component: any
       }
+  /** called when used as target for new connection */
   isValidTargetPos?: ValidConnectionFunc
+  /** called when used as source for new connection */
   isValidSourcePos?: ValidConnectionFunc
   parentNode?: string
   dragging: boolean

src/types/store.ts

@@ -10,10 +10,13 @@ import { NodeChange, EdgeChange } from './changes'
 import { StartHandle, HandleType } from './handle'
 
 export interface State<N = any, E = N> extends Omit<FlowOptions<N, E>, 'id' | 'modelValue'> {
+  /** Event hooks, you can manipulate the triggers on your own peril */
   hooks: FlowHooks<N, E>
   instance: FlowInstance<N, E> | null
 
+  /** all stored nodes */
   nodes: GraphNode<N>[]
+  /** all stored edges */
   edges: GraphEdge<E>[]
 
   d3Zoom: D3Zoom | null
@@ -24,7 +27,9 @@ export interface State<N = any, E = N> extends Omit<FlowOptions<N, E>, 'id' | 'm
   defaultZoom: number
   translateExtent: CoordinateExtent
   nodeExtent: CoordinateExtent
+  /** zoom pane dimensions */
   dimensions: Dimensions
+  /** transform x, y, z */
   transform: Transform
   onlyRenderVisibleElements: boolean
   defaultPosition: [number, number]
@@ -83,9 +88,13 @@ export interface State<N = any, E = N> extends Omit<FlowOptions<N, E>, 'id' | 'm
 export interface Actions<N = any, E = N> {
   /** @deprecated use setNodes / setEdges instead */
   setElements: (elements: Elements<N, E>, extent?: CoordinateExtent) => void
+  /** parses nodes and re-sets the state */
   setNodes: (nodes: Node<N>[], extent?: CoordinateExtent) => void
+  /** parses edges and re-sets the state */
   setEdges: (edges: Edge<E>[]) => void
+  /** parses nodes and adds to state */
   addNodes: <NA = N>(nodes: Node<NA>[], extent?: CoordinateExtent) => void
+  /** parses edges and adds to state */
   addEdges: <EA = E>(edgesOrConnections: (Edge<EA> | Connection)[]) => void
   updateEdge: <EU = E>(oldEdge: GraphEdge<EU>, newConnection: Connection) => boolean
   applyEdgeChanges: <ED = E>(changes: EdgeChange[]) => GraphEdge<ED>[]
@@ -113,7 +122,9 @@ export interface Actions<N = any, E = N> {
 export interface Getters<N = any, E = N> {
   getEdgeTypes: Record<keyof DefaultEdgeTypes | string, EdgeComponent>
   getNodeTypes: Record<keyof DefaultNodeTypes | string, NodeComponent>
+  /** filters hidden nodes */
   getNodes: GraphNode<N>[]
+  /** filters hidden edges */
   getEdges: GraphEdge<E>[]
   getNode: (id: string) => GraphNode<N> | undefined
   getEdge: (id: string) => GraphEdge<E> | undefined

src/utils/changes.ts

@@ -1,6 +1,5 @@
 import { clampPosition, isGraphNode } from './graph'
 import {
-  CreatePositionChangeParams,
   EdgeChange,
   EdgeSelectionChange,
   ElementChange,
@@ -11,8 +10,17 @@ import {
   NodeSelectionChange,
   NodePositionChange,
   Getters,
+  CoordinateExtent,
+  XYPosition,
 } from '~/types'
 
+type CreatePositionChangeParams = {
+  node: GraphNode
+  nodeExtent: CoordinateExtent
+  diff?: XYPosition
+  dragging?: boolean
+}
+
 function handleParentExpand(updateItem: GraphNode, getNode: Getters['getNode']) {
   const parent = updateItem.parentNode ? getNode(updateItem.parentNode) : undefined
   if (parent) {