use-watch-change.ts

Overview

The use-watch-change.ts file defines a custom React hook, useWatchFormChange, designed to synchronize form state changes with a graphical node-based data store. It leverages React Hook Form's useWatch to observe form value changes and updates the corresponding node's data in a centralized graph store. This ensures that any modifications made in a form UI are immediately reflected in the application's graph data model.

This hook is primarily used in contexts where users interact with form inputs tied to graph nodes (such as agents and their tools), and there is a need to keep the canvas or visual graph representation consistent with form state changes.

Detailed Explanation

Imports

• useEffect from React: for running side effects when dependencies change.

• UseFormReturn, useWatch from react-hook-form: to handle form state and watch for value changes.

• useGraphStore from local store: a Zustand or similar store managing graph state.

• getAgentNodeTools from utilities: a helper function to extract tools data from an agent node.

Function: useWatchFormChange

export function useWatchFormChange(form?: UseFormReturn<any>)

Purpose

A custom React hook that watches form value changes and updates the corresponding graph node's form data in the global state store.

Parameters

• form (optional): An object representing the form instance returned by useForm() from react-hook-form. This includes methods and state related to form handling such as control, getValues(), and formState.

Behavior and Implementation Details

1. Watching form values:

   The hook uses useWatch with the form's control to subscribe to form field changes and get the current form values reactively.

2. Accessing graph store state and actions:

   Using the useGraphStore hook, it extracts:

   • clickedToolId: the currently selected tool's identifier.

   • clickedNodeId: the currently selected node's identifier.

   • findUpstreamNodeById(id): a function to retrieve a node upstream in the graph by its ID.

   • updateNodeForm(id, values): a function to update the form data of a node in the graph.

3. Effect hook for synchronization:

   Inside a useEffect, the hook checks when:

   • The form is dirty (form?.formState.isDirty): meaning the form has unsaved changes.

   • The graph store update function or watched values change.

   If the form is dirty and the upstream agent node exists, it proceeds to:

   • Retrieve the agent node via findUpstreamNodeById(clickedNodeId).

   • Extract the current tools from the agent node using getAgentNodeTools.

   • Get the latest form values using form.getValues().

   • Update the specific tool in the tools array that matches clickedToolId by replacing its params with the new form values.

   • Construct the new node form data with the updated tools.

   • Call updateNodeForm to update the node's form data in the store.

Return Value

• This hook returns nothing (void). Its purpose is side-effect synchronization between form state and graph store data.

Usage Example

import { useForm } from 'react-hook-form';
import { useWatchFormChange } from './use-watch-change';

function AgentToolForm() {
  const form = useForm({ defaultValues: {/*...*/} });
  
  // Synchronize form changes to graph store
  useWatchFormChange(form);

  // Render form fields...
  return (
    <form>
      {/* form inputs bound to form */}
    </form>
  );
}

Important Implementation Details

• Manual synchronization: The hook only updates the graph node form data when the form is dirty, indicating user changes that need to be committed.

• Selective tool update: Only the tool with component_name matching the currently clicked tool ID is updated, preserving other tools' data.

• Dependency array: The effect depends on form?.formState.isDirty, updateNodeForm, and values from useWatch, ensuring it triggers on relevant changes.

• Data immutability: The tools array and form data are updated immutably, creating new objects rather than mutating existing ones.

Interaction with Other Parts of the System

• Graph Store (useGraphStore): The hook interacts heavily with the graph store, reading the current selected node and tool, and updating node form data. The graph store likely manages the state of nodes and edges for a visual graph or canvas.

• Form Management (react-hook-form): It uses React Hook Form's advanced features (useWatch, formState, getValues) to track and retrieve form state efficiently.

• Utility (getAgentNodeTools): This helper extracts the tools array from a node, helping to update tool-specific parameters.

• UI Components: This hook is designed to be integrated into form components that edit properties of graph nodes/tools, ensuring two-way sync between UI and graph model.

Mermaid Diagram

classDiagram
    class useWatchFormChange {
        +form?: UseFormReturn<any>
        -values: any
        +useEffect()
    }

    class useGraphStore {
        +clickedToolId: string
        +clickedNodeId: string
        +findUpstreamNodeById(id: string): Node | undefined
        +updateNodeForm(id: string, values: any): void
    }

    class getAgentNodeTools {
        +getAgentNodeTools(node: Node): Tool[]
    }

    useWatchFormChange --> useGraphStore : reads/writes state
    useWatchFormChange --> getAgentNodeTools : extracts tools
    useWatchFormChange --> useEffect : sync logic

Summary

The use-watch-change.ts file provides a specialized React hook, useWatchFormChange, that tightly couples form input changes to updates in a graph node's form data within a centralized store. It bridges React Hook Form's reactive form capabilities with a graph-based data model, making it crucial for applications involving node-tool editing on a canvas or graph interface.

This hook ensures that user modifications in forms are promptly and accurately reflected in the graph data structure, fostering consistency between UI and backend state. The design favors immutability, selective updates, and integration with global graph state, making it a key utility for managing form-driven node configurations.