work on making api easier to understand

examples/basic/README.md

@@ -1,8 +1,6 @@
 # examples/basic
-> an intro into an app using `ryannhg/elm-app`
+> a barebones example app made with ryannhg/elm-app
 
-## how to run
+### try it out
 
-1. `npm install`
-
-1. `npm run dev`
+1. `elm reactor`

examples/basic/elm.json

@@ -2,7 +2,7 @@
     "type": "application",
     "source-directories": [
         "src",
-        "../../src"
+        "package"
     ],
     "elm-version": "0.19.0",
     "dependencies": {
@@ -10,11 +10,13 @@
             "elm/browser": "1.0.1",
             "elm/core": "1.0.2",
             "elm/html": "1.0.0",
-            "elm/random": "1.0.0",
+            "elm/http": "2.0.0",
+            "elm/json": "1.1.3",
             "elm/url": "1.0.0"
         },
         "indirect": {
-            "elm/json": "1.1.3",
+            "elm/bytes": "1.0.8",
+            "elm/file": "1.0.5",
             "elm/time": "1.0.0",
             "elm/virtual-dom": "1.0.2"
         }

examples/basic/package/Application/Element.elm

@@ -0,0 +1,167 @@
+module Application.Element exposing
+    ( Application, create
+    , Page
+    , Static, static
+    , Sandbox, sandbox
+    , Element, element
+    , Init, init
+    , Update, update, keep
+    , Bundle, bundle
+    )
+
+{-|
+
+@docs Application, create
+
+@docs Page
+
+@docs Static, static
+
+@docs Sandbox, sandbox
+
+@docs Element, element
+
+@docs Init, init
+
+@docs Update, update, keep
+
+@docs Bundle, bundle
+
+-}
+
+import Application.Internals.Element.Bundle as Bundle
+import Application.Internals.Element.Init as Init
+import Application.Internals.Element.Page as Page
+import Application.Internals.Element.Update as Update
+import Browser
+
+
+
+-- APPLICATION
+
+
+type alias Application flags model msg =
+    Platform.Program flags model msg
+
+
+create :
+    { route : route
+    , pages :
+        { init : route -> Init flags model msg
+        , update : msg -> model -> Update model msg
+        , bundle : model -> Bundle model msg
+        }
+    }
+    -> Application flags model msg
+create config =
+    Browser.element
+        { init = Init.create (config.pages.init config.route)
+        , update = Update.create config.pages.update
+        , view = Bundle.createView config.pages.bundle
+        , subscriptions = Bundle.createSubscriptions config.pages.bundle
+        }
+
+
+
+-- INIT
+
+
+type alias Init flags model msg =
+    Init.Init flags model msg
+
+
+init :
+    Page flags pageModel pageMsg model msg
+    -> Init flags model msg
+init =
+    Init.init
+
+
+
+-- UPDATE
+
+
+type alias Update model msg =
+    Update.Update model msg
+
+
+update :
+    { page : Page flags pageModel pageMsg model msg
+    , model : pageModel
+    , msg : pageMsg
+    }
+    -> Update model msg
+update =
+    Update.update
+
+
+keep : model -> Update model msg
+keep =
+    Update.keep
+
+
+
+-- BUNDLE
+
+
+type alias Bundle model msg =
+    Bundle.Bundle model msg
+
+
+bundle :
+    { page : Page flags pageModel pageMsg model msg
+    , model : pageModel
+    }
+    -> Bundle model msg
+bundle =
+    Bundle.bundle
+
+
+
+-- PAGE
+
+
+type alias Page flags pageModel pageMsg model msg =
+    Page.Page flags pageModel pageMsg model msg
+
+
+type alias Static =
+    Page.Static
+
+
+type alias Sandbox pageModel pageMsg =
+    Page.Sandbox pageModel pageMsg
+
+
+type alias Element flags pageModel pageMsg =
+    Page.Element flags pageModel pageMsg
+
+
+static :
+    { toModel : () -> model
+    , toMsg : Never -> msg
+    , page : Static
+    }
+    -> Page flags () Never model msg
+static =
+    Page.static
+
+
+sandbox :
+    { toModel : pageModel -> model
+    , toMsg : pageMsg -> msg
+    , page : Sandbox pageModel pageMsg
+    }
+    -> Page flags pageModel pageMsg model msg
+sandbox =
+    Page.sandbox
+
+
+element :
+    { toModel : pageModel -> model
+    , toMsg : pageMsg -> msg
+    , page : Element flags pageModel pageMsg
+    }
+    -> Page flags pageModel pageMsg model msg
+element =
+    Page.element

examples/basic/package/Application/Internals/Element/Bundle.elm

@@ -0,0 +1,57 @@
+module Application.Internals.Element.Bundle exposing
+    ( Bundle
+    , bundle
+    , createSubscriptions
+    , createView
+    )
+
+import Application.Internals.Element.Page as Page exposing (Page)
+import Html exposing (Html)
+
+
+type Bundle model msg
+    = Bundle (Bundle_ model msg)
+
+
+type alias Bundle_ model msg =
+    { view : model -> Html msg
+    , subscriptions : model -> Sub msg
+    }
+
+
+createView :
+    (model -> Bundle model msg)
+    -> model
+    -> Html msg
+createView fn model =
+    fn model
+        |> (\(Bundle { view }) -> view model)
+
+
+createSubscriptions :
+    (model -> Bundle model msg)
+    -> model
+    -> Sub msg
+createSubscriptions fn model =
+    fn model
+        |> (\(Bundle { subscriptions }) -> subscriptions model)
+
+
+bundle :
+    { page : Page flags pageModel pageMsg model msg
+    , model : pageModel
+    }
+    -> Bundle model msg
+bundle config =
+    let
+        p =
+            Page.unwrap config.page
+    in
+    Bundle
+        { view =
+            always (p.page.view config.model)
+                >> Html.map p.toMsg
+        , subscriptions =
+            always (p.page.subscriptions config.model)
+                >> Sub.map p.toMsg
+        }

examples/basic/package/Application/Internals/Element/Init.elm

@@ -0,0 +1,38 @@
+module Application.Internals.Element.Init exposing
+    ( Init
+    , create
+    , init
+    )
+
+import Application.Internals.Element.Page as Page exposing (Page)
+
+
+type Init flags model msg
+    = Init (Init_ flags model msg)
+
+
+type alias Init_ flags model msg =
+    flags -> ( model, Cmd msg )
+
+
+init :
+    Page flags pageModel pageMsg model msg
+    -> Init flags model msg
+init page =
+    let
+        p =
+            Page.unwrap page
+    in
+    Init
+        (\flags ->
+            p.page.init flags
+                |> Tuple.mapBoth p.toModel (Cmd.map p.toMsg)
+        )
+
+
+create :
+    Init flags model msg
+    -> flags
+    -> ( model, Cmd msg )
+create (Init fn) =
+    fn

examples/basic/package/Application/Internals/Element/Page.elm

@@ -0,0 +1,124 @@
+module Application.Internals.Element.Page exposing
+    ( Page
+    , Static, static
+    , Sandbox, sandbox
+    , Element, element
+    , unwrap
+    )
+
+{-|
+
+@docs Page
+
+@docs Static, static
+@docs Sandbox, sandbox
+@docs Element, element
+
+@docs unwrap
+
+-}
+
+import Html exposing (Html)
+
+
+type Page flags pageModel pageMsg model msg
+    = Page (Page_ flags pageModel pageMsg model msg)
+
+
+type alias Page_ flags pageModel pageMsg model msg =
+    { toModel : pageModel -> model
+    , toMsg : pageMsg -> msg
+    , page :
+        { init : flags -> ( pageModel, Cmd pageMsg )
+        , update : pageMsg -> pageModel -> ( pageModel, Cmd pageMsg )
+        , view : pageModel -> Html pageMsg
+        , subscriptions : pageModel -> Sub pageMsg
+        }
+    }
+
+
+unwrap :
+    Page flags pageModel pageMsg model msg
+    -> Page_ flags pageModel pageMsg model msg
+unwrap (Page page) =
+    page
+
+
+
+-- STATIC
+
+
+type alias Static =
+    { view : Html Never
+    }
+
+
+static :
+    { toModel : () -> model
+    , toMsg : Never -> msg
+    , page : Static
+    }
+    -> Page flags () Never model msg
+static page =
+    Page
+        { toModel = page.toModel
+        , toMsg = page.toMsg
+        , page =
+            { init = \_ -> ( (), Cmd.none )
+            , update = \_ model -> ( model, Cmd.none )
+            , view = \_ -> Html.map never page.page.view
+            , subscriptions = \_ -> Sub.none
+            }
+        }
+
+
+
+-- SANDBOX
+
+
+type alias Sandbox pageModel pageMsg =
+    { init : pageModel
+    , update : pageMsg -> pageModel -> pageModel
+    , view : pageModel -> Html pageMsg
+    }
+
+
+sandbox :
+    { toModel : pageModel -> model
+    , toMsg : pageMsg -> msg
+    , page : Sandbox pageModel pageMsg
+    }
+    -> Page flags pageModel pageMsg model msg
+sandbox page =
+    Page
+        { toModel = page.toModel
+        , toMsg = page.toMsg
+        , page =
+            { init = \_ -> ( page.page.init, Cmd.none )
+            , update = \_ model -> ( model, Cmd.none )
+            , view = page.page.view
+            , subscriptions = \_ -> Sub.none
+            }
+        }
+
+
+
+-- ELEMENT
+
+
+type alias Element flags pageModel pageMsg =
+    { init : flags -> ( pageModel, Cmd pageMsg )
+    , update : pageMsg -> pageModel -> ( pageModel, Cmd pageMsg )
+    , view : pageModel -> Html pageMsg
+    , subscriptions : pageModel -> Sub pageMsg
+    }
+
+
+element :
+    { toModel : pageModel -> model
+    , toMsg : pageMsg -> msg
+    , page : Element flags pageModel pageMsg
+    }
+    -> Page flags pageModel pageMsg model msg
+element =
+    Page

examples/basic/package/Application/Internals/Element/Update.elm

@@ -0,0 +1,48 @@
+module Application.Internals.Element.Update exposing
+    ( Update
+    , create
+    , keep
+    , update
+    )
+
+import Application.Internals.Element.Page as Page exposing (Page)
+
+
+type Update model msg
+    = Update (Update_ model msg)
+
+
+type alias Update_ model msg =
+    ( model, Cmd msg )
+
+
+create :
+    (msg -> model -> Update model msg)
+    -> msg
+    -> model
+    -> ( model, Cmd msg )
+create fn msg model =
+    fn msg model
+        |> (\(Update result) -> result)
+
+
+update :
+    { page : Page flags pageModel pageMsg model msg
+    , model : pageModel
+    , msg : pageMsg
+    }
+    -> Update model msg
+update config =
+    let
+        p =
+            Page.unwrap config.page
+    in
+    Update
+        (p.page.update config.msg config.model
+            |> Tuple.mapBoth p.toModel (Cmd.map p.toMsg)
+        )
+
+
+keep : model -> Update model msg
+keep model =
+    Update ( model, Cmd.none )

examples/basic/package/Application/Internals/Sandbox/Bundle.elm

@@ -0,0 +1,43 @@
+module Application.Internals.Sandbox.Bundle exposing
+    ( Bundle
+    , bundle
+    , createView
+    )
+
+import Application.Internals.Sandbox.Page as Page exposing (Page)
+import Html exposing (Html)
+
+
+type Bundle model msg
+    = Bundle (Bundle_ model msg)
+
+
+type alias Bundle_ model msg =
+    { view : model -> Html msg
+    }
+
+
+createView :
+    (model -> Bundle model msg)
+    -> model
+    -> Html msg
+createView fn model =
+    fn model
+        |> (\(Bundle { view }) -> view model)
+
+
+bundle :
+    { page : Page pageModel pageMsg model msg
+    , model : pageModel
+    }
+    -> Bundle model msg
+bundle config =
+    let
+        p =
+            Page.unwrap config.page
+    in
+    Bundle
+        { view =
+            always (p.page.view config.model)
+                >> Html.map p.toMsg
+        }

examples/basic/package/Application/Internals/Sandbox/Init.elm

@@ -0,0 +1,29 @@
+module Application.Internals.Sandbox.Init exposing
+    ( Init
+    , create
+    , init
+    )
+
+import Application.Internals.Sandbox.Page as Page exposing (Page)
+
+
+type Init model
+    = Init model
+
+
+init :
+    Page pageModel pageMsg model msg
+    -> Init model
+init page =
+    let
+        p =
+            Page.unwrap page
+    in
+    Init (p.page.init |> p.toModel)
+
+
+create :
+    Init model
+    -> model
+create (Init value) =
+    value

examples/basic/package/Application/Internals/Sandbox/Page.elm

@@ -0,0 +1,91 @@
+module Application.Internals.Sandbox.Page exposing
+    ( Page
+    , Static, static
+    , Sandbox, sandbox
+    , unwrap
+    )
+
+{-|
+
+@docs Page
+
+@docs Static, static
+
+@docs Sandbox, sandbox
+
+@docs unwrap
+
+-}
+
+import Html exposing (Html)
+
+
+type Page pageModel pageMsg model msg
+    = Page (Page_ pageModel pageMsg model msg)
+
+
+type alias Page_ pageModel pageMsg model msg =
+    { toModel : pageModel -> model
+    , toMsg : pageMsg -> msg
+    , page : Config pageModel pageMsg model msg
+    }
+
+
+type Config pageModel pageMsg model msg
+    = StaticConfig Static
+    | SandboxConfig (Sandbox pageModel pageMsg)
+
+
+unwrap :
+    Page pageModel pageMsg model msg
+    -> Page_ pageModel pageMsg model msg
+unwrap (Page page) =
+    page
+
+
+
+-- STATIC
+
+
+type alias Static =
+    { view : Html Never
+    }
+
+
+static :
+    { toModel : () -> model
+    , toMsg : Never -> msg
+    , page : Static
+    }
+    -> Page () Never model msg
+static page =
+    Page
+        { toModel = page.toModel
+        , toMsg = page.toMsg
+        , page = StaticConfig page.page
+        }
+
+
+
+-- SANDBOX
+
+
+type alias Sandbox pageModel pageMsg =
+    { init : pageModel
+    , update : pageMsg -> pageModel -> pageModel
+    , view : pageModel -> Html pageMsg
+    }
+
+
+sandbox :
+    { toModel : pageModel -> model
+    , toMsg : pageMsg -> msg
+    , page : Sandbox pageModel pageMsg
+    }
+    -> Page pageModel pageMsg model msg
+sandbox page =
+    Page
+        { toModel = page.toModel
+        , toMsg = page.toMsg
+        , page = SandboxConfig page.page
+        }

examples/basic/package/Application/Internals/Sandbox/Update.elm

@@ -0,0 +1,44 @@
+module Application.Internals.Sandbox.Update exposing
+    ( Update
+    , create
+    , keep
+    , update
+    )
+
+import Application.Internals.Sandbox.Page as Page exposing (Page)
+
+
+type Update model
+    = Update model
+
+
+create :
+    (msg -> model -> Update model)
+    -> msg
+    -> model
+    -> model
+create fn msg model =
+    fn msg model
+        |> (\(Update result) -> result)
+
+
+update :
+    { page : Page pageModel pageMsg model msg
+    , model : pageModel
+    , msg : pageMsg
+    }
+    -> Update model
+update config =
+    let
+        p =
+            Page.unwrap config.page
+    in
+    Update
+        (p.page.update config.msg config.model
+            |> p.toModel
+        )
+
+
+keep : model -> Update model
+keep =
+    Update

examples/basic/package/Application/Sandbox.elm

@@ -0,0 +1,149 @@
+module Application.Sandbox exposing
+    ( Application, create
+    , Page
+    , Static, static
+    , Sandbox, sandbox
+    , Init, init
+    , Update, update, keep
+    , Bundle, bundle
+    )
+
+{-|
+
+@docs Application, create
+
+@docs Page
+
+@docs Static, static
+
+@docs Sandbox, sandbox
+
+@docs Init, init
+
+@docs Update, update, keep
+
+@docs Bundle, bundle
+
+-}
+
+import Application.Internals.Sandbox.Bundle as Bundle
+import Application.Internals.Sandbox.Init as Init
+import Application.Internals.Sandbox.Page as Page
+import Application.Internals.Sandbox.Update as Update
+import Browser
+
+
+
+-- APPLICATION
+
+
+type alias Application model msg =
+    Platform.Program () model msg
+
+
+create :
+    { route : route
+    , pages :
+        { init : route -> Init model
+        , update : msg -> model -> Update model
+        , bundle : model -> Bundle model msg
+        }
+    }
+    -> Application model msg
+create config =
+    Browser.sandbox
+        { init = Init.create (config.pages.init config.route)
+        , update = Update.create config.pages.update
+        , view = Bundle.createView config.pages.bundle
+        }
+
+
+
+-- INIT
+
+
+type alias Init model =
+    Init.Init model
+
+
+init :
+    Page pageModel pageMsg model msg
+    -> Init model
+init =
+    Init.init
+
+
+
+-- UPDATE
+
+
+type alias Update model =
+    Update.Update model
+
+
+update :
+    { page : Page pageModel pageMsg model msg
+    , model : pageModel
+    , msg : pageMsg
+    }
+    -> Update model
+update =
+    Update.update
+
+
+keep : model -> Update model
+keep =
+    Update.keep
+
+
+
+-- BUNDLE
+
+
+type alias Bundle model msg =
+    Bundle.Bundle model msg
+
+
+bundle :
+    { page : Page pageModel pageMsg model msg
+    , model : pageModel
+    }
+    -> Bundle model msg
+bundle =
+    Bundle.bundle
+
+
+
+-- PAGE
+
+
+type alias Page pageModel pageMsg model msg =
+    Page.Page pageModel pageMsg model msg
+
+
+type alias Static =
+    Page.Static
+
+
+type alias Sandbox pageModel pageMsg =
+    Page.Sandbox pageModel pageMsg
+
+
+static :
+    { toModel : () -> model
+    , toMsg : Never -> msg
+    , page : Static
+    }
+    -> Page () Never model msg
+static =
+    Page.static
+
+
+sandbox :
+    { toModel : pageModel -> model
+    , toMsg : pageMsg -> msg
+    , page : Sandbox pageModel pageMsg
+    }
+    -> Page pageModel pageMsg model msg
+sandbox =
+    Page.sandbox

examples/basic/src/Element/Main.elm

@@ -0,0 +1,173 @@
+module Element.Main exposing (main)
+
+import Application.Element as Application
+import Element.Pages.Counter as Counter
+import Element.Pages.Homepage as Homepage
+import Element.Pages.NotFound as NotFound
+import Element.Pages.Random as Random
+
+
+type Route
+    = Homepage
+    | Counter
+    | Random
+    | NotFound
+
+
+type alias Flags =
+    ()
+
+
+main : Program Flags Model Msg
+main =
+    Application.create
+        { route = Random
+        , pages =
+            { init = init
+            , update = update
+            , bundle = bundle
+            }
+        }
+
+
+type Model
+    = HomepageModel Homepage.Model
+    | CounterModel Counter.Model
+    | RandomModel Random.Model
+    | NotFoundModel NotFound.Model
+
+
+type Msg
+    = HomepageMsg Homepage.Msg
+    | CounterMsg Counter.Msg
+    | RandomMsg Random.Msg
+    | NotFoundMsg NotFound.Msg
+
+
+
+-- CAN / SHOULD BE GENERATED
+
+
+type alias Pages =
+    { homepage : Application.Page Flags Homepage.Model Homepage.Msg Model Msg
+    , counter : Application.Page Flags Counter.Model Counter.Msg Model Msg
+    , random : Application.Page Flags Random.Model Random.Msg Model Msg
+    , notFound : Application.Page Flags NotFound.Model NotFound.Msg Model Msg
+    }
+
+
+pages : Pages
+pages =
+    { homepage =
+        Application.static
+            { toModel = HomepageModel
+            , toMsg = HomepageMsg
+            , page = Homepage.page
+            }
+    , counter =
+        Application.sandbox
+            { toModel = CounterModel
+            , toMsg = CounterMsg
+            , page = Counter.page
+            }
+    , random =
+        Application.element
+            { toModel = RandomModel
+            , toMsg = RandomMsg
+            , page = Random.page
+            }
+    , notFound =
+        Application.static
+            { toModel = NotFoundModel
+            , toMsg = NotFoundMsg
+            , page = NotFound.page
+            }
+    }
+
+
+init : Route -> Application.Init Flags Model Msg
+init route =
+    case route of
+        Homepage ->
+            Application.init pages.homepage
+
+        Counter ->
+            Application.init pages.counter
+
+        Random ->
+            Application.init pages.random
+
+        NotFound ->
+            Application.init pages.notFound
+
+
+update : Msg -> Model -> Application.Update Model Msg
+update appMsg appModel =
+    case ( appMsg, appModel ) of
+        ( HomepageMsg msg, HomepageModel model ) ->
+            Application.update
+                { page = pages.homepage
+                , model = model
+                , msg = msg
+                }
+
+        ( HomepageMsg _, _ ) ->
+            Application.keep appModel
+
+        ( CounterMsg msg, CounterModel model ) ->
+            Application.update
+                { page = pages.counter
+                , model = model
+                , msg = msg
+                }
+
+        ( CounterMsg _, _ ) ->
+            Application.keep appModel
+
+        ( RandomMsg msg, RandomModel model ) ->
+            Application.update
+                { page = pages.random
+                , model = model
+                , msg = msg
+                }
+
+        ( RandomMsg _, _ ) ->
+            Application.keep appModel
+
+        ( NotFoundMsg msg, NotFoundModel model ) ->
+            Application.update
+                { page = pages.notFound
+                , model = model
+                , msg = msg
+                }
+
+        ( NotFoundMsg _, _ ) ->
+            Application.keep appModel
+
+
+bundle : Model -> Application.Bundle Model Msg
+bundle appModel =
+    case appModel of
+        HomepageModel model ->
+            Application.bundle
+                { page = pages.homepage
+                , model = model
+                }
+
+        CounterModel model ->
+            Application.bundle
+                { page = pages.counter
+                , model = model
+                }
+
+        RandomModel model ->
+            Application.bundle
+                { page = pages.random
+                , model = model
+                }
+
+        NotFoundModel model ->
+            Application.bundle
+                { page = pages.notFound
+                , model = model
+                }

examples/basic/src/Element/Pages/Counter.elm

@@ -0,0 +1,50 @@
+module Element.Pages.Counter exposing (Model, Msg, page)
+
+import Application.Element as Application
+import Html exposing (..)
+import Html.Events as Events
+
+
+type alias Model =
+    { counter : Int
+    }
+
+
+type Msg
+    = Increment
+    | Decrement
+
+
+page : Application.Sandbox Model Msg
+page =
+    { init = init
+    , update = update
+    , view = view
+    }
+
+
+init : Model
+init =
+    { counter = 0 }
+
+
+update : Msg -> Model -> Model
+update msg model =
+    case msg of
+        Increment ->
+            { model | counter = model.counter + 1 }
+
+        Decrement ->
+            { model | counter = model.counter - 1 }
+
+
+view : Model -> Html Msg
+view model =
+    div []
+        [ h1 [] [ text "Counter" ]
+        , div []
+            [ button [ Events.onClick Decrement ] [ text "-" ]
+            , p [] [ text (String.fromInt model.counter) ]
+            , button [ Events.onClick Increment ] [ text "+" ]
+            ]
+        ]

examples/basic/src/Element/Pages/Homepage.elm

@@ -0,0 +1,26 @@
+module Element.Pages.Homepage exposing (Model, Msg, page)
+
+import Application.Element as Application
+import Html exposing (..)
+
+
+type alias Model =
+    ()
+
+
+type alias Msg =
+    Never
+
+
+page : Application.Static
+page =
+    { view = view
+    }
+
+
+view : Html Msg
+view =
+    div []
+        [ h1 [] [ text "Homepage" ]
+        , p [] [ text "Very boring tho..." ]
+        ]

examples/basic/src/Element/Pages/NotFound.elm

@@ -0,0 +1,26 @@
+module Element.Pages.NotFound exposing (Model, Msg, page)
+
+import Application.Element as Application
+import Html exposing (..)
+
+
+type alias Model =
+    ()
+
+
+type alias Msg =
+    Never
+
+
+page : Application.Static
+page =
+    { view = view
+    }
+
+
+view : Html Msg
+view =
+    div []
+        [ h1 [] [ text "Page not found..." ]
+        , p [] [ text "what a shame!" ]
+        ]

examples/basic/src/Element/Pages/Random.elm

@@ -0,0 +1,79 @@
+module Element.Pages.Random exposing (Model, Msg, page)
+
+import Application.Element as Application
+import Html exposing (..)
+import Html.Attributes as Attr
+import Html.Events as Events
+import Http
+import Json.Decode as Json exposing (Decoder)
+
+
+type alias Model =
+    { url : Maybe String
+    }
+
+
+type Msg
+    = FetchCat
+    | CatResponded (Result Http.Error String)
+
+
+page : Application.Element () Model Msg
+page =
+    { init = init
+    , update = update
+    , view = view
+    , subscriptions = always Sub.none
+    }
+
+
+init : () -> ( Model, Cmd Msg )
+init _ =
+    ( { url = Nothing }
+    , Cmd.none
+    )
+
+
+decoder : Decoder String
+decoder =
+    Json.field "file" Json.string
+
+
+update : Msg -> Model -> ( Model, Cmd Msg )
+update msg model =
+    case msg of
+        FetchCat ->
+            ( model
+            , Http.get
+                { url = "https://aws.random.cat/meow"
+                , expect = Http.expectJson CatResponded decoder
+                }
+            )
+
+        CatResponded (Ok url) ->
+            ( { model | url = Just url }
+            , Cmd.none
+            )
+
+        CatResponded (Err _) ->
+            ( { model | url = Nothing }
+            , Cmd.none
+            )
+
+
+view : Model -> Html Msg
+view model =
+    div []
+        [ h1 [] [ text "Cat mode" ]
+        , div []
+            [ button [ Events.onClick FetchCat ] [ text "gimme a cat" ]
+            , case model.url of
+                Just url ->
+                    p []
+                        [ img [ Attr.style "width" "200px", Attr.src url ] []
+                        ]
+
+                Nothing ->
+                    text ""
+            ]
+        ]

examples/basic/src/Sandbox/Main.elm

@@ -0,0 +1,139 @@
+module Sandbox.Main exposing (main)
+
+import Application.Sandbox as Application
+import Sandbox.Pages.Counter as Counter
+import Sandbox.Pages.Homepage as Homepage
+import Sandbox.Pages.NotFound as NotFound
+
+
+type Route
+    = Homepage
+    | Counter
+    | NotFound
+
+
+main : Program () Model Msg
+main =
+    Application.create
+        { route = Counter
+        , pages =
+            { init = init
+            , update = update
+            , bundle = bundle
+            }
+        }
+
+
+type Model
+    = HomepageModel Homepage.Model
+    | CounterModel Counter.Model
+    | NotFoundModel NotFound.Model
+
+
+type Msg
+    = HomepageMsg Homepage.Msg
+    | CounterMsg Counter.Msg
+    | NotFoundMsg NotFound.Msg
+
+
+
+-- CAN / SHOULD BE GENERATED
+
+
+type alias Pages =
+    { homepage : Application.Page Homepage.Model Homepage.Msg Model Msg
+    , counter : Application.Page Counter.Model Counter.Msg Model Msg
+    , notFound : Application.Page NotFound.Model NotFound.Msg Model Msg
+    }
+
+
+pages : Pages
+pages =
+    { homepage =
+        Application.static
+            { toModel = HomepageModel
+            , toMsg = HomepageMsg
+            , page = Homepage.page
+            }
+    , counter =
+        Application.sandbox
+            { toModel = CounterModel
+            , toMsg = CounterMsg
+            , page = Counter.page
+            }
+    , notFound =
+        Application.static
+            { toModel = NotFoundModel
+            , toMsg = NotFoundMsg
+            , page = NotFound.page
+            }
+    }
+
+
+init : Route -> Application.Init Model
+init route =
+    case route of
+        Homepage ->
+            Application.init pages.homepage
+
+        Counter ->
+            Application.init pages.counter
+
+        NotFound ->
+            Application.init pages.notFound
+
+
+update : Msg -> Model -> Application.Update Model
+update appMsg appModel =
+    case ( appMsg, appModel ) of
+        ( HomepageMsg msg, HomepageModel model ) ->
+            Application.update
+                { page = pages.homepage
+                , model = model
+                , msg = msg
+                }
+
+        ( HomepageMsg _, _ ) ->
+            Application.keep appModel
+
+        ( CounterMsg msg, CounterModel model ) ->
+            Application.update
+                { page = pages.counter
+                , model = model
+                , msg = msg
+                }
+
+        ( CounterMsg _, _ ) ->
+            Application.keep appModel
+
+        ( NotFoundMsg msg, NotFoundModel model ) ->
+            Application.update
+                { page = pages.notFound
+                , model = model
+                , msg = msg
+                }
+
+        ( NotFoundMsg _, _ ) ->
+            Application.keep appModel
+
+
+bundle : Model -> Application.Bundle Model Msg
+bundle appModel =
+    case appModel of
+        HomepageModel model ->
+            Application.bundle
+                { page = pages.homepage
+                , model = model
+                }
+
+        CounterModel model ->
+            Application.bundle
+                { page = pages.counter
+                , model = model
+                }
+
+        NotFoundModel model ->
+            Application.bundle
+                { page = pages.notFound
+                , model = model
+                }

examples/basic/src/Sandbox/Pages/Counter.elm

@@ -0,0 +1,50 @@
+module Sandbox.Pages.Counter exposing (Model, Msg, page)
+
+import Application.Sandbox as Application
+import Html exposing (..)
+import Html.Events as Events
+
+
+type alias Model =
+    { counter : Int
+    }
+
+
+type Msg
+    = Increment
+    | Decrement
+
+
+page : Application.Sandbox Model Msg
+page =
+    { init = init
+    , update = update
+    , view = view
+    }
+
+
+init : Model
+init =
+    { counter = 0 }
+
+
+update : Msg -> Model -> Model
+update msg model =
+    case msg of
+        Increment ->
+            { model | counter = model.counter + 1 }
+
+        Decrement ->
+            { model | counter = model.counter - 1 }
+
+
+view : Model -> Html Msg
+view model =
+    div []
+        [ h1 [] [ text "Counter" ]
+        , div []
+            [ button [ Events.onClick Decrement ] [ text "-" ]
+            , p [] [ text (String.fromInt model.counter) ]
+            , button [ Events.onClick Increment ] [ text "+" ]
+            ]
+        ]

examples/basic/src/Sandbox/Pages/Homepage.elm

@@ -0,0 +1,26 @@
+module Sandbox.Pages.Homepage exposing (Model, Msg, page)
+
+import Application.Sandbox as Application
+import Html exposing (..)
+
+
+type alias Model =
+    ()
+
+
+type alias Msg =
+    Never
+
+
+page : Application.Static
+page =
+    { view = view
+    }
+
+
+view : Html Msg
+view =
+    div []
+        [ h1 [] [ text "Homepage" ]
+        , p [] [ text "Very boring tho..." ]
+        ]

examples/basic/src/Sandbox/Pages/NotFound.elm

@@ -0,0 +1,26 @@
+module Sandbox.Pages.NotFound exposing (Model, Msg, page)
+
+import Application.Sandbox as Application
+import Html exposing (..)
+
+
+type alias Model =
+    ()
+
+
+type alias Msg =
+    Never
+
+
+page : Application.Static
+page =
+    { view = view
+    }
+
+
+view : Html Msg
+view =
+    div []
+        [ h1 [] [ text "Page not found..." ]
+        , p [] [ text "what a shame!" ]
+        ]

examples/complete/README.md

@@ -0,0 +1,8 @@
+# examples/basic
+> an intro into an app using `ryannhg/elm-app`
+
+## how to run
+
+1. `npm install`
+
+1. `npm run dev`

examples/complete/elm.json

@@ -0,0 +1,26 @@
+{
+    "type": "application",
+    "source-directories": [
+        "src",
+        "../../src"
+    ],
+    "elm-version": "0.19.0",
+    "dependencies": {
+        "direct": {
+            "elm/browser": "1.0.1",
+            "elm/core": "1.0.2",
+            "elm/html": "1.0.0",
+            "elm/random": "1.0.0",
+            "elm/url": "1.0.0"
+        },
+        "indirect": {
+            "elm/json": "1.1.3",
+            "elm/time": "1.0.0",
+            "elm/virtual-dom": "1.0.2"
+        }
+    },
+    "test-dependencies": {
+        "direct": {},
+        "indirect": {}
+    }
+}