Technical review: Document cross-document view transitions

files/en-us/web/api/document/startviewtransition/index.md

@@ -10,9 +10,9 @@ browser-compat: api.Document.startViewTransition
 
 {{APIRef("View Transitions API")}}{{SeeCompatTable}}
 
-The **`startViewTransition()`** method of the {{domxref("Document")}} interface starts a new view transition and returns a {{domxref("ViewTransition")}} object to represent it.
+The **`startViewTransition()`** method of the {{domxref("Document")}} interface starts a new same-document (SPA) [view transition](/en-US/docs/Web/API/View_Transitions_API) and returns a {{domxref("ViewTransition")}} object to represent it.
 
-When `startViewTransition()` is invoked, a sequence of steps is followed as explained in [The view transition process](/en-US/docs/Web/API/View_Transitions_API#the_view_transition_process).
+When `startViewTransition()` is invoked, a sequence of steps is followed as explained in [The view transition process](/en-US/docs/Web/API/View_Transitions_API/Using#the_view_transition_process).
 
 ## Syntax
 
@@ -24,7 +24,7 @@ startViewTransition(updateCallback)
 ### Parameters
 
 - `updateCallback` {{optional_inline}}
-  - : An optional callback function typically invoked to update the DOM during the view transition process, which returns a {{jsxref("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.
+  - : An optional callback function typically invoked to update the DOM during the SPA view transition process, which returns a {{jsxref("Promise")}}. The callback is invoked once the API has taken a snapshot 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.
 
 ### Return value
 
@@ -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.
 
 ```js
 function updateView(event) {

files/en-us/web/api/html_dom_api/index.md

@@ -235,6 +235,8 @@ The History API interfaces let you access information about the browser's histor
 - {{DOMxRef("HashChangeEvent")}}
 - {{DOMxRef("History")}}
 - {{DOMxRef("Location")}}
+- {{DOMxRef("PageRevealEvent")}}
+- {{DOMxRef("PageSwapEvent")}}
 - {{DOMxRef("PageTransitionEvent")}}
 - {{DOMxRef("PopStateEvent")}}
 

files/en-us/web/api/navigation_api/index.md

@@ -90,6 +90,8 @@ There are a few perceived limitations with the Navigation API:
   - : Event object for the {{domxref("Navigation/navigate_event", "navigate")}} event, which fires when [any type of navigation](https://github.com/WICG/navigation-api#appendix-types-of-navigations) is initiated. It provides access to information about that navigation, and most notably the {{domxref("NavigateEvent.intercept", "intercept()")}}, which allows you to control what happens when the navigation is initiated.
 - {{domxref("Navigation")}} {{Experimental_Inline}}
   - : Allows control over all navigation actions for the current `window` in one central place, including initiating navigations programmatically, examining navigation history entries, and managing navigations as they happen.
+- {{domxref("NavigationActivation")}}
+  - : Represents a recent cross-document navigation. It contains the navigation type and current and destination document history entries.
 - {{domxref("NavigationCurrentEntryChangeEvent")}} {{Experimental_Inline}}
   - : Event object for the {{domxref("Navigation/currententrychange_event", "currententrychange")}} event, which fires when the {{domxref("Navigation.currentEntry")}} has changed. It provides access to the navigation type, and the previous history entry that was navigated from.
 - {{domxref("NavigationDestination")}} {{Experimental_Inline}}

files/en-us/web/api/navigationactivation/entry/index.md

@@ -0,0 +1,36 @@
+---
+title: "NavigationActivation: entry property"
+short-title: entry
+slug: Web/API/NavigationActivation/entry
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.NavigationActivation.entry
+---
+
+{{APIRef("Navigation API")}}{{SeeCompatTable}}
+
+The **`entry`** read-only property of the {{domxref("NavigationActivation")}} interface contains a {{domxref("NavigationHistoryEntry")}} object representing the history entry for the inbound ("to") document in the navigation. This is equivalent to the {{domxref("Navigation.currentEntry")}} property at the moment the inbound document was activated.
+
+There are some cases in which either the from or entry NavigationHistoryEntry objects would not be viable targets for the traverseTo() method, as they might not be retained in history. For example, the Document can be activated using location.replace() or its initial entry could be replaced by history.replaceState(). However, those entries' url property and getState() method are still accessible.
+
+## Value
+
+A {{domxref("NavigationHistoryEntry")}} object.
+
+## Examples
+
+See the main {{domxref("NavigationActivation")}} page.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Navigation API](/en-US/docs/Web/API/Navigation_API)
+- [View Transitions API](/en-US/docs/Web/API/View_Transitions_API)

files/en-us/web/api/navigationactivation/from/index.md

@@ -0,0 +1,37 @@
+---
+title: "NavigationActivation: from property"
+short-title: from
+slug: Web/API/NavigationActivation/from
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.NavigationActivation.from
+---
+
+{{APIRef("Navigation API")}}{{SeeCompatTable}}
+
+The **`from`** read-only property of the {{domxref("NavigationActivation")}} interface contains a {{domxref("NavigationHistoryEntry")}} object representing the history entry for the outgoing ("from") document in the navigation.
+
+## Value
+
+A {{domxref("NavigationHistoryEntry")}} object, or `null` if the outgoing document is:
+
+- Not same origin as the inbound document.
+- The initial `about:blank` document.
+
+## Examples
+
+See the main {{domxref("NavigationActivation")}} page.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Navigation API](/en-US/docs/Web/API/Navigation_API)
+- [View Transitions API](/en-US/docs/Web/API/View_Transitions_API)

files/en-us/web/api/navigationactivation/index.md

@@ -0,0 +1,94 @@
+---
+title: NavigationActivation
+slug: Web/API/NavigationActivation
+page-type: web-api-interface
+status:
+  - experimental
+browser-compat: api.NavigationActivation
+---
+
+{{APIRef("Navigation API")}}{{SeeCompatTable}}
+
+The **`NavigationActivation`** interface of the [Navigation API](/en-US/docs/Web/API/Navigation_API) represents a recent cross-document navigation. It contains the navigation type and outgoing and inbound document history entries.
+
+This object is accessed via the {{domxref("PageSwapEvent.activation")}} and {{domxref("Navigation.activation")}} properties. Note that, in each case, the `NavigationActivation` represents a different navigation:
+
+- `Navigation.activation` represents information about the navigation to the current page.
+- `PageSwapEvent.activation` represents information about the navigation to the next page.
+
+## Instance properties
+
+- {{domxref("NavigationActivation.entry", "entry")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Contains a {{domxref("NavigationHistoryEntry")}} object representing the history entry for the inbound ("to") document in the navigation. This is equivalent to the {{domxref("Navigation.currentEntry")}} property at the moment the inbound document was activated.
+- {{domxref("NavigationActivation.from", "from")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Contains a {{domxref("NavigationHistoryEntry")}} object representing the history entry for the outgoing ("from") document in the navigation.
+- {{domxref("NavigationActivation.navigationType", "navigationType")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Contains a string indicating the type of navigation.
+
+## Examples
+
+```js
+window.addEventListener("pagereveal", async (e) => {
+  // If the "from" history entry does not exist, return
+  if (!navigation.activation.from) return;
+
+  // Only run this if an active view transition exists
+  if (e.viewTransition) {
+    const fromUrl = new URL(navigation.activation.from.url);
+    const currentUrl = new URL(navigation.activation.entry.url);
+
+    // Went from profile page to homepage
+    // ~> Set VT names on the relevant list item
+    if (isProfilePage(fromUrl) && isHomePage(currentUrl)) {
+      const profile = extractProfileNameFromUrl(fromUrl);
+
+      // Set view-transition-name values on the elements to animate
+      document.querySelector(`#${profile} span`).style.viewTransitionName =
+        "name";
+      document.querySelector(`#${profile} img`).style.viewTransitionName =
+        "avatar";
+
+      // Remove names after snapshots have been taken
+      // so that we're ready for the next navigation
+      await e.viewTransition.ready;
+      document.querySelector(`#${profile} span`).style.viewTransitionName =
+        "none";
+      document.querySelector(`#${profile} img`).style.viewTransitionName =
+        "none";
+    }
+
+    // Went to profile page
+    // ~> Set VT names on the main title and image
+    if (isProfilePage(currentUrl)) {
+      // Set view-transition-name values on the elements to animate
+      document.querySelector(`#detail main h1`).style.viewTransitionName =
+        "name";
+      document.querySelector(`#detail main img`).style.viewTransitionName =
+        "avatar";
+
+      // Remove names after snapshots have been taken
+      // so that we're ready for the next navigation
+      await e.viewTransition.ready;
+      document.querySelector(`#detail main h1`).style.viewTransitionName =
+        "none";
+      document.querySelector(`#detail main img`).style.viewTransitionName =
+        "none";
+    }
+  }
+});
+```
+
+> **Note:** See [List of Chrome Dev Rel team members](https://view-transitions.netlify.app/profiles/mpa/) for the live demo this code is taken from.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Navigation API](/en-US/docs/Web/API/Navigation_API)
+- [View Transitions API](/en-US/docs/Web/API/View_Transitions_API)

files/en-us/web/api/navigationactivation/navigationtype/index.md

@@ -0,0 +1,49 @@
+---
+title: "NavigationActivation: navigationType property"
+short-title: navigationType
+slug: Web/API/NavigationActivation/navigationType
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.NavigationActivation.navigationType
+---
+
+{{APIRef("Navigation API")}}{{SeeCompatTable}}
+
+The **`navigationType`** read-only property of the {{domxref("NavigationActivation")}} interface contains a string indicating the type of navigation.
+
+## Value
+
+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("NavigationActivation.entry")}} was reloaded.
+- `replace`: The {{domxref("NavigationActivation.entry")}} 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")}}.
+- `traverse`: The browser navigated from one existing history entry to another existing history entry.
+
+## Examples
+
+```js
+window.addEventListener("pageswap", (event) => {
+  // For example, the page was hidden, or the navigation is cross-document.
+  if (!event.viewTransition) return;
+
+  // Skip the view transition for back/forward navigations.
+  if (event.activation.navigationType === "traverse") {
+    event.viewTransition.skipTransition();
+  }
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Navigation API](/en-US/docs/Web/API/Navigation_API)
+- [View Transitions API](/en-US/docs/Web/API/View_Transitions_API)

files/en-us/web/api/pagerevealevent/index.md

@@ -0,0 +1,104 @@
+---
+title: PageRevealEvent
+slug: Web/API/PageRevealEvent
+page-type: web-api-interface
+status:
+  - experimental
+browser-compat: api.PageRevealEvent
+---
+
+{{APIRef("HTML DOM")}}{{SeeCompatTable}}
+
+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.
+
+Outside view transitions, this event is also useful for cases such as triggering a startup animation, or reporting a page view. It's equivalent to the first {{domxref("Window.requestAnimationFrame()")}} run after a cross-document navigation, if you were to trigger `requestAnimationFrame()` in the {{htmlelement("head")}} of the document. For example, if you ran the following `reveal()` function in the `<head>`:
+
+```js
+function reveal() {
+  // Include startup animation here
+}
+/* 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());
+```
+
+## Constructor
+
+- {{domxref("PageRevealEvent.PageRevealEvent", "PageRevealEvent()")}}
+  - : Creates a new {{domxref("PageRevealEvent")}} object instance.
+
+## Instance properties
+
+- {{domxref("PageRevealEvent.viewTransition", "viewTransition")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Contains a {{domxref("ViewTransition")}} object representing the active view transition for the cross-document navigation.
+
+## Examples
+
+```js
+window.addEventListener("pagereveal", async (e) => {
+  // If the "from" history entry does not exist, return
+  if (!navigation.activation.from) return;
+
+  // Only run this if an active view transition exists
+  if (e.viewTransition) {
+    const fromUrl = new URL(navigation.activation.from.url);
+    const currentUrl = new URL(navigation.activation.entry.url);
+
+    // Went from profile page to homepage
+    // ~> Set VT names on the relevant list item
+    if (isProfilePage(fromUrl) && isHomePage(currentUrl)) {
+      const profile = extractProfileNameFromUrl(fromUrl);
+
+      // Set view-transition-name values on the elements to animate
+      document.querySelector(`#${profile} span`).style.viewTransitionName =
+        "name";
+      document.querySelector(`#${profile} img`).style.viewTransitionName =
+        "avatar";
+
+      // Remove names after snapshots have been taken
+      // so that we're ready for the next navigation
+      await e.viewTransition.ready;
+      document.querySelector(`#${profile} span`).style.viewTransitionName =
+        "none";
+      document.querySelector(`#${profile} img`).style.viewTransitionName =
+        "none";
+    }
+
+    // Went to profile page
+    // ~> Set VT names on the main title and image
+    if (isProfilePage(currentUrl)) {
+      // Set view-transition-name values on the elements to animate
+      document.querySelector(`#detail main h1`).style.viewTransitionName =
+        "name";
+      document.querySelector(`#detail main img`).style.viewTransitionName =
+        "avatar";
+
+      // Remove names after snapshots have been taken
+      // so that we're ready for the next navigation
+      await e.viewTransition.ready;
+      document.querySelector(`#detail main h1`).style.viewTransitionName =
+        "none";
+      document.querySelector(`#detail main img`).style.viewTransitionName =
+        "none";
+    }
+  }
+});
+```
+
+> **Note:** See [List of Chrome Dev Rel team members](https://view-transitions.netlify.app/profiles/mpa/) for the live demo this code is taken from.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [View Transitions API](/en-US/docs/Web/API/View_Transitions_API)