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

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
@@ -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

package/src/Server/Request.elm

@@ -98,6 +98,7 @@ import Internal.Request
 import Json.Decode
 import Json.Encode
 import List.NonEmpty
+import Pages.Form
 import QueryParams
 import Time
 import Url
@@ -891,7 +892,7 @@ runForm validation =
 
 {-| -}
 formDataWithServerValidation :
-    Form.Handler.Handler error (BackendTask FatalError (Validation.Validation error combined kind constraints))
+    Pages.Form.Handler error combined
     -> Parser (BackendTask FatalError (Result (Form.ServerResponse error) ( Form.ServerResponse error, combined )))
 formDataWithServerValidation formParsers =
     rawFormData

package/src/Server/Session.elm

@@ -318,7 +318,7 @@ encodeSessionUpdate config toRequest userRequestData sessionResult =
                     (\encoded ->
                         response
                             |> Server.Response.withSetCookieHeader
-                                (SetCookie.setCookie config.name encoded (config.options |> Maybe.withDefault SetCookie.initOptions))
+                                (SetCookie.setCookie config.name encoded (config.options |> Maybe.withDefault SetCookie.options))
                     )
                     (sign config.secrets
                         (encodeNonExpiringPairs sessionUpdate)

package/src/Server/SetCookie.elm

@@ -1,8 +1,8 @@
 module Server.SetCookie exposing
-    ( SetCookie
-    , SameSite(..)
-    , Options, initOptions
-    , withImmediateExpiration, makeVisibleToJavaScript, nonSecure, setCookie, withDomain, withExpiration, withMaxAge, withPath, withoutPath, withSameSite
+    ( SetCookie, setCookie
+    , Options, options
+    , SameSite(..), withSameSite
+    , withImmediateExpiration, makeVisibleToJavaScript, nonSecure, withDomain, withExpiration, withMaxAge, withPath, withoutPath
     , toString
     )
 
@@ -20,16 +20,29 @@ You can learn more about the basics of cookies in the Web Platform in these help
   - <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie>
   - <https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies>
 
-@docs SetCookie
+@docs SetCookie, setCookie
 
-@docs SameSite
 
+## Building Options
 
-## Options
+Usually you'll want to start by creating default `Options` with `options` and then overriding defaults using the `with...` helpers.
 
-@docs Options, initOptions
+    import Server.SetCookie as SetCookie
 
-@docs withImmediateExpiration, makeVisibleToJavaScript, nonSecure, setCookie, withDomain, withExpiration, withMaxAge, withPath, withoutPath, withSameSite
+    options : SetCookie.Options
+    options =
+        SetCookie.options
+            |> SetCookie.nonSecure
+            |> SetCookie.withMaxAge 123
+            |> SetCookie.makeVisibleToJavaScript
+            |> SetCookie.withoutPath
+            |> SetCookie.setCookie "id" "a3fWa"
+
+@docs Options, options
+
+@docs SameSite, withSameSite
+
+@docs withImmediateExpiration, makeVisibleToJavaScript, nonSecure, withDomain, withExpiration, withMaxAge, withPath, withoutPath
 
 
 ## Internal
@@ -51,7 +64,8 @@ type alias SetCookie =
     }
 
 
-{-| -}
+{-| The set of possible configuration options. You can configure this record directly, or use the `with...` helpers.
+-}
 type alias Options =
     { expiration : Maybe Time.Posix
     , visibleToJavaScript : Bool
@@ -63,7 +77,15 @@ type alias Options =
     }
 
 
-{-| -}
+{-| Possible values for [the cookie's same-site value](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value).
+
+The default option is [`Lax`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#lax) (Lax does not send
+cookies in cross-origin requests so it is a good default for most cases, but [`Strict`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#strict)
+is even more restrictive).
+
+Override the default option using [`withSameSite`](#withSameSite).
+
+-}
 type SameSite
     = Strict
     | Lax
@@ -95,24 +117,24 @@ toString builder =
             else
                 ""
 
-        options : Options
-        options =
+        options_ : Options
+        options_ =
             builder.options
 
         httpOnly : Bool
         httpOnly =
-            not options.visibleToJavaScript
+            not options_.visibleToJavaScript
     in
     builder.name
         ++ "="
         ++ Url.percentEncode builder.value
-        ++ option "Expires" (options.expiration |> Maybe.map Utc.fromTime)
-        ++ option "Max-Age" (options.maxAge |> Maybe.map String.fromInt)
-        ++ option "Path" options.path
-        ++ option "Domain" options.domain
-        ++ option "SameSite" (options.sameSite |> Maybe.map sameSiteToString)
+        ++ option "Expires" (options_.expiration |> Maybe.map Utc.fromTime)
+        ++ option "Max-Age" (options_.maxAge |> Maybe.map String.fromInt)
+        ++ option "Path" options_.path
+        ++ option "Domain" options_.domain
+        ++ option "SameSite" (options_.sameSite |> Maybe.map sameSiteToString)
         ++ boolOption "HttpOnly" httpOnly
-        ++ boolOption "Secure" options.secure
+        ++ boolOption "Secure" options_.secure
 
 
 sameSiteToString : SameSite -> String
@@ -128,18 +150,22 @@ sameSiteToString sameSite =
             "None"
 
 
-{-| -}
+{-| Create a `SetCookie` record with the given name, value, and [`Options`](Options]. To add a `Set-Cookie` header, you can
+pass this value with [`Server.Response.withSetCookieHeader`](Server-Response#withSetCookieHeader). Or for more low-level
+uses you can stringify the value manually with [`toString`](#toString).
+-}
 setCookie : String -> String -> Options -> SetCookie
-setCookie name value options =
+setCookie name value options_ =
     { name = name
     , value = value
-    , options = options
+    , options = options_
     }
 
 
-{-| -}
-initOptions : Options
-initOptions =
+{-| Initialize the default `SetCookie` `Options`. Can be configured directly through a record update, or with `withExpiration`, etc.
+-}
+options : Options
+options =
     { expiration = Nothing
     , visibleToJavaScript = False
     , maxAge = Nothing
@@ -158,7 +184,9 @@ withExpiration time builder =
     }
 
 
-{-| -}
+{-| Sets [`Expires`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#expiresdate) to `Time.millisToPosix 0`,
+which effectively tells the browser to delete the cookie immediately (by giving it an expiration date in the past).
+-}
 withImmediateExpiration : Options -> Options
 withImmediateExpiration builder =
     { builder
@@ -184,7 +212,8 @@ makeVisibleToJavaScript builder =
     }
 
 
-{-| -}
+{-| Sets the `Set-Cookie`'s [`Max-Age`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#max-agenumber).
+-}
 withMaxAge : Int -> Options -> Options
 withMaxAge maxAge builder =
     { builder
@@ -192,7 +221,11 @@ withMaxAge maxAge builder =
     }
 
 
-{-| -}
+{-| Sets the `Set-Cookie`'s [`Path`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#pathpath-value).
+
+The default value is `/`, which will match any sub-directories or the root directory. See also [\`withoutPath](#withoutPath)
+
+-}
 withPath : String -> Options -> Options
 withPath path builder =
     { builder
@@ -200,7 +233,13 @@ withPath path builder =
     }
 
 
-{-| -}
+{-|
+
+> If the server omits the Path attribute, the user agent will use the "directory" of the request-uri's path component as the default value.
+
+Source: <https://www.rfc-editor.org/rfc/rfc6265>. See <https://stackoverflow.com/a/43336097>.
+
+-}
 withoutPath : Options -> Options
 withoutPath builder =
     { builder
@@ -208,7 +247,8 @@ withoutPath builder =
     }
 
 
-{-| -}
+{-| Sets the `Set-Cookie`'s [`Domain`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#domaindomain-value).
+-}
 withDomain : String -> Options -> Options
 withDomain domain builder =
     { builder

package/src/{Path.elm → UrlPath.elm}

@@ -1,5 +1,5 @@
-module Path exposing
-    ( Path, join, fromString
+module UrlPath exposing
+    ( UrlPath, join, fromString
     , toAbsolute, toRelative, toSegments
     )
 
@@ -9,27 +9,27 @@ This helper lets you combine together path parts without worrying about having t
 These two examples will result in the same URL, even though the first example has trailing and leading slashes, and the
 second does not.
 
-    Path.join [ "/blog/", "/post-1/" ]
-        |> Path.toAbsolute
+    UrlPath.join [ "/blog/", "/post-1/" ]
+        |> UrlPath.toAbsolute
     --> "/blog/post-1"
 
-    Path.join [ "blog", "post-1" ]
-        |> Path.toAbsolute
+    UrlPath.join [ "blog", "post-1" ]
+        |> UrlPath.toAbsolute
     --> "/blog/post-1"
 
 We can also safely join Strings that include multiple path parts, a single path part per string, or a mix of the two:
 
-    Path.join [ "/articles/archive/", "1977", "06", "10", "post-1" ]
-        |> Path.toAbsolute
+    UrlPath.join [ "/articles/archive/", "1977", "06", "10", "post-1" ]
+        |> UrlPath.toAbsolute
     --> "/articles/archive/1977/06/10/post-1"
 
 
-## Creating Paths
+## Creating UrlPaths
 
-@docs Path, join, fromString
+@docs UrlPath, join, fromString
 
 
-## Turning Paths to String
+## Turning UrlPaths to String
 
 @docs toAbsolute, toRelative, toSegments
 
@@ -40,35 +40,35 @@ import Pages.Internal.String exposing (chopEnd, chopStart)
 
 {-| The path portion of the URL, normalized to ensure that path segments are joined with `/`s in the right places (no doubled up or missing slashes).
 -}
-type alias Path =
+type alias UrlPath =
     List String
 
 
 {-| Turn a Path to a relative URL.
 -}
-join : Path -> Path
+join : UrlPath -> UrlPath
 join parts =
     parts
         |> List.filter (\segment -> segment /= "/")
         |> List.map normalize
 
 
-{-| Turn a Path to a relative URL.
+{-| Turn a UrlPath to a relative URL.
 -}
-toRelative : Path -> String
+toRelative : UrlPath -> String
 toRelative parts =
     join parts
         |> String.join "/"
 
 
-{-| Create a Path from a path String.
+{-| Create a UrlPath from a path String.
 
-    Path.fromString "blog/post-1/"
-        |> Path.toAbsolute
+    UrlPath.fromString "blog/post-1/"
+        |> UrlPath.toAbsolute
         |> Expect.equal "/blog/post-1"
 
 -}
-fromString : String -> Path
+fromString : String -> UrlPath
 fromString path =
     path
         |> toSegments
@@ -80,9 +80,9 @@ toSegments path =
     path |> String.split "/" |> List.filter ((/=) "")
 
 
-{-| Turn a Path to an absolute URL (with no trailing slash).
+{-| Turn a UrlPath to an absolute URL (with no trailing slash).
 -}
-toAbsolute : Path -> String
+toAbsolute : UrlPath -> String
 toAbsolute path =
     "/" ++ toRelative path
 

package/src/Pages/Transition.elm

@@ -1,79 +0,0 @@
-module Pages.Transition exposing
-    ( Transition(..), LoadingState(..), map, FormData
-    , FetcherState, FetcherSubmitStatus(..)
-    )
-
-{-|
-
-@docs Transition, LoadingState, map, FormData
-
-
-## Fetchers
-
-@docs FetcherState, FetcherSubmitStatus
-
--}
-
-import Form
-import Path exposing (Path)
-import Time
-
-
-{-| -}
-type alias FormData =
-    { fields : List ( String, String )
-    , method : Form.Method
-    , action : String
-    , id : Maybe String
-    }
-
-
-{-| -}
-type Transition
-    = Submitting FormData
-    | LoadAfterSubmit FormData Path LoadingState
-    | Loading Path LoadingState
-
-
-{-| -}
-type LoadingState
-    = Redirecting
-    | Load
-    | ActionRedirect
-
-
-{-| -}
-type alias FetcherState actionData =
-    { status : FetcherSubmitStatus actionData
-    , payload : FormData
-    , initiatedAt : Time.Posix
-    }
-
-
-{-| -}
-type FetcherSubmitStatus actionData
-    = FetcherSubmitting
-    | FetcherReloading actionData
-    | FetcherComplete actionData
-
-
-{-| -}
-map : (a -> b) -> FetcherState a -> FetcherState b
-map mapFn fetcherState =
-    { status = mapStatus mapFn fetcherState.status
-    , payload = fetcherState.payload
-    , initiatedAt = fetcherState.initiatedAt
-    }
-
-
-mapStatus : (a -> b) -> FetcherSubmitStatus a -> FetcherSubmitStatus b
-mapStatus mapFn fetcherSubmitStatus =
-    case fetcherSubmitStatus of
-        FetcherSubmitting ->
-            FetcherSubmitting
-
-        FetcherReloading value ->
-            FetcherReloading (mapFn value)
-
-        FetcherComplete value ->
-            FetcherComplete (mapFn value)