feat(api-docs): add scroll-to-top button and improve navigation

- Add floating scroll-to-top button that appears when scrolling down
- Make TOC category titles clickable links to their sections
- Remove sticky positioning from package header for better scroll behavior
- Adjust scroll-margin-top values for consistent anchor positioning

Author: lambdalisue

static/style.css

@@ -1288,19 +1288,18 @@ body:has(.api-layout) .global-header {
 
 /* Package Header */
 .package-header {
-  position: sticky;
-  top: 0;
+  position: relative;
   display: flex;
   align-items: center;
   justify-content: space-between;
   flex-wrap: wrap;
   gap: 1rem;
   margin: -2.5rem -2.5rem 1.5rem -2.5rem;
   padding: 1.5rem 2.5rem;
+  padding-bottom: 2.5rem;
   background: var(--bg-card);
   border-bottom: 1px solid var(--border);
   border-radius: 16px 16px 0 0;
-  z-index: 100;
 }
 
 .package-header h1 {
@@ -1569,14 +1568,15 @@ body:has(.api-layout) .global-header {
   font-size: 1.5rem;
   color: var(--text-heading);
   margin: 0 0 1.5rem;
+  scroll-margin-top: 6rem;
 }
 
 /* API Item (Function, Class, Interface, etc.) */
 .api-item {
   margin-bottom: 2.5rem;
   padding-bottom: 2rem;
   border-bottom: 1px solid var(--border);
-  scroll-margin-top: 7rem;
+  scroll-margin-top: 6rem;
 }
 
 .api-item:last-child {
@@ -1911,7 +1911,7 @@ body:has(.api-layout) .global-header {
 .property-item {
   padding: 0.75rem 0;
   border-bottom: 1px solid var(--border);
-  scroll-margin-top: 7rem;
+  scroll-margin-top: 6rem;
 }
 
 .property-item:last-child {
@@ -2235,7 +2235,7 @@ body:has(.api-layout) .global-header {
   margin-bottom: 1rem;
   padding-bottom: 1rem;
   border-bottom: 1px dashed var(--border);
-  scroll-margin-top: 7rem;
+  scroll-margin-top: 6rem;
 }
 
 .method-item:last-child {
@@ -2284,6 +2284,16 @@ body:has(.api-layout) .global-header {
   font-weight: 600;
 }
 
+.toc-group h4 a {
+  color: inherit;
+  text-decoration: none;
+  transition: color 0.15s;
+}
+
+.toc-group h4 a:hover {
+  color: var(--accent);
+}
+
 .toc-group ul {
   list-style: none;
   margin: 0;
@@ -2964,3 +2974,58 @@ body:has(.api-layout) .global-header {
 #search-container .pagefind-ui__result-nested .pagefind-ui__result-excerpt {
   -webkit-line-clamp: 1;
 }
+
+/* ============================================================================
+   Scroll to Top Button
+   ============================================================================ */
+
+.scroll-to-top {
+  position: fixed;
+  bottom: 2rem;
+  right: 2rem;
+  width: 48px;
+  height: 48px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--accent);
+  color: white;
+  border: none;
+  border-radius: 50%;
+  cursor: pointer;
+  opacity: 0;
+  visibility: hidden;
+  transform: translateY(10px);
+  transition: opacity 0.2s, visibility 0.2s, transform 0.2s, background 0.2s;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+  z-index: 1000;
+}
+
+.scroll-to-top:hover {
+  background: var(--accent-hover);
+  transform: translateY(-2px);
+  box-shadow: 0 6px 16px rgba(0, 0, 0, 0.2);
+}
+
+.scroll-to-top.visible {
+  opacity: 1;
+  visibility: visible;
+  transform: translateY(0);
+}
+
+.scroll-to-top i {
+  font-size: 1.5rem;
+}
+
+@media (max-width: 768px) {
+  .scroll-to-top {
+    bottom: 1rem;
+    right: 1rem;
+    width: 40px;
+    height: 40px;
+  }
+
+  .scroll-to-top i {
+    font-size: 1.25rem;
+  }
+}

templates/Layout.tsx

@@ -122,8 +122,10 @@ export function Layout(
         <Header showLogo={showLogo} />
         {children}
         <SearchModal />
+        <ScrollToTop />
         <script src={`${basePath}/pagefind/pagefind-ui.js`} />
         <script dangerouslySetInnerHTML={{ __html: searchScript }} />
+        <script dangerouslySetInnerHTML={{ __html: scrollToTopScript }} />
       </body>
     </html>
   );
@@ -154,6 +156,35 @@ function SearchModal() {
   );
 }
 
+function ScrollToTop() {
+  return (
+    <button
+      type="button"
+      id="scroll-to-top"
+      class="scroll-to-top"
+      onclick="scrollToTop()"
+      aria-label="Scroll to top"
+    >
+      <i class="ti ti-chevron-up" />
+    </button>
+  );
+}
+
+const scrollToTopScript = `
+function scrollToTop() {
+  window.scrollTo({ top: 0, behavior: 'smooth' });
+}
+
+window.addEventListener('scroll', () => {
+  const btn = document.getElementById('scroll-to-top');
+  if (window.scrollY > 300) {
+    btn.classList.add('visible');
+  } else {
+    btn.classList.remove('visible');
+  }
+});
+`;
+
 const searchScript = `
 let searchInitialized = false;
 

templates/api/ApiPage.tsx

@@ -237,7 +237,7 @@ export async function PackagePage({ packageName }: PackagePageProps) {
                 {/* Render each kind group */}
                 {orderedKinds.map((kind) => (
                   <section key={kind} class="api-kind-section">
-                    <h2>{kindToTitle(kind)}</h2>
+                    <h2 id={kindInfoMap[kind]?.id}>{kindToTitle(kind)}</h2>
                     {grouped[kind].map((node) => {
                       const key = `${node.kind}:${node.name}`;
                       const overloads = overloadMap.get(key);
@@ -279,13 +279,21 @@ interface KindInfo {
   icon: string;
 }
 
-const kindInfoMap: Record<string, KindInfo> = {
-  class: { title: "Classes", icon: "ti-box" },
-  interface: { title: "Interfaces", icon: "ti-puzzle" },
-  function: { title: "Functions", icon: "ti-code" },
-  typeAlias: { title: "Type Aliases", icon: "ti-tag" },
-  variable: { title: "Variables", icon: "ti-variable" },
-  enum: { title: "Enums", icon: "ti-list" },
+const kindInfoMap: Record<string, KindInfo & { id: string }> = {
+  class: { title: "Classes", icon: "ti-box", id: "category-classes" },
+  interface: {
+    title: "Interfaces",
+    icon: "ti-puzzle",
+    id: "category-interfaces",
+  },
+  function: { title: "Functions", icon: "ti-code", id: "category-functions" },
+  typeAlias: { title: "Types", icon: "ti-tag", id: "category-types" },
+  variable: {
+    title: "Variables",
+    icon: "ti-variable",
+    id: "category-variables",
+  },
+  enum: { title: "Enums", icon: "ti-list", id: "category-enums" },
 };
 
 function kindToTitle(kind: string) {

templates/api/components.tsx

@@ -1453,11 +1453,15 @@ interface TocGroupProps {
 function TocGroup({ title, icon, items }: TocGroupProps) {
   // Sort items alphabetically to match content order
   const sortedItems = [...items].sort((a, b) => a.name.localeCompare(b.name));
+  // Create anchor ID from title (e.g., "Classes" -> "category-classes")
+  const anchorId = `category-${title.toLowerCase()}`;
 
   return (
     <div class="toc-group">
       <h4>
-        <i class={`ti ${icon}`} /> {title}
+        <a href={`#${anchorId}`}>
+          <i class={`ti ${icon}`} /> {title}
+        </a>
       </h4>
       <ul>
         {sortedItems.map((item) => (