Documentation for defaultValue of FieldProps is not matching implementation

[mauron85]

Are you submitting a bug report or a feature request?

bug report

What is the current behavior?

The documentation for Field defaultValue states:

The value of the field upon creation. This value is only needed if you want your field be dirty upon creation (i.e. for its value to be different from its initial value).

So assumption is that to mark field as initially dirty we can set different defaultValue and initialValue.

For example:

<Field name={name} defaultValue={false} initialValue={true} />

What is the expected behavior?

Field defaultValue is only used when both form and field level initialValue are undefined. thus Field is not marked dirty, when initialValue is not undefined.

Current implementation:
https://github.com/final-form/final-form/blob/main/src/FinalForm.js#L908

        // only use defaultValue if we don't yet have any value for this field
        if (
          fieldConfig.defaultValue !== undefined &&
          fieldConfig.initialValue === undefined &&
          getIn(state.formState.initialValues, name) === undefined &&
          noValueInFormState
        ) {
          state.formState.values = setIn(
            state.formState.values,
            name,
            fieldConfig.defaultValue,
          );
        }

Sandbox Link

What's your environment?

React Final Form: 6.5.9

Other information