Base utilities to help Elm developers build UI libraries

Here's a simple UI from the Official Elm Guide:

import Html exposing (Html, button, div, text)
import Html.Events exposing (onClick)

...

view : Model -> Html Msg
view model =
  div []
    [ button [ onClick Decrement ] [ text "-" ]
    , div [] [ text (String.fromInt model) ]
    , button [ onClick Increment ] [ text "+" ]
    ]

Here's how you might implement it with visotype/elm-dom:

import Html exposing (Html)
import Dom exposing (..)

...

view : Model -> Html Msg
view model =
  element "div"
    |> appendChildList
      [ element "button"
        |> addAction ("click", Decrement)
        |> appendText "-"

      , element "div"
        |> appendText (String.fromInt model)

      , element "button"
        |> addAction ("click", Increment)
        |> appendText "+"

      ]
    |> render

The second version looks more verbose, but you'll notice that the Html package's pattern of nested lists has been replaced with pipeline style code that reads from left to right and top to bottom. This can come in handy when generating more complex markup. You'll also notice that HTML properties are encoded as strings rather than as function names. That makes it simpler to pass them as arguments to UI constructors.

Let's say you want to wrap this widget in a function and share it across applications. As a Dom.Element, the outermost div is capable of being modified by appending or prepending child elements, adding attributes, swapping the tag, and so on, which is not possible with rendered Elm Html. This pattern enables UI library developers to bundle sets of minimally-defined reusable parts that users can then modify to meet their needs.

I created this package to make it easier for developers in the Elm community to create, share, and collaborate on libraries of reusable functions for building user interfaces. The package does not implement any specific set of UI constructors (beyond the generic element constructor) and it is not tied to any external dependencies (like a CSS framework). That means you can use this package to create whatever reusable parts you need, with whatever external frameworks you like to use.

• a standard data type for storing information about an individual node in Elm's virtual DOM
• a comprehensive set of functions that allow you to build nodes by updating this information (analogous to methods in the DOM Element API, but really just Elm record updates)
• a simple rendering function that outputs Elm Html

Elm platform 0.19 and the elm/core, elm/json, and elm/virtual-dom packages. Nothing else!

Record update and rendering functions have been tested to ensure functional equivalence with Elm Html constructors. To verify, you can install the elm-test NPM package and run elm-test locally from the package's root directory.

To get started, take a look at any of the examples below, then head over to the core module documentation.

• Button.elm
• Hover.elm
• Capture.elm
• Parse.elm

To run these examples in the browser, download examples/dist and initialize a local web server.

This package is a complete rewrite that includes core parts of several of my earlier attempts at a UI library for Elm. The most recent iteration included the packages elm-semantic-dom and elm-modular-ui, which have since been archived. These previous efforts helped me to identify the core problem I was trying to solve and to eliminate the parts of my code that were just gratuitous abstraction or unnecessary duplication of functionality. The following summarizes what I learned in the process and why I think the current package is a step in the right direction.

If you are using Elm, you probably know all of the reasons why Elm is great. If you've been using Elm for a while, you probably also have some ideas about things that could be done better. One idea that has been explored in a number of community packages is how take advantage of the capabilities of the Elm language to write better view code for Elm sites and apps. "Better" can mean different things to different people, but one goal shared by different community UI packages has been to rely less on literal templating of HTML markup by introducing some sort of abstraction at the element and/or component levels (I'll avoid the word "component" from here on to avoid any possible confusion with React-style stateful components). While there can be a tradeoff in API design between explicit specification and abstraction, good abstractions can help to facilitate rapid prototyping, code sharing, and improved maintainability as sites and apps scale.

UI abstraction has not been a focus of core Elm language development since the early days (pre-2014) when the Elm core library included a set of graphics modules. As part of the effort to take Elm mainstream, these modules were dropped and replaced with the Html and Svg packages, backed by Elm's VirtualDom. Now that the Elm platform is stabilizing and can be used more confidently in production, there is an opportunity for Elm community contributors to create UI libraries that address specific needs, relying on VirtualDom for internals.

In designing an API for a UI library, a lot of decisions need to be made about data structures, naming schemes, and functional patterns (like the order of arguments, whether arguments are given as separate values, tuples, or records, and so on). When package developers make different decisions about these things, it becomes more difficult to use different UI libraries together, either because of a basic incompatibility of patterns, or just because each has its own learning curve and trying to integrate something new will increase development time for the user. This leads to a trend where each UI library is its own island, resulting in duplication of effort and lack of movement toward standard implementations of things that a lot of users in the community would like to have.

Surveying this situation, I wanted to make it easier for developers in the Elm community to create, share, and collaborate on libraries of reusable functions for building user interfaces. Toward this end, the visotype/elm-dom package offers a basic set of utilities for UI development in Elm, including a data type for storing information about an individual node, a comprehensive set of functions that allow you to build nodes by updating this information, and a simple rendering function that outputs Elm Html. The package does not implement any specific set of UI constructors (beyond the generic element constructor) and it is not tied to any external dependencies (like a CSS framework). That means you can use this package to create whatever reusable parts you need, with whatever external frameworks you like to use. The benefit you get is a standard type that can be used across all of your custom UI functions and a thoroughly tested set of utility functions for building, modifying, and rendering nodes.

If you build a UI library with this package, let me know, and I will post a link here.

(c) 2018 Daniel C. Narey. Released under BSD 2-Clause "Simplified" License.