gentleeduck/duck-ui / skills/duck-vim
duck-vim
VerifiedUse when working with @gentleduck/vim - the keyboard command engine. Covers hotkey parsing, key sequence matching, chord bindings, platform-aware mod resolution, key recording, and the React hooks (useKeyBind, useKeySequence, useKeyCommands, useKeyRecorder). Not for vim-the-editor - this is a keyboard shortcut library.
@gentleduck/vim
Expert scope: packages/duck-vim/. Parses hotkey strings, matches keyboard events, supports sequences, records key presses, and provides React hooks. Import by subpath: @gentleduck/vim/{module}.
parser - @gentleduck/vim/parser
Exports: parseKeyBind(binding, platform?) => ParsedKeyBind, normalizeKeyBind(binding, platform?) => string, validateKeyBind(binding) => ValidationResult, keyboardEventToDescriptor(e) => string | null, KEY_ALIASES, MODIFIER_KEYS, types ParsedKeyBind, ValidationResult.
parseKeyBind('mod+shift+k', 'mac')
// => { key: 'k', ctrl: false, shift: true, alt: false, meta: true, modifiers: ['meta', 'shift'] }
normalizeKeyBind('Shift+Mod+s', 'mac') // => 'meta+shift+s'
validateKeyBind('ctrl+ctrl+k') // => { valid: false, errors: ['Duplicate modifier: ...'], warnings: [] }
matcher - @gentleduck/vim/matcher
Exports: createKeyBindHandler(config) => (e) => void, createMultiKeyBindHandler(configs[]) => (e) => void, matchesKeyboardEvent(parsed, event, options?) => boolean, isInputElement(el) => boolean, types KeyBindHandlerConfig, MatchOptions, SingleKeyBindOptions.
const handler = createKeyBindHandler({
binding: 'Mod+S', handler: (e) => save(),
options: { preventDefault: true, ignoreInputs: true },
})
document.addEventListener('keydown', handler) // must attach manually
command - @gentleduck/vim/command
Exports: Registry, KeyHandler, types Command, KeyBindOptions, RegistrationHandle, RegistryEntry, RegistryClass.
Command has { name: string, description?: string, execute: (args?) => void | Promise<void> }.
KeyBindOptions fields: enabled?, preventDefault?, stopPropagation?, ignoreInputs?, eventType? ('keydown'|'keyup'), requireReset?, conflictBehavior? ('warn'|'error'|'replace'|'allow', default 'warn').
const registry = new Registry(/* debug */ false)
const handle = registry.register('ctrl+k', { name: 'Palette', execute: () => openPalette() },
{ preventDefault: true, conflictBehavior: 'error' })
handle.unregister() // remove binding
handle.setEnabled(false) // disable without removing
handle.isEnabled() // => boolean
handle.resetFired() // reset requireReset flag
registry.getAllCommands() // => Map<string, Command>
registry.hasCommand('ctrl+k') // => boolean
const kh = new KeyHandler(registry, 600, /* defaultOptions */ {})
kh.attach(document) // default target is document
kh.detach(document)
platform - @gentleduck/vim/platform
Exports: detectPlatform() => Platform, isMac(platform?) => boolean, resolveMod(platform?) => 'meta' | 'ctrl', type Platform ('mac' | 'windows' | 'linux').
SSR safe: detectPlatform() falls back to 'linux' when navigator is unavailable.
format - @gentleduck/vim/format
Exports: formatForDisplay(binding, options?) => string, formatWithLabels(binding, options?) => string, SYMBOL_MAP, LABEL_MAP, type FormatOptions { platform?, separator? }.
formatForDisplay('mod+shift+k', { platform: 'mac' }) // => 'Cmd+Shift+K'
formatWithLabels('mod+enter', { platform: 'mac' }) // => 'Cmd + Enter' (space-padded separator)
sequence - @gentleduck/vim/sequence
Exports: createSequenceMatcher(steps[], handler, options?) => { feed, reset, getState }, SequenceManager, types SequenceOptions, SequenceHandle, SequenceState, SequenceRegistration, SequenceStep.
const seq = createSequenceMatcher(['g', 'g'], () => scrollToTop(), { timeout: 1000 })
seq.feed(event) // => true when complete
const mgr = new SequenceManager()
const handle = mgr.register({ steps: [{ binding: 'g' }, { binding: 'd' }], handler: goToDefinition })
mgr.handleKeyEvent(event) // feed events; returns true if any matched
handle.unregister()
mgr.destroy()
recorder - @gentleduck/vim/recorder
Exports: KeyRecorder, KeyStateTracker, types KeyRecorderOptions, KeyRecorderState, KeyStateSnapshot.
const recorder = new KeyRecorder({ onRecord: (b) => console.log(b), onStart, onStop })
recorder.start(document) // Ctrl+Shift+K => onRecord('ctrl+shift+k')
recorder.getState() // => { activeKeys: string[], recorded: string | null, isRecording }
recorder.stop(); recorder.reset(); recorder.destroy()
const tracker = new KeyStateTracker()
tracker.attach(document)
tracker.isKeyPressed('shift') // => boolean
tracker.getSnapshot() // => { pressed: ReadonlySet<string>, hasModifier: boolean }
tracker.detach(); tracker.destroy()
react - @gentleduck/vim/react
Exports: useKeyBind, useKeySequence, useKeyCommands, useKeyRecorder, KeyProvider, KeyContext, types KeyContextValue, KeyBindHookOptions, SequenceHookOptions, KeyRecorderReturn.
useKeyBind('mod+k', () => openMenu(), { preventDefault: true, targetRef })
useKeySequence(['g', 'g'], () => scrollToTop(), { timeout: 1000 }) // string[], NOT space-separated
useKeyCommands({ 'ctrl+k': { name: 'Search', execute: openSearch } }, optionalKeyBindOptions) // requires KeyProvider
const { state, start, stop, reset } = useKeyRecorder()
KeyProvider props: debug?, timeoutMs? (default 600), defaultOptions?: Partial<KeyBindOptions>, children.
Recipes
Command palette: <KeyProvider><App /></KeyProvider>, then useKeyBind('mod+k', () => setPaletteOpen(true), { preventDefault: true, ignoreInputs: true }).
Customizable keybinds: Use useKeyRecorder() -- render state.recorded, call start(el) on focus, stop() on blur, persist result, pass to useKeyBind dynamically.
Conflict detection: conflictBehavior: 'error' in dev to catch collisions; 'replace' for user overrides.
Pitfalls
- Binding silent -- check
isInputElement,options.enabled, and thatKeyProviderwraps the tree - Sequence timeout -- default 600ms; increase with
{ timeout: ms } - Always use
mod+notctrl+/meta+; always passstring[]not space-separated to sequences createKeyBindHandlertakes{ binding, handler, options }-- not positional argsuseKeyCommandsrequiresKeyProvider-- warns and no-ops without it- For many bindings prefer
useKeyCommandsover repeateduseKeyBind
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |