feat: sidebar and a bunch of other stuff

Author: duanwilliam

website/package.json

@@ -9,32 +9,52 @@
     "lint": "next lint"
   },
   "dependencies": {
-    "@teamsupercell/typings-for-css-modules-loader": "^2.5.1",
     "clsx": "^1.1.1",
     "copy-text-to-clipboard": "^3.0.1",
-    "glob": "^7.2.0",
-    "mdast-util-from-markdown": "^1.2.0",
-    "mdast-util-to-markdown": "^1.3.0",
+    "mdx-bundler": "^9.0.0",
     "next": "12.1.0",
     "next-mdx-remote": "^4.0.0",
     "prism-react-renderer": "^1.2.1",
     "react": "17.0.2",
     "react-dom": "17.0.2",
-    "rehype-katex": "^6.0.2",
-    "rehype-stringify": "^9.0.3",
-    "remark-gfm": "^3.0.1",
-    "remark-math": "^5.1.1",
-    "remark-parse": "^10.0.0",
-    "remark-rehype": "^10.1.0",
-    "remark-stringify": "^10.0.0",
-    "sass": "^1.49.7",
-    "unified": "^10.1.0"
+    "sass": "^1.49.7"
   },
   "devDependencies": {
+    "@babel/parser": "^7.17.9",
+    "@babel/traverse": "^7.17.9",
+    "@babel/types": "^7.17.0",
+    "@teamsupercell/typings-for-css-modules-loader": "^2.5.1",
+    "@types/babel__traverse": "^7.17.0",
+    "@types/escape-html": "^1.0.2",
     "@types/glob": "^7.1.4",
     "@types/react": "17.0.27",
+    "@types/stringify-object": "^4.0.1",
+    "@types/unist": "^2.0.6",
+    "esbuild": "^0.14.36",
+    "escape-html": "^1.0.3",
     "eslint": "7.32.0",
     "eslint-config-next": "11.1.2",
-    "typescript": "4.4.3"
+    "glob": "^8.0.1",
+    "mdast": "^3.0.0",
+    "mdast-util-from-markdown": "^1.2.0",
+    "mdast-util-gfm": "^2.0.1",
+    "mdast-util-math": "^2.0.1",
+    "mdast-util-mdxjs-esm": "^1.2.0",
+    "mdast-util-to-markdown": "^1.3.0",
+    "mdast-util-to-string": "^3.1.0",
+    "micromark-extension-gfm": "^2.0.1",
+    "micromark-extension-math": "^2.0.2",
+    "micromark-extension-mdxjs-esm": "^1.0.2",
+    "rehype-katex": "^6.0.2",
+    "rehype-stringify": "^9.0.3",
+    "remark-gfm": "^3.0.1",
+    "remark-math": "^5.1.1",
+    "remark-parse": "^10.0.1",
+    "remark-rehype": "^10.1.0",
+    "remark-stringify": "^10.0.2",
+    "stringify-object": "^4.0.1",
+    "typescript": "^4.6.3",
+    "unified": "^10.1.2",
+    "unist-util-visit": "^4.1.0"
   }
 }

website/src/components/Collapsible/index.tsx

@@ -26,7 +26,7 @@ const DefaultAnimationEasing = 'ease-in-out';
 /**
 * This hook is a very thin wrapper around a `useState`.
 */
-export function useCollapsible(initialState: boolean | (() => boolean) = false) {
+export const useCollapsible = (initialState: boolean | (() => boolean) = false) => {
   const [collapsed, setCollapsed] = useState(initialState ?? false);
 
   const toggleCollapsed = useCallback(() => {
@@ -52,7 +52,7 @@ const ExpandedStyles = {
   height: 'auto',
 } as const;
 
-function applyCollapsedStyle(el: HTMLElement, collapsed: boolean) {
+const applyCollapsedStyle = (el: HTMLElement, collapsed: boolean) => {
   const collapsedStyles = collapsed ? CollapsedStyles : ExpandedStyles;
   el.style.display = collapsedStyles.display;
   el.style.overflow = collapsedStyles.overflow;
@@ -65,7 +65,7 @@ is good for a large number of items.
 https://material.io/archive/guidelines/motion/duration-easing.html#duration-easing-dynamic-durations
 https://github.com/mui-org/material-ui/blob/e724d98eba018e55e1a684236a2037e24bcf050c/packages/material-ui/src/styles/createTransitions.js#L40-L43
 */
-function getAutoHeightDuration(height: number) {
+const getAutoHeightDuration = (height: number) => {
   const constant = height / 36;
   return Math.round((4 + 15 * constant ** 0.25 + constant / 5) * 10);
 }
@@ -75,21 +75,21 @@ type CollapsibleAnimationConfig = {
   easing?: string;
 };
 
-function useCollapseAnimation({
+const useCollapseAnimation = ({
   collapsibleRef,
   collapsed,
   animation,
 }: {
   collapsibleRef: RefObject<HTMLElement>;
   collapsed: boolean;
   animation?: CollapsibleAnimationConfig;
-}) {
+}) => {
   const mounted = useRef(false);
 
   useEffect(() => {
     const el = collapsibleRef.current!;
 
-    function getTransitionStyles() {
+    const getTransitionStyles = () => {
       const height = el.scrollHeight;
       const duration = animation?.duration ?? getAutoHeightDuration(height);
       const easing = animation?.easing ?? DefaultAnimationEasing;
@@ -99,7 +99,7 @@ function useCollapseAnimation({
       };
     }
 
-    function applyTransitionStyles() {
+    const applyTransitionStyles = () => {
       const transitionStyles = getTransitionStyles();
       el.style.transition = transitionStyles.transition;
       el.style.height = transitionStyles.height;
@@ -114,7 +114,7 @@ function useCollapseAnimation({
 
     el.style.willChange = 'height';
 
-    function startAnimation() {
+    const startAnimation = () => {
       const animationFrame = requestAnimationFrame(() => {
         // When collapsing
         if (collapsed) {
@@ -149,7 +149,7 @@ type CollapsibleElementType = React.ElementType<
 * Prevent hydration layout shift before animations are handled imperatively
 * with JS
 */
-function getSSRStyle(collapsed: boolean) {
+const getSSRStyle = (collapsed: boolean) => {
   if (!canUseDOM) {
     return undefined;
   }
@@ -181,15 +181,15 @@ type CollapsibleBaseProps = {
   disableSSRStyle?: boolean;
 };
 
-function CollapsibleBase({
+const CollapsibleBase = ({
   as: As = 'div',
   collapsed,
   children,
   animation,
   onCollapseTransitionEnd,
   className,
   disableSSRStyle,
-}: CollapsibleBaseProps) {
+}: CollapsibleBaseProps) => {
   // any because TS is a pain for HTML element refs, see https://twitter.com/sebastienlorber/status/1412784677795110914
   const collapsibleRef = useRef<any>(null);
 
@@ -215,7 +215,7 @@ function CollapsibleBase({
   );
 }
 
-function CollapsibleLazy({collapsed, ...props}: CollapsibleBaseProps) {
+const CollapsibleLazy = ({collapsed, ...props}: CollapsibleBaseProps) => {
   const [mounted, setMounted] = useState(!collapsed);
 
   useIsomorphicLayoutEffect(() => {
@@ -252,7 +252,9 @@ type CollapsibleProps = CollapsibleBaseProps & {
 * component will be invisible (zero height) when collapsed. Doesn't provide
 * interactivity by itself: collapse state is toggled through props.
 */
-export default function Collapsible({lazy, ...props}: CollapsibleProps): JSX.Element {
+const Collapsible = ({lazy, ...props}: CollapsibleProps): JSX.Element => {
   const Comp = lazy ? CollapsibleLazy : CollapsibleBase;
   return <Comp {...props} />;
-}
+}
+
+export default Collapsible;

website/src/components/Navbar/styles.export.module.scss

@@ -0,0 +1,6 @@
+@use "@/styles/utils";
+@use "./styles.module.scss" as *;
+
+:export {
+  navbarHeight: utils.strip-units($navbar-height);
+}

website/src/components/Navbar/styles.export.module.scss.d.ts

@@ -0,0 +1,17 @@
+// AUTOGENERATED FILE -- DO NOT EDIT DIRECTLY
+
+declare namespace StylesExportModuleScssNamespace {
+  export interface IStylesExportModuleScss {
+    hidden: string;
+    left: string;
+    logo: string;
+    navItem: string;
+    navbar: string;
+    navbarHeight: string;
+    right: string;
+  }
+}
+
+declare const StylesExportModuleScssModule: StylesExportModuleScssNamespace.IStylesExportModuleScss;
+
+export = StylesExportModuleScssModule;

website/src/components/Navbar/styles.module.scss

@@ -4,7 +4,7 @@ $navbar-height: 76px;
 
 .navbar {
   z-index: 10;
-  position: sticky;
+  position: fixed;
   top: 0;
   width: 100%;
   height: $navbar-height;

website/src/components/Sidebar/styles.module.scss

@@ -8,12 +8,14 @@
 @use "@/styles/colors";
 @use "@/styles/mixins";
 
+$desktop-sidebar-width: 300px;
+
 .items {
   list-style: none;
   margin: 0;
   padding: 0;
 
-  .items {
+  & & {
     flex: 0 0 100%;
     margin-top: 0.25rem;
     padding-left: 1rem;
@@ -70,15 +72,8 @@ $arrow-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg
 
 /* desktop sidebar */
 
-$desktop-sidebar-width: 300px;
-
 .desktop {
-  @include mixins.desktop-only(flex) {
+  @include mixins.desktop-only() {
     width: $desktop-sidebar-width;
-    flex-direction: column;
-    padding-top: var(--header-height, 0);
-    overflow-x: hidden;
-
-    @include mixins.scrollbar();
   }
 }

website/src/components/Toc/Desktop.tsx

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE-docusaurus file in the root directory of the website source tree.
+ */
+
+import c from "clsx"
+
+import Toc from "."
+
+import { markdown } from "@/mdx/markdown.module.scss"
+import s from "./styles.module.scss"
+
+import type { TocProps } from "../Toc"
+
+interface TocDesktopProps extends Omit<TocProps, 'linkClassName' | 'activeClassName'> {}
+
+export default function TocDesktop ({
+  toc,
+  minLevel = 2,
+  maxLevel = 4,
+  className,
+}: TocDesktopProps) {
+  
+  return (
+    <nav className={c(s.nav, className)}>
+      <h2 className={s.heading}>Table of Contents</h2>
+      <TocDesktopItems
+        toc={toc}
+        minLevel={minLevel}
+        maxLevel={maxLevel}
+      />
+    </nav>
+  )
+}
+
+export const TocDesktopItems = ({
+  toc,
+  minLevel = 2,
+  maxLevel = 4,
+  className,
+  linkClassName,
+  linkActiveClassName,
+}: TocProps) => (
+  <Toc
+    className={c(markdown, s.items, className)}
+    toc={toc}
+    minLevel={minLevel}
+    maxLevel={maxLevel}
+    linkClassName={c(s.link, linkClassName)}
+    linkActiveClassName={c(s.active, linkActiveClassName)}
+  />
+)

website/src/components/Toc/index.tsx

@@ -0,0 +1,80 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE-docusaurus file in the root directory of the website source tree.
+ */
+
+import useTocFilter from "./utils/filter-headings"
+import useActiveTocItem from "./utils/active-heading"
+
+import type { FC, MouseEventHandler } from "react"
+import type { HeadingLevel, TocItem } from "@/lib/unified/toc/types"
+
+export interface TocProps {
+  toc: TocItem[]
+  minLevel?: HeadingLevel
+  maxLevel?: HeadingLevel
+  className?: string
+  linkClassName?: string
+  linkActiveClassName?: string
+  onClick?: MouseEventHandler<HTMLAnchorElement>
+}
+
+const Toc: FC<TocProps> = ({
+  toc,
+  minLevel = 2,
+  maxLevel = 4,
+  className,
+  linkClassName = '',
+  linkActiveClassName = '',
+  onClick,
+}) => {
+  const filteredToc = useTocFilter({ toc, minLevel, maxLevel })
+
+  useActiveTocItem(filteredToc, {
+    linkClassName,
+    linkActiveClassName,
+  })
+
+  return (
+    <TocItems
+      toc={filteredToc}
+      className={className}
+      linkClassName={linkClassName}
+      onClick={onClick}
+    />
+  )
+}
+
+export default Toc
+
+interface TocItemsProps {
+  toc: TocItem[]
+  className?: string
+  linkClassName?: string
+  onClick?: MouseEventHandler<HTMLAnchorElement>
+}
+
+const TocItems: FC<TocItemsProps> = ({ toc, className, linkClassName, onClick }) => {
+  return toc.length === 0 ? null : (
+    <ul className={className}>
+      {toc.map(({ id, children, value }) => (
+        <li key={id}>
+          <a
+            className={linkClassName}
+            href={`#${id}`}
+            onClick={onClick}
+            // Developer provided the HTML, so assume it's safe.
+            dangerouslySetInnerHTML={{ __html: value }}
+          />
+          <TocItems
+            toc={children}
+            linkClassName={linkClassName}
+            onClick={onClick}
+          />
+        </li>
+      ))}
+    </ul>
+  )
+}