From b407157ee848296cd264891b1d7cc9c57c719418 Mon Sep 17 00:00:00 2001
From: Matthieu Riegler <kyro38@gmail.com>
Date: Thu, 20 Mar 2025 19:10:52 +0100
Subject: [PATCH] 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
---
 goldens/public-api/common/index.api.md      | 8 ++++----
 packages/common/src/directives/ng_for_of.ts | 4 ++++
 packages/common/src/directives/ng_if.ts     | 2 ++
 packages/common/src/directives/ng_switch.ts | 3 +++
 4 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/goldens/public-api/common/index.api.md b/goldens/public-api/common/index.api.md
index 16e86935ea2..1de8d8a2a35 100644
--- a/goldens/public-api/common/index.api.md
+++ b/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);
diff --git a/packages/common/src/directives/ng_for_of.ts b/packages/common/src/directives/ng_for_of.ts
index 70129bc07c5..8794a0bf8f9 100644
--- a/packages/common/src/directives/ng_for_of.ts
+++ b/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]',
diff --git a/packages/common/src/directives/ng_if.ts b/packages/common/src/directives/ng_if.ts
index d90e575923b..3b21c3bfa0e 100644
--- a/packages/common/src/directives/ng_if.ts
+++ b/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]',
diff --git a/packages/common/src/directives/ng_switch.ts b/packages/common/src/directives/ng_switch.ts
index 1ad19b45f12..b2139afe4a7 100644
--- a/packages/common/src/directives/ng_switch.ts
+++ b/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]',