@theclearsky/react-blender-nodes 0.0.2 → 0.0.4

package/dist/index.d.ts

@@ -35,7 +35,7 @@ import { z } from 'zod';
  * @template UnderlyingType - Supported underlying data types ('string' | 'number' | 'complex')
  * @template ComplexSchemaType - Zod schema type for complex data types
  */
-declare type Action<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never> = {
+export declare type Action<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never> = {
     /** Add a new node to the graph */
     type: typeof actionTypesMap.ADD_NODE;
     payload: {
@@ -44,12 +44,21 @@ declare type Action<DataTypeUniqueId extends string = string, NodeTypeUniqueId e
         /** 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 */
@@ -79,14 +88,51 @@ declare type Action<DataTypeUniqueId extends string = string, NodeTypeUniqueId e
 };
 
 /** Map of action types for type-safe action dispatching */
-declare const actionTypesMap: {
+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
  */
@@ -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,187 @@ 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
+ *
+ * This function creates the appropriate input or output instance based on the data type's
+ * underlying type (string or number). It generates a unique ID and applies the correct
+ * configuration including handle color and input allowance.
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ * @template NodeTypeUniqueId - Unique identifier type for node types
+ * @template UnderlyingType - Supported underlying data types ('string' | 'number' | 'complex')
+ * @template ComplexSchemaType - Zod schema type for complex data types
+ * @param typeOfDataType - The type definition for the input or output
+ * @param dataTypes - Map of data type definitions
+ * @returns Constructed input or output instance
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   constructInputOrOutputOfType,
+ *   makeDataTypeWithAutoInfer
+ * } from 'react-blender-nodes';
+ *
+ * // Define data types with auto-infer for type safety
+ * const dataTypes = {
+ *   stringType: makeDataTypeWithAutoInfer({
+ *     name: 'String',
+ *     underlyingType: 'string',
+ *     color: '#4A90E2',
+ *   }),
+ * };
+ *
+ * // Construct input with type safety
+ * const input = constructInputOrOutputOfType(
+ *   { name: 'Value', dataType: 'stringType', allowInput: true },
+ *   dataTypes
+ * );
+ * ```
+ */
+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
+ *
+ * This function creates an input panel with multiple inputs based on the panel type
+ * definition. It generates a unique panel ID and constructs all the inputs within
+ * the panel using the constructInputOrOutputOfType function.
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ * @template NodeTypeUniqueId - Unique identifier type for node types
+ * @template UnderlyingType - Supported underlying data types ('string' | 'number' | 'complex')
+ * @template ComplexSchemaType - Zod schema type for complex data types
+ * @param typeOfPanel - The type definition for the input panel
+ * @param dataTypes - Map of data type definitions
+ * @returns Constructed input panel instance
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   constructInputPanelOfType,
+ *   makeDataTypeWithAutoInfer
+ * } from 'react-blender-nodes';
+ *
+ * // Define data types with auto-infer for type safety
+ * const dataTypes = {
+ *   numberType: makeDataTypeWithAutoInfer({
+ *     name: 'Number',
+ *     underlyingType: 'number',
+ *     color: '#E74C3C',
+ *   }),
+ * };
+ *
+ * // Construct panel with type safety
+ * const panel = constructInputPanelOfType(
+ *   {
+ *     name: 'Settings',
+ *     inputs: [
+ *       { name: 'Width', dataType: 'numberType' },
+ *       { name: 'Height', dataType: 'numberType' }
+ *     ]
+ *   },
+ *   dataTypes
+ * );
+ * ```
+ */
+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;
+    }[];
+}, allDataTypes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['dataTypes']): ConfigurableNodeInputPanel<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>;
+
+/**
+ * Constructs a complete node from a node type definition
+ *
+ * This function creates a fully configured ReactFlow node based on the node type
+ * definition. It processes all inputs (including panels) and outputs, generates
+ * unique IDs, and sets up the node with the correct position and configuration.
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ * @template NodeTypeUniqueId - Unique identifier type for node types
+ * @template UnderlyingType - Supported underlying data types ('string' | 'number' | 'complex')
+ * @template ComplexSchemaType - Zod schema type for complex data types
+ * @param dataTypes - Map of data type definitions
+ * @param nodeType - The unique identifier of the node type
+ * @param typeOfNodes - Map of node type definitions
+ * @param nodeId - Unique identifier for the new node instance
+ * @param position - Position where the node should be placed
+ * @returns Complete ReactFlow node instance
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   constructNodeOfType,
+ *   makeStateWithAutoInfer,
+ *   makeNodeIdToNodeTypeWithAutoInfer,
+ *   makeTypeOfNodeWithAutoInfer,
+ *   makeDataTypeWithAutoInfer
+ * } from 'react-blender-nodes';
+ *
+ * // Define data types with auto-infer for type safety
+ * const dataTypes = {
+ *   stringType: makeDataTypeWithAutoInfer({
+ *     name: 'String',
+ *     underlyingType: 'string',
+ *     color: '#4A90E2',
+ *   }),
+ * };
+ *
+ * // Define node types with auto-infer for type safety
+ * const typeOfNodes = {
+ *   inputNode: makeTypeOfNodeWithAutoInfer({
+ *     name: 'Input Node',
+ *     headerColor: '#C44536',
+ *     inputs: [{ name: 'Input', dataType: 'stringType', allowInput: true }],
+ *     outputs: [{ name: 'Output', dataType: 'stringType' }]
+ *   }),
+ * };
+ *
+ * // Construct node with type safety
+ * const node = constructNodeOfType(
+ *   dataTypes,
+ *   'inputNode',
+ *   typeOfNodes,
+ *   'node-123',
+ *   { x: 100, y: 100 }
+ * );
+ * ```
+ */
+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
@@ -739,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>
@@ -759,7 +995,7 @@ export declare type CreateNodeContextMenuProps<DataTypeUniqueId extends string =
  * @template UnderlyingType - The underlying type of the data
  * @template ComplexSchemaType - Zod schema type for complex data types
  */
-declare type DataType<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never> = UnderlyingType extends 'complex' ? {
+export declare type DataType<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never> = UnderlyingType extends 'complex' ? {
     /** Display name of the data type */
     name: string;
     /** The underlying type of the data */
@@ -768,6 +1004,10 @@ declare type DataType<UnderlyingType extends SupportedUnderlyingTypes = Supporte
     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;
@@ -777,6 +1017,10 @@ declare type DataType<UnderlyingType extends SupportedUnderlyingTypes = Supporte
     complexSchema?: undefined;
     /** Color used for visual representation */
     color: string;
+    /** Shape of the handle */
+    shape?: HandleShape;
+    /** Whether this input allows direct user input */
+    allowInput?: boolean;
 };
 
 /**
@@ -902,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];
 
@@ -1026,17 +1280,291 @@ export declare function isCoordinateInBox(coordinate: Coordinate, box: Box, xAxi
  */
 export declare function isNumberInRange(number: number, min: number, max: number, minInclusive?: boolean, maxInclusive?: boolean): boolean;
 
+/**
+ * Type guard to check if a string is a supported underlying type
+ *
+ * @param type - The string to check
+ * @returns True if the string is a supported underlying type
+ *
+ * @example
+ * ```tsx
+ * if (isSupportedUnderlyingType('string')) {
+ *   // type is now 'string'
+ * }
+ * ```
+ */
+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
+ *
+ * This reducer handles all state updates for the graph including nodes, edges,
+ * and input values. It uses Immer for immutable state updates and integrates
+ * with ReactFlow for node and edge management.
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ * @template NodeTypeUniqueId - Unique identifier type for node types
+ * @template UnderlyingType - Supported underlying data types ('string' | 'number' | 'complex')
+ * @template ComplexSchemaType - Zod schema type for complex data types
+ * @param oldState - The current state of the graph
+ * @param action - The action to apply to the state
+ * @returns New state after applying the action
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   mainReducer,
+ *   makeStateWithAutoInfer,
+ *   makeNodeIdToNodeTypeWithAutoInfer,
+ *   makeTypeOfNodeWithAutoInfer,
+ *   makeDataTypeWithAutoInfer
+ * } from 'react-blender-nodes';
+ *
+ * // Create type-safe state with auto-infer helpers
+ * const dataTypes = {
+ *   stringType: makeDataTypeWithAutoInfer({
+ *     name: 'String',
+ *     underlyingType: 'string',
+ *     color: '#4A90E2',
+ *   }),
+ * };
+ *
+ * const typeOfNodes = {
+ *   inputNode: makeTypeOfNodeWithAutoInfer({
+ *     name: 'Input Node',
+ *     headerColor: '#C44536',
+ *     inputs: [{ name: 'Input', dataType: 'stringType', allowInput: true }],
+ *     outputs: [{ name: 'Output', dataType: 'stringType' }],
+ *   }),
+ * };
+ *
+ * const nodeIdToNodeType = makeNodeIdToNodeTypeWithAutoInfer({
+ *   'node-1': 'inputNode',
+ * });
+ *
+ * const state = makeStateWithAutoInfer({
+ *   dataTypes,
+ *   typeOfNodes,
+ *   nodeIdToNodeType,
+ *   nodes: [],
+ *   edges: [],
+ * });
+ *
+ * // Add a new node (type-safe!)
+ * const newState = mainReducer(state, {
+ *   type: 'ADD_NODE',
+ *   payload: {
+ *     type: 'inputNode',
+ *     position: { x: 100, y: 100 },
+ *   },
+ * });
+ *
+ * // Update input value (type-safe!)
+ * const updatedState = mainReducer(newState, {
+ *   type: 'UPDATE_INPUT_VALUE',
+ *   payload: {
+ *     nodeId: 'node1',
+ *     inputId: 'input1',
+ *     value: 'new value',
+ *   },
+ * });
+ * ```
+ */
+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
+ *
+ * This function is essential for type safety when defining 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 UnderlyingType - The underlying type of the data
+ * @template ComplexSchemaType - Zod schema type for complex data types
+ * @param input - The data type definition
+ * @returns The data type definition with proper typing
+ *
+ * @example
+ * ```tsx
+ * // ✅ Type-safe - TypeScript will validate dataType references
+ * const stringType = makeDataTypeWithAutoInfer({
+ *   name: 'String',
+ *   underlyingType: 'string',
+ *   color: '#4A90E2',
+ * });
+ *
+ * // ❌ Without auto-infer - TypeScript can't validate references
+ * const stringType = {
+ *   name: 'String',
+ *   underlyingType: 'string',
+ *   color: '#4A90E2',
+ * };
+ * ```
+ */
+export declare function makeDataTypeWithAutoInfer<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(input: DataType<UnderlyingType, ComplexSchemaType>): DataType<UnderlyingType, ComplexSchemaType>;
+
+/**
+ * Helper function to create a node ID to node type mapping with automatic type inference
+ *
+ * This function is essential for type safety when mapping node IDs to their types.
+ * It ensures that TypeScript can validate that all node type references are valid,
+ * preventing runtime errors when dispatching actions and providing better IDE support.
+ *
+ * @template NodeTypeUniqueId - Unique identifier type for node types
+ * @param input - The node ID to node type mapping
+ * @returns The mapping with proper typing
+ *
+ * @example
+ * ```tsx
+ * // ✅ Type-safe - TypeScript will validate node type references
+ * const nodeIdToNodeType = makeNodeIdToNodeTypeWithAutoInfer({
+ *   'node-1': 'inputNode',
+ *   'node-2': 'outputNode',
+ * });
+ *
+ * // ❌ Without auto-infer - TypeScript can't validate node type references
+ * const nodeIdToNodeType = {
+ *   'node-1': 'inputNode',
+ *   'node-2': 'outputNode',
+ * };
+ * ```
+ */
+export declare function makeNodeIdToNodeTypeWithAutoInfer<NodeTypeUniqueId extends string = string>(input: NodeIdToNodeType<NodeTypeUniqueId>): NodeIdToNodeType<NodeTypeUniqueId>;
+
+/**
+ * Helper function to create a state with automatic type inference
+ *
+ * This function is essential for complete type safety when creating the graph state.
+ * It ensures that TypeScript can properly infer and validate all type relationships
+ * throughout your graph system, providing compile-time type checking and better IDE support.
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ * @template NodeTypeUniqueId - Unique identifier type for node types
+ * @template UnderlyingType - Supported underlying data types ('string' | 'number' | 'complex')
+ * @template ComplexSchemaType - Zod schema type for complex data types
+ * @param input - The state definition
+ * @returns The state with proper typing
+ *
+ * @example
+ * ```tsx
+ * // ✅ Type-safe - Complete type inference and validation
+ * const state = makeStateWithAutoInfer({
+ *   dataTypes: {
+ *     stringType: makeDataTypeWithAutoInfer({
+ *       name: 'String',
+ *       underlyingType: 'string',
+ *       color: '#4A90E2'
+ *     })
+ *   },
+ *   typeOfNodes: {
+ *     inputNode: makeTypeOfNodeWithAutoInfer({
+ *       name: 'Input',
+ *       inputs: [],
+ *       outputs: []
+ *     })
+ *   },
+ *   nodeIdToNodeType: makeNodeIdToNodeTypeWithAutoInfer({}),
+ *   nodes: [],
+ *   edges: [],
+ * });
+ *
+ * // ❌ Without auto-infer - No type validation
+ * const state = {
+ *   dataTypes: { stringType: { name: 'String', underlyingType: 'string', color: '#4A90E2' } },
+ *   typeOfNodes: { inputNode: { name: 'Input', inputs: [], outputs: [] } },
+ *   nodes: [],
+ *   nodeIdToNodeType: {},
+ *   edges: [],
+ * };
+ * ```
+ */
+export declare function makeStateWithAutoInfer<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(input: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>): State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>;
+
+/**
+ * Helper function to create a node type with automatic type inference
+ *
+ * This function is essential for type safety when defining node types. It ensures
+ * that TypeScript can properly validate dataType references in inputs and outputs,
+ * preventing runtime errors when creating nodes and providing better IDE support.
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ * @param input - The node type definition
+ * @returns The node type definition with proper typing
+ *
+ * @example
+ * ```tsx
+ * // ✅ Type-safe - TypeScript will validate dataType references
+ * const inputNodeType = makeTypeOfNodeWithAutoInfer({
+ *   name: 'Input Node',
+ *   headerColor: '#C44536',
+ *   inputs: [{ name: 'Input', dataType: 'stringType', allowInput: true }],
+ *   outputs: [{ name: 'Output', dataType: 'stringType' }],
+ * });
+ *
+ * // ❌ Without auto-infer - TypeScript can't validate dataType references
+ * const inputNodeType = {
+ *   name: 'Input Node',
+ *   headerColor: '#C44536',
+ *   inputs: [{ name: 'Input', dataType: 'stringType', allowInput: true }],
+ *   outputs: [{ name: 'Output', dataType: 'stringType' }],
+ * };
+ * ```
+ */
+export declare function makeTypeOfNodeWithAutoInfer<DataTypeUniqueId extends string = string>(input: TypeOfNode<DataTypeUniqueId>): TypeOfNode<DataTypeUniqueId>;
+
 /**
  * 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
  *
  * @template NodeTypeUniqueId - Unique identifier type for node types
  */
-declare type NodeIdToNodeType<NodeTypeUniqueId extends string = string> = Record<string, NodeTypeUniqueId>;
+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
@@ -1106,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
@@ -1128,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
@@ -1215,35 +1774,52 @@ export declare type SliderNumberInputProps = {
  * @template UnderlyingType - Supported underlying data types ('string' | 'number' | 'complex')
  * @template ComplexSchemaType - Zod schema type for complex data types
  */
-declare type State<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never> = {
+export declare type State<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never> = {
     /** Map of data type definitions */
     dataTypes: Record<DataTypeUniqueId, DataType<UnderlyingType, ComplexSchemaType>>;
     /** 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;
 };
 
 /**
  * Union type of all supported underlying data types
  */
-declare type SupportedUnderlyingTypes = (typeof supportedUnderlyingTypes)[number];
+export declare type SupportedUnderlyingTypes = (typeof supportedUnderlyingTypes)[number];
 
 /**
  * Array of supported underlying data types
  */
 declare const supportedUnderlyingTypes: readonly ["string", "number", "complex", "noEquivalent", "inferFromConnection"];
 
+/**
+ * Map of supported underlying types for type checking
+ */
+export declare const supportedUnderlyingTypesMap: {
+    readonly string: "string";
+    readonly number: "number";
+    readonly complex: "complex";
+    readonly noEquivalent: "noEquivalent";
+    readonly inferFromConnection: "inferFromConnection";
+};
+
 /**
  * Definition of an input type in a node
  *
  * @template DataTypeUniqueId - Unique identifier type for data types
  */
-declare type TypeOfInput<DataTypeUniqueId extends string = string> = {
+export declare type TypeOfInput<DataTypeUniqueId extends string = string> = {
     /** Display name of the input */
     name: string;
     /** The data type identifier this input uses */
@@ -1257,7 +1833,7 @@ declare type TypeOfInput<DataTypeUniqueId extends string = string> = {
  *
  * @template DataTypeUniqueId - Unique identifier type for data types
  */
-declare type TypeOfInputPanel<DataTypeUniqueId extends string = string> = {
+export declare type TypeOfInputPanel<DataTypeUniqueId extends string = string> = {
     /** Display name of the input panel */
     name: string;
     /** Array of inputs within this panel */
@@ -1269,7 +1845,7 @@ declare type TypeOfInputPanel<DataTypeUniqueId extends string = string> = {
  *
  * @template DataTypeUniqueId - Unique identifier type for data types
  */
-declare type TypeOfNode<DataTypeUniqueId extends string = string> = {
+export declare type TypeOfNode<DataTypeUniqueId extends string = string> = {
     /** Display name of the node type */
     name: string;
     /** Color used for the node header */