Proposal: .sheetsrc config file for custom key mappings

[NSEvent]

Problem

Sheets has vim-style modal editing but no way to customize key bindings. Vim users expect to carry over muscle memory from their .vimrc — for example, many people remap <C-c><C-c> to quit, or remap navigation keys for their keyboard layout.

This is especially relevant now that #22 proposes removing Ctrl-C as a quit key. Without a config file, there's no way for users to bind their own quit sequence.

Proposal: ~/.sheetsrc

A minimal RC file that supports key mapping, using familiar vim syntax.

Format

" Comments start with " or #
# This is also a comment

" Map a key sequence in normal mode
nmap <C-c><C-c> :q

" Map in insert mode
imap <C-c> <Esc>

" Map in select mode
smap <C-c> <Esc>

" Map in all modes
map <C-c> <Esc>

Supported mapping commands

Command	Scope
nmap / nnoremap	Normal mode
imap / inoremap	Insert mode
smap	Select mode
map / noremap	All modes

Key notation

Uses vim-style <...> notation:

Notation	Key
<C-x>	Ctrl+x
<Esc>	Escape
<CR> / <Enter>	Enter
<Tab>	Tab
<Space>	Space
<BS>	Backspace
a, q, etc.	Literal characters

Multiple keys can be chained: <C-c><C-c> is a two-key sequence.

Supported actions

Action	Effect
:q	Quit
:w	Write/save
:wq	Write and quit
<Esc>	Exit current mode → normal
<Nop>	Do nothing (disable a key)

Multi-key sequence handling

When the user presses a key that is a prefix of a mapped sequence:

1. Buffer the key and wait for the next keypress
2. If the next key completes a mapping → execute the action
3. If the next key doesn't match any mapping → flush the buffer and process both keys normally
4. If no key comes within 1 second → flush the buffer (process the key normally)

This matches vim's timeoutlen behavior.

Scope / non-goals

This proposal intentionally keeps the scope small:

• No set commands (e.g., set cellwidth=20) — that can come later
• No recursive mapping — nmap and nnoremap behave identically for now
• No <leader> key — users can just spell out their sequences
• No runtime :map command — config is read once at startup

Implementation sketch

• New file config.go: RC file parser, key notation normalizer, sequence matcher
• types.go: Add config, pendingSeq, pendingSeqMsgs fields to model
• model.go: Check bindings before normal key dispatch in Update(); extract key dispatch into processKeyMsg() so buffered keys can be replayed on flush

I have a working implementation of this and am happy to open a PR if the design looks good. Feedback on the format, scope, or naming is welcome.

[maaslalani]

We definitely need to have something like this! Personally, as a Helix user I wonder if we can make the config similar to that? I'm open to opinions.

[verysleepylemon]

This is a well-scoped proposal. Adding to the Helix-style TOML angle @maaslalani raised:

Helix (~/.config/helix/config.toml) uses a [keys.normal] / [keys.insert] table structure. Here's what that would look like for sheets:

# ~/.config/sheets/config.toml   (XDG-friendly path)

[keys.normal]
"C-c" = "quit"          # single key: Ctrl-C → quit
"Z" = { "Z" = "write_quit" }   # nested: ZZ → :wq

[keys.insert]
"C-c" = "normal_mode"

[keys.normal."g"]       # prefix table: all g-prefixed sequences
"g" = "goto_top"
"B9" = "goto_cell"

Advantages over vim-style map syntax:

• Pure TOML: no custom parser needed — standard encoding/toml handles it (github.com/BurntSushi/toml or github.com/pelletier/go-toml/v2 are zero-CGO and small)
• Nested tables naturally express multi-key sequences (ZZ, gB9, <C-c><C-c>)
• set options can live in [options] alongside bindings later without format changes
• Editor-native: Helix users expect this format; vim users adapt easily

Proposed action table (string values for the binding RHS):

[actions]
# name          = description
"quit"          = ":q"
"write"         = ":w"
"write_quit"    = ":wq"
"normal_mode"   = "<Esc>"
"nop"           = "<Nop>"

Implementation path if going TOML:

• internal/sheets/config.go — LoadConfig(path string) (Config, error), DefaultConfig() Config
• Config.Bindings is a nested map[string]map[string]string matching the TOML table structure
• Key dispatch in model.go Update(): before normal handling, check m.config.Bindings[currentMode][keyString], resolve action, emit the corresponding tea.Msg

Happy to sketch either the TOML variant or support both formats (:sheetsrc for vim users, TOML for Helix / everyone else) — the parser decision is the main fork point.

[verysleepylemon]

This is a well-scoped proposal. Adding to the Helix-style TOML angle @maaslalani raised:

Helix (~/.config/helix/config.toml) uses a [keys.normal] / [keys.insert] table structure. Here's what that would look like for sheets:

# ~/.config/sheets/config.toml   (XDG-friendly path)

[keys.normal]
"C-c" = "quit"          # single key: Ctrl-C → quit
"Z" = { "Z" = "write_quit" }   # nested: ZZ → :wq

[keys.insert]
"C-c" = "normal_mode"

[keys.normal."g"]       # prefix table: all g-prefixed sequences
"g" = "goto_top"
"B9" = "goto_cell"

Advantages over vim-style map syntax:

• Pure TOML: no custom parser needed — standard encoding/toml handles it (github.com/BurntSushi/toml or github.com/pelletier/go-toml/v2 are zero-CGO and small)
• Nested tables naturally express multi-key sequences (ZZ, gB9, <C-c><C-c>)
• set options can live in [options] alongside bindings later without format changes
• Editor-native: Helix users expect this format; vim users adapt easily

Proposed action table (string values for the binding RHS):

[actions]
# name          = description
"quit"          = ":q"
"write"         = ":w"
"write_quit"    = ":wq"
"normal_mode"   = "<Esc>"
"nop"           = "<Nop>"

Implementation path if going TOML:

• internal/sheets/config.go — LoadConfig(path string) (Config, error), DefaultConfig() Config
• Config.Bindings is a nested map[string]map[string]string matching the TOML table structure
• Key dispatch in model.go Update(): before normal handling, check m.config.Bindings[currentMode][keyString], resolve action, emit the corresponding tea.Msg

Happy to sketch either the TOML variant or support both formats (:sheetsrc for vim users, TOML for Helix / everyone else) — the parser decision is the main fork point.

[adriangalilea]

Hey @maaslalani @verysleepylemon feel free to take a look at my PR #26

[maaslalani]

Closed in #67