Skip to main content

gpui_base/
scrollable_mask.rs

1use std::cell::RefCell;
2use std::rc::Rc;
3
4use gpui::{
5    App, AppContext as _, Axis, BorderStyle, Bounds, ContentMask, Edges, Element, ElementId,
6    GlobalElementId, Hitbox, Hsla, InteractiveElement as _, IntoElement, IsZero as _, LayoutId,
7    OngoingScroll, ParentElement as _, Point, Position, ScrollHandle, ScrollWheelEvent,
8    StatefulInteractiveElement as _, Style, StyleRefinement, Styled as _, Window, div, px,
9    relative,
10};
11use gpui::{Corners, Pixels};
12
13use crate::{AxisExt, OngoingScrollExt as _, ScrollbarHandle};
14
15/// Default element id for a mask: the call site, so two masks built in
16/// different places never share their per-gesture axis lock.
17#[inline]
18#[track_caller]
19fn caller_id() -> ElementId {
20    ElementId::CodeLocation(*std::panic::Location::caller())
21}
22
23/// A horizontal scroll viewport that only consumes horizontal wheel deltas.
24///
25/// GPUI's native `overflow_x_scroll` maps vertical wheel input onto horizontal
26/// scrolling when there is no vertical overflow. This wrapper keeps the visual
27/// clipping and scroll offset, while delegating wheel input to [`ScrollableMask`]
28/// so vertical wheel events can continue bubbling to the parent scroller.
29pub(crate) fn horizontal_scroll_area(
30    id: impl Into<ElementId>,
31    scroll_handle: &ScrollHandle,
32    style: &StyleRefinement,
33    child: impl IntoElement,
34) -> impl IntoElement {
35    let id = id.into();
36
37    // The mask must be a sibling of the scrolled element (like in Table), not
38    // a child of it: children are prepainted with the scroll offset applied,
39    // which would slide the mask away from the viewport as the content
40    // scrolls, leaving the uncovered part to the parent scroller.
41    div()
42        .w_full()
43        .relative()
44        .child(
45            div()
46                .id(id.clone())
47                .w_full()
48                .refine_style(style)
49                .overflow_hidden()
50                .track_scroll(scroll_handle)
51                .child(child),
52        )
53        .child(ScrollableMask::new(Axis::Horizontal, scroll_handle).id(id))
54}
55
56/// Make a scrollable mask element to cover the parent view with the mouse wheel event listening.
57///
58/// When the mouse wheel is scrolled, will move the `scroll_handle` scrolling with the `axis` direction.
59/// You can use this `scroll_handle` to control what you want to scroll.
60/// This is only can handle once axis scrolling.
61///
62/// Axis-dominant wheel events are consumed in the capture phase, so the mask
63/// wins over ancestor scrollers (e.g. `gpui::list`) that register their
64/// listeners after their children; events dominated by the other axis keep
65/// propagating. The mask stays inert while occluded.
66///
67/// Dominance is decided per gesture, not per event: a precise (trackpad) delta
68/// locks onto the axis its gesture started on, so mid-swipe wobble cannot flip
69/// which mask consumes the events. Line deltas keep the per-event comparison.
70///
71/// At the scroll edge the two axes differ, matching platform scrollers:
72/// a vertical mask hands the event over to the ancestor scroller (CSS
73/// `overscroll-behavior: auto` chaining), while a horizontal mask keeps
74/// consuming it — a bubbled horizontal delta would get mapped onto a
75/// vertical-only ancestor by gpui's own wheel listener (see #2468).
76pub struct ScrollableMask<H: ScrollbarHandle + Clone = ScrollHandle> {
77    axis: Axis,
78    id: ElementId,
79    scroll_handle: H,
80    debug: Option<Hsla>,
81}
82
83impl<H: ScrollbarHandle + Clone> ScrollableMask<H> {
84    /// Create a new scrollable mask element.
85    #[track_caller]
86    pub fn new(axis: Axis, scroll_handle: &H) -> Self {
87        Self {
88            scroll_handle: scroll_handle.clone(),
89            axis,
90            id: caller_id(),
91            debug: None,
92        }
93    }
94
95    /// Set a specific element id, default is the [`std::panic::Location::caller`].
96    ///
97    /// Only needed when one call site creates several masks of the same axis,
98    /// which would otherwise share their gesture axis lock.
99    pub fn id(mut self, id: impl Into<ElementId>) -> Self {
100        self.id = id.into();
101        self
102    }
103
104    /// Enable the debug border, to show the mask bounds.
105    #[allow(dead_code)]
106    pub fn debug(mut self) -> Self {
107        self.debug = Some(gpui::yellow());
108        self
109    }
110}
111
112impl<H: ScrollbarHandle + Clone> IntoElement for ScrollableMask<H> {
113    type Element = Self;
114
115    fn into_element(self) -> Self::Element {
116        self
117    }
118}
119
120impl<H: ScrollbarHandle + Clone> Element for ScrollableMask<H> {
121    type RequestLayoutState = ();
122    type PrepaintState = Hitbox;
123
124    // An id is needed to keep the gesture's axis lock across frames. The axis
125    // suffix keeps both masks of one scroller apart when they share an id.
126    fn id(&self) -> Option<ElementId> {
127        let axis = match self.axis {
128            Axis::Horizontal => "horizontal",
129            Axis::Vertical => "vertical",
130        };
131
132        Some((self.id.clone(), axis).into())
133    }
134
135    fn source_location(&self) -> Option<&'static std::panic::Location<'static>> {
136        None
137    }
138
139    fn request_layout(
140        &mut self,
141        _: Option<&GlobalElementId>,
142        _: Option<&gpui::InspectorElementId>,
143        window: &mut Window,
144        cx: &mut App,
145    ) -> (LayoutId, Self::RequestLayoutState) {
146        let mut style = Style::default();
147        // Set the layout style relative to the table view to get same size.
148        style.position = Position::Absolute;
149        style.flex_grow = 1.0;
150        style.flex_shrink = 1.0;
151        style.size.width = relative(1.).into();
152        style.size.height = relative(1.).into();
153
154        (window.request_layout(style, None, cx), ())
155    }
156
157    fn prepaint(
158        &mut self,
159        _: Option<&GlobalElementId>,
160        _: Option<&gpui::InspectorElementId>,
161        bounds: Bounds<Pixels>,
162        _: &mut Self::RequestLayoutState,
163        window: &mut Window,
164        _: &mut App,
165    ) -> Self::PrepaintState {
166        // Move y to bounds height to cover the parent view.
167        let cover_bounds = Bounds {
168            origin: Point {
169                x: bounds.origin.x,
170                y: bounds.origin.y - bounds.size.height,
171            },
172            size: bounds.size,
173        };
174
175        window.insert_hitbox(cover_bounds, gpui::HitboxBehavior::Normal)
176    }
177
178    fn paint(
179        &mut self,
180        global_id: Option<&GlobalElementId>,
181        _: Option<&gpui::InspectorElementId>,
182        _: Bounds<Pixels>,
183        _: &mut Self::RequestLayoutState,
184        hitbox: &mut Self::PrepaintState,
185        window: &mut Window,
186        _: &mut App,
187    ) {
188        let is_horizontal = self.axis.is_horizontal();
189        let line_height = window.line_height();
190        let bounds = hitbox.bounds;
191        let ongoing_scroll = global_id
192            .map(|global_id| {
193                window.with_element_state::<Rc<RefCell<OngoingScroll>>, _>(global_id, |state, _| {
194                    let state = state.unwrap_or_default();
195                    (state.clone(), state)
196                })
197            })
198            .unwrap_or_default();
199
200        let mask = ContentMask {
201            bounds,
202            fade_out: Default::default(),
203        };
204        window.with_content_mask(Some(mask), |window| {
205            if let Some(color) = self.debug {
206                window.paint_quad(
207                    gpui::PaintQuad::new(bounds)
208                        .border_widths(Edges::all(px(1.0)))
209                        .border_color(color)
210                        .background(gpui::transparent_white())
211                        .corner_radii(Corners::all(px(0.)))
212                        .border_style(BorderStyle::default()),
213                );
214            }
215
216            window.on_mouse_event({
217                let view_id = window.current_view();
218                let scroll_handle = self.scroll_handle.clone();
219                let hitbox_id = hitbox.id;
220                let ongoing_scroll = ongoing_scroll.clone();
221
222                move |event: &ScrollWheelEvent, phase, window, cx| {
223                    // Handle in the capture phase: ancestor scrollers such as
224                    // `gpui::list` register their wheel listeners after their
225                    // children paint, so in the bubble phase (reverse
226                    // registration order) they run first and would consume the
227                    // vertical component of a trackpad swipe before this mask
228                    // could stop the propagation.
229                    //
230                    // `should_handle_scroll` (instead of a raw bounds check)
231                    // keeps the mask inert when it is occluded, e.g. below an
232                    // open dialog or context menu.
233                    if !(phase.capture() && hitbox_id.should_handle_scroll(window)) {
234                        return;
235                    }
236
237                    let mut offset = scroll_handle.offset();
238                    let mut delta = event.delta.pixel_delta(line_height);
239
240                    // Lock the gesture to the axis it started on, so a diagonal
241                    // trackpad swipe cannot flip which mask consumes it from one
242                    // event to the next. Line deltas carry no touch phase.
243                    if event.delta.precise() {
244                        ongoing_scroll
245                            .borrow_mut()
246                            .lock_axis(&mut delta, event.touch_phase);
247                    }
248
249                    // Limit for only one way scrolling at same time.
250                    // When use MacBook touchpad we may get both x and y delta,
251                    // only allows the one that more to scroll.
252                    if !delta.x.is_zero() && !delta.y.is_zero() {
253                        if delta.x.abs() > delta.y.abs() {
254                            delta.y = px(0.);
255                        } else {
256                            delta.x = px(0.);
257                        }
258                    }
259
260                    if !is_horizontal {
261                        // The current offset must be clamped too: after a
262                        // bubbled event, the scrolled element's own listener
263                        // pushes the shared offset beyond the edge unclamped
264                        // (the div only clamps on prepaint), and that
265                        // transient overscroll would read as "room to scroll".
266                        // `ScrollbarHandle` has no `max_offset`; recover it from
267                        // the definition `content_size = viewport + max_offset`.
268                        let axis_max = (scroll_handle.content_size().height
269                            - scroll_handle.viewport_bounds().size.height)
270                            .max(px(0.));
271                        let current = offset.y.clamp(-axis_max, px(0.));
272                        let new_offset = (current + delta.y).clamp(-axis_max, px(0.));
273                        if new_offset == current {
274                            // At the edge or no overflow: bubble to the parent.
275                            return;
276                        }
277
278                        offset.y = new_offset;
279                        scroll_handle.set_offset(offset);
280                        cx.notify(view_id);
281                        cx.stop_propagation();
282                        return;
283                    }
284
285                    offset.x += delta.x;
286
287                    // NOTE: `set_offset` does not clamp (clamping happens in
288                    // the div's prepaint), so any non-zero horizontal-dominant
289                    // delta passes this guard — even at the scroll edge the
290                    // event is consumed rather than turned into a parent
291                    // scroll.
292                    if offset != scroll_handle.offset() {
293                        scroll_handle.set_offset(offset);
294                        cx.notify(view_id);
295                        cx.stop_propagation();
296                    }
297                }
298            });
299        });
300    }
301}
302
303#[cfg(test)]
304mod tests {
305    use super::*;
306    use gpui::{
307        Context, IntoElement, ListAlignment, ListState, Render, ScrollDelta, ScrollWheelEvent,
308        TestAppContext, VisualTestContext, Window, div, list, point, px,
309    };
310
311    struct HorizontalScrollAreaTest {
312        scroll_handle: ScrollHandle,
313    }
314
315    impl Render for HorizontalScrollAreaTest {
316        fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
317            div().w(px(100.)).h(px(40.)).child(horizontal_scroll_area(
318                "horizontal-scroll-area",
319                &self.scroll_handle,
320                &Default::default(),
321                div().w(px(300.)).h(px(40.)),
322            ))
323        }
324    }
325
326    #[gpui::test]
327    fn horizontal_scroll_area_ignores_vertical_wheel(cx: &mut TestAppContext) {
328        let scroll_handle = ScrollHandle::new();
329        let (_, cx) = cx.add_window_view({
330            let scroll_handle = scroll_handle.clone();
331            move |_, _| HorizontalScrollAreaTest {
332                scroll_handle: scroll_handle.clone(),
333            }
334        });
335        let cx: &mut VisualTestContext = cx;
336        cx.run_until_parked();
337        cx.update(|window, cx| {
338            _ = window.draw(cx);
339        });
340
341        cx.simulate_event(ScrollWheelEvent {
342            position: point(px(10.), px(10.)),
343            delta: ScrollDelta::Pixels(point(px(0.), px(-40.))),
344            ..Default::default()
345        });
346
347        assert_eq!(scroll_handle.offset().x, px(0.));
348    }
349
350    /// Reproduces the markdown table case: the scroll area lives inside a
351    /// `gpui::list` item. The list registers its wheel listener after its
352    /// items paint, so in the bubble phase (reverse registration order) the
353    /// list runs first and consumes `delta.y` of every trackpad swipe.
354    struct ListWithHorizontalAreaTest {
355        scroll_handle: ScrollHandle,
356        list_state: ListState,
357        occluded: bool,
358    }
359
360    impl Render for ListWithHorizontalAreaTest {
361        fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
362            let scroll_handle = self.scroll_handle.clone();
363            let mut root = div().w(px(100.)).h(px(100.)).child(
364                list(self.list_state.clone(), move |ix, _, _| {
365                    if ix == 0 {
366                        horizontal_scroll_area(
367                            "horizontal-scroll-area",
368                            &scroll_handle,
369                            &Default::default(),
370                            div().w(px(300.)).h(px(40.)),
371                        )
372                        .into_any_element()
373                    } else {
374                        div().w(px(100.)).h(px(40.)).into_any_element()
375                    }
376                })
377                .w_full()
378                .h_full(),
379            );
380            if self.occluded {
381                // An overlay above the list, like an open dialog or menu.
382                root = root.child(div().absolute().top_0().left_0().size_full().occlude());
383            }
384            root
385        }
386    }
387
388    fn setup_list_test<'a>(
389        cx: &'a mut TestAppContext,
390        scroll_handle: &ScrollHandle,
391        list_state: &ListState,
392        occluded: bool,
393    ) -> &'a mut VisualTestContext {
394        let (_, cx) = cx.add_window_view({
395            let scroll_handle = scroll_handle.clone();
396            let list_state = list_state.clone();
397            move |_, _| ListWithHorizontalAreaTest {
398                scroll_handle: scroll_handle.clone(),
399                list_state: list_state.clone(),
400                occluded,
401            }
402        });
403        cx.run_until_parked();
404        cx.update(|window, cx| {
405            _ = window.draw(cx);
406        });
407        cx
408    }
409
410    #[gpui::test]
411    fn horizontal_scroll_area_in_list_keeps_horizontal_dominant_wheel(cx: &mut TestAppContext) {
412        let scroll_handle = ScrollHandle::new();
413        let list_state = ListState::new(10, ListAlignment::Top, px(0.));
414        let cx = setup_list_test(cx, &scroll_handle, &list_state, false);
415
416        // A trackpad swipe is rarely axis-pure: horizontal dominant with a
417        // small vertical component.
418        cx.simulate_event(ScrollWheelEvent {
419            position: point(px(10.), px(10.)),
420            delta: ScrollDelta::Pixels(point(px(-40.), px(-10.))),
421            ..Default::default()
422        });
423
424        // The area consumes the horizontal delta...
425        assert_eq!(scroll_handle.offset().x, px(-40.));
426        // ...and the outer list must not scroll vertically.
427        let scroll_top = list_state.logical_scroll_top();
428        assert_eq!((scroll_top.item_ix, scroll_top.offset_in_item), (0, px(0.)));
429    }
430
431    #[gpui::test]
432    fn horizontal_scroll_area_in_list_bubbles_vertical_dominant_wheel(cx: &mut TestAppContext) {
433        let scroll_handle = ScrollHandle::new();
434        let list_state = ListState::new(10, ListAlignment::Top, px(0.));
435        let cx = setup_list_test(cx, &scroll_handle, &list_state, false);
436
437        cx.simulate_event(ScrollWheelEvent {
438            position: point(px(10.), px(10.)),
439            delta: ScrollDelta::Pixels(point(px(-10.), px(-40.))),
440            ..Default::default()
441        });
442
443        // Vertical dominant: the list scrolls, the area does not.
444        assert_eq!(scroll_handle.offset().x, px(0.));
445        let scroll_top = list_state.logical_scroll_top();
446        assert_ne!((scroll_top.item_ix, scroll_top.offset_in_item), (0, px(0.)));
447    }
448
449    /// A `MessageScroller`-shaped nesting: a `gpui::list` with a vertical
450    /// mask bound to its `ListState`, inside an ancestor vertical scroller.
451    struct ListWithVerticalMaskTest {
452        outer_handle: ScrollHandle,
453        list_state: ListState,
454    }
455
456    impl Render for ListWithVerticalMaskTest {
457        fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
458            div()
459                .id("outer")
460                .w(px(100.))
461                .h(px(100.))
462                .overflow_y_scroll()
463                .track_scroll(&self.outer_handle)
464                .child(
465                    div().w_full().h(px(400.)).child(
466                        div()
467                            .relative()
468                            .w_full()
469                            .h(px(80.))
470                            .overflow_hidden()
471                            .child(
472                                list(self.list_state.clone(), |_, _, _| {
473                                    div().w_full().h(px(40.)).into_any_element()
474                                })
475                                .w_full()
476                                .h_full(),
477                            )
478                            .child(ScrollableMask::new(Axis::Vertical, &self.list_state)),
479                    ),
480                )
481        }
482    }
483
484    fn setup_vertical_mask_test<'a>(
485        cx: &'a mut TestAppContext,
486        outer_handle: &ScrollHandle,
487        list_state: &ListState,
488    ) -> &'a mut VisualTestContext {
489        let (_, cx) = cx.add_window_view({
490            let outer_handle = outer_handle.clone();
491            let list_state = list_state.clone();
492            move |_, _| ListWithVerticalMaskTest {
493                outer_handle: outer_handle.clone(),
494                list_state: list_state.clone(),
495            }
496        });
497        cx.run_until_parked();
498        cx.update(|window, cx| {
499            _ = window.draw(cx);
500        });
501        cx
502    }
503
504    #[gpui::test]
505    fn vertical_mask_contains_wheel_inside_the_list(cx: &mut TestAppContext) {
506        let outer_handle = ScrollHandle::new();
507        // A large overdraw measures every row up front, so the mask sees the
508        // full content height.
509        let list_state = ListState::new(10, ListAlignment::Top, px(1000.));
510        let cx = setup_vertical_mask_test(cx, &outer_handle, &list_state);
511
512        cx.simulate_event(ScrollWheelEvent {
513            position: point(px(10.), px(10.)),
514            delta: ScrollDelta::Pixels(point(px(0.), px(-40.))),
515            ..Default::default()
516        });
517
518        // The inner list consumes the wheel; the ancestor must not move.
519        assert_eq!(list_state.scroll_px_offset_for_scrollbar().y, px(-40.));
520        assert_eq!(outer_handle.offset().y, px(0.));
521    }
522
523    #[gpui::test]
524    fn vertical_mask_chains_to_the_ancestor_at_the_edge(cx: &mut TestAppContext) {
525        let outer_handle = ScrollHandle::new();
526        let list_state = ListState::new(10, ListAlignment::Top, px(1000.));
527        // Start the inner list at its bottom edge (400 - 80 = 320).
528        list_state.scroll_to(gpui::ListOffset {
529            item_ix: 8,
530            offset_in_item: px(0.),
531        });
532        let cx = setup_vertical_mask_test(cx, &outer_handle, &list_state);
533
534        cx.simulate_event(ScrollWheelEvent {
535            position: point(px(10.), px(10.)),
536            delta: ScrollDelta::Pixels(point(px(0.), px(-40.))),
537            ..Default::default()
538        });
539
540        // At the edge the mask lets the event bubble to the ancestor.
541        assert_eq!(list_state.scroll_px_offset_for_scrollbar().y, px(-320.));
542        assert_eq!(outer_handle.offset().y, px(-40.));
543    }
544
545    #[gpui::test]
546    fn horizontal_scroll_area_covers_viewport_after_scrolled(cx: &mut TestAppContext) {
547        let scroll_handle = ScrollHandle::new();
548        let list_state = ListState::new(10, ListAlignment::Top, px(0.));
549        let cx = setup_list_test(cx, &scroll_handle, &list_state, false);
550
551        // Scroll the area to the middle, then repaint.
552        scroll_handle.set_offset(point(px(-150.), px(0.)));
553        cx.update(|window, cx| {
554            _ = window.draw(cx);
555        });
556
557        // Swipe over the right side of the viewport. The mask must still
558        // cover it — it must not slide away with the scrolled content.
559        cx.simulate_event(ScrollWheelEvent {
560            position: point(px(90.), px(10.)),
561            delta: ScrollDelta::Pixels(point(px(-40.), px(-10.))),
562            ..Default::default()
563        });
564
565        assert_eq!(scroll_handle.offset().x, px(-190.));
566        let scroll_top = list_state.logical_scroll_top();
567        assert_eq!((scroll_top.item_ix, scroll_top.offset_in_item), (0, px(0.)));
568    }
569
570    #[gpui::test]
571    fn horizontal_scroll_area_traps_wheel_at_edge(cx: &mut TestAppContext) {
572        let scroll_handle = ScrollHandle::new();
573        let list_state = ListState::new(10, ListAlignment::Top, px(0.));
574        let cx = setup_list_test(cx, &scroll_handle, &list_state, false);
575
576        // Scroll the area to its right edge (300 - 100 = 200).
577        scroll_handle.set_offset(point(px(-200.), px(0.)));
578        cx.update(|window, cx| {
579            _ = window.draw(cx);
580        });
581
582        cx.simulate_event(ScrollWheelEvent {
583            position: point(px(10.), px(10.)),
584            delta: ScrollDelta::Pixels(point(px(-40.), px(-10.))),
585            ..Default::default()
586        });
587
588        // A horizontal mask consumes even at the edge: a bubbled horizontal
589        // delta would be axis-mapped onto the vertical list (#2468).
590        let scroll_top = list_state.logical_scroll_top();
591        assert_eq!((scroll_top.item_ix, scroll_top.offset_in_item), (0, px(0.)));
592    }
593
594    #[gpui::test]
595    fn horizontal_scroll_area_ignores_wheel_when_occluded(cx: &mut TestAppContext) {
596        let scroll_handle = ScrollHandle::new();
597        let list_state = ListState::new(10, ListAlignment::Top, px(0.));
598        let cx = setup_list_test(cx, &scroll_handle, &list_state, true);
599
600        cx.simulate_event(ScrollWheelEvent {
601            position: point(px(10.), px(10.)),
602            delta: ScrollDelta::Pixels(point(px(-40.), px(-10.))),
603            ..Default::default()
604        });
605
606        // An overlay (dialog, context menu) occludes the area: the area
607        // must not scroll underneath it.
608        assert_eq!(scroll_handle.offset().x, px(0.));
609    }
610
611    #[gpui::test]
612    fn horizontal_scroll_area_uses_horizontal_wheel(cx: &mut TestAppContext) {
613        let scroll_handle = ScrollHandle::new();
614        let (_, cx) = cx.add_window_view({
615            let scroll_handle = scroll_handle.clone();
616            move |_, _| HorizontalScrollAreaTest {
617                scroll_handle: scroll_handle.clone(),
618            }
619        });
620        let cx: &mut VisualTestContext = cx;
621        cx.run_until_parked();
622        cx.update(|window, cx| {
623            _ = window.draw(cx);
624        });
625
626        cx.simulate_event(ScrollWheelEvent {
627            position: point(px(10.), px(10.)),
628            delta: ScrollDelta::Pixels(point(px(-40.), px(0.))),
629            ..Default::default()
630        });
631
632        assert_eq!(scroll_handle.offset().x, px(-40.));
633    }
634
635    fn setup_horizontal_area_test<'a>(
636        cx: &'a mut TestAppContext,
637        scroll_handle: &ScrollHandle,
638    ) -> &'a mut VisualTestContext {
639        let (_, cx) = cx.add_window_view({
640            let scroll_handle = scroll_handle.clone();
641            move |_, _| HorizontalScrollAreaTest {
642                scroll_handle: scroll_handle.clone(),
643            }
644        });
645        let cx: &mut VisualTestContext = cx;
646        cx.run_until_parked();
647        cx.update(|window, cx| {
648            _ = window.draw(cx);
649        });
650        cx
651    }
652
653    #[gpui::test]
654    fn horizontal_mask_keeps_axis_lock_within_a_gesture(cx: &mut TestAppContext) {
655        let scroll_handle = ScrollHandle::new();
656        let cx = setup_horizontal_area_test(cx, &scroll_handle);
657
658        cx.simulate_event(ScrollWheelEvent {
659            position: point(px(10.), px(10.)),
660            delta: ScrollDelta::Pixels(point(px(-40.), px(-10.))),
661            ..Default::default()
662        });
663        assert_eq!(scroll_handle.offset().x, px(-40.));
664
665        // Same gesture, now leaning vertical but under the unlock ratio: the
666        // lock holds and the horizontal offset keeps moving. Comparing this
667        // event alone would zero `delta.x` and stall the scroller at -40.
668        cx.simulate_event(ScrollWheelEvent {
669            position: point(px(10.), px(10.)),
670            delta: ScrollDelta::Pixels(point(px(-10.), px(-15.))),
671            ..Default::default()
672        });
673        assert_eq!(scroll_handle.offset().x, px(-50.));
674    }
675
676    #[gpui::test]
677    fn horizontal_mask_releases_axis_lock_on_a_strong_turn(cx: &mut TestAppContext) {
678        let scroll_handle = ScrollHandle::new();
679        let cx = setup_horizontal_area_test(cx, &scroll_handle);
680
681        cx.simulate_event(ScrollWheelEvent {
682            position: point(px(10.), px(10.)),
683            delta: ScrollDelta::Pixels(point(px(-40.), px(-10.))),
684            ..Default::default()
685        });
686        assert_eq!(scroll_handle.offset().x, px(-40.));
687
688        // Past the unlock ratio the gesture is no longer horizontal, so the
689        // event stops driving this scroller.
690        cx.simulate_event(ScrollWheelEvent {
691            position: point(px(10.), px(10.)),
692            delta: ScrollDelta::Pixels(point(px(-10.), px(-25.))),
693            ..Default::default()
694        });
695        assert_eq!(scroll_handle.offset().x, px(-40.));
696    }
697
698    /// Reproduces the DataTable case: a vertically scrollable element
699    /// nested inside an outer vertical scroller.
700    struct NestedVerticalScrollTest {
701        outer_handle: ScrollHandle,
702        inner_handle: ScrollHandle,
703        inner_content_height: Pixels,
704    }
705
706    impl Render for NestedVerticalScrollTest {
707        fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
708            div()
709                .id("outer")
710                .w(px(100.))
711                .h(px(100.))
712                .overflow_y_scroll()
713                .track_scroll(&self.outer_handle)
714                .child(
715                    div()
716                        .relative()
717                        .w_full()
718                        .h(px(60.))
719                        .child(
720                            div()
721                                .id("inner")
722                                .size_full()
723                                .overflow_y_scroll()
724                                .track_scroll(&self.inner_handle)
725                                .child(div().w_full().h(self.inner_content_height)),
726                        )
727                        .child(ScrollableMask::new(Axis::Vertical, &self.inner_handle)),
728                )
729                .child(div().w_full().h(px(400.)))
730        }
731    }
732
733    fn setup_nested_vertical_test<'a>(
734        cx: &'a mut TestAppContext,
735        outer_handle: &ScrollHandle,
736        inner_handle: &ScrollHandle,
737        inner_content_height: Pixels,
738    ) -> &'a mut VisualTestContext {
739        let (_, cx) = cx.add_window_view({
740            let outer_handle = outer_handle.clone();
741            let inner_handle = inner_handle.clone();
742            move |_, _| NestedVerticalScrollTest {
743                outer_handle: outer_handle.clone(),
744                inner_handle: inner_handle.clone(),
745                inner_content_height,
746            }
747        });
748        cx.run_until_parked();
749        cx.update(|window, cx| {
750            _ = window.draw(cx);
751        });
752        cx
753    }
754
755    #[gpui::test]
756    fn vertical_mask_consumes_wheel_when_scrollable(cx: &mut TestAppContext) {
757        let outer_handle = ScrollHandle::new();
758        let inner_handle = ScrollHandle::new();
759        let cx = setup_nested_vertical_test(cx, &outer_handle, &inner_handle, px(300.));
760
761        cx.simulate_event(ScrollWheelEvent {
762            position: point(px(10.), px(10.)),
763            delta: ScrollDelta::Pixels(point(px(0.), px(-40.))),
764            ..Default::default()
765        });
766
767        // The inner scroller consumes the event; the outer one must not move.
768        assert_eq!(inner_handle.offset().y, px(-40.));
769        assert_eq!(outer_handle.offset().y, px(0.));
770    }
771
772    #[gpui::test]
773    fn vertical_mask_hands_off_to_parent_at_edge(cx: &mut TestAppContext) {
774        let outer_handle = ScrollHandle::new();
775        let inner_handle = ScrollHandle::new();
776        let cx = setup_nested_vertical_test(cx, &outer_handle, &inner_handle, px(300.));
777
778        // Scroll the inner element to its bottom edge (300 - 60 = 240).
779        inner_handle.set_offset(point(px(0.), px(-240.)));
780        cx.update(|window, cx| {
781            _ = window.draw(cx);
782        });
783
784        cx.simulate_event(ScrollWheelEvent {
785            position: point(px(10.), px(10.)),
786            delta: ScrollDelta::Pixels(point(px(0.), px(-40.))),
787            ..Default::default()
788        });
789
790        // At the edge the event bubbles: the outer scroller takes over.
791        assert_eq!(outer_handle.offset().y, px(-40.));
792        // The inner offset is clamped back to the edge on the next prepaint.
793        cx.update(|window, cx| {
794            _ = window.draw(cx);
795        });
796        assert_eq!(inner_handle.offset().y, px(-240.));
797    }
798
799    #[gpui::test]
800    fn vertical_mask_bubbles_when_no_overflow(cx: &mut TestAppContext) {
801        let outer_handle = ScrollHandle::new();
802        let inner_handle = ScrollHandle::new();
803        // Inner content (40) fits its 60px viewport: nothing to scroll.
804        let cx = setup_nested_vertical_test(cx, &outer_handle, &inner_handle, px(40.));
805
806        cx.simulate_event(ScrollWheelEvent {
807            position: point(px(10.), px(10.)),
808            delta: ScrollDelta::Pixels(point(px(0.), px(-40.))),
809            ..Default::default()
810        });
811
812        assert_eq!(outer_handle.offset().y, px(-40.));
813        cx.update(|window, cx| {
814            _ = window.draw(cx);
815        });
816        assert_eq!(inner_handle.offset().y, px(0.));
817    }
818
819    #[gpui::test]
820    fn vertical_mask_ignores_transient_overscroll(cx: &mut TestAppContext) {
821        let outer_handle = ScrollHandle::new();
822        let inner_handle = ScrollHandle::new();
823        let cx = setup_nested_vertical_test(cx, &outer_handle, &inner_handle, px(300.));
824
825        inner_handle.set_offset(point(px(0.), px(-240.)));
826        cx.update(|window, cx| {
827            _ = window.draw(cx);
828        });
829
830        // Two wheel events at the edge with no redraw in between: the first
831        // one leaves the inner offset beyond the edge unclamped, which must
832        // not read as "room to scroll" and swallow the second event.
833        for _ in 0..2 {
834            cx.simulate_event(ScrollWheelEvent {
835                position: point(px(10.), px(10.)),
836                delta: ScrollDelta::Pixels(point(px(0.), px(-40.))),
837                ..Default::default()
838            });
839        }
840
841        assert_eq!(outer_handle.offset().y, px(-80.));
842        cx.update(|window, cx| {
843            _ = window.draw(cx);
844        });
845        assert_eq!(inner_handle.offset().y, px(-240.));
846    }
847
848    /// The vertical mask nested in a `gpui::list` ancestor: the list
849    /// registers its wheel listener after its items paint, so only a
850    /// capture-phase mask can stop it from scrolling on the same event.
851    struct ListWithVerticalAreaTest {
852        scroll_handle: ScrollHandle,
853        list_state: ListState,
854    }
855
856    impl Render for ListWithVerticalAreaTest {
857        fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
858            let scroll_handle = self.scroll_handle.clone();
859            div().w(px(100.)).h(px(100.)).child(
860                list(self.list_state.clone(), move |ix, _, _| {
861                    if ix == 0 {
862                        div()
863                            .relative()
864                            .w_full()
865                            .h(px(60.))
866                            .child(
867                                div()
868                                    .id("inner")
869                                    .size_full()
870                                    .overflow_y_scroll()
871                                    .track_scroll(&scroll_handle)
872                                    .child(div().w_full().h(px(300.))),
873                            )
874                            .child(ScrollableMask::new(Axis::Vertical, &scroll_handle))
875                            .into_any_element()
876                    } else {
877                        div().w(px(100.)).h(px(40.)).into_any_element()
878                    }
879                })
880                .w_full()
881                .h_full(),
882            )
883        }
884    }
885
886    #[gpui::test]
887    fn vertical_mask_in_list_consumes_wheel_when_scrollable(cx: &mut TestAppContext) {
888        let scroll_handle = ScrollHandle::new();
889        let list_state = ListState::new(10, ListAlignment::Top, px(0.));
890        let (_, cx) = cx.add_window_view({
891            let scroll_handle = scroll_handle.clone();
892            let list_state = list_state.clone();
893            move |_, _| ListWithVerticalAreaTest {
894                scroll_handle: scroll_handle.clone(),
895                list_state: list_state.clone(),
896            }
897        });
898        cx.run_until_parked();
899        cx.update(|window, cx| {
900            _ = window.draw(cx);
901        });
902
903        cx.simulate_event(ScrollWheelEvent {
904            position: point(px(10.), px(10.)),
905            delta: ScrollDelta::Pixels(point(px(0.), px(-40.))),
906            ..Default::default()
907        });
908
909        // The inner scroller consumes the event; the list must not scroll.
910        assert_eq!(scroll_handle.offset().y, px(-40.));
911        let scroll_top = list_state.logical_scroll_top();
912        assert_eq!((scroll_top.item_ix, scroll_top.offset_in_item), (0, px(0.)));
913    }
914}