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

package/src/Pages/ProgramConfig.elm

@@ -15,18 +15,20 @@ import Http
 import Json.Decode as Decode
 import Json.Encode
 import PageServerResponse exposing (PageServerResponse)
+import Pages.ConcurrentSubmission
 import Pages.Fetcher
 import Pages.Flags
 import Pages.Internal.NotFoundReason exposing (NotFoundReason)
 import Pages.Internal.Platform.ToJsPayload
 import Pages.Internal.ResponseSketch exposing (ResponseSketch)
 import Pages.Internal.RoutePattern exposing (RoutePattern)
+import Pages.Navigation
 import Pages.PageUrl exposing (PageUrl)
 import Pages.SiteConfig exposing (SiteConfig)
-import Pages.Transition
 import PagesMsg exposing (PagesMsg)
-import Path exposing (Path)
+import Server.Request
 import Url exposing (Url)
+import UrlPath exposing (UrlPath)
 
 
 type alias ProgramConfig userMsg userModel route pageData actionData sharedData effect mappedMsg errorPage =
@@ -38,7 +40,7 @@ type alias ProgramConfig userMsg userModel route pageData actionData sharedData
         ->
             Maybe
                 { path :
-                    { path : Path
+                    { path : UrlPath
                     , query : Maybe String
                     , fragment : Maybe String
                     }
@@ -46,18 +48,18 @@ type alias ProgramConfig userMsg userModel route pageData actionData sharedData
                 , pageUrl : Maybe PageUrl
                 }
         -> ( userModel, effect )
-    , update : Form.Model -> Dict String (Pages.Transition.FetcherState actionData) -> Maybe Pages.Transition.Transition -> sharedData -> pageData -> Maybe Browser.Navigation.Key -> userMsg -> userModel -> ( userModel, effect )
-    , subscriptions : route -> Path -> userModel -> Sub userMsg
+    , update : Form.Model -> Dict String (Pages.ConcurrentSubmission.ConcurrentSubmission actionData) -> Maybe Pages.Navigation.Navigation -> sharedData -> pageData -> Maybe Browser.Navigation.Key -> userMsg -> userModel -> ( userModel, effect )
+    , subscriptions : route -> UrlPath -> userModel -> Sub userMsg
     , sharedData : BackendTask FatalError sharedData
-    , data : Decode.Value -> route -> BackendTask FatalError (PageServerResponse pageData errorPage)
-    , action : Decode.Value -> route -> BackendTask FatalError (PageServerResponse actionData errorPage)
+    , data : Server.Request.Request -> route -> BackendTask FatalError (PageServerResponse pageData errorPage)
+    , action : Server.Request.Request -> route -> BackendTask FatalError (PageServerResponse actionData errorPage)
     , onActionData : actionData -> Maybe userMsg
     , view :
         Form.Model
-        -> Dict String (Pages.Transition.FetcherState actionData)
-        -> Maybe Pages.Transition.Transition
+        -> Dict String (Pages.ConcurrentSubmission.ConcurrentSubmission actionData)
+        -> Maybe Pages.Navigation.Navigation
         ->
-            { path : Path
+            { path : UrlPath
             , route : route
             }
         -> Maybe PageUrl
@@ -81,7 +83,7 @@ type alias ProgramConfig userMsg userModel route pageData actionData sharedData
         { protocol : Url.Protocol
         , host : String
         , port_ : Maybe Int
-        , path : Path
+        , path : UrlPath
         , query : Maybe String
         , fragment : Maybe String
         , metadata : route

package/src/Pages/Script.elm

@@ -6,10 +6,15 @@ module Pages.Script exposing
     , Error(..)
     )
 
-{-|
+{-| An elm-pages Script is a way to execute an `elm-pages` `BackendTask`.
+
+Read more about using the `elm-pages` CLI to run (or bundle) scripts, plus a brief tutorial, at <https://elm-pages-v3.netlify.app/docs/elm-pages-scripts>.
 
 @docs Script
 
+
+## Defining Scripts
+
 @docs withCliOptions, withoutCliOptions
 
 
@@ -40,18 +45,37 @@ import Json.Encode as Encode
 import Pages.Internal.Script
 
 
-{-| -}
+{-| The type for your `run` function that can be executed by `elm-pages run`.
+-}
 type alias Script =
     Pages.Internal.Script.Script
 
 
-{-| -}
+{-| The recoverable error type for file writes. You can use `BackendTask.allowFatal` if you want to allow the program to crash
+with an error message if a file write is unsuccessful.
+-}
 type Error
     = --TODO make more descriptive
       FileWriteError
 
 
-{-| -}
+{-| Write a file to the file system.
+
+    module MyScript exposing (run)
+
+    import BackendTask
+    import Pages.Script as Script
+
+    run =
+        Script.withoutCliOptions
+            (Script.writeFile
+                { path = "hello.json"
+                , body = """{ "message": "Hello, World!" }"""
+                }
+                |> BackendTask.allowFatal
+            )
+
+-}
 writeFile : { path : String, body : String } -> BackendTask { fatal : FatalError, recoverable : Error } ()
 writeFile { path, body } =
     BackendTask.Internal.Request.request
@@ -69,7 +93,20 @@ writeFile { path, body } =
         }
 
 
-{-| -}
+{-| Log to stdout.
+
+    module MyScript exposing (run)
+
+    import BackendTask
+    import Pages.Script as Script
+
+    run =
+        Script.withoutCliOptions
+            (Script.log "Hello!"
+                |> BackendTask.allowFatal
+            )
+
+-}
 log : String -> BackendTask error ()
 log message =
     BackendTask.Internal.Request.request
@@ -84,7 +121,20 @@ log message =
         }
 
 
-{-| -}
+{-| Define a simple Script (no CLI Options).
+
+    module MyScript exposing (run)
+
+    import BackendTask
+    import Pages.Script as Script
+
+    run =
+        Script.withoutCliOptions
+            (Script.log "Hello!"
+                |> BackendTask.allowFatal
+            )
+
+-}
 withoutCliOptions : BackendTask FatalError () -> Script
 withoutCliOptions execute =
     Pages.Internal.Script.Script
@@ -99,7 +149,14 @@ withoutCliOptions execute =
         )
 
 
-{-| -}
+{-| Same as [`withoutCliOptions`](#withoutCliOptions), but allows you to define a CLI Options Parser so the user can
+pass in additional options for the script.
+
+Uses <https://package.elm-lang.org/packages/dillonkearns/elm-cli-options-parser/latest/>.
+
+Read more at <https://elm-pages-v3.netlify.app/docs/elm-pages-scripts/#adding-command-line-options>.
+
+-}
 withCliOptions : Program.Config cliOptions -> (cliOptions -> BackendTask FatalError ()) -> Script
 withCliOptions config execute =
     Pages.Internal.Script.Script

package/src/Pages/Url.elm

@@ -12,7 +12,7 @@ If you refer to a local page, like `Route.Index |> Route.toPath |> Pages.Url.fro
 -}
 
 import Pages.Internal.String as String
-import Path exposing (Path)
+import UrlPath exposing (UrlPath)
 
 
 {-| -}
@@ -22,9 +22,9 @@ type Url
 
 
 {-| -}
-fromPath : Path -> Url
+fromPath : UrlPath -> Url
 fromPath path =
-    path |> Path.toAbsolute |> Internal
+    path |> UrlPath.toAbsolute |> Internal
 
 
 {-| -}

package/src/PagesMsg.elm

@@ -27,6 +27,8 @@ type alias PagesMsg userMsg =
 
 {-|
 
+    import Form
+    import Pages.Form
     import PagesMsg exposing (PagesMsg)
 
     type Msg
@@ -46,10 +48,14 @@ type alias PagesMsg userMsg =
                 [ onClick (PagesMsg.fromMsg ToggleMenu) ]
                 []
 
-            -- `Form.renderHtml` gives us `Html (PagesMsg msg)`, so we don't need to wrap its Msg type
+            -- `Pages.Form.renderHtml` gives us `Html (PagesMsg msg)`, so we don't need to wrap its Msg type
             , logoutForm
-                |> Form.withOnSubmit (\_ -> NewItemSubmitted)
-                |> Form.renderHtml "logout" [] (\_ -> Nothing) app Nothing
+                |> Pages.Form.renderHtml []
+                    Pages.Form.Serial
+                    (Form.options "logout"
+                        |> Form.withOnSubmit (\_ -> NewItemSubmitted)
+                    )
+                    app
             ]
         }
 

package/src/RenderRequest.elm

@@ -13,15 +13,15 @@ import Internal.ApiRoute
 import Json.Decode as Decode
 import Json.Encode as Encode
 import Pages.ProgramConfig exposing (ProgramConfig)
-import Path exposing (Path)
 import Regex
 import Url exposing (Url)
+import UrlPath exposing (UrlPath)
 
 
 type RequestPayload route
-    = Page { path : Path, frontmatter : route }
+    = Page { path : UrlPath, frontmatter : route }
     | Api ( String, ApiRoute.ApiRoute ApiRoute.Response )
-    | NotFound Path
+    | NotFound UrlPath
 
 
 type RenderRequest route
@@ -32,7 +32,7 @@ default : RenderRequest route
 default =
     SinglePage
         HtmlAndJson
-        (NotFound (Path.fromString "/error"))
+        (NotFound (UrlPath.fromString "/error"))
         Encode.null
 
 
@@ -119,12 +119,12 @@ requestPayloadDecoder config =
                                     ( path, justApi ) |> Api
 
                                 Nothing ->
-                                    NotFound (Path.fromString path)
+                                    NotFound (UrlPath.fromString path)
 
                         else
                             Page
                                 { frontmatter = route
-                                , path = config.routeToPath route |> Path.join
+                                , path = config.routeToPath route |> UrlPath.join
                                 }
 
                     Nothing ->
@@ -133,7 +133,7 @@ requestPayloadDecoder config =
                                 ( path, justApi ) |> Api
 
                             Nothing ->
-                                NotFound (Path.fromString path)
+                                NotFound (UrlPath.fromString path)
             )
     )
         |> Decode.field "path"

package/src/Scaffold/Form.elm

@@ -1,16 +1,27 @@
 module Scaffold.Form exposing
     ( Kind(..), provide, restArgsParser
     , Context
-    , fieldEncoder, recordEncoder
+    , recordEncoder, fieldEncoder
     )
 
-{-|
+{-| This module helps you with scaffolding a form in `elm-pages`, similar to how rails generators are used to scaffold out forms to
+get up and running quickly with the starting point for a form with different field types. See also [`Scaffold.Route`](Scaffold-Route).
+
+See the `AddRoute` script in the starter template for an example. It's usually easiest to modify that script as a starting
+point rather than using this API from scratch.
+
+Using the `AddRoute` script from the default starter template, you can run a command like this:
+
+`npx elm-pages run AddRoute Profile.Username_.Edit first last bio:textarea dob:date` to generate a Route module `app/Route/Profile/Username_/Edit.elm`
+with the wiring form a `Form`.
+
+[Learn more about writing and running elm-pages Scripts for scaffolding](https://elm-pages-v3.netlify.app/docs/elm-pages-scripts#scaffolding-a-route-module).
 
 @docs Kind, provide, restArgsParser
 
 @docs Context
 
-@docs fieldEncoder, recordEncoder
+@docs recordEncoder, fieldEncoder
 
 -}
 
@@ -159,7 +170,18 @@ fieldToParam ( name, _ ) =
     ( name, Nothing )
 
 
-{-| -}
+{-| This parser handles the following field types (or `text` if none is provided):
+
+  - `text`
+  - `textarea`
+  - `checkbox`
+  - `time`
+  - `date`
+
+The naming convention follows the same naming as the HTML form field elements or attributes that are used to represent them.
+In addition to using the appropriate field type, this will also give you an Elm type with the corresponding base type (like `Date` for `date` or `Bool` for `checkbox`).
+
+-}
 restArgsParser : Cli.Option.Option (List String) (List ( String, Kind )) Cli.Option.RestArgsOption
 restArgsParser =
     Cli.Option.restArgs "formFields"
@@ -506,7 +528,8 @@ recordEncoder record fields =
             )
 
 
-{-| -}
+{-| A lower-level, more granular version of `recordEncoder` - lets you generate a JSON Encoder `Expression` for an individual Field rather than a group of Fields.
+-}
 fieldEncoder : Elm.Expression -> String -> Kind -> Elm.Expression
 fieldEncoder record name kind =
     Elm.apply

package/src/Scaffold/Route.elm

@@ -9,12 +9,17 @@ module Scaffold.Route exposing
 
 {-| This module provides some functions for scaffolding code for a new Route Module. It uses [`elm-codegen`'s API](https://package.elm-lang.org/packages/mdgriffith/elm-codegen/latest/) for generating code.
 
-Typically you'll want to use this via the `elm-pages codegen` CLI command. The default starter template includes a file that uses these functions, which you can tweak to customize your scaffolding commands.
-Learn more about [the `elm-pages run` CLI command in its docs page](https://elm-pages.com/docs/run-command).
+Typically you'll want to use this via the `elm-pages run` CLI command. The default starter template includes a Script that uses these functions, which you can tweak to customize your scaffolding commands.
+[Learn more about writing and running elm-pages Scripts for scaffolding](https://elm-pages-v3.netlify.app/docs/elm-pages-scripts#scaffolding-a-route-module).
+
+It's typically easiest to modify the `AddRoute` script from the starter template and adjust it to your needs rather than writing one from scratch.
 
 
 ## Initializing the Generator Builder
 
+These functions mirror the `RouteBuilder` API that you use in your Route modules to define your route. The difference is that
+instead of defining a route, this is defining a code generator for a Route module.
+
 @docs buildWithLocalState, buildWithSharedState, buildNoState, Builder
 
 @docs Type
@@ -87,8 +92,8 @@ typeToDeclaration name type_ =
 type Builder
     = ServerRender
         (List Elm.Declaration)
-        { data : ( Type, Elm.Expression -> Elm.Expression )
-        , action : ( Type, Elm.Expression -> Elm.Expression )
+        { data : ( Type, Elm.Expression -> Elm.Expression -> Elm.Expression )
+        , action : ( Type, Elm.Expression -> Elm.Expression -> Elm.Expression )
         , head : Elm.Expression -> Elm.Expression
         , moduleName : List String
         }
@@ -103,8 +108,8 @@ type Builder
 
 {-| -}
 serverRender :
-    { data : ( Type, Elm.Expression -> Elm.Expression )
-    , action : ( Type, Elm.Expression -> Elm.Expression )
+    { data : ( Type, Elm.Expression -> Elm.Expression -> Elm.Expression )
+    , action : ( Type, Elm.Expression -> Elm.Expression -> Elm.Expression )
     , head : Elm.Expression -> Elm.Expression
     , moduleName : List String
     }
@@ -198,7 +203,7 @@ buildNoState definitions builder_ =
                             , app = app
                             }
                 , localState = Nothing
-                , data = builder.data |> Tuple.second
+                , data = builder.data |> Tuple.second |> (\fn -> \_ -> fn)
                 , action = builder.pages |> Pages
                 , head = builder.head
                 , types =
@@ -214,7 +219,11 @@ buildNoState definitions builder_ =
                 }
 
 
-{-| -}
+{-| The helpers in this module help you generate a Route module file with the core boilerplate abstracted away.
+
+You can also define additional top-level declarations in the generated Route module using this helper.
+
+-}
 addDeclarations : List Elm.Declaration -> Builder -> Builder
 addDeclarations declarations builder =
     case builder of
@@ -337,7 +346,7 @@ buildWithLocalState definitions builder_ =
                                     }
                         , state = LocalState
                         }
-                , data = builder.data |> Tuple.second
+                , data = builder.data |> Tuple.second |> (\fn -> \_ -> fn)
                 , action = builder.pages |> Pages
                 , head = builder.head
                 , types =
@@ -465,7 +474,7 @@ buildWithSharedState definitions builder_ =
                                     }
                         , state = SharedState
                         }
-                , data = builder.data |> Tuple.second
+                , data = builder.data |> Tuple.second |> (\fn -> \_ -> fn)
                 , action = builder.pages |> Pages
                 , head = builder.head
                 , types =
@@ -487,7 +496,7 @@ type State
 
 
 type ActionOrPages
-    = Action (Elm.Expression -> Elm.Expression)
+    = Action (Elm.Expression -> Elm.Expression -> Elm.Expression)
     | Pages (Maybe Elm.Expression)
 
 
@@ -503,7 +512,7 @@ userFunction :
                 , subscriptions : Elm.Expression -> Elm.Expression -> Elm.Expression -> Elm.Expression -> Elm.Expression
                 , state : State
                 }
-        , data : Elm.Expression -> Elm.Expression
+        , data : Elm.Expression -> Elm.Expression -> Elm.Expression
         , action : ActionOrPages
         , head : Elm.Expression -> Elm.Expression
         , types : { model : Type, msg : Type, data : Type, actionData : Type }
@@ -629,7 +638,7 @@ userFunction moduleName definitions =
                             Elm.Declare.fn4
                                 "subscriptions"
                                 ( "routeParams", "RouteParams" |> Elm.Annotation.named [] |> Just )
-                                ( "path", Elm.Annotation.namedWith [ "Path" ] "Path" [] |> Just )
+                                ( "path", Elm.Annotation.namedWith [ "UrlPath" ] "UrlPath" [] |> Just )
                                 ( "shared", Just (Elm.Annotation.named [ "Shared" ] "Model") )
                                 ( "model", localType "Model" |> Just )
                                 (\routeParams path shared model ->
@@ -647,7 +656,7 @@ userFunction moduleName definitions =
                     Elm.Declare.function "data"
                         []
                         (\_ ->
-                            definitions.data Elm.unit
+                            definitions.data Elm.unit Elm.unit
                                 |> Elm.withType
                                     (case definitions.action of
                                         Pages _ ->
@@ -665,11 +674,16 @@ userFunction moduleName definitions =
                                 |> Elm.Annotation.named []
                                 |> Just
                           )
+                        , ( "request"
+                          , "Request"
+                                |> Elm.Annotation.named [ "Server", "Request" ]
+                                |> Just
+                          )
                         ]
                         (\args ->
                             case args of
-                                [ arg ] ->
-                                    definitions.data arg
+                                [ arg, arg2 ] ->
+                                    definitions.data arg arg2
                                         |> Elm.withType
                                             (case definitions.action of
                                                 Pages _ ->
@@ -693,11 +707,16 @@ userFunction moduleName definitions =
                                 |> Elm.Annotation.named []
                                 |> Just
                           )
+                        , ( "request"
+                          , "Request"
+                                |> Elm.Annotation.named [ "Server", "Request" ]
+                                |> Just
+                          )
                         ]
                         (\args ->
                             case args of
-                                [ arg ] ->
-                                    action_ arg |> Elm.withType (myType "ActionData")
+                                [ arg1, arg2 ] ->
+                                    action_ arg1 arg2 |> Elm.withType (myType "ActionData")
 
                                 _ ->
                                     Elm.unit
@@ -741,17 +760,17 @@ userFunction moduleName definitions =
                 Action _ ->
                     serverRender_
                         { action =
-                            \routeParams ->
+                            \routeParams request ->
                                 actionFn
                                     |> Maybe.map
                                         (\justActionFn ->
-                                            justActionFn.call [ routeParams ]
+                                            justActionFn.call [ routeParams, request ]
                                                 |> Elm.withType (myType "ActionData")
                                         )
                                     |> Maybe.withDefault Elm.unit
                         , data =
-                            \routeParams ->
-                                dataFn.call [ routeParams ]
+                            \routeParams request ->
+                                dataFn.call [ routeParams, request ]
                                     |> Elm.withType (myType "Data")
                         , head = headFn.call
                         }
@@ -852,16 +871,18 @@ localType =
 
 myType : String -> Elm.Annotation.Annotation
 myType dataType =
-    Elm.Annotation.namedWith [ "Server", "Request" ]
-        "Parser"
-        [ throwableTask
-            (Elm.Annotation.namedWith [ "Server", "Response" ]
-                "Response"
-                [ Elm.Annotation.named [] dataType
-                , Elm.Annotation.named [ "ErrorPage" ] "ErrorPage"
-                ]
-            )
-        ]
+    --Elm.Annotation.function
+    --    [ Elm.Annotation.namedWith [ "Server", "Request" ]
+    --        "Request"
+    --        []
+    --    ]
+    throwableTask
+        (Elm.Annotation.namedWith [ "Server", "Response" ]
+            "Response"
+            [ Elm.Annotation.named [] dataType
+            , Elm.Annotation.named [ "ErrorPage" ] "ErrorPage"
+            ]
+        )
 
 
 appType : Elm.Annotation.Annotation
@@ -875,8 +896,8 @@ appType =
 
 
 serverRender_ :
-    { data : Elm.Expression -> Elm.Expression
-    , action : Elm.Expression -> Elm.Expression
+    { data : Elm.Expression -> Elm.Expression -> Elm.Expression
+    , action : Elm.Expression -> Elm.Expression -> Elm.Expression
     , head : Elm.Expression -> Elm.Expression
     }
     -> Elm.Expression
@@ -911,22 +932,20 @@ serverRender_ serverRenderArg =
                               )
                             , ( "action"
                               , Elm.Annotation.function
-                                    [ Elm.Annotation.var "routeParams" ]
-                                    (Elm.Annotation.namedWith
-                                        [ "Server", "Request" ]
-                                        "Parser"
-                                        [ throwableTask
-                                            (Elm.Annotation.namedWith
-                                                [ "Server", "Response" ]
-                                                "Response"
-                                                [ Elm.Annotation.var "action"
-                                                , Elm.Annotation.namedWith
-                                                    [ "ErrorPage" ]
-                                                    "ErrorPage"
-                                                    []
-                                                ]
-                                            )
-                                        ]
+                                    [ Elm.Annotation.var "routeParams"
+                                    , Elm.Annotation.named [ "Server", "Request" ] "Request"
+                                    ]
+                                    (throwableTask
+                                        (Elm.Annotation.namedWith
+                                            [ "Server", "Response" ]
+                                            "Response"
+                                            [ Elm.Annotation.var "action"
+                                            , Elm.Annotation.namedWith
+                                                [ "ErrorPage" ]
+                                                "ErrorPage"
+                                                []
+                                            ]
+                                        )
                                     )
                               )
                             , ( "head"
@@ -959,10 +978,20 @@ serverRender_ serverRenderArg =
         [ Elm.record
             [ Tuple.pair
                 "data"
-                (Elm.functionReduced "serverRenderUnpack" serverRenderArg.data)
+                (Elm.functionReduced
+                    "dataUnpack"
+                    (\functionReducedUnpack ->
+                        Elm.functionReduced "dataUnpack2" (serverRenderArg.data functionReducedUnpack)
+                    )
+                )
             , Tuple.pair
                 "action"
-                (Elm.functionReduced "serverRenderUnpack" serverRenderArg.action)
+                (Elm.functionReduced
+                    "actionUnpack"
+                    (\functionReducedUnpack ->
+                        Elm.functionReduced "actionUnpack2" (serverRenderArg.action functionReducedUnpack)
+                    )
+                )
             , Tuple.pair
                 "head"
                 (Elm.functionReduced "serverRenderUnpack" serverRenderArg.head)
@@ -1199,7 +1228,7 @@ buildWithLocalState_ buildWithLocalStateArg buildWithLocalStateArg0 =
                                 , ( "subscriptions"
                                   , Elm.Annotation.function
                                         [ Elm.Annotation.var "routeParams"
-                                        , Elm.Annotation.namedWith [ "Path" ] "Path" []
+                                        , Elm.Annotation.namedWith [ "UrlPath" ] "UrlPath" []
                                         , Elm.Annotation.namedWith [ "Shared" ] "Model" []
                                         , Elm.Annotation.var "model"
                                         ]