[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.

Start at lib/lib.dom.d.ts and inspect the KeyboardEvent interface alongside the well-known KeyboardEvent.key values linked in the issue. Determine the appropriate scope for the type definitions and verify that common key values receive useful type checking and completion without changing runtime behavior.