Handle part of missing VoiceOver accessibility in Shipping Labels flow (#15912)

RafaelKayumov · web-flow · commit d78ef582a940 · 2025-07-18T13:27:25.000+03:00
diff --git a/RELEASE-NOTES.txt b/RELEASE-NOTES.txt
@@ -3,6 +3,8 @@
 
 22.9
 -----
+- [*] Shipping Labels: Empty dimensions are no longer presented for product cards [https://github.com/woocommerce/woocommerce-ios/pull/15912]
+- [*] Shipping Labels: Improved VoiceOver accessibility [https://github.com/woocommerce/woocommerce-ios/pull/15912]
 - [**] Order Details: Update Shipping Labels section for stores with Woo Shipping extension [https://github.com/woocommerce/woocommerce-ios/pull/15889]
 - [*] Order List: New orders made through Point of Sale are now filterable via the Order List filters menu [https://github.com/woocommerce/woocommerce-ios/pull/15910]
 - [*] Shipping Labels: Display base rate on selected shipping service cards [https://github.com/woocommerce/woocommerce-ios/pull/15916]
diff --git a/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/ShipmentDetails/WooShippingShipmentDetailsView.swift b/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/ShipmentDetails/WooShippingShipmentDetailsView.swift
@@ -18,7 +18,8 @@ struct WooShippingShipmentDetailsView: View {
 
             WooShippingItems(itemsCountLabel: viewModel.itemsCountLabel,
                              itemsDetailLabel: viewModel.itemsDetailLabel,
-                             items: viewModel.itemsRowViewModels)
+                             items: viewModel.itemsRowViewModels,
+                             itemsSummaryAccessibilityValue: viewModel.itemsSummaryAccessibilityValue)
 
             WooShippingHazmatRow(selectedCategory: $viewModel.hazmatCategory,
                                  enabled: !viewModel.canViewLabel)
diff --git a/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/ShipmentDetails/WooShippingShipmentDetailsViewModel.swift b/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/ShipmentDetails/WooShippingShipmentDetailsViewModel.swift
@@ -263,6 +263,18 @@ final class WooShippingShipmentDetailsViewModel: ObservableObject {
     }
 }
 
+/// Accessor for manual collapsed product items section accessibility label
+extension WooShippingShipmentDetailsViewModel {
+    var itemsSummaryAccessibilityValue: String {
+        return String.localizedStringWithFormat(
+            Localization.itemsSummaryAccessibilityFormat,
+            shipment.quantity,
+            shipment.weight,
+            shipment.price
+        )
+    }
+}
+
 private extension WooShippingShipmentDetailsViewModel {
     func observeAddresses(originAddressPublisher: AnyPublisher<WooShippingAddress?, Never>,
                           destinationAddressPublisher: AnyPublisher<WooShippingAddress?, Never>) {
@@ -562,5 +574,13 @@ private extension WooShippingShipmentDetailsViewModel {
             comment: "Label for row showing the additional cost to require Saturday delivery " +
             "on the shipping label creation screen"
         )
+        static let itemsSummaryAccessibilityFormat = NSLocalizedString(
+            "shipping-labels.packages.items.summary.accessibility-label",
+            value: "%1$@ with a total weight of %2$@ and a total price of %3$@",
+            comment: "Accessibility label for the summary of product items in a shipment." +
+                " The %1$@ is items count." +
+                " The %2$@ is total weight." +
+                " The %3$@ is total price."
+        )
     }
 }
diff --git a/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShipping Items Section/ShippingItemRowAccessibility.swift b/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShipping Items Section/ShippingItemRowAccessibility.swift
@@ -0,0 +1,50 @@
+import Foundation
+
+/// Reusable accessibility builder for `WooShippingItemRow` and `SelectableShipmentItemRo`
+enum ShippingItemRowAccessibility {
+    static func accessibilityValue(
+        itemName: String,
+        quantity: String,
+        details: String,
+        weight: String,
+        price: String
+    ) -> String {
+        /// Covers item name and quantity if plural
+        let quantifiedItemFormattedString: String
+        if let quantityIntValue = Int(quantity), quantityIntValue > 1 {
+            quantifiedItemFormattedString = String(
+                format: Localization.accessibilityValueQuantityFormat,
+                quantityIntValue,
+                itemName
+            )
+        } else {
+            quantifiedItemFormattedString = itemName
+        }
+
+        return quantifiedItemFormattedString + ". " + String(
+            format: Localization.accessibilityValueFormat,
+            details,
+            weight,
+            price
+        )
+    }
+
+    enum Localization {
+        static let accessibilityValueFormat = NSLocalizedString(
+            "shipping_item_row.accessibility_value.format",
+            value: "%1$@, Weight: %2$@, Total price: %3$@",
+            comment: "Accessibility value for a shipping item row." +
+                " The %1$@ is details text." +
+                " The %2$@ is weight." +
+                " The %3$@ is a total price"
+        )
+
+        static let accessibilityValueQuantityFormat = NSLocalizedString(
+            "shipping_item_row.quantity.format",
+            value: "%1$d items of %2$@",
+            comment: "Format for plural item quantity." +
+                " The %1$@ is a plural quantity." +
+                " The %2$@ is the item name."
+        )
+    }
+}
diff --git a/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShipping Items Section/WooShippingItemRow.swift b/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShipping Items Section/WooShippingItemRow.swift
@@ -51,6 +51,21 @@ struct WooShippingItemRow: View {
             }
         }
         .frame(maxWidth: .infinity)
+        .accessibilityElement(children: .ignore)
+        .accessibilityValue(accessibilityValue)
+    }
+}
+
+/// Custom accessibility
+private extension WooShippingItemRow {
+    var accessibilityValue: String {
+        return ShippingItemRowAccessibility.accessibilityValue(
+            itemName: name,
+            quantity: quantityLabel,
+            details: detailsLabel,
+            weight: weightLabel,
+            price: priceLabel
+        )
     }
 }
 
diff --git a/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShipping Items Section/WooShippingItemRowViewModel.swift b/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShipping Items Section/WooShippingItemRowViewModel.swift
@@ -71,8 +71,23 @@ private extension ShippingLabelPackageItem {
 
     /// Formats the item dimensions with the provided dimension unit.
     ///
-    func formatDimensions(with unit: String) -> String {
-        String(format: Localization.dimensionsFormat, dimensions.length, dimensions.width, dimensions.height, unit)
+    func formatDimensions(with unit: String) -> String? {
+        var validDimensions = [String]()
+        if dimensions.length.isNotEmpty {
+            validDimensions.append(dimensions.length)
+        }
+        if dimensions.width.isNotEmpty {
+            validDimensions.append(dimensions.width)
+        }
+        if dimensions.height.isNotEmpty {
+            validDimensions.append(dimensions.height)
+        }
+
+        if validDimensions.isEmpty {
+            return nil
+        }
+
+        return validDimensions.joined(separator: Constants.dimensionsFormatSeparator) + " " + unit
     }
 
     /// Formats the total item weight (per-unit weight x quantity) with the provided weight unit.
@@ -91,11 +106,8 @@ private extension ShippingLabelPackageItem {
         return currencyFormatter.formatAmount(totalPrice, with: currency) ?? totalPrice.description
     }
 
-    enum Localization {
-        static let dimensionsFormat = NSLocalizedString("wooShipping.createLabels.items.dimensions",
-                                                        value: "%1$@ x %2$@ x %3$@ %4$@",
-                                                        comment: "Length, width, and height dimensions with the unit for an item to ship. "
-                                                        + "Reads like: '20 x 35 x 5 cm'")
+    enum Constants {
+        static let dimensionsFormatSeparator = " × "
     }
 }
 
diff --git a/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShipping Items Section/WooShippingItems.swift b/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShipping Items Section/WooShippingItems.swift
@@ -11,6 +11,9 @@ struct WooShippingItems: View {
     /// View models for items to ship
     let items: [WooShippingItemRowViewModel]
 
+    /// Summary header accessibility label
+    let itemsSummaryAccessibilityValue: String
+
     /// Whether the item list is collapsed
     @State private var isCollapsed: Bool = true
 
@@ -27,6 +30,10 @@ struct WooShippingItems: View {
                     .foregroundStyle(Color(.textSubtle))
             }
             .padding(.vertical, Layout.textContainerAdditionalVerticalPadding)
+            .accessibilityElement(children: .ignore)
+            .accessibilityLabel(Localization.collapsibleHeaderAccessibilityLabel)
+            .accessibilityValue(itemsSummaryAccessibilityValue)
+            .accessibilityHint(isCollapsed ? Localization.expandHint : Localization.collapseHint)
         },
                         content: {
             VStack {
@@ -41,7 +48,11 @@ struct WooShippingItems: View {
         .frame(maxWidth: .infinity, alignment: .center)
         .if(isCollapsed) { view in
             view
-                .roundedBorder(cornerRadius: Layout.borderCornerRadius, lineColor: Color(.separator), lineWidth: Layout.borderWidth)
+                .roundedBorder(
+                    cornerRadius: Layout.borderCornerRadius,
+                    lineColor: Color(.separator),
+                    lineWidth: Layout.borderWidth)
+                .accessibilityElement(children: .combine)
         }
     }
 }
@@ -56,6 +67,24 @@ private extension WooShippingItems {
 
         static let textContainerAdditionalVerticalPadding: CGFloat = 2
     }
+
+    private enum Localization {
+        static let expandHint = NSLocalizedString(
+            "shipping-labels.packages.items.expand.accessibility-hint",
+            value: "Double-tap to show all items",
+            comment: "Accessibility hint to expand the product items section"
+        )
+        static let collapseHint = NSLocalizedString(
+            "shipping-labels.packages.items.collapse.accessibility-hint",
+            value: "Double-tap to hide all items",
+            comment: "Accessibility hint to collapse the product items section"
+        )
+        static let collapsibleHeaderAccessibilityLabel = NSLocalizedString(
+            "shipping-labels.packages.items.header.accessibilityLabel",
+            value: "Products section",
+            comment: "Accessibility label for collapsible products section"
+        )
+    }
 }
 
 #Preview {
@@ -72,5 +101,8 @@ private extension WooShippingItems {
                                                          name: "Little Nap Brazil 250g",
                                                          detailsLabel: "15×10×8cm • Espresso",
                                                          weightLabel: "275g",
-                                                         priceLabel: "$60.00")])
+                                                         priceLabel: "$60.00")],
+                     itemsSummaryAccessibilityValue: "6 items with a total weight of 825g" +
+                     " and a total price of $135.00"
+    )
 }
diff --git a/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShipping Items Section/WooShippingItemsViewModel.swift b/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShipping Items Section/WooShippingItemsViewModel.swift
@@ -99,12 +99,3 @@ private extension WooShippingItemsViewModel {
                                                         + "Reads like: '20 x 35 x 5 cm'")
     }
 }
-
-/// Convenience extension to provide data to `WooShippingItemRow`
-extension WooShippingItems {
-    init(viewModel: WooShippingItemsViewModel) {
-        self.itemsCountLabel = viewModel.itemsCountLabel
-        self.itemsDetailLabel = viewModel.itemsDetailLabel
-        self.items = viewModel.itemRows
-    }
-}
diff --git a/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShipping Split Shipments/SelectableShipmentItemRow.swift b/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShipping Split Shipments/SelectableShipmentItemRow.swift
@@ -22,40 +22,55 @@ struct SelectableShipmentItemRow: View {
                     }
             }
 
-            ProductImageThumbnail(productImageURL: viewModel.item.imageUrl,
-                                  productImageSize: Layout.imageSize,
-                                  scale: scale,
-                                  productImageCornerRadius: Layout.imageCornerRadius,
-                                  foregroundColor: Color(UIColor.listSmallIcon))
-            .overlay(alignment: .topTrailing) {
-                if viewModel.showQuantity {
-                    BadgeView(text: viewModel.item.quantityLabel,
-                              customizations: .init(textColor: .white, backgroundColor: .black),
-                              backgroundShape: badgeStyle)
-                    .offset(x: Layout.badgeOffset, y: -Layout.badgeOffset)
+            AdaptiveStack(spacing: Layout.horizontalSpacing) {
+                ProductImageThumbnail(productImageURL: viewModel.item.imageUrl,
+                                      productImageSize: Layout.imageSize,
+                                      scale: scale,
+                                      productImageCornerRadius: Layout.imageCornerRadius,
+                                      foregroundColor: Color(UIColor.listSmallIcon))
+                .overlay(alignment: .topTrailing) {
+                    if viewModel.showQuantity {
+                        BadgeView(text: viewModel.item.quantityLabel,
+                                  customizations: .init(textColor: .white, backgroundColor: .black),
+                                  backgroundShape: badgeStyle)
+                        .offset(x: Layout.badgeOffset, y: -Layout.badgeOffset)
+                    }
                 }
-            }
-            VStack(alignment: .leading) {
-                Text(viewModel.item.name)
-                    .bodyStyle()
-                Text(viewModel.item.detailsLabel)
-                    .subheadlineStyle()
-                AdaptiveStack(verticalAlignment: .lastTextBaseline) {
-                    Text(viewModel.item.weightLabel)
+
+                VStack(alignment: .leading) {
+                    Text(viewModel.item.name)
+                        .bodyStyle()
+                    Text(viewModel.item.detailsLabel)
                         .subheadlineStyle()
-                    Spacer()
-                    Text(viewModel.item.priceLabel)
-                        .font(.subheadline)
-                        .foregroundStyle(Color(.text))
+                    AdaptiveStack(verticalAlignment: .lastTextBaseline) {
+                        Text(viewModel.item.weightLabel)
+                            .subheadlineStyle()
+                        Spacer()
+                        Text(viewModel.item.priceLabel)
+                            .font(.subheadline)
+                            .foregroundStyle(Color(.text))
+                    }
                 }
             }
+            .accessibilityElement(children: .ignore)
+            .accessibilityValue(accessibilityValue)
         }
         .frame(maxWidth: .infinity)
         .opacity(isEnabled ? 1 : Layout.disabledOpacity)
     }
 }
 
 private extension SelectableShipmentItemRow {
+    var accessibilityValue: String {
+        return ShippingItemRowAccessibility.accessibilityValue(
+            itemName: viewModel.item.name,
+            quantity: viewModel.item.quantityLabel,
+            details: viewModel.item.detailsLabel,
+            weight: viewModel.item.weightLabel,
+            price: viewModel.item.priceLabel
+        )
+    }
+
     @ViewBuilder
     func selectionCircle(selected: Bool) -> some View {
         if selected {
diff --git a/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShippingCreateLabelsView.swift b/WooCommerce/Classes/ViewRelated/Orders/Order Details/Shipping Labels/WooShipping Create Shipping Labels/WooShippingCreateLabelsView.swift
@@ -143,6 +143,9 @@ private extension WooShippingCreateLabelsView {
         viewModel.shipments.enumerated().map { (index, shipment) in
             TopTabItem(name: String.localizedStringWithFormat(Localization.shipmentFormat, index + 1),
                        icon: shipment.isPurchased ? Layout.purchasedIcon : nil,
+                       customAccessibilityValue: shipment.isPurchased ?
+                           Localization.Accessibility.shipmentTabFulfilled :
+                           Localization.Accessibility.shipmentTabUnfulfilled,
                        content: {
                 EmptyView()
             })
@@ -178,6 +181,7 @@ private extension WooShippingCreateLabelsView {
                 Image(systemName: "pencil")
                     .padding(.horizontal)
             }
+            .accessibilityHint(Localization.Accessibility.editButtonHint)
             .renderedIf(viewModel.hasUnfulfilledShipments)
         }
         .disabled(viewModel.isPurchasingLabel)
@@ -692,6 +696,21 @@ private extension WooShippingCreateLabelsView {
                                              value: "Close",
                                              comment: "Title of the button to dismiss the shipping label screen")
 
+        enum Accessibility {
+            static let editButtonHint = NSLocalizedString(
+                "wooShipping.createLabel.editButton.accessibility.hint",
+                value: "Opens the shipments editing form.",
+                comment: "Accessibility hint of the button to open the shipments editing form.")
+            static let shipmentTabFulfilled = NSLocalizedString(
+                "wooShipping.createLabel.shipmentTab.accessibility.value.fulfilled",
+                value: "Fulfilled.",
+                comment: "Accessibility value indicating that the shipment of a tab is fulfilled.")
+            static let shipmentTabUnfulfilled = NSLocalizedString(
+                "wooShipping.createLabel.shipmentTab.accessibility.value.unfulfilled",
+                value: "Unfulfilled.",
+                comment: "Accessibility value indicating that the shipment of a tab is unfulfilled.")
+        }
+
         enum BottomSheet {
             static let shipmentDetails = NSLocalizedString("wooShipping.createLabels.bottomSheet.title",
                                                            value: "Shipment details",
diff --git a/WooCommerce/Classes/ViewRelated/ReusableViews/SwiftUI Components/TopTabView.swift b/WooCommerce/Classes/ViewRelated/ReusableViews/SwiftUI Components/TopTabView.swift
diff --git a/WooCommerce/WooCommerce.xcodeproj/project.pbxproj b/WooCommerce/WooCommerce.xcodeproj/project.pbxproj
diff --git a/WooCommerce/WooCommerceTests/ViewRelated/Shipping Label/WooShipping Create Shipping Labels/WooShippingItemRowViewModelTests.swift b/WooCommerce/WooCommerceTests/ViewRelated/Shipping Label/WooShipping Create Shipping Labels/WooShippingItemRowViewModelTests.swift

Original file line number	Diff line number	Diff line change
`@@ -51,6 +51,21 @@ struct WooShippingItemRow: View {`
`51`	`51`	`}`
`52`	`52`	`}`
`53`	`53`	`.frame(maxWidth: .infinity)`
	`54`	`+ .accessibilityElement(children: .ignore)`
	`55`	`+ .accessibilityValue(accessibilityValue)`
	`56`	`+ }`
	`57`	`+}`
	`58`	`+`
	`59`	`+/// Custom accessibility`
	`60`	`+private extension WooShippingItemRow {`
	`61`	`+ var accessibilityValue: String {`
	`62`	`+ return ShippingItemRowAccessibility.accessibilityValue(`
	`63`	`+ itemName: name,`
	`64`	`+ quantity: quantityLabel,`
	`65`	`+ details: detailsLabel,`
	`66`	`+ weight: weightLabel,`
	`67`	`+ price: priceLabel`
	`68`	`+ )`
`54`	`69`	`}`
`55`	`70`	`}`
`56`	`71`
Original file line number	Diff line number	Diff line change
`@@ -99,12 +99,3 @@ private extension WooShippingItemsViewModel {`
`99`	`99`	`+ "Reads like: '20 x 35 x 5 cm'")`
`100`	`100`	`}`
`101`	`101`	`}`
`102`		`-`
`103`		-/// Convenience extension to provide data to `WooShippingItemRow`
`104`		`-extension WooShippingItems {`
`105`		`- init(viewModel: WooShippingItemsViewModel) {`
`106`		`- self.itemsCountLabel = viewModel.itemsCountLabel`
`107`		`- self.itemsDetailLabel = viewModel.itemsDetailLabel`
`108`		`- self.items = viewModel.itemRows`
`109`		`- }`
`110`		`-}`