Text Attachment Support (#93)

### Description

Adds an API for creating "text attachments". Essentially, views that replace ranges of text and act as a single character in typesetting, layout, and selection.

#### Detailed Changes

Text layout consists of two steps:

- Laying out whole lines
- Typesetting line fragments

The changes in this PR mostly consist of changes to the typesetting step. This step breaks down a line of text into fragments that fit into a constrained width. Text attachments are built by making 'runs' of content in that typesetting step.

> These are intentionally kept separate from the text storage. If these modifications were in the storage object, they'd be shared between editors that share storage objects. Putting these in the layout system means that a user can fold lines in one editor, and view them normally in another.

- Text attachments:
  - **New** `TextAttachment` protocol. A generic type that can draw it's contents in a line.
  - **New** `AnyTextAttachment` helps type-erase `any TextAttachment` and has a `range` for CETV to use. Very similar to `AnyHashable` or `AnyView`.
  - **New** `TextAttachmentManager` manages an ordered array of attachments, and manages hiding and showing text lines as needed, as well as invalidating layout when modifications happen.
- `TextLayoutManager` changes:
  - Added a new `determineVisiblePosition` method. This method takes in a line position and returns a new (potentially larger) position by merging lines covered by attachments. This is the foundational method for merging lines that attachments cover.
  - Removing the existing `Iterator`.
  - Added two iterators, `YPositionIterator` and `RangeIterator` that iterate over a range of y positions and text offsets, respectively. These iterators are now used by the `layoutLines` method to merge lines that have attachments and not layout hidden lines.
- Typesetting:
  - `Typesetter.swift` is marked as new, but that's because it's drastically changed.
    - `Typesetter` still performs typesetting on a text line, but it now takes into account attachments. It breaks the line into content runs, then calculates line fragments using those runs and a constrained width.
  - `TypesetContext` and `LineFragmentTypesetContext` represent partial parsing states while typesetting. They're both used once during typesetting and then discarded. Keeping them in their own structs makes `Typesetter` much more readable.
  - `CTLineTypesetData` was previously represented by a tuple, but a struct makes things clearer. It represents layout information received from a `CTTypesetter` for a `CTLine`.
  - Line break suggestion methods moved to a `CTTypesetter` extension. Each method was taking a `typesetter` argument, so moving to an extension makes them more ergonomic.
    - The only change to these methods was a change from passing a `startOffset` to instead pass a `subrange` that the typesetter finds line breaks in.
- `LineFragment`
  - Line fragments now have to manage a series of content runs that can be either attachments or plain text.
  - Drawing methods have been updated to loop over runs and draw them.
  - Position fetching methods now take into account attachments as well as text positions.
- Scroll view listeners - *this could have been a different PR but it's a small change, sorry!*.
  -  Fixed up the way the text view found it's enclosing scroll view, and listens to scroll changes.

#### Testing

- Added typesetting tests for attachments.
- Added layout manager tests.
  - Iteration
  - Invalidation
  - Attachments

### Related Issues

* CodeEditApp/CodeEditSourceEditor#43
* CodeEditApp/CodeEditSourceEditor#287
* CodeEditApp/CodeEdit#1623

### 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

> Demo menu item was a testing menu item, it either adds a demo attachment to the selected range, or removes selected attachments (if any are selected). It's not included in this PR.

To test the changes like in the demo video replace `TextView+Menu.swift` with this:
<details><summary>`TextView+Menu.swift`</summary>
<p>

```swift
//
//  TextView+Menu.swift
//  CodeEditTextView
//
//  Created by Khan Winter on 8/21/23.
//

import AppKit

extension TextView {
    override public func menu(for event: NSEvent) -> NSMenu? {
        guard event.type == .rightMouseDown else { return nil }

        let menu = NSMenu()

        menu.items = [
            NSMenuItem(title: "Cut", action: #selector(cut(_:)), keyEquivalent: "x"),
            NSMenuItem(title: "Copy", action: #selector(copy(_:)), keyEquivalent: "c"),
            NSMenuItem(title: "Paste", action: #selector(paste(_:)), keyEquivalent: "v"),
            NSMenuItem(title: "Attach", action: #selector(toggleAttachmentAtSelection), keyEquivalent: "b")
        ]

        return menu
    }

    class DemoAttachment: TextAttachment {
        var width: CGFloat = 100

        func draw(in context: CGContext, rect: NSRect) {
            context.setFillColor(NSColor.red.cgColor)
            context.fill(rect)
        }
    }

    @objc func toggleAttachmentAtSelection() {
        if layoutManager.attachments.get(
            startingIn: selectedRange()
        ).first?.range.location == selectedRange().location {
            layoutManager.attachments.remove(atOffset: selectedRange().location)
        } else {
            layoutManager.attachments.add(DemoAttachment(), for: selectedRange())
        }
    }
}

```

</p>
</details> 


https://github.com/user-attachments/assets/b178fe13-d5d2-4e3d-aa55-f913df1d6c4b

Author: thecoolwinter

Example/CodeEditTextViewExample/CodeEditTextViewExample.xcodeproj/xcshareddata/xcschemes/CodeEditTextViewExample.xcscheme

@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1620"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES"
+      buildArchitectures = "Automatic">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "6CCDA27C2D306A1B007CD84A"
+               BuildableName = "CodeEditTextViewExample.app"
+               BlueprintName = "CodeEditTextViewExample"
+               ReferencedContainer = "container:CodeEditTextViewExample.xcodeproj">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      shouldAutocreateTestPlan = "YES">
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "6CCDA27C2D306A1B007CD84A"
+            BuildableName = "CodeEditTextViewExample.app"
+            BlueprintName = "CodeEditTextViewExample"
+            ReferencedContainer = "container:CodeEditTextViewExample.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "6CCDA27C2D306A1B007CD84A"
+            BuildableName = "CodeEditTextViewExample.app"
+            BlueprintName = "CodeEditTextViewExample"
+            ReferencedContainer = "container:CodeEditTextViewExample.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>

Example/CodeEditTextViewExample/CodeEditTextViewExample/Documents/CodeEditTextViewExampleDocument.swift

@@ -8,11 +8,11 @@
 import SwiftUI
 import UniformTypeIdentifiers
 
-struct CodeEditTextViewExampleDocument: FileDocument {
-    var text: String
+struct CodeEditTextViewExampleDocument: FileDocument, @unchecked Sendable {
+    var text: NSTextStorage
 
     init(text: String = "") {
-        self.text = text
+        self.text = NSTextStorage(string: text)
     }
 
     static var readableContentTypes: [UTType] {
@@ -25,11 +25,21 @@ struct CodeEditTextViewExampleDocument: FileDocument {
         guard let data = configuration.file.regularFileContents else {
             throw CocoaError(.fileReadCorruptFile)
         }
-        text = String(bytes: data, encoding: .utf8) ?? ""
+        text = try NSTextStorage(
+            data: data,
+            options: [.characterEncoding: NSUTF8StringEncoding, .fileType: NSAttributedString.DocumentType.plain],
+            documentAttributes: nil
+        )
     }
 
     func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapper {
-        let data = Data(text.utf8)
+        let data = try text.data(
+            from: NSRange(location: 0, length: text.length),
+            documentAttributes: [
+                .documentType: NSAttributedString.DocumentType.plain,
+                .characterEncoding: NSUTF8StringEncoding
+            ]
+        )
         return .init(regularFileWithContents: data)
     }
 }

Example/CodeEditTextViewExample/CodeEditTextViewExample/Views/ContentView.swift

@@ -19,7 +19,11 @@ struct ContentView: View {
                 Toggle("Inset Edges", isOn: $enableEdgeInsets)
             }
             Divider()
-            SwiftUITextView(text: $document.text, wrapLines: $wrapLines, enableEdgeInsets: $enableEdgeInsets)
+            SwiftUITextView(
+                text: document.text,
+                wrapLines: $wrapLines,
+                enableEdgeInsets: $enableEdgeInsets
+            )
         }
     }
 }

Example/CodeEditTextViewExample/CodeEditTextViewExample/Views/SwiftUITextView.swift

@@ -10,13 +10,13 @@ import AppKit
 import CodeEditTextView
 
 struct SwiftUITextView: NSViewControllerRepresentable {
-    @Binding var text: String
+    var text: NSTextStorage
     @Binding var wrapLines: Bool
     @Binding var enableEdgeInsets: Bool
 
     func makeNSViewController(context: Context) -> TextViewController {
-        let controller = TextViewController(string: text)
-        context.coordinator.controller = controller
+        let controller = TextViewController(string: "")
+        controller.textView.setTextStorage(text)
         controller.wrapLines = wrapLines
         controller.enableEdgeInsets = enableEdgeInsets
         return controller
@@ -26,39 +26,4 @@ struct SwiftUITextView: NSViewControllerRepresentable {
         nsViewController.wrapLines = wrapLines
         nsViewController.enableEdgeInsets = enableEdgeInsets
     }
-
-    func makeCoordinator() -> Coordinator {
-        Coordinator(text: $text)
-    }
-
-    @MainActor
-    public class Coordinator: NSObject {
-        weak var controller: TextViewController?
-        var text: Binding<String>
-
-        init(text: Binding<String>) {
-            self.text = text
-            super.init()
-
-            NotificationCenter.default.addObserver(
-                self,
-                selector: #selector(textViewDidChangeText(_:)),
-                name: TextView.textDidChangeNotification,
-                object: nil
-            )
-        }
-
-        @objc func textViewDidChangeText(_ notification: Notification) {
-            guard let textView = notification.object as? TextView,
-                  let controller,
-                  controller.textView === textView else {
-                return
-            }
-            text.wrappedValue = textView.string
-        }
-
-        deinit {
-            NotificationCenter.default.removeObserver(self)
-        }
-    }
 }

Sources/CodeEditTextView/Extensions/CTTypesetter+SuggestLineBreak.swift

@@ -0,0 +1,127 @@
+//
+//  CTTypesetter+SuggestLineBreak.swift
+//  CodeEditTextView
+//
+//  Created by Khan Winter on 4/24/25.
+//
+
+import AppKit
+
+extension CTTypesetter {
+    /// Suggest a line break for the given line break strategy.
+    /// - Parameters:
+    ///   - typesetter: The typesetter to use.
+    ///   - strategy: The strategy that determines a valid line break.
+    ///   - startingOffset: Where to start breaking.
+    ///   - constrainingWidth: The available space for the line.
+    /// - Returns: An offset relative to the entire string indicating where to break.
+    func suggestLineBreak(
+        using string: NSAttributedString,
+        strategy: LineBreakStrategy,
+        subrange: NSRange,
+        constrainingWidth: CGFloat
+    ) -> Int {
+        switch strategy {
+        case .character:
+            return suggestLineBreakForCharacter(
+                string: string,
+                startingOffset: subrange.location,
+                constrainingWidth: constrainingWidth
+            )
+        case .word:
+            return suggestLineBreakForWord(
+                string: string,
+                subrange: subrange,
+                constrainingWidth: constrainingWidth
+            )
+        }
+    }
+
+    /// Suggest a line break for the character break strategy.
+    /// - Parameters:
+    ///   - typesetter: The typesetter to use.
+    ///   - startingOffset: Where to start breaking.
+    ///   - constrainingWidth: The available space for the line.
+    /// - Returns: An offset relative to the entire string indicating where to break.
+    private func suggestLineBreakForCharacter(
+        string: NSAttributedString,
+        startingOffset: Int,
+        constrainingWidth: CGFloat
+    ) -> Int {
+        var breakIndex: Int
+        // Check if we need to skip to an attachment
+
+        breakIndex = startingOffset + CTTypesetterSuggestClusterBreak(self, startingOffset, constrainingWidth)
+        guard breakIndex < string.length else {
+            return breakIndex
+        }
+        let substring = string.attributedSubstring(from: NSRange(location: breakIndex - 1, length: 2)).string
+        if substring == LineEnding.carriageReturnLineFeed.rawValue {
+            // Breaking in the middle of the clrf line ending
+            breakIndex += 1
+        }
+
+        return breakIndex
+    }
+
+    /// Suggest a line break for the word break strategy.
+    /// - Parameters:
+    ///   - typesetter: The typesetter to use.
+    ///   - startingOffset: Where to start breaking.
+    ///   - constrainingWidth: The available space for the line.
+    /// - Returns: An offset relative to the entire string indicating where to break.
+    private func suggestLineBreakForWord(
+        string: NSAttributedString,
+        subrange: NSRange,
+        constrainingWidth: CGFloat
+    ) -> Int {
+        var breakIndex = subrange.location + CTTypesetterSuggestClusterBreak(self, subrange.location, constrainingWidth)
+        let isBreakAtEndOfString = breakIndex >= subrange.max
+
+        let isNextCharacterCarriageReturn = checkIfLineBreakOnCRLF(breakIndex, for: string)
+        if isNextCharacterCarriageReturn {
+            breakIndex += 1
+        }
+
+        let canLastCharacterBreak = (breakIndex - 1 > 0 && ensureCharacterCanBreakLine(at: breakIndex - 1, for: string))
+
+        if isBreakAtEndOfString || canLastCharacterBreak {
+            // Breaking either at the end of the string, or on a whitespace.
+            return breakIndex
+        } else if breakIndex - 1 > 0 {
+            // Try to walk backwards until we hit a whitespace or punctuation
+            var index = breakIndex - 1
+
+            while breakIndex - index < 100 && index > subrange.location {
+                if ensureCharacterCanBreakLine(at: index, for: string) {
+                    return index + 1
+                }
+                index -= 1
+            }
+        }
+
+        return breakIndex
+    }
+
+    /// Ensures the character at the given index can break a line.
+    /// - Parameter index: The index to check at.
+    /// - Returns: True, if the character is a whitespace or punctuation character.
+    private func ensureCharacterCanBreakLine(at index: Int, for string: NSAttributedString) -> Bool {
+        let subrange = (string.string as NSString).rangeOfComposedCharacterSequence(at: index)
+        let set = CharacterSet(charactersIn: (string.string as NSString).substring(with: subrange))
+        return set.isSubset(of: .whitespacesAndNewlines) || set.isSubset(of: .punctuationCharacters)
+    }
+
+    /// Check if the break index is on a CRLF (`\r\n`) character, indicating a valid break position.
+    /// - Parameter breakIndex: The index to check in the string.
+    /// - Returns: True, if the break index lies after the `\n` character in a `\r\n` sequence.
+    private func checkIfLineBreakOnCRLF(_ breakIndex: Int, for string: NSAttributedString) -> Bool {
+        guard breakIndex - 1 > 0 && breakIndex + 1 <= string.length else {
+            return false
+        }
+        let substringRange = NSRange(location: breakIndex - 1, length: 2)
+        let substring = string.attributedSubstring(from: substringRange).string
+
+        return substring == LineEnding.carriageReturnLineFeed.rawValue
+    }
+}

Sources/CodeEditTextView/TextLayoutManager/TextAttachments/TextAttachment.swift

@@ -0,0 +1,31 @@
+//
+//  TextAttachment.swift
+//  CodeEditTextView
+//
+//  Created by Khan Winter on 4/24/25.
+//
+
+import AppKit
+
+/// Represents an attachment type. Attachments take up some set width, and draw their contents in a receiver view.
+public protocol TextAttachment: AnyObject {
+    var width: CGFloat { get }
+    func draw(in context: CGContext, rect: NSRect)
+}
+
+/// Type-erasing type for ``TextAttachment`` that also contains range information about the attachment.
+///
+/// This type cannot be initialized outside of `CodeEditTextView`, but will be received when interrogating
+/// the ``TextAttachmentManager``.
+public struct AnyTextAttachment: Equatable {
+    var range: NSRange
+    let attachment: any TextAttachment
+
+    var width: CGFloat {
+        attachment.width
+    }
+
+    public static func == (_ lhs: AnyTextAttachment, _ rhs: AnyTextAttachment) -> Bool {
+        lhs.range == rhs.range && lhs.attachment === rhs.attachment
+    }
+}