@msobiecki/react-marauders-path 1.4.0 → 1.5.0

package/README.md

@@ -16,47 +16,68 @@ npm install @msobiecki/react-marauders-path
 
 ## Quick Start
 
-### Basic Key Detection
+### Single Key Schema
 
 ```typescript
 import { useKey } from '@msobiecki/react-marauders-path';
 
 function MyComponent() {
-  useKey('ArrowUp', (event) => {
-    console.log('ArrowUp pressed');
+  useKey('a', (event, key) => {
+    console.log(`Pressed ${key}`);
   });
 
-  return <div>Press arrow up</div>;
+  return <div>Press 'a'</div>;
 }
 ```
 
-### Key Combinations
+### Multiple Patterns of Single Keys Schema
 
 ```typescript
-// Listen for simultaneous key press (Control + a)
-useKey("Control+a", (event) => {
-  console.log("Control and a pressed together");
+// Listen to multiple key patterns
+useKey(["a", "b", "c"], (event, key) => {
+  console.log(`Pressed ${key}`);
 });
 ```
 
-### Key Sequences
+### Combination Keys Schema
 
 ```typescript
-// Listen for key sequence (a then b)
-useKey(["a", "b"], (event) => {
-  console.log("a then b pressed in sequence");
+// Listen for simultaneous key press (a + b pressed together within 500ms)
+useKey("a+b", (event, key) => {
+  console.log(`Pressed ${key}`);
 });
 ```
 
-### Multiple Keys
+### Multiple Patterns of Combination Keys Schema
 
 ```typescript
-// Listen to multiple key patterns
-useKey(["ArrowUp", "w"], (event) => {
-  console.log("Either ArrowUp or W pressed");
+// Listen for multiple combination patterns
+useKey(["a+b", "c+d"], (event, key) => {
+  console.log(`Pressed ${key}`);
+});
+```
+
+### Sequential Keys Schema
+
+```typescript
+// Listen for Konami code
+useKey("ArrowUp ArrowUp ArrowDown ArrowDown", (event, key) => {
+  console.log(`Pressed ${key}`);
 });
 ```
 
+### Multiple Patterns of Sequential Keys Schema
+
+```typescript
+// Listen for multiple sequences
+useKey(
+  ["ArrowUp ArrowUp ArrowDown ArrowDown", "ArrowLeft ArrowRight"],
+  (event, key) => {
+    console.log(`Pressed ${key}`);
+  },
+);
+```
+
 ## API
 
 ### `useKey(keyEvent, callback, options?)`
@@ -78,7 +99,8 @@ interface UseKeyOptions {
   eventCapture?: boolean; // Default: false
   eventOnce?: boolean; // Default: false
   eventStopImmediatePropagation?: boolean; // Default: false
-  sequenceTimeout?: number; // Default: 1000 (ms)
+  sequenceThreshold?: number; // Default: 1000 (ms) - Timeout between sequence keys
+  combinationThreshold?: number; // Default: 500 (ms) - Timeout between combination keys
   container?: RefObject<HTMLElement>; // Default: window
 }
 ```
@@ -89,6 +111,66 @@ One-time keyboard event listener. Automatically removes after first trigger.
 
 **Parameters:** Same as `useKey`
 
+## Advanced Examples
+
+### Using Options for Event Type and Propagation Control
+
+```typescript
+useKey(
+  "Enter",
+  (event, key) => {
+    handleSubmit();
+  },
+  {
+    eventType: "keydown",
+    eventStopImmediatePropagation: true,
+    container: inputRef,
+  },
+);
+```
+
+### Listening for Key Repeat
+
+```typescript
+// Allow repeated key presses to trigger callback (useful for games)
+useKey(
+  "ArrowUp",
+  (event, key) => {
+    moveUp();
+  },
+  {
+    eventType: "keydown",
+    eventRepeat: true,
+  },
+);
+```
+
+### Custom Thresholds for Sequences and Combinations
+
+```typescript
+// Increase threshold for slower typists
+useKey(
+  "a b c",
+  (event, key) => {
+    console.log(`Sequence: ${key}`);
+  },
+  {
+    sequenceThreshold: 2000, // 2 seconds between keys
+  },
+);
+
+// Increase threshold for combination keys
+useKey(
+  "a+b",
+  (event, key) => {
+    console.log(`Combination: ${key}`);
+  },
+  {
+    combinationThreshold: 1000, // 1 second window for simultaneous press
+  },
+);
+```
+
 ## Examples
 
 ### Game Controls
@@ -103,7 +185,10 @@ npm run dev
 
 This example demonstrates:
 
-- Real-time keyboard input handling
+- Real-time keyboard input handling with arrow keys
+- Sequential key patterns (e.g., Konami code)
+- Combination keys (simultaneous key presses)
+- Game collision detection and movement
 
 ## Development
 
@@ -127,8 +212,7 @@ npm lint
 
 ## Project Status
 
-- 🚧 Core `useKey` hook combinations support
-- 🚧 `useKey` hook combinations unit test coverage
+- 🚧 Core `useKey` combination sequence pattern
 - 🚧 Core `useMouse` hook
 - 🚧 Core `useMouse` hook unit test coverage
 - 🚧 Example of usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msobiecki/react-marauders-path",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "engines": {
     "node": ">=22.17.1"
@@ -25,12 +25,12 @@
     "@anolilab/multi-semantic-release": "^4.1.1",
     "@commitlint/cli": "^20.4.1",
     "@commitlint/config-conventional": "^20.4.1",
-    "@msobiecki/eslint-config": "^9.11.0",
+    "@msobiecki/eslint-config": "^9.12.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@testing-library/react": "^16.3.2",
-    "@types/node": "^25.2.0",
-    "@types/react": "^19.2.7",
+    "@types/node": "^25.2.2",
+    "@types/react": "^19.2.13",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react-swc": "^4.2.3",
     "eslint": "^9.39.2",