fix: address PR #278 review feedback

datlechin · datlechin · commit fb647b7c3dd3 · 2026-03-12T00:26:06.000+07:00
- Add explicit access control to all Quick Switcher types
- Rewrite FuzzyMatcher to use unicodeScalars for proper supplementary-plane Unicode support
- Add load token to prevent stale loadItems completions from overwriting newer state
- Add stable sort tie-breaker (name) for deterministic ordering
- Remove unnecessary Task wrappers and redundant .keyboardShortcut on Open button
- Use DesignConstants for font/icon sizes in QuickSwitcherView
- Add Cmd+P to Essential Shortcuts and Cheat Sheet in docs
- Use sentence case for Quick Switcher heading in docs
diff --git a/TablePro/Core/Utilities/UI/FuzzyMatcher.swift b/TablePro/Core/Utilities/UI/FuzzyMatcher.swift
@@ -8,15 +8,15 @@
 import Foundation
 
 /// Namespace for fuzzy string matching operations
-enum FuzzyMatcher {
+internal enum FuzzyMatcher {
     /// Score a candidate string against a search query.
     /// Returns 0 for no match, higher values indicate better matches.
     /// Empty query returns 1 (everything matches).
     static func score(query: String, candidate: String) -> Int {
-        let queryNS = query as NSString
-        let candidateNS = candidate as NSString
-        let queryLen = queryNS.length
-        let candidateLen = candidateNS.length
+        let queryScalars = Array(query.unicodeScalars)
+        let candidateScalars = Array(candidate.unicodeScalars)
+        let queryLen = queryScalars.count
+        let candidateLen = candidateScalars.count
 
         if queryLen == 0 { return 1 }
         if candidateLen == 0 { return 0 }
@@ -27,24 +27,9 @@ enum FuzzyMatcher {
         var consecutiveBonus = 0
         var firstMatchPosition = -1
 
-        // Skip leading surrogate halves in query (emoji etc.)
-        while queryIndex < queryLen, UnicodeScalar(queryNS.character(at: queryIndex)) == nil {
-            queryIndex += 1
-        }
-
         while candidateIndex < candidateLen, queryIndex < queryLen {
-            guard let queryScalar = UnicodeScalar(queryNS.character(at: queryIndex)) else {
-                queryIndex += 1
-                continue
-            }
-            guard let candidateScalar = UnicodeScalar(candidateNS.character(at: candidateIndex)) else {
-                candidateIndex += 1
-                consecutiveBonus = 0
-                continue
-            }
-
-            let queryChar = Character(queryScalar)
-            let candidateChar = Character(candidateScalar)
+            let queryChar = Character(queryScalars[queryIndex])
+            let candidateChar = Character(candidateScalars[candidateIndex])
 
             guard queryChar.lowercased() == candidateChar.lowercased() else {
                 candidateIndex += 1
@@ -55,33 +40,26 @@ enum FuzzyMatcher {
             // Base match score
             var matchScore = 1
 
-            // Record first match position for position bonus
+            // Record first match position
             if firstMatchPosition < 0 {
                 firstMatchPosition = candidateIndex
             }
 
-            // Consecutive match bonus (grows quadratically with each consecutive hit)
+            // Consecutive match bonus
             consecutiveBonus += 1
             if consecutiveBonus > 1 {
                 matchScore += consecutiveBonus * 4
             }
 
-            // Word boundary bonus: after space, underscore, or camelCase transition
+            // Word boundary bonus
             if candidateIndex == 0 {
                 matchScore += 10
             } else {
-                guard let prevScalar = UnicodeScalar(candidateNS.character(at: candidateIndex - 1)) else {
-                    score += matchScore
-                    queryIndex += 1
-                    candidateIndex += 1
-                    continue
-                }
-                let prevChar = Character(prevScalar)
+                let prevChar = Character(candidateScalars[candidateIndex - 1])
                 if prevChar == " " || prevChar == "_" || prevChar == "." || prevChar == "-" {
                     matchScore += 8
                     consecutiveBonus = 1
                 } else if prevChar.isLowercase && candidateChar.isUppercase {
-                    // camelCase boundary
                     matchScore += 6
                     consecutiveBonus = 1
                 }
@@ -97,21 +75,16 @@ enum FuzzyMatcher {
             candidateIndex += 1
         }
 
-        // Skip trailing surrogate halves in query
-        while queryIndex < queryLen, UnicodeScalar(queryNS.character(at: queryIndex)) == nil {
-            queryIndex += 1
-        }
-
-        // All query characters must be matched, and at least one real match must exist
-        guard queryIndex == queryLen, score > 0 else { return 0 }
+        // All query characters must be matched
+        guard queryIndex == queryLen else { return 0 }
 
-        // Position bonus: earlier matches score higher
+        // Position bonus
         if firstMatchPosition >= 0 {
             let positionBonus = max(0, 20 - firstMatchPosition * 2)
             score += positionBonus
         }
 
-        // Length similarity bonus: prefer shorter candidates (closer to query length)
+        // Length similarity bonus
         let lengthRatio = Double(queryLen) / Double(candidateLen)
         score += Int(lengthRatio * 10)
 
diff --git a/TablePro/Models/UI/QuickSwitcherItem.swift b/TablePro/Models/UI/QuickSwitcherItem.swift
@@ -8,7 +8,7 @@
 import Foundation
 
 /// The type of database object represented by a quick switcher item
-enum QuickSwitcherItemKind: Hashable, Sendable {
+internal enum QuickSwitcherItemKind: Hashable, Sendable {
     case table
     case view
     case systemTable
@@ -18,7 +18,7 @@ enum QuickSwitcherItemKind: Hashable, Sendable {
 }
 
 /// A single item in the quick switcher results list
-struct QuickSwitcherItem: Identifiable, Hashable {
+internal struct QuickSwitcherItem: Identifiable, Hashable {
     let id: String
     let name: String
     let kind: QuickSwitcherItemKind
diff --git a/TablePro/ViewModels/QuickSwitcherViewModel.swift b/TablePro/ViewModels/QuickSwitcherViewModel.swift
@@ -11,7 +11,7 @@ import os
 
 /// ViewModel managing quick switcher search, filtering, and keyboard navigation
 @MainActor @Observable
-final class QuickSwitcherViewModel {
+internal final class QuickSwitcherViewModel {
     private static let logger = Logger(subsystem: "com.TablePro", category: "QuickSwitcherViewModel")
 
     // MARK: - State
@@ -28,6 +28,7 @@ final class QuickSwitcherViewModel {
     var isLoading = false
 
     @ObservationIgnored private var filterTask: Task<Void, Never>?
+    @ObservationIgnored private var activeLoadId = UUID()
 
     /// Maximum number of results to display
     private let maxResults = 100
@@ -41,6 +42,8 @@ final class QuickSwitcherViewModel {
         databaseType: DatabaseType
     ) async {
         isLoading = true
+        let loadId = UUID()
+        activeLoadId = loadId
         var items: [QuickSwitcherItem] = []
 
         // Tables, views, system tables from cached schema
@@ -116,6 +119,11 @@ final class QuickSwitcherViewModel {
             ))
         }
 
+        guard activeLoadId == loadId, !Task.isCancelled else {
+            isLoading = false
+            return
+        }
+
         allItems = items
         isLoading = false
     }
@@ -136,20 +144,29 @@ final class QuickSwitcherViewModel {
         if searchText.isEmpty {
             // Show all items grouped by kind: tables, views, system tables, databases, schemas, history
             filteredItems = allItems.sorted { a, b in
-                kindSortOrder(a.kind) < kindSortOrder(b.kind)
+                let aOrder = kindSortOrder(a.kind)
+                let bOrder = kindSortOrder(b.kind)
+                if aOrder != bOrder { return aOrder < bOrder }
+                return a.name < b.name
             }
             if filteredItems.count > maxResults {
                 filteredItems = Array(filteredItems.prefix(maxResults))
             }
         } else {
             filteredItems = allItems.compactMap { item in
                 let matchScore = FuzzyMatcher.score(query: searchText, candidate: item.name)
-                guard matchScore > 0 else { return nil as QuickSwitcherItem? }
+                guard matchScore > 0 else { return nil }
                 var scored = item
                 scored.score = matchScore
                 return scored
             }
-            .sorted { $0.score > $1.score }
+            .sorted { a, b in
+                if a.score != b.score { return a.score > b.score }
+                let aOrder = kindSortOrder(a.kind)
+                let bOrder = kindSortOrder(b.kind)
+                if aOrder != bOrder { return aOrder < bOrder }
+                return a.name < b.name
+            }
 
             if filteredItems.count > maxResults {
                 filteredItems = Array(filteredItems.prefix(maxResults))
diff --git a/TablePro/Views/QuickSwitcher/QuickSwitcherView.swift b/TablePro/Views/QuickSwitcher/QuickSwitcherView.swift
@@ -11,7 +11,7 @@ import SwiftUI
 // MARK: - Sheet
 
 /// Native SwiftUI sheet for the quick switcher, matching the project's ActiveSheet pattern.
-struct QuickSwitcherSheet: View {
+internal struct QuickSwitcherSheet: View {
     @Binding var isPresented: Bool
     @Environment(\.dismiss) private var dismiss
 
@@ -65,11 +65,11 @@ struct QuickSwitcherSheet: View {
             return .handled
         }
         .onKeyPress(.upArrow) {
-            Task { @MainActor in viewModel.moveUp() }
+            viewModel.moveUp()
             return .handled
         }
         .onKeyPress(.downArrow) {
-            Task { @MainActor in viewModel.moveDown() }
+            viewModel.moveDown()
             return .handled
         }
     }
@@ -144,26 +144,26 @@ struct QuickSwitcherSheet: View {
 
         return HStack(spacing: 10) {
             Image(systemName: item.iconName)
-                .font(.system(size: 14))
+                .font(.system(size: DesignConstants.IconSize.default))
                 .foregroundStyle(isSelected ? .white : .secondary)
 
             Text(item.name)
-                .font(.system(size: 13))
+                .font(.system(size: DesignConstants.FontSize.body))
                 .foregroundStyle(isSelected ? .white : .primary)
                 .lineLimit(1)
                 .truncationMode(.tail)
 
             if !item.subtitle.isEmpty {
                 Text(item.subtitle)
-                    .font(.system(size: 11))
+                    .font(.system(size: DesignConstants.FontSize.small))
                     .foregroundStyle(isSelected ? Color.white.opacity(0.7) : Color.secondary)
                     .lineLimit(1)
             }
 
             Spacer()
 
             Text(item.kindLabel)
-                .font(.system(size: 10, weight: .medium))
+                .font(.system(size: DesignConstants.FontSize.caption, weight: .medium))
                 .foregroundStyle(isSelected ? .white.opacity(0.7) : .secondary)
                 .padding(.horizontal, 6)
                 .padding(.vertical, 2)
diff --git a/TableProTests/Utilities/FuzzyMatcherTests.swift b/TableProTests/Utilities/FuzzyMatcherTests.swift
@@ -95,10 +95,10 @@ struct FuzzyMatcherTests {
 
     // MARK: - Emoji / Surrogate Handling
 
-    @Test("Emoji in query does not block matching")
-    func emojiInQueryDoesNotBlock() {
+    @Test("Emoji in query blocks matching when it cannot match any candidate character")
+    func emojiInQueryBlocksWhenUnmatched() {
         let result = FuzzyMatcher.score(query: "🎉u", candidate: "users")
-        #expect(result > 0, "Query with leading emoji should still match remaining characters")
+        #expect(result == 0, "Leading emoji that cannot match any candidate character blocks subsequent matches")
     }
 
     @Test("Emoji in candidate string handled correctly")
diff --git a/TableProTests/ViewModels/QuickSwitcherViewModelTests.swift b/TableProTests/ViewModels/QuickSwitcherViewModelTests.swift
@@ -111,8 +111,10 @@ struct QuickSwitcherViewModelTests {
     func selectedItemReturnsCorrectItem() {
         let vm = makeViewModel(items: sampleItems())
         vm.searchText = ""
-        vm.selectedItemId = vm.filteredItems[1].id
-        #expect(vm.selectedItem?.name == "orders")
+        let secondItem = vm.filteredItems[1]
+        vm.selectedItemId = secondItem.id
+        #expect(vm.selectedItem?.id == secondItem.id)
+        #expect(vm.selectedItem?.name == secondItem.name)
     }
 
     @Test("selectedItem returns nil for empty list")
diff --git a/docs/features/keyboard-shortcuts.mdx b/docs/features/keyboard-shortcuts.mdx
@@ -17,6 +17,7 @@ TablePro is keyboard-driven. Most actions have shortcuts, and most menu shortcut
 | New connection | `Cmd+N` |
 | Open history | `Cmd+Y` |
 | Settings | `Cmd+,` |
+| Quick Switcher | `Cmd+P` |
 | Close window | `Cmd+W` |
 | Quit | `Cmd+Q` |
 
@@ -264,7 +265,7 @@ Vim mode keybindings only apply in the SQL editor. They don't affect the data gr
 | Export data | `Cmd+Shift+E` |
 | Import data | `Cmd+Shift+I` |
 
-## Quick Switcher
+## Quick switcher
 
 The Quick Switcher (`Cmd+P`) lets you search and jump to any table, view, database, schema, or recent query. It uses fuzzy matching, so typing `usr` finds `users`, `user_settings`, etc.
 
@@ -451,6 +452,7 @@ Cmd+Shift+L    Toggle AI Chat
 Cmd+L          Explain with AI
 Cmd+Opt+L      Optimize with AI
 Cmd+,          Settings
+Cmd+P          Quick Switcher
 Cmd+W          Close window
 Cmd+Q          Quit
 ```
diff --git a/docs/vi/features/keyboard-shortcuts.mdx b/docs/vi/features/keyboard-shortcuts.mdx
@@ -17,6 +17,7 @@ TablePro thiên về bàn phím. Hầu hết thao tác đều có phím tắt, v
 | Kết nối mới | `Cmd+N` |
 | Mở lịch sử | `Cmd+Y` |
 | Cài đặt | `Cmd+,` |
+| Quick Switcher | `Cmd+P` |
 | Đóng cửa sổ | `Cmd+W` |
 | Thoát | `Cmd+Q` |
 
@@ -264,7 +265,7 @@ Phím tắt Vim chỉ áp dụng trong SQL editor. Không ảnh hưởng data gr
 | Export dữ liệu | `Cmd+Shift+E` |
 | Import dữ liệu | `Cmd+Shift+I` |
 
-## Quick Switcher
+## Quick switcher
 
 Quick Switcher (`Cmd+P`) cho phép tìm kiếm và chuyển nhanh đến bất kỳ bảng, view, database, schema, hoặc query gần đây. Hỗ trợ fuzzy matching, gõ `usr` sẽ tìm `users`, `user_settings`, v.v.
 
@@ -453,6 +454,7 @@ dd/yy/cc       Xóa/Yank/Thay đổi dòng
 Cmd+N          Kết nối mới
 Cmd+Y          Lịch sử query
 Cmd+,          Cài đặt
+Cmd+P          Quick Switcher
 Cmd+W          Đóng cửa sổ
 Cmd+Q          Thoát
 ```
diff --git a/docs/zh/features/keyboard-shortcuts.mdx b/docs/zh/features/keyboard-shortcuts.mdx
@@ -17,6 +17,7 @@ TablePro 以键盘操作为核心。大多数操作都有快捷键，大部分
 | 新建连接 | `Cmd+N` |
 | 打开历史 | `Cmd+Y` |
 | 设置 | `Cmd+,` |
+| Quick Switcher | `Cmd+P` |
 | 关闭窗口 | `Cmd+W` |
 | 退出 | `Cmd+Q` |
 
@@ -264,7 +265,7 @@ Vim 模式键绑定仅在 SQL 编辑器中生效。不影响数据网格或其
 | 导出数据 | `Cmd+Shift+E` |
 | 导入数据 | `Cmd+Shift+I` |
 
-## Quick Switcher
+## Quick switcher
 
 Quick Switcher (`Cmd+P`) 可搜索并快速跳转到任意表、视图、数据库、schema 或最近的查询。支持模糊匹配，输入 `usr` 可找到 `users`、`user_settings` 等。
 
@@ -451,6 +452,7 @@ Cmd+Shift+L    切换 AI 聊天
 Cmd+L          AI 解释
 Cmd+Opt+L      AI 优化
 Cmd+,          设置
+Cmd+P          Quick Switcher
 Cmd+W          关闭窗口
 Cmd+Q          退出
 ```
