Contents Nav

npm install motion clsx tailwind-merge

import { clsx, type ClassValue } from "clsx";
import { extendTailwindMerge } from "tailwind-merge";

/* tailwind-merge must know the site's type scale (globals.css) is a font size, not a text color — otherwise
   cn("text-h6 text-muted-foreground") drops text-h6. */
const twMerge = extendTailwindMerge({
  extend: { classGroups: { "font-size": [{ text: ["display", "h1", "h2", "h3", "h4", "h5", "h6"] }] } },
});

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

"use client";

import * as React from "react";
import { cn } from "@/lib/utils";

/*
 * Contents Nav — a list of links to the sections of the page, with the one you are reading marked: its label takes the primary
 * colour and an arrow comes in at its right. A link scrolls smoothly to its section (from the KorDent service page "On this
 * page" card, and its Home "Outcomes" index; Metuo's why and values are the same idea, written in the block).
 *
 * Which entry is active: the last section whose top has passed a line. `line="top"` puts the line `offset` px from the top of
 * the window (KorDent's service page: 50, under its fixed header; nothing is active before the first section gets there);
 * `line="third"` puts it a third of the way down (the Outcomes index: the card that crosses the top third of the window). When
 * the sections are in a box that scrolls, the line is measured from that box's own top. The state only changes when the
 * active entry does, and it is read from a passive scroll listener (one frame at a time), never from the render. The server sends
 * the list of links and no active entry, so the markup does not depend on where the page is scrolled; without script the links
 * are plain anchors.
 *
 * A click scrolls its section into view, with a smooth scroll that jumps when the visitor asked for reduced motion, and the
 * section keeps `offset` px above it: the component sets scroll-margin-top on the sections it finds, and puts it back when it
 * goes. The colour change and the arrow are KorDent's spring (bounce 0.2, 0.4s) as a CSS linear() curve sampled from the spring
 * (tools/ui/spring-curve.mjs, within 1%), with cubic-bezier(0.22, 1, 0.36, 1) for a browser without linear(); the arrow's small
 * slide is off with reduced motion. The active entry has aria-current="location".
 *
 * `sticky` (px from the top) holds the nav while the page scrolls, with CSS alone: an ancestor with overflow hidden or auto
 * stops position: sticky from working (overflow: clip does not). Inactive entries are foreground at 65%, 5.1:1 or better in
 * the four sample themes, light and dark, and the active one is the primary colour on the card.
 */

const ease =
  "[--cn-ease:cubic-bezier(0.22,1,0.36,1)] supports-[transition-timing-function:linear(0,1)]:[--cn-ease:linear(0,0.041,0.138,0.262,0.393,0.518,0.631,0.727,0.806,0.869,0.917,0.953,0.978,0.995,1.006,1.012,1.015,1.015,1.014,1.013,1.011,1.009,1.007,1.005,1.004,1.003,1.002,1.001,1.001,1)]";

export type ContentsNavItem = {
  /** The id of the section it links to. */
  id: string;
  label: React.ReactNode;
  /** Shown before the label when `numbered` is on; 01, 02… by default. */
  number?: React.ReactNode;
};

export type ContentsNavProps = {
  items: ContentsNavItem[];
  /** Accessible name of the navigation. */
  label: string;
  /** Where the line sits: `offset` px from the top, or a third of the way down. */
  line?: "top" | "third";
  /** Px from the top for line="top", and what a section keeps above it after a click. */
  offset?: number;
  /** Px from the top at which the nav sticks while the page scrolls. Left out, it scrolls with the page. */
  sticky?: number;
  /** A number before each label. */
  numbered?: boolean;
  className?: string;
};

/* The nearest ancestor that scrolls, or null for the window. */
function scrollParent(element: HTMLElement | null) {
  for (let parent = element?.parentElement ?? null; parent; parent = parent.parentElement) {
    const overflow = getComputedStyle(parent).overflowY;
    if (overflow === "auto" || overflow === "scroll") return parent;
  }
  return null;
}

export function ContentsNav({ items, label, line = "top", offset = 50, sticky, numbered = false, className }: ContentsNavProps) {
  const [active, setActive] = React.useState<string | null>(null);
  const ids = items.map((item) => item.id).join("|");

  React.useEffect(() => {
    const sections = ids.split("|").map((id) => document.getElementById(id));
    const previous = sections.map((section) => section?.style.scrollMarginTop ?? "");
    sections.forEach((section) => {
      if (section) section.style.scrollMarginTop = `${offset}px`;
    });
    const root = scrollParent(sections.find(Boolean) ?? null);
    let frame = 0;
    const update = () => {
      frame = 0;
      const box = root ? root.getBoundingClientRect() : { top: 0, height: window.innerHeight };
      const lineY = box.top + (line === "third" ? box.height * 0.33 : offset);
      let found: string | null = null;
      sections.forEach((section, index) => {
        if (section && section.getBoundingClientRect().top <= lineY + 1) found = ids.split("|")[index];
      });
      setActive((current) => (current === found ? current : found));
    };
    const schedule = () => {
      if (!frame) frame = requestAnimationFrame(update);
    };
    update();
    /* A scroll does not bubble, so listen in the capture phase: that also hears a box that scrolls. */
    document.addEventListener("scroll", schedule, { capture: true, passive: true });
    window.addEventListener("resize", schedule);
    return () => {
      cancelAnimationFrame(frame);
      document.removeEventListener("scroll", schedule, { capture: true });
      window.removeEventListener("resize", schedule);
      sections.forEach((section, index) => {
        if (section) section.style.scrollMarginTop = previous[index];
      });
    };
  }, [ids, line, offset]);

  function go(event: React.MouseEvent, id: string) {
    const section = document.getElementById(id);
    if (!section) return;
    event.preventDefault();
    const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
    section.scrollIntoView({ behavior: reduce ? "auto" : "smooth", block: "start" });
  }

  return (
    <nav
      aria-label={label}
      style={sticky !== undefined ? { ["--contents-sticky" as string]: `${sticky}px` } : undefined}
      className={cn("w-full max-w-xs", ease, sticky !== undefined && "sticky top-(--contents-sticky) self-start", className)}
    >
      <ul className="divide-y overflow-hidden rounded-xl border bg-card text-card-foreground">
        {items.map((item, index) => (
          <li key={item.id}>
            <a
              href={`#${item.id}`}
              onClick={(event) => go(event, item.id)}
              aria-current={active === item.id ? "location" : undefined}
              className="group flex items-center gap-3 px-4 py-3 text-sm font-medium text-foreground/65 outline-none transition-colors duration-400 ease-(--cn-ease) hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:ring-inset aria-[current=location]:text-primary motion-reduce:transition-none"
            >
              {numbered && <span className="w-7 shrink-0 tabular-nums">{item.number ?? String(index + 1).padStart(2, "0")}</span>}
              <span className="flex-1">{item.label}</span>
              <svg
                aria-hidden
                viewBox="0 0 18 18"
                fill="none"
                stroke="currentColor"
                strokeWidth={1.5}
                strokeLinecap="round"
                strokeLinejoin="round"
                className="size-[18px] shrink-0 -translate-x-1 opacity-0 transition-[opacity,translate] duration-400 ease-(--cn-ease) group-aria-[current=location]:translate-x-0 group-aria-[current=location]:opacity-100 motion-reduce:translate-x-0 motion-reduce:transition-none"
              >
                <path d="M4 9h10M10 5l4 4-4 4" />
              </svg>
            </a>
          </li>
        ))}
      </ul>
    </nav>
  );
}