ObservationTrackingExample

https://github.com/steipete/observationtrackingexample
Admin
A demonstration of Swift's @Observable macro working seamlessly across SwiftUI, UIKit, and AppKit...
Tokens:5,131
Snippets:39
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Launch Companion AppKit Window (macOS)

Source: https://context7.com/steipete/observationtrackingexample/llms.txt

This window controller creates an NSWindow, instantiates an AppKitViewController, and injects the shared data model. It includes logic to position the AppKit window adjacent to the SwiftUI window.

```swift
import AppKit

@MainActor
final class AppKitWindowController: NSWindowController {
    convenience init(dataModel: SharedDataModel) {
        let window = NSWindow(
            contentRect: NSRect(x: 0, y: 0, width: 550, height: 750),
            styleMask: [.titled, .closable, .miniaturizable, .resizable],
            backing: .buffered,
            defer: false
        )
        window.title = "AppKit Observer Example"
        window.minSize = NSSize(width: 500, height: 700)
        window.center()

        // Place AppKit window to the right of the SwiftUI window
        if let mainWindow = NSApp.mainWindow {
            var frame = window.frame
            frame.origin.x = mainWindow.frame.maxX + 20
            frame.origin.y = mainWindow.frame.origin.y
            window.setFrame(frame, display: true, animate: false)
        }

        self.init(window: window)

        let viewController = AppKitViewController()
        viewController.setDataModel(dataModel)
        window.contentViewController = viewController
        window.layoutIfNeeded()
    }
}
```

--------------------------------

### Enable Observation Tracking (iOS)

Source: https://github.com/steipete/observationtrackingexample/blob/main/README.md

Add this key to your iOS Info.plist to enable observation tracking.

```xml
<key>UIObservationTrackingEnabled</key>
<true/>
```

--------------------------------

### Enable Observation Tracking (macOS)

Source: https://github.com/steipete/observationtrackingexample/blob/main/README.md

Add this key to your macOS Info.plist to enable observation tracking.

```xml
<key>NSObservationTrackingEnabled</key>
<true/>
```

--------------------------------

### Enable Observation Tracking in Info.plist

Source: https://context7.com/steipete/observationtrackingexample/llms.txt

Configuration keys required in the app's `Info.plist` to enable observation tracking for UIKit and AppKit. This is necessary for `viewWillLayout()` and `viewWillLayoutSubviews()` to function as dependency-tracking scopes.

```xml
<!-- iOS Info.plist -->
<key>UIObservationTrackingEnabled</key>
<true/>

<!-- macOS Info.plist -->
<key>NSObservationTrackingEnabled</key>
<true/>
```

--------------------------------

### Create Observable Model

Source: https://github.com/steipete/observationtrackingexample/blob/main/README.md

Define a @Observable and @MainActor class to hold shared data. Properties accessed in UI will be automatically tracked.

```swift
@Observable
@MainActor
final class SharedDataModel: Sendable {
    var message = "Hello!"
    var counter = 0
    // ... more properties
}
```

--------------------------------

### Custom SwiftUI Environment for AppModel (iOS)

Source: https://context7.com/steipete/observationtrackingexample/llms.txt

Provides a mechanism to inject an AppModel instance into the SwiftUI environment, making it accessible throughout the view hierarchy. This bridges UIKit and SwiftUI.

```swift
import SwiftUI

// 1. Declare the environment key
private struct AppModelEnvironmentKey: EnvironmentKey {
    static let defaultValue: AppModel? = nil
}

// 2. Extend EnvironmentValues
extension EnvironmentValues {
    var appModel: AppModel? {
        get { self[AppModelEnvironmentKey.self] }
        set { self[AppModelEnvironmentKey.self] = newValue }
    }
}

// 3. Convenience View modifier
extension View {
    func appModel(_ model: AppModel?) -> some View {
        environment(\.appModel, model)
    }
}

// 4. Usage in the hosting controller setup (RootViewController):
let swiftUIView = SwiftUIDemoView().appModel(model)
let host = UIHostingController(rootView: swiftUIView)
host.traitOverrides.appModel = model   // also set trait for completeness

// 5. Usage in a SwiftUI view:
struct SwiftUIDemoView: View {
    @Environment(\.appModel) private var appModel: AppModel?

    var body: some View {
        Text("\(appModel?.sharedData.counter ?? 0)")
            .font(.system(size: 48, weight: .semibold, design: .monospaced))
            .foregroundColor(.green)
    }
}
```

--------------------------------

### SharedDataModel with Async Loading (iOS)

Source: https://context7.com/steipete/observationtrackingexample/llms.txt

An observable data model for iOS that includes state for text, counter, loading status, items, selected item, and theme. It supports asynchronous data loading and item management.

```swift
import Foundation
import UIKit
import Observation

@Observable
@MainActor
final class SharedDataModel: Sendable {
    var text        = "Hello from iOS!"
    var counter     = 0
    var isLoading   = false
    var items       = Item.sampleItems
    var selectedItem: Item?
    var theme: Theme = .light

    // MARK: Theme
    enum Theme: String, CaseIterable {
        case light, dark, auto
        var userInterfaceStyle: UIUserInterfaceStyle {
            switch self {
            case .light: return .light
            case .dark:  return .dark
            case .auto:  return .unspecified
            }
        }
    }

    // MARK: Item list management
    func addItem() {
        items.append(Item(
            title:    "Item #\(items.count + 1)",
            subtitle: "Added at \(Date().formatted(date: .omitted, time: .shortened))",
            detail:   "Created with counter value: \(counter)"
        ))
    }

    func removeItem(at index: Int) {
        guard items.indices.contains(index) else { return }
        if selectedItem?.id == items[index].id { selectedItem = nil }
        items.remove(at: index)
    }

    // MARK: Async loading — isLoading flips automatically; all observers update
    func loadData() async {
        isLoading = true
        try? await Task.sleep(nanoseconds: 2_000_000_000)   // simulate 2 s network call
        text = "Data loaded at \(Date().formatted())"
        incrementCounter()
        isLoading = false
    }
}
```

--------------------------------

### Use Observable Model in AppKit

Source: https://github.com/steipete/observationtrackingexample/blob/main/README.md

In AppKit, accessing properties of the observable model in `viewWillLayout()` automatically sets up tracking for UI updates.

```swift
override func viewWillLayout() {
    super.viewWillLayout()
    
    // Reading these properties automatically sets up tracking!
    textField.stringValue = model.message
    label.intValue = model.counter
}
```

--------------------------------

### Use Observable Model in UIKit

Source: https://github.com/steipete/observationtrackingexample/blob/main/README.md

In UIKit, reading properties of the observable model in `updateProperties()` (iOS 26+) or `viewWillLayoutSubviews()` automatically sets up tracking for UI updates.

```swift
@available(iOS 26.0, *)
override func updateProperties() {
    super.updateProperties()
    
    // Reading these properties automatically sets up tracking!
    textLabel.text = model.message
    counterLabel.text = "\(model.counter)"
}
```

```swift
override func viewWillLayoutSubviews() {
    super.viewWillLayoutSubviews()
    if #available(iOS 26.0, *) { return }
    textLabel.text = model.message
    counterLabel.text = "\(model.counter)"
}
```

--------------------------------

### Shared Application State Management (macOS)

Source: https://context7.com/steipete/observationtrackingexample/llms.txt

The AppState class, also @Observable, manages the single SharedDataModel instance and the lifecycle of a companion AppKit window. This ensures both windows consistently share the same model object.

```swift
import SwiftUI
import AppKit
import Observation

@Observable
@MainActor
final class AppState: Sendable {
    let dataModel = SharedDataModel()
    private var appKitWindowController: AppKitWindowController?

    func openAppKitWindow() {
        if appKitWindowController == nil {
            appKitWindowController = AppKitWindowController(dataModel: dataModel)
        }
        appKitWindowController?.showWindow(nil)
        appKitWindowController?.window?.makeKeyAndOrderFront(nil)
    }
}

// App entry point wires everything together:
@main
struct ObservationTrackingExampleApp: App {
    @State private var appState = AppState()

    var body: some Scene {
        WindowGroup {
            ContentView(appState: appState)
                .onAppear {
                    appState.openAppKitWindow()   // open AppKit window immediately
                }
        }
    }
}
```

--------------------------------

### Automatic Observation Tracking in UIKit View Controllers

Source: https://context7.com/steipete/observationtrackingexample/llms.txt

Use `updateProperties()` on iOS 26+ as the preferred hook for automatic observation tracking. For older iOS versions, `viewWillLayoutSubviews()` can be used as a fallback. Property reads within these methods are tracked, causing the method to re-run automatically when observed properties change.

```swift
import UIKit
import Observation

class UIKitDemoViewController: UIViewController {
    private var model: SharedDataModel? { traitCollection.appModel?.sharedData }

    // iOS 26+: preferred observation hook
    @available(iOS 26.0, *)
    override func updateProperties() {
        super.updateProperties()
        updateFromModel()
    }

    // iOS 18–25: fallback hook (also works but called more broadly)
    override func viewWillLayoutSubviews() {
        super.viewWillLayoutSubviews()
        if #available(iOS 26.0, *) { return }
        updateFromModel()
    }

    private func updateFromModel() {
        // Property reads here are tracked — this method re-runs on changes
        textLabel.text    = model?.text ?? "No data"
        counterLabel.text = "\(model?.counter ?? 0)"

        if model?.isLoading == true {
            activityIndicator.startAnimating()
            loadDataButton.isEnabled = false
        } else {
            activityIndicator.stopAnimating()
            loadDataButton.isEnabled = true
        }

        if let theme = model?.theme,
           let idx = SharedDataModel.Theme.allCases.firstIndex(of: theme) {
            themeSegmentedControl.selectedSegmentIndex = idx
        }
        view.window?.overrideUserInterfaceStyle = model?.theme.userInterfaceStyle ?? .unspecified
    }

    // Write-back actions mutate the shared model
    @objc private func incrementTapped() { model?.incrementCounter() }
    @objc private func resetTapped()     { model?.resetCounter() }

    @objc private func loadDataTapped() {
        Task { await model?.loadData() }   // async operation; isLoading flips automatically
    }

    @objc private func themeChanged() {
        let i = themeSegmentedControl.selectedSegmentIndex
        guard i >= 0, i < SharedDataModel.Theme.allCases.count else { return }
        model?.theme = SharedDataModel.Theme.allCases[i]
    }
}
```

--------------------------------

### Declare Reactive Data Model with @Observable

Source: https://context7.com/steipete/observationtrackingexample/llms.txt

Annotate a class with @Observable and @MainActor to make all stored properties reactive. Ensure Sendable conformance for Swift 6 strict concurrency. Any code on the MainActor can mutate the model, and observers are notified automatically.

```swift
import Foundation
import Observation

@Observable
@MainActor
final class SharedDataModel: Sendable {
    var message = "Try typing here!"
    var counter = 0
    var isEnabled = true
    var selectedColor = "Blue"
    var sliderValue = 50.0

    func incrementCounter() { counter += 1 }
    func decrementCounter() { counter -= 1 }

    func reset() {
        message = "Try typing here!"
        counter = 0
        isEnabled = true
        selectedColor = "Blue"
        sliderValue = 50.0
    }
}

// Usage: any code on the MainActor can mutate the model;
// all observers are notified automatically.
let model = SharedDataModel()
model.incrementCounter()   // counter == 1
model.reset()              // counter == 0, message == "Try typing here!"
```

--------------------------------

### Automatic AppKit Observation Tracking

Source: https://context7.com/steipete/observationtrackingexample/llms.txt

Reading @Observable properties inside viewWillLayout() registers them as dependencies. AppKit calls this method again whenever any of those properties change, keeping UI controls in sync without KVO or binding code.

```swift
import Cocoa
import Observation

@MainActor
final class AppKitViewController: NSViewController {
    private var dataModel: SharedDataModel?

    // Called automatically when any tracked @Observable property changes
    override func viewWillLayout() {
        super.viewWillLayout()
        guard let model = dataModel else { return }

        // Reading these properties registers them as tracked dependencies.
        // AppKit will re-call viewWillLayout() whenever they mutate.
        messageTextField.stringValue = model.message
        counterLabel.stringValue    = "\(model.counter)"
        enabledCheckbox.state       = model.isEnabled ? .on : .off

        if let index = colorPopupButton.itemTitles.firstIndex(of: model.selectedColor) {
            colorPopupButton.selectItem(at: index)
        }
        sliderValueLabel.stringValue = "\(Int(model.sliderValue))%"
        slider.doubleValue           = model.sliderValue

        // Animate background color change based on theme selection
        let color: NSColor
        switch model.selectedColor {
        case "Red":    color = NSColor.systemRed.withAlphaComponent(0.05)
        case "Green":  color = NSColor.systemGreen.withAlphaComponent(0.05)
        case "Yellow": color = NSColor.systemYellow.withAlphaComponent(0.05)
        default:       color = NSColor.systemBlue.withAlphaComponent(0.05)
        }
        NSAnimationContext.runAnimationGroup {
            ctx in
            ctx.duration = 0.3
            view.animator().layer?.backgroundColor = color.cgColor
        }
    }

    // Write-back: user actions mutate the shared model — SwiftUI window updates instantly
    @objc private func incrementCounter()            { dataModel?.incrementCounter() }
    @objc private func colorChanged(_ s: NSPopUpButton) {
        dataModel?.selectedColor = s.selectedItem?.title ?? "Blue"
    }
    @objc private func sliderChanged(_ s: NSSlider)  { dataModel?.sliderValue = s.doubleValue }
    @objc private func resetAll()                    { dataModel?.reset() }
}

```

--------------------------------

### SwiftUI Bidirectional Binding via @Bindable

Source: https://context7.com/steipete/observationtrackingexample/llms.txt

The SwiftUI window uses @Bindable to create two-way bindings directly to the @Observable model's properties. Changes made here propagate to the AppKit window, and vice-versa.

```swift
import SwiftUI

struct ContentView: View {
    let appState: AppState
    @Bindable var dataModel: SharedDataModel

    init(appState: AppState) {
        self.appState  = appState
        self.dataModel = appState.dataModel
    }

    var body: some View {
        VStack(spacing: 20) {
            // Two-way text binding — typing here updates AppKit window live
            TextField("Type here...", text: $dataModel.message)
                .textFieldStyle(.roundedBorder)

            // Counter with increment / decrement
            HStack(spacing: 20) {
                Button { dataModel.decrementCounter() } label: {
                    Image(systemName: "minus.circle.fill").font(.title)
                }
                Text("\(dataModel.counter)")
                    .font(.system(size: 36, weight: .bold, design: .rounded))
                Button { dataModel.incrementCounter() } label: {
                    Image(systemName: "plus.circle.fill").font(.title)
                }
            }

            // Toggle, color picker, slider — all bidirectional
            Toggle("Feature Enabled", isOn: $dataModel.isEnabled)
            Picker("Color", selection: $dataModel.selectedColor) {
                ForEach(["Blue", "Red", "Green", "Yellow"], id: \.self) { Text($0).tag($0) }
            }.pickerStyle(.segmented)
            Slider(value: $dataModel.sliderValue, in: 0...100)

            Button("Reset All Values") { dataModel.reset() }
                .buttonStyle(.borderedProminent)

            Button("Open AppKit Window") { appState.openAppKitWindow() }
                .buttonStyle(.bordered)
        }
        .padding()
    }
}

```

--------------------------------

### iOS Custom Traits Pattern

Source: https://github.com/steipete/observationtrackingexample/blob/main/README.md

Demonstrates injecting an observable object using custom traits in the view hierarchy for access in UIKit. Automatic tracking is enabled when accessing properties via the trait collection.

```swift
// Define a custom trait
struct AppModelTrait: UITraitDefinition {
    static let defaultValue: AppModel? = nil
}

// Inject at the root
rootViewController.traitOverrides.appModel = appModel

// Access anywhere in the hierarchy
@available(iOS 26.0, *)
override func updateProperties() {
    guard let model = traitCollection.appModel else { return }
    // Use model properties - automatic tracking!
}
```

--------------------------------

### Define Custom UIKit Trait for Observable Objects

Source: https://context7.com/steipete/observationtrackingexample/llms.txt

Define a custom `UITraitDefinition` to inject observable objects into the UIKit trait collection. This allows child view controllers and views to access the object via `traitCollection.appModel`, similar to SwiftUI's `@Environment.

```swift
import UIKit
import Observation

// 1. Define the custom trait
struct AppModelTrait: UITraitDefinition {
    static let defaultValue: AppModel? = nil
    static let affectsColorAppearance = false
    static let name       = "AppModel"
    static let identifier = "com.example.AppModelTrait"
}

// 2. Add typed accessors to UITraitCollection and UIMutableTraits
extension UITraitCollection {
    var appModel: AppModel? { self[AppModelTrait.self] }
}
extension UIMutableTraits {
    var appModel: AppModel? {
        get { self[AppModelTrait.self] }
        set { self[AppModelTrait.self] = newValue }
    }
}

// 3. Inject at the root (e.g., in RootViewController)
let model = AppModel()
traitOverrides.appModel = model                          // self (root)
uikitViewController.traitOverrides.appModel = model      // child UIKit VC
swiftUIHostingController.traitOverrides.appModel = model // child SwiftUI host

// 4. Read in any child view controller — no prop-drilling required
class UIKitDemoViewController: UIViewController {
    private var model: SharedDataModel? { 
        traitCollection.appModel?.sharedData
    }
}

// 5. Convenience extension for UIViewController
extension UIViewController {
    var appModel: AppModel? { traitCollection.appModel }

    func provideAppModel(_ m: AppModel, to vc: UIViewController) {
        vc.traitOverrides.appModel = m
    }
}
```
Tokens:
Raw