Table of contents

"use client";

import { useEffect, useId, useRef, useState, type ComponentProps, type MouseEvent, type ReactNode } from "react";
import "./table-of-contents.css";

export type TocHeading = {
  /** The heading element's id. */
  id: string;
  label: ReactNode;
  /** Heading level, 2 for h2 and so on. Deeper levels nest under the one before. */
  level?: number;
};

export type TableOfContentsProps = Omit<ComponentProps<"nav">, "title"> & {
  /** The headings on the page, in document order. */
  items: TocHeading[];
  /** The visible title, which also names the landmark. */
  title?: ReactNode;
  /** Pixels between the top of the scroll area and a heading that has been scrolled to, for a sticky header. */
  offset?: number;
  /** Writes the heading's id into the address bar when a link is followed. */
  updateHash?: boolean;
};

type TocNode = TocHeading & { children: TocNode[] };

/** Turns a flat list with levels into a tree: each item nests under the nearest shallower one before it. */
function nest(items: TocHeading[]): TocNode[] {
  const root: TocNode[] = [];
  const stack: { level: number; children: TocNode[] }[] = [{ level: -Infinity, children: root }];
  for (const item of items) {
    const level = item.level ?? 2;
    while (stack.length > 1 && stack[stack.length - 1].level >= level) stack.pop();
    const node: TocNode = { ...item, children: [] };
    stack[stack.length - 1].children.push(node);
    stack.push({ level, children: node.children });
  }
  return root;
}

/** The nearest ancestor that scrolls vertically, or null for the page itself. */
function scrollParent(element: HTMLElement): HTMLElement | null {
  for (let node = element.parentElement; node && node !== document.body; node = node.parentElement) {
    const overflow = getComputedStyle(node).overflowY;
    if (overflow === "auto" || overflow === "scroll" || overflow === "overlay") return node;
  }
  return null;
}

/** Smooth unless the motion tokens are at zero, which is where reduced motion puts them. */
function scrollBehavior(element: Element): ScrollBehavior {
  const value = getComputedStyle(element).getPropertyValue("--eq-dur-move").trim();
  return parseFloat(value) === 0 ? "auto" : "smooth";
}

/** A heading counts as reached once its top passes this share of the scroll area. */
const LINE = 0.3;

export function TableOfContents({
  items,
  title = "On this page",
  offset = 0,
  updateHash = true,
  className,
  "aria-label": ariaLabel,
  ...rest
}: TableOfContentsProps) {
  const titleId = useId();
  const [active, setActive] = useState<string | null>(null);
  const lock = useRef<string | null>(null);
  const ids = items.map((item) => item.id).join(" ");

  useEffect(() => {
    const headings = ids
      .split(" ")
      .map((id) => document.getElementById(id))
      .filter((element): element is HTMLElement => element !== null);
    if (headings.length === 0) return;
    const box = scrollParent(headings[0]);

    function pick() {
      if (lock.current) return;
      const top = box ? box.getBoundingClientRect().top : 0;
      const height = box ? box.clientHeight : window.innerHeight;
      const line = top + offset + (height - offset) * LINE;
      // At the very end the last sections may never reach the line; the last one in view wins then.
      const scroller = box ?? document.scrollingElement;
      const atEnd = scroller ? scroller.scrollTop > 0 && scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 2 : false;
      const reach = atEnd ? top + height : line;
      let current = headings[0].id;
      for (const heading of headings) {
        if (heading.getBoundingClientRect().top <= reach) current = heading.id;
        else break;
      }
      setActive(current);
    }

    // The observer's band ends at the line, so it reports exactly when a heading crosses it.
    const observer = new IntersectionObserver(pick, {
      root: box,
      rootMargin: `${-offset}px 0px ${-(1 - LINE) * 100}% 0px`,
      threshold: [0, 1],
    });
    for (const heading of headings) observer.observe(heading);
    // Reaching the end crosses no heading, so the end of each scroll is checked too.
    const source: HTMLElement | Window = box ?? window;
    source.addEventListener("scrollend", pick);
    pick();
    return () => {
      observer.disconnect();
      source.removeEventListener("scrollend", pick);
    };
  }, [ids, offset]);

  function follow(event: MouseEvent<HTMLAnchorElement>, id: string) {
    const heading = document.getElementById(id);
    if (!heading || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
    event.preventDefault();
    const box = scrollParent(heading);
    const behavior = scrollBehavior(event.currentTarget);
    if (box) {
      const top = box.scrollTop + heading.getBoundingClientRect().top - box.getBoundingClientRect().top - offset;
      box.scrollTo({ top, behavior });
    } else {
      window.scrollTo({ top: window.scrollY + heading.getBoundingClientRect().top - offset, behavior });
    }

    // Hold the highlight on the chosen heading until the scroll settles.
    setActive(id);
    lock.current = id;
    const source: HTMLElement | Window = box ?? window;
    // Released a moment after the scroll ends, so late observer reports from the jump are ignored.
    const release = () => {
      source.removeEventListener("scrollend", settle);
      if (lock.current === id) lock.current = null;
    };
    const settle = () => window.setTimeout(release, 150);
    source.addEventListener("scrollend", settle);
    window.setTimeout(release, 1500);

    // Focus follows, so the next Tab continues from the section and screen readers read it.
    if (!heading.hasAttribute("tabindex")) heading.setAttribute("tabindex", "-1");
    heading.focus({ preventScroll: true });
    if (updateHash) history.replaceState(history.state, "", `#${id}`);
  }

  function list(nodes: TocNode[], depth: number): ReactNode {
    return (
      <ol className="eq-table-of-contents-list" data-depth={depth}>
        {nodes.map((node) => (
          <li key={node.id} className="eq-table-of-contents-item">
            <a
              className="eq-table-of-contents-link"
              href={`#${node.id}`}
              aria-current={active === node.id ? "location" : undefined}
              onClick={(event) => follow(event, node.id)}
            >
              {node.label}
            </a>
            {node.children.length > 0 && list(node.children, depth + 1)}
          </li>
        ))}
      </ol>
    );
  }

  return (
    <nav
      {...rest}
      aria-label={ariaLabel}
      aria-labelledby={ariaLabel ? undefined : titleId}
      className={["eq-table-of-contents", className].filter(Boolean).join(" ")}
    >
      <p id={titleId} className="eq-table-of-contents-title">
        {title}
      </p>
      {list(nest(items), 0)}
    </nav>
  );
}