scroll: Bounce scrollable content like NSScrollView, by default on macOS

[shreeve]

Description

Scrollable content now bounces at its ends the way NSScrollView does, and on macOS it does so by default, as native scroll views do. Bounce comes from one shared overscroll engine and one wrapper, ScrollBounce. It covers multiline inputs, List, DataTable, Tree, Scrollable, Select, Command, Sidebar, Diff, MessageScroller, the settings page and scrollable TextView. Logical scroll positions stay clamped. Content moves inside its clip, while input frames, table headers, search fields, footers and scrollbars stay fixed.

Bounce depends on how precise the scroll input is, not on the device name:

• Trackpads and Magic Mouse send precise pixel scrolling (ScrollDelta::Pixels). It bounces.
• Ordinary mouse wheels send line scrolling (ScrollDelta::Lines). It only scrolls, and cancels any bounce in progress.

One default, one rule for nested areas

• Default. ScrollBounce::enabled_by_default() is the only place the default is decided. It is on for iOS, Android and macOS, the platforms whose own scroll views bounce, and off elsewhere. Components keep their scroll_bounce(bool) builder as an override; when it is not set, they defer to ScrollBounce. Inputs use the same default.
• Nested areas. These follow the platform. The innermost area under the pointer takes the whole gesture, including at its ends: it bounces there rather than handing the rest of the gesture to the area around it.
  • How it works. Each area claims the wheel event in the capture phase, before its children paint, so the innermost claim is the one that stands. Only that area then acts. Text inputs take part through the same claim.
  • Disabled areas. An area whose bounce is disabled still scrolls its own child and keeps the gesture; it just stops at its ends.
  • Effect on GPUI divs. Until now, nested GPUI scroll divs scrolled together.
• Popup menus. These do not bounce, matching macOS menus.

Matching NSScrollView

The desktop motion is fitted to a native NSScrollView, measured on macOS by driving it with synthesized trackpad events, and cross-checked against AppKit's own rubber-band functions:

	NSScrollView	This PR
Stretch for 100 px of travel past the end (300 px viewport)	7 px	7 px
Largest stretch, by drag or fling	36 px in Finder	36 px, eased into
Release held still: time to halve	55 ms, moving at once	55 ms
Fling into the edge at 1500 px/s: peak	≈14 px, ≈80 ms after impact	≈14 px, ≈80 ms

• Stretch. It follows AppKit's hyperbolic curve (coefficient 0.075). AppKit stretches by unaccelerated travel, which GPUI does not report, so a hard swipe would run far past native. ScrollBounceMotion therefore gains a maximum stretch, 36 px by default on desktop. The stretch eases into it, and a fling never throws the edge past it.
• Return. A released or struck edge follows (x + 0.31·v·t)·e^(-12.5t), using the same constants as AppKit's _NSElasticDeltaForTimeDelta. A fling throws the edge once per gesture, and momentum back into the content scrolls it while the edge returns.
• Fling speed. It is read over the last 50 ms. Scroll packets carry no timestamp, so a slow frame hands over several at once. Read one by one, a fling through a long list hit the top about 4× too hard.
• Touch and lift. GPUI reports MayBegin as Started, and a cancelled touch as a Moved of nothing. A touch that lifts without moving now lets go of a held edge.

iOS and Android keep the UIScrollView tuning (0.55, 524 ms, no maximum). Reduced motion disables displacement. Component documentation is synchronized in English and Chinese.

Public API

gpui-base

• pub const fn ScrollBounce::enabled_by_default() -> bool: whether scroll areas bounce unless told otherwise. True on iOS, Android and macOS.
• pub fn ScrollBounce::scroll_wheel(self, enabled: bool) -> Self: chooses whether the wrapper owns vertical wheel scrolling through the shared engine. Defaults to true. Pass false for the child-owned touch mode.
• pub fn ScrollBounceMotion::with_max_stretch(self, max_stretch: f32) -> Self: the farthest the edge goes past its end, whether stretched or thrown.
• pub fn ScrollBounceMotion::max_stretch(&self) -> Option<f32>: reads it back.
• impl Default for ScrollBounceMotion: now depends on the platform. Unchanged on iOS and Android. Elsewhere it is fitted to NSScrollView: tracking 0.075, response ≈503 ms, max_stretch 36 px.
• pub fn InputBaseState<M: MultiLineMode>::scroll_bounce(self, scroll_bounce: bool) -> Self: precise-scroll boundary bounce for TextareaState and EditorState.
• pub fn InputBaseState<M: MultiLineMode>::set_scroll_bounce(&mut self, scroll_bounce: bool, cx: &mut Context<Self>): changes the setting at runtime.

gpui-component

Each of these overrides the platform default for that component:

• pub fn List<D: ListDelegate>::scroll_bounce(self, enabled: bool) -> Self
• pub fn DataTable<D: TableDelegate>::scroll_bounce(self, enabled: bool) -> Self: headers and scrollbars stay fixed.
• pub fn Tree::scroll_bounce(self, enabled: bool) -> Self
• pub fn Scrollable<E>::scroll_bounce(self, enabled: bool) -> Self
• pub fn Select<D>::scroll_bounce(self, enabled: bool) -> Self
• pub fn Command::scroll_bounce(self, enabled: bool) -> Self: the search field and footer stay fixed.

Breaking Changes

No existing signature changes. Every existing call still compiles. Four defaults change behavior, compared with main:

1. ScrollBounce is enabled by default on macOS. On main it was enabled only on iOS and Android. A ScrollBounce created without .enabled(..) now bounces on macOS too. To keep it still:

- ScrollBounce::new(id, &handle, child)
+ ScrollBounce::new(id, &handle, child).enabled(false)

2. ScrollBounce owns vertical wheel scrolling by default. On main, the child scrolled itself and the wrapper only stretched the deltas the child left unused. Now the wrapper scrolls the handle itself, through the shared engine. Code that relied on the child-owned mode, such as touch emulation or synthesized drags, must ask for it:

- ScrollBounce::new(id, &handle, child).enabled(true)
+ ScrollBounce::new(id, &handle, child).enabled(true).scroll_wheel(false)

3. ScrollBounceMotion::default() changes on macOS, Windows and Linux. The defaults are now tuned to match NSScrollView, replacing the UIScrollView tuning:

• tracking goes from 0.55 to 0.075.
• response goes from 524 ms to ≈503 ms.
• The stretch is capped at 36 px.

iOS and Android are unchanged. To keep the previous feel:

- ScrollBounce::new(id, &handle, child)
+ ScrollBounce::new(id, &handle, child).motion(
+     ScrollBounceMotion::default()
+         .with_tracking(0.55)
+         .with_response(Duration::from_millis(524)),
+ )

4. Scrollable components scroll differently.

• They bounce on macOS. Scrollable (overflow_y_scrollbar()), List, DataTable, Tree, Select, Command, Textarea, Editor, Sidebar, Diff, MessageScroller, the settings page and scrollable TextView now bounce on precise scrolling. On main none of them did. Each one that has a builder can turn it off:

  - List::new(&state)
  + List::new(&state).scroll_bounce(false)

• Nested areas no longer scroll together, on every platform. The innermost area under the pointer takes the whole gesture, including at its ends. On main:

  • Nested GPUI scroll divs scrolled together.
  • MessageScroller handed the wheel to an ancestor scroller once it reached an end.

  Neither happens now. Sidebar, Diff, MessageScroller, the settings page and TextView have no scroll_bounce builder; they always follow the platform default.

Everything else listed under Public API is new in this PR, and so additive.

Validation

• cargo test -p gpui-base -p gpui-component --lib passes (1361 + 670). The tests include:
  • Tests pinned to the NSScrollView measurements: stretch, the 36 px limit, still release, fling peak and single throw, reverse momentum without a jump.
  • A fling whose packets arrive in a burst after slow frames.
  • A touch that lifts without moving.
  • Nested areas, where the inner one takes the gesture whether it is enabled or disabled, and a textarea inside a bouncing area.
  • Bounce interruption, ordinary-wheel exclusion, fixed input/scrollbar geometry, real List/DataTable scrolling and fixed table headers.
• The CI test command (cargo test --workspace --exclude gpui-shell --features gpui-component-story/test-support with the example crates excluded), cargo test -p gpui-base-examples, cargo clippy with --deny warnings, cargo fmt --check, typos and script/check-ai pass.
• The stretch and return match AppKit's _NSHyperbolicElasticDeltaForReboundDelta and _NSElasticDeltaForTimeDelta, called directly. The maximum stretch follows a measurement in Finder.
• Checked in the Story Gallery with a physical trackpad: list and command palette edges, top and bottom.

AI assistance

The original Input bounce implementation was AI-assisted with Claude Code. Codex assisted with the shared engine, review corrections, component integration, regression tests, and synchronized feature documentation. Claude Code measured NSScrollView, refitted the motion, fixed the momentum and release behavior, made bounce the macOS default with one nesting rule, and added Select, Command, Sidebar, Diff, MessageScroller, settings page and TextView support.

🤖 Generated with Claude Code

[shreeve]

Looks great!!! Thanks Jason!