#488 - Enhance FormControl reset method

- This introduces 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`.
- Documentation for the constructor and the `reset` method has been updated to reflect this new behavior, including new examples.
- Added a new unit test to verify the `nonNullable: false` behavior.

Author: joanpablo

lib/src/models/models.dart

@@ -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.
@@ -875,11 +878,8 @@ class FormControl<T> extends AbstractControl<T> {
   /// ```
   ///
   FormControl({
-    @Deprecated(
-      "Use [defaultValue] to specify the initial default value for the form control.",
-    )
     T? value,
-    T? defaultValue,
+    bool nonNullable = true,
     super.validators,
     super.asyncValidators,
     @Deprecated(
@@ -891,7 +891,7 @@ class FormControl<T> extends AbstractControl<T> {
     super.asyncValidatorsDebounceTime,
     super.touched,
     super.disabled,
-  }) : _defaultValue = defaultValue ?? value {
+  }) : _defaultValue = nonNullable ? value : null {
     if (value != null) {
       this.value = value;
     } else {
@@ -900,6 +900,13 @@ class FormControl<T> extends AbstractControl<T> {
   }
 
   /// 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.
@@ -1023,6 +1030,74 @@ 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`.
+  ///
+  /// 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,

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,37 @@ void main() {
         expect(
           control.value,
           'initial',
-        ); // Because (value ?? _initialValue) => (null ?? "initial") => "initial"
+        ); // Because nonNullable is true by default
       },
     );
 
+    test('resets to null is nonNullable is false', () {
+      // Arrange
+      final control = FormControl<String>(
+        value: 'initialValue',
+        nonNullable: false,
+      );
+      control.value = 'changed value';
+
+      // Act
+      control.reset();
+
+      // Assert
+      expect(control.value, null); // Because nonNullable is false
+    });
+
     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
       },
     );
   });

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),