Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 1, 2019
Merged

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

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d07411e
[css-nav-1] Update the spatialNavigationSearch steps with inside attr…
Sep 27, 2019
ec9ac99
[css-nav-1] Modify the sample code in examples
Sep 27, 2019
f6690c8
[css-nav-1] Add an example for spatialNavigationSearch with 'inside' …
Sep 27, 2019
ee70dd8
[css-nav-1] Tweak description of the example
Oct 1, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 49 additions & 24 deletions css-nav-1/Overview.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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;
Expand All @@ -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();
});
Expand All @@ -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;
Expand All @@ -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>
Expand Down Expand Up @@ -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>
Expand Down