$emit poorly documented / breaks platform patterns

Version

2.6.10

Reproduction link

https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Creating_and_triggering_events#Event_bubbling

It is largely a documentation issue / missing feature, so linking to the relevant JS Event spec on MDN.

Steps to reproduce

Call $emit(‘my-event’) on a component while listening for it on a grandparent component.

What is expected?

I expect to be able to fire an event that is able to say “this event should bubble until stopped” and likewise, fire an event that is not cancellable as per the JS specs.

What is actually happening?

There is no way to do this in Vue presently.

---

It has come to my attention that $emit does not allow for, nor does it, bubble events… At the very least, this deviation from the platform event spec should be clearly documented, as nobody working in JS ever expects they should have to implement bubbling manually when working with Javascript events (which $emit is alludes to being syntactic sugar for by claiming they are Custom Events . Ideally, $emit would be expanded to allow for bubbling to be manually controlled by the developer (As JS intends them to be done) by accepting something akin to the customEventInit object, this would include the added benefit of enabling ALL JS event specific features in the $emit method…

[yyx990803]

The docs never said custom events behave like native events. They are modeled after Node.js’ EventEmitter. The docs never claimed custom events are anything similar to native DOM events, in fact, it explicitly warns you that they are different concepts.

The deprecated option was $dispatch, which indeed bubbles, but it was removed in 2.0. In our experience bubbling events between components easily lead to code that is hard to understand because the event bubbling flow is very implicit.

[ktiedt]

@yyx990803 That is certainly more useful information, considering the docs call the feature Custom Events (which is the name in EcmaScript) it would be very useful to document this information and reference EventEmitters…

As Custom Events in Javascript are optionally able to bubble (by default they do not) so even if Vue opted to wrap the Native event system (Which makes a ton of sense for a predominantly client-side framework) by adding the EventInit object param, it would not change the default behavior in Vue and it would keep it consistent with the platform which is it built on top of.