|
1 | 1 | # Proposed APIs for the spatial navigation |
2 | | -To support the spatial navigation in the Web, we need to develop several standard APIs. The API seems to be discussed with the suitable working groups in W3C (mainly in CSS WG). In this explainer page, the latest status of the spatial navigation would be summarized so that the overall progress could be tracked at a glance. |
| 2 | +To support the spatial navigation in the Web, we need to develop several standard APIs. The APIs seem to be discussed with the suitable working groups in W3C (mainly in CSS WG). In this explainer page, the latest status of the spatial navigation would be summarized so that the overall progress could be tracked at a glance. |
3 | 3 |
|
4 | 4 | ## API for enabling the spatial navigation mode |
5 | | -It makes author set the spatial navigation mode. The following API could be considered for the possibilities to support the feature: |
6 | | - - HTML: <meta name="input" content="remote-controller"> |
7 | | - - If the using input device matches with the specified value of the content, the spatial navigation mode is enabled. |
8 | | - - CSS: |
9 | | - |
10 | | - If the proposed property is applied to the element, the DOM subtree rooted at the element can be managed by the spatial nagivation or not. |
11 | | - - arrow-key-behavior: auto | navigation | scroll |
12 | | - - auto: The directional navigational input responses as the UA-defined manner. |
13 | | - - navigation: The directional navigational input responses as the spatial navigation mode. |
14 | | - - scroll: The directional navigational input responses for controlling the scrollbar. |
15 | | - |
16 | | - or |
17 | | - |
18 | | - - spatial-mode: always | none |
19 | | - - always: The spatial navigation mode is enabled. |
20 | | - - none: The spatial navigation mode is disabled. |
21 | | - - JS: setSpatialNavigationEnabled(boolean) |
22 | | - - If the parameter is `true`, the spatial navigation mode is enabled. |
23 | | - - Otherwise, the spatial navigation mode is enabled and the directional navigational input responses as the UA-defined manner. |
| 5 | +It makes author set the spatial navigation mode. The following APIs could be considered for the possibilities to support the feature: |
| 6 | + |
| 7 | +#### * HTML meta tag |
| 8 | +- If the input device in use matches with the specified value of the content, the spatial navigation mode is enabled. |
| 9 | +- The values for the spatial navigation could be specified as follows: remote-controller, game-pad, jog-dial, etc. |
| 10 | +```html |
| 11 | +<!-- HTML meta tag --> |
| 12 | +<meta name="input" content="remote-controller">; |
| 13 | +``` |
| 14 | + |
| 15 | +#### * CSS properties |
| 16 | +- If the proposed property below is applied to the element, the DOM subtree rooted at the element can be managed by the spatial nagivation. |
| 17 | +```css |
| 18 | +// CSS property 1 |
| 19 | +arrow-key-behavior: auto | navigation | scroll |
| 20 | +``` |
| 21 | +- auto: The arrow keys work as the UA-defined manner. |
| 22 | +- navigation: The arrow keys work for the spatial navigation. |
| 23 | +- scroll: The arrow keys work for scrolling. |
| 24 | +```css |
| 25 | +// CSS property 2 |
| 26 | +spatial-mode: always | none |
| 27 | +``` |
| 28 | +- always: The spatial navigation mode is enabled. |
| 29 | +- none: The spatial navigation mode is disabled. |
| 30 | + |
| 31 | +#### * DOM method (JS) |
| 32 | +```javascript |
| 33 | +// JavaScript |
| 34 | +setSpatialNavigationEnabled(boolean) |
| 35 | +``` |
| 36 | +- If the parameter is `true`, the spatial navigation mode is enabled. |
| 37 | +- Otherwise, the arrow keys work as the UA-defined manner. |
24 | 38 |
|
25 | 39 | ## Overriding methods on top of the heuristic algorithm |
26 | | -Developers can customize the spatial navigation with CSS properties by overriding the heuristic spatial navigation. |
| 40 | +Developers can customize the spatial navigation with CSS properties while overriding the heuristic spatial navigation. |
27 | 41 |
|
28 | 42 | ### Current Approach |
29 | | -There are the properties about the directional focus navigation already in the CSS Basic User Interface Module Level 4. |
30 | | - - [nav-up/right/down/left properties (CSSUI4)](https://drafts.csswg.org/css-ui-4/#nav-dir) |
31 | | - - value: auto | <id> [ current | root | <target-name> ]? |
32 | | - |
33 | | - The properites determine which element to navigate the focus in response to the directional navigational input. This is applied to the each element which can be focused. |
34 | | - - Note |
35 | | - - Able to use even if the heuristic spatial navigation is not supported. |
36 | | - - Override the heuristic spatial navigation if it is supported. |
| 43 | +There were the properties about the directional focus navigation in the CSS Basic User Interface Module Level 4. |
| 44 | +- [nav-up/right/down/left properties (CSSUI4)](https://drafts.csswg.org/css-ui-4/#nav-dir) |
| 45 | +```css |
| 46 | +// nav-right, nav-down, nav-left have same values as nav-up below |
| 47 | +nav-up: auto | <id> [ current | root | <target-name> ]? |
| 48 | +``` |
| 49 | +- The properites determine which element to navigate the focus in response to the directional navigational input. This is applied to the each element which can be focused. |
| 50 | +- Note |
| 51 | + - Able to use even if the heuristic spatial navigation is not supported. |
| 52 | + - Override the heuristic spatial navigation if it is supported. |
37 | 53 |
|
38 | 54 | ### Proposal |
39 | | -The following properties are proposed to embrace the developer’s intention and make easier to implement and use the spatial navigation. |
40 | | - - nav-rule property (CSSUI4) |
41 | | - |
42 | | - This property can customize the spatial navigation of the group of elements in response to the directional navigational input. |
43 | | - - value: auto | projection | direction | nearest |
44 | | - - auto: The UA automatically determines which element to navigate the focus. |
45 | | - - projection: Moves the focus to the first element encountered when projecting the edge of the currently focused element to the edge of the applied element in the direction of navigation. |
46 | | - - direction : Moves the focus to the first element encountered when projecting the edge of the applied element from the currently focused element in the direction of navigation. |
47 | | - - nearest: Moves the focus to the closest element based on the shortest 2D distance and the distance is measured depending on the center of each element. |
48 | | - - Note |
49 | | - - Able to use if the heuristic spatial navigation is enabled by default. |
50 | | - - Applied to the containing block, so all focusable elements in the DOM subtree rooted at the applied element follow the specified rule for the spatial navigation. |
51 | | - - Overridden by nav-left/right/top/bottom properties. |
52 | | - - Override the Heuristic Spatial Navigation if it is supported. |
53 | | - |
54 | | - If the `nav-rule` property is applied to the element E, the DOM subtree rooted at E in the scrollable area created by E follows the focus moving algorithm as below. |
55 | | - - Let E has child nodes A, B, C, and D which are `width: 50px; height: 50px;`. |
56 | | - - Let the upper edge of the A is positioned `100px` down from the upper edge of the E and the leftside edge of the A is positioned `100px` to the right from the leftside edge of the E. |
57 | | - - Let the upper edge of the B is positioned `50px` down from the upper edge of the E and the leftside edge of the B is positioned `250px` to the right from the leftside edge of the E. |
58 | | - - Let the upper edge of the C is positioned `250px` down from the upper edge of the E and the leftside edge of the C is positioned `200px` to the right from the leftside edge of the E. |
59 | | - - Let the upper edge of the D is positioned `100px` down from the upper edge of the E and the leftside edge of the D is positioned `500px` to the right from the leftside edge of the E. |
60 | | - - Let the initial focus goes to A among the DOM subtree rooted at E. |
61 | | - - If the current focused element is A and there is an input from the :arrow_right: (right-arrow key), |
62 | | - - If `nav-rule: projection` is applied to the element E, the focus moves to D. |
63 | | - - If `nav-rule: direction` is applied to the element E, the focus moves to C. |
64 | | - - Otherwise `nav-rule: nearest` is applied to the element E, the focus moves to B. |
65 | | - |
66 | | - - nav-loop property (CSSUI4) |
67 | | - |
68 | | - This property enables the ability about the focus looping (moving the focus when the focus reaches to the end of the page). |
69 | | - |
70 | | - The sequential focus navigation by tab key supports the focus looping, but the heuristic spatial navigation implemented in blink doesn’t support it. |
71 | | - It would be useful to have the focus looping feature in the spatial navigation, especially for the single page with long-scroll. |
72 | | - |
73 | | - - value: auto | no-repeat | repeat |
74 | | - - auto: The UA automatically determines where to move the focus when the focus reaches to the end of the page. |
75 | | - - no-repeat: Disables the focus looping |
76 | | - - repeat: Enables the focus looping |
| 55 | +The following properties are proposed to provide ways for customization of the spatial navigation. |
| 56 | + |
| 57 | +#### `nav-rule` property (CSSUI4) |
| 58 | +- This property can customize the spatial navigation of the group of elements in response to the directional navigational input. |
| 59 | +```css |
| 60 | +nav-rule: auto | projection | direction | nearest |
| 61 | +``` |
| 62 | +- The meaning of `nav-rule` values |
| 63 | + - auto: The UA automatically determines which element to navigate the focus. |
| 64 | + - projection: Moves the focus to the first element encountered when projecting the edge of the currently focused element to the edge of the applied element in the direction of navigation. |
| 65 | + - direction : Moves the focus to the first element encountered when projecting the edge of the applied element from the currently focused element in the direction of navigation. |
| 66 | + - nearest: Moves the focus to the closest element based on the shortest 2D distance and the distance is measured depending on the center of each element. |
| 67 | +- Note |
| 68 | + - Able to use if the heuristic spatial navigation is enabled by default. |
| 69 | + - Applied to the containing block, so all focusable elements in the DOM subtree rooted at the applied element follow the specified rule for the spatial navigation. |
| 70 | + - Overridden by nav-left/right/top/bottom properties. |
| 71 | + - Override the Heuristic Spatial Navigation if it is supported. |
| 72 | + - If the `nav-rule` property is applied to the element E, the DOM subtree rooted at E in the scrollable area created by E follows the focus moving algorithm as below. |
| 73 | + - Let E has child nodes A, B, C, and D which are `width: 50px; height: 50px;`. |
| 74 | + - Let the upper edge of the A is positioned `100px` down from the upper edge of the E and the leftside edge of the A is positioned `100px` to the right from the leftside edge of the E. |
| 75 | + - Let the upper edge of the B is positioned `50px` down from the upper edge of the E and the leftside edge of the B is positioned `250px` to the right from the leftside edge of the E. |
| 76 | + - Let the upper edge of the C is positioned `250px` down from the upper edge of the E and the leftside edge of the C is positioned `200px` to the right from the leftside edge of the E. |
| 77 | + - Let the upper edge of the D is positioned `100px` down from the upper edge of the E and the leftside edge of the D is positioned `500px` to the right from the leftside edge of the E. |
| 78 | + - Let the initial focus goes to A among the DOM subtree rooted at E. |
| 79 | + - If the current focused element is A and there is an input from the :arrow_right: (right-arrow key), |
| 80 | + - If `nav-rule: projection` is applied to the element E, the focus moves to D. |
| 81 | + - If `nav-rule: direction` is applied to the element E, the focus moves to C. |
| 82 | + - Otherwise `nav-rule: nearest` is applied to the element E, the focus moves to B. |
77 | 83 |
|
78 | | - If `nav-loop: repeat` is applied to the element E, the DOM subtree rooted at E is eligible to participate in the focus looping for any scrollable area created by E. |
79 | | - - Let the element A is the first child node and the element Z is the last child node in the DOM subtree rooted at E. |
80 | | - - If the current focused element is Z and there is an input from the :arrow_down: (down-arrow key), the focus is moved to A. |
| 84 | +#### `nav-loop` property (CSSUI4) |
| 85 | +- This property enables the ability about the focus looping (moving the focus when the focus reaches to the end of the page). |
| 86 | +- The sequential focus navigation by tab key supports the focus looping, but the heuristic spatial navigation implemented in blink doesn’t support it. |
| 87 | +- It would be useful to have the focus looping feature in the spatial navigation, especially for the single page with long-scroll. |
| 88 | +```css |
| 89 | +nav-loop: auto | no-repeat | repeat |
| 90 | +``` |
| 91 | +- The meaning of `nav-loop` values |
| 92 | + - auto: The UA automatically determines where to move the focus when the focus reaches to the end of the page. |
| 93 | + - no-repeat: Disables the focus looping |
| 94 | + - repeat: Enables the focus looping |
| 95 | + |
| 96 | +- If `nav-loop: repeat` is applied to the element E, the DOM subtree rooted at E is eligible to participate in the focus looping for any scrollable area created by E. |
| 97 | + - Let the element A is the first child node and the element Z is the last child node in the DOM subtree rooted at E. |
| 98 | + - If the current focused element is Z and there is an input from the :arrow_down: (down-arrow key), the focus is moved to A. |
81 | 99 |
|
82 | 100 | ## Issues |
83 | | -- Why CSS properties instead of HTML attributes (like `tabindex`)? |
84 | | -- How can the feature be made to be composable. Eg. in a world of custom elements and frameworks like polymer, how can you reason about spatial navigation without having global knowledge of the whole page? Eg. could we instead make the properties define local spatial navigation (eg. between components) while allowing components to define navigation behavior inside of themselves? |
| 101 | +- Why CSS properties instead of HTML attributes (like `tabindex` as a DOM attribute)? |
| 102 | +- How can the feature be made to be composable. |
| 103 | + - Eg. in a world of custom elements and frameworks like polymer, how can you reason about spatial navigation without having global knowledge of the whole page? |
| 104 | + - Eg. could we instead make the properties define local spatial navigation (eg. between components) while allowing components to define navigation behavior inside of themselves? |
85 | 105 |
|
86 | 106 | ## Future work |
87 | 107 | Solving unreachability, saving last focus, group concept, aligning with scrolling, pointer/key mode selection |
0 commit comments