Perception

Perception provides Swift's Observation tools, back-ported to support a wider range of platforms. The library is split into two main parts:

1. PerceptionCore: Contains the core functionality of the library.
2. Perception: Automatically exports PerceptionCore and provides the macros required to support the core functionality.

For general library usage and core logic, refer to the PerceptionCore documentation.

Perception provides macros to fine-tune how properties are observed:

• @PerceptionTracked: Marks a property to be tracked by the observation system. This is the default behavior for properties in a @Perceptible type.
• @PerceptionIgnored: Marks a property so that changes to it do not trigger observation updates. Use this for properties that should not affect the UI or other observers.

Perception supports the standard SwiftUI @Environment property wrapper and .environment() view modifier for perceptible objects. You can inject perceptible objects into the environment and access them using the same APIs used for standard SwiftUI observation.

struct FeatureView: View {
  @Environment(Settings.self) var settings

  // ...
}

// In some parent view:
.environment(settings)

In SwiftUI, you must wrap your view's content in the WithPerceptionTracking view to ensure observation is correctly hooked up. If you access a perceptible property inside a view's body without this wrapper, you will receive a runtime warning:

🟣 Runtime Warning: Perceptible state '\FeatureModel.count' was accessed from a view but is not being tracked.

struct FeatureView: View {
  let model: FeatureModel

  var body: some View {
    WithPerceptionTracking {
      Form {
        Text("\(model.count)")
        Button("Increment") { model.count += 1 }
      }
    }
  }
}

Perception back-ports Swift's Observation tools (@Observable, withObservationTracking, and Observations) to older platforms like iOS 13, macOS 10.15, tvOS 13, and watchOS 6.

To use it, import Perception (which automatically imports PerceptionCore). The workflow is nearly identical to official Swift Observation, with the primary difference being the use of the @Perceptible macro and the WithPerceptionTracking view wrapper.

@Perceptible
class FeatureModel {
  var count = 0
}

To make a class observable, mark it with the @Perceptible macro. This allows the class to participate in the observation system, enabling views and other observers to track changes to its properties.

@Perceptible
class FeatureModel {
  var count = 0
}

To create two-way bindings to the properties of a perceptible object in SwiftUI, use the @Perception.Bindable property wrapper. This is the back-ported equivalent of SwiftUI's @Bindable.

struct FeatureView: View {
  @Perception.Bindable var model: FeatureModel

  // ...
}

The Perceptions async sequence is a back-port of Swift's Observations API. It allows you to observe changes to perceptible or observable objects over time using an AsyncSequence.

let counts = Perceptions { model.count }
for await count in counts {
  print("Count changed: \(count)")
}

The Observations async sequence is back-ported as Perceptions. You can use it to create an async sequence that emits new values whenever a specific property on a perceptible or observable object changes.

let counts = Perceptions { model.count }
for await count in counts {
  print("Count changed: \(count)")
}

To support two-way binding for perceptible objects in SwiftUI, use the @Perception.Bindable property wrapper. This is the back-ported equivalent of SwiftUI's @Bindable.

struct FeatureView: View {
  @Perception.Bindable var model: FeatureModel

  // ...
}

To enable observation capabilities for a type, you must make it conform to the Perceptible protocol. This is typically done using the Perceptible() macro, which handles the necessary boilerplate to allow the type to be observed by the library's tools.

@Perceptible
class MyModel {
  var name: String
}