Browser-compat-data: Representing support of events

[foolip]

Understanding and communicating the support of events in implementations is complicated. Taking the "keydown" event an example, there are many different facets of it:

• Event type: will an event with type "keydown" be created and fired by the browser?
  
  
  
  • Where these foo_event should be isn't always clear or consistent. Example: cut_event vs. oncut
  
  
• Event interface: does that event use the KeyboardEvent interface?
• Event handler IDL attribute: is the onkeydown IDL attribute supported, and on which interfaces?
  
  
  
  • HTML defines GlobalEventHandlers, but such EventHandler attributes are defined on most interfaces inheriting from EventTarget.
  
  
• Event handler content attribute: is the onkeydown content attributes supported, and on which elements? Both HTML and SVG define event handler content attributes:
  
  
  
  • https://html.spec.whatwg.org/multipage/indices.html#ix-event-handlers
  
  
  • https://svgwg.org/svg2-draft/attindex.html#RegularAttributes
  
  

Unfortunately, all four facets can come apart:

• Events being fired but onfoo IDL attributes being missing (very common)
• The reverse situation, where onfoo is supported despite "foo" never being fired, also happens.
• Events being fired, but as Event and not a more specialized FooEvent.
• The event handler content attributes being missing (relatively rare, but happened historically)

These situations are generally not handled well in BCD, and because only event interface and event handler IDL attribute can be detected with simple feature detection, it's often come up in https://github.com/mdn/browser-compat-data/issues/6369.

What I believe we need:

• Guidelines for where foo_event entries should be and what they communicate to data consumers.
• Guidelines or agreement on how to communicate a mismatch between especially cut_event and oncut entries.
  
  
  
  • Should there be notes on both, and what should they say?
  
  
  • Since this has happened so much but is usually fixed after some time, how do we avoid cluttering up the data with notes?
  
  

@Elchi3 @ddbeck @sideshowbarker @vinyldarkscratch

[Elchi3]

Yay events! :man_dancing:

I refactored the MDN events docs 2 years ago and I'm still familiar with the complicated situation. :)
(see https://docs.google.com/document/d/15F4ttUm7HSPKQNxKqzdiTHGTydDyFyVzyCVABbMHJKg/edit# for MDN thoughts)

---

To give an overview about MDN/BCD and events, with your example above:

"keydown" is an event type fired on multiple targets and so it appears on a few interfaces, like:

• api.Document.keydown_event -- https://developer.mozilla.org/en-US/docs/Web/API/Document/keydown_event
• api.Element.keydown_event -- https://developer.mozilla.org/en-US/docs/Web/API/Element/keydown_event

"keydown" is defined by an interface called "KeyBoardEvent":

• api.KeyBoardEvent -- https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent

"onkeydown" is an event handler property and it runs into the "mixin problem", so we have:

• api.GlobalEventHandlers.onkeydown -- https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onkeydown
  (if we were to flatten mixins, this would be api.Document.onkeydown and api.Element.onkeydown).

"onkeydown" is an event handler content attribute.

• For HTML, we have https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes but BCD only records data for html.global_attributes. One could image to add html.event_handler_content_attributes. This indicates support throughout all HTML elements. If support is partial or missing for a specific HTML element (we might have run into this for global attributes already), I would suggest to add something to that element. For example, html.element.dialog.onkeydown.
• For SVG, I don't know. MDN docs are sparse and not as well laid out as HTML.

---

For your specific scenarios I have some proposals (I might have practiced this already, but surely these aren't enforced guidelines)

Events being fired but onfoo IDL attributes being missing (very common)

api.Document.keydown_event and api.Element.keydown_event marked supported and api.GlobalEventHandlers.onkeydown marked unsupported.

The reverse situation, where onfoo is supported despite "foo" never being fired, also happens.

api.Document.keydown_event and api.Element.keydown_event marked unsupported and api.GlobalEventHandlers.onkeydown marked supported.

Events being fired, but as Event and not a more specialized FooEvent.

api.KeyBoardEvent marked as unsupported? Plus probably api.Document.keydown_event marked as partial support, with a note saying it is of type Event and not KeyBoard event.

The event handler content attributes being missing (relatively rare, but happened historically)

As said above, we may want to have html.event_handler_content_attributes analog to html.global_attributes. If it is only missing on certain elements, then more data could be added at say html.element.dialog.onkeydown.

---

I agree all this should be written down in extensive guidelines for events in BCD (and even more so for how to document all this on MDN). I think it comes down to agreeing to some of the more fine grained structures that I've outlined above. The events work we did 2 years ago started some of this, but it seems like it wasn't sufficient enough yet (or it is just very complicated and we should expand and add more clarity to events.)

[ddbeck]

In terms of composing the guidelines, it might help to start with some definitions for support on onevent, eventname_event and EventInterface. Very roughly:

• onevent is supported when "onevent" in target is true
• eventname_event is supported when the parent feature is a target of the event (that actually fires)
• EventInterface is supported when the interface is exposed as a global object
• onevent HTML attribute is suported when mumble something something

Then show some examples of oddities and how to represent them across the 3 or 4 corresponding features.

(I think the definitions correspond to what @Elchi3 is saying above, except the HTML bit, though I might be missing some subtleties.)

[sideshowbarker]

I’m just leaving a comment for now just to ack this and to say I’m not ignoring it, but it’ll be a while before I can free up some time＊ to think about it enough to be able to comment usefully.

＊ Lacking any other clear place to let others on the project know, I’ll just note here that my availability is gonna be a bit limited for while — the reason being that my partner and I just had a new baby girl last week (November 25th), and with two other preschool-age young ones at home already, most of my bandwidth right now is going towards time with the kids :)

[foolip]

Writing up guidelines for what the different types of entries are sounds great, and apart from the foo_event entries does not involve a whole lot of judgement calls, I think.

The main problem and the real reason I filed this issue is at the very end of my writeup:

Guidelines or agreement on how to communicate a mismatch between especially cut_event and oncut entries.

Carefully documenting the support for each will not, I think, lead to something that's good enough. Let's take https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition#Browser_compatibility as an example, a case where both kinds of entries exist for most of the events. (Ignore the prefix mess, fixed in https://github.com/mdn/browser-compat-data/pull/7554.)

As a reader, seeing "end event" and "onend" with the same support versions is conveying the same information twice: there's an "end" event that I can use. This is the normal case, which everything will be trending towards as the mismatches are discovered and fixed.

So what I wonder is whether we should move towards MDN conveying support for an event as a unified entry, with the details being hidden away unless there's something interesting going on. And what representation in BCD would help make that possible?

[Elchi3]

As a reader, seeing "end event" and "onend" with the same support versions is conveying the same information twice: there's an "end" event that I can use. This is the normal case, which everything will be trending towards as the mismatches are discovered and fixed.

Nowadays, this is probably normal, but historically MDN had documentation for both, events and event handlers, as it happened that there was only one and not the other. It still happens, I don't know how often though.

We updated the docs, so that both, event and handler, live together in the same reference page tree and now there is a bit of duplication indeed. (the writing guidelines say that event pages need to have a code example using addEventListener and the event handler pages should, well, use the even handler notation). I'd say this is an editorial policy that we could discuss in an MDN issue (sprints repo). Maybe there are better ways to document events in a more unified way with less pages?

So what I wonder is whether we should move towards MDN conveying support for an event as a unified entry, with the details being hidden away unless there's something interesting going on. And what representation in BCD would help make that possible?

Possibly. Usually BCD follows MDN structures, so either we get a discussion going how to document events in a unified way on MDN, or we first outline something for BCD that then informs MDN structures? Either way it seems like we should split out this issue and involve MDN.

[foolip]

Sounds good. What's the right place to raise editorial issues for MDN?

[Elchi3]

I talked to Chris and for now it is https://github.com/mdn/sprints/
(it might become https://github.com/mdn/content, discussion ongoing).

[ddbeck]

Every now and then something comes up that makes me think we ought to have a way of producing "synthetic" features that group together hierarchically dispersed features (e.g., onsomeevent, someevent_event, SomeEvent(), or some collection of related CSS properties or whatever).

[foolip]

@ddbeck that sounds like it might help with the events situation. Pairing reflected IDL attributes with their content attributes would also be sensible. Beyond that, are you thinking something as large as "flexbox" as one grouped feature? Would this end up with a feature hierarchy for the whole platform?

[ddbeck]

Would this end up with a feature hierarchy for the whole platform?

Yeah, this is the question that discourages me from putting effort into this. I don't want to have to maintain many hierarchies—it just seems like I ought to be able to query our data across our boundaries. Though maybe spec_urls could help with this sort of thing.