use-watch-form-change.ts

Overview

This file provides utility functions and a custom React hook to monitor and synchronize changes in a React Hook Form instance with a graph node state managed in a centralized store. Specifically, it watches form value changes and updates a corresponding graph node's form data on a canvas or visualization.

• transferToObject: Converts an array of output descriptors into an object keyed by the output names for easier access and state management.

• useWatchFormChange: A React hook that subscribes to form value changes using react-hook-form and synchronizes these changes with a graph node identified by id in the application's graph store.

This file is typically used in scenarios where form data edits need to be reflected live in a graphical representation, such as a node-based editor or workflow tool.

Detailed Documentation

1. transferToObject

export function transferToObject(list: OutputArray): OutputObject

Purpose

Transforms an array of output definitions into an object, where each output's name becomes a key, and the value is an object containing a reference and type. This transformation facilitates quick lookup and structured data storage.

Parameters

• list (OutputArray): An array of outputs, where each item is expected to have at least the properties:

  • name (string): Identifier for the output.

  • ref (any): A reference object (e.g., React ref or DOM element).

  • type (string): The type of the output.

Returns

• OutputObject: An object whose keys are output names and values are objects containing ref and type.

Usage Example

const outputsArray = [
  { name: 'output1', ref: someRef1, type: 'number' },
  { name: 'output2', ref: someRef2, type: 'string' },
];

const outputsObject = transferToObject(outputsArray);
// outputsObject = {
//   output1: { ref: someRef1, type: 'number' },
//   output2: { ref: someRef2, type: 'string' },
// }

2. useWatchFormChange

export function useWatchFormChange(id?: string, form?: UseFormReturn): void

Purpose

Custom React hook that listens to changes in a form controlled by react-hook-form and updates the form data for a corresponding graph node in a centralized graph store.

Parameters

• id (string | undefined): The unique identifier of the graph node whose form data should be synchronized.

• form (UseFormReturn | undefined): The form instance returned by react-hook-form's useForm or similar hook.

Behavior and Implementation Details

• Uses useWatch from react-hook-form to subscribe to all form value changes.

• Accesses the updateNodeForm method from useGraphStore (a Zustand or similar state management store) to update the graph node's form data.

• Within a useEffect hook, whenever the form is dirty, it:

  • Retrieves the latest form values.

  • Converts the outputs array in the form values to an object via transferToObject.

  • Calls updateNodeForm with the node id and the transformed form data.

• This mechanism ensures that manual form updates are immediately reflected in the node's visual representation or internal state.

Return Value

• None. (void)

Usage Example

function NodeEditor({ nodeId, formInstance }: { nodeId: string; formInstance: UseFormReturn }) {
  useWatchFormChange(nodeId, formInstance);
  
  // Rest of the component rendering the form and node...
}

Important Implementation Details

• The hook depends on react-hook-form's useWatch to listen to form changes efficiently without unnecessary re-renders.

• Synchronization happens only if the form is marked as dirty to avoid excessive updates.

• The transformation of the outputs field from an array to an object structure is crucial for the graph store's expected data format, likely for efficient lookup and rendering.

• updateNodeForm is sourced from a centralized state store (useGraphStore), implying a global or shared state management pattern (likely Zustand).

• The hook is designed to be flexible: if no id or form is provided, it will not perform updates, making it safe to use in conditional rendering scenarios.

Interaction with Other Parts of the System

• react-hook-form: Provides the form state and watching capabilities.

• useGraphStore: A custom state store (possibly Zustand) that manages the graph's nodes and their states.

• The updateNodeForm method in useGraphStore updates the state related to a specific node, which likely triggers UI updates in a canvas or node graph visualization.

• The file imports types OutputArray and OutputObject from a relative ./interface file, suggesting a shared type definition across the project related to form outputs.

Mermaid Diagram

Below is a flowchart showing the relationship between main functions and their interactions with external dependencies:

flowchart TD
    A[useWatchFormChange(id, form)] --> B[useWatch(form.control)]
    B --> C{form.formState.isDirty?}
    C -- Yes --> D[form.getValues()]
    D --> E[transferToObject(values.outputs)]
    E --> F[updateNodeForm(id, nextValues)]
    C -- No --> G[No update]
    
    subgraph External Dependencies
      B
      F[updateNodeForm(id, nextValues)] --- useGraphStore
      A --- react-hook-form
    end

Summary

• This file provides a seamless way to bind form changes in React Hook Form to a graph node's state.

• It converts form outputs to a structured object for efficient state updates.

• The custom hook useWatchFormChange ensures changes are propagated live to the graph store.

• It integrates with a global graph store and relies on React Hook Form for form management.

This approach enables a reactive UI where form edits are immediately reflected in a graphical node editor, improving user experience and data consistency.