Text Attachment Support

[thecoolwinter]

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

• ✨ Code Folding CodeEditSourceEditor#43
• ✨ Placeholder Support CodeEditSourceEditor#287
• ✨ Snippets CodeEdit#1623

Checklist

• I read and understood the contributing guide as well as the code of conduct
• The issues this PR addresses are related to each other
• My changes generate no new warnings
• My code builds and runs on my machine
• My changes are all related to the related issue above
• 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:

`TextView+Menu.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())
        }
    }
}

Screen.Recording.2025-05-05.at.2.25.10.PM.mov

[tom-ludwig]

I just skimmed through the code and definitely think a second reviewer is needed for changes of this size. That said, the changes look really good, to be honest.