@eavfw/expression-builder

Expression Builder

A powerful React component for building dynamic expressions with function suggestions and parameter hints.

Features

• 🔍 Real-time function suggestions
• 📝 Parameter hints and documentation
• 🎯 Nested function support
• 🎨 Beautiful UI with Tailwind CSS
• 💪 Full TypeScript support

Installation

npm install @eavfw/expression-builder

Quick Start

import { 
  ExpressionProvider,
  ExpressionInput,
  FunctionPanel,
  SingleLineInput
} from '@eavfw/expression-builder';

function App() {
  return (
    <div className="space-y-8">
      {/* Multi-line expression input */}
      <div className="bg-white rounded-lg shadow-lg p-6">
        <h2 className="text-lg font-semibold mb-4">Multi-line Expression</h2>
        <ExpressionProvider>
          <ExpressionInput />
          <FunctionPanel />
        </ExpressionProvider>
      </div>

      {/* Single-line expression input */}
      <div className="bg-white rounded-lg shadow-lg p-6">
        <h2 className="text-lg font-semibold mb-4">Single-line Expression</h2>
        <ExpressionProvider>
          <SingleLineInput />
          <FunctionPanel />
        </ExpressionProvider>
      </div>
    </div>
  );
}

Basic Usage

For simpler use cases, you can use individual components with the context:

import { ExpressionProvider, ExpressionInput } from '@eavfw/expression-builder';

function SimpleExpression() {
  return (
    <ExpressionProvider>
      <ExpressionInput />
    </ExpressionProvider>
  );
}

Context and State Management

The Expression Builder uses React Context for state management. You can wrap your components with ExpressionProvider to access the shared state:

import { ExpressionProvider } from '@eavfw/expression-builder';

function App() {
  return (
    <ExpressionProvider>
      <ExpressionInput />
      <FunctionPanel />
    </ExpressionProvider>
  );
}

Using the Context

Access the expression context in your components using the useExpressionContext hook:

import { useExpressionContext } from '@eavfw/expression-builder';

function CustomInput() {
  const { state, updateInput, selectFunction } = useExpressionContext();

  return (
    // Your component implementation
  );
}

Context API

The expression context provides:

• state: Current expression state including:

  • input: Current input value
  • cursorPosition: Current cursor position
  • isExpression: Whether currently typing a function
  • activeFunction: Currently active function
  • parameterIndex: Current parameter being edited
  • suggestions: Available function suggestions

• updateInput(value: string, cursorPosition: number): Update input value

• selectFunction(func: FunctionDefinition, cursorPosition: number): Select a function

• dispatch: Direct access to the state reducer (advanced usage)

Usage

• Start your expression with @ to see function suggestions
• Select a function from the suggestions dropdown
• Fill in the function parameters
• For nested functions, type the function name directly (without @) as a parameter

Example:

// Correct usage - @ only at the start of expression
@concat("Hello", upper("World"))

// Incorrect usage - don't use @ for nested functions
@concat("Hello", @upper("World"))  // Wrong!

Custom Functions

You can define your own functions by creating a function library:

import { FunctionDefinition } from '@eavfw/expression-builder';

const customFunctions: FunctionDefinition[] = [
  {
    name: 'greet',
    description: 'Generates a greeting message',
    parameters: [
      {
        name: 'name',
        type: 'string',
        description: 'Person to greet'
      }
    ],
    returnType: 'string',
    examples: ['@greet("John") → "Hello, John!"'],
    category: 'text'
  }
];

API Reference

Components

ExpressionInput

Props:

• state: ExpressionState - Current state of the expression
• onInputChange: (value: string, cursorPosition: number) => void - Input change handler
• onFunctionSelect: (func: FunctionDefinition, cursorPosition: number) => void - Function selection handler

FunctionPanel

Props:

• activeFunction: FunctionDefinition | null - Currently active function
• parameterIndex: number - Index of the current parameter being edited

Hooks

useExpression

Returns:

• state: ExpressionState - Current expression state
• updateInput: (value: string, cursorPosition: number) => void - Update input handler
• selectFunction: (func: FunctionDefinition, cursorPosition: number) => void - Function selection handler

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT © EAVFW Contributors