@ultimat3/render 25.2.0 → 26.1.0

package/src/navigation-modal.ts

@@ -0,0 +1,233 @@
+/**
+ * The route-presented modal: ONE native `<dialog>` over the page on screen, holding the `<main>` of
+ * a page whose route declared `navigation: 'modal'`. The page beneath is never touched — its
+ * islands, socket and state stay live, `showModal()` makes it inert — and the modal is addressed by
+ * the URL's hash (`/runs#/runs/new`), so a reload, Back/Forward and a pasted link reopen it.
+ * `navigation.ts` decides WHEN (`navigation-modal-rules.ts`); this file only shows and hides.
+ */
+
+import { metaOf } from './navigation-fetch';
+import { entryOf, STATE_KEY, withoutFragment } from './navigation-history';
+import {
+  leaveModal,
+  modalLocation,
+  NAVIGATION_MODAL_ATTRIBUTE,
+  NAVIGATION_PRESENTATION_META,
+  type Presentation,
+  type PresentationFacts,
+  presentation,
+} from './navigation-modal-rules';
+import { disposeIslands, runScripts } from './navigation-swap';
+
+export interface ModalController {
+  /** The open modal's address (`/runs/new`), or `undefined`. */
+  readonly address: string | undefined;
+  /** The entry on screen is the one this router pushed for the open modal. */
+  owned(): boolean;
+  /** `presentation`, with what this tab knows filled in: the answer's meta, the open modal. */
+  presentationOf(
+    next: Document | null,
+    landed: string,
+    facts: Omit<PresentationFacts, 'modalPage' | 'modalOpen' | 'landed' | 'rendered'>,
+  ): Presentation;
+  /** `leaveModal` for a page answered over the open modal; `undefined` with none open. */
+  leaveFor(
+    history: 'push' | 'replace' | 'none' | undefined,
+    landed: string,
+  ): 'back' | 'replace' | 'none' | undefined;
+  /** Shows `next`'s `<main>` as the modal at `address`; its stylesheets are already loaded. */
+  present(
+    next: Document,
+    address: string,
+    landed: string,
+    history: 'push' | 'replace' | 'none',
+  ): Promise<void>;
+  /** Escape, a native close, a link to the page beneath: Back when this router pushed the entry. */
+  close(): void;
+  /** The hash names no modal for this tab: dropped in place, the page stays. */
+  clear(): void;
+  /** The DOM half only, once history already says closed. */
+  dismiss(): void;
+}
+
+/**
+ * Hrefs and actions as written resolve against the MODAL's URL, as on its own page: moved over
+ * another page, `href="edit"` and a form with no `action` would point at the page beneath.
+ */
+function rebase(root: Element, landed: string): void {
+  const resolve = (el: Element, name: string): void => {
+    const raw = el.getAttribute(name) ?? '';
+    if (raw.startsWith('#') || !URL.canParse(raw, landed)) return;
+    el.setAttribute(name, new URL(raw, landed).href);
+  };
+  for (const el of root.querySelectorAll('a[href], area[href]')) resolve(el, 'href');
+  for (const el of root.querySelectorAll('[formaction]')) resolve(el, 'formaction');
+  for (const form of root.querySelectorAll('form')) {
+    if ((form.getAttribute('action') ?? '') === '') form.setAttribute('action', landed);
+    else resolve(form, 'action');
+  }
+}
+
+/** Named by its first heading, as `@ultimat3/ui`'s `Dialog` is by its title. */
+function label(dialog: HTMLDialogElement, title: string): void {
+  const heading = dialog.querySelector('h1, h2');
+  if (heading === null) {
+    dialog.setAttribute('aria-label', title);
+    return;
+  }
+  if (heading.id === '') heading.id = 'x-modal-title';
+  dialog.setAttribute('aria-labelledby', heading.id);
+}
+
+export function modalController(
+  win: Window,
+  rendered: () => string,
+  ran: Set<string>,
+  head: WeakSet<Element>,
+): ModalController {
+  const doc = win.document;
+  let dialog: HTMLDialogElement | undefined;
+  /** The open modal's path (`/runs/new`), as the URL bar shows it. */
+  let openAt: string | undefined;
+  let opener: Element | null = null;
+  let title = '';
+  /** A close is under way (a Back in flight): a second Escape must not go Back twice. */
+  let leaving = false;
+
+  const owned = (): boolean => {
+    // The modal the entry on screen was pushed for — a path, compared with the one open.
+    const pushedFor = entryOf(win.history.state)?.modal;
+    return openAt !== undefined && pushedFor === openAt;
+  };
+
+  const dismiss = (): void => {
+    const open = dialog;
+    if (open === undefined) return;
+    dialog = undefined;
+    openAt = undefined;
+    leaving = false;
+    disposeIslands(open, () => false);
+    if (open.open) open.close();
+    open.remove();
+    doc.title = title;
+    // Back where the visitor was: the link or button that opened it, when it is still there.
+    if (opener?.isConnected === true) (opener as HTMLElement).focus?.({ preventScroll: true });
+    opener = null;
+  };
+
+  /** The modal's mark off the entry, the hash off the URL — Back would leave the app. */
+  const clearEntry = (): void => {
+    const state = (win.history.state ?? {}) as Record<string, unknown>;
+    const { modal: _modal, ...entry } = entryOf(state) ?? {
+      scroll: [win.scrollX, win.scrollY] as const,
+      doc: rendered(),
+    };
+    win.history.replaceState({ ...state, [STATE_KEY]: entry }, '', rendered());
+  };
+
+  const close = (): void => {
+    if (openAt === undefined || leaving) return;
+    if (owned()) {
+      leaving = true;
+      // `popstate` reconciles: the entry beneath has no modal, so `dismiss` runs there.
+      win.history.back();
+      return;
+    }
+    clearEntry();
+    dismiss();
+  };
+
+  const onCancel = (event: Event): void => {
+    event.preventDefault();
+    close();
+  };
+  // A `<form method="dialog">`, or an Escape the browser would not let be cancelled: the dialog
+  // closed itself, and the URL must follow. One it closed for `dismiss` is no longer `dialog`.
+  const onClose = (event: Event): void => {
+    if (event.target === dialog && dialog !== undefined && !dialog.open) close();
+  };
+
+  const present = async (
+    next: Document,
+    at: string,
+    landed: string,
+    history: 'push' | 'replace' | 'none',
+  ): Promise<void> => {
+    const source = next.querySelector('main') ?? next.body;
+    // Scripts outside `<main>` (the hydration runtime, island modules) boot what is inside it.
+    const outside = [...next.body.querySelectorAll('script')].filter((s) => !source.contains(s));
+    rebase(source, landed);
+    const content = [...source.childNodes, ...outside].map((node) => doc.adoptNode(node));
+    const headScripts = [...next.head.querySelectorAll('script[src]')] as HTMLScriptElement[];
+    let open = dialog;
+    if (open === undefined) {
+      opener = doc.activeElement;
+      title = doc.title;
+      open = doc.createElement('dialog');
+      open.setAttribute(NAVIGATION_MODAL_ATTRIBUTE, '');
+      open.addEventListener('cancel', onCancel);
+      open.addEventListener('close', onClose);
+      doc.body.append(open);
+    } else {
+      // One modal at a time: the next address replaces this one's content, in the same dialog.
+      // Closed as `dismiss` closes it — no longer `dialog` — so its own `close` event, queued or
+      // (in any engine that fires it at once) synchronous, is never read as the visitor closing.
+      disposeIslands(open, () => false);
+      dialog = undefined;
+      if (open.open) open.close();
+    }
+    dialog = open;
+    openAt = at;
+    leaving = false;
+    open.replaceChildren(...content);
+    label(open, next.title);
+    doc.title = next.title;
+    open.showModal();
+    if (history !== 'none') {
+      const state = {
+        [STATE_KEY]: { scroll: [win.scrollX, win.scrollY], doc: rendered(), modal: at },
+      };
+      const url = modalLocation(rendered(), at);
+      if (history === 'push') win.history.pushState(state, '', url);
+      else win.history.replaceState(state, '', url);
+    }
+    await runScripts(headScripts, ran, (fresh) => {
+      doc.head.append(fresh);
+      head.add(fresh);
+    });
+    await runScripts([...open.querySelectorAll('script')], ran, (fresh, inert) =>
+      inert.replaceWith(fresh),
+    );
+  };
+
+  return {
+    get address() {
+      return openAt;
+    },
+    owned,
+    presentationOf: (next, landed, facts) =>
+      presentation({
+        ...facts,
+        modalPage: next !== null && metaOf(next, NAVIGATION_PRESENTATION_META) === 'modal',
+        modalOpen: openAt !== undefined,
+        landed: withoutFragment(landed),
+        rendered: rendered(),
+      }),
+    leaveFor: (history, landed) =>
+      openAt === undefined
+        ? undefined
+        : leaveModal({
+            history,
+            landed: withoutFragment(landed),
+            rendered: rendered(),
+            owned: owned(),
+          }),
+    present,
+    close,
+    clear() {
+      clearEntry();
+      dismiss();
+    },
+    dismiss,
+  };
+}

package/src/navigation-press.ts

@@ -0,0 +1,59 @@
+/**
+ * The client router's press bookkeeping: between a press and its click (the focus a press gives a
+ * link is not a hover), and the view transition still painting — whose overlay swallows a click,
+ * which is given back to the element under the pointer. Split from `navigation.ts` so that file is
+ * the controller and nothing else.
+ */
+
+import type { RunningTransition } from './navigation-dom';
+
+export interface PressTracker {
+  /** Between a press and its click. */
+  pressed(): boolean;
+  /** `transition`'s `track`: the running transition, forgotten by identity once it finishes. */
+  track(running: RunningTransition, finished: boolean): void;
+  onPress(): void;
+  onRelease(): void;
+  /**
+   * True when `event` is a click the transition overlay swallowed: the transition is skipped and
+   * the click re-aimed at the element under the pointer, and the caller has nothing left to do.
+   */
+  overlayClick(event: MouseEvent): boolean;
+}
+
+export function pressTracker(doc: Document): PressTracker {
+  let animating: RunningTransition | undefined;
+  let pressed = false;
+  /** The press landed while a transition was painting over the page. */
+  let pressedOverTransition = false;
+  return {
+    pressed: () => pressed,
+    track(running, finished) {
+      if (!finished) animating = running;
+      else if (animating === running) animating = undefined;
+    },
+    onPress() {
+      pressed = true;
+      // A press alone never skips the running transition — that snapped every named element to
+      // its end mid-glide (#621); only the click it becomes may.
+      pressedOverTransition = animating !== undefined;
+    },
+    onRelease() {
+      pressed = false;
+    },
+    // While a view transition paints, the browser hit-tests every press to `<html>` — Chrome does
+    // so whatever `pointer-events` the `::view-transition` overlay has — so the click reached
+    // nothing: the visitor's first click after a swap was lost. It is given to the element under
+    // the pointer, whatever it is: a link, a submit button, an island's own control. Only a
+    // skipped transition hit-tests the page, so the skip happens at the click, never at the
+    // press; when the animation already ended between the two, there is nothing to skip.
+    overlayClick(event) {
+      if (!pressedOverTransition || event.target !== doc.documentElement) return false;
+      pressedOverTransition = false;
+      animating?.skipTransition?.();
+      const hit = doc.elementFromPoint(event.clientX, event.clientY);
+      if (hit !== null && hit !== doc.documentElement && hit instanceof HTMLElement) hit.click();
+      return true;
+    },
+  };
+}

package/src/navigation-swap.ts

@@ -84,12 +84,19 @@ export function loadStylesheets(
 /**
  * Calls each island's disposer — what its `mount` returned, held by `el.__x` — unless the island
  * is carried across. A rejected boot has nothing to dispose, and the rejection is already on the
- * element as `data-x-failed`.
+ * element as `data-x-failed`. An island whose boot has not STARTED (an `idle` one still waiting
+ * for the browser, a `visible` one never scrolled to) is settled instead: the hydration runtime's
+ * `boot` answers an element that already has `__x` with it, so the pending boot mounts nothing into
+ * a body that left the document — a mount nobody would ever dispose.
  */
 export function disposeIslands(root: Element, kept: (el: Element) => boolean): number {
   let disposed = 0;
   for (const el of root.querySelectorAll<IslandElement>(ISLAND_SELECTOR)) {
-    if (kept(el) || el.__x === undefined) continue;
+    if (kept(el)) continue;
+    if (el.__x === undefined) {
+      el.__x = Promise.resolve();
+      continue;
+    }
     disposed += 1;
     el.__x.then(
       (dispose) => {

package/src/navigation-tags.ts

@@ -1,19 +1,23 @@
 /**
  * What an opted-in document carries for the client router: which surface rendered it, which build
- * (the skew check — the same meta realtime's sync tags write, deduped by key), and the router's
- * script. A surface that did not opt in gets none of the three, so it pays no byte.
+ * (the skew check — the same meta realtime's sync tags write, deduped by key), the router's
+ * script, and — for a `navigation: 'modal'` route — that it is presented over another page. A
+ * surface that did not opt in gets none of them, so it pays no byte.
  */
 
 import { CLIENT_BUILD_META } from '@ultimat3/core';
 import type { HeadTag } from './head';
+import { NAVIGATION_PRESENTATION_META } from './navigation-modal-rules';
 import { NAVIGATION_META } from './navigation-rules';
 
 export interface ClientNavigationHead {
   /** The surface this document belongs to — a link that lands on another is a full load. */
   readonly surface: string;
   readonly buildId: string;
-  /** `/_x/navigation/<hash>.js`, content-addressed and served `immutable`. */
+  /** `/_x/assets/navigation/<hash>.js`, content-addressed and served `immutable`. */
   readonly scriptUrl: string;
+  /** The route declared `navigation: 'modal'`: the router shows it over the page beneath. */
+  readonly modal?: boolean;
 }
 
 export function clientNavigationTags(head: ClientNavigationHead): readonly HeadTag[] {
@@ -28,6 +32,15 @@ export function clientNavigationTags(head: ClientNavigationHead): readonly HeadT
       key: `meta:${CLIENT_BUILD_META}`,
       attrs: { name: CLIENT_BUILD_META, content: head.buildId },
     },
+    ...(head.modal === true
+      ? [
+          {
+            kind: 'meta' as const,
+            key: `meta:${NAVIGATION_PRESENTATION_META}`,
+            attrs: { name: NAVIGATION_PRESENTATION_META, content: 'modal' },
+          },
+        ]
+      : []),
     // Deferred, in `<head>`: it runs once, after parsing, and survives every swap of the body.
     {
       kind: 'script',