From d5de186dc4ce56ec2ca56f3d7d7825fb681e32d1 Mon Sep 17 00:00:00 2001 From: Jihye Hong Date: Mon, 15 Oct 2018 11:07:00 +0900 Subject: [PATCH 1/4] No more using "spatnav" abbreviation The abbreviation "spatnav" may be confusing. Therefore, drop "spatnav" and use - "spatial navigation" in the text - "spatialNavigation" or "fooSpatialNavigation" for the APIs --- README.md | 20 +++--- explainer.md | 19 +++--- index.bs | 71 +++++++++++---------- index.html | 171 +++++++++++++++++++++++++-------------------------- 4 files changed, 139 insertions(+), 142 deletions(-) diff --git a/README.md b/README.md index a46c1f7c645..c5c492c2091 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ This is a repository for making the Web excellently embrace the spatial navigati * Give feedback on [issues](https://github.com/WICG/spatial-navigation/issues) or via [email](mailto://lgewst@gmail.com) ## Overview -**Spatial navigation (aka Spatnav)** is the ability to navigate between focusable elements based on their position within a structured document. Spatial navigation is often called 'directional navigation' which enables four(4) directional navigation. Users are usually familiar with the 2-way navigation using tab key for the forward direction and shift+tab key for the backward direction, but not familiar with the 4-way navigation using arrow keys. +**Spatial navigation** is the ability to navigate between focusable elements based on their position within a structured document. Spatial navigation is often called 'directional navigation' which enables four(4) directional navigation. Users are usually familiar with the 2-way navigation using tab key for the forward direction and shift+tab key for the backward direction, but not familiar with the 4-way navigation using arrow keys. Regarding TV remote control, game console pad, IVI jog dial with 4-way keys, and Web accessibility, the spatial navigation has been a rising important input mechanism in several industries. If the Web can embrace the spatial navigation and efficiently support the functionalities in Web engines and W3C APIs, it will be more promising technology for existing products as mentioned above and various upcoming smart devices. @@ -20,33 +20,33 @@ Prior to the mission explanation, we need to understand how the arrow keys work In spatial navigation mode, the default behavior of arrow keys is changed from scrolling behavior to focus moving so that users can use the arrow keys to navigate between focusable elements based on their position. To support the functionalities of the spatial navigation, we should consider the following three steps: 1. A heuristic algorithm for the spatial navigation supported in Web engines 2. Overriding methods on top of the heuristic algorithm (DOM method/attribute/event) -3. The relevant API for efficiently supporting the spatial navigation (spatnav mode, container, etc.) +3. The relevant API for efficiently supporting the spatial navigation (Setting the spatial navigation container, etc.) See the [explainer](explainer.md) for the details of W3C standardization for #1, #2 and #3 above. See the [implStatus](implStatus.md) for the details of the implementation in Web engines for #2 above. ## FAQ -**Q. I’m not sure how the Spatnav (directional) navigation works.** -- You can see the video that shows the Spatnav operations in the YouTube page ([link](https://www.youtube.com/watch?v=TzDtcX9urUg)). -- You can see the brief description for the Spatnav in Wikipedia ([link](https://en.wikipedia.org/wiki/Spatial_navigation)). -- In several references below, you can get the help to understand the Spatnav operations well. +**Q. I’m not sure how the spatial navigation works.** +- You can see the video that shows the spatial navigation operations in the YouTube page ([link](https://www.youtube.com/watch?v=TzDtcX9urUg)). +- You can see the brief description for the spatial navigation in Wikipedia ([link](https://en.wikipedia.org/wiki/Spatial_navigation)). +- In several references below, you can get the help to understand the spatial navigation operations well. **Q. Isn’t it enough just using the relevant Web frameworks?** -- Several Web frameworks and extensions for the Spatnav have been provided so far due to no support from web engines. For examples, [js-spatial-navigation](https://github.com/luke-chang/js-spatial-navigation) made by Mozilla seems one of the frameworks and its quality would be good to support the features of Spatnav. [Spotlight library](https://github.com/enyojs/spotlight) implemented by LGE is also an instance of the frameworks for the Spatnav, even though it was deprecated now. However, the support of Spatnav from Web frameworks has some limits as follows: +- Several Web frameworks and extensions for the spatial navigation have been provided so far due to no support from web engines. For examples, [js-spatial-navigation](https://github.com/luke-chang/js-spatial-navigation) made by Mozilla seems one of the frameworks and its quality would be good to support the features of the spatial navigation. [Spotlight library](https://github.com/enyojs/spotlight) implemented by LGE is also an instance of the frameworks for the spatial navigation, even though it was deprecated now. However, the support of spatial navigation from Web frameworks has some limits as follows: - Difficult to align native scroll behavior when moving the focus to an element out of view - Difficult to align native focus method for a11y support - Performance degradation due to the expensive cost of DOM Access - Inconsistency of user experience (various kinds of frameworks) - Impossible to control isolated frames like iframe and shadow DOM -**Q. The Spatnav seems not the general feature esp. in mobile with no physical key-based interface.** -- Honestly, the mobile has been a first citizen of Spatnav about ten years old. Before touch-based interface, the majority of interface for mobile was the key-based interface. We're familiar with kind of mobile phone named a feature phone, and it has been supported in several developing countries such as South America, Africa even until now. +**Q. The spatial navigation seems not the general feature esp. in mobile with no physical key-based interface.** +- Honestly, the mobile has been a first citizen of the spatial navigation about ten years old. Before touch-based interface, the majority of interface for mobile was the key-based interface. We're familiar with kind of mobile phone named a feature phone, and it has been supported in several developing countries such as South America, Africa even until now. - In the future, the input mechanism for smart devices will change to something like voice command, hand gesture, and gaze direction, but the key-based interface will never disappear, even though it'll be used as a secondary method. The key-based interface used to be evaluated as one of the most intuitive ways with a strong sense feedback of finger after pushing a key, while we couldn't imagine a touch-based keyboard without any physical keys. **Q. Put any question on [issues](https://github.com/WICG/spatial-navigation/issues) of this repository :D** -- Everything for Spatnav is welcome! +- Everything for the spatial navigation is welcome! ## Reference - JavaScript Spatial Navigation (Mozilla) diff --git a/explainer.md b/explainer.md index 2e6248a73a9..f431eea1cd1 100644 --- a/explainer.md +++ b/explainer.md @@ -8,8 +8,7 @@ since no other input mechanism is available on a typical TV remote control. Others, have enabled different key combinations to control spatial navigation, such as pressing the Shift key together with arrow keys. -This ability to move around the page directionally is called spatial navigation -(or spatnav for short). +This ability to move around the page directionally is called spatial navigation. An [experimental Polyfill](./polyfill/) is available. @@ -110,7 +109,7 @@ and especially on devices such as TVs which also lack a Tab key to sequential focus navigation, User Agents should make spatial navigation active. -We deliberately do not define which keys or key combination are meant to trigger spatnav, +We deliberately do not define which keys or key combination are meant to trigger the spatial navigation, nor whether it is on by default or not. These are choices that are best left to the user and the User Agent. This is discussed in greater detail in Issue 35 @@ -171,13 +170,13 @@ the specification exposes Javascript APIs and Events that enable authors to inte #### JS APIs -* getSpatnavContainer() +* getSpatialNavigationContainer() - Returns the spatial navigation focus container of an element. * focusableAreas() - Returns all focusable elements within a spatial navigation focus container. -* spatNavSearch() +* spatialNavigationSearch() - Runs the spatial navigation step and returns the best candidate which will gain the focus. #### Navigation Events @@ -209,7 +208,7 @@ document.addEventListener("navbeforescroll", function(e) { if (areas.length == 0)) { return; } e.preventDefault(); - var t = e.target.spatNavSearch({ + var t = e.target.spatialNavigationSearch({ dir: e.dir, candidates: areas }); @@ -280,11 +279,11 @@ You could achieve the same effect by wrapping the table in a div and using the overflow property on the div to make it scrollable, but that has side effects you probably do not want. -### Maybe authors could create "spatnav containers" with JavaScript instead? Could they listen for spat nav events to cancel (=preventDefault) the navigation? Such an event could give authors even more freedom: they might wanna grab the event and manually put focus somewhere else (to override the spatnav's default choice). Would such event allow authors to "patch" the default algorithm in a more flexible way? +### Maybe authors could create "spatial navigation containers" with JavaScript instead? Could they listen for spat nav events to cancel (=preventDefault) the navigation? Such an event could give authors even more freedom: they might wanna grab the event and manually put focus somewhere else (to override the default choice of the spatial navigation). Would such event allow authors to "patch" the default algorithm in a more flexible way? Yes, they absolutely could. We have prepared the spec with an event model that lets js authors take control, -and override the default spatnav also to do anything they like. +and override the default spatial navigation also to do anything they like. That could indeed be used to manually create spatial navigation containers other than documents or scrollers. We had various idea for other controls to influence what gets the focus, @@ -293,7 +292,7 @@ and we decided to leave these out because they could indeed be left to JS and be added later with declarative syntax if there was strong demand. However, we still included this property, because: -1. This is trivial to add to the spec (and presumably, to implementations as well), since the concept of looking for a container and searching for focusable things inside it is built-in into the spatnav logic, and we're merely exposing a hook to add additional containers +1. This is trivial to add to the spec (and presumably, to implementations as well), since the concept of looking for a container and searching for focusable things inside it is built-in into the spatial navigation logic, and we're merely exposing a hook to add additional containers 2. Recreating that logic in JS if you're fine with everything else could be quite fiddly 3. It seems like a fairly basic need @@ -305,7 +304,7 @@ We initially wanted to make it automatic for limiting the number of things autho The primary concern was that this involved a particularly expensive form of hit testing that is not used anywhere else on the platform. The secondary reason was that people already need to get the same thing right for sequential navigation, so reinforcing the message was judged useful. -### How can we move the focus inside a spatnav container? +### How can we move the focus inside a spatial navigation container? There is possible to have nested focusable elements in a web page. The most typical case for this is an ordinary focusable element (button, link, etc) is inside a scroller, as the scroller is also focusable. If the currently focused element is the scroller, how can we reach the element inside the scroller with key pressing? diff --git a/index.bs b/index.bs index bdcc8ab9ca6..843792e5965 100644 --- a/index.bs +++ b/index.bs @@ -10,7 +10,7 @@ Editor: Jihye Hong, LG Electronics, jh.hong@lge.com Editor: Florian Rivoal, Invited Expert, https://florian.rivoal.net Abstract: This specification defines a general model for navigating the focus using the arrow keys, as well as related CSS and JavaScript features. -At risk: {{getSpatnavContainer()}} +At risk: {{getSpatialNavigationContainer()}} At risk: {{focusableAreas()}} At risk: 'spatial-navigation-contain' @@ -96,8 +96,7 @@ since no other input mechanism is available on a typical TV remote control. Others, have enabled different key combinations to control spatial navigation, such as pressing the Shift key together with arrow keys. -This ability to move around the page directionally is called spatial navigation -(or spatnav for short). +This ability to move around the page directionally is called spatial navigation. Spatial navigation can be useful for a web page built using a grid-like layout, or other predominantly non linear layouts. @@ -432,16 +431,16 @@ dictionary FocusableAreasOptions { FocusableAreaSearchMode mode; }; -dictionary SpatNavSearchOptions { +dictionary SpatialNavigationSearchOptions { required SpatialNavigationDirection dir; sequence<Node>? candidates; Node? container; }; partial interface Element { - Node getSpatnavContainer(); + Node getSpatialNavigationContainer(); sequence<Node> focusableAreas(optional FocusableAreasOptions arg); - Node? spatNavSearch(SpatNavSearchOptions arg); + Node? spatialNavigationSearch(SpatialNavigationSearchOptions arg); }; @@ -449,13 +448,13 @@ Note: The way the direction is expressed allows us to expand to more than 4-way later of if this is found necessary. More directional keywords or a numerical angle could be added. -Note: the {{focusableAreas()}} and {{getSpatnavContainer()}} methods are at-risk. +Note: the {{focusableAreas()}} and {{getSpatialNavigationContainer()}} methods are at-risk. -
-The {{Element/getSpatnavContainer()}} method must follow these steps: -1. Return the element if it is a spatnav container, - or the nearest ancestor of the element that is a spatnav container, - or the document if the nearest spatnav container is the viewport. +
+The {{Element/getSpatialNavigationContainer()}} method must follow these steps: +1. Return the element if it is a spatial navigation container, + or the nearest ancestor of the element that is a spatial navigation container, + or the document if the nearest spatial navigation container is the viewport.
@@ -471,19 +470,19 @@ The {{Element/focusableAreas()}} method must follow these steps:
-
-The {{Element/spatNavSearch()}} method must follow these steps: -1. Let d be the argument's {{SpatNavSearchOptions/dir}} attribute -2. If the argument's {{SpatNavSearchOptions/candidates}} attribute is not null, +
+The {{Element/spatialNavigationSearch()}} method must follow these steps: +1. Let d be the argument's {{SpatialNavigationSearchOptions/dir}} attribute +2. If the argument's {{SpatialNavigationSearchOptions/candidates}} attribute is not null, then let areas be that attribute, else, let areas be the result of finding focusable areas - within the argument's {{SpatNavSearchOptions/container}} attribute is not null, - or the element's nearest spatnav container ancestor + within the argument's {{SpatialNavigationSearchOptions/container}} attribute is not null, + or the element's nearest spatial navigation container ancestor 4. Return the result of selecting the best candidate within areas in direction d from the element Note: When neither a container nor a list of candidates is provided, this only searches through the visible focusable areas of the nearest -spatnav container ancestor. +spatial navigation container ancestor. If none are found, this does not climb further up the ancestry chain, and the result will be null.
@@ -502,7 +501,7 @@ and the result will be null. if (areas.length === 0) { return; } e.preventDefault(); - var t = e.target.spatNavSearch({ + var t = e.target.spatialNavigationSearch({ dir: e.dir, candidates: areas }); @@ -526,12 +525,12 @@ and the result will be null. } var t = e.relatedTarget; - while (t.isSameNode(t.getSpatnavContainer())) { + while (t.isSameNode(t.getSpatialNavigationContainer())) { var areas = t.focusableAreas(); if (areas.length === 0) { break; } - t = t.spatNavSearch({ + t = t.spatialNavigationSearch({ dir: e.dir, candidates: areas }); @@ -543,9 +542,9 @@ and the result will be null.
The following code changes the behavior of spatial navigation - to trap the focus within a spatnav container: + to trap the focus within a spatial navigation container: when no further focusable elements can be found in the requested direcition - and the spatnav container cannot be scrolled any futher, + and the spatial navigation container cannot be scrolled any futher, we loop back to the other side instead of searching outside of it, either by focusing or scrolling depending on what is available. @@ -576,7 +575,7 @@ and the result will be null. break; } } else { - var t = c.spatNavSearch({ + var t = c.spatialNavigationSearch({ dir: e.dir, candidates: areas }); @@ -803,10 +802,10 @@ The navbeforescroll event occurs before spatial navigation triggers navnotarget The navnotarget event occurs before going up the tree to search candidates in the -nearest ancestor spatnav container when spatial navigation has failed to find any candidate -within the current spatnav container. +nearest ancestor spatial navigation container when spatial navigation has failed to find any candidate +within the current spatial navigation container. -If the spatnav container is scrollable, the event occurs when there isn't any candidate in it +If the spatial navigation container is scrollable, the event occurs when there isn't any candidate in it and it cannot be scrolled at the same time. @@ -827,7 +826,7 @@ and it cannot be scrolled at the same time.
Attributes of the event
{{NavigationEvent}}.{{NavigationEvent/relatedTarget}} -
The spatnav container that was searched in. +
The spatial navigation container that was searched in.
{{NavigationEvent}}.{{NavigationEvent/dir}}
The direction of the navigation as requested by the user @@ -973,16 +972,16 @@ from a local logical grouping, only looking for focusable elements outside of the grouping if a suitable one cannot be found inside it (see [[#nav]] for details). -Such groupings are called spatial navigation focus containers (or spatnav containers for short). +Such groupings are called spatial navigation focus containers. -By default, spatnav containers are established by: +By default, spatial navigation containers are established by: * The viewport of a browsing context (not limited to the top-level browsing context) * scroll containers
-Additional spatnav containers can be created using the 'spatial-navigation-contain' property (see [[#container]]). +Additional spatial navigation containers can be created using the 'spatial-navigation-contain' property (see [[#container]]).

-Creating additional spatnav containers: the 'spatial-navigation-contain' property

+Creating additional spatial navigation containers: the 'spatial-navigation-contain' property 
 Name: spatial-navigation-contain
diff --git a/index.html b/index.html
index 0b560cc08db..859b3d31d47 100644
--- a/index.html
+++ b/index.html
@@ -1212,9 +1212,8 @@
 		}
 	}
 
-  
+  
   
-