Merge branch 'release/18.2.0'

Author: joanpablo

CHANGELOG.md

@@ -1,3 +1,16 @@
+# 18.2.0
+
+## Features
+
+- Allowed overwriting default value on reset. Added 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.
+- Enhanced `FormControl` reset method. Introduced a `nonNullable` property to the `FormControl` 
+  constructor to control the behavior of the `reset()` method. When `nonNullable` is `true` 
+  (the default), calling `reset()` without a value will reset the control to its initial value. When
+  `nonNullable` is `false`, calling `reset()` without a value will reset the control to `null`.
+- Exposed `defaultValue` of the `FormControl`.
+
 # 18.1.2
 
 ## Fixes

README.md

@@ -88,7 +88,7 @@ dependencies:
   flutter:
     sdk: flutter
 
-  reactive_forms: ^18.1.2
+  reactive_forms: ^18.2.0
 ```
 
 Then, run the command `flutter packages get` in the console.

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? _initialValue;
+  T? _defaultValue;
   final _focusChanges = StreamController<bool>.broadcast();
   FocusController? _focusController;
   bool _hasFocus = false;
@@ -848,6 +848,13 @@ class FormControl<T> extends AbstractControl<T> {
   ///
   /// The control can optionally be initialized with a [value].
   ///
+  /// The [nonNullable] argument is used to determine the state of the control
+  /// when the [reset] method is called without a value. If [nonNullable] is
+  /// true (the default), the [reset] method will reset the control to the
+  /// initial [value] provided in the constructor. If [nonNullable] is false,
+  /// the [reset] method will reset the control to `null` unless a value is
+  /// provided.
+  ///
   /// The control can optionally have [validators] that validates
   /// the control each time the value changes.
   ///
@@ -859,10 +866,6 @@ class FormControl<T> extends AbstractControl<T> {
   /// (such as an HTTP request) if the more basic validation methods have
   /// already found invalid input.
   ///
-  /// You can set an [asyncValidatorsDebounceTime] in millisecond to set
-  /// a delay time before trigger async validators. This is useful for
-  /// minimizing request to a server. The default value is 250 milliseconds.
-  ///
   /// You can set [touched] as true to force the validation messages
   /// to show up at the very first time the widget that is bound to this
   /// control builds in the UI.
@@ -876,6 +879,7 @@ class FormControl<T> extends AbstractControl<T> {
   ///
   FormControl({
     T? value,
+    bool nonNullable = true,
     super.validators,
     super.asyncValidators,
     @Deprecated(
@@ -887,14 +891,24 @@ class FormControl<T> extends AbstractControl<T> {
     super.asyncValidatorsDebounceTime,
     super.touched,
     super.disabled,
-  }) : _initialValue = value {
+  }) : _defaultValue = nonNullable ? value : null {
     if (value != null) {
       this.value = value;
     } else {
       updateValueAndValidity();
     }
   }
 
+  /// Gets the default value of the control.
+  ///
+  /// This value is determined by the [value] and [nonNullable] arguments
+  /// passed to the constructor:
+  /// - If [nonNullable] is `true` (the default), this holds the initial [value].
+  /// - If [nonNullable] is `false`, this is `null`.
+  ///
+  /// When [reset] is called without a value, the control resets to this value.
+  T? get defaultValue => _defaultValue;
+
   /// True if the control is marked as focused.
   bool get hasFocus => _hasFocus;
 
@@ -1016,21 +1030,92 @@ class FormControl<T> extends AbstractControl<T> {
     }
   }
 
+  /// Resets the form control, marking it as untouched and pristine.
+  ///
+  /// If [value] is provided, the control is reset to that value.
+  ///
+  /// If [value] is not provided (null), the behavior depends on the [nonNullable]
+  /// argument passed to the constructor:
+  /// - If [nonNullable] is `true` (the default), the control resets to the
+  ///   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
+  /// not set (the default) then the control will state in the same state that
+  /// it previously was.
+  ///
+  /// The argument [removeFocus] is optional and remove the UI focus from the
+  /// control.
+  ///
+  /// When [updateParent] is true or not supplied (the default) each change
+  /// affects this control and its parent, otherwise only affects to this
+  /// control.
+  ///
+  /// When [emitEvent] is true or not supplied (the default), both the
+  /// *statusChanges* and *valueChanges* events notify listeners with the
+  /// latest status and value when the control is reset. When false, no events
+  /// are emitted.
+  ///
+  /// ### Examples
+  ///
+  /// **Reset to a specific value**
+  /// ```dart
+  /// final control = FormControl<String>();
+  ///
+  /// control.reset(value: 'John Doe');
+  ///
+  /// print(control.value); // output: 'John Doe'
+  /// ```
+  ///
+  /// **Reset to initial value (nonNullable: true)**
+  /// ```dart
+  /// // nonNullable is true by default
+  /// final control = FormControl<String>(value: 'Initial Value');
+  ///
+  /// control.value = 'New Value';
+  ///
+  /// // Resets to 'Initial Value' because no value was provided
+  /// // and nonNullable is true.
+  /// control.reset();
+  ///
+  /// print(control.value); // output: 'Initial Value'
+  /// ```
+  ///
+  /// **Reset to null (nonNullable: false)**
+  /// ```dart
+  /// final control = FormControl<String>(
+  ///   value: 'Initial Value',
+  ///   nonNullable: false,
+  /// );
+  ///
+  /// control.value = 'New Value';
+  ///
+  /// // Resets to null because no value was provided
+  /// // and nonNullable is false.
+  /// control.reset();
+  ///
+  /// print(control.value); // output: null
+  ///
   @override
   void reset({
     T? value,
+    bool overwriteDefaultValue = false,
     bool updateParent = true,
     bool emitEvent = true,
     bool removeFocus = false,
     bool? disabled,
   }) {
-    // If `value` is null, it implies either `reset()` was called (no explicit value)
-    // or `reset(value: null)` was called.
-    // In line with "If no value is provided it should assign the initial value",
-    // we use `_initialValue` when `value` is `null`.
-    // If `value` is explicitly provided and not null, we use that.
+    if (overwriteDefaultValue) {
+      _defaultValue = value;
+    }
+
     super.reset(
-      value: value ?? _initialValue,
+      value: value ?? _defaultValue,
       updateParent: updateParent,
       emitEvent: emitEvent,
       removeFocus: removeFocus,

pubspec.yaml

@@ -1,6 +1,6 @@
 name: reactive_forms
 description: This is a model-driven approach to handling form inputs and validations, heavily inspired in Angular Reactive Forms.
-version: 18.1.2
+version: 18.2.0
 homepage: "https://github.com/joanpablo/reactive_forms"
 
 environment:

test/src/models/form_control_test.dart

@@ -415,7 +415,7 @@ void main() {
       'resets to initial value (null) if no argument is provided and initial value was null',
       () {
         // Arrange
-        final control = FormControl<String?>(value: null);
+        final control = FormControl<String>(value: null);
         control.updateValue('changed');
 
         // Act
@@ -430,7 +430,7 @@ void main() {
       'resets to initial value (null) if no argument is provided and no initial value was specified (implicitly null)',
       () {
         // Arrange
-        final control = FormControl<String?>();
+        final control = FormControl<String>();
         control.updateValue('changed');
 
         // Act
@@ -460,7 +460,7 @@ void main() {
       'resets to initial value when value argument is null and initial value was not null',
       () {
         // Arrange
-        final control = FormControl<String?>(value: 'initial');
+        final control = FormControl<String>(value: 'initial');
         control.updateValue('changed');
 
         // Act
@@ -470,25 +470,104 @@ void main() {
         expect(
           control.value,
           'initial',
-        ); // Because (value ?? _initialValue) => (null ?? "initial") => "initial"
+        ); // Because nonNullable is true by default
       },
     );
 
+    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';
+
+      // And: reset the control
+      control.reset();
+
+      // Then: control value is null
+      expect(control.value, null);
+    });
+
     test(
-      'resets to null when value argument is null and initial value was also null',
+      'resets control to null if no value provided and nonNullable is false',
       () {
         // Arrange
-        final control = FormControl<String?>(value: null);
-        control.updateValue('changed');
+        final control = FormControl<String>(nonNullable: false);
+        control.value = 'changed value';
 
         // Act
-        control.reset(value: null);
+        control.reset();
 
         // Assert
-        expect(
-          control.value,
-          null,
-        ); // Because (value ?? _initialValue) => (null ?? null) => null
+        expect(control.value, null); // Because no value provided
+      },
+    );
+  });
+
+  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);
       },
     );
   });

test/src/models/form_group_test.dart

@@ -288,14 +288,8 @@ void main() {
       });
 
       // When: enable form
-      print("form.enabled: ${form.enabled}");
-
       form.markAsEnabled();
 
-      form.controls.forEach((name, control) {
-        print("control[$name].enabled: ${control.enabled}");
-      });
-
       // Then: all controls are enabled
       expect(
         form.controls.values.every((control) => control.enabled),