@ultimat3/render 22.8.0 → 22.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "22.8.0",
+  "version": "22.8.1",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -38,11 +38,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.8.0",
-    "@ultimat3/core": "22.8.0",
-    "@ultimat3/http": "22.8.0",
-    "@ultimat3/i18n": "22.8.0",
-    "@ultimat3/seo": "22.8.0",
+    "@ultimat3/cache": "22.8.1",
+    "@ultimat3/core": "22.8.1",
+    "@ultimat3/http": "22.8.1",
+    "@ultimat3/i18n": "22.8.1",
+    "@ultimat3/seo": "22.8.1",
     "sass": "1.104.0"
   }
 }

package/src/navigation-controller-fixture.ts

@@ -0,0 +1,91 @@
+/**
+ * The controller's test harness beside the fake DOM: a page with the links every test follows, a
+ * tab whose `fetch` the test answers (every call recorded), an event dispatched the way a browser
+ * does, and the router the test started — stopped after each by `stopRouter()`.
+ */
+import { startNavigation } from './navigation';
+import {
+  FakeDocument,
+  type FakeElement,
+  type FakeWindow,
+  fakeWindow,
+  h,
+  htmlAnswer,
+  routerHead,
+} from './navigation-dom-fixture';
+
+export type Handler = (init: RequestInit | undefined) => Response | Promise<Response>;
+
+export const page = (
+  title: string,
+  meta: { scope?: string; build?: string } = {},
+  body: FakeElement[] = [],
+) =>
+  new FakeDocument(routerHead(title, [], meta), [
+    h('main', {}, [
+      h('h1', {}, title),
+      h('a', { id: 'to-b', href: '/b' }, 'b'),
+      h('a', { id: 'to-c', href: '/c' }, 'c'),
+      h('a', { id: 'to-slow', href: '/slow' }, 'slow'),
+      h('a', { id: 'plain', href: '/b', 'data-x-no-prefetch': '' }, 'plain'),
+      ...body,
+    ]),
+    h('script', {}, `hydrate(${title})`),
+  ]);
+
+/** The router the current test started; `stopRouter()` in an `afterEach` lets it go. */
+let router: ReturnType<typeof startNavigation>;
+export const currentRouter = (): ReturnType<typeof startNavigation> => router;
+export function stopRouter(): void {
+  router?.stop();
+  router = undefined;
+}
+
+/** A tab on `/a` whose `fetch` answers from `routes`; `calls` records `METHOD path purpose`. */
+export function tab(routes: Record<string, Handler>, doc = page('A')) {
+  const calls: string[] = [];
+  const fetch = (url: string, init?: RequestInit): Promise<Response> => {
+    const u = new URL(url);
+    const headers = (init?.headers ?? {}) as Record<string, string>;
+    calls.push(
+      `${init?.method ?? 'GET'} ${u.pathname}${u.search} ${headers['x-ultimate-navigation']}`,
+    );
+    const handler = routes[u.pathname];
+    if (handler === undefined) return Promise.reject(new TypeError('network'));
+    return Promise.resolve(handler(init));
+  };
+  const win = fakeWindow(doc, 'https://app.test/a', fetch);
+  router = startNavigation(win as unknown as Window);
+  return { win, doc, calls };
+}
+
+/** An event the way a browser dispatches it: cancelable, with its target and fields. */
+export function fire(
+  on: EventTarget,
+  type: string,
+  target: unknown,
+  fields: Record<string, unknown> = {},
+): Event {
+  const event = new Event(type, { cancelable: true, bubbles: true });
+  Object.defineProperty(event, 'target', { value: target });
+  for (const [key, value] of Object.entries({
+    button: 0,
+    metaKey: false,
+    ctrlKey: false,
+    shiftKey: false,
+    altKey: false,
+    ...fields,
+  })) {
+    Object.defineProperty(event, key, { value });
+  }
+  on.dispatchEvent(event);
+  return event;
+}
+
+export const click = (win: FakeWindow, id: string, fields?: Record<string, unknown>) =>
+  fire(win, 'click', win.document.getElementById(id), fields);
+
+export const answers = {
+  b: () => htmlAnswer('page:B', page('B')),
+  c: () => htmlAnswer('page:C', page('C')),
+};

package/src/navigation-dom-fixture.ts

@@ -257,6 +257,11 @@ export class FakeDocument extends EventTarget {
     node.adopt(this);
     return node;
   }
+  /** What a test says is under the pointer, for a click the browser aimed at `<html>`. */
+  underPointer: FakeElement | null = null;
+  elementFromPoint(): FakeElement | null {
+    return this.underPointer;
+  }
   getElementById(id: string): FakeElement | null {
     return this.documentElement.querySelectorAll('[id]').find((el) => el.id === id) ?? null;
   }
@@ -375,6 +380,7 @@ export function fakeWindow(doc: FakeDocument, url: string, fetch: FakeWindow['fe
   globals['DOMParser'] = FakeParser;
   globals['HTMLFormElement'] = FakeForm;
   globals['FormData'] = FakeFormData;
+  globals['HTMLElement'] = FakeElement;
   return self;
 }
 

package/src/navigation-dom.ts

@@ -56,13 +56,13 @@ const hush = (): void => undefined;
  * leaves an unhandled rejection behind. A throw inside `apply` rejects `updateCallbackDone`, which
  * the caller awaits and turns into a full load.
  */
-export async function transition(win: Window, apply: () => void): Promise<void> {
+export async function transition(
+  win: Window,
+  apply: () => void,
+  track?: (running: RunningTransition | undefined) => void,
+): Promise<void> {
   const doc = win.document as Document & {
-    startViewTransition?: (update: () => void) => {
-      updateCallbackDone: Promise<void>;
-      ready: Promise<void>;
-      finished: Promise<void>;
-    };
+    startViewTransition?: (update: () => void) => RunningTransition;
   };
   const still = win.matchMedia?.('(prefers-reduced-motion: reduce)').matches === true;
   if (doc.startViewTransition === undefined || still) {
@@ -70,11 +70,23 @@ export async function transition(win: Window, apply: () => void): Promise<void>
     return;
   }
   const running = doc.startViewTransition(apply);
+  track?.(running);
   running.ready.catch(hush);
-  running.finished.catch(hush);
+  running.finished.then(
+    () => track?.(undefined),
+    () => track?.(undefined),
+  );
   await running.updateCallbackDone;
 }
 
+/** The part of a `ViewTransition` the router uses. */
+export interface RunningTransition {
+  readonly updateCallbackDone: Promise<void>;
+  readonly ready: Promise<void>;
+  readonly finished: Promise<void>;
+  skipTransition?(): void;
+}
+
 /** Where a keyboard or screen-reader user lands: the page's `<main>`, else its first heading. */
 export function focusMain(doc: Document): void {
   const target = doc.querySelector<HTMLElement>('main') ?? doc.querySelector<HTMLElement>('h1');

package/src/navigation-history.ts

@@ -0,0 +1,59 @@
+/**
+ * The client router's history entries: its own slot in `history.state` (the scroll offset and the
+ * document the entry shows), how an entry is read back, how the scroll is saved into the entry of
+ * the page ON SCREEN, and where a page lands. Split from `navigation.ts` so that file is the
+ * controller and nothing else.
+ */
+
+/** The router's own slot in `history.state`, beside whatever an app keeps there. */
+export const STATE_KEY = '__x';
+
+export interface EntryState {
+  readonly scroll: readonly [number, number];
+  /** The document this entry shows — what back/forward compares with the one on screen. */
+  readonly doc: string;
+}
+
+/** Back/forward, as the router passes it: `none` restores; the others start at the top. */
+export type HistoryMode = 'push' | 'replace' | 'none' | undefined;
+
+export const withoutFragment = (url: string): string => url.split('#')[0] ?? url;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/** The router's entry in a `history.state`, or `undefined` for an entry an app pushed. */
+export const entryOf = (state: unknown): EntryState | undefined => {
+  const entry = isRecord(state) ? state[STATE_KEY] : undefined;
+  return isRecord(entry) && typeof entry['doc'] === 'string'
+    ? (entry as unknown as EntryState)
+    : undefined;
+};
+
+/**
+ * The scroll offset, into the entry of the document `rendered` — never into another's: between a
+ * back/forward and its swap, the current entry is the next page's, and this offset is not its.
+ */
+export function saveEntryScroll(win: Window, rendered: string): void {
+  const state = (win.history.state ?? {}) as Record<string, unknown>;
+  const held = entryOf(state)?.doc;
+  if (held !== undefined && held !== rendered) return;
+  const entry: EntryState = { scroll: [win.scrollX, win.scrollY], doc: held ?? rendered };
+  win.history.replaceState({ ...state, [STATE_KEY]: entry }, '');
+}
+
+/**
+ * Where the new page lands: the saved offset on back/forward, the fragment's element, else the
+ * top. `instant`, whatever the page's `scroll-behavior` says — `@ultimat3/ui`'s reset makes it
+ * `smooth`, and a new page is a new place, which a full load jumps to rather than glides to.
+ */
+export function scrollAfter(win: Window, doc: Document, url: string, mode: HistoryMode): void {
+  const hash = new URL(url).hash;
+  const target = hash.length > 1 ? doc.getElementById(decodeURIComponent(hash.slice(1))) : null;
+  const saved = entryOf(win.history.state);
+  const to = (left: number, top: number): void =>
+    win.scrollTo({ left, top, behavior: 'instant' as ScrollBehavior });
+  if (mode === 'none' && saved !== undefined) to(saved.scroll[0], saved.scroll[1]);
+  else if (target !== null) target.scrollIntoView({ behavior: 'instant' as ScrollBehavior });
+  else to(0, 0);
+}

package/src/navigation.ts

@@ -29,9 +29,18 @@ import {
   formFields,
   handOver,
   linkFacts,
+  type RunningTransition,
   transition,
 } from './navigation-dom';
 import { type Answer, fetchDocument, metaOf } from './navigation-fetch';
+import {
+  type EntryState,
+  entryOf,
+  STATE_KEY,
+  saveEntryScroll,
+  scrollAfter,
+  withoutFragment,
+} from './navigation-history';
 import {
   answerMovesTab,
   type FormFacts,
@@ -75,29 +84,9 @@ export interface NavigationRouter {
   stop(): void;
 }
 
-/** The router's own slot in `history.state`, beside whatever an app keeps there. */
-const STATE_KEY = '__x';
-interface EntryState {
-  readonly scroll: readonly [number, number];
-  /** The document this entry shows — what back/forward compares with the one on screen. */
-  readonly doc: string;
-}
-
 /** One channel per origin: a principal change or a write in one tab empties every tab's cache. */
 const CHANNEL = 'ultimate:navigation';
 
-const withoutFragment = (url: string): string => url.split('#')[0] ?? url;
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-const entryOf = (state: unknown): EntryState | undefined => {
-  const entry = isRecord(state) ? state[STATE_KEY] : undefined;
-  return isRecord(entry) && typeof entry['doc'] === 'string'
-    ? (entry as unknown as EntryState)
-    : undefined;
-};
-
 interface RouterWindow extends Window {
   __xNavigation?: NavigationRouter;
 }
@@ -118,6 +107,16 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     ),
   );
   let rendered = withoutFragment(win.location.href);
+  /** The URL a navigation in flight is fetching: a prefetch never asks for it a second time. */
+  let navigatingTo: string | undefined;
+  /** The view transition still animating, which a press skips to the new page. */
+  let animating: RunningTransition | undefined;
+  /** Between a press and its click: the focus the press gives a link is not a hover. */
+  let pressed = false;
+  /** The press landed while a transition was painting over the page (see `onClick`). */
+  let pressedOverTransition = false;
+  /** The pending prefetch of a hover, cancelled by anything that navigates. */
+  let intent: number | undefined;
   let untrusted = false;
   let inflight: AbortController | undefined;
   const live = announcer(doc);
@@ -135,15 +134,8 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   const offWrite = onClientWrite(forget);
   const offRescope = onRescope(forget);
 
-  const saveScroll = (): void => {
-    const state = (win.history.state ?? {}) as Record<string, unknown>;
-    const held = entryOf(state)?.doc;
-    // Only into the entry of the document ON SCREEN: between a back/forward and its swap, the
-    // current entry is the next page's, and this scroll offset is not its to keep.
-    if (held !== undefined && held !== rendered) return;
-    const entry: EntryState = { scroll: [win.scrollX, win.scrollY], doc: held ?? rendered };
-    win.history.replaceState({ ...state, [STATE_KEY]: entry }, '');
-  };
+  const saveScroll = (): void => saveEntryScroll(win, rendered);
+
   saveScroll();
   // Saved as the visitor scrolls, once the scroll settles — so FORWARD restores too, and a
   // browser's cap on `replaceState` calls is never approached.
@@ -157,7 +149,10 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     fetchDocument(win, doc, url, purpose, init);
 
   const prefetch = (url: string): void => {
-    if (untrusted || withoutFragment(url) === rendered || cache.get(url) !== undefined) return;
+    const key = withoutFragment(url);
+    if (untrusted || key === rendered || key === navigatingTo || cache.get(url) !== undefined) {
+      return;
+    }
     // Cached whatever it answers: an empty `204` (the route did not opt in) is remembered too, so
     // a second hover does not ask again. Only a reusable page ever answers a click (`reusable`).
     cache.set(url, request(url, 'prefetch'));
@@ -170,22 +165,6 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     if (doc.dispatchEvent(event)) win.location.assign(win.location.href);
   };
 
-  /**
-   * Where the new page lands: the saved offset on back/forward, the fragment's element, else the
-   * top. `instant`, whatever the page's `scroll-behavior` says — `@ultimat3/ui`'s reset makes it
-   * `smooth`, and a new page is a new place, which a full load jumps to rather than glides to.
-   */
-  const scrollAfter = (url: string, mode: NavigateOptions['history']): void => {
-    const hash = new URL(url).hash;
-    const target = hash.length > 1 ? doc.getElementById(decodeURIComponent(hash.slice(1))) : null;
-    const saved = entryOf(win.history.state);
-    const to = (left: number, top: number): void =>
-      win.scrollTo({ left, top, behavior: 'instant' as ScrollBehavior });
-    if (mode === 'none' && saved !== undefined) to(saved.scroll[0], saved.scroll[1]);
-    else if (target !== null) target.scrollIntoView({ behavior: 'instant' as ScrollBehavior });
-    else to(0, 0);
-  };
-
   const answerFor = (
     url: string,
     method: 'GET' | 'POST',
@@ -231,6 +210,8 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     inflight?.abort();
     const mine = new AbortController();
     inflight = mine;
+    win.clearTimeout(intent);
+    navigatingTo = withoutFragment(url);
     if (options.history !== 'none') saveScroll();
     const progress = win.setTimeout(
       () => doc.documentElement.setAttribute(NAVIGATING_ATTRIBUTE, ''),
@@ -296,23 +277,30 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
         await loadStylesheets(doc, missingStylesheets(doc, next));
         if (mine.signal.aborted) return;
         let swapped: ReturnType<typeof swapDocument> | undefined;
-        await transition(win, () => {
-          // A newer navigation started while the sheets loaded: this answer is no longer asked for.
-          if (mine.signal.aborted) return;
-          swapped = swapDocument(doc, next, owned);
-          // Emptied here and filled after the scripts, so a page with the same title still reads out.
-          live.textContent = '';
-          swapped.body.append(live);
-          rendered = withoutFragment(landed);
-          if (options.history !== 'none') {
-            const same = landed === win.location.href || options.history === 'replace';
-            const state = { [STATE_KEY]: { scroll: [0, 0], doc: rendered } satisfies EntryState };
-            if (same) win.history.replaceState(state, '', landed);
-            else win.history.pushState(state, '', landed);
-          }
-          // Inside the swap, so a view transition's "after" frame is already where the page lands.
-          scrollAfter(landed, options.history);
-        });
+        const track = (running: RunningTransition | undefined): void => {
+          animating = running;
+        };
+        await transition(
+          win,
+          () => {
+            // A newer navigation started while the sheets loaded: this answer is no longer asked for.
+            if (mine.signal.aborted) return;
+            swapped = swapDocument(doc, next, owned);
+            // Emptied here and filled after the scripts, so a page with the same title still reads out.
+            live.textContent = '';
+            swapped.body.append(live);
+            rendered = withoutFragment(landed);
+            if (options.history !== 'none') {
+              const same = landed === win.location.href || options.history === 'replace';
+              const state = { [STATE_KEY]: { scroll: [0, 0], doc: rendered } satisfies EntryState };
+              if (same) win.history.replaceState(state, '', landed);
+              else win.history.pushState(state, '', landed);
+            }
+            // Inside the swap, so a view transition's "after" frame is already where the page lands.
+            scrollAfter(win, doc, landed, options.history);
+          },
+          track,
+        );
         const done = swapped;
         if (done === undefined) return;
         if (method === 'POST' && answerMovesTab(facts)) {
@@ -339,12 +327,37 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
       win.clearTimeout(progress);
       if (inflight === mine) {
         inflight = undefined;
+        navigatingTo = undefined;
         doc.documentElement.removeAttribute(NAVIGATING_ATTRIBUTE);
       }
     }
   };
 
+  const onPress = (): void => {
+    pressed = true;
+    pressedOverTransition = animating !== undefined;
+    // A press is not a hover: the click it becomes navigates, and a guess on its heels is a
+    // second request for the same page. And a press during the animation skips to the new page.
+    win.clearTimeout(intent);
+    animating?.skipTransition?.();
+  };
+  const onRelease = (): void => {
+    pressed = false;
+  };
+
   const onClick = (event: MouseEvent): void => {
+    win.clearTimeout(intent);
+    // While a view transition paints, the browser hit-tests every press to `<html>`: the press
+    // skipped the animation (`onPress`), the release landed on the real element, and the click —
+    // aimed at their common ancestor — reached nothing. The visitor's first click after a swap was
+    // lost. It is given to the element under the pointer NOW, whatever it is: a link, a submit
+    // button, an island's own control.
+    if (pressedOverTransition && event.target === doc.documentElement) {
+      pressedOverTransition = false;
+      const hit = doc.elementFromPoint(event.clientX, event.clientY);
+      if (hit !== null && hit !== doc.documentElement && hit instanceof HTMLElement) hit.click();
+      return;
+    }
     const anchor = anchorOf(event.target);
     if (anchor === null) return;
     const verdict = linkVerdict(linkFacts(win, anchor, event));
@@ -393,8 +406,9 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     void navigate(verdict.url, { method: 'POST', body });
   };
 
-  let intent: number | undefined;
   const onIntent = (event: Event): void => {
+    // The focus a press gives a link: its click is a moment away, and it navigates.
+    if (event.type === 'focusin' && pressed) return;
     const anchor = anchorOf(event.target);
     if (anchor === null) return;
     const verdict = linkVerdict(linkFacts(win, anchor));
@@ -456,6 +470,9 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   doc.addEventListener('focusin', onIntent);
   doc.addEventListener('touchstart', onIntent, { passive: true });
   win.addEventListener('popstate', onPop);
+  doc.addEventListener('pointerdown', onPress, { capture: true, passive: true });
+  doc.addEventListener('pointerup', onRelease, { capture: true, passive: true });
+  doc.addEventListener('pointercancel', onRelease, { capture: true, passive: true });
 
   const router: NavigationRouter = {
     navigate,
@@ -469,6 +486,9 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
       doc.removeEventListener('focusin', onIntent);
       doc.removeEventListener('touchstart', onIntent);
       win.removeEventListener('popstate', onPop);
+      doc.removeEventListener('pointerdown', onPress, { capture: true });
+      doc.removeEventListener('pointerup', onRelease, { capture: true });
+      doc.removeEventListener('pointercancel', onRelease, { capture: true });
       offWrite();
       offRescope();
       channel?.close();