Add more explanation for Event concepts

[domenic]

In https://docs.google.com/document/d/1NFARs04-4U_2y6Ssw9Lqu1GMXBUM981-NO9PLJWifTI/edit# I wrote the following explanations for event features, which we might want to consider adding into the spec itself since they are reportedly clearer than what exists today. Kudos to @benjamingr for suggesting this.

Passive

Responding to the misconception that passive means "doesn't block browser paint":

This is not what passive means. Passive means that preventDefault() has no effect.

This allows the browser to perform some optimizations behind the scenes for certain events, because otherwise it has to synchronously wait for event dispatch during scrolling/etc. to see if JS code calls preventDefault(). With passive, it doesn't have to wait for event dispatch; it can just fire-and-forget the events.

isTrusted

Responding to the misconception that firing trusted events cause special trusted actions, like making :hover match:

There isn't such a thing as a trusted action.

I think you have the architecture a bit wrong. When the user hovers their mouse over something, the browser makes :hover match, and also dispatches a mousemove event. Because the browser dispatched it, the event is marked as trusted.

The architecture is not: the user moves their mouse, the browser dispatches a trusted mousemove event, and that trusted mousemove event causes :hover to match.

isTrusted is basically a legacy feature that means "did the runtime dispatch this event". It doesn't cause more special actions to happen.

preventDefault() / cancelation

Responding to a framing that stopImmediatePropagation() / stopPropagation() are a form of cancelation:

You may be conflating two things here.

Event cancelation is done with event.preventDefault(). This causes the caller of dispatchEvent() to recieve a false return value instead of true, which they may act on if they wish to cancel some in-progress process which the event was triggered from. (E.g., form submission.)

Stopping propagation with stopPropagation() and stopImmediatePropagation() is different. It modifies the propagation process, and would be a sub-bullet of "Propagation of events" IMO.

---

I'd be happy to turn these into a PR for further discussion, but could use a bit of advice as to where would be a good place to put them. Maybe https://dom.spec.whatwg.org/#introduction-to-dom-events, with cross-references from the domintro blocks ? Not sure.

[annevk]

There's also https://dom.spec.whatwg.org/#action-versus-occurance and https://dom.spec.whatwg.org/#observing-event-listeners.

Perhaps we should have a section following the introduction called "Design background" or some such that details these design decisions.

[domenic]

Good point; a lot of this is covered already. (Although I like some of my phrasing, and might want to add a version of it to the relevant sections.)

Maybe consolidating it would be helpful, but I think most important would be cross-linking those sections from the definitions of the relevant methods.

[benjamingr]

I would add the note about isTrusted here and the note about passive here or here because that's where it would have helped me.

Thanks again, I tried doing a nice thing (making a comparison to help Node.js) and ended up learning things I thought I already knew but didn't :] So I am very happy with both your help today and I think it would be useful to add these notes to the spec.

[pshaughn]

https://w3c.github.io/uievents/ is cited and still treats default actions as existing; there should maybe be some more explicit verbiage about how WHATWG disagrees with it.