Change selectSpatNavBestCandidate into spatNavSearch

Improve the arguments it takes while we're at it.

This closes w3c#20 and w3c#30

This relates to w3c#37 as well.

Author: frivoal

index.bs

@@ -638,16 +638,17 @@ dictionary FocusableAreasOptions {
     FocusableAreaSearchMode mode;
 };
 
-dictionary SelectSpatNavBestCandidateOptions {
+dictionary SpatNavSearchOptions {
     required SpatialNavigationDirection dir;
-    required sequence<Node> candidates;
+    sequence<Node>? candidates;
+    Node? container;
 };
 
 partial interface Element {
     Node getSpatnavContainer();
     sequence<Node> focusableAreas(optional FocusableAreasOptions arg);
-    Node? selectSpatNavBestCandidate(SelectSpatNavBestCandidateOptions arg);
-    Node? sequentialNavSearch(SequentialNavigationDirection dir);
+    Node? spatNavSearch(SpatNavSearchOptions arg);
+    Node? seqNavSearch(SequentialNavigationDirection dir);
 };
 </pre>
 
@@ -669,29 +670,26 @@ The {{Element/focusableAreas()}} method must follow these steps:
 
 </div>
 
-<div algorithm="selectSpatNavBestCandidate steps">
-The {{Element/selectSpatNavBestCandidate()}} method must follow these steps:
-1. Let <var>d</var> be the argument's {{SelectSpatNavBestCandidateOptions/dir}} attribute
-2. Let <var>candidates</var> be the argument's {{SelectSpatNavBestCandidateOptions/candidates}} attribute.
-3. Let <var>areas</var> be a <a for=list>clone</a> of <var>candidates</var>,
-    with every item replaced by its <a>focusable area</a> if that is distinct from itself.
+<div algorithm="spatNavSearch steps">
+The {{Element/spatNavSearch()}} method must follow these steps:
+1. Let <var>d</var> be the argument's {{SpatNavSearchOptions/dir}} attribute
+2. If the argument's {{SpatNavSearchOptions/candidates}} attribute is not <code>null</code>,
+    then let <var>areas</var> be that atribute,
+    else, let <var>areas</var> be the result of <a>finding focusable areas</a>
+    within the argument's {{SpatNavSearchOptions/container}} attribute is not <code>null</code>,
+    or the element's nearest <a>spatnav container</a> ancestor
 4. Return the result of <a>selecting the best candidate</a> within <var>areas</var> in direction <var>d</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
+<a>spatnav container</a> ancestor.
+<strong>If none are found, this does not climb further up the ancestry chain,
+and the result will be <code>null</code>.</strong>
 </div>
 
-Issue(20): Does {{SelectSpatNavBestCandidateOptions/candidates}} need to be required?
-Is there a way to know the best candidate just with the direction argument?
-(e.g. elm.selectSpatNavBestCandidate("right");)
-It seems that such a shortcut would be convenient,
-but it may also be confusing:
-Would this be expected to search only within the innermost spatnav container,
-or to reproduce the full logic of running the <a>spatial navigation steps</a>,
-and if so, does that include scrolling, or a special return value to indicate
-that scrolling would have happened?
-Maybe we need a separate method for that.
-
-<div algorithm="sequentialNavSearch steps">
-The {{Element/sequentialNavSearch()}} method must follow these steps:
+
+<div algorithm="seqNavSearch steps">
+The {{Element/seqNavSearch()}} method must follow these steps:
 1. Let <var>d</var> be the argument
 2. Let <var>s</var> be <code>sequential</code> if the element is a <a for="/">browsing context</a>
     or if the element is in its <a>control group</a>'s <a>sequential focus navigation order</a>;
@@ -700,7 +698,6 @@ The {{Element/sequentialNavSearch()}} method must follow these steps:
     <var>d</var> as its direction argument,
     and <var>s</var> as the selection mechanism argument.
 
-
 </div>
 
 <h2 id=processing-model>