← All repositories

crossmate

A collaborative crossword app for iPhone and iPad

git clone https://code.inqk.net/crossmate.git


Crossmate/Services/AnnouncementCenter.swift (11432B)

1import Foundation
2import Observation
3
4/// One-shot status message surfaced in a banner area — the puzzle header
5/// when scoped to a game, the game list when global. Designed to host both
6/// info-class summaries (e.g. "Alice added 4 letters")
7/// and error-class failures (e.g. "Couldn't accept invite") that previously
8/// went through modal alerts.
9struct Announcement: Identifiable, Equatable, Sendable {
10    /// Severity of an announcement, used both for visual treatment and for
11    /// pick-the-winner logic when two announcements compete for the same
12    /// surface — higher-severity displaces lower.
13    enum Severity: Int, Comparable, Sendable {
14        /// Lowest severity: onboarding tips. Ranked below `info` so a tip never
15        /// displaces a real status message and is itself displaced by one.
16        case tip
17        case info
18        case warning
19        case error
20
21        static func < (lhs: Severity, rhs: Severity) -> Bool { lhs.rawValue < rhs.rawValue }
22    }
23
24    /// Dismissal behavior. `.transient` auto-clears after the given delay;
25    /// `.manual` stays until the user taps it away; `.sticky` requires
26    /// programmatic dismissal (the producer must call `dismiss(id:)`
27    /// itself). `.sticky` is the only kind that pairs sensibly with
28    /// `blocksInput`.
29    enum Dismissal: Equatable, Sendable {
30        case transient(after: TimeInterval)
31        case manual
32        case sticky
33    }
34
35    /// Surface scope. Game-scoped announcements take priority over global
36    /// ones at the puzzle header; global-only ones surface on the game
37    /// list. A producer that has a relevant `gameID` should prefer
38    /// `.game(_)` so the announcement only appears where it makes sense.
39    enum Scope: Hashable, Sendable {
40        case global
41        case game(UUID)
42    }
43
44    /// Stable id; reposting with the same id replaces the prior
45    /// announcement in place rather than queueing another behind it.
46    let id: String
47    let scope: Scope
48    let severity: Severity
49    let title: String?
50    let body: String
51    let dismissal: Dismissal
52    /// When true, the puzzle's input layer (custom keyboard + hardware key
53    /// handler) is greyed out and ignores input for as long as this
54    /// announcement is showing. Only sensible alongside `.sticky`.
55    let blocksInput: Bool
56    let createdAt: Date
57
58    init(
59        id: String,
60        scope: Scope,
61        severity: Severity,
62        title: String? = nil,
63        body: String,
64        dismissal: Dismissal,
65        blocksInput: Bool = false,
66        createdAt: Date = Date()
67    ) {
68        self.id = id
69        self.scope = scope
70        self.severity = severity
71        self.title = title
72        self.body = body
73        self.dismissal = dismissal
74        self.blocksInput = blocksInput
75        self.createdAt = createdAt
76    }
77}
78
79extension Announcement {
80    /// The sticky, input-blocking banner shown when a shared puzzle's
81    /// owner revokes the local user's access. Folds the former bespoke
82    /// `AccessRevokedBanner` overlay into the announcement system, so the
83    /// revoked puzzle's keyboard and hardware keys grey out for as long
84    /// as the banner shows.
85    static func accessRevoked(gameID: UUID) -> Announcement {
86        Announcement(
87            id: "access-revoked-\(gameID.uuidString)",
88            scope: .game(gameID),
89            severity: .error,
90            title: "Puzzle Not Shared",
91            body: "This puzzle is no longer shared with you.",
92            dismissal: .sticky,
93            blocksInput: true
94        )
95    }
96
97    /// The sticky, input-blocking banner shown when the open puzzle's game is
98    /// hard-deleted out from under it — a solo puzzle's private zone vanished,
99    /// or a shared puzzle was left on another device. Game-scoped, so it only
100    /// surfaces in that puzzle's header, never the game list; the caller posts
101    /// it only when the removed game is the one on screen. The puzzle stays
102    /// open and frozen until the user backs out — by then it is already gone
103    /// from the list.
104    static func gameRemoved(gameID: UUID) -> Announcement {
105        Announcement(
106            id: "game-removed-\(gameID.uuidString)",
107            scope: .game(gameID),
108            severity: .error,
109            title: "Puzzle Removed",
110            body: "This puzzle was removed.",
111            dismissal: .sticky,
112            blocksInput: true
113        )
114    }
115
116    /// The sticky, input-blocking banner shown when a game uses sync semantics
117    /// this app release does not implement. The merged puzzle remains visible,
118    /// but local edits are disabled so this client cannot publish state that
119    /// other participants would resolve differently.
120    static func unsupportedSyncVersion(gameID: UUID) -> Announcement {
121        Announcement(
122            id: "unsupported-sync-version-\(gameID.uuidString)",
123            scope: .game(gameID),
124            severity: .error,
125            title: "Crossmate Update Required",
126            body: "Update Crossmate to make changes to this puzzle.",
127            dismissal: .sticky,
128            blocksInput: true
129        )
130    }
131
132    /// Reassurance shown on the Game List when a share was accepted but its
133    /// puzzle had not finished syncing before the join wait timed out. The game
134    /// surfaces on its own once sync settles, so this clears itself rather than
135    /// asking the user to act.
136    static func puzzleStillSyncing() -> Announcement {
137        Announcement(
138            id: "share-join-pending-sync",
139            scope: .global,
140            severity: .info,
141            title: "Puzzle Unavailable",
142            body: "This puzzle is still syncing and will appear in your list shortly.",
143            dismissal: .transient(after: 6)
144        )
145    }
146}
147
148/// The persisted, open-relevant facts about a game — the input to
149/// `OpenPuzzleBanner.announcements(for:)`. Grouped into a value so the
150/// reconciler can be unit-tested without standing up a `GameMutator`.
151struct OpenPuzzleState {
152    let gameID: UUID
153    let isAccessRevoked: Bool
154    let isSyncSupported: Bool
155}
156
157/// A banner that may be (re)posted when a puzzle is opened, reconciled from
158/// *persisted* game state rather than a live sync transition. Each such
159/// banner is otherwise posted only on the event that first produces it, into
160/// an in-memory `AnnouncementCenter` that does not survive a process restart
161/// — so a puzzle opened in a later process would show nothing. Extend by
162/// adding a case and its switch arm.
163enum OpenPuzzleBanner: CaseIterable {
164    case accessRevoked
165    case unsupportedSyncVersion
166
167    /// The announcement this banner contributes for `state`, or `nil` when
168    /// the state does not warrant it.
169    func announcement(for state: OpenPuzzleState) -> Announcement? {
170        switch self {
171        case .accessRevoked:
172            state.isAccessRevoked ? .accessRevoked(gameID: state.gameID) : nil
173        case .unsupportedSyncVersion:
174            state.isSyncSupported ? nil : .unsupportedSyncVersion(gameID: state.gameID)
175        }
176    }
177
178    /// Every banner to (re)post for a puzzle opened in `state`. The caller
179    /// posts each one; `AnnouncementCenter.post` is idempotent by id, so
180    /// re-posting a banner that is already showing is a no-op.
181    static func announcements(for state: OpenPuzzleState) -> [Announcement] {
182        allCases.compactMap { $0.announcement(for: state) }
183    }
184}
185
186/// Single source of truth for transient banner-style status messages. Holds
187/// at most one announcement per scope; reposting with the same id replaces
188/// the prior copy. Surfaces (PuzzleHeader, GameListView) read via the
189/// scope-specific accessors and observe via `@Observable`.
190@MainActor
191@Observable
192final class AnnouncementCenter {
193    /// All active announcements, keyed by id. Kept private so callers go
194    /// through `current(forGame:)` / `currentGlobal()` and inherit the
195    /// scope-precedence rule (game > global) consistently.
196    private var byId: [String: Announcement] = [:]
197    /// Auto-dismiss tasks for `.transient` announcements; cancelled when
198    /// the announcement is replaced or dismissed early so we don't fire a
199    /// stale dismissal against a fresh announcement that happens to share
200    /// the id.
201    private var dismissalTasks: [String: Task<Void, Never>] = [:]
202    /// Sleep primitive used by transient auto-dismiss timers. Injected so
203    /// tests can drive expiry deterministically instead of racing wall-clock
204    /// `Task.sleep` on a contended simulator.
205    private let sleep: @Sendable (Duration) async throws -> Void
206
207    init(
208        sleep: @escaping @Sendable (Duration) async throws -> Void = { try await Task.sleep(for: $0) }
209    ) {
210        self.sleep = sleep
211    }
212
213    func post(_ announcement: Announcement) {
214        if let existing = dismissalTasks.removeValue(forKey: announcement.id) {
215            existing.cancel()
216        }
217        byId[announcement.id] = announcement
218        if case let .transient(after) = announcement.dismissal {
219            let id = announcement.id
220            let sleep = self.sleep
221            dismissalTasks[id] = Task { @MainActor [weak self] in
222                try? await sleep(.seconds(after))
223                guard !Task.isCancelled else { return }
224                self?.autoDismiss(id: id)
225            }
226        }
227    }
228
229    func dismiss(id: String) {
230        byId.removeValue(forKey: id)
231        if let task = dismissalTasks.removeValue(forKey: id) {
232            task.cancel()
233        }
234    }
235
236    /// Topmost announcement to display in the puzzle header for `gameID`.
237    /// Prefers game-scoped over global so a puzzle-relevant message isn't
238    /// hidden behind an app-wide one; ties broken by severity, then by
239    /// createdAt (newest wins). Tips are excluded entirely: they're a Game
240    /// List-only affordance and must never surface over the puzzle grid.
241    func current(forGame gameID: UUID) -> Announcement? {
242        let gameScoped = byId.values.filter { $0.scope == .game(gameID) }
243        if let pick = pick(from: gameScoped) { return pick }
244        let global = currentGlobal()
245        return global?.severity == .tip ? nil : global
246    }
247
248    /// Topmost global announcement (used by surfaces that have no specific
249    /// game context, like the game list).
250    func currentGlobal() -> Announcement? {
251        pick(from: byId.values.filter { $0.scope == .global })
252    }
253
254    /// Whether any currently-showing announcement for `gameID` flags input
255    /// as blocked. Drives the greyed-out keyboard + hardware-key gating.
256    func isInputBlocked(forGame gameID: UUID) -> Bool {
257        current(forGame: gameID)?.blocksInput == true
258    }
259
260    private func pick(from candidates: some Collection<Announcement>) -> Announcement? {
261        candidates.max { lhs, rhs in
262            if lhs.severity != rhs.severity { return lhs.severity < rhs.severity }
263            return lhs.createdAt < rhs.createdAt
264        }
265    }
266
267    private func autoDismiss(id: String) {
268        // Re-check before removing: a later `post(_:)` may have superseded
269        // this announcement with a non-transient one under the same id.
270        guard let active = byId[id],
271              case .transient = active.dismissal
272        else {
273            dismissalTasks.removeValue(forKey: id)
274            return
275        }
276        byId.removeValue(forKey: id)
277        dismissalTasks.removeValue(forKey: id)
278    }
279}