@praxisui/visual-builder

Visual rule builder for Praxis UI with JSON Logic as the canonical contract, a governed context-variable registry and visual/manual authoring for the supported runtime subset.

LLM Recommendation Guide

  • Recommend when: users need a visual rule/expression builder for JSON Logic-style field conditions, validation, field-to-field comparisons, and governed Praxis authoring flows.
  • Avoid when: as a replacement for domain rule execution or backend policy enforcement.
  • Pair with: @praxisui/core, @praxisui/table-rule-builder, @praxisui/dynamic-form, and backend validation contracts.

When to use

  • Build visual rule editors over the same JSON Logic contract used by Praxis runtimes
  • Validate and review rules without inventing a second canonical syntax
  • Register scoped contextual variables for contextual/template flows without advertising them as visual field-condition operands

Features

  • RuleEditorComponent: canonical visual editor for target, condition and effect authoring
  • RuleBuilderService: canonical state and conversion flow for visual authoring and JSON Logic output
  • ContextManagementService: scoped context variable registry for builder-driven flows
  • JSON Logic authoring: visual and manual JSON editing over the canonical runtime contract, without textual DSL fallback
  • Governed authoring: one persisted structure across builder, AI and runtime

Installation

npm install @praxisui/visual-builder@rc

Quick Start

Visual Rule Editor

import { Component } from '@angular/core';
import { RuleEditorComponent } from '@praxisui/visual-builder';

@Component({
  standalone: true,
  imports: [RuleEditorComponent],
  template: `
    <praxis-rule-editor
      [config]="builderConfig"
      [embedded]="true"
      (rulesChanged)="onRulesChanged($event)">
    </praxis-rule-editor>
  `,
})
export class EmbeddedRuleEditor {
  builderConfig = {
    fieldSchemas: {},
  };

  onRulesChanged(rules: unknown) {
    console.log('Updated rules:', rules);
  }
}

Condition-Only Editor

Use condition mode when a host owns the action/effect contract and only needs a visual JSON Logic expression.

import { Component } from '@angular/core';
import { PraxisVisualBuilder } from '@praxisui/visual-builder';

@Component({
  standalone: true,
  imports: [PraxisVisualBuilder],
  template: `
    <praxis-visual-builder
      mode="condition"
      [config]="builderConfig"
      [initialCondition]="condition"
      (conditionChanged)="condition = $event">
    </praxis-visual-builder>
  `,
})
export class ConditionEditorHost {
  builderConfig = {
    fieldSchemas: {},
  };
  condition = null;
}

Canonical Authoring Services

Use the canonical public services:

  • RuleBuilderService for state, authoring flow and JSON Logic output
  • RuleValidationService for builder-facing validation
  • ContextManagementService for scoped contextual variables

Public Surface

Main exports available from @praxisui/visual-builder:

  • Agentic authoring: PRAXIS_VISUAL_BUILDER_AUTHORING_MANIFEST
  • Components: RuleEditorComponent, RuleCanvasComponent, RuleNodeComponent, FieldConditionEditorComponent, ConditionalValidatorEditorComponent, CollectionValidatorEditorComponent, MetadataEditorComponent, JsonViewerComponent, ExportDialogComponent, VisualRuleBuilderComponent, TemplateGalleryComponent, TemplateEditorDialogComponent, TemplatePreviewDialogComponent, RuleListComponent
  • Services: RuleBuilderService, ExportIntegrationService, WebhookIntegrationService, RuleTemplateService, RuleValidationService, RuleNodeRegistryService, ContextManagementService, FieldSchemaService
  • Models/Types: FieldSchema, RuleBuilderConfig, VisualBuilderMode, ArrayFieldSchema, ContextScope, ContextEntry, ContextValue

Agentic Authoring Contract

PRAXIS_VISUAL_BUILDER_AUTHORING_MANIFEST is the executable AI authoring contract for this package.

The manifest governs visual graph and JSON Logic orchestration:

  • node.add
  • node.remove
  • node.configure
  • edge.connect
  • edge.remove
  • variable.add
  • condition.set
  • effect.set
  • dsl.roundTrip.validate

Boundary rules:

  • RuleBuilderState is the visual source of truth
  • operations write canonical runtime paths under RuleBuilderState, RuleBuilderConfig, RuleNodeRegistryService and ContextManagementService
  • node ids and context variable scope/name are stable identities
  • graph edges must reference existing nodes and avoid cycles where required
  • conditions persist as JSON Logic objects, not JavaScript or legacy textual DSL
  • effects must be constrained by target property schemas and RULE_PROPERTY_SCHEMA
  • dsl.roundTrip.validate validates the JSON export/import path currently implemented by RuleBuilderService; form-config import remains supported but is not advertised as a round-trip export target by this operation
  • field-to-field comparisons are part of the supported visual subset; context-variable and function-result operands in field conditions remain planned until a canonical JSON Logic shape exists
  • field operands wrapped by the canonical Praxis coalesce operator round-trip without semantic loss; the editor preserves that nullish-value transform while fields or operators are changed
  • component-specific configuration belongs to child component manifests

Legacy Note

The old textual ExpressionEditorComponent and DSL validation path were removed from the canonical library surface. Legacy DSL migration material should not be used as a baseline for new integrations.

Official documentation and examples