Code Folding (CodeEditApp#341)

### Description

Adds a code folding ribbon.

> [!NOTE]
> For reviewers: Most of these changes have been reviewed individually
in separate PRs. This shouldn't require a detailed combing over. If you
can review a few things in particular like: architecture, naming, and
bugs with real use I think those would be the best use of your limited
time.

#### Detailed Changes
- Folding-related changes
- Added `FoldingRibbonView` - A view that draws a set of folding ranges.
This does all the drawing manually to avoid having to manage view reuse,
it does the drawing in the regions macOS designates so it only draws a
small part of the visible ribbon at a time.
- Added `LineFoldProvider` - A protocol for classes to provide fold
information to CodeEditSourceEditor. This takes a line number, range,
depth, and a reference to the text controller and returns a list of
'line info' objects.
- Added `LineIndentationFoldProvider`, an implementation of
`LineFoldProvider` that calculates folds based on the user's indent
setting.
- Added `LineFoldCalculator`, which interfaces with the given
`LineFoldProvider` to calculate new folds. This happens *asynchronously*
and recalculates every so often. It's very fast but stays off the main
thread to avoid ever gumming up the user's typing.
- Added `LineFoldingModel`, which is the glue between the text view,
calculator, and view.
- To display folded folds, we display a `LineFoldPlaceholder` in the
text view. This keeps a reference to the `LineFoldingModel` via a
delegate protocol to tell the model when it's dismissed.

<details><summary>This is a slightly complicated object graph, so I've
added a diagram here</summary>

```mermaid
flowchart TD
    TV["TextView"] -->|Text Updates| LFM["LineFoldingModel"]
    PL["LineFoldPlaceholder"] --> |Placeholder Removed| LFM
    LFM -->|Text Updates| LFC["LineFoldCalculator"]
    LFC -->|LineFoldStorage| LFM
    LFM -->|Storage Updated| FRV["FoldingRibbonView"]
    LFC <--> |Fold Info| LFP["any LineFoldProvider"]
```

</details>

- Gutter View changes
- New property `showFoldingRibbon` toggles the visibility of the folding
ribbon view.
  - The gutter now manages the folding ribbon view as a subview.
- Added an additional padding option on the gutter for the folding
ribbon.
- Makes a slight modification to how it draws line numbers by using a
line iterator in the drawn lines, rather than the 'visible lines'. Uses
less resources when macOS only requests a redraw for a specific rect
rather than the whole gutter.
- Other, related changes
- Modified the minimap. The minimap is now an attachment delegate to the
text view's attachment object. It receives updates to the text view's
attachments and adds a fake attachment to it's own layout manager. This
effectively syncs the text view's attachments to the minimap.
- Renamed `DispatchQueue.syncMainIfNot` to `waitMainIfNot` and updated
it to use a better method for waiting for a dispatched work item.
  - Added an extension to `NSBezierPath` for rounding corners.
- Added a new `NSColor` convenience initializer for creating light and
dark mode colors more easily.
- Moved the font character width calculation from `TextViewController`
to an `NSFont` extension.

### Related Issues

* CodeEditApp#43 

### Checklist

- [x] Folds reflected in minimap.
- [x] Double-click fold expands it.
- [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/25e46ae4-3db5-4f08-8027-1fea9a8e64cb

---------

Co-authored-by: Austin Condiff <[email protected]>

Author: thecoolwinter

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/ContentView.swift

@@ -26,12 +26,14 @@ struct ContentView: View {
     @State private var font: NSFont = NSFont.monospacedSystemFont(ofSize: 12, weight: .medium)
     @AppStorage("wrapLines") private var wrapLines: Bool = true
     @AppStorage("systemCursor") private var useSystemCursor: Bool = false
+
     @State private var indentOption: IndentOption = .spaces(count: 4)
     @AppStorage("reformatAtColumn") private var reformatAtColumn: Int = 80
 
     @AppStorage("showGutter") private var showGutter: Bool = true
     @AppStorage("showMinimap") private var showMinimap: Bool = true
     @AppStorage("showReformattingGuide") private var showReformattingGuide: Bool = false
+    @AppStorage("showFoldingRibbon") private var showFoldingRibbon: Bool = true
     @State private var invisibleCharactersConfig: InvisibleCharactersConfiguration = .empty
     @State private var warningCharacters: Set<UInt16> = []
 
@@ -86,6 +88,7 @@ struct ContentView: View {
                     indentOption: $indentOption,
                     reformatAtColumn: $reformatAtColumn,
                     showReformattingGuide: $showReformattingGuide,
+                    showFoldingRibbon: $showFoldingRibbon
                     invisibles: $invisibleCharactersConfig,
                     warningCharacters: $warningCharacters
                 )

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/StatusBar.swift

@@ -27,6 +27,7 @@ struct StatusBar: View {
     @Binding var indentOption: IndentOption
     @Binding var reformatAtColumn: Int
     @Binding var showReformattingGuide: Bool
+    @Binding var showFoldingRibbon: Bool
     @Binding var invisibles: InvisibleCharactersConfiguration
     @Binding var warningCharacters: Set<UInt16>
 
@@ -47,6 +48,7 @@ struct StatusBar: View {
                 .onChange(of: reformatAtColumn) { _, newValue in
                     reformatAtColumn = max(1, min(200, newValue))
                 }
+                Toggle("Show Folding Ribbon", isOn: $showFoldingRibbon)
                 if #available(macOS 14, *) {
                     Toggle("Use System Cursor", isOn: $useSystemCursor)
                 } else {

Package.resolved

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

Package.swift

@@ -8,8 +8,7 @@
 import Foundation
 
 extension TextViewController: GutterViewDelegate {
-    public func gutterViewWidthDidUpdate(newWidth: CGFloat) {
-        gutterView?.frame.size.width = newWidth
-        textView?.textInsets = textViewInsets
+    public func gutterViewWidthDidUpdate() {
+        updateTextInsets()
     }
 }

Sources/CodeEditSourceEditor/Controller/TextViewController+GutterViewDelegate.swift

@@ -9,6 +9,23 @@ import CodeEditTextView
 import AppKit
 
 extension TextViewController {
+    override public func viewWillAppear() {
+        super.viewWillAppear()
+        // The calculation this causes cannot be done until the view knows it's final position
+        updateTextInsets()
+        minimapView.layout()
+    }
+
+    override public func viewDidAppear() {
+        super.viewDidAppear()
+        textCoordinators.forEach { $0.val?.controllerDidAppear(controller: self) }
+    }
+
+    override public func viewDidDisappear() {
+        super.viewDidDisappear()
+        textCoordinators.forEach { $0.val?.controllerDidDisappear(controller: self) }
+    }
+
     override public func loadView() {
         super.loadView()
 
@@ -17,7 +34,7 @@ extension TextViewController {
 
         gutterView = GutterView(
             configuration: configuration,
-            textView: textView,
+            controller: self,
             delegate: self
         )
         gutterView.updateWidthIfNeeded()
@@ -129,6 +146,7 @@ extension TextViewController {
             self.gutterView.frame.size.height = self.textView.frame.height + 10
             self.gutterView.frame.origin.y = self.textView.frame.origin.y - self.scrollView.contentInsets.top
             self.gutterView.needsDisplay = true
+            self.gutterView.foldingRibbon.needsDisplay = true
             self.reformattingGuideView?.updatePosition(in: self)
             self.scrollView.needsLayout = true
         }

Sources/CodeEditSourceEditor/Controller/TextViewController+LoadView.swift renamed to Sources/CodeEditSourceEditor/Controller/TextViewController+Lifecycle.swift

@@ -13,7 +13,7 @@ extension TextViewController {
         // swiftlint:disable:next force_cast
         let paragraph = NSParagraphStyle.default.mutableCopy() as! NSMutableParagraphStyle
         paragraph.tabStops.removeAll()
-        paragraph.defaultTabInterval = CGFloat(tabWidth) * fontCharWidth
+        paragraph.defaultTabInterval = CGFloat(tabWidth) * font.charWidth
         return paragraph
     }
 

Sources/CodeEditSourceEditor/Controller/TextViewController+StyleViews.swift

@@ -11,23 +11,6 @@ import TextFormation
 import TextStory
 
 extension TextViewController {
-
-    internal enum BracketPairs {
-        static let allValues: [(String, String)] = [
-            ("{", "}"),
-            ("[", "]"),
-            ("(", ")"),
-            ("\"", "\""),
-            ("'", "'")
-        ]
-
-        static let emphasisValues: [(String, String)] = [
-            ("{", "}"),
-            ("[", "]"),
-            ("(", ")")
-        ]
-    }
-
     // MARK: - Filter Configuration
 
     /// Initializes any filters for text editing.

Sources/CodeEditSourceEditor/Controller/TextViewController+TextFormation.swift

@@ -48,6 +48,9 @@ public class TextViewController: NSViewController {
     var localEvenMonitor: Any?
     var isPostingCursorNotification: Bool = false
 
+    /// A default `NSParagraphStyle` with a set `lineHeight`
+    lazy var paragraphStyle: NSMutableParagraphStyle = generateParagraphStyle()
+
     // MARK: - Public Variables
 
     /// Passthrough value for the `textView`s string
@@ -170,23 +173,23 @@ public class TextViewController: NSViewController {
     /// This will be `nil` if another highlighter provider is passed to the source editor.
     internal(set) public var treeSitterClient: TreeSitterClient?
 
-    package var fontCharWidth: CGFloat { (" " as NSString).size(withAttributes: [.font: font]).width }
+    var foldProvider: LineFoldProvider
 
     /// Filters used when applying edits..
-    internal var textFilters: [TextFormation.Filter] = []
+    var textFilters: [TextFormation.Filter] = []
 
-    internal var cancellables = Set<AnyCancellable>()
+    var cancellables = Set<AnyCancellable>()
 
     /// The trailing inset for the editor. Grows when line wrapping is disabled or when the minimap is shown.
-    package var textViewTrailingInset: CGFloat {
+    var textViewTrailingInset: CGFloat {
         // See https://github.com/CodeEditApp/CodeEditTextView/issues/66
         // wrapLines ? 1 : 48
         (minimapView?.isHidden ?? false) ? 0 : (minimapView?.frame.width ?? 0.0)
     }
 
-    package var textViewInsets: HorizontalEdgeInsets {
+    var textViewInsets: HorizontalEdgeInsets {
         HorizontalEdgeInsets(
-            left: showGutter ? gutterView.gutterWidth : 0.0,
+            left: showGutter ? gutterView.frame.width : 0.0,
             right: textViewTrailingInset
         )
     }
@@ -199,13 +202,15 @@ public class TextViewController: NSViewController {
         configuration: SourceEditorConfiguration,
         cursorPositions: [CursorPosition],
         highlightProviders: [HighlightProviding] = [TreeSitterClient()],
+        foldProvider: LineFoldProvider? = nil,
         undoManager: CEUndoManager? = nil,
         coordinators: [TextViewCoordinator] = []
     ) {
         self.language = language
         self.configuration = configuration
         self.cursorPositions = cursorPositions
         self.highlightProviders = highlightProviders
+        self.foldProvider = foldProvider ?? LineIndentationFoldProvider()
         self._undoManager = undoManager
         self.invisibleCharactersCoordinator = InvisibleCharactersCoordinator(configuration: configuration)
 
@@ -249,28 +254,6 @@ public class TextViewController: NSViewController {
         self.gutterView.setNeedsDisplay(self.gutterView.frame)
     }
 
-    // MARK: Paragraph Style
-
-    /// A default `NSParagraphStyle` with a set `lineHeight`
-    package lazy var paragraphStyle: NSMutableParagraphStyle = generateParagraphStyle()
-
-    override public func viewWillAppear() {
-        super.viewWillAppear()
-        // The calculation this causes cannot be done until the view knows it's final position
-        updateTextInsets()
-        minimapView.layout()
-    }
-
-    override public func viewDidAppear() {
-        super.viewDidAppear()
-        textCoordinators.forEach { $0.val?.controllerDidAppear(controller: self) }
-    }
-
-    override public func viewDidDisappear() {
-        super.viewDidDisappear()
-        textCoordinators.forEach { $0.val?.controllerDidDisappear(controller: self) }
-    }
-
     deinit {
         if let highlighter {
             textView.removeStorageDelegate(highlighter)

Sources/CodeEditSourceEditor/Controller/TextViewController.swift

@@ -0,0 +1,29 @@
+//
+//  BracketPairs.swift
+//  CodeEditSourceEditor
+//
+//  Created by Khan Winter on 6/5/25.
+//
+
+enum BracketPairs {
+    static let allValues: [(String, String)] = [
+        ("{", "}"),
+        ("[", "]"),
+        ("(", ")"),
+        ("\"", "\""),
+        ("'", "'")
+    ]
+
+    static let emphasisValues: [(String, String)] = [
+        ("{", "}"),
+        ("[", "]"),
+        ("(", ")")
+    ]
+
+    /// Checks if the given string is a matchable emphasis string.
+    /// - Parameter potentialMatch: The string to check for matches.
+    /// - Returns: True if a match was found with either start or end bracket pairs.
+    static func matches(_ potentialMatch: String) -> Bool {
+        allValues.contains(where: { $0.0 == potentialMatch || $0.1 == potentialMatch })
+    }
+}