Added formatOnBlur prop (#274)

* Added formatOnBlur flag

* Doctocking

* Better doctoc script

Author: erikras

README.md

@@ -15,7 +15,7 @@
 
 ✅ Opt-in subscriptions - only update on the state you need!
 
-✅ 💥 [**2.9k gzipped**](https://bundlephobia.com/result?p=react-final-form) 💥
+✅ 💥 [**3.1k gzipped**](https://bundlephobia.com/result?p=react-final-form) 💥
 
 ---
 
@@ -147,7 +147,7 @@ const MyForm = () => (
   * [Async Redux Submission](#async-redux-submission)
   * [Declarative Form Rules](#declarative-form-rules)
   * [Format String By Pattern](#format-string-by-pattern)
-  * [AsyncTypeahead and Redux](#asynctypeahead-redux)
+  * [AsyncTypeahead and Redux](#asynctypeahead-and-redux)
 * [Rendering](#rendering)
 * [API](#api)
   * [`Field : React.ComponentType<FieldProps>`](#field--reactcomponenttypefieldprops)
@@ -160,6 +160,7 @@ const MyForm = () => (
     * [`children?: ((props: FieldRenderProps) => React.Node) | React.Node`](#children-props-fieldrenderprops--reactnode--reactnode)
     * [`component?: React.ComponentType<FieldRenderProps> | string`](#component-reactcomponenttypefieldrenderprops--string)
     * [`format?: ((value: any, name: string) => any) | null`](#format-value-any-name-string--any--null)
+    * [`formatOnBlur?: boolean`](#formatonblur-boolean)
     * [`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)
@@ -454,6 +455,10 @@ A function that takes the value from the form values and the name of the field a
 
 **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.**
 
+#### `formatOnBlur?: boolean`
+
+If `true`, the `format` function will only be called when the field is blurred. If `false`, `format` will be called on every render. Defaults to `false`.
+
 #### `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).

package.json

@@ -11,6 +11,8 @@
   "scripts": {
     "start": "nps",
     "test": "nps test",
+    "doctoc":
+      "doctoc README.md && doctoc docs/faq.md && prettier --write README.md && prettier --write docs/faq.md",
     "precommit": "lint-staged && npm start validate",
     "prepublish": "npm start validate",
     "postinstall": "opencollective postinstall || exit 0"

src/Field.js

@@ -103,7 +103,16 @@ export default class Field extends React.Component<Props, State> {
 
   handlers = {
     onBlur: (event: ?SyntheticFocusEvent<*>) => {
-      this.state.state && this.state.state.blur()
+      const { state } = this.state
+      // this is to appease the Flow gods
+      // istanbul ignore next
+      if (state) {
+        const { format, formatOnBlur } = this.props
+        state.blur()
+        if (format && formatOnBlur) {
+          state.change(format(state.value, state.name))
+        }
+      }
     },
     onChange: (event: SyntheticInputEvent<*> | any) => {
       const { parse, value: _value } = this.props
@@ -155,6 +164,7 @@ export default class Field extends React.Component<Props, State> {
       component,
       children,
       format,
+      formatOnBlur,
       parse,
       isEqual,
       name,
@@ -183,7 +193,9 @@ export default class Field extends React.Component<Props, State> {
       valid: otherState.valid,
       visited: otherState.visited
     }
-    if (format) {
+    if (formatOnBlur) {
+      value = Field.defaultProps.format(value, name)
+    } else if (format) {
       value = format(value, name)
     }
     if (value === null && !allowNull) {

src/Field.test.js

@@ -270,6 +270,48 @@ describe('Field', () => {
     expect(renderInput.mock.calls[2][0].input.value).toBe('format.bar')
   })
 
+  it('should only format on blur if formatOnBlur is true', () => {
+    const format = jest.fn((value, name) => `format.${value}`)
+    const renderInput = jest.fn(({ input }) => <input {...input} />)
+    const render = jest.fn(() => (
+      <form>
+        <Field name="foo" render={renderInput} format={format} formatOnBlur />
+      </form>
+    ))
+
+    TestUtils.renderIntoDocument(
+      <Form onSubmit={onSubmitMock} render={render} subscription={{}} />
+    )
+
+    expect(render).toHaveBeenCalled()
+    expect(render).toHaveBeenCalledTimes(1)
+    expect(render.mock.calls[0][0].values).toBeUndefined()
+
+    expect(format).not.toHaveBeenCalled()
+
+    expect(renderInput).toHaveBeenCalled()
+    expect(renderInput).toHaveBeenCalledTimes(1)
+    expect(renderInput.mock.calls[0][0].input.value).toBe('')
+
+    const { onFocus, onChange, onBlur } = renderInput.mock.calls[0][0].input
+
+    onFocus()
+    expect(renderInput).toHaveBeenCalledTimes(2)
+    onChange('bar')
+    expect(renderInput).toHaveBeenCalledTimes(3)
+
+    expect(format).not.toHaveBeenCalled()
+
+    onBlur()
+
+    expect(format).toHaveBeenCalled()
+    expect(format).toHaveBeenCalledTimes(1)
+    expect(format.mock.calls[0]).toEqual(['bar', 'foo'])
+
+    expect(renderInput).toHaveBeenCalledTimes(5)
+    expect(renderInput.mock.calls[4][0].input.value).toBe('format.bar')
+  })
+
   it('should accept a null format prop to preserve undefined values', () => {
     const renderInput = jest.fn(({ input }) => (
       <input {...input} value={input.value || ''} />
@@ -422,9 +464,7 @@ describe('Field', () => {
     const requiredUppercase = value =>
       !value
         ? 'Required'
-        : value.toUpperCase() === value
-          ? undefined
-          : 'Must be uppercase'
+        : value.toUpperCase() === value ? undefined : 'Must be uppercase'
     class FieldsContainer extends React.Component {
       state = { uppercase: false }
 
@@ -456,9 +496,7 @@ describe('Field', () => {
     expect(input).toHaveBeenCalledTimes(2)
     expect(input.mock.calls[1][0].meta.error).toBe('Required')
 
-    const {
-      input: { onChange }
-    } = input.mock.calls[1][0]
+    const { input: { onChange } } = input.mock.calls[1][0]
 
     onChange('hi')
 

src/index.d.ts

@@ -24,7 +24,7 @@ export interface FieldRenderProps {
   meta: Partial<{
     // TODO: Make a diff of `FieldState` without all the functions
     active: boolean
-    data: object,
+    data: object
     dirty: boolean
     dirtySinceLastSubmit: boolean
     error: any
@@ -74,6 +74,7 @@ export interface FormProps extends Config, RenderableProps<FormRenderProps> {
 export interface FieldProps extends RenderableProps<FieldRenderProps> {
   allowNull?: boolean
   format?: ((value: any, name: string) => any) | null
+  formatOnBlur?: boolean
   parse?: ((value: any, name: string) => any) | null
   name: string
   isEqual?: (a: any, b: any) => boolean

src/types.js.flow

@@ -80,6 +80,7 @@ export type FieldProps = {
   allowNull?: boolean,
   component?: React.ComponentType<*> | SupportedInputs,
   format?: (value: any, name: string) => any,
+  formatOnBlur?: boolean,
   isEqual?: (a: any, b: any) => boolean,
   name: string,
   parse?: (value: any, name: string) => any,