Add the spatial-navigation-action CSS Property

- Add the description of spatial-navigation-action CSS Property
- Add an example of the property

Author: Jihye Hong

css-nav-1/Overview.bs

@@ -1250,6 +1250,84 @@ Note: the 'spatial-navigation-contain' property is <a>at-risk</a>.
 
 </div>
 
+<h3 id=container>
+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>spatial navigation focus 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 viewport.
+        When there isn't any visible candidate, then the container scrolls.
+
+    <dt><dfn>focus</dfn>
+    <dd>If the element is a <a>scroll container</a>,
+        then directional input moves the focus to the candidates(visible or not). The user cannot manually scroll the container.
+
+    NOTE: If the 'focus' value is given to 'spatial-navigation-action', 'navnotarget' event occurs 
+    when there isn’t any visible candidate in the spatial navigation container no matter what it can be scrolled more or not.
+
+    <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, there is an element which is out of the view within the scrollable element.
+Pressing the down arrow key moves the focus directly to it without scrolling mannually.
+
+    <pre><code highlight=markup>
+        &lt;div class = 'scroller'>
+            &lt;button class = 'item'>&lt;/button>
+            &lt;button class = 'item'>&lt;/button>
+            &lt;button class = 'item'>&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;
+        }
+    </code></pre>
+    <pre><code highlight=js>
+        let container = document.getElementById('feed');
+        let currentTarget = document.activeElement;
+
+        container.addEventListener('navnotarget', function(e) {
+            let nextFocus = currentTarget.spatialNavigationSearch({
+                                                dir:  e.dir,
+                                                candidates: this.focusableAreas({'mode': 'all'}),
+                                                container: this
+                                            });
+            
+            nextFocus.scrollIntoView();
+            nextFocus.focus({preventScroll:true});
+        });
+    </code></pre>
+
+</div>
+
 <h2 class=no-num id=scrolling>Appendix A. Scroll extensions</h2>
 
 This section proposes a few extensions to CSS