Using TextKit 2 to interact with text

At a glance

Project structure

Source bundle/
├── iOS/
│   ├── AppDelegate.swift
│   ├── TextDocumentView.swift
│   ├── CommentPopoverViewController.swift
│   ├── SceneDelegate.swift
│   └── TextDocumentViewController.swift
├── macOS/
│   ├── AppDelegate.swift
│   ├── TextDocumentView.swift
│   ├── CommentPopoverViewController.swift
│   ├── TextDocumentViewController.swift
│   └── WindowController.swift
└── Shared/
    ├── BubbleLayoutFragment.swift
    └── CommentUtils.swift

Structure observations

• The TextKit graph is assembled explicitly in each platform controller rather than hidden in app delegates.
• The custom document view is both the viewport rendering adapter and interaction surface for selection/comments.
• Shared fragment/layer types contain drawing geometry; iOS and macOS files contain platform input, scrolling, and presentation behavior.

Overall architecture

flowchart LR
    IOS["iOS TextDocumentViewController"] --> GRAPH["NSTextContentStorage → NSTextLayoutManager → NSTextContainer"]
    MAC["macOS TextDocumentViewController"] --> GRAPH
    GRAPH --> VIEW["Platform TextDocumentView"]
    VIEW --> LMDELEGATE["NSTextLayoutManagerDelegate"]
    LMDELEGATE --> NORMAL["NSTextLayoutFragment"]
    LMDELEGATE --> BUBBLE["BubbleLayoutFragment for comments"]
    NORMAL --> LAYER["TextLayoutFragmentLayer"]
    BUBBLE --> LAYER
    LAYER --> SURFACE["Viewport content CALayer"]
    VIEW --> EDIT["Selection and comment editing transaction"]

Reference code

iOS/TextDocumentViewController.swift:29 — explicit TextKit 2 object graph

    required init?(coder: NSCoder) {
        textLayoutManager = NSTextLayoutManager()
        textContentStorage = NSTextContentStorage()
        super.init(coder: coder)
        textContentStorage.delegate = self
        textContentStorage.addTextLayoutManager(textLayoutManager)
        let textContainer = NSTextContainer(size: CGSize(width: 200, height: 0))
        textLayoutManager.textContainer = textContainer
    }

Interpretation

Text storage, layout, and rendering are distinct owners. The controller assembles content/layout services and supplies display attributes; the custom view owns viewport and interaction mechanics. Shared fragment subclasses and CALayers turn TextKit layout results into specialized drawing without making controllers render text directly.

Ownership and state

classDiagram
    TextDocumentViewController *-- NSTextContentStorage : private
    TextDocumentViewController *-- NSTextLayoutManager : private
    NSTextContentStorage o-- NSTextLayoutManager : registered manager
    NSTextLayoutManager *-- NSTextContainer : assigned
    TextDocumentView o-- NSTextLayoutManager : assigned collaborator
    TextDocumentView *-- CALayer : content and selection
    TextDocumentView *-- NSMapTable : weak fragment-layer map
    CALayer *-- TextLayoutFragmentLayer : viewport sublayers
    TextLayoutFragmentLayer o-- NSTextLayoutFragment : draws
    BubbleLayoutFragment --|> NSTextLayoutFragment

Ownership evidence

iOS/TextDocumentView.swift:141 — view-local rendering state and delegates

    private var contentLayer: CALayer! = nil
    private var selectionLayer: CALayer! = nil
    private var fragmentLayerMap: NSMapTable<NSTextLayoutFragment, CALayer>
    private var padding: CGFloat = 5.0

    var textLayoutManager: NSTextLayoutManager? {
        didSet {
            textLayoutManager?.delegate = self
            textLayoutManager?.textViewportLayoutController.delegate = self
            layer.setNeedsLayout()
        }
    }

Composition denotes source-visible construction and retained value state. Aggregation denotes a stored or injected collaborator whose exclusive lifetime the source does not prove.

Class and protocol design

iOS/TextDocumentView.swift:251 — comment-specific layout fragment selection

    func textLayoutManager(_ textLayoutManager: NSTextLayoutManager,
                           textLayoutFragmentFor location: NSTextLocation,
                           in textElement: NSTextElement) -> NSTextLayoutFragment {
        let index = textLayoutManager.offset(
            from: textLayoutManager.documentRange.location, to: location)
        let depth = textContentStorage!.textStorage!
            .attribute(.commentDepth, at: index, effectiveRange: nil) as! NSNumber?
        if let depth {
            let fragment = BubbleLayoutFragment(
                textElement: textElement, range: textElement.elementRange)
            fragment.commentDepth = depth.uintValue
            return fragment
        }
        return NSTextLayoutFragment(textElement: textElement,
                                    range: textElement.elementRange)
    }

All protocol conformances are TextKit/UIKit/AppKit framework contracts. The sample defines no local protocol abstraction; extensibility comes from framework delegates and subclassing NSTextLayoutFragment/CALayer.

Access control

Reference code

Shared/CommentUtils.swift:10 — shared public attributed-string key

extension NSAttributedString.Key {
    public static var commentDepth: NSAttributedString.Key {
        return NSAttributedString.Key("TK2DemoCommentDepth")
    }
}

enum Reaction: Int, CaseIterable {
    // Reaction metadata remains module-internal.
}

The attribute key is the one explicit exported symbol; enclosing sample classes remain internal and implementation state is private. No open or fileprivate declaration is used in the shared rendering path.

Logic ownership and placement

Design patterns

Naming conventions

• TextKit roles retain framework vocabulary (TextContentStorage, TextLayoutManager, TextLayoutFragment).
• Custom types add one responsibility (BubbleLayoutFragment, TextLayoutFragmentLayer, TextDocumentView).
• Private commands describe mechanics (findOrCreateLayer, updateSelectionHighlights, adjustViewportOffset).
• Platform folders intentionally reuse primary type names because each target compiles only its own shell.

Architecture takeaways

• Construct the TextKit storage/layout/container graph at the controller boundary and pass collaborators to the rendering view.
• Use the viewport delegate to materialize only visible fragment layers and a fragment subclass for specialized layout/drawing.
• Keep platform interaction shells separate while sharing fragment and layer primitives.
• Reserve public access for a true shared semantic key; keep rendering state private.

Source map

• Official Apple documentation