From 7bedf3915914b77d042e5c36061b70b99d9f562d Mon Sep 17 00:00:00 2001
From: Jack Shelton <104264123+thejackshelton@users.noreply.github.com>
Date: Sun, 22 Dec 2024 03:52:16 -0600
Subject: [PATCH] docs: add TOC + site changes (#655)

---
 docs/package.json                             |   2 +
 docs/pnpm-lock.yaml                           |  17 ++
 docs/src/components/Aside/Aside.tsx           |   4 +-
 docs/src/components/Footer/Footer.tsx         |   2 +-
 docs/src/components/Header/Header.tsx         |   4 +-
 .../MdxComponents/MdxComponents.tsx           |   2 +-
 docs/src/components/Toc/Toc.tsx               | 217 +++++++++++++++---
 docs/src/global.scss                          |   9 +-
 docs/src/root.tsx                             |   2 +-
 docs/src/routes/layout.tsx                    |  16 +-
 docs/src/utils/cn.ts                          |   6 +
 11 files changed, 237 insertions(+), 44 deletions(-)
 create mode 100644 docs/src/utils/cn.ts

diff --git a/docs/package.json b/docs/package.json
index 52264d23..b4d8291e 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -36,6 +36,7 @@
     "@typescript-eslint/eslint-plugin": "7.16.1",
     "@typescript-eslint/parser": "7.16.1",
     "autoprefixer": "^10.4.19",
+    "clsx": "^2.1.1",
     "eslint": "8.57.0",
     "eslint-plugin-qwik": "^2.0.0-alpha.4",
     "postcss": "^8.4.39",
@@ -44,6 +45,7 @@
     "rehype-pretty-code": "^0.14.0",
     "sass": "^1.83.0",
     "shiki": "^1.24.3",
+    "tailwind-merge": "^2.5.5",
     "tailwindcss": "^3.4.6",
     "typescript": "5.4.5",
     "unist-util-visit": "^5.0.0",
diff --git a/docs/pnpm-lock.yaml b/docs/pnpm-lock.yaml
index e4d4d1eb..3dc34a10 100644
--- a/docs/pnpm-lock.yaml
+++ b/docs/pnpm-lock.yaml
@@ -29,6 +29,9 @@ importers:
       autoprefixer:
         specifier: ^10.4.19
         version: 10.4.20(postcss@8.4.49)
+      clsx:
+        specifier: ^2.1.1
+        version: 2.1.1
       eslint:
         specifier: 8.57.0
         version: 8.57.0
@@ -53,6 +56,9 @@ importers:
       shiki:
         specifier: ^1.24.3
         version: 1.24.3
+      tailwind-merge:
+        specifier: ^2.5.5
+        version: 2.5.5
       tailwindcss:
         specifier: ^3.4.6
         version: 3.4.17
@@ -1104,6 +1110,10 @@ packages:
     resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
     engines: {node: '>= 14.16.0'}
 
+  clsx@2.1.1:
+    resolution: {integrity: sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==}
+    engines: {node: '>=6'}
+
   collapse-white-space@2.1.0:
     resolution: {integrity: sha512-loKTxY1zCOuG4j9f6EPnuyyYkf58RnhhWTvRoZEokgB+WbdXehfjFviyOVYkqzEWz1Q5kRiZdBYS5SwxbQYwzw==}
 
@@ -2486,6 +2496,9 @@ packages:
     engines: {node: '>=14.0.0'}
     hasBin: true
 
+  tailwind-merge@2.5.5:
+    resolution: {integrity: sha512-0LXunzzAZzo0tEPxV3I297ffKZPlKDrjj7NXphC8V5ak9yHC5zRmxnOe2m/Rd/7ivsOMJe3JZ2JVocoDdQTRBA==}
+
   tailwindcss@3.4.17:
     resolution: {integrity: sha512-w33E2aCvSDP0tW9RZuNXadXlkHXqFzSkQew/aIa2i/Sj8fThxwovwlXHSPXTbAHwEIhBFXAedUhP2tueAKP8Og==}
     engines: {node: '>=14.0.0'}
@@ -3655,6 +3668,8 @@ snapshots:
     dependencies:
       readdirp: 4.0.2
 
+  clsx@2.1.1: {}
+
   collapse-white-space@2.1.0: {}
 
   color-convert@2.0.1:
@@ -5497,6 +5512,8 @@ snapshots:
       csso: 5.0.5
       picocolors: 1.1.1
 
+  tailwind-merge@2.5.5: {}
+
   tailwindcss@3.4.17:
     dependencies:
       '@alloc/quick-lru': 5.2.0
diff --git a/docs/src/components/Aside/Aside.tsx b/docs/src/components/Aside/Aside.tsx
index 65d5b2d1..ede6377e 100644
--- a/docs/src/components/Aside/Aside.tsx
+++ b/docs/src/components/Aside/Aside.tsx
@@ -6,7 +6,7 @@ export const Aside = component$(() => {
 
   return (
     <div
-      class={`fixed top-20 mt-8 flex h-[calc(100%-12rem)] flex-col overflow-hidden overflow-y-auto px-6 text-xl text-black dark:text-white`}
+      class={`fixed top-20 mt-8 flex h-full flex-col overflow-hidden overflow-y-auto px-6 text-black dark:text-white`}
     >
       {(menu?.items || []).map(({ text, items }, idx) => {
         const [title, href] = text.split("|");
@@ -15,7 +15,7 @@ export const Aside = component$(() => {
             <li>
               {href ? (
                 <a
-                  class="mb-2 block rounded bg-blue-700 px-4 py-1 text-base font-bold uppercase text-white no-underline"
+                  class="mb-2 block rounded bg-blue-700 dark:bg-blue-600 px-4 py-1 text-base font-bold uppercase text-white no-underline"
                   href={href}
                 >
                   {title}
diff --git a/docs/src/components/Footer/Footer.tsx b/docs/src/components/Footer/Footer.tsx
index 1692638d..76504143 100644
--- a/docs/src/components/Footer/Footer.tsx
+++ b/docs/src/components/Footer/Footer.tsx
@@ -3,7 +3,7 @@ import { GitHubIcon } from "../Icons/GitHubIcon";
 
 export const Footer = component$(() => {
   return (
-    <footer class="flex border-t-[2px] border-slate-200 bg-white px-6 py-4 dark:border-slate-800 dark:bg-black">
+    <footer class="flex border-t-[2px] border-slate-200 px-6 py-4 dark:border-slate-800 bg-[#F8F8FF] dark:bg-[#0D0F12] mt-6">
       <div class="grid w-full grid-cols-12">
         <div class="col-span-4" />
         <div class="col-span-4" />
diff --git a/docs/src/components/Header/Header.tsx b/docs/src/components/Header/Header.tsx
index 3915dc79..ddd727f8 100644
--- a/docs/src/components/Header/Header.tsx
+++ b/docs/src/components/Header/Header.tsx
@@ -15,9 +15,9 @@ export const Header = component$<Props>(({ links = [], showMenu = true }) => {
   const showAsideSig = useSignal(false);
   return (
     <header
-      class={`fixed top-0 z-10 h-20 w-full border-b-[2px] border-slate-200 bg-white dark:border-slate-800 dark:bg-black`}
+      class={`fixed top-0 z-10 h-20 w-full border-b-[2px] border-zinc-100 bg-[#F8F8FF] dark:border-zinc-900 dark:bg-[#0D0F12]`}
     >
-      <div class="grid h-full max-w-[1200px] grid-cols-12 px-6">
+      <div class="grid h-full max-w-[1376px] grid-cols-12 px-6">
         <div class="col-span-3 flex items-center sm:col-span-4">
           {showMenu && (
             <button
diff --git a/docs/src/components/MdxComponents/MdxComponents.tsx b/docs/src/components/MdxComponents/MdxComponents.tsx
index fab54a44..1aa34b46 100644
--- a/docs/src/components/MdxComponents/MdxComponents.tsx
+++ b/docs/src/components/MdxComponents/MdxComponents.tsx
@@ -7,7 +7,7 @@ export const components: Record<string, any> = {
     () => {
       return (
         <div class="relative">
-          <pre class="mb-4 mt-6 max-h-[650px] overflow-x-auto rounded-lg border bg-zinc-950 p-6 text-white dark:bg-zinc-900">
+          <pre class="mb-4 mt-6 max-h-[650px] overflow-x-auto rounded-lg bg-zinc-950 p-6 text-white dark:bg-zinc-950">
             <Slot />
           </pre>
         </div>
diff --git a/docs/src/components/Toc/Toc.tsx b/docs/src/components/Toc/Toc.tsx
index 9b1008e2..6f5a59a0 100644
--- a/docs/src/components/Toc/Toc.tsx
+++ b/docs/src/components/Toc/Toc.tsx
@@ -1,31 +1,192 @@
-import { component$, useSignal } from "@qwik.dev/core";
-import { useContent } from "@qwik.dev/router";
+import { cn } from "~/utils/cn";
+import { component$, useSignal, $, useOnWindow } from '@qwik.dev/core';
+import { ContentHeading } from '@qwik.dev/router';
 
-export const Toc = component$(() => {
-  const { headings } = useContent();
-  const lastScrollIdSig = useSignal("");
-  return (
-    <div class="fixed flex w-full flex-col px-6 pt-28 text-xl text-black dark:text-white">
-      <span class="mb-2 text-lg font-bold uppercase">On this page</span>
-      {(headings || []).map(({ text, id }, idx) => (
-        <ul
-          key={idx}
-          class="border-l-[4px] py-1 pl-4 hover:border-blue-700"
-          onMouseOver$={() => {
-            if (lastScrollIdSig.value !== id) {
-              const el = document.querySelector(`#${id}`);
-              if (el) {
-                el.scrollIntoView({ behavior: "smooth" });
-                lastScrollIdSig.value = id;
-              }
-            }
-          }}
-        >
-          <li class="text-base hover:text-blue-500">
-            <a href={`#${id}`}>{text}</a>
+export const TOC = component$(
+  ({ headings }: { headings: ContentHeading[] }) => {
+    if (headings.length === 0) {
+      return null;
+    }
+    return (
+      <div class="space-y-2 sticky top-24 max-h-[calc(80vh)] p-1 dark:text-white text-black hidden xl:block">
+        <div class="font-medium">On This Page</div>
+        <TableOfContents headings={headings} />
+      </div>
+    );
+  },
+);
+
+type TableOfContentsProps = { headings: ContentHeading[] };
+
+interface Node extends ContentHeading {
+  children: Node[];
+  activeItem: string;
+}
+type Tree = Array<Node>;
+
+const TableOfContents = component$<TableOfContentsProps>(({ headings }) => {
+  const sanitizedHeadings = headings.map(({ text, id, level }) => ({ text, id, level }));
+  const itemIds = headings.map(({ id }) => id);
+  const activeHeading = useActiveItem(itemIds);
+  const tree = buildTree(sanitizedHeadings);
+  const fixStartingBug: Node = { ...tree, children: [tree] };
+  return <RecursiveList tree={fixStartingBug} activeItem={activeHeading.value ?? ''} />;
+});
+
+function deltaToStrg(
+  currNode: Node,
+  nextNode: Node,
+): 'same level' | 'down one level' | 'up one level' | 'upwards discontinuous' {
+  const delta = currNode.level - nextNode.level;
+  if (delta > 1) {
+    return 'upwards discontinuous';
+  }
+  if (delta === 1) {
+    return 'up one level';
+  }
+  if (delta === 0) {
+    return 'same level';
+  }
+  if (delta === -1) {
+    return 'down one level';
+  }
+
+  throw new Error(
+    `bad headings: are downwards discontinous from: #${currNode.id} to #${nextNode.id} bc from ${currNode.level} to ${nextNode.level}`,
+  );
+}
+
+function buildTree(nodes: ContentHeading[]) {
+  let currNode = nodes[0] as Node;
+  currNode.children = [];
+  const tree = [currNode];
+  const childrenMap = new Map<number, Tree>();
+  childrenMap.set(currNode.level, currNode.children);
+  for (let index = 1; index < nodes.length; index++) {
+    const nextNode = nodes[index] as Node;
+    nextNode.children = [];
+    childrenMap.set(nextNode.level, nextNode.children);
+    const deltaStrg = deltaToStrg(currNode, nextNode);
+    switch (deltaStrg) {
+      case 'upwards discontinuous': {
+        const delta = currNode.level - nextNode.level;
+        if (childrenMap.has(delta - 1)) {
+          const nthParent = childrenMap.get(delta - 1);
+          nthParent?.push(nextNode);
+        }
+        break;
+      }
+      case 'up one level': {
+        const grandParent = childrenMap.get(currNode.level - 2);
+        grandParent?.push(nextNode);
+        break;
+      }
+      case 'same level': {
+        const parent = childrenMap.get(currNode.level - 1);
+        parent?.push(nextNode);
+        break;
+      }
+      case 'down one level': {
+        currNode.children.push(nextNode);
+        break;
+      }
+      default:
+        break;
+    }
+    currNode = nextNode;
+  }
+  return tree[0];
+}
+
+type RecursiveListProps = {
+  tree: Node;
+  activeItem: string;
+  limit?: number;
+};
+
+const RecursiveList = component$<RecursiveListProps>(
+  ({ tree, activeItem, limit = 3 }) => {
+    return tree?.children?.length && tree.level < limit ? (
+      <ul class={cn('m-0 list-none', { 'pl-4': tree.level !== 1 })}>
+        {tree.children.map((childNode) => (
+          <li key={childNode.id} class="mt-0 list-none pt-2">
+            <Anchor node={childNode} activeItem={activeItem} />
+            {childNode.children.length > 0 && (
+              <RecursiveList tree={childNode} activeItem={activeItem} />
+            )}
           </li>
-        </ul>
-      ))}
-    </div>
+        ))}
+      </ul>
+    ) : null;
+  },
+);
+
+const useActiveItem = (itemIds: string[]) => {
+  const activeId = useSignal<string>();
+
+  useOnWindow(
+    'scroll',
+    $(() => {
+      const observer = new IntersectionObserver(
+        (entries) => {
+          entries.forEach((entry) => {
+            if (entry.isIntersecting) {
+              activeId.value = entry.target.id;
+            }
+          });
+        },
+        { rootMargin: '0% 0% -85% 0%' },
+      );
+
+      itemIds.forEach((id) => {
+        const element = document.getElementById(id);
+        if (element) {
+          observer.observe(element);
+        }
+      });
+
+      return () => {
+        itemIds.forEach((id) => {
+          const element = document.getElementById(id);
+          if (element) {
+            observer.unobserve(element);
+          }
+        });
+      };
+    }),
   );
-});
+
+  return activeId;
+};
+
+type AnchorProps = {
+  node: Node;
+  activeItem: string;
+};
+
+const Anchor = component$<AnchorProps>(({ node, activeItem }) => {
+  const isActive = node.id === activeItem;
+  return (
+    <a
+      href={`#${node.id}`}
+      onClick$={[
+        $(() => {
+          const element = document.getElementById(node.id);
+          if (element) {
+            const navbarHeight = 90;
+            const position =
+              element.getBoundingClientRect().top + window.scrollY - navbarHeight;
+            window.scrollTo({ top: position, behavior: 'auto' });
+          }
+        }),
+      ]}
+      class={cn(
+        node.level > 2 && 'ml-2',
+        'inline-block no-underline transition-colors',
+        isActive ? 'text-blue-500 dark:text-blue-300' : 'text-muted-foreground',
+      )}
+    >
+      {node.text}
+    </a>
+  );
+});
\ No newline at end of file
diff --git a/docs/src/global.scss b/docs/src/global.scss
index b7974fa3..60588d5a 100644
--- a/docs/src/global.scss
+++ b/docs/src/global.scss
@@ -84,10 +84,11 @@
  */
 
 html {
-  height: 100%;
-  &.dark {
-    @apply bg-black;
-  }
+  @apply bg-[#F8F8FF];
+}
+
+.dark {
+  @apply bg-[#0D0F12]
 }
 
 body {
diff --git a/docs/src/root.tsx b/docs/src/root.tsx
index a7a0ff1a..2f7680cb 100644
--- a/docs/src/root.tsx
+++ b/docs/src/root.tsx
@@ -28,7 +28,7 @@ export default component$(() => {
         )}
         <RouterHead />
       </head>
-      <body lang="en" class="m-auto max-w-[1200px]">
+      <body lang="en" class="m-auto max-w-[1376px]">
         <RouterOutlet />
         {!isDev && <ServiceWorkerRegister />}
       </body>
diff --git a/docs/src/routes/layout.tsx b/docs/src/routes/layout.tsx
index 736ae968..9172855b 100644
--- a/docs/src/routes/layout.tsx
+++ b/docs/src/routes/layout.tsx
@@ -6,11 +6,12 @@ import {
   useStore,
   useVisibleTask$,
 } from "@qwik.dev/core";
-import { type RequestHandler } from "@qwik.dev/router";
+import { useLocation, type RequestHandler, useContent } from "@qwik.dev/router";
 import { Aside } from "~/components/Aside/Aside";
 import { Footer } from "~/components/Footer/Footer";
 import { Header } from "~/components/Header/Header";
 import { components } from "~/components/MdxComponents/MdxComponents";
+import { TOC } from "~/components/Toc/Toc";
 import { MDXProvider } from "~/state/MDXProvider";
 
 export const onGet: RequestHandler = async ({ cacheControl }) => {
@@ -32,27 +33,32 @@ export const StoreContext = createContextId<Store>("Store");
 
 export default component$(() => {
   const store = useStore<Store>({ theme: "light" });
+  const { headings } = useContent();
   useContextProvider(StoreContext, store);
   // eslint-disable-next-line qwik/no-use-visible-task
   useVisibleTask$(() => {
     const theme = localStorage.getItem("theme") as Store["theme"];
     store.theme = theme;
   });
+
+
+
   return (
     <MDXProvider components={components}>
-      <div class="h-screen bg-white dark:bg-black">
+      <div class="h-screen bg-[#F8F8FF] dark:bg-[#0D0F12]">
         <Header />
-        <main class="flex min-h-[100%] bg-white dark:bg-black lg:grid lg:grid-cols-content">
+        <main class="flex min-h-[100%] bg-[#F8F8FF] dark:bg-[#0D0F12] lg:grid lg:grid-cols-content xl:grid-cols-[260px_1fr_240px]">
           <aside
-            class={`hidden border-r-[2px] border-slate-200 dark:border-slate-800 lg:block`}
+            class={`hidden border-r-[2px] border-zinc-100 dark:border-zinc-900 lg:block`}
           >
             <Aside />
           </aside>
           <article class="docs w-full pb-10 pt-28">
             <Slot />
+            <Footer />
           </article>
+          <TOC headings={headings ?? []} />
         </main>
-        <Footer />
       </div>
     </MDXProvider>
   );
diff --git a/docs/src/utils/cn.ts b/docs/src/utils/cn.ts
new file mode 100644
index 00000000..d34cf7ef
--- /dev/null
+++ b/docs/src/utils/cn.ts
@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
\ No newline at end of file