[v5] feat: use named keys instead of key codes (#6106)

packages/core/karma.conf.js

@@ -27,10 +27,18 @@ module.exports = async function (config) {
                 "src/context/portal/portalProvider.tsx",
             ],
             coverageOverrides: {
+                "src/components/editable-text/editableText.tsx": {
+                    lines: 75,
+                    statements: 75,
+                },
                 "src/components/popover/customModifiers.ts": {
                     lines: 66,
                     statements: 66,
                 },
+                "src/components/tag-input/tagInput.tsx": {
+                    lines: 75,
+                    statements: 75,
+                },
             },
         }),
     );

packages/core/src/common/index.ts

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+export { Colors } from "@blueprintjs/colors";
+
 export { AbstractComponent } from "./abstractComponent";
 export { AbstractPureComponent } from "./abstractPureComponent";
 export { Alignment } from "./alignment";
@@ -22,6 +24,8 @@ export { Boundary } from "./boundary";
 export { Constructor } from "./constructor";
 export { Elevation } from "./elevation";
 export { Intent } from "./intent";
+// eslint-disable-next-line deprecation/deprecation
+export { KeyCodes as Keys } from "./keyCodes";
 export { Position } from "./position";
 export {
     ActionProps,
@@ -38,11 +42,7 @@ export {
 } from "./props";
 export { getRef, isRefCallback, isRefObject, mergeRefs, refHandler, setRef } from "./refs";
 
-import { Colors } from "@blueprintjs/colors";
-
 import * as Classes from "./classes";
-import * as Keys from "./keys";
 import * as Utils from "./utils";
-
-export { Classes, Keys, Utils, Colors };
+export { Classes, Utils };
 // NOTE: Errors is not exported in public API

packages/core/src/common/keys.ts → packages/core/src/common/keyCodes.ts

@@ -14,19 +14,19 @@
  * limitations under the License.
  */
 
-export const BACKSPACE = 8;
-export const TAB = 9;
-export const ENTER = 13;
-export const SHIFT = 16;
-export const ESCAPE = 27;
-export const SPACE = 32;
-export const ARROW_LEFT = 37;
-export const ARROW_UP = 38;
-export const ARROW_RIGHT = 39;
-export const ARROW_DOWN = 40;
-export const DELETE = 46;
+// tslint:disable object-literal-sort-keys
 
-/** Returns whether the key code is `enter` or `space`, the two keys that can click a button. */
-export function isKeyboardClick(keyCode: number) {
-    return keyCode === ENTER || keyCode === SPACE;
-}
+/** @deprecated use named keys instead of key codes */
+export const KeyCodes = {
+    BACKSPACE: 8,
+    TAB: 9,
+    ENTER: 13,
+    SHIFT: 16,
+    ESCAPE: 27,
+    SPACE: 32,
+    ARROW_LEFT: 37,
+    ARROW_UP: 38,
+    ARROW_RIGHT: 39,
+    ARROW_DOWN: 40,
+    DELETE: 46,
+};

packages/core/src/common/utils/index.ts

@@ -27,6 +27,7 @@ export {
 export { isFunction } from "./functionUtils";
 export * from "./jsUtils";
 export * from "./reactUtils";
+export { isArrowKey, isKeyboardClick } from "./keyboardUtils";
 export { isDarkTheme } from "./isDarkTheme";
 
 // ref utils used to live in this folder, but got refactored and moved elsewhere.

packages/core/src/common/utils/keyboardUtils.ts

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2023 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Returns whether the keyboard event was triggered by Enter or Space, the two keys that are expected to trigger
+ * interactive elements like buttons.
+ */
+export function isKeyboardClick(event: React.KeyboardEvent<HTMLElement>) {
+    return event.key === "Enter" || event.key === " ";
+}
+
+export function isArrowKey(event: React.KeyboardEvent<HTMLElement>) {
+    return ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"].indexOf(event.key) >= 0;
+}

packages/core/src/components/button/buttons.tsx

@@ -19,7 +19,7 @@ import React, { forwardRef, useCallback, useRef, useState } from "react";
 
 import { IconSize } from "@blueprintjs/icons";
 
-import { Classes, Keys, Utils } from "../../common";
+import { Classes, Utils } from "../../common";
 import { DISPLAYNAME_PREFIX, removeNonHTMLProps } from "../../common/props";
 import { mergeRefs } from "../../common/refs";
 import { Icon } from "../icon/icon";
@@ -78,7 +78,7 @@ function useSharedButtonAttributes<E extends HTMLAnchorElement | HTMLButtonEleme
     const disabled = props.disabled || loading;
 
     // the current key being pressed
-    const [currentKeyDown, setCurrentKeyDown] = useState<number | undefined>();
+    const [currentKeyPressed, setCurrentKeyPressed] = useState<string | undefined>();
     // whether the button is in "active" state
     const [isActive, setIsActive] = useState(false);
     // our local ref for the button element, merged with the consumer's own ref (if supplied) in this hook's return value
@@ -95,28 +95,24 @@ function useSharedButtonAttributes<E extends HTMLAnchorElement | HTMLButtonEleme
     );
     const handleKeyDown = useCallback(
         (e: React.KeyboardEvent<any>) => {
-            // HACKHACK: https://github.com/palantir/blueprint/issues/4165
-            /* eslint-disable deprecation/deprecation */
-            if (Keys.isKeyboardClick(e.which)) {
+            if (Utils.isKeyboardClick(e)) {
                 e.preventDefault();
-                if (e.which !== currentKeyDown) {
+                if (e.key !== currentKeyPressed) {
                     setIsActive(true);
                 }
             }
-            setCurrentKeyDown(e.which);
+            setCurrentKeyPressed(e.key);
             props.onKeyDown?.(e);
         },
-        [currentKeyDown, props.onKeyDown],
+        [currentKeyPressed, props.onKeyDown],
     );
     const handleKeyUp = useCallback(
         (e: React.KeyboardEvent<any>) => {
-            // HACKHACK: https://github.com/palantir/blueprint/issues/4165
-            /* eslint-disable deprecation/deprecation */
-            if (Keys.isKeyboardClick(e.which)) {
+            if (Utils.isKeyboardClick(e)) {
                 setIsActive(false);
                 buttonRef.current?.click();
             }
-            setCurrentKeyDown(undefined);
+            setCurrentKeyPressed(undefined);
             props.onKeyUp?.(e);
         },
         [props.onKeyUp],

packages/core/src/components/editable-text/editableText.tsx

@@ -17,7 +17,7 @@
 import classNames from "classnames";
 import React from "react";
 
-import { AbstractPureComponent, Classes, Keys } from "../../common";
+import { AbstractPureComponent, Classes } from "../../common";
 import { DISPLAYNAME_PREFIX, IntentProps, Props } from "../../common/props";
 import { clamp } from "../../common/utils";
 
@@ -341,16 +341,14 @@ export class EditableText extends AbstractPureComponent<EditableTextProps, Edita
     };
 
     private handleKeyEvent = (event: React.KeyboardEvent<HTMLElement>) => {
-        // HACKHACK: https://github.com/palantir/blueprint/issues/4165
-        /* eslint-disable-next-line deprecation/deprecation */
-        const { altKey, ctrlKey, metaKey, shiftKey, which } = event;
-        if (which === Keys.ESCAPE) {
+        const { altKey, ctrlKey, metaKey, shiftKey } = event;
+        if (event.key === "Escape") {
             this.cancelEditing();
             return;
         }
 
         const hasModifierKey = altKey || ctrlKey || metaKey || shiftKey;
-        if (which === Keys.ENTER) {
+        if (event.key === "Enter") {
             // prevent IE11 from full screening with alt + enter
             // shift + enter adds a newline by default
             if (altKey || shiftKey) {

packages/core/src/components/forms/numericInput.tsx

@@ -25,7 +25,6 @@ import {
     DISPLAYNAME_PREFIX,
     HTMLInputProps,
     Intent,
-    Keys,
     Position,
     refHandler,
     removeNonHTMLProps,
@@ -199,7 +198,7 @@ const NON_HTML_PROPS: Array<keyof NumericInputProps> = [
     "stepSize",
 ];
 
-type ButtonEventHandlers = Required<Pick<React.HTMLAttributes<Element>, "onKeyDown" | "onMouseDown">>;
+type ButtonEventHandlers = Required<Pick<React.HTMLAttributes<HTMLElement>, "onKeyDown" | "onMouseDown">>;
 
 /**
  * Numeric input component.
@@ -477,8 +476,7 @@ export class NumericInput extends AbstractPureComponent<HTMLInputProps & Numeric
         return {
             // keydown is fired repeatedly when held so it's implicitly continuous
             onKeyDown: evt => {
-                // eslint-disable-next-line deprecation/deprecation
-                if (!this.props.disabled && Keys.isKeyboardClick(evt.keyCode)) {
+                if (!this.props.disabled && Utils.isKeyboardClick(evt)) {
                     this.handleButtonClick(evt, direction);
                 }
             },
@@ -560,14 +558,11 @@ export class NumericInput extends AbstractPureComponent<HTMLInputProps & Numeric
             return;
         }
 
-        // eslint-disable-next-line deprecation/deprecation
-        const { keyCode } = e;
-
         let direction: IncrementDirection | undefined;
 
-        if (keyCode === Keys.ARROW_UP) {
+        if (e.key === "ArrowUp") {
             direction = IncrementDirection.UP;
-        } else if (keyCode === Keys.ARROW_DOWN) {
+        } else if (e.key === "ArrowDown") {
             direction = IncrementDirection.DOWN;
         }