Update Documentation and README Examples

Author: thecoolwinter

README.md

@@ -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!")
+                }
+            }
+        }
+    }
 }
 ```
 

Sources/CodeEditSourceEditor/Documentation.docc/SourceEditor.md

@@ -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!")
+                }
+            }
+        }
+    }
 }
 ```