From 274255b198789a01ab6d4c3a7390cfcb5b65fda6 Mon Sep 17 00:00:00 2001
From: alex <alex.xinliu@outlook.com>
Date: Mon, 2 Nov 2026 10:05:26 +0800
Subject: [PATCH] Highlight the current section in "On this page" as you scroll

The lesson, docs, and legal page tables of contents now mark the section
the reader is on and follow along while scrolling.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/web/src/app/components/LegalPage.tsx     | 11 ++--
 .../src/app/components/TableOfContents.tsx    | 52 +++++++++++++++++++
 .../app/components/docs/ContentArticle.tsx    | 18 +++----
 apps/web/src/app/globals.css                  |  5 ++
 4 files changed, 69 insertions(+), 17 deletions(-)
 create mode 100644 apps/web/src/app/components/TableOfContents.tsx

diff --git a/apps/web/src/app/components/LegalPage.tsx b/apps/web/src/app/components/LegalPage.tsx
index 8b24264..685022a 100644
--- a/apps/web/src/app/components/LegalPage.tsx
+++ b/apps/web/src/app/components/LegalPage.tsx
@@ -1,6 +1,7 @@
 import Link from "next/link";
 import type { ReactNode } from "react";
 import { PublicHeader } from "@/app/components/PublicHeader";
+import { TableOfContents } from "@/app/components/TableOfContents";
 import { formatDate, localePath, type Locale } from "@/i18n/config";
 import { getDictionary } from "@/i18n/messages";
 
@@ -47,13 +48,7 @@ export function LegalPage({ locale, document, effectiveDate }: LegalPageProps) {
       <section className="site-wrap grid gap-10 pb-20 lg:grid-cols-[220px_1fr]">
         <aside className="lg:sticky lg:top-24 lg:self-start">
           <p className="text-xs font-semibold uppercase tracking-[0.14em] text-[var(--ink-3)]">{t.onThisPage}</p>
-          <nav className="site-toc mt-3">
-            {document.sections.map((section) => (
-              <a key={section.id} href={`#${section.id}`}>
-                {section.title}
-              </a>
-            ))}
-          </nav>
+          <TableOfContents className="mt-3" items={document.sections.map((section) => ({ id: section.id, label: section.title }))} />
           <p className="mt-8 text-xs font-semibold uppercase tracking-[0.14em] text-[var(--ink-3)]">{t.related}</p>
           <nav className="site-toc mt-3">
             {legalLinks.map((link) => (
@@ -66,7 +61,7 @@ export function LegalPage({ locale, document, effectiveDate }: LegalPageProps) {
 
         <article className="site-card site-prose max-w-3xl p-6 md:p-10">
           {document.sections.map((section) => (
-            <section key={section.id} id={section.id}>
+            <section key={section.id} id={section.id} className="scroll-mt-24">
               <h2>{section.title}</h2>
               {section.content}
             </section>
diff --git a/apps/web/src/app/components/TableOfContents.tsx b/apps/web/src/app/components/TableOfContents.tsx
new file mode 100644
index 0000000..4aac230
--- /dev/null
+++ b/apps/web/src/app/components/TableOfContents.tsx
@@ -0,0 +1,52 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export type TocItem = { id: string; label: string };
+
+// A section becomes current once its top crosses this line, just under the sticky header.
+const activationLine = 120;
+
+export function TableOfContents({ items, className = "" }: { items: TocItem[]; className?: string }) {
+  const [activeId, setActiveId] = useState(items[0]?.id);
+
+  useEffect(() => {
+    const sections = items.flatMap((item) => document.getElementById(item.id) ?? []);
+    if (!sections.length) return;
+
+    let frame = 0;
+    const update = () => {
+      frame = 0;
+      const atBottom = window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2;
+      // Short closing sections can never reach the line, so at the bottom take the last one on screen.
+      const line = atBottom ? window.innerHeight : activationLine;
+      let current = sections[0];
+      for (const section of sections) {
+        if (section.getBoundingClientRect().top <= line) current = section;
+      }
+      setActiveId(current.id);
+    };
+    const schedule = () => {
+      if (!frame) frame = requestAnimationFrame(update);
+    };
+
+    update();
+    window.addEventListener("scroll", schedule, { passive: true });
+    window.addEventListener("resize", schedule);
+    return () => {
+      cancelAnimationFrame(frame);
+      window.removeEventListener("scroll", schedule);
+      window.removeEventListener("resize", schedule);
+    };
+  }, [items]);
+
+  return (
+    <nav className={`site-toc ${className}`}>
+      {items.map((item) => (
+        <a key={item.id} href={`#${item.id}`} aria-current={item.id === activeId ? "location" : undefined}>
+          {item.label}
+        </a>
+      ))}
+    </nav>
+  );
+}
diff --git a/apps/web/src/app/components/docs/ContentArticle.tsx b/apps/web/src/app/components/docs/ContentArticle.tsx
index 3b70dcd..f4d51ea 100644
--- a/apps/web/src/app/components/docs/ContentArticle.tsx
+++ b/apps/web/src/app/components/docs/ContentArticle.tsx
@@ -3,6 +3,7 @@ import { ArrowLeft, ArrowRight, Play } from "lucide-react";
 import { getLessonCourse } from "@/lib/lesson-syllabi";
 import { CourseReferences } from "./CourseReferences";
 import { PublicHeader } from "@/app/components/PublicHeader";
+import { TableOfContents } from "@/app/components/TableOfContents";
 import { DocSectionView } from "./DocSectionView";
 import { RichText } from "./DiagramBlocks";
 import { formatDate, localePath, localeTags, localeUrl, type Locale } from "@/i18n/config";
@@ -218,15 +219,14 @@ export function ContentArticle({ locale, doc }: { locale: Locale; doc: Doc }) {
         <aside className="max-xl:hidden">
           <div className="sticky top-20">
             <p className="px-2 text-xs font-semibold text-[var(--text3)]">{t.onThisPage}</p>
-            <nav className="site-toc mt-2">
-              {doc.sections.map((section, index) => (
-                <a key={section.heading} href={`#${sectionId(index)}`}>
-                  {section.heading}
-                </a>
-              ))}
-              {doc.keyTerms?.length ? <a href="#key-terms">{t.keyTerms}</a> : null}
-              {doc.quiz?.length ? <a href="#check-yourself">{t.checkYourself}</a> : null}
-            </nav>
+            <TableOfContents
+              className="mt-2"
+              items={[
+                ...doc.sections.map((section, index) => ({ id: sectionId(index), label: section.heading })),
+                ...(doc.keyTerms?.length ? [{ id: "key-terms", label: t.keyTerms }] : []),
+                ...(doc.quiz?.length ? [{ id: "check-yourself", label: t.checkYourself }] : []),
+              ]}
+            />
           </div>
         </aside>
       </div>
diff --git a/apps/web/src/app/globals.css b/apps/web/src/app/globals.css
index 40e37a2..5531b18 100644
--- a/apps/web/src/app/globals.css
+++ b/apps/web/src/app/globals.css
@@ -1074,6 +1074,11 @@ code {
   color: var(--text);
 }
 
+.site-toc a[aria-current="location"] {
+  background: var(--selected);
+  color: var(--text);
+}
+
 .site :where(a, button, summary):focus-visible {
   outline: 2px solid var(--accent);
   outline-offset: 3px;