Keyboard shortcut system design
A composable, conflict-aware keyboard shortcut engine for desktop-class web applications. Supports scoped bindings, chord sequences, and dynamic rebinding without leaking listeners.
Core architecture
Central ShortcutRegistry singleton owns a Map<string, Binding[]>. Each binding stores the key combo, a priority integer, a scope tag, and a callback ref. A single keydown listener on document normalizes the event into a canonical chord string and walks the sorted binding list.
Conflict resolution
When multiple bindings match a chord, the registry picks the highest-priority binding whose scope is active. Scopes form a stack — pushing a modal scope temporarily hides lower-priority global shortcuts. If two bindings share the same priority and scope, the most recently registered wins and a console warning fires in development.
Chord sequences
Multi-key sequences like Ctrl+K Ctrl+B are supported via a timeout window. After the first chord, the registry enters a pending state. If the next chord arrives within 800ms and completes a known sequence, the callback fires. Otherwise the partial sequence is discarded silently.
Cleanup contract
Every register() call returns an unsubscribe function. Components call it in their effect teardown. The registry also exposes a flush(scope) method for bulk removal when a route unmounts. No listener leaks survive navigation.