crossmate

TipStore.swift (9941B)

---

 import Foundation
 import Observation
 import UIKit
 
 /// A device family a tip can be scoped to. The app runs on iPhone and iPad; a
 /// tip lists the platforms it should appear on (its `only` set), defaulting to
 /// all of them.
 enum TipPlatform: Hashable, CaseIterable {
     case iPhone
     case iPad
 
     /// Every platform — the default `only` value, i.e. "show everywhere".
     static let all: Set<TipPlatform> = Set(allCases)
 
     /// The platform of the device the app is running on.
     @MainActor static var current: TipPlatform {
         UIDevice.current.userInterfaceIdiom == .pad ? .iPad : .iPhone
     }
 }
 
 /// One onboarding tip shown in the Game List announcement banner and listed in
 /// `Settings → Tips`. The catalog is ordered; `TipStore` walks it in order,
 /// surfacing the first tip the user has not yet dismissed.
 struct Tip: Identifiable, Equatable {
     let id: String
     let title: String
     let body: String
     /// Platforms this tip appears on. Defaults to all of them; e.g. `[.iPad]`
     /// makes it iPad-only.
     var only: Set<TipPlatform> = TipPlatform.all
 }
 
 enum TipCatalog {
     /// Ordered tips. One surfaces per cold launch until each has been dismissed.
     /// Body wraps to at most three lines in the banner (`AnnouncementBanner`
     /// caps the body at `lineLimit(3)`), title to one. Scope a tip to a device
     /// family with `only:` (e.g. the iPad-only hardware-keyboard tip).
     static let all: [Tip] = [
         Tip(
             id: "solve-together",
             title: "Try a Multiplayer Crossword",
             body: "Start a puzzle and choose Invite Players from the Players menu."
         ),
         Tip(
             id: "connect-providers",
             title: "Get More Puzzles",
             body: "Add an external provider in Settings. Connected providers appear on the new puzzle screen."
         ),
         Tip(
             id: "pick-your-colour",
             title: "Pick Your Colour",
             body: "Choose your colour. A different colour is selected each time for crossmates."
         ),
         Tip(
             id: "get-attention",
             title: "Announce Your Availability",
             body: "Nudge your crossmates from the Players menu in a shared puzzle."
         ),
         Tip(
             id: "be-notified",
             title: "Control Your Notifications",
             body: "Adjust the notifications you want to see in Settings."
         ),
         Tip(
             id: "take-a-hint",
             title: "Get Unstuck in Difficult Puzzles",
             body: "Use the Hints menu in a puzzle to check your letters or get an answer."
         ),
         Tip(
             id: "import-puzzles",
             title: "Import Your Own Puzzles",
             body: "Download Across Lite or XD files in Safari or save to the Crossmate folder in iCloud Drive."
         ),
         Tip(
             id: "undo-redo",
             title: "Undo Mistakes Easily",
             body: "Press the overflow button on the onscreen keyboard to access undo and redo."
         ),
         Tip(
             id: "hardware-keyboard",
             title: "Use a Hardware Keyboard",
             body: "Connect a keyboard to solve more swiftly.",
             only: [.iPad]
         ),
         Tip(
             id: "partial-fill",
             title: "Break Solver's Block",
             body: "Choose Fill Quarter or Fill Half from the Hints menu to reveal random squares."
         ),
         Tip(
             id: "manage-blocked",
             title: "Block and Unblock Users",
             body: "Block using the Crossmates menu in the Game List. Unblock from your block list in Settings."
         ),
         Tip(
             id: "start-shared",
             title: "Start a Shared Puzzle",
             body: "Tap the Crossmates button in the Game List and tap a crossmate to start a shared puzzle with them."
         ),
         Tip(
             id: "share-your-win",
             title: "Share Your Solve",
             body: "Use the Share control when you've completed a puzzle to show everyone your solve."
         ),
     ]
 }
 
 /// Device-local record of which tips the user has dismissed, plus a global
 /// opt-out flag, persisted in `UserDefaults`. Modelled on `GameViewedStore`:
 /// never synced, purely local presentation state. `@Observable` so the
 /// `Settings → Tips` re-enable control reacts to the opt-out flag flipping.
 @MainActor
 @Observable
 final class TipStore {
     /// Cold launches that pass tip-free before the banner ever appears. A brand
     /// new user's first couple of visits to the Game List should be about the
     /// library, not onboarding chrome, so tips hold off until the launch after
     /// this many. Counting is cold-launch based (see `noteColdLaunch`), matching
     /// how tips are surfaced one-per-launch.
     static let launchesBeforeTips = 2
 
     /// When true the user chose "Never show me tips"; no tip is surfaced until
     /// they re-enable from Settings.
     var isDisabled: Bool {
         didSet { defaults.set(isDisabled, forKey: disabledKey) }
     }
 
     /// Catalog ids the user has dismissed from the Game List banner. Once
     /// dismissed, a tip never returns there (but stays in the Settings archive).
     private var dismissedIDs: Set<String> {
         didSet { defaults.set(Array(dismissedIDs), forKey: dismissedKey) }
     }
 
     /// Cold launches noted so far, persisted so the warm-up survives restarts.
     /// Capped just past `launchesBeforeTips` — once tips are due there's no
     /// reason to keep counting, so the stored value can't grow without bound.
     private var coldLaunchCount: Int {
         didSet { defaults.set(coldLaunchCount, forKey: coldLaunchCountKey) }
     }
 
     @ObservationIgnored private let defaults: UserDefaults
     @ObservationIgnored private let catalog: [Tip]
     @ObservationIgnored private let platform: TipPlatform
     @ObservationIgnored private let disabledKey = "tipsDisabled"
     @ObservationIgnored private let dismissedKey = "dismissedTipIDs"
     @ObservationIgnored private let coldLaunchCountKey = "tipColdLaunchCount"
 
     init(
         defaults: UserDefaults = .standard,
         catalog: [Tip] = TipCatalog.all,
         platform: TipPlatform = .current
     ) {
         self.defaults = defaults
         self.catalog = catalog
         self.platform = platform
         self.isDisabled = defaults.bool(forKey: disabledKey)
         self.dismissedIDs = Set(defaults.stringArray(forKey: dismissedKey) ?? [])
         self.coldLaunchCount = defaults.integer(forKey: coldLaunchCountKey)
     }
 
     /// Records that a fresh process has reached the Game List. Call once per
     /// cold launch, ahead of `currentTip()`. Stops incrementing once the warm-up
     /// is satisfied so the persisted count stays bounded.
     func noteColdLaunch() {
         guard coldLaunchCount <= Self.launchesBeforeTips else { return }
         coldLaunchCount += 1
     }
 
     /// Catalog tips that apply to this device, in order. Tips scoped to other
     /// platforms via `only` are filtered out, so neither the Game List banner
     /// nor the Settings archive surfaces them here.
     var visibleTips: [Tip] {
         catalog.filter { $0.only.contains(platform) }
     }
 
     /// The tip to surface now: the first applicable tip the user hasn't
     /// dismissed, or `nil` when tips are disabled, still within the launch
     /// warm-up (`launchesBeforeTips`), or every one has been seen.
     func currentTip() -> Tip? {
         guard !isDisabled else { return nil }
         guard coldLaunchCount > Self.launchesBeforeTips else { return nil }
         return firstUndismissedTip()
     }
 
     /// The first applicable tip the user hasn't dismissed, regardless of the
     /// disabled flag. This is the tip currently posted to the banner (a cold
     /// launch posts it before any toggle could disable tips), so turning tips
     /// off needs it to know which announcement to clear.
     func firstUndismissedTip() -> Tip? {
         visibleTips.first { !dismissedIDs.contains($0.id) }
     }
 
     /// Records that `id` was dismissed from the Game List banner.
     func markDismissed(_ id: String) {
         guard dismissedIDs.insert(id).inserted else { return }
     }
 
     /// Turns tips off entirely ("Never show me tips").
     func disable() { isDisabled = true }
 
     /// Re-enables tips; the next cold launch surfaces the next undismissed one.
     func enable() { isDisabled = false }
 }
 
 extension Tip {
     /// Announcement id namespace for tips, so the Game List can tell a tip
     /// banner apart from a real announcement when it's dismissed.
     static func announcementID(for tipID: String) -> String { "tip-\(tipID)" }
 
     /// Recovers the catalog tip id from a live banner's announcement id, or
     /// `nil` when the announcement isn't a tip.
     static func tipID(fromAnnouncementID announcementID: String) -> String? {
         let prefix = "tip-"
         guard announcementID.hasPrefix(prefix) else { return nil }
         return String(announcementID.dropFirst(prefix.count))
     }
 
     /// The live Game List banner for this tip: manually dismissable, lowest
     /// severity (`.tip`) so any real announcement displaces it.
     func liveAnnouncement() -> Announcement {
         Announcement(
             id: Self.announcementID(for: id),
             scope: .global,
             severity: .tip,
             title: title,
             body: body,
             dismissal: .manual
         )
     }
 
     /// The read-only rendering for the Settings archive: same styling, no close
     /// control. `.sticky` shows no ✕ and runs no auto-dismiss timer when the
     /// banner is rendered directly rather than posted to an `AnnouncementCenter`.
     func archiveAnnouncement() -> Announcement {
         Announcement(
             id: Self.announcementID(for: id),
             scope: .global,
             severity: .tip,
             title: title,
             body: body,
             dismissal: .sticky
         )
     }
 }