form-hooks.ts

Overview

The form-hooks.ts file provides custom React hooks designed to facilitate building select options for forms within a graph-based UI context. Specifically, it offers hooks to:

• Dynamically generate filtered and categorized options for dropdown select fields based on the current graph's node structure (useBuildFormSelectOptions).

• Provide localized sorting options for form elements (useBuildSortOptions).

These hooks are intended to be used in React components that require dynamically generated select options, particularly when dealing with nodes and operators in a graph data structure, ensuring that invalid or restricted choices are excluded.

Detailed API Documentation

1. useBuildFormSelectOptions

Description

useBuildFormSelectOptions is a React hook that returns a memoized function (buildCategorizeToOptions) to generate a filtered list of select options for a dropdown. These options represent graph nodes that:

• Are not excluded by operator restrictions.

• Are not the current node itself.

• Are not already selected in other related fields.

This hook helps maintain data integrity and user experience by preventing selection of invalid or conflicting nodes in a form.

Signature

useBuildFormSelectOptions(
  operatorName: Operator,
  selfId?: string
): (toList: string[]) => { label: string; value: string }[]

Parameters

• operatorName (Operator):
  The type of operator of the current node. Used to determine which nodes are restricted or excluded from selection.

• selfId (string | undefined):
  The unique identifier of the current node. Used to exclude the current node from selectable options.

Returns

• buildCategorizeToOptions: a function that accepts one parameter and returns an array of select options:

  • Parameter:

    • toList (string[]): An array of node IDs already selected in other "to" fields. Used to filter out options that have already been chosen elsewhere.

  • Return:

    • An array of objects with the shape { label: string, value: string }, where:

      • label: The display name of the node (node.data.name).

      • value: The unique node ID (node.id).

Usage Example

const operatorName = Operator.Filter;
const selfId = "node-123";

const buildOptions = useBuildFormSelectOptions(operatorName, selfId);

const selectedToList = ["node-456", "node-789"];
const options = buildOptions(selectedToList);

// options now contains nodes that:
// - Are not 'Note' operator nodes
// - Are not restricted upstream of 'Filter'
// - Are not selfId ("node-123")
// - Are not in selectedToList ("node-456", "node-789")

Implementation Details

• Retrieves the current graph nodes from a global React store (useGraphStore).

• Defines an exclusion list including:

  • The Operator.Note type nodes.

  • Any operators restricted upstream of the current operator, as defined in RestrictedUpstreamMap.

• Filters nodes based on:

  • Operator exclusion.

  • Excluding the current node (selfId).

  • Excluding nodes already selected in toList.

• Maps the filtered nodes into select option objects.

2. useBuildSortOptions

Description

useBuildSortOptions is a React hook that provides localized sorting options for use in forms or dropdowns. It returns a memoized array of options with values and translated labels.

Signature

useBuildSortOptions(): { value: string; label: string }[]

Parameters

• None

Returns

• An array of objects where each object has:

  • value (string): The sorting key (e.g., 'data', 'relevance').

  • label (string): The localized display label for the sorting option.

Usage Example

const sortOptions = useBuildSortOptions();

// sortOptions might be:
// [
//   { value: 'data', label: 'Data' },        // localized label for 'data'
//   { value: 'relevance', label: 'Relevance' } // localized label for 'relevance'
// ]

Implementation Details

• Uses the useTranslate hook scoped to the 'flow' namespace for i18n.

• Uses useMemo to memoize the options array, preventing unnecessary recalculations unless the translation function changes.

Important Implementation Details and Algorithms

• Filtering Logic in useBuildFormSelectOptions:
  The filtering mechanism ensures that the dropdown options do not include invalid nodes by excluding:

  • Nodes labeled as Note operator.

  • Nodes restricted by the RestrictedUpstreamMap for the current operator.

  • The current node itself (selfId).

  • Nodes already assigned in the other related "to" fields (toList).

• Memoization and Callbacks:

  • The filtering function buildCategorizeToOptions is wrapped in useCallback with dependencies on nodes, operatorName, and selfId to optimize performance by avoiding unnecessary re-computations.

  • The sorting options array in useBuildSortOptions is memoized using useMemo for similar performance benefits.

• Internationalization:
  The sorting options are translated dynamically using the useTranslate hook, ensuring the UI respects localization requirements.

Interactions with Other Parts of the System

• useGraphStore (from './store'):
  This hook accesses the global graph state, specifically the list of current nodes, which is central to building select options.

• Operator and RestrictedUpstreamMap (from './constant'):
  These constants define operator types and their restrictions on upstream connections, which are critical for filtering valid options.

• useTranslate (from '@/hooks/common-hooks'):
  Used to translate labels for sorting options, integrating this module with the overall i18n system of the application.

• React Hooks (useCallback, useMemo):
  Utilized for performance optimizations and functional programming style.

Together, these interactions enable the dynamic generation of form options that are context-aware and consistent with the graph's rules and localization.

Mermaid Diagram: Flowchart of Main Functions and Their Relationships

flowchart TD
    A[useBuildFormSelectOptions] --> B[useGraphStore.nodes]
    A --> C[Operator & RestrictedUpstreamMap]
    A --> D[buildCategorizeToOptions(toList)]
    D --> E[Filter nodes: exclude Operator.Note, restricted operators, selfId, toList]
    E --> F[Map to { label, value } options]

    G[useBuildSortOptions] --> H[useTranslate('flow')]
    G --> I[useMemo: ['data', 'relevance']]
    I --> J[Map to { value, label } options]

Summary

The form-hooks.ts file provides two essential hooks for generating form select options in a graph-based UI environment:

• useBuildFormSelectOptions produces context-aware options for node selection, enforcing operator restrictions and excluding already selected or invalid nodes.

• useBuildSortOptions offers localized sorting options for use in forms.

These hooks leverage global state, constants defining operator rules, and internationalization to deliver robust, reusable form utilities aligned with the system's data model and UX requirements.