Merge pull request w3c#4377 from jihyerish/modify-spatnavsearch

[css-nav-1] Modify spatialNavigationSearch API with `inside` attribute

Author: Jihye Hong

css-nav-1/Overview.bs

@@ -535,19 +535,20 @@ the User Agent must run the steps described below:
 </div>
 
 <div algorithm="spatialNavigationSearch steps">
-:   <dfn method for=Element lt="spatialNavigationSearch(options)">spatialNavigationSearch(<var>options</var>)</dfn>
+:   <dfn method for=Element lt="spatialNavigationSearch(options)">spatialNavigationSearch(<var>dir</var>, <var>options</var>)</dfn>
 ::
-    1. Let <var>direction</var> be the value of {{SpatialNavigationSearchOptions/dir}} attribute of <var>options</var>.
-    2.
-        * If the value of {{SpatialNavigationSearchOptions/candidates}} attribute of <var>options</var> is not <code>null</code>,
-            then let <var>areas</var> be the that value
-        * else,
-            1.
-                * If the value of {{SpatialNavigationSearchOptions/container}} attribute of <var>options</var> is not <code>null</code>,
-                    let <var>container</var> be that value
-                * else, let <var>container</var> be the element's nearest <a>spatial navigation container</a> ancestor.
-            2. Let <var>areas</var> be the result of <a>finding focusable areas</a> within <var>container</var>.
-    3. Return the result of <a>selecting the best candidate</a> within <var>areas</var> in direction <var>direction</var> from the element.
+    1. Let <var>direction</var> be the value of <var>dir</var>.
+    2. Let <var>container</var> be the the value of {{SpatialNavigationSearchOptions/container}} attribute of <var>options</var>
+        if it is not <code>null</code>, the element's nearest <a>spatial navigation container</a> ancestor otherwise.
+    3. Let <var>areas</var> be the value of {{SpatialNavigationSearchOptions/candidates}} attribute of <var>options</var>
+        if it is not <code>null</code>, result of <a>finding focusable areas</a> within <var>container</var> otherwise.
+    4. Let <var>insideFirst</var> be the value of {{SpatialNavigationSearchOptions/inside}} attribute of <var>options</var>
+        if it is not <code>null</code>, <code>false</code> otherwise.
+    5. If <var>insideFirst</var> is <code>true</code>,
+        then let <var>bestCandidate</var> be the result of <a>selecting the best candidate</a> within element with <var>direction</var>.
+        * If <var>bestCandidate</var> is not <code>null</code>, return <var>bestCandidate</var>. 
+        * Else, fall back to the next step.
+    6. Return the result of <a>selecting the best candidate</a> within <var>areas</var> in <var>direction</var> 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
@@ -564,7 +565,7 @@ and the result will be <code>null</code>.</em>
     recursively.
 
     <pre><code highlight=javascript>
-    document.addEventListener('navbeforefocus', function(e) {
+    document.addEventListener('navbeforefocus', e => {
         e.preventDefault();
 
         let target = e.relatedTarget;
@@ -573,10 +574,7 @@ and the result will be <code>null</code>.</em>
 
             if (areas.length === 0) { break; }
 
-            target = target.spatialNavigationSearch({
-                dir:  e.dir,
-                candidates: areas
-            });
+            target = target.spatialNavigationSearch(e.dir, { candidates: areas });
         }
         target.focus();
     });
@@ -596,7 +594,7 @@ and the result will be <code>null</code>.</em>
     or programmatic calls to {{focus()}}…
 
     <pre><code highlight=javascript>
-    document.addEventListener('navnotarget', function(e) {
+    document.addEventListener('navnotarget', e => {
         e.preventDefault();
 
         const container = e.relatedTarget;
@@ -618,17 +616,44 @@ and the result will be <code>null</code>.</em>
                     break;
             }
         } else {
-            const target = container.spatialNavigationSearch({
-                dir: e.dir,
-                candidates: areas
-            });
+            const target = container.spatialNavigationSearch(e.dir, { candidates: areas });
             target.focus();
         }
     });
     </code></pre>
 </div>
 </div>
 
+<div class=example id=searchInside>
+    This example shows different results of {{Element/spatialNavigationSearch()}}
+    depending on the value of {{SpatialNavigationSearchOptions/inside}} attribute.
+
+    When the page has the code snippet as below,
+
+    <pre><code highlight=markup>
+    &lt;body>
+        &lt;div id="container" style="width:300px; height:200px; overflow-y: scroll;">
+            &lt;button id="button1" style = "width:50px; height:50px;">&lt;/button>
+        &lt;/div>
+        &lt;button id="button2" style = "width:50px; height:50px;">&lt;/button>
+    &lt;/body>
+    </code></pre>
+
+    <pre><code highlight=javascript>
+        const container = document.getElementById('container');
+
+        const innerBtn = container.spatialNavigationSearch('down', {inside: true});
+        const outerBtn = container.spatialNavigationSearch('down');
+    </code></pre>
+
+    <code>innerBtn</code> is assigned to the element whose {{Element/id}} matches with <code>'button1'</code>
+    because the {{SpatialNavigationSearchOptions/inside}} attribute is <code>true</code>.
+    But if the authors don't specify {{SpatialNavigationSearchOptions/inside}} attribute,
+    <code>false</code> is given to it by default. 
+    Therefore <code>outerBtn</code> is assigned to the element with {{Element/id}} <code>'button2'</code>
+    which is outside of <code>container</code>.
+</div>
+
 <div class=api>
 <h2 id="events-navigationevent">
 Navigation Events</h2>
@@ -998,8 +1023,8 @@ To run the <dfn>spatial navigation steps</dfn> in <var>direction</var>, do the f
                 <span class=cssapi>* Else if the computed value of the 'spatial-navigation-action' property on <var>eventTarget</var> is not ''spatial-navigation-action/focus''
                  and <var>eventTarget</var> <a>can be manually scrolled</a>,
                  then <a>directionally scroll the element</a> <var>eventTarget</var> in <var>direction</var> and return.</span>
-            * Else, fallback to the next step.
-    * Else, fallback to the next step.
+            * Else, fall back to the next step.
+    * Else, fall back to the next step.
 5. Let <var>container</var> be the nearest ancestor of <var>eventTarget</var> that is a <a>spatial navigation container</a>.
 6. <i>Loop</i>: Let <var>candidates</var> be the result of <a>finding focusable areas</a>
     within <var>container</var>