@k8ordo/router

How it works

When and where @k8ordo/router handles a navigation, and what it does and does not guarantee.

On this page

Where it runs

Navigations are handled by one hook, useInterceptedNavigation. <Router> calls it with its route table, and the runtime of @k8ordo/framework calls the same hook.

The two differ only in which navigations they handle and what they load. Everything else on this page holds under both.

To build a host of your own on this hook, see API.

Intercepted navigations

A link click, navigateTo, and the browser’s back and forward all reach the page as the same navigate event. <Router> listens to it and intercepts only the navigations whose destination path is in the route table.

The hook never intercepts these four. Whatever the route table says, the browser handles them as usual.

  • A reload: it fetches a fresh page from the server
  • A form submitted with a body (POST): only the server can act on the body
  • A download: it saves a file
  • A change to the fragment alone (what follows #): it moves within the same page

A navigation the browser does not allow a page to intercept, such as one to another origin, is not intercepted either. A GET form carries no body, so it is intercepted. URL rewrites by @k8ordo/state’s update() go through the same event. See Updates.

When finished resolves

The finished promise that navigateTo returns resolves when the new page has rendered, not when the URL changed.

More precisely, after React commits the new page and before the browser paints it, so the new page never shows for a frame at the old scroll position.

What it waits for is the new page’s first commit. When a React.lazy page suspends inside a <Suspense> the navigation newly mounted, finished resolves once the fallback is committed. It does not wait for the code to load.

State-only updates

When only the query or the history entry’s state changes, the path is that of the page on screen. The router does not treat this as a page change, and intercepts it without loading anything. Nothing remounts and focus stays where it is. Except on back and forward, scroll stays put too, and finished resolves as soon as the URL changes.

On back and forward, the scroll position returns to where the history entry was left. It does so once the page has rendered that entry’s values, so a list rendered late through useDeferredValue comes back to where it was left too, and finished waits for that render.

The exception is a refresh passed to useInterceptedNavigation that returns true. The page at the same path then loads again, and finished waits for it to render. Focus stays put, and no transition types are added. Only on back and forward does the scroll position come back, once the page loaded again is on screen. <Router> never loads again in place, while @k8ordo/framework does for a page that exports search.

The comparison is with the page on screen, which is not always what the address bar shows. A state-only update to the URL of a page that is still loading counts as a page change. That page still arrives, and the update’s finished waits for it to render. Going back, while it loads, to the entry of the page on screen calls the page change off, and the scroll position stays.

Render priority

The new page renders at the priority useDeferredValue gives it. The previous page stays on screen, and stays usable, until the next one is ready.

It is not a transition, so an action can await finished without stalling, and a pending action elsewhere does not delay a page change.

The render carries the transition types navigation and a kind such as navigation-push. For using them with <ViewTransition>, see Transitions.

Scroll and focus

Once the new page is on screen, focus goes where a page load would put it: to the element with autofocus, or to <body> when there is none. Scroll goes the same way, to the element the fragment names, or to the top when there is no fragment.

The fragment’s element is the one whose id or name attribute matches. The fragment is decoded first, so #%E5%B0%8E%E5%85%A5 finds id="導入". When nothing matches, the page goes to the top.

On the browser’s back and forward, the scroll position returns to where the history entry was left. The router puts it there, not the browser, and at once, as the page comes on screen. Scrolling the previous page while the next one loads does not change where it lands. An entry that never reached the screen, such as a page change called off while it loaded, goes to the fragment’s element or to the top.

WebKit is the exception. In a document it loaded again on coming back from another origin, it gives a traversal to an earlier history entry no key, so the browser restores the position instead of the router. If the visitor scrolled the previous page while the next one loaded, the browser does not restore it, and the page stays where they scrolled it.

Coming back from another site, WebKit does not report some traversals at all: to an entry from before that site, and, once the visitor has moved on, back to the page they came back to, even before the next page has loaded. The router then reloads the page. The browser restores the position of a page rendered on the server, and a page rendered on the client starts at the top. A step within a page that only moves the search reloads only when refresh says the page loads again for it, or while a page is still loading. A link followed while the page reloads opens as a document load.

Superseded navigations

When the next navigation starts while one is still loading, the earlier one is aborted through the browser’s own AbortSignal. The overtaken navigation’s finished rejects with the abort reason. Its page never reaches the screen, even if its load completes afterwards.

A React.lazy chunk cannot be cancelled. A dynamic import takes no AbortSignal, so the load runs to the end and is reused on the next visit.

Guarantees

  • A reload, a download, a form submitted with a body and a change to the fragment alone are never intercepted.
  • finished resolves after React commits the new page and before the browser paints it.
  • A page change is never held back by a pending action, and an action that awaits finished does not stall.
  • A navigation that changes only the query or the entry’s state does not move focus, nor, except on back and forward, the scroll position.
  • On back and forward, within one page too, the scroll position returns to where the entry was left once the page has rendered that entry.
  • Going back while a page loads, to the entry of the page still on screen, leaves the scroll position where it is.
  • A page change other than back and forward scrolls to the fragment’s element or to the top. The new page is never painted at the old scroll position.
  • A navigation overtaken while loading has its finished reject with the abort reason, and its page never reaches the screen.
  • The render of a page change carries navigation and a kind such as navigation-push. An update at the same path carries none.

Not guaranteed

  • The URL and the page on screen do not agree while the next page loads. The URL changes first, and the previous page stays on screen.
  • finished does not wait for a React.lazy page’s code to load.
  • On back and forward, only the document’s scroll position comes back, not that of an element scrolling inside the page, nor the pinch-zoom scale.
  • In a document WebKit loaded again on coming back from another origin or site, the position may not return to where the entry was left.
  • An overtaken navigation does not stop the load of its React.lazy chunk.
k8ordo

React libraries that use Baseline features without holding back.