feat: add Ctrl+HJKL navigation for keyboards without arrow keys (#391)

datlechin · web-flow · commit b1311db6730f · 2026-03-20T17:56:30.000+07:00
* feat: add Ctrl+HJKL navigation for keyboards without arrow keys (#388) * fix: keep selection on group collapse so Ctrl+L can re-expand
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Reusable SSH tunnel profiles: save SSH configurations once and select them across multiple connections
+- Ctrl+HJKL navigation as arrow key alternative for keyboards without dedicated arrow keys
 
 ### Fixed
 
diff --git a/TablePro/Views/Connection/OnboardingContentView.swift b/TablePro/Views/Connection/OnboardingContentView.swift
@@ -64,6 +64,16 @@ struct OnboardingContentView: View {
             goToPage(currentPage + 1)
             return .handled
         }
+        .onKeyPress(characters: .init(charactersIn: "h"), phases: .down) { keyPress in
+            guard keyPress.modifiers.contains(.control), currentPage > 0 else { return .ignored }
+            goToPage(currentPage - 1)
+            return .handled
+        }
+        .onKeyPress(characters: .init(charactersIn: "l"), phases: .down) { keyPress in
+            guard keyPress.modifiers.contains(.control), currentPage < 2 else { return .ignored }
+            goToPage(currentPage + 1)
+            return .handled
+        }
     }
 
     private func goToPage(_ page: Int) {
diff --git a/TablePro/Views/Connection/WelcomeWindowView.swift b/TablePro/Views/Connection/WelcomeWindowView.swift
@@ -72,6 +72,14 @@ struct WelcomeWindowView: View {
         filteredConnections.filter { $0.groupId == group.id }
     }
 
+    private var flatVisibleConnections: [DatabaseConnection] {
+        var result = ungroupedConnections
+        for group in activeGroups where !collapsedGroupIds.contains(group.id) {
+            result.append(contentsOf: connections(in: group))
+        }
+        return result
+    }
+
     var body: some View {
         ZStack {
             if showOnboarding {
@@ -318,6 +326,26 @@ struct WelcomeWindowView: View {
             }
             return .handled
         }
+        .onKeyPress(characters: .init(charactersIn: "j"), phases: .down) { keyPress in
+            guard keyPress.modifiers.contains(.control) else { return .ignored }
+            moveToNextConnection()
+            return .handled
+        }
+        .onKeyPress(characters: .init(charactersIn: "k"), phases: .down) { keyPress in
+            guard keyPress.modifiers.contains(.control) else { return .ignored }
+            moveToPreviousConnection()
+            return .handled
+        }
+        .onKeyPress(characters: .init(charactersIn: "h"), phases: .down) { keyPress in
+            guard keyPress.modifiers.contains(.control) else { return .ignored }
+            collapseSelectedGroup()
+            return .handled
+        }
+        .onKeyPress(characters: .init(charactersIn: "l"), phases: .down) { keyPress in
+            guard keyPress.modifiers.contains(.control) else { return .ignored }
+            expandSelectedGroup()
+            return .handled
+        }
     }
 
     private func connectionRow(for connection: DatabaseConnection) -> some View {
@@ -588,6 +616,60 @@ struct WelcomeWindowView: View {
         }
     }
 
+    private func moveToNextConnection() {
+        let visible = flatVisibleConnections
+        guard !visible.isEmpty else { return }
+        guard let currentId = selectedConnectionId,
+              let index = visible.firstIndex(where: { $0.id == currentId }) else {
+            selectedConnectionId = visible.first?.id
+            return
+        }
+        let next = min(index + 1, visible.count - 1)
+        selectedConnectionId = visible[next].id
+    }
+
+    private func moveToPreviousConnection() {
+        let visible = flatVisibleConnections
+        guard !visible.isEmpty else { return }
+        guard let currentId = selectedConnectionId,
+              let index = visible.firstIndex(where: { $0.id == currentId }) else {
+            selectedConnectionId = visible.last?.id
+            return
+        }
+        let prev = max(index - 1, 0)
+        selectedConnectionId = visible[prev].id
+    }
+
+    private func collapseSelectedGroup() {
+        guard let id = selectedConnectionId,
+              let connection = connections.first(where: { $0.id == id }),
+              let groupId = connection.groupId,
+              !collapsedGroupIds.contains(groupId) else { return }
+        withAnimation(.easeInOut(duration: 0.2)) {
+            collapsedGroupIds.insert(groupId)
+            // Keep selectedConnectionId so Ctrl+L can derive the groupId to expand.
+            // The List won't show a highlight for the hidden row.
+            UserDefaults.standard.set(
+                Array(collapsedGroupIds.map(\.uuidString)),
+                forKey: "com.TablePro.collapsedGroupIds"
+            )
+        }
+    }
+
+    private func expandSelectedGroup() {
+        guard let id = selectedConnectionId,
+              let connection = connections.first(where: { $0.id == id }),
+              let groupId = connection.groupId,
+              collapsedGroupIds.contains(groupId) else { return }
+        withAnimation(.easeInOut(duration: 0.2)) {
+            collapsedGroupIds.remove(groupId)
+            UserDefaults.standard.set(
+                Array(collapsedGroupIds.map(\.uuidString)),
+                forKey: "com.TablePro.collapsedGroupIds"
+            )
+        }
+    }
+
     private func moveUngroupedConnections(from source: IndexSet, to destination: Int) {
         let ungroupedIndices = connections.indices.filter { connections[$0].groupId == nil }
 
diff --git a/TablePro/Views/DatabaseSwitcher/DatabaseSwitcherSheet.swift b/TablePro/Views/DatabaseSwitcher/DatabaseSwitcherSheet.swift
@@ -130,6 +130,16 @@ struct DatabaseSwitcherSheet: View {
             moveSelection(up: false)
             return .handled
         }
+        .onKeyPress(characters: .init(charactersIn: "j"), phases: .down) { keyPress in
+            guard keyPress.modifiers.contains(.control) else { return .ignored }
+            moveSelection(up: false)
+            return .handled
+        }
+        .onKeyPress(characters: .init(charactersIn: "k"), phases: .down) { keyPress in
+            guard keyPress.modifiers.contains(.control) else { return .ignored }
+            moveSelection(up: true)
+            return .handled
+        }
     }
 
     // MARK: - Toolbar
diff --git a/TablePro/Views/QuickSwitcher/QuickSwitcherView.swift b/TablePro/Views/QuickSwitcher/QuickSwitcherView.swift
@@ -72,6 +72,16 @@ internal struct QuickSwitcherSheet: View {
             viewModel.moveDown()
             return .handled
         }
+        .onKeyPress(characters: .init(charactersIn: "j"), phases: .down) { keyPress in
+            guard keyPress.modifiers.contains(.control) else { return .ignored }
+            viewModel.moveDown()
+            return .handled
+        }
+        .onKeyPress(characters: .init(charactersIn: "k"), phases: .down) { keyPress in
+            guard keyPress.modifiers.contains(.control) else { return .ignored }
+            viewModel.moveUp()
+            return .handled
+        }
     }
 
     // MARK: - Search Toolbar
diff --git a/TablePro/Views/Results/KeyHandlingTableView.swift b/TablePro/Views/Results/KeyHandlingTableView.swift
@@ -199,7 +199,28 @@ final class KeyHandlingTableView: NSTableView {
 
         // Handle arrow keys (custom Shift+selection logic)
         let row = selectedRow
-        let isShiftHeld = event.modifierFlags.contains(.shift)
+        let modifiers = event.modifierFlags.intersection(.deviceIndependentFlagsMask)
+        let isShiftHeld = modifiers.contains(.shift)
+
+        // Ctrl+HJKL navigation (arrow key alternatives for keyboards without dedicated arrows)
+        if modifiers.contains(.control) {
+            switch key {
+            case .h:
+                handleLeftArrow(currentRow: row)
+                return
+            case .j:
+                handleDownArrow(currentRow: row, isShiftHeld: isShiftHeld)
+                return
+            case .k:
+                handleUpArrow(currentRow: row, isShiftHeld: isShiftHeld)
+                return
+            case .l:
+                handleRightArrow(currentRow: row)
+                return
+            default:
+                break
+            }
+        }
 
         switch key {
         case .upArrow:
diff --git a/TablePro/Views/Toolbar/ConnectionSwitcherPopover.swift b/TablePro/Views/Toolbar/ConnectionSwitcherPopover.swift
@@ -192,6 +192,16 @@ struct ConnectionSwitcherPopover: View {
             case KeyCode.escape.rawValue:
                 onDismiss?()
                 return nil
+            case KeyCode.j.rawValue where event.modifierFlags.intersection(.deviceIndependentFlagsMask).contains(.control):
+                if selectedIndex < items.count - 1 {
+                    selectedIndex += 1
+                }
+                return nil
+            case KeyCode.k.rawValue where event.modifierFlags.contains(.control):
+                if selectedIndex > 0 {
+                    selectedIndex -= 1
+                }
+                return nil
             default:
                 return event
             }
diff --git a/docs/features/keyboard-shortcuts.mdx b/docs/features/keyboard-shortcuts.mdx
@@ -177,6 +177,19 @@ TablePro is keyboard-driven. Most actions have shortcuts, and most menu shortcut
 | Explain with AI | `Cmd+L` | Send selected SQL (or current query) to AI for explanation |
 | Optimize with AI | `Cmd+Option+L` | Send selected SQL (or current query) to AI for optimization |
 
+## Alternative navigation (Ctrl+HJKL)
+
+For keyboards without dedicated arrow keys (e.g., HHKB), Ctrl+HJKL works as arrow key alternatives throughout the app. These work alongside arrow keys, not as replacements.
+
+| Shortcut | Action | Where |
+|----------|--------|-------|
+| `Ctrl+J` | Move down / Next item | Data grid, connection list, quick switcher, database switcher |
+| `Ctrl+K` | Move up / Previous item | Data grid, connection list, quick switcher, database switcher |
+| `Ctrl+H` | Move left / Collapse group | Data grid (column left), welcome panel (collapse group), onboarding (previous page) |
+| `Ctrl+L` | Move right / Expand group | Data grid (column right), welcome panel (expand group), onboarding (next page) |
+| `Ctrl+Shift+J` | Extend selection down | Data grid |
+| `Ctrl+Shift+K` | Extend selection up | Data grid |
+
 ## Vim Mode Keybindings
 
 When Vim mode is enabled (**Settings** > **Editor** > **Editing** > **Vim mode**), the SQL editor uses modal keybindings. A mode indicator badge appears in the toolbar.
diff --git a/docs/vi/features/keyboard-shortcuts.mdx b/docs/vi/features/keyboard-shortcuts.mdx
@@ -177,6 +177,19 @@ TablePro thiên về bàn phím. Hầu hết thao tác đều có phím tắt, v
 | Giải thích với AI | `Cmd+L` | Gửi SQL đã chọn (hoặc query hiện tại) cho AI giải thích |
 | Tối ưu với AI | `Cmd+Option+L` | Gửi SQL đã chọn (hoặc query hiện tại) cho AI tối ưu |
 
+## Điều hướng thay thế (Ctrl+HJKL)
+
+Dành cho bàn phím không có phím mũi tên riêng (ví dụ: HHKB), Ctrl+HJKL hoạt động như phím mũi tên thay thế trong toàn bộ ứng dụng. Các phím này hoạt động song song với phím mũi tên.
+
+| Phím tắt | Hành động | Nơi áp dụng |
+|----------|-----------|-------------|
+| `Ctrl+J` | Di chuyển xuống / Mục tiếp theo | Bảng dữ liệu, danh sách kết nối, quick switcher, database switcher |
+| `Ctrl+K` | Di chuyển lên / Mục trước | Bảng dữ liệu, danh sách kết nối, quick switcher, database switcher |
+| `Ctrl+H` | Di chuyển trái / Thu gọn nhóm | Bảng dữ liệu (cột trái), welcome panel (thu gọn nhóm), onboarding (trang trước) |
+| `Ctrl+L` | Di chuyển phải / Mở rộng nhóm | Bảng dữ liệu (cột phải), welcome panel (mở rộng nhóm), onboarding (trang sau) |
+| `Ctrl+Shift+J` | Mở rộng vùng chọn xuống | Bảng dữ liệu |
+| `Ctrl+Shift+K` | Mở rộng vùng chọn lên | Bảng dữ liệu |
+
 ## Phím Tắt Chế Độ Vim
 
 Khi bật chế độ Vim (**Settings** > **Editor** > **Editing** > **Vim mode**), SQL editor dùng phím tắt modal. Badge chỉ báo chế độ hiện trên thanh công cụ.
