Add Ribbon View, Demo Fold Provider, Ribbon Toggles (#315)

### Description

> [!NOTE]
> For reviewers, this is merging into the dev branch. These changes
require the version of CETV in [this
PR](CodeEditApp/CodeEditTextView#93). Please
pull those changes locally and test using that.

> [!NOTE]
> I'll be making some TODOs in the tracking issue #43 for things that
aren't included here. Like the overlapping folds UI issue.

Adds the first version of the code folding ribbon, with a very basic
folding model.

This is mostly a UI change. It includes changes to the gutter, and a new
view for displaying folds. The model and related demo fold provider
should be considered incomplete and only for demo purposes.

This also doesn't implement the hover state yet. Just a very basic
outline of everything.

Things to review:
- New `FoldingRibbonView`
- New `LineFoldingModel`
- Changes in `GutterView`
- Changes to `TextViewController`
- Changes to `CodeEditSourceEditor`

### Related Issues

* #43 

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

Light mode.
![Screenshot 2025-05-07 at 3 22
17 PM](https://github.com/user-attachments/assets/a9b7838f-6bea-4bb4-bd61-b72175c76788)

Dark Mode.
![Screenshot 2025-05-08 at 10 12
45 AM](https://github.com/user-attachments/assets/fb8e3264-71ec-40aa-9d62-7d4a74c15343)

Folds are transparent for scrolling text.
![Screenshot 2025-05-08 at 10 08
35 AM](https://github.com/user-attachments/assets/17a1623c-3e8e-40a5-ace3-6adbe8e13320)

---------

Co-authored-by: Austin Condiff <austin.condiff@gmail.com>

Author: thecoolwinter

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

@@ -27,6 +27,7 @@ struct ContentView: View {
     @State private var settingsIsPresented: Bool = false
     @State private var treeSitterClient = TreeSitterClient()
     @AppStorage("showMinimap") private var showMinimap: Bool = true
+    @AppStorage("showFoldingRibbon") private var showFoldingRibbon: Bool = true
     @State private var indentOption: IndentOption = .spaces(count: 4)
     @AppStorage("reformatAtColumn") private var reformatAtColumn: Int = 80
     @AppStorage("showReformattingGuide") private var showReformattingGuide: Bool = false
@@ -56,7 +57,8 @@ struct ContentView: View {
                 useSystemCursor: useSystemCursor,
                 showMinimap: showMinimap,
                 reformatAtColumn: reformatAtColumn,
-                showReformattingGuide: showReformattingGuide
+                showReformattingGuide: showReformattingGuide,
+                showFoldingRibbon: showFoldingRibbon
             )
             .overlay(alignment: .bottom) {
                 StatusBar(
@@ -71,7 +73,8 @@ struct ContentView: View {
                     showMinimap: $showMinimap,
                     indentOption: $indentOption,
                     reformatAtColumn: $reformatAtColumn,
-                    showReformattingGuide: $showReformattingGuide
+                    showReformattingGuide: $showReformattingGuide,
+                    showFoldingRibbon: $showFoldingRibbon
                 )
             }
             .ignoresSafeArea()

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/ContentView.swift

@@ -26,6 +26,7 @@ struct StatusBar: View {
     @Binding var indentOption: IndentOption
     @Binding var reformatAtColumn: Int
     @Binding var showReformattingGuide: Bool
+    @Binding var showFoldingRibbon: Bool
 
     var body: some View {
         HStack {
@@ -43,6 +44,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 {

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/StatusBar.swift

@@ -17,13 +17,18 @@ let package = Package(
         // A fast, efficient, text view for code.
         .package(
             url: "https://github.com/CodeEditApp/CodeEditTextView.git",
-            from: "0.10.1"
+            from: "0.11.0"
         ),
         // tree-sitter languages
         .package(
             url: "https://github.com/CodeEditApp/CodeEditLanguages.git",
             exact: "0.1.20"
         ),
+        // CodeEditSymbols
+        .package(
+            url: "https://github.com/CodeEditApp/CodeEditSymbols.git",
+            exact: "0.2.3"
+        ),
         // SwiftLint
         .package(
             url: "https://github.com/lukepistrol/SwiftLintPlugin",
@@ -43,7 +48,8 @@ let package = Package(
             dependencies: [
                 "CodeEditTextView",
                 "CodeEditLanguages",
-                "TextFormation"
+                "TextFormation",
+                "CodeEditSymbols"
             ],
             plugins: [
                 .plugin(name: "SwiftLint", package: "SwiftLintPlugin")

Package.resolved

@@ -39,20 +39,22 @@ public struct CodeEditSourceEditor: NSViewControllerRepresentable {
     ///                         the default `TreeSitterClient` highlighter.
     ///   - contentInsets: Insets to use to offset the content in the enclosing scroll view. Leave as `nil` to let the
     ///                    scroll view automatically adjust content insets.
-    ///   - additionalTextInsets: An additional amount to inset the text of the editor by.
+    ///   - additionalTextInsets: A set of extra text insets to indent only *text* content. Does not effect
+    ///                           decorations like the find panel.
     ///   - isEditable: A Boolean value that controls whether the text view allows the user to edit text.
     ///   - isSelectable: A Boolean value that controls whether the text view allows the user to select text. If this
     ///                   value is true, and `isEditable` is false, the editor is selectable but not editable.
     ///   - letterSpacing: The amount of space to use between letters, as a percent. Eg: `1.0` = no space, `1.5` = 1/2 a
     ///                    character's width between characters, etc. Defaults to `1.0`
     ///   - bracketPairEmphasis: The type of highlight to use to highlight bracket pairs.
     ///                           See `BracketPairHighlight` for more information. Defaults to `nil`
-    ///   - useSystemCursor: If true, uses the system cursor on `>=macOS 14`.
+    ///   - useSystemCursor: Use the system cursor instead of the default line cursor. Only available after macOS 14.
     ///   - undoManager: The undo manager for the text view. Defaults to `nil`, which will create a new CEUndoManager
     ///   - coordinators: Any text coordinators for the view to use. See ``TextViewCoordinator`` for more information.
-    ///   - showMinimap: Whether to show the minimap
+    ///   - showMinimap: Toggle the visibility of the minimap.
     ///   - reformatAtColumn: The column to reformat at
     ///   - showReformattingGuide: Whether to show the reformatting guide
+    ///   - showFoldingRibbon: Toggle the visibility of the line folding ribbon.
     public init(
         _ text: Binding<String>,
         language: CodeLanguage,
@@ -77,7 +79,8 @@ public struct CodeEditSourceEditor: NSViewControllerRepresentable {
         coordinators: [any TextViewCoordinator] = [],
         showMinimap: Bool,
         reformatAtColumn: Int,
-        showReformattingGuide: Bool
+        showReformattingGuide: Bool,
+        showFoldingRibbon: Bool
     ) {
         self.text = .binding(text)
         self.language = language
@@ -107,6 +110,7 @@ public struct CodeEditSourceEditor: NSViewControllerRepresentable {
         self.showMinimap = showMinimap
         self.reformatAtColumn = reformatAtColumn
         self.showReformattingGuide = showReformattingGuide
+        self.showFoldingRibbon = showFoldingRibbon
     }
 
     /// Initializes a Text Editor
@@ -127,18 +131,22 @@ public struct CodeEditSourceEditor: NSViewControllerRepresentable {
     ///                         the default `TreeSitterClient` highlighter.
     ///   - contentInsets: Insets to use to offset the content in the enclosing scroll view. Leave as `nil` to let the
     ///                    scroll view automatically adjust content insets.
+    ///   - additionalTextInsets: A set of extra text insets to indent only *text* content. Does not effect
+    ///                           decorations like the find panel.
     ///   - isEditable: A Boolean value that controls whether the text view allows the user to edit text.
     ///   - isSelectable: A Boolean value that controls whether the text view allows the user to select text. If this
     ///                   value is true, and `isEditable` is false, the editor is selectable but not editable.
     ///   - letterSpacing: The amount of space to use between letters, as a percent. Eg: `1.0` = no space, `1.5` = 1/2 a
     ///                    character's width between characters, etc. Defaults to `1.0`
     ///   - bracketPairEmphasis: The type of highlight to use to highlight bracket pairs.
     ///                           See `BracketPairEmphasis` for more information. Defaults to `nil`
+    ///   - useSystemCursor: Use the system cursor instead of the default line cursor. Only available after macOS 14.
     ///   - undoManager: The undo manager for the text view. Defaults to `nil`, which will create a new CEUndoManager
     ///   - coordinators: Any text coordinators for the view to use. See ``TextViewCoordinator`` for more information.
-    ///   - showMinimap: Whether to show the minimap
+    ///   - showMinimap: Toggle the visibility of the minimap.
     ///   - reformatAtColumn: The column to reformat at
     ///   - showReformattingGuide: Whether to show the reformatting guide
+    ///   - showFoldingRibbon: Toggle the visibility of the line folding ribbon.
     public init(
         _ text: NSTextStorage,
         language: CodeLanguage,
@@ -163,7 +171,8 @@ public struct CodeEditSourceEditor: NSViewControllerRepresentable {
         coordinators: [any TextViewCoordinator] = [],
         showMinimap: Bool,
         reformatAtColumn: Int,
-        showReformattingGuide: Bool
+        showReformattingGuide: Bool,
+        showFoldingRibbon: Bool
     ) {
         self.text = .storage(text)
         self.language = language
@@ -193,6 +202,7 @@ public struct CodeEditSourceEditor: NSViewControllerRepresentable {
         self.showMinimap = showMinimap
         self.reformatAtColumn = reformatAtColumn
         self.showReformattingGuide = showReformattingGuide
+        self.showFoldingRibbon = showFoldingRibbon
     }
 
     package var text: TextAPI
@@ -219,6 +229,7 @@ public struct CodeEditSourceEditor: NSViewControllerRepresentable {
     package var showMinimap: Bool
     private var reformatAtColumn: Int
     private var showReformattingGuide: Bool
+    package var showFoldingRibbon: Bool
 
     public typealias NSViewControllerType = TextViewController
 
@@ -247,7 +258,8 @@ public struct CodeEditSourceEditor: NSViewControllerRepresentable {
             coordinators: coordinators,
             showMinimap: showMinimap,
             reformatAtColumn: reformatAtColumn,
-            showReformattingGuide: showReformattingGuide
+            showReformattingGuide: showReformattingGuide,
+            showFoldingRibbon: showFoldingRibbon
         )
         switch text {
         case .binding(let binding):
@@ -336,6 +348,7 @@ public struct CodeEditSourceEditor: NSViewControllerRepresentable {
         controller.contentInsets = contentInsets
         controller.additionalTextInsets = additionalTextInsets
         controller.showMinimap = showMinimap
+        controller.showFoldingRibbon = showFoldingRibbon
 
         if controller.indentOption != indentOption {
             controller.indentOption = indentOption
@@ -397,6 +410,7 @@ public struct CodeEditSourceEditor: NSViewControllerRepresentable {
         controller.showMinimap == showMinimap &&
         controller.reformatAtColumn == reformatAtColumn &&
         controller.showReformattingGuide == showReformattingGuide &&
+        controller.showFoldingRibbon == showFoldingRibbon &&
         areHighlightProvidersEqual(controller: controller, coordinator: coordinator)
     }
 

Package.swift

@@ -11,7 +11,7 @@ import AppKit
 extension TextViewController {
     /// Sets new cursor positions.
     /// - Parameter positions: The positions to set. Lines and columns are 1-indexed.
-    public func setCursorPositions(_ positions: [CursorPosition]) {
+    public func setCursorPositions(_ positions: [CursorPosition], scrollToVisible: Bool = false) {
         if isPostingCursorNotification { return }
         var newSelectedRanges: [NSRange] = []
         for position in positions {
@@ -33,6 +33,10 @@ extension TextViewController {
             }
         }
         textView.selectionManager.setSelectedRanges(newSelectedRanges)
+
+        if scrollToVisible {
+            textView.scrollSelectionToVisible()
+        }
     }
 
     /// Update the ``TextViewController/cursorPositions`` variable with new text selections from the text view.

Sources/CodeEditSourceEditor/CodeEditSourceEditor/CodeEditSourceEditor.swift

@@ -5,10 +5,14 @@
 //  Created by Khan Winter on 3/16/25.
 //
 
-import Foundation
+import AppKit
 import CodeEditTextView
 
 extension TextViewController: FindPanelTarget {
+    var findPanelTargetView: NSView {
+        textView
+    }
+
     func findPanelWillShow(panelHeight: CGFloat) {
         updateContentInsets()
     }
@@ -17,6 +21,10 @@ extension TextViewController: FindPanelTarget {
         updateContentInsets()
     }
 
+    func findPanelModeDidChange(to mode: FindPanelMode) {
+        updateContentInsets()
+    }
+
     var emphasisManager: EmphasisManager? {
         textView?.emphasisManager
     }

Sources/CodeEditSourceEditor/Controller/TextViewController+Cursor.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+FindPanelTarget.swift

@@ -9,6 +9,13 @@ 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 loadView() {
         super.loadView()
 
@@ -106,9 +113,7 @@ extension TextViewController {
             object: scrollView.contentView,
             queue: .main
         ) { [weak self] notification in
-            guard let clipView = notification.object as? NSClipView,
-                  let textView = self?.textView else { return }
-            textView.updatedViewport(self?.scrollView.documentVisibleRect ?? .zero)
+            guard let clipView = notification.object as? NSClipView else { return }
             self?.gutterView.needsDisplay = true
             self?.minimapXConstraint?.constant = clipView.bounds.origin.x
         }
@@ -120,7 +125,6 @@ extension TextViewController {
             object: scrollView.contentView,
             queue: .main
         ) { [weak self] _ in
-            self?.textView.updatedViewport(self?.scrollView.documentVisibleRect ?? .zero)
             self?.gutterView.needsDisplay = true
             self?.emphasisManager?.removeEmphases(for: EmphasisGroup.brackets)
             self?.updateTextInsets()
@@ -220,7 +224,7 @@ extension TextViewController {
             self.findViewController?.showFindPanel()
             return nil
         case (0, "\u{1b}"): // Escape key
-            self.findViewController?.findPanel.dismiss()
+            self.findViewController?.hideFindPanel()
             return nil
         case (_, _):
             return event