avh4 / elm-debug-controls

Easily build interactive UIs for complex data structures

elm-debug-controls

This package helps you easily build interactive UIs for complex data structures. The resulting controls are not meant for building end-user UIs, but they are useful for quickly building debugging consoles, documentation, and style guides.

Demo

https://avh4.github.io/elm-debug-controls/

Usage

Suppose we have an Elm data structure like the following and want to create a simple debugging tool to experiment with different values:

import Time

type alias UploadRequest =
    { path : String
    , mode : WriteMode
    , autorename : Bool
    , clientModified : Maybe Time.Posix
    , mute : Bool
    , content : String
    }

type WriteMode
    = Add
    | Overwrite
    | Update String

Using elm-debug-controls, we can quickly create an interactive UI to create UploadRequest values:

elm install avh4/elm-debug-controls

import Debug.Control exposing (bool, choice, field, map, record, string, value)

type alias Model =
    { ...
    , uploadRequest : Debug.Control.Control UploadRequest
    }

init : Model
init =
    { ...
    , uploadRequest =
        record UploadRequest
            |> field "path" (string "/demo.txt")
            |> field "mode"
                (choice
                    [ ( "Add", value Add )
                    , ( "Overwrite", value Overwrite )
                    , ( "Update rev", map Update <| string "123abcdef" )
                    ]
                )
            |> field "autorename" (bool False)
            |> field "clientModified"
                (maybe False <| date Time.utc <| Time.millisToPosix 0)
            |> field "mute" (bool False)
            |> field "content" (string "HELLO.")
    }

Now we can hook the control up to our view:

type Msg
    = ...
    | ChangeUploadRequest (Debug.Control.Control UploadRequest)

update : Msg -> Model -> Model
update msg model =
    case msg of
        ...
        ChangeUploadRequest uploadRequest ->
            { model | uploadRequest = uploadRequest }

view : Model -> Html Msg
view model =
    ...
    Debug.Control.view ChangeUploadRequest model.uploadRequest

We now have an interactive UI that looks like this:

Finally, we can use the UploadResponse value elsewhere in our program with:

Debug.Control.currentValue model.uploadRequest

elm-debug-controls's Issues

Make Debug.Control.choice take a nonempty list

In the documentation for Debug.Control.choice it says

This will crash if you provide an empty list.

Why not change the type signature to ( String, Control a ) -> List ( String, Control a ) -> Control a so that can never happen?

Lists of Controls?

Great project!

https://avh4.github.io/elm-debug-controls/ demonstrates how to create, view, and interact with (click on and change) a UploadRequest, but how would one create and view a List UploadRequest? It would be great to be able to have a list of N UploadRequests all of which are interactive. That's what I am trying to do with my own model. I have a record like:

type alias Record = {
  name: String,
  notes: List String,
  things: List Thing
}

type alias Thing = {
  one: String,
  two: Int
}

It's not clear to me from the documentation and code how do to this. I saw that there is a "list" Control, but that doesn't do what I am trying to do, and I haven't been able to figure out exactly how to do it. I'm having a bit of a hard time wrapping my head around exactly how all of this works -- I'm a good developer with functional experience so a lot of it makes sense, but the overall approach is translucent to me currently (though, I can see that it is very cool).

Thank you!

Controls lack labels

For accessibility reasons, it would be nice to have labels for the inputs.

Control.float

It would be great to have something like

Control.float : { min : Float, max : Float } -> Float -> Control Float

implemented as a slider (in my case, I'd like to make some debug UIs for experimenting with different elm-3d-scene parameter values). Control.int could be implemented similarly (with a step size of 1 set on the underlying HTML slider). Happy to submit a PR if that would be helpful!

Add Debug.Control.values

values : List a -> Control a
values = List.map (\x -> (toString x, value x)) >> choice