same-document vs cross-document requests needs a clearer definition

[matt-buland-sfdc]

Perhaps I'm lacking some external background information on what decides whether a request is same vs cross-document, but I think this proposal could use a clear definition, as it contributes to the expectations during certain flows. Is it determined just by the nature of the request?

Some examples...

• Is an anchor to /foo is by default a cross-document request because it normally reloads the document?
• How would an app server with multiple SPAs describe what is/is-not a cross-document request? e.g. suppose /foo, /bar, and /foo/baz are separate SPAs with different documents -- the logic for what can be captured in the same document becomes less clear, and must be defined by the application logic, yet somehow the navigate event is able to know about this configuration? How?
• I think we need a list of elements/APIs that trigger a navigate -- <a> and <form> are described, but is that it?

[domenic]

Thanks for filing this! I've gotten similar feedback before, and I think this is just an issue where the concept is very clear to implementer/spec people like myself and not at all clear to web developers, so I need some help explaining it.

Any navigation that would normally result in a new Document object is what I call "cross-document". I believe the only "same-document" navigations are: fragment navigations, history.pushState()/appHistory.pushNewEntry(), and history.replaceState()/appHistory.updateCurrentEntry(). So indeed:

Is an anchor to /foo is by default a cross-document request because it normally reloads the document?

Yes. The old Document object is different than the new Document object.

How would an app server with multiple SPAs describe what is/is-not a cross-document request? e.g. suppose /foo, /bar, and /foo/baz are separate SPAs with different documents -- the logic for what can be captured in the same document becomes less clear, and must be defined by the application logic, yet somehow the navigate event is able to know about this configuration? How?

The concept of same-document vs. cross-document isn't supposed to capture anything app-specific. App-specific logic still needs to be programming in the app, e.g. by inspecting e.destinationEntry.url.

I think we need a list of elements/APIs that trigger a navigate -- <a> and <form> are described, but is that it?

If you add <area> (which is basically like <a>), then that's it for elements. (Although, these can be triggered in a variety of ways, e.g. <form> navigations are indirectly triggered via <button>s or <input type=submit> or formEl.submit(), and <a> navigations can be triggered via aEl.click().)

Other APIs that trigger navigations are:

• location setter, location.href setter, a ton of other location setters, location.replace(), location.assign(), location.reload()
• history.back(), history.forward(), history.go()
• history.replaceState(), history.pushState()
• App history methods

I think this is exhaustive, but I'll get a better sense once I start working on a formal spec.

[matt-buland-sfdc]

If you could take your description here of when something is cross-document, and apply it to the definition on when sameDocument is true here: https://github.com/slightlyoff/history_api/blob/master/app_history.md#the-current-entry-and-single-page-navigations I think it would become more clear, and may better prepare this doc for the formal spec.

Perhaps an example could be drafted on how an application may decide how to intercept cross-document requests and turn them into a same-document request (specifically by validating that it should indeed be intended for the current SPA, based on what the router supports), but I wonder if detailed examples like that should be shown in another way, like a repo of common recipes, or router-specific recipes that integrate with this API, etc.

The APIs you list seem reasonable to me. Thanks for the clarification!

[domenic]

I've moved the discussion about clarifying "cross-document" and "same-document" to WICG/navigation-api#3, and will close this issue as we consolidate around that repo :).

Regarding examples, recipes, and framework integrations, I definitely agree we need that sort of thing. Probably we should avoid the explainer getting too long, so a separate document or maybe samples/ directory would be good. It's also a bit tricky to create such samples without an implementation to test against, so I expect we'll be putting together more once a prototype is being worked on.