Adding peek support to PagedListLayout (#560)

- `PagedListLayout` now supports a peek value, which allows items to
peek into view from the leading/top and trailing/bottom edges.
- The peek can be disabled, uniform on both sides, or have a unique
first item leading peek.
- The layout's `PagingSize` now supports `inset(Peek)` and
`fixed(CGFloat)` page sizes.
- Replacing the `isPagingEnabled` boolean with a `PagingStyle` enum.
This gives layouts the ability to disable paging, leverage `native`
UIScrollView paging (where items are full width), or use `custom` paging
(where items can be any width).
- `ListScrollPositionInfo` now contains the percentage of visibility for
each visible item. This allows clients to pick the most visible item for
selection.

Author: johnnewman-square

CHANGELOG.md

@@ -4,14 +4,27 @@
 
 ### Added
 
+- `PagedListLayout` now supports a peek value, which allows items to peek into view from the leading/top and trailing/bottom edges.
+- Adding a `mostVisibleItem` property to `ListScrollPositionInfo`.
+
 ### Removed
 
 ### Changed
 
+- Replacing the `isPagingEnabled` boolean with a `PageScrollingBehavior` enum. This gives layouts the ability to:
+  - leverage `full` page scrolling, where items are full width (equivalent to `isPagingEnabled` being `true`)
+  - use `peek` page scrolling, where items can be less than the full width and peek into view (this is new functionality)
+  - disable page scrolling via `none` (equivalent to `isPagingEnabled` being `false`)
+- `ListScrollPositionInfo`'s `visibleItems` is now a set of `VisibleItem` models, which contains a `percentageVisible` property.
+
 ### 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.
+
 # Past Releases
 
 # [15.0.2] - 2025-04-02

Demo/Demo.xcodeproj/project.pbxproj

@@ -55,6 +55,7 @@
 		397F72040272B0B12CAD9AEE /* Pods_Test_Targets.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = CF78F98F7ED38C2DC8078110 /* Pods_Test_Targets.framework */; };
 		8ECEBF6228B7E4C200ECEC56 /* CenterSnappingTableViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = 8ECEBF6128B7E4C200ECEC56 /* CenterSnappingTableViewController.swift */; };
 		B223A33A769988911ED5C0E1 /* Pods_Demo.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = A1C03134338F55F7FD12551D /* Pods_Demo.framework */; };
+		CE03D84F2D88584E009F922B /* PeekingPagedViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = CE03D84E2D88584E009F922B /* PeekingPagedViewController.swift */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXFileReference section */
@@ -113,6 +114,7 @@
 		A1C03134338F55F7FD12551D /* Pods_Demo.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Pods_Demo.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		C55FB4CC847A4E4F271441F7 /* Pods-Test Targets.debug.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-Test Targets.debug.xcconfig"; path = "Target Support Files/Pods-Test Targets/Pods-Test Targets.debug.xcconfig"; sourceTree = "<group>"; };
 		C9EC890C0D683F6A704AB9ED /* Pods-Demo.debug.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-Demo.debug.xcconfig"; path = "Target Support Files/Pods-Demo/Pods-Demo.debug.xcconfig"; sourceTree = "<group>"; };
+		CE03D84E2D88584E009F922B /* PeekingPagedViewController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PeekingPagedViewController.swift; sourceTree = "<group>"; };
 		CF78F98F7ED38C2DC8078110 /* Pods_Test_Targets.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Pods_Test_Targets.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		E0E11D5AA6E2508505BEE4FC /* Pods-Test Targets.release.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-Test Targets.release.xcconfig"; path = "Target Support Files/Pods-Test Targets/Pods-Test Targets.release.xcconfig"; sourceTree = "<group>"; };
 /* End PBXFileReference section */
@@ -176,6 +178,7 @@
 				0A7759D628FD923B00FD7C2A /* UpdateFuzzingViewController.swift */,
 				0AD6767925423BE500A49315 /* MultiSelectViewController.swift */,
 				0AC2A1952489F93E00779459 /* PagedViewController.swift */,
+				CE03D84E2D88584E009F922B /* PeekingPagedViewController.swift */,
 				0AA4D9B7248064A300CF95A5 /* ReorderingViewController.swift */,
 				0A02B2F32675E14600B3501B /* PaymentTypesViewController.swift */,
 				1F46FB6A26010F4900760961 /* RefreshControlOffsetAdjustmentViewController.swift */,
@@ -485,6 +488,7 @@
 				2B1B39902A706B3D00D614F1 /* ChatDemoViewController.swift in Sources */,
 				0A793B5824E4B53500850139 /* ManualSelectionManagementViewController.swift in Sources */,
 				8ECEBF6228B7E4C200ECEC56 /* CenterSnappingTableViewController.swift in Sources */,
+				CE03D84F2D88584E009F922B /* PeekingPagedViewController.swift in Sources */,
 				0AC839A525EEAD110055CEF5 /* OnTapItemAnimationViewController.swift in Sources */,
 				0AA4D9C9248064A300CF95A5 /* CollectionViewBasicDemoViewController.swift in Sources */,
 				0AA4D9BC248064A300CF95A5 /* KeyboardTestingViewController.swift in Sources */,

Demo/Sources/Demos/Demo Screens/AutoScrollingViewController.swift

@@ -76,7 +76,7 @@ final class AutoScrollingViewController : UIViewController
                     shouldPerform: { info in
                         // Only scroll to the bottom if the bottom item is already visible.
                         if let identifier = lastItem {
-                            return info.visibleItems.contains(identifier)
+                            return info.visibleItems.map(\.identifier).contains(identifier)
                         } else {
                             return false
                         }

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

@@ -0,0 +1,88 @@
+import BlueprintUILists
+import BlueprintUICommonControls
+
+
+/// This demo showcases a `PagedListLayout` with peeking leading/top and trailing/bottom items.
+final class PeekingPagedViewController : UIViewController {
+    
+    let blueprintView = BlueprintView()
+    
+    let listActions = ListActions()
+    
+    var isVertical : Bool = false
+    
+    /// When `true`, the first item's leading peek is 0. When `false` the peek is uniform.
+    var zeroLeadingPeek : Bool = false
+    
+    override func loadView() {
+        view = self.blueprintView
+        navigationItem.rightBarButtonItems = [
+            UIBarButtonItem(title: "Toggle Direction", style: .plain, target: self, action: #selector(toggleDirection)),
+            UIBarButtonItem(title: "Toggle First Peek", style: .plain, target: self, action: #selector(toggleFirstPeek))
+        ]
+    }
+    
+    override func viewWillAppear(_ animated: Bool) {
+        super.viewWillAppear(animated)
+        
+        view.layoutIfNeeded()
+        // Ensure the correct peek is used before the view appears.
+        update()
+    }
+    
+    // When the size changes, update the demo peek.
+    override func viewWillTransition(to size: CGSize, with coordinator: any UIViewControllerTransitionCoordinator) {
+        coordinator.animate { _ in
+            // For demo purposes, reset the scroll position when the size changes.
+            self.listActions.scrolling.scrollToTop()
+        } completion: { _ in
+            // Once the view is resized, update the peek/item size.
+            self.update()
+        }
+    }
+    
+    func update() {
+        blueprintView.element = List { list in
+            list.actions = listActions
+            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
+                )
+            }
+        } sections: {
+            Section("first") {
+                DemoElement(color: .red)
+                DemoElement(color: .orange)
+                DemoElement(color: .yellow)
+                DemoElement(color: .green)
+                DemoElement(color: .blue)
+            }
+        }
+    }
+    
+    @objc func toggleFirstPeek() {
+        zeroLeadingPeek.toggle()
+        update()
+    }
+    
+    @objc func toggleDirection() {
+        isVertical.toggle()
+        update()
+    }
+}
+
+fileprivate struct DemoElement : BlueprintItemContent, Equatable {
+    var identifierValue: UIColor {
+        color
+    }
+    
+    var color : UIColor
+    
+    func element(with info: ApplyItemContentInfo) -> Element {
+        Box(backgroundColor: color)
+    }
+}

Demo/Sources/Demos/DemosRootViewController.swift

@@ -258,6 +258,14 @@ public final class DemosRootViewController : ListViewController
                         self?.push(PagedViewController())
                     }
                 )
+                
+                Item(
+                    DemoItem(text: "Peeking Paged Layout"),
+                    selectionStyle: .selectable(),
+                    onSelect : { _ in
+                        self?.push(PeekingPagedViewController())
+                    }
+                )
 
                 Item(
                     DemoItem(text: "Center-Snapping Table Layout"),

ListableUI/Sources/Behavior.swift

@@ -39,8 +39,8 @@ public struct Behavior : Equatable
     /// A Boolean value that determines whether the scroll view delays the handling of touch-down gestures.
     public var delaysContentTouches : Bool
 
-    /// Is paging enabled on the underlying scroll view.
-    public var isPagingEnabled : Bool
+    /// The page scrolling behavior of the underlying scroll view. When `.none`, no paging is performed.
+    public var pageScrollingBehavior : PageScrollingBehavior
 
     /// The rate at which scrolling decelerates.
     public var decelerationRate: DecelerationRate
@@ -59,7 +59,7 @@ public struct Behavior : Equatable
         underflow : Underflow = Underflow(),
         canCancelContentTouches : Bool = true,
         delaysContentTouches : Bool = true,
-        isPagingEnabled : Bool = false,
+        pageScrollingBehavior : PageScrollingBehavior = .none,
         decelerationRate : DecelerationRate = .normal,
         verticalLayoutGravity : VerticalLayoutGravity = .top
     ) {
@@ -74,7 +74,7 @@ public struct Behavior : Equatable
 
         self.canCancelContentTouches = canCancelContentTouches
         self.delaysContentTouches = delaysContentTouches
-        self.isPagingEnabled = false
+        self.pageScrollingBehavior = pageScrollingBehavior
         self.decelerationRate = decelerationRate
 
         self.verticalLayoutGravity = verticalLayoutGravity

ListableUI/Sources/Internal/CGRect.swift

@@ -0,0 +1,12 @@
+import Foundation
+
+extension CGRect {
+    
+    /// Returns the percentage from `0.0` to `1.0` that this rect overlaps `container`.
+    func percentageVisible(inside container: CGRect) -> CGFloat {
+        let overlap = intersection(container)
+        let area = (width * height)
+        guard area != 0 else { return 0 }
+        return (overlap.width * overlap.height) / area
+    }
+}

ListableUI/Sources/Layout/Flow/FlowListLayout.swift

@@ -118,7 +118,7 @@ public struct FlowAppearance : ListLayoutAppearance {
     /// The properties of the backing `UIScrollView`.
     public var scrollViewProperties: ListLayoutScrollViewProperties {
         .init(
-            isPagingEnabled: false,
+            pageScrollingBehavior: .none,
             contentInsetAdjustmentBehavior: .scrollableAxes,
             allowsBounceVertical: true,
             allowsBounceHorizontal: true,

ListableUI/Sources/Layout/ListLayout/ListLayout.swift

@@ -459,18 +459,20 @@ extension AnyListLayout
     func onDidEndDraggingTargetContentOffset(
         for targetContentOffset : CGPoint,
         velocity : CGPoint,
-        visibleContentSize: CGSize
+        visibleContentFrame: CGRect
     ) -> CGPoint?
     {
         guard self.pagingBehavior != .none else { return nil }
-        
+
         guard let item = self.itemToScrollToOnDidEndDragging(
             after: targetContentOffset,
-            velocity: velocity
+            velocity: velocity,
+            visibleContentFrame: visibleContentFrame
         ) else {
             return nil
         }
 
+        let visibleContentSize = visibleContentFrame.size
         let padding = self.bounds?.padding ?? .zero
 
         switch self.pagingBehavior {
@@ -493,39 +495,84 @@ extension AnyListLayout
 
     func itemToScrollToOnDidEndDragging(
         after contentOffset : CGPoint,
-        velocity : CGPoint
+        velocity : CGPoint,
+        visibleContentFrame: CGRect
     ) -> ListLayoutContent.ContentItem?
     {
-        let rect : CGRect = self.rectForFindingItemToScrollToOnDidEndDragging(
-            after: contentOffset,
-            velocity: velocity
-        )
+        let rect: CGRect
+        if scrollViewProperties.pageScrollingBehavior == .peek {
+            /// When peeking, the visible items are the only items considered for the page offest.
+            rect = visibleContentFrame
+        } else {
+            rect = self.rectForFindingItemToScrollToOnDidEndDragging(
+                after: contentOffset,
+                velocity: velocity
+            )
+        }
 
         let scrollDirection = ScrollVelocityDirection(direction.y(for: velocity))
 
         let items = self.content.content(
             in: rect,
             alwaysIncludeOverscroll: false,
             includeUnpopulated: false
-        ).sorted { lhs, rhs in
-            switch scrollDirection {
-            case .forward:
-                return direction.minY(for: lhs.defaultFrame) < direction.minY(for: rhs.defaultFrame)
-            case .backward:
-                return direction.maxY(for: lhs.defaultFrame) > direction.maxY(for: rhs.defaultFrame)
-            }
-        }
-
-        return items.first { item in
-            let edge = direction.minY(for: item.defaultFrame)
-            let offset = direction.y(for: contentOffset)
+        )
+        
+        if scrollViewProperties.pageScrollingBehavior == .peek {
+            let mainAxisVelocity = direction.switch(
+                vertical: { velocity.y },
+                horizontal: { velocity.x }
+            )
 
-            switch scrollDirection {
-            case .forward:
-                return edge >= offset
-            case .backward:
-                return edge <= offset
+            if 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
+            } else {
+                return items
+                    /// 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 {
+            return items
+                /// Sort items based on their position on the primary axis, in ascending order.
+                .sorted { lhs, rhs in
+                    switch scrollDirection {
+                    case .forward:
+                        return direction.minY(for: lhs.defaultFrame) < direction.minY(for: rhs.defaultFrame)
+                    case .backward:
+                        return direction.maxY(for: lhs.defaultFrame) > direction.maxY(for: rhs.defaultFrame)
+                    }
+                }
+                /// 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)
+                    
+                    switch scrollDirection {
+                    case .forward:
+                        return edge >= offset
+                    case .backward:
+                        return edge <= offset
+                    }
+                }
         }
     }
 

ListableUI/Sources/Layout/ListLayout/ListLayoutContent.swift

@@ -560,6 +560,11 @@ extension ListLayoutContent
             case .supplementary(let supplementary, _): return supplementary.defaultFrame
             }
         }
+        
+        /// Returns the percentage from `0.0` to `1.0` that this item overlaps `container`.
+        func percentageVisible(inside container: CGRect) -> CGFloat {
+            collectionViewLayoutAttributes.frame.percentageVisible(inside: container)
+        }
     }
 }