From 43b2ba1a97c7d511c8b5147042e120b0bfe86335 Mon Sep 17 00:00:00 2001 From: nemo Date: Mon, 16 Nov 2026 11:21:56 +0800 Subject: [PATCH] fix(docs): ignore child animation events in Promise helper --- docs/index.html | 6 ++- docsSource/sections/04-javascript.md | 7 ++- tests/javascript-helper.js | 65 ++++++++++++++++++++++++++++ 3 files changed, 76 insertions(+), 2 deletions(-) create mode 100644 tests/javascript-helper.js diff --git a/docs/index.html b/docs/index.html index f44fa664d..ef63af0da 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1149,14 +1149,18 @@

Usage with Javascript

// When the animation ends, we clean the classes and resolve the Promise function handleAnimationEnd(event) { + if (event.target !== node) return; + event.stopPropagation(); node.classList.remove(`${prefix}animated`, animationName); + node.removeEventListener('animationend', handleAnimationEnd); resolve('Animation ended'); } - node.addEventListener('animationend', handleAnimationEnd, {once: true}); + node.addEventListener('animationend', handleAnimationEnd); }); +

The handler ignores animation events that bubble up from children. It removes itself after the selected element finishes; using {once: true} would remove it on the first child event instead.

And use it like this:

animateCSS('.my-element', 'bounce');
 
diff --git a/docsSource/sections/04-javascript.md b/docsSource/sections/04-javascript.md
index 75097a660..e054fd2ea 100644
--- a/docsSource/sections/04-javascript.md
+++ b/docsSource/sections/04-javascript.md
@@ -38,15 +38,20 @@ const animateCSS = (element, animation, prefix = 'animate__') =>
 
     // When the animation ends, we clean the classes and resolve the Promise
     function handleAnimationEnd(event) {
+      if (event.target !== node) return;
+
       event.stopPropagation();
       node.classList.remove(`${prefix}animated`, animationName);
+      node.removeEventListener('animationend', handleAnimationEnd);
       resolve('Animation ended');
     }
 
-    node.addEventListener('animationend', handleAnimationEnd, {once: true});
+    node.addEventListener('animationend', handleAnimationEnd);
   });
 ```
 
+The handler ignores animation events that bubble up from children. It removes itself after the selected element finishes; using `{once: true}` would remove it on the first child event instead.
+
 And use it like this:
 
 ```javascript
diff --git a/tests/javascript-helper.js b/tests/javascript-helper.js
new file mode 100644
index 000000000..b01c0c05e
--- /dev/null
+++ b/tests/javascript-helper.js
@@ -0,0 +1,65 @@
+// Run with Node after installing @playwright/test and its browsers.
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const {chromium, firefox, webkit} = require('@playwright/test');
+const markdown = fs.readFileSync(
+  path.join(__dirname, '../docsSource/sections/04-javascript.md'),
+  'utf8',
+);
+const snippet = [...markdown.matchAll(/```javascript\n([\s\S]*?)```/g)]
+  .map((match) => match[1])
+  .find((code) => code.includes('const animateCSS ='));
+assert(snippet, 'Expected the documented animateCSS helper');
+
+(async () => {
+  for (const engine of [chromium, firefox, webkit]) {
+    const browser = await engine.launch();
+    try {
+      const page = await browser.newPage();
+      await page.setContent('
Child
'); + await page.addScriptTag({content: snippet + '\nwindow.animateCSS = animateCSS;'}); + const result = await page.evaluate(async () => { + const parent = document.querySelector('#parent'); + const child = document.querySelector('#child'); + let resolved = false; + let bubbled = 0; + document.body.addEventListener('animationend', () => bubbled++); + const completion = window.animateCSS('#parent', 'bounce').then(() => { + resolved = true; + }); + child.dispatchEvent( + new AnimationEvent('animationend', {bubbles: true, animationName: 'fadeIn'}), + ); + await Promise.resolve(); + const afterChild = { + resolved, + animated: parent.classList.contains('animate__animated'), + bubbled, + }; + parent.dispatchEvent( + new AnimationEvent('animationend', {bubbles: true, animationName: 'bounce'}), + ); + await completion; + parent.classList.add('animate__animated', 'animate__bounce'); + parent.dispatchEvent( + new AnimationEvent('animationend', {bubbles: true, animationName: 'bounce'}), + ); + return { + afterChild, + resolved, + listenerRemoved: parent.classList.contains('animate__bounce'), + }; + }); + assert.deepStrictEqual(result.afterChild, {resolved: false, animated: true, bubbled: 1}); + assert(result.resolved, 'The parent event should resolve the Promise'); + assert(result.listenerRemoved, 'The listener should be removed after the parent finishes'); + console.log(`PASS: ${engine.name()} child bubbling, parent completion and cleanup`); + } finally { + await browser.close(); + } + } +})().catch((error) => { + console.error(error); + process.exitCode = 1; +});