Add cell deselection API

Summary:
Adding support for a cell deselection API. Trying to make some headway to move and drag+drop support, but also want better stock `UICollectionView` API support. Will also assist eventual `UITableView` support.

- Added overridable API to `IGListSectionController`
- Support for stacked SC
- Breaking, required protocol for binding SC

Assists Instagram#524 and Instagram#184

- [x] All tests pass. Demo project builds and runs.
- [x] I added tests, an experiment, or detailed why my change isn't tested.
- [x] I added an entry to the `CHANGELOG.md` for any breaking changes, enhancements, or bug fixes.
Closes Instagram#853

Reviewed By: jeremycohen

Differential Revision: D5425414

Pulled By: rnystrom

fbshipit-source-id: 0b25c125b1f171979a15c3095095fc18b4108be6

CHANGELOG.md

@@ -9,6 +9,10 @@ The changelog for `IGListKit`. Also see the [releases](https://github.com/instag
 
 - Prevent a crash when update queued immediately after item batch update. [Ryan Nystrom](https://github.com/rnystrom) (tbd)
 
+### Enhancements
+
+- Added `-[IGListSectionController didDeselectItemAtIndex:]` API to support default `UICollectionView` cell deselection. [Ryan Nystrom](https://github.com/rnystrom) (tbd)
+
 3.0.0
 -----
 

Examples/Examples-iOS/IGListKitExamples/SectionControllers/MonthSectionController.swift

@@ -95,4 +95,6 @@ final class MonthSectionController: ListBindingSectionController<ListDiffable>,
         update(animated: true)
     }
 
+    func sectionController(_ sectionController: ListBindingSectionController<ListDiffable>, didDeselectItemAt index: Int, viewModel: Any) {}
+
 }

Source/IGListBindingSectionController.m

@@ -123,4 +123,8 @@ - (void)didSelectItemAtIndex:(NSInteger)index {
     [self.selectionDelegate sectionController:self didSelectItemAtIndex:index viewModel:self.viewModels[index]];
 }
 
+- (void)didDeselectItemAtIndex:(NSInteger)index {
+    [self.selectionDelegate sectionController:self didDeselectItemAtIndex:index viewModel:self.viewModels[index]];
+}
+
 @end

Source/IGListBindingSectionControllerSelectionDelegate.h

@@ -30,6 +30,20 @@ NS_SWIFT_NAME(ListBindingSectionControllerSelectionDelegate)
      didSelectItemAtIndex:(NSInteger)index
                 viewModel:(id)viewModel;
 
+/**
+ Tells the delegate that a cell at a given index was deselected.
+
+ @param sectionController The section controller the deselection occurred in.
+ @param index The index of the deselected cell.
+ @param viewModel The view model that was bound to the cell.
+
+ @note Method is `@optional` until the 4.0.0 release where it will become required.
+ */
+@optional
+- (void)sectionController:(IGListBindingSectionController *)sectionController
+   didDeselectItemAtIndex:(NSInteger)index
+                viewModel:(id)viewModel;
+
 @end
 
 NS_ASSUME_NONNULL_END

Source/IGListSectionController.h

@@ -81,6 +81,15 @@ NS_SWIFT_NAME(ListSectionController)
  */
 - (void)didSelectItemAtIndex:(NSInteger)index;
 
+/**
+ Tells the section controller that the cell at the specified index path was deselected.
+
+ @param index The index of the deselected cell.
+
+ @note The default implementation does nothing. **Calling super is not required.**
+ */
+- (void)didDeselectItemAtIndex:(NSInteger)index;
+
 /**
  The view controller housing the adapter that created this section controller.
 

Source/IGListSectionController.m

@@ -84,4 +84,6 @@ - (void)didUpdateToObject:(id)object {}
 
 - (void)didSelectItemAtIndex:(NSInteger)index {}
 
+- (void)didDeselectItemAtIndex:(NSInteger)index {}
+
 @end

Source/IGListStackedSectionController.m

@@ -160,6 +160,12 @@ - (void)didSelectItemAtIndex:(NSInteger)index {
     [sectionController didSelectItemAtIndex:localIndex];
 }
 
+- (void)didDeselectItemAtIndex:(NSInteger)index {
+    IGListSectionController *sectionController = [self sectionControllerForObjectIndex:index];
+    const NSInteger localIndex = [self localIndexForSectionController:sectionController index:index];
+    [sectionController didDeselectItemAtIndex:localIndex];
+}
+
 #pragma mark - IGListCollectionContext
 
 - (CGSize)containerSize {

Source/Internal/IGListAdapter+UICollectionView.m

@@ -71,6 +71,17 @@ - (void)collectionView:(UICollectionView *)collectionView didSelectItemAtIndexPa
     [sectionController didSelectItemAtIndex:indexPath.item];
 }
 
+- (void)collectionView:(UICollectionView *)collectionView didDeselectItemAtIndexPath:(NSIndexPath *)indexPath {
+    // forward this method to the delegate b/c this implementation will steal the message from the proxy
+    id<UICollectionViewDelegate> collectionViewDelegate = self.collectionViewDelegate;
+    if ([collectionViewDelegate respondsToSelector:@selector(collectionView:didDeselectItemAtIndexPath:)]) {
+        [collectionViewDelegate collectionView:collectionView didDeselectItemAtIndexPath:indexPath];
+    }
+
+    IGListSectionController * sectionController = [self sectionControllerForSection:indexPath.section];
+    [sectionController didDeselectItemAtIndex:indexPath.item];
+}
+
 - (void)collectionView:(UICollectionView *)collectionView willDisplayCell:(UICollectionViewCell *)cell forItemAtIndexPath:(NSIndexPath *)indexPath {
     // forward this method to the delegate b/c this implementation will steal the message from the proxy
     id<UICollectionViewDelegate> collectionViewDelegate = self.collectionViewDelegate;

Tests/IGListAdapterTests.m

@@ -860,6 +860,40 @@ - (void)test_whenSelectingCell_thatSectionControllerReceivesMethod {
     XCTAssertFalse(s2.wasSelected);
 }
 
+- (void)test_whenDeselectingCell_thatCollectionViewDelegateReceivesMethod {
+    self.dataSource.objects = @[@0, @1, @2];
+    [self.adapter reloadDataWithCompletion:nil];
+
+    id mockDelegate = [OCMockObject mockForProtocol:@protocol(UICollectionViewDelegate)];
+    self.adapter.collectionViewDelegate = mockDelegate;
+
+    NSIndexPath *indexPath = [NSIndexPath indexPathForItem:0 inSection:0];
+    [[mockDelegate expect] collectionView:self.collectionView didDeselectItemAtIndexPath:indexPath];
+
+    // simulates the collectionview telling its delegate that it was tapped
+    [self.adapter collectionView:self.collectionView didDeselectItemAtIndexPath:indexPath];
+
+    [mockDelegate verify];
+}
+
+- (void)test_whenDeselectingCell_thatSectionControllerReceivesMethod {
+    self.dataSource.objects = @[@0, @1, @2];
+    [self.adapter reloadDataWithCompletion:nil];
+
+    NSIndexPath *indexPath = [NSIndexPath indexPathForItem:0 inSection:0];
+
+    // simulates the collectionview telling its delegate that it was tapped
+    [self.adapter collectionView:self.collectionView didDeselectItemAtIndexPath:indexPath];
+
+    IGListTestSection *s0 = [self.adapter sectionControllerForObject:@0];
+    IGListTestSection *s1 = [self.adapter sectionControllerForObject:@1];
+    IGListTestSection *s2 = [self.adapter sectionControllerForObject:@2];
+
+    XCTAssertTrue(s0.wasDeselected);
+    XCTAssertFalse(s1.wasDeselected);
+    XCTAssertFalse(s2.wasDeselected);
+}
+
 - (void)test_whenDisplayingCell_thatCollectionViewDelegateReceivesMethod {
     self.dataSource.objects = @[@0, @1, @2];
     [self.adapter reloadDataWithCompletion:nil];

Tests/IGListBindingSectionControllerTests.m

@@ -112,6 +112,15 @@ - (void)test_whenSelectingCell_thatCorrectViewModelSelected {
     XCTAssertEqualObjects(section.selectedViewModel, @"seven");
 }
 
+- (void)test_whenDeselectingCell_thatCorrectViewModelSelected {
+    [self setupWithObjects:@[
+                             [[IGTestDiffingObject alloc] initWithKey:@1 objects:@[@7, @"seven"]],
+                             ]];
+    [self.adapter collectionView:self.collectionView didDeselectItemAtIndexPath:[NSIndexPath indexPathForItem:1 inSection:0]];
+    IGTestDiffingSectionController *section = [self.adapter sectionControllerForObject:self.dataSource.objects.firstObject];
+    XCTAssertEqualObjects(section.deselectedViewModel, @"seven");
+}
+
 - (void)test_whenAdapterReloadsObjects_thatSectionUpdated {
     [self setupWithObjects:@[
                              [[IGTestDiffingObject alloc] initWithKey:@1 objects:@[@7, @"seven"]],

Tests/IGListStackSectionControllerTests.m

@@ -567,6 +567,31 @@ - (void)test_whenSelectingItems_thatChildSectionControllersSelected {
     XCTAssertTrue([stack2.sectionControllers[1] wasSelected]);
 }
 
+- (void)test_whenDeselectingItems_thatChildSectionControllersSelected {
+    [self setupWithObjects:@[
+                             [[IGTestObject alloc] initWithKey:@0 value:@[@1, @2, @3]],
+                             [[IGTestObject alloc] initWithKey:@1 value:@[@1, @2, @3]],
+                             [[IGTestObject alloc] initWithKey:@2 value:@[@1, @1]]
+                             ]];
+
+    [self.adapter collectionView:self.collectionView didDeselectItemAtIndexPath:[NSIndexPath indexPathForItem:0 inSection:0]];
+    [self.adapter collectionView:self.collectionView didDeselectItemAtIndexPath:[NSIndexPath indexPathForItem:2 inSection:1]];
+    [self.adapter collectionView:self.collectionView didDeselectItemAtIndexPath:[NSIndexPath indexPathForItem:1 inSection:2]];
+
+    IGListStackedSectionController *stack0 = [self.adapter sectionControllerForObject:self.dataSource.objects[0]];
+    IGListStackedSectionController *stack1 = [self.adapter sectionControllerForObject:self.dataSource.objects[1]];
+    IGListStackedSectionController *stack2 = [self.adapter sectionControllerForObject:self.dataSource.objects[2]];
+
+    XCTAssertTrue([stack0.sectionControllers[0] wasDeselected]);
+    XCTAssertFalse([stack0.sectionControllers[1] wasDeselected]);
+    XCTAssertFalse([stack0.sectionControllers[2] wasDeselected]);
+    XCTAssertFalse([stack1.sectionControllers[0] wasDeselected]);
+    XCTAssertTrue([stack1.sectionControllers[1] wasDeselected]);
+    XCTAssertFalse([stack1.sectionControllers[2] wasDeselected]);
+    XCTAssertFalse([stack2.sectionControllers[0] wasDeselected]);
+    XCTAssertTrue([stack2.sectionControllers[1] wasDeselected]);
+}
+
 - (void)test_whenUsingNibs_withStoryboards_thatCellsAreConfigured {
     [self setupWithObjects:@[
                              [[IGTestObject alloc] initWithKey:@0 value:@[@1, @"nib", @"storyboard"]],

Tests/Objects/IGListTestSection.h

@@ -15,9 +15,8 @@
 @interface IGListTestSection : IGListSectionController
 
 @property (nonatomic, assign) NSInteger items;
-
 @property (nonatomic, assign) CGSize size;
-
 @property (nonatomic, assign) BOOL wasSelected;
+@property (nonatomic, assign) BOOL wasDeselected;
 
 @end

Tests/Objects/IGListTestSection.m

@@ -46,4 +46,8 @@ - (void)didSelectItemAtIndex:(NSInteger)index {
     self.wasSelected = YES;
 }
 
+- (void)didDeselectItemAtIndex:(NSInteger)index {
+    self.wasDeselected = YES;
+}
+
 @end

Tests/Objects/IGTestDiffingSectionController.h

@@ -12,5 +12,6 @@
 @interface IGTestDiffingSectionController : IGListBindingSectionController <IGListBindingSectionControllerDataSource, IGListBindingSectionControllerSelectionDelegate>
 
 @property (nonatomic, strong) id selectedViewModel;
+@property (nonatomic, strong) id deselectedViewModel;
 
 @end

Tests/Objects/IGTestDiffingSectionController.m

@@ -55,4 +55,8 @@ - (void)sectionController:(IGListBindingSectionController *)sectionController di
     self.selectedViewModel = viewModel;
 }
 
+- (void)sectionController:(IGListBindingSectionController *)sectionController didDeselectItemAtIndex:(NSInteger)index viewModel:(id)viewModel {
+    self.deselectedViewModel = viewModel;
+}
+
 @end