Jump To Definition (#348)

### Description

Adds jump to definition, including a new key command (control-command-J)
to initiate a jump, and an interaction (command + mouse click). The
destination(s) for a jump is provided via a new object protocol,
provided via the SwiftUI API. The popover presented when multiple links
are present reuses the completion window, with a slight modification so
that it appears as a popover with an arrow rather than a floating
window.

Detailed changes:
- Numerous fixes and improvements to the `SuggestionController` and
`SuggestionViewController`, making them work when presented as a
popover, as well as some resizing bugs.
- New `CodeSuggestionPreviewView`. Displays preview information for a
code suggestion, including a syntax-highlighted source preview,
documentation, and a path component.
- This only appears when one of the three potential information is
available, otherwise it is hidden.
- This view is a visual effect view, so it will inherit the style of the
suggestion controller from the user's theme with a slight tint.
- New `JumpToDefinitionModel` manages the mouse interaction, as well as
providing the layer between the jump delegate and the code suggestion
window.
- New `JumpToDefinitionDelegate` protocol defines how the editor can use
the delegate object to query links and open them once selected.

### Related Issues

* CodeEditApp/CodeEdit#1902

### 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/81d5b24c-6332-4a33-8d2a-8f637bec3bce

---------

Co-authored-by: Abe M <[email protected]>
Co-authored-by: Wesley de Groot <[email protected]>

Author: 3 people

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample.xcodeproj/project.pbxproj

@@ -20,6 +20,7 @@
 		6C1365462B8A7F2D004A1D18 /* LanguagePicker.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6C1365452B8A7F2D004A1D18 /* LanguagePicker.swift */; };
 		6C1365482B8A7FBF004A1D18 /* EditorTheme+Default.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6C1365472B8A7FBF004A1D18 /* EditorTheme+Default.swift */; };
 		6C13654D2B8A821E004A1D18 /* NSColor+Hex.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6C13654C2B8A821E004A1D18 /* NSColor+Hex.swift */; };
+		6C730A042E32CA2A00FE1F32 /* MockJumpToDefinitionDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6C730A032E32CA2A00FE1F32 /* MockJumpToDefinitionDelegate.swift */; };
 		6C8B564C2E3018CC00DC3F29 /* MockCompletionDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6C8B564B2E3018CC00DC3F29 /* MockCompletionDelegate.swift */; };
 		6CF31D4E2DB6A252006A77FD /* StatusBar.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6CF31D4D2DB6A252006A77FD /* StatusBar.swift */; };
 /* End PBXBuildFile section */
@@ -39,6 +40,7 @@
 		6C1365452B8A7F2D004A1D18 /* LanguagePicker.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = LanguagePicker.swift; sourceTree = "<group>"; };
 		6C1365472B8A7FBF004A1D18 /* EditorTheme+Default.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "EditorTheme+Default.swift"; sourceTree = "<group>"; };
 		6C13654C2B8A821E004A1D18 /* NSColor+Hex.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "NSColor+Hex.swift"; sourceTree = "<group>"; };
+		6C730A032E32CA2A00FE1F32 /* MockJumpToDefinitionDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MockJumpToDefinitionDelegate.swift; sourceTree = "<group>"; };
 		6C8B564B2E3018CC00DC3F29 /* MockCompletionDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MockCompletionDelegate.swift; sourceTree = "<group>"; };
 		6CF31D4D2DB6A252006A77FD /* StatusBar.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = StatusBar.swift; sourceTree = "<group>"; };
 /* End PBXFileReference section */
@@ -123,6 +125,7 @@
 				6CF31D4D2DB6A252006A77FD /* StatusBar.swift */,
 				6C1365452B8A7F2D004A1D18 /* LanguagePicker.swift */,
 				1CB30C392DAA1C28008058A7 /* IndentPicker.swift */,
+				6C730A032E32CA2A00FE1F32 /* MockJumpToDefinitionDelegate.swift */,
 			);
 			path = Views;
 			sourceTree = "<group>";
@@ -212,6 +215,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				6C730A042E32CA2A00FE1F32 /* MockJumpToDefinitionDelegate.swift in Sources */,
 				6C1365482B8A7FBF004A1D18 /* EditorTheme+Default.swift in Sources */,
 				6C13654D2B8A821E004A1D18 /* NSColor+Hex.swift in Sources */,
 				6C1365302B8A7B94004A1D18 /* CodeEditSourceEditorExampleDocument.swift in Sources */,

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

@@ -23,6 +23,7 @@ struct ContentView: View {
         cursorPositions: [CursorPosition(line: 1, column: 1)]
     )
     @StateObject private var suggestions: MockCompletionDelegate = MockCompletionDelegate()
+    @StateObject private var jumpToDefinition: MockJumpToDefinitionDelegate = MockJumpToDefinitionDelegate()
 
     @State private var font: NSFont = NSFont.monospacedSystemFont(ofSize: 12, weight: .medium)
     @AppStorage("wrapLines") private var wrapLines: Bool = true
@@ -73,7 +74,8 @@ struct ContentView: View {
                     )
                 ),
                 state: $editorState,
-                completionDelegate: suggestions
+                completionDelegate: suggestions,
+                jumpToDefinitionDelegate: jumpToDefinition
             )
             .overlay(alignment: .bottom) {
                 StatusBar(

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/ContentView.swift

@@ -48,15 +48,18 @@ class MockCompletionDelegate: CodeSuggestionDelegate, ObservableObject {
     class Suggestion: CodeSuggestionEntry {
         var label: String
         var detail: String?
-        var pathComponents: [String]? { nil }
-        var targetPosition: CursorPosition? { nil }
-        var sourcePreview: String? { nil }
+        var pathComponents: [String]?
+        var targetPosition: CursorPosition? = CursorPosition(line: 10, column: 20)
+        var sourcePreview: String?
         var image: Image = Image(systemName: "dot.square.fill")
         var imageColor: Color = .gray
         var deprecated: Bool = false
 
-        init(text: String) {
+        init(text: String, detail: String?, sourcePreview: String?, pathComponents: [String]?) {
             self.label = text
+            self.detail = detail
+            self.sourcePreview = sourcePreview
+            self.pathComponents = pathComponents
         }
     }
 
@@ -67,7 +70,14 @@ class MockCompletionDelegate: CodeSuggestionDelegate, ObservableObject {
             let randomString = (0..<Int.random(in: 1..<text.count)).map {
                 text[$0]
             }.shuffled().joined(separator: " ")
-            suggestions.append(Suggestion(text: randomString))
+            suggestions.append(
+                Suggestion(
+                    text: randomString,
+                    detail: text.randomElement()!,
+                    sourcePreview: randomString,
+                    pathComponents: (0..<Int.random(in: 0..<10)).map { text[$0] }
+                )
+            )
         }
         return suggestions
     }
@@ -103,10 +113,12 @@ class MockCompletionDelegate: CodeSuggestionDelegate, ObservableObject {
         textView: TextViewController,
         cursorPosition: CursorPosition?
     ) {
-        guard let suggestion = item as? Suggestion else {
+        guard let suggestion = item as? Suggestion, let cursorPosition else {
             return
         }
         textView.textView.undoManager?.beginUndoGrouping()
+        textView.textView.selectionManager.setSelectedRange(cursorPosition.range)
+
         textView.textView.insertText(suggestion.label)
         textView.textView.undoManager?.endUndoGrouping()
     }

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/MockCompletionDelegate.swift

@@ -0,0 +1,34 @@
+//
+//  MockJumpToDefinitionDelegate.swift
+//  CodeEditSourceEditorExample
+//
+//  Created by Khan Winter on 7/24/25.
+//
+
+import AppKit
+import CodeEditSourceEditor
+
+final class MockJumpToDefinitionDelegate: JumpToDefinitionDelegate, ObservableObject {
+    func queryLinks(forRange range: NSRange, textView: TextViewController) async -> [JumpToDefinitionLink]? {
+        [
+            JumpToDefinitionLink(
+                url: nil,
+                targetRange: CursorPosition(line: 0, column: 10),
+                typeName: "Start of Document",
+                sourcePreview: "// Comment at start"
+            ),
+            JumpToDefinitionLink(
+                url: URL(string: "https://codeedit.app/"),
+                targetRange: CursorPosition(line: 1024, column: 10),
+                typeName: "CodeEdit Website",
+                sourcePreview: "https://codeedit.app/"
+            )
+        ]
+    }
+
+    func openLink(link: JumpToDefinitionLink) {
+        if let url = link.url {
+            NSWorkspace.shared.open(url)
+        }
+    }
+}

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/MockJumpToDefinitionDelegate.swift

@@ -211,6 +211,7 @@ struct StatusBar: View {
         }
 
         // When there's a single cursor, display the line and column.
-        return "Line: \(cursorPositions[0].line)  Col: \(cursorPositions[0].column) Range: \(cursorPositions[0].range)"
+        // swiftlint:disable:next line_length
+        return "Line: \(cursorPositions[0].start.line)  Col: \(cursorPositions[0].start.column) Range: \(cursorPositions[0].range)"
     }
 }

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/StatusBar.swift

@@ -17,7 +17,7 @@ let package = Package(
         // A fast, efficient, text view for code.
         .package(
             url: "https://github.com/CodeEditApp/CodeEditTextView.git",
-            from: "0.12.0"
+            from: "0.12.1"
         ),
         // tree-sitter languages
         .package(

Package.resolved

@@ -5,6 +5,7 @@
 //  Created by Abe Malla on 12/26/24.
 //
 
+@MainActor
 public protocol CodeSuggestionDelegate: AnyObject {
     func completionTriggerCharacters() -> Set<String>
 

Package.swift

@@ -12,6 +12,7 @@ import SwiftUI
 public protocol CodeSuggestionEntry {
     var label: String { get }
     var detail: String? { get }
+    var documentation: String? { get }
 
     /// Leave as `nil` if the link is in the same document.
     var pathComponents: [String]? { get }