@masterteam/formula-builder

A powerful Formula Builder component for Angular 20+ with Tailwind CSS 4.

Features

• ✅ Visual Block Editor - Make.com-inspired formula editing experience
• ✅ 42+ Built-in Functions - Math, Logic, Aggregation, Hierarchy, Date, String
• ✅ Real-time Validation - Syntax checking with error highlighting
• ✅ Context-aware Autocomplete - Smart suggestions as you type
• ✅ Drag & Drop - Visual block manipulation with Angular CDK
• ✅ Property References - @PropertyKey, *.PropertyKey, $.Parent.PropertyKey

Installation

pnpm add @masterteam/formula-builder

Usage

import { FormulaBuilder, type FormulaBuilderValue } from '@masterteam/formula-builder';
import { FormsModule } from '@angular/forms';

@Component({
  imports: [FormsModule, FormulaBuilder],
  template: `
    <mt-formula-builder
      [(ngModel)]="formulaState"
      [levelSchemaId]="levelSchemaId"
      (validationChange)="onValidation($event)"
    />
  `
})
export class MyComponent {
  formulaState: FormulaBuilderValue = { expression: '', builder: [] };
  levelSchemaId = 6;
}

API

Inputs

| Input | Type | Description | |-------|------|-------------| | ngModel / formControl | FormulaBuilderValue | Form value { expression, builder } (builder is token JSON array) | | propertiesByPath | Record<string, { key: string; name?: string }[]> | Scoped properties (optional) | | levelSchemaId | number | Level schema ID for validation context | | templateId | number | Template ID for validation context | | expectedType | string | Type the result must fit — the owning property's view type (Number, Percentage, Currency, Date, DateTime, Time, Checkbox, Text…). Sent as expectedType to formulas/validate; a mismatch comes back Invalid ("This formula returns Text but the property type is Number."). Changing it re-validates. Send only a type the backend can check: any other one fails as "Unsupported expected formula type" | | placeholder | string | Placeholder text | | hideToolbar | boolean | Hide the top toolbar | | hideStatusBar | boolean | Hide the status bar | | toolbarTabs | ToolbarTab[] | Visible toolbar tabs, e.g. ['functions', 'operators'] | | functionCategories | FunctionCategoryGroup[] | Optional host-owned catalog; overrides API context functions when provided. Without it or a context, a current-only builder (isProcessBuilder) lists the backend's InlineCurrentOnly catalog (formulas/builder/functions), any other builder a validation fallback | | operators | OperatorDefinition[] | Operators shown in the toolbar; defaults to the shared formula operator catalog | | codeOnly | boolean | Force code mode and hide the mode toggle | | builderOnly | boolean | Force block builder mode and hide the code-mode toggle | | valueMode | 'object' \| 'expression' | Emit { expression, builder } by default, or emit the expression string for legacy string contracts | | isProcessBuilder | boolean | Use Process Builder current-only Formula Engine endpoints |

Builder Mode Display Contract

Lookup/status value chips keep the executable literal as the stable backend key and use the block display value only for the friendly label. Builder-only hosts can show readable labels without changing the serialized formula expression.

Switching modes and Boolean conditions

Visual and code editing are available by default. The Code mode toggle can be turned off even while Monaco is loading. The shared code editor displays loading feedback and the current expression, preserves it on failure, and offers Retry. Switching modes without editing retains friendly value labels.

Quick Insert recognizes unquoted true and false as Boolean values. Use @Current::needs_approval == true for a checkbox condition; "true" is a string and remains a string. The same typed insert path is used in both modes.

See the formula integration guide and formula showcase for workflow and property examples and their API contracts.

Outputs

| Output | Type | Description | |--------|------|-------------| | validationChange | ValidationResult | Emits validation results | | tokensChange | FormulaToken[] | Emits when tokens change |

Development

pnpm build:formula-builder