Building and improving your app with Mac Catalyst

At a glance

Project structure

Trip Planner/
├── AppDelegate.swift
├── SceneDelegate.swift
├── BrowserSplitViewController.swift
├── SidebarViewController.swift
├── SupplementaryViewController.swift
├── Model/
│   ├── DataModel.swift
│   ├── ModelItemsCollection.swift
│   └── Sample Data/SampleData.swift
├── Item Detail/
│   ├── DetailSceneDelegate.swift
│   ├── DetailViewController.swift
│   ├── LocatedItemDetailViewController.swift
│   └── RewardsProgramDetailViewController.swift
├── Printing/ItemPrintPageRenderer.swift
└── Utility Extensions/

Structure observations

• Domain values and selection state live outside the view controllers.
• The main browser and item-detail windows have separate scene delegates and restoration paths.
• Mac Catalyst code is localized behind targetEnvironment(macCatalyst) rather than forked into a second app.

Overall architecture

flowchart LR
    Scene["SceneDelegate"] --> Browser["BrowserSplitViewController"]
    Sidebar["SidebarViewController"] --> Selection["ModelItemsCollection"]
    Selection -->|"change notification"| Browser
    Browser --> Supplementary["SupplementaryViewController"]
    Browser --> Detail["DetailViewController"]
    Detail --> Located["LocatedItemDetailViewController"]
    Detail --> Rewards["RewardsProgramDetailViewController"]
    Browser --> Print["ItemPrintPageRenderer"]
    Scene -->|"encode / restore IDs"| Activity["NSUserActivity"]
    DetailScene["DetailSceneDelegate"] --> Detail
    Catalyst["Catalyst toolbar adapters"] --> Scene

Reference code

Trip Planner/BrowserSplitViewController.swift:31 — the split controller installs its column shells, observes one selection collection, and derives visible columns from that state.

setViewController(emptyNavigationController(), for: .secondary)
setViewController(emptyNavigationController(), for: .supplementary)

supplementarySelectionChangeObserver = NotificationCenter.default.addObserver(
    forName: .modelItemsCollectionDidChange,
    object: selectedItemsCollection,
    queue: nil
) { [weak self] _ in
    self?.updateDueToSelectedItemsChange()
}

updateDueToSelectedItemsChange()
updateDueToDetailItemChange()

Interpretation

BrowserSplitViewController is the high-level feature coordinator, not AppDelegate. It translates selection/detail state into columns, titles, printing targets, and a browser-state notification consumed by the scene’s restoration adapter.

Ownership and state

classDiagram
    SceneDelegate *-- NSUserActivity : current restoration activity
    SceneDelegate *-- MainSceneToolbarModel : Catalyst only
    BrowserSplitViewController *-- ModelItemsCollection : stable selection owner
    BrowserSplitViewController o-- Model : sample data
    BrowserSplitViewController *-- NotificationToken : selection observer
    SupplementaryViewController o-- ModelItemsCollection : injected reference
    DetailViewController *-- AnyModelItem : immutable input
    DetailViewController *-- UIViewController : chosen child
    AnyModelItem *-- ModelItem : private wrapped value
    DetailSceneDelegate *-- DetailToolbarModel : Catalyst only

Ownership evidence

Trip Planner/Model/DataModel.swift:108 — AnyModelItem retains one private protocol value and exposes a uniform identity/name plus optional capabilities.

class AnyModelItem: NSObject, ModelItem {
    typealias ItemID = ItemIdentifierProviding.ItemID

    private let wrapped: ModelItem
    var itemID: ItemID { wrapped.itemID }
    var name: String { wrapped.name }

    var imageName: String? { (wrapped as? ImageProviding)?.imageName }
    var location: CLLocation? { (wrapped as? LocationProviding)?.location }
    var iconName: String? { (wrapped as? IconNameProviding)?.iconName }

    init(_ modelItem: ModelItem) {
        wrapped = modelItem
    }
}

Class and protocol design

This is protocol-oriented design with a pragmatic UIKit bridge: domain features are expressed as narrow protocols, while AnyModelItem provides the concrete, homogeneous reference type required by collection identity, Objective-C equality, and controller APIs.

Access control

Reference code

Trip Planner/BrowserSplitViewController.swift:10 — the coordinator exposes its current selection but guards replacement and synchronization internals.

class BrowserSplitViewController: UISplitViewController {
    private(set) var selectedItemsCollection = ModelItemsCollection()
    private var supplementarySelectionChangeObserver: Any?

    var selectedItems: [AnyModelItem] {
        selectedItemsCollection.modelItems
    }

    var detailItem: AnyModelItem? {
        didSet { updateDueToDetailItemChange() }
    }
}

Logic ownership and placement

Design patterns

Naming conventions

• UI owners use role suffixes: BrowserSplitViewController, SidebarViewController, DetailSceneDelegate, and ItemPrintPageRenderer.
• Capability protocols use “Providing”; the common entity role uses ModelItem.
• AnyModelItem clearly signals type erasure; ModelItemsCollection signals ordered mutable selection rather than a repository.
• State-transition methods are explicit: updateDueToSelectedItemsChange, restoreSelections, configure(with:), and updateUserActivity.

Architecture takeaways

• Use a split-view coordinator as the owner of cross-column navigation state.
• Model heterogeneous domain values with small capabilities, then type-erase only at the UIKit collection boundary.
• Restore windows from stable model identifiers, not serialized UI objects.
• Keep Catalyst-only toolbar adapters private and conditionally compiled while sharing the domain/navigation core.
• Use private(set) to preserve the identity of observable state that collaborators still need to read and mutate through its API.

Source map

• Official Apple documentation