Rich interactive notebooks with elm-markup

Whether it's Observable, Google Colab or Jupyter, I love interactive notebooks. If none of these names are familiar, such notebooks are documents where regular text snippets, headings etc. mingle with working code snippets. They are great communication tools and allow a kind of fluid play with code that is hard to get inside regular IDE's.

I have been interested in making my own interactive notebooks for a long time not because there was anything missing in existing solutions, but because a lot of the times I find them to be too flexible: if a notebook allows its user to change everything, they can also be break its logic pretty easily and with little help towards recovery.

And besides, how much effort would it take to make an interactive notebook on my own terms anyway...

Well, without good crutches, probably a lot, so I didn't attempt it right until I stumbled upon a package in the Elm programming language called elm-markup. Turns out, making a basic interactive notebook in it is much simpler than I had imagined: just under 200 lines and without even touching the package's more involved modules.

This experiment is what brings me to writing this series of blog posts, covering a delightful journey looking at interactive notebooks using elm-markup. We will start with a simple counter app, working our way up to some interactive drawings.

What is elm-markup?

It is officially described as the Elm-friendly markup language, one that brings Elm's promise of type safety and friendly error messages into the world of markup languages. Roughly speaking, I would sum it up as a kind of markup language that exposes its own internal structure (AST) so we can render it as we please: plain text, HTML, elm-ui, or any other Elm value really. Spoiler: in this post, we will be turning markup into functions.

tldr the full example with comments is available in this Ellie. The rest of the post will go over it in detail.

A basic elm-markup document

Let's define a simple Title block. This block would tell elm-markup that whenever it sees this piece of text:

|> Title Interactive counteradder 

It should render the indented text inside an h1 tag. The code for that would look like this:

titleBlock : Mark.Block (Html msg) titleBlock = Mark.block "Title" (\str -> h1 [] [ text str ] ) Mark.string 

Using this block, we can create a document like so:

Mark.compile (Mark.document identity titleBlock) """ |> Title Interactive counteradder """ 

Rendering this into a running Elm app involves a few more steps that will become clear later in the post. If you're curious, the package docs are your friends.

Adding a counter

The second block we will define is a named counter that renders some UI and emits the updated value as a message. The markup syntax looks like this:

|> Counter name = var1 

And without further ado, here is the code for it:

counterBlock : Mark.Block (Html ( String, Float )) counterBlock = Mark.record "Counter" (\name -> let -- This is a placeholder value -- We'll wire this up to proper state values in the next step val = 0 in div [] [ text (name ++ " = ") , button [ onClick ( name, val - 1 ) ] [ text "-" ] , text (String.fromFloat val) , button [ onClick ( name, val + 1 ) ] [ text "+" ] ] ) |> Mark.field "name" Mark.string |> Mark.toBlock 

Adding interactivity

So far, this elm-markup document looks pretty static. In order to make it interactive and link counters to actual values by name, we will parse these them into functions that will allow us to inject values stored in the application model. This mind-bend is probably best illustrated by this shift in type signatures for the rendered block:

-- before counterBlock : Mark.Block (Html ( String, Float )) counterBlock = _ -- after type alias Values = Dict.Dict String Float counterBlock : Mark.Block (Values -> Html ( String, Float )) counterBlock = _ 

There is nothing inherent in elm-markup that would stop us from taking this shift: if we're in charge of what value a piece of markup renders to, it might as well be a function. We can use this function to inject a dictionary of Values directly from our model and wire up the (String, Float) events that changes it in response to interacting with the counter buttons.

Our finished counter block looks like this:

-- We will use this helper throughout the rest of the example getValue : String -> Values -> Float getValue name values = values |> Dict.get name -- Values that are not kept track of yet are assumed to be the default |> Maybe.withDefault 0 counterBlock : Mark.Block (Values -> Html ( String, Float )) counterBlock = Mark.record "Counter" (\name values -> let value = getValue name values in div [] [ text (name ++ " = ") , button [ onClick ( name, value - 1 ) ] [ text "-" ] , text (String.fromFloat value) , button [ onClick ( name, value + 1 ) ] [ text "+" ] ] ) |> Mark.field "name" Mark.string |> Mark.toBlock 

Doing something with our values

Now that our wiring is complete, we can simply define a Sum block that works with this markup:

|> Counter name = var1 |> Counter name = var2 |> Sum arg1 = var1 arg2 = var2 

What this block will do is simply take the values from the two named counters, add them together, and communicate the result as var1 + var2 == 3.

The sum block implementation looks like this:

sumBlock : Mark.Block (Values -> Html ( String, Float )) sumBlock = Mark.record "Sum" (\arg1 arg2 values -> let res = getValue arg1 values + getValue arg2 values in div [] [ text (arg1 ++ " + " ++ arg2 ++ " == ") , text (String.fromFloat res) ] ) |> Mark.field "arg1" Mark.string |> Mark.field "arg2" Mark.string |> Mark.toBlock 

Wiring it all up

Now that we have our blocks, we can write a method that compiles a document like this one:

markup : String markup = """ |> Title Interactive counteradder |> Counter name = var1 |> Counter name = var2 |> Sum arg1 = var1 arg2 = var2 """ 

The compiler for it would look like this:

compileMarkup : String -> Result String (Values -> Html ( String, Float )) compileMarkup markdownBody = Mark.compile (Mark.document identity (Mark.manyOf [ titleBlock , counterBlock , sumBlock ] ) ) markdownBody |> (\res -> case res of Mark.Success blocks -> Ok (\data -> div [] (List.map -- Inject data into each block -- This makes them into regular `elm-html` nodes (\block -> block data) blocks ) ) _ -> Err "Compile error" ) 

And finally, the main model, update and view:

type alias Model = { values : Values } type Msg = SetValue ( String, Float ) update : Msg -> Model -> Model update msg model = case msg of SetValue ( key, val ) -> { model | values = Dict.insert key val model.values } view : Model -> Html Msg view model = case compileMarkup markup of -- The success case yields a function that takes the current `Values` dictionary Ok viewByData -> viewByData model.values -- Map to the program message |> map SetValue Err err -> text err 

For a full implementation, head to the full example Ellie or the same code as a gist.

Where will we go next?

I know, I know, adding numbers is not that exciting. Eventually, we'll add sliders to make elm-webgl drawings like this one, interactive.

Until then ☺️