#488 - Allow overwriting default value on reset

- Adds an `overwriteDefaultValue` parameter to the `FormControl.reset()` method.
- When `overwriteDefaultValue` is `true`, the value passed to `reset()` becomes the new default value for the control.
- This allows dynamically updating what the control considers its "default" state to reset to.
- The internal `_defaultValue` field in `FormControl` is now mutable to support this change.

Author: joanpablo

lib/src/models/models.dart

@@ -839,7 +839,7 @@ abstract class AbstractControl<T> {
 
 /// Tracks the value and validation status of an individual form control.
 class FormControl<T> extends AbstractControl<T> {
-  final T? _defaultValue;
+  T? _defaultValue;
   final _focusChanges = StreamController<bool>.broadcast();
   FocusController? _focusController;
   bool _hasFocus = false;
@@ -1040,6 +1040,9 @@ class FormControl<T> extends AbstractControl<T> {
   ///   initial value provided in the constructor.
   /// - If [nonNullable] is `false`, the control resets to `null`.
   ///
+  /// If [overwriteDefaultValue] is true, then the value used to reset the
+  /// control becomes the new default value of the control.
+  ///
   /// The argument [disabled] is optional and resets the disabled status of the
   /// control. If value is `true` then it will disable the control, if value is
   /// `false` then it will enable the control, and if the value is `null` or
@@ -1101,11 +1104,16 @@ class FormControl<T> extends AbstractControl<T> {
   @override
   void reset({
     T? value,
+    bool overwriteDefaultValue = false,
     bool updateParent = true,
     bool emitEvent = true,
     bool removeFocus = false,
     bool? disabled,
   }) {
+    if (overwriteDefaultValue) {
+      _defaultValue = value;
+    }
+
     super.reset(
       value: value ?? _defaultValue,
       updateParent: updateParent,

test/src/models/form_control_test.dart

@@ -474,19 +474,21 @@ void main() {
       },
     );
 
-    test('resets to null is nonNullable is false', () {
-      // Arrange
+    test('resets to null if nonNullable is false', () {
+      // Given: a control with an initial value and nonNullable as false
       final control = FormControl<String>(
         value: 'initialValue',
         nonNullable: false,
       );
+
+      // When: set a new value
       control.value = 'changed value';
 
-      // Act
+      // And: reset the control
       control.reset();
 
-      // Assert
-      expect(control.value, null); // Because nonNullable is false
+      // Then: control value is null
+      expect(control.value, null);
     });
 
     test(
@@ -504,4 +506,69 @@ void main() {
       },
     );
   });
+
+  group('FormControl reset with overwriteDefaultValue', () {
+    test('updates default value when overwriteDefaultValue is true', () {
+      // Given: a control with an initial value
+      final control = FormControl<String>(value: 'initial');
+
+      // When: reset to a new value and ask to overwrite the default
+      control.reset(value: 'newDefault', overwriteDefaultValue: true);
+
+      // Then: current value is the new value
+      expect(control.value, 'newDefault');
+      // And: the default value property is updated
+      expect(control.defaultValue, 'newDefault');
+
+      // When: we make the control dirty again
+      control.value = 'dirty value';
+
+      // And: we reset without arguments
+      control.reset();
+
+      // Then: it resets to the NEW default value
+      expect(control.value, 'newDefault');
+    });
+
+    test(
+      'does not update default value when overwriteDefaultValue is false',
+      () {
+        // Given: a control with an initial value
+        final control = FormControl<String>(value: 'initial');
+
+        // When: reset with a specific value but do NOT overwrite default
+        control.reset(value: 'tempValue', overwriteDefaultValue: false);
+
+        // Then: value is the temporary value
+        expect(control.value, 'tempValue');
+        // And: default value remains the original one
+        expect(control.defaultValue, 'initial');
+
+        // When: we make the control dirty again
+        control.value = 'dirty value';
+
+        // And: we reset without arguments
+        control.reset();
+
+        // Then: it resets to the ORIGINAL default value
+        expect(control.value, 'initial');
+      },
+    );
+
+    test(
+      'updates default value to null when value is null and overwriteDefaultValue is true',
+      () {
+        // Given: a control with an initial value
+        final control = FormControl<String>(value: 'initial');
+
+        // When: reset to null and overwrite default
+        control.reset(value: null, overwriteDefaultValue: true);
+
+        // Then: value is null
+        expect(control.value, null);
+        // And: default value is null
+        expect(control.defaultValue, null);
+      },
+    );
+  });
 }