A state machine abstraction for React that provides declarative state management and automatic test generation.
yarn add react-automata
// App.js
import React from 'react'
import { Action, withStatechart } from 'react-automata'
export const statechart = {
initial: 'a',
states: {
a: {
on: {
NEXT: 'b',
},
onEntry: 'enterA',
},
b: {
on: {
NEXT: 'a',
},
onEntry: 'enterB',
},
},
}
export class App extends React.Component {
handleClick = () => {
this.props.transition('NEXT')
}
render() {
return (
<div>
<button onClick={this.handleClick}>NEXT</button>
<Action show="enterA">Hello, A</Action>
<Action show="enterB">Ciao, B</Action>
</div>
)
}
}
export default withStatechart(statechart)(App)
// App.spec.js
import { testStatechart } from 'react-automata'
import { App, statechart } from './App'
test('it works', () => {
testStatechart({ statechart }, App)
})
// App.spec.js.snap
exports[`it works: a 1`] = `
<div>
<button
onClick={[Function]}
>
NEXT
</button>
Hello, A
</div>
`;
exports[`it works: b 1`] = `
<div>
<button
onClick={[Function]}
>
NEXT
</button>
Ciao, B
</div>
`;
The withStatechart
higher-order component takes a statechart definition (see xstate), some optional options and a component.
It returns a new component with special props, action methods and lifecycle methods.
The initial machine state and the initial data can be passed to the resulting component through the initialMachineState
and initialData
props.
Option | Type | Description |
---|---|---|
devTools | bool | To connect the state machine to the Redux DevTools Extension. |
The method to change the state of the state machine. It takes an optional updater function that receives the previous data and returns a data change. The updater can also be an object, which gets merged into the current data.
handleClick = () => {
this.props.transition('FETCH')
}
The current state of the state machine. Using this value is discouraged, as it couples the UI and the state machine.
<button onClick={this.handleClick}>
{this.props.machineState === 'idle' ? 'Fetch' : 'Retry'}
</button>
All the component's methods whose names match the names of the actions, are fired when the related transition happen. For example:
const statechart = {
// ...
fetching: {
on: {
SUCCESS: 'success',
ERROR: 'error',
},
onEntry: 'enterFetching',
},
// ...
}
class App extends React.Component {
// ...
enterFetching() {
fetch('https://api.github.com/users/gaearon/gists')
.then(response => response.json())
.then(gists => this.props.transition('SUCCESS', { gists }))
.catch(() => this.props.transition('ERROR'))
}
// ...
}
The lifecycle method invoked when a transition is about to happen. It provides the event, and can be used to run side-effects.
componentWillTransition(event) {
if (event === 'FETCH') {
fetch('https://api.github.com/users/gaearon/gists')
.then(response => response.json())
.then(gists => this.props.transition('SUCCESS', { gists }))
.catch(() => this.props.transition('ERROR'))
}
}
The lifecycle method invoked when a transition has happened and the state is updated.
It provides the previous state machine, and the event.
The current machineState
is available in this.state
.
componentDidTransition(prevStateMachine, event) {
Logger.log(event)
}
The component to define which parts of the tree should be rendered for a given action (or set of actions).
Prop | Type | Description |
---|---|---|
children | node | The children to be rendered when the conditions match. |
hide | oneOfType(string, arrayOf(string)) | The action(s) for which the children should be hidden. |
render | func | The render prop receives a bool (true when the conditions match) and it takes precedence over children. |
show | oneOfType(string, arrayOf(string)) | The action(s) for which the children should be shown. When both show and hide are defined, the children are shown from the first show match to the first hide match. |
onEnter | func | The function invoked when the component becomes visible, it provides the current machine state. |
onLeave | func | The function invoked when the component becomes invisible, it provides the current machine state. |
<Action show="enterError">Oh, snap!</Action>
The component to define which parts of the tree should be rendered for a given state (or set of states).
Prop | Type | Description |
---|---|---|
children | node | The children to be rendered when the conditions match. |
render | func | The render prop receives a bool (true when the conditions match) and it takes precedence over children. |
value | oneOfType(string, arrayOf(string)) | The state(s) for which the children should be shown. It accepts the exact state, a glob expression or an array of states/expressions (e.g. value="idle" , value="error.*" or value={['idle', 'error.*'] ). |
onEnter | func | The function invoked when the component becomes visible, it provides the current machine state. |
onLeave | func | The function invoked when the component becomes invisible, it provides the current machine state. |
<State value="error">Oh, snap!</State>
The method to automagically generate tests given a statechart definition, and a component.
It accepts an optional fixtures
configuration to describe which data should be injected into the component for a given transition.
const fixtures = {
initialData: {
gists: [],
},
fetching: {
SUCCESS: {
gists: [
{
id: 'ID1',
description: 'GIST1',
},
{
id: 'ID2',
description: 'GIST2',
},
],
},
},
}
test('it works', () => {
testStatechart({ statechart, fixtures }, App)
})
Federico, for telling me "Hey, I think building UIs using state machines is the future".
David, for giving a very informative (and fun) talk about infinitely better UIs, and building xstate.
Ryan, for experimenting with xstate and React - Ryan's approach to React has always been a source of inspiration.
Erik, for writing about statecharts, and showing me how to keep UI and state machine decoupled.