Add binding support to Recorder

Fixes #164
Fixes #225

Author: sindresorhus

Example/KeyboardShortcutsExample/MainScreen.swift

@@ -122,14 +122,33 @@ private struct DoubleShortcut: View {
 	}
 }
 
+private struct BindingShortcut: View {
+	@State private var shortcut: KeyboardShortcuts.Shortcut?
+
+	var body: some View {
+		Form {
+			KeyboardShortcuts.Recorder("Binding Shortcut:", shortcut: $shortcut)
+			Text("Current: \(shortcut.map { "\($0)" } ?? "None")")
+				.frame(maxWidth: .infinity, alignment: .leading)
+			Button("Clear") {
+				shortcut = nil
+			}
+		}
+		.frame(maxWidth: 300)
+		.padding()
+	}
+}
+
 struct MainScreen: View {
 	var body: some View {
 		VStack {
 			DoubleShortcut()
 			Divider()
+			BindingShortcut()
+			Divider()
 			DynamicShortcut()
 		}
-		.frame(width: 400, height: 320)
+		.frame(width: 400, height: 520)
 	}
 }
 

Sources/KeyboardShortcuts/Name.swift

@@ -34,8 +34,14 @@ extension KeyboardShortcuts {
 		/**
 		- Parameter name: Name of the shortcut.
 		- Parameter initialShortcut: Optional default key combination. Do not set this unless it's essential. Users find it annoying when random apps steal their existing keyboard shortcuts. It's generally better to show a welcome screen on the first app launch that lets the user set the shortcut.
+		- Important: The name must not contain a dot (`.`) because it is used as a key path for observation.
 		*/
 		public init(_ name: String, default initialShortcut: Shortcut? = nil) {
+			runtimeWarn(
+				KeyboardShortcuts.isValidShortcutName(name),
+				"The keyboard shortcut name must not contain a dot (.)."
+			)
+
 			self.rawValue = name
 			self.defaultShortcut = initialShortcut
 
@@ -51,6 +57,13 @@ extension KeyboardShortcuts {
 	}
 }
 
+extension KeyboardShortcuts.Name {
+	init(rawValueWithoutInitialization rawValue: String) {
+		self.rawValue = rawValue
+		self.defaultShortcut = nil
+	}
+}
+
 extension KeyboardShortcuts.Name: RawRepresentable {
 	/// :nodoc:
 	public init?(rawValue: String) {

Sources/KeyboardShortcuts/Recorder.swift

@@ -2,18 +2,74 @@
 import SwiftUI
 
 extension KeyboardShortcuts {
+	enum ShortcutSource {
+		case name(Name)
+		case binding(Binding<Shortcut?>)
+
+		var binding: Binding<Shortcut?>? {
+			if case .binding(let binding) = self { binding } else { nil }
+		}
+	}
+
 	private struct _Recorder: NSViewRepresentable { // swiftlint:disable:this type_name
 		typealias NSViewType = RecorderCocoa
 
-		let name: Name
+		let source: ShortcutSource
 		let onChange: ((_ shortcut: Shortcut?) -> Void)?
 
+		final class Coordinator {
+			var shortcutBinding: Binding<Shortcut?>?
+			var onChange: ((_ shortcut: Shortcut?) -> Void)?
+
+			init(
+				shortcutBinding: Binding<Shortcut?>?,
+				onChange: ((_ shortcut: Shortcut?) -> Void)?
+			) {
+				self.shortcutBinding = shortcutBinding
+				self.onChange = onChange
+			}
+
+			func handleChange(_ shortcut: Shortcut?) {
+				shortcutBinding?.wrappedValue = shortcut
+				onChange?(shortcut)
+			}
+		}
+
+		func makeCoordinator() -> Coordinator {
+			.init(shortcutBinding: source.binding, onChange: onChange)
+		}
+
 		func makeNSView(context: Context) -> NSViewType {
-			.init(for: name, onChange: onChange)
+			let coordinator = context.coordinator
+
+			switch source {
+			case .name(let name):
+				return .init(for: name) { shortcut in
+					coordinator.handleChange(shortcut)
+				}
+			case .binding(let binding):
+				return .init(shortcut: binding.wrappedValue) { shortcut in
+					coordinator.handleChange(shortcut)
+				}
+			}
 		}
 
 		func updateNSView(_ nsView: NSViewType, context: Context) {
-			nsView.shortcutName = name
+			let coordinator = context.coordinator
+			coordinator.onChange = onChange
+
+			switch source {
+			case .name(let name):
+				nsView.shortcutName = name
+			case .binding(let binding):
+				coordinator.shortcutBinding = binding
+
+				guard nsView.shortcut != binding.wrappedValue else {
+					return
+				}
+
+				nsView.shortcut = binding.wrappedValue
+			}
 		}
 	}
 
@@ -24,7 +80,9 @@ extension KeyboardShortcuts {
 
 	It automatically prevents choosing a keyboard shortcut that is already taken by the system or by the app's main menu by showing a user-friendly alert to the user.
 
-	It takes care of storing the keyboard shortcut in `UserDefaults` for you.
+	It takes care of storing the keyboard shortcut in `UserDefaults` for you when initialized with a name. When initialized with a binding, it reads and writes the shortcut through the binding.
+
+	- Note: When initialized with a binding, the shortcut is not automatically registered as a global hotkey. You are responsible for storing and handling the shortcut yourself.
 
 	```swift
 	import SwiftUI
@@ -42,18 +100,18 @@ extension KeyboardShortcuts {
 	- Note: Since macOS 15, for sandboxed apps, it's [no longer possible](https://developer.apple.com/forums/thread/763878?answerId=804374022#804374022) to specify the `Option` key without also using `Command` or `Control`.
 	*/
 	public struct Recorder<Label: View>: View { // swiftlint:disable:this type_name
-		private let name: Name
+		private let shortcutSource: ShortcutSource
 		private let onChange: ((Shortcut?) -> Void)?
 		private let hasLabel: Bool
 		private let label: Label
 
-		init(
-			for name: Name,
+		private init(
+			shortcutSource: ShortcutSource,
 			onChange: ((Shortcut?) -> Void)? = nil,
 			hasLabel: Bool,
 			@ViewBuilder label: () -> Label
 		) {
-			self.name = name
+			self.shortcutSource = shortcutSource
 			self.onChange = onChange
 			self.hasLabel = hasLabel
 			self.label = label()
@@ -63,29 +121,27 @@ extension KeyboardShortcuts {
 			if hasLabel {
 				if #available(macOS 13, *) {
 					LabeledContent {
-						_Recorder(
-							name: name,
-							onChange: onChange
-						)
+						recorderView
 					} label: {
 						label
 					}
 				} else {
-					_Recorder(
-						name: name,
-						onChange: onChange
-					)
+					recorderView
 						.formLabel {
 							label
 						}
 				}
 			} else {
-				_Recorder(
-					name: name,
-					onChange: onChange
-				)
+				recorderView
 			}
 		}
+
+		private var recorderView: some View {
+			_Recorder(
+				source: shortcutSource,
+				onChange: onChange
+			)
+		}
 	}
 }
 
@@ -99,14 +155,47 @@ extension KeyboardShortcuts.Recorder<EmptyView> {
 		onChange: ((KeyboardShortcuts.Shortcut?) -> Void)? = nil
 	) {
 		self.init(
-			for: name,
+			shortcutSource: .name(name),
+			onChange: onChange,
+			hasLabel: false
+		) {}
+	}
+
+	/**
+	Creates a keyboard shortcut recorder that reads and writes to a binding.
+
+	Use this initializer when you want to manage the shortcut storage yourself instead of using the built-in `UserDefaults` storage. The shortcut is not automatically registered as a global hotkey — you are responsible for storing and handling the shortcut yourself.
+
+	- Parameter shortcut: The keyboard shortcut binding to read and write.
+	- Parameter onChange: Callback which will be called when the keyboard shortcut is changed/removed by the user.
+	*/
+	public init(
+		shortcut: Binding<KeyboardShortcuts.Shortcut?>,
+		onChange: ((KeyboardShortcuts.Shortcut?) -> Void)? = nil
+	) {
+		self.init(
+			shortcutSource: .binding(shortcut),
 			onChange: onChange,
 			hasLabel: false
 		) {}
 	}
 }
 
 extension KeyboardShortcuts.Recorder<Text> {
+	private init(
+		_ title: Text,
+		source: KeyboardShortcuts.ShortcutSource,
+		onChange: ((KeyboardShortcuts.Shortcut?) -> Void)?
+	) {
+		self.init(
+			shortcutSource: source,
+			onChange: onChange,
+			hasLabel: true
+		) {
+			title
+		}
+	}
+
 	/**
 	- Parameter title: The title of the keyboard shortcut recorder, describing its purpose.
 	- Parameter name: Strongly-typed keyboard shortcut name.
@@ -117,17 +206,9 @@ extension KeyboardShortcuts.Recorder<Text> {
 		name: KeyboardShortcuts.Name,
 		onChange: ((KeyboardShortcuts.Shortcut?) -> Void)? = nil
 	) {
-		self.init(
-			for: name,
-			onChange: onChange,
-			hasLabel: true
-		) {
-			Text(title)
-		}
+		self.init(Text(title), source: .name(name), onChange: onChange)
 	}
-}
 
-extension KeyboardShortcuts.Recorder<Text> {
 	/**
 	- Parameter title: The title of the keyboard shortcut recorder, describing its purpose.
 	- Parameter name: Strongly-typed keyboard shortcut name.
@@ -139,13 +220,42 @@ extension KeyboardShortcuts.Recorder<Text> {
 		name: KeyboardShortcuts.Name,
 		onChange: ((KeyboardShortcuts.Shortcut?) -> Void)? = nil
 	) {
-		self.init(
-			for: name,
-			onChange: onChange,
-			hasLabel: true
-		) {
-			Text(title)
-		}
+		self.init(Text(title), source: .name(name), onChange: onChange)
+	}
+
+	/**
+	Creates a keyboard shortcut recorder that reads and writes to a binding.
+
+	Use this initializer when you want to manage the shortcut storage yourself instead of using the built-in `UserDefaults` storage. The shortcut is not automatically registered as a global hotkey — you are responsible for storing and handling the shortcut yourself.
+
+	- Parameter title: The title of the keyboard shortcut recorder, describing its purpose.
+	- Parameter shortcut: The keyboard shortcut binding to read and write.
+	- Parameter onChange: Callback which will be called when the keyboard shortcut is changed/removed by the user.
+	*/
+	public init(
+		_ title: LocalizedStringKey,
+		shortcut: Binding<KeyboardShortcuts.Shortcut?>,
+		onChange: ((KeyboardShortcuts.Shortcut?) -> Void)? = nil
+	) {
+		self.init(Text(title), source: .binding(shortcut), onChange: onChange)
+	}
+
+	/**
+	Creates a keyboard shortcut recorder that reads and writes to a binding.
+
+	Use this initializer when you want to manage the shortcut storage yourself instead of using the built-in `UserDefaults` storage. The shortcut is not automatically registered as a global hotkey — you are responsible for storing and handling the shortcut yourself.
+
+	- Parameter title: The title of the keyboard shortcut recorder, describing its purpose.
+	- Parameter shortcut: The keyboard shortcut binding to read and write.
+	- Parameter onChange: Callback which will be called when the keyboard shortcut is changed/removed by the user.
+	*/
+	@_disfavoredOverload
+	public init(
+		_ title: String,
+		shortcut: Binding<KeyboardShortcuts.Shortcut?>,
+		onChange: ((KeyboardShortcuts.Shortcut?) -> Void)? = nil
+	) {
+		self.init(Text(title), source: .binding(shortcut), onChange: onChange)
 	}
 }
 
@@ -161,7 +271,29 @@ extension KeyboardShortcuts.Recorder {
 		@ViewBuilder label: () -> Label
 	) {
 		self.init(
-			for: name,
+			shortcutSource: .name(name),
+			onChange: onChange,
+			hasLabel: true,
+			label: label
+		)
+	}
+
+	/**
+	Creates a keyboard shortcut recorder that reads and writes to a binding.
+
+	Use this initializer when you want to manage the shortcut storage yourself instead of using the built-in `UserDefaults` storage. The shortcut is not automatically registered as a global hotkey — you are responsible for storing and handling the shortcut yourself.
+
+	- Parameter shortcut: The keyboard shortcut binding to read and write.
+	- Parameter onChange: Callback which will be called when the keyboard shortcut is changed/removed by the user.
+	- Parameter label: A view that describes the purpose of the keyboard shortcut recorder.
+	*/
+	public init(
+		shortcut: Binding<KeyboardShortcuts.Shortcut?>,
+		onChange: ((KeyboardShortcuts.Shortcut?) -> Void)? = nil,
+		@ViewBuilder label: () -> Label
+	) {
+		self.init(
+			shortcutSource: .binding(shortcut),
 			onChange: onChange,
 			hasLabel: true,
 			label: label