@aranzatech/diagrams-bpmn

BPMN 2.0 building blocks for the Aranza diagram ecosystem. This package owns BPMN-specific visual components, element metadata, BPMN modeling helpers, XML import/export and preview token simulation.

It is intentionally not responsible for execution-engine communication. Flowable integration belongs in a future wrapper package or in the consuming app backend.

Public Subpaths

import { BPMN_NODE_TYPES } from "@aranzatech/diagrams-bpmn/nodes";
import { BPMN_EDGE_TYPES } from "@aranzatech/diagrams-bpmn/edges";
import { BPMN_ELEMENT_CATALOG } from "@aranzatech/diagrams-bpmn/elements";
import { parseBpmnXml, serializeBpmnXml } from "@aranzatech/diagrams-bpmn/xml";
import {
  createBpmnNodeCommand,
  replaceBpmnNodeCommand,
  serializeBpmnDiagram,
} from "@aranzatech/diagrams-bpmn/modeling";
import { createSimulation } from "@aranzatech/diagrams-bpmn/simulation";

Scope

• BPMN visual node and edge renderers for ReactFlow.
• BPMN element catalog and guards.
• BPMN XML import/export through bpmn-moddle.
• BPMN modeling commands and interaction rules on top of diagrams-core.
• Client-side preview token simulation.

Out Of Scope

• Flowable REST/backend communication.
• BPMN business validation rules. Those belong in @aranzatech/flowslint.
• Full execution semantics.

Coverage Matrix

| Area | Status | Notes | |---|---:|---| | Events | Partial | Start, end, intermediate catch/throw, boundary; common triggers rendered/imported. | | Tasks | Partial | Task variants and call activity rendered; advanced task semantics still need richer XML mapping. | | Gateways | Good | Exclusive, inclusive, parallel, event-based and complex rendered. | | Containers | Partial | Pool, lane, subprocess, transaction, event subprocess and ad-hoc subprocess rendered; lane resizing/modeling still needs depth. | | Artifacts | Partial | Text annotation and group rendered; association semantics are basic. | | Data | Partial | Data object/input/output/store and refs rendered; full item definitions/data states pending. | | Conversation | Partial | Conversation nodes and links rendered; full conversation model pending. | | Choreography | Partial | Choreography nodes rendered; participant semantics are lightweight. | | XML import/export | Partial | Basic BPMN + DI, default flows, boundary attachment, docs and relative child coordinates; full lossless roundtrip pending. | | Modeling | Growing | Commands and rules for create/connect/attach/delete/replace/resize/reparent/copy/paste; palette/context-pad/auto-place can build on this. | | Simulation | Preview | Useful design-time token simulation, not an execution engine. |

Modeling Example

import { createCommandStackState } from "@aranzatech/diagrams-core/commands";
import {
  createBpmnNodeCommand,
  connectBpmnCommand,
  replaceBpmnNodeCommand,
  runBpmnCommands,
  runBpmnCommand,
} from "@aranzatech/diagrams-bpmn/modeling";

let stack = createCommandStackState({ nodes: [], edges: [] });

stack = runBpmnCommand(
  stack,
  createBpmnNodeCommand({
    id: "task_1",
    elementType: "Task",
    position: { x: 100, y: 100 },
    label: "Review request",
  }),
);

stack = runBpmnCommand(
  stack,
  connectBpmnCommand({
    source: "start_1",
    target: "task_1",
  }),
);

stack = runBpmnCommands(
  stack,
  [
    replaceBpmnNodeCommand({
      id: "task_1",
      elementType: "UserTask",
      label: "Human review",
    }),
  ],
  { id: "review-as-user-task" },
);

BPMN Diagram Document Example

import {
  deserializeBpmnDiagram,
  serializeBpmnDiagram,
} from "@aranzatech/diagrams-bpmn/modeling";

const json = serializeBpmnDiagram(stack.current, {
  metadata: { source: "designer" },
});

const restored = deserializeBpmnDiagram(json);

Road To Stable

• Expand XML to preserve more BPMN semantics losslessly.
• Add real-world XML fixtures from bpmn.io/Camunda/Flowable modelers.
• Add palette/context-pad and auto-place commands on top of the current modeling API.
• Add robust lane/pool resize and reparent behavior.
• Move engine-specific extensions to a dedicated package.