| 1 | arrow-key-navigation [](https://travis-ci.org/nolanlawson/arrow-key-navigation)
|
| 2 | =====
|
| 3 |
|
| 4 | ## Overview
|
| 5 |
|
| 6 | `arrow-key-navigation` is a simple utility to add left/right focus navigation to a web app. It's
|
| 7 | designed for KaiOS apps but also available for any browser.
|
| 8 |
|
| 9 | The basic idea is to make the <kbd>←</kbd> and <kbd>→</kbd> keys act similar to
|
| 10 | <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd>, i.e. to change focus between focusable elements in the DOM.
|
| 11 | Since the <kbd>↑</kbd> and <kbd>↓</kbd> keys typically scroll the page in KaiOS, this is usually all you need
|
| 12 | to add basic KaiOS accessibility to an existing web app.
|
| 13 |
|
| 14 | It will also listen for the <kbd>Enter</kbd> key for certain special cases like checkbox/radio buttons. `contenteditable` and Shadow DOM are also supported.
|
| 15 |
|
| 16 | ## Install
|
| 17 |
|
| 18 | npm install --save arrow-key-navigation
|
| 19 |
|
| 20 | Or [browse unpkg.com](https://unpkg.com/browse/arrow-key-navigation/) for a list of build files.
|
| 21 |
|
| 22 | ## Usage
|
| 23 |
|
| 24 | ```js
|
| 25 | import * as arrowKeyNavigation from 'arrow-key-navigation'
|
| 26 |
|
| 27 | arrowKeyNavigation.register() // start listening for key inputs
|
| 28 | arrowKeyNavigation.unregister() // stop listening
|
| 29 | ```
|
| 30 |
|
| 31 | ## Focus traps
|
| 32 |
|
| 33 | To build [an accessible dialog](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal), you need to
|
| 34 | "trap" focus inside of the dialog, i.e. make it so focus cannot escape the dialog while it is active. To
|
| 35 | accomplish this, you can set a "focus trap test" which takes an element as input and returns truthy/falsy
|
| 36 | to indicate that the element is a focus trap (e.g. the modal dialog root):
|
| 37 |
|
| 38 | ```js
|
| 39 | arrowKeyNavigation.setFocusTrapTest(element => {
|
| 40 | return element.classList.contains('my-dialog-class')
|
| 41 | })
|
| 42 | ```
|
| 43 |
|
| 44 | If you don't call `setFocusTrapTest()`, then `arrow-key-navigation` will assume that there are no focus traps
|
| 45 | in your app.
|
| 46 |
|
| 47 | ## Conditional or lazy loading
|
| 48 |
|
| 49 | You can choose to install this module only in KaiOS environments using logic like the following:
|
| 50 |
|
| 51 | ```js
|
| 52 | if (/KAIOS/.test(navigator.userAgent)) {
|
| 53 | import('arrow-key-navigation').then(arrowKeyNavigation => {
|
| 54 | arrowKeyNavigation.register()
|
| 55 | })
|
| 56 | }
|
| 57 | ```
|
| 58 |
|
| 59 | ## Contributing
|
| 60 |
|
| 61 | ### Build
|
| 62 |
|
| 63 | npm run build
|
| 64 |
|
| 65 | ### Lint
|
| 66 |
|
| 67 | npm run lint
|
| 68 |
|
| 69 | ### Fix most lint issues
|
| 70 |
|
| 71 | npm run lint:fix
|
| 72 |
|
| 73 | ### Test
|
| 74 |
|
| 75 | npm test
|
| 76 |
|
| 77 | ### Code coverage
|
| 78 |
|
| 79 | npm run cover
|
| 80 |
|
| 81 | ### Manual KaiOS app test
|
| 82 |
|
| 83 | The `index.html` and `manifest.webapp` files are designed for a quick-and-dirty KaiOS app test.
|
| 84 |
|
| 85 | Run `npm run build` and then install the root directory as a packaged KaiOS app to test it.
|