Merge pull request w3c#2 from jihyerish/first-draft

frivoal · web-flow · commit c1b783553c80 · 2018-01-01T12:13:15.000+09:00
Add the description about focus navigation heuristic
diff --git a/index.bs b/index.bs
@@ -36,7 +36,7 @@ Activating Spatial Navigation: the 'arrow-key-behavior' property</h2>
 
 Historically, most browsers have not offered features to let users move the focus directionally.
 Some, such as TV browsers, have controlled spatial navigation using the arrow keys out of necessity,
-since no other input mechanism is available on a typical TV remove control.
+since no other input mechanism is available on a typical TV remote control.
 
 Others, have enabled different key combinations to control spatial navigation,
 such as pressing the <code class=key>SHIFT</code> key together with arrow keys.
@@ -49,7 +49,7 @@ such as scrolling.
 The 'arrow-key-behavior' property enables an author to declare
 that their document, or part of their document,
 has been authored with spatial navigation in mind,
-and the UA can bind the arrow keys to spatial navigation
+and the User Agent can bind the arrow keys to spatial navigation
 without risk of interfering with other behavior.
 
 <pre class='propdef'>
@@ -74,11 +74,11 @@ Does that depend on whether the selection is collapsed or not?
 <dl dfn-for=arrow-key-behavior>
 	<dt><dfn>auto</dfn>
 	<dd>The User Agent defines which keys,
-	if any, 
-	control spatial navigation.
+	if any, control spatial navigation.
 
 	On devices such as TVs which do not have any pointing input device
-	and which also lack a <code class=key>Tab</code> key to control sequential navigation,
+	and which also lack a <code class=key>Tab</code> key to control
+	<a herf="https://html.spec.whatwg.org/multipage/interaction.html#sequential-focus-navigation">sequential focus navigation</a>,
 	it is recommended that arrow keys be used for that purpose without any modifier key.
 	On devices with a full keyboard,
 	the User Agent may use a combination of arrow keys with a modifier key.
@@ -159,10 +159,71 @@ the sequence is as follows:
 <h3 id=heuristic>
 Focus Navigation Heuristic</h3>
 
-The <dfn>focus navigation heuristic</dfn> determines which element should be focused next
+The <dfn>focus navigation heuristic</dfn> runs these steps:
+
+1. Select the initially focused element.
+
+    1. If there is a previously focused element, it is the initially focused element.
+    2. Otherwise, among all the focusable areas, the element on the topmost and the leftmost in the
+current level of browsing context is the initially focused element.
+
+2. Let the initially focused element be the currently focused element.
+
+3. Move focus to the currently focused element.
+
+4. Get the direction of the spatial navigation.
+
+5. Find the candidate elements.
+
+    Note: The element which is overlapped by the focused element is also the candidate element.
+
+    1. If the up arrow key or the down arrow key is pressed, <var>axis A</var> is Y. Otherwise, the left
+arrow key or the right arrow key is pressed, <var>axis A</var> is X.
+    2. If the right arrow key or the down arrow key is pressed, <var>direction D</var> is positive.
+Otherwise, the left arrow key or the up arrow key is pressed, <var>direction D</var> is negative.
+    3. Find the candidate elements which satisfy the conditions below:
+      * The element should be focusable.
+      * The element should be visible within the viewport.
+      * The position of the center point of the element should be greater than that of the currently focused
+element in <var>direction D</var> on <var>axis A</var>.
+      * The position value of the edge in the navigation direction of the element should be greater than
+that of the currently focused element in <var>direction D</var> on <var>axis A</var>.
+
+6. Find the next focused element.
+
+    1. Find the combination of the vertex on the currently focused element and the vertex on the
+candidate element which makes the shortest distance between two vertices.
+
+        * Select <var>vertex V1</var> from the currently focused element.
+        * Select <var>vertex V2</var> from the candidate element.
+
+
+    2. Calculate the distance between <var>vertex V1</var> and <var>vertex V2</var> for each candidate
+element.
+        The Distance function is:
+
+        <dfn>distance</dfn> = <var>A</var> + <var>B</var> + <var>C</var> - <var>D</var></code>
+
+        Note: This refers to the <a href="https://www.w3.org/TR/WICD/#focus-handling">old WICD Spec</a>
+
+        <var>A</var> : The euclidian distance between <var>vertex V1</var> and <var>vertex V2</var>.
+
+        <var>B</var> : The absolute distance in the navigation direction between <var>vertex V1</var> and
+<var>vertex V2</var>.
+
+        <var>C</var> : The absolute distance in the direction which is orthogonal to the navigation
+direction between <var>vertex V1</var> and <var>vertex V2</var>.
+
+        <var>D</var> : The square root of the overlapped area between the candidate element and the
+currently focused element.
+
+    3. Select the element which distance is the least among the candidate elements.
+
+7. Move focus to the next focused element.
+
+The <a>focus navigation heuristic</a> determines which element should be focused next
 when the user invokes either spatial or sequential navigation.
 
 Issue: Add the details. Link to HTML for the logic on sequential navigation.
 
 </div>
-
diff --git a/index.html b/index.html
@@ -1176,9 +1176,8 @@
 		}
 	}
 </style>
-  <meta content="Bikeshed version b43bcf8d18510de03d8b56c5e878eea93e955427" name="generator">
+  <meta content="Bikeshed version bbd6a9c4064dd454886bb3e0c74f0a19865c3c74" name="generator">
   <link href="http://wicg.github.io/spatial-navigation" rel="canonical">
-  <meta content="2654c96167fa9d0e5432f1b722d6d4d9a934a5ed" name="document-revision">
 <style>/* style-md-lists */
 
 /* This is a weird hack for me not yet following the commonmark spec
@@ -1425,13 +1424,12 @@
   <div class="head">
    <p data-fill-with="logo"></p>
    <h1 class="p-name no-ref" id="title">Spatial Navigation</h1>
-   <h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Editor’s Draft, <time class="dt-updated" datetime="2017-12-21">21 December 2017</time></span></h2>
+   <h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Editor’s Draft, <time class="dt-updated" datetime="2017-12-25">25 December 2017</time></span></h2>
    <div data-fill-with="spec-metadata">
     <dl>
      <dt>This version:
      <dd><a class="u-url" href="http://wicg.github.io/spatial-navigation">http://wicg.github.io/spatial-navigation</a>
      <dt>Issue Tracking:
-     <dd><a href="https://github.com/frivoal/spatial-navigation/issues/">GitHub</a>
      <dd><a href="#issues-index">Inline In Spec</a>
      <dt class="editor">Editors:
      <dd class="editor p-author h-card vcard"><a class="p-name fn u-email email" href="mailto:jh.hong@lge.com">Jihye Hong</a> (<span class="p-org org">LG Electronics</span>)
@@ -1510,7 +1508,7 @@ <h2 class="heading settled" data-level="1" id="intro"><span class="secno">1. </s
    <h2 class="heading settled" data-level="2" id="activation"><span class="secno">2. </span><span class="content"> Activating Spatial Navigation: the <a class="property" data-link-type="propdesc" href="#propdef-arrow-key-behavior" id="ref-for-propdef-arrow-key-behavior">arrow-key-behavior</a> property</span><a class="self-link" href="#activation"></a></h2>
    <p>Historically, most browsers have not offered features to let users move the focus directionally.
 Some, such as TV browsers, have controlled spatial navigation using the arrow keys out of necessity,
-since no other input mechanism is available on a typical TV remove control.</p>
+since no other input mechanism is available on a typical TV remote control.</p>
    <p>Others, have enabled different key combinations to control spatial navigation,
 such as pressing the <code class="key">SHIFT</code> key together with arrow keys.</p>
    <p>While arrow keys are well suited for this,
@@ -1520,7 +1518,7 @@ <h2 class="heading settled" data-level="2" id="activation"><span class="secno">2
    <p>The <a class="property" data-link-type="propdesc" href="#propdef-arrow-key-behavior" id="ref-for-propdef-arrow-key-behavior①">arrow-key-behavior</a> property enables an author to declare
 that their document, or part of their document,
 has been authored with spatial navigation in mind,
-and the UA can bind the arrow keys to spatial navigation
+and the User Agent can bind the arrow keys to spatial navigation
 without risk of interfering with other behavior.</p>
    <table class="def propdef" data-link-for-hint="arrow-key-behavior">
     <tbody>
@@ -1567,10 +1565,9 @@ <h2 class="heading settled" data-level="2" id="activation"><span class="secno">2
     <dt><dfn data-dfn-for="arrow-key-behavior" data-dfn-type="dfn" data-noexport="" id="arrow-key-behavior-auto">auto<a class="self-link" href="#arrow-key-behavior-auto"></a></dfn> 
     <dd>
      The User Agent defines which keys,
-	if any, 
-	control spatial navigation. 
+	if any, control spatial navigation. 
      <p>On devices such as TVs which do not have any pointing input device
-	and which also lack a <code class="key">Tab</code> key to control sequential navigation,
+	and which also lack a <code class="key">Tab</code> key to control <a data-link-type="dfn" herf="https://html.spec.whatwg.org/multipage/interaction.html#sequential-focus-navigation" href="https://html.spec.whatwg.org/multipage/interaction.html#sequential-focus-navigation" id="ref-for-sequential-focus-navigation">sequential focus navigation</a>,
 	it is recommended that arrow keys be used for that purpose without any modifier key.
 	On devices with a full keyboard,
 	the User Agent may use a combination of arrow keys with a modifier key.</p>
@@ -1641,7 +1638,79 @@ <h3 class="heading settled" data-level="4.1" id="events"><span class="secno">4.1
      </ul>
    </ul>
    <h3 class="heading settled" data-level="4.2" id="heuristic"><span class="secno">4.2. </span><span class="content"> Focus Navigation Heuristic</span><a class="self-link" href="#heuristic"></a></h3>
-   <p>The <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport="" id="focus-navigation-heuristic">focus navigation heuristic</dfn> determines which element should be focused next
+   <p>The <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport="" id="focus-navigation-heuristic">focus navigation heuristic</dfn> runs these steps:</p>
+   <ol>
+    <li data-md="">
+     <p>Select the initially focused element.</p>
+     <ol>
+      <li data-md="">
+       <p>If there is a previously focused element, it is the initially focused element.</p>
+      <li data-md="">
+       <p>Otherwise, among all the focusable areas, the element on the topmost and the leftmost in the
+current level of browsing context is the initially focused element.</p>
+     </ol>
+    <li data-md="">
+     <p>Let the initially focused element be the currently focused element.</p>
+    <li data-md="">
+     <p>Move focus to the currently focused element.</p>
+    <li data-md="">
+     <p>Get the direction of the spatial navigation.</p>
+    <li data-md="">
+     <p>Find the candidate elements.</p>
+     <p class="note" role="note"><span>Note:</span> The element which is overlapped by the focused element is also the candidate element.</p>
+     <ol>
+      <li data-md="">
+       <p>If the up arrow key or the down arrow key is pressed, <var>axis A</var> is Y. Otherwise, the left
+arrow key or the right arrow key is pressed, <var>axis A</var> is X.</p>
+      <li data-md="">
+       <p>If the right arrow key or the down arrow key is pressed, <var>direction D</var> is positive.
+Otherwise, the left arrow key or the up arrow key is pressed, <var>direction D</var> is negative.</p>
+      <li data-md="">
+       <p>Find the candidate elements which satisfy the conditions below:</p>
+       <ul>
+        <li data-md="">
+         <p>The element should be focusable.</p>
+        <li data-md="">
+         <p>The element should be visible within the viewport.</p>
+        <li data-md="">
+         <p>The position of the center point of the element should be greater than that of the currently focused
+element in <var>direction D</var> on <var>axis A</var>.</p>
+        <li data-md="">
+         <p>The position value of the edge in the navigation direction of the element should be greater than
+that of the currently focused element in <var>direction D</var> on <var>axis A</var>.</p>
+       </ul>
+     </ol>
+    <li data-md="">
+     <p>Find the next focused element.</p>
+     <ol>
+      <li data-md="">
+       <p>Find the combination of the vertex on the currently focused element and the vertex on the
+candidate element which makes the shortest distance between two vertices.</p>
+       <ul>
+        <li data-md="">
+         <p>Select <var>vertex V1</var> from the currently focused element.</p>
+        <li data-md="">
+         <p>Select <var>vertex V2</var> from the candidate element.</p>
+       </ul>
+      <li data-md="">
+       <p>Calculate the distance between <var>vertex V1</var> and <var>vertex V2</var> for each candidate
+element.
+The Distance function is:</p>
+       <p><dfn data-dfn-type="dfn" data-noexport="" id="distance">distance<a class="self-link" href="#distance"></a></dfn> = <var>A</var> + <var>B</var> + <var>C</var> - <var>D</var></p>
+       <p class="note" role="note"><span>Note:</span> This refers to the <a href="https://www.w3.org/TR/WICD/#focus-handling">old WICD Spec</a></p>
+       <p><var>A</var> : The euclidian distance between <var>vertex V1</var> and <var>vertex V2</var>.</p>
+       <p><var>B</var> : The absolute distance in the navigation direction between <var>vertex V1</var> and <var>vertex V2</var>.</p>
+       <p><var>C</var> : The absolute distance in the direction which is orthogonal to the navigation
+direction between <var>vertex V1</var> and <var>vertex V2</var>.</p>
+       <p><var>D</var> : The square root of the overlapped area between the candidate element and the
+currently focused element.</p>
+      <li data-md="">
+       <p>Select the element which distance is the least among the candidate elements.</p>
+     </ol>
+    <li data-md="">
+     <p>Move focus to the next focused element.</p>
+   </ol>
+   <p>The <a data-link-type="dfn" href="#focus-navigation-heuristic" id="ref-for-focus-navigation-heuristic②">focus navigation heuristic</a> determines which element should be focused next
 when the user invokes either spatial or sequential navigation.</p>
    <p class="issue" id="issue-3eba2d0c"><a class="self-link" href="#issue-3eba2d0c"></a> Add the details. Link to HTML for the logic on sequential navigation.</p>
   </main>
@@ -1803,6 +1872,7 @@ <h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="c
      <li><a href="#dom-focusnavigationevent-dir">attribute for FocusNavigationEvent</a><span>, in §3</span>
      <li><a href="#dom-focusnavigationeventinit-dir">dict-member for FocusNavigationEventInit</a><span>, in §3</span>
     </ul>
+   <li><a href="#distance">distance</a><span>, in §4.2</span>
    <li><a href="#dom-navigationdirection-down">down</a><span>, in §3</span>
    <li><a href="#dom-navigationdirection-down">"down"</a><span>, in §3</span>
    <li><a href="#dom-element-findfocusable">findFocusable(arg)</a><span>, in §3</span>
@@ -1844,6 +1914,11 @@ <h3 class="no-num no-ref heading settled" id="index-defined-elsewhere"><span cla
      <li><a href="https://dom.spec.whatwg.org/#element">Element</a>
      <li><a href="https://dom.spec.whatwg.org/#eventtarget">EventTarget</a>
     </ul>
+   <li>
+    <a data-link-type="biblio">[HTML]</a> defines the following terms:
+    <ul>
+     <li><a href="https://html.spec.whatwg.org/multipage/interaction.html#sequential-focus-navigation">sequential focus navigation</a>
+    </ul>
    <li>
     <a data-link-type="biblio">[uievents]</a> defines the following terms:
     <ul>
@@ -1863,6 +1938,8 @@ <h3 class="no-num no-ref heading settled" id="normative"><span class="content">N
    <dd>Tab Atkins Jr.; Elika Etemad. <a href="https://www.w3.org/TR/css-values-3/">CSS Values and Units Module Level 3</a>. 29 September 2016. CR. URL: <a href="https://www.w3.org/TR/css-values-3/">https://www.w3.org/TR/css-values-3/</a>
    <dt id="biblio-dom">[DOM]
    <dd>Anne van Kesteren. <a href="https://dom.spec.whatwg.org/">DOM Standard</a>. Living Standard. URL: <a href="https://dom.spec.whatwg.org/">https://dom.spec.whatwg.org/</a>
+   <dt id="biblio-html">[HTML]
+   <dd>Anne van Kesteren; et al. <a href="https://html.spec.whatwg.org/multipage/">HTML Standard</a>. Living Standard. URL: <a href="https://html.spec.whatwg.org/multipage/">https://html.spec.whatwg.org/multipage/</a>
    <dt id="biblio-rfc2119">[RFC2119]
    <dd>S. Bradner. <a href="https://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>. March 1997. Best Current Practice. URL: <a href="https://tools.ietf.org/html/rfc2119">https://tools.ietf.org/html/rfc2119</a>
    <dt id="biblio-uievents">[UIEVENTS]
@@ -2039,6 +2116,8 @@ <h2 class="no-num no-ref heading settled" id="issues-index"><span class="content
 Controlling Spatial Navigation in JavaScript</a>
     <li><a href="#ref-for-focus-navigation-heuristic①">4.1. 
 Event Sequence</a>
+    <li><a href="#ref-for-focus-navigation-heuristic②">4.2. 
+Focus Navigation Heuristic</a>
    </ul>
   </aside>
 <script>/* script-dfn-panel */
