Improve key naming / detection

[isti115]

I second the recently opened issue (#1006) by @ptxmac, the strangely named key mappings have also caught my attention, and I would consider them to be an issue with the current code, but since you asked for the topic to be moved over to a discussion, I'm responding here.

I think that the code property of KeyboardEvent that is currently in use is the proper way to go about this, as that one maps to the actual key instead of the symbol produced while typing.

To quote MDN:

The KeyboardEvent.code property represents a physical key on the keyboard (as opposed to the character generated by pressing the key). In other words, this property returns a value that isn't altered by keyboard layout or the state of the modifier keys.

Im my opinion hotkeys should "stay in place" on different layouts even if the symbols are moving around, since they are (usually) meant to be comfortable and stored in muscle memory. Let's say that my application has the combination ctrl+s bound to an action, that is a very convenient one handed gesture on most of the layouts, but in case someone would be using let's say a 40% Dvorak layout, they would have practically no way to execute the action one-handed if it moved with the letter s. (I know, that's a pretty contrived example, but you get what I mean.)

One drawback of this that I can think of is the possible disconnection from mnemonics, such as ctrl+s for "save", ctrl+a for "all", ctrl+c for "copy" and so on, but those also partially lose their value with locale changes that bring the layout variations in the first place, and to be fair, most layouts only move the symbols around, not the basic letters of the alphabet, and symbols can't serve as mnemonics anyway.

My suggestion would be to get rid of the entire mappedKeys object and mapKey function and instead use the proper names as provided here:
https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values

This would also remove the necessity for the extra complexity introduced by combinationKey and splitKey, as + and , don't appear among the list of codes anyway.

I'm interested to see what @JohannesKlauss and others think about this!

ps.: I understand that the fact that I've questioned one of the recently merged PRs (#980), opened a new issue (#1013) and am starting a discussion as well on the same day might make it seem like I'm a bit overzealous, but I can assure you that I don't have any invasive motives! I'm just very happy to see that the trends are showing that an alternative to the now more than three years ago abandoned react-hotkeys library is rising, and would like to switch to it as soon as possible, but I need some things to be fixed before I can make the transition. I would also like to ensure that the code doesn't get unnecessarily bloated or complicated, that's why I'm also questioning the importance of the recently added ignoreEventWhen option. I am very happy to see that in it's current state the library has less than 500 lines of source, only about one tenth of the previously mentioned and still most widely used react-hotkeys, which had almost 5000...

[JohannesKlauss]

I would love to do that, but here's a simple problem:
How would you then listen for a combination like option+8? This is the issue where different keyboard layouts and languages come into play, because option+8 produces a key value that is dependent on your language, layout and operating system.
On a german layout this will produce the key [ on windows and { on mac. On a british keyboard layout this will produce * as far as I know.

The approach you are suggesting is great if you want to listen to the produced key, but there are a lot of cases where you want to listen for layout independent keys.

I am leaning more and more to the conclusion that it would be best to have two hooks. One listening to key, the other one to keyCode. But then the API would get really confusing, because it is not intuitive to most devs why there is a difference in key and keyCode. I am happy to discuss this matter and appreciate any insight and proposed solution to this dilemma, since this is bothering me for a long time now. But I didn't had a sparking idea yet.

Hotkeys are hard 😄

[isti115]

That's exactly the point of the code property, which the codebase currently uses!
(There seems to be some complication on Mac though:
https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values#code_values_on_mac)

As opposed to the key value, which describes the produced symbol, the code property gives you the actual physical key that was pressed. I think that I have found a better real-life example than the one I described in the original text. On the Hungarian layout the y and z letters are swapped.

This leads to one of the most used shortcuts - undo: ctrl + z - being messed with sometimes. There are programs that handle it by requiring the user to actually stretch their hands and reach all the way to the middle of the top row while pressing ctrl (or turn it into a two handed gesture), but some actually just treat the hotkey as being "press ctrl and the key to the right of the left shift, we don't care what symbol it produces" [being KeyZ, scancode 0x0034], which is a much better approach in my opinion.

If we were to get rid of the further translation of keys (the mapKey function), the combination you asked about could be uniquely identified by AltLeft+Digit8, AltRight+Digit8.

ps.: I understand that this would increase verbosity, but the current "convenience" of treating hotkey strings leniently and trying to guess what the developer meant is part of what leads to ambiguity.

[JohannesKlauss]

Assume for a moment we would use this approach: What are you displaying to the user? What would you communicate to the user which key to press in order to activate the hotkey?

[isti115]

If this gets cross browser compatibility (currently not supported in Firefox), then we're golden: https://wicg.github.io/keyboard-map/#keyboardlayoutmap-interface

Until then the only viable solution seems to be a graphical representation of the keyboard with the given key highlighted. (Or to allow the users to tell us about their keyboard layout explicitly by either selecting it from a list, or pressing all the keys in sequence, but those seems kind of clunky...)

[filipesmedeiros]

@JohannesKlauss what I suggested to the dev at an app I use is for them to use the "regular" shortcuts UI/display (e.g. CMD + A, but have a warning at the top saying that there is no solution to this issue, and give the person the option to customise the shortcuts (to avoid having really unergonomic shortcuts).

So basically just downstream the issue to the person using the app :/

But can't think of another better solution without KeyboardLayout, which I think will take years to come.

[JohannesKlauss]

Downstreaming a technical issue to the user renders this library unusable. Which product owner would display such a message?
As I said I don't see any other useful solution other than having two hooks: One that listens to the produced symbol and one that listens to the code.

[filipesmedeiros]

But what do you display as the command, for the person? There is no way to know what layout the person has, and therefore, no way to know if the command you're displaying is correct, right? I might be seeing something wrong

[isti115]

After deciding to implement this and submit as a pull request I am starting to realize what might actually pose a problem with my suggestion. 😑 There doesn't seem to be an easy way to map keycodes to their respectively produced symbols under the currently active keyboard layout of the user, which makes showing meaningful hints very difficult.
I have put this issue up as a SO question hoping that someone would maybe enlighten me about a solution that I don't know about / haven't yet considered, but until this happens, I guess that the best approach would be to provide the property being mapped as an option as I've seen you have already suggested in one of the issues that I've read about this topic.