form-hooks.ts

Overview

The form-hooks.ts file provides custom React hooks designed to build option lists for form elements in a flow or graph-based UI. These hooks assist in constructing dropdown options for selecting nodes and sorting criteria, ensuring that invalid or restricted choices are automatically excluded based on business logic and graph state.

Primarily, the file exports two hooks:

• useBuildFormSelectOptions: Generates selectable node options for form dropdowns, filtering out nodes that are restricted or already selected elsewhere.

• useBuildSortOptions: Provides sorting options with localized labels, typically for sorting data or relevance.

These hooks rely on internal graph state management and localization utilities, making them integral to dynamic form controls within a graph-driven application.

Detailed Documentation

Imports

• useTranslate (from @/hooks/common-hooks): A hook for internationalization, returning a translation function scoped to a given namespace.

• React hooks useCallback and useMemo for memoizing functions and values.

• Constants Operator and RestrictedUpstreamMap from ./constant which define operator types and restrictions.

• useGraphStore from ./store: A Zustand (or similar) store hook to access current graph nodes.

Exported Hooks

useBuildFormSelectOptions

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

Purpose

Generates a memoized function that builds an array of selectable options representing graph nodes, excluding those that are restricted for the given operatorName, the current node itself (selfId), and any nodes already selected in other "to" fields (toList).

Parameters

• operatorName: Operator
  The operator type of the current node requesting options. Used to determine which upstream nodes are restricted.

• selfId?: string (optional)
  The ID of the current node to exclude itself from the selectable options.

Returns

• A callback function (toList: string[]) => Array<{ label: string; value: string }>
  This function accepts a list of node IDs (toList) that are already selected in other dropdowns and returns a filtered array of option objects for use in a select input.

Behavior and Implementation Details

• Retrieves the current list of nodes from the global graph state (useGraphStore).

• Defines an exclusion list that always includes nodes labeled as Operator.Note plus any operators restricted upstream for the given operatorName (from RestrictedUpstreamMap).

• Filters the nodes:

  • Excludes any node whose label is in the exclusion list.

  • Excludes the current node by selfId.

  • Excludes nodes already present in the toList parameter (to prevent duplicate selections across dropdowns).

• Maps remaining nodes into { label, value } pairs, where:

  • label is the node's display name (x.data.name)

  • value is the node's unique ID (x.id)

Usage Example

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

const selectedIds = ['node1', 'node3'];

const options = buildOptions(selectedIds);

// options can be passed to a <Select> component
<Select options={options} />

useBuildSortOptions

useBuildSortOptions() => Array<{ value: string; label: string }>

Purpose

Creates a memoized array of sorting options with internationalized labels, typically used for sorting data in UI dropdowns.

Returns

• An array of option objects:

  [
    { value: 'data', label: string },
    { value: 'relevance', label: string }
  ]
  

Behavior and Implementation Details

• Uses the translation function t scoped to the 'flow' namespace.

• Generates options for the sorting fields 'data' and 'relevance'.

• Each option includes a translated label via t(value).

Usage Example

const sortOptions = useBuildSortOptions();

<Select options={sortOptions} />

Important Implementation Details

• Filtering Logic in useBuildFormSelectOptions:
  The exclusion of nodes is driven by RestrictedUpstreamMap which defines upstream restrictions for each operator. This enforces graph constraints and prevents invalid connections.

• Memoization:
  Both hooks use React's useCallback and useMemo to optimize performance by preventing unnecessary recalculations on re-renders unless dependencies change.

• Localization Support:
  useBuildSortOptions leverages useTranslate to support multi-language labels, facilitating internationalization.

• Graph State Dependency:
  The useBuildFormSelectOptions hook depends on the current graph nodes state from useGraphStore, ensuring that option lists reflect the up-to-date graph structure.

Interaction with Other System Components

• Graph State Store (./store):
  Accesses graph nodes for filtering and option construction.

• Constants (./constant):
  Uses Operator enums and RestrictedUpstreamMap to apply business rules for filtering nodes.

• Common Hooks (@/hooks/common-hooks):
  Utilizes useTranslate for localization.

• UI Components:
  The generated options are intended to be passed to form components like dropdown selects.

Visual Diagram

flowchart TD
    A[useBuildFormSelectOptions] --> B[useGraphStore.nodes]
    A --> C[Operator & RestrictedUpstreamMap]
    A --> D[Callback function: buildCategorizeToOptions(toList)]
    D --> E[Filters nodes excluding restricted, self, and selected in toList]
    D --> F[Returns list of { label, value } options]

    G[useBuildSortOptions] --> H[useTranslate('flow')]
    G --> I[useMemo generates options for 'data' and 'relevance']
    I --> J[Returns list of { value, label }]

    style A fill:#f9f,stroke:#333,stroke-width:1px
    style G fill:#ccf,stroke:#333,stroke-width:1px

Summary

The form-hooks.ts file is a utility module that provides reusable hooks to build and filter options for forms within a graph-based application. It encapsulates complex filtering logic and localization concerns, enabling consistent and efficient creation of dropdown options that respect graph constraints and UI localization requirements. This file plays a key role in ensuring forms reflect the current graph state and adhere to operator restrictions, enhancing user experience and data integrity.