Model web component behaviour with XState
Tags: javascript, webcomponents, xstate, webdev
Published: 2022-07-20 14:42:40

[XState](https://xstate.js.org/) is a library for creating, interpreting, and executing finite state machines and statecharts.

[Finite state machines](https://en.wikipedia.org/wiki/Finite-state_machine) (or 'state machines' for short) and [statecharts](https://statecharts.dev/) are a visual language used to describe the states in a process. You may have used similar diagrams in the past to design user flows, plan databases or map application architecture. They are perfect for modelling web component behaviour.

State machines and statecharts provide a visual way of using boxes and arrows to represent behaviour. These flows are also executable code that can be used to control the logic in your application and that makes it more predicable and testable.

In this post, we're going to look at how to model behaviour in web components using state machines and statecharts in [FicusJS](https://docs.ficusjs.org/).

## State machines vs statecharts

What is the difference between state machines and statecharts? Understanding state machines is almost the same as understanding statecharts. Statecharts are the “bigger brother” of state machines and is essentially a state machine that allows any state to include more machines, in a hierarchical fashion.

## Benefits of using state machines

There are many benefits to using state machines or statecharts, including:

- The behaviour (when things happen) is decoupled from the actual component (what happens).
- They produce lower bug counts than traditional code.
- As the complexity of your program grows, statecharts scale well.
- You explore all the possible states of your program.

## Designing state machines

The first step in designing state machines is to use a whiteboard or pen and paper and write down the possible states of the component you want to create. This is an important part of the process and should involve UX designers, product owners and developers. Talking through the behaviour of the component and writing down all the states helps to identify all the possibilities up-front.

Once you have a list of identified states, create a [visual state machine](https://stately.ai/viz) to check that the behaviour works. Using a visual tool helps all stakeholders to understand the state machine and the behaviour of the component.

### An example

We are going to create a visual depiction of a simple state machine. It is a model of a simple on/off switch.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/y1qu9qrr6w584qyfppkg.png)

To view the visual model and interact with it visit [https://stately.ai/viz/04fcf47e-df9f-4f78-b3b9-4826c24b2df9](https://stately.ai/viz/04fcf47e-df9f-4f78-b3b9-4826c24b2df9)
 
The visual model is a simulation which helps to refine the behaviour through defining the states and transitions of the state machine.

- It consists of two states, “on” and “off”. This machine can therefore be in exactly one of the two states at any point in time. In other words, the transitions between states are instantaneous.
- The “flick” event causes it to transition between states.
- When the machine enters the “on” state, a side effect occurs. A light is turned on.
- When the machine exits the “on” state, another side effect occurs. A light is turned off.

The definition of the machine is as follows:

```js
{
  id: "switch",
  initial: "off",
  states: {
    off: {
      on: {
        FLICK: {
          target: "on",
          actions: "turnLightOn",
        },
      },
    },
    on: {
      on: {
        FLICK: {
          target: "off",
          actions: "turnLightOff",
        },
      },
    },
  },
}
```

## Creating a state machine

In order to create a state machine, you import the `createMachine` function and pass it a machine definition object.

> FicusJS decorates the [@xstate/fsm](https://xstate.js.org/docs/packages/xstate-fsm/) package to provide additional features like extended state getters. You can also use the full XState library with FicusJS, See [the state machine docs](https://docs.ficusjs.org/state-machines/) for more information.

```js
import { createMachine } from 'https://cdn.skypack.dev/@ficusjs/state@3/xstate-service'

const machine = createMachine({
  id: "switch",
  context: { bulb: 'off' },
  initial: "off",
  states: {
    off: {
      on: {
        FLICK: {
          target: "on",
          actions: "turnLightOn",
        },
      },
    },
    on: {
      on: {
        FLICK: {
          target: "off",
          actions: "turnLightOff",
        },
      },
    },
  },
})
```

## Creating side effects

Our state machine has two side effects. These are actions that are invoked when a transition is received.

Actions are passed as options to the `createMachine` function.

```js
import { createMachine } from 'https://cdn.skypack.dev/@ficusjs/state@3/xstate-service'

const definition = {
  id: "switch",
  context: { bulb: 'off' },
  initial: "off",
  states: {
    off: {
      on: {
        FLICK: {
          target: "on",
          actions: "turnLightOn",
        },
      },
    },
    on: {
      on: {
        FLICK: {
          target: "off",
          actions: "turnLightOff",
        },
      },
    },
  },
}

const options = {
  actions: {
    turnLightOn: assign({
      bulb: 'on'
    }),
    turnLightOff: assign({
      bulb: 'off'
    })
  }
}

const machine = createMachine(definition, options)
```

## Interpreted state machines

We can use an interpreted state machine to keep track of the state for us. To create an interpreted state machine, pass the machine created with `createMachine` into the `interpret` function. The result of the `interpret` function is called a service (a running instance of the machine).

```js
const machine = createMachine(definition, options)
const service = interpret(machine)
```

## Component usage

The service created with `interpret` can then be passed to a web component for it to react to state changes and therefore allow you to render UI based on the current state.

To pass the service to the component, use the `withXStateService` component extension.

```js
import { html, renderer } from 'https://cdn.skypack.dev/@ficusjs/renderers@5/uhtml'
import { createCustomElement, withXStateService } from 'https://cdn.skypack.dev/ficusjs@5'

createCustomElement(
  'switch-state-machine',
  withXStateService(service, {
    renderer,
    onChange () {
      this.fsm.send('FLICK')
    },
    render () {
    }
  })
)
```

## The result

The following [Codepen](https://codepen.io/ducksoupdev/pen/GRxWXQm) is an implementation example of the switch state machine used to turn on/off a light bulb.

{% codepen https://codepen.io/ducksoupdev/pen/GRxWXQm %}

## Summary

State machines and statecharts reduce complexity, bugs and inconsistencies in UI development by helping you define components using a behaviour-driven model. This ensures that what is designed through the visual model, is the same output that components provide through the implementation of XState.

State machines are a great fit if you need to control the application’s flow carefully. If you start using XState, it does not mean that everything will have to live inside the state machine. Some things need to be controlled on a local level inside a component rather than on a global level inside a state machine. That goes for both the state and the side effects.

Make smaller state machines rather than one enormous state machine. Programming is about composability, making larger things from smaller things — and state machines compose well.