Configurable keyboard mapping system design

Helge Sverre
Helge Sverre Hessevik Liseth • @helgesverre
 7mo ago
@docs/EDITOR_UI_REFERENCE.md use librarian and search agents to research how other editors do user editable keyboard mapping and consult oracle to add a section in the reference document about keymaps and lets sketch out a feature design document for adding configurable keyboard mapping system to our applicaiton in @docs/feature/KEYMAPPING.md
Ran tool todo_write
How do major text editors like VS Code, Neovim, Helix, Zed, and Sublime Text implement user-configurable keyboard mappings/keybindings? I want to understand the data structures, file formats (JSON, TOML, Lua), key representation, modifier handling, context/when clauses, command dispatch architecture, and conflict resolution strategies.
Ran tool sa__researcher
Explored 1 file

Excellent research! Now let me consult the oracle for guidance on designing our keymapping system.

Ran tool todo_write
Design a configurable keyboard mapping system for our Rust text editor. Based on research from VS Code, Neovim, Helix, and Zed, provide guidance on: 1. **Data Structures**: KeyEvent/Keystroke representation, modifier handling, keybinding storage (trie vs flat vector) 2. **Configuration Format**: TOML vs JSON, structure for default vs user bindings 3. **Context System**: How to handle context-aware bindings (editor mode, panel focus, etc.) 4. **Command Dispatch**: Architecture for keystroke → action resolution with sequence/chord support 5. **Conflict Resolution**: Precedence rules for overlapping bindings 6. **Platform Considerations**: macOS Cmd vs Windows/Linux Ctrl handling Our editor uses Elm Architecture (Message → Update → Command → Render) with: - AppModel, Document, EditorState, UiState in model - Msg, EditorMsg, DocumentMsg, UiMsg, AppMsg for messages - winit for window/event handling Provide concrete Rust code recommendations and highlight potential pitfalls.

I have comprehensive research and oracle guidance. Now I'll create both documents.

Ran tool todo_write
Explored 2 files, 1 search

Let me find the end of Chapter 12 to place the new chapter correctly:

Explored 1 file, 1 search

Now I'll add the new Keymapping chapter and update the TOC. First, let me update the TOC:

Edited EDITOR_UI_REFERENCE.md
+1

Now add the new chapter before Appendix A:

Edited EDITOR_UI_REFERENCE.md
+446
Ran tool todo_write

Now let me create the feature design document:

Created KEYMAPPING.md
+847
Ran tool todo_write

Done! I've completed both deliverables:

  1. Chapter 13: Keyboard Mapping and Command Dispatch added to EDITOR_UI_REFERENCE.md - covers core entities, key formats, storage strategies, context systems, dispatch architecture, conflict resolution, configuration formats, and platform considerations.

  2. docs/feature/KEYMAPPING.md - comprehensive feature design document with:

    • Module structure and data flow diagrams
    • Complete Rust code for all types (Keystroke, Keybinding, Command, Keymap, KeyContext)
    • TOML configuration format with examples
    • Default bindings implementation
    • Integration guide with your Elm architecture
    • 8-phase implementation plan (~15h total)
    • Command reference table

Key design decisions based on research from VS Code, Helix, Zed, and Neovim:

  • Flat vector storage (simpler than trie, sufficient for editor-scale)
  • TOML config (Rust-native, human-friendly)
  • mod modifier for platform-agnostic shortcuts
  • Simple &&/! condition syntax (extensible later)
  • SmallVec for sequences (most bindings are 1-2 keys)