form-hooks.ts

Overview

The form-hooks.ts file provides a set of custom React hooks designed to facilitate form-related interactions within a graph-based UI, particularly for managing node connections and option selections in a flow or graph editor. It leverages state management from a centralized graph store (useGraphStore) and supports localized UI text through translation hooks.

This file's primary responsibilities include:

• Dynamically constructing selectable options for form dropdowns based on graph nodes, while respecting constraints related to node types and relationships.

• Handling changes in form select inputs to update edges (connections) between nodes in the graph.

• Providing predefined sorting options with localization support.

These hooks are intended for use in React components that manage graph nodes and their interconnections, enabling intuitive user interactions and maintaining consistent graph state.

Detailed Explanations

Imports

• useTranslate: Custom hook for internationalization, used here to translate UI labels.

• React hooks: useCallback, useMemo for memoization and performance optimization.

• Operator, RestrictedUpstreamMap: Constants defining node operator types and restrictions on upstream connections.

• useGraphStore: A Zustand-based store managing the graph's nodes and edges.

Hook: useBuildFormSelectOptions

export const useBuildFormSelectOptions = (
  operatorName: Operator,
  selfId?: string,
) => { ... }

Purpose

Generates a memoized function that builds a list of selectable options for a form dropdown, representing nodes in the graph that can be connected to the current node. It filters out nodes based on operator restrictions and prevents selection of the current node or already selected nodes in other dropdowns.

Parameters

• operatorName: Operator — The operator type of the current node. Used to determine which nodes are restricted upstream and should be excluded.

• selfId?: string — Optional. The ID of the current node to exclude it from the options list.

Returns

• A function (toList: string[]) => { label: string; value: string }[] that takes a list of node IDs already selected in other dropdowns (toList) and returns an array of option objects suitable for form select components.

Usage Example

const buildOptions = useBuildFormSelectOptions(Operator.Filter, currentNodeId);
const options = buildOptions(selectedTargetIds);

Where selectedTargetIds is an array of node IDs already selected in other related form fields to avoid duplicates.

Hook: useHandleFormSelectChange

export const useHandleFormSelectChange = (nodeId?: string) => { ... }

Purpose

Provides a memoized callback function to handle changes in form select inputs by adding or removing edges (connections) between nodes in the graph store.

Parameters

• nodeId?: string — The source node ID for which the select input is being managed.

Returns

• An object with a method:

  • handleSelectChange(name?: string): (value?: string) => void — Returns a function that takes the selected target node ID (value) and updates the graph edges accordingly.

Behavior

• When a value is selected, it adds an edge from the source node (nodeId) to the target node (value), specifying the handle name on the source.

• When the value is cleared (null/undefined), it deletes the corresponding edge based on source node and handle name.

Usage Example

const { handleSelectChange } = useHandleFormSelectChange(currentNodeId);

<select onChange={e => handleSelectChange('output')(e.target.value)}>
  {options.map(opt => (
    <option key={opt.value} value={opt.value}>{opt.label}</option>
  ))}
</select>

Hook: useBuildSortOptions

export const useBuildSortOptions = () => { ... }

Purpose

Generates a memoized array of sorting options for form select inputs, with localized labels for sorting criteria such as "data" and "relevance".

Returns

• An array of objects: { value: string; label: string }[]

Implementation Details

• Uses the useTranslate hook scoped to the 'flow' namespace to translate option labels.

• The returned options can be used in dropdowns to allow users to select sorting preferences.

Usage Example

const sortOptions = useBuildSortOptions();

<select>
  {sortOptions.map(opt => (
    <option key={opt.value} value={opt.value}>{opt.label}</option>
  ))}
</select>

Important Implementation Details and Algorithms

• Filtering Logic in useBuildFormSelectOptions:
  The hook excludes nodes from the selectable options based on:

  • The current node's operator restrictions (RestrictedUpstreamMap), which define which operator types are disallowed as upstream connections.

  • Exclusion of the current node itself (selfId).

  • Exclusion of nodes already selected in other related dropdowns (toList), preventing duplicate or cyclic selections.

• Edge Management in useHandleFormSelectChange:
  Edges are managed by adding or deleting connections in the graph store. The source node and handle name identify edges uniquely for deletion. This ensures that changes in form fields directly reflect in the graph's connectivity.

• Localization with useTranslate:
  useBuildSortOptions demonstrates integration with an i18n system to provide user-friendly, localized UI labels.

Interaction with Other Parts of the System

• Graph Store (useGraphStore):
  Central to this file's functionality, the graph store holds the state of nodes and edges. Hooks here use it to read node data and update edges, ensuring that form selections keep the graph structure consistent.

• Constants (Operator, RestrictedUpstreamMap):
  These define the types of nodes/operators and rules about allowable connections, enforcing business logic constraints.

• Translation Hook (useTranslate):
  Provides localized strings for UI components, making the form hooks adaptable to different languages.

• React Components (not shown here):
  Components rendering the form inputs would use these hooks to build options, handle user interactions, and update the graph accordingly.

Mermaid Diagram

flowchart TD
    A[useBuildFormSelectOptions] -->|uses| B[useGraphStore.nodes]
    A -->|uses| C[Operator, RestrictedUpstreamMap]
    D[useHandleFormSelectChange] -->|uses| E[useGraphStore.addEdge]
    D -->|uses| F[useGraphStore.deleteEdgeBySourceAndSourceHandle]
    G[useBuildSortOptions] -->|uses| H[useTranslate('flow')]
    subgraph GraphStore
        B
        E
        F
    end
    subgraph Constants
        C
    end
    subgraph Hooks
        A
        D
        G
    end

Summary

The form-hooks.ts file encapsulates essential logic for managing dynamic form options and selections in a graph editing UI. By abstracting the complexity of filtering nodes, managing graph edges, and providing localized options, it supports clean and maintainable React component implementations that interact with a graph data model. The hooks ensure that user inputs remain consistent with the underlying graph constraints and provide a seamless user experience.