enhance: parity with elm-land (#791)

src/elm/Auth.elm

@@ -3,7 +3,7 @@ SPDX-License-Identifier: Apache-2.0
 --}
 
 
-module Auth exposing (User, onPageLoad, viewLoadingPage)
+module Auth exposing (User, onPageLoad, viewCustomPage)
 
 import Auth.Action
 import Auth.Session exposing (Session(..))
@@ -39,8 +39,8 @@ onPageLoad shared route =
                 }
 
 
-{-| Renders whenever `Auth.Action.showLoadingPage` is returned from `onPageLoad`.
+{-| Renders whenever `Auth.Action.loadCustomPage` is returned from `onPageLoad`.
 -}
-viewLoadingPage : Shared.Model -> Route () -> View Never
-viewLoadingPage shared route =
+viewCustomPage : Shared.Model -> Route () -> View Never
+viewCustomPage shared route =
     View.fromString "Loading..."

src/elm/Auth/Action.elm

@@ -5,15 +5,15 @@ SPDX-License-Identifier: Apache-2.0
 
 module Auth.Action exposing
     ( Action(..)
-    , loadPageWithUser, showLoadingPage
+    , loadPageWithUser, loadCustomPage
     , replaceRoute, pushRoute, loadExternalUrl
     , view, subscriptions, command
     )
 
 {-|
 
 @docs Action
-@docs loadPageWithUser, showLoadingPage
+@docs loadPageWithUser, loadCustomPage
 @docs replaceRoute, pushRoute, loadExternalUrl
 
 @docs view, subscriptions, command
@@ -25,9 +25,12 @@ import Route.Path
 import View exposing (View)
 
 
+{-| Describes the action to take for authenticated pages, based
+on the current `Route` and `Shared.Model`
+-}
 type Action user
     = LoadPageWithUser user
-    | ShowLoadingPage (View Never)
+    | LoadCustomPage
     | ReplaceRoute
         { path : Route.Path.Path
         , query : Dict String String
@@ -41,16 +44,27 @@ type Action user
     | LoadExternalUrl String
 
 
+{-| Successfully pass the user along to the authenticated page.
+-}
 loadPageWithUser : user -> Action user
 loadPageWithUser =
     LoadPageWithUser
 
 
-showLoadingPage : View Never -> Action user
-showLoadingPage =
-    ShowLoadingPage
+{-| Rather than navigating to a different route, keep the URL, but render
+what was defined in `Auth.loadCustomPage`.
+
+**Note:** `Auth.loadCustomPage` has access to the `Shared.Model`, so you
+can render different pages in different authentication scenarios.
+
+-}
+loadCustomPage : Action user
+loadCustomPage =
+    LoadCustomPage
 
 
+{-| Replace the URL with the provided route.
+-}
 replaceRoute :
     { path : Route.Path.Path
     , query : Dict String String
@@ -61,6 +75,8 @@ replaceRoute =
     ReplaceRoute
 
 
+{-| Push a new URL with the provided route.
+-}
 pushRoute :
     { path : Route.Path.Path
     , query : Dict String String
@@ -71,6 +87,8 @@ pushRoute =
     PushRoute
 
 
+{-| Navigate to a URL for an external website.
+-}
 loadExternalUrl : String -> Action user
 loadExternalUrl =
     LoadExternalUrl
@@ -80,14 +98,14 @@ loadExternalUrl =
 -- USED INTERNALLY BY ELM LAND
 
 
-view : (user -> View msg) -> Action user -> View msg
-view toView authAction =
+view : View msg -> (user -> View msg) -> Action user -> View msg
+view viewCustomPage viewPageWithUser authAction =
     case authAction of
         LoadPageWithUser user ->
-            toView user
+            viewPageWithUser user
 
-        ShowLoadingPage loadingView ->
-            View.map never loadingView
+        LoadCustomPage ->
+            viewCustomPage
 
         ReplaceRoute _ ->
             View.none
@@ -105,7 +123,7 @@ subscriptions toSub authAction =
         LoadPageWithUser user ->
             toSub user
 
-        ShowLoadingPage _ ->
+        LoadCustomPage ->
             Sub.none
 
         ReplaceRoute _ ->
@@ -124,7 +142,7 @@ command toCmd authAction =
         LoadPageWithUser user ->
             toCmd user
 
-        ShowLoadingPage _ ->
+        LoadCustomPage ->
             Cmd.none
 
         ReplaceRoute _ ->