components/anchor-bar/anchor-bar.ts

Functions

Imports

It imports no other module of this repo. Imported by components/anchor-bar/anchor-bar.react.tsx.

Source

1// The "On this page" bar: links to a long view's sections, sticky at the top, with the
2// current section marked aria-current="location". Only for a view with three or more
3// sections that is taller than two screens; otherwise the module hides the bar, unless it has
4// data-always. The rule is measured again whenever the window or the content changes size,
5// so a view that fills in after it loads (a panel arriving with its data) gets its bar when it
6// earns one, and loses it when it stops. Following a link moves focus to the section and
7// replaces the address's hash. No framework; the React wrapper uses the same functions.
8//
9// The measuring and the "bar's own height does not count" rule are the Portal's
10// (dashboard/src/ui/anchors.tsx), which learned that mounting the bar could otherwise tip the
11// rule it was mounted by.
12
13// The nearest ancestor that scrolls, or null for the window.
14export function scrollParent(el: Element | null | undefined): HTMLElement | null {
15  for (let n = el?.parentElement ?? null; n && n !== document.body && n !== document.documentElement; n = n.parentElement) {
16    const o = getComputedStyle(n).overflowY;
17    if (o === "auto" || o === "scroll") return n;
18  }
19  return null;
20}
21
22// What the bar links to: the blocks of the page marked data-section with an id (a panel: its
23// data-section is the link's name), or, when there are none, its h2 headings that have one.
24export function sectionsIn(scope: ParentNode): HTMLElement[] {
25  const blocks = Array.from(scope.querySelectorAll<HTMLElement>("[data-section][id]"));
26  return blocks.length ? blocks : Array.from(scope.querySelectorAll<HTMLElement>("h2[id]"));
27}
28
29export function sectionLabel(section: HTMLElement): string {
30  return section.dataset.section ?? section.textContent?.trim() ?? section.id;
31}
32
33// The rule: three or more sections, and a view taller than two screens. The bar's own height
34// does not count (`barHeight`), or showing it could tip the rule it was shown by.
35export function meetsRule(headings: Element[], scroller: HTMLElement | null, barHeight = 0): boolean {
36  if (headings.length < 3) return false;
37  const total = (scroller ? scroller.scrollHeight : document.documentElement.scrollHeight) - barHeight;
38  const screen = scroller ? scroller.clientHeight : window.innerHeight;
39  return total > 2 * screen;
40}
41
42// The current section: the last heading above a line 35% down the view, or the last
43// heading once the view is scrolled to its end.
44export function currentSection(headings: HTMLElement[], scroller: HTMLElement | null, line = 0.35): HTMLElement | null {
45  const top = scroller ? scroller.getBoundingClientRect().top : 0;
46  const height = scroller ? scroller.clientHeight : window.innerHeight;
47  const y = top + height * line;
48  let cur: HTMLElement | null = null;
49  for (const h of headings) if (h.getBoundingClientRect().top <= y) cur = h;
50  const atEnd = scroller
51    ? scroller.scrollTop > 0 && scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 2
52    : window.scrollY > 0 && window.scrollY + window.innerHeight >= document.documentElement.scrollHeight - 2;
53  if (atEnd) cur = headings.at(-1) ?? cur;
54  return cur;
55}
56
57// Calls onChange with the current section's id whenever it changes. Returns a function
58// that stops watching.
59export function watchSections(headings: HTMLElement[], onChange: (id: string | null) => void, scroller: HTMLElement | null = scrollParent(headings[0])): () => void {
60  let last: string | null | undefined;
61  const update = () => {
62    const id = currentSection(headings, scroller)?.id ?? null;
63    if (id !== last) {
64      last = id;
65      onChange(id);
66    }
67  };
68  // A heading crossing the 35% line is what changes the answer.
69  const io = new IntersectionObserver(update, { root: scroller, rootMargin: "0px 0px -65% 0px", threshold: [0, 1] });
70  for (const h of headings) io.observe(h);
71  // The end of the view, where the last heading may never reach the line.
72  const target: EventTarget = scroller ?? window;
73  target.addEventListener("scrollend", update);
74  update();
75  return () => {
76    io.disconnect();
77    target.removeEventListener("scrollend", update);
78  };
79}
80
81const reduced = () => window.matchMedia("(prefers-reduced-motion: reduce)").matches;
82
83// Scrolls a section to the top, under the bar, moves focus to it, and replaces the address's
84// hash (a click on an in-page link is not a place to go Back to). `push: true` adds an entry.
85export function goToSection(heading: HTMLElement, opts: { push?: boolean } = {}): void {
86  if (!heading.hasAttribute("tabindex")) heading.tabIndex = -1;
87  heading.scrollIntoView({ block: "start", behavior: reduced() ? "auto" : "smooth" });
88  heading.focus({ preventScroll: true });
89  if (heading.id) {
90    if (opts.push) history.pushState(null, "", `#${heading.id}`);
91    else history.replaceState(history.state, "", `#${heading.id}`);
92  }
93}
94
95// Tells the page how tall the bar is, so a section scrolled to sits below it.
96export function measureBar(nav: HTMLElement, scroller: HTMLElement | null): void {
97  (scroller ?? document.documentElement).style.setProperty("--cap-anchors-h", `${Math.ceil(nav.getBoundingClientRect().height)}px`);
98}
99
100// Marks the sections the bar links to, so each stops below the bar when scrolled to.
101export function markSections(headings: HTMLElement[]): void {
102  for (const h of headings) {
103    if (!h.hasAttribute("tabindex")) h.tabIndex = -1;
104    h.dataset.capAnchor = "";
105  }
106}
107
108// Attaches to every [data-cap="anchor-bar"] under root. A bar with an empty list is filled
109// from the sections in its scope (data-cap-scope, or its main) and kept in step with them.
110// Returns a function that detaches them.
111export function enhance(root: ParentNode = document): () => void {
112  const undo: Array<() => void> = [];
113  for (const nav of root.querySelectorAll<HTMLElement>("[data-cap='anchor-bar']:not([data-cap-ready])")) {
114    nav.dataset.capReady = "";
115    const scope = (nav.dataset.capScope ? document.querySelector(nav.dataset.capScope) : nav.closest("main")) ?? document.body;
116    const scroller = scrollParent(nav);
117    const always = nav.hasAttribute("data-always");
118    let list = nav.querySelector("ul");
119    const auto = !list?.querySelector("a");
120    if (!list) {
121      list = document.createElement("ul");
122      list.className = "cap-anchors-list";
123      nav.append(list);
124    }
125    const ul = list;
126
127    // An empty list is rebuilt from the sections whenever they change. True when it changed.
128    let filled = "";
129    const fill = (): boolean => {
130      const sections = sectionsIn(scope);
131      const key = sections.map((s) => `${s.id}\u0000${sectionLabel(s)}`).join("\u0001");
132      if (key === filled) return false;
133      filled = key;
134      ul.replaceChildren(
135        ...sections.map((s) => {
136          const li = document.createElement("li");
137          const a = document.createElement("a");
138          a.href = `#${s.id}`;
139          a.textContent = sectionLabel(s);
140          li.append(a);
141          return li;
142        }),
143      );
144      return true;
145    };
146    let pairs: Array<{ a: HTMLAnchorElement; h: HTMLElement }> = [];
147    const resolve = () => {
148      pairs = Array.from(nav.querySelectorAll<HTMLAnchorElement>("a[href^='#']"))
149        .map((a) => ({ a, h: document.getElementById(decodeURIComponent(a.hash.slice(1))) }))
150        .filter((p): p is { a: HTMLAnchorElement; h: HTMLElement } => p.h !== null);
151    };
152    if (auto) fill();
153    resolve();
154
155    let stop: (() => void) | null = null;
156    const halt = () => {
157      stop?.();
158      stop = null;
159      for (const p of pairs) p.a.removeAttribute("aria-current");
160    };
161    const apply = () => {
162      if (auto && fill()) {
163        halt();
164        resolve();
165      }
166      const headings = pairs.map((p) => p.h);
167      const ok = always || meetsRule(headings, scroller, nav.offsetHeight);
168      // Only on a change: setting the attribute again would be a mutation, and the mutation
169      // observer below would measure again, without end.
170      if (nav.hidden === ok) nav.hidden = !ok;
171      if (ok) {
172        markSections(headings);
173        measureBar(nav, scroller);
174        stop ??= watchSections(
175          headings,
176          (id) => {
177            for (const p of pairs) {
178              if (p.h.id === id) p.a.setAttribute("aria-current", "location");
179              else p.a.removeAttribute("aria-current");
180            }
181          },
182          scroller,
183        );
184      } else halt();
185    };
186
187    const ro = new ResizeObserver(apply);
188    ro.observe(scroller ?? document.documentElement);
189    ro.observe(nav);
190    const mo = new MutationObserver(apply);
191    mo.observe(scope, { childList: true, subtree: true, attributes: true, attributeFilter: ["data-section", "id", "hidden"] });
192    apply();
193
194    const onClick = (e: MouseEvent) => {
195      if (e.ctrlKey || e.metaKey || e.shiftKey || e.button !== 0) return;
196      const a = (e.target as Element).closest<HTMLAnchorElement>("a[href^='#']");
197      const pair = pairs.find((p) => p.a === a);
198      if (!pair) return;
199      e.preventDefault();
200      goToSection(pair.h);
201    };
202    nav.addEventListener("click", onClick);
203    undo.push(() => {
204      halt();
205      ro.disconnect();
206      mo.disconnect();
207      nav.removeEventListener("click", onClick);
208      nav.hidden = false;
209      delete nav.dataset.capReady;
210    });
211  }
212  return () => undo.forEach((f) => f());
213}