Explainer for focus management and scroll restoration

[domenic]

This also rearranges some of the content around accessibility technology announcements and loading spinners/stop buttons, grouping them all under a new section "Customizations and consequences of navigation interception".

Still a few TODOs for next week, thus leaving this in a draft state. But the plan is for this PR to address #187, #190, and #25.

---

Preview | Diff

[domenic]

Hmm, transitionWhile() being the place to set these options runs into unclear semantics if you set it twice:

appHistory.addEventListener("navigate", e => {
  e.transitionWhile(Promise.resolve(), { focusReset: "manual" });
  e.transitionWhile(Promise.resolve(), { focusReset: "after-transition" });
});

// A more realistic example might involve multiple navigate handlers...

Options I see...

• Require the options to always match, throwing an exception on callers after the first if they mismatch. (Not great for apps trying to use multiple transitionWhile() calls or navigate event handlers in a non-coordinated fashion.)

• Try to come up with a conflict-resolution procedure. E.g.:

  • First wins (with later values ignored)
  • Last wins (with previous values ignored)
  • if "manual" is ever specified (i.e., not the default), it wins over "after-transition". (Gets complicated if we ever expand the value space like the explainer indicates we might.)
  • Any of these could include console warnings, I guess.

• Abandon the idea of tying these options to transitionWhile() calls? E.g. navigateEvent.setOptions(...)?

  • It's not clear this really solves the problem, since you could still call that method twice. But it might give us flexibility to pick one of the above strategies in a way that's less confusing.
  • This is a bit less appealing because these options generally only make sense in the transitionWhile() case anyway... we'd basically duplicate all of the precondition logic.
  • Maybe something global, like appHistory.setTransitionOptions(...) or appHistory.focusReset = ..., appHistory.scrollRestoration = ...?

[domenic]

I think the primary question is: do we expect people to want the same values for focusReset / scrollRestoration for all app history-mediated navigations in their app? Or might it vary depending on the navigation in question?

If we expect it to be the same, then a global API makes sense. Otherwise, it'd need to be configured per-navigate event.

[tbondwilkinson]

Can you comment here when it would be appropriate to call element.focus() after transition? Would you recommend using the transition property, or in a currentchange listener, after the promise resolves, etc.

[domenic]

Any of appHistory.transition.finished.then(updateFocus), appHistory.back().then(updateFocus) or appHistory.addEventListener("navigatesuccess", updateFocus) would work; they have the same timing.

If you wanted to update focus even on failure then you'd do appHistory.transition.finished.finally(updateFocus) or appHistory.back().finally(updateFocus). For the event version you'd add handlers for both navigatesuccess and navigateerror.

You could also integrate it into your specific application logic, e.g.

appHistory.addEventListener("navigate", e => {
  e.transitionWhile((async () => {
    await updateDOMWithSkeleton();
    findElement().focus();
    await updateTheRestOfTheDOM();
  })());
});

I'll mention the basics here in the PR.

[tbondwilkinson]

Do we really want to cancel scroll behavior if the user scrolls during the transition? I feel like the current behavior in a multi-page application is to disregard user scrolls while the page is navigating?

[dvoytenko]

I'd tend to agree: user scroll should be ignored. But this rule could apply to manual calls to window.scrollTo and similar APIs.

[domenic]

The Chromium engineers pointed me to code which abandons scroll restoration (for MPA navs) when the user scrolls. I will do some black-box testing to confirm.

[domenic]

Here is an example:

1. Open https://neat-equal-cent.glitch.me/, preferably in a vertically-small-ish window
2. Wait for, e.g., paragraph 50 to load, and scroll down to it
3. Click the example.com link
4. Click back. Do not touch anything.
5. After paragraph 50 loads, scroll position will be restored.

Then try it this way:

4. Click back. Once a scrollbar appears, scroll slightly.
5. Even after paragraph 50 loads, your scroll position will not be disturbed. You having scrolled will have changed how it works.

[tbondwilkinson]

This is equivalent to calling restoreScroll immediately though, right?

[domenic]

Yep.

[tbondwilkinson]

Would anyone want this? Sounds dubious.

[domenic]

Well, that's why it's in the unclear-utility section :).

[tbondwilkinson]

I'm wondering about how there's no ability to influence WHERE the browser scrolls. This just provides an API for WHEN the browser restores scroll position. is that correct?

[domenic]

Right. You can use window.scrollTo() + scrollRestoration: "manual" for manual scrolling. I can mention that...

[dvoytenko]

IMHO heuristics with (1) the input object instance (if it wasn't removed from DOM), and (2) ID should be a good start. Are there any other similar restoration rules, e.g. from the current BFCache heuristics? Maybe also include an input's name? ID are often autogenerated, but names are usually logical.

[domenic]

For bfcache there aren't any heuristics; the entire DOM is still around in the same state it used to be.

I'm not aware of any real precedence for trying to capture something interesting about the current state of the page in a way that survives arbitrary author DOM mutations... We could try to invent it, but I'd punt it to the future-additions section for now.

[dvoytenko]

I'm wondering if we're going down the manual route, should we just leave it to the app to restore scroll manually? e.restoreScroll() is otherwise useful because an app doesn't have to save an old scroll position manually. But would this make API excessively complicated?

[domenic]

I'm hopeful e.restoreScroll() is doable without much work, so I kept it in the explainer as an MVP feature. It's true we could omit it though without any compat issues, so it might get deprioritized if other things come up or if we find out that it's not as easy to implement as I'd hoped.

[dvoytenko]

If we have this API, I think we can drop e.restoreScroll() for manual mode.

[domenic]

Offline feedback is that it might vary depending on navigation. So we still have lots of options to choose from in how to resolve conflicts...

I think I'd prefer to tie this to transitionWhile(). So the alternatives are:

• Throw on mismatches
• Last wins
• First wins
• Something more complicated

I think throwing is too painful for people who want to have multiple uncoordinated transitionWhile() handlers; see #94 for the background there. Although it should be rare and might not work perfectly, it shouldn't be almost-always-broken.

So I'm going to propose two alternatives:

1. Last wins

2. More-complicated version

   In the more-complicated version, transitionWhile(..., { focusReset: "after-transition" }) is not equivalent to transitionWhile(..., { focusReset: undefined }) or transitionWhile(...). So we have three possibilities: "after-transition", "manual", and undefined. The rule is then the last non-undefined value wins.

   The intent here is that if we have multiple people calling transitionWhile(), ones that don't explicitly set focusReset don't impact the outcome, even if they were called after cases that did set it.

I'll spec last-wins for now but am very open to feedback as to whether the more-complicated version, or first wins, would be better.

[domenic]

Going to split the spec work out into its own PR so I can keep noodling, and then we can point people to the actual README for the current plans.