refactor(animations): deprecation of AnimationDriver.NOOP (#51843)

The `NoopAnimationDriver` as static property of `AnimationDriver` prevents it from being removed by tree shaking. This commit deprecates it and exposes the `NoopAnimationDriver` on the public API to replace its usage.

DEPRECATED:
The `AnimationDriver.NOOP` symbol is deprecated, use `NoopAnimationDriver` instead.

PR Close #51843

aio/content/guide/deprecations.md

@@ -129,6 +129,7 @@ v16 - v19
 
 | Area                                | API or Feature                                                                                             | Deprecated in | May be removed in |
 |:---                                 |:---                                                                                                        |:---           |:---               |
+| `@angular/animations` | `AnimationDriver.NOOP` | v17 | v19 |
 | `@angular/core` | `PACKAGE_ROOT_URL` | v17 | v19 |
 
 ### Deprecated features with no planned removal version
@@ -150,6 +151,14 @@ In the [API reference section](api) of this site, deprecated APIs are indicated
 
 </div>
 
+<a id="animations"></a>
+
+### &commat;angular/animations
+
+| API                                                                                           | Replacement                                         | Deprecation announced | Details |
+|:---                                                                                           |:---                                                 |:---                   |:---     |
+| [AnimationDriver.NOOP](api/animations/browser/AnimationDriver#NOOP) | `NoopAnimationDriver` | v17 | Create a new  `NoopAnimationDriver` directly instead of calling `AnimationDriver.NOOP`
+
 <a id="common"></a>
 
 ### &commat;angular/common

goldens/public-api/animations/browser/index.md

@@ -4,6 +4,9 @@
 
 ```ts
 
+import { AnimationPlayer } from '@angular/animations';
+import * as i0 from '@angular/core';
+
 // @public (undocumented)
 export abstract class AnimationDriver {
     // (undocumented)
@@ -15,7 +18,7 @@ export abstract class AnimationDriver {
     abstract getParentElement(element: unknown): unknown;
     // @deprecated (undocumented)
     abstract matchesElement(element: any, selector: string): boolean;
-    // (undocumented)
+    // @deprecated (undocumented)
     static NOOP: AnimationDriver;
     // (undocumented)
     abstract query(element: any, selector: string, multi: boolean): any[];
@@ -25,6 +28,28 @@ export abstract class AnimationDriver {
     abstract validateStyleProperty(prop: string): boolean;
 }
 
+// @public
+export class NoopAnimationDriver implements AnimationDriver {
+    // (undocumented)
+    animate(element: any, keyframes: Array<Map<string, string | number>>, duration: number, delay: number, easing: string, previousPlayers?: any[], scrubberAccessRequested?: boolean): AnimationPlayer;
+    // (undocumented)
+    computeStyle(element: any, prop: string, defaultValue?: string): string;
+    // (undocumented)
+    containsElement(elm1: any, elm2: any): boolean;
+    // (undocumented)
+    getParentElement(element: unknown): unknown;
+    // @deprecated (undocumented)
+    matchesElement(_element: any, _selector: string): boolean;
+    // (undocumented)
+    query(element: any, selector: string, multi: boolean): any[];
+    // (undocumented)
+    validateStyleProperty(prop: string): boolean;
+    // (undocumented)
+    static ɵfac: i0.ɵɵFactoryDeclaration<NoopAnimationDriver, never>;
+    // (undocumented)
+    static ɵprov: i0.ɵɵInjectableDeclaration<NoopAnimationDriver>;
+}
+
 // (No @packageDocumentation comment for this package)
 
 ```

packages/animations/browser/src/browser.ts

@@ -11,5 +11,5 @@
  * @description
  * Entry point for all animation APIs of the animation browser package.
  */
-export {AnimationDriver} from './render/animation_driver';
+export {AnimationDriver, NoopAnimationDriver} from './render/animation_driver';
 export * from './private_export';

packages/animations/browser/src/private_export.ts

@@ -8,7 +8,6 @@
 export {Animation as ɵAnimation} from './dsl/animation';
 export {AnimationStyleNormalizer as ɵAnimationStyleNormalizer, NoopAnimationStyleNormalizer as ɵNoopAnimationStyleNormalizer} from './dsl/style_normalization/animation_style_normalizer';
 export {WebAnimationsStyleNormalizer as ɵWebAnimationsStyleNormalizer} from './dsl/style_normalization/web_animations_style_normalizer';
-export {NoopAnimationDriver as ɵNoopAnimationDriver} from './render/animation_driver';
 export {AnimationEngine as ɵAnimationEngine} from './render/animation_engine_next';
 export {containsElement as ɵcontainsElement, getParentElement as ɵgetParentElement, invokeQuery as ɵinvokeQuery, validateStyleProperty as ɵvalidateStyleProperty, validateWebAnimatableStyleProperty as ɵvalidateWebAnimatableStyleProperty} from './render/shared';
 export {WebAnimationsDriver as ɵWebAnimationsDriver} from './render/web_animations/web_animations_driver';

packages/animations/browser/src/render/animation_driver.ts

@@ -10,33 +10,61 @@ import {Injectable} from '@angular/core';
 
 import {containsElement, getParentElement, invokeQuery, validateStyleProperty} from './shared';
 
+/**
+ * @publicApi
+ *
+ * `AnimationDriver` implentation for Noop animations
+ */
 @Injectable()
 export class NoopAnimationDriver implements AnimationDriver {
+  /**
+   * @returns Whether `prop` is a valid CSS property
+   */
   validateStyleProperty(prop: string): boolean {
     return validateStyleProperty(prop);
   }
 
+  /**
+   * @deprecated unused
+   */
   matchesElement(_element: any, _selector: string): boolean {
     // This method is deprecated and no longer in use so we return false.
     return false;
   }
 
+  /**
+   *
+   * @returns Whether elm1 contains elm2.
+   */
   containsElement(elm1: any, elm2: any): boolean {
     return containsElement(elm1, elm2);
   }
 
+  /**
+   * @returns Rhe parent of the given element or `null` if the element is the `document`
+   */
   getParentElement(element: unknown): unknown {
     return getParentElement(element);
   }
 
+  /**
+   * @returns The result of the query selector on the element. The array will contain up to 1 item
+   *     if `multi` is  `false`.
+   */
   query(element: any, selector: string, multi: boolean): any[] {
     return invokeQuery(element, selector, multi);
   }
 
+  /**
+   * @returns The `defaultValue` or empty string
+   */
   computeStyle(element: any, prop: string, defaultValue?: string): string {
     return defaultValue || '';
   }
 
+  /**
+   * @returns An `NoopAnimationPlayer`
+   */
   animate(
       element: any, keyframes: Array<Map<string, string|number>>, duration: number, delay: number,
       easing: string, previousPlayers: any[] = [],
@@ -49,6 +77,9 @@ export class NoopAnimationDriver implements AnimationDriver {
  * @publicApi
  */
 export abstract class AnimationDriver {
+  /**
+   * @deprecated Use the NoopAnimationDriver class.
+   */
   static NOOP: AnimationDriver = (/* @__PURE__ */ new NoopAnimationDriver());
 
   abstract validateStyleProperty(prop: string): boolean;

packages/core/test/animation/animation_integration_spec.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 import {animate, animateChild, animation, AnimationEvent, AnimationMetadata, AnimationOptions, AUTO_STYLE, group, keyframes, query, sequence, state, style, transition, trigger, useAnimation, ɵPRE_STYLE as PRE_STYLE} from '@angular/animations';
-import {AnimationDriver, ɵAnimationEngine, ɵNoopAnimationDriver as NoopAnimationDriver} from '@angular/animations/browser';
+import {AnimationDriver, NoopAnimationDriver, ɵAnimationEngine} from '@angular/animations/browser';
 import {MockAnimationDriver, MockAnimationPlayer} from '@angular/animations/browser/testing';
 import {ChangeDetectorRef, Component, HostBinding, HostListener, Inject, RendererFactory2, ViewChild, ViewContainerRef} from '@angular/core';
 import {fakeAsync, flushMicrotasks, TestBed} from '@angular/core/testing';

packages/platform-browser/animations/src/providers.ts

@@ -7,7 +7,7 @@
  */
 
 import {AnimationBuilder} from '@angular/animations';
-import {AnimationDriver, ɵAnimationEngine as AnimationEngine, ɵAnimationStyleNormalizer as AnimationStyleNormalizer, ɵNoopAnimationDriver as NoopAnimationDriver, ɵWebAnimationsDriver as WebAnimationsDriver, ɵWebAnimationsStyleNormalizer as WebAnimationsStyleNormalizer} from '@angular/animations/browser';
+import {AnimationDriver, NoopAnimationDriver, ɵAnimationEngine as AnimationEngine, ɵAnimationStyleNormalizer as AnimationStyleNormalizer, ɵWebAnimationsDriver as WebAnimationsDriver, ɵWebAnimationsStyleNormalizer as WebAnimationsStyleNormalizer} from '@angular/animations/browser';
 import {DOCUMENT} from '@angular/common';
 import {ANIMATION_MODULE_TYPE, ApplicationRef, Inject, Injectable, NgZone, OnDestroy, Provider, RendererFactory2} from '@angular/core';
 import {ɵDomRendererFactory2 as DomRendererFactory2} from '@angular/platform-browser';