Osci-react-form NPM

key features

write JSX in the react containment style
automatic dependency injection on values and event handlers
instictive validation interfaces

npm

npm install --save-dev osci-react-form

a basic example

import React, { Component } from "react";
import Form, { enhance, Input } from "osci-react-form";

export default class SampleForm extends Component {
  constructor(props) {
    super(props);

    this.state = {
      values: {},
      config: {
        asyncValidateOnBlur: true,
        asyncValidateOnInit: true,
        touchNonEmptyOnInit: true,
        fieldsToNormalize: [],
        normailzeTest: /^$/
      }
    };
  }

  render() {
    return (
      <Form scope={this} onSubmit={this.handleSubmit}>
        <Input name="username" />
        <Input name="password" type="password" />
        <button type="submit">Sign in</button>
        <button type="reset">reset</button>
      </Form>
    );
  }
}

scope attribute

The attribute scope is the client that has the state of Form.
If it is not defined, it will be the instance of Form itself.

state control methods

You can execute enhance(scope) to enable the state control methods.
This method should be executed before any execution of the methods.
scope can be either an instance or a class. (not plain functions. React plain functions cannot have this.)
It is trivial that the scope attribute and the scope argument should be the same.

fields definition

Form regards components with names as fields.

method caveats

If a method modifies this.state or reads it not in the 'render' method frame, put the previous state as its argument,

this.setState(prev => {
  this.setValue("username", "pororo", prev);
  return true;
});

else just use the mothod directly.

this.isValid("username");

If you implemented React.Component abstract methods like getSnapShotBeforeUpdate, you have to set the state in the immutable way. (frankly speaking...i have not tested this case yet)

this.setState(prev => {
  this.setValue("username", "pororo", prev);
  return { values: this.getCopy(prev.values) };
});

define validators

the custom validator interface

validator : String || { name : String, regex : RegExp || api : function, async : boolean [Optional], message : String [Optional] }

client definition

<input validators={[ validator1, validator2, ...]} ... />

built-in definition

<input name="confirm" match="password" ... />

the list of the built-in validators
- type="email"
- required
- match="anyNameOfField"
- notMatch="anyNameOfField"
- pattern={/.*/}
- assertTrue={anyCustomValidator}
- assertFalse={anyCustomValidator}
ordering built-in validators with strings

<Input validators={[ 'required', validator1, 'email', 'pattern', validator2, 'match', 'assertFalse', ...]} pattern={/(1|2)/} match="password" ...built-in-validators />

validation scoping

You can avoid each component having the same validator objects and their value caches for the same validation functionality.

<ul>
  {arr.map((v, i) =>
    <Input key={i.toString()}
           validators={...validators}
           validationScope="serialNumber" />
  )}
</ul>
<Input validators={...validators} validationScope="serialNumber" />

validator caveats
- Once validators are registered, you cannot change them.
- api mothods should return a promise that returns a boolean.
- The required built-in validator always goes first.

methods that reads `this.state`

'getValue(name : String, prev : Object Optional) : String'
'isTouched(name : String, prev : Object Optional) : Boolean'
'syncValidate(name : String, prev : Object Optional, value : Object Optional) : String || null'
'syncValidateFull(name : String, prev : Object Optional, value : Object Optional) : Array'
'isSyncValid(name : String, prev : Object Optional) : Boolean'
'getSyncValidator(name : String, prev : Object Optional) : Array'
- no Validator class yet
'getAsyncStatus(name : String, prev : Object Optional) : Object { asyncName1 : 'processing' || 'resolved' || 'rejected', asyncName2 : ... } || null'
'getFieldNames(prev : Object Optional) : Array'
'isAsyncValidating(name : String Optional, prev : Object Optional) : Boolean'
'isAsyncRejected(name : String Optional, prev : Object Optional) : Boolean'
'getAsyncErrors(name : String, prev : Object Optional) : Object { asyncName1 : 'message or name', asyncName2 : ... } || null'
'getAsyncIdleFields(name : String, prev : Object Optional) : Array'
'getProcessingPromises(prev : Object Optional) : Array'

methods that modifies `this.state`

'setValue(name : String, value : any, prev : Object) : Boolean'
'deleteValue(name : String, prev : Object) : true'
'touch(name : String, prev : Object) : Boolean'
'touchAll(name : String, prev : Object) : Boolean'
'untouch(name : String, prev : Object) : true'
'asyncValidate(name : String, prev : Object, value : Object Optional) : Promise<{asyncName : String, message : String, value : Object, result : Boolean}>'
'normalize(prev : Object, names : Array Optional) : undefined'
- cleans up empty strings for the names in the second argument or field names defined in the configuration of 'fieldsToNormalize'
- this method is for dynamic fields that are not assigned any values to.

plain methods

'getCopy(original : Object) : Object'
- deeply copy all properties

submit interface

<Form
  onSubmit={this.onSubmit}
  onSuccess={this.onSuccess}
  onFailure={this.onFailure}
/>

Form attributes could have onSubmit, onSuccess and onFailure.
onSubmit is supposed to return a promise. If you cannot do so in certain cases like bcrypt, you have to implement this.setState({submitting : false}) manually.
The inner source code of submit handling is below

submit() {
  const { scope } = this;
  const body = scope.getCopy(scope.state.values);
  const submitAction = this.props.onSubmit(body);
  if (submitAction instanceof Promise) {
    submitAction
      .then(
        (!scope.isUnmounted && this.props.onSuccess) || (result => result),
        (!scope.isUnmounted && this.props.onFailure) || (result => result),
      )
      .then(this.handleAfterSubmitCompletion);
  }
}

control the unmounted component

You can put the code below to avoid the unmounted component error with setState.

if (scope.isUnmounted) {
  // scope.setState({ any });
}

the sample page

http://osci-react-form.surge.sh/

test the sample code

git clone git@github.com:OpenSourceConsulting/osci-react-form.git
cd osci-react-form
npm install
npm start

update logs

2018/5/15 update logs have been refreshed.

issues

eager
- test React.Component abstract methods with the state control methods
- asyncValidateOnChange, asyncValidateOnChangeForNonText, asyncValidateOnBlurForNonText, suppressAutoDenpency
lazy
- uncontrolled component 디자인 구상, ref? no? ex) type="file"
- html5 의 모든 스펙을 구현해야한다. (range, textarea, contenteditable, submit action async ...)
- old browser, study of xss cases
- old browser, onSubmit setState promise event loop hole 학습 및 테스트, 최신브라우져는 테스트 완료
- customizing 혹은 logging 을 위해 다양한 hook 을 제공해야한다. promise 의 대부분 stack 에서 logging 할 수 있도록 할 것이다.
extra
- componentDidCatch 사용성 테스트, 좋은 인터페이스인가
- dev logging, dev minifying 구현
- chrome dev tool perfomance test