sysml-reactflow

Pure SysML v2.0 building blocks for React Flow. This package implements the OMG Systems Modeling Language v2.0 specification with comprehensive support for all core metaclasses, relationships, and diagram types.

🎯 Zero SysML v1 legacy - All deprecated SysML v1 elements have been removed for clean v2.0 compliance.

Features

• ✅ Full SysML v2.0 Compliance - Supports 60+ element types covering all major SysML v2 metaclasses
• 🧱 Comprehensive Node Renderers - Prebuilt renderers for definitions, usages, behaviors, requirements, cases, and metadata
• 🔗 Complete Relationship Support - 30+ edge types including typing, specialization, feature relationships, and more
• 🛠️ Type-Safe Factories - Strongly typed factory functions for all SysML v2 elements
• 🗺️ SysML v2 Viewpoints - Built-in viewpoint system for diagram materialization
• 🎨 Professional Styling - IBM Plex-based design with Definition/Usage badges and status indicators
• 🤖 Automatic Layout - Powered by elkjs with optimized algorithms for each diagram type (layered, force-directed, tree, orthogonal, sequence)

SysML v2.0 Element Coverage

Structural Elements (16 types):

• ✅ Part Definition/Usage
• ✅ Attribute Definition/Usage
• ✅ Port Definition/Usage
• ✅ Item Definition/Usage
• ✅ Connection Definition/Usage
• ✅ Interface Definition/Usage
• ✅ Allocation Definition/Usage
• ✅ Reference Usage
• ✅ Occurrence Definition/Usage

Behavioral Elements (14 types):

• ✅ Action Definition/Usage
• ✅ Activity
• ✅ Calculation Definition/Usage
• ✅ Perform Action, Send Action, Accept Action
• ✅ Assignment Action
• ✅ If Action, For Loop, While Loop
• ✅ State Definition/Usage, Transition, Exhibit State

Requirements & Cases (12 types):

• ✅ Requirement Definition/Usage
• ✅ Constraint Definition/Usage
• ✅ Verification Case Definition/Usage
• ✅ Analysis Case Definition/Usage
• ✅ Use Case Definition/Usage
• ✅ Concern Definition/Usage

Organizational & Metadata (8 types):

• ✅ Package, Library Package
• ✅ Interaction, Sequence Lifeline
• ✅ Metadata Definition/Usage
• ✅ Comment, Documentation

Relationships (30+ types):

• Type relationships: Specialization, Conjugation, Feature Typing, Subsetting, Redefinition
• Dependency relationships: Satisfy, Verify, Refine, Allocate
• Flow relationships: Control Flow, Item Flow, Action Flow, Flow Connection
• Structure relationships: Feature Membership, Owning Membership, Variant Membership
• Connectors: Binding Connector, Succession
• Use case: Include, Extend
• State: Transition
• Interaction: Message, Succession

Diagram coverage

• BDD & IBD: Full Definition/Usage semantics with compartments, ports, and attributes
• SysML v2 Definition/Usage Pattern: Proper modeling of all definition/usage pairs with typing relationships
• Use Cases: Use case definitions/usages with include/extend/actor support
• State Machines: State definitions, usages, transitions with guards/triggers/effects
• Sequence Diagrams: Lifelines, interactions, and synchronous/asynchronous/return messages
• Activity Diagrams: Actions, control nodes (fork/join/decision/merge), control flows
• Requirement Diagrams: Requirement definitions/usages with satisfy/verify/refine relationships
• Analysis & Verification: Full support for verification cases and analysis cases
• Parametric & Calculations: Constraint and calculation definitions/usages

SysML v2 viewpoints

SysML v2 diagrams are view specifications. The library ships with reusable viewpoints that materialize the appropriate nodes/edges following SysML v2 semantics:

import {
  SysMLDiagram,
  structuralDefinitionViewpoint,
  type SysMLModel
} from 'sysml-reactflow';

const model: SysMLModel = { nodes: specs, relationships };

<SysMLDiagram model={model} viewpoint={structuralDefinitionViewpoint} />;

Behind the scenes the viewpoint filters the SysML element kinds, applies the correct definition/usage semantics, and renders the React Flow scene so you get a true SysML v2 environment.

Installation

npm install sysml-reactflow react react-dom reactflow

Quick start

import { ReactFlowProvider } from 'reactflow';
import {
  SysMLDiagram,
  createNodesFromSpecs,
  createEdgesFromRelationships
} from 'sysml-reactflow';

const nodes = createNodesFromSpecs([
  {
    kind: 'requirement-usage',
    spec: {
      id: 'REQ-101',
      name: 'Thermal Compliance',
      text: 'The payload shall remain between 0°C and 40°C.',
      status: 'reviewed'
    }
  },
  {
    kind: 'part-definition',
    spec: {
      id: 'PART-42',
      name: 'ThermalController',
      description: 'Regulates loop temp.',
      attributes: [
        { name: 'pump', type: 'Pump', multiplicity: '[2]' }
      ],
      ports: [
        { name: 'coolantIn', type: 'Coolant', direction: 'in' },
        { name: 'coolantOut', type: 'Coolant', direction: 'out' }
      ]
    }
  }
]);

const edges = createEdgesFromRelationships([
  { id: 'edge-1', type: 'satisfy', source: 'PART-42', target: 'REQ-101', label: 'satisfy' }
]);

export function Example() {
  return (
    <ReactFlowProvider>
      <div style={{ width: '100%', height: 520 }}>
        <SysMLDiagram nodes={nodes} edges={edges} />
      </div>
    </ReactFlowProvider>
  );
}

Automatic Layout

Apply automatic graph layout with optimized algorithms for different diagram types:

import { layoutAndRouteFromSpecs } from 'sysml-reactflow';

const specs = [...];
const relationships = [...];

const { nodes: layoutedNodes, edges: layoutedEdges } = await layoutAndRouteFromSpecs(
  specs,
  relationships,
  'requirements',
  { measure: true }
);

<SysMLDiagram nodes={layoutedNodes} edges={layoutedEdges} fitView />

The library supports multiple layout algorithms:

• Layered (Hierarchical) - For BDD, requirements, packages, activities
• Force-Directed - For state machines, use cases
• Tree - For package hierarchies
• Box (Orthogonal) - For IBD, component compositions
• Sequence - For sequence diagram lifelines

See Layout Guide for detailed documentation and examples.

API surface

Components

• SysMLDiagram: Thin wrapper over ReactFlow that registers all SysML v2 node/edge types with recommended controls
• sysmlNodeTypes, sysmlEdgeTypes: Complete registries with 60+ node types and 30+ edge types

Factory Functions

The library exports 60+ factory functions for creating SysML v2 elements:

Structural Element Factories:

• createAttributeDefinitionNode, createAttributeUsageNode
• createConnectionDefinitionNode, createConnectionUsageNode
• createInterfaceDefinitionNode, createInterfaceUsageNode
• createAllocationDefinitionNode, createAllocationUsageNode
• createReferenceUsageNode
• createOccurrenceDefinitionNode, createOccurrenceUsageNode
• And more...

Behavioral Element Factories:

• createCalculationDefinitionNode, createCalculationUsageNode
• createPerformActionNode, createSendActionNode, createAcceptActionNode
• createAssignmentActionNode, createIfActionNode, createForLoopActionNode, createWhileLoopActionNode
• createStateDefinitionNode, createStateUsageNode, createTransitionUsageNode
• And more...

Requirements & Cases Factories:

• createRequirementDefinitionNode, createRequirementUsageNode
• createConstraintDefinitionNode, createConstraintUsageNode
• createVerificationCaseDefinitionNode, createVerificationCaseUsageNode
• createAnalysisCaseDefinitionNode, createAnalysisCaseUsageNode
• createUseCaseDefinitionNode, createUseCaseUsageNode
• createConcernDefinitionNode, createConcernUsageNode

Organizational & Metadata Factories:

• createPackageNode, createLibraryPackageNode
• createInteractionNode
• createMetadataDefinitionNode, createMetadataUsageNode
• createCommentNode, createDocumentationNode

Batch Helpers:

• createNodesFromSpecs – batch creation with auto-positioning
• createEdgesFromRelationships – batch edge creation

All factory functions are fully typed with TypeScript, providing IDE autocomplete for all SysML v2 properties.

Example catalog

See examples/basic.tsx for a runnable snippet that assembles a small SysML allocation chain. Drop it into a Vite/Next playground to see the styling in action.

Additional examples:

• examples/state-machine.tsx - Complete state machine with transitions, guards, and actions
• examples/sequence-diagram.tsx - Interaction sequences with lifelines and messages
• examples/automatic-layout.tsx - Automatic layout for different diagram types with interactive controls
• examples/system-decomposition.tsx - Three-level decomposition of system, subsystem, and component parts
• examples/component-interfaces.tsx - Component-level interface view with shared buses and flows
• examples/requirements-schema.tsx - Requirement, constraint, analysis, and verification relationships
• examples/functional-flow.tsx - Functional activity flow with sequential and control links

Documentation

Comprehensive guides for specific features and diagram types:

• Automatic Layout - Complete guide to automatic graph layout with elkjs (layered, force, tree, box, sequence algorithms)
• State Machines - Complete guide to modeling state machines with states, transitions, triggers, guards, and effects
• Sequence Diagrams - Complete guide to modeling interactions with lifelines, messages, and conditional flows

Storybook

Spin up the component workbench to explore SysML nodes interactively:

npm run storybook   # dev server on http://localhost:6006
npm run build-storybook   # static export in storybook-static/

Continuous Storybook build

Every push or pull request triggers .github/workflows/storybook.yml, which installs dependencies, runs npm run lint, builds the static Storybook bundle, and publishes it as a GitHub Actions artifact named storybook-static. Grab the latest artifact from the Actions tab if you want to preview the CI build without running it locally.

GitHub Pages deployment

The Deploy Storybook to GitHub Pages workflow (.github/workflows/pages.yml) publishes the latest Storybook build to GitHub Pages on each push to master/main. Visit https://hollando78.github.io/SysML-reactflow/ for the hosted docs.

Testing

npm test              # Run tests once
npm run test:watch    # Run tests in watch mode
npm run test:ui       # Run tests with UI
npm run test:coverage # Run tests with coverage report

Test Coverage:

• ✅ 69 tests across 4 test suites
• ✅ 63% overall code coverage
• ✅ 100% coverage on core components (SysMLDiagram, viewpoints)
• ✅ Unit tests for factory functions
• ✅ Component tests for node rendering
• ✅ Integration tests for viewpoint filtering

Building the package

npm run build

This runs tsup to emit both ESM (dist/index.js) and CJS (dist/index.cjs) bundles alongside type declarations.

SysML v2.0 Compliance

This library implements the OMG Systems Modeling Language (SysML) v2.0 specification with comprehensive coverage of:

✅ Core Metamodel Elements - All major definition/usage pairs following KerML foundations ✅ Type Relationships - Specialization, conjugation, typing, subsetting, redefinition, feature chaining ✅ Behavioral Modeling - Actions, activities, calculations, state machines, interactions ✅ Requirement Engineering - Requirements, constraints, verification cases, analysis cases, concerns ✅ Structural Modeling - Parts, attributes, ports, items, connections, interfaces, allocations ✅ Organizational Elements - Packages, library packages, namespaces, memberships ✅ Metadata & Annotations - Comments, documentation, metadata definitions/usages

Alignment with SysML v2 Specifications:

• Based on OMG SysML v2.0 specification (ptc/24-02-03)
• Follows OASIS OSLC SysML v2.0 vocabulary (2024)
• Compatible with SysML v2 Pilot Implementation metamodel (Eclipse)

Limitations:

• Visualization Focus: This library provides visualization components, not a full authoring/editing environment
• No XMI/JSON Serialization: Does not currently serialize to/from standard SysML v2 interchange formats
• Simplified Expressions: Expression types (literal, invocation, feature reference) represented as strings
• Read-Only Rendering: Interactive editing and model manipulation not included

For full SysML v2 authoring capabilities, consider tools built on the Eclipse SysML v2 API.

Roadmap

• ✅ ~~Complete SysML v2 element type coverage~~
• ✅ ~~All definition/usage pairs~~
• ✅ ~~Full relationship support~~
• ✅ ~~Automatic layout with elkjs (layered, force, tree, box, sequence algorithms)~~
• 🔲 SysML v2 JSON/XMI serialization support
• 🔲 Expression metaclasses (LiteralExpression, InvocationExpression, FeatureReferenceExpression)
• 🔲 Advanced feature relationships (FeatureValue, FeatureChaining visualization)
• 🔲 Theme tokens + CSS variables for customization
• 🔲 Interactive editing capabilities
• 🔲 Model validation against SysML v2 constraints

Contributions and issues are welcome!