feat(docs): improve table of contents functionality

Author: auswm85

apps/docs/src/components/navigation/TableOfContents.astro

@@ -36,48 +36,40 @@ const tocHeadings = filterTocHeadings(headings);
 		const tocLinks = document.querySelectorAll('[data-toc-link]');
 		if (tocLinks.length === 0) return;
 
-		const headingIds = Array.from(tocLinks).map((link) => {
-			const href = link.getAttribute('href');
-			return href ? href.slice(1) : '';
-		});
-
-		const headings = headingIds
-			.map((id) => document.getElementById(id))
-			.filter((el): el is HTMLElement => el !== null);
-
-		if (headings.length === 0) return;
-
-		const observer = new IntersectionObserver(
-			(entries) => {
-				// Find the first visible heading
-				const visibleEntry = entries.find((entry) => entry.isIntersecting);
+		function updateFromHash() {
+			const hash = window.location.hash || '';
+			tocLinks.forEach((link, index) => {
+				const href = link.getAttribute('href');
+				// Match hash, or default to first link if no hash
+				const isActive = hash ? href === hash : index === 0;
+				link.setAttribute('aria-current', isActive ? 'true' : 'false');
+			});
+		}
 
-				if (visibleEntry) {
-					const id = visibleEntry.target.id;
+		// Update on click (immediately, before hash changes)
+		tocLinks.forEach((link, index) => {
+			link.addEventListener('click', (e) => {
+				tocLinks.forEach((l) => l.setAttribute('aria-current', 'false'));
+				link.setAttribute('aria-current', 'true');
 
-					// Update aria-current on all links
-					tocLinks.forEach((link) => {
-						const href = link.getAttribute('href');
-						const isActive = href === `#${id}`;
-						link.setAttribute('aria-current', isActive ? 'true' : 'false');
-					});
+				// First link scrolls to top of page
+				if (index === 0) {
+					e.preventDefault();
+					window.scrollTo({ top: 0, behavior: 'smooth' });
+					history.pushState(null, '', link.getAttribute('href') || '');
 				}
-			},
-			{
-				rootMargin: '-80px 0px -70% 0px',
-				threshold: 0,
-			}
-		);
-
-		headings.forEach((heading) => {
-			observer.observe(heading);
+			});
 		});
 
+		// Initial state and hash changes
+		updateFromHash();
+		window.addEventListener('hashchange', updateFromHash);
+
 		// Cleanup on page transitions
 		document.addEventListener(
 			'astro:before-swap',
 			() => {
-				observer.disconnect();
+				window.removeEventListener('hashchange', updateFromHash);
 			},
 			{ once: true }
 		);

apps/docs/src/styles/docs.css

@@ -2,6 +2,20 @@
  * Shift CSS Documentation Layout Styles
  */
 
+/* =============================================================================
+   Smooth Scrolling & Performance
+   ============================================================================= */
+
+html {
+	scroll-behavior: smooth;
+}
+
+@media (prefers-reduced-motion: reduce) {
+	html {
+		scroll-behavior: auto;
+	}
+}
+
 /* =============================================================================
    CSS Custom Properties
    ============================================================================= */
@@ -37,6 +51,7 @@
 @media (min-width: 1024px) {
 	.docs-layout {
 		grid-template-columns: var(--docs-sidebar-width) 1fr var(--docs-toc-width);
+		align-items: start;
 	}
 }
 
@@ -55,7 +70,7 @@
 	padding-inline: var(--docs-gutter);
 	background: var(--s-surface-base);
 	border-bottom: 1px solid var(--s-border-default);
-	backdrop-filter: blur(8px);
+	transform: translateZ(0); /* GPU acceleration */
 }
 
 @media (min-width: 768px) {
@@ -174,25 +189,29 @@
 
 .docs-toc {
 	display: none;
-	position: sticky;
-	top: var(--docs-header-height);
-	height: calc(100vh - var(--docs-header-height));
-	overflow-y: auto;
-	padding: var(--docs-gutter);
-	font-size: var(--s-text-sm);
-
-	/* Hide scrollbar but keep functionality */
-	scrollbar-width: none; /* Firefox */
-	-ms-overflow-style: none; /* IE/Edge */
-}
-
-.docs-toc::-webkit-scrollbar {
-	display: none; /* Chrome, Safari, Opera */
 }
 
 @media (min-width: 1024px) {
 	.docs-toc {
 		display: block;
+		position: fixed;
+		top: var(--docs-header-height);
+		right: 0;
+		width: var(--docs-toc-width);
+		max-height: calc(100vh - var(--docs-header-height));
+		overflow-y: auto;
+		padding: var(--docs-gutter);
+		padding-bottom: var(--s-space-16);
+		font-size: var(--s-text-sm);
+		transform: translateZ(0); /* GPU acceleration */
+
+		/* Hide scrollbar but keep functionality */
+		scrollbar-width: none; /* Firefox */
+		-ms-overflow-style: none; /* IE/Edge */
+	}
+
+	.docs-toc::-webkit-scrollbar {
+		display: none; /* Chrome, Safari, Opera */
 	}
 }