03 · The reviews that won't stop loading

public struct Review: Decodable, Identifiable, Hashable, Sendable {
    ...

// MARK: - Service
public protocol ReviewsFetching: Sendable {
    func fetchReviews(tourID: String, page: Int) async throws -> ReviewPage
}

public actor ReviewsService: ReviewsFetching {
    // ... unchanged ...

import Foundation
import Observation
import ReviewsService

@Observable
final class TourReviewsViewModel {   // main actor: the target's default isolation
    enum Phase: Equatable {
        case loading            // the first page is on its way
        case loaded
        case failed(String)     // the first page failed: there is nothing to show
    }

    let tourID: String
    private(set) var phase: Phase = .loading
    private(set) var reviews: [Review] = []
    private(set) var totalCount = 0
    private(set) var hasMore = true
    private(set) var pageError: String?     // a later page failed: keep what's on screen

    init(tourID: String, service: any ReviewsFetching) {
        self.tourID = tourID
        self.service = service
    }

    /// The average of what's loaded so far, so it moves as pages arrive. The server should send it.
    var averageRating: Double? {
        guard !reviews.isEmpty else { return nil }
        return Double(reviews.map(\.rating).reduce(0, +)) / Double(reviews.count)
    }

    /// The first load, pull to refresh and Try again. Supersedes any page still in flight.
    func reload() async {
        generation += 1
        pageTask?.cancel()
        pageError = nil
        if case .failed = phase { phase = .loading }   // a refresh keeps the old list on screen
        let task = Task { [generation] in await load(page: 1, generation: generation) }
        pageTask = task
        await task.value
    }

    /// Called when the footer appears. A second call while a page is in flight joins it.
    func loadNextPage() async {
        if pageTask == nil {
            guard phase == .loaded, hasMore else { return }
            pageError = nil
            pageTask = Task { [nextPage, generation] in await load(page: nextPage, generation: generation) }
        }
        await pageTask?.value
    }

    @ObservationIgnored private let service: any ReviewsFetching
    @ObservationIgnored private var nextPage = 1
    @ObservationIgnored private var pageTask: Task<Void, Never>?   // owned here, not by a row
    @ObservationIgnored private var generation = 0

    private func load(page number: Int, generation: Int) async {
        defer { if generation == self.generation { pageTask = nil } }
        do {
            let page = try await service.fetchReviews(tourID: tourID, page: number)
            guard generation == self.generation else { return }   // a reload started meanwhile
            reviews = number == 1 ? page.reviews : reviews + page.reviews
            totalCount = page.totalCount
            nextPage = page.page + 1
            hasMore = page.page < page.totalPages
            phase = .loaded
        } catch is CancellationError {
            // superseded by a reload: not an error
        } catch {
            guard generation == self.generation else { return }
            if phase == .loaded {
                pageError = error.localizedDescription
            } else {
                phase = .failed(error.localizedDescription)
            }
        }
    }
}

import SwiftUI
import ReviewsService

struct TourReviewsView: View {
    @State private var viewModel: TourReviewsViewModel

    init(tourID: String = "berlin-wall-walk", service: any ReviewsFetching = ReviewsService()) {
        _viewModel = State(initialValue: TourReviewsViewModel(tourID: tourID, service: service))
    }

    var body: some View {
        NavigationStack {
            content
                .navigationTitle("Berlin Wall walk")
                .task { await viewModel.reload() }
        }
    }

    @ViewBuilder
    private var content: some View {
        switch viewModel.phase {
        case .loading:
            ProgressView()
        case .failed(let message):
            ContentUnavailableView {
                Label("Couldn't load reviews", systemImage: "exclamationmark.bubble")
            } description: {
                Text(message)
            } actions: {
                Button("Try again") { Task { await viewModel.reload() } }
            }
        case .loaded where viewModel.reviews.isEmpty:
            ContentUnavailableView("No reviews yet", systemImage: "star.bubble")
        case .loaded:
            List {
                Section {
                    ForEach(viewModel.reviews) { review in
                        ReviewRow(review: review)
                    }
                } header: {
                    RatingSummary(average: viewModel.averageRating, count: viewModel.totalCount)
                }
                footer
            }
            .refreshable { await viewModel.reload() }
        }
    }

    @ViewBuilder
    private var footer: some View {
        if let message = viewModel.pageError {
            Button {
                Task { await viewModel.loadNextPage() }
            } label: {
                Label("\(message) Try again", systemImage: "arrow.clockwise")
            }
        } else if viewModel.hasMore {
            ProgressView()
                .frame(maxWidth: .infinity)
                .task(id: viewModel.reviews.count) { await viewModel.loadNextPage() }   // re-arms after each page
        }
    }
}

/// v2: an opaque cursor. Filtering happens on the server.
public struct ReviewCursorPage: Decodable, Sendable {
    public let reviews: [Review]
    public let nextCursor: String?      // nil: there is nothing after this page
    public let matchingCount: Int       // reviews that pass the filter
    public let summary: ReviewSummary   // the whole tour, unfiltered

    public init(reviews: [Review], nextCursor: String?, matchingCount: Int, summary: ReviewSummary) {
        self.reviews = reviews
        self.nextCursor = nextCursor
        self.matchingCount = matchingCount
        self.summary = summary
    }
}

// MARK: - Service
public protocol ReviewsFetching: Sendable {
    func fetchReviews(tourID: String, minimumRating: Int?, cursor: String?) async throws -> ReviewCursorPage
}

import Foundation
import Observation
import ReviewsService

@Observable
final class TourReviewsViewModel {   // main actor: the target's default isolation
    enum Phase: Equatable {
        case loading            // the first page is on its way
        case loaded
        case failed(String)     // the first page failed: there is nothing to show
    }

    let tourID: String
    private(set) var phase: Phase = .loading
    private(set) var reviews: [Review] = []
    private(set) var summary: ReviewSummary?     // the whole tour: it does not follow the filter
    private(set) var matchingCount = 0           // reviews that pass the filter, counted by the server
    private(set) var pageError: String?          // a later page failed: keep what's on screen

    /// nil shows every rating. The server filters, so a new value starts a new cursor chain.
    var minimumRating: Int? {
        didSet {
            guard minimumRating != oldValue else { return }
            generation += 1                  // drop any page of the old chain still in flight
            pageTask?.cancel()
            pageTask = nil
            reviews = []
            cursor = nil
            isAtEnd = false
            pageError = nil
            phase = .loading
        }
    }

    var hasMore: Bool { !isAtEnd }

    init(tourID: String, service: any ReviewsFetching) {
        self.tourID = tourID
        self.service = service
    }

    /// The first load, a filter change, pull to refresh and Try again. Supersedes any page in flight.
    func reload() async {
        generation += 1
        pageTask?.cancel()
        pageError = nil
        if case .failed = phase { phase = .loading }   // a refresh keeps the old list on screen
        let task = Task { [generation] in await load(after: nil, generation: generation) }
        pageTask = task
        await task.value
    }

    /// Called when the footer appears. A second call while a page is in flight joins it.
    func loadNextPage() async {
        if pageTask == nil {
            guard phase == .loaded, let cursor else { return }   // no cursor: the chain has ended
            pageError = nil
            pageTask = Task { [generation] in await load(after: cursor, generation: generation) }
        }
        await pageTask?.value
    }

    @ObservationIgnored private let service: any ReviewsFetching
    @ObservationIgnored private var cursor: String?
    @ObservationIgnored private var pageTask: Task<Void, Never>?   // owned here, not by a row
    @ObservationIgnored private var generation = 0
    private var isAtEnd = false

    private func load(after cursor: String?, generation: Int) async {
        defer { if generation == self.generation { pageTask = nil } }
        do {
            let page = try await service.fetchReviews(tourID: tourID, minimumRating: minimumRating, cursor: cursor)
            guard generation == self.generation else { return }   // a reload or a new filter took over
            reviews = cursor == nil ? page.reviews : reviews + page.reviews
            self.cursor = page.nextCursor
            isAtEnd = page.nextCursor == nil
            matchingCount = page.matchingCount
            summary = page.summary
            phase = .loaded
        } catch is CancellationError {
            // superseded: not an error
        } catch {
            guard generation == self.generation else { return }
            if phase == .loaded {
                pageError = error.localizedDescription
            } else {
                phase = .failed(error.localizedDescription)
            }
        }
    }
}

    var body: some View {
        NavigationStack {
            content
                .navigationTitle("Berlin Wall walk")
                .toolbar { RatingFilter(minimumRating: $viewModel.minimumRating) }
                .task(id: viewModel.minimumRating) { await viewModel.reload() }   // runs on appear, then on every change
        }

        case .loaded where viewModel.reviews.isEmpty && viewModel.minimumRating != nil:
            ContentUnavailableView {
                Label("No reviews with \(viewModel.minimumRating ?? 0) stars or more", systemImage: "star.slash")
            } actions: {
                Button("Show all reviews") { viewModel.minimumRating = nil }
            }
        case .loaded where viewModel.reviews.isEmpty:
            ContentUnavailableView("No reviews yet", systemImage: "star.bubble")

                } header: {
                    RatingSummary(summary: viewModel.summary, minimumRating: viewModel.minimumRating,
                                  matchingCount: viewModel.matchingCount)
                }

}

struct RatingFilter: View {
    @Binding var minimumRating: Int?

    var body: some View {
        Menu {
            Picker("Minimum rating", selection: $minimumRating) {
                Text("All ratings").tag(Int?.none)
                ForEach([5, 4, 3, 2], id: \.self) { stars in
                    Text(stars == 5 ? "5 stars" : "\(stars) stars or more").tag(Optional(stars))
                }
            }
        } label: {
            Label("Filter", systemImage: minimumRating == nil
                  ? "line.3.horizontal.decrease.circle" : "line.3.horizontal.decrease.circle.fill")
        }
    }
}

struct RatingSummary: View {
    let summary: ReviewSummary?
    let minimumRating: Int?
    let matchingCount: Int

    var body: some View {
        VStack(alignment: .leading, spacing: 2) {
            if let summary {
                HStack {
                    Image(systemName: "star.fill")
                        .foregroundStyle(.yellow)
                    Text(summary.averageRating, format: .number.precision(.fractionLength(1)))
                        .font(.title2.bold())
                    Text("· \(summary.totalCount) reviews")
                }
                .accessibilityElement(children: .combine)
            }
            if let minimumRating {
                Text("Showing \(matchingCount) with \(minimumRating) stars or more")
                    .font(.footnote)
            }
        }
        .textCase(nil)

import Foundation
import Testing
import ReviewsService
@testable import TourReviews

/// Serves `reviews` in pages of `pageSize`, filtered like the server. The cursor is the next offset.
private actor FakeReviews: ReviewsFetching {
    struct Request: Equatable { let minimumRating: Int?; let cursor: String? }
    struct Offline: LocalizedError { var errorDescription: String? { "Offline" } }

    private(set) var requests: [Request] = []
    var failingCursors: Set<String> = []
    var delays: [Int?: Duration] = [:]     // per filter: lets an old request finish after a new one

    let reviews: [Review]
    let pageSize: Int

    init(_ reviews: [Review], pageSize: Int = 2) {
        self.reviews = reviews
        self.pageSize = pageSize
    }

    func failOnce(at cursor: String) { failingCursors.insert(cursor) }
    func delay(_ duration: Duration, for minimumRating: Int?) { delays[minimumRating] = duration }

    func fetchReviews(tourID: String, minimumRating: Int?, cursor: String?) async throws -> ReviewCursorPage {
        requests.append(Request(minimumRating: minimumRating, cursor: cursor))
        if let delay = delays[minimumRating] { try await Task.sleep(for: delay) }
        if let cursor, failingCursors.remove(cursor) != nil { throw Offline() }
        let matching = reviews.filter { $0.rating >= (minimumRating ?? 1) }
        let start = cursor.flatMap(Int.init) ?? 0
        let end = min(start + pageSize, matching.count)
        return ReviewCursorPage(reviews: Array(matching[start..<end]),
                                nextCursor: end < matching.count ? String(end) : nil,
                                matchingCount: matching.count,
                                summary: ReviewSummary(averageRating: 3.6, totalCount: reviews.count))
    }
}

private func review(_ id: Int, _ rating: Int) -> Review {
    Review(id: "r\(id)", author: "A", rating: rating, text: "", date: .now)
}

struct TourReviewsViewModelTests {
    let sample = [review(1, 5), review(2, 2), review(3, 4), review(4, 5), review(5, 1)]

    @Test func twoTriggersForOnePageSendOneRequest() async {
        let service = FakeReviews(sample)
        let viewModel = TourReviewsViewModel(tourID: "t", service: service)
        await viewModel.reload()

        async let first: Void = viewModel.loadNextPage()     // the footer appears twice
        async let second: Void = viewModel.loadNextPage()
        _ = await (first, second)

        #expect(viewModel.reviews.map(\.id) == ["r1", "r2", "r3", "r4"])
        #expect(await service.requests == [.init(minimumRating: nil, cursor: nil), .init(minimumRating: nil, cursor: "2")])
    }

    @Test func noRequestAfterTheLastPage() async {
        let service = FakeReviews(sample)
        let viewModel = TourReviewsViewModel(tourID: "t", service: service)
        await viewModel.reload()
        await viewModel.loadNextPage()
        await viewModel.loadNextPage()   // the last page: nextCursor is nil
        await viewModel.loadNextPage()   // must not ask again

        #expect(viewModel.reviews.count == 5)
        #expect(viewModel.hasMore == false)
        #expect(await service.requests.count == 3)
    }

    @Test func aFailedPageKeepsTheListAndRetries() async {
        let service = FakeReviews(sample)
        await service.failOnce(at: "2")
        let viewModel = TourReviewsViewModel(tourID: "t", service: service)
        await viewModel.reload()
        await viewModel.loadNextPage()

        #expect(viewModel.phase == .loaded)
        #expect(viewModel.reviews.map(\.id) == ["r1", "r2"])
        #expect(viewModel.pageError == "Offline")

        await viewModel.loadNextPage()   // Try again
        #expect(viewModel.reviews.map(\.id) == ["r1", "r2", "r3", "r4"])
        #expect(viewModel.pageError == nil)
    }

    @Test func aNewFilterStartsANewCursorChain() async {
        let service = FakeReviews(sample)
        let viewModel = TourReviewsViewModel(tourID: "t", service: service)
        await viewModel.reload()
        await viewModel.loadNextPage()

        viewModel.minimumRating = 4
        await viewModel.reload()

        #expect(viewModel.reviews.map(\.id) == ["r1", "r3"])
        #expect(viewModel.matchingCount == 3)
        #expect(await service.requests.last == .init(minimumRating: 4, cursor: nil))   // not cursor "4"
    }

    @Test func aSlowPageFromTheOldFilterIsDropped() async {
        let service = FakeReviews(sample)
        let viewModel = TourReviewsViewModel(tourID: "t", service: service)
        await viewModel.reload()
        await service.delay(.milliseconds(200), for: nil)
        let oldPage = Task { await viewModel.loadNextPage() }   // in flight for 200 ms
        await Task.yield()

        viewModel.minimumRating = 5
        await viewModel.reload()
        await oldPage.value

        #expect(viewModel.reviews.map(\.id) == ["r1", "r4"])
    }

    @Test func theAverageIsTheToursNotTheFilters() async {
        let viewModel = TourReviewsViewModel(tourID: "t", service: FakeReviews(sample))
        viewModel.minimumRating = 5
        await viewModel.reload()

        #expect(viewModel.summary == ReviewSummary(averageRating: 3.6, totalCount: 5))
    }
}