From 006fb5ae5bc3e54e47e49c7e6819a45691d16a4a Mon Sep 17 00:00:00 2001 From: Felipe Coury Date: Sat, 21 Feb 2026 17:06:42 -0300 Subject: [PATCH] docs(tui): document shifted-letter keybinding compatibility Clarify that shifted letter bindings are matched compatibly when terminals emit uppercase letters without an explicit SHIFT modifier. Update config guidance, the default keymap template, and the action matrix with examples for shift-i, shift-a, and shift-o mapping to I, A, and O. --- docs/config.md | 4 +++- docs/default-keymap.toml | 2 ++ docs/keymap-action-matrix.md | 3 +++ 3 files changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/config.md b/docs/config.md index dcef03396e..47be7f1ca2 100644 --- a/docs/config.md +++ b/docs/config.md @@ -95,7 +95,9 @@ Actions accept a single key or multiple keys: Some defaults intentionally include multiple variants for one logical shortcut because terminal modifier reporting can differ by platform/emulator. For example, `?` may arrive as plain `?` or `shift-?`, and control chords may -arrive with or without `SHIFT`. +arrive with or without `SHIFT`. Shifted letter bindings are also matched +compatibly when terminals report uppercase letters without explicit `SHIFT` +(for example, `shift-i` matching `I`). Aliases like `escape`, `pageup`, and `pgdn` are normalized. diff --git a/docs/default-keymap.toml b/docs/default-keymap.toml index c2453b2ec5..cf9a2b3a9f 100644 --- a/docs/default-keymap.toml +++ b/docs/default-keymap.toml @@ -73,6 +73,8 @@ yank = ["ctrl-y"] [tui.keymap.vim_normal] # Vim normal-mode actions for modal editing. +# Shifted letter bindings also match uppercase event forms reported without +# explicit SHIFT by some terminals. enter_insert = "i" append_after_cursor = "a" append_line_end = "shift-a" diff --git a/docs/keymap-action-matrix.md b/docs/keymap-action-matrix.md index dada5155e9..b399bf135e 100644 --- a/docs/keymap-action-matrix.md +++ b/docs/keymap-action-matrix.md @@ -24,6 +24,9 @@ For runtime behavior, safety invariants, and testing guidance, see - `composer.toggle_shortcuts`: `?` and `shift-?` - `approval.open_fullscreen`: `ctrl-a` and `ctrl-shift-a` - `onboarding.toggle_animation`: `ctrl-.` and `ctrl-shift-.` +- Shifted letter bindings are also matched compatibly across terminal variants + when reported as uppercase letters without explicit `SHIFT` (for example + `shift-i` matching `I`, `shift-a` matching `A`, and `shift-o` matching `O`). - Keep these paired defaults unless/until key-event normalization is made platform-consistent at a lower layer.