@abreen/tada 1.4.1 → 1.5.0

package/src/navigate/index.ts

@@ -0,0 +1,365 @@
+import { isEligibleLink } from './eligible';
+import { mountPerPageComponents, teardownPerPageComponents } from './lifecycle';
+
+let currentAbortController: AbortController | null = null;
+let historyIndex = 0;
+let currentPath = '';
+
+type Direction = 'forward' | 'back';
+
+function findAnchor(event: MouseEvent): HTMLAnchorElement | null {
+  const target = event.target as HTMLElement | null;
+  return target?.closest('a[href]') ?? null;
+}
+
+function shouldIgnoreClick(
+  event: MouseEvent,
+  anchor: HTMLAnchorElement,
+): boolean {
+  if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) {
+    return true;
+  }
+
+  if (anchor.target) {
+    return true;
+  }
+
+  const href = anchor.href;
+  if (!href) {
+    return true;
+  }
+
+  return false;
+}
+
+function updateHead(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();
+    }
+  }
+
+  // Adopt stylesheet links from the new page that aren't already loaded
+  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(newDoc: Document): void {
+  const newContainer = newDoc.querySelector('.container');
+  const oldContainer = document.querySelector('.container');
+  if (newContainer && oldContainer) {
+    oldContainer.replaceChildren(...newContainer.childNodes);
+  }
+
+  // Update body class (carries template name and toc-is-active)
+  document.body.className = newDoc.body.className;
+}
+
+function clearSearch(): void {
+  const input = document.querySelector(
+    'input.search.quick-search',
+  ) as HTMLInputElement | null;
+  if (input && input.value) {
+    input.value = '';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+  }
+}
+
+async function performNavigation(
+  url: string,
+  scrollTarget: number | string | null,
+  direction: Direction,
+  isPush: boolean,
+): Promise<void> {
+  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;
+    }
+    // Fetch failed, fall back to full navigation
+    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 parser = new DOMParser();
+  const newDoc = parser.parseFromString(html, 'text/html');
+
+  if (!newDoc.querySelector('meta[name="generator"][content="Tada"]')) {
+    window.location.href = url;
+    return;
+  }
+
+  const doSwap = () => {
+    teardownPerPageComponents();
+    swapContent(newDoc);
+    updateHead(newDoc);
+    if (isPush) {
+      historyIndex++;
+      history.pushState({ navIndex: historyIndex }, '', url);
+    }
+    const parsed = new URL(url);
+    currentPath = parsed.pathname + parsed.search;
+
+    if (typeof scrollTarget === 'string') {
+      // Hash target
+      const el = document.getElementById(scrollTarget);
+      if (el) {
+        el.scrollIntoView();
+      } else {
+        window.scrollTo({ top: 0 });
+      }
+    } else if (typeof scrollTarget === 'number') {
+      // Restore scroll position (popstate)
+      window.scrollTo({ top: scrollTarget });
+    } else {
+      window.scrollTo({ top: 0 });
+    }
+  };
+
+  const doc = document as Document & {
+    startViewTransition?: (cb: () => void) => { finished: Promise<void> };
+  };
+
+  if (typeof doc.startViewTransition === 'function') {
+    // Only give the title its own transition group if it's visible
+    const titleEl = document.querySelector('.title-and-info');
+    const headerHeight =
+      document.querySelector('header')?.getBoundingClientRect().height ?? 0;
+    const titleVisible =
+      titleEl != null && titleEl.getBoundingClientRect().bottom >= 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 = doc.startViewTransition(() => {
+      doSwap();
+      // Apply transition names to the new title if the old one was visible
+      if (titleVisible) {
+        const newTitleEl = document.querySelector('.title-and-info');
+        if (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');
+    // Clean up inline styles
+    const newH1 = document.querySelector(
+      '.title-and-info h1',
+    ) as HTMLElement | null;
+    const newInfo = document.querySelector(
+      '.title-and-info .info',
+    ) as HTMLElement | null;
+    if (newH1) {
+      newH1.style.viewTransitionName = '';
+    }
+    if (newInfo) {
+      newInfo.style.viewTransitionName = '';
+    }
+    const newBreadcrumb = document.querySelector(
+      '.title-and-info a.breadcrumb',
+    ) as HTMLElement | null;
+    if (newBreadcrumb) {
+      newBreadcrumb.style.viewTransitionName = '';
+    }
+  } else {
+    doSwap();
+  }
+
+  await mountPerPageComponents(window);
+  currentAbortController = null;
+}
+
+export default function mountNavigate(window: Window): () => void {
+  window.history.scrollRestoration = 'manual';
+  currentPath = window.location.pathname + window.location.search;
+
+  function handleClick(event: MouseEvent) {
+    const anchor = findAnchor(event);
+    if (!anchor) {
+      return;
+    }
+
+    if (shouldIgnoreClick(event, anchor)) {
+      return;
+    }
+
+    if (
+      !isEligibleLink(anchor.href, window.location.origin, __SITE_BASE_PATH__)
+    ) {
+      return;
+    }
+
+    // Same-page hash links: smooth scroll instead of letting the browser jump
+    const url = new URL(anchor.href);
+    if (
+      url.pathname === window.location.pathname &&
+      url.search === window.location.search
+    ) {
+      event.preventDefault();
+      clearSearch();
+      const details = window.document.querySelector(
+        'header details',
+      ) as HTMLDetailsElement | null;
+      if (details?.open) {
+        details.open = false;
+      }
+      if (url.hash) {
+        window.history.pushState(null, '', url.hash);
+        const el = window.document.getElementById(url.hash.slice(1));
+        if (el) {
+          el.scrollIntoView({ behavior: 'smooth' });
+        }
+      }
+      return;
+    }
+
+    event.preventDefault();
+
+    // Clear search and close header immediately, before the fetch
+    clearSearch();
+
+    const details = window.document.querySelector(
+      'header details',
+    ) as HTMLDetailsElement | null;
+    if (details?.open) {
+      details.open = false;
+    }
+
+    // Save current scroll position and history index
+    window.history.replaceState(
+      {
+        ...window.history.state,
+        scrollY: window.scrollY,
+        navIndex: historyIndex,
+      },
+      '',
+    );
+
+    const hash = url.hash ? url.hash.slice(1) : null;
+
+    performNavigation(anchor.href, hash, 'forward', true);
+  }
+
+  function handlePopState(event: PopStateEvent) {
+    const newPath = window.location.pathname + window.location.search;
+    if (newPath === currentPath) {
+      // Same page, different hash: scroll to the target
+      const hash = window.location.hash.slice(1);
+      if (hash) {
+        const el = window.document.getElementById(hash);
+        if (el) {
+          el.scrollIntoView({ behavior: 'smooth' });
+        }
+      } else {
+        window.scrollTo({ top: 0, behavior: 'smooth' });
+      }
+      return;
+    }
+    currentPath = newPath;
+
+    const scrollY = event.state?.scrollY ?? null;
+    const targetIndex = event.state?.navIndex ?? 0;
+    const direction: Direction =
+      targetIndex >= historyIndex ? 'forward' : 'back';
+    historyIndex = targetIndex;
+    performNavigation(
+      window.location.href,
+      typeof scrollY === 'number' ? scrollY : null,
+      direction,
+      false,
+    );
+  }
+
+  // Use capture phase so the handler fires before stopPropagation
+  // in the header component can block the event from reaching us
+  window.document.addEventListener('click', handleClick, true);
+  window.addEventListener('popstate', handlePopState);
+
+  return () => {
+    window.document.removeEventListener('click', handleClick, true);
+    window.removeEventListener('popstate', handlePopState);
+  };
+}

package/src/navigate/lifecycle.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from 'bun:test';
+import { JSDOM } from 'jsdom';
+
+describe('component lifecycle', () => {
+  test('mountPerPageComponents returns a teardown function', async () => {
+    const dom = new JSDOM(
+      `<body><header><details><summary>Menu</summary><nav></nav></details></header><div class="container"></div></body>`,
+      { url: 'http://localhost/' },
+    );
+
+    const { mountPerPageComponents } = await import('./lifecycle');
+    const teardown = await mountPerPageComponents(dom.window);
+    expect(typeof teardown).toBe('function');
+  });
+
+  test('teardown calls all per-page cleanup functions', async () => {
+    const dom = new JSDOM(
+      `<body><header><details><summary>Menu</summary><nav></nav></details></header><div class="container"></div></body>`,
+      { url: 'http://localhost/' },
+    );
+
+    const { mountPerPageComponents } = await import('./lifecycle');
+    const teardown = await mountPerPageComponents(dom.window);
+    teardown();
+  });
+});

package/src/navigate/lifecycle.ts

@@ -0,0 +1,65 @@
+import mountTableOfContents from '../toc';
+import mountAnchor from '../anchor';
+import mountQuestion from '../question';
+import mountTimeZone from '../timezone';
+import mountCode from '../code';
+import mountTrace from '../trace';
+import mountPrint from '../print';
+import { scheduleTask } from '../util';
+
+const PER_PAGE_COMPONENTS: Record<
+  string,
+  (w: Window) => void | (() => void) | Promise<void>
+> = {
+  toc: mountTableOfContents,
+  anchor: mountAnchor,
+  question: mountQuestion,
+  timeZone: mountTimeZone,
+  code: mountCode,
+  trace: mountTrace,
+  print: mountPrint,
+};
+
+let cleanups: (() => void)[] = [];
+
+export async function mountPerPageComponents(
+  window: Window,
+): Promise<() => void> {
+  cleanups = [];
+
+  const entries = Object.entries(PER_PAGE_COMPONENTS);
+
+  const mountPromises = entries.map(([name, mount]) => {
+    return new Promise<void>((resolve, reject) => {
+      scheduleTask(async () => {
+        try {
+          const cleanup = await mount(window);
+          if (typeof cleanup === 'function') {
+            cleanups.push(cleanup);
+          }
+          resolve();
+        } catch (err) {
+          if (__IS_DEV__) {
+            console.error(`Failed to mount ${name} component:`, String(err));
+          }
+          reject();
+        }
+      });
+    });
+  });
+
+  await Promise.allSettled(mountPromises);
+
+  return teardownPerPageComponents;
+}
+
+export function teardownPerPageComponents(): void {
+  for (const cleanup of cleanups) {
+    try {
+      cleanup();
+    } catch {
+      // ignore teardown errors
+    }
+  }
+  cleanups = [];
+}

package/src/navigate/style.scss

@@ -0,0 +1,61 @@
+$shift: 40px;
+$duration: 200ms;
+
+@keyframes slide-out-left {
+  to {
+    opacity: 0;
+    transform: translateX(-$shift);
+  }
+}
+
+@keyframes slide-in-right {
+  from {
+    opacity: 0;
+    transform: translateX($shift);
+  }
+}
+
+@keyframes slide-out-right {
+  to {
+    opacity: 0;
+    transform: translateX($shift);
+  }
+}
+
+@keyframes slide-in-left {
+  from {
+    opacity: 0;
+    transform: translateX(-$shift);
+  }
+}
+
+// Page heading and info: crossfade in place instead of sliding with the page
+// view-transition-name is set via inline style by the navigator
+// only when .title-and-info is visible in the viewport
+
+::view-transition-old(page-title),
+::view-transition-new(page-title),
+::view-transition-old(page-info),
+::view-transition-new(page-info),
+::view-transition-old(page-breadcrumb),
+::view-transition-new(page-breadcrumb) {
+  animation-duration: $duration;
+}
+
+// Forward navigation: old content slides left, new content slides in from right
+.nav-forward::view-transition-old(root) {
+  animation: slide-out-left $duration ease-in;
+}
+
+.nav-forward::view-transition-new(root) {
+  animation: slide-in-right $duration ease-out;
+}
+
+// Back navigation: old content slides right, new content slides in from left
+.nav-back::view-transition-old(root) {
+  animation: slide-out-right $duration ease-in;
+}
+
+.nav-back::view-transition-new(root) {
+  animation: slide-in-left $duration ease-out;
+}

package/src/print/index.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from 'bun:test';
+import { JSDOM } from 'jsdom';
+import mount from './index';
+
+function create(html: string) {
+  const dom = new JSDOM(`<body>${html}</body>`);
+  return dom.window;
+}
+
+describe('print', () => {
+  test('opens closed details on beforeprint', () => {
+    const win = create('<details><summary>S</summary>Content</details>');
+    mount(win);
+
+    const details = win.document.querySelector('details')!;
+    expect(details.open).toBe(false);
+
+    win.dispatchEvent(new win.Event('beforeprint'));
+    expect(details.open).toBe(true);
+    expect(details.getAttribute('data-was-closed')).toBe('true');
+  });
+
+  test('restores closed details on afterprint', () => {
+    const win = create('<details><summary>S</summary>Content</details>');
+    mount(win);
+
+    win.dispatchEvent(new win.Event('beforeprint'));
+    win.dispatchEvent(new win.Event('afterprint'));
+
+    const details = win.document.querySelector('details')!;
+    expect(details.open).toBe(false);
+    expect(details.hasAttribute('data-was-closed')).toBe(false);
+  });
+
+  test('leaves already-open details open after print', () => {
+    const win = create('<details open><summary>S</summary>Content</details>');
+    mount(win);
+
+    win.dispatchEvent(new win.Event('beforeprint'));
+    win.dispatchEvent(new win.Event('afterprint'));
+
+    const details = win.document.querySelector('details')!;
+    expect(details.open).toBe(true);
+  });
+
+  test('skips details inside header', () => {
+    const win = create(
+      '<header><details><summary>Nav</summary>Menu</details></header>' +
+        '<details><summary>S</summary>Content</details>',
+    );
+    mount(win);
+
+    win.dispatchEvent(new win.Event('beforeprint'));
+
+    const headerDetails = win.document.querySelector('header details')!;
+    const bodyDetails = win.document.querySelectorAll('details')[1];
+    expect(headerDetails.hasAttribute('data-was-closed')).toBe(false);
+    expect(bodyDetails.open).toBe(true);
+  });
+
+  test('cleanup removes event listeners', () => {
+    const win = create('<details><summary>S</summary>Content</details>');
+    const cleanup = mount(win);
+
+    cleanup!();
+
+    win.dispatchEvent(new win.Event('beforeprint'));
+    const details = win.document.querySelector('details')!;
+    expect(details.open).toBe(false);
+  });
+});

package/src/question/index.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from 'bun:test';
+import { JSDOM } from 'jsdom';
+import mount from './index';
+
+function create(html: string) {
+  const dom = new JSDOM(`<body>${html}</body>`);
+  return dom.window;
+}
+
+describe('question', () => {
+  test('sets ARIA attributes on answer body', () => {
+    const win = create('<div class="question-a-body">Answer</div>');
+    mount(win);
+
+    const el = win.document.querySelector('.question-a-body')!;
+    expect(el.getAttribute('role')).toBe('button');
+    expect(el.getAttribute('tabindex')).toBe('0');
+    expect(el.getAttribute('aria-label')).toBe('Click to reveal answer');
+  });
+
+  test('reveals answer on click', () => {
+    const win = create('<div class="question-a-body">Answer</div>');
+    mount(win);
+
+    const el = win.document.querySelector('.question-a-body')!;
+    el.dispatchEvent(new win.MouseEvent('click', { bubbles: true }));
+
+    expect(el.hasAttribute('data-revealed')).toBe(true);
+    expect(el.hasAttribute('role')).toBe(false);
+    expect(el.hasAttribute('tabindex')).toBe(false);
+    expect(el.hasAttribute('aria-label')).toBe(false);
+  });
+
+  test('reveals answer on Enter key', () => {
+    const win = create('<div class="question-a-body">Answer</div>');
+    mount(win);
+
+    const el = win.document.querySelector('.question-a-body')!;
+    el.dispatchEvent(
+      new win.KeyboardEvent('keydown', { key: 'Enter', bubbles: true }),
+    );
+
+    expect(el.hasAttribute('data-revealed')).toBe(true);
+  });
+
+  test('reveals answer on Space key', () => {
+    const win = create('<div class="question-a-body">Answer</div>');
+    mount(win);
+
+    const el = win.document.querySelector('.question-a-body')!;
+    el.dispatchEvent(
+      new win.KeyboardEvent('keydown', { key: ' ', bubbles: true }),
+    );
+
+    expect(el.hasAttribute('data-revealed')).toBe(true);
+  });
+
+  test('does not reveal on other keys', () => {
+    const win = create('<div class="question-a-body">Answer</div>');
+    mount(win);
+
+    const el = win.document.querySelector('.question-a-body')!;
+    el.dispatchEvent(
+      new win.KeyboardEvent('keydown', { key: 'Tab', bubbles: true }),
+    );
+
+    expect(el.hasAttribute('data-revealed')).toBe(false);
+  });
+
+  test('handles multiple question bodies', () => {
+    const win = create(
+      '<div class="question-a-body">A1</div><div class="question-a-body">A2</div>',
+    );
+    mount(win);
+
+    const els = win.document.querySelectorAll('.question-a-body');
+    expect(els.length).toBe(2);
+    els.forEach(el => {
+      expect(el.getAttribute('role')).toBe('button');
+    });
+  });
+});

package/src/question/style.scss

@@ -35,6 +35,18 @@
   @include user-select(none);
 }
 
+.question-a-body:focus-visible {
+  outline: 2px solid var(--theme-color);
+  outline-offset: -2px;
+}
+
+.question-a-body[data-revealed] {
+  &:focus,
+  &:focus-visible {
+    outline: none;
+  }
+}
+
 .question-a-body > *:first-child {
   margin-top: 0;
 }