Some lower-level navigate options?

[jakearchibald]

I was thinking about a few ways navigations can happen, and maybe we want to expose those as options?

replace is currently a boolean, but it feels like it needs to be three states. So, how about entryPlacement:

• "add" - Creates a new history entry and adds it to the timeline, clearing forward history.
• "replace" - Creates a new history entry and replaces the current item in the timeline.
• "auto" - What browsers do now, where it depends on the current URL and the target URL.

Also nextDocument:

• "new" - Forces the creation of a new document for the new history entry.
• "reuse-current" - Reuses the current document for the new history entry.
• "auto" - What browsers do now, where it depends on the target URL.

And fragmentScroll:

• "prevent" - will not scroll to fragment.
• "force" - will scroll to fragment if there's a match.
• "auto" - will not scroll if the URL is different to the current URL, and the document is reused. Otherwise scrolls.

appHistory.navigate(url, {
  fragmentScroll: 'prevent',
  nextDocument: 'reuse-current',
});

The above would be similar to pushState, and it would reject if the url is another origin.

appHistory.navigate(location.href, {
  entryPlacement: 'add'
});

Creates a new entry with the same URL. This isn't something you can do right now without redirect tricks.

[Yay295]

I'm not entirely sure on this, but aren't there situations where nextDocument: 'reuse-current' would still have to create a new document, depending on the URL being navigated to?

[jakearchibald]

Yeah, it would need to reject if the url is to another origin, just as pushState does.

[domenic]

It's important to keep in mind that our goal with app history is not to provide a primitive that allows any possible navigation. It's to provide an API which guides people along a very specific path for building single-page apps.

For the replace question, I agree that three states is one possible avenue. That's #111.

I don't think nextDocument is a good idea. We want to guide people down a specific path, which is:

• Do a "normal" navigation by default, i.e. same-document for fragments, otherwise cross-document.
• If you want to convert a cross-document navigation into a same-document navigation, do that in a centralized router that uses the navigate event. Don't make that choice at the call site of your navigation.

Similarly, fragmentScroll is again a case where we want the navigate handler to make that decision in a centralized manner, instead of making each call site do so. I think we have enough nobs: do the normal fragment thing by default, or call event.preventDefault() if you want to handle it another way.

[jakearchibald]

Yeah, I'm happy with that. Agreed that the "expose everything" model doesn't work well here.