docs: page transitions (#1136)

## 📜 Description

Added animated transitions to documentation.

## 💡 Motivation and Context

Inspired by mrousavy/nitro#901

I like animated transitions more than instant one (even on web), so in
this PR I add them 👀

## 📢 Changelog

<!-- High level overview of important changes -->
<!-- For example: fixed status bar manipulation; added new types
declarations; -->
<!-- If your changes don't affect one of platform/language below - then
remove this platform/language -->

### Docs

- added scroll animation;
- added cross-page transition between pages (opacity)

## 🤔 How Has This Been Tested?

Tested manually on `localhost:3000`

## 📸 Screenshots (if appropriate):


https://github.com/user-attachments/assets/6007441b-6f3a-4df2-a1e3-ebb9110655c8

## 📝 Checklist

- [x] CI successfully passed
- [x] I added new mocks and corresponding unit-tests if library API was
changed

Author: kirillzyusko

docs/docusaurus.config.js

@@ -21,6 +21,9 @@ const config = {
   onBrokenMarkdownLinks: "warn",
   favicon: "favicon.ico",
 
+  // Runs animations on page change
+  clientModules: ["./src/modules/page-transitions.ts"],
+
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
   organizationName: "kirillzyusko",

docs/src/css/custom.css

@@ -325,3 +325,22 @@ h3 .label {
   height: 400px;
   margin-bottom: 24px;
 }
+
+html {
+  scroll-behavior: smooth;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .doc-fade--run {
+    animation: doc-fade-in 250ms ease-in-out;
+    will-change: opacity, transform, filter;
+  }
+  @keyframes doc-fade-in {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
+  }
+}

docs/src/modules/page-transitions.ts

@@ -0,0 +1,65 @@
+import type { ClientModule } from "@docusaurus/types";
+
+function getDocsMain(): HTMLElement | null {
+  // match "docMainContainer_<hash>" no matter where it appears in class attr
+  return document.querySelector(
+    'main[class^="docMainContainer_"], main[class*=" docMainContainer_"]',
+  );
+}
+
+function scrollIntoView(element: HTMLElement) {
+  // let layout settle first
+  requestAnimationFrame(() => {
+    element.scrollIntoView({ behavior: "smooth", block: "start" });
+  });
+}
+
+function runFadeInAnimation(element: HTMLElement) {
+  element.classList.remove("doc-fade--run");
+  void element.offsetWidth; // reflow
+  requestAnimationFrame(() => {
+    element.classList.add("doc-fade--run");
+  });
+}
+
+const client: ClientModule = {
+  onRouteDidUpdate({ location, previousLocation }) {
+    if (!previousLocation) {
+      // first mount should not play an animation
+      return;
+    }
+    const pathChanged = location.pathname !== previousLocation.pathname;
+    const hashChanged = location.hash !== previousLocation.hash;
+
+    if (!hashChanged && !pathChanged) {
+      // nothing changed, do nothing
+      return;
+    }
+
+    const mainElement = getDocsMain();
+
+    if (!mainElement) {
+      // we're not on our docs page
+      return;
+    }
+
+    if (hashChanged && !pathChanged) {
+      // anchor changed - smoothly scroll to new anchor
+      const id = decodeURIComponent(location.hash.replace(/^#/, ""));
+      const target = id ? document.getElementById(id) : null;
+
+      if (target) {
+        scrollIntoView(target);
+      }
+
+      return;
+    }
+
+    if (pathChanged) {
+      // page changed - run fade-in animation
+      runFadeInAnimation(mainElement);
+    }
+  },
+};
+
+export default client;