@abreen/tada 1.9.0 → 1.10.1

package/src/navigate/runtime.ts

@@ -0,0 +1,341 @@
+import { mountPerPageComponents, teardownPerPageComponents } from './lifecycle';
+
+export const NAVIGATION_EVENT = 'tada:navigation';
+
+let currentAbortController: AbortController | null = null;
+let historyIndex = 0;
+let currentPath = '';
+
+const scrollByIndex = new Map<number, number>();
+const scrollByLocation = new Map<string, number>();
+
+type Direction = 'forward' | 'back';
+
+interface NavigationOptions {
+  url: string;
+  scrollTarget: number | string | null;
+  direction: Direction;
+  pushHistory: boolean;
+  useViewTransition?: boolean;
+}
+
+function updateHead(document: Document, newDoc: Document): void {
+  document.title = newDoc.title;
+
+  const metaTags = ['description', 'author'];
+  for (const name of metaTags) {
+    const newMeta = newDoc.querySelector(`meta[name="${name}"]`);
+    const oldMeta = document.querySelector(`meta[name="${name}"]`);
+    if (newMeta && oldMeta) {
+      oldMeta.setAttribute('content', newMeta.getAttribute('content') ?? '');
+    } else if (newMeta && !oldMeta) {
+      document.head.appendChild(newMeta.cloneNode(true));
+    } else if (!newMeta && oldMeta) {
+      oldMeta.remove();
+    }
+  }
+
+  const ogTags = ['og:title', 'og:author'];
+  for (const prop of ogTags) {
+    const newMeta = newDoc.querySelector(`meta[property="${prop}"]`);
+    const oldMeta = document.querySelector(`meta[property="${prop}"]`);
+    if (newMeta && oldMeta) {
+      oldMeta.setAttribute('content', newMeta.getAttribute('content') ?? '');
+    } else if (newMeta && !oldMeta) {
+      document.head.appendChild(newMeta.cloneNode(true));
+    } else if (!newMeta && oldMeta) {
+      oldMeta.remove();
+    }
+  }
+
+  const existingHrefs = new Set(
+    Array.from(document.querySelectorAll('link[rel="stylesheet"]')).map(link =>
+      link.getAttribute('href'),
+    ),
+  );
+
+  for (const link of newDoc.querySelectorAll('link[rel="stylesheet"]')) {
+    if (!existingHrefs.has(link.getAttribute('href'))) {
+      document.head.appendChild(link.cloneNode(true));
+    }
+  }
+}
+
+function swapContent(document: Document, newDoc: Document): void {
+  const newContainer = newDoc.querySelector('.container');
+  const oldContainer = document.querySelector('.container');
+  if (newContainer && oldContainer) {
+    const imported = document.importNode(newContainer, true);
+    oldContainer.replaceChildren(...imported.childNodes);
+  }
+
+  document.body.className = newDoc.body.className;
+}
+
+export function clearSearch(document: Document): void {
+  const input = document.querySelector(
+    'input.search.quick-search',
+  ) as HTMLInputElement | null;
+  if (input && input.value) {
+    const EventCtor = document.defaultView?.Event ?? Event;
+    input.value = '';
+    input.dispatchEvent(new EventCtor('input', { bubbles: true }));
+  }
+}
+
+export function closeHeaderDetails(document: Document): void {
+  const details = document.querySelector(
+    'header details',
+  ) as HTMLDetailsElement | null;
+  if (details?.open) {
+    details.open = false;
+  }
+}
+
+function dispatchNavigationEvent(window: Window): void {
+  const CustomEventCtor = (
+    window as unknown as { CustomEvent: typeof CustomEvent }
+  ).CustomEvent;
+  window.dispatchEvent(
+    new CustomEventCtor(NAVIGATION_EVENT, { detail: { path: currentPath } }),
+  );
+}
+
+function cleanupViewTransitionNames(document: Document): void {
+  const newH1 = document.querySelector(
+    '.title-and-info h1',
+  ) as HTMLElement | null;
+  const newInfo = document.querySelector(
+    '.title-and-info .info',
+  ) as HTMLElement | null;
+  const newBreadcrumb = document.querySelector(
+    '.title-and-info a.breadcrumb',
+  ) as HTMLElement | null;
+
+  if (newH1) {
+    newH1.style.viewTransitionName = '';
+  }
+  if (newInfo) {
+    newInfo.style.viewTransitionName = '';
+  }
+  if (newBreadcrumb) {
+    newBreadcrumb.style.viewTransitionName = '';
+  }
+}
+
+function getLocationKey(window: Window): string {
+  return (
+    window.location.pathname + window.location.search + window.location.hash
+  );
+}
+
+export function initNavigation(window: Window): void {
+  currentAbortController = null;
+  historyIndex = 0;
+  scrollByIndex.clear();
+  scrollByLocation.clear();
+  window.history.scrollRestoration = 'manual';
+  currentPath = window.location.pathname + window.location.search;
+  scrollByIndex.set(historyIndex, window.scrollY);
+  scrollByLocation.set(getLocationKey(window), window.scrollY);
+}
+
+export function saveScrollPosition(window: Window): void {
+  scrollByIndex.set(historyIndex, window.scrollY);
+  scrollByLocation.set(getLocationKey(window), window.scrollY);
+}
+
+export function getCurrentPath(): string {
+  return currentPath;
+}
+
+export function setCurrentPath(path: string): void {
+  currentPath = path;
+}
+
+export function getHistoryIndex(): number {
+  return historyIndex;
+}
+
+export function setHistoryIndex(index: number): void {
+  historyIndex = index;
+}
+
+export function getSavedScroll(index: number): number | undefined {
+  return scrollByIndex.get(index);
+}
+
+export function getSavedLocationScroll(
+  locationKey: string,
+): number | undefined {
+  return scrollByLocation.get(locationKey);
+}
+
+export async function navigateToUrl(
+  window: Window,
+  options: NavigationOptions,
+): Promise<void> {
+  const { document } = window;
+  const {
+    url,
+    scrollTarget,
+    direction,
+    pushHistory,
+    useViewTransition = true,
+  } = options;
+
+  if (currentAbortController) {
+    currentAbortController.abort();
+  }
+
+  const controller = new AbortController();
+  currentAbortController = controller;
+
+  const header = document.querySelector('header');
+  header?.classList.add('loading');
+
+  let response: Response;
+  try {
+    response = await fetch(url, { signal: controller.signal });
+  } catch (err: unknown) {
+    header?.classList.remove('loading');
+    if (err instanceof Error && err.name === 'AbortError') {
+      return;
+    }
+    window.location.href = url;
+    return;
+  }
+
+  if (!response.ok) {
+    header?.classList.remove('loading');
+    window.location.href = url;
+    return;
+  }
+
+  const html = await response.text();
+  header?.classList.remove('loading');
+
+  const DOMParserCtor = (window as unknown as { DOMParser: typeof DOMParser })
+    .DOMParser;
+  const parser = new DOMParserCtor();
+  const newDoc = parser.parseFromString(html, 'text/html');
+  if (!newDoc.querySelector('meta[name="generator"][content="Tada"]')) {
+    window.location.href = url;
+    return;
+  }
+
+  const parsed = new URL(url);
+
+  const doSwap = () => {
+    teardownPerPageComponents();
+    swapContent(document, newDoc);
+    updateHead(document, newDoc);
+    currentPath = parsed.pathname + parsed.search;
+
+    if (pushHistory) {
+      historyIndex++;
+      const urlWithoutHash = parsed.origin + parsed.pathname + parsed.search;
+      window.history.pushState({ navIndex: historyIndex }, '', urlWithoutHash);
+    }
+
+    if (typeof scrollTarget === 'string') {
+      const urlWithHash = parsed.pathname + parsed.search + '#' + scrollTarget;
+      window.location.replace(urlWithHash);
+      window.history.replaceState({ navIndex: historyIndex }, '', urlWithHash);
+    } else if (typeof scrollTarget === 'number') {
+      window.scrollTo({ top: scrollTarget });
+    } else {
+      window.scrollTo({ top: 0 });
+    }
+
+    scrollByIndex.set(historyIndex, window.scrollY);
+    scrollByLocation.set(getLocationKey(window), window.scrollY);
+  };
+
+  const transitionDoc = document as Document & {
+    startViewTransition?: (cb: () => void) => { finished: Promise<void> };
+  };
+
+  if (
+    useViewTransition &&
+    typeof transitionDoc.startViewTransition === 'function'
+  ) {
+    const titleEl = document.querySelector('.title-and-info');
+    const headerHeight =
+      document.querySelector('header')?.getBoundingClientRect().height ?? 0;
+    const titleVisible =
+      titleEl != null && titleEl.getBoundingClientRect().top >= headerHeight;
+
+    if (titleVisible) {
+      const h1 = titleEl.querySelector('h1') as HTMLElement | null;
+      const info = titleEl.querySelector('.info') as HTMLElement | null;
+      const breadcrumb = titleEl.querySelector(
+        'a.breadcrumb',
+      ) as HTMLElement | null;
+      if (h1) {
+        h1.style.viewTransitionName = 'page-title';
+      }
+      if (info) {
+        info.style.viewTransitionName = 'page-info';
+      }
+      if (breadcrumb) {
+        breadcrumb.style.viewTransitionName = 'page-breadcrumb';
+      }
+    }
+
+    document.documentElement.classList.add(
+      direction === 'forward' ? 'nav-forward' : 'nav-back',
+    );
+
+    const transition = transitionDoc.startViewTransition(() => {
+      doSwap();
+
+      const newTitleEl = document.querySelector('.title-and-info');
+      const newHeaderHeight =
+        document.querySelector('header')?.getBoundingClientRect().height ?? 0;
+      const newTitleVisible =
+        newTitleEl != null &&
+        newTitleEl.getBoundingClientRect().top >= newHeaderHeight;
+
+      if (newTitleVisible && newTitleEl) {
+        const h1 = newTitleEl.querySelector('h1') as HTMLElement | null;
+        const info = newTitleEl.querySelector('.info') as HTMLElement | null;
+        const breadcrumb = newTitleEl.querySelector(
+          'a.breadcrumb',
+        ) as HTMLElement | null;
+        if (h1) {
+          h1.style.viewTransitionName = 'page-title';
+        }
+        if (info) {
+          info.style.viewTransitionName = 'page-info';
+        }
+        if (breadcrumb) {
+          breadcrumb.style.viewTransitionName = 'page-breadcrumb';
+        }
+      }
+    });
+
+    await transition.finished;
+    document.documentElement.classList.remove('nav-forward', 'nav-back');
+    cleanupViewTransitionNames(document);
+  } else {
+    doSwap();
+  }
+
+  await mountPerPageComponents(window);
+  currentAbortController = null;
+  dispatchNavigationEvent(window);
+}
+
+export async function refreshCurrentPage(window: Window): Promise<void> {
+  clearSearch(window.document);
+  closeHeaderDetails(window.document);
+  saveScrollPosition(window);
+  await navigateToUrl(window, {
+    url: window.location.href,
+    scrollTarget: window.scrollY,
+    direction: 'forward',
+    pushHistory: false,
+    useViewTransition: false,
+  });
+}

package/src/page-update/README.md

@@ -0,0 +1,4 @@
+# The `page-update` component
+
+Show a floating toast when the current page has a newer `ETag` or
+`Last-Modified` value on the server and let the user refresh the page in place.

package/src/page-update/index.ts

@@ -0,0 +1,280 @@
+import {
+  EMPTY_RESPONSE_VALIDATORS,
+  getPreferredValidatorKey,
+  getResponseValidators,
+  hasResponseValidatorsChanged,
+  hasUsableResponseValidators,
+  type ResponseValidators,
+} from '../validators';
+import { NAVIGATION_EVENT, refreshCurrentPage } from '../navigate/runtime';
+
+const POLL_INTERVAL_MS = 60_000;
+
+export interface PageUpdateOptions {
+  pollIntervalMs?: number;
+  refreshPage?: (window: Window) => Promise<void>;
+}
+
+function createToast(document: Document): {
+  container: HTMLDivElement;
+  toast: HTMLDivElement;
+  reloadButton: HTMLButtonElement;
+  dismissButton: HTMLButtonElement;
+} {
+  const container = document.createElement('div');
+  container.className = 'page-update-container';
+
+  const toast = document.createElement('div');
+  toast.className = 'page-update-toast';
+  toast.setAttribute('role', 'status');
+  toast.setAttribute('aria-live', 'polite');
+
+  const body = document.createElement('div');
+  body.className = 'page-update-body';
+
+  const message = document.createElement('div');
+  message.className = 'page-update-message';
+  message.textContent = 'A newer version of this page is available.';
+
+  const actions = document.createElement('div');
+  actions.className = 'page-update-actions';
+
+  const reloadButton = document.createElement('button');
+  reloadButton.type = 'button';
+  reloadButton.textContent = 'Reload';
+
+  const dismissButton = document.createElement('button');
+  dismissButton.type = 'button';
+  dismissButton.textContent = 'Dismiss';
+
+  actions.append(reloadButton, dismissButton);
+  body.append(message, actions);
+  toast.appendChild(body);
+  container.appendChild(toast);
+  document.body.appendChild(container);
+
+  return { container, toast, reloadButton, dismissButton };
+}
+
+export function mountPageUpdate(
+  window: Window,
+  options: PageUpdateOptions = {},
+): (() => void) | undefined {
+  const { document } = window;
+  if (!document.body) {
+    return;
+  }
+
+  const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
+  const refreshPage = options.refreshPage ?? refreshCurrentPage;
+  const { container, toast, reloadButton, dismissButton } =
+    createToast(document);
+
+  let currentPath = window.location.pathname;
+  let baseline = EMPTY_RESPONSE_VALIDATORS;
+  let dismissedValidatorKey: string | null = null;
+  let nextValidator: ResponseValidators | null = null;
+  let hasBaseline = false;
+  let timer: number | null = null;
+  let checkInFlight = false;
+  let rerunAfterCurrentCheck = false;
+
+  function hideToast() {
+    toast.classList.remove('is-showing');
+  }
+
+  function showToast() {
+    toast.classList.add('is-showing');
+  }
+
+  function clearTimer() {
+    if (timer !== null) {
+      window.clearTimeout(timer);
+      timer = null;
+    }
+  }
+
+  function scheduleNextCheck() {
+    clearTimer();
+    if (document.hidden) {
+      return;
+    }
+    timer = window.setTimeout(() => {
+      void checkForUpdate();
+    }, pollIntervalMs);
+  }
+
+  async function fetchValidators(
+    path: string,
+  ): Promise<ResponseValidators | null> {
+    if (typeof __IS_DEV__ !== 'undefined' && __IS_DEV__) {
+      console.log(
+        `[page-update] HEAD ${path} visibility=${document.visibilityState} focus=${document.hasFocus()}`,
+      );
+    }
+
+    const res = await fetch(path, { method: 'HEAD', cache: 'no-cache' });
+
+    if (typeof __IS_DEV__ !== 'undefined' && __IS_DEV__) {
+      console.log(
+        `[page-update] HEAD ${path} -> ${res.status} etag=${res.headers.get('ETag')} last-modified=${res.headers.get('Last-Modified')} visibility=${document.visibilityState} focus=${document.hasFocus()}`,
+      );
+    }
+
+    if (!res.ok) {
+      return null;
+    }
+
+    const validators = getResponseValidators(res);
+    if (!hasUsableResponseValidators(validators)) {
+      return null;
+    }
+
+    return validators;
+  }
+
+  async function checkForUpdate(): Promise<void> {
+    if (checkInFlight) {
+      rerunAfterCurrentCheck = true;
+      return;
+    }
+
+    const requestedPath = currentPath;
+    let shouldRerun = false;
+    checkInFlight = true;
+    try {
+      const validators = await fetchValidators(requestedPath);
+      if (!validators || requestedPath !== currentPath) {
+        return;
+      }
+
+      if (!hasBaseline) {
+        baseline = validators;
+        hasBaseline = true;
+        return;
+      }
+
+      if (!hasResponseValidatorsChanged(baseline, validators)) {
+        return;
+      }
+
+      nextValidator = validators;
+      const validatorKey = getPreferredValidatorKey(validators);
+      if (validatorKey !== null && validatorKey === dismissedValidatorKey) {
+        hideToast();
+        return;
+      }
+
+      showToast();
+    } catch {
+      // best-effort
+    } finally {
+      checkInFlight = false;
+      if (rerunAfterCurrentCheck && !document.hidden) {
+        rerunAfterCurrentCheck = false;
+        shouldRerun = true;
+      } else {
+        scheduleNextCheck();
+      }
+    }
+
+    if (shouldRerun) {
+      void checkForUpdate();
+    }
+  }
+
+  function resetState() {
+    currentPath = window.location.pathname;
+    baseline = EMPTY_RESPONSE_VALIDATORS;
+    dismissedValidatorKey = null;
+    nextValidator = null;
+    hasBaseline = false;
+    hideToast();
+    clearTimer();
+    if (!document.hidden) {
+      void checkForUpdate();
+    }
+  }
+
+  function handleVisibilityChange() {
+    if (typeof __IS_DEV__ !== 'undefined' && __IS_DEV__) {
+      console.log(
+        `[page-update] visibilitychange hidden=${document.hidden} visibility=${document.visibilityState} focus=${document.hasFocus()}`,
+      );
+    }
+
+    clearTimer();
+    if (document.hidden) {
+      return;
+    }
+
+    void checkForUpdate();
+  }
+
+  function handleNavigation() {
+    if (typeof __IS_DEV__ !== 'undefined' && __IS_DEV__) {
+      console.log(
+        `[page-update] navigation path=${window.location.pathname} visibility=${document.visibilityState} focus=${document.hasFocus()}`,
+      );
+    }
+    resetState();
+  }
+
+  function handleDismiss() {
+    dismissedValidatorKey =
+      nextValidator === null ? null : getPreferredValidatorKey(nextValidator);
+    hideToast();
+  }
+
+  function handleWindowFocus() {
+    if (typeof __IS_DEV__ !== 'undefined' && __IS_DEV__) {
+      console.log(
+        `[page-update] window focus visibility=${document.visibilityState} focus=${document.hasFocus()}`,
+      );
+    }
+  }
+
+  function handleWindowBlur() {
+    if (typeof __IS_DEV__ !== 'undefined' && __IS_DEV__) {
+      console.log(
+        `[page-update] window blur visibility=${document.visibilityState} focus=${document.hasFocus()}`,
+      );
+    }
+  }
+
+  function handleReloadClick() {
+    void refreshPage(window);
+  }
+
+  reloadButton.addEventListener('click', handleReloadClick);
+  dismissButton.addEventListener('click', handleDismiss);
+  document.addEventListener('visibilitychange', handleVisibilityChange);
+  window.addEventListener('focus', handleWindowFocus);
+  window.addEventListener('blur', handleWindowBlur);
+  window.addEventListener(NAVIGATION_EVENT, handleNavigation);
+
+  if (!document.hidden) {
+    if (typeof __IS_DEV__ !== 'undefined' && __IS_DEV__) {
+      console.log(
+        `[page-update] mount path=${currentPath} interval=${pollIntervalMs} visibility=${document.visibilityState} focus=${document.hasFocus()}`,
+      );
+    }
+
+    void checkForUpdate();
+  }
+
+  return () => {
+    clearTimer();
+    document.removeEventListener('visibilitychange', handleVisibilityChange);
+    window.removeEventListener('focus', handleWindowFocus);
+    window.removeEventListener('blur', handleWindowBlur);
+    window.removeEventListener(NAVIGATION_EVENT, handleNavigation);
+    dismissButton.removeEventListener('click', handleDismiss);
+    reloadButton.removeEventListener('click', handleReloadClick);
+    container.remove();
+  };
+}
+
+export default function mount(window: Window): (() => void) | undefined {
+  return mountPageUpdate(window);
+}

package/src/page-update/style.scss

@@ -0,0 +1,53 @@
+.page-update-container {
+  position: fixed;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  z-index: 1000;
+  display: flex;
+  justify-content: center;
+  padding: 1rem;
+  pointer-events: none;
+}
+
+.page-update-toast {
+  display: none;
+  width: min(100%, 640px);
+  overflow: hidden;
+  color: var(--fg-color);
+  pointer-events: auto;
+  background: var(--bg-color);
+  border: var(--control-border-width) solid var(--fg2-color);
+  border-radius: var(--border-radius);
+  box-shadow: var(--box-shadow);
+
+  &.is-showing {
+    display: block;
+  }
+
+  .page-update-body {
+    display: flex;
+    gap: var(--gap);
+    align-items: center;
+    justify-content: space-between;
+    padding: var(--gap);
+
+    @media (width <= 580px) {
+      flex-direction: column;
+      align-items: stretch;
+    }
+  }
+
+  .page-update-message {
+    min-width: 0;
+    font-size: var(--font-size-small);
+  }
+
+  .page-update-actions {
+    display: flex;
+    flex: 0 0 auto;
+    gap: var(--gap);
+    align-items: center;
+    justify-content: space-between;
+  }
+}

package/src/print/style.scss

@@ -3,8 +3,8 @@
 @media print {
   html,
   body {
-    background: none !important;
     color: #000;
+    background: none !important;
   }
 
   hr {
@@ -25,7 +25,7 @@
     margin-top: 0;
   }
 
-  main a:not(.heading-anchor):not(.footnote-ref):not(.line-number) {
+  main a:not(.heading-anchor, .footnote-ref, .line-number) {
     @include link-underline;
   }
 
@@ -76,10 +76,10 @@
   }
 
   section {
-    border: none;
+    width: 100%;
     padding: 0;
     margin: 0;
-    width: 100%;
+    border: none;
   }
 
   a.heading-anchor::after {