Skip to content

docs(scroll): add iOS 18+ onScrollGeometryChange and scrollPosition APIs - #75

Merged
AvdLee merged 4 commits into
AvdLee:mainfrom
elio-Wang:docs/ios18-scroll-patterns
Jul 24, 2026
Merged

docs(scroll): add iOS 18+ onScrollGeometryChange and scrollPosition APIs#75
AvdLee merged 4 commits into
AvdLee:mainfrom
elio-Wang:docs/ios18-scroll-patterns

Conversation

@elio-Wang

Copy link
Copy Markdown
Contributor

Add onScrollGeometryChange and scrollPosition() coverage, restructure
Scroll Position Tracking to present the modern API first, and demote
the GeometryReader + PreferenceKey approach to a legacy fallback note.

Closes #68

elio-Wang and others added 2 commits June 29, 2026 16:03
Add onScrollGeometryChange and scrollPosition() coverage, restructure
Scroll Position Tracking to present the modern API first, and demote
the GeometryReader + PreferenceKey approach to a legacy fallback note.

Closes AvdLee#68
Use the proper iOS 17 and iOS 18 scroll position overloads, clarify geometry update behavior, and consolidate duplicate examples so agents receive one accurate pattern.
@AvdLee

AvdLee commented Jul 24, 2026

Copy link
Copy Markdown
Owner

Thanks for adding these modern scroll APIs — this addresses an important gap where agents can otherwise fall back to older geometry-preference patterns.

I pushed a follow-up commit to keep that intent while correcting and tightening the guidance:

  • Changed the iOS 18 scrollPosition(_:) examples to bind a ScrollPosition, which is the type required by the unlabeled overload.
  • Added .scrollTargetLayout() for identity-based scrolling and showed position.scrollTo(id:) for programmatic navigation.
  • Added the distinct iOS 17 scrollPosition(id:) form with an optional ID binding so agents do not mix the two overloads.
  • Corrected the offset-threshold direction and accounted for the top content inset.
  • Clarified that extracting a CGFloat offset still changes every scrolling frame, while deriving a Bool limits actions to threshold crossings.
  • Fixed the header fallback so it becomes visible again when returning above the threshold.
  • Consolidated the duplicated iOS 18 sections into one source of truth and described the geometry/preference technique as pre-iOS 18 compatibility rather than a deprecated API.

I type-checked the revised iOS 17 and iOS 18 API examples against the respective simulator SDK targets. Both compile successfully.

AvdLee added 2 commits July 24, 2026 08:45
Make the modern API decision path visible before examples, remove duplicate threshold guidance, and improve scroll reference routing for agents.
Resolve the topic router conflict by preserving the expanded scroll guidance alongside the new focus reference.
@AvdLee
AvdLee merged commit 7477136 into AvdLee:main Jul 24, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add iOS 18+ scroll APIs to scroll-patterns.md (onScrollGeometryChange, scrollPosition)

2 participants