[css-nav-1] describe spatial-navigation-action in more detail

Author: frivoal

css-nav-1/Overview.bs

@@ -1369,29 +1369,61 @@ Applies to: <a>scroll containers</a>
 Inherited: no
 </pre>
 
-When the user triggers spatial navigation in a given direction, the 'spatial-navigation-action' decides
-the proper spatial navigation behavior.
+When the focus is inside of a scroll container and the user triggers spatial navigation,
+it is somewhat ambiguous whether they are requesting that the focus be moved in that direction,
+or whether the document should be scrolled in that direction.
+By default, this is automatically determined,
+but this property allows the author to decide between focusing or scrolling.
+
+The precise behavior is defined in [[#nav]],
+but a high level description of the effect of each value is provided below.
+
+When spatial navigation is triggered,
+the behavior depends on the value of the 'spatial-navigation-action' on the currently focused element
+if that element is a [=scroll container=],
+or of its nearest [=scroll container=] ancestor if it isn't.
 
 <dl dfn-for=spatial-navigation-action dfn-type=value>
     <dt><dfn>auto</dfn>
-    <dd>If the element is a <a>scroll container</a>,
-        then directional input moves the focus to the candidates in the optimal viewing region.
-        When there isn't any visible candidate, then the container scrolls.
-
-        Otherwise, the focus moves to the candidates in the viewport.
+    <dd>
+        If there are visible focusable elements within the
+        [=scroll container=] in the direction requested,
+        the closest one becomes focused.
+        Otherwise, the [=scroll container=] is scrolled in the direction requested.
 
     <dt><dfn>focus</dfn>
-    <dd>The directional input moves the focus to all candidates inside a scroll container. The container <a>cannot be scrolled manually</a>.
+    <dd>
+        The focus is moved to the nearest focusable element within the [=scroll container=],
+        regardless of whether it is visible.
+        If there are none,
+        the scroll container is <em>not</em> scrolled,
+        and the search continues up the ancestry chain instead.
 
-    NOTE: If the ''spatial-navigation-action/focus'' value is given to 'spatial-navigation-action',
-    <a event>navnotarget</a> event occurs when there isn’t any visible candidate in the given direction within the viewport of
-    the <a>spatial navigation container</a> even through the container can be scrolled more.
+        Note: The [=scroll container=] may be scrolled as a side effect of focusing
+        an element which was previously not in view,
+        but it will not be scrolled directly.
 
-    <dt><dfn>scroll</dfn>
-    <dd>If the element is a <a>scroll container</a>,
-        then directional input only works for manually scrolling the container.
+        Note: If the ''spatial-navigation-action/focus'' value is given to 'spatial-navigation-action',
+        <a event>navnotarget</a> event occurs when there isn’t any visible candidate in the given direction within the viewport of
+        the <a>spatial navigation container</a> even if the container can be scrolled more.
 
-    Note: The ''spatial-navigation-ation/scroll'' value is <a>at-risk</a>.
+    <dt><dfn>scroll</dfn>
+    <dd>
+        If the currently focused element is not itself a [=scroll container=],
+        this value on an ancestor [=scroll container=] has the same effect as ''spatial-navigation-action/auto''.
+
+        If the currently focused element is a [=scroll container=],
+        it is scrolled in the direction requested without changing which element is in focus,
+        regardless of the presence of focusable descendants.
+
+        Note: This means that spatial navigation can be used
+        to move the focus to a [=scroll container=] and to scroll it,
+        but not to move the focus to its descendants.
+        However, if the focus is moved to a descendant by some other mean
+        (such as pressing the <span class=key>Tab</span> key or using the <{{HTMLOrSVGElement/focus()}}> method)
+        spatial navigation can be used to move the focus to other focusable descendants.
+
+        Note: The ''spatial-navigation-ation/scroll'' value is <a>at-risk</a>.
 </dl>
 
 <div class=example>