[lib.dom.d.ts] Include well-known KeyboardEvent.key values

Search Terms

• keyCode
• KeyboardEvent
• KeyboardEvent.key
• KeyboardEvent.keyCode

Suggestion

Include KeyboardEvent.key values in the KeyboardEvent interface.

The current implementation is:

interface KeyboardEvent extends UIEvent {
  ...
  readonly key: string;
  ...

See here for a list of some possible values.

Here is my suggestion for how this type can be usefully updated:

type ModifierKeys = "Alt" | "AltGraph" | "CapsLock" | "Control" | "Fn" | "FnLock" | "Hyper" | "Meta" | NumLock" | "ScrollLock" | "Shift" | "Super" | "Symbol" | "SymbolLock";
type WhitespaceKeys = "Enter" | "Tab" | " ";
type NavigationKeys = "ArrowDown" | "ArrowLeft" | "ArrowRight" | "ArrowUp" | "End" | "Home" | "PageDown" | "PageUp";
type FunctionKeys = "F1" | "F2" | "F3" | "F4" | "F5" | "F6" | "F7" | "F8" | "F9" | "F10" | "F11" | "F12" | "F13" | "F14" | "F15" | "F16" | "F17" | "F18" | "F19" | "F20" | "Soft1" | "Soft2" | "Soft3" | "Soft4";
type NumericKeypadKeys = "Decimal" | "Key11" | "Key12" | "Multiply" | "Add" | "Clear" | "Divide" | "Subtract" | "Separator" | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";

interface KeyboardEvent extends UIEvent {
  ...
  readonly key: string | ModifierKeys | WhitespaceKeys | NavigationKeys | FunctionKeys | NumericKeypadKeys;
  ...
}

In the above I left out EditingKeys, UIKeys, DeviceKeys, IMEKeys, PhoneKeys, MultimediaKeys, AudioControlKeys, TVControlKeys, MediaControllerKeys, SpeechRecognitionKeys, DocumentKeys, ApplicationSelectorKeys, and BrowserControlKeys, but we could either include them all at the start or just as necessary.

Use Cases

When a user is accessing the KeyboardEvent.key API, a sane set of the known defaults should be available for type checking.

Examples

This will help prevent scenarios like:

if (event.key === "ArowDown") { // <- "ArrowDown" is misspelled here

Since users will get completion on common values when typing.

note: I had previously suggested implementing this in the React types, but @ferdaber suggested (and I agree) that the dom types themselves are the better place.

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Inizia da lib/lib.dom.d.ts ed esamina l’interfaccia KeyboardEvent insieme ai valori noti di KeyboardEvent.key collegati nell’issue. Determina l’ambito appropriato per le definizioni dei tipi e verifica che i valori dei tasti comuni ricevano un controllo dei tipi e un completamento utili senza modificare il comportamento a runtime.