[Woo POS] Improve VoiceOver accessibility for barcode scanning errors (#15793)

Author: staskus

WooCommerce/Classes/POS/Models/Cart+BarcodeScanError.swift

@@ -11,7 +11,8 @@ extension Cart {
             title: title(for: error),
             subtitle: subtitle(for: error),
             quantity: 1,
-            state: .error
+            state: .error,
+            accessibilityLabel: accessibilityLabel(for: error)
         )
 
         return purchasableItems[index]
@@ -35,6 +36,12 @@ extension Cart {
     private func subtitle(for error: PointOfSaleBarcodeScanError) -> String {
         return error.localizedDescription
     }
+
+    private func accessibilityLabel(for error: PointOfSaleBarcodeScanError) -> String {
+        let errorDescription = error.localizedDescription
+        let scannedValue = title(for: error)
+        return "\(errorDescription). \(scannedValue)"
+    }
 }
 
 extension PointOfSaleBarcodeScanError {

WooCommerce/Classes/POS/Models/Cart.swift

@@ -6,6 +6,8 @@ import enum Yosemite.PointOfSaleBarcodeScanError
 struct Cart {
     var purchasableItems: [Cart.PurchasableItem] = []
     var coupons: [Cart.CouponItem] = []
+
+    var accessibilityFocusedItemID: UUID? = nil
 }
 
 protocol CartItem {
@@ -26,6 +28,7 @@ extension Cart {
         let quantity: Int
         let type: CartItemType = .purchasableItem
         let state: ItemState
+        let accessibilityLabel: String?
 
         enum ItemState {
             case loaded(POSOrderableItem)
@@ -42,12 +45,13 @@ extension Cart {
             }
         }
 
-        init(id: UUID, title: String, subtitle: String?, quantity: Int, state: ItemState) {
+        init(id: UUID, title: String, subtitle: String?, quantity: Int, state: ItemState, accessibilityLabel: String? = nil) {
             self.id = id
             self.title = title
             self.subtitle = subtitle
             self.quantity = quantity
             self.state = state
+            self.accessibilityLabel = accessibilityLabel
         }
 
         init(id: UUID, item: POSOrderableItem, title: String, subtitle: String?, quantity: Int) {
@@ -56,6 +60,7 @@ extension Cart {
             self.subtitle = subtitle
             self.quantity = quantity
             self.state = .loaded(item)
+            self.accessibilityLabel = nil
         }
 
         static func loading(id: UUID) -> PurchasableItem {

WooCommerce/Classes/POS/Models/PointOfSaleAggregateModel.swift

@@ -207,12 +207,16 @@ extension PointOfSaleAggregateModel {
                             productType: .init(cartItem: cartItem)
                         )
                     )
+
+                    cart.accessibilityFocusedItemID = cartItem.id
                 }
             } catch {
                 DDLogInfo("Failed to find item by barcode: \(error)")
-                if let _ = cart.updateLoadingItem(id: placeholderItemID, with: error) {
+                if let errorItem = cart.updateLoadingItem(id: placeholderItemID, with: error) {
                     // Only play a sound and track analytics if the item still exists in the cart.
-                    await soundPlayer.playSound(.barcodeScanFailure)
+                    await soundPlayer.playSound(.barcodeScanFailure, completion: { [weak self] in
+                        self?.cart.accessibilityFocusedItemID = errorItem.id
+                    })
 
                     analytics.track(
                         event: .PointOfSale.addItemToCart(

WooCommerce/Classes/POS/Presentation/CartView.swift

@@ -24,6 +24,7 @@ struct CartView: View {
     }
 
     @State private var shouldShowItemImages: Bool = false
+    @AccessibilityFocusState private var accessibilityFocusedItem: UUID?
 
     private var shouldShowCoupons: Bool {
         posModel.cart.coupons.isNotEmpty
@@ -90,9 +91,17 @@ struct CartView: View {
                                     })
                                     .id(cartItem.id)
                                     .transition(.opacity)
+                                    .accessibilityFocused($accessibilityFocusedItem, equals: cartItem.id)
                                 }
                             }
                             .padding(.bottom, Constants.cartLastItemBottomPadding)
+                            .onChange(of: posModel.cart.accessibilityFocusedItemID) { itemID in
+                                if let itemID = itemID {
+                                    Task { @MainActor in
+                                        accessibilityFocusedItem = itemID
+                                    }
+                                }
+                            }
                             .animation(Constants.cartAnimation, value: posModel.cart.purchasableItems.map(\.id))
                             .animation(Constants.cartAnimation, value: posModel.cart.coupons.map(\.id))
                             .background(GeometryReader { geometry in

WooCommerce/Classes/POS/Presentation/ItemRowView.swift

@@ -77,6 +77,10 @@ struct ItemRowView: View {
             .padding(.leading, showProductImage ? 0 : Constants.cardContentHorizontalPadding * (1 / scale))
             .padding(.vertical, Constants.verticalPadding * (1 / scale))
             .accessibilityElement(children: .combine)
+            .if(cartItem.accessibilityLabel != nil) { view in
+                view
+                    .accessibilityLabel(cartItem.accessibilityLabel ?? "")
+            }
 
             if let onItemRemoveTapped {
                 CartRowRemoveButton {

WooCommerce/Classes/POS/Presentation/PointOfSaleBarcodeScannerInformationModal.swift

@@ -16,9 +16,13 @@ struct PointOfSaleBarcodeScannerInformationModal: View {
 
             PointOfSaleInformationModalParagraphView {
                 Text(bulletPointWithLink)
+                    .accessibilityLabel(bulletPointWithLinkAccessibilityLabel)
                 Text(AttributedString(Localization.barcodeInfoSecondaryMessage))
+                    .accessibilityLabel(Localization.barcodeInfoSecondaryMessageAccessible)
                 Text(AttributedString(Localization.barcodeInfoTertiaryMessage))
+                    .accessibilityLabel(Localization.barcodeInfoTertiaryMessageAccessible)
                 Text(AttributedString(Localization.barcodeInfoQuaternaryMessage))
+                    .accessibilityLabel(Localization.barcodeInfoQuaternaryMessageAccessible)
             }
             .padding(.leading, POSSpacing.medium)
 
@@ -37,6 +41,10 @@ struct PointOfSaleBarcodeScannerInformationModal: View {
         secondary.append(moreDetails)
         return secondary
     }
+
+    private var bulletPointWithLinkAccessibilityLabel: String {
+        return Localization.barcodeInfoPrimaryMessageAccessible + " " + Localization.barcodeInfoMoreDetailsLinkAccessible
+    }
 }
 
 private extension PointOfSaleBarcodeScannerInformationModal {
@@ -65,6 +73,11 @@ private extension PointOfSaleBarcodeScannerInformationModal {
             value: "More details.",
             comment: "Link text in the barcode info modal in POS, leading to more details about barcode setup"
         )
+        static let barcodeInfoMoreDetailsLinkAccessible = NSLocalizedString(
+            "pos.barcodeInfoModal.moreDetailsLink.accessible",
+            value: "More details, link.",
+            comment: "Accessible version of more details link in barcode info modal, announcing it as a link for screen readers"
+        )
         static let barcodeInfoSecondaryMessage = NSLocalizedString(
             "pos.barcodeInfoModal.secondaryMessage",
             value: "• Refer to your Bluetooth barcode scanner's instructions to set HID mode.",
@@ -86,6 +99,28 @@ private extension PointOfSaleBarcodeScannerInformationModal {
                 "Tap on the keyboard icon to show it again.",
             comment: "Quinary message in the barcode info modal in POS, explaining scanner keyboard emulation and how to show software keyboard again"
         )
+
+        // Accessibility-friendly versions without bullet points
+        static let barcodeInfoPrimaryMessageAccessible = NSLocalizedString(
+            "pos.barcodeInfoModal.primaryMessage.accessible",
+            value: "First: Set up barcodes in the \"G-T-I-N, U-P-C, E-A-N, I-S-B-N\" field by navigating to Products, then Product Details, then Inventory.",
+            comment: "Accessible version of primary bullet point in barcode info modal, without bullet character for screen readers"
+        )
+        static let barcodeInfoSecondaryMessageAccessible = NSLocalizedString(
+            "pos.barcodeInfoModal.secondaryMessage.accessible",
+            value: "Second: Refer to your Bluetooth barcode scanner's instructions to set H-I-D mode.",
+            comment: "Accessible version of secondary bullet point in barcode info modal, without bullet character for screen readers"
+        )
+        static let barcodeInfoTertiaryMessageAccessible = NSLocalizedString(
+            "pos.barcodeInfoModal.tertiaryMessage.accessible",
+            value: "Third: Connect your barcode scanner in iOS Bluetooth settings.",
+            comment: "Accessible version of tertiary bullet point in barcode info modal, without bullet character for screen readers"
+        )
+        static let barcodeInfoQuaternaryMessageAccessible = NSLocalizedString(
+            "pos.barcodeInfoModal.quaternaryMessage.accessible",
+            value: "Fourth: Scan barcodes while on the item list to add products to the cart.",
+            comment: "Accessible version of quaternary bullet point in barcode info modal, without bullet character for screen readers"
+        )
     }
 }
 

WooCommerce/Classes/POS/Utils/Audio/PointOfSaleSoundPlayer.swift

@@ -11,33 +11,64 @@ struct PointOfSaleSound: Equatable, Hashable {
 }
 
 protocol PointOfSaleSoundPlayerProtocol {
+    func playSound(_ sound: PointOfSaleSound, completion: @escaping (() -> Void)) async
     func playSound(_ sound: PointOfSaleSound) async
 }
 
-actor PointOfSaleSoundPlayer: PointOfSaleSoundPlayerProtocol {
+actor PointOfSaleSoundPlayer: NSObject, PointOfSaleSoundPlayerProtocol {
     private var playerCache: [PointOfSaleSound: AVAudioPlayer] = [:]
+    private var completionHandlers: [AVAudioPlayer: () -> Void] = [:]
 
     func playSound(_ sound: PointOfSaleSound) async {
+        await playSound(sound, completion: {})
+    }
+
+    func playSound(_ sound: PointOfSaleSound, completion: @escaping (() -> Void)) async {
         guard let url = Bundle.main.url(forResource: sound.name, withExtension: sound.type) else {
             DDLogError("Sound file not found: \(sound.name).\(sound.type)")
+            completion()
             return
         }
 
         if let cachedPlayer = playerCache[sound] {
              if !cachedPlayer.isPlaying {
-                 cachedPlayer.currentTime = 0
-                 cachedPlayer.play()
+                 play(cachedPlayer, completion: completion)
+             } else {
+                 completion()
              }
              return
          }
 
         do {
             let audioPlayer = try AVAudioPlayer(contentsOf: url)
             audioPlayer.prepareToPlay()
-            audioPlayer.play()
+            play(audioPlayer, completion: completion)
             playerCache[sound] = audioPlayer
         } catch {
             DDLogError("Failed to play sound: \(error)")
+            completion()
+        }
+    }
+
+    private func play(_ player: AVAudioPlayer, completion: @escaping (() -> Void)) {
+        completionHandlers[player] = completion
+        player.delegate = self
+        player.currentTime = 0
+        player.play()
+    }
+}
+
+extension PointOfSaleSoundPlayer: AVAudioPlayerDelegate {
+    nonisolated func audioPlayerDidFinishPlaying(_ player: AVAudioPlayer, successfully flag: Bool) {
+        Task { @MainActor in
+            await handlePlayerFinished(player)
+        }
+    }
+
+    private func handlePlayerFinished(_ player: AVAudioPlayer) {
+        if let completion = completionHandlers[player] {
+            completionHandlers.removeValue(forKey: player)
+            completion()
         }
     }
 }

WooCommerce/WooCommerceTests/POS/Mocks/MockPointOfSaleSoundPlayer.swift

@@ -7,4 +7,8 @@ final class MockPointOfSaleSoundPlayer: PointOfSaleSoundPlayerProtocol {
     func playSound(_ sound: PointOfSaleSound) {
         onPlaySound?(sound)
     }
+
+    func playSound(_ sound: WooCommerce.PointOfSaleSound, completion: @escaping () -> Void) async {
+        onPlaySound?(sound)
+    }
 }