[css-nav-1] Clarify how the improve distance function works

Author: frivoal

css-nav-1/Overview.bs

@@ -1155,14 +1155,9 @@ run the following steps:
             whose boundary goes through the geometric center of the <var>searchOrigin</var>
             and is perpendicular to <var>dir</var>.
         2. For each <var>candidate</var> in <var>candidates</var>,
-            1. If the <var>searchOrigin</var> is an element, then find the points <var>P1</var> inside the <a>boundary box</a>
-                of <var>searchOrigin</var> and P2 inside the boundary box of <var>candidate</var>.
-            2. Else if the <var>searchOrigin</var> is a point, then let the point <var>P1</var> be the <var>searchOrigin</var>
-                and find the point <var>P2</var> inside the <a>boundary box</a>.
-        3. Let <var>intersectRect</var> be an <dfn>intersecting area</dfn> between the search origin and a candidate.
-        4. Select the <var>P1</var> and <var>P2</var> that make the smallest <var>distance</var> between those two points by
-            <a>calculating the distance</a>.
-        5. Return the item of the <var>candidates</var> set that has the smallest <var>distance</var>.
+            [=find the shortest distance=] between <var>searchOrigin</var> and <var>candidate</var>
+            in direction <var>dir</var>.
+        3. Return the item of the <var>candidates</var> set that has the smallest distance.
             If several have the same distance,
             return the first one in document order,
             unless its [=boundary box=] overlaps with the [=boundary box=] of an other item at the same distance,
@@ -1172,82 +1167,95 @@ run the following steps:
 
 </div>
 
-<div algorithm="to calculate the distance">
-To <dfn lt="calculating the distance | to calculate the distance">calculate the <var>distance</var></dfn>, the function is defined as below:
+<div algorithm="to find the shortest the distance">
+To <dfn lt="find the shortest distance">to find the shortest distance</dfn>
+between a <var>reference</var> and a <var>candidate</var>
+in direction <var>dir</var>,
+find the points <var>P1</var> and <var>P2</var>,
+respectively within the boundary boxes of the <var>reference</var> and of the <var>candidate</var>,
+that minimize the <var>distance</var> as defined as below:
 
-<pre class="prod">
+<pre><code>
     <var>distance</var> = <var>euclidean</var> + <var>displacement</var> - <var>alignment</var> - <var>sqrt(Overlap)</var>
-</pre>
+</code></pre>
 
-The meaning of each factor in the function is as follows:
+The meaning of each term is as follows:
 
 <dl dfn-type="value" dfn-for="spatial-navigation-distance-function">
     <dt><var>euclidean</var>
-    <dd>The euclidean distance between <var>P1</var> and <var>P2</var>
+    <dd>
+        The euclidean distance between <var>P1</var> and <var>P2</var>
 
     <dt><var>displacement</var>
-    <dd>The degree of displacement in <var>dir</var> between <var>searchOrigin</var> and <var>candidate</var>
-    <dd>Defined as <pre class="prod">(absolute distance on the axis orthogonal to <var>dir</var> + <var>orthogonalBias</var>) * <var>orthogonalWeight</var></pre>
-
-        * <var>orthogonalBias</var>
-            * If the <var>dir</var> is {{SpatialNavigationDirection/left}} or {{SpatialNavigationDirection/right}},
-                height of <var>searchOrigin</var> / 2
-            * Else if the <var>dir</var> is {{SpatialNavigationDirection/up}} or {{SpatialNavigationDirection/down}},
-                width of <var>searchOrigin</var> / 2
+    <dd>
+        The degree of displacement in <var>dir</var> between the <var>reference</var> and the <var>candidate</var>,
+        defined as
+        <pre><code>
+            <var>displacement</var> = (absolute distance on the axis orthogonal to <var>dir</var> between <var>P1</var> and <var>P2</var> +
+                            <var>orthogonalBias</var>) *
+                           <var>orthogonalWeight</var>
+        </code></pre>
+
+    <dt><var>orthogonalBias</var>:
+    <dd>
+        * If the <var>dir</var> is {{SpatialNavigationDirection/left}} or {{SpatialNavigationDirection/right}},
+            the height of the axis-aligned bounding box of <var>reference</var> / 2
+        * Else if the <var>dir</var> is {{SpatialNavigationDirection/up}} or {{SpatialNavigationDirection/down}},
+            the width of the axis-aligned bounding box of <var>reference</var> / 2
 
-        * <var>orthogonalWeight</var>:
-            * If the <var>dir</var> is {{SpatialNavigationDirection/left}} or {{SpatialNavigationDirection/right}}, 30
-            * Else if the <var>dir</var> is {{SpatialNavigationDirection/up}} or {{SpatialNavigationDirection/down}}, 2
+    <dt><var>orthogonalWeight</var>:
+    <dd>
+        * If the <var>dir</var> is {{SpatialNavigationDirection/left}} or {{SpatialNavigationDirection/right}}, 30
+        * Else if the <var>dir</var> is {{SpatialNavigationDirection/up}} or {{SpatialNavigationDirection/down}}, 2
 
     <dt><var>alignment</var>
-    <dd>The degree of alignment in <var>dir</var> between <var>searchOrigin</var> and <var>candidate</var>
-    <dd>Defined as <pre class="prod"><var>alignBias</var> * <var>alignWeight</var></pre>
+    <dd>
+        The degree of alignment in <var>dir</var> between the <var>reference</var> and the <var>candidate</var>,
+        defined as:
+        <pre><code>
+            <var>alignment</var> = <var>alignBias</var> * <var>alignWeight</var>
+        </code></pre>
 
-        * <var>alignBias</var>
+    <dt><var>alignBias</var>:
+    <dd>
+        * If the <var>dir</var> is {{SpatialNavigationDirection/left}} or {{SpatialNavigationDirection/right}},
+            <var>projectedOverlap</var> / height of the axis-aligned bounding box of <var>candidate</var>
+        * Else if the <var>dir</var> is {{SpatialNavigationDirection/up}} or {{SpatialNavigationDirection/down}},
+            <var>projectedOverlap</var> / width of the axis-aligned bounding box of <var>candidate</var>
 
-            * If the <var>dir</var> is {{SpatialNavigationDirection/left}} or {{SpatialNavigationDirection/right}},
-                height of <var>intersectRect</var> / height of <var>candidate</var>
-            * Else if the <var>dir</var> is {{SpatialNavigationDirection/up}} or {{SpatialNavigationDirection/down}},
-                width of <var>intersectRect</var> / width of <var>candidate</var>
+    <dt><var>projectedOverlap</var>:
+    <dd>
+        * If the <var>dir</var> is {{SpatialNavigationDirection/left}} or {{SpatialNavigationDirection/right}},
+            the length of the overlap between the horizontal projections onto the vertical axis
+            of the <var>reference</var> and the <var>candidate</var>
+        * Else if the <var>dir</var> is {{SpatialNavigationDirection/up}} or {{SpatialNavigationDirection/down}},
+            the length of the overlap between the vertical projections onto the horizontal axis
+            of the <var>reference</var> and the <var>candidate</var>
 
-        * <var>alignWeight</var> is 5
+	    <figure>
+		    <img alt="" src="images/projected_overlap.png" style="width: 500px;"/>
+		    <figcaption>projectedOverlap</figcaption>
+	    </figure>
+
+    <dt><var>alignWeight</var>:
+    <dd>5
 
     <dt><var>sqrt(Overlap)</var>
-    <dd>The square root of an <a>overlapping area</a> between the <a>boundary boxes</a> of <var>searchOrigin</var> and <var>candidate</var>
-    <dd>Let <var>overlapRect</var> be
-    <var>intersectRect</var> if the <a>overlapping area</a> exists,
-    and 0 otherwise.
-    <dd>Defined as <pre class="prod">sqrt(height of <var>overlapRect</var> * width of <var>overlapRect</var>)</pre>
+    <dd>
+        The square root of area of overlap between the <var>reference</var> and the <var>candidate</var>,
+        or 0 if they do not overlap.
 </dl>
 
-NOTE: The values of <var>alignWeight</var> and <var>orthogonalWeight</var> in the function are decided based on
-        the collected <a href="https://wicg.github.io/spatial-navigation/tests/ux/list.html">UX test cases</a>.
-        It aims to show the generally expected result in the real pages.
-        Everyone is welcome to contribute to the test cases!
+Note: This general formula was picked from several plausible alternatives,
+based on which one most often match intuition
+when used to select the best candidate
+in a series of <a href="https://wicg.github.io/spatial-navigation/tests/ux/list.html">UX test cases</a>.
+Similarly, the values of <var>alignWeight</var> and <var>orthogonalWeight</var>
+were also determined experimentatlly based on the same test cases.
+The resulting forumla is somewhat complicated,
+but seems to give good answers.
+Suggestions on improvements or simplifications are welcome.
 
-<div class='example'>
-    This example shows how the <a>intersecting area</a>(<var>intersectRect</var>) is defined.
-
-    <figure>
-        <img alt="" src="images/intersecting-area-1.png" style="height: 200px;"/>
-        <figcaption>The <a>intersecting area</a> when there is the <a>overlapping area</a>.</figcaption>
-    </figure>
-
-    The figure above is the simplest case to define the <a>intersecting area</a>.
-    The <dfn>overlapping area</dfn> is the geometric overlap region between the two elements.
-    In this case, the <a>intersecting area</a> is the same as the <a>overlapping area</a> without reference to the direction of the navigation.
-
-    <figure>
-        <img alt="" src="images/intersecting-area-2.png" style="height: 200px;"/>
-        <figcaption>The <a>intersecting area</a> when the elements are aligned.</figcaption>
-    </figure>
-
-    In the case above, the search origin element and the candidate element are aligned and the requested direction is {{SpatialNavigationDirection/right}}.
-    The <a>intersecting area</a> is created with
-    (1) The gap between two elements.
-    (2) The parts of the edges from each element which are overlapped
-        when the right edge of the search origin element and the left edge of the candidate are projected to each other.
-</div>
 </div>
 
 <div class=cssapi>