fix: Fix container-query driven layout oscillation caused by scrollbars

[avinashbot]

Description

Cleanest solution I could find for the issue in the ticket — make breakpoint changes "stick" or "lag" into a boundary between two breakpoints. This prevents any added scrollbars from making the breakpoint calculation unstable. Of course, this now means that adjacent breakpoints values are implicitly dependent on the current breakpoint, but only by 20px, so we're not messing up people's layouts too badly.

I use term "stickiness" in the code; I imagine it like a kind of magnet that doesn't let go until you pass a certain distance in either direction of the numerical boundary values.

-----------<-20px-|------------|-20px->------
           ^      ^            ^
           |      |            |
           |   breakpoint boundaries
           |
  breakpoint actually
    switches here

Related links, issue #, if available: AWSUI-62065

How has this been tested?

Kiro wrote me up some unit tests, but there's a dev page recreating the original ticket scenario.

Review checklist

The following items are to be evaluated by the author(s) and the reviewer(s).

Correctness

• Changes include appropriate documentation updates.
• Changes are backward-compatible if not indicated, see CONTRIBUTING.md.
• Changes do not include unsupported browser features, see CONTRIBUTING.md.
• Changes were manually tested for accessibility, see accessibility guidelines.

Security

• If the code handles URLs: all URLs are validated through the checkSafeUrl function.

Testing

• Changes are covered with new/existing unit tests?
• Changes are covered with new/existing integration tests?

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.52%. Comparing base (4eb88bc) to head (7549546).
⚠️ Report is 24 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4615      +/-   ##
==========================================
+ Coverage   97.50%   97.52%   +0.01%     
==========================================
  Files         948      948              
  Lines       30275    30364      +89     
  Branches    11039    11079      +40     
==========================================
+ Hits        29520    29611      +91     
+ Misses        748      706      -42     
- Partials        7       47      +40     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[SpyZzey]

While this is probably fine, I am wondering if we could/should calculate the width of the scrollbar. This way, the approach would also work for cases where the scrollbar is bigger than 20px. Note: As of now, all default scrollbar sizes are <= 17px (https://codepen.io/sambible/post/browser-scrollbar-widths) - but could theoretically be changed by browser extensions (or even ourselves through CSS).

[avinashbot]

I could go either way on that, I was conflicted about this.

We actually already have a utility for it (browser-scrollbar-size.ts) but the only reliable way of doing is to modify the DOM and measure the elements, which is a bit of a worrying performance trap (not something I noticed on my Macbook on a simple dev page, but breakpoint measurements are pretty foundational and used in a lot of places). Plus, having a fixed number makes it more predictable between test and real environments (for example, we don't have any testing for overlay scrollbars, even browser/screenshot tests).