Updated docs

Author: Vlad Balin

README.md

@@ -1,4 +1,4 @@
-![logo](/docs/images/value-link-logo.png)
+![logo](/images/value-link-logo.png)
 
 # Painless React forms, validation, and state management
 
@@ -99,7 +99,7 @@ const $name = this.$at('name');
 const state$ = this.state$();
 ```
 
-Refer to the [databinding examples](/examples/databinding) and the [manual](/docs/databinding.md) for the typical data binding scenarios.
+Refer to the [databinding examples](/examples/databinding) and the [manual](/linked-controls/README.md) for the typical data binding scenarios.
 
 * [/lib](/lib) folder contains ES5 modules prebuilt with ES6 exports suitable for modern build tools like `webpack 2`.
 * [/dist](/dist) folder contains minified UMD ES5 assembly exporting `NestedLink` global valiable.
@@ -118,9 +118,9 @@ You can either use `Link.value` inside to create links dynamically, or extend th
 
 ### Start hacking
 
-![design](/docs/images/valuelinks.jpg)
+![design](/images/valuelinks.jpg)
 
-If you want to play with the examples, fix the bug, or whatever:
+It's a very simple library written with TypeScript, there's no any magic inside (except some scary type annotations). If you want to play with the examples, fix the bug, or whatever:
 
 `yarn` - installs the dependencies.
 
@@ -153,4 +153,4 @@ React Hooks support.
 - `<input {...link.props} />` can be used to bind the link to any of the standard controls expecting `value` and `onChange` props.
 
 ---
-![usedby](/docs/images/usedby.png)
+![usedby](/images/usedby.png)

docs/databinding.md

@@ -0,0 +1,123 @@
+# Linked Controls
+
+Reference implementation of linked form controls. Can be used as a starting boilerplate for
+your own controls with inlined validation errors.
+
+Link can be bound to the any form control consuming `value` and `onChange` props, so linked controls from this package may be used but not really required.
+
+```javascript
+<input {...$value.props} />
+```
+
+However, it's beneficial to create a custom form control wrappers encapsulating your markup patterns for a form layout and validation in order to take a full advantage of the value link.
+
+## Installation
+
+    npm install linked-controls --save-dev
+
+## List of controls
+
+### Text and number form fields 
+
+##### `<Input type="text"/>`, `<TextArea />` 
+
+Wrappers for standard `<input>` and `<textarea>` tags which can be directly bound to the string links.
+
+These wrappers will add `invalid` class to enclosed HTML element if an error is present in the link.
+
+```jsx
+<Input type="text" $value={ $link } />
+<TextArea $value={ $link } />
+```
+
+##### `<NumberInput/>`
+
+A cross-browser implementation of *numeric input* tag. It has following differences compared to `<Input>`:
+
+- Keyboard input which obviously leads to invalid values (e.g. letters) are rejected.
+- Value is being always converted to valid number.
+- There are `integer` and `positive` boolean props controlling input rejection. They can be combined.
+
+`<NumberInput>` validates its value and adds `invalid` class to enclosed input element if it's not a number.
+
+```jsx
+<NumberInput $value={ $link } />
+<NumberInput $value={ $link } integer={ true }/>
+<NumberInput $value={ $link } positive={ true }/>
+```
+
+### Checkboxes
+
+##### `<Input type="checkbox" />`
+
+Wrapper for the standard `<input>`. Directly binds boolean value with `checkedLink` property.
+
+```jsx
+<Input type="text" $checked={ booleanLink } />
+<Input type="text" $checked={ $array.contains( 'option' ) } />
+```
+
+##### `<Checkbox/>`
+
+Internally, it's `<div>` element which toggles `selected` class on click.
+Thus, it can be easily styled.
+
+By default, it has `checkbox` CSS class which can be overridden by passing `className` prop.
+
+It passes through anything else including `children`.
+ 
+```jsx
+<Checkbox $checked={ $boolean } />
+<Checkbox $checked={ $array.contains( 'option' ) } />
+```
+
+### Radio Groups and Select list
+
+##### `<Select/>`
+
+Wrapper for standard `<select/>`. Regular `<option/>` tags must be used. All props are passed through.
+
+```jsx
+<Select $value={ linkToSelectedValue }>
+    <option value="a">A</option>
+    <option value="b">B</option>
+</Select>
+```
+
+##### `<Input type="radio"/>`
+      
+Wrapper for the standard `<input>`. Directly binds boolean value with `$checked` property.
+
+Can be directly bound to the link of any type with `$value` or `$checked` property.
+
+```jsx
+<label>
+    A:
+    <Input type="radio" $value={ $flag } value="a" />
+</label>
+<label>
+    B:
+    <Input type="radio" $checked={ $flag.equals( "b" ) } />
+</label>
+```
+
+##### `<Radio/>`
+
+Internally, it's `<div>` element which always sets `selected` class on click. Thus,
+it can be easily styled. 
+
+By default, it has `radio` CSS class, which can be overridden by passing `className` prop.
+It passes through anything else, including `children`.
+
+It *must* be used in conjunction with `$link.equals( 'value' )` method.
+
+```jsx
+<label>
+    A:
+    <Radio $checked={ $flag.equals( 'a' ) } />
+</label>
+<label>
+    B:
+    <Radio $checked={ $flag.equals( 'b' ) } />
+</label>
+```

docs/images/comparison.png renamed to images/comparison.png

@@ -373,8 +373,8 @@ but returns `undefined` and leads to the proper purely functional update of the
 Evaluate given condition for the current link value, and assign
 given error object to the `link.error` when it fails. There are no restriction on the error object shape and type.
 
-It's possible to assign default error message to the validator function. `tags.jsx` provides `isRequired` and `isEmail`
-generic validator functions as an examples. Excerpt from `tags.jsx`: 
+It's possible to assign default error message to the validator function. `linked-controls` package provides `isRequired` and `isEmail`
+generic validator functions as an examples: 
 
 ```jsx
 export const isRequired = x => x != null && x !== '';
@@ -385,9 +385,8 @@ Checks can be chained. In this case, the first check which fails will leave its
 
 ##### ![var] $link.error : any | void
 
-This link field may be analyzed by custom `<Input />` control to indicate an error (see `tags.jsx` controls and supplied examples).
-
-This mechanics can be used to add ad-hoc validation in `render`. 
+This field is populated by the `link.check` method and must not be assigned manually.
+It should be used by a custom `<Input />` control to display an error (see `linked-controls` and examples).
 
 ```javascript
 // Simple check
@@ -410,6 +409,6 @@ const $num = this.$at( 'num' )
 console.log( $num.error );
 ```
 
-[method]: /docs/images/method.png
-[static]: /docs/images/static.png
-[var]: /docs/images/var.png
+[method]: /images/method.png
+[static]: /images/static.png
+[var]: /images/var.png