elm-pages 3.0.0-beta.40 → 3.0.0-beta.41

package/src/Pages/Form.elm

@@ -1,11 +1,47 @@
 module Pages.Form exposing
-    ( Strategy(..), renderHtml, renderStyledHtml
+    ( renderHtml, renderStyledHtml
+    , Options
+    , withConcurrent
     , FormWithServerValidations, Handler
     )
 
-{-|
+{-| `elm-pages` has a built-in integration with [`dillonkearns/elm-form`](https://package.elm-lang.org/packages/dillonkearns/elm-form/latest/). See the `dillonkearns/elm-form`
+docs and examples for more information on how to define your [`Form`](https://package.elm-lang.org/packages/dillonkearns/elm-form/latest/Form). This module is the interface for rendering your `Form` in your `elm-pages` app.
 
-@docs Strategy, renderHtml, renderStyledHtml
+By rendering your `Form` with this module,
+you get all of the boilerplate managed for you automatically by the `elm-pages` framework. That means you do not need to use `Form.init`, `Form.update`, `Form.Model` since these are all
+abstracted away. In addition to that, in-flight form state is automatically managed for you and exposed through the `app` argument in your Route modules.
+
+This means that you can declaratively derive Pending UI or Optimistic UI state from `app.navigation` or `app.concurrentSubmissions` in your Route modules, and even build a
+rich dynamic page that shows pending submissions in the UI without using your Route module's `Model`! This is the power of this abstraction - it's less error-prone to
+declaratively derive state rather than imperatively managing your `Model`.
+
+
+## Rendering Forms
+
+@docs renderHtml, renderStyledHtml
+
+@docs Options
+
+
+## Form Submission Strategies
+
+When you render with [`Pages.Form.renderHtml`](#renderHtml) or [`Pages.Form.renderStyledHtml`](#renderStyledHtml),
+`elm-pages` progressively enhances form submissions to manage the requests through Elm (instead of as a vanilla HTML form submission, which performs a full page reload).
+
+By default, `elm-pages` Forms will use the same mental model as the browser's default form submission behavior. That is, the form submission state will be tied to the page's navigation state.
+If you click a link while a form is submitting, the form submission will be cancelled and the page will navigate to the new page. Conceptually, you can think of this as being tied to the navigation state.
+A form submission is part of the page's navigation state, and so is a page navigation. So if you have a page with an edit form, a delete form (no inputs but only a delete button), and a link to a new page,
+you can interact with any of these and it will cancel the previous interactions.
+
+You can access this state through `app.navigation` in your `Route` module, which is a value of type [`Pages.Navigation`](Pages-Navigation).
+
+This default form submission strategy is a good fit for more linear actions. This is more traditional server submission behavior that you might be familiar with from Rails or other server frameworks without JavaScript enhancement.
+
+@docs withConcurrent
+
+
+## Server-Side Validation
 
 @docs FormWithServerValidations, Handler
 
@@ -19,8 +55,9 @@ import Form.Handler
 import Form.Validation exposing (Validation)
 import Html
 import Html.Styled
+import Pages.ConcurrentSubmission
 import Pages.Internal.Msg
-import Pages.Transition
+import Pages.Navigation
 import PagesMsg exposing (PagesMsg)
 
 
@@ -45,56 +82,122 @@ type alias Handler error combined =
     Form.Handler.Handler error (BackendTask FatalError (Validation error combined Never Never))
 
 
-{-| -}
-type Strategy
-    = Parallel
-    | Serial
+{-| A replacement for [`Form.Options`](https://package.elm-lang.org/packages/dillonkearns/elm-form/latest/Form#Options)
+with some extra configuration for the `elm-pages` integration. You can use this type to annotate your form's options.
+-}
+type alias Options error parsed input msg =
+    Form.Options error parsed input msg { concurrent : Bool }
 
 
-{-| -}
+{-| Instead of using the default submission strategy (tied to the page's navigation state), you can use `withConcurrent`.
+`withConcurrent` allows multiple form submissions to be in flight at the same time. It is useful for more dynamic applications. A good rule of thumb
+is if you could have multiple pending spinners on the page at the same time, you should use `withConcurrent`. For example, if you have a page with a list of items,
+say a Twitter clone. If you click the like button on a Tweet, it won't result in a page navigation. You can click the like button on multiple Tweets at the same time
+and they will all submit independently.
+
+In the case of Twitter, there isn't an indication of a loading spinner on the like button because it is expected that it will succeed. This is an example of a User Experience (UX) pattern
+called Optimistic UI. Since it is very likely that liking a Tweet will be successful, the UI will update the UI as if it has immediately succeeded even though the request is still in flight.
+If the request fails, the UI will be updated to reflect the failure with an animation to show that something went wrong.
+
+The `withConcurrent` is a good fit for either of these UX patterns (Optimistic UI or Pending UI, i.e. showing a loading spinner). You can derive either of these
+visual states from the `app.concurrentSubmissions` field in your `Route` module.
+
+You can call `withConcurrent` on your `Form.Options`. Note that while `withConcurrent` will allow multiple form submissions to be in flight at the same time independently,
+the ID of the Form will still have a unique submission. For example, if you click submit on a form with the ID `"edit-123"` and then submit it again before the first submission has completed,
+the second submission will cancel the first submission. So it is important to use unique IDs for forms that represent unique operations.
+
+    import Form
+    import Pages.Form
+
+    todoItemView app todo =
+        deleteItemForm
+            |> Pages.Form.renderHtml []
+                (Form.options ("delete-" ++ todo.id)
+                    |> Form.withInput todo
+                    |> Pages.Form.withConcurrent
+                )
+                app
+
+-}
+withConcurrent : Options error parsed input msg -> Options error parsed input msg
+withConcurrent options_ =
+    { options_ | extras = Just { concurrent = True } }
+
+
+
+--init :
+--    (parsed -> combined)
+--    -> FormWithServerValidations error parsed input view
+--    -> Handler error combined
+--init mapFn form =
+--    Form.Handler.init
+--        (\something ->
+--            let
+--                foo : parsed
+--                foo =
+--                    something
+--
+--                goal : BackendTask FatalError (Validation error combined Never Never)
+--                goal =
+--                    Debug.todo ""
+--            in
+--            --Form.Validation.map (BackendTask.map (mapFn something))
+--            --Debug.todo ""
+--            goal
+--        )
+--        form
+
+
+{-| A replacement for `Form.renderHtml` from `dillonkearns/elm-form` that integrates with `elm-pages`. Use this to render your [`Form`](https://package.elm-lang.org/packages/dillonkearns/elm-form/latest/Form)
+as `elm/html` `Html`.
+-}
 renderHtml :
     List (Html.Attribute (PagesMsg userMsg))
-    -> Strategy
-    -> Form.Options error parsed input userMsg
+    -> Options error parsed input userMsg
     ->
         { --path : Path
           --, url : Maybe PageUrl
           --, action : Maybe action
           app
             | pageFormState : Form.Model
-            , transition : Maybe Pages.Transition.Transition
-            , fetchers : Dict String (Pages.Transition.FetcherState (Maybe action))
+            , navigation : Maybe Pages.Navigation.Navigation
+            , concurrentSubmissions : Dict String (Pages.ConcurrentSubmission.ConcurrentSubmission (Maybe action))
         }
     -> Form.Form error { combine : Validation error parsed named constraints, view : Form.Context error input -> List (Html.Html (PagesMsg userMsg)) } parsed input
     -> Html.Html (PagesMsg userMsg)
-renderHtml attrs strategy options_ app form_ =
+renderHtml attrs options_ app form_ =
+    let
+        concurrent : Bool
+        concurrent =
+            options_.extras |> Maybe.map .concurrent |> Maybe.withDefault False
+    in
     form_
         |> Form.renderHtml
             { state = app.pageFormState
             , submitting =
-                (case app.fetchers |> Dict.get options_.id of
+                (case app.concurrentSubmissions |> Dict.get options_.id of
                     Just { status } ->
                         case status of
-                            Pages.Transition.FetcherComplete _ ->
+                            Pages.ConcurrentSubmission.Complete _ ->
                                 False
 
-                            Pages.Transition.FetcherSubmitting ->
+                            Pages.ConcurrentSubmission.Submitting ->
                                 True
 
-                            Pages.Transition.FetcherReloading _ ->
+                            Pages.ConcurrentSubmission.Reloading _ ->
                                 True
 
                     Nothing ->
                         False
                 )
-                    || (case app.transition of
-                            Just (Pages.Transition.Submitting formData) ->
+                    || (case app.navigation of
+                            Just (Pages.Navigation.Submitting formData) ->
                                 formData.id == Just options_.id
 
-                            Just (Pages.Transition.LoadAfterSubmit submitData _ _) ->
+                            Just (Pages.Navigation.LoadAfterSubmit submitData _ _) ->
                                 submitData.id == Just options_.id
 
-                            Just (Pages.Transition.Loading _ _) ->
+                            Just (Pages.Navigation.Loading _ _) ->
                                 False
 
                             Nothing ->
@@ -113,7 +216,7 @@ renderHtml attrs strategy options_ app form_ =
                         case submission.parsed of
                             Form.Valid _ ->
                                 Pages.Internal.Msg.Submit
-                                    { useFetcher = strategy == Parallel
+                                    { useFetcher = concurrent
                                     , action = submission.action
                                     , fields = submission.fields
                                     , method = submission.method
@@ -127,7 +230,7 @@ renderHtml attrs strategy options_ app form_ =
 
                             Form.Invalid _ _ ->
                                 Pages.Internal.Msg.Submit
-                                    { useFetcher = strategy == Parallel
+                                    { useFetcher = concurrent
                                     , action = submission.action
                                     , method = submission.method
                                     , fields = submission.fields
@@ -136,55 +239,62 @@ renderHtml attrs strategy options_ app form_ =
                                     , valid = False
                                     }
                     )
+            , extras = Nothing
             }
             attrs
 
 
-{-| -}
+{-| A replacement for `Form.renderStyledHtml` from `dillonkearns/elm-form` that integrates with `elm-pages`. Use this to render your [`Form`](https://package.elm-lang.org/packages/dillonkearns/elm-form/latest/Form)
+as `rtfeldman/elm-css` `Html.Styled.Html`.
+-}
 renderStyledHtml :
     List (Html.Styled.Attribute (PagesMsg userMsg))
-    -> Strategy
-    -> Form.Options error parsed input userMsg
+    -> Options error parsed input userMsg
     ->
         { --path : Path
           --, url : Maybe PageUrl
           --, action : Maybe action
           app
             | pageFormState : Form.Model
-            , transition : Maybe Pages.Transition.Transition
-            , fetchers : Dict String (Pages.Transition.FetcherState (Maybe action))
+            , navigation : Maybe Pages.Navigation.Navigation
+            , concurrentSubmissions : Dict String (Pages.ConcurrentSubmission.ConcurrentSubmission (Maybe action))
         }
     -> Form.Form error { combine : Validation error parsed named constraints, view : Form.Context error input -> List (Html.Styled.Html (PagesMsg userMsg)) } parsed input
     -> Html.Styled.Html (PagesMsg userMsg)
-renderStyledHtml attrs strategy options_ app form_ =
+renderStyledHtml attrs options_ app form_ =
+    let
+        concurrent : Bool
+        concurrent =
+            options_.extras |> Maybe.map .concurrent |> Maybe.withDefault False
+    in
     form_
         |> Form.renderStyledHtml
             { state = app.pageFormState
             , toMsg = Pages.Internal.Msg.FormMsg
             , submitting =
-                (case app.fetchers |> Dict.get options_.id of
+                (case app.concurrentSubmissions |> Dict.get options_.id of
                     Just { status } ->
                         case status of
-                            Pages.Transition.FetcherComplete _ ->
+                            Pages.ConcurrentSubmission.Complete _ ->
                                 False
 
-                            Pages.Transition.FetcherSubmitting ->
+                            Pages.ConcurrentSubmission.Submitting ->
                                 True
 
-                            Pages.Transition.FetcherReloading _ ->
+                            Pages.ConcurrentSubmission.Reloading _ ->
                                 True
 
                     Nothing ->
                         False
                 )
-                    || (case app.transition of
-                            Just (Pages.Transition.Submitting formData) ->
+                    || (case app.navigation of
+                            Just (Pages.Navigation.Submitting formData) ->
                                 formData.id == Just options_.id
 
-                            Just (Pages.Transition.LoadAfterSubmit submitData _ _) ->
+                            Just (Pages.Navigation.LoadAfterSubmit submitData _ _) ->
                                 submitData.id == Just options_.id
 
-                            Just (Pages.Transition.Loading _ _) ->
+                            Just (Pages.Navigation.Loading _ _) ->
                                 False
 
                             Nothing ->
@@ -202,7 +312,7 @@ renderStyledHtml attrs strategy options_ app form_ =
                         case submission.parsed of
                             Form.Valid _ ->
                                 Pages.Internal.Msg.Submit
-                                    { useFetcher = strategy == Parallel
+                                    { useFetcher = concurrent
                                     , action = submission.action
                                     , fields = submission.fields
                                     , method = submission.method
@@ -216,7 +326,7 @@ renderStyledHtml attrs strategy options_ app form_ =
 
                             Form.Invalid _ _ ->
                                 Pages.Internal.Msg.Submit
-                                    { useFetcher = strategy == Parallel
+                                    { useFetcher = concurrent
                                     , action = submission.action
                                     , fields = submission.fields
                                     , method = submission.method
@@ -225,5 +335,6 @@ renderStyledHtml attrs strategy options_ app form_ =
                                     , valid = False
                                     }
                     )
+            , extras = Nothing
             }
             attrs

package/src/Pages/FormData.elm

@@ -0,0 +1,18 @@
+module Pages.FormData exposing (FormData)
+
+{-|
+
+@docs FormData
+
+-}
+
+import Form
+
+
+{-| -}
+type alias FormData =
+    { fields : List ( String, String )
+    , method : Form.Method
+    , action : String
+    , id : Maybe String
+    }

package/src/Pages/Internal/NotFoundReason.elm

@@ -9,7 +9,7 @@ module Pages.Internal.NotFoundReason exposing (ModuleContext, NotFoundReason(..)
 import Html exposing (Html)
 import Html.Attributes as Attr
 import Pages.Internal.RoutePattern exposing (RoutePattern)
-import Path exposing (Path)
+import UrlPath exposing (UrlPath)
 
 
 {-| -}
@@ -22,7 +22,7 @@ type alias ModuleContext =
 
 {-| -}
 type alias Payload =
-    { path : Path
+    { path : UrlPath
     , reason : NotFoundReason
     }
 
@@ -58,7 +58,7 @@ document pathPatterns payload =
                     , Html.code []
                         [ Html.text
                             (payload.path
-                                |> Path.toAbsolute
+                                |> UrlPath.toAbsolute
                             )
                         ]
                     , Html.text " Did you mean to go to one of these routes:"
@@ -85,7 +85,7 @@ document pathPatterns payload =
                     , Html.code []
                         [ Html.text
                             (payload.path
-                                |> Path.toAbsolute
+                                |> UrlPath.toAbsolute
                             )
                         ]
                     , Html.text " successfully matched the route "

package/src/Pages/Internal/Platform/Cli.elm

@@ -32,11 +32,11 @@ import Pages.ProgramConfig exposing (ProgramConfig)
 import Pages.SiteConfig exposing (SiteConfig)
 import Pages.StaticHttp.Request
 import PagesMsg exposing (PagesMsg)
-import Path exposing (Path)
 import RenderRequest exposing (RenderRequest)
 import RequestsAndPending exposing (RequestsAndPending)
 import TerminalText as Terminal
 import Url exposing (Url)
+import UrlPath exposing (UrlPath)
 
 
 {-| -}
@@ -402,7 +402,7 @@ initLegacy site ((RenderRequest.SinglePage includeHtml singleRequest _) as rende
                             { protocol = Url.Https
                             , host = site.canonicalUrl
                             , port_ = Nothing
-                            , path = serverRequestPayload.path |> Path.toRelative
+                            , path = serverRequestPayload.path |> UrlPath.toRelative
                             , query = Nothing
                             , fragment = Nothing
                             }
@@ -471,7 +471,7 @@ initLegacy site ((RenderRequest.SinglePage includeHtml singleRequest _) as rende
                                                                             case pageData of
                                                                                 PageServerResponse.RenderPage responseInfo pageData_ ->
                                                                                     let
-                                                                                        currentPage : { path : Path, route : route }
+                                                                                        currentPage : { path : UrlPath, route : route }
                                                                                         currentPage =
                                                                                             { path = serverRequestPayload.path, route = urlToRoute config currentUrl }
 
@@ -565,7 +565,7 @@ initLegacy site ((RenderRequest.SinglePage includeHtml singleRequest _) as rende
                                                                                                     -- TODO handle other cases besides redirects?
                                                                                                     |> Maybe.withDefault byteEncodedPageData
                                                                                                     |> (\encodedData ->
-                                                                                                            { route = currentPage.path |> Path.toRelative
+                                                                                                            { route = currentPage.path |> UrlPath.toRelative
                                                                                                             , contentJson = Dict.empty
                                                                                                             , html = viewValue.body |> bodyToString
                                                                                                             , errors = []
@@ -615,7 +615,7 @@ initLegacy site ((RenderRequest.SinglePage includeHtml singleRequest _) as rende
 
                                                                                 PageServerResponse.ErrorPage error record ->
                                                                                     let
-                                                                                        currentPage : { path : Path, route : route }
+                                                                                        currentPage : { path : UrlPath, route : route }
                                                                                         currentPage =
                                                                                             { path = serverRequestPayload.path, route = urlToRoute config currentUrl }
 
@@ -651,7 +651,7 @@ initLegacy site ((RenderRequest.SinglePage includeHtml singleRequest _) as rende
                                                                                         |> Bytes.Encode.encode
                                                                                     )
                                                                                         |> (\encodedData ->
-                                                                                                { route = currentPage.path |> Path.toRelative
+                                                                                                { route = currentPage.path |> UrlPath.toRelative
                                                                                                 , contentJson = Dict.empty
                                                                                                 , html = viewValue.body |> bodyToString
                                                                                                 , errors = []
@@ -743,7 +743,7 @@ initLegacy site ((RenderRequest.SinglePage includeHtml singleRequest _) as rende
                                                                                 )
                                                                                 |> Tuple.first
 
-                                                                        currentPage : { path : Path, route : route }
+                                                                        currentPage : { path : UrlPath, route : route }
                                                                         currentPage =
                                                                             { path = serverRequestPayload.path, route = urlToRoute config currentUrl }
 
@@ -752,7 +752,7 @@ initLegacy site ((RenderRequest.SinglePage includeHtml singleRequest _) as rende
                                                                             (config.view Dict.empty Dict.empty Nothing currentPage Nothing justSharedData dataThing Nothing |> .view)
                                                                                 pageModel
                                                                     in
-                                                                    { route = Path.toAbsolute currentPage.path
+                                                                    { route = UrlPath.toAbsolute currentPage.path
                                                                     , contentJson = Dict.empty
                                                                     , html = viewValue.body |> bodyToString
                                                                     , errors = []
@@ -797,7 +797,7 @@ initLegacy site ((RenderRequest.SinglePage includeHtml singleRequest _) as rende
                                         -- TODO do I need sharedDataResult here?
                                         Nothing
                                         isDevServer
-                                        (Path.fromString path)
+                                        (UrlPath.fromString path)
                                         NotFoundReason.NoMatchingRoute
                          --Err error ->
                          --    [ error ]
@@ -909,7 +909,7 @@ render404Page :
     ProgramConfig userMsg userModel route pageData actionData sharedData effect mappedMsg errorPage
     -> Maybe sharedData
     -> Bool
-    -> Path
+    -> UrlPath
     -> NotFoundReason
     -> Effect
 render404Page config sharedData isDevServer path notFoundReason =
@@ -940,7 +940,7 @@ render404Page config sharedData isDevServer path notFoundReason =
                 pageData =
                     config.errorPageToData config.notFoundPage
 
-                pathAndRoute : { path : Path, route : route }
+                pathAndRoute : { path : UrlPath, route : route }
                 pathAndRoute =
                     { path = path, route = config.notFoundRoute }
 
@@ -958,7 +958,7 @@ render404Page config sharedData isDevServer path notFoundReason =
                     )
                         pageModel
             in
-            { route = Path.toAbsolute path
+            { route = UrlPath.toAbsolute path
             , contentJson = Dict.empty
             , html = viewValue.body |> bodyToString
             , errors = []
@@ -987,7 +987,7 @@ render404Page config sharedData isDevServer path notFoundReason =
                     }
                         |> NotFoundReason.document config.pathPatterns
             in
-            { route = Path.toAbsolute path
+            { route = UrlPath.toAbsolute path
             , contentJson = Dict.empty
             , html = bodyToString notFoundDocument.body
             , errors = []
@@ -1021,7 +1021,7 @@ urlToRoute config url =
 
 toRedirectResponse :
     ProgramConfig userMsg userModel route pageData actionData sharedData effect mappedMsg errorPage
-    -> { b | path : Path }
+    -> { b | path : UrlPath }
     -> RenderRequest.IncludeHtml
     -> { c | headers : List ( String, String ), statusCode : Int }
     -> { response | statusCode : Int, headers : List ( String, String ) }
@@ -1044,7 +1044,7 @@ toRedirectResponse config serverRequestPayload includeHtml serverResponse respon
                             |> Bytes.Encode.encode
                         )
                 in
-                { route = serverRequestPayload.path |> Path.toRelative
+                { route = serverRequestPayload.path |> UrlPath.toRelative
                 , contentJson = Dict.empty
                 , html = "This is intentionally blank HTML"
                 , errors = []

package/src/Pages/Internal/Platform/CompatibilityKey.elm

@@ -3,4 +3,4 @@ module Pages.Internal.Platform.CompatibilityKey exposing (currentCompatibilityKe
 
 currentCompatibilityKey : Int
 currentCompatibilityKey =
-    17
+    18