@abreen/tada 1.19.1 → 1.19.3

package/build/watch/engine.ts

@@ -22,6 +22,10 @@ export function runWatchEngine<Meta>(
   const debounceMs = options.debounceMs ?? 300;
   const watchers: ReturnType<typeof chokidar.watch>[] = [];
   const pending = new Set<string>();
+  const removed = new Map<
+    string,
+    { watcher: ReturnType<typeof chokidar.watch>; root: string }
+  >();
   let uncommitted = new Set<string>();
   let closed = false;
   let fatal: { error: unknown } | undefined;
@@ -33,6 +37,7 @@ export function runWatchEngine<Meta>(
   function stop(): void {
     closed = true;
     pending.clear();
+    removed.clear();
     if (timer !== undefined) {
       clock.clearTimeout(timer);
     }
@@ -78,6 +83,52 @@ export function runWatchEngine<Meta>(
     }
   }
 
+  function isFile(filePath: string): boolean {
+    try {
+      return dependencies.stat(filePath)?.isFile() ?? false;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOTDIR') {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  function isInside(root: string, filePath: string): boolean {
+    const relative = path.relative(root, filePath);
+    return (
+      relative !== '' &&
+      relative !== '..' &&
+      !relative.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(relative)
+    );
+  }
+
+  /**
+   * Chokidar tracks entries by name, so a directory replaced by a file keeps
+   * its directory subscription and edits to the file are never reported. When
+   * a poll misses the moment between the two, the only events are removals of
+   * what was inside the directory. Once changes have settled, resubscribe any
+   * parent of a removed path that is now a file.
+   */
+  function resubscribeReplacedDirectories(): void {
+    const checked = new Set<string>();
+    for (const [removedPath, { watcher, root }] of removed) {
+      for (
+        let dir = path.dirname(removedPath);
+        isInside(root, dir) && !checked.has(dir);
+        dir = path.dirname(dir)
+      ) {
+        checked.add(dir);
+        if (isFile(dir)) {
+          watcher.unwatch(dir);
+          watcher.add(dir);
+        }
+      }
+    }
+    removed.clear();
+  }
+
   async function emit(event: WatchLifecycleEvent<Meta>): Promise<void> {
     if (!closed) {
       await options.onEvent?.(event);
@@ -139,7 +190,13 @@ export function runWatchEngine<Meta>(
           fail(error);
         }
       };
-      watcher.on('add', included).on('unlink', included);
+      const removedPath = (filePath: string) => {
+        if (!closed) {
+          removed.set(filePath, { watcher, root: target.path });
+        }
+        included(filePath);
+      };
+      watcher.on('add', included).on('unlink', removedPath);
       watcher.on('change', (filePath, stats) => {
         if (closed) {
           return;
@@ -156,20 +213,18 @@ export function runWatchEngine<Meta>(
       });
       watcher.on('addDir', included);
       watcher.on('unlinkDir', filePath => {
-        included(filePath);
+        removedPath(filePath);
         // Wait until Chokidar finishes closing the old directory subscription.
         queueMicrotask(() => {
           if (closed) {
             return;
           }
           try {
-            if (dependencies.stat(filePath)?.isFile()) {
+            if (isFile(filePath)) {
               watcher.add(filePath);
             }
           } catch (error) {
-            if ((error as NodeJS.ErrnoException).code !== 'ENOTDIR') {
-              fail(error);
-            }
+            fail(error);
           }
         });
       });
@@ -197,6 +252,7 @@ export function runWatchEngine<Meta>(
       while (!closed && pending.size) {
         const paths = new Set([...uncommitted, ...pending]);
         pending.clear();
+        resubscribeReplacedDirectories();
         const outcome = await build(paths);
         if (!outcome?.ok) {
           uncommitted = paths;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abreen/tada",
-  "version": "1.19.1",
+  "version": "1.19.3",
   "type": "module",
   "description": "A static site generator",
   "license": "MIT",

package/src/hash-target.ts

@@ -5,6 +5,9 @@
  * Tada also allows raw HTML, so an author can create a decoded ID like
  * <h2 id="hello world">Hello</h2>. A link to that target becomes
  * #hello%20world, and getElementById('hello%20world') would not find it.
+ *
+ * Like the browser, fall back to a legacy <a name="..."> anchor when no
+ * element has the ID.
  */
 export function getHashTarget(
   document: Document,
@@ -15,15 +18,31 @@ export function getHashTarget(
     return null;
   }
 
-  const rawTarget = document.getElementById(id);
+  const rawTarget = findIndicatedElement(document, id);
   if (rawTarget) {
     return rawTarget;
   }
 
   try {
     const decodedId = decodeURIComponent(id);
-    return decodedId === id ? null : document.getElementById(decodedId);
+    return decodedId === id ? null : findIndicatedElement(document, decodedId);
   } catch {
     return null;
   }
 }
+
+function findIndicatedElement(
+  document: Document,
+  fragment: string,
+): HTMLElement | null {
+  const byId = document.getElementById(fragment);
+  if (byId) {
+    return byId;
+  }
+  for (const element of document.getElementsByName(fragment)) {
+    if (element.localName === 'a') {
+      return element;
+    }
+  }
+  return null;
+}

package/src/navigate/_index.scss

@@ -105,12 +105,10 @@ html.navigation-loading * {
   mix-blend-mode: normal;
 }
 
-// The footer and appearance controls get their own stationary layer. Show only
-// the incoming snapshot so disabled defaults and stale hover states cannot blend.
-.page-bottom {
-  view-transition-name: page-bottom;
-}
-
+// The footer and appearance controls get their own layer while they are in the
+// viewport. view-transition-name is set via inline style by the navigator. On
+// screen on both pages, the layer stays put and shows only the incoming
+// snapshot so disabled defaults and stale hover states cannot blend.
 ::view-transition-group(page-bottom),
 ::view-transition-old(page-bottom),
 ::view-transition-new(page-bottom) {
@@ -125,6 +123,19 @@ html.navigation-loading * {
   mix-blend-mode: normal;
 }
 
+// On screen on only one page, such as between a short page and the top of a
+// long page: fade out or in where they are, in step with the page. Fill both
+// ways, like the UA default, so the faded-out snapshot cannot reappear in the
+// transition's last frame.
+::view-transition-old(page-bottom):only-child {
+  display: block;
+  animation: page-fade-out $duration ease-in both;
+}
+
+::view-transition-new(page-bottom):only-child {
+  animation: page-fade-in $duration ease-out both;
+}
+
 // Forward navigation: old content slides left, new content slides in from right
 .nav-forward::view-transition-old(root) {
   animation:

package/src/navigate/index.ts

@@ -1,5 +1,6 @@
 import { isEligibleLink } from './eligible';
 import {
+  applyFragmentTarget,
   clearSearch,
   closeHeaderDetails,
   getCurrentPath,
@@ -7,6 +8,7 @@ import {
   getHistoryIndex,
   getSavedScroll,
   initNavigation,
+  isApplyingFragment,
   navigateToUrl,
   saveScrollPosition,
   setCurrentPath,
@@ -134,6 +136,10 @@ export default function mountNavigate(window: Window): () => void {
   }
 
   function handlePopState(event: PopStateEvent) {
+    if (isApplyingFragment()) {
+      return;
+    }
+
     if (clearingFragment) {
       clearingFragment = false;
       if (!window.location.hash) {
@@ -145,19 +151,24 @@ export default function mountNavigate(window: Window): () => void {
     if (newPath === getCurrentPath()) {
       const locationKey = newPath + window.location.hash;
       const savedY = getSavedLocationScroll(locationKey);
+      // Fragment traversal can update :target and apply its native target
+      // scroll after popstate. Correct both in the next task so the URL and our
+      // saved position win. Capture savedY now because the native scroll event
+      // can update the location map first.
+      window.setTimeout(() => {
+        const currentLocationKey =
+          window.location.pathname +
+          window.location.search +
+          window.location.hash;
+        if (currentLocationKey !== locationKey) {
+          return;
+        }
+        applyFragmentTarget(window);
+        if (typeof savedY === 'number') {
+          window.scrollTo({ top: savedY });
+        }
+      }, 0);
       if (typeof savedY === 'number') {
-        // Fragment traversal can apply its native target scroll after popstate.
-        // Restore in the next task so our saved position wins. Capture savedY
-        // now because the native scroll event can update the location map first.
-        window.setTimeout(() => {
-          const currentLocationKey =
-            window.location.pathname +
-            window.location.search +
-            window.location.hash;
-          if (currentLocationKey === locationKey) {
-            window.scrollTo({ top: savedY });
-          }
-        }, 0);
         return;
       }
 

package/src/navigate/runtime.ts

@@ -5,18 +5,31 @@ import {
   teardownPerPageComponents,
 } from './lifecycle';
 import { globals } from '../globals';
+import { getHashTarget } from '../hash-target';
 import { swapHeaderTitle } from '../header';
 
 export const NAVIGATION_EVENT = 'tada:navigation';
 
 const LOADING_CURSOR_DELAY = 400;
+const HOLD_SCROLL_FRAMES = 6;
+const HOLD_SCROLL_RELEASE_EVENTS = [
+  'wheel',
+  'touchstart',
+  'keydown',
+  'pointerdown',
+] as const;
 
 let currentAbortController: AbortController | null = null;
 let historyIndex = 0;
 let currentPath = '';
+let applyingFragment = false;
+let fragmentTargetRequest = 0;
 
 const scrollByIndex = new Map<number, number>();
 const scrollByLocation = new Map<string, number>();
+// Stylesheets the navigator added that have not loaded or failed yet. Those in
+// the initial document have settled before the deferred client script runs.
+const pendingStylesheets = new Map<Element, Promise<void>>();
 
 type Direction = 'forward' | 'back';
 
@@ -65,7 +78,19 @@ function updateHead(document: Document, newDoc: Document): void {
 
   for (const link of newDoc.querySelectorAll('link[rel="stylesheet"]')) {
     if (!existingHrefs.has(link.getAttribute('href'))) {
-      document.head.appendChild(link.cloneNode(true));
+      const clone = link.cloneNode(true) as Element;
+      pendingStylesheets.set(
+        clone,
+        new Promise(resolve => {
+          const settle = () => {
+            pendingStylesheets.delete(clone);
+            resolve();
+          };
+          clone.addEventListener('load', settle, { once: true });
+          clone.addEventListener('error', settle, { once: true });
+        }),
+      );
+      document.head.appendChild(clone);
     }
   }
 }
@@ -138,11 +163,29 @@ function setTitleTransitionNames(titleEl: Element, enabled: boolean): void {
   }
 }
 
+// The footer and appearance pickers get their own layer only while they are in
+// the viewport, so the layer stays put when they are on screen on both pages
+// and fades on its own when they are on screen on only one.
+function setPageBottomTransitionName(window: Window): void {
+  const bottom = window.document.querySelector<HTMLElement>('.page-bottom');
+  if (!bottom) {
+    return;
+  }
+  const rect = bottom.getBoundingClientRect();
+  if (rect.bottom > 0 && rect.top < window.innerHeight) {
+    bottom.style.viewTransitionName = 'page-bottom';
+  }
+}
+
 function cleanupViewTransitionNames(document: Document): void {
   const titleEl = document.querySelector('.title-and-info');
   if (titleEl) {
     setTitleTransitionNames(titleEl, false);
   }
+  const bottom = document.querySelector<HTMLElement>('.page-bottom');
+  if (bottom) {
+    bottom.style.viewTransitionName = '';
+  }
 }
 
 function getLocationKey(window: Window): string {
@@ -213,6 +256,111 @@ export function getSavedLocationScroll(
   return scrollByLocation.get(locationKey);
 }
 
+// Browsers fire popstate synchronously during applyFragmentTarget
+export function isApplyingFragment(): boolean {
+  return applyingFragment;
+}
+
+// Restoring a history entry can leave :target stale. With manual scroll
+// restoration, WebKit skips fragment processing on Back/Forward, and swapped
+// content loses it in every browser. A fragment navigation sets it in every
+// browser, but it can reset the entry's history state and scroll position, so
+// restore both.
+//
+// WebKit defers fragment scrolling until pending stylesheets load, which would
+// later move the page away from the restored scroll position. Wait for them
+// first, and skip the update if another request or navigation replaced it.
+//
+// That deferred scroll can also set :target before the wait ends, which would
+// leave nothing to replace. WebKit then scrolls to the target again on the next
+// frame, undoing a scroll back to the saved position. A fragment navigation of
+// our own does not have that problem, so after waiting, repeat it even when
+// :target matches, restoring the saved position the caller passed in. When the
+// last stylesheet finishes loading just after the content swap, WebKit can
+// still scroll to the target in the next rendering update, after our restore,
+// so hold that position for a few frames.
+export function applyFragmentTarget(
+  window: Window,
+  restoredTop?: number,
+): void {
+  const request = ++fragmentTargetRequest;
+  const { href } = window.location;
+  let waited = false;
+  const apply = (): void => {
+    if (request !== fragmentTargetRequest || window.location.href !== href) {
+      return;
+    }
+    const pending = Array.from(pendingStylesheets.values());
+    if (pending.length > 0) {
+      waited = true;
+      void Promise.all(pending).then(apply);
+      return;
+    }
+    replaceFragmentTarget(window, waited ? restoredTop : undefined);
+  };
+  apply();
+}
+
+function replaceFragmentTarget(window: Window, forcedTop?: number): void {
+  const { document, history, location } = window;
+  if (
+    forcedTop === undefined &&
+    document.querySelector(':target') === getHashTarget(document, location.hash)
+  ) {
+    return;
+  }
+  const { href } = location;
+  const state = history.state;
+  const { scrollX } = window;
+  const scrollY = forcedTop ?? window.scrollY;
+  applyingFragment = true;
+  try {
+    globals.replaceLocation(
+      window,
+      location.pathname + location.search + (location.hash || '#'),
+    );
+  } finally {
+    applyingFragment = false;
+  }
+  history.replaceState(state, '', href);
+  window.scrollTo({ left: scrollX, top: scrollY });
+  if (forcedTop !== undefined) {
+    holdScroll(window, scrollX, scrollY);
+  }
+}
+
+// Scroll back to the given position on each of the next few frames if the
+// browser moved the page, until the visitor scrolls or the URL changes
+function holdScroll(window: Window, left: number, top: number): void {
+  const { href } = window.location;
+  let held = true;
+  const release = (): void => {
+    held = false;
+    for (const type of HOLD_SCROLL_RELEASE_EVENTS) {
+      window.removeEventListener(type, release);
+    }
+  };
+  for (const type of HOLD_SCROLL_RELEASE_EVENTS) {
+    window.addEventListener(type, release, { passive: true });
+  }
+  let frames = 0;
+  const tick = (): void => {
+    if (!held || window.location.href !== href) {
+      release();
+      return;
+    }
+    if (Math.abs(window.scrollY - top) > 1) {
+      window.scrollTo({ left, top });
+    }
+    if (++frames < HOLD_SCROLL_FRAMES) {
+      window.requestAnimationFrame(tick);
+    } else {
+      release();
+    }
+  };
+  window.requestAnimationFrame(tick);
+}
+
 export async function navigateToUrl(
   window: Window,
   options: NavigationOptions,
@@ -323,6 +471,14 @@ export async function navigateToUrl(
 
     teardownPerPageComponents();
     swapContent(document, newDoc);
+    if (!pushHistory) {
+      // Restore the entry's :target before updateHead adds stylesheets, so it
+      // applies right away unless an earlier stylesheet is still loading
+      applyFragmentTarget(
+        window,
+        typeof scrollTarget === 'number' ? scrollTarget : undefined,
+      );
+    }
     updateHead(document, newDoc);
     mountAppearancePickerForPage(window);
     currentPath = parsed.pathname + parsed.search;
@@ -369,6 +525,7 @@ export async function navigateToUrl(
     if (titleVisible) {
       setTitleTransitionNames(titleEl, true);
     }
+    setPageBottomTransitionName(window);
 
     document.documentElement.classList.add(
       direction === 'forward' ? 'nav-forward' : 'nav-back',
@@ -389,6 +546,7 @@ export async function navigateToUrl(
       if (newTitleVisible && newTitleEl) {
         setTitleTransitionNames(newTitleEl, true);
       }
+      setPageBottomTransitionName(window);
     });
 
     await transition.finished;

package/src/toc/_index.scss

@@ -149,10 +149,15 @@ body.code .toc ol a {
   width: var(--toc-alert-icon-size);
   height: var(--toc-alert-icon-size);
   margin-right: 4px;
-  vertical-align: sub;
+  vertical-align: middle;
   content: '';
 
   @include contained-mask(var(--toc-alert-icon));
+
+  // Center the icon on the cap height, which scales with each level's font
+  @supports (width: 1cap) {
+    vertical-align: calc(0.5cap - var(--toc-alert-icon-size) / 2);
+  }
 }
 
 .toc ol li.label {

package/templates/_theme.scss

@@ -54,7 +54,7 @@
     'Segoe UI Symbol';
   --sans-mono-font: 'Google Sans Code', 'Consolas', 'Courier', monospace;
   --serif-font: <%= serifFontStack %>;
-  --serif-preview-font: 'Times New Roman', 'Times', serif;
+  --serif-preview-font: 'Georgia', 'Times New Roman', 'Times', serif;
   --serif-mono-font: <%= serifMonoFontStack %>;
   --sans-font-feature-settings:
     'liga', 'calt', 'ss07', 'ss08', 'cv01', 'cv08', 'cv10';