elm-pages 3.0.0-beta.10 → 3.0.0-beta.13

package/src/DataSource.elm

@@ -38,38 +38,27 @@ So why not just get the data the old-fashioned way, with `elm/http`, for example
 A few reasons:
 
 1.  DataSource's allow you to pull in data that you wouldn't normally be able to access from an Elm app, like local files, or listings of files in a folder. Not only that, but the dev server knows to automatically hot reload the data when the files it depends on change, so you can edit the files you used in your DataSource and see the page hot reload as you save!
-2.  Because `elm-pages` has a build step, you know that your `DataSource.Http` requests succeeded, your decoders succeeded, your custom DataSource validations succeeded, and everything went smoothly. If something went wrong, you get a build failure and can deal with the issues before the site goes live. That means your users won't see those errors, and as a developer you don't need to handle those error cases in your code! Think of it as "parse, don't validate", but for your entire build.
-3.  You don't have to worry about an API being down, or hitting it repeatedly. You can build in data and it will end up as JSON files served up with all the other assets of your site. If your CDN (static site host) is down, then the rest of your site is probably down anyway. If your site host is up, then so is all of your `DataSource` data. Also, it will be served up extremely quickly without needing to wait for any database queries to be performed, `andThen` requests to be resolved, etc., because all of that work and waiting was done at build-time!
-4.  You can pre-render pages, including the SEO meta tags, with all that rich, well-typed Elm data available! That's something you can't accomplish with a vanilla Elm app, and it's one of the main use cases for elm-pages.
+2.  You can pre-render HTML for your pages, including the SEO meta tags, with all that rich, well-typed Elm data available! That's something you can't accomplish with a vanilla Elm app, and it's one of the main use cases for elm-pages.
+3.  Because `elm-pages` has a build step, you know that your `DataSource.Http` requests succeeded, your decoders succeeded, your custom DataSource validations succeeded, and everything went smoothly. If something went wrong, you get a build failure and can deal with the issues before the site goes live. That means your users won't see those errors, and as a developer you don't need to handle those error cases in your code! Think of it as "parse, don't validate", but for your entire build. In the case of server-rendered routes, a DataSource failure will render a 500 page, so more care needs to be taken to make sure all common errors are handled properly, but the tradeoff is that you can use DataSource's to pull in highly dynamic data and even render user-specific pages.
+4.  For static routes, you don't have to worry about an API being down, or hitting it repeatedly. You can build in data and it will end up as optimized binary-encoded data served up with all the other assets of your site. If your CDN (static site host) is down, then the rest of your site is probably down anyway. If your site host is up, then so is all of your `DataSource` data. Also, it will be served up extremely quickly without needing to wait for any database queries to be performed, `andThen` requests to be resolved, etc., because all of that work and waiting was done at build-time!
 
 
 ## Mental Model
 
 You can think of a DataSource as a declarative (not imperative) definition of data. It represents where to get the data from, and how to transform it (map, combine with other DataSources, etc.).
 
-Even though an HTTP request is non-deterministic, you should think of it that way as much as possible with a DataSource because elm-pages will only perform a given DataSource.Http request once, and
-it will share the result between any other DataSource.Http requests that have the exact same URL, Method, Body, and Headers.
 
-So calling a function to increment a counter on a server through an HTTP request would not be a good fit for a `DataSource`. Let's imagine we have an HTTP endpoint that gives these stateful results when called repeatedly:
+## How do I actually use a DataSource?
 
-<https://my-api.example.com/increment-counter>
--> Returns 1
-<https://my-api.example.com/increment-counter>
--> Returns 2
-<https://my-api.example.com/increment-counter>
--> Returns 3
+This is very similar to Cmd's in Elm. You don't perform a Cmd just by running that code, as you might in a language like JavaScript. Instead, a Cmd _will not do anything_ unless you pass it to The Elm Architecture to have it perform it for you.
+You pass a Cmd to The Elm Architecture by returning it in `init` or `update`. So actually a `Cmd` is just data describing a side-effect that the Elm runtime can perform, and how to build a `Msg` once it's done.
 
-If we define a `DataSource` that hits that endpoint:
+`DataSource`'s are very similar. A `DataSource` doesn't do anything just by "running" it. Just like a `Cmd`, it's only data that describes a side-effect to perform. Specifically, it describes a side-effect that the _elm-pages runtime_ can perform.
+There are a few places where we can pass a `DataSource` to the `elm-pages` runtime so it can perform it. Most commonly, you give a field called `data` in your Route Module's definition. Instead of giving a `Msg` when the side-effects are complete,
+the page will render once all of the side-effects have run and all the data is resolved. `elm-pages` makes the resolved data available your Route Module's `init`, `view`, `update`, and `head` functions, similar to how a regular Elm app passes `Msg`'s in
+to `update`.
 
-    data =
-        DataSource.Http.get
-            "https://my-api.example.com/increment-counter"
-            Decode.int
-
-No matter how many places we use that `DataSource`, its response will be "locked in" (let's say the response was `3`, then every page would have the same value of `3` for that request).
-
-So even though HTTP requests, JavaScript code, etc. can be non-deterministic, a `DataSource` always represents a single snapshot of a resource, and those values will be re-used as if they were a deterministic, declarative resource.
-So it's best to use that mental model to avoid confusion.
+Any place in your `elm-pages` app where the framework lets you pass in a value of type `DataSource` is a place where you can give `elm-pages` a DataSource to perform (for example, `Site.head` where you define global head tags for your site).
 
 
 ## Basics

package/src/Form.elm

@@ -272,7 +272,7 @@ import Dict exposing (Dict)
 import Form.Field as Field exposing (Field(..))
 import Form.FieldStatus as FieldStatus exposing (FieldStatus)
 import Form.FieldView
-import Form.Validation as Validation exposing (Combined, Validation)
+import Form.Validation as Validation exposing (Combined)
 import Html exposing (Html)
 import Html.Attributes as Attr
 import Html.Lazy
@@ -332,7 +332,7 @@ dynamic :
      ->
         Form
             error
-            { combine : Validation error parsed named constraints1
+            { combine : Validation.Validation error parsed named constraints1
             , view : subView
             }
             data
@@ -341,7 +341,7 @@ dynamic :
         Form
             error
             --((decider -> Validation error parsed named) -> combined)
-            ({ combine : decider -> Validation error parsed named constraints1
+            ({ combine : decider -> Validation.Validation error parsed named constraints1
              , view : decider -> subView
              }
              -> combineAndView
@@ -674,14 +674,14 @@ hiddenField name (Field fieldParser _) (Form definitions parseFn toInitialValues
 toServerForm :
     Form
         error
-        { combine : Validation error combined kind constraints
+        { combine : Validation.Validation error combined kind constraints
         , view : viewFn
         }
         data
     ->
         Form
             error
-            { combine : Validation error (DataSource (Validation error combined kind constraints)) kind constraints
+            { combine : Validation.Validation error (DataSource (Validation.Validation error combined kind constraints)) kind constraints
             , view : viewFn
             }
             data
@@ -694,7 +694,7 @@ toServerForm (Form a b c) =
                 { result : Dict String (List error)
                 , isMatchCandidate : Bool
                 , combineAndView :
-                    { combine : Validation error (DataSource (Validation error combined kind constraints)) kind constraints
+                    { combine : Validation.Validation error (DataSource (Validation.Validation error combined kind constraints)) kind constraints
                     , view : viewFn
                     }
                 }
@@ -844,7 +844,7 @@ parse :
     String
     -> AppContext app actionData
     -> data
-    -> Form error { info | combine : Validation error parsed named constraints } data
+    -> Form error { info | combine : Validation.Validation error parsed named constraints } data
     -> ( Maybe parsed, Dict String (List error) )
 parse formId app data (Form _ parser _) =
     -- TODO Get transition context from `app` so you can check if the current form is being submitted
@@ -883,7 +883,7 @@ insertIfNonempty key values dict =
 {-| -}
 runServerSide :
     List ( String, String )
-    -> Form error (Validation error parsed kind constraints) data
+    -> Form error (Validation.Validation error parsed kind constraints) data
     -> ( Bool, ( Maybe parsed, Dict String (List error) ) )
 runServerSide rawFormData (Form _ parser _) =
     let
@@ -989,7 +989,7 @@ renderHtml :
     ->
         FinalForm
             error
-            (Validation error parsed named constraints)
+            (Validation.Validation error parsed named constraints)
             data
             (Context error data
              -> List (Html (Pages.Msg.Msg msg))
@@ -1025,14 +1025,14 @@ toDynamicFetcher :
     ->
         Form
             error
-            { combine : Validation error parsed field constraints
+            { combine : Validation.Validation error parsed field constraints
             , view : Context error data -> view
             }
             data
     ->
         FinalForm
             error
-            (Validation error parsed field constraints)
+            (Validation.Validation error parsed field constraints)
             data
             (Context error data -> view)
             userMsg
@@ -1098,14 +1098,14 @@ toDynamicTransition :
     ->
         Form
             error
-            { combine : Validation error parsed field constraints
+            { combine : Validation.Validation error parsed field constraints
             , view : Context error data -> view
             }
             data
     ->
         FinalForm
             error
-            (Validation error parsed field constraints)
+            (Validation.Validation error parsed field constraints)
             data
             (Context error data -> view)
             userMsg
@@ -1126,7 +1126,7 @@ toDynamicTransition name (Form a b c) =
                 { result : Dict String (List error)
                 , isMatchCandidate : Bool
                 , combineAndView :
-                    { combine : Validation error parsed field constraints
+                    { combine : Validation.Validation error parsed field constraints
                     , view : Context error data -> view
                     }
                 }
@@ -1136,7 +1136,7 @@ toDynamicTransition name (Form a b c) =
                  -> FormState
                  ->
                     { result :
-                        ( Validation error parsed field constraints
+                        ( Validation.Validation error parsed field constraints
                         , Dict String (List error)
                         )
                     , isMatchCandidate : Bool
@@ -1150,7 +1150,7 @@ toDynamicTransition name (Form a b c) =
                         { result : Dict String (List error)
                         , isMatchCandidate : Bool
                         , combineAndView :
-                            { combine : Validation error parsed field constraints
+                            { combine : Validation.Validation error parsed field constraints
                             , view : Context error data -> view
                             }
                         }
@@ -1190,7 +1190,7 @@ renderStyledHtml :
     ->
         FinalForm
             error
-            (Validation error parsed named constraints)
+            (Validation.Validation error parsed named constraints)
             data
             (Context error data
              -> List (Html.Styled.Html (Pages.Msg.Msg msg))
@@ -1219,7 +1219,7 @@ renderHelper :
     -> RenderOptions msg
     -> AppContext app actionData
     -> data
-    -> FormInternal error (Validation error parsed named constraints) data (Context error data -> List (Html (Pages.Msg.Msg msg)))
+    -> FormInternal error (Validation.Validation error parsed named constraints) data (Context error data -> List (Html (Pages.Msg.Msg msg)))
     -> Html (Pages.Msg.Msg msg)
 renderHelper attrs maybe options formState data form =
     -- TODO Get transition context from `app` so you can check if the current form is being submitted
@@ -1261,7 +1261,7 @@ renderStyledHelper :
     -> RenderOptions msg
     -> AppContext app actionData
     -> data
-    -> FormInternal error (Validation error parsed named constraints) data (Context error data -> List (Html.Styled.Html (Pages.Msg.Msg msg)))
+    -> FormInternal error (Validation.Validation error parsed named constraints) data (Context error data -> List (Html.Styled.Html (Pages.Msg.Msg msg)))
     -> Html.Styled.Html (Pages.Msg.Msg msg)
 renderStyledHelper attrs maybe options formState data form =
     -- TODO Get transition context from `app` so you can check if the current form is being submitted
@@ -1304,7 +1304,7 @@ helperValues :
     -> AppContext app actionData
     -> data
     ---> Form error parsed data view
-    -> FormInternal error (Validation error parsed named constraints) data (Context error data -> List view)
+    -> FormInternal error (Validation.Validation error parsed named constraints) data (Context error data -> List view)
     -> { formId : String, hiddenInputs : List view, children : List view, isValid : Bool }
 helperValues toHiddenInput maybe options formState data (FormInternal fieldDefinitions parser toInitialValues) =
     let
@@ -1343,18 +1343,18 @@ helperValues toHiddenInput maybe options formState data (FormInternal fieldDefin
                 |> Dict.union part2
 
         parsed :
-            { result : ( Validation error parsed named constraints, Dict String (List error) )
+            { result : ( Validation.Validation error parsed named constraints, Dict String (List error) )
             , isMatchCandidate : Bool
             , view : Context error data -> List view
             }
         parsed =
             parser (Just data) thisFormState
 
-        withoutServerErrors : Validation error parsed named constraints
+        withoutServerErrors : Validation.Validation error parsed named constraints
         withoutServerErrors =
             parsed |> mergeResults
 
-        withServerErrors : Validation error parsed named constraints
+        withServerErrors : Validation.Validation error parsed named constraints
         withServerErrors =
             mergeResults
                 { parsed
@@ -1498,7 +1498,7 @@ initCombined :
         Form
             error
             { combineAndView
-                | combine : Validation error parsed kind constraints
+                | combine : Validation.Validation error parsed kind constraints
             }
             input
     -> ServerForms error combined
@@ -1511,7 +1511,7 @@ initCombined mapFn (Form _ parseFn _) =
                     foo :
                         { result : Dict String (List error)
                         , isMatchCandidate : Bool
-                        , combineAndView : { combineAndView | combine : Validation error parsed kind constraints }
+                        , combineAndView : { combineAndView | combine : Validation.Validation error parsed kind constraints }
                         }
                     foo =
                         parseFn Nothing formState
@@ -1532,7 +1532,7 @@ combine :
         Form
             error
             { combineAndView
-                | combine : Validation error parsed kind constraints
+                | combine : Validation.Validation error parsed kind constraints
             }
             input
     -> ServerForms error combined
@@ -1546,7 +1546,7 @@ combine mapFn (Form _ parseFn _) (ServerForms serverForms) =
                             foo :
                                 { result : Dict String (List error)
                                 , isMatchCandidate : Bool
-                                , combineAndView : { combineAndView | combine : Validation error parsed kind constraints }
+                                , combineAndView : { combineAndView | combine : Validation.Validation error parsed kind constraints }
                                 }
                             foo =
                                 parseFn Nothing formState
@@ -1568,10 +1568,10 @@ initCombinedServer :
         Form
             error
             { combineAndView
-                | combine : Combined error (DataSource (Validation error parsed kind constraints))
+                | combine : Combined error (DataSource (Validation.Validation error parsed kind constraints))
             }
             input
-    -> ServerForms error (DataSource (Validation error combined kind constraints))
+    -> ServerForms error (DataSource (Validation.Validation error combined kind constraints))
 initCombinedServer mapFn serverForms =
     initCombined (DataSource.map (Validation.map mapFn)) serverForms
 
@@ -1584,11 +1584,11 @@ combineServer :
             error
             { combineAndView
                 | combine :
-                    Combined error (DataSource (Validation error parsed kind constraints))
+                    Combined error (DataSource (Validation.Validation error parsed kind constraints))
             }
             input
-    -> ServerForms error (DataSource (Validation error combined kind constraints))
-    -> ServerForms error (DataSource (Validation error combined kind constraints))
+    -> ServerForms error (DataSource (Validation.Validation error combined kind constraints))
+    -> ServerForms error (DataSource (Validation.Validation error combined kind constraints))
 combineServer mapFn a b =
     combine (DataSource.map (Validation.map mapFn)) a b
 

package/src/Head.elm

@@ -9,14 +9,118 @@ module Head exposing
     , toJson, canonicalLink
     )
 
-{-| This module contains low-level functions for building up
-values that will be rendered into the page's `<head>` tag
-when you run `elm-pages build`. Most likely the `Head.Seo` module
-will do everything you need out of the box, and you will just need to import `Head`
-so you can use the `Tag` type in your type annotations.
-
-But this module might be useful if you have a special use case, or if you are
-writing a plugin package to extend `elm-pages`.
+{-| This module contains functions for building up
+tags with metadata that will be rendered into the page's `<head>` tag
+when your page is pre-rendered (or server-rendered, in the case of your server-rendered Route Modules). See also [`Head.Seo`](Head-Seo),
+which has some helper functions for defining OpenGraph and Twitter tags.
+
+One of the unique benefits of using `elm-pages` is that all of your routes (both pre-rendered and server-rendered) fully
+render the HTML of your page. That includes the full initial `view` (with the DataSource resolved, and the `Model` from `init`).
+The HTML response also includes all of the `Head` tags, which are defined in two places:
+
+1.  `app/Site.elm` - there is a `head` definition in `Site.elm` where you define global head tags that will be included on every rendered page.
+
+2.  In each Route Module - there is a `head` function where you have access to both the resolved `DataSource` and the `RouteParams` for the page and can return head tags based on that.
+
+Here is a common set of global head tags that we can define in `Site.elm`:
+
+    module Site exposing (canonicalUrl, config)
+
+    import DataSource exposing (DataSource)
+    import Head
+    import MimeType
+    import SiteConfig exposing (SiteConfig)
+
+    config : SiteConfig
+    config =
+    { canonicalUrl = "<https://elm-pages.com">
+    , head = head
+    }
+
+    head : DataSource (List Head.Tag)
+    head =
+    [ Head.metaName "viewport" (Head.raw "width=device-width,initial-scale=1")
+    , Head.metaName "mobile-web-app-capable" (Head.raw "yes")
+    , Head.metaName "theme-color" (Head.raw "#ffffff")
+    , Head.metaName "apple-mobile-web-app-capable" (Head.raw "yes")
+    , Head.metaName "apple-mobile-web-app-status-bar-style" (Head.raw "black-translucent")
+    , Head.icon [ ( 32, 32 ) ] MimeType.Png (cloudinaryIcon MimeType.Png 32)
+    , Head.icon [ ( 16, 16 ) ] MimeType.Png (cloudinaryIcon MimeType.Png 16)
+    , Head.appleTouchIcon (Just 180) (cloudinaryIcon MimeType.Png 180)
+    , Head.appleTouchIcon (Just 192) (cloudinaryIcon MimeType.Png 192)
+    ]
+    |> DataSource.succeed
+
+And here is a `head` function for a Route Module for a blog post. Note that we have access to our `DataSource` Data and
+are using it to populate article metadata like the article's image, publish date, etc.
+
+    import Article
+    import DataSource
+    import Date
+    import Head
+    import Head.Seo
+    import Path
+    import Route exposing (Route)
+    import RouteBuilder exposing (StatelessRoute, StaticPayload)
+
+    type alias RouteParams =
+        { slug : String }
+
+    type alias Data =
+        { metadata : ArticleMetadata
+        , body : List Markdown.Block.Block
+        }
+
+    route : StatelessRoute RouteParams Data ActionData
+    route =
+        RouteBuilder.preRender
+            { data = data
+            , head = head
+            , pages = pages
+            }
+            |> RouteBuilder.buildNoState { view = view }
+
+    head :
+        StaticPayload Data ActionData RouteParams
+        -> List Head.Tag
+    head static =
+        let
+            metadata =
+                static.data.metadata
+        in
+        Head.Seo.summaryLarge
+            { canonicalUrlOverride = Nothing
+            , siteName = "elm-pages"
+            , image =
+                { url = metadata.image
+                , alt = metadata.description
+                , dimensions = Nothing
+                , mimeType = Nothing
+                }
+            , description = metadata.description
+            , locale = Nothing
+            , title = metadata.title
+            }
+            |> Head.Seo.article
+                { tags = []
+                , section = Nothing
+                , publishedTime = Just (DateOrDateTime.Date metadata.published)
+                , modifiedTime = Nothing
+                , expirationTime = Nothing
+                }
+
+
+## Why is pre-rendered HTML important? Does it still matter for SEO?
+
+Many search engines are able to execute JavaScript now. However, not all are, and even with crawlers like Google, there
+is a longer lead time for your pages to be indexed when you have HTML with a blank page that is only visible after the JavaScript executes.
+
+But most importantly, many tools that unfurl links will not execute JavaScript at all, but rather simply do a simple pass to parse your `<head>` tags.
+It is not viable or reliable to add `<head>` tags for metadata on the client-side, it must be present in the initial HTML payload. Otherwise you may not
+get unfurling preview content when you share a link to your site on Slack, Twitter, etc.
+
+
+## Building up Head Tags
 
 @docs Tag, metaName, metaProperty, metaRedirect
 @docs rssLink, sitemapLink, rootLanguage, manifestLink

package/src/MultiDict.elm

@@ -0,0 +1,49 @@
+module MultiDict exposing (MultiDict, empty, get, insert, keys, remove, set)
+
+import Dict exposing (Dict)
+import List.Extra
+import List.Nonempty as NonEmpty
+
+
+type alias NonEmpty a =
+    NonEmpty.Nonempty a
+
+
+type MultiDict k v
+    = MultiDict (Dict k (NonEmpty v))
+
+
+empty : MultiDict k v
+empty =
+    MultiDict Dict.empty
+
+
+insert : comparable -> v -> MultiDict comparable v -> MultiDict comparable v
+insert key value (MultiDict dict) =
+    MultiDict
+        (Dict.update key (Maybe.map (NonEmpty.cons value) >> Maybe.withDefault (NonEmpty.fromElement value) >> Just) dict)
+
+
+get : comparable -> MultiDict comparable v -> List v
+get key (MultiDict dict) =
+    Dict.get key dict
+        |> Maybe.map NonEmpty.toList
+        |> Maybe.withDefault []
+
+
+keys : MultiDict k v -> List k
+keys (MultiDict dict) =
+    Dict.toList dict
+        |> List.concatMap (\( k, vs ) -> List.repeat (NonEmpty.length vs) k)
+
+
+remove : comparable -> v -> MultiDict comparable v -> MultiDict comparable v
+remove key value (MultiDict dict) =
+    MultiDict
+        (Dict.update key (Maybe.andThen (NonEmpty.toList >> List.Extra.remove value >> NonEmpty.fromList)) dict)
+
+
+set : comparable -> List v -> MultiDict comparable v -> MultiDict comparable v
+set key values (MultiDict dict) =
+    MultiDict
+        (Dict.update key (\_ -> NonEmpty.fromList values) dict)

package/src/Pages/Generate.elm

@@ -5,7 +5,10 @@ module Pages.Generate exposing
     , preRender, single
     )
 
-{-|
+{-| 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).
 
 
 ## Initializing the Generator Builder

package/src/Pages/GeneratorProgramConfig.elm

@@ -0,0 +1,15 @@
+module Pages.GeneratorProgramConfig exposing (GeneratorProgramConfig)
+
+import Json.Decode as Decode
+import Json.Encode
+import Pages.Internal.Platform.ToJsPayload
+import Pages.Script exposing (Script)
+
+
+type alias GeneratorProgramConfig =
+    { data : Script
+    , toJsPort : Json.Encode.Value -> Cmd Never
+    , fromJsPort : Sub Decode.Value
+    , gotBatchSub : Sub Decode.Value
+    , sendPageData : Pages.Internal.Platform.ToJsPayload.NewThingForPort -> Cmd Never
+    }

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

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