Title: CSS Spatial Navigation Level 1
Shortname: css-nav
Level: 1
Status: ED
Work Status: exploring
Group: csswg
ED: https://drafts.csswg.org/css-nav-1/
Editor: Jihye Hong, LG Electronics, jh.hong@lge.com
Editor: Florian Rivoal, Invited Expert, https://florian.rivoal.net
Abstract: This specification defines a general model for navigating the focus using the arrow keys,
    as well as related CSS and JavaScript features.
At risk: {{getSpatialNavigationContainer()}}
At risk: {{focusableAreas()}}
At risk: 'spatial-navigation-contain'

spec: ui-events; urlPrefix: https://w3c.github.io/uievents/;
    type: event;
        text: keydown
        text: click
spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/;
    urlPrefix: interaction.html
        type: dfn;
            text: DOM anchor
            text: focusable area
            text: currently focused area of a top-level browsing context
            text: sequential focus navigation order
            text: sequential focus navigation starting point
            text: sequential navigation search algorithm
            text: control group
    urlPrefix: dom.html
        type: dfn;
            text: the body element; url: #the-body-element-2
spec: dom; urlPrefix: https://dom.spec.whatwg.org/
    type: dfn;
        text: document element
spec: feature-policy; urlPrefix: https://wicg.github.io/feature-policy/
    type: dfn;
        text: is enabled; url: is-feature-enabled
spec: overscroll-behavior; urlPrefix: https://wicg.github.io/overscroll-behavior/;
    type: dfn;
        text: scroll boundary
spec: css2; urlPrefix: https://drafts.csswg.org/css2/
    urlPrefix: box.html
        type: dfn;
            text: border box; url: #x14
    urlPrefix: zindex.html
        type: dfn;
            text: painting order; url: #painting-order

spec:html; type:method; for:HTMLOrSVGElement; text:focus()

Introduction

Module interaction

Overview

This section is not normative. Using a UA-defined mechanism (typically arrow keys, possibly in combination with modifier keys like Shift or Control), the user may ask the User Agent to navigate in a particular direction. This will either move the focus from its current location to a new focusable item in the direction requested, 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 spatial navigation focus container (by default the root element, scrollable elements, and iframes, but other elements can be made into spatial navigation focus containers using the 'spatial-navigation-contain' property). 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 spatial navigation focus container 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 spatial navigation focus container 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 spatial navigation focus container up the ancestry chain, and repeat the process of looking for eligible focus targets, selecting the best one if there's any, scrolling if not, going up the ancestry chain if it cannot scroll, until it has either moved focus, scrolled, or reached the root. Note: As a consequnce 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, and those that cannot be scrolled into view, for instance because they are placed at a negative offset, are out of reach.

At key points during this search for the appropriate response to the spatial navigation request, the User Agent will fire events. These enable authors to prevent the upcoming action (by calling {{preventDefault()}}), and if desired to provide an alternate action, such as using calling the {{HTMLOrSVGElement/focus()}} method on a different element of the author's choosing. To help authors write such alternate actions, and as part of exposing underlying platform primitives as per the Extensible Web principles, this specification also defines JavaScript APIs that expose key constructs of the underlying model. See [[#events-nav-type]] for details about the various events, and [[#js-api]] for details about the JavaScript API.

In 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, this example assumes a UA where spatial navigation is triggered using arrow keys.

On the left of figure 2, "Box 2" is focused. Pressing the ArrowDown key moves focus to "Box 3" without scrolling because "Box 3" is visible in the scrollport of the spatial navigation focus container.

On the first of figure 3, under "Box 3", there isn't any visible element in the scrollport. Therefore, the effect of pressing the ArrowDown is to scroll down, as shown in the second. The next press of the ArrowDown key makes "Box 4" come into the scrollport, and the focus will move to it when there is additional pressing the ArrowDown, as the fourth. This example uses the markup as follows:

        #scroller {
            width: 700px;
            height: 700px;
            overflow-x: hidden;
            overflow-y: auto;
        }

        .box {
            width: 150px;
            height: 110px;
            background-color: blue;
        }

        .box:focus {
            background-color: red;
        }
    

        <div id="scroller">
            <div class="box" tabindex="0">Box 1</div>
            <div class="box" tabindex="0">Box 2</div>
            <div class="box" tabindex="0">Box 3</div>
            <div class="box" tabindex="0">Box 4</div>
        </div>
    

Triggering Spatial Navigation

enum SpatialNavigationDirection {
    "up",
    "down",
    "left",
    "right",
};

partial interface Window {
    void navigate(SpatialNavigationDirection dir);
};

enum FocusableAreaSearchMode {
    "visible",
    "all"
};

dictionary FocusableAreasOptions {
    FocusableAreaSearchMode mode;
};

dictionary SpatialNavigationSearchOptions {
    required SpatialNavigationDirection dir;
    sequence<Node>? candidates;
    Node? container;
};

partial interface Element {
    Node getSpatialNavigationContainer();
    sequence<Node> focusableAreas(optional FocusableAreasOptions arg);
    Node? spatialNavigationSearch(SpatialNavigationSearchOptions arg);
};

    document.addEventListener("navbeforescroll", function(e) {
        var container = e.relatedTarget;
        var areas = container.focusableAreas({ mode: "all" });

        if (areas.length === 0) { return; }

        e.preventDefault();
        var t = e.target.spatialNavigationSearch({
            dir: e.dir,
            candidates: areas
        });
        t.focus();
    });
    

    document.addEventListener("navbeforefocus", function(e) {
        e.preventDefault();

        if (e.dir === "forward" || e.dir === "backward") {
            e.dir = "top";
        }

        var t = e.relatedTarget;
        while (t.isSameNode(t.getSpatialNavigationContainer())) {
            var areas = t.focusableAreas();

            if (areas.length === 0) { break; }

            t = t.spatialNavigationSearch({
                dir:  e.dir,
                candidates: areas
            });
        }
        t.focus();
    });
    

    document.addEventListener("navnotarget", function(e) {
        e.preventDefault();

        var c = e.relatedTarget;
        var areas = c.focusableAreas({mode: "all"});

        if (areas.length === 0) {
            switch (e.dir) {
                case "down":
                    c.scrollTop = 0;
                    break;
                case "up":
                    c.scrollTop = c.scrollHeight;
                    break;
                case "right":
                    c.scrollLeft = 0;
                    break;
                case "left":
                    c.scrollLeft = c.scrollWidth;
                    break;
            }
        } else {
            var t = c.spatialNavigationSearch({
                dir: e.dir,
                candidates: areas
            });
            t.focus();
    });
    

Navigation Events

Interface NavigationEvent

The {{NavigationEvent}} interface provides specific contextual information associated with spatial navigation. To create an instance of the {{NavigationEvent}} interface, use the {{NavigationEvent}} constructor, passing an optional {{NavigationEventInit}} dictionary.

[Constructor(DOMString type, optional NavigationEventInit eventInitDict)]
interface NavigationEvent : UIEvent {
      readonly attribute SpatialNavigationDirection dir;
      readonly attribute EventTarget? relatedTarget;
};

dictionary NavigationEventInit : UIEventInit {
      required SpatialNavigationDirection dir;
      EventTarget? relatedTarget = null;
};

Navigation Event Types

This section and its subsections are not normative. The Navigation event types are summarized below. For full normative details, see [[#processing-model]].

navbeforefocus

The navbeforefocus event occurs before spatial navigation changes the focus.

Type	navbeforefocus
Interface	{{NavigationEvent}}
Bubbles	Yes
Cancelable	Yes
Attributes of the event	{{NavigationEvent}}.{{NavigationEvent/relatedTarget}} The DOM anchor of the focusable area that will be focused {{NavigationEvent}}.{{NavigationEvent/dir}} The direction of the navigation as requested by the user

This example shows the [[UI-EVENTS#event-order]] when pressing the ArrowRight key. For the sake of keeping the description simple, this example assumes a UA where spatial navigation is triggered using arrow keys.

	Event type	{{KeyboardEvent}}.{{KeyboardEvent/key}}	Notes
1	keydown	ArrowRight	MUST be a key which can activate spatial navigation, such as the arrow keys, or spatial navigation is not activated.
2	navbeforefocus		Sent if the candidates for spatial navigation is not null, or this is not generated.
3	focusin		Sent before the target element receives focus.
4	focus		Sent after the target element receives focus.

navbeforescroll

The navbeforescroll event occurs before spatial navigation triggers scrolling.

Type	navbeforescroll
Interface	{{NavigationEvent}}
Bubbles	Yes
Cancelable	Yes
Attributes of the event	{{NavigationEvent}}.{{NavigationEvent/relatedTarget}} The element that will be scrolled if the event is not canceled {{NavigationEvent}}.{{NavigationEvent/dir}} The direction of the navigation as requested by the user

This example shows the [[UI-EVENTS#event-order]] when pressing the ArrowDown key in the situation like the following figure. For the sake of keeping the description simple, this example assumes a UA where spatial navigation is triggered using arrow keys.

	Event type	Event target	relatedTarget	Notes
1	keydown	#box2	N/A	MUST be a key which can activate spatial navigation, such as the arrow keys, otherwise spatial navigation is not triggered.
2	navbeforescroll	#box2	#scrollContainer	Sent if #scrollContainer doesn't contain any candidate in the scrollport, otherwise this would not be generated.

After navbeforescroll is fired, pressing the ArrowDown key triggers scrolling down the scrollbar like in the figure below:

This example uses the markup as follows:

        #scrollContainer {
            width: 700px;
            height: 700px;
            overflow-x: hidden;
            overflow-y: auto;
        }

        .item {
            width: 150px;
            height: 110px;
            background-color: blue;
        }

        .item:focus {
            background-color: red;
        }
    

        <div id="scrollContainer">
            <div id="box1" class="item" tabindex="0">Box 1</div>
            <div id="box2" class="item" tabindex="0">Box 2</div>
            <div id="box3" class="item" tabindex="0">Box 3</div>
        </div>
   

navnotarget

The navnotarget event occurs before going up the tree to search candidates in the nearest ancestor spatial navigation container when spatial navigation has failed to find any candidate within the current spatial navigation container. If the spatial navigation container is scrollable, the event occurs when there isn't any candidate in it and it cannot be scrolled at the same time.

Type	navnotarget
Interface	{{NavigationEvent}}
Bubbles	Yes
Cancelable	Yes
Attributes of the event	{{NavigationEvent}}.{{NavigationEvent/relatedTarget}} The spatial navigation container that was searched in. {{NavigationEvent}}.{{NavigationEvent/dir}} The direction of the navigation as requested by the user

This example shows the [[UI-EVENTS#event-order]] when pressing the ArrowDown key in the situation like the following figure. For the sake of keeping the description simple, this example assumes a UA where spatial navigation is triggered using arrow keys.

	Event type	Event target	relatedTarget	Notes
1	keydown	#box2	N/A	MUST be a key which can activate spatial navigation, such as the arrow keys, otherwise spatial navigation is not triggered.
2	navnotarget	#box2	#scrollContainer	Sent if #scrollContainer doesn't contain any candidate and cannot be scrolled, otherwise this would not be generated.
3	navbeforefocus	#box2	#box3	Sent if the candidates in #container is not null, otherwise this would not be fired.
4	focusin	#box3	N/A	Sent before the target element receives focus.
5	focus	#box3	N/A	Sent after the target element receives focus.

The result of this example is the figure as follows:

This example uses the markup as follows:

        #container {
            width: 900px;
            height: 1400px;
        }

        #scrollContainer {
            width: 700px;
            height: 700px;
            overflow-x: hidden;
            overflow-y: auto;
        }

        .item {
            width: 150px;
            height: 110px;
            background-color: blue;
        }

        .item:focus {
            background-color: red;
        }
    

        <div id="container">
            <div id="scrollContainer">
                <div id="box1" class="item" tabindex="0">Box 1</div>
                <div id="box2" class="item" tabindex="0">Box 2</div>
            </div>
            <div id="box3" class="item" tabindex="0">Box 3</div>
        </div>
   

The navigation-override [=policy-controlled feature=]

Processing Model

Groupings of elements

Navigation

Focus Navigation Heuristics

Name: spatial-navigation-contain
Value: auto | contain
Initial: auto
Inherited: no

        <div>
            <button>Previous Week</button>
            <table>
                <tr><td><th>M<th>T<th>W<th>T<th>F<th>S<th>S
                <tr><td>0-6<td><td><td><td><td><td><td><a href="#">Foo</a>
                <tr><td>6-9<td><a href="#">Bar</a><td><td><td><td><td><td>
                <tr><td>9-12<td><td><td><td><td><td><td>
                <tr><td>12-18<td><td><td><td><td><td><td>
                <tr><td>18-21<td><td><td><td><td><td><td>
                <tr><td>21-24<td><td><td><td><td><td><a href="#">Baz</a><td>
            </table>
            <button>Next Week</button>
        </div>
    

        table, td, th {
            border-collapse: collapse;
            border: solid 1px;
        }
        td { width: 12.5%; }
        div {
            display: grid;
            grid-template-columns: auto 1fr auto;
        }
        button { align-self: center; }
    

Appendix A. Scroll extensions

Appendix B. Privacy and Security Considerations

Does this specification deal with personally-identifiable information?

No.

Does this specification deal with high-value data?

No.

Does this specification introduce new state for an origin that persists across browsing sessions?

No.

Does this specification expose persistent, cross-origin state to the web?

No.

Does this specification expose any other data to an origin that it doesn’t currently have access to?

Mostly, no. The one exception identified would be in the following scenario: if the author uses `window.navigate` while the focus is in a cross origin iframe, if they don't get an event at all it means that either there was something scrollable or focusable within the iframe, as the only case where they'd get an event is when the search didn't find anything at all goes up the tree. This is so limited information that it does not seem it would introduces real a security risk, but it is as far as the editors can tell information that the author could not get could not get otherwise.

Does this specification enable new script execution/loading mechanisms?

No.

Does this specification allow an origin access to a user’s location?

No.

Does this specification allow an origin access to sensors on a user’s device?

No.

Does this specification allow an origin access to aspects of a user’s local computing environment?

No.

Does this specification allow an origin access to other devices?

No.

Does this specification allow an origin some measure of control over a user agent’s native UI?

No control is given over the appearance of the User Agent's UI. Some control is given over how the User Agent performs spatial navigation, which may be considered part of its user interface. This is intentional, to let authors tailor the behavior of spatial navigation to their pages. To prevent malicious authors to interefere with the users' desire to control focus and navigate the document, this overriding mechanism is disabled by default for cross-origin iframes. See [[#policy-feature]].

Does this specification expose temporary identifiers to the web?

No.

Does this specification distinguish between behavior in first-party and third-party contexts?

No.

How should this specification work in the context of a user agent’s "incognito" mode?

No Difference is expected.

Does this specification persist data to a user’s local device?

No.

Does this specification have a "Security Considerations" and "Privacy Considerations" section?

Yes, this is the section you are reading now.

Does this specification allow downgrading default security characteristics?

It does not allow downgrading any unrelated security mechanism. It **does** allow authors to opt into allowing the events needed to override the default behavior of spatial navigation in cross origin iframes they trust using [[feature-policy]]. See [[#policy-feature]].

Acknowledgements