crossmate

PuzzleNotificationText.swift (8025B)

---

 import Foundation
 
 /// Composes the visible text of a Crossmate notification from its parts. This
 /// is the single source of truth for alert wording: the sender builds the body
 /// it ships through these builders, and the notification service extension
 /// calls the same ones (via `PushPayload.composedBody`) to rebuild the body
 /// with the recipient's private nickname in place of the sender's name. Pure
 /// string logic only, so it lives in `Shared` and compiles into both the app
 /// and the extension.
 enum PuzzleNotificationText {
     static func title(_ title: String, publisher: String?, date: Date?) -> String {
         let subtitle = subtitle(publisher: publisher, date: date)
         guard let subtitle else { return title }
         return "\(title) – \(subtitle)"
     }
 
     /// Body for a nudge push: "Alice nudged you to play the puzzle 'X'". A
     /// deliberate rouse from the in-game players menu, so it always names an
     /// action even when nothing in the grid changed.
     static func nudgeBody(playerName: String, puzzleTitle: String) -> String {
         "\(resolvedName(playerName)) nudged you to play \(puzzleSuffix(puzzleTitle))"
     }
 
     /// Body for a join push: "Alice joined the puzzle 'X'". Sent to everyone
     /// already in the room when a new player accepts the invitation, so it
     /// always names the action even though joining changes nothing in the grid.
     static func joinBody(playerName: String, puzzleTitle: String) -> String {
         "\(resolvedName(playerName)) joined \(puzzleSuffix(puzzleTitle))"
     }
 
     /// Body for an invite push: "Alice invited you to the puzzle 'X'".
     static func inviteBody(playerName: String, puzzleTitle: String) -> String {
         "\(resolvedName(playerName)) invited you to \(puzzleSuffix(puzzleTitle))"
     }
 
     /// Body for a completion push — "Alice solved …" or, when `resigned`,
     /// "Alice resigned …" (the resign sentence ends in a full stop to match the
     /// app's existing wording).
     static func completionBody(
         playerName: String,
         puzzleTitle: String,
         resigned: Bool
     ) -> String {
         let name = resolvedName(playerName)
         let suffix = puzzleSuffix(puzzleTitle)
         return resigned
             ? "\(name) resigned \(suffix)."
             : "\(name) solved \(suffix)"
     }
 
     /// Body for a session-end push, addressed to a single recipient,
     /// describing what the peer did since that recipient last looked (entries
     /// in the peer's journal newer than the recipient's last-known
     /// `Player.presenceUntil`): net letter `fills` / `clears`, and the number of
     /// `checks` / `reveals` *gestures* run. When every count is zero the
     /// recipient still gets the push as a presence signal ("stopped solving")
     /// — the session end is worth surfacing even with nothing unseen — but the
     /// payload's zero counts keep it from bumping the badge.
     static func pauseBody(
         playerName: String,
         puzzleTitle: String,
         fills: Int,
         clears: Int,
         checks: Int,
         reveals: Int
     ) -> String {
         let name = resolvedName(playerName)
         let suffix = puzzleSuffix(puzzleTitle)
         guard let actions = pauseActions(fills: fills, clears: clears, checks: checks, reveals: reveals) else {
             return "\(name) stopped solving \(suffix)."
         }
         return "\(name) \(actions) in \(suffix)"
     }
 
     /// The action phrase of a pause — "filled 3 letters and ran 1 check" —
     /// without the name or puzzle suffix, or `nil` when nothing changed. Shared
     /// by `pauseBody` and the multi-contributor `coalescedBody` so a single
     /// sender and a coalesced one read in exactly the same voice.
     private static func pauseActions(
         fills: Int,
         clears: Int,
         checks: Int,
         reveals: Int
     ) -> String? {
         func letters(_ n: Int) -> String { "\(n) \(n == 1 ? "letter" : "letters")" }
 
         var clauses: [String] = []
         if fills > 0 { clauses.append("filled \(letters(fills))") }
         if clears > 0 { clauses.append("cleared \(letters(clears))") }
         // Checks and reveals are help gestures; fold them into one "ran …"
         // clause so the sentence doesn't repeat the verb.
         var help: [String] = []
         if checks > 0 { help.append("\(checks) \(checks == 1 ? "check" : "checks")") }
         if reveals > 0 { help.append("\(reveals) \(reveals == 1 ? "reveal" : "reveals")") }
         if !help.isEmpty { clauses.append("ran \(joinList(help))") }
 
         return clauses.isEmpty ? nil : joinList(clauses)
     }
 
     /// Body for a coalesced game tile that has folded together one or more
     /// session-end (`pause`) updates (see `CoalescedSummary`). Each contributor
     /// is described in the same wording a single pause uses; several are joined
     /// with semicolons and the puzzle is named once at the end ("Alice filled 5
     /// letters and cleared 1 letter; Bob filled 3 letters in the puzzle 'X'").
     /// Returns `nil` when there is nothing to summarise.
     static func coalescedBody(
         puzzleTitle: String,
         contributors: [CoalescedSummary.Contributor]
     ) -> String? {
         switch contributors.count {
         case 0:
             return nil
         case 1:
             let only = contributors[0]
             return pauseBody(
                 playerName: only.name,
                 puzzleTitle: puzzleTitle,
                 fills: only.fills,
                 clears: only.clears,
                 checks: only.checks,
                 reveals: only.reveals
             )
         default:
             // One player per clause in the single-pause voice, separated by
             // semicolons (each clause already uses commas/"and" internally),
             // with the puzzle named once at the end.
             let phrases = contributors.map { contributor -> String in
                 let name = resolvedName(contributor.name)
                 guard let actions = pauseActions(
                     fills: contributor.fills,
                     clears: contributor.clears,
                     checks: contributor.checks,
                     reveals: contributor.reveals
                 ) else {
                     // A contributor always has unseen changes (a pause is only
                     // sent when it does), so this is unreachable in practice;
                     // degrade to a neutral phrase rather than drop them.
                     return "\(name) made changes"
                 }
                 return "\(name) \(actions)"
             }
             return "\(phrases.joined(separator: "; ")) in \(puzzleSuffix(puzzleTitle))"
         }
     }
 
     /// The empty name falls back to a neutral label, so a peer who hasn't set a
     /// name still reads as a person rather than a blank.
     private static func resolvedName(_ name: String) -> String {
         name.isEmpty ? "A player" : name
     }
 
     /// "the puzzle" alone, or "the puzzle 'Title'" when a title is known.
     private static func puzzleSuffix(_ title: String) -> String {
         title.isEmpty ? "the puzzle" : "the puzzle '\(title)'"
     }
 
     /// Joins clauses into prose: "a", "a and b", or "a, b and c".
     private static func joinList(_ parts: [String]) -> String {
         switch parts.count {
         case 0: return ""
         case 1: return parts[0]
         case 2: return "\(parts[0]) and \(parts[1])"
         default: return "\(parts.dropLast().joined(separator: ", ")) and \(parts[parts.count - 1])"
         }
     }
 
     private static func subtitle(publisher: String?, date: Date?) -> String? {
         let formattedDate = date?.formatted(date: .long, time: .omitted)
         if let publisher, !publisher.isEmpty, let formattedDate {
             return "\(publisher) · \(formattedDate)"
         }
         if let formattedDate {
             return formattedDate
         }
         if let publisher, !publisher.isEmpty {
             return publisher
         }
         return nil
     }
 }