Never Punch Manticores

    @maulingmonkey/keyboard
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.5 • Public • Published

    mmk.keyboard

    MaulingMonkey's typescript keyboard API for consistent cross-browser keybinding, polling input for games, etc.

    What? Why?

    The vanilla browser keyboard APIs are pretty inconsistent about a lot of things. IE11's keyboardEvent.repeat lies, .code may or may not be available - and if present, has different names for the same keys across different browsers, vanilla numpad events are annoying to differentiate from other hotkeys (e.g. Shift+Numpad1 maps to key: "End"), etc.) which is annoying for roguelikes...

    Additionally, doing "the right thing" with the vanilla API isn't straightforward. A lot of webcomics I read implement page handlers for ArrowLeft / ArrowRight, which is nice. Less nice is that most of them don't think to check event.alt or other modifier keys, so their page handlers interfere with browser history navigation (Alt+ArrowLeft, Alt+ArrowRight in Chrome).

    Browser Support

    OS Browser U.S. Dvorak[1] mmkCode keypress[2]
    Windows 7 Chrome 57
    Windows 7 IE 11 ✗ [3]
    • [1] Dvorak "support" means mmkKey reports correctly the logical key pressed.
    • [2] Key press events are only partially implemented: mmkCode should be set, if available. mmkKey is not, period.
    • [3] This browser provides no API to get physical key codes - and thus cannot support mmkCode at all.

    Basic API

    // APIs for consistent results across multiple browsers
    keyboardEvent.mmkRepeat // Workaround IE11 keyboardEvent.repeat lying (always being false)
    keyboardEvent.mmkKey    // Logical key pressed               (e.g. by keyboard layout labels)
    keyboardEvent.mmkCode   // Physical key pressed if available (e.g. ignoring keyboard layout)
    
    // Combination parsing and testing
    combo = mmk.keyboard.parseSimpleKeyCombo("Alt+["); // Won't match "[" or "Ctrl+Alt+["
    combo = mmk.keyboard.parseSimpleKeyCombo("?Shift+?Ctrl+Alt+["); // Match "Alt+[" or "Ctrl+Alt+[" but not "Meta+["
    if (mmk.keyboard.isSimpleKeyCombo(keyboardEvent, combo)) { ... }
    conflicts = mmk.keyboard.systemConflictsWithSimpleKeyCombo(combo).filter(conflict => !conflict.overrideable);

    Unstablized API Bits

    What Why
    mmkRepeat Still mulling over how to handle LCtrl + RCtrl "repeats" in Chrome
    mmkKey Digits Still mulling over how to handle Digit0 vs Numpad0
    mmkCode Numpad Still mulling over how to handle Shift+Numpad 1
    mmkCode IE11 Could add fallback for some keys that doesn't rely on keyboard layout (e.g. arrows, basic numpad)
    Conflicts API Some conflict detection depends on mmkKey/mmkCode bits above
    Key.CtrlLeft Might drop sided keys if we split off a separate 'Code' field.
    Key["0"] Ambiguous - Digit0? Include Numpad0? Key based? Code based? ...
    Key["."] Punctuation is very likely to be dropped from the Key namespace at some point - too ambiguous
    parseSimpleKeyCombo Naming?
    isSimpleKeyCombo Naming?
    systemConflictsWithSimpleKeyCombo Naming? Bloody wordy.

    (Unstable here means the API is subject to change - it shouldn't crash or anything.)

    Project Scope

    Perhaps easier to say what's not in scope:

    • No "on screen keyboard" support (I should make one, but it can be a separate module)
    • No/limited automatic keyboard layout detection. Even flash doesn't have an API - I'd need to write my own native plugins? Might be able to partially bodge around it.

    Installation

    Via npm

    • Grab NPM via node.js
    • Install per project
      npm i @maulingmonkey/keyboard

    Install

    npm i @maulingmonkey/keyboard

    DownloadsWeekly Downloads

    2

    Version

    0.0.5

    License

    Apache-2.0

    Unpacked Size

    164 kB

    Total Files

    7

    Last publish

    Collaborators

    • maulingmonkey