From b0ab36f51b25b3c5757a58b29ce8b64bb1a745e2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 22 Nov 2025 16:54:02 +0000
Subject: [PATCH] Add Lenis smooth scrolling for improved interaction design

- Integrate Lenis library for butter-smooth scrolling experience
- Add scroll progress indicator bar at top of page
- Create ScrollToTop button with gradient styling and animations
- Implement scroll-linked CSS animations and reveal effects
- Support Astro view transitions with proper lifecycle hooks
- Add i18n support for scroll-to-top accessibility label
---
 package.json                        |   1 +
 src/components/core/LenisInit.astro | 170 ++++++++++++++++++++++++++++
 src/components/ui/ScrollToTop.astro | 110 ++++++++++++++++++
 src/i18n/languages.ts               |   2 +
 src/layouts/BaseLayout.astro        |   2 +
 src/layouts/PageLayout.astro        |   2 +
 src/scripts/lenis-init.ts           | 118 +++++++++++++++++++
 7 files changed, 405 insertions(+)
 create mode 100644 src/components/core/LenisInit.astro
 create mode 100644 src/components/ui/ScrollToTop.astro
 create mode 100644 src/scripts/lenis-init.ts

diff --git a/package.json b/package.json
index cf4c171..718ef23 100644
--- a/package.json
+++ b/package.json
@@ -29,6 +29,7 @@
     "astro": "^5.12.9",
     "cloudinary": "^2.8.0",
     "framer-motion": "^12.23.24",
+    "lenis": "^1.3.15",
     "limax": "^4.1.0",
     "lodash.merge": "^4.6.2",
     "matter-js": "^0.20.0",
diff --git a/src/components/core/LenisInit.astro b/src/components/core/LenisInit.astro
new file mode 100644
index 0000000..435915a
--- /dev/null
+++ b/src/components/core/LenisInit.astro
@@ -0,0 +1,170 @@
+---
+/**
+ * Lenis Smooth Scrolling Component
+ * Initializes Lenis for butter-smooth scrolling experience
+ */
+---
+
+<!-- Lenis CSS -->
+<style is:global>
+  /* Lenis base styles */
+  html.lenis, html.lenis body {
+    height: auto;
+  }
+
+  .lenis.lenis-smooth {
+    scroll-behavior: auto !important;
+  }
+
+  .lenis.lenis-smooth [data-lenis-prevent] {
+    overscroll-behavior: contain;
+  }
+
+  .lenis.lenis-stopped {
+    overflow: hidden;
+  }
+
+  .lenis.lenis-smooth iframe {
+    pointer-events: none;
+  }
+
+  /* Scroll-based effects */
+  body.is-scrolling {
+    /* Elements can react to scrolling state */
+  }
+
+  body.is-scrolling-fast {
+    /* Fast scroll effects */
+  }
+
+  /* Smooth scroll anchor offset for fixed header */
+  :target {
+    scroll-margin-top: 80px;
+  }
+
+  /* Scroll-linked animations */
+  @supports (animation-timeline: scroll()) {
+    /* Progress bar at top of page */
+    .scroll-progress {
+      position: fixed;
+      top: 0;
+      left: 0;
+      width: 100%;
+      height: 3px;
+      background: linear-gradient(90deg,
+        var(--color-primary, #6366f1) 0%,
+        var(--color-secondary, #a855f7) 100%
+      );
+      transform-origin: left;
+      transform: scaleX(0);
+      animation: scroll-progress-anim linear;
+      animation-timeline: scroll();
+      z-index: 9999;
+    }
+
+    @keyframes scroll-progress-anim {
+      to {
+        transform: scaleX(1);
+      }
+    }
+  }
+
+  /* Scroll reveal animations */
+  .scroll-fade-in {
+    opacity: 0;
+    transform: translateY(30px);
+    transition: opacity 0.6s ease-out, transform 0.6s ease-out;
+  }
+
+  .scroll-fade-in.is-visible {
+    opacity: 1;
+    transform: translateY(0);
+  }
+
+  .scroll-slide-left {
+    opacity: 0;
+    transform: translateX(-50px);
+    transition: opacity 0.6s ease-out, transform 0.6s ease-out;
+  }
+
+  .scroll-slide-left.is-visible {
+    opacity: 1;
+    transform: translateX(0);
+  }
+
+  .scroll-slide-right {
+    opacity: 0;
+    transform: translateX(50px);
+    transition: opacity 0.6s ease-out, transform 0.6s ease-out;
+  }
+
+  .scroll-slide-right.is-visible {
+    opacity: 1;
+    transform: translateX(0);
+  }
+
+  .scroll-scale-in {
+    opacity: 0;
+    transform: scale(0.9);
+    transition: opacity 0.6s ease-out, transform 0.6s ease-out;
+  }
+
+  .scroll-scale-in.is-visible {
+    opacity: 1;
+    transform: scale(1);
+  }
+
+  /* Parallax effect helper classes */
+  .parallax-slow {
+    will-change: transform;
+  }
+
+  .parallax-fast {
+    will-change: transform;
+  }
+
+  /* Stagger animation delays */
+  .stagger-1 { transition-delay: 0.1s; }
+  .stagger-2 { transition-delay: 0.2s; }
+  .stagger-3 { transition-delay: 0.3s; }
+  .stagger-4 { transition-delay: 0.4s; }
+  .stagger-5 { transition-delay: 0.5s; }
+  .stagger-6 { transition-delay: 0.6s; }
+</style>
+
+<!-- Lenis initialization script -->
+<script>
+  import '~/scripts/lenis-init.ts';
+
+  // Intersection Observer for scroll reveal animations
+  const setupScrollReveal = () => {
+    const observerOptions = {
+      root: null,
+      rootMargin: '0px 0px -50px 0px',
+      threshold: 0.1,
+    };
+
+    const observer = new IntersectionObserver((entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          entry.target.classList.add('is-visible');
+        }
+      });
+    }, observerOptions);
+
+    // Observe all scroll-animated elements
+    document.querySelectorAll('.scroll-fade-in, .scroll-slide-left, .scroll-slide-right, .scroll-scale-in').forEach((el) => {
+      observer.observe(el);
+    });
+  };
+
+  // Initialize on page load
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', setupScrollReveal);
+  } else {
+    setupScrollReveal();
+  }
+
+  // Re-initialize on Astro page navigation
+  document.addEventListener('astro:page-load', setupScrollReveal);
+</script>
diff --git a/src/components/ui/ScrollToTop.astro b/src/components/ui/ScrollToTop.astro
new file mode 100644
index 0000000..765a17f
--- /dev/null
+++ b/src/components/ui/ScrollToTop.astro
@@ -0,0 +1,110 @@
+---
+/**
+ * Scroll to Top Button
+ * A floating button that appears when user scrolls down and smoothly scrolls back to top
+ */
+---
+
+<!-- Scroll Progress Bar -->
+<div class="scroll-progress" aria-hidden="true"></div>
+
+<!-- Scroll to Top Button -->
+<button
+  id="scroll-to-top"
+  class="fixed bottom-8 right-8 z-50 w-12 h-12 rounded-full bg-primary dark:bg-primary-dark text-white shadow-lg opacity-0 invisible translate-y-4 transition-all duration-300 hover:scale-110 hover:shadow-xl focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2 group"
+  aria-label="Scroll to top"
+  data-i18n-aria="common.scrollToTop"
+>
+  <svg
+    class="w-6 h-6 mx-auto transform transition-transform group-hover:-translate-y-0.5"
+    fill="none"
+    stroke="currentColor"
+    viewBox="0 0 24 24"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      stroke-width="2"
+      d="M5 10l7-7m0 0l7 7m-7-7v18"
+    ></path>
+  </svg>
+</button>
+
+<style>
+  #scroll-to-top.visible {
+    opacity: 1;
+    visibility: visible;
+    transform: translateY(0);
+  }
+
+  #scroll-to-top {
+    background: linear-gradient(135deg, var(--color-primary, #6366f1) 0%, var(--color-secondary, #a855f7) 100%);
+  }
+
+  #scroll-to-top:hover {
+    background: linear-gradient(135deg, var(--color-primary-dark, #4f46e5) 0%, var(--color-secondary-dark, #9333ea) 100%);
+  }
+
+  /* Pulse animation when visible */
+  #scroll-to-top.visible {
+    animation: subtle-pulse 2s ease-in-out infinite;
+  }
+
+  @keyframes subtle-pulse {
+    0%, 100% {
+      box-shadow: 0 10px 15px -3px rgba(99, 102, 241, 0.3), 0 4px 6px -4px rgba(99, 102, 241, 0.3);
+    }
+    50% {
+      box-shadow: 0 10px 25px -3px rgba(99, 102, 241, 0.5), 0 4px 10px -4px rgba(99, 102, 241, 0.5);
+    }
+  }
+</style>
+
+<script>
+  const initScrollToTop = () => {
+    const button = document.getElementById('scroll-to-top');
+    if (!button) return;
+
+    // Show/hide button based on scroll position
+    const toggleVisibility = () => {
+      const scrollY = window.scrollY || document.documentElement.scrollTop;
+      const threshold = 300;
+
+      if (scrollY > threshold) {
+        button.classList.add('visible');
+      } else {
+        button.classList.remove('visible');
+      }
+    };
+
+    // Listen to scroll events
+    window.addEventListener('scroll', toggleVisibility, { passive: true });
+
+    // Also listen to Lenis scroll events for smoother updates
+    window.addEventListener('lenis-scroll', toggleVisibility);
+
+    // Scroll to top on click
+    button.addEventListener('click', () => {
+      // Use Lenis if available, otherwise fallback
+      if ((window as any).lenis) {
+        (window as any).lenis.scrollTo(0, { duration: 1.5 });
+      } else {
+        window.scrollTo({ top: 0, behavior: 'smooth' });
+      }
+    });
+
+    // Initial check
+    toggleVisibility();
+  };
+
+  // Initialize on page load
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initScrollToTop);
+  } else {
+    initScrollToTop();
+  }
+
+  // Re-initialize on Astro page navigation
+  document.addEventListener('astro:page-load', initScrollToTop);
+</script>
diff --git a/src/i18n/languages.ts b/src/i18n/languages.ts
index 17854a8..29df501 100644
--- a/src/i18n/languages.ts
+++ b/src/i18n/languages.ts
@@ -135,6 +135,7 @@ export const ui = {
     'common.filter': '筛选',
     'common.sort': '排序',
     'common.all': '全部',
+    'common.scrollToTop': '返回顶部',
 
     // 表单
     'form.name': '姓名',
@@ -753,6 +754,7 @@ export const ui = {
     'common.filter': 'Filter',
     'common.sort': 'Sort',
     'common.all': 'All',
+    'common.scrollToTop': 'Back to Top',
 
     // Form
     'form.name': 'Name',
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 6bcf5c5..4e3494f 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -4,6 +4,7 @@ import '~/assets/styles/base.css';
 import MetaTags from '~/components/core/MetaTags.astro';
 import BasicScripts from '~/components/core/BasicScripts.astro';
 import AOSInit from '~/components/core/AOSInit.astro';
+import LenisInit from '~/components/core/LenisInit.astro';
 import { defaultLang } from '~/i18n/languages';
 
 const { meta = {} } = Astro.props;
@@ -19,6 +20,7 @@ const { meta = {} } = Astro.props;
 		<slot />
 		<BasicScripts />
 		<AOSInit />
+		<LenisInit />
 
 		<!-- Language initialization script -->
 		<script is:inline>
diff --git a/src/layouts/PageLayout.astro b/src/layouts/PageLayout.astro
index c523e3a..b295722 100644
--- a/src/layouts/PageLayout.astro
+++ b/src/layouts/PageLayout.astro
@@ -5,6 +5,7 @@ import Footer from '~/components/widgets/Footer.astro';
 import Announcement from '~/components/widgets/Announcement.astro';
 import PhysicsBackground from '~/components/widgets/PhysicsBackground.astro';
 import ParticlesBackground from '~/components/widgets/ParticlesBackground.astro';
+import ScrollToTop from '~/components/ui/ScrollToTop.astro';
 
 const { meta } = Astro.props;
 ---
@@ -18,4 +19,5 @@ const { meta } = Astro.props;
 		<slot />
 	</main>
 	<Footer />
+	<ScrollToTop />
 </Layout>
diff --git a/src/scripts/lenis-init.ts b/src/scripts/lenis-init.ts
new file mode 100644
index 0000000..b84b5a7
--- /dev/null
+++ b/src/scripts/lenis-init.ts
@@ -0,0 +1,118 @@
+/**
+ * Lenis Smooth Scrolling Initialization
+ * Provides butter-smooth scrolling experience with momentum
+ */
+
+import Lenis from 'lenis';
+
+// Global Lenis instance
+let lenis: Lenis | null = null;
+
+// Initialize Lenis
+const initLenis = () => {
+  // Destroy existing instance if any
+  if (lenis) {
+    lenis.destroy();
+  }
+
+  lenis = new Lenis({
+    duration: 1.2,
+    easing: (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)), // Exponential easing
+    smoothWheel: true,
+    wheelMultiplier: 1,
+    touchMultiplier: 2,
+    autoRaf: true,
+    anchors: true, // Enable smooth scrolling to anchor links
+  });
+
+  // Expose lenis instance globally for other scripts
+  (window as any).lenis = lenis;
+
+  // Listen for scroll events (useful for debugging or syncing with other animations)
+  lenis.on('scroll', () => {
+    // Dispatch custom event for other components to listen to
+    window.dispatchEvent(new CustomEvent('lenis-scroll', {
+      detail: {
+        scroll: lenis?.scroll,
+        velocity: lenis?.velocity,
+        progress: lenis?.progress,
+      }
+    }));
+  });
+
+  // Add scroll velocity class to body for CSS-based effects
+  lenis.on('scroll', () => {
+    const velocity = Math.abs(lenis?.velocity || 0);
+    document.body.classList.toggle('is-scrolling', velocity > 0.1);
+    document.body.classList.toggle('is-scrolling-fast', velocity > 2);
+  });
+};
+
+// Handle anchor links with smooth scroll
+const setupAnchorLinks = () => {
+  document.querySelectorAll('a[href^="#"]').forEach((anchor) => {
+    anchor.addEventListener('click', (e) => {
+      const href = anchor.getAttribute('href');
+      if (href && href !== '#' && lenis) {
+        const target = document.querySelector(href);
+        if (target) {
+          e.preventDefault();
+          lenis.scrollTo(target as HTMLElement, {
+            offset: -80, // Account for fixed header
+            duration: 1.5,
+          });
+        }
+      }
+    });
+  });
+};
+
+// Scroll to top function
+export const scrollToTop = () => {
+  lenis?.scrollTo(0, { duration: 1.5 });
+};
+
+// Scroll to element function
+export const scrollToElement = (selector: string, offset = -80) => {
+  const element = document.querySelector(selector);
+  if (element && lenis) {
+    lenis.scrollTo(element as HTMLElement, { offset, duration: 1.5 });
+  }
+};
+
+// Stop scrolling (useful for modals)
+export const stopScroll = () => {
+  lenis?.stop();
+};
+
+// Resume scrolling
+export const startScroll = () => {
+  lenis?.start();
+};
+
+// Get Lenis instance
+export const getLenis = () => lenis;
+
+// Initialize on page load
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', () => {
+    initLenis();
+    setupAnchorLinks();
+  });
+} else {
+  initLenis();
+  setupAnchorLinks();
+}
+
+// Re-initialize on Astro page navigation
+document.addEventListener('astro:page-load', () => {
+  initLenis();
+  setupAnchorLinks();
+});
+
+// Handle Astro view transitions
+document.addEventListener('astro:after-swap', () => {
+  if (lenis) {
+    lenis.resize();
+  }
+});