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

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.

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().

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.

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.

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

	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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aaalaniz commented May 21, 2026 •

edited

Loading