query-variable.tsx

Overview

The query-variable.tsx file defines a React functional component named QueryVariable. This component provides a form field that allows users to select a query variable from a searchable dropdown list. The dropdown options are dynamically generated and optionally filtered by a specified variable type. It integrates tightly with react-hook-form for form state management and uses internationalization support via react-i18next.

This component is intended for use within forms that require selecting or specifying query variables, likely in a broader application context related to building or configuring queries (e.g., for data filtering or API requests).

Detailed Explanation

QueryVariable Component

function QueryVariable({
  name = 'query',
  type,
  label,
}: QueryVariableProps): JSX.Element

Description

QueryVariable renders a form field with a label and a searchable select dropdown for choosing query variables. It leverages the useFormContext hook to integrate with react-hook-form's form control, ensuring that the selected value is managed within the form's state.

Props

• name?: string
  The name of the form field. Defaults to 'query'. This is the key used in the form data for this field.

• type?: VariableType
  Optional. If provided, used to filter the available variable options by this type (case-insensitive). The filtering is done on the type property of each option.

• label?: ReactNode
  Optional. A custom label to display above the select field. If not provided, a localized default label with a tooltip is rendered.

Return Value

Returns a React JSX element rendering the form field with the filtered variable options.

Usage Example

<QueryVariable 
  name="userQuery" 
  type="string" 
  label={<span>User Query</span>} 
/>

This example renders the QueryVariable form field with a custom label "User Query", filters options to only those of type including "string", and uses "userQuery" as the form field name.

Implementation Details and Algorithms

• Options Generation & Filtering
  The component uses a custom hook useBuildQueryVariableOptions() to fetch or generate the list of available query variable options. This hook likely returns an array of option groups, each containing options with metadata including a type field.

• Filtering Logic
  If the type prop is provided, the options are filtered to include only those whose lowercase type string contains the given type substring. This filtering is memoized via useMemo to optimize performance by avoiding unnecessary recalculations on re-renders.

• Form Integration
  The FormField component from the UI library integrates with react-hook-form via the control prop from useFormContext(). It binds the selected value and change handlers to the form state.

• Localization
  The label and tooltip text use the useTranslation hook from react-i18next to support internationalization.

• UI Components Used

  • SelectWithSearch: a custom select component supporting searching within options.

  • FormControl, FormField, FormItem, FormLabel, FormMessage: components from the UI form library to structure the form field, label, validation messages, and controls.

Interaction with Other Parts of the System

• useBuildQueryVariableOptions Hook
  This hook is crucial as it provides the options data. It presumably accesses application state or performs computations to build the list of query variables that can be selected.

• UI Component Library
  The form and select components are imported from shared UI component libraries, suggesting consistent styling and behavior across the application.

• Internationalization
  The component uses translation keys (flow.queryTip, flow.query) which depend on the application's i18n resource files.

• Form State Management
  The component must be used inside a react-hook-form context provider (FormProvider or equivalent), as it uses useFormContext().

Component Structure Diagram

classDiagram
    class QueryVariable {
      +name: string
      +type: VariableType | undefined
      +label: ReactNode | undefined
      +render(): JSX.Element
    }

    QueryVariable ..> SelectWithSearch : uses
    QueryVariable ..> FormField : uses
    QueryVariable ..> useBuildQueryVariableOptions : calls
    QueryVariable ..> useFormContext : calls
    QueryVariable ..> useTranslation : calls

Summary

The query-variable.tsx file provides a reusable, localized, and form-integrated React component to select query variables from dynamically generated and optionally filtered options. It abstracts away the complexity of fetching and filtering options, localization, and form integration, making it easy to embed query variable selection in forms throughout the application.

This component depends on several shared modules including UI form components, a custom select-with-search component, translation hooks, and a custom hook for fetching query variable options. It is designed for use within a react-hook-form managed form environment.

End of Documentation for query-variable.tsx