Technical review: Document cross-document view transitions #32723
Conversation
chrisdavidmills
requested review from
Elchi3 and
bsmth
and removed request for
a team
github-actions
bot
added
Content:CSS
github-actions
bot
added
size/xl
Co-authored-by: dawei-wang <dawei-wang@users.noreply.github.com>
chrisdavidmills
changed the title
|
This pull request has merge conflicts that must be resolved before it can be merged. |
| @@ -34,7 +34,7 @@ A {{domxref("ViewTransition")}} object instance. | |||
|
|
|||
| ### Basic usage | |||
|
|
|||
| In our [Basic View Transitions demo](https://mdn.github.io/dom-examples/view-transitions/), the `updateView()` function handles both browsers that do and don't support the View Transitions API. In supporting browsers, we invoke `startViewTransition()` to set off the view transition process without worrying about the return value. | |||
| In our [Basic SPA View Transitions demo](https://mdn.github.io/dom-examples/view-transitions/spa/), the `updateView()` function handles both browsers that do and don't support the View Transitions API. In supporting browsers, we invoke `startViewTransition()` to trigger the view transition process without worrying about the return value. | |||
There was a problem hiding this comment.
The link to https://mdn.github.io/dom-examples/view-transitions/spa/ doesn’t work.
There was a problem hiding this comment.
Yeah, these links won't work at present because the accompanying dom-examples repo update (see mdn/dom-examples#265) isn't yet merged. I'm going to merge them both together when the content work is finished; if I merged the dom-examples PR right now, it would break the existing demo links ;-)
|
|
||
| 1. A view transition is triggered. How this is done depends on the type of view transition: | ||
| - In the case of same-document transitions (SPAs), a view transition is triggered by passing the function that would trigger the view change DOM update as a callback to the {{domxref("Document.startViewTransition()", "document.startViewTransition()")}} method. | ||
| - In the case of cross-document transitions (MPAs), a view transition is triggered by initiating navigation to a new document. Both the current and destination documents of the navigation need to opt-in to the view transition by including a {{cssxref("@view-transition")}} at rule in their CSS with a `navigation` descriptor of `auto`. |
There was a problem hiding this comment.
On top of the opt-in, both documents also need to be on the same origin.
There was a problem hiding this comment.
excellent, thanks. I've added this detail to the page in question, and I've also noted it on the @view-transition reference page.
| 1. A view transition is triggered. How this is done depends on the type of view transition: | ||
| - In the case of same-document transitions (SPAs), a view transition is triggered by passing the function that would trigger the view change DOM update as a callback to the {{domxref("Document.startViewTransition()", "document.startViewTransition()")}} method. | ||
| - In the case of cross-document transitions (MPAs), a view transition is triggered by initiating navigation to a new document. Both the current and destination documents of the navigation need to opt-in to the view transition by including a {{cssxref("@view-transition")}} at rule in their CSS with a `navigation` descriptor of `auto`. | ||
| > **Note:** An active view transition has an associated {{domxref("ViewTransition")}} instance (for example, returned by `startViewTransition()` in the case of same-document (SPA) transitions). The `ViewTransition` object includes several promises, allowing you to run code in response to different parts of the view transition process being reached. See [Controlling view transitions with JavaScript](#controlling_view_transitions_with_javascript) for mroe information. |
There was a problem hiding this comment.
Typo:
| > **Note:** An active view transition has an associated {{domxref("ViewTransition")}} instance (for example, returned by `startViewTransition()` in the case of same-document (SPA) transitions). The `ViewTransition` object includes several promises, allowing you to run code in response to different parts of the view transition process being reached. See [Controlling view transitions with JavaScript](#controlling_view_transitions_with_javascript) for mroe information. | |
| > **Note:** An active view transition has an associated {{domxref("ViewTransition")}} instance (for example, returned by `startViewTransition()` in the case of same-document (SPA) transitions). The `ViewTransition` object includes several promises, allowing you to run code in response to different parts of the view transition process being reached. See [Controlling view transitions with JavaScript](#controlling_view_transitions_with_javascript) for more information. |
| - In the case of same-document transitions (SPAs), a view transition is triggered by passing the function that would trigger the view change DOM update as a callback to the {{domxref("Document.startViewTransition()", "document.startViewTransition()")}} method. | ||
| - In the case of cross-document transitions (MPAs), a view transition is triggered by initiating navigation to a new document. Both the current and destination documents of the navigation need to opt-in to the view transition by including a {{cssxref("@view-transition")}} at rule in their CSS with a `navigation` descriptor of `auto`. | ||
| > **Note:** An active view transition has an associated {{domxref("ViewTransition")}} instance (for example, returned by `startViewTransition()` in the case of same-document (SPA) transitions). The `ViewTransition` object includes several promises, allowing you to run code in response to different parts of the view transition process being reached. See [Controlling view transitions with JavaScript](#controlling_view_transitions_with_javascript) for mroe information. | ||
| 2. The API takes a screenshot of the current (old page) view. |
There was a problem hiding this comment.
Best to refrain from using screenshot but use snapshot instead. Also: it takes snapshots of the elements with a view-transition-name (that is not none) on them.
| 2. The API takes a screenshot of the current (old page) view. | |
| 2. On the current (old page) view, the API captures snapshots of elements that have a {{cssxref("view-transition-name")}} declared on them. |
There was a problem hiding this comment.
Good call; I've made your suggested change, but I've also grepped the rest of the PR to find other instances that needed changing.
| At this point, the view transition is about to run, and the {{domxref("ViewTransition.ready")}} promise fulfills, allowing you to respond by running a custom JavaScript animation instead of the default, for example. | ||
|
|
||
| 5. The old page view animates "out", while the new view animates "in". By default, the old view animates from {{cssxref("opacity")}} 1 to 0 and the new view animates from `opacity` 0 to 1, which creates a cross-fade. | ||
| 6. When the transition animation has reached its end state, the {{domxref("ViewTransition.finished")}} promise fulfills, allowing you to respond. |
There was a problem hiding this comment.
| 6. When the transition animation has reached its end state, the {{domxref("ViewTransition.finished")}} promise fulfills, allowing you to respond. | |
| 6. When the transition animations have reached its end state, the {{domxref("ViewTransition.finished")}} promise fulfills, allowing you to respond. |
There was a problem hiding this comment.
I have gone a bit further with the update:
When the transition animations have reached their end states...
|
|
||
| It is a replaced element, and therefore can be manipulated with properties such as {{cssxref("object-fit")}} and {{cssxref("object-position")}}. It has natural dimensions equal to the content's size. | ||
| It is a replaced element and therefore can be manipulated with properties such as {{cssxref("object-fit")}} and {{cssxref("object-position")}}. It has natural dimensions equal to the content's size. | ||
|
|
||
| The following default styling is included in the UA stylesheet: |
There was a problem hiding this comment.
The contents of the code block are out of date:
- It’s not
htmlbut:root - The
animation-delayis also inherited nowadays. - It also has the
-ua-mix-blend-mode-plus-lighteranimation applied
Sources:
- https://drafts.csswg.org/css-view-transitions-1/#ua-styles
- https://drafts.csswg.org/css-view-transitions-1/#ua-styles:~:text=to%20be%20replaced.-,Set%20capturedElement%E2%80%99s%20image%20animation%20name%20rule%20to%20a%20new%20CSSStyleRule%20representing%20the%20following%20CSS%2C%20and%20append%20it%20to%20document%E2%80%99s%20dynamic%20view%20transition%20style%20sheet%3A,-%3Aroot%3A%3Aview
| // Only transition to/from same basePath | ||
| // ~> SKIP! | ||
| if (!fromURL.pathname.startsWith(basePath)) { | ||
| e.viewTransition.skipTransition(); | ||
| } |
There was a problem hiding this comment.
This code was added to my own demos because I run multiple MPA demos on the same origin. This code can be removed.
| // Only transition to same basePath | ||
| // ~> SKIP! | ||
| if (!url.pathname.startsWith(basePath)) { | ||
| e.viewTransition.skipTransition(); | ||
| } |
There was a problem hiding this comment.
Sam remark as earlier: can be removed.
| // Remove VT-names from currently shown ones when already at a detail page | ||
| // @TODO: Figure out why I had to set to x and y here, instead of just '' | ||
| if (profilePagePattern.test(window.location.href)) { | ||
| document.querySelector(`main h1`).style.viewTransitionName = "x"; | ||
| document.querySelector(`main img`).style.viewTransitionName = "y"; | ||
| } | ||
|
|
||
| // Restore orig VT names after snapshots have been taken | ||
| // (This to deal with BFCache) | ||
| await e.viewTransition.finished; | ||
| document.querySelector(`#${profile} span`).style.viewTransitionName = "z"; | ||
| document.querySelector(`#${profile} img`).style.viewTransitionName = "w"; | ||
| if (profilePagePattern.test(window.location.href)) { | ||
| document.querySelector(`main h1`).style.viewTransitionName = | ||
| "profile-name"; | ||
| document.querySelector(`main img`).style.viewTransitionName = | ||
| "profile-avatar"; | ||
| } | ||
| } |
There was a problem hiding this comment.
As noted elsewhere: I’m not entirely happy with my code here as it has a nasty TODO still left :-/
There was a problem hiding this comment.
See earlier comments; I really liked your demo and would like to use it, but I can understand your concerns.
There was a problem hiding this comment.
The solution to my problem here was to set the viewTransitionName to "none" (instead of "") where you see "x","y","z","w".
This because I also had v-t-name’s in the CSS present, which the empty string doesn’t clear.
| - [Basic View Transitions SPA demo](https://mdn.github.io/dom-examples/view-transitions/spa/): A basic image gallery demo with view transitions, featuring separate animations between old and new images, and old and new captions. | ||
| - [Basic View Transitions MPA demo](https://mdn.github.io/dom-examples/view-transitions/mpa/): A sample two-page site that demonstrates usage of cross-document (MPA) view transitions, providing a custom "swipe up" transition when the two pages are navigated between. |
There was a problem hiding this comment.
These two links don’t work.
There was a problem hiding this comment.
They will when the dom-examples repo PR is merged.
|
|
||
| - : Specifies the effect this at-rule will have on the document's view transition behavior. Possible values are: | ||
|
|
||
| - `auto`: The document will undergo a view transition when taking part in a navigation, provided the navigation is same-origin, without cross-origin redirects, and its {{domxref("NavigateEvent.navigationType", "navigationType")}} is `traverse`, `push`, or `replace`. In the case of `replace`, the navigation must be initiated by a user interacting with the page content, not by a browser UI feature. |
| A string representing the type of navigation the {{domxref("NavigationActivation")}} relates to. Possible values are: | ||
|
|
||
| - `push`: A new location was navigated to, causing a new entry to be pushed onto the history list. | ||
| - `reload`: The {{domxref("Navigation.currentEntry")}} was reloaded. |
There was a problem hiding this comment.
I'd say "NavigationActivation.entry" instead of "Navigation.currentEntry"
|
|
||
| - `push`: A new location was navigated to, causing a new entry to be pushed onto the history list. | ||
| - `reload`: The {{domxref("Navigation.currentEntry")}} was reloaded. | ||
| - `replace`: The {{domxref("Navigation.currentEntry")}} was replaced with a new history entry. This new entry will reuse the same {{domxref("NavigationHistoryEntry.key", "key")}}, but be assigned a different {{domxref("NavigationHistoryEntry.id", "id")}}. |
| } | ||
| ``` | ||
|
|
||
| In the case of cross-document (MPA) transitions, the CSS needs to be included in the current _and_ destination documents. You might think that you can just target `::view-transition-old(root)` in the current document and `::view-transition-new(root)` in the destination document but this results in some strange behavior, plus you'll probably want to navigate in the other direction at some point, in which case the old current document will become the new destination document, and the old destination document will become the new current document. |
There was a problem hiding this comment.
The pseudo-elements only need to be present in the new document. Important to fix this.
| }); | ||
| ``` | ||
|
|
||
| ## Making cross-document transitions consistent with `rel="expect"` |
There was a problem hiding this comment.
I think the framing can be improved here. This is about making cross-document transitions consistent with render-blocking - and <link rel=expect> is a new component of that . See https://drafts.csswg.org/css-view-transitions-2/#waiting-for-stable-state for how I think this should be framed.
We basically want to wait until the state stabilizes, which means:
- Critical styles are loaded and applied
- Critical scripts are loaded and run
- enough of the HTML has been parsed (this is
<link rel=expect>)
There was a problem hiding this comment.
OK, gotcha. I've rewritten the section to hopefully match the framing in the spec. Let me know what you think.
|
|
||
| The **`PageRevealEvent`** event object is made available inside handler functions for the {{domxref("Window.pagereveal_event", "pagereveal")}} event. | ||
|
|
||
| During a cross-document navigation, it allows you to manipulate a related [view transition](/en-US/docs/Web/API/View_Transitions_API) (providing access to the relevant {{domxref("ViewTransition")}} object) from the document being navigated _to_, if a view transition was triggered by the navigation. |
There was a problem hiding this comment.
We should probably say a word about it regardless of view-transitions. It's equivalent to the first requestAnimationFrame() after a cross-document navigation.
There was a problem hiding this comment.
Can you expand on this? I'm not sure I 100% understand it. Are you saying that the event itself is equivalent to the first requestAnimationFrame() after a cross-document navigation?
There was a problem hiding this comment.
Yes exactly, it's roughly equivalent to something like this in the head:
function reveal() { ... }
/* This will fire in the first rendered frame after loading */
requestAnimationFrame(() => reveal());
/* This will fire if the page is restored from BFCache */
window.onpagehide = () => requestAnimationFrame(() => reveal());There was a problem hiding this comment.
I think readers will find this confusing, and ask questions about how requestAnimationFrame() is involved in the view transition. Is a rAF() call use internally to run the animation — is that what you are saying? And how is that useful to the developer? Can they so something beneficial with that?
There was a problem hiding this comment.
A common use case for this outside of view-transitions is something like a startup animation. You wait for the first frame (either the first frame at load or after BFCache-restore) using the pagereveal event. I'd say it would also be the appropriate place to do something like reporting a page view.
|
|
||
| The **`PageSwapEvent`** event object is made available inside handler functions for the {{domxref("Window.pageswap_event", "pageswap")}} event. | ||
|
|
||
| During a cross-document navigation, it allows you to manipulate the related [view transition](/en-US/docs/Web/API/View_Transitions_API) (providing access to the relevant {{domxref("ViewTransition")}} object) from the document being navigated _from_, if a view transition was triggered by the navigation. It also provides access to information on the navigation type and current and destination documents. |
There was a problem hiding this comment.
I'd start by saying that the pageswap event is fired when you navigate across documents, when the previous document is about to unload.
|
|
||
| The **`PageRevealEvent`** event object is made available inside handler functions for the {{domxref("Window.pagereveal_event", "pagereveal")}} event. | ||
|
|
||
| During a cross-document navigation, it allows you to manipulate a related [view transition](/en-US/docs/Web/API/View_Transitions_API) (providing access to the relevant {{domxref("ViewTransition")}} object) from the document being navigated _to_, if a view transition was triggered by the navigation. |
There was a problem hiding this comment.
Yes exactly, it's roughly equivalent to something like this in the head:
function reveal() { ... }
/* This will fire in the first rendered frame after loading */
requestAnimationFrame(() => reveal());
/* This will fire if the page is restored from BFCache */
window.onpagehide = () => requestAnimationFrame(() => reveal());| @@ -24,6 +24,7 @@ The following table lists some of the most important existing keywords. Every ke | |||
| | [`canonical`](#canonical) | Preferred URL for the current document. | Link | Not allowed | Not allowed | | |||
| | [`dns-prefetch`](/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch) | Tells the browser to preemptively perform DNS resolution for the target resource's origin. | External Resource | Not allowed | Not allowed | | |||
| | [`external`](#external) | The referenced document is not part of the same site as the current document. | Not allowed | Annotation | Annotation | | |||
| | [`expect`](#expect) | Allows the HTML visible for the user's initial view of the page to be render-blocked until it has been parsed and is visible. | Link | Not allowed | Not allowed | | |||
There was a problem hiding this comment.
I'm not sure what "visible" means here, expect is about the element being parsed (including its children)
There was a problem hiding this comment.
- This is an "Internal resource link", not a regular link
I
There was a problem hiding this comment.
What I meant here, is that the element whose ID is referenced in the rel element, e.g.
<link rel="expect" href="#lead-content" blocking="render" />Should wrap the content that will be visible when the page first loads, right? We will be blocking rendering of it until it is ready to be shown fully-parsed and ready, meaning that any cross-document view transition that is done on it will be consistent?
I've not phrased this text very well. The "and is visible." at the end of the sentence shouldn't be there for sure.
There was a problem hiding this comment.
I've played around with this and ended up with:
Allows the HTML at the top of the page to be render-blocked until it has been parsed so it will render consistently.
Does this explain it's purpose better?
| @@ -120,6 +121,8 @@ The `rel` attribute has no default value. If the attribute is omitted or if none | |||
| - : Relevant for the {{htmlelement('link')}} element both in the {{htmlelement('body')}} and {{htmlelement('head')}}, it tells the browser to preemptively perform DNS resolution for the target resource's origin. Useful for resources the user will likely need, it helps reduce latency and thereby improves performance when the user does access the resources as the browser preemptively performed DNS resolution for the origin of the specified resource. See [dns-prefetch](/en-US/docs/Web/Performance/dns-prefetch) described in [resource hints](https://w3c.github.io/resource-hints/). | |||
| - `external` | |||
| - : Relevant to {{htmlelement('form')}}, {{htmlelement('a')}}, and {{htmlelement('area')}}, it indicates the referenced document is not part of the current site. This can be used with attribute selectors to style external links in a way that indicates to the user that they will be leaving the current site. | |||
| - `expect` | |||
| - : Allows the HTML visible for the user's initial view of the page to be [render-blocked](/en-US/docs/Glossary/Render_blocking) until it has been parsed and is visible. See [Stabilizing page state to make cross-document transitions consistent](/en-US/docs/Web/API/View_Transitions_API/Using#stabilizing_page_state_to_make_cross-document_transitions_consistent) for more information. | |||
There was a problem hiding this comment.
It's just about render-blocking until that element is seen by the parser. The term "visible" is incorrect here
| @@ -120,6 +121,8 @@ The `rel` attribute has no default value. If the attribute is omitted or if none | |||
| - : Relevant for the {{htmlelement('link')}} element both in the {{htmlelement('body')}} and {{htmlelement('head')}}, it tells the browser to preemptively perform DNS resolution for the target resource's origin. Useful for resources the user will likely need, it helps reduce latency and thereby improves performance when the user does access the resources as the browser preemptively performed DNS resolution for the origin of the specified resource. See [dns-prefetch](/en-US/docs/Web/Performance/dns-prefetch) described in [resource hints](https://w3c.github.io/resource-hints/). | |||
| - `external` | |||
| - : Relevant to {{htmlelement('form')}}, {{htmlelement('a')}}, and {{htmlelement('area')}}, it indicates the referenced document is not part of the current site. This can be used with attribute selectors to style external links in a way that indicates to the user that they will be leaving the current site. | |||
| - `expect` | |||
| - : Allows the HTML visible for the user's initial view of the page to be [render-blocked](/en-US/docs/Glossary/Render_blocking) until it has been parsed and is visible. See [Stabilizing page state to make cross-document transitions consistent](/en-US/docs/Web/API/View_Transitions_API/Using#stabilizing_page_state_to_make_cross-document_transitions_consistent) for more information. | |||
There was a problem hiding this comment.
Important to note that it only render-blocks when supplemented with the blocking=render attribute.
| @@ -24,6 +24,7 @@ The following table lists some of the most important existing keywords. Every ke | |||
| | [`canonical`](#canonical) | Preferred URL for the current document. | Link | Not allowed | Not allowed | | |||
| | [`dns-prefetch`](/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch) | Tells the browser to preemptively perform DNS resolution for the target resource's origin. | External Resource | Not allowed | Not allowed | | |||
| | [`external`](#external) | The referenced document is not part of the same site as the current document. | Not allowed | Annotation | Annotation | | |||
| | [`expect`](#expect) | Allows the HTML visible for the user's initial view of the page to be render-blocked until it has been parsed and is visible. | Link | Not allowed | Not allowed | | |||
There was a problem hiding this comment.
- This is an "Internal resource link", not a regular link
I
|
This pull request has merge conflicts that must be resolved before it can be merged. |
|
removed myself as a reviewer. Pls add me back in when we get to editorial review time. |
| @@ -120,6 +121,12 @@ The `rel` attribute has no default value. If the attribute is omitted or if none | |||
| - : Relevant for the {{htmlelement('link')}} element both in the {{htmlelement('body')}} and {{htmlelement('head')}}, it tells the browser to preemptively perform DNS resolution for the target resource's origin. Useful for resources the user will likely need, it helps reduce latency and thereby improves performance when the user does access the resources as the browser preemptively performed DNS resolution for the origin of the specified resource. See [dns-prefetch](/en-US/docs/Web/Performance/dns-prefetch) described in [resource hints](https://w3c.github.io/resource-hints/). | |||
| - `external` | |||
| - : Relevant to {{htmlelement('form')}}, {{htmlelement('a')}}, and {{htmlelement('area')}}, it indicates the referenced document is not part of the current site. This can be used with attribute selectors to style external links in a way that indicates to the user that they will be leaving the current site. | |||
| - `expect` | |||
|
|
|||
| - : Allows the HTML at the top of the page to be [render-blocked](/en-US/docs/Glossary/Render_blocking) until it has been parsed so it will render consistently. Note that render-blocking occurs only when supplemented with the [`blocking="render"`](/en-US/docs/Web/HTML/Attributes/rel#blocking) attribute. | |||
There was a problem hiding this comment.
I think the wording here can be improved... Top of the page is perhaps not the term I would use. How about "Allows the page to be render blocked until the essential parts of the document are parsed" or something like that?
| @@ -24,6 +24,7 @@ The following table lists some of the most important existing keywords. Every ke | |||
| | [`canonical`](#canonical) | Preferred URL for the current document. | Link | Not allowed | Not allowed | | |||
| | [`dns-prefetch`](/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch) | Tells the browser to preemptively perform DNS resolution for the target resource's origin. | External Resource | Not allowed | Not allowed | | |||
| | [`external`](#external) | The referenced document is not part of the same site as the current document. | Not allowed | Annotation | Annotation | | |||
| | [`expect`](#expect) | Allows the HTML at the top of the page to be render-blocked until it has been parsed so it will render consistently. | Link | Not allowed | Not allowed | | |||
Description
Chrome 123/124 includes features required for developers to create cross-document View Transitions. This includes:
PageRevealEventinterfacepagerevealeventPageSwapEventinterfacepageswapeventNavigationActivationinterface@view-transitionat rule<link rel="expect">This PR adds content for all of these. In addition, it:
Related ChromeStatus entries:
Motivation
Additional details
Related issues and pull requests