elm-pages 3.0.0-beta.3 → 3.0.0-beta.30

package/src/FatalError.elm

@@ -0,0 +1,89 @@
+module FatalError exposing (FatalError, fromString, recoverable)
+
+{-| The Elm language doesn't have the concept of exceptions or special control flow for errors. It just has
+Custom Types, and by convention types like `Result` and the `Err` variant are used to represent possible failure states
+and combine together different error states.
+
+`elm-pages` doesn't change that, Elm still doesn't have special exception control flow at the language level. It does have
+a type, which is just a regular old Elm type, called `FatalError`. Why? Because this plain old Elm type does have one
+special characteristic - the `elm-pages` framework knows how to turn it into an error message. This becomes interesting
+because an `elm-pages` app has several places that accept a value of type `BackendTask FatalError.FatalError value`.
+This design lets the `elm-pages` framework do some of the work for you.
+
+For example, if you wanted to handle possible errors to present them to the user
+
+    type alias Data =
+        String
+
+    data : RouteParams -> BackendTask FatalError Data
+    data routeParams =
+        BackendTask.Http.getJson "https://api.github.com/repos/dillonkearns/elm-pages"
+            (Decode.field "description" Decode.string)
+            |> BackendTask.onError
+                (\error ->
+                    case FatalError.unwrap error of
+                        BackendTask.Http.BadStatus metadata string ->
+                            if metadata.statusCode == 401 || metadata.statusCode == 403 || metadata.statusCode == 404 then
+                                BackendTask.succeed "Either this repo doesn't exist or you don't have access to it."
+
+                            else
+                                -- we're only handling these expected error cases. In the case of an HTTP timeout,
+                                -- we'll let the error propagate as a FatalError
+                                BackendTask.fail error |> BackendTask.allowFatal
+
+                        _ ->
+                            BackendTask.fail error |> BackendTask.allowFatal
+                )
+
+This can be a lot of work for all possible errors, though. If you don't expect this kind of error (it's an _exceptional_ case),
+you can let the framework handle it if the error ever does unexpectedly occur.
+
+    data : RouteParams -> BackendTask FatalError Data
+    data routeParams =
+        BackendTask.Http.getJson "https://api.github.com/repos/dillonkearns/elm-pages"
+            (Decode.field "description" Decode.string)
+            |> BackendTask.allowFatal
+
+This is especially useful for pages generated at build-time (`RouteBuilder.preRender`) where you want the build
+to fail if anything unexpected happens. With pre-rendered routes, you know that these error cases won't
+be seen by users, so it's often a great idea to just let the framework handle these unexpected errors so a developer can
+debug them and see what went wrong. In the example above, maybe we are only pre-rendering pages for a set of known
+GitHub Repositories, so a Not Found or Unauthorized HTTP error would be unexpected and should stop the build so we can fix the
+issue.
+
+In the case of server-rendered Routes (`RouteBuilder.serverRender`), `elm-pages` will show your 500 error page
+when these errors occur.
+
+@docs FatalError, fromString, recoverable
+
+-}
+
+import Pages.Internal.FatalError
+
+
+{-| -}
+type alias FatalError =
+    Pages.Internal.FatalError.FatalError
+
+
+{-| -}
+build : { title : String, body : String } -> FatalError
+build info =
+    Pages.Internal.FatalError.FatalError info
+
+
+{-| -}
+fromString : String -> FatalError
+fromString string =
+    build
+        { title = "Custom Error"
+        , body = string
+        }
+
+
+{-| -}
+recoverable : { title : String, body : String } -> error -> { fatal : FatalError, recoverable : error }
+recoverable info value =
+    { fatal = build info
+    , recoverable = value
+    }

package/src/Form/Field.elm

@@ -3,7 +3,7 @@ module Form.Field exposing
     , select, range, OutsideRange(..)
     , date, time, TimeOfDay
     , Field(..), FieldInfo, exactValue
-    , required, withClientValidation, withInitialValue, map
+    , required, withClientValidation, withInitialValue, withOptionalInitialValue, map
     , email, password, search, telephone, url, textarea
     , withMax, withMin, withStep, withMinLength, withMaxLength
     , No, Yes
@@ -34,7 +34,7 @@ module Form.Field exposing
 
 ## Field Configuration
 
-@docs required, withClientValidation, withInitialValue, map
+@docs required, withClientValidation, withInitialValue, withOptionalInitialValue, map
 
 
 ## Text Field Display Options
@@ -67,7 +67,7 @@ type Field error parsed data kind constraints
 
 {-| -}
 type alias FieldInfo error parsed data =
-    { initialValue : Maybe (data -> String)
+    { initialValue : Maybe (data -> Maybe String)
     , decode : Maybe String -> ( Maybe parsed, List error )
     , properties : List ( String, Encode.Value )
     }
@@ -327,7 +327,7 @@ exactValue :
             }
 exactValue initialValue error =
     Field
-        { initialValue = Just (\_ -> initialValue)
+        { initialValue = Just (\_ -> Just initialValue)
         , decode =
             \rawValue ->
                 if rawValue == Just initialValue then
@@ -490,10 +490,11 @@ url (Field field _) =
 
 {-| -}
 textarea :
-    Field error parsed data Input { constraints | plainText : () }
+    { rows : Maybe Int, cols : Maybe Int }
+    -> Field error parsed data Input { constraints | plainText : () }
     -> Field error parsed data Input constraints
-textarea (Field field _) =
-    Field field (FieldView.Input FieldView.Textarea)
+textarea options (Field field _) =
+    Field field (FieldView.Input (FieldView.Textarea options))
 
 
 {-| -}
@@ -535,7 +536,7 @@ range info field =
         |> required info.missing
         |> withMin info.min (info.invalid BelowRange)
         |> withMax info.max (info.invalid AboveRange)
-        |> (\(Field innerField _) -> Field { innerField | initialValue = Just (info.initial >> Form.Value.toString) } (FieldView.Input FieldView.Range))
+        |> (\(Field innerField _) -> Field { innerField | initialValue = Just (info.initial >> Form.Value.toString >> Just) } (FieldView.Input FieldView.Range))
 
 
 {-| -}
@@ -576,7 +577,18 @@ withInitialValue toInitialValue (Field field kind) =
     Field
         { field
             | initialValue =
-                Just (toInitialValue >> Form.Value.toString)
+                Just (toInitialValue >> Form.Value.toString >> Just)
+        }
+        kind
+
+
+{-| -}
+withOptionalInitialValue : (data -> Maybe (Form.Value.Value valueType)) -> Field error value data kind { constraints | initial : valueType } -> Field error value data kind constraints
+withOptionalInitialValue toInitialValue (Field field kind) =
+    Field
+        { field
+            | initialValue =
+                Just (toInitialValue >> Maybe.map Form.Value.toString)
         }
         kind
 

package/src/Form/FieldView.elm

@@ -1,16 +1,16 @@
 module Form.FieldView exposing
-    ( Input(..), InputType(..), Options(..), input, inputTypeToString, radio, toHtmlProperties, Hidden(..), select
-    , radioStyled, inputStyled
+    ( Input(..), InputType(..), Options(..), input, inputTypeToString, radio, toHtmlProperties, Hidden(..), select, valueButton
+    , radioStyled, inputStyled, valueButtonStyled
     )
 
 {-|
 
-@docs Input, InputType, Options, input, inputTypeToString, radio, toHtmlProperties, Hidden, select
+@docs Input, InputType, Options, input, inputTypeToString, radio, toHtmlProperties, Hidden, select, valueButton
 
 
 ## Html.Styled Helpers
 
-@docs radioStyled, inputStyled
+@docs radioStyled, inputStyled, valueButtonStyled
 
 -}
 
@@ -40,7 +40,7 @@ type InputType
     | Password
     | Email
     | Url
-    | Textarea
+    | Textarea { rows : Maybe Int, cols : Maybe Int }
 
 
 {-| -}
@@ -50,7 +50,7 @@ inputTypeToString inputType =
         Text ->
             "text"
 
-        Textarea ->
+        Textarea _ ->
             "text"
 
         Number ->
@@ -103,6 +103,74 @@ type Options a
     = Options (String -> Maybe a) (List String)
 
 
+{-| Gives you a submit button that will submit the form with a specific value for the given Field.
+-}
+valueButton :
+    String
+    -> List (Html.Attribute msg)
+    -> List (Html msg)
+    -> Form.Validation.Field error parsed kind
+    -> Html msg
+valueButton exactValue attrs children (Validation viewField fieldName _) =
+    let
+        justViewField : ViewField kind
+        justViewField =
+            expectViewField viewField
+
+        rawField : { name : String, value : Maybe String, kind : ( kind, List ( String, Encode.Value ) ) }
+        rawField =
+            { name = fieldName |> Maybe.withDefault ""
+            , value = Just exactValue --justViewField.value
+            , kind = justViewField.kind
+            }
+    in
+    case rawField.kind of
+        ( _, properties ) ->
+            Html.button
+                (attrs
+                    ++ toHtmlProperties properties
+                    ++ [ Attr.value (rawField.value |> Maybe.withDefault "")
+                       , Attr.name rawField.name
+                       ]
+                )
+                children
+
+
+{-| Gives you a submit button that will submit the form with a specific value for the given Field.
+-}
+valueButtonStyled :
+    String
+    -> List (Html.Styled.Attribute msg)
+    -> List (Html.Styled.Html msg)
+    -> Form.Validation.Field error parsed kind
+    -> Html.Styled.Html msg
+valueButtonStyled exactValue attrs children (Validation viewField fieldName _) =
+    let
+        justViewField : ViewField kind
+        justViewField =
+            expectViewField viewField
+
+        rawField : { name : String, value : Maybe String, kind : ( kind, List ( String, Encode.Value ) ) }
+        rawField =
+            { name = fieldName |> Maybe.withDefault ""
+            , value = Just exactValue
+            , kind = justViewField.kind
+            }
+    in
+    case rawField.kind of
+        ( _, properties ) ->
+            Html.Styled.button
+                (attrs
+                    ++ (toHtmlProperties properties |> List.map StyledAttr.fromUnstyled)
+                    ++ ([ Attr.value (rawField.value |> Maybe.withDefault "")
+                        , Attr.name rawField.name
+                        ]
+                            |> List.map StyledAttr.fromUnstyled
+                       )
+                )
+                children
+
+
 {-| -}
 input :
     List (Html.Attribute msg)
@@ -122,15 +190,21 @@ input attrs (Validation viewField fieldName _) =
             }
     in
     case rawField.kind of
-        ( Input Textarea, properties ) ->
+        ( Input (Textarea { rows, cols }), properties ) ->
             Html.textarea
                 (attrs
                     ++ toHtmlProperties properties
-                    ++ [ Attr.value (rawField.value |> Maybe.withDefault "")
-                       , Attr.name rawField.name
+                    ++ ([ rows |> Maybe.map Attr.rows
+                        , cols |> Maybe.map Attr.cols
+                        ]
+                            |> List.filterMap identity
+                       )
+                    ++ [ Attr.name rawField.name
                        ]
                 )
-                []
+                [ -- textarea does not support the `value` attribute, but instead uses inner text for its form value
+                  Html.text (rawField.value |> Maybe.withDefault "")
+                ]
 
         ( Input inputType, properties ) ->
             Html.input
@@ -170,17 +244,23 @@ inputStyled attrs (Validation viewField fieldName _) =
             }
     in
     case rawField.kind of
-        ( Input Textarea, properties ) ->
+        ( Input (Textarea { rows, cols }), properties ) ->
             Html.Styled.textarea
                 (attrs
                     ++ (toHtmlProperties properties |> List.map StyledAttr.fromUnstyled)
-                    ++ ([ Attr.value (rawField.value |> Maybe.withDefault "")
-                        , Attr.name rawField.name
+                    ++ ([ rows |> Maybe.map StyledAttr.rows
+                        , cols |> Maybe.map StyledAttr.cols
+                        ]
+                            |> List.filterMap identity
+                       )
+                    ++ ([ Attr.name rawField.name
                         ]
                             |> List.map StyledAttr.fromUnstyled
                        )
                 )
-                []
+                [ -- textarea does not support the `value` attribute, but instead uses inner text for its form value
+                  Html.Styled.text (rawField.value |> Maybe.withDefault "")
+                ]
 
         ( Input inputType, properties ) ->
             Html.Styled.input