OWD project: update existing events

[foolip]

The way that events are documented on MDN and represented in BCD is not great, with different facets of events being treated as separate, and no clear entry point to learn about an event. Previous discussion on this is in mdn/browser-compat-data#7545 and mdn/browser-compat-data#12290.

To summarize the three main facets in terms of BCD entries / MDN pages that often co-exist:

• Event interfaces, such as ClipboardEvent
• *_event entries/pages such as cut_event (in this case there are three more pages)
• on* event handler attributes, such as oncut (these are often on many interfaces, often via the GlobalEventHandlers mixins)

Suggested work:

• Avoiding the duplication between *_event and on* entries and pages, and have a clear main page for each event such as "cut". While element.addEventListener('cut', handler) and element.oncut = handler aren't exactly the same and can have different browser support, I think we should think of this as one feature, which could have partial support.
• Get rid of the last mixins: GlobalEventHandlers and WindowEventHandlers (Reorganize GlobalEventHandlers and WindowEventHandlers mixin data mdn/browser-compat-data#12290)
• Ensure the correct linkage between events and their interface, so that one can always find the right interface for an event ("cut" → ClipboardEvent and ClipboardEvent → "cut" + "copy" + "paste")

[Elchi3]

Thanks for filing a project proposal for improvements of MDN's event docs! I agree event docs need work and the items you suggest are good issues to look into.

I started https://github.com/mdn/content/discussions/9098 to discuss your first suggested work item. If a specific proposal can reach consensus there, work could start.

I will look at your other suggested work items, too, but they seem not blocked by any prior discussion.

[ddbeck]

@Elchi3 and I chatted about this idea earlier today. I like this idea a lot, but, if it's accepted, I'd like to sugest a couple of work items so that this can fit in with other content organization, structure, and tooling work:

• Uniquely identifying this kind of page, among others (e.g., a page type name and version or date or something—perhaps existing event pages are api-event-1.0 and these are api-event-2.0 or somesuch—that could be recorded in frontmatter to show an author's intent to follow this new convention)
• Writing a detailed specification for the page type (e.g., describing expected titles, sections, etc.) so that authors not directly involved in this effort can determine whether they're producing content that's congruent with it

[wbamberg]

While we are doing this (and also related to defining the event page type) I'd love to make the tables:

...not be hardcoded, but built out of metadata. Maybe webref has or could have the data, even.

[foolip]

@wbamberg I like that idea. Unfortunately, most of that isn't possible to derive from specs automatically AFAICT, as the bubbles/cancelable/interface bits are almost always spelled out using prose.

The relevant event handler properties probably could be derived given just some basic hard-coded facts about things bubble, i.e. knowing that events bubble through Element nodes though a Document and finally a Window. Without that knowledge, it would be hard to tie api.Element.mouseover_event to api.Window.onmouseover, for example.

[saschanaz]

Data about events using more specific event interfaces (not just Event) are in @types/web generator (see "events" fields in addedTypes.jsonc and overridingTypes.jsonc), but no bubbles/cancelable unfortunately.

[jpmedley]

I'm still confused about something. I've heard this proposal described as 'one event page', It sounds like event interfaces will still exist, unless I'm misreading this. I think the confusion might be around the meaning of 'event'. I always (or try to) refer either 'event interface', 'event callback' or 'event handler'. If the proposal is simply to merge callbacks and handlers to 'event callback/handler' or some such thing, I'm completely on board with that.

The distinction between 'event interface' and 'event callback/handler' is the one I'm most concerned about. This morning I was reviewing Rachel's drafts for FontFaceSet. It has three callback/handlers, but they're all passed the same event interface type. In this case we're lucky that these were implemented as part of the same spec. I'm more concerned about events that are shared by interfaces and specs. The Event interface is very old, but it could be passed to a callback/handler that was implemented yesterday and the BCD would need to reflect that.

[wbamberg]

@jpmedley , although I didn't file this I will try to explain my understanding.

It sounds like event interfaces will still exist

Yes.

If the proposal is simply to merge callbacks and handlers to 'event callback/handler' or some such thing, I'm completely on board with that.

I think it is.

Consider, say, the "click" event. On MDN at the moment we have 2 pages describing this event:

• Element/click_event: this page describes the event as an abstraction really, inasmuch as there's no property or method called click_event. This page means "you can call addEventListener("click", ...) on this interface, and here's all the information about that".
• GlobalEventHandlers/onclick: this page describes a concrete property onclick that this interface has, that allows you to listen for click events.

The proposal is to combine these two pages.

There's also the object that get passed into the click event handler, which MDN says is a MouseEvent, and which MDN (and you) call an "event interface". As you say, this type could appear in the handlers for many different events, so it wouldn't make sense to try to fold it into the event pages. It's a completely separate thing.

[foolip]

Indeed, there's no suggestion to merge event interfaces into the event pages.

[jpmedley]

The other thing that had confused me was that I thought this decision had been made already, quite some time ago. I've been submitting APIs without the abstraction page for quite some time and had hired contractors do the same. No one ever complained.

[foolip]

Which is the abstraction page you've been skipping, foo_event or onfoo?

[jpmedley]

foo_event

I have this vague memory of Chris Mills telling me I didn't need to do them any more.

[foolip]

@jpmedley what do you do when there are lots of onfoo event handler properties?

@Elchi3 do you know who will be driving this issue this quarter? @queengooborg are continuing towards 100% complete API data in BCD, and have to update both kinds of entries. Deciding what happens in BCD sooner rather than later would be great.

[jpmedley]

I document the onfoo properties as I would any other property, and I document the event interfaces passed to them as I wold any other interface.

[foolip]

@jpmedley I see. If we get rid of GlobalEventHandlers by just documenting these properties like any others, it would result in both duplication (somewhat OK) but also a fair amount of useless documentation for event that the browser actually never fires. An example of this is document.onvolumechange, which exists, but the "volumechange" event is only ever fired at media elements and doesn't bubble, so this property is useless for web developers.