-
Notifications
You must be signed in to change notification settings - Fork 790
Expand file tree
/
Copy pathOverview.bs
More file actions
1531 lines (1291 loc) · 64.8 KB
/
Overview.bs
File metadata and controls
1531 lines (1291 loc) · 64.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<pre class='metadata'>
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'
</pre>
<pre class="anchors">
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
</pre>
<pre class=link-defaults>
spec:html; type:method; for:HTMLOrSVGElement; text:focus()
</pre>
<style>
code.key {
border: solid 1px;
border-radius: 0.5ch;
padding: 1px 5px;
}
.output {
background: white;
padding: 1em;
}
</style>
<style>
#api-check:checked ~ .api,
#api-check:checked ~ * .api {
display: none;
}
#cssapi-check:checked ~ .cssapi,
#cssapi-check:checked ~ * .cssapi {
display: none;
}
#verbose-check:checked ~ .verbose,
#verbose-check:checked ~ * .verbose {
display: none;
}
</style>
This specification is rather long.
To make it easier to read and focus on a particular area,
a few checkboxes are provided below.
Checking them hides part of the specification.
This is only meant as a reading aid,
the specification remains the full document.
<input type=checkbox id=api-check> <label for=api-check>Hide JavaScript APIs, including events</label><br>
<input type=checkbox id=cssapi-check> <label for=cssapi-check>Hide CSS properties that enable selecting behavior variants, and related information</label><br>
<input type=checkbox id=verbose-check> <label for=verbose-check>Hide informative sections that explain and summarise normative sections without adding more information</label><br>
<h2 id="intro" class=non-normative>
Introduction</h2>
<em>This section is not normative.</em>
Historically, most browsers have not offered features to let users move the focus directionally.
Some, such as TV browsers, have enabled users to move the focus using the arrow keys out of necessity,
since no other input mechanism is available on a typical TV remote control.
Others, have enabled different key combinations to control spatial navigation,
such as pressing the <code class=key>Shift</code> key together with arrow keys.
This ability to move around the page directionally is called <dfn lt="spatial navigation | spatialNavigation" export>spatial navigation</dfn>.
<a>Spatial navigation</a> can be useful for a web page built using a grid-like layout,
or other predominantly non linear layouts.
The figure below represents a photo gallery arranged in a grid layout.
If the user presses the <code class=key>Tab</code> key to move focus,
they need to press the key many times to reach the desired element.
Also, the grid layout may arrange the layout of elements independently of their source order.
Therefore sequential navigation using the <code class=key>Tab</code> key makes focus navigation unpredictable.
In contrast, <a>spatial navigation</a> moves the focus among focusable elements
depending on their position
allowing it to address problems encountered with sequential navigation.
<figure>
<img alt="When elements are laid out in a grid pattern, spatial navigation makes it much easier to predict and control where focus should move to." src="images/spatnav-enable.png" style="width: 500px;"/>
<figcaption>Application using a grid-like layout.</figcaption>
</figure>
While arrow keys are naturally suited to control spatial navigation,
no previous specification describes how that should work,
or how it may be controlled.
<span class=api>This specification introduces a processing model for spatial navigation,
as well as APIs
enabling authors to control and override how spatial navigation works.</span>
Note: Some aspects of this specification, such as the JavaScript Events and APIs
could also be extended to sequential navigation,
in order to make sure that keyboard navigation in general
has a consistent and well defined model.
Note: As a general principle,
keyboard navigation,
and spatial navigation in particular,
should be possible to use and control without JavaScript<span class=cssapi>,
and declarative solutions are therefore preferred.
Since spatial navigation depends on layout,
that means CSS is typically the right mechanism to define
spatial navigation related controls</span>.
<span class=api>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.
More declarative features may be added later,
based on feedback and experience acquired through such JavaScript usage.</span>
Note: A few features are marked <dfn noexport>at-risk</dfn>.
The editors of this specification believe
they represent an important part of the user or author experience
of the features defined in specification.
At the same time, the core functionality of this specification
can be implemented without implementing these
so it seems possible that implementors may choose to down-prioritize them
to reduce the scope of a first implementation.
While it is hoped that these features will be implemented as well,
they are marked at-risk in recognition that they might not be at first.
<h2 id=interaction>
Module interaction</h2>
This document depends on the Infra Standard [[!infra]].
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119. [[!RFC2119]]
<div class=verbose>
<h2 id=overview class=non-normative>
Overview</h2>
<em>This section is not normative.</em>
Using a UA-defined mechanism
(typically arrow keys, possibly in combination with modifier keys like <code class=key>Shift</code> or <code class=key>Control</code>),
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 <a>spatial navigation focus 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>
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
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,
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,
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.
<div class=api>
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 <a href="https://github.com/extensibleweb/manifesto">Extensible Web</a> 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.
</div>
<div class='example'>
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.
<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>
</figure>
On the left of figure 2, "Box 2" is focused.
Pressing the <code class=key>ArrowDown</code> key moves focus to
"Box 3" without scrolling because "Box 3" is visible in the <a>scrollport</a> of the <a>spatial navigation focus 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>
</figure>
On the first of figure 3, under "Box 3", there isn't any visible element in the <a>scrollport</a>.
Therefore, the effect of pressing the <code class=key>ArrowDown</code> is to scroll down, as shown in the second.
The next press of the <code class=key>ArrowDown</code> key makes "Box 4" come into the <a>scrollport</a>,
and the focus will move to it when there is additional pressing the <code class=key>ArrowDown</code>, as the fourth.
This example uses the markup as follows:
<pre class="lang-css">
#scroller {
width: 700px;
height: 700px;
overflow-x: hidden;
overflow-y: auto;
}
.box {
width: 150px;
height: 110px;
background-color: blue;
}
.box:focus {
background-color: red;
}
</pre>
<pre class="lang-html">
<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>
</pre>
</div>
</div>
<h2 id=triggering>
Triggering Spatial Navigation</h2>
When the user triggers spatial navigation in a given direction,
the User Agent must run the <a>spatial navigation steps</a> in that direction.
This specification does not define what UI mechanism User Agents should offer to users to trigger spatial navigation.
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 devices operated with a game controller,
will use spatial navigation as their primary or exclusive navigation mechanism.
</div>
Although it is possible for User Agents
to implement the processing model and APIs defined by the specification
without giving any direct means to the user to trigger spatial navigation themselves,
this specification recommends not to do so:
User Agents should offer a means for users to trigger spatial navigation directly,
without having to use the APIs.
Note: Conversely, authors should assume that spatial navigation may be triggered
by the UA in response to user actions
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}},
then that 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.
<div class=example>
Gaming devices may trigger spatial navigation based on pressing the D-pad.
This would result in firing a <a event>keydown</a> event
with the key set to one of
<code class=key>ArrowDown</code>,
<code class=key>ArrowLeft</code>,
<code class=key>ArrowRight</code>,
or <code class=key>ArrowUp</code>,
followed if not canceled by running the <a>spatial navigation steps</a><span class=api>,
including firing the relevant {{NavigationEvent}}s</span>.
A User Agent on a desktop computer that triggers spatial navigation
using the arrow keys of the keyboard
would follow the same sequence.
</div>
* If the mechanism the user must use to trigger spatial navigation
would in some contexts trigger other actions,
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.
<div class=example>
In a User Agent that triggers spatial navigation
using the arrow keys without modifier keys,
and uses these same arrow keys to move
the text insertion caret when an editable element is focused,
the arrow keys should by default to moving the caret.
Spatial navigation would only be triggered by the arrow keys
when the focused element is not editable,
or when it is editable but the caret cannot move any further in the requested direction.
</div>
An exception is made for scrolling:
since spatial navigation itself handles scrolling
(in addition to moving the focus)
User Agents should not offer the same mechanism to trigger both spatial navigation
and a scrolling behavior separate from spatial navigation.
UAs may however, offer a way for the user to switch between different modes,
or offer both based on different UI mechanism.
<div class=example>
A User Agent may have a setting to let the user choose
between using the arrow keys without modifier keys
for spatial navigation or for scrolling.
Another one may offer scrolling on arrow keys without modifiers,
and spatial navigation on arrow keys when pressed together
with the <code class=key>Shift</code> key,
or on the <code class=key>W</code> <code class=key>A</code> <code class=key>S</code> <code class=key>D</code> keys.
Offering only spatial navigation or only scrolling
as responses to pressing arrow keys would also be possibilities.
</div>
<div class=api>
<h2 id="js-api">
JavaScript API</h2>
<h3 id=high-level-api>
Triggering Navigation Programmatically</h3>
The {{Window/navigate()}} method enables the author to trigger spatial navigation programatically,
as if the user had done so manually
(for instance, by pressing the arrow keys in a browser where that is the way to trigger spatial navigation).
Note: As this triggers the same
F882
processing model as a manual navigation,
all the same results should be expected:
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 UA,
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
(e.g. load more content in an infinite scroller) then resume where they cancelled.
Note: This API is also useful for testing purposes,
as there is no other way to trigger spatial navigation
that does not depend on vendor specific UI conventions.
<pre class="idl">
enum SpatialNavigationDirection {
"up",
"down",
"left",
"right",
};
partial interface Window {
void navigate(SpatialNavigationDirection dir);
};
</pre>
<div algorithm="windowNavigate steps">
The {{Window/navigate()}} method must follow these steps:
If <var>dir</var> is <code>"up"</code>, <code>"down"</code>, <code>"left"</code>, or <code>"right"</code>,
run the <a>spatial navigation steps</a> in direction <var>dir</var>.
Issue(3387): The name of this API is under discussion
</div>
<h3 id=low-level-api>
Low level APIs</h3>
Note: These APIs are designed to be low level constructs following the processing model closely.
As such, they should be easy to use by authors who want to extend or override the way spatial navigation works.
<pre class="idl">
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);
};
</pre>
Note: The way the direction is expressed allows us to expand to more than 4-way navigation
later of if this is found necessary.
More directional keywords or a numerical angle could be added.
Note: the {{focusableAreas()}} and {{getSpatialNavigationContainer()}} methods are <a>at-risk</a>.
<div algorithm="getSpatialNavigationContainer steps">
The {{Element/getSpatialNavigationContainer()}} method must follow 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.
</div>
<div algorithm="focusableAreas steps">
The {{Element/focusableAreas()}} method must follow these steps:
1. Let <var>v</var> be <code>false</code>
if the argument's {{FocusableAreasOptions/mode}} attribute if present and equal to <code>"all"</code>,
or <code>true</code> otherwise.
4. Let <var>areas</var> be the result of <a>finding focusable areas</a> within the element with the visibleOnly argument set to <var>v</var>
5. 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>.
6. Return <var>anchors</var>
</div>
<div algorithm="spatialNavigationSearch steps">
The {{Element/spatialNavigationSearch()}} method must follow these steps:
1. Let <var>d</var> be the argument's {{SpatialNavigationSearchOptions/dir}} attribute
2. If the argument's {{SpatialNavigationSearchOptions/candidates}} attribute is not <code>null</code>,
then let <var>areas</var> be that attribute,
else, let <var>areas</var> be the result of <a>finding focusable areas</a>
within the argument's {{SpatialNavigationSearchOptions/container}} attribute is not <code>null</code>,
or the element's nearest <a>spatial navigation container</a> ancestor
4. Return the result of <a>selecting the best candidate</a> within <var>areas</var> in direction <var>d</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 none are found, this does not climb further up the ancestry chain,
and the result will be <code>null</code>.</strong>
</div>
<div class=example id=focus-only>
The following code changes the behavior of spatial navigation
from scrolling when there is no focusable element visible,
to jumping to focusable elements even when they are not visible.
<pre><code highlight=javascript>
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();
});
</code></pre>
</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 transfered to it.
<pre><code highlight=javascript>
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();
});
</code></pre>
</div>
<div class=example id=loop>
The following code changes the behavior of spatial navigation
to trap the focus within a spatial navigation container:
when no further focusable elements can be found in the requested direcition
and the spatial navigation container cannot be scrolled any futher,
we loop back to the other side instead of searching outside of it,
either by focusing or scrolling depending on what is available.
The focus can still be moved outside by sequential navigation,
mouse interaction,
programatic calls to {{focus()}}…
<pre><code highlight=javascript>
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();
});
</code></pre>
</div>
</div>
<div class=api>
<h2 id="events-navigationevent">
Navigation Events</h2>
<h3 id="interface-focusevent">
Interface NavigationEvent</h3>
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.
<pre class=idl>
[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;
};
</pre>
<div class=verbose>
<h3 id="events-nav-type" class="non-normative">
Navigation Event Types</h3>
<em>This section and its subsections are not normative.</em>
The Navigation event types are summarized below.
For full normative details, see [[#processing-model]].
<h4 id="event-type-navbeforefocus" class="non-normative">
<dfn event for=NavigationEvent>navbeforefocus</dfn></h4>
The <a event>navbeforefocus</a> event occurs before spatial navigation changes the focus.
<table class="def">
<tbody>
<tr>
<th>Type
<td><strong><code>navbeforefocus</code></strong>
<tr>
<th>Interface
<td>{{NavigationEvent}}
<tr>
<th>Bubbles
<td>Yes
<tr>
<th>Cancelable
<td>Yes
<tr>
<th>Attributes of the event
<td><dl>
<dt>{{NavigationEvent}}.{{NavigationEvent/relatedTarget}}
<dd>The DOM anchor of the focusable area that will be focused
<dt>{{NavigationEvent}}.{{NavigationEvent/dir}}
<dd>The direction of the navigation as requested by the user
</dl>
</tbody>
</table>
<div class='example'>
This example shows the [[UI-EVENTS#event-order]] when pressing the <code class=key>ArrowRight</code>
key.
For the sake of keeping the description simple,
this example assumes a UA where spatial navigation is triggered using arrow keys.
<table class="complex data">
<thead>
<tr>
<th>
<th>Event type
<th>{{KeyboardEvent}}.{{KeyboardEvent/key}}
<th>Notes
</thead>
<tbody>
<tr>
<td>1
<td>keydown
<td><code class=key>ArrowRight</code>
<td>MUST be a key which can activate spatial navigation,
such as the arrow keys, or spatial navigation is not activated.
<tr>
<td>2
<td>navbeforefocus
<td>
<td>Sent if the candidates for spatial navigation is not <code>null</code>,
or this is not generated.
<tr>
<td>3
<td>focusin
<td>
<td>Sent before the target element receives focus.
<tr>
<td>4
<td>focus
<td>
<td>Sent after the target element receives focus.
</tbody>
</table>
</div>
<h4 id="event-type-navbeforescroll" class="non-normative">
<dfn event for=NavigationEvent>navbeforescroll</dfn></h4>
The <a event>navbeforescroll</a> event occurs before spatial navigation triggers scrolling.
<table class="def">
<tbody>
<tr>
<th>Type
<td><strong><code>navbeforescroll</code></strong>
<tr>
<th>Interface
<td>{{NavigationEvent}}
<tr>
<th>Bubbles
<td>Yes
<tr>
<th>Cancelable
<td>Yes
<tr>
<th>Attributes of the event
<td><dl>
<dt>{{NavigationEvent}}.{{NavigationEvent/relatedTarget}}
<dd>The element that will be scrolled if the event is not canceled
<dt>{{NavigationEvent}}.{{NavigationEvent/dir}}
<dd>The direction of the navigation as requested by the user
</dl>
</tbody>
</table>
<div class='example'>
This example shows the [[UI-EVENTS#event-order]] when pressing the <code class=key>ArrowDown</code>
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.
<figure>
<img alt="An image about navbeforescroll" src="images/navbeforescroll-example-1.png" style="width: 200px;"/>
<figcaption>"Box 2" gains the focus and there isn't any candidate in a downward direction
in the <a>scrollport</a>.</figcaption>
</figure>
<table class="complex data">
<thead>
<tr>
<th>
<th>Event type
<th>Event target
<th><code>relatedTarget</code>
<th>Notes
</thead>
<tbody>
9E70
<tr>
<td>1
<td>keydown
<td><code>#box2</code>
<td>N/A
<td>MUST be a key which can activate spatial navigation,
such as the arrow keys,
otherwise spatial navigation is not triggered.
<tr>
<td>2
<td>navbeforescroll
<td><code>#box2</code>
<td><code>#scrollContainer</code>
<td>Sent if <code>#scrollContainer</code> doesn't contain any candidate in the <a>scrollport</a>,
otherwise this would not be generated.
</tbody>
</table>
After <a event>navbeforescroll</a> is fired, pressing the <code class=key>ArrowDown</code> key triggers scrolling
down the scrollbar like in the figure below:
<figure>
<img alt="An image of the result about navnotarget" src="images/navbeforescroll-example-2.png" style="width: 200px;"/>
<figcaption>The result of moving focus when there isn't any candidate in the <a>scrollport</a>.</figcaption>
</figure>
This example uses the markup as follows:
<pre class="lang-css">
#scrollContainer {
width: 700px;
height: 700px;
overflow-x: hidden;
overflow-y: auto;
}
.item {
width: 150px;
height: 110px;
background-color: blue;
}
.item:focus {
background-color: red;
}
</pre>
<pre class="lang-html">
<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>
</pre>
</div>
<h4 id="event-type-navnotarget" class="non-normative">
<dfn event for=NavigationEvent>navnotarget</dfn></h4>
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.
<table class="def">
<tbody>
<tr>
<th>Type
<td><strong><code>navnotarget</code></strong>
<tr>
<th>Interface
<td>{{NavigationEvent}}
<tr>
<th>Bubbles
<td>Yes
<tr>
<th>Cancelable
<td>Yes
<tr>
<th>Attributes of the event
<td><dl>
<dt>{{NavigationEvent}}.{{NavigationEvent/relatedTarget}}
<dd>The <a>spatial navigation container</a> that was searched in.
<dt>{{NavigationEvent}}.{{NavigationEvent/dir}}
<dd>The direction of the navigation as requested by the user
</dl>
</tbody>
</table>
<div class='example'>
This example shows the [[UI-EVENTS#event-order]] when pressing the <code class=key>ArrowDown</code>
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.
<figure>
<img alt="An image about navnotarget" src="images/navnotarget-example-1.png" style="width: 200px;"/>
<figcaption>Moving focus when there isn't any candidate in the
<a>scroll container</a>.</figcaption>
</figure>
<table class="complex data">
<thead>
<tr>
<th>
<th>Event type
<th>Event target
<th><code>relatedTarget</code>
<th>Notes
</thead>
<tbody>
<tr>
<td>1
<td>keydown
<td><code>#box2</code>
<td>N/A
<td>MUST be a key which can activate spatial navigation,
such as the arrow keys,
otherwise spatial navigation is not triggered.
<tr>
<td>2
<td>navnotarget
<td><code>#box2</code>
<td><code>#scrollContainer</code>
<td>Sent if <code>#scrollContainer</code> doesn't contain any candidate and
cannot be scrolled,
otherwise this would not be generated.
<tr>
<td>3
<td>navbeforefocus
<td><code>#box2</code>
<td><code>#box3</code>
<td>Sent if the candidates in <code>#container</code> is not <code>null</code>,
otherwise this would not be fired.
<tr>
<td>4
<td>focusin
<td><code>#box3</code>
<td>N/A
<td>Sent before the target element receives focus.
<tr>
<td>5
<td>focus
<td><code>#box3</code>
<td>N/A
<td>Sent after the target element receives focus.
</tbody>
</table>
The result of this example is the figure as follows:
<figure>
<img alt="An image of the result about navnotarget" src="images/navnotarget-example-2.png" style="width: 200px;"/>
<figcaption>The result of moving focus when there isn't any candidate in the <a>scrollport</a>
and <a>scroll container</a> cannot be scrolled.</figcaption>
</figure>
This example uses the markup as follows:
<pre class="lang-css">
#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;
}
</pre>
<pre class="lang-html">
<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>
</pre>
</div>
</div>
</div>
<h2 id=policy-feature>
The <a>navigation-override</a> [=policy-controlled feature=]</h2>
The <dfn>navigation-override</dfn> [=policy-controlled feature=] controls
the availability of mechanisms that enables page authors
to take control over the behavior of spatial navigation,
or to cancel it outright.
* The feature name is "<code>navigation-override</code>"
* The [=default allowlist=] for <a>navigation-override</a> is "<code>self</code>"
As defined in further details in [[#nav]],
if <a>navigation-override</a> is disabled in a document,
the navigation events (see [[#events-navigationevent]]) will not be fired.
Note: This is to prevent a hostile iframe from using these events
in order to highjack the focus.
We recognize that there exists other mechanisms predating spatial navigation
that malicious authors could use
to interfere with the user's ability to control where the focus goes.
Despite that, it seems worthwile to attempt not to increase this attack surface,
although it is possible that such attacks are already sufficiently easy to perform
that this is a lost cause.
Further feedback on this topic,
based on experience with implementation or with mitigating such attacks,
is very welcome.
<h2 id=processing-model>
Processing Model</h2>
<div class=verbose>
The [[#overview]] section gives a high level idea of how spatial navigation works,
to help readers of this specification build a general mental model.