dom-keyboard v1.0.1

DOM Keyboard

An in-browser representation of a keyboard built out of DOM nodes. It includes simple methods for interacting with key presses and making visual changes to the keyboard along side them. Open-source with zero dependencies.

This project is open-source! Feel free to submit pull requests or suggest changes, and check the github issues for ways to contribute!

Install

npm install dom-keyboard

Table of Contents

• Initializing

  • options object

• DOMKeyboard object

  • Properties

    • keys
    • node

  • Methods

    • getKey
    • onKeyDown
    • onKeyUp
    • press
    • typeInto

• Key object

  • Properties
    • character
    • code
    • node
    • shift
    • side
    • type
  • Methods
    • down
    • up
    • match
    • press
    • style

Initializing

Call the DOMKeyboard constructor function with the width you want the keyboard to be, an optional id attribute, and an optional options object. The width must be a percentage. The id will be the DOM id of the keyboard. More on the options object below.

The keyboard object has a node property that returns the DOM node for the keybaord.

const kb = new DOMKeyboard("100%", "my-keyboard", [options]);
document.body.appendChild(kb.node);

options

A javascript object with the following optional properties:

• reactToKeyPress boolean Default: true Determines if the keys of the DOMKeyboard are pressed when a user presses a key on their keybaord.

(Currently there is only one option, more are set to be added in future updates)

DOMKeyboard

Properties

• keys An array of all of the Key objects.

• node The DOM <div> node holding the keyboard.

Methods

• getKey(str) >> Key Takes a string as an argument and uses Key.prototype.match to return the first matching Key.

• onKeyDown([...matches], callback) Specifies a callback to execute when a matching key is pressed on a user's keyboard. The callback receives the matching Key object. matches can be a string matching any property of a Key object, a series of such strings, or an array of such strings.

  kb.onKeyDown("t", (key) => console.log(key.code));
  // When the "t" is pressed "KeyT" is logged
  
  kb.onKeyDown("t", "R", "KeyE", (key) => console.log(key.code));
  // When the "t", "r", or "e" is pressed, the callback is executed
  
  kb.onKeyDown([["t", "R", "number"], (key) => console.log(key.code));
  // When the "t", "r", or any number key is pressed, the callback is executed

• onKeyUp([...matches], callback) Specifies a callback to execute when a matching key is released on a user's keyboard. The callback receives the matching Key object. See onKeyDown for details.

• press(key, [time = 100], [calback]) >> Promise Presses a key on the DOMKeyboard and releases it after time milliseconds. The returned Promise is resolved after the key has been pressed and released in the DOMKeyboard. key is a string that uses Key.prototype.match to find all matching keys. A shift key will also be pressed if key matches the shift property of the matching key. callback is an optional function that is called as each key is pressed. It is passed the Key object that is being pressed as an argument. time and callback are all optional. callback must be the last argument if provided. NOTE: the press method does not create a keypress event in the DOM.

• typeInto(node, text, [speed = 100], [variability = 0], [callback]) >> Promise Enters characters into node one character at a time while pressing the matching key on the DOMKeyboard. DOMKeyboard.prototype.press is used to press the keys. node is a DOM node. text is a string that will be added one character at a time to the end of node's innerHTML speed is the time between key presses in milliseconds variability is a time in milliseconds that the speed will randomly vary by to imitate inconsistent typing speed. If provided, a random number between speed - variability and speed + variability will be chosen for each key press. A speed must be specified in order to provide a variability callback is an optional function that is called as each key is pressed. It is passed the Key object that is being pressed as an argument. speed, variability, and callback are all optional. callback must be the last argument if provided. The returned Promise is resolved after the full text has been typed into the node

Key

Properties

• character The main character for the key. A string.

• code The KeyboardEvent.key value for the key. A String

• node The DOM <div> node holding the key.

• shift The character for if the key is pressed while shift is held. A String

• side The side of the keyboard that the key is on. Either the string "Left" or "Right"

• type The type of the key's character. A string. One of the following:

  • "letter"
  • "number"
  • "control"
  • "special"
  • "arrow"

Methods

• down([time = 100]) >> Promise Adds the keyboard-key-down CSS class to the key's node. The returned Promise is resolved after time milliseconds.

• up([time = 100]) >> Promise Removes the keyboard-key-down CSS class to the key's node. The returned Promise is resolved after time milliseconds.

• match(selected) >> boolean Checks whether selected matches the key's code, character, shift, or type property selected can be a string or array of strings.

• press([time = 100]) >> Promise Calls the Key.prototype.down method then delays time milliseconds before calling Key.prototype.up The returned Promise is resolved after the key down and key up animaition have finished.

• style(cssStyle, newValue) Sets inline styles on the key's node using it's DOM Style Object. To unset any added styles, set the value to null.

  const t = kb.getKey("t");
  t.style("backgroundColor", "red")
  t.style("backgroundColor", null)