Xstate: [Docs] Clarify transition configuration options

[andrewgordstewart]

Description
It's possible to define a transition config at the machine level. There are, in fact, examples of this in the guides. However, it's probably worth spelling that out at the start of the transition section, since that's where I'd expect to find out where and how I can define transitions.

Additional context
https://gitter.im/statecharts/statecharts?at=5e4d400314b4d670a334eba6

[andrewgordstewart]

@davidkpiano I put together this diagram which (I think?) is an overview of

• All of the places where a transition can be defined
  
  
  
  • including onDone and onError transitions in
  
  
• All of the ways of targeting states

What about including something like that in the guides as a quick reference for transition configs?

[davidkpiano]

@andrewgordstewart That looks great. The general rule of thumb is that any property starting with on* is for transitions.

Note: I don't want to encourage on: { ... } transitions on the machine (top-level state node) level, because that goes back to an event-first paradigm, which is what causes the bugs that state machines solve.

In short, the docs should say that it _can_ be done, but only when needed.

[hrafnkellpalsson]

Yeah, that had me confused when reading about self transitions since those examples use transitions at machine level.

On a related note the wordMachine in the docs doesn't work in the visualizer, it doesn't seem to like the machine id being used in the full path 'word.justify' in the JUSTIFY_CLICK event and gives an error in the console. I created my own example for self transitions using a hierarchical state node (so the transitions are not defined on the machine) and the same thing happens.

[hrafnkellpalsson]

Here's another simpler example of self transitions. In this case the node being entered and exited is not a parent node of anything, so maybe the emphasis in the docs about _parent_ actions being executed or not (external vs internal) is not the right strategy?

[hrafnkellpalsson]

In hindsight, I probably should have created a new issue, I just that I started investigating self transitions in more detail because of confusion about transitions at the machine config level.

Will happily create a new issue if appropriate!

[davidkpiano]

Will happily create a new issue if appropriate!

That sounds appropriate, thanks!

Also, feel free to contribute a better example; I'll gladly use it.