Added support for tabbing through links in AttributedLabel (#558)

This change supports both VoiceOver and Full Keyboard Access through a
new consolidated class that refactors the existing
`UIAccessibilityElement` code with accommodations for the focus system.

### Demo (tested on an iPad with a hardware keyboard)

Note that I activated the call link using the space bar.


https://github.com/user-attachments/assets/7ebb3511-1e83-4663-976b-225c34007f80

Additionally, it updates how bounding rectangles are calculated for
links so that a more relevant portion of the link is highlighted when it
overflows into multiple lines.

### Demo for the bounding rectangles fix

#### Before


https://github.com/user-attachments/assets/ffdaee0a-d2a2-4e69-b80a-a8016f843653

#### After


https://github.com/user-attachments/assets/b5b7ab41-56ff-4dd3-be47-6f3bf7ddb902

Author: meherkasam-square

BlueprintUICommonControls/Sources/AttributedLabel.swift

@@ -201,6 +201,7 @@ extension AttributedLabel {
         private var linkAttributes: [NSAttributedString.Key: Any] = [:]
         private var activeLinkAttributes: [NSAttributedString.Key: Any] = [:]
         private var links: [Link] = []
+        private var linkElements: [LinkElement] = []
 
         private var textRectOffset: UIOffset = .zero {
             didSet {
@@ -211,13 +212,14 @@ extension AttributedLabel {
         }
 
         override var accessibilityCustomRotors: [UIAccessibilityCustomRotor]? {
-            set { fatalError("accessibilityCustomRotors is not settable.") }
-            get {
-                guard let attributedText, !links.isEmpty else { return [] }
-                return [accessibilityRotor(for: links, in: attributedText)]
-            }
+            set { assertionFailure("accessibilityCustomRotors is not settable.") }
+            get { !linkElements.isEmpty ? [linkElements.accessibilityRotor(systemType: .link)] : [] }
         }
 
+        override var canBecomeFocused: Bool { false }
+
+        override func focusItems(in rect: CGRect) -> [any UIFocusItem] { linkElements }
+
         var urlHandler: URLHandler?
 
         func update(model: AttributedLabel, text: NSAttributedString, environment: Environment, isMeasuring: Bool) {
@@ -256,6 +258,9 @@ extension AttributedLabel {
                         in: model.attributedText.string,
                         linkAccessibilityLabel: environment.linkAccessibilityLabel
                     )
+                    linkElements = links
+                        .sorted(by: { $0.range.location < $1.range.location })
+                        .compactMap { .init(sourceLabel: attributedText, link: $0) }
                 }
 
                 if let shadow = model.shadow {
@@ -431,9 +436,9 @@ extension AttributedLabel {
                 options: []
             ) { link, range, _ in
                 if let link = link as? URL {
-                    links.append(.init(url: link, range: range))
+                    links.append(.init(url: link, range: range, container: self))
                 } else if let link = link as? String, let url = URL(string: link) {
-                    links.append(.init(url: url, range: range))
+                    links.append(.init(url: url, range: range, container: self))
                 }
             }
 
@@ -468,13 +473,13 @@ extension AttributedLabel {
                         let charactersToRemove = CharacterSet.decimalDigits.inverted
                         let trimmedPhoneNumber = phoneNumber.components(separatedBy: charactersToRemove).joined()
                         if let url = URL(string: "tel:\(trimmedPhoneNumber)") {
-                            links.append(.init(url: url, range: result.range))
+                            links.append(.init(url: url, range: result.range, container: self))
                         }
                     }
 
                 case .link:
                     if let url = result.url {
-                        links.append(.init(url: url, range: result.range))
+                        links.append(.init(url: url, range: result.range, container: self))
                     }
 
                 case .address:
@@ -495,15 +500,15 @@ extension AttributedLabel {
                         if let urlQuery = address.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed),
                            let url = URL(string: "https://maps.apple.com/?address=\(urlQuery)")
                         {
-                            links.append(.init(url: url, range: result.range))
+                            links.append(.init(url: url, range: result.range, container: self))
                         }
                     }
 
                 case .date:
                     if let date = result.date,
                        let url = URL(string: "calshow:\(date.timeIntervalSinceReferenceDate)")
                     {
-                        links.append(.init(url: url, range: result.range))
+                        links.append(.init(url: url, range: result.range, container: self))
                     }
 
                 default:
@@ -514,22 +519,6 @@ extension AttributedLabel {
             return links
         }
 
-        internal func accessibilityRotor(for links: [Link], in string: NSAttributedString) -> UIAccessibilityCustomRotor {
-            let elements: [LinkAccessibilityElement] = links
-                .sorted(by: { $0.range.location < $1.range.location })
-                .compactMap { link in
-                    guard NSIntersectionRange(string.entireRange, link.range).length > 0 else {
-                        return nil
-                    }
-                    return LinkAccessibilityElement(
-                        container: self,
-                        label: string.attributedSubstring(from: link.range).string,
-                        link: link
-                    )
-                }
-            return elements.accessibilityRotor(systemType: .link)
-        }
-
         internal func accessibilityLabel(with links: [Link], in string: String, linkAccessibilityLabel: String?) -> String {
             // When reading an attributed string that contains the `.link` attribute VoiceOver will announce "link" when it encounters the applied range. This is important because it informs the user about the context and position of the linked text within the greater string. This can be particularly important when a string contains multiple links with the same linked text but different link destinations.
 
@@ -663,41 +652,108 @@ extension AttributedLabel {
     struct Link: Equatable, Hashable {
         var url: URL
         var range: NSRange
+        weak var container: LabelView?
+
+        var boundingRect: CGRect {
+            guard let container = container,
+                  let textStorage = container.makeTextStorage(),
+                  let layoutManager = textStorage.layoutManagers.first,
+                  let textContainer = layoutManager.textContainers.first
+            else {
+                return .zero
+            }
+
+            let glyphRange = layoutManager.glyphRange(forCharacterRange: range, actualCharacterRange: nil)
+
+            // In cases where a link overflows from one line to the next,
+            // we will get back more than one rect. If we had used the boundingRect
+            // function instead, it will only return us a bounding rect that can
+            // fully encompass all the sub-rects - this is undesired behavior as
+            // it will suppress focusable items within the label that have an
+            // overlap with the larger bounding box.
+            // Since we only select the first rectangle, if there is indeed an overflow,
+            // only the portion of the link in the preceding line would be highlighted by
+            // VoiceOver or Full Keyboard Access. While this is not ideal behavior, it is still
+            // preferred over the former. The correct fix for this would be to return bezier paths
+            // that encompass exactly the linked portion.
+            let rects = { () -> [CGRect] in
+                var glyphRects: [CGRect] = []
+                layoutManager.enumerateEnclosingRects(
+                    forGlyphRange: glyphRange,
+                    withinSelectedGlyphRange: NSMakeRange(NSNotFound, 0),
+                    in: textContainer
+                ) { rect, _ in
+                    glyphRects.append(rect)
+                }
+                return glyphRects
+            }()
+
+            return rects.first ?? .zero
+        }
     }
 
-    private final class LinkAccessibilityElement: UIAccessibilityElement {
-        private let link: AttributedLabel.Link
-        private var container: LabelView? { accessibilityContainer as? LabelView }
+    class LinkElement: UIAccessibilityElement, UIFocusItem {
+
+        var preferredFocusEnvironments: [any UIFocusEnvironment] = []
+
+        var focusItemContainer: (any UIFocusItemContainer)?
+
+        func setNeedsFocusUpdate() {}
+
+        func updateFocusIfNeeded() {}
 
-        init(
-            container: LabelView,
-            label: String,
+        func didUpdateFocus(in context: UIFocusUpdateContext, with coordinator: UIFocusAnimationCoordinator) {}
+
+        private var sourceLabel: NSAttributedString
+        private var label: String {
+            sourceLabel.attributedSubstring(from: link.range).string
+        }
+
+        private var link: AttributedLabel.Link
+
+        init?(
+            sourceLabel: NSAttributedString?,
             link: AttributedLabel.Link
         ) {
+            guard let sourceLabel, NSIntersectionRange(sourceLabel.entireRange, link.range).length > 0 else { return nil }
+
+            self.sourceLabel = sourceLabel
             self.link = link
-            super.init(accessibilityContainer: container)
-            accessibilityLabel = label
-            accessibilityTraits = [.link]
+            super.init(accessibilityContainer: link.container)
         }
 
+        var frame: CGRect {
+            set { assertionFailure("cannot set frame") }
+            get { link.boundingRect }
+        }
+
+        weak var parentFocusEnvironment: (any UIFocusEnvironment)? {
+            link.container
+        }
+
+        func shouldUpdateFocus(in context: UIFocusUpdateContext) -> Bool {
+            true
+        }
+
+        var canBecomeFocused: Bool { true }
+
         override var accessibilityFrameInContainerSpace: CGRect {
-            set { fatalError("accessibilityFrameInContainerSpace") }
-            get {
-                guard let container = container,
-                      let textStorage = container.makeTextStorage(),
-                      let layoutManager = textStorage.layoutManagers.first,
-                      let textContainer = layoutManager.textContainers.first
-                else {
-                    return .zero
-                }
+            set { assertionFailure("cannot set accessibilityFrameInContainerSpace") }
+            get { link.boundingRect }
+        }
 
-                let glyphRange = layoutManager.glyphRange(forCharacterRange: link.range, actualCharacterRange: nil)
-                return layoutManager.boundingRect(forGlyphRange: glyphRange, in: textContainer)
-            }
+        override var accessibilityLabel: String? {
+            set { assertionFailure("cannot set accessibilityLabel") }
+            get { label }
+        }
+
+        override var accessibilityTraits: UIAccessibilityTraits {
+            set { assertionFailure("cannot set accessibilityTraits") }
+            get { [.link] }
         }
 
         override func accessibilityActivate() -> Bool {
-            container?.urlHandler?.onTap(url: link.url)
+            link.container?.urlHandler?.onTap(url: link.url)
             return true
         }
     }
@@ -844,3 +900,4 @@ extension String {
         components(separatedBy: .newlines).filter { !$0.isEmpty }.joined(separator: " ")
     }
 }
+

BlueprintUICommonControls/Tests/Sources/AttributedLabelTests.swift

@@ -484,27 +484,6 @@ class AttributedLabelTests: XCTestCase {
         }
     }
 
-
-    func test_linkAccessibility_Rotors() {
-        let labelView = AttributedLabel.LabelView()
-        let text: NSString = "The Fellowship of the ring was established at the Council of Elrond and consisted of Gandalf, Sam, Frodo, Aragorn, Gimli, Pippin, Boromir, Legolas, and Merry."
-
-        let url = URL(string: "https://one.ring")!
-
-        let links = ["Frodo", "Merry", "Sam", "Pippin"].map {
-            AttributedLabel.Link(url: url, range: text.range(of: $0))
-        }
-
-        let rotor = labelView.accessibilityRotor(for: links, in: NSAttributedString(string: text as String))
-        XCTAssertNotNil(rotor)
-
-        // links should be sorted by their position in the main string.
-        let sortedHobbits = rotor.dumpItems().map { $0.accessibilityLabel }
-        XCTAssertEqual(sortedHobbits, ["Sam", "Frodo", "Pippin", "Merry"])
-    }
-
-
-
     func test_linkAccessibility_Rotors_update() {
         let string = "The Fellowship of the ring was established at the Council of Elrond and consisted of Gandalf, Sam, Frodo, Aragorn, Gimli, Pippin, Boromir, Legolas, and Merry."
         var attributedText = AttributedText(string)
@@ -712,6 +691,63 @@ class AttributedLabelTests: XCTestCase {
         }
     }
 
+    func test_focusItems() {
+        let string = "The Fellowship of the ring was established at the Council of Elrond and consisted of Gandalf, Sam, Frodo, Aragorn, Gimli, Pippin, Boromir, Legolas, and Merry."
+        var attributedText = AttributedText(string)
+
+        for hobbit in ["Frodo", "Merry", "Sam", "Pippin"] {
+            let range = attributedText.range(of: hobbit)!
+            attributedText[range].link = URL(string: "https://one.ring")!
+        }
+
+        let label = AttributedLabel(attributedText: attributedText.attributedString)
+
+        let view = BlueprintView()
+        view.element = label
+        view.layoutIfNeeded()
+
+        guard let labelView = view.firstSubview(ofType: AttributedLabel.LabelView.self) else {
+            XCTFail("Could not find AttributedLabel.LabelView")
+            return
+        }
+
+        XCTAssertFalse(labelView.canBecomeFocused, "Label view should not be focusable")
+
+        let focusItems = labelView.focusItems(in: labelView.bounds)
+        XCTAssertEqual(focusItems.count, 4)
+
+        for item in focusItems {
+            XCTAssertTrue(item.canBecomeFocused, "Focus item should be focusable")
+            XCTAssertNotNil(item.parentFocusEnvironment, "Focus item should have a parent focus environment")
+        }
+
+        let linkElements: [AttributedLabel.LinkElement] = focusItems.compactMap { $0 as? AttributedLabel.LinkElement }
+        XCTAssertEqual(linkElements.count, focusItems.count, "All focus items should be LinkElement instances")
+
+        // Using accessibilityLabel here since label is private.
+        XCTAssertEqual(
+            linkElements.map { $0.accessibilityLabel! },
+            ["Sam", "Frodo", "Pippin", "Merry"],
+            "Focus items ordering should match the ordering of the links in the attributed string"
+        )
+    }
+
+    func test_focusItems_emptyWhenNoLinks() {
+        let string = NSAttributedString(string: "This is plain text with no links")
+        let label = AttributedLabel(attributedText: string)
+
+        let view = BlueprintView()
+        view.element = label
+        view.layoutIfNeeded()
+
+        guard let labelView = view.firstSubview(ofType: AttributedLabel.LabelView.self) else {
+            XCTFail("Could not find AttributedLabel.LabelView")
+            return
+        }
+
+        let focusItems = labelView.focusItems(in: labelView.bounds)
+        XCTAssertTrue(focusItems.isEmpty, "Focus items should be empty when no links are present")
+    }
 }
 
 extension UIAccessibilityCustomRotor {

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added support for tabbing through links in `AttributedLabel`
+
 ### Removed
 
 ### Changed