Samuel Défago’s Corner

Declarative Reactive Programming with Combine

2021-12-13T00:00:00+00:00

Any non-trivial application uses some form of data, whether retrieved from a web service, from a database or generated by user interaction. A well-behaved application properly responds to data changing over time while preserving a delightful uninterrupted user experience. Achieving this result can be a challenge, though, as most applications rely on several data sources whose changes might require a user interface update at any time.

Reactive programming offers an elegant solution to dealing with heterogeneous data sources, as it provides a comprehensive toolbox with which their results can be processed and consolidated. Though reactive programming is not new in the Apple ecosystem it historically required integrating third-party libraries like ReactiveSwift or RXSwift, which could be a tough decision.

This is why the fact that Apple officially introduced Combine in 2019 is a huge step forward, as it makes reactive programming immediately available to any project targeting iOS 13, tvOS 13, watchOS 6 or macOS 10.15. Adopting Combine or reactive programming might sometimes be frowned upon, though, as the initial learning curve might be steep. This is true but, as this article will attempt to illustrate, Combine and reactive programming can be invaluable tools to help you manage data sources in a way that is both expressive and scalable.

This article assumes some familiarity with Combine and reactive programming in general. If you are new to Combine you should probably watch the corresponding WWDC talk for a mild introduction first. You can also peek at Joseph Heck’s excellent Using Combine book at any time to better understand code snippets appearing in this article.

Foreword
Data Emitters
Data Pipelines
Triggers and Signals
Paginated Publishers
Refresh Publishers
Accumulators
Advanced Pipeline Design
Declarative Data Pipelines and View Models
User-driven Data Emitters
Conclusion
Sample Code

Remark

For the sake of simplicity code samples appearing in this article often define types and methods at global scope. In practice these should be of course be part of a narrower scope for better encapsulation.

Foreword

Async/await and actors draw a lot of attention nowadays and Combine did not receive any significant updates since its introduction in 2019, merely a few stability fixes and a couple of API improvements. The question of whether Combine might soon be discontinued entirely in favor of async/await, or even whether Combine is still relevant now that async/await is available with the same version requirements,¹ regularly appears in articles and on Twitter since WWDC 2021.

I am pretty confident that Combine is here to stay, especially considered its tight relationship with SwiftUI. The Combine API was already comprehensive in 2019 and I think that the fact that no significant updates were made is a proof of maturity, rather than the worrying sign of a decaying framework.

This article might also convince you that async/await and Combine are complementary rather than mutually exclusive. Combine is namely a reactive framework with the concept of back pressure at its heart, while asyc/await and actors provide language constructs for structured concurrency. Both approaches might address common concerns like avoiding concurrent access to mutable states or scalability, but in general they serve different purposes.

A significant time I spend every week as an app developer involves writing or updating code that aggregates data from several sources. I found reactive programming and Combine to be invaluable tools for such tasks. It would certainly be possible to achieve the same results using other approaches but, as this article will hopefully illustrate, Combine provides a formalism with which the obtained code can be both expressive and scalable, whereas other approaches usually quickly lead to code which is hard to maintain. If I were to implement a database access layer or a cache, though, I would rather use actors instead, since safe access to a shared resource is more relevant in this case than reactiveness or back pressure. Different purposes, different tools.

Some people might of course argue that Combine and reactive programming are not easy and that compiler support is not always great, and they would certainly be right. But async/await and actors, or even GCD, are not easy either. Concurrency in general is a hard problem and it is only natural that approaches dealing with it have some learning curve, advantages and drawbacks. Just stay open-minded about which options are available and where they work best to pick the one that will help you write better code. We never had as many great options as we have nowadays, and it would be a shame not to use the one that works best in a specific case.

Data Emitters

It usually does not matter how a data source actually fetches data internally. This might happen through a network request or a database operation, but how the associated network or data access layers are internally implemented is not important. Instead you should treat data sources in your application as opaque data emitters with a well-defined API contract. This contract essentially boils down to what kind of data is emitted, how the process might fail, and whether an emitter delivers data once or several times until possible exhaustion.

With Combine any data emitter can be exposed as a publisher, either because this is how its API was designed in the first place or because some asynchronous API call was wrapped into a Future. The specifics of data delivery are expressed through output and failure generic types, for example:

func profilePublisher(forUserId: String) -> AnyPublisher<Profile, Error>
func filesPublisher(inDirectoryAt: url: URL) -> AnyPublisher<[File], Error>
func lifecycleEventPublisher() -> AnyPublisher<NSNotification, Never>

Data Pipelines

Once you have identified the data emitters you need you can connect them together, ultimately forming a tree-shaped structure describing the entire data delivery process. No matter how complex this tree can be, it can be seen as a data pipeline assembling data from various emitters, transforming and consolidating it along the way, before delivering it to a single endpoint.

Combine provides a rich toolset to build pipelines:

Operators with which you can shape the data, e.g. extracting or formatting a value, or wrapping it into a different type (map, filter, etc.).
Operators with which you can tweak the delivery process (throttle, debounce, etc.).
Operators which gather data before delivering it further (scan, reduce).
Publishers that aggregate other publishers (Publishers.Merge, Publishers.Zip, Publishers.CombineLatest).
And many more…

Using publishers like Publishers.Merge or Publishers.CombineLatest, as well as combinations of operators like map and switchToLatest, a trunk is able to grow branches, which themselves can grow other branches and so forth, allowing you to create abritrarily complex data delivery trees, e.g. to consolidate data associated with a user id:

The process of building a pipeline this way is inherently declarative, as you focus on the description of the data flow rather than on the intricacies of its implementation. Moreover, since any pipeline is itself a publisher, arbitrarily complex pipelines can be treated as opaque data emitters and inserted into other pipelines, in a composite fashion. For example the above pipeline reduces to a single user data emitter and can therefore be used in a pipeline fetching several user ids and consolidating the result as a view model state:

Triggers and Signals

Some data emitters in a pipeline might deliver data in pages of results. Traditional examples include network or database requests, as usually only partial results can be retrieved at a time, not the whole result set at once. When additional pages of results need to be loaded on-demand (e.g. when the user reaches the bottom of a list), it would be tempting to use a secondary pipeline for retrieving the subsequent pages of results. This approach, often applied in imperative block-based network code, can of course be applied with reactive pipelines, but suffers from similar drawbacks:

A pointer to the next retrievable page must be stored as a mutable state external to the pipelines.
The results must be consolidated between the two pipelines, again via an external mutable state.
Cancellation must be properly coordinated. In our example, if a reload is triggered for the first pipeline while the secondary pipeline is still retrieving the next page of results, then both pipelines must likely be reset so that the overall state remains consistent.

This approach does not scale well, since more states need to be added and synchronized as the number of paginated emitters increases. To make things worse, and due to the usually concurrent nature of data retrieval, extra care is required when accessing all these shared mutable states.

With the help of a few additions, though, reactive programming and Combine make it possible to eliminate these issues entirely. If we namely only keep the first pipeline describing the whole data delivery process (without pagination), we can directly build pagination into this pipeline if we are able to ask any publisher directly for more results when needed. Updated results will then flow through the usual pipeline and deliver a consolidated update consistently.

For example, if the document and address publishers in the above example both support pagination, all we need to add pagination support is a way to contact these two data emitters directly when more data is required:

The idea of contacting a publisher directly can be neatly implemented using signals and triggers. A signal is a publisher whose values we are not interested in (Void), which never fails, and whose only purpose is therefore to signal that something happened, for example:

func networkReachableAgainSignal() -> AnyPublisher<Void, Never>

A trigger, on the other hand, is a communication device with a set of associated signals, which it can contact on-demand so that they emit a value. Being publishers, signals associated with a trigger can be inserted into any pipeline at design time to define control points which can be activated on-demand later on.

Implementing triggers and associated signals is straightforward:

struct Trigger {
    typealias Index = Int
    typealias Signal = AnyPublisher<Void, Never>
    
    private let sender = PassthroughSubject<Index, Never>()
    
    func signal(activatedBy index: Index) -> Signal {
        return sender
            .filter { $0 == index }
            .map { _ in }
            .eraseToAnyPublisher()
    }
    
    func activate(for index: Index) {
        sender.send(index)
    }
}

By leveraging publishers to implement communication between triggers and signals we ensure that no state or multithreading issues arise, as all the heavy lifting is entirely managed by Combine itself.

Now assume we are equipped with a trigger:

let trigger = Trigger()

We can create an associated signal publisher for some identifier:

let signal = trigger.signal(activatedBy: 1)

which will emit a value when activated by the trigger:

trigger.activate(for: 1)

Note that we use integers as identifiers, but we can simply use any hashable type as well with the help of the following extension:

extension Trigger {
    func signal<T>(activatedBy t: T) -> Signal where T: Hashable {
        return signal(activatedBy: t.hashValue)
    }

    func activate<T>(for t: T) where T: Hashable {
        activate(for: t.hashValue)
    }
}

With triggers and signals now defined, let us see how they can be used to implement publishers supporting pagination.

Paginated Publishers

Assume we have some paginated publisher which returns items for a specific page, as well as a next page which can be used to load the next page of results (if any):

func itemsPublisher(at page: Page?) -> AnyPublisher<(items: [Items], next: Page?), Error>

The first page of results can be obtained with page set to nil, and the next page is set to nil when all results have been returned. The publisher might internally retrieve results from a web service or from a database, and the next page might be extracted from the data itself, from a database cursor or from a response HTTP headers, but this is not important to our present discussion.

We cannot use this publisher as is in a complex declarative data pipeline, as the page parameter would require some state to be stored externally, as discussed in the previous section. But what if we could have the publisher itself manage this state internally?

This is exactly what we can achieve with triggers and signals. Let us namely define a helper publisher which takes a signal bound to a trigger as parameter. Since pagination is not necessarily desired in all cases we define this parameter as optional:

func itemsPublisher(at page: Page?, paginatedBy paginator: Trigger.Signal?) -> AnyPublisher<(items: [Items], next: Page?), Error>

If we could find a way to have this publisher enter a dormant state each time a page of results has been emitted, we could wake it up when a new page of results is desired, so that pagination can be entirely managed by the publisher implementation, eliminating the need for external states. This is actually possible if we introduce a wait(untilOutputFrom:) operator which, as its name suggests, simply waits for another signal to emit a value:

extension Publisher {
    func wait<S>(untilOutputFrom signal: S) -> AnyPublisher<Self.Output, Self.Failure> where S: Publisher, S.Failure == Never {
        return prepend(
            Empty(completeImmediately: false)
                .prefix(untilOutputFrom: signal)
        )
        .eraseToAnyPublisher()
    }
}

Using this new operator we can manage pagination entirely within our helper publisher implementation:

func itemsPublisher(at page: Page?, paginatedBy paginator: Trigger.Signal?) -> AnyPublisher<(items: [Items], next: Page?), Error> {
    return itemsPublisher(at: page)
        .map { result -> AnyPublisher<(items: [Items], next: Page?), Error> in
            if let paginator = paginator, let next = result.next {
                return itemsPublisher(at: next, paginatedBy: paginator)
                    .wait(untilOutputFrom: paginator)
                    .retry(.max)
                    .prepend(result)
                    .eraseToAnyPublisher()
            }
            else {
                return Just(result)
                    .setFailureType(to: Error.self)
                    .eraseToAnyPublisher()
            }
        }
        .switchToLatest()
}

This implementation deserves a few words of explanation:

If a paginator has been provided and a next page is available we return the result immediately (prepend) and recursively prepare the request for the subsequent page of results, whose delivery is controlled by a wait (the pipeline must be read from the bottom to the top here). We also insert a retry(.max) so that, in the event a request fails, the trigger can be used to perform new attempts.
Otherwise we just return the result we have and the publisher completes.

This helper publisher can finally be used to implement the paginated item publisher we need, which can be inserted into any pipeline and controlled externally when more results are needed:

func itemsPublisher(paginatedBy paginator: Trigger.Signal? = nil) -> AnyPublisher<[Item], Error> {
    return itemsPublisher(at: nil, paginatedBy: paginator)
        .map(\.items)
        .eraseToAnyPublisher()
}

Now that have discussed how triggers and signals can be used to insert control points into any declarative pipelines, let us discuss how signals can be also used to refresh an entire pipeline or subset thereof.

Refresh Publishers

Let us assume we have some pipeline delivering data to a view model the first time its associated view is displayed, and that this process can fail (e.g. because network requests are somehow involved):

func dataPublisher() -> AnyPublisher<Data, Error>

An application should in general be able to execute this pipeline again, most notably:

When the user manually reloads the screen (e.g. pull-to-refresh).
When the application returns to the foreground, so that data is up to date.
When the network is reachable again, so that the application can automatically recover from network failure or ensure data is up to date.

It is tempting to recreate the publisher again in such cases, but there is in fact a better way. If we namely realize that the above events can be translated into corresponding signal publishers, we can namely build these events right into our original reactive pipeline.

Assume we have wrapped the above events into publishers with the following signatures:

func reloadSignal() -> AnyPublisher<Void, Never>
func foregroundSignal() -> AnyPublisher<Void, Never>
func networkReachableAgainSignal() -> AnyPublisher<Void, Never>

We can use any of these signals to force our pipeline or a subset thereof to be executed or repeated when they emit a value, provided we introduce the following publisher helpers:

extension Publishers {
    static func Publish<S, P>(onOutputFrom signal: S, _ publisher: @escaping () -> P) -> AnyPublisher<P.Output, P.Failure> where S: Publisher, P: Publisher, S.Failure == Never {
        return signal
            .map { _ in }
            .setFailureType(to: P.Failure.self)          // Required for iOS 13, can be removed for iOS 14+
            .map { _ in
                return publisher()
            }
            .switchToLatest()
            .eraseToAnyPublisher()
    }
    
    static func PublishAndRepeat<S, P>(onOutputFrom signal: S, _ publisher: @escaping () -> P) -> AnyPublisher<P.Output, P.Failure> where S: Publisher, P: Publisher, S.Failure == Never {
        return signal
            .map { _ in }
            .prepend(())
            .setFailureType(to: P.Failure.self)          // Required for iOS 13, can be removed for iOS 14+
            .map { _ in
                return publisher()
            }
            .switchToLatest()
            .eraseToAnyPublisher()
    }
}

The first publisher only executes the wrapped publisher when a signal emits a value, while the second one always executes the wrapped publisher at least once (a value is namely prepended to the pipeline), repeating the process each time a signal emits a value.

Equipped with these publishers it is straightforward to have dataPublisher() execute once and repeat when, for example, a reload is made:

Publishers.PublishAndRepeat(onOutputFrom: reloadSignal()) {
    return dataPublisher()
}

We can even respond to any of the above listed signals by merging them together first:

func consolidatedReloadSignal() -> AnyPublisher<Void, Never> {
    return Publishers.MergeMany(
        reloadSignal(),
        foregroundSignal(),
        networkReachableAgainSignal()
    )
    .eraseToAnyPublisher()
}

then using the consolidated signal instead:

Publishers.PublishAndRepeat(onOutputFrom: consolidatedReloadSignal()) {
    return dataPublisher()
}

Accumulators

Suppose we want to build a Netflix-like homepage whose main structure is made of different topic rows (e.g. Comedy, Drama, Documentaries, etc.), each one presenting a list of associated medias. The topic list and medias for each topic are retrieved from a webservice through associated data emitters:

func topics() -> AnyPublisher<[Topic], Error>
func medias(forTopicId topicId: String) -> AnyPublisher<[Media], Error>

delivering instances of the following types:

struct Topic {
    var id: String
    var title: String
    // ...
}

struct Media {
    var id: String
    var title: String
    // ...
}

We want to design a pipeline retrieving topics and their associated medias, consolidating them into rows:

struct Row {
    let topic: Topic
    let medias: [Media]
}

Since the number of topics is not known beforehand we cannot directly use Publishers.CombineLatest to retrieve medias once the topic list is known, as Publishers.CombineLatest does not support arbitrary lists of publishers (currently only 2, 3 or 4 publishers are supported, though variadic generics might lift this restriction in the future).

With simple bissection, though, we can implement a Publishers.AccumulateLatestMany publisher which supports an arbitrary number of publishers, returning their output in order as an array rather than as a tuple:

extension Publishers {
    static func AccumulateLatestMany<Upstream>(_ publishers: Upstream...) -> AnyPublisher<[Upstream.Output], Upstream.Failure> where Upstream: Publisher {
        return AccumulateLatestMany(publishers)
    }
    
    static func AccumulateLatestMany<Upstream, S>(_ publishers: S) -> AnyPublisher<[Upstream.Output], Upstream.Failure> where Upstream: Publisher, S: Swift.Sequence, S.Element == Upstream {
        let publishersArray = Array(publishers)
        switch publishersArray.count {
        case 0:
            return Just([])
                .setFailureType(to: Upstream.Failure.self)
                .eraseToAnyPublisher()
        case 1:
            return publishersArray[0]
                .map { [$0] }
                .eraseToAnyPublisher()
        case 2:
            return Publishers.CombineLatest(publishersArray[0], publishersArray[1])
                .map { t1, t2 in
                    return [t1, t2]
                }
                .eraseToAnyPublisher()
        case 3:
            return Publishers.CombineLatest3(publishersArray[0], publishersArray[1], publishersArray[2])
                .map { t1, t2, t3 in
                    return [t1, t2, t3]
                }
                .eraseToAnyPublisher()
        default:
            let half = publishersArray.count / 2
            return Publishers.CombineLatest(
                AccumulateLatestMany(Array(publishersArray[0..<half])),
                AccumulateLatestMany(Array(publishersArray[half..<publishersArray.count]))
            )
            .map { array1, array2 in
                return array1 + array2
            }
            .eraseToAnyPublisher()
        }
    }
}

With the help of Publishers.AccumulateLatestMany we can now write a publisher for our Netflix-like homepage:

func rowsPublisher() -> AnyPublisher<[Row], Error> {
    return topics()
        .map { topics in
            return Publishers.AccumulateLatestMany(topics.map { topic in
                return medias(forTopicId: topic.id)
                    .map { Row(topic: topic, medias: $0) }
            })
        }
        .switchToLatest()
        .eraseToAnyPublisher()
}

This publisher is kept as simple as possible but could be improved in several ways:

Since Publishers.AccumulateLatestMany is based on Publishers.CombineLatest, a result is only delivered by the pipeline once all rows could be loaded. In general, though, we would prefer delivering rows as they are retrieved. This behavior can be implemented by immediately emitting a row before performing the medias(forTopicId:) request using the prepend operator.
Similarly, if a media request fails for some topic, the entire pipeline fails. Again this can be improved by using replaceError to emit a row instead.

A good row value to use in both cases is a list of placeholder medias, or a list of previously retrieved medias. Please have a look at the sample code associated with this article to see how this can be achieved in practice.

Advanced Pipeline Design

With triggers, signals, refresh publishers, accumulators and a recipe to implement paginated publishers, we can now write a single declarative pipeline for our Netflix-like homepage which not only retrieves topics and their medias in order, but also supports global reloads and individual pagination per topic.

Let us assume that media lists per topic support pagination. We can augment the API contract to support pagination via trigger and signals as described in the Paginated Publishers section:

func topics() -> AnyPublisher<[Topic], Error>
func medias(forTopicId topicId: String, paginatedBy paginator: Trigger.Signal? = nil) -> AnyPublisher<[Media], Error>

On a Netflix-like homepage, where media lists are displayed as horizontally scrollable rows for each topic, we want to be able to load more content when the user scrolls to the end of a row. Moreover, we want a pull-to-refresh to be available so that the user can reload the entire screen when desired. Let us introduce a hashable enum describing these use cases:

enum TriggerId: Hashable {
    case reload
    case loadMore(topicId: String)
}

Also assume we have a trigger stored somewhere:²

let trigger = Trigger()

We can now enhance our rowsPublisher() pipeline to add support for global reloads and pagination in each section:

func rowsPublisher() -> AnyPublisher<[Row], Error> {
    return Publishers.PublishAndRepeat(onOutputFrom: trigger.signal(activatedBy: TriggerId.reload)) { [trigger] in
        return topics()
            .map { topics in
                return Publishers.AccumulateLatestMany(topics.map { topic in
                    return medias(forTopicId: topic.id, paginatedBy: TriggerId.loadMore(topicId: topic.id))
                        .scan([]) { $0 + $1 }
                        .map { Row(topic: topic, medias: $0) }
                })
            }
            .switchToLatest()
            .eraseToAnyPublisher()
    }
}

Only three changes were required in comparison to the pipeline we obtained at the end of the Accumulators section:

Publishers.PublishAndRepeat ensures the pipeline is executed once and repeated when a reload is triggered.
A paginator signal is provided to medias(forTopicId:paginatedBy:) so that more medias can be loaded for any topic, independently and on-demand.
scan is used to gather pages of medias returned by the paginated medias(forTopicId:paginatedBy:) publisher.

We proceeded here like you would in practice, namely by starting with a basic pipeline implementing the nominal case, then inserting signals where appropriate to deliver more data or repeat part or the entirety of the pipeline. This approach is especially nice, as it allows a pipeline to be gradually enhanced with surgical code changes. Think about the code you would have written if you had to do the same with block-based APIs and you will probably better understand the advantages of this approach.

Even better, you can very easily throttle data delivery (e.g. to avoid signals triggering too many unnecessary reloads in part of the pipeline) or use debouncing to add some delay (e.g. if a signal is bound to keyboard input), with only a few additional operator insertions. This is an area where reactive programming really shines in comparison to more imperative approaches which would require much more convoluted code to be written.

Declarative Data Pipelines and View Models

Declarative data pipelines are especially useful when writing view models conforming to ObservableObject. Since pipelines deliver consolidated results they can be immediately wired to a published state property so that the view automatically reflects its changes.

For example our Netflix-like homepage could be driven by the following view model, which is based on our rowsPublisher() from the previous section, whose result is wrapped into a State:

final class HomepageViewModel: ObservableObject {
    enum State {
        case loading
        case loaded(rows: [Row])
        case failure(error: Error)
    }

    @Published private(set) var state: State = .loading
    
    private let trigger = Trigger()
    
    init() {
        Publishers.PublishAndRepeat(onOutputFrom: consolidatedReloadSignal()) { [trigger] in
            return topics()
                .map { topics in
                    return Publishers.AccumulateLatestMany(topics.map { topic in
                        return medias(forTopicId: topic.id, paginatedBy: TriggerId.loadMore(topicId: topic.id))
                            .scan([]) { $0 + $1 }
                            .map { Row(topic: topic, medias: $0) }
                    })
                }
                .switchToLatest()
                .map { State.loaded(rows: $0) }
                .catch { error in
                    return Just(State.failure(error: error))
                }
                .eraseToAnyPublisher()
        }
        .receive(on: DispatchQueue.main)
        .assign(to: &$state)
    }
    
    func reload() {
        trigger.activate(for: TriggerId.reload)
    }

    func loadMore(for topic: Topic) {
        trigger.activate(for: TriggerId.loadMore(topicId: topic.id))
    }

    private func consolidatedReloadSignal() {
        return Publishers.Merge(
            trigger.signal(activatedBy: TriggerId.reload),
            networkReachableAgainSignal(),
            foregroundSignal()
        )
        .eraseToAnyPublisher()
    }
}

By assigning the publisher to the state property publisher using the assign(to:) operator, we bind the lifetime of our pipeline to the lifetime of the state property and therefore to the HomepageViewModel instance itself. This ensures correct resource management without the need for explicit cancellables. We also catch errors and replace them with a new publisher so that the pipeline never finishes, even in case of failure.

Here is a visual representation of the pipeline, with reloads and pagination indicated:

Just take a deep breath and consider which features the above view model provides in ~50 lines of code:

The model delivers state updates in a reactive way, with loading and failure states, as well as a loaded state with the relevant content attached.
It performs a request for topics and, for each one, performs another request to gather medias associated with it.
It provides support for reloading, either in response to user interaction (e.g. pull-to-refresh) or in response to application environment changes.
More medias can be individually loaded for each topic (as the user scrolls, for example).
If a reload occurs while more medias are still being loaded for one or several rows, all pipelines are properly cancelled accordingly.

Remark

There is no way to cancel subscriptions made with the assign(to:) operator since no AnyCancellable is returned. This means that associated subscriptions remain valid until the parent ObservableObject is deinitialized.

Also note that calling assign(to:) several times on the same published property does not replace existing subscriptions. New subscriptions will pile up instead, which is why you should avoid code that calls assign(to:) unnecessarily.

For these reasons declaring a reactive pipeline from a designated intializer is a good practice, especially when this pipeline is wired to a published property using assign(to:).

Sometimes a pipeline might depend on parameters supplied by the user, though, for example a search criterium or a username and password pair. Such parameters are not known at initialization time and you might wonder how their updated values can be provided to an existing pipeline. The next section will show you how this can be achieved.

User-driven Data Emitters

Assume our example webservice provides an additional endpoint to search medias using some query and additional settings. We introduce a corresponding data emitter:

func medias(matchingQuery query: String, settings: Settings) -> AnyPublisher<[Media], Error>

with settings letting the user pick a date range or a sort order, for example:

struct Setting {
    let dateRange: DateRange?
    let ascending: Bool
    // ...
}

In most scenarios the above emitter would likely support pagination as described in the Paginated Publishers section, but this is left as an exercise for the reader. As usual the details of the data emitter implementation are not important, only its signature is.

Similar to what we did in the previous section we can now implement the view model of a basic search screen. This view model must support query and setting updates made by the user. We declare a pipeline in the view model initializer, starting our implementation with constant query and settings:

final class SearchViewModel: ObservableObject {
    enum State {
        case loading
        case loaded(medias: [Media])
        case failure(error: Error)
    }

    let query = ""
    let settings = Settings()

    @Published private(set) var state: State = .loading
    
    init() {
        Publishers.PublishAndRepeat(onOutputFrom: consolidatedReloadSignal()) { [query, settings] in
            return medias(matchingQuery: query, settings: settings)
                .map { State.loaded(medias: $0) }
                .catch { error in
                    return Just(State.failure(error: error))
                }
                .eraseToAnyPublisher()
        }
        .receive(on: DispatchQueue.main)
        .assign(to: &$state)
    }

    // ...
}

We implement pull-to-refresh and respond to the application being woken up by using the same consolidatedReloadSignal() signal introduced in the previous section (details are therefore omitted here). Note that the use of Publishers.PublishAndRepeat(onOutputFrom:) requires the query and settings to be accessible within the associated closure, which is here achieved through a capture list.

The query and settings must support updates made by the user, but simply turning associated properties into vars does not work:

Since String and Settings are value types, their initial value is captured. Updates will never be visible in the closure.
There is no way to reload the pipeline in response to these values being changed.

The need to respond to change is a hint about how we can solve both problems. Instead of simple mutable properties, let us namely introduce @Published properties:

final class SearchViewModel: ObservableObject {
    // ...

    @Published var query = ""
    @Published var settings = Settings()

    // ...
}

The publishers associated with these properties can now be captured and inserted into the pipeline so that search results are updated when the query or settings change:

final class SearchViewModel: ObservableObject {
    enum State {
        case loading
        case loaded(medias: [Media])
        case failure(error: Error)
    }

    @Published var query = ""
    @Published var settings = Settings()

    @Published private(set) var state: State = .loading
    
    init() {
        Publishers.PublishAndRepeat(onOutputFrom: consolidatedReloadSignal()) { [$query, $settings] in
            Publishers.CombineLatest($query, $settings)
                .map { query, settings in
                    return medias(matchingQuery: query, settings: settings)
                }
                .switchToLatest()
                .map { State.loaded(medias: $0) }
                .prepend(State.loading)
                .catch { error in
                    return Just(State.failure(error: error))
                }
                .eraseToAnyPublisher()
        }
        .receive(on: DispatchQueue.main)
        .assign(to: &$state)
    }

    // ...
}

The above code deserves a brief explanation:

Query and setting publishers are assembled using Publishers.CombineLatest so that any update received from them triggers a new search. Note that Publishers.CombineLatest requires each involved publisher to emit a value before emitting its first value, which is here guaranteed since @Published publishers provide their initial value automatically upon subscription. The pipeline therefore always executes once.
A usual map and switchToLatest combination is used to produce a single request matching the latest search parameters, ensuring prior requests are properly discarded.
The prepend operator is used to reset the state to State.loading before each new search attempt.

As usual we can easily tweak this pipeline further, for example to avoid performing a new request if the query did not change, or to ensure requests are not immediately sent while the user is still typing or updating search settings:

final class SearchViewModel: ObservableObject {
    enum State {
        case loading
        case loaded(medias: [Media])
        case failure(error: Error)
    }

    @Published var query = ""
    @Published var settings = Settings()

    @Published private(set) var state: State = .loading
    
    init() {
        Publishers.PublishAndRepeat(onOutputFrom: consolidatedReloadSignal()) { [$query, $settings] in
            Publishers.CombineLatest($query.removeDuplicates(), $settings)
                .debounce(for: 0.3, scheduler: DispatchQueue.main)
                .map { query, settings in
                    return medias(matchingQuery: query, settings: settings)
                }
                .switchToLatest()
                .map { State.loaded(medias: $0) }
                .prepend(State.loading)
                .catch { error in
                    return Just(State.failure(error: error))
                }
                .eraseToAnyPublisher()
        }
        .receive(on: DispatchQueue.main)
        .assign(to: &$state)
    }

    // ...
}

Conclusion

In this article we illustrated how reactive programming and Combine can be used to build data delivery pipelines in a declarative way. The strategies we elaborated are not only scalable, but also eliminate challenges associated with shared mutable states. This neatly avoid issues commonly encountered when aggregating several asynchronous data sources using imperative block-based or async/await-based approaches.

Key concepts we introduced are signals and triggers, which can be inserted as control points into any pipeline, as well as a wait(untilOutputFrom:) operator which can be used to implement publishers natively supporting signal-based pagination. We also introduced Publishers.AccumulateLatestMany to solve limitations of Publishers.CombineLatest, especially when an arbitrary number of publishers must deliver their results in a specific order.

Finally, we applied this declarative formalism to view model building, opening the door to implementations where view and view models are built declaratively.³ Exactly like a SwiftUI View is a view recipe, focusing on the desired result rather than on its actual implementation, a declarative pipeline is namely a data delivery recipe and as such is a perfect fit for view models.

The approach discussed in this article has of course a few drawbacks. Combine and reactive programming have a steep learning curve, and compiler messages might be cryptic, though experience definitely helps. Pipeline design also requires special care, as it can be quite surgical. There is definitely an entry fee involved, but hopefully this article helped you realize the return might be worth the investment.

Finally, and though this discussion was focused on reactive programming with Combine, all the concepts introduced in this article could likely be transposed to any other declarative framework. For this reason I hope this article can be insightful outside Apple or Swift development communities as well, or useful to people using reactive frameworks like ReactiveSwift or RxSwift.

Sample Code

Sample code is provided on GitHub. The Combine toolset built in this article is provided as a Swift package associated with the project, which implements a basic Netflix-like homepage as described in this article, and built using SwiftUI. The underlying view model includes a few improvements in comparison to the one discussed in this article, mostly to display placeholders while loading content or if a media list cannot be loaded for some reason.

As of Xcode 13.2 async/await are backward compatible with the same minimum OS versions as Combine. ↩
Recall that we use a global scope for simplicity, but in this case trigger and row publishers would likely be stored in a class (therefore the capture list used to make trigger accessible within the block). ↩
SwiftUI or UIKit diffable data sources and compositional layouts, for example, nicely support this philosophy. ↩

Understanding SwiftUI Layout Behaviors

2021-06-03T00:00:00+00:00

The SwiftUI layout system is more predictable and easier to understand than UIKit layout system. But this does not mean how it works is entirely straightforward.

For newcomers with no preconception of how layout historically worked on Apple platforms, official documentation about the SwiftUI layout system might namely be incomplete or obscure. The number of views and modifiers, as well as their various behaviors, can be quite overwhelming. Even for seasoned UIKit developers it can be difficult to figure out how SwiftUI layout system works, as its core principles are quite different from UIKit well-known concepts of Auto Layout constraints, springs and struts.

This article explores the essential rules and behaviors of the SwiftUI layout system and explains how you should reason about it. It also introduces a formalism that helps characterize views and their sizing behaviors in general. It finally provides a list of the sizing behaviors for most SwiftUI built-in views.

View Categories
The SwiftUI Layout Process
Sizing Behaviors
Decorator Views and Modifiers
Determining the Intrinsic Sizing Behavior of a View
Ambiguous Layouts
Sizing Behaviors in View Hierarchies
Altering Sizing Behaviors
Layout Priorities
Sizing SwiftUI Views
UIViewRepresentable and UIViewControllerRepresentable
Layout Advice
TL;DR
View Taxonomy

View Categories

SwiftUI views all belong to either one of the following categories:

Simple views which do not take another view (or view builder) as parameter, like Text or Image.
Composed views which take another view or a view builder as parameter, like VStack or Toggle.

Layouts themselves are simply created by assembling simple views and composed views in arbitrarily complex hierarchies.

The SwiftUI Layout Process

When a parent must lay out one of its child views it proceeds in three steps, very well explained in articles from Alex Grebenyuk and Paul Hudson:

The parent offers some size to the child view.
The child view decides the size it requires, eventualy taking into account the parent size offer (a hint which the child is free to ignore entirely). It then returns the size it requires to its parent.
The parent lays out the child somewhere, strictly respecting the size that the child requested.

Examples

Size offers and child view placements vary depending on the expected result, for example:

A Painting might draw some ostentatious painting frame around its edges, and offers the rest to a single child view centered in it.
A Border might offer its entire size to a single child view and adds a 1-pixel border on top of it.
A Plane might be made of two coordinate axes, equally offering a fourth of its size to four child views, each one drawn in a quadrant. Child views are positioned in their respective quadrant with different alignments (bottom left for the 1st, bottom right for the 2nd, top right for the 3rd and top left for the 4th), so that one of their corners coincides with the origin.

Sizing Behaviors

During step 2 of the layout process children must decide the size they need before communicating it to their parent. We call sizing behaviors¹ the various possibilities with which a view can decide the size it needs. Note that views might have different sizing behaviors in the horizontal and vertical directions. Knowing which sizing behavior is adopted by a view and how it affects the layout process is crucial in understanding how SwiftUI assigns sizes and positions to views.

Usually a view exhibits one of the two following concrete opposite sizing behaviors:

Expanding (exp): The view strives to match the size offered by its parent.
Hugging (hug): The view chooses the best size to fit its content without consulting the size offered by its parent.

If a view is expanding in a single direction it must match the size offered by its parent in this direction so that it can scale when the parent does. But if a view expands in horizontal and vertical directions at the same time it must only fulfill the size offered by its parent in at least one direction.² Child views are namely ultimately responsible of deciding alone which size they want. If they are expanding in all directions they must still match the size offered by their parent in at least one direction (so that they can scale when the parent does), but they remain free to choose the size in the other direction if they do not want to stretch.³

A third abstract behavior must be introduced for composed views, whose behavior depend on their children behavior:

Neutral (neu): The view adjusts its sizing behavior based on the behaviors of its children, adopting hugging behavior if and only if all its children have hugging behavior, otherwise expanding behavior.

These three sizing behaviors describe intrinsic properties of views, which means they apply to views considered in isolation. In concrete situations, though, views are part of a layout hierarchy. When a view is part of a hierarchy only expanding and hugging behaviors ultimately apply. Neutral behavior must therefore be seen a behavioral placeholder for expanding or hugging behaviors, with no existence in concrete hierarchies.

In the following we might sometimes use h-exp, v-exp, h-hug, v-hug, h-neu and v-neu as shorthands for all possible intrinsic behaviors in horizontal (h) and vertical (v) directions respectively.

Decorator Views and Modifiers

Composed views containing a single child are special. They namely behave like decorators, possibly altering or preserving the decorated view behavior:

A composed view with hugging behavior in some direction provides its child with a fixed content proposal in this direction.
A composed view with expanding behavior in some direction provides its child with the maximal content proposal it can afford in this direction.
A composed view with neutral behavior in some direction transparently adopts the behavior of its child in the same direction.

SwiftUI makes extensive use of decorators for defining modifiers. Each modifier has an associated private composed view wrapper, returned as an opaque type from the view modifier. Modifiers are therefore mostly syntactic sugar and include iconic examples like View/frame(width:height:) or View/aspectRatio(_:contentMode:).

Determining the Intrinsic Sizing Behavior of a View

You can probe the sizing behavior of a view to determine its intrinsic sizing behavior, even if you don’t have access to its implementation. The procedure to follow depends on the category the view belongs to.

Probing Intrinsic Sizing Behavior for Simple Views

To determine the sizing behavior of a simple view use a sufficiently large canvas, attach a border to the simple view, and observe where the border is displayed:

struct SimpleView_Previews: PreviewProvider {
    static var previews: some View {
        SimpleView(...)
            .border(Color.blue, width: 3)
            .previewLayout(.fixed(width: 1000, height: 1000))
    }
}

If the border is close to the simple view for some direction it has hugging behavior in this direction, otherwise expanding behavior.

With this method it can be verified that Text has hugging behavior in all directions, while Color has expanding behavior in all directions:

Probing Intrinsic Sizing Behavior for Composed Views

To determine the behavior of a composed view use a sufficiently large canvas, attach a border to the composed view, and observe where the border is displayed when the composed view wraps an expanding child view, respectively a hugging child view. Text and Color are ideal child candidates as they let us probe both horizontal and vertical behaviors at the same time:

struct ComposedView_Previews: PreviewProvider {
    static var previews: some View {
        Group {
            ComposedView(...) {
                Color.red
                    .border(Color.green, width: 3)
            }
            ComposedView(...) {
                Text("Test")
                    .border(Color.green, width: 3)
            }
        }
        .border(Color.blue, width: 3)
        .previewLayout(.fixed(width: 1000, height: 1000))
    }
}

If expanding, respectively hugging behavior is observed for the composed view when its child is expanding, respectively hugging in some direction, this means the composed view has neutral behavior in this direction, as it adopts the behavior of its child.

If on the other hand the composed view ignores its child behavior for some direction, then it must either have expanding or hugging behavior in this direction. Simply apply the procedure for simple views to determine the intrinsic composed view behavior in this case.

With this method it can be verified that a Toggle wrapping some View label:

struct ComposedView_Previews: PreviewProvider {
    static var previews: some View {
        Group {
            Toggle(isOn: .constant(true)) {
                Color.red
                    .border(Color.green, width: 3)
            }
            Toggle(isOn: .constant(true)) {
                Text("Option")
                    .border(Color.green, width: 3)
            }
        }
        .border(Color.blue, width: 3)
        .previewLayout(.fixed(width: 1000, height: 1000))
    }
}

has expanding behavior horizontally, but neutral behavior vertically:

Probing Modifiers

Modifiers return opaque composed views (as they are meant to augment the view they are applied on). Probing a modifier is therefore achieved in the same way as for composed views:

struct Modifier_Previews: PreviewProvider {
    static var previews: some View {
        Group {
            Color.red
            Text("Test")
        }
        .border(Color.green, width: 3)
        .modifier(...)
        .border(Color.blue, width: 3)
        .previewLayout(.fixed(width: 1000, height: 1000))
    }
}

With this method it can be verified that applying the frame(maxWidth: .infinity) modifier creates an expanding horizontal frame with neutral vertical behavior:

Thoroughly probing the View/frame(minWidth:idealWidth:maxWidth:minWeight:idealHeight:maxHeight:alignment:) modifier is achieved by probing its behavior for other values of maxWidth and maxHeight. The observed behavior is characterized in the View Taxonomy section.

Ambiguous Layouts

One of the biggest advantages of SwiftUI over Auto Layout is the fact that layouts can never break. Every seasoned UIKit developer has experienced Auto Layout failing when layouts are over- or underdetermined, yielding unpredictable results and logging horrendous messages to the console. This never occurs with SwiftUI.

This does not mean that ambiguities do not exist in SwiftUI layouts, though. When the SwiftUI layout engine encounters an ambiguity it simply assigns a magical value of 10 to view dimensions it could not properly determine. The layout succeeds and no issues are reported, though of course the result obtained is not the expected one.

Such situations usually occur when a parent view wants to size itself based on the size of its children, but those children exhibit expanding behavior and thus want to match the parent size. This creates a chicken-and-egg problem which SwiftUI solves by replacing undetermined sizes with 10, as can be seen with the simple following code:

struct Undetermined_Size_Previews: PreviewProvider {
    static var previews: some View {
        Color.red
            .fixedSize()
    }
}

Since Color has h-exp and v-exp behavior, the View/fixedSize() modifier cannot figure out the intrinsic size it needs to apply, using 10 as fallback in both directions.

Therefore, when you see some size of 10 popping somewhere in your layout for unknown reasons, this usually means that a similar chicken-and-egg problem exists with the involved view and its parent. Nothing will break or throw an exception, but you should still have a look at why the problem exists in the first place and lift the associated ambiguity, for example by applying a frame modifier which will provide the child with a well-defined size.

Sizing Behaviors in View Hierarchies

Layouts are created by assembling simple and composed views with various sizing behaviors together. Associated with composed views only, the neutral sizing behavior is a placeholder for expanding or hugging behavior, though. Before you can understand how some layout works in practice, you therefore must determine which behavior some neutral behavior translates into, depending on the behavior of its children.

Finding the true nature of a neutral behavior is typically achieved in a top-bottom / bottom-up fashion. Starting from a composed view with undetermined neutral behavior you consider the behavior of its children, recursively applying the same strategy when you encounter another view with composed behavior. Once the behavior of all children contained in a composed view is known the behavior of the parent view itself can be determined.

This process might seem cumbersome but is thankfully theoretical in most cases. As SwiftUI views are usually small reusable units for which the behavior is known or can be quickly determined, the process above should in practice only involve a brief look at the children of some composed view to guess its overall behavior.

To speed up the process of identifying neutral behaviors, it might still be useful to document custom views in your code so that their behavior can be quickly guessed from their documentation, for example:

/// Intrinsic sizing behavior: h-exp, v-exp
struct CalendarView: View {
    // ...
}

/// Intrinsic sizing behavior: h-exp, v-hug
struct SegmentedControl: View {
    // ...
}

// Tag is a "Dual-Category View", see corresponding paragraph in the View Taxonomy section
struct Tag<Label: View>: View {
    /// Intrinsic sizing behavior: h-neu, v-neu
    init(@ViewBuilder label: @escaping () -> Label) {
        // ...
    }
    
    /// Intrinsic sizing behavior: h-hug, v-hug
    init(_ titleKey: LocalizedStringKey) where Label == Text {
        // ...
    }
}

extension View {
    /// Intrinsic sizing behavior: h-neu, v-neu
    func ornatePictureFrame() -> some View {
        // ...
    }
}

Altering Sizing Behaviors

When the behavior of a SwiftUI view is not the one you want you cannot alter its properties directly, as views themselves are value types and thus immutable. Instead you wrap the view with unsatisfying behavior into another one to obtain the desired behavior. This is usually achieved using some public composed view (e.g. a stack) or by applying a modifier.

You can refer to the View Taxonomy section to help you decide which modifier can be helpful to achieve the desired behavior.

Layout Priorities

Layout priorities do not change the sizing behavior of a view. They merely are used by composed parent views to decide which child they should propose a size first.

For this reason this article will not further discuss layout priorities. You can read the dedicated article from John Sundell to learn more about this topic.

Sizing SwiftUI Views

If you are wrapping SwiftUI views within UIKit you might be interested to know which size a SwiftUI view requires, depending on the space it can be provided. This can be helpful if the view contains a variable amount of text and you want to provide a matching size to a collection layout in advance, for example.

Fortunately UIHostingController provides a sizeThatFits(in:) method to calculate the intrinsic size of a view, which in facts apply the UIView/sizeThatFits(:) method to its associated view.

Note that if your SwiftUI layout depends on size classes you should inject the size class into the environment when calculating the size, so that the view you probe adopts the correct behavior:

extension View {
    func adaptiveSizeThatFits(in size: CGSize, for horizontalSizeClass: UIUserInterfaceSizeClass) -> CGSize {
        let hostController = UIHostingController(rootView: self.environment(\.horizontalSizeClass, UserInterfaceSizeClass(horizontalSizeClass)))
        return hostController.sizeThatFits(in: size)
    }
}

You can use UIView.layoutFittingExpandedSize to calculate the size required by some SwiftUI view. For example here is how you would calculate the height of SomeView constrained to 800px horizontally, for the regular size class:

let fittingSize = CGSize(width: 800, height: UIView.layoutFittingExpandedSize.height)
let height = SomeView().adaptiveSizeThatFits(in: fittingSize, for: .regular).height

If SomeView has hugging behavior the matching height is returned. If the view has expanding behavior, though, the returned height will be equal to the size offer UIView.layoutFittingExpandedSize.height instead.

Remark

Instead of the visual approach described above you can use UIHostingController and sizeThatFits(in:) to probe view sizing behavior. I like the visual approach better but here is a rough idea how you can check that a VStack has neutral behavior in all directions, using a Swift playground:

struct ComposedViewExpandingTest: View {
    var body: some View {
        VStack {
            Color.red
        }
    }
}

struct ComposedViewHuggingTest: View {
    var body: some View {
        VStack {
            Text("Test")
        }
    }
}

extension View {
    func probedSize() -> CGSize {
        let hostController = UIHostingController(rootView: self)
        return hostController.sizeThatFits(in: UIView.layoutFittingExpandedSize)
    }
}

let expandingSize = ComposedViewExpandingTest().probedSize()
let huggingSize = ComposedViewHuggingTest().probedSize()

let hNeutral = huggingSize.width != UIView.layoutFittingExpandedSize.width && expandingSize.width == UIView.layoutFittingExpandedSize.width
let vNeutral = huggingSize.height != UIView.layoutFittingExpandedSize.height && expandingSize.height == UIView.layoutFittingExpandedSize.height

UIViewRepresentable and UIViewControllerRepresentable

Special considerations are required when considering the sizing behavior of views implemented with UIViewRepresentable or UIViewControllerRepresentable. Such considerations are outside the scope of this article and will be discussed in a separate article.

Layout Advice

When creating layouts you should think about the sizing behavior of the involved views and alter them as required, for example using frame modifiers. You can refer to the View Taxonomy at the end of this article to guess the resulting behavior beforehand.

To avoid messy layouts I recommend to:

Factor out view hierarchies into smaller views with documented sizing behaviors.
Avoid geometry readers, which should be considered only if there are no other possibilities to achieve what you want. View positioning can in general be made in a much cleaner way using frame modifiers.
Avoid fixed Spacers to insert spacings in stacks. In general you can use paddings and nested stacks with proper spacing settings to achieve a better result.

TL;DR

SwiftUI introduces a robust layout system relying on size negociation between parent and children views. Children ultimately choose the size they want based on three possible intrisic sizing behaviors, expanding, hugging and neutral, possibly different in horizontal and vertical directions.

Views involved in a hierarchy effectively only exhibit expanding or hugging behaviors, though. It is the responsibility of the layout system, or yours when you create or inspect layouts, to identify how neutral behaviors ultimately translate into expanding or hugging behaviors in a hierarchy.

To quicker analyze view hiearchies and understand how adding a view to an existing hierarchy might affect the overall result, it might prove helpful to document custom views so that their intrinsic behavior can be quickly read. While this process must be done for custom views, it can be done for SwiftUI built-in views to offer an overview of their respective behaviors.

View Taxonomy

The following taxonomy lists the intrinsic sizing behaviors of most SwiftUI built-in views, and can be used as a reference when inspecting or building layouts.

Each view was probed using one of the procedures outlined in this article. Results were consolidated and presented in several tables, grouping views with similar purposes.

Note that tables not only list behaviors of public view types like Text, but also of opaque types returned by modifiers like Image/resizable(capInsets:resizingMode:) or View/frame(width:height:).

Dual-Category Views

Some views can either be simple views or composed views depending on how they are instantiated. You should be especially careful when using such views, as simply adding a trailing closure to them might change a simple view into a composed view with entirely different layout behaviors (usually switching from hugging to neutral behavior).

Dual-category views include most notably Label, Link, ProgressView, Slider, Stepper and Toggle.

Simple Building Blocks

The following views are commonly used when building any kind of layout.

Type	Category	Horizontal	Vertical
`Color`	Simple	exp	exp
`Divider`	Simple	exp	hug
`Image`	Simple	hug	hug
`Image` from `resizable(capInsets:resizingMode:)` modifier	Simple	exp	exp
`SecureField`	Simple	exp	hug
`Text`	Simple	hug	hug
`TextEditor`	Simple	exp	exp
`TextField`	Simple	exp	hug

Buttons

Button style can be controlled with the Button/buttonStyle(_:) modifier, resulting in different behaviors.

Type	Category	Horizontal	Vertical	Remarks
`Button` (default)	Composed	neu	neu	No style or `DefaultButtonStyle`. Corresponds to `PlainButtonStyle` on iOS and to `BorderedButtonStyle` on tvOS
`Button` (plain)	Composed	neu	neu	`PlainButtonStyle`. No content insets are applied on tvOS
`Button` (bordered, tvOS only)	Composed	neu	neu	`BorderedButtonStyle`. Some content insets are applied
`Button` (card, tvOS only)	Composed	hug	hug	`CardButtonStyle`. ⚠️ This button calls `View/fixedSize(horizontal:vertical:)` on its content

Links

Links can be created with a title String or with a custom label view.

Type	Category	Horizontal	Vertical
`Link`	Simple	hug	hug
`Link` with `Label: View`	Composed	neu	neu

Labels

Labels can be created with a title String and an image / system image, or with two custom views for the title and the icon.

Type	Category	Horizontal	Vertical
`Label`	Simple	hug	hug
`Label` with `Title: View` and `Icon: View`	Composed	neu	neu

Stacks

Stacks are essential components for horizontally and vertically arranging views.

Type	Category	Horizontal	Vertical
`HStack`	Composed	neu	neu
`VStack`	Composed	neu	neu
`ZStack`	Composed	neu	neu
`LazyHStack`	Composed	hug	exp
`LazyVStack`	Composed	exp	hug

Note that lazy stacks have very different sizing behaviors from their standard counterparts. You should therefore be especially careful when you repalce a stack with its lazy counterpart, as this will change its sizing behavior and will likely require some layout adjustments.

Sliders

Sliders can be created with or without associated custom label view.

Type	Category	Horizontal	Vertical	Remarks
`Slider`	Simple	exp	hug
`Slider` with `Label: View`	Composed	exp	hug	Label used only for accessibility; does not participate in the layout

Progress Views

Progress views can be created with or without associated custom label view. Their style can be controlled with the View/progressViewStyle(_:) modifier, resulting in different behaviors.

Type	Category	Horizontal	Vertical	Remarks
`ProgressView` (linear)	Simple	exp	hug	No style, `DefaultProgressViewStyle` or `LinearProgressViewStyle`
`ProgressView` (linear) with `Label: View`	Composed	exp	hug	No style, `DefaultProgressViewStyle` or `LinearProgressViewStyle`. Label used only for accessibility; does not participate in the layout
`ProgressView` (circular)	Simple	hug	hug	`CircularProgressViewStyle`
`ProgressView` (circular) with `Label: View`	Composed	neu	neu	`CircularProgressViewStyle`. Label displayed underneath

Steppers

Steppers can be created with a title String, or with a custom view for the title.

Type	Category	Horizontal	Vertical
`Stepper`	Simple	exp	hug
`Stepper` with `Label: View`	Composed	exp	neu

Toggles

Toggles can be created with a title String, or with a custom view for the title.

Type	Category	Horizontal	Vertical
`Toggle`	Simple	exp	hug
`Toggle` with `Label: View`	Composed	exp	neu

Shapes

Several built-in shapes are available. Custom shapes can be created by implementing the Shape protocol. All have expanding behaviors in all directions.

Type	Category	Horizontal	Vertical
`Capsule`	Simple	exp	exp
`Circle`	Simple	exp	exp
`Ellipse`	Simple	exp	exp
`Rectangle`	Simple	exp	exp
`RoundedRectangle`	Simple	exp	exp
`Shape` (custom)	Simple	exp	exp

Spacers

Spacers are always flexible and work only within stacks. You can create a fixed size spacer with the View/frame(width:height:) modifier, though this is best avoided in general.

Type	Category	Horizontal	Vertical
`Spacer`	Simple	exp	exp

Simple Frame

The View/frame(width:height:alignment:) modifier is used to constrain space provided to its receiver in any or all directions.

`width` / `height` argument	Obtained behavior in the horizontal / vertical direction
Omitted	neu
Finite value	hug

If an argument is omitted for some direction the frame wrapper transparently adopts the same behavior as the receiver in this direction.

Advanced Frame

The View/frame(minWidth:idealWidth:maxWidth:minWeight:idealHeight:maxHeight:alignment:) modifier is used to constrain space or create an invisible largest frame in some direction, letting various alignments be applied for views drawn in it.

`maxWidth` / `maxHeight` argument	Obtained behavior in the horizontal / vertical direction
Omitted	neu
Finite value	hug
`.infinity`	exp

If an argument is omitted for some direction the frame wrapper transparently adopts the same behavior as the receiver in this direction.

Note that only maximum arguments alter the sizing behavior of the frame. Minimal and ideal arguments are only considered when the frame has hugging behavior (finite maximum argument) to choose the best possible size.

Aspect Ratio

A view can be forced to a given aspect ratio with the View/aspectRatio(_:contentMode:) modifier. This modifier does not change the sizing behavior of the receiver, but if the receiver is expanding in all directions it guarantees that it fit or fills the parent view while the other direction is adjusted to satisfy the desired aspect ratio and content mode.

Type	Category	Horizontal	Vertical
`View/aspectRatio(_:contentMode:)`	Composed	neu	neu

The aspect ratio is an optional parameter. If omitted the intrinsic aspect ratio of the receiver is used.

Remark

The intrinsic aspect ratio of the receiver is calculated from its intrinsic dimensions. As discussed in the Ambiguous Layout section, if some intrinsic dimension of the receiver cannot be determined SwiftUI will replace it with the magic value 10.

Fixed Size

A view can be forced to its intrinsic size with the View/fixedSize(horizontal:vertical:) modifier in any direction, adopting hugging behavior. If not the view behavior is preserved in the corresponding direction.

`horizontal` / `vertical` argument	Obtained behavior in the horizontal / vertical direction
true	hug
false	neu

As discussed in the Ambiguous Layout section, if some intrinsic dimension of the receiver cannot be determined SwiftUI will replace it with the magic value 10.

Common Decorators

These views adopt the behavior of the receiver in all directions and decorate it.

Type	Category	Horizontal	Vertical
`View/border(_:width:)`	Composed	neu	neu
`View/background(_:alignment:)`	Composed	neu	neu
`View/overlay(_:alignment:)`	Composed	neu	neu
`View/offset(_:)` and `View/offset(x:y:)`	Composed	neu	neu

Special Views

The following are special views for positioning and grouping.

Type	Category	Horizontal	Vertical	Remarks
`GeometryReader`	Composed	exp	exp	Takes the whole size offered by its parent. Its `geometryProxy` parameter can be used for precise children placement within the associated region. If a child is not provided with a frame the geometry reader simply places it at the top left
`Group`	Composed	neu	neu

The term sizing behavior is informally encountered in Apple frame documentation. ↩
This is why the definition of expanding behavior mentions that the view strives to match, not that it exactly matches the size offered by its parent. ↩
This is for example how the aspect ratio modifier works. ↩

Building a Collection For SwiftUI (Part 3) - Fixes and Focus Management

2020-09-15T00:00:00+00:00

In part 2 of this article series we implemented a first working collection view in SwiftUI, powered by UICollectionView. This implementation is promising but still has a few issues and shortcomings that we will address in this final article.

This article is part 3 in the Building a Collection For SwiftUI series.

Fixing Cell Frames
Supporting Focus on tvOS
Supporting Supplementary Views
Additional Considerations
Source Code
Wrapping Up

Fixing Cell Frames

When running our shelf example, cells initially on screen have correct frames, while cells emerging from screen edges do not:

When inspected in the view debugger, UICollectionViewCell and UIHostingController view frames are fine, so the problem must be related to how SwiftUI assigns a frame to views contained in a UIHostingController. In fact, closer inspection of the applied frames reveals that the reduction in size is due to safe area insets being somehow applied.

A Stack Overflow thread proposes a workaround for this issue until UIHostingController itself provides an official API to disable this behavior. This workaround applies swizzling to all hosting view instances indiscriminately, disabling safe area inset support entirely for all hosted SwiftUI views.

This approach is too greedy and affects hosting controllers for which this behavior is actually legitimate and desired, for example a UIHostingController hosting the SwiftUI root of a UIApplication. A more surgical approach than method swizzling is to use dynamic subclassing, the runtime wizardry applied by key-value observing.

To briefly sketch the theory behind dynamic subclassing, consider you have an object of some class whose behavior you want to tweak:

First register a new subclass of this class at runtime.
Then add methods to the subclass (possibly calling a parent implementation if this makes sense).
Finally change the class of the object to the subclass.

In our case, we can provide the missing opt-in behavior we need as an extension on UIHostingController, applied by dynamically changing the hosting view class to a subclass ignoring safe area insets:

extension UIHostingController {
    convenience public init(rootView: Content, ignoreSafeArea: Bool) {
        self.init(rootView: rootView)
        
        if ignoreSafeArea {
            disableSafeArea()
        }
    }
    
    func disableSafeArea() {
        guard let viewClass = object_getClass(view) else { return }
        
        let viewSubclassName = String(cString: class_getName(viewClass)).appending("_IgnoreSafeArea")
        if let viewSubclass = NSClassFromString(viewSubclassName) {
            object_setClass(view, viewSubclass)
        }
        else {
            guard let viewClassNameUtf8 = (viewSubclassName as NSString).utf8String else { return }
            guard let viewSubclass = objc_allocateClassPair(viewClass, viewClassNameUtf8, 0) else { return }
            
            if let method = class_getInstanceMethod(UIView.self, #selector(getter: UIView.safeAreaInsets)) {
                let safeAreaInsets: @convention(block) (AnyObject) -> UIEdgeInsets = { _ in
                    return .zero
                }
                class_addMethod(viewSubclass, #selector(getter: UIView.safeAreaInsets), imp_implementationWithBlock(safeAreaInsets), method_getTypeEncoding(method))
            }
            
            objc_registerClassPair(viewSubclass)
            object_setClass(view, viewSubclass)
        }
    }
}

This way we only apply a change of behavior to those UIHostingController instances for which safe area insets must not be taken into account, for example in our HostCell implementation:

hostController = UIHostingController(rootView: view, ignoreSafeArea: true)

With this simple trick cell frames are now correct:

Supporting Focus on tvOS

In the shelf example discussed at the end of part 2 of this article series, using the new tvOS 14 CardButtonStyle, the usual focused appearance is not applied when running the application. This is actually expected behavior, as the cell itself is focusable and the button style is not meant to receive focus in such cases.

In fact, SwiftUI buttons wrapped in focusable cells cannot be triggered at all. As a good SwiftUI citizen, our CollectionView must not prevent buttons from being used in cells, therefore host cells must not be focusable themselves. This also means we will not respond to collection cell standard selection delegate either, but rather let buttons handle actions.

One way to disable focus for a cell is by implementing canBecomeFocused on the cell class itself and return false. This seems to work well in general, but this strategy breaks when data source changes are applied with animations. In such cases the focus often spins out of control on tvOS. We therefore need a better approach.

UICollectionView and Animated Reloads

To understand this buggy behavior we need to figure the expected behavior of a UICollectionView when an animated reload occurs. To find the answer I simply implemented a basic collection in UIKit, with a simple data source and focusable UICollectionViewCells:

On tvOS I could observe that the focused item is followed when data source changes are animated. The focus never spins out of control during reloads. There is still a minor issue with the focused appearance being lost after the animation ends (likely a UICollectionView bug), but it suffices to swipe the remote again to have a nearby item focused.
On iOS the content offset is simply preserved, as there is no currently focus concept.

This user experience sets our goal for our SwiftUI CollectionView focus behavior.

Disabling and Enabling Focus

Disabling focus on cell classes directly does not work, but a similar result can be achieved thanks to UICollectionViewDelegate, which provides a dedicated delegate method to decide at any time whether a cell must be focusable or not. We therefore make our Coordinator conform to this protocol and introduce an internal flag to enable or disable focus for all cells when we want:

public struct CollectionView<Section: Hashable, Item: Hashable, Cell: View>: UIViewRepresentable {
    public class Coordinator: NSObject, UICollectionViewDelegate {
        // ...
        
        fileprivate var isFocusable: Bool = false
        
        public func collectionView(_ collectionView: UICollectionView, canFocusItemAt indexPath: IndexPath) -> Bool {
            return isFocusable
        }
    }
}

We can now enable UICollectionView cell focus during reloads, letting the collection view correctly follow the currently focused item. The rest of the time cells must not be focusable. We strive to enable focus for as little time as possible, and forcing a focus update before restting the flag to its nominal value is sufficient to achieve proper behavior:

public struct CollectionView<Section: Hashable, Item: Hashable, Cell: View>: UIViewRepresentable {
    private func reloadData(in collectionView: UICollectionView, context: Context, animated: Bool = false) {
        let coordinator = context.coordinator
        coordinator.sectionLayoutProvider = self.sectionLayoutProvider
        
        guard let dataSource = coordinator.dataSource else { return }
        
        let rowsHash = rows.hashValue
        if coordinator.rowsHash != rowsHash {
            dataSource.apply(snapshot(), animatingDifferences: animated) {
                coordinator.isFocusable = true
                collectionView.setNeedsFocusUpdate()
                collectionView.updateFocusIfNeeded()
                coordinator.isFocusable = false
            }
            coordinator.rowsHash = rowsHash
        }
    }
}

Note that this requires the UICollectionView to be provided as additional parameter to our reload method.

With these changes the focus now appears as expected and the focused item is followed when the data source is updated:

Remark

During my investigations I worked with focusable cells for a while until I realized this was a bad idea. Here are a few more findings if you are interested.

If we keep cells focusable Buttons are basically useless, as said above. Moreover, focused appearance must be implemented manually by tweaking view properties. Scaling is easy but tilting is another matter, and the native tvOS look & feel is not easy to reproduce accurately.

Finally, the pressed appearance (obtained for free with CardButtonStyle) requires catching cell interactions and transferring them up the SwiftUI view hierarchy, for example through the @Environment using a custom EnvironmentKey. Again this requires the appearance (scaling) to be adjusted manually.

For all these reasons I recommend avoiding focusable cells if you intend to wrap SwiftUI views within them.

Supporting Supplementary Views

Supporting supplementary views is very similar to supporting cells. We simply introduce a dedicated view builder and a host view. As for cells, type inference requires the addition of a new SupplementaryView type parameter to the generic CollectionView type:

struct CollectionView<Section: Hashable, Item: Hashable, Cell: View, SupplementaryView: View>: UIViewRepresentable {
    private class HostSupplementaryView: UICollectionReusableView {
        private var hostController: UIHostingController<SupplementaryView>?
        
        override func prepareForReuse() {
            if let hostView = hostController?.view {
                hostView.removeFromSuperview()
            }
            hostController = nil
        }
        
        var hostedSupplementaryView: SupplementaryView? {
            willSet {
                guard let view = newValue else { return }
                hostController = UIHostingController(rootView: view, ignoreSafeArea: true)
                if let hostView = hostController?.view {
                    hostView.frame = self.bounds
                    hostView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
                    addSubview(hostView)
                }
            }
        }
    }
    
    // ...
    
    let supplementaryView: (String, IndexPath) -> SupplementaryView
    
    init(rows: [CollectionRow<Section, Item>],
         sectionLayoutProvider: @escaping (Int, NSCollectionLayoutEnvironment) -> NSCollectionLayoutSection,
         @ViewBuilder cell: @escaping (IndexPath, Item) -> Cell,
         @ViewBuilder supplementaryView: @escaping (String, IndexPath) -> SupplementaryView) {
        self.rows = rows
        self.sectionLayoutProvider = sectionLayoutProvider
        self.cell = cell
        self.supplementaryView = supplementaryView
    }
}

Supplementary views are registered for a single reuse identifier (for the same reason a single identifier is required for cells) but specific kinds, e.g. header, footer or custom. We store known kinds in our coordinator as they are registered so that each required registration is made at most once:

struct CollectionView<Section: Hashable, Item: Hashable, Cell: View, SupplementaryView: View>: UIViewRepresentable {
    // ...
    
    class Coordinator: NSObject, UICollectionViewDelegate {
        // ...
        fileprivate var registeredSupplementaryViewKinds: [String] = []
    }

    func makeUIView(context: Context) -> UICollectionView {
        let cellIdentifier = "hostCell"
        let supplementaryViewIdentifier = "hostSupplementaryView"
        
        let collectionView = UICollectionView(frame: .zero, collectionViewLayout: layout(context: context))
        collectionView.register(HostCell.self, forCellWithReuseIdentifier: cellIdentifier)
        
        let dataSource = Coordinator.DataSource(collectionView: collectionView) { collectionView, indexPath, item in
            let hostCell = collectionView.dequeueReusableCell(withReuseIdentifier: cellIdentifier, for: indexPath) as? HostCell
            hostCell?.hostedCell = cell(indexPath, item)
            return hostCell
        }
        context.coordinator.dataSource = dataSource
        
        dataSource.supplementaryViewProvider = { collectionView, kind, indexPath in
            let coordinator = context.coordinator
            if !coordinator.registeredSupplementaryViewKinds.contains(kind) {
                collectionView.register(HostSupplementaryView.self, forSupplementaryViewOfKind: kind, withReuseIdentifier: supplementaryViewIdentifier)
                coordinator.registeredSupplementaryViewKinds.append(kind)
            }
            
            guard let view = collectionView.dequeueReusableSupplementaryView(ofKind: kind, withReuseIdentifier: supplementaryViewIdentifier, for: indexPath) as? HostSupplementaryView else { return nil }
            view.hostedSupplementaryView = supplementaryView(kind, indexPath)
            return view
        }
        
        reloadData(in:collectionView, context: context)
        return collectionView
    }
    
    // ...
}

Supplementary views must be added to your layout and defined within the corresponding view builder. Refer to the source code (link at the end of this article) for an example of use.

Additional Considerations

Before we wrap things up, I just wanted to mention a few important behaviors related to this implementation:

Since cells are reused any @State they store is temporary. Persistent state should be stored in your model instead.
Diffable data sources need each item to have a unique identifier, no matter the row it appears in, otherwise errors will be reported. This is because items can be moved between sections in general. Several sections can display the same item, but in order to do so you need to make the item truly unique for each section, for example by wrapping it into a struct and associating it with its section.
Changes are detected based on hashes. If a displayed item changes internally (e.g. some title changes) but its hash does not change, no update will be triggered.

Further improvements could be made and are left as exercise for the reader:

Make supplementary view support optional.
Make tabs optionally scroll with the content on tvOS (Hint: tabBarObservedScrollView).
Use decoration views to add focus guides for navigation between rows of different length on tvOS.
Port this collection to macOS and NSCollectionView. I read somewhere that nested stacks and scroll view performance was poor on macOS as well, probably because macOS has focus support for keyboard navigation. It is therefore likely that the approach discussed for tvOS can be applied to macOS in a similar way.

Source Code

The code for the collection view (< 200 LOC) and an example of use is available on GitHub. I even added a SPM manifest so that you can quickly test the collection in a project of your own. This does not mean the code is intended to be used as a library yet (it should be applied to a broader set of cases first), but feel free to use it any way you want.

Wrapping Up

This article is the last one in this series. I hope you enjoyed the ride and learned a few things!

You can also return to the introduction.

Building a Collection For SwiftUI (Part 2) - SwiftUI Collection Implementation

2020-09-14T00:00:00+00:00

Faced with the inability to reach an acceptable level of performance with grid layouts made of simple SwiftUI building blocks, I decided to roll my own solution.

This article is part 2 in the Building a Collection For SwiftUI series.

Implementation Strategies and Requirements
Wrapping UIKit Collection View Into SwiftUI
Providing a Collection View Layout
Loading Data Into the Collection
Data Source and Coordinator
Data Source Snapshots
Solving Performance Issues
Collection Layout Support
Cell Layout
Cell Display
Example of a Grid Layout
Wrapping Up

Implementation Strategies and Requirements

Two possible implementation strategies can be considered when implementing a SwiftUI collection:

Reproducing UICollectionView entirely in SwiftUI, including cell reuse and decoration views, not to mention flexible layout support.
Wrapping UICollectionView into a SwifUI UIViewRepresentable.

Since UICollectionView is already mature and has been greatly enhanced lately, the second option is obviously more manageable.

I added a few implementation constraints to ensure the custom collection view feels like a native SwiftUI component:

It must nicely integrate with SwiftUI declarative formalism.
Cells and supplementary views must be built in SwiftUI, not in UIKit, and certainly not with xibs or constraint-based layouts.
Cells and supplementary views must be lazily instantiated and reused. Put another way, scrolling performance must be similar to what is usually expected from a UICollectionView.
The collection view must support arbitrary layouts and nicely update when SwiftUI detects a change to a source of truth.
Focus must be correctly managed on tvOS, in particular it should be possible to implement the standard user experience expected on Apple TV according to the Human Interface Guidelines.

Let us start by wrapping a UIKit collection into a SwiftUI view.

Wrapping UIKit Collection View Into SwiftUI

A great feature of SwiftUI is the ease with which you can embed UIKit views in SwiftUI and conversely. This makes it easy to adopt SwiftUI where you can in your app, while still using good old UIKit where SwiftUI is lagging behind in functionality or performance.

SwiftUI provides the UIViewRepresentable protocol to wrap a UIKit view for use in SwiftUI. We can also wrap a view controller into a UIViewControllerRepresentable, but I here prefer the former approach as there is here no real competitive advantage in wrapping UICollectionViewController instead of UICollectionView directly.

If you are not familiar with SwiftUI, just recall that a View in SwiftUI can be seen as a short-lived layout snapshot, unlike a UIView in UIKit which is actually what is drawn on screen. To create and update content on screen in SwiftUI you therefore provide an up-to-date snapshot of your layout which then gets applied by the SwiftUI layout engine depending on what has changed. Snapshots are then discarded until new ones are required by further updates.

When interfacing UIKit with SwiftUI this important distiction translates into two protocol methods required by UIViewRepresentable, so that View snapshots can create or update the matching UIView on screen:

makeUIView(context:) is called when the UIView described by a View needs to be created.
updateUIView(_:context:) is called when the available UIView described by a View needs to be updated.

We therefore start our implementation by conforming our new CollectionView type to UIViewRepresentable and implementing its two required methods:

struct CollectionView: UIViewRepresentable {
    func makeUIView(context: Context) -> UICollectionView {
        // Create the collection view for the first time
    }
    
    func updateUIView(_ uiView: UICollectionView, context: Context) {
        // Update the existing collection view
    }
}

In our case the actual UICollectionView instance must be created in makeUIView(context:), but this requires a collection view layout to be provided at initialization time first.

Providing a Collection View Layout

With iOS 13 and tvOS 13 collection view layouts can be provided in a general declarative way through compositional layouts. The obtained layout code is expressive and supports advanced features like independently scrollable sections.

Because SwiftUI was introduced with iOS and tvOS 13, compositional layouts are the obvious choice for our implementation:

struct CollectionView: UIViewRepresentable {
    private func layout() -> UICollectionViewLayout {
        return UICollectionViewCompositionalLayout { sectionIndex, layoutEnvironment in
            // Return section layout
        }
    }

    func makeUIView(context: Context) -> UICollectionView {
        return UICollectionView(frame: .zero, collectionViewLayout: layout())
    }
    
    func updateUIView(_ uiView: UICollectionView, context: Context) {
        // Update the existing collection view
    }
}

Note that we provide .zero as frame since SwiftUI is responsible of applying a suitable frame when the UICollectionView is actually drawn on screen.

Compositional layouts are defined using sections, each section containing groups of items with supplementary or decoration views, and possibly independent orthogonal scrolling behavior. How and where this layout definition should be provided is yet still unclear, we just know it must ultimately be delivered by a layout() method.

Before we proceed with finding how to actually provide section layout definitions, let us first discuss how data will be loaded into the collection.

Loading Data Into the Collection

Since iOS 13 and tvOS 13, and in addition to compositional layouts, UIKit provides diffable data sources to incrementally update data associated with a collection and animate changes. Such data sources ensure that cells and underlying data stay consistent, avoiding crashes ususally associated with mismatches between data and layout.

When a data change needs to be made, a corresponding snapshot must be created and applied to the data source, which then takes care of the updating the associated collection view. This approach is quite similar to how SwiftUI reacts to data changes in general: When a change is detected a new layout description is provided to represent the new state and SwiftUI takes care of applying it to update the content visible on screen. Diffable data sources therefore seem quite appropriate in achieving what we need.

Let us first briefly consider from a client perspective. A parent content view which displays some Model conforming to ObservableObject into our CollectionView would roughly be implemented as follows:

struct ContentView: View {
    @ObservedObject var model: Model
    
    private func data(from model: Model) -> CollectionData {
        // Build data as expected by the CollectionView
    }

    var body: some View {
        CollectionView(data: data(from: model))
    }
}

When a model update is published by the observed object the view body is recalculated. An internal method takes care of creating a new data snapshot in some format understood by the CollectionView, yet to be determined. The SwiftUI layout engine then either creates or updates the underlying UICollectionView using this new view snapshot.

What kind of data format should we use, then? Using UICollectionViewDiffableDataSource internally is appropriate for the reasons outlined above. Since this type is generic and parametrized with two types, SectionIdentifierType and ItemIdentifierType (both required to be Hashable), our CollectionView type needs to be generic as well.

For compatibility with compositional layouts which display rows of items, it is natural to model the data displayed by a CollectionView as an array of rows, each row being described by the section it corresponds to and the items it contains:

struct CollectionRow<Section: Hashable, Item: Hashable>: Hashable {
    let section: Section
    let items: [Item]
}

Since Section and Item are both Hashable, making CollectionViewRow itself hashable only requires an explicit protocol conformance. Having a row itself hashable is useful to quickly check whether it changed, but more on that later.

Since CollectionRow is a generic type, the collection view itself must at least be parametrized with the same Section and Item types:

struct CollectionView<Section: Hashable, Item: Hashable>: UIViewRepresentable {
    let rows: [CollectionRow<Section, Item>]
    
    // ...
}

Types for the generic parameters will be automatically inferred by the Swift compiler when assigning rows to the collection. Still these rows are received by CollectionView and must be represented by a UICollectionView. Now is therefore the time to actually implement the diffable data source we need.

Data Source and Coordinator

A UICollectionView requires a data source to provide the data it displays. Instantiating a diffable data source containing Items in Sections and displaying them in a collectionView is simple:

let dataSource = UICollectionViewDiffableDataSource<Section, Item>(collectionView: collectionView) { collectionView, indexPath, item in
    // Return UICollectionViewCell for the item
}

This data source must be retained, as the collection view only keeps a weak reference to it. But where should we store a strong reference to the data source to keep it alive, since Views in SwiftUI are merely short-lived snapshots which get destroyed once they have been applied?

Fortunately SwiftUI provides an answer in the form of coordinators. The UIViewRepresentable protocol namely lets you optionally implement a makeCoordinator() method, from which you can return an instance of a custom type. SwiftUI calls this method before creating the UIKit view from the first time, associates the coordinator with it, and keeps the coordinator alive for as long as the UIView is in use.

We don’t know much about the coordinator type we need yet, except that it must store our data source. After initial creation, this coordinator is provided to the makeUIView(context:) method through the context parameter as a constant. We must be able to mutate the contained data source reference after the UICollectionView has been instantiated (the diffable data source namely requires the collection view at initialization time), so our Coordinator needs to be a class:

struct CollectionView<Section: Hashable, Item: Hashable>: UIViewRepresentable {
    class Coordinator {
        fileprivate typealias DataSource = UICollectionViewDiffableDataSource<Section, Item>
        
        fileprivate var dataSource: DataSource? = nil
    }
    
    // ...
    
    func makeCoordinator() -> Coordinator {
        return Coordinator()
    }
    
    func makeUIView(context: Context) -> UICollectionView {
        let collectionView = UICollectionView(frame: .zero, collectionViewLayout: layout())
        context.coordinator.dataSource = Coordinator.DataSource(collectionView: collectionView) { collectionView, indexPath, item in
            // Return UICollectionViewCell for the item
        }
        return collectionView
    }
}

Now that we have a data source properly created and retained for the lifetime of the collection view, we can discuss how to fill it with data.

Data Source Snapshots

Updating a diffable data source is made in increments. When data changes it suffices to build a new data snapshot and apply it:

struct CollectionView<Section: Hashable, Item: Hashable>: UIViewRepresentable {
    // ...
    
    private func snapshot() -> NSDiffableDataSourceSnapshot<Section, Item> {
        var snapshot = NSDiffableDataSourceSnapshot<Section, Item>()
        for row in rows {
            snapshot.appendSections([row.section])
            snapshot.appendItems(row.items, toSection: row.section)
        }
        return snapshot
    }
    
    func updateUIView(_ uiView: UICollectionView, context: Context) {
        guard let dataSource = context.coordinator.dataSource else { return }
        dataSource.apply(snapshot(), animatingDifferences: true)
    }
}

There are two performance issues associated with the above code, though:

The first animated applied snapshot can be slow for a large amount of data.
If you run this code on tvOS for a large number of row items and try to navigate the collection, you will discover that performance is really poor. If you try the same code on iOS performance is much better, though.

Since performance issues are what motivated the creation of a custom CollectionView in the first place, we must fix these identified problems before going any further.

Solving Performance Issues

To fix performance issues associated with the first snapshot, it suffices to factor out the corresponding code into a reloadData(context:animated:) method, called with or without animation depending on whether we are creating or updating the view:

struct CollectionView<Section: Hashable, Item: Hashable, Cell: View>: UIViewRepresentable {
    // ...
    
    private func reloadData(context: Context, animated: Bool = false) {
        guard let dataSource = context.coordinator.dataSource else { return }
        dataSource.apply(snapshot(), animatingDifferences: animated)
    }
    
    func makeUIView(context: Context) -> UICollectionView {
        let collectionView = UICollectionView(frame: .zero, collectionViewLayout: layout())
        
        context.coordinator.dataSource = Coordinator.DataSource(collectionView: collectionView) { collectionView, indexPath, item in
            // Return UICollectionViewCell for the item
        }
        
        reloadData(context: context)
        return collectionView
    }
    
    func updateUIView(_ uiView: UICollectionView, context: Context) {
        reloadData(context: context, animated: true)
    }
}

The second performance problem we are facing on tvOS is due to snapshots being applied too many times. Recall that SwiftUI recalculates view bodies when a source of truth changes. Many kinds of changes can therefore trigger updateUIView(_:context:), which is why you should attempt to keep its implementation as lightweight as possible in general.

In particular @Environment changes trigger a view update. A specificity of tvOS is that focus updates are provided through the environment. Moving the focus around is therefore sufficient to trigger view updates with each and every move. This is the reason why navigating the collection is a lot heavier on tvOS than on iOS with the implementation above, as snaphots are applied every time the focus is moved.

Sadly there is no way to distinguish updates due to data or enviroment changes in updateUIView(_:context:). The context does not provide this kind of information, the implementation therefore has no way to know whether an update requires a snapshot to be applied (data change) or not (simple environment change). Is there a way to avoid applying snaphots when the data has not changed?

Fortunately there is. As you may remember we made CollectionViewRow conform to Hashable. Calculating hashes is much cheaper than creating and applying a snapshot. Each time we apply a snapshot we can therefore store a hash of its rows, persist this value into our coordinator so that it stays available between updates, and only apply a new snapshot when the hash actually changed:

struct CollectionView<Section: Hashable, Item: Hashable>: UIViewRepresentable {
    class Coordinator {
        // ...
        
        fileprivate var rowsHash: Int? = nil
    }
    
    // ...
    
    private func reloadData(context: Context, animated: Bool = false) {
        let coordinator = context.coordinator
        guard let dataSource = coordinator.dataSource else { return }
        
        let rowsHash = rows.hashValue
        if coordinator.rowsHash != rowsHash {
            dataSource.apply(snapshot(), animatingDifferences: animated)
            coordinator.rowsHash = rowsHash
        }
    }
}

With this simple trick performance problems on tvOS are eliminated, even with large data sets containing thousands of items. Note that though this CollectionView implementation inhibits reloads due to environment changes, subviews (e.g. cells we will discuss below) can still individually respond to environment changes if they need to.

We now almost have a first working CollectionView implementation. We only need to be able to configure its layout and cells when creating it.

Collection Layout Support

At the beginning of this article we instantiated a UICollectionViewCompositionalLayout but did not provide any meaningful implementation for it:

struct CollectionView<Section: Hashable, Item: Hashable>: UIViewRepresentable {
    // ...

    private func layout() -> UICollectionViewLayout {
        return UICollectionViewCompositionalLayout { sectionIndex, layoutEnvironment in
            // Return section layout
        }
    }
}

How should clients of our CollectionView provide a layout? We want our collection to behave as a native SwiftUI component, it would therefore be tempting to use function builders to have a SwiftUI-inspired syntax for layout construction too. But since the current compositional layout API is already declarative and simple, I think it is simpler to just use it as is, rather than introducing a new syntax and the code to support it.

Our compositional layout internally requires a section layout provider trailing closure, so this is what our public type interface will let the user customize:

struct CollectionView<Section: Hashable, Item: Hashable>: UIViewRepresentable {
    // ...
    
    let rows: [CollectionRow<Section, Item>]
    let sectionLayoutProvider: (Int, NSCollectionLayoutEnvironment) -> NSCollectionLayoutSection

    private func layout() -> UICollectionViewLayout {
        return UICollectionViewCompositionalLayout { sectionIndex, layoutEnvironment in
            return sectionLayoutProvider(sectionIndex, layoutEnvironment)
        }
    }
}

Clients provide a section layout when instantiating a CollectionView, for example a shelf-like layout similar to the one we previously implemented with SwiftUI stacks and scroll views (see part 1):

CollectionView(rows: rows()) { sectionIndex, layoutEnvironment in
    let itemSize = NSCollectionLayoutSize(widthDimension: .fractionalWidth(1), heightDimension: .fractionalHeight(1))
    let item = NSCollectionLayoutItem(layoutSize: itemSize)
            
    let groupSize = NSCollectionLayoutSize(widthDimension: .absolute(320), heightDimension: .absolute(180))
    let group = NSCollectionLayoutGroup.horizontal(layoutSize: groupSize, subitems: [item])
            
    let section = NSCollectionLayoutSection(group: group)
    section.orthogonalScrollingBehavior = .continuous
    return section
}

Refer to the official documentation for more information about the compositional layout API. Note that how rows() are actually provided is here omitted for simplicity, as it does not affect the layout.

The layout example above is quite simple. In general each section layout might depend on the data model, though, for example if the layout is received from a web service. In such cases the sectionLayoutProvider block will capture the initial context and keep it for subsequent layout updates, which is not what we want if the layout returned by the web service later changes. To solve this issue our friend the coordinator again comes to the rescue:

struct CollectionView<Section: Hashable, Item: Hashable>: UIViewRepresentable {
    class Coordinator {
        // ...
        
        fileprivate var sectionLayoutProvider: ((Int, NSCollectionLayoutEnvironment) -> NSCollectionLayoutSection)?
    }

    let rows: [CollectionRow<Section, Item>]
    let sectionLayoutProvider: (Int, NSCollectionLayoutEnvironment) -> NSCollectionLayoutSection

    private func layout(context: Context) -> UICollectionViewLayout {
        return UICollectionViewCompositionalLayout { sectionIndex, layoutEnvironment in
            return context.coordinator.sectionLayoutProvider!(sectionIndex, layoutEnvironment)
        }
    }
    
    private func reloadData(context: Context, animated: Bool = false) {
        let coordinator = context.coordinator
        coordinator.sectionLayoutProvider = self.sectionLayoutProvider
        
        guard let dataSource = coordinator.dataSource else { return }
        
        let rowsHash = rows.hashValue
        if coordinator.rowsHash != rowsHash {
            dataSource.apply(snapshot(), animatingDifferences: animated)
            coordinator.rowsHash = rowsHash
        }
    }
        
    // ...
    
    func updateUIView(_ uiView: UICollectionView, context: Context) {
        reloadData(context: context, animated: true)
    }
}

This way we ensure the section layout provider is kept up-to-date between view updates so that the layout is always the most recent one, especially if it depends on the data model. Note that the optional sectionLayoutProvider stored by the Coordinator can here be safely force unwrapped, as it will always be available by construction. Note we also updated the layout(context:) method with a Context parameter to retrieve the coordinator from.

With layout definition needs covered let us finish by discussing cell layout and display.

Cell Layout

Our CollectionView first implementation is almost finished, but the cell provider closure of our UICollectionViewDiffableDataSource is still missing. Recall that we don’t want to layout cells with UIKit code but with SwiftUI declarative syntax. How should we now proceed?

SwiftUI syntax is built on top of view builders, actually a special kind of function builder. To be able to associate SwiftUI cells with their UICollectionViewCell counterparts (which we still need internally for our UICollectionView implementation), we simply introduce a view builder taking an index path and item as parameters, and returning some SwiftUI view as cell:

struct CollectionView<Section: Hashable, Item: Hashable, Cell: View>: UIViewRepresentable {
    // ...
    
    let rows: [CollectionRow<Section, Item>]
    let sectionLayoutProvider: (Int, NSCollectionLayoutEnvironment) -> NSCollectionLayoutSection
    let cell: (IndexPath, Item) -> Cell
    
    init(rows: [CollectionRow<Section, Item>],
         sectionLayoutProvider: @escaping (Int, NSCollectionLayoutEnvironment) -> NSCollectionLayoutSection,
         @ViewBuilder cell: @escaping (IndexPath, Item) -> Cell) {
        self.rows = rows
        self.sectionLayoutProvider = sectionLayoutProvider
        self.cell = cell
    }
}

The @ViewBuilder syntax requires a dedicated initializer, as @ViewBuilder can only appear as a parameter-attribute. Note that Swift infers the type of the cell body based on the view builder block, forcing us to add Cell as additional parameter of the CollectionView generic type list.

Cell Display

Cells whose layout is defined with SwiftUI code are ultimately displayed by a UICollectionView and thus must be wrapped for display by UIKit. This is achieved by using UIHostingController and a simple host UICollectionViewCell:

struct CollectionView<Section: Hashable, Item: Hashable, Cell: View>: UIViewRepresentable {
    // ...
    
    private class HostCell: UICollectionViewCell {
        private var hostController: UIHostingController<Cell>?
        
        override func prepareForReuse() {
            if let hostView = hostController?.view {
                hostView.removeFromSuperview()
            }
            hostController = nil
        }
        
        var hostedCell: Cell? {
            willSet {
                guard let view = newValue else { return }
                hostController = UIHostingController(rootView: view)
                if let hostView = hostController?.view {
                    hostView.frame = contentView.bounds
                    hostView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
                    contentView.addSubview(hostView)
                }
            }
        }
    }
}

The implementation of this cell is straightforward:

We prepare a UIHostingController when setting a SwiftUI cell. The hosting controller view is installed to fill the entire cell content view. Such embedding is actually made possible by the fact that creating a UIHostingController is actually quite cheap.
When a cell is reused, the hosting controller view is removed and the controller itself is released.

Now that we have a cell, it suffices to register it and return dequeued instances from our data source, assigning it the corresponding SwiftUI cell:

struct CollectionView<Section: Hashable, Item: Hashable>: UIViewRepresentable {
    // ...
    
    func makeUIView(context: Context) -> UICollectionView {
        let cellIdentifier = "hostCell"
    
        let collectionView = UICollectionView(frame: .zero, collectionViewLayout: layout(context: context))
        collectionView.register(HostCell.self, forCellWithReuseIdentifier: cellIdentifier)
        
        context.coordinator.dataSource = Coordinator.DataSource(collectionView: collectionView) { collectionView, indexPath, item in
            let hostCell = collectionView.dequeueReusableCell(withReuseIdentifier: cellIdentifier, for: indexPath) as? HostCell
            hostCell?.hostedCell = cell(indexPath, item)
            return hostCell
        }
        
        reloadData(context: context)
        return collectionView
    }
}

Note that, unlike cells defined in UIKit, there is no need for clients of our CollectionView to mess with cell class registrations and reuse identifiers. Only one cell identifier is required and managed internally. All cells provided in SwiftUI namely share the same Cell generic type parameter, whose actual value is filled in by the Swift compiler based on what is inside the view builder closure.

Remark

iOS and tvOS 14 provide a new CellRegistration API but, to keep things simple, we still use the old cell registration and dequeuing API, so that the implementation is compatible with iOS and tvOS 13 without the use of availability macros. The iOS and tvOS 14 modern implementation is left as an exercise for the reader.

Example of a Grid Layout

Bringing everything together, we now have a first working implementation of a CollectionView in SwiftUI, powered by UICollectionView. The complete source code will be provided in the third and last article in this series, but let us have a look at how a shelf-like layout like the one we discussed in part 1 is implemented with the API we have defined throughout this article, on tvOS:

import SwiftUI

struct Shelf: View {
    typealias Row = CollectionRow<Int, String>
    
    var rows: [Row] = {
        var rows = [Row]()
        for i in 0..<20 {
            rows.append(Row(section: i, items: (0..<10).map { "\(i), \($0)" }))
        }
        return rows
    }()
    
    var body: some View {
        CollectionView(rows: rows) { sectionIndex, layoutEnvironment in
            let itemSize = NSCollectionLayoutSize(widthDimension: .fractionalWidth(1), heightDimension: .fractionalHeight(1))
            let item = NSCollectionLayoutItem(layoutSize: itemSize)
            
            let groupSize = NSCollectionLayoutSize(widthDimension: .absolute(320), heightDimension: .absolute(180))
            let group = NSCollectionLayoutGroup.horizontal(layoutSize: groupSize, subitems: [item])
            
            let section = NSCollectionLayoutSection(group: group)
            section.contentInsets = NSDirectionalEdgeInsets(top: 20, leading: 0, bottom: 20, trailing: 0)
            section.interGroupSpacing = 40
            section.orthogonalScrollingBehavior = .continuous
            return section
        } cell: { indexPath, item in
            GeometryReader { geometry in
                Button(action: {}) {
                    Text(item)
                        .frame(width: geometry.size.width, height: geometry.size.height)
                        .background(Color.blue)
                }
                .buttonStyle(CardButtonStyle())
            }
        }
        .frame(maxWidth: .infinity, maxHeight: .infinity)
        .ignoresSafeArea(.all)
    }
}

The formalism is quite elegant and compact but, when actually running the code above, we find a few more issues:

When scrolling a shelf horizontally, cells which appear from the edges are not properly sized.
Buttons do not exhibit the CardButtonStyle appearance when focused.

Wrapping Up

In this lengthy article we have implemented a working collection view for SwiftUI, based on UICollectionView. We have designed an API to layout the collection itself as well as its individual cells. We also have ensured performance is on par with what we expect from a usual UIKit collection view, thus addressing our initial problem.

The end result, while certainly promising, still suffers from a few issues we will solve in the next and final article in this series.

Building a Collection For SwiftUI (Part 1) - Mimicking Collections in SwiftUI

2020-09-13T00:00:00+00:00

SwiftUI does not offer any full-featured collection component like UIKit does, merely smaller building blocks like stacks, lists and scroll views (as well as lazy stacks and grids newly introduced in iOS and tvOS 14). In isolation none of these components is a true competitor to UICollectionView but, combined together, they can be used to build pretty advanced grid and table layouts.

In fact, combining these basic components to achieve grid and table layouts in SwiftUI is incredibly simple, with a clean and beautiful formalism. And with the lazy components added this year, there hasn’t apparently been any better time to fully embrace SwiftUI, has there?

This article is part 1 in the Building a Collection For SwiftUI series.

Basic Grid Layouts in SwiftUI
Better SwiftUI Grid Layouts With Lazy Stacks
The Problem with SwiftUI Stack-based Grid Layouts
Wrapping Up

Basic Grid Layouts in SwiftUI

Think about the TV, App Store or Netflix apps. They present their content in horizontally scrollable shelves, a layout fairly common among iOS and tvOS apps.

Creating such a layout in SwiftUI is as simple as nesting a few stacks and scroll views:

struct Cell: View {
    let row: Int
    let column: Int
    
    var body: some View {
        Text("\(row), \(column)")
            .frame(width: 320, height: 180)
            .background(Color.blue)
    }
}

struct Row: View {
    let index: Int
    
    var body: some View {
        ScrollView(.horizontal) {
            HStack {
                ForEach(0..<10) { i in
                    Cell(row: index, column: i)
                }
            }
        }
    }
}

struct Grid: View {
    var body: some View {
        ScrollView {
            VStack {
                ForEach(0..<20) { i in
                    Row(index: i)
                }
            }
        }
    }
}

Achieving a similar result with UIKit would have usually required a UICollectionView with a compositional layout made of horizontally scrollable sections.

Compositional layouts are only available since iOS and tvOS 13, though. On earlier versions you would rather have used a main vertical collection or table, containing as many nested horizontal collections as needed for rows. Not to mention that in this case horizontal content offsets need to be saved and restored as the main vertical collection or table is scrolled and cells are reused. All these behaviors are provided for free with the above SwiftUI layout code, which is quite amazing.

The real downside of the above SwiftUI implementation is that, unlike UICollectionView, all view bodies are loaded initially, as is appearant when you profile the code with Instruments:

Surely this is not optimal from a performance and memory consumption point of view, and fortunately Apple’s engineers probably thought the same.

Better SwiftUI Grid Layouts With Lazy Stacks

This year SwiftUI introduces lazy variants of stacks in iOS and tvOS 14. Seems like magic when you watch WWDC 2020 10031 where they are presented in action, but you still have to be somewhat careful about which stacks you promote to laziness.

In our case only the outermost stack should be made lazy so that each row height can be properly calculated:

struct Cell: View {
    let row: Int
    let column: Int
    
    var body: some View {
        Text("\(row), \(column)")
            .frame(width: 320, height: 180)
            .background(Color.blue)
    }
}

struct Row: View {
    let index: Int
    
    var body: some View {
        ScrollView(.horizontal) {
            HStack {
                ForEach(0..<10) { i in
                    Cell(row: index, column: i)
                }
            }
        }
    }
}

struct Grid: View {
    var body: some View {
        ScrollView {
            LazyVStack {
                ForEach(0..<20) { i in
                    Row(index: i)
                }
            }
        }
    }
}

When profiled with Instruments we clearly see an improvement:

Pretty nice until now, isn’t it?

Remark

Though iOS and tvOS 14 also introduce lazy grids with similar behavior, those are not suited for our shelf-based layout as they currently do not support independently scrollable rows.

The Problem with SwiftUI Stack-based Grid Layouts

What is not immediately apparant with the code above is that, while you can easily navigate this grid on iOS by swiping the screen, you cannot do the same on tvOS. There is namely no focusable item in the layout code above, therefore no way to navigate the collection on Apple TV.

Fortunately it is very easy to make cells focusable by turning them into buttons. We can even have standard look and feel with the new tvOS 14 card button style, which makes focused buttons pop out with a large shadow underneath and tilting support.

Since focus makes the button larger and adds a large shadow to it, I tweaked the margins to let the content shine when focused, but otherwise the code is identical to the one above, except for an added button wrapper in cells. Note that this code only runs on tvOS 14, as the button style is only available there (it is quite easy to make the code compatible with iOS 13 and tvOS 13, but this is left as an exercise for the reader):

struct Cell: View {
    let row: Int
    let column: Int
    
    var body: some View {
        Button(action: {}) {
            Text("\(row), \(column)")
                .frame(width: 320, height: 180)
                .background(Color.blue)
        }
        .buttonStyle(CardButtonStyle())
    }
}

struct Row: View {
    let index: Int
    
    var body: some View {
        ScrollView(.horizontal) {
            HStack {
                ForEach(0..<10) { i in
                    Cell(row: index, column: i)
                }
            }
            .padding([.leading, .trailing], 40)
            .padding(.top, 20)
            .padding(.bottom, 80)
        }
    }
}

struct Grid: View {
    var body: some View {
        ScrollView {
            LazyVStack {
                ForEach(0..<20) { i in
                    Row(index: i)
                }
            }
        }
    }
}

We can now navigate the collection and enjoy the native tvOS behavior we expect according to the Human Interface Guidelines:

UICollectionView excels at ensuring smooth scrolling for large data sets by reusing cells as the view is scrolled. Stacks initially introduced by SwiftUI load all content at the same time, but surely lazy variants added this year are supposed to address this issue, aren’t they?

To verify this assumption it suffices to tweak the code above and to load 20 rows of 50 items instead. If you attempt to run the result on an Apple TV device you will clearly experience severe issues. Scrolling performance namely degrades fast with increasing number of items and the user experience becomes horrendous, even with the basic cells we display. You can also notice that lazy stacks do not work well on tvOS, as they force the focus to move one item at a time near collection boundaries.

Remark

If you run the code above on iOS (without the card button style which is available for tvOS only), the experience is better overall:

Scrolling is smoother, which does not mean that it is anywhere the performance of a UICollectionView displaying the same number of items.
It is possible to move more than one item at a time near view boundaries since only swipes are involved for navigation.

Without having the time to dig into what actually makes things worse on tvOS, I conjectured these issues are related to tvOS focus changes, which trigger @Environment updates probably leading to additional layout work. This is something we will discuss again in part 2 of this article series but, if I am correct, I think this problem can likely be solved in a future SwiftUI release. Still we must find a solution in the meantime.

Wrapping Up

SwiftUI grid-based layouts made of nested stacks and scroll views currently suffer from major performance issues. On tvOS these performance issues are so significant that attempting to load a few hundred items leads to a poor user experience. Loading thousands of items can bring an Apple TV to its knees.

I reported this problem to Apple during the iOS and tvOS 14 beta phase, knowing it would likely not be fixed in the official releases, and considered the available options:

Blissful optimism: Do nothing, continue to work with nested stack and scroll views, and hope that later iOS and tvOS releases fix the issue. In the meantime put an upper bound on the amount of content we display in grids, a couple hundred items at most.
Complete pessimism: Consider SwiftUI is not mature enough and use UIKit.
Compromise: Use SwiftUI where possible but find a way to solve collection performance issues.

Having tasted how great working and thinking in SwiftUI can be, the mere idea of dropping it entirely was disappointing, especially knowing it can be integrated with UIKit fairly easily. Putting upper bounds to the amount of items displayed was not acceptable either. I therefore decided to go with the compromise and roll my own collection, knowing I would probably learn a lot along the way.

Building a Collection For SwiftUI - Introduction

2020-09-12T00:00:00+00:00

UICollectionView has been an essential tool for Apple app developers since its introduction in iOS 6. Over the years it received a range of improvements and was ported to tvOS so that you can build layouts with the same formalism on both platforms. In iOS and tvOS 13 UICollectionView received the most significant enhancements ever made since its introduction, namely diffable data sources and compositional layouts.

Last year Apple introduced SwiftUI, its declarative UI framework. Now in its second iteration with iOS and tvOS 14, SwiftUI is obviously still lagging behind in terms of functionality. While SwiftUI provides lists, scrollable views and grids as of version 14, it still does not provide a collection which could compete with UICollectionView in terms of feature set or versatility. This does not mean that grid and table layouts usually achieved with UICollectionView are not possible with SwiftUI. The smaller components already available can be easily combined to create complex scrollable layouts, so that what can be achieved in UIKit can be more or less achieved in SwiftUI as well.

When evaluating SwiftUI as a viable option for porting our iOS apps to tvOS, one of the essential requirements to satisfy was to ensure grid and table layouts, used throughout our implementation, would be easy to create in SwiftUI, with satisfying user experience. I initially and naively thought so, but I did not quite imagine how wrong I was.

I thought sharing my experience could probably be helpful to other developers who might be considering SwiftUI for their own apps as well. Since the material to be covered is larger than initially expected, I opted out for a series of articles requiring some prior SwiftUI and UIKit knowledge, but which I tried to keep accessible for newcomers as well:

Part 1: Mimicking Collections in SwiftUI: A mild introduction into the world of collection aleternatives in SwiftUI (and associated delusions).
Part 2: SwiftUI Collection Implementation: Where we build a first working SwiftUI collection from the ground up.
Part 3: Fixes and Focus Management: Where we solve issues with the implementation and implement focus management for tvOS.

The source code for this series is available if you want to have a look at the implementation while reading the articles.

Yet another article about method swizzling

2014-12-04T00:00:00+00:00

Many Objective-C developers disregard method swizzling, considering it a bad practice. I don’t like method swizzling, I love it. Of course it is risky and can hurt you like a bullet. Carefully done, though, it makes it possible to fill annoying gaps in system frameworks which would be impossible to fill otherwise. From simply providing a convenient way to track the parent popover controller of a view controller to implementing Cocoa-like bindings on iOS, method swizzling has always been an invaluable tool to me.

Function prototype
Issues in class hierarchies
First implementation attempt
Large struct return values
Wrapping up: IMP-swizzling
Block-swizzling
Macros
Conclusion

Implementing swizzling correctly is not easy, though, probably because it looks straightforward at first (all is needed is a few Objective-C runtime function calls, after all). Though the Web is crawling with articles about the right way to swizzle a method, I sadly found issues with all of them.

The implementation discussed in this article may have issues of its own, but I do hope sharing it will help improve existing implementations, as well as mine. For this reason, do not regard these few words as a Done right article, only as a small step towards hopefully better swizzling implementations. There is a correct way to swizzle methods, but it probably still remains to be found.

Function prototype

Since the Objective-C runtime is a series of functions, I decided to implement swizzling as a function as well. Most existing implementations, for example the well-respected JRSwizzle, exchange IMPs associated with two selectors. Ultimately, though, method swizzling is about changing, not exchanging, which is why I prefer a function expecting an original SEL and an IMP arguments:

IMP class_swizzleSelector(Class clazz, SEL selector, IMP newImplementation);

instead of two SEL arguments:

IMP class_swizzleSelectorWithSelector(Class clazz, SEL selector, SEL swizzlingSelector); 

Moreover, using an IMP (in other words a C-function) instead of a selector implementation avoids potential clashes if your swizzling selector name convention happens to be the same as the one used elsewhere, especially when dealing with 3rd party code. Don’t be too optimistic, accidental method overriding due to bad conventions can happen all the time.

The function above returns the original implementation, which must be properly cast and called from within the swizzling method implementation, so that the original behavior is preserved. If the method to swizzle is not implemented, I decided the function must do nothing and return NULL.

Issues in class hierarchies

When swizzling methods in class hierarchies, we must take extra care when the method we swizzle is not implemented by the class on which it is swizzled, but is implemented by one of its parents. For example, the -awakeFromNib method, declared and implemented at the NSObject level, is neither implemented by the UIView nor by the UILabel subclasses. When calling this method on an instance of any of theses classes, it is therefore the NSObject implementation which gets called:

If we naively swizzle the -awakeFromNib method both at the UIView and UILabel levels, we get the following result:

As we see, when -[UILabel awakeFromNib] is now called, the swizzled UIView implementation does not get called, which is not what is expected from proper swizzling.

The situation would be completely different if the -awakeFromNib method was implemented on UIView and UILabel. If this was the case, and if each implementation properly called the super method counterpart first, we would namely obtain:

and, after swizzling:

No swizzling implementation I encountered correctly deals with this issue, not even JRSwizzle. As should be clear from the last picture above, the solution to this problem is to ensure a method is always implemented by a class before swizzling it. If this is not the case, an implementation must be injected first, simply calling the super method counterpart. This way, all implementations will correctly be called after swizzling.

First implementation attempt

Based on the above, I first implemented instance method swizzling as follows:

#import <objc/runtime.h>
#import <objc/message.h>

IMP class_swizzleSelector(Class clazz, SEL selector, IMP newImplementation)
{
    // If the method does not exist for this class, do nothing
    Method method = class_getInstanceMethod(clazz, selector);
    if (! method) {
        return NULL;
    }
    
    // Make sure the class implements the method. If this is not the case, inject an implementation, calling 'super'
    const char *types = method_getTypeEncoding(method);
    class_addMethod(clazz, selector, imp_implementationWithBlock(^(__unsafe_unretained id self, va_list argp) {
        struct objc_super super = {
            .receiver = self,
            .super_class = class_getSuperclass(clazz)
        };
        
        id (*objc_msgSendSuper_typed)(struct objc_super *, SEL, va_list) = (void *)&objc_msgSendSuper;
        return objc_msgSendSuper_typed(&super, selector, argp);
    }), types);
    
    // Can now safely swizzle
    return class_replaceMethod(clazz, selector, newImplementation, types);
}

For class method swizzling, it suffices to call the above function on a metaclass:

IMP class_swizzleClassSelector(Class clazz, SEL selector, IMP newImplementation)
{
    return class_swizzleSelector(object_getClass(clazz), selector, newImplementation);
}

The imp_implementationWithBlock function is used as a trampoline to accomodate any kind of method prototype through a variable argument list va_list. The super method call is made by properly casting objc_msgSendSuper, available from <objc/message.h>. In order to prevent ARC from inserting incorrect memory management calls, the self parameter of the implementation block has been marked with __unsafe_unretained.

Large struct return values

As pointed out by Peter Steinberger and @__block on Twitter, struct returns require special care on some architectures.

Most method calls are funnelled through the objc_msgSend function, returning the result in a register. For large structs which cannot fit in a register, though, the compiler might generate a call to the special objc_msgSend_stret function, which returns the parameter on the stack instead. According to the ABI, this happens on 32-bit architectures for types whose size is neither 1, 2, 4 nor 8. The implementation above does not account for this special case and must therefore be changed to account for such cases.

For method returning large structs, we need the imp_implementationWithBlock function to generate the correct implementation by having the block return a large struct. The kind of struct and its layout are irrelevant, we only need it to be sufficiently large so that the compiler can make the right decision. As for objc_msgSend_stret, there is an objc_msgSendSuper_stret for super calls to methods returning large structs, which we need to use instead.

For large struct returns, instead of calling the class_swizzleSelector function above, we therefore must call the following class_swizzleSelector_stret function:

#import <objc/runtime.h>
#import <objc/message.h>

IMP class_swizzleSelector_stret(Class clazz, SEL selector, IMP newImplementation)
{
    // If the method does not exist for this class, do nothing
    Method method = class_getInstanceMethod(clazz, selector);
    if (! method) {
        return NULL;
    }
    
    // Make sure the class implements the method. If this is not the case, inject an implementation, only calling 'super'
    const char *types = method_getTypeEncoding(method);
    class_addMethod(clazz, selector, imp_implementationWithBlock(^(__unsafe_unretained id self, va_list argp) {
        struct objc_super super = {
            .receiver = self,
            .super_class = class_getSuperclass(clazz)
        };
        
        // Sufficiently large struct
        typedef struct LargeStruct_ {
            char dummy[16];
        } LargeStruct;
        
        // Cast the call to objc_msgSendSuper_stret appropriately
        LargeStruct (*objc_msgSendSuper_stret_typed)(struct objc_super *, SEL, va_list) = (void *)&objc_msgSendSuper_stret;
        return objc_msgSendSuper_stret_typed(&super, selector, argp);
    }), types);
    
    // Can now safely swizzle
    return class_replaceMethod(clazz, selector, newImplementation, types);
}

Wrapping up: IMP-swizzling

Having a separate class_swizzleSelector_stret function which must appropriately be called when large structs are returned is rather inconvenient. Fortunately, its implementation can be merged into class_swizzleSelector by checking return type size information for 32-bit architectures first. We obtain a single function for method swizzling with an IMP:

#import <objc/runtime.h>
#import <objc/message.h>

IMP class_swizzleSelector(Class clazz, SEL selector, IMP newImplementation)
{
    // If the method does not exist for this class, do nothing
    Method method = class_getInstanceMethod(clazz, selector);
    if (! method) {
        // Cannot swizzle methods which are not implemented by the class or one of its parents
        return NULL;
    }
    
    // Make sure the class implements the method. If this is not the case, inject an implementation, only calling 'super'
    const char *types = method_getTypeEncoding(method);
    
#if !defined(__arm64__)
    NSUInteger returnSize = 0;
    NSGetSizeAndAlignment(types, &returnSize, NULL);
    
    // Large structs on 32-bit architectures
    if (sizeof(void *) == 4 && types[0] == _C_STRUCT_B && returnSize != 1 && returnSize != 2 && returnSize != 4 && returnSize != 8) {
        class_addMethod(clazz, selector, imp_implementationWithBlock(^(__unsafe_unretained id self, va_list argp) {
            struct objc_super super = {
                .receiver = self,
                .super_class = class_getSuperclass(clazz)
            };
            
            // Sufficiently large struct
            typedef struct LargeStruct_ {
                char dummy[16];
            } LargeStruct;
            
            // Cast the call to objc_msgSendSuper_stret appropriately
            LargeStruct (*objc_msgSendSuper_stret_typed)(struct objc_super *, SEL, va_list) = (void *)&objc_msgSendSuper_stret;
            return objc_msgSendSuper_stret_typed(&super, selector, argp);
        }), types);
    }
    // All other cases
    else {
#endif
        class_addMethod(clazz, selector, imp_implementationWithBlock(^(__unsafe_unretained id self, va_list argp) {
            struct objc_super super = {
                .receiver = self,
                .super_class = class_getSuperclass(clazz)
            };
            
            // Cast the call to objc_msgSendSuper appropriately
            id (*objc_msgSendSuper_typed)(struct objc_super *, SEL, va_list) = (void *)&objc_msgSendSuper;
            return objc_msgSendSuper_typed(&super, selector, argp);
        }), types);
#if !defined(__arm64__)
    }
#endif
    
    // Swizzling
    return class_replaceMethod(clazz, selector, newImplementation, types);
}

The _stret variants are not available on ARM 64, thus the extra preprocessor adornments.

Example of use

To swizzle a method, define a static C-function for the new implementation and call class_swizzleSelector or class_swizzleClassSelector to set it as new one. Save the original implementation into a function pointer matching the function signature, and make sure the new implementation calls it somehow:

static id (*initWithFrame)(id, SEL, CGRect) = NULL;
static void (*awakeFromNib)(id, SEL) = NULL;
static void (*dealloc)(__unsafe_unretained id, SEL) = NULL;

static id swizzle_initWithFrame(UILabel *self, SEL _cmd, CGRect frame)
{
    if ((self = initWithFrame(self, _cmd, frame))) {
        // ...
    }
    return self;
}

static void swizzle_awakeFromNib(UILabel *self, SEL _cmd)
{
    awakeFromNib(self, _cmd);
    
    // ...
}

static void swizzle_dealloc(__unsafe_unretained UILabel *self, SEL _cmd)
{
    // ...
    
    dealloc(self, _cmd);
}

@implementation UILabel (SwizzlingExamples)

+ (void)load
{
    initWithFrame = (__typeof(initWithFrame))class_swizzleSelector(self, @selector(initWithFrame:), (IMP)swizzle_initWithFrame);
    awakeFromNib = (__typeof(awakeFromNib))class_swizzleSelector(self, @selector(awakeFromNib), (IMP)swizzle_awakeFromNib);
    dealloc = (__typeof(dealloc))class_swizzleSelector(self, sel_getUid("dealloc"), (IMP)swizzle_dealloc);
}

@end

Note that I added an extra __unsafe_unretained specifier to the swizzle_dealloc prototype to ensure ARC does not insert additional memory management calls. I also cheated by getting the dealloc selector with sel_getUid, since @selector(dealloc) cannot be used with ARC.

Block-swizzling

Thanks to imp_implementationWithBlock, we can provide a block instead of an IMP for the new implementation:

IMP class_swizzleSelectorWithBlock(Class clazz, SEL selector, id newImplementationBlock)
{
    IMP newImplementation = imp_implementationWithBlock(newImplementationBlock);
    return class_swizzleSelector(clazz, selector, newImplementation);
}

IMP class_swizzleClassSelectorWithBlock(Class clazz, SEL selector, id newImplementationBlock)
{
    IMP newImplementation = imp_implementationWithBlock(newImplementationBlock);
    return class_swizzleClassSelector(clazz, selector, newImplementation);
}

The block signature itself does not include the selector parameter, as specified in the imp_implementationWithBlock documentation.

Example of use

The above example can be rewritten using blocks, eliminating the need for static methods and function pointers:

@implementation UILabel (SwizzlingExamples)

+ (void)load
{
    __block IMP originalInitWithFrame = class_swizzleSelectorWithBlock(self, @selector(initWithFrame:), ^(UILabel *self, CGRect frame) {
        if ((self = ((id (*)(id, SEL, CGRect))originalInitWithFrame)(self, @selector(initWithFrame:), frame))) {
            // ...
        }
        return self;
    });
    
    __block IMP originalAwakeFromNib = class_swizzleSelectorWithBlock(self, @selector(awakeFromNib), ^(UILabel *self) {
        ((void (*)(id, SEL))originalAwakeFromNib)(self, @selector(awakeFromNib));
        
        // ...
    });
    
    __block IMP originalDealloc = class_swizzleSelectorWithBlock(self, sel_getUid("dealloc"), ^(__unsafe_unretained UILabel *self) {
        // ...

        ((void (*)(id, SEL))originalDealloc)(self, sel_getUid("dealloc"));
    });
}

@end

Returned original implementations must be saved into __block variables to be accessible from within the corresponding implementation blocks.

Macros

Some redundancy is found in both examples of use above, but can be eliminated by defining a few convenience macros:

#define SwizzleSelector(clazz, selector, newImplementation, pPreviousImplementation) \
    (*pPreviousImplementation) = (__typeof((*pPreviousImplementation)))class_swizzleSelector((clazz), (selector), (IMP)(newImplementation))

#define SwizzleClassSelector(clazz, selector, newImplementation, pPreviousImplementation) \
    (*pPreviousImplementation) = (__typeof((*pPreviousImplementation)))class_swizzleClassSelector((clazz), (selector), (IMP)(newImplementation))

#define SwizzleSelectorWithBlock_Begin(clazz, selector) { \
    SEL _cmd = selector; \
    __block IMP _imp = class_swizzleSelectorWithBlock((clazz), (selector),
#define SwizzleSelectorWithBlock_End );}

#define SwizzleClassSelectorWithBlock_Begin(clazz, selector) { \
    SEL _cmd = selector; \
    __block IMP _imp = class_swizzleClassSelectorWithBlock((clazz), (selector),
#define SwizzleClassSelectorWithBlock_End );}

To emphasize that the IMP-swizzling macros set the new implementation variable, the corresponding macro parameter needs to be adorned with an ampersand.

Block-swizzling, on the other hand, has been turned into a pair of macros. This avoids block parameters, which do not work well with macros:

Macro expansion of a block turns the block implementation into a single line, confusing the debugger
A block can contain commas, preventing correct macro argument detection (this can be avoided by enclosing the blocks within parentheses, though)

Moreover, the block-swizzling macros declare a hidden scope where the selector _cmd and original implementation _imp are immediately available.

Example of use

The two previous examples can now be rewritten as follows:

@implementation UILabel (SwizzlingExamples)

// Function pointers and static functions, as defined above

+ (void)load
{
    SwizzleSelector(self, @selector(initWithFrame:), swizzle_initWithFrame, &initWithFrame);
    SwizzleSelector(self, @selector(awakeFromNib), &swizzle_awakeFromNib, &awakeFromNib);
    SwizzleSelector(self, sel_getUid("dealloc"), &swizzle_dealloc, &dealloc);
}

@end

respectively:

@implementation UILabel (SwizzlingExamples)

+ (void)load
{
    SwizzleSelectorWithBlock_Begin(self, @selector(initWithFrame:))
    ^(UILabel *self, CGRect frame) {
        if ((self = ((id (*)(id, SEL, CGRect))_imp)(self, _cmd, frame))) {
            // ...
        }
        return self;
    }
    SwizzleSelectorWithBlock_End;
    
    SwizzleSelectorWithBlock_Begin(self, @selector(awakeFromNib))
    ^(UILabel *self) {
        ((void (*)(id, SEL))_imp)(self, _cmd);
        
        // ...
    }
    SwizzleSelectorWithBlock_End;

    SwizzleSelectorWithBlock_Begin(self, sel_getUid("dealloc"))
    ^(__unsafe_unretained UILabel *self) {
        // ...
        
        ((void (*)(id, SEL))_imp)(self, _cmd);
    }
    SwizzleSelectorWithBlock_End;
}

@end

I especially like the compactness of block-swizzling using macros. There is no need to define separate functions and method pointers, and the swizzled method implementation can be easily recognized, enclosed between the Begin and End macros.

Conclusion

The implementation discussed in this article might not be optimal, but should cover most practical cases. It is available from my CoconutKit framework, with a comprehensive test suite, or from the following gist. Have fun with method swizzling!

Sharing LLDB debugging helpers between projects using a dynamic library

2014-03-11T00:00:00+00:00

Xcode 5 added QuickLook support for standard types like UIImage, NSData or NSString, right within Xcode. Starting with Xcode 5.1, UIView and custom types can be quickly previewed as well, which can be quite convenient when debugging projects.

The LLDB-QuickLook project adds a similar functionality to the LLDB Xcode console as well, but requires some categories to be added to each project you want to use LLDB-QuickLook with. This process is rather inconvenient since it requires you to edit your projects to make these categories somehow available (most probably by including the corresponding source files).

Based on a trick similar to the one used to link in Reveal dynamic library, we can improve LLDB-QuickLook so that its categories can be used transparently with all your projects.

Instead of adding the categories to the projects, the LLDB-QuickLook categories can namely be packaged as a dynamic library, and made available when LLDB starts. Within the iOS simulator, the library can be loaded without dlopen-ing it from the application, and without jailbreaking. This is why this post only focuses on the iOS simulator.

The approach described below can be applied to your own LLDB debugging helpers, which can be packaged as a dynamic library shared between your projects.

Enabling iOS dynamic library compilation in Xcode

Apple does not officially provide a way to create dynamic libraries for iOS, since their use does not comply with App Store rules. Xcode unsurprisingly complains when we try to build one:

target specifies product type 'com.apple.product-type.library.dynamic', but there's no such product type for the 'iphonesimulator' platform

You can still enable iOS dynamic library support by editing some Xcode configuration files, though, as described elsewhere:

For the simulator, open the Mac OS specification file:

  /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Xcode/Specifications/MacOSX Product Types.xcspec

and copy over the section beginning with com.apple.product-type.library.dynamic to its iOS counterpart:

  /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/Library/Xcode/Specifications/iPhone Simulator ProductTypes.xcspec

Proceed similarly with the following files:

  /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Xcode/Specifications/MacOSX Package Types.xcspec
  /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/Library/Xcode/Specifications/iPhone Simulator PackageTypes.xcspec

and the section beginning with com.apple.package-type.mach-o-dylib

Restart Xcode to take the changes into account.

Building an LLDB-Quicklook dynamic library

To build a dynamic library we create a Mac OS X Cocoa Library project, setting its type to dynamic. We remove all useless stuff, set its SDK to Latest iOS and add LLDB-QuickLook source files. The resulting project can be found on my Github page, on a branch called dylib.

Checkout the repository, switch to the dylib branch and run the following command to build the library:

 xcodebuild -sdk iphonesimulator -configuration Release -project LLDB-QuickLook.xcodeproj

The dynamic library can be found in the build directory, and is called LLDB-QuickLook.dylib.

Loading the LLDB-QuickLook dynamic library into LLDB

To load the LLDB-QuickLook.dylib dynamic library when LLDB starts, copy it somewhere (e.g. ~/Library/lldb/lib/LLDB-QuickLook.dylib) and add the following line to your ~/.lldbinit configuration file:

command alias quick_look_load_sim process load ~/Library/lldb/lib/LLDB-QuickLook.dylib

replacing the path by the one you chose.

The quick_look_load_sim command can be manually triggered in LLDB to load the library (when running in the iOS simulator), but cannot work when no process has been attached.

To run the quick_look_load_sim command early when an application has been attached, add a user-defined symbolic breakpoint on a function which gets called early, e.g. UIApplicationMain. User-defined breakpoints are common to all you projects, and can trigger actions, like executing LLDB commands. To call our custom quick_look_load_sim command, add a Debugger Command action calling quick_look_load_sim to the breakpoint, and check Automatically continue after evaluating.

There is hope pending breakpoints might be added to LLDB in the future, in which case this trick could be replaced with pending breakpoints defined in the ~/.lldbinit file.

QuickLooking

Follow the LLDB-QuickLook installation steps and add the following commands to your ~/.lldbinit file:

command script import ~/Library/lldb/lldb_quick_look.py
command alias ql quicklook

Here I saved the Python script under ~/Library/lldb.

Now run any project in the simulator (be sure that the user-defined breakpoint is available), pause the execution, and try to enter a QuickLook LLDB command, e.g.

ql @"Hello, World!"

QuickLook should open and display the string.

Wrapping up

This post discussed how debugging code can be packaged as a dynamic library, and how it can be automatically loaded when an application is debugged in the iOS simulator. By applying the same strategy, you could package your own LLDB debugging helpers as dynamic libraries which can be shared between your projects, without having to modify them. Have fun!