NextKeyboard: Simplified Keyboard Event Handling

Introduction

NextKeyboard is a flexible and robust library designed to simplify keyboard event handling in React and JavaScript/TypeScript projects. It supports monitoring individual keys, key combinations, and global listeners, with a focus on extensibility and developer experience.

Installation

Install the library using npm or yarn:

npm install nextkeyboard

yarn add nextkeyboard

Features

• Monitor individual keys, combinations, or groups of keys.
• Supports global listeners for all keyboard events.
• Handles modifiers like Command, Control, Alt, and Meta.
• Predefined keys for easy usage via Keyboard.
• Simple integration with React and TypeScript.

Usage

Basic Key Monitoring

Monitor when a key is pressed or released:

import { Keyboard } from "nextkeyboard";

const { LeftShift } = Keyboard;

LeftShift.onPress((event) => {
  console.log("LeftShift key pressed!");
});

LeftShift.onRelease((event) => {
  console.log("LeftShift key released!");
});

Hotkeys (Key Combinations)

Monitor combinations of keys such as Command + A:

import { Hotkeys, Keyboard } from "nextkeyboard";

const { A, LeftCommand } = Keyboard;

const commandAndA = new Hotkeys([LeftCommand, A]);

commandAndA.onPress(() => {
  console.log("Command + A was pressed!");
});

commandAndA.onRelease(() => {
  console.log("Command + A was released!");
});

SomeOfKeys (Any Key in a Group)

Monitor when any key in a group is pressed or released:

import { SomeOfKeys, Keyboard } from "nextkeyboard";

const { LeftCommand, RightCommand } = Keyboard;

const commandKeys = new SomeOfKeys([LeftCommand, RightCommand]);

commandKeys.onPress(() => {
  console.log("Either Command key was pressed!");
});

commandKeys.onRelease(() => {
  console.log("Either Command key was released!");
});

Integration: SomeOfKeys with Hotkeys

Monitor combinations involving key groups and specific keys:

Example: Command (Left or Right) + Win (Meta) + "B"

import { Hotkeys, SomeOfKeys, Keyboard } from "nextkeyboard";

const { LeftCommand, RightCommand, LeftMeta, RightMeta, B } = Keyboard;

const commandKeys = new SomeOfKeys([LeftCommand, RightCommand]);
const metaKeys = new SomeOfKeys([LeftMeta, RightMeta]);

const commandMetaB = new Hotkeys([commandKeys, metaKeys, B]);

commandMetaB.onPress(() => {
  console.log(
    "Command (Left or Right) + Meta (Left or Right) + B was pressed!"
  );
});

commandMetaB.onRelease(() => {
  console.log(
    "Command (Left or Right) + Meta (Left or Right) + B was released!"
  );
});

Global Keyboard Listener

The GlobalKeyboardListener monitors all keys globally and allows handling both keydown and keyup events for any key.

import { GlobalKeyboardListener, Keyboard } from "nextkeyboard";

const { A, LeftCommand } = Keyboard;

const listener = new GlobalKeyboardListener();

// Handle keydown globally
listener.onKeydown((event, key) => {
  console.log(`${key.key} was pressed globally!`);
});

// Handle keyup globally
listener.onKeyup((event, key) => {
  console.log(`${key.key} was released globally!`);
});

// Cleanup listeners when no longer needed
listener.cleanup();

API Reference

Class GlobalKeyboardListener

Monitors all keys globally.

| Method | Description | | ------------------------------ | --------------------------------------------------------- | | onKeydown(callback) | Registers a global callback for all keydown events. | | onKeyup(callback) | Registers a global callback for all keyup events. | | setCallbackOf(key, callback) | Registers a callback for a specific key. | | cleanup() | Removes all global listeners configured for the instance. |

Class Key

Represents an individual key.

| Method | Description | | --------------------- | ------------------------------------------------------------------ | | onPress(callback) | Registers a callback for when the key is pressed. | | onRelease(callback) | Registers a callback for when the key is released. | | isKeyPressed() | Returns true if the key is currently pressed. | | getState() | Returns true if the key is in an active state (e.g., Caps Lock). | | resetListeners() | Removes and reinitializes listeners for the key. |

Class Hotkeys

Manages key combinations.

| Method | Description | | --------------------- | ---------------------------------------------------------- | | onPress(callback) | Registers a callback for when the combination is pressed. | | onRelease(callback) | Registers a callback for when the combination is released. | | resetListeners() | Removes and reinitializes listeners for the combination. |

Class SomeOfKeys

Monitors any key in a group.

| Method | Description | | --------------------- | --------------------------------------------------------------- | | onPress(callback) | Registers a callback for when any key in the group is pressed. | | onRelease(callback) | Registers a callback for when any key in the group is released. | | resetListeners() | Removes and reinitializes listeners for the group. |

Predefined Keys

The library includes predefined constants for common keys, accessible via Keyboard:

• Letters: A, B, ..., Z.
• Numbers: Zero, One, ..., Nine.
• Modifiers: Shift, Control, Alt, Meta, Command.
• Navigation: ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, etc.
• Function Keys: F1, F2, ..., F12.
• State Keys: CapsLock, NumLock, ScrollLock, etc.

Example usage:

import { Keyboard } from "nextkeyboard";

const { A, LeftCommand, F1 } = Keyboard;

A.onPress(() => console.log("A was pressed!"));
LeftCommand.onPress(() => console.log("Left Command was pressed!"));
F1.onPress(() => console.log("F1 was pressed!"));

Contributing

Steps to Contribute

1. Clone the repository:

   git clone https://github.com/silvaezequias/nextkeyboard.git

2. Install dependencies:

   npm install

3. Run the project in development mode:

   npm run dev

4. Make your changes and submit a pull request!

License

This project is licensed under the MIT License. See the LICENSE file for details.