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.

[foolip]

Also, there are events that still don't have event handler properties even in the spec, like https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event

[saschanaz]

A non-bubbling event is defined in GlobalEventHandlers? That's weird, sounds like it should be fixed...

[jpmedley]

This is a gap in my knowledge. Why does document.onvolumechange exist if developers can't set it to a callback function?

[wbamberg]

@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.

I think Florian is driving this project, but he's out until November 1st. Unless it's urgent I'd prefer to wait until he is back.

[jpmedley]

@wbamberg Do you mean how do I document them? I autogenerate them.

[foolip]

This is a gap in my knowledge. Why does document.onvolumechange exist if developers can't set it to a callback function?

Although I haven't gone back to find when and how it was decided, it seems deliberate HTML doesn't define any on* event handler attributes on any HTML*Element interfaces. Instead, they're all put in GlobalEventHandlers. I guess that it was originally because for events that bubble, you otherwise have to define those event handler attributes in lots of places. And for non-bubbling events, there would be cases where it's hard to decide where exactly the attributes should be added, like onerror for example. Instead, for simplicity I guess, all the attributes go everywhere.

The result is that some of them don't serve any purpose. I haven't checked if there are others beyond the (many) media element events.

[jpmedley]

I haven't checked if there are others beyond the (many) media element events.

How hard is it to get a list of these events? I need to add it to my app's muted list so that I stop reporting it and stop generating boilerplates for it.

[foolip]

@jpmedley it's not hard but fairly time consuming. What you'd do is to go through each event listed in https://html.spec.whatwg.org/multipage/webappapis.html#idl-definitions and search the spec for all the places that event is fired. If none of those places say that the event bubbles, then it's in this category of on* attributes sprinkled around where it's not useful.

Most of the events listed in https://html.spec.whatwg.org/multipage/media.html#mediaevents are like this. The exceptions are the ones that are also fired at something other than media elements, but being sure of which requires searching the spec. I'm sure that "error" and "resize" events are fired at other targets, but I don't think those other events bubble.

[jpmedley]

I think we're going to need a complete list. It's not just my tooling that needs it. I would think MDN would need to avoid documenting them. But if there are places in DevTools, stack traces, or wherever that developers can see them, we need to at least explain them.

Anyone want to help?

[foolip]

Depending on how events in BCD are restructured as part of this project, it may not be necessary to figure out which on* event handler properties are pointless, at least not up front. In particular, with the kind of approach suggested in mdn/browser-compat-data#7545 (comment), the on* properties would likely be moved one by one, and what's left at the end is the stuff that should be removed.

[jpmedley]

Let me rephrase. I need a list. I regularly generate boilerplates for missing pages and make them available to contributors. I need to not generate boilerplates for these events.

[Elchi3]

I made some lists here: https://github.com/mdn/content/discussions/9098#discussioncomment-1588303
However, it is time consuming to get all events from specs given they aren't in IDL or in some structure, see w3c/reffy#772 for an issue that aims to extract event data.

[Elchi3]

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.

I propose I start work by focusing on this aspect.

[jpmedley]

This seems reasonable to me. If we separated these, the two pages would be nearly identical. It's extra work with little gain.

[Elchi3]

We've agreed on a template for event pages: https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types/API_event_subpage_template (it takes into account doing something about the table and other things proposed in this issue).

The backlog for updating all events is here: mdn/browser-compat-data#14578

The event page type won't get done as part of this. I propose we fold it into a new project that deals with introducing page types.

So, I'll consider this done once mdn/browser-compat-data#14578 is resolved. Help appreciated, there are lots of events.

[dontcallmedom]

@foolip @Elchi3 when you get a chance, @tidoust and I have made good progress in collecting information about events from across specifications, with the current version of our work ready to be released as a package reviewable in https://raw.githubusercontent.com/w3c/webref/curated/ed/events.json with the guarantees described at https://github.com/w3c/webref/tree/curated/packages/events#guarantees

If you could review this and bring feedback in the webref repo on improvements either to the structure or the data itself, this would be useful in determining next steps for this effort.

[queengooborg]

Great news: GlobalEventHandlers has been demixed from BCD and mdn/browser-compat-data#14578 has been completed!

As mentioned a few times above, the linked issue was the criteria for completion of this project, however do we also want to include adding missing events, using the wonderful work from @dontcallmedom and @tidoust, as a part of this project's scope? Or do we want to create a new project for that?

[teoli2003]

\o/

I would rename this project "Demixing GEH" and create a new one for "Add missing events".

Not that there is practically no difference (same work), but sometimes it is good to mark progress and to keep projects smaller (read scoped).

Else we will never be able to celebrate.

🎉

[queengooborg]

Thanks @teoli2003! I brought this up during the SC call and it was generally agreed we should create a new project for adding the missing events and mark this one as completed. I will create the new project now and close this one! 🎉