fix(settings): say why a shortcut with only Option or Shift is refused (#2462)

Claude-Session: https://claude.ai/code/session_014MXT7tDsb7Rsm1HhBnwhSj

Signed-off-by: Ngô Quốc Đạt <datlechin@gmail.com>

Author: datlechin

CHANGELOG.md

@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - A data grid shortcut bound to `Cmd+G` silently taking the key from Find Next, with no conflict warning.
 - Stale cells after fitting, hiding or reordering a data grid column on a result narrower than the window. (#2446)
+- A shortcut recorded with only Option or Shift beeping with no reason given, against docs that said it would work.
 - A rebound shortcut silently killing Quit, Minimize, Hide, Settings, Show Toolbar or Enter Full Screen.
 - `Ctrl+Cmd+J` accepted in Settings > Keyboard while the SQL editor kept it for Jump to Definition.
 - Autocomplete keeping an earlier prefix's ordering after the typed word becomes an exact match. (#2444)

TablePro/Views/Settings/KeyboardSettingsView.swift

@@ -132,7 +132,7 @@ struct KeyboardSettingsView: View {
                 needsModifierAlert = nil
             }
         } message: {
-            Text(String(localized: "This action needs a modifier key like ⌘ or ⌥. A plain key won't reach the menu reliably."))
+            Text(String(localized: "This action needs ⌘ or ⌃. Option and Shift can join them, but cannot hold a shortcut on their own."))
         }
         .onAppear {
             SystemHotkeyChecker.shared.reload()
@@ -169,6 +169,9 @@ struct KeyboardSettingsView: View {
                 },
                 onClear: {
                     settings.clearShortcut(for: action)
+                },
+                onUnusableModifiers: {
+                    needsModifierAlert = action
                 }
             )
             .frame(width: 160, height: 24)

TablePro/Views/Settings/ShortcutRecorderView.swift

@@ -19,6 +19,10 @@ final class ShortcutRecorderNSView: NSView {
     /// Callback when the shortcut is cleared (Delete key while recording)
     var onClear: (() -> Void)?
 
+    /// Callback when the captured combo carries no modifier the menu can use, so the
+    /// caller can say why instead of leaving the recorder to beep with no explanation.
+    var onUnusableModifiers: (() -> Void)?
+
     /// The currently displayed key combo
     var currentCombo: BoundKey? {
         didSet {
@@ -149,7 +153,8 @@ final class ShortcutRecorderNSView: NSView {
             return nil
         }
         guard let combo = BoundKey(from: event) else {
-            NSSound.beep()
+            endRecording()
+            onUnusableModifiers?()
             return nil
         }
         onRecord?(combo)
@@ -290,6 +295,9 @@ struct ShortcutRecorderView: NSViewRepresentable {
     /// Called when the shortcut is cleared
     var onClear: (() -> Void)?
 
+    /// Called when the pressed combo carries no modifier a menu key equivalent can use.
+    var onUnusableModifiers: (() -> Void)?
+
     func makeNSView(context: Context) -> ShortcutRecorderNSView {
         let view = ShortcutRecorderNSView()
         view.currentCombo = combo
@@ -299,12 +307,16 @@ struct ShortcutRecorderView: NSViewRepresentable {
         view.onClear = {
             onClear?()
         }
+        view.onUnusableModifiers = {
+            onUnusableModifiers?()
+        }
         return view
     }
 
     func updateNSView(_ nsView: ShortcutRecorderNSView, context: Context) {
         nsView.currentCombo = combo
         nsView.onRecord = { [onRecord] newCombo in onRecord?(newCombo) }
         nsView.onClear = { [onClear] in onClear?() }
+        nsView.onUnusableModifiers = { [onUnusableModifiers] in onUnusableModifiers?() }
     }
 }

TableProTests/Models/KeyboardShortcutTests.swift

@@ -7,6 +7,7 @@
 //  and migration from the legacy character-string storage.
 //
 
+import AppKit
 import Foundation
 @testable import TablePro
 import Testing
@@ -181,6 +182,35 @@ struct BareKeyValidationTests {
         #expect(!ShortcutAction.executeQuery.allowsBareKey)
     }
 
+    /// The recorder tells the user a shortcut needs Command or Control, so the capture rule has
+    /// to be exactly that. Option and Shift only ever qualify a combo, they never carry one, and
+    /// a letter key held with either alone is a text-input keystroke rather than a shortcut.
+    @Test("Option and Shift cannot hold a shortcut without Command or Control")
+    func optionAndShiftAloneAreNotRecordable() {
+        func capture(_ flags: NSEvent.ModifierFlags) -> BoundKey? {
+            let event = NSEvent.keyEvent(
+                with: .keyDown,
+                location: .zero,
+                modifierFlags: flags,
+                timestamp: 0,
+                windowNumber: 0,
+                context: nil,
+                characters: "e",
+                charactersIgnoringModifiers: "e",
+                isARepeat: false,
+                keyCode: 14
+            )
+            return event.flatMap(BoundKey.init(from:))
+        }
+
+        #expect(capture(.option) == nil)
+        #expect(capture(.shift) == nil)
+        #expect(capture([.option, .shift]) == nil)
+        #expect(capture(.command) != nil)
+        #expect(capture(.control) != nil)
+        #expect(capture([.command, .option]) != nil)
+    }
+
     @Test("hasModifier reflects the combo")
     func hasModifierReflectsCombo() {
         #expect(BoundKey.character("r", command: true).hasModifier)

docs/features/keyboard-shortcuts.mdx

@@ -270,7 +270,7 @@ Open **Settings > Keyboard** (`Cmd+,`). Each action has a recorder field: click
 
 A combination already taken by another action in the same context raises a dialog naming it: **Cancel** keeps the existing assignment, **Reassign** moves the shortcut and clears it from the other action. Editor and grid actions can share a key without conflict.
 
-Menu actions need a modifier (`Cmd`, `Option`, `Ctrl`, or `Shift`); function keys `F1` through `F12` work bare, as do grid actions that read the key directly, like Preview FK Reference (`Space`).
+Menu actions need `Cmd` or `Ctrl`, with `Option` and `Shift` available alongside them but not on their own; function keys `F1` through `F12` work bare, as do grid actions that read the key directly, like Preview FK Reference (`Space`).
 
 <Info>
 Some shortcuts cannot be reassigned: editor built-ins such as `Cmd+/`, tab selection (`Cmd+1` through `Cmd+9`), text size (`Cmd+=`, `Cmd+-`), and macOS system shortcuts, which are read live from System Settings. The recorder warns if you try.