Merge pull request #6 from pstrh/#1_improve_documentation

#1 improve documentation

Author: pstrh

.gitignore

@@ -8,3 +8,4 @@ node_modules
 .rts2_cache_umd
 dist
 /HOW_TO_RELEASE.md
+*.iml

.npmignore

@@ -2,4 +2,5 @@ tsconfig.json
 src
 test
 .idea
-examples
+examples
+*.iml

README.md

@@ -1,50 +1,215 @@
 # react-constraint-validation
-**React Constraint Validation** is a small library that provides validation props for React components similar to the HTML Constraint Validation attributes.
+**React Constraint Validation** is a small library that aims to provide validation props for React components similar to the HTML Constraint Validation attributes.
 
 ### Features
 
-- HTML Constraint Validation attributes for React components (without refs)
+- HTML Constraint Validation attributes (like required, min, maxLength) for React components (without refs)
 - Easily extensible with own validators
 - Localisation of error messages and interpolation
 - Written in Typescript 
-- Perfect fit to Formik
+- To be used with Formik
 
 ### Use case
 
 You don't want to declare field-level validation like this with your form framework:
 
     <Field name="username" validate={[required, minLength2, maxLength20]} /> 
 
-Instead you want to write:
+Instead you want to create Fields that directly support these validations with respective props:
 
     <Field name="username" required minLength={2} maxLength={20} />    
 
 ### Form framework needed
 
-**React Constraint Validation** provides a HOC and some standard validators. The HOC can be used to enhance form components of your preferred form framework e.g. Formik.
+**React Constraint Validation** provides a experimental HOC and some standard validators. The HOC can be used to enhance form components of your preferred form framework e.g. Formik.
 
-Limitation: Actually it currently only supports Formik ;) Support for other form frameworks like Redux-Form is planned with one of the next releases.   
+Limitation: Actually it currently only supports Formik ;) Support for other form frameworks like React Final Form is planned with one of the next releases.   
 
 ### Getting started
 
 Add react-constraint-validation:
 
-    $ npm install react-constraint-validation --save
+    npm i react-constraint-validation # or yarn add react-constraint-validation
 
 Enhance a Formik field component with validation (should be done once per application):
 
-    const NumberField = withValidator({required, min, max },{number})(Field);
+    import {withValidator, required, min, max, number, minLength, maxLength, email} from "react-constraint-validation";
+    
     const TextField = withValidator({required, minLength, maxLength})(Field);
-    const EmailField = withValidator({required},{email})(Field);    
+    const NumberField = withValidator({required, min, max}, {number})(Field);    
+    const EmailField = withValidator({required}, {email})(Field);    
 
 Use your enhanced components in your form:
 
     <TextField name="username" required minLength={2} maxLength={20} />
+    <NumberField name="age" required min={20} max={120} />
+    <EmailField name="email" required />
 
 A complete example can be found in [examples/formik](https://github.com/pstrh/react-constraint-validation/blob/master/examples/formik/src/components/FieldLevelValidation.tsx).
 
-### WIP
+### Validators
+
+**React Constraint Validation** provides the following validations out-of-the-box:
+* `required` checks that the given value is not null, undefined or an empty string
+* `min` checks that the given number value is equal or greater than the given lower bound
+* `max` checks that the given value is smaller than or equal to the given upper bound 
+* `minLength` checks that the length of the given string value is equal or greater than the given length
+* `maxLength` checks that the length of the given string value is smaller or equal to the given length
+* `pattern` checks if the given value matches a RegEx pattern
+* `number` checks if the given value is a number
+* `email` checks if the given value is a valid email (via a RegEx pattern)
+
+### The withValidator HOC (experimental)
+
+Fields wrapped with the withValidator HOC can be configured with two kinds of validators:
+- (optional) validators that can be activated via field props
+- default validators that should be always executed as they are inherent to the specific field type
+
+Take a look at the examples:
+
+    const TextField = withValidator({required, minLength, maxLength})(Field);
+    const NumberField = withValidator({required, min, max}, {number})(Field); 
+    
+    <TextField name="name" required />
+    <NumberField name="amount" required min={100} />
+    
+NumberField has the optional validations `required`, `min` and `max`. These validations can (but don't have to) be set via field props. 
+Whereas the `number` validation is defined as default validation and is always applied.     
+Textfield on the other hand doesn't enforce a default validation. Here only the optional validations `required`, 
+`minLength` and `maxLength` are configured on the field.
+
+### Default error messages
+
+The following object defines the default error messages:
+
+```
+const defaultMessages: Messages = {
+    "required": "{name} is required",
+    "min": "{name} must be greater than {minValue}",
+    "max": "{name} must be less than {maxValue}",
+    "minLength": "{name} must have at least {minLength} characters",
+    "maxLength": "{name} must have less than {maxLength} characters",
+    "pattern": "{name} does not match the pattern {pattern}",
+    "number": "{name} must be a number",
+    "email": "{name} is not a valid email"
+};
+```
+
+The placeholders `{name}`, `{minValue}`, `{maxValue}` and so on are replaced if the actual error message is created. `name` is the name of the form field. The other placeholders like `{minValue}` provide access to the respective validation constraints.
+
+### Custom error messages
+
+If you want to override the default error messages, just initialize the Validator with a custom error message object as shown in the following example:
+
+```
+import * as Validator from "react-constraint-validation";
+
+const customErrorMessages = {    
+    "required": "This field is required", // override without placeholder
+    "number": "Enter only numbers in {name}"
+};
+
+Validator.init(customErrorMessages);
+```
+
+In the `init` method the custom error messages are merged with the default messages. As you can see in the `required` example, it's not necessary to use the placeholders of the default error 
+messages. Usage of the placeholders in the custom error messages is optional. 
+
+If you want to create custom error messages for a specific field, you can just add an additional attribute following
+ the pattern `required.<name>` (where name is the name attribute of the field).
+ 
+ ```
+ import * as Validator from "react-constraint-validation";
+ 
+ const customErrorMessages = {    
+     "required": "This field is required", // Error message for all other fields
+     "required.firstName": "First name is required", // Error message for field 'firstName'
+     "required.lastName": "Last name is required", // Error message for field 'lastName'
+     "number": "Enter only numbers in {name}"
+ };
+ 
+ Validator.init(customErrorMessages);
+ ```
+
+E.g. for the required validation on the field 'firstName' react-constraint-validation will first check if the attribute 
+`required.firstname` is contained in the errorMessage object. If `required.firstname` is not present it will 
+retreive the error message configured via the `required` attribute.  
+
+### Localisation
+
+Localisation of the error messages can be done in the same way as you customize the default error messages. Just initialize the Validator with an object of localized error messages as shown below:
+
+```
+import * as Validator from "react-constraint-validation";
+
+// should be content of your localisation file
+const germanMessages: Messages = {
+    "required": "Bitte fülllen Sie dieses Feld",
+    "min": "Der Wert des Feldes muss größer als {minValue} sein",
+    "max": "Der Wert des Feldes darf nicht größer sein als {maxValue}",
+    "minLength": "Bitte geben Sie mindestens {minLength} Zeichen ein",
+    "maxLength": "Bitte geben Sie nicht mehr als {maxLength} Zeichen ein",
+    "pattern": "Die Eingabe hat ein ungültiges Format",
+    "number": "Hier sind nur Zahlen erlaubt",
+    "email": "Die Email-Adresse ist nicht korrekt"
+};
+
+// to be called if user locale changes
+Validator.init(germanMessages);
+```
+
+### Create custom validators
+
+If needed, you can create additional custom validators and configured them on your field via the withValidator HOC.
+
+The following example illustrates how to create a custom validator. As a sample use case we create an "UpperCaseValidator".
+
+```
+import { init, required, resolveErrorMessage, withValidator } from "react-constraint-validation";
+
+// add new error message with key = "upperCase"
+init({
+    "upperCase": "Given text must be upper case only"
+});
+
+// create validator 
+const upperCase = (name: string | undefined, value: string): string | undefined => {
+    console.log("upperCase");
+    if (value && value.toUpperCase() !== value) {
+        // helper method to resolve error message with key = "upperCase"
+        return resolveErrorMessage("upperCase", name, {});
+    } else {
+        return undefined;
+    }
+}
+
+// bind validator to field
+const TextField = withValidator({required, upperCase})(Field);
+
+// activate upperCase validation in TextField   
+<TextField name="myUpperCaseField" upperCase/>
+```
+
+A custom validator must implement one of the following APIs:
+
+    type ValidationFunction = (name: string | undefined, value:any) => string | undefined;
+    type ValidationFunctionWithParam = (name: string | undefined, value:any, param: any) => string | undefined;
+
+The type `ValidationFunctionWithParam` can be used if the validator takes an argument like `minLenght={5}`. 
+
+### Field-Level vs. Form-Level validation
+
+**React Constraint Validation** is designed to provide standard fields with build-in validation support (EmailField, NumberField and so on). 
+
+Therefore it might be useful if you need to build an application with many form fields or if you provide a component library for a number of different applications. If you only need to implement one or two small forms in your application using react-constraint-validation might be less useful.
+
+Furthermore as this small library is designed to provide standard fields it is solely focused on field-level validation. Cross field or multi field validations is an aspect that depends on the individual form rather than on the single field. It's therefore better done on the form level 
+(unfortunetly there is currently an issue with Formik as it execute form level validation before the field level validation).     
+
+### About
+
+This project is experimental and still work in progress. Feel free to try. Feedback, suggestions and any kind of contribution is welcome. 
 
-This is a new project. The basic functionality is there and can be used.
+### License
 
-Any feedback, suggestions and contributions are welcome. 
+[MIT](./LICENSE)

examples/formik-advanced/.npmignore

@@ -0,0 +1,3 @@
+node_modules
+.cache
+dist

examples/formik-advanced/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+      <meta name="viewport" content="minimum-scale=1, initial-scale=1, width=device-width, shrink-to-fit=no"/>
+    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap" />
+    <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />
+    <title>Playground</title>
+  </head>
+
+  <body>
+    <div id="root"></div>
+    <script src="./src/index.tsx"></script>
+  </body>
+</html>

examples/formik-advanced/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "react-constraint-validation-formik-example",
+  "version": "0.0.1",
+  "description": "Example to show usage with formik",
+  "main": "index.js",
+  "author": "pstrh",
+  "license": "MIT",
+  "scripts": {
+    "start": "parcel index.html",
+    "build": "parcel build index.html"
+  },
+  "dependencies": {
+    "@material-ui/core": "^4.5.1",
+    "formik": "1.5.8",
+    "formik-material-ui": "^0.0.22",
+    "react-app-polyfill": "1.0.0"
+  },
+  "alias": {
+    "react": "../../node_modules/react",
+    "react-dom": "../../node_modules/react-dom/profiling",
+    "scheduler/tracing": "../../node_modules/scheduler/tracing-profiling"
+  },
+  "devDependencies": {
+    "@types/react": "16.8.15",
+    "@types/react-dom": "16.8.4",
+    "parcel": "1.12.3",
+    "typescript": "3.4.5"
+  }
+}

examples/formik-advanced/src/App.tsx

@@ -0,0 +1,71 @@
+import * as React from "react";
+import {AppBar, Typography, Toolbar, Container, Card, CardContent, Button, makeStyles} from "@material-ui/core";
+import {LanguageMenu} from "./components/LanguageMenu";
+import * as Validator from "../../../src";
+import {Messages} from "../../../src";
+import MyForm from "./components/MyForm";
+import {useEffect} from "react";
+
+const useStyles = makeStyles(theme => ({
+    root: {
+        flexGrow: 1,
+    },
+    title: {
+        flexGrow: 1,
+    },
+}));
+
+// German messages needed for this example
+const germanMessages: Messages = {
+    "required": "{name} ist ein Pflichtfeld",
+    "min": "{name} muss größer sein als {minValue}",
+    "max": "{name} muss kleiner sein als {maxValue}",
+    "minLength": "{name} muss mindestens {minLength} Zeichen haben",
+    "maxLength": "{name} darf höchstens {maxLength} Zeichen haben",
+    "number": "{name} muss eine Zahl sein",
+    "email": "{name} ist keine gültige Email-Adresse",
+    "upperCase": "Nur Großbuchstaben erlaubt"
+};
+
+const customMessages: Messages = {
+    "upperCase": "Only upper case please"
+}
+
+const App = () => {
+    const [locale, setLocale] = React.useState<string>("en");
+    const classes = useStyles();
+
+    useEffect(() => {
+        Validator.init(customMessages);
+    }, [])
+
+    const handleLocaleChange = (locale: string) => {
+        setLocale(locale)
+        if (locale === "de") {
+            Validator.init(germanMessages);
+        } else {
+            // reset
+            Validator.init(customMessages);
+        }
+    };
+
+    return (
+        <Container className={classes.root} maxWidth="sm">
+            <AppBar position="static">
+                <Toolbar>
+                    <Typography className={classes.title}>
+                        Example
+                    </Typography>
+                    <LanguageMenu activeLocale={locale} onLocaleChange={handleLocaleChange}/>
+                </Toolbar>
+            </AppBar>
+            <Card>
+                <CardContent>
+                    <MyForm key={locale}/>
+                </CardContent>
+            </Card>
+        </Container>
+    );
+};
+
+export default App;