Add custom item offset scrolling

[aaalaniz]

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.

[aaalaniz]

🤖 @codex review

[aaalaniz]

The new API in action

[aaalaniz]

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

[aaalaniz]

Add coverage when user specifies to skip scroll during scroll