docs(forms): Deprecate legacy options for FormBuilder.group (angular#…

…39769)

DEPRECATION:

Mark the {[key: string]: any} type for the options property of the FormBuilder.group method as deprecated.
Using AbstractControlOptions gives the same functionality and is type-safe.

PR Close angular#39769

aio/content/guide/deprecations.md

@@ -31,6 +31,8 @@ v7 - v10
 v8 - v11
 v9 - v12
 v10 - v13
+v11 - v14
+v12 - v15
 -->
 
 
@@ -54,7 +56,8 @@ v10 - v13
 | `@angular/core`               | [`ANALYZE_FOR_ENTRY_COMPONENTS`](api/core/ANALYZE_FOR_ENTRY_COMPONENTS)       | <!--v9--> v11 |
 | `@angular/router`             | [`loadChildren` string syntax](#loadChildren)                                 | <!--v9--> v11 |
 | `@angular/core/testing`       | [`TestBed.get`](#testing)                                                     | <!--v9--> v12 |
-| `@angular/core/testing`       | [`async`](#testing)                                                     | <!--v9--> v12 |
+| `@angular/core/testing`       | [`async`](#testing)                                                           | <!--v9--> v12 |
+| `@angular/forms`              | [`FormBuilder.group` legacy options parameter](api/forms/FormBuilder#group)   | <!--v11--> v14 |
 | `@angular/router`             | [`ActivatedRoute` params and `queryParams` properties](#activatedroute-props) | unspecified |
 | template syntax               | [`/deep/`, `>>>`, and `::ng-deep`](#deep-component-style-selector)            | <!--v7--> unspecified |
 
@@ -108,6 +111,7 @@ Tip: In the [API reference section](api) of this doc site, deprecated APIs are i
 | API | Replacement | Deprecation announced | Notes |
 | --- | ----------- | --------------------- | ----- |
 | [`ngModel` with reactive forms](#ngmodel-reactive) | [`FormControlDirective`](api/forms/FormControlDirective) | v6 | none |
+| [`FormBuilder.group` legacy options parameter](api/forms/FormBuilder#group) | [`AbstractControlOptions` parameter value](api/forms/AbstractControlOptions) | v11 | none |
 
 
 {@a upgrade}
@@ -434,7 +438,7 @@ This section contains a complete list all of the currently deprecated CLI flags.
 
 | API/Option                      | May be removed in | Notes                                                                           |
 | ------------------------------- | ----------------- |-------------------------------------------------------------------------------- |
-| `extractCss`                    | <!--v11--> v13     | No longer required to disable CSS extraction during development.               | 
+| `extractCss`                    | <!--v11--> v13     | No longer required to disable CSS extraction during development.               |
 | `i18nFormat`                    | <!--v9--> v12      | Format is now automatically detected.                                           |
 | `i18nLocale`                    | <!--v9--> v12      | New [localization option](/guide/i18n#localize-config) in version 9 and later.  |
 | `lazyModules`                   | <!--v9--> v12      | Used with deprecated SystemJsNgModuleLoader.                                    |

goldens/public-api/forms/forms.d.ts

@@ -207,9 +207,12 @@ export declare class FormBuilder {
     control(formState: any, validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null): FormControl;
     group(controlsConfig: {
         [key: string]: any;
-    }, options?: AbstractControlOptions | {
+    }, options?: AbstractControlOptions | null): FormGroup;
+    /** @deprecated */ group(controlsConfig: {
         [key: string]: any;
-    } | null): FormGroup;
+    }, options: {
+        [key: string]: any;
+    }): FormGroup;
 }
 
 export declare class FormControl extends AbstractControl {

packages/forms/src/form_builder.ts

@@ -39,20 +39,38 @@ export class FormBuilder {
    * @param controlsConfig A collection of child controls. The key for each child is the name
    * under which it is registered.
    *
-   * @param options Configuration options object for the `FormGroup`. The object can
-   * have two shapes:
-   *
-   * 1) `AbstractControlOptions` object (preferred), which consists of:
+   * @param options Configuration options object for the `FormGroup`. The object should have the
+   * the `AbstractControlOptions` type and might contain the following fields:
    * * `validators`: A synchronous validator function, or an array of validator functions
    * * `asyncValidators`: A single async validator or array of async validator functions
    * * `updateOn`: The event upon which the control should be updated (options: 'change' | 'blur' |
    * submit')
+   */
+  group(
+      controlsConfig: {[key: string]: any},
+      options?: AbstractControlOptions|null,
+      ): FormGroup;
+  /**
+   * @description
+   * Construct a new `FormGroup` instance.
    *
-   * 2) Legacy configuration object, which consists of:
+   * @deprecated This api is not typesafe and can result in issues with Closure Compiler renaming.
+   *  Use the `FormBuilder#group` overload with `AbstractControlOptions` instead.
+   *
+   * @param controlsConfig A collection of child controls. The key for each child is the name
+   * under which it is registered.
+   *
+   * @param options Configuration options object for the `FormGroup`. The legacy configuration
+   * object consists of:
    * * `validator`: A synchronous validator function, or an array of validator functions
    * * `asyncValidator`: A single async validator or array of async validator functions
-   *
+   * Note: the legacy format is deprecated and might be removed in one of the next major versions
+   * of Angular.
    */
+  group(
+      controlsConfig: {[key: string]: any},
+      options: {[key: string]: any},
+      ): FormGroup;
   group(
       controlsConfig: {[key: string]: any},
       options: AbstractControlOptions|{[key: string]: any}|null = null): FormGroup {