compose: Add types to useKeyboardShortcut

packages/compose/README.md

@@ -291,10 +291,14 @@ throws a warning when using useLayoutEffect in that environment.
 
 Attach a keyboard shortcut handler.
 
+_Related_
+
+- <https://craig.is/killing/mice#api.bind> for information about the `callback` parameter.
+
 _Parameters_
 
 - _shortcuts_ `string[]|string`: Keyboard Shortcuts.
-- _callback_ `Function`: Shortcut callback.
+- _callback_ `(e: import('mousetrap').ExtendedKeyboardEvent, combo: string) => void`: Shortcut callback.
 - _options_ `WPKeyboardShortcutConfig`: Shortcut options.
 
 <a name="useMediaQuery" href="#useMediaQuery">#</a> **useMediaQuery**

packages/compose/package.json

@@ -29,6 +29,7 @@
  "sideEffects": false,
  "dependencies": {
  "@babel/runtime": "^7.13.10",
+ "@types/mousetrap": "^1.6.8",
  "@wordpress/deprecated": "file:../deprecated",
  "@wordpress/dom": "file:../dom",
  "@wordpress/element": "file:../element",

packages/compose/src/hooks/use-keyboard-shortcut/index.js

@@ -18,13 +18,13 @@ import { useEffect, useRef } from '@wordpress/element';
  * @property {boolean} [bindGlobal] Handle keyboard events anywhere including inside textarea/input fields.
  * @property {string} [eventName] Event name used to trigger the handler, defaults to keydown.
  * @property {boolean} [isDisabled] Disables the keyboard handler if the value is true.
- * @property {Object} [target] React reference to the DOM element used to catch the keyboard event.
+ * @property {import('react').RefObject<HTMLElement>} [target] React reference to the DOM element used to catch the keyboard event.
  */
 
 /**
  * Return true if platform is MacOS.
  *
- * @param {Object} _window window object by default; used for DI testing.
+ * @param {Window} [_window] window object by default; used for DI testing.
  *
  * @return {boolean} True if MacOS; false otherwise.
  */
@@ -37,14 +37,18 @@ function isAppleOS( _window = window ) {
  );
 }
 
+/* eslint-disable jsdoc/valid-types */
 /**
  * Attach a keyboard shortcut handler.
  *
- * @param {string[]|string} shortcuts Keyboard Shortcuts.
- * @param {Function} callback Shortcut callback.
- * @param {WPKeyboardShortcutConfig} options Shortcut options.
+ * @see https://craig.is/killing/mice#api.bind for information about the `callback` parameter.
+ *
+ * @param {string[]|string} shortcuts Keyboard Shortcuts.
+ * @param {(e: import('mousetrap').ExtendedKeyboardEvent, combo: string) => void} callback Shortcut callback.
+ * @param {WPKeyboardShortcutConfig} options Shortcut options.
  */
 function useKeyboardShortcut(
+ /* eslint-enable jsdoc/valid-types */
  shortcuts,
  callback,
  {
@@ -63,7 +67,14 @@ function useKeyboardShortcut(
  if ( isDisabled ) {
  return;
  }
- const mousetrap = new Mousetrap( target ? target.current : document );
+ const mousetrap = new Mousetrap(
+ target && target.current
+ ? target.current
+ : // We were passing `document` here previously, so to successfully cast it to Element we must cast it first to `unknown`.
+ // Not sure if this is a mistake but it was the behavior previous to the addition of types so we're just doing what's
+ // necessary to maintain the existing behavior
+ /** @type {Element} */ (/** @type {unknown} */ ( document ))
+ );
  castArray( shortcuts ).forEach( ( shortcut ) => {
  const keys = shortcut.split( '+' );
  // Determines whether a key is a modifier by the length of the string.
@@ -87,9 +98,15 @@ function useKeyboardShortcut(
  }
 
  const bindFn = bindGlobal ? 'bindGlobal' : 'bind';
+ // @ts-ignore `bindGlobal` is an undocumented property
  mousetrap[ bindFn ](
  shortcut,
- ( ...args ) => currentCallback.current( ...args ),
+ (
+ /* eslint-disable jsdoc/valid-types */
+ /** @type {[e: import('mousetrap').ExtendedKeyboardEvent, combo: string]} */ ...args
+ ) =>
+ /* eslint-enable jsdoc/valid-types */
+ currentCallback.current( ...args ),
  eventName
  );
  } );

packages/compose/tsconfig.json

@@ -18,9 +18,10 @@
  "src/hooks/use-async-list/**/*",
  "src/hooks/use-constrained-tabbing/**/*",
  "src/hooks/use-debounce/**/*",
+ "src/hooks/use-focus-return/**/*",
  "src/hooks/use-instance-id/**/*",
  "src/hooks/use-isomorphic-layout-effect/**/*",
- "src/hooks/use-focus-return/**/*",
+ "src/hooks/use-keyboard-shortcut/**/*",
  "src/hooks/use-previous/**/*",
  "src/hooks/use-media-query/**/*",
  "src/hooks/use-reduced-motion/**/*",