@theclearsky/react-blender-nodes 0.0.3 → 0.0.5

package/README.md

@@ -5,53 +5,28 @@ 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
+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.
 
-![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 +97,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 +139,119 @@ 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
+
+### 🧠 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