Fix #988: Update initialValues when field initialValue prop changes

Problem

When using Field-level initialValue props (instead of Form-level initialValues), if the field's initialValue prop changes after submit (e.g., to reflect a newly saved value), the form's initialValues doesn't update. This causes the field to remain dirty even though the current value matches the new "saved" initialValue.

Example Scenario (Radio Buttons)

1. Field registers with initialValue="A" → Form initialValues = {field: "A"}
2. User changes to "B" → Form values = {field: "B"}, dirty = true
3. After submit, Field re-registers with initialValue="B" (reflecting saved value)
4. BUG: Form initialValues stays as {field: "A"}
5. Result: dirty calculation: "B" !== "A" = still dirty! ❌

Root Cause

In registerField (line 1002), the condition for updating initialValues was:

if (
  fieldConfig.initialValue !== undefined &&
  (noValueInFormState ||
    currentValue === currentInitialValue)
) {
  // Update initialValues
}

This fails when:

• noValueInFormState is FALSE (value exists)
• currentValue ("B") !== currentInitialValue ("A") is FALSE

So the new initialValue prop is ignored!

Solution

Added a second condition that updates initialValues when the field's initialValue prop changes, without overwriting the user's current input:

} else if (
  // Fix #988: Update initialValue when field's initialValue prop changes
  fieldConfig.initialValue !== undefined &&
  fieldConfig.initialValue !== currentInitialValue &&
  currentValue !== undefined
) {
  state.formState.initialValues = setIn(
    state.formState.initialValues || {},
    name as string,
    fieldConfig.initialValue,
  ) as InitialFormValues;
  runValidation(undefined, notify);
}

Tests

Added comprehensive test coverage in src/FinalForm.field-initialValue-988.test.ts:

1. Basic scenario: Field initialValue changes after user input → initialValues updates, dirty = false ✅
2. Preserve user input: Field initialValue changes but user has different value → initialValues updates but values unchanged ✅
3. Radio button scenario: Exact reproduction of issue #988 ✅

All existing tests still pass (367 total).

Related Issue

Fixes final-form/react-final-form#988

Checklist

• Code follows project style
• Added comprehensive test coverage
• All tests pass
• Handles edge cases (user input preservation)
• Backward compatible

Summary by CodeRabbit

• Bug Fixes

  • Prevents user-entered field values from being overwritten when a field's initial value changes; keeps initial/current values and dirty state consistent and refreshes validation.

• Tests

  • Added tests covering initial-value updates across registration and re-registration flows, including nested fields and radio selections.

• Chores

  • Slightly increased size-limit thresholds for built artifacts.