Proposal: New method to reorder child nodes

[josepharhar]

Summary

The goal of this method is to allow for the reordering of child nodes without the need to remove them and re-append them. Currently, reordering child nodes (by re-appending) causes several undesired side effects:

• Reloading of iframes
• Restarting of animations
• Loss of selection which cannot be restored in certain input types

This is a problem for several frameworks, including React, Preact, and Mithril.

Adding a new API vs changing existing APIs

Instead of adding a new API, we could change existing uses of DOM APIs to avoid reparenting. For example:

<div id=parent>
  <div id=firstchild></div>
  <div id=secondchild></div>
</div>
<script>
  parent.appendChild(firstchild);
</script>

In this case, you can see that the script wants to move firstchild past secondchild and doesn't necessarily want the browser to remove firstchild from the DOM and reparent it, so we could try to change appendChild to keep the parent throughout the DOM modification and avoid the loss of state.

However, I think a new API would be a better solution:

• Changing appendChild and other DOM modification methods would get more complicated due to difficulties defining and standardizing the existing behavior.
• If there are any sites out there which rely on the full reparenting logic, they could become broken.

API shape

I have some ideas for what this method could look like:

• Provide a full list with all children in desired order.
  parentNode.reorderChildren([childOne, childTwo, childThree])
• Move one child one spot forward or one spot backwards.
  childNode.movePastNextSibling()
childNode.moveBeforePreviousSibling()
• Move child before or after another child.
  childNode.moveBefore(otherChildNode)
childNode.moveAfter(otherChildNode)

I don't want to bikeshed too much on this until it really sounds like we will add a new method, but if any API shape seems particularly good please speak up so I can start prototyping.

Relationship to #808

@annevk is #808 blocking us from having a new way to reorder child nodes? That issue seems more concerned about insertions and mutation events which don't really seem to apply to reordering. Couldn't we just have new spec steps with no special functionality for iframes and scripts and no mutation events?

I made this issue based on feedback in this discussion: whatwg/html#5484

[annevk]

I think without fully understanding (and specifying) #808 it's hard to reason about how moving-within-a-parent should work. I.e., what side effects we need and do not need.

I think the most logical API that follows existing conventions would be parent.moveChildBefore(Node child, Node? referenceChild). However, if sole use case is reordering multiple children parent.moveChildren(Node...) probably makes more sense. Either way this also requires designing new mutation records as this is a new mutation primitive. And we should probably forbid firing (legacy) mutation events.

I would also like to see some more rationale as to why an arbitrary move (with both parents sharing a common root) is less feasible. What are the particular implementation challenges that we would only expose a more restricted move?

[dead-claudia]

I'm not convinced of spec complexity of modifying existing operations being that much higher (though it would technically be somewhat higher): #880 (comment)

[bathos]

If there are any sites out there which rely on the full reparenting logic, they could become broken.

The disconnectedCallback and connectedCallback reactions fire on custom elements when nodes are shuffled like this. It seems very unlikely to me that this would not break sites (including ours).

[josepharhar]

I would also like to see some more rationale as to why an arbitrary move (with both parents sharing a common root) is less feasible. What are the particular implementation challenges that we would only expose a more restricted move?

This is due to @rniwa's comments in whatwg/html#5484 against reparenting iframes without reloading them.

[josepharhar]

I think without fully understanding (and specifying) #808 it's hard to reason about how moving-within-a-parent should work. I.e., what side effects we need and do not need.

Moving within a parent should:

• Not fire mutation events
• Not run script inside of <script> elements, since that is supposed to be run on insertion
• Not fire loading/unloading events for iframes, since those are supposed to happen when the iframe is appended or removed.

Are there other types of side effects I'm not aware of?

[dead-claudia]

@josepharhar Why shouldn't it fire a mutation event of a new type? If a new method is added specifically for moving elements around, they can't possibly fire that mutation without invoking that previously-unknown method anyways, so in theory, a page would have to have its contents updated to experience breakage.

Also, I would expect it to invoke a new hook within custom elements to notify it of nodes being reordered. (This is very useful info for them, BTW, as libraries like A-Frame don't use shadow roots to render their data but otherwise need to know layout order at all times.)

As for the rest, I agree.

[josepharhar]

@josepharhar Why shouldn't it fire a mutation event of a new type? If a new method is added specifically for moving elements around, they can't possibly fire that mutation without invoking that previously-unknown method anyways, so in theory, a page would have to have its contents updated to experience breakage.

Yeah I presume that we would add new mutation signaling stuff for MutationObserver and whatever the equivalent is for custom elements (I'm not super familiar with either yet). I don't think that we should make new mutation events since they seem to be deprecated and people are interested in removing them from the web - I don't have historical context on this though. Right now I'm just trying to work through the relationship between this new proposed method and #808, which is interested in mutation events.
To clarify - when I say "mutation events," I am referring to this: https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Mutation_events

[rniwa]

I would really like to better understand what the use cases are. Could someone provide a concrete scenario (not just framework X does Y so they need it) in which this capability is desirable?

[josepharhar]

I would really like to better understand what the use cases are. Could someone provide a concrete scenario (not just framework X does Y so they need it) in which this capability is desirable?

@sebmarkbage @isiahmeadows @marvinhagemeister @developit could any/all of you elaborate on scenarios where state is lost when reordering child nodes? Links to issues would be greatly appreciated, as well as live examples if possible.

@isiahmeadows already made some live examples with four different frameworks listed in the description of #880. It does sound like appendChild has the desired behavior in that particular case though...?

[dead-claudia]

@josepharhar The transitions issue is that of this:

• Partial removal + reinsertion leaves unexpected transition state
• Full removal + reinsertion resets everything

Though now that I'm taking a closer look, I'm not sure movement semantics would help with transitions, as it reproduces even with simple add/remove. So my issue is independent of this.

Edit: Further confirmed that the transitions issue is independent of this.

[annevk]

This is due to @rniwa's comments in whatwg/html#5484 against reparenting iframes without reloading them.

I don't think that discussion was really settled though. Those arguments would apply to moving within a parent as well as you have to contend with subtrees and multiple elements there too.

[josepharhar]

I don't think that discussion was really settled though. Those arguments would apply to moving within a parent as well as you have to contend with subtrees and multiple elements there too.

@rniwa said that "Since a node can't have multiple parents, it needs to be disconnected at some point in some internal engine state. That's precisely what caused the problem."
When reordering children instead of reparenting them across the DOM, we will never have to change the pointer to the parent node, only the node's sibling pointers and the parent's first/last node pointers. @rniwa this does address your concern, right?

[rniwa]

I don't think that discussion was really settled though. Those arguments would apply to moving within a parent as well as you have to contend with subtrees and multiple elements there too.

@rniwa said that "Since a node can't have multiple parents, it needs to be disconnected at some point in some internal engine state. That's precisely what caused the problem."
When reordering children instead of reparenting them across the DOM, we will never have to change the pointer to the parent node, only the node's sibling pointers and the parent's first/last node pointers. @rniwa this does address your concern, right?

Well, it does address the previous concern but re-ordering nodes isn't something we've ever done so we'd likely encounter new list of issues with it. I'd still like to learn more about what specific use cases would require this new capability, and why careful manipulations of nodes in the user land won't suffice.

[annevk]

@rniwa what problem would be caused by disconnecting an <iframe> from its parent if we can also guarantee that no script would run until it is attached again?