Add events compat data

[a2sheppy]

We need to have a place to place compatibility data for events. I propose we add a top-level "events" folder, inside which we place the JSON files for each event.

Because the same event can be used by multiple interfaces, sometimes with different event interfaces (Event vs KeyboardEvent for example), we need to decide how to handle these. In content, we have shifted to documenting all of these on one page, with sections for each of the various versions of the event.

For BCD purposes, I propose that each specification's version of the event be placed in a file named eventname-interfacename, and that they be referenced using the name event.eventname.interfacename.

So for the KeyboardEvent named keydown, the file would be keydown-KeyboardEvent.json and it would be referred to using the name event.keydown.keyboardevent (or event.keydown.KeyboardEvent if we use camelcased names).

One outstanding question: If two specifications use the same form of the event, should they share a BCD file, or use separate ones? Sharing is tempting for convenience, but what if they deviate over time?

[teoli2003]

Hi Sheppy,

tl;dr;
id: event.eventname.interfacename (interfacename camelcased)
folder and filename: api/events/eventname.json

Complete answer

Yes, I think that having an id: event.eventname.interfacename is the good way to go, as it makes easy to generate the BCD table on the event page.

For the naming of the files, I think we should have one file per eventname which each entry for the different interface in there.

So keydown.json will contain an entry for event.keydown.KeyboardEvent and eventually another for event.keydown.OtherInterface

About your outstanding question, I think it isn't a problem: we don't document specs, we document implementation, so if 2 specs are incompatible, we document what is implemented.

[a2sheppy]

So keydown.json will contain an entry for event.keydown.KeyboardEvent and eventually another for event.keydown.OtherInterface

I concur. That's my preference. I think it will be easier to manage, and more in keeping with how we're moving toward doing the same in the documentation.

I take it, then, that the actual JSON would have something like:

{
  "event": {
    "Event": {
      "__compat": {
        ...
      }
    },
    "MediaStreamEvent": {
      "__compat": {
        ...
      }
    }
  }
}

The main question I have is about "event" as the top level name there; it seems incongruous given that what you're looking at are actually event targets. Should that be "target" or "interface" instead?

[mdittmer]

What's the rationale for separating event targets from APIs? I was just thinking about how EventTarget and its subclasses manifest as interfaces from a developer's perspective.

[a2sheppy]

@mdittmer - This isn't actually about event targets but about the events themselves. This is strictly about organizing the events, given that events by the same name can have different contents and meanings depending on which API they're used by. For example, the "close" event is used by WebRTC, WebSockets, IndexedDB, HTML DOM, and potentially others, and thus needs to be covered by the JSON in a way that allows us to identify which target the event is intended for, given that the event may have different contents.

We don't need to, and should not, I think, actually allow sub-features in the events JSON. The event interface names and the mdn_url referencing the event documentation should be enough, I think.

Sheppy

[Elchi3]

Here's a list of event pages that currently store compat information.

1. Web/Events/Activate
2. Web/Events/addtrack
3. Web/Events/afterscriptexecute
4. Web/Events/animationcancel
5. Web/Events/audioprocess
6. Web/Events/audiostart
7. Web/Events/auxclick
8. Web/Events/beforeunload
9. Web/Events/blur
10. Web/Events/boundary
11. Web/Events/bufferedamountlow
12. Web/Events/cancel
13. Web/Events/change
14. Web/Events/close
15. Web/Events/complete
16. Web/Events/compositionend
17. Web/Events/compositionstart
18. Web/Events/compositionupdate
19. Web/Events/contextmenu
20. Web/Events/copy
21. Web/Events/cut
22. Web/Events/datachannel
23. Web/Events/dblclick
24. Web/Events/devicechange
25. Web/Events/deviceorientation
26. Web/Events/DOMContentLoaded
27. Web/Events/DOMMouseScroll
28. Web/Events/dragenter
29. Web/Events/dragexit
30. Web/Events/dragleave
31. Web/Events/dragstart
32. Web/Events/drop
33. Web/Events/end_(SpeechRecognition)
34. Web/Events/error_(SpeechSynthesis)
35. Web/Events/focusin
36. Web/Events/focusout
37. Web/Events/gesturechange
38. Web/Events/gestureend
39. Web/Events/gesturestart
40. Web/Events/gotpointercapture
41. Web/Events/hashchange
42. Web/Events/icecandidate
43. Web/Events/iceconnectionstatechange
44. Web/Events/identityresult
45. Web/Events/idpassertionerror
46. Web/Events/idpvalidationerror
47. Web/Events/input
48. Web/Events/languagechange
49. Web/Events/lostpointercapture
50. Web/Events/message
51. Web/Events/message_(ServiceWorker)
52. Web/Events/messageerror
53. Web/Events/mousemove
54. Web/Events/mouseup
55. Web/Events/mousewheel
56. Web/Events/MozMousePixelScroll
57. Web/Events/negotiationneeded
58. Web/Events/nomatch
59. Web/Events/open
60. Web/Events/pause_(SpeechSynthesis)
61. Web/Events/pointercancel
62. Web/Events/pointerenter
63. Web/Events/pointerleave
64. Web/Events/pointermove
65. Web/Events/pointerout
66. Web/Events/pointerover
67. Web/Events/pointerup
68. Web/Events/popstate
69. Web/Events/resourcetimingbufferfull
70. Web/Events/result
71. Web/Events/resume
72. Web/Events/search
73. Web/Events/selectionchange
74. Web/Events/selectstart
75. Web/Events/signalingstatechange
76. Web/Events/soundend
77. Web/Events/soundstart
78. Web/Events/start_(SpeechSynthesis)
79. Web/Events/timeout
80. Web/Events/tonechange
81. Web/Events/touchcancel
82. Web/Events/touchend
83. Web/Events/touchstart
84. Web/Events/transitioncancel
85. Web/Events/transitionrun
86. Web/Events/transitionstart
87. Web/Events/unhandledrejection
88. Web/Events/visibilitychange
89. Web/Events/vrdisplayactivate
90. Web/Events/vrdisplaydeactivate
91. Web/Events/vrdisplayfocus
92. Web/Events/vrdisplaypresentchange
93. Web/Events/webglcontextcreationerror
94. Web/Events/webglcontextrestored
95. Web/Events/wheel

[Elchi3]

https://developer.mozilla.org/en-US/docs/Web/Events/close is in fact an extreme example and I don't like how the documentation is done there.

I don't know much about how MDN readers use event pages. I guess somewhere you have a "close" fired and then you want to read about it. However, the "close" page has not much information, no code samples, no details about each of the various close events.

Pages where there is only one event described, like https://developer.mozilla.org/en-US/docs/Web/Events/webglcontextcreationerror, are better imo, but the info is also similar to say the info on https://developer.mozilla.org/en-US/docs/Web/API/WebGLContextEvent.

So, I think "collection pages" like "close" are not really useful, except for pointing to pages where each of the close events is described in more details. So, if I were to document "close" events I would create something like:

• Web/Events/close (disambig page, almost what we have right now)
• Web/Events/close_HTMLDialogElement
• Web/Events/close_IDBDatabase
• Web/Events/close_RTCDataChannel
• Web/Events/close_WebSocket

For browser compat data, we then either have the data in an own tree and by target interface like this (events/targetInterface.json is the file):

• events.HTMLDialogElement.close
• events.IDBDatabase.close
• events.RTCDataChannel.close
• events.WebSocket.close
• events.HTMLCanvasElement.webglcontextcreationerror
• events.HTMLCanvasElement.webglcontextlost
• events.HTMLCanvasElement.webglcontextrestored

Or, we add events to the target interfaces directly, say like this (api/targetInterface.json is the file):

• api.HTMLDialogElement.events.close
• api.IDBDatabase.events.close
• api.RTCDataChannel.events.close
• api.WebSocket.events.close
• api.HTMLCanvasElement.events.webglcontextcreationerror
• api.HTMLCanvasElement.events.webglcontextlost
• api.HTMLCanvasElement.events.webglcontextrestored

[a2sheppy]

OK, that makes sense. I still personally like them better on one page but I can see the issues you raise are legitimate ones, too. :)

If we make this change, we will also need to change the {{event}} macro to accept an additional parameter specifying the target interface name. Except it already accepts several optional parameters, and tacking the interface name to the end is really awkward.

So I propose we create a new macro to replace it, called perhaps {{EventXRef}}, with syntax like so:

{{EventXRef(eventname, targetinterface, text, anchor)}}

Examples:

{{EventXRef("negotiationneeded")}}
{{EventXRef("close", "HTMLDialogElement")}}
{{EventXRef("close", "WebSocket", "Usage note", "additional information")}}

Only the first parameter, eventname, is required. Additional behavior notes:

• If the text parameter is included, the text should not be wrapped in a <code> block; otherwise it is.
• Process the anchor to convert it into a valid ID before using it; that means converting spaces to underscores, stripping out or escaping special characters, etc. Exactly like we do for the {{anch}} macro, I think.

[Elchi3]

We've started refactoring the event docs, please see: mdn/sprints#685 (and discuss docs refactoring plans there)

As for adding events to this repo, we're now about to install them under "targetInterface.eventname_event". See the first two PRs on this:

#3469
#3420

I'm leaving this issue open until we're done refactoring and events compat data has been migrated.

[Elchi3]

All legacy compat tables for events have been migrated and we have a convention for adding more in the future. Thanks everyone who was involved with this work.