DEV Community: Anton Kiłka

Play: UI Layouts in PureScript

Anton Kiłka — Sun, 11 Jan 2026 04:13:13 +0000

[ play package in pursuit ] | [ original article in my blog ]

Introduction

Now that most of my latest projects are written in PureScript¹, my favorite language for development for several years already, I noticed that I am developing a bunch of web apps with user interfaces of different complexity:

Let me list some of the details from these examples:

Noodle — visual programming platform, where:
- it is possible to open many side panels: documentation, action history, log, and so on;
- there is a library of node families;
- there as well is status bar with several cells;
- there is patch area where all the nodes are layed out;
- and all the nodes have their own structure which I want to have modular;
  - the node could be vertical: inlets on the top, outlets on the bottom;
  - the node could be horizontal: inlets on the left, outlets on the right;
- there are several stacked layers: canvas in the background, SVG main area as a layer in the middle, HTML layer on top, and recently I have added one more canvas on top for the node bodies;
- not to mention that to find a free space for a new node, we could also need a smart layouting system intended just for nodes;

Noodle at Github

Tree graph explorer, to visualize the many kinds of tree-structured data I have; Sometimes I store UI dependencies in a graph, sometimes I keep my book library organized as a tree, where a shelf or an author's name first letters can represent a node; It has these optional panels:
- The tree itself;
- The pinned nodes area, to keep an eye on the specific tree nodes (they can be complex interactive components by themselves);
- The area where I can see a tree in its plain representation for easier navigation, where the selected nodes are highlighted;
- The history of the visited paths, so I would be able to return to them later;
- Current location and current selection, since it is heavily based on keyboard navigation;
- Zoom panel;
- The export area, for JSON and other formats preview;
- ...

...and counting. I also plan to revive some older projects, and they also have many panels and subpanels. So I felt an acute need to ease the calculation of all the positioning, because for every small part the position needs to be calculated and I want them responsive. And with PureScript we're not having Swift UI-like constructors... yet.

SVG Tree at Github

Clay UI as an inspiration

Almost in the same moments when this need was most desperate in my mind, YouTube happened to suggest me the video about Clay UI : the UI layouting library for C++ with beautifully simple and consice algorithm (yes, in C++) and it was all explained in all details in full in 40 minutes.

How Clay's UI Layout Algorithm Works by Nic Barker

So I was definitely inspired, I love to discover the easier parts in what was considered complex before, and O decided to translate this algorithm to pure FP version, of course it turned out to be an interesting thought-trainer by itself, and considering the problems I mentioned above, the challenge, when resolved, tended to grow very helpful and useful for my cause.

While C++ code is usually imperative, pure FP seem to require the completely perpendicular approach... partly it is true, the code is very different, but Nic, the author of Clay UI is so talented that his ideas are universal for almost any programming approach, and they could be layed out over FP concepts like one would considered they were there from the start, we have folding and recursion out of the box for our help, but the order of steps and mathematics are the same:

* fit sizing reverse-breadth-first (from leaves to the root);
* then calculate grow sizing breadth-first (from the root to the leaves);
* then apply positions having the sizes already (in any direction);

NB: It is worth mentioning that one of the core features of Clay is measuring text size in any font, so that it can be layed out correctly. In C++ it is an uncommon but needed feature, but in front-end web development we have our own ways for that: nowadays browser engines help us, but not a long time ago we had to pre-render the text in some HTML element that is invisible to the user and measuring it. So I decided to omit this part, which is probably better to implement through JavaScript FFI.

I can't say that it was very easy, but still it was much was easier than I expected, to implement all this logic. And it also turned out to be just around 300 lines of code, even including empty lines, documentation and type definitions. I planned to use Claude/Copilot only on the last stages for writing the tests and clarifying the algorithm with documentation, and indeed I did enable it only after implementing the core part, but in the end we developed the UI Constructor as well as some quick encoding system for layouts together, and also AI helped me later with fixing some hardly noticable issues regarding children alignment and percentage positioning in deeper structures.

The UI of the constructor is a bit bulky, there are many inline CSS styles there, but there are many features that could help you draft or build your layout beforehand, and generate the code to fill it in with the values later.

...And I named the library Play, because no other word came to my mind in attempts to combine PureScript and Clay. Also, I suppose with Japanese pronounciation of this word could sound very similar to "Pure". ChatGPT, do you know any better? Picklay? Purée? Hooray?...

...Hey, may you would like to have some fun already, so there is a beforementioned layout constructor for you to play with: https://shamansir.github.io/purescript-play/constructor.html

Play API

The idea is to let user fill in a polymorphic parameter a with any type they want: Play a can be Play Int, Play String, Play Color, Play UIPart, Play Key, Play Character, Play Sonet, Play HalfLife3UI, Play (Play Whatever)...

PureScript allows you to define almost any operator you want, so I decided to have ~* for chaining, which is actually just an alias for #, so you can use any you prefer, just don't mix them in the same code. Here's the example of a defintion:

data MenuItem
   = Root
   | Title String
   | Icon

data ClayMenu
    = Root
    | Item MenuItem

menuItem :: String -> Play ClayMenu
menuItem itemTitle =
    Play.i (Item Root)
        ~* Play.widthGrow
        ~* Play.heightFit
        ~* Play.leftToRight
        ~* (Play.padding $ Play.all 3.0)
        ~* Play.with
        [ Play.i (Item $ Title itemTitle)
            ~* Play.widthGrow
            ~* Play.height 60.0
        , Play.i (Item Icon)
            ~* Play.width 60.0
            ~* Play.height 60.0
        ]


menuDef :: Play ClayMenu
menuDef =
    Play.i Root
        ~* Play.width 250.0
        ~* Play.heightFit
        ~* (Play.padding $ Play.all 5.0)
        ~* Play.topToBottom
        ~* Play.childGap 5.0
        ~* Play.with (menuItem <$> 
                        [ "Copy", "Paste", "Delete", "Spell Check", "Dictionary", "Comment" ])
    :: Example ClayMenu

You can find the examples in the sources of the Constructor as well as in the test spec², there should be a fitting one for almost any case! :)

`Play` Types and Functions

Play a contains all the layout definitions, which side of the container / cell is fixed in size, or grows, or if it fits its children (more on that later), but they are not layed out yet (don't lay off, better lay out!).

For that, there's Layout a, which, as you may suggest, stores all the items layed out strictly following these definitions, having their positions and dimensions calculated.

So, when you have defined the logic of how your UI parts fit and grow, call the layout function, which is a verb in this case, and you'll have the calculated rectangles in place:

menuLayout :: Play.Layout ClayMenu
menuLayout = Play.layout menuDef

Since, as you may have noticed, I really like tree structures, both of those are just trees under the hood:

type WithDef a = { v :: a, def :: Def }
type WithDefRect a = { v :: a, def :: Def, rect :: Rect }

data Play a = Play (Tree (PT.WithDef a))
data Layout a = Layout (Tree (PT.WithDefAndRect a))

layout :: forall a. Play a -> Layout a
layout = toTree >>> Layout.layoutTree >>> Layout

Def is just the configuration, while Rect contains both position and size of every element. You may convert the Layout a to either a tree or a flattened array, what is better fits your needs:

layoutToTree :: forall a. Layout a -> Tree (PT.WithRect a)

flattenLayout :: forall a. Layout a -> Array (PT.WithRect a)

The calculations are already made, so the order is not important anymore, all the positions and dimensions are there, so you lose nothing even with a flat array, you may just map over it in the UI renderer:

let 
    windowSize = window.size
    myLayout = Play.layout $ myUI windowSize -- your layout could depend on the window size, but it's not obligatory;
in 
    H.div 
        [ H.style $ Position Relative ]
        $ renderItem <$> Play.flattenLayout myLayout
    where 
        renderItem :: PT.WithDefAndRect a -> Html _
        renderItem { rect, v } = 
            H.div 
              [ H.style $ Position Absolute <> Left rect.pos.x <> Top rect.pos.y ] -- I usually use SVG so I translate `Svg.g [] [...]` to the position
              $ case v of 
                  Root -> ...
                  Item (Title title) -> ...
                  Item (Icon url) -> ...

If you need to keep parent-child relations for something else, I recommend prefer using Play a structure over Layout a, however once again those both are just Tree a in disguise.

So, once more, this a can be anything, for example in case of Noodle node inner layout I have Play NodePart where NodePart is defined this way:

data NodePart
    = Background
    ...
    | Title
    | BodyBg
    | BodyContent
    | Inlets
    | Outlets
    | Inlet Int
    | InletName Int String
    | InletConnector Int
    | Outlet Int
    | OutletName Int
    | OutletConnector Int
    | Buttons
    | Button Remove
    | Button Collapse
    ...

You may find even more examples later in the post.

Layout definition

So, here's how you can define your layout:

Any cell can have its orientation either:

Horizontal / LeftToRight — width is the main axis, the children are aligned horizontally;
Vertical / TopToBottom — height is the main axis, the children are aligned vertically;
ZAxis / BackToFront - yes, just like the layered cake, I really wanted to have this in some particular cases so I implemented it as well;

Then, either width or height of any cell can either be:

Fixed to some exact pixel size;
Fit its children by this side: pack them and resize to the sum of their width or height;
Percentage amount of the corresponding side of its parent, overflow is allowed and cut by the rectangle of the parent;
Grow, unless it meets the next child or its parent can not expand more on the right / to the bottom;
FitGrow — fit its children and only then grow to the right / to the bottom;
FitMin — fit the children but no less than given value in pixels, so if children take less requested space, the side will have this size anyway, otherwise it will fit them into a larger size;
FitMax — same, but no more than given value in pixels;
FitMinMax — if the children fit between the given range, use the actual value, or restrict it with the given bounds;
GrowMin - grow only if there's a minimum of space, else have this side zero;

There is an additional configuration possible for any cell:

Children Gap — constant space inserted between children;
Padding — padding on the inner sides of the cell, so that there is a space between the border and its children, can be a specific value for each side;
Alignment - how the children are aligned inside the cell if their size is smaller on the side of alignment, could be specified both horizontally (Left / Center / Right) and vertically (Top / Middle / Bottom);

Both of Play and Layout are functors and applicatives:

type MyItem = { title :: String, textColor :: Color, background :: Color } 

myUI :: Play MyItem
myUI = ....

jsonTree :: Play Json
jsonTree = toJson <$> myUI

positionedLabels :: Play.Layout String
positionedLabels = _.title <$> Play.layout myUI

The Constructor

Together with Claude, we've developed for you the Constructor which can ease creating layouts by making it visual instead of just code:

It can be not that easy to use though, however at least we tried! :). There are several useful features we implemented:

Full properties editor:
- You may change any layout parameter of a cell;
- Manage their children: add or remove them;
Navigate over the tree:
- By clicking on the cell in the example preview;
- Using the buttons on the top of the properies editor;
- In the Tree viewer, by clicking on the title of the item;
View the Tree interactively:
- You may collapse and expand branches in the Tree Viewer;
Convert the layout:
- to PureScript code as Play String, so that you can just copy-paste it when your layout is ready;
- to JSON definition;
- to YAML definition;
Optional encoded sizing labels can help in debugging (however, if the item is in the background, you can't see them);
No dark mode (yet);
The selected example is stored in the URL;
Kinda illustrates responsiveness of the layouts when you change the size of the root element...;

By enabling encoded sizing labels, you may get visual help on how your layout is structured.

Start with the Blank UI example if you would like to experiment from scratch.

You can click blocks on the visual preview to edit their properties. Or, especially for the cases when the block is zero-size or hidden below being compltely covered by its children, you can navigate using the Properties panel. For every child there is Go button to switch to this child, and whene you're there, there are Parent (which allows you to switch to the parent of this particular child) and Root (which allows you to switch to the only one parent for all this layout) buttons. If they are both disabled, you're already at root. If Parent is disabled, then you're on the top level.

There's another, third way, to navigate: If you open the Code & Tree panel on the bottom side of the screen, there's a tab with fully navigatable tree. Just click on any leaf and there you have switched to it.

The first tab on this panel, Code, contains the generated code for current layout.

Both tree view and code are instantly updated whenever you change something in the layout. Same way as the visual preview, obviously :).

The Algorithm

At first I wanted to explain here the algorithm in the very detail, but I really tried to make it self-explanatory and I hope I succeeded, however it could still be the topic for another article.

Examples

You could've been bored enough to this point, so I decided to give you more examples and illustrate them with Kanji structure.

Kanji

Kanji are japanese hieroglyphs and they can be recursive in a sense: they can be treated as a single whole characters or contain other kanji characters inside and still be treated as a whole. But there are only a few certain ways to lay them out:

single character;
top to bottom; no matter if there are two or three elements, the above element could be smaller than the element below it or vise versa; may be the middle element is in most cases larger than the others, because other way it wouldn't be beautiful and would be weird, and kanji are nothing about weird;
left to right; the left element could be smaller than the right one or vise versa, the same statements as for vertical axis could apply here;
enclosing: where one larger element contains another smaller one and either wraps it around completely or wraps it at least from two connected sides;

Image Source

It could be quite easy to implement, but languages and writing systems are a bit more natural than mathematical, so they tend to be unpredictable and suprising more often than solving an equation or proving a theorem. But always beatiful. As how leaves are disordered on the tree. Or may be there's pure order we aren't aware about, in search of this order we developed fractals or Wave Function Collapse algorithm or Neural Networks...

So the laying out process of the kanji could repeat some times, there could be enclosing of one element inside another and then this enclosing could be
attached to the left of other two elements.³

The element of kanji that can be reused inside other characters is called radical. Not all of dozens of thousands kanji can be radicals, but only around 214. If we follow the book, then the number is exactly 214.

Becase Unicode tries to cover all the writing systems and tries to optimize the rendering algorithms whenever possible by finding the patterns of possible combinations of characters, they developed the system called IDS:

It defines all the possible known ways of combining radicals by doing what we love to do in functional programming: binary or ternary operators/functions are applied to the results of the calls of another operators/functions, and the arguments of these functions are the forementioned radicals.

Image Source

Since we plan to stretch radicals in different ways and not always proportionally, for rendering we'll use the slabby font instead of a caligraphic one, or else the beauty will be completely broken.

Here's a separate page with all the examples of these Kanji rendered using Play UI:

So lets finally define what we know with the code, our implementation would mirror the IDS machine, if you want, you make take a look at the actual code behind this page:

newtype KanjiPart = KanjiP String -- we store the radical char here

data KanjiOp
    = Single KanjiPart
    | LeftToRight
        { left :: KanjiOp, right :: KanjiOp }
        { rate :: Number }
    | TopToBottom
        { top :: KanjiOp, bottom :: KanjiOp }
        { rate :: Number }
    | Surround
        SurroundKind
        { inside :: KanjiOp, surround :: KanjiOp }
        { rateX :: Number, rateY :: Number }   


data SurroundKind
    = Full
    | FromAbove
    | FromBelow
    | FromLeft
    | FromRight
    | FromUpperLeft
    | FromUpperRight
    | FromLowerLeft
    | Inbetween

The difference is that we also remember the rate — the proportion between how much more one radical takes than its pair in a space of 1.0. To represent a kanji as triplets, we'll just add a pair to an element, like in pure FP. Oh wait...

So now we have a universal recursive function:

toPlaySpecAt :: _ -> KanjiOp -> Play KanjiItem
toPlaySpecAt posKey = case _ of
    Single kanji -> ...
    LeftToRight { left, right } { rate } -> ...
    TopToBottom { top, bottom } { rate } -> ...
    Surround kind { inside, surround } { rateX, rateY } -> ...

The snippets below are the parts of this function. You may find these examples separately in the constructor, just look for the ones titled Kanji Example ...:

Kanji. A single sole character / radical:

The definition for a single character is as easy as this:

Play.i (AKanji kanji posKey)
        ~* Play.widthGrow
        ~* Play.heightGrow

Kanji. Two (or more) characters aside:

When we need to position two sub-parts together, we need to decide how they share the space, usually one dominates over the other:

Play.i (OpRoot OpLeftToRight)
    ~* Play.widthGrow
    ~* Play.heightGrow
    ~* Play.leftToRight
    ~* Play.with
        [ toPlaySpecAt KLeft left
            ~* Play.widthPercent (Play.pct rate)
            ~* Play.heightGrow
        , toPlaySpecAt KRight right
            ~* Play.widthPercent (Play.pct $ 1.0 - rate)
            ~* Play.heightGrow
        ]

Kanji. Two (or more) characters above each other:

It's the same as with horizontal axis, but vertical:

Play.i (OpRoot OpTopToBottom)
    ~* Play.widthGrow
    ~* Play.heightGrow
    ~* Play.topToBottom
    ~* Play.with
        [ toPlaySpecAt KTop top
            ~* Play.widthGrow
            ~* Play.heightPercent (Play.pct rate)
        , toPlaySpecAt KBottom bottom
            ~* Play.widthGrow
            ~* Play.heightPercent (Play.pct $ 1.0 - rate)
        ]

Kanji. The enclosure:

This one is a bit more complicated:

let
    insidePlay = toPlaySpecAt (KInside kind) inside
    surroundPlay = toPlaySpecAt (KSurround kind) surround
    construct alignHorz alignVert =
        Play.i (OpRoot $ OpSurround kind)
            ~* Play.widthGrow
            ~* Play.heightGrow
            ~* Play.backToFront
            ~* Play.with
                [ surroundPlay
                , Play.i Stub
                    ~* Play.widthGrow
                    ~* Play.heightGrow
                    ~* alignHorz
                    ~* alignVert
                    ~* Play.with
                        [ Play.i (OpRoot $ OpSurroundInside kind)
                            ~* Play.widthPercent  (Play.pct $ 1.0 - rateX)
                            ~* Play.heightPercent (Play.pct $ 1.0 - rateY)
                            ~* Play.with [ insidePlay ]
                        ]
                ]
in case kind of
    Full ->
        construct     Play.alignCenter    Play.alignMiddle
    FromAbove ->
        construct     Play.alignCenter    Play.alignBottom
    FromLeft ->
        construct     Play.alignRight     Play.alignMiddle
    FromRight ->
        construct     Play.alignLeft      Play.alignMiddle
    FromBelow ->
        construct     Play.alignCenter    Play.alignTop
    FromUpperLeft ->
        construct     Play.alignRight     Play.alignBottom
    FromUpperRight ->
        construct     Play.alignLeft      Play.alignBottom
    FromLowerLeft ->
        construct     Play.alignRight     Play.alignTop
    Inbetween ->
        construct     Play.alignCenter    Play.alignTop

The Riichi mahjong table

As you may have noticed, Japanese culture inspires truly inspires people, so let's stick with it a bit more. There is a tabletop game called Riichi Mahjong in Japan, of which can think of something like Poker card game variation (what was earlier?), but the all the cards are made from dragon teeth rather than paper.

You may have noticed people playing in in some Cyberpunk movies or Umbrella Academy TV series or somewhere else... I am lazily trying to learn the rules already for more than a year (a perfect game for playing in Corona times with your household), for example with the help of this three-hour-long video.

So I decided that it could also be fun to lay out the table for the game. There are many variants of Mahjong games for your phone now, but be aware, it could be a casino-like experience:

Source of the image

I decided that I would like to implement the layout of the table from Nintendo Switch 51 Worldwide Classics:

Source of the image

In my case it's not that beautiful and not 3D but the positions are there:

It's where BackToFront direction and percentage fitting helped a lot, because there are many parts that is easier to implement when they overlap each other. It would be an insidious move of mine if I would include the full code of this layout (even considering that it is woven from several reusable functions), so I will just leave the link to the source code for you: The Riichi Mahjong Table layout

SVG Tree Viewer

Let the last example be a more laconic code, so here's the mentioned SVG Tree editor layout ( source code ):

Outro

With this article I hope to attract more attention to the languages like PureScript, or Unison or LEAN, or Haskell or Elm and its descendants, because they not only bring mathematical beauty in the world (I say it from the position of the guy who totally didn't like maths at school, though gladly read books from Martin Gardner or Lewis Carroll about Logic), but also the code written using them is stable, easy to reason, and brings joy.

be confused with a kind of non-lazy Haskell for web development;

which is (I please you) not to be confused with TypeScript, but rather ↩
notice that for the tests specs I developed the quick encoding of the layout parameters (which is itself covered with tests), this kind of encoding is also shown in the constructor, and if you find it useful, you are free to use it! ↩
some more resources about kanji: ↩

PureScript: UI driven by Finite State Machines and Event Streams, Part II: The Example

Anton Kiłka — Thu, 23 Apr 2020 09:42:57 +0000

Just to recall, in the first part we are discussing using the Finite State Machines for UI with the possibility to collect errors, the ability to rollback to the last successful state, and created using Event Streams, and this is the second part with the actual practical example.

To give you a nice example other than a shopping cart or ATM, let’s recall the game of Animal Crossing: New Horizons. If you haven’t played it, you most probably heard about it nowadays, but it’s not important since I will describe the scheme anyway and there should be no huge spoilers.

First, the complete source code. It’s here: https://github.com/shamansir/purescript-ffm. To run it, an least four commands are needed to be executed (the project is working on spago + parcel ):

npm install -g purescript spago
npm install
npm run build
npm run dev

You should be able now to go to http://localhost:1234 and observe some weird interface there, which we cover below, but first let’s explain the basic logic behind it.

It also has tests made with awesome purescript-spec, you can easily run them using:

npm run test

There is a museum and it has (yet discovered by me to the moment) three stages of development:

The Plot

First, you are catching bugs and fishing and deliver these specimens to the bear (bear with me, I can promise we are all sane!), who is very serious about business and who collects your species until the amount reaches five.

They all should be unique though, and that requirement goes through the whole system. Everything that already exists in the museum or extends the amount of one, will be returned back to you.

Only after that, you are introduced to Blathers, the owl that lives in a tent and has some botanical and archeological skills. Now, in addition to aggregating bugs and fish, you also can dig up the fossils with the shovel, which are then “unpacked” by Blathers to some specific part of an outdated animal skeleton and returned to you, only after that you know what was inside of that fossil.

And so now you deliver the bugs and fossils to the tent, and the owl has one side effect of telling you the very detailed, perfectly scientific, story about every new creature you’ve found. You always have an option to decline and nobody will judge you (won’t they, actually? there are rumours that the animals were not that polite in the previous games of series…).

Now, when you reach the 15 of species (unique unpacked fossils also count as one), you can select the place for the large fancy museum and have it built it on the next day. It has three floors and all your bugs and fish and skeletons (not the ones from the closet) are located in here.

And now you also get a nice option to deliver several unique things at once and politely omit the _side effect_of hearing the story. Sometimes it looks like Blathers is actually also bored with telling, but the curiosity, or may be ethic rules, keeps me asking him to tell and tell them again and again.

The Interface

In the interface, there are some buttons at the top, and they are only usable by player, which means you. You are the God here and the button of the God is the one that just produces errors, for sure. Also you can dig, catch bugs and go fishing, but ensure to press these buttons a lot of times, because the chance that you get something in response is 40%. We do use random numbers here!

Aside from that, you can see all the species you have (none for the moment), grouped by bugs/fish/skeletons/fossils and then by quantity and kind, and much more details about the future museum.

You can deliver the items you have to the museum, but the museum will take only the unique ones, and just one item of such (even though you’re God and they should’ve store pairs of them, ignorant… animals!). Everything else gets back to you.

But the situation with fossils is different! You don’t know what’s inside of them. You can not deliver them to the museum at the first stage where Tom Nook rules the party, since he is unable to unwrap that fossils too. Only Blathers has required education, so you have to upgrade to the tent before delivering them. Also, after that he only unwraps them and returns them back as the skeleton parts, which you may then try to deliver the usual way.

Upgrading: When you have delivered enough of unique species to upgrade (5 for the tent, 10 for the building), the museum will close until you will find the location for the tent or the building. In the game, you would have to wait for a day after that, but we are not that realistic here, so when you find the location (by pressing the corresponding button and so choosing it randomly) the museum just opens back again.

I won’t inspect the source line by line, but rather will just discuss with you the most important parts.

The Structure of Code

The most interesting for you should be the Example.purs file, it has all the logic discussed above. Secondly, the Ui.purs, which specifies the rendering engine in just a few lines. And the last may be VDom.purs, which reuses the Halogen’s VDom engine to actually render stuff and run the User Interface.
And, of course, Fsm/Fsm.purs, but we have discussed it in the details through all the first part, so you already know everything about it, don’t bother looking!

The FSM

Okay, just a quick look. It is different from the article in the sense that it collects effects in the list rather than produces a singe effect with a list of actions as the result:

data Fsm action model =
    Fsm (action -> model -> model /\ List (Effect action))

Everything else is the same and takes just a dozen of lines. Well, ten dozens, but it’s just because we have no economy for lines of code in functional languages, it is the infinite resource here!

The Rendering

We just redefine the original Fsm with model being the Coveredtype and use it for the Ui, that’s it:

type CoveredFsm error action model = 
    Fsm action (Covered error model)


data Ui error action model view =
    Ui 
        (CoveredFsm error action model) 
        (Covered error model -> view)

Notice the make and make' functions, they are different in the way of joining or not joining errors, as discussed in the original article:

make
    :: forall error action model view
     . (action
            -> Covered error model
            -> Covered error model /\ List (Effect action))
    -> (Covered error model -> view)
    -> Ui error action model view
make updateF viewF =
    Ui (Fsm.make updateF # Fsm.joinWith (<|>)) viewF


make'
    :: forall error action model view
     . Semigroup error
    => (action
            -> Covered error model
            -> Covered error model /\ List (Effect action))
    -> (Covered error model -> view)
    -> Ui error action model view
make' updateF viewF =
    Ui (Fsm.make updateF
            # Fsm.joinWith Covered.appendErrors) viewF

Implementation

We have Action and Model and Error here and also he have an App:

data Action 
    = ...

data Model 
    = ...

data Error 
    = ...

type App =
    Ui Error Action Model (Html Action)

We create it using Ui.make:

app :: App
app =
    Ui.make' update' view'

Notice the quotes. If you change make' to make, then it no more requires Semigroup for errors, so they are aggregated no more, just the latest one is going through all the engine. You’ll notice it when you run the example and do something erroneous or just press the almighty “Produce Error” button. Just a subtle change leads to such serious consequences!

update' is different from update only by the fact it unwraps the Covered model since in the logic we don’t care, were there errors before or not:

update' 
    :: Action 
    -> Covered Error Model 
    -> Covered Error Model /\ List (Effect Action)
update' action covered =
    update action $ Covered.recover covered

update 
    :: Action 
    -> Model 
    -> Covered Error Model /\ List (Effect Action)
update ...

view' with the quote just also renders the error(-s) when it (they) happened before:

view' :: Covered Error Model -> Html Action
view' covered =
    case covered of
        Carried model -> view model
        Recovered error model ->
            H.div
                [ ]
                [ view model
                , H.text $ "Latest errors: " <> show error
                ]


view :: Model -> Html Action
view ...

To run it, we use Ui.run in the VDom.purs.

Regarding Semigroup and Errors, we have a special constructor for the errors to collect them:

data Error 
    = ...
    | SeveralErrors (List Error)

And the Semigroup implementation:

instance semigroupError :: Semigroup Error where
    append (SeveralErrors listA) (SeveralErrors listB) 
        = SeveralErrors $ listA <> listB
    append singleError (SeveralErrors list) 
        = SeveralErrors $ singleError : list
    append (SeveralErrors list) singleError 
        = SeveralErrors $ list <> pure singleError
    append singleErrorA singleErrorB 
        = SeveralErrors $ pure singleErrorA <> pure singleErrorB

You may just use List Error when you specify the App and don’t care about Semigroup instance at all, but I wanted to demonstrate how easy it is to change from the multi-error mode to the single-error mode using one press of a key and here you need a bit more pressing:

type App =
    Ui (List Error) Action Model (Html Action)

Actions, Producing

From now we discuss the update function code, the one without a quote.

There are no cases in this example where several actions would be produced in response to another action, may be it needs improvement.

If there would be one, it would look like this:

pure model /\ pure Dig : pure Catch : pure GoFishing : Nil

For now, it is usually just one:

pure model /\ pure Deliver : Nil
...
pure model /\ pure DeliverFossils : Nil

Effects, Producing

In this implementation each effect is bound to an action, for example to decide if you catch something at all and if you do, what kind of bug you’ve got, we use random numbers and random weight distribution, which is surely an effect:

playerUpdate Catch =
    pure model
    /\ do
        n1 <- Random.random
        n2 <- Random.random
        pure $ Player
             $ decide
                (GetBug $ decide' bugsChoice Tarantula n2)
                GetNoBug 0.4 n1
        : Nil

With the first number n1 we decide by 40% possibility if there is a bug, and then we use the second number n2 to decide which kind of bug exactly, using this weight definition:

bugsChoice
    = (Butterfly /\ 0.40) 
    : (Spider /\ 0.30) 
    : (Ladybug /\ 0.15) 
    : (Caterpillar /\ 0.10) 
    : (Tarantula /\ 0.05)
    : Nil

So, we either return the action GetNoBug or the actionGetBug <SomeBug> in response.

To find a location for the museum, we also use random numbers:

playerUpdate FindMuseumSpot =
    pure model
    /\ (Player <<< LocateMuseumSpot <<< Location
           <$> ((/\) <$> Random.random <*> Random.random)
       ) : Nil

If you are eager to play with the code, take the challenge of implementing the effect of telling the scientific story by Blathers, it should be as easy as these examples.

Errors, Producing

For example, you can’t locate the spot for the museum if it’s open, it only can be closed, so we produce an error if we’ve met that case. Previously I’ve disabled the buttons in the interface if such conditions would happen, but lately I decided that it is better demonstrates the error system if they are always enabled.

To produce an error (and it can be accumulated automatically!), it is just as easy as cover the previous model in the Covered instance together with that error.

playerUpdate (LocateMuseumSpot location) 
    | not model.museum.open = ...
    | otherwise =
        (NoLocatingAllowed # Covered.cover model) /\ Nil

Since we have SeveralErrors there, it is also possible to produce lists of them. Which would be merged automatically with the previous ones thanks to the UI.make' implementation and Semigroup instance.

Some more examples:

playerUpdate Deliver 
    | canDeliver model.museum =
        pure ... /\ pure ConsiderSpecies ... : Nil
    | otherwise =
        (NoSpeciesDeliveryAllowed # Covered.cover model) /\ Nil

playerUpdate DeliverFossils 
    | canDeliverFossils model.museum =
        pure ... /\ pure ConsiderFossils ... : Nil
    | otherwise =
        (NoFossilsDeliveryAllowed # Covered.cover model) /\ Nil

Haven’t I wrote in the first part that I don’t use separate constructors for different errors? I lied!

Finalé

Now that is really it. I hope this pair of articles will find it useful for somebody.

Again, please feel free to comment and everything else is appreciated.

I am shaman_sir in Twitter and usually I post either functional programming things or the things about generative graphics (sometimes my own), and I can promise that more to come, especially where these both topics meet each other. Stay tuned.

Also, my personal blog which demonstrates the weird ways I took to reach the PureScript enlightenment, and where I should add these too articles a bit later:
https://shamansir.github.io/blog/.

Thank you!

PureScript: UI driven by Finite State Machines and Event Streams

Anton Kiłka — Thu, 23 Apr 2020 09:39:04 +0000

I should've call the article ”The Elm Architecture in PureScript”, but both the inner demons and the inner angels said "Oh, dear, no!". Still I can't deny the article covers such topic as well.

Among that, this article covers the easiest way for accumulating errors and recovering to the last successful state of the application in a flick of the wrist (I love that song).

Also I plan to abandon explaining why I chose PureScript and get straight to the details. Just keep in mind that Haskell and PureScript are bro-s: each one is pretending to be radically different, but they share truly a lot of common.

The project I am working on, Noodle, has quite complex UI and API as well. For some time I struggled in finding the proper architecture to define both of them, because my intuition strictly said there are common patterns I am yet too blind to see. In pure functional languages it is really easy to write some shitty code, just not making it public, and reason about it later, while you have everything working and stable. And not to confuse you with the harsh word shitty, I have a bunch of unit tests to ensure the logic is what I expect it to be. Also, I think, in leaning to perfection it is important to know where to do a step off the road for some time and get back to this infinite road with new strengths and visions… but enough morals.

When I discovered the article Finite State Machines in Haskell and read it, everything stood on its place. This was the pattern! Not to oblige you reading the article, the key point is that Finite State Machine is as easy as this function:

finiteStateMachine 
    :: forall action model
     . action -> model -> model

That is our famous ”The Elm Architecture” in its essence, simplified to the origins where it was actually born.

The function, which receives some action (say, DecrementCounter or WithdrawMoney or JustRobThePlace), gets previous model and evaluates to the new modified model. Some people prefer it flipped, so the model comes as the first argument. Those actions are usually the sum types so it is easy to keep them in one place and have a birds-eye view on the processes happening in your application. ¹

Let’s move the practical example to another part of the article and for now mostly speak theory. Don’t be confused, in the end of this part I’ll give the complete working code for FSM using FRP, since it’s just a few lines of code. First, we will define the signature, then the way to make it and, finally, run it.

Considering Effects

Both the UI and API in my case require some side effects to be performed. For API it’s, for example, generating a random UUID for any new entity. And, since I use FRP events, subscribing to event streams or cancelling them is also a side effect. In case of UI, it is Event.stopPropagation (where event is HTML event, not the FRP one), requestAnimationFrame, drawing on canvas, some connections to JavaScript using FFI. Some of such effects should be Aff though, since they are asynchronous, but it doesn’t really affect what we discuss in any matter.

Separating effects from the pure actions is very important in pure functional languages, still it doesn’t mean you can’t use them, just keep them marked as such and, preferably, sorted (see below).

finiteStateMachine 
    :: forall action model
     . action -> model -> Effect model

In Elm, every update function returns Cmd along with the model, which is also the wrapper for the effects, still you may need some effort to realise it. Actually, they separate model from the effects, and that’s smart thing to do, so let’s do the same:

finiteStateMachine 
    :: forall action model
     . action -> model -> model /\ Effect Unit

If you ever used the Spork library, you may want to draw attention to the fact that they also use a sum type to describe effects. So in my case they would have NewUUID and StopPropagation constructors for the effect type instances and functions like:

finiteStateMachine 
    :: forall action model effect
     . action -> model -> model /\ List effect

performEffect 
    :: forall effect
     . effect -> Effect Unit

Where performEffect is performed after every call to FSM. That’s a really good way to sort the effects and don’t put them into one basket. But I decided not to do that in the end: I had such code before and may be I’ll get it back in some form, but during the rewriting stage I wanted not to bother thinking about that, and now I have the working code, which is open to return to this approach, at some point, maybe. Just please notice that it’s really something to think through.

Actually the Elm’s Cmd is doing the similar thing by requiring you to provide functions which return specific actions, but more on that later, just in the next chapter.

If you have considered that, let’s get back to the latest specification and stick with it in the end of this section:

finiteStateMachine 
    :: forall action model
     . action -> model -> model /\ Effect Unit

The article on Haskell’s way covers it really well with the examples using IO, which is the same concept as Effect in PureScript.

Recursing to Actions

If you are willing to keep actions minimalistic, meaning that each action is modifying the model in one single and predictable way, defined by the name of such action (e.g. not just RobTheBank, but rather splitting it into BuyToyShotgun, DefineWorkingHours, FindOutSecuritySchedule, WearMask, EnterTheBank, GetToCachier, TryNotToPee and so on, it’s not me to give you details on how to do it, just visit wikihow.com on robbing banks), you would see that one action sometimes requires other actions to be performed. Without wearing a mask, it’s better not to start the robbing procedure at all (depends on your case, for sure).

So it becomes handy to return the list of the actions to perform next, which can be empty, of course.

finiteStateMachine 
    :: forall action model
     . action -> model -> model /\ List action

If you are still thinking about Elm, you may recall that Cmd.batch thing, which represents effects that are evaluated from update function where every effect is bound to the specific action. Let’s also join this concept with the specification of effects we did previously:

finiteStateMachine 
    :: forall action model
     . action -> model -> model /\ Effect (List action)

It could be another way around:

finiteStateMachine 
    :: forall action model
     . action -> model -> model /\ List (Effect action)

This way you can not share data between the effects you perform, only with carrying them together with actions. Which is really a good thing for making things really pure and minimalistic. But I decided to avoid that for the sake of simplicity, still you are always free to choose the proper way by just replacing one with another and make it compile.

I also made some helpers to refrain from typing pure in the end of do-blocks a lot. If you use List (Effect action) technique, you don’t need them, obviously:

doNothing :: forall action. Effect (List action)
doNothing = pure []

single :: forall action. action -> Effect (List action)
single = pure <<< List.singleton

batch :: forall action. List action -> Effect (List action)
batch = pure

At this point, we are ready to define our data type:

data FSM action model = 
    FSM (action -> model -> model /\ Effect (List action))

Let’s also define the function to create such instances, which is just a type constructor for now, but we leave the opportunity for it to be changed later:

make 
    :: forall action model
     . (action -> model -> model /\ Effect (List action))
    -> FSM action model
make = FSM

That’s actually it! We can represent all other things just with reusing this one.

Errors, Introducing `Covered`

I have to confess that I am using my own data type to work with errors. As much of you probably did, I researched the problem of accumulating errors (no, I do swear I have no intention to have separate types for them!) and no solution satisfied me, except this one:

data Covered e a
    = Carried a
    | Recovered e a

Where Carried means we carry the value and it’s all good. And Recovered means we had some error and the value was recovered from that failure. It just always stores the last successful value, along with the error, when it had un-fortune to happen. The single and the latest error, same as for value,.. unless you have Semigroup e => Covered e a!

Imagine you are cooking something and if you have forgot to buy some ingredient, you just skip it and happily continue the process, but notice such failure in the list of failures to avoid in the future. Or you broke the eggs together with the eggshells while preparing the cake, so you just suck the eggs and the eggshells back from the stock, and it’s all fine, you just put a notice near the cake that eggshells were there, and the eggs were also required to be reverted due to error, but it’s all clean now, bon appétit. Seems I am not that good in examples.

So the FSM, where it is possible to keep the last error (or accumulate errors), looks like this:

type CoveredFSM error action model =
    FSM action (Covered error model)

But since we need to alter the update function behaviour, and it should be imprinted in the logic of such machine, it could be better to make it a data type (and ensure to hide the constructor):

data CoveredFSM error action model =
    CoveredFSM (FSM action (Covered error model))

Since Either is the purest way of dealing with errors, I use it as an atomic part of the API: every function that belongs to the core API and can fail with some error, evaluates to Either and nothing else. So does the update function that wraps the API, except that inbetween the calls, after the action was applied to the model, it either (no pun intended) replaces Either with the Covered, holding the previous model (which we always have in update function) or, if the error type satisfies Semigroup typeclass, it glues the errors from the previous call with the ones from the ongoing call.

But first, let’s review the approach where we just store the last error and rollback to a last successful state. For that you’ll need a function that moves the error from one Covered instance to another, if there is one. The function is simple:

consider 
    :: forall e a
     . Covered e a -> Covered e a -> Covered e a
consider (Recovered errA _) (Carried vB) = Recovered errA vB
consider _ coveredB = coveredB

It seems to satisfy Alt laws (but not Alternative), so we may assign the <|> operator for it. And this way you can use this function for folding the event streams of Covered values, for example.

instance coveredAlt :: Alt (Covered e) where
    alt = consider

And so we need to define custom make function for CoveredFSM:

make 
    :: forall error action model
     . (action 
            -> Covered error model 
            -> Covered error model /\ Effect (List action))
    -> CoveredFSM action model 
make updateF =   
    CoveredFSM
        $ FSM.make \action model ->
            let model' /\ effects' = updateF action model
            in (model <|> model') /\ effects'

If storing the last error satisfies your needs, you could stop at this point.

If you want to store all the errors happened, you’ll need some function to append errors from one Covered instance to another. Let’s call it appendErrors—it’s not Semigroup’s append, since it operates on errors rather than values:

appendErrors 
      :: forall e a b
     . Semigroup e 
    => Covered e a -> Covered e b -> Covered e b
appendErrors (Recovered errorsA _) (Recovered errorsB valB) = 
    Recovered (errorsA <> errorsB) valB
appendErrors (Recovered errorsA _) (Carried valB) = 
    Recovered errorsA valB
appendErrors (Carried _) coveredB = 
    coveredB

And it’s update function looks like this:

make' 
    :: forall error action model
     . Semigroup error 
    => (action 
            -> Covered error model 
            -> Covered error model /\ Effect (List action))
    -> CoveredFSM action model 
make' updateF =   
    CoveredFSM
        $ FSM.make \action model ->
            let model' /\ effects' = updateF action model
            in (model `appendErrors` model') /\ effects'

A trained eye may notice a pattern here: we just have one function that changes the way how we join the previous model with the next one. If it sounds like folding to you, I share your inference. By defining a data type or newtype we are ensuring that user uses the proper instance of CoveredFSM and don’t forget to specify the way to glue errors. But that doesn’t prevent us from adding a helper to FSM, such as:

joinWith
    :: forall action model
     . (model -> model -> model)
    -> FSM action model
    -> FSM action model
joinWith joinF (FSM updateF) =
    FSM $ \action model ->
            let model' /\ effects' = updateF action model
            in (model `joinF` model') /\ effects'

And now our make functions become much fancier:

make 
    :: forall error action model
     . (action 
            -> Covered error model 
            -> Covered error model /\ Effect (List action))
    -> CoveredFSM error action model 
make = 
    FSM.make 
        >>> FSM.joinWith ((<|>)) 
        >>> CoveredFSM

make' 
    :: forall error action model
     . Semigroup error 
    => (action 
            -> Covered error model 
            -> Covered error model /\ Effect (List action))
    -> CoveredFSM error action model 
make' =   
    FSM.make 
        >>> FSM.joinWith Covered.appendErrors
        >>> CoveredFSM

One of the downsides of using Covered could be that it’s not that fancy to useCovered in do-notation, rather than its brothers Maybe and Either since (unless you wrap the Either-producing function in Covered later, as noted above) you always have to specify the fallback value and it is usually the same value through all the block. I suppose it could potentially be solved with monad transformers and State monad, and if yes, please tell in the comments how.

FRP and Running

Finally, let’s implement it! Using event streams from the FRP Events Library.

It’s rather simple: we provide the initial model (init), we create the actions stream, and on every push of some action, we call the FSM’s update function on it, skipping the effects from previous update. And we subscribe to the stream of updates to perform all the effects requested after the update. Then we provide user with the ability to push actions into system. Which is quite useful for UIs for example, to push some specific action in response to the HTML event handler.

run
    :: forall action model
     . FSM action model
    -> model
    -> Effect
            { push :: action -> Effect Unit
            , stop :: Effect Unit
            }
run (FSM updateF) init = do
    { event : actions, push } <- Event.create
    let
        (updates :: Event (model /\ Effect (List action))) =
            Event.fold
                (\action prev -> updateF action $ Tuple.fst prev)
                actions
                (init /\ pure [])
    stop <- Event.subscribe updates
        \(_ /\ eff) -> eff >>= traverse_ pushAction
    pure { push, stop }

This has a little sense though, since you have no way to see what models are, so let’s add the ability to specify the subscription to models. The problem with just returning the event stream of models is that if you subscribe to it after the subscription which performs the effects, you get the results of these calls in the model stream as well, which you would probably like to avoid.

run
    :: forall action model
     . FSM action model
    -> (model -> Effect Unit)
    -> model
    -> Effect
            { push :: action -> Effect Unit
            , stop :: Effect Unit
            }
run (FSM updateF) subModels init = do
    { event : actions, push : pushAction } <- Event.create
    let
        (updates :: Event (model /\ Effect (List action))) =
            Event.fold
                (\action prev -> updateF action $ Tuple.fst prev)
                actions
                (init /\ pure [])
        (models :: Event model)
            = Tuple.fst <$> updates
    stopModelSubscription <- Event.subscribe models subModels
    stopPerformingEffects <- Event.subscribe updates
        \(_ /\ eff) -> eff >>= traverse_ pushAction
    pure
        { push : pushAction
        , stop : stopModelSubscription <> stopPerformingEffects
        }

We can use it to fold some list of actions and get the latest model out of it:

fold
    :: forall action model f
     . Foldable f
    => FSM action model
    -> model
    -> f action
    -> Effect model 
fold fsm init actionList = do
    lastValRef <- Ref.new init
    { pushAction, stop } <- 
        FSM.run fsm (flip Ref.write lastValRef) init
    _ <- traverse_ pushAction actionList
    lastVal <- Ref.read lastValRef
    pure lastVal

Running a CoveredFSM instance is just calling the FSM.run for the underlying instance, like this:

run
    :: forall action model
     . CoveredFSM action model
    -> (model -> Effect Unit)
    -> model
    -> Effect
            { push :: action -> Effect Unit
            , stop :: Effect Unit
            }
run (CoveredFSM fsm) = FSM.run fsm

UI, Renderers and VDOM

Now, to the UI part. Finite State Machine only lacks one addition to be able to render model into some view. And this addition is easily represented with a corresponding function:

data UI action model view = 
    UI (FSM action model) (model -> view)

The UI which stores the information about errors is:

type CoveredUI error action model view = 
    UI action (Covered error model) view

Since we hide the FSM under the UI type constructor, we may avoid using CoveredFSM type and provide making functions like these:

make
    :: forall action model view
     . (action -> model -> model /\ Effect (List action))
    -> (model -> view)
    -> UI action model view
make updateF viewF =
    UI (FSM.make updateF) viewF 


makeCovered 
    :: forall error action model view
     . (action 
            -> Covered error model 
            -> Covered error model /\ Effect (List action))
    -> (Covered error model -> view)
    -> UI error action model view
makeCovered updateF viewF = 
    UI (FSM.make updateF # FSM.joinWith (<|>)) viewF


makeCovered'
    :: forall error action model view
     . Semigroup error 
    => (action 
            -> Covered error model 
            -> Covered error model /\ Effect (List action))
    -> (Covered error model -> view)
    -> UI error action model view
makeCovered' updateF viewF = 
    UI (FSM.make updateF 
            # FSM.joinWith Covered.appendErrors) viewF

And, this way running UI is as easy as:

run
    :: forall action model view
     . UI action model view
    -> model
    -> Effect
        { next :: Event view
        , push :: action -> Effect Unit
        , stop :: Canceler
        }
run (UI fsm viewF) model = do
    { event : views, push : pushView } <- Event.create
    { push, stop } <- 
        FSM.run fsm (pushView <<< viewF) (Covered.carry model)
    pure
        { next : views
        , push
        , stop
        }

What user gets is response is the stream of views and we can now feed it to the rendering engine.

Let’s address to Halogen VDOM engine which is distributed in a separate package. First, we now definitely render to HTML:

type HtmlRenderer error action model = 
    CoveredUI error action model (Html action)

Another confession I have to make: currently, yes, it’s the Html from the Spork library. But since in this article we intentionally decline the techniques behind the libraries like Spork for the sake of learning, I had to keep it in secret till the end. Also, it is still up to you which output you want to have, SVG or canvas or text string or may be even you will decide to output to terminal using ASCII, for all views it works the same!

And we’re just giving the specific examples.

This code is a bit more complicated since VDOM and HTML API are both not as friendly as ours, but still it works like a charm:

embed
    :: forall action model
     . String
    -> HtmlRenderer action model -- renderer
    -> model -- initial model
    -> Effect Unit
embed sel render firstModel = do
    doc <- DOM.window >>= DOM.document
    mbEl <- DOM.querySelector 
                (wrap sel) 
                (HTMLDocument.toParentNode doc)
    case mbEl of
        Nothing -> throwException 
                    (error $ "Element does not exist: " <> sel)
        Just el -> do
            { next, push } 
                <- UI.run renderer firstModel
            let
                vdomSpec = V.VDomSpec
                    { document : HTMLDocument.toDocument doc
                    , buildWidget: buildThunk unwrap
                    , buildAttributes: P.buildProp push
                    }
            first_vdom <- EFn.runEffectFn1
                            (V.buildVDom vdomSpec)
                            (unwrap 
                                $ UI.view renderer 
                                $ Covered.carry firstModel)
            vdom_ref <- Ref.new first_vdom
            void $ DOM.appendChild 
                    (Machine.extract first_vdom) 
                    (DOMElement.toNode el)
            cancel <- Event.subscribe next $
                \next_view -> do
                    prev_vdom <- Ref.read vdom_ref
                    next_vdom <- EFn.runEffectFn2 
                                    Machine.step 
                                    prev_vdom 
                                    (unwrap next_view)
                    _ <- Ref.write next_vdom vdom_ref
                    pure unit
            pure unit

Wait… It turns out the VDOM engine uses the Finite State Machines under the hood as well. Just a bit more complicated ones.

The Stub and the Actual App

We need some actual code to work with the system, let’s do some stubs:

data Error = Error

data Action = Action

data Model = Model


init :: Model
init = Model


update 
    :: Action 
    -> Covered Error Model 
    -> Covered Error Model /\ List (Effect Action)
update action covered = covered /\ List.Nil


view 
    :: Covered Error Model 
    -> Html Action
view _ =
    H.div [] [ H.text "example" ]


myRenderer :: HtmlRenderer Error Action Model
myRenderer =
    Ui.makeCovered update view

Finally, your main function can now be as easy as:

main :: Effect Unit
main =
    VDom.embed "#app" myRenderer init

That’s it, folks!

Aftermath

Aftermath One

What we defined as UI is actually containing both application logic (the FSM stored inside) and rendering (model -> view function), so you could want to separate these functions or just rename UI to App and abstract your application by view:

data App action model view = 
    App (FSM action model) (model -> view)

data App' error action model view  = 
    App' 
        (FSM action (Covered error model)) 
        (Covered error model -> view)

type MyApp view = App' Action Model view


myApp :: App Action Model (Html Action)
myApp = Ui.makeCovered update view

It is the same things as HtmlRenderer defined above, so embedding is no different:

main :: Effect Unit
main =
    VDom.embed "#app" myApp init

But now you may reuse the same logic for different views.

Aftermath Two

Another thing. This would be useful to map over the FSM types to convert, for example, FSM action (Either error model) to FSM action (Covered error model) with just one call, but if you try to implement Functor instance for it, you’ll find that to do it we also need a function to convert Covered to Either back, which breaks the Functor logic, of course. But it looks like there’s Invariantfor that!

imapModel
    :: forall action modelA modelB
     . (modelA -> modelB)
    -> (modelB -> modelA)
    -> FSM action modelA
    -> FSM action modelB
imapModel mapAToB mapBToA (Fsm updateF) =
    FSM \action modelB ->
        Bifunctor.bimap mapAToB identity 
            $ updateF action 
            $ mapBToA modelB


instance invariantFSM :: Invariant (FSM action) where
    imap = imapModel

…Unfortunately, no, imap is not enough, because you can not create Covered out of thin air if there’s Left error value in Either part—you need some value to put in Covered. You may use imap for any cases where models are easily converted both one to another and back without the loss of data.

Aftermath Three

Remember I noticed that it’s better to use List (Effect action) rather than Effect (List action)? It indeed is, and it requires just one change in the code of the run function. To replace:

    stopPerformingEffects <- Event.subscribe updates
        \(_ /\ eff) -> eff >>= traverse_ pushAction

with

    stopPerformingEffects <- Event.subscribe updates
        \(_ /\ effs) -> traverse_ ((=<<) pushAction) effs

Done. The example is written using List (Effect Action), by the way.

Aftermath Four

And the last. Covered type has the Bind instance such as (where recover extracts the value from the Covered type):

instance coveredBind 
    :: Semigroup e => Bind (Covered e) where
    bind covered k = appendErrors covered $ k $ recover covered

You’ve seen appendErrors above. So now you know, that you may use >>= anywhere to join errors between two Covered values in any place.

Aftermath Five

One project that inspired me for using PureScript with FRP is Flare. The way it uses Functor and Applicative instances to adapt the values inside of the components is just awesome and they are all just one-liners. So the future plan is to find a way to do similar things with FSMs.

And Everything Else…

Don’t forget to take a look at the example which has the code with the effects, and passing actions from the UI and everything you would question about during reading this article. Hope you enjoyed it.

Also, here is the example source code.

On the other hand, the article could contain errors and misleading information, not intentionally, of course. If you notice such case, please inform the author and the readers as soon as possible by leaving a friendly, yet correcting, comment.

If you see the ways to improve the approach, please also do comment. Even comment if you have ideas on how to do things worse.

There is some controversy on the effectiveness of the approach, but let’s decide the author (for sure) and the reader (hope so) still think the approach is just awesome, if you use it right. ↩

Hi, I'm Anton Kotenko a.k.a. Ulric Wilfred.

Anton Kiłka — Thu, 13 Jul 2017 11:17:15 +0000

I have been coding for 10+ years.

My blog in English language is located here.
My blog in Russian language is located here.

Both were abandoned for several years, but I am slowly returning to the roots.

You can find me on Twitter as @shaman_sir

For almost five years I live in Munich. It was two years in Odessa before that. And from the start I was born in Saint-Petersburg :).

I work for JetBrains GmbH.

I mostly program in these languages: JavaScript, Java, whichever.

I am currently learning more about Elm, Racket, React and Functional Programming in general. I am also quite fascinated with Computer Graphics, User Interfaces, Typography and writing Electronic Music.

I gave several talks throughout these years, the slides for some of them are here and the videos are ... in a lot of places — I'll collect them in one place at some point.

Nice to meet you.