└── README.md


/README.md:
--------------------------------------------------------------------------------
  1 | # The problem
  2 | 
  3 | If you want to transition between pages, your current option is to fetch the new page with JavaScript, update the URL with [`pushState`](https://developer.mozilla.org/en-US/docs/Web/API/History_API#The_pushState()_method), and animate between the two.
  4 | 
  5 | Having to reimplement navigation for a simple transition is a bit much, often leading developers to use large frameworks where they could otherwise be avoided. This proposal provides a low-level way to create transitions while maintaining regular browser navigation.
  6 | 
  7 | # Goals
  8 | 
  9 | * Enable complex transitions.
 10 | * Allow transitions to start while the next page is being fetched.
 11 | * Allow transitions to differ between navigation from clicking a link, back button, forward button, reload button, etc.
 12 | * Allow transitions to cater for a non-zero scroll position in the navigated-to page.
 13 | 
 14 | # Experiments, talks & reading materials
 15 | 
 16 | ## Web Navigation Transitions (2014): CSS-based experiment by Google Chrome team
 17 | * [**Spec:** Initial (deprecated) spec for experimental Web Navigation Transitions prototype (2014)](https://docs.google.com/document/d/17jg1RRL3RI969cLwbKBIcoGDsPwqaEdBxafGNYGwiY4/edit)
 18 | * [**Talk (video):** Ryan Schoen's talk, Wicked Fast: Performance investments (Chrome Dev Summit 2014)](https://www.youtube.com/watch?v=v0xRTEf-ytE)
 19 |     * [**Demo (video):** Web Navigation Transitions in Chrome on Android](https://www.youtube.com/watch?v=v0xRTEf-ytE&t=968)
 20 |     * [**Demo (video):** Android's Activities Transitions API and experimental Web Navigation Transitions in Chrome on Android](https://www.youtube.com/watch?v=v0xRTEf-ytE&t=1075)
 21 | 
 22 | ## Web Navigation Transitions (2015): CSS-based proposal by Chris Lord (Mozilla, Firefox OS)
 23 | * [**Article:** Web Navigation Transitions by Chris Lord (Mozilla)](http://chrislord.net/index.php/2015/04/24/web-navigation-transitions/)
 24 | * [**Examples:** Web Navigation Transitions examples (emulated with CSS Animations, custom CSS media queries, events, `<iframe>`s, `postMessage`, etc.)](http://chrislord.net/files/mozilla/gaia-navigator/examples/)
 25 | * [**Code samples:** Source code of "Gaia Navigator" Web Navigation Transitions examples](https://github.com/Cwiiis/gaia-navigator)
 26 | 
 27 | ## Web Navigation Transitions (2016): New proposal by Jake Archibald (Google Chrome)
 28 | * [**Talk (video):** Intro to this proposal (Chrome Dev Summit 2016)](https://www.youtube.com/watch?v=J2dOTKBoTL4&t=1815)
 29 | 
 30 | # API sketch
 31 | 
 32 | ```js
 33 | window.addEventListener('navigate', event => {
 34 |   // …
 35 | });
 36 | ```
 37 | 
 38 | The `navigate` event fires when the document is being navigated in a way that would replace the current document.
 39 | 
 40 | * `event.type` - The name of this event, `navigate`.
 41 | * `event.reason` - The way in which the document is being navigated to. One of the following strings:
 42 |   * `back` - User is navigating back.
 43 |   * `forward` - User is navigating forward.
 44 |   * `reload` - Reload-triggered navigation.
 45 |   * `normal` - Not one of the above.
 46 | * `event.url` - The URL being navigated to. An empty string if the URL is of another origin.
 47 | * `event.newWindow` - A promise for a `WindowProxy` being navigated to. Resolves with `undefined` if another origin is involved in the navigation (i.e., the initial URL or URLs of redirects). Rejects if the navigation fails. Cancels if the navigation cancels (dependent on cancelable promises).
 48 | * `event.transitionUntil(promise)` - Keep this document alive and potentially visible until `promise` settles, or once another origin is involved in the navigation (i.e., the initial URL or URLs of redirects).
 49 | 
 50 | **Note:** The same-origin restrictions are to avoid new URL leaks and timing attacks.
 51 | 
 52 | # Simple cross-fade transition
 53 | 
 54 | ```js
 55 | window.addEventListener('navigate', event => {
 56 |   event.transitionUntil(
 57 |     event.newWindow.then(newWin => {
 58 |       if (!newWin) return;
 59 | 
 60 |       // assuming newWin.document.interactive means DOM ready
 61 |       return newWin.document.interactive.then(() => {
 62 |         return newWin.document.documentElement.animate([
 63 |           {opacity: 0}, {opacity: 1}
 64 |         ], 1000).finished;
 65 |       });
 66 |     })
 67 |   );
 68 | });
 69 | ```
 70 | 
 71 | # Slide-in/out transition
 72 | 
 73 | ```js
 74 | window.addEventListener('navigate', event => {
 75 |   if (event.reason == 'reload') return;
 76 | 
 77 |   const fromRight = [
 78 |     {transform: 'translate(100%, 0)'},
 79 |     {transform: 'none'}
 80 |   ];
 81 | 
 82 |   const toLeft = [
 83 |     {transform: 'none'},
 84 |     {transform: 'translate(-100%, 0)'}
 85 |   ];
 86 | 
 87 |   const fromLeft = toLeft.slice().reverse();
 88 |   const toRight = fromRight.slice().reverse();
 89 | 
 90 |   event.transitionUntil(
 91 |     event.newWindow.then(newWin => {
 92 |       if (!newWin) return;
 93 |  
 94 |       return newWin.document.interactive.then(() => {
 95 |         return Promise.all([
 96 |           newWin.document.documentElement.animate(
 97 |             event.reason == 'back' ? fromLeft : fromRight, 500
 98 |           ).finished,
 99 |           document.documentElement.animate(
100 |             event.reason == 'back' ? toRight : toLeft, 500
101 |           ).finished
102 |         ]);
103 |       });
104 |     })
105 |   );
106 | });
107 | ```
108 | 
109 | # Immediate slide-in/out transition
110 | 
111 | The above examples don't begin to animate until the new page has fetched and become interactive. That's ok, but this API allows the current page to transition while the new page is being fetched, improving the perception of performance:
112 | 
113 | ```js
114 | window.addEventListener('navigate', event => {
115 |   if (event.reason == 'reload') return;
116 | 
117 |   const newURL = new URL(event.url);
118 | 
119 |   if (newURL.origin !== location.origin) return;
120 | 
121 |   const documentRect = document.documentElement.getBoundingClientRect();
122 | 
123 |   // Create something that looks like the shell of the new page
124 |   const pageShell = createPageShellFor(event.url);
125 |   document.body.appendChild(pageShell);
126 | 
127 |   const directionMultiplier = event.reason == 'back' ? -1 : 1;
128 | 
129 |   pageShell.style.transform = `translate(${100 * directionMultiplier}%, ${-documentRect.top}px)`;
130 | 
131 |   const slideAnim = document.body.animate({
132 |     transform: `translate(${100 * directionMultiplier}%, 0)`
133 |   }, 500);
134 | 
135 |   event.transitionUntil(
136 |     event.newWindow.then(newWin => {
137 |       if (!newWin) return;
138 |  
139 |       return slideAnim.finished.then(() => {
140 |         return newWin.document.documentElement
141 |           .animate({opacity: 0}, 200).finished;
142 |       });
143 |     })
144 |   );
145 | });
146 | ```
147 | 
148 | # Rendering & interactivity
149 | 
150 | During the transition, the document with the highest `z-index` on the `documentElement` will render on top. If `z-index`es are equal, the entering document will render on top. Both `documentElement`s will generate stacking contexts.
151 | 
152 | If the background of `html`/`body` is transparent, the underlying document will be visible through it. Beneath both documents is the browser's default background (usually white).
153 | 
154 | During the transition, the render-box of the documents will be clipped to that of the viewport size. This means `html { transform: translate(0, -20px); }` on the top document will leave a 20-pixel gap at the bottom, through which the bottom document will be visible. After the transition, rendering switches back to using the regular model.
155 | 
156 | We must guarantee that the new document doesn't visibly appear until `event.newWindow`'s reactions have completed.
157 | 
158 | As for interactivity, both documents will be at least scrollable, although developers could prevent this using `pointer-events: none` or similar.
159 | 
160 | Apologies for the hand-waving.
161 | 
162 | # Place within the navigation algorithm
163 | 
164 | It feels like the event should fire immediately after step 10 of [`navigate`](https://html.spec.whatwg.org/multipage/browsers.html#navigate). If `transitionUntil` is called, the browser would consider the pages to be transitioning.
165 | 
166 | The rest of the handling would likely be in the ["update the session history with the new page" algorithm](https://html.spec.whatwg.org/multipage/browsers.html#update-the-session-history-with-the-new-page). The unloading of the current document would be delayed but without delaying the loading of the new document.
167 | 
168 | Yep, more hand-waving.
169 | 
170 | # Potential issues & questions
171 | 
172 | * Can transitions/animations be reliably synchronised between documents? They at least share an event loop.
173 | * Any issues with firing transitions/animations for nested contexts?
174 | * What if the promise passed to `transitionUntil` never resolves? Feels like it should have a timeout.
175 | * What happens on low-end devices that can't display two documents at once?
176 | * What if the navigation is cancelled (e.g., use of a `Content-Disposition` response header). `event.newWindow` could also cancel.
177 | * How does this interact with browsers that have a [back-forward cache](https://developer.mozilla.org/en-US/docs/Working_with_BFCache)?
178 | * How should redirects be handled?
179 | * How should interactivity during the transition be handled?
180 | * During a sliding transitions, is it possible to switch a fake shell for the actual page's document mid-transition? Feels like this is something the [Animation API](https://www.w3.org/TR/web-animations-1/) should be able to do.
181 | 


--------------------------------------------------------------------------------