Home

Welcome to the statecharts wiki!

Problem definition

Statecharts library tries to solve the problem of describing complex UI programs. Currently we are focusing mainly on re-frame integration.

Re-frame is an excellent library. It manages the state of the application in form of the immutable database. Immutable database is then projected into HTML code using react/reagent libraries.

Problems begins when there are a lot of different screens and components which displays several parts of the application database all with different lifecycles. For instance uppon entering the page we need to change URL, uppon leaving we may want to persist current settings into browser storage etc...

Page can have several entry events (like goto-page, show-user-detail, set-data-filter) where you can put a middleware. But to detect leaving the page you have to cover all (possible future) other events which can cause the page leave.

FSM and Statecharts

There are several sources on the internet idicating that Finite state machines (FSM) and Statecharts can be successfuly used for UI description:

• http://blog.cognitect.com/blog/2017/8/14/restate-your-ui-creating-a-user-interface-with-re-frame-and-state-machines
• http://blog.cognitect.com/blog/2017/5/22/restate-your-ui-using-state-machines-to-simplify-user-interface-development
• https://github.com/nodename/stately
• https://github.com/etgryphon/stativus
• https://github.com/davidkpiano/xstate
• https://statecharts.github.io/

FSM is flat mathematical model of computation. It consists of states and transitions. All states are on the same level.

FSMs works great on small models, but suffers from combinatorial explosion with addition of new states. Simply, there are too many arrows between states.

This is the place where statecharts comes to the rescue. Statecharts are finite state machines, where each state can be hierarchically composed of another states.

Further description can be found on Statecharts page.

Problems with Re-frame/Redux/Vuex

• Global events
• Initialization
• Cleanup
• Reinitialization
• Handler polymorphism
• Composition and reuse

Statecharts library

Features include:

• Works with immutable structures
• Seamless integration with re-frame
• All effects are described as datastructures.
• re-frame effects can be directly used

DSL

• State
• Event/Transition
• Statechart context

API

• Path helpers
• Event processing
• Re-frame DB/Fx

Examples

• Simple example
• Realworld (Still work in progress)

Cookbook

• Page machine
• List machine
• Form machine
• Detail machine
• Url routes, back button (TODO)
• Timeout, Schedule event (TODO)