Name

[annevk]

I'm somewhat hesitant to raise this bikeshed, but #82 (comment) made me think it. Should it be named appHistory?

Perhaps appSession would reflect things a tiny bit better? (I guess the one potential confusing thing here is that it's not 1:1 with sessionStorage, but appHistory is not 1:1 with history either.)

[domenic]

Yeah, app history is more of a "least bad" name. The predecessor proposal was called "navigator" and lived on window.history.navigator, but I thought that was pretty confusing.

"Session" seems like it might be the right spec-level concept to encompass "history and navigation", but it feels like the wrong web-dev-facing concept. When web devs talk about "sessions" it's mostly about user sessions, being logged in and out, etc., and not about history and navigation.

Between "history" and "navigation" I think most of the complexity (for web developers) comes in with history, so that's why I went with window.appHistory instead of window.appNavigator or window.historyAndNavigation or something. That does lead to confusion like #82 (comment) but that seems like an OK-ish price...

I'm happy to leave this open in case we come up with something brilliant. But my instincts are to stick with the inertia behind the current name, despite it not being perfect.

[kidwm]

How about window.navigator.navigation or window.navigator.history?

[kenchris]

navigationHistory? navigationStack?

[tbondwilkinson]

• appSession: For me this is confusing, because it doesn't necessarily indicate it has to do with history or navigation or the URL, which are things that I think of when I think of this API.
• window.navigator.navigation and window.navigator.history: I'm shaking my fist at the folks who got to navigator, because I think it has more to do with the User Agent than "navigation." But given that the existing window.navigator has little to do with navigation or history, I don't think it's right to hang this new API off that object.
• navigationHistory: I think this is largely equivalent to appHistory, but not better.
• navigationStack: People have quibbled about whether history is in fact a 'stack' (technically from a data structure POV, it's not), so I think I'd like to get away from this nomenclature.

[kenchris]

in appHistory, I am not sure what value "app" provides :-) at least "navigation history" provides a bit more clarification

[tbondwilkinson]

Well, I suppose the "app" part is signifying to importance of same-origin history for this API - most of the new functionality has to do with enabling an "app" to inspect and modify its own history. So I'm not totally opposed to "app" being in the name.

But I do agree that if I had to pick one word to represent all this, it would be "navigation". Navigation to me represents the action that the API enables, "history" represents the state left behind by that action.

Not to throw another wrench, but other good words: "page", "view," "site". For instance, pageHistory (or pageNavigation), as opposed to appHistory, if no one likes the word app.

[Yay295]

In that case it would be siteHistory, not pageHistory. A website can be composed of many webpages.

[uasan]

Better - window.navigator.router

[domenic]

@jakearchibald, @annevk, @smaug---- and I discussed this today. @smaug---- especially was of the opinion that this API is largely about navigation, and less so history. We tentatively thought that maybe just the name window.navigation (and spec title "Navigation API") would work:

await navigation.navigate(url);

const entries = navigation.entries();
const currentEntry = navigation.current; // or currentEntry? or now?

await navigation.transition.finished;

await navigation.back();
await navigation.goTo(key);

This seems pretty OK to me. What do other folks think?

[frehner]

I like it.

Are there any chances of library/global conflicts? I tried doing some searching to see if anything puts navigation onto global/window but at first glance couldn't find anything.

[domenic]

It's always hard to say, but generally on the web platform we haven't had many such conflicts. (The only one I'm aware of is when TC39 tried to introduce global, resulting in the current globalThis name.) We could also minimize the risk by making the global [Replaceable].

[bathos]

Navigation is not a bad name, though it seem a lot more natural to call the-stateful-thing-you-call-navigate-on navigator, which — oh, wait, it seems that’s taken? perhaps this is not such a good name. :)

Can’t say I would look forward much to mistyping and misreading this all the time, and I’m a native speaker, so it may be more troublesome for others. AppHistory seemed fine to me — FWIW, the moment I saw that name, I knew what it was gonna be about, though I couldn’t nec explain why?

Of course this won’t make or break it but I do hope folks land on anything-but-navigation (because of navigator I mean — it seems fine conceptually).

(ActualNavigator?)

[Yay295]

Unfortunately, I agree that "Navigation" may be too similar to the existing Navigator object (which ironically doesn't seem to have much to do with navigating). Perhaps "ApplicationState"?

[uasan]

Maybe - window.navigator.app?

[jakearchibald]

I'd be happy with navigation or just nav. But in case we need another option:

Aside from just being better in a number of ways, there are two restrictions appHistory has vs history:

• The exposed history is for the current frame only
• The exposed history is limited to the current origin, contiguously

Based on that, there still isn't a name that jumps out at me, but here goes:

• frameHistory/frameNav/frameNavigation - since the history is related to the frame. But, maybe frame sounds old and horrible, and it isn't clear that the top level is also a frame of sorts?
• navigableHistory/navHistory - Assuming 'navigable' is a term we land on for "a thing that can be navigated".
• originHistory - Although this doesn't make it clear that entries are limited to this navigable.

[bathos]

Spitballing in case one of these clicks with people or, more likely, serves as a prompt.

• Traverser
• Traveller
• BrowserNav
• BrowserTimeline
• Annals
• Herstory
• Historiographer
• Ziggy

To be safe I’m not gonna make any claim about which of these are jokes and which I actually think are potentially good. If you hate them all, then they’re all jokes :)

[bathos]

Placing this on the radar if it’s not already: the currently unqualified/unprefixed use of "navigate"/"nav" in global interface, operation, and event names in CSS Spatial Navigation proposal.

w3c/csswg-drafts#3387 (comment)

[domenic]

Hey everyone,

After a half-year with no particularly better ideas, and a bit more offline discussion with @annevk and @smaug----, we think window.navigation is the best name on offer. This API really is about navigation, which encompasses history. All the other alternatives, e.g. variants on "history" or "traversal", fail to capture this scope.

The way in which the name starts with the same seven characters as navigator is unfortunate, but we think it'll be survivable.

This issue will remain open to track renaming everything (which will be fun 😬).

[domenic]

I'm working on a draft spec PR, but I want to get some any feedback on the details of the rename as early as possible.

Noticeable developer-visible renames

• window.appHistory → window.navigation
• appHistory.current → navigation.currentEntry
  • currentchange event → currententrychange event
  • updateCurrent() → updateCurrentEntry()
• appHistory.goTo() → navigation.traverseTo()

Class name changes

These are mostly not developer-impacting in mainstream code scenarios, but can impact e.g. feature detection. So we can make them longer and uglier if we want.

We should avoid changing them after shipping.

• AppHistory → Navigation
• AppHistoryTransition → NavigationTransition
• AppHistoryEntry → NavigationHistoryEntry
• AppHistoryCurrentChangeEvent → NavigationCurrentEntryChangeEvent
• AppHistoryNavigateEvent → NavigateEvent
• AppHistoryDestination → NavigationDestination

Not-exposed IDL name changes

These names, for dictionaries and enums, are not something developers have any interaction with, and the only concern is clarity and avoiding collisions within the spec ecosystem. We can change them at any time.

• AppHistoryUpdateCurrentOptions → NavigationUpdateCurrentEntryOptions
• AppHistoryNavigationOptions → NavigationOptions
• AppHistoryNavigateOptions → NavigationNavigateOptions
• AppHistoryReloadOptions → NavigationReloadOptions
• AppHistoryResult → NavigationResult
• AppHistoryNavigationType → NavigationNavigationType (I would like this to be NavigationType; depends on Rename NavigationType to NavigationTimingType w3c/navigation-timing#172)

[frehner]

AppHistoryEntry → HistoryEntry
AppHistoryCurrentChangeEvent → CurrentHistoryEntryChangeEvent

It seems a little strange to me that these don't have the word navigation in them and everything else developer-facing does. I also like the idea of having navigation in the name to help direct people what it's associated with.

AppHistoryUpdateCurrentOptions → UpdateCurrentHistoryEntryOptions
AppHistoryReloadOptions → ReloadOptions

Same here for these two, but maybe not as important because they're not dev-facing.

[domenic]

Yeah, fair point, let me do some updates...