use-simple-keyboard 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+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.1] - 2026-05-13
+
+### Added
+
+- `useHotkey` hook — listen for a single key or key combination (`ctrl+c`, `meta+s`, `escape`, etc.)
+- `useHotkeys` hook — register multiple hotkeys at once via a key→callback record
+- `useKeySequence` hook — detect sequential key presses (e.g. Konami code), with configurable timeout, strict mode, and reset-on-complete
+- Full TypeScript definitions including `UseHotkeyOptions`, `UseKeySequenceOptions`, `KeySequenceState`, `HotkeyCallback`, `KeyInfo`, and all key types
+- Cross-platform key normalization (`normalizeKey`, `parseHotkey`, `matchesHotkey`, `keysToHotkey`, `createKeyInfo`)
+- `getPlatformModifier` utility to detect Cmd (macOS) vs Ctrl (Windows/Linux)
+- Support for `keydown`, `keyup`, and `keypress` event types
+- `enabled` option to conditionally activate/deactivate hooks without unmounting
+- `preventDefault` and `stopPropagation` options per hook
+- Custom `target` element support (defaults to `document`)
+- Catch-all listener via empty string key (`""`)
+- Zero runtime dependencies — only a React peer dependency (`>=16.8.0`)
+- Comprehensive test suite (72 tests, ~95% line coverage)
+- Interactive demo application (`demos/`)
+
+[0.0.1]: https://github.com/SkorpionG/use-simple-keyboard/releases/tag/v0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SkorpionG2000
+
+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/README.md

@@ -0,0 +1,301 @@
+# useSimpleKeyboard
+
+A simple library of React hooks for handling keyboard inputs and hotkeys across different platforms and languages.
+
+[![npm version](https://img.shields.io/npm/v/use-simple-keyboard.svg)](https://www.npmjs.com/package/use-simple-keyboard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🎯 **Cross-platform support** - Works consistently across Windows, macOS, and Linux
+- 🌍 **Multi-language keyboard support** - Handles different keyboard layouts and languages
+- ⚡ **Lightweight** - Zero dependencies (except React peer dependency)
+- 🔧 **TypeScript support** - Full TypeScript definitions included
+- 🎨 **Flexible API** - Support for single hotkeys and multiple hotkey combinations
+- 🛡️ **Event handling** - Built-in preventDefault and stopPropagation options
+
+## Installation
+
+```bash
+npm install use-simple-keyboard
+```
+
+## Quick Start
+
+```tsx
+import React from 'react';
+import { useHotkey } from 'use-simple-keyboard';
+
+function App() {
+  // Simple hotkey
+  useHotkey(['ctrl', 'c'], () => {
+    console.log('Copy triggered!');
+  });
+
+  // Platform-specific hotkey (Cmd on Mac, Ctrl on others)
+  useHotkey(['meta', 's'], () => {
+    console.log('Save triggered!');
+  });
+
+  return <div>Press Ctrl+C or Cmd+S (Mac)</div>;
+}
+```
+
+## API Reference
+
+### `useHotkey(keys, callback, options?)`
+
+The main hook for handling single hotkey combinations.
+
+#### Parameters
+
+- **keys**: `string | string[]` - The key combination to listen for
+- **callback**: `(event: KeyboardEvent) => void` - Function to execute when hotkey is pressed
+- **options**: `UseHotkeyOptions` - Optional configuration
+
+#### Key Formats
+
+You can specify keys in multiple formats:
+
+```tsx
+// Array format
+useHotkey(['ctrl', 'c'], callback);
+useHotkey(['ctrl', 'shift', 'z'], callback);
+
+// String format with '+' separator
+useHotkey('ctrl+c', callback);
+useHotkey('ctrl+shift+z', callback);
+
+// Single key
+useHotkey('escape', callback);
+useHotkey(['f1'], callback);
+```
+
+#### Supported Keys
+
+**Modifier Keys:**
+
+- `ctrl` / `control` - Control key
+- `meta` / `cmd` / `command` - Command key (Mac) / Windows key
+- `alt` - Alt key
+- `shift` - Shift key
+
+**Special Keys:**
+
+- `enter` / `return`
+- `escape` / `esc`
+- `space` / `spacebar`
+- `tab`
+- `backspace`
+- `delete` / `del`
+- `insert`
+- `home`, `end`
+- `pageup`, `pagedown`
+- `arrowup`, `arrowdown`, `arrowleft`, `arrowright` (or `up`, `down`, `left`, `right`)
+
+**Function Keys:**
+
+- `f1` through `f12`
+
+**Regular Keys:**
+
+- Any letter: `a`, `b`, `c`, etc.
+- Any number: `1`, `2`, `3`, etc.
+- Any symbol: `+`, `-`, `=`, etc.
+
+#### Options
+
+```tsx
+interface UseHotkeyOptions {
+  enabled?: boolean; // Default: true
+  preventDefault?: boolean; // Default: true
+  stopPropagation?: boolean; // Default: false
+  target?: HTMLElement | Document | Window | null; // Default: document
+  eventType?: 'keydown' | 'keyup' | 'keypress'; // Default: 'keydown'
+}
+```
+
+### `useHotkeys(hotkeys, options?)`
+
+Hook for handling multiple hotkeys at once.
+
+```tsx
+import { useHotkeys } from 'use-simple-keyboard';
+
+function Editor() {
+  useHotkeys({
+    'ctrl+c': () => copy(),
+    'ctrl+v': () => paste(),
+    'ctrl+z': () => undo(),
+    'ctrl+shift+z': () => redo(),
+    'ctrl+s': () => save(),
+    escape: () => closeModal(),
+  });
+
+  return <div>Text Editor</div>;
+}
+```
+
+## Usage Examples
+
+### Basic Hotkeys
+
+```tsx
+import { useHotkey } from 'use-simple-keyboard';
+
+function BasicExample() {
+  useHotkey(['ctrl', 'c'], () => alert('Copy!'));
+  useHotkey(['ctrl', 'v'], () => alert('Paste!'));
+  useHotkey('escape', () => alert('Escape pressed!'));
+
+  return <div>Try Ctrl+C, Ctrl+V, or Escape</div>;
+}
+```
+
+### Platform-Specific Hotkeys
+
+```tsx
+function PlatformExample() {
+  // Use 'meta' for Cmd on Mac, Ctrl on others
+  useHotkey(['meta', 's'], () => save());
+
+  // Or handle both explicitly
+  useHotkey(['ctrl', 's'], () => save()); // Windows/Linux
+  useHotkey(['cmd', 's'], () => save()); // Mac
+
+  return <div>Press Cmd+S (Mac) or Ctrl+S (Windows/Linux)</div>;
+}
+```
+
+### Conditional Hotkeys
+
+```tsx
+function ConditionalExample() {
+  const [isEditing, setIsEditing] = useState(false);
+
+  useHotkey(['ctrl', 'e'], () => setIsEditing(true), {
+    enabled: !isEditing,
+  });
+
+  useHotkey('escape', () => setIsEditing(false), {
+    enabled: isEditing,
+  });
+
+  return (
+    <div>
+      {isEditing ? 'Editing mode - Press Escape' : 'Press Ctrl+E to edit'}
+    </div>
+  );
+}
+```
+
+### Scoped Hotkeys
+
+```tsx
+function ScopedExample() {
+  const modalRef = useRef<HTMLDivElement>(null);
+
+  // Only listen for hotkeys within the modal
+  useHotkey('escape', () => closeModal(), {
+    target: modalRef.current,
+  });
+
+  return (
+    <div ref={modalRef} tabIndex={-1}>
+      Modal content - Press Escape to close
+    </div>
+  );
+}
+```
+
+### Complex Combinations
+
+```tsx
+function ComplexExample() {
+  // Multiple modifier keys
+  useHotkey(['ctrl', 'shift', 'alt', 'r'], () => {
+    console.log('Super reload!');
+  });
+
+  // Function keys
+  useHotkey('f12', () => openDevTools());
+
+  // Number keys
+  useHotkey(['ctrl', '1'], () => switchToTab(1));
+  useHotkey(['ctrl', '2'], () => switchToTab(2));
+
+  return <div>Try various key combinations</div>;
+}
+```
+
+### Global App Hotkeys
+
+```tsx
+function App() {
+  useHotkeys({
+    // File operations
+    'ctrl+n': () => newFile(),
+    'ctrl+o': () => openFile(),
+    'ctrl+s': () => saveFile(),
+
+    // Edit operations
+    'ctrl+z': () => undo(),
+    'ctrl+y': () => redo(),
+    'ctrl+shift+z': () => redo(), // Alternative redo
+
+    // Navigation
+    'ctrl+f': () => openSearch(),
+    'ctrl+g': () => findNext(),
+    'ctrl+shift+g': () => findPrevious(),
+
+    // Application
+    f11: () => toggleFullscreen(),
+    'ctrl+shift+i': () => openDevTools(),
+  });
+
+  return <YourAppContent />;
+}
+```
+
+## Cross-Platform Considerations
+
+The library automatically handles platform differences:
+
+- **macOS**: Uses `meta` key (Cmd) for system shortcuts
+- **Windows/Linux**: Uses `ctrl` key for system shortcuts
+- **Key normalization**: Handles different key representations across browsers
+- **Language support**: Works with different keyboard layouts and languages
+
+## TypeScript Support
+
+The library is written in TypeScript and includes full type definitions:
+
+```tsx
+import { useHotkey, UseHotkeyOptions, KeyEvent } from 'use-simple-keyboard';
+
+const options: UseHotkeyOptions = {
+  enabled: true,
+  preventDefault: true,
+  target: document.body,
+};
+
+useHotkey(
+  ['ctrl', 'c'],
+  (event: KeyboardEvent) => {
+    // event is properly typed
+    console.log(event.key);
+  },
+  options
+);
+```
+
+## Browser Support
+
+- Chrome/Chromium 60+
+- Firefox 55+
+- Safari 12+
+- Edge 79+
+
+## License
+
+MIT

package/dist/hooks/useHotkey.d.ts

@@ -0,0 +1,73 @@
+import type { HotkeyInput, HotkeysRecord, HotkeyCallback } from '../types/keys';
+export interface UseHotkeyOptions {
+    /**
+     * Whether the hotkey should be enabled
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Whether to prevent the default browser behavior when the hotkey is triggered
+     * @default true
+     */
+    preventDefault?: boolean;
+    /**
+     * Whether to stop event propagation when the hotkey is triggered
+     * @default false
+     */
+    stopPropagation?: boolean;
+    /**
+     * Target element to attach the event listener to
+     * @default document
+     */
+    target?: HTMLElement | Document | Window | null;
+    /**
+     * Event type to listen for
+     * @default 'keydown'
+     */
+    eventType?: 'keydown' | 'keyup' | 'keypress';
+}
+/**
+ * React hook for handling keyboard shortcuts/hotkeys
+ *
+ * @param keys - Array of keys that should be pressed to trigger the callback
+ * @param callback - Function to execute when the hotkey is pressed
+ * @param options - Additional options for the hotkey behavior
+ *
+ * @example
+ * ```tsx
+ * // Simple hotkey
+ * useHotkey(['ctrl', 'c'], () => console.log('Copy!'));
+ *
+ * // Multiple key combination
+ * useHotkey(['ctrl', 'shift', 'z'], () => console.log('Redo!'));
+ *
+ * // Platform-specific (cmd on Mac, ctrl on others)
+ * useHotkey(['meta', 's'], () => console.log('Save!'));
+ *
+ * // With options
+ * useHotkey(['escape'], handleEscape, {
+ *   preventDefault: false,
+ *   enabled: isModalOpen
+ * });
+ * ```
+ */
+export declare const useHotkey: (keys: HotkeyInput, callback: HotkeyCallback, options?: UseHotkeyOptions) => void;
+/**
+ * Hook for handling multiple hotkeys at once
+ *
+ * @param hotkeys - Object mapping hotkey combinations to their callbacks
+ * @param options - Global options applied to all hotkeys
+ *
+ * @example
+ * ```tsx
+ * useHotkeys({
+ *   'ctrl+c': () => copy(),
+ *   'ctrl+v': () => paste(),
+ *   'ctrl+z': () => undo(),
+ *   'ctrl+shift+z': () => redo(),
+ *   'escape': () => closeModal()
+ * });
+ * ```
+ */
+export declare const useHotkeys: (hotkeys: HotkeysRecord, options?: UseHotkeyOptions) => void;
+export default useHotkey;

package/dist/hooks/useHotkey.js

@@ -0,0 +1,173 @@
+import { useEffect, useCallback, useRef } from 'react';
+import { matchesHotkey, parseHotkey, createKeyInfo, } from '../utils/keyUtils';
+/**
+ * React hook for handling keyboard shortcuts/hotkeys
+ *
+ * @param keys - Array of keys that should be pressed to trigger the callback
+ * @param callback - Function to execute when the hotkey is pressed
+ * @param options - Additional options for the hotkey behavior
+ *
+ * @example
+ * ```tsx
+ * // Simple hotkey
+ * useHotkey(['ctrl', 'c'], () => console.log('Copy!'));
+ *
+ * // Multiple key combination
+ * useHotkey(['ctrl', 'shift', 'z'], () => console.log('Redo!'));
+ *
+ * // Platform-specific (cmd on Mac, ctrl on others)
+ * useHotkey(['meta', 's'], () => console.log('Save!'));
+ *
+ * // With options
+ * useHotkey(['escape'], handleEscape, {
+ *   preventDefault: false,
+ *   enabled: isModalOpen
+ * });
+ * ```
+ */
+export const useHotkey = (keys, callback, options = {}) => {
+    const { enabled = true, preventDefault = true, stopPropagation = false, target = typeof document !== 'undefined' ? document : null, eventType = 'keydown', } = options;
+    // Convert keys to array and normalize
+    const normalizedKeys = useRef([]);
+    const callbackRef = useRef(callback);
+    // Update callback ref when callback changes
+    useEffect(() => {
+        callbackRef.current = callback;
+    }, [callback]);
+    // Parse and normalize keys
+    useEffect(() => {
+        const keyArray = Array.isArray(keys) ? keys : [keys];
+        // Handle empty string for all keys
+        if (keyArray.length === 1 && keyArray[0] === '') {
+            normalizedKeys.current = [''];
+        }
+        // If it's a single string with '+', parse it as a hotkey combination
+        else if (keyArray.length === 1 && keyArray[0].includes('+')) {
+            normalizedKeys.current = parseHotkey(keyArray[0]);
+        }
+        else {
+            normalizedKeys.current = keyArray.map((key) => key.toLowerCase().trim());
+        }
+    }, [keys]);
+    const handleKeyEvent = useCallback((event) => {
+        if (!enabled)
+            return;
+        const keyInfo = createKeyInfo(event);
+        // Check if this is a catch-all listener (empty string)
+        const isCatchAll = normalizedKeys.current.length === 1 && normalizedKeys.current[0] === '';
+        if (isCatchAll) {
+            // Trigger for all key presses
+            if (preventDefault) {
+                event.preventDefault();
+            }
+            if (stopPropagation) {
+                event.stopPropagation();
+            }
+            callbackRef.current(event, keyInfo);
+        }
+        else {
+            // Normal hotkey matching
+            const keyEvent = {
+                key: event.key,
+                code: event.code,
+                ctrlKey: event.ctrlKey,
+                metaKey: event.metaKey,
+                altKey: event.altKey,
+                shiftKey: event.shiftKey,
+            };
+            if (matchesHotkey(keyEvent, normalizedKeys.current)) {
+                if (preventDefault) {
+                    event.preventDefault();
+                }
+                if (stopPropagation) {
+                    event.stopPropagation();
+                }
+                callbackRef.current(event, keyInfo);
+            }
+        }
+    }, [enabled, preventDefault, stopPropagation]);
+    useEffect(() => {
+        if (!target || !enabled)
+            return;
+        const element = target;
+        element.addEventListener(eventType, handleKeyEvent);
+        return () => {
+            element.removeEventListener(eventType, handleKeyEvent);
+        };
+    }, [target, enabled, eventType, handleKeyEvent]);
+};
+/**
+ * Hook for handling multiple hotkeys at once
+ *
+ * @param hotkeys - Object mapping hotkey combinations to their callbacks
+ * @param options - Global options applied to all hotkeys
+ *
+ * @example
+ * ```tsx
+ * useHotkeys({
+ *   'ctrl+c': () => copy(),
+ *   'ctrl+v': () => paste(),
+ *   'ctrl+z': () => undo(),
+ *   'ctrl+shift+z': () => redo(),
+ *   'escape': () => closeModal()
+ * });
+ * ```
+ */
+export const useHotkeys = (hotkeys, options = {}) => {
+    const { enabled = true, preventDefault = true, stopPropagation = false, target = typeof document !== 'undefined' ? document : null, eventType = 'keydown', } = options;
+    const hotkeysRef = useRef(hotkeys);
+    // Update hotkeys ref when hotkeys change
+    useEffect(() => {
+        hotkeysRef.current = hotkeys;
+    }, [hotkeys]);
+    const handleKeyEvent = useCallback((event) => {
+        if (!enabled)
+            return;
+        const keyInfo = createKeyInfo(event);
+        const keyEvent = {
+            key: event.key,
+            code: event.code,
+            ctrlKey: event.ctrlKey,
+            metaKey: event.metaKey,
+            altKey: event.altKey,
+            shiftKey: event.shiftKey,
+        };
+        // Check each hotkey combination
+        for (const [keys, callback] of Object.entries(hotkeysRef.current)) {
+            // Handle empty string for catch-all
+            if (keys === '') {
+                if (preventDefault) {
+                    event.preventDefault();
+                }
+                if (stopPropagation) {
+                    event.stopPropagation();
+                }
+                callback(event, keyInfo);
+                break; // Only trigger the first matching hotkey
+            }
+            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
+                }
+            }
+        }
+    }, [enabled, preventDefault, stopPropagation]);
+    useEffect(() => {
+        if (!target || !enabled)
+            return;
+        const element = target;
+        element.addEventListener(eventType, handleKeyEvent);
+        return () => {
+            element.removeEventListener(eventType, handleKeyEvent);
+        };
+    }, [target, enabled, eventType, handleKeyEvent]);
+};
+export default useHotkey;

package/dist/hooks/useKeySequence.d.ts

@@ -0,0 +1,79 @@
+import type { HotkeyInput, HotkeyCallback } from '../types/keys';
+export interface UseKeySequenceOptions {
+    /**
+     * Whether the key sequence should be enabled
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Whether to prevent the default browser behavior when keys in the sequence are triggered
+     * @default true
+     */
+    preventDefault?: boolean;
+    /**
+     * Whether to stop event propagation when keys in the sequence are triggered
+     * @default false
+     */
+    stopPropagation?: boolean;
+    /**
+     * Target element to attach the event listener to
+     * @default document
+     */
+    target?: HTMLElement | Document | Window | null;
+    /**
+     * Event type to listen for
+     * @default 'keydown'
+     */
+    eventType?: 'keydown' | 'keyup';
+    /**
+     * Time in milliseconds to wait for the next key in the sequence
+     * If exceeded, the sequence resets
+     * @default 1000
+     */
+    timeout?: number;
+    /**
+     * Whether to reset the sequence after successful completion
+     * @default true
+     */
+    resetOnComplete?: boolean;
+    /**
+     * Whether to allow partial matches to continue the sequence
+     * If false, any non-matching key will reset the sequence
+     * @default false
+     */
+    strict?: boolean;
+}
+export interface KeySequenceState {
+    currentIndex: number;
+    isActive: boolean;
+    matchedKeys: string[];
+    timeoutId: number | null;
+}
+/**
+ * Hook for handling key sequences (e.g., Konami code, custom shortcuts)
+ *
+ * @param sequence - Array of keys/hotkey combinations that must be pressed in order
+ * @param callback - Function to call when the sequence is completed
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * // Simple sequence: up, up, down, down
+ * useKeySequence(['arrowup', 'arrowup', 'arrowdown', 'arrowdown'], () => {
+ *   console.log('Konami code entered!');
+ * });
+ *
+ * // Mixed sequence with hotkeys
+ * useKeySequence(['ctrl+c', 'ctrl+v', 'enter'], () => {
+ *   console.log('Copy-paste-enter sequence!');
+ * });
+ *
+ * // With options
+ * useKeySequence(['a', 'b', 'c'], handleSequence, {
+ *   timeout: 2000,
+ *   strict: true,
+ *   resetOnComplete: false
+ * });
+ * ```
+ */
+export declare const useKeySequence: (sequence: HotkeyInput[], callback: HotkeyCallback, options?: UseKeySequenceOptions) => KeySequenceState;

package/dist/hooks/useKeySequence.js

@@ -0,0 +1,205 @@
+import { useEffect, useCallback, useRef, useState } from 'react';
+import { matchesHotkey, parseHotkey, createKeyInfo, } from '../utils/keyUtils';
+/**
+ * Hook for handling key sequences (e.g., Konami code, custom shortcuts)
+ *
+ * @param sequence - Array of keys/hotkey combinations that must be pressed in order
+ * @param callback - Function to call when the sequence is completed
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * // Simple sequence: up, up, down, down
+ * useKeySequence(['arrowup', 'arrowup', 'arrowdown', 'arrowdown'], () => {
+ *   console.log('Konami code entered!');
+ * });
+ *
+ * // Mixed sequence with hotkeys
+ * useKeySequence(['ctrl+c', 'ctrl+v', 'enter'], () => {
+ *   console.log('Copy-paste-enter sequence!');
+ * });
+ *
+ * // With options
+ * useKeySequence(['a', 'b', 'c'], handleSequence, {
+ *   timeout: 2000,
+ *   strict: true,
+ *   resetOnComplete: false
+ * });
+ * ```
+ */
+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 [state, setState] = useState({
+        currentIndex: 0,
+        isActive: false,
+        matchedKeys: [],
+        timeoutId: null,
+    });
+    const sequenceRef = useRef([]);
+    const callbackRef = useRef(callback);
+    const timeoutRef = useRef(null);
+    // Update callback ref when callback changes
+    useEffect(() => {
+        callbackRef.current = callback;
+    }, [callback]);
+    // Parse and normalize sequence
+    useEffect(() => {
+        sequenceRef.current = sequence.map((keys) => {
+            if (Array.isArray(keys)) {
+                return keys.map((key) => key.toLowerCase().trim());
+            }
+            else if (typeof keys === 'string' && keys.includes('+')) {
+                return parseHotkey(keys);
+            }
+            else {
+                return [keys.toString().toLowerCase().trim()];
+            }
+        });
+    }, [sequence]);
+    const resetSequence = useCallback(() => {
+        if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+            timeoutRef.current = null;
+        }
+        setState((prev) => ({
+            ...prev,
+            currentIndex: 0,
+            isActive: false,
+            matchedKeys: [],
+            timeoutId: null,
+        }));
+    }, []);
+    const startTimeout = useCallback(() => {
+        if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+        }
+        timeoutRef.current = window.setTimeout(() => {
+            resetSequence();
+        }, timeout);
+        setState((prev) => ({
+            ...prev,
+            timeoutId: timeoutRef.current,
+        }));
+    }, [timeout, resetSequence]);
+    const handleKeyEvent = useCallback((event) => {
+        if (!enabled || sequenceRef.current.length === 0)
+            return;
+        const keyInfo = createKeyInfo(event);
+        const keyEvent = {
+            key: event.key,
+            code: event.code,
+            ctrlKey: event.ctrlKey,
+            metaKey: event.metaKey,
+            altKey: event.altKey,
+            shiftKey: event.shiftKey,
+        };
+        setState((prevState) => {
+            const { currentIndex } = prevState;
+            const expectedKeys = sequenceRef.current[currentIndex];
+            if (!expectedKeys) {
+                return prevState;
+            }
+            // Check if current key matches the expected key in sequence
+            const isMatch = matchesHotkey(keyEvent, expectedKeys);
+            if (isMatch) {
+                const newIndex = currentIndex + 1;
+                const newMatchedKeys = [
+                    ...prevState.matchedKeys,
+                    keyInfo.combination,
+                ];
+                // Prevent default and stop propagation if configured
+                if (preventDefault) {
+                    event.preventDefault();
+                }
+                if (stopPropagation) {
+                    event.stopPropagation();
+                }
+                // Check if sequence is complete
+                if (newIndex >= sequenceRef.current.length) {
+                    // Sequence completed!
+                    callbackRef.current(event, keyInfo);
+                    // Clear timeout
+                    if (timeoutRef.current) {
+                        clearTimeout(timeoutRef.current);
+                        timeoutRef.current = null;
+                    }
+                    // Reset or keep sequence based on options
+                    if (resetOnComplete) {
+                        return {
+                            currentIndex: 0,
+                            isActive: false,
+                            matchedKeys: [],
+                            timeoutId: null,
+                        };
+                    }
+                    else {
+                        return {
+                            currentIndex: newIndex,
+                            isActive: true,
+                            matchedKeys: newMatchedKeys,
+                            timeoutId: null,
+                        };
+                    }
+                }
+                else {
+                    // Continue sequence
+                    startTimeout();
+                    return {
+                        currentIndex: newIndex,
+                        isActive: true,
+                        matchedKeys: newMatchedKeys,
+                        timeoutId: timeoutRef.current,
+                    };
+                }
+            }
+            else {
+                // Key doesn't match
+                if (strict || currentIndex === 0) {
+                    // Reset sequence in strict mode or if no progress made
+                    if (timeoutRef.current) {
+                        clearTimeout(timeoutRef.current);
+                        timeoutRef.current = null;
+                    }
+                    return {
+                        currentIndex: 0,
+                        isActive: false,
+                        matchedKeys: [],
+                        timeoutId: null,
+                    };
+                }
+                else {
+                    // In non-strict mode, just continue without resetting
+                    return prevState;
+                }
+            }
+        });
+    }, [
+        enabled,
+        preventDefault,
+        stopPropagation,
+        startTimeout,
+        strict,
+        resetOnComplete,
+    ]);
+    useEffect(() => {
+        if (!target || !enabled)
+            return;
+        const element = target;
+        element.addEventListener(eventType, handleKeyEvent);
+        return () => {
+            element.removeEventListener(eventType, handleKeyEvent);
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+            }
+        };
+    }, [target, enabled, eventType, handleKeyEvent]);
+    // Cleanup timeout on unmount
+    useEffect(() => {
+        return () => {
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+            }
+        };
+    }, []);
+    return state;
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { useHotkey, useHotkeys, type UseHotkeyOptions, } from './hooks/useHotkey';
+export { useKeySequence, type UseKeySequenceOptions, type KeySequenceState, } from './hooks/useKeySequence';
+export type { ModifierKey, SpecialKey, ArrowKey, LetterKey, NumberKey, FunctionKey, SymbolKey, SupportedKey, HotkeyString, HotkeyInput, HotkeysRecord, KeyInfo, HotkeyCallback, } from './types/keys';
+export { normalizeKey, getPlatformModifier, parseHotkey, matchesHotkey, keysToHotkey, createKeyInfo, type KeyEvent, } from './utils/keyUtils';
+export { default } from './hooks/useHotkey';

package/dist/index.js

@@ -0,0 +1,7 @@
+// Main exports
+export { useHotkey, useHotkeys, } from './hooks/useHotkey';
+export { useKeySequence, } from './hooks/useKeySequence';
+// Utility exports for advanced usage
+export { normalizeKey, getPlatformModifier, parseHotkey, matchesHotkey, keysToHotkey, createKeyInfo, } from './utils/keyUtils';
+// Re-export default
+export { default } from './hooks/useHotkey';

package/dist/types/keys.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Type definitions for supported keyboard keys
+ */
+export type ModifierKey = 'ctrl' | 'meta' | 'alt' | 'shift' | 'cmd' | 'command' | 'control';
+export type SpecialKey = 'enter' | 'return' | 'escape' | 'esc' | 'space' | 'spacebar' | 'tab' | 'backspace' | 'delete' | 'del' | 'insert' | 'home' | 'end' | 'pageup' | 'pagedown';
+export type ArrowKey = 'arrowup' | 'arrowdown' | 'arrowleft' | 'arrowright' | 'up' | 'down' | 'left' | 'right';
+export type LetterKey = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
+export type NumberKey = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+export type FunctionKey = 'f1' | 'f2' | 'f3' | 'f4' | 'f5' | 'f6' | 'f7' | 'f8' | 'f9' | 'f10' | 'f11' | 'f12';
+export type SymbolKey = '`' | '~' | '!' | '@' | '#' | '$' | '%' | '^' | '&' | '*' | '(' | ')' | '-' | '_' | '=' | '+' | '[' | '{' | ']' | '}' | '\\' | '|' | ';' | ':' | "'" | '"' | ',' | '<' | '.' | '>' | '/' | '?';
+export type SupportedKey = ModifierKey | SpecialKey | ArrowKey | LetterKey | NumberKey | FunctionKey | SymbolKey;
+export interface KeyInfo {
+    key: string;
+    code: string;
+    normalizedKey: string;
+    modifiers: {
+        ctrl: boolean;
+        meta: boolean;
+        alt: boolean;
+        shift: boolean;
+    };
+    combination: string;
+}
+export type HotkeyCallback = (event: KeyboardEvent, keyInfo: KeyInfo) => void;
+export type HotkeyString = `${string}+${string}` | SupportedKey | '';
+export type HotkeyInput = SupportedKey | SupportedKey[] | string | string[] | '';
+export type HotkeysRecord = Record<HotkeyString, HotkeyCallback> | Record<string, HotkeyCallback>;

package/dist/types/keys.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for supported keyboard keys
+ */
+export {};

package/dist/utils/keyUtils.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Utility functions for normalizing keyboard events across different platforms and languages
+ */
+export interface KeyEvent {
+    key: string;
+    code: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    altKey: boolean;
+    shiftKey: boolean;
+}
+/**
+ * Normalize key names to handle cross-platform differences
+ */
+export declare const normalizeKey: (key: string) => string;
+/**
+ * Get the platform-specific modifier key (Cmd on Mac, Ctrl on others)
+ */
+export declare const getPlatformModifier: () => string;
+/**
+ * Parse a hotkey string into normalized components
+ * Examples: "ctrl+c", "cmd+shift+z", "alt+f4"
+ */
+export declare const parseHotkey: (hotkey: string) => string[];
+/**
+ * Check if the current key event matches the target hotkey combination
+ */
+export declare const matchesHotkey: (event: KeyEvent, targetKeys: string[]) => boolean;
+/**
+ * Convert array of keys to a normalized hotkey string
+ */
+export declare const keysToHotkey: (keys: string[]) => string;
+/**
+ * Create KeyInfo object from a keyboard event
+ */
+export declare const createKeyInfo: (event: KeyboardEvent) => {
+    key: string;
+    code: string;
+    normalizedKey: string;
+    modifiers: {
+        ctrl: boolean;
+        meta: boolean;
+        alt: boolean;
+        shift: boolean;
+    };
+    combination: string;
+};

package/dist/utils/keyUtils.js

@@ -0,0 +1,157 @@
+/**
+ * Utility functions for normalizing keyboard events across different platforms and languages
+ */
+/**
+ * Normalize key names to handle cross-platform differences
+ */
+export const normalizeKey = (key) => {
+    const keyMap = {
+        // Handle different representations of common keys
+        Control: 'ctrl',
+        Meta: 'meta',
+        Alt: 'alt',
+        Shift: 'shift',
+        Enter: 'enter',
+        Return: 'enter',
+        Escape: 'escape',
+        Esc: 'escape',
+        Space: 'space',
+        ' ': 'space',
+        Spacebar: 'space',
+        Tab: 'tab',
+        Backspace: 'backspace',
+        Delete: 'delete',
+        Del: 'delete',
+        Insert: 'insert',
+        Home: 'home',
+        End: 'end',
+        PageUp: 'pageup',
+        PageDown: 'pagedown',
+        ArrowUp: 'arrowup',
+        ArrowDown: 'arrowdown',
+        ArrowLeft: 'arrowleft',
+        ArrowRight: 'arrowright',
+        Up: 'arrowup',
+        Down: 'arrowdown',
+        Left: 'arrowleft',
+        Right: 'arrowright',
+    };
+    // Convert to lowercase for consistent comparison
+    const normalizedKey = key.toLowerCase();
+    // Return mapped key or original normalized key
+    return keyMap[key] || normalizedKey;
+};
+/**
+ * Get the platform-specific modifier key (Cmd on Mac, Ctrl on others)
+ */
+export const getPlatformModifier = () => {
+    const isMac = typeof navigator !== 'undefined' &&
+        /Mac|iPod|iPhone|iPad/.test(navigator.platform);
+    return isMac ? 'meta' : 'ctrl';
+};
+/**
+ * Parse a hotkey string into normalized components
+ * Examples: "ctrl+c", "cmd+shift+z", "alt+f4"
+ */
+export const parseHotkey = (hotkey) => {
+    return hotkey
+        .toLowerCase()
+        .split('+')
+        .map((key) => key.trim())
+        .map((key) => {
+        // Handle platform-specific aliases
+        if (key === 'cmd')
+            return 'meta';
+        if (key === 'command')
+            return 'meta';
+        if (key === 'control')
+            return 'ctrl';
+        return normalizeKey(key);
+    });
+};
+/**
+ * Check if the current key event matches the target hotkey combination
+ */
+export const matchesHotkey = (event, targetKeys) => {
+    const normalizedEventKey = normalizeKey(event.key);
+    const normalizedTargetKeys = targetKeys.map((key) => normalizeKey(key));
+    // Check if all modifier keys match
+    const hasCtrl = event.ctrlKey;
+    const hasMeta = event.metaKey;
+    const hasAlt = event.altKey;
+    const hasShift = event.shiftKey;
+    const expectedCtrl = normalizedTargetKeys.includes('ctrl');
+    const expectedMeta = normalizedTargetKeys.includes('meta');
+    const expectedAlt = normalizedTargetKeys.includes('alt');
+    const expectedShift = normalizedTargetKeys.includes('shift');
+    // Modifier keys must match exactly
+    if (hasCtrl !== expectedCtrl ||
+        hasMeta !== expectedMeta ||
+        hasAlt !== expectedAlt ||
+        hasShift !== expectedShift) {
+        return false;
+    }
+    // Find the non-modifier key
+    const nonModifierKeys = normalizedTargetKeys.filter((key) => !['ctrl', 'meta', 'alt', 'shift'].includes(key));
+    // Should have exactly one non-modifier key
+    if (nonModifierKeys.length !== 1) {
+        return false;
+    }
+    // Check if the main key matches
+    return normalizedEventKey === nonModifierKeys[0];
+};
+/**
+ * Convert array of keys to a normalized hotkey string
+ */
+export const keysToHotkey = (keys) => {
+    const normalizedKeys = keys.map((key) => normalizeKey(key));
+    // Sort modifiers in a consistent order
+    const modifiers = [];
+    const nonModifiers = [];
+    for (const key of normalizedKeys) {
+        if (['ctrl', 'meta', 'alt', 'shift'].includes(key)) {
+            modifiers.push(key);
+        }
+        else {
+            nonModifiers.push(key);
+        }
+    }
+    // Sort modifiers in standard order
+    const sortedModifiers = modifiers.sort((a, b) => {
+        const order = ['ctrl', 'meta', 'alt', 'shift'];
+        return order.indexOf(a) - order.indexOf(b);
+    });
+    return [...sortedModifiers, ...nonModifiers].join('+');
+};
+/**
+ * Create KeyInfo object from a keyboard event
+ */
+export const createKeyInfo = (event) => {
+    const normalizedKey = normalizeKey(event.key);
+    const modifiers = {
+        ctrl: event.ctrlKey,
+        meta: event.metaKey,
+        alt: event.altKey,
+        shift: event.shiftKey,
+    };
+    // Build combination string
+    const modifierKeys = [];
+    if (modifiers.ctrl)
+        modifierKeys.push('ctrl');
+    if (modifiers.meta)
+        modifierKeys.push('meta');
+    if (modifiers.alt)
+        modifierKeys.push('alt');
+    if (modifiers.shift)
+        modifierKeys.push('shift');
+    const combination = modifierKeys.length > 0
+        ? `${modifierKeys.join('+')}+${normalizedKey}`
+        : normalizedKey;
+    return {
+        key: event.key,
+        code: event.code,
+        normalizedKey,
+        modifiers,
+        combination,
+    };
+};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "use-simple-keyboard",
+  "version": "0.0.1",
+  "description": "React hooks for handling keyboard inputs and hotkeys across different platforms",
+  "license": "MIT",
+  "author": "SkorpionG",
+  "homepage": "https://github.com/SkorpionG/use-simple-keyboard#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SkorpionG/use-simple-keyboard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SkorpionG/use-simple-keyboard/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --project tsconfig.typecheck.json",
+    "test": "jest --config jest.config.ts",
+    "test:watch": "jest --config jest.config.ts --watch",
+    "test:coverage": "jest --config jest.config.ts --coverage",
+    "lint": "eslint .",
+    "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"
+  },
+  "keywords": [
+    "react",
+    "hooks",
+    "keyboard",
+    "hotkeys",
+    "shortcuts",
+    "input"
+  ],
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.36.0",
+    "@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",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
+    "jiti": "^2.7.0",
+    "prettier": "^3.8.3",
+    "ts-jest": "^29.4.9",
+    "typescript": "^6.0.3"
+  }
+}