refactor(core): Deprecate the structural directives ngIf/ngFor/ngSwitch. (#60492)

Note: This is not a deprecation of structural directives, this only about  `ngIf`/`ngFor`/`ngSwitch`.

DEPRECATED: `ngIf`/`ngFor`/`ngSwitch` are deprecated. Use the control flow blocks instead (`@for`/`@if`/`@switch`).

PR Close #60492

Author: JeanMeche

goldens/public-api/common/index.api.md

@@ -516,7 +516,7 @@ export class NgComponentOutlet<T = any> implements OnChanges, DoCheck, OnDestroy
     static ɵfac: i0.ɵɵFactoryDeclaration<NgComponentOutlet<any>, never>;
 }
 
-// @public
+// @public @deprecated
 class NgForOf<T, U extends NgIterable<T> = NgIterable<T>> implements DoCheck {
     constructor(_viewContainer: ViewContainerRef, _template: TemplateRef<NgForOfContext<T, U>>, _differs: IterableDiffers);
     ngDoCheck(): void;
@@ -534,7 +534,7 @@ class NgForOf<T, U extends NgIterable<T> = NgIterable<T>> implements DoCheck {
 export { NgForOf as NgFor }
 export { NgForOf }
 
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export class NgForOfContext<T, U extends NgIterable<T> = NgIterable<T>> {
     $implicit: T;
     constructor(
@@ -555,7 +555,7 @@ export class NgForOfContext<T, U extends NgIterable<T> = NgIterable<T>> {
     get odd(): boolean;
 }
 
-// @public
+// @public @deprecated
 export class NgIf<T = unknown> {
     constructor(_viewContainer: ViewContainerRef, templateRef: TemplateRef<NgIfContext<T>>);
     set ngIf(condition: T);
@@ -682,7 +682,7 @@ export class NgStyle implements DoCheck {
     static ɵfac: i0.ɵɵFactoryDeclaration<NgStyle, never>;
 }
 
-// @public
+// @public @deprecated
 export class NgSwitch {
     // (undocumented)
     set ngSwitch(newValue: any);

packages/common/src/directives/ng_for_of.ts

@@ -26,6 +26,8 @@ import {RuntimeErrorCode} from '../errors';
 
 /**
  * @publicApi
+ *
+ * @deprecated The `ngFor` directive is deprecated. Use the `@for` block instead.
  */
 export class NgForOfContext<T, U extends NgIterable<T> = NgIterable<T>> {
   constructor(
@@ -164,6 +166,8 @@ export class NgForOfContext<T, U extends NgIterable<T> = NgIterable<T>> {
  * @see [Structural Directives](guide/directives/structural-directives)
  * @ngModule CommonModule
  * @publicApi
+ *
+ * @deprecated Use the @for block instead. Intent to remove in v22
  */
 @Directive({
   selector: '[ngFor][ngForOf]',

packages/common/src/directives/ng_if.ts

@@ -156,6 +156,8 @@ import {RuntimeErrorCode} from '../errors';
  *
  * @ngModule CommonModule
  * @publicApi
+ *
+ * @deprecated Use the @if block instead. Intent to remove in v22
  */
 @Directive({
   selector: '[ngIf]',

packages/common/src/directives/ng_switch.ts

@@ -111,6 +111,7 @@ export class SwitchView {
  * @see {@link NgSwitchDefault}
  * @see [Structural Directives](guide/directives/structural-directives)
  *
+ * @deprecated Use the @switch block instead. Intent to remove in v22
  */
 @Directive({
   selector: '[ngSwitch]',
@@ -196,6 +197,7 @@ export class NgSwitch {
  * @see {@link NgSwitch}
  * @see {@link NgSwitchDefault}
  *
+ * @deprecated Use the @case block within a @switch block instead. Intent to remove in v22
  */
 @Directive({
   selector: '[ngSwitchCase]',
@@ -242,6 +244,7 @@ export class NgSwitchCase implements DoCheck {
  * @see {@link NgSwitch}
  * @see {@link NgSwitchCase}
  *
+ * @deprecated Use the @default block within a @switch block instead. Intent to remove in v22
  */
 @Directive({
   selector: '[ngSwitchDefault]',