Add ScrollAnimation for duration-based scrolls

[maxmeyers]

UIScrollView gives you a Bool for setContentOffset(_:animated:) and nothing else, so a programmatic Listable scroll is either instant or runs at a fixed system speed. This adds ScrollAnimation so a caller can say how long the scroll should take.

listActions.scrolling.scrollToSection(
    with: section.identifier,
    scrollPosition: .init(position: .top),
    animation: .duration(0.75)
)

The motivating case is a guided flow in Square Point of Sale: as the user completes each step, the list scrolls to the next one. At system speed the scroll is fast enough that it reads as a jump, and there's no way to slow it down.

What's here

ScrollAnimation has three states — .none, .system, and .duration(_:) — and every animated: Bool scrolling method on ListView and ListActions.Scrolling now has an animation: counterpart. animated: true and false map to .system and .none, so existing callers behave exactly as before.

Two things came along with it, because the new path needed them and the old ones didn't have them:

• scrollToTop(...) and scrollToLastItem(...) now take a completion handler. They previously had no way to report finishing.
• Fixed a completion handler being stranded when animated: true was requested inside a UIView.performWithoutAnimation block. The suppressed scroll produced no scrollViewDidEndScrollingAnimation(_:) callback, so the handler queued for it was never called.

Why a display link, and not UIView.animate

The usual suggestion for this problem is:

UIView.animate(withDuration: duration) {
    scrollView.setContentOffset(target, animated: false)
}

That animates, but on a UICollectionView the scroll is completely blank. The assignment lands the real contentOffset on the target immediately, so the collection view lays out at the destination and recycles every cell it was showing. Only the layer's bounds animate back — across a region that no longer has any cells in it. I had this built and passing tests before noticing it on screen; at ~100 rows and at ~800 rows of travel, content vanished for the whole animation and reappeared at the end.

Unit tests can't see it, which is worth knowing if this code is ever revisited: layer.animationKeys() contains bounds.origin and layer.presentation() interpolates correctly the entire time the screen is empty.

So ScrollAnimationDriver does what UIScrollView does for its own animation — assigns contentOffset on every frame from a CADisplayLink. Each assignment drives a layout pass, so cells dequeue as they scroll into view. ListViewTests has a regression test for this specifically (test_scroll_with_duration_animation_keeps_content_laid_out), asserting that the visible-item set mid-scroll is both non-empty and different from the set at the end — content laid out only at the destination would report the same items throughout.

The curve is a hardcoded ease-in-out, matching what UIScrollView does for its own scroll. It's a cosine rather than UIKit's bezier because a CAMediaTimingFunction only exposes its control points, not its value at a given time — solving the bezier per frame would mean carrying a Newton-iteration solver in Listable to land within 2% of where a one-line closed form already lands. There's no parameter for it: an exposed curve would have needed a bezier solver to be honest about the names, and no caller wanted one.

Two details worth a reviewer's attention

Where the animation is resolved. A scroll toward content that hasn't been laid out yet is deferred until the presentation state catches up, and that deferred work runs on a later runloop pass — outside any performWithoutAnimation block the caller made the request from, where UIView.areAnimationsEnabled reads true again. So the animation is resolved against the current context where the scroll is requested, not where the offset changes. Resolving late would silently ignore a caller's request not to animate.

Interruption. A driven scroll is stopped by the same things that stop the scroll view's own animation — the user taking hold of the list (scrollViewWillBeginDragging), or another scroll superseding it — and reports its completion handler either way. It's also cancelled when the list's identifier changes, since the offset reset there invalidates the target, and in ListView.deinit, because the main runloop retains the display link and would otherwise keep driving a torn down list.

Testing

Nine tests in ListViewTests under // MARK: Scroll animations, covering completion-exactly-once, offset parity with .system, mid-scroll sampling proving it eases rather than jumps, the blank-scroll regression above, cancellation, non-positive durations, suppressed animations, and that the driver doesn't retain itself while animating.

Worth noting for anyone extending these: a display-link animation is immune to layer.speed, so the layer.speed = 4 that show(vc:) applies to the test host doesn't affect it. Durations in these tests are real wall-clock seconds.

Also verified by hand in the demo app. ScrollToSectionCompletionHandlerViewController and its new ScrollToOffscreenSectionCompletionHandlerViewController subclass (40 sections, so the far ones are nowhere near the initial layout) both have an animation picker with None / System / 1s / 3s.

Checklist

Please do the following before merging:

• Ensure any public-facing changes are reflected in the changelog. Include them in the Main section.

[johnnewman-square]

Neat! This change looks good on my end and the demo works great. I left a couple comments: the one from my agent about the scroll completion handler feels like one worth investigating before we merge.

[johnnewman-square]

Not a blocker at all, but one edge case occurred to me: if the cell heights dynamically change during the driven scroll animation, we may animate to the wrong end location. It might be difficult to add a test for this case and I'm happy to treat it as an edge case.

[maxmeyers]

🤖 Agreed it's an edge case, and worth noting the system animation has it too: setContentOffset(_:animated:) commits to a target offset up front just as the driver does, so content that resizes mid-scroll can land off-target either way. The driven scroll is no worse than .system here rather than introducing a new failure mode, which is why I've left it. Clamping to the content size each frame would diverge from what the caller asked for, so if this ever needs solving I'd rather it be solved for both paths at once.

🤖 Addressed by Claude Code