@abreen/tada 1.0.0

package/src/toc/index.ts

@@ -0,0 +1,322 @@
+import { debounce } from '../util';
+
+const LATENCY_MS = 50;
+
+type HeadingLevel = '1' | '2' | '3' | '4' | '5' | '6';
+type AlertType = 'warning' | 'note';
+
+type Alert = { type: AlertType; title: string };
+type Heading = { level: HeadingLevel; innerHtml: string; id: string };
+type Dinkus = { type: 'dinkus' };
+
+function getContainer(parent: HTMLElement): HTMLElement | null {
+  return parent.querySelector('nav.toc');
+}
+
+function getCurrentListItem(parent: HTMLElement): HTMLLIElement | null {
+  return parent.querySelector('nav.toc .current');
+}
+
+function scrollIfNeeded(element: HTMLElement) {
+  const container = getContainer(document.body);
+  if (container == null) {
+    return;
+  }
+  const containerHasScrollbar = container.scrollHeight > container.clientHeight;
+  if (!containerHasScrollbar) {
+    return;
+  }
+
+  // Calculate element center relative to container's scroll space
+  const elementRect = element.getBoundingClientRect();
+  const containerRect = container.getBoundingClientRect();
+  const elementCenter =
+    elementRect.top -
+    containerRect.top +
+    container.scrollTop +
+    elementRect.height / 2;
+  const desiredScrollTop = elementCenter - container.clientHeight / 2;
+
+  container.scrollTop = desiredScrollTop;
+}
+
+function getHighlightIndexes(items: (Heading | Alert | Dinkus)[]) {
+  const indexes: (number | null)[] = [];
+  let currentHeadingIndex: number | null = null;
+  let tocIndex = 0;
+
+  items.forEach(item => {
+    if (!('level' in item) && item.type === 'dinkus') {
+      return;
+    }
+
+    if ('level' in item) {
+      currentHeadingIndex = tocIndex;
+    }
+
+    indexes.push(currentHeadingIndex ?? tocIndex);
+    tocIndex++;
+  });
+
+  return indexes;
+}
+
+function getHeadingsAndAlerts(
+  parent: HTMLElement,
+): (HTMLHeadingElement | HTMLDivElement)[] {
+  return Array.from(
+    parent.querySelectorAll(
+      '.body h1, .body h2, .body h3, .body h4, .body h5, .body h6, .body > div.alert, .body section > div.alert',
+    ),
+  );
+}
+
+function getTocElements(
+  parent: HTMLElement,
+): (HTMLHeadingElement | HTMLDivElement | HTMLHRElement)[] {
+  return Array.from(
+    parent.querySelectorAll(
+      '.body h1, .body h2, .body h3, .body h4, .body h5, .body h6, .body > div.alert, .body section > div.alert, .body > hr',
+    ),
+  );
+}
+
+/* Calculate how much to offset scroll calculations based on floating header */
+function getHeaderOffset() {
+  const element = document.querySelector('header details summary');
+  if (!element) {
+    return 0;
+  }
+
+  return element.getBoundingClientRect().height;
+}
+
+function getViewportActivationPoint() {
+  const headerOffset = getHeaderOffset();
+
+  return headerOffset + (window.innerHeight - headerOffset) / 3;
+}
+
+function headingToTableItem(el: HTMLHeadingElement): Heading {
+  const level = el.tagName[1] as HeadingLevel;
+
+  const subtitle = el.querySelector('.heading-subtitle');
+  const subtitleText = subtitle?.textContent || '';
+  let mainText = el.textContent || '';
+
+  if (mainText.length > 0 && subtitleText.length > 0) {
+    mainText = mainText.replace(subtitleText, '').trim();
+    return {
+      level,
+      id: el.id,
+      innerHtml: `${mainText}: <span class="heading-subtitle">${subtitleText}</span>`,
+    };
+  }
+  return { level, id: el.id, innerHtml: el.innerHTML };
+}
+
+function alertToTableItem(el: HTMLElement): Alert | null {
+  const classes = el.className
+    .split(' ')
+    .map(cl => cl.trim())
+    .filter(cl => cl != 'alert');
+
+  const firstClass = classes[0];
+  if (firstClass === 'warning' || firstClass === 'note') {
+    let title = el.querySelector('.title')?.innerHTML;
+    if (!title) {
+      if (firstClass === 'warning') {
+        title = 'Warning';
+      } else {
+        title = 'Note';
+      }
+    }
+
+    return { type: firstClass, title };
+  }
+
+  return null;
+}
+
+function switchCurrent(
+  oldCurrent: HTMLElement | null,
+  newCurrent: HTMLElement,
+) {
+  if (oldCurrent) {
+    oldCurrent.classList.remove('current');
+  }
+  newCurrent.classList.add('current');
+}
+
+function wireAlertClickHandlers(
+  toc: HTMLElement,
+  headingsAndAlerts: (HTMLHeadingElement | HTMLDivElement)[],
+  items: (Heading | Alert | Dinkus)[],
+) {
+  const alertLinks = toc.querySelectorAll('li.alert-item a');
+  let alertIdx = 0;
+  let scrollIdx = 0;
+
+  items.forEach(item => {
+    if (!('level' in item) && (item as Alert | Dinkus).type === 'dinkus') {
+      return;
+    }
+
+    if (!('level' in item)) {
+      // This is an alert item
+      const scrollEl = headingsAndAlerts[scrollIdx];
+      const link = alertLinks[alertIdx] as HTMLAnchorElement | undefined;
+      if (link && scrollEl) {
+        link.onclick = (e: MouseEvent) => {
+          e.preventDefault();
+
+          const titleElement = scrollEl.querySelector('.title');
+          const titleId = titleElement?.id || null;
+
+          if (titleId) {
+            history.replaceState(
+              null,
+              document.title,
+              `${window.location.pathname}#${titleId}`,
+            );
+          }
+
+          scrollEl.scrollIntoView();
+          scrollEl.focus();
+        };
+      }
+      alertIdx++;
+    }
+
+    scrollIdx++;
+  });
+}
+
+export default (window: Window) => {
+  const toc = window.document.querySelector('nav.toc') as HTMLElement;
+  if (toc == null) {
+    return;
+  }
+
+  const isCodePage = window.document.body.classList.contains('code');
+
+  if (isCodePage) {
+    const elements: HTMLAnchorElement[] = Array.from(
+      toc.querySelectorAll('ol li a'),
+    );
+    if (elements.length === 0) {
+      return;
+    }
+
+    const codeLines: number[] = elements.map(a => {
+      const match = a.getAttribute('href')?.match(/^#L(\d+)$/);
+      return match ? parseInt(match[1], 10) : 0;
+    });
+
+    const parseHash = (hash: string): number | null => {
+      const single = hash.match(/^#L(\d+)$/);
+      if (single) {
+        return parseInt(single[1], 10);
+      }
+      const range = hash.match(/^#L(\d+)-L(\d+)$/);
+      if (range) {
+        return parseInt(range[1], 10);
+      }
+      return null;
+    };
+
+    const updateFromHash = () => {
+      const line = parseHash(window.location.hash);
+      const existingItem = getCurrentListItem(document.body);
+
+      if (line == null) {
+        if (existingItem) {
+          existingItem.classList.remove('current');
+        }
+        return;
+      }
+
+      let best = 0;
+      for (let i = 0; i < codeLines.length; i++) {
+        if (codeLines[i] <= line) {
+          best = i;
+        } else {
+          break;
+        }
+      }
+
+      const nextItem = elements[best]?.parentElement ?? null;
+      if (nextItem != null && nextItem !== existingItem) {
+        switchCurrent(existingItem, nextItem);
+        scrollIfNeeded(nextItem);
+      }
+    };
+
+    window.addEventListener('hashchange', updateFromHash);
+    updateFromHash();
+
+    return () => {
+      window.removeEventListener('hashchange', updateFromHash);
+    };
+  }
+
+  // Regular page: TOC is already rendered in the DOM
+  const elements: HTMLAnchorElement[] = Array.from(
+    toc.querySelectorAll('ol li a'),
+  );
+  if (elements.length === 0) {
+    return;
+  }
+
+  const headingsAndAlerts = getHeadingsAndAlerts(window.document.body);
+  const items = getTocElements(window.document.body)
+    .map(el => {
+      const tag = el.tagName.toLowerCase();
+      if (tag === 'hr') {
+        return { type: 'dinkus' } as Dinkus;
+      } else if (tag === 'div') {
+        return alertToTableItem(el as HTMLElement);
+      } else {
+        return headingToTableItem(el as HTMLHeadingElement);
+      }
+    })
+    .filter(obj => obj != null);
+
+  const highlightIndexes = getHighlightIndexes(items);
+
+  // Wire up click handlers for alert items
+  wireAlertClickHandlers(toc, headingsAndAlerts, items);
+
+  function handleScroll() {
+    const viewportActivationPoint = getViewportActivationPoint();
+
+    let i = 0;
+    for (let idx = 0; idx < headingsAndAlerts.length; idx++) {
+      const top = headingsAndAlerts[idx].getBoundingClientRect().top;
+      if (top <= viewportActivationPoint + 1) {
+        i = idx;
+      } else {
+        break;
+      }
+    }
+
+    const existingItem = getCurrentListItem(document.body);
+    const highlightIndex = highlightIndexes[i];
+    const nextItem =
+      highlightIndex == null ? null : elements[highlightIndex]?.parentElement;
+
+    if (nextItem != null && nextItem !== existingItem) {
+      switchCurrent(existingItem, nextItem);
+      scrollIfNeeded(nextItem);
+    }
+  }
+  const debounced = debounce(handleScroll, LATENCY_MS);
+  window.addEventListener('scroll', debounced, { passive: true });
+
+  // Call after load to set current item
+  handleScroll();
+
+  return () => {
+    window.removeEventListener('scroll', debounced);
+  };
+};

package/src/toc/style.scss

@@ -0,0 +1,203 @@
+@import '../_mixins.scss';
+
+:root {
+  --highlight-hue: 59deg;
+  --highlight-color: hsl(var(--highlight-hue) 100% 50% / 50%);
+  // For animations
+  --highlight-color-transparent: hsl(var(--highlight-hue) 50% 90% / 0%);
+}
+
+.toc {
+  @include user-select(none);
+
+  line-height: 1.4;
+}
+
+body.code .toc ol li:has(a) {
+  font-family: var(--mono-font);
+  font-size: var(--mono-font-size);
+}
+
+body.code .toc ol a {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.toc ol::before {
+  content: 'On this page';
+  display: block;
+  font-family: var(--mono-font);
+  font-style: italic;
+  font-size: var(--font-size-small);
+  text-align: center;
+}
+
+.toc ol {
+  margin: 0;
+  padding: 0;
+}
+
+.toc ol li {
+  list-style-type: none;
+  overflow-wrap: break-word;
+  margin-bottom: 0;
+}
+
+.toc ol a {
+  text-decoration: none;
+  border: none;
+  display: block;
+  padding: 4px 6px;
+  color: var(--fg-color);
+
+  &:focus-visible {
+    outline-offset: -2px;
+  }
+}
+
+@media (hover: hover) {
+  .toc ol li:has(a):hover,
+  .toc ol li:has(a):hover a {
+    color: var(--fg2-color);
+  }
+
+  .toc ol li a:active {
+    color: var(--link-active-color);
+  }
+}
+
+@media (min-width: 900px) {
+  .toc ol li.current a {
+    background: var(--bg2-color);
+  }
+
+  .toc ol li:last-child {
+    margin-bottom: var(--gap);
+  }
+
+  .toc ol::before {
+    display: none;
+    content: '';
+  }
+}
+
+.toc ol li.level1 {
+  font-size: var(--font-size-smaller);
+}
+
+.toc ol li.level2 {
+  font-size: var(--font-size-smaller);
+}
+
+.toc ol li.level3 {
+  font-size: var(--font-size-smaller);
+  margin-left: 10px;
+}
+
+.toc ol li.level4 {
+  font-size: var(--font-size-small);
+  font-weight: 450;
+  margin-left: 18px;
+}
+
+.toc ol li.level5 {
+  font-size: var(--font-size-small);
+  font-weight: 450;
+  margin-left: 24px;
+}
+
+.toc ol li.level6 {
+  font-size: var(--font-size-small);
+  font-weight: 450;
+  margin-left: 32px;
+}
+
+.toc ol li.dinkus-item {
+  height: 8px;
+  margin: 4px 0;
+  pointer-events: none;
+  background-color: var(--fg2-color);
+  mask-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 160 12'><rect x='0' y='5.5' width='96' height='1' fill='black'/><path d='M 64,6 C 71,6 80,4.5 80,1 C 80,4.5 89,6 96,6 C 89,6 80,7.5 80,11 C 80,7.5 71,6 64,6 Z' fill='black'/><rect x='64' y='5.5' width='96' height='1' fill='black'/></svg>");
+  mask-size: 100% 100%;
+  mask-repeat: no-repeat;
+}
+
+.toc ol li.alert-item {
+  position: relative;
+}
+
+.toc ol li.alert-item.warning a::before,
+.toc ol li.alert-item.note a::before {
+  display: inline-block;
+  height: 20px;
+  vertical-align: bottom;
+  margin-right: 4px;
+}
+
+.toc ol li.alert-item.warning a::before {
+  // fg-color
+  content: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 24 24'><polygon points='12,2 22,20 2,20' fill='none' stroke='hsl(20deg 8% 8%)' stroke-width='2' stroke-linejoin='round'/><line x1='12' y1='9' x2='12' y2='13' stroke='hsl(20deg 8% 8%)' stroke-width='2' stroke-linecap='round'/><line x1='12' y1='16' x2='12' y2='16' stroke='hsl(20deg 8% 8%)' stroke-width='2' stroke-linecap='round'/></svg>");
+}
+
+@media (prefers-color-scheme: dark) {
+  .toc ol li.alert-item.warning a::before {
+    // fg2-color
+    content: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 24 24'><polygon points='12,2 22,20 2,20' fill='none' stroke='hsl(20deg 20% 90%)' stroke-width='2' stroke-linejoin='round'/><line x1='12' y1='9' x2='12' y2='13' stroke='hsl(20deg 20% 90%)' stroke-width='2' stroke-linecap='round'/><line x1='12' y1='16' x2='12' y2='16' stroke='hsl(20deg 20% 90%)' stroke-width='2' stroke-linecap='round'/></svg>");
+  }
+}
+
+@media (hover: hover) {
+  .toc ol li.alert-item.warning:hover a::before,
+  .toc ol li.alert-item.warning a:hover::before {
+    // fg2-color
+    content: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 24 24'><polygon points='12,2 22,20 2,20' fill='none' stroke='hsl(20deg 6% 60%)' stroke-width='2' stroke-linejoin='round'/><line x1='12' y1='9' x2='12' y2='13' stroke='hsl(20deg 6% 60%)' stroke-width='2' stroke-linecap='round'/><line x1='12' y1='16' x2='12' y2='16' stroke='hsl(20deg 6% 60%)' stroke-width='2' stroke-linecap='round'/></svg>");
+  }
+}
+
+@media (hover: hover) and (prefers-color-scheme: dark) {
+  .toc ol li.alert-item.warning:hover a::before,
+  .toc ol li.alert-item.warning a:hover::before {
+    // fg2-color
+    content: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 24 24'><polygon points='12,2 22,20 2,20' fill='none' stroke='hsl(20deg 6% 55%)' stroke-width='2' stroke-linejoin='round'/><line x1='12' y1='9' x2='12' y2='13' stroke='hsl(20deg 6% 55%)' stroke-width='2' stroke-linecap='round'/><line x1='12' y1='16' x2='12' y2='16' stroke='hsl(20deg 6% 55%)' stroke-width='2' stroke-linecap='round'/></svg>");
+  }
+}
+
+.toc ol li.alert-item.note a::before {
+  // fg-color
+  content: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 24 24'><circle cx='12' cy='12' r='10' fill='none' stroke='hsl(20deg 8% 8%)' stroke-width='2'/><line x1='12' y1='10' x2='12' y2='16' stroke='hsl(20deg 8% 8%)' stroke-width='2' stroke-linecap='round'/><line x1='12' y1='7' x2='12' y2='7' stroke='hsl(20deg 8% 8%)' stroke-width='2' stroke-linecap='round'/></svg>");
+}
+
+@media (prefers-color-scheme: dark) {
+  .toc ol li.alert-item.note a::before {
+    // fg-color
+    content: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 24 24'><circle cx='12' cy='12' r='10' fill='none' stroke='hsl(20deg 20% 90%)' stroke-width='2'/><line x1='12' y1='10' x2='12' y2='16' stroke='hsl(20deg 20% 90%)' stroke-width='2' stroke-linecap='round'/><line x1='12' y1='7' x2='12' y2='7' stroke='hsl(20deg 20% 90%)' stroke-width='2' stroke-linecap='round'/></svg>");
+  }
+}
+
+@media (hover: hover) {
+  .toc ol li.alert-item.note:hover a::before,
+  .toc ol li.alert-item.note a:hover::before {
+    // fg2-color
+    content: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 24 24'><circle cx='12' cy='12' r='10' fill='none' stroke='hsl(20deg 6% 60%)' stroke-width='2'/><line x1='12' y1='10' x2='12' y2='16' stroke='hsl(20deg 6% 60%)' stroke-width='2' stroke-linecap='round'/><line x1='12' y1='7' x2='12' y2='7' stroke='hsl(20deg 6% 60%)' stroke-width='2' stroke-linecap='round'/></svg>");
+  }
+}
+
+@media (hover: hover) and (prefers-color-scheme: dark) {
+  .toc ol li.alert-item.note:hover a::before,
+  .toc ol li.alert-item.note a:hover::before {
+    // fg2-color
+    content: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 24 24'><circle cx='12' cy='12' r='10' fill='none' stroke='hsl(20deg 6% 55%)' stroke-width='2'/><line x1='12' y1='10' x2='12' y2='16' stroke='hsl(20deg 6% 55%)' stroke-width='2' stroke-linecap='round'/><line x1='12' y1='7' x2='12' y2='7' stroke='hsl(20deg 6% 55%)' stroke-width='2' stroke-linecap='round'/></svg>");
+  }
+}
+
+.toc ol li.label {
+  font-size: var(--font-size-smaller);
+  color: var(--fg2-color);
+}
+
+@media print {
+  .toc {
+    display: none;
+  }
+}

package/src/top/README.md

@@ -0,0 +1,4 @@
+# The `top` component
+
+Show a floating "back to top" button once the page is scrolled more than 250px,
+and keep it visible until the page is back near the top.

package/src/top/index.ts

@@ -0,0 +1,75 @@
+import { debounce, removeClass } from '../util';
+
+/** Show the "Back to top" button once the user is past this scroll position */
+const SHOW_THRESHOLD_PX = 250;
+
+/** Debounce time (maximum amount of time to wait before updates) */
+const LATENCY_MS = 50;
+
+export default (window: Window) => {
+  const mountParent =
+    (window.document.getElementById(
+      'to-top-container',
+    ) as HTMLElement | null) ?? document.body;
+
+  function createLink(parent: HTMLElement): HTMLAnchorElement {
+    const link = window.document.createElement('a');
+    link.href = '#';
+    link.className = 'button';
+    link.tabIndex = -1;
+    link.innerText = 'Back to top';
+    parent.appendChild(link);
+    return link;
+  }
+
+  const link = createLink(mountParent);
+
+  let isShowing = false;
+
+  link.onclick = e => {
+    e.preventDefault();
+    const cleanUrl = window.location.pathname + window.location.search;
+    if (window.location.hash) {
+      history.pushState(null, '', cleanUrl);
+    } else {
+      history.replaceState(null, '', cleanUrl);
+    }
+    window.scrollTo({ top: 0 });
+    const toc = window.document.querySelector('nav.toc') as HTMLElement | null;
+    if (toc) {
+      toc.scrollTop = 0;
+    }
+  };
+
+  function show(link: HTMLAnchorElement) {
+    if (!isShowing) {
+      link.classList.add('is-visible');
+      link.tabIndex = 0;
+    }
+    isShowing = true;
+  }
+
+  function hide(link: HTMLAnchorElement) {
+    if (isShowing) {
+      removeClass(link, 'is-visible');
+      link.tabIndex = -1;
+    }
+    isShowing = false;
+  }
+
+  function updateVisibility() {
+    if (window.scrollY > SHOW_THRESHOLD_PX) {
+      show(link);
+    } else {
+      hide(link);
+    }
+  }
+
+  const debounced = debounce(updateVisibility, LATENCY_MS);
+  window.addEventListener('scroll', debounced, { passive: true });
+  updateVisibility();
+
+  return () => {
+    window.removeEventListener('scroll', debounced);
+  };
+};