Merge pull request #472 from xyflow/docs/new-connection-callbacks

Document new connection callback API and `useConnection` hook.

sites/reactflow.dev/src/page-data/reference/ReactFlow.props.ts

@@ -365,9 +365,11 @@ export const edgeEventHandlerProps: PropsTableProps = {
     },
     {
       name: 'onReconnectEnd',
-      type: '(event: React.MouseEvent, edge: Edge, handleType: "source" | "target") => void',
+      type: '(event: React.MouseEvent, edge: Edge, handleType: "source" | "target", connectionState: Omit<ConnectionState, \'inProgress\'>) => void',
       description: `This event fires when the user releases the source or target
-      of an editable edge. It is called even if an edge update does not occur.`,
+      of an editable edge. It is called even if an edge update does not occur.
+      You can use the fourth connectionState parameter to have different behaviour
+      when a reconnection was unsuccessful.`,
     },
     { name: 'onEdgesDelete', type: '(edges: Edge[]) => void' },
     {
@@ -392,7 +394,13 @@ export const connectionEventHandlerProps: PropsTableProps = {
       name: 'onConnectStart',
       type: '(event: React.MouseEvent, params: { nodeId: string | null; handleId: string | null; handleType: "source" | "target" | null; }) => void',
     },
-    { name: 'onConnectEnd', type: '(event: React.MouseEvent) => void' },
+    {
+      name: 'onConnectEnd',
+      type: "(event: React.MouseEvent, connectionState: Omit<ConnectionState, 'inProgress'>) => void",
+      description: `This callback will fire regardless of whether a valid connection
+      could be made or not. You can use the second connectionState parameter to
+      have different behaviour when a connection was unsuccessful.`,
+    },
     {
       name: 'onClickConnectStart',
       type: '(event: React.MouseEvent, params: { nodeId: string | null; handleId: string | null; handleType: "source" | "target" | null; }) => void',

sites/reactflow.dev/src/page-data/reference/hooks/useConnection.ts

@@ -2,10 +2,19 @@ import { type PropsTableProps } from 'xy-shared';
 
 export const signature: PropsTableProps = {
   props: [
+    { name: 'Params' },
+    {
+      name: 'selector?',
+      type: '(connection: ConnectionState<InternalNode<NodeType>>) => T',
+      description: `An optional selector function used to extract a slice of the
+      ConnectionState data. Using a selector can prevent component re-renders where
+      data you don't otherwise care about might change. If a selector is not provided,
+      the entire ConnectionState object is returned unchanged.`,
+    },
     { name: 'Returns' },
     {
       name: '',
-      type: 'ConnectionState',
+      type: 'T',
       description: '',
     },
   ],

sites/reactflow.dev/src/page-data/reference/types/InternalNode.fields.ts

@@ -0,0 +1,62 @@
+import { type PropsTableProps } from 'xy-shared';
+
+export const internalNodeFields: PropsTableProps = {
+  props: [
+    { name: 'id', type: 'string' },
+    { name: 'position', type: 'XYPosition' },
+    { name: 'data', type: 'T' },
+    { name: 'type?', type: 'U' },
+    { name: 'sourcePosition?', type: 'Position' },
+    { name: 'targetPosition?', type: 'Position' },
+    {
+      name: 'hidden?',
+      type: 'boolean',
+      description: `Whether or not the node should be visible on the canvas.`,
+    },
+    { name: 'selected?', type: 'boolean' },
+    {
+      name: 'dragging?',
+      type: 'boolean',
+      description: `Whether or not the node is currently being dragged.`,
+    },
+    {
+      name: 'draggable?',
+      type: 'boolean',
+      description: `Whether or not the node is able to be dragged.`,
+    },
+    { name: 'selectable?', type: 'boolean' },
+    { name: 'connectable?', type: 'boolean' },
+    { name: 'resizing?', type: 'boolean' },
+    { name: 'deletable?', type: 'boolean' },
+    { name: 'dragHandle?', type: 'string' },
+    { name: 'width?', type: 'number | null' },
+    { name: 'height?', type: 'number | null' },
+    { name: 'parentNode?', type: 'string' },
+    { name: 'parentId?', type: 'string' },
+    { name: 'zIndex?', type: 'number' },
+    { name: 'extent?', type: '"parent" | CoordinateExtent' },
+    {
+      name: 'expandParent?',
+      type: 'boolean',
+      description: `When true, the parent node will automatically expand if this
+      node is dragged to the edge of the parent node's bounds.`,
+    },
+    { name: 'positionAbsolute?', type: 'XYPosition' },
+    { name: 'ariaLabel?', type: 'string' },
+    { name: 'focusable?', type: 'boolean' },
+    { name: 'style?', type: 'React.CSSProperties' },
+    { name: 'className?', type: 'string' },
+    { name: 'handles?', type: 'NodeHandle[]' },
+    { name: 'origin?', type: 'NodeOrigin' },
+    {
+      name: 'measured?',
+      type: '{ width?: number, height?: number }',
+    },
+    { name: 'internals', type: 'object' },
+    { name: 'internals.positionAbsolute', type: 'XYPosition' },
+    { name: 'internals.z', type: 'number' },
+    { name: 'internals.userNode', type: 'NodeType' },
+    { name: 'internals.handleBounds?', type: 'NodeHandleBounds' },
+    { name: 'internals.bounds?', type: 'NodeBounds' },
+  ],
+};

sites/reactflow.dev/src/pages/api-reference/types/_meta.json

@@ -1,11 +1,10 @@
 {
   "background-variant": "BackgroundVariant",
-  "handle-connection": "HandleConnection",
   "connection": "Connection",
   "connection-line-component-props": "ConnectionLineComponentProps",
   "connection-line-type": "ConnectionLineType",
-  "coordinate-extent": "CoordinateExtent",
   "connection-state": "ConnectionState",
+  "coordinate-extent": "CoordinateExtent",
   "default-edge-options": "DefaultEdgeOptions",
   "delete-elements": "DeleteElements",
   "edge": "Edge",
@@ -14,15 +13,17 @@
   "edge-props": "EdgeProps",
   "fit-view-options": "FitViewOptions",
   "handle": "Handle",
+  "handle-connection": "HandleConnection",
+  "internal-node": "InternalNode",
   "marker-type": "MarkerType",
   "mini-map-node-props": "MiniMapNodeProps",
   "node": "Node",
-  "node-props": "NodeProps",
   "node-change": "NodeChange",
-  "node-origin": "NodeOrigin",
   "node-handle": "NodeHandle",
-  "on-nodes-change": "OnNodesChange",
+  "node-origin": "NodeOrigin",
+  "node-props": "NodeProps",
   "on-edges-change": "OnEdgesChange",
+  "on-nodes-change": "OnNodesChange",
   "pan-on-scroll-mode": "PanOnScrollMode",
   "panel-position": "PanelPosition",
   "position": "Position",

sites/reactflow.dev/src/pages/api-reference/types/internal-node.mdx

@@ -0,0 +1,38 @@
+---
+title: InternalNode
+description:
+  'The InternalNode is an extension of the base Node type with additional properties
+  React Flow uses internally for rendering. .'
+---
+
+import { Callout } from 'nextra/components';
+import { PropsTable } from '@/components/props-table';
+import { internalNodeFields } from '@/page-data/reference/types/InternalNode.fields.ts';
+
+# InternalNode
+
+[Source on GitHub](https://github.com/xyflow/xyflow/blob/99985b52026cf4ac65a1033178cf8c2bea4e14fa/packages/system/src/types/nodes.ts#L68)
+
+The `InternalNode` type is identical to the base [`Node`](/api-references/types/node)
+type but is extended with some additional properties used internall by React
+Flow. Some functions and callbacks that return nodes may return an `InternalNode`.
+
+```ts
+export type InternalNodeBase<NodeType extends NodeBase = NodeBase> = NodeType & {
+  measured: {
+    width?: number;
+    height?: number;
+  };
+  internals: {
+    positionAbsolute: XYPosition;
+    z: number;
+    userNode: NodeType;
+    handleBounds?: NodeHandleBounds;
+    bounds?: NodeBounds;
+  };
+};
+```
+
+## Fields
+
+<PropsTable {...internalNodeFields} />