@theclearsky/react-blender-nodes 0.0.3 → 0.0.4

package/README.md

@@ -5,53 +5,25 @@ a flexible and customizable node-based graph editor for web applications.
 
 ![React Blender Nodes Banner](./docs/screenshots/banner.png)
 
-## 🎯 Overview
+## Quick Links
+
+- [![Storybook](https://img.shields.io/badge/Storybook-FF4785?style=for-the-badge&logo=storybook&logoColor=white)](https://theclearsky.github.io/react-blender-nodes/?path=/story/components-organisms-fullgraph--playground) -
+  Interactive examples and component playground
+- [![NPM](https://img.shields.io/badge/NPM-%23CB3837.svg?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/@theclearsky/react-blender-nodes) -
+  Install and use in your project
+- [![GitHub Issues](https://img.shields.io/badge/GitHub-Issues-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/TheClearSky/react-blender-nodes/issues) -
+  Report bugs and issues
+- [![GitHub Discussions](https://img.shields.io/badge/GitHub-Discussions-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/TheClearSky/react-blender-nodes/discussions) -
+  Request features and discuss ideas
+
+## Overview
 
 React Blender Nodes recreates the iconic Blender node editor experience on the
 web. Built with modern React patterns and TypeScript, it offers a complete
 solution for creating interactive node-based interfaces with support for custom
 nodes, connections, and real-time manipulation.
 
-## ✨ Features
-
-### 🎨 Blender-Inspired Interface
-
-![Blender Interface](./docs/screenshots/blender-interface.png)
-
-- Authentic dark theme matching Blender's node editor
-- Familiar interactions and visual design
-- Smooth animations and transitions
-
-### 🔧 Customizable Nodes
-
-![Customizable Nodes](./docs/screenshots/customizable-nodes.png)
-
-- Dynamic inputs and outputs with custom shapes
-- Collapsible input panels for complex configurations
-- Interactive input components (text, number sliders)
-- Custom handle shapes (circle, square, diamond, star, etc.)
-
-### 🎮 Interactive Graph Editor
-
-![Interactive Graph](./docs/screenshots/interactive-graph.png)
-
-- Pan, zoom, and select nodes with intuitive controls
-- Drag and drop node connections
-- Context menu for adding new nodes
-- Real-time node manipulation
-
-### 🎯 Advanced Features
-
-![Advanced Features](./docs/screenshots/advanced-features.png)
-
-- **Handle Shapes**: 13+ custom handle shapes including geometric and artistic
-  designs
-- **Input Components**: Built-in text and number inputs with validation
-- **Panel System**: Collapsible panels for organizing complex node inputs
-- **State Management**: Integrated reducer for managing graph state
-- **TypeScript Support**: Full type safety with comprehensive definitions
-
-## 🚀 Quick Start
+## Quick Start
 
 ### Installation
 
@@ -122,7 +94,7 @@ function MyNodeEditor() {
 }
 ```
 
-### 🔒 Type Safety with Auto-Infer Helpers
+### Type Safety with Auto-Infer Helpers
 
 The auto-infer helper functions are **essential** for type safety in React
 Blender Nodes. They ensure TypeScript can properly validate type references
@@ -164,7 +136,46 @@ const dataTypes = {
 };
 ```
 
-## 📖 Usage Examples
+## Features
+
+### 🎨 Blender-Inspired Interface
+
+![Blender Interface](./docs/screenshots/blender-interface.png)
+
+- Authentic dark theme matching Blender's node editor
+- Familiar interactions and visual design
+- Smooth animations and transitions
+
+### 🔧 Customizable Nodes
+
+![Customizable Nodes](./docs/screenshots/customizable-nodes.png)
+
+- Dynamic inputs and outputs with custom shapes
+- Collapsible input panels for complex configurations
+- Interactive input components (text, number sliders)
+- Custom handle shapes (circle, square, diamond, star, etc.)
+
+### 🎮 Interactive Graph Editor
+
+![Interactive Graph](./docs/screenshots/interactive-graph.png)
+
+- Pan, zoom, and select nodes with intuitive controls
+- Drag and drop node connections
+- Context menu for adding new nodes
+- Real-time node manipulation
+
+### 🎯 Advanced Features
+
+![Advanced Features](./docs/screenshots/advanced-features.png)
+
+- **Handle Shapes**: 13+ custom handle shapes including geometric and artistic
+  designs
+- **Input Components**: Built-in text and number inputs with validation
+- **Panel System**: Collapsible panels for organizing complex node inputs
+- **State Management**: Integrated reducer for managing graph state
+- **TypeScript Support**: Full type safety with comprehensive definitions
+
+## Usage Examples
 
 ### Custom Node with Panels
 

package/dist/index.d.ts

@@ -44,12 +44,21 @@ export declare type Action<DataTypeUniqueId extends string = string, NodeTypeUni
         /** Position where to place the node */
         position: XYPosition;
     };
+} | {
+    /** Add a new node to the graph and select it */
+    type: typeof actionTypesMap.ADD_NODE_AND_SELECT;
+    payload: {
+        /** Type of node to add */
+        type: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['nodeIdToNodeType'][string];
+        /** Position where to place the node */
+        position: XYPosition;
+    };
 } | {
     /** Update nodes based on ReactFlow changes */
     type: typeof actionTypesMap.UPDATE_NODE_BY_REACT_FLOW;
     payload: {
         /** Array of node changes from ReactFlow */
-        changes: NodeChanges;
+        changes: NodeChanges<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>;
     };
 } | {
     /** Update edges based on ReactFlow changes */
@@ -81,12 +90,49 @@ export declare type Action<DataTypeUniqueId extends string = string, NodeTypeUni
 /** Map of action types for type-safe action dispatching */
 export declare const actionTypesMap: {
     readonly ADD_NODE: "ADD_NODE";
+    readonly ADD_NODE_AND_SELECT: "ADD_NODE_AND_SELECT";
     readonly UPDATE_NODE_BY_REACT_FLOW: "UPDATE_NODE_BY_REACT_FLOW";
     readonly UPDATE_EDGES_BY_REACT_FLOW: "UPDATE_EDGES_BY_REACT_FLOW";
     readonly ADD_EDGE_BY_REACT_FLOW: "ADD_EDGE_BY_REACT_FLOW";
     readonly UPDATE_INPUT_VALUE: "UPDATE_INPUT_VALUE";
 };
 
+/**
+ * Adds a new edge between two handles with type checking and inference
+ *
+ * This function validates that a connection is allowed between two handles based on
+ * their data types, handles type inference for 'inferFromConnection' types, and
+ * validates Zod schema compatibility for complex types.
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ * @template NodeTypeUniqueId - Unique identifier type for node types
+ * @template UnderlyingType - Supported underlying data types
+ * @template ComplexSchemaType - Zod schema type for complex data types
+ * @param nodes - Array of nodes in the graph
+ * @param edges - Array of edges in the graph
+ * @param newEdgeSourceNodeId - ID of the source node
+ * @param newEdgeSourceHandleId - ID of the source handle
+ * @param newEdgeTargetNodeId - ID of the target node
+ * @param newEdgeTargetHandleId - ID of the target handle
+ * @param state - The current graph state
+ * @param allowedConversionsBetweenDataTypes - Optional mapping of allowed conversions
+ * @param enableTypeInference - Whether to enable type inference
+ * @param enableComplexTypeChecking - Whether to enable complex type checking
+ * @returns Object containing updated nodes, edges, and validation result
+ */
+export declare function addEdgeWithTypeChecking<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(newEdgeSourceNodeId: string, newEdgeSourceHandleId: string, newEdgeTargetNodeId: string, newEdgeTargetHandleId: string, state: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>): {
+    updatedNodes: Nodes<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>;
+    updatedEdges: Edges;
+    validation: ConnectionValidationResult;
+};
+
+/**
+ * Mapping of allowed conversions between data types
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ */
+declare type AllowedConversionsBetweenDataTypes<DataTypeUniqueId extends string = string> = Partial<Record<DataTypeUniqueId, Partial<Record<DataTypeUniqueId, boolean>>>>;
+
 /**
  * Represents a rectangular bounding box
  */
@@ -227,7 +273,7 @@ export declare function cn(...inputs: ClassValue[]): string;
  * />
  * ```
  */
-export declare const ConfigurableEdge: ForwardRefExoticComponent<Pick<ConfigurableEdgeState, "data" | "source" | "style" | "id" | "selectable" | "deletable" | "selected" | "target" | "animated"> & EdgePosition & EdgeLabelOptions & {
+export declare const ConfigurableEdge: ForwardRefExoticComponent<Pick<ConfigurableEdgeState, "data" | "source" | "style" | "id" | "target" | "selectable" | "deletable" | "selected" | "animated"> & EdgePosition & EdgeLabelOptions & {
 sourceHandleId?: string | null;
 targetHandleId?: string | null;
 markerStart?: string;
@@ -322,9 +368,9 @@ name?: string;
 /** Background color of the node header */
 headerColor?: string;
 /** Array of inputs and input panels */
-inputs?: (ConfigurableNodeInput | ConfigurableNodeInputPanel)[];
+inputs?: (ConfigurableNodeInput<"string" | "number" | "complex" | "noEquivalent" | "inferFromConnection", never, string> | ConfigurableNodeInputPanel<"string" | "number" | "complex" | "noEquivalent" | "inferFromConnection", never, string>)[] | undefined;
 /** Array of output sockets */
-outputs?: ConfigurableNodeOutput[];
+outputs?: ConfigurableNodeOutput<"string" | "number" | "complex" | "noEquivalent" | "inferFromConnection", never, string>[] | undefined;
 /** Whether the node is currently inside a ReactFlow context */
 isCurrentlyInsideReactFlow?: boolean;
 /** Props for the node resizer component */
@@ -337,7 +383,7 @@ nodeResizerProps?: NodeResizerWithMoreControlsProps;
  * Defines an input socket on a node with optional interactive input component.
  * Supports both string and number types with type-specific onChange handlers.
  */
-export declare type ConfigurableNodeInput = {
+export declare type ConfigurableNodeInput<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = {
     /** Unique identifier for the input */
     id: string;
     /** Display name for the input */
@@ -348,6 +394,16 @@ export declare type ConfigurableNodeInput = {
     handleShape?: HandleShape;
     /** Whether to show an interactive input component when not connected */
     allowInput?: boolean;
+    /** Data type of the input, used by full graph */
+    dataType?: {
+        dataTypeObject: DataType<UnderlyingType, ComplexSchemaType>;
+        dataTypeUniqueId: DataTypeUniqueId;
+    };
+    /** Inferred data type of the input (only when type inference is enabled and datatype is inferredFromConnection and connected), used by full graph */
+    inferredDataType?: {
+        dataTypeObject: DataType<UnderlyingType, ComplexSchemaType>;
+        dataTypeUniqueId: DataTypeUniqueId;
+    } | null;
 } & ({
     /** String input type */
     type: 'string';
@@ -369,13 +425,13 @@ export declare type ConfigurableNodeInput = {
  *
  * Groups multiple inputs together in a collapsible panel for better organization.
  */
-export declare type ConfigurableNodeInputPanel = {
+export declare type ConfigurableNodeInputPanel<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = {
     /** Unique identifier for the panel */
     id: string;
     /** Display name for the panel */
     name: string;
     /** Array of inputs contained in this panel */
-    inputs: ConfigurableNodeInput[];
+    inputs: ConfigurableNodeInput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>[];
 };
 
 /**
@@ -383,7 +439,7 @@ export declare type ConfigurableNodeInputPanel = {
  *
  * Defines an output socket on a node that can be connected to inputs.
  */
-export declare type ConfigurableNodeOutput = {
+export declare type ConfigurableNodeOutput<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = {
     /** Unique identifier for the output */
     id: string;
     /** Display name for the output */
@@ -392,6 +448,16 @@ export declare type ConfigurableNodeOutput = {
     handleColor?: string;
     /** Shape of the output handle (circle, square, diamond, etc.) */
     handleShape?: HandleShape;
+    /** Data type of the output, used by full graph */
+    dataType?: {
+        dataTypeObject: DataType<UnderlyingType, ComplexSchemaType>;
+        dataTypeUniqueId: DataTypeUniqueId;
+    };
+    /** Inferred data type of the output (only when type inference is enabled and datatype is inferredFromConnection and connected), used by full graph */
+    inferredDataType?: {
+        dataTypeObject: DataType<UnderlyingType, ComplexSchemaType>;
+        dataTypeUniqueId: DataTypeUniqueId;
+    } | null;
 } & ({
     /** String output type */
     type: 'string';
@@ -406,15 +472,15 @@ export declare type ConfigurableNodeOutput = {
  * Defines the complete configuration for a customizable node with inputs, outputs,
  * and optional panels. Supports both standalone usage and ReactFlow integration.
  */
-export declare type ConfigurableNodeProps = {
+export declare type ConfigurableNodeProps<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = {
     /** Display name of the node */
     name?: string;
     /** Background color of the node header */
     headerColor?: string;
     /** Array of inputs and input panels */
-    inputs?: (ConfigurableNodeInput | ConfigurableNodeInputPanel)[];
+    inputs?: (ConfigurableNodeInput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId> | ConfigurableNodeInputPanel<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>)[];
     /** Array of output sockets */
-    outputs?: ConfigurableNodeOutput[];
+    outputs?: ConfigurableNodeOutput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>[];
     /** Whether the node is currently inside a ReactFlow context */
     isCurrentlyInsideReactFlow?: boolean;
     /** Props for the node resizer component */
@@ -464,17 +530,23 @@ export declare type ConfigurableNodeProps = {
  * />
  * ```
  */
-export declare const ConfigurableNodeReactFlowWrapper: ForwardRefExoticComponent<Pick<ConfigurableNodeState, "data" | "id" | "width" | "height" | "sourcePosition" | "targetPosition" | "dragHandle" | "parentId"> & Required<Pick<ConfigurableNodeState, "type" | "draggable" | "dragging" | "zIndex" | "selectable" | "deletable" | "selected">> & {
-isConnectable: boolean;
-positionAbsoluteX: number;
-positionAbsoluteY: number;
-} & RefAttributes<HTMLDivElement>>;
+export declare const ConfigurableNodeReactFlowWrapper: ForwardRefExoticComponent<Omit<ConfigurableNodeReactFlowWrapperProps<"string" | "number" | "complex" | "noEquivalent" | "inferFromConnection", never, string>, "position"> & RefAttributes<HTMLDivElement>>;
 
 /** Props for the ConfigurableNodeReactFlowWrapper component */
-export declare type ConfigurableNodeReactFlowWrapperProps = NodeProps<ConfigurableNodeState>;
+export declare type ConfigurableNodeReactFlowWrapperProps<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = NodeProps<ConfigurableNodeState<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>> & {
+    position: XYPosition;
+};
 
 /** State type for configurable nodes in ReactFlow */
-export declare type ConfigurableNodeState = Node_2<Omit<ConfigurableNodeProps, 'isCurrentlyInsideReactFlow'>, 'configurableNode'>;
+export declare type ConfigurableNodeState<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = Node_2<Omit<ConfigurableNodeProps<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>, 'isCurrentlyInsideReactFlow'>, 'configurableNode'>;
+
+/**
+ * Type for connection validation result
+ */
+declare type ConnectionValidationResult = {
+    isValid: boolean;
+    reason?: string;
+};
 
 /**
  * Constructs a ConfigurableNodeInput or ConfigurableNodeOutput from a type definition
@@ -514,7 +586,7 @@ export declare type ConfigurableNodeState = Node_2<Omit<ConfigurableNodeProps, '
  * );
  * ```
  */
-export declare function constructInputOrOutputOfType<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(typeOfDataType: TypeOfInput<DataTypeUniqueId> | TypeOfNode<DataTypeUniqueId>['outputs'][number], dataTypes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['dataTypes']): ConfigurableNodeInput | ConfigurableNodeOutput;
+export declare function constructInputOrOutputOfType<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(typeOfDataTypeInNode: TypeOfInput<DataTypeUniqueId> | TypeOfNode<DataTypeUniqueId>['outputs'][number], allDataTypes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['dataTypes']): ConfigurableNodeInput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId> | ConfigurableNodeOutput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>;
 
 /**
  * Constructs a ConfigurableNodeInputPanel from a type definition
@@ -560,13 +632,13 @@ export declare function constructInputOrOutputOfType<DataTypeUniqueId extends st
  * );
  * ```
  */
-export declare function constructInputPanelOfType<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(typeOfPanel: {
+export declare function constructInputPanelOfType<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(typeOfPanelInNode: {
     name: string;
     inputs: {
         name: string;
         dataType: DataTypeUniqueId;
     }[];
-}, dataTypes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['dataTypes']): ConfigurableNodeInputPanel;
+}, allDataTypes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['dataTypes']): ConfigurableNodeInputPanel<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>;
 
 /**
  * Constructs a complete node from a node type definition
@@ -625,7 +697,20 @@ export declare function constructInputPanelOfType<DataTypeUniqueId extends strin
  * );
  * ```
  */
-export declare function constructNodeOfType<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(dataTypes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['dataTypes'], nodeType: NodeTypeUniqueId, typeOfNodes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['typeOfNodes'], nodeId: string, position: XYPosition): State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['nodes'][number];
+export declare function constructNodeOfType<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(allDataTypes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['dataTypes'], nodeType: NodeTypeUniqueId, typeOfNodes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['typeOfNodes'], nodeId: string, position: XYPosition): State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['nodes'][number];
+
+/**
+ * Constructs the type of a handle from indices
+ *
+ * This function constructs the type of a handle from indices, handling both regular inputs and inputs within panels.
+ *
+ * @param allDataTypes - The all data types
+ * @param nodeType - The node type
+ * @param typeOfNodes - The type of nodes
+ * @param indices - The indices of the handle
+ * @returns The type of the handle
+ */
+export declare function constructTypeOfHandleFromIndices<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(allDataTypes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['dataTypes'], nodeType: NodeTypeUniqueId, typeOfNodes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['typeOfNodes'], indices: HandleIndices | undefined): ConfigurableNodeInput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId> | ConfigurableNodeOutput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId> | undefined;
 
 /**
  * A context-aware handle component for node inputs and outputs
@@ -890,9 +975,9 @@ export declare type Coordinate = {
  * @param contextMenuPosition - The position where the context menu was opened
  * @returns ContextMenuItem array for the context menu
  */
-export declare function createNodeContextMenu<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends 'string' | 'number' | 'complex' = 'string' | 'number' | 'complex', ComplexSchemaType extends UnderlyingType extends 'complex' ? any : never = never>({ typeOfNodes, dispatch, setContextMenu, contextMenuPosition, }: CreateNodeContextMenuProps<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>): ContextMenuItem[];
+export declare function createNodeContextMenu<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>({ typeOfNodes, dispatch, setContextMenu, contextMenuPosition, }: CreateNodeContextMenuProps<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>): ContextMenuItem[];
 
-export declare type CreateNodeContextMenuProps<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends 'string' | 'number' | 'complex' = 'string' | 'number' | 'complex', ComplexSchemaType extends UnderlyingType extends 'complex' ? any : never = never> = {
+export declare type CreateNodeContextMenuProps<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? any : never = never> = {
     typeOfNodes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['typeOfNodes'];
     dispatch: ActionDispatch<[
     action: Action<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>
@@ -919,6 +1004,10 @@ export declare type DataType<UnderlyingType extends SupportedUnderlyingTypes = S
     complexSchema: ComplexSchemaType;
     /** Color used for visual representation */
     color: string;
+    /** Shape of the handle */
+    shape?: HandleShape;
+    /** Whether this input allows direct user input */
+    allowInput?: boolean;
 } : {
     /** Display name of the data type */
     name: string;
@@ -928,6 +1017,10 @@ export declare type DataType<UnderlyingType extends SupportedUnderlyingTypes = S
     complexSchema?: undefined;
     /** Color used for visual representation */
     color: string;
+    /** Shape of the handle */
+    shape?: HandleShape;
+    /** Whether this input allows direct user input */
+    allowInput?: boolean;
 };
 
 /**
@@ -1053,6 +1146,16 @@ export declare type FullGraphProps<DataTypeUniqueId extends string = string, Nod
     ]>;
 };
 
+declare type HandleIndices = {
+    type: 'input';
+    index1: number;
+    index2: number | undefined;
+} | {
+    type: 'output';
+    index1: number;
+    index2: undefined;
+};
+
 /** Type representing all available handle shapes */
 export declare type HandleShape = (typeof handleShapesMap)[keyof typeof handleShapesMap];
 
@@ -1192,6 +1295,16 @@ export declare function isNumberInRange(number: number, min: number, max: number
  */
 export declare function isSupportedUnderlyingType(type: string): type is SupportedUnderlyingTypes;
 
+/**
+ * Type guard to check if a string is a valid DataTypeUniqueId
+ */
+export declare function isValidDataTypeId<DataTypeUniqueId extends string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(id: string, dataTypes: Record<DataTypeUniqueId, DataType<UnderlyingType, ComplexSchemaType>>): id is DataTypeUniqueId;
+
+/**
+ * Type guard to check if a string is a valid NodeTypeUniqueId
+ */
+export declare function isValidNodeTypeUniqueId<NodeTypeUniqueId extends string>(id: string, nodeIdToNodeType: Record<string, NodeTypeUniqueId>): id is NodeTypeUniqueId;
+
 /**
  * Main reducer function for managing graph state
  *
@@ -1269,6 +1382,36 @@ export declare function isSupportedUnderlyingType(type: string): type is Support
  */
 export declare function mainReducer<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(oldState: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>, action: Action<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>): State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>;
 
+/**
+ * Helper function to create a mapping of allowed conversions between data types with automatic type inference
+ *
+ * This function is essential for type safety when creating a mapping of allowed conversions between data types.
+ * It ensures that TypeScript can properly infer and validate the types throughout your graph system,
+ * preventing runtime errors and providing better IDE support.
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ * @param input - The mapping of allowed conversions between data types
+ * @returns The mapping with proper typing
+ *
+ * @example
+ * ```tsx
+ * // ✅ Type-safe - TypeScript will validate node type references
+ * const allowedConversionsBetweenDataTypes = makeAllowedConversionsBetweenDataTypesWithAutoInfer({
+ *   'inputDataType': {
+ *     'outputDataType': true,
+ *   },
+ * });
+ *
+ * // ❌ Without auto-infer - TypeScript can't validate node type references
+ * const allowedConversionsBetweenDataTypes = {
+ *   'inputDataType': {
+ *     'outputDataType': true,
+ *   },
+ * };
+ * ```
+ */
+export declare function makeAllowedConversionsBetweenDataTypesWithAutoInfer<DataTypeUniqueId extends string = string>(input: AllowedConversionsBetweenDataTypes<DataTypeUniqueId>): Partial<Record<DataTypeUniqueId, Partial<Record<DataTypeUniqueId, boolean>>>>;
+
 /**
  * Helper function to create a data type with automatic type inference
  *
@@ -1412,7 +1555,7 @@ export declare function makeTypeOfNodeWithAutoInfer<DataTypeUniqueId extends str
 /**
  * Array of node changes for ReactFlow
  */
-export declare type NodeChanges = NodeChange<ConfigurableNodeState>[];
+export declare type NodeChanges<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = NodeChange<Optional<ConfigurableNodeReactFlowWrapperProps<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>, NodeOptionalKeys>>[];
 
 /**
  * Mapping from node IDs to their node types
@@ -1421,6 +1564,8 @@ export declare type NodeChanges = NodeChange<ConfigurableNodeState>[];
  */
 export declare type NodeIdToNodeType<NodeTypeUniqueId extends string = string> = Record<string, NodeTypeUniqueId>;
 
+declare type NodeOptionalKeys = 'draggable' | 'zIndex' | 'selectable' | 'deletable' | 'dragging' | 'selected' | 'isConnectable' | 'positionAbsoluteX' | 'positionAbsoluteY';
+
 /**
  * Enhanced node resizer component with customizable controls
  *
@@ -1489,7 +1634,9 @@ export declare type NodeResizerWithMoreControlsProps = NodeResizerProps & {
 /**
  * Array of configurable nodes in the graph
  */
-export declare type Nodes = ConfigurableNodeState[];
+export declare type Nodes<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = Optional<ConfigurableNodeReactFlowWrapperProps<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>, NodeOptionalKeys>[];
+
+declare type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
 
 /**
  * ReactFlow-aware input component that automatically updates node data
@@ -1511,6 +1658,35 @@ export declare type ReactFlowAwareInputProps = {
     input: ConfigurableNodeInput;
 };
 
+/**
+ * Removes an edge between two handles with type checking and inference
+ *
+ * This function validates that a connection is removed between two handles based on
+ * their data types, handles type inference for 'inferFromConnection' types, and
+ * validates Zod schema compatibility for complex types.
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ * @template NodeTypeUniqueId - Unique identifier type for node types
+ * @template UnderlyingType - Supported underlying data types
+ * @template ComplexSchemaType - Zod schema type for complex data types
+ * @param nodes - Array of nodes in the graph
+ * @param edges - Array of edges in the graph
+ * @param removedEdgeSourceNodeId - ID of the source node
+ * @param removedEdgeSourceHandleId - ID of the source handle
+ * @param removedEdgeTargetNodeId - ID of the target node
+ * @param removedEdgeTargetHandleId - ID of the target handle
+ * @param state - The current graph state
+ * @param allowedConversionsBetweenDataTypes - Optional mapping of allowed conversions
+ * @param enableTypeInference - Whether to enable type inference
+ * @param enableComplexTypeChecking - Whether to enable complex type checking
+ * @returns Object containing updated nodes, edges, and validation result
+ */
+export declare function removeEdgeWithTypeChecking<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(removedEdge: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['edges'][number], state: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>, removedEdgeChange: EdgeChange<ConfigurableEdgeState>): {
+    updatedNodes: Nodes<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>;
+    updatedEdges: Edges;
+    validation: ConnectionValidationResult;
+};
+
 /**
  * Sanitizes a number to be shown as a text, removing the trailing zeros after the decimal point if the number is an integer
  * @param value - The number to sanitize
@@ -1604,11 +1780,17 @@ export declare type State<DataTypeUniqueId extends string = string, NodeTypeUniq
     /** Map of node type definitions */
     typeOfNodes: Record<NodeTypeUniqueId, TypeOfNode<DataTypeUniqueId>>;
     /** Array of nodes in the graph */
-    nodes: Nodes;
+    nodes: Nodes<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>;
     /** Mapping from node IDs to their types */
     nodeIdToNodeType: NodeIdToNodeType<NodeTypeUniqueId>;
     /** Array of edges in the graph */
     edges: Edges;
+    /** Optional mapping of allowed conversions between data types */
+    allowedConversionsBetweenDataTypes?: AllowedConversionsBetweenDataTypes<DataTypeUniqueId>;
+    /** Whether to enable type inference */
+    enableTypeInference?: boolean;
+    /** Whether to enable complex type checking */
+    enableComplexTypeChecking?: boolean;
 };
 
 /**