[Accessibility] Add .isAccessibilityContainer property, allowing automatic aggregation of children's a11y labels.

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## master
 
 * Add your own contributions to the next release on the line below this with your name.
+- [Accessibility] Add .isAccessibilityContainer property, allowing automatic aggregation of children's a11y labels. [Scott Goodson](https://github.com/appleguy)
 - [ASCollectionView] Add delegate bridging and index space translation for missing UICollectionViewLayout properties. [Scott Goodson](https://github.com/appleguy)
 - [ASTextNode2] Add initial implementation for link handling. [Scott Goodson](https://github.com/appleguy) [#396](https://github.com/TextureGroup/Texture/pull/396)
 - [ASTextNode2] Provide compile flag to globally enable new implementation of ASTextNode: ASTEXTNODE_EXPERIMENT_GLOBAL_ENABLE. [Scott Goodson](https://github.com/appleguy) [#396](https://github.com/TextureGroup/Texture/pull/410)

Source/ASDisplayNode+Beta.h

@@ -112,6 +112,19 @@ typedef struct {
 @property (nonatomic, strong, readonly) ASEventLog *eventLog;
 #endif
 
+/**
+ * @abstract Whether this node acts as an accessibility container. If set to YES, then this node's accessibility label will represent
+ * an aggregation of all child nodes' accessibility labels. Nodes in this node's subtree that are also accessibility containers will
+ * not be included in this aggregation, and will be exposed as separate accessibility elements to UIKit.
+ */
+@property (nonatomic, assign) BOOL isAccessibilityContainer;
+
+/**
+ * @abstract Invoked when a user performs a custom action on an accessible node. Nodes that are children of accessibility containers, have
+ * an accessibity label and have an interactive UIAccessibilityTrait will automatically receive custom-action handling.
+ */
+- (void)performAccessibilityCustomAction:(UIAccessibilityCustomAction *)action;
+
 /**
  * @abstract Currently used by ASNetworkImageNode and ASMultiplexImageNode to allow their placeholders to stay if they are loading an image from the network.
  * Otherwise, a display pass is scheduled and completes, but does not actually draw anything - and ASDisplayNode considers the element finished.

Source/ASDisplayNode+Yoga.mm

@@ -19,6 +19,7 @@
 
 #if YOGA /* YOGA */
 
+#import <AsyncDisplayKit/_ASDisplayViewAccessiblity.h>
 #import <AsyncDisplayKit/ASYogaLayoutSpec.h>
 #import <AsyncDisplayKit/ASYogaUtilities.h>
 #import <AsyncDisplayKit/ASDisplayNode+Beta.h>
@@ -235,6 +236,11 @@ - (void)calculateLayoutFromYogaRoot:(ASSizeRange)rootConstrainedSize
                         yogaFloatForCGFloat(rootConstrainedSize.max.height),
                         YGDirectionInherit);
 
+  // Reset accessible elements, since layout may have changed.
+  ASPerformBlockOnMainThread(^{
+    [(_ASDisplayView *)self.view setAccessibleElements:nil];
+  });
+
   ASDisplayNodePerformBlockOnEveryYogaChild(self, ^(ASDisplayNode * _Nonnull node) {
     [node setupYogaCalculatedLayout];
     node.yogaLayoutInProgress = NO;

Source/ASDisplayNode.mm

@@ -3167,6 +3167,19 @@ - (ASDisplayNodePerformanceMeasurements)performanceMeasurements
   return measurements;
 }
 
+#pragma mark - Accessibility
+
+- (void)setIsAccessibilityContainer:(BOOL)isAccessibilityContainer
+{
+  ASDN::MutexLocker l(__instanceLock__);
+  _isAccessibilityContainer = isAccessibilityContainer;
+}
+
+- (BOOL)isAccessibilityContainer
+{
+  ASDN::MutexLocker l(__instanceLock__);
+  return _isAccessibilityContainer;
+}
 
 #pragma mark - Debugging (Private)
 

Source/Details/_ASDisplayViewAccessiblity.mm

@@ -23,9 +23,21 @@
 #import <AsyncDisplayKit/ASDisplayNode+Beta.h>
 #import <AsyncDisplayKit/ASDisplayNodeInternal.h>
 
+#import <queue>
+
+NS_INLINE UIAccessibilityTraits InteractiveAccessibilityTraitsMask() {
+  return UIAccessibilityTraitLink | UIAccessibilityTraitKeyboardKey | UIAccessibilityTraitButton;
+}
+
 #pragma mark - UIAccessibilityElement
 
-typedef NSComparisonResult (^SortAccessibilityElementsComparator)(UIAccessibilityElement *, UIAccessibilityElement *);
+@protocol ASAccessibilityElementPositioning
+
+@property (nonatomic, readonly) CGRect accessibilityFrame;
+
+@end
+
+typedef NSComparisonResult (^SortAccessibilityElementsComparator)(id<ASAccessibilityElementPositioning>, id<ASAccessibilityElementPositioning>);
 
 /// Sort accessiblity elements first by y and than by x origin.
 static void SortAccessibilityElements(NSMutableArray *elements)
@@ -35,7 +47,7 @@ static void SortAccessibilityElements(NSMutableArray *elements)
   static SortAccessibilityElementsComparator comparator = nil;
   static dispatch_once_t onceToken;
   dispatch_once(&onceToken, ^{
-      comparator = ^NSComparisonResult(UIAccessibilityElement *a, UIAccessibilityElement *b) {
+      comparator = ^NSComparisonResult(id<ASAccessibilityElementPositioning> a, id<ASAccessibilityElementPositioning> b) {
         CGPoint originA = a.accessibilityFrame.origin;
         CGPoint originB = b.accessibilityFrame.origin;
         if (originA.y == originB.y) {
@@ -50,7 +62,7 @@ static void SortAccessibilityElements(NSMutableArray *elements)
   [elements sortUsingComparator:comparator];
 }
 
-@interface ASAccessibilityElement : UIAccessibilityElement
+@interface ASAccessibilityElement : UIAccessibilityElement<ASAccessibilityElementPositioning>
 
 @property (nonatomic, strong) ASDisplayNode *node;
 @property (nonatomic, strong) ASDisplayNode *containerNode;
@@ -85,6 +97,25 @@ - (CGRect)accessibilityFrame
 
 #pragma mark - _ASDisplayView / UIAccessibilityContainer
 
+@interface ASAccessibilityCustomAction : UIAccessibilityCustomAction<ASAccessibilityElementPositioning>
+
+@property (nonatomic, strong) UIView *container;
+@property (nonatomic, strong) ASDisplayNode *node;
+@property (nonatomic, strong) ASDisplayNode *containerNode;
+
+@end
+
+@implementation ASAccessibilityCustomAction
+
+- (CGRect)accessibilityFrame
+{
+  CGRect accessibilityFrame = [self.containerNode convertRect:self.node.bounds fromNode:self.node];
+  accessibilityFrame = UIAccessibilityConvertFrameToScreenCoordinates(accessibilityFrame, self.container);
+  return accessibilityFrame;
+}
+
+@end
+
 /// Collect all subnodes for the given node by walking down the subnode tree and calculates the screen coordinates based on the containerNode and container
 static void CollectUIAccessibilityElementsForNode(ASDisplayNode *node, ASDisplayNode *containerNode, id container, NSMutableArray *elements)
 {
@@ -100,12 +131,64 @@ static void CollectUIAccessibilityElementsForNode(ASDisplayNode *node, ASDisplay
   });
 }
 
+static void CollectAccessibilityElementsForContainer(ASDisplayNode *container, _ASDisplayView *view, NSMutableArray *elements) {
+  UIAccessibilityElement *accessiblityElement = [ASAccessibilityElement accessibilityElementWithContainer:view node:container containerNode:container];
+
+  NSMutableArray<ASAccessibilityElement *> *labeledNodes = [NSMutableArray array];
+  NSMutableArray<ASAccessibilityCustomAction *> *actions = [NSMutableArray array];
+  std::queue<ASDisplayNode *> queue;
+  queue.push(container);
+
+  ASDisplayNode *node;
+  while (!queue.empty()) {
+    node = queue.front();
+    queue.pop();
+
+    if (node != container && node.isAccessibilityContainer) {
+      CollectAccessibilityElementsForContainer(node, view, elements);
+      continue;
+    }
+
+    if (node.accessibilityLabel.length > 0) {
+      if (node.accessibilityTraits & InteractiveAccessibilityTraitsMask()) {
+        ASAccessibilityCustomAction *action = [[ASAccessibilityCustomAction alloc] initWithName:node.accessibilityLabel target:node selector:@selector(performAccessibilityCustomAction:)];
+        action.node = node;
+        action.containerNode = node.supernode;
+        action.container = node.supernode.view;
+        [actions addObject:action];
+      } else {
+        // Even though not surfaced to UIKit, create a non-interactive element for purposes of building sorted aggregated label.
+        ASAccessibilityElement *nonInteractiveElement = [ASAccessibilityElement accessibilityElementWithContainer:view node:node containerNode:container];
+        [labeledNodes addObject:nonInteractiveElement];
+      }
+    }
+
+    for (ASDisplayNode *subnode in node.subnodes) {
+      queue.push(subnode);
+    }
+  }
+
+  SortAccessibilityElements(labeledNodes);
+  NSArray *labels = [labeledNodes valueForKey:@"accessibilityLabel"];
+  accessiblityElement.accessibilityLabel = [labels componentsJoinedByString:@", "];
+
+  SortAccessibilityElements(actions);
+  accessiblityElement.accessibilityCustomActions = actions;
+
+  [elements addObject:accessiblityElement];
+}
+
 /// Collect all accessibliity elements for a given view and view node
 static void CollectAccessibilityElementsForView(_ASDisplayView *view, NSMutableArray *elements)
 {
   ASDisplayNodeCAssertNotNil(elements, @"Should pass in a NSMutableArray");
 
   ASDisplayNode *node = view.asyncdisplaykit_node;
+
+  if (node.isAccessibilityContainer) {
+    CollectAccessibilityElementsForContainer(node, view, elements);
+    return;
+  }
 
   // Handle rasterize case
   if (node.rasterizesSubtree) {

Source/Private/ASDisplayNodeInternal.h

@@ -195,6 +195,7 @@ FOUNDATION_EXPORT NSString * const ASRenderingEngineDidDisplayNodesScheduledBefo
   NSArray *_accessibilityHeaderElements;
   CGPoint _accessibilityActivationPoint;
   UIBezierPath *_accessibilityPath;
+  BOOL _isAccessibilityContainer;
 
   // performance measurement
   ASDisplayNodePerformanceMeasurementOptions _measurementOptions;