State-preserving atomic move integration

[domfarolino]

This PR is a supplementary PR to whatwg/dom#1307. It provides the HTML-overrides for the DOM Standard's "moving steps" extension, to allow pieces of the HTML Standard to react to atomic DOM moves without the use of the "insertion steps" or "removing steps", which by default, intentionally fail to preserve most state. The changes in this PR are inspired by the audit carried out in https://docs.google.com/document/d/1qfYyvdK4zhzloABKeh0K1lHPm-SpnEcsWEE9UdDuoMk/edit.

• At least two implementers are interested (and none opposed):
  • Chromium: https://issues.chromium.org/issues/40150299
  • WebKit: DOM State-preserving move (Node.prototype.moveBefore) WebKit/standards-positions#375
  • Gecko: DOM State-preserving move (Node.prototype.moveBefore) mozilla/standards-positions#1053
• Tests are written and can be reviewed and commented upon at:
  • https://github.com/web-platform-tests/wpt/tree/master/dom/nodes/moveBefore/tentative (need to mark as non-tentative)
• Implementation bugs are filed:
  • Chromium: https://issues.chromium.org/issues/40150299
  • Gecko: https://bugzilla.mozilla.org/show_bug.cgi?id=1923880
  • WebKit: https://bugs.webkit.org/show_bug.cgi?id=281223
• MDN issue is filed: Document the moveBefore() API mdn/mdn#613 & the impacts-documentation label
• The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

---

/custom-elements.html ( diff )
/embedded-content.html ( diff )
/form-control-infrastructure.html ( diff )
/form-elements.html ( diff )
/images.html ( diff )
/index.html ( diff )
/infrastructure.html ( diff )
/media.html ( diff )

[annevk]

I don't think you mentioned connectedMoveCallback everywhere connectedCallback is mentioned (and it's relevant).

• https://html.spec.whatwg.org/#custom-element-reactions
• https://html.spec.whatwg.org/#element-definition (this one seems especially important)
• It could do with some examples as well.

[noamr]

I don't think you mentioned connectedMoveCallback everywhere connectedCallback is mentioned (and it's relevant).

• https://html.spec.whatwg.org/#custom-element-reactions

This was there already, see https://whatpr.org/html/10657/custom-elements.html#custom-element-reactions ("When it is moved"). Not sure what's missing?

• https://html.spec.whatwg.org/#element-definition (this one seems especially important)

Done

• It could do with some examples as well.

Added non-normative note and an example

[domenic]

Seems like #10828 should be addressed here too?

[domfarolino]

Seems like #10828 should be addressed here too?

I think it needs to be done separately; I've uploaded #10840.

[smaug----]

"was"? So somehow this algorithm needs to get the old sibling as argument?

[domfarolino]

Hmm yes I guess, but the same goes for the removing steps which pre-date this PR and this API. I think fixing that is best left to a follow-up where we evaluate and perhaps overhaul the inputs to these steps.

For example, we could hack together a single parameter hot fix for this hook, but that's not ideal. Rather we need to do something consistent with what's desired in whatwg/dom#1288, where we teach the various hooks to take in a bundle of contextual information (ChildrenChange and ContainerNode in Chromium).

So I think I'd prefer to fix this and removing steps in one swoop after this, since it's easy, ensures nothing diverges, and this doesn't make the problem any worse. How does that sound?

Furthermore, I am actually skeptical that the spec has been doing the right thing in this case anyways. For example, Chromium doesn't track the "old next sibling" of the removed source, and trigger a relevant mutation on it. It triggers relevant mutations on all image children of the picture (https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/html/html_picture_element.cc;l=26-29;drc=a7096322ab1e5c9e70ae7b773faed492ed8461cb) so maybe implementations are compatible with that, and we can simplify all of this anyways. Regardless, I'd prefer it not block this.

[smaug----]

Fixing move and removing steps as a followup should be ok.

[annevk]

Please file an issue to track this. And ideally leave a source comment pointing to it.

[annevk]

#11113

[mfreed7]

Just noting #10954 (comment), which will require a small change to this PR if/when that one lands.

[theengineear]

First off, I want to say that moveBefore is going to be a major win in terms of functionality — so, thanks so much for working on it!

That said, I wanted to raise a concern about the following part of the specification:

<p>To opt in to a state-preserving behavior while <span
  data-x="concept-node-move-ext">moving</span>, the author can implement a "<code
  data-x="">connectedMoveCallback</code>". The existence of this callback, even if empty, would
  supercede the default behavior of calling "<code data-x="">disconnectedCallback</code>" and "<code
  data-x="">connectedCallback</code>". "<code data-x="">connectedMoveCallback</code>" can also be an
  appropriate place to execute logic that depends on the element's ancestors. For example:</p>

I find it confusing that the existence of a connectedMoveCallback method on a custom element changes the behavior of moveBefore. I think it will lead to custom element authors needing to write empty connectedMoveCallback() {/* do nothing, just here to prevent disconnectedCallback */} methods — and that feels like an anti-pattern. It will also lead to integration uncertainty for folks trying to leverage moveBefore.

By way of counter point, I don’t think the presence of an adoptedCallback lifecycle method changes how adoptNode works, just like the presence of connectedMoveCallback won’t change how the current insertBefore works.

Is there any flexibility in the specification at this point to change that? Or, would it be possible to understand the rationale on this decision in a little more detail?

[noamr]

First off, I want to say that moveBefore is going to be a major win in terms of functionality — so, thanks so much for working on it!

That said, I wanted to raise a concern about the following part of the specification:

<p>To opt in to a state-preserving behavior while <span
  data-x="concept-node-move-ext">moving</span>, the author can implement a "<code
  data-x="">connectedMoveCallback</code>". The existence of this callback, even if empty, would
  supercede the default behavior of calling "<code data-x="">disconnectedCallback</code>" and "<code
  data-x="">connectedCallback</code>". "<code data-x="">connectedMoveCallback</code>" can also be an
  appropriate place to execute logic that depends on the element's ancestors. For example:</p>

I find it confusing that the existence of a connectedMoveCallback method on a custom element changes the behavior of moveBefore. I think it will lead to custom element authors needing to write empty connectedMoveCallback() {/* do nothing, just here to prevent disconnectedCallback */} methods — and that feels like an anti-pattern. It will also lead to integration uncertainty for folks trying to leverage moveBefore.

This is by design. By adding this empty callback you signal that your component is capable of handling moves.

By way of counter point, I don’t think the presence of an adoptedCallback lifecycle method changes how adoptNode works, just like the presence of connectedMoveCallback won’t change how the current insertBefore works.

I don't think this analogy is valid. The presence of the callback doesn't change how ’moveBefore’ works, only which custom element callbacks are called.

Is there any flexibility in the specification at this point to change that? Or, would it be possible to understand the rationale on this decision in a little more detail?

It's late at this point.

To explain the rationale:
This is to avoid breaking existing components that might assume that an element cannot be moved, as custom elements predate moving. For example, a custom element might check the tag name of Its parent in its ’connectedCallback’. Before moving this was guaranteed to not change until the next ’disconnectedCallback’, so by calling both callbacks by default we simulate the old behavior to ensure components that rely on it, and by providing the new callback the component can open out from that.

[theengineear]

The presence of the callback doesn't change how ’moveBefore’ works, only which custom element callbacks are called.

@noamr — Thanks for the thoughtful response. I get your point from a “don’t break the web perspective”, but I am struggling to understand the mental model related to disconnectedCallback and moveBefore.

I had previously thought that part of the point of using moveBefore was to prevent disconnection. I.e., I use moveBefore on some set of elements to ensure that they don’t disconnect — why is it the case that using moveBefore doesn’t guarantee that disconnectedCallback is skipped? Perhaps I just need to fix my mental model to think about these lifecycle methods as maybeDisconnectedCallback and maybeConnectedCallback.

Either way, I’ll just bake connectedMoveCallback into a base element and I’m excited to see this stuff landing ❤️

[noamr]

The presence of the callback doesn't change how ’moveBefore’ works, only which custom element callbacks are called.

@noamr — Thanks for the thoughtful response. I get your point from a “don’t break the web perspective”, but I am struggling to understand the mental model related to disconnectedCallback and moveBefore.

It also fires the connectedCallback straight after. The mental model is that if your existing component is not prepared for a move, it should fall back to disconnecting and reconnecting, like a "restart" to make sure it didn't go into some funky state.

I had previously thought that part of the point of using moveBefore was to prevent disconnection. I.e., I use moveBefore on some set of elements to ensure that they don’t disconnect — why is it the case that using moveBefore doesn’t guarantee that disconnectedCallback is skipped? Perhaps I just need to fix my mental model to think about these lifecycle methods as maybeDisconnectedCallback and maybeConnectedCallback.

Either way, I’ll just bake connectedMoveCallback into a base element and I’m excited to see this stuff landing ❤️

[domenic]

In case it helps, a possible mental model might be that it disconnects and reconnects the vast majority of elements (e.g. <p>, <div>, <strong>, custom elements by default, ...). But for certain special elements it performs a move (e.g. <img>, <iframe>, <select>, <audio>, <video>, certain custom elements, ...).

[theengineear]

@domenic — That is actually super helpful! Makes much more sense to me that this works the way it does 🤘

[noamr]

@domenic — That is actually super helpful! Makes much more sense to me that this works the way it does 🤘

Thanks for asking for clarifications, I will make sure this is reflected in documentation.