Expand Two-Way Editor State Bindings (#337)

Author: thecoolwinter

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved

@@ -19,7 +19,9 @@ struct ContentView: View {
 
     @State private var language: CodeLanguage = .default
     @State private var theme: EditorTheme = .light
-    @State private var cursorPositions: [CursorPosition] = [.init(line: 1, column: 1)]
+    @State private var editorState = SourceEditorState(
+        cursorPositions: [CursorPosition(line: 1, column: 1)]
+    )
 
     @State private var font: NSFont = NSFont.monospacedSystemFont(ofSize: 12, weight: .medium)
     @AppStorage("wrapLines") private var wrapLines: Bool = true
@@ -67,15 +69,15 @@ struct ContentView: View {
                         warningCharacters: warningCharacters
                     )
                 ),
-                cursorPositions: $cursorPositions
+                state: $editorState
             )
             .overlay(alignment: .bottom) {
                 StatusBar(
                     fileURL: fileURL,
                     document: $document,
                     wrapLines: $wrapLines,
                     useSystemCursor: $useSystemCursor,
-                    cursorPositions: $cursorPositions,
+                    state: $editorState,
                     isInLongParse: $isInLongParse,
                     language: $language,
                     theme: $theme,

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/ContentView.swift

@@ -18,7 +18,7 @@ struct StatusBar: View {
     @Binding var document: CodeEditSourceEditorExampleDocument
     @Binding var wrapLines: Bool
     @Binding var useSystemCursor: Bool
-    @Binding var cursorPositions: [CursorPosition]
+    @Binding var state: SourceEditorState
     @Binding var isInLongParse: Bool
     @Binding var language: CodeLanguage
     @Binding var theme: EditorTheme
@@ -100,11 +100,29 @@ struct StatusBar: View {
                             .controlSize(.small)
                         Text("Parsing Document")
                     }
-                } else {
-                    Text(getLabel(cursorPositions))
                 }
+                scrollPosition
+                Text(getLabel(state.cursorPositions))
+            }
+            .foregroundStyle(.secondary)
+
+            Divider()
+                .frame(height: 12)
+
+            Text(state.findText ?? "")
+                .frame(maxWidth: 30)
+                .lineLimit(1)
+                .truncationMode(.head)
+                .foregroundStyle(.secondary)
+
+            Button {
+                state.findPanelVisible.toggle()
+            } label: {
+                Text(state.findPanelVisible ? "Hide" : "Show") + Text(" Find")
             }
+            .buttonStyle(.borderless)
             .foregroundStyle(.secondary)
+
             Divider()
                 .frame(height: 12)
             LanguagePicker(language: $language)
@@ -133,6 +151,39 @@ struct StatusBar: View {
         }
     }
 
+    var formatter: NumberFormatter {
+        let formatter = NumberFormatter()
+        formatter.numberStyle = .decimal
+        formatter.maximumFractionDigits = 2
+        formatter.minimumFractionDigits = 0
+        formatter.allowsFloats = true
+        return formatter
+    }
+
+    @ViewBuilder private var scrollPosition: some View {
+        HStack(spacing: 0) {
+            Text("{")
+            TextField(
+                "",
+                value: Binding(get: { Double(state.scrollPosition?.x ?? 0.0) }, set: { state.scrollPosition?.x = $0 }),
+                formatter: formatter
+            )
+            .textFieldStyle(.plain)
+            .labelsHidden()
+            .fixedSize()
+            Text(",")
+            TextField(
+                "",
+                value: Binding(get: { Double(state.scrollPosition?.y ?? 0.0) }, set: { state.scrollPosition?.y = $0 }),
+                formatter: formatter
+            )
+            .textFieldStyle(.plain)
+            .labelsHidden()
+            .fixedSize()
+            Text("}")
+        }
+    }
+
     private func detectLanguage(fileURL: URL?) -> CodeLanguage? {
         guard let fileURL else { return nil  }
         return CodeLanguage.detectLanguageFrom(

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/StatusBar.swift

@@ -38,20 +38,28 @@ This package is fully documented [here](https://codeeditapp.github.io/CodeEditSo
 
 ## Usage (SwiftUI)
 
+CodeEditSourceEditor provides two APIs for creating an editor: SwiftUI and AppKit. The SwiftUI API provides extremely customizable and flexible configuration options, including two-way bindings for state like cursor positions and scroll position. 
+
+For more complex features that require access to the underlying text view or text storage, we've developed the <doc:TextViewCoordinators> API. Using this API, developers can inject custom behavior into the editor as events happen, without having to work with state or bindings.
+
 ```swift
 import CodeEditSourceEditor
 
 struct ContentView: View {
     @State var text = "let x = 1.0"
 
-    /// Automatically updates with cursor positions, or update the binding to set the user's cursors.
-    @State var cursorPositions: [CursorPosition] = []
+   /// Automatically updates with cursor positions, scroll position, find panel text.
+    /// Everything in this object is two-way, use it to update cursor positions, scroll position, etc.
+    @State var editorState = SourceEditorState()
 
     /// Configure the editor's appearance, features, and editing behavior...
     @State var theme = EditorTheme(...)
     @State var font = NSFont.monospacedSystemFont(ofSize: 11, weight: .regular)
     @State var indentOption = .spaces(count: 4)
 
+    /// *Powerful* customization options with our text view coordinators API 
+    @State var autoCompleteCoordinator = AutoCompleteCoordinator()
+
     var body: some View { 
         SourceEditor(
             $text,
@@ -61,9 +69,27 @@ struct ContentView: View {
                 appearance: .init(theme: theme, font: font),
                 behavior: .init(indentOption: indentOption)
             ),
-            cursorPositions: $cursorPositions
+            state: $editorState,
+            coordinators: [autoCompleteCoordinator]
         )
     }
+    
+    /// Autocompletes "Hello" to "Hello world!" whenever it's typed.
+    final class AutoCompleteCoordinator: TextViewCoordinator {
+        func prepareCoordinator(controller: TextViewController) { }
+
+        func textViewDidChangeText(controller: TextViewController) {
+            for cursorPosition in controller.cursorPositions where cursorPosition.range.location >= 5 {
+                let location = cursorPosition.range.location
+                let previousRange = NSRange(start: location - 5, end: location)
+                let string = (controller.text as NSString).substring(with: previousRange)
+
+                if string.lowercased() == "hello" {
+                    controller.textView.replaceCharacters(in: NSRange(location: location, length: 0), with: " world!")
+                }
+            }
+        }
+    }
 }
 ```
 

README.md

@@ -102,6 +102,7 @@ extension TextViewController {
             guard let clipView = notification.object as? NSClipView else { return }
             self?.gutterView.needsDisplay = true
             self?.minimapXConstraint?.constant = clipView.bounds.origin.x
+            NotificationCenter.default.post(name: Self.scrollPositionDidUpdateNotification, object: self)
         }
     }
 
@@ -114,6 +115,7 @@ extension TextViewController {
             self?.gutterView.needsDisplay = true
             self?.emphasisManager?.removeEmphases(for: EmphasisGroup.brackets)
             self?.updateTextInsets()
+            NotificationCenter.default.post(name: Self.scrollPositionDidUpdateNotification, object: self)
         }
     }
 

Sources/CodeEditSourceEditor/Controller/TextViewController+LoadView.swift

@@ -19,6 +19,10 @@ import TextFormation
 public class TextViewController: NSViewController {
     // swiftlint:disable:next line_length
     public static let cursorPositionUpdatedNotification: Notification.Name = .init("TextViewController.cursorPositionNotification")
+    // swiftlint:disable:next line_length
+    public static let scrollPositionDidUpdateNotification: Notification.Name = .init("TextViewController.scrollPositionDidUpdateNotification")
+
+    // MARK: - Views and Child VCs
 
     // MARK: - Views and Child VCs
 

Sources/CodeEditSourceEditor/Controller/TextViewController.swift

@@ -2,7 +2,9 @@
 
 ## Usage
 
-CodeEditSourceEditor provides two APIs for creating an editor: SwiftUI and AppKit.
+CodeEditSourceEditor provides two APIs for creating an editor: SwiftUI and AppKit. We provide a fast and efficient SwiftUI API that avoids unnecessary view updates whenever possible. It also provides extremely customizable and flexible configuration options, including two-way bindings for state like cursor positions and scroll position. 
+
+For more complex features that require access to the underlying text view or text storage, we've developed the <doc:TextViewCoordinators> API. Using this API, developers can inject custom behavior into the editor as events happen, without having to work with state or bindings.
 
 #### SwiftUI
 
@@ -12,11 +14,12 @@ import CodeEditSourceEditor
 struct ContentView: View {
 
     @State var text = "let x = 1.0"
-    // For large documents use (avoids SwiftUI inneficiency)
+    // For large documents use a text storage object (avoids SwiftUI comparisons)
     // var text: NSTextStorage
 
-    /// Automatically updates with cursor positions, or update the binding to set the user's cursors.
-    @State var cursorPositions: [CursorPosition] = []
+    /// Automatically updates with cursor positions, scroll position, find panel text.
+    /// Everything in this object is two-way, use it to update cursor positions, scroll position, etc.
+    @State var editorState = SourceEditorState()
 
     /// Configure the editor's appearance, features, and editing behavior...
     @State var theme = EditorTheme(...)
@@ -25,6 +28,9 @@ struct ContentView: View {
     @State var editorOverscroll = 0.3
     @State var showMinimap = true
 
+    /// *Powerful* customization options with text coordinators 
+    @State var autoCompleteCoordinator = AutoCompleteCoordinator()
+
     var body: some View { 
         SourceEditor(
             $text,
@@ -35,9 +41,27 @@ struct ContentView: View {
                 layout: .init(editorOverscroll: editorOverscroll),
                 peripherals: .init(showMinimap: showMinimap)
             ),
-            cursorPositions: $cursorPositions
+            state: $editorState,
+            coordinators: [autoCompleteCoordinator]
         )
     }
+
+    /// Autocompletes "Hello" to "Hello world!" whenever it's typed.
+    class AutoCompleteCoordinator: TextViewCoordinator {
+        func prepareCoordinator(controller: TextViewController) { }
+
+        func textViewDidChangeText(controller: TextViewController) {
+            for cursorPosition in controller.cursorPositions.reversed() where cursorPosition.range.location >= 5 {
+                let location = cursorPosition.range.location
+                let previousRange = NSRange(start: location - 5, end: location)
+                let string = (controller.text as NSString).substring(with: previousRange)
+
+                if string.lowercased() == "hello" {
+                    controller.textView.replaceCharacters(in: NSRange(location: location, length: 0), with: " world!")
+                }
+            }
+        }
+    }
 }
 ```
 

Sources/CodeEditSourceEditor/Documentation.docc/SourceEditor.md

@@ -44,6 +44,11 @@ extension FindViewController {
 
         viewModel.isFocused = true
         findPanel.addEventMonitor()
+
+        NotificationCenter.default.post(
+            name: FindPanelViewModel.Notifications.didToggle,
+            object: viewModel.target
+        )
     }
 
     /// Hide the find panel
@@ -70,6 +75,11 @@ extension FindViewController {
         if let target = viewModel.target {
             _ = target.findPanelTargetView.window?.makeFirstResponder(target.findPanelTargetView)
         }
+
+        NotificationCenter.default.post(
+            name: FindPanelViewModel.Notifications.didToggle,
+            object: viewModel.target
+        )
     }
 
     /// Performs an animation with a completion handler, conditionally animating the changes.

Sources/CodeEditSourceEditor/Find/FindViewController+Toggle.swift

@@ -60,6 +60,9 @@ struct FindPanelView: View {
         .onChange(of: viewModel.findText) { _ in
             viewModel.findTextDidChange()
         }
+        .onChange(of: viewModel.replaceText) { _ in
+            viewModel.replaceTextDidChange()
+        }
         .onChange(of: viewModel.wrapAround) { _ in
             viewModel.find()
         }

Sources/CodeEditSourceEditor/Find/PanelView/FindPanelView.swift

@@ -10,6 +10,12 @@ import Combine
 import CodeEditTextView
 
 class FindPanelViewModel: ObservableObject {
+    enum Notifications {
+        static let textDidChange = Notification.Name("FindPanelViewModel.textDidChange")
+        static let replaceTextDidChange = Notification.Name("FindPanelViewModel.replaceTextDidChange")
+        static let didToggle = Notification.Name("FindPanelViewModel.didToggle")
+    }
+
     weak var target: FindPanelTarget?
     var dismiss: (() -> Void)?
 
@@ -99,5 +105,11 @@ class FindPanelViewModel: ObservableObject {
         // Clear existing emphases before performing new find
         target?.textView.emphasisManager?.removeEmphases(for: EmphasisGroup.find)
         find()
+
+        NotificationCenter.default.post(name: Self.Notifications.textDidChange, object: target)
+    }
+
+    func replaceTextDidChange() {
+        NotificationCenter.default.post(name: Self.Notifications.replaceTextDidChange, object: target)
     }
 }