Added documentation for parse/format & killed normalize (#76)

Author: erikras

README.md

@@ -135,8 +135,10 @@ const MyForm = () => (
     * [`allowNull?: boolean`](#allownull-boolean)
     * [`children?: ((props: FieldRenderProps) => React.Node) | React.Node`](#children-props-fieldrenderprops--reactnode--reactnode)
     * [`component?: React.ComponentType<FieldRenderProps>`](#component-reactcomponenttypefieldrenderprops)
+    * [`format?: ((value: any, name: string) => any) | null`](#format-value-any-name-string--any--null)
     * [`isEqual?: (a: any, b: any) => boolean`](#isequal-a-any-b-any--boolean)
     * [`name: string`](#name-string)
+    * [`parse?: ((value: any, name: string) => any) | null`](#parse-value-any-name-string--any--null)
     * [`render?: (props: FieldRenderProps) => React.Node`](#render-props-fieldrenderprops--reactnode)
     * [`subscription?: FieldSubscription`](#subscription-fieldsubscription)
     * [`validate?: (value: ?any, allValues: Object) => ?any`](#validate-value-any-allvalues-object--any)
@@ -168,7 +170,7 @@ const MyForm = () => (
     * [`decorators?: Decorator[]`](#decorators-decorator)
     * [`initialValues?: Object`](#initialvalues-object)
     * [`mutators?: { [string]: Mutator }`](#mutators--string-mutator-)
-    * [`onSubmit: (values: Object, callback: ?(errors: ?Object) => void) => ?Object | Promise<?Object> | void`](#onsubmit-values-object-callback-errors-object--void--object--promiseobject--void)
+    * [`onSubmit: (values: Object, form: FormApi, callback: ?(errors: ?Object) => void) => ?Object | Promise<?Object> | void`](#onsubmit-values-object-form-formapi-callback-errors-object--void--object--promiseobject--void)
     * [`render?: (props: FormRenderProps) => React.Node`](#render-props-formrenderprops--reactnode)
     * [`subscription?: FormSubscription`](#subscription-formsubscription)
     * [`validate?: (values: Object) => Object | Promise<Object>`](#validate-values-object--object--promiseobject)
@@ -345,6 +347,12 @@ as any non-API props passed into the `<Field/>` component.
 A component that is given [`FieldRenderProps`](#fieldrenderprops) as props, as
 well as any non-API props passed into the `<Field/>` component.
 
+#### `format?: ((value: any, name: string) => any) | null`
+
+A function that takes the value from the form values and the name of the field and formats the value to give to the input. Common use cases include converting javascript `Date` values into a localized date string. Almost always used in conjunction with `parse`.
+
+**Note: If you pass `null` to `format`, it will override the default behavior of converting `undefined` into `''`. If you do this, making sure your inputs are "controlled" is up to you.**
+
 #### `isEqual?: (a: any, b: any) => boolean`
 
 [See the 🏁 Final Form docs on `isEqual`](https://github.com/final-form/final-form#isequal-a-any-b-any--boolean).
@@ -353,6 +361,12 @@ well as any non-API props passed into the `<Field/>` component.
 
 The name of your field.
 
+#### `parse?: ((value: any, name: string) => any) | null`
+
+A function that takes the value from the input and name of the field and converts the value into the value you want stored as this field's value in the form. Common usecases include converting strings into `Number`s or parsing localized dates into actual javascript `Date` objects. Almost always used in conjuction with `format`.
+
+**Note: If you pass `null` to `parse`, it will override the default behavior of converting `''` into `undefined`, thus allowing you to have form values of `''`.**
+
 #### `render?: (props: FieldRenderProps) => React.Node`
 
 A render function that is given [`FieldRenderProps`](#fieldrenderprops), as well

src/Field.js

@@ -31,8 +31,7 @@ export default class Field extends React.PureComponent<Props, State> {
 
   static defaultProps = {
     format: (value: ?any, name: string) => (value === undefined ? '' : value),
-    parse: (value: ?any, name: string) => (value === '' ? undefined : value),
-    normalize: (value: ?any, previousValue: ?any, allValues: Object) => value
+    parse: (value: ?any, name: string) => (value === '' ? undefined : value)
   }
 
   constructor(props: Props, context: ReactContext) {
@@ -76,17 +75,6 @@ export default class Field extends React.PureComponent<Props, State> {
 
   notify = (state: FieldState) => this.setState({ state })
 
-  parseAndNormalize = (value: ?any) => {
-    if (this.props.parse !== null) {
-      value = this.props.parse(value, this.props.name)
-    }
-    return this.props.normalize(
-      value,
-      this.state.state.value,
-      this.context.reactFinalForm.getState().values
-    )
-  }
-
   componentWillReceiveProps(nextProps: Props) {
     const { name, subscription } = nextProps
     if (
@@ -114,9 +102,12 @@ export default class Field extends React.PureComponent<Props, State> {
       this.state.state.blur()
     },
     onChange: (event: SyntheticInputEvent<*> | any) => {
+      const { parse } = this.props
       const value: any =
         event && event.target ? getValue(event, isReactNative) : event
-      this.state.state.change(this.parseAndNormalize(value))
+      this.state.state.change(
+        parse !== null ? parse(value, this.props.name) : value
+      )
     },
     onFocus: (event: ?SyntheticFocusEvent<*>) => {
       this.state.state.focus()
@@ -130,7 +121,6 @@ export default class Field extends React.PureComponent<Props, State> {
       children,
       format,
       parse,
-      normalize,
       isEqual,
       name,
       subscription,

src/Field.test.js

@@ -193,74 +193,6 @@ describe('Field', () => {
     expect(render.mock.calls[2][0].values.foo).toBeUndefined()
   })
 
-  it('should accept parse and normalize function props', () => {
-    const parse = jest.fn((value, name) => `parse.${value}`)
-    const normalize = jest.fn(
-      (value, previousValue, allValues) => `normalize.${value}`
-    )
-    const renderInput = jest.fn(({ input }) => <input {...input} />)
-    const render = jest.fn(() => (
-      <form>
-        <Field
-          name="foo"
-          render={renderInput}
-          parse={parse}
-          normalize={normalize}
-        />
-        <Field name="boo" component="select" />
-      </form>
-    ))
-
-    const dom = TestUtils.renderIntoDocument(
-      <Form
-        onSubmit={onSubmitMock}
-        render={render}
-        initialValues={{ boo: 'abc' }}
-      />
-    )
-
-    expect(render).toHaveBeenCalled()
-    expect(render).toHaveBeenCalledTimes(1)
-    expect(render.mock.calls[0][0].values).toEqual({
-      foo: undefined,
-      boo: 'abc'
-    })
-
-    const input = TestUtils.findRenderedDOMComponentWithTag(dom, 'input')
-
-    TestUtils.Simulate.change(input, { target: { value: 'bar' } })
-
-    expect(render).toHaveBeenCalledTimes(2)
-    expect(render.mock.calls[1][0].values.foo).toBe('normalize.parse.bar')
-
-    expect(parse).toHaveBeenCalled()
-    expect(parse).toHaveBeenCalledTimes(1)
-    expect(parse.mock.calls[0]).toEqual(['bar', 'foo'])
-
-    expect(normalize).toHaveBeenCalled()
-    expect(normalize).toHaveBeenCalledTimes(1)
-    expect(normalize.mock.calls[0]).toEqual([
-      'parse.bar',
-      undefined,
-      { foo: undefined, boo: 'abc' }
-    ])
-
-    TestUtils.Simulate.change(input, { target: { value: 'x' } })
-
-    expect(render).toHaveBeenCalledTimes(3)
-    expect(render.mock.calls[2][0].values.foo).toBe('normalize.parse.x')
-
-    expect(parse).toHaveBeenCalledTimes(2)
-    expect(parse.mock.calls[1]).toEqual(['x', 'foo'])
-
-    expect(normalize).toHaveBeenCalledTimes(2)
-    expect(normalize.mock.calls[1]).toEqual([
-      'parse.x',
-      'normalize.parse.bar',
-      { foo: 'normalize.parse.bar', boo: 'abc' }
-    ])
-  })
-
   it('should accept a null parse prop to preserve empty strings', () => {
     const renderInput = jest.fn(({ input }) => <input {...input} />)
     const render = jest.fn(() => (
@@ -369,7 +301,7 @@ describe('Field', () => {
     expect(select.value).toBe('')
   })
 
-  it("should convert null values to ''", () => {
+  it("should convert undefined values to ''", () => {
     const renderInput = jest.fn(({ input }) => (
       <input {...input} value={input.value} />
     ))

src/ReactFinalForm.test.js

@@ -175,11 +175,10 @@ describe('ReactFinalForm', () => {
 
     const form = TestUtils.findRenderedDOMComponentWithTag(dom, 'form')
     TestUtils.Simulate.submit(form)
-    const formComponent = TestUtils.findRenderedComponentWithType(dom, Form)
 
     expect(onSubmit).toHaveBeenCalled()
     expect(onSubmit).toHaveBeenCalledTimes(1)
-    expect(onSubmit).toHaveBeenCalledWith({ foo: 'bar' }, formComponent.form)
+    expect(onSubmit.mock.calls[0][0]).toEqual({ foo: 'bar' })
   })
 
   it('should reinitialize when initialValues prop changes', () => {

src/index.d.ts

@@ -62,10 +62,9 @@ export type FormProps = {
 
 export type FieldProps = {
   allowNull?: boolean
-  format: (value: any, name: string) => any | null
-  parse: (value: any, name: string) => any | null
+  format: ((value: any, name: string) => any) | null
+  parse: ((value: any, name: string) => any) | null
   name: string
-  normalize: (value: any, previousValue: any, allValues: object) => any
   subscription?: FieldSubscription
   validate?: (value: any, allValues: object) => any
   value?: any

src/types.js.flow

@@ -63,11 +63,10 @@ export type FormProps = {
 
 export type FieldProps = {
   allowNull?: boolean,
-  format: (value: ?any, name: string) => ?any | null,
-  parse: (value: ?any, name: string) => ?any | null,
+  format: ((value: any, name: string) => any) | null,
   isEqual?: (a: any, b: any) => boolean,
   name: string,
-  normalize: (value: ?any, previousValue: ?any, allValues: Object) => ?any,
+  parse: ((value: any, name: string) => any) | null,
   subscription?: FieldSubscription,
   validate?: (value: ?any, allValues: Object) => ?any,
   validateFields?: string[],