# finger-roll

> Provides information about keyboard layouts

Latest version **0.1.3** (published 2018-02-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install finger-roll
pnpm add finger-roll
yarn add finger-roll
bun add finger-roll
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.3 |
| Published | 2018-02-23 |
| First published | 2018-02-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 24.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Mike Cluck |
| Maintainers | mcluck |
| Keywords | keyboard-layouts, fat-fingering |

## Links

- npm: https://www.npmjs.com/package/finger-roll
- Repository: https://github.com/MCluck90/finger-roll
- Homepage: https://github.com/MCluck90/finger-roll#readme
- Issues: https://github.com/MCluck90/finger-roll/issues
- npm.io page: https://npm.io/package/finger-roll

## Recent versions

- 0.1.3 (latest) — 2018-02-23
- 0.1.1 — 2018-02-22
- 0.1.0 — 2018-02-22

## README

# Finger Roll

This goes out to all the people who have fat fingered something on their keyboard.

Finger Roll provides information about keyboard layouts. Specifically, it will let you know
which keys are close to another on the keyboard (`'A'` is close to `'S'` on a QWERTY layout, for example).

## Example

```js
const FingerRoll = require('finger-roll');

const fingerRoll = new FingerRoll('us-qwerty');

fingerRoll.getAdjacentKeys('F'); // [ 'C', 'D', 'G', 'R', 'T', 'V' ]
fingerRoll.distanceBetween('A', 'L'); // 8
```

## Supported Keyboard Layouts

* US QWERTY

## API

*Note:* All examples are given assuming as US QWERTY layout since that's what I type with.

* `FingerRoll(string layout = 'us-qwerty') -> FingerRoll`
	* Creates a new instance of FingerRoll with the designated keyboard layout.
* `toKeyFormat(string key) -> string`
	* Converts a key name obtained from something like `event.key` in a `keypress` event to the internal format. Example: `toKeyFormat('a') == 'A'`
	* All other methods use this internally so if you only use the given API then you won't need this. However, it may be useful when working with the results of other methods.
* `getAlternate(string key) -> string?`
	* Returns the equivalent key as if you were holding down Shift
	* Returns `null` if it doesn't recognize the key
	* Example: `getAlternate('1') == '!'`
	* Example: `getAlternate('not a key') == null`
* `getAdjacentKeys(string key) -> string[]`
	* Returns an array with all keys surrounding the given one
	* Example: `getAdjacentKeys('F') == [ 'C', 'D', 'G', 'R', 'T', 'V' ]`
* `isAdjacent(string keyA, string keyB) -> bool`
	* Reports whether two keys are next to each other or not
	* Example: `isAdjacent('G', 'H') == true`
	* Example: `isAdjacent('G', 'J') == false`
* `distanceBetween(string source, string destination) -> number?`
	* Returns the distance between two keys
	* Returns `null` if it doesn't recognize either the `source` or `destination`
	* Example: `distanceBetween('A', 'L') == 8`
	* Example: `distanceBetween('not a key', 'L') == null`
* `distanceToAll(string source) -> ({ [key]: number })?`
	* Returns an object indicating the distance from one key to any other key on the keyboard
	* Returns `null` if it doesn't recognize the `source` key
	* Example: `distanceToAll('A')['D'] == 2`
	* Example: `distanceToAll('not a key') == null`
* `pathTo(string source, string destination) -> string[]?`
	* Returns an array indicating the path to take to go between two keys.
	* Returns `null` if it doesn't recognize either the `source` or `destination`
	* Example: `pathTo('A', 'F') == ['A', 'S', 'D', 'F']`
	* Example: `pathTo('not a key', 'F') == null`
* `pathToAll(string source) -> ({ [key]: string })?`
	* Returns an object indicating which key to follow to return to the `source`
	* Returns `null` if it doesn't recognize the `source`
	* Example: `pathToAll('A')['F'] == 'D'`
	* Example: `pathToAll('not a key') == null`

## Contributing

If you'd like to create a mapping for a different keyboard layout, look in the `layouts` folder. I recommend using the `us-qwerty.js` file for reference. It basically comes down to stating which keys are neighbors for every other key. Use the names given by a `keypress` event in the DOM as reference. The goal is to be able to plug this straight into a `keypress` (or similar) event and have it work out-of-the-box.

---
_Source: https://npm.io/package/finger-roll · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
