crossmate

GridAccessibility.swift (24637B)

---

 import SwiftUI
 
 /// Builds the VoiceOver label/value strings for one grid cell. Pure and
 /// UI-free so the wording is unit-testable without any view scaffolding.
 struct CellAccessibilityDescriber {
     let puzzle: Puzzle
     /// Display names keyed by authorID, spoken as "filled by <name>" on a
     /// filled square ("you" for the local player). Empty when author
     /// attribution should not be spoken (solo games, hidden annotations).
     let authorNames: [String: String]
 
     /// The cell's position within its word(s): "5 Across, letter 2 of 7;
     /// 3 Down, letter 4 of 5", dropping either half when the cell isn't part
     /// of a crossing word. A cell in no word at all (a length-1 run) falls
     /// back to its coordinates so it still reads as something.
     func label(atRow row: Int, atCol col: Int) -> String {
         var parts: [String] = []
         for direction in [Puzzle.Direction.across, .down] {
             let cells = puzzle.wordCells(atRow: row, col: col, direction: direction)
             guard let number = cells.first?.number,
                   let index = cells.firstIndex(where: { $0.row == row && $0.col == col })
             else { continue }
             let name = direction == .across ? "Across" : "Down"
             parts.append("\(number) \(name), letter \(index + 1) of \(cells.count)")
         }
         if parts.isEmpty {
             parts.append("Row \(row + 1), Column \(col + 1)")
         }
         let special = puzzle.cells[row][col].special
         if special == .circled { parts.append("circled") }
         if special == .shaded { parts.append("shaded") }
         return parts.joined(separator: "; ")
     }
 
     /// The spoken heading for a clue: "5 Across: Big cheese in Holland".
     /// Used both as the rotor entry label and as the announcement prefix.
     /// Nil when no clue carries that number in that direction.
     func clueLabel(number: Int, direction: Puzzle.Direction) -> String? {
         let clues = direction == .across ? puzzle.acrossClues : puzzle.downClues
         guard let clue = clues.first(where: { $0.number == number }) else { return nil }
         let name = direction == .across ? "Across" : "Down"
         return "\(number) \(name): \(clue.text)"
     }
 
     /// The announcement posted when the cursor enters a new word or the
     /// direction toggles: the clue heading plus progress — "5 Across: Big
     /// cheese in Holland. 7 letters, 3 filled." A zero filled-count is
     /// omitted; a complete word is spoken as "all filled". Nil when the cell
     /// has no word in `direction`.
     func clueAnnouncement(
         atRow row: Int,
         atCol col: Int,
         direction: Puzzle.Direction,
         squares: [[Square]]
     ) -> String? {
         let cells = puzzle.wordCells(atRow: row, col: col, direction: direction)
         guard let number = cells.first?.number,
               let heading = clueLabel(number: number, direction: direction)
         else { return nil }
         let filled = cells.count { !squares[$0.row][$0.col].entry.isEmpty }
         var progress = "\(cells.count) letters"
         if filled == cells.count {
             progress += ", all filled"
         } else if filled > 0 {
             progress += ", \(filled) filled"
         }
         return "\(heading). \(progress)"
     }
 
     /// The coalesced announcement for a burst of peer fills: "Alice filled
     /// 5 Across" when the burst completes a single word, "Alice filled
     /// 3 squares in 5 Across" while it's still open, and a plain square
     /// count when the burst spans words. Gap cells count as filled for the
     /// completeness read, matching the completion logic.
     func peerFillAnnouncement(
         playerName: String,
         positions: Set<GridPosition>,
         squares: [[Square]]
     ) -> String? {
         guard let first = positions.first else { return nil }
         for direction in [Puzzle.Direction.across, .down] {
             let cells = puzzle.wordCells(atRow: first.row, col: first.col, direction: direction)
             guard let number = cells.first?.number else { continue }
             let wordPositions = Set(cells.map { GridPosition(row: $0.row, col: $0.col) })
             guard positions.isSubset(of: wordPositions) else { continue }
             let word = "\(number) \(direction == .across ? "Across" : "Down")"
             let complete = cells.allSatisfy {
                 !squares[$0.row][$0.col].entry.isEmpty || $0.expectsBlank
             }
             if complete { return "\(playerName) filled \(word)" }
             if positions.count == 1 { return "\(playerName) filled a square in \(word)" }
             return "\(playerName) filled \(positions.count) squares in \(word)"
         }
         return positions.count == 1
             ? "\(playerName) filled a square"
             : "\(playerName) filled \(positions.count) squares"
     }
 
     /// The outcome of a check gesture over `cells`, read against the marks
     /// the check just applied. Single-cell checks read as a bare verdict;
     /// word checks count mistakes and unfilled squares.
     func checkAnnouncement(for cells: [Puzzle.Cell], squares: [[Square]]) -> String {
         let open = cells.filter { !$0.isBlock }
         let filled = open.filter { !squares[$0.row][$0.col].entry.isEmpty }
         guard !filled.isEmpty else { return "Nothing to check" }
         let wrong = filled.count { squares[$0.row][$0.col].mark.isCheckedWrong }
         if open.count == 1 {
             return wrong > 0 ? "Incorrect" : "Correct"
         }
         if wrong > 0 {
             return wrong == 1 ? "1 square incorrect" : "\(wrong) squares incorrect"
         }
         let empty = open.count - filled.count
         if empty == 0 { return "All correct" }
         return empty == 1
             ? "No mistakes, 1 square empty"
             : "No mistakes, \(empty) squares empty"
     }
 
     /// Speaks the letter a reveal just wrote: "Revealed R". Nil when the
     /// reveal was a no-op (e.g. a gap cell, whose correct state is empty).
     func revealAnnouncement(atRow row: Int, atCol col: Int, squares: [[Square]]) -> String? {
         let entry = squares[row][col].entry
         guard !entry.isEmpty else { return nil }
         return "Revealed \(entry)"
     }
 
     /// The grid-completion announcement. `.incomplete` is a return to normal
     /// play and stays silent. `.filledWithErrors` is the state a sighted
     /// player notices by the absence of the success panel — for a blind
     /// player it must be said out loud.
     func completionAnnouncement(for state: Game.CompletionState) -> String? {
         switch state {
         case .incomplete: nil
         case .filledWithErrors: "The grid is full, but something isn't right"
         case .solved: "Puzzle solved. Congratulations!"
         }
     }
 
     /// The cell's fill and its provenance: "Empty", "R", "R, draft",
     /// "R, revealed", "R, incorrect", plus "filled by Alice" when author
     /// names are being spoken. "Draft" matches the keyboard's user-facing
     /// term for pencil mode.
     func value(for square: Square) -> String {
         guard !square.entry.isEmpty else { return "Empty" }
         var parts = [square.entry]
         if square.mark.isPencil { parts.append("draft") }
         if square.mark.isRevealed { parts.append("revealed") }
         if square.mark.isCheckedWrong { parts.append("incorrect") }
         if let authorID = square.letterAuthorID, let name = authorNames[authorID] {
             parts.append("filled by \(name)")
         }
         return parts.joined(separator: ", ")
     }
 }
 
 extension View {
     /// Synthesises a VoiceOver representation for the Canvas-drawn puzzle
     /// grid: one accessibility element per open cell, framed to match the
     /// drawn cell exactly (so touch exploration works and blocks read as
     /// gaps), plus two-way sync between VoiceOver focus and the session
     /// cursor. Apply to the grid container alongside the tap recogniser.
     func puzzleGridAccessibility(
         session: PlayerSession,
         roster: PlayerRoster,
         revealConfirmation: RevealConfirmation,
         showsSharedAnnotations: Bool,
         isReplaying: Bool,
         gridSize: CGSize,
         spacing: CGFloat
     ) -> some View {
         modifier(PuzzleGridAccessibility(
             session: session,
             roster: roster,
             revealConfirmation: revealConfirmation,
             showsSharedAnnotations: showsSharedAnnotations,
             isReplaying: isReplaying,
             gridSize: gridSize,
             spacing: spacing
         ))
     }
 }
 
 private struct PuzzleGridAccessibility: ViewModifier {
     let session: PlayerSession
     let roster: PlayerRoster
     let revealConfirmation: RevealConfirmation
     let showsSharedAnnotations: Bool
     let isReplaying: Bool
     let gridSize: CGSize
     let spacing: CGFloat
 
     @Environment(\.accessibilityVoiceOverEnabled) private var voiceOverEnabled
     @AccessibilityFocusState private var focusedCell: GridPosition?
     /// Pairs the rotor entries with the cell elements they jump to.
     @Namespace private var rotorNamespace
     /// Peer fills buffered per author while a burst is in flight, flushed as
     /// one coalesced announcement after a quiet interval — a peer typing a
     /// word arrives as one edit per letter and must not announce per letter.
     @State private var pendingPeerFills: [String: Set<GridPosition>] = [:]
     @State private var peerFillFlushTask: Task<Void, Never>?
 
     /// Whether to build the synthetic hierarchy. Normally only while
     /// VoiceOver is running, but the Simulator can't run VoiceOver at all —
     /// Accessibility Inspector reads the tree without setting the flag — so
     /// debug builds can force it on with the `-ForceGridAccessibility`
     /// launch argument.
     private var isActive: Bool {
         if voiceOverEnabled { return true }
         #if DEBUG
         return ProcessInfo.processInfo.arguments.contains("-ForceGridAccessibility")
         #else
         return false
         #endif
     }
 
     func body(content: Content) -> some View {
         // The synthetic hierarchy is ~441 accessibility-only nodes, so it is
         // built only while VoiceOver is running — sighted users keep the
         // single-Canvas render path untouched. Replay is display-only: the
         // cells are suppressed and the scrubber narrates the playhead.
         if isActive, !isReplaying, gridSize != .zero {
             content
                 .accessibilityChildren { cellElements }
                 // Selection → focus: `enter(_:)` auto-advances the cursor, so
                 // following it makes VoiceOver read the newly focused cell —
                 // that is the typing echo; no explicit announcement needed.
                 .onChange(of: selection) { _, newValue in
                     focusedCell = newValue
                 }
                 // Focus → selection: a flick onto a cell is navigation, so the
                 // session cursor (and the clue bar, and peers' view of our
                 // cursor) follows. Guarded on inequality because `select` on
                 // the already-selected cell toggles direction — that toggle is
                 // reserved for an explicit double-tap (the activate action),
                 // matching what a sighted tap does.
                 .onChange(of: focusedCell) { _, newValue in
                     guard let newValue, newValue != selection else { return }
                     session.select(row: newValue.row, col: newValue.col)
                 }
                 // Word-change context: moving within a word stays quiet (the
                 // focused cell's own label carries the position); entering a
                 // new word or toggling direction announces the clue and its
                 // progress once.
                 .onChange(of: currentClueRef) { _, newValue in
                     guard newValue != nil else { return }
                     announceCurrentClue()
                 }
                 .accessibilityRotor("Across clues") { clueRotorEntries(for: .across) }
                 .accessibilityRotor("Down clues") { clueRotorEntries(for: .down) }
                 .accessibilityRotor("Incomplete clues") { incompleteClueRotorEntries }
                 // Peer fills: both the realtime overlay and CloudKit merges
                 // land on the open game through `GameStore.refreshCurrentGame`,
                 // so diffing the squares here catches every remote path with
                 // no sync plumbing. Local edits are filtered out by authorID.
                 .onChange(of: session.game.squares) { oldValue, newValue in
                     collectPeerFills(from: oldValue, to: newValue)
                 }
                 .onChange(of: session.completionEvent) { _, event in
                     guard let event else { return }
                     announce(describer.completionAnnouncement(for: event.state))
                 }
                 .onAppear { focusedCell = selection }
                 .onDisappear { peerFillFlushTask?.cancel() }
         } else {
             content
         }
     }
 
     private var selection: GridPosition {
         GridPosition(row: session.selectedRow, col: session.selectedCol)
     }
 
     /// Identity of the word the cursor is in: changes when the cursor crosses
     /// into a different word or the direction toggles, and drives the clue
     /// announcement. Nil when the focused cell has no word in the current
     /// direction.
     private var currentClueRef: Puzzle.ClueRef? {
         session.puzzle.clue(
             atRow: session.selectedRow,
             col: session.selectedCol,
             direction: session.direction
         ).map { Puzzle.ClueRef(number: $0.number, direction: session.direction) }
     }
 
     private var describer: CellAccessibilityDescriber {
         CellAccessibilityDescriber(puzzle: session.puzzle, authorNames: [:])
     }
 
     private func announceCurrentClue() {
         announce(describer.clueAnnouncement(
             atRow: session.selectedRow,
             atCol: session.selectedCol,
             direction: session.direction,
             squares: session.game.squares
         ))
     }
 
     /// Posts a spoken announcement. Low priority queues behind whatever
     /// VoiceOver is already saying (and may be dropped if the user keeps
     /// talking over it) — right for ambient peer activity, wrong for direct
     /// responses to the user's own action.
     private func announce(_ text: String?, lowPriority: Bool = false) {
         guard let text else { return }
         if lowPriority {
             var attributed = AttributedString(text)
             attributed.accessibilitySpeechAnnouncementPriority = .low
             AccessibilityNotification.Announcement(attributed).post()
         } else {
             AccessibilityNotification.Announcement(text).post()
         }
     }
 
     // MARK: - Check actions
 
     private func checkAndAnnounce(wholeWord: Bool) {
         let cells: [Puzzle.Cell]
         if wholeWord {
             session.checkCurrentWord()
             cells = session.puzzle.wordCells(
                 atRow: session.selectedRow,
                 col: session.selectedCol,
                 direction: session.direction
             )
         } else {
             session.checkSquare()
             cells = [session.puzzle.cells[session.selectedRow][session.selectedCol]]
         }
         announce(describer.checkAnnouncement(for: cells, squares: session.game.squares))
     }
 
     // MARK: - Peer fill announcements
 
     /// Collects squares whose entry a remote author just changed. Fills only:
     /// a cleared square carries no author, so a peer's clear is
     /// indistinguishable here from the local player's own delete and must
     /// stay silent rather than misfire on every local backspace.
     private func collectPeerFills(from old: [[Square]], to new: [[Square]]) {
         guard old.count == new.count else { return }
         let localAuthorID = roster.entries.first(where: { $0.isLocal })?.authorID
         var found = false
         for row in 0..<new.count {
             guard old[row].count == new[row].count else { continue }
             for col in 0..<new[row].count {
                 let after = new[row][col]
                 guard after.entry != old[row][col].entry,
                       !after.entry.isEmpty,
                       let author = after.letterAuthorID,
                       author != localAuthorID
                 else { continue }
                 pendingPeerFills[author, default: []].insert(GridPosition(row: row, col: col))
                 found = true
             }
         }
         guard found else { return }
         peerFillFlushTask?.cancel()
         peerFillFlushTask = Task {
             try? await Task.sleep(for: .seconds(2))
             guard !Task.isCancelled else { return }
             flushPeerFills()
         }
     }
 
     private func flushPeerFills() {
         let fills = pendingPeerFills
         pendingPeerFills = [:]
         guard !fills.isEmpty else { return }
         let names = Dictionary(
             roster.entries.map { ($0.authorID, $0.name) },
             uniquingKeysWith: { first, _ in first }
         )
         let squares = session.game.squares
         let texts = fills.keys.sorted().compactMap { author in
             describer.peerFillAnnouncement(
                 playerName: names[author] ?? "A collaborator",
                 positions: fills[author] ?? [],
                 squares: squares
             )
         }
         guard !texts.isEmpty else { return }
         announce(texts.joined(separator: ". "), lowPriority: true)
     }
 
     // MARK: - Rotors
 
     /// Rotor entries for one direction's clue list, each jumping VoiceOver to
     /// the word's first cell. The prepare closure aligns the session cursor
     /// first so the jump lands with direction and selection already correct
     /// (and the clue announcement fires from the resulting word change).
     @AccessibilityRotorContentBuilder
     private func clueRotorEntries(
         for direction: Puzzle.Direction
     ) -> some AccessibilityRotorContent {
         let puzzle = session.puzzle
         let describer = CellAccessibilityDescriber(puzzle: puzzle, authorNames: [:])
         let clues = direction == .across ? puzzle.acrossClues : puzzle.downClues
         ForEach(clues) { clue in
             if let cell = puzzle.cell(numbered: clue.number),
                let label = describer.clueLabel(number: clue.number, direction: direction) {
                 AccessibilityRotorEntry(
                     Text(label),
                     id: GridPosition(row: cell.row, col: cell.col),
                     in: rotorNamespace
                 ) {
                     session.selectClue(direction: direction, number: clue.number)
                 }
             }
         }
     }
 
     /// "What's left": every clue whose word still has an unfilled square,
     /// acrosses first then downs. Gap cells (`expectsBlank`) count as filled —
     /// their correct state is empty, so they must not pin a word in this
     /// rotor forever.
     @AccessibilityRotorContentBuilder
     private var incompleteClueRotorEntries: some AccessibilityRotorContent {
         let puzzle = session.puzzle
         let describer = CellAccessibilityDescriber(puzzle: puzzle, authorNames: [:])
         ForEach(incompleteClueRefs, id: \.self) { ref in
             if let cell = puzzle.cell(numbered: ref.number),
                let label = describer.clueLabel(number: ref.number, direction: ref.direction) {
                 AccessibilityRotorEntry(
                     Text(label),
                     id: GridPosition(row: cell.row, col: cell.col),
                     in: rotorNamespace
                 ) {
                     session.selectClue(direction: ref.direction, number: ref.number)
                 }
             }
         }
     }
 
     private var incompleteClueRefs: [Puzzle.ClueRef] {
         let puzzle = session.puzzle
         let squares = session.game.squares
         var refs: [Puzzle.ClueRef] = []
         for direction in [Puzzle.Direction.across, .down] {
             let clues = direction == .across ? puzzle.acrossClues : puzzle.downClues
             for clue in clues {
                 guard let start = puzzle.cell(numbered: clue.number) else { continue }
                 let cells = puzzle.wordCells(
                     atRow: start.row, col: start.col, direction: direction
                 )
                 let isIncomplete = cells.contains {
                     squares[$0.row][$0.col].entry.isEmpty && !$0.expectsBlank
                 }
                 if isIncomplete {
                     refs.append(Puzzle.ClueRef(number: clue.number, direction: direction))
                 }
             }
         }
         return refs
     }
 
     /// The hidden per-cell hierarchy handed to `accessibilityChildren`. Each
     /// open cell becomes a clear rect at the exact `PuzzleGridGeometry` frame
     /// of the drawn cell; blocks get no element and read as gaps. Emitted in
     /// row-major order, which is also VoiceOver's flick order.
     private var cellElements: some View {
         let puzzle = session.puzzle
         let geometry = PuzzleGridGeometry(
             size: gridSize,
             columns: puzzle.width,
             rows: puzzle.height,
             spacing: spacing
         )
         let describer = CellAccessibilityDescriber(
             puzzle: puzzle,
             authorNames: authorNames
         )
         let selection = self.selection
         return ZStack(alignment: .topLeading) {
             ForEach(openPositions, id: \.self) { pos in
                 let rect = geometry.cellRect(row: pos.row, col: pos.col)
                 Color.clear
                     .accessibilityElement()
                     .accessibilityLabel(describer.label(atRow: pos.row, atCol: pos.col))
                     .accessibilityValue(describer.value(for: session.game.squares[pos.row][pos.col]))
                     .accessibilityAddTraits(pos == selection ? .isSelected : [])
                     // Double-tap: same entry point as a sighted tap, including
                     // select's toggle-direction behaviour on the focused cell.
                     .accessibilityAction {
                         session.select(row: pos.row, col: pos.col)
                     }
                     .accessibilityFocused($focusedCell, equals: pos)
                     .accessibilityRotorEntry(id: pos, in: rotorNamespace)
                     // These act on the session's *selected* cell, which the
                     // focus sync keeps equal to the focused element. Check and
                     // reveal disappear on a solved grid or a read-only mutator
                     // — revoked access or an unsupported protocol (which would
                     // reject them anyway); Switch Direction stays for
                     // navigation. Reveal is non-undoable, so it routes through
                     // the same confirmation alert as the Hints menu and ⌘R
                     // instead of revealing immediately.
                     .accessibilityActions {
                         Button("Switch Direction") { session.toggleDirection() }
                         if session.mutator.isEditable, session.game.completionState != .solved {
                             Button("Check Square") { checkAndAnnounce(wholeWord: false) }
                             Button("Check Word") { checkAndAnnounce(wholeWord: true) }
                             Button("Reveal Square") { revealConfirmation.request(.square) }
                         }
                     }
                     .frame(width: rect.width, height: rect.height)
                     .position(x: rect.midX, y: rect.midY)
             }
         }
         .frame(width: gridSize.width, height: gridSize.height, alignment: .topLeading)
     }
 
     private var openPositions: [GridPosition] {
         let puzzle = session.puzzle
         var positions: [GridPosition] = []
         for row in 0..<puzzle.height {
             for col in 0..<puzzle.width where !puzzle.cells[row][col].isBlock {
                 positions.append(GridPosition(row: row, col: col))
             }
         }
         return positions
     }
 
     /// Spoken author attribution, mirroring the visual author tints: only in
     /// a shared game, with the local player spoken as "you".
     private var authorNames: [String: String] {
         guard showsSharedAnnotations else { return [:] }
         return Dictionary(
             roster.entries.map { ($0.authorID, $0.isLocal ? "you" : $0.name) },
             uniquingKeysWith: { first, _ in first }
         )
     }
 }