feat: View Transition hook (#7237)

* feat: dispatch q:viewTransition when started

* add changeset

* add documentation

* replace q:viewTransition for qviewTransition

* move QwikTransitionEvent up

* doc: fix example

* doc: improve examples

* doc: expose new page

* doc: add indication about ViewTransition interface

* doc: fix doc typo and add explaination

Author: GrandSchtroumpf

.changeset/plenty-books-sin.md

@@ -0,0 +1,5 @@
+---
+'@builder.io/qwik': patch
+---
+
+Emit an CustomEvent `qviewTransition` when view transition starts.

packages/docs/src/routes/docs/cookbook/index.mdx

@@ -32,3 +32,4 @@ Examples:
 - [Synchronous Events with State](./sync-events/)
 - [Theme Management](./theme-management/)
 - [Drag & Drop](./drag&drop/)
+- [View Transition](./view-transition/)

packages/docs/src/routes/docs/cookbook/view-transition/index.mdx

@@ -0,0 +1,130 @@
+---
+title: Cookbook | View Transition API
+contributors:
+  - GrandSchtroumpf
+---
+
+# View Transition API
+By default Qwik will start a view transition when SPA navigation. We can run animation either with CSS or WAAPI.
+
+## CSS
+```tsx
+export default component$(({ list }) => {
+  return (
+    <ul>
+      {list.map((item) => (
+        // Create a name per item
+        <li key={item.id} class="item" style={{viewTransitionName: `_${item.id}_`}}>...</li>
+      ))}
+    </ul>
+  )
+})
+```
+
+```css
+.item {
+  /* Alias to target all .item with a view-transition-name */
+  view-transition-class: animated-item;
+}
+/* Animate when item didn't exist in the previous page */
+::view-transition-new(.animated-item):only-child {
+  animation: fade-in 200ms;
+}
+/* Animate when item doesn't exist in the next page */
+::view-transition-old(.animated-item):only-child {
+  animation: fade-out 200ms;
+}
+```
+
+Sometime we need to have some specific logic before the animation start. In this case you can listen to the `qviewTransition` event.
+
+For example if you want to only animate visible element:
+```tsx
+export default component$(() => {
+  // In this case we need the callback to be sync, else the transition might have already happened
+  useOnDocument('qviewTransition', sync$((event: CustomEvent<ViewTransition>) => {
+    const transition = event.detail;
+    const items = document.querySelectorAll('.item');
+    for (const item of items) {
+      if (!item.checkVisibility()) continue;
+      item.dataset.hasViewTransition = true;
+    }
+  }))
+  return (
+    <ul>
+      {list.map((item) => (
+        // Create a name per item
+        <li key={item.id} class="item" style={{viewTransitionName: `_${item.id}_`}}>...</li>
+      ))}
+    </ul>
+  )
+})
+```
+
+```css
+.item[data-has-view-transition="true"] {
+  view-transition-class: animated-item;
+}
+::view-transition-new(.animated-item):only-child {
+  animation: fade-in 200ms;
+}
+::view-transition-old(.animated-item):only-child {
+  animation: fade-out 200ms;
+}
+```
+
+> **Note**: `ViewTransition` interface is available with Typescript >5.6.
+
+## WAAPI
+With Web Animation API you can get more precise, but for that we need to wait for the ::view-transition pseudo-element to exist in the DOM. To achieve that you can wait the `transition.ready` promise.
+
+In this example we add some delay for each item :
+```tsx
+export default component$(() => {
+  // Remove default style on the pseudo-element.
+  useStyles$(`
+    li {
+      view-transition-class: items;
+    }
+    ::view-transition-old(.items) {
+      animation: none;
+    }
+  `);
+  useOnDocument('qviewTransition', $(async (event: CustomEvent<ViewTransition>) => {
+    // Get visible item's viewTransitionName (should happen before transition is ready)
+    const items = document.querySelectorAll<HTMLElement>('.item');
+    const names = Array.from(items)
+      .filter((item) => item.checkVisibility())
+      .map((item) => item.style.viewTransitionName);
+
+    // Wait for ::view-transition pseudo-element to exist
+    const transition = event.detail;
+    await transition.ready; 
+
+    // Animate each leaving item
+    for (let i = 0; i < names.length; i++) {
+      // Note: we animate the <html> element
+      document.documentElement.animate({
+        opacity: 0,
+        transform: 'scale(0.9)'
+      }, {
+        // Target the pseudo-element inside the <html> element
+        pseudoElement: `::view-transition-old(${names[i]})`,
+        duration: 200,
+        fill: "forwards",
+        delay: i * 50, // Add delay for each pseudo-element
+      })
+    }
+  }))
+  return (
+    <ul>
+      {list.map((item) => (
+        // Create a name per item
+        <li key={item.id} class="item" style={{viewTransitionName: `_${item.id}_`}}>...</li>
+      ))}
+    </ul>
+  )
+})
+```
+
+> **Note**: For it to work correctly, we need to **remove the default view transition** animation else it happens on top of the `.animate()`. I'm using `view-transition-class` which is only working with Chrome right now.

packages/docs/src/routes/docs/menu.md

@@ -52,6 +52,7 @@
 - [Sync events w state](/docs/cookbook/sync-events/index.mdx)
 - [Theme Management](/docs/cookbook/theme-management/index.mdx)
 - [Drag & Drop](/docs/cookbook/drag&drop/index.mdx)
+- [View Transition](/docs/cookbook/view-transition/index.mdx)
 
 ## Integrations
 

packages/qwik/src/core/index.ts

@@ -139,6 +139,7 @@ export type {
   QwikVisibleEvent,
   QwikIdleEvent,
   QwikInitEvent,
+  QwikTransitionEvent,
   // old
   NativeAnimationEvent,
   NativeClipboardEvent,
@@ -166,7 +167,6 @@ export type {
   QwikTouchEvent,
   QwikUIEvent,
   QwikWheelEvent,
-  QwikTransitionEvent,
 } from './render/jsx/types/jsx-qwik-events';
 
 //////////////////////////////////////////////////////////////////////////////////////////

packages/qwik/src/core/render/dom/visitor.ts

@@ -1172,10 +1172,15 @@ export const executeContextWithScrollAndTransition = async (ctx: RenderStaticCon
     if (document.__q_view_transition__) {
       document.__q_view_transition__ = undefined;
       if (document.startViewTransition) {
-        await document.startViewTransition(() => {
+        const transition = document.startViewTransition(() => {
           executeDOMRender(ctx);
           restoreScroll();
-        }).finished;
+        });
+        const event = new CustomEvent('qviewTransition', {
+          detail: transition,
+        });
+        document.dispatchEvent(event);
+        await transition.finished;
         return;
       }
     }

packages/qwik/src/core/render/jsx/types/jsx-qwik-attributes.ts

@@ -5,6 +5,7 @@ import type {
   QwikIdleEvent,
   QwikInitEvent,
   QwikSymbolEvent,
+  QwikViewTransitionEvent,
   QwikVisibleEvent,
 } from './jsx-qwik-events';
 
@@ -113,6 +114,7 @@ type AllEventMapRaw = HTMLElementEventMap &
     qinit: QwikInitEvent;
     qsymbol: QwikSymbolEvent;
     qvisible: QwikVisibleEvent;
+    qviewTransition: QwikViewTransitionEvent;
   };
 
 /** This corrects the TS definition for ToggleEvent @public */

packages/qwik/src/core/render/jsx/types/jsx-qwik-events.ts

@@ -8,6 +8,8 @@ export type QwikSymbolEvent = CustomEvent<{ symbol: string; element: Element; re
 export type QwikInitEvent = CustomEvent<{}>;
 /** Emitted by qwik-loader on document when the document first becomes idle @public */
 export type QwikIdleEvent = CustomEvent<{}>;
+/** Emitted by qwik-core on document when the a view transition start @public */
+export type QwikViewTransitionEvent = CustomEvent<ViewTransition>;
 
 // Utility types for supporting autocompletion in union types