@theclearsky/react-blender-nodes 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -27,36 +27,58 @@ import { VariantProps } from 'class-variance-authority';
 import { XYPosition } from '@xyflow/react';
 import { z } from 'zod';
 
+/**
+ * Union type of all possible actions for the graph state reducer
+ *
+ * @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
+ */
 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: {
+        /** 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;
     };
 } | {
+    /** Update edges based on ReactFlow changes */
     type: typeof actionTypesMap.UPDATE_EDGES_BY_REACT_FLOW;
     payload: {
+        /** Array of edge changes from ReactFlow */
         changes: EdgeChanges;
     };
 } | {
+    /** Add a new edge to the graph */
     type: typeof actionTypesMap.ADD_EDGE_BY_REACT_FLOW;
     payload: {
+        /** Connection object from ReactFlow */
         edge: Connection;
     };
 } | {
+    /** Update the value of a node input */
     type: typeof actionTypesMap.UPDATE_INPUT_VALUE;
     payload: {
+        /** ID of the node containing the input */
         nodeId: string;
+        /** ID of the input to update */
         inputId: string;
+        /** New value for the input */
         value: string | number;
     };
 };
 
+/** Map of action types for type-safe action dispatching */
 declare const actionTypesMap: {
     readonly ADD_NODE: "ADD_NODE";
     readonly UPDATE_NODE_BY_REACT_FLOW: "UPDATE_NODE_BY_REACT_FLOW";
@@ -65,16 +87,69 @@ declare const actionTypesMap: {
     readonly UPDATE_INPUT_VALUE: "UPDATE_INPUT_VALUE";
 };
 
+/**
+ * Represents a rectangular bounding box
+ */
 export declare type Box = {
+    /** Top edge position */
     top: number;
+    /** Left edge position */
     left: number;
+    /** Right edge position */
     right: number;
+    /** Bottom edge position */
     bottom: number;
 };
 
+/**
+ * A customizable button component with Blender-inspired styling
+ *
+ * This button component provides multiple color variants and hover states
+ * that match the Blender node editor aesthetic. It supports composition
+ * through the asChild prop and includes proper accessibility features.
+ *
+ * Features:
+ * - Multiple color variants (dark, lightNonPriority, lightPriority)
+ * - Configurable hover styles
+ * - Composition support with Radix Slot
+ * - Full TypeScript support
+ * - Accessibility features
+ *
+ * @param props - The component props
+ * @param ref - Forwarded ref to the button element
+ * @returns JSX element containing the button
+ *
+ * @example
+ * ```tsx
+ * // Basic button
+ * <Button onClick={handleClick}>Click me</Button>
+ *
+ * // Button with custom color
+ * <Button color="lightPriority" onClick={handleSubmit}>
+ *   Submit
+ * </Button>
+ *
+ * // Button as child component
+ * <Button asChild>
+ *   <Link to="/dashboard">Go to Dashboard</Link>
+ * </Button>
+ *
+ * // Button without hover styles
+ * <Button applyHoverStyles={false} disabled>
+ *   Disabled Button
+ * </Button>
+ * ```
+ */
 export declare const Button: ForwardRefExoticComponent<Omit<ButtonProps, "ref"> & RefAttributes<HTMLButtonElement>>;
 
+/**
+ * Props for the Button component
+ *
+ * Extends the standard button element props with custom styling variants
+ * and composition capabilities.
+ */
 export declare type ButtonProps = ComponentProps<'button'> & VariantProps<typeof buttonVariants> & {
+    /** Whether to render as a child component using Radix Slot */
     asChild?: boolean;
 };
 
@@ -83,8 +158,75 @@ declare const buttonVariants: (props?: ({
     applyHoverStyles?: boolean | null | undefined;
 } & ClassProp) | undefined) => string;
 
+/**
+ * Utility function for combining and merging CSS classes
+ *
+ * This function combines clsx for conditional class handling with tailwind-merge
+ * for intelligent Tailwind CSS class merging. It resolves conflicts between
+ * Tailwind classes and ensures only the last conflicting class is applied.
+ *
+ * @param inputs - Variable number of class values (strings, objects, arrays, etc.)
+ * @returns Merged and deduplicated class string
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * cn('px-4 py-2', 'bg-blue-500', 'text-white')
+ * // Returns: "px-4 py-2 bg-blue-500 text-white"
+ *
+ * // Conditional classes
+ * cn('base-class', isActive && 'active-class', isDisabled && 'disabled-class')
+ *
+ * // Tailwind class merging (conflicts resolved)
+ * cn('px-4 px-6', 'py-2 py-4')
+ * // Returns: "px-6 py-4" (last conflicting classes win)
+ *
+ * // With objects
+ * cn({
+ *   'bg-blue-500': isPrimary,
+ *   'bg-gray-500': !isPrimary,
+ *   'text-white': true,
+ * })
+ * ```
+ */
 export declare function cn(...inputs: ClassValue[]): string;
 
+/**
+ * A configurable edge component with gradient colors and viewport optimization
+ *
+ * This component renders edges between nodes with automatic color gradients
+ * based on the source and target handle colors. It includes viewport optimization
+ * to reduce rendering overhead for edges outside the visible area.
+ *
+ * Features:
+ * - Automatic gradient colors based on handle colors
+ * - Viewport optimization for performance
+ * - Bezier curve rendering
+ * - ReactFlow integration
+ * - Custom styling and animations
+ *
+ * @param props - The component props
+ * @param _ - Unused ref parameter
+ * @returns JSX element containing the configurable edge
+ *
+ * @example
+ * ```tsx
+ * // Edge with automatic gradient colors
+ * <ConfigurableEdge
+ *   id="edge1"
+ *   sourceX={100}
+ *   sourceY={50}
+ *   targetX={200}
+ *   targetY={50}
+ *   sourcePosition={Position.Right}
+ *   targetPosition={Position.Left}
+ *   source="node1"
+ *   target="node2"
+ *   sourceHandleId="output1"
+ *   targetHandleId="input1"
+ * />
+ * ```
+ */
 export declare const ConfigurableEdge: ForwardRefExoticComponent<Pick<ConfigurableEdgeState, "data" | "source" | "style" | "id" | "target" | "selectable" | "deletable" | "selected" | "animated"> & EdgePosition & EdgeLabelOptions & {
 sourceHandleId?: string | null;
 targetHandleId?: string | null;
@@ -94,111 +236,478 @@ pathOptions?: any;
 interactionWidth?: number;
 } & RefAttributes<HTMLDivElement>>;
 
+/** Props for the ConfigurableEdge component */
 export declare type ConfigurableEdgeProps = EdgeProps<ConfigurableEdgeState>;
 
+/** State type for configurable edges */
 export declare type ConfigurableEdgeState = Edge<{}, 'configurableEdge'>;
 
+/**
+ * A customizable node component inspired by Blender's node editor
+ *
+ * This component creates a node with configurable inputs, outputs, and collapsible panels.
+ * It supports both standalone usage and ReactFlow integration with automatic handle
+ * management and interactive input components.
+ *
+ * Features:
+ * - Customizable header with color and name
+ * - Dynamic inputs and outputs with custom handle shapes
+ * - Collapsible input panels for organization
+ * - Interactive input components (text/number) when not connected
+ * - ReactFlow integration with automatic handle positioning
+ * - Node resizing controls when inside ReactFlow
+ *
+ * @param props - The component props
+ * @param ref - Forwarded ref to the root div element
+ * @returns JSX element containing the configurable node
+ *
+ * @example
+ * ```tsx
+ * // Basic node with inputs and outputs
+ * <ConfigurableNode
+ *   name="Data Processor"
+ *   headerColor="#C44536"
+ *   inputs={[
+ *     {
+ *       id: 'input1',
+ *       name: 'Text Input',
+ *       type: 'string',
+ *       handleColor: '#00BFFF',
+ *       handleShape: 'circle',
+ *       allowInput: true,
+ *     },
+ *   ]}
+ *   outputs={[
+ *     {
+ *       id: 'output1',
+ *       name: 'Result',
+ *       type: 'string',
+ *       handleColor: '#FECA57',
+ *       handleShape: 'square',
+ *     },
+ *   ]}
+ * />
+ *
+ * // Node with collapsible panels
+ * <ConfigurableNode
+ *   name="Advanced Node"
+ *   headerColor="#2D5A87"
+ *   inputs={[
+ *     {
+ *       id: 'direct-input',
+ *       name: 'Direct Input',
+ *       type: 'string',
+ *       allowInput: true,
+ *     },
+ *     {
+ *       id: 'settings-panel',
+ *       name: 'Settings Panel',
+ *       inputs: [
+ *         {
+ *           id: 'threshold',
+ *           name: 'Threshold',
+ *           type: 'number',
+ *           handleShape: 'diamond',
+ *           allowInput: true,
+ *         },
+ *       ],
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
 export declare const ConfigurableNode: ForwardRefExoticComponent<    {
+/** Display name of the node */
 name?: string;
+/** Background color of the node header */
 headerColor?: string;
+/** Array of inputs and input panels */
 inputs?: (ConfigurableNodeInput | ConfigurableNodeInputPanel)[];
+/** Array of output sockets */
 outputs?: ConfigurableNodeOutput[];
+/** Whether the node is currently inside a ReactFlow context */
 isCurrentlyInsideReactFlow?: boolean;
+/** Props for the node resizer component */
 nodeResizerProps?: NodeResizerWithMoreControlsProps;
 } & HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>>;
 
+/**
+ * Configuration for a node input
+ *
+ * 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 = {
+    /** Unique identifier for the input */
     id: string;
+    /** Display name for the input */
     name: string;
+    /** Color of the input handle/socket */
     handleColor?: string;
+    /** Shape of the input handle (circle, square, diamond, etc.) */
     handleShape?: HandleShape;
+    /** Whether to show an interactive input component when not connected */
     allowInput?: boolean;
 } & ({
+    /** String input type */
     type: 'string';
+    /** Current value of the input */
     value?: string;
+    /** Callback when the input value changes */
     onChange?: (value: string) => void;
 } | {
+    /** Number input type */
     type: 'number';
+    /** Current value of the input */
     value?: number;
+    /** Callback when the input value changes */
     onChange?: (value: number) => void;
 });
 
+/**
+ * Configuration for a collapsible input panel
+ *
+ * Groups multiple inputs together in a collapsible panel for better organization.
+ */
 export declare type ConfigurableNodeInputPanel = {
+    /** Unique identifier for the panel */
     id: string;
+    /** Display name for the panel */
     name: string;
+    /** Array of inputs contained in this panel */
     inputs: ConfigurableNodeInput[];
 };
 
+/**
+ * Configuration for a node output
+ *
+ * Defines an output socket on a node that can be connected to inputs.
+ */
 export declare type ConfigurableNodeOutput = {
+    /** Unique identifier for the output */
     id: string;
+    /** Display name for the output */
     name: string;
+    /** Color of the output handle/socket */
     handleColor?: string;
+    /** Shape of the output handle (circle, square, diamond, etc.) */
     handleShape?: HandleShape;
 } & ({
+    /** String output type */
     type: 'string';
 } | {
+    /** Number output type */
     type: 'number';
 });
 
+/**
+ * Props for the ConfigurableNode component
+ *
+ * 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 = {
+    /** Display name of the node */
     name?: string;
+    /** Background color of the node header */
     headerColor?: string;
+    /** Array of inputs and input panels */
     inputs?: (ConfigurableNodeInput | ConfigurableNodeInputPanel)[];
+    /** Array of output sockets */
     outputs?: ConfigurableNodeOutput[];
+    /** Whether the node is currently inside a ReactFlow context */
     isCurrentlyInsideReactFlow?: boolean;
+    /** Props for the node resizer component */
     nodeResizerProps?: NodeResizerWithMoreControlsProps;
 } & HTMLAttributes<HTMLDivElement>;
 
+/**
+ * ReactFlow wrapper for the ConfigurableNode component
+ *
+ * This component wraps the ConfigurableNode for use within ReactFlow.
+ * It automatically sets the isCurrentlyInsideReactFlow prop to true and
+ * applies ReactFlow-specific styling and behavior.
+ *
+ * Features:
+ * - Automatic ReactFlow integration
+ * - Full-width styling for ReactFlow context
+ * - Proper handle and interaction setup
+ * - Node resizing controls
+ * - Connection management
+ *
+ * @param props - The component props
+ * @param ref - Forwarded ref to the node element
+ * @returns JSX element containing the wrapped configurable node
+ *
+ * @example
+ * ```tsx
+ * // Used as a node type in ReactFlow
+ * const nodeTypes = {
+ *   configurableNode: ConfigurableNodeReactFlowWrapper,
+ * };
+ *
+ * <ReactFlow
+ *   nodeTypes={nodeTypes}
+ *   nodes={[
+ *     {
+ *       id: 'node1',
+ *       type: 'configurableNode',
+ *       position: { x: 100, y: 100 },
+ *       data: {
+ *         name: 'My Node',
+ *         headerColor: '#C44536',
+ *         inputs: [{ id: 'input1', name: 'Input', type: 'string' }],
+ *         outputs: [{ id: 'output1', name: 'Output', type: 'string' }],
+ *       },
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
 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>>;
 
+/** Props for the ConfigurableNodeReactFlowWrapper component */
 export declare type ConfigurableNodeReactFlowWrapperProps = NodeProps<ConfigurableNodeState>;
 
+/** State type for configurable nodes in ReactFlow */
 export declare type ConfigurableNodeState = Node_2<Omit<ConfigurableNodeProps, 'isCurrentlyInsideReactFlow'>, 'configurableNode'>;
 
+/**
+ * A context-aware handle component for node inputs and outputs
+ *
+ * This component renders handles (connection points) for nodes with support for
+ * various shapes and automatic ReactFlow integration. It can render as either
+ * a ReactFlow Handle when inside a ReactFlow context or as a standalone element
+ * for preview purposes.
+ *
+ * Features:
+ * - 13+ custom handle shapes (circle, square, diamond, star, etc.)
+ * - Automatic ReactFlow integration
+ * - Custom colors and styling
+ * - Border support for clip-path shapes
+ * - Type-safe shape definitions
+ *
+ * @param props - The component props
+ * @param ref - Forwarded ref to the handle element
+ * @returns JSX element containing the handle
+ *
+ * @example
+ * ```tsx
+ * // Basic handle
+ * <ContextAwareHandle
+ *   type="target"
+ *   position={Position.Left}
+ *   id="input1"
+ *   color="#00BFFF"
+ *   shape="circle"
+ *   isCurrentlyInsideReactFlow={true}
+ * />
+ *
+ * // Custom shape handle
+ * <ContextAwareHandle
+ *   type="source"
+ *   position={Position.Right}
+ *   id="output1"
+ *   color="#FECA57"
+ *   shape="diamond"
+ *   isCurrentlyInsideReactFlow={true}
+ * />
+ *
+ * // Preview handle (outside ReactFlow)
+ * <ContextAwareHandle
+ *   type="target"
+ *   position={Position.Left}
+ *   id="preview-input"
+ *   color="#96CEB4"
+ *   shape="star"
+ *   isCurrentlyInsideReactFlow={false}
+ * />
+ * ```
+ */
 export declare const ContextAwareHandle: ForwardRefExoticComponent<    {
+/** Type of handle (source or target) */
 type: HandleType;
+/** Position of the handle on the node */
 position: Position;
+/** Unique identifier for the handle */
 id: string;
+/** Color of the handle */
 color?: string;
+/** Shape of the handle */
 shape?: HandleShape;
+/** Whether the handle is currently inside a ReactFlow context */
 isCurrentlyInsideReactFlow?: boolean;
 } & HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>>;
 
+/**
+ * Props for the ContextAwareHandle component
+ */
 export declare type ContextAwareHandleProps = {
+    /** Type of handle (source or target) */
     type: HandleType;
+    /** Position of the handle on the node */
     position: Position;
+    /** Unique identifier for the handle */
     id: string;
+    /** Color of the handle */
     color?: string;
+    /** Shape of the handle */
     shape?: HandleShape;
+    /** Whether the handle is currently inside a ReactFlow context */
     isCurrentlyInsideReactFlow?: boolean;
 } & HTMLAttributes<HTMLDivElement>;
 
+/**
+ * Context-aware input component that handles both connected and unconnected inputs
+ *
+ * This component intelligently renders either a label (for connected inputs) or an
+ * input component (for unconnected inputs) based on the connection state. It uses
+ * the ReactFlow context to determine if an input is connected to other nodes.
+ *
+ * Features:
+ * - Automatically detects input connection state
+ * - Renders appropriate UI based on connection status
+ * - Integrates with ReactFlow's connection system
+ * - Supports both string and number input types
+ *
+ * @param props - The component props
+ * @returns JSX element containing either a label or input component
+ *
+ * @example
+ * ```tsx
+ * <ContextAwareInput
+ *   input={{
+ *     id: 'input1',
+ *     name: 'Value',
+ *     type: 'string',
+ *     dataType: 'stringType',
+ *     allowInput: true,
+ *     value: 'Hello World',
+ *   }}
+ *   isCurrentlyInsideReactFlow={true}
+ * />
+ * ```
+ */
 export declare const ContextAwareInput: ({ input, isCurrentlyInsideReactFlow, }: ContextAwareInputProps) => JSX.Element;
 
+/**
+ * Props for the ContextAwareInput component
+ */
 export declare type ContextAwareInputProps = {
+    /** The input configuration */
     input: ConfigurableNodeInput;
+    /** Whether the component is currently inside a ReactFlow context */
     isCurrentlyInsideReactFlow: boolean;
 };
 
+/**
+ * A context menu component with nested submenu support
+ *
+ * This component provides a hierarchical context menu system with support for
+ * nested submenus, icons, keyboard shortcuts, and separators. It features
+ * hover-based submenu activation and Blender-inspired dark theme styling.
+ *
+ * Features:
+ * - Nested submenu support with unlimited depth
+ * - Icon and keyboard shortcut display
+ * - Separator lines for visual grouping
+ * - Hover-based submenu activation
+ * - Dark theme styling matching Blender's aesthetic
+ * - TypeScript support with full type safety
+ *
+ * @param props - The component props
+ * @returns JSX element containing the context menu
+ *
+ * @example
+ * ```tsx
+ * // Basic context menu
+ * <ContextMenu
+ *   subItems={[
+ *     {
+ *       id: 'copy',
+ *       label: 'Copy',
+ *       icon: <CopyIcon className="w-4 h-4" />,
+ *       shortcut: 'Ctrl+C',
+ *       onClick: () => handleCopy(),
+ *     },
+ *     {
+ *       id: 'paste',
+ *       label: 'Paste',
+ *       icon: <PasteIcon className="w-4 h-4" />,
+ *       shortcut: 'Ctrl+V',
+ *       onClick: () => handlePaste(),
+ *       separator: true,
+ *     },
+ *   ]}
+ * />
+ *
+ * // Nested submenu
+ * <ContextMenu
+ *   subItems={[
+ *     {
+ *       id: 'edit',
+ *       label: 'Edit',
+ *       icon: <EditIcon className="w-4 h-4" />,
+ *       subItems: [
+ *         {
+ *           id: 'cut',
+ *           label: 'Cut',
+ *           onClick: () => handleCut(),
+ *         },
+ *         {
+ *           id: 'copy',
+ *           label: 'Copy',
+ *           onClick: () => handleCopy(),
+ *         },
+ *         {
+ *           id: 'paste',
+ *           label: 'Paste',
+ *           onClick: () => handlePaste(),
+ *         },
+ *       ],
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
 export declare const ContextMenu: ({ subItems, className, onItemClick, }: ContextMenuProps) => JSX.Element;
 
+/**
+ * Configuration for a context menu item
+ *
+ * Defines a single item in the context menu with optional submenu, icon, and actions.
+ * Supports nested submenus for hierarchical menu structures.
+ */
 export declare type ContextMenuItem = {
+    /** Unique identifier for the menu item */
     id: string;
+    /** Display text for the menu item */
     label: string;
+    /** Optional icon to display next to the label */
     icon?: ReactNode;
+    /** Optional array of submenu items for nested menus */
     subItems?: ContextMenuItem[];
+    /** Callback function when the item is clicked */
     onClick?: () => void;
+    /** Optional keyboard shortcut text to display */
     shortcut?: string;
+    /** Whether to show a separator line before this item */
     separator?: boolean;
 };
 
+/**
+ * Props for the ContextMenu component
+ */
 export declare type ContextMenuProps = {
+    /** Array of menu items to display */
     subItems: ContextMenuItem[];
+    /** Additional CSS classes */
     className?: string;
+    /** Optional callback when any item is clicked */
     onItemClick?: (item: ContextMenuItem) => void;
 };
 
@@ -212,8 +721,13 @@ export declare type ContextMenuProps = {
  */
 export declare function convertStringToNumber(inputNumberAsString: string): number;
 
+/**
+ * Represents a 2D coordinate point
+ */
 export declare type Coordinate = {
+    /** X coordinate */
     x: number;
+    /** Y coordinate */
     y: number;
 };
 
@@ -239,33 +753,159 @@ export declare type CreateNodeContextMenuProps<DataTypeUniqueId extends string =
     contextMenuPosition: XYPosition;
 };
 
+/**
+ * Definition of a data type in the graph system
+ *
+ * @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' ? {
+    /** Display name of the data type */
     name: string;
+    /** The underlying type of the data */
     underlyingType: UnderlyingType;
+    /** Zod schema for complex data validation */
     complexSchema: ComplexSchemaType;
+    /** Color used for visual representation */
     color: string;
 } : {
+    /** Display name of the data type */
     name: string;
+    /** The underlying type of the data */
     underlyingType: UnderlyingType;
+    /** Complex schema is not used for non-complex types */
     complexSchema?: undefined;
+    /** Color used for visual representation */
     color: string;
 };
 
+/**
+ * Array of edge changes for ReactFlow
+ */
 export declare type EdgeChanges = EdgeChange<ConfigurableEdgeState>[];
 
+/**
+ * Array of configurable edges in the graph
+ */
 export declare type Edges = ConfigurableEdgeState[];
 
+/**
+ * Main graph editor component inspired by Blender's node editor
+ *
+ * This is the primary component for creating interactive node-based graph editors.
+ * It provides a complete ReactFlow-based interface with custom nodes, edges, and
+ * context menu functionality for adding new nodes.
+ *
+ * Features:
+ * - Pan, zoom, and select nodes with intuitive controls
+ * - Drag and drop node connections
+ * - Right-click context menu for adding new nodes
+ * - Custom node types with configurable inputs and outputs
+ * - Real-time node manipulation and state 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 props - The component props
+ * @returns JSX element containing the complete graph editor
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   FullGraph,
+ *   useFullGraph,
+ *   makeStateWithAutoInfer,
+ *   makeNodeIdToNodeTypeWithAutoInfer,
+ *   makeTypeOfNodeWithAutoInfer,
+ *   makeDataTypeWithAutoInfer
+ * } from 'react-blender-nodes';
+ *
+ * function MyNodeEditor() {
+ *   // Define data types with auto-infer for type safety
+ *   const dataTypes = {
+ *     stringType: makeDataTypeWithAutoInfer({
+ *       name: 'String',
+ *       underlyingType: 'string',
+ *       color: '#4A90E2',
+ *     }),
+ *     numberType: makeDataTypeWithAutoInfer({
+ *       name: 'Number',
+ *       underlyingType: 'number',
+ *       color: '#E74C3C',
+ *     }),
+ *   };
+ *
+ *   // 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' }
+ *       ],
+ *     }),
+ *     outputNode: makeTypeOfNodeWithAutoInfer({
+ *       name: 'Output Node',
+ *       headerColor: '#2D5A87',
+ *       inputs: [
+ *         { name: 'Input', dataType: 'stringType' }
+ *       ],
+ *       outputs: [],
+ *     }),
+ *   };
+ *
+ *   // Define node ID to type mapping with auto-infer
+ *   const nodeIdToNodeType = makeNodeIdToNodeTypeWithAutoInfer({
+ *     'node-1': 'inputNode',
+ *     'node-2': 'outputNode',
+ *   });
+ *
+ *   // Create state with auto-infer for complete type safety
+ *   const initialState = makeStateWithAutoInfer({
+ *     dataTypes,
+ *     typeOfNodes,
+ *     nodeIdToNodeType,
+ *     nodes: [],
+ *     edges: [],
+ *   });
+ *
+ *   const { state, dispatch } = useFullGraph(initialState);
+ *
+ *   return (
+ *     <div style={{ height: '600px', width: '100%' }}>
+ *       <FullGraph state={state} dispatch={dispatch} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export declare function FullGraph<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>({ state, dispatch, }: FullGraphProps<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>): JSX.Element;
 
+/**
+ * Props for the FullGraph component
+ *
+ * @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
+ */
 export declare type FullGraphProps<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never> = {
+    /** The current state of the graph including nodes, edges, and type definitions */
     state: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>;
+    /** Dispatch function for updating the graph state */
     dispatch: ActionDispatch<[
     action: Action<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>
     ]>;
 };
 
+/** Type representing all available handle shapes */
 export declare type HandleShape = (typeof handleShapesMap)[keyof typeof handleShapesMap];
 
+/** Map of handle shapes for type-safe access */
 export declare const handleShapesMap: {
     readonly circle: "circle";
     readonly square: "square";
@@ -345,51 +985,146 @@ export declare type InputProps = {
     numberOfDecimals?: never;
 });
 
+/**
+ * Checks if a coordinate point is within a bounding box
+ *
+ * @param coordinate - The coordinate point to check
+ * @param box - The bounding box to check against
+ * @param xAxisInclusive - Whether the x-axis boundaries are inclusive (default: false)
+ * @param yAxisInclusive - Whether the y-axis boundaries are inclusive (default: false)
+ * @returns True if the coordinate is within the box, false otherwise
+ *
+ * @example
+ * ```tsx
+ * const point = { x: 50, y: 50 };
+ * const box = { top: 0, left: 0, right: 100, bottom: 100 };
+ *
+ * isCoordinateInBox(point, box) // true
+ * isCoordinateInBox({ x: 0, y: 0 }, box, true, true) // true (inclusive)
+ * isCoordinateInBox({ x: 100, y: 100 }, box) // false (exclusive)
+ * ```
+ */
 export declare function isCoordinateInBox(coordinate: Coordinate, box: Box, xAxisInclusive?: boolean, yAxisInclusive?: boolean): boolean;
 
+/**
+ * Checks if a number is within a specified range
+ *
+ * @param number - The number to check
+ * @param min - The minimum value of the range
+ * @param max - The maximum value of the range
+ * @param minInclusive - Whether the minimum value is inclusive (default: false)
+ * @param maxInclusive - Whether the maximum value is inclusive (default: false)
+ * @returns True if the number is within the range, false otherwise
+ *
+ * @example
+ * ```tsx
+ * isNumberInRange(5, 1, 10) // true (5 is between 1 and 10, exclusive)
+ * isNumberInRange(1, 1, 10, true) // true (1 is included)
+ * isNumberInRange(10, 1, 10, false, true) // true (10 is included)
+ * isNumberInRange(0, 1, 10) // false (0 is below range)
+ * ```
+ */
 export declare function isNumberInRange(number: number, min: number, max: number, minInclusive?: boolean, maxInclusive?: boolean): boolean;
 
+/**
+ * Array of node changes for ReactFlow
+ */
 export declare type NodeChanges = NodeChange<ConfigurableNodeState>[];
 
+/**
+ * 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>;
 
 /**
- * The `<NodeResizer />` component can be used to add a resize functionality to your
- * nodes. It renders draggable controls around the node to resize in all directions.
- * @public
+ * Enhanced node resizer component with customizable controls
+ *
+ * This component extends the standard ReactFlow NodeResizer with additional
+ * customization options for line and handle positions. It provides fine-grained
+ * control over which resize controls are displayed and how they behave.
+ *
+ * Features:
+ * - Customizable line and handle positions
+ * - Direction-specific resize controls
+ * - Min/max width and height constraints
+ * - Aspect ratio preservation
+ * - Auto-scaling support
+ * - Custom styling options
+ *
+ * @param props - The component props
+ * @returns JSX element containing the node resizer controls
  *
  * @example
- *```jsx
- *import { memo } from 'react';
- *import { Handle, Position, NodeResizer } from '@xyflow/react';
- *
- *function ResizableNode({ data }) {
- *  return (
- *    <>
- *      <NodeResizer minWidth={100} minHeight={30} />
- *      <Handle type="target" position={Position.Left} />
- *      <div style={{ padding: 10 }}>{data.label}</div>
- *      <Handle type="source" position={Position.Right} />
- *    </>
- *  );
- *};
- *
- *export default memo(ResizableNode);
- *```
+ * ```tsx
+ * // Basic resizer with default controls
+ * <NodeResizerWithMoreControls
+ *   minWidth={100}
+ *   minHeight={50}
+ *   maxWidth={500}
+ *   maxHeight={300}
+ * />
+ *
+ * // Custom line positions only
+ * <NodeResizerWithMoreControls
+ *   linePosition={['left', 'right']}
+ *   minWidth={100}
+ *   minHeight={50}
+ * />
+ *
+ * // Custom handle positions
+ * <NodeResizerWithMoreControls
+ *   handlePosition={['top-left', 'bottom-right']}
+ *   minWidth={100}
+ *   minHeight={50}
+ * />
+ *
+ * // Horizontal-only resizing
+ * <NodeResizerWithMoreControls
+ *   resizeDirection="horizontal"
+ *   linePosition={['left', 'right']}
+ *   minWidth={100}
+ *   maxWidth={500}
+ * />
+ * ```
  */
 export declare function NodeResizerWithMoreControls({ nodeId, isVisible, handleClassName, handleStyle, lineClassName, lineStyle, color, minWidth, minHeight, maxWidth, maxHeight, keepAspectRatio, autoScale, shouldResize, onResizeStart, onResize, onResizeEnd, linePosition, handlePosition, resizeDirection, }: NodeResizerWithMoreControlsProps): JSX.Element | null;
 
+/**
+ * Props for the NodeResizerWithMoreControls component
+ */
 export declare type NodeResizerWithMoreControlsProps = NodeResizerProps & {
+    /** Array of line positions for resize controls */
     linePosition?: ControlLinePosition[];
+    /** Array of handle positions for resize controls */
     handlePosition?: ControlPosition[];
+    /** Direction of resize operation */
     resizeDirection?: ResizeControlDirection;
 };
 
+/**
+ * Array of configurable nodes in the graph
+ */
 export declare type Nodes = ConfigurableNodeState[];
 
+/**
+ * ReactFlow-aware input component that automatically updates node data
+ *
+ * This component renders the appropriate input component (Input or SliderNumberInput)
+ * and automatically updates the ReactFlow node data when values change. It integrates
+ * with the ReactFlow context to maintain state consistency.
+ *
+ * @param props - The component props
+ * @returns JSX element containing the appropriate input component
+ */
 export declare const ReactFlowAwareInput: ({ input }: ReactFlowAwareInputProps) => JSX.Element;
 
+/**
+ * Props for the ReactFlowAwareInput component
+ */
 export declare type ReactFlowAwareInputProps = {
+    /** The input configuration */
     input: ConfigurableNodeInput;
 };
 
@@ -401,48 +1136,198 @@ export declare type ReactFlowAwareInputProps = {
  */
 export declare function sanitizeNumberToShowAsText(value: number, numberOfDecimals: number): string;
 
+/**
+ * A combined slider and number input component with drag functionality
+ *
+ * This component provides an intuitive way to input and adjust numeric values
+ * through both dragging and direct input. It features a slider interface with
+ * increment/decrement buttons and switches to a text input when clicked.
+ *
+ * Features:
+ * - Drag-to-adjust functionality with visual feedback
+ * - Increment/decrement buttons for precise control
+ * - Click-to-edit mode with text input
+ * - Min/max value constraints
+ * - Customizable step size
+ * - Blender-inspired dark theme styling
+ *
+ * @param props - The component props
+ * @param ref - Forwarded ref to the component
+ * @returns JSX element containing the slider number input
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <SliderNumberInput
+ *   name="Price"
+ *   value={10.5}
+ *   onChange={(value) => setPrice(value)}
+ * />
+ *
+ * // With constraints
+ * <SliderNumberInput
+ *   name="Temperature"
+ *   value={25}
+ *   min={0}
+ *   max={100}
+ *   step={0.5}
+ *   onChange={(value) => setTemperature(value)}
+ * />
+ *
+ * // Controlled component
+ * const [value, setValue] = useState(42);
+ * <SliderNumberInput
+ *   name="Count"
+ *   value={value}
+ *   onChange={setValue}
+ *   min={0}
+ *   max={1000}
+ * />
+ * ```
+ */
 export declare const SliderNumberInput: ForwardRefExoticComponent<SliderNumberInputProps & RefAttributes<HTMLInputElement & HTMLDivElement>>;
 
+/**
+ * Props for the SliderNumberInput component
+ */
 export declare type SliderNumberInputProps = {
+    /** Display name for the input */
     name?: string;
+    /** Current numeric value */
     value?: number;
+    /** Callback when the value changes */
     onChange?: (value: number) => void;
+    /** Additional CSS classes */
     className?: string;
+    /** Minimum allowed value */
     min?: number;
+    /** Maximum allowed value */
     max?: number;
+    /** Step size for value changes */
     step?: number;
 };
 
+/**
+ * Complete state definition for the graph system
+ *
+ * @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
+ */
 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;
+    /** Mapping from node IDs to their types */
     nodeIdToNodeType: NodeIdToNodeType<NodeTypeUniqueId>;
+    /** Array of edges in the graph */
     edges: Edges;
 };
 
+/**
+ * Union type of all supported underlying data types
+ */
 declare type SupportedUnderlyingTypes = (typeof supportedUnderlyingTypes)[number];
 
+/**
+ * Array of supported underlying data types
+ */
 declare const supportedUnderlyingTypes: readonly ["string", "number", "complex", "noEquivalent", "inferFromConnection"];
 
+/**
+ * Definition of an input type in a node
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ */
 declare type TypeOfInput<DataTypeUniqueId extends string = string> = {
+    /** Display name of the input */
     name: string;
+    /** The data type identifier this input uses */
     dataType: DataTypeUniqueId;
+    /** Whether this input allows direct user input */
     allowInput?: boolean;
 };
 
+/**
+ * Definition of an input panel type in a node
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ */
 declare type TypeOfInputPanel<DataTypeUniqueId extends string = string> = {
+    /** Display name of the input panel */
     name: string;
+    /** Array of inputs within this panel */
     inputs: TypeOfInput<DataTypeUniqueId>[];
 };
 
+/**
+ * Definition of a node type in the graph system
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ */
 declare type TypeOfNode<DataTypeUniqueId extends string = string> = {
+    /** Display name of the node type */
     name: string;
+    /** Color used for the node header */
     headerColor?: string;
+    /** Array of inputs (can be regular inputs or input panels) */
     inputs: (TypeOfInput<DataTypeUniqueId> | TypeOfInputPanel<DataTypeUniqueId>)[];
+    /** Array of outputs */
     outputs: TypeOfInput<DataTypeUniqueId>[];
 };
 
+/**
+ * Custom hook for detecting clicks outside of a specified element
+ *
+ * This hook provides functionality to detect when a user clicks outside of a
+ * specified element, commonly used for closing dropdowns, modals, or other
+ * overlay components.
+ *
+ * @template T - The type of HTML element being referenced
+ * @param ref - Reference to the element to monitor (can be RefObject or direct element)
+ * @param callback - Function to call when a click outside is detected
+ * @param checkDescendants - Whether to check if the click target is a descendant of the ref element (default: true)
+ * @param checkCoordinates - Whether to use coordinate-based checking instead of DOM hierarchy (default: false)
+ *
+ * @example
+ * ```tsx
+ * function Dropdown() {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *   const dropdownRef = useRef<HTMLDivElement>(null);
+ *
+ *   useClickedOutside(dropdownRef, () => {
+ *     setIsOpen(false);
+ *   });
+ *
+ *   return (
+ *     <div ref={dropdownRef}>
+ *       {isOpen && <div>Dropdown content</div>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using coordinate-based checking for more precise control
+ * function Modal() {
+ *   const modalRef = useRef<HTMLDivElement>(null);
+ *
+ *   useClickedOutside(
+ *     modalRef,
+ *     () => closeModal(),
+ *     false, // Don't check descendants
+ *     true   // Use coordinate checking
+ *   );
+ *
+ *   return <div ref={modalRef}>Modal content</div>;
+ * }
+ * ```
+ */
 export declare function useClickedOutside<T extends HTMLElement>(ref: RefObject<T | null> | T | null, callback: () => void, checkDescendants?: boolean, checkCoordinates?: boolean): void;
 
 /**
@@ -493,6 +1378,81 @@ export declare type UseDragReturn = {
     dragRef: (element: HTMLElement | null) => void;
 };
 
+/**
+ * Custom hook for managing the full graph state with reducer
+ *
+ * This hook provides state management for the entire graph including nodes, edges,
+ * data types, and node type definitions. It uses a reducer pattern for predictable
+ * state updates.
+ *
+ * @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 initialState - The initial state of the graph
+ * @returns Object containing the current state and dispatch function
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   useFullGraph,
+ *   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',
+ *   }),
+ *   numberType: makeDataTypeWithAutoInfer({
+ *     name: 'Number',
+ *     underlyingType: 'number',
+ *     color: '#E74C3C',
+ *   }),
+ * };
+ *
+ * // 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' }
+ *     ],
+ *   }),
+ * };
+ *
+ * // Define node ID to type mapping with auto-infer
+ * const nodeIdToNodeType = makeNodeIdToNodeTypeWithAutoInfer({
+ *   'node-1': 'inputNode',
+ * });
+ *
+ * // Create state with auto-infer for complete type safety
+ * const initialState = makeStateWithAutoInfer({
+ *   dataTypes,
+ *   typeOfNodes,
+ *   nodeIdToNodeType,
+ *   nodes: [],
+ *   edges: [],
+ * });
+ *
+ * const { state, dispatch } = useFullGraph(initialState);
+ *
+ * // Add a new node (type-safe!)
+ * dispatch({
+ *   type: 'ADD_NODE',
+ *   payload: { type: 'inputNode', position: { x: 100, y: 100 } },
+ * });
+ * ```
+ */
 export declare function useFullGraph<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(initialState: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>): {
     state: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>;
     dispatch: ActionDispatch<[action: Action<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>]>;