fix: scrollIntoView should respect scroll-margin

[nwidynski]

Closes #8689

This PR adds scroll-margin adherence to our scrollIntoView shim. It also fixes smooth scrolling when offset is mutated bidirectionally by using native scrollTo().

✅ Pull Request Checklist:

• Included link to corresponding React Spectrum GitHub Issue.
• Added/updated unit tests and storybook for this change (for new code or code which already has tests).
• Filled out test instructions.
• Updated documentation (if it already exists for this component).
• Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

🧢 Your Project:

[snowystinger]

Thanks for the PR, could you add any storybook examples or can you describe what stories to use in testing?
I'm unsure how you tested this as you developed this.

[nwidynski]

@snowystinger Added two stories 👍

You can test for scroll-margin by simply using the keyboard to bring items into view. Additionally, try scrolling the container to the right to bring description into view, then navigate downwards with keyboard - you will notice x now remaining consistent instead of it scrolling to x=0 whenever an item is brought into view.

For smooth scroll, you can test the grid story I added. Simply place focus onto an item, scroll it out of view with mouse, then tab into the collection to restore focus - Previously it was ignored whenever x & y changed simultaneously.

PS: We should consider changing every occurence of el.scrollLeft=<value>; el.scrollTop=<value>; to el.scrollTo(), which respects smooth scroll. In RAC Virtualizer i would kindly ask to force instant behavior, more on that in the RFC.

[snowystinger]

you will notice x now remaining consistent instead of it scrolling to x=0 whenever an item is brought into view.

I'm not able to reproduce this one with that story and reverting the changes in scrollIntoView? Am I doing something wrong? Tried in both Chrome and Safari
Steps:

1. tab to listbox
2. arrow right to farthest edge
3. arrow down/end/page down, x scroll position remains constant

For smooth scroll, you can test the grid story I added. Simply place focus onto an item, scroll it out of view with mouse, then tab into the collection to restore focus - Previously it was ignored whenever x & y changed simultaneously.

I didn't notice a difference in this one either in chrome or safari?

I feel like I must be doing something wrong here.

[nwidynski]

@snowystinger This is what the scroll-margin story w/o the changes looks like for me in (OSX) Chrome, Safari and FF. For the grid, I will have to reach out to the teammate who discovered that later today - i should have tested it not working, sry.

Screen.Recording.2025-08-21.at.6.55.43.AM.mov

Edit: I think I know why the grid appears normal for you after reverting to main. You need to make sure still to include the !isChrome() condition, which is used to circumvent the scroll-margin bug - otherwise the shim is never triggered in that story. Coincidentally the x & y smooth interference when not using scrollTo() is an issue exclusive to chrome 🫠

Additionally, I just found another issue in FireFox & Safari, which do not scroll items to their proper alignment on native scrollIntoView. I've attached this demo to showcase (note they are center-ish aligned, even though they have scroll-align start). This appears to be a regression from recent changes, possibly related to #8234

Screen.Recording.2025-08-21.at.7.59.12.AM.mov