Skip to content

README.md

Latest commit

 

History

History
200 lines (164 loc) · 8 KB

README.md

File metadata and controls

200 lines (164 loc) · 8 KB

Spatial Navigation Polyfill

What is this?

This is a JavaScript implementation of the Spatial Navigation Specification.

It enables users to navigate the page using the arrow keys of the keyboard (or remote control, or game pad…), instead of (or in addition to) the Tab key, the mouse cursor, or the touch screen.

Depending on the content and layout of the page, pressing one of the directional keys will either move the focus in that direction, or scroll the page, as appropriate.

For more details, see the specification or its explainer document.

Why Use the Polyfill

Eventually, we expect spatial navigation to be natively supported by browsers. However, this is not yet the case.

Until then, authors who wish to experiment with providing this feature to their users can include this polyfill in their page.

It can also be used for people interested in reviewing the specification it order to test the behavior it defines in various situations.

Current Status

Browser Support

With the polyfill, the Spatial Navigation has been tested and known to work in the following browsers:

Chrome
49+ 		Firefox
61+ 		Safari
11.1+ 		Edge
17+ 		Opera
36+

Remaining Issues

The polyfill is not yet complete. It roughly matches the specification but does not yet follow it closely, and has a number of known issues.

See the list of open bugs in github.

How to Use

Installation

npm i spatial-navigation-polyfill

We recommend only using versions of the polyfill that have been published to npm, rather than cloning the repo and using the source directly. This helps ensure the version you're using is stable and thoroughly tested.

If you do want to build from source, make sure you clone the latest tag!

Including the Polyfill in a page

Include the following code in your web page, and the polyfill will be included, enabling spatial navigation.

...
    <script src="/node_modules/spatial-navigation-polyfill/polyfill/spatnav-heuristic.js"></script>
  </body>
</html>

Users can now user the keyboard's arrow keys to navigate the page.

Handling Browser Events

In the polyfill, keydown event and mouseup event are used for the spatial navigation. The event handlers of those are attached to the window object.

We recommend to use it with the polyfill as below:

  • If you want to use those event handlers for other usages besides the spatial navigation,
    • attach the event handler on the children of window object or
    • call the event handler during the capturing phase of the event.
  • If you don't want those events work with the spatial navigation, call preventDefault().

Using the APIs

The spatial navigation specification defines several JavaScript events and APIs. Using these is not necessary to use the polyfill, and users can start using the arrow keys as soon as the polyfill is included, but they can be convenient for authors who wish to override the default behavior in some cases. See the specification for more details.

Following the guidance from the W3C Technical Architecture Group, the polyfill provides these features under alternative names, to avoid interfering with the standardization process.

Standard APIs

Standard Name Polyfill Name
navbeforefocus navbeforefocusPolyfill
navbeforescroll navbeforescrollPolyfill
navnotarget navnotargetPolyfill
spatNavSearch() spatNavSearchPolyfill()
navigate() navigatePolyfill()
getSpatnavContainer() getSpatnavContainerPolyfill()
focusableAreas() focusableAreasPolyfill()

Experimental APIs

NOTE: The APIs below are non-standard and experimental features of the spatial navigation.

  • isContainer (element) :
    • Determines whether the element is a spatial Navigation container.
    • Returns true if the element is the spatial Navigation container, and false if not.
    • Parameter
      • element : Required.
        • Any element.
  • findCandidates (element, dir, option) :
    • Searchs all valid candidates for a certain direction.
    • Returns a list of elements.
    • Parameter
      • element : Required.
        • The currently focused element to search for candidates.
      • dir : Required.
        • The direction to find candidates.
        • It should be one of ['up', 'down', 'left', 'right'].
      • option : Optional.
        • Default value is {'mode': 'visible'}.
        • The FocusableAreasOptions to find candidates.
        • It should be {'mode': 'visible'} or { mode: 'all' }.
  • findNextTarget (element, dir, option) :
    • Indicates what is the best element to move the focus for a certain direction.
    • Returns the next target element.
      • If there is no target for the direction, it returns null.
      • If scrolling occurs, it returns the element itself.
    • Parameter
      • element : Required.
        • The currently focused element to search for candidates.
      • dir : Required.
        • The direction to find candidates.
        • It should be one of ['up', 'down', 'left', 'right'].
      • option : Optional.
        • Default value is {'mode': 'visible'}.
        • The FocusableAreasOptions to find candidates.
        • It should be {'mode': 'visible'} or { mode: 'all' }.
  • getDistanceFromTarget (element, candidateElement, dir) :
    • Calculates the distance between the currently focused element and a certain candiate element.
    • Parameter
      • element : Required.
        • The currently focused element to search for candidates.
      • candidateElement : Required.
        • The candidate element which may gain the focus.
      • dir : Required.
        • The direction to find candidates.
        • It should be one of ['up', 'down', 'left', 'right'].
  • setKeyMode (option) :
    • Sets which key type to use for the spatial navigation.
    • Parameter
      • option: Required.
        • It should be one of ['ARROW', 'SHIFTARROW', 'NONE'].
        • In the case of using 'NONE' value as the option, the spatial navigation feature will be turned off.

Usage in automated tests

Automated tests for the specification are written assuming standard syntax. In order to be able to use the Polyfill to run those tests, it is possible to load it in a special mode where it uses the standard names for the APIs and Events, unlike what is described in section [#using-the-apis].

It is recommended not to use this option for purposes other than runing the automated tests of the specication.

<script src="../spatnav-heuristic.js"></script>
<script>setStandardName();</script>