Building a Router the Back Button Can't Break

// index.ts
import { fetchMessage } from '../stand-in-server';
import type { InboxView } from '../inbox-view/types';

/**
 * Starts the smallest router the Navigation API allows.
 *
 * One `navigate` listener gets every navigation in the document, whether it comes from a link, a form, Back, Forward, or a script.
 * The listener takes over the ones that stay on the inbox's own page, loads the message the new URL names, and renders it.
 * It never stops a request.
 * A message the user already left can still finish loading and render under a newer URL.
 * Without the Navigation API it does nothing, and every link loads as a normal page.
 *
 * @param view - The inbox that draws what the URL names.
 * @returns A function that stops the router.
 */
export function startRouter( view: InboxView ): () => void {
	// Check if the Navigation API is available. If not, return a no-op function.
	if ( ! ( 'navigation' in window ) ) {
		return () => {};
	}

	// Remember the inbox's own path, to tell its links apart from links to other pages.
	const inboxPath = location.pathname;

	// Runs on every navigation, whether from a link, a form, Back, Forward, or a script.
	const onNavigate = ( event: NavigateEvent ): void => {
		// Leave navigations the page can't take over, jumps to a #fragment, and downloads to the browser.
		if ( ! event.canIntercept || event.hashChange || event.downloadRequest !== null ) {
			return;
		}
		// Other pages on the same site load as usual, because the inbox only handles its own page.
		const url = new URL( event.destination.url );
		if ( url.pathname !== inboxPath ) {
			return;
		}
		// The message id from ?message=, or null on the inbox itself.
		const id = url.searchParams.get( 'message' );

		// Take the navigation over.
		// The browser changes the URL without loading a page, then runs handler().
		event.intercept( {
			async handler() {
				// The inbox needs no request.
				if ( id === null ) {
					view.showInbox();
					document.title = 'Inbox';
					return;
				}

				// Load the message, draw it, and name the tab after it.
				const message = await fetchMessage( id );
				view.showMessage( message );
				document.title = message.subject;
			},
		} );
	};

	navigation.addEventListener( 'navigate', onNavigate );

	// Hand back a function that stops the router.
	return () => navigation.removeEventListener( 'navigate', onNavigate );
}

// index.ts
import { fetchMessage } from '../stand-in-server';
import type { InboxView } from '../inbox-view/types';

/**
 * Starts the smallest router, plus the one change that stops a load the user left.
 *
 * The browser aborts `event.signal` as soon as another navigation starts or the user presses Stop.
 * The router passes it to the request, which stops the request, and checks it again before rendering in case the response was already on its way.
 * The URL still changes the moment a link is clicked, while the old message stays on screen until the new one has loaded.
 * Without the Navigation API it does nothing, and every link loads as a normal page.
 *
 * @param view - The inbox that draws what the URL names.
 * @returns A function that stops the router.
 */
export function startRouter( view: InboxView ): () => void {
	// Check if the Navigation API is available. If not, return a no-op function.
	if ( ! ( 'navigation' in window ) ) {
		return () => {};
	}

	// Remember the inbox's own path, to tell its links apart from links to other pages.
	const inboxPath = location.pathname;

	// Runs on every navigation, whether from a link, a form, Back, Forward, or a script.
	const onNavigate = ( event: NavigateEvent ): void => {
		// Leave navigations the page can't take over, jumps to a #fragment, and downloads to the browser.
		if ( ! event.canIntercept || event.hashChange || event.downloadRequest !== null ) {
			return;
		}
		// Other pages on the same site load as usual, because the inbox only handles its own page.
		const url = new URL( event.destination.url );
		if ( url.pathname !== inboxPath ) {
			return;
		}
		// The message id from ?message=, or null on the inbox itself.
		const id = url.searchParams.get( 'message' );

		// Take the navigation over.
		// The browser changes the URL without loading a page, then runs handler().
		event.intercept( {
			async handler() {
				// The inbox needs no request.
				if ( id === null ) {
					view.showInbox();
					document.title = 'Inbox';
					return;
				}

				// With the signal, the request stops if the browser cancels the navigation.
				const message = await fetchMessage( id, { signal: event.signal } );

				// The navigation was canceled while the request ran. Draw nothing.
				if ( event.signal.aborted ) {
					return;
				}

				view.showMessage( message );
				document.title = message.subject;
			},
		} );
	};

	navigation.addEventListener( 'navigate', onNavigate );

	// Hand back a function that stops the router.
	return () => navigation.removeEventListener( 'navigate', onNavigate );
}

// index.ts
import { fetchMessage } from '../stand-in-server';
import type { Message } from '../stand-in-server/types';
import type { InboxView } from '../inbox-view/types';

/**
 * Draws what the URL names and names the page after it.
 *
 * With no id it draws the inbox, and with an id but no message it draws the error view, because the request for that message failed.
 *
 * @param view - The inbox that draws it.
 * @param id - The message id from the URL, or `null` for the inbox itself.
 * @param message - The conversation that loaded, or `null` when there is none.
 */
function render( view: InboxView, id: string | null, message: Message | null ): void {
	if ( id === null ) {
		// No message in the URL means the inbox.
		view.showInbox();
		document.title = 'Inbox';
	} else if ( message === null ) {
		// An id without a message means its request failed.
		view.showError( id );
		document.title = 'Message not found';
	} else {
		view.showMessage( message );
		document.title = message.subject;
	}
}

/**
 * Starts a router that keeps the URL and the screen in agreement while a message loads.
 *
 * Where the browser lets it, the router switches when ready.
 * Its `precommitHandler` loads the message before the navigation commits.
 * Until then, the old message and the old URL stay on screen.
 * The option needs a cancelable `navigate` event, and `intercept()` throws an `InvalidStateError` when it comes with an event that can't be canceled.
 * That's why the router checks `event.cancelable` first.
 * A Back press is cancelable only in a top-level page, and a browser without `precommitHandler` has no `NavigationPrecommitController`.
 * Everywhere else the router switches right away.
 * The URL changes at once, and the page shows a loading view until the message is there.
 * In both designs, a request that fails ends in the error view for the URL it was for.
 * Because the browser never commits a navigation whose signal was aborted, the `.catch()` in `precommitHandler` can't put a load the user left on screen.
 * Without the Navigation API it does nothing, and every link loads as a normal page.
 *
 * @param view - The inbox that draws what the URL names.
 * @returns A function that stops the router.
 */
export function startRouter( view: InboxView ): () => void {
	// Check if the Navigation API is available. If not, return a no-op function.
	if ( ! ( 'navigation' in window ) ) {
		return () => {};
	}

	// Remember the inbox's own path, to tell its links apart from links to other pages.
	const inboxPath = location.pathname;

	// Runs on every navigation, whether from a link, a form, Back, Forward, or a script.
	const onNavigate = ( event: NavigateEvent ): void => {
		// Leave navigations the page can't take over, jumps to a #fragment, and downloads to the browser.
		if ( ! event.canIntercept || event.hashChange || event.downloadRequest !== null ) {
			return;
		}
		// Other pages on the same site load as usual, because the inbox only handles its own page.
		const url = new URL( event.destination.url );
		if ( url.pathname !== inboxPath ) {
			return;
		}
		// The message id from ?message=, or null on the inbox itself.
		const id = url.searchParams.get( 'message' );

		// Switch when ready where the navigation is cancelable and precommitHandler exists.
		if ( event.cancelable && 'NavigationPrecommitController' in window ) {
			let message: Message | null = null;
			event.intercept( {
				// Runs before the URL changes. The navigation waits for its promise.
				async precommitHandler() {
					// The inbox needs no request.
					if ( id === null ) {
						return;
					}

					// A failed request becomes null, and render() then draws the error view.
					message = await fetchMessage( id, { signal: event.signal } ).catch( () => null );
				},
				// Runs once the URL has changed.
				handler() {
					render( view, id, message );
				},
			} );
			return;
		}

		// Otherwise switch right away. The URL changes now, and a loading view stays up until the message arrives.
		event.intercept( {
			async handler() {
				// The inbox needs no request.
				if ( id === null ) {
					render( view, id, null );
					return;
				}

				// The URL already changed. Show the loading view while the message loads.
				view.showLoading( id );

				// On failure, message is null and render() draws the error view.
				const message = await fetchMessage( id, { signal: event.signal } ).catch( () => null );

				// Skip drawing if the user left during the load.
				if ( event.signal.aborted ) {
					return;
				}

				render( view, id, message );
			},
		} );
	};

	navigation.addEventListener( 'navigate', onNavigate );

	// Hand back a function that stops the router.
	return () => navigation.removeEventListener( 'navigate', onNavigate );
}

// index.ts
import { fetchMessage } from '../stand-in-server';
import type { Message } from '../stand-in-server/types';
import type { InboxView } from '../inbox-view/types';

/**
 * Draws what the URL names, names the page after it, and moves focus to its heading.
 *
 * With no id it draws the inbox, and with an id but no message it draws the error view, because the request for that message failed.
 * Focus goes to the heading so a keyboard user continues from the new content and a screen reader announces where they arrived.
 *
 * @param view - The inbox that draws it.
 * @param id - The message id from the URL, or `null` for the inbox itself.
 * @param message - The conversation that loaded, or `null` when there is none.
 */
function render( view: InboxView, id: string | null, message: Message | null ): void {
	if ( id === null ) {
		// No message in the URL means the inbox.
		view.showInbox();
		document.title = 'Inbox';
	} else if ( message === null ) {
		// An id without a message means its request failed.
		view.showError( id );
		document.title = 'Message not found';
	} else {
		view.showMessage( message );
		document.title = message.subject;
	}

	// All three branches end here, with focus on the heading the view just drew.
	view.focusHeading();
}

/**
 * Starts the router from the two designs, with focus handled by the router instead of the browser.
 *
 * By default the browser moves focus to the page body, or to the first `autofocus` element, once an intercepted navigation finishes.
 * `focusReset: 'manual'` turns that off, so focus stays where the router puts it, on the heading of the new content.
 * Everything else matches the two designs.
 * It switches when ready where the `navigate` event is cancelable and `precommitHandler` exists, and switches right away with a loading view everywhere else.
 * Without the Navigation API it does nothing, and every link loads as a normal page.
 *
 * @param view - The inbox that draws what the URL names.
 * @returns A function that stops the router.
 */
export function startRouter( view: InboxView ): () => void {
	// Check if the Navigation API is available. If not, return a no-op function.
	if ( ! ( 'navigation' in window ) ) {
		return () => {};
	}

	// Remember the inbox's own path, to tell its links apart from links to other pages.
	const inboxPath = location.pathname;

	// Runs on every navigation, whether from a link, a form, Back, Forward, or a script.
	const onNavigate = ( event: NavigateEvent ): void => {
		// Leave navigations the page can't take over, jumps to a #fragment, and downloads to the browser.
		if ( ! event.canIntercept || event.hashChange || event.downloadRequest !== null ) {
			return;
		}
		// Other pages on the same site load as usual, because the inbox only handles its own page.
		const url = new URL( event.destination.url );
		if ( url.pathname !== inboxPath ) {
			return;
		}
		// The message id from ?message=, or null on the inbox itself.
		const id = url.searchParams.get( 'message' );

		// Switch when ready where the navigation is cancelable and precommitHandler exists.
		if ( event.cancelable && 'NavigationPrecommitController' in window ) {
			let message: Message | null = null;
			event.intercept( {
				// Keep the browser from moving focus to the page body after the navigation.
				focusReset: 'manual',
				// Runs before the URL changes. The navigation waits for its promise.
				async precommitHandler() {
					// The inbox needs no request.
					if ( id === null ) {
						return;
					}

					// A failed request becomes null, and render() then draws the error view.
					message = await fetchMessage( id, { signal: event.signal } ).catch( () => null );
				},
				// Runs once the URL has changed.
				handler() {
					render( view, id, message );
				},
			} );
			return;
		}

		// Otherwise switch right away. The URL changes now, and a loading view stays up until the message arrives.
		event.intercept( {
			// Keep the browser from moving focus to the page body after the navigation.
			focusReset: 'manual',
			async handler() {
				// The inbox needs no request.
				if ( id === null ) {
					render( view, id, null );
					return;
				}

				// The URL already changed. Show the loading view while the message loads.
				view.showLoading( id );

				// On failure, message is null and render() draws the error view.
				const message = await fetchMessage( id, { signal: event.signal } ).catch( () => null );

				// Skip drawing if the user left during the load.
				if ( event.signal.aborted ) {
					return;
				}

				render( view, id, message );
			},
		} );
	};

	navigation.addEventListener( 'navigate', onNavigate );

	// Hand back a function that stops the router.
	return () => navigation.removeEventListener( 'navigate', onNavigate );
}

/**
 * Returns the scroll position saved in a history entry's state, if there is one.
 *
 * @param state - Whatever `getState()` returned for the entry.
 * @returns The saved position, or `0` for an entry that never saved one.
 */
function savedScrollTop( state: unknown ): number {
	if ( typeof state === 'object' && state !== null && 'scrollTop' in state && typeof state.scrollTop === 'number' ) {
		return state.scrollTop;
	}
	return 0;
}

/**
 * Saves the position of a box that scrolls inside the page in each history entry, and puts it back on Back, Forward, and reload.
 *
 * The browser restores the scroll position of the page itself after an intercepted Back, but not of a box that scrolls inside the page, like a reading pane.
 * So before every navigation the current position goes into the current entry's state with `navigation.updateCurrentEntry()`.
 * When a traversal finishes, the box scrolls to the position saved in the destination entry, a reload keeps the position it had, and any other navigation starts it at the top.
 * After a jump to a fragment, the box stays where the browser put it, even though `navigatesuccess` fires for that jump too.
 * It runs next to any router built on the `navigate` event, because it only listens and never calls `intercept()`.
 *
 * @param $scroller - The box whose position each entry keeps.
 * @returns A function that stops saving and restoring.
 */
export function rememberScroll( $scroller: HTMLElement ): () => void {
	if ( ! ( 'navigation' in window ) ) {
		return () => {};
	}
	let restoreTo: number | null = null;

	const onNavigate = ( event: NavigateEvent ): void => {
		// A new navigation drops the position the last one was going to restore.
		restoreTo = null;
		if ( ! event.canIntercept || event.hashChange ) {
			return;
		}
		// Read what the page already stored in the entry it's leaving.
		const state = navigation.currentEntry?.getState();

		// Start from that data when it's an object, and from an empty object otherwise.
		const saved = typeof state === 'object' && state !== null ? state : {};

		// Add the pane's position to the entry the page is leaving, next to that data.
		navigation.updateCurrentEntry( {
			state: {
				...saved,
				scrollTop: $scroller.scrollTop,
			},
		} );

		// On Back or Forward, the pane returns to the position saved in the destination entry.
		if ( event.navigationType === 'traverse' ) {
			// Find it by key, since WebKit's event.destination.getState() is empty here.
			const destination = navigation.entries().find( ( entry ) => entry.key === event.destination.key );
			restoreTo = savedScrollTop( destination?.getState() );
			return;
		}

		// A reload leaves the pane in place.
		if ( event.navigationType === 'reload' ) {
			restoreTo = $scroller.scrollTop;
			return;
		}

		// A click, or any other navigation, starts the pane at the top.
		restoreTo = 0;
	};

	// Scroll only once the router has drawn the new content, which is when the navigation succeeds.
	const onSuccess = (): void => {
		if ( restoreTo !== null ) {
			$scroller.scrollTop = restoreTo;
		}
	};

	navigation.addEventListener( 'navigate', onNavigate );
	navigation.addEventListener( 'navigatesuccess', onSuccess );
	return () => {
		navigation.removeEventListener( 'navigate', onNavigate );
		navigation.removeEventListener( 'navigatesuccess', onSuccess );
	};
}