[css-shared-element-transitions-1] Should createDocumentTransition start the transition

[vmpstr]

Currently the spec says that createDocumentTransition also start the transition, with no other way to start a transition.

I'm opening an issue here to decide, since we oscillated a little bit on this. The other alternative is createDocumentTransition just creates a transition object which can then be started at a later time via something like transition.start or transition.prepare.

To draw a parallel with web animations, I think it supports both Element.animate(), and animation = new Animation(...); animation.play(). Should this API also support both?

@jakearchibald @khushalsagar

[jakearchibald]

I think it should play on creation. I don't have a use-case for deferred playing, but we could add a constructor later if we discover we need it.

[khushalsagar]

Should we rename the API to document.transition() or document.transitionView() for parallel with the web animations API?

[vmpstr]

I think one of the problems with starting the transition as soon as we call createDocumentTransition is that it doesn't lend many opportunities for script to register for promise observations:

async function f() {
  let t = document.createDocumentTransition(...);
  t.ready.then(() => { /* synchronize my animation with the document one */ });
}

Could the ready promise be resolved already by the time we say .then? What I have to yield for some reason between create transition and ready.then?

It feels similar to something like

img.src = "...";
img.onload = () => { ... }

which as I understand it can cause us to miss onload, and the correct thing (onload before src) in the document transition world would not be possible

[khushalsagar]

All promises on ViewTransition are guaranteed to resolve asynchronously after calling createTransition. So it's guaranteed to not be resolved immediately when you call createTransition.

"What I have to yield for some reason between create transition and ready.then". Is there a use-case where that work can't be done before calling createTransition()?

[khushalsagar]

Summary from offline discussion: Makes sense to follow the WA-API model and have the document.createDocumentTransition API also start the transition by initiating the capture phase. Registering a callback on a promise after it has already resolve still invokes the callback so the pattern above is not an issue. And if the developer wants to ensure that they register a callback with the ready promise (to synchronize work with the first frame), they can do any work requiring yielding before calling the API. Note that the callback passed to createDocumentTransition is also an opportunity where the developer can do any async work before animations start.

Proposed Resolution: document.createDocumentTransition(...) immediately starts the transition. No need for a "play" function to be called after.