Suggestion Window Fixes (#350)

### Description

Generally improves a few UX bugs with the suggestion window.
Specifically the window would flash often even if the controller did not
re-request new items, and would sometimes move the window when it
shouldn't have. Also adjusts the window's x position to align the
completion labels with the text.

- Centralizes suggestion presentation logic into a single class.
- Moves the trigger character logic out of a filter and into a textview
delegate-like method that checks if the last typed character was a
trigger character.
- Ensures the textview and cursor positions are up-to-date when the
notification is sent.
- Helps remove duplicate cursor update notifications sent to the
suggestion controller by checking if an update is a duplicate in the
centralized logic controller.
- Adjusts the suggestion window's x position to align the text in the
completion labels with the text being typed.

Also includes a few changes fixing some build warnings.

### Related Issues

* #282 

### Checklist

- [x] I read and understood the [contributing
guide](https://github.com/CodeEditApp/CodeEdit/blob/main/CONTRIBUTING.md)
as well as the [code of
conduct](https://github.com/CodeEditApp/CodeEdit/blob/main/CODE_OF_CONDUCT.md)
- [x] The issues this PR addresses are related to each other
- [x] My changes generate no new warnings
- [x] My code builds and runs on my machine
- [x] My changes are all related to the related issue above
- [x] I documented my code

### Screenshots


https://github.com/user-attachments/assets/14662210-0c15-422d-8dea-a5ae55b5d836

Author: thecoolwinter

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

@@ -45,9 +45,12 @@ private let text = [
 ]
 
 class MockCompletionDelegate: CodeSuggestionDelegate, ObservableObject {
+    var lastPosition: CursorPosition?
+
     class Suggestion: CodeSuggestionEntry {
         var label: String
         var detail: String?
+        var documentation: String?
         var pathComponents: [String]?
         var targetPosition: CursorPosition? = CursorPosition(line: 10, column: 20)
         var sourcePreview: String?
@@ -89,19 +92,32 @@ class MockCompletionDelegate: CodeSuggestionDelegate, ObservableObject {
         cursorPosition: CursorPosition
     ) async -> (windowPosition: CursorPosition, items: [CodeSuggestionEntry])? {
         try? await Task.sleep(for: .seconds(0.2))
+        lastPosition = cursorPosition
         return (cursorPosition, randomSuggestions())
     }
 
     func completionOnCursorMove(
         textView: TextViewController,
         cursorPosition: CursorPosition
     ) -> [CodeSuggestionEntry]? {
+        // Check if we're typing all in a row.
+        guard (lastPosition?.range.location ?? 0) + 1 == cursorPosition.range.location else {
+            lastPosition = nil
+            moveCount = 0
+            return nil
+        }
+
+        lastPosition = cursorPosition
         moveCount += 1
         switch moveCount {
         case 1:
             return randomSuggestions(2)
         case 2:
             return randomSuggestions(20)
+        case 3:
+            return randomSuggestions(4)
+        case 4:
+            return randomSuggestions(1)
         default:
             moveCount = 0
             return nil

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/MockCompletionDelegate.swift

@@ -15,13 +15,16 @@ final class MockJumpToDefinitionDelegate: JumpToDefinitionDelegate, ObservableOb
                 url: nil,
                 targetRange: CursorPosition(line: 0, column: 10),
                 typeName: "Start of Document",
-                sourcePreview: "// Comment at start"
+                sourcePreview: "// Comment at start",
+                documentation: "Jumps to the comment at the start of the document. Useful?"
             ),
             JumpToDefinitionLink(
                 url: URL(string: "https://codeedit.app/"),
                 targetRange: CursorPosition(line: 1024, column: 10),
                 typeName: "CodeEdit Website",
-                sourcePreview: "https://codeedit.app/"
+                sourcePreview: "https://codeedit.app/",
+                documentation: "Opens CodeEdit's homepage! You can customize how links are handled, this one opens a "
+                + "URL."
             )
         ]
     }

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/MockJumpToDefinitionDelegate.swift

@@ -0,0 +1,70 @@
+//
+//  SuggestionTriggerCharacterModel.swift
+//  CodeEditSourceEditor
+//
+//  Created by Khan Winter on 8/25/25.
+//
+
+import AppKit
+import CodeEditTextView
+import TextStory
+
+/// Triggers the suggestion window when trigger characters are typed.
+/// Designed to be called in the ``TextViewDelegate``'s didReplaceCharacters method.
+///
+/// Was originally a `TextFilter` model, however those are called before text is changed and cursors are updated.
+/// The suggestion model expects up-to-date cursor positions as well as complete text contents. This being
+/// essentially a textview delegate ensures both of those promises are upheld.
+final class SuggestionTriggerCharacterModel {
+    weak var controller: TextViewController?
+    private var lastPosition: NSRange?
+
+    var triggerCharacters: Set<String>? {
+        controller?.configuration.peripherals.codeSuggestionTriggerCharacters
+    }
+
+    func textView(_ textView: TextView, didReplaceContentsIn range: NSRange, with string: String) {
+        guard let controller, let completionDelegate = controller.completionDelegate, let triggerCharacters else {
+            return
+        }
+
+        let mutation = TextMutation(
+            string: string,
+            range: range,
+            limit: textView.textStorage.length
+        )
+        guard mutation.delta >= 0,
+              let lastChar = mutation.string.last else {
+            lastPosition = nil
+            return
+        }
+
+        guard triggerCharacters.contains(String(lastChar)) || lastChar.isNumber || lastChar.isLetter else {
+            lastPosition = nil
+            return
+        }
+
+        let range = NSRange(location: mutation.postApplyRange.max, length: 0)
+        lastPosition = range
+        SuggestionController.shared.cursorsUpdated(
+            textView: controller,
+            delegate: completionDelegate,
+            position: CursorPosition(range: range),
+            presentIfNot: true
+        )
+    }
+
+    func selectionUpdated(_ position: CursorPosition) {
+        guard let controller, let completionDelegate = controller.completionDelegate else {
+            return
+        }
+
+        if lastPosition != position.range {
+            SuggestionController.shared.cursorsUpdated(
+                textView: controller,
+                delegate: completionDelegate,
+                position: position
+            )
+        }
+    }
+}

Sources/CodeEditSourceEditor/CodeSuggestion/Model/SuggestionTriggerCharacterModel.swift

@@ -16,6 +16,7 @@ final class SuggestionViewModel: ObservableObject {
 
     weak var delegate: CodeSuggestionDelegate?
 
+    private var cursorPosition: CursorPosition?
     private var syntaxHighlightedCache: [Int: NSAttributedString] = [:]
 
     func showCompletions(

Sources/CodeEditSourceEditor/CodeSuggestion/Model/SuggestionViewModel.swift

@@ -9,6 +9,8 @@ import AppKit
 import SwiftUI
 
 struct CodeSuggestionLabelView: View {
+    static let HORIZONTAL_PADDING: CGFloat = 13
+
     let suggestion: CodeSuggestionEntry
     let labelColor: NSColor
     let secondaryLabelColor: NSColor
@@ -45,7 +47,7 @@ struct CodeSuggestionLabelView: View {
             }
         }
         .padding(.vertical, 3)
-        .padding(.horizontal, 13)
+        .padding(.horizontal, Self.HORIZONTAL_PADDING)
         .buttonStyle(PlainButtonStyle())
     }
 }

Sources/CodeEditSourceEditor/CodeSuggestion/TableView/CodeSuggestionLabelView.swift

@@ -9,7 +9,7 @@ import AppKit
 
 extension SuggestionController {
     /// Will constrain the window's frame to be within the visible screen
-    public func constrainWindowToScreenEdges(cursorRect: NSRect) {
+    public func constrainWindowToScreenEdges(cursorRect: NSRect, font: NSFont) {
         guard let window = self.window,
               let screenFrame = window.screen?.visibleFrame else {
             return
@@ -18,7 +18,8 @@ extension SuggestionController {
         let windowSize = window.frame.size
         let padding: CGFloat = 22
         var newWindowOrigin = NSPoint(
-            x: cursorRect.origin.x - Self.WINDOW_PADDING,
+            x: cursorRect.origin.x - Self.WINDOW_PADDING
+            - CodeSuggestionLabelView.HORIZONTAL_PADDING - font.pointSize,
             y: cursorRect.origin.y
         )
 

Sources/CodeEditSourceEditor/CodeSuggestion/Window/SuggestionController+Window.swift

@@ -91,7 +91,7 @@ public final class SuggestionController: NSWindowController {
                 self.popover = popover
             } else {
                 self.showWindow(attachedTo: parentWindow)
-                self.constrainWindowToScreenEdges(cursorRect: cursorRect)
+                self.constrainWindowToScreenEdges(cursorRect: cursorRect, font: textView.font)
 
                 if let controller = self.contentViewController as? SuggestionViewController {
                     controller.styleView(using: textView)

Sources/CodeEditSourceEditor/CodeSuggestion/Window/SuggestionController.swift

@@ -82,8 +82,8 @@ extension TextViewController {
         }
         isPostingCursorNotification = false
 
-        if let completionDelegate = completionDelegate, let position = cursorPositions.first {
-            SuggestionController.shared.cursorsUpdated(textView: self, delegate: completionDelegate, position: position)
+        if let position = cursorPositions.first {
+            suggestionTriggerModel.selectionUpdated(position)
         }
     }
 
@@ -96,7 +96,7 @@ extension TextViewController {
                     let linePosition = textView.layoutManager.textLineForIndex(position.start.line - 1) else {
                 return nil
             }
-            if let end = position.end, let endPosition = textView.layoutManager.textLineForIndex(end.line - 1) {
+            if position.end != nil {
                 range = NSRange(
                     location: linePosition.range.location + position.start.column,
                     length: linePosition.range.max

Sources/CodeEditSourceEditor/Controller/TextViewController+Cursor.swift

@@ -24,7 +24,6 @@ extension TextViewController {
         setUpNewlineTabFilters(indentOption: configuration.behavior.indentOption)
         setUpDeletePairFilters(pairs: BracketPairs.allValues)
         setUpDeleteWhitespaceFilter(indentOption: configuration.behavior.indentOption)
-        setUpSuggestionsFilter()
     }
 
     /// Returns a `TextualIndenter` based on available language configuration.
@@ -121,24 +120,4 @@ extension TextViewController {
 
         return true
     }
-
-    func setUpSuggestionsFilter() {
-        textFilters.append(
-            CodeSuggestionTriggerFilter(
-                triggerCharacters: configuration.peripherals.codeSuggestionTriggerCharacters,
-                didTrigger: { [weak self] in
-                    guard let self else { return }
-                    if let completionDelegate = self.completionDelegate,
-                       let position = self.cursorPositions.first {
-                        SuggestionController.shared.cursorsUpdated(
-                            textView: self,
-                            delegate: completionDelegate,
-                            position: position,
-                            presentIfNot: true
-                        )
-                    }
-                }
-            )
-        )
-    }
 }