jung-li

Author: hwisu

src/scripts/main.js

@@ -1,61 +1,103 @@
 /**
- * Global site enhancements: theme persistence and mobile navigation interactions.
- * The module is loaded on every page via BaseLayout/HomePage.
+ * Global site enhancements for Astro static site with View Transitions
+ *
+ * Handles:
+ * - Theme persistence across page navigations
+ * - Mobile navigation interactions
+ * - Back-to-top button
+ *
+ * Best practices for Astro + GitHub Pages:
+ * - No external dependencies (pure vanilla JS)
+ * - Defensive coding for SSG/SSR compatibility
+ * - Proper cleanup of event listeners for View Transitions
+ * - FOUC prevention with early theme initialization
  */
 
 const THEME_STORAGE_KEY = 'theme';
+const THEME_DARK = 'dark';
+const THEME_LIGHT = 'light';
 
+/**
+ * Safely retrieves stored theme preference from localStorage
+ * @returns {'dark' | 'light'} The stored theme or default 'dark'
+ */
 const getStoredTheme = () => {
+  if (typeof localStorage === 'undefined') {
+    return THEME_DARK;
+  }
+
   try {
-    if (typeof localStorage === 'undefined') {
-      return 'dark';
-    }
     const stored = localStorage.getItem(THEME_STORAGE_KEY);
-    return stored === 'light' ? 'light' : 'dark';
+    return stored === THEME_LIGHT ? THEME_LIGHT : THEME_DARK;
   } catch (error) {
-    console.warn('Failed to access localStorage:', error);
-    return 'dark';
+    // localStorage might be blocked in private browsing
+    return THEME_DARK;
   }
 };
 
+/**
+ * Applies theme to document root
+ * @param {'dark' | 'light'} theme - Theme to apply
+ */
 const setThemeAttribute = (theme) => {
   document.documentElement.setAttribute('data-theme', theme);
 };
 
+/**
+ * Synchronizes theme toggle button icons with current theme
+ * @param {'dark' | 'light'} theme - Current theme
+ */
 const syncThemeIcons = (theme) => {
   const icon = document.getElementById('theme-icon');
   const mobileIcon = document.getElementById('mobile-theme-icon');
-  const iconText = theme === 'dark' ? '○' : '●';
+  const iconText = theme === THEME_DARK ? '○' : '●';
 
   if (icon) icon.textContent = iconText;
   if (mobileIcon) mobileIcon.textContent = iconText;
 };
 
+/**
+ * Applies theme and optionally persists to localStorage
+ * @param {'dark' | 'light'} theme - Theme to apply
+ * @param {boolean} persist - Whether to save to localStorage
+ */
 const applyTheme = (theme, persist = false) => {
   setThemeAttribute(theme);
   syncThemeIcons(theme);
-  if (persist) {
+
+  if (persist && typeof localStorage !== 'undefined') {
     try {
       localStorage.setItem(THEME_STORAGE_KEY, theme);
     } catch (error) {
-      console.warn('Failed to save theme to localStorage:', error);
+      // Silently fail if localStorage is unavailable
     }
   }
 };
 
+// Critical: Initialize theme before first paint to prevent FOUC
+// This runs immediately when the script loads
 setThemeAttribute(getStoredTheme());
 
+/**
+ * Handles theme toggle button clicks
+ * Toggles between light and dark themes and persists the choice
+ */
 const handleThemeToggle = () => {
   const currentAttr = document.documentElement.getAttribute('data-theme');
-  const current = currentAttr === 'light' ? 'light' : 'dark';
-  const next = current === 'dark' ? 'light' : 'dark';
+  const current = currentAttr === THEME_LIGHT ? THEME_LIGHT : THEME_DARK;
+  const next = current === THEME_DARK ? THEME_LIGHT : THEME_DARK;
   applyTheme(next, true);
 };
 
+// Expose for potential programmatic access
 window.toggleTheme = handleThemeToggle;
 
+/**
+ * Sets up theme toggle button event listeners
+ * @returns {Function} Cleanup function to remove listeners
+ */
 const setupThemeToggles = () => {
-  const buttons = Array.from(document.querySelectorAll('.theme-toggle'));
+  const buttons = document.querySelectorAll('.theme-toggle');
 
   if (buttons.length === 0) {
     return () => {};
@@ -72,6 +114,11 @@ const setupThemeToggles = () => {
   };
 };
 
+/**
+ * Sets up mobile navigation menu interactions
+ * Handles menu toggle, outside clicks, and keyboard navigation
+ * @returns {Function} Cleanup function to remove listeners
+ */
 const setupMobileNavigation = () => {
   const navToggle = document.getElementById('mobile-nav-toggle');
   const navMenu = document.getElementById('mobile-nav-menu');
@@ -80,7 +127,7 @@ const setupMobileNavigation = () => {
     return () => {};
   }
 
-  const links = Array.from(navMenu.querySelectorAll('a'));
+  const links = navMenu.querySelectorAll('a');
 
   const openMenu = () => {
     navMenu.classList.add('is-open');
@@ -93,31 +140,35 @@ const setupMobileNavigation = () => {
   };
 
   const toggleMenu = () => {
-    if (navMenu.classList.contains('is-open')) {
-      closeMenu();
-    } else {
-      openMenu();
-    }
+    navMenu.classList.contains('is-open') ? closeMenu() : openMenu();
   };
 
   const handleDocumentClick = (event) => {
-    const target = event.target;
     if (!navMenu.classList.contains('is-open')) return;
-    if (target && (navMenu.contains(target) || navToggle.contains(target))) return;
-    closeMenu();
+
+    const target = event.target;
+    const isInsideMenu = navMenu.contains(target);
+    const isToggleButton = navToggle.contains(target);
+
+    if (!isInsideMenu && !isToggleButton) {
+      closeMenu();
+    }
   };
 
   const handleDocumentKeydown = (event) => {
     if (event.key === 'Escape' && navMenu.classList.contains('is-open')) {
       closeMenu();
+      navToggle.focus(); // Return focus to toggle button for better a11y
     }
   };
 
+  // Event listeners
   navToggle.addEventListener('click', toggleMenu);
   links.forEach((link) => link.addEventListener('click', closeMenu));
   document.addEventListener('click', handleDocumentClick);
   document.addEventListener('keydown', handleDocumentKeydown);
 
+  // Cleanup function
   return () => {
     navToggle.removeEventListener('click', toggleMenu);
     links.forEach((link) => link.removeEventListener('click', closeMenu));
@@ -126,15 +177,22 @@ const setupMobileNavigation = () => {
   };
 };
 
+/**
+ * Sets up back-to-top button interactions
+ * Shows button after scrolling down 300px
+ * @returns {Function} Cleanup function to remove listeners
+ */
 const setupBackToTop = () => {
   const backToTopBtn = document.getElementById('back-to-top');
 
   if (!backToTopBtn) {
     return () => {};
   }
 
+  const SCROLL_THRESHOLD = 300;
+
   const toggleVisibility = () => {
-    if (window.scrollY > 300) {
+    if (window.scrollY > SCROLL_THRESHOLD) {
       backToTopBtn.classList.add('visible');
     } else {
       backToTopBtn.classList.remove('visible');
@@ -148,58 +206,83 @@ const setupBackToTop = () => {
     });
   };
 
+  // Set initial visibility
   toggleVisibility();
 
+  // Event listeners with passive flag for better scroll performance
   window.addEventListener('scroll', toggleVisibility, { passive: true });
   backToTopBtn.addEventListener('click', scrollToTop);
 
+  // Cleanup function
   return () => {
     window.removeEventListener('scroll', toggleVisibility);
     backToTopBtn.removeEventListener('click', scrollToTop);
   };
 };
 
-let teardownNav;
-let teardownTheme;
-let teardownBackToTop;
+// Store cleanup functions for proper listener management with View Transitions
+let teardownNav = null;
+let teardownTheme = null;
+let teardownBackToTop = null;
 
+/**
+ * Main initialization function for progressive enhancement
+ * Called on initial page load and after each View Transition
+ *
+ * This function:
+ * 1. Syncs theme icons with current state
+ * 2. Cleans up old event listeners
+ * 3. Sets up new event listeners for the current page
+ */
 const enhance = () => {
-  const currentAttr = document.documentElement.getAttribute('data-theme');
-  syncThemeIcons(currentAttr === 'light' ? 'light' : 'dark');
-  if (teardownTheme) {
-    teardownTheme();
-  }
+  // Ensure theme icons match the current theme
+  const currentTheme = document.documentElement.getAttribute('data-theme') || THEME_DARK;
+  syncThemeIcons(currentTheme === THEME_LIGHT ? THEME_LIGHT : THEME_DARK);
+
+  // Clean up existing listeners before setting up new ones
+  // This prevents memory leaks and duplicate event handlers
+  if (teardownTheme) teardownTheme();
+  if (teardownNav) teardownNav();
+  if (teardownBackToTop) teardownBackToTop();
+
+  // Setup new listeners for the current page
   teardownTheme = setupThemeToggles();
-  if (teardownNav) {
-    teardownNav();
-  }
   teardownNav = setupMobileNavigation();
-  if (teardownBackToTop) {
-    teardownBackToTop();
-  }
   teardownBackToTop = setupBackToTop();
 };
 
+// Initialize on DOM ready
 if (document.readyState === 'complete' || document.readyState === 'interactive') {
   enhance();
 } else {
   document.addEventListener('DOMContentLoaded', enhance, { once: true });
 }
 
+/**
+ * Astro View Transitions lifecycle hooks
+ *
+ * Best practices for Astro View Transitions:
+ * - Use astro:page-load for main initialization (fires after transition completes)
+ * - Use astro:after-swap for immediate DOM updates (fires right after DOM swap)
+ * - Use astro:before-preparation for cleanup before transition starts
+ */
+
+// Re-initialize after each page transition
 document.addEventListener('astro:page-load', enhance);
+
+// Also run after DOM swap for faster perceived performance
 document.addEventListener('astro:after-swap', enhance);
 
-// Close mobile menu on navigation
+// Clean up mobile menu state before page transitions
 document.addEventListener('astro:before-preparation', () => {
   const navMenu = document.getElementById('mobile-nav-menu');
   const navToggle = document.getElementById('mobile-nav-toggle');
 
-  if (navMenu && navMenu.classList.contains('is-open')) {
+  if (navMenu?.classList.contains('is-open')) {
     navMenu.classList.remove('is-open');
-    if (navToggle) {
-      navToggle.setAttribute('aria-expanded', 'false');
-    }
+    navToggle?.setAttribute('aria-expanded', 'false');
   }
 });
 
+// ESM export to ensure this is treated as a module
 export {};