npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

keyboard-i18n

v0.2.0

Published

Internationalization and localization utils for keyboard shortcuts

Downloads

425

Readme

keyboard-i18n

Internationalization and localization utils for keyboard shortcuts on web browsers.

Why

Dealing with various keyboard layouts can be tricky when setting up shortcuts because not all keyboards are the same. This leads to two main challenges:

Firstly, shortcuts might need to be based on either the character a key represents or its physical location on the keyboard.

For instance, Ctrl A is often used to select all text because "A" stands for "all". However, in gaming, keys like W A S D are used for movement, and here, the actual characters on the keys aren't as important as their positions.

To address this, keyboard-i18n lets you define shortcuts using either the KeyboardEvent.key for characters or KeyboardEvent.code for key positions. For example, ctrl+a would be set using KeyboardEvent.key, and ctrl+KeyA would use KeyboardEvent.code.

Secondly, the same shortcuts can behave differently on various keyboard layouts.

For example, shortcuts for navigating back and forward like Ctrl [ and Ctrl ] change drastically between US, German and Latin American layouts.

keyboard-i18n solves this by providing a localizer that maps shortcuts from the US layout to other layouts, specifically adjusting code including BracketLeft, BracketRight and Slash.

Features

  • Auto detect keyboard layout on supported browsers.
  • Manually specify keyboard layout.
  • Keyboard event handler and shortcut formatter.
  • Full TypeScript support.

Install

npm install keyboard-i18n keyboard-layout-map

keyboard-layout-map is a peer dependency of this package.

Usage

Define a Shortcut

A shortcut is a string that combines zero or more modifiers with a KeyboardEvent.key or KeyboardEvent.code, separated by +.

Modifiers

  • "mod": Command on macOS, Ctrl on Windows
  • "ctrl": Control on macOS, Ctrl on Windows
  • "alt": Option on macOS, Alt on Windows
  • "meta": Command on macOS, Win on Windows
  • "shift": Shift on all platforms

Using KeyboardEvent.key

Examples include single characters or symbols like "a", "9", or "/".

Using KeyboardEvent.code

Examples include "KeyA", "Digit9", or "Slash".

Examples

  • "Escape" triggers the Escape key.
  • "mod+KeyA" results in Command A on macOS and Ctrl A on Windows.
  • "ctrl+shift+a" results in Ctrl Shift A on all platforms.
  • "mod+BracketLeft" results in Command [ on macOS with a US layout, and Ctrl Ö on Windows with a German layout.

TypeScript support

keyboard-i18n uses TypeScript to provide type safety, so that you can catch potential errors at compile time.

import type { KeyboardShortcut } from 'keyboard-i18n'

const shortcut: KeyboardShortcut = 'Mod+Shift+arrow_right'
//     ^ Type '"Mod+Shift+arrow_right"' is not assignable to type 'KeyboardShortcut'.
//       Did you mean '"mod+shift+ArrowRight"'? ts(2820)

Create an Event Handler

You can create an event handler for a shortcut using the createHandler function.

import { createHandler } from 'keyboard-i18n'

const handler = createHandler('mod+a', (event: KeyboardEvent) => {
  console.log('mod+a is pressed')
})

document.addEventListener('keydown', handler)

You can also handle multiple shortcuts with a single event handler.

import { createHandler } from 'keyboard-i18n'

const handler = createHandler(
  ['ctrl+a', 'ctrl+shift+a'],
  (event: KeyboardEvent) => {
    console.log('ctrl+a or ctrl+shift+a is pressed')
  },
)

document.addEventListener('keydown', handler)

Create an Event Checker

If you want more control over the event handling, you can use createChecker to check if a keyboard event matches a specific shortcut.

import { createChecker } from 'keyboard-i18n'

const checker = createChecker('Escape')

const isEscapePressed: boolean = checker(event)

Create a Shortcut Formater

You can format a shortcut based on the current platform and keyboard layout using the createFormatter function.

import { createFormatter } from 'keyboard-i18n'

const formatter = createFormatter('mod+shift+BracketLeft')

const formatted: string[] = formatter()
// On macOS with US layout, the shortcut is formatted as ["Shift", "Command", "["]
// On macOS with German layout, the shortcut is formatted as ["Ctrl", "Shift", "Ö"]

Customize the Keyboard Layout

By default, keyboard-i18n will use the experimental Keyboard API to get the current keyboard layout.

For those browsers that don't support the Keyboard API, you can pass a layout manually to createHandler, createChecker and createFormatter.

import { createFormatter, type } from 'keyboard-i18n'
import * as layouts from 'keyboard-layout-map/layouts'

createHandler('mod+shift+BracketLeft', { layout: layouts.German })

API references

Please check the API references for full list of APIs.

License

MIT