React Automata

A state machine abstraction for React that provides declarative state management and automatic test generation.

Quick Start

Installation

yarn add react-automata

Usage

// App.js

import React from 'react'
import { Action, withStatechart } from 'react-automata'

export const statechart = {
  initial: 'a',
  states: {
    a: {
      on: {
        NEXT: 'b',
      },
      onEntry: 'sayHello',
    },
    b: {
      on: {
        NEXT: 'a',
      },
      onEntry: 'sayCiao',
    },
  },
}

export class App extends React.Component {
  handleClick = () => {
    this.props.transition('NEXT')
  }

  render() {
    return (
      <div>
        <button onClick={this.handleClick}>NEXT</button>
        <Action show="sayHello">Hello, A</Action>
        <Action show="sayCiao">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>
`;

API

withStatechart(statechart[, options])(Component)

The withStatechart higher-order component takes an xstate configuration object or an xstate machine, some options and a component. It returns a new component with special props, action methods and additional lifecycle hooks. The initial machine state and the initial data can be passed to the resulting component through the initialMachineState and initialData props.

Options

Option	Type	Description
channel	string	The key of the context on which to set the state.
devTools	bool	To connect the state machine to the Redux DevTools Extension.

Props

transition(event[, updater])

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')
}

machineState

The current state of the state machine.

The use of this value is discouraged, as it couples the component and the state machine.

<button onClick={this.handleClick}>
  {this.props.machineState === 'idle' ? 'Fetch' : 'Retry'}
</button>

Action methods

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: 'fetchGists',
  },
  // ...
}

class App extends React.Component {
  // ...
  fetchGists() {
    fetch('https://api.github.com/users/gaearon/gists')
      .then(response => response.json())
      .then(gists => this.props.transition('SUCCESS', { gists }))
      .catch(() => this.props.transition('ERROR'))
  }
  // ...
}

Lifecycle hooks

componentWillTransition(event)

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'))
  }
}

componentDidTransition(prevStateMachine, event)

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.props.

componentDidTransition(prevStateMachine, event) {
  Logger.log(event)
}

<Action />

The component to define which parts of the tree should be rendered for a given action (or set of actions).

Prop	Type	Description
hide	oneOfType(string, arrayOf(string))	The action(s) for which the children should be hidden.
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.
channel	string	The key of the context from where to read the state.
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.
onHide	func	The function invoked when the component becomes invisible.
onShow	func	The function invoked when the component becomes visible.

<Action show="showError">Oh, snap!</Action>

<Action
  show="showError"
  render={visible => (visible ? <div>Oh, snap!</div> : null)}
/>

<State />

The component to define which parts of the tree should be rendered for a given state (or set of states).

Prop	Type	Description
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.']`).
channel	string	The key of the context from where to read the state.
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.
onHide	func	The function invoked when the component becomes invisible.
onShow	func	The function invoked when the component becomes visible.

<State value="error">Oh, snap!</State>

<State
  value="error"
  render={visible => (visible ? <div>Oh, snap!</div> : null)}
/>

testStatechart({ statechart[, fixtures][, extendedState] }, Component)

The method to automagically generate tests given a statechart definition, and a component. It accepts an additional fixtures option to describe the data to be injected into the component for a given transition, and an extendedState option to control the statechart's conditions - both are optional.

Please note that the component should be a base component not wrapped into withStateChart (see #46).

const fixtures = {
  initialData: {
    gists: [],
  },
  fetching: {
    SUCCESS: {
      gists: [
        {
          id: 'ID1',
          description: 'GIST1',
        },
        {
          id: 'ID2',
          description: 'GIST2',
        },
      ],
    },
  },
}

test('it works', () => {
  testStatechart({ statechart, fixtures }, App)
})

Examples

Inspiration

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.

ioss / react-automata