use-simple-keyboard 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.2] - 2026-07-07
+
+### Fixed
+
+- **`useHotkeys` catch-all ordering**: Specific hotkeys now correctly take precedence over the empty string (`""`) catch-all, regardless of definition order in the record object.
+- **`useKeySequence` re-triggering**: When `resetOnComplete` is set to `false`, completing a sequence now properly resets the internal tracking index to `0` while maintaining `matchedKeys` history, allowing the sequence to be re-entered and re-triggered without unmounting.
+
 ## [0.0.1] - 2026-05-13
 
 ### Added
@@ -24,4 +31,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Comprehensive test suite (72 tests, ~95% line coverage)
 - Interactive demo application (`demos/`)
 
+[0.0.2]: https://github.com/SkorpionG/use-simple-keyboard/compare/v0.0.1...v0.0.2
 [0.0.1]: https://github.com/SkorpionG/use-simple-keyboard/releases/tag/v0.0.1

package/dist/hooks/useHotkey.d.ts

@@ -1,3 +1,4 @@
+import { type KeyboardEventTarget } from '../utils/domUtils';
 import type { HotkeyInput, HotkeysRecord, HotkeyCallback } from '../types/keys';
 export interface UseHotkeyOptions {
     /**
@@ -19,7 +20,7 @@ export interface UseHotkeyOptions {
      * Target element to attach the event listener to
      * @default document
      */
-    target?: HTMLElement | Document | Window | null;
+    target?: KeyboardEventTarget;
     /**
      * Event type to listen for
      * @default 'keydown'
@@ -29,7 +30,10 @@ export interface UseHotkeyOptions {
 /**
  * React hook for handling keyboard shortcuts/hotkeys
  *
- * @param keys - Array of keys that should be pressed to trigger the callback
+ * @param keys - Array of keys or string containing keys that should be pressed to trigger the callback.
+ *               Note: When passing an array, ensure it is a stable reference (e.g. via useMemo or defined outside the component)
+ *               to prevent unnecessary effect executions on every render. If an array contains a single string with a '+',
+ *               it will be parsed as a combined string (e.g., `['ctrl+c']` is identical to `'ctrl+c'`).
  * @param callback - Function to execute when the hotkey is pressed
  * @param options - Additional options for the hotkey behavior
  *

package/dist/hooks/useHotkey.js

@@ -1,9 +1,13 @@
 import { useEffect, useCallback, useRef } from 'react';
 import { matchesHotkey, parseHotkey, createKeyInfo, } from '../utils/keyUtils';
+import { getDefaultTarget } from '../utils/domUtils';
 /**
  * React hook for handling keyboard shortcuts/hotkeys
  *
- * @param keys - Array of keys that should be pressed to trigger the callback
+ * @param keys - Array of keys or string containing keys that should be pressed to trigger the callback.
+ *               Note: When passing an array, ensure it is a stable reference (e.g. via useMemo or defined outside the component)
+ *               to prevent unnecessary effect executions on every render. If an array contains a single string with a '+',
+ *               it will be parsed as a combined string (e.g., `['ctrl+c']` is identical to `'ctrl+c'`).
  * @param callback - Function to execute when the hotkey is pressed
  * @param options - Additional options for the hotkey behavior
  *
@@ -26,7 +30,7 @@ import { matchesHotkey, parseHotkey, createKeyInfo, } from '../utils/keyUtils';
  * ```
  */
 export const useHotkey = (keys, callback, options = {}) => {
-    const { enabled = true, preventDefault = true, stopPropagation = false, target = typeof document !== 'undefined' ? document : null, eventType = 'keydown', } = options;
+    const { enabled = true, preventDefault = true, stopPropagation = false, target = getDefaultTarget(), eventType = 'keydown', } = options;
     // Convert keys to array and normalize
     const normalizedKeys = useRef([]);
     const callbackRef = useRef(callback);
@@ -50,6 +54,7 @@ export const useHotkey = (keys, callback, options = {}) => {
         }
     }, [keys]);
     const handleKeyEvent = useCallback((event) => {
+        /* istanbul ignore next */
         if (!enabled)
             return;
         const keyInfo = createKeyInfo(event);
@@ -114,13 +119,14 @@ export const useHotkey = (keys, callback, options = {}) => {
  * ```
  */
 export const useHotkeys = (hotkeys, options = {}) => {
-    const { enabled = true, preventDefault = true, stopPropagation = false, target = typeof document !== 'undefined' ? document : null, eventType = 'keydown', } = options;
+    const { enabled = true, preventDefault = true, stopPropagation = false, target = getDefaultTarget(), eventType = 'keydown', } = options;
     const hotkeysRef = useRef(hotkeys);
     // Update hotkeys ref when hotkeys change
     useEffect(() => {
         hotkeysRef.current = hotkeys;
     }, [hotkeys]);
     const handleKeyEvent = useCallback((event) => {
+        /* istanbul ignore next */
         if (!enabled)
             return;
         const keyInfo = createKeyInfo(event);
@@ -132,10 +138,14 @@ export const useHotkeys = (hotkeys, options = {}) => {
             altKey: event.altKey,
             shiftKey: event.shiftKey,
         };
-        // Check each hotkey combination
+        // First pass: check specific hotkeys (non-empty keys)
+        // This ensures the catch-all never steals events that have a specific match.
+        let matched = false;
         for (const [keys, callback] of Object.entries(hotkeysRef.current)) {
-            // Handle empty string for catch-all
-            if (keys === '') {
+            if (keys === '')
+                continue; // skip catch-all in first pass
+            const keyArray = keys.includes('+') ? parseHotkey(keys) : [keys];
+            if (matchesHotkey(keyEvent, keyArray)) {
                 if (preventDefault) {
                     event.preventDefault();
                 }
@@ -143,20 +153,21 @@ export const useHotkeys = (hotkeys, options = {}) => {
                     event.stopPropagation();
                 }
                 callback(event, keyInfo);
-                break; // Only trigger the first matching hotkey
+                matched = true;
+                break;
             }
-            else {
-                const keyArray = keys.includes('+') ? parseHotkey(keys) : [keys];
-                if (matchesHotkey(keyEvent, keyArray)) {
-                    if (preventDefault) {
-                        event.preventDefault();
-                    }
-                    if (stopPropagation) {
-                        event.stopPropagation();
-                    }
-                    callback(event, keyInfo);
-                    break; // Only trigger the first matching hotkey
+        }
+        // Second pass: fire catch-all only if no specific hotkey matched
+        if (!matched) {
+            const catchAllCallback = hotkeysRef.current[''];
+            if (catchAllCallback !== undefined) {
+                if (preventDefault) {
+                    event.preventDefault();
+                }
+                if (stopPropagation) {
+                    event.stopPropagation();
                 }
+                catchAllCallback(event, keyInfo);
             }
         }
     }, [enabled, preventDefault, stopPropagation]);

package/dist/hooks/useKeySequence.d.ts

@@ -1,3 +1,4 @@
+import { type KeyboardEventTarget } from '../utils/domUtils';
 import type { HotkeyInput, HotkeyCallback } from '../types/keys';
 export interface UseKeySequenceOptions {
     /**
@@ -19,7 +20,7 @@ export interface UseKeySequenceOptions {
      * Target element to attach the event listener to
      * @default document
      */
-    target?: HTMLElement | Document | Window | null;
+    target?: KeyboardEventTarget;
     /**
      * Event type to listen for
      * @default 'keydown'

package/dist/hooks/useKeySequence.js

@@ -1,5 +1,6 @@
 import { useEffect, useCallback, useRef, useState } from 'react';
 import { matchesHotkey, parseHotkey, createKeyInfo, } from '../utils/keyUtils';
+import { getDefaultTarget } from '../utils/domUtils';
 /**
  * Hook for handling key sequences (e.g., Konami code, custom shortcuts)
  *
@@ -28,7 +29,7 @@ import { matchesHotkey, parseHotkey, createKeyInfo, } from '../utils/keyUtils';
  * ```
  */
 export const useKeySequence = (sequence, callback, options = {}) => {
-    const { enabled = true, preventDefault = true, stopPropagation = false, target = typeof document !== 'undefined' ? document : null, eventType = 'keydown', timeout = 1000, resetOnComplete = true, strict = false, } = options;
+    const { enabled = true, preventDefault = true, stopPropagation = false, target = getDefaultTarget(), eventType = 'keydown', timeout = 1000, resetOnComplete = true, strict = false, } = options;
     const [state, setState] = useState({
         currentIndex: 0,
         isActive: false,
@@ -57,10 +58,9 @@ export const useKeySequence = (sequence, callback, options = {}) => {
         });
     }, [sequence]);
     const resetSequence = useCallback(() => {
-        if (timeoutRef.current) {
-            clearTimeout(timeoutRef.current);
-            timeoutRef.current = null;
-        }
+        // clearTimeout is always safe to call even when no timer is active
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
         setState((prev) => ({
             ...prev,
             currentIndex: 0,
@@ -96,9 +96,11 @@ export const useKeySequence = (sequence, callback, options = {}) => {
         setState((prevState) => {
             const { currentIndex } = prevState;
             const expectedKeys = sequenceRef.current[currentIndex];
-            if (!expectedKeys) {
+            // Defensive guard: expectedKeys should always be defined here since
+            // currentIndex is always bounded to [0, sequence.length - 1].
+            /* istanbul ignore next */
+            if (!expectedKeys)
                 return prevState;
-            }
             // Check if current key matches the expected key in sequence
             const isMatch = matchesHotkey(keyEvent, expectedKeys);
             if (isMatch) {
@@ -133,9 +135,11 @@ export const useKeySequence = (sequence, callback, options = {}) => {
                         };
                     }
                     else {
+                        // Keep matchedKeys for history but reset currentIndex to 0 so
+                        // the sequence can be re-entered and re-triggered.
                         return {
-                            currentIndex: newIndex,
-                            isActive: true,
+                            currentIndex: 0,
+                            isActive: false,
                             matchedKeys: newMatchedKeys,
                             timeoutId: null,
                         };

package/dist/utils/domUtils.d.ts

@@ -0,0 +1,2 @@
+export type KeyboardEventTarget = HTMLElement | Document | Window | null;
+export declare const getDefaultTarget: () => Document | null;

package/dist/utils/domUtils.js

@@ -0,0 +1,3 @@
+export const getDefaultTarget = () => 
+/* istanbul ignore next -- SSR fallback is not reachable in the jsdom test environment */
+typeof document !== 'undefined' ? document : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-simple-keyboard",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "React hooks for handling keyboard inputs and hotkeys across different platforms",
   "license": "MIT",
   "author": "SkorpionG",
@@ -25,14 +25,22 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "typecheck": "tsc --project tsconfig.typecheck.json",
+    "typecheck:all": "npm run typecheck && npm --prefix demos run typecheck",
     "test": "jest --config jest.config.ts",
     "test:watch": "jest --config jest.config.ts --watch",
     "test:coverage": "jest --config jest.config.ts --coverage",
+    "test:coverage:text": "jest --config jest.config.ts --coverage --coverageReporters='text'",
     "lint": "eslint .",
+    "lint:all": "npm run lint && npm --prefix demos run lint",
     "lint:fix": "eslint . --fix",
-    "format": "prettier --write \"{src,test}/**/*.{ts,tsx}\" \"*.{json,md}\"",
-    "format:check": "prettier --check \"{src,test}/**/*.{ts,tsx}\" \"*.{json,md}\"",
-    "prepublishOnly": "npm run format && npm run typecheck && npm run lint && npm run test && npm run build"
+    "lint:fix:all": "npm run lint:fix && npm --prefix demos run lint:fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "format:all": "npm run format && npm --prefix demos run format",
+    "format:check:all": "npm run format:check && npm --prefix demos run format:check",
+    "prepublishOnly": "npm run format && npm run typecheck && npm run lint && npm run test && npm run build",
+    "prepare": "husky",
+    "husky:chmod": "chmod +x .husky/pre-commit"
   },
   "keywords": [
     "react",
@@ -45,25 +53,34 @@
   "peerDependencies": {
     "react": ">=16.8.0"
   },
+  "overrides": {
+    "eslint": "$eslint"
+  },
   "devDependencies": {
-    "@eslint/js": "^9.36.0",
+    "@eslint/js": "^10.0.1",
+    "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/jest": "^30.0.0",
-    "@types/react": "^19.2.14",
-    "@typescript-eslint/eslint-plugin": "^8.59.3",
-    "@typescript-eslint/parser": "^8.59.3",
-    "eslint": "^9.36.0",
+    "@types/react": "^19.2.17",
+    "@typescript-eslint/eslint-plugin": "^8.63.0",
+    "@typescript-eslint/parser": "^8.63.0",
+    "eslint": "^10.6.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-prettier": "^5.5.6",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
+    "husky": "^9.1.7",
     "jest": "^30.4.2",
     "jest-environment-jsdom": "^30.4.1",
     "jiti": "^2.7.0",
-    "prettier": "^3.8.3",
-    "ts-jest": "^29.4.9",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.9.4",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "ts-jest": "^29.4.11",
+    "ts-node": "^10.9.2",
     "typescript": "^6.0.3"
   }
 }