use-watch-change.ts

Overview

use-watch-change.ts provides a custom React hook useHandleFreedomChange designed to facilitate reactive updates in a form driven by React Hook Form and contextual graph state management. This hook listens for changes in specific parameters, merges predefined variable maps into the form state, and synchronizes these updates with a graph-based node store.

This file plays a crucial role in dynamically handling form field dependencies and propagating updates through the application state, particularly within agent configuration pages of the host system.

Detailed Explanation

useHandleFreedomChange

A custom hook that returns a handler function for updating form values and graph node state based on a parameter change.

Signature

function useHandleFreedomChange(
  getFieldWithPrefix: (name: string) => string,
): (parameter: string) => void

Parameters

• getFieldWithPrefix: (name: string) => string

  A function that, given a field name, returns the corresponding form field name with any necessary prefix. This supports namespacing or scoped fields within the form.

Returns

• (parameter: string) => void

  A handler function that accepts a parameter name. When called, it updates the form and graph node state according to predefined mappings associated with that parameter.

Internal Functions

setLLMParameters

A helper function defined inside the hook using useCallback. It sets multiple form field values at once.

Parameters

• values: Record<string, any> — An object mapping form field keys to their new values.

• withPrefix: boolean — If true, the keys are prefixed using getFieldWithPrefix before being set in the form.

Behavior

Iterates over each key-value pair in values, transforms the key if withPrefix is true, and sets the value in the form context using React Hook Form's setValue.

Usage Example

setLLMParameters({ temperature: 0.7, maxTokens: 256 }, true);

handleChange

The main callback returned by the hook, created with useCallback, which performs the following sequence when invoked with a parameter key:

1. Retrieves the current form values.

2. Looks up predefined variable mappings for the given parameter in settledModelVariableMap.

3. Merges these variables into the current form values to create a new state snapshot.

4. If a node ID exists in context, calls updateNodeForm from the global graph store to update the node's form data.

5. Retrieves a mapping of additional checkbox fields from setChatVariableEnabledFieldValuePage.

6. Calls setLLMParameters twice:

   • Once to update the form fields with the new variable values (with prefix).

   • Once to update the checkbox field values (without prefix).

Parameters

• parameter: string — The key identifying which variable mapping to apply.

Usage Example

const handleChange = useHandleFreedomChange(getFieldWithPrefix);
handleChange('temperature');

Important Implementation Details

• Dependency on External Constants and Contexts:

  • settledModelVariableMap: A constant mapping parameter keys to variable sets that should be applied when those parameters change.

  • AgentFormContext: Provides the current node context, specifically the node ID.

  • useGraphStore: A Zustand store hook for managing the graph of nodes and their form data.

  • setChatVariableEnabledFieldValuePage: Returns a mapping of checkbox-related field values which are also updated upon parameter change.

• Form Integration:

  Uses react-hook-form's useFormContext to interact with form state, ensuring compatibility with forms built using this library.

• State Synchronization:

  Updates are propagated to both the local form and the global graph store, ensuring UI consistency and centralized state management.

• Use of useCallback:

  Memoizes internal functions (setLLMParameters and handleChange) to avoid unnecessary re-renders or recreations of handlers.

Interaction with Other Parts of the System

• Agent Page Context and Store:

  The hook assumes it is used within a React component tree that provides AgentFormContext and useGraphStore. It updates the graph node's form state directly, which likely triggers UI updates elsewhere in the agent configuration interface.

• Form Fields and Variables:

  Works with predefined variable mappings (settledModelVariableMap and checkbox mappings) to automatically adjust form fields, helping maintain consistency between user selections and underlying model parameters.

• Utilities:

  Uses setChatVariableEnabledFieldValuePage utility to manage checkbox fields, indicating a coupling to chat-related UI or logic.

Example Usage

import React from 'react';
import { useHandleFreedomChange } from './use-watch-change';

function AgentParameterSelector({ getFieldWithPrefix }) {
  const handleChange = useHandleFreedomChange(getFieldWithPrefix);

  return (
    <select onChange={e => handleChange(e.target.value)}>
      <option value="temperature">Temperature</option>
      <option value="maxTokens">Max Tokens</option>
      {/* other options */}
    </select>
  );
}

Mermaid Diagram: Flowchart of Main Functions and Their Relationships

flowchart TD
    A[useHandleFreedomChange Hook]
    A --> B[setLLMParameters]
    A --> C[handleChange]

    C -->|uses| D[settledModelVariableMap]
    C -->|calls| B
    C -->|calls| E[setChatVariableEnabledFieldValuePage]
    C -->|calls| F[updateNodeForm (Graph Store)]
    B -->|calls| G[form.setValue]

    subgraph Contexts and Stores
      H[AgentFormContext]
      I[useGraphStore]
      J[useFormContext]
    end

    A --> H
    A --> I
    A --> J

Summary

The use-watch-change.ts file implements a reusable hook that bridges form state management with graph-based node state updates in an agent configuration context. It provides a clean abstraction for applying parameter-driven changes to form fields and syncing these changes with a global store, leveraging React context and hooks for optimal performance and maintainability.