From 7cb3caf15830956348fc96e5f8c9f66972b792d9 Mon Sep 17 00:00:00 2001
From: opentabs-dev <260357279+opentabs-dev@users.noreply.github.com>
Date: Sat, 21 Feb 2026 10:19:15 -0800
Subject: [PATCH] fix: prevent sidebar jitter, scroll passthrough, and nav
 z-index overlap

Three related bugs fixed:

1. Sidebar jitter on scroll
   sticky + self-start in a flex container causes 1-2px drift each frame
   as the browser recalculates position. Fixed by making the sidebar fixed
   so it is composited independently of page scroll. left tracks the
   max-w-7xl centered container via max(0px, (100vw - 80rem) / 2).

2. Scroll passthrough on sidebar and TOC
   overflow-y-auto only intercepts wheel events when content overflows.
   Hovering over gaps between items or on a short sidebar sends scroll
   to the page instead. Fixed with overflow-y-scroll (always a scroll
   container) and overscroll-y-contain (no chaining at boundaries).
   sidebar-scroll already hides the forced scrollbar track visually.

3. TopNav z-index too low (z-1)
   Page content with higher z-index (copy buttons, etc.) rendered over
   the sticky nav while scrolling. Fixed by raising nav to z-50.

Files changed:
- app/(docs)/docs/layout.tsx
- components/SideNav.tsx
- components/TableOfContents.tsx
- components/TopNav.tsx
---
 app/(docs)/docs/layout.tsx     | 20 +++++++++++---------
 components/SideNav.tsx         |  4 ++--
 components/TableOfContents.tsx |  2 +-
 components/TopNav.tsx          |  2 +-
 4 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/app/(docs)/docs/layout.tsx b/app/(docs)/docs/layout.tsx
index 6696c78..b6ee836 100644
--- a/app/(docs)/docs/layout.tsx
+++ b/app/(docs)/docs/layout.tsx
@@ -11,15 +11,17 @@ export default function ComponentLayout({
   children: React.ReactNode;
 }>) {
   return (
-    <div className="relative max-w-7xl mx-auto">
-      <div className="max-lg:px-4">
-        <div className="flex lg:gap-20 items-start">
-          {/* Sidebar */}
-          <div className="hidden lg:block w-60 flex-shrink-0 sticky top-28 self-start">
-            <SideNav />
-          </div>
-          {children}
-        </div>
+    <div className="mx-auto max-w-7xl">
+      {/* Sidebar — fixed to the viewport, left-aligned with the max-w-7xl (80rem)
+          centered container. On screens narrower than 80rem, left is 0. */}
+      <div className="fixed top-28 hidden h-[calc(100vh-7rem)] w-60 lg:left-[max(0px,calc((100vw-80rem)/2))] lg:block">
+        <SideNav />
+      </div>
+
+      {/* Content area — pl-80 reserves space for the fixed sidebar (w-60) + gap (20).
+          No independent centering: the parent max-w-7xl is the single source of truth. */}
+      <div className="flex w-full items-start max-lg:px-4 lg:gap-20 lg:pl-80">
+        {children}
       </div>
     </div>
   );
diff --git a/components/SideNav.tsx b/components/SideNav.tsx
index 233a243..668412c 100644
--- a/components/SideNav.tsx
+++ b/components/SideNav.tsx
@@ -13,9 +13,9 @@ export default function SideNav({ setIsOpen }: SideNavProps) {
   const pathname = usePathname();
 
   return (
-    <div className="sidebar-scroll border-r-2 z-10 overflow-y-scroll h-full max-h-[calc(100vh-6rem)] transition-transform transform md:translate-x-0 w-full bg-background flex flex-col justify-start md:justify-start py-8">
+    <div className="sidebar-scroll border-r-2 overflow-y-scroll overscroll-y-contain h-full w-full bg-background flex flex-col justify-start py-8">
       <nav
-        className="flex flex-col items-start max-lg:px-6 space-y-4 z-99"
+        className="flex flex-col items-start max-lg:px-6 space-y-4"
         aria-label="Main navigation"
       >
         {navConfig.sideNavItems.map((item) => (
diff --git a/components/TableOfContents.tsx b/components/TableOfContents.tsx
index 3d3c2ea..8a99f80 100644
--- a/components/TableOfContents.tsx
+++ b/components/TableOfContents.tsx
@@ -31,7 +31,7 @@ export default function TableOfContents({ toc }: TableOfContentsProps) {
   }
 
   return (
-    <div className="border p-4 rounded-sm max-h-60 overflow-y-auto sidebar-scroll">
+    <div className="border p-4 rounded-sm max-h-60 overflow-y-scroll overscroll-y-contain sidebar-scroll">
       <h3 className="mb-3 border-b border-black pb-2">
         On this Page
       </h3>
diff --git a/components/TopNav.tsx b/components/TopNav.tsx
index 1d70fb1..dd3f776 100644
--- a/components/TopNav.tsx
+++ b/components/TopNav.tsx
@@ -12,7 +12,7 @@ export default function TopNav() {
   const { isDarkMode, toggleDarkMode } = useTheme();
 
   return (
-    <nav className="sticky z-1 top-0 right-0 w-full border-b-2 bg-background">
+    <nav className="sticky z-50 top-0 right-0 w-full border-b-2 bg-background">
       <div className="w-full bg-black text-white">
         <div className="container max-w-6xl mx-auto px-4 py-2 flex justify-center space-x-4 items-center">
           <Text className="text-sm lg:text-center">