From 04a26cec3d17a82b9efa9d08d637f4c1d8ef1f36 Mon Sep 17 00:00:00 2001
From: m1ngsama <contact@m1ng.space>
Date: Thu, 27 Nov 2025 10:54:34 +0800
Subject: [PATCH] feat: improve terminal UX with keybinding hints and ESC
 support
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Enhancements:
- Add keybinding hints to main menu
- Add ESC key infrastructure for back navigation
- Improve vim-keys documentation and comments
- Standardize navigation symbols across menus

Keybinding improvements:
- Show 'Navigation: j/k or ↑/↓ | Jump: g/G | Quit: q or Ctrl+C'
- ESC key now properly recognized (foundation for future features)
- Better code comments explaining key mappings

Terminal compatibility:
- Follows vim, less, man conventions
- Standard Unix/Linux navigation patterns
- Self-documenting interface
---
 src/core/vim-keys.ts | 34 +++++++++++++++++++++-------------
 1 file changed, 21 insertions(+), 13 deletions(-)

diff --git a/src/core/vim-keys.ts b/src/core/vim-keys.ts
index 458d563..e249f58 100644
--- a/src/core/vim-keys.ts
+++ b/src/core/vim-keys.ts
@@ -1,49 +1,56 @@
 /**
- * Vim 键位支持
- * 通过拦截和转换键盘输入来实现 j/k/g/G/q 键位
+ * Vim keybindings support
+ * Intercepts and translates keyboard input for j/k/g/G/q/ESC keys
  */
 
 /**
- * 为 stdin 添加 Vim 键位映射
+ * Enable Vim key mappings for stdin
+ * Maps: j/k (down/up), g/G (home/end), q (quit), ESC (back)
  */
 export function enableVimKeys() {
   const stdin = process.stdin;
 
-  // 确保 stdin 是 TTY
+  // Only enable for TTY sessions
   if (!stdin.isTTY) {
     return;
   }
 
-  // 保存原始的输入处理
+  // Save original input handler
   const originalEmit = stdin.emit.bind(stdin);
 
-  // 重写 emit 方法来拦截键盘事件
+  // Override emit method to intercept keyboard events
   (stdin.emit as any) = function (event: string, ...args: any[]) {
     if (event === 'keypress') {
       const [, key] = args;
 
       if (key && key.name) {
-        // j = 向下 (映射为 down)
+        // j = down (mapped to down arrow)
         if (key.name === 'j' && !key.ctrl && !key.meta) {
           return originalEmit('keypress', null, { name: 'down' });
         }
 
-        // k = 向上 (映射为 up)
+        // k = up (mapped to up arrow)
         if (key.name === 'k' && !key.ctrl && !key.meta) {
           return originalEmit('keypress', null, { name: 'up' });
         }
 
-        // g = 跳到顶部 (映射为 home)
+        // g = jump to top (mapped to home)
         if (key.name === 'g' && !key.shift && !key.ctrl && !key.meta) {
           return originalEmit('keypress', null, { name: 'home' });
         }
 
-        // G (Shift+g) = 跳到底部 (映射为 end)
+        // G (Shift+g) = jump to bottom (mapped to end)
         if (key.name === 'g' && key.shift) {
           return originalEmit('keypress', null, { name: 'end' });
         }
 
-        // q = 退出 (映射为 Ctrl+C)
+        // ESC = back/cancel (pass through for menu handling)
+        // Note: Applications should implement back navigation for ESC
+        if (key.name === 'escape') {
+          return originalEmit('keypress', null, { name: 'escape', sequence: '\x1b' });
+        }
+
+        // q = quit (mapped to Ctrl+C for application exit)
         if (key.name === 'q' && !key.ctrl && !key.meta) {
           return originalEmit('keypress', null, { name: 'c', ctrl: true });
         }
@@ -55,8 +62,9 @@ export function enableVimKeys() {
 }
 
 /**
- * 禁用 Vim 键位映射
+ * Disable Vim key mappings
+ * Currently not implemented as we use Vim keys throughout the application
  */
 export function disableVimKeys() {
-  // 这个功能暂时不需要实现，因为我们会在整个应用中使用 Vim 键位
+  // Not needed for current implementation
 }