UIExplorer

Component Explorers and Style Guides have been around for a while now. We don't build pages anymore but components that are assembled together to build systems.

In the Elm world, components are just called views, and are defined as pure functions. Elm UI Explorer takes advantage of the composability and the purity of Elm and offers a way to showcase your views and their states in a single tool.

This project is inspired by React Storybook and styled with Bulma.

Anatomy of the UI Explorer

The Explorer is devided into a list of UICategory (ex: Buttons)
Each Category contains some UI items (ex: ToggleButton, ButtonWithImage, SubmitButton etc...)
Each UI item defines states (ex: Loaded, Disabled etc..) that we usually call stories

Main API

app : List UICategory -> Program Never Model Msg

Launches a UI Explorer Applicaton given a list of UI Categories

main =
    app
        (emptyUICategories
            |> addUICategory
                "Atoms"
                [ createUIWithDescription
                    "Colors"
                    "Global Color Schemes"
                    Colors.viewStories
                ]
            |> addUICategory
                "Molecules"
                [ createUI
                    "Card"
                    Card.viewStories
                ]
        )

renderStories : (a -> Html msg) -> List ( String, a ) -> UIViewConfig -> Html Msg

Renders Stories of a given UI. A story represents a state of a view such as (Loading, Error, Success, NoNetwork ...)

stories : List ( String, Model )
stories =
    [ ( "Loading", { isLoading = True } ), ( "Loading", { isLoading = False } ) ]

viewStories = renderStories (view model) stories

Models

type UI

A UI represents a view and lists a set of stories. For Example : A Button with following stories (Loading, Disabled)

type UICategory

Represents a familly of related views. For example using Atomic Design, we can have the following categories : Atoms, Molecules etc..

Helpers

addUICategory : String -> List UI -> List UICategory -> List UICategory

Adds a UI Category to a list of categories Convenient for running a UI Explorer devided into categories

   emptyUICategories
       |> addUICategory
           "A Great Category"
           [ createUI
               "My View"
               MyView.viewStories
           ]

emptyUICategories : List UICategory

Creates an empty list of UI Categories

createUI : String -> (UIViewConfig -> Html Msg) -> UI

Create a UI given an ID and Story Views

stories : List ( String, ButtonModel )
stories =
    [ ( "LargePrimary", { label = "Primary", isLarge = True, isPrimary = True } )
    , ( "TinyPrimary", { label = "Primary", isLarge = False, isPrimary = True } )
    , ( "LargeSecondary", { label = "Secondary", isLarge = True, isPrimary = False } )
    , ( "TinySecondary", { label = "Secondary", isLarge = False, isPrimary = False } )
    ]


viewStories =
    renderStories customButton stories

createUI "Button" viewStories

createUIWithDescription : String -> String -> (UIViewConfig -> Html Msg) -> UI

Create a UI with a description

createUI "Button" "A Simple Button :-)" viewStories

fromUIList : List UI -> List UICategory

Create a list of UICategories from a list of UI and Add them in a Default Category. This is the simplest way to initialize the UI Explorer app.

main =
    app
        (fromUIList
            [ createUI
                "PlayPause"
                PlayPause.viewStories
            , createUI
                "Controls"
                Controls.viewStories
            , createUI
                "TrackList"
                TrackList.viewStories
            ]
        )

Modules

UIExplorer