@abreen/tada 1.4.1 → 1.5.1

package/src/timezone/index.ts

@@ -84,18 +84,26 @@ function getOffsetMinutes(tz: string, date: Date): number {
   return (utcTs - date.getTime()) / 60000;
 }
 
-// typeof guard prevents ReferenceError when tests import this module
-// without going through the bundler (which substitutes __SITE_TIMEZONES__).
-const TIMEZONES: TimeZone[] =
-  typeof __SITE_TIMEZONES__ !== 'undefined' ? __SITE_TIMEZONES__ : [];
+// Read lazily so tests can set __SITE_TIMEZONES__ before the first call.
+// Cache the result so mutations (like computeOffsets adding offsetMinutes)
+// persist across calls. The bundler inlines __SITE_TIMEZONES__ as a JSON
+// literal, so each raw access would create a fresh array.
+let _timezones: TimeZone[] | null = null;
+function getTimezones(): TimeZone[] {
+  if (_timezones === null) {
+    _timezones =
+      typeof __SITE_TIMEZONES__ !== 'undefined' ? __SITE_TIMEZONES__ : [];
+  }
+  return _timezones;
+}
 
 function getDefaultTimezone() {
   const value = __SITE_DEFAULT_TIMEZONE__;
-  return TIMEZONES.find(tz => tz.value === value)!;
+  return getTimezones().find(tz => tz.value === value)!;
 }
 
 function computeOffsets(baseDate: Date) {
-  TIMEZONES.forEach(tz => {
+  getTimezones().forEach(tz => {
     tz.offsetMinutes = getOffsetMinutes(tz.value, baseDate);
   });
 }
@@ -134,7 +142,7 @@ export default (window: Window) => {
   let initialTz = defaultTz.value;
   try {
     const stored = window.localStorage.getItem(STORAGE_KEY);
-    if (stored && TIMEZONES.some(t => t.value === stored)) {
+    if (stored && getTimezones().some(t => t.value === stored)) {
       initialTz = stored;
     }
   } catch {
@@ -147,66 +155,69 @@ export default (window: Window) => {
 
   // Snapshot the original AM/PM style from each <time> element's text
   const periodStyles = new Map<HTMLTimeElement, PeriodStyle | null>();
-  Array.from(window.document.querySelectorAll('time[datetime]'))
-    .filter((el): el is HTMLTimeElement => el instanceof HTMLTimeElement)
-    .forEach(el => {
-      periodStyles.set(el, detectPeriodStyle(el.textContent ?? ''));
-    });
+  (
+    Array.from(
+      window.document.querySelectorAll('time[datetime]'),
+    ) as HTMLTimeElement[]
+  ).forEach(el => {
+    periodStyles.set(el, detectPeriodStyle(el.textContent ?? ''));
+  });
   const pagePeriodStyle = dominantPeriodStyle(periodStyles);
 
   function updateTimes(targetTz: string) {
-    const target = TIMEZONES.find(t => t.value === targetTz) || defaultTz;
+    const target = getTimezones().find(t => t.value === targetTz) || defaultTz;
     const targetOffset = target.offsetMinutes ?? 0;
     const deltaMinutes = targetOffset - defaultOffset;
 
-    Array.from(window.document.querySelectorAll('time[datetime]'))
-      .filter(el => el instanceof HTMLTimeElement)
-      .forEach(el => {
-        const datetime = el.getAttribute('datetime');
-        if (!datetime) {
-          return;
-        }
+    (
+      Array.from(
+        window.document.querySelectorAll('time[datetime]'),
+      ) as HTMLTimeElement[]
+    ).forEach(el => {
+      const datetime = el.getAttribute('datetime');
+      if (!datetime) {
+        return;
+      }
 
-        const isDefault = target.value === defaultTz.value;
+      const isDefault = target.value === defaultTz.value;
 
-        const baseMinutes = parseHHMM(datetime);
-        if (isNaN(baseMinutes)) {
-          return;
-        }
+      const baseMinutes = parseHHMM(datetime);
+      if (isNaN(baseMinutes)) {
+        return;
+      }
 
-        // raw (can be < 0 or > 1439)
-        const rawMinutes = baseMinutes + deltaMinutes;
-        const dayShift =
-          Math.floor(rawMinutes / 1440) - (rawMinutes < 0 ? 1 : 0);
-        // Normalize after computing dayShift
-        const [h, m] = normalizeHM(rawMinutes);
-
-        let suffix = '';
-        if (!isDefault) {
-          if (dayShift === 1) {
-            suffix = ' <span class="next-prev-day">(next day)</span>';
-          } else if (dayShift === -1) {
-            suffix = ' <span class="next-prev-day">(prev. day)</span>';
-          }
+      // raw (can be < 0 or > 1439)
+      const rawMinutes = baseMinutes + deltaMinutes;
+      const dayShift = Math.floor(rawMinutes / 1440) - (rawMinutes < 0 ? 1 : 0);
+      // Normalize after computing dayShift
+      const [h, m] = normalizeHM(rawMinutes);
+
+      let suffix = '';
+      if (!isDefault) {
+        if (dayShift === 1) {
+          suffix = ' <span class="next-prev-day">(next day)</span>';
+        } else if (dayShift === -1) {
+          suffix = ' <span class="next-prev-day">(prev. day)</span>';
         }
+      }
 
-        const originalStyle = periodStyles.get(el) ?? null;
-        const originalIsPm = Math.floor(baseMinutes / 60) >= 12;
-        const periodChanged = originalIsPm !== h >= 12 || dayShift !== 0;
-        const style =
-          originalStyle === null && periodChanged
-            ? pagePeriodStyle
-            : originalStyle;
-        el.innerHTML = to12Hour(h, m, style) + suffix;
-
-        if (isDefault) {
-          el.classList.remove('is-modified');
-          el.title = '';
-        } else {
-          el.classList.add('is-modified');
-          el.title = `${to12Hour(...normalizeHM(baseMinutes), style ?? pagePeriodStyle)} ${defaultTz.abbreviation}`;
-        }
-      });
+      const originalStyle = periodStyles.get(el) ?? null;
+      const originalIsPm = Math.floor(baseMinutes / 60) >= 12;
+      const periodChanged = originalIsPm !== h >= 12 || dayShift !== 0;
+      const style =
+        originalStyle === null && periodChanged
+          ? pagePeriodStyle
+          : originalStyle;
+      el.innerHTML = to12Hour(h, m, style) + suffix;
+
+      if (isDefault) {
+        el.classList.remove('is-modified');
+        el.title = '';
+      } else {
+        el.classList.add('is-modified');
+        el.title = `${to12Hour(...normalizeHM(baseMinutes), style ?? pagePeriodStyle)} ${defaultTz.abbreviation}`;
+      }
+    });
   }
 
   window.document
@@ -272,6 +283,7 @@ export default (window: Window) => {
       }
       syncAll(defaultTz.value);
       updateTimes(defaultTz.value);
+      selectEl.focus();
     });
   });
 

package/src/toc/index.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, test } from 'bun:test';
+import { JSDOM } from 'jsdom';
+import mount, {
+  getHighlightIndexes,
+  headingToTableItem,
+  alertToTableItem,
+  switchCurrent,
+  type Heading,
+  type Alert,
+  type Dinkus,
+} from './index';
+
+function dom(html: string) {
+  return new JSDOM(`<body>${html}</body>`);
+}
+
+describe('getHighlightIndexes', () => {
+  test('maps headings to their own index', () => {
+    const items: Heading[] = [
+      { level: '1', id: 'a', innerHtml: 'A' },
+      { level: '2', id: 'b', innerHtml: 'B' },
+    ];
+    expect(getHighlightIndexes(items)).toEqual([0, 1]);
+  });
+
+  test('maps alerts to the preceding heading index', () => {
+    const items: (Heading | Alert)[] = [
+      { level: '1', id: 'a', innerHtml: 'A' },
+      { type: 'warning', title: 'Watch out' },
+      { level: '2', id: 'b', innerHtml: 'B' },
+    ];
+    expect(getHighlightIndexes(items)).toEqual([0, 0, 2]);
+  });
+
+  test('alert before any heading gets its own index', () => {
+    const items: (Heading | Alert)[] = [
+      { type: 'note', title: 'FYI' },
+      { level: '1', id: 'a', innerHtml: 'A' },
+    ];
+    expect(getHighlightIndexes(items)).toEqual([0, 1]);
+  });
+
+  test('skips dinkus items entirely', () => {
+    const items: (Heading | Dinkus)[] = [
+      { level: '1', id: 'a', innerHtml: 'A' },
+      { type: 'dinkus' },
+      { level: '2', id: 'b', innerHtml: 'B' },
+    ];
+    expect(getHighlightIndexes(items)).toEqual([0, 1]);
+  });
+
+  test('returns empty array for empty input', () => {
+    expect(getHighlightIndexes([])).toEqual([]);
+  });
+});
+
+describe('headingToTableItem', () => {
+  test('extracts level and innerHTML from a heading', () => {
+    const { document } = dom('<h2 id="intro">Introduction</h2>').window;
+    const el = document.querySelector('h2') as HTMLHeadingElement;
+    const result = headingToTableItem(el);
+    expect(result).toEqual({
+      level: '2',
+      id: 'intro',
+      innerHtml: 'Introduction',
+    });
+  });
+
+  test('separates subtitle from main text', () => {
+    const { document } = dom(
+      '<h3 id="s"><span class="heading-subtitle">v2</span>Setup</h3>',
+    ).window;
+    const el = document.querySelector('h3') as HTMLHeadingElement;
+    const result = headingToTableItem(el);
+    expect(result.level).toBe('3');
+    expect(result.id).toBe('s');
+    expect(result.innerHtml).toContain('Setup');
+    expect(result.innerHtml).toContain('heading-subtitle');
+  });
+
+  test('uses innerHTML when no subtitle', () => {
+    const { document } = dom('<h1 id="top"><em>Bold</em> title</h1>').window;
+    const el = document.querySelector('h1') as HTMLHeadingElement;
+    const result = headingToTableItem(el);
+    expect(result.innerHtml).toBe('<em>Bold</em> title');
+  });
+});
+
+describe('alertToTableItem', () => {
+  test('returns warning alert with custom title', () => {
+    const { document } = dom(
+      '<div class="alert warning"><span class="title">Danger</span></div>',
+    ).window;
+    const el = document.querySelector('.alert') as HTMLElement;
+    expect(alertToTableItem(el)).toEqual({ type: 'warning', title: 'Danger' });
+  });
+
+  test('returns note alert with default title', () => {
+    const { document } = dom('<div class="alert note">Some note</div>').window;
+    const el = document.querySelector('.alert') as HTMLElement;
+    expect(alertToTableItem(el)).toEqual({ type: 'note', title: 'Note' });
+  });
+
+  test('returns default Warning title when no .title element', () => {
+    const { document } = dom(
+      '<div class="alert warning">Text only</div>',
+    ).window;
+    const el = document.querySelector('.alert') as HTMLElement;
+    expect(alertToTableItem(el)).toEqual({ type: 'warning', title: 'Warning' });
+  });
+
+  test('returns null for non-warning/note alert types', () => {
+    const { document } = dom('<div class="alert info">Some info</div>').window;
+    const el = document.querySelector('.alert') as HTMLElement;
+    expect(alertToTableItem(el)).toBeNull();
+  });
+});
+
+describe('switchCurrent', () => {
+  test('adds current class to new element', () => {
+    const { document } = dom('<li>A</li><li>B</li>').window;
+    const items = document.querySelectorAll('li');
+    switchCurrent(null, items[0] as HTMLElement);
+    expect(items[0].classList.contains('current')).toBe(true);
+  });
+
+  test('removes current from old and adds to new', () => {
+    const { document } = dom('<li class="current">A</li><li>B</li>').window;
+    const items = document.querySelectorAll('li');
+    switchCurrent(items[0] as HTMLElement, items[1] as HTMLElement);
+    expect(items[0].classList.contains('current')).toBe(false);
+    expect(items[1].classList.contains('current')).toBe(true);
+  });
+});
+
+describe('toc mount', () => {
+  test('returns early when no nav.toc exists', () => {
+    const win = dom('<div>No toc</div>').window;
+    const cleanup = mount(win);
+    expect(cleanup).toBeUndefined();
+  });
+
+  test('returns early when toc has no links', () => {
+    const win = dom('<nav class="toc"><ol></ol></nav>').window;
+    const cleanup = mount(win);
+    expect(cleanup).toBeUndefined();
+  });
+
+  describe('code page', () => {
+    function createCodePage(hash = '') {
+      const html =
+        '<nav class="toc"><ol>' +
+        '<li><a href="#L1">main</a></li>' +
+        '<li><a href="#L10">helper</a></li>' +
+        '<li><a href="#L20">util</a></li>' +
+        '</ol></nav>' +
+        '<div class="body"></div>';
+      return new JSDOM(`<body class="code">${html}</body>`, {
+        url: `http://localhost/${hash}`,
+      }).window;
+    }
+
+    test('highlights the matching toc entry for the current hash', () => {
+      const win = createCodePage('#L10');
+      mount(win);
+
+      const items = win.document.querySelectorAll('nav.toc ol li');
+      expect(items[1].classList.contains('current')).toBe(true);
+    });
+
+    test('highlights nearest entry when hash is between line ranges', () => {
+      const win = createCodePage('#L15');
+      mount(win);
+
+      const items = win.document.querySelectorAll('nav.toc ol li');
+      expect(items[1].classList.contains('current')).toBe(true);
+    });
+
+    test('parses range hashes like #L5-L10', () => {
+      const win = createCodePage('#L5-L10');
+      mount(win);
+
+      const items = win.document.querySelectorAll('nav.toc ol li');
+      expect(items[0].classList.contains('current')).toBe(true);
+    });
+
+    test('no current item when hash has no line number', () => {
+      const win = createCodePage('');
+      mount(win);
+
+      const current = win.document.querySelector('nav.toc .current');
+      expect(current).toBeNull();
+    });
+
+    test('cleanup removes hashchange listener', () => {
+      const win = createCodePage('#L1');
+      const cleanup = mount(win);
+
+      expect(typeof cleanup).toBe('function');
+      cleanup!();
+    });
+  });
+
+  describe('regular page', () => {
+    function createRegularPage() {
+      const html =
+        '<nav class="toc"><ol>' +
+        '<li><a href="#intro">Introduction</a></li>' +
+        '<li><a href="#setup">Setup</a></li>' +
+        '</ol></nav>' +
+        '<div class="body">' +
+        '<h2 id="intro">Introduction</h2>' +
+        '<p>Content</p>' +
+        '<h2 id="setup">Setup</h2>' +
+        '<p>More content</p>' +
+        '</div>';
+      return new JSDOM(`<body>${html}</body>`, { url: 'http://localhost/' })
+        .window;
+    }
+
+    test('sets a current item on mount', () => {
+      const win = createRegularPage();
+      mount(win);
+
+      const current = win.document.querySelector('nav.toc .current');
+      expect(current).not.toBeNull();
+    });
+
+    test('cleanup removes scroll listener', () => {
+      const win = createRegularPage();
+      const cleanup = mount(win);
+
+      expect(typeof cleanup).toBe('function');
+      cleanup!();
+    });
+  });
+});

package/src/toc/index.ts

@@ -2,12 +2,12 @@ import { debounce } from '../util';
 
 const LATENCY_MS = 50;
 
-type HeadingLevel = '1' | '2' | '3' | '4' | '5' | '6';
-type AlertType = 'warning' | 'note';
+export type HeadingLevel = '1' | '2' | '3' | '4' | '5' | '6';
+export type AlertType = 'warning' | 'note';
 
-type Alert = { type: AlertType; title: string };
-type Heading = { level: HeadingLevel; innerHtml: string; id: string };
-type Dinkus = { type: 'dinkus' };
+export type Alert = { type: AlertType; title: string };
+export type Heading = { level: HeadingLevel; innerHtml: string; id: string };
+export type Dinkus = { type: 'dinkus' };
 
 function getContainer(parent: HTMLElement): HTMLElement | null {
   return parent.querySelector('nav.toc');
@@ -17,8 +17,8 @@ function getCurrentListItem(parent: HTMLElement): HTMLLIElement | null {
   return parent.querySelector('nav.toc .current');
 }
 
-function scrollIfNeeded(element: HTMLElement) {
-  const container = getContainer(document.body);
+function scrollIfNeeded(element: HTMLElement, doc: Document) {
+  const container = getContainer(doc.body as HTMLElement);
   if (container == null) {
     return;
   }
@@ -37,10 +37,10 @@ function scrollIfNeeded(element: HTMLElement) {
     elementRect.height / 2;
   const desiredScrollTop = elementCenter - container.clientHeight / 2;
 
-  container.scrollTop = desiredScrollTop;
+  container.scrollTo({ top: desiredScrollTop, behavior: 'smooth' });
 }
 
-function getHighlightIndexes(items: (Heading | Alert | Dinkus)[]) {
+export function getHighlightIndexes(items: (Heading | Alert | Dinkus)[]) {
   const indexes: (number | null)[] = [];
   let currentHeadingIndex: number | null = null;
   let tocIndex = 0;
@@ -82,8 +82,8 @@ function getTocElements(
 }
 
 /* Calculate how much to offset scroll calculations based on floating header */
-function getHeaderOffset() {
-  const element = document.querySelector('header details summary');
+function getHeaderOffset(doc: Document) {
+  const element = doc.querySelector('header details summary');
   if (!element) {
     return 0;
   }
@@ -91,13 +91,13 @@ function getHeaderOffset() {
   return element.getBoundingClientRect().height;
 }
 
-function getViewportActivationPoint() {
-  const headerOffset = getHeaderOffset();
+function getViewportActivationPoint(win: Window, doc: Document) {
+  const headerOffset = getHeaderOffset(doc);
 
-  return headerOffset + (window.innerHeight - headerOffset) / 3;
+  return headerOffset + (win.innerHeight - headerOffset) / 3;
 }
 
-function headingToTableItem(el: HTMLHeadingElement): Heading {
+export function headingToTableItem(el: HTMLHeadingElement): Heading {
   const level = el.tagName[1] as HeadingLevel;
 
   const subtitle = el.querySelector('.heading-subtitle');
@@ -115,7 +115,7 @@ function headingToTableItem(el: HTMLHeadingElement): Heading {
   return { level, id: el.id, innerHtml: el.innerHTML };
 }
 
-function alertToTableItem(el: HTMLElement): Alert | null {
+export function alertToTableItem(el: HTMLElement): Alert | null {
   const classes = el.className
     .split(' ')
     .map(cl => cl.trim())
@@ -138,7 +138,7 @@ function alertToTableItem(el: HTMLElement): Alert | null {
   return null;
 }
 
-function switchCurrent(
+export function switchCurrent(
   oldCurrent: HTMLElement | null,
   newCurrent: HTMLElement,
 ) {
@@ -148,50 +148,6 @@ function switchCurrent(
   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) {
@@ -227,7 +183,9 @@ export default (window: Window) => {
 
     const updateFromHash = () => {
       const line = parseHash(window.location.hash);
-      const existingItem = getCurrentListItem(document.body);
+      const existingItem = getCurrentListItem(
+        window.document.body as HTMLElement,
+      );
 
       if (line == null) {
         if (existingItem) {
@@ -248,7 +206,7 @@ export default (window: Window) => {
       const nextItem = elements[best]?.parentElement ?? null;
       if (nextItem != null && nextItem !== existingItem) {
         switchCurrent(existingItem, nextItem);
-        scrollIfNeeded(nextItem);
+        scrollIfNeeded(nextItem, window.document);
       }
     };
 
@@ -284,11 +242,11 @@ export default (window: Window) => {
 
   const highlightIndexes = getHighlightIndexes(items);
 
-  // Wire up click handlers for alert items
-  wireAlertClickHandlers(toc, headingsAndAlerts, items);
-
   function handleScroll() {
-    const viewportActivationPoint = getViewportActivationPoint();
+    const viewportActivationPoint = getViewportActivationPoint(
+      window,
+      window.document,
+    );
 
     let i = 0;
     for (let idx = 0; idx < headingsAndAlerts.length; idx++) {
@@ -300,14 +258,16 @@ export default (window: Window) => {
       }
     }
 
-    const existingItem = getCurrentListItem(document.body);
+    const existingItem = getCurrentListItem(
+      window.document.body as HTMLElement,
+    );
     const highlightIndex = highlightIndexes[i];
     const nextItem =
       highlightIndex == null ? null : elements[highlightIndex]?.parentElement;
 
     if (nextItem != null && nextItem !== existingItem) {
       switchCurrent(existingItem, nextItem);
-      scrollIfNeeded(nextItem);
+      scrollIfNeeded(nextItem, window.document);
     }
   }
   const debounced = debounce(handleScroll, LATENCY_MS);

package/src/toc/style.scss

@@ -127,6 +127,23 @@ body.code .toc ol a {
   position: relative;
 }
 
+// Preload hover icon variants so the browser decodes them before first hover
+.toc ol li.alert-item.warning::after {
+  content: var(--icon-warning-sm-hover);
+  position: absolute;
+  width: 0;
+  height: 0;
+  overflow: hidden;
+}
+
+.toc ol li.alert-item.note::after {
+  content: var(--icon-note-sm-hover);
+  position: absolute;
+  width: 0;
+  height: 0;
+  overflow: hidden;
+}
+
 .toc ol li.alert-item.warning a::before,
 .toc ol li.alert-item.note a::before {
   display: inline-block;

package/src/top/index.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from 'bun:test';
+import { JSDOM } from 'jsdom';
+import mount from './index';
+
+function create(html = '') {
+  const dom = new JSDOM(`<body>${html}</body>`, { url: 'http://localhost/' });
+  return dom.window;
+}
+
+describe('top', () => {
+  test('creates a back-to-top link in the body', () => {
+    const win = create();
+    mount(win);
+
+    const link = win.document.querySelector('a.button');
+    expect(link).not.toBeNull();
+    expect(link!.getAttribute('href')).toBe('#');
+  });
+
+  test('mounts link inside #to-top-container when present', () => {
+    const win = create('<div id="to-top-container"></div>');
+    mount(win);
+
+    const container = win.document.getElementById('to-top-container')!;
+    const link = container.querySelector('a.button');
+    expect(link).not.toBeNull();
+  });
+
+  test('link starts hidden (no is-visible class)', () => {
+    const win = create();
+    mount(win);
+
+    const link = win.document.querySelector('a.button')!;
+    expect(link.classList.contains('is-visible')).toBe(false);
+    expect(link.getAttribute('tabindex')).toBe('-1');
+  });
+
+  test('cleanup removes scroll listener', () => {
+    const win = create();
+    const cleanup = mount(win);
+
+    expect(typeof cleanup).toBe('function');
+    // Should not throw
+    cleanup!();
+  });
+});