From d34b440664977a5af47da3118a3e9e18d7e72e62 Mon Sep 17 00:00:00 2001
From: ginger <26461046+gingerchew@users.noreply.github.com>
Date: Wed, 8 Jan 2025 12:20:13 -0500
Subject: [PATCH] feat: Add sticky table of contents (#178)

---
 package.json                         |   2 +-
 pnpm-lock.yaml                       |  10 +-
 src/components/TableOfContents.astro | 158 +++++++++++++++++++++++++++
 src/layouts/ProseLayout.astro        |  76 ++++++++++++-
 src/pages/[id].astro                 |   3 +-
 src/pages/abuse.astro                |   3 +-
 src/pages/blog/[id].astro            |   3 +-
 src/pages/privacy.astro              |   3 +-
 src/pages/subprocessors.astro        |   3 +-
 src/pages/terms.astro                |   3 +-
 10 files changed, 249 insertions(+), 15 deletions(-)
 create mode 100644 src/components/TableOfContents.astro

diff --git a/package.json b/package.json
index bdaa4d3..d6e38e9 100644
--- a/package.json
+++ b/package.json
@@ -32,7 +32,7 @@
     "@types/react-dom": "^19.0.2",
     "astro": "^5.1.2",
     "astro-font": "^0.1.81",
-    "astro-github-file-loader": "^1.0.2",
+    "astro-github-file-loader": "^1.1.0",
     "dayjs": "^1.11.13",
     "fathom-client": "^3.7.2",
     "react": "^19.0.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index db675c2..3770e97 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -48,8 +48,8 @@ importers:
         specifier: ^0.1.81
         version: 0.1.81
       astro-github-file-loader:
-        specifier: ^1.0.2
-        version: 1.0.2(@types/node@22.10.5)(idb-keyval@6.2.1)(jiti@2.4.2)(rollup@4.29.1)(sass@1.83.1)(typescript@5.7.2)(yaml@2.5.1)
+        specifier: ^1.1.0
+        version: 1.1.0(@types/node@22.10.5)(idb-keyval@6.2.1)(jiti@2.4.2)(rollup@4.29.1)(sass@1.83.1)(typescript@5.7.2)(yaml@2.5.1)
       dayjs:
         specifier: ^1.11.13
         version: 1.11.13
@@ -2160,8 +2160,8 @@ packages:
   astro-font@0.1.81:
     resolution: {integrity: sha512-rbrv/+ZSYdgyjBlhkAqfCjMxqqo6iEwnSo/rAdDt/POILsF0ChxMFhefIIzKEukrRGtVjEj1lrLRYk+AdV9scQ==}
 
-  astro-github-file-loader@1.0.2:
-    resolution: {integrity: sha512-KL/ZYr6X5YlmISKLXxfLKCIqJZPe9Fm7TMNiz8VM+6YRF8bPbTQEox7FfWkyeaF+jPumpWGHIsMueA20DtEvhw==}
+  astro-github-file-loader@1.1.0:
+    resolution: {integrity: sha512-zRrmC+lEJPkqzbPQTS/g8l55TwXYDbKuJozKj4aAnCrF3KEP6VHkhVGfnzSABOX3XiGj/FpwBfIQdE//AgP9oQ==}
 
   astro-integration-kit@0.17.0:
     resolution: {integrity: sha512-fe31CCKmrGYn/kkBd1J4b7P02gEdMdEIFBz14zdAud+YAmJeLtZD6wmrCz3LDau+lE1oM1hQnvmZXVSM/YveKw==}
@@ -6974,7 +6974,7 @@ snapshots:
 
   astro-font@0.1.81: {}
 
-  astro-github-file-loader@1.0.2(@types/node@22.10.5)(idb-keyval@6.2.1)(jiti@2.4.2)(rollup@4.29.1)(sass@1.83.1)(typescript@5.7.2)(yaml@2.5.1):
+  astro-github-file-loader@1.1.0(@types/node@22.10.5)(idb-keyval@6.2.1)(jiti@2.4.2)(rollup@4.29.1)(sass@1.83.1)(typescript@5.7.2)(yaml@2.5.1):
     dependencies:
       astro: 5.1.2(@types/node@22.10.5)(idb-keyval@6.2.1)(jiti@2.4.2)(rollup@4.29.1)(sass@1.83.1)(typescript@5.7.2)(yaml@2.5.1)
     transitivePeerDependencies:
diff --git a/src/components/TableOfContents.astro b/src/components/TableOfContents.astro
new file mode 100644
index 0000000..a9164a0
--- /dev/null
+++ b/src/components/TableOfContents.astro
@@ -0,0 +1,158 @@
+---
+import type { MarkdownHeading } from "astro";
+
+interface Props {
+  headings?: MarkdownHeading[];
+}
+
+const { headings } = Astro.props;
+
+const showTOC = headings && headings.length > 2;
+---
+
+{
+  showTOC && (
+    <nav class="toc" aria-labelledby="tocHeader">
+      <h2 class="toc-header" id="tocHeader">
+        On this page
+      </h2>
+      <table-of-contents>
+        <ul>
+          {headings.map(({ depth, slug, text }) => (
+            <li style={"--depth: " + depth}>
+              <a href={`#${slug}`}>{text}</a>
+            </li>
+          ))}
+        </ul>
+      </table-of-contents>
+    </nav>
+  )
+}
+
+<script>
+  import { annotate } from "rough-notation";
+  import type { RoughAnnotation } from "rough-notation/lib/model";
+
+  customElements.define(
+    "table-of-contents",
+    class extends HTMLElement {
+      #io: IntersectionObserver;
+      #links: HTMLAnchorElement[];
+      #headings: HTMLHeadingElement[];
+      #annotations: Map<HTMLAnchorElement, RoughAnnotation>;
+      #activeIndex = -1;
+
+      constructor() {
+        super();
+        this.#annotations = new Map();
+
+        // 90% of the viewport, to expand subtract from this value to bring the bottom threshold lower
+        const ioBottomThreshold = window.innerHeight * 0.9;
+        this.#io = new IntersectionObserver(
+          (entries, _obs) => {
+            for (const entry of entries) {
+              const target = entry.target as HTMLHeadingElement;
+              const { boundingClientRect, intersectionRect, isIntersecting } =
+                entry;
+
+              if (
+                boundingClientRect.top < intersectionRect.bottom &&
+                isIntersecting
+              ) {
+                this.#activeIndex = this.#headings.indexOf(target);
+                this.updateAnnotation();
+                /**
+                 * Make sure it isn't intersecting so we aren't calling this
+                 * when the heading is scrolling off screen
+                 */
+              } else if (
+                boundingClientRect.top > intersectionRect.bottom &&
+                !isIntersecting
+              ) {
+                this.#activeIndex = this.#headings.indexOf(target) - 1;
+                this.updateAnnotation();
+              }
+            }
+          },
+          {
+            threshold: 0,
+            rootMargin: `0px 0px ${-ioBottomThreshold}px 0px`,
+          },
+        );
+
+        this.#headings = [];
+        this.#links = Array.from(this.querySelectorAll("a"), (link) => {
+          const { hash } = new URL(link.href);
+          const heading = document.querySelector<HTMLHeadingElement>(hash)!;
+
+          this.#headings.push(heading);
+
+          return link;
+        });
+        /**
+         * Observing the element runs the callback,
+         * this leads to the second to last item being annotated
+         *
+         * here we reverse the array, and observe them from bottom
+         * to top and avoid any annotations rendering when the
+         * user is at the top of the page
+         */
+        this.#headings.toReversed().forEach((h) => this.#io.observe(h));
+      }
+
+      updateAnnotation() {
+        const activeHeading = this.#headings[this.#activeIndex];
+
+        this.#headings.forEach((h, i) => {
+          const annotation = this.getAnnotationFromIndex(i);
+
+          Object.is(h, activeHeading) ? annotation?.show() : annotation?.hide();
+        });
+      }
+
+      getAnnotationFromIndex(i: number): RoughAnnotation | null {
+        if (i < 0 || i > this.#links.length - 1) return null;
+        const item = this.#links[i];
+
+        if (!this.#annotations.has(item)) {
+          this.#annotations.set(
+            item,
+            annotate(item, {
+              type: "underline",
+              animate: false,
+              iterations: 1,
+              multiline: true,
+              padding: 0,
+            }),
+          );
+        }
+
+        return this.#annotations.get(item)!;
+      }
+    },
+  );
+</script>
+
+<style>
+  h2 {
+    font-size: var(--step-0);
+  }
+
+  ul {
+    list-style-type: none;
+    padding-inline-start: 0;
+    padding-block: var(--space-l);
+    display: flex;
+    flex-flow: column;
+    gap: var(--space-2xs);
+  }
+
+  li {
+    font-size: var(--step--1);
+    margin-inline-start: calc((var(--depth) - 2) * var(--space-m));
+  }
+
+  a {
+    text-decoration: 1px solid transparent;
+  }
+</style>
diff --git a/src/layouts/ProseLayout.astro b/src/layouts/ProseLayout.astro
index 7421a1b..b95596a 100644
--- a/src/layouts/ProseLayout.astro
+++ b/src/layouts/ProseLayout.astro
@@ -4,6 +4,8 @@ import PageHeader from "~/components/PageHeader.astro";
 import type { NamesakeColor } from "~/data/colors";
 import { smartquotes } from "../helpers/helpers";
 import BaseLayout from "./BaseLayout.astro";
+import type { MarkdownHeading } from "astro";
+import TableOfContents from "~/components/TableOfContents.astro";
 
 interface Props {
   title: string;
@@ -13,10 +15,19 @@ interface Props {
   ogAlt?: string;
   annotation?: RoughAnnotationType;
   color?: NamesakeColor;
+  headings?: MarkdownHeading[];
 }
 
-const { title, date, description, ogImage, ogAlt, annotation, color } =
-  Astro.props;
+const {
+  title,
+  date,
+  description,
+  ogImage,
+  ogAlt,
+  annotation,
+  color,
+  headings,
+} = Astro.props;
 ---
 
 <BaseLayout
@@ -26,7 +37,11 @@ const { title, date, description, ogImage, ogAlt, annotation, color } =
   ogAlt={ogAlt}
   color={color}
 >
-  <article itemscope itemtype="https://schema.org/BlogPosting">
+  <article
+    class="article-grid"
+    itemscope
+    itemtype="https://schema.org/BlogPosting"
+  >
     <PageHeader
       title={title}
       date={date}
@@ -34,6 +49,7 @@ const { title, date, description, ogImage, ogAlt, annotation, color } =
       annotation={annotation}
     />
     <slot name="after-header" />
+    <TableOfContents headings={headings} />
     <section itemprop="articleBody" class="prose">
       <slot />
     </section>
@@ -42,9 +58,63 @@ const { title, date, description, ogImage, ogAlt, annotation, color } =
 </BaseLayout>
 
 <style lang="scss" is:global>
+  .article-grid {
+    display: grid;
+    grid-auto-rows: minmax(min-content, max-content);
+    column-gap: var(--space-m);
+    grid-template-columns: 1fr;
+    grid-template-areas:
+      "head"
+      "authors"
+      "toc"
+      "prose"
+      "bios";
+    @media (width >= 900px) {
+      grid-template-columns: 3fr 1fr;
+      grid-template-areas:
+        "head head"
+        "authors toc"
+        "prose toc"
+        "bios .";
+
+      .toc {
+        position: sticky;
+        top: var(--space-xl);
+        right: 0;
+        /* `display: grid` will extend the height of this past it's content, let's stop that */
+        max-height: fit-content;
+      }
+    }
+
+    .bios {
+      grid-area: bios;
+    }
+
+    .prose:not(.not-content) {
+      grid-area: prose;
+    }
+
+    .toc {
+      grid-area: toc;
+    }
+
+    .authors {
+      grid-area: authors;
+    }
+
+    .page-head {
+      grid-area: head;
+    }
+  }
+
   .prose:not(.not-content) {
     max-width: 720px;
     margin-inline-end: auto;
+    grid-area: prose;
+
+    [id] {
+      scroll-margin-top: 1ex;
+    }
 
     h2,
     h3 {
diff --git a/src/pages/[id].astro b/src/pages/[id].astro
index 5c1d009..2b9bed4 100644
--- a/src/pages/[id].astro
+++ b/src/pages/[id].astro
@@ -20,7 +20,7 @@ const { page } = Astro.props;
 if (!page) return Astro.redirect("/404");
 
 const { data } = page;
-const { Content } = await render(page);
+const { Content, headings } = await render(page);
 ---
 
 <ProseLayout
@@ -30,6 +30,7 @@ const { Content } = await render(page);
   ogAlt={data.ogImage?.alt}
   annotation={data.annotation}
   color={data.color}
+  headings={headings}
 >
   <Content />
 </ProseLayout>
diff --git a/src/pages/abuse.astro b/src/pages/abuse.astro
index 5bbb1d4..fe8c649 100644
--- a/src/pages/abuse.astro
+++ b/src/pages/abuse.astro
@@ -5,7 +5,7 @@ import ProseLayout from "~/layouts/ProseLayout.astro";
 const entry = await getEntry("policy", "abuse");
 if (entry === undefined) return Astro.redirect("/404");
 
-const { Content } = await render(entry);
+const { Content, headings } = await render(entry);
 ---
 
 <ProseLayout
@@ -13,6 +13,7 @@ const { Content } = await render(entry);
   description="It is not okay to use Namesake for these restricted purposes."
   color="brown"
   annotation="crossed-off"
+  headings={headings}
 >
   <Content />
 </ProseLayout>
diff --git a/src/pages/blog/[id].astro b/src/pages/blog/[id].astro
index d39d7e2..0a47cd8 100644
--- a/src/pages/blog/[id].astro
+++ b/src/pages/blog/[id].astro
@@ -26,7 +26,7 @@ const { post } = Astro.props;
 if (!post) return Astro.redirect("/404");
 
 const { data } = post;
-const { Content } = await render(post);
+const { Content, headings } = await render(post);
 
 const authors = await getEntries(data.authors);
 ---
@@ -37,6 +37,7 @@ const authors = await getEntries(data.authors);
   description={data.description}
   color="blue"
   annotation="highlight"
+  headings={headings}
 >
   <div class="authors" slot="after-header">
     {
diff --git a/src/pages/privacy.astro b/src/pages/privacy.astro
index 390c11c..c0f3b19 100644
--- a/src/pages/privacy.astro
+++ b/src/pages/privacy.astro
@@ -5,13 +5,14 @@ import ProseLayout from "~/layouts/ProseLayout.astro";
 const entry = await getEntry("policy", "privacy");
 if (entry === undefined) return Astro.redirect("/404");
 
-const { Content } = await render(entry);
+const { Content, headings } = await render(entry);
 ---
 
 <ProseLayout
   title="Privacy"
   description="The privacy of your data—and it is your data, not ours!—is a big deal to us. Here’s the rundown of what we collect and why, when we access your information, and your rights."
   color="brown"
+  headings={headings}
 >
   <Content />
 </ProseLayout>
diff --git a/src/pages/subprocessors.astro b/src/pages/subprocessors.astro
index 03ab8f2..abceb1d 100644
--- a/src/pages/subprocessors.astro
+++ b/src/pages/subprocessors.astro
@@ -5,13 +5,14 @@ import ProseLayout from "~/layouts/ProseLayout.astro";
 const entry = await getEntry("policy", "subprocessors");
 if (entry === undefined) return Astro.redirect("/404");
 
-const { Content } = await render(entry);
+const { Content, headings } = await render(entry);
 ---
 
 <ProseLayout
   title="Subprocessors"
   description="All the third-party subprocessors that we use to run Namesake."
   color="brown"
+  headings={headings}
 >
   <Content />
 </ProseLayout>
diff --git a/src/pages/terms.astro b/src/pages/terms.astro
index b46bdd3..3dd1b86 100644
--- a/src/pages/terms.astro
+++ b/src/pages/terms.astro
@@ -5,7 +5,7 @@ import ProseLayout from "~/layouts/ProseLayout.astro";
 const entry = await getEntry("policy", "terms");
 if (entry === undefined) return Astro.redirect("/404");
 
-const { Content } = await render(entry);
+const { Content, headings } = await render(entry);
 ---
 
 <ProseLayout
@@ -13,6 +13,7 @@ const { Content } = await render(entry);
   description="All the terms that you agree to when you sign up for Namesake."
   color="brown"
   annotation="box"
+  headings={headings}
 >
   <Content />
 </ProseLayout>