Add auto-hide navigation with opt-out and simplify ScrollProgress

- Install headroom.js (1.5 kB) for scroll-aware navigation behavior
- Desktop nav slides up, mobile nav slides down on scroll with 50px threshold
- Egyptian water easing (0.4s) and prefers-reduced-motion support
- Opt-out mechanism: homepage and contact keep nav always visible
- Simplify ScrollProgress to official Astro astro:page-load pattern
- Page-controlled ScrollProgress via showScrollProgress prop
- Enable on About, Resume, and case study pages only

Author: saadshahd

bun.lock

@@ -6,6 +6,7 @@
     "@tailwindcss/typography": "^0.5.19",
     "@tailwindcss/vite": "^4.1.16",
     "@types/bun": "latest",
+    "@types/headroom": "^0.12.4",
     "astro": "^5.15.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -24,8 +25,11 @@
   },
   "type": "module",
   "dependencies": {
+    "@astrojs/mdx": "^4.3.9",
     "@lucide/astro": "^0.548.0",
     "@northstarthemes/astrobook": "^0.11.1",
+    "astro-mermaid": "^1.1.0",
+    "headroom.js": "^0.12.0",
     "motion": "^12.23.24",
     "shiki": "^3.13.0"
   }

package.json

@@ -21,19 +21,9 @@
   import { scroll, animate } from "motion";
   import { prefersReducedMotion } from "../../utils/animations";
 
-  function initScrollProgress() {
+  document.addEventListener('astro:page-load', () => {
     const progressBar = document.querySelector('.scroll-progress');
-
-    if (!progressBar || !(progressBar instanceof HTMLElement)) {
-      console.warn('ScrollProgress: Progress bar element not found');
-      return;
-    }
-
-    // Skip if already initialized
-    if (progressBar.dataset.scrollInit === 'true') {
-      return;
-    }
-    progressBar.dataset.scrollInit = 'true';
+    if (!progressBar || !(progressBar instanceof HTMLElement)) return;
 
     // If user prefers reduced motion, show full bar instantly
     if (prefersReducedMotion()) {
@@ -42,34 +32,10 @@
     }
 
     // Animate scaleX based on scroll position
-    try {
-      scroll(
-        animate(progressBar, { scaleX: [0, 1] }),
-        {
-          target: document.documentElement,
-          offset: ['start start', 'end end']
-        }
-      );
-    } catch (error) {
-      console.error('ScrollProgress: Failed to initialize scroll animation', error);
-    }
-  }
-
-  // Run on initial load
-  if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', initScrollProgress);
-  } else {
-    initScrollProgress();
-  }
-
-  // Re-run after Astro View Transitions
-  document.addEventListener('astro:page-load', () => {
-    // Reset initialization flag to allow reinit
-    const progressBar = document.querySelector('.scroll-progress');
-    if (progressBar instanceof HTMLElement) {
-      delete progressBar.dataset.scrollInit;
-    }
-    initScrollProgress();
+    scroll(
+      animate(progressBar, { scaleX: [0, 1] }),
+      { target: document.documentElement, offset: ['start start', 'end end'] }
+    );
   });
 </script>
 

src/components/animations/ScrollProgress.astro

@@ -1,16 +1,57 @@
 ---
 // BottomTabBar - Composable mobile navigation container
 // Purely structural, accepts TabItem children for flexibility
+
+interface Props {
+  disableAutoHide?: boolean;
+}
+
+const { disableAutoHide = false } = Astro.props;
 ---
 
 <nav
-  class="fixed bottom-0 left-0 right-0 z-50 md:hidden
+  id="mobile-nav"
+  class="headroom headroom--mobile fixed bottom-0 left-0 right-0 z-50 md:hidden
          bg-surface/95 backdrop-blur-md border-t border-neutral-lighter
          h-16 pb-safe"
   role="navigation"
   aria-label="Mobile navigation"
+  data-disable-auto-hide={disableAutoHide}
 >
   <div class="flex items-center justify-around h-full px-4">
     <slot />
   </div>
 </nav>
+
+<script>
+  import Headroom from 'headroom.js';
+
+  let headroomInstance: Headroom | null = null;
+
+  document.addEventListener('astro:page-load', () => {
+    const nav = document.getElementById('mobile-nav');
+    if (!nav) return;
+
+    // Check if page opted out of auto-hide behavior
+    const disableAutoHide = nav.dataset.disableAutoHide === 'true';
+
+    // Destroy previous instance to prevent memory leaks
+    if (headroomInstance) {
+      headroomInstance.destroy();
+      headroomInstance = null;
+    }
+
+    // Skip initialization if page disabled auto-hide
+    if (disableAutoHide) return;
+
+    // Initialize headroom with same settings as desktop
+    headroomInstance = new Headroom(nav, {
+      offset: 50,         // Hide after scrolling down 50px
+      tolerance: {
+        up: 10,           // Show after scrolling up 10px
+        down: 10          // Hide after scrolling down 10px past offset
+      }
+    });
+    headroomInstance.init();
+  });
+</script>

src/components/navigation/BottomTabBar.astro

@@ -14,12 +14,16 @@ interface Props {
   title: string;
   description?: string;
   ogImage?: string;
+  showScrollProgress?: boolean;
+  disableAutoHideNav?: boolean;
 }
 
 const {
   title,
   description = 'Building realtime systems that scale through functional architecture and separation of concerns',
-  ogImage = '/og-image.png'
+  ogImage = '/og-image.png',
+  showScrollProgress = false,
+  disableAutoHideNav = false
 } = Astro.props;
 
 const currentPath = Astro.url.pathname;
@@ -92,13 +96,47 @@ const ogImageURL = new URL(ogImage, Astro.site);
         });
       });
     </script>
+
+    <!-- Auto-hide desktop navigation on scroll -->
+    <script>
+      import Headroom from 'headroom.js';
+
+      let headroomInstance: Headroom | null = null;
+
+      document.addEventListener('astro:page-load', () => {
+        const nav = document.getElementById('desktop-nav');
+        if (!nav) return;
+
+        // Check if page opted out of auto-hide behavior
+        const disableAutoHide = nav.dataset.disableAutoHide === 'true';
+
+        // Destroy previous instance to prevent memory leaks
+        if (headroomInstance) {
+          headroomInstance.destroy();
+          headroomInstance = null;
+        }
+
+        // Skip initialization if page disabled auto-hide
+        if (disableAutoHide) return;
+
+        // Initialize headroom with threshold and tolerance settings
+        headroomInstance = new Headroom(nav, {
+          offset: 50,         // Hide after scrolling down 50px
+          tolerance: {
+            up: 10,           // Show after scrolling up 10px
+            down: 10          // Hide after scrolling down 10px past offset
+          }
+        });
+        headroomInstance.init();
+      });
+    </script>
   </head>
   <body class="bg-background text-text antialiased">
-    <!-- Scroll Progress Indicator (reading pages only, not homepage) -->
-    {currentPath !== '/' && <ScrollProgress />}
+    <!-- Scroll Progress Indicator (long-form content pages only) -->
+    {showScrollProgress && <ScrollProgress />}
 
     <!-- Responsive Navigation: Mobile circular badge → Desktop bar -->
-    <nav class="md:fixed md:mt-0 mt-8 top-2 left-2 right-2 max-w-6xl mx-auto z-50 rounded-full md:bg-surface/60 md:backdrop-blur-lg flex items-center justify-center border border-neutral-lighter">
+    <nav id="desktop-nav" class="headroom md:fixed md:mt-0 mt-8 top-2 left-2 right-2 max-w-6xl mx-auto z-50 rounded-full md:bg-surface/80 md:backdrop-blur-lg flex items-center justify-center border border-neutral-lighter" data-disable-auto-hide={disableAutoHideNav}>
       <div class="flex items-center justify-center md:justify-between w-full px-4">
         <a href="/" class="hover:opacity-80 transition-opacity">
           <SSLogo />
@@ -115,7 +153,7 @@ const ogImageURL = new URL(ogImage, Astro.site);
     </nav>
 
     <!-- Mobile Bottom Tab Bar -->
-    <BottomTabBar>
+    <BottomTabBar disableAutoHide={disableAutoHideNav}>
       <TabItem href="/" active={currentPath === '/'} label="Home">
         <House size={24} />
       </TabItem>

src/layouts/Layout.astro

@@ -7,7 +7,7 @@ import Body from '../components/typography/Body.astro';
 import { FileText } from '@lucide/astro';
 ---
 
-<Layout title="About - Saad Shahd">
+<Layout title="About - Saad Shahd" showScrollProgress={true}>
   <Container width="narrow">
     <Heading level={1} as="h1" class="mb-16"><span>About</span></Heading>
 

src/pages/about.astro

@@ -5,7 +5,7 @@ import Body from '../components/typography/Body.astro';
 import Link from '../components/Link.astro';
 ---
 
-<Layout title="Contact - Saad Shahd">
+<Layout title="Contact - Saad Shahd" disableAutoHideNav={true}>
   <div class="max-w-4xl mx-auto px-4 md:px-6 py-20">
     <Heading level={1} as="h1" class="mb-16"><span>Get in Touch</span></Heading>
     <Body size="lg" as="p" class="text-neutral mb-16 leading-normal">

src/pages/contact.astro

@@ -6,7 +6,7 @@ import Display from '../components/typography/Display.astro';
 import Body from '../components/typography/Body.astro';
 ---
 
-<Layout title="Saad Shahd - Software Engineer">
+<Layout title="Saad Shahd - Software Engineer" disableAutoHideNav={true}>
   <!-- Centered content on top of patterns -->
   <Container width="default" spacing="hero" class="relative flex flex-col justify-center items-center" style="z-index: 1;">
     <section class="w-full flex flex-col items-center text-center">