Sprints: Refactor Drag & Drop events

[Elchi3]

This is a work item for #685.

Pages:

• [ ] https://developer.mozilla.org/en-US/docs/Web/Events/drag
• [ ] https://developer.mozilla.org/en-US/docs/Web/Events/dragend
• [ ] https://developer.mozilla.org/en-US/docs/Web/Events/dragenter
• [ ] https://developer.mozilla.org/en-US/docs/Web/Events/dragexit
• [ ] https://developer.mozilla.org/en-US/docs/Web/Events/dragleave
• [ ] https://developer.mozilla.org/en-US/docs/Web/Events/dragover
• [ ] https://developer.mozilla.org/en-US/docs/Web/Events/dragstart
• [ ] https://developer.mozilla.org/en-US/docs/Web/Events/drop

Here the targets are difficult, see https://html.spec.whatwg.org/multipage/dnd.html#dndevents
The pages itself mention Document and Element, which I think sound like reasonable targets.

[Elchi3]

So, here I'm hitting the same case as Will had with pointer events. The event handler properties are documented on a mixin page called GlobalEventHandlers:

https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/ondrag
https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/ondragend
https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/ondragenter
https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/ondragexit
https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/ondragleave
https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/ondragover
https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/ondragstart
https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/ondrop

The actual targets are Document and Element, so that's where web devs actually interact with them, but for spec authoring convenience the authors came up with GlobalEventHandlers to not duplicate the handlers in their texts. MDN followed this convenience and documented this non-observable mix-in as well. I'm unclear if web devs actually understand non-observable interfaces. It is explained on the GlobalEventHandlers page, but is it practical when looking things up?

See also my previous comment about GlobalEventHandlers here https://github.com/mdn/sprints/issues/949#issuecomment-464733445. I think we will hit this with many event pages and we should make a call on how we want to proceed.

@chrisdavidmills @wbamberg, do you have thoughts on this and https://github.com/mdn/sprints/issues/949#issuecomment-464733445? I'm afraid this is sort of opening the grand debate around "do we document mixins or not?" :-/

[Elchi3]

Part of me thinks that the event pages should be together with their "on" event handler pages.
Another part of me thinks that all this mix-in business is confusing and we should rather duplicate pages than to follow the specs.
I'm really torn here. Also no idea what to do now vs. what to do ideally when we have the time.

[chrisdavidmills]

Annoying as it is, I think the only thing we can do now is to leave the on... pages where they are, put the event pages below the interfaces they are fired on, and link both from the interface landing page as agreed.

If we try to start moving on... pages around now and deleting mixin landing pages, etc., that makes things inconsistent and opens up a rabbit hole below this work that we don't have time for.

We need to have agreement and a definite plan of what to do about mixin pages and then execute it, probably as part of the maintenance work we are doing this year. I'd be more than happy to duplicate pages and get rid of mixin pages, but we need to plan and get agreement first.

Florian, do you fancy taking that planning work on? ;-)

[Elchi3]

OK, so basically leave on... pages as is, but have event pages documented on both Element and Document now?

Generally, I think this whole situation boils down to us deeply understanding WebIDL, then derive and agree on structures for MDN docs that are useful for web developers.

That is, I can imagine to write a tool that accepts WebIDL and then spits out MDN URLs and BCD paths to create after we have looked into all sorts of types that WebIDL can have and formulated structure for them (observable interfaces, mixins, dictionaries, etc). Only then our API docs aren't of random structure anymore I suppose.

One rule we agreed on (I think) was to not have subpages for dictionaries, for example, but that decision alone wasn't straight forward to come to ;-)
So, yes, I can maybe take on planning some of this, but this is quite gigantic due to the WebIDL complexity, decision making, (user) research, and amount of API pages (5000+?).

[wbamberg]

the only thing we can do now is to leave the on... pages where they are, put the event pages below the interfaces they are fired on, and link both from the interface landing page as agreed.

This is what I've done in https://github.com/mdn/sprints/issues/949 and I agree, it's the best plan at the moment.

In the bigger picture: it might be worth some research to see whether people see things in terms of these mixins rather than just in terms of the actual objects they work with (e.g. Document, Element). I would be very surprised if they did though.

Assuming they don't, then I think abolishing the mixins and duplicating the event properties across the objects that implement then is a better approach.

About duplicating information when/if we do this: that's just like the conversation we have had about duplicating event pages that have multiple targets. Yes, there is duplication, but also differences: at least the examples and BCD can be different in the different pages.

[chrisdavidmills]

I think this all makes total sense.

[Elchi3]

About duplicating information when/if we do this: that's just like the conversation we have had about duplicating event pages that have multiple targets. Yes, there is duplication, but also differences: at least the examples and BCD can be different in the different pages.

I think this is a core finding (we found this before, but we now see it again thanks to the event work). I want to stress that I see this as a major argument against documenting mixins.

[Elchi3]

I have a question regarding the targets here. The MDN pages say the targets are Document and Element (the pages for pointer events said the same), but when you look at the specs or the Firefox webidl files, Element doesn't actually implement the GlobalEventHandlers mixin. See https://dxr.mozilla.org/mozilla-central/search?q=GlobalEventHandlers+ext%3Awebidl&redirect=false

So, my understanding would be that the targets here are:

• Window
• Document
• HTMLElement
• SVGElement
• (XULElement but we don't document this one)

If you type in devtools "Element.prototype.on" there is actually only "onfullscreenchange" and "onfullscreenerror" and no other event handler properties whereas when typing "HTMLElement.prototype.ond" you actually see all the drag and drop events (and pointer events, etc).

So, what do you think about this? @chrisdavidmills @wbamberg

[wbamberg]

Good, if depressing, catch, @Elchi3 . I suppose the _correct_ thing to do then is to have these events live off HTMLElement (and SVGElement). And that's also probably the least disruptive thing to do in terms of getting this project completed without opening too many worm-cans.

But I worry whether the correct thing to do is actually the most helpful thing to do. This feels like another version of the 'mixin debate'. Do most web developers care about the distinction between HTMLElement and Element, or know (or want to know) which methods and properties and events are on one versus the other?

[Elchi3]

Good, if depressing, catch, @Elchi3 . I suppose the _correct_ thing to do then is to have these events live off HTMLElement (and SVGElement). And that's also probably the least disruptive thing to do in terms of getting this project completed without opening too many worm-cans.

That is my thinking as well.

But I worry whether the correct thing to do is actually the most helpful thing to do. This feels like another version of the 'mixin debate'. Do most web developers care about the distinction between HTMLElement and Element, or know (or want to know) which methods and properties and events are on one versus the other?

I don't know tbh. Seems like speculation what is helpful and what not. Part of me also wants to understand and then teach the differences of these interfaces and event installations on different targets. At the moment it isn't very clear to me how these things differ when you install a drag event on say window or document or HTMLElement.
Also, it feels like we need to be more conscious where we put docs and how we arrange them if our content aims to be machine-readable and highly structured and at the same time useful (for some definition of "useful"/"helpful").

[chrisdavidmills]

The general rule should be to have multiple pages hanging off of all the different interfaces the event is fired on. So we can then have different BCD, and examples if the sensible examples would be different in different contexts. Sucks, but it is still less confusing than having them on weird mixins or made up constructs.

If you are not currently sure what the differences are between the different contexts they fire on, then for the moment I'd say just keep the pages generic for now, and then make a note to research these differences and follow up on them in a future sprint. For each one, it'd probably make sense to chat to a relevant engineer about what their feelings are, and get them to help with the explanations.

[wbamberg]

Do you think then that we should reopen https://github.com/mdn/sprints/issues/949 to move them under HTMLElement? (and redo the BCD?) I think we should although I'm reluctant to...

[Elchi3]

It sounds like we should bite the bullet and re-open.

[chrisdavidmills]

Agreed.

[Elchi3]

Back to Drag & Drop. I've moved the pages and added them to the Document listing:
https://developer.mozilla.org/en-US/docs/Web/API/Document#Drag_drop_events

https://developer.mozilla.org/en-US/docs/Web/API/Document/drag_event
https://developer.mozilla.org/en-US/docs/Web/API/Document/dragstart_event
https://developer.mozilla.org/en-US/docs/Web/API/Document/dragend_event
https://developer.mozilla.org/en-US/docs/Web/API/Document/dragover_event
https://developer.mozilla.org/en-US/docs/Web/API/Document/dragenter_event
https://developer.mozilla.org/en-US/docs/Web/API/Document/dragleave_event
https://developer.mozilla.org/en-US/docs/Web/API/Document/dragexit_event
https://developer.mozilla.org/en-US/docs/Web/API/Document/drop_event

Can you review this before I copy this and make pages for other targets (Window, HTMLElement, SVGElement).

The example is longer and the same throughout as it shows all drag and drop events in context. Do you think this is OK or should it be split up and only show the relevant code for the given event?

[wbamberg]

The example is longer and the same throughout as it shows all drag and drop events in context. Do you think this is OK or should it be split up and only show the relevant code for the given event?

I think it's OK to have a longer example, but I think if possible longer examples should be "live" (this is really the point of having a longer example, and long examples that you can't run are so much more likely to not work properly). Not to mention that examples that are one big blob of HTML with embedded JS and CSS are harder to read. Note that the copy in at least one of these page (https://developer.mozilla.org/en-US/docs/Web/API/Document/dragstart_event#Examples) has been converted to a live example, so perhaps that could be copied? It's a bit sad to duplicate the example across like 20 pages, but hey ho.

https://developer.mozilla.org/en-US/docs/Web/API/Document#Drag_drop_events

This should use code style for the <dt> elements, and alphabetize them.

https://developer.mozilla.org/en-US/docs/Web/API/Document/drag_event

These comments apply to more than one page:

• This includes "Default action" in the blue box, which most of the others don't. Is this optional?
• I think H2 "Example" should be "Examples" even when there's just one of them.
• the Demo link in See also is redundant, doubly so if the example is converted to live.

https://developer.mozilla.org/en-US/docs/Web/API/Document/dragstart_event

• The blue box should use th for the cells in column 1

https://developer.mozilla.org/en-US/docs/Web/API/Document/dragend_event

• The blue box has a different order here

https://developer.mozilla.org/en-US/docs/Web/API/Document/dragenter_event

The blue box includes "Target objects" as well here. Or did you keep this in intentionally, because it's an unusual value? If so I think it would be better to note that outside the table.

[Elchi3]

I think it's OK to have a longer example, but I think if possible longer examples should be "live" (this is really the point of having a longer example, and long examples that you can't run are so much more likely to not work properly). Not to mention that examples that are one big blob of HTML with embedded JS and CSS are harder to read. Note that the copy in at least one of these page (https://developer.mozilla.org/en-US/docs/Web/API/Document/dragstart_event#Examples) has been converted to a live example, so perhaps that could be copied? It's a bit sad to duplicate the example across like 20 pages, but hey ho.

How about this: I've added the example to the drag event with code blocks and live demo and jsfiddle link: https://developer.mozilla.org/en-US/docs/Web/API/Document/drag_event
On other event pages I have referred this to the drag event page but also still to jsfiddle and showed the demo. https://developer.mozilla.org/en-US/docs/Web/API/Document/dragstart_event

https://developer.mozilla.org/en-US/docs/Web/API/Document#Drag_drop_events
This should use code style for the <dt> elements, and alphabetize them.

Done.

This includes "Default action" in the blue box, which most of the others don't. Is this optional?

I'm not sure. I guess the page author copied or modeled this blue box after the table in the spec https://html.spec.whatwg.org/multipage/dnd.html#dndevents
Do you think it is okay to leave it in?

I think H2 "Example" should be "Examples" even when there's just one of them.

I agree and I've changed it to be "Examples" throughout.

the Demo link in See also is redundant, doubly so if the example is converted to live.

I agree. Removed.

The blue box should use th for the cells in column 1

Oversight, sorry. Fixed now.

The blue box has a different order here

I've now made them all alphabetically.

The blue box includes "Target objects" as well here. Or did you keep this in intentionally, because it's an unusual value? If so I think it would be better to note that outside the table.

Yeah, I guess I left that there as it is special. I've now moved it after the summary sentence. Is that a better place?

[Elchi3]

The BCD is in https://github.com/mdn/browser-compat-data/pull/3542

[wbamberg]

Thanks @Elchi3 , these changes look good.