States connected across composite states behave counterintuitively

[Gliptal]

Description

The behaviour of a state that's connected across two (or multiple) composite states is counterintuitive.

Consider this:

stateDiagram-v2
    direction LR
    state A {
        1 --> 2
    }
    state B {
        2 --> 3
    }

stateDiagram-v2
    direction LR
    state A {
        1 --> 2
    }
    state B {
        2 --> 3
    }

Loading

I'd expect the 2 state to be in the A composite state, but it's placed in B instead: 2 is defined in A, so why is it being placed in B? This becomes even more confusing if you add a third composite state:

stateDiagram-v2
    direction LR
    state A {
        1 --> 2
    }
    state B {
        2 --> 3
    }
    state C {
        2 --> 4
    }

stateDiagram-v2
    direction LR
    state A {
        1 --> 2
    }
    state B {
        2 --> 3
    }
    state C {
        2 --> 4
    }

Loading

Now 2 is placed in C and B only has 3.

It appears states are placed in the last composite state defined, given this works as I would initially expect:

stateDiagram-v2
    direction LR
    state B {
        2 --> 3
    }
    state A {
        1 --> 2
    }

stateDiagram-v2
    direction LR
    state B {
        2 --> 3
    }
    state A {
        1 --> 2
    }

Loading

Which might arguably be an even more confusing construct, forcing you to define following composite states before preceding ones.

Code Sample

stateDiagram-v2
    direction LR
    state A {
        1 --> 2
    }
    state B {
        2 --> 3
    }

stateDiagram-v2
    direction LR
    state A {
        1 --> 2
    }
    state B {
        2 --> 3
    }
    state C {
        2 --> 4
    }

stateDiagram-v2
    direction LR
    state B {
        2 --> 3
    }
    state A {
        1 --> 2
    }

Setup

• Mermaid version: v10.8.0

Suggested Solutions

• Invert the order in which states connected across composite states are evaluated.
• Always place a state in the composite state it's first found.