Document Adding a Parameter, Finish Merge Invisible Chars API

Author: thecoolwinter

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/ContentView.swift

@@ -30,7 +30,8 @@ struct ContentView: View {
     @AppStorage("showGutter") private var showGutter: Bool = true
     @AppStorage("showMinimap") private var showMinimap: Bool = true
     @AppStorage("showReformattingGuide") private var showReformattingGuide: Bool = false
-    @State private var invisibleCharactersConfig: InvisibleCharactersConfig = .empty
+    @State private var invisibleCharactersConfig: InvisibleCharactersConfiguration = .empty
+    @State private var warningCharacters: Set<UInt16> = []
 
     @State private var isInLongParse = false
     @State private var settingsIsPresented: Bool = false
@@ -61,7 +62,9 @@ struct ContentView: View {
                     peripherals: .init(
                         showGutter: showGutter,
                         showMinimap: showMinimap,
-                        showReformattingGuide: showReformattingGuide
+                        showReformattingGuide: showReformattingGuide,
+                        invisibleCharactersConfiguration: invisibleCharactersConfig,
+                        warningCharacters: warningCharacters
                     )
                 ),
                 cursorPositions: $cursorPositions
@@ -81,7 +84,8 @@ struct ContentView: View {
                     indentOption: $indentOption,
                     reformatAtColumn: $reformatAtColumn,
                     showReformattingGuide: $showReformattingGuide,
-                    invisibles: $invisibleCharactersConfig
+                    invisibles: $invisibleCharactersConfig,
+                    warningCharacters: $warningCharacters
                 )
             }
             .ignoresSafeArea()

Example/CodeEditSourceEditorExample/CodeEditSourceEditorExample/Views/StatusBar.swift

@@ -27,7 +27,8 @@ struct StatusBar: View {
     @Binding var indentOption: IndentOption
     @Binding var reformatAtColumn: Int
     @Binding var showReformattingGuide: Bool
-    @Binding var invisibles: InvisibleCharactersConfig
+    @Binding var invisibles: InvisibleCharactersConfiguration
+    @Binding var warningCharacters: Set<UInt16>
 
     var body: some View {
         HStack {
@@ -63,16 +64,16 @@ struct StatusBar: View {
                         "Warning Characters",
                         isOn: Binding(
                             get: {
-                                !invisibles.warningCharacters.isEmpty
+                                !warningCharacters.isEmpty
                             },
                             set: { newValue in
                                 // In this example app, we only add one character
                                 // For real apps, consider providing a table where users can add UTF16
                                 // char codes to warn about, as well as a set of good defaults.
                                 if newValue {
-                                    invisibles.warningCharacters.insert(0x200B) // zero-width space
+                                    warningCharacters.insert(0x200B) // zero-width space
                                 } else {
-                                    invisibles.warningCharacters.removeAll()
+                                    warningCharacters.removeAll()
                                 }
                             }
                         )

Sources/CodeEditSourceEditor/Controller/TextViewController.swift

@@ -32,6 +32,10 @@ public class TextViewController: NSViewController {
     /// The reformatting guide view
     var reformattingGuideView: ReformattingGuideView!
 
+    /// Middleman between the text view to our invisible characters config, with knowledge of things like the
+    ///  /// user's theme and indent option to help correctly draw invisible character placeholders.
+    var invisibleCharactersCoordinator: InvisibleCharactersCoordinator
+
     var minimapXConstraint: NSLayoutConstraint?
 
     var _undoManager: CEUndoManager!
@@ -140,6 +144,17 @@ public class TextViewController: NSViewController {
     /// Toggle the visibility of the reformatting guide in the editor.
     public var showReformattingGuide: Bool { configuration.peripherals.showReformattingGuide }
 
+    /// Configuration for drawing invisible characters.
+    ///
+    /// See ``InvisibleCharactersConfiguration`` for more details.
+    public var invisibleCharactersConfiguration: InvisibleCharactersConfiguration {
+        configuration.peripherals.invisibleCharactersConfiguration
+    }
+
+    /// Indicates characters that the user may not have meant to insert, such as a zero-width space: `(0x200D)` or a
+    /// non-standard quote character: `“ (0x201C)`.
+    public var warningCharacters: Set<UInt16> { configuration.peripherals.warningCharacters }
+
     // MARK: - Internal Variables
 
     var textCoordinators: [WeakCoordinator] = []
@@ -177,17 +192,18 @@ public class TextViewController: NSViewController {
     public init(
         string: String,
         language: CodeLanguage,
-        config: SourceEditorConfiguration,
+        configuration: SourceEditorConfiguration,
         cursorPositions: [CursorPosition],
         highlightProviders: [HighlightProviding] = [TreeSitterClient()],
         undoManager: CEUndoManager? = nil,
         coordinators: [TextViewCoordinator] = []
     ) {
         self.language = language
-        self.configuration = config
+        self.configuration = configuration
         self.cursorPositions = cursorPositions
         self.highlightProviders = highlightProviders
         self._undoManager = undoManager
+        self.invisibleCharactersCoordinator = InvisibleCharactersCoordinator(configuration: configuration)
 
         super.init(nibName: nil, bundle: nil)
 

…aracters/InvisibleCharactersConfig.swift …s/InvisibleCharactersConfiguration.swiftSources/CodeEditSourceEditor/InvisibleCharacters/InvisibleCharactersConfig.swift renamed to Sources/CodeEditSourceEditor/InvisibleCharacters/InvisibleCharactersConfiguration.swift Sources/CodeEditSourceEditor/InvisibleCharacters/InvisibleCharactersConfig.swift renamed to Sources/CodeEditSourceEditor/InvisibleCharacters/InvisibleCharactersConfiguration.swift

@@ -1,5 +1,5 @@
 //
-//  InvisibleCharactersConfig.swift
+//  InvisibleCharactersConfiguration.swift
 //  CodeEditSourceEditor
 //
 //  Created by Khan Winter on 6/11/25.
@@ -9,10 +9,10 @@
 ///
 /// Enable specific categories using the ``showSpaces``, ``showTabs``, and ``showLineEndings`` toggles. Customize
 /// drawing further with the ``spaceReplacement`` and family variables.
-public struct InvisibleCharactersConfig: Equatable, Hashable, Sendable, Codable {
+public struct InvisibleCharactersConfiguration: Equatable, Hashable, Sendable, Codable {
     /// An empty configuration.
-    public static var empty: InvisibleCharactersConfig {
-        InvisibleCharactersConfig(showSpaces: false, showTabs: false, showLineEndings: false)
+    public static var empty: InvisibleCharactersConfiguration {
+        InvisibleCharactersConfiguration(showSpaces: false, showTabs: false, showLineEndings: false)
     }
 
     /// Set to true to draw spaces with a dot.

Sources/CodeEditSourceEditor/InvisibleCharacters/InvisibleCharactersCoordinator.swift

@@ -19,7 +19,7 @@ import CodeEditTextView
 /// theme, or font are updated, this object will tell the text view to clear it's cache. Keep updates to a minimum to
 /// retain as much cached data as possible.
 final class InvisibleCharactersCoordinator: InvisibleCharactersDelegate {
-    var config: InvisibleCharactersConfig {
+    var configuration: InvisibleCharactersConfiguration {
         didSet {
             updateTriggerCharacters()
         }
@@ -60,14 +60,24 @@ final class InvisibleCharactersCoordinator: InvisibleCharactersDelegate {
     /// The set of characters the text view should trigger a call to ``invisibleStyle`` for.
     var triggerCharacters: Set<UInt16> = []
 
+    convenience init(configuration: SourceEditorConfiguration) {
+        self.init(
+            configuration: configuration.peripherals.invisibleCharactersConfiguration,
+            warningCharacters: configuration.peripherals.warningCharacters,
+            indentOption: configuration.behavior.indentOption,
+            theme: configuration.appearance.theme,
+            font: configuration.appearance.font
+        )
+    }
+
     init(
-        config: InvisibleCharactersConfig,
+        configuration: InvisibleCharactersConfiguration,
         warningCharacters: Set<UInt16>,
         indentOption: IndentOption,
         theme: EditorTheme,
         font: NSFont
     ) {
-        self.config = config
+        self.configuration = configuration
         self.warningCharacters = warningCharacters
         self.indentOption = indentOption
         self.theme = theme
@@ -83,7 +93,7 @@ final class InvisibleCharactersCoordinator: InvisibleCharactersDelegate {
     }
 
     private func updateTriggerCharacters() {
-        triggerCharacters = config.triggerCharacters().union(warningCharacters)
+        triggerCharacters = configuration.triggerCharacters().union(warningCharacters)
     }
 
     /// Determines if the textview should clear cached styles.
@@ -103,62 +113,62 @@ final class InvisibleCharactersCoordinator: InvisibleCharactersDelegate {
     /// often and is cached in ``emphasizedFont``.
     func invisibleStyle(for character: UInt16, at range: NSRange, lineRange: NSRange) -> InvisibleCharacterStyle? {
         switch character {
-        case InvisibleCharactersConfig.Symbols.space:
+        case InvisibleCharactersConfiguration.Symbols.space:
             return spacesStyle(range: range, lineRange: lineRange)
-        case InvisibleCharactersConfig.Symbols.tab:
+        case InvisibleCharactersConfiguration.Symbols.tab:
             return tabStyle()
-        case InvisibleCharactersConfig.Symbols.carriageReturn:
+        case InvisibleCharactersConfiguration.Symbols.carriageReturn:
             return carriageReturnStyle()
-        case InvisibleCharactersConfig.Symbols.lineFeed:
+        case InvisibleCharactersConfiguration.Symbols.lineFeed:
             return lineFeedStyle()
-        case InvisibleCharactersConfig.Symbols.paragraphSeparator:
+        case InvisibleCharactersConfiguration.Symbols.paragraphSeparator:
             return paragraphSeparatorStyle()
-        case InvisibleCharactersConfig.Symbols.lineSeparator:
+        case InvisibleCharactersConfiguration.Symbols.lineSeparator:
             return lineSeparatorStyle()
         default:
             return warningCharacterStyle(for: character)
         }
     }
 
     private func spacesStyle(range: NSRange, lineRange: NSRange) -> InvisibleCharacterStyle? {
-        guard config.showSpaces else { return nil }
+        guard configuration.showSpaces else { return nil }
         let locationInLine = range.location - lineRange.location
         let shouldBold = locationInLine % indentOption.charCount == indentOption.charCount - 1
         return .replace(
-            replacementCharacter: config.spaceReplacement,
+            replacementCharacter: configuration.spaceReplacement,
             color: invisibleColor,
             font: shouldBold ? emphasizedFont : font
         )
     }
 
     private func tabStyle() -> InvisibleCharacterStyle? {
-        guard config.showTabs else { return nil }
-        return .replace(replacementCharacter: config.tabReplacement, color: invisibleColor, font: font)
+        guard configuration.showTabs else { return nil }
+        return .replace(replacementCharacter: configuration.tabReplacement, color: invisibleColor, font: font)
     }
 
     private func carriageReturnStyle() -> InvisibleCharacterStyle? {
-        guard config.showLineEndings else { return nil }
-        return .replace(replacementCharacter: config.carriageReturnReplacement, color: invisibleColor, font: font)
+        guard configuration.showLineEndings else { return nil }
+        return .replace(replacementCharacter: configuration.carriageReturnReplacement, color: invisibleColor, font: font)
     }
 
     private func lineFeedStyle() -> InvisibleCharacterStyle? {
-        guard config.showLineEndings else { return nil }
-        return .replace(replacementCharacter: config.lineFeedReplacement, color: invisibleColor, font: font)
+        guard configuration.showLineEndings else { return nil }
+        return .replace(replacementCharacter: configuration.lineFeedReplacement, color: invisibleColor, font: font)
     }
 
     private func paragraphSeparatorStyle() -> InvisibleCharacterStyle? {
-        guard config.showLineEndings else { return nil }
+        guard configuration.showLineEndings else { return nil }
         return .replace(
-            replacementCharacter: config.paragraphSeparatorReplacement,
+            replacementCharacter: configuration.paragraphSeparatorReplacement,
             color: invisibleColor,
             font: font
         )
     }
 
     private func lineSeparatorStyle() -> InvisibleCharacterStyle? {
-        guard config.showLineEndings else { return nil }
+        guard configuration.showLineEndings else { return nil }
         return .replace(
-            replacementCharacter: config.lineSeparatorReplacement,
+            replacementCharacter: configuration.lineSeparatorReplacement,
             color: invisibleColor,
             font: font
         )

Sources/CodeEditSourceEditor/SourceEditor/SourceEditor.swift

@@ -89,7 +89,7 @@ public struct SourceEditor: NSViewControllerRepresentable {
         let controller = TextViewController(
             string: "",
             language: language,
-            config: configuration,
+            configuration: configuration,
             cursorPositions: cursorPositions.wrappedValue,
             highlightProviders: context.coordinator.highlightProviders,
             undoManager: undoManager,

Sources/CodeEditSourceEditor/SourceEditorConfiguration/SourceEditorConfiguration+Peripherals.swift

@@ -16,14 +16,27 @@ extension SourceEditorConfiguration {
         /// Whether to show the reformatting guide.
         public var showReformattingGuide: Bool
 
+        /// Configuration for drawing invisible characters.
+        ///
+        /// See ``InvisibleCharactersConfiguration`` for more details.
+        public var invisibleCharactersConfiguration: InvisibleCharactersConfiguration
+
+        /// Indicates characters that the user may not have meant to insert, such as a zero-width space: `(0x200D)` or a
+        /// non-standard quote character: `“ (0x201C)`.
+        public var warningCharacters: Set<UInt16>
+
         public init(
             showGutter: Bool = true,
             showMinimap: Bool = true,
-            showReformattingGuide: Bool = false
+            showReformattingGuide: Bool = false,
+            invisibleCharactersConfiguration: InvisibleCharactersConfiguration = .empty,
+            warningCharacters: Set<UInt16> = []
         ) {
             self.showGutter = showGutter
             self.showMinimap = showMinimap
             self.showReformattingGuide = showReformattingGuide
+            self.invisibleCharactersConfiguration = invisibleCharactersConfiguration
+            self.warningCharacters = warningCharacters
         }
 
         @MainActor
@@ -45,6 +58,14 @@ extension SourceEditorConfiguration {
                 controller.reformattingGuideView.updatePosition(in: controller)
             }
 
+            if oldConfig?.invisibleCharactersConfiguration != invisibleCharactersConfiguration {
+                controller.invisibleCharactersCoordinator.configuration = invisibleCharactersConfiguration
+            }
+
+            if oldConfig?.warningCharacters != warningCharacters {
+                controller.invisibleCharactersCoordinator.warningCharacters = warningCharacters
+            }
+
             if shouldUpdateInsets && controller.scrollView != nil { // Check for view existence
                 controller.updateContentInsets()
                 controller.updateTextInsets()

Sources/CodeEditSourceEditor/SourceEditorConfiguration/SourceEditorConfiguration.swift

@@ -7,6 +7,31 @@
 
 import AppKit
 
+/// # Dev Note
+///
+/// If you're looking to **add a parameter**, make sure you check these off:
+/// - Determine what category it should go in. If what your adding changes often during editing (like cursor positions),
+///   *it doesn't belong here*. These should be configurable, but (mostly) constant options (like the user's font).
+/// - Add the parameter as a *public, mutable, variable* on that category. If it should have a default value, add it
+///   to the variable.
+/// - Add the parameter to that category's initializer, if it should have a default value, add it here too.
+/// - Add a public variable to `TextViewController` in the "Config Helpers" mark with the same name and type.
+///   The variable should be a passthrough variable to the configuration object. Eg:
+///   ```swift
+///   // in config:
+///   var myVariable: Bool
+///
+///   // in TextViewController
+///   public var myVariable: Bool { configuration.category.myVariable }
+///   ```
+/// - Add a new case to the category's `didSetOnController` method. You should check if the parameter has changed, and
+///   update the text view controller as necessary to reflect the updated configuration.
+/// - Add documentation in:
+///   - The variable in the category.
+///   - The category initializer.
+///   - The passthrough variable in `TextViewController`.
+
+
 /// Configuration object for the ``SourceEditor``. Determines appearance, behavior, layout and what features are
 /// enabled (peripherals).
 ///