@theclearsky/react-blender-nodes 0.0.4 → 0.0.5

package/README.md

@@ -21,7 +21,10 @@ a flexible and customizable node-based graph editor for web applications.
 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.
+nodes, connections, and real-time manipulation. Features an intelligent type
+system with automatic inference, complex data validation, and comprehensive
+connection validation to ensure your node graphs are always type-safe and
+error-free.
 
 ## Quick Start
 
@@ -164,19 +167,92 @@ const dataTypes = {
 - 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
+### 🧠 Smart Type System & Validation + Advanced Features
+
+![Smart Type System And Advanced Features](./docs/screenshots/smart-type-system-and-advanced-features.mp4)
+
+- **Intelligent Type Inference**: Automatically infer node types from
+  connections
+  - Dynamic type resolution as you build your graph
+  - Real-time type updates when connections change
+  - Support for `inferFromConnection` data types
+- **Advanced Type Validation**: Comprehensive type checking system
+  - **Complex Type Checking**: Zod schema validation for complex data structures
+  - **Type Conversion Control**: Fine-grained control over allowed type
+    conversions
+  - **Cycle Detection**: Prevent infinite loops in your node graphs
+- **Multiple Data Types**: Support for diverse data structures
+  - Basic types: `string`, `number`
+  - Complex types: Custom objects with Zod schemas
+  - Special types: `inferFromConnection`, `noEquivalent`
+- **Runtime Safety**: Catch type errors before they break your application
+  - Connection validation with detailed error messages
+  - Automatic type propagation across connected nodes
+  - Schema compatibility checking for complex types
 - **State Management**: Integrated reducer for managing graph state
 - **TypeScript Support**: Full type safety with comprehensive definitions
 
 ## Usage Examples
 
+### Smart Type System with Validation
+
+```tsx
+import { z } from 'zod';
+
+// Define complex data types with Zod schemas
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+const dataTypes = {
+  stringType: makeDataTypeWithAutoInfer({
+    name: 'String',
+    underlyingType: 'string',
+    color: '#4A90E2',
+  }),
+  userType: makeDataTypeWithAutoInfer({
+    name: 'User',
+    underlyingType: 'complex',
+    complexSchema: userSchema,
+    color: '#7ED321',
+  }),
+  inferredType: makeDataTypeWithAutoInfer({
+    name: 'Inferred',
+    underlyingType: 'inferFromConnection',
+    color: '#FF6B6B',
+  }),
+};
+
+// Enable advanced validation features
+const initialState = makeStateWithAutoInfer({
+  dataTypes,
+  typeOfNodes: {
+    userInput: makeTypeOfNodeWithAutoInfer({
+      name: 'User Input',
+      inputs: [{ name: 'User Data', dataType: 'userType' }],
+      outputs: [{ name: 'Output', dataType: 'inferredType' }],
+    }),
+    stringProcessor: makeTypeOfNodeWithAutoInfer({
+      name: 'String Processor',
+      inputs: [{ name: 'Input', dataType: 'inferredType' }],
+      outputs: [{ name: 'Result', dataType: 'stringType' }],
+    }),
+  },
+  nodeIdToNodeType: makeNodeIdToNodeTypeWithAutoInfer({}),
+  nodes: [],
+  edges: [],
+  // Enable smart validation features
+  enableTypeInference: true,
+  enableComplexTypeChecking: true,
+  enableCycleChecking: true,
+  allowedConversionsBetweenDataTypes: {
+    userType: { stringType: true }, // Allow user to string conversion
+  },
+});
+```
+
 ### Custom Node with Panels
 
 ```tsx

package/dist/index.d.ts

@@ -1146,6 +1146,11 @@ export declare type FullGraphProps<DataTypeUniqueId extends string = string, Nod
     ]>;
 };
 
+export declare function getResultantDataTypeOfHandleConsideringInferredType<DataTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(handle: ConfigurableNodeInput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId> | ConfigurableNodeOutput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId> | undefined): {
+    dataTypeObject: DataType<UnderlyingType, ComplexSchemaType>;
+    dataTypeUniqueId: DataTypeUniqueId;
+} | undefined;
+
 declare type HandleIndices = {
     type: 'input';
     index1: number;
@@ -1785,12 +1790,54 @@ export declare type State<DataTypeUniqueId extends string = string, NodeTypeUniq
     nodeIdToNodeType: NodeIdToNodeType<NodeTypeUniqueId>;
     /** Array of edges in the graph */
     edges: Edges;
-    /** Optional mapping of allowed conversions between data types */
+    /**
+     * Optional mapping of allowed conversions between data types
+     * - When not provided, all conversions are allowed
+     * - If provided, only the conversions that are explicitly allowed will be allowed (happens even with empty object)
+     * - By default, it will not allow conversion between complex types unless explicitly allowed here (even if complex type checking is enabled)
+     * - If you want to allow conversion between complex types unless disallowed by complex type checking, you can set `allowConversionBetweenComplexTypesUnlessDisallowedByComplexTypeChecking` to true
+     *
+     * @default undefined
+     */
     allowedConversionsBetweenDataTypes?: AllowedConversionsBetweenDataTypes<DataTypeUniqueId>;
-    /** Whether to enable type inference */
+    /**
+     * Whether to allow conversion between complex types unless disallowed by complex type checking
+     * - If not provided, is considered disabled
+     * - Only takes effect if complex type checking is enabled (`allowedConversionsBetweenDataTypes` is provided)
+     * - If enabled, it will allow conversion between complex types unless disallowed by complex type checking
+     * - If disabled, it will not allow conversion between complex types unless explicitly allowed by `allowedConversionsBetweenDataTypes`, even if complex type checking is enabled
+     *
+     * @default undefined
+     */
+    allowConversionBetweenComplexTypesUnlessDisallowedByComplexTypeChecking?: boolean;
+    /**
+     * Whether to enable type inference
+     * - If not provided, is considered disabled
+     * - When disabled, the types of the nodes are not inferred from the connections
+     * - When enabled, the types of the nodes are inferred from the connections and reset when edges are removed
+     *
+     * @default undefined
+     */
     enableTypeInference?: boolean;
-    /** Whether to enable complex type checking */
+    /**
+     * Whether to enable complex type checking
+     * - If not provided, is considered disabled
+     * - When disabled, the complex types are not checked for compatibility, all connections are allowed
+     * - When enabled, the complex types are checked for compatibility, and connections are not allowed if the complex types are not compatible
+     * - Complex types are compatible if they are the same type or if they have exactly the same schema
+     *
+     * @default undefined
+     */
     enableComplexTypeChecking?: boolean;
+    /**
+     * Whether to enable cycle checking
+     * - If not provided, is considered disabled
+     * - When disabled, the cycles are not checked, all connections are allowed
+     * - When enabled, the cycles are checked, and connections are not allowed if they create a cycle
+     *
+     * @default undefined
+     */
+    enableCycleChecking?: boolean;
 };
 
 /**
@@ -2034,4 +2081,17 @@ export declare function useFullGraph<DataTypeUniqueId extends string = string, N
     dispatch: ActionDispatch<[action: Action<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>]>;
 };
 
+/**
+ * Checks if adding an edge will create a cycle in the graph
+ *
+ * @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 state - The current graph state
+ * @param newEdge - The edge to check
+ * @returns Whether the edge will create a cycle
+ */
+export declare function willAddingEdgeCreateCycle<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(state: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>, sourceNodeId: string, targetNodeId: string): boolean;
+
 export { }