query-variable.tsx

Overview

The query-variable.tsx file defines a reusable React component named QueryVariable that renders a form field allowing users to select query variables with searchable dropdown options. This component integrates tightly with React Hook Form for form state management and supports dynamic filtering of options based on a specified variable type.

This component is designed for use in forms where users need to pick variables related to queries, with support for internationalization and customizable labeling. It leverages custom UI components and hooks from the project to build a flexible and user-friendly selection interface.

Detailed Documentation

Imports and Dependencies

SelectWithSearch: A custom dropdown component with search functionality.
FormControl, FormField, FormItem, FormLabel, FormMessage: UI components for building accessible and consistent form layouts.
toLower (lodash): Utility to convert strings to lowercase.
useMemo (React): Hook to memoize expensive calculations.
useFormContext (react-hook-form): Hook to access form context and control.
useTranslation (react-i18next): Hook for internationalization (i18n) support.
VariableType: Enum or type representing valid variable types.
useBuildQueryVariableOptions: Custom hook to retrieve query variable options.

`QueryVariable` Component

type QueryVariableProps = {
  name?: string;
  type?: VariableType;
  label?: ReactNode;
};

Description

QueryVariable is a functional React component that renders a searchable select dropdown form field within a form managed by React Hook Form. It allows users to select from a filtered list of query variables, optionally filtered by their type.

Props

Prop Name	Type	Default	Description
`name`	`string`	`'query'`	The name of the form field, used by React Hook Form to identify and manage the field state.
`type`	`VariableType`	`undefined`	An optional filter to limit the displayed variables to those matching the provided type.
`label`	`ReactNode`	`undefined`	An optional custom label to display for the form field. If not provided, a default label is shown.

Internal Workflow

Form Context Access
Uses useFormContext() to obtain the current form context and control object for managing the field's value and validation.
Building Options
Calls useBuildQueryVariableOptions() to retrieve the available query variable options grouped appropriately.
Filtering Options by Type
Using useMemo, it processes the options to filter out variables that do not match the type prop if provided. The filtering is case-insensitive via toLower.
Rendering
Renders a FormField component connected to the form's control and name. Inside the render prop:
- Displays a label, either the custom one passed via props or a default translated label with a tooltip.
- Renders the SelectWithSearch dropdown with the filtered options and integrated with form state.
- Shows validation messages via FormMessage.

Return Value

Returns a JSX element representing the complete form field for selecting query variables.

Usage Example

import { QueryVariable } from './query-variable';
import { VariableType } from '../../constant';

function MyFormComponent() {
  return (
    <form>
      <QueryVariable 
        name="myQueryVar" 
        type={VariableType.String} 
        label="Select Query Variable" 
      />
      {/* other form fields and submit button */}
    </form>
  );
}

In this example, the QueryVariable component is used with a specific name, filtered to only show variables of type String, and with a custom label.

Implementation Details & Algorithms

Option Filtering Algorithm
The component filters the query variable options based on the type prop. This is done by iterating over option groups (nextOptions) and filtering their nested options where the type property (converted to lowercase) includes the lowercase string of the provided type. This ensures flexible partial matching.
Performance Optimization
The filtering logic is wrapped inside a useMemo hook, preventing unnecessary recalculations unless the nextOptions or type values change.
Form Integration
Utilizes React Hook Form's FormField to synchronize the selected value with the form state, ensuring easy validation and submission handling.
Internationalization
Uses useTranslation to fetch localized strings for labels and tooltips, supporting multi-language applications.

Interaction with Other System Parts

Custom Hooks:
- useBuildQueryVariableOptions: Retrieves the data structure representing available query variables. This hook is likely connected to upstream data sources or state management to supply current options.
UI Components:
- SelectWithSearch: Provides the searchable dropdown UI element.
- Form components (FormField, FormControl, etc.) provide consistent styling and accessibility.
Form System:
The component is built to work within a React Hook Form context, making it dependent on being used inside a form managed by react-hook-form.
Localization:
Leverages react-i18next for translating UI text, depending on the app's i18n setup.

Mermaid Diagram - Component Structure and Workflow

componentDiagram
    component QueryVariable {
      +props: QueryVariableProps
      +uses: useFormContext()
      +uses: useTranslation()
      +uses: useBuildQueryVariableOptions()
      +uses: useMemo()
      +renders: FormField
      +renders: SelectWithSearch
    }

    component SelectWithSearch
    component FormField
    component useBuildQueryVariableOptions
    component useFormContext
    component useTranslation

    QueryVariable --> useFormContext
    QueryVariable --> useTranslation
    QueryVariable --> useBuildQueryVariableOptions
    QueryVariable --> useMemo
    QueryVariable --> FormField
    FormField --> SelectWithSearch

Summary

query-variable.tsx provides an encapsulated, internationalized, and form-integrated React component to select query variables with dynamic filtering based on variable type. It interacts with the application's form state, translation system, and data layer via custom hooks, ensuring a clean separation of concerns and enhancing reusability across the app's query-building interfaces.