Restore at-risk the property to create additional spatnav containers

frivoal · frivoal · commit 13ad7dfdfa7c · 2018-03-22T18:50:01.000+09:00
At the same time, I have renamed it to the better naming discussed in w3c#17
diff --git a/index.bs b/index.bs
@@ -12,6 +12,7 @@ Abstract: This specification defines a general model for navigating the focus us
     as well as related CSS and JavaScript features.
 At risk: {{getSpatnavContainer()}}
 At risk: {{focusableAreas()}}
+At risk: 'spatial-navigation-contain'
 </pre>
 <pre class="anchors">
 spec: ui-events; urlPrefix: https://w3c.github.io/uievents/;
@@ -105,7 +106,7 @@ spatial navigation related controls.
 However, in the spirit of the <a href="https://github.com/extensibleweb/manifesto">Extensible Web Manifesto</a> [[EXTENSIBLE]],
 we feel it is important to provide the right JavaScript primitives
 to let authors experiment and explore the problem space.
-Declarative features may be added later,
+More declarative features may be added later,
 based on feedback and experience acquired through such JavaScript usage.
 
 Note: A few features are marked <dfn noexport>at-risk</dfn>.
@@ -144,7 +145,9 @@ 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>
-(the root element, scrollable elements, or iframes)
+(by default the root element, scrollable elements, and iframes,
+but other elements can be made into <a>spatial navigation focus containers</a>
+using the 'spatial-navigation-contain' property).
 
 If it finds any, it will pick the best one for that direction,
 and move the focus there.
@@ -265,7 +268,6 @@ and [[#js-api]] for details about the JavaScript API.
     </pre>
 </div>
 
-
 <h2 id=triggering>
 Triggering Spatial Navigation</h2>
 
@@ -857,19 +859,30 @@ for <a href="https://github.com/WICG/overscroll-behavior">the proposed overscrol
 Issue(21): The following does not take shadow dom into account.
 
 
-<h3 id=nav>
-Navigation</h3>
+<h3 id=grouping>
+Groupings of elements</h3>
+
+While the general model for spatial navigation
+is to work from the layout of the document
+and the relative position of focusable elements,
+the User Agent is required to prioritize finding elements
+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 | spatnav container | spatnav containers">spatial navigation focus containers</dfn> (or <strong>spatnav containers</strong> for short).
 
-<dfn lt="spatial navigation focus container | spatial navigation focus containers | spatnav container | spatnav containers">Spatial navigation focus containers</dfn> (or <strong>spatnav containers</strong> for short),
-are defined to be any of:
+By default, <a>spatnav containers</a> are established by:
 * the <a>document element</a> of a <a for="/">browsing context</a>'s <a>document</a>
     (not limited to the <a>top-level browsing context</a>)
 
     Issue(18): Should that be the viewport rather than the document element?
-* a <a>scroll container</a>
+* a <a>scroll containers</a>
 
-Note: A mechanism such as a css property to let the author turn additional elements into
-spatnav containers may be added in future extentions of this specification.
+Additional <a>spatnav containers</a> can be created using the 'spatial-navigation-contain' property (see [[#container]]).
+
+<h3 id=nav>
+Navigation</h3>
 
 There can be a <dfn>spatial navigation starting point</dfn>. It is initially unset.
 The user agent may set it when the user indicates that it should be moved.
@@ -1099,6 +1112,38 @@ follow the following steps:
 
 </div>
 
+<h2 id=declarative>
+Controlling spatial navigation through declarative means</h2>
+
+<h3 id=container>
+Creating additional spatnav containers: the 'spatial-navigation-contain' property</h3>
+
+<pre class='propdef'>
+Name: spatial-navigation-contain
+Value: auto | contain
+Initial: auto
+Inherited: no
+</pre>
+
+<dl dfn-for=spatial-navigation-contain dfn-type=value>
+    <dt><dfn>auto</dfn>
+    <dd>If the element is either
+    the <a>document element</a> of a <a for="/">browsing context</a>'s <a>document</a>
+    (not limited to the <a>top-level browsing context</a>)
+    or
+    a <a>scroll container</a>
+    then it establishes a <a>spatial navigation focus container</a>,
+    otherwise it does not.
+
+    <dt><dfn>contain</dfn>
+    <dd>The element establishes a <a>spatial navigation focus container</a>
+</dl>
+
+Issue(16): Add an example
+
+Note: the 'spatial-navigation-contain' property is <a>at-risk</a>.
+
+
 <h2 class=no-num id=scrolling>Appendix A. Scroll extensions</h2>
 
 This section proposes a few extensions to CSS
