react-hotkeys-hook 5.2.1 → 5.2.2

package/README.md

@@ -1,223 +1,54 @@
-<hr>
-<div align="center">
-  <h1 align="center">
-    useHotkeys(keys, callback)
-  </h1>
-</div>
-
-<p align="center">
-  <a href="https://bundlephobia.com/result?p=react-hotkeys-hook">
-    <img alt="Bundlephobia" src="https://img.shields.io/bundlephobia/minzip/react-hotkeys-hook?style=for-the-badge&labelColor=24292e">
-  </a>
-  <a aria-label="Types" href="https://www.npmjs.com/package/react-hotkeys-hook">
-    <img alt="Types" src="https://img.shields.io/npm/types/react-hotkeys-hook?style=for-the-badge&labelColor=24292e">
-  </a>
-  <a aria-label="NPM version" href="https://www.npmjs.com/package/react-hotkeys-hook">
-    <img alt="NPM Version" src="https://img.shields.io/npm/v/react-hotkeys-hook?style=for-the-badge&labelColor=24292e">
-  </a>
-  <a aria-label="License" href="https://jaredlunde.mit-license.org/">
-    <img alt="MIT License" src="https://img.shields.io/npm/l/react-hotkeys-hook?style=for-the-badge&labelColor=24292e">
-  </a>
-</p>
-
-<p align="center">
-  <a aria-label="Sponsored by Spaceteams" href="https://spaceteams.de">
-    <img alt="Sponsored by Spaceteams" src="https://raw.githubusercontent.com/spaceteams/badges/main/sponsored-by-spaceteams.svg">
-  </a>
-</p>
-
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default tseslint.config({
+  extends: [
+    // Remove ...tseslint.configs.recommended and replace with this
+    ...tseslint.configs.recommendedTypeChecked,
+    // Alternatively, use this for stricter rules
+    ...tseslint.configs.strictTypeChecked,
+    // Optionally, add this for stylistic rules
+    ...tseslint.configs.stylisticTypeChecked,
+  ],
+  languageOptions: {
+    // other options...
+    parserOptions: {
+      project: ['./tsconfig.node.json', './tsconfig.app.json'],
+      tsconfigRootDir: import.meta.dirname,
+    },
+  },
+})
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default tseslint.config({
+  plugins: {
+    // Add the react-x and react-dom plugins
+    'react-x': reactX,
+    'react-dom': reactDom,
+  },
+  rules: {
+    // other rules...
+    // Enable its recommended typescript rules
+    ...reactX.configs['recommended-typescript'].rules,
+    ...reactDom.configs.recommended.rules,
+  },
+})
 ```
-npm i react-hotkeys-hook
-```
-
-<p align="center">
-A React hook for using keyboard shortcuts in components in a declarative way.
-</p>
-
-<hr>
-
-## Quick Start
-
-The easiest way to use the hook.
-
-```jsx harmony
-import { useHotkeys } from 'react-hotkeys-hook'
-
-export const ExampleComponent = () => {
-  const [count, setCount] = useState(0)
-  useHotkeys('ctrl+k', () => setCount(count + 1), [count])
-
-  return (
-    <p>
-      Pressed {count} times.
-    </p>
-  )
-}
-```
-
-### Scopes
-
-Scopes allow you to group hotkeys together. You can use scopes to prevent hotkeys from colliding with each other.
-
-```jsx harmony
-const App = () => {
-  return (
-    <HotkeysProvider initiallyActiveScopes={['settings']}>
-      <ExampleComponent />
-    </HotkeysProvider>
-  )
-}
-
-export const ExampleComponent = () => {
-  const [count, setCount] = useState(0)
-  useHotkeys('ctrl+k', () => setCount(prevCount => prevCount + 1), { scopes: ['settings'] })
-
-  return (
-    <p>
-      Pressed {count} times.
-    </p>
-  )
-}
-```
-
-#### Changing a scope's active state
-
-You can change the active state of a scope using the `disableScope`, `enableScope` and `toggleScope` functions
-returned by the `useHotkeysContext()` hook. Note that you have to have your app wrapped in a `<HotkeysProvider>` component.
-
-```jsx harmony
-const App = () => {
-  return (
-    <HotkeysProvider initiallyActiveScopes={['settings']}>
-      <ExampleComponent />
-    </HotkeysProvider>
-  )
-}
-
-export const ExampleComponent = () => {
-  const { toggleScope } = useHotkeysContext()
-
-  return (
-    <button onClick={() => toggleScope('settings')}>
-      Change scope active state
-    </button>
-  )
-}
-```
-
-### Focus trap
-
-This will only trigger the hotkey if the component is focused.
-
-```tsx harmony
-export const ExampleComponent = () => {
-  const [count, setCount] = useState(0)
-  const ref = useHotkeys<HTMLParagraphElement>('ctrl+k', () => setCount(prevCount => prevCount + 1))
-
-  return (
-    <p tabIndex={-1} ref={ref}>
-      Pressed {count} times.
-    </p>
-  )
-}
-```
-
-## Documentation & Live Examples
-
-* [Quick Start](https://react-hotkeys-hook.vercel.app/docs/intro)
-* [Documentation](https://react-hotkeys-hook.vercel.app/docs/documentation/installation)
-* [API](https://react-hotkeys-hook.vercel.app/docs/api/use-hotkeys)
-
-## API
-
-### useHotkeys(keys, callback)
-
-```typescript
-useHotkeys(keys: string | string[], callback: (event: KeyboardEvent, handler: HotkeysEvent) => void, options: Options = {}, deps: DependencyList = [])
-```
-
-| Parameter     | Type                                                    | Required? | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-|---------------|---------------------------------------------------------|-----------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `keys`        | `string` or `string[]`                                  | required  | -             | set the hotkeys you want the hook to listen to. You can use single or multiple keys, modifier combinations, etc. This will either be a string or an array of strings. To separate multiple keys, use a comma. This split key value can be overridden with the `splitKey` option.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `callback`    | `(event: KeyboardEvent, handler: HotkeysEvent) => void` | required  | -             | This is the callback function that will be called when the hotkey is pressed. The callback will receive the browsers native `KeyboardEvent` and the libraries `HotkeysEvent`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `options`     | `Options`                                               | optional  | `{}`          | Object to modify the behavior of the hook. Default options are given below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `dependencies` | `DependencyList`                                         | optional  | `[]`           | The given callback will always be memoised inside the hook. So if you reference any outside variables, you need to set them here for the callback to get updated (Much like `useCallback` works in React). |
-
-### Options
-
-All options are optional and have a default value which you can override to change the behavior of the hook.
-
-| Option                   | Type                                                                                 | Default value | Description                                                                                                                                                                                                                                                                                                                                                                             |
-|--------------------------|--------------------------------------------------------------------------------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `enabled`                | `boolean` or `(keyboardEvent: KeyboardEvent, hotkeysEvent: HotkeysEvent) => boolean` | `true`        | This option determines whether the hotkey is active or not. It can take a boolean (for example a flag from a state outside) or a function which gets executed once the hotkey is pressed. If the function returns `false` the hotkey won't get executed and all browser events are prevented.                                                                                           |
-| `enableOnFormTags`       | `boolean` or `FormTags[]`                                                            | `false`       | By default hotkeys are not registered if a focus focuses on an input field. This will prevent accidental triggering of hotkeys when the user is typing. If you want to enable hotkeys, use this option. Setting it to true will enable on all form tags, otherwise you can give an array of form tags to enable the hotkey on (possible options are: `['input', 'textarea', 'select']`) |
-| `enableOnContentEditable` | `boolean`                                                                            | `false`       | Set this option to enable hotkeys on tags that have set the `contentEditable` prop to `true`                                                                                                                                                                                                                                                                                            |
-| `combinationKey`         | `string`                                                                             | `+`           | Character to indicate keystrokes like `shift+c`. You might want to change this if you want to listen to the `+` character like `ctrl-+`.                                                                                                                                                                                                                                                |
-| `splitKey`               | `string`                                                                             | `,`           | Character to separate different keystrokes like `ctrl+a, ctrl+b`.                                                                                                                                                                                                                                                                                                                       |
-| `scopes`                 | `string` or `string[]`                                                               | `*`           | With scopes you can group hotkeys together. The default scope is the wildcard `*` which matches all hotkeys. Use the `<HotkeysProvider>` component to change active scopes.                                                                                                                                                                                                             |
-| `keyup`                  | `boolean`                                                                            | `false`       | Determines whether to listen to the browsers `keyup` event for triggering the callback.                                                                                                                                                                                                                                                                                                 |
-| `keydown`                | `boolean`                                                                            | `true`        | Determines whether to listen to the browsers `keydown` event for triggering the callback. If you set both `keyup`and `keydown` to true, the callback will trigger on both events.                                                                                                                                                                                                       |
-| `preventDefault`         | `boolean` or `(keyboardEvent: KeyboardEvent, hotkeysEvent: HotkeysEvent) => boolean` | `false`       | Set this to a `true` if you want the hook to prevent the browsers default behavior on certain keystrokes like `meta+s` to save a page. NOTE: Certain keystrokes are not preventable, like `meta+w` to close a tab in chrome.                                                                                                                                                            |
-| `description`             | `string`                                                                              | `undefined`    | Use this option to describe what the hotkey does. this is helpful if you want to display a list of active hotkeys to the user.                                                                                                                                                                                                                                                          |
-
-
-#### Overloads
-
-The hooks call signature is very flexible. For example if you don't need to set any special options you can use the dependency
-array as your third parameter:
-
-`useHotkeys('ctrl+k', () => console.log(counter + 1), [counter])`
-
-### `isHotkeyPressed(keys: string | string[], splitKey?: string = ',')`
-
-This function allows us to check if the user is currently pressing down a key.
-
-```ts
-import { isHotkeyPressed } from 'react-hotkeys-hook'
-
-isHotkeyPressed('esc') // Returns true if Escape key is pressed down.
-```
-
-You can also check for multiple keys at the same time:
-
-```ts
-isHotkeyPressed(['esc', 'ctrl+s']) // Returns true if Escape or Ctrl+S are pressed down.
-```
-
-## Support
-
-* Ask your question in the [Github Discussions]([Support](https://github.com/JohannesKlauss/react-hotkeys-hook/discussions))
-* Ask your question on [StackOverflow](https://stackoverflow.com/search?page=1&tab=Relevance&q=react-hotkeys-hook)
-
-## Found an issue or have a feature request?
-
-Open up an [issue](https://github.com/JohannesKlauss/react-hotkeys-hook/issues/new)
-or [pull request](https://github.com/JohannesKlauss/react-hotkeys-hook/compare) and participate.
-
-## Local Development
-
-Checkout this repo, run `yarn` or `npm i` and then run the `test` script to test the behavior of the hook.
-
-## Contributing
-Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
-
-1. Fork the Project
-2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the Branch (`git push origin feature/AmazingFeature`)
-5. Open a Pull Request
-
-## License
-Distributed under the MIT License. See `LICENSE` for more information.
-
-## Contact
-
-Johannes Klauss - [@JohannesKlauss](https://github.com/JohannesKlauss) - klauss.johannes@gmail.com
-
-Project Link: [https://github.com/JohannesKlauss/react-hotkeys-hook](https://github.com/JohannesKlauss/react-hotkeys-hook)
-
-## Contributors
-
-<a href="https://github.com/johannesklauss/react-hotkeys-hook/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=johannesklauss/react-hotkeys-hook" />
-</a>

package/dist/index.js

@@ -0,0 +1,300 @@
+import { createContext as T, useContext as M, useState as A, useCallback as k, useRef as S, useLayoutEffect as z, useEffect as J } from "react";
+import { jsx as b } from "react/jsx-runtime";
+const j = ["shift", "alt", "meta", "mod", "ctrl", "control"], Q = {
+  esc: "escape",
+  return: "enter",
+  left: "arrowleft",
+  right: "arrowright",
+  up: "arrowup",
+  down: "arrowdown",
+  ShiftLeft: "shift",
+  ShiftRight: "shift",
+  AltLeft: "alt",
+  AltRight: "alt",
+  MetaLeft: "meta",
+  MetaRight: "meta",
+  OSLeft: "meta",
+  OSRight: "meta",
+  ControlLeft: "ctrl",
+  ControlRight: "ctrl"
+};
+function K(e) {
+  return (Q[e.trim()] || e.trim()).toLowerCase().replace(/key|digit|numpad/, "");
+}
+function D(e) {
+  return j.includes(e);
+}
+function H(e, n = ",") {
+  return e.toLowerCase().split(n);
+}
+function P(e, n = "+", r = ">", i = !1, u, f) {
+  let o = [], y = !1;
+  e = e.trim(), e.includes(r) ? (y = !0, o = e.toLocaleLowerCase().split(r).map((d) => K(d))) : o = e.toLocaleLowerCase().split(n).map((d) => K(d));
+  const c = {
+    alt: o.includes("alt"),
+    ctrl: o.includes("ctrl") || o.includes("control"),
+    shift: o.includes("shift"),
+    meta: o.includes("meta"),
+    mod: o.includes("mod"),
+    useKey: i
+  }, m = o.filter((d) => !j.includes(d));
+  return {
+    ...c,
+    keys: m,
+    description: u,
+    isSequence: y,
+    hotkey: e,
+    metadata: f
+  };
+}
+typeof document < "u" && (document.addEventListener("keydown", (e) => {
+  e.code !== void 0 && _([K(e.code)]);
+}), document.addEventListener("keyup", (e) => {
+  e.code !== void 0 && I([K(e.code)]);
+})), typeof window < "u" && (window.addEventListener("blur", () => {
+  L.clear();
+}), window.addEventListener("contextmenu", () => {
+  setTimeout(() => {
+    L.clear();
+  }, 0);
+}));
+const L = /* @__PURE__ */ new Set();
+function R(e) {
+  return Array.isArray(e);
+}
+function U(e, n = ",") {
+  return (R(e) ? e : e.split(n)).every((i) => L.has(i.trim().toLowerCase()));
+}
+function _(e) {
+  const n = Array.isArray(e) ? e : [e];
+  L.has("meta") && L.forEach((r) => {
+    D(r) || L.delete(r.toLowerCase());
+  }), n.forEach((r) => {
+    L.add(r.toLowerCase());
+  });
+}
+function I(e) {
+  const n = Array.isArray(e) ? e : [e];
+  e === "meta" ? L.clear() : n.forEach((r) => {
+    L.delete(r.toLowerCase());
+  });
+}
+function V(e, n, r) {
+  (typeof r == "function" && r(e, n) || r === !0) && e.preventDefault();
+}
+function X(e, n, r) {
+  return typeof r == "function" ? r(e, n) : r === !0 || r === void 0;
+}
+const Y = [
+  "input",
+  "textarea",
+  "select",
+  "searchbox",
+  "slider",
+  "spinbutton",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "radio",
+  "textbox"
+];
+function Z(e) {
+  return F(e, Y);
+}
+function F(e, n = !1) {
+  const { target: r, composed: i } = e;
+  let u, f;
+  return ee(r) && i ? (u = e.composedPath()[0] && e.composedPath()[0].tagName, f = e.composedPath()[0] && e.composedPath()[0].role) : (u = r && r.tagName, f = r && r.role), R(n) ? !!(u && n && n.some((o) => o.toLowerCase() === u.toLowerCase() || o === f)) : !!(u && n && n);
+}
+function ee(e) {
+  return !!e.tagName && !e.tagName.startsWith("-") && e.tagName.includes("-");
+}
+function te(e, n) {
+  return e.length === 0 && n ? !1 : n ? e.some((r) => n.includes(r)) || e.includes("*") : !0;
+}
+const re = (e, n, r = !1) => {
+  const { alt: i, meta: u, mod: f, shift: o, ctrl: y, keys: c, useKey: m } = n, { code: d, key: t, ctrlKey: a, metaKey: l, shiftKey: h, altKey: w } = e, p = K(d);
+  if (m) {
+    if (c?.length === 1 && c.includes(t.toLowerCase())) {
+      if (!r) {
+        if (i !== w || o !== h) return !1;
+        if (f) {
+          if (!l && !a) return !1;
+        } else if (u !== l || y !== a) return !1;
+      }
+      return !0;
+    }
+    return !1;
+  }
+  if (!c?.includes(p) && !["ctrl", "control", "unknown", "meta", "alt", "shift", "os"].includes(p))
+    return !1;
+  if (!r) {
+    if (i !== w && p !== "alt" || o !== h && p !== "shift")
+      return !1;
+    if (f) {
+      if (!l && !a)
+        return !1;
+    } else if (u !== l && p !== "meta" && p !== "os" || y !== a && p !== "ctrl" && p !== "control")
+      return !1;
+  }
+  return c && c.length === 1 && c.includes(p) ? !0 : c && c.length > 0 ? c.includes(p) ? U(c) : !1 : !c || c.length === 0;
+}, $ = T(void 0), ne = () => M($);
+function oe({ addHotkey: e, removeHotkey: n, children: r }) {
+  return /* @__PURE__ */ b($.Provider, { value: { addHotkey: e, removeHotkey: n }, children: r });
+}
+function x(e, n) {
+  return e && n && typeof e == "object" && typeof n == "object" ? Object.keys(e).length === Object.keys(n).length && // @ts-expect-error TS7053
+  Object.keys(e).reduce((r, i) => r && x(e[i], n[i]), !0) : e === n;
+}
+const W = T({
+  hotkeys: [],
+  activeScopes: [],
+  // This array has to be empty instead of containing '*' as default, to check if the provider is set or not
+  toggleScope: () => {
+  },
+  enableScope: () => {
+  },
+  disableScope: () => {
+  }
+}), se = () => M(W), fe = ({ initiallyActiveScopes: e = ["*"], children: n }) => {
+  const [r, i] = A(e), [u, f] = A([]), o = k((t) => {
+    i((a) => a.includes("*") ? [t] : Array.from(/* @__PURE__ */ new Set([...a, t])));
+  }, []), y = k((t) => {
+    i((a) => a.filter((l) => l !== t));
+  }, []), c = k((t) => {
+    i((a) => a.includes(t) ? a.filter((l) => l !== t) : a.includes("*") ? [t] : Array.from(/* @__PURE__ */ new Set([...a, t])));
+  }, []), m = k((t) => {
+    f((a) => [...a, t]);
+  }, []), d = k((t) => {
+    f((a) => a.filter((l) => !x(l, t)));
+  }, []);
+  return /* @__PURE__ */ b(
+    W.Provider,
+    {
+      value: { activeScopes: r, hotkeys: u, enableScope: o, disableScope: y, toggleScope: c },
+      children: /* @__PURE__ */ b(oe, { addHotkey: m, removeHotkey: d, children: n })
+    }
+  );
+};
+function ie(e) {
+  const n = S(void 0);
+  return x(n.current, e) || (n.current = e), n.current;
+}
+const N = (e) => {
+  e.stopPropagation(), e.preventDefault(), e.stopImmediatePropagation();
+}, ue = typeof window < "u" ? z : J;
+function de(e, n, r, i) {
+  const u = S(null), f = S(!1), o = Array.isArray(r) ? Array.isArray(i) ? void 0 : i : r, y = R(e) ? e.join(o?.delimiter) : e, c = Array.isArray(r) ? r : Array.isArray(i) ? i : void 0, m = k(n, c ?? []), d = S(m);
+  c ? d.current = m : d.current = n;
+  const t = ie(o), { activeScopes: a } = se(), l = ne();
+  return ue(() => {
+    if (t?.enabled === !1 || !te(a, t?.scopes))
+      return;
+    let h = [], w;
+    const p = (s, B = !1) => {
+      if (!(Z(s) && !F(s, t?.enableOnFormTags))) {
+        if (u.current !== null) {
+          const v = u.current.getRootNode();
+          if ((v instanceof Document || v instanceof ShadowRoot) && v.activeElement !== u.current && !u.current.contains(v.activeElement)) {
+            N(s);
+            return;
+          }
+        }
+        s.target?.isContentEditable && !t?.enableOnContentEditable || H(y, t?.delimiter).forEach((v) => {
+          if (v.includes(t?.splitKey ?? "+") && v.includes(t?.sequenceSplitKey ?? ">")) {
+            console.warn(
+              `Hotkey ${v} contains both ${t?.splitKey ?? "+"} and ${t?.sequenceSplitKey ?? ">"} which is not supported.`
+            );
+            return;
+          }
+          const g = P(
+            v,
+            t?.splitKey,
+            t?.sequenceSplitKey,
+            t?.useKey,
+            t?.description,
+            t?.metadata
+          );
+          if (g.isSequence) {
+            w = setTimeout(() => {
+              h = [];
+            }, t?.sequenceTimeoutMs ?? 1e3);
+            const C = g.useKey ? s.key : K(s.code);
+            if (D(C.toLowerCase()))
+              return;
+            h.push(C);
+            const G = g.keys?.[h.length - 1];
+            if (C !== G) {
+              h = [], w && clearTimeout(w);
+              return;
+            }
+            h.length === g.keys?.length && (d.current(s, g), w && clearTimeout(w), h = []);
+          } else if (re(s, g, t?.ignoreModifiers) || g.keys?.includes("*")) {
+            if (t?.ignoreEventWhen?.(s) || B && f.current)
+              return;
+            if (V(s, g, t?.preventDefault), !X(s, g, t?.enabled)) {
+              N(s);
+              return;
+            }
+            d.current(s, g), B || (f.current = !0);
+          }
+        });
+      }
+    }, O = (s) => {
+      s.code !== void 0 && (_(K(s.code)), (t?.keydown === void 0 && t?.keyup !== !0 || t?.keydown) && p(s));
+    }, q = (s) => {
+      s.code !== void 0 && (I(K(s.code)), f.current = !1, t?.keyup && p(s, !0));
+    }, E = u.current || o?.document || document;
+    return E.addEventListener("keyup", q, o?.eventListenerOptions), E.addEventListener("keydown", O, o?.eventListenerOptions), l && H(y, t?.delimiter).forEach((s) => {
+      l.addHotkey(
+        P(
+          s,
+          t?.splitKey,
+          t?.sequenceSplitKey,
+          t?.useKey,
+          t?.description,
+          t?.metadata
+        )
+      );
+    }), () => {
+      E.removeEventListener("keyup", q, o?.eventListenerOptions), E.removeEventListener("keydown", O, o?.eventListenerOptions), l && H(y, t?.delimiter).forEach((s) => {
+        l.removeHotkey(
+          P(
+            s,
+            t?.splitKey,
+            t?.sequenceSplitKey,
+            t?.useKey,
+            t?.description,
+            t?.metadata
+          )
+        );
+      }), h = [], w && clearTimeout(w);
+    };
+  }, [y, t, a]), u;
+}
+function le(e = !1) {
+  const [n, r] = A(/* @__PURE__ */ new Set()), [i, u] = A(!1), f = k(
+    (m) => {
+      m.code !== void 0 && (m.preventDefault(), m.stopPropagation(), r((d) => {
+        const t = new Set(d);
+        return t.add(K(e ? m.key : m.code)), t;
+      }));
+    },
+    [e]
+  ), o = k(() => {
+    typeof document < "u" && (document.removeEventListener("keydown", f), u(!1));
+  }, [f]), y = k(() => {
+    r(/* @__PURE__ */ new Set()), typeof document < "u" && (o(), document.addEventListener("keydown", f), u(!0));
+  }, [f, o]), c = k(() => {
+    r(/* @__PURE__ */ new Set());
+  }, []);
+  return [n, { start: y, stop: o, resetKeys: c, isRecording: i }];
+}
+export {
+  fe as HotkeysProvider,
+  U as isHotkeyPressed,
+  de as useHotkeys,
+  se as useHotkeysContext,
+  le as useRecordHotkeys
+};

package/{packages/react-hotkeys-hook/dist → dist}/parseHotkeys.d.ts

@@ -2,4 +2,4 @@ import { Hotkey } from './types';
 export declare function mapCode(key: string): string;
 export declare function isHotkeyModifier(key: string): boolean;
 export declare function parseKeysHookInput(keys: string, delimiter?: string): string[];
-export declare function parseHotkey(hotkey: string, splitKey?: string, sequenceSplitKey?: string, useKey?: boolean, description?: string): Hotkey;
+export declare function parseHotkey(hotkey: string, splitKey?: string, sequenceSplitKey?: string, useKey?: boolean, description?: string, metadata?: Record<string, unknown>): Hotkey;

package/{packages/react-hotkeys-hook/dist → dist}/types.d.ts

@@ -22,6 +22,7 @@ export type Hotkey = KeyboardModifiers & {
     description?: string;
     isSequence?: boolean;
     hotkey: string;
+    metadata?: Record<string, unknown>;
 };
 export type HotkeysEvent = Hotkey;
 export type HotkeyCallback = (keyboardEvent: KeyboardEvent, hotkeysEvent: HotkeysEvent) => void;
@@ -44,5 +45,6 @@ export type Options = {
     useKey?: boolean;
     sequenceTimeoutMs?: number;
     sequenceSplitKey?: string;
+    metadata?: Record<string, unknown>;
 };
 export type OptionsOrDependencyArray = Options | DependencyList;

package/package.json

@@ -1,19 +1,23 @@
 {
   "name": "react-hotkeys-hook",
-  "description": "React hook for handling keyboard shortcuts",
-  "version": "5.2.1",
-  "sideEffects": false,
+  "version": "5.2.2",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "test": "vitest",
+    "prepublishOnly": "vitest run && npm run build"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/JohannesKlauss/react-keymap-hook.git"
   },
-  "homepage": "https://johannesklauss.github.io/react-hotkeys-hook/",
+  "homepage": "https://react-hotkeys-hook.vercel.app/",
   "author": "Johannes Klauss",
-  "type": "module",
-  "main": "packages/react-hotkeys-hook/dist/index.js",
-  "types": "packages/react-hotkeys-hook/dist/index.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
-    "packages/react-hotkeys-hook/dist"
+    "dist"
   ],
   "keywords": [
     "react",
@@ -28,22 +32,24 @@
     "hotkeys"
   ],
   "license": "MIT",
-  "scripts": {
-    "build": "npm run -w packages/react-hotkeys-hook build",
-    "build:documentation": "npm run -w packages/documentation build",
-    "test": "npm run -w packages/react-hotkeys-hook test",
-    "prepublishOnly": "npm run test && npm run lint && npm run build",
-    "format": "npx @biomejs/biome format --write packages",
-    "lint": "npx @biomejs/biome lint --write packages"
-  },
-  "workspaces": [
-    "packages/*"
-  ],
   "peerDependencies": {
     "react": ">=16.8.0",
     "react-dom": ">=16.8.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.0.6"
+    "@eslint/js": "9.39.2",
+    "@types/react": "19.2.8",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "5.1.2",
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/react": "16.3.1",
+    "@testing-library/user-event": "14.6.1",
+    "@types/node": "24.10.8",
+    "globals": "16.5.0",
+    "jsdom": "27.4.0",
+    "typescript": "5.9.3",
+    "vite": "7.3.1",
+    "vitest": "4.0.17",
+    "vite-plugin-dts": "4.5.4"
   }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2018 Johannes Klauss
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/packages/react-hotkeys-hook/dist/index.js

@@ -1,282 +0,0 @@
-import { createContext as T, useContext as M, useState as A, useCallback as w, useRef as S, useLayoutEffect as z, useEffect as J } from "react";
-import { jsx as b } from "react/jsx-runtime";
-const j = ["shift", "alt", "meta", "mod", "ctrl", "control"], Q = {
-  esc: "escape",
-  return: "enter",
-  left: "arrowleft",
-  right: "arrowright",
-  up: "arrowup",
-  down: "arrowdown",
-  ShiftLeft: "shift",
-  ShiftRight: "shift",
-  AltLeft: "alt",
-  AltRight: "alt",
-  MetaLeft: "meta",
-  MetaRight: "meta",
-  OSLeft: "meta",
-  OSRight: "meta",
-  ControlLeft: "ctrl",
-  ControlRight: "ctrl"
-};
-function K(e) {
-  return (Q[e.trim()] || e.trim()).toLowerCase().replace(/key|digit|numpad/, "");
-}
-function D(e) {
-  return j.includes(e);
-}
-function H(e, r = ",") {
-  return e.toLowerCase().split(r);
-}
-function P(e, r = "+", o = ">", i = !1, u) {
-  let n = [], c = !1;
-  e = e.trim(), e.includes(o) ? (c = !0, n = e.toLocaleLowerCase().split(o).map((f) => K(f))) : n = e.toLocaleLowerCase().split(r).map((f) => K(f));
-  const y = {
-    alt: n.includes("alt"),
-    ctrl: n.includes("ctrl") || n.includes("control"),
-    shift: n.includes("shift"),
-    meta: n.includes("meta"),
-    mod: n.includes("mod"),
-    useKey: i
-  }, d = n.filter((f) => !j.includes(f));
-  return {
-    ...y,
-    keys: d,
-    description: u,
-    isSequence: c,
-    hotkey: e
-  };
-}
-typeof document < "u" && (document.addEventListener("keydown", (e) => {
-  e.code !== void 0 && I([K(e.code)]);
-}), document.addEventListener("keyup", (e) => {
-  e.code !== void 0 && _([K(e.code)]);
-})), typeof window < "u" && (window.addEventListener("blur", () => {
-  L.clear();
-}), window.addEventListener("contextmenu", () => {
-  setTimeout(() => {
-    L.clear();
-  }, 0);
-}));
-const L = /* @__PURE__ */ new Set();
-function R(e) {
-  return Array.isArray(e);
-}
-function U(e, r = ",") {
-  return (R(e) ? e : e.split(r)).every((i) => L.has(i.trim().toLowerCase()));
-}
-function I(e) {
-  const r = Array.isArray(e) ? e : [e];
-  L.has("meta") && L.forEach((o) => !D(o) && L.delete(o.toLowerCase())), r.forEach((o) => L.add(o.toLowerCase()));
-}
-function _(e) {
-  const r = Array.isArray(e) ? e : [e];
-  e === "meta" ? L.clear() : r.forEach((o) => L.delete(o.toLowerCase()));
-}
-function V(e, r, o) {
-  (typeof o == "function" && o(e, r) || o === !0) && e.preventDefault();
-}
-function X(e, r, o) {
-  return typeof o == "function" ? o(e, r) : o === !0 || o === void 0;
-}
-const Y = [
-  "input",
-  "textarea",
-  "select",
-  "searchbox",
-  "slider",
-  "spinbutton",
-  "menuitem",
-  "menuitemcheckbox",
-  "menuitemradio",
-  "option",
-  "radio",
-  "textbox"
-];
-function Z(e) {
-  return F(e, Y);
-}
-function F(e, r = !1) {
-  const { target: o, composed: i } = e;
-  let u, n;
-  return ee(o) && i ? (u = e.composedPath()[0] && e.composedPath()[0].tagName, n = e.composedPath()[0] && e.composedPath()[0].role) : (u = o && o.tagName, n = o && o.role), R(r) ? !!(u && r && r.some((c) => c.toLowerCase() === u.toLowerCase() || c === n)) : !!(u && r && r);
-}
-function ee(e) {
-  return !!e.tagName && !e.tagName.startsWith("-") && e.tagName.includes("-");
-}
-function te(e, r) {
-  return e.length === 0 && r ? (console.warn(
-    'A hotkey has the "scopes" option set, however no active scopes were found. If you want to use the global scopes feature, you need to wrap your app in a <HotkeysProvider>'
-  ), !0) : r ? e.some((o) => r.includes(o)) || e.includes("*") : !0;
-}
-const re = (e, r, o = !1) => {
-  const { alt: i, meta: u, mod: n, shift: c, ctrl: y, keys: d, useKey: f } = r, { code: p, key: t, ctrlKey: a, metaKey: l, shiftKey: g, altKey: k } = e, m = K(p);
-  if (f && d?.length === 1 && d.includes(t))
-    return !0;
-  if (!d?.includes(m) && !["ctrl", "control", "unknown", "meta", "alt", "shift", "os"].includes(m))
-    return !1;
-  if (!o) {
-    if (i !== k && m !== "alt" || c !== g && m !== "shift")
-      return !1;
-    if (n) {
-      if (!l && !a)
-        return !1;
-    } else if (u !== l && m !== "meta" && m !== "os" || y !== a && m !== "ctrl" && m !== "control")
-      return !1;
-  }
-  return d && d.length === 1 && d.includes(m) ? !0 : d ? U(d) : !d;
-}, $ = T(void 0), oe = () => M($);
-function ne({ addHotkey: e, removeHotkey: r, children: o }) {
-  return /* @__PURE__ */ b($.Provider, { value: { addHotkey: e, removeHotkey: r }, children: o });
-}
-function x(e, r) {
-  return e && r && typeof e == "object" && typeof r == "object" ? Object.keys(e).length === Object.keys(r).length && // @ts-expect-error TS7053
-  Object.keys(e).reduce((o, i) => o && x(e[i], r[i]), !0) : e === r;
-}
-const W = T({
-  hotkeys: [],
-  activeScopes: [],
-  // This array has to be empty instead of containing '*' as default, to check if the provider is set or not
-  toggleScope: () => {
-  },
-  enableScope: () => {
-  },
-  disableScope: () => {
-  }
-}), se = () => M(W), de = ({ initiallyActiveScopes: e = ["*"], children: r }) => {
-  const [o, i] = A(e), [u, n] = A([]), c = w((t) => {
-    i((a) => a.includes("*") ? [t] : Array.from(/* @__PURE__ */ new Set([...a, t])));
-  }, []), y = w((t) => {
-    i((a) => a.filter((l) => l !== t));
-  }, []), d = w((t) => {
-    i((a) => a.includes(t) ? a.filter((l) => l !== t) : a.includes("*") ? [t] : Array.from(/* @__PURE__ */ new Set([...a, t])));
-  }, []), f = w((t) => {
-    n((a) => [...a, t]);
-  }, []), p = w((t) => {
-    n((a) => a.filter((l) => !x(l, t)));
-  }, []);
-  return /* @__PURE__ */ b(
-    W.Provider,
-    {
-      value: { activeScopes: o, hotkeys: u, enableScope: c, disableScope: y, toggleScope: d },
-      children: /* @__PURE__ */ b(ne, { addHotkey: f, removeHotkey: p, children: r })
-    }
-  );
-};
-function ie(e) {
-  const r = S(void 0);
-  return x(r.current, e) || (r.current = e), r.current;
-}
-const N = (e) => {
-  e.stopPropagation(), e.preventDefault(), e.stopImmediatePropagation();
-}, ue = typeof window < "u" ? z : J;
-function fe(e, r, o, i) {
-  const u = S(null), n = S(!1), c = Array.isArray(o) ? Array.isArray(i) ? void 0 : i : o, y = R(e) ? e.join(c?.delimiter) : e, d = Array.isArray(o) ? o : Array.isArray(i) ? i : void 0, f = w(r, d ?? []), p = S(f);
-  d ? p.current = f : p.current = r;
-  const t = ie(c), { activeScopes: a } = se(), l = oe();
-  return ue(() => {
-    if (t?.enabled === !1 || !te(a, t?.scopes))
-      return;
-    let g = [], k;
-    const m = (s, B = !1) => {
-      if (!(Z(s) && !F(s, t?.enableOnFormTags))) {
-        if (u.current !== null) {
-          const v = u.current.getRootNode();
-          if ((v instanceof Document || v instanceof ShadowRoot) && v.activeElement !== u.current && !u.current.contains(v.activeElement)) {
-            N(s);
-            return;
-          }
-        }
-        s.target?.isContentEditable && !t?.enableOnContentEditable || H(y, t?.delimiter).forEach((v) => {
-          if (v.includes(t?.splitKey ?? "+") && v.includes(t?.sequenceSplitKey ?? ">")) {
-            console.warn(
-              `Hotkey ${v} contains both ${t?.splitKey ?? "+"} and ${t?.sequenceSplitKey ?? ">"} which is not supported.`
-            );
-            return;
-          }
-          const h = P(
-            v,
-            t?.splitKey,
-            t?.sequenceSplitKey,
-            t?.useKey,
-            t?.description
-          );
-          if (h.isSequence) {
-            k = setTimeout(() => {
-              g = [];
-            }, t?.sequenceTimeoutMs ?? 1e3);
-            const C = h.useKey ? s.key : K(s.code);
-            if (D(C.toLowerCase()))
-              return;
-            g.push(C);
-            const G = h.keys?.[g.length - 1];
-            if (C !== G) {
-              g = [], k && clearTimeout(k);
-              return;
-            }
-            g.length === h.keys?.length && (p.current(s, h), k && clearTimeout(k), g = []);
-          } else if (re(s, h, t?.ignoreModifiers) || h.keys?.includes("*")) {
-            if (t?.ignoreEventWhen?.(s) || B && n.current)
-              return;
-            if (V(s, h, t?.preventDefault), !X(s, h, t?.enabled)) {
-              N(s);
-              return;
-            }
-            p.current(s, h), B || (n.current = !0);
-          }
-        });
-      }
-    }, O = (s) => {
-      s.code !== void 0 && (I(K(s.code)), (t?.keydown === void 0 && t?.keyup !== !0 || t?.keydown) && m(s));
-    }, q = (s) => {
-      s.code !== void 0 && (_(K(s.code)), n.current = !1, t?.keyup && m(s, !0));
-    }, E = u.current || c?.document || document;
-    return E.addEventListener("keyup", q, c?.eventListenerOptions), E.addEventListener("keydown", O, c?.eventListenerOptions), l && H(y, t?.delimiter).forEach(
-      (s) => l.addHotkey(
-        P(
-          s,
-          t?.splitKey,
-          t?.sequenceSplitKey,
-          t?.useKey,
-          t?.description
-        )
-      )
-    ), () => {
-      E.removeEventListener("keyup", q, c?.eventListenerOptions), E.removeEventListener("keydown", O, c?.eventListenerOptions), l && H(y, t?.delimiter).forEach(
-        (s) => l.removeHotkey(
-          P(
-            s,
-            t?.splitKey,
-            t?.sequenceSplitKey,
-            t?.useKey,
-            t?.description
-          )
-        )
-      ), g = [], k && clearTimeout(k);
-    };
-  }, [y, t, a]), u;
-}
-function le(e = !1) {
-  const [r, o] = A(/* @__PURE__ */ new Set()), [i, u] = A(!1), n = w(
-    (f) => {
-      f.code !== void 0 && (f.preventDefault(), f.stopPropagation(), o((p) => {
-        const t = new Set(p);
-        return t.add(K(e ? f.key : f.code)), t;
-      }));
-    },
-    [e]
-  ), c = w(() => {
-    typeof document < "u" && (document.removeEventListener("keydown", n), u(!1));
-  }, [n]), y = w(() => {
-    o(/* @__PURE__ */ new Set()), typeof document < "u" && (c(), document.addEventListener("keydown", n), u(!0));
-  }, [n, c]), d = w(() => {
-    o(/* @__PURE__ */ new Set());
-  }, []);
-  return [r, { start: y, stop: c, resetKeys: d, isRecording: i }];
-}
-export {
-  de as HotkeysProvider,
-  U as isHotkeyPressed,
-  fe as useHotkeys,
-  se as useHotkeysContext,
-  le as useRecordHotkeys
-};