Expose more modules and improve documentation.

Author: niho

README.md

@@ -16,6 +16,7 @@ Generate validating forms from JSON schemas.
 
 1. The way form fields are generated and presented is very opinionated and thus not always suitable for general case usage. This library is intended to be used for cases where you have control over how the schema is structured.
 2. The HTML that the library outputs is intended to be used together with [Bootstrap](https://getbootstrap.com/) to style the form. It can of course be used without Bootstrap but some field types might need some custom styling to look ok.
+3. There is currently no support for linked schemas using `$ref`.
 
 
 ## Example usage

elm.json

@@ -6,8 +6,10 @@
     "version": "1.0.0",
     "exposed-modules": [
       "Json.Schema.Form",
+      "Json.Schema.Form.Encode",
       "Json.Schema.Form.Error",
-      "Json.Schema.Form.Encode"
+      "Json.Schema.Form.Format",
+      "Json.Schema.Form.Value"
     ],
     "elm-version": "0.19.0 <= v < 0.20.0",
     "dependencies": {

src/Json/Schema/Form.elm

@@ -2,6 +2,7 @@ module Json.Schema.Form exposing
     ( Options, State, Msg
     , init, update
     , view, onSubmit
+    , getOutput
     )
 
 {-| Generate validating forms from JSON schemas.
@@ -63,7 +64,7 @@ type alias Msg =
     F.Msg
 
 
-{-| Initialize a form state with options and a schema.
+{-| Initialize a form state with options and a schema. Use [json-tools/json-schema](https://package.elm-lang.org/packages/json-tools/json-schema/1.0.2/) to parse or build a schema.
 -}
 init : Options -> Schema -> State
 init options schema =
@@ -96,10 +97,28 @@ view state =
 
     form [ Json.Schema.Form.onSubmit ]
         [ Json.Schema.Form.view state
-        , button [] [ test "Submit" ]
+        , button [] [ text "Submit" ]
         ]
 
 -}
 onSubmit : Attribute Msg
 onSubmit =
     Html.Events.onSubmit F.Submit
+
+
+{-| Get the output value of the form if it validates.
+
+    case Json.Schema.Form.getOutput state of
+        Just value ->
+            -- The `value` is a tree of all the fields in the form (see the
+            -- `Json.Schema.Form.Value` module).
+            -- Use the `Json.Schema.Form.Encode.encode` function to turn
+            -- it into a JSON value.
+        Nothing ->
+            -- If any field in the form is not valid `getOutput` will
+            -- return `Nothing`.
+
+-}
+getOutput : State -> Maybe Value
+getOutput state =
+    F.getOutput state.form

src/Json/Schema/Form/Fields.elm

@@ -21,7 +21,7 @@ import Json.Schema.Definitions
         , blankSchema
         )
 import Json.Schema.Form.Error exposing (ErrorValue, Errors)
-import Json.Schema.Form.Format exposing (Formats, getFormat)
+import Json.Schema.Form.Format exposing (CustomFormat, Formats)
 import Json.Schema.Form.Validation exposing (validation)
 import Json.Schema.Form.Value exposing (Value(..))
 
@@ -485,3 +485,8 @@ conditional f conditions =
                 Nothing
     in
     Html.Keyed.node "div" [] <| List.filterMap cond conditions
+
+
+getFormat : String -> Formats -> Maybe CustomFormat
+getFormat format formats =
+    formats |> Dict.fromList |> Dict.get format

src/Json/Schema/Form/Format.elm

@@ -1,20 +1,28 @@
-module Json.Schema.Form.Format exposing (CustomFormat, Formats, getFormat)
+module Json.Schema.Form.Format exposing (Formats, CustomFormat)
+
+{-| In a JSON schema the `format` keyword has a number of pre-defined formats (`date`, `email`, etc.) but can also be any custom format (see [7. Semantic Validation with "format"](https://json-schema.org/latest/json-schema-validation.html#rfc.section.7)). If you simply need a to match a field against a regular expression you should use the `pattern` keyword instead. Custom formats are intended for annotation and more complex validation that is not possible to accomplish with a regex.
+
+@docs Formats, CustomFormat
+
+-}
 
-import Dict
 import Form.Validate exposing (Validation)
 import Json.Schema.Form.Error exposing (ErrorValue)
 
 
+{-| A list of custom formats with a format identifier for each.
+-}
 type alias Formats =
     List ( String, CustomFormat )
 
 
+{-| A custom format has a title and a validation function that validates the string value of the field according to the rules of the format.
+
+  - `title` - A user readable description of the format that is used to annotate the field.
+  - `validation` - A validation function (see [etaque/elm-form](https://package.elm-lang.org/packages/etaque/elm-form/4.0.0/Form-Validate) for details on how to write a validation function).
+
+-}
 type alias CustomFormat =
     { title : Maybe String
     , validation : String -> Validation ErrorValue String
     }
-
-
-getFormat : String -> Formats -> Maybe CustomFormat
-getFormat format formats =
-    formats |> Dict.fromList |> Dict.get format

src/Json/Schema/Form/Validation.elm

@@ -18,7 +18,7 @@ import Json.Schema.Definitions
         )
 import Json.Schema.Form.Encode
 import Json.Schema.Form.Error exposing (ErrorValue(..))
-import Json.Schema.Form.Format exposing (Formats)
+import Json.Schema.Form.Format exposing (CustomFormat, Formats)
 import Json.Schema.Form.Regex
 import Json.Schema.Form.Value exposing (Value(..))
 import Regex
@@ -422,3 +422,8 @@ isType types schema_ =
 lazy : (() -> Validation e o) -> Validation e o
 lazy thunk =
     andThen thunk (succeed ())
+
+
+getFormat : String -> Formats -> Maybe CustomFormat
+getFormat format formats =
+    formats |> Dict.fromList |> Dict.get format

src/Json/Schema/Form/Value.elm

@@ -1,6 +1,14 @@
 module Json.Schema.Form.Value exposing (Value(..))
 
+{-| When a form is valid the output is a tree of `Value` items that represent the type and value of each field or group/list of fields in the form.
 
+@docs Value
+
+-}
+
+
+{-| A form value.
+-}
 type Value
     = IntValue Int
     | FloatValue Float

tests/ValidationTest.elm

@@ -4,14 +4,14 @@ import Expect exposing (Expectation)
 import Form.Field exposing (..)
 import Json.Schema.Builder exposing (..)
 import Json.Schema.Definitions exposing (..)
-import Schema.Validation exposing (validation)
-import Schema.Value exposing (Value(..))
+import Json.Schema.Form.Validation exposing (validation)
+import Json.Schema.Form.Value exposing (Value(..))
 import Test exposing (..)
 
 
 suite : Test
 suite =
-    describe "Schema.Validation"
+    describe "Json.Schema.Form.Validation"
         [ describe "validation"
             [ describe "with a blank schema"
                 [ describe "any type of input"