Add Letter Spacing (#174)

### Description

Adds a `letterSpacing` parameter that determines the amount of space
between characters. The parameter is a multiplier of the font's
character width so `1.0` indicates no space, `2.0` indicates a full
character width's space. This is exactly as described in #153.

In detail:
- The letter spacing parameter modifies a stored `kern` variable that is
used for all default attributes.

This PR also adds documentation for a couple undocumented parameters in
the initializer and moves `lineHeight` into the `STTextViewController`
initializer for a cleaner `CodeEditTextView`.

### Related Issues

* closes #153 

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

The below recording shows a placeholder settings adjusting the letter
spacing, as well as the spacing being applied while typing.


https://user-images.githubusercontent.com/35942988/230160550-c540523c-4fb9-4984-8564-5bdebb7fbcb3.mov

Author: thecoolwinter

Sources/CodeEditTextView/CodeEditTextView.swift

@@ -23,11 +23,16 @@ public struct CodeEditTextView: NSViewControllerRepresentable {
     ///   - lineHeight: The line height multiplier (e.g. `1.2`)
     ///   - wrapLines: Whether lines wrap to the width of the editor
     ///   - editorOverscroll: The percentage for overscroll, between 0-1 (default: `0.0`)
+    ///   - cursorPosition: The cursor's position in the editor, measured in `(lineNum, columnNum)`
+    ///   - useThemeBackground: Determines whether the editor uses the theme's background color, or a transparent
+    ///                         background color
     ///   - highlightProvider: A class you provide to perform syntax highlighting. Leave this as `nil` to use the
     ///                        built-in `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.
     ///   - isEditable: A Boolean value that controls whether the text view allows the user to edit text.
+    ///   - 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`
     public init(
         _ text: Binding<String>,
         language: CodeLanguage,
@@ -42,7 +47,8 @@ public struct CodeEditTextView: NSViewControllerRepresentable {
         useThemeBackground: Bool = true,
         highlightProvider: HighlightProviding? = nil,
         contentInsets: NSEdgeInsets? = nil,
-        isEditable: Bool = true
+        isEditable: Bool = true,
+        letterSpacing: Double = 1.0
     ) {
         self._text = text
         self.language = language
@@ -58,6 +64,7 @@ public struct CodeEditTextView: NSViewControllerRepresentable {
         self.highlightProvider = highlightProvider
         self.contentInsets = contentInsets
         self.isEditable = isEditable
+        self.letterSpacing = letterSpacing
     }
 
     @Binding private var text: String
@@ -74,6 +81,7 @@ public struct CodeEditTextView: NSViewControllerRepresentable {
     private var highlightProvider: HighlightProviding?
     private var contentInsets: NSEdgeInsets?
     private var isEditable: Bool
+    private var letterSpacing: Double
 
     public typealias NSViewControllerType = STTextViewController
 
@@ -85,15 +93,16 @@ public struct CodeEditTextView: NSViewControllerRepresentable {
             theme: theme,
             tabWidth: tabWidth,
             indentOption: indentOption,
+            lineHeight: lineHeight,
             wrapLines: wrapLines,
             cursorPosition: $cursorPosition,
             editorOverscroll: editorOverscroll,
             useThemeBackground: useThemeBackground,
             highlightProvider: highlightProvider,
             contentInsets: contentInsets,
-            isEditable: isEditable
+            isEditable: isEditable,
+            letterSpacing: letterSpacing
         )
-        controller.lineHeightMultiple = lineHeight
         return controller
     }
 
@@ -118,6 +127,9 @@ public struct CodeEditTextView: NSViewControllerRepresentable {
         if controller.tabWidth != tabWidth {
             controller.tabWidth = tabWidth
         }
+        if controller.letterSpacing != letterSpacing {
+            controller.letterSpacing = letterSpacing
+        }
 
         controller.reloadUI()
         return

Sources/CodeEditTextView/Controller/STTextViewController.swift

@@ -76,6 +76,22 @@ public class STTextViewController: NSViewController, STTextViewDelegate, ThemeAt
     /// Optional insets to offset the text view in the scroll view by.
     public var contentInsets: NSEdgeInsets?
 
+    /// A multiplier that determines the amount of space between characters. `1.0` indicates no space,
+    /// `2.0` indicates one character of space between other characters.
+    public var letterSpacing: Double = 1.0 {
+        didSet {
+            kern = fontCharWidth * (letterSpacing - 1.0)
+            reloadUI()
+        }
+    }
+
+    /// The kern to use for characters. Defaults to `0.0` and is updated when `letterSpacing` is set.
+    private var kern: CGFloat = 0.0
+
+    private var fontCharWidth: CGFloat {
+        (" " as NSString).size(withAttributes: [.font: font]).width
+    }
+
     // MARK: - Highlighting
 
     internal var highlighter: Highlighter?
@@ -92,20 +108,23 @@ public class STTextViewController: NSViewController, STTextViewDelegate, ThemeAt
         theme: EditorTheme,
         tabWidth: Int,
         indentOption: IndentOption,
+        lineHeight: Double,
         wrapLines: Bool,
         cursorPosition: Binding<(Int, Int)>,
         editorOverscroll: Double,
         useThemeBackground: Bool,
         highlightProvider: HighlightProviding? = nil,
         contentInsets: NSEdgeInsets? = nil,
-        isEditable: Bool
+        isEditable: Bool,
+        letterSpacing: Double
     ) {
         self.text = text
         self.language = language
         self.font = font
         self.theme = theme
         self.tabWidth = tabWidth
         self.indentOption = indentOption
+        self.lineHeightMultiple = lineHeight
         self.wrapLines = wrapLines
         self.cursorPosition = cursorPosition
         self.editorOverscroll = editorOverscroll
@@ -122,7 +141,7 @@ public class STTextViewController: NSViewController, STTextViewDelegate, ThemeAt
 
     // MARK: VC Lifecycle
 
-    // swiftlint:disable function_body_length
+    // swiftlint:disable:next function_body_length
     public override func loadView() {
         textView = STTextView()
 
@@ -234,7 +253,7 @@ public class STTextViewController: NSViewController, STTextViewDelegate, ThemeAt
         paragraph.minimumLineHeight = lineHeight
         paragraph.maximumLineHeight = lineHeight
         paragraph.tabStops.removeAll()
-        paragraph.defaultTabInterval = CGFloat(tabWidth) * (" " as NSString).size(withAttributes: [.font: font]).width
+        paragraph.defaultTabInterval = CGFloat(tabWidth) * fontCharWidth
         return paragraph
     }
 
@@ -252,9 +271,6 @@ public class STTextViewController: NSViewController, STTextViewDelegate, ThemeAt
 
     /// Reloads the UI to apply changes to ``STTextViewController/font``, ``STTextViewController/theme``, ...
     internal func reloadUI() {
-        // if font or baseline has been modified, set the hasSetStandardAttributesFlag
-        // to false to ensure attributes are updated. This allows live UI updates when changing preferences.
-
         textView?.textColor = theme.text
         textView.backgroundColor = useThemeBackground ? theme.background : .clear
         textView?.insertionPointColor = theme.insertionPoint
@@ -293,7 +309,8 @@ public class STTextViewController: NSViewController, STTextViewDelegate, ThemeAt
             .font: font,
             .foregroundColor: theme.colorFor(capture),
             .baselineOffset: baselineOffset,
-            .paragraphStyle: paragraphStyle
+            .paragraphStyle: paragraphStyle,
+            .kern: kern
         ]
     }
 

Tests/CodeEditTextViewTests/CodeEditTextViewTests.swift

@@ -40,3 +40,4 @@ final class CodeEditTextViewTests: XCTestCase {
         XCTAssertEqual(result, expected)
     }
 }
+// swiftlint:enable all

Tests/CodeEditTextViewTests/STTextViewControllerTests.swift

@@ -4,6 +4,7 @@ import SwiftTreeSitter
 import AppKit
 import TextStory
 
+// swiftlint:disable all
 final class STTextViewControllerTests: XCTestCase {
 
     var controller: STTextViewController!
@@ -35,11 +36,13 @@ final class STTextViewControllerTests: XCTestCase {
             theme: theme,
             tabWidth: 4,
             indentOption: .spaces(count: 4),
+            lineHeight: 1.0,
             wrapLines: true,
             cursorPosition: .constant((1, 1)),
             editorOverscroll: 0.5,
             useThemeBackground: true,
-            isEditable: true
+            isEditable: true,
+            letterSpacing: 1.0
         )
 
         controller.loadView()
@@ -193,4 +196,24 @@ final class STTextViewControllerTests: XCTestCase {
         controller.textView.insertText("\t", replacementRange: .zero)
         XCTAssertEqual(controller.textView.string, String(repeating: " ", count: 1000))
     }
+
+    func test_letterSpacing() {
+        let font: NSFont = .monospacedSystemFont(ofSize: 11, weight: .medium)
+
+        controller.letterSpacing = 1.0
+
+        XCTAssertEqual(
+            controller.attributesFor(nil)[.kern]! as! CGFloat,
+            (" " as NSString).size(withAttributes: [.font: font]).width * 0.0
+        )
+
+        controller.letterSpacing = 2.0
+        XCTAssertEqual(
+            controller.attributesFor(nil)[.kern]! as! CGFloat,
+            (" " as NSString).size(withAttributes: [.font: font]).width * 1.0
+        )
+
+        controller.letterSpacing = 1.0
+    }
 }
+// swiftlint:enable all