docs: general improvements

Author: anabastos

docs/assets/schema.png

@@ -5,9 +5,9 @@ title: Basic usage
 
 A basic usage of ReForm looks like this:
 
-First, create a lenses module that will be passed as a param to the ReFormNext functor:
+First, create a lenses module that will be passed as a param to the ReForm functor:
 
-```reason
+```ocaml
 module StateLenses = [%lenses
   type state = {
     description: string,
@@ -18,112 +18,71 @@ module StateLenses = [%lenses
 ```
 
 Now you can generate the actual form container component:
-```reason
-module PostAddForm = ReFormNext.Make(StateLenses);
+```ocaml
+module PostAddForm = ReForm.Make(StateLenses);
 ```
 
 After creating the container module, you can use it as a React component:
 
-```reason
+```ocaml
 [@react.component]
 let make = () => {
-  let {state, submit, getFieldState, handleChange}: PostAddForm.api =
+  let reform =
     PostAddForm.use(
+      ~validationStrategy=OnDemand,
       ~schema={
         PostAddForm.Validation.Schema([|
-          Custom(
-            Title,
-            values =>
-              Js.String.length(values.title) > 20
-                ? Error("Keep it short!") : Valid,
-          ),
+          StringMin(Title, 20),
           StringNonEmpty(Description),
           Custom(
             AcceptTerms,
             values =>
               values.acceptTerms == false
                 ? Error("You must accept all the terms") : Valid,
-          ),
+          )
         |]);
       },
       ~onSubmit=
         ({state}) => {
-          yourLogic()
-
+          Js.log2("title", state.values.description);
+          Js.log2("description", state.values.description);
+          Js.log2("acceptTerms", state.values.description);
           None;
         },
       ~initialState={title: "", description: "", acceptTerms: false},
       (),
     );
 
+  <PostAddForm.Provider value=reform>
     <form
       onSubmit={event => {
         ReactEvent.Synthetic.preventDefault(event);
-        submit();
+        reform.submit();
       }}>
-      <label>
-        <span> {"Title:" |> React.string} </span>
-        <input
-          value={state.values.title}
-          onChange={ReForm.Helpers.handleDomFormChange(handleChange(Title))}
-        />
-        <p>
-          {getFieldState(Field(Title))
-           |> (
-             fun
-             | Error(error) => Some(error)
-             | _ => None
-           )
-           |> Belt.Option.getWithDefault(_, "")
-           |> React.string}
-        </p>
-      </label>
-      <label>
-        <span> {"Description:" |> React.string} </span>
-        <textarea
-          value={state.values.description}
-          rows=4
-          onChange={ReForm.Helpers.handleDomFormChange(
-            handleChange(Description),
-          )}
-        />
-        <p>
-          {getFieldState(Field(Description))
-           |> (
-             fun
-             | Error(error) => Some(error)
-             | _ => None
-           )
-           |> Belt.Option.getWithDefault(_, "")
-           |> React.string}
-        </p>
-      </label>
-      <label>
-        <p>
-          <span> {"Accept terms? " |> React.string} </span>
-          <input
-            type_="checkbox"
-            value={string_of_bool(state.values.acceptTerms)}
-            onChange={event =>
-              ReactEvent.Form.target(event)##checked
-              |> handleChange(AcceptTerms)
-            }
-          />
-        </p>
-        <p>
-          {getFieldState(Field(AcceptTerms))
-           |> (
-             fun
-             | Error(error) => Some(error)
-             | _ => None
-           )
-           |> Belt.Option.getWithDefault(_, "")
-           |> React.string}
-        </p>
-      </label>
-      {state.formState == Submitting
+      <FieldString field=StateLenses.Title label="Title" />
+      <FieldString field=StateLenses.Description label="Description" />
+      <PostAddForm.Field
+        field=StateLenses.AcceptTerms
+        render={({handleChange, error, value}) =>
+          <label>
+            <p>
+              <span> {"Accept terms? " |> React.string} </span>
+              <input
+                type_="checkbox"
+                value={string_of_bool(value)}
+                onChange={event =>
+                  ReactEvent.Form.target(event)##checked |> handleChange
+                }
+              />
+            </p>
+            <p> {error->Belt.Option.getWithDefault("")->React.string} </p>
+          </label>
+        }
+      />
+      {reform.state.formState == Submitting
          ? <p> {React.string("Saving...")} </p>
          : <button type_="submit"> {"Submit" |> React.string} </button>}
     </form>
+  </PostAddForm.Provider>;
 };
 ```

docs/basic_usage.md

@@ -0,0 +1,19 @@
+---
+id: gettingStarted
+title: Getting Started
+---
+
+## What this is and why
+
+Code that deals with strongly typed forms can quickly become walls of repeated text.
+We created ReForm to be both deadly simple and to make forms sound good leveraging ReasonML's powerful typesytem.
+Even the schemas we use are nothing more than constructors built-in in the language itself with a small size footprint.
+
+## Features
+
+- Hook API
+- Schema API
+- Type safe, `handleChange` properly infers the value of the field it is handling
+- Context Provider
+- Field component
+- Validation strategy, OnDemand and OnChange

docs/getting_started.md

@@ -4,24 +4,49 @@ title: Installation
 sidebar_label: Installation
 ---
 
-Add via yarn
+### Pre-requisites
+
+#### BS-Platform
+ In order to start using Reform you need the basic tooling for ReasonML using [Buckescript](https://bucklescript.github.io/en/).
+
+#### React
+Reform is a library for React applications, so we assume that you are already familiar with [React](https://reactjs.org/).
+
+### Instalation and Setup
+
+You’ll need to have [Node 8.16.0 or Node 10.16.0 or later version](https://nodejs.org/en/) on your local development machine (but it’s not required on the server). You can use `nvm` (macOS/Linux) or `nvm-windows` to easily switch Node versions between different projects.
+
+If you want to create a ReasonReact development envinroment you can use the create-react-app to bootstrap a initial project.
+`yarn create react-app my-app --scripts-version reason-scripts`
+`yarn create` is available in [Yarn 0.25+](https://yarnpkg.com/lang/en/)
+
+or
+
+`npx create-react-app <app-name> --scripts-version reason-scripts`
+`npx` comes with npm 5.2+ and higher
+
+It will create a directory called my-app inside the current folder.
+Inside that directory, it will generate the initial project structure.
+
+Now you can install the package Reform to your existing project using yarn or npm:
 ```
 yarn add bs-reform reschema
 ```
-Then add to your bs-dependencies in bsconfig.json
+
+Then add to your `bs-dependencies` in bsconfig.json
 ```
 "bs-dependencies": [
   "bs-reform",
   "reschema"
 ]
 ```
 
-Now add lenses
+Now add lenses, a package to generate GADT lenses for ReasonML.
 ```
 yarn add -D lenses-ppx
 ```
 
-And update your bs-dependencies
+And update your `bs-dependencies`
 ```
 "ppx-flags": [
   "lenses-ppx/ppx"

docs/installation.md

@@ -8,79 +8,79 @@ Validators are type safe and only accept the field of the type they are meant to
 
 ### Email(Lenses.field(string))
 Validates email values
-```reason
+```ocaml
 let schema = ReSchema.Validation([|
   Email(Lenses.Email),
 |]);
 ```
 
 ### StringNonEmpty(Lenses.field(string))
 Requires that the string within is not empty
-```reason
+```ocaml
 let schema = ReSchema.Validation([|
   StringNonEmpty(Lenses.Name),
 |]);
 ```
 
 ### NoValidation(Lenses.field('a))
 Does not apply any validation in the field
-```reason
+```ocaml
 let schema = ReSchema.Validation([|
   NoValidation(Lenses.Age),
 |]);
 ```
 
 ### StringRegExp(Lenses.field(string), string)
 Set a custom RegExp to match the value
-```reason
+```ocaml
 let schema = ReSchema.Validation([|
   StringRegExp(Lenses.Name, "^[a-zA-Z\s]*$"),
 |]);
 ```
 
 ### StringMin(Lenses.field(string), int)
 Set a minimum length for the string
-```reason
+```ocaml
 let schema = ReSchema.Validation([|
   StringMin(Lenses.Name, 3),
 |]);
 ```
 
 ### StringMax(Lenses.field(string), int)
 Set a maximum length for the string
-```reason
+```ocaml
 let schema = ReSchema.Validation([|
   StringMax(Lenses.Name, 20),
 |]);
 ```
 
 ### IntMin(Lenses.field(int), int)
 Set a minumum value for the int
-```reason
+```ocaml
 let schema = ReSchema.Validation([|
   IntMin(Lenses.Age, 21),
 |]);
 ```
 
 ### IntMax(Lenses.field(int), int)
 Set a maximum value for the int
-```reason
+```ocaml
 let schema = ReSchema.Validation([|
   IntMax(Leses.Age, 60),
 |]);
 ```
 
 ### FloatMin(Lenses.field(float), float)
 Set a minimum value for the float
-```reason
+```ocaml
 let schema = ReSchema.Validation([|
   FloatMin(Lenses.Price, 1.0),
 |]);
 ```
 
 ### FloatMax(Lenses.field(float), float)
 Set a maximum value for the float
-```reason
+```ocaml
 let schema = ReSchema.Validation([|
   FloatMax(Lenses.Price, 100.0),
 |]);
@@ -89,3 +89,24 @@ let schema = ReSchema.Validation([|
 ### Custom(Lenses.field('a), Lenses.state => fieldState)
 Useful for when you need to build your own custom logic. 
 You can validate with props your component received - this is why we let you pass the schema as prop and not in the functor - or whatever you need.
+
+In this example the "Title" input must have a length smaller than 20, the "Description" input must not be empty and the "AcceptTerms" must be checked.
+```reason
+PostAddForm.Validation.Schema([|
+  Custom(
+    Title,
+    values =>
+      Js.String.length(values.title) > 20
+        ? Error("Keep it short!") : Valid,
+  ),
+  StringNonEmpty(Description),
+  Custom(
+    AcceptTerms,
+    values =>
+      values.acceptTerms == false
+        ? Error("You must accept all the terms") : Valid,
+  ),
+|]);
+```
+
+![Example of Schema Validation](https://github.com/Astrocoders/reform/tree/master/docs/assets/schema.png)

docs/schema.md

@@ -14,6 +14,9 @@
       "doc5": {
         "title": "Fifth Document"
       },
+      "gettingStarted": {
+        "title": "Getting Started"
+      },
       "i18n": {
         "title": "i18n"
       },

website/i18n/en.json

@@ -1,6 +1,6 @@
 {
   "docs": {
-    "Setting up": ["installation"],
+    "Setting up": ["gettingStarted", "installation"],
     "Usage": ["basicUsage"],
     "API": ["schema", "i18n"]
   },