Navigation API (formerly app history API)

[domenic]

Braw mornin' TAG!

I'm requesting a TAG review of the proposed navigation API.

The web's existing history API is problematic for a number of reasons, which makes it hard to use for web applications. This proposal introduces a new API encompassing navigation and history traversal, which is more directly usable by web application developers. Its scope is: initiating navigations, intercepting navigations, and history introspection and mutation.

This new window.navigation API layers on top of the existing API and specification infrastructure, with well-defined interaction points. The main differences are that it is scoped to the current origin and frame, it has a different flow for implementing single-page app navigations, and it is designed to be pleasant to use instead of being a historical accident with many sharp edges.

• Explainer¹ (minimally containing user needs and example code): https://github.com/WICG/navigation-api/blob/main/README.md
• Specification URL: https://wicg.github.io/navigation-api/
• Tests: https://github.com/web-platform-tests/wpt/tree/master/app-history (being renamed)
• User research: this is mostly a developer-facing feature, but it draws upon some preexisting user research on the accessibility questions
• Security and Privacy self-review²: https://github.com/WICG/navigation-api/blob/main/security-privacy-questionnaire.md
• GitHub repo (if you prefer feedback filed there): https://github.com/WICG/navigation-api/
• Primary contacts (and their relationship to the specification):
  • Domenic Denicola (@domenic), Google, editor
• Organization(s)/project(s) driving the specification: Google
• Key pieces of existing multi-stakeholder review or discussion of this specification: the issue tracker is full of discussion with web developers and with Mozilla engineers. See also https://github.com/mozilla/standards-positions/issues/543 .
• External status/issue trackers for this specification (publicly visible, e.g. Chrome Status): https://chromestatus.com/feature/6232287446302720

Further details:

• [x] I have reviewed the TAG's Web Platform Design Principles
• Relevant time constraints or deadlines: we are hoping to send out an Intent to Ship before April 14, 2022
• The group where the work on this specification is currently being done: WICG
• The group where standardization of this work is intended to be done (if current group is a community group or other incubation venue): WHATWG (HTML Standard)
• Major unresolved issues with or opposition to this specification: no major issues. Some minor issues in https://github.com/WICG/navigation-api/milestone/1 which I am setting up a working session with Mozilla to nail down.
• This work is being funded by: Google

You should also know that...

This was previously reviewed in https://github.com/w3ctag/design-reviews/issues/605. Based on TAG and Mozilla feedback, we had a renaming discussion in https://github.com/WICG/app-history/issues/83 which led to the new "navigation API" (and window.navigation) name.

We'd prefer the TAG provide feedback as (please delete all but the desired option):

🐛 open issues in our GitHub repo for each point of feedback

[hadleybeeman]

Linking to our previous review on App history API

[domenic]

Just leaving a quick note here about an upcoming breaking change we're making. I don't think it needs a separate TAG review but it might be interesting for the group: https://github.com/WICG/navigation-api/pull/235

[torgo]

Hi Domenic - sorry this took so long. We've been reviewing and have had the chance to discuss on today's call. Some feedback from that session: In general we're happy with this API. We appreciate the care taken in the security & privacy considations section. One question I had was about how this impacts the behaviour of the back button - it wasn't exactly clear what you mean by "when iframes are involved" here. Can you spell it out a bit more clearly? Is this to do with the iframe's navigation history being integrated with the parent document's history? And what is the changed UI you anticipate? Generally we have positive feedback. This looks like it will be an improvement over the current state of the platform. We're planning to finish the review and close next week.

[domenic]

Thanks for the feedback, and I'm glad to hear you all feel it's an improvement!

One question I had was about how this impacts the behaviour of the back button - it wasn't exactly clear what you mean by "when iframes are involved" here. Can you spell it out a bit more clearly? Is this to do with the iframe's navigation history being integrated with the parent document's history?

This is spelled out in a bit more detail in https://github.com/WICG/navigation-api/blob/main/README.md#correspondence-with-the-joint-session-history . It is indeed about how the iframe's navigation history is integrated with the parent document's history, and how that makes programs harder to reason about even if it can give a better user experience.

That integration remains true for the back button and thus for the user's experience. It also remains true for the classic history API's history.back(), history.go(), etc.

The new feature of the navigation API is that if you use it, then the developer only has to deal with their own frame's history. I.e. instead of how the classic history API has you traverse through the all-inclusive history entry list, with the navigation API you get separate history entry lists for each frame. The section I linked above has specific examples, including what this means for navigation.back() behaving differently than history.back().

However, implementing the navigation API does not imply any UI changes, or changes in the behavior of the back button.

I hope this helps, and am happy to clarify more. Other relevant sections:

• https://github.com/WICG/navigation-api/blob/main/README.md#impact-on-the-back-button-and-user-agent-ui
• https://github.com/WICG/navigation-api/blob/main/README.md#warning-backforward-are-not-always-opposites
• https://github.com/whatwg/html/issues/6501

[cynthia]

Thanks a lot for the clarification! If the frame is first-party and the content author would like to delegate history down (to the frame) and then back up, how would that work? Obviously this is a bit of an edge case, so mostly asking out of curiosity.

Regardless of an answer to that question, we are very happy to see this proposal move forward.

[domenic]

I'm not sure what you mean by "delegate history"; could you expand on that?

[cynthia]

Ah, so the question was how to get the parent document's navigation stack needs to cooperate with a frame's navigation stack - I wasn't sure by looking at the proposal.

That said, we can take this offline as we are happy whether or not that question is answered. Thank you for bringing this to our attention!