fix(core): debounce leave animation instruction calls

There are cases where the animation instructions get called in rapid succession. For example:

```
@if (show$ | async) {
  <div animate.leave="class-name">...</div>
}
```

In this situation, the leave instruction may be called several times.
With `animate.leave` this causes problems due to the promises that are awaited, but will never resolve. This results in duplicated or nodes that are left behind.

This PR adds a debounce based on the lView, tNode index, and value. The main reason we need to key off of the value is because of host binding composition, which is a legitimate reason we may have multiple calls in rapid succession. We need to still allow those to happen.

`animate.enter` would also be called in rapid succession in this same scenario, but there's no concerns with that situation since there's no promises present. It would resolve on its own.

fixes: angular#64581

Author: thePunderWoman

packages/core/src/animation/interfaces.ts

@@ -76,9 +76,12 @@ export interface LongestAnimation {
   duration: number;
 }
 
+export type AnimationValue = string | Function | AnimationFunction;
+
 export interface NodeAnimations {
   animateFns: Function[];
   resolvers?: VoidFunction[];
+  timeouts?: Map<AnimationValue, unknown>;
 }
 
 export interface AnimationLViewData {

packages/core/src/animation/utils.ts

@@ -7,7 +7,7 @@
  */
 
 import {stringify} from '../util/stringify'; // Adjust imports as per actual location
-import {ANIMATIONS_DISABLED, LongestAnimation, NodeAnimations} from './interfaces';
+import {ANIMATIONS_DISABLED, AnimationValue, LongestAnimation, NodeAnimations} from './interfaces';
 import {INJECTOR, LView, DECLARATION_LCONTAINER, ANIMATIONS} from '../render3/interfaces/view';
 import {RuntimeError, RuntimeErrorCode} from '../errors';
 import {Renderer} from '../render3/interfaces/renderer';
@@ -16,6 +16,7 @@ import {TNode} from '../render3/interfaces/node';
 import {getBeforeNodeForView} from '../render3/node_manipulation';
 
 const DEFAULT_ANIMATIONS_DISABLED = false;
+const ANIMATION_LEAVE_DEBOUNCE_TIMEOUT = 10;
 
 export const areAnimationSupported =
   (typeof ngServerMode === 'undefined' || !ngServerMode) &&
@@ -292,3 +293,29 @@ export function leaveAnimationFunctionCleanup(
   cleanupAfterLeaveAnimations(resolvers, cleanupFns);
   clearLViewNodeAnimationResolvers(lView, tNode);
 }
+
+/**
+ * We have to debounce leave animations due to potential for legitimate rapid calling of the instruction
+ * in cases with async control flow values. Due to composition with host bindings, we need to key off
+ * of the value, as composition with host bindings are a valid reason for rapid calls.
+ */
+export function debounceLeaveAnimation(
+  lView: LView,
+  tNode: TNode,
+  value: AnimationValue,
+  animateFn: Function,
+) {
+  const animations = getLViewLeaveAnimations(lView);
+  const nodeAnimations = animations.get(tNode.index) ?? {animateFns: []};
+  if (nodeAnimations.timeouts && nodeAnimations.timeouts.has(value)) {
+    clearTimeout(nodeAnimations.timeouts.get(value) as number);
+  }
+  const timeouts = (nodeAnimations.timeouts ??= new Map<AnimationValue, unknown>());
+  const timeoutId = setTimeout(() => {
+    timeouts.delete(value);
+    animateFn();
+  }, ANIMATION_LEAVE_DEBOUNCE_TIMEOUT);
+
+  timeouts.set(value, timeoutId);
+  animations.set(tNode.index, nodeAnimations);
+}

packages/core/src/render3/instructions/animation.ts

@@ -33,6 +33,7 @@ import {
   cleanupEnterClassData,
   clearLeavingNodes,
   clearLViewNodeAnimationResolvers,
+  debounceLeaveAnimation,
   enterClassMap,
   getClassListFromValue,
   getLViewEnterAnimations,
@@ -251,11 +252,12 @@ export function ɵɵanimateLeave(value: string | Function): typeof ɵɵanimateLe
   const tNode = getCurrentTNode()!;
   cancelLeavingNodes(tNode, lView);
 
-  addAnimationToLView(getLViewLeaveAnimations(lView), tNode, () =>
-    runLeaveAnimations(lView, tNode, value),
-  );
-
-  initializeAnimationQueueScheduler(lView[INJECTOR]);
+  debounceLeaveAnimation(lView, tNode, value, () => {
+    addAnimationToLView(getLViewLeaveAnimations(lView), tNode, () =>
+      runLeaveAnimations(lView, tNode, value),
+    );
+    initializeAnimationQueueScheduler(lView[INJECTOR]);
+  });
 
   return ɵɵanimateLeave; // For chaining
 }
@@ -341,6 +343,7 @@ function animateLeaveClassRunner(
   for (const item of classList) {
     renderer.addClass(el, item);
   }
+
   // In the case that the classes added have no animations, we need to remove
   // the element right away. This could happen because someone is intentionally
   // preventing an animation via selector specificity.
@@ -384,13 +387,13 @@ export function ɵɵanimateLeaveListener(value: AnimationFunction): typeof ɵɵa
   const tNode = getCurrentTNode()!;
   cancelLeavingNodes(tNode, lView);
 
-  allLeavingAnimations.add(lView);
-
-  addAnimationToLView(getLViewLeaveAnimations(lView), tNode, () =>
-    runLeaveAnimationFunction(lView, tNode, value),
-  );
-
-  initializeAnimationQueueScheduler(lView[INJECTOR]);
+  debounceLeaveAnimation(lView, tNode, value, () => {
+    allLeavingAnimations.add(lView);
+    addAnimationToLView(getLViewLeaveAnimations(lView), tNode, () =>
+      runLeaveAnimationFunction(lView, tNode, value),
+    );
+    initializeAnimationQueueScheduler(lView[INJECTOR]);
+  });
 
   return ɵɵanimateLeaveListener; // For chaining
 }

packages/core/test/acceptance/animation_spec.ts

@@ -1651,7 +1651,7 @@ describe('Animation', () => {
         encapsulation: ViewEncapsulation.None,
       })
       class TestComponent {
-        show = signal(false);
+        show = signal(true);
         cdr = inject(ChangeDetectorRef);
 
         toggle() {
@@ -1674,8 +1674,16 @@ describe('Animation', () => {
       cmp.toggle();
       fixture.detectChanges();
       tickAnimationFrames(1);
-      const paragraphs = fixture.debugElement.queryAll(By.css('p'));
-      expect(paragraphs.length).toBe(1);
+
+      fixture.debugElement
+        .query(By.css('p'))
+        .nativeElement.dispatchEvent(
+          new AnimationEvent('animationend', {animationName: 'fade-out'}),
+        );
+      fixture.detectChanges();
+      tickAnimationFrames(1);
+
+      expect(fixture.debugElement.queryAll(By.css('p')).length).toBe(0);
     }));
 
     it('should always run animations for `@for` loops when adding and removing quickly', fakeAsync(() => {
@@ -2045,7 +2053,6 @@ describe('Animation', () => {
       cmp.removeSecondToLast();
       fixture.detectChanges();
       tickAnimationFrames(1);
-
       expect(fixture.debugElement.queryAll(By.css('p.fade')).length).toBe(1);
       expect(fixture.debugElement.queryAll(By.css('p')).length).toBe(4);
       fixture.debugElement
@@ -2219,6 +2226,7 @@ describe('Animation', () => {
       const fixture = TestBed.createComponent(TestComponent);
       const cmp = fixture.componentInstance;
       fixture.detectChanges();
+      tick(10);
 
       expect(fixture.debugElement.query(By.css('p.all-there-is'))).not.toBeNull();
       expect(fixture.debugElement.query(By.css('p.not-here.fade-out'))).not.toBeNull();