Add custom item offset scrolling by aaalaniz · Pull Request #615 · square/Listable

aaalaniz · 2026-05-21T14:27:51Z

Adds a Listable-owned API for custom vertical item positioning from both imperative ListActions and declarative AutoScrollAction.

What's changed

Adds ListItemScrollPosition.standard(_:) and .verticalContentOffsetAdjustment(_:).
Adds AutoScrollAction.scrollTo(... itemPosition:) and pin(... itemPosition:), with existing position: overloads preserved.
Adds AutoScrollAction.ScrollInterruptionPolicy:
- .performImmediately
- .deferDuringUserScrolling
- .skipDuringUserScrolling
Keeps custom adjustments vertical-only; no horizontal offset API is added.
Adds a generic demo: Custom Auto Scrolling (Footer-Aware Pin).
Adds tests for custom declarative auto-scroll, callback behavior, deferral, and skip policy.

Example

list.autoScrollAction = .pin(
    .item(targetIdentifier),
    itemPosition: .verticalContentOffsetAdjustment { info in
        max(0.0, info.itemFrame.maxY - info.visibleContentFrame.maxY)
    },
    scrollInterruptionPolicy: .deferDuringUserScrolling
)

Use .skipDuringUserScrolling when an auto-scroll request should be dropped instead of retried after user scrolling ends.

Visuals

auto-scroll-vertical-offset-rotated.mov

Test Plan

mise exec -- xcodebuild test -workspace Development/ListableDevelopment.xcworkspace -scheme ListableDevelopment-Workspace -destination 'id=52DC49DC-0376-4B43-99BE-BC7A016A51B3' -derivedDataPath /tmp/listable-dd-development-tests -only-testing:ListableTests
git diff --check
Built and launched Custom Auto Scrolling (Footer-Aware Pin) demo on iOS Simulator

Checklist

Please do the following before merging:

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

Expose a Listable-owned item scrolling API that lets callers compute a vertical content offset adjustment without accessing the scroll view.

aaalaniz · 2026-05-21T14:28:01Z

🤖 @codex review

aaalaniz · 2026-05-22T18:09:32Z

+            list.animation = .fast
+            list.scrollIndicatorInsets.bottom = 112.0
+
+            list.autoScrollAction = .pin(


The new API in action

aaalaniz · 2026-05-22T18:17:52Z

+    @discardableResult
+    public func scrollTo(
+        item : AnyIdentifier,
+        contentOffsetAdjustment : @escaping ListItemScrollPositionAdjustment,


I think it's okay that this is marked as escaping but making a note for myself

This is okay to me. Since this closure is stored, it would be good to add a small doc around this new closure to note that clients should only use weak self.

🤖 [Codex] Addressed in 2a62c74. I added docs to the adjustment type/factory noting that declarative scrolling APIs may store the closure, and that clients should capture list owners/configurers weakly to avoid retain cycles.

johnnewman-square

This is a neat enhancement. I left just a few notes that I think we could potentially explore.

johnnewman-square · 2026-05-22T22:23:24Z

I received this feedback from Codex. I think we could potentially make a few adjustments here and add a unit test to capture this specific case:

In ListView.Delegate.swift, onDidEndScrollingAnimation now gets actions, so a client can start another scroll from inside that callback. But self.view.didEndScrolling() is called after the observer callback. If the callback starts an animated scroll with a completion, ListView.swift appends that new completion, and then the current “old scroll ended” event drains it immediately. So the completion can fire with stale position info before the newly requested scroll finishes.

The likely fix is to snapshot/drain existing scroll completions before invoking onDidEndScrollingAnimation, or otherwise make didEndScrolling() only process handlers that existed before this delegate callback began.

Good catch, will adjust.

🤖 [Codex] Addressed in bd63c5a. The delegate now drains the completion handlers that existed before onDidEndScrollingAnimation, runs the observer callback with actions, and then executes only that drained batch. I also added a regression test covering a new animated scroll started from the callback so its completion waits for the next scroll end.

These updates look good 👍

johnnewman-square · 2026-05-27T13:52:12Z

+            list.appearance = .demoAppearance
+            list.layout = .demoLayout
+            list.animation = .fast
+            list.scrollIndicatorInsets.bottom = 112.0


We could replace the hardcoded inset with an example of a calculated inset that gets the scroll indicator closer to the top edge of the footer. Though, we'd need to call updateList in viewSafeAreaInsetsDidChange() for good measure. Up to you!

Suggested change

list.scrollIndicatorInsets.bottom = 112.0

list.scrollIndicatorInsets.bottom = footer.bounds.height - view.safeAreaInsets.bottom

Good suggestion. This is more aligned with the target use case too 👍🏼

🤖 [Codex] Addressed in c27fe33. The demo now calculates the bottom scroll indicator inset from the footer height minus the safe-area bottom inset, clamps it to zero, and re-runs updateList() from viewSafeAreaInsetsDidChange().

This update is looking good!

johnnewman-square · 2026-05-27T14:03:51Z

+            list.autoScrollAction = .pin(
+                .item(targetIdentifier),
+                itemPosition: .verticalContentOffsetAdjustment { [weak self] info in
+                    self?.footerAwareScrollDelta(for: info) ?? 0.0
+                },
+                animated: false,
+                scrollInterruptionPolicy: .deferDuringUserScrolling,
+                shouldPerform: { _ in true }
+            )


I think we should explore the initial animations when the view is presented. When opening the demo, the list animates to the selected row when viewDidLayoutSubviews() calls updateList(). It would be a great enhancement if we could find a way around this issue in the demo example. Also curious if this is an issue in the production use case.

Here's a recording with slow animations, taken from an iOS 17.5 simulator.

Simulator.Screen.Recording.-.UI.Test.-.2026-05-27.at.09.53.29.mov

While investigating, I flipped animations to enabled by default in AutoScrollingViewController3 but opening that demo's controller didn't perform the same initial scroll there. I don't think this is an issue in the other demos that showcase pin and scrollTo because they don't have the viewDidLayoutSubviews pass.

I will investigate 👍🏼

🤖 [Codex] Addressed in 67ade56. The demo now suppresses animation only for the first layout-driven updateList() pass when the screen is presented. Later row changes still honor the animation toggle.

Sorry, AI missed here; let me explore addressing this workaround within the library itself.

Actually, on second though, I do think this maneuver should be done within the client app.

The new behavior looks much smoother in the demo. And having this be a client app configuration tweak sounds good.

johnnewman-square · 2026-05-27T14:05:05Z

+                itemPosition: .verticalContentOffsetAdjustment { [weak self] info in
+                    self?.footerAwareScrollDelta(for: info) ?? 0.0
+                },
+                animated: false,


A button in the navigation bar to toggle the animated flag would be a neat enhancement here, similar to some of the other autoscrolling demos.

Makes sense, I'll add.

🤖 [Codex] Addressed in 82b39ea and refined in 0eb4ab2. The demo has a navigation bar control for the auto-scroll animated flag, and the button now shows Animations: On / Animations: Off so the current state is visible while recording the demo.

Thank you for adding that flag -- it's nice to see both behaviors in the demo.

johnnewman-square

This looks good. Thanks for making those edits. There were just a couple final items of feedback that I think we could address before merging.

johnnewman-square · 2026-05-28T18:54:56Z

+    private func shouldSkipAutoScroll(_ info: _AutoScrollActionConfiguration) -> Bool {
+        guard info.scrollInterruptionPolicy == .skipDuringUserScrolling else {
+            return false
+        }
+
+        return self.isUserScrollInProgress || self.scrollPositionInfo.isScrollInProgress
+    }
+
+    private func shouldDeferAutoScroll(_ info: _AutoScrollActionConfiguration) -> Bool {
+        guard info.scrollInterruptionPolicy == .deferDuringUserScrolling else {
+            return false
+        }
+
+        return self.isUserScrollInProgress || self.scrollPositionInfo.isScrollInProgress
+    }


My agent had this final feedback:

I think using Listable’s own isUserScrollInProgress is the cleaner fix for the deferral/skip logic. Right now the PR does this:

return self.isUserScrollInProgress || self.scrollPositionInfo.isScrollInProgress

But scrollPositionInfo.isScrollInProgress includes scrollView.isTracking, so it can be true for a touch-down that never becomes a drag. That creates a pending auto-scroll even though Listable never entered its own “user scroll” lifecycle, so there may be no later delegate callback to flush it.

isUserScrollInProgress has the better lifecycle pairing:

Set true in scrollViewWillBeginDragging.

Set false and flush in scrollViewDidEndDragging when there is no deceleration.

Set false and flush in scrollViewDidEndDecelerating when there is deceleration.

That means every deferred action caused by isUserScrollInProgress == true has a corresponding end callback that should flush it. Nice and tidy.

I have verified locally that touching down on the scroll view without dragging will enter the isTracking state, but will not call those delegates when the touch down gesture ends. I think this does create a small opportunity to enter a pending autoscroll. We could remove || self.scrollPositionInfo.isScrollInProgress from both of these functions to omit the tracking case.

My agent had the same finding.

Resolve before merging

🤖 [Codex] Addressed in 370abbc. The skip/defer policies now rely only on Listable’s own isUserScrollInProgress lifecycle flag, so a touch-down tracking state that never becomes a drag will not create a pending auto-scroll with no matching flush callback. I also added focused coverage for the non-dragging path.

johnnewman-square · 2026-05-28T18:55:48Z

+            list.appearance = .demoAppearance
+            list.layout = .demoLayout
+            list.animation = .fast
+            list.scrollIndicatorInsets.bottom = 112.0


This update is looking good!

johnnewman-square · 2026-05-28T18:56:30Z

+    @discardableResult
+    public func scrollTo(
+        item : AnyIdentifier,
+        contentOffsetAdjustment : @escaping ListItemScrollPositionAdjustment,


This is okay to me. Since this closure is stored, it would be good to add a small doc around this new closure to note that clients should only use weak self.

johnnewman-square · 2026-05-28T18:57:18Z

+            list.autoScrollAction = .pin(
+                .item(targetIdentifier),
+                itemPosition: .verticalContentOffsetAdjustment { [weak self] info in
+                    self?.footerAwareScrollDelta(for: info) ?? 0.0
+                },
+                animated: false,
+                scrollInterruptionPolicy: .deferDuringUserScrolling,
+                shouldPerform: { _ in true }
+            )


The new behavior looks much smoother in the demo. And having this be a client app configuration tweak sounds good.

johnnewman-square · 2026-05-28T18:58:24Z

+                itemPosition: .verticalContentOffsetAdjustment { [weak self] info in
+                    self?.footerAwareScrollDelta(for: info) ?? 0.0
+                },
+                animated: false,


Thank you for adding that flag -- it's nice to see both behaviors in the demo.

johnnewman-square · 2026-05-28T19:00:14Z

These updates look good 👍

robmaceachern

Thanks for doing this!

robmaceachern · 2026-05-28T19:48:47Z

+    private func shouldSkipAutoScroll(_ info: _AutoScrollActionConfiguration) -> Bool {
+        guard info.scrollInterruptionPolicy == .skipDuringUserScrolling else {
+            return false
+        }
+
+        return self.isUserScrollInProgress || self.scrollPositionInfo.isScrollInProgress
+    }
+
+    private func shouldDeferAutoScroll(_ info: _AutoScrollActionConfiguration) -> Bool {
+        guard info.scrollInterruptionPolicy == .deferDuringUserScrolling else {
+            return false
+        }
+
+        return self.isUserScrollInProgress || self.scrollPositionInfo.isScrollInProgress
+    }


My agent had the same finding.

Resolve before merging

Add custom item offset scrolling

233d85a

Expose a Listable-owned item scrolling API that lets callers compute a vertical content offset adjustment without accessing the scroll view.

Add declarative custom auto-scroll positioning

228e66e

aaalaniz commented May 22, 2026

View reviewed changes

aaalaniz marked this pull request as ready for review May 22, 2026 18:42

johnnewman-square reviewed May 27, 2026

View reviewed changes

johnnewman-square requested a review from a team May 27, 2026 14:30

aaalaniz added 6 commits May 27, 2026 10:00

Fix scroll completion ordering

bd63c5a

Calculate custom auto-scroll demo indicator inset

c27fe33

Add custom auto-scroll demo animation toggle

82b39ea

Suppress initial custom auto-scroll demo animation

67ade56

Clean custom scroll test warnings

efc899c

Show custom auto-scroll animation state

0eb4ab2

johnnewman-square approved these changes May 28, 2026

View reviewed changes

robmaceachern approved these changes May 28, 2026

View reviewed changes

aaalaniz added 2 commits May 28, 2026 15:15

Document auto-scroll adjustment captures

2a62c74

Use user scroll lifecycle for auto-scroll policies

370abbc

robmaceachern enabled auto-merge (squash) May 28, 2026 20:39

robmaceachern merged commit fe74f3f into square:main May 28, 2026
6 checks passed

	list.scrollIndicatorInsets.bottom = 112.0
	list.scrollIndicatorInsets.bottom = footer.bounds.height - view.safeAreaInsets.bottom

Conversation

aaalaniz commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's changed

Example

Visuals

Test Plan

Checklist

Uh oh!

aaalaniz commented May 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

johnnewman-square left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johnnewman-square left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robmaceachern May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

aaalaniz commented May 21, 2026 •

edited

Loading

johnnewman-square left a comment •

edited

Loading

robmaceachern May 28, 2026 •

edited

Loading

robmaceachern May 28, 2026 •

edited

Loading