Reusable React Flow building blocks for OMG-compliant SysML diagrams.
npm install sysml-reactflowPure 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.
- β
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)
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
- 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 diagrams are view specifications. The library ships with reusable viewpoints that materialize the appropriate nodes/edges following SysML v2 semantics:
``tsx
import {
SysMLDiagram,
structuralDefinitionViewpoint,
type SysMLModel
} from 'sysml-reactflow';
const model: SysMLModel = { nodes: specs, relationships };
`
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.
`bash`
npm install sysml-reactflow react react-dom reactflow
`tsx
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 (
);
}
`
Apply automatic graph layout with optimized algorithms for different diagram types:
`tsx
import { layoutAndRouteFromSpecs } from 'sysml-reactflow';
const specs = [...];
const relationships = [...];
const { nodes: layoutedNodes, edges: layoutedEdges } = await layoutAndRouteFromSpecs(
specs,
relationships,
'requirements',
{ measure: true }
);
`
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.
- SysMLDiagram: Thin wrapper over ReactFlow that registers all SysML v2 node/edge types with recommended controlssysmlNodeTypes
- , sysmlEdgeTypes: Complete registries with 60+ node types and 30+ edge types
The library exports 60+ factory functions for creating SysML v2 elements:
Structural Element Factories:
- createAttributeDefinitionNode, createAttributeUsageNodecreateConnectionDefinitionNode
- , createConnectionUsageNodecreateInterfaceDefinitionNode
- , createInterfaceUsageNodecreateAllocationDefinitionNode
- , createAllocationUsageNodecreateReferenceUsageNode
- createOccurrenceDefinitionNode
- , createOccurrenceUsageNode
- And more...
Behavioral Element Factories:
- createCalculationDefinitionNode, createCalculationUsageNodecreatePerformActionNode
- , createSendActionNode, createAcceptActionNodecreateAssignmentActionNode
- , createIfActionNode, createForLoopActionNode, createWhileLoopActionNodecreateStateDefinitionNode
- , createStateUsageNode, createTransitionUsageNode
- And more...
Requirements & Cases Factories:
- createRequirementDefinitionNode, createRequirementUsageNodecreateConstraintDefinitionNode
- , createConstraintUsageNodecreateVerificationCaseDefinitionNode
- , createVerificationCaseUsageNodecreateAnalysisCaseDefinitionNode
- , createAnalysisCaseUsageNodecreateUseCaseDefinitionNode
- , createUseCaseUsageNodecreateConcernDefinitionNode
- , createConcernUsageNode
Organizational & Metadata Factories:
- createPackageNode, createLibraryPackageNodecreateInteractionNode
- createMetadataDefinitionNode
- , createMetadataUsageNodecreateCommentNode
- , createDocumentationNode
Batch Helpers:
- createNodesFromSpecs β batch creation with auto-positioningcreateEdgesFromRelationships
- β batch edge creation
All factory functions are fully typed with TypeScript, providing IDE autocomplete for all SysML v2 properties.
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
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
Spin up the component workbench to explore SysML nodes interactively:
`bash`
npm run storybook # dev server on http://localhost:6006
npm run build-storybook # static export in storybook-static/
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.
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.
`bash`
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
`bash`
npm run build
This runs tsup to emit both ESM (dist/index.js) and CJS (dist/index.cjs`) bundles alongside type declarations.
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.
- β
~~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!