diff --git a/README.md b/README.md index f0ba177..458ad13 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # @bigbinary/neeto-hotkeys -The `neeto-hotkeys` package provides the `useHotKeys` hook, a versatile utility for managing hotkeys in an application. -This hook allows you to define specific hotkey combinations and associate them with corresponding handler functions. -The associated handler is invoked upon pressing the configured hotkey(s), enabling you to execute actions in response to keyboard input. +The `neeto-hotkeys` package provides the `useHotKeys` hook, a versatile utility +for managing hotkeys in an application. This hook allows you to define specific +hotkey combinations and associate them with corresponding handler functions. The +associated handler is invoked upon pressing the configured hotkey(s), enabling +you to execute actions in response to keyboard input. ## Installation @@ -38,8 +40,9 @@ yarn add @bigbinary/neeto-hotkeys Handler will receive the original key `event`. This can be used to stop the default browser action like so `event.preventDefault()`. -- `config`: A config object which has 3 properties `mode`, `unbindOnUnmount` & - `enabled`. +- `config` (optional): A config object which has 3 properties `mode`, + `unbindOnUnmount` & `enabled`. + 1. mode: The available values for mode are `default`, `global` & `scoped`. - default: It is the default mode. Handlers will only be called if the user is outside of a textarea, input, or select element. @@ -55,8 +58,21 @@ yarn add @bigbinary/neeto-hotkeys value to `false`. 3. enabled: By default its value will be `true`. Setting this to `false` will not register the hotkey. - -- `externalDocument`: This is an optional argument. If you want to listen for hotkeys on an external document (e.g., an iframe), pass the reference of that document as the 4th argument for useHotKeys hook. If you do not provide this argument, the hook will listen for hotkeys on the current document by default. + 4. externalDocument: This is an optional property. If you want to listen for + hotkeys on an external document (e.g., an iframe), pass the reference of + that document using the `externalDocument` property in the `config` + object. If you do not provide this property, the hook will listen for + hotkeys on the current document by default. + + - `dependencies`: The `useHotkeys` hook automatically memoizes the callback it + receives to avoid unnecessary re-renders. However, this behavior can cause + issues with stale state. To address this, hook accepts a dependencies array. + The general rule is to put every unstable reference used inside the callback + into the dependency array. + + Note: If the third argument is an object, it is treated as the config and the + fourth argument will be the dependencies array. If no config is provided, the + dependencies array can be passed directly as the third argument. ### Return value: @@ -65,8 +81,8 @@ yarn add @bigbinary/neeto-hotkeys ### Usage: -Following illustrates the usage of `useHotKeys` hook in implementing shortcut for -Sidebar opening. +Following illustrates the usage of `useHotKeys` hook in implementing shortcut +for Sidebar opening. ```jsx import useHotKeys from "@bigbinary/neeto-hotkeys"; diff --git a/index.d.ts b/index.d.ts index 452a856..dcd53a3 100644 --- a/index.d.ts +++ b/index.d.ts @@ -2,10 +2,12 @@ type ConfigType = { mode?: "default" | "global" | "scoped"; unbindOnUnmount?: boolean; enabled?: boolean; + externalDocument?: Document; }; export default function useHotkeys( hotkey: string | string[], handler: (event: React.KeyboardEvent) => void, - config?: ConfigType + configOrDependencies?: ConfigType | unknown[], + dependencies?: unknown[] ): React.MutableRefObject | null; diff --git a/src/index.js b/src/index.js index 15b6385..f573e09 100644 --- a/src/index.js +++ b/src/index.js @@ -1,6 +1,6 @@ import { useEffect, useMemo, useRef } from "react"; -import { mergeLeft } from "ramda"; +import { mergeLeft, type } from "ramda"; import { DEFAULT_CONFIG, MODES } from "src/constants"; import { @@ -9,20 +9,37 @@ import { unBindHotKey, } from "src/utils"; -const useHotKeys = (hotkey, handler, userConfig, externalDocument) => { +const useHotKeys = ( + hotkey, + handler, + configOrDependencies, + dependencies = [] +) => { const ref = useRef(null); const handlerRef = useRef(handler); handlerRef.current = handler; + const isConfigObject = type(configOrDependencies) === "Object"; + const config = isConfigObject ? configOrDependencies : {}; + const deps = + !isConfigObject && Array.isArray(configOrDependencies) + ? configOrDependencies + : dependencies; + const convertedHotkey = useMemo( () => convertHotkeyToUsersPlatform(hotkey), - [hotkey] + [hotkey, ...deps] ); const memoizedConfig = useMemo( - () => mergeLeft(userConfig, DEFAULT_CONFIG), - [userConfig?.enabled, userConfig?.mode, userConfig?.unbindOnUnmount] + () => mergeLeft(config, DEFAULT_CONFIG), + [ + config?.enabled, + config?.mode, + config?.unbindOnUnmount, + config?.externalDocument, + ] ); useEffect(() => { @@ -33,7 +50,7 @@ const useHotKeys = (hotkey, handler, userConfig, externalDocument) => { hotkey: convertedHotkey, handler: handlerRef.current, ref, - externalDocument, + externalDocument: memoizedConfig.externalDocument, }); return () => { @@ -43,7 +60,7 @@ const useHotKeys = (hotkey, handler, userConfig, externalDocument) => { hotkey: convertedHotkey, }); }; - }, [convertedHotkey, externalDocument, memoizedConfig]); + }, [convertedHotkey, memoizedConfig]); return memoizedConfig.mode === MODES.scoped ? ref : null; };