Enhancing the target content offset logic.

Author: johnnewman-square

CHANGELOG.md

@@ -18,6 +18,8 @@
 
 ### Misc
 
+- `PagedListLayout.pagingBehavior` is now configurable. This can be used to keep the items centered when peeking.
+
 ### Internal
 
 - Replacing `PagedAppearance.PagingSize.view` with a `.inset(Peek)` case. This is used by `PagedListLayout` to lay out items with an edge peek.

Demo/Sources/Demos/Demo Screens/PeekingPagedViewController.swift

@@ -47,6 +47,7 @@ final class PeekingPagedViewController : UIViewController {
             list.behavior.decelerationRate = .fast
             list.layout = .paged {
                 $0.direction = isVertical ? .vertical : .horizontal
+                $0.pagingBehavior = .firstVisibleItemCentered
                 $0.peek = PagedAppearance.Peek(
                     value: (isVertical ? view.bounds.height : view.bounds.width) / 6,
                     firstItemConfiguration: zeroLeadingPeek ? .customLeading(0) : .uniform

ListableUI/Sources/Layout/ListLayout/ListLayout.swift

@@ -461,7 +461,9 @@ extension AnyListLayout
         velocity : CGPoint,
         visibleContentFrame: CGRect
     ) -> CGPoint?
-    {        
+    {
+        guard self.pagingBehavior != .none else { return nil }
+
         guard let item = self.itemToScrollToOnDidEndDragging(
             after: targetContentOffset,
             velocity: velocity,
@@ -510,21 +512,43 @@ extension AnyListLayout
             includeUnpopulated: false
         )
 
-        let mainAxisVelocity = direction.switch(
-            vertical: { velocity.y },
-            horizontal: { velocity.x }
-        )
-        
-        if scrollViewProperties.pagingStyle == .custom && mainAxisVelocity == 0 {
-            /// When the items are being held still with custom paging, bias the most visible item.
-            return items
-                .sorted { lhs, rhs in
-                    lhs.percentageVisible(inside: visibleContentFrame) > rhs.percentageVisible(inside: visibleContentFrame)
-                }
-                .first
+        if scrollViewProperties.pagingStyle == .custom {
+            let mainAxisVelocity = direction.switch(
+                vertical: { velocity.y },
+                horizontal: { velocity.x }
+            )
+            
+            if mainAxisVelocity == 0 {
+                return items
+                    /// When the items are being held still with custom paging, bias the most visible item.
+                    .sorted { lhs, rhs in
+                        lhs.percentageVisible(inside: visibleContentFrame) > rhs.percentageVisible(inside: visibleContentFrame)
+                    }
+                    .first
+            } else {
+                return items
+                    /// Only consider the visible items when calculating the custom paging offest.
+                    .filter { $0.percentageVisible(inside: visibleContentFrame) > 0 }
+                    /// Sort items in ascending order, based on their position along the primary axis.
+                    .sorted { lhs, rhs in
+                        direction.minY(for: lhs.defaultFrame) > direction.minY(for: rhs.defaultFrame)
+                    }
+                    /// Using the visible sorted items, return the first that has a minimum edge outside the target offset.
+                    .first { item in
+                        let edge = direction.minY(for: item.defaultFrame)
+                        let offset = direction.y(for: contentOffset)
+                        
+                        switch scrollDirection {
+                        case .forward:
+                            return edge >= offset
+                        case .backward:
+                            return edge <= offset
+                        }
+                    }
+            }
         } else {
-            /// Sort items based on their position on the primary axis, in ascending order.
             return items
+                /// Sort items based on their position on the primary axis, in ascending order.
                 .sorted { lhs, rhs in
                     switch scrollDirection {
                     case .forward:
@@ -533,7 +557,7 @@ extension AnyListLayout
                         return direction.maxY(for: lhs.defaultFrame) > direction.maxY(for: rhs.defaultFrame)
                     }
                 }
-                /// Find the first item that has a min edge beyond the offset, along the primary axis.
+                /// Using the sorted items, return the first has has a min edge outside the offset.
                 .first { item in
                     let edge = direction.minY(for: item.defaultFrame)
                     let offset = direction.y(for: contentOffset)

ListableUI/Sources/Layout/Paged/PagedListLayout.swift

@@ -66,7 +66,7 @@ public struct PagedAppearance : ListLayoutAppearance
 
     public let stickySectionHeaders: Bool = false
 
-    public let pagingBehavior: ListPagingBehavior = .firstVisibleItemCentered
+    public var pagingBehavior: ListPagingBehavior = .none
 
     public var scrollViewProperties: ListLayoutScrollViewProperties {
 
@@ -199,8 +199,8 @@ public extension PagedAppearance {
             (isFirstItem ? firstItemLeadingValue : value) + value
         }
 
-        /// This is `true` if there are no associated peek values.
-        var isEmpty: Bool {
+        /// This is `true` if there are no peek values.
+        public var isEmpty: Bool {
             value == 0 && firstItemLeadingValue == 0
         }
 

ListableUI/Sources/ListView/ListView.Delegate.swift

@@ -365,38 +365,17 @@ extension ListView
             withVelocity velocity: CGPoint,
             targetContentOffset: UnsafeMutablePointer<CGPoint>
         ) {
-            func findTarget() -> CGPoint? {
-                layoutManager.layout.onDidEndDraggingTargetContentOffset(
-                    for: scrollView.contentOffset,
-                    velocity: velocity,
-                    visibleContentFrame: scrollView.visibleContentFrame
-                )
-            }
-            
             switch layoutManager.layout.scrollViewProperties.pagingStyle {
             case .native:
-                // With a native paging style, leverage the system's target offset.
+                // With a native paging style, leverage the system's default target offset.
                 break
-            case .custom:
-                guard let target = findTarget() else { return }
-                let mainAxisVelocity = layoutManager.layout.direction.switch(
-                    vertical: { velocity.y.magnitude },
-                    horizontal: { velocity.x.magnitude }
+            case .custom, .none:
+                let target = layoutManager.layout.onDidEndDraggingTargetContentOffset(
+                    for: scrollView.contentOffset,
+                    velocity: velocity,
+                    visibleContentFrame: scrollView.visibleContentFrame
                 )
-                if mainAxisVelocity < 1.25 {
-                    // With a custom paging style, when the velocity is low, programatically
-                    // scroll to the target. This avoids cases where it takes too long for
-                    // the scroll view to reach the target. This is dispatched to wait for
-                    // scrollViewWillEndDragging(_:withVelocity:targetContentOffset:) to
-                    // finish, identical to an async programmatic scroll while decelerating.
-                    DispatchQueue.main.async {
-                        scrollView.setContentOffset(target, animated: true)
-                    }
-                } else {
-                    targetContentOffset.pointee = target
-                }
-            case .none:
-                guard let target = findTarget() else { return }
+                guard let target else { return }
                 targetContentOffset.pointee = target
             }
         }

ListableUI/Tests/Layout/ListLayout/ListLayoutTests.swift

@@ -28,7 +28,7 @@ final class AnyListLayoutTests : XCTestCase {
                     velocity: CGPoint(x: 0, y: 1),
                     visibleContentFrame: CGRect(origin: .zero, size: listSize)
                 ),
-                .zero
+                nil
             )
         }