@goplasmatic/datalogic-ui

A React component library for visualizing, debugging, and editing JSONLogic expressions as interactive node-based flow diagrams.

This is the React surface of the datalogic-rs monorepo. It consumes the WASM binding (@goplasmatic/datalogic-wasm) for evaluation and tracing — for the engine itself and the cross-runtime overview, see the repo README.

Features

• Visual representation of JSONLogic expressions as flow diagrams
• Support for all standard JSONLogic operators (logical, comparison, arithmetic, string, array, control flow, datetime, error handling)
• Tree-based automatic layout using @dagrejs/dagre
• Prop-based modes: read-only visualization, debugging with step-through trace, and full visual editing
• Editing mode with node selection, properties panel, context menus, and undo/redo
• Templating mode for JSON templates with embedded JSONLogic
• Built-in WASM-based JSONLogic evaluation with execution tracing
• Light/dark theme support with system preference detection

Installation

npm install @goplasmatic/datalogic-ui @xyflow/react

Peer dependencies: React 18+ or 19+, @xyflow/react 12+

Quick Start

import '@xyflow/react/dist/style.css';
import '@goplasmatic/datalogic-ui/styles.css';

import { DataLogicEditor } from '@goplasmatic/datalogic-ui';

function App() {
  const expression = {
    "and": [
      { ">": [{ "var": "age" }, 18] },
      { "==": [{ "var": "status" }, "active"] }
    ]
  };

  return <DataLogicEditor value={expression} />;
}

Usage Modes

The editor behavior is controlled by props rather than a mode enum. Different combinations of props enable different functionality:

Read-only (default)

Simply render a JSONLogic expression as a flow diagram:

<DataLogicEditor value={expression} />

With Debugger

Provide data to enable debugger controls with step-through execution trace:

<DataLogicEditor
  value={expression}
  data={{ age: 25, status: "active" }}
/>

Editable

Enable full visual editing with node selection, properties panel, context menus, and undo/redo:

<DataLogicEditor
  value={expression}
  onChange={setExpression}
  editable
/>

Editable + Debugger

Combine editing with live debugging:

<DataLogicEditor
  value={expression}
  onChange={setExpression}
  data={{ age: 25, status: "active" }}
  editable
/>

Props

Prop	Type	Default	Description
value	JsonLogicValue | null	required	JSONLogic expression to render
onChange	(expr: JsonLogicValue | null) => void	-	Callback when expression changes (only when editable is true)
data	unknown	-	Data context for evaluation. When provided, debugger controls become available
theme	'light' | 'dark'	system	Theme override. If not provided, uses system preference
className	string	-	Additional CSS class
templating	boolean	false	Enable templating mode: multi-key objects and arrays compile to output-shaping templates with embedded JSONLogic
onTemplatingChange	(value: boolean) => void	-	Callback when templating mode changes (from toolbar checkbox)
editable	boolean	false	Enable editing: node selection, properties panel, context menus, undo/redo

Exports

Component

import { DataLogicEditor } from '@goplasmatic/datalogic-ui';

Types

import type {
  DataLogicEditorProps,
  JsonLogicValue,
  LogicNode,
  LogicEdge,
  LogicNodeData,
  OperatorNodeData,
  VariableNodeData,
  LiteralNodeData,
  NodeEvaluationResult,
  EvaluationResultsMap,
  OperatorCategory,
} from '@goplasmatic/datalogic-ui';

Constants (for customization)

import { OPERATORS, CATEGORY_COLORS } from '@goplasmatic/datalogic-ui';

Utilities (for advanced use)

import { jsonLogicToNodes, applyTreeLayout } from '@goplasmatic/datalogic-ui';

Styling

The component requires two CSS imports:

// React Flow base styles
import '@xyflow/react/dist/style.css';

// DataLogicEditor styles
import '@goplasmatic/datalogic-ui/styles.css';

The component respects the data-theme attribute on parent elements for theming, or you can override with the theme prop.

Development

This package lives at ui/ in the datalogic-rs monorepo. It depends on a locally-built @goplasmatic/datalogic-wasm WASM bundle — see DEVELOPMENT.md for the full link/install dance. Day-to-day, from the repo root:

cd ui
npm install       # install dependencies
npm run dev       # start the dev playground
npm run build:lib # build the publishable library bundle
npm run lint      # run ESLint

Architecture

The main component is DataLogicEditor which:

1. Accepts a value prop (JSONLogic expression) and renders it as a flow diagram
2. Uses React Flow (@xyflow/react) for the node canvas
3. Internally loads WASM module for JSONLogic evaluation and execution tracing
4. Supports read-only, debugger, and editable modes via props

Data Flow

1. JSONLogic Input → useLogicEditor hook parses the expression
2. Conversion → jsonLogicToNodes() transforms JSONLogic to visual nodes/edges
3. Layout → applyTreeLayout() positions nodes in a tree structure
4. Rendering → React Flow renders with custom node types

Node Types

• OperatorNode (UnifiedOperatorNode): Renders all operators with cell-based argument display (and, or, if, var, val, ==, +, etc.)
• LiteralNode: Renders primitive values (strings, numbers, booleans, null)
• StructureNode: Renders JSON objects/arrays in templating mode

Tech Stack

• React 18/19
• TypeScript
• Vite
• React Flow (@xyflow/react)
• @dagrejs/dagre (graph layout)
• lucide-react (icons)
• @msgpack/msgpack (data serialization)
• fflate (compression)
• @goplasmatic/datalogic-wasm (bundled, for WASM evaluation)

Documentation

For complete documentation including all props, customization options, and advanced usage, see the full documentation.

Learn more

• Repo README — cross-runtime overview, all binding READMEs
• WASM binding README — @goplasmatic/datalogic-wasm, the JS/TS engine this UI consumes
• Rust crate README — engine design, the 5-tier API model
• Full documentation
• Online playground

License

Apache-2.0