⌨️ Keycraft

Ultra-performant, zero-dependency keyboard shortcut management for modern web applications.

Keycraft is a headless, framework-agnostic keyboard shortcut engine built for production apps that demand precision, performance, and accessibility. It ships as two packages — a vanilla core and a React integration — designed to handle everything from simple hotkeys to complex Vim-style leader-key sequences.

---

Packages

Package	Description	Size
@keycraft/core	Framework-agnostic shortcut engine. Zero runtime dependencies.	~2.5 KB gzip
@keycraft/react	React hooks & components wrapping @keycraft/core.	~1 KB gzip

---

✨ Key Highlights

• 🪶 Zero Dependencies — @keycraft/core has no runtime dependencies. None.
• 🧱 LIFO Scope Stacking & Isolation — Automatic hotkey isolation for modals & drawers ({ isolate: true }). Push a scope, and parent shortcuts pause automatically.
• 🎹 Leader-Key Sequences — Vim / VS Code–style chords like g → i with configurable timeouts.
• 🌍 International Keyboard Support — Layout-aware normalization via KeyboardEvent.code for QWERTY, AZERTY, QWERTZ, and Dvorak users.
• 🔒 SSR Safe — Every window, document, and navigator access is guarded. Works in Node.js, Bun, Deno, and server-rendered frameworks.
• ♿ Accessible by Default — Auto-generated <HotkeyHUD /> cheat-sheet overlay with ARIA roles, focus trapping, and keyboard navigation.
• 🔁 Dynamic Remapping — Let users rebind shortcuts at runtime with optional localStorage persistence.
• 🛡️ Ghost-Key Flushing — Automatically resets stuck modifier state on window.blur and visibilitychange.
• 📥 Input-Aware — Single-key shortcuts are auto-suppressed inside <input>, <textarea>, and [contenteditable] unless explicitly enabled.

---

Quick Start

# Install core (framework-agnostic)
pnpm add @keycraft/core

# Install React integration
pnpm add @keycraft/react

Vanilla JS

import { ShortcutManager } from '@keycraft/core';

const manager = new ShortcutManager();

// Register a shortcut
const unsubscribe = manager.register('Mod+S', (event) => {
  event.preventDefault();
  saveDocument();
}, {
  description: 'Save document',
  category: 'File',
});

// Scope isolation for modals (isolate: true blocks all parent shortcuts)
manager.pushScope('settings-modal', { isolate: true });
// ... only 'settings-modal' shortcuts are active
manager.popScope('settings-modal');

// Cleanup
unsubscribe();
manager.destroy();

React

import { HotkeyProvider, useHotkey, useHotkeyScope, HotkeyHUD } from '@keycraft/react';

function App() {
  return (
    <HotkeyProvider>
      <Editor />
      <HotkeyHUD triggerKey="?" />
    </HotkeyProvider>
  );
}

function Editor() {
  useHotkey('Mod+S', (e) => {
    e.preventDefault();
    save();
  }, { description: 'Save', category: 'File', enableInInputs: true });

  return <textarea />;
}

function SettingsModal() {
  useHotkeyScope('settings', { isolate: true }); // Auto push/pop & strict scope isolation
  useHotkey('Escape', () => closeModal(), { scope: 'settings' });
  return <dialog open>...</dialog>;
}

---

Combo Syntax

Format	Example	Description
Single key	k	Fires on key press
Modifier combo	Ctrl+Shift+A	Requires all modifiers held
Platform-aware	Mod+S	⌘+S on Mac, Ctrl+S on Windows/Linux
Sequence / Leader	g>i	Press g then i within 750ms
Aliases	Esc, Space, Cmd	Normalized automatically

---

📋 Changelog

v0.1.5

• Strict Scope Isolation: Added { isolate: true } option to pushScope and useHotkeyScope to completely block parent scope shortcuts while modals or dialogs are active.

v0.1.4

• Vim Leader Key & Layout Normalization: Enhanced multi-key chord sequence matching (g>i) with layout-aware key code normalization across QWERTY, AZERTY, and Dvorak.

---

Development

# Clone and install
git clone https://github.com/keycraft/keycraft.git
cd keycraft
pnpm install

# Build all packages
pnpm run build

# Run tests
pnpm run test

# Type checking
pnpm run typecheck

---

License

MIT © Keycraft Contributors