Improve Our Handling of Flow Layout Headers/Footers (#2939)

* Rejigger our flow layout supplementary support to make more sense.

* Support old protocol

* Update

* Update deprecation message

* Undeprecate insetForSection method, because it actually _does_ still work

* Update the tests

* Remove irrelevant junk

* Remove cast, add pragma

Author: Adlai Holler

AsyncDisplayKit/ASCollectionView.h

@@ -416,33 +416,71 @@ ASDISPLAYNODE_DEPRECATED_MSG("Renamed to ASCollectionDelegate.")
 @end
 
 /**
- * Defines methods that let you coordinate with a `UICollectionViewFlowLayout` in combination with an `ASCollectionView`.
+ * Defines methods that let you coordinate a `UICollectionViewFlowLayout` in combination with an `ASCollectionNode`.
  */
-@protocol ASCollectionViewDelegateFlowLayout <ASCollectionDelegate>
+@protocol ASCollectionDelegateFlowLayout <ASCollectionDelegate>
 
 @optional
 
 /**
- * @discussion This method is deprecated and does nothing from 1.9.7 and up
- * Previously it applies the section inset to every cells within the corresponding section.
- * The expected behavior is to apply the section inset to the whole section rather than
- * shrinking each cell individually.
- * If you want this behavior, you can integrate your insets calculation into
- * `constrainedSizeForNodeAtIndexPath`
- * please file a github issue if you would like this to be restored.
+ * Asks the delegate for the inset that should be applied to the given section.
+ *
+ * @see the same method in UICollectionViewDelegate. 
+ */
+- (UIEdgeInsets)collectionView:(UICollectionView *)collectionView layout:(UICollectionViewLayout *)collectionViewLayout insetForSectionAtIndex:(NSInteger)section;
+
+/**
+ * Asks the delegate for the size range that should be used to measure the header in the given flow layout section.
+ *
+ * @param collectionNode The sender.
+ * @param section The section.
+ *
+ * @return The size range for the header, or @c ASSizeRangeZero if there is no header in this section.
+ *
+ * If you want the header to completely determine its own size, return @c ASSizeRangeUnconstrained.
+ *
+ * @note Only the scrollable dimension of the returned size range will be used. In a vertical flow,
+ * only the height will be used. In a horizontal flow, only the width will be used. The other dimension
+ * will be constrained to fill the collection node.
+ *
+ * @discussion If you do not implement this method, ASDK will fall back to calling @c collectionView:layout:referenceSizeForHeaderInSection:
+ * and using that as the exact constrained size. If you don't implement that method, ASDK will read the @c headerReferenceSize from the layout.
  */
-- (UIEdgeInsets)collectionView:(ASCollectionView *)collectionView layout:(UICollectionViewLayout *)collectionViewLayout insetForSectionAtIndex:(NSInteger)section ASDISPLAYNODE_DEPRECATED_MSG("This method does nothing for 1.9.7+ due to incorrect implementation previously, see the header file for more information.");
+- (ASSizeRange)collectionNode:(ASCollectionNode *)collectionNode sizeRangeForHeaderInSection:(NSInteger)section;
+
+/**
+ * Asks the delegate for the size range that should be used to measure the footer in the given flow layout section.
+ *
+ * @param collectionNode The sender.
+ * @param section The section.
+ *
+ * @return The size range for the footer, or @c ASSizeRangeZero if there is no footer in this section.
+ *
+ * If you want the footer to completely determine its own size, return @c ASSizeRangeUnconstrained.
+ *
+ * @note Only the scrollable dimension of the returned size range will be used. In a vertical flow,
+ * only the height will be used. In a horizontal flow, only the width will be used. The other dimension
+ * will be constrained to fill the collection node.
+ *
+ * @discussion If you do not implement this method, ASDK will fall back to calling @c collectionView:layout:referenceSizeForFooterInSection:
+ * and using that as the exact constrained size. If you don't implement that method, ASDK will read the @c footerReferenceSize from the layout.
+ */
+- (ASSizeRange)collectionNode:(ASCollectionNode *)collectionNode sizeRangeForFooterInSection:(NSInteger)section;
 
 /**
  * Asks the delegate for the size of the header in the specified section.
  */
-- (CGSize)collectionView:(ASCollectionView *)collectionView layout:(UICollectionViewLayout *)collectionViewLayout referenceSizeForHeaderInSection:(NSInteger)section;
+- (CGSize)collectionView:(ASCollectionView *)collectionView layout:(UICollectionViewLayout *)collectionViewLayout referenceSizeForHeaderInSection:(NSInteger)section ASDISPLAYNODE_DEPRECATED_MSG("Implement collectionNode:sizeRangeForHeaderInSection: instead.");
 
 /**
  * Asks the delegate for the size of the footer in the specified section.
  */
-- (CGSize)collectionView:(ASCollectionView *)collectionView layout:(UICollectionViewLayout *)collectionViewLayout referenceSizeForFooterInSection:(NSInteger)section;
+- (CGSize)collectionView:(ASCollectionView *)collectionView layout:(UICollectionViewLayout *)collectionViewLayout referenceSizeForFooterInSection:(NSInteger)section ASDISPLAYNODE_DEPRECATED_MSG("Implement collectionNode:sizeRangeForFooterInSection: instead.");
+
+@end
 
+ASDISPLAYNODE_DEPRECATED_MSG("Renamed to ASCollectionDelegateFlowLayout.")
+@protocol ASCollectionViewDelegateFlowLayout <ASCollectionDelegateFlowLayout>
 @end
 
 NS_ASSUME_NONNULL_END

AsyncDisplayKit/ASCollectionView.mm

@@ -138,7 +138,7 @@ - (void)layoutSubviews
 #pragma mark -
 #pragma mark ASCollectionView.
 
-@interface ASCollectionView () <ASRangeControllerDataSource, ASRangeControllerDelegate, ASCollectionDataControllerSource, ASCellNodeInteractionDelegate, ASDelegateProxyInterceptor, ASBatchFetchingScrollView, ASDataControllerEnvironmentDelegate, ASCALayerExtendedDelegate> {
+@interface ASCollectionView () <ASRangeControllerDataSource, ASRangeControllerDelegate, ASCollectionDataControllerSource, ASCellNodeInteractionDelegate, ASDelegateProxyInterceptor, ASBatchFetchingScrollView, ASDataControllerEnvironmentDelegate, ASCALayerExtendedDelegate, UICollectionViewDelegateFlowLayout> {
   ASCollectionViewProxy *_proxyDataSource;
   ASCollectionViewProxy *_proxyDelegate;
 
@@ -927,6 +927,16 @@ - (CGSize)collectionView:(UICollectionView *)collectionView layout:(UICollection
   return [[self nodeForItemAtIndexPath:indexPath] calculatedSize];
 }
 
+- (CGSize)collectionView:(UICollectionView *)collectionView layout:(UICollectionViewLayout *)collectionViewLayout referenceSizeForHeaderInSection:(NSInteger)section
+{
+  return [self supplementaryNodeForElementKind:UICollectionElementKindSectionHeader atIndexPath:[NSIndexPath indexPathForItem:0 inSection:section]].calculatedSize;
+}
+
+- (CGSize)collectionView:(UICollectionView *)collectionView layout:(UICollectionViewLayout *)collectionViewLayout referenceSizeForFooterInSection:(NSInteger)section
+{
+  return [self supplementaryNodeForElementKind:UICollectionElementKindSectionFooter atIndexPath:[NSIndexPath indexPathForItem:0 inSection:section]].calculatedSize;
+}
+
 - (UICollectionReusableView *)collectionView:(UICollectionView *)collectionView viewForSupplementaryElementOfKind:(NSString *)kind atIndexPath:(NSIndexPath *)indexPath
 {
   UICollectionReusableView *view = [self dequeueReusableSupplementaryViewOfKind:kind withReuseIdentifier:kReuseIdentifier forIndexPath:indexPath];
@@ -936,8 +946,6 @@ - (UICollectionReusableView *)collectionView:(UICollectionView *)collectionView
   return view;
 }
 
-
-
 - (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath
 {
   _ASCollectionViewCell *cell = [self dequeueReusableCellWithReuseIdentifier:kReuseIdentifier forIndexPath:indexPath];

AsyncDisplayKit/ASPagerNode.m

@@ -18,7 +18,7 @@
 #import "ASCellNode.h"
 #import "ASCollectionView+Undeprecated.h"
 
-@interface ASPagerNode () <ASCollectionDataSource, ASCollectionDelegate, ASCollectionViewDelegateFlowLayout, ASDelegateProxyInterceptor>
+@interface ASPagerNode () <ASCollectionDataSource, ASCollectionDelegate, ASCollectionDelegateFlowLayout, ASDelegateProxyInterceptor>
 {
   ASPagerFlowLayout *_flowLayout;
 

AsyncDisplayKit/Details/ASCollectionViewFlowLayoutInspector.m

@@ -24,7 +24,9 @@ @interface ASCollectionViewFlowLayoutInspector ()
 
 @implementation ASCollectionViewFlowLayoutInspector {
   struct {
+    unsigned int implementsSizeRangeForHeader:1;
     unsigned int implementsReferenceSizeForHeader:1;
+    unsigned int implementsSizeRangeForFooter:1;
     unsigned int implementsReferenceSizeForFooter:1;
     unsigned int implementsConstrainedSizeForNodeAtIndexPathDeprecated:1;
     unsigned int implementsConstrainedSizeForItemAtIndexPath:1;
@@ -53,7 +55,9 @@ - (void)didChangeCollectionViewDelegate:(id<ASCollectionDelegate>)delegate;
   if (delegate == nil) {
     memset(&_delegateFlags, 0, sizeof(_delegateFlags));
   } else {
+    _delegateFlags.implementsSizeRangeForHeader = [delegate respondsToSelector:@selector(collectionNode:sizeRangeForHeaderInSection:)];
     _delegateFlags.implementsReferenceSizeForHeader = [delegate respondsToSelector:@selector(collectionView:layout:referenceSizeForHeaderInSection:)];
+    _delegateFlags.implementsSizeRangeForFooter = [delegate respondsToSelector:@selector(collectionNode:sizeRangeForFooterInSection:)];
     _delegateFlags.implementsReferenceSizeForFooter = [delegate respondsToSelector:@selector(collectionView:layout:referenceSizeForFooterInSection:)];
     _delegateFlags.implementsConstrainedSizeForNodeAtIndexPathDeprecated = [delegate respondsToSelector:@selector(collectionView:constrainedSizeForNodeAtIndexPath:)];
     _delegateFlags.implementsConstrainedSizeForItemAtIndexPath = [delegate respondsToSelector:@selector(collectionNode:constrainedSizeForItemAtIndexPath:)];
@@ -84,65 +88,64 @@ - (ASSizeRange)collectionView:(ASCollectionView *)collectionView constrainedSize
 
 - (ASSizeRange)collectionView:(ASCollectionView *)collectionView constrainedSizeForSupplementaryNodeOfKind:(NSString *)kind atIndexPath:(NSIndexPath *)indexPath
 {
-  CGSize constrainedSize;
-  CGSize supplementarySize = [self sizeForSupplementaryViewOfKind:kind inSection:indexPath.section collectionView:collectionView];
-  if (_layout.scrollDirection == UICollectionViewScrollDirectionVertical) {
-    constrainedSize = CGSizeMake(CGRectGetWidth(collectionView.bounds), supplementarySize.height);
-  } else {
-    constrainedSize = CGSizeMake(supplementarySize.width, CGRectGetHeight(collectionView.bounds));
-  }
-  return ASSizeRangeMake(CGSizeZero, constrainedSize);
-}
-
-- (NSUInteger)collectionView:(ASCollectionView *)collectionView supplementaryNodesOfKind:(NSString *)kind inSection:(NSUInteger)section
-{
-  return [self layoutHasSupplementaryViewOfKind:kind inSection:section collectionView:collectionView] ? 1 : 0;
-}
-
-- (ASScrollDirection)scrollableDirections
-{
-  return (self.layout.scrollDirection == UICollectionViewScrollDirectionHorizontal) ? ASScrollDirectionHorizontalDirections : ASScrollDirectionVerticalDirections;
-}
-
-#pragma mark - Private helpers
-
-- (CGSize)sizeForSupplementaryViewOfKind:(NSString *)kind inSection:(NSUInteger)section collectionView:(ASCollectionView *)collectionView
-{
+  ASSizeRange result = ASSizeRangeZero;
   if (ASObjectIsEqual(kind, UICollectionElementKindSectionHeader)) {
-    if (_delegateFlags.implementsReferenceSizeForHeader) {
-      return [[self delegateForCollectionView:collectionView] collectionView:collectionView layout:_layout referenceSizeForHeaderInSection:section];
+    if (_delegateFlags.implementsSizeRangeForHeader) {
+      result = [[self delegateForCollectionView:collectionView] collectionNode:collectionView.collectionNode sizeRangeForHeaderInSection:indexPath.section];
+    } else if (_delegateFlags.implementsReferenceSizeForHeader) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+      CGSize exactSize = [[self delegateForCollectionView:collectionView] collectionView:collectionView layout:_layout referenceSizeForHeaderInSection:indexPath.section];
+#pragma clang diagnostic pop
+      result = ASSizeRangeMake(exactSize);
     } else {
-      return [self.layout headerReferenceSize];
+      result = ASSizeRangeMake(_layout.headerReferenceSize);
     }
   } else if (ASObjectIsEqual(kind, UICollectionElementKindSectionFooter)) {
-    if (_delegateFlags.implementsReferenceSizeForFooter) {
-      return [[self delegateForCollectionView:collectionView] collectionView:collectionView layout:_layout referenceSizeForFooterInSection:section];
+    if (_delegateFlags.implementsSizeRangeForFooter) {
+      result = [[self delegateForCollectionView:collectionView] collectionNode:collectionView.collectionNode sizeRangeForFooterInSection:indexPath.section];
+    } else if (_delegateFlags.implementsReferenceSizeForFooter) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+      CGSize exactSize = [[self delegateForCollectionView:collectionView] collectionView:collectionView layout:_layout referenceSizeForFooterInSection:indexPath.section];
+#pragma clang diagnostic pop
+      result = ASSizeRangeMake(exactSize);
     } else {
-      return [self.layout footerReferenceSize];
+      result = ASSizeRangeMake(_layout.footerReferenceSize);
     }
   } else {
-    return CGSizeZero;
+    ASDisplayNodeFailAssert(@"Unexpected supplementary kind: %@", kind);
+    return ASSizeRangeZero;
   }
-}
 
-- (BOOL)layoutHasSupplementaryViewOfKind:(NSString *)kind inSection:(NSUInteger)section collectionView:(ASCollectionView *)collectionView
-{
-  CGSize size = [self sizeForSupplementaryViewOfKind:kind inSection:section collectionView:collectionView];
-  return [self usedLayoutValueForSize:size] > 0;
+  if (_layout.scrollDirection == UICollectionViewScrollDirectionVertical) {
+    result.min.width = result.max.width = CGRectGetWidth(collectionView.bounds);
+  } else {
+    result.min.height = result.max.height = CGRectGetHeight(collectionView.bounds);
+  }
+  return result;
 }
 
-- (CGFloat)usedLayoutValueForSize:(CGSize)size
+- (NSUInteger)collectionView:(ASCollectionView *)collectionView supplementaryNodesOfKind:(NSString *)kind inSection:(NSUInteger)section
 {
+  ASSizeRange constraint = [self collectionView:collectionView constrainedSizeForSupplementaryNodeOfKind:kind atIndexPath:[NSIndexPath indexPathForItem:0 inSection:section]];
   if (_layout.scrollDirection == UICollectionViewScrollDirectionVertical) {
-    return size.height;
+    return (constraint.max.height > 0 ? 1 : 0);
   } else {
-    return size.width;
+    return (constraint.max.width > 0 ? 1 : 0);
   }
 }
 
-- (id<ASCollectionViewDelegateFlowLayout>)delegateForCollectionView:(ASCollectionView *)collectionView
+- (ASScrollDirection)scrollableDirections
+{
+  return (self.layout.scrollDirection == UICollectionViewScrollDirectionHorizontal) ? ASScrollDirectionHorizontalDirections : ASScrollDirectionVerticalDirections;
+}
+
+#pragma mark - Private helpers
+
+- (id<ASCollectionDelegateFlowLayout>)delegateForCollectionView:(ASCollectionView *)collectionView
 {
-  return (id<ASCollectionViewDelegateFlowLayout>)collectionView.asyncDelegate;
+  return (id<ASCollectionDelegateFlowLayout>)collectionView.asyncDelegate;
 }
 
 @end

AsyncDisplayKit/Details/ASDelegateProxy.m

@@ -68,6 +68,8 @@ - (BOOL)interceptsSelector:(SEL)selector
           // handled by ASCollectionView node<->cell machinery
           selector == @selector(collectionView:cellForItemAtIndexPath:) ||
           selector == @selector(collectionView:layout:sizeForItemAtIndexPath:) ||
+          selector == @selector(collectionView:layout:referenceSizeForHeaderInSection:) ||
+          selector == @selector(collectionView:layout:referenceSizeForFooterInSection:) ||
           selector == @selector(collectionView:viewForSupplementaryElementOfKind:atIndexPath:) ||
 
           // Selection, highlighting, menu

AsyncDisplayKit/Layout/ASDimension.h

@@ -201,6 +201,16 @@ typedef struct {
   CGSize max;
 } ASSizeRange;
 
+/**
+ * A size range with all dimensions zero.
+ */
+extern ASSizeRange const ASSizeRangeZero;
+
+/**
+ * A size range from zero to infinity in both directions.
+ */
+extern ASSizeRange const ASSizeRangeUnconstrained;
+
 /**
  * Creates an ASSizeRange with provided min and max size.
  */

AsyncDisplayKit/Layout/ASDimension.mm

@@ -61,6 +61,10 @@ ASOVERLOADABLE ASDimension ASDimensionMake(NSString *dimension)
 
 #pragma mark - ASSizeRange
 
+ASSizeRange const ASSizeRangeZero = {};
+
+ASSizeRange const ASSizeRangeUnconstrained = { {0, 0}, { INFINITY, INFINITY }};
+
 struct _Range {
   CGFloat min;
   CGFloat max;