Implementing UIs with state machines

In this section, we make the link between reactive systems, behavior, state machines, and Kingly. We however strive to remain concise. You can alternatively review previously published long-form articles that gently go more in depth:

• User Interfaces You Can Trust with State Machines
• User interfaces as reactive systems

Implementing an application with state machines consists of two steps:

• implementing the behavior of the application; and
• implementing the actual application (with its user interface and all else).

The application behavior is simply the relation between events received by the interface and commands to perform on the interfaced systems. Implementing the actual application includes performing the commands on the interfaced systems and creating listeners for the events accepted by the UI.

Architecture

Kingly is thus designed to encourage a UI implementation consisting of separate modules with delimited responsibilities:

The interfaced systems — that includes the input device (e.g. your laptop or mobile phone) — are operated by command handlers. Interfaced systems can:

• respond to requests from the command handlers; or
• generate events that are dispatched to their intended recipient. For instance, web users may generate user events by interacting with DOM elements. DOM elements may have event handlers that dispatch those events to the machine.

Command handlers may react to responses from interfaced systems (e.g., remotely fetched data) by passing on events to the machine. The machine computes commands from the events it receives which are executed by command handlers. Those commands may result in API calls on the interfaced systems, which in turn may result in responses.

Note that the output device (e.g., a screen), is also one of the interfaced systems, and rendering is simply a command to an interfaced output device.

Modeling behavior

The behavior of an application can be specified by a relation between events received by the application and actions to be performed as a result on the interfaced system. With Kingly, you are expressing this relation with a procedure fsm which takes an event received by the interface into commands to perform on the interfaced systems: commands = fsm(event).

In most of the cases, the same event may result in different commands to be executed. This means that the fsm procedure is a stateful one. A Kingly state machine is such a function, which encapsulates the necessary state so that it is only accessible and visible to the fsm function itself. If we make the encapsulated state visible, we can define a pure function $g$ such that $(actions_n, state_{n+1}) = g (state_n, event_n)$, where $n$ is the $n^{th}$ invocation of the fsm function for the $n^{th}$ input it processes.

Additionally, a Kingly state machine divides its encapsulated state in two kinds of state: control states, and extended state. The machine starts in an initial control state. For each control state, the state machine must define a sub-procedure fsm' which will:

• perform the computation of commands when the machine is in that control state (i.e. fsm(event) = fsm'(event));
• update its control state (we say that the machine transitions to its new control state) if some conditions are fulfilled (we call such conditions guards); and
• update its extended state.

Control states thus define a “formula” computing the commands, while the extended state gathers the data necessary to perform the computation. As the machine changes of control state, the computation to perform changes accordingly. Control states may for instance serve to model interfaces going through different screens, associating a different relation between events and commands (i.e. behavior) to each screen.

State machines can be visually represented by a graph that links two control states whenever there is a possible transition between the two control states. The visualized graph summarizes accurately the fsm computation, i.e. the behavior of the interface to implement.

Modeling an interface behavior with state machines has the following advantages:

• the machine visualization is an accurate specification of the interface behavior;
• the machine visualization can be used to communicate the behavior to programmers and non-programmers alike, including designers, project managers, and other project stakeholders; and
• the state machine can be compiled to a standard JavaScript function that implements the interface behavior.

Using Kingly as a state machine library has the following advantages:

• the behavior of the machine, i.e. the computation of commands to perform, is completely separated from the execution of those commands. This means that any rendering library can be used to display the user interface, without any modification of the machine implementation.
• a Kingly machine is a standard JavaScript function that performs no effects. This means it is easy to test, without resorting to mocking, with any testing library of your choice.
• test input sequences for the machine can additionally be automatically computed.
• the interface behavior being separated from other concerns; it can be reused and shared among projects (for example on npm).

Application implementation

You should always start with getting a refined understanding of the application behavior from its informal specifications. From there, the previously described architecture allows you to decide in which order to go about implementing the separate modules. After some time doing this, we found the following workflow convenient:

⊕

Pick the order that makes more sense for you. Understanding what a screen depends on (props), and what are the events that it may generate also often helps define the set of events accepted by the machine; the parameters that the machine must compute for rendering a screen; and the set of commands executed by command handlers.

• get a refined understanding of the application behavior from its informal specifications;
• define the application’s user interface — for web applications, this may be HTML, CSS, props, and events;
• implement and test the user interface;
• define the command module interface (i.e., which commands are triggered by the user, the shape of those commands, and which events they produce as a result of their execution);
• implement and test the command module;
• model the interface behavior with a graph editor
• write some tests (with at least all-transitions coverage of the modeled machine);
• write the definition of the machine (i.e., initial state, events, transitions, guards, action factories) and pass the previous tests;
• write and pass a few integration tests (all-states coverage may suffice if high confidence derived from unit tests); and
• fully test the machine with automatically generated tests.

We will address automated test generation in a future dedicated section.

This section was fairly theoretical. We encourage you to review the tutorials to see these concepts and architecture put in practice. You can then come back and forth between tutorials and concepts to further your understanding. Let us know if you are stuck!

Alternatively, you can refer to the site map and navigate to other parts of the documentation.