variable-node.tsx

Overview

The variable-node.tsx file defines a custom Lexical editor node representing a "variable" element within rich text content. This node extends the DecoratorNode class from the Lexical framework to provide a specialized inline component that visually displays a variable label, optionally prefixed by a parent label and an icon. It facilitates the embedding of variable references in an editable text area, offering both a textual representation and a React-rendered visual decoration.

This file primarily supports the rendering and manipulation of variable nodes inside a Lexical editor instance, allowing for consistent display and interaction with variable placeholders in user-generated content or flow definitions.

Detailed Explanation

Imports

BeginId: A constant string prefix imported from the flow page constants.
DecoratorNode, LexicalNode, NodeKey: Core Lexical editor classes for custom node creation and type-checking.
ReactNode: Type from React representing any React-renderable element.

Class: `VariableNode`

VariableNode extends DecoratorNode<ReactNode>, meaning it leverages Lexical's decorator node functionality to embed React components inline within the editor content.

Properties

Property	Type	Description
`__value`	`string`	The internal value or identifier of the variable.
`__label`	`string`	The display label text for the variable.
`key`	`NodeKey` (optional)	Unique key identifier for the node instance.
`__parentLabel`	`string	ReactNode` (optional)
`__icon`	`ReactNode` (optional)	Optional icon shown alongside the parent label.

Static Methods

getType(): string
Returns the string "variable" identifying the node type. This is required by Lexical for node registration and serialization.
Usage:
```
const type = VariableNode.getType(); // "variable"
```
clone(node: VariableNode): VariableNode
Creates a new VariableNode instance by copying an existing one, preserving all its properties.
Parameters:
- node: The existing VariableNode instance to clone.
Returns:
A new VariableNode instance with identical data.
Usage:
```
const newNode = VariableNode.clone(existingNode);
```

Constructor

constructor(
  value: string,
  label: string,
  key?: NodeKey,
  parent?: string | ReactNode,
  icon?: ReactNode,
)

Creates a new VariableNode.

value: The variable's internal identifier.
label: The visible text label for the variable.
key: Optional Lexical node key.
parent: Optional parent label or React element providing contextual information.
icon: Optional React element icon to display before the parent label.

Instance Methods

createDOM(): HTMLElement
Creates and returns the DOM element representing this node in the editor.
- Creates a <span> element with a margin-right class (mr-1).
- This element acts as a container for the React decoration.
Returns:
HTMLElement - The DOM element for this node.
updateDOM(): false
Indicates that the DOM does not require updates when node properties change, as React handles rendering.
Returns:
false - Signals no DOM update.
decorate(): ReactNode
Returns the React element to render as the node's decoration inside the editor.
Behavior:
- If __parentLabel exists, it renders a flex container combining:
  - The optional icon (__icon),
  - The parent label (__parentLabel),
  - A separator slash /,
  - The variable label (__label) styled in blue text.
- Otherwise, it renders just the variable label in blue text.
- The whole decoration is wrapped in a styled <div> with background, padding, rounded corners, and inline-flex alignment.
Returns:
A ReactNode representing the styled variable display.
getTextContent(): string
Returns a text representation of the variable for serialization or plain text export.
Format:
{variable_value}
Returns:
string - The variable value wrapped in curly braces.

Functions

`$createVariableNode`

function $createVariableNode(
  value: string,
  label: string,
  parentLabel: string | ReactNode,
  icon?: ReactNode,
): VariableNode

Factory function to create a new VariableNode instance.

Parameters:
- value: Variable internal value.
- label: Display label.
- parentLabel: Parent context label or React element.
- icon: Optional icon React element.
Returns:
A new VariableNode.

Usage:

const node = $createVariableNode('var1', 'Variable 1', 'Parent Group', <Icon />);

`$isVariableNode`

function $isVariableNode(
  node: LexicalNode | null | undefined,
): node is VariableNode

Type guard function to check if a given Lexical node is an instance of VariableNode.

Parameters:
- node: The LexicalNode to check.
Returns:
true if node is a VariableNode; otherwise false.

Usage:

if ($isVariableNode(node)) {
  // node is typed as VariableNode here
}

Implementation Details

The node class extends DecoratorNode to leverage React rendering capabilities inside Lexical editor content.
The decorate() method provides rich UI for variables with optional parent label and icon, enhancing UX.
The DOM node is minimal (<span>) and styling is applied via React components, allowing dynamic updates and theming.
The node is identified by the static type "variable", which aligns with Lexical's serialization and deserialization.
Cloning supports editor operations like copy-paste or undo/redo.
The text content serialization wraps the variable's value in curly braces, supporting plain text export or processing.

Interaction with Other Parts of the System

Flow Page Constants: Uses BeginId from @/pages/flow/constant as a prefix, implying integration with flow-related identifiers.
Lexical Editor: Interacts deeply with Lexical's node system, enabling custom inline variable nodes inside the rich text editor.
React Components: Uses ReactNode for rendering icons and labels, allowing seamless UI composition.
This file likely integrates into a larger flow or form editor where variables are dynamically inserted and displayed.
Other parts of the system might create VariableNode instances via $createVariableNode and check node types with $isVariableNode.

Usage Example

import { $createVariableNode, $isVariableNode } from './variable-node';

// Creating a variable node
const variableNode = $createVariableNode(
  'userName',
  'User Name',
  'User Info',
  <UserIcon />
);

// Checking node type
if ($isVariableNode(variableNode)) {
  console.log(variableNode.getTextContent()); // Outputs: {userName}
}

Visual Diagram: Component Interaction

classDiagram
    class VariableNode {
        -__value: string
        -__label: string
        -key?: NodeKey
        -__parentLabel?: string | ReactNode
        -__icon?: ReactNode
        +static getType(): string
        +static clone(node: VariableNode): VariableNode
        +constructor(value: string, label: string, key?: NodeKey, parent?: string | ReactNode, icon?: ReactNode)
        +createDOM(): HTMLElement
        +updateDOM(): false
        +decorate(): ReactNode
        +getTextContent(): string
    }

    VariableNode ..> DecoratorNode : extends
    VariableNode ..> ReactNode : uses in properties (__icon, __parentLabel)
    DecoratorNode ..|> LexicalNode

    class $createVariableNode {
        +function(value: string, label: string, parentLabel: string | ReactNode, icon?: ReactNode): VariableNode
    }

    class $isVariableNode {
        +function(node: LexicalNode | null | undefined): node is VariableNode
    }

    $createVariableNode --> VariableNode : creates
    $isVariableNode --> VariableNode : type guard

Summary

The variable-node.tsx file provides a specialized Lexical editor node class VariableNode and helper functions to create and identify such nodes. It supports rich visual decoration of variables with optional parent context and icons, enabling enhanced user interfaces for variable placeholders in flow or text editors. The design leverages React for rendering and Lexical for editor integration, forming a critical piece in the system's variable management and display functionality.