Bk/add layout state #148

bryankeller · 2025-11-06T07:30:52Z

Details

This PR builds on the last few, introducing a new abstraction called the LayoutState. The LayoutState contains a snapshot of the ModelState (which contains section and item models), as well as collection view metrics like the current bounds and content insets.

When updates occur (due to prepareLayout, prepareForCollectionViewUpdates, and prepareForAnimatedBoundsChange being called), we save a snapshot of the layout by creating a LayoutState instance before making any changes. This is very useful, as it allows us to later on reference the exact state the collection view was in when doing things like:

calculating the target content offset when rotating the device
calculating the contentOffsetAdjustment as items are self-sized when scrolling
referencing pre-update item frames if needed when performing the aforementioned calculations

Once we land this, I plan to further simplify MagazineLayout.swift, which currently does a ton of layout metric caching / tracking across updates, each one being done in a bespoke way. With the introduction of the LayoutState, we should be able to clean up most of this one-off metric tracking.

How Has This Been Tested

Tested new example app, Airbnb app, unit tests

Types of changes

Docs change / refactoring / dependency upgrade
Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist

My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have read the CONTRIBUTING document.
I have added tests to cover my changes.

bryankeller · 2025-11-06T07:31:20Z

MagazineLayout/LayoutCore/Types/MagazineLayoutSectionMetrics.swift

  }

-  private init(
+  init(


made internal for unit test support

bryankeller · 2025-11-06T07:32:39Z

MagazineLayout/LayoutCore/Types/TargetContentOffsetAnchor.swift

-/// An internal type for calculating the target content offset for various state of the collection view. Various anchors are possible, each
-/// changing how the collection view prioritizes keeping certain items visible in target content offset calculations.


All of the static functions below for calculating the targetContentOffsetAnchor and yOffset moved to the LayoutState, making it easier to get this information for pre-update and post-update layout states.

bryankeller · 2025-11-06T07:34:14Z

MagazineLayout/LayoutCore/LayoutState.swift

+  var contentSize: CGSize {
+    // This is a workaround for `layoutAttributesForElementsInRect:` not getting invoked enough
+    // times if `collectionViewContentSize.width` is not smaller than the width of the collection
+    // view, minus horizontal insets. This results in visual defects when performing batch
+    // updates. To work around this, we subtract 0.0001 from our content size width calculation;
+    // this small decrease in `collectionViewContentSize.width` is enough to work around the
+    // incorrect, internal collection view `CGRect` checks, without introducing any visual
+    // differences for elements in the collection view.
+    // See https://openradar.appspot.com/radar?id=5025850143539200 for more details.
+    let width = bounds.width - contentInset.left - contentInset.right - 0.0001
+
+    let numberOfSections = modelState.numberOfSections
+    let height: CGFloat =
+      if numberOfSections <= 0 {
+        0
+      } else {
+        modelState.sectionMaxY(forSectionAtIndex: numberOfSections - 1)
+      }
+
+    return CGSize(width: width, height: height)


all of this used to live in MagazineLayout.swift - I moved it here without changing any math or comments

bryankeller · 2025-11-06T07:34:45Z

MagazineLayout/LayoutCore/LayoutState.swift

+  var targetContentOffsetAnchor: TargetContentOffsetAnchor {
+    var visibleItemLocationFramePairs = [ElementLocationFramePair]()
+    for itemLocationFramePair in modelState.itemLocationFramePairs(forItemsIn: bounds) {
+      visibleItemLocationFramePairs.append(itemLocationFramePair)
+    }
+    visibleItemLocationFramePairs.sort { $0.elementLocation < $1.elementLocation }
+
+    let firstVisibleItemLocationFramePair = visibleItemLocationFramePairs.first {
+      // When scrolling up, only calculate a target content offset based on visible, already-sized
+      // cells. Otherwise, scrolling will be jumpy.
+      modelState.isItemHeightSettled(indexPath: $0.elementLocation.indexPath)
+    } ?? visibleItemLocationFramePairs.first // fallback to the first item if we can't find one with a settled height
+
+    let lastVisibleItemLocationFramePair = visibleItemLocationFramePairs.reversed().first {
+      // When scrolling down, only calculate a target content offset based on visible, already-sized
+      // cells. Otherwise, scrolling will be jumpy.
+      modelState.isItemHeightSettled(indexPath: $0.elementLocation.indexPath)
+    } ?? visibleItemLocationFramePairs.last // fallback to the last item if we can't find one with a settled height
+
+    guard
+      let firstVisibleItemLocationFramePair,
+      let lastVisibleItemLocationFramePair,
+      let firstVisibleItemID = modelState.idForItemModel(
+        at: firstVisibleItemLocationFramePair.elementLocation.indexPath),
+      let lastVisibleItemID = modelState.idForItemModel(
+        at: lastVisibleItemLocationFramePair.elementLocation.indexPath)
+    else {
+      switch verticalLayoutDirection {
+      case .topToBottom: return .top
+      case .bottomToTop: return .bottom
+      }
+    }
+
+    let top = minContentOffset.y.alignedToPixel(forScreenWithScale: scale)
+    let bottom = maxContentOffset.y.alignedToPixel(forScreenWithScale: scale)
+    let isAtTop = bounds.minY <= top
+    let isAtBottom = bounds.minY >= bottom
+    let position: Position
+    if isAtTop, isAtBottom {
+      switch verticalLayoutDirection {
+      case .topToBottom:
+        position = .atTop
+      case .bottomToTop:
+        position = .atBottom
+      }
+    } else if isAtTop {
+      position = .atTop
+    } else if isAtBottom {
+      position = .atBottom
+    } else {
+      position = .inMiddle
+    }
+
+    switch verticalLayoutDirection {
+    case .topToBottom:
+      switch position {
+      case .atTop:
+        return .top
+      case .inMiddle, .atBottom:
+        let top = bounds.minY + contentInset.top
+        let distanceFromTop = firstVisibleItemLocationFramePair.frame.minY - top
+        return .topItem(
+          id: firstVisibleItemID,
+          distanceFromTop: distanceFromTop.alignedToPixel(forScreenWithScale: scale))
+      }
+    case .bottomToTop:
+      switch position {
+      case .atTop, .inMiddle:
+        let bottom = bounds.maxY - contentInset.bottom
+        let distanceFromBottom = lastVisibleItemLocationFramePair.frame.maxY - bottom
+        return .bottomItem(
+          id: lastVisibleItemID,
+          distanceFromBottom: distanceFromBottom.alignedToPixel(forScreenWithScale: scale))
+      case .atBottom:
+        return .bottom
+      }
+    }
+  }


logic pulled out of a function that used to live in MagazineLayout.swift

bryankeller · 2025-11-06T07:35:38Z

MagazineLayout/LayoutCore/ModelState.swift

-    if !disableSectionMaxYsCache {
-      cacheMaxY(maxY, forSectionAtIndex: targetSectionIndex)
-    }


I meant to delete this in my last PR - this extra property / check isn't necessary, and was never actually used

bryankeller · 2025-11-06T07:36:48Z

Tests/LayoutStateTargetContentOffsetTests.swift

+
+@testable import MagazineLayout
+
+final class LayoutStateTargetContentOffsetTests: XCTestCase {


Deleted the old target-content-offset-related tests, and replaced them with these new ones. The test cases are the same, but the implementations are different due to the tested logic moving to the LayoutState

bryankeller · 2025-11-06T07:37:05Z