Rewritten doubterPlugin README.md

Author: smikhalevski

README.md

@@ -462,12 +462,12 @@ you can use `form` tags as you did before, but read input values from the `Field
 
 ```tsx
 const App = () => {
-  const rootField = useField({ foo: 'bar' });
+  const rootField = useField({ bar: 'foo' });
 
   const handleSubmit = (event: SyntheticEvent): void => {
     event.preventDefault();
 
-    // Acquire the current value of the root field
+    // The form value to submit
     const value = rootField.getValue();
   };
 
@@ -498,78 +498,30 @@ You can always [create a plugin](#plugins) that would enhance the `Field` with c
 
 # Validation
 
-Roqueform isn't tied to any validation library. You can use an existing plugin, or write your own plugin to extend
-Roqueform with validation provided by an arbitrary library.
+Roqueform isn't tied to any validation library. You can use an existing plugin, or write your own to extend Roqueform
+with validation provided by an arbitrary library.
 
-For example, let's consider a [@roqueform/doubter-plugin](./packages/doubter-plugin) that enables a no-hassle validation
-using [Doubter](https://github.com/smikhalevski/doubter).
+Currently, the only available validation plugin [@roqueform/doubter-plugin](./packages/doubter-plugin) which enables
+uses [Doubter](https://github.com/smikhalevski/doubter) under-the-hood.
 
 ```ts
-import { useErrors, useField } from 'roqueform';
+import { useField } from 'roqueform';
 import { doubterPlugin } from '@roqueform/doubter-plugin';
 import * as d from 'doubter';
 
-const fieldType = d.object({
+const valueType = d.object({
   bar: d.string().min(5)
 });
 
-const field = useField({ bar: 'qux' }, doubterPlugin(fieldType));
-```
-
-The `field` value type is inferred from the `fieldType`.
+const rootField = useField({ bar: 'qux' }, doubterPlugin(valueType));
 
-Plugin enhances all fields with `validate` method that triggers the validation:
+rootField.validate();
 
-```ts
-field.validate();
-
-field.at('bar').getIssue()?.message
-// → 'Must have the minimum length of 5'
+rootField.at('bar').getIssue();
+// → { message: 'Must have the minimum length of 5', … }
 ```
 
-You can manually set and clear field errors:
-
-```ts
-field.at('bar').setIssue({ message: 'Oh, snap!' });
-
-field.at('bar').clearIssue();
-```
-
-This comes in handy when you receive an error after a backend validation and want to associate it with a particular
-field.
-
-```tsx
-const handleSubmit = (event: SyntheticEvent) => {
-  field.validate();
-
-  if (field.isInvalid()) {
-    event.preventDefault();
-  }
-};
-
-<form onSubmit={handleSubmit}>
-  <Field field={field.at('bar')}>
-    {barField => (
-      <>
-        <input
-          name="bar"
-          value={barField.getValue()}
-          onChange={event => {
-            barField.dispatchValue(event.target.value);
-          }}
-          aria-invalid={barField.isInvalid()}
-        />
-
-        {barField.getIssue()?.message}
-      </>
-    )}
-  </Field>
-
-  <button type="submit">
-    {'Submit'}
-  </button>
-</form>
-```
+[Plugin usage details can be found here.](./packages/doubter-plugin)
 
 # Accessors
 

packages/doubter-plugin/README.md

@@ -0,0 +1,141 @@
+# Doubter plugin for Roqueform
+
+Plugin that enhances [Roqueform](https://github.com/smikhalevski/roqueform) fields with validation methods powered by
+[Doubter](https://github.com/smikhalevski/doubter).
+
+```sh
+npm install --save-prod @roqueform/doubter-plugin
+```
+
+# Usage example
+
+🔥 [**Try it on CodeSandbox**](https://codesandbox.io/s/roqueform-doubter-plugin-example-74hkgw)
+
+```tsx
+import * as d from 'doubter';
+import { useField } from 'roqueform';
+import { doubterPlugin } from '@roqueform/doubter-plugin';
+
+const valueType = d.object({
+  bar: d.string().min(1),
+});
+
+export const App = () => {
+  const rootField = useField({ bar: '' }, doubterPlugin(valueType));
+
+  const handleSubmit = (event: SyntheticEvent): void => {
+    event.preventDefault();
+
+    // Trigger validation
+    rootField.validate();
+
+    if (rootField.isInvalid()) {
+      // Isses are associated with fields automatically
+      return;
+    }
+
+    // The form value to submit
+    const value = rootField.getValue();
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+
+      <Field field={rootField.at('bar')}>
+        {barField => (
+          <>
+            <input
+              value={barField.getValue()}
+              onChange={event => {
+                barField.dispatchValue(event.target.value);
+              }}
+              aria-invalid={barField.isInvalid()}
+            />
+
+            {barField.getIssue()?.message}
+          </>
+        )}
+      </Field>
+
+      <button type="submit">
+        {'Submit'}
+      </button>
+
+    </form>
+  );
+};
+```
+
+# Validating fields
+
+First, you should first define your runtime data types using [Doubter](https://github.com/smikhalevski/doubter) DSL
+methods.
+
+```ts
+import * as d from 'doubter';
+
+const valueType = d.object({
+  bar: d.string().min(5)
+});
+// → Type<{ bar: string }>
+```
+
+Then you can create a new field and enhance it with validation methods:
+
+```ts
+import { useField } from 'roqueform';
+import { doubterPlugin } from '@roqueform/doubter-plugin';
+
+const rootField = useField({ bar: 'qux' }, doubterPlugin(valueType));
+```
+
+Type of the field value is inferred from the provided runtime type definition, so everything remains statically checked
+even there's no TypeScript types were explicitly specified.
+
+When you call the `validate` method it triggers validation of the field and all of its derived fields. So if you call
+`validate` on the derived field, it won't validate the parent field:
+
+```ts
+// rootField is not validated here! 
+rootField.at('bar').validate();
+```
+
+So it's safe to trigger validation of a single text field on every keystroke, since it does't have an overhead of
+validating the whole form object. On the other hand, you can validate the whole form by calling validate on the root
+field.
+
+To detect whether the field, or any of its derived fields contain an issue:
+
+```ts
+rootField.isInvalid();
+// → true
+```
+
+To retrieve an issue associated with a particular field:
+
+```ts
+rootField.at('bar').getIssue();
+// → { message: 'Must have the minimum length of 5', … }
+```
+
+# Manage issues manually
+
+You can manually associate an issue with the field:
+
+```ts
+rootField.at('bar').setIssue({ message: 'Oh, snap!' });
+```
+
+This allows you to mix client-side and server-side validation using the same mechanism.
+
+To delete an issue for the particular field:
+
+```ts
+rootField.at('bar').deleteIssue();
+```
+
+Sometimes it is required to clear issues of the field itself and all of its derived fields:
+
+```ts
+rootField.clearIssues();
+```

packages/doubter-plugin/src/test/doubterPlugin.test.tsx

@@ -1,6 +1,6 @@
 import * as d from 'doubter';
 import { doubterPlugin } from '../main';
-import { createField, objectAccessor } from 'roqueform/src/main';
+import { createField, objectAccessor } from 'roqueform';
 
 describe('doubterPlugin', () => {
   const fooType = d.object({