Add a special `Mod` modifier that translates to either `Meta` on Mac or `Control` on other platforms

[theinterned]

resolves #56

What is this?

On Mac, Meta (command) is frequently used as the modifier for shortcuts: on Windows and Linux Control is used instead. Therefor in order to correctly localize hotkeys, it's common to see code that handles swapping platform-specific modifier keys in users of this library. It would make sense to do this in the library and eliminate all that custom code!

Mod modifier

This PR adds support for using a special Mod modifier that automatically localizes to Control on Windows / Linux, or Meta on Mac.

The rational is that this allows an easy way to define cross-platform shortcuts. Without this feature, an implementer would have to either support both Control and Meta forms of shortcuts, or write their own code to handle swapping these.

Consistent sorting of modifiers

Although it was only documented in #62 , hotkey has always had a hard requirement that modifiers are sorted in the order that matches the order eventToHotkeyString formats the modifier keys from an event.

Since the Control and Meta keys appear in different places in the hotkey string, in order to support the Mod key, I also had to ensure that modifiers in a hotkey string are consistently sorted before comparoson to an event that is serialized via eventToHotkeyString.

So this PR also removes the hard requirement that modifiers be sorted in a strict order.

Approach

I chose to add a new normalizeHotkey function to handle localizing the Mod key and sorting the modifiers. This normalizeHotkey is applied to the hotkey string in the expandHotkeyToEdges before it is added to the Trie. This ensures that when we later look for a serialized event in the trie, the hotkey string is already normalized to match the serialized output of eventToHotkeyString.

Limitations

The "Mod" key is not currently compatible with Shift and Alt modifiers.

Because Mac treats event.key differently than Windows or Linux when the Shift and / or Alt key is pressed, it means that the Mod modifier will not localize as expected when paired with Shift. I have noted this limitation in the tests and in the README. I was hoping to address #54 and #68 in this PR too but decided to defer to keep the size of the PR down.

TODO

• [x] implement normalizeHotkey function to allow comparing a eventToHotkey string to a hotkey string containing a Mod character.
  • [x] Account for hotkeys that contain both Control and Meta!
  • [ ] Account for how Mac lowercases event.key when Meta+Shift are pressed.
• [x] Make normalizeHotkey platform specific: convert Mod to Meta on Mac or Control on other platforms.
• [x] Use this normalizeHotkey to map hotkey to Trie in expandHotkeyToEdges so that the Trie contains the platform-specific modifier: use it to allow keyDownHandler to match events to hotkey strings containing the Mod alias.
• [x] Add docs about Mod character
  • [x] Add special notes about Shift etc?