From ba5f5f38b1e865215b3fb1e9731ce0dd64193c52 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Thu, 25 Jul 2024 13:04:39 -0400
Subject: [PATCH] chore: tweak event delegation docs (#12607)

---
 .../docs/02-template-syntax/02-basic-markup.md       | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/documentation/docs/02-template-syntax/02-basic-markup.md b/documentation/docs/02-template-syntax/02-basic-markup.md
index a97f8b84e6..b8e2632319 100644
--- a/documentation/docs/02-template-syntax/02-basic-markup.md
+++ b/documentation/docs/02-template-syntax/02-basic-markup.md
@@ -110,18 +110,18 @@ Because events are just attributes, the same rules as for attributes apply:
 - you can spread them: `<button {...thisSpreadContainsEventAttributes}>click me</button>`
 - component events are just (callback) properties and don't need a separate concept
 
-Timing-wise, event attributes always fire after events from bindings (e.g. `oninput` always fires after an update to `bind:value`). Under the hood, events are either listened to directly through `addEventListener`, or the event is delegated.
+Timing-wise, event attributes always fire after events from bindings (e.g. `oninput` always fires after an update to `bind:value`). Under the hood, some event handlers are attached directly with `addEventListener`, while others are _delegated_.
 
 ### Event delegation
 
-To reduce the memory footprint and increase performance, Svelte uses a technique called event delegation. This means that certain events are only listened to once at the application root, invoking a handler that then traverses the event call path and invokes listeners along the way.
+To reduce memory footprint and increase performance, Svelte uses a technique called event delegation. This means that for certain events — see the list below — a single event listener at the application root takes responsibility for running any handlers on the event's path.
 
-There are a few gotchas you need to be aware of when it comes to event delegation:
+There are a few gotchas to be aware of:
 
-- when you manually dispatch an event with the same name as one of the delegated ones, make sure to set the `{ bubbles: true }` option
-- when listening to events programmatically (i.e. not through `<button onclick={...}>` but through `node.addEventListener`), be careful to not call `stopPropagation` or else the delegated event handler won't be reached and handlers won't be invoked. Similarly, event listeners added manually and higher up the DOM tree will be invoked _before_ events that are delegated and deeper down the DOM tree (because the actual event reaction happens in the delegated handler at the root). For these reasons it's best to use `on` (which properly handles `stopPropagation`) from `svelte/events` instead of `addEventListener` to make sure the chain of events is preserved
+- when you manually dispatch an event with a delegated listener, make sure to set the `{ bubbles: true }` option or it won't reach the application root
+- when using `addEventListener` directly, avoid calling `stopPropagation` or the event won't reach the application root and handlers won't be invoked. Similarly, handlers added manually inside the application root will run _before_ handlers added declaratively deeper in the DOM (with e.g. `onclick={...}`), in both capturing and bubbling phases. For these reasons it's better to use the `on` function imported from `svelte/events` rather than `addEventListener`, as it will ensure that order is preserved and `stopPropagation` is handled correctly.
 
-The following events are delegated:
+The following event handlers are delegated:
 
 - `beforeinput`
 - `click`