Events: bubbles and cancelable properties

[wbamberg]

When events were refactored in openwebdocs/project#61, the tables that list various properties of events (bubbles and cancelable) were dropped. Since then multiple issues have been raised on MDN asking to restore them. So this discussion is intended to be a place where we can reconsider this decision.

Event properties in the old pages

Before openwebdocs/project#61, the pages for events included tables listing some of their properties: whether the event bubbles, is cancelable, and the interface passed to event handlers:

See the page in archive.org at: https://web.archive.org/web/20210225074714/https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/invalid_event.

Current practice

When events were refactored in openwebdocs/project#61, these tables were removed.

Current practice is not documented in the template, but it seems de facto practice is that only if the event does not bubble or is not cancelable, to write that in prose (mdn/content#22198 (comment)). If the event bubbles or is cancelable, the fact is omitted, since that's the more common case.

The history of this and the reasoning are given in mdn/content#31137 (comment).

Issues

Since then several issues have been raised asking for this information to be reinstated, including at least:

• Event documentation no longer depicts "bubbles" information. content#22198
• Restore event init options tables (bubbles, cancelable, composed) content#32832
• Event references should list bubbles, cancelable, and composed values content#19590

mdn/content#31137 (comment) also has some relevant discussion.

I think there are a couple of separable issues: content and presentation.

Content

It's confusing to omit bubbles/cancels in the common case:

• we never know if it's omitted because the event is in the common case, or because the author forgot to add the sentence
• most readers won't know the convention to omit the common case, so if a page omits it, people won't think "this event obviously bubbles, because the page does not mention not bubbling", they will think "I don't know if the event bubbles, because the page doesn't say".

Presentation

Some people have said that the old table is more scannable than having the information in prose. Against this is the contention in mdn/content#31137 (comment) that it takes up a lot of space and pushes more important information below the fold. Against that though, the "Syntax" is arguably not very useful in these pages, and it is almost always pure cookie-cutter content.

[hamishwillee]

Good summary. IMO the current approach does not work, or we would not still be talking about this. I think the information should be in front page metadata, required for the event page type, and rendered either via a macro (or even better, fully automatically). The actual rendering can be a separate discussion, but if we're doing it automatically we can do it using a much more compact form than the old way.

[hamishwillee]

So, to be clear, the main issue is that Bubbles and Cancelable are no longer easy to find?

No, the main issue is that you can know if they bubble/cancel because that is added as (barely visible) prose.
But if you read a doc and it doesn't say anything, you can't assume anything - they might just have been omitted.

If we have the data one way or the other we can always choose to render it or not (IMO we should render it), but at least authors can see that the data has been recorded, and it is therefore reasonable to assume that if it is missing from prose this is deliberate.

[teoli2003]

From the reader's point of view: both bubble/cancle should be listed on the page (being supported or not). I would prefer in a standard automatizable way.
From the author's point of view: if we have it in webref, we should just read it from there. If not, in the frontmatter section sounds good to me.

Ideally, we should have a bot maintaining coherence (or a macro).

[dontcallmedom]

webref doesn't have cancelability information today; see some early exploration on this back in October 2021; if there is clear interest in consuming that data in MDN, this could be a motivation to restart that exploration; I don't think we have well-identified consumer of events data today, so we're not likely to focus on them without a clearly identified need :)

[dontcallmedom]

it turns out that it shouldn't too hard to get reasonable data landed in webref: w3c/reffy#1534

[tidoust]

Event cancelability is now captured in Webref data. 47 events get identified as cancelable (they have a "cancelable": true property in @webref/events). Other events should be viewed as non cancelable. Some entries have a "cancelable": false property, but that just means that the underlying spec explicitly mentions that the event is not cancelable. Many specs do not say anything in that case though.

[OnkarRuikar]

IMO the current approach does not work, or we would not still be talking about this.

Yeah, looks like people are looking for more discernible mechanism e.g badge or a table to get the info. Nobody ain't got no time to go through the prose to get to the info.

the information should be in front page metadata, required for the event page type, and rendered either via a macro (or even better, fully automatically)

Having it in front-matter would be more nit. We can't have front-matter as well as macro at the same time. With front-matter yari need to render it automatically. I think this should go in the proposed and upcoming header badge row. Either way whether front-matter or macros, yari will be involved and so this will take time to happen.

Also front-matter makes it easy to search in repo for the info. Current prose are not worded exactly the same and there are variations, so it is not possible to scan the repo for all the events that are not cancelable or bubbly. Can we have, for now, uniform status banners at the top?

---

From the author's point of view: if we have it in webref, we should just read it from there. If not, in the frontmatter section sounds good to me.
Ideally, we should have a bot maintaining coherence (or a macro).

With quick search for the prose following are number of non bubbly and canclelable events:

• This event does not bubble 5 occurrences
• This event is not cancellable 10 occurrences
• This event is not cancelable 16 occurrences
• This event is not cancellable and does not bubble 10 occurrences
• This event is not cancelable and does not bubble 127 occurrences

I think getting the info from webref will hit the same snag that we did for secure context info. In short, the specs don't meticulously documents the statuses in same machine readable manor and webref fails to acquire such stats.
For example, the webref doesn't track bubbles status for following events:

• RTCDTMFToneChangeEvent MDN says it doesn't.
• AudioScheduledSourceNode.ended_event MDN says it doesn't
• Web/API/AudioTrackList/addtrack_event
• etc.

When the cancelable PR lands it'll face the same issue. The webref is not a complete source of truth and for now we'll have to manually update front-matter. Or we could re-purpose mdn/data or create a new repo to track such statuses e.g. secure context, bubbles, cancelable, and other status that we were looking for in the past I don't remember now.

For HTMLElement.cancel_event prose on mdn says it doesn't bubble but webref says it does.

---

About cancellable vs cancelable, cancellable is the British spelling while cancelable is the US spelling. We need to convert all occurrences to the US spelling.

[dontcallmedom]

webref only documents "bubbles" for events that targets interfaces that are part of a bubbling tree; we could set bubbles: false on all other events, although that feels somewhat redundant.

There are likely bugs in webref data, but we have a reasonably good patching mechanism that allows to override data that cannot be extracted from specs.

[dontcallmedom]

I've filed w3c/webref#1212 re cancel event

[OnkarRuikar]

There are likely bugs in webref data, but we have a reasonably good patching mechanism that allows to override data that cannot be extracted from specs.

Webref didn't accept having patches for secure context status and decision was to keep it transparent with the specs. Are you willing to accept patch PRs from MDN side for bubbles and cancelable statuses?
If you accept then we'll be able to easily and quickly automate the statuses on mdn/content side rather than waiting for mdn/yari.

[dontcallmedom]

The situation for securecontext was different since this was patching content in a way that conflicted with what the specs say.

We will very happily accept patches that align data with what is specified (in general, including for events)

[dontcallmedom]

part of what's emerging in w3c/webref#1212 is probably relevant to this discussion: the cancel event bubbles on input elements, but doesn't on dialog elements (or at least so the spec says); this might point at challenges in representing this in the current single page on the event.

[estelle]

This discussion was discussed synchronously during the #writing-docs meeting held on April 16, 2024. Here are the (slightly edited for clarity) minutes from that portion of the meeting:

• Nobody talked about composable in the thread. Is the composable mentioned in this discussion about the composed property?
• YES, it is about the composed property. (Note: composable has since been removed from the title of this discussion)
• Should read “composed” rather than composable. This was included b/c it was brought up that way. WebRef doesn’t expose it, but it was in the old table but not “always”
• Let’s focus on bubbles and cancelable, remove composable.
• Was bubbles true/false or where it bubbles too? Answer: only T/F
• Cancellable has two chains. There’s an open issue about that. We should figure out how to expose these. What do readers care about, and what do they want to know. Bubbling to which interface? What does it mean. Bubbling chain is needed. The one for the UI … go up the tree to document or window, but in some other cases, serialports, it can bubble there too. That information should be looked at. They need the information because the developers needs to know the bubbling to know where to place the listener. Put it higher or lower. When the inheritance diagram was created, visualizing it, wondered how we want to present it? Do we want to do an SVG to demonstrate? Need to know what is interesting to the user. Maybe a bubbling chain is interesting.
• Why did we remove the boxes? Because most were bubbles: no, cancellable: yes. There’s a reason we removed the table, so bringing back the table as is is likely not the right solution.
• We already have enough frontmatter, but should it go there?
• It’s not information that needs to be an alert to the reader. It should be in the content as available, but not as super important.
• Just because information is included in a structured way (in frontmatter) it doesn’t mean that the information needs to be “alerted” to the user. bubbles and cancelable should not be a banner.
• CSS has a formal syntax. The important stuff is organized in a structured way, not as an alert.
• It should be structured, but there may not be enough information that is structured to create a table. Presenting the information is useful, but a table as the format may not be necessary.
• Issue is that pages currently omit important information. We don’t know if people forgot to include it, if it doesn’t bubble, it should be noted. Looks like information about bubbling or not bubbling is missing from the page.
• Represent bubbling chain if we have to.
• See SerialPort: connect event - this page has a section on bubbling with a heading. This is a way to represent. Just a data point. May not be the right way to present it, but it is a way to present it.
• Should we ask a broad range of developers what they think?
• Helpful to understand when knowing if something bubbles is important.
• If we add a “bubbling” section (like serialPort) do we also and cancelable and compose?
• Compose only works if bubbling. Doesn’t need a separate section.
• Is event type ever more than a sentence? We should include bubbling, cancellable, and event type in a table.
• Is the section going to be generic? If generic, we can automate it. By generic we mean the same sentences occur on each page; not custom content. Yes! Consistency is important. Represent information in a common and consistent way.
• Need to do research into one-off cases like serialport. One off cases can make the project more difficult. Also, can we get Dom (and Francois) to create a WebRef for us that is usable for our needs?
• Can’t be frontmatter (b/c that would be yari). Webref. Recreate macro system using github bots.

SOLUTION:

• Can’t rely on Yari. Needs to be within content only.
• We need to know what the one-offs are
• Need to know what the useful bits are that need to be included.

CONCLUSION: we do need something. Research is needed to know exactly what readers need.

Webref is not the complete source of truth. Dominique from webref is suggesting to use their patch mechanism to handle missed cases.

[dontcallmedom]

re "bubbling chain", that's something we've manually collected from specs: https://github.com/w3c/reffy/blob/2a37ea28cf99b30a54212f4f6b72f74b934b6175/src/lib/util.js#L970 - this would be very easy to publish along with webref data if useful (and we need to maintain that information to maintain the events data extraction, so its maintenance should be on par with events data maintenance)

[teoli2003]

So, it looks like we can obtain all the data needed automatically.

The main question is how we want to display this information to the user. There are several ways:

1. The table: we did this before the last change. It was taking a lot of place.
2. The text: it is what we are doing now. It takes less place but is difficult to find.
3. A section:
   We could have a section (near the bottom) called Event propagation that indicates if the event bubbles, and if so, how (= its position in the bubbling chain), or is cancelable.

We should try the 3rd option, but maybe there are others. Does anybody think of anything else?

[wbamberg]

I'm in favour of something very structured, to make the data points easy to find. The problem is always what to call these sections. I would not think of cancelability as part of propagation. We have for instance "Technical summary", that's roughly analogous, in HTML elements (https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th#technical_summary), and "Formal definition" in CSS properties (https://developer.mozilla.org/en-US/docs/Web/CSS/margin#formal_definition).

[OnkarRuikar]

I am in favour of adding the tables back. May be the readers really want the tables and the issue won't get put to rest till we do it. We could call the table Event summary.
If not then the option 3, a section, sounds good. We could call it ## Event propagation.

[chrisdavidmills]

I think "Technical summary" is OK, at least for starters. It is consistent with the HTML pages, and sound fairly intuitive to non-experts ("Some technical information is being summarized down there"), as opposed to "Event propagation" ("Hrm, I've got no idea what that means").

I think one of the most important things is to choose a name that's OK and test it, say on 20 pages, rather than getting bogged down at this stage. We can then test those pages on a section of target audience and see what they think, and change it if needs be before rolling it out sidewide.

[hamishwillee]

Probably it should be added using a macro placed by the user. I don't mind if there is a heading or not (in fact I would prefer there was not). If possible I'd love to have this added magically (i.e. not macro or any interaction from authors - to the end of the first section/before the first heading)

I'm not concerned about it being a table, and I think that is a good format because we're adding using a macro, and so we're not limited to user layout or default rendering of tables. We could do this:

What other information do we need here?

• I don't think we need the event handler
• What about the interface. I'd prefer not, but perhaps add an inheritance diagram to the Event type section?

[teoli2003]

From a user perspective, we need more than a Yes/No for bubbling.

For example, a "click" event that bubbles is documented on Element but is sent on the lowest HTML*Element (or SVG*Element, …) in the document tree, then goes up the page structure up to HTMLBodyElement and even toHTMLHtmlElement and Document (but not Window).

That means that the developer can put the event listener on any elements inside the document hierarchy containing the element that is clicked upon.

I think explaining (or linking to an explanation) is important as this is not obvious for beginners.

Something like:

Bubbles: Yes (sent on the specific Element that is acted upon, and bubbles up the document tree to the Document object if not intercepted).

Where:

• bubbles up the document tree will link to a beginner's introduction to the bubbling in the UI (I guess we have it in the LA)
• intercepted will link to an explanation of how to use stopPropagation() to actually prevent more bubbling.

Some bubbling events will bubble to Document, others to Window, and others will bubble only one level (non-UI cases).

For example, SerialPort.connect_event will have:

Bubbles: Yes (sent on the specific SerialPort that is acted upon and bubbles up to the Serial object encapsulating it if not intercepted).

One of the criteria that led to ditching the table back then was that bubbling is neither a single word (Yes/No) nor the interface it bubbles to. We can have a table (no strong feeling here), but I strongly believe we need a more consistent explanation than Yes/No for it to be useful to our users (both beginners and seasoned developers).