@theclearsky/react-blender-nodes 0.0.2 → 0.0.3

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: {
@@ -79,7 +79,7 @@ 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 UPDATE_NODE_BY_REACT_FLOW: "UPDATE_NODE_BY_REACT_FLOW";
     readonly UPDATE_EDGES_BY_REACT_FLOW: "UPDATE_EDGES_BY_REACT_FLOW";
@@ -227,7 +227,7 @@ export declare function cn(...inputs: ClassValue[]): string;
  * />
  * ```
  */
-export declare const ConfigurableEdge: ForwardRefExoticComponent<Pick<ConfigurableEdgeState, "data" | "source" | "style" | "id" | "target" | "selectable" | "deletable" | "selected" | "animated"> & EdgePosition & EdgeLabelOptions & {
+export declare const ConfigurableEdge: ForwardRefExoticComponent<Pick<ConfigurableEdgeState, "data" | "source" | "style" | "id" | "selectable" | "deletable" | "selected" | "target" | "animated"> & EdgePosition & EdgeLabelOptions & {
 sourceHandleId?: string | null;
 targetHandleId?: string | null;
 markerStart?: string;
@@ -476,6 +476,157 @@ export declare type ConfigurableNodeReactFlowWrapperProps = NodeProps<Configurab
 /** State type for configurable nodes in ReactFlow */
 export declare type ConfigurableNodeState = Node_2<Omit<ConfigurableNodeProps, 'isCurrentlyInsideReactFlow'>, 'configurableNode'>;
 
+/**
+ * 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>(typeOfDataType: TypeOfInput<DataTypeUniqueId> | TypeOfNode<DataTypeUniqueId>['outputs'][number], dataTypes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['dataTypes']): ConfigurableNodeInput | ConfigurableNodeOutput;
+
+/**
+ * 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>(typeOfPanel: {
+    name: string;
+    inputs: {
+        name: string;
+        dataType: DataTypeUniqueId;
+    }[];
+}, dataTypes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['dataTypes']): ConfigurableNodeInputPanel;
+
+/**
+ * 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>(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];
+
 /**
  * A context-aware handle component for node inputs and outputs
  *
@@ -759,7 +910,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 */
@@ -1026,6 +1177,238 @@ 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;
+
+/**
+ * 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 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
  */
@@ -1036,7 +1419,7 @@ export declare type NodeChanges = NodeChange<ConfigurableNodeState>[];
  *
  * @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>;
 
 /**
  * Enhanced node resizer component with customizable controls
@@ -1215,7 +1598,7 @@ 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 */
@@ -1231,19 +1614,30 @@ declare type State<DataTypeUniqueId extends string = string, NodeTypeUniqueId ex
 /**
  * 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 +1651,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 +1663,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 */