[css-nav-1] Improve the name of window.navigate

[frivoal]

---

Migrated from WICG/spatial-navigation#120
Originally created by @frivoal on Wed, 17 Oct 2018 05:21:10 GMT

---

Previously in #70, we discussed whether window.navigate() was a great name for this API or not. It seems like it could be confused with navigating to a new URL, so some better name would be good.

However, no suggestion so far seems to work:

• focusNavigate() or other names invoking focus are wrong, because it can also scroll things instead of focusing them
• directionalNavigate() or spatialNavigate() or similar are also problematic, because this method should be possible to extend to sequential navigation by passing it a "prev" or "next" argument, and that does not work with such names.

So, leaving this issue open to see if we can do better.

[frivoal]

---

Migrated from WICG/spatial-navigation#120 (comment)
Originally created by @hugoholgersson on Tue, 30 Oct 2018 15:36:17 GMT

---

stepFocusOrScroll

[zcorpan]

directionalNavigate() or spatialNavigate() or similar are also problematic, because this method should be possible to extend to sequential navigation by passing it a "prev" or "next" argument, and that does not work with such names.

Maybe the spatial navigation starting point (and/or sequential focus navigation starting point) should be exposed as an object that is a subclass of Range, that has methods to navigate like prev() next() up() right() etc. And then you can get the current spatial navigation starting point with an attribute on window (if that is the appropriate place to put it?).

spatialNavigationStartingPoing.up();
sequentialFocusStartingPoint.next();
// or same object for both?

I don't know if there are use cases for getting the Range without invoking the other methods, though.

[AmeliaBR]

I agree that "navigate" is problematic, because of its potential for confusion with Navigator and URL navigation.

The problem extends beyond this particular property to all the interface names. E.g. NavigationEvent sounds to me like something that should be triggered when the user clicks a URL. Adding adjectives doesn't seem to simplify things, especially when you want this to be a very generic framework for directional or sequential movement of focus or viewport.

Throwing out some potential names (forgive me if these have previously been discussed & discarded):

• view or contentView (con: view already has plenty of meanings in the web platform which are similar but not the same)

• browse (con: although the word is not used in web platform APIs, it could still be confused with browsing to a different URL)

• explore (pro: name implies that you are looking around the content that is already loaded; name not already used in the web platform; con: "Windows Explorer" and "Internet Explorer" might interfere with SEO)

I like "explore". You're exploring the page. You can explore to the left, you can explore up or down, but you can also explore next or previous items in a list. You can explore only focusable items, or all content. For other API names, exploration could replace spatialNavigation, e.g., ExplorationEvent, getExplorationContainer() or ExplorationDirection.

[jihyerish]

@zcorpan @AmeliaBR Thank you for your opinions!

spatial navigation starting point (and/or sequential focus navigation starting point) should be exposed as an object that is a subclass of Range

Interesting idea! Exposing spatial navigation starting point (and/or sequential focus navigation starting point) as an object may be useful because sometimes those aren't the same with document.activeElement.

However, window.navigate() intends to provide a way to simulate spatial navigation simple for the author.
So, I wonder if there is a more intuitive way to do this than using spatial navigation starting point object.

etc. And then you can get the current spatial navigation starting point with an attribute on window (if that is the appropriate place to put it?).

I have thought the similar thing about this!
I'm thinking about SpatialNavigation object which can be referenced as an attribute of the Window interface.
The SpatialNavigation object provides an interface for manipulating spatial navigation.
When we have this, window.navigate() may be changed to
window.SpatialNavigation.explore(dir) or window.SpatialNavigation.browse(dir).
(Thank you @AmeliaBR for the potential names!)

What do you think about this idea? (+ @frivoal)

I agree that "navigate" is problematic, because of its potential for confusion with Navigator and URL navigation.

Indeed.

Throwing out some potential names (forgive me if these have previously been discussed & discarded):

I also like explore among the candidates.
But I'm bit worried about omitting the meaning of "directional" navigation.

[frivoal]

@zcorpan using the staring point as the object from which this hangs seems like a good idea but I'm less sure about replacing function_name("up") with up(). If we have single function with parameters for doing this, it makes it trivial in the future to extent to more than 4 directions. Not only can we add the two sequential ones, but we can also have the 8 directions a game controler's d-pad typically has, or even start taking an arbitrary angle. Without a function name, this extensibility is lost.

[hugoholgersson]

... makes it trivial in the future to extent to more than 4 directions.

For implementors, I guess it would be the same effort?

I prefer an API that's Easy To Use And Hard To Misuse (EUHM). It is possible to misspell a string.

Also, with an explicit function for each direction, authors could easily check if a direction is supported (check if the function exists) before calling it?

[zcorpan]

I disagree that the extensibility is lost. We can always add more methods, and if something requires an argument (like angle), that can also still be done with a new method.

I think there are two advantages of using multiple methods over a single method:

• developer ergonomics (up() is less typing than function_name("up")
• easier to feature-check specific APIs (as @hugoholgersson said above)

[bathos]

I think window.navigate() is unshippable, the collision is major. Likewise NavigationEvent.

Other existing or proposed APIs have seemingly been pretty consistent about using unqualified “navigate” to refer to the HTML definition of navigate, with unqualified “navigator” referring to the agent (or ... something along those lines anyway, but it’s intelligible as “the thing that navigates” in the prior sense).

• interface Navigator
• interface NavigatorManagedData
• interface NavigatorUAData
• interface NavigationPreloadManager
• interface PerformanceNavigationTiming

The collision gets a lot uglier with AppHistory on the horizon exposing interaction with HTML’s “navigate” through an evented API:

• interface AppHistoryNavigateEvent
• event type "navigate"
• event type "navigatesuccess"
• event type "navigateerror"
• event type "navigateto"
• event type "navigatefrom"
• operation navigate()

It’s not great to squat on generic terms for specific concepts. (Seems like there is agreement about that here already overall.) The AppHistory API is an example that avoids the “terminology manspreading” problem by using a consistent prefix for global contstructs (and the events don’t fire on window/document). I think the word “navigate” does make sense here, but it should likely be consistently qualified as spatial navigation (e.g. SpatialNavigationEvent).

[jihyerish]

@bathos , Thank you for listing up the issues and discussion related to "navigate"!
I needed more feedback about the naming here, for spatial navigation.
And I'm open to change the name such as "navigate" to "spatialNavigate"

[ncallaway]

I like the idea of putting a separate SpatialNavigation object on window, which could then expose its own interface for navigation. I think that dramatically reduces the ambiguity of what is going to happen with I interact with it (as opposed to navigate().

For the navigation function name itself, I'd like to suggest move() as another option for the function name. I think this is short and memorable, distinct from the ambiguity of navigate().

Something like window.SpatialNavigation.move("up") feels like it conveys the developer intent pretty clearly