Merge pull request #3732 from jihyerish/add-spatnav-action

[css-nav-1] Add spatial-navigation-action CSS Property

Author: Jihye Hong

css-nav-1/Overview.bs

@@ -1229,7 +1229,7 @@ NOTE: The values of <var>alignWeight</var> and <var>orthogonalWeight</var> in th
 <h2 id=declarative>
 Controlling spatial navigation through declarative means</h2>
 
-<h3 id=container>
+<h3 id=css-property-spatialnavigationcontain>
 Creating additional spatial navigation containers: the 'spatial-navigation-contain' property</h3>
 
 <pre class='propdef'>
@@ -1347,6 +1347,81 @@ Note: the 'spatial-navigation-contain' property is <a>at-risk</a>.
 
 </div>
 
+<h3 id=css-property-spatialnavigationaction>
+Defining the spatial navigation behavior : the 'spatial-navigation-action' property</h3>
+
+<pre class='propdef'>
+Name: spatial-navigation-action
+Value: auto | focus | scroll
+Initial: auto
+Applies to: <a>scroll container</a>
+Inherited: true
+</pre>
+
+When the user triggers spatial navigation in a given direction, the 'spatial-navigation-action' decides
+the proper spatial navigation behavior.
+
+<dl dfn-for=spatial-navigation-action dfn-type=value>
+    <dt><dfn>auto</dfn>
+    <dd>If the element is a <a>scroll container</a>,
+        then directional input moves the focus to the candidates in the optimal viewing region.
+        When there isn't any visible candidate, then the container scrolls.
+        
+        Otherwise, the focus moves to the candidates in the viewport.
+
+    <dt><dfn>focus</dfn>
+    <dd>The directional input moves the focus to all candidates inside a scroll container. The container <a>cannot be scrolled manually</a>.
+
+    NOTE: If the 'focus' value is given to 'spatial-navigation-action', 
+    <a event>navnotarget</a> event occurs when there isn’t any visible candidate in the given direction within the viewport of 
+    the <a>spatial navigation container</a> even through the container can be scrolled more.
+
+    <dt><dfn>scroll</dfn>
+    <dd>If the element is a <a>scroll container</a>,
+        then directional input only works for manually scrolling the container.
+
+    Note: The 'scroll' value is <a>at-risk</a>. 
+</dl>
+
+<div class=example>
+In this example, a scrollable container is specified with <code highlight=css>spatial-navigation-action: focus</code>.
+Inside the container, there is an element which is out of the view within a <a>scrollport</a>.
+Pressing the right arrow key moves the focus directly to it without scrolling manually.
+
+    <figure>
+        <img alt="" src="images/spatnav-action.png" style="width: 500px;"/>
+        <figcaption>Moving focus from "Box 2" to "Box 3" without manually scrolling</figcaption>
+    </figure>
+
+    <pre><code highlight=markup>
+        &lt;div class = 'scroller'>
+            &lt;button class = 'item'>Box 1&lt;/button>
+            &lt;button class = 'item'>Box 2&lt;/button>
+            &lt;button class = 'item'>Box 3&lt;/button>
+        &lt;/div>
+    </code></pre>
+    <pre><code highlight=css>
+        .scroller {
+            display: grid;
+            grid-template-columns: repeat(1, 1fr);
+            height: 300px;
+            width: 200px;
+            overflow-y: scroll;            
+            spatial-navigation-action: focus;
+        }
+        .item {
+            height: 100px;
+            width: 100px;
+            margin: 50px auto;
+            background-color: blue;
+        }
+        :focus {
+            background-color: red;
+        }
+    </code></pre>
+
+</div>
+
 <h2 class=no-num id=scrolling>Appendix A. Scroll extensions</h2>
 
 This section proposes a few extensions to CSS