[css-nav-1] Editorial and gramatical fix-ups

Author: frivoal

css-nav-1/Overview.bs

@@ -183,40 +183,36 @@ or scroll if there is no appropriate item.
 More specifically,
 the User Agent will first search for visible and focusable items
 in the direction indicated
-within the current <a>spatial navigation focus container</a>
+within the current <a>spatial navigation container</a>
 (<span class=cssapi>by default </span>the root element, scrollable elements, and iframes<span class=cssapi>,
-but other elements can be made into <a>spatial navigation focus containers</a>
+but other elements can be made into <a>spatial navigation containers</a>
 using the 'spatial-navigation-contain' property</span>).
 
 If it finds any, it will pick the best one for that direction,
 and move the focus there.
 
-If it does not, it will scroll the <a>spatial navigation focus container</a> in the requested direction
+If it does not, it will scroll the <a>spatial navigation container</a> in the requested direction
 instead of moving focus.
 Doing so may uncover focusable elements
 which would then be eligible targets to move the focus to
 next time spatial navigation in the same direction is requested.
 
-If the <a>spatial navigation focus container</a> cannot be scrolled,
+If the <a>spatial navigation container</a> cannot be scrolled,
 either because it is not a scrollable element
 or because it is already scrolled to the maximum in that direction,
-the User Agent will select the next <a>spatial navigation focus container</a> up the ancestry chain.
+the User Agent will select the next <a>spatial navigation container</a> up the ancestry chain,
+and recursively repeat the above process
+until it finds some element to focus or scroll,
+or reaches the root element.
 
-The process of looking for an eligible focus target and
-if there is any, then move the focus,
-else if the <a>spatial navigation focus container</a> can be scrolled, then scroll,
-otherwise, going up to the next container
-is repeated until the ancestry chain reaches the root element.
-
-<div class=note>
-NOTE: As a consequence of this processing model,
+Note: As a consequence of this processing model,
 the elements that are reachable by sequential navigation
-and by spatial navigation are almost the same:
-    * Elements that are currently outside of the viewport of a scrollable element
-        can only be reached once they have been scrolled into view
-    * Elements that cannot be scrolled into view.
-        For instance, those are out of reach because they are placed at a negative offset.
-</div>
+and by spatial navigation are almost the same.
+Elements that are currently outside of the viewport of a scrollable element
+can only be reached by spatial navigation once they have been scrolled into view.
+Therefore, elements that cannot be scrolled into view
+(for example because they are placed at a negative offset)
+cannot be reached by spatial navigation.
 
 <div class=api>
 At key points during this search for the appropriate response to the spatial navigation request,
@@ -239,7 +235,7 @@ and [[#declarative]] for details about the CSS properties.
 </div>
 
 <div class='example'>
-    In this example, shows how a series of focusable elements
+    This example shows how a series of focusable elements
     arranged in a scrollable element
     would be navigated when using spatial navigation.
     For the sake of keeping the description simple,
@@ -248,19 +244,19 @@ and [[#declarative]] for details about the CSS properties.
     <figure>
         <img alt="" src="images/spatnav-scroll-visible-1.png" style="width: 200px;"/>
         <img alt="" src="images/spatnav-scroll-visible-2.png" style="width: 200px;"/>
-        <figcaption>Moving focus to the visible element in the <a>spatial navigation focus container</a>.</figcaption>
+        <figcaption>Moving focus to the visible element in the <a>spatial navigation container</a>.</figcaption>
     </figure>
 
     On the left of figure 2, "Box 2" is focused.
     Pressing the <code class=key>ArrowDown</code> key moves the focus to
-    "Box 3" without scrolling because "Box 3" is visible in the <a>scrollport</a> of the <a>spatial navigation focus container</a>.
+    "Box 3" without scrolling because "Box 3" is visible in the <a>scrollport</a> of the <a>spatial navigation container</a>.
 
     <figure>
         <img alt="" src="images/spatnav-scroll-invisible-1.png" style="width: 160px;"/>
         <img alt="" src="images/spatnav-scroll-invisible-2.png" style="width: 160px;"/>
         <img alt="" src="images/spatnav-scroll-invisible-3.png" style="width: 160px;"/>
         <img alt="" src="images/spatnav-scroll-invisible-4.png" style="width: 160px;"/>
-        <figcaption>Moving focus to the hidden element in the <a>spatial navigation focus container</a>.</figcaption>
+        <figcaption>Moving focus to the hidden element in the <a>spatial navigation container</a>.</figcaption>
     </figure>
 
     On the first of figure 3, under "Box 3", there isn't any visible element in the <a>scrollport</a>.
@@ -311,7 +307,7 @@ This intentionally left for User Agents to decide.
 <div class=note>Note:
     It is expected that User Agents on devices with limited input capabilities,
     such as TVs operated with a remote control,
-    or smart feature phones,
+    feature phones,
     or devices operated with a game controller,
     will use spatial navigation as their primary or exclusive navigation mechanism.
 </div>
@@ -330,8 +326,8 @@ even if the author has not invoked any of the APIs.
 Regardless of the actual mechanism chosen to trigger spatial navigation,
 the following requirements apply:
 * If the mechanism the user must use to trigger spatial navigation
-    would normally fire a {{UIEvent}}.
-    The event must be fired prior to running the <a>spatial navigation steps</a>
+    would normally fire a {{UIEvent}},
+    the event must be fired prior to running the <a>spatial navigation steps</a>
     and these steps must not be run if that event's <a>canceled flag</a>
     gets set.
 
@@ -351,8 +347,8 @@ the following requirements apply:
         would follow the same sequence.
     </div>
 * If the mechanism the user must use to trigger spatial navigation
-    would trigger other actions in some contexts.
-    The User Agent should in these contexts
+    would trigger other actions in some contexts,
+    the User Agent should in these contexts
     give priority to these other actions
     and execute them instead of spatial navigation.
     It must not trigger both.
@@ -406,8 +402,8 @@ the same chain of events will be fired and
 the same element will be scrolled or focused.
 
 Note: Authors can use this to trigger spatial navigation
-based on a different UI mechanism than the one assigned by the User Agent.
-Such as mapping to different keys,
+based on a different UI mechanism than the one assigned by the User Agent,
+such as mapping to different keys,
 or triggering spatial navigation from a clickable on-screen directional pad,
 or in reaction to other events than UI ones.
 It could also be used when an author wants to interrupt navigation to do some asynchronous operation
@@ -475,9 +471,12 @@ More directional keywords or a numerical angle could be added.
 
 Note: the {{focusableAreas()}} and {{getSpatialNavigationContainer()}} methods are <a>at-risk</a>.
 
+When these methods are called,
+the User Agent must run the steps described below:
+
 <div algorithm="getSpatialNavigationContainer steps">
 :   <dfn method for=Element lt="getSpatialNavigationContainer()">{{Element/getSpatialNavigationContainer()}}</dfn>
-::  Follows these steps:
+::
     1. Return the element if it is a <a>spatial navigation container</a>,
         or the nearest ancestor of the element that is a <a>spatial navigation container</a>,
         or the <a>document</a> if the nearest <a>spatial navigation container</a> is the viewport.
@@ -486,11 +485,11 @@ Note: the {{focusableAreas()}} and {{getSpatialNavigationContainer()}} methods a
 
 <div algorithm="focusableAreas steps">
 :   <dfn method for=Element lt="focusableAreas(option)">focusableAreas(<var>option</var>)</dfn>
-::  Follows these steps:
+::
     1. Let <var>visibleOnly</var> be <code>false</code>
         if <var>option</var> is present and its value is equal to <code>'all'</code>,
         or <code>true</code> otherwise.
-    2. Let <var>areas</var> be the result of <a>finding focusable areas</a> within the element with the <var>visibleOnly</var>.
+    2. Let <var>areas</var> be the result of <a>finding focusable areas</a> within the element with <var>visibleOnly</var> as argument.
     3. Let <var>anchors</var> be a <a for=list>clone</a> of <var>areas</var>,
         with every <a>focusable area</a> which is not itself a <a>Node</a> replaced with its <a>DOM anchor</a>.
     4. Return <var>anchors</var>
@@ -500,7 +499,7 @@ Note: the {{focusableAreas()}} and {{getSpatialNavigationContainer()}} methods a
 <div class=example id=focusAreas-visible>
     The following code shows how to get all the visible focusable elements in the current page using {{Element/focusableAreas()}}.
     If the method finds a <a>spatial navigation container</a>, it recursively finds focusable areas inside it.
-	However, <code>visible</code> is given to the {{FocusableAreasOptions/mode}} attribute of this method,
+    However, as the {{FocusableAreasOptions/mode}} attribute of this method is set to <code>visible</code>,
     the focusable element which isn’t inside the <a>scrollport</a> is excluded from the result.
 
     <pre><code highlight=markup>
@@ -528,28 +527,32 @@ Note: the {{focusableAreas()}} and {{getSpatialNavigationContainer()}} methods a
 
 <div algorithm="spatialNavigationSearch steps">
 :   <dfn method for=Element lt="spatialNavigationSearch(options)">spatialNavigationSearch(<var>options</var>)</dfn>
-::  Follows these steps:
-    1. Let <var>direction</var> be the value of {{SpatialNavigationSearchOptions/dir}} attribute from <var>options</var>.
-    2. If the value of {{SpatialNavigationSearchOptions/candidates}} attribute from <var>options</var> is not <code>null</code>,
-        then let <var>areas</var> be the corresponding value.
-    3. Else, let <var>container</var> be
-        * the value of {{SpatialNavigationSearchOptions/container}} attribute from <var>options</var>, if it is not <code>null</code>,
-        * the element's nearest <a>spatial navigation container</a> ancestor, otherwise.
-    4. Let <var>areas</var> be the result of <a>finding focusable areas</a> within <var>container</var>.
-    5. 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 {{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.
 
 Note: When neither a container nor a list of candidates is provided,
 this only searches through the visible focusable areas of the nearest
 <a>spatial navigation container</a> ancestor.
-<strong>If there isn't any eligible element to navigate, this does not climb further up the ancestry chain,
-and the result will be <code>null</code>.</strong>
+<em>If there isn't any, this does not climb further up the ancestry chain,
+and the result will be <code>null</code>.</em>
 </div>
 
 <div class=example id=delegation>
     The following code changes the behavior of spatial navigation
     so that when a scroll container would get focused,
     if it has at least one visible focusable descendant,
-    the focus is automatically transferred to it.
+    the focus is automatically transferred to it,
+    recursively.
 
     <pre><code highlight=javascript>
     document.addEventListener('navbeforefocus', function(e) {
@@ -581,7 +584,7 @@ and the result will be <code>null</code>.</strong>
 
     However, the focus can still be moved outside by sequential navigation,
     mouse interaction,
-    and programmatic calls to {{focus()}}…
+    or programmatic calls to {{focus()}}…
 
     <pre><code highlight=javascript>
     document.addEventListener('navnotarget', function(e) {
@@ -729,10 +732,9 @@ The <a event>navbeforefocus</a> event occurs before spatial navigation changes t
 
 The <a event>navnotarget</a> event occurs before going up the tree to search candidates in the
 nearest ancestor <a>spatial navigation container</a> when spatial navigation has failed to find any candidate
-within the current <a>spatial navigation container</a>.
-
-If the <a>spatial navigation container</a> is scrollable, the event occurs when there isn't any candidate in it
-and it cannot be scrolled at the same time.
+within the current <a>spatial navigation container</a>,
+and in cases where the <a>spatial navigation container</a> is scrollable,
+when it cannot be scrolled further.
 
 <table class="def">
     <tbody>
@@ -924,9 +926,9 @@ from a local logical grouping,
 only looking for focusable elements outside of the grouping
 if a suitable one cannot be found inside it (see [[#nav]] for details).
 
-Such groupings are called <dfn lt="spatial navigation focus container | spatial navigation focus containers | spatial navigation container | spatial navigation containers">spatial navigation focus containers</dfn>.
+Such groupings are called <dfn>spatial navigation containers</dfn>.
 
-<span class=cssapi>By default, </span><a>spatial navigation containers</a>(same with spatial navigation focus container) are established by:
+<span class=cssapi>By default, </span><a>spatial navigation containers</a> are established by:
 * The viewport of a <a for="/">browsing context</a>
     (not limited to the <a>top-level browsing context</a>)
 
@@ -977,9 +979,9 @@ To run the <dfn>spatial navigation steps</dfn> in <var>direction</var>, do the f
                 within <var>candidates</var> in <var>direction</var> starting from <var>searchOrigin</var>
             2. If <a>navigation-override</a> <a>is enabled</a> in the [=node document=] of <var>eventTarget</var> for the <a spec=html for="/">origin</a> of the [=active document=] of the [=top-level browsing context=], then
                 <span class=api><a>fire an event</a> named <a event>navbeforefocus</a> at <var>eventTarget</var> using {{NavigationEvent}} with:
-                * Set {{NavigationEvent/dir}} to <var>direction</var>
-                * Set {{NavigationEvent/relatedTarget}} to <var>bestCandidate</var>
-                * Set <code>bubbles</code> and <code>cancelable</code> attributes to <code>true</code>
+                * {{NavigationEvent/dir}} set to <var>direction</var>
+                * {{NavigationEvent/relatedTarget}} set to <var>bestCandidate</var>
+                * the <code>bubbles</code> and <code>cancelable</code> attributes set to <code>true</code>
 
                 and return if the result is <code>false</code>.</span>
             3. Run the <a>focusing steps</a> for <var>bestCandidate</var> and return
@@ -995,9 +997,9 @@ To run the <dfn>spatial navigation steps</dfn> in <var>direction</var>, do the f
     * Else,
         1. If <a>navigation-override</a> <a>is enabled</a> in the [=node document=] of <var>eventTarget</var> for the <a spec=html for="/">origin</a> of the [=active document=] of the [=top-level browsing context=], then
             <span class=api><a>fire an event</a> named <a event>navnotarget</a> at <var>eventTarget</var> using {{NavigationEvent}} with:
-            * Set {{NavigationEvent/dir}} to <var>direction</var>
-            * Set {{NavigationEvent/relatedTarget}} to <var>container</var>
-            * Set <code>bubbles</code> and <code>cancelable</code> attributes to <code>true</code>
+            * {{NavigationEvent/dir}} set to <var>direction</var>
+            * {{NavigationEvent/relatedTarget}} set to <var>container</var>
+            * the <code>bubbles</code> and <code>cancelable</code> attributes set to <code>true</code>
 
             and return if the result is <code>false</code>.</span>
         2.
@@ -1015,9 +1017,9 @@ To run the <dfn>spatial navigation steps</dfn> in <var>direction</var>, do the f
     within <var>candidates</var> in <var>direction</var> starting from <var>searchOrigin</var>.
 10. If <a>navigation-override</a> <a>is enabled</a> in the [=node document=] of <var>eventTarget</var> for the <a spec=html for="/">origin</a> of the [=active document=] of the [=top-level browsing context=], then
     <span class=api><a>fire an event</a> named <a event>navbeforefocus</a> at <var>eventTarget</var> using {{NavigationEvent}} with:
-    * Set {{NavigationEvent/dir}} to <var>direction</var>
-    * Set {{NavigationEvent/relatedTarget}} to <var>bestCandidate</var>
-    * Set <code>bubbles</code> and <code>cancelable</code> attributes to <code>true</code>
+    * {{NavigationEvent/dir}} set to <var>direction</var>
+    * {{NavigationEvent/relatedTarget}} set to <var>bestCandidate</var>
+    * the <code>bubbles</code> and <code>cancelable</code> attributes set to <code>true</code>
 
     and return if the result is <code>false</code>.</span>
 11. Run the <a>focusing steps</a> for <var>bestCandidate</var> and return.
@@ -1246,16 +1248,16 @@ Inherited: no
 <dl dfn-for=spatial-navigation-contain dfn-type=value>
     <dt><dfn>auto</dfn>
     <dd>If the element is a <a>scroll container</a>
-        then it establishes a <a>spatial navigation focus container</a>,
+        then it establishes a <a>spatial navigation container</a>,
         otherwise it does not.
 
     <dt><dfn>contain</dfn>
-    <dd>The element establishes a <a>spatial navigation focus container</a>
+    <dd>The element establishes a <a>spatial navigation container</a>
 </dl>
 
 Note: In addition, as per [[#grouping]], the viewport of a <a for="/">browsing context</a>
         (not limited to the <a>top-level browsing context</a>)
-        also establishes a <a>spatial navigation focus container</a>.
+        also establishes a <a>spatial navigation container</a>.
 
 <div class=example>
     The following example shows a simplified TV program schedule or calendar.
@@ -1352,14 +1354,13 @@ Note: the 'spatial-navigation-contain' property is <a>at-risk</a>.
 </div>
 
 <h3 id=css-property-spatialnavigationaction>
-Defining the spatial navigation behavior : the 'spatial-navigation-action' property</h3>
+Controlling the interaction with scrolling: the 'spatial-navigation-action' property</h3>
 
 <pre class='propdef'>
 Name: spatial-navigation-action
 Value: auto | focus | scroll
 Initial: auto
-Applies to: <a>scroll container</a>
-Inherited: true
+Applies to: <a>scroll containers</a>
 </pre>
 
 When the user triggers spatial navigation in a given direction, the 'spatial-navigation-action' decides