iplus / NestedLink

Purely functional two-way data binding and form validation for React

Purely functional data binding for React

Lightweight (6.5K minified) purely functional two-way data binding for the React designed to be used in TypeScript and ES6. While loosely based on the original React Link idea, valuelink develops the concept further providing simple and elegant solutions for handling of the compound state and form validation.

Here's the series of 5-minute tutorials to quickly understand the concept and its rationale:

• The basics of ValueLink design pattern
• Form validation with ValueLinks
• Complex state with ValueLinks

Features

• Declarative binding of the component state elements to form controls.
• Instant "as you type" form validation.
• Easy handling of nested state with objects and arrays.
• 'pure render' optimization friendly.
• Full static type checks with the TypeScript.

Reference implementation of 'linked' UI controls (valuelink/tags):

• Standard tags: <Input /> and <TextArea /> (with validation), <Select />,
• Custom tags: <Radio />, <Checkbox />, <NumberInput />

Examples

• Typical data binding scenarios(source)
• Reusable stateful components(source)
• Complex app state example(source)
• TodoMVC

API Reference

Data Bound Controls Reference

How to

Use in your project

There are no side dependencies except react as peer dependency. Installation:

npm install valuelink --save-dev

Usage:

import React from 'react'
import Link, { LinkedComponent } from 'valuelink'

// If you're using TypeScript or the modern module bundler (like webpack 2) supporting ES6 imports and "tree shaking".
import { Input, TextArea, Select, Radio, Checkbox } from 'valuelink/lib/tags'

// For all other cases there's CommonJS tags module, when previous option won't work.
import { Input, TextArea, Select, Radio, Checkbox } from 'valuelink/tags'

Refer to the databinding examples and the manual for the typical data binding scenarios.

• /lib folder contains ES5 modules prebuilt with ES6 exports suitable for modern build tools like webpack 2.
• /dist folder contains minified UMD ES5 assembly exporting NestedLink global valiable.

Create your own data bound controls

Use tags.jsx or src/tags.tsx as the starting boilerplate for your components. Copy this file over to your project, and start hacking.

Create the binding to the custom state container

ValueLink abstracts data binding from both the particular control and the state container. The default binding implemented in the library is for the standard React state. It's fairly easy to create your own.

You need to subclass React.Component and make your own linkAt and linkAll methods. You can either use Link.value inside to create links dynamically, or extend the Link as it's done in /src/component.ts.

Start hacking

If you want to play with the examples, fix the bug, or whatever:

npm install - installs the dependencies.

npm run build - compiles everything including examples.

1.5 Release Notes

• <input {...link.props} /> can be used to bind the link to any of the standard controls expecting value and onChange props.

---