Using startViewTransition with Lit

[KeithHenry]

I want to use the new View Transitions API with LitElement.

To use this you wrap the update to the DOM inside startViewTransition, something like this?

@customElement('my-component')
export class MyComponent 
  extends LitElement {

  render() {
    ...
  }
  
  private lifecycleRenderTransition;
  
  performUpdate() {
    if (!document.startViewTransition)
      return super.performUpdate();
    
    this.lifecycleRenderTransition = document.startViewTransition(() => {
      super.performUpdate();
    });
  }
}

By default this will just cause DOM changes to fade-transition in Chrome, Edge and Opera.

• Am I missing any potential gotchas here?
• Is this the right way to add it to the Lit lifecycle?
• Do I need to await super.performUpdate() or await transition.ready?
  (my guess is no as updateComplete is already exposed for that)
• Has anyone else tried using startViewTransition with LitElement?
• Are there any plans to implement this sort of thing in Lit or Lit Labs?

Edit following feedback

@lit-labs/motion PR: #4185

Updated playground

[ChrisShank]

Since LitElement/ReactiveElement batch DOM updates asynchronously my understanding is that you will want to await performUpdate or updateComplete in the startViewTransition.

this.lifecycleRenderTransition = document.startViewTransition(() => super.performUpdate());

https://developer.chrome.com/docs/web-platform/view-transitions/#async-dom-updates-and-waiting-for-content

[justinfagnani]

performUpdate() is only called after a previous update has completed, so you don't need to await updateComplete. You may need to await ViewTransition.finished though.

[ChrisShank]

Thanks for clarifying!

[justinfagnani]

I haven't used the view transition API (aside from editing your playground just now) yet, but this seems (edit: about) right!

We don't have any plans to add this yet. I would want to know a bit more - when is it good to enable, what's the cost, what kind of options do developers need and would the be pre-class or more dynamic and per instance, etc.

Being able to do this yourself with an override to performUpdate() shows the power of this our API shape here. I think this is a fine way to do it.

Edit: I think you need to wait for the transition to finish, or you could get additional calls to performUpdate before then:

@customElement('my-component')
export class MyComponent extends LitElement {
  
  private _viewTransition?: ViewTransition;
  
  async scheduleUpdate() {
    if (this._viewTransition !== undefined) {
      await this._viewTransition.finished;
    }
    return super.scheduleUpdate();
  }
  
  performUpdate() {
    if (!document.startViewTransition) {
      return super.performUpdate();
    }
    
    await (this._viewTransition = document.startViewTransition(() => {
      super.performUpdate();
    }));
    // clear the _viewTransition object so that we don't await a resolved Promise in a
    // future scheduleUpdate() call:
    this._viewTransition = undefined;
  }
}

This is enough code and subtle enough that I could see a mixin added to a labs package, maybe to @lit-labs/motion?

[johnyanarella]

Rather than awaiting the ViewTransition's finished promise, perhaps the key is to await the updateCallbackDone promise.

@customElement("my-component")
export class MyComponent extends LitElement {

  get viewTransition() { return this._viewTransition };
  private _viewTransition?: ViewTransition;

  // ...leaving viewTransition open to allow user code to await viewTransition's various promises

  async performUpdate() {
    if (!document.startViewTransition) {
      return super.performUpdate();
    }
    this._viewTransition = document.startViewTransition(async () => {
      await super.performUpdate();
    });
    await this._viewTransition.updateCallbackDone;
  }
}

(This can be expressed more succinctly, but I wanted to emphasize the various awaits for clarity.)

Per the View Transition Process this leaves the door open for customizing the animation through JavaScript via the ready and finished Promises.

This would require await this.updateComplete; before awaiting those, though. (Otherwise, those would be for the prior transition...)

[KeithHenry]

Thanks, and yeah I think the main question is the Lit DOM update lifecycle vs the view transition visible one - in particular the duration of the latter can be set by CSS.

I was looking at something like:

    private lifecycleRenderTransition: ViewTransition;
  
    async performUpdate() {
        if (!(document as DocumentWithTransition).startViewTransition)
            return await super.performUpdate();

        // If a previous update is done but still animating, wait for it to finish
        if (this.lifecycleRenderTransition)
            await this.lifecycleRenderTransition.finished;

        this.lifecycleRenderTransition = (document as DocumentWithTransition).startViewTransition(
            async () => 
                await super.performUpdate());
    }

This means performUpdate would be done as soon as the new DOM is ready (I could also await this.lifecycleRenderTransition.updateCallbackDonebut that should happen at the end ofsuper.performUpdate()`) but the transition animation could still be running. Then if we had another DOM update to process it would wait for that animation.

That has the risk of Lit seeming to stall because it's waiting for a long CSS animation, so another option is to cancel it with this.lifecycleRenderTransition.skipTransition() instead.

@justinfagnani I notice you use scheduleUpdate for this - is that better than waiting at the start of the already scheduled update?

PS... here are the TS defs I'm using:

interface DocumentWithTransition 
    extends Document {
    /** The startViewTransition() method of the View Transitions API starts a new view transition and returns a ViewTransition object to represent it.  
     When startViewTransition() is invoked, a sequence of steps is followed as explained in The view transition process. 
     @param callback A callback function typically invoked to update the DOM during the view transition process, which returns a Promise. The callback is invoked once the API has taken a screenshot of the current page. When the promise returned by the callback fulfills, the view transition begins in the next frame. If the promise returned by the callback rejects, the transition is abandoned.*/
    startViewTransition(callback: () => Promise<unknown>): ViewTransition;
}

interface ViewTransition { 
    /** A Promise that fulfills once the transition animation is finished, and the new page view is visible and interactive to the user. */
    finished: Promise<unknown>;

    /** A Promise that fulfills once the pseudo-element tree is created and the transition animation is about to start. */
    ready: Promise<unknown>;

    /** A Promise that fulfills when the promise returned by the document.startViewTransition()'s callback fulfills. */
    updateCallbackDone: Promise<unknown>;

    /** Skips the animation part of the view transition, but doesn't skip running the document.startViewTransition() callback that updates the DOM. */
    skipTransition(): void;
}

[KeithHenry]

@justinfagnani quick question - this._viewTransition.finished can error after the DOM has successfully update, with:

  async scheduleUpdate() {
    if (this._viewTransition !== undefined) {
      await this._viewTransition.finished;
    }
    return super.scheduleUpdate();
  }

That means an exception will block the next scheduled update - following this advice should we either skipTransition() or try-catch/try-finally?

[johnyanarella]

Perhaps, rather than exposing the ViewTransition the mixin could also introduce opt-in callbacks around the ready and finished steps for JS animation customization, and subsequently perform the promise cleanup you were suggesting?

[johnyanarella]

...and possibly also an opt-in start callback to await within the startViewTransition() call, for the "wait for other important content to be ready" escape hatch. 🤔

[johnyanarella]

From startViewTransition() Method Steps:

If document’s active view transition is not null, then skip that view transition with an "AbortError" DOMException in this’s relevant Realm.

NOTE: This can result in two asynchronous update callbacks running concurrently (and therefore possibly out of sequence): one for the document’s current active view transition, and another for this transition. As per the design of this feature, it’s assumed that the developer is using another feature or framework to correctly schedule these DOM changes.

Definitely some subtleties to this API!

[johnyanarella]

After further discussion with @ChrisShank, and looking at this with fresh eyes today, I'm not convinced the View Transitions API should generally be integrated inside a Lit custom element.

Consider:

• these are whole Document transitions, and there can only be one active at a time
• they capture "old" and "new" pseudo-elements snapshots around an expectation of settled whole Document states
• the lifecycle of a single Lit element does not (by design) wait for its children (or peers or ancestors, etc.)
• multiple Lit elements attempting to use startViewTransition() internally will compete & collide with each other

Many of the View Transitions API experiments floating around recently conflate generalized UI animation with the page layout transitions that this API seems best suited to address. While metaframeworks and routers have some overlapping concerns, a custom element probably just needs to provide some indication that its DOM output is settled (ex. .updateComplete) to allow external logic to orchestrate that element within a whole Document view transition.

To produce a visually complete and coherent page level animation may require the startViewTransition() update callback to validate settled state across a variety of sources (are fonts loaded, are images loaded, are custom elements upgraded, are various scattered Lit elements whose properties were just set updateComplete, etc.)

This seems like it might be more of a concern for the Lit Router, which could potentially centralize control over the view transition. There might be a way to make this functionality composable by externalizing the scheduling to a single authority like that via collaborating APIs.

(For very constrained use cases, a custom element representing the whole page could also coordinate this internally as above and akin to getUpdateComplete(), but it would require the same concrete knowledge and awareness of page level specifics as could be represented in an externalized coordinating function or closure.)

[KeithHenry]

@johnyanarella Yeah, this shouldn't be baked in everywhere - it's something you'd add to the top level page control, or your routing. It would make sense in Lit Router, sure, but I'd still want to a way to do it outside of that.

You'd definitely have to account for it in the design of your controls, as it looks pretty janky if you reflow just after the anim.