variable-picker-plugin.tsx

Overview

variable-picker-plugin.tsx is a React component plugin designed for the Lexical text editor framework. It provides a typeahead menu that allows users to insert variable nodes into the editor content by typing a trigger character (/). This plugin supports searching and selecting variables from a structured list and replaces matched text patterns with special variable nodes inside the editor.

Key features:

• Displays a typeahead dropdown menu when the trigger / is typed.

• Supports filtering variable options based on user input.

• Inserts custom variable nodes into the Lexical editor content.

• Parses existing text with variable placeholders ({variable}) and converts them into variable nodes on initial load.

• Integrates with external flow form context and component ID options for dynamic variable options.

Classes

VariableInnerOption (extends MenuOption)

Represents an individual variable option within a grouped menu.

Properties

• label: string — The display text label for the option.

• value: string — The underlying variable identifier.

Constructor

constructor(label: string, value: string)

• label: The text label to show.

• value: The variable value/ID.

Creates an option representing a selectable variable.

VariableOption (extends MenuOption)

Represents a grouped menu option containing multiple VariableInnerOption entries.

Properties

• label: ReactElement | string — Label for the group header.

• title: string — Title of the group.

• options: VariableInnerOption[] — List of variable options in the group.

Constructor

constructor(
  label: ReactElement | string,
  title: string,
  options: VariableInnerOption[],
)

• label: Display label or React element for the group header.

• title: Group title.

• options: Array of VariableInnerOption items.

Components & Functions

VariablePickerMenuItem

A React component that renders a single grouped variable menu item with its inner options.

Props

{
  index: number;
  option: VariableOption;
  selectOptionAndCleanUp: (option: VariableOption | VariableInnerOption) => void;
}

• index: The position index for accessibility attributes.

• option: The grouped variable option to render.

• selectOptionAndCleanUp: Callback invoked when an inner option is selected.

Usage Example

Renders a group label and a list of clickable variable items:

<VariablePickerMenuItem
  index={0}
  option={someVariableOption}
  selectOptionAndCleanUp={handleSelect}
/>

VariablePickerMenuPlugin

The main exported React component that integrates with Lexical's LexicalTypeaheadMenuPlugin to provide the variable picker functionality.

Props

{
  value?: string;
}

• value: Optional initial string that may contain variable placeholders to parse and render as variable nodes on first load.

Functionality

• Uses Lexical editor context to update editor state.

• Uses FlowFormContext to retrieve current flow node data.

• Fetches variable options dynamically via useBuildComponentIdSelectOptions.

• Filters options based on user query string.

• On variable option selection, replaces the trigger text with a variable node.

• Parses initial text with {variable} placeholders and converts them to variable nodes.

Usage Example

<VariablePickerMenuPlugin value="{userName} logged in" />

This would initialize the editor content by replacing {userName} with the corresponding variable node if found.

Important Implementation Details

Trigger and Query Matching

• Uses Lexical's useBasicTypeaheadTriggerMatch with / as the trigger character.

• Minimum trigger length set to 0, so the menu opens immediately after /.

Option Filtering

• Filters nested options to show only those whose label or value includes the current query string (case-insensitive).

Variable Node Insertion

• On selection, the plugin removes the typed trigger text node and inserts a custom variable node created by $createVariableNode(value, label).

Parsing Text to Variable Nodes

• parseTextToVariableNodes uses a regex /{([^}]*)}/g to find {variable} patterns.

• Text parts outside variables become text nodes.

• Recognized variables are replaced by variable nodes.

• Unmatched placeholders remain as text nodes.

• Clears the editor root and appends the constructed paragraph with mixed text and variable nodes.

React Portals & Menu Rendering

• The menu is rendered as a portal attached to the anchor element provided by LexicalTypeaheadMenuPlugin.

• The menu lists grouped variables and handles click selection.

Interaction with Other System Parts

• Lexical Editor Framework: Integrates tightly with Lexical's React composer context, selection APIs, and custom node creation for rich text editing.

• FlowFormContext: Consumes context to determine current node identifiers for fetching relevant variable options.

• useBuildComponentIdSelectOptions: Custom hook fetching structured variable options based on flow node IDs.

• variable-node.ts: Uses $createVariableNode from this module to generate specialized variable text nodes inside Lexical.

• constant.ts: Uses ProgrammaticTag for tagging editor updates programmatically.

• CSS (index.css): Styles the typeahead dropdown and options.

Mermaid Component Diagram

componentDiagram
    component VariablePickerMenuPlugin {
        +value?: string
        +onQueryChange(query: string)
        +onSelectOption(option, node, closeMenu)
        +parseTextToVariableNodes(text)
    }
    component VariablePickerMenuItem {
        +index: number
        +option: VariableOption
        +selectOptionAndCleanUp(option)
    }
    component VariableOption {
        +label: ReactElement | string
        +title: string
        +options: VariableInnerOption[]
    }
    component VariableInnerOption {
        +label: string
        +value: string
    }
    VariablePickerMenuPlugin --> VariableOption : uses
    VariableOption *-- VariableInnerOption : contains
    VariablePickerMenuPlugin --> VariablePickerMenuItem : renders
    VariablePickerMenuItem --> VariableInnerOption : renders items

Summary

The variable-picker-plugin.tsx file implements a powerful and flexible variable insertion UI for the Lexical text editor using React. It leverages Lexical’s plugin infrastructure to provide an intuitive slash-triggered typeahead menu for selecting variables, supports dynamic option lists, and ensures seamless integration of variable nodes into rich text content with custom parsing capabilities. This makes it a key component for any application that requires embedding dynamic variables or tokens into user-editable text flows.